@brightlocal/ui-components 3.2.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (428) hide show
  1. package/AI_USAGE.md +10 -0
  2. package/README.md +3 -1
  3. package/component-meta.json +1271 -428
  4. package/deprecations.json +44 -0
  5. package/dist/_virtual/_rolldown/runtime.cjs +1 -0
  6. package/dist/accordion.cjs +1 -1
  7. package/dist/accordion.js +73 -102
  8. package/dist/alert-dialog.cjs +1 -1
  9. package/dist/alert-dialog.d.ts +6 -4
  10. package/dist/alert-dialog.d.ts.map +1 -1
  11. package/dist/alert-dialog.js +85 -133
  12. package/dist/alert.cjs +1 -1
  13. package/dist/alert.d.ts +4 -4
  14. package/dist/alert.d.ts.map +1 -1
  15. package/dist/alert.js +106 -168
  16. package/dist/aspect-ratio.cjs +1 -1
  17. package/dist/aspect-ratio.js +13 -16
  18. package/dist/avatar.cjs +1 -1
  19. package/dist/avatar.js +30 -45
  20. package/dist/badge.cjs +1 -1
  21. package/dist/badge.d.ts +23 -1
  22. package/dist/badge.d.ts.map +1 -1
  23. package/dist/badge.js +90 -91
  24. package/dist/banner.cjs +1 -1
  25. package/dist/banner.js +102 -148
  26. package/dist/blocks/empty-state.cjs +1 -1
  27. package/dist/blocks/empty-state.d.ts +20 -3
  28. package/dist/blocks/empty-state.d.ts.map +1 -1
  29. package/dist/blocks/empty-state.js +73 -140
  30. package/dist/blocks/input-list.cjs +2 -2
  31. package/dist/blocks/input-list.d.ts +2 -2
  32. package/dist/blocks/input-list.d.ts.map +1 -1
  33. package/dist/blocks/input-list.js +136 -176
  34. package/dist/blocks/progress-state.cjs +1 -1
  35. package/dist/blocks/progress-state.js +223 -347
  36. package/dist/blocks/sidebar.cjs +1 -1
  37. package/dist/blocks/sidebar.d.ts +11 -6
  38. package/dist/blocks/sidebar.d.ts.map +1 -1
  39. package/dist/blocks/sidebar.js +763 -1092
  40. package/dist/brand-illustration-motif.cjs +1 -1
  41. package/dist/brand-illustration-motif.js +40 -61
  42. package/dist/breadcrumb.cjs +1 -1
  43. package/dist/breadcrumb.js +62 -102
  44. package/dist/button-group.cjs +1 -1
  45. package/dist/button-group.js +23 -31
  46. package/dist/button.cjs +1 -1
  47. package/dist/button.d.ts +4 -2
  48. package/dist/button.d.ts.map +1 -1
  49. package/dist/button.js +149 -189
  50. package/dist/calendar.cjs +1 -1
  51. package/dist/calendar.d.ts +87 -3
  52. package/dist/calendar.d.ts.map +1 -1
  53. package/dist/calendar.js +116 -173
  54. package/dist/callout.cjs +1 -1
  55. package/dist/callout.js +73 -96
  56. package/dist/card.cjs +1 -1
  57. package/dist/card.d.ts +10 -4
  58. package/dist/card.d.ts.map +1 -1
  59. package/dist/card.js +233 -316
  60. package/dist/carousel.cjs +1 -1
  61. package/dist/carousel.d.ts +3 -3
  62. package/dist/carousel.d.ts.map +1 -1
  63. package/dist/carousel.js +174 -268
  64. package/dist/centred-layout.cjs +1 -1
  65. package/dist/centred-layout.js +27 -48
  66. package/dist/chart-empty.cjs +1 -1
  67. package/dist/chart-empty.js +18 -27
  68. package/dist/chart.cjs +7 -7
  69. package/dist/chart.d.ts +23 -13
  70. package/dist/chart.d.ts.map +1 -1
  71. package/dist/chart.js +445 -651
  72. package/dist/checkbox.cjs +1 -1
  73. package/dist/checkbox.js +36 -69
  74. package/dist/chip.cjs +1 -1
  75. package/dist/chip.js +116 -173
  76. package/dist/collapsible.cjs +1 -1
  77. package/dist/collapsible.d.ts.map +1 -1
  78. package/dist/collapsible.js +35 -41
  79. package/dist/combobox.cjs +3 -3
  80. package/dist/combobox.d.ts +14 -4
  81. package/dist/combobox.d.ts.map +1 -1
  82. package/dist/combobox.js +439 -638
  83. package/dist/command.cjs +1 -1
  84. package/dist/command.d.ts.map +1 -1
  85. package/dist/command.js +273 -420
  86. package/dist/context-menu.cjs +1 -1
  87. package/dist/context-menu.d.ts +5 -5
  88. package/dist/context-menu.d.ts.map +1 -1
  89. package/dist/context-menu.js +121 -191
  90. package/dist/data-table.cjs +1 -1
  91. package/dist/data-table.d.ts +280 -129
  92. package/dist/data-table.d.ts.map +1 -1
  93. package/dist/data-table.js +687 -948
  94. package/dist/date-picker.cjs +1 -1
  95. package/dist/date-picker.d.ts +15 -4
  96. package/dist/date-picker.d.ts.map +1 -1
  97. package/dist/date-picker.js +156 -231
  98. package/dist/delta.cjs +1 -0
  99. package/dist/delta.d.ts +79 -0
  100. package/dist/delta.d.ts.map +1 -0
  101. package/dist/delta.js +62 -0
  102. package/dist/description.cjs +1 -1
  103. package/dist/description.js +11 -20
  104. package/dist/dialog.cjs +1 -1
  105. package/dist/dialog.d.ts +1 -1
  106. package/dist/dialog.d.ts.map +1 -1
  107. package/dist/dialog.js +76 -116
  108. package/dist/drawer.cjs +1 -1
  109. package/dist/drawer.d.ts +11 -11
  110. package/dist/drawer.d.ts.map +1 -1
  111. package/dist/drawer.js +76 -134
  112. package/dist/dropdown-menu.cjs +1 -1
  113. package/dist/dropdown-menu.d.ts +6 -6
  114. package/dist/dropdown-menu.d.ts.map +1 -1
  115. package/dist/dropdown-menu.js +179 -300
  116. package/dist/field.cjs +1 -1
  117. package/dist/field.d.ts +9 -9
  118. package/dist/field.d.ts.map +1 -1
  119. package/dist/field.js +166 -286
  120. package/dist/global-layout.cjs +1 -1
  121. package/dist/global-layout.js +203 -342
  122. package/dist/grid.cjs +1 -1
  123. package/dist/grid.js +16 -29
  124. package/dist/header.cjs +1 -1
  125. package/dist/header.js +21 -38
  126. package/dist/height-transition.cjs +1 -1
  127. package/dist/height-transition.js +38 -55
  128. package/dist/hooks/use-breakpoint.cjs +1 -1
  129. package/dist/hooks/use-breakpoint.js +9 -9
  130. package/dist/hooks/use-debounce.cjs +1 -1
  131. package/dist/hooks/use-debounce.js +12 -11
  132. package/dist/hooks/use-delayed-pending.cjs +1 -1
  133. package/dist/hooks/use-delayed-pending.js +8 -9
  134. package/dist/hooks/use-filter-search-params.cjs +1 -0
  135. package/dist/hooks/use-filter-search-params.d.ts +93 -0
  136. package/dist/hooks/use-filter-search-params.d.ts.map +1 -0
  137. package/dist/hooks/use-filter-search-params.js +122 -0
  138. package/dist/hooks/use-mobile.cjs +1 -1
  139. package/dist/hooks/use-mobile.js +6 -6
  140. package/dist/hooks/use-overlay-pointer-lock.cjs +1 -1
  141. package/dist/hooks/use-overlay-pointer-lock.js +8 -9
  142. package/dist/hooks/use-prefers-reduced-motion.cjs +1 -1
  143. package/dist/hooks/use-prefers-reduced-motion.js +5 -8
  144. package/dist/hover-card.cjs +1 -1
  145. package/dist/hover-card.d.ts +1 -1
  146. package/dist/hover-card.d.ts.map +1 -1
  147. package/dist/hover-card.js +30 -62
  148. package/dist/index.cjs +1 -1
  149. package/dist/index.d.ts +6 -0
  150. package/dist/index.d.ts.map +1 -1
  151. package/dist/index.js +630 -608
  152. package/dist/info-tooltip.cjs +1 -1
  153. package/dist/info-tooltip.js +22 -36
  154. package/dist/input-chip.cjs +1 -1
  155. package/dist/input-chip.d.ts +32 -3
  156. package/dist/input-chip.d.ts.map +1 -1
  157. package/dist/input-chip.js +181 -230
  158. package/dist/input-group.cjs +1 -1
  159. package/dist/input-group.js +174 -221
  160. package/dist/input-otp.cjs +1 -1
  161. package/dist/input-otp.d.ts +3 -3
  162. package/dist/input-otp.d.ts.map +1 -1
  163. package/dist/input-otp.js +102 -146
  164. package/dist/input-password.cjs +1 -1
  165. package/dist/input-password.d.ts +12 -16
  166. package/dist/input-password.d.ts.map +1 -1
  167. package/dist/input-password.js +139 -171
  168. package/dist/input.cjs +1 -1
  169. package/dist/input.d.ts.map +1 -1
  170. package/dist/input.js +51 -73
  171. package/dist/label.cjs +1 -1
  172. package/dist/label.js +20 -38
  173. package/dist/lib/block-illustration.cjs +1 -1
  174. package/dist/lib/block-illustration.d.ts +1 -1
  175. package/dist/lib/block-illustration.d.ts.map +1 -1
  176. package/dist/lib/block-illustration.js +16 -18
  177. package/dist/lib/compose-event-handlers.cjs +1 -0
  178. package/dist/lib/compose-event-handlers.d.ts +9 -0
  179. package/dist/lib/compose-event-handlers.d.ts.map +1 -0
  180. package/dist/lib/compose-event-handlers.js +8 -0
  181. package/dist/lib/download-file.cjs +1 -0
  182. package/dist/lib/download-file.d.ts +14 -0
  183. package/dist/lib/download-file.d.ts.map +1 -0
  184. package/dist/lib/download-file.js +40 -0
  185. package/dist/lib/empty-canvas.cjs +1 -1
  186. package/dist/lib/empty-canvas.js +28 -56
  187. package/dist/lib/empty-chip.cjs +1 -1
  188. package/dist/lib/empty-chip.d.ts +14 -3
  189. package/dist/lib/empty-chip.d.ts.map +1 -1
  190. package/dist/lib/empty-chip.js +15 -11
  191. package/dist/lib/field-aria.cjs +1 -0
  192. package/dist/lib/field-aria.d.ts +34 -0
  193. package/dist/lib/field-aria.d.ts.map +1 -0
  194. package/dist/lib/field-aria.js +52 -0
  195. package/dist/lib/image-file-info.cjs +1 -0
  196. package/dist/lib/image-file-info.d.ts +25 -0
  197. package/dist/lib/image-file-info.d.ts.map +1 -0
  198. package/dist/lib/image-file-info.js +67 -0
  199. package/dist/lib/media-viewer-content.cjs +1 -0
  200. package/dist/lib/media-viewer-content.d.ts +102 -0
  201. package/dist/lib/media-viewer-content.d.ts.map +1 -0
  202. package/dist/lib/media-viewer-content.js +650 -0
  203. package/dist/lib/media-viewer-internal.cjs +1 -0
  204. package/dist/lib/media-viewer-internal.d.ts +98 -0
  205. package/dist/lib/media-viewer-internal.d.ts.map +1 -0
  206. package/dist/lib/media-viewer-internal.js +61 -0
  207. package/dist/lib/media-viewer-motion.cjs +1 -0
  208. package/dist/lib/media-viewer-motion.d.ts +40 -0
  209. package/dist/lib/media-viewer-motion.d.ts.map +1 -0
  210. package/dist/lib/media-viewer-motion.js +37 -0
  211. package/dist/lib/motion.cjs +1 -1
  212. package/dist/lib/motion.d.ts +8 -0
  213. package/dist/lib/motion.d.ts.map +1 -1
  214. package/dist/lib/motion.js +11 -10
  215. package/dist/lib/optical-center.cjs +1 -1
  216. package/dist/lib/optical-center.d.ts +1 -1
  217. package/dist/lib/optical-center.d.ts.map +1 -1
  218. package/dist/lib/optical-center.js +12 -5
  219. package/dist/lib/spring-settle.cjs +1 -1
  220. package/dist/lib/spring-settle.js +1 -1
  221. package/dist/lib/table-internal.cjs +1 -0
  222. package/dist/lib/table-internal.d.ts +62 -0
  223. package/dist/lib/table-internal.d.ts.map +1 -0
  224. package/dist/lib/table-internal.js +18 -0
  225. package/dist/lib/use-controllable.cjs +1 -0
  226. package/dist/lib/use-controllable.d.ts +12 -0
  227. package/dist/lib/use-controllable.d.ts.map +1 -0
  228. package/dist/lib/use-controllable.js +15 -0
  229. package/dist/lib/use-dev-warning.cjs +1 -1
  230. package/dist/lib/utils.cjs +1 -1
  231. package/dist/lib/utils.js +26 -33
  232. package/dist/link.cjs +1 -1
  233. package/dist/link.d.ts +1 -1
  234. package/dist/link.js +78 -124
  235. package/dist/list.cjs +1 -1
  236. package/dist/list.d.ts +8 -0
  237. package/dist/list.d.ts.map +1 -1
  238. package/dist/list.js +94 -156
  239. package/dist/loading.cjs +1 -1
  240. package/dist/loading.js +124 -151
  241. package/dist/logo-mark.cjs +1 -0
  242. package/dist/logo-mark.d.ts +79 -0
  243. package/dist/logo-mark.d.ts.map +1 -0
  244. package/dist/logo-mark.js +219 -0
  245. package/dist/logo.cjs +1 -1
  246. package/dist/logo.d.ts +1 -1
  247. package/dist/logo.d.ts.map +1 -1
  248. package/dist/logo.js +51 -87
  249. package/dist/map.cjs +1 -1
  250. package/dist/map.d.ts.map +1 -1
  251. package/dist/map.js +390 -586
  252. package/dist/media-empty.cjs +1 -1
  253. package/dist/media-empty.js +27 -42
  254. package/dist/media-viewer.cjs +1 -0
  255. package/dist/media-viewer.d.ts +224 -0
  256. package/dist/media-viewer.d.ts.map +1 -0
  257. package/dist/media-viewer.js +295 -0
  258. package/dist/menubar.cjs +1 -1
  259. package/dist/menubar.d.ts +14 -14
  260. package/dist/menubar.d.ts.map +1 -1
  261. package/dist/menubar.js +130 -267
  262. package/dist/multi-select-filter.cjs +1 -1
  263. package/dist/multi-select-filter.d.ts +9 -1
  264. package/dist/multi-select-filter.d.ts.map +1 -1
  265. package/dist/multi-select-filter.js +357 -446
  266. package/dist/navigation-menu.cjs +1 -1
  267. package/dist/navigation-menu.js +108 -172
  268. package/dist/pagination.cjs +1 -1
  269. package/dist/pagination.d.ts +36 -12
  270. package/dist/pagination.d.ts.map +1 -1
  271. package/dist/pagination.js +208 -281
  272. package/dist/popover.cjs +1 -1
  273. package/dist/popover.d.ts +1 -1
  274. package/dist/popover.d.ts.map +1 -1
  275. package/dist/popover.js +34 -45
  276. package/dist/progress.cjs +1 -1
  277. package/dist/progress.d.ts +17 -2
  278. package/dist/progress.d.ts.map +1 -1
  279. package/dist/progress.js +116 -162
  280. package/dist/radio-group.cjs +1 -1
  281. package/dist/radio-group.js +90 -146
  282. package/dist/rating.cjs +1 -1
  283. package/dist/rating.d.ts +80 -13
  284. package/dist/rating.d.ts.map +1 -1
  285. package/dist/rating.js +70 -65
  286. package/dist/relative-date.cjs +1 -1
  287. package/dist/relative-date.d.ts.map +1 -1
  288. package/dist/relative-date.js +73 -89
  289. package/dist/resizable.cjs +1 -1
  290. package/dist/resizable.d.ts +39 -23
  291. package/dist/resizable.d.ts.map +1 -1
  292. package/dist/resizable.js +42 -44
  293. package/dist/result-count.cjs +1 -0
  294. package/dist/result-count.d.ts +110 -0
  295. package/dist/result-count.d.ts.map +1 -0
  296. package/dist/result-count.js +49 -0
  297. package/dist/route-progress.cjs +1 -1
  298. package/dist/route-progress.js +58 -102
  299. package/dist/scroll-area.cjs +1 -1
  300. package/dist/scroll-area.d.ts +9 -1
  301. package/dist/scroll-area.d.ts.map +1 -1
  302. package/dist/scroll-area.js +44 -79
  303. package/dist/select.cjs +2 -2
  304. package/dist/select.d.ts +10 -10
  305. package/dist/select.d.ts.map +1 -1
  306. package/dist/select.js +118 -238
  307. package/dist/separator.cjs +1 -1
  308. package/dist/separator.js +90 -78
  309. package/dist/sheet.cjs +1 -1
  310. package/dist/sheet.d.ts +8 -5
  311. package/dist/sheet.d.ts.map +1 -1
  312. package/dist/sheet.js +250 -317
  313. package/dist/single-select-filter.cjs +1 -1
  314. package/dist/single-select-filter.d.ts +32 -0
  315. package/dist/single-select-filter.d.ts.map +1 -1
  316. package/dist/single-select-filter.js +201 -203
  317. package/dist/skeleton.cjs +1 -1
  318. package/dist/skeleton.js +24 -38
  319. package/dist/slider.cjs +1 -1
  320. package/dist/slider.js +51 -81
  321. package/dist/sonner.cjs +1 -1
  322. package/dist/sonner.d.ts +1 -1
  323. package/dist/sonner.d.ts.map +1 -1
  324. package/dist/sonner.js +101 -125
  325. package/dist/spinner.cjs +1 -1
  326. package/dist/spinner.js +22 -31
  327. package/dist/split-layout.cjs +1 -1
  328. package/dist/split-layout.js +52 -101
  329. package/dist/status.cjs +1 -0
  330. package/dist/status.d.ts +51 -0
  331. package/dist/status.d.ts.map +1 -0
  332. package/dist/status.js +60 -0
  333. package/dist/stepper.cjs +1 -1
  334. package/dist/stepper.js +184 -316
  335. package/dist/switch.cjs +1 -1
  336. package/dist/switch.js +17 -32
  337. package/dist/table.cjs +1 -1
  338. package/dist/table.d.ts +103 -30
  339. package/dist/table.d.ts.map +1 -1
  340. package/dist/table.js +170 -209
  341. package/dist/tabs.cjs +1 -1
  342. package/dist/tabs.d.ts.map +1 -1
  343. package/dist/tabs.js +102 -147
  344. package/dist/text-reveal-motion.cjs +1 -1
  345. package/dist/text-reveal-motion.js +307 -363
  346. package/dist/textarea.cjs +1 -1
  347. package/dist/textarea.d.ts.map +1 -1
  348. package/dist/textarea.js +22 -35
  349. package/dist/toggle-group.cjs +1 -1
  350. package/dist/toggle-group.js +43 -62
  351. package/dist/toggle.cjs +1 -1
  352. package/dist/toggle.js +34 -46
  353. package/dist/tooltip.cjs +1 -1
  354. package/dist/tooltip.d.ts +2 -2
  355. package/dist/tooltip.d.ts.map +1 -1
  356. package/dist/tooltip.js +157 -249
  357. package/dist/typography-heading.cjs +1 -1
  358. package/dist/typography-heading.js +25 -61
  359. package/dist/typography-text.cjs +1 -1
  360. package/dist/typography-text.js +27 -57
  361. package/dist/typography.cjs +1 -1
  362. package/dist/typography.js +132 -340
  363. package/package.json +46 -46
  364. package/src/blocks/empty-state.tsx +34 -18
  365. package/src/blocks/sidebar.tsx +86 -31
  366. package/src/components/accordion.tsx +1 -1
  367. package/src/components/alert-dialog.tsx +4 -2
  368. package/src/components/badge.tsx +127 -15
  369. package/src/components/breadcrumb.tsx +1 -1
  370. package/src/components/button.tsx +8 -6
  371. package/src/components/calendar.tsx +155 -9
  372. package/src/components/card.tsx +63 -10
  373. package/src/components/carousel.tsx +4 -1
  374. package/src/components/chart.tsx +151 -17
  375. package/src/components/checkbox.tsx +1 -1
  376. package/src/components/collapsible.tsx +4 -1
  377. package/src/components/combobox.tsx +40 -7
  378. package/src/components/command.tsx +9 -10
  379. package/src/components/context-menu.tsx +4 -4
  380. package/src/components/data-table.tsx +619 -237
  381. package/src/components/date-picker.tsx +31 -4
  382. package/src/components/delta.tsx +217 -0
  383. package/src/components/drawer.tsx +5 -5
  384. package/src/components/dropdown-menu.tsx +4 -4
  385. package/src/components/field.tsx +36 -15
  386. package/src/components/global-layout.tsx +1 -1
  387. package/src/components/input-chip.tsx +51 -7
  388. package/src/components/input-group.tsx +1 -1
  389. package/src/components/input-password.tsx +15 -19
  390. package/src/components/input.tsx +10 -1
  391. package/src/components/list.tsx +14 -2
  392. package/src/components/logo-mark.tsx +345 -0
  393. package/src/components/map.tsx +18 -20
  394. package/src/components/media-viewer.tsx +908 -0
  395. package/src/components/multi-select-filter.tsx +255 -121
  396. package/src/components/navigation-menu.tsx +2 -2
  397. package/src/components/pagination.tsx +86 -26
  398. package/src/components/progress.tsx +91 -23
  399. package/src/components/rating.tsx +200 -74
  400. package/src/components/relative-date.tsx +19 -11
  401. package/src/components/resizable.tsx +86 -33
  402. package/src/components/result-count.tsx +253 -0
  403. package/src/components/scroll-area.tsx +31 -5
  404. package/src/components/select.tsx +2 -2
  405. package/src/components/sheet.tsx +14 -4
  406. package/src/components/single-select-filter.tsx +136 -41
  407. package/src/components/slider.tsx +2 -2
  408. package/src/components/status.tsx +162 -0
  409. package/src/components/switch.tsx +1 -1
  410. package/src/components/table.tsx +278 -106
  411. package/src/components/tabs.tsx +1 -0
  412. package/src/components/textarea.tsx +20 -2
  413. package/src/components/toggle.tsx +2 -2
  414. package/src/components/tooltip.tsx +11 -20
  415. package/src/hooks/use-filter-search-params.ts +302 -0
  416. package/src/index.ts +6 -0
  417. package/src/lib/compose-event-handlers.ts +14 -0
  418. package/src/lib/download-file.ts +61 -0
  419. package/src/lib/empty-chip.tsx +52 -0
  420. package/src/lib/field-aria.tsx +97 -0
  421. package/src/lib/image-file-info.ts +102 -0
  422. package/src/lib/media-viewer-content.tsx +1587 -0
  423. package/src/lib/media-viewer-internal.tsx +191 -0
  424. package/src/lib/media-viewer-motion.ts +120 -0
  425. package/src/lib/motion.ts +9 -0
  426. package/src/lib/table-internal.ts +74 -0
  427. package/src/lib/use-controllable.ts +43 -0
  428. package/src/lib/empty-chip.ts +0 -24
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brightlocal/ui-components",
3
- "version": "3.2.0",
3
+ "version": "3.3.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
- "Page- or form-level errors and failures that must stay visible (Destructive)",
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 (Warning, Destructive)"
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": false,
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 (top offset --ds-section-padding-y-sm: 16px mobile, 24px from xl), painting the card's surface so content never shows through.",
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": "(info: RowCountRenderInfo) => React.ReactNode — default: renders \"{startRow}-{endRow} of {totalRows}\""
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": "(info: RowCountRenderInfo) => React.ReactNode — default: renders \"{startRow}-{endRow} of {totalRows}\""
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: \"Pick a date\""
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",
@@ -2779,394 +2985,122 @@
2779
2985
  ]
