@zeyos/zx 5.4.0 → 5.6.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.
- package/CHANGELOG.md +136 -0
- package/README.md +23 -16
- package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
- package/dist/types/components/approval-card/approval-card.d.ts +596 -0
- package/dist/types/components/avatar/avatar.d.ts +91 -4
- package/dist/types/components/badge/badge.d.ts +5 -4
- package/dist/types/components/block-view/block-view.d.ts +205 -0
- package/dist/types/components/composer/composer.d.ts +736 -0
- package/dist/types/components/datebox/date-range-box.d.ts +15 -2
- package/dist/types/components/datebox/datebox.d.ts +37 -3
- package/dist/types/components/kbd/kbd.d.ts +41 -0
- package/dist/types/components/launcher/launcher.d.ts +4 -2
- package/dist/types/components/prose/prose.d.ts +69 -0
- package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
- package/dist/types/components/run-status/run-status.d.ts +393 -0
- package/dist/types/components/run-trace/run-trace.d.ts +624 -0
- package/dist/types/components/source-list/source-list.d.ts +177 -0
- package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
- package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
- package/dist/types/components/tree/tree.d.ts +44 -3
- package/dist/types/core/icons.d.ts +22 -1
- package/dist/types/core/messages.d.ts +135 -0
- package/dist/types/index.d.ts +12 -2
- package/dist/types/internal/agent-model.d.ts +587 -0
- package/dist/types/internal/app-rail.d.ts +10 -3
- package/dist/types/internal/highlight.d.ts +24 -0
- package/dist/types/internal/presence-loop.d.ts +148 -0
- package/dist/types/internal/row-actions.d.ts +151 -0
- package/dist/zx-zeyos.esm.js +4852 -4535
- package/dist/zx-zeyos.esm.min.js +4 -4
- package/dist/zx.css +3152 -434
- package/dist/zx.esm.js +13730 -6595
- package/dist/zx.esm.min.js +27 -8
- package/dist/zx.global.js +13730 -6595
- package/dist/zx.global.min.js +27 -8
- package/dist/zx.min.css +1 -1
- package/docs/api.json +1474 -205
- package/docs/llms.md +698 -39
- package/docs/llms.txt +12 -1
- package/package.json +1 -1
- package/src/components/account-menu/account-menu.js +2 -2
- package/src/components/agent-thread/agent-thread.css +417 -0
- package/src/components/agent-thread/agent-thread.js +1365 -0
- package/src/components/app-rail/app-rail.css +11 -11
- package/src/components/app-sidebar/app-sidebar.css +90 -17
- package/src/components/app-sidebar/app-sidebar.js +120 -12
- package/src/components/approval-card/approval-card.css +289 -0
- package/src/components/approval-card/approval-card.js +1377 -0
- package/src/components/avatar/avatar.css +56 -1
- package/src/components/avatar/avatar.js +148 -26
- package/src/components/badge/badge.css +33 -20
- package/src/components/badge/badge.js +5 -4
- package/src/components/block-view/block-view.css +300 -0
- package/src/components/block-view/block-view.js +523 -0
- package/src/components/breadcrumb/breadcrumb.css +28 -3
- package/src/components/breadcrumb/breadcrumb.js +2 -2
- package/src/components/button/button.css +24 -13
- package/src/components/button/button.js +20 -2
- package/src/components/calendar/calendar.css +14 -4
- package/src/components/card-view/card-view.js +2 -2
- package/src/components/chart/chart.js +20 -5
- package/src/components/check-button/check-button.css +11 -3
- package/src/components/check-button/check-button.js +3 -3
- package/src/components/composer/composer.css +403 -0
- package/src/components/composer/composer.js +1441 -0
- package/src/components/context-menu/context-menu.css +7 -1
- package/src/components/date-picker/date-picker.css +6 -0
- package/src/components/date-picker/date-picker.js +5 -5
- package/src/components/date-picker/date-range-picker.css +6 -0
- package/src/components/date-picker/date-range-picker.js +3 -3
- package/src/components/date-picker/month-picker.js +3 -3
- package/src/components/date-picker/time-picker.css +6 -0
- package/src/components/datebox/date-range-box.js +30 -6
- package/src/components/datebox/datebox.js +44 -7
- package/src/components/dialog/dialog.css +0 -1
- package/src/components/dialog/dialog.js +2 -1
- package/src/components/dock/dock.js +2 -2
- package/src/components/dropdown/dropdown.css +2 -1
- package/src/components/entity-ref/entity-ref.css +8 -1
- package/src/components/file-item/file-item.css +1 -1
- package/src/components/finder/finder.js +2 -2
- package/src/components/groupbox/groupbox.js +2 -2
- package/src/components/kanban-view/kanban-view.css +8 -4
- package/src/components/kanban-view/kanban-view.js +3 -3
- package/src/components/kbd/kbd.css +64 -0
- package/src/components/kbd/kbd.js +121 -0
- package/src/components/launcher/launcher.css +30 -25
- package/src/components/launcher/launcher.js +15 -21
- package/src/components/list-toolbar/list-toolbar.css +7 -1
- package/src/components/menu-button/menu-button.css +9 -2
- package/src/components/message/message.js +2 -2
- package/src/components/module-bar/module-bar.css +11 -1
- package/src/components/multi-value-editor/multi-value-editor.js +4 -4
- package/src/components/navigation-bar/navigation-bar.css +3 -2
- package/src/components/pagination/pagination.js +2 -2
- package/src/components/panel/panel.js +2 -2
- package/src/components/prose/prose.css +53 -0
- package/src/components/prose/prose.js +152 -0
- package/src/components/questionnaire/questionnaire.css +7 -17
- package/src/components/questionnaire/questionnaire.js +16 -1
- package/src/components/rating/rating.css +3 -1
- package/src/components/run-status/run-status.css +208 -0
- package/src/components/run-status/run-status.js +782 -0
- package/src/components/run-trace/run-trace.css +443 -0
- package/src/components/run-trace/run-trace.js +1209 -0
- package/src/components/search/search.js +2 -2
- package/src/components/select/glyphs.js +3 -3
- package/src/components/select/select.css +35 -7
- package/src/components/select/select.js +4 -4
- package/src/components/source-list/source-list.css +208 -0
- package/src/components/source-list/source-list.js +355 -0
- package/src/components/stat-tile/stat-tile.css +56 -2
- package/src/components/stat-tile/stat-tile.js +25 -2
- package/src/components/stepper/stepper.css +2 -1
- package/src/components/stepper/stepper.js +3 -3
- package/src/components/tabbox/tabbox.css +2 -2
- package/src/components/tabbox/tabbox.js +2 -2
- package/src/components/table/table.css +52 -16
- package/src/components/table/table.js +7 -5
- package/src/components/tag-picker/tag-picker.css +56 -43
- package/src/components/tag-picker/tag-picker.js +21 -16
- package/src/components/tree/tree.css +44 -0
- package/src/components/tree/tree.js +97 -9
- package/src/components/value-list/value-list.css +25 -4
- package/src/components/value-list/value-list.js +2 -1
- package/src/components/view/record-view.js +3 -3
- package/src/components/view-settings/view-settings.css +2 -1
- package/src/components/workspace-switcher/workspace-switcher.js +3 -3
- package/src/core/icons.js +34 -3
- package/src/core/messages.js +143 -0
- package/src/elements/define.js +1 -0
- package/src/index.js +12 -2
- package/src/internal/agent-model.js +488 -0
- package/src/internal/app-rail.js +5 -1
- package/src/internal/highlight.js +104 -0
- package/src/internal/presence-loop.js +343 -0
- package/src/internal/row-actions.js +203 -0
- package/styles/base.css +26 -1
- package/styles/prose.css +306 -0
- package/styles/tokens/dark.css +97 -120
- package/styles/tokens/global.css +24 -9
- package/styles/tokens/semantic.css +464 -184
- package/styles/tokens/themes.css +9 -0
- package/styles/zx.css +10 -0
package/docs/llms.md
CHANGED
|
@@ -147,7 +147,7 @@ a second navigation.
|
|
|
147
147
|
| A spreadsheet-like editable grid (lines, positions) | `Grid` (`Grid.BillingItems()`) | `Table` with `editMode` — that is for occasional cell edits |
|
|
148
148
|
| A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
|
|
149
149
|
| Events over time | `Calendar` (agenda, day, week, month, year) | — |
|
|
150
|
-
| One number with context | `StatTile` (delta, sparkline, loading) | a card with a big figure |
|
|
150
|
+
| One number with context | `StatTile` (delta, sparkline, loading; plain and one leading for a record's figures) | a card with a big figure |
|
|
151
151
|
| A chart | `Chart` with `ChartJsAdapter` (Chart.js injected, never bundled) | — |
|
|
152
152
|
| A linked record inline | `EntityRef` | a link |
|
|
153
153
|
| Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
|
|
@@ -183,12 +183,13 @@ the library already reads — never as component CSS:
|
|
|
183
183
|
|
|
184
184
|
1. **Theme** — `data-zx-theme="auto"` unless the product pins `light` or `dark`. Both must work; a
|
|
185
185
|
region may differ from the page.
|
|
186
|
-
2. **Accent** — a preset (`data-zx-preset="zx|zeyos|ocean|violet|rose|slate"`) or a five-stop
|
|
186
|
+
2. **Accent** — a preset (`data-zx-preset="zx|zeyos|ocean|violet|rose|slate|folio"`) or a five-stop
|
|
187
187
|
`--zx-accent-300…700` ramp built in the theme studio (<https://zx.zeyos.com/theme.html>), which
|
|
188
188
|
exports the CSS. Never a one-off colour on a button.
|
|
189
189
|
3. **Geometry** — the rhythm is three tokens on `:root` (or on a dense region): `--zx-space-unit`,
|
|
190
190
|
`--zx-control-height`, `--zx-radius`. Dense data tools sit around 3.5px / 28px; comfortable
|
|
191
|
-
products around 4.5px / 32–34px. Never a per-component size.
|
|
191
|
+
products around 4.5px / 32–34px. Never a per-component size. Data rows follow the control
|
|
192
|
+
height through `--zx-row-height`; set it only to make rows tighter or more relaxed than that.
|
|
192
193
|
4. **Material** — how surfaces answer light, exported from the studio as token overrides (there
|
|
193
194
|
is no attribute). `Glass` (the default: a thin lit pane), `Deep glass` (a thick one), `Frost`
|
|
194
195
|
(milk glass for reading surfaces), `Smoke` (tinted glass that darkens the scene; dark-first
|
|
@@ -201,13 +202,20 @@ the library already reads — never as component CSS:
|
|
|
201
202
|
6. **Colour roles** — `--zx-color-tone-*` for categories (tags, modules, avatars),
|
|
202
203
|
`--zx-color-danger|warning|success|info` for status, `--zx-color-bg-current` for "you are here"
|
|
203
204
|
and `--zx-color-bg-selected` for "what you picked", `--zx-color-bg-chrome` for navigation and
|
|
204
|
-
inspector columns. A module's colour is its `tone` on `ModuleBar`.
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
205
|
+
inspector columns. A module's colour is its `tone` on `ModuleBar`. A product's own colour is a
|
|
206
|
+
role overridden once on `:root`, `light-dark(<light>, <dark>)` where the appearances differ —
|
|
207
|
+
never per theme attribute (see **Override once**).
|
|
208
|
+
7. **Type** — two registers. Interface type is `--zx-font-sans`, `--zx-font-mono` and
|
|
209
|
+
`--zx-text-base` (every `--zx-text-*` step derives from it). Reading type is a second, separate
|
|
210
|
+
decision for authored content in `.zx-prose`: `--zx-font-prose` (a serif here leaves the
|
|
211
|
+
interface alone), `--zx-prose-size`, `--zx-prose-measure`.
|
|
212
|
+
8. **Content** — wrap authored text (a document, notes, a message body, an assistant's answer) in
|
|
213
|
+
`.zx-prose`; set emphasis apart with `.zx-callout` (neutral unless it is a status or a
|
|
214
|
+
category). Never style headings and paragraphs per screen.
|
|
215
|
+
9. **Fields** — `data-zx-fields="quiet"` on property panels (no border or fill until hovered or
|
|
208
216
|
focused).
|
|
209
|
-
|
|
210
|
-
|
|
217
|
+
10. **Print** — works without work; keep status badges, hide chrome. Nothing to add.
|
|
218
|
+
11. **Markup-first pages** — `defineElements()` for `<zx-*>` custom elements where templates are
|
|
211
219
|
authored as HTML.
|
|
212
220
|
|
|
213
221
|
### Never
|
|
@@ -234,18 +242,53 @@ Themes: `light` | `dark` | `auto` (follows OS).
|
|
|
234
242
|
**One geometry.** Spacing steps are multiples of one unit
|
|
235
243
|
(`--zx-space-unit`, 4px: `--zx-space-1…8` = 4/8/12/16/20/24/32/40px), radius steps are fractions of
|
|
236
244
|
one base (`--zx-radius`, 4px: `-sm/-md/-lg/-xl` = 2/3/4/6px; `-full` only for shapes whose roundness
|
|
237
|
-
is the meaning —
|
|
245
|
+
is the meaning — status pills, avatars, toggles; a tag takes `-md`; `-panel` is the corner of a panel that holds rounded
|
|
246
|
+
items, a menu or a listbox, concentric with them: the item corner plus the inset between them, 6px
|
|
247
|
+
at the default and square when the base is 0), and controls are `--zx-control-height` (30px) tall.
|
|
248
|
+
A data row — a table row, a single-line list row — is `--zx-row-height`, derived from the control
|
|
249
|
+
height (36px at the default), so every list on a screen shares one rhythm and a tighter product is
|
|
250
|
+
still one decision. Type is one base: `--zx-text-base` (14px) with every `--zx-text-*` step derived
|
|
251
|
+
from it (12 / 13 / 14 / 16 / 18 / 24 / 30px at the default), so changing the base keeps the
|
|
252
|
+
hierarchy; setting `--zx-text-md` alone still moves only the control size.
|
|
238
253
|
To tighten or loosen an application, override those tokens on `:root` or on any region. The
|
|
239
254
|
geometry and material tokens (control size, radius, spacing, blur and glass filters, durations,
|
|
240
|
-
easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]`
|
|
241
|
-
override on `:root` reaches nested light and dark regions alike
|
|
255
|
+
easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` element, so an
|
|
256
|
+
override on `:root` reaches nested light and dark regions alike — and colours work the same way
|
|
257
|
+
(see **Override once**):
|
|
242
258
|
|
|
243
259
|
```css
|
|
244
260
|
:root { --zx-space-unit: 3.5px; --zx-control-height: 28px; }
|
|
245
261
|
```
|
|
246
262
|
|
|
263
|
+
**Override once.** Every colour role is declared once, on `:root`; a theme element sets only
|
|
264
|
+
`color-scheme`, which picks the half of each `light-dark()` pair it reads. So a colour override
|
|
265
|
+
belongs on `:root` as well, written as `light-dark(<light>, <dark>)` where the two appearances
|
|
266
|
+
differ, and it reaches light, dark, auto and every nested region alike — together with everything
|
|
267
|
+
derived from it (hover, current, the glass and overlay tiers, and the tone tints follow
|
|
268
|
+
`--zx-color-text` and `--zx-color-bg-surface`) and every material the theme studio exports:
|
|
269
|
+
|
|
270
|
+
```css
|
|
271
|
+
:root {
|
|
272
|
+
--zx-color-bg-page: light-dark(#f7f8fa, #14161b);
|
|
273
|
+
--zx-color-text-muted: light-dark(#5b6170, #a3a9b6);
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
A value without `light-dark()` applies to both appearances. The accent is a ramp, not a role: set
|
|
278
|
+
`--zx-accent-300…700` (or use a preset) and each appearance takes its own stop. A nested
|
|
279
|
+
`data-zx-preset` region restates the roles that read that ramp (`--zx-color-accent*`,
|
|
280
|
+
`--zx-color-bg-selected`, `--zx-color-ring`, `--zx-focus-ring`, `--zx-color-overlay-selected`, the
|
|
281
|
+
overlay images), so an override of one of those meant to reach such a region too is written
|
|
282
|
+
`:root, [data-zx-preset] { … }`. Never register a colour role with `@property`: a registered colour
|
|
283
|
+
resolves where it is declared and stops following the region. Script that needs a role's value
|
|
284
|
+
reads a probe element's computed `color`, not the property's text, which may be a `light-dark()`
|
|
285
|
+
pair that a canvas cannot parse. `light-dark()` needs a 2024 browser; older ones read Xenon's own
|
|
286
|
+
per-theme fallback, where a `:root` override stops at a nested theme region, so an application that
|
|
287
|
+
supports them puts its own `light-dark()` overrides inside `@supports (color: light-dark(#000,
|
|
288
|
+
#fff))`.
|
|
289
|
+
|
|
247
290
|
**Accent presets.** A second, orthogonal attribute picks the accent ramp:
|
|
248
|
-
`data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate"` (`zx` is the default and
|
|
291
|
+
`data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate" | "folio"` (`zx` is the default and
|
|
249
292
|
need not be set). A preset repoints five tier-1 tokens — `--zx-accent-300` … `--zx-accent-700` —
|
|
250
293
|
and the semantic tier takes its own stop per polarity (600/700 on light surfaces, 300/400/500 on
|
|
251
294
|
dark), so one five-line block rethemes light, dark, and auto together. Status colours are not part
|
|
@@ -293,10 +336,16 @@ increased-contrast, forced-colour, and unsupported-filter environments restore s
|
|
|
293
336
|
Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
|
|
294
337
|
set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
|
|
295
338
|
|
|
296
|
-
Define a product theme
|
|
339
|
+
Define a product theme as an accent ramp (a preset) plus **semantic** token overrides, each declared
|
|
340
|
+
once on `:root` as above — not under a `[data-zx-theme="name"]` selector, which would stop at the
|
|
341
|
+
first nested region:
|
|
297
342
|
`--zx-color-bg-page/surface/raised/control/muted/hover/selected`, `--zx-color-bg-current` (the
|
|
298
343
|
neutral "you are here" fill of the current nav item, row, tab, or pressed toggle — never the
|
|
299
344
|
accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off the canvas),
|
|
345
|
+
`--zx-color-text-chrome` (navigation labels at rest, one ink step under the content and above 7:1;
|
|
346
|
+
hover, focus and the current item take the full text colour), `--zx-color-border-chrome` (the line
|
|
347
|
+
where a chrome column meets the canvas: none in light, where the tone step separates them; a
|
|
348
|
+
hairline in dark, under `prefers-contrast: more`, and in forced colours),
|
|
300
349
|
`--zx-color-glass-chrome/surface`,
|
|
301
350
|
`--zx-color-overlay-surface/panel/backdrop/border/hover/selected/divider/scrim`,
|
|
302
351
|
`--zx-overlay-surface-image/toast-image/panel-image`,
|
|
@@ -309,12 +358,29 @@ accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off
|
|
|
309
358
|
tiles, avatars — neither the accent nor a status) and `-solid` (a solid identity fill, such as a
|
|
310
359
|
module tile, that the white icon glyph reads on at 3:1 in both themes), the chart series
|
|
311
360
|
`--zx-color-chart-1…8`,
|
|
312
|
-
`--zx-
|
|
361
|
+
`--zx-color-ring` with `--zx-focus-ring` (keyboard focus; see **Focus** below),
|
|
362
|
+
`--zx-control-height/-radius`, `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`
|
|
313
363
|
(`-3xl` for document titles), `--zx-weight-medium/-semibold`, `--zx-tracking-tight/-title`. Never
|
|
314
364
|
use tier-1 palette tokens (`--zx-gray-*`, `--zx-green-*`, `--zx-emerald-*`, `--zx-tone-*`) or raw
|
|
315
365
|
color literals in application/component CSS. Prefer the least-specific override that works (global
|
|
316
366
|
token → then, if needed, a component style).
|
|
317
367
|
|
|
368
|
+
**Focus.** Keyboard focus is one quiet line: `--zx-focus-ring` is a single 2px spread shadow in
|
|
369
|
+
`--zx-color-ring` (the accent, at the stop each theme reads as text), opaque, so it clears the 3:1
|
|
370
|
+
a focus indicator needs against everything it sits on — the page, the chrome, a card, a raised
|
|
371
|
+
panel, a current row and a selected row — in both themes, under every preset and tint, and for any
|
|
372
|
+
custom ramp that keeps the promise above. Being one shadow, it works both ways round:
|
|
373
|
+
`box-shadow: var(--zx-focus-ring)` draws it around a control, `box-shadow: inset
|
|
374
|
+
var(--zx-focus-ring)` inside a row, a tab, or a cell. Combine it by listing it after the
|
|
375
|
+
element's own shadows (`var(--zx-focus-ring), var(--zx-drag-shadow)`), with any `inset` layer
|
|
376
|
+
first, since `inset` belongs to one shadow of a list rather than to the list. Where the focused
|
|
377
|
+
element is itself an accent fill — a primary button, a chosen day — the ring would only make it
|
|
378
|
+
look larger, so lead with a 1px line in the fill's ink: `box-shadow: inset 0 0 0 1px
|
|
379
|
+
var(--zx-color-on-accent-solid), var(--zx-focus-ring)` (`--zx-color-on-accent` on a
|
|
380
|
+
`--zx-color-accent` fill). Leave the outline transparent rather than removing it: forced colours
|
|
381
|
+
drop every shadow and paint that outline in the system highlight instead. A product that restyles
|
|
382
|
+
the ring keeps it one shadow, at least 2px, and at 3:1; to recolour it, set `--zx-color-ring`.
|
|
383
|
+
|
|
318
384
|
**Print.** `zx.css` imports `styles/print.css` last. It releases sticky headers and scroll
|
|
319
385
|
containers, drops fills, shadows, zebra striping and focus rings, hides overlays and navigation
|
|
320
386
|
chrome, repeats table headers across pages, keeps cards and rows from breaking, and prints link
|
|
@@ -559,6 +625,65 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
|
|
|
559
625
|
Each component is `new Component(target, options)`. Events are the component-level names (also
|
|
560
626
|
dispatched as bubbling `zx-<name>` on the root). Detail is always an object.
|
|
561
627
|
|
|
628
|
+
<!-- doc:prose -->
|
|
629
|
+
### Prose — `.zx-prose` and `.zx-callout`
|
|
630
|
+
|
|
631
|
+
The reading register: a class, not a component, that sets authored content — a document, a
|
|
632
|
+
record's notes, a message body, an assistant's answer — in the reading tokens rather than the
|
|
633
|
+
interface ones. Write plain HTML inside it: `h1`–`h4`, `p`, `ul`/`ol`, `blockquote`, `hr`, links,
|
|
634
|
+
inline `code`, `pre`, `kbd`, `mark`, tables, `figure`/`figcaption`, `img`.
|
|
635
|
+
|
|
636
|
+
- **Tokens** — `--zx-font-prose` (the interface stack by default; a serif here leaves the interface
|
|
637
|
+
alone), `--zx-prose-size` (16px, `--zx-text-lg`), `--zx-prose-leading` (1.7), `--zx-prose-measure`
|
|
638
|
+
(62ch, the reading width). Headings scale with the reading size and read `--zx-weight-title`.
|
|
639
|
+
- **Attributes** — `data-size="sm"` sets prose at the interface size, for comments, previews, and
|
|
640
|
+
panels; `data-zx-measure="full"` drops the measure where the column already sets the width.
|
|
641
|
+
- **Rhythm** — one gap between blocks, more above a heading and less below it; links in the body
|
|
642
|
+
colour over a quiet underline, accent on hover; tables without a frame, a muted header over
|
|
643
|
+
hairline rows, `data-align="end"` cells in tabular figures.
|
|
644
|
+
- **Content colour** — a bare `mark` highlights in the amber tone; `mark[data-tone]` in any of the
|
|
645
|
+
nine tones; a bare `span[data-tone]` colours its text, and `data-fill` highlights it as well.
|
|
646
|
+
- **Callout** — `.zx-callout` with an optional `.zx-callout__icon` and a `.zx-callout__body`
|
|
647
|
+
(`.zx-callout__title` for a bold first line): a tinted fill, no frame, at the interface size.
|
|
648
|
+
Neutral by default, because most callouts are emphasis; `data-kind="info|success|warning|danger"`
|
|
649
|
+
makes it a status and `data-tone` a category. Works inside or outside prose.
|
|
650
|
+
- **Specificity** — every rule is `.zx-prose` plus `:where()`, and the stylesheet loads before the
|
|
651
|
+
components, so a badge, an entity reference, or a table placed in prose keeps its own styles,
|
|
652
|
+
while an application's bare element reset cannot undo the rhythm.
|
|
653
|
+
- **Section links** — `proseAnchors(root, options)` ends every `h2`–`h4` with an `id` inside a
|
|
654
|
+
`.zx-prose` under `root` with a small link to itself (`a.zx-prose__anchor`, "Copy link to …").
|
|
655
|
+
It shows while the heading is pointed at or the link has focus (and always on a touch screen or
|
|
656
|
+
under a contrast preference). A click copies the address with the section's hash — the current
|
|
657
|
+
address by default, `href(id)` to build another — and confirms with a tick and a polite "Link
|
|
658
|
+
copied"; it never changes the location, and a middle or modified click is left to the browser.
|
|
659
|
+
Options: `selector`, `label` (`%1` is the heading), `title`, `feedback`, `feedbackDuration`,
|
|
660
|
+
`href`, `oncopy(url, copied)`. It returns `{refresh(), destroy()}`: call `refresh()` after
|
|
661
|
+
re-rendering the content. Headings without an id are skipped — give the ones worth linking a
|
|
662
|
+
stable id. `sectionHref(base, id)` builds the address.
|
|
663
|
+
<!-- /doc -->
|
|
664
|
+
|
|
665
|
+
<!-- doc:kbd -->
|
|
666
|
+
### Kbd — `kbd(keys, options)`
|
|
667
|
+
|
|
668
|
+
A factory (not a class) returning keycaps: one `<kbd class="zx-kbd">` holding a nested
|
|
669
|
+
`<kbd class="zx-kbd__key">` per key, which is how HTML marks up a combination. Button shortcuts,
|
|
670
|
+
the launcher's hints, and shortcut references all use it, so a key looks the same everywhere.
|
|
671
|
+
|
|
672
|
+
- **Signature** — `kbd(keys, { size, tone })` → `HTMLElement`. `keys` is a chord written like
|
|
673
|
+
`aria-keyshortcuts` (`'Mod+Shift+K'`; a literal plus as `'Mod++'`) or an array of keys for a
|
|
674
|
+
sequence (`['g', 'i']`). `size: 'md'|'sm'` (`sm` inside buttons and menu rows); `tone:
|
|
675
|
+
'neutral'|'inherit'` (`inherit` draws the caps in the surrounding ink, for a solid button or a
|
|
676
|
+
dark toast). `keyLabels(keys, { apple })` returns the labels without building DOM.
|
|
677
|
+
- **Labels** — `Mod` is ⌘ on Apple platforms and Ctrl elsewhere; `Alt`, `Shift`, `Ctrl`,
|
|
678
|
+
`Backspace`, `Delete`, `Tab` become ⌥ ⇧ ⌃ ⌫ ⌦ ⇥ on Apple platforms and words elsewhere; `Enter`,
|
|
679
|
+
`Escape` and the arrows become ↵, Esc, ↑ ↓ ← →; single letters are upper-cased.
|
|
680
|
+
- **Look** — a surface fill, one hairline and a 1px foot, the label at the small size and medium
|
|
681
|
+
weight, centred on its capital height; a single key is square. Retint it with `--zx-kbd-ink`,
|
|
682
|
+
`--zx-kbd-fill` and `--zx-kbd-line` on any ancestor.
|
|
683
|
+
- **Accessibility** — the caps are presentation. Announce a control's shortcut with
|
|
684
|
+
`aria-keyshortcuts` on the control and mark a hint that repeats it `aria-hidden`.
|
|
685
|
+
<!-- /doc -->
|
|
686
|
+
|
|
562
687
|
<!-- doc:button -->
|
|
563
688
|
### Button — `button(options)` / `buttonGroup(buttons)`
|
|
564
689
|
|
|
@@ -582,9 +707,9 @@ accept.
|
|
|
582
707
|
<!-- doc:badge -->
|
|
583
708
|
### Badge — `badge(options)` / `badgeGroup(badges)`
|
|
584
709
|
|
|
585
|
-
Factories (not classes) returning a
|
|
586
|
-
|
|
587
|
-
record-header metadata. A badge with no label but a `title` is named for assistive technology
|
|
710
|
+
Factories (not classes) returning a chip: a small, non-interactive `<span>` carrying a semantic
|
|
711
|
+
colour — a status — or, with `tone`, a categorical one — a tag — used for stages, counts, labels,
|
|
712
|
+
and record-header metadata. A badge with no label but a `title` is named for assistive technology
|
|
588
713
|
through `role="img"`; everything else is plain text and needs no ARIA.
|
|
589
714
|
|
|
590
715
|
- **Options** — `label`, `icon` (an icon name, rendered before the label), `kind:
|
|
@@ -597,11 +722,18 @@ through `role="img"`; everything else is plain text and needs no ARIA.
|
|
|
597
722
|
accent nor the status set, so a project tagged red never reads as an error. When `tone` is set it
|
|
598
723
|
decides the colour and `kind` is ignored for it; every `variant` still applies (soft: tinted,
|
|
599
724
|
borderless; solid: filled with the tone's ink; outline). The badge carries `data-tone`. Badges
|
|
600
|
-
are
|
|
725
|
+
are sentence case.
|
|
726
|
+
- **Two shapes, one construction** — a status is a pill (`--zx-radius-full`); give a workflow state
|
|
727
|
+
`dot: true`, a 6px dot centred in the pill's round end. A tag (any badge with a `tone`) has small
|
|
728
|
+
corners (`--zx-radius-md`). Both are one fill and no line, 12px at weight 500 at either size,
|
|
729
|
+
and their height follows the row they sit in: about five ninths of `--zx-row-height` for `md`
|
|
730
|
+
and half of it for `sm` (20px and 18px in the default row), never below a line of their own text,
|
|
731
|
+
so a chip follows the row height setting without making a row taller. `TagPicker` builds its tags with
|
|
732
|
+
`badge()`, so a label reads the same in a list row, a record header and the field that edits it.
|
|
601
733
|
- **Neutral and small** — the neutral soft fill is a wash of the text colour, not an opaque surface
|
|
602
734
|
step, so it stays visible on raised surfaces in the dark theme. `size: 'sm'` fits table cells
|
|
603
|
-
and board cards;
|
|
604
|
-
|
|
735
|
+
and board cards; it is shorter and tighter, never smaller type. Under `prefers-contrast: more` a
|
|
736
|
+
soft badge gets its edge back, and under forced colours every badge does.
|
|
605
737
|
- **Methods** — none. `badge(options)` → `HTMLSpanElement`, `badgeGroup([badge(…), …])` → a wrapping
|
|
606
738
|
inline row with its own spacing; you own both elements.
|
|
607
739
|
- **Events** — none; a badge is not interactive.
|
|
@@ -866,14 +998,28 @@ and the component is decorative by default so adjacent identity text is not anno
|
|
|
866
998
|
- **Options** — `src`, `name`, `initials`, `label`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 /
|
|
867
999
|
40px at the default spacing unit), `shape: 'circle'|'rounded'|'square'`, `tone:
|
|
868
1000
|
'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'|null`, `status:
|
|
869
|
-
'online'|'away'|'busy'|'offline'|null`,
|
|
1001
|
+
'online'|'away'|'busy'|'offline'|null`, `statusLabel`, `activity:
|
|
1002
|
+
'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`, `activityLabel`, `animate: false`, and `phase: null|number`.
|
|
870
1003
|
- **Fallback** — no ring; the `--zx-color-tone-*-bg` fill with its `-fg` ink, initials at 0.4× the
|
|
871
1004
|
size (never under 10px), weight 600, one initial below 24px. `tone: null` derives the tone with
|
|
872
1005
|
`avatarTone(name)` (exported from the module): FNV-1a over the trimmed, NFC-normalised,
|
|
873
1006
|
lower-cased name, mapped onto the eight chromatic tones, so a person keeps their colour on every
|
|
874
1007
|
screen. `slate`, the neutral, is reserved for an avatar with no name and can be set explicitly.
|
|
875
1008
|
The root carries `data-tone`. `avatarInitials(name, limit = 2)` returns the initials.
|
|
876
|
-
- **
|
|
1009
|
+
- **Agent activity** — `activity` draws what an agent is doing as a dot whose shape differs as
|
|
1010
|
+
well as its tone: solid success (working), solid info (thinking), solid warning (needs you), a
|
|
1011
|
+
danger square (blocked), a hollow ring (idle), and a dashed ring (offline). Its word ("Needs
|
|
1012
|
+
you", or `activityLabel`) joins the accessible name and the dot's tooltip, and the root carries
|
|
1013
|
+
`data-activity`. When both are given, `activity` wins over `status`. `animate: true` moves the
|
|
1014
|
+
avatar with its activity — idle breathes, thinking sways, working bobs, needs-you leans and
|
|
1015
|
+
blinks — in the one `requestAnimationFrame` loop every animated avatar on the page shares: only
|
|
1016
|
+
on screen, never while the page is hidden, and back at rest under reduced motion (the system's
|
|
1017
|
+
or a `data-zx-motion="reduced"` region). While it is on, the loop owns the root's `transform`. `phase` sets where in its activity's cycle the avatar moves, as a fraction from 0 up to 1
|
|
1018
|
+
(whole turns wrap): two avatars of one agent on the same screen — a roster and an inspector —
|
|
1019
|
+
at `phase: 0` and `phase: 0.5` move half a cycle apart. `null` derives the phase from the name
|
|
1020
|
+
(or the initials), so avatars of the same agent without a phase move in step.
|
|
1021
|
+
- **Methods** — `set(values)` (any option above, `phase` included, applied while the avatar moves), `setStatus(status, label?)`,
|
|
1022
|
+
`setActivity(activity, label?)`, `getActivity()`, `hasImage()`, `destroy()`.
|
|
877
1023
|
- **Accessibility** — set `label` only when the avatar stands alone. Presence is supplementary
|
|
878
1024
|
status, not the account's accessible name; supply `statusLabel` when it conveys information.
|
|
879
1025
|
<!-- /doc -->
|
|
@@ -1305,9 +1451,19 @@ Text date input with a calendar popover. `DateTimeBox(target, opts)` is a Datebo
|
|
|
1305
1451
|
`time: true`, which also brings the TimePicker (and its clock face) into the popover. Format
|
|
1306
1452
|
tokens are the date-utility ones: `%d %m %Y %H %M`.
|
|
1307
1453
|
|
|
1308
|
-
- **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `
|
|
1309
|
-
`max`, `placeholder`, `clearable: true` (the clear button shows while
|
|
1310
|
-
box is enabled; without `clearable` the input keeps no room for it),
|
|
1454
|
+
- **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `displayFormat: null`,
|
|
1455
|
+
`time: false`, `min`, `max`, `placeholder`, `clearable: true` (the clear button shows while
|
|
1456
|
+
there is a value and the box is enabled; without `clearable` the input keeps no room for it),
|
|
1457
|
+
`disabled`.
|
|
1458
|
+
- **Two formats** — `format` is what the reader types, and what the field shows while it has
|
|
1459
|
+
focus; it is parsed, so it takes numeric tokens only. `displayFormat` is what the field shows at
|
|
1460
|
+
rest, so a date field reads the way the rest of the screen writes dates (`'%e %b %Y'` → "2 Nov
|
|
1461
|
+
2026" beside a header that says "Created 19 Jul 2026"). It is never parsed, so month and weekday
|
|
1462
|
+
names (`%b %B %a %A`) are fine; `null` shows `format`. Focus switches the text to the typing
|
|
1463
|
+
format, a valid commit on blur or Enter switches it back, and text that failed to parse stays as
|
|
1464
|
+
typed. With `time`, a format without `%H`/`%M` gets ` %H:%M` appended, the display format too.
|
|
1465
|
+
The placeholder still describes `format`, and string values passed to `set()` are parsed with it.
|
|
1466
|
+
`dateboxFormats({format, displayFormat, time})` → `{format, display}` resolves both the same way.
|
|
1311
1467
|
- **In a Field** — field types `date`/`datetime` (and `daterange`) fill the control column like a
|
|
1312
1468
|
text input and give way in a narrow two-column row; standalone, the box keeps its own width.
|
|
1313
1469
|
- **Methods** — `get(unit='date')` (`'seconds'` → unix), `set(value, {silent})` (accepts a Date;
|
|
@@ -1333,7 +1489,7 @@ An inline two-month calendar for picking a start and an end day, plus the form-u
|
|
|
1333
1489
|
|
|
1334
1490
|
#### DateRangeBox
|
|
1335
1491
|
|
|
1336
|
-
- **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open.
|
|
1492
|
+
- **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `displayFormat: null`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open. `displayFormat` is the endpoints' format at rest, as on Datebox (`'%e %b %Y'` → "3 Aug 2026 – 9 Aug 2026"); focus switches to `format`, and text left untouched while the calendar holds focus goes back to the display format.
|
|
1337
1493
|
- **Methods** — `get(unit = 'date')` (`'seconds'` returns `{start, end}` as Unix seconds), `set(range, {silent})` accepting `{start, end}` of Dates, Unix-seconds numbers, or formatted strings, `clear({silent})`, `open()`, `close()`, `enable()`, `disable()`, `focus()`, `destroy()`.
|
|
1338
1494
|
- **Events** — `change {start, end}`, `invalid {text}` when the typed value cannot be parsed (the text stays editable and the field takes `data-state="invalid"` plus `aria-invalid`), `open`, `close`.
|
|
1339
1495
|
<!-- /doc -->
|
|
@@ -2221,7 +2377,17 @@ mutate the caller's data.
|
|
|
2221
2377
|
- **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
|
|
2222
2378
|
`expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
|
|
2223
2379
|
(tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
|
|
2224
|
-
(lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height
|
|
2380
|
+
(lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`,
|
|
2381
|
+
`rowActions: (node) => actions`, `moreLabel: 'More actions'`.
|
|
2382
|
+
- **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
|
|
2383
|
+
disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
|
|
2384
|
+
buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
|
|
2385
|
+
menu (a node never folds). They rest out of sight and keep their room, and show while the row is
|
|
2386
|
+
pointed at, focused or selected, while its menu is open, and always on a touch screen, under a
|
|
2387
|
+
contrast preference and in forced colours — the `data-zx-reveal` utility. Every descriptor is
|
|
2388
|
+
also in the row's context menu (right-click, Shift+F10, the Menu key), and each control is named
|
|
2389
|
+
after its action and its row ("Add sub-page: Onboarding"); the row's own name stays its label.
|
|
2390
|
+
Use them only for repeated, secondary commands that are reachable another way too.
|
|
2225
2391
|
- **Methods** — `setItems()`, `getItems()`, `getNode(id)`, `getPath(id)`, `setFilter(query)` (keeps
|
|
2226
2392
|
matching nodes' ancestors and opens the surviving branches),
|
|
2227
2393
|
`expand(id)`/`collapse(id)`/`toggle(id)` (async — they await the loader),
|
|
@@ -2234,6 +2400,9 @@ mutate the caller's data.
|
|
|
2234
2400
|
activates, Space selects or toggles the checkbox, `*` expands every sibling, typing jumps to the
|
|
2235
2401
|
next match. A typed character's default action is prevented, so find-as-you-type and page
|
|
2236
2402
|
shortcuts do not act on it too; typing into a control inside a row is left to that control.
|
|
2403
|
+
With row actions, Tab from the focused row walks that row's actions and then leaves the tree
|
|
2404
|
+
(Shift+Tab comes back); keys pressed on an action belong to it, and clicking one neither selects
|
|
2405
|
+
nor focuses the row.
|
|
2237
2406
|
- **Appearance** — the selected node of a single-selection tree is where you are: the neutral
|
|
2238
2407
|
`--zx-color-bg-current` fill, the text colour, a semibold label. A `selection: 'multi'` tree is a
|
|
2239
2408
|
set of picks and keeps the accent tint. Icons, folders included, are drawn in
|
|
@@ -2503,12 +2672,16 @@ yet. Field type: `tagpicker`.
|
|
|
2503
2672
|
`filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
|
|
2504
2673
|
`max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
|
|
2505
2674
|
`placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
|
|
2675
|
+
- **Tags are Badges** — every selected tag is built by `badge()` (`.zx-badge.zx-tag-picker__tag`):
|
|
2676
|
+
the Badge's height from the row, 12px medium type, padding and one fill, with the tag shape's
|
|
2677
|
+
small corners. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
|
|
2678
|
+
`green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`), so a toned tag is exactly the
|
|
2679
|
+
`badge({ tone })` a list row or record header shows for the same item; a tone wins over a colour.
|
|
2680
|
+
An untoned tag keeps the text ink, because in a field it is the value.
|
|
2506
2681
|
- **Tag identity** — icon values accept a bundled icon name or Node; colors (a CSS colour or a token
|
|
2507
2682
|
reference such as `var(--zx-color-tone-blue-fg)`) are scoped to the tag and its option through
|
|
2508
|
-
`--zx-tag-color`.
|
|
2509
|
-
|
|
2510
|
-
toned Badge does (`data-tone`), and a tone wins over a colour. Custom `renderItem`/`renderTag`
|
|
2511
|
-
remain authoritative.
|
|
2683
|
+
`--zx-tag-color`. An option shows its icon on a tile of its colour; inside a tag the icon is a bare
|
|
2684
|
+
glyph, since the tag is already the fill. Custom `renderItem`/`renderTag` remain authoritative.
|
|
2512
2685
|
- **Read-only** — `readonly` (or `setReadonly(true)`) shows only the tags: no input, chevron, or
|
|
2513
2686
|
remove buttons, so a full row of tags never wraps onto an empty line.
|
|
2514
2687
|
- **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
|
|
@@ -2567,13 +2740,21 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
|
|
|
2567
2740
|
|
|
2568
2741
|
- **Options** — `label`, `value`, `format: 'number'|'currency'|'percent'|'fileSize'|null|fn`,
|
|
2569
2742
|
`currency`, `locale`, `caption`, `delta`, `deltaKind: 'positive'|'negative'|'neutral'`,
|
|
2570
|
-
`deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `
|
|
2571
|
-
`msg`.
|
|
2743
|
+
`deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `variant: 'default'|'plain'`,
|
|
2744
|
+
`emphasis`, `href`, `clickable`, `loading`, `msg`.
|
|
2572
2745
|
- **Appearance** — the label is a sentence-case muted line (13px, medium); the value is the loud
|
|
2573
2746
|
part (24px, weight 650, tabular figures); `caption` is one muted context line under it ("of
|
|
2574
2747
|
13,184"). `icon` is a muted glyph beside the label, never a coloured chip; `kind` tints only the
|
|
2575
2748
|
sparkline. The tile is a column with the sparkline at its foot, so tiles in a row are the same
|
|
2576
2749
|
height and line up whether or not each has a caption, a delta or a trend.
|
|
2750
|
+
- **Framed or plain** — the default is a framed tile on its own surface: use it where a figure
|
|
2751
|
+
stands among other content, as on a dashboard. `variant: 'plain'` drops the frame, the fill and
|
|
2752
|
+
the padding, for a record's own figures under its title: its text sits on the content edge,
|
|
2753
|
+
space alone separates it from the next, and the figure steps down to 16px. Do not draw boxes
|
|
2754
|
+
around plain figures in the layout either. Reflected as `data-variant`.
|
|
2755
|
+
- **One figure leads** — `emphasis: true` sets one figure per row above the others: 24px in a
|
|
2756
|
+
plain row (the record title's size, never above it), 30px on a framed tile. Reflected as
|
|
2757
|
+
`data-emphasis`. The size is `--zx-stat-tile-value-size`, which the loading skeleton reads too.
|
|
2577
2758
|
- **Methods** — `update(options)`, `getAccessibleName()`.
|
|
2578
2759
|
- **Events** — `click {event}`.
|
|
2579
2760
|
|
|
@@ -2971,8 +3152,18 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
|
|
|
2971
3152
|
`side: 'left'|'right'|'top'|'bottom'`, `layout: 'tree'|'modules'`, `module`, `moduleBar`
|
|
2972
3153
|
(`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
|
|
2973
3154
|
strip), `label`,
|
|
2974
|
-
`header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
|
|
2975
|
-
`renderIcon(item, context)`. Icon values may also be names,
|
|
3155
|
+
`header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
|
|
3156
|
+
`moreLabel: 'More actions'`, and `renderIcon(item, context)`. Icon values may also be names,
|
|
3157
|
+
nodes, components, or factories.
|
|
3158
|
+
- **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
|
|
3159
|
+
disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
|
|
3160
|
+
rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
|
|
3161
|
+
for them, and show while the row is pointed at, holds focus, is the current page or has its menu
|
|
3162
|
+
open — always on a touch screen, under a contrast preference and in forced colours. Each is named
|
|
3163
|
+
after its action and the destination ("Rename: Customers"). Only the actions of the destination
|
|
3164
|
+
holding focus are Tab stops, right after it; a right-click or Shift+F10 on the destination lists
|
|
3165
|
+
them all. The expanded tree and the modules layout's panel draw them; minimized flyouts show the
|
|
3166
|
+
destinations only.
|
|
2976
3167
|
- **Sections** — an item with `section: true` is a quiet heading over its `children`, which stay
|
|
2977
3168
|
at its own level: never indented, collapsed, focused, or selected, and it needs no `id`.
|
|
2978
3169
|
`actions` (a node) adds trailing controls such as an add button. Sections replace stacking
|
|
@@ -3101,6 +3292,445 @@ bar.setBadge('mail', 8);
|
|
|
3101
3292
|
`--zx-control-height` resizes the bar; a coarse pointer keeps a 40px target.
|
|
3102
3293
|
<!-- /doc -->
|
|
3103
3294
|
|
|
3295
|
+
### Agents — the conversation model
|
|
3296
|
+
|
|
3297
|
+
The agent components draw a conversation with one or more AI agents from **plain JSON**: no
|
|
3298
|
+
functions and no DOM nodes in the data, so an agent can produce it, an application can store and
|
|
3299
|
+
replay it, and a component can render it. Three rules hold for every agent component:
|
|
3300
|
+
|
|
3301
|
+
1. **The application owns transport and state.** No agent component fetches anything. The
|
|
3302
|
+
application feeds them (`upsert`, `patch`, `appendText`) and acts on the intents they emit
|
|
3303
|
+
(`send`, `stop`, `approve`, `regenerate`, …).
|
|
3304
|
+
2. **Model text is data.** Every string an agent wrote reaches the page as text. Inside a text run
|
|
3305
|
+
the whole grammar is `**bold**`, `` `code` `` and `[n]` citations (a backslash makes a marker
|
|
3306
|
+
literal); there are no links, no HTML, and no images in answer text.
|
|
3307
|
+
3. **Consequence comes from the application.** Whether an action needs a confirmation — and which
|
|
3308
|
+
— is decided by the application from the tool the action triggers, never taken from model
|
|
3309
|
+
output.
|
|
3310
|
+
|
|
3311
|
+
A thread is a list of items, each `{id, type, at?, author?, …}`, where `author` is a key into
|
|
3312
|
+
the thread's `authors` (`{name, kind: 'person'|'agent'|'model', initials?, tone?, activity?, via?}`):
|
|
3313
|
+
|
|
3314
|
+
```json
|
|
3315
|
+
[
|
|
3316
|
+
{"id": "ask", "type": "user", "text": "Reconcile September and draft reminders.", "files": [{"name": "Policy.pdf", "size": 188416}]},
|
|
3317
|
+
{"id": "note", "type": "text", "author": "finance", "text": "I’ll check the bank feed first."},
|
|
3318
|
+
{"id": "work", "type": "trace", "author": "finance", "steps": [
|
|
3319
|
+
{"id": "q", "kind": "query", "label": "Queried invoices", "count": "42 rows", "ms": 800, "tool": "invoices.search", "args": "{\"month\": \"2026-09\"}", "result": "42 invoices"}
|
|
3320
|
+
]},
|
|
3321
|
+
{"id": "a1", "type": "answer", "author": "finance", "blocks": [
|
|
3322
|
+
{"type": "p", "text": "Three invoices are more than **14 days** late [1]."},
|
|
3323
|
+
{"type": "figures", "rows": [["Late", "3 invoices", "€19,375.50"]]}
|
|
3324
|
+
], "sources": [{"id": "inv", "title": "Invoices · September", "kind": "call", "call": "q"}]},
|
|
3325
|
+
{"id": "ok", "type": "approval", "author": "finance", "title": "Send 3 reminder emails?", "status": "pending"},
|
|
3326
|
+
{"id": "n1", "type": "notice", "text": "The bank feed timed out; retried once.", "tone": "warning"}
|
|
3327
|
+
]
|
|
3328
|
+
```
|
|
3329
|
+
|
|
3330
|
+
- **Blocks** — `p`, `quote`, `heading` (`level: 2|3`), `list` (`ordered`), `code` (`language`),
|
|
3331
|
+
`table` (`columns`, `rows`, `align`), `figures` (`rows` of `[label, detail, value]` or
|
|
3332
|
+
`{label, detail?, value, call?}`), `callout` (`tone`, `title`), `artifact` (`id`, `title`,
|
|
3333
|
+
`kind: 'document'|'code'`, `versions`).
|
|
3334
|
+
- **Steps** — `{id, kind: 'search'|'read'|'query'|'write'|'run'|'call'|'handoff'|'think', label,
|
|
3335
|
+
status, doing?, detail?, ms?, count?, sources?, tool?, args?, result?, error?, retryOf?, actor?,
|
|
3336
|
+
to?, at?}`. A retry names the step it repeats with `retryOf`; a hand-off names `actor` and `to`.
|
|
3337
|
+
- **States** — runs and steps are `queued`, `running`, `waiting`, `paused`, `done`, `failed`,
|
|
3338
|
+
`stopped`, or `skipped`; an agent's activity is `idle`, `thinking`, `working`, `needs-you`,
|
|
3339
|
+
`blocked`, or `offline`. Each is always drawn as a glyph and a word, never by colour or motion
|
|
3340
|
+
alone.
|
|
3341
|
+
|
|
3342
|
+
<!-- doc:block-view -->
|
|
3343
|
+
### BlockView — `new BlockView(target, options)` / `renderBlocks(blocks, options)`
|
|
3344
|
+
|
|
3345
|
+
An answer an agent wrote, drawn block by block as semantic elements inside `.zx-prose`, and
|
|
3346
|
+
written to as it streams. Finished blocks are never redrawn: `append()` and `appendText()` touch
|
|
3347
|
+
only the last block, so a reader's selection or focus in an earlier paragraph survives the rest of
|
|
3348
|
+
the answer arriving.
|
|
3349
|
+
|
|
3350
|
+
- **Options** — `blocks: []`, `headingLevel: 3` (the element level of a level-2 `heading` block;
|
|
3351
|
+
set it one below the heading that names the answer), `size: 'sm'|'md'` (interface or reading
|
|
3352
|
+
size), `streaming: false`, `sources: null` (names the citation buttons by title), `msg`.
|
|
3353
|
+
- **Methods** — `setBlocks(blocks, {streaming?})`, `append(block)`, `appendText(text)` (continues
|
|
3354
|
+
the last paragraph, or opens one; a blank line in the text starts a new paragraph; a marker split
|
|
3355
|
+
across two chunks resolves when its close arrives), `end()`, `stop()` (adds "Stopped here."),
|
|
3356
|
+
`setSources(sources)`, `setArtifactState(id, {expanded, controls})` (reflects whether the
|
|
3357
|
+
application has the artifact open somewhere), `getBlocks()`, `isStreaming()`, `toText()`,
|
|
3358
|
+
`toMarkdown()`, `destroy()`. A single line break in model text is kept (an address, a sign-off); a
|
|
3359
|
+
blank line starts a new paragraph.
|
|
3360
|
+
- **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
|
|
3361
|
+
`end` when a streamed answer is marked finished.
|
|
3362
|
+
- **Rendering** — code is a figure with its language, a copy button and a focusable `<pre>`
|
|
3363
|
+
(`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
|
|
3364
|
+
code read at length in an inspector),
|
|
3365
|
+
coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
|
|
3366
|
+
scrolls inside the answer and becomes a named, focusable region only while it overflows; figures
|
|
3367
|
+
are a `<dl>` with tabular numbers; a callout uses `.zx-callout` with its tone as `data-kind`.
|
|
3368
|
+
- **Static** — `renderBlocks(blocks, options)` returns a `DocumentFragment` for a transcript or a
|
|
3369
|
+
print view: citations are plain superscripts and artifacts plain cards. `blocksToMarkdown(blocks)`
|
|
3370
|
+
and `blocksToText(blocks)` export an answer for copying and search.
|
|
3371
|
+
- **State** — `data-state` is `streaming`, `done` or `stopped`; the root is `aria-busy` while it
|
|
3372
|
+
streams. Streamed text is never inside a live region.
|
|
3373
|
+
<!-- /doc -->
|
|
3374
|
+
|
|
3375
|
+
<!-- doc:agent-thread -->
|
|
3376
|
+
### AgentThread
|
|
3377
|
+
|
|
3378
|
+
A conversation with one or more agents, drawn from the items above: the person's messages, the
|
|
3379
|
+
agents' answers as they stream (`BlockView` with a `SourceList`), the steps a run took
|
|
3380
|
+
(`RunTrace`), the approvals that hold it (`ApprovalCard`), and one-line notices.
|
|
3381
|
+
|
|
3382
|
+
- **Options** — `items: []`, `authors: {}`, `me: 'me'` (the reader's author key; an item without
|
|
3383
|
+
`author` is the reader's when it is a `user` item), `label` (the feed's name, "Conversation"),
|
|
3384
|
+
`headingLevel: 3`, `emptyState: null` (`emptyState()` options shown while empty),
|
|
3385
|
+
`followOutput: true`, `scroller: null` (the element that scrolls; the nearest scrolling ancestor
|
|
3386
|
+
when null), `answerActions: ['copy', 'regenerate', 'branch']` (add `'rate'` for helpful / not
|
|
3387
|
+
helpful), `userActions: []` (`'edit'`, `'copy'` on the reader's own messages, revealed while the
|
|
3388
|
+
message is pointed at or holds focus), `icons` (glyphs for `regenerate`, `branch`, `rateUp`,
|
|
3389
|
+
`rateDown`, `edit`), `traceIcons` (handed to every `RunTrace` it draws), `now: null` (the clock
|
|
3390
|
+
"today" is measured against, for a world on fixed dates), `formatTime`, `locale`, `msg`.
|
|
3391
|
+
- **Item extras** — any item's `refs: [{id, label, icon?, entity?}]` draws links to the
|
|
3392
|
+
application's own things after its content (`open {item, ref}`); a `user` item's `mentions`
|
|
3393
|
+
(names, or `{name, tone}`) marks each `@name` in its text; an `answer`'s `steps` show the work it
|
|
3394
|
+
did inline above its text (`stepsOpen` opens them) and, like `stopped`, `rating` and `at`, follow
|
|
3395
|
+
its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
|
|
3396
|
+
"Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
|
|
3397
|
+
(`action {item, action: id}`); an author with an `icon` is drawn as a tinted tile instead of
|
|
3398
|
+
initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an `approval`'s
|
|
3399
|
+
`editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
|
|
3400
|
+
drawn later; `sourceIcons` is handed to every `SourceList`.
|
|
3401
|
+
- **Methods** — `setItems(items)`, `upsert(item)` (adds, or replaces in place by `id`),
|
|
3402
|
+
`patch(id, partial)` (an answer finishing, stopping or gaining sources, a trace's steps, an
|
|
3403
|
+
approval's status change in place; anything else redraws the item), `appendText(id, text)`
|
|
3404
|
+
(streams into an answer, creating it when the id is new), `appendBlock(id, block)` (adds a whole
|
|
3405
|
+
block — figures, a table — without redrawing the answer), `announce(text)` (says an outcome
|
|
3406
|
+
through the thread's polite status), `setArtifactState(id, {expanded, controls})` (whether an
|
|
3407
|
+
artifact is open in an inspector, on every card naming it), `remove(id)`, `get(id)`,
|
|
3408
|
+
`getItems()`, `getComponent(id)`, `reveal(target)` (`item:<id>`, `step:<id>`, `source:<n>`),
|
|
3409
|
+
`scrollToEnd()`, `destroy()`. The static `AgentThread.register(type, render)` draws an item type
|
|
3410
|
+
of the application's own; `render(item, {thread, author, own})` returns its content, and `own()`
|
|
3411
|
+
hands a component to the thread to destroy with the item.
|
|
3412
|
+
- **Events** — `action {item, action, value?}` (`copy`, `regenerate`, `branch`, `rate` with
|
|
3413
|
+
`up`/`down`/null, `version` with an index — preventable for `rate` and `version`; `edit` on the
|
|
3414
|
+
reader's message; a notice's action id), `open {item, ref, step?}` (an item's link, or a trace
|
|
3415
|
+
step's),
|
|
3416
|
+
`approve {item, values}`, `edit {item, values}`, `reject {item, reason}` (preventable: the card
|
|
3417
|
+
stays pending), `cite {item, n, source}` (preventable: by default the cited source is
|
|
3418
|
+
highlighted), `artifact {item, id}`, `reveal {target}`. Each reaches a listener on the thread's
|
|
3419
|
+
root once, as the thread's `zx-*` event: the cards, answers and traces inside it do not bubble
|
|
3420
|
+
their own copies past it. A source that names a `call` reveals that
|
|
3421
|
+
step in the trace.
|
|
3422
|
+
- **Turns** — consecutive items by the same agent read as one turn: the avatar and byline are drawn
|
|
3423
|
+
once, and the byline still names every article. The reader's own messages sit at the end as a
|
|
3424
|
+
bubble without an avatar.
|
|
3425
|
+
- **Following output** — while the reader is at the end, new output keeps the end in view;
|
|
3426
|
+
scrolled up, a "Jump to latest" button appears and the reader is never moved. While a streaming
|
|
3427
|
+
answer has nothing yet, a quiet line says who is writing.
|
|
3428
|
+
- **Narrow** — the thread is a size container; below 30rem the content takes the full width and
|
|
3429
|
+
the avatar stays beside the byline.
|
|
3430
|
+
- **Keyboard and semantics** — the APG feed pattern: each item is an `article` in a `role="feed"`
|
|
3431
|
+
with `aria-posinset`, `aria-setsize` and `aria-labelledby` its byline; PageDown and PageUp move
|
|
3432
|
+
between articles; Ctrl+End and Ctrl+Home move focus past the end or before the start of the feed.
|
|
3433
|
+
The feed is `aria-busy` while an answer streams. One polite status says when an agent starts
|
|
3434
|
+
writing, answers, needs approval, or is stopped — streamed text is never read aloud as it arrives.
|
|
3435
|
+
<!-- /doc -->
|
|
3436
|
+
|
|
3437
|
+
<!-- doc:run-status -->
|
|
3438
|
+
### RunStatus
|
|
3439
|
+
|
|
3440
|
+
Where an agent's run stands, for a run panel or a narrow header: the state as a glyph and a word,
|
|
3441
|
+
one sentence on what is happening, the steps as a progressbar, when it started and how long the
|
|
3442
|
+
agent has worked, the tokens, and the cost against a budget. It draws the values it is given and
|
|
3443
|
+
announces nothing itself; the thread the run belongs to announces its milestones.
|
|
3444
|
+
|
|
3445
|
+
- **Options** — `state` (a run state: `queued`, `running`, `waiting`, `paused`, `blocked`, `done`,
|
|
3446
|
+
`failed`, `stopped`, `skipped`; default `'queued'`, reflected as `data-state`), `summary` (one
|
|
3447
|
+
sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
|
|
3448
|
+
(local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
|
|
3449
|
+
it is a number), `tokens: [in, out]|number|null` (the pair, or the total as one number),
|
|
3450
|
+
`tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`,
|
|
3451
|
+
`actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
|
|
3452
|
+
`now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
|
|
3453
|
+
labels).
|
|
3454
|
+
- **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
|
|
3455
|
+
"3 of 6 steps"; the actions as small buttons; and a `<dl>` of Started, Working time, Waiting
|
|
3456
|
+
since (while `waiting`) or Blocked since (while `blocked`), Finished / Failed at / Stopped at
|
|
3457
|
+
(once the run is over), Model, Tokens ("18,420 in · 1,236 out", or "22,840" for a total) and
|
|
3458
|
+
Cost. With a `budget` the cost is a `role="meter"` reading "€0.14 of €2.00" whose `data-level`
|
|
3459
|
+
is `warning` from 80% and `danger` at 100%. With a `tokenBudget` the tokens are a meter the same
|
|
3460
|
+
way, in the locale's compact figures (`Intl.NumberFormat` `notation: 'compact'`): "22.8K of 60K
|
|
3461
|
+
tokens"; without one they stay text. A time on another day than today shows its date too.
|
|
3462
|
+
- **Blocked** — `blocked` is a glyph and the word "Blocked" in the danger tone, and the steps bar
|
|
3463
|
+
takes the danger tone. A blocked run is not over: it shows "Blocked since" from `waitingSince`
|
|
3464
|
+
and never a finished time.
|
|
3465
|
+
- **Compact** — `compact: true` (reflected as `data-compact`) draws only the state, glyph and
|
|
3466
|
+
word, as a pill for a header too narrow for the panel. `compact: 'icon'`
|
|
3467
|
+
(`data-compact="icon"`) draws the glyph alone, for a list row: the word stays in the pill,
|
|
3468
|
+
visually hidden, as its accessible text, and is the pill's `title` tooltip.
|
|
3469
|
+
- **Ticking** — while `state` is `running` and `ticking` is on, the working time counts on once a
|
|
3470
|
+
second from `workMs` and the moment of the last `update()`, through one interval that sleeps
|
|
3471
|
+
while the page is hidden. Leaving `running` freezes the clock where it stands. `now` replaces
|
|
3472
|
+
the clock, both for that count and for deciding whether a time is today; a fixed `now` makes the
|
|
3473
|
+
panel deterministic for screenshots and tests. It is fixed at construction.
|
|
3474
|
+
- **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
|
|
3475
|
+
not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
|
|
3476
|
+
the action at the same index, or the nearest one left. When no action is left the panel itself
|
|
3477
|
+
holds focus (`tabindex="-1"`, removed again once focus moves on).
|
|
3478
|
+
- **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
|
|
3479
|
+
update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
|
|
3480
|
+
(the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
|
|
3481
|
+
- **Events** — `action {index, action}`, after the descriptor's own `onclick`.
|
|
3482
|
+
<!-- /doc -->
|
|
3483
|
+
|
|
3484
|
+
<!-- doc:composer -->
|
|
3485
|
+
### Composer — the message box of an agent conversation
|
|
3486
|
+
|
|
3487
|
+
A text that grows with what is written, Send (Stop while the agent works), attachments, `@`
|
|
3488
|
+
mentions, `/` commands, extra tools and removable context chips. It keeps only the unsent message:
|
|
3489
|
+
`send` hands the text, files, mentions and context to the application, which owns the conversation
|
|
3490
|
+
and the transport.
|
|
3491
|
+
|
|
3492
|
+
- **Constructor** — `new Composer(null, options)` creates its own root; `new Composer(element,
|
|
3493
|
+
options)` takes over an element and restores it on `destroy()`.
|
|
3494
|
+
- **Options** — `label` (accessible name of the text and of the `role="group"` root, English
|
|
3495
|
+
`Message`), `placeholder`, `value`, `submitKey: 'enter'|'mod+enter'`, `busy: false`,
|
|
3496
|
+
`disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
|
|
3497
|
+
`maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
|
|
3498
|
+
description?, icon?}]` or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
|
|
3499
|
+
`tools: []` (`[{id, label, icon, pressed?, expanded?, controls?, disabled?}]` — `pressed` makes a
|
|
3500
|
+
toggle, `expanded`/`controls` a disclosure; see Tools), `icons: {}` (`attach`, `commands` glyphs),
|
|
3501
|
+
`context: [{id, label,
|
|
3502
|
+
icon?, ref?}]`, `hint` (quiet text beside Send), `note` (a quiet line under the composer, also
|
|
3503
|
+
its description), `sendLabel: null` (visible text on Send, see Send), `draftKey: null`,
|
|
3504
|
+
`minRows: 1` (the text never shrinks below it, even empty; capped at `maxRows`), `maxRows: 10`
|
|
3505
|
+
(it scrolls beyond), `msg`.
|
|
3506
|
+
- **Methods** — `focus()`, `getValue()`, `setValue(text)`, `insertText(text)` (types at the caret
|
|
3507
|
+
as the person would — text ending in `@` opens the suggestions), `clear()` (text, files and draft;
|
|
3508
|
+
context stays), `setBusy(busy)`, `isBusy()`, `setDisabled(disabled)`, `setHint(text)`,
|
|
3509
|
+
`setNote(text)` (an empty text hides either), `update(partial)`, `setTools(tools)`,
|
|
3510
|
+
`setToolPressed(id, pressed)`, `addFiles(files)`, `getFiles()`, `addContext(chip)` (replaces a
|
|
3511
|
+
chip with the same id), `removeContext(id)`, `getContext()`, `destroy()`. The setters emit
|
|
3512
|
+
nothing.
|
|
3513
|
+
- **update(partial)** — changes `label`, `placeholder`, `hint`, `note`, `submitKey`, `sendLabel`,
|
|
3514
|
+
`disabled` and `busy` in place; a key left out or `undefined` is kept, other keys are ignored.
|
|
3515
|
+
The text, its caret and selection, the focus, the attachments, the context chips and the draft
|
|
3516
|
+
all stay, so a placeholder that names the chosen model follows the model picker without
|
|
3517
|
+
recreating the composer: `composer.update({placeholder: 'Message Halden 3 Deep'})`.
|
|
3518
|
+
`label: null` returns to `composer.label`; an empty `placeholder` removes it.
|
|
3519
|
+
- **Events** — `send {text, files, mentions, context}` is preventable: unless prevented, the text,
|
|
3520
|
+
files and draft clear; it never fires with an empty text and no files, nor while busy. `text` is
|
|
3521
|
+
trimmed; `mentions` are the picked items whose `@<label>` is still in the text. `stop`,
|
|
3522
|
+
`input {text}`, `attach {files}` (preventable, before the files are added), `remove {kind:
|
|
3523
|
+
'file'|'context', id, file?, chip?}` (after the reader removes one), `mention {item}`,
|
|
3524
|
+
`command {item}` (the application's own item), `tool {id, tool}` (a copy of the tool as it
|
|
3525
|
+
stands, `pressed` included), `historyprevious`.
|
|
3526
|
+
- **Keyboard** — `submitKey: 'enter'`: Enter sends, Shift+Enter breaks the line;
|
|
3527
|
+
`'mod+enter'`: Cmd+Enter (Ctrl+Enter elsewhere) sends, Enter breaks the line. A key during an IME
|
|
3528
|
+
composition never sends. Escape closes the suggestions, otherwise emits `stop` while busy (and is
|
|
3529
|
+
left alone when idle, so a surrounding dialog can close). ArrowUp on an empty text emits
|
|
3530
|
+
`historyprevious`; `/` on an empty text opens the commands. In the suggestions, Up and Down move,
|
|
3531
|
+
Enter or Tab picks, Escape closes. Tools are ordinary buttons in the tab order (Enter or Space).
|
|
3532
|
+
No key is bound on the document.
|
|
3533
|
+
- **Tools** — icon buttons in the bar after Attach and Commands, each named by its `label` (also
|
|
3534
|
+
its `title` tooltip). A boolean `pressed` makes a toggle with `aria-pressed`, drawn with the
|
|
3535
|
+
neutral current fill and an edge; without it the tool is a plain button. Pressing one emits
|
|
3536
|
+
`tool`; the composer never changes `pressed` itself — call `setToolPressed(id, !tool.pressed)`.
|
|
3537
|
+
`setTools(tools)` redraws them, keeping the focus on the tool with the same id (on the text when
|
|
3538
|
+
that tool is gone or disabled). An entry without `id`, `label` or `icon` is left out, as is a
|
|
3539
|
+
repeated id; other fields on a tool are handed back in `tool`. `icon` is a built-in glyph name or
|
|
3540
|
+
one the application registered with `registerIcons()`. Tools are disabled with the composer.
|
|
3541
|
+
- **Send** — one button that swaps its glyph, name and `aria-keyshortcuts` between Send and Stop.
|
|
3542
|
+
With `sendLabel` (`'Start task'`) it shows the glyph and that text, which is also its accessible
|
|
3543
|
+
name; while busy it reads `composer.stop` ("Stop"). In a composer narrower than 24rem (a phone, a
|
|
3544
|
+
side column) the text is visually hidden and Send is the square glyph again — the text stays its
|
|
3545
|
+
accessible name and its tooltip.
|
|
3546
|
+
- **Mentions** — the query is the text after the trigger up to the caret, with no whitespace;
|
|
3547
|
+
picking writes `@<label> `. An array is filtered by label prefix, word prefix, label substring,
|
|
3548
|
+
then id prefix or a word of the description, ignoring case and accents. A function answers the
|
|
3549
|
+
query itself; a stale Promise is ignored.
|
|
3550
|
+
- **Commands** — opened in a `Launcher` the composer creates on first use and destroys with
|
|
3551
|
+
itself; an item with `items` opens a page. The commands keep the order given. A Commands button
|
|
3552
|
+
in the bar opens the same list for pointer and touch.
|
|
3553
|
+
- **Files** — the Attach button, pasting files, and dropping files on the composer (the root shows
|
|
3554
|
+
`data-state="dropping"` and a drop label meanwhile) add attachments, filtered by `accept` and
|
|
3555
|
+
capped by `maxFiles`.
|
|
3556
|
+
- **Accessibility** — the `<textarea>` keeps its textbox role. While suggestions show it carries
|
|
3557
|
+
`aria-autocomplete="list"`, `aria-controls` (the listbox) and `aria-activedescendant` (the
|
|
3558
|
+
highlighted `role="option"`), and a polite status says how many there are. Attachments and
|
|
3559
|
+
context chips are labelled lists, each chip with a button named "Remove <name>". Send is never
|
|
3560
|
+
disabled while the composer is live (it is `aria-disabled` when there is nothing to send), so
|
|
3561
|
+
the focus it holds survives a run ending. A toggled tool states itself with `aria-pressed`, not
|
|
3562
|
+
colour alone.
|
|
3563
|
+
- **Draft** — with `draftKey`, the unsent text is kept through `storage('composer')`, restored
|
|
3564
|
+
when the composer is created without a `value`, and cleared on send and `clear()`.
|
|
3565
|
+
<!-- /doc -->
|
|
3566
|
+
|
|
3567
|
+
<!-- doc:approval-card -->
|
|
3568
|
+
### ApprovalCard
|
|
3569
|
+
|
|
3570
|
+
A request that holds an agent's run until a person answers it: what the agent wants to do, what
|
|
3571
|
+
will happen, a preview of what it produces, and Approve, Edit, and Reject. Answered, it freezes
|
|
3572
|
+
into the record of what was decided, by whom, and when. The card never acts on its own — it emits
|
|
3573
|
+
the answer, and the application carries it out.
|
|
3574
|
+
|
|
3575
|
+
- **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
|
|
3576
|
+
'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `headingLevel: 3`,
|
|
3577
|
+
`status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
|
|
3578
|
+
amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
|
|
3579
|
+
is accepted for `content`, as the thread model spells it), `fields: Record<string,
|
|
3580
|
+
FieldOptions>|null` (the Edit form — no fields, no Edit), `values: {}`, `confirmText: null`,
|
|
3581
|
+
`reason: 'optional'|'required'|'none'` (whether Reject asks why), `answeredBy: null` (the verdict's
|
|
3582
|
+
"you" when null), `answeredAt: null` (local ISO date-time or Date), `edited: false`,
|
|
3583
|
+
`editedKeys: null` and `rejectReason: null` (for a card restored from a record), `now: null`
|
|
3584
|
+
(a `() => Date` clock), `keys: true`, and `msg`.
|
|
3585
|
+
- **Edited values** — `edited: true` lists every field under "Edited by you"; `editedKeys:
|
|
3586
|
+
['subject']` lists only those (in field order) and on its own marks the card edited. The card's
|
|
3587
|
+
own Edit flow keeps `editedKeys` as the union of every save so far, so a restored card and a
|
|
3588
|
+
card edited in place list the same thing.
|
|
3589
|
+
- **Events** — `approve {values}`, `edit {values, changed, editedKeys}`, `reject {reason}`, all
|
|
3590
|
+
**preventable** (on the component or on the bubbling `zx-*` event). Unless `approve` or `reject`
|
|
3591
|
+
is prevented the card moves to its answered state; a saved `edit` keeps it pending and adopts
|
|
3592
|
+
the values. `changed` names the fields this save changed. `editedKeys` is the union the card
|
|
3593
|
+
will list (null when it lists every field), so the application can store it with the record.
|
|
3594
|
+
Prevent an answer to refuse or defer it, then settle the card with `setStatus()`.
|
|
3595
|
+
- **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`,
|
|
3596
|
+
`details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
|
|
3597
|
+
place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
|
|
3598
|
+
now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
|
|
3599
|
+
included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
|
|
3600
|
+
`focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
|
|
3601
|
+
starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
|
|
3602
|
+
dialogs, including an open confirmation).
|
|
3603
|
+
- **Update in place** — `update()` is for a request the agent revises while it waits, or a record
|
|
3604
|
+
that changed. It redraws only what changed: values equal to what is drawn (compared by content,
|
|
3605
|
+
so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
|
|
3606
|
+
where it was. When the focused control goes away (Edit when `fields` go, the preview toggle when
|
|
3607
|
+
`preview` goes), focus moves to the card. A change closes a dialog only when the dialog no
|
|
3608
|
+
longer applies: new `fields` close the Edit form, a new `reason` closes the Reject dialog, a new
|
|
3609
|
+
`confirmText` closes the typed confirmation without approving. An open Edit form stays open over
|
|
3610
|
+
new `values`. Status goes through `setStatus()`. `update()` emits nothing.
|
|
3611
|
+
- **Approve** — with `confirmText`, Approve first opens `Dialog.confirm({confirmText, danger:
|
|
3612
|
+
true})` titled with the card's title; only a confirmed approval emits `approve`.
|
|
3613
|
+
- **Reject** — `reason: 'optional'` asks in a dialog with a textarea and accepts an empty answer;
|
|
3614
|
+
`'required'` keeps the Reject button disabled until the reason is non-empty; `'none'` rejects at
|
|
3615
|
+
once with `reason: ''`. Mod+Enter submits the Reject and Edit dialogs.
|
|
3616
|
+
- **Answered state** — no actions; the line under the title becomes the verdict ("Approved by you
|
|
3617
|
+
at 10:31"; the date is added when it is not today, by the `now` clock); the edited values and
|
|
3618
|
+
the reason (as a quote) stay. An answer given on the card, or a `setStatus()` without `at`,
|
|
3619
|
+
takes its time from `now`. `data-state` is the status, and the state pill is a `statusIcon()`
|
|
3620
|
+
glyph plus its word (waiting, done, skipped, stopped glyphs for pending, approved, rejected,
|
|
3621
|
+
expired).
|
|
3622
|
+
- **Keyboard** — A approves, E edits, R rejects, only while focus is inside the pending card, not
|
|
3623
|
+
in a text control, with no modifier held, and while none of the card's dialogs is open. The card
|
|
3624
|
+
binds no document key: an application that wants them from elsewhere forwards the event to
|
|
3625
|
+
`handleKey(event)`, which returns true and prevents the default when it used the key.
|
|
3626
|
+
`keys: false` stops the card listening on itself (and drops the key hints on its buttons).
|
|
3627
|
+
- **Accessibility** — `role="group"` labelled by the title heading and described by the
|
|
3628
|
+
description and the state line; a pending card says "The run is paused until you answer."
|
|
3629
|
+
(message `approvalCard.paused`). The preview toggle follows the APG Disclosure pattern.
|
|
3630
|
+
- **Consequence comes from the application** — whether an action needs `confirmText` (or
|
|
3631
|
+
`reason: 'required'`) is decided by the application from the tool the action triggers. It is
|
|
3632
|
+
never taken from model output: an agent that could set its own confirmation could also waive it.
|
|
3633
|
+
<!-- /doc -->
|
|
3634
|
+
|
|
3635
|
+
<!-- doc:run-trace -->
|
|
3636
|
+
### RunTrace
|
|
3637
|
+
|
|
3638
|
+
What an agent did during a run: a one-line summary ("Worked for 41 s · 5 tool calls · 9 sources ·
|
|
3639
|
+
1 retry") that opens into a timeline of its steps. A tool call opens to the arguments it was made
|
|
3640
|
+
with and what came back; a retry is drawn under the call it repeats; a hand-off shows both agents.
|
|
3641
|
+
The same component draws a plan: `task` steps under a `label` of the plan's own, the people's
|
|
3642
|
+
`ask` and `decision` steps among them, chosen one at a time with `selectable`. The trace changes
|
|
3643
|
+
only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
|
|
3644
|
+
|
|
3645
|
+
- **Options** — `steps: []` (`TraceStep[]`, in the order they started), `open: false` (the step
|
|
3646
|
+
list starts open), `label: null` (text the summary reads instead of the computed line — "Close
|
|
3647
|
+
September · 2 of 5 done"; every state but done still follows it as a word, "· Running"),
|
|
3648
|
+
`authors: {}` (who the steps' `actor` and `to` keys name), `showArguments: true`,
|
|
3649
|
+
`maxResult: 4000` (characters of a result shown before a "Show all" button; 0 shows every
|
|
3650
|
+
result whole), `summary: true` (false: no summary line, the list always shows — for a run panel
|
|
3651
|
+
whose state is told beside it), `kindIcons: null` (whether a step leads with its kind's glyph;
|
|
3652
|
+
null hides them for a plan whose steps are all `task`s), `selectable: false` (every step can be chosen, see Events), `ticking: false`
|
|
3653
|
+
(a running step that has `at` counts its time once a second, on from its `ms` when it was
|
|
3654
|
+
resumed), `now: null` (`() => Date`, the
|
|
3655
|
+
clock `ticking` counts against, for an application whose world is fixed on another date; real
|
|
3656
|
+
time when null), `formatTime: null` (`(at) => string`, how a step's start time is written;
|
|
3657
|
+
"10:31:05" when null), `icons: {}` (glyph per step kind over the built-in `search`→search,
|
|
3658
|
+
`read`→file, `query`→table, `write`→type, `run`→code, `call`→gear, `handoff`→link-2,
|
|
3659
|
+
`think`→dots, `task`→list, `ask`→mail, `decision`→check), `msg` (`runTrace.*` and the
|
|
3660
|
+
`agent.status.*` words).
|
|
3661
|
+
- **Methods** — `setSteps(steps)` (open steps stay open, focus stays on its step),
|
|
3662
|
+
`upsert(step)` (replaces the step with the same `id` and redraws only that step, keeping its
|
|
3663
|
+
retries, its open state, and focus on its row or links; a new step is appended, under the step
|
|
3664
|
+
it repeats when it has `retryOf`), `setLabel(text|null)` (null or `''` goes back to the computed
|
|
3665
|
+
line), `expand(id?)` (opens the list, and that step), `collapse(id?)` (closes the list, or only
|
|
3666
|
+
that step), `reveal(id)` (opens the list and the step, scrolls to it, focuses its row and marks
|
|
3667
|
+
it `data-state="revealed"` for 2 s; the scroll jumps under reduced motion), `getSteps()`,
|
|
3668
|
+
`isOpen()`, `destroy()` (also stops the clock).
|
|
3669
|
+
- **Events** — `toggle {id, open}` whenever the list (`id: null`) or a step opens or closes, from a
|
|
3670
|
+
click or a method; `reveal {id}`; `open {step, ref}` when one of a step's links is activated
|
|
3671
|
+
(copies; the application opens what the `ref` names); `select {id}` in a `selectable` trace when
|
|
3672
|
+
the reader activates a row with nothing to open, or opens a step's disclosure (not from
|
|
3673
|
+
`expand()` or `reveal()`, so an application can answer `select` with them).
|
|
3674
|
+
- **Rendering** — while a step runs the summary reads "Working…" with the step's `doing` line, and
|
|
3675
|
+
the step shows "Reading the policy…"; with `ticking` and an `at`, its end shows how long it has
|
|
3676
|
+
run ("41 s", "1 min 42 s"). A waiting or blocked run says so and names the step ("Blocked after
|
|
3677
|
+
12 s · 3 tool calls"); paused, stopped and failed runs say so first ("Failed after 12 s · 3
|
|
3678
|
+
tool calls"); a run no step of which has started reads "Not started · 6 steps". Counts are left
|
|
3679
|
+
out at zero, and `think`, `handoff`, `task`, `ask` and `decision` steps are not tool calls. Each
|
|
3680
|
+
step's muted meta line follows its label and wraps under it only when narrow: the `count`, a
|
|
3681
|
+
search's `sources`, the actor's name, the start time (`<time>`, tabular figures) and the
|
|
3682
|
+
`tokens` it used ("912 tokens"), each only when present. A step's `refs` (`ItemRef[]`, `{id,
|
|
3683
|
+
label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
|
|
3684
|
+
`icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
|
|
3685
|
+
name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
|
|
3686
|
+
otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
|
|
3687
|
+
`handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
|
|
3688
|
+
avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
|
|
3689
|
+
model — and its own label moves to the meta line.
|
|
3690
|
+
- **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
|
|
3691
|
+
(`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
|
|
3692
|
+
`<button>`. A step's links are buttons beside its row, never inside it, so no control holds
|
|
3693
|
+
another; each is reached with Tab. The running step carries `aria-current="step"`. Every state
|
|
3694
|
+
is a glyph and a word: visible for waiting, blocked, failed, stopped, skipped and queued steps
|
|
3695
|
+
(blocked and failed in the danger tone), visually hidden beside a finished step's duration and a
|
|
3696
|
+
running step's "…ing" line. The running glyph pulses only without a reduced-motion preference.
|
|
3697
|
+
The clock is one interval for the whole trace, running only while a counting step is in the open
|
|
3698
|
+
list and the page is visible. The trace has no live region; the thread it sits in announces
|
|
3699
|
+
milestones.
|
|
3700
|
+
- **State** — the root's `data-state` is the run's state (`running`, `waiting`, `blocked`,
|
|
3701
|
+
`paused`, `stopped`, `failed`, `queued`, `done`), and it is hidden while it has no steps. Each
|
|
3702
|
+
step's `<li>` carries `data-kind` and `data-status`.
|
|
3703
|
+
<!-- /doc -->
|
|
3704
|
+
|
|
3705
|
+
<!-- doc:source-list -->
|
|
3706
|
+
### SourceList
|
|
3707
|
+
|
|
3708
|
+
The sources an answer cites: a numbered chip (or row) for each, naming its site or title, with a
|
|
3709
|
+
card of its title, where it is, and the passage used on hover and focus. It never loads a favicon,
|
|
3710
|
+
a thumbnail, or any other remote resource.
|
|
3711
|
+
|
|
3712
|
+
- **Options** — `sources: []` (`Source[]`, numbered in order as the answer's `[n]` markers are),
|
|
3713
|
+
`label: 'Sources'` (the visible label naming the list; `''` drops it and names the list with
|
|
3714
|
+
the `sourceList.label` message), `layout: 'chips'|'list'` (`list` gives each source a row with
|
|
3715
|
+
its title and site), `numbered: true`, `icons: {}` (glyph per kind over the built-in
|
|
3716
|
+
`web`→link-2, `file`→file, `record`→table, `call`→gear), `msg`.
|
|
3717
|
+
- **Methods** — `setSources(sources)` (focus stays on the same source), `highlight(n)` (a number is
|
|
3718
|
+
the 1-based position, a string an `id`: scrolls to it, focuses it, and marks it
|
|
3719
|
+
`data-state="highlighted"` for 2 s — the answer to a BlockView `cite`), `getSources()`,
|
|
3720
|
+
`destroy()`.
|
|
3721
|
+
- **Events** — `select {source, n}`, **preventable** (on the component or on the bubbling
|
|
3722
|
+
`zx-select`). Unprevented, a `web` source opens its `href` in a new tab with
|
|
3723
|
+
`noopener,noreferrer`, and only when `safeHref()` accepts it and it is an absolute `https:` URL;
|
|
3724
|
+
the card shows that host. Every other kind is the application's to act on, for example
|
|
3725
|
+
`runTrace.reveal(source.call)`.
|
|
3726
|
+
- **Accessibility** — each source is a native `<button>` named "Source 1: bank.example" (the
|
|
3727
|
+
visible number and name, plus visually hidden words); its card is a `Tooltip`, so it is the
|
|
3728
|
+
button's description while open. The list is an `<ol>` labelled by the visible label. It is not
|
|
3729
|
+
a landmark, so a thread with many answers does not repeat a "Sources" region.
|
|
3730
|
+
- **Privacy** — the pure `sourceHref(source)` returns the only address a source may open, or null;
|
|
3731
|
+
nothing is fetched to draw a source.
|
|
3732
|
+
<!-- /doc -->
|
|
3733
|
+
|
|
3104
3734
|
<!-- doc:kernel -->
|
|
3105
3735
|
### Core helpers
|
|
3106
3736
|
|
|
@@ -3119,8 +3749,8 @@ bar.setBadge('mail', 8);
|
|
|
3119
3749
|
newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
|
|
3120
3750
|
triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
|
|
3121
3751
|
these functions globally or compose them into their own UI and routing layer.
|
|
3122
|
-
- **Icons** — `icon(name, {size, label})` and `
|
|
3123
|
-
by default, Font Awesome after an opt-in.
|
|
3752
|
+
- **Icons** — `icon(name, {size, label})`, `icons`, and `ICON_SIZE` (one size per role); see the
|
|
3753
|
+
Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
|
|
3124
3754
|
- **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
|
|
3125
3755
|
`{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
|
|
3126
3756
|
supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
|
|
@@ -3193,6 +3823,26 @@ old `RangeError`, at a call site that can afford to fail: a test, or a build-tim
|
|
|
3193
3823
|
Font Awesome elements are sized with `font-size` and occupy 1em; bundled SVGs use width/height
|
|
3194
3824
|
attributes (default 16). Both honour `label` (`null` ⇒ `aria-hidden`, otherwise `role="img"` +
|
|
3195
3825
|
`aria-label`).
|
|
3826
|
+
|
|
3827
|
+
**Size an icon by its role.** `ICON_SIZE` names one pixel size per role, so every chevron, every
|
|
3828
|
+
dismiss ×, and every check renders alike wherever it appears, and a call site says what a glyph is
|
|
3829
|
+
for rather than how big it is: `icon('chevron-down', { size: ICON_SIZE.chevron })`. The components
|
|
3830
|
+
use it throughout; use it in application code too, and never write a number for one of these roles.
|
|
3831
|
+
|
|
3832
|
+
- `ICON_SIZE.control` (16) — the default: an icon that is a control's content or leads its label.
|
|
3833
|
+
- `ICON_SIZE.chevron` (14) — dropdown, disclosure, and reorder chevrons; calendar and pager
|
|
3834
|
+
arrows; breadcrumb separators.
|
|
3835
|
+
- `ICON_SIZE.dismiss` (14) — the × that clears a field, closes a tab, dialog, or message, or
|
|
3836
|
+
removes a row.
|
|
3837
|
+
- `ICON_SIZE.check` (14) — the check of a selected option, a pressed toggle button, or a completed
|
|
3838
|
+
step.
|
|
3839
|
+
- `ICON_SIZE.sort` (14) — the sort-direction arrow beside a column heading.
|
|
3840
|
+
- `ICON_SIZE.chip` (12) — any glyph inside a chip or token, its remove × included.
|
|
3841
|
+
- `ICON_SIZE.marker` (8) — a glyph drawn inside a small status marker.
|
|
3842
|
+
|
|
3843
|
+
Several roles share a value and are named apart so one can change on its own. At 14px and below an
|
|
3844
|
+
outline is drawn with a one-pixel line, so the indicator roles also share a stroke weight. A text
|
|
3845
|
+
character is never a stand-in for an icon: draw "×", "✓", or an arrow with `icon()`.
|
|
3196
3846
|
<!-- /doc -->
|
|
3197
3847
|
|
|
3198
3848
|
<!-- doc:helpers -->
|
|
@@ -3298,7 +3948,8 @@ destroys its component.
|
|
|
3298
3948
|
|
|
3299
3949
|
Registered elements: `<zx-toggle>`, `<zx-check-button>`, `<zx-select items='[…]' required>`,
|
|
3300
3950
|
`<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
|
|
3301
|
-
`<zx-table>`, `<zx-dialog>`.
|
|
3951
|
+
`<zx-table>`, `<zx-dialog>`. `<zx-datebox>` takes `display-format` beside `format`, as the
|
|
3952
|
+
Datebox options `displayFormat` and `format`.
|
|
3302
3953
|
<!-- /doc -->
|
|
3303
3954
|
|
|
3304
3955
|
<!-- doc:tokens -->
|
|
@@ -3369,4 +4020,12 @@ record: native inputs, selects, and textareas inside it drop their border and fi
|
|
|
3369
4020
|
(`--zx-color-bg-hover`) or focus (the normal border, the control fill, and the focus ring), so values
|
|
3370
4021
|
read as text rather than as a wall of boxes. Read-only and disabled fields stay quiet. The rules have
|
|
3371
4022
|
zero specificity, so a component's own input styling still wins.
|
|
4023
|
+
|
|
4024
|
+
**Revealed actions.** Mark a row or a section heading `data-zx-reveal-host` and a secondary action
|
|
4025
|
+
inside it `data-zx-reveal`: the action rests invisible and appears while the host is pointed at,
|
|
4026
|
+
holds focus, is current or selected, or has a menu open. It keeps its space, so nothing shifts, and
|
|
4027
|
+
stays in the tab order, so focusing it shows it. On touch screens, under `prefers-contrast: more`
|
|
4028
|
+
and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
|
|
4029
|
+
that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
|
|
4030
|
+
visible. Hosts do not nest.
|
|
3372
4031
|
<!-- /doc -->
|