@jcsoftdev/ui 0.5.0 → 0.6.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 (373) hide show
  1. package/CHANGELOG.md +337 -0
  2. package/README.md +25 -3
  3. package/bin/ui-theme.mjs +40 -6
  4. package/dist/ai/code-block/code-block.js +1 -1
  5. package/dist/atoms/big-date/big-date.js +2 -2
  6. package/dist/atoms/button/button.d.ts +6 -1
  7. package/dist/atoms/button/button.js +2 -2
  8. package/dist/atoms/chip/chip.d.ts +5 -0
  9. package/dist/atoms/chip/chip.js +3 -3
  10. package/dist/atoms/icon-button/icon-button.js +1 -1
  11. package/dist/atoms/internal/hit-area.d.ts +5 -4
  12. package/dist/atoms/internal/hit-area.js +1 -1
  13. package/dist/atoms/progress/index.d.ts +1 -1
  14. package/dist/atoms/progress/index.js +4 -1
  15. package/dist/atoms/progress/progress.d.ts +6 -1
  16. package/dist/atoms/progress/progress.js +19 -1
  17. package/dist/atoms/radio-group/radio-group.js +1 -1
  18. package/dist/atoms/status-pill/status-pill.d.ts +16 -5
  19. package/dist/atoms/status-pill/status-pill.js +43 -18
  20. package/dist/brand/logo-forge.js +1 -1
  21. package/dist/charts/candlestick-chart/candlestick-chart.js +2 -2
  22. package/dist/charts/chart-grid/chart-grid.js +2 -2
  23. package/dist/charts/chord-chart/chord-chart.js +1 -1
  24. package/dist/charts/core/axes.js +2 -2
  25. package/dist/charts/core/cartesian/annotations.js +2 -2
  26. package/dist/charts/core/cartesian/marks.js +1 -1
  27. package/dist/charts/core/distribution/marks.js +1 -1
  28. package/dist/charts/core/distribution/xy-points.js +1 -1
  29. package/dist/charts/core/export-menu.js +1 -1
  30. package/dist/charts/funnel-chart/funnel-chart.js +1 -1
  31. package/dist/charts/gantt-chart/gantt-chart.js +4 -4
  32. package/dist/charts/gantt-chart/gantt-marks.js +3 -3
  33. package/dist/charts/index.d.ts +2 -0
  34. package/dist/charts/index.js +2 -0
  35. package/dist/charts/maps/geo/map-data-table.js +1 -1
  36. package/dist/charts/polar-area-chart/polar-area-chart.js +1 -1
  37. package/dist/charts/radar-chart/radar-chart.js +1 -1
  38. package/dist/charts/stock-chart/stock-chart.js +1 -1
  39. package/dist/charts/stock-chart/stock-drawing-layer.js +3 -3
  40. package/dist/charts/stock-chart/stock-plot.js +2 -2
  41. package/dist/containers/chat-thread/chat-thread.d.ts +98 -0
  42. package/dist/containers/chat-thread/chat-thread.js +219 -0
  43. package/dist/containers/chat-thread/format.d.ts +20 -0
  44. package/dist/containers/chat-thread/format.js +50 -0
  45. package/dist/containers/chat-thread/index.d.ts +1 -0
  46. package/dist/containers/chat-thread/index.js +8 -0
  47. package/dist/containers/cols/cols.d.ts +1 -1
  48. package/dist/containers/cols/cols.js +7 -0
  49. package/dist/containers/comment/comment.js +1 -1
  50. package/dist/containers/context-rail/context-rail.d.ts +62 -0
  51. package/dist/containers/context-rail/context-rail.js +175 -0
  52. package/dist/containers/context-rail/index.d.ts +1 -0
  53. package/dist/containers/context-rail/index.js +6 -0
  54. package/dist/containers/dashboard/dashboard.d.ts +40 -0
  55. package/dist/containers/dashboard/dashboard.js +84 -0
  56. package/dist/containers/dashboard/index.d.ts +1 -0
  57. package/dist/containers/dashboard/index.js +14 -0
  58. package/dist/containers/data-grid/data-grid.demos.js +4 -4
  59. package/dist/containers/data-grid/data-grid.js +6 -6
  60. package/dist/containers/data-grid/filter-builder-editor.js +2 -2
  61. package/dist/containers/data-grid/grid-toolbar.js +1 -1
  62. package/dist/containers/data-grid/spreadsheet.demos.d.ts +1 -1
  63. package/dist/containers/data-grid/spreadsheet.demos.js +1 -1
  64. package/dist/containers/detail-header/detail-header.d.ts +24 -0
  65. package/dist/containers/detail-header/detail-header.js +32 -0
  66. package/dist/containers/detail-header/index.d.ts +1 -0
  67. package/dist/containers/detail-header/index.js +6 -0
  68. package/dist/containers/facts/facts.js +1 -1
  69. package/dist/containers/filter-bar/filter-bar.d.ts +58 -0
  70. package/dist/containers/filter-bar/filter-bar.js +123 -0
  71. package/dist/containers/filter-bar/index.d.ts +1 -0
  72. package/dist/containers/filter-bar/index.js +6 -0
  73. package/dist/containers/hbars/hbars.js +2 -2
  74. package/dist/containers/index.d.ts +9 -0
  75. package/dist/containers/index.js +9 -0
  76. package/dist/containers/kanban/kanban.d.ts +23 -2
  77. package/dist/containers/kanban/kanban.js +101 -21
  78. package/dist/containers/kanban/model.d.ts +12 -0
  79. package/dist/containers/kanban/model.js +8 -0
  80. package/dist/containers/kpi/kpi.js +1 -1
  81. package/dist/containers/kpi-group/kpi-group.d.ts +6 -1
  82. package/dist/containers/kpi-group/kpi-group.js +6 -2
  83. package/dist/containers/list-detail/index.d.ts +1 -1
  84. package/dist/containers/list-detail/index.js +4 -0
  85. package/dist/containers/list-detail/list-detail.d.ts +51 -3
  86. package/dist/containers/list-detail/list-detail.js +109 -15
  87. package/dist/containers/page/page.d.ts +17 -4
  88. package/dist/containers/page/page.js +33 -4
  89. package/dist/containers/page-header/back.d.ts +10 -0
  90. package/dist/containers/page-header/back.js +28 -0
  91. package/dist/containers/page-header/index.d.ts +1 -0
  92. package/dist/containers/page-header/index.js +1 -0
  93. package/dist/containers/page-header/page-header.d.ts +19 -2
  94. package/dist/containers/page-header/page-header.js +26 -2
  95. package/dist/containers/pagination/cursor-pagination.d.ts +28 -0
  96. package/dist/containers/pagination/cursor-pagination.js +48 -0
  97. package/dist/containers/pagination/index.d.ts +3 -0
  98. package/dist/containers/pagination/index.js +10 -0
  99. package/dist/containers/pagination/pagination.d.ts +52 -0
  100. package/dist/containers/pagination/pagination.js +216 -0
  101. package/dist/containers/pagination/range.d.ts +29 -0
  102. package/dist/containers/pagination/range.js +42 -0
  103. package/dist/containers/pagination/use-pagination.d.ts +18 -0
  104. package/dist/containers/pagination/use-pagination.js +22 -0
  105. package/dist/containers/responsive-list/responsive-list.d.ts +28 -2
  106. package/dist/containers/responsive-list/responsive-list.js +134 -25
  107. package/dist/containers/row-actions/index.d.ts +1 -0
  108. package/dist/containers/row-actions/index.js +4 -0
  109. package/dist/containers/row-actions/row-actions.d.ts +26 -0
  110. package/dist/containers/row-actions/row-actions.js +78 -0
  111. package/dist/containers/selectable-card/index.d.ts +1 -0
  112. package/dist/containers/selectable-card/index.js +6 -0
  113. package/dist/containers/selectable-card/selectable-card.d.ts +26 -0
  114. package/dist/containers/selectable-card/selectable-card.js +57 -0
  115. package/dist/containers/settings-layout/settings-layout.d.ts +24 -7
  116. package/dist/containers/settings-layout/settings-layout.js +63 -8
  117. package/dist/containers/shortcuts/shortcuts.js +1 -1
  118. package/dist/containers/table/cell-padding.d.ts +2 -0
  119. package/dist/containers/table/cell-padding.js +4 -0
  120. package/dist/containers/table/index.d.ts +1 -0
  121. package/dist/containers/table/index.js +8 -0
  122. package/dist/containers/table/sort.d.ts +14 -0
  123. package/dist/containers/table/sort.js +11 -0
  124. package/dist/containers/table/table-parts.d.ts +24 -0
  125. package/dist/containers/table/table-parts.js +52 -0
  126. package/dist/containers/table/table.d.ts +37 -3
  127. package/dist/containers/table/table.js +120 -19
  128. package/dist/containers/table-columns-menu/index.d.ts +1 -0
  129. package/dist/containers/table-columns-menu/index.js +6 -0
  130. package/dist/containers/table-columns-menu/table-columns-menu.d.ts +14 -0
  131. package/dist/containers/table-columns-menu/table-columns-menu.js +46 -0
  132. package/dist/dashboards/layout.d.ts +1 -27
  133. package/dist/dashboards/layout.js +8 -40
  134. package/dist/forms/chip-group/chip-group.d.ts +5 -0
  135. package/dist/forms/chip-group/chip-group.js +3 -1
  136. package/dist/forms/combobox/combobox.js +1 -1
  137. package/dist/forms/copy-field/copy-field.js +1 -1
  138. package/dist/forms/date-picker/date-picker.d.ts +3 -1
  139. package/dist/forms/date-picker/date-picker.js +4 -2
  140. package/dist/forms/date-picker/date-time-picker.d.ts +8 -2
  141. package/dist/forms/date-picker/date-time-picker.js +13 -2
  142. package/dist/forms/field/field.d.ts +9 -2
  143. package/dist/forms/field/field.js +18 -4
  144. package/dist/forms/fieldset/fieldset.d.ts +11 -0
  145. package/dist/forms/fieldset/fieldset.js +12 -0
  146. package/dist/forms/fieldset/index.d.ts +1 -0
  147. package/dist/forms/fieldset/index.js +4 -0
  148. package/dist/forms/form-footer/form-footer.d.ts +26 -0
  149. package/dist/forms/form-footer/form-footer.js +44 -0
  150. package/dist/forms/form-footer/index.d.ts +1 -0
  151. package/dist/forms/form-footer/index.js +4 -0
  152. package/dist/forms/form-grid/form-grid.d.ts +21 -4
  153. package/dist/forms/form-grid/form-grid.js +20 -3
  154. package/dist/forms/form-grid/index.d.ts +1 -1
  155. package/dist/forms/form-grid/index.js +6 -2
  156. package/dist/forms/form-section/form-section.d.ts +12 -0
  157. package/dist/forms/form-section/form-section.js +30 -0
  158. package/dist/forms/form-section/index.d.ts +1 -0
  159. package/dist/forms/form-section/index.js +4 -0
  160. package/dist/forms/index.d.ts +3 -0
  161. package/dist/forms/index.js +3 -0
  162. package/dist/forms/input/input.d.ts +6 -2
  163. package/dist/forms/input/input.js +4 -1
  164. package/dist/forms/internal/listbox-items.d.ts +1 -1
  165. package/dist/forms/internal/listbox-items.js +3 -2
  166. package/dist/forms/native-select/native-select.js +1 -1
  167. package/dist/forms/select/index.d.ts +1 -1
  168. package/dist/forms/select/select.d.ts +5 -2
  169. package/dist/forms/select/select.js +7 -2
  170. package/dist/forms/select-menu/select-menu.js +1 -1
  171. package/dist/forms/time-input/time-input.d.ts +4 -2
  172. package/dist/forms/time-input/time-input.js +3 -1
  173. package/dist/i18n/strings.d.ts +86 -0
  174. package/dist/i18n/strings.js +46 -0
  175. package/dist/motion/count-up.d.ts +20 -0
  176. package/dist/motion/count-up.js +59 -0
  177. package/dist/motion/cross-fade.d.ts +21 -0
  178. package/dist/motion/cross-fade.js +86 -0
  179. package/dist/motion/index.d.ts +5 -0
  180. package/dist/motion/index.js +14 -0
  181. package/dist/motion/model.d.ts +15 -0
  182. package/dist/motion/model.js +68 -0
  183. package/dist/motion/motion-styles.d.ts +1 -0
  184. package/dist/motion/motion-styles.js +35 -0
  185. package/dist/motion/reveal.d.ts +37 -0
  186. package/dist/motion/reveal.js +69 -0
  187. package/dist/motion/use-enter-phase.d.ts +11 -0
  188. package/dist/motion/use-enter-phase.js +40 -0
  189. package/dist/motion/use-highlight-row.d.ts +22 -0
  190. package/dist/motion/use-highlight-row.js +38 -0
  191. package/dist/navigation/tabs/tabs.js +1 -1
  192. package/dist/navigation/wizard/wizard.d.ts +4 -1
  193. package/dist/navigation/wizard/wizard.js +3 -0
  194. package/dist/overlays/alert-dialog/alert-dialog.js +8 -1
  195. package/dist/overlays/context-menu/context-menu.js +3 -1
  196. package/dist/overlays/dialog/dialog.js +10 -2
  197. package/dist/overlays/drawer/drawer.d.ts +18 -4
  198. package/dist/overlays/drawer/drawer.js +53 -4
  199. package/dist/overlays/drawer/index.d.ts +1 -1
  200. package/dist/overlays/dropdown-menu/dropdown-menu.d.ts +1 -1
  201. package/dist/overlays/dropdown-menu/dropdown-menu.js +5 -4
  202. package/dist/overlays/hover-card/hover-card.js +2 -0
  203. package/dist/overlays/popover/popover.js +2 -0
  204. package/dist/overlays/toaster/index.d.ts +1 -1
  205. package/dist/overlays/toaster/toaster.d.ts +28 -2
  206. package/dist/overlays/toaster/toaster.js +73 -29
  207. package/dist/overlays/tooltip/tooltip.js +2 -0
  208. package/dist/primitives/use-presence.js +9 -0
  209. package/dist/shell/app-shell/app-shell.d.ts +8 -1
  210. package/dist/shell/app-shell/app-shell.js +50 -3
  211. package/dist/shell/index.d.ts +1 -0
  212. package/dist/shell/index.js +1 -0
  213. package/dist/shell/sidebar/sidebar.d.ts +17 -1
  214. package/dist/shell/sidebar/sidebar.js +126 -76
  215. package/dist/shell/topbar/topbar.d.ts +4 -2
  216. package/dist/shell/topbar/topbar.js +2 -0
  217. package/dist/showcase/operations-bento.js +2 -2
  218. package/dist/states/empty-state/empty-state.d.ts +10 -3
  219. package/dist/states/empty-state/empty-state.js +46 -5
  220. package/dist/states/error-state/error-state.js +1 -1
  221. package/dist/states/skeleton/skeleton.js +1 -1
  222. package/dist/utils/class-tokens.generated.js +4 -6
  223. package/dist/utils/list-navigation.d.ts +14 -0
  224. package/dist/utils/list-navigation.js +44 -0
  225. package/dist/utils/overlay-motion.d.ts +12 -0
  226. package/dist/utils/overlay-motion.js +14 -0
  227. package/dist/utils/use-container-width.d.ts +6 -0
  228. package/dist/utils/use-container-width.js +19 -0
  229. package/package.json +2 -2
  230. package/scripts/build-theme.mjs +46 -5
  231. package/src/ai/code-block/code-block.tsx +1 -1
  232. package/src/atoms/big-date/big-date.tsx +2 -2
  233. package/src/atoms/button/button.tsx +8 -3
  234. package/src/atoms/chip/chip.tsx +8 -3
  235. package/src/atoms/icon-button/icon-button.tsx +1 -1
  236. package/src/atoms/internal/hit-area.ts +5 -4
  237. package/src/atoms/progress/index.ts +8 -1
  238. package/src/atoms/progress/progress.tsx +30 -1
  239. package/src/atoms/radio-group/radio-group.tsx +1 -1
  240. package/src/atoms/status-pill/status-pill.tsx +59 -18
  241. package/src/brand/logo-forge.tsx +1 -1
  242. package/src/charts/candlestick-chart/candlestick-chart.tsx +2 -2
  243. package/src/charts/chart-grid/chart-grid.tsx +2 -2
  244. package/src/charts/chord-chart/chord-chart.tsx +1 -1
  245. package/src/charts/core/axes.tsx +2 -2
  246. package/src/charts/core/cartesian/annotations.tsx +2 -2
  247. package/src/charts/core/cartesian/marks.tsx +1 -1
  248. package/src/charts/core/distribution/marks.tsx +1 -1
  249. package/src/charts/core/distribution/xy-points.tsx +1 -1
  250. package/src/charts/core/export-menu.tsx +1 -1
  251. package/src/charts/funnel-chart/funnel-chart.tsx +1 -1
  252. package/src/charts/gantt-chart/gantt-chart.tsx +4 -4
  253. package/src/charts/gantt-chart/gantt-marks.tsx +3 -3
  254. package/src/charts/index.ts +2 -0
  255. package/src/charts/maps/geo/map-data-table.tsx +1 -1
  256. package/src/charts/polar-area-chart/polar-area-chart.tsx +1 -1
  257. package/src/charts/radar-chart/radar-chart.tsx +1 -1
  258. package/src/charts/stock-chart/stock-chart.tsx +1 -1
  259. package/src/charts/stock-chart/stock-drawing-layer.tsx +3 -3
  260. package/src/charts/stock-chart/stock-plot.tsx +2 -2
  261. package/src/containers/chat-thread/chat-thread.tsx +331 -0
  262. package/src/containers/chat-thread/format.ts +67 -0
  263. package/src/containers/chat-thread/index.ts +12 -0
  264. package/src/containers/cols/cols.tsx +13 -1
  265. package/src/containers/comment/comment.tsx +1 -1
  266. package/src/containers/context-rail/context-rail.tsx +229 -0
  267. package/src/containers/context-rail/index.ts +7 -0
  268. package/src/containers/dashboard/dashboard.tsx +142 -0
  269. package/src/containers/dashboard/index.ts +12 -0
  270. package/src/containers/data-grid/data-grid.demos.tsx +4 -4
  271. package/src/containers/data-grid/data-grid.tsx +6 -6
  272. package/src/containers/data-grid/filter-builder-editor.tsx +2 -2
  273. package/src/containers/data-grid/grid-toolbar.tsx +1 -1
  274. package/src/containers/data-grid/spreadsheet.demos.tsx +1 -1
  275. package/src/containers/detail-header/detail-header.tsx +64 -0
  276. package/src/containers/detail-header/index.ts +5 -0
  277. package/src/containers/facts/facts.tsx +1 -1
  278. package/src/containers/filter-bar/filter-bar.tsx +201 -0
  279. package/src/containers/filter-bar/index.ts +7 -0
  280. package/src/containers/hbars/hbars.tsx +2 -2
  281. package/src/containers/index.ts +9 -0
  282. package/src/containers/kanban/kanban.tsx +146 -39
  283. package/src/containers/kanban/model.ts +20 -0
  284. package/src/containers/kpi/kpi.tsx +1 -1
  285. package/src/containers/kpi-group/kpi-group.tsx +17 -2
  286. package/src/containers/list-detail/index.ts +5 -0
  287. package/src/containers/list-detail/list-detail.tsx +157 -9
  288. package/src/containers/page/page.tsx +61 -7
  289. package/src/containers/page-header/back.tsx +42 -0
  290. package/src/containers/page-header/index.ts +1 -0
  291. package/src/containers/page-header/page-header.tsx +49 -3
  292. package/src/containers/pagination/cursor-pagination.tsx +79 -0
  293. package/src/containers/pagination/index.ts +7 -0
  294. package/src/containers/pagination/pagination.tsx +266 -0
  295. package/src/containers/pagination/range.ts +68 -0
  296. package/src/containers/pagination/use-pagination.ts +44 -0
  297. package/src/containers/responsive-list/responsive-list.tsx +183 -46
  298. package/src/containers/row-actions/index.ts +1 -0
  299. package/src/containers/row-actions/row-actions.tsx +114 -0
  300. package/src/containers/selectable-card/index.ts +5 -0
  301. package/src/containers/selectable-card/selectable-card.tsx +84 -0
  302. package/src/containers/settings-layout/settings-layout.tsx +104 -13
  303. package/src/containers/shortcuts/shortcuts.tsx +1 -1
  304. package/src/containers/table/cell-padding.ts +2 -0
  305. package/src/containers/table/index.ts +6 -0
  306. package/src/containers/table/sort.ts +23 -0
  307. package/src/containers/table/table-parts.tsx +81 -0
  308. package/src/containers/table/table.tsx +212 -45
  309. package/src/containers/table-columns-menu/index.ts +5 -0
  310. package/src/containers/table-columns-menu/table-columns-menu.tsx +68 -0
  311. package/src/dashboards/layout.tsx +8 -75
  312. package/src/forms/chip-group/chip-group.tsx +8 -1
  313. package/src/forms/combobox/combobox.tsx +1 -1
  314. package/src/forms/copy-field/copy-field.tsx +1 -1
  315. package/src/forms/date-picker/date-picker.tsx +7 -2
  316. package/src/forms/date-picker/date-time-picker.tsx +28 -2
  317. package/src/forms/field/field.tsx +30 -3
  318. package/src/forms/fieldset/fieldset.tsx +22 -0
  319. package/src/forms/fieldset/index.ts +1 -0
  320. package/src/forms/form-footer/form-footer.tsx +74 -0
  321. package/src/forms/form-footer/index.ts +1 -0
  322. package/src/forms/form-grid/form-grid.tsx +42 -5
  323. package/src/forms/form-grid/index.ts +8 -1
  324. package/src/forms/form-section/form-section.tsx +41 -0
  325. package/src/forms/form-section/index.ts +1 -0
  326. package/src/forms/index.ts +3 -0
  327. package/src/forms/input/input.tsx +10 -3
  328. package/src/forms/internal/listbox-items.tsx +3 -4
  329. package/src/forms/native-select/native-select.tsx +1 -1
  330. package/src/forms/select/index.ts +1 -1
  331. package/src/forms/select/select.tsx +14 -3
  332. package/src/forms/select-menu/select-menu.tsx +1 -1
  333. package/src/forms/time-input/time-input.tsx +6 -2
  334. package/src/i18n/strings.ts +86 -0
  335. package/src/motion/count-up.tsx +83 -0
  336. package/src/motion/cross-fade.tsx +139 -0
  337. package/src/motion/index.ts +5 -0
  338. package/src/motion/model.ts +86 -0
  339. package/src/motion/motion-styles.tsx +47 -0
  340. package/src/motion/reveal.tsx +115 -0
  341. package/src/motion/use-enter-phase.ts +50 -0
  342. package/src/motion/use-highlight-row.ts +63 -0
  343. package/src/navigation/tabs/tabs.tsx +1 -1
  344. package/src/navigation/wizard/wizard.tsx +6 -1
  345. package/src/overlays/alert-dialog/alert-dialog.tsx +5 -1
  346. package/src/overlays/context-menu/context-menu.tsx +3 -2
  347. package/src/overlays/dialog/dialog.tsx +7 -2
  348. package/src/overlays/drawer/drawer.tsx +68 -6
  349. package/src/overlays/drawer/index.ts +1 -0
  350. package/src/overlays/dropdown-menu/dropdown-menu.tsx +5 -4
  351. package/src/overlays/hover-card/hover-card.tsx +2 -0
  352. package/src/overlays/popover/popover.tsx +2 -0
  353. package/src/overlays/toaster/index.ts +2 -0
  354. package/src/overlays/toaster/toaster.tsx +113 -17
  355. package/src/overlays/tooltip/tooltip.tsx +2 -0
  356. package/src/primitives/use-presence.ts +13 -0
  357. package/src/shell/app-shell/app-shell.tsx +54 -2
  358. package/src/shell/index.ts +1 -0
  359. package/src/shell/sidebar/sidebar.tsx +154 -75
  360. package/src/shell/topbar/topbar.tsx +8 -0
  361. package/src/showcase/operations-bento.tsx +2 -2
  362. package/src/states/empty-state/empty-state.tsx +52 -9
  363. package/src/states/error-state/error-state.tsx +1 -1
  364. package/src/states/skeleton/skeleton.tsx +1 -1
  365. package/src/utils/class-tokens.generated.ts +4 -6
  366. package/src/utils/list-navigation.ts +63 -0
  367. package/src/utils/overlay-motion.ts +33 -0
  368. package/src/utils/use-container-width.ts +24 -0
  369. package/styles/Theme.kt +15 -18
  370. package/styles/tailwind.css +29 -28
  371. package/styles/theme.css +29 -28
  372. package/styles/tokens.css +46 -0
  373. package/tokens/default.json +51 -29
