@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
@@ -37,8 +37,8 @@ the answer, and the application carries it out.
37
37
  now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
38
38
  included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
39
39
  `focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
40
- starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
41
- dialogs, including an open confirmation).
40
+ starts waiting; it is a container and draws no focus ring), `handleKey(event)` → `boolean`, and
41
+ `destroy()` (also destroys the card's dialogs, including an open confirmation).
42
42
  - **Update in place** — `update()` is for a request the agent revises while it waits, or a record
43
43
  that changed. It redraws only what changed: values equal to what is drawn (compared by content,
44
44
  so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
@@ -21,7 +21,8 @@ the answer arriving.
21
21
  blank line starts a new paragraph.
22
22
  - **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
23
23
  `end` when a streamed answer is marked finished.
24
- - **Rendering** — code is a figure with its language, a copy button and a focusable `<pre>`
24
+ - **Rendering** — code is a figure with its language, a copy button and a `<pre>` that is a Tab
25
+ stop only while a long line scrolls it
25
26
  (`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
26
27
  code read at length in an inspector),
27
28
  coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
@@ -94,6 +94,10 @@ the application, which owns the conversation and the transport.
94
94
  - **Files** — the Attach button, pasting files, and dropping files on the composer (the root shows
95
95
  `data-state="dropping"` and a drop label meanwhile) add attachments, filtered by `accept` and
96
96
  capped by `maxFiles`.
97
+ - **Focus** — the box is a tray on the chrome tone; the text inside it is a field with the control
98
+ edge and fill, and it alone draws the focus ring while it is typed into. The box, the chips, the
99
+ queue and the bar never light up; Attach, Commands, the tools and Send ring only when they hold
100
+ the focus themselves.
97
101
  - **Accessibility** — the `<textarea>` keeps its textbox role. While suggestions show it carries
98
102
  `aria-autocomplete="list"`, `aria-controls` (the listbox) and `aria-activedescendant` (the
99
103
  highlighted `role="option"`), and a polite status says how many there are. Attachments and
@@ -48,7 +48,10 @@ detail side of a master–detail screen. Give the root a size of its own (a grid
48
48
  a release that added or removed panes.
49
49
  - **Keyboard and screen readers** — each pane header is a row, not one big button, so the collapse
50
50
  toggle and the tab strip can coexist; the toggle carries `aria-expanded` and `aria-controls`.
51
- Tabs follow the APG tab pattern with one roving tab stop, Left/Right moving between them.
51
+ Tabs follow the APG tab pattern with one roving tab stop, Left/Right moving between them. The
52
+ active panel is a Tab stop itself only while nothing inside it is focusable, with the ring
53
+ inside its edge, so its text can be read and scrolled; a panel holding a control is not. A scrolling pane
54
+ body that the browser makes a Tab stop (nothing focusable inside) rings the same way.
52
55
  Dividers are focusable `separator`s carrying live `aria-valuenow`/`aria-valuemin`/`aria-valuemax`
53
56
  in pixels: Up/Down (or Left/Right when horizontal) resize by 16px, Shift by 64px, and Enter or
54
57
  Space collapses the pane before the divider. A divider with nothing to resize is taken out of the
@@ -28,7 +28,9 @@ DOM child of the anchor's nearest Zx theme scope while the browser lifts it into
28
28
  not opened from it) leaves the panel open; nothing below an open modal reacts at all. A panel
29
29
  opened from inside another overlay closes with that overlay.
30
30
  - **Keyboard** — the panel follows its trigger in the Tab order: Tab on the anchor of an open panel
31
- moves to the panel's first Tab stop, or onto the panel itself when it has a `tabindex`; Tab past
31
+ moves to the panel's first Tab stop, or onto the panel itself when it has a `tabindex` of 0 or
32
+ more (it then shows focus as a region, with the ring inside its edge; a panel only a script
33
+ focuses draws none); Tab past
32
34
  the last stop continues with whatever follows the anchor; Shift+Tab from the first
33
35
  stop returns to the anchor. A Tab stop is what the browser itself stops at: a `tabindex="-1"` part
