@brightlocal/ui-components 2.11.0 → 2.13.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.
Files changed (154) hide show
  1. package/component-meta.json +474 -27
  2. package/dist/blocks/data-table.cjs +1 -1
  3. package/dist/blocks/data-table.d.ts +16 -4
  4. package/dist/blocks/data-table.d.ts.map +1 -1
  5. package/dist/blocks/data-table.js +57 -53
  6. package/dist/blocks/input-list.cjs +2 -2
  7. package/dist/blocks/input-list.d.ts +7 -1
  8. package/dist/blocks/input-list.d.ts.map +1 -1
  9. package/dist/blocks/input-list.js +82 -81
  10. package/dist/blocks/sidebar.cjs +1 -1
  11. package/dist/blocks/sidebar.d.ts +221 -11
  12. package/dist/blocks/sidebar.d.ts.map +1 -1
  13. package/dist/blocks/sidebar.js +687 -406
  14. package/dist/breadcrumb.cjs +1 -1
  15. package/dist/breadcrumb.d.ts +14 -2
  16. package/dist/breadcrumb.d.ts.map +1 -1
  17. package/dist/breadcrumb.js +37 -37
  18. package/dist/callout.cjs +1 -1
  19. package/dist/callout.d.ts +3 -3
  20. package/dist/callout.d.ts.map +1 -1
  21. package/dist/callout.js +2 -1
  22. package/dist/carousel.cjs +1 -1
  23. package/dist/carousel.d.ts +24 -3
  24. package/dist/carousel.d.ts.map +1 -1
  25. package/dist/carousel.js +121 -117
  26. package/dist/chip.cjs +1 -1
  27. package/dist/chip.d.ts +11 -0
  28. package/dist/chip.d.ts.map +1 -1
  29. package/dist/chip.js +43 -38
  30. package/dist/combobox.cjs +3 -3
  31. package/dist/combobox.d.ts +20 -2
  32. package/dist/combobox.d.ts.map +1 -1
  33. package/dist/combobox.js +244 -238
  34. package/dist/command.cjs +1 -1
  35. package/dist/command.d.ts +5 -0
  36. package/dist/command.d.ts.map +1 -1
  37. package/dist/command.js +207 -206
  38. package/dist/date-picker.cjs +1 -1
  39. package/dist/date-picker.d.ts +10 -0
  40. package/dist/date-picker.d.ts.map +1 -1
  41. package/dist/date-picker.js +96 -96
  42. package/dist/dialog.cjs +1 -1
  43. package/dist/dialog.d.ts +7 -2
  44. package/dist/dialog.d.ts.map +1 -1
  45. package/dist/dialog.js +38 -30
  46. package/dist/drawer.d.ts +2 -2
  47. package/dist/dropdown-menu.cjs +1 -1
  48. package/dist/dropdown-menu.js +1 -1
  49. package/dist/global-layout.cjs +1 -1
  50. package/dist/global-layout.d.ts +5 -0
  51. package/dist/global-layout.d.ts.map +1 -1
  52. package/dist/global-layout.js +15 -7
  53. package/dist/index.cjs +1 -1
  54. package/dist/index.js +313 -305
  55. package/dist/input-chip.cjs +1 -1
  56. package/dist/input-chip.d.ts +7 -1
  57. package/dist/input-chip.d.ts.map +1 -1
  58. package/dist/input-chip.js +131 -130
  59. package/dist/input-group.d.ts +1 -1
  60. package/dist/input-password.cjs +1 -1
  61. package/dist/input-password.d.ts +10 -0
  62. package/dist/input-password.d.ts.map +1 -1
  63. package/dist/input-password.js +108 -106
  64. package/dist/link.cjs +1 -1
  65. package/dist/link.d.ts +1 -1
  66. package/dist/link.d.ts.map +1 -1
  67. package/dist/link.js +36 -37
  68. package/dist/list.cjs +1 -1
  69. package/dist/list.d.ts +25 -4
  70. package/dist/list.d.ts.map +1 -1
  71. package/dist/list.js +71 -53
  72. package/dist/logo.cjs +1 -1
  73. package/dist/logo.d.ts +6 -1
  74. package/dist/logo.d.ts.map +1 -1
  75. package/dist/logo.js +25 -22
  76. package/dist/map.cjs +1 -1
  77. package/dist/map.d.ts +17 -2
  78. package/dist/map.d.ts.map +1 -1
  79. package/dist/map.js +32 -26
  80. package/dist/pagination.cjs +1 -1
  81. package/dist/pagination.d.ts +29 -3
  82. package/dist/pagination.d.ts.map +1 -1
  83. package/dist/pagination.js +26 -25
  84. package/dist/popover.cjs +1 -1
  85. package/dist/popover.js +7 -7
  86. package/dist/rating.cjs +1 -1
  87. package/dist/rating.d.ts +6 -0
  88. package/dist/rating.d.ts.map +1 -1
  89. package/dist/rating.js +28 -20
  90. package/dist/resizable.d.ts +1 -1
  91. package/dist/select.cjs +2 -2
  92. package/dist/select.d.ts +17 -3
  93. package/dist/select.d.ts.map +1 -1
  94. package/dist/select.js +65 -58
  95. package/dist/separator.cjs +1 -1
  96. package/dist/separator.d.ts +16 -4
  97. package/dist/separator.d.ts.map +1 -1
  98. package/dist/separator.js +38 -35
  99. package/dist/sheet.cjs +1 -1
  100. package/dist/sheet.d.ts +6 -1
  101. package/dist/sheet.d.ts.map +1 -1
  102. package/dist/sheet.js +42 -41
  103. package/dist/skeleton.cjs +1 -1
  104. package/dist/skeleton.d.ts +5 -0
  105. package/dist/skeleton.d.ts.map +1 -1
  106. package/dist/skeleton.js +13 -11
  107. package/dist/table.cjs +1 -1
  108. package/dist/table.d.ts +14 -0
  109. package/dist/table.d.ts.map +1 -1
  110. package/dist/table.js +57 -39
  111. package/dist/tabs.cjs +1 -1
  112. package/dist/tabs.d.ts +25 -9
  113. package/dist/tabs.d.ts.map +1 -1
  114. package/dist/tabs.js +128 -113
  115. package/dist/text-reveal-motion.cjs +1 -1
  116. package/dist/text-reveal-motion.d.ts +5 -0
  117. package/dist/text-reveal-motion.d.ts.map +1 -1
  118. package/dist/text-reveal-motion.js +111 -110
  119. package/dist/typography.cjs +1 -1
  120. package/dist/typography.d.ts +1 -2
  121. package/dist/typography.d.ts.map +1 -1
  122. package/dist/typography.js +49 -50
  123. package/package.json +2 -3
  124. package/src/blocks/data-table.tsx +26 -9
  125. package/src/blocks/input-list.tsx +12 -1
  126. package/src/blocks/sidebar.tsx +638 -29
  127. package/src/components/breadcrumb.tsx +43 -26
  128. package/src/components/callout.tsx +5 -4
  129. package/src/components/carousel.tsx +33 -4
  130. package/src/components/chip.tsx +22 -2
  131. package/src/components/combobox.tsx +28 -3
  132. package/src/components/command.tsx +7 -1
  133. package/src/components/date-picker.tsx +17 -3
  134. package/src/components/dialog.tsx +17 -4
  135. package/src/components/drawer.tsx +2 -2
  136. package/src/components/dropdown-menu.tsx +1 -1
  137. package/src/components/global-layout.tsx +15 -2
  138. package/src/components/input-chip.tsx +12 -1
  139. package/src/components/input-password.tsx +73 -49
  140. package/src/components/link.tsx +29 -17
  141. package/src/components/list.tsx +45 -2
  142. package/src/components/logo.tsx +10 -2
  143. package/src/components/map.tsx +23 -0
  144. package/src/components/pagination.tsx +44 -11
  145. package/src/components/popover.tsx +1 -1
  146. package/src/components/rating.tsx +21 -3
  147. package/src/components/select.tsx +33 -3
  148. package/src/components/separator.tsx +40 -25
  149. package/src/components/sheet.tsx +28 -20
  150. package/src/components/skeleton.tsx +13 -2
  151. package/src/components/table.tsx +39 -2
  152. package/src/components/tabs.tsx +195 -146
  153. package/src/components/text-reveal-motion.tsx +7 -1
  154. package/src/components/typography.tsx +6 -7
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brightlocal/ui-components",
3
- "version": "2.11.0",
3
+ "version": "2.13.0",
4
4
  "description": "Machine-readable registry of all components in the BrightLocal Design System",
