From f8c84ec5888cde091afa94bb21e8a44e1e03ffae Mon Sep 17 00:00:00 2001
From: filipvnencak <vnencak.filip@gmail.com>
Date: Mon, 14 Sep 2026 17:11:35 +0200
Subject: [PATCH 1/3] feat(SF): implement lazy loading for filter option values
 in SearchFilter

---
 src/SearchFilter/SearchFilter.stories.tsx     |  29 +++
 src/SearchFilter/SearchFilter.tsx             | 187 +++++++++++++-----
 .../SearchFilterDropdown.styled.ts            |   5 +
 .../SearchFilterDropdown.tsx                  |  16 +-
 src/SearchFilter/types.ts                     |   1 +
 5 files changed, 186 insertions(+), 52 deletions(-)

diff --git a/src/SearchFilter/SearchFilter.stories.tsx b/src/SearchFilter/SearchFilter.stories.tsx
index 7f43fe5..08f8d6f 100644
--- a/src/SearchFilter/SearchFilter.stories.tsx
+++ b/src/SearchFilter/SearchFilter.stories.tsx
@@ -624,3 +624,32 @@ export const CustomRangeDebug: Story = {
   },
   render: (args) => <SearchFilterCustomRangeDebug {...args} baseOptions={options} />,
 }
+
+const lazyPaletteValues = [
+  { id: 'red', label: 'Red', color: '#F44336', icon: 'circle' },
+  { id: 'green', label: 'Green', color: '#4CAF50', icon: 'circle' },
+  { id: 'blue', label: 'Blue', color: '#2196F3', icon: 'circle' },
+]
+
+export const LazyOptions: Story = {
+  args: {},
+  render: (args) => {
+    const [filters, setFilters] = useState<Filter[]>([])
+
+    const lazyOptions: Option[] = [
+      ...options,
+      {
+        id: 'palette',
+        label: 'Palette (loads on open)',
+        icon: 'palette',
+        operator: 'OR',
+        allowExcludes: true,
+        values: [],
+        loadValues: () =>
+          new Promise((resolve) => setTimeout(() => resolve(lazyPaletteValues), 1500)),
+      },
+    ]
+
+    return <SearchFilter {...args} options={lazyOptions} filters={filters} onChange={setFilters} />
+  },
+}
diff --git a/src/SearchFilter/SearchFilter.tsx b/src/SearchFilter/SearchFilter.tsx
index 208b2d9..a0f1206 100644
--- a/src/SearchFilter/SearchFilter.tsx
+++ b/src/SearchFilter/SearchFilter.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useRef, useState, useImperativeHandle, forwardRef } from 'react'
 
-import { Filter, FilterOperator, Option, SearchFilterGroupOption } from './types'
+import { Filter, FilterOperator, FilterValue, Option, SearchFilterGroupOption } from './types'
 import * as Styled from './SearchFilter.styled'
 import { SearchFilterItem, SearchFilterItemProps } from './SearchFilterItem/SearchFilterItem'
 import SearchFilterDropdown, {
@@ -73,7 +73,7 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
       filters = [],
       onChange,
       onFinish,
-      options = [],
+      options: rawOptions = [],
       groupOptions = [],
       quickActions,
       onQuickAction,
@@ -109,6 +109,28 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
 
     const { enableMultiple: enableGlobalSearchMultiple } = globalSearchConfig || {}
 
+    const [lazyValues, setLazyValues] = useState<Record<string, LazyValuesState>>({})
+    const lazyRequestsRef = useRef(new Set<string>())
+
+    const options = useMemo(() => withLazyValues(rawOptions, lazyValues), [rawOptions, lazyValues])
+
+    const loadOptionValues = (option?: Option) => {
+      if (!option?.loadValues || lazyRequestsRef.current.has(option.id)) return
+      const { id } = option
+      lazyRequestsRef.current.add(id)
+      setLazyValues((current) => ({ ...current, [id]: { status: 'loading', values: [] } }))
+      option
+        .loadValues()
+        .then((values) =>
+          setLazyValues((current) => ({ ...current, [id]: { status: 'loaded', values } })),
+        )
+        .catch(() => {
+          // a failed load is retried the next time the filter opens
+          lazyRequestsRef.current.delete(id)
+          setLazyValues((current) => ({ ...current, [id]: { status: 'error', values: [] } }))
+        })
+    }
+
     const [dropdownParentId, setDropdownParentId] = useState<null | string>(null)
     const [dropdownOptions, setOptions] = useState<Option[] | null>(null)
     const [search, setSearch] = useState('')
@@ -327,20 +349,12 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
       // boolean options without explicit values are one-click toggles: add
       // immediately with an "on" value and close, instead of opening a values panel
       if (!parentId && option.type === 'boolean' && !option.values?.length) {
-        const {
-          group: _group,
-          search: _search,
-          tooltip: _tooltip,
-          ...filterOptionData
-        } = filterOption
-        const addFilter: Filter = {
-          ...filterOptionData,
+        const addFilter = createFilterState(filterOption, {
           id: newId,
           // value label = filter name so the compact chip (label hidden) reads the
           // filter name instead of "Yes"
           values: [{ id: 'true', label: option.label }],
-        }
-        delete (addFilter as Option).allowsCustomValues
+        })
         const updatedFilters = [...filters, addFilter]
         onChange(updatedFilters)
         handleClose(updatedFilters)
@@ -356,11 +370,10 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
         if (option.searchOnly) {
           const parentOption = findOption(options, option.parentId)
           if (parentOption) {
-            parentFilter = {
-              ...parentOption,
+            parentFilter = createFilterState(parentOption, {
               id: buildFilterId(option.parentId || ''),
               values: [],
-            }
+            })
           }
         } else {
           parentFilter = filters.find((filter) => filter.id === parentId)
@@ -433,26 +446,22 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
           }
         }
       } else {
-        const {
-          group: _group,
-          search: _search,
-          tooltip: _tooltip,
-          ...filterOptionData
-        } = filterOption
-        const addFilter = { ...filterOptionData, id: newId, values: [] }
-        // remove not required fields
-        delete addFilter.allowsCustomValues
+        const addFilter = createFilterState(filterOption, { id: newId, values: [] })
 
         // add to filters top level
         onChange([...filters, addFilter])
       }
 
       // if there are values set the next dropdownOptions