2780
2986
  },
2781
2987
  {
2782
- "name": "MultiSelectFilter",
2783
- "import": "@brightlocal/ui-components/multi-select-filter",
2988
+ "name": "Field",
2989
+ "import": "@brightlocal/ui-components/field",
2784
2990
  "category": "form",
2785
2991
  "exports": [
2786
- "MultiSelectFilter",
2787
- "multiSelectFilterTriggerVariants"
2992
+ "Field",
2993
+ "FieldLabel",
2994
+ "FieldDescription",
2995
+ "FieldError",
2996
+ "FieldErrorIcon",
2997
+ "FieldGroup",
2998
+ "FieldLegend",
2999
+ "FieldSet",
3000
+ "FieldContent"
2788
3001
  ],
2789
- "compound": false,
3002
+ "compound": true,
2790
3003
  "dataHookRequired": true,
2791
3004
  "variants": {
2792
- "size": [
3005
+ "orientation": [
3006
+ "vertical",
3007
+ "horizontal",
3008
+ "responsive"
3009
+ ],
3010
+ "variant": [
2793
3011
  "default",
2794
- "sm"
3012
+ "box"
2795
3013
  ]
2796
3014
  },
2797
3015
  "props": [
2798
- "label",
2799
- "options",
2800
- "value",
2801
- "defaultValue",
2802
- "onValueChange",
2803
- "open",
2804
- "onOpenChange",
2805
- "icon",
2806
- "maxVisibleLabels",
2807
- "allLabel",
2808
- "allCount",
2809
- "searchThreshold",
2810
- "searchable",
2811
- "disabled",
2812
- "presentation",
2813
- "collapseFullSelection",
2814
- "allIcon"
3016
+ "align",
3017
+ "srOnly"
3018
+ ],
3019
+ "description": "Form field wrapper with label, description, and error handling",
3020
+ "aliases": [
3021
+ "form field",
3022
+ "input group",
3023
+ "field wrapper"
2815
3024
  ],
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
3025
  "whenToUse": [
2830
- "Picking several values from one dimension that combine as OR (status, source, city) in a filter bar",
2831
- "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",
2832
- "Stacked in a filter panel or sidebar — className='w-full' takes the row's width; same component, no form-field variant",
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"
3026
+ "A standard label-plus-input layout for any typical form question",
3027
+ "Consistent alignment of label, hint text, and error message without extra setup",
3028
+ "Box variant for card-style questions that need to stand out (highlighted settings, onboarding)"
2836
3029
  ],
2837
3030
  "doNotUseFor": [
2838
- "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)",
2839
- "2–5 values with room to show them all (use ToggleGroup, or the Lab SegmentedControl quick filter)",
2840
- "typing new values into the selection (use InputChip)",
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"
3031
+ "showing information without a form question (use Description or plain text)",
3032
+ "grouping related checkboxes or radios under one heading (use FieldSet with FieldLegend)",
3033
+ "boxed fields in dense forms (adds clutter and vertical space; use the default variant)"
2844
3034
  ],
2845
3035
  "alternatives": [
2846
3036
  {
2847
- "component": "Select",
2848
- "rule": "Use Select for a single choice from a short, known list"
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
- },
3037
+ "component": "Label",
3038
+ "rule": "Use standalone Label only when building a custom field layout — Field includes FieldLabel with proper a11y wiring"
3039
+ }
3040
+ ],
3041
+ "replaces": [],
3042
+ "states": [
3043
+ "default",
3044
+ "invalid"
3045
+ ],
3046
+ "a11yContract": {
3047
+ "role": "group",
3048
+ "requiresLabel": false,
3049
+ "keyboardInteraction": []
3050
+ },
3051
+ "figma": {
3052
+ "fileKey": "p3krmC8DBUgqpbq6cLzaal",
3053
+ "status": "represented-inline",
3054
+ "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."
3055
+ },
3056
+ "decisions": [
2870
3057
  {
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"
3058
+ "date": "2026-10-28",
3059
+ "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.",
3060
+ "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.",
3061
+ "ticket": "DS-899"
2873
3062
  }
3063
+ ]
3064
+ },
3065
+ {
3066
+ "name": "GlobalLayout",
3067
+ "import": "@brightlocal/ui-components/global-layout",
3068
+ "category": "layout",
3069
+ "exports": [
3070
+ "GlobalLayout",
3071
+ "GlobalLayoutSidebar",
3072
+ "GlobalLayoutContent",
3073
+ "GlobalLayoutActions",
3074
+ "GlobalLayoutContentHeader",
3075
+ "GlobalLayoutBackLink",
3076
+ "GlobalLayoutSubtitle",
3077
+ "GlobalLayoutBody",
3078
+ "GlobalLayoutMobileHeader",
3079
+ "GlobalLayoutContentActions",
3080
+ "GlobalLayoutContentBody"
3081
+ ],
3082
+ "compound": true,
3083
+ "dataHookRequired": true,
3084
+ "variants": {
3085
+ "variant": [
3086
+ "full",
3087
+ "md",
3088
+ "sm"
3089
+ ]
3090
+ },
3091
+ "props": [
3092
+ "maxWidth",
3093
+ "width"
2874
3094
  ],
2875
- "figma": {
2876
- "fileKey": "p3krmC8DBUgqpbq6cLzaal",
2877
- "nodes": [
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
- ]
2953
- },
2954
- "knownGaps": [
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
- },
2959
- {
2960
- "description": "Picks apply at once in both presentations — there is no batch/Apply mode on a single filter",
2961
- "workaround": "A batch drawer of several filters is the Filtering page's MobileFilterDrawer recipe (Drawer + multiSelectFilterTriggerVariants), to be packaged as a FilterDrawer block"
2962
- }
2963
- ]
2964
- },
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
- {
3132
- "name": "GlobalLayout",
3133
- "import": "@brightlocal/ui-components/global-layout",
3134
- "category": "layout",
3135
- "exports": [
3136
- "GlobalLayout",
3137
- "GlobalLayoutSidebar",
3138
- "GlobalLayoutContent",
3139
- "GlobalLayoutActions",
3140
- "GlobalLayoutContentHeader",
3141
- "GlobalLayoutBackLink",
3142
- "GlobalLayoutSubtitle",
3143
- "GlobalLayoutBody",
3144
- "GlobalLayoutMobileHeader",
3145
- "GlobalLayoutContentActions",
3146
- "GlobalLayoutContentBody"
3147
- ],
3148
- "compound": true,
3149
- "dataHookRequired": true,
3150
- "variants": {
3151
- "variant": [
3152
- "full",
3153
- "md",
3154
- "sm"
3155
- ]
3156
- },
3157
- "props": [
3158
- "maxWidth",
3159
- "width"
3160
- ],
3161
- "i18nProps": {
3162
- "GlobalLayoutMobileHeader": {
3163
- "ariaLabel": "string — default: \"Mobile navigation\""
3164
- },
3165
- "GlobalLayoutBackLink": {
3166
- "ariaLabel": "string — default: \"Go back\""
3167
- }
3168
- },
3169
- "description": "Full-page responsive layout with sidebar",
3095
+ "i18nProps": {
3096
+ "GlobalLayoutMobileHeader": {
3097
+ "ariaLabel": "string — default: \"Mobile navigation\""
3098
+ },
3099
+ "GlobalLayoutBackLink": {
3100
+ "ariaLabel": "string — default: \"Go back\""
3101
+ }
3102
+ },
3103
+ "description": "Full-page responsive layout with sidebar",
3170
3104
  "figma": {
3171
3105
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
3172
3106
  "nodes": [
@@ -3611,7 +3545,8 @@
3611
3545
  "defaultValue",
3612
3546
  "disabled",
3613
3547
  "allowDuplicates",
3614
- "error"
3548
+ "error",
3549
+ "onBeforeAdd"
3615
3550
  ],
3616
3551
  "i18nProps": {
3617
3552
  "InputChipItems": {
@@ -3661,6 +3596,20 @@
3661
3596
  "choosing from an existing list (use Combobox)",
3662
3597
  "displaying already-chosen tags with no typing (use Chip)",
3663
3598
  "adding many items at once via paste with per-row remove controls (use InputList)"
3599
+ ],
3600
+ "decisions": [
3601
+ {
3602
+ "date": "2026-10-30",
3603
+ "ticket": "DS-1224",
3604
+ "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.",
3605
+ "why": "Matches the pre-validation pattern consumers asked for without breaking the existing uncontrolled flow"
3606
+ },
3607
+ {
3608
+ "date": "2026-10-30",
3609
+ "ticket": "DS-1225",
3610
+ "decision": "InputChipInput ref flipped from HTMLDivElement to HTMLInputElement via useImperativeHandle; wrapper access via wrapperRef prop",
3611
+ "why": "DS form contract requires ref → interactive element for focus management and aria-describedby wiring; wrapperRef covers the rare case of measuring the container"
3612
+ }
3664
3613
  ]
3665
3614
  },
3666
3615
  {
@@ -3998,6 +3947,10 @@
3998
3947
  "filled",
3999
3948
  "outline",
4000
3949
  "loading"
3950
+ ],
3951
+ "align": [
3952
+ "center",
3953
+ "start"
4001
3954
  ]
4002
3955
  },
4003
3956
  "props": [],
@@ -4106,30 +4059,166 @@
4106
4059
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
4107
4060
  "nodes": [
4108
4061
  {
4109
- "nodeId": "18315:468385",
4110
- "figmaName": "Logo",
4062
+ "nodeId": "18315:468385",
4063
+ "figmaName": "Logo",
4064
+ "kind": "componentSet",
4065
+ "export": "Logo",
4066
+ "axes": [
4067
+ {
4068
+ "figma": "Variant",
4069
+ "code": "variant"
4070
+ }
4071
+ ]
4072
+ }
4073
+ ],
4074
+ "unmappedExports": [],
4075
+ "figmaOnly": []
4076
+ },
4077
+ "whenToUse": [
4078
+ "Headers, footers, and branded spaces with room for the full wordmark (logotype)",
4079
+ "Compact or mobile spaces like collapsed sidebars (mark)",
4080
+ "Favicon or app-icon style placements (mark)"
4081
+ ],
4082
+ "doNotUseFor": [
4083
+ "representing a person (use Avatar)",
4084
+ "tight spaces with the full logotype (use the mark variant)"
4085
+ ]
4086
+ },
4087
+ {
4088
+ "name": "LogoMark",
4089
+ "import": "@brightlocal/ui-components/logo-mark",
4090
+ "category": "display",
4091
+ "exports": [
4092
+ "LogoMark",
4093
+ "SOURCE_ICON_ALIASES"
4094
+ ],
4095
+ "compound": false,
4096
+ "dataHookRequired": true,
4097
+ "variants": {
4098
+ "variant": [
4099
+ "transparent",
4100
+ "filled",
4101
+ "border"
4102
+ ],
4103
+ "size": [
4104
+ "xs",
4105
+ "sm",
4106
+ "md",
4107
+ "lg"
4108
+ ],
4109
+ "colorScheme": [
4110
+ "original",
4111
+ "neutral"
4112
+ ]
4113
+ },
4114
+ "props": [
4115
+ "name",
4116
+ "size",
4117
+ "variant",
4118
+ "colorScheme",
4119
+ "fallback",
4120
+ "ariaLabel"
4121
+ ],
4122
+ "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.",
4123
+ "knownGaps": [
4124
+ {
4125
+ "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.",
4126
+ "workaround": "Use static SVG icons from @brightlocal/icons/social-media in Select-based filters instead of LogoMark."
4127
+ }
4128
+ ],
4129
+ "i18nProps": {
4130
+ "LogoMark": {
4131
+ "ariaLabel": "string — default: undefined (decorative aria-hidden when omitted; pass to announce as img)"
4132
+ }
4133
+ },
4134
+ "decisions": [
4135
+ {
4136
+ "decision": "Three explicit variants instead of boolean container prop",
4137
+ "why": "transparent/filled/border is clearer than container=true/false + neutral; each variant has a distinct visual treatment",
4138
+ "date": "2026-10-27",
4139
+ "ticket": "DS-1060"
4140
+ },
4141
+ {
4142
+ "decision": "Dual icon resolution: social-media → lucide → letter fallback",
4143
+ "why": "Component is used for both brand logos and generic lucide icons across the product; single name prop resolves both registries",
4144
+ "date": "2026-10-27",
4145
+ "ticket": "DS-1060"
4146
+ },
4147
+ {
4148
+ "decision": "Renamed from SourceLogo to LogoMark",
4149
+ "why": "The component is no longer limited to source/platform logos — it handles any brand or icon mark",
4150
+ "date": "2026-10-27",
4151
+ "ticket": "DS-1060"
4152
+ },
4153
+ {
4154
+ "decision": "colorScheme prop for original vs neutral icon variants",
4155
+ "why": "Location Manager social links row needs monochrome icons; reversed prior ruledOut after discovering prototype usage",
4156
+ "date": "2026-10-28",
4157
+ "ticket": "DS-1060"
4158
+ },
4159
+ {
4160
+ "decision": "Only verified brand artwork enters the social-media registry; sources without one render the letter fallback",
4161
+ "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.",
4162
+ "date": "2026-10-28",
4163
+ "ticket": "DS-1060"
4164
+ },
4165
+ {
4166
+ "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)",
4167
+ "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",
4168
+ "date": "2026-10-28",
4169
+ "ticket": "DS-1060"
4170
+ },
4171
+ {
4172
+ "decision": "Per-icon lazy loading through iconImports from @brightlocal/icons/dynamic",
4173
+ "why": "Importing the social-media barrel pulled every registered icon into one chunk on first render",
4174
+ "date": "2026-10-28",
4175
+ "ticket": "DS-1060"
4176
+ }
4177
+ ],
4178
+ "ruledOut": [
4179
+ {
4180
+ "option": "Hand-drawn or AI-generated approximations of brand marks",
4181
+ "why": "Not the brand's logo; see decision of 2026-10-28",
4182
+ "ticket": "DS-1060"
4183
+ }
4184
+ ],
4185
+ "figma": {
4186
+ "fileKey": "p3krmC8DBUgqpbq6cLzaal",
4187
+ "note": "Mapped on DS-1060 Figma branch eBiPZa4scA07GtyHQP9uY0; node IDs valid after branch merge. State axis uses FIG-5 reserved word — see FIG-32.",
4188
+ "nodes": [
4189
+ {
4190
+ "nodeId": "35320:4945",
4191
+ "figmaName": "Logo Mark",
4111
4192
  "kind": "componentSet",
4112
- "export": "Logo",
4193
+ "export": "LogoMark",
4113
4194
  "axes": [
4114
4195
  {
4115
4196
  "figma": "Variant",
4116
4197
  "code": "variant"
4198
+ },
4199
+ {
4200
+ "figma": "Size",
4201
+ "code": "size"
4202
+ },
4203
+ {
4204
+ "figma": "Color Scheme",
4205
+ "code": "colorScheme"
4206
+ },
4207
+ {
4208
+ "figma": "State",
4209
+ "exempt": "figma-only-style",
4210
+ "note": "Known/Fallback is a runtime resolution outcome (not a consumer prop); demonstrates the two visual states"
4117
4211
  }
4118
4212
  ]
4119
4213
  }
4120
4214
  ],
4121
- "unmappedExports": [],
4122
- "figmaOnly": []
4123
- },
4124
- "whenToUse": [
4125
- "Headers, footers, and branded spaces with room for the full wordmark (logotype)",
4126
- "Compact or mobile spaces like collapsed sidebars (mark)",
4127
- "Favicon or app-icon style placements (mark)"
4128
- ],
4129
- "doNotUseFor": [
4130
- "representing a person (use Avatar)",
4131
- "tight spaces with the full logotype (use the mark variant)"
4132
- ]
4215
+ "unmappedExports": [
4216
+ {
4217
+ "export": "SOURCE_ICON_ALIASES",
4218
+ "reason": "Constant (Record<string, string>) — not a component, no Figma representation"
4219
+ }
4220
+ ]
4221
+ }
4133
4222
  },