5
5
  "components": [
6
6
  {
@@ -108,10 +108,25 @@
108
108
  "confirm modal",
109
109
  "destructive action dialog"
110
110
  ],
111
+ "whenToUse": [
112
+ "User is about to perform an irreversible or destructive action (delete, discard, overwrite)",
113
+ "Action has significant consequences that require explicit confirmation",
114
+ "Two clear actions: confirm or cancel — no other options needed"
115
+ ],
111
116
  "doNotUseFor": [
112
117
  "informational dialogs (use Dialog)",
113
118
  "toast messages (use Sonner)"
114
119
  ],
120
+ "alternatives": [
121
+ {
122
+ "component": "Dialog",
123
+ "rule": "Use Dialog when content is informational or includes a form — not a simple confirm/cancel"
124
+ },
125
+ {
126
+ "component": "Sonner",
127
+ "rule": "Use Sonner for non-blocking success/error feedback after an action completes"
128
+ }
129
+ ],
115
130
  "replaces": [],
116
131
  "states": [
117
132
  "open",
@@ -187,10 +202,25 @@
187
202
  "label",
188
203
  "status indicator"
189
204
  ],
205
+ "whenToUse": [
206
+ "Displaying a status label (active/inactive, new, draft)",
207
+ "Showing a count or numeric indicator",
208
+ "Non-interactive categorical labels"
209
+ ],
190
210
  "doNotUseFor": [
191
211
  "removable tags (use Chip)",
192
212
  "interactive elements (use Button)"
193
213
  ],
214
+ "alternatives": [
215
+ {
216
+ "component": "Chip",
217
+ "rule": "Use Chip when the user can remove/dismiss the tag — Badge is non-interactive"
218
+ },
219
+ {
220
+ "component": "Button",
221
+ "rule": "Use Button for interactive status toggles"
222
+ }
223
+ ],
194
224
  "replaces": [],
195
225
  "states": [
196
226
  "default"
@@ -218,6 +248,14 @@
218
248
  "dataHookRequired": true,
219
249
  "variants": {},
220
250
  "props": [],
251
+ "i18nProps": {
252
+ "Breadcrumb": {
253
+ "ariaLabel": "string — default: \"breadcrumb\""
254
+ },
255
+ "BreadcrumbEllipsis": {
256
+ "srLabel": "string — default: \"More\""
257
+ }
258
+ },
221
259
  "description": "Hierarchical navigation trail"
222
260
  },
223
261
  {
@@ -260,10 +298,36 @@
260
298
  "submit button",
261
299
  "confirm button"
262
300
  ],
301
+ "whenToUse": [
302
+ "Triggering an action (submit, save, delete, open)",
303
+ "Primary and secondary CTAs in forms, dialogs, and cards",
304
+ "Icon-only actions using the iconOnly prop"
305
+ ],
263
306
  "doNotUseFor": [
264
307
  "navigation links (use Link)",
265
308
  "toggle state (use Toggle or Switch)"
266
309
  ],
310
+ "alternatives": [
311
+ {
312
+ "component": "Link",
313
+ "rule": "Use Link for navigation to a URL — even if it looks like a button, use Button with asChild wrapping a router Link for button-styled navigation"
314
+ },
315
+ {
316
+ "component": "Toggle",
317
+ "rule": "Use Toggle for on/off state that persists (e.g., bold, italic)"
318
+ },
319
+ {
320
+ "component": "DropdownMenu",
321
+ "rule": "Use Button + DropdownMenu for a button with secondary actions (SplitButton recipe)"
322
+ }
323
+ ],
324
+ "knownGaps": [
325
+ {
326
+ "description": "No ButtonLink variant for navigation-styled buttons",
327
+ "ticket": "DS-530",
328
+ "workaround": "Use Button with asChild wrapping a router Link component"
329
+ }
330
+ ],
267
331
  "replaces": [
268
332
  "native <button>"
269
333
  ],
@@ -361,7 +425,7 @@
361
425
  "props": [
362
426
  "maxWidth"
363
427
  ],
364
- "description": "Content container with consistent styling",
428
+ "description": "Content container with consistent styling. Supports a density prop: 'default' uses generous spacing (gap-8, py-section-md, px-section-md) for standalone cards; 'condensed' uses compact spacing (gap-3, py-3, px-3) for cards nested inside other cards as sub-sections, inline stat panels, or dense dashboard widgets.",
365
429
  "aliases": [
366
430
  "container",
367
431
  "panel",
@@ -369,6 +433,18 @@
369
433
  "wrapper",
370
434
  "content card"
371
435
  ],
436
+ "whenToUse": [
437
+ "Grouping related content with a visual boundary (form sections, detail panels, stat cards)",
438
+ "Page-level content containers that need consistent padding and border styling",
439
+ "Nested sub-sections within a parent card — use density='condensed' for compact inline panels (e.g., stat summaries, ranking grids, metric tiles)"
440
+ ],
441
+ "knownGaps": [
442
+ {
443
+ "description": "CardTitle text size too large for some contexts — smaller variant needed",
444
+ "ticket": "DS-535",
445
+ "workaround": "Override CardTitle with className='text-lg' or 'text-base' for smaller titles"
446
+ }
447
+ ],
372
448
  "doNotUseFor": [
373
449
  "clickable list items (use List)",
374
450
  "modal content (use Dialog)"
@@ -415,6 +491,18 @@
415
491
  "hooks": [
416
492
  "useCarousel"
417
493
  ],
494
+ "i18nProps": {
495
+ "CarouselPrevious": {
496
+ "ariaLabel": "string — default: \"Previous slide\""
497
+ },
498
+ "CarouselNext": {
499
+ "ariaLabel": "string — default: \"Next slide\""
500
+ },
501
+ "CarouselDots": {
502
+ "ariaLabel": "string — default: \"Slide navigation\"",
503
+ "slideAriaLabel": "string — default: \"Go to slide {slide}\""
504
+ }
505
+ },
418
506
  "description": "Image/content carousel slider"
419
507
  },
420
508
  {
@@ -430,7 +518,25 @@
430
518
  "dataHookRequired": true,
431
519
  "variants": {},
432
520
  "props": [],
433
- "description": "Full-page centered content layout"
521
+ "description": "Full-page centered content layout",
522
+ "whenToUse": [
523
+ "Single-column centered pages (login, signup, password reset, onboarding)",
524
+ "Pages with a centered Card and branded header"
525
+ ],
526
+ "doNotUseFor": [
527
+ "two-column layouts (use SplitLayout)",
528
+ "app shells with sidebar navigation (use GlobalLayout + Sidebar)"
529
+ ],
530
+ "alternatives": [
531
+ {
532
+ "component": "SplitLayout",
533
+ "rule": "Use SplitLayout for two-column pages with marketing content on one side"
534
+ },
535
+ {
536
+ "component": "GlobalLayout",
537
+ "rule": "Use GlobalLayout for full app shells with sidebar navigation"
538
+ }
539
+ ]
434
540
  },
435
541
  {
436
542
  "name": "Chart",
@@ -517,7 +623,32 @@
517
623
  "onRemove",
518
624
  "maxWidth"
519
625
  ],
520
- "description": "Removable chip/tag element"
626
+ "i18nProps": {
627
+ "Chip": {
628
+ "loadingLabel": "string — default: \"Loading\"",
629
+ "removeAriaLabel": "string — default: \"Remove {name}\""
630
+ }
631
+ },
632
+ "description": "Removable chip/tag element",
633
+ "whenToUse": [
634
+ "Displaying user-created tags that can be removed",
635
+ "Selected filter values that can be dismissed",
636
+ "Multi-select token display with remove capability"
637
+ ],
638
+ "doNotUseFor": [
639
+ "non-interactive status labels (use Badge)",
640
+ "category labels without remove action (use Badge)"
641
+ ],
642
+ "alternatives": [
643
+ {
644
+ "component": "Badge",
645
+ "rule": "Use Badge for non-interactive status indicators or labels"
646
+ },
647
+ {
648
+ "component": "InputChip",
649
+ "rule": "Use InputChip when users need to both add and remove tags via an input field"
650
+ }
651
+ ]
521
652
  },