34
36
  of a composite (a Select's toggle), a roving toolbar's inactive items, disabled, hidden and inert
@@ -13,6 +13,9 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
13
13
  dialog detached until then, rather than parking it on `<body>` outside the theme.
14
14
  - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
15
15
  - **Events** — `open`, `close {result}`, `cancel {reason}`.
16
+ - **Focus** — opening focuses an `autofocus` control, else the first focusable one. A panel with
17
+ nothing focusable takes focus itself (`tabindex="-1"`, outside the Tab order) and draws no focus
18
+ ring, keeping its elevation: the panel is a surface, not a control (`data-zx-focus="container"`).
16
19
  - **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
17
20
  `reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
18
21
  action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
@@ -11,6 +11,11 @@ menu on narrow widths.
11
11
  `overflow: true`, `overflowBelow: '44rem'`, `minVisible: 0`.
12
12
  - **Methods** — `setTitle()`, `setItems()`, `setActive()`, `setBadge()`, `setActions()`.
13
13
  - **Events** — `change {name}`.
14
+ - **Panels** — items that all carry `content` (a Node, a Component, or a factory called on first
15
+ selection) make the items an APG tab list with a panel each: ArrowLeft/Right and Home/End move
16
+ focus, Enter/Space select. The active panel is a Tab stop itself only while nothing inside it is
17
+ focusable, with the ring inside its edge, so its text can be read and scrolled; a panel holding a
18
+ control is not, and Tab reaches its first control after the bar's own actions.
14
19
 
15
20
  **Overflow is a default, not a law.** Collapsing every item behind "More" is right for a top app
16
21
  bar and wrong for a phone bottom bar, where the navigation is the point. `overflow: false` keeps
@@ -111,5 +111,5 @@ can be any registered `Field` type, and its validation may be asynchronous.
111
111
  cap on each choice; the caps are `aria-hidden`, since a screen-reader user moves through the
112
112
  group with the arrow keys the radios already provide. `Enter` continues, except in a `multiline`
113
113
  input. Shortcuts are suppressed while focus is in a text control. Navigating moves focus to the
114
- new question's fieldset, which is what gets the prompt announced; failing validation moves it to
115
- the first answer control instead.
114
+ new question's fieldset, which is what gets the prompt announced (it draws no focus ring: it is
115
+ not a control); failing validation moves it to the first answer control instead.
@@ -43,7 +43,8 @@ announces nothing itself; the thread the run belongs to announces its milestones
43
43
  - **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
44
44
  not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
45
45
  the action at the same index, or the nearest one left. When no action is left the panel itself
46
- holds focus (`tabindex="-1"`, removed again once focus moves on).
46
+ holds focus (`tabindex="-1"` with `data-zx-focus="container"`, so no focus ring; both removed
47
+ again once focus moves on).
47
48
  - **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
48
49
  update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
49
50
  (the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
@@ -52,7 +52,8 @@ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
52
52
  label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
53
53
  `icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
54
54
  name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
55
- otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
55
+ otherwise) and the result or the error, each in a `<pre>` with a copy button, a Tab stop while
56
+ its text scrolls. A
56
57
  `handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
57
58
  avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
58
59
  model, and an agent author with `face` as its still `AgentAvatar` — and its own label moves to
@@ -31,3 +31,9 @@ restores rounded corners without forking the stylesheet.
31
31
  - **Keyboard** — ArrowLeft/Right and Home/End move focus, Enter/Space activate, Delete closes a
32
32
  closable tab. The × is a plain glyph rather than a nested button (buttons cannot nest), so
33
33
  keyboard and screen-reader users close through Delete; focus lands on the neighbouring tab.
34
+ - **Panel focus** — a panel holding a control is not a Tab stop itself, so Tab from the tab list
35
+ reaches the control. A panel with nothing focusable inside is a Tab stop (`tabindex="0"`), drawn
36
+ with the ring inside its edge, so its text can be read and scrolled from the keyboard. This is
37
+ settled whenever a panel is shown and again as Tab leaves the tab list, so content that changes
38
+ inside a panel is taken into account. Controls inside a custom element's shadow root are not
39
+ seen, so a panel whose only controls sit there stays a Tab stop as well.
@@ -80,3 +80,23 @@ stays in the tab order, so focusing it shows it. On touch screens, under `prefer
80
80
  and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
81
81
  that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
82
82
  visible. Hosts do not nest.
