@zeyos/zx 5.8.0 → 5.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/CHANGELOG.md +93 -0
  2. package/dist/types/components/block-view/block-view.d.ts +3 -2
  3. package/dist/types/components/check-button/check-button.d.ts +10 -2
  4. package/dist/types/components/checklist/checklist.d.ts +28 -6
  5. package/dist/types/components/code-editor/code-editor.d.ts +19 -1
  6. package/dist/types/components/dock/dock.d.ts +2 -1
  7. package/dist/types/components/dropdown/dropdown.d.ts +2 -1
  8. package/dist/types/components/field-upload/field-upload.d.ts +6 -0
  9. package/dist/types/components/filter-panel/filter-panel.d.ts +6 -2
  10. package/dist/types/components/module-bar/module-bar.d.ts +53 -2
  11. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +28 -0
  12. package/dist/types/components/run-status/run-status.d.ts +1 -1
  13. package/dist/types/components/run-trace/run-trace.d.ts +8 -0
  14. package/dist/types/components/select/select.d.ts +18 -5
  15. package/dist/types/components/tabbox/tabbox.d.ts +7 -0
  16. package/dist/types/components/tag-picker/tag-picker.d.ts +21 -5
  17. package/dist/types/components/timebox/timebox.d.ts +9 -0
  18. package/dist/types/core/component.d.ts +4 -1
  19. package/dist/types/internal/focus-stops.d.ts +42 -0
  20. package/dist/zx-zeyos.esm.js +296 -97
  21. package/dist/zx-zeyos.esm.min.js +4 -4
  22. package/dist/zx.core.css +13 -6
  23. package/dist/zx.core.min.css +1 -1
  24. package/dist/zx.css +26 -88
  25. package/dist/zx.esm.js +516 -159
  26. package/dist/zx.esm.min.js +26 -26
  27. package/dist/zx.global.js +516 -159
  28. package/dist/zx.global.min.js +26 -26
  29. package/dist/zx.layered.css +26 -88
  30. package/dist/zx.layered.min.css +1 -1
  31. package/dist/zx.min.css +1 -1
  32. package/docs/api.json +97 -9
  33. package/docs/components/approval-card.md +2 -2
  34. package/docs/components/block-view.md +2 -1
  35. package/docs/components/check-button.md +3 -1
  36. package/docs/components/checklist.md +2 -1
  37. package/docs/components/code-editor.md +4 -3
  38. package/docs/components/composer.md +4 -0
  39. package/docs/components/dock.md +4 -1
  40. package/docs/components/dropdown.md +3 -1
  41. package/docs/components/field-upload.md +2 -1
  42. package/docs/components/modal.md +3 -0
  43. package/docs/components/multi-value-editor.md +5 -2
  44. package/docs/components/navigation-bar.md +5 -0
  45. package/docs/components/questionnaire.md +2 -2
  46. package/docs/components/run-status.md +2 -1
  47. package/docs/components/run-trace.md +2 -1
  48. package/docs/components/select.md +6 -2
  49. package/docs/components/tabbox.md +6 -0
  50. package/docs/components/tag-picker.md +3 -1
  51. package/docs/components/timebox.md +2 -1
  52. package/docs/components/tokens.md +20 -0
  53. package/docs/llms.md +84 -21
  54. package/package.json +1 -1
  55. package/src/components/app-sidebar/app-sidebar.js +1 -1
  56. package/src/components/approval-card/approval-card.css +0 -5
  57. package/src/components/approval-card/approval-card.js +2 -0
  58. package/src/components/block-view/block-view.css +0 -10
  59. package/src/components/block-view/block-view.js +11 -6
  60. package/src/components/card/card.css +3 -0
  61. package/src/components/card/card.js +2 -2
  62. package/src/components/card-view/card-view.css +5 -5
  63. package/src/components/card-view/card-view.js +3 -1
  64. package/src/components/check-button/check-button.js +5 -1
  65. package/src/components/checklist/checklist.js +26 -10
  66. package/src/components/checklist/field-adapter.js +5 -13
  67. package/src/components/code-editor/code-editor.js +24 -3
  68. package/src/components/composer/composer.css +15 -26
  69. package/src/components/copy/copy-input.css +3 -1
  70. package/src/components/dialog/dialog.js +2 -1
  71. package/src/components/dock/dock.css +0 -6
  72. package/src/components/dock/dock.js +22 -7
  73. package/src/components/dropdown/dropdown.js +17 -2
  74. package/src/components/field/field.js +2 -1
  75. package/src/components/field-upload/field-upload.js +15 -0
  76. package/src/components/filter-panel/filter-panel.js +8 -11
  77. package/src/components/master-panel/master-panel.js +3 -1
  78. package/src/components/modal/modal.css +2 -11
  79. package/src/components/modal/modal.js +5 -2
  80. package/src/components/module-bar/module-bar.js +110 -26
  81. package/src/components/multi-value-editor/field-adapter.js +8 -23
  82. package/src/components/multi-value-editor/multi-value-editor.js +63 -5
  83. package/src/components/navigation-bar/navigation-bar.css +0 -4
  84. package/src/components/navigation-bar/navigation-bar.js +11 -2
  85. package/src/components/questionnaire/questionnaire.css +0 -14
  86. package/src/components/questionnaire/questionnaire.js +4 -2
  87. package/src/components/run-status/run-status.css +0 -7
  88. package/src/components/run-status/run-status.js +3 -1
  89. package/src/components/run-trace/run-trace.css +0 -5
  90. package/src/components/run-trace/run-trace.js +23 -2
  91. package/src/components/select/select.js +43 -5
  92. package/src/components/skeleton/skeleton.js +16 -3
  93. package/src/components/surface/surface.css +0 -6
  94. package/src/components/surface/surface.js +1 -1
  95. package/src/components/tabbox/tabbox.css +0 -6
  96. package/src/components/tabbox/tabbox.js +20 -2
  97. package/src/components/table/table.js +5 -0
  98. package/src/components/tag-picker/tag-picker.js +35 -6
  99. package/src/components/timebox/timebox.js +17 -1
  100. package/src/components/view-settings/view-settings.js +1 -1
  101. package/src/core/component.js +22 -2
  102. package/src/core/date.js +1 -4
  103. package/src/core/drag-axis.js +22 -6
  104. package/src/internal/focus-stops.js +108 -0
  105. package/src/zeyos/connect.js +7 -3
  106. package/src/zeyos/icons.js +7 -2
  107. package/styles/base.css +27 -3
  108. package/styles/tokens/dark.css +2 -2
  109. package/styles/tokens/semantic.css +2 -2
