@brightlocal/ui-components 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brightlocal/ui-components",
3
- "version": "2.1.0",
3
+ "version": "2.2.0",
4
4
  "description": "BrightLocal Design System UI Components",
5
5
  "type": "module",
6
6
  "private": false,
@@ -431,11 +431,31 @@ export interface ComboboxValueProps {
431
431
  placeholder?: string;
432
432
  /** Custom className */
433
433
  className?: string;
434
+ /**
435
+ * Resolve a display label for the selected value. Called when the internal
436
+ * label registry doesn't have a match (e.g. before the popover opens for
437
+ * the first time with a pre-selected value).
438
+ *
439
+ * @example
440
+ * ```tsx
441
+ * <ComboboxValue
442
+ * placeholder="Select country..."
443
+ * displayValue={(v) => countriesMap.get(v)?.name}
444
+ * />
445
+ * ```
446
+ */
447
+ displayValue?: (value: string) => string | undefined;
434
448
  }
435
449
 
436
- function ComboboxValue({ placeholder, className }: ComboboxValueProps) {
450
+ function ComboboxValue({
451
+ placeholder,
452
+ className,
453
+ displayValue,
454
+ }: ComboboxValueProps) {
437
455
  const { value, itemLabels } = useComboboxContext();
438
- const displayText = value ? itemLabels.get(value) || value : placeholder;
456
+ const displayText = value
457
+ ? itemLabels.get(value) || displayValue?.(value) || value
458
+ : placeholder;
439
459
 
440
460
  return (
441
461
  <span
@@ -737,21 +757,28 @@ ComboboxList.displayName = "ComboboxList";
737
757
  * -----------------------------------------------------------------------------------------------*/
738
758
 
739
759
  export interface ComboboxVirtualListProps<T> {
740
- /** Array of items to virtualise */
760
+ /** Array of items to virtualise. Memoize with useMemo to avoid re-registering labels on every render. */
741
761
  items: T[];
742
762
  /** Extract the string value for each item (used for selection and keyboard navigation) */
743
763
  getItemValue: (item: T) => string;
744
764
  /**
745
- * Extract a display label for filtering. Defaults to `getItemValue`.
765
+ * Extract a display label for filtering and trigger display. Defaults to `getItemValue`.
746
766
  * Only used when `shouldFilter` is true on the parent Combobox.
747
767
  */
748
768
  getItemLabel?: (item: T) => string;
769
+ /**
770
+ * Extract additional keywords to match against when filtering.
771
+ * The item label is always included automatically — these are extras
772
+ * (e.g. ISO codes, abbreviations) that should be searchable without
773
+ * appearing in the trigger display.
774
+ */
775
+ getItemKeywords?: (item: T) => string[];
749
776
  /** Estimated item height in pixels. @default 36 */
750
777
  estimateSize?: number;
751
778
  /** Number of items to render above and below the visible area. @default 5 */
752
779
  overscan?: number;
753
- /** Render function for each item */
754
- children: (item: T, index: number) => React.ReactNode;
780
+ /** Render function for each item. The third argument is the current search query, useful for highlighting matching text. */
781
+ children: (item: T, index: number, searchValue: string) => React.ReactNode;
755
782
  /** Content to render when no items match the filter */
756
783
  renderEmpty?: React.ReactNode;
757
784
  /** Custom className for the scrollable container */
@@ -777,6 +804,7 @@ function ComboboxVirtualListInner<T>(
777
804
  items,
778
805
  getItemValue,
779
806
  getItemLabel,
807
+ getItemKeywords,
780
808
  estimateSize = 36,
781
809
  overscan = 5,
782
810
  children,
@@ -795,6 +823,8 @@ function ComboboxVirtualListInner<T>(
795
823
  searchValue,
796
824
  filterFn,
797
825
  setActiveDescendantId,
826
+ registerItem,
827
+ unregisterItem,
798
828
  } = useComboboxContext();
799
829
  const [activeIndex, setActiveIndex] = React.useState(0);
800
830
  const idPrefix = React.useId();
@@ -802,6 +832,23 @@ function ComboboxVirtualListInner<T>(
802
832
  // Merge forwarded ref with internal ref
803
833
  React.useImperativeHandle(ref, () => parentRef.current!, []);
804
834
 
835
+ // Bulk-register all item labels upfront so ComboboxValue can always resolve
836
+ // the display label — even for items outside the virtualised viewport.
837
+ // Cleanup unregisters stale labels when `items` changes (e.g. server-driven
838
+ // filtering/pagination). The selected value's label survives because
839
+ // unregisterItem has a guard that preserves the currently selected value.
840
+ React.useEffect(() => {
841
+ const resolveLabel = getItemLabel ?? getItemValue;
842
+ for (const item of items) {
843
+ registerItem(getItemValue(item), resolveLabel(item));
844
+ }
845
+ return () => {
846
+ for (const item of items) {
847
+ unregisterItem(getItemValue(item));
848
+ }
849
+ };
850
+ }, [items, getItemValue, getItemLabel, registerItem, unregisterItem]);
851
+
805
852
  // Filter AND rank items by score — same behaviour as cmdk's scoring system.
806
853
  // Items with higher match scores appear first, so ordering is consistent
807
854
  // between the virtual list and cmdk's normal list path.
@@ -812,16 +859,33 @@ function ComboboxVirtualListInner<T>(
812
859
  for (const item of items) {
813
860
  // getItemLabel is a virtual-list-specific override; otherwise delegate
814
861
  // to the shared filterFn which already respects itemToStringValue.
815
- const score = getItemLabel
862
+ let score = getItemLabel
816
863
  ? defaultFilter(getItemLabel(item), searchValue)
817
864
  : filterFn(getItemValue(item), searchValue);
865
+
866
+ // Check additional keywords — take the best score across label + keywords,
867
+ // mirroring how cmdk's keywords prop works on regular ComboboxItem.
868
+ if (getItemKeywords) {
869
+ for (const kw of getItemKeywords(item)) {
870
+ score = Math.max(score, defaultFilter(kw, searchValue));
871
+ }
872
+ }
873
+
818
874
  if (score > 0) scored.push({ item, score });
819
875
  }
820
876
 
821
877
  // Sort descending by score (best match first) — matches cmdk behaviour
822
878
  scored.sort((a, b) => b.score - a.score);
823
879
  return scored.map((s) => s.item);
824
- }, [items, shouldFilter, searchValue, getItemValue, getItemLabel, filterFn]);
880
+ }, [
881
+ items,
882
+ shouldFilter,
883
+ searchValue,
884
+ getItemValue,
885
+ getItemLabel,
886
+ getItemKeywords,
887
+ filterFn,
888
+ ]);
825
889
 
826
890
  // eslint-disable-next-line react-hooks/incompatible-library -- compiler already skips this component; virtualizer is not passed to memoized consumers
827
891
  const virtualizer = useVirtualizer({
@@ -1017,7 +1081,11 @@ function ComboboxVirtualListInner<T>(
1017
1081
  transform: `translateY(${virtualItem.start}px)`,
1018
1082
  }}
1019
1083
  >
1020
- {children(filteredItems[virtualItem.index]!, virtualItem.index)}
1084
+ {children(
1085
+ filteredItems[virtualItem.index]!,
1086
+ virtualItem.index,
1087
+ searchValue
1088
+ )}
1021
1089
  </div>
1022
1090
  ))}
1023
1091
  </div>
@@ -1182,10 +1250,13 @@ const ComboboxItem = React.forwardRef<
1182
1250
 
1183
1251
  // Register item label for ComboboxValue display; clean up on unmount
1184
1252
  // to prevent stale labels in async/pagination/dynamic datasets.
1253
+ // Skip when inside a VirtualList — VirtualList bulk-registers all labels.
1254
+ const isVirtual = !!virtualCtx;
1185
1255
  React.useEffect(() => {
1256
+ if (isVirtual) return;
1186
1257
  registerItemRef.current(itemValue, childText);
1187
1258
  return () => unregisterItemRef.current(itemValue);
1188
- }, [itemValue, childText]);
1259
+ }, [itemValue, childText, isVirtual]);
1189
1260
 
1190
1261
  const handleSelect = () => {
1191
1262
  const newValue = itemValue === value ? "" : itemValue;