@@ -1,17 +1,71 @@
1
- import type { ComponentPropsWithoutRef } from "react";
1
+ import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
2
2
  import { cn } from "../../utils/cn.js";
3
3
 
4
- export type PageProps = ComponentPropsWithoutRef<"div">;
4
+ export interface PageProps extends ComponentPropsWithoutRef<"div"> {
5
+ /**
6
+ * A fixed column beside the page content, usually an `Aside`. The column draws a divider and the
7
+ * page background, never narrows the width the `page` container measures (so `Cols` inside the
8
+ * content react the same with or without it), and falls under the content once the page is
9
+ * 1000px wide or less. With an aside, `className` and the other props apply to the content column.
10
+ */
11
+ aside?: ReactNode;
12
+ /** Width of the aside column: a number is pixels, a string any CSS length. Default `20rem` (320px at 16px). */
13
+ asideWidth?: number | string;
14
+ /** Keeps the aside column in view and scrolls it on its own beside the content (above 1000px). */
15
+ asideSticky?: boolean;
16
+ }
17
+
18
+ const CONTENT = "flex w-full min-w-0 flex-col gap-6";
5
19
 
6
20
  /**
7
21
  * Vertical flow of page sections. It is the `page` container, so `Cols` and `SettingsLayout`
8
- * inside it react to the page width instead of the viewport.
22
+ * inside it react to the page width instead of the viewport. With `aside` the page is a content
23
+ * column plus a rail; the shell around the page still owns the outer gutter and scrolling.
9
24
  */
