@brightlocal/ui-components 3.1.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 (463) hide show
  1. package/AI_USAGE.md +10 -0
  2. package/README.md +8 -1
  3. package/component-meta.json +1591 -123
  4. package/deprecations.json +45 -1
  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 +36 -5
  10. package/dist/alert-dialog.d.ts.map +1 -1
  11. package/dist/alert-dialog.js +83 -128
  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 +116 -177
  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 +32 -1
  22. package/dist/badge.d.ts.map +1 -1
  23. package/dist/badge.js +90 -71
  24. package/dist/banner.cjs +1 -0
  25. package/dist/banner.d.ts +81 -0
  26. package/dist/banner.d.ts.map +1 -0
  27. package/dist/banner.js +130 -0
  28. package/dist/blocks/empty-state.cjs +1 -1
  29. package/dist/blocks/empty-state.d.ts +24 -6
  30. package/dist/blocks/empty-state.d.ts.map +1 -1
  31. package/dist/blocks/empty-state.js +74 -140
  32. package/dist/blocks/input-list.cjs +2 -2
  33. package/dist/blocks/input-list.d.ts +2 -2
  34. package/dist/blocks/input-list.d.ts.map +1 -1
  35. package/dist/blocks/input-list.js +136 -176
  36. package/dist/blocks/progress-state.cjs +1 -1
  37. package/dist/blocks/progress-state.d.ts +2 -2
  38. package/dist/blocks/progress-state.js +223 -347
  39. package/dist/blocks/sidebar.cjs +1 -1
  40. package/dist/blocks/sidebar.d.ts +28 -6
  41. package/dist/blocks/sidebar.d.ts.map +1 -1
  42. package/dist/blocks/sidebar.js +763 -1086
  43. package/dist/brand-illustration-motif.cjs +1 -1
  44. package/dist/brand-illustration-motif.d.ts +1 -1
  45. package/dist/brand-illustration-motif.js +40 -61
  46. package/dist/breadcrumb.cjs +1 -1
  47. package/dist/breadcrumb.js +62 -102
  48. package/dist/button-group.cjs +1 -1
  49. package/dist/button-group.js +23 -31
  50. package/dist/button.cjs +1 -1
  51. package/dist/button.d.ts +4 -2
  52. package/dist/button.d.ts.map +1 -1
  53. package/dist/button.js +149 -189
  54. package/dist/calendar.cjs +1 -1
  55. package/dist/calendar.d.ts +87 -3
  56. package/dist/calendar.d.ts.map +1 -1
  57. package/dist/calendar.js +116 -173
  58. package/dist/callout.cjs +1 -1
  59. package/dist/callout.js +73 -96
  60. package/dist/card.cjs +1 -1
  61. package/dist/card.d.ts +92 -6
  62. package/dist/card.d.ts.map +1 -1
  63. package/dist/card.js +240 -234
  64. package/dist/carousel.cjs +1 -1
  65. package/dist/carousel.d.ts +3 -3
  66. package/dist/carousel.d.ts.map +1 -1
  67. package/dist/carousel.js +174 -268
  68. package/dist/centred-layout.cjs +1 -1
  69. package/dist/centred-layout.js +27 -48
  70. package/dist/chart-empty.cjs +1 -1
  71. package/dist/chart-empty.js +18 -27
  72. package/dist/chart.cjs +7 -7
  73. package/dist/chart.d.ts +253 -25
  74. package/dist/chart.d.ts.map +1 -1
  75. package/dist/chart.js +465 -511
  76. package/dist/checkbox.cjs +1 -1
  77. package/dist/checkbox.d.ts +1 -1
  78. package/dist/checkbox.d.ts.map +1 -1
  79. package/dist/checkbox.js +37 -69
  80. package/dist/chip.cjs +1 -1
  81. package/dist/chip.js +116 -173
  82. package/dist/collapsible.cjs +1 -1
  83. package/dist/collapsible.d.ts.map +1 -1
  84. package/dist/collapsible.js +35 -41
  85. package/dist/combobox.cjs +3 -3
  86. package/dist/combobox.d.ts +14 -4
  87. package/dist/combobox.d.ts.map +1 -1
  88. package/dist/combobox.js +440 -639
  89. package/dist/command.cjs +1 -1
  90. package/dist/command.d.ts.map +1 -1
  91. package/dist/command.js +273 -420
  92. package/dist/context-menu.cjs +1 -1
  93. package/dist/context-menu.d.ts +5 -5
  94. package/dist/context-menu.d.ts.map +1 -1
  95. package/dist/context-menu.js +121 -191
  96. package/dist/data-table.cjs +1 -1
  97. package/dist/data-table.d.ts +442 -144
  98. package/dist/data-table.d.ts.map +1 -1
  99. package/dist/data-table.js +708 -835
  100. package/dist/date-picker.cjs +1 -1
  101. package/dist/date-picker.d.ts +15 -4
  102. package/dist/date-picker.d.ts.map +1 -1
  103. package/dist/date-picker.js +156 -231
  104. package/dist/delta.cjs +1 -0
  105. package/dist/delta.d.ts +79 -0
  106. package/dist/delta.d.ts.map +1 -0
  107. package/dist/delta.js +62 -0
  108. package/dist/description.cjs +1 -1
  109. package/dist/description.js +11 -20
  110. package/dist/dialog.cjs +1 -1
  111. package/dist/dialog.d.ts +1 -1
  112. package/dist/dialog.d.ts.map +1 -1
  113. package/dist/dialog.js +76 -116
  114. package/dist/drawer.cjs +1 -1
  115. package/dist/drawer.d.ts +11 -11
  116. package/dist/drawer.d.ts.map +1 -1
  117. package/dist/drawer.js +76 -134
  118. package/dist/dropdown-menu.cjs +1 -1
  119. package/dist/dropdown-menu.d.ts +6 -6
  120. package/dist/dropdown-menu.d.ts.map +1 -1
  121. package/dist/dropdown-menu.js +179 -300
  122. package/dist/field.cjs +1 -1
  123. package/dist/field.d.ts +9 -9
  124. package/dist/field.d.ts.map +1 -1
  125. package/dist/field.js +166 -286
  126. package/dist/global-layout.cjs +1 -1
  127. package/dist/global-layout.js +203 -342
  128. package/dist/grid.cjs +1 -1
  129. package/dist/grid.d.ts +24 -1
  130. package/dist/grid.d.ts.map +1 -1
  131. package/dist/grid.js +16 -29
  132. package/dist/header.cjs +1 -1
  133. package/dist/header.js +21 -38
  134. package/dist/height-transition.cjs +1 -1
  135. package/dist/height-transition.js +38 -55
  136. package/dist/hooks/use-breakpoint.cjs +1 -1
  137. package/dist/hooks/use-breakpoint.d.ts +1 -1
  138. package/dist/hooks/use-breakpoint.d.ts.map +1 -1
  139. package/dist/hooks/use-breakpoint.js +10 -9
  140. package/dist/hooks/use-debounce.cjs +1 -1
  141. package/dist/hooks/use-debounce.js +12 -11
  142. package/dist/hooks/use-delayed-pending.cjs +1 -1
  143. package/dist/hooks/use-delayed-pending.js +8 -9
  144. package/dist/hooks/use-filter-search-params.cjs +1 -0
  145. package/dist/hooks/use-filter-search-params.d.ts +93 -0
  146. package/dist/hooks/use-filter-search-params.d.ts.map +1 -0
  147. package/dist/hooks/use-filter-search-params.js +122 -0
  148. package/dist/hooks/use-mobile.cjs +1 -1
  149. package/dist/hooks/use-mobile.js +6 -6
  150. package/dist/hooks/use-overlay-pointer-lock.cjs +1 -1
  151. package/dist/hooks/use-overlay-pointer-lock.js +8 -9
  152. package/dist/hooks/use-prefers-reduced-motion.cjs +1 -1
  153. package/dist/hooks/use-prefers-reduced-motion.js +5 -8
  154. package/dist/hover-card.cjs +1 -1
  155. package/dist/hover-card.d.ts +1 -1
  156. package/dist/hover-card.d.ts.map +1 -1
  157. package/dist/hover-card.js +30 -62
  158. package/dist/index.cjs +1 -1
  159. package/dist/index.d.ts +11 -0
  160. package/dist/index.d.ts.map +1 -1
  161. package/dist/index.js +636 -582
  162. package/dist/info-tooltip.cjs +1 -0
  163. package/dist/info-tooltip.d.ts +39 -0
  164. package/dist/info-tooltip.d.ts.map +1 -0
  165. package/dist/info-tooltip.js +27 -0
  166. package/dist/input-chip.cjs +1 -1
  167. package/dist/input-chip.d.ts +32 -3
  168. package/dist/input-chip.d.ts.map +1 -1
  169. package/dist/input-chip.js +182 -231
  170. package/dist/input-group.cjs +1 -1
  171. package/dist/input-group.d.ts +33 -2
  172. package/dist/input-group.d.ts.map +1 -1
  173. package/dist/input-group.js +188 -122
  174. package/dist/input-otp.cjs +1 -1
  175. package/dist/input-otp.d.ts +3 -3
  176. package/dist/input-otp.d.ts.map +1 -1
  177. package/dist/input-otp.js +102 -146
  178. package/dist/input-password.cjs +1 -1
  179. package/dist/input-password.d.ts +26 -8
  180. package/dist/input-password.d.ts.map +1 -1
  181. package/dist/input-password.js +139 -171
  182. package/dist/input.cjs +1 -1
  183. package/dist/input.d.ts.map +1 -1
  184. package/dist/input.js +51 -73
  185. package/dist/label.cjs +1 -1
  186. package/dist/label.js +20 -38
  187. package/dist/lib/block-illustration.cjs +1 -1
  188. package/dist/lib/block-illustration.d.ts +5 -2
  189. package/dist/lib/block-illustration.d.ts.map +1 -1
  190. package/dist/lib/block-illustration.js +16 -17
  191. package/dist/lib/compose-event-handlers.cjs +1 -0
  192. package/dist/lib/compose-event-handlers.d.ts +9 -0
  193. package/dist/lib/compose-event-handlers.d.ts.map +1 -0
  194. package/dist/lib/compose-event-handlers.js +8 -0
  195. package/dist/lib/download-file.cjs +1 -0
  196. package/dist/lib/download-file.d.ts +14 -0
  197. package/dist/lib/download-file.d.ts.map +1 -0
  198. package/dist/lib/download-file.js +40 -0
  199. package/dist/lib/empty-canvas.cjs +1 -1
  200. package/dist/lib/empty-canvas.js +28 -56
  201. package/dist/lib/empty-chip.cjs +1 -1
  202. package/dist/lib/empty-chip.d.ts +14 -3
  203. package/dist/lib/empty-chip.d.ts.map +1 -1
  204. package/dist/lib/empty-chip.js +15 -11
  205. package/dist/lib/field-aria.cjs +1 -0
  206. package/dist/lib/field-aria.d.ts +34 -0
  207. package/dist/lib/field-aria.d.ts.map +1 -0
  208. package/dist/lib/field-aria.js +52 -0
  209. package/dist/lib/image-file-info.cjs +1 -0
  210. package/dist/lib/image-file-info.d.ts +25 -0
  211. package/dist/lib/image-file-info.d.ts.map +1 -0
  212. package/dist/lib/image-file-info.js +67 -0
  213. package/dist/lib/media-viewer-content.cjs +1 -0
  214. package/dist/lib/media-viewer-content.d.ts +102 -0
  215. package/dist/lib/media-viewer-content.d.ts.map +1 -0
  216. package/dist/lib/media-viewer-content.js +650 -0
  217. package/dist/lib/media-viewer-internal.cjs +1 -0
  218. package/dist/lib/media-viewer-internal.d.ts +98 -0
  219. package/dist/lib/media-viewer-internal.d.ts.map +1 -0
  220. package/dist/lib/media-viewer-internal.js +61 -0
  221. package/dist/lib/media-viewer-motion.cjs +1 -0
  222. package/dist/lib/media-viewer-motion.d.ts +40 -0
  223. package/dist/lib/media-viewer-motion.d.ts.map +1 -0
  224. package/dist/lib/media-viewer-motion.js +37 -0
  225. package/dist/lib/motion.cjs +1 -1
  226. package/dist/lib/motion.d.ts +8 -0
  227. package/dist/lib/motion.d.ts.map +1 -1
  228. package/dist/lib/motion.js +11 -10
  229. package/dist/lib/optical-center.cjs +1 -1
  230. package/dist/lib/optical-center.d.ts +1 -1
  231. package/dist/lib/optical-center.d.ts.map +1 -1
  232. package/dist/lib/optical-center.js +12 -5
  233. package/dist/lib/spring-settle.cjs +1 -1
  234. package/dist/lib/spring-settle.js +1 -1
  235. package/dist/lib/table-internal.cjs +1 -0
  236. package/dist/lib/table-internal.d.ts +62 -0
  237. package/dist/lib/table-internal.d.ts.map +1 -0
  238. package/dist/lib/table-internal.js +18 -0
  239. package/dist/lib/use-controllable.cjs +1 -0
  240. package/dist/lib/use-controllable.d.ts +12 -0
  241. package/dist/lib/use-controllable.d.ts.map +1 -0
  242. package/dist/lib/use-controllable.js +15 -0
  243. package/dist/lib/use-dev-warning.cjs +1 -1
  244. package/dist/lib/utils.cjs +1 -1
  245. package/dist/lib/utils.d.ts.map +1 -1
  246. package/dist/lib/utils.js +29 -35
  247. package/dist/link.cjs +1 -1
  248. package/dist/link.d.ts +1 -1
  249. package/dist/link.js +78 -124
  250. package/dist/list.cjs +1 -1
  251. package/dist/list.d.ts +8 -0
  252. package/dist/list.d.ts.map +1 -1
  253. package/dist/list.js +94 -156
  254. package/dist/loading.cjs +1 -1
  255. package/dist/loading.js +124 -151
  256. package/dist/logo-mark.cjs +1 -0
  257. package/dist/logo-mark.d.ts +79 -0
  258. package/dist/logo-mark.d.ts.map +1 -0
  259. package/dist/logo-mark.js +219 -0
  260. package/dist/logo.cjs +1 -1
  261. package/dist/logo.d.ts +1 -1
  262. package/dist/logo.d.ts.map +1 -1
  263. package/dist/logo.js +51 -87
  264. package/dist/map.cjs +1 -1
  265. package/dist/map.d.ts.map +1 -1
  266. package/dist/map.js +390 -586
  267. package/dist/media-empty.cjs +1 -1
  268. package/dist/media-empty.js +27 -42
  269. package/dist/media-viewer.cjs +1 -0
  270. package/dist/media-viewer.d.ts +224 -0
  271. package/dist/media-viewer.d.ts.map +1 -0
  272. package/dist/media-viewer.js +295 -0
  273. package/dist/menubar.cjs +1 -1
  274. package/dist/menubar.d.ts +14 -14
  275. package/dist/menubar.d.ts.map +1 -1
  276. package/dist/menubar.js +130 -267
  277. package/dist/multi-select-filter.cjs +1 -0
  278. package/dist/multi-select-filter.d.ts +186 -0
  279. package/dist/multi-select-filter.d.ts.map +1 -0
  280. package/dist/multi-select-filter.js +374 -0
  281. package/dist/navigation-menu.cjs +1 -1
  282. package/dist/navigation-menu.js +108 -172
  283. package/dist/pagination.cjs +1 -1
  284. package/dist/pagination.d.ts +36 -12
  285. package/dist/pagination.d.ts.map +1 -1
  286. package/dist/pagination.js +208 -281
  287. package/dist/popover.cjs +1 -1
  288. package/dist/popover.d.ts +1 -1
  289. package/dist/popover.d.ts.map +1 -1
  290. package/dist/popover.js +34 -45
  291. package/dist/progress.cjs +1 -1
  292. package/dist/progress.d.ts +139 -17
  293. package/dist/progress.d.ts.map +1 -1
  294. package/dist/progress.js +116 -148
  295. package/dist/radio-group.cjs +1 -1
  296. package/dist/radio-group.js +90 -146
  297. package/dist/rating.cjs +1 -1
  298. package/dist/rating.d.ts +80 -13
  299. package/dist/rating.d.ts.map +1 -1
  300. package/dist/rating.js +70 -65
  301. package/dist/relative-date.cjs +1 -0
  302. package/dist/relative-date.d.ts +65 -0
  303. package/dist/relative-date.d.ts.map +1 -0
  304. package/dist/relative-date.js +112 -0
  305. package/dist/resizable.cjs +1 -1
  306. package/dist/resizable.d.ts +39 -23
  307. package/dist/resizable.d.ts.map +1 -1
  308. package/dist/resizable.js +42 -44
  309. package/dist/result-count.cjs +1 -0
  310. package/dist/result-count.d.ts +110 -0
  311. package/dist/result-count.d.ts.map +1 -0
  312. package/dist/result-count.js +49 -0
  313. package/dist/route-progress.cjs +1 -1
  314. package/dist/route-progress.js +58 -102
  315. package/dist/scroll-area.cjs +1 -1
  316. package/dist/scroll-area.d.ts +9 -1
  317. package/dist/scroll-area.d.ts.map +1 -1
  318. package/dist/scroll-area.js +44 -79
  319. package/dist/select.cjs +2 -2
  320. package/dist/select.d.ts +20 -10
  321. package/dist/select.d.ts.map +1 -1
  322. package/dist/select.js +132 -236
  323. package/dist/separator.cjs +1 -1
  324. package/dist/separator.js +90 -78
  325. package/dist/sheet.cjs +1 -1
  326. package/dist/sheet.d.ts +86 -7
  327. package/dist/sheet.d.ts.map +1 -1
  328. package/dist/sheet.js +275 -235
  329. package/dist/single-select-filter.cjs +1 -0
  330. package/dist/single-select-filter.d.ts +113 -0
  331. package/dist/single-select-filter.d.ts.map +1 -0
  332. package/dist/single-select-filter.js +224 -0
  333. package/dist/skeleton.cjs +1 -1
  334. package/dist/skeleton.js +24 -38
  335. package/dist/slider.cjs +1 -1
  336. package/dist/slider.js +51 -81
  337. package/dist/sonner.cjs +1 -1
  338. package/dist/sonner.d.ts +1 -1
  339. package/dist/sonner.d.ts.map +1 -1
  340. package/dist/sonner.js +113 -137
  341. package/dist/spinner.cjs +1 -1
  342. package/dist/spinner.js +22 -31
  343. package/dist/split-layout.cjs +1 -1
  344. package/dist/split-layout.d.ts +1 -1
  345. package/dist/split-layout.js +53 -102
  346. package/dist/status.cjs +1 -0
  347. package/dist/status.d.ts +51 -0
  348. package/dist/status.d.ts.map +1 -0
  349. package/dist/status.js +60 -0
  350. package/dist/stepper.cjs +1 -1
  351. package/dist/stepper.js +184 -316
  352. package/dist/switch.cjs +1 -1
  353. package/dist/switch.js +17 -32
  354. package/dist/table.cjs +1 -1
  355. package/dist/table.d.ts +127 -13
  356. package/dist/table.d.ts.map +1 -1
  357. package/dist/table.js +170 -192
  358. package/dist/tabs.cjs +1 -1
  359. package/dist/tabs.d.ts +12 -1
  360. package/dist/tabs.d.ts.map +1 -1
  361. package/dist/tabs.js +123 -146
  362. package/dist/text-reveal-motion.cjs +1 -1
  363. package/dist/text-reveal-motion.js +307 -363
  364. package/dist/textarea.cjs +1 -1
  365. package/dist/textarea.d.ts.map +1 -1
  366. package/dist/textarea.js +23 -36
  367. package/dist/toggle-group.cjs +1 -1
  368. package/dist/toggle-group.js +43 -62
  369. package/dist/toggle.cjs +1 -1
  370. package/dist/toggle.js +34 -46
  371. package/dist/tooltip.cjs +1 -1
  372. package/dist/tooltip.d.ts +38 -36
  373. package/dist/tooltip.d.ts.map +1 -1
  374. package/dist/tooltip.js +175 -78
  375. package/dist/typography-heading.cjs +1 -1
  376. package/dist/typography-heading.js +25 -61
  377. package/dist/typography-text.cjs +1 -1
  378. package/dist/typography-text.d.ts +1 -2
  379. package/dist/typography-text.d.ts.map +1 -1
  380. package/dist/typography-text.js +27 -57
  381. package/dist/typography.cjs +1 -1
  382. package/dist/typography.d.ts +1 -1
  383. package/dist/typography.js +132 -340
  384. package/package.json +45 -46
  385. package/src/blocks/empty-state.tsx +42 -21
  386. package/src/blocks/progress-state.tsx +2 -2
  387. package/src/blocks/sidebar.tsx +111 -32
  388. package/src/components/accordion.tsx +1 -1
  389. package/src/components/alert-dialog.tsx +52 -5
  390. package/src/components/alert.tsx +16 -8
  391. package/src/components/badge.tsx +152 -3
  392. package/src/components/banner.tsx +288 -0
  393. package/src/components/brand-illustration-motif.tsx +1 -1
  394. package/src/components/breadcrumb.tsx +1 -1
  395. package/src/components/button.tsx +8 -6
  396. package/src/components/calendar.tsx +155 -9
  397. package/src/components/card.tsx +266 -26
  398. package/src/components/carousel.tsx +4 -1
  399. package/src/components/chart.tsx +664 -42
  400. package/src/components/checkbox.tsx +2 -2
  401. package/src/components/collapsible.tsx +4 -1
  402. package/src/components/combobox.tsx +42 -9
  403. package/src/components/command.tsx +10 -11
  404. package/src/components/context-menu.tsx +4 -4
  405. package/src/components/data-table.tsx +1363 -398
  406. package/src/components/date-picker.tsx +31 -4
  407. package/src/components/delta.tsx +217 -0
  408. package/src/components/drawer.tsx +5 -5
  409. package/src/components/dropdown-menu.tsx +4 -4
  410. package/src/components/field.tsx +36 -15
  411. package/src/components/global-layout.tsx +1 -1
  412. package/src/components/grid.tsx +32 -1
  413. package/src/components/info-tooltip.tsx +94 -0
  414. package/src/components/input-chip.tsx +52 -8
  415. package/src/components/input-group.tsx +247 -12
  416. package/src/components/input-otp.tsx +1 -1
  417. package/src/components/input-password.tsx +29 -11
  418. package/src/components/input.tsx +11 -2
  419. package/src/components/list.tsx +15 -3
  420. package/src/components/logo-mark.tsx +345 -0
  421. package/src/components/map.tsx +18 -20
  422. package/src/components/media-viewer.tsx +908 -0
  423. package/src/components/multi-select-filter.tsx +1046 -0
  424. package/src/components/navigation-menu.tsx +2 -2
  425. package/src/components/pagination.tsx +86 -26
  426. package/src/components/progress.tsx +281 -54
  427. package/src/components/rating.tsx +200 -74
  428. package/src/components/relative-date.tsx +238 -0
  429. package/src/components/resizable.tsx +86 -33
  430. package/src/components/result-count.tsx +253 -0
  431. package/src/components/scroll-area.tsx +31 -5
  432. package/src/components/select.tsx +37 -7
  433. package/src/components/sheet.tsx +252 -6
  434. package/src/components/single-select-filter.tsx +538 -0
  435. package/src/components/slider.tsx +2 -2
  436. package/src/components/sonner.tsx +16 -5
  437. package/src/components/split-layout.tsx +2 -2
  438. package/src/components/status.tsx +162 -0
  439. package/src/components/switch.tsx +1 -1
  440. package/src/components/table.tsx +305 -73
  441. package/src/components/tabs.tsx +94 -46
  442. package/src/components/textarea.tsx +21 -3
  443. package/src/components/toggle.tsx +2 -2
  444. package/src/components/tooltip.tsx +431 -68
  445. package/src/components/typography-text.tsx +1 -2
  446. package/src/components/typography.tsx +1 -1
  447. package/src/hooks/use-breakpoint.ts +2 -1
  448. package/src/hooks/use-filter-search-params.ts +302 -0
  449. package/src/index.ts +11 -0
  450. package/src/lib/block-illustration.tsx +5 -1
  451. package/src/lib/compose-event-handlers.ts +14 -0
  452. package/src/lib/download-file.ts +61 -0
  453. package/src/lib/empty-chip.tsx +52 -0
  454. package/src/lib/field-aria.tsx +97 -0
  455. package/src/lib/image-file-info.ts +102 -0
  456. package/src/lib/media-viewer-content.tsx +1587 -0
  457. package/src/lib/media-viewer-internal.tsx +191 -0
  458. package/src/lib/media-viewer-motion.ts +120 -0
  459. package/src/lib/motion.ts +9 -0
  460. package/src/lib/table-internal.ts +74 -0
  461. package/src/lib/use-controllable.ts +43 -0
  462. package/src/lib/utils.ts +1 -0
  463. package/src/lib/empty-chip.ts +0 -24
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brightlocal/ui-components",
3
- "version": "3.1.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)"
@@ -200,11 +201,25 @@
200
201
  ],