4134
4223
  {
4135
4224
  "name": "Map",
@@ -4304,6 +4393,162 @@
4304
4393
  }
4305
4394
  }
4306
4395
  },
4396
+ {
4397
+ "name": "MediaViewer",
4398
+ "import": "@brightlocal/ui-components/media-viewer",
4399
+ "category": "overlay",
4400
+ "exports": [
4401
+ "MediaViewer",
4402
+ "MediaViewerTrigger",
4403
+ "MediaViewerAddon",
4404
+ "MediaViewerContent",
4405
+ "MediaViewerTitle",
4406
+ "MediaViewerActions"
4407
+ ],
4408
+ "compound": true,
4409
+ "dataHookRequired": true,
4410
+ "variants": {},
4411
+ "props": [
4412
+ "items",
4413
+ "index",
4414
+ "defaultIndex",
4415
+ "onIndexChange",
4416
+ "open",
4417
+ "defaultOpen",
4418
+ "onOpenChange",
4419
+ "actions",
4420
+ "formatActionsLabel",
4421
+ "viewable",
4422
+ "indicator",
4423
+ "formatPosition",
4424
+ "previousLabel",
4425
+ "nextLabel",
4426
+ "thumbnailsLabel",
4427
+ "unavailableMessage",
4428
+ "formatLabel",
4429
+ "zoomInLabel",
4430
+ "zoomOutLabel",
4431
+ "downloadLabel",
4432
+ "infoLabel",
4433
+ "dateLabels"
4434
+ ],
4435
+ "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.",
4436
+ "aliases": [
4437
+ "lightbox",
4438
+ "photo viewer",
4439
+ "image viewer",
4440
+ "screenshot viewer",
4441
+ "gallery dialog",
4442
+ "thumbnail",
4443
+ "photo tile",
4444
+ "image preview",
4445
+ "preview tile",
4446
+ "screenshot thumbnail",
4447
+ "photo gallery"
4448
+ ],
4449
+ "whenToUse": [
4450
+ "A preview of an image, or a grid of them, that opens a full view and steps through the set (saved screenshots, business photos)"
4451
+ ],
4452
+ "doNotUseFor": [
4453
+ "a plain non-interactive image (use AspectRatio with an img)",
4454
+ "a missing-media slot with nothing to open (use MediaEmpty)",
4455
+ "a form or free-form content in a modal (use Dialog)",
4456
+ "an inline slideshow on the page (use Carousel)"
4457
+ ],
4458
+ "i18nProps": {
4459
+ "MediaViewer": {
4460
+ "formatActionsLabel": "(item, index) => string — default: \"More actions for {item.alt}\" (\"image {index + 1}\" when alt is empty)"
4461
+ },
4462
+ "MediaViewerContent": {
4463
+ "previousLabel": "string — default: \"Previous\"",
4464
+ "nextLabel": "string — default: \"Next\"",
4465
+ "thumbnailsLabel": "string — default: \"Images\"",
4466
+ "zoomInLabel": "string — default: \"Zoom in\"",
4467
+ "zoomOutLabel": "string — default: \"Zoom out\"",
4468
+ "downloadLabel": "string — default: \"Download\"",
4469
+ "infoLabel": "string — default: \"Image details\" (the ⓘ button; its tooltip shows format, size in pixels and file size)",
4470
+ "dateLabels": "Partial<RelativeDateLabels> — default: RelativeDate's English words",
4471
+ "unavailableMessage": "string — default: \"Image no longer available\"",
4472
+ "formatPosition": "(current, total) => string — default: \"{current} of {total}\""
4473
+ },
4474
+ "MediaViewerTrigger": {
4475
+ "emptyMessage": "string — default: \"No photo available\"",
4476
+ "unavailableMessage": "string — default: \"Image no longer available\"",
4477
+ "formatLabel": "(item, index, total) => string — default: item.alt, or \"Image {index + 1} of {total}\" when it is empty (the button's name)"
4478
+ }
4479
+ },
4480
+ "a11yContract": {
4481
+ "role": "dialog",
4482
+ "requiresLabel": true,
4483
+ "keyboardInteraction": [
4484
+ "Escape",
4485
+ "ArrowLeft",
4486
+ "ArrowRight",
4487
+ "+",
4488
+ "-",
4489
+ "Tab"
4490
+ ]
4491
+ },
4492
+ "states": [
4493
+ "open",
4494
+ "closed"
4495
+ ],
4496
+ "decisions": [
4497
+ {
4498
+ "date": "2026-10-31",
4499
+ "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.",
4500
+ "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.",
4501
+ "ticket": "DS-1204"
4502
+ },
4503
+ {
4504
+ "date": "2026-10-31",
4505
+ "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.",
4506
+ "why": "Same backdrop as every modal; the whole stage is the close target, as in Telegram's viewer.",
4507
+ "ticket": "DS-1204"
4508
+ },
4509
+ {
4510
+ "date": "2026-11-01",
4511
+ "decision": "The view's backdrop is darker than a modal's (black at 85%), and the bottom bar has no shade of its own.",
4512
+ "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.",
4513
+ "ticket": "DS-1204"
4514
+ },
4515
+ {
4516
+ "date": "2026-11-01",
4517
+ "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.",
4518
+ "why": "Stretching a small file to the stage made it blurry; the Zoom buttons already give a bigger view on demand.",
4519
+ "ticket": "DS-1204"
4520
+ },
4521
+ {
4522
+ "date": "2026-10-31",
4523
+ "decision": "Previous / Next are full-height strips and the thumbnails are image buttons, both raw <button>; the arrow is drawn with ButtonVariants ghost.",
4524
+ "why": "No DS component is a full-height hit strip or an image thumbnail; a Button would need appearance overrides.",
4525
+ "ticket": "DS-1204"
4526
+ },
4527
+ {
4528
+ "date": "2026-10-31",
4529
+ "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.",
4530
+ "why": "A widely used, well-tried approach rather than one tuned to a single trackpad.",
4531
+ "ticket": "DS-1204"
4532
+ }
4533
+ ],
4534
+ "ruledOut": [
4535
+ {
4536
+ "option": "The browser Fullscreen API for the view",
4537
+ "why": "Permission prompts and no support on iOS; a window-filling dialog does the same everywhere.",
4538
+ "ticket": "DS-1204"
4539
+ },
4540
+ {
4541
+ "option": "Three states: preview, a modal, then full screen",
4542
+ "why": "An extra step between the preview and the image; the preview opens the full view.",
4543
+ "ticket": "DS-1204"
4544
+ },
4545
+ {
4546
+ "option": "Reading the finger lift from wheel deltas (deceleration, short quiet timers)",
4547
+ "why": "Unreliable across trackpads: it stalled swipes half-way, dropped quick second swipes and ran fast ones through the set.",
4548
+ "ticket": "DS-1204"
4549
+ }
4550
+ ]
4551
+ },
4307
4552
  {
4308
4553
  "name": "Menubar",
4309
4554
  "import": "@brightlocal/ui-components/menubar",
@@ -4428,10 +4673,205 @@
4428
4673
  "Power-user, keyboard-navigable tools expecting app-menu structure",
4429
4674
  "Internal or admin tools modeled after desktop software conventions"
4430
4675
  ],
