@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
@@ -3,6 +3,7 @@ import { h } from '../../core/dom.js';
3
3
  import { ICON_SIZE, icon } from '../../core/icons.js';
4
4
  import { rovingStep } from '../../core/keyboard.js';
5
5
  import { uid } from '../../core/util.js';
6
+ import { syncPanelStop } from '../../internal/focus-stops.js';
6
7
 
7
8
  /** @typedef {Node|Component|(() => Node|Component)} TabContent */
8
9
 
@@ -198,13 +199,14 @@ export class Tabbox extends Component {
198
199
  ariaDisabled: normalized.disabled ? 'true' : null,
199
200
  dataset: { closable: normalized.closable ? 'true' : null }
200
201
  }, children));
202
+ // A Tab stop only while it holds nothing that is one (`_syncPanelStop()`).
201
203
  const panel = h('div', {
202
204
  class: 'zx-tabbox__panel',
203
205
  id: panelId,
204
206
  role: 'tabpanel',
205
- tabindex: '0',
206
207
  ariaLabelledby: tabId,
207
- hidden: true
208
+ hidden: true,
209
+ dataset: { zxFocus: 'region' }
208
210
  });
209
211
  /** @type {TabRecord} */
210
212
  const record = { definition: normalized, tab, title, badge, panel, built: false };