201
202
  "compound": true,
202
203
  "dataHookRequired": true,
203
- "variants": {},
204
+ "variants": {
205
+ "variant": [
206
+ "primary",
207
+ "secondary",
208
+ "destructive"
209
+ ]
210
+ },
204
211
  "props": [
205
212
  "open",
206
213
  "onOpenChange"
207
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
+ ],
208
223
  "description": "Modal confirmation dialogs",
209
224
  "aliases": [
210
225
  "confirmation dialog",
@@ -214,7 +229,8 @@
214
229
  "whenToUse": [
215
230
  "Confirming irreversible actions (permanent delete of an account or location)",
216
231
  "Serious consequences needing an explicit confirm-or-cancel choice",
217
- "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)"
218
234
  ],
219
235
  "doNotUseFor": [
220
236
  "easily undoable actions (use Sonner with an Undo action)",
@@ -255,6 +271,12 @@
255
271
  "export": "AlertDialog",
256
272
  "note": "Draws the assembled dialog; all sub-parts are drawn inside",
257
273
  "axes": [
274
+ {
275
+ "figma": "Variant",
276
+ "code": "variant",
277
+ "export": "AlertDialogAction",
278
+ "note": "Prop lives on AlertDialogAction; the set swaps the confirm Button instance to Primary/Destructive (DS-818)"
279
+ },
258
280
  {
259
281
  "figma": "Breakpoint",
260
282
  "exempt": "figma-only-style",
@@ -290,7 +312,7 @@
290
312
  },
291
313
  {
292
314
  "export": "AlertDialogAction",
293
- "reason": "Drawn inside the set as a Button instance"
315
+ "reason": "Drawn inside the set as a Button instance; its variant prop is the set's Variant axis"
294
316
  },
295
317
  {
296
318
  "export": "AlertDialogCancel",
@@ -423,26 +445,32 @@
423
445
  "primary",
424
446
  "secondary",
425
447
  "destructive",
426
- "outline"
448
+ "outline",
449
+ "highlight-gold"
427
450
  ]
428
451
  },
429
452
  "props": [
430
- "asChild"
453
+ "asChild",
454
+ "srLabel",
455
+ "iconOnly",
456
+ "truncate",
457
+ "maxWidth"
431
458
  ],
432
459
  "description": "Status badges and labels",
433
460
  "aliases": [
434
461
  "tag",
435
462
  "chip",
436
463
  "pill",
437
- "label",
438
- "status indicator"
464
+ "label"
439
465
  ],
440
466
  "whenToUse": [
441
467
  "Status labels like \"New,\" \"Active,\" \"Draft,\" or \"Error\"",
442
468
  "Numeric counts on icons or navigation items",
443
- "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"
444
471
  ],
445
472
  "doNotUseFor": [
473
+ "highlight-gold as a caution or status — gold is not a warning (use Alert's Warning)",
446
474
  "removable tags or filter values (use Chip)",
447
475
  "neutral or positive statuses styled as Destructive",
448
476
  "page-level cautions rather than failures (use Alert's Warning variant)"
@@ -488,8 +516,68 @@
488
516
  ],
489
517
  "unmappedExports": [],
490
518
  "figmaOnly": []
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
+ ],
534
+ "i18nProps": {
535
+ "Badge": {
536
+ "srLabel": "string — no default; screen-reader phrase replacing a bare numeral (\"3 active\"); ignored with asChild"
537
+ }
491
538
  }
492
539
  },
