@zeyos/zx 5.7.1 → 5.8.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 (326) hide show
  1. package/CHANGELOG.md +296 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +19 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +13 -2
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +11 -0
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +7 -0
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +18 -4
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/drag-axis.d.ts +10 -5
  61. package/dist/types/core/export.d.ts +2 -2
  62. package/dist/types/core/format.d.ts +3 -1
  63. package/dist/types/core/icons.d.ts +36 -3
  64. package/dist/types/core/keyboard.d.ts +7 -3
  65. package/dist/types/core/messages.d.ts +3 -0
  66. package/dist/types/core/storage.d.ts +4 -3
  67. package/dist/types/core/util.d.ts +3 -1
  68. package/dist/types/elements/define.d.ts +5 -2
  69. package/dist/types/index.d.ts +6 -4
  70. package/dist/types/internal/agent-model.d.ts +99 -0
  71. package/dist/types/internal/app-rail.d.ts +37 -2
  72. package/dist/types/internal/collections.d.ts +18 -0
  73. package/dist/types/internal/menu-items.d.ts +27 -0
  74. package/dist/types/internal/overlay-content.d.ts +23 -0
  75. package/dist/types/internal/presence-loop.d.ts +5 -2
  76. package/dist/types/locales/index.d.ts +3 -0
  77. package/dist/types/zeyos/calendar.d.ts +43 -7
  78. package/dist/types/zeyos/connect.d.ts +4 -0
  79. package/dist/types/zeyos/form.d.ts +13 -5
  80. package/dist/types/zeyos/select.d.ts +5 -2
  81. package/dist/types/zeyos/table.d.ts +16 -8
  82. package/dist/types/zeyos/view.d.ts +2 -1
  83. package/dist/zx-zeyos.esm.js +2998 -451
  84. package/dist/zx-zeyos.esm.min.js +4 -4
  85. package/dist/zx.core.css +4 -0
  86. package/dist/zx.core.min.css +1 -1
  87. package/dist/zx.css +948 -48
  88. package/dist/zx.esm.js +7432 -3408
  89. package/dist/zx.esm.min.js +26 -26
  90. package/dist/zx.global.js +7432 -3408
  91. package/dist/zx.global.min.js +26 -26
  92. package/dist/zx.layered.css +950 -48
  93. package/dist/zx.layered.min.css +1 -1
  94. package/dist/zx.min.css +1 -1
  95. package/docs/agent-catalog.json +159 -1
  96. package/docs/agent-surfaces.md +21 -21
  97. package/docs/api.json +3122 -528
  98. package/docs/components/account-menu.md +24 -0
  99. package/docs/components/activity-item.md +23 -0
  100. package/docs/components/activity-list.md +28 -0
  101. package/docs/components/agent-avatar.md +59 -0
  102. package/docs/components/agent-thread.md +275 -0
  103. package/docs/components/app-icon.md +36 -0
  104. package/docs/components/app-sidebar.md +92 -0
  105. package/docs/components/approval-card.md +71 -0
  106. package/docs/components/aurora.md +34 -0
  107. package/docs/components/avatar.md +37 -0
  108. package/docs/components/badge.md +36 -0
  109. package/docs/components/block-view.md +34 -0
  110. package/docs/components/breadcrumb.md +20 -0
  111. package/docs/components/button.md +23 -0
  112. package/docs/components/calendar.md +68 -0
  113. package/docs/components/card-view.md +73 -0
  114. package/docs/components/card.md +25 -0
  115. package/docs/components/chart.md +109 -0
  116. package/docs/components/check-button.md +16 -0
  117. package/docs/components/checklist.md +19 -0
  118. package/docs/components/code-editor.md +38 -0
  119. package/docs/components/composer.md +107 -0
  120. package/docs/components/context-menu.md +32 -0
  121. package/docs/components/copy.md +37 -0
  122. package/docs/components/data-filter.md +16 -0
  123. package/docs/components/date-picker.md +31 -0
  124. package/docs/components/date-range.md +21 -0
  125. package/docs/components/datebox.md +31 -0
  126. package/docs/components/dialog.md +25 -0
  127. package/docs/components/dock.md +57 -0
  128. package/docs/components/dropdown.md +39 -0
  129. package/docs/components/elements.md +63 -0
  130. package/docs/components/empty-state.md +17 -0
  131. package/docs/components/entity-ref.md +26 -0
  132. package/docs/components/field-upload.md +18 -0
  133. package/docs/components/file-item.md +27 -0
  134. package/docs/components/file-list.md +23 -0
  135. package/docs/components/filter-panel.md +45 -0
  136. package/docs/components/filter.md +47 -0
  137. package/docs/components/finder.md +25 -0
  138. package/docs/components/form-widgets.md +42 -0
  139. package/docs/components/form.md +80 -0
  140. package/docs/components/grid.md +26 -0
  141. package/docs/components/groupbox.md +11 -0
  142. package/docs/components/helpers.md +359 -0
  143. package/docs/components/icons.md +87 -0
  144. package/docs/components/index.md +99 -0
  145. package/docs/components/kanban-view.md +42 -0
  146. package/docs/components/kbd.md +23 -0
  147. package/docs/components/kernel.md +41 -0
  148. package/docs/components/launcher.md +66 -0
  149. package/docs/components/layout.md +33 -0
  150. package/docs/components/list-toolbar.md +38 -0
  151. package/docs/components/loading.md +48 -0
  152. package/docs/components/menu-button.md +47 -0
  153. package/docs/components/message.md +76 -0
  154. package/docs/components/modal.md +27 -0
  155. package/docs/components/module-bar.md +71 -0
  156. package/docs/components/multi-value-editor.md +16 -0
  157. package/docs/components/navigation-bar.md +22 -0
  158. package/docs/components/number-field.md +34 -0
  159. package/docs/components/pagination.md +73 -0
  160. package/docs/components/panel.md +28 -0
  161. package/docs/components/prompt-starters.md +40 -0
  162. package/docs/components/prose.md +38 -0
  163. package/docs/components/questionnaire.md +115 -0
  164. package/docs/components/rating.md +19 -0
  165. package/docs/components/run-status.md +50 -0
  166. package/docs/components/run-trace.md +72 -0
  167. package/docs/components/search.md +11 -0
  168. package/docs/components/select.md +129 -0
  169. package/docs/components/sheet-stack.md +39 -0
  170. package/docs/components/sheet.md +77 -0
  171. package/docs/components/skeleton.md +27 -0
  172. package/docs/components/slider.md +29 -0
  173. package/docs/components/sort-control.md +21 -0
  174. package/docs/components/source-list.md +30 -0
  175. package/docs/components/split-view.md +12 -0
  176. package/docs/components/stat-tile.md +49 -0
  177. package/docs/components/stepper.md +27 -0
  178. package/docs/components/surface.md +152 -0
  179. package/docs/components/tabbox.md +33 -0
  180. package/docs/components/table-view.md +43 -0
  181. package/docs/components/table.md +232 -0
  182. package/docs/components/tag-picker.md +39 -0
  183. package/docs/components/timebox.md +16 -0
  184. package/docs/components/toggle.md +21 -0
  185. package/docs/components/tokens.md +82 -0
  186. package/docs/components/toolbar.md +26 -0
  187. package/docs/components/tooltip.md +16 -0
  188. package/docs/components/tree.md +48 -0
  189. package/docs/components/truncate.md +21 -0
  190. package/docs/components/value-list.md +14 -0
  191. package/docs/components/view-settings.md +56 -0
  192. package/docs/components/workspace-switcher.md +42 -0
  193. package/docs/components/zeyos.md +196 -0
  194. package/docs/llms-small.txt +299 -0
  195. package/docs/llms.md +697 -100
  196. package/docs/llms.txt +46 -19
  197. package/package.json +9 -4
  198. package/src/components/activity-item/activity-item.js +21 -2
  199. package/src/components/agent-avatar/agent-avatar.css +195 -0
  200. package/src/components/agent-avatar/agent-avatar.js +333 -0
  201. package/src/components/agent-avatar/agent-face.js +292 -0
  202. package/src/components/agent-thread/ag-ui.js +44 -11
  203. package/src/components/agent-thread/agent-thread.js +103 -11
  204. package/src/components/agent-thread/ui-message-stream.js +3 -1
  205. package/src/components/app-rail/app-rail.css +5 -0
  206. package/src/components/app-sidebar/app-sidebar.css +3 -0
  207. package/src/components/app-sidebar/app-sidebar.js +4 -3
  208. package/src/components/approval-card/approval-card.css +6 -0
  209. package/src/components/approval-card/approval-card.js +55 -7
  210. package/src/components/aurora/aurora.css +149 -14
  211. package/src/components/aurora/aurora.js +49 -6
  212. package/src/components/calendar/calendar.css +6 -2
  213. package/src/components/calendar/calendar.js +127 -47
  214. package/src/components/card-view/card-view.js +5 -6
  215. package/src/components/chart/chart.css +159 -1
  216. package/src/components/chart/chart.js +450 -62
  217. package/src/components/chart/color.js +297 -0
  218. package/src/components/chart/svg-adapter.js +576 -0
  219. package/src/components/chart/svg-geometry.js +323 -0
  220. package/src/components/check-button/check-button.js +3 -18
  221. package/src/components/checklist/checklist.js +46 -17
  222. package/src/components/checklist/field-adapter.js +4 -1
  223. package/src/components/code-editor/code-editor.css +33 -0
  224. package/src/components/code-editor/code-editor.js +97 -8
  225. package/src/components/code-editor/field-adapter.js +3 -0
  226. package/src/components/composer/composer.css +3 -0
  227. package/src/components/composer/composer.js +100 -22
  228. package/src/components/context-menu/context-menu.js +41 -5
  229. package/src/components/copy/copy-button.js +9 -1
  230. package/src/components/copy/copy-input.js +5 -0
  231. package/src/components/data-filter/filter-core.js +0 -1
  232. package/src/components/date-picker/date-picker.css +8 -0
  233. package/src/components/date-picker/date-picker.js +47 -8
  234. package/src/components/date-picker/date-range-picker.js +1 -1
  235. package/src/components/date-picker/month-picker.js +19 -3
  236. package/src/components/date-picker/time-picker.js +54 -19
  237. package/src/components/datebox/date-range-box.js +7 -3
  238. package/src/components/datebox/datebox.js +32 -6
  239. package/src/components/dialog/dialog.css +6 -0
  240. package/src/components/dialog/dialog.js +22 -30
  241. package/src/components/dropdown/dropdown.js +1 -18
  242. package/src/components/empty-state/empty-state.js +21 -2
  243. package/src/components/field/field.js +19 -3
  244. package/src/components/fieldset/fieldset.js +3 -1
  245. package/src/components/filter/filter.js +9 -0
  246. package/src/components/form/form.js +19 -2
  247. package/src/components/kanban-view/kanban-card.js +15 -2
  248. package/src/components/kanban-view/kanban-view.css +21 -0
  249. package/src/components/kanban-view/kanban-view.js +29 -16
  250. package/src/components/launcher/launcher.css +14 -0
  251. package/src/components/launcher/launcher.js +54 -9
  252. package/src/components/master-panel/master-panel.js +24 -22
  253. package/src/components/menu-button/menu-button.js +26 -4
  254. package/src/components/message/message.css +228 -29
  255. package/src/components/message/message.js +664 -30
  256. package/src/components/modal/modal.js +70 -25
  257. package/src/components/modal/native-dialog.js +91 -0
  258. package/src/components/module-bar/module-bar.css +3 -0
  259. package/src/components/module-bar/module-bar.js +17 -4
  260. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  261. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  262. package/src/components/navigation-bar/navigation-bar.js +13 -1
  263. package/src/components/number-field/field-adapter.js +3 -0
  264. package/src/components/number-field/number-field.js +2 -1
  265. package/src/components/pagination/pagination.css +26 -2
  266. package/src/components/pagination/pagination.js +551 -65
  267. package/src/components/prose/prose.js +7 -1
  268. package/src/components/rating/field-adapter.js +3 -0
  269. package/src/components/run-status/run-status.js +43 -3
  270. package/src/components/run-trace/run-trace.js +15 -7
  271. package/src/components/search/search.js +3 -18
  272. package/src/components/select/field-adapter.js +8 -1
  273. package/src/components/select/select.js +68 -13
  274. package/src/components/sheet/sheet.js +27 -8
  275. package/src/components/slider/field-adapter.js +3 -0
  276. package/src/components/slider/slider.js +4 -6
  277. package/src/components/stat-tile/stat-tile.js +24 -9
  278. package/src/components/stepper/stepper.css +15 -0
  279. package/src/components/stepper/stepper.js +34 -2
  280. package/src/components/surface/catalog.js +185 -28
  281. package/src/components/surface/surface.js +10 -5
  282. package/src/components/tabbox/tabbox.js +13 -1
  283. package/src/components/table/table.css +160 -2
  284. package/src/components/table/table.js +479 -52
  285. package/src/components/table/window.js +46 -4
  286. package/src/components/table-view/table-view.js +1 -10
  287. package/src/components/tag-picker/field-adapter.js +3 -0
  288. package/src/components/tag-picker/tag-picker.js +2 -0
  289. package/src/components/timebox/field-adapter.js +3 -0
  290. package/src/components/toggle/toggle.js +51 -27
  291. package/src/components/tooltip/tooltip.js +21 -14
  292. package/src/components/tree/tree.js +87 -14
  293. package/src/components/truncate/truncate.js +21 -5
  294. package/src/components/value-list/value-list.js +37 -9
  295. package/src/components/view-settings/view-settings.js +1 -5
  296. package/src/core/component.js +34 -2
  297. package/src/core/date.js +5 -4
  298. package/src/core/drag-axis.js +24 -7
  299. package/src/core/export.js +4 -4
  300. package/src/core/fontawesome.js +34 -3
  301. package/src/core/format.js +3 -1
  302. package/src/core/http.js +23 -11
  303. package/src/core/icons.js +51 -10
  304. package/src/core/keyboard.js +83 -9
  305. package/src/core/messages.js +3 -0
  306. package/src/core/position.js +2 -2
  307. package/src/core/storage.js +80 -31
  308. package/src/core/util.js +16 -5
  309. package/src/elements/define.js +82 -47
  310. package/src/elements/kit.js +46 -35
  311. package/src/index.js +8 -4
  312. package/src/internal/agent-model.js +152 -0
  313. package/src/internal/app-rail.js +53 -2
  314. package/src/internal/collections.js +25 -0
  315. package/src/internal/menu-items.js +59 -0
  316. package/src/internal/overlay-content.js +35 -0
  317. package/src/internal/presence-loop.js +61 -14
  318. package/src/locales/de.js +3 -0
  319. package/src/zeyos/calendar.js +81 -19
  320. package/src/zeyos/connect.js +5 -1
  321. package/src/zeyos/form.js +29 -10
  322. package/src/zeyos/select.js +36 -12
  323. package/src/zeyos/table.js +43 -11
  324. package/src/zeyos/view.js +2 -1
  325. package/styles/tokens/semantic.css +7 -1
  326. package/styles/zx.css +1 -0