@@ -351,6 +353,11 @@ export class Tabbox extends Component {
351
353
  if (!tab || !this.refs.tablist.contains(tab)) return;
352
354
  const current = this._recordForTab(tab);
353
355
  if (!current) return;
356
+ if (event.key === 'Tab' && !event.shiftKey) {
357
+ // The panel's content may have changed since it was shown; settle its stop before Tab moves.
358
+ this._syncPanelStop();
359
+ return;
360
+ }
354
361
  const enabled = this._enabledTabs();
355
362
  if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
356
363
  event.preventDefault();
@@ -440,9 +447,20 @@ export class Tabbox extends Component {
440
447
  record.tab.setAttribute('aria-selected', 'true');
441
448
  record.panel.hidden = false;
442
449
  if (record.panel.parentNode !== this.refs.panels) this.refs.panels.append(record.panel);
450
+ this._syncPanelStop();
443
451
  this._setFocused(record, false);
444
452
  }
445
453
 
454
+ /**
455
+ * Makes the active panel a Tab stop only while nothing inside it is one: Tab from the tab goes
456
+ * to the panel's first control when it has one, and onto the panel itself when it holds only
457
+ * text to read or scroll.
458
+ * @returns {void}
459
+ */
460
+ _syncPanelStop() {
461
+ if (this._active) syncPanelStop(this._active.panel);
462
+ }
463
+
446
464
  /** @param {TabRecord} record @returns {void} */
447
465
  _ensureContent(record) {
448
466
  if (record.built) return;
@@ -472,6 +472,9 @@ export class Table extends Component {
472
472
  this._scroll = h('div', {
473
473
  class: 'zx-table__scroll',
474
474
  dataset: {
475
+ // A scroller with nothing focusable inside is a Tab stop of the browser's making: it keeps
476
+ // an inset ring there, and none while it holds focus for a table with no rows.
477
+ zxFocus: 'region',
475
478
  stickyHeader: String(Boolean(this.options.stickyHeader)),
476
479
  // Stripes follow the row's place in the data while windowed: `:nth-child` would count the
477
480
  // spacers, and the stripes would swap as the window moved.
@@ -2917,11 +2920,13 @@ export class Table extends Component {
2917
2920
  if (!frame.hasAttribute('tabindex')) {
2918
2921
  frame.tabIndex = -1;
2919
2922
  frame.setAttribute('data-empty-focus', '');
2923
+ frame.dataset.zxFocus = 'container';
2920
2924
  }
2921
2925
  frame.focus({ preventScroll: true });
2922
2926
  } else if (frame.hasAttribute('data-empty-focus')) {
2923
2927
  frame.removeAttribute('tabindex');
2924
2928
  frame.removeAttribute('data-empty-focus');
2929
+ frame.dataset.zxFocus = 'region';
2925
2930
  }
2926
2931
  }
2927
2932
 
@@ -10,6 +10,16 @@ import { matchItems } from '../select/filter.js';
10
10
  /** @typedef {Record<string, any>|string|number} TagItem */
11
11
  /** @typedef {string|((item: TagItem) => unknown)} TagValueReader */
12
12
  /** @typedef {string|((item: TagItem) => string)} TagLabelReader */
13
+ /**
14
+ * A remote filter: returns the items for a query, or a promise of them. The second argument
15
+ * carries an `AbortSignal` that aborts as soon as the answer would be ignored — a newer query
16
+ * starts, the list closes (or the picker is disabled or made read-only), `setItems()` replaces the
17
+ * catalogue, or the picker is destroyed — so the request can be cancelled by passing the signal on,
18
+ * e.g. `fetch(url, { signal })`. A result that arrives after its query was superseded is discarded
19
+ * whether or not the request honoured the signal, and the rejection an aborted request ends in is
20
+ * not reported as `error`.
21
+ * @typedef {(query: string, context: {signal: AbortSignal}) => Promise<TagItem[]>|TagItem[]} TagPickerFilter
22
+ */
13
23
  /**
14
24
  * @typedef {Object} TagPickerOptions
15
25
  * @property {TagItem[]} [items=[]] Selectable items.
@@ -25,7 +35,8 @@ import { matchItems } from '../select/filter.js';
25
35
  * — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a
26
36
  * colour, and unknown names are ignored.
27
37
  * @property {Array<TagValueReader>|null} [searchKeys=null] Fields searched by local filtering.
28
- * @property {'local'|((query: string) => Promise<TagItem[]>|TagItem[])} [filter='local'] Filtering mode.
38
+ * @property {'local'|TagPickerFilter} [filter='local'] Filtering mode: `'local'` matches against
39
+ * `items`; a function returns the items for each query (see `TagPickerFilter`).
29
40
  * @property {number} [minQuery=0] Minimum async query length.
30
41
  * @property {number} [debounce=200] Async query delay in milliseconds.
31
42
  * @property {boolean} [allowCreate=false] Whether unknown values may be created from the query.
@@ -108,6 +119,7 @@ export class TagPicker extends Component {
108
119
  this._loading = false;
109
120
  this._requestSequence = 0;
110
121
  this._queryTimer = null;
122
+ this._queryController = null;
111
123
  this._position = null;
112
124
  this._activeId = null;
113
125
  this._createdRoot = this.el === null;
@@ -669,7 +681,8 @@ export class TagPicker extends Component {
669
681
 
670
682
  /** @param {string} query @returns {void} */
671
683
  _scheduleAsyncQuery(query) {
672
- this._cancelQuery();
684
+ // An abort listener of the application's that started another query has superseded this one.
685
+ if (this._cancelQuery() !== this._requestSequence) return;
673
686
  const text = String(query ?? '');
674
687
  if (text.length < Number(this.options.minQuery ?? 0)) {
675
688
  this._visible = [];
@@ -692,9 +705,17 @@ export class TagPicker extends Component {
692
705
  const sequence = this._requestSequence + 1;
693
706
  this._requestSequence = sequence;
694
707
  this._setLoading(true);
708
+ // The controller is in place before `query` is reported, so a listener that closes the picker,
709
+ // replaces its items or destroys it aborts it; and a query it superseded never starts.
710
+ const controller = new AbortController();
711
+ this._queryController = controller;
695
712
  this.emit('query', { query });
713
+ if (sequence !== this._requestSequence || controller.signal.aborted) {
714
+ if (this._queryController === controller) this._queryController = null;
715
+ return;
716
+ }
696
717
  try {
697
- const result = await /** @type {Function} */ (this.options.filter)(query);
718
+ const result = await /** @type {TagPickerFilter} */ (this.options.filter)(query, { signal: controller.signal });
698
719
  if (sequence !== this._requestSequence) return;
699
720
  this._items = Array.isArray(result) ? result.slice() : [];
700
721
  this._visible = this._items.slice();
@@ -709,17 +730,25 @@ export class TagPicker extends Component {
709
730
  this._setActive(this._entries.length > 0 ? 0 : -1);
710
731
  this._position?.update();
711
732
  }
733
+ // A settled request has nothing left to cancel.
734
+ if (this._queryController === controller) this._queryController = null;
712
735
  }
713
736
  }
714
737
 
715
- /** @returns {void} */
738
+ /** @returns {number} The request generation this cancellation started. */
716
739
  _cancelQuery() {
717
740
  if (this._queryTimer !== null) {
718
741
  clearTimeout(this._queryTimer);
719
742
  this._queryTimer = null;
720
743
  }
721
- this._requestSequence += 1;
722
- this._setLoading(false);
744
+ const sequence = ++this._requestSequence;
745
+ // The sequence has moved on first, so whatever the aborted request settles with is stale.
746
+ const controller = this._queryController;
747
+ this._queryController = null;
748
+ controller?.abort();
749
+ // An abort listener that started a newer query owns the loading state now.
750
+ if (sequence === this._requestSequence) this._setLoading(false);
751
+ return sequence;
723
752
  }
724
753
 
725
754
  /** @param {boolean} loading @returns {void} */
@@ -145,6 +145,17 @@ export class Timebox extends Component {
145
145
  return this;
146
146
  }
147
147
 
148
+ /**
149
+ * Moves focus to the hours segment, the first one a duration is typed into (the sign toggle of a
150
+ * `signed` timebox sits before it and stays one Shift+Tab away). Focusing selects the segment's
151
+ * digits, as a click into it does. A disabled timebox does not take focus.
152
+ * @returns {this}
153
+ */
154
+ focus() {
155
+ this._inputs[0]?.focus();
156
+ return this;
157
+ }
158
+
148
159
  /** Enables the timebox. @returns {this} */
149
160
  enable() {
150
161
  this._disabled = false;
@@ -210,9 +221,12 @@ export class Timebox extends Component {
210
221
 
211
222
  /** @returns {void} */
212
223
  _commitSegments() {
224
+ // Enter and the blur that follows both commit; only a commit that changed the value reports.
225
+ // The segments hold what is being typed, so the last committed value is the comparison.
226
+ const before = this._committed;
213
227
  this._parts = this._readParts();
214
228
  this._writeParts();
215
- this._emitChange();
229
+ if (this._committed !== before) this._emitChange();
216
230
  }
217
231
 
218
232
  /** @returns {void} */
@@ -221,6 +235,8 @@ export class Timebox extends Component {
221
235
  const name = input.dataset.segment;
222
236
  input.value = name === 'hours' ? String(this._parts[name]) : pad(this._parts[name]);
223
237
  }
238
+ /** The value the segments were last written with: what a later commit is compared with. */
239
+ this._committed = joinTime(this._parts, this.options.unit);
224
240
  if (this.refs.sign) {
225
241
  this.refs.sign.textContent = this._parts.negative ? '-' : '+';
226
242
  this.refs.sign.setAttribute('aria-pressed', String(this._parts.negative));
@@ -485,7 +485,7 @@ export class ViewSettings extends Component {
485
485
  // not kept alive by this panel until it is destroyed.
486
486
  const controller = new AbortController();
487
487
  this._bound = { view: candidate, controller };
488
- candidate.addEventListener('statechange', (/** @type {Event} */ event) => {
488
+ this.listen(candidate, 'statechange', (/** @type {Event} */ event) => {
489
489
  if (this._syncing) return;
490
490
  const reason = /** @type {CustomEvent} */ (event).detail?.reason;
491
491
  this._pullFromView(reason === 'fields' || reason === 'restore');
@@ -193,7 +193,10 @@ export class Component extends EventTarget {
193
193
  }
194
194
 
195
195
  /**
196
- * Adds an automatically cleaned-up DOM event listener.
196
+ * Adds an automatically cleaned-up DOM event listener. It goes when the component is destroyed;
197
+ * a `signal` in the options shortens its life further, for a listener that belongs to one
198
+ * rendering of a part — it then goes when that signal aborts or the component is destroyed,
199
+ * whichever comes first.
197
200
  * @param {EventTarget} element DOM event target.
198
201
  * @param {string} type Event name.
199
202
  * @param {EventListenerOrEventListenerObject} fn Listener.
@@ -202,7 +205,24 @@ export class Component extends EventTarget {
202
205
  */
203
206
  listen(element, type, fn, opts = {}) {
204
207
  const options = typeof opts === 'boolean' ? { capture: opts } : { ...opts };
205
- element.addEventListener(type, fn, { ...options, signal: this.#abort.signal });
208
+ const shorter = options.signal;
209
+ // A destroyed component, like an aborted signal, takes no more listeners.
210
+ if (shorter?.aborted || this.#abort.signal.aborted) return this;
211
+ if (!shorter || shorter === this.#abort.signal) {
212
+ element.addEventListener(type, fn, { ...options, signal: this.#abort.signal });
213
+ return this;
214
+ }
215
+ // Either signal ends the listener through one link of its own, and the link goes with it: a
216
+ // once listener that has run, or one signal aborting, leaves nothing held by the other. The
217
+ // callback is registered as given, so the platform still folds a repeated registration of it.
218
+ const link = new AbortController();
219
+ element.addEventListener(type, fn, { ...options, signal: link.signal });
220
+ if (options.once) {
221
+ element.addEventListener(type, () => link.abort(),
222
+ { once: true, capture: Boolean(options.capture), signal: link.signal });
223
+ }
224
+ shorter.addEventListener('abort', () => link.abort(), { once: true, signal: link.signal });
225
+ this.#abort.signal.addEventListener('abort', () => link.abort(), { once: true, signal: link.signal });
206
226
  return this;
207
227
  }
208
228
 
package/src/core/date.js CHANGED
@@ -1,5 +1,6 @@
1
1
  // @ts-check
2
2
  import { formattingLocale, getLanguage, hostMessage } from './i18n.js';
3
+ import { escapeRegExp } from './util.js';
3
4
 
4
5
  const MONTHS = [
5
6
  'January', 'February', 'March', 'April', 'May', 'June',
@@ -257,7 +258,3 @@ function yearFromTwoDigits(year) {
257
258
  return year >= 69 ? 1900 + year : 2000 + year;
258
259
  }
259
260
 
260
- /** @param {string} value @returns {string} */
261
- function escapeRegExp(value) {
262
- return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
263
- }
@@ -68,6 +68,9 @@ export function dragAxis(handle, options) {
68
68
  let moved = false;
69
69
  /** Handle of the frame a pending update is scheduled in; `0` if none. */
70
70
  let frame = 0;
71
+ /** Listeners on the document for a drag whose pointer could not be captured; null otherwise. */
72
+ /** @type {AbortController|null} */
73
+ let uncaptured = null;
71
74
 
72
75
  /** @param {PointerEvent} event @returns {number} */
73
76
  const axis = (event) => (vertical ? event.clientY : event.clientX);
@@ -110,6 +113,8 @@ export function dragAxis(handle, options) {
110
113
  moved = false;
111
114
  cancelFrame();
112
115
  releasePointer();
116
+ uncaptured?.abort();
117
+ uncaptured = null;
113
118
  };
114
119
 
115
120
  handle.addEventListener('pointerdown', (event) => {
@@ -130,12 +135,22 @@ export function dragAxis(handle, options) {
130
135
  try {
131
136
  /** @type {HTMLElement} */ (handle).setPointerCapture(pointer.pointerId);
132
137
  } catch {
133
- // A pointer that ended between the event and this call cannot be captured; the drag simply
134
- // finishes on the next pointerup.
138
+ // Uncaptured, the pointer's moves and release go to whatever is under it, so the document is
139
+ // watched for them: a release off the handle must still end the drag, or every later press
140
+ // is refused while it stays open.
141
+ const target = handle.ownerDocument;
142
+ if (target) {
143
+ uncaptured = new AbortController();
144
+ const watch = { signal: uncaptured.signal };
145
+ target.addEventListener('pointermove', move, watch);
146
+ target.addEventListener('pointerup', end, watch);
147
+ target.addEventListener('pointercancel', end, watch);
148
+ }
135
149
  }
136
150
  }, { signal });
137
151
 
138
- handle.addEventListener('pointermove', (event) => {
152
+ /** @param {Event} event @returns {void} */
153
+ function move(event) {
139
154
  const pointer = /** @type {PointerEvent} */ (event);
140
155
  if (!dragging || pointer.pointerId !== pointerId) return;
141
156
  client = axis(pointer);
@@ -145,10 +160,11 @@ export function dragAxis(handle, options) {
145
160
  frame = 0;
146
161
  if (dragging) options.onMove(sign * (client - startClient));
147
162
  });
148
- }, { signal });
163
+ }
164
+ handle.addEventListener('pointermove', move, { signal });
149
165
 
150
166
  /** @param {Event} event @returns {void} */
151
- const end = (event) => {
167
+ function end(event) {
152
168
  const pointer = /** @type {PointerEvent} */ (event);
153
169
  if (!dragging || pointer.pointerId !== pointerId) return;
154
170
  cancelFrame();
@@ -157,7 +173,7 @@ export function dragAxis(handle, options) {
157
173
  const delta = sign * (client - startClient);
158
174
  finish();
159
175
  options.onEnd?.(delta, travelled);
160
- };
176
+ }
161
177
  handle.addEventListener('pointerup', end, { signal });
162
178
  handle.addEventListener('pointercancel', end, { signal });
163
179
 
@@ -0,0 +1,108 @@
1
+ // @ts-check
2
+ /**
3
+ * Tab stops for elements that are not controls: a tab panel and a scrolling block.
4
+ *
5
+ * Both carry `data-zx-focus="region"` (see `styles/base.css`), so when the keyboard does reach them
6
+ * the ring is drawn inset. These helpers decide whether the keyboard reaches them at all.
7
+ */
8
+
9
+ /** Elements the browser puts in the Tab order without a `tabindex` of their own. */
10
+ const NATIVE_STOPS = [
11
+ 'a[href]', 'area[href]', 'button', 'input:not([type="hidden"])', 'select', 'textarea', 'iframe',
12
+ 'object', 'embed', 'audio[controls]', 'video[controls]', 'details > summary:first-of-type',
13
+ '[contenteditable]:not([contenteditable="false"])'
14
+ ].join(',');
15
+
16
+ /** Every element that may be a Tab stop: the native ones and anything with a `tabindex`. */
17
+ const CANDIDATES = `${NATIVE_STOPS},[tabindex]`;
18
+
19
+ /**
20
+ * Keeps a tab panel in the Tab order only while nothing inside it is a Tab stop, as the WAI-ARIA
21
+ * tabs pattern asks: a panel holding controls hands Tab straight to its first control, and a panel
22
+ * of plain text stays reachable from its tab so it can be read and scrolled.
23
+ *
24
+ * The decision is made from the markup — tab indexes, `disabled`, and `hidden`, `inert` or closed
25
+ * `<details>` subtrees inside the panel — and from layout only while the panel is rendered, so it
26
+ * holds for a panel that is not in the document yet. Call it whenever a panel is shown or its
27
+ * content is replaced, and again just before focus can move from the tab list into the panel. A
28
+ * panel that holds focus keeps its stop until a later call. Controls inside a shadow root are not
29
+ * seen, so a panel whose only controls sit in a custom element's shadow tree stays a stop itself.
30
+ * @param {HTMLElement} panel The `role="tabpanel"` element.
31
+ * @returns {boolean} Whether the panel is now a Tab stop itself.
32
+ */
33
+ export function syncPanelStop(panel) {
34
+ const stop = !containsTabStop(panel);
35
+ if (stop && panel.getAttribute('tabindex') !== '0') panel.tabIndex = 0;
36
+ // A panel holding focus keeps its stop, so focus never drops to <body>; a later call settles it.
37
+ else if (!stop && panel.hasAttribute('tabindex') && panel.ownerDocument.activeElement !== panel) {
38
+ panel.removeAttribute('tabindex');
39
+ }
40
+ return stop;
41
+ }
42
+
43
+ /**
44
+ * Whether Tab can stop anywhere inside a container.
45
+ * @param {Element} container Container to search.
46
+ * @returns {boolean}
47
+ */
48
+ export function containsTabStop(container) {
49
+ const rendered = isRendered(container);
50
+ for (const element of container.querySelectorAll(CANDIDATES)) {
51
+ if (isTabStop(element, container, rendered)) return true;
52
+ }
53
+ return false;
54
+ }
55
+
56
+ /**
57
+ * Keeps a scrolling block in the Tab order only while its content overflows, so the keyboard can
58
+ * scroll what the pointer can, and a block that fits is no stop at all. A block that is not laid
59
+ * out (detached, or inside something hidden) measures nothing and is left out until it is. A
60
+ * block holding focus keeps its stop, so a resize never drops focus; a later call settles it.
61
+ * @param {HTMLElement} element The scrolling element.
62
+ * @returns {boolean} Whether the element now overflows.
63
+ */
64
+ export function syncScrollStop(element) {
65
+ const overflowing = isOverflowing(element);
66
+ if (overflowing && !element.hasAttribute('tabindex')) element.tabIndex = 0;
67
+ else if (!overflowing && element.hasAttribute('tabindex') && element.ownerDocument.activeElement !== element) {
68
+ element.removeAttribute('tabindex');
69
+ }
70
+ return overflowing;
71
+ }
72
+
73
+ /**
74
+ * Whether an element's content is larger than its box on either axis.
75
+ * @param {Element} element Element to measure.
76
+ * @returns {boolean}
77
+ */
78
+ export function isOverflowing(element) {
79
+ return element.scrollWidth > element.clientWidth + 1 || element.scrollHeight > element.clientHeight + 1;
80
+ }
81
+
82
+ /**
83
+ * @param {Element} element Candidate found by `CANDIDATES`.
84
+ * @param {Element} container The container being searched; ancestors above it do not count.
85
+ * @param {boolean} rendered Whether the container is laid out, so layout can be asked too.
86
+ * @returns {boolean}
87
+ */
88
+ function isTabStop(element, container, rendered) {
89
+ const html = /** @type {HTMLElement} */ (element);
90
+ if (typeof html.focus !== 'function') return false;
91
+ const index = Number.parseInt(element.getAttribute('tabindex') ?? '', 10);
92
+ if (Number.isNaN(index) ? !element.matches(NATIVE_STOPS) : index < 0) return false;
93
+ if (element.matches(':disabled')) return false;
94
+ for (let node = /** @type {Element|null} */ (element); node && node !== container; node = node.parentElement) {
95
+ if (/** @type {HTMLElement} */ (node).hidden || node.hasAttribute('inert')) return false;
96
+ const parent = node.parentElement;
97
+ if (parent?.localName === 'details' && !(/** @type {HTMLDetailsElement} */ (parent).open)
98
+ && node !== parent.querySelector(':scope > summary')) return false;
99
+ }
100
+ if (!rendered) return true;
101
+ if (typeof html.checkVisibility === 'function') return html.checkVisibility({ visibilityProperty: true });
102
+ return html.getClientRects().length > 0;
103
+ }
104
+
105
+ /** @param {Element} element @returns {boolean} Whether the element is laid out at all. */
106
+ function isRendered(element) {
107
+ return element.isConnected && element.getClientRects().length > 0;
108
+ }
@@ -117,9 +117,13 @@ function isRecord(value) {
117
117
  * @returns {string}
118
118
  */
119
119
  export function errorMessage(error) {
120
- if (error instanceof Error && error.message) return error.message;
121
- if (error && typeof error === 'object' && typeof error.message === 'string') return error.message;
122
- return String(error ?? 'ZeyOS request failed');
120
+ // An object's text is its `message`, never its `[object Object]` string form.
121
+ const message = error && typeof error === 'object'
122
+ ? /** @type {{message?: unknown}} */ (error).message
123
+ : error;
124
+ const text = message == null ? '' : String(message);
125
+ // A blank message reads as an empty toast; the generic sentence at least says what failed.
126
+ return text.trim() ? text : 'ZeyOS request failed';
123
127
  }
124
128
 
125
129
  /** @param {string} value @returns {string} */
@@ -24,7 +24,10 @@ export const ZEYOS_ICON_KIT = 'https://kit.fontawesome.com/ae8320b210.js';
24
24
  * @returns {Promise<object>} Resolves with the icon configuration once the kit has loaded.
25
25
  */
26
26
  export function useZeyosIcons(options = {}) {
27
- return loadFontAwesome({ kit: ZEYOS_ICON_KIT, ...options });
27
+ // A kit passed as `undefined` is a kit not passed, so a wrapper forwarding an unset setting
28
+ // still loads the ZeyOS kit.
29
+ const { kit = ZEYOS_ICON_KIT, ...rest } = options ?? {};
30
+ return loadFontAwesome({ ...rest, kit });
28
31
  }
29
32
 
30
33
  /**
@@ -113,5 +116,7 @@ export function moduleChip(name, options = {}) {
113
116
  * @returns {HTMLElement}
114
117
  */
115
118
  export function zeyosAppIcon(name, options = {}) {
116
- return moduleChip(name, { shape: 'circle', ...options });
119
+ // An unset shape — absent or passed as undefined — is the AppIcon's circle.
120
+ const { shape = 'circle', ...rest } = options ?? {};
121
+ return moduleChip(name, { ...rest, shape });
117
122
  }
package/styles/base.css CHANGED
@@ -26,12 +26,35 @@
26
26
  outline in Chrome/Safari) at the border edge, so a focused control showed a blue border inside
27
27
  our accent glow. The replacement outline is transparent rather than removed: forced-colors mode
28
28
  drops box-shadows but forces outline-color to a system colour, so focus stays visible there. */
29
- .zx-scope :focus-visible {
29
+ .zx-scope :focus-visible:where(:not([data-zx-focus])) {
30
30
  outline: 2px solid transparent;
31
31
  outline-offset: 2px;
32
32
  box-shadow: var(--zx-focus-ring);
33
33
  }
34
34
 
35
+ /* The ring marks the control the next key operates. An element that takes focus without being
36
+ one says so with `data-zx-focus`, because Chrome rings a focused element after any key press —
37
+ even Shift — so a click into plain content followed by a keystroke lit a whole panel up like a
38
+ field:
39
+ - `container` — only a script focuses it (`tabindex="-1"`, never a Tab stop): a dialog with
40
+ nothing to operate, a card holding focus after its answered button went away, a heading a
41
+ view moves the reader to, an application root that keeps its shortcuts reachable. It draws
42
+ no ring, in forced colours either.
43
+ - `region` — a Tab stop that is not a control: a scroll region the keyboard has to reach, a tab
44
+ panel with nothing inside to operate. Keyboard focus there must stay visible, so it keeps the
45
+ ring, inside its edge rather than around it. The ring is an outline, not an inset shadow: an
46
+ inset shadow paints under the content, and a table's cells cover their scroller entirely.
47
+ Either way the element's own box-shadow — a dialog's elevation — is left alone. The marker
48
+ works on the `.zx-scope` element itself as well as inside it. */
49
+ :is(.zx-scope, .zx-scope *)[data-zx-focus="container"]:focus-visible {
50
+ outline: none; /* lint: outline-ok — never a Tab stop; only a script focuses it */
51
+ }
52
+
53
+ :is(.zx-scope, .zx-scope *)[data-zx-focus="region"]:focus-visible {
54
+ outline: 2px solid var(--zx-color-ring);
55
+ outline-offset: -2px;
56
+ }
57
+
35
58
  /* Forced colours (Windows high contrast) drop every box-shadow, so the accent ring disappears and
36
59
  the outline is the only focus indicator left. Components therefore never set `outline: 0` or
37
60
  `outline: none` on a focusable element — they make it transparent (`outline-color:
@@ -39,9 +62,10 @@
39
62
  system colour. `tests/lint-tokens.js` rejects outline suppression outside a marked exception.
40
63
  `!important` because a component's own, more specific `outline-color: transparent` would
41
64
  otherwise survive on an element that opts out with `forced-color-adjust: none` (a current item
42
- filled with Highlight). Offsets are left to the component, so inset rings stay inset. */
65
+ filled with Highlight). Offsets are left to the component, so inset rings stay inset. A
66
+ `data-zx-focus="container"` is never a Tab stop and stays unmarked. */
43
67
  @media (forced-colors: active) {
44
- .zx-scope :focus-visible {
68
+ .zx-scope :focus-visible:where(:not([data-zx-focus="container"])) {
45
69
  outline: 2px solid Highlight !important;
46
70
  }
47
71
  }
@@ -47,7 +47,7 @@
47
47
  --zx-color-text: var(--zx-gray-200);
48
48
  --zx-color-text-muted: var(--zx-gray-400);
49
49
  --zx-color-text-subtle: color-mix(in srgb, var(--zx-gray-500) 50%, var(--zx-gray-400));
50
- --zx-color-text-placeholder: var(--zx-gray-500);
50
+ --zx-color-text-placeholder: var(--zx-gray-400);
51
51
  --zx-color-text-invert: var(--zx-gray-950);
52
52
  --zx-color-accent: var(--zx-accent-400);
53
53
  --zx-color-accent-hover: var(--zx-accent-300);
@@ -126,7 +126,7 @@
126
126
  --zx-color-text: var(--zx-gray-200);
127
127
  --zx-color-text-muted: var(--zx-gray-400);
128
128
  --zx-color-text-subtle: color-mix(in srgb, var(--zx-gray-500) 50%, var(--zx-gray-400));
129
- --zx-color-text-placeholder: var(--zx-gray-500);
129
+ --zx-color-text-placeholder: var(--zx-gray-400);
130
130
  --zx-color-text-invert: var(--zx-gray-950);
131
131
  --zx-color-accent: var(--zx-accent-400);
132
132
  --zx-color-accent-hover: var(--zx-accent-300);
@@ -152,7 +152,7 @@
152
152
  /* Icons and non-essential meta: at least 3:1 on the surface, the chrome, and a current row. */
153
153
  --zx-color-text-subtle: light-dark(color-mix(in srgb, var(--zx-gray-500) 70%, var(--zx-gray-400)),
154
154
  color-mix(in srgb, var(--zx-gray-500) 50%, var(--zx-gray-400)));
155
- --zx-color-text-placeholder: light-dark(var(--zx-gray-400), var(--zx-gray-500));
155
+ --zx-color-text-placeholder: light-dark(color-mix(in srgb, var(--zx-gray-500) 80%, var(--zx-gray-600)), var(--zx-gray-400));
156
156
  --zx-color-text-invert: light-dark(var(--zx-gray-50), var(--zx-gray-950));
157
157
  /* Navigation at rest: one ink step under the content, so the eye lands on the page and the
158
158
  columns beside it read as places rather than as a second document. Hover, focus, and the
@@ -397,7 +397,7 @@
397
397
  --zx-color-text: var(--zx-gray-950);
398
398
  --zx-color-text-muted: color-mix(in srgb, var(--zx-gray-500) 50%, var(--zx-gray-600));
399
399
  --zx-color-text-subtle: color-mix(in srgb, var(--zx-gray-500) 70%, var(--zx-gray-400));
400
- --zx-color-text-placeholder: var(--zx-gray-400);
400
+ --zx-color-text-placeholder: color-mix(in srgb, var(--zx-gray-500) 80%, var(--zx-gray-600));
401
401
  --zx-color-text-invert: var(--zx-gray-50);
402
402
  --zx-color-app-icon-glyph: var(--zx-gray-0);
403
403
  --zx-color-app-icon-shade: var(--zx-gray-950);