10
- export function Page({ className, ...props }: PageProps) {
25
+ export function Page({
26
+ aside,
27
+ asideWidth,
28
+ asideSticky = false,
29
+ className,
30
+ style,
31
+ children,
32
+ ...props
33
+ }: PageProps) {
34
+ if (aside === undefined) {
35
+ return (
36
+ <div className={cn("@container/page", CONTENT, className)} style={style} {...props}>
37
+ {children}
38
+ </div>
39
+ );
40
+ }
41
+ const width =
42
+ asideWidth === undefined
43
+ ? undefined
44
+ : typeof asideWidth === "number"
45
+ ? `${asideWidth}px`
46
+ : asideWidth;
11
47
  return (
12
48
  <div
13
- className={cn("@container/page flex w-full min-w-0 flex-col gap-6", className)}
14
- {...props}
15
- />
49
+ data-page-aside=""
50
+ className="@container/page w-full min-w-0"
51
+ style={width === undefined ? undefined : ({ "--page-aside-width": width } as CSSProperties)}
52
+ >
53
+ <div className="grid grid-cols-[minmax(0,1fr)_var(--page-aside-width,20rem)] items-start @max-[1000px]/page:grid-cols-[minmax(0,1fr)]">
54
+ <div className={cn(CONTENT, className)} style={style} {...props}>
55
+ {children}
56
+ </div>
57
+ <div
58
+ data-page-rail=""
59
+ className={cn(
60
+ "flex min-w-0 flex-col self-stretch border-l-divider bg-surface",
61
+ "@max-[1000px]/page:border-t-divider @max-[1000px]/page:border-l-0",
62
+ asideSticky &&
63
+ "@min-[1001px]/page:sticky @min-[1001px]/page:top-0 @min-[1001px]/page:max-h-dvh @min-[1001px]/page:self-start @min-[1001px]/page:overflow-y-auto",
64
+ )}
65
+ >
66
+ {aside}
67
+ </div>
68
+ </div>
69
+ </div>
16
70
  );
17
71
  }
@@ -0,0 +1,42 @@
1
+ "use client";
2
+
3
+ import type { ComponentPropsWithoutRef } from "react";
4
+ import { useUiStrings } from "../../i18n/index.js";
5
+ import { ChevronLeft } from "../../icons/index.js";
6
+ import { cn } from "../../utils/cn.js";
7
+ import { Slot } from "../../utils/slot.js";
8
+
9
+ export interface PageHeaderBackProps extends ComponentPropsWithoutRef<"a"> {
10
+ /** Renders the single child element (a router `Link`) with the link's look. The child supplies the label. */
11
+ asChild?: boolean | undefined;
12
+ }
13
+
14
+ /**
15
+ * The way back to the parent screen, for `PageHeader`'s `back` slot. A real link: pass `href`, or
16
+ * `asChild` with your router's `Link`. The label defaults to the localized "Back".
17
+ */
18
+ export function PageHeaderBack({
19
+ asChild = false,
20
+ className,
21
+ children,
22
+ ...props
23
+ }: PageHeaderBackProps) {
24
+ const strings = useUiStrings();
25
+ const classes = cn(
26
+ "inline-flex min-h-8 items-center gap-1 text-control text-ink-2 no-underline hover:text-ink focus-visible:focus-ring",
27
+ className,
28
+ );
29
+ if (asChild) {
30
+ return (
31
+ <Slot {...props} className={classes}>
32
+ {children}
33
+ </Slot>
34
+ );
35
+ }
36
+ return (
37
+ <a {...props} className={classes}>
38
+ <ChevronLeft aria-hidden="true" className="size-4" />
39
+ {children ?? strings.back}
40
+ </a>
41
+ );
42
+ }
@@ -1 +1,2 @@
1
+ export * from "./back.js";
1
2
  export * from "./page-header.js";
@@ -1,4 +1,4 @@
1
- import type { ComponentPropsWithoutRef, ReactNode } from "react";
1
+ import type { ComponentPropsWithoutRef, CSSProperties, ReactNode } from "react";
2
2
  import { cn } from "../../utils/cn.js";
3
3
 
4
4
  export interface PageHeaderProps extends ComponentPropsWithoutRef<"header"> {
@@ -6,32 +6,78 @@ export interface PageHeaderProps extends ComponentPropsWithoutRef<"header"> {
6
6
  breadcrumbs?: ReactNode;
7
7
  /** Tighter, centred header with a smaller title and a body-size lede. */
8
8
  compact?: boolean;
9
+ /** Link to the parent screen on its own row above the title: a `PageHeaderBack`. Shown before `breadcrumbs`. */
10
+ back?: ReactNode;
11
+ /** Row under the title block for status chips and short facts. Wraps; never needs a container query. */
12
+ meta?: ReactNode;
13
+ /**
14
+ * Sub-navigation under the title, full width: a `TabsNav` (route tabs) or a `Tabs` list. The
15
+ * strip carries its own bottom divider, so it closes the header.
16
+ */
17
+ tabs?: ReactNode;
18
+ /**
19
+ * Keeps the whole header, tabs included, at the top of its scroll container with an opaque page
20
+ * background. The navigation inside stays reachable while the page scrolls.
21
+ */
22
+ sticky?: boolean;
23
+ /** Distance a sticky header keeps from the top of its scroll container (number = pixels). Default `0`. */
24
+ stickyOffset?: number | string;
9
25
  }
10
26
 
11
27
  /**
12
28
  * Page header. No required parts: compose an eyebrow / title / lede block in
13
29
  * a plain `<div>` and, when the view has buttons, `PageHeaderActions` as the
14
- * second child. Actions wrap under the title when the container is too narrow.
30
+ * second child. Actions wrap under the title when the container is too narrow. `back`,
31
+ * `breadcrumbs`, `meta` and `tabs` each take a full-width row around the children.
15
32
  */
16
33
  export function PageHeader({
17
34
  breadcrumbs,
35
+ back,
36
+ meta,
37
+ tabs,
38
+ sticky,
39
+ stickyOffset,
18
40
  className,
19
41
  compact,
42
+ style,
20
43
  children,
21
44
  ...props
22
45
  }: PageHeaderProps) {
23
46
  return (
24
47
  <header
25
48
  data-compact={compact ? "" : undefined}
49
+ data-sticky={sticky ? "" : undefined}
26
50
  className={cn(
27
51
  "flex flex-wrap items-end justify-between gap-x-6 gap-y-3.5",
28
52
  compact && "flex-col items-center justify-center gap-y-2 text-center",
53
+ sticky && "sticky top-(--page-header-top,0px) z-10 bg-surface",
29
54
  className,
30
55
  )}
56
+ style={
57
+ stickyOffset === undefined
58
+ ? style
59
+ : ({
60
+ ...style,
61
+ "--page-header-top":
62
+ typeof stickyOffset === "number" ? `${stickyOffset}px` : stickyOffset,
63
+ } as CSSProperties)
64
+ }
31
65
  {...props}
32
66
  >
67
+ {back ? <div className="basis-full">{back}</div> : null}
33
68
  {breadcrumbs ? <div className="basis-full">{breadcrumbs}</div> : null}
34
69
  {children}
70
+ {meta ? (
71
+ <div
72
+ className={cn(
73
+ "flex basis-full flex-wrap items-center gap-x-3 gap-y-1.5 text-ink-2 text-meta",
74
+ compact && "justify-center",
75
+ )}
76
+ >
77
+ {meta}
78
+ </div>
79
+ ) : null}
80
+ {tabs ? <div className="basis-full">{tabs}</div> : null}
35
81
  </header>
36
82
  );
37
83
  }
@@ -54,7 +100,7 @@ export function PageHeaderTitle({ className, ...props }: PageHeaderTitleProps) {
54
100
  return (
55
101
  <h1
56
102
  className={cn(
57
- "m-0 break-words text-page-title [text-wrap:balance] in-data-compact:text-fs-220",
103
+ "m-0 break-words text-page-title [text-wrap:balance] in-data-compact:text-fs-200",
58
104
  className,
59
105
  )}
60
106
  {...props}
@@ -0,0 +1,79 @@
1
+ "use client";
2
+
3
+ import { type ComponentPropsWithoutRef, useMemo } from "react";
4
+ import { Button } from "../../atoms/button/button.js";
5
+ import { useUiStrings } from "../../i18n/index.js";
6
+ import { cn } from "../../utils/cn.js";
7
+ import { formatRange } from "./range.js";
8
+
9
+ export interface CursorPaginationLabels {
10
+ nav: string;
11
+ /** `{first}` and `{last}` are replaced. */
12
+ range: string;
13
+ previous: string;
14
+ next: string;
15
+ }
16
+
17
+ export interface CursorPaginationProps
18
+ extends Omit<ComponentPropsWithoutRef<"nav">, "children" | "onChange"> {
19
+ /** 1-based page the cursor trail is on. */
20
+ page: number;
21
+ /** Rows on this page. */
22
+ count: number;
23
+ /** Rows per page, to number the range. Default 25. */
24
+ pageSize?: number;
25
+ /** Whether the server reported a next cursor. */
26
+ hasNext: boolean;
27
+ onPrevious: () => void;
28
+ onNext: () => void;
29
+ /** Texts (localized by default through `UiStrings`). */
30
+ labels?: Partial<CursorPaginationLabels>;
31
+ }
32
+
33
+ /**
34
+ * Footer for server-side cursor paging, where the total is unknown: the range on screen ("Showing
35
+ * 26–50") and Previous / Next. Keep the cursor trail yourself; this only reports the clicks. It
36
+ * renders nothing while the whole list fits on the first page.
37
+ */
38
+ export function CursorPagination({
39
+ page,
40
+ count,
41
+ pageSize = 25,
42
+ hasNext,
43
+ onPrevious,
44
+ onNext,
45
+ labels,
46
+ className,
47
+ ...props
48
+ }: CursorPaginationProps) {
49
+ const strings = useUiStrings();
50
+ const format = useMemo(() => new Intl.NumberFormat(strings.locale), [strings.locale]);
51
+ if (page <= 1 && !hasNext) return null;
52
+ const first = (Math.max(1, page) - 1) * pageSize + 1;
53
+ const last = first + Math.max(count, 1) - 1;
54
+ return (
55
+ <nav
56
+ aria-label={labels?.nav ?? strings.pagination}
57
+ className={cn(
58
+ "flex min-w-0 flex-wrap items-center justify-between gap-x-4 gap-y-2 py-2 text-fs-120 text-ink-2",
59
+ className,
60
+ )}
61
+ {...props}
62
+ >
63
+ <span aria-live="polite" className="tabular-nums">
64
+ {formatRange(labels?.range ?? strings.showingRangeOpen, {
65
+ first: format.format(first),
66
+ last: format.format(last),
67
+ })}
68
+ </span>
69
+ <span className="flex items-center gap-1">
70
+ <Button size="sm" disabled={page <= 1} onClick={onPrevious}>
71
+ {labels?.previous ?? strings.previous}
72
+ </Button>
73
+ <Button size="sm" disabled={!hasNext} onClick={onNext}>
74
+ {labels?.next ?? strings.next}
75
+ </Button>
76
+ </span>
77
+ </nav>
78
+ );
79
+ }
@@ -0,0 +1,7 @@
1
+ export {
2
+ CursorPagination,
3
+ type CursorPaginationLabels,
4
+ type CursorPaginationProps,
5
+ } from "./cursor-pagination.js";
6
+ export { Pagination, type PaginationLabels, type PaginationProps } from "./pagination.js";
7
+ export { type PaginationState, usePagination } from "./use-pagination.js";
@@ -0,0 +1,266 @@
1
+ "use client";
2
+
3
+ import { type ComponentPropsWithoutRef, useId, useMemo } from "react";
4
+ import { Button } from "../../atoms/button/button.js";
5
+ import { useUiStrings } from "../../i18n/index.js";
6
+ import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from "../../icons/index.js";
7
+ import { cn } from "../../utils/cn.js";
8
+ import { useControllableState } from "../../utils/use-controllable-state.js";
9
+ import {
10
+ clampPage,
11
+ formatPageRange,
12
+ formatRange,
13
+ pageCount,
14
+ pageItems,
15
+ pageRange,
16
+ } from "./range.js";
17
+
18
+ export {
19
+ clampPage,
20
+ formatPageRange,
21
+ formatRange,
22
+ type PageItem,
23
+ pageCount,
24
+ pageItems,
25
+ pageRange,
26
+ } from "./range.js";
27
+
28
+ export interface PaginationLabels {
29
+ nav: string;
30
+ rowsPerPage: string;
31
+ /** `{first}`, `{last}` and `{total}` are replaced. */
32
+ range: string;
33
+ first: string;
34
+ previous: string;
35
+ next: string;
36
+ last: string;
37
+ /** Range text of the `pages` variant; `{first}`, `{last}` and `{total}` are replaced. */
38
+ showing: string;
39
+ /** Visible label of the previous button of the `pages` variant. */
40
+ previousLabel: string;
41
+ /** Visible label of the next button of the `pages` variant. */
42
+ nextLabel: string;
43
+ /** Name of a page number button; `{page}` is replaced. */
44
+ pageNumber: string;
45
+ }
46
+
47
+ export interface PaginationProps extends Omit<ComponentPropsWithoutRef<"nav">, "onChange"> {
48
+ /** Total rows across every page. */
49
+ total: number;
50
+ /** Controlled 1-based page. Pair it with `onPageChange`. */
51
+ page?: number;
52
+ /** Initial page when uncontrolled. Default 1. */
53
+ defaultPage?: number;
54
+ onPageChange?: (page: number) => void;
55
+ /** Controlled rows per page. Pair it with `onPageSizeChange`. */
56
+ pageSize?: number;
57
+ /** Initial rows per page when uncontrolled. Default: the first of `pageSizeOptions`. */
58
+ defaultPageSize?: number;
59
+ onPageSizeChange?: (pageSize: number) => void;
60
+ /** Choices of the page size picker. Default `[10, 25, 50, 100]`; a single option hides the picker. */
61
+ pageSizeOptions?: readonly number[];
62
+ /** Texts (localized by default through `UiStrings`). */
63
+ labels?: Partial<PaginationLabels>;
64
+ /**
65
+ * `default`: rows per page, the range and first/previous/next/last icon buttons. `pages`: the
66
+ * range ("Showing 1–25 of 134") and Previous, page number and Next buttons; it shows the page size
67
+ * picker only when `pageSizeOptions` is passed with more than one option.
68
+ */
69
+ variant?: "default" | "pages";
70
+ /** Renders nothing while every row fits on one page. Default `true` for `pages`, `false` otherwise. */
71
+ hideOnSinglePage?: boolean;
72
+ }
73
+
74
+ const DEFAULT_OPTIONS = [10, 25, 50, 100] as const;
75
+
76
+ const stepButton =
77
+ "grid size-8 place-items-center rounded-control text-ink-2 hover:bg-surface-2 hover:text-ink focus-visible:focus-ring disabled:pointer-events-none disabled:opacity-35 [&_svg]:size-4";
78
+
79
+ /**
80
+ * Footer of a list or table: rows per page, the range shown ("11–20 of 134") and first, previous,
81
+ * next and last buttons. Pages are 1-based. It does not slice your rows: use `page` and `pageSize`
82
+ * to do that, or to request the page from your API. Changing the page size returns to page 1.
83
+ */
84
+ export function Pagination({
85
+ total,
86
+ page,
87
+ defaultPage = 1,
88
+ onPageChange,
89
+ pageSize,
90
+ defaultPageSize,
91
+ onPageSizeChange,
92
+ pageSizeOptions: pageSizeOptionsProp,
93
+ labels,
94
+ variant = "default",
95
+ hideOnSinglePage = variant === "pages",
96
+ className,
97
+ ...props
98
+ }: PaginationProps) {
99
+ const pageSizeOptions = pageSizeOptionsProp ?? DEFAULT_OPTIONS;
100
+ const strings = useUiStrings();
101
+ const selectId = useId();
102
+ const [size, setSize] = useControllableState<number>({
103
+ prop: pageSize,
104
+ defaultProp: defaultPageSize ?? pageSizeOptions[0] ?? DEFAULT_OPTIONS[0],
105
+ onChange: onPageSizeChange,
106
+ });
107
+ const [current, setPage] = useControllableState<number>({
108
+ prop: page,
109
+ defaultProp: defaultPage,
110
+ onChange: onPageChange,
111
+ });
112
+ const text: PaginationLabels = {
113
+ nav: labels?.nav ?? strings.pagination,
114
+ rowsPerPage: labels?.rowsPerPage ?? strings.rowsPerPage,
115
+ range: labels?.range ?? strings.pageRange,
116
+ first: labels?.first ?? strings.firstPage,
117
+ previous: labels?.previous ?? strings.previousPage,
118
+ next: labels?.next ?? strings.nextPage,
119
+ last: labels?.last ?? strings.lastPage,
120
+ showing: labels?.showing ?? strings.showingRange,
121
+ previousLabel: labels?.previousLabel ?? strings.previous,
122
+ nextLabel: labels?.nextLabel ?? strings.next,
123
+ pageNumber: labels?.pageNumber ?? strings.pageNumber,
124
+ };
125
+ const pages = pageCount(total, size);
126
+ const at = clampPage(current, pages);
127
+ const { first, last } = pageRange(at, size, total);
128
+ const format = useMemo(() => new Intl.NumberFormat(strings.locale), [strings.locale]);
129
+ const sizes = [...new Set([...pageSizeOptions, size])].sort((a, b) => a - b);
130
+ const atStart = at <= 1;
131
+ const atEnd = at >= pages;
132
+ if (hideOnSinglePage && pages <= 1) return null;
133
+ const picker =
134
+ sizes.length > 1 && (variant === "default" || pageSizeOptionsProp !== undefined) ? (
135
+ <span className="flex items-center gap-2">
136
+ <label htmlFor={selectId}>{text.rowsPerPage}</label>
137
+ <select
138
+ id={selectId}
139
+ value={size}
140
+ onChange={(event) => {
141
+ setSize(Number(event.target.value));
142
+ setPage(1);
143
+ }}
144
+ className="h-control-sm rounded-input border-control bg-surface-control px-1.5 text-fs-120 text-ink"
145
+ >
146
+ {sizes.map((option) => (
147
+ <option key={option} value={option}>
148
+ {option}
149
+ </option>
150
+ ))}
151
+ </select>
152
+ </span>
153
+ ) : null;
154
+ if (variant === "pages") {
155
+ return (
156
+ <nav
157
+ aria-label={text.nav}
158
+ className={cn(
159
+ "flex min-w-0 flex-wrap items-center justify-between gap-x-4 gap-y-2 py-2 text-fs-120 text-ink-2",
160
+ className,
161
+ )}
162
+ {...props}
163
+ >
164
+ <span aria-live="polite" className="tabular-nums">
165
+ {formatRange(text.showing, {
166
+ first: format.format(first),
167
+ last: format.format(last),
168
+ total: format.format(Math.max(0, total)),
169
+ })}
170
+ </span>
171
+ <span className="flex flex-wrap items-center gap-x-4 gap-y-2">
172
+ {picker}
173
+ <span className="flex items-center gap-1">
174
+ <Button size="sm" disabled={atStart} onClick={() => setPage(at - 1)}>
175
+ {text.previousLabel}
176
+ </Button>
177
+ {pageItems(at, pages).map((item, index) =>
178
+ item === "gap" ? (
179
+ <span
180
+ // biome-ignore lint/suspicious/noArrayIndexKey: a gap has no identity besides its slot
181
+ key={`gap-${index}`}
182
+ aria-hidden="true"
183
+ className="w-6 text-center text-ink-3"
184
+ >
185
+ …
186
+ </span>
187
+ ) : (
188
+ <Button
189
+ key={item}
190
+ size="sm"
191
+ variant={item === at ? "secondary" : "ghost"}
192
+ aria-current={item === at ? "page" : undefined}
193
+ aria-label={text.pageNumber.replace("{page}", String(item))}
194
+ onClick={() => setPage(item)}
195
+ className="min-w-control-sm px-2 tabular-nums"
196
+ >
197
+ {format.format(item)}
198
+ </Button>
199
+ ),
200
+ )}
201
+ <Button size="sm" disabled={atEnd} onClick={() => setPage(at + 1)}>
202
+ {text.nextLabel}
203
+ </Button>
204
+ </span>
205
+ </span>
206
+ </nav>
207
+ );
208
+ }
209
+ return (
210
+ <nav
211
+ aria-label={text.nav}
212
+ className={cn(
213
+ "@container/pagination flex min-w-0 flex-wrap items-center justify-end gap-x-4 gap-y-1 px-2 py-1.5 text-fs-120 text-ink-2",
214
+ className,
215
+ )}
216
+ {...props}
217
+ >
218
+ {picker}
219
+ <span aria-live="polite" className="tabular-nums">
220
+ {formatPageRange(text.range, {
221
+ first: format.format(first),
222
+ last: format.format(last),
223
+ total: format.format(Math.max(0, total)),
224
+ })}
225
+ </span>
226
+ <span className="flex items-center">
227
+ <button
228
+ type="button"
229
+ className={stepButton}
230
+ aria-label={text.first}
231
+ disabled={atStart}
232
+ onClick={() => setPage(1)}
233
+ >
234
+ <ChevronsLeft aria-hidden="true" />
235
+ </button>
236
+ <button
237
+ type="button"
238
+ className={stepButton}
239
+ aria-label={text.previous}
240
+ disabled={atStart}
241
+ onClick={() => setPage(at - 1)}
242
+ >
243
+ <ChevronLeft aria-hidden="true" />
244
+ </button>
245
+ <button
246
+ type="button"
247
+ className={stepButton}
248
+ aria-label={text.next}
249
+ disabled={atEnd}
250
+ onClick={() => setPage(at + 1)}
251
+ >
252
+ <ChevronRight aria-hidden="true" />
253
+ </button>
254
+ <button
255
+ type="button"
256
+ className={stepButton}
257
+ aria-label={text.last}
258
+ disabled={atEnd}
259
+ onClick={() => setPage(pages)}
260
+ >
261
+ <ChevronsRight aria-hidden="true" />
262
+ </button>
263
+ </span>
264
+ </nav>
265
+ );
266
+ }
@@ -0,0 +1,68 @@
1
+ /** Number of pages for `total` rows; at least 1 so an empty list still has a first page. */
2
+ export function pageCount(total: number, pageSize: number): number {
3
+ if (pageSize <= 0) return 1;
4
+ return Math.max(1, Math.ceil(Math.max(0, total) / pageSize));
5
+ }
6
+
7
+ /** Keeps a 1-based page inside `1..pages`. */
8
+ export function clampPage(page: number, pages: number): number {
9
+ return Math.min(Math.max(1, Math.trunc(page) || 1), pages);
10
+ }
11
+
12
+ /** 1-based first and last row shown on `page`; `{ first: 0, last: 0 }` when there are no rows. */
13
+ export function pageRange(
14
+ page: number,
15
+ pageSize: number,
16
+ total: number,
17
+ ): { first: number; last: number } {
18
+ if (total <= 0 || pageSize <= 0) return { first: 0, last: 0 };
19
+ const current = clampPage(page, pageCount(total, pageSize));
20
+ return { first: (current - 1) * pageSize + 1, last: Math.min(total, current * pageSize) };
21
+ }
22
+
23
+ /** Fills the `{first}`, `{last}` and `{total}` placeholders of the `pageRange` UI string. */
24
+ export function formatPageRange(
25
+ template: string,
26
+ values: { first: string; last: string; total: string },
27
+ ): string {
28
+ return template
29
+ .replace("{first}", values.first)
30
+ .replace("{last}", values.last)
31
+ .replace("{total}", values.total);
32
+ }
33
+
34
+ /** A page number button, or a gap between two runs of them. */
35
+ export type PageItem = number | "gap";
36
+
37
+ /**
38
+ * The page buttons to show: the first and last page, the current one with `siblings` on each side,
39
+ * and a `"gap"` where pages are left out. A gap never hides a single page (that page shows instead),
40
+ * so the list keeps the same length while the current page moves through the middle.
41
+ */
42
+ export function pageItems(page: number, pages: number, siblings = 1): PageItem[] {
43
+ const total = Math.max(1, Math.trunc(pages));
44
+ const current = clampPage(page, total);
45
+ const slots = siblings * 2 + 5;
46
+ if (total <= slots) return Array.from({ length: total }, (_, i) => i + 1);
47
+ const start = Math.max(Math.min(current - siblings, total - siblings * 2 - 2), 3);
48
+ const end = Math.min(Math.max(current + siblings, siblings * 2 + 3), total - 2);
49
+ const middle = Array.from({ length: end - start + 1 }, (_, i) => start + i);
50
+ return [
51
+ 1,
52
+ start > 3 ? ("gap" as const) : 2,
53
+ ...middle,
54
+ end < total - 2 ? ("gap" as const) : total - 1,
55
+ total,
56
+ ];
57
+ }
58
+
59
+ /** Fills `{first}` and `{last}` (and `{total}` when given) in a range template. */
60
+ export function formatRange(
61
+ template: string,
62
+ values: { first: string; last: string; total?: string },
63
+ ): string {
64
+ return template
65
+ .replace("{first}", values.first)
66
+ .replace("{last}", values.last)
67
+ .replace("{total}", values.total ?? "");
68
+ }
@@ -0,0 +1,44 @@
1
+ "use client";
2
+
3
+ import { useMemo, useState } from "react";
4
+ import { clampPage, pageCount } from "./range.js";
5
+
6
+ export interface PaginationState<T> {
7
+ /** Current 1-based page, always inside `1..pageCount`. */
8
+ page: number;
9
+ pageCount: number;
10
+ /** Rows across every page. */
11
+ total: number;
12
+ pageSize: number;
13
+ /** The rows of the current page. */
14
+ items: readonly T[];
15
+ setPage: (page: number) => void;
16
+ }
17
+
18
+ /**
19
+ * Client-side paging over an already filtered and sorted list. The page is clamped, so a search
20
+ * that shrinks the list lands on the last page that still exists instead of an empty one, and it
21
+ * returns to the first page whenever `resetKey` changes (the search text, a filter, the sort).
22
+ * Pair it with `<Pagination variant="pages">`.
23
+ */
24
+ export function usePagination<T>(
25
+ rows: readonly T[],
26
+ resetKey: unknown = "",
27
+ pageSize = 25,
28
+ ): PaginationState<T> {
29
+ const [requested, setPage] = useState(1);
30
+ const [key, setKey] = useState(resetKey);
31
+ // Reset during render rather than in an effect, so the first page shows without a stale frame.
32
+ if (!Object.is(key, resetKey)) {
33
+ setKey(resetKey);
34
+ setPage(1);
35
+ }
36
+ const total = rows.length;
37
+ const pages = pageCount(total, pageSize);
38
+ const page = Object.is(key, resetKey) ? clampPage(requested, pages) : 1;
39
+ const items = useMemo(
40
+ () => rows.slice((page - 1) * pageSize, page * pageSize),
41
+ [rows, page, pageSize],
42
+ );
43
+ return { page, pageCount: pages, total, pageSize, items, setPage };
44
+ }