540
+ {
541
+ "name": "Banner",
542
+ "import": "@brightlocal/ui-components/banner",
543
+ "category": "feedback",
544
+ "exports": [
545
+ "Banner",
546
+ "BannerIllustration",
547
+ "BannerContent",
548
+ "BannerTitle",
549
+ "BannerDescription",
550
+ "BannerActions"
551
+ ],
552
+ "compound": true,
553
+ "dataHookRequired": true,
554
+ "variants": {
555
+ "variant": [
556
+ "sky",
557
+ "violet"
558
+ ]
559
+ },
560
+ "props": [
561
+ "variant",
562
+ "onDismiss",
563
+ "dismissLabel"
564
+ ],
565
+ "description": "Branded, dismissible invitation to an optional step — composed from BannerIllustration, BannerContent (BannerTitle, BannerDescription) and BannerActions on a highlight sky/violet surface",
566
+ "i18nProps": {
567
+ "Banner": {
568
+ "dismissLabel": "string — default: \"Dismiss\""
569
+ }
570
+ },
571
+ "whenToUse": [
572
+ "Inviting the user to an optional step that improves the page (connect an account, turn on two-factor authentication)",
573
+ "A one-off, dismissible nudge tied to the current page"
574
+ ],
575
+ "doNotUseFor": [
576
+ "something that happened — a failure, a risk, a tip (use Alert)",
577
+ "brand statements or pull-quotes (use Callout)",
578
+ "feedback after an action (use a toast / Sonner)"
579
+ ]
580
+ },
493
581
  {
494
582
  "name": "BrandIllustrationMotif",
495
583
  "import": "@brightlocal/ui-components/brand-illustration-motif",
@@ -650,8 +738,7 @@
650
738
  "destructive",
651
739
  "outline",
652
740
  "secondary",
653
- "ghost",
654
- "warning"
741
+ "ghost"
655
742
  ],