-      // or the option allows custom values (text)
-      if (!parentId && ((values && values.length > 0) || option.allowsCustomValues)) {
+      // or the option allows custom values (text), or it loads its values lazily
+      if (
+        !parentId &&
+        ((values && values.length > 0) || option.allowsCustomValues || option.loadValues)
+      ) {
         const newOptions = values?.map((value) => ({ ...value, parentId: newId })) || []
 
         openOptions(newOptions, newId)
+        loadOptionValues(filterOption)
         // enter inline chip editing mode so the chip's search input drives the value selection
         setEditingSearchChipId(newId)
         setIsEditingExisting(false)
@@ -507,29 +516,57 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
       onFinish && onFinish(updatedFilters)
     }
 
+    const getEditValueOptions = (id: string, filter?: Filter): Option[] => {
+      if (!filter?.values?.length) return options
+
+      // Merge options with filter values to include custom values
+      const newOptions = mergeOptionsWithFilterValues(filter, options).map((value) => ({
+        ...value,
+        parentId: id,
+        isSelected: getIsValueSelected(value.id, id, filters),
+      }))
+
+      const filterName = getFilterFromId(id)
+      if (sortSelectedToTopFields.includes(filterName)) {
+        // sort selected to top
+        newOptions.sort((a, b) => {
+          if (a.isSelected && !b.isSelected) return -1
+          if (!a.isSelected && b.isSelected) return 1
+          return 0
+        })
+      }
+      return newOptions
+    }
+
     const handleEditFilterValues = (id: string, filter?: Filter) => {
-      if (filter && filter.values && filter.values.length > 0) {
-        // Merge options with filter values to include custom values
-        const newOptions = mergeOptionsWithFilterValues(filter, options).map((value) => ({
-          ...value,
-          parentId: id,
-          isSelected: getIsValueSelected(value.id, id, filters),
-        }))
-
-        const filterName = getFilterFromId(id)
-        if (sortSelectedToTopFields.includes(filterName)) {
-          // sort selected to top
-          newOptions.sort((a, b) => {
-            if (a.isSelected && !b.isSelected) return -1
-            if (!a.isSelected && b.isSelected) return 1
-            return 0
-          })
-        }
-        openOptions(newOptions, id)
+      openOptions(getEditValueOptions(id, filter), id)
+      const option = findOption(options, getFilterFromId(id))
+      loadOptionValues(option)
+    }
+
+    // Values loaded after the panel opened (see Option.loadValues) replace the snapshot taken on open
+    const parentValues = parentOption?.values
+    const parentValuesRef = useRef(parentValues)
+    useEffect(() => {
+      if (parentValuesRef.current === parentValues) return
+      parentValuesRef.current = parentValues
+      if (!dropdownOptions || !dropdownParentId || !parentOption || isGroupMenu) return
+
+      if (isEditingExisting) {
+        const filter = filters.find((candidate) => candidate.id === dropdownParentId)
+        setOptions(getEditValueOptions(dropdownParentId, filter))
       } else {
-        openOptions(options, id)
+        setOptions(parentValues?.map((value) => ({ ...value, parentId: dropdownParentId })) || [])
       }
-    }
+    }, [parentValues])
+
+    // Active filters need their values too, so chips show labels instead of raw ids
+    const activeFilterNames = filters.map((filter) => getFilterFromId(filter.id)).join(',')
+    useEffect(() => {
+      filters.forEach((filter) =>
+        loadOptionValues(rawOptions.find((option) => option.id === getFilterFromId(filter.id))),
+      )
+    }, [activeFilterNames])
 
     const handleRemoveFilter = (id: string) => {
       // remove a filter by id
@@ -857,11 +894,10 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
 
         if (!selectedValues.length) return
 
-        const updatedFilter = {
-          ...(existing || option),
+        const updatedFilter = createFilterState(existing || option, {
           id: existing?.id || buildFilterId(optionId),
           values: selectedValues,
-        }
+        })
         const updatedFilters = existing
           ? filters.map((filter) => (filter.id === existing.id ? updatedFilter : filter))
           : [...filters, updatedFilter]
@@ -948,7 +984,7 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
                       label={filter.label}
                       inverted={filter.inverted}
                       operator={filter.operator}
-                      values={filter.values}
+                      values={getDisplayValues(filter, option)}
                       icon={filter.icon}
                       isCustom={filter.isCustom}
                       index={index}
@@ -1051,6 +1087,7 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
             isCustomAllowed={
               !!parentOption?.allowsCustomValues || (!parentOption && !!enableGlobalSearch)
             }
+            valuesStatus={parentOption ? lazyValues[parentOption.id]?.status : undefined}
             isHasValueAllowed={!!parentOption?.allowHasValue}
             isNoValueAllowed={!!parentOption?.allowNoValue}
             isInvertedAllowed={!!parentOption?.allowExcludes}
@@ -1201,3 +1238,53 @@ const mergeOptionsWithFilterValues = (filter: Filter, options: Option[]): Option
 
   return mergedOptions
 }
+
+type LazyValuesState = {
+  status: 'loading' | 'loaded' | 'error'
+  values: FilterValue[]
+}
+
+const withLazyValues = (options: Option[], lazyValues: Record<string, LazyValuesState>) => {
+  if (!Object.keys(lazyValues).length) return options
+  return options.map((option) => {
+    const loaded = lazyValues[option.id]
+    if (loaded?.status !== 'loaded') return option
+    const existing = option.values || []
+    const extra = existing.filter((value) => !loaded.values.some((l) => l.id === value.id))
+    return { ...option, values: [...loaded.values, ...extra] }
+  })
+}
+
+// Chips built before lazy values arrived carry the raw id as label
+const getDisplayValues = (filter: Filter, option?: Option): FilterValue[] | undefined => {
+  if (!option?.loadValues || !filter.values) return filter.values
+  return filter.values.map((value) => {
+    if (value.label !== value.id) return value
+    const loaded = option.values?.find((candidate) => candidate.id === value.id)
+    if (!loaded) return value
+    return {
+      ...value,
+      label: loaded.label,
+      icon: value.icon ?? loaded.icon,
+      img: value.img ?? loaded.img,
+      color: value.color ?? loaded.color,
+    }
+  })
+}
+
+// Only filter fields are kept: option-only data (loadValues, loaded values, React content) must not leak into filters
+const createFilterState = (option: Option | Filter, overrides: Partial<Filter> = {}): Filter => ({
+  id: option.id,
+  label: option.label,
+  type: option.type,
+  inverted: option.inverted,
+  operator: option.operator,
+  icon: option.icon,
+  img: option.img,
+  values: option.values,
+  isCustom: option.isCustom,
+  isReadonly: option.isReadonly,
+  singleSelect: option.singleSelect,
+  fieldType: option.fieldType,
+  ...overrides,
+})
diff --git a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts
index 223a425..1fa300b 100644
--- a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts
+++ b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts
@@ -66,6 +66,11 @@ export const OptionsList = styled.ul`
   }
 `
 
+export const Loading = styled.span`
+  padding: 6px 8px;
+  color: var(--md-sys-color-outline);
+`
+
 export const Item = styled.li`
   margin: 0;
   list-style: none;
diff --git a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
index c20cea1..3999e3d 100644
--- a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
+++ b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
@@ -35,6 +35,7 @@ export interface SearchFilterDropdownProps {
   searchInputRef?: React.RefObject<HTMLInputElement>
   listRef?: React.RefObject<HTMLUListElement>
   isCustomAllowed: boolean
+  valuesStatus?: 'loading' | 'loaded' | 'error' // state of the parent filter's lazily loaded values
   isHasValueAllowed?: boolean
   isNoValueAllowed?: boolean
   isInvertedAllowed?: boolean
@@ -70,6 +71,7 @@ const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDro
       searchInputRef,
       listRef,
       isCustomAllowed,
+      valuesStatus,
       isHasValueAllowed,
       isNoValueAllowed,
       isInvertedAllowed,
@@ -373,6 +375,7 @@ const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDro
                   groupItems,
                   values: optionValues,
                   allowsCustomValues,
+                  loadValues,
                   label,
                   searchLabel,
                   icon,
@@ -407,7 +410,10 @@ const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDro
                   : undefined
                 const opensSubmenu =
                   !parentId &&
-                  (Boolean(groupItems) || Boolean(optionValues?.length) || !!allowsCustomValues)
+                  (Boolean(groupItems) ||
+                    Boolean(optionValues?.length) ||
+                    !!allowsCustomValues ||
+                    !!loadValues)
                 return (
                   <Fragment key={id + '-' + parentId}>
                     {hasLevelDivider && <Styled.Divider aria-hidden="true" />}
@@ -449,7 +455,13 @@ const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDro
                 )
               },
             )}
-            {filteredOptions.length === 0 && !isCustomAllowed && <span>No filters found</span>}
+            {valuesStatus === 'loading' && <Styled.Loading>Loading...</Styled.Loading>}
+            {valuesStatus === 'error' && <Styled.Loading>Could not load values</Styled.Loading>}
+            {filteredOptions.length === 0 &&
+              !isCustomAllowed &&
+              (!valuesStatus || valuesStatus === 'loaded') && (
+              <span>No filters found</span>
+            )}
             {parentId && !!parentFilter?.values?.length && (
               <Styled.Toolbar className="toolbar">
                 <Spacer />
diff --git a/src/SearchFilter/types.ts b/src/SearchFilter/types.ts
index 1e87e91..3abe361 100644
--- a/src/SearchFilter/types.ts
+++ b/src/SearchFilter/types.ts
@@ -65,6 +65,7 @@ export interface Option extends Filter {
   allowNoValue?: boolean // allows the filter to have "no value"
   allowHasValue?: boolean // allows the filter to have "has a value"
   allowsCustomValues?: boolean // allows the filter to have custom values
+  loadValues?: () => Promise<FilterValue[]> // fetched on first open (and for active filters), merged into values
   allowExcludes?: boolean // allows the filter to be inverted
   operatorChangeable?: boolean // allows the operator to be changed
   color?: string | null // color of the filter (not used for root options)

From 77275fb4e689eb4244a682a4a02d8351a24138b5 Mon Sep 17 00:00:00 2001
From: filipvnencak <vnencak.filip@gmail.com>
Date: Tue, 15 Sep 2026 10:41:35 +0200
Subject: [PATCH 2/3] feat(SF): enhance lazy loading with error handling and
 loading states in SearchFilter

---
 src/SearchFilter/SearchFilter.stories.tsx     |  12 ++
 src/SearchFilter/SearchFilter.tsx             | 193 ++++++++++++------
 .../SearchFilterDropdown.styled.ts            |  33 ++-
 .../SearchFilterDropdown.tsx                  |  23 ++-
 4 files changed, 193 insertions(+), 68 deletions(-)

diff --git a/src/SearchFilter/SearchFilter.stories.tsx b/src/SearchFilter/SearchFilter.stories.tsx
index 08f8d6f..1b4b115 100644
--- a/src/SearchFilter/SearchFilter.stories.tsx
+++ b/src/SearchFilter/SearchFilter.stories.tsx
@@ -644,10 +644,22 @@ export const LazyOptions: Story = {
         icon: 'palette',
         operator: 'OR',
         allowExcludes: true,
+        allowHasValue: true,
+        allowNoValue: true,
         values: [],
         loadValues: () =>
           new Promise((resolve) => setTimeout(() => resolve(lazyPaletteValues), 1500)),
       },
+      {
+        id: 'broken',
+        label: 'Broken (fails to load)',
+        icon: 'error',
+        values: [],
+        loadValues: () =>
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Enum resolver timed out')), 1500),
+          ),
+      },
     ]
 
     return <SearchFilter {...args} options={lazyOptions} filters={filters} onChange={setFilters} />
diff --git a/src/SearchFilter/SearchFilter.tsx b/src/SearchFilter/SearchFilter.tsx
index a0f1206..246667d 100644
--- a/src/SearchFilter/SearchFilter.tsx
+++ b/src/SearchFilter/SearchFilter.tsx
@@ -110,29 +110,51 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
     const { enableMultiple: enableGlobalSearchMultiple } = globalSearchConfig || {}
 
     const [lazyValues, setLazyValues] = useState<Record<string, LazyValuesState>>({})
-    const lazyRequestsRef = useRef(new Set<string>())
 
     const options = useMemo(() => withLazyValues(rawOptions, lazyValues), [rawOptions, lazyValues])
 
+    // Caching is left to the consumer (e.g. RTK Query), so every call hits loadValues.
+    // Previously loaded values stay visible while reloading.
     const loadOptionValues = (option?: Option) => {
-      if (!option?.loadValues || lazyRequestsRef.current.has(option.id)) return
-      const { id } = option
-      lazyRequestsRef.current.add(id)
-      setLazyValues((current) => ({ ...current, [id]: { status: 'loading', values: [] } }))
-      option
-        .loadValues()
+      if (!option?.loadValues) return
+      const { id, loadValues } = option
+      // only the latest load of an option may write its result (e.g. after a project switch)
+      const request = {}
+      const isLatest = (current: Record<string, LazyValuesState>) =>
+        current[id]?.request === request
+
+      setLazyValues((current) => ({
+        ...current,
+        [id]: { status: 'loading', values: current[id]?.values || [], request },
+      }))
+      // started inside the chain so a synchronous throw also ends in the error state
+      Promise.resolve()
+        .then(loadValues)
         .then((values) =>
-          setLazyValues((current) => ({ ...current, [id]: { status: 'loaded', values } })),
+          setLazyValues((current) =>
+            isLatest(current) ? { ...current, [id]: { status: 'loaded', values, request } } : current,
+          ),
+        )
+        .catch((error: unknown) =>
+          setLazyValues((current) =>
+            isLatest(current)
+              ? {
+                  ...current,
+                  [id]: {
+                    status: 'error',
+                    values: current[id]?.values || [],
+                    error: getLoadErrorMessage(error),
+                    request,
+                  },
+                }
+              : current,
+          ),
         )
-        .catch(() => {
-          // a failed load is retried the next time the filter opens
-          lazyRequestsRef.current.delete(id)
-          setLazyValues((current) => ({ ...current, [id]: { status: 'error', values: [] } }))
-        })
     }
 
     const [dropdownParentId, setDropdownParentId] = useState<null | string>(null)
-    const [dropdownOptions, setOptions] = useState<Option[] | null>(null)
+    // options snapshot taken when a menu/panel opens (see dropdownOptions below)
+    const [openedOptions, setOptions] = useState<Option[] | null>(null)
     const [search, setSearch] = useState('')
     // in-place editing of a search chip (typing directly in the chip)
     const [editingSearchChipId, setEditingSearchChipId] = useState<string | null>(null)
@@ -166,6 +188,18 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
       ? [parentMenuOption.label]
       : []
 
+    // Lazy values can arrive after a value panel opened, so they are merged into the snapshot at render
+    const loadedParentValues = dropdownParentId
+      ? lazyValues[getFilterFromId(dropdownParentId)]?.values
+      : undefined
+    const dropdownOptions = useMemo(
+      () =>
+        openedOptions && dropdownParentId && loadedParentValues?.length
+          ? mergeLoadedValues(openedOptions, loadedParentValues, dropdownParentId)
+          : openedOptions,
+      [openedOptions, dropdownParentId, loadedParentValues],
+    )
+
     const allOptions = useMemo(() => {
       if (!dropdownOptions) return null
 
@@ -348,7 +382,12 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
 
       // boolean options without explicit values are one-click toggles: add
       // immediately with an "on" value and close, instead of opening a values panel
-      if (!parentId && option.type === 'boolean' && !option.values?.length) {
+      if (
+        !parentId &&
+        option.type === 'boolean' &&
+        !option.values?.length &&
+        !option.loadValues
+      ) {
         const addFilter = createFilterState(filterOption, {
           id: newId,
           // value label = filter name so the compact chip (label hidden) reads the
@@ -516,57 +555,40 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
       onFinish && onFinish(updatedFilters)
     }
 
-    const getEditValueOptions = (id: string, filter?: Filter): Option[] => {
-      if (!filter?.values?.length) return options
-
-      // Merge options with filter values to include custom values
-      const newOptions = mergeOptionsWithFilterValues(filter, options).map((value) => ({
-        ...value,
-        parentId: id,
-        isSelected: getIsValueSelected(value.id, id, filters),
-      }))
-
-      const filterName = getFilterFromId(id)
-      if (sortSelectedToTopFields.includes(filterName)) {
-        // sort selected to top
-        newOptions.sort((a, b) => {
-          if (a.isSelected && !b.isSelected) return -1
-          if (!a.isSelected && b.isSelected) return 1
-          return 0
-        })
-      }
-      return newOptions
-    }
-
     const handleEditFilterValues = (id: string, filter?: Filter) => {
-      openOptions(getEditValueOptions(id, filter), id)
-      const option = findOption(options, getFilterFromId(id))
-      loadOptionValues(option)
-    }
-
-    // Values loaded after the panel opened (see Option.loadValues) replace the snapshot taken on open
-    const parentValues = parentOption?.values
-    const parentValuesRef = useRef(parentValues)
-    useEffect(() => {
-      if (parentValuesRef.current === parentValues) return
-      parentValuesRef.current = parentValues
-      if (!dropdownOptions || !dropdownParentId || !parentOption || isGroupMenu) return
-
-      if (isEditingExisting) {
-        const filter = filters.find((candidate) => candidate.id === dropdownParentId)
-        setOptions(getEditValueOptions(dropdownParentId, filter))
+      if (filter && filter.values && filter.values.length > 0) {
+        // Merge options with filter values to include custom values
+        const newOptions = mergeOptionsWithFilterValues(filter, options).map((value) => ({
+          ...value,
+          parentId: id,
+          isSelected: getIsValueSelected(value.id, id, filters),
+        }))
+
+        const filterName = getFilterFromId(id)
+        if (sortSelectedToTopFields.includes(filterName)) {
+          // sort selected to top
+          newOptions.sort((a, b) => {
+            if (a.isSelected && !b.isSelected) return -1
+            if (!a.isSelected && b.isSelected) return 1
+            return 0
+          })
+        }
+        openOptions(newOptions, id)
       } else {
-        setOptions(parentValues?.map((value) => ({ ...value, parentId: dropdownParentId })) || [])
+        openOptions(options, id)
       }
-    }, [parentValues])
+      loadOptionValues(findOption(options, getFilterFromId(id)))
+    }
 
-    // Active filters need their values too, so chips show labels instead of raw ids
-    const activeFilterNames = filters.map((filter) => getFilterFromId(filter.id)).join(',')
+    // Chips restored with raw ids (e.g. from a URL) need their option's values to show labels.
+    // Options that already have a load entry are skipped; opening the panel reloads them.
     useEffect(() => {
-      filters.forEach((filter) =>
-        loadOptionValues(rawOptions.find((option) => option.id === getFilterFromId(filter.id))),
-      )
-    }, [activeFilterNames])
+      filters.forEach((filter) => {
+        const option = rawOptions.find((candidate) => candidate.id === getFilterFromId(filter.id))
+        if (!option?.loadValues || lazyValues[option.id]) return
+        if (filter.values?.some((value) => value.label === value.id)) loadOptionValues(option)
+      })
+    }, [filters, rawOptions, lazyValues])
 
     const handleRemoveFilter = (id: string) => {
       // remove a filter by id
@@ -627,7 +649,9 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
 
     // Get the rendered <li> elements from the dropdown list.
     const getDropdownItems = (): HTMLElement[] =>
-      dropdownRef.current ? Array.from(dropdownRef.current.querySelectorAll('li')) : []
+      dropdownRef.current
+        ? Array.from(dropdownRef.current.querySelectorAll('li:not(.status)'))
+        : []
 
     // Scroll the highlighted item into view if it is not visible.
     useEffect(() => {
@@ -972,7 +996,8 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
                   const tooltipLabel =
                     option?.tooltip ||
                     (option?.group ? getGroupFieldLabel(option.label) : filter.label)
-                  const tooltipValues = filter.values?.map((value) => value.label).join(', ')
+                  const displayValues = getDisplayValues(filter, option)
+                  const tooltipValues = displayValues?.map((value) => value.label).join(', ')
                   const tooltip = `${filter.inverted ? 'not ' : ''}${tooltipLabel}${
                     tooltipValues ? `: ${tooltipValues}` : ''
                   }`
@@ -984,7 +1009,7 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
                       label={filter.label}
                       inverted={filter.inverted}
                       operator={filter.operator}
-                      values={getDisplayValues(filter, option)}
+                      values={displayValues}
                       icon={filter.icon}
                       isCustom={filter.isCustom}
                       index={index}
@@ -1088,6 +1113,7 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
               !!parentOption?.allowsCustomValues || (!parentOption && !!enableGlobalSearch)
             }
             valuesStatus={parentOption ? lazyValues[parentOption.id]?.status : undefined}
+            valuesError={parentOption ? lazyValues[parentOption.id]?.error : undefined}
             isHasValueAllowed={!!parentOption?.allowHasValue}
             isNoValueAllowed={!!parentOption?.allowNoValue}
             isInvertedAllowed={!!parentOption?.allowExcludes}
@@ -1242,19 +1268,56 @@ const mergeOptionsWithFilterValues = (filter: Filter, options: Option[]): Option
 type LazyValuesState = {
   status: 'loading' | 'loaded' | 'error'
   values: FilterValue[]
+  error?: string
+  request: object // identity of the load that owns this entry
+}
+
+// Loaders may reject with anything: an Error, a string or an API error payload
+const getLoadErrorMessage = (error: unknown): string | undefined => {
+  if (typeof error === 'string') return error
+  if (error instanceof Error) return error.message
+  if (!error || typeof error !== 'object') return undefined
+  const { message, error: nested, data } = error as {
+    message?: unknown
+    error?: unknown
+    data?: { detail?: unknown; message?: unknown }
+  }
+  const candidate = [message, data?.detail, data?.message, nested].find(
+    (value) => typeof value === 'string' && value,
+  )
+  return candidate as string | undefined
 }
 
 const withLazyValues = (options: Option[], lazyValues: Record<string, LazyValuesState>) => {
   if (!Object.keys(lazyValues).length) return options
   return options.map((option) => {
     const loaded = lazyValues[option.id]
-    if (loaded?.status !== 'loaded') return option
+    if (!loaded?.values.length) return option
     const existing = option.values || []
     const extra = existing.filter((value) => !loaded.values.some((l) => l.id === value.id))
     return { ...option, values: [...loaded.values, ...extra] }
   })
 }
 
+// Updates the opened panel snapshot with loaded values: matching items are refreshed in place
+// (order stays stable), new values are appended, custom values in the snapshot are kept
+const mergeLoadedValues = (
+  openedOptions: Option[],
+  loadedValues: FilterValue[],
+  parentId: string,
+): Option[] => {
+  const loadedById = new Map(loadedValues.map((value) => [value.id, value]))
+  const openedIds = new Set(openedOptions.map((option) => option.id))
+  const refreshed = openedOptions.map((option) => {
+    const loaded = loadedById.get(option.id)
+    return loaded ? { ...option, ...loaded, parentId } : option
+  })
+  const added = loadedValues
+    .filter((value) => !openedIds.has(value.id))
+    .map((value) => ({ ...value, parentId }))
+  return [...refreshed, ...added]
+}
+
 // Chips built before lazy values arrived carry the raw id as label
 const getDisplayValues = (filter: Filter, option?: Option): FilterValue[] | undefined => {
   if (!option?.loadValues || !filter.values) return filter.values
diff --git a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts
index 1fa300b..58fdeb5 100644
--- a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts
+++ b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.styled.ts
@@ -1,6 +1,7 @@
 import styled from 'styled-components'
 import { Icon } from '../../Icon'
 import { Button } from '../../Buttons/Button'
+import { getShimmerStyles } from '../../helpers'
 
 export const OptionsContainer = styled.div`
   position: absolute;
@@ -66,9 +67,39 @@ export const OptionsList = styled.ul`
   }
 `
 
-export const Loading = styled.span`
+// non-interactive rows (loading / error), excluded from keyboard navigation via .status
+export const StatusItem = styled.li`
+  margin: 0;
+  list-style: none;
   padding: 6px 8px;
   color: var(--md-sys-color-outline);
+
+  &.error {
+    color: var(--md-sys-color-error);
+  }
+
+  &.visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+  }
+`
+
+export const PlaceholderItem = styled.li`
+  position: relative;
+  overflow: hidden;
+  margin: 0;
+  list-style: none;
+  height: 32px;
+  flex-shrink: 0;
+  border-radius: var(--border-radius-m);
+  background-color: var(--md-sys-color-surface-container);
+
+  ${getShimmerStyles()}
 `
 
 export const Item = styled.li`
