@brightlocal/ui-components 3.2.0 → 3.4.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/AI_USAGE.md +10 -0
- package/README.md +3 -1
- package/component-meta.json +1458 -380
- package/deprecations.json +44 -0
- package/dist/_virtual/_rolldown/runtime.cjs +1 -0
- package/dist/accordion.cjs +1 -1
- package/dist/accordion.js +73 -102
- package/dist/alert-dialog.cjs +1 -1
- package/dist/alert-dialog.d.ts +6 -4
- package/dist/alert-dialog.d.ts.map +1 -1
- package/dist/alert-dialog.js +85 -133
- package/dist/alert.cjs +1 -1
- package/dist/alert.d.ts +4 -4
- package/dist/alert.d.ts.map +1 -1
- package/dist/alert.js +106 -168
- package/dist/aspect-ratio.cjs +1 -1
- package/dist/aspect-ratio.js +13 -16
- package/dist/avatar.cjs +1 -1
- package/dist/avatar.js +30 -45
- package/dist/badge.cjs +1 -1
- package/dist/badge.d.ts +23 -1
- package/dist/badge.d.ts.map +1 -1
- package/dist/badge.js +90 -91
- package/dist/banner.cjs +1 -1
- package/dist/banner.js +102 -148
- package/dist/blocks/empty-state.cjs +1 -1
- package/dist/blocks/empty-state.d.ts +20 -3
- package/dist/blocks/empty-state.d.ts.map +1 -1
- package/dist/blocks/empty-state.js +73 -140
- package/dist/blocks/input-list.cjs +2 -2
- package/dist/blocks/input-list.d.ts +2 -2
- package/dist/blocks/input-list.d.ts.map +1 -1
- package/dist/blocks/input-list.js +138 -178
- package/dist/blocks/progress-state.cjs +1 -1
- package/dist/blocks/progress-state.js +223 -347
- package/dist/blocks/sidebar.cjs +1 -1
- package/dist/blocks/sidebar.d.ts +11 -6
- package/dist/blocks/sidebar.d.ts.map +1 -1
- package/dist/blocks/sidebar.js +763 -1092
- package/dist/brand-illustration-motif.cjs +1 -1
- package/dist/brand-illustration-motif.js +40 -61
- package/dist/breadcrumb.cjs +1 -1
- package/dist/breadcrumb.js +62 -102
- package/dist/button-group.cjs +1 -1
- package/dist/button-group.js +23 -31
- package/dist/button.cjs +1 -1
- package/dist/button.d.ts +4 -2
- package/dist/button.d.ts.map +1 -1
- package/dist/button.js +149 -189
- package/dist/calendar.cjs +1 -1
- package/dist/calendar.d.ts +87 -3
- package/dist/calendar.d.ts.map +1 -1
- package/dist/calendar.js +116 -173
- package/dist/callout.cjs +1 -1
- package/dist/callout.js +73 -96
- package/dist/card.cjs +1 -1
- package/dist/card.d.ts +10 -4
- package/dist/card.d.ts.map +1 -1
- package/dist/card.js +233 -316
- package/dist/carousel.cjs +1 -1
- package/dist/carousel.d.ts +3 -3
- package/dist/carousel.d.ts.map +1 -1
- package/dist/carousel.js +174 -268
- package/dist/centred-layout.cjs +1 -1
- package/dist/centred-layout.js +27 -48
- package/dist/chart-empty.cjs +1 -1
- package/dist/chart-empty.js +18 -27
- package/dist/chart.cjs +7 -7
- package/dist/chart.d.ts +23 -13
- package/dist/chart.d.ts.map +1 -1
- package/dist/chart.js +445 -651
- package/dist/checkbox.cjs +1 -1
- package/dist/checkbox.js +36 -69
- package/dist/chip.cjs +1 -1
- package/dist/chip.js +116 -173
- package/dist/collapsible.cjs +1 -1
- package/dist/collapsible.d.ts.map +1 -1
- package/dist/collapsible.js +35 -41
- package/dist/combobox.cjs +3 -3
- package/dist/combobox.d.ts +14 -4
- package/dist/combobox.d.ts.map +1 -1
- package/dist/combobox.js +439 -638
- package/dist/command.cjs +1 -1
- package/dist/command.d.ts.map +1 -1
- package/dist/command.js +273 -420
- package/dist/context-menu.cjs +1 -1
- package/dist/context-menu.d.ts +5 -5
- package/dist/context-menu.d.ts.map +1 -1
- package/dist/context-menu.js +121 -191
- package/dist/data-table.cjs +1 -1
- package/dist/data-table.d.ts +280 -129
- package/dist/data-table.d.ts.map +1 -1
- package/dist/data-table.js +687 -948
- package/dist/date-picker.cjs +1 -1
- package/dist/date-picker.d.ts +15 -4
- package/dist/date-picker.d.ts.map +1 -1
- package/dist/date-picker.js +156 -231
- package/dist/delta.cjs +1 -0
- package/dist/delta.d.ts +79 -0
- package/dist/delta.d.ts.map +1 -0
- package/dist/delta.js +62 -0
- package/dist/description-list.cjs +1 -0
- package/dist/description-list.d.ts +142 -0
- package/dist/description-list.d.ts.map +1 -0
- package/dist/description-list.js +173 -0
- package/dist/description.cjs +1 -1
- package/dist/description.js +11 -20
- package/dist/dialog.cjs +1 -1
- package/dist/dialog.d.ts +1 -1
- package/dist/dialog.d.ts.map +1 -1
- package/dist/dialog.js +76 -116
- package/dist/drawer.cjs +1 -1
- package/dist/drawer.d.ts +11 -11
- package/dist/drawer.d.ts.map +1 -1
- package/dist/drawer.js +76 -134
- package/dist/dropdown-menu.cjs +1 -1
- package/dist/dropdown-menu.d.ts +6 -6
- package/dist/dropdown-menu.d.ts.map +1 -1
- package/dist/dropdown-menu.js +179 -300
- package/dist/field.cjs +1 -1
- package/dist/field.d.ts +9 -9
- package/dist/field.d.ts.map +1 -1
- package/dist/field.js +166 -286
- package/dist/global-layout.cjs +1 -1
- package/dist/global-layout.js +203 -342
- package/dist/grid.cjs +1 -1
- package/dist/grid.js +16 -29
- package/dist/header.cjs +1 -1
- package/dist/header.js +21 -38
- package/dist/height-transition.cjs +1 -1
- package/dist/height-transition.js +38 -55
- package/dist/hooks/use-breakpoint.cjs +1 -1
- package/dist/hooks/use-breakpoint.js +9 -9
- package/dist/hooks/use-debounce.cjs +1 -1
- package/dist/hooks/use-debounce.js +12 -11
- package/dist/hooks/use-delayed-pending.cjs +1 -1
- package/dist/hooks/use-delayed-pending.js +8 -9
- package/dist/hooks/use-filter-search-params.cjs +1 -0
- package/dist/hooks/use-filter-search-params.d.ts +93 -0
- package/dist/hooks/use-filter-search-params.d.ts.map +1 -0
- package/dist/hooks/use-filter-search-params.js +122 -0
- package/dist/hooks/use-mobile.cjs +1 -1
- package/dist/hooks/use-mobile.js +6 -6
- package/dist/hooks/use-overlay-pointer-lock.cjs +1 -1
- package/dist/hooks/use-overlay-pointer-lock.js +8 -9
- package/dist/hooks/use-prefers-reduced-motion.cjs +1 -1
- package/dist/hooks/use-prefers-reduced-motion.js +5 -8
- package/dist/hover-card.cjs +1 -1
- package/dist/hover-card.d.ts +1 -1
- package/dist/hover-card.d.ts.map +1 -1
- package/dist/hover-card.js +30 -62
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +658 -614
- package/dist/info-tooltip.cjs +1 -1
- package/dist/info-tooltip.js +22 -36
- package/dist/input-chip.cjs +1 -1
- package/dist/input-chip.d.ts +32 -3
- package/dist/input-chip.d.ts.map +1 -1
- package/dist/input-chip.js +181 -230
- package/dist/input-group.cjs +1 -1
- package/dist/input-group.js +174 -221
- package/dist/input-otp.cjs +1 -1
- package/dist/input-otp.d.ts +3 -3
- package/dist/input-otp.d.ts.map +1 -1
- package/dist/input-otp.js +102 -146
- package/dist/input-password.cjs +1 -1
- package/dist/input-password.d.ts +12 -16
- package/dist/input-password.d.ts.map +1 -1
- package/dist/input-password.js +139 -171
- package/dist/input.cjs +1 -1
- package/dist/input.d.ts.map +1 -1
- package/dist/input.js +51 -73
- package/dist/label.cjs +1 -1
- package/dist/label.js +20 -38
- package/dist/lib/block-illustration.cjs +1 -1
- package/dist/lib/block-illustration.d.ts +1 -1
- package/dist/lib/block-illustration.d.ts.map +1 -1
- package/dist/lib/block-illustration.js +16 -18
- package/dist/lib/compose-event-handlers.cjs +1 -0
- package/dist/lib/compose-event-handlers.d.ts +9 -0
- package/dist/lib/compose-event-handlers.d.ts.map +1 -0
- package/dist/lib/compose-event-handlers.js +8 -0
- package/dist/lib/download-file.cjs +1 -0
- package/dist/lib/download-file.d.ts +14 -0
- package/dist/lib/download-file.d.ts.map +1 -0
- package/dist/lib/download-file.js +40 -0
- package/dist/lib/empty-canvas.cjs +1 -1
- package/dist/lib/empty-canvas.js +28 -56
- package/dist/lib/empty-chip.cjs +1 -1
- package/dist/lib/empty-chip.d.ts +14 -3
- package/dist/lib/empty-chip.d.ts.map +1 -1
- package/dist/lib/empty-chip.js +15 -11
- package/dist/lib/field-aria.cjs +1 -0
- package/dist/lib/field-aria.d.ts +34 -0
- package/dist/lib/field-aria.d.ts.map +1 -0
- package/dist/lib/field-aria.js +52 -0
- package/dist/lib/image-file-info.cjs +1 -0
- package/dist/lib/image-file-info.d.ts +25 -0
- package/dist/lib/image-file-info.d.ts.map +1 -0
- package/dist/lib/image-file-info.js +67 -0
- package/dist/lib/media-viewer-content.cjs +1 -0
- package/dist/lib/media-viewer-content.d.ts +102 -0
- package/dist/lib/media-viewer-content.d.ts.map +1 -0
- package/dist/lib/media-viewer-content.js +650 -0
- package/dist/lib/media-viewer-internal.cjs +1 -0
- package/dist/lib/media-viewer-internal.d.ts +98 -0
- package/dist/lib/media-viewer-internal.d.ts.map +1 -0
- package/dist/lib/media-viewer-internal.js +61 -0
- package/dist/lib/media-viewer-motion.cjs +1 -0
- package/dist/lib/media-viewer-motion.d.ts +40 -0
- package/dist/lib/media-viewer-motion.d.ts.map +1 -0
- package/dist/lib/media-viewer-motion.js +37 -0
- package/dist/lib/motion.cjs +1 -1
- package/dist/lib/motion.d.ts +8 -0
- package/dist/lib/motion.d.ts.map +1 -1
- package/dist/lib/motion.js +14 -8
- package/dist/lib/optical-center.cjs +1 -1
- package/dist/lib/optical-center.d.ts +1 -1
- package/dist/lib/optical-center.d.ts.map +1 -1
- package/dist/lib/optical-center.js +12 -5
- package/dist/lib/spring-settle.cjs +1 -1
- package/dist/lib/spring-settle.js +1 -1
- package/dist/lib/table-internal.cjs +1 -0
- package/dist/lib/table-internal.d.ts +62 -0
- package/dist/lib/table-internal.d.ts.map +1 -0
- package/dist/lib/table-internal.js +18 -0
- package/dist/lib/use-controllable.cjs +1 -0
- package/dist/lib/use-controllable.d.ts +12 -0
- package/dist/lib/use-controllable.d.ts.map +1 -0
- package/dist/lib/use-controllable.js +15 -0
- package/dist/lib/use-dev-warning.cjs +1 -1
- package/dist/lib/utils.cjs +1 -1
- package/dist/lib/utils.js +26 -33
- package/dist/link.cjs +1 -1
- package/dist/link.d.ts +1 -1
- package/dist/link.js +78 -124
- package/dist/list.cjs +1 -1
- package/dist/list.d.ts +224 -39
- package/dist/list.d.ts.map +1 -1
- package/dist/list.js +323 -171
- package/dist/loading.cjs +1 -1
- package/dist/loading.js +124 -151
- package/dist/logo-mark.cjs +1 -0
- package/dist/logo-mark.d.ts +79 -0
- package/dist/logo-mark.d.ts.map +1 -0
- package/dist/logo-mark.js +219 -0
- package/dist/logo.cjs +1 -1
- package/dist/logo.d.ts +1 -1
- package/dist/logo.d.ts.map +1 -1
- package/dist/logo.js +51 -87
- package/dist/map.cjs +1 -1
- package/dist/map.d.ts.map +1 -1
- package/dist/map.js +390 -586
- package/dist/media-empty.cjs +1 -1
- package/dist/media-empty.js +27 -42
- package/dist/media-viewer.cjs +1 -0
- package/dist/media-viewer.d.ts +224 -0
- package/dist/media-viewer.d.ts.map +1 -0
- package/dist/media-viewer.js +295 -0
- package/dist/menubar.cjs +1 -1
- package/dist/menubar.d.ts +14 -14
- package/dist/menubar.d.ts.map +1 -1
- package/dist/menubar.js +130 -267
- package/dist/multi-select-filter.cjs +1 -1
- package/dist/multi-select-filter.d.ts +9 -1
- package/dist/multi-select-filter.d.ts.map +1 -1
- package/dist/multi-select-filter.js +357 -446
- package/dist/navigation-menu.cjs +1 -1
- package/dist/navigation-menu.js +108 -172
- package/dist/pagination.cjs +1 -1
- package/dist/pagination.d.ts +36 -12
- package/dist/pagination.d.ts.map +1 -1
- package/dist/pagination.js +208 -281
- package/dist/popover.cjs +1 -1
- package/dist/popover.d.ts +1 -1
- package/dist/popover.d.ts.map +1 -1
- package/dist/popover.js +34 -45
- package/dist/progress.cjs +1 -1
- package/dist/progress.d.ts +17 -2
- package/dist/progress.d.ts.map +1 -1
- package/dist/progress.js +116 -162
- package/dist/radio-group.cjs +1 -1
- package/dist/radio-group.js +90 -146
- package/dist/rating.cjs +1 -1
- package/dist/rating.d.ts +80 -13
- package/dist/rating.d.ts.map +1 -1
- package/dist/rating.js +70 -65
- package/dist/relative-date.cjs +1 -1
- package/dist/relative-date.d.ts.map +1 -1
- package/dist/relative-date.js +73 -89
- package/dist/resizable.cjs +1 -1
- package/dist/resizable.d.ts +39 -23
- package/dist/resizable.d.ts.map +1 -1
- package/dist/resizable.js +42 -44
- package/dist/result-count.cjs +1 -0
- package/dist/result-count.d.ts +110 -0
- package/dist/result-count.d.ts.map +1 -0
- package/dist/result-count.js +49 -0
- package/dist/route-progress.cjs +1 -1
- package/dist/route-progress.js +59 -102
- package/dist/scroll-area.cjs +1 -1
- package/dist/scroll-area.d.ts +9 -1
- package/dist/scroll-area.d.ts.map +1 -1
- package/dist/scroll-area.js +44 -79
- package/dist/select.cjs +2 -2
- package/dist/select.d.ts +10 -10
- package/dist/select.d.ts.map +1 -1
- package/dist/select.js +118 -238
- package/dist/separator.cjs +1 -1
- package/dist/separator.js +90 -78
- package/dist/sheet.cjs +1 -1
- package/dist/sheet.d.ts +8 -5
- package/dist/sheet.d.ts.map +1 -1
- package/dist/sheet.js +250 -317
- package/dist/single-select-filter.cjs +1 -1
- package/dist/single-select-filter.d.ts +32 -0
- package/dist/single-select-filter.d.ts.map +1 -1
- package/dist/single-select-filter.js +201 -203
- package/dist/skeleton.cjs +1 -1
- package/dist/skeleton.js +24 -38
- package/dist/slider.cjs +1 -1
- package/dist/slider.js +51 -81
- package/dist/sonner.cjs +1 -1
- package/dist/sonner.d.ts +1 -1
- package/dist/sonner.d.ts.map +1 -1
- package/dist/sonner.js +101 -125
- package/dist/spinner.cjs +1 -1
- package/dist/spinner.js +22 -31
- package/dist/split-layout.cjs +1 -1
- package/dist/split-layout.js +52 -101
- package/dist/status.cjs +1 -0
- package/dist/status.d.ts +51 -0
- package/dist/status.d.ts.map +1 -0
- package/dist/status.js +60 -0
- package/dist/stepper.cjs +1 -1
- package/dist/stepper.js +184 -316
- package/dist/switch.cjs +1 -1
- package/dist/switch.js +17 -32
- package/dist/table.cjs +1 -1
- package/dist/table.d.ts +103 -30
- package/dist/table.d.ts.map +1 -1
- package/dist/table.js +170 -209
- package/dist/tabs.cjs +1 -1
- package/dist/tabs.d.ts.map +1 -1
- package/dist/tabs.js +102 -147
- package/dist/text-reveal-motion.cjs +1 -1
- package/dist/text-reveal-motion.js +307 -363
- package/dist/textarea.cjs +1 -1
- package/dist/textarea.d.ts.map +1 -1
- package/dist/textarea.js +22 -35
- package/dist/toggle-group.cjs +1 -1
- package/dist/toggle-group.js +43 -62
- package/dist/toggle.cjs +1 -1
- package/dist/toggle.js +34 -46
- package/dist/tooltip.cjs +1 -1
- package/dist/tooltip.d.ts +2 -2
- package/dist/tooltip.d.ts.map +1 -1
- package/dist/tooltip.js +157 -249
- package/dist/typography-heading.cjs +1 -1
- package/dist/typography-heading.js +25 -61
- package/dist/typography-text.cjs +1 -1
- package/dist/typography-text.js +27 -57
- package/dist/typography.cjs +1 -1
- package/dist/typography.js +132 -340
- package/package.json +47 -47
- package/src/blocks/empty-state.tsx +34 -18
- package/src/blocks/input-list.tsx +14 -9
- package/src/blocks/sidebar.tsx +86 -31
- package/src/components/accordion.tsx +1 -1
- package/src/components/alert-dialog.tsx +4 -2
- package/src/components/badge.tsx +127 -15
- package/src/components/breadcrumb.tsx +1 -1
- package/src/components/button.tsx +8 -6
- package/src/components/calendar.tsx +155 -9
- package/src/components/card.tsx +63 -10
- package/src/components/carousel.tsx +4 -1
- package/src/components/chart.tsx +151 -17
- package/src/components/checkbox.tsx +1 -1
- package/src/components/collapsible.tsx +4 -1
- package/src/components/combobox.tsx +40 -7
- package/src/components/command.tsx +9 -10
- package/src/components/context-menu.tsx +4 -4
- package/src/components/data-table.tsx +619 -237
- package/src/components/date-picker.tsx +31 -4
- package/src/components/delta.tsx +217 -0
- package/src/components/description-list.tsx +445 -0
- package/src/components/drawer.tsx +5 -5
- package/src/components/dropdown-menu.tsx +4 -4
- package/src/components/field.tsx +36 -15
- package/src/components/global-layout.tsx +1 -1
- package/src/components/input-chip.tsx +51 -7
- package/src/components/input-group.tsx +1 -1
- package/src/components/input-password.tsx +15 -19
- package/src/components/input.tsx +10 -1
- package/src/components/list.tsx +695 -72
- package/src/components/logo-mark.tsx +345 -0
- package/src/components/map.tsx +18 -20
- package/src/components/media-viewer.tsx +908 -0
- package/src/components/multi-select-filter.tsx +255 -121
- package/src/components/navigation-menu.tsx +2 -2
- package/src/components/pagination.tsx +86 -26
- package/src/components/progress.tsx +91 -23
- package/src/components/rating.tsx +200 -74
- package/src/components/relative-date.tsx +19 -11
- package/src/components/resizable.tsx +86 -33
- package/src/components/result-count.tsx +253 -0
- package/src/components/scroll-area.tsx +31 -5
- package/src/components/select.tsx +2 -2
- package/src/components/sheet.tsx +14 -4
- package/src/components/single-select-filter.tsx +136 -41
- package/src/components/slider.tsx +2 -2
- package/src/components/status.tsx +162 -0
- package/src/components/switch.tsx +1 -1
- package/src/components/table.tsx +278 -106
- package/src/components/tabs.tsx +1 -0
- package/src/components/textarea.tsx +20 -2
- package/src/components/toggle.tsx +2 -2
- package/src/components/tooltip.tsx +11 -20
- package/src/hooks/use-filter-search-params.ts +302 -0
- package/src/index.ts +7 -0
- package/src/lib/compose-event-handlers.ts +14 -0
- package/src/lib/download-file.ts +61 -0
- package/src/lib/empty-chip.tsx +52 -0
- package/src/lib/field-aria.tsx +97 -0
- package/src/lib/image-file-info.ts +102 -0
- package/src/lib/media-viewer-content.tsx +1587 -0
- package/src/lib/media-viewer-internal.tsx +191 -0
- package/src/lib/media-viewer-motion.ts +120 -0
- package/src/lib/motion.ts +9 -0
- package/src/lib/table-internal.ts +74 -0
- package/src/lib/use-controllable.ts +43 -0
- package/src/lib/empty-chip.ts +0 -24
package/component-meta.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@brightlocal/ui-components",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.4.0",
|
|
4
4
|
"description": "Machine-readable registry of all components in the BrightLocal Design System",
|
|
5
5
|
"components": [
|
|
6
6
|
{
|
|
@@ -177,7 +177,8 @@
|
|
|
177
177
|
"figmaOnly": []
|
|
178
178
|
},
|
|
179
179
|
"whenToUse": [
|
|
180
|
-
"
|
|
180
|
+
"Failures on our side that must stay visible: a server error (5xx), a broken connection (Destructive)",
|
|
181
|
+
"Refused or blocked actions the person can retry or change: no access, too many requests, a limit (Warning)",
|
|
181
182
|
"Cautionary heads-ups before anything fails (Warning)",
|
|
182
183
|
"Helpful, neutral information tied to the page (Info)",
|
|
183
184
|
"Persistent success confirmation that stays until no longer true (Success)"
|
|
@@ -203,6 +204,7 @@
|
|
|
203
204
|
"variants": {
|
|
204
205
|
"variant": [
|
|
205
206
|
"primary",
|
|
207
|
+
"secondary",
|
|
206
208
|
"destructive"
|
|
207
209
|
]
|
|
208
210
|
},
|
|
@@ -210,6 +212,14 @@
|
|
|
210
212
|
"open",
|
|
211
213
|
"onOpenChange"
|
|
212
214
|
],
|
|
215
|
+
"decisions": [
|
|
216
|
+
{
|
|
217
|
+
"date": "2026-10-30",
|
|
218
|
+
"decision": "AlertDialogAction takes secondary as well as primary and destructive. Destructive confirms deleting what was saved; secondary (the grey button) confirms a risky action that leaves saved data untouched, such as discarding unsaved changes (Leave without saving). The safe choice is the cancel button. A warning (amber) button variant was proposed and dropped on team feedback: Button variants stay primary, secondary, destructive, outline and ghost. The Figma Alert Dialog set only has Primary and Destructive, so Secondary is code-first until design adds it.",
|
|
219
|
+
"why": "Red on a leave-page confirmation says the saved record is being destroyed, when only an unsaved edit is lost, and an orange button is unfamiliar and hard to read. Grey secondary keeps the dialog calm while Cancel stays the safe choice (DS-899).",
|
|
220
|
+
"ticket": "DS-899"
|
|
221
|
+
}
|
|
222
|
+
],
|
|
213
223
|
"description": "Modal confirmation dialogs",
|
|
214
224
|
"aliases": [
|
|
215
225
|
"confirmation dialog",
|
|
@@ -219,7 +229,8 @@
|
|
|
219
229
|
"whenToUse": [
|
|
220
230
|
"Confirming irreversible actions (permanent delete of an account or location)",
|
|
221
231
|
"Serious consequences needing an explicit confirm-or-cancel choice",
|
|
222
|
-
"Forcing a deliberate pause before something irreversible happens"
|
|
232
|
+
"Forcing a deliberate pause before something irreversible happens",
|
|
233
|
+
"Leaving a form with unsaved changes (confirm with the secondary variant)"
|
|
223
234
|
],
|
|
224
235
|
"doNotUseFor": [
|
|
225
236
|
"easily undoable actions (use Sonner with an Undo action)",
|
|
@@ -434,27 +445,32 @@
|
|
|
434
445
|
"primary",
|
|
435
446
|
"secondary",
|
|
436
447
|
"destructive",
|
|
437
|
-
"outline"
|
|
448
|
+
"outline",
|
|
449
|
+
"highlight-gold"
|
|
438
450
|
]
|
|
439
451
|
},
|
|
440
452
|
"props": [
|
|
441
453
|
"asChild",
|
|
442
|
-
"srLabel"
|
|
454
|
+
"srLabel",
|
|
455
|
+
"iconOnly",
|
|
456
|
+
"truncate",
|
|
457
|
+
"maxWidth"
|
|
443
458
|
],
|
|
444
459
|
"description": "Status badges and labels",
|
|
445
460
|
"aliases": [
|
|
446
461
|
"tag",
|
|
447
462
|
"chip",
|
|
448
463
|
"pill",
|
|
449
|
-
"label"
|
|
450
|
-
"status indicator"
|
|
464
|
+
"label"
|
|
451
465
|
],
|
|
452
466
|
"whenToUse": [
|
|
453
467
|
"Status labels like \"New,\" \"Active,\" \"Draft,\" or \"Error\"",
|
|
454
468
|
"Numeric counts on icons or navigation items",
|
|
455
|
-
"Highlighting a plan tier or account type"
|
|
469
|
+
"Highlighting a plan tier or account type",
|
|
470
|
+
"A top or exceptional outcome (variant highlight-gold), e.g. the knowledge panel mark — icon-only via iconOnly + srLabel"
|
|
456
471
|
],
|
|
457
472
|
"doNotUseFor": [
|
|
473
|
+
"highlight-gold as a caution or status — gold is not a warning (use Alert's Warning)",
|
|
458
474
|
"removable tags or filter values (use Chip)",
|
|
459
475
|
"neutral or positive statuses styled as Destructive",
|
|
460
476
|
"page-level cautions rather than failures (use Alert's Warning variant)"
|
|
@@ -501,6 +517,20 @@
|
|
|
501
517
|
"unmappedExports": [],
|
|
502
518
|
"figmaOnly": []
|
|
503
519
|
},
|
|
520
|
+
"decisions": [
|
|
521
|
+
{
|
|
522
|
+
"decision": "Truncation uses auto-tooltip (Chip pattern), not consumer-composed Tooltip",
|
|
523
|
+
"why": "Chip already ships scrollWidth > clientWidth detection + conditional Tooltip; reusing the same pattern keeps the DS consistent and lets consumers opt in with a single prop instead of composing Tooltip externally",
|
|
524
|
+
"date": "2026-10-31",
|
|
525
|
+
"ticket": "DS-1223"
|
|
526
|
+
},
|
|
527
|
+
{
|
|
528
|
+
"decision": "truncate prop is ignored with asChild",
|
|
529
|
+
"why": "Slot renders the consumer's element; injecting a label span and resize listener would break the contract — truncation must be applied by the consumer on their own element",
|
|
530
|
+
"date": "2026-10-31",
|
|
531
|
+
"ticket": "DS-1223"
|
|
532
|
+
}
|
|
533
|
+
],
|
|
504
534
|
"i18nProps": {
|
|
505
535
|
"Badge": {
|
|
506
536
|
"srLabel": "string — no default; screen-reader phrase replacing a bare numeral (\"3 active\"); ignored with asChild"
|
|
@@ -708,8 +738,7 @@
|
|
|
708
738
|
"destructive",
|
|
709
739
|
"outline",
|
|
710
740
|
"secondary",
|
|
711
|
-
"ghost"
|
|
712
|
-
"warning"
|
|
741
|
+
"ghost"
|
|
713
742
|
],
|
|
714
743
|
"size": [
|
|
715
744
|
"default",
|
|
@@ -725,6 +754,14 @@
|
|
|
725
754
|
"type",
|
|
726
755
|
"ariaLabel"
|
|
727
756
|
],
|
|
757
|
+
"decisions": [
|
|
758
|
+
{
|
|
759
|
+
"date": "2026-10-30",
|
|
760
|
+
"decision": "The warning variant is removed. Button has five variants: primary, secondary, destructive, outline, ghost. A moderate-risk action, such as discarding unsaved changes, uses secondary; destructive is for deleting what was saved.",
|
|
761
|
+
"why": "Design review: an orange or yellow button is unfamiliar and unnecessary next to primary, secondary, destructive, outline and ghost. Nothing used it: no greenfield code, no prototype and no Figma frame outside the Button page itself (DS-899).",
|
|
762
|
+
"ticket": "DS-899"
|
|
763
|
+
}
|
|
764
|
+
],
|
|
728
765
|
"description": "Primary interactive button with variants",
|
|
729
766
|
"aliases": [
|
|
730
767
|
"btn",
|
|
@@ -737,7 +774,7 @@
|
|
|
737
774
|
"Triggering an action (submit, save, delete, open)",
|
|
738
775
|
"The single most important action on a screen or dialog (Primary)",
|
|
739
776
|
"Supporting or low-emphasis actions (Secondary, Outline, Ghost)",
|
|
740
|
-
"Risky or destructive actions signaled by color (
|
|
777
|
+
"Risky or destructive actions signaled by color (Destructive; Secondary for a moderate one, like Discard changes)"
|
|
741
778
|
],
|
|
742
779
|
"doNotUseFor": [
|
|
743
780
|
"navigation to another page (use Link)",
|
|
@@ -866,18 +903,25 @@
|
|
|
866
903
|
"import": "@brightlocal/ui-components/calendar",
|
|
867
904
|
"category": "form",
|
|
868
905
|
"exports": [
|
|
869
|
-
"Calendar"
|
|
906
|
+
"Calendar",
|
|
907
|
+
"CalendarPresets"
|
|
870
908
|
],
|
|
871
|
-
"compound":
|
|
909
|
+
"compound": true,
|
|
872
910
|
"dataHookRequired": true,
|
|
873
911
|
"variants": {},
|
|
874
912
|
"props": [
|
|
875
913
|
"numberOfMonths",
|
|
914
|
+
"fullWidth",
|
|
876
915
|
"mode",
|
|
877
916
|
"selected",
|
|
878
917
|
"onSelect",
|
|
879
918
|
"disabled"
|
|
880
919
|
],
|
|
920
|
+
"i18nProps": {
|
|
921
|
+
"CalendarPresets": {
|
|
922
|
+
"groupLabel": "string — default: \"Quick picks\"; accessible name of the presets group"
|
|
923
|
+
}
|
|
924
|
+
},
|
|
881
925
|
"description": "Date selection calendar (wraps react-day-picker)",
|
|
882
926
|
"figma": {
|
|
883
927
|
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
@@ -896,7 +940,12 @@
|
|
|
896
940
|
]
|
|
897
941
|
}
|
|
898
942
|
],
|
|
899
|
-
"unmappedExports": [
|
|
943
|
+
"unmappedExports": [
|
|
944
|
+
{
|
|
945
|
+
"export": "CalendarPresets",
|
|
946
|
+
"reason": "No Figma node yet - the 'With Presets' type in Figma is drawn by hand; needs a Figma branch (DS-1201) before mapping"
|
|
947
|
+
}
|
|
948
|
+
],
|
|
900
949
|
"figmaOnly": [
|
|
901
950
|
{
|
|
902
951
|
"nodeId": "234:196",
|
|
@@ -1007,7 +1056,7 @@
|
|
|
1007
1056
|
"props": [
|
|
1008
1057
|
"maxWidth"
|
|
1009
1058
|
],
|
|
1010
|
-
"description": "Content container with consistent styling. Full-width by default — constrain width via className (e.g., className='max-w-sm'). 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; 'data' uses the report-page scale (DS-989): fixed 24px horizontal padding, a header with 16px vertical padding, 24px section spacing below it (pair with CardTitle size='small'). CardHeader's divider prop closes the header with its own full-width bottom border in every density — the header pads its bottom by the density's spacing, and flush content right after sits on the line. variant='border' uses the card surface (bg-card: white in light mode, neutral-900 in dark) so it lifts off the off-white page; variant='filled' uses the muted fill (bg-muted). For cards carrying a filter row and a data view. CardContent accepts a flush prop for edge-to-edge tables/maps inside a filled or border card (the card keeps its surface and border). CardToolbar puts the filter row (search — Input, InputGroup or DataTableSearch — capped at 360px, then filters, 8px gap; styles direct children only) in the header, for everything that narrows what the card shows; pagination stays in a DataTableToolbar beside the table; CardMetric shows a value + trend badge opposite the title. CardHeader takes align ('left' | 'center' | 'right') for header layout; CardDescription takes its own align with the same values to pin the description's text alignment when it would otherwise inherit it (e.g. centred inside a button trigger) — omitted, it inherits as before. CardHeader's sticky prop pins the header while a tall card scrolls
|
|
1059
|
+
"description": "Content container with consistent styling. Full-width by default — constrain width via className (e.g., className='max-w-sm'). 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; 'data' uses the report-page scale (DS-989): fixed 24px horizontal padding, a header with 16px vertical padding, 24px section spacing below it (pair with CardTitle size='small'). CardHeader's divider prop closes the header with its own full-width bottom border in every density — the header pads its bottom by the density's spacing, and flush content right after sits on the line. variant='border' uses the card surface (bg-card: white in light mode, neutral-900 in dark) so it lifts off the off-white page; variant='filled' uses the muted fill (bg-muted). For cards carrying a filter row and a data view. CardContent accepts a flush prop for edge-to-edge tables/maps inside a filled or border card (the card keeps its surface and border). CardToolbar puts the filter row (search — Input, InputGroup or DataTableSearch — capped at 360px, then filters, 8px gap; styles direct children only) in the header, for everything that narrows what the card shows; pagination stays in a DataTableToolbar beside the table; CardMetric shows a value + trend badge opposite the title. CardHeader takes align ('left' | 'center' | 'right') for header layout; CardDescription takes its own align with the same values to pin the description's text alignment when it would otherwise inherit it (e.g. centred inside a button trigger) — omitted, it inherits as before. CardHeader's sticky prop pins the header to the top edge of its scroll container (page, Sheet, Dialog or any scroll box) while a tall card scrolls, with no gap above it (DS-1211), painting the card's surface so content never shows through.",
|
|
1011
1060
|
"aliases": [
|
|
1012
1061
|
"container",
|
|
1013
1062
|
"panel",
|
|
@@ -1130,7 +1179,27 @@
|
|
|
1130
1179
|
"reason": "Figma demo helper"
|
|
1131
1180
|
}
|
|
1132
1181
|
]
|
|
1133
|
-
}
|
|
1182
|
+
},
|
|
1183
|
+
"decisions": [
|
|
1184
|
+
{
|
|
1185
|
+
"date": "2026-10-01",
|
|
1186
|
+
"decision": "Card follows shadcn roles: variant=\"border\" is bg-card (white), variant=\"filled\" is bg-muted. There is no surface-* token layer.",
|
|
1187
|
+
"why": "A variant is a recipe of semantic roles; a new token is added only when no role fits.",
|
|
1188
|
+
"ticket": "DS-989"
|
|
1189
|
+
}
|
|
1190
|
+
],
|
|
1191
|
+
"ruledOut": [
|
|
1192
|
+
{
|
|
1193
|
+
"option": "A surface-raised / surface-* token for cards",
|
|
1194
|
+
"why": "It created a second colour vocabulary next to background, card and popover; it was added and then removed.",
|
|
1195
|
+
"ticket": "DS-989"
|
|
1196
|
+
},
|
|
1197
|
+
{
|
|
1198
|
+
"option": "popover as the card colour",
|
|
1199
|
+
"why": "Cards merge with popovers in dark mode.",
|
|
1200
|
+
"ticket": "DS-989"
|
|
1201
|
+
}
|
|
1202
|
+
]
|
|
1134
1203
|
},
|
|
1135
1204
|
{
|
|
1136
1205
|
"name": "Carousel",
|
|
@@ -1357,12 +1426,25 @@
|
|
|
1357
1426
|
},
|
|
1358
1427
|
"props": [
|
|
1359
1428
|
"config",
|
|
1360
|
-
"id"
|
|
1429
|
+
"id",
|
|
1430
|
+
"width",
|
|
1431
|
+
"height",
|
|
1432
|
+
"minWidth",
|
|
1433
|
+
"minHeight",
|
|
1434
|
+
"maxHeight"
|
|
1361
1435
|
],
|
|
1362
1436
|
"hooks": [
|
|
1363
1437
|
"useChart"
|
|
1364
1438
|
],
|
|
1365
1439
|
"description": "Data visualization wrapper for Recharts. Legends are composable: ChartLegendContent renders Recharts' payload inside a chart (with sortBy, showValue/valueKey, renderItem); ChartLegendList + ChartLegendItem compose a legend beside a chart — vertical with values next to a donut, shared across charts, or a row of toggles/popover triggers via asChild. size sm (12px chart chrome, default) or md (14px key read as content, 10px swatch). Item states: muted = de-emphasised but still drawn (a filter focused elsewhere); hidden = switched off, faded + struck label, never colour alone.",
|
|
1440
|
+
"decisions": [
|
|
1441
|
+
{
|
|
1442
|
+
"date": "2026-10-22",
|
|
1443
|
+
"decision": "A numeric height prop auto-switches the wrapper from aspect-video to aspect-auto and sets the height on the wrapper div, so the container takes exactly the chart's height with no empty gap.",
|
|
1444
|
+
"why": "A percent-string height keeps aspect-video because the wrapper needs intrinsic sizing from the aspect ratio.",
|
|
1445
|
+
"ticket": "DS-1051"
|
|
1446
|
+
}
|
|
1447
|
+
],
|
|
1366
1448
|
"i18nProps": {
|
|
1367
1449
|
"ChartLegendList": {
|
|
1368
1450
|
"ariaLabel": "string — default: \"Chart legend\""
|
|
@@ -2173,10 +2255,16 @@
|
|
|
2173
2255
|
},
|
|
2174
2256
|
"DataTablePagination": {
|
|
2175
2257
|
"ariaLabel": "string — default: \"Table pagination\"",
|
|
2176
|
-
"renderRowCount": "
|
|
2258
|
+
"renderRowCount": "render prop — plain-text escape hatch; prefer rowCountLabel",
|
|
2259
|
+
"rowCountLabel": "string — default: \"{from} to {to} of {total} results\"",
|
|
2260
|
+
"rowCountLabelOne": "string — default: \"{from} to {to} of {total} result\"; used at total === 1",
|
|
2261
|
+
"rowCountEmptyLabel": "string — default: \"No results\"; screen-reader-only at zero rows"
|
|
2177
2262
|
},
|
|
2178
2263
|
"DataTablePaginationRowCount": {
|
|
2179
|
-
"renderText": "
|
|
2264
|
+
"renderText": "render prop — plain-text escape hatch; prefer label",
|
|
2265
|
+
"label": "string — default: \"{from} to {to} of {total} results\"",
|
|
2266
|
+
"labelOne": "string — default: \"{from} to {to} of {total} result\"; used at total === 1",
|
|
2267
|
+
"emptyLabel": "string — default: \"No results\"; screen-reader-only at zero rows"
|
|
2180
2268
|
},
|
|
2181
2269
|
"DataTableSelectAllCheckbox": {
|
|
2182
2270
|
"selectAllAriaLabel": "string — default: \"Select all\""
|
|
@@ -2195,7 +2283,7 @@
|
|
|
2195
2283
|
"children": "React.ReactNode | ((info: { selectedCount: number; totalCount: number }) => React.ReactNode) — default: \"{selectedCount} of {totalCount} row(s) selected.\""
|
|
2196
2284
|
}
|
|
2197
2285
|
},
|
|
2198
|
-
"description": "Composable data table built on TanStack Table. Exposes `useDataTable` hook + `DataTable` / `VirtualizedDataTable` renderers + toolbar layout + pagination and search helpers. Compose the table and its companions (DataTableToolbar rows, bulk actions) as ONE slot — a single flex-column wrapper — inside gapped parents like DialogContent or Card, so the parent's gap applies around the table block, not between the toolbars and the table; the toolbars' built-in padding provides the internal spacing. noResultsMessage accepts a ReactNode as well as a string: pass an EmptyState for a collection that is empty, and keep a one-line string for a collection that is merely filtered — the reader typed the query and wants its outcome, not an onboarding block. The cell is a polite live region either way. The component's outer wrapper is its single scroll container for both axes (DS-912): bound the height through className (`max-h-*` for a fixed cap, `min-h-0 flex-1` inside a height-capped parent like a dialog body) and stickyHeader keeps the column headers pinned while the rows scroll — no internal slot targeting needed. With stickyHeader, minWidth, or scrollRegionLabel set (and always on VirtualizedDataTable) the wrapper is a focusable scroll region (role=region + tabIndex, labelled by scrollRegionLabel) so keyboard users can scroll the rows — pass scrollRegionLabel to opt in when the height is capped via className with the header deliberately left unpinned.",
|
|
2286
|
+
"description": "Composable data table built on TanStack Table. Exposes `useDataTable` hook + `DataTable` / `VirtualizedDataTable` renderers + toolbar layout + pagination and search helpers. Compose the table and its companions (DataTableToolbar rows, bulk actions) as ONE slot — a single flex-column wrapper — inside gapped parents like DialogContent or Card, so the parent's gap applies around the table block, not between the toolbars and the table; the toolbars' built-in padding provides the internal spacing. noResultsMessage accepts a ReactNode as well as a string: pass an EmptyState for a collection that is empty, and keep a one-line string for a collection that is merely filtered — the reader typed the query and wants its outcome, not an onboarding block. The cell is a polite live region either way. The component's outer wrapper is its single scroll container for both axes (DS-912): bound the height through className (`max-h-*` for a fixed cap, `min-h-0 flex-1` inside a height-capped parent like a dialog body) and stickyHeader keeps the column headers pinned while the rows scroll — no internal slot targeting needed. With stickyHeader, minWidth, or scrollRegionLabel set (and always on VirtualizedDataTable) the wrapper is a focusable scroll region (role=region + tabIndex, labelled by scrollRegionLabel) so keyboard users can scroll the rows — pass scrollRegionLabel to opt in when the height is capped via className with the header deliberately left unpinned. To keep the row's name in view while a wide table scrolls sideways (minWidth), set `meta: { pinned: \"left\" }` on ONE column definition (normally the first): its header and body cells become sticky at the left edge with an opaque background that follows the row state (selected, expanded, sub-row) and a divider on the pinned edge, and it works with stickyHeader (DS-1205).",
|
|
2199
2287
|
"figma": {
|
|
2200
2288
|
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
2201
2289
|
"status": "code-only",
|
|
@@ -2218,6 +2306,44 @@
|
|
|
2218
2306
|
"ticket": "DS-912",
|
|
2219
2307
|
"workaround": "Set stickyHeader on height-capped tables (almost always wanted anyway); if the header must scroll away, own the scrolling yourself: wrap the table in your own max-h-* overflow-y-auto container carrying role=\"region\", an aria-label, and tabIndex={0} (arrow keys only scroll the focused element or an ancestor, so the semantics must sit on the element that scrolls), and leave className un-capped"
|
|
2220
2308
|
}
|
|
2309
|
+
],
|
|
2310
|
+
"decisions": [
|
|
2311
|
+
{
|
|
2312
|
+
"date": "2026-09-11",
|
|
2313
|
+
"decision": "enableRowSelection accepts a per-row predicate; selection caps are expressed through it.",
|
|
2314
|
+
"why": "Individual rows must be blockable from selection, and the predicate matches TanStack's own boolean | (row) => boolean.",
|
|
2315
|
+
"ticket": "DS-901"
|
|
2316
|
+
},
|
|
2317
|
+
{
|
|
2318
|
+
"date": "2026-10-31",
|
|
2319
|
+
"decision": "DataTablePagination's row count delegates to ResultCount in its range form; the default wording is the range template \"{from} to {to} of {total} results\", named via rowCountLabel.",
|
|
2320
|
+
"why": "One count per collection with one wording; renderRowCount stays only as a plain-text escape hatch.",
|
|
2321
|
+
"ticket": "DS-973"
|
|
2322
|
+
},
|
|
2323
|
+
{
|
|
2324
|
+
"date": "2026-11-02",
|
|
2325
|
+
"decision": "DataTableSearch accepts `disabled` (initial load — no data to search) and forwards its ref to the inner input. `disabled` dims the group and hides the clear button via existing InputGroup infrastructure; `loading` (refetch — input stays editable) remains a separate concern.",
|
|
2326
|
+
"why": "Sibling toolbar filters (SingleSelectFilter, MultiSelectFilter) already support `disabled`; DataTableSearch was the only toolbar control that could not be disabled during initial load. Ref forwarding lets consumers call .focus() without querying the component's markup (DS-1232 workaround).",
|
|
2327
|
+
"ticket": "DS-1231"
|
|
2328
|
+
},
|
|
2329
|
+
{
|
|
2330
|
+
"date": "2026-11-02",
|
|
2331
|
+
"decision": "stickyHeader=\"page\" pins the thead to the page scroller with CSS sticky at --content-sticky-top, which a sticky CardHeader publishes with its live height. The headings stick while the table fits; once it is measured wider than the view (minWidth, column meta.minWidth, wide content) and scrolls sideways the view becomes the horizontal scroll region and the headings scroll with the page.",
|
|
2332
|
+
"why": "Any overflow:auto axis makes the view a scroll container that traps a sticky thead, and CSS cannot stick one element to two scrollers. CSS-only keeps scroll-linked JS out of the table.",
|
|
2333
|
+
"ticket": "DS-1215"
|
|
2334
|
+
}
|
|
2335
|
+
],
|
|
2336
|
+
"ruledOut": [
|
|
2337
|
+
{
|
|
2338
|
+
"option": "A select-all checkbox on a table with a count-based selection cap",
|
|
2339
|
+
"why": "The predicate sees the selection as it stands, so every row passes while nothing is selected and one bulk click blows past the cap. Select-all pairs only with a predicate that reads the row itself (row.original.status !== \"Inactive\"); capped tables omit it, and always let an already-selected row pass.",
|
|
2340
|
+
"ticket": "DS-901"
|
|
2341
|
+
},
|
|
2342
|
+
{
|
|
2343
|
+
"option": "A JS scroll listener that translates the thead under the card header while the table scrolls sideways",
|
|
2344
|
+
"why": "Scroll-linked positioning lags the compositor by a frame and jitters on fast scroll; the owner chose CSS-only.",
|
|
2345
|
+
"ticket": "DS-1215"
|
|
2346
|
+
}
|
|
2221
2347
|
]
|
|
2222
2348
|
},
|
|
2223
2349
|
{
|
|
@@ -2250,7 +2376,7 @@
|
|
|
2250
2376
|
],
|
|
2251
2377
|
"i18nProps": {
|
|
2252
2378
|
"DatePickerTrigger": {
|
|
2253
|
-
"triggerLabel": "string — default: \"
|
|
2379
|
+
"triggerLabel": "string — default: \"Select date\" / \"Select date range\"; the visible value is appended (\"<label>: <value>\")"
|
|
2254
2380
|
},
|
|
2255
2381
|
"DatePickerContent": {
|
|
2256
2382
|
"contentLabel": "string — default: \"Date picker\""
|
|
@@ -2331,6 +2457,86 @@
|
|
|
2331
2457
|
"fixed predefined ranges only (plain preset buttons are faster)"
|
|
2332
2458
|
]
|
|
2333
2459
|
},
|
|
2460
|
+
{
|
|
2461
|
+
"name": "Delta",
|
|
2462
|
+
"import": "@brightlocal/ui-components/delta",
|
|
2463
|
+
"category": "display",
|
|
2464
|
+
"exports": [
|
|
2465
|
+
"Delta"
|
|
2466
|
+
],
|
|
2467
|
+
"compound": false,
|
|
2468
|
+
"dataHookRequired": true,
|
|
2469
|
+
"variants": {
|
|
2470
|
+
"variant": [
|
|
2471
|
+
"inline",
|
|
2472
|
+
"pill"
|
|
2473
|
+
]
|
|
2474
|
+
},
|
|
2475
|
+
"props": [
|
|
2476
|
+
"value",
|
|
2477
|
+
"greenWhen",
|
|
2478
|
+
"variant",
|
|
2479
|
+
"children",
|
|
2480
|
+
"increasedLabel",
|
|
2481
|
+
"decreasedLabel",
|
|
2482
|
+
"unchangedLabel"
|
|
2483
|
+
],
|
|
2484
|
+
"description": "How much a value moved between two points: an arrow and an amount. The arrow follows the sign of value (the change as the product phrases it — rank up 8 is value={8}); the colour comes from greenWhen (score-strong ink when the direction is good, score-poor when bad, muted for zero). variant inline (text-label, 16px arrow) or pill (text-label-sm on a 15% score tint). Screen readers hear a phrase (\"Increased by 8\") instead of the arrow and number. Exposes data-direction (increase|decrease|none) and data-trend (better|worse|none).",
|
|
2485
|
+
"aliases": [
|
|
2486
|
+
"change",
|
|
2487
|
+
"trend",
|
|
2488
|
+
"trend indicator",
|
|
2489
|
+
"diff",
|
|
2490
|
+
"difference",
|
|
2491
|
+
"increase",
|
|
2492
|
+
"decrease",
|
|
2493
|
+
"up down arrow",
|
|
2494
|
+
"movement",
|
|
2495
|
+
"period over period"
|
|
2496
|
+
],
|
|
2497
|
+
"whenToUse": [
|
|
2498
|
+
"The change between two values of one metric (this period vs the last, today vs the previous check)",
|
|
2499
|
+
"A rank, count or percentage movement next to the value it belongs to — variant=\"pill\" beside a metric, inline in a table cell"
|
|
2500
|
+
],
|
|
2501
|
+
"doNotUseFor": [
|
|
2502
|
+
"An absolute grade of a value — use the score-* colour scale",
|
|
2503
|
+
"A lifecycle state — use Status",
|
|
2504
|
+
"A fact or label — use Badge"
|
|
2505
|
+
],
|
|
2506
|
+
"alternatives": [
|
|
2507
|
+
{
|
|
2508
|
+
"component": "Status",
|
|
2509
|
+
"rule": "Use Status for where a tracked thing is in its lifecycle; Delta is only the change between two values"
|
|
2510
|
+
}
|
|
2511
|
+
],
|
|
2512
|
+
"i18nProps": {
|
|
2513
|
+
"Delta": {
|
|
2514
|
+
"increasedLabel": "string — default: \"Increased by\"",
|
|
2515
|
+
"decreasedLabel": "string — default: \"Decreased by\"",
|
|
2516
|
+
"unchangedLabel": "string — default: \"Unchanged\""
|
|
2517
|
+
}
|
|
2518
|
+
},
|
|
2519
|
+
"decisions": [
|
|
2520
|
+
{
|
|
2521
|
+
"decision": "value is the signed change as the product phrases it; the arrow follows the sign and greenWhen sets the colour",
|
|
2522
|
+
"why": "Rank up 8 places is good news but a smaller number — phrasing-first keeps the arrow matching the copy while greenWhen keeps the colour honest",
|
|
2523
|
+
"date": "2026-11-02",
|
|
2524
|
+
"ticket": "DS-1202"
|
|
2525
|
+
},
|
|
2526
|
+
{
|
|
2527
|
+
"decision": "Arrow only — no +/- sign in the text; children override the amount (magnitude only)",
|
|
2528
|
+
"why": "The arrow carries the sign; a sign plus an arrow double-encodes it",
|
|
2529
|
+
"date": "2026-11-02",
|
|
2530
|
+
"ticket": "DS-1202"
|
|
2531
|
+
},
|
|
2532
|
+
{
|
|
2533
|
+
"decision": "The colour prop is greenWhen (\"up\" | \"down\"), not betterWhen",
|
|
2534
|
+
"why": "It names what the user sees — which direction shows green — so designers and engineers read it without a definition of better",
|
|
2535
|
+
"date": "2026-11-02",
|
|
2536
|
+
"ticket": "DS-1152"
|
|
2537
|
+
}
|
|
2538
|
+
]
|
|
2539
|
+
},
|
|
2334
2540
|
{
|
|
2335
2541
|
"name": "Description",
|
|
2336
2542
|
"import": "@brightlocal/ui-components/description",
|
|
@@ -2356,7 +2562,104 @@
|
|
|
2356
2562
|
"doNotUseFor": [
|
|
2357
2563
|
"form field descriptions (use Field's built-in description)",
|
|
2358
2564
|
"heading or body-copy weight text (use Typography)",
|
|
2359
|
-
"validation errors (use Field's error text)"
|
|
2565
|
+
"validation errors (use Field's error text)",
|
|
2566
|
+
"label-value pairs describing a record (use DescriptionList)"
|
|
2567
|
+
]
|
|
2568
|
+
},
|
|
2569
|
+
{
|
|
2570
|
+
"name": "DescriptionList",
|
|
2571
|
+
"import": "@brightlocal/ui-components/description-list",
|
|
2572
|
+
"category": "display",
|
|
2573
|
+
"exports": [
|
|
2574
|
+
"DescriptionList",
|
|
2575
|
+
"DescriptionListItem",
|
|
2576
|
+
"DescriptionListTerm",
|
|
2577
|
+
"DescriptionListDetails",
|
|
2578
|
+
"DescriptionListIconText"
|
|
2579
|
+
],
|
|
2580
|
+
"compound": true,
|
|
2581
|
+
"dataHookRequired": true,
|
|
2582
|
+
"variants": {
|
|
2583
|
+
"layout": [
|
|
2584
|
+
"inline",
|
|
2585
|
+
"stacked",
|
|
2586
|
+
"responsive",
|
|
2587
|
+
"container",
|
|
2588
|
+
"grid"
|
|
2589
|
+
],
|
|
2590
|
+
"align": [
|
|
2591
|
+
"start",
|
|
2592
|
+
"end"
|
|
2593
|
+
]
|
|
2594
|
+
},
|
|
2595
|
+
"props": [
|
|
2596
|
+
"termWidth",
|
|
2597
|
+
"divided",
|
|
2598
|
+
"color"
|
|
2599
|
+
],
|
|
2600
|
+
"description": "Label-and-value pairs describing one record, rendered as a semantic <dl>",
|
|
2601
|
+
"aliases": [
|
|
2602
|
+
"description list",
|
|
2603
|
+
"definition list",
|
|
2604
|
+
"key value",
|
|
2605
|
+
"key-value pairs",
|
|
2606
|
+
"label value",
|
|
2607
|
+
"details list",
|
|
2608
|
+
"metadata list",
|
|
2609
|
+
"summary list",
|
|
2610
|
+
"dl"
|
|
2611
|
+
],
|
|
2612
|
+
"whenToUse": [
|
|
2613
|
+
"Properties of one record: the details of a review, a location's business details",
|
|
2614
|
+
"The read view of a settings card (the card header owns the Edit action)",
|
|
2615
|
+
"Receipts and totals in a popover or dialog (align=\"end\")",
|
|
2616
|
+
"A plan's limits or a record's facts as stacked items in columns (layout=\"grid\")"
|
|
2617
|
+
],
|
|
2618
|
+
"doNotUseFor": [
|
|
2619
|
+
"several records compared by the same attributes (use Table or DataTable)",
|
|
2620
|
+
"rows the user acts on: navigation, drill-down, toggles (use List with ItemButton/ItemLink)",
|
|
2621
|
+
"headline numbers with a trend (use CardMetric)",
|
|
2622
|
+
"form inputs (use Field)"
|
|
2623
|
+
],
|
|
2624
|
+
"states": [
|
|
2625
|
+
"default"
|
|
2626
|
+
],
|
|
2627
|
+
"a11yContract": [
|
|
2628
|
+
"renders <dl> with each <dt>/<dd> pair grouped in a <div> (allowed inside dl)",
|
|
2629
|
+
"no interactive role; links and buttons inside values keep their own semantics",
|
|
2630
|
+
"DescriptionListIconText hides its icon from assistive tech; the text names the value"
|
|
2631
|
+
],
|
|
2632
|
+
"decisions": [
|
|
2633
|
+
{
|
|
2634
|
+
"date": "2026-11-03",
|
|
2635
|
+
"decision": "DescriptionList is its own component, not a Table variant. One record's properties are a dl; several records compared by the same attributes are a Table.",
|
|
2636
|
+
"why": "A table announces rows and columns that a list of one record's fields does not have, and a variant would have overridden Table's header, borders, density and hover, plus added stacked and grid layouts a table cannot do without losing its semantics.",
|
|
2637
|
+
"ticket": "DS-1124"
|
|
2638
|
+
},
|
|
2639
|
+
{
|
|
2640
|
+
"date": "2026-11-03",
|
|
2641
|
+
"decision": "Promoted from the local DescriptionList that Tool Settings, Location Manager and Review Manager carried (inline/stacked/responsive/container layouts, termWidth 128px default, divided, IconText), adding termWidth=\"auto\", align=\"end\" and layout=\"grid\".",
|
|
2642
|
+
"why": "The three prototype copies were identical and already matched the Figma Description List anatomy; the additions cover the auto-width read views (account settings, greenfield ReviewDetails), popover receipts and the plan facts grid found in the prototypes.",
|
|
2643
|
+
"ticket": "DS-1124"
|
|
2644
|
+
},
|
|
2645
|
+
{
|
|
2646
|
+
"date": "2026-11-03",
|
|
2647
|
+
"decision": "An empty value is DescriptionListDetails color=\"muted\" (\"Not set\"), not a className.",
|
|
2648
|
+
"why": "Colour on a DS component through className is lint-blocked outside ui-components, and empty values appear in most read views.",
|
|
2649
|
+
"ticket": "DS-1124"
|
|
2650
|
+
}
|
|
2651
|
+
],
|
|
2652
|
+
"ruledOut": [
|
|
2653
|
+
{
|
|
2654
|
+
"option": "A key-value variant of Table",
|
|
2655
|
+
"why": "Different semantics (2D grid vs one record's properties) and the variant would replace almost all of Table's styling; see decisions.",
|
|
2656
|
+
"ticket": "DS-1124"
|
|
2657
|
+
},
|
|
2658
|
+
{
|
|
2659
|
+
"option": "Per-row edit actions inside DescriptionList",
|
|
2660
|
+
"why": "Every read view in the prototypes edits from the container header; an action on the row turns it into a List row (DS-1166).",
|
|
2661
|
+
"ticket": "DS-1124"
|
|
2662
|
+
}
|
|
2360
2663
|
]
|
|
2361
2664
|
},
|
|
2362
2665
|
{
|
|
@@ -2779,355 +3082,83 @@
|
|
|
2779
3082
|
]
|
|
2780
3083
|
},
|
|
2781
3084
|
{
|
|
2782
|
-
"name": "
|
|
2783
|
-
"import": "@brightlocal/ui-components/
|
|
3085
|
+
"name": "Field",
|
|
3086
|
+
"import": "@brightlocal/ui-components/field",
|
|
2784
3087
|
"category": "form",
|
|
2785
3088
|
"exports": [
|
|
2786
|
-
"
|
|
2787
|
-
"
|
|
3089
|
+
"Field",
|
|
3090
|
+
"FieldLabel",
|
|
3091
|
+
"FieldDescription",
|
|
3092
|
+
"FieldError",
|
|
3093
|
+
"FieldErrorIcon",
|
|
3094
|
+
"FieldGroup",
|
|
3095
|
+
"FieldLegend",
|
|
3096
|
+
"FieldSet",
|
|
3097
|
+
"FieldContent"
|
|
2788
3098
|
],
|
|
2789
|
-
"compound":
|
|
3099
|
+
"compound": true,
|
|
2790
3100
|
"dataHookRequired": true,
|
|
2791
3101
|
"variants": {
|
|
2792
|
-
"
|
|
3102
|
+
"orientation": [
|
|
3103
|
+
"vertical",
|
|
3104
|
+
"horizontal",
|
|
3105
|
+
"responsive"
|
|
3106
|
+
],
|
|
3107
|
+
"variant": [
|
|
2793
3108
|
"default",
|
|
2794
|
-
"
|
|
3109
|
+
"box"
|
|
2795
3110
|
]
|
|
2796
3111
|
},
|
|
2797
3112
|
"props": [
|
|
2798
|
-
"
|
|
2799
|
-
"
|
|
2800
|
-
|
|
2801
|
-
|
|
2802
|
-
|
|
2803
|
-
"
|
|
2804
|
-
"
|
|
2805
|
-
"
|
|
2806
|
-
"maxVisibleLabels",
|
|
2807
|
-
"allLabel",
|
|
2808
|
-
"allCount",
|
|
2809
|
-
"searchThreshold",
|
|
2810
|
-
"searchable",
|
|
2811
|
-
"disabled",
|
|
2812
|
-
"presentation",
|
|
2813
|
-
"collapseFullSelection",
|
|
2814
|
-
"allIcon"
|
|
3113
|
+
"align",
|
|
3114
|
+
"srOnly"
|
|
3115
|
+
],
|
|
3116
|
+
"description": "Form field wrapper with label, description, and error handling",
|
|
3117
|
+
"aliases": [
|
|
3118
|
+
"form field",
|
|
3119
|
+
"input group",
|
|
3120
|
+
"field wrapper"
|
|
2815
3121
|
],
|
|
2816
|
-
"description": "The Filtering pattern's faceted multi-select: one dimension, several values combining as OR, over a Popover + Command menu that stays open across picks. The trigger hugs its label in a toolbar and wears the Select field look (border, radius, focus ring, chevron) because a filter trigger holds a value, it does not act; stacked in a panel it takes className='w-full'. No error state — a filter does not validate. size='default' (h-9, text-field like Select: 14px desktop / 16px touch) or 'sm' (h-8, text-label, phone card headers). The trigger always reads its picks, like a Select shows its value: allLabel at zero (or the dimension's label, muted, as a placeholder), then the picked labels, collapsing past maxVisibleLabels (default 1) into summaryLabel ('Google +2' via the default '{labels} +{rest}'; '3 selected' via '{count} selected') — and it computes the accessible name itself with every pick spelled out. Glyphs are the consumer's, never a fixed funnel: option.icon shows before each label in the menu and drawer, allIcon marks the All row, and the trigger follows the selection (allIcon at zero, then the first pick's icon) unless icon pins one. No-match shows the compact empty form (muted chip, emptyLabel, emptyDescription) in both presentations. allLabel adds a leading reset row: 'All' means no narrowing, so it is checked when value is empty and picking it clears the selection; a pick that completes the set collapses to [] for the same reason (collapseFullSelection, default true). Picks read on the trigger in pick order. Selected values pin to the top on reopen; a zero-count option is disabled, never hidden; past searchThreshold (10) the menu grows an autofocused search input (searchable forces it) — a case-insensitive substring match on label and value, never on the count; while searching the All row and Clear step aside, and a no-match search shows emptyLabel alone. presentation='menu' (default) is the Popover + Command menu; 'drawer' is the phone form — the same trigger opens a bottom Drawer titled with the dimension, All row, options as Checkboxes in two columns, search past the threshold, Clear while something is picked, a Done button that only closes (ticks apply at once); 'auto' switches at the md breakpoint. Both render from one state. Per-filter commit model: onValueChange on every pick, run an expensive refetch on onOpenChange(false). multiSelectFilterTriggerVariants is exported for the 'Filters (n)' recipe — a trigger that opens a Sheet or Drawer of hidden filters, with a Badge srLabel count.",
|
|
2817
|
-
"i18nProps": {
|
|
2818
|
-
"MultiSelectFilter": {
|
|
2819
|
-
"clearLabel": "string — default: \"Clear filters\"",
|
|
2820
|
-
"summaryLabel": "string — default: \"{labels} +{rest}\" (placeholders: {labels}, {rest}, {count})",
|
|
2821
|
-
"searchPlaceholder": "string — default: \"Search options...\"",
|
|
2822
|
-
"emptyLabel": "string — default: \"No options found.\"",
|
|
2823
|
-
"doneLabel": "string — default: \"Done\" (the drawer's close button)",
|
|
2824
|
-
"drawerDescription": "string — default: \"Picks apply as you make them.\" (sr-only drawer description)",
|
|
2825
|
-
"emptyDescription": "string — default: \"Try another search.\" (hint under the no-match message)",
|
|
2826
|
-
"clearSearchAriaLabel": "string — default: \"Clear search\" (the menu search input's clear button; the drawer search has none)"
|
|
2827
|
-
}
|
|
2828
|
-
},
|
|
2829
3122
|
"whenToUse": [
|
|
2830
|
-
"
|
|
2831
|
-
"
|
|
2832
|
-
"
|
|
2833
|
-
"Any option list past ~10 values — the menu's autofocused search input and pinned selections handle it",
|
|
2834
|
-
"Desktop: presentation='menu' (default), the Popover + Command menu beside a Select in a toolbar (size='default', h-9, text-field)",
|
|
2835
|
-
"Phone: presentation='drawer' opens the same picks as a bottom Drawer (Checkbox rows in two columns, search past the threshold, Clear, Done only closes); presentation='auto' switches at the md breakpoint; size='sm' (h-8) for card headers — no hand-rolled drawer per filter"
|
|
3123
|
+
"A standard label-plus-input layout for any typical form question",
|
|
3124
|
+
"Consistent alignment of label, hint text, and error message without extra setup",
|
|
3125
|
+
"Box variant for card-style questions that need to stand out (highlighted settings, onboarding)"
|
|
2836
3126
|
],
|
|
2837
3127
|
"doNotUseFor": [
|
|
2838
|
-
"
|
|
2839
|
-
"
|
|
2840
|
-
"
|
|
2841
|
-
"a form field that validates and submits — this is a filter and has no error state; a form multi-select is a separate component",
|
|
2842
|
-
"the 'Filters (n)' trigger that opens a panel of hidden filters — compose a button with multiSelectFilterTriggerVariants and a Badge srLabel count instead",
|
|
2843
|
-
"a batch drawer of several filters behind one Apply — the Filtering page's MobileFilterDrawer recipe (Drawer + the trigger style), not one MultiSelectFilter"
|
|
3128
|
+
"showing information without a form question (use Description or plain text)",
|
|
3129
|
+
"grouping related checkboxes or radios under one heading (use FieldSet with FieldLegend)",
|
|
3130
|
+
"boxed fields in dense forms (adds clutter and vertical space; use the default variant)"
|
|
2844
3131
|
],
|
|
2845
3132
|
"alternatives": [
|
|
2846
3133
|
{
|
|
2847
|
-
"component": "
|
|
2848
|
-
"rule": "Use
|
|
2849
|
-
},
|
|
2850
|
-
{
|
|
2851
|
-
"component": "Combobox",
|
|
2852
|
-
"rule": "Use Combobox for a single choice from a long, searchable list — it is single-value by design"
|
|
2853
|
-
},
|
|
2854
|
-
{
|
|
2855
|
-
"component": "ToggleGroup",
|
|
2856
|
-
"rule": "Use ToggleGroup (or the Lab SegmentedControl) for a quick filter kept visible in the bar"
|
|
2857
|
-
},
|
|
2858
|
-
{
|
|
2859
|
-
"component": "InputChip",
|
|
2860
|
-
"rule": "Use InputChip when the person types new values rather than picking existing ones"
|
|
2861
|
-
},
|
|
2862
|
-
{
|
|
2863
|
-
"component": "Drawer",
|
|
2864
|
-
"rule": "Use Drawer with multiSelectFilterTriggerVariants for a batch panel of several filters on a phone (MobileFilterDrawer recipe); a single filter's phone form is presentation='drawer' on MultiSelectFilter itself"
|
|
2865
|
-
},
|
|
2866
|
-
{
|
|
2867
|
-
"component": "Chip",
|
|
2868
|
-
"rule": "Use Chip for the applied-filter tokens that show what a MultiSelectFilter has picked"
|
|
2869
|
-
},
|
|
2870
|
-
{
|
|
2871
|
-
"component": "SingleSelectFilter",
|
|
2872
|
-
"rule": "Use SingleSelectFilter for one value from a dimension — it shares the trigger look and the drawer, with a DS Select on desktop"
|
|
3134
|
+
"component": "Label",
|
|
3135
|
+
"rule": "Use standalone Label only when building a custom field layout — Field includes FieldLabel with proper a11y wiring"
|
|
2873
3136
|
}
|
|
2874
3137
|
],
|
|
3138
|
+
"replaces": [],
|
|
3139
|
+
"states": [
|
|
3140
|
+
"default",
|
|
3141
|
+
"invalid"
|
|
3142
|
+
],
|
|
3143
|
+
"a11yContract": {
|
|
3144
|
+
"role": "group",
|
|
3145
|
+
"requiresLabel": false,
|
|
3146
|
+
"keyboardInteraction": []
|
|
3147
|
+
},
|
|
2875
3148
|
"figma": {
|
|
2876
3149
|
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
2877
|
-
"
|
|
2878
|
-
|
|
2879
|
-
"nodeId": "34233:70287",
|
|
2880
|
-
"figmaName": "Multi Select Filter",
|
|
2881
|
-
"kind": "componentSet",
|
|
2882
|
-
"export": "MultiSelectFilter",
|
|
2883
|
-
"note": "Built on branch task/DS-1023-faced-filter (2026-10-08); node ids persist on merge. Draws the trigger (Text, Show Icon + Icon swap); the menu is the figmaOnly sub-parts below.",
|
|
2884
|
-
"axes": [
|
|
2885
|
-
{
|
|
2886
|
-
"figma": "Size",
|
|
2887
|
-
"code": "size"
|
|
2888
|
-
},
|
|
2889
|
-
{
|
|
2890
|
-
"figma": "State",
|
|
2891
|
-
"exempt": "interaction-state",
|
|
2892
|
-
"valueToProp": {
|
|
2893
|
-
"Disabled": "disabled"
|
|
2894
|
-
},
|
|
2895
|
-
"note": "Focus and Open are runtime states"
|
|
2896
|
-
}
|
|
2897
|
-
]
|
|
2898
|
-
}
|
|
2899
|
-
],
|
|
2900
|
-
"unmappedExports": [
|
|
2901
|
-
{
|
|
2902
|
-
"export": "multiSelectFilterTriggerVariants",
|
|
2903
|
-
"reason": "cva style helper for the 'Filters (n)' recipe, not a component — the Multi Select Filter set's variants are its drawing"
|
|
2904
|
-
}
|
|
2905
|
-
],
|
|
2906
|
-
"figmaOnly": [
|
|
2907
|
-
{
|
|
2908
|
-
"nodeId": "34233:70355",
|
|
2909
|
-
"figmaName": "Multi Select Filter / Menu Item",
|
|
2910
|
-
"reason": "The menu row MultiSelectFilter renders internally (CommandItem + Checkbox look + count); no sub-part export by design — one component, one engine. Checked/State are runtime states."
|
|
2911
|
-
},
|
|
2912
|
-
{
|
|
2913
|
-
"nodeId": "34233:70435",
|
|
2914
|
-
"figmaName": "Multi Select Filter / Menu",
|
|
2915
|
-
"reason": "The Popover + Command menu MultiSelectFilter renders internally (search, All row, options, empty, Clear); no sub-part export by design."
|
|
2916
|
-
}
|
|
2917
|
-
]
|
|
2918
|
-
},
|
|
2919
|
-
"aliases": [
|
|
2920
|
-
"faceted filter",
|
|
2921
|
-
"facet filter",
|
|
2922
|
-
"multi-select",
|
|
2923
|
-
"multi select dropdown",
|
|
2924
|
-
"filter dropdown",
|
|
2925
|
-
"checkbox filter",
|
|
2926
|
-
"filter menu",
|
|
2927
|
-
"mobile filter drawer"
|
|
2928
|
-
],
|
|
2929
|
-
"replaces": [
|
|
2930
|
-
"Lab FacetedFilter",
|
|
2931
|
-
"Lab SearchableMultiSelect",
|
|
2932
|
-
"Lab FilterTrigger (as multiSelectFilterTriggerVariants + Badge srLabel)",
|
|
2933
|
-
"per-app faceted-filter copies in the prototypes"
|
|
2934
|
-
],
|
|
2935
|
-
"states": [
|
|
2936
|
-
"closed",
|
|
2937
|
-
"open (menu)",
|
|
2938
|
-
"open (drawer)",
|
|
2939
|
-
"searching",
|
|
2940
|
-
"no match",
|
|
2941
|
-
"disabled"
|
|
2942
|
-
],
|
|
2943
|
-
"a11yContract": {
|
|
2944
|
-
"role": "button (trigger, aria-label computed: '{label}: {every pick}') → Popover with a cmdk listbox of aria-checked options, or a Drawer dialog titled with the dimension",
|
|
2945
|
-
"requiresLabel": true,
|
|
2946
|
-
"keyboardInteraction": [
|
|
2947
|
-
"Enter/Space opens",
|
|
2948
|
-
"Arrow keys move between options (cmdk root takes focus when there is no search input)",
|
|
2949
|
-
"Enter toggles the highlighted option; the menu stays open",
|
|
2950
|
-
"Type to narrow past the search threshold",
|
|
2951
|
-
"Escape closes and returns focus to the trigger"
|
|
2952
|
-
]
|
|
3150
|
+
"status": "represented-inline",
|
|
3151
|
+
"reason": "No standalone Figma component — the Field scaffolding (label, description, error message, orientation) is drawn as 'Label Text'/'Description Text'/State=Error props inside every field set (Input, Textarea, Select, Combobox, Date Picker, ...). Verified 2026-08-18."
|
|
2953
3152
|
},
|
|
2954
|
-
"
|
|
2955
|
-
{
|
|
2956
|
-
"description": "The trigger hugs its text, so its width moves with the reading ('All sources' → 'Google' → 'Google +2'); Select solves this with reserveValues, MultiSelectFilter does not yet",
|
|
2957
|
-
"workaround": "Keep maxVisibleLabels at its default of 1; where neighbours must not shift, add className='min-w-40' (a layout class) sized to the dimension's longest label"
|
|
2958
|
-
},
|
|
3153
|
+
"decisions": [
|
|
2959
3154
|
{
|
|
2960
|
-
"
|
|
2961
|
-
"
|
|
3155
|
+
"date": "2026-10-28",
|
|
3156
|
+
"decision": "Inside a Field, Input and Textarea point aria-describedby at the rendered FieldError and FieldDescription by themselves. Field provides the context, the two parts register their id while rendered, and a hand-written aria-describedby is merged, not replaced. Select, Combobox, DatePicker and InputOTP are not wired yet.",
|
|
3157
|
+
"why": "Hand-wiring the id on every field was the only way a screen reader heard the message with the control, and every consumer form had to repeat it. Registering at render time keeps the reference pointing only at elements that exist.",
|
|
3158
|
+
"ticket": "DS-899"
|
|
2962
3159
|
}
|
|
2963
3160
|
]
|
|
2964
3161
|
},
|
|
2965
|
-
{
|
|
2966
|
-
"name": "SingleSelectFilter",
|
|
2967
|
-
"import": "@brightlocal/ui-components/single-select-filter",
|
|
2968
|
-
"category": "form",
|
|
2969
|
-
"exports": [
|
|
2970
|
-
"SingleSelectFilter"
|
|
2971
|
-
],
|
|
2972
|
-
"compound": false,
|
|
2973
|
-
"dataHookRequired": true,
|
|
2974
|
-
"variants": {
|
|
2975
|
-
"size": [
|
|
2976
|
-
"default",
|
|
2977
|
-
"sm"
|
|
2978
|
-
],
|
|
2979
|
-
"presentation": [
|
|
2980
|
-
"menu",
|
|
2981
|
-
"drawer",
|
|
2982
|
-
"auto"
|
|
2983
|
-
]
|
|
2984
|
-
},
|
|
2985
|
-
"props": [
|
|
2986
|
-
"label",
|
|
2987
|
-
"options",
|
|
2988
|
-
"value",
|
|
2989
|
-
"defaultValue",
|
|
2990
|
-
"onValueChange",
|
|
2991
|
-
"open",
|
|
2992
|
-
"onOpenChange",
|
|
2993
|
-
"icon",
|
|
2994
|
-
"disabled",
|
|
2995
|
-
"presentation"
|
|
2996
|
-
],
|
|
2997
|
-
"description": "The Filtering pattern's single-value dropdown filter: one value from one dimension (time period, interval, source type). Shows a DS Select (native listbox, keyboard navigation, scroll indicators) on desktop and a bottom Drawer with RadioGroup in two columns on mobile. The trigger wears the same field look as MultiSelectFilter (multiSelectFilterTriggerVariants — border, radius, focus ring, chevron) so a SingleSelectFilter sits beside a MultiSelectFilter in a toolbar row without looking different. size='default' (h-9, text-field: 14px desktop / 16px touch like Select) or 'sm' (h-8, text-label, phone card headers). The trigger always reads the selected label, or the dimension's name when nothing is picked — both in foreground text, never muted. Options may carry their own icon (option.icon) shown before the label in the menu and the drawer; the trigger wears the picked option's icon unless the icon prop pins one. Counts render in the menu only, never in the trigger. Clear resets to defaultValue — unlike MultiSelectFilter which clears to []; a single-value filter always has a value, and 'no filter' is an explicit option in the list. Drawer anatomy matches MultiSelectFilter: DrawerTitle = label, sr-only DrawerDescription, RadioGroup in grid-cols-2, Clear when value ≠ defaultValue, Done button that only closes. Per-filter commit model: onValueChange fires on every pick. presentation='menu' (default) is the DS Select; 'drawer' is the phone form; 'auto' switches at the md breakpoint.",
|
|
2998
|
-
"i18nProps": {
|
|
2999
|
-
"SingleSelectFilter": {
|
|
3000
|
-
"clearLabel": "string — default: \"Clear filters\"",
|
|
3001
|
-
"doneLabel": "string — default: \"Done\" (the drawer's close button)",
|
|
3002
|
-
"drawerDescription": "string — default: \"Pick one option.\" (sr-only drawer description)"
|
|
3003
|
-
}
|
|
3004
|
-
},
|
|
3005
|
-
"whenToUse": [
|
|
3006
|
-
"One value from a dimension in a filter toolbar (time period, interval, source type) — the Filtering pattern's dropdown filter",
|
|
3007
|
-
"A responsive filter that shows a DS Select on desktop and a radio drawer on mobile: presentation='auto' switches at md",
|
|
3008
|
-
"Sitting beside MultiSelectFilter in a filter bar — the trigger look matches exactly"
|
|
3009
|
-
],
|
|
3010
|
-
"doNotUseFor": [
|
|
3011
|
-
"picking more than one option (use MultiSelectFilter)",
|
|
3012
|
-
"a form field that validates (use Select — SingleSelectFilter has no error state)",
|
|
3013
|
-
"quick filters with 2–5 always-visible options (use ToggleGroup or SegmentedControl)",
|
|
3014
|
-
"a long, searchable single-value list in a form (use Combobox)"
|
|
3015
|
-
],
|
|
3016
|
-
"alternatives": [
|
|
3017
|
-
{
|
|
3018
|
-
"component": "MultiSelectFilter",
|
|
3019
|
-
"rule": "Use MultiSelectFilter for several values from one dimension combining as OR"
|
|
3020
|
-
},
|
|
3021
|
-
{
|
|
3022
|
-
"component": "Select",
|
|
3023
|
-
"rule": "Use Select for a form field that validates — SingleSelectFilter is a filter, not a form field"
|
|
3024
|
-
},
|
|
3025
|
-
{
|
|
3026
|
-
"component": "ToggleGroup",
|
|
3027
|
-
"rule": "Use ToggleGroup for a quick filter with 2–5 always-visible options"
|
|
3028
|
-
},
|
|
3029
|
-
{
|
|
3030
|
-
"component": "Combobox",
|
|
3031
|
-
"rule": "Use Combobox for a long, searchable single-value list in a form"
|
|
3032
|
-
}
|
|
3033
|
-
],
|
|
3034
|
-
"figma": {
|
|
3035
|
-
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
3036
|
-
"nodes": [
|
|
3037
|
-
{
|
|
3038
|
-
"nodeId": "34438:81566",
|
|
3039
|
-
"figmaName": "Single Select Filter",
|
|
3040
|
-
"kind": "componentSet",
|
|
3041
|
-
"export": "SingleSelectFilter",
|
|
3042
|
-
"note": "Built on branch task/DS-1050-sigle-select-filter (2026-10-12); node ids persist on merge. Draws the trigger (Text, Show Icon + Icon swap). The desktop menu is the Select page's `Select / Menu` (the component wraps DS Select) and the phone drawer is a Playground composition of Drawer + Radio / Item — neither is a sub-part export. `presentation` is a runtime/responsive prop with no Figma axis.",
|
|
3043
|
-
"axes": [
|
|
3044
|
-
{
|
|
3045
|
-
"figma": "Size",
|
|
3046
|
-
"code": "size"
|
|
3047
|
-
},
|
|
3048
|
-
{
|
|
3049
|
-
"figma": "State",
|
|
3050
|
-
"exempt": "interaction-state",
|
|
3051
|
-
"valueToProp": {
|
|
3052
|
-
"Disabled": "disabled"
|
|
3053
|
-
},
|
|
3054
|
-
"note": "Focus and Open are runtime states; the CVA has no hover style, so there is no Hover variant"
|
|
3055
|
-
}
|
|
3056
|
-
]
|
|
3057
|
-
}
|
|
3058
|
-
]
|
|
3059
|
-
}
|
|
3060
|
-
},
|
|
3061
|
-
{
|
|
3062
|
-
"name": "Field",
|
|
3063
|
-
"import": "@brightlocal/ui-components/field",
|
|
3064
|
-
"category": "form",
|
|
3065
|
-
"exports": [
|
|
3066
|
-
"Field",
|
|
3067
|
-
"FieldLabel",
|
|
3068
|
-
"FieldDescription",
|
|
3069
|
-
"FieldError",
|
|
3070
|
-
"FieldErrorIcon",
|
|
3071
|
-
"FieldGroup",
|
|
3072
|
-
"FieldLegend",
|
|
3073
|
-
"FieldSet",
|
|
3074
|
-
"FieldContent"
|
|
3075
|
-
],
|
|
3076
|
-
"compound": true,
|
|
3077
|
-
"dataHookRequired": true,
|
|
3078
|
-
"variants": {
|
|
3079
|
-
"orientation": [
|
|
3080
|
-
"vertical",
|
|
3081
|
-
"horizontal",
|
|
3082
|
-
"responsive"
|
|
3083
|
-
],
|
|
3084
|
-
"variant": [
|
|
3085
|
-
"default",
|
|
3086
|
-
"box"
|
|
3087
|
-
]
|
|
3088
|
-
},
|
|
3089
|
-
"props": [
|
|
3090
|
-
"align",
|
|
3091
|
-
"srOnly"
|
|
3092
|
-
],
|
|
3093
|
-
"description": "Form field wrapper with label, description, and error handling",
|
|
3094
|
-
"aliases": [
|
|
3095
|
-
"form field",
|
|
3096
|
-
"input group",
|
|
3097
|
-
"field wrapper"
|
|
3098
|
-
],
|
|
3099
|
-
"whenToUse": [
|
|
3100
|
-
"A standard label-plus-input layout for any typical form question",
|
|
3101
|
-
"Consistent alignment of label, hint text, and error message without extra setup",
|
|
3102
|
-
"Box variant for card-style questions that need to stand out (highlighted settings, onboarding)"
|
|
3103
|
-
],
|
|
3104
|
-
"doNotUseFor": [
|
|
3105
|
-
"showing information without a form question (use Description or plain text)",
|
|
3106
|
-
"grouping related checkboxes or radios under one heading (use FieldSet with FieldLegend)",
|
|
3107
|
-
"boxed fields in dense forms (adds clutter and vertical space; use the default variant)"
|
|
3108
|
-
],
|
|
3109
|
-
"alternatives": [
|
|
3110
|
-
{
|
|
3111
|
-
"component": "Label",
|
|
3112
|
-
"rule": "Use standalone Label only when building a custom field layout — Field includes FieldLabel with proper a11y wiring"
|
|
3113
|
-
}
|
|
3114
|
-
],
|
|
3115
|
-
"replaces": [],
|
|
3116
|
-
"states": [
|
|
3117
|
-
"default",
|
|
3118
|
-
"invalid"
|
|
3119
|
-
],
|
|
3120
|
-
"a11yContract": {
|
|
3121
|
-
"role": "group",
|
|
3122
|
-
"requiresLabel": false,
|
|
3123
|
-
"keyboardInteraction": []
|
|
3124
|
-
},
|
|
3125
|
-
"figma": {
|
|
3126
|
-
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
3127
|
-
"status": "represented-inline",
|
|
3128
|
-
"reason": "No standalone Figma component — the Field scaffolding (label, description, error message, orientation) is drawn as 'Label Text'/'Description Text'/State=Error props inside every field set (Input, Textarea, Select, Combobox, Date Picker, ...). Verified 2026-08-18."
|
|
3129
|
-
}
|
|
3130
|
-
},
|
|
3131
3162
|
{
|
|
3132
3163
|
"name": "GlobalLayout",
|
|
3133
3164
|
"import": "@brightlocal/ui-components/global-layout",
|
|
@@ -3611,7 +3642,8 @@
|
|
|
3611
3642
|
"defaultValue",
|
|
3612
3643
|
"disabled",
|
|
3613
3644
|
"allowDuplicates",
|
|
3614
|
-
"error"
|
|
3645
|
+
"error",
|
|
3646
|
+
"onBeforeAdd"
|
|
3615
3647
|
],
|
|
3616
3648
|
"i18nProps": {
|
|
3617
3649
|
"InputChipItems": {
|
|
@@ -3661,6 +3693,20 @@
|
|
|
3661
3693
|
"choosing from an existing list (use Combobox)",
|
|
3662
3694
|
"displaying already-chosen tags with no typing (use Chip)",
|
|
3663
3695
|
"adding many items at once via paste with per-row remove controls (use InputList)"
|
|
3696
|
+
],
|
|
3697
|
+
"decisions": [
|
|
3698
|
+
{
|
|
3699
|
+
"date": "2026-10-30",
|
|
3700
|
+
"ticket": "DS-1224",
|
|
3701
|
+
"decision": "onBeforeAdd returns false to reject; any other return (including void) lets the add proceed. Rejected text stays in the input so the user can correct it.",
|
|
3702
|
+
"why": "Matches the pre-validation pattern consumers asked for without breaking the existing uncontrolled flow"
|
|
3703
|
+
},
|
|
3704
|
+
{
|
|
3705
|
+
"date": "2026-10-30",
|
|
3706
|
+
"ticket": "DS-1225",
|
|
3707
|
+
"decision": "InputChipInput ref flipped from HTMLDivElement to HTMLInputElement via useImperativeHandle; wrapper access via wrapperRef prop",
|
|
3708
|
+
"why": "DS form contract requires ref → interactive element for focus management and aria-describedby wiring; wrapperRef covers the rare case of measuring the container"
|
|
3709
|
+
}
|
|
3664
3710
|
]
|
|
3665
3711
|
},
|
|
3666
3712
|
{
|
|
@@ -3982,6 +4028,18 @@
|
|
|
3982
4028
|
"category": "display",
|
|
3983
4029
|
"exports": [
|
|
3984
4030
|
"List",
|
|
4031
|
+
"ListItem",
|
|
4032
|
+
"ListItemButton",
|
|
4033
|
+
"ListItemLink",
|
|
4034
|
+
"ListItemMedia",
|
|
4035
|
+
"ListItemContent",
|
|
4036
|
+
"ListItemTitle",
|
|
4037
|
+
"ListItemDescription",
|
|
4038
|
+
"ListItemValue",
|
|
4039
|
+
"ListItemChevron",
|
|
4040
|
+
"ListItemActions",
|
|
4041
|
+
"ListSubheader",
|
|
4042
|
+
"ListSeparator",
|
|
3985
4043
|
"Item",
|
|
3986
4044
|
"ItemMedia",
|
|
3987
4045
|
"ItemContent",
|
|
@@ -3998,10 +4056,21 @@
|
|
|
3998
4056
|
"filled",
|
|
3999
4057
|
"outline",
|
|
4000
4058
|
"loading"
|
|
4059
|
+
],
|
|
4060
|
+
"align": [
|
|
4061
|
+
"center",
|
|
4062
|
+
"start"
|
|
4063
|
+
],
|
|
4064
|
+
"mediaVariant": [
|
|
4065
|
+
"default",
|
|
4066
|
+
"icon",
|
|
4067
|
+
"image"
|
|
4001
4068
|
]
|
|
4002
4069
|
},
|
|
4003
|
-
"props": [
|
|
4004
|
-
|
|
4070
|
+
"props": [
|
|
4071
|
+
"truncate"
|
|
4072
|
+
],
|
|
4073
|
+
"description": "Vertical list of rows: static, pressable (button or link), drill-down with a value and chevron, toggle and media rows, with section headings and separators",
|
|
4005
4074
|
"figma": {
|
|
4006
4075
|
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
4007
4076
|
"nodes": [
|
|
@@ -4016,33 +4085,81 @@
|
|
|
4016
4085
|
"nodeId": "28298:5025",
|
|
4017
4086
|
"figmaName": "Item Subheader",
|
|
4018
4087
|
"kind": "component",
|
|
4019
|
-
"export": "
|
|
4088
|
+
"export": "ListSubheader"
|
|
4020
4089
|
}
|
|
4021
4090
|
],
|
|
4022
4091
|
"unmappedExports": [
|
|
4023
4092
|
{
|
|
4024
|
-
"export": "
|
|
4093
|
+
"export": "ListItem",
|
|
4025
4094
|
"reason": "Drawn inside the List composition"
|
|
4026
4095
|
},
|
|
4027
4096
|
{
|
|
4028
|
-
"export": "
|
|
4097
|
+
"export": "ListItemMedia",
|
|
4029
4098
|
"reason": "Drawn inside the List composition"
|
|
4030
4099
|
},
|
|
4031
4100
|
{
|
|
4032
|
-
"export": "
|
|
4101
|
+
"export": "ListItemContent",
|
|
4033
4102
|
"reason": "Drawn inside the List composition"
|
|
4034
4103
|
},
|
|
4035
4104
|
{
|
|
4036
|
-
"export": "
|
|
4105
|
+
"export": "ListItemTitle",
|
|
4037
4106
|
"reason": "Drawn inside the List composition"
|
|
4038
4107
|
},
|
|
4039
4108
|
{
|
|
4040
|
-
"export": "
|
|
4109
|
+
"export": "ListItemDescription",
|
|
4041
4110
|
"reason": "Drawn inside the List composition"
|
|
4042
4111
|
},
|
|
4043
4112
|
{
|
|
4044
|
-
"export": "
|
|
4113
|
+
"export": "ListItemActions",
|
|
4114
|
+
"reason": "Drawn inside the List composition"
|
|
4115
|
+
},
|
|
4116
|
+
{
|
|
4117
|
+
"export": "ListItemButton",
|
|
4118
|
+
"reason": "Drawn inside the List composition"
|
|
4119
|
+
},
|
|
4120
|
+
{
|
|
4121
|
+
"export": "ListItemLink",
|
|
4122
|
+
"reason": "Drawn inside the List composition"
|
|
4123
|
+
},
|
|
4124
|
+
{
|
|
4125
|
+
"export": "ListItemValue",
|
|
4045
4126
|
"reason": "Drawn inside the List composition"
|
|
4127
|
+
},
|
|
4128
|
+
{
|
|
4129
|
+
"export": "ListItemChevron",
|
|
4130
|
+
"reason": "Drawn inside the List composition"
|
|
4131
|
+
},
|
|
4132
|
+
{
|
|
4133
|
+
"export": "ListSeparator",
|
|
4134
|
+
"reason": "Drawn inside the List composition"
|
|
4135
|
+
},
|
|
4136
|
+
{
|
|
4137
|
+
"export": "Item",
|
|
4138
|
+
"reason": "Deprecated alias of the ListItem/ListSubheader name; removed in 4.0"
|
|
4139
|
+
},
|
|
4140
|
+
{
|
|
4141
|
+
"export": "ItemMedia",
|
|
4142
|
+
"reason": "Deprecated alias of the ListItem/ListSubheader name; removed in 4.0"
|
|
4143
|
+
},
|
|
4144
|
+
{
|
|
4145
|
+
"export": "ItemContent",
|
|
4146
|
+
"reason": "Deprecated alias of the ListItem/ListSubheader name; removed in 4.0"
|
|
4147
|
+
},
|
|
4148
|
+
{
|
|
4149
|
+
"export": "ItemTitle",
|
|
4150
|
+
"reason": "Deprecated alias of the ListItem/ListSubheader name; removed in 4.0"
|
|
4151
|
+
},
|
|
4152
|
+
{
|
|
4153
|
+
"export": "ItemDescription",
|
|
4154
|
+
"reason": "Deprecated alias of the ListItem/ListSubheader name; removed in 4.0"
|
|
4155
|
+
},
|
|
4156
|
+
{
|
|
4157
|
+
"export": "ItemActions",
|
|
4158
|
+
"reason": "Deprecated alias of the ListItem/ListSubheader name; removed in 4.0"
|
|
4159
|
+
},
|
|
4160
|
+
{
|
|
4161
|
+
"export": "ItemSubheader",
|
|
4162
|
+
"reason": "Deprecated alias of the ListItem/ListSubheader name; removed in 4.0"
|
|
4046
4163
|
}
|
|
4047
4164
|
],
|
|
4048
4165
|
"figmaOnly": []
|
|
@@ -4050,11 +4167,78 @@
|
|
|
4050
4167
|
"whenToUse": [
|
|
4051
4168
|
"Rows with media, title, description, and trailing actions (filled)",
|
|
4052
4169
|
"Settings or form-related rows needing a visible border (outline)",
|
|
4053
|
-
"Lightweight lists inside popovers or dropdowns (default)"
|
|
4170
|
+
"Lightweight lists inside popovers or dropdowns (default)",
|
|
4171
|
+
"A row that navigates or opens something: ListItemLink or ListItemButton inside the ListItem, with ListItemChevron",
|
|
4172
|
+
"A drill-down list (label, current value, chevron) such as a phone filters drawer: <List divided> + ListItemButton + ListItemValue + ListItemChevron",
|
|
4173
|
+
"A row whose trailing part is a Switch, Badge, Status, text Button or two actions: put them in ListItemActions",
|
|
4174
|
+
"Logo or icon tiles in front of a row: ListItemMedia variant=\"icon\""
|
|
4054
4175
|
],
|
|
4055
4176
|
"doNotUseFor": [
|
|
4056
4177
|
"tabular data with sortable columns (use Table or DataTable)",
|
|
4057
|
-
"main page content with the default variant (use filled)"
|
|
4178
|
+
"main page content with the default variant (use filled)",
|
|
4179
|
+
"read-only label and value pairs describing one record (use DescriptionList, DS-1124)",
|
|
4180
|
+
"choosing one or several options in a form (use Field, RadioGroup variant=\"box\" or Checkbox)"
|
|
4181
|
+
],
|
|
4182
|
+
"decisions": [
|
|
4183
|
+
{
|
|
4184
|
+
"date": "2026-11-03",
|
|
4185
|
+
"decision": "List follows shadcn's Item anatomy (media with variant default|icon|image, content, title, description, actions, separator) under List-prefixed names: ListItem, ListItemMedia, ListItemContent, ListItemTitle, ListItemDescription, ListItemValue, ListItemChevron, ListItemActions, ListItemButton, ListItemLink for row parts, and ListSubheader, ListSeparator for parts that sit in the list beside rows. The shipped Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions and ItemSubheader stay as deprecated aliases, removed in 4.0. This settles DS-850.",
|
|
4186
|
+
"why": "Structure agreed in refinement on 28 October; the names follow the family-prefix rule (components.md: ListItem, not Item) so every part says which component it belongs to.",
|
|
4187
|
+
"ticket": "DS-1166"
|
|
4188
|
+
},
|
|
4189
|
+
{
|
|
4190
|
+
"date": "2026-11-03",
|
|
4191
|
+
"decision": "A pressable row is an ListItemButton or ListItemLink inside the ListItem. The ListItem stays the <li> and hands its padding to the pressable part, which carries hover and focus-visible.",
|
|
4192
|
+
"why": "Our List renders ul > li. Replacing the li with a link or button would break the list semantics, and the prototypes already hand-built drill-down rows as li > button.",
|
|
4193
|
+
"ticket": "DS-1166"
|
|
4194
|
+
},
|
|
4195
|
+
{
|
|
4196
|
+
"date": "2026-11-03",
|
|
4197
|
+
"decision": "ListItemActions takes any trailing content (min 36px square, gap-2) instead of a fixed 36px circle.",
|
|
4198
|
+
"why": "Switches, Badges, Status, text Buttons and pairs of actions overflowed the circle in six prototype screens.",
|
|
4199
|
+
"ticket": "DS-1166"
|
|
4200
|
+
},
|
|
4201
|
+
{
|
|
4202
|
+
"date": "2026-11-03",
|
|
4203
|
+
"decision": "The drill-down value is its own part, ListItemValue: muted body-sm, right-aligned, truncated past half the row.",
|
|
4204
|
+
"why": "shadcn has no value slot; the Rank Tracker filters drawer needs the current value before the chevron.",
|
|
4205
|
+
"ticket": "DS-1166"
|
|
4206
|
+
},
|
|
4207
|
+
{
|
|
4208
|
+
"date": "2026-11-03",
|
|
4209
|
+
"decision": "truncate on ListItemTitle and ListItemDescription wraps to two lines and clamps the rest (line-clamp-2). The full text appears in a Tooltip only when the text is clamped: on hover, or on keyboard focus of the row's ListItemButton / ListItemLink. The text is never its own tab stop, and a touch tap inside a button, link or label is left to that control.",
|
|
4210
|
+
"why": "Rows need a predictable height, but a clamped name or address must still be readable. Two lines cover most real text with no tooltip; opening it from the row's own focus keeps the row a single interactive target.",
|
|
4211
|
+
"ticket": "DS-1166"
|
|
4212
|
+
}
|
|
4213
|
+
],
|
|
4214
|
+
"ruledOut": [
|
|
4215
|
+
{
|
|
4216
|
+
"option": "ListItem asChild rendering an <a> or <button> as the row (shadcn's Item asChild pattern)",
|
|
4217
|
+
"why": "Swaps out the <li>, so a ul would hold links instead of list items. shadcn's list is div-based; ours is ul > li.",
|
|
4218
|
+
"ticket": "DS-1166"
|
|
4219
|
+
},
|
|
4220
|
+
{
|
|
4221
|
+
"option": "Renaming the ListItem variants (default|filled|outline) to shadcn's names in this change",
|
|
4222
|
+
"why": "Breaking change; kept out of DS-1166 so the new row types ship as a minor. Rename is a separate decision for 4.0.",
|
|
4223
|
+
"ticket": "DS-1166"
|
|
4224
|
+
},
|
|
4225
|
+
{
|
|
4226
|
+
"option": "shadcn's bare Item naming with an ItemGroup alias for List",
|
|
4227
|
+
"why": "The names didn't say which component they belong to; the DS family-prefix rule asks for ListItem, not Item.",
|
|
4228
|
+
"ticket": "DS-1166"
|
|
4229
|
+
}
|
|
4230
|
+
],
|
|
4231
|
+
"knownGaps": [
|
|
4232
|
+
{
|
|
4233
|
+
"description": "Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions and ItemSubheader are deprecated since the DS-1166 release and will be removed in 4.0",
|
|
4234
|
+
"ticket": "DS-1166",
|
|
4235
|
+
"workaround": "Use ListItem, ListItemMedia, ListItemContent, ListItemTitle, ListItemDescription, ListItemActions and ListSubheader (same components)"
|
|
4236
|
+
},
|
|
4237
|
+
{
|
|
4238
|
+
"description": "truncate on a non-pressable ListItem shows its tooltip on hover and tap only; a keyboard user cannot open it because the text is not focusable. TypographyText / TypographyHeading truncate (DS-988) clamp to one line and have no tooltip at all.",
|
|
4239
|
+
"ticket": "DS-1166",
|
|
4240
|
+
"workaround": "Put the full text where the row leads (sheet or page), or make the row a ListItemButton / ListItemLink so its focus opens the tooltip."
|
|
4241
|
+
}
|
|
4058
4242
|
]
|
|
4059
4243
|
},
|
|
4060
4244
|
{
|
|
@@ -4131,6 +4315,142 @@
|
|
|
4131
4315
|
"tight spaces with the full logotype (use the mark variant)"
|
|
4132
4316
|
]
|
|
4133
4317
|
},
|
|
4318
|
+
{
|
|
4319
|
+
"name": "LogoMark",
|
|
4320
|
+
"import": "@brightlocal/ui-components/logo-mark",
|
|
4321
|
+
"category": "display",
|
|
4322
|
+
"exports": [
|
|
4323
|
+
"LogoMark",
|
|
4324
|
+
"SOURCE_ICON_ALIASES"
|
|
4325
|
+
],
|
|
4326
|
+
"compound": false,
|
|
4327
|
+
"dataHookRequired": true,
|
|
4328
|
+
"variants": {
|
|
4329
|
+
"variant": [
|
|
4330
|
+
"transparent",
|
|
4331
|
+
"filled",
|
|
4332
|
+
"border"
|
|
4333
|
+
],
|
|
4334
|
+
"size": [
|
|
4335
|
+
"xs",
|
|
4336
|
+
"sm",
|
|
4337
|
+
"md",
|
|
4338
|
+
"lg"
|
|
4339
|
+
],
|
|
4340
|
+
"colorScheme": [
|
|
4341
|
+
"original",
|
|
4342
|
+
"neutral"
|
|
4343
|
+
]
|
|
4344
|
+
},
|
|
4345
|
+
"props": [
|
|
4346
|
+
"name",
|
|
4347
|
+
"size",
|
|
4348
|
+
"variant",
|
|
4349
|
+
"colorScheme",
|
|
4350
|
+
"fallback",
|
|
4351
|
+
"ariaLabel"
|
|
4352
|
+
],
|
|
4353
|
+
"description": "Displays a brand logo, any lucide icon (globe, star, map-pin, building-2, phone, mail, etc.), or a letter-initial fallback in a consistent mark. Resolves the name against the DS social-media icon registry first, then lucide, loading each icon as its own chunk via iconImports from @brightlocal/icons/dynamic. Variants: filled (bg-muted surface, default), border (border ring), transparent (bare icon). Four sizes: xs, sm, md, lg. colorScheme toggles original/neutral for social-media icons.",
|
|
4354
|
+
"knownGaps": [
|
|
4355
|
+
{
|
|
4356
|
+
"description": "LogoMark inside Radix Select (SingleSelectFilter) fails in Storybook multiview: the dynamic import's async setState destabilises Radix's scroll-lock lifecycle when many variants render simultaneously. Popover-based filters (MultiSelectFilter) are unaffected. This is a Storybook test limitation, not a production bug.",
|
|
4357
|
+
"workaround": "Use static SVG icons from @brightlocal/icons/social-media in Select-based filters instead of LogoMark."
|
|
4358
|
+
}
|
|
4359
|
+
],
|
|
4360
|
+
"i18nProps": {
|
|
4361
|
+
"LogoMark": {
|
|
4362
|
+
"ariaLabel": "string — default: undefined (decorative aria-hidden when omitted; pass to announce as img)"
|
|
4363
|
+
}
|
|
4364
|
+
},
|
|
4365
|
+
"decisions": [
|
|
4366
|
+
{
|
|
4367
|
+
"decision": "Three explicit variants instead of boolean container prop",
|
|
4368
|
+
"why": "transparent/filled/border is clearer than container=true/false + neutral; each variant has a distinct visual treatment",
|
|
4369
|
+
"date": "2026-10-27",
|
|
4370
|
+
"ticket": "DS-1060"
|
|
4371
|
+
},
|
|
4372
|
+
{
|
|
4373
|
+
"decision": "Dual icon resolution: social-media → lucide → letter fallback",
|
|
4374
|
+
"why": "Component is used for both brand logos and generic lucide icons across the product; single name prop resolves both registries",
|
|
4375
|
+
"date": "2026-10-27",
|
|
4376
|
+
"ticket": "DS-1060"
|
|
4377
|
+
},
|
|
4378
|
+
{
|
|
4379
|
+
"decision": "Renamed from SourceLogo to LogoMark",
|
|
4380
|
+
"why": "The component is no longer limited to source/platform logos — it handles any brand or icon mark",
|
|
4381
|
+
"date": "2026-10-27",
|
|
4382
|
+
"ticket": "DS-1060"
|
|
4383
|
+
},
|
|
4384
|
+
{
|
|
4385
|
+
"decision": "colorScheme prop for original vs neutral icon variants",
|
|
4386
|
+
"why": "Location Manager social links row needs monochrome icons; reversed prior ruledOut after discovering prototype usage",
|
|
4387
|
+
"date": "2026-10-28",
|
|
4388
|
+
"ticket": "DS-1060"
|
|
4389
|
+
},
|
|
4390
|
+
{
|
|
4391
|
+
"decision": "Only verified brand artwork enters the social-media registry; sources without one render the letter fallback",
|
|
4392
|
+
"why": "An audit found 168 of 200 generated logos were typographic initials or generic pictograms, not the brands' marks — misrepresenting third-party trademarks while adding nothing over the fallback. Accepted sources: Simple Icons (byte-exact) or the brand's official asset.",
|
|
4393
|
+
"date": "2026-10-28",
|
|
4394
|
+
"ticket": "DS-1060"
|
|
4395
|
+
},
|
|
4396
|
+
{
|
|
4397
|
+
"decision": "Seven brand marks sourced from the brands' own sites/favicons, not brand kits: yellowbot (official logo.svg), opentable (guidelines vector, support-site red), realtor (first-party logo-brand.svg, favicon tile), agoda (official press SVG elements in favicon layout), vrbo (striped V on favicon blue), hotfrog and pagesjaunes (potrace of the official raster icon)",
|
|
4398
|
+
"why": "No brand-supplied standalone SVG exists for these; product shows them at 16–32 px as review-source marks. Hotfrog/PagesJaunes are mechanical traces of official rasters and the Vrbo V comes from the Wikimedia Commons wordmark vectorization — replace with brand files if they ever publish them",
|
|
4399
|
+
"date": "2026-10-28",
|
|
4400
|
+
"ticket": "DS-1060"
|
|
4401
|
+
},
|
|
4402
|
+
{
|
|
4403
|
+
"decision": "Per-icon lazy loading through iconImports from @brightlocal/icons/dynamic",
|
|
4404
|
+
"why": "Importing the social-media barrel pulled every registered icon into one chunk on first render",
|
|
4405
|
+
"date": "2026-10-28",
|
|
4406
|
+
"ticket": "DS-1060"
|
|
4407
|
+
}
|
|
4408
|
+
],
|
|
4409
|
+
"ruledOut": [
|
|
4410
|
+
{
|
|
4411
|
+
"option": "Hand-drawn or AI-generated approximations of brand marks",
|
|
4412
|
+
"why": "Not the brand's logo; see decision of 2026-10-28",
|
|
4413
|
+
"ticket": "DS-1060"
|
|
4414
|
+
}
|
|
4415
|
+
],
|
|
4416
|
+
"figma": {
|
|
4417
|
+
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
4418
|
+
"note": "Mapped on DS-1060 Figma branch eBiPZa4scA07GtyHQP9uY0; node IDs valid after branch merge. State axis uses FIG-5 reserved word — see FIG-32.",
|
|
4419
|
+
"nodes": [
|
|
4420
|
+
{
|
|
4421
|
+
"nodeId": "35320:4945",
|
|
4422
|
+
"figmaName": "Logo Mark",
|
|
4423
|
+
"kind": "componentSet",
|
|
4424
|
+
"export": "LogoMark",
|
|
4425
|
+
"axes": [
|
|
4426
|
+
{
|
|
4427
|
+
"figma": "Variant",
|
|
4428
|
+
"code": "variant"
|
|
4429
|
+
},
|
|
4430
|
+
{
|
|
4431
|
+
"figma": "Size",
|
|
4432
|
+
"code": "size"
|
|
4433
|
+
},
|
|
4434
|
+
{
|
|
4435
|
+
"figma": "Color Scheme",
|
|
4436
|
+
"code": "colorScheme"
|
|
4437
|
+
},
|
|
4438
|
+
{
|
|
4439
|
+
"figma": "State",
|
|
4440
|
+
"exempt": "figma-only-style",
|
|
4441
|
+
"note": "Known/Fallback is a runtime resolution outcome (not a consumer prop); demonstrates the two visual states"
|
|
4442
|
+
}
|
|
4443
|
+
]
|
|
4444
|
+
}
|
|
4445
|
+
],
|
|
4446
|
+
"unmappedExports": [
|
|
4447
|
+
{
|
|
4448
|
+
"export": "SOURCE_ICON_ALIASES",
|
|
4449
|
+
"reason": "Constant (Record<string, string>) — not a component, no Figma representation"
|
|
4450
|
+
}
|
|
4451
|
+
]
|
|
4452
|
+
}
|
|
4453
|
+
},
|
|
4134
4454
|
{
|
|
4135
4455
|
"name": "Map",
|
|
4136
4456
|
"import": "@brightlocal/ui-components/map",
|
|
@@ -4304,6 +4624,162 @@
|
|
|
4304
4624
|
}
|
|
4305
4625
|
}
|
|
4306
4626
|
},
|
|
4627
|
+
{
|
|
4628
|
+
"name": "MediaViewer",
|
|
4629
|
+
"import": "@brightlocal/ui-components/media-viewer",
|
|
4630
|
+
"category": "overlay",
|
|
4631
|
+
"exports": [
|
|
4632
|
+
"MediaViewer",
|
|
4633
|
+
"MediaViewerTrigger",
|
|
4634
|
+
"MediaViewerAddon",
|
|
4635
|
+
"MediaViewerContent",
|
|
4636
|
+
"MediaViewerTitle",
|
|
4637
|
+
"MediaViewerActions"
|
|
4638
|
+
],
|
|
4639
|
+
"compound": true,
|
|
4640
|
+
"dataHookRequired": true,
|
|
4641
|
+
"variants": {},
|
|
4642
|
+
"props": [
|
|
4643
|
+
"items",
|
|
4644
|
+
"index",
|
|
4645
|
+
"defaultIndex",
|
|
4646
|
+
"onIndexChange",
|
|
4647
|
+
"open",
|
|
4648
|
+
"defaultOpen",
|
|
4649
|
+
"onOpenChange",
|
|
4650
|
+
"actions",
|
|
4651
|
+
"formatActionsLabel",
|
|
4652
|
+
"viewable",
|
|
4653
|
+
"indicator",
|
|
4654
|
+
"formatPosition",
|
|
4655
|
+
"previousLabel",
|
|
4656
|
+
"nextLabel",
|
|
4657
|
+
"thumbnailsLabel",
|
|
4658
|
+
"unavailableMessage",
|
|
4659
|
+
"formatLabel",
|
|
4660
|
+
"zoomInLabel",
|
|
4661
|
+
"zoomOutLabel",
|
|
4662
|
+
"downloadLabel",
|
|
4663
|
+
"infoLabel",
|
|
4664
|
+
"dateLabels"
|
|
4665
|
+
],
|
|
4666
|
+
"description": "One family for an image set, modelled on Telegram's media view. MediaViewer (root, no DOM) owns items, the open index and whether the lightbox is open — uncontrolled by default, controllable via open/onOpenChange and index/onIndexChange. MediaViewerTrigger is a fixed-ratio preview that is a button; it opens the lightbox at its index (one tile or a grid is the same markup), indicator adds dots for the set and lets the preview be browsed in place (swipe, arrow keys) before opening, MediaViewerAddon children lie over a corner (align top-start/top-end/bottom-start/bottom-end: a position Badge, a status), beside the button so they stay out of its name; the root's actions (DropdownMenuItems per item) appear behind a More actions button on each preview (top-right, on hover/focus/open, always on touch) and in the view's bar after Download, MediaEmpty when there is no item; while the view is open, the preview of the open item is hidden in place, as if the image had lifted out of it. MediaViewerContent is a lightbox that fills the window over a backdrop darker than a modal's (text and controls in scoped dark tokens): the image with Previous/Next as full-height clickable strips at its sides (shown on hover or keyboard focus; touch and trackpad swipes drag the image carousel-style and step or spring back; buttons, keys and thumbnails swap at once), no close button (Esc or a click on the image or backdrop closes), and a bottom bar — MediaViewerTitle on the left over the open item's description (its alt, shown for the eye) and date (a RelativeDate from items[].date), a strip of thumbnails in the middle (the open one at full opacity, aria-current, kept in view), the built-in Download / Zoom in / Zoom out on the right, then MediaViewerActions (the consumer's extra actions: share, a menu), the item's More actions and, last, Image details (an InfoTooltip: format, size in pixels and file size); on phones the strip takes its own row. Opening zooms the image out of its preview and closing zooms it back in, slightly faster (fade with reduced motion or no preview on screen); stepping swaps the image with no animation. Photos are fitted, never past their own pixels (a small image shows at its size); a capture far taller than wide (over 2.5:1) keeps the stage width (or its own, if narrower) and scrolls. A title or description cut to one line shows the full text on hover. Arrow keys step, focus returns to the opening trigger, the position is announced in a visually hidden polite live region. An expired item or failed load shows MediaEmpty in the same frame. A long set stays light: three slides on the stage, lazy thumbnails, at most five indicator dots.",
|
|
4667
|
+
"aliases": [
|
|
4668
|
+
"lightbox",
|
|
4669
|
+
"photo viewer",
|
|
4670
|
+
"image viewer",
|
|
4671
|
+
"screenshot viewer",
|
|
4672
|
+
"gallery dialog",
|
|
4673
|
+
"thumbnail",
|
|
4674
|
+
"photo tile",
|
|
4675
|
+
"image preview",
|
|
4676
|
+
"preview tile",
|
|
4677
|
+
"screenshot thumbnail",
|
|
4678
|
+
"photo gallery"
|
|
4679
|
+
],
|
|
4680
|
+
"whenToUse": [
|
|
4681
|
+
"A preview of an image, or a grid of them, that opens a full view and steps through the set (saved screenshots, business photos)"
|
|
4682
|
+
],
|
|
4683
|
+
"doNotUseFor": [
|
|
4684
|
+
"a plain non-interactive image (use AspectRatio with an img)",
|
|
4685
|
+
"a missing-media slot with nothing to open (use MediaEmpty)",
|
|
4686
|
+
"a form or free-form content in a modal (use Dialog)",
|
|
4687
|
+
"an inline slideshow on the page (use Carousel)"
|
|
4688
|
+
],
|
|
4689
|
+
"i18nProps": {
|
|
4690
|
+
"MediaViewer": {
|
|
4691
|
+
"formatActionsLabel": "(item, index) => string — default: \"More actions for {item.alt}\" (\"image {index + 1}\" when alt is empty)"
|
|
4692
|
+
},
|
|
4693
|
+
"MediaViewerContent": {
|
|
4694
|
+
"previousLabel": "string — default: \"Previous\"",
|
|
4695
|
+
"nextLabel": "string — default: \"Next\"",
|
|
4696
|
+
"thumbnailsLabel": "string — default: \"Images\"",
|
|
4697
|
+
"zoomInLabel": "string — default: \"Zoom in\"",
|
|
4698
|
+
"zoomOutLabel": "string — default: \"Zoom out\"",
|
|
4699
|
+
"downloadLabel": "string — default: \"Download\"",
|
|
4700
|
+
"infoLabel": "string — default: \"Image details\" (the ⓘ button; its tooltip shows format, size in pixels and file size)",
|
|
4701
|
+
"dateLabels": "Partial<RelativeDateLabels> — default: RelativeDate's English words",
|
|
4702
|
+
"unavailableMessage": "string — default: \"Image no longer available\"",
|
|
4703
|
+
"formatPosition": "(current, total) => string — default: \"{current} of {total}\""
|
|
4704
|
+
},
|
|
4705
|
+
"MediaViewerTrigger": {
|
|
4706
|
+
"emptyMessage": "string — default: \"No photo available\"",
|
|
4707
|
+
"unavailableMessage": "string — default: \"Image no longer available\"",
|
|
4708
|
+
"formatLabel": "(item, index, total) => string — default: item.alt, or \"Image {index + 1} of {total}\" when it is empty (the button's name)"
|
|
4709
|
+
}
|
|
4710
|
+
},
|
|
4711
|
+
"a11yContract": {
|
|
4712
|
+
"role": "dialog",
|
|
4713
|
+
"requiresLabel": true,
|
|
4714
|
+
"keyboardInteraction": [
|
|
4715
|
+
"Escape",
|
|
4716
|
+
"ArrowLeft",
|
|
4717
|
+
"ArrowRight",
|
|
4718
|
+
"+",
|
|
4719
|
+
"-",
|
|
4720
|
+
"Tab"
|
|
4721
|
+
]
|
|
4722
|
+
},
|
|
4723
|
+
"states": [
|
|
4724
|
+
"open",
|
|
4725
|
+
"closed"
|
|
4726
|
+
],
|
|
4727
|
+
"decisions": [
|
|
4728
|
+
{
|
|
4729
|
+
"date": "2026-10-31",
|
|
4730
|
+
"decision": "One family: MediaViewerTrigger (the preview, a button) and MediaViewerContent (the view). A trigger opens the full view directly; MediaTile was merged in before release.",
|
|
4731
|
+
"why": "A preview and its viewer always come together and share the set and the open index; two states (preview, view) are all the reader needs.",
|
|
4732
|
+
"ticket": "DS-1204"
|
|
4733
|
+
},
|
|
4734
|
+
{
|
|
4735
|
+
"date": "2026-10-31",
|
|
4736
|
+
"decision": "The view fills the window over the standard modal backdrop and has no close button: Esc or a click on the image or the backdrop closes it.",
|
|
4737
|
+
"why": "Same backdrop as every modal; the whole stage is the close target, as in Telegram's viewer.",
|
|
4738
|
+
"ticket": "DS-1204"
|
|
4739
|
+
},
|
|
4740
|
+
{
|
|
4741
|
+
"date": "2026-11-01",
|
|
4742
|
+
"decision": "The view's backdrop is darker than a modal's (black at 85%), and the bottom bar has no shade of its own.",
|
|
4743
|
+
"why": "Over the modal backdrop the page showed through the bar, so its text needed a gradient band, which read as a hard dark strip. A darker backdrop makes the page fall away and keeps the title, description and controls legible with nothing behind them.",
|
|
4744
|
+
"ticket": "DS-1204"
|
|
4745
|
+
},
|
|
4746
|
+
{
|
|
4747
|
+
"date": "2026-11-01",
|
|
4748
|
+
"decision": "An image opens at most at its own size: a file smaller than the stage (a 150 px logo) shows at its pixels, not stretched to fill. Zoom in enlarges it when the reader wants.",
|
|
4749
|
+
"why": "Stretching a small file to the stage made it blurry; the Zoom buttons already give a bigger view on demand.",
|
|
4750
|
+
"ticket": "DS-1204"
|
|
4751
|
+
},
|
|
4752
|
+
{
|
|
4753
|
+
"date": "2026-10-31",
|
|
4754
|
+
"decision": "Previous / Next are full-height strips and the thumbnails are image buttons, both raw <button>; the arrow is drawn with ButtonVariants ghost.",
|
|
4755
|
+
"why": "No DS component is a full-height hit strip or an image thumbnail; a Button would need appearance overrides.",
|
|
4756
|
+
"ticket": "DS-1204"
|
|
4757
|
+
},
|
|
4758
|
+
{
|
|
4759
|
+
"date": "2026-10-31",
|
|
4760
|
+
"decision": "Trackpad swipes follow yet-another-react-lightbox's wheel swipe: 30px of intent, follow one to one, step past a fifth of the stage, spring back after 600ms of rest; while the image glides in, input the same way is inertia.",
|
|
4761
|
+
"why": "A widely used, well-tried approach rather than one tuned to a single trackpad.",
|
|
4762
|
+
"ticket": "DS-1204"
|
|
4763
|
+
}
|
|
4764
|
+
],
|
|
4765
|
+
"ruledOut": [
|
|
4766
|
+
{
|
|
4767
|
+
"option": "The browser Fullscreen API for the view",
|
|
4768
|
+
"why": "Permission prompts and no support on iOS; a window-filling dialog does the same everywhere.",
|
|
4769
|
+
"ticket": "DS-1204"
|
|
4770
|
+
},
|
|
4771
|
+
{
|
|
4772
|
+
"option": "Three states: preview, a modal, then full screen",
|
|
4773
|
+
"why": "An extra step between the preview and the image; the preview opens the full view.",
|
|
4774
|
+
"ticket": "DS-1204"
|
|
4775
|
+
},
|
|
4776
|
+
{
|
|
4777
|
+
"option": "Reading the finger lift from wheel deltas (deceleration, short quiet timers)",
|
|
4778
|
+
"why": "Unreliable across trackpads: it stalled swipes half-way, dropped quick second swipes and ran fast ones through the set.",
|
|
4779
|
+
"ticket": "DS-1204"
|
|
4780
|
+
}
|
|
4781
|
+
]
|
|
4782
|
+
},
|
|
4307
4783
|
{
|
|
4308
4784
|
"name": "Menubar",
|
|
4309
4785
|
"import": "@brightlocal/ui-components/menubar",
|
|
@@ -4428,10 +4904,205 @@
|
|
|
4428
4904
|
"Power-user, keyboard-navigable tools expecting app-menu structure",
|
|
4429
4905
|
"Internal or admin tools modeled after desktop software conventions"
|
|
4430
4906
|
],
|
|
4431
|
-
"doNotUseFor": [
|
|
4432
|
-
"a single dropdown of actions (use DropdownMenu)",
|
|
4433
|
-
"mobile or touch-first contexts",
|
|
4434
|
-
"primary app navigation (use NavigationMenu or Sidebar)"
|
|
4907
|
+
"doNotUseFor": [
|
|
4908
|
+
"a single dropdown of actions (use DropdownMenu)",
|
|
4909
|
+
"mobile or touch-first contexts",
|
|
4910
|
+
"primary app navigation (use NavigationMenu or Sidebar)"
|
|
4911
|
+
]
|
|
4912
|
+
},
|
|
4913
|
+
{
|
|
4914
|
+
"name": "MultiSelectFilter",
|
|
4915
|
+
"import": "@brightlocal/ui-components/multi-select-filter",
|
|
4916
|
+
"category": "form",
|
|
4917
|
+
"exports": [
|
|
4918
|
+
"MultiSelectFilter",
|
|
4919
|
+
"multiSelectFilterTriggerVariants"
|
|
4920
|
+
],
|
|
4921
|
+
"compound": false,
|
|
4922
|
+
"dataHookRequired": true,
|
|
4923
|
+
"variants": {
|
|
4924
|
+
"size": [
|
|
4925
|
+
"default",
|
|
4926
|
+
"sm"
|
|
4927
|
+
]
|
|
4928
|
+
},
|
|
4929
|
+
"props": [
|
|
4930
|
+
"label",
|
|
4931
|
+
"options",
|
|
4932
|
+
"value",
|
|
4933
|
+
"defaultValue",
|
|
4934
|
+
"onValueChange",
|
|
4935
|
+
"open",
|
|
4936
|
+
"onOpenChange",
|
|
4937
|
+
"icon",
|
|
4938
|
+
"maxVisibleLabels",
|
|
4939
|
+
"allLabel",
|
|
4940
|
+
"allCount",
|
|
4941
|
+
"searchThreshold",
|
|
4942
|
+
"searchable",
|
|
4943
|
+
"disabled",
|
|
4944
|
+
"presentation",
|
|
4945
|
+
"collapseFullSelection",
|
|
4946
|
+
"allIcon"
|
|
4947
|
+
],
|
|
4948
|
+
"description": "The Filtering pattern's several-at-once filter: one dimension, several values combining as OR, over a Popover + Command menu that stays open across picks. The trigger hugs its label in a toolbar and wears the Select field look (border, radius, focus ring, chevron) because a filter trigger holds a value, it does not act; stacked in a panel it takes className='w-full'. No error state — a filter does not validate. size='default' (h-9, text-field like Select: 14px desktop / 16px touch) or 'sm' (h-8, text-label, phone card headers). The trigger always reads its picks, like a Select shows its value: allLabel at zero (or the dimension's label, muted, as a placeholder), then the picked labels, collapsing past maxVisibleLabels (default 1) into summaryLabel ('Google +2' via the default '{labels} +{rest}'; '3 selected' via '{count} selected') — and it computes the accessible name itself with every pick spelled out. Glyphs are the consumer's, never a fixed funnel: option.icon shows before each label in the menu and drawer, allIcon marks the All row, and the trigger follows the selection (allIcon at zero, then the first pick's icon) unless icon pins one. No-match shows the compact empty form (muted chip, emptyLabel, emptyDescription) in both presentations. allLabel adds a leading reset row: 'All' means no narrowing, so it is checked when value is empty and picking it clears the selection; a pick that completes the set collapses to [] for the same reason (collapseFullSelection, default true). Picks read on the trigger in pick order. Selected values pin to the top on reopen; a zero-count option is disabled, never hidden; past searchThreshold (10) the menu grows an autofocused search input (searchable forces it) — a case-insensitive substring match on label and value, never on the count; while searching the All row and Clear step aside, and a no-match search shows emptyLabel alone. presentation='menu' (default) is the Popover + Command menu; 'drawer' is the phone form — the same trigger opens a bottom Drawer titled with the dimension, All row, options as Checkboxes in two columns, search past the threshold, Clear while something is picked, a Done button that only closes (ticks apply at once); 'auto' switches at the md breakpoint. Both render from one state. Per-filter commit model: onValueChange on every pick, run an expensive refetch on onOpenChange(false). multiSelectFilterTriggerVariants is the trigger's cva style helper.",
|
|
4949
|
+
"i18nProps": {
|
|
4950
|
+
"MultiSelectFilter": {
|
|
4951
|
+
"clearLabel": "string — default: \"Clear filters\"",
|
|
4952
|
+
"summaryLabel": "string — default: \"{labels} +{rest}\" (placeholders: {labels}, {rest}, {count})",
|
|
4953
|
+
"searchPlaceholder": "string — default: \"Search options...\"",
|
|
4954
|
+
"emptyLabel": "string — default: \"No options found.\"",
|
|
4955
|
+
"doneLabel": "string — default: \"Done\" (the drawer's close button)",
|
|
4956
|
+
"drawerDescription": "string — default: \"Picks apply as you make them.\" (sr-only drawer description)",
|
|
4957
|
+
"emptyDescription": "string — default: \"Try another search.\" (hint under the no-match message)",
|
|
4958
|
+
"clearSearchAriaLabel": "string — default: \"Clear search\" (the menu and drawer search clear button)"
|
|
4959
|
+
}
|
|
4960
|
+
},
|
|
4961
|
+
"whenToUse": [
|
|
4962
|
+
"Picking several values from one dimension that combine as OR (status, source, city) in a filter bar",
|
|
4963
|
+
"A filter whose trigger reads its current picks ('All sources', 'Google +2') like a Select shows its value, with every pick in the accessible name",
|
|
4964
|
+
"Stacked in a filter panel or sidebar — className='w-full' takes the row's width; same component, no form-field variant",
|
|
4965
|
+
"Any option list past ~10 values — the menu's autofocused search input and pinned selections handle it",
|
|
4966
|
+
"Desktop: presentation='menu' (default), the Popover + Command menu beside a Select in a toolbar (size='default', h-9, text-field)",
|
|
4967
|
+
"Phone: presentation='drawer' opens the same picks as a bottom Drawer (Checkbox rows in two columns, search past the threshold, Clear, Done only closes); presentation='auto' switches at the md breakpoint; size='sm' (h-8) for card headers — no hand-rolled drawer per filter"
|
|
4968
|
+
],
|
|
4969
|
+
"doNotUseFor": [
|
|
4970
|
+
"picking exactly one value from a filter dimension (use SingleSelectFilter — it shares the trigger look and the drawer, with a DS Select on desktop and RadioGroup in the drawer)",
|
|
4971
|
+
"2–5 values with room to show them all (use ToggleGroup, or the Lab SegmentedControl quick filter)",
|
|
4972
|
+
"typing new values into the selection (use InputChip)",
|
|
4973
|
+
"a form field that validates and submits — this is a filter and has no error state; a form multi-select is a separate component",
|
|
4974
|
+
"a 'Filters (n)' button opening a panel of hidden filters — not a DS pattern: every filter shows its own value in the toolbar row (Patterns/Filtering)",
|
|
4975
|
+
"a batch drawer of several filters behind one Apply — not a DS pattern: on a phone each filter opens its own drawer (presentation='auto')"
|
|
4976
|
+
],
|
|
4977
|
+
"alternatives": [
|
|
4978
|
+
{
|
|
4979
|
+
"component": "Select",
|
|
4980
|
+
"rule": "Use Select for a single choice from a short, known list"
|
|
4981
|
+
},
|
|
4982
|
+
{
|
|
4983
|
+
"component": "Combobox",
|
|
4984
|
+
"rule": "Use Combobox for a single choice from a long, searchable list — it is single-value by design"
|
|
4985
|
+
},
|
|
4986
|
+
{
|
|
4987
|
+
"component": "ToggleGroup",
|
|
4988
|
+
"rule": "Use ToggleGroup (or the Lab SegmentedControl) for a quick filter kept visible in the bar"
|
|
4989
|
+
},
|
|
4990
|
+
{
|
|
4991
|
+
"component": "InputChip",
|
|
4992
|
+
"rule": "Use InputChip when the person types new values rather than picking existing ones"
|
|
4993
|
+
},
|
|
4994
|
+
{
|
|
4995
|
+
"component": "Drawer",
|
|
4996
|
+
"rule": "presentation='drawer' (or 'auto' below md) opens this filter's picks in a bottom Drawer; there is no batch drawer holding several filters"
|
|
4997
|
+
},
|
|
4998
|
+
{
|
|
4999
|
+
"component": "Chip",
|
|
5000
|
+
"rule": "Never repeat a MultiSelectFilter's picks as Chips — the trigger already reads them ('Google +2')"
|
|
5001
|
+
},
|
|
5002
|
+
{
|
|
5003
|
+
"component": "SingleSelectFilter",
|
|
5004
|
+
"rule": "Use SingleSelectFilter for one value from a dimension — it shares the trigger look and the drawer, with a DS Select on desktop"
|
|
5005
|
+
}
|
|
5006
|
+
],
|
|
5007
|
+
"figma": {
|
|
5008
|
+
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
5009
|
+
"nodes": [
|
|
5010
|
+
{
|
|
5011
|
+
"nodeId": "34233:70287",
|
|
5012
|
+
"figmaName": "Multi Select Filter",
|
|
5013
|
+
"kind": "componentSet",
|
|
5014
|
+
"export": "MultiSelectFilter",
|
|
5015
|
+
"note": "Built on branch task/DS-1023-faced-filter (2026-10-08); node ids persist on merge. Draws the trigger (Text, Show Icon + Icon swap); the menu is the figmaOnly sub-parts below.",
|
|
5016
|
+
"axes": [
|
|
5017
|
+
{
|
|
5018
|
+
"figma": "Size",
|
|
5019
|
+
"code": "size"
|
|
5020
|
+
},
|
|
5021
|
+
{
|
|
5022
|
+
"figma": "State",
|
|
5023
|
+
"exempt": "interaction-state",
|
|
5024
|
+
"valueToProp": {
|
|
5025
|
+
"Disabled": "disabled"
|
|
5026
|
+
},
|
|
5027
|
+
"note": "Focus and Open are runtime states"
|
|
5028
|
+
}
|
|
5029
|
+
]
|
|
5030
|
+
}
|
|
5031
|
+
],
|
|
5032
|
+
"unmappedExports": [
|
|
5033
|
+
{
|
|
5034
|
+
"export": "multiSelectFilterTriggerVariants",
|
|
5035
|
+
"reason": "cva style helper, not a component — the Multi Select Filter set's variants are its drawing"
|
|
5036
|
+
}
|
|
5037
|
+
],
|
|
5038
|
+
"figmaOnly": [
|
|
5039
|
+
{
|
|
5040
|
+
"nodeId": "34233:70355",
|
|
5041
|
+
"figmaName": "Multi Select Filter / Menu Item",
|
|
5042
|
+
"reason": "The menu row MultiSelectFilter renders internally (CommandItem + Checkbox look + count); no sub-part export by design — one component, one engine. Checked/State are runtime states."
|
|
5043
|
+
},
|
|
5044
|
+
{
|
|
5045
|
+
"nodeId": "34233:70435",
|
|
5046
|
+
"figmaName": "Multi Select Filter / Menu",
|
|
5047
|
+
"reason": "The Popover + Command menu MultiSelectFilter renders internally (search, All row, options, empty, Clear); no sub-part export by design."
|
|
5048
|
+
}
|
|
5049
|
+
]
|
|
5050
|
+
},
|
|
5051
|
+
"aliases": [
|
|
5052
|
+
"faceted filter",
|
|
5053
|
+
"facet filter",
|
|
5054
|
+
"multi-select",
|
|
5055
|
+
"multi select dropdown",
|
|
5056
|
+
"filter dropdown",
|
|
5057
|
+
"checkbox filter",
|
|
5058
|
+
"filter menu",
|
|
5059
|
+
"mobile filter drawer"
|
|
5060
|
+
],
|
|
5061
|
+
"replaces": [
|
|
5062
|
+
"Lab FacetedFilter",
|
|
5063
|
+
"Lab SearchableMultiSelect",
|
|
5064
|
+
"Lab FilterTrigger (as multiSelectFilterTriggerVariants + Badge srLabel)",
|
|
5065
|
+
"per-app faceted-filter copies in the prototypes"
|
|
5066
|
+
],
|
|
5067
|
+
"states": [
|
|
5068
|
+
"closed",
|
|
5069
|
+
"open (menu)",
|
|
5070
|
+
"open (drawer)",
|
|
5071
|
+
"searching",
|
|
5072
|
+
"no match",
|
|
5073
|
+
"disabled"
|
|
5074
|
+
],
|
|
5075
|
+
"a11yContract": {
|
|
5076
|
+
"role": "button (trigger, aria-label computed: '{label}: {every pick}') → Popover with a cmdk listbox of aria-checked options, or a Drawer dialog titled with the dimension",
|
|
5077
|
+
"requiresLabel": true,
|
|
5078
|
+
"keyboardInteraction": [
|
|
5079
|
+
"Enter/Space opens",
|
|
5080
|
+
"Arrow keys move between options (cmdk root takes focus when there is no search input)",
|
|
5081
|
+
"Enter toggles the highlighted option; the menu stays open",
|
|
5082
|
+
"Type to narrow past the search threshold",
|
|
5083
|
+
"Escape closes and returns focus to the trigger"
|
|
5084
|
+
]
|
|
5085
|
+
},
|
|
5086
|
+
"knownGaps": [
|
|
5087
|
+
{
|
|
5088
|
+
"description": "The trigger hugs its text, so its width moves with the reading ('All sources' → 'Google' → 'Google +2'); Select solves this with reserveValues, MultiSelectFilter does not yet",
|
|
5089
|
+
"workaround": "Keep maxVisibleLabels at its default of 1; where neighbours must not shift, add className='min-w-40' (a layout class) sized to the dimension's longest label"
|
|
5090
|
+
}
|
|
5091
|
+
],
|
|
5092
|
+
"decisions": [
|
|
5093
|
+
{
|
|
5094
|
+
"date": "2026-11-02",
|
|
5095
|
+
"decision": "A MultiSelectFilter with nothing to choose — no time range after a single update, no source with reviews — stays in place, disabled and reset to its All option, with one line under the toolbar saying why. Only a filter that can never apply to the account is left out of the toolbar. An option with nothing behind it stays in the list, greyed with its count.",
|
|
5096
|
+
"why": "A filter that comes and goes moves the toolbar and makes the user hunt for it; a disabled one with a reason teaches the product (Carbon: disable, don't hide). The reason is a helper line, not a tooltip, because the disabled trigger takes no pointer events.",
|
|
5097
|
+
"ticket": "DS-973"
|
|
5098
|
+
}
|
|
5099
|
+
],
|
|
5100
|
+
"ruledOut": [
|
|
5101
|
+
{
|
|
5102
|
+
"option": "Hiding the filter when the current data leaves it nothing to choose",
|
|
5103
|
+
"why": "Greenfield did this (a one-update report hid Time period and Interval) and the toolbar shifted between states; the Filtering pattern keeps every filter in place and explains it instead.",
|
|
5104
|
+
"ticket": "DS-973"
|
|
5105
|
+
}
|
|
4435
5106
|
]
|
|
4436
5107
|
},
|
|
4437
5108
|
{
|
|
@@ -4569,7 +5240,10 @@
|
|
|
4569
5240
|
"nextAriaLabel": "string — default: \"Go to next page\"",
|
|
4570
5241
|
"pageAriaLabel": "string — default: \"Go to page {page}\"",
|
|
4571
5242
|
"ellipsisSrLabel": "string — default: \"More pages\"",
|
|
4572
|
-
"renderCaption": "render prop —
|
|
5243
|
+
"renderCaption": "render prop — plain-text escape hatch; prefer captionLabel",
|
|
5244
|
+
"captionLabel": "string — default: \"{from} to {to} of {total} results\"",
|
|
5245
|
+
"captionLabelOne": "string — default: \"{from} to {to} of {total} result\"; used at total === 1",
|
|
5246
|
+
"captionEmptyLabel": "string — default: \"No results\"; screen-reader-only at zero items"
|
|
4573
5247
|
},
|
|
4574
5248
|
"PaginationPrevious": {
|
|
4575
5249
|
"ariaLabel": "string — default: \"Go to previous page\""
|
|
@@ -4649,6 +5323,14 @@
|
|
|
4649
5323
|
"lists inside a Data Table (use its built-in pagination)",
|
|
4650
5324
|
"continuously loading content (use infinite scroll)",
|
|
4651
5325
|
"result sets that fit on one screen"
|
|
5326
|
+
],
|
|
5327
|
+
"decisions": [
|
|
5328
|
+
{
|
|
5329
|
+
"date": "2026-09-09",
|
|
5330
|
+
"decision": "Pagination hides itself when there is nothing to navigate (one page or fewer); consumers do not add their own totalPages > 1 guard.",
|
|
5331
|
+
"why": "A lone disabled arrow pair reads as a broken control rather than a boundary. DataTablePaginationNav and PaginationControls must agree.",
|
|
5332
|
+
"ticket": "DS-900"
|
|
5333
|
+
}
|
|
4652
5334
|
]
|
|
4653
5335
|
},
|
|
4654
5336
|
{
|
|
@@ -4750,6 +5432,10 @@
|
|
|
4750
5432
|
"size": [
|
|
4751
5433
|
"sm",
|
|
4752
5434
|
"md"
|
|
5435
|
+
],
|
|
5436
|
+
"labelPlacement": [
|
|
5437
|
+
"inline",
|
|
5438
|
+
"above"
|
|
4753
5439
|
]
|
|
4754
5440
|
},
|
|
4755
5441
|
"props": [
|
|
@@ -4757,18 +5443,17 @@
|
|
|
4757
5443
|
"max",
|
|
4758
5444
|
"color",
|
|
4759
5445
|
"size",
|
|
5446
|
+
"labelPlacement",
|
|
4760
5447
|
"showValue",
|
|
4761
5448
|
"unit",
|
|
4762
5449
|
"valueFormatter",
|
|
4763
5450
|
"ariaLabel",
|
|
4764
5451
|
"label",
|
|
4765
|
-
"statusDescription",
|
|
4766
|
-
"indeterminate",
|
|
4767
5452
|
"labelWidth",
|
|
4768
5453
|
"indicatorClassName",
|
|
4769
5454
|
"disabled"
|
|
4770
5455
|
],
|
|
4771
|
-
"description": "Progress bar indicator with optional
|
|
5456
|
+
"description": "Progress bar indicator with optional label (text, or a node such as a Rating or icon) placed inline or stacked above, numeric value with optional custom formatting, and score-scale color options",
|
|
4772
5457
|
"i18nProps": {
|
|
4773
5458
|
"Progress": {
|
|
4774
5459
|
"ariaLabel": "string — default: \"Progress\" (required when `label` is an element)"
|
|
@@ -4782,7 +5467,7 @@
|
|
|
4782
5467
|
"figmaName": "Progress",
|
|
4783
5468
|
"kind": "componentSet",
|
|
4784
5469
|
"export": "Progress",
|
|
4785
|
-
"note": "Show label / Label text (TEXT) ↔ `label`; Show value ↔ `showValue`; `disabled` has no variant by decision — shown as a 50%-opacity instance in the Playground; Fill ↔ `value` (fill + Number text); Fraction form (BOOLEAN) / Max (TEXT) / Unit (TEXT) ↔ `unit !== \"%\"` / `max` / `unit`. Label column is the exposed nested set Progress / Label — Width Auto | 20% | 30% | 40% | 50% (default 40%) + Label text = code labelWidth (\"auto\" | \"20%\"–\"50%\", default \"40%\") + label; % values are fixed px at the 364 base since Figma has no % sizing; long labels wrap (never truncate); Value layer hugs with a 40px minimum, right-aligned (code sizes it to the widest value automatically). Indicator/Track use the
|
|
5470
|
+
"note": "Show label / Label text (TEXT) ↔ `label`; Show value ↔ `showValue`; `disabled` has no variant by decision — shown as a 50%-opacity instance in the Playground; Fill ↔ `value` (fill + Number text); Fraction form (BOOLEAN) / Max (TEXT) / Unit (TEXT) ↔ `unit !== \"%\"` / `max` / `unit`. Label column is the exposed nested set Progress / Label — Width Auto | 20% | 30% | 40% | 50% (default 40%) + Label text = code labelWidth (\"auto\" | \"20%\"–\"50%\", default \"40%\") + label; % values are fixed px at the 364 base since Figma has no % sizing; long labels wrap (never truncate); Value layer hugs with a 40px minimum, right-aligned (code sizes it to the widest value automatically). Indicator/Track use the score scale (score-strong/moderate/weak/poor, track at /20; DS-774) — Figma binds the same base/score-* variables. Text style text-xs/leading-normal = 16px = Tailwind text-xs default line-height. DS-773. DS-1024: `label` also accepts an element (Rating, icon) with a required `ariaLabel` ↔ Progress / Label `Type = Text | Element` VARIANT (the code's two label shapes; an export-discriminator axis if the Label set is ever mapped) + `Element` INSTANCE_SWAP (default Rating Size=Small; preferred Rating, Progress / Element / Thumbs Up, Progress / Element / Thumbs Down — 16px icons in hugging frames); drawn on the DS-1024 branch (FIG-29, mapping after merge); `valueFormatter` output (e.g. a raw count) maps to the overridable Number text.",
|
|
4786
5471
|
"axes": [
|
|
4787
5472
|
{
|
|
4788
5473
|
"figma": "Colour",
|
|
@@ -4813,6 +5498,32 @@
|
|
|
4813
5498
|
"stalled or failed tasks (use Alert for the failure)",
|
|
4814
5499
|
"unknown waits with no real percentage (Skeleton covers initial content loading)",
|
|
4815
5500
|
"static scores with the green variant (colored variant is the meter-style option)"
|
|
5501
|
+
],
|
|
5502
|
+
"decisions": [
|
|
5503
|
+
{
|
|
5504
|
+
"date": "2026-09-10",
|
|
5505
|
+
"decision": "Progress is determinate only: indeterminate and statusDescription were removed (breaking, 3.0.0).",
|
|
5506
|
+
"why": "A bar that cannot measure anything is decoration pretending to be data. A wait with nothing to measure uses Spinner (short), Skeleton (known geometry) or ProgressState (minutes); the step name belongs in ProgressState's description, which is already the live region.",
|
|
5507
|
+
"ticket": "DS-908"
|
|
5508
|
+
},
|
|
5509
|
+
{
|
|
5510
|
+
"date": "2026-10-30",
|
|
5511
|
+
"decision": "labelPlacement prop (\"inline\" | \"above\", default \"inline\") stacks the label row above the bar instead of fixing a label column width. Named labelPlacement (not orientation) because only the label position changes — matches Stepper's naming precedent.",
|
|
5512
|
+
"why": "In narrow columns (< 200 px) the fixed-width label column leaves almost no room for the bar, making it unreadable. Stacking lets the label and bar each use full width. Second consumer request in a month (after DS-1024) confirmed the pattern gap.",
|
|
5513
|
+
"ticket": "DS-1217"
|
|
5514
|
+
}
|
|
5515
|
+
],
|
|
5516
|
+
"ruledOut": [
|
|
5517
|
+
{
|
|
5518
|
+
"option": "An indeterminate (sweeping) Progress bar",
|
|
5519
|
+
"why": "It invites the reader to look for a number that is not coming; every case it covered has a better component (Spinner, Skeleton, ProgressState).",
|
|
5520
|
+
"ticket": "DS-908"
|
|
5521
|
+
},
|
|
5522
|
+
{
|
|
5523
|
+
"option": "A statusDescription line above the bar",
|
|
5524
|
+
"why": "description already carries what the run is doing and is already the live region — a second moving line is two voices for one wait.",
|
|
5525
|
+
"ticket": "DS-908"
|
|
5526
|
+
}
|
|
4816
5527
|
]
|
|
4817
5528
|
},
|
|
4818
5529
|
{
|
|
@@ -4908,14 +5619,25 @@
|
|
|
4908
5619
|
],
|
|
4909
5620
|
"compound": false,
|
|
4910
5621
|
"dataHookRequired": true,
|
|
4911
|
-
"variants": {
|
|
5622
|
+
"variants": {
|
|
5623
|
+
"variant": [
|
|
5624
|
+
"stars",
|
|
5625
|
+
"recommendation"
|
|
5626
|
+
],
|
|
5627
|
+
"size": [
|
|
5628
|
+
"sm",
|
|
5629
|
+
"md"
|
|
5630
|
+
]
|
|
5631
|
+
},
|
|
4912
5632
|
"props": [
|
|
4913
5633
|
"value"
|
|
4914
5634
|
],
|
|
4915
|
-
"description": "
|
|
5635
|
+
"description": "Review score display: a 0–5 star value (0.5 increments) or Facebook's Recommended / Not recommended verdict",
|
|
4916
5636
|
"i18nProps": {
|
|
4917
5637
|
"Rating": {
|
|
4918
|
-
"ariaLabel": "string — default: \"Rating: {value} out of 5 stars\""
|
|
5638
|
+
"ariaLabel": "string — default: \"Rating: {value} out of 5 stars\" (stars)",
|
|
5639
|
+
"recommendedLabel": "string — default: \"Recommended\" (recommendation)",
|
|
5640
|
+
"notRecommendedLabel": "string — default: \"Not recommended\" (recommendation)"
|
|
4919
5641
|
}
|
|
4920
5642
|
},
|
|
4921
5643
|
"figma": {
|
|
@@ -4927,15 +5649,23 @@
|
|
|
4927
5649
|
"kind": "componentSet",
|
|
4928
5650
|
"export": "Rating",
|
|
4929
5651
|
"axes": [
|
|
5652
|
+
{
|
|
5653
|
+
"figma": "Variant",
|
|
5654
|
+
"code": "variant"
|
|
5655
|
+
},
|
|
4930
5656
|
{
|
|
4931
5657
|
"figma": "Rating",
|
|
4932
5658
|
"exempt": "figma-only-style",
|
|
4933
|
-
"note": "Discrete value
|
|
5659
|
+
"note": "Discrete value demos — 1.0–5.0 for Stars (value is continuous in code), Recommended / Not recommended for Recommendation (code: recommended boolean)"
|
|
4934
5660
|
},
|
|
4935
5661
|
{
|
|
4936
5662
|
"figma": "Size",
|
|
4937
|
-
"
|
|
4938
|
-
"
|
|
5663
|
+
"code": "size",
|
|
5664
|
+
"valueAliases": {
|
|
5665
|
+
"Default": "md",
|
|
5666
|
+
"Small": "sm"
|
|
5667
|
+
},
|
|
5668
|
+
"note": "Figma Default = 24px = code md, Small = 16px = code sm (DS-544). Show Label (BOOLEAN) ↔ showLabel on the Recommendation variants"
|
|
4939
5669
|
}
|
|
4940
5670
|
]
|
|
4941
5671
|
}
|
|
@@ -4945,12 +5675,14 @@
|
|
|
4945
5675
|
},
|
|
4946
5676
|
"whenToUse": [
|
|
4947
5677
|
"Showing a star-based score, like 4.5 out of 5, on a review, listing, or summary card",
|
|
5678
|
+
"Showing a Facebook review's Recommended / Not recommended verdict beside star ratings from other sources (variant=\"recommendation\")",
|
|
4948
5679
|
"Visualizing quality or satisfaction where the star convention is expected",
|
|
4949
5680
|
"Summarizing aggregate customer feedback at a glance"
|
|
4950
5681
|
],
|
|
4951
5682
|
"doNotUseFor": [
|
|
4952
|
-
"collecting a rating from the user (display-only, no input)",
|
|
4953
|
-
"
|
|
5683
|
+
"collecting a rating or a like/dislike from the user (display-only, no input — use ToggleGroup)",
|
|
5684
|
+
"counts or category labels (use plain text or Badge)",
|
|
5685
|
+
"scores with no star or thumbs convention, like 7/10 or NPS (use plain text)"
|
|
4954
5686
|
]
|
|
4955
5687
|
},
|
|
4956
5688
|
{
|
|
@@ -4976,7 +5708,7 @@
|
|
|
4976
5708
|
"labels",
|
|
4977
5709
|
"className"
|
|
4978
5710
|
],
|
|
4979
|
-
"description": "When something happened, in words people read at a glance (\"1 hour ago\"), with the exact date and time in a tooltip. Handles ISO timestamps, calendar dates, and null/unknown.",
|
|
5711
|
+
"description": "When something happened, in words people read at a glance (\"1 hour ago\"), with the exact date and time in a tooltip — left out when the words already are the exact date (an older calendar date from another year). Handles ISO timestamps, calendar dates, and null/unknown.",
|
|
4980
5712
|
"aliases": [
|
|
4981
5713
|
"last updated",
|
|
4982
5714
|
"time ago",
|
|
@@ -5087,6 +5819,78 @@
|
|
|
5087
5819
|
"small/mobile screens where drag-resize is impractical (use a fixed stacked layout)"
|
|
5088
5820
|
]
|
|
5089
5821
|
},
|
|
5822
|
+
{
|
|
5823
|
+
"name": "ResultCount",
|
|
5824
|
+
"import": "@brightlocal/ui-components/result-count",
|
|
5825
|
+
"category": "display",
|
|
5826
|
+
"exports": [
|
|
5827
|
+
"ResultCount"
|
|
5828
|
+
],
|
|
5829
|
+
"compound": false,
|
|
5830
|
+
"dataHookRequired": true,
|
|
5831
|
+
"variants": {},
|
|
5832
|
+
"props": [
|
|
5833
|
+
"count",
|
|
5834
|
+
"total",
|
|
5835
|
+
"from",
|
|
5836
|
+
"to",
|
|
5837
|
+
"updating"
|
|
5838
|
+
],
|
|
5839
|
+
"description": "The one count text the DS renders for a collection, as the screen's one role=\"status\" live region (Patterns/Filtering, Where controls live). Plain form (`count` + optional `total`): \"4 of 24 locations\" — the toolbar count of a filtered list. Range form (`from` + `to` + `total`): \"1 to 20 of 45 locations\" — what DataTablePagination and PaginationControls render, so a paged collection shows the count once, in the toolbar or the pagination row, never both. At zero the visible text hides (the empty state says it) and the region keeps the screen-reader-only emptyLabel; `updating` keeps the previous count on screen aria-hidden beside a spinner while the region announces the updating message once. Name the records in the product's words through the label templates.",
|
|
5840
|
+
"i18nProps": {
|
|
5841
|
+
"ResultCount": {
|
|
5842
|
+
"label": "string — default: \"{count} of {total} results\"",
|
|
5843
|
+
"labelOne": "string — default: \"{count} of {total} result\"; used at total === 1, falls back to label",
|
|
5844
|
+
"noTotalLabel": "string — default: \"{count} results\"",
|
|
5845
|
+
"noTotalLabelOne": "string — default: \"{count} result\"; used at count === 1, falls back to noTotalLabel",
|
|
5846
|
+
"rangeLabel": "string — default: \"{from} to {to} of {total} results\"",
|
|
5847
|
+
"rangeLabelOne": "string — default: \"{from} to {to} of {total} result\"; used at total === 1, falls back to rangeLabel",
|
|
5848
|
+
"updatingLabel": "string — default: \"Updating results\"",
|
|
5849
|
+
"emptyLabel": "string — default: \"No results\""
|
|
5850
|
+
}
|
|
5851
|
+
},
|
|
5852
|
+
"whenToUse": [
|
|
5853
|
+
"The count a filterable list shows in its toolbar — what the search and filters left",
|
|
5854
|
+
"The row count of a paged table or list — DataTablePagination and PaginationControls render it for you; use useDataTablePagination(table) to place it in the toolbar instead"
|
|
5855
|
+
],
|
|
5856
|
+
"doNotUseFor": [
|
|
5857
|
+
"a second count on the same collection (one count per collection: toolbar or pagination row, not both)",
|
|
5858
|
+
"live announcements that are not a count — use the empty state, FieldError or a toast"
|
|
5859
|
+
],
|
|
5860
|
+
"decisions": [
|
|
5861
|
+
{
|
|
5862
|
+
"date": "2026-10-31",
|
|
5863
|
+
"decision": "One count per collection: ResultCount is the only count text the DS renders — the toolbar count, DataTablePagination's row count and PaginationControls' caption are the same component in its range or plain form.",
|
|
5864
|
+
"why": "Two wordings for the same numbers was the drift the Miro rule-system board documented (five pager variants); one component with one template ends it.",
|
|
5865
|
+
"ticket": "DS-973"
|
|
5866
|
+
},
|
|
5867
|
+
{
|
|
5868
|
+
"date": "2026-11-02",
|
|
5869
|
+
"decision": "The label templates accept i18next's `{{count}}` / `{{from}}` form as well as the DS `{count}` / `{from}` form, every occurrence replaced.",
|
|
5870
|
+
"why": "Greenfield's 12 tables each carried a renderRowCount function only to feed t() the numbers; accepting the i18next placeholder lets rowCountLabel={t('key')} take the untranslated string and keeps the count a live region. The DS still resolves nothing else of i18next's syntax.",
|
|
5871
|
+
"ticket": "DS-973"
|
|
5872
|
+
},
|
|
5873
|
+
{
|
|
5874
|
+
"date": "2026-11-02",
|
|
5875
|
+
"decision": "The default wording is the frontend team's bare form with the noun: \"1 to 20 of 45 locations\" (plain form \"4 of 24 locations\") — no leading \"Showing\", \"to\" not a dash.",
|
|
5876
|
+
"why": "The team rule since 22 Oct 2026 and five greenfield pages already write \"1 to 20 of 45\"; adopting it as the DS default costs one string here, while \"Showing …\" would have been a sixth pager variant for those pages to migrate to. \"to\" stays for screen readers and dyscalculia (MoJ); the noun stays because it is the a11y payload.",
|
|
5877
|
+
"ticket": "DS-973"
|
|
5878
|
+
},
|
|
5879
|
+
{
|
|
5880
|
+
"date": "2026-11-02",
|
|
5881
|
+
"decision": "Each template has one singular counterpart (labelOne, noTotalLabelOne, rangeLabelOne), picked by the number the noun follows — the total when there is one, the count otherwise — and falling back to the plural template so a noun is never swapped for the English default.",
|
|
5882
|
+
"why": "A single template read \"1 results\" and \"1 to 1 of 1 invoices\"; the prototypes had hand-rolled the singular in renderText and lost it on the move to the template. One `_one` form mirrors i18next's plural keys, so t(\"key_one\") / t(\"key_other\") map straight onto the two props; ICU plural syntax in the template was more than English and the team's locales need.",
|
|
5883
|
+
"ticket": "DS-973"
|
|
5884
|
+
}
|
|
5885
|
+
],
|
|
5886
|
+
"ruledOut": [
|
|
5887
|
+
{
|
|
5888
|
+
"option": "A second count component for the pagination row",
|
|
5889
|
+
"why": "Two wordings for the same numbers was the drift the Miro rule-system board documented (five pager variants).",
|
|
5890
|
+
"ticket": "DS-973"
|
|
5891
|
+
}
|
|
5892
|
+
]
|
|
5893
|
+
},
|
|
5090
5894
|
{
|
|
5091
5895
|
"name": "RouteProgress",
|
|
5092
5896
|
"import": "@brightlocal/ui-components/route-progress",
|
|
@@ -5157,6 +5961,26 @@
|
|
|
5157
5961
|
"description": "active is fully controlled: the component cannot itself know what a route is, so back/forward support, ignoring in-page changes, and not being held open by a slow section all depend on what active is wired to",
|
|
5158
5962
|
"workaround": "Derive active from the router rather than a click handler, and mount the bar once at the root route so every route family is covered."
|
|
5159
5963
|
}
|
|
5964
|
+
],
|
|
5965
|
+
"decisions": [
|
|
5966
|
+
{
|
|
5967
|
+
"date": "2026-09-07",
|
|
5968
|
+
"decision": "RouteProgress paints a solid bg-primary bar (dark keeps the light-mode primary), not the loading gradient.",
|
|
5969
|
+
"why": "At 2px a gradient reads as a colour inconsistency along the bar rather than a ramp, and the dark-mode primary measures 2.15:1 as a hairline.",
|
|
5970
|
+
"ticket": "DS-904"
|
|
5971
|
+
}
|
|
5972
|
+
],
|
|
5973
|
+
"ruledOut": [
|
|
5974
|
+
{
|
|
5975
|
+
"option": "Folding RouteProgress into Progress as a color=\"gradient\" variant",
|
|
5976
|
+
"why": "The a11y contract is inverted (Progress is role=progressbar with aria-valuenow; RouteProgress is aria-hidden over a polite live region because its fill is a fabricated trickle), the fill mechanism differs (clip-path reveal vs translated indicator), and it is a single-pass 12%→90%→100%→fade viewport singleton, not an in-flow bar.",
|
|
5977
|
+
"ticket": "DS-904"
|
|
5978
|
+
},
|
|
5979
|
+
{
|
|
5980
|
+
"option": "A determinate Progress fed a consumer-supplied fake number",
|
|
5981
|
+
"why": "It pushes the trickle into every app, cannot do the slow asymptote through value, and announces a fiction through aria-valuenow.",
|
|
5982
|
+
"ticket": "DS-904"
|
|
5983
|
+
}
|
|
5160
5984
|
]
|
|
5161
5985
|
},
|
|
5162
5986
|
{
|
|
@@ -5203,6 +6027,7 @@
|
|
|
5203
6027
|
},
|
|
5204
6028
|
"whenToUse": [
|
|
5205
6029
|
"A specific box needing its own scroll bar (chat panel, fixed-height list)",
|
|
6030
|
+
"A list that grows with its content and scrolls past a max height (className=\"max-h-64\"), e.g. inside PopoverContent — add reserveScrollbarSpace when right-aligned values must stay clear of the scrollbar",
|
|
5206
6031
|
"Dropdown menus or sidebars with long content that shouldn't grow the page",
|
|
5207
6032
|
"Keeping scrollbar styling consistent with the design system"
|
|
5208
6033
|
],
|
|
@@ -5460,7 +6285,8 @@
|
|
|
5460
6285
|
],
|
|
5461
6286
|
"size": [
|
|
5462
6287
|
"default",
|
|
5463
|
-
"sm"
|
|
6288
|
+
"sm",
|
|
6289
|
+
"lg"
|
|
5464
6290
|
]
|
|
5465
6291
|
},
|
|
5466
6292
|
"props": [
|
|
@@ -5606,6 +6432,126 @@
|
|
|
5606
6432
|
]
|
|
5607
6433
|
}
|
|
5608
6434
|
},
|
|
6435
|
+
{
|
|
6436
|
+
"name": "SingleSelectFilter",
|
|
6437
|
+
"import": "@brightlocal/ui-components/single-select-filter",
|
|
6438
|
+
"category": "form",
|
|
6439
|
+
"exports": [
|
|
6440
|
+
"SingleSelectFilter"
|
|
6441
|
+
],
|
|
6442
|
+
"compound": false,
|
|
6443
|
+
"dataHookRequired": true,
|
|
6444
|
+
"variants": {
|
|
6445
|
+
"size": [
|
|
6446
|
+
"default",
|
|
6447
|
+
"sm"
|
|
6448
|
+
],
|
|
6449
|
+
"presentation": [
|
|
6450
|
+
"menu",
|
|
6451
|
+
"drawer",
|
|
6452
|
+
"auto"
|
|
6453
|
+
]
|
|
6454
|
+
},
|
|
6455
|
+
"props": [
|
|
6456
|
+
"label",
|
|
6457
|
+
"options",
|
|
6458
|
+
"value",
|
|
6459
|
+
"defaultValue",
|
|
6460
|
+
"onValueChange",
|
|
6461
|
+
"open",
|
|
6462
|
+
"onOpenChange",
|
|
6463
|
+
"icon",
|
|
6464
|
+
"disabled",
|
|
6465
|
+
"presentation",
|
|
6466
|
+
"searchable",
|
|
6467
|
+
"searchThreshold",
|
|
6468
|
+
"searchPlaceholder",
|
|
6469
|
+
"emptyLabel",
|
|
6470
|
+
"emptyDescription"
|
|
6471
|
+
],
|
|
6472
|
+
"description": "The Filtering pattern's single-value dropdown filter: one value from one dimension (time period, interval, source type). Shows a DS Select (native listbox, keyboard navigation, scroll indicators) on desktop and a bottom Drawer with RadioGroup in two columns on mobile. The trigger wears the same field look as MultiSelectFilter (multiSelectFilterTriggerVariants — border, radius, focus ring, chevron) so a SingleSelectFilter sits beside a MultiSelectFilter in a toolbar row without looking different. size='default' (h-9, text-field: 14px desktop / 16px touch like Select) or 'sm' (h-8, text-label, phone card headers). The trigger always reads the selected label, or the dimension's name when nothing is picked — both in foreground text, never muted. Options may carry their own icon (option.icon) shown before the label in the menu and the drawer; the trigger wears the picked option's icon unless the icon prop pins one. Counts render in the menu only, never in the trigger. Clear resets to defaultValue — unlike MultiSelectFilter which clears to []; a single-value filter always has a value, and 'no filter' is an explicit option in the list. Drawer anatomy matches MultiSelectFilter: DrawerTitle = label, sr-only DrawerDescription, RadioGroup in grid-cols-2, Clear when value ≠ defaultValue, Done button that only closes. When options.length > searchThreshold (default 10) the drawer shows a search field above the scrolling radio list — case-insensitive substring match on label and value; override with searchable. The query resets on close. Per-filter commit model: onValueChange fires on every pick. presentation='menu' (default) is the DS Select; 'drawer' is the phone form; 'auto' switches at the md breakpoint.",
|
|
6473
|
+
"i18nProps": {
|
|
6474
|
+
"SingleSelectFilter": {
|
|
6475
|
+
"clearLabel": "string — default: \"Clear filters\"",
|
|
6476
|
+
"doneLabel": "string — default: \"Done\" (the drawer's close button)",
|
|
6477
|
+
"drawerDescription": "string — default: \"Pick one option.\" (sr-only drawer description)",
|
|
6478
|
+
"searchPlaceholder": "string — default: \"Search options...\" (drawer search field placeholder and aria-label)",
|
|
6479
|
+
"clearSearchAriaLabel": "string — default: \"Clear search\" (the drawer search clear button)",
|
|
6480
|
+
"emptyLabel": "string — default: \"No options found.\" (no-match heading)",
|
|
6481
|
+
"emptyDescription": "string — default: \"Try another search.\" (no-match description)"
|
|
6482
|
+
}
|
|
6483
|
+
},
|
|
6484
|
+
"whenToUse": [
|
|
6485
|
+
"One value from a dimension in a filter toolbar (time period, interval, source type) — the Filtering pattern's dropdown filter",
|
|
6486
|
+
"A responsive filter that shows a DS Select on desktop and a radio drawer on mobile: presentation='auto' switches at md",
|
|
6487
|
+
"Sitting beside MultiSelectFilter in a filter bar — the trigger look matches exactly"
|
|
6488
|
+
],
|
|
6489
|
+
"doNotUseFor": [
|
|
6490
|
+
"picking more than one option (use MultiSelectFilter)",
|
|
6491
|
+
"a form field that validates (use Select — SingleSelectFilter has no error state)",
|
|
6492
|
+
"quick filters with 2–5 always-visible options (use ToggleGroup or SegmentedControl)",
|
|
6493
|
+
"a long, searchable single-value list in a form — not a filter (use Combobox)"
|
|
6494
|
+
],
|
|
6495
|
+
"alternatives": [
|
|
6496
|
+
{
|
|
6497
|
+
"component": "MultiSelectFilter",
|
|
6498
|
+
"rule": "Use MultiSelectFilter for several values from one dimension combining as OR"
|
|
6499
|
+
},
|
|
6500
|
+
{
|
|
6501
|
+
"component": "Select",
|
|
6502
|
+
"rule": "Use Select for a form field that validates — SingleSelectFilter is a filter, not a form field"
|
|
6503
|
+
},
|
|
6504
|
+
{
|
|
6505
|
+
"component": "ToggleGroup",
|
|
6506
|
+
"rule": "Use ToggleGroup for a quick filter with 2–5 always-visible options"
|
|
6507
|
+
},
|
|
6508
|
+
{
|
|
6509
|
+
"component": "Combobox",
|
|
6510
|
+
"rule": "Use Combobox for a long, searchable single-value list in a form — not a filter (SingleSelectFilter has its own drawer search)"
|
|
6511
|
+
}
|
|
6512
|
+
],
|
|
6513
|
+
"figma": {
|
|
6514
|
+
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
6515
|
+
"nodes": [
|
|
6516
|
+
{
|
|
6517
|
+
"nodeId": "34438:81566",
|
|
6518
|
+
"figmaName": "Single Select Filter",
|
|
6519
|
+
"kind": "componentSet",
|
|
6520
|
+
"export": "SingleSelectFilter",
|
|
6521
|
+
"note": "Built on branch task/DS-1050-sigle-select-filter (2026-10-12); node ids persist on merge. Draws the trigger (Text, Show Icon + Icon swap). The desktop menu is the Select page's `Select / Menu` (the component wraps DS Select) and the phone drawer is a Playground composition of Drawer + Radio / Item — neither is a sub-part export. `presentation` is a runtime/responsive prop with no Figma axis.",
|
|
6522
|
+
"axes": [
|
|
6523
|
+
{
|
|
6524
|
+
"figma": "Size",
|
|
6525
|
+
"code": "size"
|
|
6526
|
+
},
|
|
6527
|
+
{
|
|
6528
|
+
"figma": "State",
|
|
6529
|
+
"exempt": "interaction-state",
|
|
6530
|
+
"valueToProp": {
|
|
6531
|
+
"Disabled": "disabled"
|
|
6532
|
+
},
|
|
6533
|
+
"note": "Focus and Open are runtime states; the CVA has no hover style, so there is no Hover variant"
|
|
6534
|
+
}
|
|
6535
|
+
]
|
|
6536
|
+
}
|
|
6537
|
+
]
|
|
6538
|
+
},
|
|
6539
|
+
"decisions": [
|
|
6540
|
+
{
|
|
6541
|
+
"date": "2026-11-02",
|
|
6542
|
+
"decision": "A SingleSelectFilter with nothing to choose — no time range after a single update, no source with reviews — stays in place, disabled and reset to its All option, with one line under the toolbar saying why. Only a filter that can never apply to the account is left out of the toolbar. An option with nothing behind it stays in the list, greyed with its count.",
|
|
6543
|
+
"why": "A filter that comes and goes moves the toolbar and makes the user hunt for it; a disabled one with a reason teaches the product (Carbon: disable, don't hide). The reason is a helper line, not a tooltip, because the disabled trigger takes no pointer events.",
|
|
6544
|
+
"ticket": "DS-973"
|
|
6545
|
+
}
|
|
6546
|
+
],
|
|
6547
|
+
"ruledOut": [
|
|
6548
|
+
{
|
|
6549
|
+
"option": "Hiding the filter when the current data leaves it nothing to choose",
|
|
6550
|
+
"why": "Greenfield did this (a one-update report hid Time period and Interval) and the toolbar shifted between states; the Filtering pattern keeps every filter in place and explains it instead.",
|
|
6551
|
+
"ticket": "DS-973"
|
|
6552
|
+
}
|
|
6553
|
+
]
|
|
6554
|
+
},
|
|
5609
6555
|
{
|
|
5610
6556
|
"name": "Skeleton",
|
|
5611
6557
|
"import": "@brightlocal/ui-components/skeleton",
|
|
@@ -5899,6 +6845,89 @@
|
|
|
5899
6845
|
"figmaOnly": []
|
|
5900
6846
|
}
|
|
5901
6847
|
},
|
|
6848
|
+
{
|
|
6849
|
+
"name": "Status",
|
|
6850
|
+
"import": "@brightlocal/ui-components/status",
|
|
6851
|
+
"category": "display",
|
|
6852
|
+
"exports": [
|
|
6853
|
+
"Status"
|
|
6854
|
+
],
|
|
6855
|
+
"compound": false,
|
|
6856
|
+
"dataHookRequired": true,
|
|
6857
|
+
"variants": {
|
|
6858
|
+
"variant": [
|
|
6859
|
+
"success",
|
|
6860
|
+
"warning",
|
|
6861
|
+
"error",
|
|
6862
|
+
"info",
|
|
6863
|
+
"neutral",
|
|
6864
|
+
"loading"
|
|
6865
|
+
]
|
|
6866
|
+
},
|
|
6867
|
+
"props": [
|
|
6868
|
+
"variant",
|
|
6869
|
+
"dotOnly",
|
|
6870
|
+
"children"
|
|
6871
|
+
],
|
|
6872
|
+
"description": "A dot and a word on an outlined pill: where a tracked thing is in its lifecycle (Connected, Syncing, Paused, Failed). variant sets the mark's visual weight only (success, warning, error, info, neutral) or loading, which swaps the dot for a small Spinner (same name as Button's loading); dotOnly hides the word, which becomes the accessible name and a tooltip on a keyboard-focusable trigger. The root is a polite live region (role=\"status\"), so a change like Syncing → Connected is announced.",
|
|
6873
|
+
"aliases": [
|
|
6874
|
+
"status dot",
|
|
6875
|
+
"status indicator",
|
|
6876
|
+
"state indicator",
|
|
6877
|
+
"connection status",
|
|
6878
|
+
"sync status",
|
|
6879
|
+
"lifecycle state",
|
|
6880
|
+
"presence dot"
|
|
6881
|
+
],
|
|
6882
|
+
"whenToUse": [
|
|
6883
|
+
"One Status per tracked aspect of a thing (its sync, its listing, its subscription), at the end of the row it describes",
|
|
6884
|
+
"A lifecycle state that can change while the user watches (Syncing → Connected)"
|
|
6885
|
+
],
|
|
6886
|
+
"doNotUseFor": [
|
|
6887
|
+
"A fact or label about the thing (plan tier, count, \"New\") — use Badge",
|
|
6888
|
+
"A message the user should read or act on — use Alert",
|
|
6889
|
+
"A lone problem on an otherwise healthy row — use an icon, not a dotOnly Status",
|
|
6890
|
+
"The change between two values — use Delta"
|
|
6891
|
+
],
|
|
6892
|
+
"alternatives": [
|
|
6893
|
+
{
|
|
6894
|
+
"component": "Badge",
|
|
6895
|
+
"rule": "Badge states a fact; Status states where something is in its lifecycle"
|
|
6896
|
+
},
|
|
6897
|
+
{
|
|
6898
|
+
"component": "Alert",
|
|
6899
|
+
"rule": "Alert is a message to read or act on; Status is a one-word state"
|
|
6900
|
+
}
|
|
6901
|
+
],
|
|
6902
|
+
"a11yContract": {
|
|
6903
|
+
"role": "status",
|
|
6904
|
+
"requiresLabel": false,
|
|
6905
|
+
"keyboardInteraction": [
|
|
6906
|
+
"Tab focuses the dotOnly trigger and opens its tooltip",
|
|
6907
|
+
"Escape closes the tooltip"
|
|
6908
|
+
]
|
|
6909
|
+
},
|
|
6910
|
+
"decisions": [
|
|
6911
|
+
{
|
|
6912
|
+
"decision": "variant is visual weight only; the word always carries the meaning",
|
|
6913
|
+
"why": "Colour is never the only indicator; the same variant can mean different lifecycle words",
|
|
6914
|
+
"date": "2026-11-02",
|
|
6915
|
+
"ticket": "DS-1235"
|
|
6916
|
+
},
|
|
6917
|
+
{
|
|
6918
|
+
"decision": "Root is role=\"status\" (polite live region)",
|
|
6919
|
+
"why": "Lifecycle states change in place (Syncing → Connected) and the change must be announced",
|
|
6920
|
+
"date": "2026-11-02",
|
|
6921
|
+
"ticket": "DS-1235"
|
|
6922
|
+
},
|
|
6923
|
+
{
|
|
6924
|
+
"decision": "In progress is variant=\"loading\", not a separate boolean",
|
|
6925
|
+
"why": "One axis for every state of the mark, named like Button's loading so the DS speaks one word for in-progress",
|
|
6926
|
+
"date": "2026-11-02",
|
|
6927
|
+
"ticket": "DS-1235"
|
|
6928
|
+
}
|
|
6929
|
+
]
|
|
6930
|
+
},
|
|
5902
6931
|
{
|
|
5903
6932
|
"name": "Stepper",
|
|
5904
6933
|
"import": "@brightlocal/ui-components/stepper",
|
|
@@ -6128,6 +7157,10 @@
|
|
|
6128
7157
|
{
|
|
6129
7158
|
"component": "DataTable",
|
|
6130
7159
|
"rule": "Use DataTable for sortable, filterable, paginated tables with row selection — it wraps TanStack Table"
|
|
7160
|
+
},
|
|
7161
|
+
{
|
|
7162
|
+
"component": "DescriptionList",
|
|
7163
|
+
"rule": "Use DescriptionList for the label-value properties of one record; Table is for several records compared by the same columns"
|
|
6131
7164
|
}
|
|
6132
7165
|
],
|
|
6133
7166
|
"replaces": [
|
|
@@ -6701,7 +7734,15 @@
|
|
|
6701
7734
|
"fileKey": "p3krmC8DBUgqpbq6cLzaal",
|
|
6702
7735
|
"status": "deprecated-in-figma",
|
|
6703
7736
|
"reason": "Every export in this file is @deprecated in code (DS-714 replaced the tag-coupled parts with TypographyHeading + TypographyText on the semantic type scale), and design is retiring the drawings in step: of the 13 mapped nodes, 6 were already deleted from the library by 2026-09-11 (H1 30021:14432, H4 26:234, InlineCode 37:58, Large 26:319, Small 26:324, Muted 36:56) while H2/H3/P/Blockquote/List/Code/Lead still resolve. Per-node parity on a family both sides are removing buys nothing but nightly node-missing noise, so the entry is exempted wholesale rather than trimmed node-by-node. Drop this entry outright when the deprecated exports are removed from code (FIG-26)."
|
|
6704
|
-
}
|
|
7737
|
+
},
|
|
7738
|
+
"decisions": [
|
|
7739
|
+
{
|
|
7740
|
+
"date": "2026-09-07",
|
|
7741
|
+
"decision": "TypographyH1–H4, P, Lead, Large, Small, Muted and the rest of the Typography family are deprecated in favour of TypographyHeading / TypographyText.",
|
|
7742
|
+
"why": "Tag and visual size were coupled; the two-axis semantic type scale separates the document outline (level) from the visual role (variant).",
|
|
7743
|
+
"ticket": "DS-714"
|
|
7744
|
+
}
|
|
7745
|
+
]
|
|
6705
7746
|
},
|
|
6706
7747
|
{
|
|
6707
7748
|
"name": "TypographyHeading",
|
|
@@ -6805,6 +7846,14 @@
|
|
|
6805
7846
|
"component": "Card",
|
|
6806
7847
|
"rule": "Inside Card, prefer the CardTitle export so the card owns its title slot"
|
|
6807
7848
|
}
|
|
7849
|
+
],
|
|
7850
|
+
"decisions": [
|
|
7851
|
+
{
|
|
7852
|
+
"date": "2026-09-08",
|
|
7853
|
+
"decision": "Titles inside dense surfaces over 14px body text use variant=\"compact\" (text-heading-compact, Inter 14/20, 600).",
|
|
7854
|
+
"why": "text-heading-subsection (16/600) assumes a 16px body; over a 14px body it double-jumps in size and weight and reads oversized.",
|
|
7855
|
+
"ticket": "DS-920"
|
|
7856
|
+
}
|
|
6808
7857
|
]
|
|
6809
7858
|
},
|
|
6810
7859
|
{
|
|
@@ -6930,6 +7979,11 @@
|
|
|
6930
7979
|
"EmptyStateAlign": [
|
|
6931
7980
|
"center",
|
|
6932
7981
|
"left"
|
|
7982
|
+
],
|
|
7983
|
+
"EmptyStateIconVariant": [
|
|
7984
|
+
"filled",
|
|
7985
|
+
"border",
|
|
7986
|
+
"transparent"
|
|
6933
7987
|
]
|
|
6934
7988
|
},
|
|
6935
7989
|
"props": [
|
|
@@ -6939,10 +7993,25 @@
|
|
|
6939
7993
|
"description",
|
|
6940
7994
|
"size",
|
|
6941
7995
|
"align",
|
|
7996
|
+
"iconVariant",
|
|
6942
7997
|
"titleLevel",
|
|
6943
7998
|
"className"
|
|
6944
7999
|
],
|
|
6945
|
-
"
|
|
8000
|
+
"decisions": [
|
|
8001
|
+
{
|
|
8002
|
+
"decision": "The icon chip is the DS LogoMark at lg (40px rounded square), shared with CommandEmpty / ComboboxEmpty and the filter no-match forms via lib/empty-chip",
|
|
8003
|
+
"why": "The hand-rolled 40px bg-muted circle drifted from every other icon mark; one mark keeps the empty chip and the rest of the product on one shape",
|
|
8004
|
+
"date": "2026-10-30",
|
|
8005
|
+
"ticket": "DS-1208"
|
|
8006
|
+
},
|
|
8007
|
+
{
|
|
8008
|
+
"decision": "iconVariant passes LogoMark's variant through (filled default, border, transparent)",
|
|
8009
|
+
"why": "The filled chip disappears on a bg-muted panel; the surface, not the block, decides the container",
|
|
8010
|
+
"date": "2026-10-30",
|
|
8011
|
+
"ticket": "DS-1208"
|
|
8012
|
+
}
|
|
8013
|
+
],
|
|
8014
|
+
"description": "The empty block. Four parts in reading order: a visual, a real heading, one supporting line, and the actions row — children render in source order, so the primary action goes last and lands rightmost. size sets visual prominence and nothing else — the block is pure content and owns no page layout, so position is always the consumer's composition. size=\"md\" (default) is for the box a working page gives it (a card, a panel, a zero-row table): an icon in a 40px LogoMark chip (lg, rounded square; iconVariant picks filled / border / transparent for the surface — border or transparent on a bg-muted panel, where the filled chip vanishes) and a 16/24 title. size=\"lg\" is for the moment the whole page has nothing to show: a 130px illustration and a 20/28 title, composed inside Grid variant=\"centered\" for the page body's optical centre — the same spot ProgressState uses. The props are a discriminated union on size: illustration exists only at lg and align only at md, so a 130px drawing inside a card will not compile. Pass the illustration without a size; the block sets it. titleLevel stays the consumer's, for the document outline. (sm is reserved — a compact row-level tier is not designed yet.)",
|
|
6946
8015
|
"aliases": [
|
|
6947
8016
|
"empty state",
|
|
6948
8017
|
"empty block",
|
|
@@ -7452,6 +8521,14 @@
|
|
|
7452
8521
|
"ticket": "DS-1029",
|
|
7453
8522
|
"workaround": "Place SidebarMenuSubItem directly inside SidebarMenuCollapsibleContent and pass variant on it; use a standalone SidebarMenuSub only outside a collapsible"
|
|
7454
8523
|
}
|
|
8524
|
+
],
|
|
8525
|
+
"decisions": [
|
|
8526
|
+
{
|
|
8527
|
+
"decision": "SidebarAccountDropdown children replaces only the items area, not the name/email header — composition with DropdownMenuItem for links, disabled, loading, per-item dataHook instead of extending the menuGroups data type",
|
|
8528
|
+
"ticket": "DS-1212",
|
|
8529
|
+
"date": "2026-11-02",
|
|
8530
|
+
"why": "The underlying DropdownMenuItem already supports asChild (links), disabled, dataHook, and onSelect with preventDefault (stay open for loading). Extending menuGroups would couple the data type to every primitive feature and still not cover router links (which need asChild composition). The shadcn NavUser follows this exact composition pattern."
|
|
8531
|
+
}
|
|
7455
8532
|
]
|
|
7456
8533
|
}
|
|
7457
8534
|
],
|
|
@@ -7474,6 +8551,7 @@
|
|
|
7474
8551
|
"transitions": "Always specify property (transition-colors, transition-opacity). Never use transition-all.",
|
|
7475
8552
|
"focus": "Use focus-visible: prefix. Never use bare focus: prefix.",
|
|
7476
8553
|
"icons": "@brightlocal/icons package. Default 16px, no size/strokeWidth override needed.",
|
|
7477
|
-
"figmaMapping": "Some components carry an optional figma entry (fileKey + node IDs + axis rules) mapping code exports to the Figma library for the DS-824 drift watchdog (scripts/figma-sync/). Note for DS engineers: this file ships in the public npm tarball, so those Figma file keys and node IDs are public metadata. That is intentional and harmless — Figma permissions still gate all file access — but do not add anything sensitive to figma entries (no tokens, no internal URLs). Rules: docs/figma-sync/conventions.md in the design-system repo."
|
|
8554
|
+
"figmaMapping": "Some components carry an optional figma entry (fileKey + node IDs + axis rules) mapping code exports to the Figma library for the DS-824 drift watchdog (scripts/figma-sync/). Note for DS engineers: this file ships in the public npm tarball, so those Figma file keys and node IDs are public metadata. That is intentional and harmless — Figma permissions still gate all file access — but do not add anything sensitive to figma entries (no tokens, no internal URLs). Rules: docs/figma-sync/conventions.md in the design-system repo.",
|
|
8555
|
+
"decisions": "Optional per-component decision memory: `decisions` (dated one-liner + why + ticket: what was decided and the reason), `ruledOut` (option + why + ticket: a considered option that was rejected) and `open` (question + owner: an unresolved call). Returned by the MCP get_component_api so agents and teammates stop re-proposing settled options. AGENT RULE: a component with an `open` entry is not built on or extended by guesswork — stop and ask the owner. LOGGING BAR: log an entry only if someone could plausibly propose the opposite (a rejected variant, a removed prop, a token that was added then dropped). If nobody would, it belongs in a commit message, not here. Never fill a field with a guess: an empty field means 'nothing recorded', and entries are added when a component is touched. Shapes — decisions: {date: YYYY-MM-DD, decision: one line, why: one line, ticket: DS-123}; ruledOut: {option, why, ticket}; open: {question, owner}. Validated by `pnpm --filter @brightlocal/ui-components sync-meta:check`; the registry parity check fails when the MCP copy drifts."
|
|
7478
8556
|
}
|
|
7479
8557
|
}
|