656
743
  "size": [
657
744
  "default",
@@ -667,6 +754,14 @@
667
754
  "type",
668
755
  "ariaLabel"
669
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
+ ],
670
765
  "description": "Primary interactive button with variants",
671
766
  "aliases": [
672
767
  "btn",
@@ -679,7 +774,7 @@
679
774
  "Triggering an action (submit, save, delete, open)",
680
775
  "The single most important action on a screen or dialog (Primary)",
681
776
  "Supporting or low-emphasis actions (Secondary, Outline, Ghost)",
682
- "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)"
683
778
  ],
684
779
  "doNotUseFor": [
685
780
  "navigation to another page (use Link)",
@@ -788,7 +883,7 @@
788
883
  ],
789
884
  "doNotUseFor": [
790
885
  "on/off or single-choice selection (use ToggleGroup — it owns the selected state and keyboard model)",
791
- "quick filters over a collection (use the Lab SegmentedControl)",
886
+ "quick filters over a collection (use ToggleGroup, or Tabs variant=\"underline\" for a promoted tab row)",
792
887
  "attaching icons or buttons to a text input (use InputGroup)"
793
888
  ],
794
889
  "states": [
@@ -808,18 +903,25 @@
808
903
  "import": "@brightlocal/ui-components/calendar",
809
904
  "category": "form",
810
905
  "exports": [
811
- "Calendar"
906
+ "Calendar",
907
+ "CalendarPresets"
812
908
  ],
813
- "compound": false,
909
+ "compound": true,
814
910
  "dataHookRequired": true,
815
911
  "variants": {},
816
912
  "props": [
817
913
  "numberOfMonths",
914
+ "fullWidth",
818
915
  "mode",
819
916
  "selected",
820
917
  "onSelect",
821
918
  "disabled"
822
919
  ],
920
+ "i18nProps": {
921
+ "CalendarPresets": {
922
+ "groupLabel": "string — default: \"Quick picks\"; accessible name of the presets group"
923
+ }
924
+ },
823
925
  "description": "Date selection calendar (wraps react-day-picker)",
824
926
  "figma": {
825
927
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
@@ -838,7 +940,12 @@
838
940
  ]
839
941
  }
840
942
  ],
841
- "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
+ ],
842
949
  "figmaOnly": [
843
950
  {
844
951
  "nodeId": "234:196",
@@ -921,7 +1028,9 @@
921
1028
  "CardTitle",
922
1029
  "CardAction",
923
1030
  "CardDescription",
1031
+ "CardToolbar",
924
1032
  "CardMedia",
1033
+ "CardMetric",
925
1034
  "CardContent"
926
1035
  ],
927
1036
  "compound": true,
@@ -935,7 +1044,8 @@
935
1044
  ],
936
1045
  "density": [
937
1046
  "default",
938
- "condensed"
1047
+ "condensed",
1048
+ "data"
939
1049
  ],
940
1050
  "align": [
941
1051
  "left",
@@ -946,7 +1056,7 @@
946
1056
  "props": [
947
1057
  "maxWidth"
948
1058
  ],
949
- "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. 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.",
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.",
950
1060
  "aliases": [
951
1061
  "container",
952
1062
  "panel",
@@ -958,7 +1068,8 @@
958
1068
  "Putting a box around related content (form section, detail panel, stat summary)",
959
1069
  "Dashboard widgets or sections separated from the page background",
960
1070
  "Grouping content without a visible boundary (Transparent variant)",
961
- "Full-bleed edge-to-edge media (Transparent Flush variant)"
1071
+ "Full-bleed edge-to-edge media (Transparent Flush variant)",
1072
+ "Report-page cards with filter rows, header metrics and edge-to-edge data views (density='data', CardToolbar, CardMetric, CardContent flush)"
962
1073
  ],
963
1074
  "knownGaps": [],
964
1075
  "doNotUseFor": [
@@ -1046,6 +1157,14 @@
1046
1157
  {
1047
1158
  "export": "CardAction",
1048
1159
  "reason": "No Figma representation found (2026-08-13) — candidate designer task at rollout"
1160
+ },
1161
+ {
1162
+ "export": "CardToolbar",
1163
+ "reason": "Drawn as the 'Toolbar Slot' SLOT property on the Card set in the DS-989 Figma branch (gQkQkqVsqDRzJpkbMHR5S7); map via /figma-map Card after the branch merges (FIG-28)"
1164
+ },
1165
+ {
1166
+ "export": "CardMetric",
1167
+ "reason": "Drawn as the 'Card Metric' component on the DS-989 Figma branch; map via /figma-map Card after the branch merges (FIG-28)"
1049
1168
  }
1050
1169
  ],
1051
1170
  "figmaOnly": [
@@ -1060,7 +1179,27 @@
1060
1179
  "reason": "Figma demo helper"
1061
1180
  }
1062
1181
  ]
1063
- }
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
+ ]
1064
1203
  },
1065
1204
  {
1066
1205
  "name": "Carousel",
@@ -1261,6 +1400,8 @@
1261
1400
  "ChartTooltipContent",
1262
1401
  "ChartLegend",
1263
1402
  "ChartLegendContent",
1403
+ "ChartLegendList",
1404
+ "ChartLegendItem",
1264
1405
  "ChartStyle",
1265
1406
  "ChartDot",
1266
1407
  "ChartDotOnStroke",
@@ -1273,15 +1414,53 @@
1273
1414
  ],
1274
1415
  "compound": true,
1275
1416
  "dataHookRequired": true,
1276
- "variants": {},
1417
+ "variants": {
1418
+ "orientation": [
1419
+ "horizontal",
1420
+ "vertical"
1421
+ ],
1422
+ "size": [
1423
+ "sm",
1424
+ "md"
1425
+ ]
1426
+ },
1277
1427
  "props": [
1278
1428
  "config",
1279
- "id"
1429
+ "id",
1430
+ "width",
1431
+ "height",
1432
+ "minWidth",
1433
+ "minHeight",
1434
+ "maxHeight"
1280
1435
  ],
1281
1436
  "hooks": [
1282
1437
  "useChart"
1283
1438
  ],
1284
- "description": "Data visualization wrapper for Recharts",
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
+ ],
1448
+ "i18nProps": {
1449
+ "ChartLegendList": {
1450
+ "ariaLabel": "string — default: \"Chart legend\""
1451
+ },
1452
+ "ChartLegendContent": {
1453
+ "ariaLabel": "string — default: \"Chart legend\""
1454
+ }
1455
+ },
1456
+ "aliases": [
1457
+ "chart legend",
1458
+ "chart key",
1459
+ "vertical legend",
1460
+ "legend beside chart",
1461
+ "interactive legend",
1462
+ "legend with values"
1463
+ ],
1285
1464
  "figma": {
1286
1465
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
1287
1466
  "status": "code-only",
@@ -1291,7 +1470,8 @@
1291
1470
  "Trends over time (Line), or trends emphasizing total volume underneath (Area)",
1292
1471
  "Comparing a few categories or rankings (Bar)",
1293
1472
  "Part-of-whole proportions with 5 or fewer categories (Pie)",
1294
- "Multi-measure profiles of one or two items (Radar), or a single percentage/progress value as a circular tile (Radial Bar)"
1473
+ "Multi-measure profiles of one or two items (Radar), or a single percentage/progress value as a circular tile (Radial Bar)",
1474
+ "A legend beside the plot or shared by several charts: ChartLegendList + ChartLegendItem (orientation=\"vertical\" with values; asChild makes an item a popover trigger or an aria-pressed toggle)"
1295
1475
  ],
1296
1476
  "doNotUseFor": [
1297
1477
  "exact values users must read precisely (pair with or use Table/DataTable)",
@@ -1340,7 +1520,8 @@
1340
1520
  "import": "@brightlocal/ui-components/checkbox",
1341
1521
  "category": "form",
1342
1522
  "exports": [
1343
- "Checkbox"
1523
+ "Checkbox",
1524
+ "checkboxVariants"
1344
1525
  ],
1345
1526
  "compound": false,
1346
1527
  "dataHookRequired": true,
@@ -1361,7 +1542,7 @@
1361
1542
  "turning a system feature or state on or off (use Switch)",
1362
1543
  "single-choice selection from a list (use RadioGroup)",
1363
1544
  "pressed-button toolbar controls (use Toggle)",
1364
- "more than ~7 options (use the faceted multi-select from the Filtering pattern)"
1545
+ "more than ~7 options (use MultiSelectFilter)"
1365
1546
  ],
