@brightlocal/ui-components 3.1.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (463) hide show
  1. package/AI_USAGE.md +10 -0
  2. package/README.md +8 -1
  3. package/component-meta.json +1591 -123
  4. package/deprecations.json +45 -1
  5. package/dist/_virtual/_rolldown/runtime.cjs +1 -0
  6. package/dist/accordion.cjs +1 -1
  7. package/dist/accordion.js +73 -102
  8. package/dist/alert-dialog.cjs +1 -1
  9. package/dist/alert-dialog.d.ts +36 -5
  10. package/dist/alert-dialog.d.ts.map +1 -1
  11. package/dist/alert-dialog.js +83 -128
  12. package/dist/alert.cjs +1 -1
  13. package/dist/alert.d.ts +4 -4
  14. package/dist/alert.d.ts.map +1 -1
  15. package/dist/alert.js +116 -177
  16. package/dist/aspect-ratio.cjs +1 -1
  17. package/dist/aspect-ratio.js +13 -16
  18. package/dist/avatar.cjs +1 -1
  19. package/dist/avatar.js +30 -45
  20. package/dist/badge.cjs +1 -1
  21. package/dist/badge.d.ts +32 -1
  22. package/dist/badge.d.ts.map +1 -1
  23. package/dist/badge.js +90 -71
  24. package/dist/banner.cjs +1 -0
  25. package/dist/banner.d.ts +81 -0
  26. package/dist/banner.d.ts.map +1 -0
  27. package/dist/banner.js +130 -0
  28. package/dist/blocks/empty-state.cjs +1 -1
  29. package/dist/blocks/empty-state.d.ts +24 -6
  30. package/dist/blocks/empty-state.d.ts.map +1 -1
  31. package/dist/blocks/empty-state.js +74 -140
  32. package/dist/blocks/input-list.cjs +2 -2
  33. package/dist/blocks/input-list.d.ts +2 -2
  34. package/dist/blocks/input-list.d.ts.map +1 -1
  35. package/dist/blocks/input-list.js +136 -176
  36. package/dist/blocks/progress-state.cjs +1 -1
  37. package/dist/blocks/progress-state.d.ts +2 -2
  38. package/dist/blocks/progress-state.js +223 -347
  39. package/dist/blocks/sidebar.cjs +1 -1
  40. package/dist/blocks/sidebar.d.ts +28 -6
  41. package/dist/blocks/sidebar.d.ts.map +1 -1
  42. package/dist/blocks/sidebar.js +763 -1086
  43. package/dist/brand-illustration-motif.cjs +1 -1
  44. package/dist/brand-illustration-motif.d.ts +1 -1
  45. package/dist/brand-illustration-motif.js +40 -61
  46. package/dist/breadcrumb.cjs +1 -1
  47. package/dist/breadcrumb.js +62 -102
  48. package/dist/button-group.cjs +1 -1
  49. package/dist/button-group.js +23 -31
  50. package/dist/button.cjs +1 -1
  51. package/dist/button.d.ts +4 -2
  52. package/dist/button.d.ts.map +1 -1
  53. package/dist/button.js +149 -189
  54. package/dist/calendar.cjs +1 -1
  55. package/dist/calendar.d.ts +87 -3
  56. package/dist/calendar.d.ts.map +1 -1
  57. package/dist/calendar.js +116 -173
  58. package/dist/callout.cjs +1 -1
  59. package/dist/callout.js +73 -96
  60. package/dist/card.cjs +1 -1
  61. package/dist/card.d.ts +92 -6
  62. package/dist/card.d.ts.map +1 -1
  63. package/dist/card.js +240 -234
  64. package/dist/carousel.cjs +1 -1
  65. package/dist/carousel.d.ts +3 -3
  66. package/dist/carousel.d.ts.map +1 -1
  67. package/dist/carousel.js +174 -268
  68. package/dist/centred-layout.cjs +1 -1
  69. package/dist/centred-layout.js +27 -48
  70. package/dist/chart-empty.cjs +1 -1
  71. package/dist/chart-empty.js +18 -27
  72. package/dist/chart.cjs +7 -7
  73. package/dist/chart.d.ts +253 -25
  74. package/dist/chart.d.ts.map +1 -1
  75. package/dist/chart.js +465 -511
  76. package/dist/checkbox.cjs +1 -1
  77. package/dist/checkbox.d.ts +1 -1
  78. package/dist/checkbox.d.ts.map +1 -1
  79. package/dist/checkbox.js +37 -69
  80. package/dist/chip.cjs +1 -1
  81. package/dist/chip.js +116 -173
  82. package/dist/collapsible.cjs +1 -1
  83. package/dist/collapsible.d.ts.map +1 -1
  84. package/dist/collapsible.js +35 -41
  85. package/dist/combobox.cjs +3 -3
  86. package/dist/combobox.d.ts +14 -4
  87. package/dist/combobox.d.ts.map +1 -1
  88. package/dist/combobox.js +440 -639
  89. package/dist/command.cjs +1 -1
  90. package/dist/command.d.ts.map +1 -1
  91. package/dist/command.js +273 -420
  92. package/dist/context-menu.cjs +1 -1
  93. package/dist/context-menu.d.ts +5 -5
  94. package/dist/context-menu.d.ts.map +1 -1
  95. package/dist/context-menu.js +121 -191
  96. package/dist/data-table.cjs +1 -1
  97. package/dist/data-table.d.ts +442 -144
  98. package/dist/data-table.d.ts.map +1 -1
  99. package/dist/data-table.js +708 -835
  100. package/dist/date-picker.cjs +1 -1
  101. package/dist/date-picker.d.ts +15 -4
  102. package/dist/date-picker.d.ts.map +1 -1
  103. package/dist/date-picker.js +156 -231
  104. package/dist/delta.cjs +1 -0
  105. package/dist/delta.d.ts +79 -0
  106. package/dist/delta.d.ts.map +1 -0
  107. package/dist/delta.js +62 -0
  108. package/dist/description.cjs +1 -1
  109. package/dist/description.js +11 -20
  110. package/dist/dialog.cjs +1 -1
  111. package/dist/dialog.d.ts +1 -1
  112. package/dist/dialog.d.ts.map +1 -1
  113. package/dist/dialog.js +76 -116
  114. package/dist/drawer.cjs +1 -1
  115. package/dist/drawer.d.ts +11 -11
  116. package/dist/drawer.d.ts.map +1 -1
  117. package/dist/drawer.js +76 -134
  118. package/dist/dropdown-menu.cjs +1 -1
  119. package/dist/dropdown-menu.d.ts +6 -6
  120. package/dist/dropdown-menu.d.ts.map +1 -1
  121. package/dist/dropdown-menu.js +179 -300
  122. package/dist/field.cjs +1 -1
  123. package/dist/field.d.ts +9 -9
  124. package/dist/field.d.ts.map +1 -1
  125. package/dist/field.js +166 -286
  126. package/dist/global-layout.cjs +1 -1
  127. package/dist/global-layout.js +203 -342
  128. package/dist/grid.cjs +1 -1
  129. package/dist/grid.d.ts +24 -1
  130. package/dist/grid.d.ts.map +1 -1
  131. package/dist/grid.js +16 -29
  132. package/dist/header.cjs +1 -1
  133. package/dist/header.js +21 -38
  134. package/dist/height-transition.cjs +1 -1
  135. package/dist/height-transition.js +38 -55
  136. package/dist/hooks/use-breakpoint.cjs +1 -1
  137. package/dist/hooks/use-breakpoint.d.ts +1 -1
  138. package/dist/hooks/use-breakpoint.d.ts.map +1 -1
  139. package/dist/hooks/use-breakpoint.js +10 -9
  140. package/dist/hooks/use-debounce.cjs +1 -1
  141. package/dist/hooks/use-debounce.js +12 -11
  142. package/dist/hooks/use-delayed-pending.cjs +1 -1
  143. package/dist/hooks/use-delayed-pending.js +8 -9
  144. package/dist/hooks/use-filter-search-params.cjs +1 -0
  145. package/dist/hooks/use-filter-search-params.d.ts +93 -0
  146. package/dist/hooks/use-filter-search-params.d.ts.map +1 -0
  147. package/dist/hooks/use-filter-search-params.js +122 -0
  148. package/dist/hooks/use-mobile.cjs +1 -1
  149. package/dist/hooks/use-mobile.js +6 -6
  150. package/dist/hooks/use-overlay-pointer-lock.cjs +1 -1
  151. package/dist/hooks/use-overlay-pointer-lock.js +8 -9
  152. package/dist/hooks/use-prefers-reduced-motion.cjs +1 -1
  153. package/dist/hooks/use-prefers-reduced-motion.js +5 -8
  154. package/dist/hover-card.cjs +1 -1
  155. package/dist/hover-card.d.ts +1 -1
  156. package/dist/hover-card.d.ts.map +1 -1
  157. package/dist/hover-card.js +30 -62
  158. package/dist/index.cjs +1 -1
  159. package/dist/index.d.ts +11 -0
  160. package/dist/index.d.ts.map +1 -1
  161. package/dist/index.js +636 -582
  162. package/dist/info-tooltip.cjs +1 -0
  163. package/dist/info-tooltip.d.ts +39 -0
  164. package/dist/info-tooltip.d.ts.map +1 -0
  165. package/dist/info-tooltip.js +27 -0
  166. package/dist/input-chip.cjs +1 -1
  167. package/dist/input-chip.d.ts +32 -3
  168. package/dist/input-chip.d.ts.map +1 -1
  169. package/dist/input-chip.js +182 -231
  170. package/dist/input-group.cjs +1 -1
  171. package/dist/input-group.d.ts +33 -2
  172. package/dist/input-group.d.ts.map +1 -1
  173. package/dist/input-group.js +188 -122
  174. package/dist/input-otp.cjs +1 -1
  175. package/dist/input-otp.d.ts +3 -3
  176. package/dist/input-otp.d.ts.map +1 -1
  177. package/dist/input-otp.js +102 -146
  178. package/dist/input-password.cjs +1 -1
  179. package/dist/input-password.d.ts +26 -8
  180. package/dist/input-password.d.ts.map +1 -1
  181. package/dist/input-password.js +139 -171
  182. package/dist/input.cjs +1 -1
  183. package/dist/input.d.ts.map +1 -1
  184. package/dist/input.js +51 -73
  185. package/dist/label.cjs +1 -1
  186. package/dist/label.js +20 -38
  187. package/dist/lib/block-illustration.cjs +1 -1
  188. package/dist/lib/block-illustration.d.ts +5 -2
  189. package/dist/lib/block-illustration.d.ts.map +1 -1
  190. package/dist/lib/block-illustration.js +16 -17
  191. package/dist/lib/compose-event-handlers.cjs +1 -0
  192. package/dist/lib/compose-event-handlers.d.ts +9 -0
  193. package/dist/lib/compose-event-handlers.d.ts.map +1 -0
  194. package/dist/lib/compose-event-handlers.js +8 -0
  195. package/dist/lib/download-file.cjs +1 -0
  196. package/dist/lib/download-file.d.ts +14 -0
  197. package/dist/lib/download-file.d.ts.map +1 -0
  198. package/dist/lib/download-file.js +40 -0
  199. package/dist/lib/empty-canvas.cjs +1 -1
  200. package/dist/lib/empty-canvas.js +28 -56
  201. package/dist/lib/empty-chip.cjs +1 -1
  202. package/dist/lib/empty-chip.d.ts +14 -3
  203. package/dist/lib/empty-chip.d.ts.map +1 -1
  204. package/dist/lib/empty-chip.js +15 -11
  205. package/dist/lib/field-aria.cjs +1 -0
  206. package/dist/lib/field-aria.d.ts +34 -0
  207. package/dist/lib/field-aria.d.ts.map +1 -0
  208. package/dist/lib/field-aria.js +52 -0
  209. package/dist/lib/image-file-info.cjs +1 -0
  210. package/dist/lib/image-file-info.d.ts +25 -0
  211. package/dist/lib/image-file-info.d.ts.map +1 -0
  212. package/dist/lib/image-file-info.js +67 -0
  213. package/dist/lib/media-viewer-content.cjs +1 -0
  214. package/dist/lib/media-viewer-content.d.ts +102 -0
  215. package/dist/lib/media-viewer-content.d.ts.map +1 -0
  216. package/dist/lib/media-viewer-content.js +650 -0
  217. package/dist/lib/media-viewer-internal.cjs +1 -0
  218. package/dist/lib/media-viewer-internal.d.ts +98 -0
  219. package/dist/lib/media-viewer-internal.d.ts.map +1 -0
  220. package/dist/lib/media-viewer-internal.js +61 -0
  221. package/dist/lib/media-viewer-motion.cjs +1 -0
  222. package/dist/lib/media-viewer-motion.d.ts +40 -0
  223. package/dist/lib/media-viewer-motion.d.ts.map +1 -0
  224. package/dist/lib/media-viewer-motion.js +37 -0
  225. package/dist/lib/motion.cjs +1 -1
  226. package/dist/lib/motion.d.ts +8 -0
  227. package/dist/lib/motion.d.ts.map +1 -1
  228. package/dist/lib/motion.js +11 -10
  229. package/dist/lib/optical-center.cjs +1 -1
  230. package/dist/lib/optical-center.d.ts +1 -1
  231. package/dist/lib/optical-center.d.ts.map +1 -1
  232. package/dist/lib/optical-center.js +12 -5
  233. package/dist/lib/spring-settle.cjs +1 -1
  234. package/dist/lib/spring-settle.js +1 -1
  235. package/dist/lib/table-internal.cjs +1 -0
  236. package/dist/lib/table-internal.d.ts +62 -0
  237. package/dist/lib/table-internal.d.ts.map +1 -0
  238. package/dist/lib/table-internal.js +18 -0
  239. package/dist/lib/use-controllable.cjs +1 -0
  240. package/dist/lib/use-controllable.d.ts +12 -0
  241. package/dist/lib/use-controllable.d.ts.map +1 -0
  242. package/dist/lib/use-controllable.js +15 -0
  243. package/dist/lib/use-dev-warning.cjs +1 -1
  244. package/dist/lib/utils.cjs +1 -1
  245. package/dist/lib/utils.d.ts.map +1 -1
  246. package/dist/lib/utils.js +29 -35
  247. package/dist/link.cjs +1 -1
  248. package/dist/link.d.ts +1 -1
  249. package/dist/link.js +78 -124
  250. package/dist/list.cjs +1 -1
  251. package/dist/list.d.ts +8 -0
  252. package/dist/list.d.ts.map +1 -1
  253. package/dist/list.js +94 -156
  254. package/dist/loading.cjs +1 -1
  255. package/dist/loading.js +124 -151
  256. package/dist/logo-mark.cjs +1 -0
  257. package/dist/logo-mark.d.ts +79 -0
  258. package/dist/logo-mark.d.ts.map +1 -0
  259. package/dist/logo-mark.js +219 -0
  260. package/dist/logo.cjs +1 -1
  261. package/dist/logo.d.ts +1 -1
  262. package/dist/logo.d.ts.map +1 -1
  263. package/dist/logo.js +51 -87
  264. package/dist/map.cjs +1 -1
  265. package/dist/map.d.ts.map +1 -1
  266. package/dist/map.js +390 -586
  267. package/dist/media-empty.cjs +1 -1
  268. package/dist/media-empty.js +27 -42
  269. package/dist/media-viewer.cjs +1 -0
  270. package/dist/media-viewer.d.ts +224 -0
  271. package/dist/media-viewer.d.ts.map +1 -0
  272. package/dist/media-viewer.js +295 -0
  273. package/dist/menubar.cjs +1 -1
  274. package/dist/menubar.d.ts +14 -14
  275. package/dist/menubar.d.ts.map +1 -1
  276. package/dist/menubar.js +130 -267
  277. package/dist/multi-select-filter.cjs +1 -0
  278. package/dist/multi-select-filter.d.ts +186 -0
  279. package/dist/multi-select-filter.d.ts.map +1 -0
  280. package/dist/multi-select-filter.js +374 -0
  281. package/dist/navigation-menu.cjs +1 -1
  282. package/dist/navigation-menu.js +108 -172
  283. package/dist/pagination.cjs +1 -1
  284. package/dist/pagination.d.ts +36 -12
  285. package/dist/pagination.d.ts.map +1 -1
  286. package/dist/pagination.js +208 -281
  287. package/dist/popover.cjs +1 -1
  288. package/dist/popover.d.ts +1 -1
  289. package/dist/popover.d.ts.map +1 -1
  290. package/dist/popover.js +34 -45
  291. package/dist/progress.cjs +1 -1
  292. package/dist/progress.d.ts +139 -17
  293. package/dist/progress.d.ts.map +1 -1
  294. package/dist/progress.js +116 -148
  295. package/dist/radio-group.cjs +1 -1
  296. package/dist/radio-group.js +90 -146
  297. package/dist/rating.cjs +1 -1
  298. package/dist/rating.d.ts +80 -13
  299. package/dist/rating.d.ts.map +1 -1
  300. package/dist/rating.js +70 -65
  301. package/dist/relative-date.cjs +1 -0
  302. package/dist/relative-date.d.ts +65 -0
  303. package/dist/relative-date.d.ts.map +1 -0
  304. package/dist/relative-date.js +112 -0
  305. package/dist/resizable.cjs +1 -1
  306. package/dist/resizable.d.ts +39 -23
  307. package/dist/resizable.d.ts.map +1 -1
  308. package/dist/resizable.js +42 -44
  309. package/dist/result-count.cjs +1 -0
  310. package/dist/result-count.d.ts +110 -0
  311. package/dist/result-count.d.ts.map +1 -0
  312. package/dist/result-count.js +49 -0
  313. package/dist/route-progress.cjs +1 -1
  314. package/dist/route-progress.js +58 -102
  315. package/dist/scroll-area.cjs +1 -1
  316. package/dist/scroll-area.d.ts +9 -1
  317. package/dist/scroll-area.d.ts.map +1 -1
  318. package/dist/scroll-area.js +44 -79
  319. package/dist/select.cjs +2 -2
  320. package/dist/select.d.ts +20 -10
  321. package/dist/select.d.ts.map +1 -1
  322. package/dist/select.js +132 -236
  323. package/dist/separator.cjs +1 -1
  324. package/dist/separator.js +90 -78
  325. package/dist/sheet.cjs +1 -1
  326. package/dist/sheet.d.ts +86 -7
  327. package/dist/sheet.d.ts.map +1 -1
  328. package/dist/sheet.js +275 -235
  329. package/dist/single-select-filter.cjs +1 -0
  330. package/dist/single-select-filter.d.ts +113 -0
  331. package/dist/single-select-filter.d.ts.map +1 -0
  332. package/dist/single-select-filter.js +224 -0
  333. package/dist/skeleton.cjs +1 -1
  334. package/dist/skeleton.js +24 -38
  335. package/dist/slider.cjs +1 -1
  336. package/dist/slider.js +51 -81
  337. package/dist/sonner.cjs +1 -1
  338. package/dist/sonner.d.ts +1 -1
  339. package/dist/sonner.d.ts.map +1 -1
  340. package/dist/sonner.js +113 -137
  341. package/dist/spinner.cjs +1 -1
  342. package/dist/spinner.js +22 -31
  343. package/dist/split-layout.cjs +1 -1
  344. package/dist/split-layout.d.ts +1 -1
  345. package/dist/split-layout.js +53 -102
  346. package/dist/status.cjs +1 -0
  347. package/dist/status.d.ts +51 -0
  348. package/dist/status.d.ts.map +1 -0
  349. package/dist/status.js +60 -0
  350. package/dist/stepper.cjs +1 -1
  351. package/dist/stepper.js +184 -316
  352. package/dist/switch.cjs +1 -1
  353. package/dist/switch.js +17 -32
  354. package/dist/table.cjs +1 -1
  355. package/dist/table.d.ts +127 -13
  356. package/dist/table.d.ts.map +1 -1
  357. package/dist/table.js +170 -192
  358. package/dist/tabs.cjs +1 -1
  359. package/dist/tabs.d.ts +12 -1
  360. package/dist/tabs.d.ts.map +1 -1
  361. package/dist/tabs.js +123 -146
  362. package/dist/text-reveal-motion.cjs +1 -1
  363. package/dist/text-reveal-motion.js +307 -363
  364. package/dist/textarea.cjs +1 -1
  365. package/dist/textarea.d.ts.map +1 -1
  366. package/dist/textarea.js +23 -36
  367. package/dist/toggle-group.cjs +1 -1
  368. package/dist/toggle-group.js +43 -62
  369. package/dist/toggle.cjs +1 -1
  370. package/dist/toggle.js +34 -46
  371. package/dist/tooltip.cjs +1 -1
  372. package/dist/tooltip.d.ts +38 -36
  373. package/dist/tooltip.d.ts.map +1 -1
  374. package/dist/tooltip.js +175 -78
  375. package/dist/typography-heading.cjs +1 -1
  376. package/dist/typography-heading.js +25 -61
  377. package/dist/typography-text.cjs +1 -1
  378. package/dist/typography-text.d.ts +1 -2
  379. package/dist/typography-text.d.ts.map +1 -1
  380. package/dist/typography-text.js +27 -57
  381. package/dist/typography.cjs +1 -1
  382. package/dist/typography.d.ts +1 -1
  383. package/dist/typography.js +132 -340
  384. package/package.json +45 -46
  385. package/src/blocks/empty-state.tsx +42 -21
  386. package/src/blocks/progress-state.tsx +2 -2
  387. package/src/blocks/sidebar.tsx +111 -32
  388. package/src/components/accordion.tsx +1 -1
  389. package/src/components/alert-dialog.tsx +52 -5
  390. package/src/components/alert.tsx +16 -8
  391. package/src/components/badge.tsx +152 -3
  392. package/src/components/banner.tsx +288 -0
  393. package/src/components/brand-illustration-motif.tsx +1 -1
  394. package/src/components/breadcrumb.tsx +1 -1
  395. package/src/components/button.tsx +8 -6
  396. package/src/components/calendar.tsx +155 -9
  397. package/src/components/card.tsx +266 -26
  398. package/src/components/carousel.tsx +4 -1
  399. package/src/components/chart.tsx +664 -42
  400. package/src/components/checkbox.tsx +2 -2
  401. package/src/components/collapsible.tsx +4 -1
  402. package/src/components/combobox.tsx +42 -9
  403. package/src/components/command.tsx +10 -11
  404. package/src/components/context-menu.tsx +4 -4
  405. package/src/components/data-table.tsx +1363 -398
  406. package/src/components/date-picker.tsx +31 -4
  407. package/src/components/delta.tsx +217 -0
  408. package/src/components/drawer.tsx +5 -5
  409. package/src/components/dropdown-menu.tsx +4 -4
  410. package/src/components/field.tsx +36 -15
  411. package/src/components/global-layout.tsx +1 -1
  412. package/src/components/grid.tsx +32 -1
  413. package/src/components/info-tooltip.tsx +94 -0
  414. package/src/components/input-chip.tsx +52 -8
  415. package/src/components/input-group.tsx +247 -12
  416. package/src/components/input-otp.tsx +1 -1
  417. package/src/components/input-password.tsx +29 -11
  418. package/src/components/input.tsx +11 -2
  419. package/src/components/list.tsx +15 -3
  420. package/src/components/logo-mark.tsx +345 -0
  421. package/src/components/map.tsx +18 -20
  422. package/src/components/media-viewer.tsx +908 -0
  423. package/src/components/multi-select-filter.tsx +1046 -0
  424. package/src/components/navigation-menu.tsx +2 -2
  425. package/src/components/pagination.tsx +86 -26
  426. package/src/components/progress.tsx +281 -54
  427. package/src/components/rating.tsx +200 -74
  428. package/src/components/relative-date.tsx +238 -0
  429. package/src/components/resizable.tsx +86 -33
  430. package/src/components/result-count.tsx +253 -0
  431. package/src/components/scroll-area.tsx +31 -5
  432. package/src/components/select.tsx +37 -7
  433. package/src/components/sheet.tsx +252 -6
  434. package/src/components/single-select-filter.tsx +538 -0
  435. package/src/components/slider.tsx +2 -2
  436. package/src/components/sonner.tsx +16 -5
  437. package/src/components/split-layout.tsx +2 -2
  438. package/src/components/status.tsx +162 -0
  439. package/src/components/switch.tsx +1 -1
  440. package/src/components/table.tsx +305 -73
  441. package/src/components/tabs.tsx +94 -46
  442. package/src/components/textarea.tsx +21 -3
  443. package/src/components/toggle.tsx +2 -2
  444. package/src/components/tooltip.tsx +431 -68
  445. package/src/components/typography-text.tsx +1 -2
  446. package/src/components/typography.tsx +1 -1
  447. package/src/hooks/use-breakpoint.ts +2 -1
  448. package/src/hooks/use-filter-search-params.ts +302 -0
  449. package/src/index.ts +11 -0
  450. package/src/lib/block-illustration.tsx +5 -1
  451. package/src/lib/compose-event-handlers.ts +14 -0
  452. package/src/lib/download-file.ts +61 -0
  453. package/src/lib/empty-chip.tsx +52 -0
  454. package/src/lib/field-aria.tsx +97 -0
  455. package/src/lib/image-file-info.ts +102 -0
  456. package/src/lib/media-viewer-content.tsx +1587 -0
  457. package/src/lib/media-viewer-internal.tsx +191 -0
  458. package/src/lib/media-viewer-motion.ts +120 -0
  459. package/src/lib/motion.ts +9 -0
  460. package/src/lib/table-internal.ts +74 -0
  461. package/src/lib/use-controllable.ts +43 -0
  462. package/src/lib/utils.ts +1 -0
  463. package/src/lib/empty-chip.ts +0 -24