package/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
@@ -1135,7 +1137,9 @@ reads as a two-state control. Pressed, the button goes neutral (the `--zx-color-
1135
1137
  a stronger border, the text colour); only the check glyph, the mark, keeps the accent.
1136
1138
 
1137
1139
  - **Options** — `label: '' | [onLabel, offLabel]`, `checked: false`, `icon: true`,
1138
- `disabled: false`.
1140
+ `disabled: false`. Prefer one label: the pressed state is announced already, and a name that
1141
+ changes with it is read twice over, which the APG toggle-button pattern advises against; an
1142
+ on/off setting reads better as a Toggle.
1139
1143
  - **Methods** — `get()`, `set(checked, {silent})`, `toggle()`, `setLabel()`, `enable()`/`disable()`.
1140
1144
  - **Events** — `change {checked}`, fired only on a real state change.
1141
1145
  - **Keyboard** — Space/Enter.
@@ -1560,8 +1564,12 @@ Unifies single-select, local filtering, and async loading.
1560
1564
  `labelKey: 'name'` (string or `(item)=>string`), `renderItem`, `renderValue`,
1561
1565
  `renderValueAdornment`, `renderNone`, `noneLabel`, `actions`, `value`, `disabled`, `placeholder`,
1562
1566
  `label` (accessible combobox name; defaults to the placeholder or "Select"),
1563
- `clearable: false`, `filter: false | 'local' | async (query)=>items`, `searchKeys`,
1567
+ `clearable: false`, `filter: false | 'local' | async (query, {signal})=>items`, `searchKeys`,
1564
1568
  `minQuery: 0`, `debounce: 200`, `listHeight: 280`, `groupKey`.
1569
+ - **Async filter** — the function's second argument carries an `AbortSignal` that aborts once the
1570
+ answer would be ignored: a newer query starts, the list closes (or the Select is disabled), or the
1571
+ Select is destroyed. Pass it on (`fetch(url, { signal })`) to cancel the request; a late result
1572
+ is discarded either way.
1565
1573
  - **Getters** — `.value`, `.selected`.
1566
1574
  - **Methods** — `get()` (the same as `.value`), `set(id, {silent})`, `setItems()`,
1567
1575
  `setFixedItems()`, `setActions()`, `reset()`, `open()`/`close()`, `enable()`/`disable()`,
@@ -1582,7 +1590,7 @@ Unifies single-select, local filtering, and async loading.
1582
1590
  and accepts replacement `items` (each `{ID, name, indicator, tone, description?, shortcut?}`);
1583
1591
  `Select.permission(target, {groups, value})` pins Private and
1584
1592
  Public above record-access groups. Its value is the tri-state ZeyOS stores (`false` private,
1585
- `true` public, or a group ID), and `groups` takes an array or loader `(query)=>items`.
1593
+ `true` public, or a group ID), and `groups` takes an array or loader `(query, {signal})=>items`.
1586
1594
  - **Glyphs** — `statusIcon(status, {tone?, indicator?, label?})` and `priorityIcon(level, {label?})`
1587
1595
  return the exact glyphs the two presets draw (`.zx-status-icon`, `.zx-priority-icon`; inside a
1588
1596
  Select they also carry `.zx-select__status-indicator` / `.zx-select__priority-icon`), for list
@@ -1711,7 +1719,8 @@ Searchable multi-check list with optional async loading.
1711
1719
  the heading; the group keeps its text as `aria-label`), `load: async ()=>items`.
1712
1720
  - **In a Field** — field type `checklist` draws no heading of its own: the field's label names the
1713
1721
  group (`aria-labelledby`).
1714
- - **Methods** — `setItems()`, `getValues()`, `setValues(ids)`, `checkAll()`/`uncheckAll()`,
1722
+ - **Methods** — `setItems()`, `getValues()`, `setValues(ids, {silent})`,
1723
+ `checkAll({silent})`/`uncheckAll({silent})` (`silent` updates the boxes without a `change`),
1715
1724
  `search(query)`, `reload()`, `setLabel(text)`, `enable()`/`disable()`, `isDisabled()`. Disabled,
1716
1725
  the search field and every checkbox are disabled (`aria-disabled="true"` on the group) through
1717
1726
  searches, `setItems()` and reloads; values can still be set from code.
@@ -1921,7 +1930,8 @@ use `TimePicker` or `DateTimeBox`.
1921
1930
 
1922
1931
  - **Options** — `value: 0`, `unit: 'minutes'|'seconds'|'hours'`, `seconds: false`, `signed: false`,
1923
1932
  `disabled`.
1924
- - **Methods** — `get(unit)`, `set(value, unit?, {silent})`, `enable()`/`disable()`.
1933
+ - **Methods** — `get(unit)`, `set(value, unit?, {silent})`, `focus()` (the hours segment),
1934
+ `enable()`/`disable()`.
1925
1935
  - **Events** — `change {value}`, in `options.unit`.
1926
1936
  - **Also exported** — the pure helpers `splitTime` and `joinTime`.
1927
1937
  - **Quiet fields** — inside `[data-zx-fields="quiet"]` the segments (native inputs) and the sign
@@ -2015,6 +2025,9 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
2015
2025
  dialog detached until then, rather than parking it on `<body>` outside the theme.
2016
2026
  - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
2017
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"`).
2018
2031
  - **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
