@brightlocal/ui-components 3.2.0 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (434) hide show
  1. package/AI_USAGE.md +10 -0
  2. package/README.md +3 -1
  3. package/component-meta.json +1458 -380
  4. package/deprecations.json +44 -0
  5. package/dist/_virtual/_rolldown/runtime.cjs +1 -0
  6. package/dist/accordion.cjs +1 -1
  7. package/dist/accordion.js +73 -102
  8. package/dist/alert-dialog.cjs +1 -1
  9. package/dist/alert-dialog.d.ts +6 -4
  10. package/dist/alert-dialog.d.ts.map +1 -1
  11. package/dist/alert-dialog.js +85 -133
  12. package/dist/alert.cjs +1 -1
  13. package/dist/alert.d.ts +4 -4
  14. package/dist/alert.d.ts.map +1 -1
  15. package/dist/alert.js +106 -168
  16. package/dist/aspect-ratio.cjs +1 -1
  17. package/dist/aspect-ratio.js +13 -16
  18. package/dist/avatar.cjs +1 -1
  19. package/dist/avatar.js +30 -45
  20. package/dist/badge.cjs +1 -1
  21. package/dist/badge.d.ts +23 -1
  22. package/dist/badge.d.ts.map +1 -1
  23. package/dist/badge.js +90 -91
  24. package/dist/banner.cjs +1 -1
  25. package/dist/banner.js +102 -148
  26. package/dist/blocks/empty-state.cjs +1 -1
  27. package/dist/blocks/empty-state.d.ts +20 -3
  28. package/dist/blocks/empty-state.d.ts.map +1 -1
  29. package/dist/blocks/empty-state.js +73 -140
  30. package/dist/blocks/input-list.cjs +2 -2
  31. package/dist/blocks/input-list.d.ts +2 -2
  32. package/dist/blocks/input-list.d.ts.map +1 -1
  33. package/dist/blocks/input-list.js +138 -178
  34. package/dist/blocks/progress-state.cjs +1 -1
  35. package/dist/blocks/progress-state.js +223 -347
  36. package/dist/blocks/sidebar.cjs +1 -1
  37. package/dist/blocks/sidebar.d.ts +11 -6
  38. package/dist/blocks/sidebar.d.ts.map +1 -1
  39. package/dist/blocks/sidebar.js +763 -1092
  40. package/dist/brand-illustration-motif.cjs +1 -1
  41. package/dist/brand-illustration-motif.js +40 -61
  42. package/dist/breadcrumb.cjs +1 -1
  43. package/dist/breadcrumb.js +62 -102
  44. package/dist/button-group.cjs +1 -1
  45. package/dist/button-group.js +23 -31
  46. package/dist/button.cjs +1 -1
  47. package/dist/button.d.ts +4 -2
  48. package/dist/button.d.ts.map +1 -1
  49. package/dist/button.js +149 -189
  50. package/dist/calendar.cjs +1 -1
  51. package/dist/calendar.d.ts +87 -3
  52. package/dist/calendar.d.ts.map +1 -1
  53. package/dist/calendar.js +116 -173
  54. package/dist/callout.cjs +1 -1
  55. package/dist/callout.js +73 -96
  56. package/dist/card.cjs +1 -1
  57. package/dist/card.d.ts +10 -4
  58. package/dist/card.d.ts.map +1 -1
  59. package/dist/card.js +233 -316
  60. package/dist/carousel.cjs +1 -1
  61. package/dist/carousel.d.ts +3 -3
  62. package/dist/carousel.d.ts.map +1 -1
  63. package/dist/carousel.js +174 -268
  64. package/dist/centred-layout.cjs +1 -1
  65. package/dist/centred-layout.js +27 -48
  66. package/dist/chart-empty.cjs +1 -1
  67. package/dist/chart-empty.js +18 -27
  68. package/dist/chart.cjs +7 -7
  69. package/dist/chart.d.ts +23 -13
  70. package/dist/chart.d.ts.map +1 -1
  71. package/dist/chart.js +445 -651
  72. package/dist/checkbox.cjs +1 -1
  73. package/dist/checkbox.js +36 -69
  74. package/dist/chip.cjs +1 -1
  75. package/dist/chip.js +116 -173
  76. package/dist/collapsible.cjs +1 -1
  77. package/dist/collapsible.d.ts.map +1 -1
  78. package/dist/collapsible.js +35 -41
  79. package/dist/combobox.cjs +3 -3
  80. package/dist/combobox.d.ts +14 -4
  81. package/dist/combobox.d.ts.map +1 -1
  82. package/dist/combobox.js +439 -638
  83. package/dist/command.cjs +1 -1
  84. package/dist/command.d.ts.map +1 -1
  85. package/dist/command.js +273 -420
  86. package/dist/context-menu.cjs +1 -1
  87. package/dist/context-menu.d.ts +5 -5
  88. package/dist/context-menu.d.ts.map +1 -1
  89. package/dist/context-menu.js +121 -191
  90. package/dist/data-table.cjs +1 -1
  91. package/dist/data-table.d.ts +280 -129
  92. package/dist/data-table.d.ts.map +1 -1
  93. package/dist/data-table.js +687 -948
  94. package/dist/date-picker.cjs +1 -1
  95. package/dist/date-picker.d.ts +15 -4
  96. package/dist/date-picker.d.ts.map +1 -1
  97. package/dist/date-picker.js +156 -231
  98. package/dist/delta.cjs +1 -0
  99. package/dist/delta.d.ts +79 -0
  100. package/dist/delta.d.ts.map +1 -0
  101. package/dist/delta.js +62 -0
  102. package/dist/description-list.cjs +1 -0
  103. package/dist/description-list.d.ts +142 -0
  104. package/dist/description-list.d.ts.map +1 -0
  105. package/dist/description-list.js +173 -0
  106. package/dist/description.cjs +1 -1
  107. package/dist/description.js +11 -20
  108. package/dist/dialog.cjs +1 -1
  109. package/dist/dialog.d.ts +1 -1
  110. package/dist/dialog.d.ts.map +1 -1
  111. package/dist/dialog.js +76 -116
  112. package/dist/drawer.cjs +1 -1
  113. package/dist/drawer.d.ts +11 -11
  114. package/dist/drawer.d.ts.map +1 -1
  115. package/dist/drawer.js +76 -134
  116. package/dist/dropdown-menu.cjs +1 -1
  117. package/dist/dropdown-menu.d.ts +6 -6
  118. package/dist/dropdown-menu.d.ts.map +1 -1
  119. package/dist/dropdown-menu.js +179 -300
  120. package/dist/field.cjs +1 -1
  121. package/dist/field.d.ts +9 -9
  122. package/dist/field.d.ts.map +1 -1
  123. package/dist/field.js +166 -286
  124. package/dist/global-layout.cjs +1 -1
  125. package/dist/global-layout.js +203 -342
  126. package/dist/grid.cjs +1 -1
  127. package/dist/grid.js +16 -29
  128. package/dist/header.cjs +1 -1
  129. package/dist/header.js +21 -38
  130. package/dist/height-transition.cjs +1 -1
  131. package/dist/height-transition.js +38 -55
  132. package/dist/hooks/use-breakpoint.cjs +1 -1
  133. package/dist/hooks/use-breakpoint.js +9 -9
  134. package/dist/hooks/use-debounce.cjs +1 -1
  135. package/dist/hooks/use-debounce.js +12 -11
  136. package/dist/hooks/use-delayed-pending.cjs +1 -1
  137. package/dist/hooks/use-delayed-pending.js +8 -9
  138. package/dist/hooks/use-filter-search-params.cjs +1 -0
  139. package/dist/hooks/use-filter-search-params.d.ts +93 -0
  140. package/dist/hooks/use-filter-search-params.d.ts.map +1 -0
  141. package/dist/hooks/use-filter-search-params.js +122 -0
  142. package/dist/hooks/use-mobile.cjs +1 -1
  143. package/dist/hooks/use-mobile.js +6 -6
  144. package/dist/hooks/use-overlay-pointer-lock.cjs +1 -1
  145. package/dist/hooks/use-overlay-pointer-lock.js +8 -9
  146. package/dist/hooks/use-prefers-reduced-motion.cjs +1 -1
  147. package/dist/hooks/use-prefers-reduced-motion.js +5 -8
  148. package/dist/hover-card.cjs +1 -1
  149. package/dist/hover-card.d.ts +1 -1
  150. package/dist/hover-card.d.ts.map +1 -1
  151. package/dist/hover-card.js +30 -62
  152. package/dist/index.cjs +1 -1
  153. package/dist/index.d.ts +7 -0
  154. package/dist/index.d.ts.map +1 -1
  155. package/dist/index.js +658 -614
  156. package/dist/info-tooltip.cjs +1 -1
  157. package/dist/info-tooltip.js +22 -36
  158. package/dist/input-chip.cjs +1 -1
  159. package/dist/input-chip.d.ts +32 -3
  160. package/dist/input-chip.d.ts.map +1 -1
  161. package/dist/input-chip.js +181 -230
  162. package/dist/input-group.cjs +1 -1
  163. package/dist/input-group.js +174 -221
  164. package/dist/input-otp.cjs +1 -1
  165. package/dist/input-otp.d.ts +3 -3
  166. package/dist/input-otp.d.ts.map +1 -1
  167. package/dist/input-otp.js +102 -146
  168. package/dist/input-password.cjs +1 -1
  169. package/dist/input-password.d.ts +12 -16
  170. package/dist/input-password.d.ts.map +1 -1
  171. package/dist/input-password.js +139 -171
  172. package/dist/input.cjs +1 -1
  173. package/dist/input.d.ts.map +1 -1
  174. package/dist/input.js +51 -73
  175. package/dist/label.cjs +1 -1
  176. package/dist/label.js +20 -38
  177. package/dist/lib/block-illustration.cjs +1 -1
  178. package/dist/lib/block-illustration.d.ts +1 -1
  179. package/dist/lib/block-illustration.d.ts.map +1 -1
  180. package/dist/lib/block-illustration.js +16 -18
  181. package/dist/lib/compose-event-handlers.cjs +1 -0
  182. package/dist/lib/compose-event-handlers.d.ts +9 -0
  183. package/dist/lib/compose-event-handlers.d.ts.map +1 -0
  184. package/dist/lib/compose-event-handlers.js +8 -0
  185. package/dist/lib/download-file.cjs +1 -0
  186. package/dist/lib/download-file.d.ts +14 -0
  187. package/dist/lib/download-file.d.ts.map +1 -0
  188. package/dist/lib/download-file.js +40 -0
  189. package/dist/lib/empty-canvas.cjs +1 -1
  190. package/dist/lib/empty-canvas.js +28 -56
  191. package/dist/lib/empty-chip.cjs +1 -1
  192. package/dist/lib/empty-chip.d.ts +14 -3
  193. package/dist/lib/empty-chip.d.ts.map +1 -1
  194. package/dist/lib/empty-chip.js +15 -11
  195. package/dist/lib/field-aria.cjs +1 -0
  196. package/dist/lib/field-aria.d.ts +34 -0
  197. package/dist/lib/field-aria.d.ts.map +1 -0
  198. package/dist/lib/field-aria.js +52 -0
  199. package/dist/lib/image-file-info.cjs +1 -0
  200. package/dist/lib/image-file-info.d.ts +25 -0
  201. package/dist/lib/image-file-info.d.ts.map +1 -0
  202. package/dist/lib/image-file-info.js +67 -0
  203. package/dist/lib/media-viewer-content.cjs +1 -0
  204. package/dist/lib/media-viewer-content.d.ts +102 -0
  205. package/dist/lib/media-viewer-content.d.ts.map +1 -0
  206. package/dist/lib/media-viewer-content.js +650 -0
  207. package/dist/lib/media-viewer-internal.cjs +1 -0
  208. package/dist/lib/media-viewer-internal.d.ts +98 -0
  209. package/dist/lib/media-viewer-internal.d.ts.map +1 -0
  210. package/dist/lib/media-viewer-internal.js +61 -0
  211. package/dist/lib/media-viewer-motion.cjs +1 -0
  212. package/dist/lib/media-viewer-motion.d.ts +40 -0
  213. package/dist/lib/media-viewer-motion.d.ts.map +1 -0
  214. package/dist/lib/media-viewer-motion.js +37 -0
  215. package/dist/lib/motion.cjs +1 -1
  216. package/dist/lib/motion.d.ts +8 -0
  217. package/dist/lib/motion.d.ts.map +1 -1
  218. package/dist/lib/motion.js +14 -8
  219. package/dist/lib/optical-center.cjs +1 -1
  220. package/dist/lib/optical-center.d.ts +1 -1
  221. package/dist/lib/optical-center.d.ts.map +1 -1
  222. package/dist/lib/optical-center.js +12 -5
  223. package/dist/lib/spring-settle.cjs +1 -1
  224. package/dist/lib/spring-settle.js +1 -1
  225. package/dist/lib/table-internal.cjs +1 -0
  226. package/dist/lib/table-internal.d.ts +62 -0
  227. package/dist/lib/table-internal.d.ts.map +1 -0
  228. package/dist/lib/table-internal.js +18 -0
  229. package/dist/lib/use-controllable.cjs +1 -0
  230. package/dist/lib/use-controllable.d.ts +12 -0
  231. package/dist/lib/use-controllable.d.ts.map +1 -0
  232. package/dist/lib/use-controllable.js +15 -0
  233. package/dist/lib/use-dev-warning.cjs +1 -1
  234. package/dist/lib/utils.cjs +1 -1
  235. package/dist/lib/utils.js +26 -33
  236. package/dist/link.cjs +1 -1
  237. package/dist/link.d.ts +1 -1
  238. package/dist/link.js +78 -124
  239. package/dist/list.cjs +1 -1
  240. package/dist/list.d.ts +224 -39
  241. package/dist/list.d.ts.map +1 -1
  242. package/dist/list.js +323 -171
  243. package/dist/loading.cjs +1 -1
  244. package/dist/loading.js +124 -151
  245. package/dist/logo-mark.cjs +1 -0
  246. package/dist/logo-mark.d.ts +79 -0
  247. package/dist/logo-mark.d.ts.map +1 -0
  248. package/dist/logo-mark.js +219 -0
  249. package/dist/logo.cjs +1 -1
  250. package/dist/logo.d.ts +1 -1
  251. package/dist/logo.d.ts.map +1 -1
  252. package/dist/logo.js +51 -87
  253. package/dist/map.cjs +1 -1
  254. package/dist/map.d.ts.map +1 -1
  255. package/dist/map.js +390 -586
  256. package/dist/media-empty.cjs +1 -1
  257. package/dist/media-empty.js +27 -42
  258. package/dist/media-viewer.cjs +1 -0
  259. package/dist/media-viewer.d.ts +224 -0
  260. package/dist/media-viewer.d.ts.map +1 -0
  261. package/dist/media-viewer.js +295 -0
  262. package/dist/menubar.cjs +1 -1
  263. package/dist/menubar.d.ts +14 -14
  264. package/dist/menubar.d.ts.map +1 -1
  265. package/dist/menubar.js +130 -267
  266. package/dist/multi-select-filter.cjs +1 -1
  267. package/dist/multi-select-filter.d.ts +9 -1
  268. package/dist/multi-select-filter.d.ts.map +1 -1
  269. package/dist/multi-select-filter.js +357 -446
  270. package/dist/navigation-menu.cjs +1 -1
  271. package/dist/navigation-menu.js +108 -172
  272. package/dist/pagination.cjs +1 -1
  273. package/dist/pagination.d.ts +36 -12
  274. package/dist/pagination.d.ts.map +1 -1
  275. package/dist/pagination.js +208 -281
  276. package/dist/popover.cjs +1 -1
  277. package/dist/popover.d.ts +1 -1
  278. package/dist/popover.d.ts.map +1 -1
  279. package/dist/popover.js +34 -45
  280. package/dist/progress.cjs +1 -1
  281. package/dist/progress.d.ts +17 -2
  282. package/dist/progress.d.ts.map +1 -1
  283. package/dist/progress.js +116 -162
  284. package/dist/radio-group.cjs +1 -1
  285. package/dist/radio-group.js +90 -146
  286. package/dist/rating.cjs +1 -1
  287. package/dist/rating.d.ts +80 -13
  288. package/dist/rating.d.ts.map +1 -1
  289. package/dist/rating.js +70 -65
  290. package/dist/relative-date.cjs +1 -1
  291. package/dist/relative-date.d.ts.map +1 -1
  292. package/dist/relative-date.js +73 -89
  293. package/dist/resizable.cjs +1 -1
  294. package/dist/resizable.d.ts +39 -23
  295. package/dist/resizable.d.ts.map +1 -1
  296. package/dist/resizable.js +42 -44
  297. package/dist/result-count.cjs +1 -0
  298. package/dist/result-count.d.ts +110 -0
  299. package/dist/result-count.d.ts.map +1 -0
  300. package/dist/result-count.js +49 -0
  301. package/dist/route-progress.cjs +1 -1
  302. package/dist/route-progress.js +59 -102
  303. package/dist/scroll-area.cjs +1 -1
  304. package/dist/scroll-area.d.ts +9 -1
  305. package/dist/scroll-area.d.ts.map +1 -1
  306. package/dist/scroll-area.js +44 -79
  307. package/dist/select.cjs +2 -2
  308. package/dist/select.d.ts +10 -10
  309. package/dist/select.d.ts.map +1 -1
  310. package/dist/select.js +118 -238
  311. package/dist/separator.cjs +1 -1
  312. package/dist/separator.js +90 -78
  313. package/dist/sheet.cjs +1 -1
  314. package/dist/sheet.d.ts +8 -5
  315. package/dist/sheet.d.ts.map +1 -1
  316. package/dist/sheet.js +250 -317
  317. package/dist/single-select-filter.cjs +1 -1
  318. package/dist/single-select-filter.d.ts +32 -0
  319. package/dist/single-select-filter.d.ts.map +1 -1
  320. package/dist/single-select-filter.js +201 -203
  321. package/dist/skeleton.cjs +1 -1
  322. package/dist/skeleton.js +24 -38
  323. package/dist/slider.cjs +1 -1
  324. package/dist/slider.js +51 -81
  325. package/dist/sonner.cjs +1 -1
  326. package/dist/sonner.d.ts +1 -1
  327. package/dist/sonner.d.ts.map +1 -1
  328. package/dist/sonner.js +101 -125
  329. package/dist/spinner.cjs +1 -1
  330. package/dist/spinner.js +22 -31
  331. package/dist/split-layout.cjs +1 -1
  332. package/dist/split-layout.js +52 -101
  333. package/dist/status.cjs +1 -0
  334. package/dist/status.d.ts +51 -0
  335. package/dist/status.d.ts.map +1 -0
  336. package/dist/status.js +60 -0
  337. package/dist/stepper.cjs +1 -1
  338. package/dist/stepper.js +184 -316
  339. package/dist/switch.cjs +1 -1
  340. package/dist/switch.js +17 -32
  341. package/dist/table.cjs +1 -1
  342. package/dist/table.d.ts +103 -30
  343. package/dist/table.d.ts.map +1 -1
  344. package/dist/table.js +170 -209
  345. package/dist/tabs.cjs +1 -1
  346. package/dist/tabs.d.ts.map +1 -1
  347. package/dist/tabs.js +102 -147
  348. package/dist/text-reveal-motion.cjs +1 -1
  349. package/dist/text-reveal-motion.js +307 -363
  350. package/dist/textarea.cjs +1 -1
  351. package/dist/textarea.d.ts.map +1 -1
  352. package/dist/textarea.js +22 -35
  353. package/dist/toggle-group.cjs +1 -1
  354. package/dist/toggle-group.js +43 -62
  355. package/dist/toggle.cjs +1 -1
  356. package/dist/toggle.js +34 -46
  357. package/dist/tooltip.cjs +1 -1
  358. package/dist/tooltip.d.ts +2 -2
  359. package/dist/tooltip.d.ts.map +1 -1
  360. package/dist/tooltip.js +157 -249
  361. package/dist/typography-heading.cjs +1 -1
  362. package/dist/typography-heading.js +25 -61
  363. package/dist/typography-text.cjs +1 -1
  364. package/dist/typography-text.js +27 -57
  365. package/dist/typography.cjs +1 -1
  366. package/dist/typography.js +132 -340
  367. package/package.json +47 -47
  368. package/src/blocks/empty-state.tsx +34 -18
  369. package/src/blocks/input-list.tsx +14 -9
  370. package/src/blocks/sidebar.tsx +86 -31
  371. package/src/components/accordion.tsx +1 -1
  372. package/src/components/alert-dialog.tsx +4 -2
  373. package/src/components/badge.tsx +127 -15
  374. package/src/components/breadcrumb.tsx +1 -1
  375. package/src/components/button.tsx +8 -6
  376. package/src/components/calendar.tsx +155 -9
  377. package/src/components/card.tsx +63 -10
  378. package/src/components/carousel.tsx +4 -1
  379. package/src/components/chart.tsx +151 -17
  380. package/src/components/checkbox.tsx +1 -1
  381. package/src/components/collapsible.tsx +4 -1
  382. package/src/components/combobox.tsx +40 -7
  383. package/src/components/command.tsx +9 -10
  384. package/src/components/context-menu.tsx +4 -4
  385. package/src/components/data-table.tsx +619 -237
  386. package/src/components/date-picker.tsx +31 -4
  387. package/src/components/delta.tsx +217 -0
  388. package/src/components/description-list.tsx +445 -0
  389. package/src/components/drawer.tsx +5 -5
  390. package/src/components/dropdown-menu.tsx +4 -4
  391. package/src/components/field.tsx +36 -15
  392. package/src/components/global-layout.tsx +1 -1
  393. package/src/components/input-chip.tsx +51 -7
  394. package/src/components/input-group.tsx +1 -1
  395. package/src/components/input-password.tsx +15 -19
  396. package/src/components/input.tsx +10 -1
  397. package/src/components/list.tsx +695 -72
  398. package/src/components/logo-mark.tsx +345 -0
  399. package/src/components/map.tsx +18 -20
  400. package/src/components/media-viewer.tsx +908 -0
  401. package/src/components/multi-select-filter.tsx +255 -121
  402. package/src/components/navigation-menu.tsx +2 -2
  403. package/src/components/pagination.tsx +86 -26
  404. package/src/components/progress.tsx +91 -23
  405. package/src/components/rating.tsx +200 -74
  406. package/src/components/relative-date.tsx +19 -11
  407. package/src/components/resizable.tsx +86 -33
  408. package/src/components/result-count.tsx +253 -0
  409. package/src/components/scroll-area.tsx +31 -5
  410. package/src/components/select.tsx +2 -2
  411. package/src/components/sheet.tsx +14 -4
  412. package/src/components/single-select-filter.tsx +136 -41
  413. package/src/components/slider.tsx +2 -2
  414. package/src/components/status.tsx +162 -0
  415. package/src/components/switch.tsx +1 -1
  416. package/src/components/table.tsx +278 -106
  417. package/src/components/tabs.tsx +1 -0
  418. package/src/components/textarea.tsx +20 -2
  419. package/src/components/toggle.tsx +2 -2
  420. package/src/components/tooltip.tsx +11 -20
  421. package/src/hooks/use-filter-search-params.ts +302 -0
  422. package/src/index.ts +7 -0
  423. package/src/lib/compose-event-handlers.ts +14 -0
  424. package/src/lib/download-file.ts +61 -0
  425. package/src/lib/empty-chip.tsx +52 -0
  426. package/src/lib/field-aria.tsx +97 -0
  427. package/src/lib/image-file-info.ts +102 -0
  428. package/src/lib/media-viewer-content.tsx +1587 -0
  429. package/src/lib/media-viewer-internal.tsx +191 -0
  430. package/src/lib/media-viewer-motion.ts +120 -0
  431. package/src/lib/motion.ts +9 -0
  432. package/src/lib/table-internal.ts +74 -0
  433. package/src/lib/use-controllable.ts +43 -0
  434. package/src/lib/empty-chip.ts +0 -24