@@ -2,6 +2,9 @@ import { Component } from '../../core/component.js';
2
2
  import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
3
3
  import { printf } from '../../core/i18n.js';
4
4
  import { ICON_SIZE, icon } from '../../core/icons.js';
5
+ import { clamp } from '../../core/util.js';
6
+ import { cancelFrame, nextFrame } from '../table/window.js';
7
+ import { Toggle } from '../toggle/toggle.js';
5
8
 
6
9
  /** @typedef {'pages'|'loadmore'} PaginationMode */
7
10
 
@@ -9,6 +12,8 @@ import { ICON_SIZE, icon } from '../../core/icons.js';
9
12
  const ELLIPSIS = '…';
10
13
  /** Modes the component supports. */
11
14
  const MODES = new Set(['pages', 'loadmore']);
15
+ /** The page size that fits the page to the viewport. */
16
+ const AUTO = 'auto';
12
17
 
13
18
  /**
14
19
  * @typedef {Object} PaginationRangeOptions
@@ -65,33 +70,146 @@ export function paginationRange({ page = 1, pages = 1, siblings = 1, boundaries
65
70
  ];
66
71
  }
67
72
 
73
+ /**
74
+ * @typedef {Object} FitPageSizeOptions
75
+ * @property {number} available Height the rows may fill, in pixels: the viewport's content box.
76
+ * @property {number} rowHeight Height of one row of items, the gap to the next included, in pixels.
77
+ * @property {number} [perRow=1] Items per row: 1 for a table or a list, the column count of a grid.
78
+ * @property {number} [reserve=0] Pixels of `available` something else takes, such as a sticky
79
+ * table header. Negative gives space back — a grid's last row has no gap after it.
80
+ * @property {number} [min=1] Smallest size returned.
81
+ * @property {number} [max=Infinity] Largest size returned.
82
+ */
83
+
84
+ /**
85
+ * Computes how many items fill a viewport: whole rows only, times the items per row. The rows are
86
+ * clamped so the size stays within `[min, max]` in whole rows — `min` rounds up to a full row,
87
+ * `max` down to one, and there is always at least one row — so a grid never ends on a partial
88
+ * row. Pure arithmetic, no DOM — the component measures, this decides.
89
+ *
90
+ * Returns 0 when there is nothing to measure yet (no height, no row height), so a caller can keep
91
+ * the size it has rather than collapse to the minimum while a view is still hidden.
92
+ * @param {FitPageSizeOptions} options Measurements.
93
+ * @returns {number} Items per page, or 0 when unknown.
94
+ */
95
+ export function fitPageSize({ available, rowHeight, perRow = 1, reserve = 0, min = 1, max = Infinity } = /** @type {FitPageSizeOptions} */ ({})) {
96
+ const height = Number(available);
97
+ const pitch = Number(rowHeight);
98
+ if (!Number.isFinite(height) || height <= 0 || !Number.isFinite(pitch) || pitch <= 0) return 0;
99
+ const space = height - (Number(reserve) || 0);
100
+ const columns = Math.max(1, Math.trunc(Number(perRow)) || 1);
101
+ // Half a pixel of tolerance: subpixel layout must not drop a row that visibly fits.
102
+ const rows = Math.max(0, Math.floor((space + 0.5) / pitch));
103
+ const lower = Math.max(1, toCount(min) || 1);
104
+ const upper = max == null || Number(max) === Infinity ? Infinity : Math.max(lower, toCount(max) || lower);
105
+ // Where no whole row lands inside the range, the minimum wins, as it does for single items.
106
+ const fewest = Math.ceil(lower / columns);
107
+ const most = Math.max(fewest, Math.floor(upper / columns));
108
+ return clamp(rows, fewest, most) * columns;
109
+ }
110
+
111
+ /**
112
+ * @typedef {Object} PageFitStep
113
+ * @property {number} size The page size just measured.
114
+ * @property {number} current The page size the pager has now.
115
+ * @property {number[]} [trail=[]] The sizes the pager's recent fits applied, oldest first.
116
+ * @property {number|string} viewport The viewport's size now: its height in pixels, or a key that
117
+ * changes with its width and height (`'640x300'`), as the component passes.
118
+ * @property {number|string|null} [settled=null] The viewport's size, in the same form, as the
119
+ * pager's last applied fit left it; null before the first fit.
120
+ */
121
+
122
+ /**
123
+ * Decides whether a measured page size replaces the current one while the pager fits its
124
+ * viewport. Pure, no DOM — the component measures and keeps the state, this decides.
125
+ *
126
+ * A fit changes the page count, and that can change the viewport it was measured in — a footer
127
+ * that wraps with the longer page numbers — so two sizes could take turns for ever. While the
128
+ * viewport still has the size the last fit left it at, a size that would take the pager back up
129
+ * to where it was two fits ago is that loop, and the smaller size stays. A viewport whose height
130
+ * or width changed since was resized by something else (a drawer, the window, a card grid's
131
+ * columns), and its size is followed whichever way it went, with the trail starting over.
132
+ * @param {PageFitStep} step Measurements and the pager's recent fits.
133
+ * @returns {{apply: boolean, trail: number[]}} Whether to apply `size`, and the trail to keep.
134
+ */
135
+ export function pageFitStep({ size, current, trail = [], viewport, settled = null }) {
136
+ const resized = settled == null || viewport !== settled;
137
+ const history = resized ? [] : trail;
138
+ const bounce = history.length >= 2 && history[history.length - 2] === size && size > current;
139
+ if (!(size > 0) || size === current || bounce) return { apply: false, trail: history };
140
+ return { apply: true, trail: [...history, size].slice(-4) };
141
+ }
142
+
143
+ /**
144
+ * A measurement the pager takes from its viewport: a number of pixels (or items, for `perRow`),
145
+ * or a function that reads it from the viewport — returning null hands back to the default.
146
+ * @typedef {number|((viewport: Element) => number|null|undefined)|null} PaginationMeasure
147
+ */
148
+
68
149
  /**
69
150
  * @typedef {Object} PaginationOptions
70
151
  * @property {number} [page=1] One-based current page.
71
- * @property {number} [pageSize=25] Rows per page.
152
+ * @property {number|'auto'} [pageSize=25] Rows per page, or `'auto'`: as many as fit `viewport`
153
+ * without scrolling, measured again whenever the viewport changes size.
72
154
  * @property {number} [total=0] Total row count; 0 is one empty page.
73
- * @property {number[]} [pageSizes=[25, 50, 100]] Choices offered by the page-size select.
155
+ * @property {Array<number|'auto'>} [pageSizes=[25, 50, 100]] Choices offered by the page-size
156
+ * select. `'auto'` offers the fitted size, shown with the count it currently stands for.
74
157
  * @property {number} [siblings=1] Pages shown either side of the current one.
75
158
  * @property {number} [boundaries=1] Pages pinned at each end of the range.
76
159
  * @property {boolean} [showPageSize=true] Whether to render the page-size select.
77
160
  * @property {boolean} [showSummary=true] Whether to render the "26–50 of 312" summary.
78
161
  * @property {PaginationMode} [mode='pages'] `pages` renders a numbered pager, `loadmore` a single
79
162
  * "Load more" button for append-style lists.
163
+ * @property {boolean} [autoLoad=false] Loads the next page by itself when the end of the list
164
+ * scrolls into view — infinite scroll. The pager then appends, as in `loadmore`, whatever `mode`
165
+ * says; `mode` is what it returns to when auto-load is switched off.
166
+ * @property {boolean} [showAutoLoad=false] Whether to render the Auto-load switch, so the reader
167
+ * decides between paging and continuous scrolling.
168
+ * @property {Element|string|(() => Element|null)|null} [viewport=null] The element the rows
169
+ * scroll in. `'auto'` fits the page to its height; auto-load watches its scroll position. A
170
+ * function is asked again on `refit()`, for a host that swaps its views. Without one, auto-load
171
+ * watches the pager itself approach the end of its scrolling ancestor, which suits a pager that
172
+ * follows the rows; a pager in a fixed footer needs the viewport.
173
+ * @property {PaginationMeasure} [rowHeight=null] One row's height, gap included. By default the
174
+ * first body row of a Zx Table in the viewport (`tbody > tr[data-row]`), else `--zx-row-height`.
175
+ * @property {PaginationMeasure} [perRow=1] Items per row, for a grid of cards.
176
+ * @property {PaginationMeasure} [reserve=null] Pixels of the viewport the rows cannot use. By
177
+ * default the height of the viewport's `thead`, which sticks above the rows.
178
+ * @property {number} [minPageSize=5] Smallest fitted page size.
179
+ * @property {number} [maxPageSize=200] Largest fitted page size.
180
+ * @property {number|null} [autoLoadMargin=null] How close to the end, in pixels, auto-load
181
+ * starts on the next page; half the viewport by default, so the rows arrive before they are due.
80
182
  * @property {boolean} [disabled=false] Whether every control starts disabled.
81
183
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
82
184
  * @property {(event: CustomEvent<PaginationChangeDetail>) => void} [onchange] Change listener.
185
+ * @property {(event: CustomEvent<{autoLoad: boolean}>) => void} [onautoload] Auto-load switch listener.
83
186
  */