4431
- "doNotUseFor": [
4432
- "a single dropdown of actions (use DropdownMenu)",
4433
- "mobile or touch-first contexts",
4434
- "primary app navigation (use NavigationMenu or Sidebar)"
4676
+ "doNotUseFor": [
4677
+ "a single dropdown of actions (use DropdownMenu)",
4678
+ "mobile or touch-first contexts",
4679
+ "primary app navigation (use NavigationMenu or Sidebar)"
4680
+ ]
4681
+ },
4682
+ {
4683
+ "name": "MultiSelectFilter",
4684
+ "import": "@brightlocal/ui-components/multi-select-filter",
4685
+ "category": "form",
4686
+ "exports": [
4687
+ "MultiSelectFilter",
4688
+ "multiSelectFilterTriggerVariants"
4689
+ ],
4690
+ "compound": false,
4691
+ "dataHookRequired": true,
4692
+ "variants": {
4693
+ "size": [
4694
+ "default",
4695
+ "sm"
4696
+ ]
4697
+ },
4698
+ "props": [
4699
+ "label",
4700
+ "options",
4701
+ "value",
4702
+ "defaultValue",
4703
+ "onValueChange",
4704
+ "open",
4705
+ "onOpenChange",
4706
+ "icon",
4707
+ "maxVisibleLabels",
4708
+ "allLabel",
4709
+ "allCount",
4710
+ "searchThreshold",
4711
+ "searchable",
4712
+ "disabled",
4713
+ "presentation",
4714
+ "collapseFullSelection",
4715
+ "allIcon"
4716
+ ],
4717
+ "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.",
4718
+ "i18nProps": {
4719
+ "MultiSelectFilter": {
4720
+ "clearLabel": "string — default: \"Clear filters\"",
4721
+ "summaryLabel": "string — default: \"{labels} +{rest}\" (placeholders: {labels}, {rest}, {count})",
4722
+ "searchPlaceholder": "string — default: \"Search options...\"",
4723
+ "emptyLabel": "string — default: \"No options found.\"",
4724
+ "doneLabel": "string — default: \"Done\" (the drawer's close button)",
4725
+ "drawerDescription": "string — default: \"Picks apply as you make them.\" (sr-only drawer description)",
4726
+ "emptyDescription": "string — default: \"Try another search.\" (hint under the no-match message)",
4727
+ "clearSearchAriaLabel": "string — default: \"Clear search\" (the menu and drawer search clear button)"
4728
+ }
4729
+ },
4730
+ "whenToUse": [
4731
+ "Picking several values from one dimension that combine as OR (status, source, city) in a filter bar",
4732
+ "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",
4733
+ "Stacked in a filter panel or sidebar — className='w-full' takes the row's width; same component, no form-field variant",
4734
+ "Any option list past ~10 values — the menu's autofocused search input and pinned selections handle it",
4735
+ "Desktop: presentation='menu' (default), the Popover + Command menu beside a Select in a toolbar (size='default', h-9, text-field)",
4736
+ "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"
4737
+ ],
4738
+ "doNotUseFor": [
4739
+ "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)",
4740
+ "2–5 values with room to show them all (use ToggleGroup, or the Lab SegmentedControl quick filter)",
4741
+ "typing new values into the selection (use InputChip)",
4742
+ "a form field that validates and submits — this is a filter and has no error state; a form multi-select is a separate component",
4743
+ "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)",
4744
+ "a batch drawer of several filters behind one Apply — not a DS pattern: on a phone each filter opens its own drawer (presentation='auto')"
4745
+ ],
4746
+ "alternatives": [
4747
+ {
4748
+ "component": "Select",
4749
+ "rule": "Use Select for a single choice from a short, known list"
4750
+ },
4751
+ {
4752
+ "component": "Combobox",
4753
+ "rule": "Use Combobox for a single choice from a long, searchable list — it is single-value by design"
4754
+ },
4755
+ {
4756
+ "component": "ToggleGroup",
4757
+ "rule": "Use ToggleGroup (or the Lab SegmentedControl) for a quick filter kept visible in the bar"
4758
+ },
4759
+ {
4760
+ "component": "InputChip",
4761
+ "rule": "Use InputChip when the person types new values rather than picking existing ones"
4762
+ },
4763
+ {
4764
+ "component": "Drawer",
4765
+ "rule": "presentation='drawer' (or 'auto' below md) opens this filter's picks in a bottom Drawer; there is no batch drawer holding several filters"
4766
+ },
4767
+ {
4768
+ "component": "Chip",
4769
+ "rule": "Never repeat a MultiSelectFilter's picks as Chips — the trigger already reads them ('Google +2')"
4770
+ },
4771
+ {
4772
+ "component": "SingleSelectFilter",
4773
+ "rule": "Use SingleSelectFilter for one value from a dimension — it shares the trigger look and the drawer, with a DS Select on desktop"
4774
+ }
4775
+ ],
4776
+ "figma": {
4777
+ "fileKey": "p3krmC8DBUgqpbq6cLzaal",
4778
+ "nodes": [
4779
+ {
4780
+ "nodeId": "34233:70287",
4781
+ "figmaName": "Multi Select Filter",
4782
+ "kind": "componentSet",
4783
+ "export": "MultiSelectFilter",
4784
+ "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.",
4785
+ "axes": [
4786
+ {
4787
+ "figma": "Size",
4788
+ "code": "size"
4789
+ },
4790
+ {
4791
+ "figma": "State",
4792
+ "exempt": "interaction-state",
4793
+ "valueToProp": {
4794
+ "Disabled": "disabled"
4795
+ },
4796
+ "note": "Focus and Open are runtime states"
4797
+ }
4798
+ ]
4799
+ }
4800
+ ],
4801
+ "unmappedExports": [
4802
+ {
4803
+ "export": "multiSelectFilterTriggerVariants",
4804
+ "reason": "cva style helper, not a component — the Multi Select Filter set's variants are its drawing"
4805
+ }
4806
+ ],
4807
+ "figmaOnly": [
4808
+ {
4809
+ "nodeId": "34233:70355",
4810
+ "figmaName": "Multi Select Filter / Menu Item",
4811
+ "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."
4812
+ },
4813
+ {
4814
+ "nodeId": "34233:70435",
4815
+ "figmaName": "Multi Select Filter / Menu",
4816
+ "reason": "The Popover + Command menu MultiSelectFilter renders internally (search, All row, options, empty, Clear); no sub-part export by design."
4817
+ }
4818
+ ]
4819
+ },
4820
+ "aliases": [
4821
+ "faceted filter",
4822
+ "facet filter",
4823
+ "multi-select",
4824
+ "multi select dropdown",
4825
+ "filter dropdown",
4826
+ "checkbox filter",
4827
+ "filter menu",
4828
+ "mobile filter drawer"
4829
+ ],
4830
+ "replaces": [
4831
+ "Lab FacetedFilter",
4832
+ "Lab SearchableMultiSelect",
4833
+ "Lab FilterTrigger (as multiSelectFilterTriggerVariants + Badge srLabel)",
4834
+ "per-app faceted-filter copies in the prototypes"
4835
+ ],
4836
+ "states": [
4837
+ "closed",
4838
+ "open (menu)",
4839
+ "open (drawer)",
4840
+ "searching",
4841
+ "no match",
4842
+ "disabled"
4843
+ ],
4844
+ "a11yContract": {
4845
+ "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",
4846
+ "requiresLabel": true,
4847
+ "keyboardInteraction": [
4848
+ "Enter/Space opens",
4849
+ "Arrow keys move between options (cmdk root takes focus when there is no search input)",
4850
+ "Enter toggles the highlighted option; the menu stays open",
4851
+ "Type to narrow past the search threshold",
4852
+ "Escape closes and returns focus to the trigger"
4853
+ ]
4854
+ },
4855
+ "knownGaps": [
4856
+ {
4857
+ "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",
4858
+ "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"
4859
+ }
4860
+ ],
4861
+ "decisions": [
4862
+ {
4863
+ "date": "2026-11-02",
4864
+ "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.",
4865
+ "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.",
4866
+ "ticket": "DS-973"
4867
+ }
4868
+ ],
4869
+ "ruledOut": [
4870
+ {
4871
+ "option": "Hiding the filter when the current data leaves it nothing to choose",
4872
+ "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.",
4873
+ "ticket": "DS-973"
4874
+ }
4435
4875
  ]
4436
4876
  },