522
653
  {
523
654
  "name": "Collapsible",
@@ -570,6 +701,14 @@
570
701
  "sideOffset",
571
702
  "avoidCollisions"
572
703
  ],
704
+ "i18nProps": {
705
+ "ComboboxContent": {
706
+ "ariaLabel": "string — default: \"Options\""
707
+ },
708
+ "ComboboxLoading": {
709
+ "loadingText": "string — default: \"Loading...\""
710
+ }
711
+ },
573
712
  "description": "Searchable select dropdown with filtering",
574
713
  "aliases": [
575
714
  "autocomplete",
@@ -577,10 +716,35 @@
577
716
  "typeahead",
578
717
  "filterable dropdown"
579
718
  ],
719
+ "whenToUse": [
720
+ "Dropdown with 10+ options where search/filtering improves UX",
721
+ "Autocomplete or typeahead for large lists (cities, categories, users)",
722
+ "Multi-select with search capability"
723
+ ],
580
724
  "doNotUseFor": [
581
725
  "simple select without search (use Select)",
582
726
  "command palette (use Command)"
583
727
  ],
728
+ "alternatives": [
729
+ {
730
+ "component": "Select",
731
+ "rule": "Use Select for short lists (under 10 options) where search is unnecessary"
732
+ },
733
+ {
734
+ "component": "Command",
735
+ "rule": "Use Command for keyboard-driven command palettes or action search"
736
+ },
737
+ {
738
+ "component": "DropdownMenu",
739
+ "rule": "Use DropdownMenu for action menus triggered by a button — not form selection"
740
+ }
741
+ ],
742
+ "knownGaps": [
743
+ {
744
+ "description": "Missing onValueChange callback — consumers need @ts-expect-error workaround",
745
+ "workaround": "Use @ts-expect-error when passing onValueChange to Combobox until the API is updated"
746
+ }
747
+ ],
584
748
  "replaces": [],
