@brightlocal/ui-components 2.1.0 → 2.3.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.
@@ -0,0 +1,182 @@
1
+ import * as React from "react";
2
+ import { cva } from "class-variance-authority";
3
+
4
+ import { cn } from "@brightlocal/ui-components/lib/utils";
5
+
6
+ /** Available color variants for the Callout component */
7
+ type CalloutVariant = "primary" | "purple" | "blue" | "green";
8
+
9
+ /** Pointer/caret position for the Callout speech bubble */
10
+ type CalloutPointer = "top" | "bottom" | "left" | "right" | "none";
11
+
12
+ const calloutVariants = cva("relative rounded-2xl p-12 shadow-lg", {
13
+ variants: {
14
+ variant: {
15
+ primary: "bg-primary text-primary-foreground",
16
+ purple: "bg-violet-300 text-violet-950",
17
+ blue: "bg-sky-300 text-sky-950",
18
+ green: "bg-green-200 text-green-950",
19
+ },
20
+ },
21
+ defaultVariants: {
22
+ variant: "primary",
23
+ },
24
+ });
25
+
26
+ const citationColorMap: Record<CalloutVariant, string> = {
27
+ primary: "text-primary-foreground/80",
28
+ purple: "text-violet-800",
29
+ blue: "text-sky-900",
30
+ green: "text-green-900",
31
+ };
32
+
33
+ const pointerBgMap: Record<CalloutVariant, string> = {
34
+ primary: "bg-primary",
35
+ purple: "bg-violet-300",
36
+ blue: "bg-sky-300",
37
+ green: "bg-green-200",
38
+ };
39
+
40
+ const pointerPositionMap: Record<Exclude<CalloutPointer, "none">, string> = {
41
+ bottom: "left-1/2 -bottom-2 -translate-x-1/2",
42
+ top: "left-1/2 -top-2 -translate-x-1/2",
43
+ left: "top-1/2 -left-2 -translate-y-1/2",
44
+ right: "top-1/2 -right-2 -translate-y-1/2",
45
+ };
46
+
47
+ /** Context for sharing variant with sub-components */
48
+ const CalloutContext = React.createContext<{ variant: CalloutVariant }>({
49
+ variant: "primary",
50
+ });
51
+
52
+ /** Props for the Callout component */
53
+ interface CalloutProps extends React.ComponentPropsWithoutRef<"div"> {
54
+ /** Required test hook identifier */
55
+ dataHook: string;
56
+ /**
57
+ * Color variant
58
+ * @default "primary"
59
+ */
60
+ variant?: CalloutVariant;
61
+ /**
62
+ * Pointer/caret direction
63
+ * @default "bottom"
64
+ */
65
+ pointer?: CalloutPointer;
66
+ /** Analytics element identifier */
67
+ trackingEl?: string;
68
+ /** Analytics label */
69
+ trackingLabel?: string;
70
+ }
71
+
72
+ /**
73
+ * Speech bubble callout for highlighting key statements or quotes.
74
+ * Supports 4 color variants and configurable pointer direction.
75
+ *
76
+ * Use with `CalloutHeading` and optionally `CalloutCitation` as children.
77
+ */
78
+ const Callout = React.forwardRef<HTMLDivElement, CalloutProps>(
79
+ (
80
+ {
81
+ className,
82
+ variant = "primary",
83
+ pointer = "bottom",
84
+ children,
85
+ dataHook,
86
+ trackingEl,
87
+ trackingLabel,
88
+ ...props
89
+ },
90
+ ref
91
+ ) => {
92
+ const contextValue = React.useMemo(() => ({ variant }), [variant]);
93
+
94
+ return (
95
+ <CalloutContext.Provider value={contextValue}>
96
+ <div
97
+ ref={ref}
98
+ className={cn(calloutVariants({ variant }), className)}
99
+ data-hook={dataHook}
100
+ data-slot="callout"
101
+ data-tracking-el={trackingEl || `callout-${variant}`}
102
+ data-tracking-label={trackingLabel}
103
+ {...props}
104
+ >
105
+ <div className="flex flex-col gap-8">{children}</div>
106
+ {pointer !== "none" && (
107
+ <span
108
+ aria-hidden="true"
109
+ className={cn(
110
+ "pointer-events-none absolute size-4 rotate-45",
111
+ pointerPositionMap[pointer],
112
+ pointerBgMap[variant]
113
+ )}
114
+ data-slot="callout-pointer"
115
+ />
116
+ )}
117
+ </div>
118
+ </CalloutContext.Provider>
119
+ );
120
+ }
121
+ );
122
+
123
+ Callout.displayName = "Callout";
124
+
125
+ /** Props for the CalloutHeading sub-component */
126
+ interface CalloutHeadingProps extends React.ComponentPropsWithoutRef<"div"> {
127
+ /** Optional test hook identifier */
128
+ dataHook?: string;
129
+ }
130
+
131
+ /** Main heading/statement content for a Callout */
132
+ const CalloutHeading = React.forwardRef<HTMLDivElement, CalloutHeadingProps>(
133
+ ({ className, dataHook, ...props }, ref) => (
134
+ <div
135
+ ref={ref}
136
+ className={cn("heading-lg font-semibold", className)}
137
+ data-hook={dataHook}
138
+ data-slot="callout-heading"
139
+ {...props}
140
+ />
141
+ )
142
+ );
143
+
144
+ CalloutHeading.displayName = "CalloutHeading";
145
+
146
+ /** Props for the CalloutCitation sub-component */
147
+ interface CalloutCitationProps extends React.ComponentPropsWithoutRef<"div"> {
148
+ /** Optional test hook identifier */
149
+ dataHook?: string;
150
+ }
151
+
152
+ /** Citation/attribution text for a Callout. Auto-styles based on parent variant. */
153
+ const CalloutCitation = React.forwardRef<HTMLDivElement, CalloutCitationProps>(
154
+ ({ className, dataHook, ...props }, ref) => {
155
+ const { variant } = React.useContext(CalloutContext);
156
+
157
+ return (
158
+ <div
159
+ ref={ref}
160
+ className={cn(
161
+ "text-xs font-medium",
162
+ citationColorMap[variant],
163
+ className
164
+ )}
165
+ data-hook={dataHook}
166
+ data-slot="callout-citation"
167
+ {...props}
168
+ />
169
+ );
170
+ }
171
+ );
172
+
173
+ CalloutCitation.displayName = "CalloutCitation";
174
+
175
+ export { Callout, CalloutHeading, CalloutCitation, calloutVariants };
176
+ export type {
177
+ CalloutProps,
178
+ CalloutHeadingProps,
179
+ CalloutCitationProps,
180
+ CalloutVariant,
181
+ CalloutPointer,
182
+ };
@@ -267,6 +267,11 @@ interface CarouselPreviousProps extends Omit<
267
267
  * @default "carousel-previous"