4437
4877
  {
@@ -4569,7 +5009,10 @@
4569
5009
  "nextAriaLabel": "string — default: \"Go to next page\"",
4570
5010
  "pageAriaLabel": "string — default: \"Go to page {page}\"",
4571
5011
  "ellipsisSrLabel": "string — default: \"More pages\"",
4572
- "renderCaption": "render prop — default: \"Showing {from} to {to} of {total} results\""
5012
+ "renderCaption": "render prop — plain-text escape hatch; prefer captionLabel",
5013
+ "captionLabel": "string — default: \"{from} to {to} of {total} results\"",
5014
+ "captionLabelOne": "string — default: \"{from} to {to} of {total} result\"; used at total === 1",
5015
+ "captionEmptyLabel": "string — default: \"No results\"; screen-reader-only at zero items"
4573
5016
  },
4574
5017
  "PaginationPrevious": {
4575
5018
  "ariaLabel": "string — default: \"Go to previous page\""
@@ -4649,6 +5092,14 @@
4649
5092
  "lists inside a Data Table (use its built-in pagination)",
4650
5093
  "continuously loading content (use infinite scroll)",
4651
5094
  "result sets that fit on one screen"
5095
+ ],
5096
+ "decisions": [
5097
+ {
5098
+ "date": "2026-09-09",
5099
+ "decision": "Pagination hides itself when there is nothing to navigate (one page or fewer); consumers do not add their own totalPages > 1 guard.",
5100
+ "why": "A lone disabled arrow pair reads as a broken control rather than a boundary. DataTablePaginationNav and PaginationControls must agree.",
5101
+ "ticket": "DS-900"
5102
+ }
4652
5103
  ]