2019
2032
  `reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
2020
2033
  action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
@@ -2194,7 +2207,9 @@ DOM child of the anchor's nearest Zx theme scope while the browser lifts it into
2194
2207
  not opened from it) leaves the panel open; nothing below an open modal reacts at all. A panel
2195
2208
  opened from inside another overlay closes with that overlay.
2196
2209
  - **Keyboard** — the panel follows its trigger in the Tab order: Tab on the anchor of an open panel
2197
- 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
2198
2213
  the last stop continues with whatever follows the anchor; Shift+Tab from the first
2199
2214
  stop returns to the anchor. A Tab stop is what the browser itself stops at: a `tabindex="-1"` part
2200
2215
  of a composite (a Select's toggle), a roving toolbar's inactive items, disabled, hidden and inert
@@ -3201,9 +3216,10 @@ stays a separate policy decision.
3201
3216
  - **Options** — `value`, `name`, `language` (shown to the reader and exposed as data),
3202
3217
  `label`, `placeholder`, `rows` (clamped 2–100), `indent: '\t'` (inserted by Tab, removed by
3203
3218
  Shift+Tab; `' '` for two spaces, `''` to leave Tab alone), `wrap: 'off'|'soft'|'hard'`,
3204
- `spellcheck`, `readOnly`, `disabled`, `status` (the line/column readout).
3205
- - **Methods** — `setValue()`, `getValue()`, `setLanguage()`, `setReadOnly()`,
3206
- `enable()`/`disable()`, `getInput()` (the
3219
+ `spellcheck`, `readOnly` (also spelled `readonly`, as on every other control; either one set to
3220
+ true makes the editor read-only), `disabled`, `status` (the line/column readout).
3221
+ - **Methods** — `setValue()`, `getValue()`, `setLanguage()`, `setReadOnly()` (also spelled
3222
+ `setReadonly()`), `enable()`/`disable()`, `getInput()` (the
3207
3223
  native textarea: the element that carries the name, validity and description, and the one a
3208
3224
  `<label for>` names), `setHighlight(message, kind = 'danger')`, `clearHighlight()`, `focus()`.
3209
3225
  - **Events** — `input {value}`, `change {value}`, `invalid {message}`.
@@ -3337,8 +3353,8 @@ can be any registered `Field` type, and its validation may be asynchronous.
3337
3353
  cap on each choice; the caps are `aria-hidden`, since a screen-reader user moves through the
3338
3354
  group with the arrow keys the radios already provide. `Enter` continues, except in a `multiline`
3339
3355
  input. Shortcuts are suppressed while focus is in a text control. Navigating moves focus to the
3340
- new question's fieldset, which is what gets the prompt announced; failing validation moves it to
3341
- 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.
3342
3358
  <!-- /doc -->
3343
3359
 
3344
3360
  <!-- doc:value-list -->
@@ -3361,8 +3377,11 @@ Ordered value editor with explicit rows (add / remove / move).
3361
3377
 
3362
3378
  - **Options** — `values`, `options` (allowed values, which turns the rows into selects),
3363
3379
  `addLabel`, `reorder: 'both'` (`'both'` | `'buttons'` | `'drag'` | `'none'` — a drag handle, the
3364
- up/down buttons, both, or neither).
3365
- - **Methods** — `getValues()`, `setValues()`.
3380
+ up/down buttons, both, or neither), `disabled: false`.
3381
+ - **Methods** — `getValues()`, `setValues(values, {silent})`, `setDisabled(bool)`,
3382
+ `enable()`/`disable()`, `isDisabled()`. Disabled, every value input or select, handle, move and
3383
+ remove button and the add button is disabled (`aria-disabled="true"` on the root) and nothing
3384
+ reorders; values can still be set from code.
3366
3385
  - **Events** — `change {values}`.
3367
3386
  - Dragging goes through a dedicated handle, so text selection inside a row's input still works. The
3368
3387
  handle is also a keyboard control (Arrow keys, Home, End), which is what keeps `reorder: 'drag'`
@@ -3381,7 +3400,8 @@ Aborted uploads ignore late progress and success callbacks.
3381
3400
 
3382
3401
  - **Options** — `url`, `paramName: 'upload'`, `params`, `headers`, `multiple: false`, `accept`,
3383
3402
  `maxSize`, `autoUpload: true`, `preview: true`, `http`.
3384
- - **Methods** — `upload(files?)`, `abort()`, `clear()`, `setDisabled()`.
3403
+ - **Methods** — `upload(files?)`, `abort()`, `clear()`, `setDisabled(bool)`,
3404
+ `enable()`/`disable()`, `isDisabled()`.
3385
3405
  - **Events** — `select {files}`, `progress {percent}`, `success {response}`, `error {error}`,
3386
3406
  `abort`.
3387
3407
  <!-- /doc -->
@@ -3397,7 +3417,9 @@ yet. Field type: `tagpicker`.
3397
3417
 
3398
3418
  - **Options** — `items`, `values: []`, `valueKey: 'ID'`, `labelKey: 'name'`, `iconKey: 'icon'`,
3399
3419
  `colorKey: 'color'`, `toneKey: 'tone'`, `searchKeys`,
3400
- `filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
3420
+ `filter: 'local'|(query, {signal})=>Promise<items>` (the signal aborts when a newer query
3421
+ starts, the list closes, `setItems()` replaces the catalogue, or the picker is destroyed; a late
3422
+ result is discarded either way), `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
3401
3423
  `max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