268
268
  */
269
269
  dataHook?: string;
270
+ /**
271
+ * Hide the button instead of disabling it when there are no previous slides
272
+ * @default false
273
+ */
274
+ hideWhenDisabled?: boolean;
270
275
  }
271
276
 
272
277
  /**
@@ -277,17 +282,20 @@ function CarouselPrevious({
277
282
  variant = "outline",
278
283
  size = "default",
279
284
  dataHook = "carousel-previous",
285
+ hideWhenDisabled = false,
280
286
  ...props
281
287
  }: CarouselPreviousProps) {
282
288
  const { orientation, scrollPrev, canScrollPrev } = useCarousel();
283
289
 
290
+ if (hideWhenDisabled && !canScrollPrev) return null;
291
+
284
292
  return (
285
293
  <Button
286
294
  iconOnly
287
295
  className={cn(
288
296
  "absolute",
289
297
  orientation === "horizontal"
290
- ? "top-1/2 -left-12 -translate-y-1/2"
298
+ ? "top-1/2 left-1 -translate-y-1/2 sm:-left-12"
291
299
  : "-top-12 left-1/2 -translate-x-1/2 rotate-90",
292
300
  className
293
301
  )}
@@ -329,6 +337,11 @@ interface CarouselNextProps extends Omit<
329
337
  * @default "carousel-next"
330
338
  */
331
339
  dataHook?: string;
340
+ /**
341
+ * Hide the button instead of disabling it when there are no next slides
342
+ * @default false
343
+ */
344
+ hideWhenDisabled?: boolean;
332
345
  }
333
346
 