4653
5104
  },
4654
5105
  {
@@ -4750,6 +5201,10 @@
4750
5201
  "size": [
4751
5202
  "sm",
4752
5203
  "md"
5204
+ ],
5205
+ "labelPlacement": [
5206
+ "inline",
5207
+ "above"
4753
5208
  ]
4754
5209
  },
4755
5210
  "props": [
@@ -4757,18 +5212,17 @@
4757
5212
  "max",
4758
5213
  "color",
4759
5214
  "size",
5215
+ "labelPlacement",
4760
5216
  "showValue",
4761
5217
  "unit",
4762
5218
  "valueFormatter",
4763
5219
  "ariaLabel",
4764
5220
  "label",
4765
- "statusDescription",
4766
- "indeterminate",
4767
5221
  "labelWidth",
4768
5222
  "indicatorClassName",
4769
5223
  "disabled"
4770
5224
  ],
4771
- "description": "Progress bar indicator with optional inline label (text, or a node such as a Rating or icon), numeric value with optional custom formatting, and brand color options",
5225
+ "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
5226
  "i18nProps": {
4773
5227
  "Progress": {
4774
5228
  "ariaLabel": "string — default: \"Progress\" (required when `label` is an element)"
@@ -4782,7 +5236,7 @@
4782
5236
  "figmaName": "Progress",
4783
5237
  "kind": "componentSet",
4784
5238
  "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 brand palette by decision (green-400, brand-primary-foreground/20, brand-red/orange/yellow + /20) — Figma binds the same variables; not the chart-* tokens. 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.",
5239
+ "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
5240
  "axes": [
4787
5241
  {
4788
5242
  "figma": "Colour",
@@ -4813,6 +5267,32 @@
4813
5267
  "stalled or failed tasks (use Alert for the failure)",
4814
5268
  "unknown waits with no real percentage (Skeleton covers initial content loading)",
4815
5269
  "static scores with the green variant (colored variant is the meter-style option)"
5270
+ ],
5271
+ "decisions": [
5272
+ {
5273
+ "date": "2026-09-10",
5274
+ "decision": "Progress is determinate only: indeterminate and statusDescription were removed (breaking, 3.0.0).",
5275
+ "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.",
5276
+ "ticket": "DS-908"
5277
+ },
5278
+ {
5279
+ "date": "2026-10-30",
5280
+ "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.",
5281
+ "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.",
5282
+ "ticket": "DS-1217"
5283
+ }
5284
+ ],
5285
+ "ruledOut": [
5286
+ {
5287
+ "option": "An indeterminate (sweeping) Progress bar",
5288
+ "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).",
5289
+ "ticket": "DS-908"
5290
+ },
5291
+ {
5292
+ "option": "A statusDescription line above the bar",
5293
+ "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.",
5294
+ "ticket": "DS-908"
5295
+ }
4816
5296
  ]
4817
5297
  },
4818
5298
  {
@@ -4908,14 +5388,25 @@
4908
5388
  ],
4909
5389
  "compound": false,
4910
5390
  "dataHookRequired": true,
4911
- "variants": {},
5391
+ "variants": {
5392
+ "variant": [
5393
+ "stars",
5394
+ "recommendation"
5395
+ ],
5396
+ "size": [
5397
+ "sm",
5398
+ "md"
5399
+ ]
5400
+ },
4912
5401
  "props": [
4913
5402
  "value"
4914
5403
  ],
4915
- "description": "Star rating display (0–5, 0.5 increments)",
5404
+ "description": "Review score display: a 0–5 star value (0.5 increments) or Facebook's Recommended / Not recommended verdict",
4916
5405
  "i18nProps": {
4917
5406
  "Rating": {
4918
- "ariaLabel": "string — default: \"Rating: {value} out of 5 stars\""
5407
+ "ariaLabel": "string — default: \"Rating: {value} out of 5 stars\" (stars)",
5408
+ "recommendedLabel": "string — default: \"Recommended\" (recommendation)",
5409
+ "notRecommendedLabel": "string — default: \"Not recommended\" (recommendation)"
4919
5410
  }
4920
5411
  },
4921
5412
  "figma": {
@@ -4927,15 +5418,23 @@
4927
5418
  "kind": "componentSet",
4928
5419
  "export": "Rating",
4929
5420
  "axes": [
5421
+ {
5422
+ "figma": "Variant",
5423
+ "code": "variant"
5424
+ },
4930
5425
  {
4931
5426
  "figma": "Rating",
4932
5427
  "exempt": "figma-only-style",
4933
- "note": "Discrete value-prop demos (1.0–5.0) — value is continuous in code"
5428
+ "note": "Discrete value demos — 1.0–5.0 for Stars (value is continuous in code), Recommended / Not recommended for Recommendation (code: recommended boolean)"
4934
5429
  },
4935
5430
  {
4936
5431
  "figma": "Size",
4937
- "exempt": "figma-only-style",
4938
- "note": "No size variant in code"
5432
+ "code": "size",
5433
+ "valueAliases": {
5434
+ "Default": "md",
5435
+ "Small": "sm"
5436
+ },
5437
+ "note": "Figma Default = 24px = code md, Small = 16px = code sm (DS-544). Show Label (BOOLEAN) ↔ showLabel on the Recommendation variants"
4939
5438
  }
4940
5439
  ]
4941
5440
  }
@@ -4945,12 +5444,14 @@
4945
5444
  },
4946
5445
  "whenToUse": [
4947
5446
  "Showing a star-based score, like 4.5 out of 5, on a review, listing, or summary card",
5447
+ "Showing a Facebook review's Recommended / Not recommended verdict beside star ratings from other sources (variant=\"recommendation\")",
4948
5448
  "Visualizing quality or satisfaction where the star convention is expected",
4949
5449
  "Summarizing aggregate customer feedback at a glance"
4950
5450
  ],
4951
5451
  "doNotUseFor": [
4952
- "collecting a rating from the user (display-only, no input)",
4953
- "non-star scores or counts (use plain text or Badge)"
5452
+ "collecting a rating or a like/dislike from the user (display-only, no input — use ToggleGroup)",
5453
+ "counts or category labels (use plain text or Badge)",
5454
+ "scores with no star or thumbs convention, like 7/10 or NPS (use plain text)"
4954
5455
  ]
4955
5456
  },