585
749
  "states": [
586
750
  "open",
@@ -624,6 +788,11 @@
624
788
  "onClear",
625
789
  "debounceMs"
626
790
  ],
791
+ "i18nProps": {
792
+ "CommandInput": {
793
+ "clearSearchAriaLabel": "string — default: \"Clear search\""
794
+ }
795
+ },
627
796
  "description": "Command palette and search interface"
628
797
  },
629
798
  {
@@ -657,9 +826,7 @@
657
826
  "DatePickerTrigger",
658
827
  "DatePickerContent",
659
828
  "DatePickerCalendar",
660
- "DatePickerInput",
661
- "DatePickerPresets",
662
- "DatePickerFooter"
829
+ "DatePickerPresets"
663
830
  ],
664
831
  "compound": true,
665
832
  "dataHookRequired": true,
@@ -677,6 +844,14 @@
677
844
  "disabled",
678
845
  "dateFormat"
679
846
  ],
847
+ "i18nProps": {
848
+ "DatePickerTrigger": {
849
+ "triggerLabel": "string — default: \"Pick a date\""
850
+ },
851
+ "DatePickerContent": {
852
+ "contentLabel": "string — default: \"Date picker\""
853
+ }
854
+ },
680
855
  "description": "Date selection with calendar popup and presets"
681
856
  },
682
857
  {
@@ -716,16 +891,40 @@
716
891
  "onOpenChange",
717
892
  "modal"
718
893
  ],
894
+ "i18nProps": {
895
+ "DialogContent": {
896
+ "closeLabel": "string — default: \"Close\""
897
+ }
898
+ },
719
899
  "description": "Modal dialog overlay",
720
900
  "aliases": [
721
901
  "modal",
722
902
  "popup",
723
903
  "lightbox"
724
904
  ],