3402
3424
  `placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
3403
3425
  - **Tags are Badges** — every selected tag is built by `badge()` (`.zx-badge.zx-tag-picker__tag`):
@@ -3645,7 +3667,10 @@ detail side of a master–detail screen. Give the root a size of its own (a grid
3645
3667
  a release that added or removed panes.
3646
3668
  - **Keyboard and screen readers** — each pane header is a row, not one big button, so the collapse
3647
3669
  toggle and the tab strip can coexist; the toggle carries `aria-expanded` and `aria-controls`.
3648
- 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.
3649
3674
  Dividers are focusable `separator`s carrying live `aria-valuenow`/`aria-valuemin`/`aria-valuemax`
3650
3675
  in pixels: Up/Down (or Left/Right when horizontal) resize by 16px, Shift by 64px, and Enter or
3651
3676
  Space collapses the pane before the divider. A divider with nothing to resize is taken out of the
@@ -3684,6 +3709,12 @@ restores rounded corners without forking the stylesheet.
3684
3709
  - **Keyboard** — ArrowLeft/Right and Home/End move focus, Enter/Space activate, Delete closes a
3685
3710
  closable tab. The × is a plain glyph rather than a nested button (buttons cannot nest), so
3686
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.
3687
3718
  <!-- /doc -->
3688
3719
 
3689
3720
  <!-- doc:stepper -->
@@ -3905,6 +3936,11 @@ menu on narrow widths.
3905
3936
  `overflow: true`, `overflowBelow: '44rem'`, `minVisible: 0`.
3906
3937
  - **Methods** — `setTitle()`, `setItems()`, `setActive()`, `setBadge()`, `setActions()`.
3907
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.
3908
3944
 
3909
3945
  **Overflow is a default, not a law.** Collapsing every item behind "More" is right for a top app
3910
3946
  bar and wrong for a phone bottom bar, where the navigation is the point. `overflow: false` keeps
@@ -4144,7 +4180,8 @@ the answer arriving.
4144
4180
  blank line starts a new paragraph.
4145
4181
  - **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
4146
4182
  `end` when a streamed answer is marked finished.
4147
- - **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
4148
4185
  (`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