1366
1547
  "replaces": [
1367
1548
  "native <input type='checkbox'>"
@@ -1388,6 +1569,11 @@
1388
1569
  "kind": "componentSet",
1389
1570
  "export": "Checkbox",
1390
1571
  "axes": [
1572
+ {
1573
+ "figma": "Variant",
1574
+ "exempt": "figma-only-style",
1575
+ "note": "Simple|Box draws the Field variant=\"box\" composition (DS-572/DS-576) — `box` is a Field prop, not a Checkbox prop"
1576
+ },
1391
1577
  {
1392
1578
  "figma": "Status",
1393
1579
  "exempt": "interaction-state",
@@ -1408,7 +1594,12 @@
1408
1594
  ]
1409
1595
  }
1410
1596
  ],
1411
- "unmappedExports": [],
1597
+ "unmappedExports": [
1598
+ {
1599
+ "export": "checkboxVariants",
1600
+ "reason": "cva style helper (the Checkbox look for presentational check marks, e.g. MultiSelectFilter's option rows), not a component"
1601
+ }
1602
+ ],
1412
1603
  "figmaOnly": []
1413
1604
  },
1414
1605
  "whenToUse": [
@@ -1586,7 +1777,7 @@
1586
1777
  "short lists under 10 items (use Select)",
1587
1778
  "free-text values not on the list (use InputChip)",
1588
1779
  "options that should all be visible for comparison (use RadioGroup or ToggleGroup)",
1589
- "picking several values at once — Combobox is single-value by design (use the faceted multi-select from the Filtering pattern)"
1780
+ "picking several values at once — Combobox is single-value by design (use MultiSelectFilter)"
1590
1781
  ],
1591
1782
  "alternatives": [
1592
1783
  {
@@ -2034,6 +2225,8 @@
2034
2225
  "getRowClassName",
2035
2226
  "renderExpandedContent",
2036
2227
  "isLoading",
2228
+ "refetching",
2229
+ "refetchingLabel",
2037
2230
  "skeletonRowCount",
2038
2231
  "noResultsMessage",
2039
2232
  "layout",
@@ -2046,7 +2239,8 @@
2046
2239
  "i18nProps": {
2047
2240
  "DataTable": {
2048
2241
  "scrollRegionLabel": "string — default: \"Scrollable table\"",
2049
- "noResultsMessage": "string — default: \"No results.\""
2242
+ "noResultsMessage": "string — default: \"No results.\"",
2243
+ "refetchingLabel": "string — default: \"Loading results…\""
2050
2244
  },
2051
2245
  "DataTableColumnHeader": {
2052
2246
  "getSortLabel": "(title: string, direction: \"asc\" | \"desc\" | false) => string"
@@ -2061,10 +2255,16 @@
2061
2255
  },
2062
2256
  "DataTablePagination": {
2063
2257
  "ariaLabel": "string — default: \"Table pagination\"",
2064
- "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"
2065
2262
  },
2066
2263
  "DataTablePaginationRowCount": {
2067
- "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"
2068
2268
  },
2069
2269
  "DataTableSelectAllCheckbox": {
2070
2270
  "selectAllAriaLabel": "string — default: \"Select all\""
@@ -2083,7 +2283,7 @@
2083
2283
  "children": "React.ReactNode | ((info: { selectedCount: number; totalCount: number }) => React.ReactNode) — default: \"{selectedCount} of {totalCount} row(s) selected.\""
2084
2284
  }
2085
2285
  },
2086
- "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.",
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).",
2087
2287
  "figma": {
2088
2288
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
2089
2289
  "status": "code-only",
@@ -2099,6 +2299,51 @@
2099
2299
  "simple read-only data with no sorting/filtering (use Table)",
2100
2300
  "1,000+ rows with the standard renderer (use VirtualizedDataTable)",
2101
2301
  "simple visual lists of items with icons and actions (use List)"
2302
+ ],
2303
+ "knownGaps": [
2304
+ {
2305
+ "description": "A height bound set through className without stickyHeader scrolls vertically but is not keyboard-focusable — the component cannot inspect className, so the focusable scroll-region semantics are gated on stickyHeader (or minWidth)",
2306
+ "ticket": "DS-912",
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"
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
+ }
2102
2347
  ]
2103
2348
  },
2104
2349
  {
@@ -2131,7 +2376,7 @@
2131
2376
  ],
2132
2377
  "i18nProps": {
2133
2378
  "DatePickerTrigger": {
2134
- "triggerLabel": "string — default: \"Pick a date\""
2379
+ "triggerLabel": "string — default: \"Select date\" / \"Select date range\"; the visible value is appended (\"<label>: <value>\")"
2135
2380
  },
2136
2381
  "DatePickerContent": {
2137
2382
  "contentLabel": "string — default: \"Date picker\""
@@ -2212,6 +2457,86 @@
2212
2457
  "fixed predefined ranges only (plain preset buttons are faster)"
2213
2458
  ]
2214
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
+ },
2215
2540
  {
2216
2541
  "name": "Description",
2217
2542
  "import": "@brightlocal/ui-components/description",
@@ -2727,7 +3052,15 @@
2727
3052
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
2728
3053
  "status": "represented-inline",
2729
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."
2730
- }
3055
+ },
3056
+ "decisions": [
3057
+ {
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"
3062
+ }
3063
+ ]
2731
3064
  },
2732
3065
  {
2733
3066
  "name": "GlobalLayout",
@@ -2892,6 +3225,13 @@
2892
3225
  "a whole standalone page like login or invite (use CentredLayout — it owns the viewport)",
2893
3226
  "a section's empty frame (an md EmptyState fills the frame it is given, no centring wrapper)",
2894
3227
  "a layout the vocabulary lacks (request a new variant in the DS, never a className at the call site)"
3228
+ ],
3229
+ "knownGaps": [
3230
+ {
3231
+ "description": "variant=\"centered\" needs an unbroken flex chain: it stretches with flex-1, so a non-flex wrapper between the page body and the Grid collapses it to its content height — the 38/62 spacers shrink to zero and the message is centred horizontally only (it hugs the top of the body). Nothing warns about it.",
3232
+ "ticket": "DS-1058",
3233
+ "workaround": "Make every wrapper between the page body and the Grid a flex column that fills it (className=\"flex flex-1 flex-col\"), or render the Grid directly inside GlobalLayoutBody. Never compensate with a top margin (mt-*)."
3234
+ }
2895
3235
  ]
2896
3236
  },
2897
3237
  {
@@ -3044,6 +3384,66 @@
3044
3384
  "single short lines of text (use Tooltip)"
3045
3385
  ]
3046
3386
  },
3387
+ {
3388
+ "name": "InfoTooltip",
3389
+ "import": "@brightlocal/ui-components/info-tooltip",
3390
+ "category": "feedback",
3391
+ "exports": [
3392
+ "InfoTooltip"
3393
+ ],
3394
+ "compound": false,
3395
+ "dataHookRequired": true,
3396
+ "variants": {},
3397
+ "props": [
3398
+ "content",
3399
+ "icon",
3400
+ "iconSize",
3401
+ "ariaLabel",
3402
+ "trackingEl",
3403
+ "trackingLabel"
3404
+ ],
3405
+ "description": "Muted info icon that opens a tooltip (hover/tap/focus) — the standard pattern for inline hints next to labels. Composes the Tooltip component.",
3406
+ "aliases": [
3407
+ "info icon",
3408
+ "help icon",
3409
+ "hint tooltip",
3410
+ "info tooltip",
3411
+ "muted tooltip trigger"
3412
+ ],
3413
+ "whenToUse": [
3414
+ "A small info/help icon next to a label that explains what it means",
3415
+ "Inline clarifications that should not take up permanent space"
3416
+ ],
3417
+ "doNotUseFor": [
3418
+ "Clickable tooltip content — use Popover",
3419
+ "Content longer than a sentence or two — use HoverCard or Popover",
3420
+ "A button or interactive control as trigger — use Tooltip directly with asChild"
3421
+ ],
3422
+ "i18nProps": {
3423
+ "InfoTooltip": {
3424
+ "ariaLabel": "string — default: \"More info\""
3425
+ }
3426
+ },
3427
+ "figma": {
3428
+ "fileKey": "p3krmC8DBUgqpbq6cLzaal",
3429
+ "nodes": [
3430
+ {
3431
+ "nodeId": "34112:2577",
3432
+ "figmaName": "Info Tooltip",
3433
+ "kind": "componentSet",
3434
+ "export": "InfoTooltip",
3435
+ "axes": [
3436
+ {
3437
+ "figma": "State",
3438
+ "exempt": "interaction-state"
3439
+ }
3440
+ ]
3441
+ }
3442
+ ],
3443
+ "unmappedExports": [],
3444
+ "figmaOnly": []
3445
+ }
3446
+ },
3047
3447
  {
3048
3448
  "name": "Input",
3049
3449
  "import": "@brightlocal/ui-components/input",
@@ -3145,7 +3545,8 @@
3145
3545
  "defaultValue",
3146
3546
  "disabled",
3147
3547
  "allowDuplicates",
3148
- "error"
3548
+ "error",
3549
+ "onBeforeAdd"
3149
3550
  ],
