@zeyos/zx 5.8.1 → 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 (68) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/dist/types/components/block-view/block-view.d.ts +3 -2
  3. package/dist/types/components/dock/dock.d.ts +2 -1
  4. package/dist/types/components/dropdown/dropdown.d.ts +2 -1
  5. package/dist/types/components/module-bar/module-bar.d.ts +53 -2
  6. package/dist/types/components/run-status/run-status.d.ts +1 -1
  7. package/dist/types/components/run-trace/run-trace.d.ts +8 -0
  8. package/dist/types/components/tabbox/tabbox.d.ts +7 -0
  9. package/dist/types/internal/focus-stops.d.ts +42 -0
  10. package/dist/zx-zeyos.esm.js +87 -25
  11. package/dist/zx-zeyos.esm.min.js +4 -4
  12. package/dist/zx.core.css +9 -2
  13. package/dist/zx.core.min.css +1 -1
  14. package/dist/zx.css +22 -84
  15. package/dist/zx.esm.js +258 -51
  16. package/dist/zx.esm.min.js +26 -26
  17. package/dist/zx.global.js +258 -51
  18. package/dist/zx.global.min.js +26 -26
  19. package/dist/zx.layered.css +22 -84
  20. package/dist/zx.layered.min.css +1 -1
  21. package/dist/zx.min.css +1 -1
  22. package/docs/components/approval-card.md +2 -2
  23. package/docs/components/block-view.md +2 -1
  24. package/docs/components/composer.md +4 -0
  25. package/docs/components/dock.md +4 -1
  26. package/docs/components/dropdown.md +3 -1
  27. package/docs/components/modal.md +3 -0
  28. package/docs/components/navigation-bar.md +5 -0
  29. package/docs/components/questionnaire.md +2 -2
  30. package/docs/components/run-status.md +2 -1
  31. package/docs/components/run-trace.md +2 -1
  32. package/docs/components/tabbox.md +6 -0
  33. package/docs/components/tokens.md +20 -0
  34. package/docs/llms.md +57 -9
  35. package/package.json +1 -1
  36. package/src/components/approval-card/approval-card.css +0 -5
  37. package/src/components/approval-card/approval-card.js +2 -0
  38. package/src/components/block-view/block-view.css +0 -10
  39. package/src/components/block-view/block-view.js +11 -6
  40. package/src/components/card/card.css +3 -0
  41. package/src/components/card-view/card-view.css +5 -5
  42. package/src/components/card-view/card-view.js +3 -1
  43. package/src/components/composer/composer.css +15 -26
  44. package/src/components/copy/copy-input.css +3 -1
  45. package/src/components/dialog/dialog.js +2 -1
  46. package/src/components/dock/dock.css +0 -6
  47. package/src/components/dock/dock.js +22 -7
  48. package/src/components/dropdown/dropdown.js +17 -2
  49. package/src/components/field/field.js +2 -1
  50. package/src/components/master-panel/master-panel.js +3 -1
  51. package/src/components/modal/modal.css +2 -11
  52. package/src/components/modal/modal.js +5 -2
  53. package/src/components/module-bar/module-bar.js +110 -26
  54. package/src/components/navigation-bar/navigation-bar.css +0 -4
  55. package/src/components/navigation-bar/navigation-bar.js +11 -2
  56. package/src/components/questionnaire/questionnaire.css +0 -14
  57. package/src/components/questionnaire/questionnaire.js +4 -2
  58. package/src/components/run-status/run-status.css +0 -7
  59. package/src/components/run-status/run-status.js +3 -1
  60. package/src/components/run-trace/run-trace.css +0 -5
  61. package/src/components/run-trace/run-trace.js +23 -2
  62. package/src/components/surface/surface.css +0 -6
  63. package/src/components/surface/surface.js +1 -1
  64. package/src/components/tabbox/tabbox.css +0 -6
  65. package/src/components/tabbox/tabbox.js +20 -2
  66. package/src/components/table/table.js +5 -0
  67. package/src/internal/focus-stops.js +108 -0
  68. package/styles/base.css +27 -3
@@ -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
 
@@ -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
+ }
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
  }