@zeyos/zx 5.8.0 → 5.9.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 (109) hide show
  1. package/CHANGELOG.md +93 -0
  2. package/dist/types/components/block-view/block-view.d.ts +3 -2
  3. package/dist/types/components/check-button/check-button.d.ts +10 -2
  4. package/dist/types/components/checklist/checklist.d.ts +28 -6
  5. package/dist/types/components/code-editor/code-editor.d.ts +19 -1
  6. package/dist/types/components/dock/dock.d.ts +2 -1
  7. package/dist/types/components/dropdown/dropdown.d.ts +2 -1
  8. package/dist/types/components/field-upload/field-upload.d.ts +6 -0
  9. package/dist/types/components/filter-panel/filter-panel.d.ts +6 -2
  10. package/dist/types/components/module-bar/module-bar.d.ts +53 -2
  11. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +28 -0
  12. package/dist/types/components/run-status/run-status.d.ts +1 -1
  13. package/dist/types/components/run-trace/run-trace.d.ts +8 -0
  14. package/dist/types/components/select/select.d.ts +18 -5
  15. package/dist/types/components/tabbox/tabbox.d.ts +7 -0
  16. package/dist/types/components/tag-picker/tag-picker.d.ts +21 -5
  17. package/dist/types/components/timebox/timebox.d.ts +9 -0
  18. package/dist/types/core/component.d.ts +4 -1
  19. package/dist/types/internal/focus-stops.d.ts +42 -0
  20. package/dist/zx-zeyos.esm.js +296 -97
  21. package/dist/zx-zeyos.esm.min.js +4 -4
  22. package/dist/zx.core.css +13 -6
  23. package/dist/zx.core.min.css +1 -1
  24. package/dist/zx.css +26 -88
  25. package/dist/zx.esm.js +516 -159
  26. package/dist/zx.esm.min.js +26 -26
  27. package/dist/zx.global.js +516 -159
  28. package/dist/zx.global.min.js +26 -26
  29. package/dist/zx.layered.css +26 -88
  30. package/dist/zx.layered.min.css +1 -1
  31. package/dist/zx.min.css +1 -1
  32. package/docs/api.json +97 -9
  33. package/docs/components/approval-card.md +2 -2
  34. package/docs/components/block-view.md +2 -1
  35. package/docs/components/check-button.md +3 -1
  36. package/docs/components/checklist.md +2 -1
  37. package/docs/components/code-editor.md +4 -3
  38. package/docs/components/composer.md +4 -0
  39. package/docs/components/dock.md +4 -1
  40. package/docs/components/dropdown.md +3 -1
  41. package/docs/components/field-upload.md +2 -1
  42. package/docs/components/modal.md +3 -0
  43. package/docs/components/multi-value-editor.md +5 -2
  44. package/docs/components/navigation-bar.md +5 -0
  45. package/docs/components/questionnaire.md +2 -2
  46. package/docs/components/run-status.md +2 -1
  47. package/docs/components/run-trace.md +2 -1
  48. package/docs/components/select.md +6 -2
  49. package/docs/components/tabbox.md +6 -0
  50. package/docs/components/tag-picker.md +3 -1
  51. package/docs/components/timebox.md +2 -1
  52. package/docs/components/tokens.md +20 -0
  53. package/docs/llms.md +84 -21
  54. package/package.json +1 -1
  55. package/src/components/app-sidebar/app-sidebar.js +1 -1
  56. package/src/components/approval-card/approval-card.css +0 -5
  57. package/src/components/approval-card/approval-card.js +2 -0
  58. package/src/components/block-view/block-view.css +0 -10
  59. package/src/components/block-view/block-view.js +11 -6
  60. package/src/components/card/card.css +3 -0
  61. package/src/components/card/card.js +2 -2
  62. package/src/components/card-view/card-view.css +5 -5
  63. package/src/components/card-view/card-view.js +3 -1
  64. package/src/components/check-button/check-button.js +5 -1
  65. package/src/components/checklist/checklist.js +26 -10
  66. package/src/components/checklist/field-adapter.js +5 -13
  67. package/src/components/code-editor/code-editor.js +24 -3
  68. package/src/components/composer/composer.css +15 -26
  69. package/src/components/copy/copy-input.css +3 -1
  70. package/src/components/dialog/dialog.js +2 -1
  71. package/src/components/dock/dock.css +0 -6
  72. package/src/components/dock/dock.js +22 -7
  73. package/src/components/dropdown/dropdown.js +17 -2
  74. package/src/components/field/field.js +2 -1
  75. package/src/components/field-upload/field-upload.js +15 -0
  76. package/src/components/filter-panel/filter-panel.js +8 -11
  77. package/src/components/master-panel/master-panel.js +3 -1
  78. package/src/components/modal/modal.css +2 -11
  79. package/src/components/modal/modal.js +5 -2
  80. package/src/components/module-bar/module-bar.js +110 -26
  81. package/src/components/multi-value-editor/field-adapter.js +8 -23
  82. package/src/components/multi-value-editor/multi-value-editor.js +63 -5
  83. package/src/components/navigation-bar/navigation-bar.css +0 -4
  84. package/src/components/navigation-bar/navigation-bar.js +11 -2
  85. package/src/components/questionnaire/questionnaire.css +0 -14
  86. package/src/components/questionnaire/questionnaire.js +4 -2
  87. package/src/components/run-status/run-status.css +0 -7
  88. package/src/components/run-status/run-status.js +3 -1
  89. package/src/components/run-trace/run-trace.css +0 -5
  90. package/src/components/run-trace/run-trace.js +23 -2
  91. package/src/components/select/select.js +43 -5
  92. package/src/components/skeleton/skeleton.js +16 -3
  93. package/src/components/surface/surface.css +0 -6
  94. package/src/components/surface/surface.js +1 -1
  95. package/src/components/tabbox/tabbox.css +0 -6
  96. package/src/components/tabbox/tabbox.js +20 -2
  97. package/src/components/table/table.js +5 -0
  98. package/src/components/tag-picker/tag-picker.js +35 -6
  99. package/src/components/timebox/timebox.js +17 -1
  100. package/src/components/view-settings/view-settings.js +1 -1
  101. package/src/core/component.js +22 -2
  102. package/src/core/date.js +1 -4
  103. package/src/core/drag-axis.js +22 -6
  104. package/src/internal/focus-stops.js +108 -0
  105. package/src/zeyos/connect.js +7 -3
  106. package/src/zeyos/icons.js +7 -2
  107. package/styles/base.css +27 -3
  108. package/styles/tokens/dark.css +2 -2
  109. package/styles/tokens/semantic.css +2 -2