905
+ "whenToUse": [
906
+ "Presenting informational content or forms that require focused attention",
907
+ "Content that should block interaction with the page behind it",
908
+ "Multi-step flows or forms that don't fit inline"
909
+ ],
725
910
  "doNotUseFor": [
726
911
  "confirmation actions (use AlertDialog)",
727
912
  "side panels (use Sheet or Drawer)"
728
913
  ],
914
+ "alternatives": [
915
+ {
916
+ "component": "AlertDialog",
917
+ "rule": "Use AlertDialog when the user must confirm or cancel a destructive/irreversible action"
918
+ },
919
+ {
920
+ "component": "Sheet",
921
+ "rule": "Use Sheet for side panels with supplementary content or forms that don't need centered focus"
922
+ },
923
+ {
924
+ "component": "Drawer",
925
+ "rule": "Use Drawer for mobile-friendly bottom/side slide-out panels"
926
+ }
927
+ ],
729
928
  "replaces": [
730
929
  "native <dialog>"
731
930
  ],
@@ -766,7 +965,26 @@
766
965
  "onOpenChange",
767
966
  "direction"
768
967
  ],
769
- "description": "Slide-out drawer panel"
968
+ "description": "Slide-out drawer panel",
969
+ "whenToUse": [
970
+ "Mobile-friendly slide-out panel from any edge",
971
+ "Non-modal supplementary content on touch devices",
972
+ "Bottom sheet pattern on mobile viewports"
973
+ ],
974
+ "doNotUseFor": [
975
+ "centered dialogs (use Dialog)",
976
+ "confirmation prompts (use AlertDialog)"
977
+ ],
978
+ "alternatives": [
979
+ {
980
+ "component": "Sheet",
981
+ "rule": "Use Sheet for always-modal side panels with overlay — Sheet is modal-only, Drawer supports non-modal"
982
+ },
983
+ {
984
+ "component": "Dialog",
985
+ "rule": "Use Dialog when content should be centered and focused, not sliding from an edge"
986
+ }
987
+ ]
770
988
  },
771
989
  {
772
990
  "name": "DropdownMenu",
@@ -855,10 +1073,21 @@
855
1073
  "input group",
856
1074
  "field wrapper"
857
1075
  ],
1076
+ "whenToUse": [
1077
+ "Wrapping any form input with label, description, and error message",
1078
+ "Canonical pattern: Field > FieldLabel + Input/Select/Textarea + FieldDescription + FieldError",
1079
+ "When integrating with React Hook Form — use Field with Controller to wire up error state"
1080
+ ],
858
1081
  "doNotUseFor": [
859
1082
  "standalone labels (use Label)",
860
1083
  "inline text (use Typography)"
861
1084
  ],
1085
+ "alternatives": [
1086
+ {
1087
+ "component": "Label",
1088
+ "rule": "Use standalone Label only when building a custom field layout — Field includes FieldLabel with proper a11y wiring"
1089
+ }
1090
+ ],
862
1091
  "replaces": [],
863
1092
  "states": [
864
1093
  "default",
@@ -877,7 +1106,10 @@
877
1106
  "exports": [
878
1107
  "GlobalLayout",
879
1108
  "GlobalLayoutSidebar",
880
- "GlobalLayoutContent"
1109
+ "GlobalLayoutContent",
1110
+ "GlobalLayoutContentHeader",
1111
+ "GlobalLayoutContentBody",
1112
+ "GlobalLayoutMobileHeader"
881
1113
  ],
882
1114
  "compound": true,
883
1115
  "dataHookRequired": true,
@@ -892,6 +1124,11 @@
892
1124
  "maxWidth",
893
1125
  "width"
894
1126
  ],
1127
+ "i18nProps": {
1128
+ "GlobalLayoutMobileHeader": {
1129
+ "ariaLabel": "string — default: \"Mobile navigation\""
1130
+ }
1131
+ },
895
1132
  "description": "Full-page responsive layout with sidebar"
896
1133
  },
897
1134
  {
@@ -995,6 +1232,11 @@
995
1232
  "disabled",
996
1233
  "allowDuplicates"
997
1234
  ],
1235
+ "i18nProps": {
1236
+ "InputChipItems": {
1237
+ "itemAriaLabel": "string — default: \"{item}, press Delete to remove\""
1238
+ }
1239
+ },
998
1240
  "description": "Tag/chip input with managed items"
999
1241
  },
1000
1242
  {
@@ -1057,6 +1299,12 @@
1057
1299
  "onStrengthChange",
1058
1300
  "showMeter"
1059
1301
  ],
1302
+ "i18nProps": {
1303
+ "InputPassword": {
1304
+ "showLabel": "string — default: \"Show password\"",
1305
+ "hideLabel": "string — default: \"Hide password\""
1306
+ }
1307
+ },
1060
1308
  "description": "Password input with visibility toggle and strength meter"
1061
1309
  },
1062
1310
  {
@@ -1108,7 +1356,22 @@
1108
1356
  "showExternalIcon",
1109
1357
  "asChild"
1110
1358
  ],