@@ -25,6 +25,7 @@ import {
25
25
  type Column,
26
26
  type ColumnDef,
27
27
  type ExpandedState,
28
+ type Header,
28
29
  type PaginationState,
29
30
  type Row,
30
31
  type RowData,
@@ -47,8 +48,36 @@ declare module "@tanstack/react-table" {
47
48
  width?: string;
48
49
  /** Minimum column width (e.g., "100px", "8rem"). */
49
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";
50
65
  }
51
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
+ );
52
81
  import { useVirtualizer } from "@tanstack/react-virtual";
53
82
  import {
54
83
  ArrowDown,
@@ -56,14 +85,20 @@ import {
56
85
  ArrowUpDown,
57
86
  ChevronRight,
58
87
  Search,
59
- X,
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
- import { InputGroup, InputGroupAddon, InputGroupInput } from "./input-group";
96
+ import {
97
+ InputGroup,
98
+ InputGroupAddon,
99
+ InputGroupClear,
100
+ InputGroupInput,
101
+ } from "./input-group";
67
102
  import {
68
103
  Pagination,
69
104
  PaginationContent,
@@ -74,62 +109,31 @@ import {
74
109
  PaginationPrevious,
75
110
  usePagination,
76
111
  } from "./pagination";
112
+ import { ResultCount } from "./result-count";
77
113
  import { Skeleton } from "./skeleton";
114
+ import { Spinner } from "./spinner";
115
+ import { EmptyState } from "../blocks/empty-state";
78
116
  import {
79
117
  Table,
80
118
  TableBody,
81
119
  TableCell,
120
+ TableEmpty,
82
121
  TableHead,
83
122
  TableHeader,
84
123
  TableRow,
85
124
  } from "./table";
125
+ import {
126
+ TABLE_ROW_MIN_HEIGHT,
127
+ scrollRegionProps,
128
+ type TableFrame,
129
+ type TableSize,
130
+ } from "../lib/table-internal";
86
131
  import { TypographyMuted } from "./typography";
87
132
 
88
133
  /* -------------------------------------------------------------------------------------------------
89
134
  * useDataTable (hook)
90
135
  * -----------------------------------------------------------------------------------------------*/
91
136
 
92
- /**
93
- * Controlled/uncontrolled state helper.
94
- *
95
- * Resolves a "controlled or internal" value and returns a setter compatible
96
- * with TanStack Table's `SetStateAction<T>` updater signature. When the
97
- * `controlled` value is defined, the parent owns state and `onChange` is
98
- * called with the next value. When undefined, state is kept internally and
99
- * `onChange` is still invoked (the common "notify but self-manage" pattern).
100
- */
101
- function useControllable<T>(
102
- controlled: T | undefined,
103
- initialValue: T,
104
- onChange?: (next: T) => void
105
- ): [T, (updater: T | ((prev: T) => T)) => void] {
106
- const [internal, setInternal] = React.useState<T>(initialValue);
107
- const value = controlled !== undefined ? controlled : internal;
108
-
109
- const valueRef = React.useRef(value);
110
- React.useEffect(() => {
111
- valueRef.current = value;
112
- });
113
-
114
- const isControlled = controlled !== undefined;
115
-
116
- const setValue = React.useCallback(
117
- (updater: T | ((prev: T) => T)) => {
118
- const next =
119
- typeof updater === "function"
120
- ? (updater as (prev: T) => T)(valueRef.current)
121
- : updater;
122
- if (!isControlled) {
123
- setInternal(next);
124
- }
125
- onChange?.(next);
126
- },
127
- [isControlled, onChange]
128
- );
129
-
130
- return [value, setValue];
131
- }
132
-
133
137
  /**
134
138
  * Configuration for `useDataTable`.
135
139
  *
@@ -193,7 +197,11 @@ export interface UseDataTableOptions<TData> {
193
197
  enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
194
198
  /** Enable client-side pagination. @default false */
195
199
  enablePagination?: boolean;
196
- /** 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
+ */
197
205
  pageSize?: number;
198
206
 
199
207
  // ---------- Server-side / manual modes ----------
@@ -324,7 +332,7 @@ export function useDataTable<TData>(
324
332
  enableGlobalFiltering = false,
325
333
  enableRowSelection = false,
326
334
  enablePagination = false,
327
- pageSize = 10,
335
+ pageSize = 20,
328
336
  manualSorting = false,
329
337
  manualFiltering = false,
330
338
  manualPagination = false,
@@ -461,6 +469,22 @@ export function useDataTable<TData>(
461
469
  * rendering-focused — wire toolbars, pagination, and search components
462
470
  * outside of it via composition.
463
471
  */
472
+ /* -------------------------------------------------------------------------------------------------
473
+ * Internal: refetch context (DS-916)
474
+ *
475
+ * While a server-side refetch is in flight the rows on screen are stale.
476
+ * Selection controls rendered inside the table (`DataTableSelectAllCheckbox`,
477
+ * `DataTableSelectRowCheckbox`) read this context and block interaction:
478
+ * `aria-disabled` plus a guarded change handler (the checkbox is controlled,
479
+ * so a guarded handler stops pointer and keyboard alike). Not `inert` — that
480
+ * removes the checkbox from the accessibility tree, leaving the select-all
481
+ * `<th>` with no screen-reader-visible content (axe `empty-table-header`)
482
+ * and yanking focus from a user mid-interaction. The bulk-actions bar lives
483
+ * outside the table's subtree, so it takes its own `refetching` prop instead.
484
+ * -----------------------------------------------------------------------------------------------*/
485
+
486
+ const DataTableRefetchingContext = React.createContext(false);
487
+
464
488
  export interface DataTableProps<TData> {
465
489
  /** TanStack Table instance (usually returned from `useDataTable`). */
466
490
  table: TanStackTable<TData>;
@@ -470,34 +494,148 @@ export interface DataTableProps<TData> {
470
494
  trackingEl?: string;
471
495
  /** Analytics label. */
472
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;
473
527
  /** Show skeleton rows instead of data while loading async data. */
474
528
  isLoading?: boolean;
529
+ /**
530
+ * Marks a server-side refetch (page, sort, filter or search change) as in
531
+ * flight. Unlike `isLoading` — the initial load, which swaps rows for
532
+ * skeletons — `refetching` never touches the rows: they stay rendered at
533
+ * full contrast (keep the stale data with TanStack Query's
534
+ * `placeholderData: keepPreviousData` or `useTransition`). The table sets
535
+ * `aria-busy` (never the wrapper — the live region must stay outside the
536
+ * busy subtree to be announced), a polite live region announces
537
+ * `refetchingLabel`, and the
538
+ * selection checkboxes (`DataTableSelectAllCheckbox`,
539
+ * `DataTableSelectRowCheckbox`) set `aria-disabled` and ignore toggles —
540
+ * selecting rows that are about to be replaced acts on stale data. The busy *visual* belongs to the
541
+ * control that requested the refetch (the pagination button, the sort
542
+ * header's or search field's `loading`), not to the body.
543
+ *
544
+ * Wrap a raw `isFetching` in `useDelayedPending` before passing it, so a
545
+ * refetch that resolves inside the flash threshold shows nothing at all.
546
+ * @default false
547
+ */
548
+ refetching?: boolean;
549
+ /**
550
+ * What the polite live region announces to screen readers while
551
+ * `refetching` is set.
552
+ * @default "Loading results…"
553
+ */
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;
475
561
  /** Number of skeleton rows when loading. Falls back to the table's page size, then 10. */
476
562
  skeletonRowCount?: number;
477
563
  /**
478
- * 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.
479
566
  *
480
- * A string is the no-results case — a filter or search that excludes
481
- * everything — and it is announced politely, because the reader's own query
482
- * 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`.
483
572
  *
484
- * Pass an `<EmptyState>` for a collection that is empty rather than filtered:
485
- * nothing has been added yet, so the cell needs a title and a way to add the
486
- * first one. The cell brings the block's breathing room with it — do not wrap
487
- * it in a padding element. The block is wrapped in the same live region, so
488
- * keep it to the standard anatomy — its title and one line are worth hearing;
489
- * a wall of copy is not.
490
- * @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
491
580
  */
492
581
  noResultsMessage?: React.ReactNode;
493
582
  /**
494
- * Pin the `<thead>` to the top of the scroll container so column headers
495
- * remain visible while scrolling. The header keeps its opaque `bg-muted`
496
- * background to separate it from body rows.
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;
594
+ /**
595
+ * Pin the `<thead>` to the top of the component's own scroll container
596
+ * (the outer wrapper) so column headers remain visible while the rows
597
+ * scroll. Bound the height through `className` — a fixed cap
598
+ * (`max-h-96`) or flex sizing inside a height-capped parent
599
+ * (`min-h-0 flex-1`) — and the header sticks while rows scroll beneath
600
+ * it (DS-912). The header keeps its opaque `bg-muted` background to
601
+ * separate it from body rows.
602
+ *
603
+ * Setting this also makes the outer wrapper a focusable scroll region
604
+ * (`role="region"` + `tabIndex`, labelled by `scrollRegionLabel`), so
605
+ * keyboard users can focus and scroll the rows — the height bound lives
606
+ * in `className`, which the component cannot inspect, so the sticky
607
+ * intent is the signal. For the same reason, don't set it on a table
608
+ * with no height bound: the wrapper never scrolls, and the region
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.
497
622
  * @default false
498
623
  */
499
- stickyHeader?: boolean;
500
- /** Additional class name for the outer wrapper. */
624
+ stickyHeader?: boolean | "page";
625
+ /**
626
+ * Additional class name for the outer wrapper — the component's single
627
+ * scroll container for both axes. Height bounds belong here: `max-h-*`
628
+ * for a fixed cap, or `min-h-0 flex-1` to fill a height-capped parent
629
+ * such as a dialog body.
630
+ *
631
+ * A height bound almost always wants `stickyHeader` with it — that also
632
+ * grants the keyboard-focusable scroll-region semantics. If you cap the
633
+ * height and deliberately let the header scroll away, pass
634
+ * `scrollRegionLabel` instead: it opts the wrapper into the same
635
+ * focusable scroll-region semantics without pinning the header, so the
636
+ * region semantics sit on the element that actually scrolls — keyboard
637
+ * arrow keys only scroll the focused element itself or an ancestor.
638
+ */
501
639
  className?: string;
502
640
  /**
503
641
  * Table layout algorithm.
@@ -518,8 +656,23 @@ export interface DataTableProps<TData> {
518
656
  */
519
657
  minWidth?: string;
520
658
  /**
521
- * Accessible label for the scroll container region.
522
- * Used when `minWidth` is set to provide context for keyboard users.
659
+ * Accessible label for the scroll container region (the outer wrapper).
660
+ * Applied whenever the wrapper is a focusable scroll region: `minWidth`
661
+ * is set (horizontal scrolling), `stickyHeader` is set (vertical
662
+ * scrolling under a pinned header), or always on `VirtualizedDataTable`
663
+ * (its viewport is bounded by definition).
664
+ *
665
+ * Passing it is also itself the opt-in for tables that scroll without
666
+ * either signal — a `className` height cap with the header deliberately
667
+ * left unpinned. The height bound lives in `className`, which the
668
+ * component cannot inspect, so the supplied label tells it the rows
669
+ * scroll and the wrapper becomes a focusable region. Don't pass it on a
670
+ * table that never scrolls: the region would be an inert tab stop.
671
+ *
672
+ * Give each table on a page a distinct label ("Invoices", "Team
673
+ * members") — several region landmarks sharing the default name violate
674
+ * axe's landmark-unique rule and are indistinguishable to screen-reader
675
+ * users.
523
676
  * @default "Scrollable table"
524
677
  */
525
678
  scrollRegionLabel?: string;
@@ -553,6 +706,73 @@ export interface DataTableProps<TData> {
553
706
  renderExpandedContent?: (row: Row<TData>) => React.ReactNode;
554
707
  }
555
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
+
556
776
  /**
557
777
  * Generic DataTable renderer.
558
778
  *
@@ -575,111 +795,293 @@ export interface DataTableProps<TData> {
575
795
  *
576
796
  * @example
577
797
  * // One slot inside a gapped parent (dialog, card, page section).
578
- * // min-h-0/flex-1 keep the table scrollable in height-capped parents.
798
+ * // min-h-0/flex-1 keep the table scrollable in height-capped parents;
799
+ * // the outer wrapper is the scroll container, so stickyHeader keeps the
800
+ * // column headers visible while the rows scroll (DS-912).
579
801
  * <div className="flex min-h-0 flex-1 flex-col">
580
802
  * <DataTableToolbar dataHook="toolbar-top">
581
803
  * <DataTableToolbarLeft>{heading or search}</DataTableToolbarLeft>
582
804
  * <DataTableToolbarRight>{filters}</DataTableToolbarRight>
583
805
  * </DataTableToolbar>
584
- * <DataTable table={table} dataHook="my-table" className="min-h-0 flex-1 overflow-y-auto" />
806
+ * <DataTable table={table} dataHook="my-table" stickyHeader className="min-h-0 flex-1" />
585
807
  * <DataTableToolbar dataHook="toolbar-bottom">
586
808
  * <DataTableToolbarLeft>{selection counter}</DataTableToolbarLeft>
587
809
  * <DataTableToolbarRight>{pagination}</DataTableToolbarRight>
588
810
  * </DataTableToolbar>
589
811
  * </div>
590
812
  */
591
- export function DataTable<TData>({
592
- table,
593
- dataHook,
594
- trackingEl,
595
- trackingLabel,
596
- isLoading = false,
597
- skeletonRowCount,
598
- noResultsMessage = "No results.",
599
- stickyHeader = false,
600
- className,
601
- layout,
602
- minWidth,
603
- scrollRegionLabel,
604
- footer,
605
- getRowClassName,
606
- renderExpandedContent,
607
- }: 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
+ ) {
608
841
  const columnCount = table.getVisibleLeafColumns().length;
609
842
  const resolvedSkeletonCount =
610
- skeletonRowCount ?? table.getState().pagination.pageSize ?? 10;
843
+ skeletonRowCount ?? table.getState().pagination.pageSize ?? 20;
844
+
845
+ // A focusable scroll region whenever scrolling is part of the contract:
846
+ // minWidth (horizontal), stickyHeader, or an explicit scrollRegionLabel
847
+ // (the consumer bounds the height via className, which we cannot see,
848
+ // so the sticky intent — or the supplied label — is the signal that
849
+ // keyboard users must be able to focus and scroll the rows). One const
850
+ // gates both the focus classes and the region props so the two can
851
+ // never drift apart.
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;
611
868
 
612
869
  return (
613
870
  <div
614
- aria-busy={isLoading || undefined}
615
- className={cn("border-border overflow-auto rounded-md border", className)}
871
+ ref={viewRef}
872
+ // `relative`: the sr-only live region below positions absolutely and
873
+ // must not escape to a distant containing block (double-scrollbar bug).
874
+ className={cn(
875
+ // `scrollbar` themes the native scrollbar with DS colors — the same
876
+ // treatment Command/Combobox lists use for bounded scroll containers.
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",
884
+ isScrollRegion && "focus-visible:shadow-default outline-none",
885
+ className
886
+ )}
887
+ data-frame={frame}
616
888
  data-hook={dataHook}
889
+ data-overflowing={pageSticky && overflowing ? "" : undefined}
617
890
  data-slot="data-table-view"
891
+ data-sticky-header={
892
+ stickyHeader === false ? undefined : pageSticky ? "page" : "self"
893
+ }
618
894
  data-tracking-el={trackingEl}
619
895
  data-tracking-label={trackingLabel}
896
+ {...(isScrollRegion ? scrollRegionProps(scrollRegionLabel) : undefined)}
620
897
  >
621
- <Table
622
- dataHook={`${dataHook}-table`}
623
- layout={layout}
624
- minWidth={minWidth}
625
- scrollRegionLabel={scrollRegionLabel}
626
- >
627
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
628
- <TableBody>
629
- {isLoading ? (
630
- <>
631
- <LoadingRows
632
- colCount={columnCount}
633
- rowCount={resolvedSkeletonCount}
634
- />
635
- <TableRow className="sr-only">
636
- <TableCell colSpan={columnCount}>
637
- <div aria-live="polite" role="status">
638
- Loading data…
639
- </div>
640
- </TableCell>
641
- </TableRow>
642
- </>
643
- ) : (
644
- <>
645
- {table.getRowModel().rows.length > 0 ? (
646
- table
647
- .getRowModel()
648
- .rows.map((row) => (
649
- <DataTableRow
650
- key={row.id}
651
- columnCount={columnCount}
652
- getRowClassName={getRowClassName}
653
- renderExpandedContent={renderExpandedContent}
654
- row={row}
655
- />
656
- ))
657
- ) : (
658
- <TableRow>
659
- <TableCell align="center" colSpan={columnCount} size="lg">
660
- {/* Padded for a block, not for a line: an `EmptyState` passed
661
- as the message needs the same room here that it gets
662
- anywhere else, and a prop API gives the consumer nowhere
663
- to add it. 24 rather than 32, because this sits inside
664
- the cell's own 8: together they give the block its 32,
665
- and a one-line message still measures under `size="lg"`'s
666
- min-height, so the plain-string row does not move. */}
667
- <div aria-live="polite" className="py-6" role="status">
668
- {noResultsMessage}
898
+ {/* Always mounted so screen readers reliably announce the text change —
899
+ a live region inserted together with its content can be skipped. */}
900
+ <div aria-live="polite" className="sr-only" role="status">
901
+ {refetching ? (refetchingLabel ?? "Loading results…") : null}
902
+ </div>
903
+ <DataTableRefetchingContext.Provider value={refetching}>
904
+ <Table
905
+ // Busy on the table, never on the wrapper: `aria-busy` on an
906
+ // ancestor defers the live region above until the busy state clears,
907
+ // by which point its text is gone and nothing is announced.
908
+ aria-busy={isLoading || refetching || undefined}
909
+ dataHook={`${dataHook}-table`}
910
+ frame={frame}
911
+ layout={layout}
912
+ minWidth={minWidth}
913
+ rowDividers={rowDividers}
914
+ scrollOwner="parent"
915
+ size={size}
916
+ >
917
+ <DataTableHeaderRows
918
+ sticky={
919
+ pageSticky
920
+ ? !overflowing && "page"
921
+ : stickyHeader === true && "self"
922
+ }
923
+ table={table}
924
+ />
925
+ <TableBody>
926
+ {isLoading ? (
927
+ <>
928
+ <LoadingRows
929
+ colCount={columnCount}
930
+ rowCount={resolvedSkeletonCount}
931
+ />
932
+ <TableRow className="sr-only">
933
+ <TableCell colSpan={columnCount}>
934
+ <div aria-live="polite" role="status">
935
+ {loadingLabel ?? "Loading data…"}
669
936
  </div>
670
937
  </TableCell>
671
938
  </TableRow>
672
- )}
673
- </>
674
- )}
675
- </TableBody>
676
- {footer}
677
- </Table>
939
+ </>
940
+ ) : (
941
+ <>
942
+ {table.getRowModel().rows.length > 0 ? (
943
+ table
944
+ .getRowModel()
945
+ .rows.map((row) => (
946
+ <DataTableRow
947
+ key={row.id}
948
+ columnCount={columnCount}
949
+ getRowClassName={getRowClassName}
950
+ renderExpandedContent={renderExpandedContent}
951
+ row={row}
952
+ />
953
+ ))
954
+ ) : (
955
+ <TableEmpty colSpan={columnCount}>
956
+ {noResultsMessage ?? (
957
+ <DataTableNoResults
958
+ dataHook={dataHook}
959
+ description={noResultsDescription}
960
+ table={table}
961
+ title={noResultsTitle}
962
+ />
963
+ )}
964
+ </TableEmpty>
965
+ )}
966
+ </>
967
+ )}
968
+ </TableBody>
969
+ {footer}
970
+ </Table>
971
+ </DataTableRefetchingContext.Provider>
678
972
  </div>
679
973
  );
680
974
  }
681
975
 
682
- 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";
988
+
989
+ /* -------------------------------------------------------------------------------------------------
990
+ * Internal: settled-sort override store (DS-916)
991
+ *
992
+ * During a server-side sort refetch, `DataTableColumnHeader` keeps announcing
993
+ * the settled sort order — the one the visible rows still reflect. ARIA
994
+ * requires `aria-sort` on the `<th>` (the columnheader element), which is
995
+ * rendered by `DataTableHeaderRows`, above the header button. This store is
996
+ * the single source of the per-column settled direction, with no consumer
997
+ * wiring: the button publishes every render from a layout effect (the live
998
+ * direction while idle, the held one while `loading`), the cell subscribes.
999
+ * Living at the table level, the value survives header remounts — the common
1000
+ * wiring rebuilds the columns array when the fetching flag flips, which
1001
+ * remounts every header through flexRender and would wipe header-local
1002
+ * state. Outside a DataTable (no provider) both sides fall back to the live
1003
+ * TanStack sort state.
1004
+ * -----------------------------------------------------------------------------------------------*/
1005
+
1006
+ type SortOverride = "asc" | "desc" | false;
1007
+
1008
+ interface SortOverrideEntry {
1009
+ /**
1010
+ * What the header announces — the settled order while `loading`, the live
1011
+ * one while idle.
1012
+ */
1013
+ displayed: SortOverride;
1014
+ /**
1015
+ * The live TanStack direction at the same publish. It differs from
1016
+ * `displayed` exactly while a settled order is being held, which is how the
1017
+ * store identifies the column whose click requested the refetch.
1018
+ */
1019
+ live: SortOverride;
1020
+ }
1021
+
1022
+ interface SortOverrideStore {
1023
+ set: (columnId: string, entry: SortOverrideEntry | null) => void;
1024
+ get: (columnId: string) => SortOverrideEntry | null;
1025
+ /**
1026
+ * Whether any column is holding a settled order its live sort has moved
1027
+ * away from — i.e. the in-flight refetch has an identifiable requesting
1028
+ * column. When it does, only that column shows the spinner; when it does
1029
+ * not (the flag flipped on a later render, e.g. wrapped in
1030
+ * `useDelayedPending`), every sorted column falls back to showing it.
1031
+ */
1032
+ anyHeld: () => boolean;
1033
+ subscribe: (listener: () => void) => () => void;
1034
+ }
1035
+
1036
+ const DataTableSortOverridesContext =
1037
+ React.createContext<SortOverrideStore | null>(null);
1038
+
1039
+ const noopSubscribe = () => () => {};
1040
+
1041
+ function useSortOverrideStore(): SortOverrideStore {
1042
+ const [store] = React.useState<SortOverrideStore>(() => {
1043
+ const entries = new Map<string, SortOverrideEntry>();
1044
+ const listeners = new Set<() => void>();
1045
+ const read = (columnId: string): SortOverrideEntry | null =>
1046
+ entries.get(columnId) ?? null;
1047
+ return {
1048
+ set: (columnId, entry) => {
1049
+ const current = read(columnId);
1050
+ if (
1051
+ current === entry ||
1052
+ (current !== null &&
1053
+ entry !== null &&
1054
+ current.displayed === entry.displayed &&
1055
+ current.live === entry.live)
1056
+ ) {
1057
+ return;
1058
+ }
1059
+ if (entry === null) {
1060
+ entries.delete(columnId);
1061
+ } else {
1062
+ entries.set(columnId, entry);
1063
+ }
1064
+ listeners.forEach((listener) => listener());
1065
+ },
1066
+ get: read,
1067
+ anyHeld: () => {
1068
+ for (const entry of entries.values()) {
1069
+ if (entry.displayed !== entry.live) {
1070
+ return true;
1071
+ }
1072
+ }
1073
+ return false;
1074
+ },
1075
+ subscribe: (listener) => {
1076
+ listeners.add(listener);
1077
+ return () => {
1078
+ listeners.delete(listener);
1079
+ };
1080
+ },
1081
+ };
1082
+ });
1083
+ return store;
1084
+ }
683
1085
 
684
1086
  /**
685
1087
  * Internal: render all header groups with `aria-sort` attributes.
@@ -687,48 +1089,86 @@ DataTable.displayName = "DataTable";
687
1089
  */
688
1090
  function DataTableHeaderRows<TData>({
689
1091
  table,
690
- stickyHeader,
1092
+ sticky,
691
1093
  }: {
692
1094
  table: TanStackTable<TData>;
693
- 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";
694
1102
  }) {
1103
+ const sortOverrides = useSortOverrideStore();
695
1104
  return (
696
- <TableHeader className={cn(stickyHeader && "sticky top-0 z-10")}>
697
- {table.getHeaderGroups().map((headerGroup) => (
698
- <TableRow key={headerGroup.id}>
699
- {headerGroup.headers.map((header) => {
700
- const sortDirection = header.column.getCanSort()
701
- ? header.column.getIsSorted()
702
- : false;
703
- const ariaSort =
704
- sortDirection === "asc"
705
- ? "ascending"
706
- : sortDirection === "desc"
707
- ? "descending"
708
- : header.column.getCanSort()
709
- ? "none"
710
- : undefined;
711
- const meta = header.column.columnDef.meta;
712
- return (
713
- <TableHead
714
- key={header.id}
715
- aria-sort={ariaSort}
716
- colSpan={header.colSpan}
717
- minWidth={meta?.minWidth}
718
- width={meta?.width}
719
- >
720
- {header.isPlaceholder
721
- ? null
722
- : flexRender(
723
- header.column.columnDef.header,
724
- header.getContext()
725
- )}
726
- </TableHead>
727
- );
728
- })}
729
- </TableRow>
730
- ))}
731
- </TableHeader>
1105
+ <DataTableSortOverridesContext.Provider value={sortOverrides}>
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
+ >
1112
+ {table.getHeaderGroups().map((headerGroup) => (
1113
+ <TableRow key={headerGroup.id}>
1114
+ {headerGroup.headers.map((header) => (
1115
+ <DataTableHeadCell key={header.id} header={header} />
1116
+ ))}
1117
+ </TableRow>
1118
+ ))}
1119
+ </TableHeader>
1120
+ </DataTableSortOverridesContext.Provider>
1121
+ );
1122
+ }
1123
+
1124
+ /**
1125
+ * Internal: one `<th>` of the header row.
1126
+ *
1127
+ * `aria-sort` belongs on the columnheader element, but during a sort refetch
1128
+ * the direction the rows still reflect is tracked inside
1129
+ * `DataTableColumnHeader` (rendered below this cell). The cell subscribes to
1130
+ * that settled direction through the override store, so the `<th>` and the
1131
+ * sort button never announce two different orders (DS-916).
1132
+ */
1133
+ function DataTableHeadCell<TData>({
1134
+ header,
1135
+ }: {
1136
+ header: Header<TData, unknown>;
1137
+ }) {
1138
+ const overrides = React.useContext(DataTableSortOverridesContext);
1139
+ const override = React.useSyncExternalStore(
1140
+ overrides ? overrides.subscribe : noopSubscribe,
1141
+ () =>
1142
+ overrides ? (overrides.get(header.column.id)?.displayed ?? null) : null,
1143
+ // Server render: no header has published yet — fall back to live state.
1144
+ () => null
1145
+ );
1146
+ const canSort = header.column.getCanSort();
1147
+ const sortDirection = canSort
1148
+ ? (override ?? header.column.getIsSorted())
1149
+ : false;
1150
+ const ariaSort =
1151
+ sortDirection === "asc"
1152
+ ? "ascending"
1153
+ : sortDirection === "desc"
1154
+ ? "descending"
1155
+ : canSort
1156
+ ? "none"
1157
+ : undefined;
1158
+ const meta = header.column.columnDef.meta;
1159
+ return (
1160
+ <TableHead
1161
+ aria-sort={ariaSort}
1162
+ className={meta?.pinned === "left" ? PINNED_HEAD_CLASS : undefined}
1163
+ colSpan={header.colSpan}
1164
+ data-pinned={meta?.pinned === "left" ? "left" : undefined}
1165
+ minWidth={meta?.minWidth}
1166
+ width={meta?.width}
1167
+ >
1168
+ {header.isPlaceholder
1169
+ ? null
1170
+ : flexRender(header.column.columnDef.header, header.getContext())}
1171
+ </TableHead>
732
1172
  );
733
1173
  }
734
1174
 
@@ -776,17 +1216,33 @@ function DataTableRow<TData>({
776
1216
  // table head's bg-muted at ANY depth; other expanded-zone rows
777
1217
  // (sub-rows) get the lighter accent wash.
778
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))]",
779
1227
  getRowClassName?.(row)
780
1228
  )}
781
1229
  data-depth={row.depth}
782
1230
  data-expanded={canExpand ? String(expanded) : undefined}
783
1231
  data-state={row.getIsSelected() ? "selected" : undefined}
784
1232
  >
785
- {row.getVisibleCells().map((cell) => (
786
- <TableCell key={cell.id}>
787
- {flexRender(cell.column.columnDef.cell, cell.getContext())}
788
- </TableCell>
789
- ))}
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
+ })}
790
1246
  </TableRow>
791
1247
  {panel != null && (
792
1248
  // No data-depth here: panels are not data rows, and sharing the
@@ -846,8 +1302,15 @@ function LoadingRows({
846
1302
  */
847
1303
  export interface VirtualizedDataTableProps<TData> extends Omit<
848
1304
  DataTableProps<TData>,
849
- "renderExpandedContent"
1305
+ "renderExpandedContent" | "stickyHeader"
850
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;
851
1314
  /**
852
1315
  * Height of the scroll container in pixels. Required — virtualization
853
1316
  * needs a bounded viewport. Pass a CSS value via `className` instead
@@ -857,8 +1320,10 @@ export interface VirtualizedDataTableProps<TData> extends Omit<
857
1320
  height?: number;
858
1321
  /**
859
1322
  * Estimated height of a single row in pixels. The virtualizer uses this
860
- * for initial layout before measuring real DOM nodes.
861
- * @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"`)
862
1327
  */
863
1328
  estimateSize?: number;
864
1329
  /**
@@ -889,34 +1354,47 @@ export interface VirtualizedDataTableProps<TData> extends Omit<
889
1354
  * table={table}
890
1355
  * dataHook="big-table"
891
1356
  * height={600}
892
- * estimateSize={48}
893
1357
  * />
894
1358
  * );
895
1359
  */
896
- export function VirtualizedDataTable<TData>({
897
- table,
898
- dataHook,
899
- trackingEl,
900
- trackingLabel,
901
- isLoading = false,
902
- skeletonRowCount,
903
- noResultsMessage = "No results.",
904
- stickyHeader = false,
905
- className,
906
- layout,
907
- minWidth,
908
- scrollRegionLabel,
909
- footer,
910
- getRowClassName,
911
- height,
912
- estimateSize = 48,
913
- overscan = 5,
914
- }: 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];
915
1391
  const columnCount = table.getVisibleLeafColumns().length;
916
1392
  const resolvedSkeletonCount =
917
- skeletonRowCount ?? table.getState().pagination.pageSize ?? 10;
1393
+ skeletonRowCount ?? table.getState().pagination.pageSize ?? 20;
918
1394
 
919
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!, []);
920
1398
 
921
1399
  const rows = table.getRowModel().rows;
922
1400
 
@@ -941,79 +1419,120 @@ export function VirtualizedDataTable<TData>({
941
1419
  return (
942
1420
  <div
943
1421
  ref={scrollContainerRef}
944
- aria-busy={isLoading || undefined}
945
- className={cn("border-border overflow-auto rounded-md border", className)}
1422
+ // `relative`: the sr-only live region below positions absolutely and
1423
+ // must not escape to a distant containing block (double-scrollbar bug).
1424
+ className={cn(
1425
+ // `scrollbar` themes the native scrollbar with DS colors (the
1426
+ // Command/Combobox treatment for bounded scroll containers).
1427
+ "scrollbar relative overflow-auto",
1428
+ frame === "own" && "border-border rounded-md border",
1429
+ // Always a focusable scroll region: virtualization requires a
1430
+ // bounded viewport (height or a className bound), so this wrapper
1431
+ // always scrolls vertically and keyboard users need to reach it.
1432
+ "focus-visible:shadow-default outline-none",
1433
+ className
1434
+ )}
1435
+ data-frame={frame}
946
1436
  data-hook={dataHook}
947
1437
  data-slot="data-table-view"
948
1438
  data-tracking-el={trackingEl}
949
1439
  data-tracking-label={trackingLabel}
950
1440
  style={height != null ? { height } : undefined}
1441
+ {...scrollRegionProps(scrollRegionLabel)}
951
1442
  >
952
- <Table
953
- dataHook={`${dataHook}-table`}
954
- layout={layout}
955
- minWidth={minWidth}
956
- scrollRegionLabel={scrollRegionLabel}
957
- >
958
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
959
- <TableBody>
960
- {isLoading ? (
961
- <>
962
- <LoadingRows
963
- colCount={columnCount}
964
- rowCount={resolvedSkeletonCount}
965
- />
966
- <TableRow className="sr-only">
967
- <TableCell colSpan={columnCount}>
968
- <div aria-live="polite" role="status">
969
- Loading data…
970
- </div>
971
- </TableCell>
972
- </TableRow>
973
- </>
974
- ) : rows.length > 0 ? (
975
- <>
976
- {paddingTop > 0 && (
977
- <tr aria-hidden="true">
978
- <td colSpan={columnCount} style={{ height: paddingTop }} />
979
- </tr>
980
- )}
981
- {virtualItems.map((virtualItem) => {
982
- const row = rows[virtualItem.index]!;
983
- return (
984
- <DataTableRow
985
- key={row.id}
986
- columnCount={columnCount}
987
- getRowClassName={getRowClassName}
988
- row={row}
1443
+ {/* Always mounted so screen readers reliably announce the text change —
1444
+ a live region inserted together with its content can be skipped. */}
1445
+ <div aria-live="polite" className="sr-only" role="status">
1446
+ {refetching ? (refetchingLabel ?? "Loading results…") : null}
1447
+ </div>
1448
+ <DataTableRefetchingContext.Provider value={refetching}>
1449
+ <Table
1450
+ // Busy on the table, never on the wrapper: `aria-busy` on an
1451
+ // ancestor defers the live region above until the busy state clears,
1452
+ // by which point its text is gone and nothing is announced.
1453
+ aria-busy={isLoading || refetching || undefined}
1454
+ dataHook={`${dataHook}-table`}
1455
+ frame={frame}
1456
+ layout={layout}
1457
+ minWidth={minWidth}
1458
+ rowDividers={rowDividers}
1459
+ scrollOwner="parent"
1460
+ size={size}
1461
+ >
1462
+ <DataTableHeaderRows sticky={stickyHeader && "self"} table={table} />
1463
+ <TableBody>
1464
+ {isLoading ? (
1465
+ <>
1466
+ <LoadingRows
1467
+ colCount={columnCount}
1468
+ rowCount={resolvedSkeletonCount}
1469
+ />
1470
+ <TableRow className="sr-only">
1471
+ <TableCell colSpan={columnCount}>
1472
+ <div aria-live="polite" role="status">
1473
+ {loadingLabel ?? "Loading data…"}
1474
+ </div>
1475
+ </TableCell>
1476
+ </TableRow>
1477
+ </>
1478
+ ) : rows.length > 0 ? (
1479
+ <>
1480
+ {paddingTop > 0 && (
1481
+ <tr aria-hidden="true">
1482
+ <td colSpan={columnCount} style={{ height: paddingTop }} />
1483
+ </tr>
1484
+ )}
1485
+ {virtualItems.map((virtualItem) => {
1486
+ const row = rows[virtualItem.index]!;
1487
+ return (
1488
+ <DataTableRow
1489
+ key={row.id}
1490
+ columnCount={columnCount}
1491
+ getRowClassName={getRowClassName}
1492
+ row={row}
1493
+ />
1494
+ );
1495
+ })}
1496
+ {paddingBottom > 0 && (
1497
+ <tr aria-hidden="true">
1498
+ <td
1499
+ colSpan={columnCount}
1500
+ style={{ height: paddingBottom }}
1501
+ />
1502
+ </tr>
1503
+ )}
1504
+ </>
1505
+ ) : (
1506
+ <TableEmpty colSpan={columnCount}>
1507
+ {noResultsMessage ?? (
1508
+ <DataTableNoResults
1509
+ dataHook={dataHook}
1510
+ description={noResultsDescription}
1511
+ table={table}
1512
+ title={noResultsTitle}
989
1513
  />
990
- );
991
- })}
992
- {paddingBottom > 0 && (
993
- <tr aria-hidden="true">
994
- <td colSpan={columnCount} style={{ height: paddingBottom }} />
995
- </tr>
996
- )}
997
- </>
998
- ) : (
999
- <TableRow>
1000
- <TableCell align="center" colSpan={columnCount} size="lg">
1001
- {/* Padded for a block — see the note on the non-virtualised
1002
- table's no-results cell. */}
1003
- <div aria-live="polite" className="py-6" role="status">
1004
- {noResultsMessage}
1005
- </div>
1006
- </TableCell>
1007
- </TableRow>
1008
- )}
1009
- </TableBody>
1010
- {footer}
1011
- </Table>
1514
+ )}
1515
+ </TableEmpty>
1516
+ )}
1517
+ </TableBody>
1518
+ {footer}
1519
+ </Table>
1520
+ </DataTableRefetchingContext.Provider>
1012
1521
  </div>
1013
1522
  );
1014
1523
  }
1015
1524
 
1016
- 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";
1017
1536
 
1018
1537
  /* -------------------------------------------------------------------------------------------------
1019
1538
  * DataTableColumnHeader (sortable header)
@@ -1042,9 +1561,35 @@ export interface DataTableColumnHeaderProps<
1042
1561
  /**
1043
1562
  * Builds the accessible label for the sort button.
1044
1563
  * Receives the column title and current sort direction (`"asc"`, `"desc"`, or `false`).
1564
+ * While `loading` is true the direction passed is the settled one — the
1565
+ * order the visible rows still reflect, not the one just requested.
1045
1566
  * @default (title, dir) => `Sort by ${title}${dir ? `, currently ${dir === "asc" ? "ascending" : "descending"}` : ""}`
1046
1567
  */
1047
1568
  getSortLabel?: (title: string, direction: "asc" | "desc" | false) => string;
1569
+ /**
1570
+ * Marks a server-side sort refetch as in flight. Pass the same fetching
1571
+ * flag to every column's header: every sort button sets `aria-busy` and
1572
+ * becomes inert — clicks are ignored to prevent a double-fetch — without a
1573
+ * disabled look, and the column whose click requested the refetch (the one
1574
+ * whose requested order differs from the settled one it still shows) swaps
1575
+ * its sort icon for a spinner. Icons, labels and the `<th>`'s `aria-sort`
1576
+ * keep describing the settled sort order — the order the visible rows still
1577
+ * reflect — until the flag clears.
1578
+ *
1579
+ * The settled order is captured when the sort change and this flag land in
1580
+ * the same render commit: a click handler that sets both, or React Query's
1581
+ * `isFetching` in the same batch — the normal wirings. It is tracked at the
1582
+ * table level, so it survives the columns array being rebuilt (and every
1583
+ * header remounting) when the flag flips. A flag that only flips on a later
1584
+ * render (e.g. wrapped in `useDelayedPending`) degrades gracefully to
1585
+ * announcing the requested order (the standard behavior of sortable
1586
+ * tables), with the spinner on the sorted column or columns — the
1587
+ * requesting one can no longer be told apart; button and `<th>` stay
1588
+ * consistent with each other either way. Rendered standalone (outside a
1589
+ * DataTable), the settled order is held in header-local state instead.
1590
+ * @default false
1591
+ */
1592
+ loading?: boolean;
1048
1593
  }
1049
1594
 
1050
1595
  /**
@@ -1077,7 +1622,74 @@ export function DataTableColumnHeader<TData, TValue>({
1077
1622
  trackingLabel,
1078
1623
  align = "left",
1079
1624
  getSortLabel,
1625
+ loading = false,
1080
1626
  }: DataTableColumnHeaderProps<TData, TValue>) {
1627
+ const currentSort = column.getIsSorted();
1628
+ // Clicking a header flips TanStack's sort state immediately, but during a
1629
+ // server-side refetch the rows still show the previous order. The settled
1630
+ // sort — what the visible rows actually reflect — lives in the table-level
1631
+ // override store, not in local state: the common wiring rebuilds the
1632
+ // columns array when the fetching flag flips, which remounts every header
1633
+ // through flexRender and would wipe component state. The store (owned by
1634
+ // DataTableHeaderRows) survives those remounts, and a remounting header
1635
+ // reads the previous value during render, before the old instance's
1636
+ // cleanup runs (DS-916).
1637
+ const sortOverrides = React.useContext(DataTableSortOverridesContext);
1638
+ const storedSort = React.useSyncExternalStore(
1639
+ sortOverrides ? sortOverrides.subscribe : noopSubscribe,
1640
+ () =>
1641
+ sortOverrides ? (sortOverrides.get(column.id)?.displayed ?? null) : null,
1642
+ () => null
1643
+ );
1644
+ // Standalone fallback: rendered outside a DataTable (no provider) the
1645
+ // settled order lives in local state instead — the previous-render-value
1646
+ // pattern. It cannot survive a header remount, but without the table there
1647
+ // is no DataTableHeaderRows rebuilding the columns array either, so the
1648
+ // remount hazard the store exists for does not apply.
1649
+ const [localSettled, setLocalSettled] = React.useState(currentSort);
1650
+ if (!sortOverrides && !loading && localSettled !== currentSort) {
1651
+ setLocalSettled(currentSort);
1652
+ }
1653
+ const settledSort = sortOverrides
1654
+ ? (storedSort ?? currentSort)
1655
+ : localSettled;
1656
+ const displayedSort = loading ? settledSort : currentSort;
1657
+
1658
+ // The column whose click requested the refetch is the one holding a settled
1659
+ // order its live sort has moved away from — only it gets the spinner, so a
1660
+ // multi-sorted table never animates every sorted header at once. When no
1661
+ // column is held (the flag flipped on a later render — e.g. wrapped in
1662
+ // `useDelayedPending` — so the settled order was never captured), fall back
1663
+ // to showing the spinner on the sorted column(s).
1664
+ const heldSelf = displayedSort !== currentSort;
1665
+ const storeAnyHeld = React.useSyncExternalStore(
1666
+ sortOverrides ? sortOverrides.subscribe : noopSubscribe,
1667
+ () => (sortOverrides ? sortOverrides.anyHeld() : false),
1668
+ () => false
1669
+ );
1670
+ const anyHeld = sortOverrides ? storeAnyHeld : heldSelf;
1671
+ const sortRefetching =
1672
+ loading && (heldSelf || (!anyHeld && currentSort !== false));
1673
+
1674
+ // Publish what this header announces so the enclosing `<th>` mirrors it in
1675
+ // `aria-sort` — the two must never contradict each other. While idle the
1676
+ // store tracks the live sort (the rows reflect it); while loading it holds
1677
+ // the settled value. A layout effect flushes before paint, so no frame is
1678
+ // painted with the `<th>` and the button disagreeing. Rendered standalone
1679
+ // (no provider) the local fallback above holds the settled order instead.
1680
+ React.useLayoutEffect(() => {
1681
+ if (!sortOverrides) {
1682
+ return;
1683
+ }
1684
+ sortOverrides.set(column.id, {
1685
+ displayed: displayedSort,
1686
+ live: currentSort,
1687
+ });
1688
+ return () => {
1689
+ sortOverrides.set(column.id, null);
1690
+ };
1691
+ }, [sortOverrides, column.id, displayedSort, currentSort]);
1692
+
1081
1693
  if (!column.getCanSort()) {
1082
1694
  return (
1083
1695
  <div
@@ -1097,20 +1709,19 @@ export function DataTableColumnHeader<TData, TValue>({
1097
1709
  );
1098
1710
  }
1099
1711
 
1100
- const sortState = column.getIsSorted();
1101
1712
  // First click on an unsorted column follows the column def's explicit
1102
1713
  // `sortDescFirst`; later clicks reverse the current direction. TanStack's
1103
1714
  // `getFirstSortDir()` is not used here — its automatic numeric detection
1104
1715
  // would silently flip existing tables to descending-first (DS-953).
1105
1716
  const nextSortDesc =
1106
- sortState === false
1717
+ currentSort === false
1107
1718
  ? column.columnDef.sortDescFirst === true
1108
- : sortState === "asc";
1719
+ : currentSort === "asc";
1109
1720
  const sortLabel = getSortLabel
1110
- ? getSortLabel(title, sortState)
1111
- : sortState === "desc"
1721
+ ? getSortLabel(title, displayedSort)
1722
+ : displayedSort === "desc"
1112
1723
  ? `Sort by ${title}, currently descending`
1113
- : sortState === "asc"
1724
+ : displayedSort === "asc"
1114
1725
  ? `Sort by ${title}, currently ascending`
1115
1726
  : `Sort by ${title}`;
1116
1727
 
@@ -1127,21 +1738,30 @@ export function DataTableColumnHeader<TData, TValue>({
1127
1738
  data-tracking-label={trackingLabel}
1128
1739
  >
1129
1740
  <Button
1741
+ aria-busy={loading ? "true" : undefined}
1130
1742
  aria-label={sortLabel}
1131
1743
  className="text-muted-foreground text-label h-auto p-0 font-semibold"
1132
1744
  dataHook={dataHook || `column-header-${column.id}`}
1133
1745
  size="sm"
1134
1746
  variant="ghost"
1135
- onClick={() => column.toggleSorting(nextSortDesc)}
1747
+ onClick={() => {
1748
+ // Inert while a refetch is in flight — busy, not disabled, so the
1749
+ // button keeps its look and stays focusable but cannot double-fetch.
1750
+ if (!loading) {
1751
+ column.toggleSorting(nextSortDesc);
1752
+ }
1753
+ }}
1136
1754
  >
1137
1755
  <span aria-hidden="true">{title}</span>
1138
1756
  <span
1139
1757
  aria-hidden="true"
1140
1758
  className="flex size-3 items-center justify-center"
1141
1759
  >
1142
- {sortState === "desc" ? (
1760
+ {sortRefetching ? (
1761
+ <Spinner size="sm" />
1762
+ ) : displayedSort === "desc" ? (
1143
1763
  <ArrowDown size={12} />
1144
- ) : sortState === "asc" ? (
1764
+ ) : displayedSort === "asc" ? (
1145
1765
  <ArrowUp size={12} />
1146
1766
  ) : (
1147
1767
  <ArrowUpDown size={12} />
@@ -1177,8 +1797,49 @@ export interface DataTableSearchProps<TData> extends Omit<
1177
1797
  placeholder?: string;
1178
1798
  /** Accessible label for the clear button. @default "Clear search" */
1179
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;
1811
+ /**
1812
+ * Search refetch in flight — the leading search icon swaps to a spinner
1813
+ * and the group sets `aria-busy`. The input stays fully editable, and the
1814
+ * clear button keeps its place in the trailing slot whenever there is a
1815
+ * value: the way out of a slow search never disappears.
1816
+ * @default false
1817
+ */
1818
+ loading?: boolean;
1819
+ /**
1820
+ * Debounce between keystrokes and the table's global filter, in
1821
+ * milliseconds. The input echoes instantly; the filter (and any server
1822
+ * refetch keyed off it) only updates after the pause. Clearing via the
1823
+ * clear button skips the debounce.
1824
+ *
1825
+ * The default is derived from the table's filtering mode: `300` when the
1826
+ * table uses `manualFiltering` (server-side — one refetch per pause,
1827
+ * "debounce the request"), `0` for client-side filtering (rows keep
1828
+ * narrowing per keystroke, as before). Pass a value to override either mode.
1829
+ * @default table.options.manualFiltering ? 300 : 0
1830
+ */
1831
+ debounceMs?: number;
1180
1832
  }
1181
1833
 
1834
+ /**
1835
+ * How many of DataTableSearch's own unacknowledged filter writes are
1836
+ * remembered for telling them apart from external writes. Writes echo back
1837
+ * within a render or two even through a transition- or URL-synced filter, so
1838
+ * anything beyond this is a consumer that never echoes at all — the cap keeps
1839
+ * that wiring from growing the list forever.
1840
+ */
1841
+ const MAX_TRACKED_FILTER_PUSHES = 10;
1842
+
1182
1843
  /**
1183
1844
  * Search input for filtering DataTable rows.
1184
1845
  *
@@ -1187,53 +1848,192 @@ export interface DataTableSearchProps<TData> extends Omit<
1187
1848
  * customize width or shape.
1188
1849
  *
1189
1850
  * Uses the table's global filter (requires `enableGlobalFiltering` on the hook).
1851
+ *
1852
+ * With `manualFiltering` (server-side search) keystrokes echo in the input
1853
+ * instantly while the global filter — and any server refetch keyed off it —
1854
+ * only updates after `debounceMs` of inactivity. Client-side filtering stays
1855
+ * synchronous: rows narrow per keystroke, exactly as the Filtering pattern
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.
1190
1860
  */
1191
- export function DataTableSearch<TData>({
1192
- table,
1193
- ariaLabel,
1194
- placeholder,
1195
- clearSearchAriaLabel,
1196
- ...inputGroupProps
1197
- }: 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
+ ) {
1198
1874
  const filterValue = (table.getState().globalFilter ?? "") as string;
1875
+ const [inputValue, setInputValue] = React.useState(filterValue);
1876
+ // manualFiltering is the consumer's own declaration that filter changes are
1877
+ // server requests — those get the 300ms debounce (DS-916). Without it the
1878
+ // filter is an in-memory narrowing the reader watches, so it stays
1879
+ // per-keystroke. An explicit debounceMs wins in either mode.
1880
+ const effectiveDebounceMs =
1881
+ debounceMs ?? (table.options.manualFiltering === true ? 300 : 0);
1882
+
1883
+ // The debounce is a plain timer owned by this component — no debounced
1884
+ // value lives in state. A remembered value is exactly what made clearing
1885
+ // and then retyping the same query silently skip its push (the memory
1886
+ // bailed out on the equal value and the filter never updated), and what
1887
+ // made a mode flip replay a stale value over the live filter.
1888
+ const pushTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
1889
+ const cancelPendingPush = React.useCallback(() => {
1890
+ if (pushTimerRef.current !== null) {
1891
+ clearTimeout(pushTimerRef.current);
1892
+ pushTimerRef.current = null;
1893
+ }
1894
+ }, []);
1895
+ React.useEffect(() => cancelPendingPush, [cancelPendingPush]);
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
+
1903
+ // The latest input value, readable from the timer callback. Synced in a
1904
+ // passive effect (never during render); the shortest debounce that
1905
+ // schedules a timer still fires long after the commit's effects, so a
1906
+ // pending push always compares against the current value.
1907
+ const inputValueRef = React.useRef(inputValue);
1908
+ React.useEffect(() => {
1909
+ inputValueRef.current = inputValue;
1910
+ });
1199
1911
 
1200
- const handleFilterChange = (value: string) => {
1201
- table.setGlobalFilter(value);
1912
+ // `filter` mirrors the last observed table filter (the previous-render
1913
+ // value); `pushed` lists the values THIS component wrote that have not been
1914
+ // observed back yet, so a push's own echo is not mistaken for an external
1915
+ // write. Acknowledgment is by value and recency, not true write identity —
1916
+ // the filter is a plain string in table state, so there is no channel for a
1917
+ // revision token. That leaves one ambiguous case: an external write whose
1918
+ // value exactly equals an in-flight unacknowledged push is read as that
1919
+ // push's echo, and keystrokes typed since are kept rather than overwritten.
1920
+ // Every external write that differs from the in-flight pushes is adopted.
1921
+ // A list, not a single slot: with writes landing a render late (a
1922
+ // transition- or URL-synced filter) several pushes can be in flight at
1923
+ // once. Recorded via setState (not a ref) so render never touches a mutable
1924
+ // value, and batched with the table write itself.
1925
+ const [filterSync, setFilterSync] = React.useState<{
1926
+ filter: string;
1927
+ pushed: string[];
1928
+ }>({ filter: filterValue, pushed: [] });
1929
+
1930
+ // Write the filter and record the write — called from handlers and timer
1931
+ // callbacks only, never during render. The record is capped: a consumer
1932
+ // that never echoes pushes back (a controlled filter without a handler, or
1933
+ // one that normalizes values) must not grow it for the component's
1934
+ // lifetime, and more than a handful of unacknowledged writes can no longer
1935
+ // be meaningfully "in flight" anyway.
1936
+ const pushFilter = (next: string) => {
1937
+ if ((table.getState().globalFilter ?? "") === next) {
1938
+ return;
1939
+ }
1940
+ setFilterSync((sync) => ({
1941
+ filter: sync.filter,
1942
+ pushed: [...sync.pushed, next].slice(-MAX_TRACKED_FILTER_PUSHES),
1943
+ }));
1944
+ table.setGlobalFilter(next);
1945
+ };
1946
+
1947
+ const schedulePush = (next: string) => {
1948
+ cancelPendingPush();
1949
+ if (effectiveDebounceMs > 0) {
1950
+ pushTimerRef.current = setTimeout(() => {
1951
+ pushTimerRef.current = null;
1952
+ // An adopted external write (which replaces `inputValue` below) or a
1953
+ // clear supersedes this push — stale keystrokes never win over them.
1954
+ if (inputValueRef.current === next) {
1955
+ pushFilter(next);
1956
+ }
1957
+ }, effectiveDebounceMs);
1958
+ } else {
1959
+ pushFilter(next);
1960
+ }
1961
+ };
1962
+
1963
+ // Adopt filter changes made outside this input (a consumer reset, another
1964
+ // control writing the filter) — state adjusted during render. A pending
1965
+ // debounced push cannot write over the adopted value: its timer compares
1966
+ // against the adopted `inputValue` and skips itself.
1967
+ if (filterValue !== filterSync.filter) {
1968
+ // Acknowledge own pushes by identity: the observed value is the most
1969
+ // recent matching push, and everything pushed before it was superseded
1970
+ // (renders can skip intermediate states, so earlier entries may never be
1971
+ // observed on their own). An unmatched value is an external write; later
1972
+ // own pushes may still be observed, so the list is kept.
1973
+ const ackIndex = filterSync.pushed.lastIndexOf(filterValue);
1974
+ const isOwnPush = ackIndex !== -1;
1975
+ setFilterSync({
1976
+ filter: filterValue,
1977
+ pushed: isOwnPush
1978
+ ? filterSync.pushed.slice(ackIndex + 1)
1979
+ : filterSync.pushed,
1980
+ });
1981
+ if (!isOwnPush && filterValue !== inputValue) {
1982
+ setInputValue(filterValue);
1983
+ }
1984
+ }
1985
+
1986
+ const handleClear = () => {
1987
+ // Clearing skips the debounce — the filter resets immediately, and any
1988
+ // pending keystroke push is cancelled rather than resurrecting the query.
1989
+ cancelPendingPush();
1990
+ setInputValue("");
1991
+ pushFilter("");
1202
1992
  };
1203
1993
 
1204
1994
  return (
1205
- <InputGroup data-slot="data-table-search" {...inputGroupProps}>
1995
+ <InputGroup
1996
+ aria-busy={loading ? "true" : undefined}
1997
+ data-slot="data-table-search"
1998
+ {...inputGroupProps}
1999
+ >
1206
2000
  <InputGroupAddon className="pl-3">
1207
- <Search />
2001
+ {/* The spinner takes the search icon's slot, never the clear button's:
2002
+ the way out of a slow search must stay where it always is. */}
2003
+ {loading ? (
2004
+ <Spinner dataHook={`${inputGroupProps.dataHook}-loading`} />
2005
+ ) : (
2006
+ <Search />
2007
+ )}
1208
2008
  </InputGroupAddon>
1209
2009
  <InputGroupInput
2010
+ ref={ref}
1210
2011
  aria-label={ariaLabel ?? "Search table"}
2012
+ disabled={disabled}
1211
2013
  placeholder={placeholder ?? "Search..."}
1212
2014
  type="text"
1213
- value={filterValue}
1214
- onChange={(event) => handleFilterChange(event.target.value)}
2015
+ value={inputValue}
2016
+ onChange={(event) => {
2017
+ const next = event.target.value;
2018
+ setInputValue(next);
2019
+ // Debounced (server-side) mode schedules the push; synchronous mode
2020
+ // pushes in the handler for same-keystroke narrowing.
2021
+ schedulePush(next);
2022
+ }}
2023
+ />
2024
+ <InputGroupClear
2025
+ clearSearchAriaLabel={clearSearchAriaLabel}
2026
+ data-slot="data-table-search-clear"
2027
+ dataHook={`${inputGroupProps.dataHook}-clear`}
2028
+ onClear={effectiveDebounceMs > 0 ? handleClear : undefined}
1215
2029
  />
1216
- {filterValue && (
1217
- <InputGroupAddon className="pr-1">
1218
- <Button
1219
- aria-label={clearSearchAriaLabel ?? "Clear search"}
1220
- /* Fixed square hit area — h-auto p-1 let the ghost hover hug the
1221
- 14px icon into a squashed pill. */
1222
- className="size-6 p-0"
1223
- data-slot="data-table-search-clear"
1224
- dataHook={`${inputGroupProps.dataHook}-clear`}
1225
- variant="ghost"
1226
- onClick={() => handleFilterChange("")}
1227
- >
1228
- <X size={14} />
1229
- </Button>
1230
- </InputGroupAddon>
1231
- )}
1232
2030
  </InputGroup>
1233
2031
  );
1234
- }
2032
+ }) as <TData>(
2033
+ props: DataTableSearchProps<TData> & React.RefAttributes<HTMLInputElement>
2034
+ ) => React.ReactElement;
1235
2035
 
1236
- DataTableSearch.displayName = "DataTableSearch";
2036
+ (DataTableSearch as React.FC).displayName = "DataTableSearch";
1237
2037
 
1238
2038
  /* -------------------------------------------------------------------------------------------------
1239
2039
  * useDataTablePagination (hook)
@@ -1343,6 +2143,7 @@ function useDataTablePagination<TData>(
1343
2143
 
1344
2144
  interface DataTablePaginationContextValue {
1345
2145
  info: DataTablePaginationInfo;
2146
+ dataHook: string;
1346
2147
  }
1347
2148
 
1348
2149
  const DataTablePaginationContext =
@@ -1362,6 +2163,7 @@ function useDataTablePaginationContext() {
1362
2163
  * DataTablePaginationRowCount
1363
2164
  * -----------------------------------------------------------------------------------------------*/
1364
2165
 
2166
+ /** The English default: compact "start – end of total", nothing when empty. */
1365
2167
  /** Info passed to row-count render functions. */
1366
2168
  export interface RowCountRenderInfo {
1367
2169
  /** First visible row (1-based, 0 when empty). */
@@ -1378,30 +2180,61 @@ export interface RowCountRenderInfo {
1378
2180
 
1379
2181
  export interface DataTablePaginationRowCountProps {
1380
2182
  /**
1381
- * Render the row-count text. Receives pagination numbers; you control
1382
- * wording, pluralization, and order. Return `null` to hide.
1383
- * @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.
1384
2208
  */
1385
2209
  renderText?: (info: RowCountRenderInfo) => React.ReactNode;
2210
+ /** Data hook for the count. @default "{paginationDataHook}-row-count" */
2211
+ dataHook?: string;
1386
2212
  /** Additional class name. */
1387
2213
  className?: string;
1388
2214
  }
1389
2215
 
1390
2216
  /**
1391
- * 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.
1392
2222
  *
1393
- * Renders "start–end of total" by default. Pass `renderText` for i18n-friendly
1394
- * custom text with full control over wording, pluralization, and order.
1395
2223
  * Renders nothing below the `sm` viewport breakpoint — on small screens the
1396
2224
  * label is removed so the page buttons get the full width (DS-998).
1397
2225
  *
1398
2226
  * Must be rendered inside `<DataTablePagination>`.
1399
2227
  */
1400
2228
  function DataTablePaginationRowCount({
2229
+ label,
2230
+ labelOne,
2231
+ emptyLabel,
1401
2232
  renderText,
2233
+ dataHook,
1402
2234
  className,
1403
2235
  }: DataTablePaginationRowCountProps) {
1404
- const { info } = useDataTablePaginationContext();
2236
+ const { info, dataHook: paginationDataHook } =
2237
+ useDataTablePaginationContext();
1405
2238
  const isMobile = useIsBelowBreakpoint("sm");
1406
2239
  const { startRow, endRow, totalRows, pageIndex, pageSize } = info;
1407
2240
 
@@ -1410,24 +2243,40 @@ function DataTablePaginationRowCount({
1410
2243
  // `PaginationControls`.
1411
2244
  if (isMobile) return null;
1412
2245
 
1413
- const content = renderText
1414
- ? renderText({ startRow, endRow, totalRows, pageIndex, pageSize })
1415
- : totalRows === 0
1416
- ? null
1417
- : `${startRow}-${endRow} of ${totalRows}`;
1418
-
1419
- 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
+ }
1420
2268
 
1421
2269
  return (
1422
- <span
1423
- className={cn(
1424
- "text-body-sm text-muted-foreground whitespace-nowrap",
1425
- className
1426
- )}
1427
- data-slot="data-table-pagination-row-count"
1428
- >
1429
- {content}
1430
- </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
+ />
1431
2280
  );
1432
2281
  }
1433
2282
 
@@ -1554,10 +2403,36 @@ export interface DataTablePaginationProps<TData> {
1554
2403
  */
1555
2404
  showRowCount?: boolean;
1556
2405
  /**
1557
- * Render the row-count text. Receives pagination numbers; you control
1558
- * 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.
1559
2435
  * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
1560
- * @default Renders "{startRow}-{endRow} of {totalRows}" or nothing when empty.
1561
2436
  */
1562
2437
  renderRowCount?: ((info: RowCountRenderInfo) => React.ReactNode) | null;
1563
2438
  /** Analytics element identifier. */
@@ -1580,14 +2455,16 @@ export interface DataTablePaginationProps<TData> {
1580
2455
  /**
1581
2456
  * Pagination controls for a DataTable.
1582
2457
  *
1583
- * **Default mode** (no children): renders previous/next/page links and an
1584
- * optional "start–end of total" row count label. Use `renderRowCount` for
1585
- * 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.
1586
2461
  *
1587
2462
  * The navigation hides itself when there is at most one page (the row count
1588
- * stays, keeping the bar informative and the layout stable). When both the
1589
- * row count and the nav are empty, the component renders nothing — no
1590
- * 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.
1591
2468
  *
1592
2469
  * **Responsive behaviour:** below the `sm` viewport breakpoint the row-count
1593
2470
  * label is removed and the page buttons centre in the available width — the
@@ -1616,9 +2493,7 @@ export interface DataTablePaginationProps<TData> {
1616
2493
  * <DataTablePagination
1617
2494
  * table={table}
1618
2495
  * dataHook="pagination"
1619
- * renderRowCount={({ startRow, endRow, totalRows }) =>
1620
- * t('pagination.caption', { from: startRow, to: endRow, total: totalRows })
1621
- * }
2496
+ * rowCountLabel={t('pagination.caption')} // "{from} to {to} of {total} locations"
1622
2497
  * />
1623
2498
  *
1624
2499
  * @example
@@ -1632,6 +2507,9 @@ export function DataTablePagination<TData>({
1632
2507
  table,
1633
2508
  dataHook,
1634
2509
  showRowCount = true,
2510
+ rowCountLabel,
2511
+ rowCountLabelOne,
2512
+ rowCountEmptyLabel,
1635
2513
  renderRowCount,
1636
2514
  trackingEl,
1637
2515
  trackingLabel,
@@ -1643,8 +2521,8 @@ export function DataTablePagination<TData>({
1643
2521
  const isMobile = useIsBelowBreakpoint("sm");
1644
2522
 
1645
2523
  const contextValue = React.useMemo<DataTablePaginationContextValue>(
1646
- () => ({ info }),
1647
- [info]
2524
+ () => ({ info, dataHook }),
2525
+ [info, dataHook]
1648
2526
  );
1649
2527
 
1650
2528
  const wrapperDataAttrs = {
@@ -1670,26 +2548,32 @@ export function DataTablePagination<TData>({
1670
2548
  );
1671
2549
  }
1672
2550
 
1673
- const rowCountContent = (() => {
1674
- // Below `sm` the label is removed so the page buttons get the full width
1675
- // and centre (DS-998).
1676
- if (isMobile) return null;
1677
- if (!showRowCount) return null;
1678
- if (renderRowCount === null) return null;
1679
- if (renderRowCount) {
1680
- return renderRowCount({
1681
- startRow: info.startRow,
1682
- endRow: info.endRow,
1683
- totalRows: info.totalRows,
1684
- pageIndex: info.pageIndex,
1685
- pageSize: info.pageSize,
1686
- });
1687
- }
1688
- if (info.totalRows === 0) return null;
1689
- return `${info.startRow}-${info.endRow} of ${info.totalRows}`;
1690
- })();
1691
-
1692
- 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) {
1693
2577
  return null;
1694
2578
  }
1695
2579
 
@@ -1697,17 +2581,23 @@ export function DataTablePagination<TData>({
1697
2581
  <DataTablePaginationContext.Provider value={contextValue}>
1698
2582
  <div
1699
2583
  className={cn(
1700
- "flex min-h-9 w-full flex-wrap items-center gap-x-4 gap-y-2",
1701
- 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",
1702
2587
  className
1703
2588
  )}
1704
2589
  {...wrapperDataAttrs}
1705
2590
  >
1706
- {rowCountContent != null && (
1707
- <span className="text-body-sm text-muted-foreground whitespace-nowrap">
1708
- {rowCountContent}
1709
- </span>
1710
- )}
2591
+ {hasRowCount &&
2592
+ (renderRowCount ? (
2593
+ <DataTablePaginationRowCount renderText={() => customRowCount} />
2594
+ ) : (
2595
+ <DataTablePaginationRowCount
2596
+ emptyLabel={rowCountEmptyLabel}
2597
+ label={rowCountLabel}
2598
+ labelOne={rowCountLabelOne}
2599
+ />
2600
+ ))}
1711
2601
  <DataTablePaginationNav
1712
2602
  ariaLabel={ariaLabel}
1713
2603
  className="grow"
@@ -1742,8 +2632,15 @@ export interface DataTableSelectAllCheckboxProps<TData> {
1742
2632
  }
1743
2633
 
1744
2634
  /**
1745
- * Header checkbox for selecting all visible page rows. Renders as
1746
- * 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.
2639
+ *
2640
+ * While the surrounding `DataTable` is `refetching`, the checkbox is
2641
+ * `aria-disabled` and toggles are ignored (visually unchanged, still exposed
2642
+ * to screen readers so the select-all `<th>` never reads as empty): the rows
2643
+ * it would select are stale and about to be replaced (DS-916).
1747
2644
  */
1748
2645
  export function DataTableSelectAllCheckbox<TData>({
1749
2646
  table,
@@ -1752,17 +2649,22 @@ export function DataTableSelectAllCheckbox<TData>({
1752
2649
  trackingLabel,
1753
2650
  selectAllAriaLabel,
1754
2651
  }: DataTableSelectAllCheckboxProps<TData>) {
2652
+ const refetching = React.useContext(DataTableRefetchingContext);
1755
2653
  return (
1756
2654
  <Checkbox
2655
+ aria-disabled={refetching || undefined}
1757
2656
  aria-label={selectAllAriaLabel ?? "Select all"}
1758
- checked={
1759
- table.getIsAllPageRowsSelected() ||
1760
- (table.getIsSomePageRowsSelected() && "indeterminate")
1761
- }
2657
+ checked={table.getIsAllPageRowsSelected()}
1762
2658
  dataHook={dataHook || "select-all-checkbox"}
1763
2659
  trackingEl={trackingEl}
1764
2660
  trackingLabel={trackingLabel}
1765
- onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
2661
+ onCheckedChange={(value) => {
2662
+ // The guard is the real block: the checkbox is controlled, so pointer
2663
+ // and keyboard toggles alike are ignored while refetching.
2664
+ if (!refetching) {
2665
+ table.toggleAllPageRowsSelected(!!value);
2666
+ }
2667
+ }}
1766
2668
  />
1767
2669
  );
1768
2670
  }
@@ -1787,6 +2689,11 @@ export interface DataTableSelectRowCheckboxProps<TData> {
1787
2689
 
1788
2690
  /**
1789
2691
  * Row-level selection checkbox. Disabled when the row cannot be selected.
2692
+ *
2693
+ * While the surrounding `DataTable` is `refetching`, the checkbox is
2694
+ * `aria-disabled` and toggles are ignored (visually unchanged, still exposed
2695
+ * to screen readers): the row it would select is stale and about to be
2696
+ * replaced (DS-916).
1790
2697
  */
1791
2698
  export function DataTableSelectRowCheckbox<TData>({
1792
2699
  row,
@@ -1795,15 +2702,23 @@ export function DataTableSelectRowCheckbox<TData>({
1795
2702
  trackingLabel,
1796
2703
  selectRowAriaLabel,
1797
2704
  }: DataTableSelectRowCheckboxProps<TData>) {
2705
+ const refetching = React.useContext(DataTableRefetchingContext);
1798
2706
  return (
1799
2707
  <Checkbox
2708
+ aria-disabled={refetching || undefined}
1800
2709
  aria-label={selectRowAriaLabel ?? "Select row"}
1801
2710
  checked={row.getIsSelected()}
1802
2711
  dataHook={dataHook || `select-row-${row.id}`}
1803
2712
  disabled={!row.getCanSelect()}
1804
2713
  trackingEl={trackingEl}
1805
2714
  trackingLabel={trackingLabel}
1806
- onCheckedChange={(value) => row.toggleSelected(!!value)}
2715
+ onCheckedChange={(value) => {
2716
+ // The guard is the real block: the checkbox is controlled, so pointer
2717
+ // and keyboard toggles alike are ignored while refetching.
2718
+ if (!refetching) {
2719
+ row.toggleSelected(!!value);
2720
+ }
2721
+ }}
1807
2722
  />
1808
2723
  );
1809
2724
  }
@@ -2010,6 +2925,13 @@ export interface DataTableBulkActionsContextValue {
2010
2925
  * `useDataTable` — the same option `DataTablePagination` relies on.
2011
2926
  */
2012
2927
  totalCount: number;
2928
+ /**
2929
+ * Whether a server-side refetch is in flight (the bar's `refetching` prop).
2930
+ * `DataTableBulkActionsActions` goes inert on it; custom action parts built
2931
+ * on this context should do the same — the selection they would act on is
2932
+ * stale (DS-916).
2933
+ */
2934
+ refetching: boolean;
2013
2935
  }
2014
2936
 
2015
2937
  const DataTableBulkActionsContext =
@@ -2056,6 +2978,16 @@ export interface DataTableBulkActionsProps<TData> {
2056
2978
  * `DataTableBulkActionsActions`, and any custom parts in any order.
2057
2979
  */
2058
2980
  children?: React.ReactNode;
2981
+ /**
2982
+ * Marks a server-side refetch as in flight — pass the same flag given to
2983
+ * the `DataTable`'s `refetching`. The bar sets `aria-busy` and
2984
+ * `DataTableBulkActionsActions` becomes inert (unfocusable and unclickable,
2985
+ * visually unchanged): bulk actions would act on stale rows about to be
2986
+ * replaced. The bar lives outside the table's subtree, so it cannot inherit
2987
+ * the flag from `DataTable` — it must be passed here too (DS-916).
2988
+ * @default false
2989
+ */
2990
+ refetching?: boolean;
2059
2991
  }
2060
2992
 
2061
2993
  /**
@@ -2074,8 +3006,6 @@ export interface DataTableBulkActionsProps<TData> {
2074
3006
  * <DataTableToolbar dataHook="toolbar">
2075
3007
  * <DataTableToolbarLeft>
2076
3008
  * <DataTableSearch table={table} dataHook="search" />
2077
- * </DataTableToolbarLeft>
2078
- * <DataTableToolbarRight>
2079
3009
  * <DataTableBulkActions table={table} dataHook="bulk-actions">
2080
3010
  * <DataTableBulkActionsSummary />
2081
3011
  * <DataTableBulkActionsActions>
@@ -2084,6 +3014,9 @@ export interface DataTableBulkActionsProps<TData> {
2084
3014
  * </Button>
2085
3015
  * </DataTableBulkActionsActions>
2086
3016
  * </DataTableBulkActions>
3017
+ * </DataTableToolbarLeft>
3018
+ * <DataTableToolbarRight>
3019
+ * <DataTablePagination table={table} dataHook="pagination" />
2087
3020
  * </DataTableToolbarRight>
2088
3021
  * </DataTableToolbar>
2089
3022
  */
@@ -2094,6 +3027,7 @@ export function DataTableBulkActions<TData>({
2094
3027
  trackingLabel,
2095
3028
  className,
2096
3029
  children,
3030
+ refetching = false,
2097
3031
  }: DataTableBulkActionsProps<TData>) {
2098
3032
  const selectedCount = table.getFilteredSelectedRowModel().rows.length;
2099
3033
  // getRowCount() = the rowCount option in manual mode, the filtered row
@@ -2101,8 +3035,8 @@ export function DataTableBulkActions<TData>({
2101
3035
  const totalCount = table.getRowCount();
2102
3036
 
2103
3037
  const contextValue = React.useMemo<DataTableBulkActionsContextValue>(
2104
- () => ({ selectedCount, totalCount }),
2105
- [selectedCount, totalCount]
3038
+ () => ({ selectedCount, totalCount, refetching }),
3039
+ [selectedCount, totalCount, refetching]
2106
3040
  );
2107
3041
 
2108
3042
  if (selectedCount === 0) return null;
@@ -2110,6 +3044,7 @@ export function DataTableBulkActions<TData>({
2110
3044
  return (
2111
3045
  <DataTableBulkActionsContext.Provider value={contextValue}>
2112
3046
  <div
3047
+ aria-busy={refetching || undefined}
2113
3048
  className={cn("flex items-center gap-2.5", className)}
2114
3049
  data-hook={dataHook}
2115
3050
  data-slot="data-table-bulk-actions"
@@ -2178,11 +3113,12 @@ export function DataTableBulkActionsSummary({
2178
3113
  className,
2179
3114
  children,
2180
3115
  }: DataTableBulkActionsSummaryProps) {
2181
- const { selectedCount, totalCount } = useDataTableBulkActionsContext();
3116
+ const context = useDataTableBulkActionsContext();
3117
+ const { selectedCount, totalCount } = context;
2182
3118
 
2183
3119
  let content: React.ReactNode;
2184
3120
  if (typeof children === "function") {
2185
- content = children({ selectedCount, totalCount });
3121
+ content = children(context);
2186
3122
  } else if (children != null) {
2187
3123
  content = children;
2188
3124
  } else {
@@ -2230,17 +3166,26 @@ export interface DataTableBulkActionsActionsProps {
2230
3166
  * Optional: a single action can sit directly inside
2231
3167
  * `DataTableBulkActions`. Use this when you have several, or need them
2232
3168
  * grouped and protected from shrinking.
3169
+ *
3170
+ * While the bar's `refetching` flag is set, the slot is `inert` — its buttons
3171
+ * cannot be clicked or focused (without a disabled look), because the
3172
+ * selection they would act on is stale (DS-916).
2233
3173
  */
2234
3174
  export function DataTableBulkActionsActions({
2235
3175
  dataHook = "data-table-bulk-actions-actions",
2236
3176
  className,
2237
3177
  children,
2238
3178
  }: DataTableBulkActionsActionsProps) {
3179
+ // Read null-safely rather than via the throwing hook: the slot renders fine
3180
+ // outside the bar, it just has no refetch flag to honor there.
3181
+ const refetching =
3182
+ React.useContext(DataTableBulkActionsContext)?.refetching ?? false;
2239
3183
  return (
2240
3184
  <div
2241
3185
  className={cn("flex shrink-0 items-center gap-2", className)}
2242
3186
  data-hook={dataHook}
2243
3187
  data-slot="data-table-bulk-actions-actions"
3188
+ inert={refetching || undefined}
2244
3189
  >
2245
3190
  {children}
2246
3191
  </div>
@@ -2270,14 +3215,24 @@ export interface DataTableToolbarProps {
2270
3215
  * Responsive toolbar container for DataTable companion controls.
2271
3216
  *
2272
3217
  * Stacks vertically on mobile (< 640 px) and switches to a horizontal
2273
- * row on `sm:` and up. Layout-only — no dependency on a TanStack Table
2274
- * 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.
2275
3226
  *
2276
3227
  * Toolbars belong in the same flex-column container as their `DataTable` so
2277
3228
  * the group reads as one slot inside gapped parents — see the composition
2278
3229
  * note on `DataTable`. The built-in vertical padding provides the spacing
2279
3230
  * between a toolbar and its table; don't add custom margins or padding.
2280
3231
  *
3232
+ * Inside a Card with a header, filters that narrow what the card shows
3233
+ * (`DataTableSearch` included) go in the header's `CardToolbar`; this toolbar
3234
+ * keeps pagination beside the table. A report card uses both.
3235
+ *
2281
3236
  * @example
2282
3237
  * <DataTableToolbar dataHook="locations-toolbar">
2283
3238
  * <DataTableToolbarLeft>
@@ -2296,7 +3251,7 @@ export function DataTableToolbar({
2296
3251
  return (
2297
3252
  <div
2298
3253
  className={cn(
2299
- "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",
2300
3255
  className
2301
3256
  )}
2302
3257
  data-hook={dataHook}
@@ -2325,8 +3280,10 @@ export interface DataTableToolbarLeftProps {
2325
3280
 
2326
3281
  /**
2327
3282
  * Left slot of `DataTableToolbar`. Grows to fill remaining space on
2328
- * desktop; full-width on mobile. `min-w-0` lets long inputs shrink
2329
- * 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.
2330
3287
  */
2331
3288
  export function DataTableToolbarLeft({
2332
3289
  className,
@@ -2335,7 +3292,7 @@ export function DataTableToolbarLeft({
2335
3292
  return (
2336
3293
  <div
2337
3294
  className={cn(
2338
- "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",
2339
3296
  className
2340
3297
  )}
2341
3298
  data-slot="data-table-toolbar-left"
@@ -2357,14 +3314,15 @@ DataTableToolbarLeft.displayName = "DataTableToolbarLeft";
2357
3314
  export interface DataTableToolbarRightProps {
2358
3315
  /** Additional class name (merged after defaults via `cn`). */
2359
3316
  className?: string;
2360
- /** 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. */
2361
3318
  children: React.ReactNode;
2362
3319
  }
2363
3320
 
2364
3321
  /**
2365
3322
  * Right slot of `DataTableToolbar`. Collapses to content width and
2366
- * right-aligns on desktop; full-width with `justify-end` on mobile so
2367
- * 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.
2368
3326
  */
2369
3327
  export function DataTableToolbarRight({
2370
3328
  className,
@@ -2373,7 +3331,7 @@ export function DataTableToolbarRight({
2373
3331
  return (
2374
3332
  <div
2375
3333
  className={cn(
2376
- "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",
2377
3335
  className
2378
3336
  )}
2379
3337
  data-slot="data-table-toolbar-right"
@@ -2389,9 +3347,16 @@ DataTableToolbarRight.displayName = "DataTableToolbarRight";
2389
3347
  * Re-exported TanStack Table helpers
2390
3348
  * -----------------------------------------------------------------------------------------------*/
2391
3349
 
2392
- export { DataTablePaginationRowCount, DataTablePaginationNav };
3350
+ export {
3351
+ DataTable,
3352
+ VirtualizedDataTable,
3353
+ DataTablePaginationRowCount,
3354
+ DataTablePaginationNav,
3355
+ useDataTablePagination,
3356
+ };
2393
3357
 
2394
3358
  export type {
3359
+ DataTablePaginationInfo,
2395
3360
  Column,
2396
3361
  ColumnDef,
2397
3362
  ExpandedState,