package/CHANGELOG.md CHANGED
@@ -8,6 +8,99 @@ and friends remain the complete record.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 5.9.0 — 2026-11-21
12
+
13
+ Focus rings that mark only the control you operate, tab panels that follow the APG tab sequence, a
14
+ Composer that rings its text field, and a ModuleBar that shows every pinned module that fits.
15
+
16
+ ### Added
17
+
18
+ - **`data-zx-focus` marks a focus target that is not a control.** `"container"` — focused only by a
19
+ script, with `tabindex="-1"` — draws no focus ring, in forced colours either; `"region"` — a Tab
20
+ stop such as a keyboard scroll region — draws the ring inside its edge, as an outline the
21
+ region's content cannot cover. Put it on an application's own view
22
+ roots, headings a route change focuses, and scroll regions.
23
+
24
+ ### Changed
25
+
26
+ - **The focus ring marks controls only.** Chrome shows keyboard focus on any focused element after
27
+ any key press, even Shift, so a click into a panel followed by a keystroke ringed the panel like a
28
+ field. The Modal, Dialog and Sheet panel, a Dropdown panel only a script focuses, the ApprovalCard
29
+ and RunStatus roots, Questionnaire's question and review, Surface's verdict and an emptied Table
30
+ or CardView body no longer draw one. Modal no longer rings its panel when it holds focus itself: it keeps its glass
31
+ elevation instead of an accent outline. Tab panels, code blocks, a Dropdown panel the application
32
+ puts in the Tab order, and the scroll regions of Table, Dock and MasterPanel draw the ring inside
33
+ their edge.
34
+ - **Tab panels are Tab stops only when nothing inside them is.** Tabbox, NavigationBar and Dock
35
+ panels follow the APG tabs pattern: a panel holding a control is no Tab stop of its own, so Tab
36
+ reaches the control, and a panel of plain text stays reachable to read and scroll. BlockView and RunTrace
37
+ code blocks are Tab stops only while their text scrolls.
38
+ - **The Composer rings its text, not its box.** Typing used to ring the whole box, chips, tools and
39
+ Send included. The text is now a field inside the box, with the control edge and fill, lined up
40
+ with the chips above it and the tools below, and it alone draws the focus ring while it is typed
41
+ into. The box stays a tray on the chrome tone; the tools and Send ring only when they hold the
42
+ focus themselves.
43
+
44
+ ### Fixed
45
+
46
+ - **A linked Card draws one focus ring.** Its primary link no longer adds a second ring inside the
47
+ card's own.
48
+ - **CopyInput's box rings only for its field.** With focus on the Copy button, the box rang around
49
+ the button's own ring; the button now rings alone.
50
+ - **ModuleBar shows every pinned module that fits.** With names beside the tiles — AppSidebar's
51
+ `layout: 'modules'`, expanded — pinned modules moved behind "All modules" while a third of the bar
52
+ stood empty. Unpinned modules and their section headings were measured although only the
53
+ catalogue offers them, a heading counted even when none of its modules stayed on the bar, and one
54
+ name wrapping to two lines charged every row its height. Each row now takes its own height, and a
55
+ heading only takes room above a module that is shown; no row is cut off.
56
+
57
+ ## 5.8.1 — 2026-11-17
58
+
59
+ Placeholder text that meets 4.5:1, the same small API on sibling inputs, cancellable async
60
+ filters, and fixes for drags, Timebox changes and a few defaults.
61
+
62
+ ### Added
63
+
64
+ - **`Component#listen(element, type, fn, {signal})`** takes a shorter-lived signal: the listener
65
+ goes when that signal aborts or the component is destroyed, whichever comes first — for a
66
+ listener that belongs to one rendering of a part.
67
+ - **Async filters get a signal.** An async `filter` on Select and TagPicker is called with
68
+ `(query, { signal })`; the signal aborts when a newer query starts, the list closes, or the
69
+ control is destroyed (and on `TagPicker#setItems()`), so passing it to `fetch()` cancels requests
70
+ nobody waits for.
71
+ - **The same small API on sibling inputs.** `Timebox#focus()`; CodeEditor's `readonly` option and
72
+ `setReadonly()`, the spelling every other control uses (`readOnly` and `setReadOnly()` keep
73
+ working, and either set to true makes it read-only); MultiValueEditor's `disabled` option with
74
+ `setDisabled()`, `disable()`, `enable()` and `isDisabled()`, which the `multivalueeditor` field
75
+ type now uses; FieldUpload's `disable()`, `enable()` and `isDisabled()`; and `{ silent }` on
76
+ Checklist's `setValues()`, `checkAll()` and `uncheckAll()`.
77
+
78
+ ### Changed
79
+
80
+ - **Placeholder text meets 4.5:1 contrast.** `--zx-color-text-placeholder` is darker in light mode
81
+ (a mix of gray-500 and gray-600, still lighter than muted text) and lighter in dark mode
82
+ (gray-400, the colour of muted text there), so an empty field's hint is readable on every
83
+ surface.
84
+
85
+ - **Timebox reports a change only when the value changed.** Enter followed by leaving the field
86
+ reported the same edit twice, and Enter without an edit reported one.
87
+
88
+ ### Fixed
89
+
90
+ - A click on a `multivalueeditor` field's label focuses its first value instead of the drag
91
+ handle. Setting a `checklist` field's value from code no longer lets the inner Checklist
92
+ announce a `change` of its own.
93
+ - A drag on a SplitView, Dock or resizable Sheet handle whose pointer could not be captured ends
94
+ when the pointer is released off the handle; it used to stay open and refuse every later press.
95
+ - `skeleton()`, `skeletonText()` and `skeletonTable()` keep their defaults when an option is passed
96
+ as `undefined`, so a forwarded unset height no longer draws an invisible block.
97
+ - ZeyOS: `zeyosAppIcon()` keeps its circle when `shape` is passed as `undefined`;
98
+ `useZeyosIcons({ kit: undefined })` loads the ZeyOS kit instead of rejecting; a failed request
99
+ whose error has an empty message, or none, is reported with the generic message instead of an
100
+ empty notification or "[object Object]".
101
+ - The CheckButton reference explains why a single label reads better than an
102
+ `[onLabel, offLabel]` pair.
103
+
11
104
  ## 5.8.0 — 2026-11-17