1111
- "description": "Styled hyperlink with external link support"
1359
+ "description": "Styled hyperlink with external link support",
1360
+ "whenToUse": [
1361
+ "Inline text links within paragraphs or sentences",
1362
+ "Navigation to internal or external URLs",
1363
+ "Links inside i18n <Trans> blocks — use Link as a component in the components map"
1364
+ ],
1365
+ "doNotUseFor": [
1366
+ "actions that don't navigate (use Button)",
1367
+ "button-styled navigation (use Button with asChild wrapping a router link)"
1368
+ ],
1369
+ "alternatives": [
1370
+ {
1371
+ "component": "Button",
1372
+ "rule": "Use Button for actions (submit, delete, open). For button-styled navigation, use Button asChild wrapping your router's Link component"
1373
+ }
1374
+ ]
1112
1375
  },
1113
1376
  {
1114
1377
  "name": "List",
@@ -1117,20 +1380,25 @@
1117
1380
  "exports": [
1118
1381
  "List",
1119
1382
  "Item",
1383
+ "ItemMedia",
1120
1384
  "ItemContent",
1121
1385
  "ItemTitle",
1122
- "ItemActions"
1386
+ "ItemDescription",
1387
+ "ItemActions",
1388
+ "ItemSubheader"
1123
1389
  ],
1124
1390
  "compound": true,
1125
1391
  "dataHookRequired": true,
1126
1392
  "variants": {
1127
1393
  "variant": [
1128
1394
  "default",
1129
- "outline"
1395
+ "filled",
1396
+ "outline",
1397
+ "loading"
1130
1398
  ]
1131
1399
  },
1132
1400
  "props": [],
1133
- "description": "Vertical item list"
1401
+ "description": "Vertical item list with optional section headings"
1134
1402
  },
1135
1403
  {
1136
1404
  "name": "Logo",
@@ -1148,19 +1416,25 @@
1148
1416
  ]
1149
1417
  },
1150
1418
  "props": [],
1151
- "description": "BrightLocal brand logo"
1419
+ "description": "BrightLocal brand logo",
1420
+ "i18nProps": {
1421
+ "Logo": {
1422
+ "ariaLabel": "string — default: \"BrightLocal Logo\""
1423
+ }
1424
+ }
1152
1425
  },
1153
1426
  {
1154
1427
  "name": "Map",
1155
1428
  "import": "@brightlocal/ui-components/map",
1156
1429
  "category": "display",
1157
1430
  "exports": [
1431
+ "MapTypeId",
1432
+ "MapLocationPin",
1433
+ "MapGridPin",
1158
1434
  "MapControlButton",
1435
+ "MapLoadingState",
1159
1436
  "MapErrorState",
1160
- "MapGridPin",
1161
1437
  "MapLegend",
1162
- "MapLoadingState",
1163
- "MapLocationPin",
1164
1438
  "MapPopover",
1165
1439
  "MapPopoverAnchor",
1166
1440
  "MapPopoverContent",
@@ -1242,6 +1516,23 @@
1242
1516
  "hooks": [
1243
1517
  "usePagination"
1244
1518
  ],
1519
+ "i18nProps": {
1520
+ "Pagination": {
1521
+ "ariaLabel": "string — default: \"Pagination\""
1522
+ },
1523
+ "PaginationPrevious": {
1524
+ "ariaLabel": "string — default: \"Go to previous page\""
1525
+ },
1526
+ "PaginationNext": {
1527
+ "ariaLabel": "string — default: \"Go to next page\""
1528
+ },
1529
+ "PaginationLink": {
1530
+ "ariaLabel": "string — default: \"Go to page {page}\""
1531
+ },
1532
+ "PaginationEllipsis": {
1533
+ "srLabel": "string — default: \"More pages\""
1534
+ }
1535
+ },
1245
1536
  "description": "Page navigation controls"
1246
1537
  },
1247
1538
  {
@@ -1352,7 +1643,12 @@
1352
1643
  "props": [
1353
1644
  "value"
1354
1645
  ],
1355
- "description": "Star rating display (0–5, 0.5 increments)"
1646
+ "description": "Star rating display (0–5, 0.5 increments)",
1647
+ "i18nProps": {
1648
+ "Rating": {
1649
+ "ariaLabel": "string — default: \"Rating: {value} out of 5 stars\""
1650
+ }
1651
+ }
1356
1652
  },
1357
1653
  {
1358
1654
  "name": "Resizable",
@@ -1444,6 +1740,11 @@
1444
1740
  "Enter",
1445
1741
  "Arrow keys"
1446
1742
  ]
1743
+ },
1744
+ "i18nProps": {
1745
+ "SelectTrigger": {
1746
+ "selectLabel": "string — default: \"Select an option\""
1747
+ }
1447
1748
  }
1448
1749
  },
1449
1750
  {
@@ -1497,6 +1798,11 @@
1497
1798
  "open",
1498
1799
  "onOpenChange"
1499
1800
  ],
1801
+ "i18nProps": {
1802
+ "SheetContent": {
1803
+ "closeLabel": "string — default: \"Close\""
1804
+ }
1805
+ },
1500
1806
  "description": "Side panel overlay",
1501
1807
  "aliases": [
1502
1808
  "side panel",
@@ -1505,10 +1811,29 @@
1505
1811
  "tray",
1506
1812
  "slide-out"
1507
1813
  ],