83
+
84
+ **Focus targets.** `.zx-scope` draws the focus ring on whatever matches `:focus-visible`, and
85
+ Chrome matches any focused element once a key has been pressed — even Shift — so a click into a
86
+ focusable panel followed by a keystroke would ring the whole panel like a field. An element that
87
+ takes focus without being a control says which kind it is with `data-zx-focus`:
88
+ - `data-zx-focus="container"` — only a script focuses it (`tabindex="-1"`, never a Tab stop): a
89
+ view root that keeps its shortcuts reachable, a heading a route change moves the reader to, a
90
+ panel holding focus after the control in it went away. It draws no ring and no outline, in forced
91
+ colours either; its own box-shadow (an overlay's elevation) stays.
92
+ - `data-zx-focus="region"` — a Tab stop that is not a control: a scroll region the keyboard has to
93
+ reach, a tab panel with nothing inside to operate. Keyboard focus there stays visible as a ring
94
+ inside its edge, drawn as an outline so the region's own content cannot cover it; forced colours
95
+ paint it in the system highlight.
96
+
97
+ Set it when the element is created; it only matters while the element has focus. It works on the
98
+ `.zx-scope` element itself as well as on anything inside it. Zx components
99
+ mark their own: the Modal, Dialog and Sheet panel, a Dropdown panel only a script focuses, the
100
+ ApprovalCard and RunStatus roots, Questionnaire's question and review, Surface's verdict and the
101
+ emptied Table and CardView bodies are containers; tab panels, code blocks, a Dropdown panel with a
102
+ `tabindex` of 0 or more, and the scroll regions of Table, Dock and MasterPanel are regions.
package/docs/llms.md CHANGED
@@ -452,6 +452,8 @@ var(--zx-color-on-accent-solid), var(--zx-focus-ring)` (`--zx-color-on-accent` o
452
452
  `--zx-color-accent` fill). Leave the outline transparent rather than removing it: forced colours
453
453
  drop every shadow and paint that outline in the system highlight instead. A product that restyles
454
454
  the ring keeps it one shadow, at least 2px, and at 3:1; to recolour it, set `--zx-color-ring`.
455
+ The ring marks controls only: an element that takes focus without being one carries
456
+ `data-zx-focus` (see **Focus targets** in the tokens reference).
455
457
 
456
458
  **Print.** `zx.css` imports `styles/print.css` last. It releases sticky headers and scroll
457
459
  containers, drops fills, shadows, zebra striping and focus rings, hides overlays and navigation
@@ -2023,6 +2025,9 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
2023
2025
  dialog detached until then, rather than parking it on `<body>` outside the theme.
2024
2026
  - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
2025
2027
  - **Events** — `open`, `close {result}`, `cancel {reason}`.
2028
+ - **Focus** — opening focuses an `autofocus` control, else the first focusable one. A panel with
2029
+ nothing focusable takes focus itself (`tabindex="-1"`, outside the Tab order) and draws no focus
2030
+ ring, keeping its elevation: the panel is a surface, not a control (`data-zx-focus="container"`).
2026
2031
  - **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
2027
2032
  `reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
2028
2033
  action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
@@ -2202,7 +2207,9 @@ DOM child of the anchor's nearest Zx theme scope while the browser lifts it into
2202
2207
  not opened from it) leaves the panel open; nothing below an open modal reacts at all. A panel
2203
2208
  opened from inside another overlay closes with that overlay.
2204
2209
  - **Keyboard** — the panel follows its trigger in the Tab order: Tab on the anchor of an open panel
2205
- moves to the panel's first Tab stop, or onto the panel itself when it has a `tabindex`; Tab past
2210
+ moves to the panel's first Tab stop, or onto the panel itself when it has a `tabindex` of 0 or
2211
+ more (it then shows focus as a region, with the ring inside its edge; a panel only a script
2212
+ focuses draws none); Tab past
2206
2213
  the last stop continues with whatever follows the anchor; Shift+Tab from the first
2207
2214
  stop returns to the anchor. A Tab stop is what the browser itself stops at: a `tabindex="-1"` part
2208
2215
  of a composite (a Select's toggle), a roving toolbar's inactive items, disabled, hidden and inert
@@ -3346,8 +3353,8 @@ can be any registered `Field` type, and its validation may be asynchronous.
3346
3353
  cap on each choice; the caps are `aria-hidden`, since a screen-reader user moves through the
3347
3354
  group with the arrow keys the radios already provide. `Enter` continues, except in a `multiline`
3348
3355
  input. Shortcuts are suppressed while focus is in a text control. Navigating moves focus to the
3349
- new question's fieldset, which is what gets the prompt announced; failing validation moves it to
3350
- the first answer control instead.
3356
+ new question's fieldset, which is what gets the prompt announced (it draws no focus ring: it is
3357
+ not a control); failing validation moves it to the first answer control instead.
3351
3358
  <!-- /doc -->
3352
3359
 
3353
3360
  <!-- doc:value-list -->