12
105
 
13
106
  Pinned columns and header groups in Table, placements, stacks and highlights for messages, a Chart
@@ -171,8 +171,9 @@ export declare class BlockView extends Component<BlockViewOptions> {
171
171
  /** @private @returns {void} */
172
172
  private _syncState;
173
173
  /**
174
- * A wide table scrolls inside the answer; while it does, its wrapper is a named, focusable
175
- * region so the keyboard can scroll it too. A table that fits is not a tab stop.
174
+ * A wide table or a long code line scrolls inside the answer; while it does, its scroller is a
175
+ * Tab stop so the keyboard can scroll it too — a table's wrapper a named region. One that fits
176
+ * is not a Tab stop.
176
177
  * @private
177
178
  * @returns {void}
178
179
  */
@@ -1,7 +1,11 @@
1
1
  import { Component } from '../../core/component.js';
2
2
  export type CheckButtonOptions = {
3
3
  /**
4
- * A shared label or `[onLabel, offLabel]`.
4
+ * A shared label or `[onLabel, offLabel]`. Prefer one
5
+ * label: the button is announced as pressed or not, and the APG toggle-button pattern advises
6
+ * against a name that changes with the state, which a screen reader then reads twice over
7
+ * ("Disabled, toggle button, not pressed"). A pair suits a visible state word only where that
8
+ * repetition is acceptable; for an on/off setting a Toggle reads better.
5
9
  */
6
10
  label?: string | [string, string];
7
11
  /**
@@ -25,7 +29,11 @@ export type CheckButtonOptions = {
25
29
  };
26
30
  /**
27
31
  * @typedef {Object} CheckButtonOptions
28
- * @property {string|[string, string]} [label=''] A shared label or `[onLabel, offLabel]`.
32
+ * @property {string|[string, string]} [label=''] A shared label or `[onLabel, offLabel]`. Prefer one
33
+ * label: the button is announced as pressed or not, and the APG toggle-button pattern advises
34
+ * against a name that changes with the state, which a screen reader then reads twice over
35
+ * ("Disabled, toggle button, not pressed"). A pair suits a visible state word only where that
36
+ * repetition is acceptable; for an on/off setting a Toggle reads better.
29
37
  * @property {boolean} [checked=false] Initial pressed state.
30
38
  * @property {boolean} [icon=true] Whether to show the check indicator.
31
39
  * @property {boolean} [disabled=false] Initial disabled state.
@@ -64,6 +64,12 @@ export type ChecklistOptions = {
64
64
  export type ChecklistChangeDetail = {
65
65
  values: unknown[];
66
66
  };
67
+ export type ChecklistSetOptions = {
68
+ /**
69
+ * Update the checked state without emitting `change`.
70
+ */
71
+ silent?: boolean;
72
+ };
67
73
  export type ChecklistLoadedDetail = {
68
74
  items: ChecklistItem[];
69
75
  };
@@ -89,6 +95,10 @@ export type ChecklistLoadedDetail = {
89
95
  * @property {(event: CustomEvent<ChecklistLoadedDetail>) => void} [onloaded] Loaded listener.
90
96
  */
91
97
  /** @typedef {{values: unknown[]}} ChecklistChangeDetail */
98
+ /**
99
+ * @typedef {Object} ChecklistSetOptions
100
+ * @property {boolean} [silent=false] Update the checked state without emitting `change`.
101
+ */
92
102
  /** @typedef {{items: ChecklistItem[]}} ChecklistLoadedDetail */
93
103
  /**
94
104
  * Searchable native-checkbox group.
@@ -145,14 +155,25 @@ export declare class Checklist extends Component<ChecklistOptions> {
145
155
  * and checked as soon as items carrying them arrive — through `setItems()` or the `load`
146
156
  * loader — so a value set before the items load is not lost.
147
157
  * @param {Iterable<unknown>|unknown[]} ids Checked item IDs.
158
+ * @param {ChecklistSetOptions} [options={}] Set `silent` to suppress `change`.
159
+ * @returns {this}
160
+ * @fires Checklist#change
161
+ */
162
+ setValues(ids: Iterable<unknown> | unknown[], { silent }?: ChecklistSetOptions): this;
163
+ /**
164
+ * Checks every item.
165
+ * @param {ChecklistSetOptions} [options={}] Set `silent` to suppress `change`.
166
+ * @returns {this}
167
+ * @fires Checklist#change
168
+ */
169
+ checkAll({ silent }?: ChecklistSetOptions): this;
170
+ /**
171
+ * Unchecks every item.
172
+ * @param {ChecklistSetOptions} [options={}] Set `silent` to suppress `change`.
148
173
  * @returns {this}
149
174
  * @fires Checklist#change
150
175
  */
151
- setValues(ids: Iterable<unknown> | unknown[]): this;
152
- /** Checks every item. @returns {this} @fires Checklist#change */
153
- checkAll(): this;
154
- /** Unchecks every item. @returns {this} @fires Checklist#change */
155
- uncheckAll(): this;
176
+ uncheckAll({ silent }?: ChecklistSetOptions): this;
156
177
  /**
157
178
  * Filters visible items by label.
158
179
  * @param {string} query Search text.
@@ -179,9 +200,10 @@ export declare class Checklist extends Component<ChecklistOptions> {
179
200
  * @param {Set<unknown>} next
180
201
  * @param {unknown[]|null} pending Requested IDs no item carries yet, or null when no request waits
181
202
  * for items; an empty array is a request made before any item existed.
203
+ * @param {boolean} [silent=false] Whether to leave out the `change` event.
182
204
  * @returns {void}
183
205
  */
184
- _replaceChecked(next: Set<unknown>, pending: unknown[] | null): void;
206
+ _replaceChecked(next: Set<unknown>, pending: unknown[] | null, silent?: boolean): void;
185
207
  /** @param {ChecklistItem} item @returns {unknown} */
186
208
  _itemValue(item: ChecklistItem): unknown;
187
209
  /** @param {ChecklistItem} item @returns {string} */
@@ -47,6 +47,12 @@ export type CodeEditorOptions = {
47
47
  * Whether content can be selected but not changed.
48
48
  */
49
49
  readOnly?: boolean;
50
+ /**
51
+ * The same setting under the spelling every other Zx control
52
+ * uses. The editor starts read-only when either `readOnly` or `readonly` is true, so neither
53
+ * spelling can switch off what the other one turned on.
54
+ */
55
+ readonly?: boolean;
50
56
  /**
51
57
  * Whether the editor is disabled.
52
58
  */
@@ -153,8 +159,20 @@ export declare class CodeEditor extends Component<CodeEditorOptions> {
153
159
  enable(): this;
154
160
  /** @returns {this} */
155
161
  disable(): this;
156
- /** @param {boolean} value Read-only state. @returns {this} */
162
+ /**
163
+ * Makes the text selectable but not editable, or editable again; reflected as `data-readonly` on
164
+ * the root.
165
+ * @param {boolean} value Read-only state.
166
+ * @returns {this}
167
+ */
157
168
  setReadOnly(value: boolean): this;
169
+ /**
170
+ * `setReadOnly()` under the spelling every other Zx control uses (`Field#setReadonly()`,
171
+ * `NumberField#setReadonly()`, `TagPicker#setReadonly()`); the two are interchangeable.
172
+ * @param {boolean} value Read-only state.
173
+ * @returns {this}
174
+ */
175
+ setReadonly(value: boolean): this;
158
176
  /** @param {KeyboardEvent} event @returns {void} */
159
177
  _handleKeydown(event: KeyboardEvent): void;
160
178
  /**
@@ -371,7 +371,8 @@ export declare class Dock extends Component<DockOptions> {
371
371
  */
372
372
  _buildPane(definition: DockPane): Record<string, any>;
373
373
  /**
374
- * Runs any not-yet-run content factory for whatever the pane currently shows.
374
+ * Runs any not-yet-run content factory for whatever the pane currently shows, and settles
375
+ * whether a shown tab panel is a Tab stop itself.
375
376
  * @param {Record<string, any>} record Pane record.
376
377
  * @returns {void}
377
378
  */
@@ -60,7 +60,8 @@ export type DropdownOptions = {
60
60
  * panel is hosted by that dialog, so `showModal()` does not make it inert.
61
61
  *
62
62
  * The panel follows its trigger in the Tab order: Tab on the anchor of an open panel moves into
63
- * the panel's first focusable control (or onto the panel itself when it carries a `tabindex`),
63
+ * the panel's first focusable control (or onto the panel itself when it carries a `tabindex`, where
64
+ * it shows focus with the ring inside its edge),
64
65
  * Tab past the panel's last control continues after the anchor, and Shift+Tab from the first goes
65
66
  * back to the anchor. Closing while focus is inside returns it to the anchor.
66
67
  * @fires Dropdown#open
@@ -195,6 +195,12 @@ export declare class FieldUpload extends Component<FieldUploadOptions> {
195
195
  * @returns {this}
196
196
  */
197
197
  setDisabled(disabled: boolean): this;
198
+ /** Disables file selection and dropping; the same as `setDisabled(true)`. @returns {this} */
199
+ disable(): this;
200
+ /** Enables file selection and dropping; the same as `setDisabled(false)`. @returns {this} */
201
+ enable(): this;
202
+ /** Whether file selection and dropping are disabled. @returns {boolean} */
203
+ isDisabled(): boolean;
198
204
  /** @param {FileList|File[]|ArrayLike<File>} files @returns {void} */
199
205
  _selectFiles(files: FileList | File[] | ArrayLike<File>): void;
200
206
  /** @param {FileList|File[]|ArrayLike<File>} files @returns {boolean} */
@@ -220,7 +220,6 @@ export declare class FilterPanel extends Component<FilterPanelOptions> {
220
220
  _restored: boolean;
221
221
  _entries: any[];
222
222
  _children: any[];
223
- _writing: boolean;
224
223
  _draft: {};
225
224
  _applied: {};
226
225
  _appliedDraft: string;
@@ -368,7 +367,12 @@ export declare class FilterPanel extends Component<FilterPanelOptions> {
368
367
  _commit(value: Record<string, unknown>): void;
369
368
  /** @returns {Record<string, unknown>} The draft, serialized and pruned. */
370
369
  _draftValue(): Record<string, unknown>;
371
- /** Pushes the draft back into the controls without re-entering the edit path. @returns {void} */
370
+ /**
371
+ * Pushes the draft back into the controls without re-entering the edit path: every entry writes
372
+ * silently (a plain input's `value`, `{silent: true}` to the composed controls), so none of them
373
+ * reports the write back as an edit.
374
+ * @returns {void}
375
+ */
372
376
  _writeControls(): void;
373
377
  /** @param {Record<string, unknown>} [value] The draft value, when it is already at hand. @returns {void} */
374
378
  _syncActions(value?: Record<string, unknown>): void;
@@ -299,8 +299,10 @@ export declare class ModuleBar extends AppRailPresenter {
299
299
  /** @returns {void} */
300
300
  _syncActive(): void;
301
301
  /**
302
- * Shows the tiles that fit, in bar order, and moves the rest behind "All modules". Everything is
303
- * shown first so a bar sized by its content measures as not overflowing and never shrinks itself.
302
+ * Shows the tiles that fit, in bar order, and moves the rest behind "All modules". Every module
303
+ * the bar could place is shown first, so a bar sized by its content measures as not overflowing
304
+ * and never shrinks itself; a module that can only ever be in the catalogue is not, so it takes
305
+ * no room.
304
306
  * @returns {void}
305
307
  */
306
308
  _layout(): void;
@@ -369,6 +371,55 @@ export declare function partitionModules(items: ModuleItem[], capacity?: number,
369
371
  overflow: ModuleItem[];
370
372
  more: boolean;
371
373
  };
374
+ export type ModuleBarSpace = {
375
+ /**
376
+ * Length of the list's content box along the bar.
377
+ */
378
+ room: number;
379
+ /**
380
+ * Gap between two shown entries.
381
+ */
382
+ gap?: number;
383
+ /**
384
+ * Shown
385
+ * entries: a module row by its `id`, a heading, or the button. A heading takes its room only when
386
+ * a module after it, before the next heading, is on the bar.
387
+ */
388
+ entries: Array<{
389
+ id?: string;
390
+ heading?: boolean;
391
+ more?: boolean;
392
+ size: number;
393
+ }>;
394
+ };
395
+ /**
396
+ * The bar's list as measured with every module it could place shown: its rows, section headings,
397
+ * and "All modules" button in document order, each with the length it takes along the bar, its
398
+ * margins included.
399
+ * @typedef {Object} ModuleBarSpace
400
+ * @property {number} room Length of the list's content box along the bar.
401
+ * @property {number} [gap=0] Gap between two shown entries.
402
+ * @property {Array<{id?: string, heading?: boolean, more?: boolean, size: number}>} entries Shown
403
+ * entries: a module row by its `id`, a heading, or the button. A heading takes its room only when
404
+ * a module after it, before the next heading, is on the bar.
405
+ */
406
+ /**
407
+ * Splits modules as `partitionModules()` does, giving it the most slots for which what it places
408
+ * fits the measured list: each row at its own length, a section heading only where one of its
409
+ * modules is on the bar, and the "All modules" button when it is shown. So one name that wraps to
410
+ * two lines costs its extra line, not a tile, and no row is ever cut in half. Kept modules stay
411
+ * on the bar even when nothing else fits, as with `partitionModules()`.
412
+ * @param {ModuleItem[]} items Modules.
413
+ * @param {ModuleBarSpace} space The measured list.
414
+ * @param {Array<string|number|null|undefined>|string|number|null} [keep=[]] Module ids that must stay visible.
415
+ * @param {boolean} [reserve=false] The button is shown even when every module fits.
416
+ * @returns {{visible: ModuleItem[], overflow: ModuleItem[], more: boolean}}
417
+ */
418
+ export declare function fitModules(items: ModuleItem[], space: ModuleBarSpace, keep?: Array<string | number | null | undefined> | string | number | null, reserve?: boolean): {
419
+ visible: ModuleItem[];
420
+ overflow: ModuleItem[];
421
+ more: boolean;
422
+ };
372
423
  /**
373
424
  * Resolves a module's identity colour: a valid CSS `color` wins, then a known `tone`.
374
425
  * @param {{tone?: unknown, color?: unknown}} item Module.
@@ -18,6 +18,11 @@ export type MultiValueEditorOptions = {
18
18
  * a drag handle, the up/down buttons, both, or neither.
19
19
  */
20
20
  reorder?: 'both' | 'buttons' | 'drag' | 'none';
21
+ /**
22
+ * Whether every row control (values, handles, move and remove
23
+ * buttons) and the add button are disabled; values can still be set from code.
24
+ */
25
+ disabled?: boolean;
21
26
  /**
22
27
  * Values change listener.
23
28
  */
@@ -39,6 +44,8 @@ export declare class MultiValueEditor extends Component<MultiValueEditorOptions>
39
44
  _values: string[];
40
45
  _ownedNodes: any[];
41
46
  _initialState: string;
47
+ _initialAriaDisabled: string;
48
+ _disabled: boolean;
42
49
  _dragIndex: number;
43
50
  /** @type {HTMLElement|null} Row made draggable by a pointer press on its handle. */
44
51
  _armed: HTMLElement | null;
@@ -63,6 +70,27 @@ export declare class MultiValueEditor extends Component<MultiValueEditorOptions>
63
70
  setValues(values: unknown[], { silent }?: {
64
71
  silent?: boolean;
65
72
  }): this;
73
+ /**
74
+ * Disables or enables the editor. Disabled, every value input or select, drag handle, move and
75
+ * remove button and the add button is disabled, the root carries `aria-disabled="true"`, and
76
+ * neither a pointer nor the handle's keys reorder anything. `setValues()` still works, and rows
77
+ * it renders stay disabled.
78
+ * @param {boolean} disabled Disabled state.
79
+ * @returns {this}
80
+ */
81
+ setDisabled(disabled: boolean): this;
82
+ /** Disables the editor; see `setDisabled()`. @returns {this} */
83
+ disable(): this;
84
+ /** Enables the editor. @returns {this} */
85
+ enable(): this;
86
+ /** Whether the editor is disabled. @returns {boolean} */
87
+ isDisabled(): boolean;
88
+ /**
89
+ * Applies the disabled state to the controls in place rather than re-rendering them, so a value
90
+ * typed into a row and not yet committed survives.
91
+ * @returns {void}
92
+ */
93
+ _syncDisabled(): void;
66
94
  /** @returns {{drag: boolean, buttons: boolean}} */
67
95
  _reorder(): {
68
96
  drag: boolean;
@@ -204,7 +204,7 @@ export declare class RunStatus extends Component<RunStatusOptions> {
204
204
  /** @type {AgentAvatar|null} The agent's face, kept across draws while it asks for the same traits. */
205
205
  _avatar: AgentAvatar | null;
206
206
  _faceKey: any;
207
- /** Whether the root took `tabindex="-1"` to hold focus that had nowhere else to go. */
207
+ /** Whether the root took `tabindex="-1"` (and `data-zx-focus`) to hold focus that had nowhere else to go. */
208
208
  _heldFocus: boolean;
209
209
  /** @type {ReturnType<typeof setInterval>|0} */
210
210
  _interval: ReturnType<typeof setInterval> | 0;
@@ -326,6 +326,7 @@ export declare class RunTrace extends Component<RunTraceOptions> {
326
326
  _summaryDoing: HTMLElement;
327
327
  _summary: HTMLElement;
328
328
  _list: HTMLElement;
329
+ _resize: ResizeObserver;
329
330
  static cssName: string;
330
331
  /** @type {Readonly<RunTraceOptions>} */
331
332
  static defaults: Readonly<RunTraceOptions>;
@@ -476,6 +477,13 @@ export declare class RunTrace extends Component<RunTraceOptions> {
476
477
  * @returns {void}
477
478
  */
478
479
  private _setStep;
480
+ /**
481
+ * Makes each code block a Tab stop while, and only while, its text scrolls inside it.
482
+ * @private
483
+ * @param {Element} scope Where to look for code blocks.
484
+ * @returns {void}
485
+ */
486
+ private _syncCodeStops;
479
487
  /**
480
488
  * Redraws the summary from the steps.
481
489
  * @private
@@ -79,9 +79,11 @@ export type SelectOptions = {
79
79
  */
80
80
  clearable?: boolean;
81
81
  /**
82
- * Filtering mode.
82
+ * Filtering mode: no filtering (a read-only
83
+ * input that opens the list), `'local'` matching against `items`, or a function that returns the
84
+ * items for a query (see `SelectFilter`).
83
85
  */
84
- filter?: false | 'local' | ((query: string) => Promise<SelectItem[]> | SelectItem[]);
86
+ filter?: false | 'local' | SelectFilter;
85
87
  /**
86
88
  * Fields searched by local filtering.
87
89
  */
@@ -191,6 +193,9 @@ export type SelectOptionEntry = {
191
193
  export type SelectSetOptions = {
192
194
  silent?: boolean;
193
195
  };
196
+ export type SelectFilter = (query: string, context: {
197
+ signal: AbortSignal;
198
+ }) => Promise<SelectItem[]> | SelectItem[];
194
199
  /**
195
200
  * APG editable combobox with optional local or asynchronous filtering.
196
201
  *
@@ -215,6 +220,7 @@ export declare class Select extends Component<SelectOptions> {
215
220
  _loading: boolean;
216
221
  _requestSequence: number;
217
222
  _queryTimer: number;
223
+ _queryController: AbortController;
218
224
  _position: import("../../core/position.js").PositionController;
219
225
  _createdRoot: boolean;
220
226
  _root: HTMLElement;
@@ -366,13 +372,14 @@ export declare class Select extends Component<SelectOptions> {
366
372
  * `true` for public, or a group ID — so the control binds straight to the record field.
367
373
  *
368
374
  * @param {Element|string|null} target Component target.
369
- * @param {SelectOptions & {groups?: SelectItem[]|((query: string) => Promise<SelectItem[]>|SelectItem[])}} [options={}]
375
+ * @param {SelectOptions & {groups?: SelectItem[]|SelectFilter}} [options={}]
370
376
  * Select overrides other than the fixed choices; `groups` holds the shareable groups, either as
371
- * an array (filtered locally) or as a loader function (queried remotely).
377
+ * an array (filtered locally) or as a loader function (queried remotely, and handed the same
378
+ * `{signal}` as any `filter` function).
372
379
  * @returns {Select}
373
380
  */
374
381
  static permission(target: Element | string | null, options?: SelectOptions & {
375
- groups?: SelectItem[] | ((query: string) => Promise<SelectItem[]> | SelectItem[]);
382
+ groups?: SelectItem[] | SelectFilter;
376
383
  }): Select;
377
384
  /** Cleans up the panel, pending async work, and enhanced target contents. @returns {void} */
378
385
  destroy(): void;
@@ -402,6 +409,12 @@ export declare class Select extends Component<SelectOptions> {
402
409
  _runAsyncQuery(query: string, sequence: number): Promise<void>;
403
410
  /** @returns {void} */
404
411
  _cancelQuery(): void;
412
+ /**
413
+ * Aborts the signal handed to the filter for the request in flight. Callers move the sequence on
414
+ * first, so whatever the aborted request resolves or rejects with is already stale.
415
+ * @returns {void}
416
+ */
417
+ _abortQuery(): void;
405
418
  /** @param {boolean} loading @returns {void} */
406
419
  _setLoading(loading: boolean): void;
407
420
  /** @returns {void} */
@@ -233,6 +233,13 @@ export declare class Tabbox extends Component<TabboxOptions> {
233
233
  _removeTab(name: string, emitClose: boolean): boolean;
234
234
  /** @param {TabRecord} record @returns {void} */
235
235
  _applyActive(record: TabRecord): void;
236
+ /**
237
+ * Makes the active panel a Tab stop only while nothing inside it is one: Tab from the tab goes
238
+ * to the panel's first control when it has one, and onto the panel itself when it holds only
239
+ * text to read or scroll.
240
+ * @returns {void}
241
+ */
242
+ _syncPanelStop(): void;
236
243
  /** @param {TabRecord} record @returns {void} */
237
244
  _ensureContent(record: TabRecord): void;
238
245
  /** @param {TabRecord} record @param {boolean} [focus=true] @returns {void} */
@@ -2,6 +2,9 @@ import { Component } from '../../core/component.js';
2
2
  export type TagItem = Record<string, any> | string | number;
3
3
  export type TagValueReader = string | ((item: TagItem) => unknown);
4
4
  export type TagLabelReader = string | ((item: TagItem) => string);
5
+ export type TagPickerFilter = (query: string, context: {
6
+ signal: AbortSignal;
7
+ }) => Promise<TagItem[]> | TagItem[];
5
8
  export type TagPickerOptions = {
6
9
  /**
7
10
  * Selectable items.
@@ -41,9 +44,10 @@ export type TagPickerOptions = {
41
44
  */
42
45
  searchKeys?: Array<TagValueReader> | null;
43
46
  /**
44
- * Filtering mode.
47
+ * Filtering mode: `'local'` matches against
48
+ * `items`; a function returns the items for each query (see `TagPickerFilter`).
45
49
  */
46
- filter?: 'local' | ((query: string) => Promise<TagItem[]> | TagItem[]);
50
+ filter?: 'local' | TagPickerFilter;
47
51
  /**
48
52
  * Minimum async query length.
49
53
  */
@@ -145,6 +149,16 @@ export type TagPickerOptions = {
145
149
  /** @typedef {Record<string, any>|string|number} TagItem */
146
150
  /** @typedef {string|((item: TagItem) => unknown)} TagValueReader */
147
151
  /** @typedef {string|((item: TagItem) => string)} TagLabelReader */
152
+ /**
153
+ * A remote filter: returns the items for a query, or a promise of them. The second argument
154
+ * carries an `AbortSignal` that aborts as soon as the answer would be ignored — a newer query
155
+ * starts, the list closes (or the picker is disabled or made read-only), `setItems()` replaces the
156
+ * catalogue, or the picker is destroyed — so the request can be cancelled by passing the signal on,
157
+ * e.g. `fetch(url, { signal })`. A result that arrives after its query was superseded is discarded
158
+ * whether or not the request honoured the signal, and the rejection an aborted request ends in is
159
+ * not reported as `error`.
160
+ * @typedef {(query: string, context: {signal: AbortSignal}) => Promise<TagItem[]>|TagItem[]} TagPickerFilter
161
+ */
148
162
  /**
149
163
  * @typedef {Object} TagPickerOptions
150
164
  * @property {TagItem[]} [items=[]] Selectable items.
@@ -160,7 +174,8 @@ export type TagPickerOptions = {
160
174
  * — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a
161
175
  * colour, and unknown names are ignored.
162
176
  * @property {Array<TagValueReader>|null} [searchKeys=null] Fields searched by local filtering.
163
- * @property {'local'|((query: string) => Promise<TagItem[]>|TagItem[])} [filter='local'] Filtering mode.
177
+ * @property {'local'|TagPickerFilter} [filter='local'] Filtering mode: `'local'` matches against
178
+ * `items`; a function returns the items for each query (see `TagPickerFilter`).
164
179
  * @property {number} [minQuery=0] Minimum async query length.
165
180
  * @property {number} [debounce=200] Async query delay in milliseconds.
166
181
  * @property {boolean} [allowCreate=false] Whether unknown values may be created from the query.
@@ -213,6 +228,7 @@ export declare class TagPicker extends Component<TagPickerOptions> {
213
228
  _loading: boolean;
214
229
  _requestSequence: any;
215
230
  _queryTimer: number;
231
+ _queryController: AbortController;
216
232
  _position: import("../../core/position.js").PositionController;
217
233
  _activeId: string;
218
234
  _createdRoot: boolean;
@@ -359,8 +375,8 @@ export declare class TagPicker extends Component<TagPickerOptions> {
359
375
  _scheduleAsyncQuery(query: string): void;
360
376
  /** @param {string} query @returns {Promise<void>} */
361
377
  _runQuery(query: string): Promise<void>;
362
- /** @returns {void} */
363
- _cancelQuery(): void;
378
+ /** @returns {number} The request generation this cancellation started. */
379
+ _cancelQuery(): number;
364
380
  /** @param {boolean} loading @returns {void} */
365
381
  _setLoading(loading: boolean): void;
366
382
  /**
@@ -80,6 +80,8 @@ export declare class Timebox extends Component<TimeboxOptions> {
80
80
  };
81
81
  _inputs: any[];
82
82
  _content: HTMLElement;
83
+ /** The value the segments were last written with: what a later commit is compared with. */
84
+ _committed: number;
83
85
  static cssName: string;
84
86
  /** @type {TimeboxOptions} */
85
87
  static defaults: TimeboxOptions;
@@ -100,6 +102,13 @@ export declare class Timebox extends Component<TimeboxOptions> {
100
102
  * @fires Timebox#change
101
103
  */
102
104
  set(value: number, unit?: TimeUnit | TimeboxSetOptions, options?: TimeboxSetOptions): this;
105
+ /**
106
+ * Moves focus to the hours segment, the first one a duration is typed into (the sign toggle of a
107
+ * `signed` timebox sits before it and stays one Shift+Tab away). Focusing selects the segment's
108
+ * digits, as a click into it does. A disabled timebox does not take focus.
109
+ * @returns {this}
110
+ */
111
+ focus(): this;
103
112
  /** Enables the timebox. @returns {this} */
104
113
  enable(): this;
105
114
  /** Disables the timebox. @returns {this} */
@@ -85,7 +85,10 @@ export declare class Component<TOptions extends ComponentOptions = ComponentOpti
85
85
  detail: Record<string, unknown>;
86
86
  };
87
87
  /**
88
- * Adds an automatically cleaned-up DOM event listener.
88
+ * Adds an automatically cleaned-up DOM event listener. It goes when the component is destroyed;
89
+ * a `signal` in the options shortens its life further, for a listener that belongs to one
90
+ * rendering of a part — it then goes when that signal aborts or the component is destroyed,
91
+ * whichever comes first.
89
92
  * @param {EventTarget} element DOM event target.
90
93
  * @param {string} type Event name.
91
94
  * @param {EventListenerOrEventListenerObject} fn Listener.