1814
+ "whenToUse": [
1815
+ "Side panel for editing details, settings, or supplementary info",
1816
+ "Right-side panel pattern (most common: filters, detail views, forms)",
1817
+ "Content that should slide in from an edge without navigating away"
1818
+ ],
1508
1819
  "doNotUseFor": [
1509
1820
  "centered dialogs (use Dialog)",
1510
1821
  "confirmations (use AlertDialog)"
1511
1822
  ],
1823
+ "alternatives": [
1824
+ {
1825
+ "component": "Dialog",
1826
+ "rule": "Use Dialog for centered content requiring focused attention"
1827
+ },
1828
+ {
1829
+ "component": "Drawer",
1830
+ "rule": "Use Drawer when you need non-modal behavior or mobile bottom-sheet pattern"
1831
+ },
1832
+ {
1833
+ "component": "Sidebar",
1834
+ "rule": "Use Sidebar for persistent collapsible navigation — Sheet is for temporary overlays"
1835
+ }
1836
+ ],
1512
1837
  "replaces": [],
1513
1838
  "states": [
1514
1839
  "open",
@@ -1620,7 +1945,27 @@
1620
1945
  "left",
1621
1946
  "right"
1622
1947
  ],
1623
- "description": "Two-column responsive layout with composition pattern"
1948
+ "description": "Two-column responsive layout with composition pattern",
1949
+ "whenToUse": [
1950
+ "Two-column pages where one side is content and the other is decorative/marketing",
1951
+ "Auth pages with form on the left and branding on the right",
1952
+ "Any page where the right column should be hidden on mobile"
1953
+ ],
1954
+ "doNotUseFor": [
1955
+ "centered single-column layouts (use CentredLayout)",
1956
+ "app shells with sidebar navigation (use GlobalLayout + Sidebar)",
1957
+ "equal-width columns that should both be visible on mobile (use CSS grid)"
1958
+ ],
1959
+ "alternatives": [
1960
+ {
1961
+ "component": "CentredLayout",
1962
+ "rule": "Use CentredLayout for single-column centered content"
1963
+ },
1964
+ {
1965
+ "component": "GlobalLayout",
1966
+ "rule": "Use GlobalLayout for full app shells with persistent sidebar"
1967
+ }
1968
+ ]
1624
1969
  },
1625
1970
  {
1626
1971
  "name": "Switch",
@@ -1695,10 +2040,21 @@
1695
2040
  "grid",
1696
2041
  "list table"
1697
2042
  ],
2043
+ "whenToUse": [
2044
+ "Simple read-only data display with no sorting, filtering, or pagination",
2045
+ "Static tables like pricing tiers, feature comparisons, or settings summaries",
2046
+ "When you control the exact columns and rows — no dynamic column configuration needed"
2047
+ ],
1698
2048
  "doNotUseFor": [
1699
2049
  "complex filtering and sorting (use DataTable block)",
1700
2050
  "layout grids (use CSS grid)"
1701
2051
  ],
2052
+ "alternatives": [
2053
+ {
2054
+ "component": "DataTable",
2055
+ "rule": "Use DataTable for sortable, filterable, paginated tables with row selection — it wraps TanStack Table"
2056
+ }
2057
+ ],
1702
2058
  "replaces": [
1703
2059
  "native <table>"
1704
2060
  ],
@@ -1787,7 +2143,12 @@
1787
2143
  "gradientFrom",
1788
2144
  "gradientTo"
1789
2145
  ],
1790
- "description": "Animated text reveal with rolling shape-morphing ball"
2146
+ "description": "Animated text reveal with rolling shape-morphing ball",
2147
+ "i18nProps": {
2148
+ "TextRevealMotion": {
2149
+ "loadingLabel": "string — default: \"Loading\""
2150
+ }
2151
+ }
1791
2152
  },
1792
2153
  {
1793
2154
  "name": "Toggle",
@@ -1917,7 +2278,22 @@
1917
2278
  "props": [
1918
2279
  "asChild"
1919
2280
  ],
1920
- "description": "Semantic text components for headings, paragraphs, and inline styles"
2281
+ "description": "Semantic text components for headings, paragraphs, and inline styles",
2282
+ "whenToUse": [
2283
+ "Page and section headings (H1–H4) with consistent font and spacing",
2284
+ "Body text, lead text, muted captions, and inline code",
2285
+ "Any heading or paragraph that should follow the design system type scale"
2286
+ ],
2287
+ "doNotUseFor": [
2288
+ "display-sized hero text larger than H1 — not yet covered, use custom Tailwind classes",
2289
+ "form labels (use Label or FieldLabel)"
2290
+ ],
2291
+ "alternatives": [
2292
+ {
2293
+ "component": "Label",
2294
+ "rule": "Use Label for form input labels — Typography is for content headings and body text"
2295
+ }
2296
+ ]
1921
2297
  }
1922
2298
  ],
1923
2299
  "blocks": [
@@ -1954,6 +2330,25 @@
1954
2330
  "isLoading",
1955
2331
  "noResultsMessage"
1956
2332
  ],