3150
3551
  "i18nProps": {
3151
3552
  "InputChipItems": {
@@ -3195,6 +3596,20 @@
3195
3596
  "choosing from an existing list (use Combobox)",
3196
3597
  "displaying already-chosen tags with no typing (use Chip)",
3197
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
+ }
3198
3613
  ]
3199
3614
  },
3200
3615
  {
@@ -3205,7 +3620,8 @@
3205
3620
  "InputGroup",
3206
3621
  "InputGroupInput",
3207
3622
  "InputGroupAddon",
3208
- "InputGroupButton"
3623
+ "InputGroupButton",
3624
+ "InputGroupClear"
3209
3625
  ],
3210
3626
  "compound": true,
3211
3627
  "dataHookRequired": true,
@@ -3219,7 +3635,7 @@
3219
3635
  "props": [
3220
3636
  "error"
3221
3637
  ],
3222
- "description": "Input with addon text or button",
3638
+ "description": "Input with addon text or button, and an opt-in built-in clear X",
3223
3639
  "figma": {
3224
3640
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
3225
3641
  "status": "represented-inline",
@@ -3227,6 +3643,7 @@
3227
3643
  },
3228
3644
  "whenToUse": [
3229
3645
  "A text box with something extra attached (search icon, clear button, unit prefix)",
3646
+ "Search fields needing the Filtering pattern’s in-field clear X — add InputGroupClear, no hand-wiring",
3230
3647
  "Attachments that should feel like part of the same control, not a separate element",
3231
3648
  "Ghost variant for search fields in toolbars or dense filter bars where a border feels heavy"
3232
3649
  ],
@@ -3234,7 +3651,12 @@
3234
3651
  "inputs with nothing attached (use Input)",
3235
3652
  "password visibility toggle with strength meter (use InputPassword)",
3236
3653
  "ghost variant on plain backgrounds with no surrounding context (can look non-interactive)"
3237
- ]
3654
+ ],
3655
+ "i18nProps": {
3656
+ "InputGroupClear": {
3657
+ "clearSearchAriaLabel": "string — default: \"Clear search\""
3658
+ }
3659
+ }
3238
3660
  },
3239
3661
  {
3240
3662
  "name": "InputOTP",
@@ -3525,6 +3947,10 @@
3525
3947
  "filled",
3526
3948
  "outline",
3527
3949
  "loading"
3950
+ ],
3951
+ "align": [
3952
+ "center",
3953
+ "start"
3528
3954
  ]
3529
3955
  },
3530
3956
  "props": [],
@@ -3659,33 +4085,169 @@
3659
4085
  ]
3660
4086
  },
3661
4087
  {
3662
- "name": "Map",
3663
- "import": "@brightlocal/ui-components/map",
4088
+ "name": "LogoMark",
4089
+ "import": "@brightlocal/ui-components/logo-mark",
3664
4090
  "category": "display",
3665
4091
  "exports": [
3666
- "MAP_STYLES",
3667
- "MapTypeId",
3668
- "MapLocationPin",
3669
- "MapGridPin",
3670
- "MapClusterPin",
3671
- "mapGridPinColorMap",
3672
- "clusterPinHexColors",
3673
- "resolveClusterPinColors",
3674
- "createClusterPinSvg",
3675
- "createClusterPinElement",
3676
- "MapControlButton",
3677
- "MapLoadingState",
3678
- "MapErrorState",
3679
- "MapEmpty",
3680
- "MapLegend",
3681
- "MapLegendItem",
3682
- "MapPopover",
3683
- "MapPopoverAnchor",
3684
- "MapPopoverContent",
3685
- "useMapStyles",
3686
- "useMapPopoverClick"
4092
+ "LogoMark",
4093
+ "SOURCE_ICON_ALIASES"
3687
4094
  ],
3688
- "compound": true,
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",
4192
+ "kind": "componentSet",
4193
+ "export": "LogoMark",
4194
+ "axes": [
4195
+ {
4196
+ "figma": "Variant",
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"
4211
+ }
4212
+ ]
4213
+ }
4214
+ ],
4215
+ "unmappedExports": [
4216
+ {
4217
+ "export": "SOURCE_ICON_ALIASES",
4218
+ "reason": "Constant (Record<string, string>) — not a component, no Figma representation"
4219
+ }
4220
+ ]
4221
+ }
4222
+ },
4223
+ {
4224
+ "name": "Map",
4225
+ "import": "@brightlocal/ui-components/map",
4226
+ "category": "display",
4227
+ "exports": [
4228
+ "MAP_STYLES",
4229
+ "MapTypeId",
4230
+ "MapLocationPin",
4231
+ "MapGridPin",
4232
+ "MapClusterPin",
4233
+ "mapGridPinColorMap",
4234
+ "clusterPinHexColors",
4235
+ "resolveClusterPinColors",
4236
+ "createClusterPinSvg",
4237
+ "createClusterPinElement",
4238
+ "MapControlButton",
4239
+ "MapLoadingState",
4240
+ "MapErrorState",
4241
+ "MapEmpty",
4242
+ "MapLegend",
4243
+ "MapLegendItem",
4244
+ "MapPopover",
4245
+ "MapPopoverAnchor",
4246
+ "MapPopoverContent",
4247
+ "useMapStyles",
4248
+ "useMapPopoverClick"
4249
+ ],
4250
+ "compound": true,
3689
4251
  "dataHookRequired": true,
3690
4252
  "variants": {
3691
4253
  "MapStyleVariant": [
@@ -3831,6 +4393,162 @@
3831
4393
  }
3832
4394
  }
3833
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
+ },
3834
4552
  {
3835
4553
  "name": "Menubar",
3836
4554
  "import": "@brightlocal/ui-components/menubar",
@@ -3961,6 +4679,201 @@
3961
4679
  "primary app navigation (use NavigationMenu or Sidebar)"
3962
4680
  ]
3963
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
+ }
4875
+ ]
4876
+ },
3964
4877
  {
3965
4878
  "name": "NavigationMenu",
3966
4879
  "import": "@brightlocal/ui-components/navigation-menu",
@@ -4096,7 +5009,10 @@
4096
5009
  "nextAriaLabel": "string — default: \"Go to next page\"",
4097
5010
  "pageAriaLabel": "string — default: \"Go to page {page}\"",
4098
5011
  "ellipsisSrLabel": "string — default: \"More pages\"",
4099
- "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"
4100
5016
  },
4101
5017
  "PaginationPrevious": {
4102
5018
  "ariaLabel": "string — default: \"Go to previous page\""
@@ -4176,6 +5092,14 @@
4176
5092
  "lists inside a Data Table (use its built-in pagination)",
4177
5093
  "continuously loading content (use infinite scroll)",
4178
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
+ }
4179
5103
  ]
4180
5104
  },
4181
5105
  {
@@ -4277,6 +5201,10 @@
4277
5201
  "size": [
4278
5202
  "sm",
4279
5203
  "md"
5204
+ ],
5205
+ "labelPlacement": [
5206
+ "inline",
5207
+ "above"
4280
5208
  ]
4281
5209
  },
4282
5210
  "props": [
@@ -4284,17 +5212,22 @@
4284
5212
  "max",
4285
5213
  "color",
4286
5214
  "size",
5215
+ "labelPlacement",
4287
5216
  "showValue",
4288
5217
  "unit",
5218
+ "valueFormatter",
4289
5219
  "ariaLabel",
4290
5220
  "label",
4291
- "statusDescription",
4292
- "indeterminate",
4293
5221
  "labelWidth",
4294
5222
  "indicatorClassName",
4295
5223
  "disabled"
4296
5224
  ],
4297
- "description": "Progress bar indicator with optional inline label, numeric value, 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",
5226
+ "i18nProps": {
5227
+ "Progress": {
5228
+ "ariaLabel": "string — default: \"Progress\" (required when `label` is an element)"
5229
+ }
5230
+ },
4298
5231
  "figma": {
4299
5232
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
4300
5233
  "nodes": [
@@ -4303,7 +5236,7 @@
4303
5236
  "figmaName": "Progress",
4304
5237
  "kind": "componentSet",
4305
5238
  "export": "Progress",
4306
- "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.",
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.",
4307
5240
  "axes": [
4308
5241
  {
4309
5242
  "figma": "Colour",
@@ -4334,6 +5267,32 @@
4334
5267
  "stalled or failed tasks (use Alert for the failure)",
4335
5268
  "unknown waits with no real percentage (Skeleton covers initial content loading)",
4336
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
+ }
4337
5296
  ]
4338
5297
  },
4339
5298
  {
@@ -4416,63 +5375,183 @@
4416
5375
  "Icon-led visual choices (box icon variants)"
4417
5376
  ],
4418
5377
  "doNotUseFor": [
4419
- "multiple selection (use Checkbox or ToggleGroup)",
4420
- "more than a handful of options (use Select or Combobox)"
5378
+ "multiple selection (use Checkbox or ToggleGroup)",
5379
+ "more than a handful of options (use Select or Combobox)"
5380
+ ]
5381
+ },
5382
+ {
5383
+ "name": "Rating",
5384
+ "import": "@brightlocal/ui-components/rating",
5385
+ "category": "display",
5386
+ "exports": [
5387
+ "Rating"
5388
+ ],
5389
+ "compound": false,
5390
+ "dataHookRequired": true,
5391
+ "variants": {
5392
+ "variant": [
5393
+ "stars",
5394
+ "recommendation"
5395
+ ],
5396
+ "size": [
5397
+ "sm",
5398
+ "md"
5399
+ ]
5400
+ },
5401
+ "props": [
5402
+ "value"
5403
+ ],
5404
+ "description": "Review score display: a 0–5 star value (0.5 increments) or Facebook's Recommended / Not recommended verdict",
5405
+ "i18nProps": {
5406
+ "Rating": {
5407
+ "ariaLabel": "string — default: \"Rating: {value} out of 5 stars\" (stars)",
5408
+ "recommendedLabel": "string — default: \"Recommended\" (recommendation)",
5409
+ "notRecommendedLabel": "string — default: \"Not recommended\" (recommendation)"
5410
+ }
5411
+ },
5412
+ "figma": {
5413
+ "fileKey": "p3krmC8DBUgqpbq6cLzaal",
5414
+ "nodes": [
5415
+ {
5416
+ "nodeId": "22262:19688",
5417
+ "figmaName": "Rating",
5418
+ "kind": "componentSet",
5419
+ "export": "Rating",
5420
+ "axes": [
5421
+ {
5422
+ "figma": "Variant",
5423
+ "code": "variant"
5424
+ },
5425
+ {
5426
+ "figma": "Rating",
5427
+ "exempt": "figma-only-style",
5428
+ "note": "Discrete value demos — 1.0–5.0 for Stars (value is continuous in code), Recommended / Not recommended for Recommendation (code: recommended boolean)"
5429
+ },
5430
+ {
5431
+ "figma": "Size",
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"
5438
+ }
5439
+ ]
5440
+ }
5441
+ ],
5442
+ "unmappedExports": [],
5443
+ "figmaOnly": []
5444
+ },
5445
+ "whenToUse": [
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\")",
5448
+ "Visualizing quality or satisfaction where the star convention is expected",
5449
+ "Summarizing aggregate customer feedback at a glance"
5450
+ ],
5451
+ "doNotUseFor": [
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)"
4421
5455
  ]