84
187
 
85
188
  /**
86
189
  * @typedef {Object} PaginationState
87
190
  * @property {number} page One-based current page.
88
- * @property {number} pageSize Rows per page.
191
+ * @property {number} pageSize Rows per page: the fitted count while `auto`.
89
192
  * @property {number} total Total row count.
90
193
  * @property {number} pages Number of pages; at least 1.
91
194
  * @property {number} offset Zero-based row offset of the current page.
195
+ * @property {boolean} auto Whether the page size is fitted to the viewport.
196
+ * @property {boolean} autoLoad Whether the next page loads as the end comes into view.
197
+ * @property {PaginationMode} mode What the pager shows: `loadmore` while auto-load is on.
92
198
  */
93
199
 
94
- /** @typedef {PaginationState} PaginationChangeDetail */
200
+ /**
201
+ * Why a `change` fired: `page` (a page button, previous/next, `setPage()`), `pageSize` (the select,
202
+ * `setPageSize()`), `fit` (the fitted size followed the viewport), `more` (Load more), `scroll`
203
+ * (auto-load), `mode` (auto-load switched between paging and appending), or `state` (`setState()`).
204
+ * @typedef {'page'|'pageSize'|'fit'|'more'|'scroll'|'mode'|'state'} PaginationReason
205
+ */
206
+
207
+ /**
208
+ * @typedef {PaginationState & {reason: PaginationReason, append: boolean}} PaginationChangeDetail
209
+ * `append` is true when the rows `offset … offset + pageSize` go after the ones already shown
210
+ * (Load more, auto-load). Otherwise the slice is shown from scratch: rows
211
+ * `offset … offset + pageSize` when paging, rows `0 … page × pageSize` while appending.
212
+ */
95
213
 