4956
5457
  {
@@ -4976,7 +5477,7 @@
4976
5477
  "labels",
4977
5478
  "className"
4978
5479
  ],
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.",
5480
+ "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
5481
  "aliases": [
4981
5482
  "last updated",
4982
5483
  "time ago",
@@ -5087,6 +5588,78 @@
5087
5588
  "small/mobile screens where drag-resize is impractical (use a fixed stacked layout)"
5088
5589
  ]
5089
5590
  },
5591
+ {
5592
+ "name": "ResultCount",
5593
+ "import": "@brightlocal/ui-components/result-count",
5594
+ "category": "display",
5595
+ "exports": [
5596
+ "ResultCount"
5597
+ ],
5598
+ "compound": false,
5599
+ "dataHookRequired": true,
5600
+ "variants": {},
5601
+ "props": [
5602
+ "count",
5603
+ "total",
5604
+ "from",
5605
+ "to",
5606
+ "updating"
5607
+ ],
5608
+ "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.",
5609
+ "i18nProps": {
5610
+ "ResultCount": {
5611
+ "label": "string — default: \"{count} of {total} results\"",
5612
+ "labelOne": "string — default: \"{count} of {total} result\"; used at total === 1, falls back to label",
5613
+ "noTotalLabel": "string — default: \"{count} results\"",
5614
+ "noTotalLabelOne": "string — default: \"{count} result\"; used at count === 1, falls back to noTotalLabel",
5615
+ "rangeLabel": "string — default: \"{from} to {to} of {total} results\"",
5616
+ "rangeLabelOne": "string — default: \"{from} to {to} of {total} result\"; used at total === 1, falls back to rangeLabel",
5617
+ "updatingLabel": "string — default: \"Updating results\"",
5618
+ "emptyLabel": "string — default: \"No results\""
5619
+ }
5620
+ },
5621
+ "whenToUse": [
5622
+ "The count a filterable list shows in its toolbar — what the search and filters left",
5623
+ "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"
5624
+ ],
5625
+ "doNotUseFor": [
5626
+ "a second count on the same collection (one count per collection: toolbar or pagination row, not both)",
5627
+ "live announcements that are not a count — use the empty state, FieldError or a toast"
5628
+ ],
5629
+ "decisions": [
5630
+ {
5631
+ "date": "2026-10-31",
5632
+ "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.",
5633
+ "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.",
5634
+ "ticket": "DS-973"
5635
+ },
5636
+ {
5637
+ "date": "2026-11-02",
5638
+ "decision": "The label templates accept i18next's `{{count}}` / `{{from}}` form as well as the DS `{count}` / `{from}` form, every occurrence replaced.",
5639
+ "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.",
5640
+ "ticket": "DS-973"
5641
+ },
5642
+ {
5643
+ "date": "2026-11-02",
5644
+ "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.",
5645
+ "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.",
5646
+ "ticket": "DS-973"
5647
+ },
5648
+ {
5649
+ "date": "2026-11-02",
5650
+ "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.",
5651
+ "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.",
5652
+ "ticket": "DS-973"
5653
+ }
5654
+ ],
5655
+ "ruledOut": [
5656
+ {
5657
+ "option": "A second count component for the pagination row",
5658
+ "why": "Two wordings for the same numbers was the drift the Miro rule-system board documented (five pager variants).",
5659
+ "ticket": "DS-973"
5660
+ }
5661
+ ]
5662
+ },
5090
5663
  {
5091
5664
  "name": "RouteProgress",
5092
5665
  "import": "@brightlocal/ui-components/route-progress",
@@ -5157,6 +5730,26 @@
5157
5730
  "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
5731
  "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
5732
  }
5733
+ ],
5734
+ "decisions": [
5735
+ {
5736
+ "date": "2026-09-07",
5737
+ "decision": "RouteProgress paints a solid bg-primary bar (dark keeps the light-mode primary), not the loading gradient.",
5738
+ "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.",
5739
+ "ticket": "DS-904"
5740
+ }
5741
+ ],
5742
+ "ruledOut": [
5743
+ {
5744
+ "option": "Folding RouteProgress into Progress as a color=\"gradient\" variant",
5745
+ "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.",
5746
+ "ticket": "DS-904"
5747
+ },
5748
+ {
5749
+ "option": "A determinate Progress fed a consumer-supplied fake number",
5750
+ "why": "It pushes the trickle into every app, cannot do the slow asymptote through value, and announces a fiction through aria-valuenow.",
5751
+ "ticket": "DS-904"
5752
+ }
5160
5753
  ]
5161
5754
  },
5162
5755
  {
@@ -5203,6 +5796,7 @@
5203
5796
  },
5204
5797
  "whenToUse": [
5205
5798
  "A specific box needing its own scroll bar (chat panel, fixed-height list)",
5799
+ "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
5800
  "Dropdown menus or sidebars with long content that shouldn't grow the page",
5207
5801
  "Keeping scrollbar styling consistent with the design system"
5208
5802
  ],
@@ -5460,7 +6054,8 @@
5460
6054
  ],
5461
6055
  "size": [
5462
6056
  "default",
5463
- "sm"
6057
+ "sm",
6058
+ "lg"
5464
6059
  ]
5465
6060
  },
5466
6061
  "props": [
@@ -5606,6 +6201,126 @@
5606
6201
  ]
5607
6202
  }
5608
6203
  },