4422
5456
  },
4423
5457
  {
4424
- "name": "Rating",
4425
- "import": "@brightlocal/ui-components/rating",
5458
+ "name": "RelativeDate",
5459
+ "import": "@brightlocal/ui-components/relative-date",
4426
5460
  "category": "display",
4427
5461
  "exports": [
4428
- "Rating"
5462
+ "RelativeDate",
5463
+ "useNow",
5464
+ "relativeWords",
5465
+ "exactText",
5466
+ "isDateOnly",
5467
+ "toDate",
5468
+ "dateLabel",
5469
+ "DEFAULT_RELATIVE_DATE_LABELS"
4429
5470
  ],
4430
5471
  "compound": false,
4431
5472
  "dataHookRequired": true,
4432
5473
  "variants": {},
4433
5474
  "props": [
4434
- "value"
5475
+ "value",
5476
+ "label",
5477
+ "labels",
5478
+ "className"
5479
+ ],
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.",
5481
+ "aliases": [
5482
+ "last updated",
5483
+ "time ago",
5484
+ "timestamp",
5485
+ "freshness",
5486
+ "relative time",
5487
+ "date ago"
5488
+ ],
5489
+ "whenToUse": [
5490
+ "Report page headers showing how fresh the data is (\"Last updated 1 hour ago\")",
5491
+ "Any line where users need a glanceable sense of how recent something is",
5492
+ "Calendar dates where the reader cares about recency, not the date itself (\"today\", \"yesterday\", \"3 days ago\")"
5493
+ ],
5494
+ "doNotUseFor": [
5495
+ "Picking or entering a date (use DatePicker)",
5496
+ "Displaying a fixed, absolute date that does not need relative context",
5497
+ "Countdown timers or future dates"
4435
5498
  ],
4436
- "description": "Star rating display (0–5, 0.5 increments)",
4437
5499
  "i18nProps": {
4438
- "Rating": {
4439
- "ariaLabel": "string — default: \"Rating: {value} out of 5 stars\""
5500
+ "RelativeDate": {
5501
+ "labels.justNow": "string — default: \"just now\"",
5502
+ "labels.minuteAgo": "string — default: \"1 minute ago\"",
5503
+ "labels.minutesAgo": "string — default: \"{n} minutes ago\"",
5504
+ "labels.hourAgo": "string — default: \"1 hour ago\"",
5505
+ "labels.hoursAgo": "string — default: \"{n} hours ago\"",
5506
+ "labels.today": "string — default: \"today\"",
5507
+ "labels.yesterday": "string — default: \"yesterday\"",
5508
+ "labels.daysAgo": "string — default: \"{n} days ago\"",
5509
+ "labels.unknown": "string — default: \"unknown\""
4440
5510
  }
4441
5511
  },
4442
5512
  "figma": {
4443
5513
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
4444
5514
  "nodes": [
4445
5515
  {
4446
- "nodeId": "22262:19688",
4447
- "figmaName": "Rating",
5516
+ "nodeId": "34279:1059",
5517
+ "figmaName": "Relative Date",
4448
5518
  "kind": "componentSet",
4449
- "export": "Rating",
4450
- "axes": [
4451
- {
4452
- "figma": "Rating",
4453
- "exempt": "figma-only-style",
4454
- "note": "Discrete value-prop demos (1.0–5.0) — value is continuous in code"
4455
- },
4456
- {
4457
- "figma": "Size",
4458
- "exempt": "figma-only-style",
4459
- "note": "No size variant in code"
4460
- }
4461
- ]
5519
+ "export": "RelativeDate",
5520
+ "axes": []
5521
+ }
5522
+ ],
5523
+ "unmappedExports": [
5524
+ {
5525
+ "export": "useNow",
5526
+ "reason": "Hook — no Figma representation"
5527
+ },
5528
+ {
5529
+ "export": "relativeWords",
5530
+ "reason": "Utility function — no Figma representation"
5531
+ },
5532
+ {
5533
+ "export": "exactText",
5534
+ "reason": "Utility function — no Figma representation"
5535
+ },
5536
+ {
5537
+ "export": "isDateOnly",
5538
+ "reason": "Utility function — no Figma representation"
5539
+ },
5540
+ {
5541
+ "export": "toDate",
5542
+ "reason": "Utility function — no Figma representation"
5543
+ },
5544
+ {
5545
+ "export": "dateLabel",
5546
+ "reason": "Utility function — no Figma representation"
5547
+ },
5548
+ {
5549
+ "export": "DEFAULT_RELATIVE_DATE_LABELS",
5550
+ "reason": "Default labels constant — no Figma representation"
4462
5551
  }
4463
5552
  ],
4464
- "unmappedExports": [],
4465
5553
  "figmaOnly": []
4466
- },
4467
- "whenToUse": [
4468
- "Showing a star-based score, like 4.5 out of 5, on a review, listing, or summary card",
4469
- "Visualizing quality or satisfaction where the star convention is expected",
4470
- "Summarizing aggregate customer feedback at a glance"
4471
- ],
4472
- "doNotUseFor": [
4473
- "collecting a rating from the user (display-only, no input)",
4474
- "non-star scores or counts (use plain text or Badge)"
4475
- ]
5554
+ }
4476
5555
  },
4477
5556
  {
4478
5557
  "name": "Resizable",
@@ -4509,6 +5588,78 @@
4509
5588
  "small/mobile screens where drag-resize is impractical (use a fixed stacked layout)"
4510
5589
  ]
4511
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
+ },
4512
5663
  {
4513
5664
  "name": "RouteProgress",
4514
5665
  "import": "@brightlocal/ui-components/route-progress",
@@ -4579,6 +5730,26 @@
4579
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",
4580
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."
4581
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
+ }
4582
5753
  ]
4583
5754
  },
4584
5755
  {
@@ -4625,6 +5796,7 @@
4625
5796
  },
4626
5797
  "whenToUse": [
4627
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",
4628
5800
  "Dropdown menus or sidebars with long content that shouldn't grow the page",
4629
5801
  "Keeping scrollbar styling consistent with the design system"
4630
5802
  ],
@@ -4659,7 +5831,8 @@
4659
5831
  "onClose",
4660
5832
  "disabled",
4661
5833
  "error",
4662
- "hint"
5834
+ "hint",
5835
+ "reserveValues"
4663
5836
  ],
4664
5837
  "description": "Dropdown select input",
4665
5838
  "aliases": [
@@ -4669,8 +5842,9 @@
4669
5842
  ],
4670
5843
  "doNotUseFor": [
4671
5844
  "long or searchable lists (use Combobox)",
4672
- "picking more than one option (use the faceted multi-select from the Filtering pattern)",
4673
- "showing every option at once (use RadioGroup)"
5845
+ "picking more than one option (use MultiSelectFilter)",
5846
+ "showing every option at once (use RadioGroup)",
5847
+ "a single-value filter in a toolbar (use SingleSelectFilter — it wraps Select on desktop and adds a radio drawer on mobile)"
4674
5848
  ],
4675
5849
  "replaces": [
4676
5850
  "native <select>"
@@ -4862,6 +6036,7 @@
4862
6036
  "SheetClose",
4863
6037
  "SheetOverlay",
4864
6038
  "SheetContent",
6039
+ "SheetPagination",
4865
6040
  "SheetHeader",
4866
6041
  "SheetBody",
4867
6042
  "SheetFooter",
@@ -4879,7 +6054,8 @@
4879
6054
  ],
4880
6055
  "size": [
4881
6056
  "default",
4882
- "sm"
6057
+ "sm",
6058
+ "lg"
4883
6059
  ]
4884
6060
  },