@@ -1,18 +1,26 @@
1
+ "use client";
2
+
1
3
  import * as React from "react";
2
4
  import { Slot } from "@radix-ui/react-slot";
3
5
  import { cva } from "class-variance-authority";
4
6
 
7
+ import { ChevronRight } from "@brightlocal/icons";
5
8
  import { cn } from "@brightlocal/ui-components/lib/utils";
6
9
  import { Skeleton } from "@brightlocal/ui-components/skeleton";
10
+ import {
11
+ Tooltip,
12
+ TooltipContent,
13
+ TooltipTrigger,
14
+ } from "@brightlocal/ui-components/tooltip";
7
15
 
8
16
  /* -------------------------------------------------------------------------------------------------
9
- * Item variants
17
+ * ListItem variants
10
18
  * -----------------------------------------------------------------------------------------------*/
11
19
 
12
- const itemVariants = cva(
20
+ const listItemVariants = cva(
13
21
  [
22
+ "group/item",
14
23
  "flex",
15
- "items-center",
16
24
  "gap-4",
17
25
  "rounded-lg",
18
26
  "py-2",
@@ -21,6 +29,10 @@ const itemVariants = cva(
21
29
  "transition-colors",
22
30
  "duration-fast",
23
31
  "ease-out",
32
+ // A row that holds an ListItemButton or ListItemLink hands its padding to it, so the
33
+ // whole row is the hit area and the padding never doubles (DS-1166).
34
+ "has-[>[data-slot=item-button]]:p-0",
35
+ "has-[>[data-slot=item-link]]:p-0",
24
36
  ],
25
37
  {
26
38
  variants: {
@@ -30,9 +42,14 @@ const itemVariants = cva(
30
42
  outline: ["bg-background", "border", "border-border"],
31
43
  loading: ["p-0"],
32
44
  },
45
+ align: {
46
+ center: ["items-center"],
47
+ start: ["items-start"],
48
+ },
33
49
  },
34
50
  defaultVariants: {
35
51
  variant: "filled",
52
+ align: "center",
36
53
  },
37
54
  }
38
55
  );
@@ -50,6 +67,19 @@ export type ListProps = React.ComponentProps<"ul"> & {
50
67
  * Data hook for automated testing (required).
51
68
  */
52
69
  dataHook: string;
70
+ /**
71
+ * Pulls the list out by the row's own inline padding, so the text of plain
72
+ * (`default`) rows lines up with the content edge of the card around it.
73
+ * @default false
74
+ */
75
+ inset?: boolean;
76
+ /**
77
+ * Draws a hairline between rows and drops the gap and the row radius, for
78
+ * plain (`default`) rows such as a drill-down list. For a single break
79
+ * between two groups, use `ListSeparator` instead.
80
+ * @default false
81
+ */
82
+ divided?: boolean;
53
83
  /**
54
84
  * Tracking element identifier for analytics.
55
85
  */
@@ -61,27 +91,58 @@ export type ListProps = React.ComponentProps<"ul"> & {
61
91
  };
62
92
 
63
93
  /**
64
- * Vertical list container for rendering a collection of Item rows.
94
+ * Vertical list container for rendering a collection of ListItem rows.
65
95
  *
66
96
  * @example
67
97
  * ```tsx
68
98
  * <List dataHook="keywords-list">
69
- * <Item variant="filled" dataHook="item-1">
70
- * <ItemContent>
71
- * <ItemTitle>Keyword</ItemTitle>
72
- * </ItemContent>
73
- * <ItemActions>
99
+ * <ListItem variant="filled" dataHook="item-1">
100
+ * <ListItemContent>
101
+ * <ListItemTitle>Keyword</ListItemTitle>
102
+ * </ListItemContent>
103
+ * <ListItemActions>
74
104
  * <Button variant="ghost" size="icon" dataHook="remove"><XIcon /></Button>
75
- * </ItemActions>
76
- * </Item>
105
+ * </ListItemActions>
106
+ * </ListItem>
77
107
  * </List>
78
108
  * ```
79
109
  */
110
+ const listVariants = cva(["flex", "flex-col"], {
111
+ variants: {
112
+ inset: {
113
+ true: ["-mr-2", "-ml-4"],
114
+ false: [],
115
+ },
116
+ divided: {
117
+ true: [
118
+ "gap-0",
119
+ "[&>[data-slot=item]]:rounded-none",
120
+ "[&>[data-slot=item]+[data-slot=item]]:border-t",
121
+ "[&>[data-slot=item]+[data-slot=item]]:border-border",
122
+ ],
123
+ false: ["gap-2"],
124
+ },
125
+ },
126
+ defaultVariants: { inset: false, divided: false },
127
+ });
128
+
80
129
  const List = React.forwardRef<HTMLUListElement, ListProps>(
81
- ({ className, dataHook, trackingEl, trackingLabel, ...props }, ref) => (
130
+ (
131
+ {
132
+ className,
133
+ dataHook,
134
+ trackingEl,
135
+ trackingLabel,
136
+ inset,
137
+ divided,
138
+ ...props
139
+ },
140
+ ref
141
+ ) => (
82
142
  <ul
83
143
  ref={ref}
84
- className={cn("flex flex-col gap-2", className)}
144
+ className={cn(listVariants({ inset, divided }), className)}
145
+ data-divided={divided ? "" : undefined}
85
146
  data-hook={dataHook}
86
147
  data-slot="list"
87
148
  data-tracking-el={trackingEl}
@@ -93,14 +154,14 @@ const List = React.forwardRef<HTMLUListElement, ListProps>(
93
154
  List.displayName = "List";
94
155
 
95
156
  /* -------------------------------------------------------------------------------------------------
96
- * Item
157
+ * ListItem
97
158
  * -----------------------------------------------------------------------------------------------*/
98
159
 
99
160
  /**
100
- * Props for an individual Item row within a List.
161
+ * Props for an individual ListItem row within a List.
101
162
  * Extends native `<li>` props with CVA variant styling and optional testing/analytics attributes.
102
163
  */
103
- export type ItemProps = React.ComponentProps<"li"> & {
164
+ export type ListItemProps = React.ComponentProps<"li"> & {
104
165
  /**
105
166
  * Render as the child element instead of `<li>`.
106
167
  * Useful when the item is wrapped by another element (e.g. `<motion.li>`).
@@ -115,6 +176,13 @@ export type ItemProps = React.ComponentProps<"li"> & {
115
176
  * @default "filled"
116
177
  */
117
178
  variant?: "default" | "filled" | "outline" | "loading";
179
+ /**
180
+ * Cross-axis alignment of the row's children (media, content, actions).
181
+ * Use `"start"` when ListItemMedia (icon, avatar, step number) should pin to the
182
+ * first line of multi-line content instead of centering vertically.
183
+ * @default "center"
184
+ */
185
+ align?: "center" | "start";
118
186
  /**
119
187
  * Data hook for automated testing.
120
188
  */
@@ -131,14 +199,15 @@ export type ItemProps = React.ComponentProps<"li"> & {
131
199
 
132
200
  /**
133
201
  * Row component within a List. Supports `default`, `filled`, `outline`, and `loading` variants.
134
- * Compose with ItemMedia, ItemContent, ItemTitle, ItemDescription, and ItemActions.
202
+ * Compose with ListItemMedia, ListItemContent, ListItemTitle, ListItemDescription, and ListItemActions.
135
203
  */
136
- const Item = React.forwardRef<HTMLLIElement, ItemProps>(
204
+ const ListItem = React.forwardRef<HTMLLIElement, ListItemProps>(
137
205
  (
138
206
  {
139
207
  asChild = false,
140
208
  className,
141
209
  variant,
210
+ align,
142
211
  dataHook,
143
212
  trackingEl,
144
213
  trackingLabel,
@@ -152,7 +221,8 @@ const Item = React.forwardRef<HTMLLIElement, ItemProps>(
152
221
  return (
153
222
  <Comp
154
223
  ref={ref}
155
- className={cn(itemVariants({ variant }), className)}
224
+ className={cn(listItemVariants({ variant, align }), className)}
225
+ data-align={align ?? "center"}
156
226
  data-hook={dataHook}
157
227
  data-slot="item"
158
228
  data-tracking-el={trackingEl}
@@ -171,113 +241,354 @@ const Item = React.forwardRef<HTMLLIElement, ItemProps>(
171
241
  );
172
242
  }
173
243
  );
174
- Item.displayName = "Item";
244
+ ListItem.displayName = "ListItem";
175
245
 
176
246
  /* -------------------------------------------------------------------------------------------------
177
- * ItemMedia
247
+ * ListItemMedia
178
248
  * -----------------------------------------------------------------------------------------------*/
179
249
 
180
- /** Props for the ItemMedia sub-component — optional left-side media slot. */
181
- export type ItemMediaProps = React.ComponentProps<"div">;
250
+ const listItemMediaVariants = cva(["shrink-0"], {
251
+ variants: {
252
+ variant: {
253
+ default: [],
254
+ icon: [
255
+ "inline-flex",
256
+ "size-10",
257
+ "items-center",
258
+ "justify-center",
259
+ "rounded-lg",
260
+ "border",
261
+ "border-border",
262
+ "bg-background",
263
+ ],
264
+ image: [
265
+ "size-10",
266
+ "overflow-hidden",
267
+ "rounded-lg",
268
+ "[&_img]:size-full",
269
+ "[&_img]:object-cover",
270
+ ],
271
+ },
272
+ },
273
+ defaultVariants: { variant: "default" },
274
+ });
275
+
276
+ /** Props for the ListItemMedia sub-component — optional left-side media slot. */
277
+ export type ListItemMediaProps = React.ComponentProps<"div"> & {
278
+ /**
279
+ * How the media is framed.
280
+ * - `default` — the icon or avatar as it is
281
+ * - `icon` — a 40px bordered tile, for brand logos and icons
282
+ * - `image` — a 40px rounded crop, for thumbnails
283
+ * @default "default"
284
+ */
285
+ variant?: "default" | "icon" | "image";
286
+ };
182
287
 
183
288
  /**
184
- * Optional left-side media slot for icons or avatars.
289
+ * Optional left-side media slot for icons, avatars, logo tiles or thumbnails.
185
290
  */
186
- const ItemMedia = React.forwardRef<HTMLDivElement, ItemMediaProps>(
187
- ({ className, ...props }, ref) => (
291
+ const ListItemMedia = React.forwardRef<HTMLDivElement, ListItemMediaProps>(
292
+ ({ className, variant, ...props }, ref) => (
188
293
  <div
189
294
  ref={ref}
190
- className={cn("shrink-0", className)}
295
+ className={cn(listItemMediaVariants({ variant }), className)}
191
296
  data-slot="item-media"
297
+ data-variant={variant ?? "default"}
192
298
  {...props}
193
299
  />
194
300
  )
195
301
  );
196
- ItemMedia.displayName = "ItemMedia";
302
+ ListItemMedia.displayName = "ListItemMedia";
197
303
 
198
304
  /* -------------------------------------------------------------------------------------------------
199
- * ItemContent
305
+ * ListItemContent
200
306
  * -----------------------------------------------------------------------------------------------*/
201
307
 
202
- /** Props for the ItemContent sub-component — flexible content area within an Item. */
203
- export type ItemContentProps = React.ComponentProps<"div">;
308
+ /** Props for the ListItemContent sub-component — flexible content area within an ListItem. */
309
+ export type ListItemContentProps = React.ComponentProps<"div">;
204
310
 
205
311
  /**
206
312
  * Flexible content area that grows to fill available space.
207
- * Place ItemTitle and ItemDescription inside.
313
+ * Place ListItemTitle and ListItemDescription inside.
208
314
  */
209
- const ItemContent = React.forwardRef<HTMLDivElement, ItemContentProps>(
315
+ const ListItemContent = React.forwardRef<HTMLDivElement, ListItemContentProps>(
210
316
  ({ className, ...props }, ref) => (
211
317
  <div
212
318
  ref={ref}
213
- className={cn("flex flex-1 flex-col gap-1", className)}
319
+ className={cn("flex min-w-0 flex-1 flex-col gap-1", className)}
214
320
  data-slot="item-content"
215
321
  {...props}
216
322
  />
217
323
  )
218
324
  );
219
- ItemContent.displayName = "ItemContent";
325
+ ListItemContent.displayName = "ListItemContent";
220
326
 
221
327
  /* -------------------------------------------------------------------------------------------------
222
- * ItemTitle
328
+ * Truncated text (shared by ListItemTitle and ListItemDescription)
223
329
  * -----------------------------------------------------------------------------------------------*/
224
330
 
225
- /** Props for the ItemTitle sub-component — primary text label within an Item. */
226
- export type ItemTitleProps = React.ComponentProps<"div">;
331
+ /** The pressable row parts whose keyboard focus also reveals a cut-off text. */
332
+ const PRESSABLE_ROW_SELECTOR =
333
+ '[data-slot="item-button"], [data-slot="item-link"]';
227
334
 
228
335
  /**
229
- * Primary text label within an Item.
336
+ * Whether the element's text is clamped (cut off past its second line).
337
+ * Measured in a ResizeObserver callback, so it follows the element's width and
338
+ * runs again when the text changes (a MutationObserver re-observes).
230
339
  */
231
- const ItemTitle = React.forwardRef<HTMLDivElement, ItemTitleProps>(
232
- ({ className, ...props }, ref) => (
233
- <div
234
- ref={ref}
235
- className={cn("text-foreground text-body", className)}
236
- data-slot="item-title"
237
- {...props}
238
- />
239
- )
340
+ function useIsClamped(el: HTMLElement | null, enabled: boolean) {
341
+ const [clamped, setClamped] = React.useState(false);
342
+
343
+ React.useEffect(() => {
344
+ if (!enabled || !el) return;
345
+ const measure = () =>
346
+ setClamped(
347
+ el.scrollHeight > el.clientHeight + 1 ||
348
+ el.scrollWidth > el.clientWidth + 1
349
+ );
350
+ // ResizeObserver fires once on observe, so the first measure is async.
351
+ const resize = new ResizeObserver(measure);
352
+ resize.observe(el);
353
+ const mutation = new MutationObserver(measure);
354
+ mutation.observe(el, {
355
+ characterData: true,
356
+ childList: true,
357
+ subtree: true,
358
+ });
359
+ return () => {
360
+ resize.disconnect();
361
+ mutation.disconnect();
362
+ };
363
+ }, [enabled, el]);
364
+
365
+ return enabled && el !== null && clamped;
366
+ }
367
+
368
+ /**
369
+ * Keyboard focus on the row's ListItemButton / ListItemLink. The text itself is
370
+ * never a tab stop: the row stays one interactive target, and focusing it
371
+ * shows the full text of whatever is clamped inside it.
372
+ */
373
+ function useRowFocusVisible(el: HTMLElement | null, enabled: boolean) {
374
+ const [focusedRow, setFocusedRow] = React.useState<Element | null>(null);
375
+ const row = enabled ? (el?.closest(PRESSABLE_ROW_SELECTOR) ?? null) : null;
376
+
377
+ React.useEffect(() => {
378
+ if (!row) return;
379
+ const onFocus = () =>
380
+ setFocusedRow(
381
+ row === document.activeElement && row.matches(":focus-visible")
382
+ ? row
383
+ : null
384
+ );
385
+ const onBlur = () => setFocusedRow(null);
386
+ // The row may already hold focus when the listeners go in (it was
387
+ // focused before the text became clamped), so read the current state too.
388
+ onFocus();
389
+ row.addEventListener("focus", onFocus);
390
+ row.addEventListener("blur", onBlur);
391
+ return () => {
392
+ row.removeEventListener("focus", onFocus);
393
+ row.removeEventListener("blur", onBlur);
394
+ };
395
+ }, [row]);
396
+
397
+ return row !== null && focusedRow === row;
398
+ }
399
+
400
+ type TruncatableTextProps = React.ComponentProps<"div"> & {
401
+ asChild?: boolean;
402
+ truncate?: boolean;
403
+ partSlot: "item-title" | "item-description";
404
+ tooltipSide: "top" | "bottom";
405
+ };
406
+
407
+ /**
408
+ * Renders the text, and when `truncate` is on and the text runs past two
409
+ * lines (clamped with an ellipsis), wraps it in a Tooltip with the full text. Hover opens it with a
410
+ * mouse; keyboard focus on the row opens it; a tap opens it only when the
411
+ * text is not inside a button, link or label, so a tap on a pressable row
412
+ * still does what the row does. The full text stays in the DOM for screen
413
+ * readers, so nothing extra is announced.
414
+ */
415
+ const TruncatableText = React.forwardRef<HTMLDivElement, TruncatableTextProps>(
416
+ (
417
+ {
418
+ asChild = false,
419
+ truncate = false,
420
+ partSlot,
421
+ tooltipSide,
422
+ className,
423
+ children,
424
+ ...props
425
+ },
426
+ forwardedRef
427
+ ) => {
428
+ // The node lives in state, not a ref: wrapping the text in the Tooltip
429
+ // remounts it, and the observers must follow the new node.
430
+ const [node, setNode] = React.useState<HTMLDivElement | null>(null);
431
+ const setRefs = React.useCallback(
432
+ (el: HTMLDivElement | null) => {
433
+ setNode(el);
434
+ if (typeof forwardedRef === "function") forwardedRef(el);
435
+ else if (forwardedRef) forwardedRef.current = el;
436
+ },
437
+ [forwardedRef]
438
+ );
439
+ const truncated = useIsClamped(node, truncate);
440
+ const rowFocused = useRowFocusVisible(node, truncated);
441
+ const [hoverOpen, setHoverOpen] = React.useState(false);
442
+ // Escape closes the tooltip even while the row keeps focus; it stays
443
+ // closed until the next focus or hover asks for it again.
444
+ const [dismissed, setDismissed] = React.useState(false);
445
+ const [prevRowFocused, setPrevRowFocused] = React.useState(rowFocused);
446
+ if (rowFocused !== prevRowFocused) {
447
+ setPrevRowFocused(rowFocused);
448
+ if (rowFocused) setDismissed(false);
449
+ }
450
+
451
+ const Comp = asChild ? Slot : "div";
452
+ const text = (
453
+ <Comp
454
+ ref={setRefs}
455
+ className={cn(truncate && "line-clamp-2", className)}
456
+ data-slot={partSlot}
457
+ data-truncated={truncated ? "" : undefined}
458
+ {...props}
459
+ >
460
+ {children}
461
+ </Comp>
462
+ );
463
+
464
+ if (!truncated) return text;
465
+
466
+ return (
467
+ <Tooltip
468
+ open={!dismissed && (hoverOpen || rowFocused)}
469
+ onOpenChange={(open) => {
470
+ if (open) setDismissed(false);
471
+ setHoverOpen(open);
472
+ }}
473
+ >
474
+ <TooltipTrigger
475
+ asChild
476
+ onPointerDown={(event) => {
477
+ // Inside a button, link or label a tap belongs to that control:
478
+ // stop the tooltip from claiming it. The click still fires.
479
+ const target = event.currentTarget as HTMLElement;
480
+ if (
481
+ event.pointerType === "touch" &&
482
+ (target.closest("button, a, label") || target.tagName === "LABEL")
483
+ ) {
484
+ event.preventDefault();
485
+ }
486
+ }}
487
+ >
488
+ {text}
489
+ </TooltipTrigger>
490
+ <TooltipContent
491
+ dataHook={`list-${partSlot}-tooltip`}
492
+ side={tooltipSide}
493
+ sideOffset={4}
494
+ onEscapeKeyDown={() => setDismissed(true)}
495
+ >
496
+ {children}
497
+ </TooltipContent>
498
+ </Tooltip>
499
+ );
500
+ }
240
501
  );
241
- ItemTitle.displayName = "ItemTitle";
502
+ TruncatableText.displayName = "TruncatableText";
242
503
 
243
504
  /* -------------------------------------------------------------------------------------------------
244
- * ItemDescription
505
+ * ListItemTitle
245
506
  * -----------------------------------------------------------------------------------------------*/
246
507
 
247
- /** Props for the ItemDescription sub-component — supporting text beneath ItemTitle. */
248
- export type ItemDescriptionProps = React.ComponentProps<"div">;
508
+ /** Props for the ListItemTitle sub-component — primary text label within a ListItem. */
509
+ export type ListItemTitleProps = React.ComponentProps<"div"> & {
510
+ /**
511
+ * Render as the child element, e.g. a `<label>` that names the row's Switch.
512
+ * Works together with `truncate`.
513
+ */
514
+ asChild?: boolean;
515
+ /**
516
+ * Wrap the title to at most two lines and clamp the rest with an ellipsis.
517
+ * When it is clamped, hovering it (or focusing the row's ListItemButton /
518
+ * ListItemLink) shows the full title in a Tooltip. Two lines that fit get
519
+ * no tooltip.
520
+ * @default false
521
+ */
522
+ truncate?: boolean;
523
+ };
249
524
 
250
525
  /**
251
- * Supporting description text beneath ItemTitle.
526
+ * Primary text label within a ListItem.
252
527
  */
253
- const ItemDescription = React.forwardRef<HTMLDivElement, ItemDescriptionProps>(
528
+ const ListItemTitle = React.forwardRef<HTMLDivElement, ListItemTitleProps>(
254
529
  ({ className, ...props }, ref) => (
255
- <div
530
+ <TruncatableText
256
531
  ref={ref}
257
- className={cn("text-body-sm text-muted-foreground", className)}
258
- data-slot="item-description"
532
+ className={cn("text-foreground text-body", className)}
533
+ partSlot="item-title"
534
+ tooltipSide="top"
259
535
  {...props}
260
536
  />
261
537
  )
262
538
  );
263
- ItemDescription.displayName = "ItemDescription";
539
+ ListItemTitle.displayName = "ListItemTitle";
540
+
541
+ /* -------------------------------------------------------------------------------------------------
542
+ * ListItemDescription
543
+ * -----------------------------------------------------------------------------------------------*/
544
+
545
+ /** Props for the ListItemDescription sub-component — supporting text beneath ListItemTitle. */
546
+ export type ListItemDescriptionProps = React.ComponentProps<"div"> & {
547
+ /**
548
+ * Wrap the description to at most two lines and clamp the rest with an
549
+ * ellipsis. When it is clamped, hovering it (or focusing the row's
550
+ * ListItemButton / ListItemLink) shows the full text in a Tooltip. Two lines
551
+ * that fit get no tooltip.
552
+ * @default false
553
+ */
554
+ truncate?: boolean;
555
+ };
556
+
557
+ /**
558
+ * Supporting description text beneath ListItemTitle.
559
+ */
560
+ const ListItemDescription = React.forwardRef<
561
+ HTMLDivElement,
562
+ ListItemDescriptionProps
563
+ >(({ className, ...props }, ref) => (
564
+ <TruncatableText
565
+ ref={ref}
566
+ className={cn("text-body-sm text-muted-foreground", className)}
567
+ partSlot="item-description"
568
+ tooltipSide="bottom"
569
+ {...props}
570
+ />
571
+ ));
572
+ ListItemDescription.displayName = "ListItemDescription";
264
573
 
265
574
  /* -------------------------------------------------------------------------------------------------
266
- * ItemActions
575
+ * ListItemActions
267
576
  * -----------------------------------------------------------------------------------------------*/
268
577
 
269
- /** Props for the ItemActions sub-component — right-side slot for action controls. */
270
- export type ItemActionsProps = React.ComponentProps<"div">;
578
+ /** Props for the ListItemActions sub-component — right-side slot for action controls. */
579
+ export type ListItemActionsProps = React.ComponentProps<"div">;
271
580
 
272
581
  /**
273
- * Right-side slot for action controls such as remove buttons.
582
+ * Right-side slot for trailing content: an icon button, a menu, a Switch, a
583
+ * Badge or Status, a text Button, or several of them side by side. It is at
584
+ * least 36px square, so a single icon button keeps its place.
274
585
  */
275
- const ItemActions = React.forwardRef<HTMLDivElement, ItemActionsProps>(
586
+ const ListItemActions = React.forwardRef<HTMLDivElement, ListItemActionsProps>(
276
587
  ({ className, ...props }, ref) => (
277
588
  <div
278
589
  ref={ref}
279
590
  className={cn(
280
- "text-muted-foreground flex size-9 shrink-0 items-center justify-center rounded-full",
591
+ "text-muted-foreground flex min-h-9 min-w-9 shrink-0 items-center justify-center gap-2",
281
592
  className
282
593
  )}
283
594
  data-slot="item-actions"
@@ -285,14 +596,14 @@ const ItemActions = React.forwardRef<HTMLDivElement, ItemActionsProps>(
285
596
  />
286
597
  )
287
598
  );
288
- ItemActions.displayName = "ItemActions";
599
+ ListItemActions.displayName = "ListItemActions";
289
600
 
290
601
  /* -------------------------------------------------------------------------------------------------
291
- * ItemSubheader
602
+ * ListSubheader
292
603
  * -----------------------------------------------------------------------------------------------*/
293
604
 
294
- /** Props for the ItemSubheader sub-component — section heading within a List. */
295
- export type ItemSubheaderProps = React.ComponentProps<"li"> & {
605
+ /** Props for the ListSubheader sub-component — section heading within a List. */
606
+ export type ListSubheaderProps = React.ComponentProps<"li"> & {
296
607
  /**
297
608
  * Data hook for automated testing.
298
609
  */
@@ -306,12 +617,12 @@ export type ItemSubheaderProps = React.ComponentProps<"li"> & {
306
617
  * @example
307
618
  * ```tsx
308
619
  * <List dataHook="actions-list">
309
- * <ItemSubheader>Suggestions</ItemSubheader>
310
- * <Item variant="default" dataHook="item-1">...</Item>
620
+ * <ListSubheader>Suggestions</ListSubheader>
621
+ * <ListItem variant="default" dataHook="item-1">...</ListItem>
311
622
  * </List>
312
623
  * ```
313
624
  */
314
- const ItemSubheader = React.forwardRef<HTMLLIElement, ItemSubheaderProps>(
625
+ const ListSubheader = React.forwardRef<HTMLLIElement, ListSubheaderProps>(
315
626
  ({ className, dataHook, ...props }, ref) => (
316
627
  <li
317
628
  ref={ref}
@@ -335,7 +646,304 @@ const ItemSubheader = React.forwardRef<HTMLLIElement, ItemSubheaderProps>(
335
646
  />
336
647
  )
337
648
  );
338
- ItemSubheader.displayName = "ItemSubheader";
649
+ ListSubheader.displayName = "ListSubheader";
650
+
651
+ /* -------------------------------------------------------------------------------------------------
652
+ * ListItemButton / ListItemLink
653
+ * -----------------------------------------------------------------------------------------------*/
654
+
655
+ /* The pressable part of a row. The ListItem stays the <li>, so the list keeps its
656
+ semantics, and this fills it: it takes over the row's padding and gap
657
+ (ListItem drops its own padding while it holds one) and carries the hover and
658
+ focus states. Align follows the parent ListItem through data-align. */
659
+ const listItemPressableClasses = [
660
+ "flex",
661
+ "w-full",
662
+ "min-w-0",
663
+ "items-center",
664
+ "group-data-[align=start]/item:items-start",
665
+ "gap-4",
666
+ "rounded-[inherit]",
667
+ "py-2",
668
+ "pr-2",
669
+ "pl-4",
670
+ "text-left",
671
+ "cursor-pointer",
672
+ "outline-none",
673
+ "hover:bg-accent",
674
+ "focus-visible:shadow-default",
675
+ "transition-colors",
676
+ "duration-fast",
677
+ "ease-out",
678
+ "disabled:pointer-events-none",
679
+ "disabled:cursor-not-allowed",
680
+ "disabled:opacity-50",
681
+ "aria-disabled:pointer-events-none",
682
+ "aria-disabled:cursor-not-allowed",
683
+ "aria-disabled:opacity-50",
684
+ ];
685
+
686
+ /**
687
+ * A row marked `aria-disabled` stays focusable (so it is still announced), but
688
+ * must not activate. Enter on a button or link fires a click, so blocking the
689
+ * click covers keyboard and pointer. It runs in the capture phase, before any
690
+ * child handler (a router link under `asChild`), and router links skip
691
+ * navigation once the default is prevented.
692
+ */
693
+ function blockDisabledClick(
694
+ event: React.MouseEvent<HTMLElement>,
695
+ onClickCapture?: React.MouseEventHandler<HTMLElement>
696
+ ) {
697
+ const disabled = event.currentTarget.getAttribute("aria-disabled");
698
+ if (disabled === "true" || disabled === "") {
699
+ event.preventDefault();
700
+ event.stopPropagation();
701
+ return;
702
+ }
703
+ onClickCapture?.(event);
704
+ }
705
+
706
+ /** Props for ListItemButton — a row that runs an action (opens a sheet, a drill-down level). */
707
+ export type ListItemButtonProps = React.ComponentProps<"button"> & {
708
+ /**
709
+ * Data hook for automated testing.
710
+ */
711
+ dataHook?: string;
712
+ /**
713
+ * Tracking element identifier for analytics.
714
+ */
715
+ trackingEl?: string;
716
+ /**
717
+ * Tracking label for analytics context.
718
+ */
719
+ trackingLabel?: string;
720
+ };
721
+
722
+ /**
723
+ * Makes the whole row a button. Place it as the only child of an ListItem and put
724
+ * the row's parts (ListItemMedia, ListItemContent, ListItemValue, ListItemChevron) inside it.
725
+ *
726
+ * @example
727
+ * ```tsx
728
+ * <ListItem variant="default" dataHook="location">
729
+ * <ListItemButton dataHook="location-row" onClick={open}>
730
+ * <ListItemContent><ListItemTitle>Location</ListItemTitle></ListItemContent>
731
+ * <ListItemValue>London, UK</ListItemValue>
732
+ * <ListItemChevron />
733
+ * </ListItemButton>
734
+ * </ListItem>
735
+ * ```
736
+ */
737
+ const ListItemButton = React.forwardRef<HTMLButtonElement, ListItemButtonProps>(
738
+ (
739
+ {
740
+ className,
741
+ type = "button",
742
+ dataHook,
743
+ trackingEl,
744
+ trackingLabel,
745
+ onClickCapture,
746
+ ...props
747
+ },
748
+ ref
749
+ ) => (
750
+ <button
751
+ ref={ref}
752
+ className={cn(listItemPressableClasses, className)}
753
+ data-hook={dataHook}
754
+ data-slot="item-button"
755
+ data-tracking-el={trackingEl}
756
+ data-tracking-label={trackingLabel}
757
+ type={type}
758
+ onClickCapture={(event) => blockDisabledClick(event, onClickCapture)}
759
+ {...props}
760
+ />
761
+ )
762
+ );
763
+ ListItemButton.displayName = "ListItemButton";
764
+
765
+ /** Props for ListItemLink — a row that navigates. */
766
+ export type ListItemLinkProps = React.ComponentProps<"a"> & {
767
+ /**
768
+ * Render as the child element, e.g. a router `<Link>`.
769
+ */
770
+ asChild?: boolean;
771
+ /**
772
+ * Data hook for automated testing.
773
+ */
774
+ dataHook?: string;
775
+ /**
776
+ * Tracking element identifier for analytics.
777
+ */
778
+ trackingEl?: string;
779
+ /**
780
+ * Tracking label for analytics context.
781
+ */
782
+ trackingLabel?: string;
783
+ };
784
+
785
+ /**
786
+ * Makes the whole row a link. Place it as the only child of an ListItem; use
787
+ * `asChild` to render a router link.
788
+ *
789
+ * @example
790
+ * ```tsx
791
+ * <ListItem variant="outline" dataHook="billing">
792
+ * <ListItemLink asChild dataHook="billing-link">
793
+ * <NextLink href="/settings/billing">
794
+ * <ListItemContent><ListItemTitle>Billing</ListItemTitle></ListItemContent>
795
+ * <ListItemChevron />
796
+ * </NextLink>
797
+ * </ListItemLink>
798
+ * </ListItem>
799
+ * ```
800
+ */
801
+ const ListItemLink = React.forwardRef<HTMLAnchorElement, ListItemLinkProps>(
802
+ (
803
+ {
804
+ className,
805
+ asChild = false,
806
+ dataHook,
807
+ trackingEl,
808
+ trackingLabel,
809
+ onClickCapture,
810
+ ...props
811
+ },
812
+ ref
813
+ ) => {
814
+ const Comp = asChild ? Slot : "a";
815
+ return (
816
+ <Comp
817
+ ref={ref}
818
+ className={cn(listItemPressableClasses, className)}
819
+ data-hook={dataHook}
820
+ data-slot="item-link"
821
+ data-tracking-el={trackingEl}
822
+ data-tracking-label={trackingLabel}
823
+ onClickCapture={(event: React.MouseEvent<HTMLAnchorElement>) =>
824
+ blockDisabledClick(event, onClickCapture)
825
+ }
826
+ {...props}
827
+ />
828
+ );
829
+ }
830
+ );
831
+ ListItemLink.displayName = "ListItemLink";
832
+
833
+ /* -------------------------------------------------------------------------------------------------
834
+ * ListItemValue
835
+ * -----------------------------------------------------------------------------------------------*/
836
+
837
+ /** Props for ListItemValue — the current value shown at the end of a drill-down row. */
838
+ export type ListItemValueProps = React.ComponentProps<"span">;
839
+
840
+ /**
841
+ * The row's current value, before the chevron: muted, right-aligned, and cut
842
+ * off with an ellipsis past half the row so the title always keeps its room.
843
+ */
844
+ const ListItemValue = React.forwardRef<HTMLSpanElement, ListItemValueProps>(
845
+ ({ className, ...props }, ref) => (
846
+ <span
847
+ ref={ref}
848
+ className={cn(
849
+ "text-muted-foreground text-body-sm max-w-1/2 min-w-0 shrink truncate text-right",
850
+ className
851
+ )}
852
+ data-slot="item-value"
853
+ {...props}
854
+ />
855
+ )
856
+ );
857
+ ListItemValue.displayName = "ListItemValue";
858
+
859
+ /* -------------------------------------------------------------------------------------------------
860
+ * ListItemChevron
861
+ * -----------------------------------------------------------------------------------------------*/
862
+
863
+ /** Props for ListItemChevron — the trailing arrow of a row that opens something. */
864
+ export type ListItemChevronProps = React.ComponentProps<typeof ChevronRight>;
865
+
866
+ /**
867
+ * Trailing chevron for a row that navigates or drills down. Decorative: the
868
+ * row's button or link carries the meaning.
869
+ */
870
+ const ListItemChevron = React.forwardRef<SVGSVGElement, ListItemChevronProps>(
871
+ ({ className, ...props }, ref) => (
872
+ <ChevronRight
873
+ ref={ref}
874
+ aria-hidden
875
+ className={cn("text-muted-foreground shrink-0", className)}
876
+ data-slot="item-chevron"
877
+ {...props}
878
+ />
879
+ )
880
+ );
881
+ ListItemChevron.displayName = "ListItemChevron";
882
+
883
+ /* -------------------------------------------------------------------------------------------------
884
+ * ListSeparator
885
+ * -----------------------------------------------------------------------------------------------*/
886
+
887
+ /** Props for ListSeparator — a hairline between two rows or groups. */
888
+ export type ListSeparatorProps = React.ComponentProps<"li">;
889
+
890
+ /**
891
+ * A hairline between rows. Hidden from assistive tech so the list's item
892
+ * count stays the number of rows. For a line between every row, use
893
+ * `<List divided>` instead.
894
+ */
895
+ const ListSeparator = React.forwardRef<HTMLLIElement, ListSeparatorProps>(
896
+ ({ className, ...props }, ref) => (
897
+ <li
898
+ ref={ref}
899
+ aria-hidden
900
+ className={cn("bg-border h-px w-full shrink-0", className)}
901
+ data-slot="item-separator"
902
+ {...props}
903
+ />
904
+ )
905
+ );
906
+ ListSeparator.displayName = "ListSeparator";
907
+
908
+ /* -------------------------------------------------------------------------------------------------
909
+ * Exports
910
+ * -----------------------------------------------------------------------------------------------*/
911
+
912
+ /* -------------------------------------------------------------------------------------------------
913
+ * Deprecated names (removed in 4.0)
914
+ * -----------------------------------------------------------------------------------------------*/
915
+
916
+ /** @deprecated Use `ListItem`. Removed in 4.0. */
917
+ const Item = ListItem;
918
+ /** @deprecated Use `ListItemMedia`. Removed in 4.0. */
919
+ const ItemMedia = ListItemMedia;
920
+ /** @deprecated Use `ListItemContent`. Removed in 4.0. */
921
+ const ItemContent = ListItemContent;
922
+ /** @deprecated Use `ListItemTitle`. Removed in 4.0. */
923
+ const ItemTitle = ListItemTitle;
924
+ /** @deprecated Use `ListItemDescription`. Removed in 4.0. */
925
+ const ItemDescription = ListItemDescription;
926
+ /** @deprecated Use `ListItemActions`. Removed in 4.0. */
927
+ const ItemActions = ListItemActions;
928
+ /** @deprecated Use `ListSubheader`. Removed in 4.0. */
929
+ const ItemSubheader = ListSubheader;
930
+ /** @deprecated Use `listItemVariants`. Removed in 4.0. */
931
+ const itemVariants = listItemVariants;
932
+
933
+ /** @deprecated Use `ListItemProps`. Removed in 4.0. */
934
+ export type ItemProps = ListItemProps;
935
+ /** @deprecated Use `ListItemMediaProps`. Removed in 4.0. */
936
+ export type ItemMediaProps = ListItemMediaProps;
937
+ /** @deprecated Use `ListItemContentProps`. Removed in 4.0. */
938
+ export type ItemContentProps = ListItemContentProps;
939
+ /** @deprecated Use `ListItemTitleProps`. Removed in 4.0. */
940
+ export type ItemTitleProps = ListItemTitleProps;
941
+ /** @deprecated Use `ListItemDescriptionProps`. Removed in 4.0. */
942
+ export type ItemDescriptionProps = ListItemDescriptionProps;
943
+ /** @deprecated Use `ListItemActionsProps`. Removed in 4.0. */
944
+ export type ItemActionsProps = ListItemActionsProps;
945
+ /** @deprecated Use `ListSubheaderProps`. Removed in 4.0. */
946
+ export type ItemSubheaderProps = ListSubheaderProps;
339
947
 
340
948
  /* -------------------------------------------------------------------------------------------------
341
949
  * Exports
@@ -343,6 +951,21 @@ ItemSubheader.displayName = "ItemSubheader";
343
951
 
344
952
  export {
345
953
  List,
954
+ ListItem,
955
+ ListItemButton,
956
+ ListItemLink,
957
+ ListItemMedia,
958
+ ListItemContent,
959
+ ListItemTitle,
960
+ ListItemDescription,
961
+ ListItemValue,
962
+ ListItemChevron,
963
+ ListItemActions,
964
+ ListSubheader,
965
+ ListSeparator,
966
+ listVariants,
967
+ listItemVariants,
968
+ listItemMediaVariants,
346
969
  Item,
347
970
  ItemMedia,
348
971
  ItemContent,