@@ -3660,7 +3667,10 @@ detail side of a master–detail screen. Give the root a size of its own (a grid
3660
3667
  a release that added or removed panes.
3661
3668
  - **Keyboard and screen readers** — each pane header is a row, not one big button, so the collapse
3662
3669
  toggle and the tab strip can coexist; the toggle carries `aria-expanded` and `aria-controls`.
3663
- Tabs follow the APG tab pattern with one roving tab stop, Left/Right moving between them.
3670
+ Tabs follow the APG tab pattern with one roving tab stop, Left/Right moving between them. The
3671
+ active panel is a Tab stop itself only while nothing inside it is focusable, with the ring
3672
+ inside its edge, so its text can be read and scrolled; a panel holding a control is not. A scrolling pane
3673
+ body that the browser makes a Tab stop (nothing focusable inside) rings the same way.
3664
3674
  Dividers are focusable `separator`s carrying live `aria-valuenow`/`aria-valuemin`/`aria-valuemax`
3665
3675
  in pixels: Up/Down (or Left/Right when horizontal) resize by 16px, Shift by 64px, and Enter or
3666
3676
  Space collapses the pane before the divider. A divider with nothing to resize is taken out of the
@@ -3699,6 +3709,12 @@ restores rounded corners without forking the stylesheet.
3699
3709
  - **Keyboard** — ArrowLeft/Right and Home/End move focus, Enter/Space activate, Delete closes a
3700
3710
  closable tab. The × is a plain glyph rather than a nested button (buttons cannot nest), so
3701
3711
  keyboard and screen-reader users close through Delete; focus lands on the neighbouring tab.
3712
+ - **Panel focus** — a panel holding a control is not a Tab stop itself, so Tab from the tab list
3713
+ reaches the control. A panel with nothing focusable inside is a Tab stop (`tabindex="0"`), drawn
3714
+ with the ring inside its edge, so its text can be read and scrolled from the keyboard. This is
3715
+ settled whenever a panel is shown and again as Tab leaves the tab list, so content that changes
3716
+ inside a panel is taken into account. Controls inside a custom element's shadow root are not
3717
+ seen, so a panel whose only controls sit there stays a Tab stop as well.
3702
3718
  <!-- /doc -->
3703
3719
 
3704
3720
  <!-- doc:stepper -->
@@ -3920,6 +3936,11 @@ menu on narrow widths.
3920
3936
  `overflow: true`, `overflowBelow: '44rem'`, `minVisible: 0`.
3921
3937
  - **Methods** — `setTitle()`, `setItems()`, `setActive()`, `setBadge()`, `setActions()`.
3922
3938
  - **Events** — `change {name}`.
3939
+ - **Panels** — items that all carry `content` (a Node, a Component, or a factory called on first
3940
+ selection) make the items an APG tab list with a panel each: ArrowLeft/Right and Home/End move
3941
+ focus, Enter/Space select. The active panel is a Tab stop itself only while nothing inside it is
3942
+ focusable, with the ring inside its edge, so its text can be read and scrolled; a panel holding a
3943
+ control is not, and Tab reaches its first control after the bar's own actions.
3923
3944
 
3924
3945
  **Overflow is a default, not a law.** Collapsing every item behind "More" is right for a top app
3925
3946
  bar and wrong for a phone bottom bar, where the navigation is the point. `overflow: false` keeps
@@ -4159,7 +4180,8 @@ the answer arriving.
4159
4180
  blank line starts a new paragraph.
4160
4181
  - **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
4161
4182
  `end` when a streamed answer is marked finished.
4162
- - **Rendering** — code is a figure with its language, a copy button and a focusable `<pre>`
4183
+ - **Rendering** — code is a figure with its language, a copy button and a `<pre>` that is a Tab
4184
+ stop only while a long line scrolls it
4163
4185
  (`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
4164
4186
  code read at length in an inspector),
4165
4187
  coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
@@ -4639,7 +4661,8 @@ announces nothing itself; the thread the run belongs to announces its milestones
4639
4661
  - **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
4640
4662
  not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
4641
4663
  the action at the same index, or the nearest one left. When no action is left the panel itself
4642
- holds focus (`tabindex="-1"`, removed again once focus moves on).
4664
+ holds focus (`tabindex="-1"` with `data-zx-focus="container"`, so no focus ring; both removed
4665
+ again once focus moves on).
4643
4666
  - **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
4644
4667
  update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
4645
4668
  (the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
@@ -4739,6 +4762,10 @@ the application, which owns the conversation and the transport.
4739
4762
  - **Files** — the Attach button, pasting files, and dropping files on the composer (the root shows
4740
4763
  `data-state="dropping"` and a drop label meanwhile) add attachments, filtered by `accept` and
4741
4764
  capped by `maxFiles`.
4765
+ - **Focus** — the box is a tray on the chrome tone; the text inside it is a field with the control
4766
+ edge and fill, and it alone draws the focus ring while it is typed into. The box, the chips, the
4767
+ queue and the bar never light up; Attach, Commands, the tools and Send ring only when they hold
4768
+ the focus themselves.
4742
4769
  - **Accessibility** — the `<textarea>` keeps its textbox role. While suggestions show it carries
4743
4770
  `aria-autocomplete="list"`, `aria-controls` (the listbox) and `aria-activedescendant` (the
4744
4771
  highlighted `role="option"`), and a polite status says how many there are. Attachments and
@@ -4827,8 +4854,8 @@ the answer, and the application carries it out.
4827
4854
  now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
4828
4855
  included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
4829
4856
  `focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
4830
- starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
4831
- dialogs, including an open confirmation).
4857
+ starts waiting; it is a container and draws no focus ring), `handleKey(event)` → `boolean`, and
4858
+ `destroy()` (also destroys the card's dialogs, including an open confirmation).
4832
4859
  - **Update in place** — `update()` is for a request the agent revises while it waits, or a record
4833
4860
  that changed. It redraws only what changed: values equal to what is drawn (compared by content,
4834
4861
  so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
@@ -4912,7 +4939,8 @@ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
4912
4939
  label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
4913
4940
  `icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
4914
4941
  name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
4915
- otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
4942
+ otherwise) and the result or the error, each in a `<pre>` with a copy button, a Tab stop while
4943
+ its text scrolls. A
4916
4944
  `handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
4917
4945
  avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
4918
4946
  model, and an agent author with `face` as its still `AgentAvatar` — and its own label moves to
@@ -5606,4 +5634,24 @@ stays in the tab order, so focusing it shows it. On touch screens, under `prefer
5606
5634
  and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
5607
5635
  that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
5608
5636
  visible. Hosts do not nest.
5637
+
5638
+ **Focus targets.** `.zx-scope` draws the focus ring on whatever matches `:focus-visible`, and
5639
+ Chrome matches any focused element once a key has been pressed — even Shift — so a click into a
5640
+ focusable panel followed by a keystroke would ring the whole panel like a field. An element that
5641
+ takes focus without being a control says which kind it is with `data-zx-focus`:
5642
+ - `data-zx-focus="container"` — only a script focuses it (`tabindex="-1"`, never a Tab stop): a
5643
+ view root that keeps its shortcuts reachable, a heading a route change moves the reader to, a
5644
+ panel holding focus after the control in it went away. It draws no ring and no outline, in forced
5645
+ colours either; its own box-shadow (an overlay's elevation) stays.
5646
+ - `data-zx-focus="region"` — a Tab stop that is not a control: a scroll region the keyboard has to
5647
+ reach, a tab panel with nothing inside to operate. Keyboard focus there stays visible as a ring
5648
+ inside its edge, drawn as an outline so the region's own content cannot cover it; forced colours
5649
+ paint it in the system highlight.
5650
+
5651
+ Set it when the element is created; it only matters while the element has focus. It works on the
5652
+ `.zx-scope` element itself as well as on anything inside it. Zx components
5653
+ mark their own: the Modal, Dialog and Sheet panel, a Dropdown panel only a script focuses, the
5654
+ ApprovalCard and RunStatus roots, Questionnaire's question and review, Surface's verdict and the
5655
+ emptied Table and CardView bodies are containers; tab panels, code blocks, a Dropdown panel with a
5656
+ `tabindex` of 0 or more, and the scroll regions of Table, Dock and MasterPanel are regions.
5609
5657
  <!-- /doc -->
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeyos/zx",
3
- "version": "5.8.1",
3
+ "version": "5.9.0",
4
4
  "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -20,11 +20,6 @@
20
20
  border-color: var(--zx-color-border);
21
21
  }
22
22
 
23
- .zx-approval-card:focus-visible {
24
- outline-color: transparent;
25
- box-shadow: var(--zx-focus-ring);
26
- }
27
-
28
23
  :is(
29
24
  .zx-approval-card__changes,
30
25
  .zx-approval-card__reason,
@@ -281,7 +281,9 @@ export class ApprovalCard extends Component {
281
281
 
282
282
  root.setAttribute('role', 'group');
283
283
  root.setAttribute('aria-labelledby', titleId);
284
+ // Focusable only for a script that brings the reader to the request; never a Tab stop.
284
285
  root.tabIndex = -1;
286
+ root.dataset.zxFocus = 'container';
285
287
 
286
288
  this._titleEl = h(`h${level}`, { class: 'zx-approval-card__title', id: titleId }, this._title);
287
289
  this._noteEl = h('p', { class: 'zx-approval-card__note', id: uid('zx-approval-card-note') });
@@ -89,11 +89,6 @@
89
89
  user-select: none;
90
90
  }
91
91
 
92
- .zx-block-view__pre:focus-visible {
93
- outline-color: transparent;
94
- box-shadow: inset var(--zx-focus-ring);
95
- }
96
-
97
92
  .zx-block-view__token[data-token="keyword"] { color: var(--zx-color-tone-violet-fg); }
98
93
  .zx-block-view__token[data-token="string"] { color: var(--zx-color-tone-green-fg); }
99
94
  .zx-block-view__token[data-token="number"] { color: var(--zx-color-tone-orange-fg); }
@@ -107,11 +102,6 @@
107
102
  overflow-wrap: normal;
108
103
  }
109
104
 
110
- .zx-block-view__table:focus-visible {
111
- outline-color: transparent;
112
- box-shadow: var(--zx-focus-ring);
113
- }
114
-
115
105
  .zx-block-view__table :is(th, td)[data-align="end"] {
116
106
  text-align: end;
117
107
  }
@@ -4,6 +4,7 @@ import { h, restoreTarget, snapshotTarget } from '../../core/dom.js';
4
4
  import { translate } from '../../core/i18n.js';
5
5
  import { icon } from '../../core/icons.js';
6
6
  import { blocksToMarkdown, blocksToText, figureRow, parseInline } from '../../internal/agent-model.js';
7
+ import { syncScrollStop } from '../../internal/focus-stops.js';
7
8
  import { highlight } from '../../internal/highlight.js';
8
9
  import { copyButton } from '../copy/copy-button.js';
9
10
 
@@ -267,7 +268,7 @@ export class BlockView extends Component {
267
268
  this._nodes.push(node);
268
269
  if (this._stoppedNote) this._stoppedNote.before(node);
269
270
  else this.el.append(node);
270
- if (copy.type === 'table') this._syncScrollers();
271
+ if (copy.type === 'table' || copy.type === 'code') this._syncScrollers();
271
272
  }
272
273
 
273
274
  /** @private @returns {void} */
@@ -311,12 +312,16 @@ export class BlockView extends Component {
311
312
  }
312
313
 
313
314
  /**
314
- * A wide table scrolls inside the answer; while it does, its wrapper is a named, focusable
315
- * region so the keyboard can scroll it too. A table that fits is not a tab stop.
315
+ * A wide table or a long code line scrolls inside the answer; while it does, its scroller is a
316
+ * Tab stop so the keyboard can scroll it too — a table's wrapper a named region. One that fits
317
+ * is not a Tab stop.
316
318
  * @private
317
319
  * @returns {void}
318
320
  */
319
321
  _syncScrollers() {
322
+ for (const pre of /** @type {NodeListOf<HTMLElement>} */ (this.el.querySelectorAll('.zx-block-view__pre'))) {
323
+ syncScrollStop(pre);
324
+ }
320
325
  for (const wrap of /** @type {NodeListOf<HTMLElement>} */ (this.el.querySelectorAll('.zx-block-view__table'))) {
321
326
  const overflowing = wrap.scrollWidth > wrap.clientWidth + 1;
322
327
  if (overflowing && !wrap.hasAttribute('tabindex')) {
@@ -459,11 +464,11 @@ function renderCode(block, msg) {
459
464
  h('span', { class: 'zx-block-view__code-language' }, language || msg('blockView.code')),
460
465
  copyButton({ text: String(block.code ?? ''), title: msg('blockView.copyCode'), size: 'sm' })),
461
466
  block.lines
462
- ? h('pre', { class: 'zx-block-view__pre', dataset: { lines: '' }, tabindex: '0' }, h('code', {},
467
+ ? h('pre', { class: 'zx-block-view__pre', dataset: { lines: '', zxFocus: 'region' } }, h('code', {},
463
468
  String(block.code ?? '').split('\n').map((line) => h('span', {
464
469
  class: 'zx-block-view__line', style: { '--zx-block-view-indent': `${/^\s*/.exec(line)?.[0].length ?? 0}ch` }
465
470
  }, codeSegments(language, line)))))
466
- : h('pre', { class: 'zx-block-view__pre', tabindex: '0' }, h('code', {}, codeSegments(language, block.code))));
471
+ : h('pre', { class: 'zx-block-view__pre', dataset: { zxFocus: 'region' } }, h('code', {}, codeSegments(language, block.code))));
467
472
  }
468
473
 
469
474
  /**
@@ -490,7 +495,7 @@ function renderTable(block, cite) {
490
495
  const value = block.align?.[index];
491
496
  return value === 'end' || value === 'center' ? value : null;
492
497
  };
493
- return h('div', { class: 'zx-block-view__table' }, h('table', {},
498
+ return h('div', { class: 'zx-block-view__table', dataset: { zxFocus: 'region' } }, h('table', {},
494
499
  h('thead', {}, h('tr', {}, columns.map((column, index) => h('th', { scope: 'col', dataset: { align: align(index) } },
495
500
  inlineNodes(column, cite))))),
496
501
  h('tbody', {}, rows.map((row) => h('tr', {}, (Array.isArray(row) ? row : []).map((cell, index) => h('td', {
@@ -128,8 +128,11 @@
128
128
  z-index: 1;
129
129
  }
130
130
 
131
+ /* The card rings itself (above); the link adds no second ring of its own. Its outline stays,
132
+ transparent, for forced colours. */
131
133
  .zx-card__primary:focus-visible {
132
134
  outline-color: transparent;
135
+ box-shadow: none;
133
136
  }
134
137
 
135
138
  .zx-card__actions,
@@ -119,11 +119,6 @@
119
119
  box-shadow: inset var(--zx-focus-ring);
120
120
  }
121
121
 
122
- .zx-card-view__content[data-empty-focus]:focus-visible {
123
- outline: 2px solid transparent;
124
- box-shadow: inset var(--zx-focus-ring);
125
- }
126
-
127
122
  @media (prefers-reduced-motion: no-preference) {
128
123
  .zx-card-view__group-toggle > .zx-icon {
129
124
  transition: transform var(--zx-dur-fast) var(--zx-ease);
@@ -178,6 +173,11 @@
178
173
  box-shadow: var(--zx-focus-ring);
179
174
  }
180
175
 
176
+ /* A loading placeholder only ever holds focus for the view; it is no card to ring. */
177
+ .zx-record-card.zx-card-view__skeleton:focus-visible {
178
+ box-shadow: none;
179
+ }
180
+
181
181
  /* A selected card is a pick, so it keeps the accent — as a tint over the card and its outline,
182
182
  not a doubled frame. */
183
183
  .zx-record-card[data-selected="true"] {
@@ -576,11 +576,13 @@ export class CardView extends RecordView {
576
576
  if (!content.hasAttribute('tabindex')) {
577
577
  content.tabIndex = -1;
578
578
  content.setAttribute('data-empty-focus', '');
579
+ content.setAttribute('data-zx-focus', 'container');
579
580
  }
580
581
  content.focus({ preventScroll: true });
581
582
  } else if (content.hasAttribute('data-empty-focus')) {
582
583
  content.removeAttribute('tabindex');
583
584
  content.removeAttribute('data-empty-focus');
585
+ content.removeAttribute('data-zx-focus');
584
586
  }
585
587
  }
586
588
 
@@ -701,7 +703,7 @@ export class CardView extends RecordView {
701
703
  ariaHidden: 'true'
702
704
  });
703
705
  for (let index = 0; index < this._cardLoadingCount; index += 1) {
704
- list.append(h('li', { class: 'zx-record-card zx-card-view__skeleton', tabindex: -1 },
706
+ list.append(h('li', { class: 'zx-record-card zx-card-view__skeleton', tabindex: -1, dataset: { zxFocus: 'container' } },
705
707
  h('span', { class: 'zx-card-view__skeleton-preview zx-skeleton' }),
706
708
  h('span', { class: 'zx-card-view__skeleton-line zx-skeleton' }),
707
709
  h('span', { class: 'zx-card-view__skeleton-line zx-skeleton' }),
@@ -1,7 +1,9 @@
1
1
  /*
2
2
  * Composer — the message box of an agent conversation. A filled box on the chrome tone with no
3
- * frame of its own: the context and attachment chips, the text, and a bar of quiet tools ending in
4
- * Send. Focus in the text rings the whole box. The `@` suggestions open above it, in the top layer.
3
+ * frame of its own: a tray holding the context and attachment chips, the text, and a bar of quiet
4
+ * tools ending in Send. The text is a field with its own edge, and it alone draws the focus ring
5
+ * while it is typed into; the tray, the chips and the bar never light up. The `@` suggestions open
6
+ * above it, in the top layer.
5
7
  */
6
8
  .zx-composer {
7
9
  position: relative;
@@ -13,36 +15,34 @@
13
15
  .zx-composer__frame {
14
16
  position: relative;
15
17
  display: grid;
16
- gap: var(--zx-space-1);
18
+ gap: var(--zx-space-2);
17
19
  min-inline-size: 0;
18
- padding: var(--zx-space-2) var(--zx-space-3);
20
+ padding: var(--zx-space-2);
19
21
  border-radius: var(--zx-radius-lg);
20
22
  background: var(--zx-color-bg-chrome);
21
23
  color: var(--zx-color-text);
22
24
  }
23
25
 
24
- .zx-composer__frame:has(.zx-composer__input:focus) {
25
- box-shadow: var(--zx-focus-ring);
26
- }
27
-
28
26
  .zx-composer[aria-disabled="true"] .zx-composer__frame {
29
27
  opacity: 0.6;
30
28
  }
31
29
 
32
30
  /* ------------------------------------------------------------------ text -- */
33
31
 
32
+ /* The text is drawn as any text area is — the control edge, fill and radius, its padding — so the
33
+ box reads as a tray around a field. Focused, it takes the shared ring from the base styles; a
34
+ quiet-fields region does not take its edge away. */
34
35
  .zx-composer .zx-composer__input {
35
36
  display: block;
36
37
  inline-size: 100%;
37
38
  min-block-size: 0;
38
39
  margin: 0;
39
- padding: var(--zx-space-1);
40
+ padding: var(--zx-space-2) var(--zx-control-pad-x);
40
41
  overflow-y: hidden;
41
- border: 0;
42
- border-radius: 0;
43
- background: transparent;
44
- box-shadow: none;
45
- color: inherit;
42
+ border: 1px solid var(--zx-color-border-control);
43
+ border-radius: var(--zx-control-radius);
44
+ background: var(--zx-color-bg-control);
45
+ color: var(--zx-color-text);
46
46
  font: inherit;
47
47
  font-size: var(--zx-text-md);
48
48
  line-height: 1.5;
@@ -57,12 +57,6 @@
57
57
  color: var(--zx-color-text-placeholder);
58
58
  }
59
59
 
60
- /* The box draws the ring; the text inside it draws none of its own. */
61
- .zx-composer .zx-composer__input:is(:focus, :focus-visible) {
62
- outline-color: transparent;
63
- box-shadow: none;
64
- }
65
-
66
60
  .zx-composer .zx-composer__input:disabled {
67
61
  cursor: not-allowed;
68
62
  }
@@ -77,7 +71,6 @@
77
71
  align-items: center;
78
72
  gap: var(--zx-space-1);
79
73
  min-inline-size: 0;
80
- margin-inline-start: calc(-1 * var(--zx-space-1));
81
74
  }
82
75
 
83
76
  .zx-composer__tools {
@@ -224,7 +217,7 @@
224
217
  flex-wrap: wrap;
225
218
  gap: var(--zx-space-2);
226
219
  margin: 0;
227
- padding: var(--zx-space-1) 0 0;
220
+ padding: 0;
228
221
  list-style: none;
229
222
  }
230
223
 
@@ -478,8 +471,4 @@
478
471
  background-color var(--zx-dur-fast) var(--zx-ease),
479
472
  color var(--zx-dur-fast) var(--zx-ease);
480
473
  }
481
-
482
- .zx-composer__frame {
483
- transition: box-shadow var(--zx-dur-fast) var(--zx-ease);
484
- }
485
474
  }
@@ -36,7 +36,9 @@
36
36
  background: var(--zx-color-bg-control);
37
37
  }
38
38
 
39
- .zx-copy-input__box:focus-within {
39
+ /* The box is the field's edge, so it rings while the field has focus; the Copy button inside it
40
+ rings itself, and the box stays quiet then. */
41
+ .zx-copy-input__box:has(.zx-copy-input__field:focus) {
40
42
  border-color: var(--zx-color-accent);
41
43
  box-shadow: var(--zx-focus-ring);
42
44
  }
@@ -134,7 +134,8 @@ export class Dialog extends Modal {
134
134
  const close = this._message('dialog.close', 'Close');
135
135
  const dialog = /** @type {HTMLDialogElement} */ (h('dialog', {
136
136
  class: 'zx-modal zx-dialog',
137
- ariaLabelledby: titleId
137
+ ariaLabelledby: titleId,
138
+ dataset: { zxFocus: 'container' }
138
139
  },
139
140
  h('header', { class: 'zx-dialog__header' },
140
141
  h('h2', { class: 'zx-dialog__title', id: titleId, ref: 'title' }),
@@ -171,12 +171,6 @@
171
171
  block-size: 100%;
172
172
  }
173
173
 
174
- .zx-dock__panel:focus-visible {
175
- outline-color: transparent;
176
- outline-offset: -2px;
177
- box-shadow: inset var(--zx-focus-ring);
178
- }
179
-
180
174
  /*
181
175
  * The hit area is thicker than the line it draws, so the divider is grabbable without a visible
182
176
  * gutter — the same trade SplitView makes.