diff --git a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
index 3999e3d..14619e6 100644
--- a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
+++ b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
@@ -36,6 +36,7 @@ export interface SearchFilterDropdownProps {
   listRef?: React.RefObject<HTMLUListElement>
   isCustomAllowed: boolean
   valuesStatus?: 'loading' | 'loaded' | 'error' // state of the parent filter's lazily loaded values
+  valuesError?: string // error message when lazily loading values failed
   isHasValueAllowed?: boolean
   isNoValueAllowed?: boolean
   isInvertedAllowed?: boolean
@@ -59,6 +60,9 @@ export interface SearchFilterDropdownProps {
   }
 }
 
+// has/no value rows are always present, so they do not count as loaded values
+const isValueOption = (option: Option) => option.id !== 'hasValue' && option.id !== 'noValue'
+
 const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDropdownProps>(
   (
     {
@@ -72,6 +76,7 @@ const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDro
       listRef,
       isCustomAllowed,
       valuesStatus,
+      valuesError,
       isHasValueAllowed,
       isNoValueAllowed,
       isInvertedAllowed,
@@ -455,8 +460,22 @@ const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDro
                 )
               },
             )}
-            {valuesStatus === 'loading' && <Styled.Loading>Loading...</Styled.Loading>}
-            {valuesStatus === 'error' && <Styled.Loading>Could not load values</Styled.Loading>}
+            {/* placeholders only on first load; a reload keeps showing the previous values */}
+            {valuesStatus === 'loading' && !filteredOptions.some(isValueOption) && (
+              <>
+                <Styled.StatusItem className="status visually-hidden" role="status">
+                  Loading values
+                </Styled.StatusItem>
+                {[0, 1, 2].map((index) => (
+                  <Styled.PlaceholderItem key={index} className="status" aria-hidden="true" />
+                ))}
+              </>
+            )}
+            {valuesStatus === 'error' && (
+              <Styled.StatusItem className="status error" role="alert">
+                Could not load values{valuesError ? `: ${valuesError}` : ''}
+              </Styled.StatusItem>
+            )}
             {filteredOptions.length === 0 &&
               !isCustomAllowed &&
               (!valuesStatus || valuesStatus === 'loaded') && (

From 41e862d64fd78f0120ed32cbfbc2250baf8f255e Mon Sep 17 00:00:00 2001
From: filipvnencak <vnencak.filip@gmail.com>
Date: Tue, 15 Sep 2026 11:06:34 +0200
Subject: [PATCH 3/3] feat(SF): implement lazy loading support with error
 handling and value merging in SearchFilter

---
 src/SearchFilter/SearchFilter.tsx             | 113 +++++-------------
 .../SearchFilterDropdown.tsx                  |   6 +-
 .../SearchFilterItem/SearchFilterItem.tsx     |   1 -
 src/SearchFilter/lazyValues.ts                |  69 +++++++++++
 src/SearchFilter/types.ts                     |   3 +-
 5 files changed, 105 insertions(+), 87 deletions(-)
 create mode 100644 src/SearchFilter/lazyValues.ts

diff --git a/src/SearchFilter/SearchFilter.tsx b/src/SearchFilter/SearchFilter.tsx
index 246667d..027c1bc 100644
--- a/src/SearchFilter/SearchFilter.tsx
+++ b/src/SearchFilter/SearchFilter.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useRef, useState, useImperativeHandle, forwardRef } from 'react'
 
-import { Filter, FilterOperator, FilterValue, Option, SearchFilterGroupOption } from './types'
+import { Filter, FilterOperator, Option, SearchFilterGroupOption } from './types'
 import * as Styled from './SearchFilter.styled'
 import { SearchFilterItem, SearchFilterItemProps } from './SearchFilterItem/SearchFilterItem'
 import SearchFilterDropdown, {
@@ -16,6 +16,14 @@ import doesFilterExist from './doesFilterExist'
 import { Icon, IconType } from '../Icon'
 import clsx from 'clsx'
 import { SEARCH_FILTER_ID } from './constants'
+import {
+  LazyValuesState,
+  getCurrentValues,
+  getDisplayValues,
+  getLoadErrorMessage,
+  mergeLoadedValues,
+  withLazyValues,
+} from './lazyValues'
 
 const sortSelectedToTopFields = ['assignee', 'taskType']
 
@@ -114,10 +122,10 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
     const options = useMemo(() => withLazyValues(rawOptions, lazyValues), [rawOptions, lazyValues])
 
     // Caching is left to the consumer (e.g. RTK Query), so every call hits loadValues.
-    // Previously loaded values stay visible while reloading.
+    // Previously loaded values stay visible while reloading, unless loadValuesKey changed.
     const loadOptionValues = (option?: Option) => {
       if (!option?.loadValues) return
-      const { id, loadValues } = option
+      const { id, loadValues, loadValuesKey: key } = option
       // only the latest load of an option may write its result (e.g. after a project switch)
       const request = {}
       const isLatest = (current: Record<string, LazyValuesState>) =>
@@ -125,14 +133,16 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
 
       setLazyValues((current) => ({
         ...current,
-        [id]: { status: 'loading', values: current[id]?.values || [], request },
+        [id]: { status: 'loading', values: getCurrentValues(current[id], key), key, request },
       }))
       // started inside the chain so a synchronous throw also ends in the error state
       Promise.resolve()
         .then(loadValues)
         .then((values) =>
           setLazyValues((current) =>
-            isLatest(current) ? { ...current, [id]: { status: 'loaded', values, request } } : current,
+            isLatest(current)
+              ? { ...current, [id]: { status: 'loaded', values, key, request } }
+              : current,
           ),
         )
         .catch((error: unknown) =>
@@ -144,6 +154,7 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
                     status: 'error',
                     values: current[id]?.values || [],
                     error: getLoadErrorMessage(error),
+                    key,
                     request,
                   },
                 }
@@ -189,12 +200,13 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
       : []
 
     // Lazy values can arrive after a value panel opened, so they are merged into the snapshot at render
-    const loadedParentValues = dropdownParentId
-      ? lazyValues[getFilterFromId(dropdownParentId)]?.values
-      : undefined
+    const loadedParentValues = getCurrentValues(
+      dropdownParentId ? lazyValues[getFilterFromId(dropdownParentId)] : undefined,
+      parentOption?.loadValuesKey,
+    )
     const dropdownOptions = useMemo(
       () =>
-        openedOptions && dropdownParentId && loadedParentValues?.length
+        openedOptions && dropdownParentId && loadedParentValues.length
           ? mergeLoadedValues(openedOptions, loadedParentValues, dropdownParentId)
           : openedOptions,
       [openedOptions, dropdownParentId, loadedParentValues],
@@ -581,13 +593,20 @@ export const SearchFilter = forwardRef<SearchFilterRef, SearchFilterProps>(
     }
 
     // Chips restored with raw ids (e.g. from a URL) need their option's values to show labels.
-    // Options that already have a load entry are skipped; opening the panel reloads them.
+    // Options with a load entry for the current loadValuesKey are skipped; opening the panel reloads them.
     useEffect(() => {
+      // collected first so an option shared by several chips loads once per pass
+      const optionsToLoad = new Map<string, Option>()
       filters.forEach((filter) => {
         const option = rawOptions.find((candidate) => candidate.id === getFilterFromId(filter.id))
-        if (!option?.loadValues || lazyValues[option.id]) return
-        if (filter.values?.some((value) => value.label === value.id)) loadOptionValues(option)
+        if (!option?.loadValues || optionsToLoad.has(option.id)) return
+        const entry = lazyValues[option.id]
+        if (entry && entry.key === option.loadValuesKey) return
+        if (filter.values?.some((value) => value.label === value.id)) {
+          optionsToLoad.set(option.id, option)
+        }
       })
+      optionsToLoad.forEach((option) => loadOptionValues(option))
     }, [filters, rawOptions, lazyValues])
 
     const handleRemoveFilter = (id: string) => {
@@ -1265,76 +1284,6 @@ const mergeOptionsWithFilterValues = (filter: Filter, options: Option[]): Option
   return mergedOptions
 }
 
-type LazyValuesState = {
-  status: 'loading' | 'loaded' | 'error'
-  values: FilterValue[]
-  error?: string
-  request: object // identity of the load that owns this entry
-}
-
-// Loaders may reject with anything: an Error, a string or an API error payload
-const getLoadErrorMessage = (error: unknown): string | undefined => {
-  if (typeof error === 'string') return error
-  if (error instanceof Error) return error.message
-  if (!error || typeof error !== 'object') return undefined
-  const { message, error: nested, data } = error as {
-    message?: unknown
-    error?: unknown
-    data?: { detail?: unknown; message?: unknown }
-  }
-  const candidate = [message, data?.detail, data?.message, nested].find(
-    (value) => typeof value === 'string' && value,
-  )
-  return candidate as string | undefined
-}
-
-const withLazyValues = (options: Option[], lazyValues: Record<string, LazyValuesState>) => {
-  if (!Object.keys(lazyValues).length) return options
-  return options.map((option) => {
-    const loaded = lazyValues[option.id]
-    if (!loaded?.values.length) return option
-    const existing = option.values || []
-    const extra = existing.filter((value) => !loaded.values.some((l) => l.id === value.id))
-    return { ...option, values: [...loaded.values, ...extra] }
-  })
-}
-
-// Updates the opened panel snapshot with loaded values: matching items are refreshed in place
-// (order stays stable), new values are appended, custom values in the snapshot are kept
-const mergeLoadedValues = (
-  openedOptions: Option[],
-  loadedValues: FilterValue[],
-  parentId: string,
-): Option[] => {
-  const loadedById = new Map(loadedValues.map((value) => [value.id, value]))
-  const openedIds = new Set(openedOptions.map((option) => option.id))
-  const refreshed = openedOptions.map((option) => {
-    const loaded = loadedById.get(option.id)
-    return loaded ? { ...option, ...loaded, parentId } : option
-  })
-  const added = loadedValues
-    .filter((value) => !openedIds.has(value.id))
-    .map((value) => ({ ...value, parentId }))
-  return [...refreshed, ...added]
-}
-
-// Chips built before lazy values arrived carry the raw id as label
-const getDisplayValues = (filter: Filter, option?: Option): FilterValue[] | undefined => {
-  if (!option?.loadValues || !filter.values) return filter.values
-  return filter.values.map((value) => {
-    if (value.label !== value.id) return value
-    const loaded = option.values?.find((candidate) => candidate.id === value.id)
-    if (!loaded) return value
-    return {
-      ...value,
-      label: loaded.label,
-      icon: value.icon ?? loaded.icon,
-      img: value.img ?? loaded.img,
-      color: value.color ?? loaded.color,
-    }
-  })
-}
-
 // Only filter fields are kept: option-only data (loadValues, loaded values, React content) must not leak into filters
 const createFilterState = (option: Option | Filter, overrides: Partial<Filter> = {}): Filter => ({
   id: option.id,
diff --git a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
index 14619e6..f29e93e 100644
--- a/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
+++ b/src/SearchFilter/SearchFilterDropdown/SearchFilterDropdown.tsx
@@ -60,8 +60,8 @@ export interface SearchFilterDropdownProps {
   }
 }
 
-// has/no value rows are always present, so they do not count as loaded values
-const isValueOption = (option: Option) => option.id !== 'hasValue' && option.id !== 'noValue'
+// has/no value rows and the custom search shortcut are always present, so they do not count as loaded values
+const isValueOption = (option: Option) => !['hasValue', 'noValue', 'search'].includes(option.id)
 
 const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDropdownProps>(
   (
@@ -479,7 +479,7 @@ const SearchFilterDropdown = forwardRef<SearchFilterDropdownRef, SearchFilterDro
             {filteredOptions.length === 0 &&
               !isCustomAllowed &&
               (!valuesStatus || valuesStatus === 'loaded') && (
-              <span>No filters found</span>
+              <Styled.StatusItem className="status">No filters found</Styled.StatusItem>
             )}
             {parentId && !!parentFilter?.values?.length && (
               <Styled.Toolbar className="toolbar">
diff --git a/src/SearchFilter/SearchFilterItem/SearchFilterItem.tsx b/src/SearchFilter/SearchFilterItem/SearchFilterItem.tsx
index f1ea9a3..dd74d3a 100644
--- a/src/SearchFilter/SearchFilterItem/SearchFilterItem.tsx
+++ b/src/SearchFilter/SearchFilterItem/SearchFilterItem.tsx
@@ -16,7 +16,6 @@ export interface SearchFilterItemProps
   isSearch?: boolean
   isInlineEditing?: boolean
   inlineSuggestion?: string
-  valueOverride?: SearchFilterDropdownOption
   tooltip?: string
   valueOverride?: SearchFilterDropdownOption
   // search is html input props
diff --git a/src/SearchFilter/lazyValues.ts b/src/SearchFilter/lazyValues.ts
new file mode 100644
index 0000000..4b0bdb8
--- /dev/null
+++ b/src/SearchFilter/lazyValues.ts
@@ -0,0 +1,69 @@
+import { Filter, FilterValue, Option } from './types'
+
+// State of one Option.loadValues request, keyed by option id in SearchFilter
+export type LazyValuesState = {
+  status: 'loading' | 'loaded' | 'error'
+  values: FilterValue[]
+  error?: string
+  key?: string // Option.loadValuesKey the values were loaded for
+  request: object // identity of the load that owns this entry
+}
+
+// Values loaded for a different loadValuesKey (e.g. another project) are stale and not shown
+export const getCurrentValues = (entry: LazyValuesState | undefined, key?: string): FilterValue[] =>
+  entry && entry.key === key ? entry.values : []
+
+// Consumers are expected to reject with an Error (or a string); API payloads are normalized there
+export const getLoadErrorMessage = (error: unknown): string | undefined => {
+  if (typeof error === 'string') return error
+  if (error instanceof Error) return error.message
+  return undefined
+}
+
+// Merges loaded values into their options: loaded values first, static values not covered by them after
+export const withLazyValues = (options: Option[], lazyValues: Record<string, LazyValuesState>) => {
+  if (!Object.keys(lazyValues).length) return options
+  return options.map((option) => {
+    const loadedValues = getCurrentValues(lazyValues[option.id], option.loadValuesKey)
+    if (!loadedValues.length) return option
+    const existing = option.values || []
+    const extra = existing.filter((value) => !loadedValues.some((l) => l.id === value.id))
+    return { ...option, values: [...loadedValues, ...extra] }
+  })
+}
+
+// Updates the opened panel snapshot with loaded values: matching items are refreshed in place
+// (order stays stable), new values are appended, custom values in the snapshot are kept
+export const mergeLoadedValues = (
+  openedOptions: Option[],
+  loadedValues: FilterValue[],
+  parentId: string,
+): Option[] => {
+  const loadedById = new Map(loadedValues.map((value) => [value.id, value]))
+  const openedIds = new Set(openedOptions.map((option) => option.id))
+  const refreshed = openedOptions.map((option) => {
+    const loaded = loadedById.get(option.id)
+    return loaded ? { ...option, ...loaded, parentId } : option
+  })
+  const added = loadedValues
+    .filter((value) => !openedIds.has(value.id))
+    .map((value) => ({ ...value, parentId }))
+  return [...refreshed, ...added]
+}
+
+// Chips built before lazy values arrived carry the raw id as label
+export const getDisplayValues = (filter: Filter, option?: Option): FilterValue[] | undefined => {
+  if (!option?.loadValues || !filter.values) return filter.values
+  return filter.values.map((value) => {
+    if (value.label !== value.id) return value
+    const loaded = option.values?.find((candidate) => candidate.id === value.id)
+    if (!loaded) return value
+    return {
+      ...value,
+      label: loaded.label,
+      icon: value.icon ?? loaded.icon,
+      img: value.img ?? loaded.img,
+      color: value.color ?? loaded.color,
+    }
+  })
+}
diff --git a/src/SearchFilter/types.ts b/src/SearchFilter/types.ts
index 3abe361..4fc3930 100644
--- a/src/SearchFilter/types.ts
+++ b/src/SearchFilter/types.ts
@@ -65,7 +65,8 @@ export interface Option extends Filter {
   allowNoValue?: boolean // allows the filter to have "no value"
   allowHasValue?: boolean // allows the filter to have "has a value"
   allowsCustomValues?: boolean // allows the filter to have custom values
-  loadValues?: () => Promise<FilterValue[]> // fetched on first open (and for active filters), merged into values
+  loadValues?: () => Promise<FilterValue[]> // fetched on open (and for active filters), merged into values; reject with an Error for a readable message
+  loadValuesKey?: string // context the loaded values belong to (e.g. project name); when it changes, previously loaded values are dropped
   allowExcludes?: boolean // allows the filter to be inverted
   operatorChangeable?: boolean // allows the operator to be changed
   color?: string | null // color of the filter (not used for root options)