96
214
  /**
97
215
  * The pager for a server-backed list. It owns no data: it reports which slice the user asked for
@@ -113,9 +231,17 @@ export function paginationRange({ page = 1, pages = 1, siblings = 1, boundaries
113
231
  *
114
232
  * In `loadmore` mode each `change` stands for one `binding.loadMore()`, which appends.
115
233
  *
234
+ * Two things adapt the pager to the screen. `pageSize: 'auto'` fits the page to `viewport` — no
235
+ * scrollbar, no empty half page — and follows it as the window, the theme's row height, or a drawer changes
236
+ * its height, keeping the first row of the page on it. `autoLoad` turns paging into continuous
237
+ * scrolling: the next page arrives as the end of the list comes into view. An application loading
238
+ * asynchronously calls `disable()` in its `change` listener and `enable()` once the rows are in;
239
+ * auto-load waits for that, so it never asks for two pages at once.
240
+ *
116
241
  * `page` is clamped into `[1, pages]` after every state change, so shrinking `total` under the
117
242
  * user's feet can never leave the pager pointing past the end of the data.
118
243
  * @fires Pagination#change
244
+ * @fires Pagination#autoload
119
245
  * @extends {Component<PaginationOptions>}
120
246
  */
121
247
  export class Pagination extends Component {
@@ -132,6 +258,15 @@ export class Pagination extends Component {
132
258
  showPageSize: true,
133
259
  showSummary: true,
134
260
  mode: 'pages',
261
+ autoLoad: false,
262
+ showAutoLoad: false,
263
+ viewport: null,
264
+ rowHeight: null,
265
+ perRow: 1,
266
+ reserve: null,
267
+ minPageSize: 5,
268
+ maxPageSize: 200,
269
+ autoLoadMargin: null,
135
270
  disabled: false
136
271
  };
137
272
 
@@ -152,14 +287,33 @@ export class Pagination extends Component {
152
287
  this._createdRoot = this.el === null;
153
288
  this._snapshot = this._createdRoot ? null : snapshotTarget(this.el);
154
289
  this._destroyed = false;
155
- this._pageSize = toSize(this.options.pageSize, 25);
290
+ const choices = Array.isArray(this.options.pageSizes) ? this.options.pageSizes : [];
291
+ this._offerAuto = choices.some(isAuto);
292
+ this._pageSizes = choices.filter((size) => !isAuto(size))
293
+ .map((size) => toSize(size, 0))
294
+ .filter((size) => size > 0);
295
+ this._auto = isAuto(this.options.pageSize);
296
+ // Until the viewport can be measured, an auto pager pages by the first size it offers.
297
+ this._pageSize = this._auto ? this._pageSizes[0] ?? 25 : toSize(this.options.pageSize, 25);
156
298
  this._total = Math.max(0, toCount(this.options.total));
157
299
  this._page = Math.max(1, toCount(this.options.page) || 1);
158
300
  this._disabled = Boolean(this.options.disabled);
301
+ this._autoLoad = Boolean(this.options.autoLoad);
159
302
  this._sizeKey = '';
160
- this._pageSizes = (Array.isArray(this.options.pageSizes) ? this.options.pageSizes : [])
161
- .map((size) => toSize(size, 0))
162
- .filter((size) => size > 0);
303
+ /** @type {{fit: number, load: number}} Pending animation frames, one per kind of check. */
304
+ this._frames = { fit: 0, load: 0 };
305
+ /** @type {number[]} The fitted sizes most recently applied, to stop a resize from oscillating. */
306
+ this._fitTrail = [];
307
+ /** @type {number|null} The viewport's height as the last applied fit left it. */
308
+ this._fitSize = null;
309
+ /** @type {ResizeObserver|null} */
310
+ this._observer = null;
311
+ /** @type {Element|null} The viewport being observed. */
312
+ this._observed = null;
313
+ /** @type {Element|null} The viewport's first child, observed beside it. */
314
+ this._observedContent = null;
315
+ /** @type {Toggle|null} */
316
+ this._switch = null;
163
317
 
164
318
  if (!MODES.has(this.options.mode)) {
165
319
  throw new RangeError(`Unknown pagination mode: ${this.options.mode}`);
@@ -170,22 +324,25 @@ export class Pagination extends Component {
170
324
  this.el = root;
171
325
  if (root.tagName !== 'NAV') root.setAttribute('role', 'navigation');
172
326
  root.setAttribute('aria-label', this._message('pagination.label', 'Pagination'));
173
- root.dataset.mode = this.options.mode;
174
327
 
175
328
  /** @type {Node[]} */
176
329
  const children = [];
177
330
  if (this.options.showSummary) {
178
331
  children.push(h('span', { class: 'zx-pagination__summary', ref: 'summary', ariaLive: 'polite' }));
179
332
  }
180
- // The summary and the page size describe the slice and sit together at the start; the pager
181
- // walks the slice and sits alone at the end, where the next-page action is reached last.
333
+ // The summary, the page size, and the Auto-load switch describe the slice and sit together at
334
+ // the start; the pager walks the slice and sits alone at the end, where the next-page action
335
+ // is reached last.
182
336
  if (this.options.showPageSize) children.push(this._renderPageSize());
337
+ if (this.options.showAutoLoad) children.push(this._renderAutoLoad());
183
338
  children.push(h('span', { class: 'zx-pagination__spacer' }));
184
- children.push(this.options.mode === 'pages' ? this._renderPages() : this._renderLoadMore());
339
+ // Both ends are built once; switching auto-load shows one and hides the other.
340
+ children.push(this._renderPages(), this._renderLoadMore());
185
341
  root.replaceChildren(...children);
186
342
 
187
343
  this._sync();
188
344
  this._wire();
345
+ this._observe();
189
346
  return root;
190
347
  }
191
348
 
@@ -196,7 +353,7 @@ export class Pagination extends Component {
196
353
  * @fires Pagination#change
197
354
  */
198
355
  setPage(page) {
199
- return this.setState({ page });
356
+ return this._apply({ page }, 'page');
200
357
  }
201
358
 
202
359
  /**
@@ -210,42 +367,65 @@ export class Pagination extends Component {
210
367
  }
211
368
 
212
369
  /**
213
- * Replaces the page size and returns to page 1.
214
- * @param {number} pageSize Rows per page.
370
+ * Replaces the page size and returns to page 1. `'auto'` fits it to the viewport.
371
+ * @param {number|'auto'} pageSize Rows per page.
215
372
  * @returns {this}
216
373
  * @fires Pagination#change
217
374
  */
218
375
  setPageSize(pageSize) {
219
- return this.setState({ pageSize, page: 1 });
376
+ return this._apply({ pageSize, page: 1 }, 'pageSize');
220
377
  }
221
378
 
222
379
  /**
223
380
  * Applies any combination of page, page size, and total in one pass, then clamps the page.
224
381
  * `change` fires when the effective page or page size moved — updating only `total` is silent
225
382
  * unless the new count clamps the page.
226
- * @param {Partial<Pick<PaginationState, 'page'|'pageSize'|'total'>>} [state={}] Values to change.
383
+ * @param {{page?: number, pageSize?: number|'auto', total?: number}} [state={}] Values to change.
227
384
  * @param {{silent?: boolean}} [options={}] Set `silent` to suppress the event.
228
385
  * @returns {this}
229
386
  * @fires Pagination#change
230
387
  */
231
388
  setState(state = {}, { silent = false } = {}) {
232
- if (!state || typeof state !== 'object' || Array.isArray(state)) {
233
- throw new TypeError('Pagination state must be an object');
234
- }
235
- const fromPage = this._page;
236
- const fromSize = this._pageSize;
237
- if (Object.hasOwn(state, 'total')) this._total = Math.max(0, toCount(state.total));
238
- if (Object.hasOwn(state, 'pageSize')) this._pageSize = toSize(state.pageSize, this._pageSize);
239
- if (Object.hasOwn(state, 'page')) {
240
- // Any real number is accepted and then clamped; only garbage leaves the page where it was.
241
- const page = Math.trunc(Number(state.page));
242
- if (Number.isFinite(page)) this._page = page;
243
- }
244
- this._page = clamp(this._page, 1, this._pageCount());
389
+ return this._apply(state, 'state', silent);
390
+ }
391
+
392
+ /**
393
+ * Switches auto-load. Where that changes what the pager shows — paging becomes appending, or
394
+ * back — it returns to page 1 and fires `change` with reason `mode`.
395
+ * @param {boolean} autoLoad Whether the next page loads as the end comes into view.
396
+ * @param {{silent?: boolean}} [options={}] Set `silent` to suppress both events.
397
+ * @returns {this}
398
+ * @fires Pagination#autoload
399
+ * @fires Pagination#change
400
+ */
401
+ setAutoLoad(autoLoad, { silent = false } = {}) {
402
+ const next = Boolean(autoLoad);
403
+ if (next === this._autoLoad) return this;
404
+ const before = this._continuous();
405
+ this._autoLoad = next;
406
+ this._switch?.set(next, { silent: true });
407
+ const moved = before !== this._continuous();
408
+ if (moved) this._page = 1;
245
409
  this._sync();
246
- if (!silent && (this._page !== fromPage || this._pageSize !== fromSize)) {
247
- this.emit('change', this.getState());
410
+ if (!silent) {
411
+ this.emit('autoload', { autoLoad: next });
412
+ if (moved) this._emitChange('mode', false);
248
413
  }
414
+ this._schedule('load');
415
+ return this;
416
+ }
417
+
418
+ /**
419
+ * Measures the viewport again — after the host swapped what it shows in it, or replaced it
420
+ * (a `viewport` function is asked again) — and refits an `'auto'` page size. Cheap to call after
421
+ * every redraw: it measures once on the next frame and fires only when the fitted size moved.
422
+ * @returns {this}
423
+ * @fires Pagination#change
424
+ */
425
+ refit() {
426
+ this._observe();
427
+ this._schedule('fit');
428
+ this._schedule('load');
249
429
  return this;
250
430
  }
251
431
 
@@ -260,22 +440,26 @@ export class Pagination extends Component {
260
440
  pageSize: this._pageSize,
261
441
  total: this._total,
262
442
  pages,
263
- offset: (this._page - 1) * this._pageSize
443
+ offset: (this._page - 1) * this._pageSize,
444
+ auto: this._auto,
445
+ autoLoad: this._autoLoad,
446
+ mode: this._continuous() ? 'loadmore' : 'pages'
264
447
  };
265
448
  }
266
449
 
267
450
  /**
268
- * Enables every control.
451
+ * Enables every control, and lets auto-load continue.
269
452
  * @returns {this}
270
453
  */
271
454
  enable() {
272
455
  this._disabled = false;
273
456
  this._sync();
457
+ this._schedule('load');
274
458
  return this;
275
459
  }
276
460
 
277
461
  /**
278
- * Disables every control, for instance while a page is in flight.
462
+ * Disables every control, for instance while a page is in flight. Auto-load waits too.
279
463
  * @returns {this}
280
464
  */
281
465
  disable() {
@@ -291,6 +475,11 @@ export class Pagination extends Component {
291
475
  destroy() {
292
476
  if (this._destroyed) return;
293
477
  this._destroyed = true;
478
+ for (const kind of /** @type {Array<'fit'|'load'>} */ (['fit', 'load'])) {
479
+ if (this._frames[kind]) cancelFrame(this._frames[kind]);
480
+ }
481
+ this._observer?.disconnect();
482
+ this._switch?.destroy();
294
483
  const root = this.el;
295
484
  super.destroy();
296
485
  if (!this._createdRoot && root) restoreTarget(root, this._snapshot);
@@ -303,6 +492,67 @@ export class Pagination extends Component {
303
492
  return this._total <= 0 ? 1 : Math.ceil(this._total / this._pageSize);
304
493
  }
305
494
 
495
+ /** @returns {boolean} Whether pages append — Load more, or auto-load — rather than replace. */
496
+ _continuous() {
497
+ return this._autoLoad || this.options.mode === 'loadmore';
498
+ }
499
+
500
+ /**
501
+ * The one place state changes: applies, clamps, redraws, and reports.
502
+ * @param {{page?: number, pageSize?: number|'auto', total?: number}} state Values to change.
503
+ * @param {PaginationReason} reason Why, for the event.
504
+ * @param {boolean} [silent=false] Suppresses the event.
505
+ * @returns {this}
506
+ */
507
+ _apply(state, reason, silent = false) {
508
+ if (!state || typeof state !== 'object' || Array.isArray(state)) {
509
+ throw new TypeError('Pagination state must be an object');
510
+ }
511
+ const fromPage = this._page;
512
+ const fromSize = this._pageSize;
513
+ const fromAuto = this._auto;
514
+ if (Object.hasOwn(state, 'total')) this._total = Math.max(0, toCount(state.total));
515
+ if (Object.hasOwn(state, 'pageSize')) {
516
+ if (isAuto(state.pageSize)) {
517
+ if (!this._auto) {
518
+ this._auto = true;
519
+ this._fitTrail = [];
520
+ this._fitSize = null;
521
+ this._pageSize = this._measure() || this._pageSize;
522
+ }
523
+ } else {
524
+ const size = toSize(state.pageSize, 0);
525
+ if (size > 0) {
526
+ this._auto = false;
527
+ this._pageSize = size;
528
+ }
529
+ }
530
+ }
531
+ if (Object.hasOwn(state, 'page')) {
532
+ // Any real number is accepted and then clamped; only garbage leaves the page where it was.
533
+ const page = Math.trunc(Number(state.page));
534
+ if (Number.isFinite(page)) this._page = page;
535
+ }
536
+ this._page = clamp(this._page, 1, this._pageCount());
537
+ this._sync();
538
+ if (!silent && (this._page !== fromPage || this._pageSize !== fromSize || this._auto !== fromAuto)) {
539
+ this._emitChange(reason, (reason === 'more' || reason === 'scroll') && this._page === fromPage + 1);
540
+ }
541
+ // The viewport may not be full yet — a short page, a total that grew — so look again.
542
+ if (this._auto && !fromAuto) this._schedule('fit');
543
+ this._schedule('load');
544
+ return this;
545
+ }
546
+
547
+ /**
548
+ * @param {PaginationReason} reason
549
+ * @param {boolean} append
550
+ * @returns {void}
551
+ */
552
+ _emitChange(reason, append) {
553
+ this.emit('change', { ...this.getState(), reason, append });
554
+ }
555
+
306
556
  /** @returns {HTMLElement} The page-size select and its visible label. */
307
557
  _renderPageSize() {
308
558
  const label = this._message('pagination.pageSize', 'Rows per page');
@@ -315,9 +565,19 @@ export class Pagination extends Component {
315
565
  }));
316
566
  }
317
567
 
568
+ /** @returns {HTMLElement} The Auto-load switch. */
569
+ _renderAutoLoad() {
570
+ this._switch = new Toggle(null, {
571
+ label: this._message('pagination.autoLoad', 'Auto-load'),
572
+ checked: this._autoLoad,
573
+ onchange: ({ detail }) => this.setAutoLoad(detail.checked)
574
+ });
575
+ return h('span', { class: 'zx-pagination__autoload' }, this._switch.toElement());
576
+ }
577
+
318
578
  /** @returns {HTMLElement} Previous / page buttons / next. */
319
579
  _renderPages() {
320
- return h('div', { class: 'zx-pagination__controls' },
580
+ return h('div', { class: 'zx-pagination__controls', ref: 'controls' },
321
581
  this._navButton('prev', 'chevron-left', this._message('pagination.previous', 'Previous page')),
322
582
  h('div', { class: 'zx-pagination__pages', ref: 'pages' }),
323
583
  this._navButton('next', 'chevron-right', this._message('pagination.next', 'Next page')));
@@ -339,7 +599,7 @@ export class Pagination extends Component {
339
599
  }, icon(glyph, { size: ICON_SIZE.chevron }));
340
600
  }
341
601
 
342
- /** @returns {HTMLElement} The append-style trigger. */
602
+ /** @returns {HTMLElement} The append-style trigger; under auto-load, the keyboard's way on. */
343
603
  _renderLoadMore() {
344
604
  return h('button', {
345
605
  class: 'zx-btn zx-pagination__more',
@@ -353,35 +613,53 @@ export class Pagination extends Component {
353
613
  _wire() {
354
614
  if (this.refs.select) {
355
615
  this.listen(this.refs.select, 'change', () => {
356
- this.setPageSize(Number(/** @type {HTMLSelectElement} */ (this.refs.select).value));
616
+ const value = /** @type {HTMLSelectElement} */ (this.refs.select).value;
617
+ this.setPageSize(isAuto(value) ? AUTO : Number(value));
357
618
  });
358
619
  }
359
- if (this.options.mode === 'pages') {
360
- this.listen(this.refs.prev, 'click', () => this.setPage(this._page - 1));
361
- this.listen(this.refs.next, 'click', () => this.setPage(this._page + 1));
362
- this.listen(this.refs.pages, 'click', (event) => {
363
- const control = /** @type {Element} */ (event.target).closest?.('[data-page]');
364
- if (!control || !this.refs.pages.contains(control)) return;
365
- this.setPage(Number(/** @type {HTMLElement} */ (control).dataset.page));
366
- });
367
- return;
620
+ this.listen(this.refs.prev, 'click', () => this.setPage(this._page - 1));
621
+ this.listen(this.refs.next, 'click', () => this.setPage(this._page + 1));
622
+ this.listen(this.refs.pages, 'click', (event) => {
623
+ const control = /** @type {Element} */ (event.target).closest?.('[data-page]');
624
+ if (!control || !this.refs.pages.contains(control)) return;
625
+ this.setPage(Number(/** @type {HTMLElement} */ (control).dataset.page));
626
+ });
627
+ this.listen(this.refs.more, 'click', () => this._apply({ page: this._page + 1 }, 'more'));
628
+ // Scrolling anywhere may bring the end of the list near; the check itself is one per frame.
629
+ const doc = this.el.ownerDocument;
630
+ const view = doc?.defaultView;
631
+ if (doc) {
632
+ this.listen(doc, 'scroll', () => {
633
+ if (this._autoLoad) this._schedule('load');
634
+ }, { capture: true, passive: true });
635
+ }
636
+ if (view) {
637
+ this.listen(view, 'resize', () => {
638
+ if (this._autoLoad) this._schedule('load');
639
+ }, { passive: true });
368
640
  }
369
- this.listen(this.refs.more, 'click', () => this.setPage(this._page + 1));
370
641
  }
371
642
 
372
643
  /** Pushes the current state onto every control. @returns {void} */
373
644
  _sync() {
374
645
  const pages = this._pageCount();
646
+ const continuous = this._continuous();
647
+ this.el.dataset.mode = continuous ? 'loadmore' : 'pages';
648
+ this.el.dataset.autoload = this._autoLoad ? 'true' : 'false';
375
649
  this.el.dataset.disabled = this._disabled ? 'true' : 'false';
376
650
  if (this.refs.summary) this.refs.summary.textContent = this._summary();
377
651
  if (this.refs.select) this._syncPageSize();
378
- if (this.options.mode === 'pages') {
379
- /** @type {HTMLButtonElement} */ (this.refs.prev).disabled = this._disabled || this._page <= 1;
380
- /** @type {HTMLButtonElement} */ (this.refs.next).disabled = this._disabled || this._page >= pages;
381
- this._syncPages(pages);
382
- return;
652
+ if (this._switch) {
653
+ if (this._disabled) this._switch.disable();
654
+ else this._switch.enable();
383
655
  }
656
+ /** @type {HTMLElement} */ (this.refs.controls).hidden = continuous;
657
+ /** @type {HTMLElement} */ (this.refs.more).hidden = !continuous;
384
658
  /** @type {HTMLButtonElement} */ (this.refs.more).disabled = this._disabled || this._page >= pages;
659
+ if (continuous) return;
660
+ /** @type {HTMLButtonElement} */ (this.refs.prev).disabled = this._disabled || this._page <= 1;
661
+ /** @type {HTMLButtonElement} */ (this.refs.next).disabled = this._disabled || this._page >= pages;
662
+ this._syncPages(pages);
385
663
  }
386
664
 
387
665
  /**
@@ -392,7 +670,7 @@ export class Pagination extends Component {
392
670
  const offset = (this._page - 1) * this._pageSize;
393
671
  const to = Math.min(offset + this._pageSize, this._total);
394
672
  // Appending lists have shown everything up to `to`, not just the newest page.
395
- if (this.options.mode === 'loadmore') {
673
+ if (this._continuous()) {
396
674
  return this._message('pagination.loaded', '%1 of %2', count(to), count(this._total));
397
675
  }
398
676
  return this._message('pagination.summary', '%1–%2 of %3',
@@ -402,13 +680,21 @@ export class Pagination extends Component {
402
680
  /** Rebuilds the page-size options only when the choice set actually changed. @returns {void} */
403
681
  _syncPageSize() {
404
682
  const select = /** @type {HTMLSelectElement} */ (this.refs.select);
405
- const sizes = [...new Set([...this._pageSizes, this._pageSize])].sort((left, right) => left - right);
406
- const key = sizes.join(',');
683
+ const sizes = [...new Set(this._auto ? this._pageSizes : [...this._pageSizes, this._pageSize])]
684
+ .sort((left, right) => left - right);
685
+ const auto = this._offerAuto || this._auto
686
+ ? this._auto
687
+ ? this._message('pagination.autoSize', 'Auto (%1)', count(this._pageSize))
688
+ : this._message('pagination.auto', 'Auto')
689
+ : null;
690
+ const key = `${auto ?? ''}|${sizes.join(',')}`;
407
691
  if (key !== this._sizeKey) {
408
692
  this._sizeKey = key;
409
- select.replaceChildren(...sizes.map((size) => h('option', { value: String(size) }, String(size))));
693
+ select.replaceChildren(
694
+ ...(auto === null ? [] : [h('option', { value: AUTO }, auto)]),
695
+ ...sizes.map((size) => h('option', { value: String(size) }, String(size))));
410
696
  }
411
- select.value = String(this._pageSize);
697
+ select.value = this._auto ? AUTO : String(this._pageSize);
412
698
  select.disabled = this._disabled;
413
699
  }
414
700
 
@@ -448,6 +734,154 @@ export class Pagination extends Component {
448
734
  if (restored && !restored.disabled) restored.focus();
449
735
  }
450
736
 
737
+ /* -------------------------------------------------------- fitting and loading -- */
738
+
739
+ /** @returns {Element|null} The viewport option, resolved now. */
740
+ _viewport() {
741
+ const option = this.options.viewport;
742
+ const value = typeof option === 'function' ? option() : option;
743
+ if (typeof value === 'string') return this.el.ownerDocument?.querySelector(value) ?? null;
744
+ return value && typeof value === 'object' && /** @type {Node} */ (value).nodeType === 1
745
+ ? /** @type {Element} */ (value) : null;
746
+ }
747
+
748
+ /**
749
+ * Observes the current viewport and what it holds, letting go of previous ones. The viewport's
750
+ * size is the space; its content's size changes when the rows themselves do — a table stacking
751
+ * into cards on a narrow screen, a new row height, a font arriving.
752
+ * @returns {void}
753
+ */
754
+ _observe() {
755
+ const viewport = this._viewport();
756
+ const content = viewport?.firstElementChild ?? null;
757
+ if (viewport === this._observed && content === this._observedContent) return;
758
+ this._observer?.disconnect();
759
+ this._observed = viewport;
760
+ this._observedContent = content;
761
+ if (!viewport || typeof ResizeObserver !== 'function') return;
762
+ this._observer ??= new ResizeObserver(() => {
763
+ this._schedule('fit');
764
+ this._schedule('load');
765
+ });
766
+ this._observer.observe(viewport);
767
+ if (content) this._observer.observe(content);
768
+ }
769
+
770
+ /**
771
+ * Runs a fit or an auto-load check on the next frame, once however often it is asked for — a
772
+ * resize or a scroll asks many times a frame, and measuring inside a ResizeObserver callback
773
+ * that changes the rows would loop.
774
+ * @param {'fit'|'load'} kind
775
+ * @returns {void}
776
+ */
777
+ _schedule(kind) {
778
+ if (this._destroyed || this._frames[kind]) return;
779
+ if (kind === 'fit' ? !this._auto : !this._autoLoad) return;
780
+ this._frames[kind] = nextFrame(() => {
781
+ this._frames[kind] = 0;
782
+ if (this._destroyed) return;
783
+ if (kind === 'fit') this._fit();
784
+ else this._checkAutoLoad();
785
+ });
786
+ }
787
+
788
+ /**
789
+ * Measures the viewport and, when the fitted size moved, keeps the page's first row on the new
790
+ * page. Appending pagers fit only their first batch: later batches keep its size, so the rows
791
+ * loaded so far always number `page × pageSize`.
792
+ * @returns {void}
793
+ */
794
+ _fit() {
795
+ if (!this._auto || (this._continuous() && this._page > 1)) return;
796
+ const size = this._measure();
797
+ if (!size) return;
798
+ // A resize feeding on itself is told from a real one by the viewport's own size: see
799
+ // pageFitStep(). The size is read again once the fit is applied and reported, so a footer
800
+ // that wrapped because of it counts as the fit's doing, not as a resize.
801
+ const step = pageFitStep({
802
+ size,
803
+ current: this._pageSize,
804
+ trail: this._fitTrail,
805
+ viewport: this._viewportSize(),
806
+ settled: this._fitSize
807
+ });
808
+ this._fitTrail = step.trail;
809
+ if (!step.apply) return;
810
+ const offset = (this._page - 1) * this._pageSize;
811
+ this._pageSize = size;
812
+ this._page = clamp(Math.floor(offset / size) + 1, 1, this._pageCount());
813
+ this._sync();
814
+ this._emitChange('fit', false);
815
+ if (this._destroyed) return;
816
+ this._fitSize = this._viewportSize();
817
+ this._schedule('load');
818
+ }
819
+
820
+ /** @returns {string} The viewport's width and height now, as one key; '' when there is none. */
821
+ _viewportSize() {
822
+ const viewport = this._viewport();
823
+ return viewport?.isConnected ? `${viewport.clientWidth}x${viewport.clientHeight}` : '';
824
+ }
825
+
826
+ /**
827
+ * How many items fit the viewport now, or 0 when it cannot be measured (absent, hidden).
828
+ * @returns {number}
829
+ */
830
+ _measure() {
831
+ const viewport = this._viewport();
832
+ if (!viewport || !viewport.isConnected) return 0;
833
+ const view = viewport.ownerDocument.defaultView;
834
+ const style = view?.getComputedStyle(viewport);
835
+ const padding = style
836
+ ? (Number.parseFloat(style.paddingBlockStart) || 0) + (Number.parseFloat(style.paddingBlockEnd) || 0)
837
+ : 0;
838
+ /**
839
+ * @param {PaginationMeasure|undefined} option
840
+ * @param {() => number} fallback
841
+ * @returns {number}
842
+ */
843
+ const read = (option, fallback) => {
844
+ const value = typeof option === 'function' ? option(viewport) : option;
845
+ const number = Number(value);
846
+ return value == null || !Number.isFinite(number) ? fallback() : number;
847
+ };
848
+ return fitPageSize({
849
+ available: viewport.clientHeight - padding,
850
+ reserve: read(this.options.reserve, () => headerHeight(viewport)),
851
+ rowHeight: read(this.options.rowHeight, () => rowHeightIn(viewport)),
852
+ perRow: read(this.options.perRow, () => 1),
853
+ min: this.options.minPageSize,
854
+ max: this.options.maxPageSize
855
+ });
856
+ }
857
+
858
+ /** Loads the next page when auto-load is on, idle, and the end of the list is near. @returns {void} */
859
+ _checkAutoLoad() {
860
+ if (!this._autoLoad || this._disabled || this._page >= this._pageCount()) return;
861
+ const root = /** @type {HTMLElement} */ (this.el);
862
+ if (!root.isConnected || (typeof root.checkVisibility === 'function' && !root.checkVisibility())) return;
863
+ if (!this._nearEnd()) return;
864
+ this._apply({ page: this._page + 1 }, 'scroll');
865
+ }
866
+
867
+ /** @returns {boolean} Whether the end of the list is within the auto-load margin. */
868
+ _nearEnd() {
869
+ const option = this.options.autoLoadMargin;
870
+ /** @param {number} height @returns {number} */
871
+ const margin = (height) => (typeof option === 'number' && option >= 0 ? option : height / 2);
872
+ const viewport = this._viewport();
873
+ if (viewport) {
874
+ if (viewport.clientHeight <= 0) return false;
875
+ return viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight <= margin(viewport.clientHeight);
876
+ }
877
+ const scroller = scrollParent(this.el);
878
+ const view = this.el.ownerDocument?.defaultView;
879
+ const bounds = scroller ? scroller.getBoundingClientRect() : { top: 0, bottom: view?.innerHeight ?? 0 };
880
+ const height = bounds.bottom - bounds.top;
881
+ if (height <= 0) return false;
882
+ return this.el.getBoundingClientRect().top <= bounds.bottom + margin(height);
883
+ }
884
+
451
885
  /**
452
886
  * Resolves a message through the host translator, falling back to the built-in English text.
453
887
  * @param {string} key Message key.
@@ -462,12 +896,69 @@ export class Pagination extends Component {
462
896
  }
463
897
 
464
898
  /**
465
- * Fired whenever the user picks a different slice — a page number, previous/next, a new page size
466
- * (which returns to page 1), or Load more.
899
+ * Fired whenever the slice changes — a page number, previous/next, a new page size (which returns
900
+ * to page 1), Load more, auto-load, a fitted size that followed the viewport, or auto-load switching
901
+ * between paging and appending. `detail.reason` says which.
467
902
  * @event Pagination#change
468
903
  * @type {CustomEvent<PaginationChangeDetail>}
469
904
  */
470
905
 
906
+ /**
907
+ * Fired when auto-load is switched on or off — by the switch or `setAutoLoad()` — before any
908
+ * `change` that follows from it; the moment to remember the reader's preference.
909
+ * @event Pagination#autoload
910
+ * @type {CustomEvent<{autoLoad: boolean}>}
911
+ */
912
+
913
+ /** @param {unknown} value @returns {boolean} Whether a page-size value asks for the fitted size. */
914
+ function isAuto(value) {
915
+ return typeof value === 'string' && value.trim().toLowerCase() === AUTO;
916
+ }
917
+
918
+ /**
919
+ * Height of the header that sticks above a table's rows inside the viewport.
920
+ * @param {Element} viewport
921
+ * @returns {number}
922
+ */
923
+ function headerHeight(viewport) {
924
+ const head = viewport.querySelector('thead');
925
+ return head ? head.getBoundingClientRect().height : 0;
926
+ }
927
+
928
+ /**
929
+ * One row's height: a Zx Table's first body row when there is one — the rows as drawn, stacked
930
+ * on a narrow screen or not — else the theme's `--zx-row-height`, read through a probe.
931
+ * @param {Element} viewport
932
+ * @returns {number}
933
+ */
934
+ function rowHeightIn(viewport) {
935
+ const row = viewport.querySelector('tbody > tr[data-row]');
936
+ const height = row ? row.getBoundingClientRect().height : 0;
937
+ if (height > 0) return height;
938
+ const probe = h('div', {
939
+ ariaHidden: 'true',
940
+ style: { position: 'absolute', visibility: 'hidden', inlineSize: '0', blockSize: 'var(--zx-row-height)' }
941
+ });
942
+ viewport.append(probe);
943
+ const probed = probe.getBoundingClientRect().height;
944
+ probe.remove();
945
+ return probed;
946
+ }
947
+
948
+ /**
949
+ * The nearest ancestor that scrolls vertically, or null for the window.
950
+ * @param {Element} element
951
+ * @returns {Element|null}
952
+ */
953
+ function scrollParent(element) {
954
+ const view = element.ownerDocument?.defaultView;
955
+ for (let node = element.parentElement; node && node !== element.ownerDocument.body; node = node.parentElement) {
956
+ const overflow = view?.getComputedStyle(node).overflowY ?? '';
957
+ if (/(auto|scroll|overlay)/.test(overflow)) return node;
958
+ }
959
+ return null;
960
+ }
961
+
471
962
  /** @param {unknown} value @returns {number} A non-negative integer, or 0. */
472
963
  function toCount(value) {
473
964
  const number = Math.trunc(Number(value));
@@ -480,11 +971,6 @@ function toSize(value, fallback) {
480
971
  return Number.isFinite(number) && number > 0 ? number : fallback;
481
972
  }
482
973
 
483
- /** @param {number} value @param {number} min @param {number} max @returns {number} */
484
- function clamp(value, min, max) {
485
- return Math.min(Math.max(value, min), max);
486
- }
487
-
488
974
  /** @param {number} start @param {number} end @returns {number[]} Inclusive range, empty when reversed. */
489
975
  function numberRange(start, end) {
490
976
  if (end < start) return [];