334
347
  /**
@@ -339,17 +352,20 @@ function CarouselNext({
339
352
  variant = "outline",
340
353
  size = "default",
341
354
  dataHook = "carousel-next",
355
+ hideWhenDisabled = false,
342
356
  ...props
343
357
  }: CarouselNextProps) {
344
358
  const { orientation, scrollNext, canScrollNext } = useCarousel();
345
359
 
360
+ if (hideWhenDisabled && !canScrollNext) return null;
361
+
346
362
  return (
347
363
  <Button
348
364
  iconOnly
349
365
  className={cn(
350
366
  "absolute",
351
367
  orientation === "horizontal"
352
- ? "top-1/2 -right-12 -translate-y-1/2"
368
+ ? "top-1/2 right-1 -translate-y-1/2 sm:-right-12"
353
369
  : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90",
354
370
  className
355
371
  )}
@@ -369,6 +385,102 @@ function CarouselNext({
369
385
 
370
386
  CarouselNext.displayName = "CarouselNext";
371
387
 
388
+ /**
389
+ * Props for CarouselDots component.
390
+ */
391
+ interface CarouselDotsProps extends React.ComponentProps<"div"> {
392
+ /**
393
+ * Data hook for automated testing
394
+ * @default "carousel-dots"
395
+ */
396
+ dataHook?: string;
397
+ /**
398
+ * Tracking element identifier for analytics
399
+ */
400
+ trackingEl?: string;
401
+ /**
402
+ * Tracking label for analytics context
403
+ */
404
+ trackingLabel?: string;
405
+ }
406
+
407
+ /**
408
+ * Dot/pill pagination indicator for the carousel.
409
+ * Active slide is shown as an elongated pill, inactive slides as circles.
410
+ */
411
+ function CarouselDots({
412
+ className,
413
+ dataHook = "carousel-dots",
414
+ trackingEl,
415
+ trackingLabel,
416
+ ...props
417
+ }: CarouselDotsProps) {
418
+ const { api } = useCarousel();
419
+ const [selectedIndex, setSelectedIndex] = React.useState(0);
420
+ const [scrollSnaps, setScrollSnaps] = React.useState<number[]>([]);
421
+
422
+ React.useEffect(() => {
423
+ if (!api) return;
424
+
425
+ setScrollSnaps(api.scrollSnapList());
426
+ setSelectedIndex(api.selectedScrollSnap());
427
+
428
+ const onSelect = () => {
429
+ setSelectedIndex(api.selectedScrollSnap());
430
+ };
431
+
432
+ const onReInit = () => {
433
+ setScrollSnaps(api.scrollSnapList());
434
+ setSelectedIndex(api.selectedScrollSnap());
435
+ };
436
+
437
+ api.on("select", onSelect);
438
+ api.on("reInit", onReInit);
439
+
440
+ return () => {
441
+ api.off("select", onSelect);
442
+ api.off("reInit", onReInit);
443
+ };
444
+ }, [api]);
445
+
446
+ if (scrollSnaps.length === 0) return null;
447
+
448
+ return (
449
+ <div
450
+ aria-label="Slide navigation"
451
+ className={cn(
452
+ "border-border dark:border-input dark:bg-input/30 inline-flex items-center justify-center gap-2 rounded-full border bg-white px-2.5 py-2",
453
+ className
454
+ )}
455
+ data-hook={dataHook}
456
+ data-slot="carousel-dots"
457
+ data-tracking-el={trackingEl}
458
+ data-tracking-label={trackingLabel}
459
+ role="group"
460
+ {...props}
461
+ >
462
+ {scrollSnaps.map((_, index) => (
463
+ <button
464
+ key={index}
465
+ aria-current={index === selectedIndex ? "step" : undefined}
466
+ aria-label={`Go to slide ${index + 1}`}
467
+ className={cn(
468
+ "focus-visible:shadow-default size-3 rounded-full transition-[width,background-color] duration-200 ease-out outline-none",
469
+ index === selectedIndex
470
+ ? "bg-muted-foreground/50 dark:bg-muted-foreground/70 w-9"
471
+ : "bg-input hover:bg-muted-foreground/30 dark:bg-input/80 dark:hover:bg-muted-foreground/50"
472
+ )}
473
+ data-slot="carousel-dot"
474
+ type="button"
475
+ onClick={() => api?.scrollTo(index)}
476
+ />
477
+ ))}
478
+ </div>
479
+ );
480
+ }
481
+
482
+ CarouselDots.displayName = "CarouselDots";
483
+
372
484
  export {
373
485
  type CarouselApi,
374
486
  Carousel,
@@ -376,6 +488,12 @@ export {
376
488
  CarouselItem,
377
489
  CarouselPrevious,
378
490
  CarouselNext,
491
+ CarouselDots,
379
492
  };
380
493
 
381
- export type { CarouselProps, CarouselPreviousProps, CarouselNextProps };
494
+ export type {
495
+ CarouselProps,
496
+ CarouselPreviousProps,
497
+ CarouselNextProps,
498
+ CarouselDotsProps,
499
+ };
@@ -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;
@@ -8,7 +8,7 @@ import { cn } from "@brightlocal/ui-components/lib/utils";
8
8
  import { Input, type InputProps } from "./input";
9
9
 
10
10
  const inputGroupVariants = cva(
11
- "relative flex w-full items-center rounded-md border border-input bg-background transition-colors has-[input:focus-visible]:border-ring has-[input:focus-visible]:shadow-default has-[:disabled]:opacity-50",
11
+ "relative flex w-full items-center rounded-sm border border-input bg-background transition-colors has-[input:focus-visible]:border-ring has-[input:focus-visible]:shadow-default has-[:disabled]:opacity-50",
12
12
  {
13
13
  variants: {
14
14
  size: {
package/src/index.ts CHANGED
@@ -8,6 +8,7 @@ export * from "./components/badge";
8
8
  export * from "./components/breadcrumb";
9
9
  export * from "./components/button";
10
10
  export * from "./components/calendar";
11
+ export * from "./components/callout";
11
12
  export * from "./components/card";
12
13
  export * from "./components/carousel";
13
14
  export * from "./components/chart";