4149
4186
  code read at length in an inspector),
4150
4187
  coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
@@ -4624,7 +4661,8 @@ announces nothing itself; the thread the run belongs to announces its milestones
4624
4661
  - **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
4625
4662
  not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
4626
4663
  the action at the same index, or the nearest one left. When no action is left the panel itself
4627
- 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).
4628
4666
  - **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
4629
4667
  update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
4630
4668
  (the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
@@ -4724,6 +4762,10 @@ the application, which owns the conversation and the transport.
4724
4762
  - **Files** — the Attach button, pasting files, and dropping files on the composer (the root shows
4725
4763
  `data-state="dropping"` and a drop label meanwhile) add attachments, filtered by `accept` and
4726
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.
4727
4769
  - **Accessibility** — the `<textarea>` keeps its textbox role. While suggestions show it carries
4728
4770
  `aria-autocomplete="list"`, `aria-controls` (the listbox) and `aria-activedescendant` (the
4729
4771
  highlighted `role="option"`), and a polite status says how many there are. Attachments and
@@ -4812,8 +4854,8 @@ the answer, and the application carries it out.
4812
4854
  now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
4813
4855
  included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
4814
4856
  `focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
4815
- starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
4816
- 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).
4817
4859
  - **Update in place** — `update()` is for a request the agent revises while it waits, or a record
4818
4860
  that changed. It redraws only what changed: values equal to what is drawn (compared by content,
4819
4861
  so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
@@ -4897,7 +4939,8 @@ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
4897
4939
  label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
4898
4940
  `icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
4899
4941
  name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
4900
- 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
4901
4944
  `handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
4902
4945
  avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
4903
4946
  model, and an agent author with `face` as its still `AgentAvatar` — and its own label moves to
@@ -5591,4 +5634,24 @@ stays in the tab order, so focusing it shows it. On touch screens, under `prefer
5591
5634
  and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
5592
5635
  that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
5593
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.
5594
5657
  <!-- /doc -->
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeyos/zx",
3
- "version": "5.8.0",
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",
@@ -937,7 +937,7 @@ export class AppSidebar extends Component {
937
937
 
938
938
  /** @param {EventTarget} target @param {string} type @param {EventListener} listener @returns {void} */
939
939
  _listenMode(target, type, listener) {
940
- target.addEventListener(type, listener, { signal: this._modeAbort.signal });
940
+ this.listen(target, type, listener, { signal: this._modeAbort.signal });
941
941
  }
942
942
 
943
943
  /** @returns {void} */
@@ -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,
@@ -158,7 +158,7 @@ export class Card extends Component {
158
158
  if (onclick !== undefined && typeof onclick !== 'function') {
159
159
  throw new TypeError('Card action onclick must be a function');
160
160
  }
161
- if (onclick) control.addEventListener('click', onclick, { signal: nextAbort.signal });
161
+ if (onclick) this.listen(control, 'click', onclick, { signal: nextAbort.signal });
162
162
  return control;
163
163
  });
164
164
  } catch (error) {
@@ -210,7 +210,7 @@ export class Card extends Component {
210
210
  target: this._link.target,
211
211
  rel: this._link.rel
212
212
  }, title) : h('span', { class: 'zx-card__title' }, title);
