@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
@@ -48,8 +48,36 @@ declare module "@tanstack/react-table" {
48
48
  width?: string;
49
49
  /** Minimum column width (e.g., "100px", "8rem"). */
50
50
  minWidth?: string;
51
+ /**
52
+ * This column starts a column group (DS-1195): its body cells draw a
53
+ * separator on their start edge. The header band stays clean.
54
+ */
55
+ groupStart?: boolean;
56
+ /**
57
+ * Pin the column to the left edge while the table scrolls sideways
58
+ * (DS-1205). Pin ONE column — the first, normally; two pinned columns
59
+ * would stack on the same edge. The pinned header and body cells get an
60
+ * opaque background that follows the row state (selected, expanded,
61
+ * sub-row) and a divider on the pinned edge. Only has a visible effect
62
+ * when the table scrolls horizontally (`minWidth`).
63
+ */
64
+ pinned?: "left";
51
65
  }
52
66
  }
67
+
68
+ /**
69
+ * Sticky classes for a pinned column (DS-1205). `shadow` draws the divider
70
+ * inside the cell — a border would not travel with a sticky cell under
71
+ * `border-collapse`. Header cells sit one layer above body cells so a row
72
+ * never paints over the pinned header while scrolling; the body background
73
+ * reads `--dt-row-bg`, which each row sets to its own opaque surface.
74
+ */
75
+ const PINNED_CELL_BASE = "sticky left-0 shadow-[inset_-1px_0_0_var(--border)]";
76
+ const PINNED_HEAD_CLASS = cn(PINNED_CELL_BASE, "z-2");
77
+ const PINNED_BODY_CLASS = cn(
78
+ PINNED_CELL_BASE,
79
+ "z-1 bg-(--dt-row-bg,var(--background))"
80
+ );
53
81
  import { useVirtualizer } from "@tanstack/react-virtual";