2333
+ "i18nProps": {
2334
+ "DataTableColumnHeader": {
2335
+ "getSortLabel": "(title: string, direction: \"asc\" | \"desc\" | false) => string"
2336
+ },
2337
+ "DataTableSearch": {
2338
+ "ariaLabel": "string — default: \"Search table\"",
2339
+ "placeholder": "string — default: \"Search...\"",
2340
+ "clearSearchAriaLabel": "string — default: \"Clear search\""
2341
+ },
2342
+ "DataTablePaginationNav": {
2343
+ "ariaLabel": "string — default: \"Table pagination\""
2344
+ },
2345
+ "DataTableSelectAllCheckbox": {
2346
+ "selectAllAriaLabel": "string — default: \"Select all\""
2347
+ },
2348
+ "DataTableSelectRowCheckbox": {
2349
+ "selectRowAriaLabel": "string — default: \"Select row\""
2350
+ }
2351
+ },
1957
2352
  "description": "Composable data table built on TanStack Table. Exposes `useDataTable` hook + `DataTable` / `VirtualizedDataTable` renderers + toolbar layout + pagination and search helpers."
1958
2353
  },
1959
2354
  {
@@ -1976,7 +2371,12 @@
1976
2371
  "children",
1977
2372
  "className"
1978
2373
  ],
1979
- "description": "Editable list of text items with add/remove, paste support, and validation"
2374
+ "description": "Editable list of text items with add/remove, paste support, and validation",
2375
+ "i18nProps": {
2376
+ "InputListItems": {
2377
+ "removeAriaLabel": "string — default: \"Remove {item}\""
2378
+ }
2379
+ }
1980
2380
  },
1981
2381
  {
1982
2382
  "name": "Sidebar",
@@ -1984,21 +2384,43 @@
1984
2384
  "category": "block",
1985
2385
  "exports": [
1986
2386
  "Sidebar",
2387
+ "SidebarAccountDropdown",
2388
+ "SidebarCollapseIcon",
1987
2389
  "SidebarContent",
1988
- "SidebarHeader",
1989
2390
  "SidebarFooter",
2391
+ "SidebarGroup",
2392
+ "SidebarGroupAction",
2393
+ "SidebarGroupContent",
2394
+ "SidebarGroupLabel",
2395
+ "SidebarHeader",
2396
+ "SidebarHeaderButton",
2397
+ "SidebarInboxItem",
2398
+ "SidebarInput",
2399
+ "SidebarInset",
1990
2400
  "SidebarMenu",
2401
+ "SidebarMenuAction",
2402
+ "SidebarMenuBadge",
1991
2403
  "SidebarMenuButton",
2404
+ "SidebarMenuCollapsible",
2405
+ "SidebarMenuCollapsibleContent",
2406
+ "SidebarMenuCollapsibleTrigger",
1992
2407
  "SidebarMenuItem",
2408
+ "SidebarMenuSkeleton",
1993
2409
  "SidebarMenuSub",
1994
- "SidebarMenuAction",
1995
- "SidebarMenuBadge",
2410
+ "SidebarMenuSubButton",
2411
+ "SidebarMenuSubItem",
2412
+ "SidebarPopoverMenu",
2413
+ "SidebarPopoverMenuItem",
2414
+ "SidebarPopoverTrigger",
2415
+ "SidebarProvider",
1996
2416
  "SidebarRail",
2417
+ "SidebarSeparator",
2418
+ "SidebarSwitcher",
1997
2419
  "SidebarTrigger",
1998
- "SidebarInset"
2420
+ "useSidebar"
1999
2421
  ],
2000
2422
  "compound": true,
2001
- "dataHookRequired": false,
2423
+ "dataHookRequired": true,
2002
2424
  "variants": {
2003
2425
  "side": [
2004
2426
  "left"
@@ -2013,6 +2435,31 @@
2013
2435
  ]
2014
2436
  },
2015
2437
  "props": [],
2438
+ "i18nProps": {
2439
+ "Sidebar": {
2440
+ "mobileTitle": "string — default: \"Navigation\"",
2441
+ "mobileDescription": "string — default: \"Main navigation menu\""
2442
+ },
2443
+ "SidebarContent": {
2444
+ "ariaLabel": "string — default: \"Sidebar\""
2445
+ },
2446
+ "SidebarTrigger": {
2447
+ "toggleAriaLabel": "string — default: \"Toggle Sidebar\""
2448
+ },
2449
+ "SidebarRail": {
2450
+ "toggleAriaLabel": "string — default: \"Toggle Sidebar\""
2451
+ },
2452
+ "SidebarPopoverTrigger": {
2453
+ "triggerAriaLabel": "string — default: \"Switch workspace\""
2454
+ },
2455
+ "SidebarPopoverMenu": {
2456
+ "groupTitle": "string — default: \"Teams\"",
2457
+ "addActionLabel": "string — default: \"Add team\""
2458
+ },
2459
+ "SidebarSwitcher": {
2460
+ "triggerAriaLabel": "string — default: \"Switch workspace\""
2461
+ }
2462
+ },
2016
2463
  "description": "Complex sidebar navigation with collapsible support"
2017
2464
  }
2018
2465
  ],