@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
@@ -2,6 +2,8 @@
2
2
 
3
3
  import * as React from "react";
4
4
  import * as RechartsPrimitive from "recharts";
5
+ import { Slot, Slottable } from "@radix-ui/react-slot";
6
+ import { cva } from "class-variance-authority";
5
7
  import { cn } from "@brightlocal/ui-components/lib/utils";
6
8
 
7
9
  // ============================================================================
@@ -22,7 +24,15 @@ type ChartContextProps = {
22
24
  config: ChartConfig;
23
25
  };
24
26
 
25
- const ChartContext = React.createContext<ChartContextProps | null>(null);
27
+ /** What the context carries — the public props plus internal provenance. */
28
+ type ChartContextValue = ChartContextProps & {
29
+ /** True when the config comes from a `ChartLegendList` rather than a `ChartContainer` — no `ChartStyle` variables exist there. */
30
+ standalone?: boolean;
31
+ /** Ref to the ChartContainer root element, used by ChartTooltip for touch dismiss. */
32
+ containerRef?: React.RefObject<HTMLDivElement | null>;
33
+ };
34
+
35
+ const ChartContext = React.createContext<ChartContextValue | null>(null);
26
36
 
27
37
  function useChart() {
28
38
  const context = React.useContext(ChartContext);
@@ -34,6 +44,15 @@ function useChart() {
34
44
  return context;
35
45
  }
36
46
 
47
+ /**
48
+ * The chart config when rendered inside a `ChartContainer` (or a
49
+ * `ChartLegendList` given a `config`), otherwise `null`. Lets legend parts
50
+ * render beside a chart as well as inside one.
51
+ */
52
+ function useChartOptional() {
53
+ return React.useContext(ChartContext);
54
+ }
55
+
37
56
  // ============================================================================
38
57
  // Chart Container
39
58
  // ============================================================================
@@ -114,17 +133,29 @@ const ChartContainer = React.forwardRef<HTMLDivElement, ChartContainerProps>(
114
133
  trackingLabel,
115
134
  ...props
116
135
  },
117
- ref
136
+ forwardedRef
118
137
  ) => {
119
138
  const uniqueId = React.useId();
120
139
  const chartId = `chart-${id || uniqueId.replace(/:/g, "")}`;
140
+ const containerRef = React.useRef<HTMLDivElement>(null);
141
+ const composedRef = React.useCallback(
142
+ (node: HTMLDivElement | null) => {
143
+ containerRef.current = node;
144
+ if (typeof forwardedRef === "function") forwardedRef(node);
145
+ else if (forwardedRef) forwardedRef.current = node;
146
+ },
147
+ [forwardedRef]
148
+ );
149
+
150
+ const hasFixedHeight = typeof height === "number";
121
151
 
122
152
  return (
123
- <ChartContext.Provider value={{ config }}>
153
+ <ChartContext.Provider value={{ config, containerRef }}>
124
154
  <div
125
- ref={ref}
155
+ ref={composedRef}
126
156
  className={cn(
127
- "[&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground [&_.recharts-polar-radius-axis-tick-value]:fill-foreground [&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border/50 [&_.recharts-curve.recharts-tooltip-cursor]:stroke-border [&_.recharts-polar-grid_[stroke='#ccc']]:stroke-border [&_.recharts-radial-bar-background-sector]:fill-muted [&_.recharts-rectangle.recharts-tooltip-cursor]:fill-muted [&_.recharts-reference-line_[stroke='#ccc']]:stroke-border [&_.recharts-pie-sector]:stroke-background text-body-xs flex aspect-video justify-center [&_.recharts-dot[stroke='#fff']]:stroke-transparent [&_.recharts-layer]:outline-none [&_.recharts-pie-sector]:stroke-2 [&_.recharts-sector]:outline-none [&_.recharts-surface]:outline-none [&_svg_g]:outline-none [&_svg_g]:focus:outline-none",
157
+ "[&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground [&_.recharts-polar-radius-axis-tick-value]:fill-foreground [&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border/50 [&_.recharts-curve.recharts-tooltip-cursor]:stroke-border [&_.recharts-polar-grid_[stroke='#ccc']]:stroke-border [&_.recharts-radial-bar-background-sector]:fill-muted [&_.recharts-rectangle.recharts-tooltip-cursor]:fill-muted [&_.recharts-reference-line_[stroke='#ccc']]:stroke-border [&_.recharts-pie-sector]:stroke-background text-body-xs flex justify-center [&_.recharts-dot[stroke='#fff']]:stroke-transparent [&_.recharts-layer]:outline-none [&_.recharts-pie-sector]:stroke-2 [&_.recharts-sector]:outline-none [&_.recharts-surface]:outline-none [&_svg_g]:outline-none [&_svg_g]:focus:outline-none",
158
+ hasFixedHeight ? "aspect-auto" : "aspect-video",
128
159
  className
129
160
  )}
130
161
  data-chart={chartId}
@@ -132,6 +163,7 @@ const ChartContainer = React.forwardRef<HTMLDivElement, ChartContainerProps>(
132
163
  data-slot="chart-container"
133
164
  data-tracking-el={trackingEl}
134
165
  data-tracking-label={trackingLabel}
166
+ style={hasFixedHeight ? { height } : undefined}
135
167
  {...props}
136
168
  >
137
169
  <ChartStyle config={config} id={chartId} />
@@ -239,6 +271,11 @@ function isRenderableValue(
239
271
 
240
272
  /**
241
273
  * Props for the ChartTooltip component.
274
+ *
275
+ * Inherits all Recharts Tooltip props. Notable defaults changed by the DS:
276
+ * - `portal` — renders to `document.body`; pass `null` for inline (Recharts default)
277
+ * - `allowEscapeViewBox` — `{ x: true, y: true }` so the tooltip is never clipped
278
+ * - `wrapperStyle` — includes `zIndex: 50`; consumer values are merged on top
242
279
  */
243
280
  interface ChartTooltipProps extends React.ComponentProps<
244
281
  typeof RechartsPrimitive.Tooltip
@@ -255,11 +292,120 @@ interface ChartTooltipProps extends React.ComponentProps<
255
292
  labelKey?: string;
256
293
  }
257
294
 
295
+ const TOOLTIP_Z_INDEX = 50;
296
+
258
297
  /**
259
- * ChartTooltip displays data values on hover.
298
+ * Creates and manages a body-appended div for portalling the chart tooltip
299
+ * outside the chart container, so it is never clipped by overflow or
300
+ * stacking-context boundaries.
260
301
  */
261
- function ChartTooltip({ ...props }: ChartTooltipProps) {
262
- return <RechartsPrimitive.Tooltip {...props} />;
302
+ function useChartTooltipPortal(enabled: boolean): HTMLDivElement | null {
303
+ const [portalEl, setPortalEl] = React.useState<HTMLDivElement | null>(null);
304
+
305
+ /* eslint-disable react-hooks/set-state-in-effect -- portal div must be created in an effect (DOM side-effect) and stored in state so the component re-renders with it */
306
+ React.useEffect(() => {
307
+ if (!enabled) {
308
+ setPortalEl(null);
309
+ return;
310
+ }
311
+ const div = document.createElement("div");
312
+ div.setAttribute("data-slot", "chart-tooltip-portal");
313
+ document.body.appendChild(div);
314
+ setPortalEl(div);
315
+ return () => {
316
+ document.body.removeChild(div);
317
+ };
318
+ }, [enabled]);
319
+ /* eslint-enable react-hooks/set-state-in-effect */
320
+
321
+ return portalEl;
322
+ }
323
+
324
+ /**
325
+ * Dismisses the chart tooltip on touch-outside and scroll. On touch devices
326
+ * Recharts keeps the tooltip visible after a tap (no pointerleave fires), so
327
+ * this hook hides the Recharts tooltip wrapper when the user taps elsewhere or
328
+ * scrolls. Recharts naturally restores `visibility: visible` when a new data
329
+ * point is tapped.
330
+ */
331
+ function useChartTouchDismiss(
332
+ containerRef: React.RefObject<HTMLDivElement | null> | undefined,
333
+ portalEl: HTMLDivElement | null
334
+ ) {
335
+ React.useEffect(() => {
336
+ const container = containerRef?.current;
337
+ if (!container) return;
338
+
339
+ const tooltipHost = portalEl ?? container;
340
+ let touchActive = false;
341
+
342
+ function dismiss() {
343
+ const wrapper = tooltipHost.querySelector(
344
+ ".recharts-tooltip-wrapper"
345
+ ) as HTMLElement | null;
346
+ if (wrapper) {
347
+ wrapper.style.visibility = "hidden";
348
+ }
349
+ }
350
+
351
+ function handleTouchStart(e: TouchEvent) {
352
+ touchActive = true;
353
+ const target = e.target as Node;
354
+ if (!container!.contains(target) && !tooltipHost.contains(target)) {
355
+ dismiss();
356
+ touchActive = false;
357
+ }
358
+ }
359
+
360
+ function handleScroll() {
361
+ if (!touchActive) return;
362
+ dismiss();
363
+ touchActive = false;
364
+ }
365
+
366
+ document.addEventListener("touchstart", handleTouchStart, {
367
+ passive: true,
368
+ });
369
+ window.addEventListener("scroll", handleScroll, {
370
+ passive: true,
371
+ capture: true,
372
+ });
373
+
374
+ return () => {
375
+ document.removeEventListener("touchstart", handleTouchStart);
376
+ window.removeEventListener("scroll", handleScroll, { capture: true });
377
+ };
378
+ }, [containerRef, portalEl]);
379
+ }
380
+
381
+ /**
382
+ * ChartTooltip displays data values on hover/tap. Portals to `document.body`
383
+ * by default so the tooltip escapes chart overflow clipping and sits above
384
+ * page-level widgets (z-index 50). On touch devices, dismisses on tap-outside
385
+ * and scroll.
386
+ *
387
+ * Pass `portal={null}` to render inline (pre-portal Recharts default).
388
+ */
389
+ function ChartTooltip({
390
+ portal,
391
+ wrapperStyle,
392
+ allowEscapeViewBox,
393
+ ...props
394
+ }: ChartTooltipProps) {
395
+ const chartContext = useChartOptional();
396
+ const usePortal = portal !== null;
397
+ const portalEl = useChartTooltipPortal(usePortal);
398
+
399
+ useChartTouchDismiss(chartContext?.containerRef, portalEl);
400
+
401
+ return (
402
+ <RechartsPrimitive.Tooltip
403
+ allowEscapeViewBox={allowEscapeViewBox ?? { x: true, y: true }}
404
+ portal={portal !== undefined ? portal : portalEl}
405
+ wrapperStyle={{ zIndex: TOOLTIP_Z_INDEX, ...wrapperStyle }}
406
+ {...props}
407
+ />
408
+ );
263
409
  }
264
410
 
265
411
  ChartTooltip.displayName = "ChartTooltip";
@@ -483,7 +629,12 @@ interface ChartLegendProps extends React.ComponentProps<
483
629
  }
484
630
 
485
631
  /**
486
- * ChartLegend displays a legend for the chart series.
632
+ * ChartLegend positions a legend inside a Recharts chart. Pass
633
+ * `content={<ChartLegendContent />}` to render it with DS styling.
634
+ *
635
+ * For a legend that lives *beside* a chart (next to a donut, or shared by
636
+ * several charts) compose {@link ChartLegendList} and {@link ChartLegendItem}
637
+ * directly instead — Recharts' Legend takes its room from the plot area.
487
638
  */
488
639
  function ChartLegend({ ...props }: ChartLegendProps) {
489
640
  return <RechartsPrimitive.Legend {...props} />;
@@ -491,36 +642,456 @@ function ChartLegend({ ...props }: ChartLegendProps) {
491
642
 
492
643
  ChartLegend.displayName = "ChartLegend";
493
644
 
645
+ // ----------------------------------------------------------------------------
646
+ // Chart Legend Item
647
+ // ----------------------------------------------------------------------------
648
+
649
+ /**
650
+ * Layout direction of a {@link ChartLegendList}.
651
+ */
652
+ type ChartLegendOrientation = "horizontal" | "vertical";
653
+
654
+ /**
655
+ * Scale of a {@link ChartLegendList} and its items.
656
+ * - `sm` — 12/16 text, 8px swatch: chart chrome, next to axis ticks and the tooltip.
657
+ * - `md` — 14/20 text, 10px swatch: a key read as content, beside a donut or under a report chart.
658
+ */
659
+ type ChartLegendSize = "sm" | "md";
660
+
661
+ /**
662
+ * Props for the ChartLegendItem component.
663
+ */
664
+ interface ChartLegendItemProps extends React.ComponentPropsWithoutRef<"div"> {
665
+ /**
666
+ * Data hook for automated testing (required)
667
+ * @example "sources-legend-google"
668
+ */
669
+ dataHook: string;
670
+ /**
671
+ * Key into the chart config. Resolves the swatch colour, the custom icon and
672
+ * the default label. Reads the config from the nearest `ChartContainer` or
673
+ * `ChartLegendList config={…}`; outside both, pass `color` and a label.
674
+ */
675
+ seriesKey?: string;
676
+ /**
677
+ * Swatch colour. Wins over the config colour — the way to colour an item
678
+ * that renders beside a chart rather than inside one.
679
+ * @example "var(--chart-blue)"
680
+ */
681
+ color?: string;
682
+ /**
683
+ * Hide the series icon from the config and draw the colour swatch instead.
684
+ * @default false
685
+ */
686
+ hideIcon?: boolean;
687
+ /**
688
+ * Trailing value (a count, a percentage), rendered in tabular figures and
689
+ * pushed to the far edge in a vertical list.
690
+ */
691
+ value?: React.ReactNode;
692
+ /**
693
+ * De-emphasised: the swatch dims and the text turns muted. The series is
694
+ * still drawn and still counts — it is just not what the reader is looking
695
+ * at (e.g. sources a filter has not chosen). Figma `Visibility=Muted`.
696
+ * @default false
697
+ */
698
+ muted?: boolean;
699
+ /**
700
+ * Switched off: the muted look plus a strike through the label (the value
701
+ * stays legible), so a hidden series reads as hidden in greyscale and in a
702
+ * screenshot — never by colour alone. The strike also reaches a nested
703
+ * button or link used as the label. Use it for a toggled-off series in an
704
+ * interactive legend. Wins over `muted`. Figma `Visibility=Hidden`.
705
+ * @default false
706
+ */
707
+ hidden?: boolean;
708
+ /**
709
+ * Render the child element instead of a `div`, merging the item's props
710
+ * into it — so the item can be a `PopoverTrigger` or a `<button
711
+ * aria-pressed>`. The child's own content becomes the label; the swatch
712
+ * and value are placed around it.
713
+ * @default false
714
+ */
715
+ asChild?: boolean;
716
+ /** Analytics element identifier */
717
+ trackingEl?: string;
718
+ /** Analytics label */
719
+ trackingLabel?: string;
720
+ /**
721
+ * The label. Defaults to the config label for `seriesKey`, then to the key
722
+ * itself. Required when `asChild` is set (it is the element to render).
723
+ */
724
+ children?: React.ReactNode;
725
+ }
726
+
727
+ /**
728
+ * One legend entry: a colour swatch (or the series icon), a label and an
729
+ * optional value. Composable — it renders inside a chart via
730
+ * {@link ChartLegendContent}, or anywhere else inside a
731
+ * {@link ChartLegendList}.
732
+ *
733
+ * @example
734
+ * ```tsx
735
+ * <ChartLegendList dataHook="sources-legend" orientation="vertical" config={config}>
736
+ * <ChartLegendItem dataHook="sources-legend-google" seriesKey="google" value={1240} />
737
+ * <ChartLegendItem dataHook="sources-legend-other" seriesKey="other" value={88} asChild>
738
+ * <PopoverTrigger>Other</PopoverTrigger>
739
+ * </ChartLegendItem>
740
+ * </ChartLegendList>
741
+ * ```
742
+ */
743
+ const ChartLegendItem = React.forwardRef<HTMLDivElement, ChartLegendItemProps>(
744
+ (
745
+ {
746
+ asChild = false,
747
+ children,
748
+ className,
749
+ color,
750
+ dataHook,
751
+ hidden = false,
752
+ hideIcon = false,
753
+ muted = false,
754
+ seriesKey,
755
+ trackingEl,
756
+ trackingLabel,
757
+ value,
758
+ ...props
759
+ },
760
+ ref
761
+ ) => {
762
+ const chart = useChartOptional();
763
+ const itemConfig = seriesKey ? chart?.config[seriesKey] : undefined;
764
+ /* Colour order: explicit prop → config colour → the `--color-<key>`
765
+ variable ChartStyle defines inside a ChartContainer (the only place a
766
+ `theme` config resolves). */
767
+ const swatchColor =
768
+ color ??
769
+ itemConfig?.color ??
770
+ (seriesKey ? `var(--color-${seriesKey})` : undefined);
771
+
772
+ const unresolved =
773
+ !!seriesKey &&
774
+ !color &&
775
+ (!chart || (!!chart.standalone && !itemConfig?.color));
776
+ React.useEffect(() => {
777
+ if (process.env.NODE_ENV !== "production" && unresolved) {
778
+ console.warn(
779
+ `ChartLegendItem: seriesKey="${seriesKey}" has no colour to resolve — render it inside a ChartContainer, give the ChartLegendList config a \`color\` for this key (a \`theme\` only resolves inside a container), or set \`color\`.`
780
+ );
781
+ }
782
+ }, [seriesKey, unresolved]);
783
+
784
+ const Comp = asChild ? Slot : "div";
785
+ const label = children ?? itemConfig?.label ?? seriesKey;
786
+
787
+ return (
788
+ <Comp
789
+ ref={ref}
790
+ className={cn(
791
+ /* The focus ring is here rather than at each call site, so an
792
+ `asChild` button gets it without remembering to. */
793
+ "[&>svg]:text-muted-foreground focus-visible:shadow-default flex items-center gap-1.5 rounded-sm outline-none group-data-[size=md]/legend:gap-2 [&>svg]:size-3 group-data-[size=md]/legend:[&>svg]:size-3.5",
794
+ (muted || hidden) && "text-muted-foreground",
795
+ /* text-decoration does not propagate into a nested <button>/<a>
796
+ (atomic inline-level boxes), so a trigger used as the label gets
797
+ the strike explicitly. */
798
+ hidden && "line-through [&_:is(button,a)]:line-through",
799
+ className
800
+ )}
801
+ data-hidden={hidden || undefined}
802
+ data-hook={dataHook}
803
+ data-muted={muted || hidden || undefined}
804
+ data-slot="chart-legend-item"
805
+ data-tracking-el={trackingEl}
806
+ data-tracking-label={trackingLabel}
807
+ {...props}
808
+ >
809
+ {itemConfig?.icon && !hideIcon ? (
810
+ <itemConfig.icon size={12} />
811
+ ) : (
812
+ /* A span, not a div: with `asChild` the item is often a button,
813
+ which only allows phrasing content. */
814
+ <span
815
+ aria-hidden="true"
816
+ className={cn(
817
+ "duration-fast block size-2 shrink-0 rounded-[2px] transition-opacity ease-out group-data-[size=md]/legend:size-2.5",
818
+ (muted || hidden) && "opacity-40"
819
+ )}
820
+ data-slot="chart-legend-item-swatch"
821
+ style={{ backgroundColor: swatchColor }}
822
+ />
823
+ )}
824
+ <Slottable>{label}</Slottable>
825
+ {value != null && (
826
+ <span
827
+ className="ml-auto pl-0.5 tabular-nums"
828
+ data-slot="chart-legend-item-value"
829
+ >
830
+ {/* inline-block stops the hidden strike propagating from the item:
831
+ the label is struck, the value stays legible — as in Figma and
832
+ the Chart Legend pattern spec. */}
833
+ <span className="inline-block">{value}</span>
834
+ </span>
835
+ )}
836
+ </Comp>
837
+ );
838
+ }
839
+ );
840
+
841
+ ChartLegendItem.displayName = "ChartLegendItem";
842
+
843
+ // ----------------------------------------------------------------------------
844
+ // Chart Legend List
845
+ // ----------------------------------------------------------------------------
846
+
847
+ const chartLegendListVariants = cva("group/legend flex", {
848
+ variants: {
849
+ size: {
850
+ sm: "text-body-xs",
851
+ md: "text-body-sm",
852
+ },
853
+ orientation: {
854
+ /* Wraps: six or seven series do not fit one line on a phone, and
855
+ without wrapping the tail is simply clipped. */
856
+ horizontal: "flex-wrap items-center justify-center gap-x-4 gap-y-1",
857
+ /* Items stretch to the list's width so a value can sit at the far edge. */
858
+ vertical: "flex-col items-stretch gap-3",
859
+ },
860
+ },
861
+ defaultVariants: {
862
+ orientation: "horizontal",
863
+ size: "sm",
864
+ },
865
+ });
866
+
867
+ /**
868
+ * Props for the ChartLegendList component.
869
+ */
870
+ interface ChartLegendListProps extends React.ComponentPropsWithoutRef<"div"> {
871
+ /**
872
+ * Data hook for automated testing (required)
873
+ * @example "sources-legend"
874
+ */
875
+ dataHook: string;
876
+ /**
877
+ * Layout direction. Horizontal wraps under or above a plot; vertical stacks
878
+ * beside a donut, label left and value right.
879
+ * @default "horizontal"
880
+ */
881
+ orientation?: ChartLegendOrientation;
882
+ /**
883
+ * Scale of the list and its items. `sm` matches the chart's axis ticks and
884
+ * tooltip; `md` is for a key read as content beside a donut or under a
885
+ * report chart (14px text, 10px swatch).
886
+ * @default "sm"
887
+ */
888
+ size?: ChartLegendSize;
889
+ /**
890
+ * Accessible name of the legend group.
891
+ * @default "Chart legend"
892
+ */
893
+ ariaLabel?: string;
894
+ /**
895
+ * Chart config for the items, when the list renders outside a
896
+ * `ChartContainer`. Replaces (does not merge with) a surrounding
897
+ * container's config. Give each key a `color` — a `theme` only resolves
898
+ * inside a container.
899
+ */
900
+ config?: ChartConfig;
901
+ /** Analytics element identifier */
902
+ trackingEl?: string;
903
+ /** Analytics label */
904
+ trackingLabel?: string;
905
+ }
906
+
907
+ /**
908
+ * A legend as a standalone list of {@link ChartLegendItem}s — the key beside
909
+ * a donut, a shared key under several charts, or a row of series toggles.
910
+ * {@link ChartLegendContent} renders one of these inside a chart.
911
+ *
912
+ * It is a labelled `role="group"`, not a list: the same container holds
913
+ * static keys and rows of toggle buttons, and a group with a name reads
914
+ * correctly for both ("Chart legend, group"). A static key therefore no
915
+ * longer announces its item count — accepted trade-off (DS-1026 review).
916
+ */
917
+ const ChartLegendList = React.forwardRef<HTMLDivElement, ChartLegendListProps>(
918
+ (
919
+ {
920
+ ariaLabel,
921
+ children,
922
+ className,
923
+ config,
924
+ dataHook,
925
+ orientation = "horizontal",
926
+ size = "sm",
927
+ trackingEl,
928
+ trackingLabel,
929
+ ...props
930
+ },
931
+ ref
932
+ ) => {
933
+ const contextValue = React.useMemo<ChartContextValue | null>(
934
+ () => (config ? { config, standalone: true } : null),
935
+ [config]
936
+ );
937
+ const list = (
938
+ <div
939
+ ref={ref}
940
+ aria-label={ariaLabel ?? "Chart legend"}
941
+ className={cn(
942
+ chartLegendListVariants({ orientation, size }),
943
+ className
944
+ )}
945
+ data-hook={dataHook}
946
+ data-orientation={orientation}
947
+ data-size={size}
948
+ data-slot="chart-legend-list"
949
+ data-tracking-el={trackingEl}
950
+ data-tracking-label={trackingLabel}
951
+ role="group"
952
+ {...props}
953
+ >
954
+ {children}
955
+ </div>
956
+ );
957
+
958
+ return contextValue ? (
959
+ <ChartContext.Provider value={contextValue}>{list}</ChartContext.Provider>
960
+ ) : (
961
+ list
962
+ );
963
+ }
964
+ );
965
+
966
+ ChartLegendList.displayName = "ChartLegendList";
967
+
968
+ // ----------------------------------------------------------------------------
969
+ // Chart Legend Content (Recharts adapter)
970
+ // ----------------------------------------------------------------------------
971
+
972
+ /** `data-hook` segment from an entry key: lower-case, non-alphanumerics to `-`. */
973
+ const slug = (key: string) =>
974
+ key
975
+ .toLowerCase()
976
+ .replace(/[^a-z0-9]+/g, "-")
977
+ .replace(/^-|-$/g, "");
978
+
979
+ /**
980
+ * One entry of the legend payload Recharts hands to `ChartLegend`'s content.
981
+ */
982
+ interface ChartLegendPayloadItem {
983
+ /** Display name — the series name for Bar/Line, the sector name for Pie. */
984
+ value: string;
985
+ /** Series key. Present for Bar/Line/Area series; Pie entries have none. */
986
+ dataKey?: string;
987
+ color?: string;
988
+ /** The series' or sector's raw datum. */
989
+ payload: Record<string, unknown>;
990
+ }
991
+
494
992
  /**
495
993
  * Props for the ChartLegendContent component.
496
994
  */
497
995
  interface ChartLegendContentProps
498
996
  extends React.ComponentProps<"div">, Pick<ChartLegendProps, "nameKey"> {
997
+ /**
998
+ * Data hook for automated testing. Items derive theirs from it
999
+ * (`<dataHook>-<entry key>`, where the entry key is the series `dataKey`,
1000
+ * or the Pie entry's `nameKey` value, slugified).
1001
+ * @default "chart-legend"
1002
+ */
1003
+ dataHook?: string;
499
1004
  /** Hide the series icon in the legend */
500
1005
  hideIcon?: boolean;
501
1006
  /** Legend payload from Recharts (automatically provided) */
502
- payload?: Array<{
503
- value: string;
504
- dataKey: string;
505
- color?: string;
506
- payload: Record<string, unknown>;
507
- }>;
1007
+ payload?: Array<ChartLegendPayloadItem>;
508
1008
  /**
509
- * Vertical alignment of the legend relative to the chart
1009
+ * Vertical alignment of the legend relative to the chart — sets the gap
1010
+ * to the plot. Pass the same value to `ChartLegend`.
510
1011
  * @default "bottom"
511
1012
  */
512
- verticalAlign?: "top" | "bottom";
1013
+ verticalAlign?: "top" | "middle" | "bottom";
1014
+ /**
1015
+ * Layout direction. Pair `vertical` with
1016
+ * `<ChartLegend layout="vertical" align="right" verticalAlign="middle" />`.
1017
+ * @default "horizontal"
1018
+ */
1019
+ orientation?: ChartLegendOrientation;
1020
+ /**
1021
+ * Accessible name of the legend group.
1022
+ * @default "Chart legend"
1023
+ */
1024
+ ariaLabel?: string;
1025
+ /**
1026
+ * Scale of the legend. Keep `sm` inside a chart — it matches the axis
1027
+ * ticks and the tooltip; `md` is for a key read as content.
1028
+ * @default "sm"
1029
+ */
1030
+ size?: ChartLegendSize;
1031
+ /**
1032
+ * Show each entry's value after its label, read from `payload[valueKey]`.
1033
+ * Meaningful for Pie/Donut, whose payload is the sector's datum — for Bar
1034
+ * and Line series the payload carries no total, so render a
1035
+ * `ChartLegendList` beside the chart with your own values instead.
1036
+ * @default false
1037
+ */
1038
+ showValue?: boolean;
1039
+ /**
1040
+ * Field of each entry's datum that holds its value — for a Pie, its
1041
+ * `dataKey` (e.g. `"visitors"`). Defaults to the series `dataKey`, then
1042
+ * `"value"`.
1043
+ */
1044
+ valueKey?: string;
1045
+ /**
1046
+ * Formats the value shown by `showValue`. Receives the payload entry;
1047
+ * read the number from `item.payload`.
1048
+ * @example (item) => `${item.payload.visitors} visitors`
1049
+ */
1050
+ valueFormatter?: (item: ChartLegendPayloadItem) => React.ReactNode;
1051
+ /**
1052
+ * Order of the entries. Recharts sorts the payload alphabetically by
1053
+ * default; pass the entry keys (series `dataKey`s, or Pie `nameKey`
1054
+ * values) in the order the chart declares them, or a comparator. Keys not
1055
+ * listed go last. Legend order should match series order and tooltip
1056
+ * order.
1057
+ * @example ["google", "facebook", "other"]
1058
+ */
1059
+ sortBy?:
1060
+ | string[]
1061
+ | ((a: ChartLegendPayloadItem, b: ChartLegendPayloadItem) => number);
1062
+ /**
1063
+ * Replace the rendering of one entry — e.g. wrap "Other" in a popover
1064
+ * trigger. Receives the entry and the default item. Recharts positions the
1065
+ * legend inside the chart's box, so floating content opened from here can
1066
+ * be clipped by it; for an interactive legend prefer a `ChartLegendList`
1067
+ * beside the chart.
1068
+ */
1069
+ renderItem?: (
1070
+ item: ChartLegendPayloadItem,
1071
+ defaultNode: React.ReactNode
1072
+ ) => React.ReactNode;
513
1073
  }
514
1074
 
515
1075
  /**
516
- * ChartLegendContent renders the content inside the legend.
1076
+ * ChartLegendContent renders Recharts' legend payload as a
1077
+ * {@link ChartLegendList} of {@link ChartLegendItem}s. Use as
1078
+ * `<ChartLegend content={<ChartLegendContent />} />`.
517
1079
  */
518
1080
  function ChartLegendContent({
1081
+ ariaLabel,
519
1082
  className,
1083
+ dataHook = "chart-legend",
520
1084
  hideIcon = false,
1085
+ nameKey,
1086
+ orientation = "horizontal",
521
1087
  payload,
1088
+ renderItem,
1089
+ showValue = false,
1090
+ size = "sm",
1091
+ sortBy,
1092
+ valueFormatter,
1093
+ valueKey,
522
1094
  verticalAlign = "bottom",
523
- nameKey,
524
1095
  }: ChartLegendContentProps) {
525
1096
  const { config } = useChart();
526
1097
 
@@ -528,41 +1099,85 @@ function ChartLegendContent({
528
1099
  return null;
529
1100
  }
530
1101
 
1102
+ /* The key an entry is known by: an explicit nameKey value from the datum,
1103
+ then — for a series (Bar/Line/Area), whose `payload` is the series props
1104
+ carrying the same dataKey — that dataKey, then the display name. A Pie
1105
+ entry stamps the Pie's dataKey on every sector (Recharts 3.10) but its
1106
+ `payload` is the raw datum, so its name (`value`, already resolved through
1107
+ the Pie's own nameKey) is what tells sectors apart. Drives the config
1108
+ lookup, sortBy and the hook. */
1109
+ const entryKey = (item: ChartLegendPayloadItem) => {
1110
+ const isSeries =
1111
+ item.dataKey !== undefined && item.payload?.dataKey === item.dataKey;
1112
+ return String(
1113
+ (nameKey ? item.payload?.[nameKey] : undefined) ??
1114
+ (isSeries ? item.dataKey : (item.value ?? item.dataKey))
1115
+ );
1116
+ };
1117
+ /* Keys absent from a `sortBy` array go last, in their incoming order. */
1118
+ const rank = (item: ChartLegendPayloadItem) => {
1119
+ const index = Array.isArray(sortBy) ? sortBy.indexOf(entryKey(item)) : -1;
1120
+ return index === -1 ? Number.POSITIVE_INFINITY : index;
1121
+ };
1122
+ const sorted = sortBy
1123
+ ? [...payload].sort(
1124
+ Array.isArray(sortBy)
1125
+ ? (a, b) => {
1126
+ const ra = rank(a);
1127
+ const rb = rank(b);
1128
+ return ra === rb ? 0 : ra - rb;
1129
+ }
1130
+ : sortBy
1131
+ )
1132
+ : payload;
1133
+
531
1134
  return (
532
- <div
1135
+ <ChartLegendList
1136
+ ariaLabel={ariaLabel}
533
1137
  className={cn(
534
- "flex items-center justify-center gap-4",
535
- verticalAlign === "top" ? "pb-4" : "pt-4",
1138
+ verticalAlign === "top" && "pb-4",
1139
+ verticalAlign === "bottom" && "pt-4",
536
1140
  className
537
1141
  )}
1142
+ /* Intentional: inside a chart the root keeps the slot name consumers
1143
+ have selected since before the list existed. */
538
1144
  data-slot="chart-legend-content"
1145
+ dataHook={dataHook}
1146
+ orientation={orientation}
1147
+ size={size}
539
1148
  >
540
- {payload.map((item) => {
541
- const key = `${nameKey || item.dataKey || "value"}`;
1149
+ {sorted.map((item) => {
1150
+ const key = entryKey(item);
542
1151
  const itemConfig = config[key];
543
-
544
- return (
545
- <div
1152
+ const value = showValue
1153
+ ? valueFormatter
1154
+ ? valueFormatter(item)
1155
+ : (item.payload?.[valueKey ?? item.dataKey ?? "value"] as
1156
+ React.ReactNode | undefined)
1157
+ : undefined;
1158
+
1159
+ const node = (
1160
+ <ChartLegendItem
546
1161
  key={item.value}
547
- className={cn(
548
- "[&>svg]:text-muted-foreground flex items-center gap-1.5"
549
- )}
1162
+ color={item.color}
1163
+ dataHook={`${dataHook}-${slug(key)}`}
1164
+ hideIcon={hideIcon}
1165
+ seriesKey={key}
1166
+ value={value}
550
1167
  >
551
- {itemConfig?.icon && !hideIcon ? (
552
- <itemConfig.icon size={12} />
553
- ) : (
554
- <div
555
- className="h-2 w-2 shrink-0 rounded-[2px]"
556
- style={{
557
- backgroundColor: item.color,
558
- }}
559
- />
560
- )}
561
1168
  {itemConfig?.label || item.value}
562
- </div>
1169
+ </ChartLegendItem>
1170
+ );
1171
+
1172
+ return renderItem ? (
1173
+ <React.Fragment key={item.value}>
1174
+ {renderItem(item, node)}
1175
+ </React.Fragment>
1176
+ ) : (
1177
+ node
563
1178
  );
564
1179
  })}
565
- </div>
1180
+ </ChartLegendList>
566
1181
  );
567
1182
  }
568
1183
 
@@ -1194,6 +1809,8 @@ export {
1194
1809
  ChartTooltipContent,
1195
1810
  ChartLegend,
1196
1811
  ChartLegendContent,
1812
+ ChartLegendList,
1813
+ ChartLegendItem,
1197
1814
  ChartStyle,
1198
1815
  ChartDot,
1199
1816
  ChartDotOnStroke,
@@ -1211,6 +1828,11 @@ export type {
1211
1828
  ChartTooltipPayloadItem,
1212
1829
  ChartLegendProps,
1213
1830
  ChartLegendContentProps,
1831
+ ChartLegendListProps,
1832
+ ChartLegendItemProps,
1833
+ ChartLegendOrientation,
1834
+ ChartLegendPayloadItem,
1835
+ ChartLegendSize,
1214
1836
  ChartDotProps,
1215
1837
  ChartDotOnStrokeProps,
1216
1838
  ChartDotSize,