54
82
  import {
55
83
  ArrowDown,
@@ -57,10 +85,12 @@ import {
57
85
  ArrowUpDown,
58
86
  ChevronRight,
59
87
  Search,
88
+ SearchX,
60
89
  } from "@brightlocal/icons";
61
90
 
62
91
  import { cn } from "@brightlocal/ui-components/lib/utils";
63
92
  import { useIsBelowBreakpoint } from "@brightlocal/ui-components/hooks/use-breakpoint";
93
+ import { useControllable } from "../lib/use-controllable";
64
94
  import { Button } from "./button";
65
95
  import { Checkbox } from "./checkbox";
66
96
  import {
@@ -79,64 +109,31 @@ import {
79
109
  PaginationPrevious,
80
110
  usePagination,
81
111
  } from "./pagination";
112
+ import { ResultCount } from "./result-count";
82
113
  import { Skeleton } from "./skeleton";
83
114
  import { Spinner } from "./spinner";
115
+ import { EmptyState } from "../blocks/empty-state";
84
116
  import {
85
117
  Table,
86
118
  TableBody,
87
119
  TableCell,
120
+ TableEmpty,
88
121
  TableHead,
89
122
  TableHeader,
90
123
  TableRow,
91
- scrollRegionProps,
92
124
  } from "./table";
125
+ import {
126
+ TABLE_ROW_MIN_HEIGHT,
127
+ scrollRegionProps,
128
+ type TableFrame,
129
+ type TableSize,
130
+ } from "../lib/table-internal";
93
131
  import { TypographyMuted } from "./typography";
94
132
 
95
133
  /* -------------------------------------------------------------------------------------------------
96
134
  * useDataTable (hook)
97
135
  * -----------------------------------------------------------------------------------------------*/
98
136
 
99
- /**
100
- * Controlled/uncontrolled state helper.
101
- *
102
- * Resolves a "controlled or internal" value and returns a setter compatible
103
- * with TanStack Table's `SetStateAction<T>` updater signature. When the
104
- * `controlled` value is defined, the parent owns state and `onChange` is
105
- * called with the next value. When undefined, state is kept internally and
106
- * `onChange` is still invoked (the common "notify but self-manage" pattern).
107
- */
108
- function useControllable<T>(
109
- controlled: T | undefined,
110
- initialValue: T,
111
- onChange?: (next: T) => void
112
- ): [T, (updater: T | ((prev: T) => T)) => void] {
113
- const [internal, setInternal] = React.useState<T>(initialValue);
114
- const value = controlled !== undefined ? controlled : internal;
115
-
116
- const valueRef = React.useRef(value);
117
- React.useEffect(() => {
118
- valueRef.current = value;
119
- });
120
-
121
- const isControlled = controlled !== undefined;
122
-
123
- const setValue = React.useCallback(
124
- (updater: T | ((prev: T) => T)) => {
125
- const next =
126
- typeof updater === "function"
127
- ? (updater as (prev: T) => T)(valueRef.current)
128
- : updater;
129
- if (!isControlled) {
130
- setInternal(next);
131
- }
132
- onChange?.(next);
133
- },
134
- [isControlled, onChange]
135
- );
136
-
137
- return [value, setValue];
138
- }
139
-
140
137
  /**
141
138
  * Configuration for `useDataTable`.
142
139
  *
@@ -200,7 +197,11 @@ export interface UseDataTableOptions<TData> {
200
197
  enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
201
198
  /** Enable client-side pagination. @default false */
202
199
  enablePagination?: boolean;
203
- /** Initial page size when pagination is enabled. @default 10 */
200
+ /**
201
+ * Initial page size when pagination is enabled. The Filtering pattern's
202
+ * 20 rows a page; pass 10 when two tables share a page.
203
+ * @default 20
204
+ */
204
205
  pageSize?: number;
205
206
 
206
207
  // ---------- Server-side / manual modes ----------
@@ -331,7 +332,7 @@ export function useDataTable<TData>(
331
332
  enableGlobalFiltering = false,
332
333
  enableRowSelection = false,
333
334
  enablePagination = false,
334
- pageSize = 10,
335
+ pageSize = 20,
335
336
  manualSorting = false,
336
337
  manualFiltering = false,
337
338
  manualPagination = false,
@@ -493,6 +494,36 @@ export interface DataTableProps<TData> {
493
494
  trackingEl?: string;
494
495
  /** Analytics label. */
495
496
  trackingLabel?: string;
497
+ /**
498
+ * Row density, passed through to the underlying `Table` (DS-556):
499
+ * `default` rows are `h-12` (48px) under `h-12` (48px) column headers;
500
+ * `sm` rows are `h-10` (40px) under `h-9` (36px) headers. Rows still grow
501
+ * with multi-line content, and a row hosting an expander or icon-only
502
+ * action button (`size-9` + the cell's `p-2`) measures 52px at either size.
503
+ * Use `sm` for dense tables inside cards, dialogs and side panels.
504
+ * @default "default"
505
+ */
506
+ size?: TableSize;
507
+ /**
508
+ * Where the frame comes from (DS-1103), passed through to the `Table`.
509
+ * - `"own"` — the view draws its own 1px `border-border`, `rounded-md`
510
+ * frame; cells keep `p-2`. The standalone table.
511
+ * - `"container"` — no border, square corners, and the first/last cell of
512
+ * every row — heads, cells, footer, empty row, skeleton rows — pads to the
513
+ * container's gutter, `var(--content-inset)` (24px in a `data` Card).
514
+ * Use inside `CardContent flush`, a Sheet or a dialog body so the page
515
+ * shows one box and the columns line up with the title; no className
516
+ * override needed. The view stays a focusable scroll region either way.
517
+ * @default "own"
518
+ */
519
+ frame?: TableFrame;
520
+ /**
521
+ * Faint rule under every body row but the last (DS-1195), passed through to
522
+ * the `Table`. For long, dense tables with many numeric or grouped columns;
523
+ * leave off for short or simple tables.
524
+ * @default false
525
+ */
526
+ rowDividers?: boolean;
496
527
  /** Show skeleton rows instead of data while loading async data. */
497
528
  isLoading?: boolean;
498
529
  /**
@@ -521,24 +552,45 @@ export interface DataTableProps<TData> {
521
552
  * @default "Loading results…"
522
553
  */
523
554
  refetchingLabel?: string;
555
+ /**
556
+ * What the polite live region announces to screen readers while
557
+ * `isLoading` is set and the rows are skeletons.
558
+ * @default "Loading data…"
559
+ */
560
+ loadingLabel?: string;
524
561
  /** Number of skeleton rows when loading. Falls back to the table's page size, then 10. */
525
562
  skeletonRowCount?: number;
526
563
  /**
527
- * What the table shows in place of rows when it has none.
564
+ * What the table shows in place of rows when it has none — rendered through
565
+ * `TableEmpty`, announced politely either way.
528
566
  *
529
- * A string is the no-results case — a filter or search that excludes
530
- * everything — and it is announced politely, because the reader's own query
531
- * caused it and they are waiting to hear the outcome.
567
+ * Left unset, the table renders the designed no-results state (Figma
568
+ * `No results`): an `<EmptyState size="md">` with the `SearchX` icon, the
569
+ * global-filter query echoed in the title and one line of description, no
570
+ * action — the reader wants the outcome of their own query, not a CTA.
571
+ * Translate it with `noResultsTitle` / `noResultsDescription`.
532
572
  *
533
- * Pass an `<EmptyState>` for a collection that is empty rather than filtered:
534
- * nothing has been added yet, so the cell needs a title and a way to add the
535
- * first one. The cell brings the block's breathing room with it — do not wrap
536
- * it in a padding element. The block is wrapped in the same live region, so
537
- * keep it to the standard anatomy — its title and one line are worth hearing;
538
- * a wall of copy is not.
539
- * @default "No results."
573
+ * Pass your own `<EmptyState size="md">` for an empty collection (Figma
574
+ * `Empty`): a title, one line and the setup CTA. The cell brings the
575
+ * block's breathing room with it — do not wrap it in a padding element.
576
+ * The block sits in the same live region, so keep it to the standard
577
+ * anatomy — its title and one line are worth hearing; a wall of copy is
578
+ * not. A string renders as a one-line message in an ordinary row.
579
+ * @default the no-results EmptyState
540
580
  */
541
581
  noResultsMessage?: React.ReactNode;
582
+ /**
583
+ * Title of the default no-results state. `{query}` is replaced with the
584
+ * current global-filter value; the plain default is used when there is no
585
+ * query (column filters only).
586
+ * @default "No results for \"{query}\"" with a query, else "No results"
587
+ */
588
+ noResultsTitle?: string;
589
+ /**
590
+ * The one line under the default no-results title.
591
+ * @default "Try a different search, or clear the filters."
592
+ */
593
+ noResultsDescription?: string;
542
594
  /**
543
595
  * Pin the `<thead>` to the top of the component's own scroll container
544
596
  * (the outer wrapper) so column headers remain visible while the rows
@@ -555,9 +607,21 @@ export interface DataTableProps<TData> {
555
607
  * intent is the signal. For the same reason, don't set it on a table
556
608
  * with no height bound: the wrapper never scrolls, and the region
557
609
  * becomes an inert tab stop.
610
+ *
611
+ * `"page"` pins the headings to the page's scroll instead, with no height
612
+ * bound and no inner scroll box (DS-1215) — for long report tables that
613
+ * scroll with the page. The `<thead>` sticks at `--content-sticky-top`,
614
+ * which a `CardHeader sticky` publishes with its live height, so inside
615
+ * such a card the headings stick directly beneath the card header; with
616
+ * no sticky card header they stick at the top of the scrolling page,
617
+ * Sheet or Dialog. The headings stick while the table fits its container;
618
+ * once it is wider (`minWidth`, column `meta.minWidth`, wide content) the
619
+ * wrapper becomes the horizontal scroll region, labelled by
620
+ * `scrollRegionLabel`, and the headings scroll with the page — a sideways
621
+ * scroll box would otherwise trap them.
558
622
  * @default false
559
623
  */
560
- stickyHeader?: boolean;
624
+ stickyHeader?: boolean | "page";
561
625
  /**
562
626
  * Additional class name for the outer wrapper — the component's single
563
627
  * scroll container for both axes. Height bounds belong here: `max-h-*`
@@ -642,6 +706,73 @@ export interface DataTableProps<TData> {
642
706
  renderExpandedContent?: (row: Row<TData>) => React.ReactNode;
643
707
  }
644
708
 
709
+ /**
710
+ * The default `noResultsMessage`: the Figma `No results` state as an
711
+ * `EmptyState` block — `SearchX`, the echoed global-filter query as the title,
712
+ * one line, no action. Composed from the public block (the one place a
713
+ * component renders a block — by decision, so the default and a consumer's
714
+ * own `<EmptyState>` are the same DOM).
715
+ */
716
+ function DataTableNoResults<TData>({
717
+ table,
718
+ dataHook,
719
+ title,
720
+ description,
721
+ }: {
722
+ table: TanStackTable<TData>;
723
+ dataHook: string;
724
+ title?: string;
725
+ description?: string;
726
+ }) {
727
+ const filter = table.getState().globalFilter;
728
+ const query = typeof filter === "string" ? filter.trim() : "";
729
+ const resolvedTitle = (
730
+ title ?? (query ? 'No results for "{query}"' : "No results")
731
+ ).replace("{query}", query);
732
+ return (
733
+ <EmptyState
734
+ dataHook={`${dataHook}-no-results`}
735
+ description={
736
+ description ?? "Try a different search, or clear the filters."
737
+ }
738
+ icon={<SearchX />}
739
+ title={resolvedTitle}
740
+ />
741
+ );
742
+ }
743
+
744
+ /**
745
+ * Whether the table is wider than its view wrapper — `minWidth`, a column's
746
+ * `meta.minWidth` or wide content forces a sideways scroll (DS-1215). Only
747
+ * measured when `enabled` (page-sticky headings); otherwise always `false`. Under
748
+ * `overflow-clip` the table still lays out at its full width, so the
749
+ * comparison holds in both wrapper modes and never oscillates.
750
+ */
751
+ function useTableOverflowing(
752
+ viewRef: React.RefObject<HTMLDivElement | null>,
753
+ enabled: boolean
754
+ ): boolean {
755
+ const [overflowing, setOverflowing] = React.useState(false);
756
+ React.useLayoutEffect(() => {
757
+ const view = viewRef.current;
758
+ const table = view?.querySelector<HTMLElement>('[data-slot="table"]');
759
+ if (!enabled || !view || !table) {
760
+ setOverflowing(false);
761
+ return;
762
+ }
763
+ // Whole pixels on both sides (offsetWidth/clientWidth round), with a 1px
764
+ // tolerance so a sub-pixel full-width table never counts as overflowing.
765
+ const measure = () =>
766
+ setOverflowing(table.offsetWidth > view.clientWidth + 1);
767
+ measure();
768
+ const observer = new ResizeObserver(measure);
769
+ observer.observe(view);
770
+ observer.observe(table);
771
+ return () => observer.disconnect();
772
+ }, [viewRef, enabled]);
773
+ return overflowing;
774
+ }
775
+
645
776
  /**
646
777
  * Generic DataTable renderer.
647
778
  *
@@ -679,28 +810,37 @@ export interface DataTableProps<TData> {
679
810
  * </DataTableToolbar>
680
811
  * </div>
681
812
  */
682
- export function DataTable<TData>({
683
- table,
684
- dataHook,
685
- trackingEl,
686
- trackingLabel,
687
- isLoading = false,
688
- refetching = false,
689
- refetchingLabel,
690
- skeletonRowCount,
691
- noResultsMessage = "No results.",
692
- stickyHeader = false,
693
- className,
694
- layout,
695
- minWidth,
696
- scrollRegionLabel,
697
- footer,
698
- getRowClassName,
699
- renderExpandedContent,
700
- }: DataTableProps<TData>) {
813
+ function DataTableInner<TData>(
814
+ {
815
+ table,
816
+ dataHook,
817
+ trackingEl,
818
+ trackingLabel,
819
+ size = "default",
820
+ frame = "own",
821
+ rowDividers = false,
822
+ isLoading = false,
823
+ refetching = false,
824
+ refetchingLabel,
825
+ loadingLabel,
826
+ skeletonRowCount,
827
+ noResultsMessage,
828
+ noResultsTitle,
829
+ noResultsDescription,
830
+ stickyHeader = false,
831
+ className,
832
+ layout,
833
+ minWidth,
834
+ scrollRegionLabel,
835
+ footer,
836
+ getRowClassName,
837
+ renderExpandedContent,
838
+ }: DataTableProps<TData>,
839
+ ref: React.ForwardedRef<HTMLDivElement>
840
+ ) {
701
841
  const columnCount = table.getVisibleLeafColumns().length;
702
842
  const resolvedSkeletonCount =
703
- skeletonRowCount ?? table.getState().pagination.pageSize ?? 10;
843
+ skeletonRowCount ?? table.getState().pagination.pageSize ?? 20;
704
844
 
705
845
  // A focusable scroll region whenever scrolling is part of the contract:
706
846
  // minWidth (horizontal), stickyHeader, or an explicit scrollRegionLabel
@@ -709,22 +849,48 @@ export function DataTable<TData>({
709
849
  // keyboard users must be able to focus and scroll the rows). One const
710
850
  // gates both the focus classes and the region props so the two can
711
851
  // never drift apart.
712
- const isScrollRegion =
713
- Boolean(minWidth) || stickyHeader || scrollRegionLabel !== undefined;
852
+ const pageSticky = stickyHeader === "page";
853
+ const viewRef = React.useRef<HTMLDivElement>(null);
854
+ React.useImperativeHandle(ref, () => viewRef.current!, []);
855
+ // Measured for every page-sticky table: `minWidth`, a column's
856
+ // `meta.minWidth` or wide cell content can all push it past the view.
857
+ const overflowing = useTableOverflowing(viewRef, pageSticky);
858
+ // Page-sticky headings need a wrapper that is not a scroll container (any
859
+ // `overflow: auto` axis would trap the sticky <thead>), so it only scrolls
860
+ // sideways once the table is actually wider than it (DS-1215) — and is a
861
+ // focusable region exactly then, never an inert tab stop.
862
+ const scrolls = !pageSticky || overflowing;
863
+ const isScrollRegion = pageSticky
864
+ ? overflowing
865
+ : Boolean(minWidth) ||
866
+ stickyHeader === true ||
867
+ scrollRegionLabel !== undefined;
714
868
 
715
869
  return (
716
870
  <div
871
+ ref={viewRef}
717
872
  // `relative`: the sr-only live region below positions absolutely and
718
873
  // must not escape to a distant containing block (double-scrollbar bug).
719
874
  className={cn(
720
875
  // `scrollbar` themes the native scrollbar with DS colors — the same
721
876
  // treatment Command/Combobox lists use for bounded scroll containers.
722
- "border-border scrollbar relative overflow-auto rounded-md border",
877
+ // `overflow-clip` keeps the rounded frame's clip without creating a
878
+ // scroll container, so the page-sticky <thead> sticks to the page.
879
+ "relative",
880
+ scrolls ? "scrollbar overflow-auto" : "overflow-clip",
881
+ // `own`: the 1px frame + rounded clip; `container`: square and
882
+ // frameless — the Card/Sheet/Dialog is the frame (DS-1103).
883
+ frame === "own" && "border-border rounded-md border",
723
884
  isScrollRegion && "focus-visible:shadow-default outline-none",
724
885
  className
725
886
  )}
887
+ data-frame={frame}
726
888
  data-hook={dataHook}
889
+ data-overflowing={pageSticky && overflowing ? "" : undefined}
727
890
  data-slot="data-table-view"
891
+ data-sticky-header={
892
+ stickyHeader === false ? undefined : pageSticky ? "page" : "self"
893
+ }
728
894
  data-tracking-el={trackingEl}
729
895
  data-tracking-label={trackingLabel}
730
896
  {...(isScrollRegion ? scrollRegionProps(scrollRegionLabel) : undefined)}
@@ -741,11 +907,21 @@ export function DataTable<TData>({
741
907
  // by which point its text is gone and nothing is announced.
742
908
  aria-busy={isLoading || refetching || undefined}
743
909
  dataHook={`${dataHook}-table`}
910
+ frame={frame}
744
911
  layout={layout}
745
912
  minWidth={minWidth}
913
+ rowDividers={rowDividers}
746
914
  scrollOwner="parent"
915
+ size={size}
747
916
  >
748
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
917
+ <DataTableHeaderRows
918
+ sticky={
919
+ pageSticky
920
+ ? !overflowing && "page"
921
+ : stickyHeader === true && "self"
922
+ }
923
+ table={table}
924
+ />
749
925
  <TableBody>
750
926
  {isLoading ? (
751
927
  <>
@@ -756,7 +932,7 @@ export function DataTable<TData>({
756
932
  <TableRow className="sr-only">
757
933
  <TableCell colSpan={columnCount}>
758
934
  <div aria-live="polite" role="status">
759
- Loading data…
935
+ {loadingLabel ?? "Loading data…"}
760
936
  </div>
761
937
  </TableCell>
762
938
  </TableRow>
@@ -776,20 +952,16 @@ export function DataTable<TData>({
776
952
  />
777
953
  ))
778
954
  ) : (
779
- <TableRow>
780
- <TableCell align="center" colSpan={columnCount} size="lg">
781
- {/* Padded for a block, not for a line: an `EmptyState` passed
782
- as the message needs the same room here that it gets
783
- anywhere else, and a prop API gives the consumer nowhere
784
- to add it. 24 rather than 32, because this sits inside
785
- the cell's own 8: together they give the block its 32,
786
- and a one-line message still measures under `size="lg"`'s
787
- min-height, so the plain-string row does not move. */}
788
- <div aria-live="polite" className="py-6" role="status">
789
- {noResultsMessage}
790
- </div>
791
- </TableCell>
792
- </TableRow>
955
+ <TableEmpty colSpan={columnCount}>
956
+ {noResultsMessage ?? (
957
+ <DataTableNoResults
958
+ dataHook={dataHook}
959
+ description={noResultsDescription}
960
+ table={table}
961
+ title={noResultsTitle}
962
+ />
963
+ )}
964
+ </TableEmpty>
793
965
  )}
794
966
  </>
795
967
  )}
@@ -801,7 +973,18 @@ export function DataTable<TData>({
801
973
  );
802
974
  }
803
975
 
804
- DataTable.displayName = "DataTable";
976
+ /**
977
+ * Generic DataTable renderer — see `DataTableInner` for the full contract.
978
+ * `ref` is the view wrapper (`data-slot="data-table-view"`), the component's
979
+ * scroll container: scroll it back to the top after a page change, or
980
+ * `scrollIntoView` it. Cast keeps the `TData` generic through `forwardRef`
981
+ * (the Tabs / CommandVirtualList idiom).
982
+ */
983
+ const DataTable = React.forwardRef(DataTableInner) as <TData>(
984
+ props: DataTableProps<TData> & React.RefAttributes<HTMLDivElement>
985
+ ) => React.ReactElement | null;
986
+
987
+ (DataTable as React.FC).displayName = "DataTable";
805
988
 
806
989
  /* -------------------------------------------------------------------------------------------------
807
990
  * Internal: settled-sort override store (DS-916)
@@ -906,15 +1089,26 @@ function useSortOverrideStore(): SortOverrideStore {
906
1089
  */
907
1090
  function DataTableHeaderRows<TData>({
908
1091
  table,
909
- stickyHeader,
1092
+ sticky,
910
1093
  }: {
911
1094
  table: TanStackTable<TData>;
912
- stickyHeader: boolean;
1095
+ /**
1096
+ * `"self"`: the top of the view wrapper's own scroll box. `"page"`: the
1097
+ * outer scroller, beneath whatever publishes `--content-sticky-top` (a
1098
+ * sticky CardHeader), one layer under it so the headings slide behind
1099
+ * the card header when the table scrolls out (DS-1215).
1100
+ */
1101
+ sticky: false | "self" | "page";
913
1102
  }) {
914
1103
  const sortOverrides = useSortOverrideStore();
915
1104
  return (
916
1105
  <DataTableSortOverridesContext.Provider value={sortOverrides}>
917
- <TableHeader className={cn(stickyHeader && "sticky top-0 z-10")}>
1106
+ <TableHeader
1107
+ className={cn(
1108
+ sticky === "self" && "sticky top-0 z-10",
1109
+ sticky === "page" && "sticky top-[var(--content-sticky-top,0px)] z-9"
1110
+ )}
1111
+ >
918
1112
  {table.getHeaderGroups().map((headerGroup) => (
919
1113
  <TableRow key={headerGroup.id}>
920
1114
  {headerGroup.headers.map((header) => (
@@ -965,7 +1159,9 @@ function DataTableHeadCell<TData>({
965
1159
  return (
966
1160
  <TableHead
967
1161
  aria-sort={ariaSort}
1162
+ className={meta?.pinned === "left" ? PINNED_HEAD_CLASS : undefined}
968
1163
  colSpan={header.colSpan}
1164
+ data-pinned={meta?.pinned === "left" ? "left" : undefined}
969
1165
  minWidth={meta?.minWidth}
970
1166
  width={meta?.width}
971
1167
  >
@@ -1020,17 +1216,33 @@ function DataTableRow<TData>({
1020
1216
  // table head's bg-muted at ANY depth; other expanded-zone rows
1021
1217
  // (sub-rows) get the lighter accent wash.
1022
1218
  canExpand && expanded ? "bg-muted" : row.depth > 0 && "bg-accent/50",
1219
+ // Pinned cells are opaque, so they read the row surface from this
1220
+ // variable instead of the row's (possibly translucent) background
1221
+ // — selected, expanded and sub-row states follow through (DS-1205).
1222
+ "data-[state=selected]:[--dt-row-bg:var(--muted)]",
1223
+ canExpand && expanded
1224
+ ? "[--dt-row-bg:var(--muted)]"
1225
+ : row.depth > 0 &&
1226
+ "[--dt-row-bg:color-mix(in_oklab,var(--accent)_50%,var(--background))]",
1023
1227
  getRowClassName?.(row)
1024
1228
  )}
1025
1229
  data-depth={row.depth}
1026
1230
  data-expanded={canExpand ? String(expanded) : undefined}
1027
1231
  data-state={row.getIsSelected() ? "selected" : undefined}
1028
1232
  >
1029
- {row.getVisibleCells().map((cell) => (
1030
- <TableCell key={cell.id}>
1031
- {flexRender(cell.column.columnDef.cell, cell.getContext())}
1032
- </TableCell>
1033
- ))}
1233
+ {row.getVisibleCells().map((cell) => {
1234
+ const pinned = cell.column.columnDef.meta?.pinned === "left";
1235
+ return (
1236
+ <TableCell
1237
+ key={cell.id}
1238
+ className={pinned ? PINNED_BODY_CLASS : undefined}
1239
+ data-pinned={pinned ? "left" : undefined}
1240
+ groupStart={cell.column.columnDef.meta?.groupStart}
1241
+ >
1242
+ {flexRender(cell.column.columnDef.cell, cell.getContext())}
1243
+ </TableCell>
1244
+ );
1245
+ })}
1034
1246
  </TableRow>
1035
1247
  {panel != null && (
1036
1248
  // No data-depth here: panels are not data rows, and sharing the
@@ -1090,8 +1302,15 @@ function LoadingRows({
1090
1302
  */
1091
1303
  export interface VirtualizedDataTableProps<TData> extends Omit<
1092
1304
  DataTableProps<TData>,
1093
- "renderExpandedContent"
1305
+ "renderExpandedContent" | "stickyHeader"
1094
1306
  > {
1307
+ /**
1308
+ * Pin the `<thead>` to the top of the virtualized viewport so column
1309
+ * headers stay visible while the rows scroll. The viewport is always
1310
+ * bounded, so there is no `"page"` mode here.
1311
+ * @default false
1312
+ */
1313
+ stickyHeader?: boolean;
1095
1314
  /**
1096
1315
  * Height of the scroll container in pixels. Required — virtualization
1097
1316
  * needs a bounded viewport. Pass a CSS value via `className` instead
@@ -1101,8 +1320,10 @@ export interface VirtualizedDataTableProps<TData> extends Omit<
1101
1320
  height?: number;
1102
1321
  /**
1103
1322
  * Estimated height of a single row in pixels. The virtualizer uses this
1104
- * for initial layout before measuring real DOM nodes.
1105
- * @default 48
1323
+ * for initial layout before measuring real DOM nodes. Defaults to the
1324
+ * table's row min-height for its `size` — 48 for `default`, 40 for `sm` —
1325
+ * so only tables whose rows routinely wrap need to set it.
1326
+ * @default 48 (`size="default"`) | 40 (`size="sm"`)
1106
1327
  */
1107
1328
  estimateSize?: number;
1108
1329
  /**
@@ -1133,36 +1354,47 @@ export interface VirtualizedDataTableProps<TData> extends Omit<
1133
1354
  * table={table}
1134
1355
  * dataHook="big-table"
1135
1356
  * height={600}
1136
- * estimateSize={48}
1137
1357
  * />
1138
1358
  * );
1139
1359
  */
1140
- export function VirtualizedDataTable<TData>({
1141
- table,
1142
- dataHook,
1143
- trackingEl,
1144
- trackingLabel,
1145
- isLoading = false,
1146
- refetching = false,
1147
- refetchingLabel,
1148
- skeletonRowCount,
1149
- noResultsMessage = "No results.",
1150
- stickyHeader = false,
1151
- className,
1152
- layout,
1153
- minWidth,
1154
- scrollRegionLabel,
1155
- footer,
1156
- getRowClassName,
1157
- height,
1158
- estimateSize = 48,
1159
- overscan = 5,
1160
- }: VirtualizedDataTableProps<TData>) {
1360
+ function VirtualizedDataTableInner<TData>(
1361
+ {
1362
+ table,
1363
+ dataHook,
1364
+ trackingEl,
1365
+ trackingLabel,
1366
+ size = "default",
1367
+ frame = "own",
1368
+ rowDividers = false,
1369
+ isLoading = false,
1370
+ refetching = false,
1371
+ refetchingLabel,
1372
+ loadingLabel,
1373
+ skeletonRowCount,
1374
+ noResultsMessage,
1375
+ noResultsTitle,
1376
+ noResultsDescription,
1377
+ stickyHeader = false,
1378
+ className,
1379
+ layout,
1380
+ minWidth,
1381
+ scrollRegionLabel,
1382
+ footer,
1383
+ getRowClassName,
1384
+ height,
1385
+ estimateSize: estimateSizeProp,
1386
+ overscan = 5,
1387
+ }: VirtualizedDataTableProps<TData>,
1388
+ ref: React.ForwardedRef<HTMLDivElement>
1389
+ ) {
1390
+ const estimateSize = estimateSizeProp ?? TABLE_ROW_MIN_HEIGHT[size];
1161
1391
  const columnCount = table.getVisibleLeafColumns().length;
1162
1392
  const resolvedSkeletonCount =
1163
- skeletonRowCount ?? table.getState().pagination.pageSize ?? 10;
1393
+ skeletonRowCount ?? table.getState().pagination.pageSize ?? 20;
1164
1394
 
1165
1395
  const scrollContainerRef = React.useRef<HTMLDivElement>(null);
1396
+ // The forwarded ref is the same view wrapper the virtualizer scrolls.
1397
+ React.useImperativeHandle(ref, () => scrollContainerRef.current!, []);
1166
1398
 
1167
1399
  const rows = table.getRowModel().rows;
1168
1400
 
@@ -1192,13 +1424,15 @@ export function VirtualizedDataTable<TData>({
1192
1424
  className={cn(
1193
1425
  // `scrollbar` themes the native scrollbar with DS colors (the
1194
1426
  // Command/Combobox treatment for bounded scroll containers).
1195
- "border-border scrollbar relative overflow-auto rounded-md border",
1427
+ "scrollbar relative overflow-auto",
1428
+ frame === "own" && "border-border rounded-md border",
1196
1429
  // Always a focusable scroll region: virtualization requires a
1197
1430
  // bounded viewport (height or a className bound), so this wrapper
1198
1431
  // always scrolls vertically and keyboard users need to reach it.
1199
1432
  "focus-visible:shadow-default outline-none",
1200
1433
  className
1201
1434
  )}
1435
+ data-frame={frame}
1202
1436
  data-hook={dataHook}
1203
1437
  data-slot="data-table-view"
1204
1438
  data-tracking-el={trackingEl}
@@ -1218,11 +1452,14 @@ export function VirtualizedDataTable<TData>({
1218
1452
  // by which point its text is gone and nothing is announced.
1219
1453
  aria-busy={isLoading || refetching || undefined}
1220
1454
  dataHook={`${dataHook}-table`}
1455
+ frame={frame}
1221
1456
  layout={layout}
1222
1457
  minWidth={minWidth}
1458
+ rowDividers={rowDividers}
1223
1459
  scrollOwner="parent"
1460
+ size={size}
1224
1461
  >
1225
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
1462
+ <DataTableHeaderRows sticky={stickyHeader && "self"} table={table} />
1226
1463
  <TableBody>
1227
1464
  {isLoading ? (
1228
1465
  <>
@@ -1233,7 +1470,7 @@ export function VirtualizedDataTable<TData>({
1233
1470
  <TableRow className="sr-only">
1234
1471
  <TableCell colSpan={columnCount}>
1235
1472
  <div aria-live="polite" role="status">
1236
- Loading data…
1473
+ {loadingLabel ?? "Loading data…"}
1237
1474
  </div>
1238
1475
  </TableCell>
1239
1476
  </TableRow>
@@ -1266,15 +1503,16 @@ export function VirtualizedDataTable<TData>({
1266
1503
  )}
1267
1504
  </>
1268
1505
  ) : (
1269
- <TableRow>
1270
- <TableCell align="center" colSpan={columnCount} size="lg">
1271
- {/* Padded for a block — see the note on the non-virtualised
1272
- table's no-results cell. */}
1273
- <div aria-live="polite" className="py-6" role="status">
1274
- {noResultsMessage}
1275
- </div>
1276
- </TableCell>
1277
- </TableRow>
1506
+ <TableEmpty colSpan={columnCount}>
1507
+ {noResultsMessage ?? (
1508
+ <DataTableNoResults
1509
+ dataHook={dataHook}
1510
+ description={noResultsDescription}
1511
+ table={table}
1512
+ title={noResultsTitle}
1513
+ />
1514
+ )}
1515
+ </TableEmpty>
1278
1516
  )}
1279
1517
  </TableBody>
1280
1518
  {footer}
@@ -1284,7 +1522,17 @@ export function VirtualizedDataTable<TData>({
1284
1522
  );
1285
1523
  }
1286
1524
 
1287
- VirtualizedDataTable.displayName = "VirtualizedDataTable";
1525
+ /**
1526
+ * Virtualized renderer — see `VirtualizedDataTableInner` for the contract.
1527
+ * `ref` is the view wrapper, the scroll container the virtualizer drives.
1528
+ */
1529
+ const VirtualizedDataTable = React.forwardRef(VirtualizedDataTableInner) as <
1530
+ TData,
1531
+ >(
1532
+ props: VirtualizedDataTableProps<TData> & React.RefAttributes<HTMLDivElement>
1533
+ ) => React.ReactElement | null;
1534
+
1535
+ (VirtualizedDataTable as React.FC).displayName = "VirtualizedDataTable";
1288
1536
 
1289
1537
  /* -------------------------------------------------------------------------------------------------
1290
1538
  * DataTableColumnHeader (sortable header)
@@ -1549,6 +1797,17 @@ export interface DataTableSearchProps<TData> extends Omit<
1549
1797
  placeholder?: string;
1550
1798
  /** Accessible label for the clear button. @default "Clear search" */
1551
1799
  clearSearchAriaLabel?: string;
1800
+ /**
1801
+ * Disables the search input. Use during initial data load when there is
1802
+ * nothing to search yet — the input cannot be typed in, the clear button
1803
+ * hides, and the group dims via `has-[:disabled]:opacity-50`. Any pending
1804
+ * debounced push is discarded.
1805
+ *
1806
+ * This is for *initial load*, not refetch — during a search-triggered
1807
+ * refetch, use `loading` instead (the input stays editable).
1808
+ * @default false
1809
+ */
1810
+ disabled?: boolean;
1552
1811
  /**
1553
1812
  * Search refetch in flight — the leading search icon swaps to a spinner
1554
1813
  * and the group sets `aria-busy`. The input stays fully editable, and the
@@ -1595,16 +1854,23 @@ const MAX_TRACKED_FILTER_PUSHES = 10;
1595
1854
  * only updates after `debounceMs` of inactivity. Client-side filtering stays
1596
1855
  * synchronous: rows narrow per keystroke, exactly as the Filtering pattern
1597
1856
  * promises ("debounce the request, never the input").
1857
+ *
1858
+ * Accepts a `ref` that resolves to the inner `<input>` element, so consumers
1859
+ * can call `.focus()` without querying the component's markup.
1598
1860
  */
1599
- export function DataTableSearch<TData>({
1600
- table,
1601
- ariaLabel,
1602
- placeholder,
1603
- clearSearchAriaLabel,
1604
- loading = false,
1605
- debounceMs,
1606
- ...inputGroupProps
1607
- }: DataTableSearchProps<TData>) {
1861
+ export const DataTableSearch = React.forwardRef(function DataTableSearch<TData>(
1862
+ {
1863
+ table,
1864
+ ariaLabel,
1865
+ placeholder,
1866
+ clearSearchAriaLabel,
1867
+ disabled = false,
1868
+ loading = false,
1869
+ debounceMs,
1870
+ ...inputGroupProps
1871
+ }: DataTableSearchProps<TData>,
1872
+ ref: React.ForwardedRef<HTMLInputElement>
1873
+ ) {
1608
1874
  const filterValue = (table.getState().globalFilter ?? "") as string;
1609
1875
  const [inputValue, setInputValue] = React.useState(filterValue);
1610
1876
  // manualFiltering is the consumer's own declaration that filter changes are
@@ -1628,6 +1894,12 @@ export function DataTableSearch<TData>({
1628
1894
  }, []);
1629
1895
  React.useEffect(() => cancelPendingPush, [cancelPendingPush]);
1630
1896
 
1897
+ // Disabling discards any in-flight debounced push — a disabled search has
1898
+ // nothing to search, so a pending filter write is meaningless.
1899
+ React.useEffect(() => {
1900
+ if (disabled) cancelPendingPush();
1901
+ }, [disabled, cancelPendingPush]);
1902
+
1631
1903
  // The latest input value, readable from the timer callback. Synced in a
1632
1904
  // passive effect (never during render); the shortest debounce that
1633
1905
  // schedules a timer still fires long after the commit's effects, so a
@@ -1735,7 +2007,9 @@ export function DataTableSearch<TData>({
1735
2007
  )}
1736
2008
  </InputGroupAddon>
1737
2009
  <InputGroupInput
2010
+ ref={ref}
1738
2011
  aria-label={ariaLabel ?? "Search table"}
2012
+ disabled={disabled}
1739
2013
  placeholder={placeholder ?? "Search..."}
1740
2014
  type="text"
1741
2015
  value={inputValue}
@@ -1755,9 +2029,11 @@ export function DataTableSearch<TData>({
1755
2029
  />
1756
2030
  </InputGroup>
1757
2031
  );
1758
- }
2032
+ }) as <TData>(
2033
+ props: DataTableSearchProps<TData> & React.RefAttributes<HTMLInputElement>
2034
+ ) => React.ReactElement;
1759
2035
 
1760
- DataTableSearch.displayName = "DataTableSearch";
2036
+ (DataTableSearch as React.FC).displayName = "DataTableSearch";
1761
2037
 
1762
2038
  /* -------------------------------------------------------------------------------------------------
1763
2039
  * useDataTablePagination (hook)
@@ -1867,6 +2143,7 @@ function useDataTablePagination<TData>(
1867
2143
 
1868
2144
  interface DataTablePaginationContextValue {
1869
2145
  info: DataTablePaginationInfo;
2146
+ dataHook: string;
1870
2147
  }
1871
2148
 
1872
2149
  const DataTablePaginationContext =
@@ -1886,6 +2163,7 @@ function useDataTablePaginationContext() {
1886
2163
  * DataTablePaginationRowCount
1887
2164
  * -----------------------------------------------------------------------------------------------*/
1888
2165
 
2166
+ /** The English default: compact "start – end of total", nothing when empty. */
1889
2167
  /** Info passed to row-count render functions. */
1890
2168
  export interface RowCountRenderInfo {
1891
2169
  /** First visible row (1-based, 0 when empty). */
@@ -1902,30 +2180,61 @@ export interface RowCountRenderInfo {
1902
2180
 
1903
2181
  export interface DataTablePaginationRowCountProps {
1904
2182
  /**
1905
- * Render the row-count text. Receives pagination numbers; you control
1906
- * wording, pluralization, and order. Return `null` to hide.
1907
- * @default Renders "{startRow}-{endRow} of {totalRows}" or nothing when empty.
2183
+ * Row-count text. Supports the `{from}`, `{to}` and `{total}`
2184
+ * placeholders — name the records in the product's words
2185
+ * ("{from} to {to} of {total} locations"). Passed to
2186
+ * `ResultCount` as its `rangeLabel`.
2187
+ * @default "{from} to {to} of {total} results"
2188
+ */
2189
+ label?: string;
2190
+ /**
2191
+ * `label` for a total of exactly 1 ("1 to 1 of 1 location"). Falls back to
2192
+ * `label`. Passed to `ResultCount` as its `rangeLabelOne`.
2193
+ * @default "{from} to {to} of {total} result"
2194
+ */
2195
+ labelOne?: string;
2196
+ /**
2197
+ * Screen-reader-only text while the table is empty. The visible count
2198
+ * hides at zero — the empty state says it — but the live region stays and
2199
+ * announces the result. Passed to `ResultCount` as its `emptyLabel`.
2200
+ * @default "No results"
2201
+ */
2202
+ emptyLabel?: string;
2203
+ /**
2204
+ * Render the row-count text yourself. Receives pagination numbers; you
2205
+ * control wording, pluralization, and order. Return `null` to hide. The
2206
+ * node renders as plain text — prefer `label` so the count stays the
2207
+ * `ResultCount` live region.
1908
2208
  */
1909
2209
  renderText?: (info: RowCountRenderInfo) => React.ReactNode;
2210
+ /** Data hook for the count. @default "{paginationDataHook}-row-count" */
2211
+ dataHook?: string;
1910
2212
  /** Additional class name. */
1911
2213
  className?: string;
1912
2214
  }
1913
2215
 
1914
2216
  /**
1915
- * Row-count label for `DataTablePagination`.
2217
+ * Row-count label for `DataTablePagination` — a `ResultCount` in its range
2218
+ * form ("1 to 20 of 45 results"), so a paged table and a filtered
2219
+ * list share one count component and one wording. At zero rows the visible
2220
+ * count hides (the empty state says it) but the live region stays, with the
2221
+ * screen-reader-only `emptyLabel`, so the empty result is announced.
1916
2222
  *
1917
- * Renders "start–end of total" by default. Pass `renderText` for i18n-friendly
1918
- * custom text with full control over wording, pluralization, and order.
1919
2223
  * Renders nothing below the `sm` viewport breakpoint — on small screens the
1920
2224
  * label is removed so the page buttons get the full width (DS-998).
1921
2225
  *
1922
2226
  * Must be rendered inside `<DataTablePagination>`.
1923
2227
  */
1924
2228
  function DataTablePaginationRowCount({
2229
+ label,
2230
+ labelOne,
2231
+ emptyLabel,
1925
2232
  renderText,
2233
+ dataHook,
1926
2234
  className,
1927
2235
  }: DataTablePaginationRowCountProps) {
1928
- const { info } = useDataTablePaginationContext();
2236
+ const { info, dataHook: paginationDataHook } =
2237
+ useDataTablePaginationContext();
1929
2238
  const isMobile = useIsBelowBreakpoint("sm");
1930
2239
  const { startRow, endRow, totalRows, pageIndex, pageSize } = info;
1931
2240
 
@@ -1934,24 +2243,40 @@ function DataTablePaginationRowCount({
1934
2243
  // `PaginationControls`.
1935
2244
  if (isMobile) return null;
1936
2245
 
1937
- const content = renderText
1938
- ? renderText({ startRow, endRow, totalRows, pageIndex, pageSize })
1939
- : totalRows === 0
1940
- ? null
1941
- : `${startRow}-${endRow} of ${totalRows}`;
1942
-
1943
- if (content == null) return null;
2246
+ if (renderText) {
2247
+ const content = renderText({
2248
+ startRow,
2249
+ endRow,
2250
+ totalRows,
2251
+ pageIndex,
2252
+ pageSize,
2253
+ });
2254
+ if (content == null) return null;
2255
+ return (
2256
+ <span
2257
+ className={cn(
2258
+ "text-body-sm text-muted-foreground whitespace-nowrap",
2259
+ className
2260
+ )}
2261
+ data-hook={dataHook ?? `${paginationDataHook}-row-count`}
2262
+ data-slot="data-table-pagination-row-count"
2263
+ >
2264
+ {content}
2265
+ </span>
2266
+ );
2267
+ }
1944
2268
 
1945
2269
  return (
1946
- <span
1947
- className={cn(
1948
- "text-body-sm text-muted-foreground whitespace-nowrap",
1949
- className
1950
- )}
1951
- data-slot="data-table-pagination-row-count"
1952
- >
1953
- {content}
1954
- </span>
2270
+ <ResultCount
2271
+ className={cn("whitespace-nowrap", className)}
2272
+ dataHook={dataHook ?? `${paginationDataHook}-row-count`}
2273
+ emptyLabel={emptyLabel}
2274
+ from={startRow}
2275
+ rangeLabel={label}
2276
+ rangeLabelOne={labelOne}
2277
+ to={endRow}
2278
+ total={totalRows}
2279
+ />
1955
2280
  );
1956
2281
  }
1957
2282
 
@@ -2078,10 +2403,36 @@ export interface DataTablePaginationProps<TData> {
2078
2403
  */
2079
2404
  showRowCount?: boolean;
2080
2405
  /**
2081
- * Render the row-count text. Receives pagination numbers; you control
2082
- * wording, pluralization, and order. Return `null` to hide.
2406
+ * Row-count text in the default layout. Supports the `{from}`, `{to}` and
2407
+ * `{total}` placeholders — name the records in the product's words
2408
+ * ("{from} to {to} of {total} locations"). i18next's `{{from}}`
2409
+ * form is accepted too, so `rowCountLabel={t("pagination.caption")}` works
2410
+ * with the untranslated string.
2411
+ * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
2412
+ * @default "{from} to {to} of {total} results"
2413
+ */
2414
+ rowCountLabel?: string;
2415
+ /**
2416
+ * `rowCountLabel` for a total of exactly 1 ("1 to 1 of 1 location"). Falls
2417
+ * back to `rowCountLabel`; pair with i18next's `_one` key.
2418
+ * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
2419
+ * @default "{from} to {to} of {total} result"
2420
+ */
2421
+ rowCountLabelOne?: string;
2422
+ /**
2423
+ * Screen-reader-only row count while the table is empty. The visible count
2424
+ * hides at zero (the empty state says it) but the live region stays and
2425
+ * announces the result; nothing is visible and the bar keeps no height.
2426
+ * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
2427
+ * @default "No results"
2428
+ */
2429
+ rowCountEmptyLabel?: string;
2430
+ /**
2431
+ * Render the row-count text yourself. Receives pagination numbers; you
2432
+ * control wording, pluralization, and order. Return `null` to hide. The
2433
+ * node renders as plain text — prefer `rowCountLabel` so the count stays
2434
+ * the `ResultCount` live region.
2083
2435
  * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
2084
- * @default Renders "{startRow}-{endRow} of {totalRows}" or nothing when empty.
2085
2436
  */
2086
2437
  renderRowCount?: ((info: RowCountRenderInfo) => React.ReactNode) | null;
2087
2438
  /** Analytics element identifier. */
@@ -2104,14 +2455,16 @@ export interface DataTablePaginationProps<TData> {
2104
2455
  /**
2105
2456
  * Pagination controls for a DataTable.
2106
2457
  *
2107
- * **Default mode** (no children): renders previous/next/page links and an
2108
- * optional "start–end of total" row count label. Use `renderRowCount` for
2109
- * i18n-friendly text.
2458
+ * **Default mode** (no children): renders previous/next/page links and the
2459
+ * row count — a `ResultCount` in its range form, "1 to 20 of 45
2460
+ * results". Use `rowCountLabel` for i18n-friendly text.
2110
2461
  *
2111
2462
  * The navigation hides itself when there is at most one page (the row count
2112
- * stays, keeping the bar informative and the layout stable). When both the
2113
- * row count and the nav are empty, the component renders nothing — no
2114
- * consumer render gate needed.
2463
+ * stays, keeping the bar informative and the layout stable). At zero rows the
2464
+ * row count keeps its live region mounted with nothing visible, so the empty
2465
+ * result is announced; only with the row count off (`showRowCount={false}`,
2466
+ * `renderRowCount` null or returning null, or below `sm`) and a single page
2467
+ * does the component render nothing — no consumer render gate needed.
2115
2468
  *
2116
2469
  * **Responsive behaviour:** below the `sm` viewport breakpoint the row-count
2117
2470
  * label is removed and the page buttons centre in the available width — the
@@ -2140,9 +2493,7 @@ export interface DataTablePaginationProps<TData> {
2140
2493
  * <DataTablePagination
2141
2494
  * table={table}
2142
2495
  * dataHook="pagination"
2143
- * renderRowCount={({ startRow, endRow, totalRows }) =>
2144
- * t('pagination.caption', { from: startRow, to: endRow, total: totalRows })
2145
- * }
2496
+ * rowCountLabel={t('pagination.caption')} // "{from} to {to} of {total} locations"
2146
2497
  * />
2147
2498
  *
2148
2499
  * @example
@@ -2156,6 +2507,9 @@ export function DataTablePagination<TData>({
2156
2507
  table,
2157
2508
  dataHook,
2158
2509
  showRowCount = true,
2510
+ rowCountLabel,
2511
+ rowCountLabelOne,
2512
+ rowCountEmptyLabel,
2159
2513
  renderRowCount,
2160
2514
  trackingEl,
2161
2515
  trackingLabel,
@@ -2167,8 +2521,8 @@ export function DataTablePagination<TData>({
2167
2521
  const isMobile = useIsBelowBreakpoint("sm");
2168
2522
 
2169
2523
  const contextValue = React.useMemo<DataTablePaginationContextValue>(
2170
- () => ({ info }),
2171
- [info]
2524
+ () => ({ info, dataHook }),
2525
+ [info, dataHook]
2172
2526
  );
2173
2527
 
2174
2528
  const wrapperDataAttrs = {
@@ -2194,26 +2548,32 @@ export function DataTablePagination<TData>({
2194
2548
  );
2195
2549
  }
2196
2550
 
2197
- const rowCountContent = (() => {
2198
- // Below `sm` the label is removed so the page buttons get the full width
2199
- // and centre (DS-998).
2200
- if (isMobile) return null;
2201
- if (!showRowCount) return null;
2202
- if (renderRowCount === null) return null;
2203
- if (renderRowCount) {
2204
- return renderRowCount({
2205
- startRow: info.startRow,
2206
- endRow: info.endRow,
2207
- totalRows: info.totalRows,
2208
- pageIndex: info.pageIndex,
2209
- pageSize: info.pageSize,
2210
- });
2211
- }
2212
- if (info.totalRows === 0) return null;
2213
- return `${info.startRow}-${info.endRow} of ${info.totalRows}`;
2214
- })();
2215
-
2216
- if (rowCountContent == null && info.totalPages <= 1) {
2551
+ // Resolved here (not left to the sub-component) because the wrapper's
2552
+ // layout and its render-nothing rule depend on whether there is text.
2553
+ // Below `sm` the label is removed so the page buttons get the full width
2554
+ // and centre (DS-998).
2555
+ const customRowCount =
2556
+ renderRowCount && showRowCount && !isMobile
2557
+ ? renderRowCount({
2558
+ startRow: info.startRow,
2559
+ endRow: info.endRow,
2560
+ totalRows: info.totalRows,
2561
+ pageIndex: info.pageIndex,
2562
+ pageSize: info.pageSize,
2563
+ })
2564
+ : null;
2565
+ const hasRowCount =
2566
+ !isMobile &&
2567
+ showRowCount &&
2568
+ renderRowCount !== null &&
2569
+ (renderRowCount ? customRowCount != null : true);
2570
+ // At zero rows the default count is only its screen-reader empty label,
2571
+ // so the bar keeps no height for it and nothing is visible.
2572
+ const rowCountVisible =
2573
+ hasRowCount && (Boolean(renderRowCount) || info.totalRows > 0);
2574
+ const showNav = info.totalPages > 1;
2575
+
2576
+ if (!hasRowCount && !showNav) {
2217
2577
  return null;
2218
2578
  }
2219
2579
 
@@ -2221,17 +2581,23 @@ export function DataTablePagination<TData>({
2221
2581
  <DataTablePaginationContext.Provider value={contextValue}>
2222
2582
  <div
2223
2583
  className={cn(
2224
- "flex min-h-9 w-full flex-wrap items-center gap-x-4 gap-y-2",
2225
- rowCountContent != null ? "justify-between" : "justify-end",
2584
+ "flex w-full flex-wrap items-center gap-x-4 gap-y-2",
2585
+ (rowCountVisible || showNav) && "min-h-9",
2586
+ rowCountVisible ? "justify-between" : "justify-end",
2226
2587
  className
2227
2588
  )}
2228
2589
  {...wrapperDataAttrs}
2229
2590
  >
2230
- {rowCountContent != null && (
2231
- <span className="text-body-sm text-muted-foreground whitespace-nowrap">
2232
- {rowCountContent}
2233
- </span>
2234
- )}
2591
+ {hasRowCount &&
2592
+ (renderRowCount ? (
2593
+ <DataTablePaginationRowCount renderText={() => customRowCount} />
2594
+ ) : (
2595
+ <DataTablePaginationRowCount
2596
+ emptyLabel={rowCountEmptyLabel}
2597
+ label={rowCountLabel}
2598
+ labelOne={rowCountLabelOne}
2599
+ />
2600
+ ))}
2235
2601
  <DataTablePaginationNav
2236
2602
  ariaLabel={ariaLabel}
2237
2603
  className="grow"
@@ -2266,8 +2632,10 @@ export interface DataTableSelectAllCheckboxProps<TData> {
2266
2632
  }
2267
2633
 
2268
2634
  /**
2269
- * Header checkbox for selecting all visible page rows. Renders as
2270
- * indeterminate when some (but not all) rows are selected.
2635
+ * Header checkbox for selecting all visible page rows. Checked only when
2636
+ * every page row is selected; a partial selection shows it unchecked — the
2637
+ * DS checkbox has no indeterminate state (Active | Inactive, like the Figma
2638
+ * set), and clicking it still selects or clears every page row.
2271
2639
  *
2272
2640
  * While the surrounding `DataTable` is `refetching`, the checkbox is
2273
2641
  * `aria-disabled` and toggles are ignored (visually unchanged, still exposed
@@ -2286,10 +2654,7 @@ export function DataTableSelectAllCheckbox<TData>({
2286
2654
  <Checkbox
2287
2655
  aria-disabled={refetching || undefined}
2288
2656
  aria-label={selectAllAriaLabel ?? "Select all"}
2289
- checked={
2290
- table.getIsAllPageRowsSelected() ||
2291
- (table.getIsSomePageRowsSelected() && "indeterminate")
2292
- }
2657
+ checked={table.getIsAllPageRowsSelected()}
2293
2658
  dataHook={dataHook || "select-all-checkbox"}
2294
2659
  trackingEl={trackingEl}
2295
2660
  trackingLabel={trackingLabel}
@@ -2641,8 +3006,6 @@ export interface DataTableBulkActionsProps<TData> {
2641
3006
  * <DataTableToolbar dataHook="toolbar">
2642
3007
  * <DataTableToolbarLeft>
2643
3008
  * <DataTableSearch table={table} dataHook="search" />
2644
- * </DataTableToolbarLeft>
2645
- * <DataTableToolbarRight>
2646
3009
  * <DataTableBulkActions table={table} dataHook="bulk-actions">
2647
3010
  * <DataTableBulkActionsSummary />
2648
3011
  * <DataTableBulkActionsActions>
@@ -2651,6 +3014,9 @@ export interface DataTableBulkActionsProps<TData> {
2651
3014
  * </Button>
2652
3015
  * </DataTableBulkActionsActions>
2653
3016
  * </DataTableBulkActions>
3017
+ * </DataTableToolbarLeft>
3018
+ * <DataTableToolbarRight>
3019
+ * <DataTablePagination table={table} dataHook="pagination" />
2654
3020
  * </DataTableToolbarRight>
2655
3021
  * </DataTableToolbar>
2656
3022
  */
@@ -2849,8 +3215,14 @@ export interface DataTableToolbarProps {
2849
3215
  * Responsive toolbar container for DataTable companion controls.
2850
3216
  *
2851
3217
  * Stacks vertically on mobile (< 640 px) and switches to a horizontal
2852
- * row on `sm:` and up. Layout-only — no dependency on a TanStack Table
2853
- * instance, so it works for table footers or any search-plus-pagination row.
3218
+ * row on `sm:` and up. The row **wraps**: the bulk-actions bar joins the
3219
+ * search and filters in the left slot while rows are selected, and when the
3220
+ * right slot (pagination) no longer fits beside them it drops to a second
3221
+ * line, right-aligned.
3222
+ * Nothing is hidden or squeezed, which is what keeps the bulk-actions
3223
+ * contract ("search and filters stay mounted") true at any width.
3224
+ * Layout-only — no dependency on a TanStack Table instance, so it works
3225
+ * for table footers or any search-plus-pagination row.
2854
3226
  *
2855
3227
  * Toolbars belong in the same flex-column container as their `DataTable` so
2856
3228
  * the group reads as one slot inside gapped parents — see the composition
@@ -2879,7 +3251,7 @@ export function DataTableToolbar({
2879
3251
  return (
2880
3252
  <div
2881
3253
  className={cn(
2882
- "flex flex-col gap-3 py-4 sm:flex-row sm:items-center",
3254
+ "flex flex-col gap-3 py-4 sm:flex-row sm:flex-wrap sm:items-center",
2883
3255
  className
2884
3256
  )}
2885
3257
  data-hook={dataHook}
@@ -2908,8 +3280,10 @@ export interface DataTableToolbarLeftProps {
2908
3280
 
2909
3281
  /**
2910
3282
  * Left slot of `DataTableToolbar`. Grows to fill remaining space on
2911
- * desktop; full-width on mobile. `min-w-0` lets long inputs shrink
2912
- * instead of overflowing on narrow viewports.
3283
+ * desktop; full-width on mobile. Its flex basis is its content
3284
+ * (`flex-auto`, not `flex-1`) so a crowded toolbar wraps the right slot
3285
+ * onto a new line instead of squeezing the search and filters; `min-w-0`
3286
+ * still lets long inputs shrink on narrow viewports.
2913
3287
  */
2914
3288
  export function DataTableToolbarLeft({
2915
3289
  className,
@@ -2918,7 +3292,7 @@ export function DataTableToolbarLeft({
2918
3292
  return (
2919
3293
  <div
2920
3294
  className={cn(
2921
- "flex w-full min-w-0 items-center gap-2 sm:w-auto sm:flex-1",
3295
+ "flex w-full min-w-0 items-center gap-2 sm:w-auto sm:flex-auto",
2922
3296
  className
2923
3297
  )}
2924
3298
  data-slot="data-table-toolbar-left"
@@ -2940,14 +3314,15 @@ DataTableToolbarLeft.displayName = "DataTableToolbarLeft";
2940
3314
  export interface DataTableToolbarRightProps {
2941
3315
  /** Additional class name (merged after defaults via `cn`). */
2942
3316
  className?: string;
2943
- /** Slot contents — typically `DataTablePagination` or action buttons. */
3317
+ /** Slot contents — action buttons, bulk actions, or a compact top `DataTablePagination` for long-list pages. Pagination default placement is below the table. */
2944
3318
  children: React.ReactNode;
2945
3319
  }
2946
3320
 
2947
3321
  /**
2948
3322
  * Right slot of `DataTableToolbar`. Collapses to content width and
2949
- * right-aligns on desktop; full-width with `justify-end` on mobile so
2950
- * pagination controls don't jump when stacking.
3323
+ * right-aligns on desktop (`ml-auto`, so it stays right-aligned when the
3324
+ * toolbar wraps it onto its own line); full-width with `justify-end` on
3325
+ * mobile so pagination controls don't jump when stacking.
2951
3326
  */
2952
3327
  export function DataTableToolbarRight({
2953
3328
  className,
@@ -2956,7 +3331,7 @@ export function DataTableToolbarRight({
2956
3331
  return (
2957
3332
  <div
2958
3333
  className={cn(
2959
- "flex w-full items-center justify-end gap-2 sm:w-auto",
3334
+ "flex w-full items-center justify-end gap-2 sm:ml-auto sm:w-auto",
2960
3335
  className
2961
3336
  )}
2962
3337
  data-slot="data-table-toolbar-right"
@@ -2972,9 +3347,16 @@ DataTableToolbarRight.displayName = "DataTableToolbarRight";
2972
3347
  * Re-exported TanStack Table helpers
2973
3348
  * -----------------------------------------------------------------------------------------------*/
2974
3349
 
2975
- export { DataTablePaginationRowCount, DataTablePaginationNav };
3350
+ export {
3351
+ DataTable,
3352
+ VirtualizedDataTable,
3353
+ DataTablePaginationRowCount,
3354
+ DataTablePaginationNav,
3355
+ useDataTablePagination,
3356
+ };
2976
3357
 
2977
3358
  export type {
3359
+ DataTablePaginationInfo,
2978
3360
  Column,
2979
3361
  ColumnDef,
2980
3362
  ExpandedState,