4885
6061
  "props": [
@@ -4889,6 +6065,12 @@
4889
6065
  "i18nProps": {
4890
6066
  "SheetContent": {
4891
6067
  "closeLabel": "string — default: \"Close\""
6068
+ },
6069
+ "SheetPagination": {
6070
+ "ariaLabel": "string — default: \"Item navigation\"",
6071
+ "prevAriaLabel": "string — default: \"Previous item\"",
6072
+ "nextAriaLabel": "string — default: \"Next item\"",
6073
+ "renderPosition": "(info) => ReactNode — default: \"{current} of {total}\""
4892
6074
  }
4893
6075
  },
4894
6076
  "description": "Side panel overlay",
@@ -4932,7 +6114,9 @@
4932
6114
  "requiresLabel": true,
4933
6115
  "keyboardInteraction": [
4934
6116
  "Escape",
4935
- "Tab"
6117
+ "Tab",
6118
+ "ArrowUp/ArrowLeft (SheetPagination: previous item)",
6119
+ "ArrowDown/ArrowRight (SheetPagination: next item)"
4936
6120
  ]
4937
6121
  },
4938
6122
  "figma": {
@@ -4978,6 +6162,10 @@
4978
6162
  "export": "SheetContent",
4979
6163
  "reason": "Drawn by the Sheet set (the panel); its side variant is declared on the set's Position axis"
4980
6164
  },
6165
+ {
6166
+ "export": "SheetPagination",
6167
+ "reason": "Drawn as the SheetPagination component on Figma branch b5xlDa4Z8KpgCwho15fOcM (DS-1035); map with /figma-map after the branch merges"
6168
+ },
4981
6169
  {
4982
6170
  "export": "SheetHeader",
4983
6171
  "reason": "Drawn inside the set ('Show Header' toggle)"
@@ -5013,6 +6201,126 @@
5013
6201
  ]
5014
6202
  }
5015
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
+ },
5016
6324
  {
5017
6325
  "name": "Skeleton",
5018
6326
  "import": "@brightlocal/ui-components/skeleton",
@@ -5306,6 +6614,89 @@
5306
6614
  "figmaOnly": []
5307
6615
  }
5308
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
+ },
5309
6700
  {
5310
6701
  "name": "Stepper",
5311
6702
  "import": "@brightlocal/ui-components/stepper",
@@ -5484,6 +6875,10 @@
5484
6875
  "layout": [
5485
6876
  "auto",
5486
6877
  "fixed"
6878
+ ],
6879
+ "scrollOwner": [
6880
+ "self",
6881
+ "parent"
5487
6882
  ]
5488
6883
  },
5489
6884
  "props": [
@@ -5492,7 +6887,8 @@
5492
6887
  "trackingLabel",
5493
6888
  "layout",
5494
6889
  "minWidth",
5495
- "scrollRegionLabel"
6890
+ "scrollRegionLabel",
6891
+ "scrollOwner"
5496
6892
  ],
5497
6893
  "i18nProps": {
5498
6894
  "Table": {
@@ -5510,7 +6906,7 @@
5510
6906
  "workaround": "Use DataTableColumnHeader from DataTable for sortable headers"
5511
6907
  }
5512
6908
  ],
5513
- "description": "Semantic HTML table with accessibility features. Text alignment is physical (left/right/center). Set layout=\"fixed\" with width on TableHead for stable columns.",
6909
+ "description": "Semantic HTML table with accessibility features. Text alignment is physical (left/right/center). Set layout=\"fixed\" with width on TableHead for stable columns. scrollOwner=\"parent\" keeps the table-container wrapper in the DOM as a plain positioned block but strips its scroll behavior, so a scrolling ancestor owns both axes (how DataTable renders it); default \"self\" makes the wrapper the horizontal scroll container.",
5514
6910
  "aliases": [
5515
6911
  "data grid",
5516
6912
  "grid",
@@ -5653,8 +7049,14 @@
5653
7049
  ],
5654
7050
  "compound": true,
5655
7051
  "dataHookRequired": true,
5656
- "variants": {},
7052
+ "variants": {
7053
+ "variant": [
7054
+ "default",
7055
+ "underline"
7056
+ ]
7057
+ },
5657
7058
  "props": [
7059
+ "variant",
5658
7060
  "value",
5659
7061
  "defaultValue",
5660
7062
  "onValueChange",
@@ -5665,7 +7067,10 @@
5665
7067
  "aliases": [
5666
7068
  "tab bar",
5667
7069
  "tab group",
5668
- "tabbed interface"
7070
+ "tabbed interface",
7071
+ "underline tabs",
7072
+ "promoted tab row",
7073
+ "promoted filter tabs"
5669
7074
  ],
5670
7075
  "doNotUseFor": [
5671
7076
  "sections that must be completed in order (use Stepper)",
@@ -5688,18 +7093,30 @@
5688
7093
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
5689
7094
  "nodes": [
5690
7095
  {
5691
- "nodeId": "183:539",
7096
+ "nodeId": "34619:82902",
5692
7097
  "figmaName": "Tabs",
5693
- "kind": "component",
7098
+ "kind": "componentSet",
5694
7099
  "export": "Tabs",
5695
- "note": "Figma node is a demo composition"
7100
+ "note": "Rebuilt on Figma branch task/DS-946-tab-variant (DS-946); the set draws the TabsList row with four Tabs / Trigger instances",
7101
+ "axes": [
7102
+ {
7103
+ "figma": "Variant",
7104
+ "code": "variant"
7105
+ }
7106
+ ]
5696
7107
  },
5697
7108
  {
5698
- "nodeId": "183:532",
7109
+ "nodeId": "34619:82769",
5699
7110
  "figmaName": "Tabs / Trigger",
5700
7111
  "kind": "componentSet",
5701
7112
  "export": "TabsTrigger",
7113
+ "note": "Rebuilt on Figma branch task/DS-946-tab-variant (DS-946)",
5702
7114
  "axes": [
7115
+ {
7116
+ "figma": "Variant",
7117
+ "code": "variant",
7118
+ "note": "Inherited from the Tabs root via context; the trigger has no variant prop of its own"
7119
+ },
5703
7120
  {
5704
7121
  "figma": "Active",
5705
7122
  "exempt": "interaction-state",
@@ -5718,7 +7135,7 @@
5718
7135
  "unmappedExports": [
5719
7136
  {
5720
7137
  "export": "TabsList",
5721
- "reason": "Drawn implicitly as the trigger row in the Tabs demo node"
7138
+ "reason": "Drawn as the Tabs component set itself (Variant=Default pill list / Variant=Underline bordered row)"
5722
7139
  },
5723
7140
  {
5724
7141
  "export": "TabsContent",
@@ -5965,7 +7382,7 @@
5965
7382
  "align",
5966
7383
  "sideOffset"
5967
7384
  ],
5968
- "description": "Hover tooltip with configurable positioning",
7385
+ "description": "Toggletip: hover on desktop, tap to toggle on touch (stays open for copying text), dismiss via click-outside or Escape",
5969
7386
  "aliases": [
5970
7387
  "hover tip",
5971
7388
  "info tip",
@@ -5973,8 +7390,7 @@
5973
7390
  ],
5974
7391
  "doNotUseFor": [
5975
7392
  "clickable content like links or buttons (use Popover)",
5976
- "content longer than a sentence (use HoverCard or Popover)",
5977
- "critical info for touch-only users (hover has no touch equivalent)"
7393
+ "content longer than a sentence (use HoverCard or Popover)"
5978
7394
  ],
5979
7395
  "replaces": [
5980
7396
  "title attribute"
@@ -6083,7 +7499,15 @@
6083
7499
  "fileKey": "p3krmC8DBUgqpbq6cLzaal",
6084
7500
  "status": "deprecated-in-figma",
6085
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)."
6086
- }
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
+ ]
6087
7511
  },
6088
7512
  {
6089
7513
  "name": "TypographyHeading",
@@ -6187,6 +7611,14 @@
6187
7611
  "component": "Card",
6188
7612
  "rule": "Inside Card, prefer the CardTitle export so the card owns its title slot"
6189
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
+ }
6190
7622
  ]
6191
7623
  },
6192
7624
  {
@@ -6312,6 +7744,11 @@
6312
7744
  "EmptyStateAlign": [
6313
7745
  "center",
6314
7746
  "left"
7747
+ ],
7748
+ "EmptyStateIconVariant": [
7749
+ "filled",
7750
+ "border",
7751
+ "transparent"
6315
7752
  ]
6316
7753
  },
6317
7754
  "props": [
@@ -6321,10 +7758,25 @@
6321
7758
  "description",
6322
7759
  "size",
6323
7760
  "align",
7761
+ "iconVariant",
6324
7762
  "titleLevel",
6325
7763
  "className"
6326
7764
  ],
6327
- "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.)",
6328
7780
  "aliases": [
6329
7781
  "empty state",
6330
7782
  "empty block",
@@ -6827,6 +8279,21 @@
6827
8279
  "doNotUseFor": [
6828
8280
  "simple, shallow navigation (a plain nav list may be simpler)",
6829
8281
  "small screens with a permanently visible sidebar (prefer Offcanvas over None)"
8282
+ ],
8283
+ "knownGaps": [
8284
+ {
8285
+ "description": "SidebarMenuCollapsibleContent already renders the SidebarMenuSub list; nesting another SidebarMenuSub inside it stacks both indents and leaves ~100px for labels at the default 288px width, so sub-items wrap",
8286
+ "ticket": "DS-1029",
8287
+ "workaround": "Place SidebarMenuSubItem directly inside SidebarMenuCollapsibleContent and pass variant on it; use a standalone SidebarMenuSub only outside a collapsible"
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
+ }
6830
8297
  ]
6831
8298
  }
6832
8299
  ],
@@ -6849,6 +8316,7 @@
6849
8316
  "transitions": "Always specify property (transition-colors, transition-opacity). Never use transition-all.",
6850
8317
  "focus": "Use focus-visible: prefix. Never use bare focus: prefix.",
6851
8318
  "icons": "@brightlocal/icons package. Default 16px, no size/strokeWidth override needed.",
6852
- "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."
6853
8321
  }
6854
8322
  }