213
- if (this._link?.onclick) node.addEventListener('click', this._link.onclick, { signal: nextAbort.signal });
213
+ if (this._link?.onclick) this.listen(node, 'click', this._link.onclick, { signal: nextAbort.signal });
214
214
  this._linkAbort?.abort();
215
215
  this._linkAbort = nextAbort;
216
216
  this.refs.heading.replaceChildren(node);
@@ -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' }),
@@ -4,7 +4,11 @@ import { ICON_SIZE, icon } from '../../core/icons.js';
4
4
 
5
5
  /**
6
6
  * @typedef {Object} CheckButtonOptions
7
- * @property {string|[string, string]} [label=''] A shared label or `[onLabel, offLabel]`.
7
+ * @property {string|[string, string]} [label=''] A shared label or `[onLabel, offLabel]`. Prefer one
8
+ * label: the button is announced as pressed or not, and the APG toggle-button pattern advises
9
+ * against a name that changes with the state, which a screen reader then reads twice over
10
+ * ("Disabled, toggle button, not pressed"). A pair suits a visible state word only where that
11
+ * repetition is acceptable; for an on/off setting a Toggle reads better.
8
12
  * @property {boolean} [checked=false] Initial pressed state.
9
13
  * @property {boolean} [icon=true] Whether to show the check indicator.
10
14
  * @property {boolean} [disabled=false] Initial disabled state.
@@ -25,6 +25,10 @@ import { matchItems } from '../select/filter.js';
25
25
  * @property {(event: CustomEvent<ChecklistLoadedDetail>) => void} [onloaded] Loaded listener.
26
26
  */
27
27
  /** @typedef {{values: unknown[]}} ChecklistChangeDetail */
28
+ /**
29
+ * @typedef {Object} ChecklistSetOptions
30
+ * @property {boolean} [silent=false] Update the checked state without emitting `change`.
31
+ */
28
32
  /** @typedef {{items: ChecklistItem[]}} ChecklistLoadedDetail */
29
33
 
30
34
  /**
@@ -176,29 +180,40 @@ export class Checklist extends Component {
176
180
  * and checked as soon as items carrying them arrive — through `setItems()` or the `load`
177
181
  * loader — so a value set before the items load is not lost.
178
182
  * @param {Iterable<unknown>|unknown[]} ids Checked item IDs.
183
+ * @param {ChecklistSetOptions} [options={}] Set `silent` to suppress `change`.
179
184
  * @returns {this}
180
185
  * @fires Checklist#change
181
186
  */