6204
+ {
6205
+ "name": "SingleSelectFilter",
6206
+ "import": "@brightlocal/ui-components/single-select-filter",
6207
+ "category": "form",
6208
+ "exports": [
6209
+ "SingleSelectFilter"
6210
+ ],
6211
+ "compound": false,
6212
+ "dataHookRequired": true,
6213
+ "variants": {
6214
+ "size": [
6215
+ "default",
6216
+ "sm"
6217
+ ],
6218
+ "presentation": [
6219
+ "menu",
6220
+ "drawer",
6221
+ "auto"
6222
+ ]
6223
+ },
6224
+ "props": [
6225
+ "label",
6226
+ "options",
6227
+ "value",
6228
+ "defaultValue",
6229
+ "onValueChange",
6230
+ "open",
6231
+ "onOpenChange",
6232
+ "icon",
6233
+ "disabled",
6234
+ "presentation",
6235
+ "searchable",
6236
+ "searchThreshold",
6237
+ "searchPlaceholder",
6238
+ "emptyLabel",
6239
+ "emptyDescription"
6240
+ ],
6241
+ "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.",
6242
+ "i18nProps": {
6243
+ "SingleSelectFilter": {
6244
+ "clearLabel": "string — default: \"Clear filters\"",
6245
+ "doneLabel": "string — default: \"Done\" (the drawer's close button)",
6246
+ "drawerDescription": "string — default: \"Pick one option.\" (sr-only drawer description)",
6247
+ "searchPlaceholder": "string — default: \"Search options...\" (drawer search field placeholder and aria-label)",
6248
+ "clearSearchAriaLabel": "string — default: \"Clear search\" (the drawer search clear button)",
6249
+ "emptyLabel": "string — default: \"No options found.\" (no-match heading)",
6250
+ "emptyDescription": "string — default: \"Try another search.\" (no-match description)"
6251
+ }
6252
+ },
6253
+ "whenToUse": [
6254
+ "One value from a dimension in a filter toolbar (time period, interval, source type) — the Filtering pattern's dropdown filter",
6255
+ "A responsive filter that shows a DS Select on desktop and a radio drawer on mobile: presentation='auto' switches at md",
6256
+ "Sitting beside MultiSelectFilter in a filter bar — the trigger look matches exactly"
6257
+ ],
6258
+ "doNotUseFor": [
6259
+ "picking more than one option (use MultiSelectFilter)",
6260
+ "a form field that validates (use Select — SingleSelectFilter has no error state)",
6261
+ "quick filters with 2–5 always-visible options (use ToggleGroup or SegmentedControl)",
6262
+ "a long, searchable single-value list in a form — not a filter (use Combobox)"
6263
+ ],
6264
+ "alternatives": [
6265
+ {
6266
+ "component": "MultiSelectFilter",
6267
+ "rule": "Use MultiSelectFilter for several values from one dimension combining as OR"
6268
+ },
6269
+ {
6270
+ "component": "Select",
6271
+ "rule": "Use Select for a form field that validates — SingleSelectFilter is a filter, not a form field"
6272
+ },
6273
+ {
6274
+ "component": "ToggleGroup",
6275
+ "rule": "Use ToggleGroup for a quick filter with 2–5 always-visible options"
6276
+ },
6277
+ {
6278
+ "component": "Combobox",
6279
+ "rule": "Use Combobox for a long, searchable single-value list in a form — not a filter (SingleSelectFilter has its own drawer search)"
6280
+ }
6281
+ ],
6282
+ "figma": {
6283
+ "fileKey": "p3krmC8DBUgqpbq6cLzaal",
6284
+ "nodes": [
6285
+ {
6286
+ "nodeId": "34438:81566",
6287
+ "figmaName": "Single Select Filter",
6288
+ "kind": "componentSet",
6289
+ "export": "SingleSelectFilter",
6290
+ "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.",
6291
+ "axes": [
6292
+ {
6293
+ "figma": "Size",
6294
+ "code": "size"
6295
+ },
6296
+ {
6297
+ "figma": "State",
6298
+ "exempt": "interaction-state",
6299
+ "valueToProp": {
6300
+ "Disabled": "disabled"
6301
+ },
6302
+ "note": "Focus and Open are runtime states; the CVA has no hover style, so there is no Hover variant"
6303
+ }
6304
+ ]
6305
+ }
6306
+ ]
6307
+ },
6308
+ "decisions": [
6309
+ {
6310
+ "date": "2026-11-02",
6311
+ "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.",
6312
+ "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.",
6313
+ "ticket": "DS-973"
6314
+ }
6315
+ ],
6316
+ "ruledOut": [
6317
+ {
6318
+ "option": "Hiding the filter when the current data leaves it nothing to choose",
6319
+ "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.",
6320
+ "ticket": "DS-973"
6321
+ }
6322
+ ]
6323
+ },
5609
6324
  {
5610
6325
  "name": "Skeleton",
5611
6326
  "import": "@brightlocal/ui-components/skeleton",
@@ -5899,6 +6614,89 @@
5899
6614
  "figmaOnly": []
5900
6615
  }
5901
6616
  },
6617
+ {
6618
+ "name": "Status",
6619
+ "import": "@brightlocal/ui-components/status",
6620
+ "category": "display",
6621
+ "exports": [
6622
+ "Status"
6623
+ ],
6624
+ "compound": false,
6625
+ "dataHookRequired": true,
6626
+ "variants": {
6627
+ "variant": [
6628
+ "success",
6629
+ "warning",
6630
+ "error",
6631
+ "info",
6632
+ "neutral",
6633
+ "loading"
6634
+ ]
6635
+ },
6636
+ "props": [
6637
+ "variant",
6638
+ "dotOnly",
6639
+ "children"
6640
+ ],
6641
+ "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.",
6642
+ "aliases": [
6643
+ "status dot",
6644
+ "status indicator",
6645
+ "state indicator",
6646
+ "connection status",
6647
+ "sync status",
6648
+ "lifecycle state",
6649
+ "presence dot"
6650
+ ],
6651
+ "whenToUse": [
6652
+ "One Status per tracked aspect of a thing (its sync, its listing, its subscription), at the end of the row it describes",
6653
+ "A lifecycle state that can change while the user watches (Syncing → Connected)"
6654
+ ],
6655
+ "doNotUseFor": [
6656
+ "A fact or label about the thing (plan tier, count, \"New\") — use Badge",
6657
+ "A message the user should read or act on — use Alert",
6658
+ "A lone problem on an otherwise healthy row — use an icon, not a dotOnly Status",
6659
+ "The change between two values — use Delta"
6660
+ ],
6661
+ "alternatives": [
6662
+ {
6663
+ "component": "Badge",
6664
+ "rule": "Badge states a fact; Status states where something is in its lifecycle"
6665
+ },
6666
+ {
6667
+ "component": "Alert",
6668
+ "rule": "Alert is a message to read or act on; Status is a one-word state"
6669
+ }
6670
+ ],
6671
+ "a11yContract": {
6672
+ "role": "status",
6673
+ "requiresLabel": false,
6674
+ "keyboardInteraction": [
6675
+ "Tab focuses the dotOnly trigger and opens its tooltip",
6676
+ "Escape closes the tooltip"
6677
+ ]
6678
+ },
6679
+ "decisions": [
6680
+ {
6681
+ "decision": "variant is visual weight only; the word always carries the meaning",
6682
+ "why": "Colour is never the only indicator; the same variant can mean different lifecycle words",
6683
+ "date": "2026-11-02",
6684
+ "ticket": "DS-1235"
6685
+ },
6686
+ {
6687
+ "decision": "Root is role=\"status\" (polite live region)",
6688
+ "why": "Lifecycle states change in place (Syncing → Connected) and the change must be announced",
6689
+ "date": "2026-11-02",
6690
+ "ticket": "DS-1235"
6691
+ },
6692
+ {
6693
+ "decision": "In progress is variant=\"loading\", not a separate boolean",
6694
+ "why": "One axis for every state of the mark, named like Button's loading so the DS speaks one word for in-progress",
6695
+ "date": "2026-11-02",
6696
+ "ticket": "DS-1235"
6697
+ }
6698
+ ]
6699
+ },
5902
6700
  {
5903
6701
  "name": "Stepper",
5904
6702
  "import": "@brightlocal/ui-components/stepper",
@@ -6701,7 +7499,15 @@
6701
7499
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
6702
7500
  "status": "deprecated-in-figma",
6703
7501
  "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
- }
7502
+ },
7503
+ "decisions": [
7504
+ {
7505
+ "date": "2026-09-07",
7506
+ "decision": "TypographyH1–H4, P, Lead, Large, Small, Muted and the rest of the Typography family are deprecated in favour of TypographyHeading / TypographyText.",
7507
+ "why": "Tag and visual size were coupled; the two-axis semantic type scale separates the document outline (level) from the visual role (variant).",
7508
+ "ticket": "DS-714"
7509
+ }
7510
+ ]
6705
7511
  },
6706
7512
  {
6707
7513
  "name": "TypographyHeading",
@@ -6805,6 +7611,14 @@
6805
7611
  "component": "Card",
6806
7612
  "rule": "Inside Card, prefer the CardTitle export so the card owns its title slot"
6807
7613
  }
7614
+ ],
7615
+ "decisions": [
7616
+ {
7617
+ "date": "2026-09-08",
7618
+ "decision": "Titles inside dense surfaces over 14px body text use variant=\"compact\" (text-heading-compact, Inter 14/20, 600).",
7619
+ "why": "text-heading-subsection (16/600) assumes a 16px body; over a 14px body it double-jumps in size and weight and reads oversized.",
7620
+ "ticket": "DS-920"
7621
+ }
6808
7622
  ]
6809
7623
  },
6810
7624
  {
@@ -6930,6 +7744,11 @@
6930
7744
  "EmptyStateAlign": [
6931
7745
  "center",
6932
7746
  "left"
7747
+ ],
7748
+ "EmptyStateIconVariant": [
7749
+ "filled",
7750
+ "border",
7751
+ "transparent"
6933
7752
  ]
6934
7753
  },
6935
7754
  "props": [
@@ -6939,10 +7758,25 @@
6939
7758
  "description",
6940
7759
  "size",
6941
7760
  "align",
7761
+ "iconVariant",
6942
7762
  "titleLevel",
6943
7763
  "className"
6944
7764
  ],
6945
- "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 muted chip 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.)",
7765
+ "decisions": [
7766
+ {
7767
+ "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",
7768
+ "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",
7769
+ "date": "2026-10-30",
7770
+ "ticket": "DS-1208"
7771
+ },
7772
+ {
7773
+ "decision": "iconVariant passes LogoMark's variant through (filled default, border, transparent)",
7774
+ "why": "The filled chip disappears on a bg-muted panel; the surface, not the block, decides the container",
7775
+ "date": "2026-10-30",
7776
+ "ticket": "DS-1208"
7777
+ }
7778
+ ],
7779
+ "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
7780
  "aliases": [
6947
7781
  "empty state",
6948
7782
  "empty block",
@@ -7452,6 +8286,14 @@
7452
8286
  "ticket": "DS-1029",
7453
8287
  "workaround": "Place SidebarMenuSubItem directly inside SidebarMenuCollapsibleContent and pass variant on it; use a standalone SidebarMenuSub only outside a collapsible"
7454
8288
  }
8289
+ ],
8290
+ "decisions": [
8291
+ {
8292
+ "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",
8293
+ "ticket": "DS-1212",
8294
+ "date": "2026-11-02",
8295
+ "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."
8296
+ }
7455
8297
  ]
7456
8298
  }
7457
8299
  ],
@@ -7474,6 +8316,7 @@
7474
8316
  "transitions": "Always specify property (transition-colors, transition-opacity). Never use transition-all.",
7475
8317
  "focus": "Use focus-visible: prefix. Never use bare focus: prefix.",
7476
8318
  "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."
8319
+ "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.",
8320
+ "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
8321
  }
7479
8322
  }