182
- setValues(ids) {
187
+ setValues(ids, { silent = false } = {}) {
183
188
  const requested = new Set(ids == null ? [] : Array.from(ids));
184
189
  const known = new Set(this._items.map((item) => this._itemValue(item)));
185
190
  const next = new Set([...known].filter((value) => requested.has(value)));
186
191
  const missing = [...requested].filter((value) => !known.has(value));
187
192
  // Before any item exists the request stands for the items still to come — an empty one too —
188
193
  // in place of their own checked flags.
189
- this._replaceChecked(next, missing.length || this._items.length === 0 ? missing : null);
194
+ this._replaceChecked(next, missing.length || this._items.length === 0 ? missing : null, silent);
190
195
  return this;
191
196
  }
192
197
 
193
- /** Checks every item. @returns {this} @fires Checklist#change */
194
- checkAll() {
195
- this._replaceChecked(new Set(this._items.map((item) => this._itemValue(item))), null);
198
+ /**
199
+ * Checks every item.
200
+ * @param {ChecklistSetOptions} [options={}] Set `silent` to suppress `change`.
201
+ * @returns {this}
202
+ * @fires Checklist#change
203
+ */
204
+ checkAll({ silent = false } = {}) {
205
+ this._replaceChecked(new Set(this._items.map((item) => this._itemValue(item))), null, silent);
196
206
  return this;
197
207
  }
198
208
 
199
- /** Unchecks every item. @returns {this} @fires Checklist#change */
200
- uncheckAll() {
201
- this._replaceChecked(new Set(), null);
209
+ /**
210
+ * Unchecks every item.
211
+ * @param {ChecklistSetOptions} [options={}] Set `silent` to suppress `change`.
212
+ * @returns {this}
213
+ * @fires Checklist#change
214
+ */
215
+ uncheckAll({ silent = false } = {}) {
216
+ this._replaceChecked(new Set(), null, silent);
202
217
  return this;
203
218
  }
204
219
 
@@ -319,9 +334,10 @@ export class Checklist extends Component {
319
334
  * @param {Set<unknown>} next
320
335
  * @param {unknown[]|null} pending Requested IDs no item carries yet, or null when no request waits
321
336
  * for items; an empty array is a request made before any item existed.
337
+ * @param {boolean} [silent=false] Whether to leave out the `change` event.
322
338
  * @returns {void}
323
339
  */
324
- _replaceChecked(next, pending) {
340
+ _replaceChecked(next, pending, silent = false) {
325
341
  const nextPending = pending;
326
342
  const pendingChanged = !setsEqual(new Set(this._pending ?? []), new Set(nextPending ?? []));
327
343
  const unchanged = setsEqual(this._checked, next) && !pendingChanged;
@@ -329,7 +345,7 @@ export class Checklist extends Component {
329
345
  if (unchanged) return;
330
346
  this._checked = next;
331
347
  this._renderItems();
332
- this.emit('change', { values: this.getValues() });
348
+ if (!silent) this.emit('change', { values: this.getValues() });
333
349
  }
334
350
 
335
351
  /** @param {ChecklistItem} item @returns {unknown} */
@@ -10,24 +10,16 @@ export function registerChecklistFieldAdapter() {
10
10
  // The Field's label names the list (`aria-labelledby`), so the checklist draws no heading of
11
11
  // its own under it.
12
12
  const checklist = field.own(new Checklist(null, { hideLabel: true, ...(options.props ?? {}) }));
13
- let setting = false;
14
13
  field.listen(checklist.el, 'change', (event) => event.stopImmediatePropagation());
15
- checklist.on('change', (event) => {
16
- if (!setting) field.emit('change', { value: event.detail.values });
17
- });
14
+ checklist.on('change', (event) => field.emit('change', { value: event.detail.values }));
18
15
  return {
19
16
  el: checklist.el,
20
17
  get: () => checklist.getValues(),
21
18
  set: (value) => {
22
- setting = true;
23
- try {
24
- // An array is the value, an empty one included; anything else — the Field's '' when no
25
- // value was given — clears what is shown and leaves items still to load their own flags.
26
- if (Array.isArray(value)) checklist.setValues(value);
27
- else checklist.uncheckAll();
28
- } finally {
29
- setting = false;
30
- }
19
+ // An array is the value, an empty one included; anything else — the Field's '' when no
20
+ // value was given — clears what is shown and leaves items still to load their own flags.
21
+ if (Array.isArray(value)) checklist.setValues(value, { silent: true });
22
+ else checklist.uncheckAll({ silent: true });
31
23
  },
32
24
  focus: () => {
33
25
  const search = checklist.el.querySelector('.zx-checklist__search:not([hidden]):not([disabled])');