@zeyos/zx 5.5.0 → 5.7.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 +210 -0
- package/README.md +73 -7
- package/bin/zx-css.js +328 -0
- package/dist/types/components/account-menu/account-menu.d.ts +4 -2
- package/dist/types/components/activity-list/activity-list.d.ts +14 -8
- package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
- package/dist/types/components/agent-thread/agent-thread.d.ts +711 -0
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
- 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/block-view/block-view.d.ts +205 -0
- package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
- package/dist/types/components/calendar/calendar-model.d.ts +9 -2
- package/dist/types/components/calendar/calendar.d.ts +12 -4
- package/dist/types/components/chart/chart.d.ts +25 -13
- package/dist/types/components/code-editor/code-editor.d.ts +7 -2
- package/dist/types/components/composer/composer.d.ts +938 -0
- package/dist/types/components/composer/queue.d.ts +76 -0
- package/dist/types/components/copy/copy-button.d.ts +6 -4
- package/dist/types/components/copy/copy-input.d.ts +10 -6
- package/dist/types/components/datebox/date-range-box.d.ts +33 -0
- package/dist/types/components/datebox/placeholder.d.ts +7 -0
- package/dist/types/components/dock/dock.d.ts +12 -3
- package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
- package/dist/types/components/field-upload/field-upload.d.ts +3 -2
- package/dist/types/components/file-item/file-item.d.ts +3 -2
- package/dist/types/components/file-list/file-list.d.ts +14 -8
- package/dist/types/components/filter/filter-model.d.ts +31 -1
- package/dist/types/components/filter/filter.d.ts +20 -2
- package/dist/types/components/finder/finder.d.ts +14 -6
- package/dist/types/components/flag/flag.d.ts +99 -0
- package/dist/types/components/grid/grid.d.ts +1 -1
- package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
- package/dist/types/components/launcher/launcher.d.ts +2 -0
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
- package/dist/types/components/number-field/number-field.d.ts +17 -6
- package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
- package/dist/types/components/prose/prose.d.ts +9 -6
- package/dist/types/components/questionnaire/conditions.d.ts +270 -0
- package/dist/types/components/questionnaire/items.d.ts +52 -30
- package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
- package/dist/types/components/rating/rating.d.ts +5 -3
- 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/select/country.d.ts +106 -0
- package/dist/types/components/select/field-adapter.d.ts +2 -1
- package/dist/types/components/select/locale.d.ts +102 -0
- package/dist/types/components/select/select.d.ts +41 -2
- package/dist/types/components/slider/slider.d.ts +1 -0
- package/dist/types/components/sort-control/sort-control.d.ts +7 -3
- package/dist/types/components/source-list/source-list.d.ts +179 -0
- package/dist/types/components/split-view/split-view.d.ts +5 -3
- package/dist/types/components/surface/catalog.d.ts +260 -0
- package/dist/types/components/surface/elicit.d.ts +81 -0
- package/dist/types/components/surface/mcp.d.ts +165 -0
- package/dist/types/components/surface/schema.d.ts +314 -0
- package/dist/types/components/surface/stream.d.ts +118 -0
- package/dist/types/components/surface/surface.d.ts +718 -0
- package/dist/types/components/surface/text.d.ts +277 -0
- package/dist/types/components/surface/validate.d.ts +339 -0
- package/dist/types/components/table/table.d.ts +55 -3
- package/dist/types/components/table/window.d.ts +203 -0
- package/dist/types/components/toolbar/toolbar.d.ts +10 -6
- package/dist/types/components/tooltip/tooltip.d.ts +2 -2
- package/dist/types/components/tree/tree.d.ts +20 -13
- package/dist/types/core/component.d.ts +10 -0
- package/dist/types/core/date.d.ts +8 -1
- package/dist/types/core/dom.d.ts +1 -0
- package/dist/types/core/http.d.ts +10 -0
- package/dist/types/core/i18n.d.ts +38 -0
- package/dist/types/core/messages.d.ts +479 -1
- package/dist/types/core/storage.d.ts +7 -2
- package/dist/types/elements/define.d.ts +21 -46
- package/dist/types/elements/definitions.d.ts +147 -0
- package/dist/types/elements/kit.d.ts +7 -0
- package/dist/types/elements/reflect.d.ts +6 -3
- package/dist/types/index.d.ts +18 -1
- package/dist/types/internal/agent-model.d.ts +587 -0
- package/dist/types/internal/date-locale.d.ts +7 -0
- package/dist/types/internal/highlight.d.ts +24 -0
- package/dist/types/internal/json-patch.d.ts +146 -0
- package/dist/types/internal/presence-loop.d.ts +148 -0
- package/dist/types/locales/de.d.ts +13 -0
- package/dist/types/locales/en.d.ts +2 -0
- package/dist/types/locales/index.d.ts +823 -0
- package/dist/types/zeyos/view.d.ts +8 -1
- package/dist/zx-zeyos.esm.js +20505 -18748
- package/dist/zx-zeyos.esm.min.js +5 -5
- package/dist/zx.core.css +1276 -0
- package/dist/zx.core.min.css +1 -0
- package/dist/zx.css +2424 -134
- package/dist/zx.esm.js +46167 -28468
- package/dist/zx.esm.min.js +40 -8
- package/dist/zx.global.js +46167 -28468
- package/dist/zx.global.min.js +40 -8
- package/dist/zx.layered.css +17302 -0
- package/dist/zx.layered.min.css +1 -0
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +12501 -0
- package/docs/agent-surfaces.md +340 -0
- package/docs/api.json +2057 -166
- package/docs/llms.md +1458 -58
- package/docs/llms.txt +38 -8
- package/package.json +29 -6
- package/src/components/account-menu/account-menu.js +6 -3
- package/src/components/activity-item/activity-item.js +2 -1
- package/src/components/activity-list/activity-list.js +16 -10
- package/src/components/agent-thread/ag-ui.js +1439 -0
- package/src/components/agent-thread/agent-thread.css +417 -0
- package/src/components/agent-thread/agent-thread.js +1670 -0
- package/src/components/agent-thread/ui-message-stream.js +1281 -0
- package/src/components/app-sidebar/app-sidebar.js +18 -8
- package/src/components/approval-card/approval-card.css +289 -0
- package/src/components/approval-card/approval-card.js +1378 -0
- package/src/components/avatar/avatar.css +56 -1
- package/src/components/avatar/avatar.js +148 -26
- package/src/components/block-view/block-view.css +300 -0
- package/src/components/block-view/block-view.js +524 -0
- package/src/components/breadcrumb/breadcrumb.js +8 -5
- package/src/components/calendar/calendar-model.js +8 -2
- package/src/components/calendar/calendar.js +53 -18
- package/src/components/chart/chart.js +54 -23
- package/src/components/code-editor/code-editor.js +45 -8
- package/src/components/code-editor/field-adapter.js +1 -1
- package/src/components/composer/composer.css +482 -0
- package/src/components/composer/composer.js +1815 -0
- package/src/components/composer/queue.js +78 -0
- package/src/components/context-menu/context-menu.js +12 -1
- package/src/components/copy/copy-button.js +9 -7
- package/src/components/copy/copy-input.js +10 -6
- package/src/components/date-picker/date-picker.js +2 -1
- package/src/components/date-picker/date-range-picker.js +8 -7
- package/src/components/datebox/date-range-box.js +3 -9
- package/src/components/datebox/datebox.js +18 -21
- package/src/components/datebox/placeholder.js +18 -0
- package/src/components/dialog/dialog.js +1 -1
- package/src/components/dock/dock.js +34 -13
- package/src/components/entity-ref/entity-ref.js +16 -5
- package/src/components/field-upload/field-upload.js +81 -38
- package/src/components/file-item/file-item.js +70 -40
- package/src/components/file-list/file-list.js +15 -9
- package/src/components/filter/filter-model.js +46 -8
- package/src/components/filter/filter.css +3 -3
- package/src/components/filter/filter.js +29 -10
- package/src/components/filter-panel/filter-panel.js +13 -5
- package/src/components/finder/finder.js +50 -26
- package/src/components/flag/flag.css +40 -0
- package/src/components/flag/flag.js +177 -0
- package/src/components/form/form.js +1 -1
- package/src/components/grid/grid.js +22 -8
- package/src/components/kanban-view/kanban-view.js +51 -81
- package/src/components/launcher/launcher.js +17 -2
- package/src/components/list-toolbar/list-toolbar.js +2 -1
- package/src/components/master-panel/master-panel.js +1 -1
- package/src/components/menu-button/menu-button.js +4 -0
- package/src/components/message/message.js +3 -0
- package/src/components/multi-value-editor/multi-value-editor.js +10 -9
- package/src/components/navigation-bar/navigation-bar.js +3 -3
- package/src/components/number-field/number-field.js +29 -13
- package/src/components/prompt-starters/prompt-starters.css +91 -0
- package/src/components/prompt-starters/prompt-starters.js +206 -0
- package/src/components/prose/prose.js +14 -10
- package/src/components/questionnaire/conditions.js +666 -0
- package/src/components/questionnaire/items.js +150 -41
- package/src/components/questionnaire/questionnaire.js +126 -32
- package/src/components/rating/rating.js +5 -4
- 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/select/country.js +136 -0
- package/src/components/select/field-adapter.js +7 -2
- package/src/components/select/locale.js +219 -0
- package/src/components/select/select.css +20 -22
- package/src/components/select/select.js +94 -12
- package/src/components/sheet/sheet-stack.js +10 -1
- package/src/components/slider/slider.js +7 -2
- package/src/components/sort-control/sort-control.js +15 -5
- package/src/components/source-list/source-list.css +208 -0
- package/src/components/source-list/source-list.js +358 -0
- package/src/components/split-view/split-view.js +5 -3
- package/src/components/surface/catalog.js +1334 -0
- package/src/components/surface/elicit.js +107 -0
- package/src/components/surface/mcp.js +243 -0
- package/src/components/surface/schema.js +644 -0
- package/src/components/surface/stream.js +245 -0
- package/src/components/surface/surface.css +308 -0
- package/src/components/surface/surface.js +2291 -0
- package/src/components/surface/text.js +513 -0
- package/src/components/surface/validate.js +2218 -0
- package/src/components/tabbox/tabbox.js +9 -0
- package/src/components/table/table.css +63 -3
- package/src/components/table/table.js +167 -28
- package/src/components/table/window.js +317 -0
- package/src/components/toolbar/toolbar.js +12 -7
- package/src/components/tooltip/tooltip.css +2 -3
- package/src/components/tooltip/tooltip.js +32 -5
- package/src/components/tree/tree.js +53 -23
- package/src/core/component.js +25 -1
- package/src/core/date.js +62 -16
- package/src/core/dom.js +22 -2
- package/src/core/format.js +15 -13
- package/src/core/http.js +29 -20
- package/src/core/i18n.js +83 -10
- package/src/core/keyboard.js +79 -8
- package/src/core/messages.js +519 -2
- package/src/core/overlay-host.js +1 -0
- package/src/core/storage.js +59 -6
- package/src/elements/define.js +178 -130
- package/src/elements/definitions.js +229 -0
- package/src/elements/kit.js +444 -0
- package/src/elements/reflect.js +8 -3
- package/src/index.js +18 -1
- package/src/internal/agent-model.js +488 -0
- package/src/internal/date-locale.js +11 -0
- package/src/internal/highlight.js +104 -0
- package/src/internal/json-patch.js +405 -0
- package/src/internal/presence-loop.js +343 -0
- package/src/locales/de.js +911 -0
- package/src/locales/en.js +2 -0
- package/src/locales/index.js +7 -0
- package/src/zeyos/calendar.js +2 -1
- package/src/zeyos/form.js +2 -1
- package/src/zeyos/launcher.js +7 -6
- package/src/zeyos/module-bar.js +2 -1
- package/src/zeyos/schema.js +37 -23
- package/src/zeyos/select.js +4 -3
- package/src/zeyos/table.js +2 -13
- package/src/zeyos/view.js +57 -17
- package/styles/core.css +11 -0
- package/styles/tokens/semantic.css +1 -0
- package/styles/zeyos.css +2 -0
- package/styles/zx.css +11 -8
- package/styles/zx.layered.css +1 -0
package/docs/llms.md
CHANGED
|
@@ -9,6 +9,18 @@
|
|
|
9
9
|
> component below is wrapped in `<!-- doc:<name> -->` markers so tools can extract a single
|
|
10
10
|
> component's section (`website/docs.html` renders them as each component's Reference tab).
|
|
11
11
|
|
|
12
|
+
## Optional integration requirements
|
|
13
|
+
|
|
14
|
+
Zx has no package runtime dependencies and its source modules import no external runtime packages.
|
|
15
|
+
Optional integrations still need application-provided assets or clients. `Chart` requires an injected
|
|
16
|
+
renderer; the only supplied renderer, `ChartJsAdapter`, requires Chart.js 4 supplied by the host.
|
|
17
|
+
There is no built-in chart renderer. Chart.js 4.5.1 is pinned as a development dependency and copied
|
|
18
|
+
to the documentation site's self-hosted vendor assets during its build; it is not bundled into Zx.
|
|
19
|
+
Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
|
|
20
|
+
ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
|
|
21
|
+
ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
|
|
22
|
+
requires an injected compatible client and never imports the client package.
|
|
23
|
+
|
|
12
24
|
## Mental model
|
|
13
25
|
|
|
14
26
|
Every visual component is an ES class extending `Component`, instantiated identically:
|
|
@@ -44,11 +56,52 @@ const t = new Table(target, options);
|
|
|
44
56
|
- ESM: `import { … } from '/assets/zx.esm.js'` (or `../src/index.js` in-repo, no build).
|
|
45
57
|
- Granular: `import { Slider } from '@zeyos/zx/src/components/slider/slider.js'` — one component
|
|
46
58
|
rather than the whole library, for consumers running a bundler. Two components bundle 26 kB
|
|
47
|
-
minified against 157 kB through the package entry.
|
|
59
|
+
minified against 157 kB through the package entry. `zx-css` does the same for the stylesheet.
|
|
48
60
|
- Global: `<script src="/assets/zx.global.js">` → `window.zx.*`.
|
|
49
|
-
- Styles: load `/assets/zx.css` once.
|
|
61
|
+
- Styles: load `/assets/zx.css` once, or one of the stylesheets below.
|
|
50
62
|
- Build bundles with `npm run build` (esbuild). No build is needed to develop against `src/`.
|
|
51
63
|
|
|
64
|
+
Use one entry family for component instances and their registrations: source modules share the
|
|
65
|
+
source `Field` registry, while each distribution bundle contains its own classes and registry.
|
|
66
|
+
An adapter registered through a distribution bundle does not register a separately imported source
|
|
67
|
+
`Field`; import the related components from the same entry family.
|
|
68
|
+
|
|
69
|
+
### Stylesheets
|
|
70
|
+
|
|
71
|
+
| Load | It holds | Choose it when |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| `@zeyos/zx/zx.css`, `zx.min.css` | the whole library | the default |
|
|
74
|
+
| a file written by `zx-css` | the core sheet and the components named, with what they depend on | an application uses a few components |
|
|
75
|
+
| `@zeyos/zx/zx.layered.css` | the whole library in `@layer zx` | the application's own CSS should win without specificity work |
|
|
76
|
+
| `@zeyos/zx/zx.core.css`, `zx.core.min.css` | tokens, base rules, icons, reading type | composing stylesheets by hand |
|
|
77
|
+
| `@zeyos/zx/src/components/select/select.css` | one component's own rules | composing stylesheets by hand |
|
|
78
|
+
| `@zeyos/zx/styles/zeyos.css` | ZeyOS module colours | optional product palette for the ZeyOS binding |
|
|
79
|
+
|
|
80
|
+
**`zx-css`** ships with the package and runs on Node alone:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
npx zx-css select table --out public/zx.css # one stylesheet for these components
|
|
84
|
+
npx zx-css select table --out public/zx.css --min --layer
|
|
85
|
+
npx zx-css select table --list # the files it contains, in order
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The file starts with the core sheet, then every stylesheet the components reach, in `zx.css` order,
|
|
89
|
+
each once. A component reaches another by importing it, and by naming a `zx-<block>` class in the
|
|
90
|
+
source of any module it imports, because a component may draw another's markup without importing it.
|
|
91
|
+
A name is the file name of a stylesheet under `src/components/`: `select`, `progress-bar`,
|
|
92
|
+
`button` for `button()`, `layout` for `stack()` and `grid()`. An unknown name fails and lists the
|
|
93
|
+
known ones. Name what the page draws by hand as well: a `Form` that uses `type: 'zxselect'` needs
|
|
94
|
+
`form select`, because a field type is registered at run time, not imported. The print rules are not
|
|
95
|
+
part of a subset: a page that prints loads `@zeyos/zx/styles/print.css` after it.
|
|
96
|
+
|
|
97
|
+
**The layered build** puts the whole library in `@layer zx`, and an unlayered rule beats any layered
|
|
98
|
+
one whatever its specificity, so `button { padding: 0 }` overrides `.zx-btn[data-size="sm"]` with no
|
|
99
|
+
`!important`. The trade-off is that this holds for every unlayered rule on the page, not just the
|
|
100
|
+
application's: a reset or a third-party stylesheet that is not in a layer overrides Zx just as
|
|
101
|
+
easily. Choose `zx.layered.css` (or `zx-css --layer`) when the application controls the CSS on its
|
|
102
|
+
pages, and stay on `zx.css` when it does not. `!important` turns the other way round: one inside the
|
|
103
|
+
layer beats an unlayered one.
|
|
104
|
+
|
|
52
105
|
## Choosing what to build with
|
|
53
106
|
|
|
54
107
|
Three decisions come before any code: which **layout** the screen is, which **component** does
|
|
@@ -422,6 +475,10 @@ await zeyos.api.updateTransaction({ ID, status: 9 });
|
|
|
422
475
|
Feed results straight into Zx components (Table `data`, Select `items`, Form values). See the
|
|
423
476
|
`website/layouts/zeyos-invoices.layout.js` layout for the reference integration. Zx also ships a minimal `Http` /
|
|
424
477
|
`zeyosService(service, accesskey)` for ad-hoc `remotecall`, but `@zeyos/client` is the default.
|
|
478
|
+
`Http.request(path, options)` accepts a caller `signal` and multipart `paramName` (default
|
|
479
|
+
`'files'`). Caller cancellation aborts the request; the client's timeout rejects with
|
|
480
|
+
`TimeoutError`. Legacy envelopes with `error: false`, `0`, `null`, or no error return `result`;
|
|
481
|
+
string and object errors reject.
|
|
425
482
|
|
|
426
483
|
<!-- doc:zeyos -->
|
|
427
484
|
## ZeyOS binding (zx-zeyos)
|
|
@@ -505,6 +562,12 @@ await records.saveView({ name: 'My open invoices', setDefault: true });
|
|
|
505
562
|
paging and server sort. Paging is the same loader as `zeyosTable()` — same `pageSize: 50` default,
|
|
506
563
|
validation, `replace`/`pageSize` load options, and destroy guard. Title, preview, group, column, and swim-lane fields stay in the projection
|
|
507
564
|
even when hidden. Without `savedViews`, the host may persist `view.getViewState()` directly.
|
|
565
|
+
`savedViewFallback: 'error'` is the default: a saved-view initialization failure blocks loads.
|
|
566
|
+
Opt into `'baseline'` to load records using the configured query and sort when the registry
|
|
567
|
+
cannot be read. The failure is reported and `ready` still rejects; capture, save, apply, and
|
|
568
|
+
default restoration remain blocked. Later operations retry initialization so repaired storage
|
|
569
|
+
can restore its default. The unreadable document is never rewritten automatically, and a
|
|
570
|
+
failure while applying a view or query cannot fall back.
|
|
508
571
|
- `createSavedViewRegistry(transport, {userId,workspaceId,resource})` coordinates private named
|
|
509
572
|
Table/Card/Kanban configurations as one versioned, atomically replaced document. Entries capture
|
|
510
573
|
component state plus filters/search and an explicit presentation type, never records, selection,
|
|
@@ -563,7 +626,8 @@ registerModules({ tickets: '#f04639', 'my-fork': { label: 'My Fork', icon: 'zeyo
|
|
|
563
626
|
```
|
|
564
627
|
|
|
565
628
|
- `moduleIcon(name, {size, label, standard})` → the bare glyph; `standard: true` uses the stock
|
|
566
|
-
Font Awesome fallback, for pages on a kit without the ZeyOS uploads.
|
|
629
|
+
Font Awesome fallback, for pages on a kit without the ZeyOS uploads. Stock Font Awesome
|
|
630
|
+
CSS or kit assets must still be loaded by the host.
|
|
567
631
|
- `moduleChip(name, {size, iconSize, label, title, standard})` → `<span class="zx-module-icon">`
|
|
568
632
|
with a centred white glyph on the module colour. `moduleGlyphColor(hex)` remains available as a
|
|
569
633
|
separate contrast helper for non-AppIcon integrations that deliberately choose their foreground.
|
|
@@ -616,7 +680,10 @@ new ModuleBar(header, buildZeyosModuleBarConfig(state, { orientation: 'horizonta
|
|
|
616
680
|
`defineElements()` (not auto-called) registers light-DOM `<zx-*>` wrappers with attribute↔option
|
|
617
681
|
reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-button>`, `<zx-select>`,
|
|
618
682
|
`<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
|
|
619
|
-
`<zx-table>`, `<zx-dialog>`.
|
|
683
|
+
`<zx-table>`, `<zx-dialog>`. The agent kit and the data views are elements too, with forwarded
|
|
684
|
+
methods and events under their plain names: `<zx-agent-thread>`, `<zx-composer>`, `<zx-block-view>`,
|
|
685
|
+
`<zx-run-trace>`, `<zx-approval-card>`, `<zx-source-list>`, `<zx-run-status>`, `<zx-card-view>`,
|
|
686
|
+
`<zx-kanban-view>`, `<zx-tree>`, `<zx-chart>`.
|
|
620
687
|
|
|
621
688
|
---
|
|
622
689
|
|
|
@@ -749,9 +816,9 @@ items that overflow — removing them from the tab order and the roving group
|
|
|
749
816
|
a `MenuButton`, where choosing one activates the original control.
|
|
750
817
|
|
|
751
818
|
- **Options** — `items: [Element | '-' | {name, label, icon, kind, size, disabled, title, active,
|
|
752
|
-
onclick}]`, `align: 'start'|'end'|'between'`, `label` (accessible name, default `
|
|
753
|
-
`overflow` (default `true`), `overflowLabel` (default `
|
|
754
|
-
item as a pressed toggle (`aria-pressed`).
|
|
819
|
+
onclick}]`, `align: 'start'|'end'|'between'`, `label` (accessible name, by default the `toolbar.label` message),
|
|
820
|
+
`overflow` (default `true`), `overflowLabel` (by default the `toolbar.more` message), `dense`; `null` gives either
|
|
821
|
+
no name. `active` renders the item as a pressed toggle (`aria-pressed`).
|
|
755
822
|
- **Methods** — `setItems()`, `getItem(name)`, `enable(name)`, `disable(name)`,
|
|
756
823
|
`setActive(name, active?)`, `destroy()`.
|
|
757
824
|
- **Events** — `action {name, item}`, emitted for descriptor-built items in addition to their own
|
|
@@ -998,14 +1065,28 @@ and the component is decorative by default so adjacent identity text is not anno
|
|
|
998
1065
|
- **Options** — `src`, `name`, `initials`, `label`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 /
|
|
999
1066
|
40px at the default spacing unit), `shape: 'circle'|'rounded'|'square'`, `tone:
|
|
1000
1067
|
'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'|null`, `status:
|
|
1001
|
-
'online'|'away'|'busy'|'offline'|null`,
|
|
1068
|
+
'online'|'away'|'busy'|'offline'|null`, `statusLabel`, `activity:
|
|
1069
|
+
'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`, `activityLabel`, `animate: false`, and `phase: null|number`.
|
|
1002
1070
|
- **Fallback** — no ring; the `--zx-color-tone-*-bg` fill with its `-fg` ink, initials at 0.4× the
|
|
1003
1071
|
size (never under 10px), weight 600, one initial below 24px. `tone: null` derives the tone with
|
|
1004
1072
|
`avatarTone(name)` (exported from the module): FNV-1a over the trimmed, NFC-normalised,
|
|
1005
1073
|
lower-cased name, mapped onto the eight chromatic tones, so a person keeps their colour on every
|
|
1006
1074
|
screen. `slate`, the neutral, is reserved for an avatar with no name and can be set explicitly.
|
|
1007
1075
|
The root carries `data-tone`. `avatarInitials(name, limit = 2)` returns the initials.
|
|
1008
|
-
- **
|
|
1076
|
+
- **Agent activity** — `activity` draws what an agent is doing as a dot whose shape differs as
|
|
1077
|
+
well as its tone: solid success (working), solid info (thinking), solid warning (needs you), a
|
|
1078
|
+
danger square (blocked), a hollow ring (idle), and a dashed ring (offline). Its word ("Needs
|
|
1079
|
+
you", or `activityLabel`) joins the accessible name and the dot's tooltip, and the root carries
|
|
1080
|
+
`data-activity`. When both are given, `activity` wins over `status`. `animate: true` moves the
|
|
1081
|
+
avatar with its activity — idle breathes, thinking sways, working bobs, needs-you leans and
|
|
1082
|
+
blinks — in the one `requestAnimationFrame` loop every animated avatar on the page shares: only
|
|
1083
|
+
on screen, never while the page is hidden, and back at rest under reduced motion (the system's
|
|
1084
|
+
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
|
|
1085
|
+
(whole turns wrap): two avatars of one agent on the same screen — a roster and an inspector —
|
|
1086
|
+
at `phase: 0` and `phase: 0.5` move half a cycle apart. `null` derives the phase from the name
|
|
1087
|
+
(or the initials), so avatars of the same agent without a phase move in step.
|
|
1088
|
+
- **Methods** — `set(values)` (any option above, `phase` included, applied while the avatar moves), `setStatus(status, label?)`,
|
|
1089
|
+
`setActivity(activity, label?)`, `getActivity()`, `hasImage()`, `destroy()`.
|
|
1009
1090
|
- **Accessibility** — set `label` only when the avatar stands alone. Presence is supplementary
|
|
1010
1091
|
status, not the account's accessible name; supply `statusLabel` when it conveys information.
|
|
1011
1092
|
<!-- /doc -->
|
|
@@ -1067,8 +1148,9 @@ preview, or persists a file.
|
|
|
1067
1148
|
An accessible ordered collection of `FileItem` rows with loading and empty presentations.
|
|
1068
1149
|
Explicit duplicate file IDs are rejected; source order is preserved.
|
|
1069
1150
|
|
|
1070
|
-
- **Options** — `items`, `label
|
|
1071
|
-
|
|
1151
|
+
- **Options** — `items`, `label`, `loading`, `loadingCount: 3`, `loadingText`, and `emptyText` (text,
|
|
1152
|
+
Node, or Component). Unset, the three read the `fileList.*` messages; `loadingText` or `emptyText`
|
|
1153
|
+
set to `null` shows no text.
|
|
1072
1154
|
- **Methods** — `setItems(items,{silent?})`, `getItems()`, `getItem(id)`,
|
|
1073
1155
|
`addItem(item,index?,{silent?})`, `updateItem(id,values,{silent?})`,
|
|
1074
1156
|
`removeItem(id,{silent?})`, `setLoading()`, and `destroy()`.
|
|
@@ -1110,8 +1192,9 @@ incremental host-controlled mutation. It deliberately preserves source order ins
|
|
|
1110
1192
|
whether a feed is newest- or oldest-first.
|
|
1111
1193
|
|
|
1112
1194
|
- **Options** — `items`, `groupBy` (property, resolver, or null), `groupLabel`,
|
|
1113
|
-
`label
|
|
1114
|
-
`
|
|
1195
|
+
`label`, `variant: 'default'|'compact'`, `loading`, `loadingCount: 3`, `loadingText`, `emptyText`,
|
|
1196
|
+
`groupHeadingLevel`, and `itemHeadingLevel`. Unset, `label`, `loadingText` and `emptyText` read the
|
|
1197
|
+
`activityList.*` messages; `loadingText` or `emptyText` set to `null` shows no text.
|
|
1115
1198
|
- **Compact** — `variant: 'compact'` (reflected as `data-variant`) keeps every entry on one line at
|
|
1116
1199
|
any width, for a summary card narrower than 30rem: actor and title read as one sentence that
|
|
1117
1200
|
wraps as text, the time keeps the trailing end instead of stacking under the title, an avatar
|
|
@@ -1257,6 +1340,68 @@ Unifies single-select, local filtering, and async loading.
|
|
|
1257
1340
|
as a disabled Field does, and not a second time inside one.
|
|
1258
1341
|
- **Quiet fields** — inside `[data-zx-fields="quiet"]` the value reads as text: no border, fill,
|
|
1259
1342
|
chevron or clear button until hover; full field chrome while focused or open.
|
|
1343
|
+
|
|
1344
|
+
#### Select.locale()
|
|
1345
|
+
|
|
1346
|
+
`Select.locale(target, options)` returns an ordinary Select: each locale is named in its own language ("Deutsch") with the interface's
|
|
1347
|
+
name for it beneath ("German"), and the flag of its region or a language chip before it. Names come
|
|
1348
|
+
from `Intl.DisplayNames`, so no translation table ships. The value is the canonical BCP 47 tag
|
|
1349
|
+
(`'de-AT'`); `set()` and `value` accept any spelling of a listed tag (`'de_at'`). Everything else —
|
|
1350
|
+
keyboard map, events, `clearable`, `disabled`, `msg` — is Select's. Field type: `zxselect` with
|
|
1351
|
+
`props.preset: 'locale'`.
|
|
1352
|
+
|
|
1353
|
+
The picker supplies locale names, not translations for the application. It emits `change` without
|
|
1354
|
+
changing the active language. See the [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales)
|
|
1355
|
+
for catalogues, message variables, formatting, and runtime language switching.
|
|
1356
|
+
|
|
1357
|
+
```js
|
|
1358
|
+
Select.locale(el, { locales: ['en-GB', 'de', 'de-AT', 'fr'], value: 'de' });
|
|
1359
|
+
```
|
|
1360
|
+
|
|
1361
|
+
- **Options** — `locales` (tags or `{code, name?, description?, region?}`; invalid tags are left
|
|
1362
|
+
out; a short list of common languages by default), `preferred: []` and `preferredLabel` (pinned
|
|
1363
|
+
above the list), `displayLocale` (default: the `lang` option, then `getLanguage()`),
|
|
1364
|
+
`display: 'both'|'native'|'localized'`, `flags: 'auto'|'emoji'|'code'|'none'|(region, item) => Node`,
|
|
1365
|
+
`flagUrl` (image template, `{code}`/`{CODE}`), `flagRegions` (`{ en: 'GB' }` — a language's flag
|
|
1366
|
+
when its likely region is not the one meant), `sort: false`, plus Select options. Message overrides
|
|
1367
|
+
retain the `localePicker.*` keys. A list longer
|
|
1368
|
+
than seven filters locally by native name, localized name, and tag.
|
|
1369
|
+
- **Flags** — a full-tag `flagRegions` override wins, then the tag's own region (`de-AT` → Austria),
|
|
1370
|
+
then a language-level override, then the language's likely region (`Intl.Locale#maximize()`:
|
|
1371
|
+
`ja` → Japan). A locale with no country (`es-419`) shows
|
|
1372
|
+
its language chip. `flags: 'code'` shows chips throughout — the honest choice where a language is
|
|
1373
|
+
not a country.
|
|
1374
|
+
- **Statics** — `Select.localeItems(locales, options)` returns the rows without the DOM;
|
|
1375
|
+
`canonicalLocale(tag)` canonicalizes one tag.
|
|
1376
|
+
|
|
1377
|
+
#### Select.country()
|
|
1378
|
+
|
|
1379
|
+
`Select.country(target, options)` returns an ordinary Select: a filterable list of ISO 3166-1 countries, named in the interface's language by
|
|
1380
|
+
`Intl.DisplayNames` and drawn with their flags. The value is the upper-case alpha-2 code (`'DE'`);
|
|
1381
|
+
`set()` accepts either case. Search matches the name, the code, and the English name, so "Germany"
|
|
1382
|
+
finds Deutschland in a German interface. Field type: `zxselect` with `props.preset: 'country'`.
|
|
1383
|
+
Custom descriptions are searchable too. Its `displayLocale` names countries without changing the
|
|
1384
|
+
application language; see the [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales).
|
|
1385
|
+
|
|
1386
|
+
```js
|
|
1387
|
+
Select.country(el, { preferred: ['DE', 'AT', 'CH'], value: 'AT', clearable: true });
|
|
1388
|
+
```
|
|
1389
|
+
|
|
1390
|
+
- **Options** — `countries` (codes or `{code, name?, description?}`; all of `COUNTRY_CODES` by
|
|
1391
|
+
default), `preferred: []` and `preferredLabel`, `displayLocale`, `flags`, `flagUrl`,
|
|
1392
|
+
`showCode: false`, `sort: true` (by name, with `Intl.Collator`), plus Select options. Message
|
|
1393
|
+
overrides retain the `countryPicker.*` keys.
|
|
1394
|
+
- **Statics** — `Select.countryItems(countries, options)` returns the rows without the DOM.
|
|
1395
|
+
|
|
1396
|
+
#### flag()
|
|
1397
|
+
|
|
1398
|
+
`flag(code, { kind, src, text, label })` draws one flag as a `.zx-flag` span — for a picker row, a
|
|
1399
|
+
table cell, a profile. `kind: 'auto'` (default) draws the platform's flag emoji where it has them
|
|
1400
|
+
(`supportsFlagEmoji()`) and a muted code chip where it does not (Windows); `'emoji'`, `'code'`, and
|
|
1401
|
+
`'image'` force one. Zx ships no flag artwork: `src: '/flags/{code}.svg'` draws from any flag set
|
|
1402
|
+
the application serves. Decorative (`aria-hidden`) unless `label` is given. Also exported:
|
|
1403
|
+
`flagEmoji(code)`, `supportsFlagEmoji()`, and `COUNTRY_CODES`.
|
|
1404
|
+
|
|
1260
1405
|
<!-- /doc -->
|
|
1261
1406
|
|
|
1262
1407
|
<!-- doc:sort-control -->
|
|
@@ -1267,7 +1412,8 @@ appears once. Changing fields preserves direction; toggling direction preserves
|
|
|
1267
1412
|
from `Select`, with its themed popover and keyboard behavior.
|
|
1268
1413
|
|
|
1269
1414
|
- **Options** — `fields: [{id,label}]`, `value: {id,dir:'asc'|'desc'}` (null selects the first field
|
|
1270
|
-
ascending), `label
|
|
1415
|
+
ascending), `label` (by default the `sortControl.label` message, and `null` gives no name), `labels: {asc,desc}` to override
|
|
1416
|
+
the `sortControl.ascending` and `sortControl.descending` messages, `disabled`.
|
|
1271
1417
|
- **Methods** — defensive `getValue()`, `setValue(value,{silent})`, `enable()`, `disable()`,
|
|
1272
1418
|
`focus()`, `destroy()`. Unknown fields or directions are rejected. An empty catalogue disables
|
|
1273
1419
|
selection and returns null.
|
|
@@ -1355,7 +1501,7 @@ from; everything Zx adds is chrome around it. Field type: `slider`.
|
|
|
1355
1501
|
- **Methods** — `get()`, `set(value, {silent})`, `setRange(min, max, step?)`, `setLabel()`,
|
|
1356
1502
|
`setReadonly()`, `focus()`, `enable()`/`disable()`. `value` is also a getter/setter.
|
|
1357
1503
|
- **Events** — `input {value}` continuously while dragging, `change {value}` once the value is
|
|
1358
|
-
committed (pointer released,
|
|
1504
|
+
committed (pointer released, a range key pressed, or the optional number box committed).
|
|
1359
1505
|
- **Behaviour** — values snap to the step grid anchored at `min`, so 5…95 by 10 gives 5, 15, 25 —
|
|
1360
1506
|
not 10, 20, 30. Bounds win over the grid, so a `max` that is not a whole number of steps above
|
|
1361
1507
|
`min` stays reachable. A fractional step snaps to the decimals it carries: 0.1 gives 0.3, never
|
|
@@ -1379,7 +1525,7 @@ to a hidden textarea when the async Clipboard API is unavailable or denied.
|
|
|
1379
1525
|
→ `HTMLButtonElement`.
|
|
1380
1526
|
- **Options** — `text: ''` — a string, or **a function returning one**, which is what a button
|
|
1381
1527
|
beside a live value needs so the copy is never stale; `label: ''` (empty renders an icon-only
|
|
1382
|
-
ghost button), `title
|
|
1528
|
+
ghost button), `title`, `feedback` (by default the `copy.copy` and `copy.copied` messages, and `null` gives no text), `feedbackDuration: 2000`,
|
|
1383
1529
|
`size: 'md'|'sm'`, `kind: 'default'|'primary'|'ghost'`.
|
|
1384
1530
|
- **Events** — `oncopy(text, copied)` is called for every attempt; `copied` is `false` when the
|
|
1385
1531
|
clipboard refused the write, and the button then stays untouched rather than claiming a copy
|
|
@@ -1391,8 +1537,8 @@ to a hidden textarea when the async Clipboard API is unavailable or denied.
|
|
|
1391
1537
|
|
|
1392
1538
|
#### CopyInput
|
|
1393
1539
|
|
|
1394
|
-
- **Options** — `value: ''`, `label: ''`, `hideLabel: false`, `feedback
|
|
1395
|
-
`
|
|
1540
|
+
- **Options** — `value: ''`, `label: ''`, `hideLabel: false`, `feedback`, `buttonTitle` (by default
|
|
1541
|
+
the `copy.copied` and `copy.copy` messages, and `null` gives no text), `size: 'md'|'sm'`.
|
|
1396
1542
|
- **Methods** — `get()`, `set(value)`, `focus()` (focuses and selects the whole value).
|
|
1397
1543
|
- **Events** — `copy {value, copied}`.
|
|
1398
1544
|
- **Behaviour** — the field is `readonly`, not `disabled`, so the text stays selectable and
|
|
@@ -1792,7 +1938,7 @@ parked at the pointer, so it flips near a viewport edge like every other floatin
|
|
|
1792
1938
|
<!-- doc:tooltip -->
|
|
1793
1939
|
### Tooltip
|
|
1794
1940
|
|
|
1795
|
-
A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor gets `aria-describedby` pointing at it only while it is open — closing puts the anchor's original value back, including no value at all. The bubble
|
|
1941
|
+
A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor gets `aria-describedby` pointing at it only while it is open — closing puts the anchor's original value back, including no value at all. The bubble contains no focusable controls and stays visible while the pointer is over either the anchor or the bubble. Keyboard focus on the anchor independently keeps it visible. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
|
|
1796
1942
|
|
|
1797
1943
|
- **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
|
|
1798
1944
|
(`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
|
|
@@ -1801,7 +1947,7 @@ A description bubble anchored to another element. The panel is a manual popover
|
|
|
1801
1947
|
at all and leaves everything to the methods), `disabled` (false).
|
|
1802
1948
|
- **Methods** — `show()`, `hide()`, `toggle()`, `isOpen()`, `setContent(content)`, `enable()`, `disable()`, `isDisabled()`, `getAnchor()`, `destroy()`. Convenience factories: `tooltip(anchor, contentOrOptions)` takes either a content value or a full option object, and `describe(anchor, text)` is the one-liner replacement for a `title` attribute. Both return the instance.
|
|
1803
1949
|
- **Events** — `open`, `close`. Both fire only on a real transition, so a `show()` on an open tooltip is silent.
|
|
1804
|
-
- **Keyboard** — Focusing the anchor opens the tooltip at once;
|
|
1950
|
+
- **Keyboard** — Focusing the anchor opens the tooltip at once; it closes after both focus and hover have left the anchor and bubble. `Escape` closes it without moving focus (WCAG 1.4.13 "dismissible") — and only it, when it is the topmost open overlay, so one press never closes a tooltip and the menu beneath it. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it. A closed tooltip listens to nothing outside its anchor; an open one is an entry on the shared overlay stack.
|
|
1805
1951
|
<!-- /doc -->
|
|
1806
1952
|
|
|
1807
1953
|
<!-- doc:split-view -->
|
|
@@ -1835,7 +1981,7 @@ range select.
|
|
|
1835
1981
|
type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
|
|
1836
1982
|
render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
|
|
1837
1983
|
`sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
|
|
1838
|
-
`stickyHeader: true`, `height`, `emptyText`, `rowClass`, `zebra: true`, `variant:
|
|
1984
|
+
`stickyHeader: true`, `height`, `virtual: false`, `emptyText`, `rowClass`, `zebra: true`, `variant:
|
|
1839
1985
|
'default'|'plain'`, `hierarchy: false|{parentId, column?, expanded?}`, `interactive: false`,
|
|
1840
1986
|
and `label`/`labelledBy`. Locale, currency, unit, and decimals may be row callbacks; values
|
|
1841
1987
|
remain numbers in row data while display formatting is locale-aware.
|
|
@@ -1855,8 +2001,8 @@ range select.
|
|
|
1855
2001
|
root; TableView passes it through `table: { variant: 'plain' }`.
|
|
1856
2002
|
- **Methods** — `setData()`, `addData()`, `updateRow(id,row)`, `removeRow(id)`, `getRow(id)`,
|
|
1857
2003
|
`getData()`, `empty()`, `setSort(id,dir)`, `getSort()`, `clearSort()`, `getSelection()`, `setSelection(ids)`,
|
|
1858
|
-
`clearSelection()`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an
|
|
1859
|
-
top bar, sets `aria-busy`, and is cleared by the next `setData`).
|
|
2004
|
+
`clearSelection()`, `reveal(id)`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an
|
|
2005
|
+
indeterminate top bar, sets `aria-busy`, and is cleared by the next `setData`).
|
|
1860
2006
|
- **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
|
|
1861
2007
|
`selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
|
|
1862
2008
|
`rowclick` fires for Enter on a focused row as well as for a click; `event` is then the keydown.
|
|
@@ -1954,6 +2100,26 @@ range select.
|
|
|
1954
2100
|
call `showAll()` first to mean all of them. While growing, the table carries `aria-rowcount` and
|
|
1955
2101
|
each row an `aria-rowindex`, so assistive technology hears the real total rather than the size of
|
|
1956
2102
|
the batch.
|
|
2103
|
+
- **Windowed rendering** — `virtual: true` draws only the rows in view and one viewport of overscan
|
|
2104
|
+
above and below; spacer rows keep the scroll height, so what the table costs stops depending on
|
|
2105
|
+
how many rows it holds. It is off by default, and a table that does not ask for it renders exactly
|
|
2106
|
+
as before. A windowed table is one grid over all of its rows, so `virtual` implies `interactive`:
|
|
2107
|
+
the table carries `aria-rowcount`, every drawn row an `aria-rowindex`, and the whole keyboard map
|
|
2108
|
+
moves through every row, drawing the one it lands on. The focused row and the row being edited
|
|
2109
|
+
stay drawn wherever the reader scrolls. Sorting, filtering through `setData()`, section rows,
|
|
2110
|
+
hierarchy, row-level controls in cells, inline editing, and the sticky header work as usual, and
|
|
2111
|
+
`getData()`, `getSelection()`, and exports built on them read the data, not the DOM. Selection
|
|
2112
|
+
reaches rows that are not drawn: a Shift range covers them, and **the header checkbox and
|
|
2113
|
+
Ctrl/Cmd+A take every row**, not only the drawn ones. `reveal(id)` scrolls a row into view, drawing
|
|
2114
|
+
it first, and returns whether it could; it works without `virtual` too, on any row in the DOM.
|
|
2115
|
+
`getRenderedCount()` reports the rows drawn. `virtual` wins over `growing`, and the conflict is
|
|
2116
|
+
reported once through the console. Limits: give the table a `height`, or its scroll region stops at
|
|
2117
|
+
the height of the window. **Rows have one height:** the table measures one row and takes that
|
|
2118
|
+
height for all, following `--zx-row-height`, so rows of differing height are not supported, and
|
|
2119
|
+
long text is cut short with an ellipsis rather than wrapped. Column widths cannot follow content
|
|
2120
|
+
that is not drawn, so the layout is fixed: `auto` columns share the width evenly, and a column that
|
|
2121
|
+
needs more sets `width`. **Find-in-page does not see rows that are not drawn**, and printing prints
|
|
2122
|
+
the drawn rows only.
|
|
1957
2123
|
- **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
|
|
1958
2124
|
label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
|
|
1959
2125
|
hidden behind it. The width measured is **the table's own container**, not the viewport, so this
|
|
@@ -2163,7 +2329,8 @@ editable cells/rows, loading, events, and teardown keep the Table contract.
|
|
|
2163
2329
|
|
|
2164
2330
|
An accessible, engine-neutral chart host. Zx renders state, canvas, semantic data summary, tokens,
|
|
2165
2331
|
and lifecycle; an injected adapter owns the drawing engine. The Zx runtime imports no Chart.js
|
|
2166
|
-
code
|
|
2332
|
+
code. A renderer must be injected: without one Chart cannot draw data. The only supplied renderer
|
|
2333
|
+
is `ChartJsAdapter`, which requires host-provided Chart.js 4.
|
|
2167
2334
|
|
|
2168
2335
|
- **Options** — `adapter`, `type: 'bar'`, `data`, engine-specific `chartOptions`, `label`,
|
|
2169
2336
|
`description`, `summary: 'hidden'|'visible'`, `loading`, loading/empty/error text, and
|
|
@@ -2178,8 +2345,8 @@ code, so future adapters do not change the public `Chart` API.
|
|
|
2178
2345
|
system preference or inside a `data-zx-motion="reduced"` region, and an adapter must then turn its
|
|
2179
2346
|
engine's animation off; Chart watches for the answer changing and updates the mounted engine.
|
|
2180
2347
|
- **`ChartJsAdapter`** — construct it with a Chart.js constructor or namespace:
|
|
2181
|
-
`new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development
|
|
2182
|
-
|
|
2348
|
+
`new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development dependency and copies it to its
|
|
2349
|
+
self-hosted vendor assets during the website build; `package.json` has no runtime dependencies and application builds explicitly choose how
|
|
2183
2350
|
the engine is loaded. Under reduced motion it sets `animation: false`, over any animation the
|
|
2184
2351
|
application configured.
|
|
2185
2352
|
- **Accessibility** — the canvas always has a name and optional description, while synchronized
|
|
@@ -2282,7 +2449,8 @@ form renders, with no per-application translation layer in between.
|
|
|
2282
2449
|
`int:range` / `float:range` / `number:range`. An unrecognised type renders a visible,
|
|
2283
2450
|
labelled placeholder naming it and is excluded from the value — never dropped silently.
|
|
2284
2451
|
- **Methods** — `getValue()`, `setValue()`, `apply()`, `reset()`, `clear()`.
|
|
2285
|
-
- **Events** — `apply {value}`, `change {value, field}`.
|
|
2452
|
+
- **Events** — `apply {value}`, `change {value, field}`. Values read back from typed controls
|
|
2453
|
+
include their normalization, such as integer rounding and numeric bounds.
|
|
2286
2454
|
|
|
2287
2455
|
Five behaviours are deliberate rather than incidental:
|
|
2288
2456
|
|
|
@@ -2321,7 +2489,9 @@ adapter to compile into its own backend query language.
|
|
|
2321
2489
|
- **Fields** — `{id,label,type,operators?,defaultOperator?,choices?,loadChoices?,editor?,minQuery?,
|
|
2322
2490
|
debounce?}`. Built-in types cover text, number/money, date/datetime, boolean, enum/status/
|
|
2323
2491
|
priority/country/currency/unit/entity, and tags. Compatible operators and their arity come from
|
|
2324
|
-
the exported `filterOperators` matrix; applications may explicitly override/add operator IDs.
|
|
2492
|
+
the exported `filterOperators` matrix; applications may explicitly override/add operator IDs. The
|
|
2493
|
+
labels in that matrix are English data. `Filter` shows a built-in operator through its
|
|
2494
|
+
`filter.op.<id>` message, and an operator the `operators` option supplies through its own `label`.
|
|
2325
2495
|
- **Relative dates** — `withinLast` and `withinNext` take a span, not two dates: the editor is a
|
|
2326
2496
|
whole-number amount and a unit select, and the value is the pair `[amount, unit]` with `unit` one
|
|
2327
2497
|
of `RELATIVE_DATE_UNITS` (`'days'|'weeks'|'months'`), e.g. `[7, 'days']`. `validate()` requires a
|
|
@@ -2364,7 +2534,9 @@ mutate the caller's data.
|
|
|
2364
2534
|
`expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
|
|
2365
2535
|
(tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
|
|
2366
2536
|
(lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`,
|
|
2367
|
-
`rowActions: (node) => actions`, `moreLabel
|
|
2537
|
+
`rowActions: (node) => actions`, `moreLabel`. Unset, `label`, `emptyText` and `moreLabel` read the
|
|
2538
|
+
`tree.label`, `tree.noItems` and `tree.more` messages; `tree.empty` still wins over `emptyText`, and
|
|
2539
|
+
`emptyText: null` shows no text.
|
|
2368
2540
|
- **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
|
|
2369
2541
|
disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
|
|
2370
2542
|
buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
|
|
@@ -2406,7 +2578,8 @@ breadcrumb.
|
|
|
2406
2578
|
- **Options** — `items` (the same nested shape as `TreeView`), `valueKey`, `labelKey`,
|
|
2407
2579
|
`childrenKey`, `path: []` (initial selection, root first), `load: (node)=>Promise<children>`,
|
|
2408
2580
|
`preview: (node)=>Node|null` (renders a pane after the last column for a selected leaf),
|
|
2409
|
-
`rootLabel`, `columnWidth: 220`, `height: 320`, `icons: true`, `renderItem`, `emptyText
|
|
2581
|
+
`rootLabel`, `columnWidth: 220`, `height: 320`, `icons: true`, `renderItem`, `emptyText` (unset, the
|
|
2582
|
+
`finder.noItems` message; `null` shows no text).
|
|
2410
2583
|
- **Methods** — `getPath()`, `getNodes()`, `getSelection()`, `setPath(ids, {silent, focus})`
|
|
2411
2584
|
(async — loads every branch along the way), `reveal(id)`, `setItems()`, `focus()`.
|
|
2412
2585
|
- **Events** — `change {path, nodes, node}`, `activate {node, id}`.
|
|
@@ -2541,9 +2714,10 @@ a feedback survey. The questionnaire owns the ordered items, the active one, the
|
|
|
2541
2714
|
validation, progress and navigation; the page, card, dialog or drawer around it owns closing,
|
|
2542
2715
|
persistence and transport.
|
|
2543
2716
|
|
|
2544
|
-
The root is a real `<form
|
|
2545
|
-
|
|
2546
|
-
|
|
2717
|
+
The created root is a real `<form>`, so `new FormData(questionnaire.toElement())` reads the
|
|
2718
|
+
applicable answers. When enhancing a non-form target, pass its contained `<form>` to `FormData`
|
|
2719
|
+
or call `toFormData()`. Choices are native radios and checkboxes carrying the item name, and
|
|
2720
|
+
arrow keys inside a choice group use the browser's navigation. Three
|
|
2547
2721
|
things separate it from a `Form` with one `Fieldset` per question: it branches, its answer control
|
|
2548
2722
|
can be any registered `Field` type, and its validation may be asynchronous.
|
|
2549
2723
|
|
|
@@ -2559,7 +2733,10 @@ can be any registered `Field` type, and its validation may be asynchronous.
|
|
|
2559
2733
|
`setAnswer(name, value, {silent})`, `getActive()`, `getPath()`, `getProgress()`, `getState()`,
|
|
2560
2734
|
`toFormData()`, `reset()`, `focus()`, `destroy()`. `next()`, `skip()` and `submit()` return
|
|
2561
2735
|
**promises** — `next()` because an item's `validate` may be asynchronous, and `skip()` because
|
|
2562
|
-
skipping the last question submits. Everything else is synchronous.
|
|
2736
|
+
skipping the last question submits. Everything else is synchronous. Async validation applies
|
|
2737
|
+
only to the answer and step it started on; editing, navigating, replacing items, resetting, or
|
|
2738
|
+
destroying the questionnaire invalidates a pending result. The last answer is validated once,
|
|
2739
|
+
and skipping an optional last question does not validate it again.
|
|
2563
2740
|
- **Events** — `change {name, value, answers}`, `navigate {from, to, reason}` **preventable**,
|
|
2564
2741
|
`skip {name}`, `invalid {name, message}`, `submit {answers, path}` **preventable**,
|
|
2565
2742
|
`complete {answers, path}`.
|
|
@@ -2568,9 +2745,49 @@ can be any registered `Field` type, and its validation may be asynchronous.
|
|
|
2568
2745
|
only the answers of visible items declared before it, so hiding the VAT question also hides
|
|
2569
2746
|
whatever depended on the VAT id. An answer to a conditioned-out question is kept internally —
|
|
2570
2747
|
walk back into the branch and it is still there — but is left out of `getAnswers()` and
|
|
2571
|
-
`toFormData()`, so an abandoned branch
|
|
2748
|
+
`toFormData()` and native `new FormData(questionnaire.toElement())`, so an abandoned branch
|
|
2749
|
+
never submits stale data. Native form data includes applicable answers from earlier steps too. A `next` naming a hidden item
|
|
2572
2750
|
walks forward from it rather than stranding the reader; naming an item that does not exist
|
|
2573
|
-
throws `RangeError`.
|
|
2751
|
+
throws `RangeError`. `next: '$review'` opens the review screen and `next: '$submit'` submits at
|
|
2752
|
+
once, wherever the item stands; an item of that name goes first. A `when`, `next` or `validate`
|
|
2753
|
+
that is neither a function nor a declarative form (`false`, `[]`, `{}`) reads as absent, so
|
|
2754
|
+
`validate: strict && check` is safe.
|
|
2755
|
+
- **Declarative logic** — `when`, `next` and `validate` also take plain JSON, so a questionnaire can
|
|
2756
|
+
be stored, sent, or written by an agent; the function forms keep working beside them.
|
|
2757
|
+
- A condition is `{field, op, value?}` with `op` one of `eq`, `ne`, `in`, `nin`, `gt`, `gte`,
|
|
2758
|
+
`lt`, `lte`, `empty`, `filled`, `contains`, combined with `{all: […]}`, `{any: […]}` and
|
|
2759
|
+
`{not: …}`, at most four levels deep. A `when` condition may only name items declared before
|
|
2760
|
+
it, and sees only their visible answers, so it cascades like a predicate. A `value` is never
|
|
2761
|
+
`null`: an unanswered item has no answer to compare, so test it with `empty` or `filled`. A
|
|
2762
|
+
`Date` answer compares by its local date against `YYYY-MM-DD`, and by its local
|
|
2763
|
+
`YYYY-MM-DDTHH:MM` against a date-time.
|
|
2764
|
+
- `next` may be a list of branches, `[{if: condition, goto: name}, …, {goto: name}]`; the first
|
|
2765
|
+
match wins, and no match falls through to the next visible item. A branch condition may also
|
|
2766
|
+
name the item itself.
|
|
2767
|
+
- `validate` may be a list of rules, each one key plus an optional `message`: `{required: true}`,
|
|
2768
|
+
`{minLength: n}`, `{maxLength: n}` (characters, or entries of a multiple answer),
|
|
2769
|
+
`{minimum: n}`, `{maximum: n}`, `{format: 'date'|'date-time'|'time'|'email'|'uri'}`,
|
|
2770
|
+
`{oneOf: [values]}`. Rules other than `required` pass an empty answer; there are no patterns.
|
|
2771
|
+
A `{required: true}` rule marks the item required, like `required: true`.
|
|
2772
|
+
A rule's own `message` wins; otherwise its text resolves through `msg()` under
|
|
2773
|
+
`questionnaire.rule.<rule>` (`minLength`, `maxLength`, `minItems`, `maxItems`, `minimum`,
|
|
2774
|
+
`maximum`, `oneOf`, `date`, `dateTime`, `time`, `email`, `uri`), the same keys a Surface's
|
|
2775
|
+
fields use.
|
|
2776
|
+
- A malformed condition, branch list or rule list throws `TypeError` when the items are set.
|
|
2777
|
+
`evaluate(condition, answers)`, `resolveNext(next, answer, answers)`, `checkRules(rules,
|
|
2778
|
+
value)` and the shape checks `checkCondition()`, `checkNext()` and `checkRuleList()` are pure
|
|
2779
|
+
exports of `src/components/questionnaire/conditions.js`, for evaluating the same JSON elsewhere.
|
|
2780
|
+
|
|
2781
|
+
```js
|
|
2782
|
+
items: [
|
|
2783
|
+
{ name: 'method', prompt: 'How will you pay?', required: true,
|
|
2784
|
+
choices: [{ value: 'card', label: 'Card' }, { value: 'transfer', label: 'Bank transfer' }],
|
|
2785
|
+
next: [{ if: { field: 'method', op: 'eq', value: 'card' }, goto: '$submit' }] },
|
|
2786
|
+
{ name: 'iban', prompt: 'IBAN', input: {},
|
|
2787
|
+
when: { field: 'method', op: 'eq', value: 'transfer' },
|
|
2788
|
+
validate: [{ required: true }, { minLength: 15, message: 'An IBAN has at least 15 characters.' }] }
|
|
2789
|
+
]
|
|
2790
|
+
```
|
|
2574
2791
|
- **Path and progress** — `getPath()` is the questionnaire's memory of the route walked, and
|
|
2575
2792
|
`previous()` pops it: once a branch has been taken, "previous" is not `index - 1`. `getProgress()`
|
|
2576
2793
|
returns `{index, answered, total, percent, section}` where `total` is the path plus the items
|
|
@@ -2581,8 +2798,8 @@ can be any registered `Field` type, and its validation may be asynchronous.
|
|
|
2581
2798
|
itself. The `<legend>` already asks the question, so the Field's own label is hidden from sight
|
|
2582
2799
|
but kept as the control's accessible name unless the item gives `field.label` explicitly; the
|
|
2583
2800
|
Field draws its own highlight, so a failing answer shows one message, not two.
|
|
2584
|
-
- **Validation** — `required`
|
|
2585
|
-
return a message, `null`, or a **promise** of either, and a rejection is reported as its message.
|
|
2801
|
+
- **Validation** — `required` and declarative rules are checked synchronously; a function
|
|
2802
|
+
`validate(answer, answers)` may return a message, `null`, or a **promise** of either, and a rejection is reported as its message.
|
|
2586
2803
|
While the check is pending the root carries `data-state="checking"` and `aria-busy="true"` and
|
|
2587
2804
|
the actions are disabled.
|
|
2588
2805
|
- **Review** — `review: true` shows a summary of every answer on the path before submitting, each
|
|
@@ -2635,7 +2852,11 @@ Ordered value editor with explicit rows (add / remove / move).
|
|
|
2635
2852
|
### FieldUpload
|
|
2636
2853
|
|
|
2637
2854
|
Click/drop file upload with progress. The drop zone is keyboard-accessible and progress comes from
|
|
2638
|
-
`XMLHttpRequest`.
|
|
2855
|
+
`XMLHttpRequest`. Passing the shipped `Http` client keeps XHR upload progress while applying its
|
|
2856
|
+
base URL, default headers, timeout, JSON/envelope parsing, and error observer. Per-upload headers
|
|
2857
|
+
can override defaults; the browser supplies the multipart boundary. Custom `upload()` or
|
|
2858
|
+
`request()` transports receive files, `paramName`, a cancellation signal, and a progress callback.
|
|
2859
|
+
Aborted uploads ignore late progress and success callbacks.
|
|
2639
2860
|
|
|
2640
2861
|
- **Options** — `url`, `paramName: 'upload'`, `params`, `headers`, `multiple: false`, `accept`,
|
|
2641
2862
|
`maxSize`, `autoUpload: true`, `preview: true`, `http`.
|
|
@@ -2965,7 +3186,8 @@ first and last items.
|
|
|
2965
3186
|
- **Options** — `items: [{name, label, icon?, href?}]`, `maxVisible: 0` (0 shows all),
|
|
2966
3187
|
`separator: 'chevron'|'slash'`, `rootIcon: null`.
|
|
2967
3188
|
- **Methods** — `setItems()`, `getItems()`, `push(item)`, `pop()`, `truncateTo(name)`, `destroy()`.
|
|
2968
|
-
- **Events** — `select {name, item, index}
|
|
3189
|
+
- **Events** — `select {name, item, index}` **preventable**, including overflow items. An item
|
|
3190
|
+
with an `href` renders as a real `<a>` in the trail or overflow, and its
|
|
2969
3191
|
default is left alone, so ordinary navigation and middle-click still work; without one it renders
|
|
2970
3192
|
as a `<button>` and only the event fires.
|
|
2971
3193
|
- **Semantics** — `<nav aria-label="Breadcrumb"><ol>`; the last item is plain text carrying
|
|
@@ -3139,7 +3361,7 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
|
|
|
3139
3361
|
(`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
|
|
3140
3362
|
strip), `label`,
|
|
3141
3363
|
`header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
|
|
3142
|
-
`moreLabel
|
|
3364
|
+
`moreLabel` (by default the `appSidebar.more` message), and `renderIcon(item, context)`. Icon values may also be names,
|
|
3143
3365
|
nodes, components, or factories.
|
|
3144
3366
|
- **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
|
|
3145
3367
|
disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
|
|
@@ -3278,6 +3500,850 @@ bar.setBadge('mail', 8);
|
|
|
3278
3500
|
`--zx-control-height` resizes the bar; a coarse pointer keeps a 40px target.
|
|
3279
3501
|
<!-- /doc -->
|
|
3280
3502
|
|
|
3503
|
+
### Agents — the conversation model
|
|
3504
|
+
|
|
3505
|
+
The agent components draw a conversation with one or more AI agents from **plain JSON**: no
|
|
3506
|
+
functions and no DOM nodes in the data, so an agent can produce it, an application can store and
|
|
3507
|
+
replay it, and a component can render it. Three rules hold for every agent component:
|
|
3508
|
+
|
|
3509
|
+
1. **The application owns transport and state.** No agent component fetches anything. The
|
|
3510
|
+
application feeds them (`upsert`, `patch`, `appendText`) and acts on the intents they emit
|
|
3511
|
+
(`send`, `stop`, `approve`, `regenerate`, …).
|
|
3512
|
+
2. **Model text is data.** Every string an agent wrote reaches the page as text. Inside a text run
|
|
3513
|
+
the whole grammar is `**bold**`, `` `code` `` and `[n]` citations (a backslash makes a marker
|
|
3514
|
+
literal); there are no links, no HTML, and no images in answer text.
|
|
3515
|
+
3. **Consequence comes from the application.** Whether an action needs a confirmation — and which
|
|
3516
|
+
— is decided by the application from the tool the action triggers, never taken from model
|
|
3517
|
+
output.
|
|
3518
|
+
|
|
3519
|
+
A thread is a list of items, each `{id, type, at?, author?, …}`, where `author` is a key into
|
|
3520
|
+
the thread's `authors` (`{name, kind: 'person'|'agent'|'model', initials?, tone?, activity?, via?}`):
|
|
3521
|
+
|
|
3522
|
+
```json
|
|
3523
|
+
[
|
|
3524
|
+
{"id": "ask", "type": "user", "text": "Reconcile September and draft reminders.", "files": [{"name": "Policy.pdf", "size": 188416}]},
|
|
3525
|
+
{"id": "note", "type": "text", "author": "finance", "text": "I’ll check the bank feed first."},
|
|
3526
|
+
{"id": "work", "type": "trace", "author": "finance", "steps": [
|
|
3527
|
+
{"id": "q", "kind": "query", "label": "Queried invoices", "count": "42 rows", "ms": 800, "tool": "invoices.search", "args": "{\"month\": \"2026-09\"}", "result": "42 invoices"}
|
|
3528
|
+
]},
|
|
3529
|
+
{"id": "a1", "type": "answer", "author": "finance", "blocks": [
|
|
3530
|
+
{"type": "p", "text": "Three invoices are more than **14 days** late [1]."},
|
|
3531
|
+
{"type": "figures", "rows": [["Late", "3 invoices", "€19,375.50"]]}
|
|
3532
|
+
], "sources": [{"id": "inv", "title": "Invoices · September", "kind": "call", "call": "q"}]},
|
|
3533
|
+
{"id": "ok", "type": "approval", "author": "finance", "title": "Send 3 reminder emails?", "status": "pending"},
|
|
3534
|
+
{"id": "n1", "type": "notice", "text": "The bank feed timed out; retried once.", "tone": "warning"}
|
|
3535
|
+
]
|
|
3536
|
+
```
|
|
3537
|
+
|
|
3538
|
+
- **Blocks** — `p`, `quote`, `heading` (`level: 2|3`), `list` (`ordered`), `code` (`language`),
|
|
3539
|
+
`table` (`columns`, `rows`, `align`), `figures` (`rows` of `[label, detail, value]` or
|
|
3540
|
+
`{label, detail?, value, call?}`), `callout` (`tone`, `title`), `artifact` (`id`, `title`,
|
|
3541
|
+
`kind: 'document'|'code'`, `versions`).
|
|
3542
|
+
- **Steps** — `{id, kind: 'search'|'read'|'query'|'write'|'run'|'call'|'handoff'|'think', label,
|
|
3543
|
+
status, doing?, detail?, ms?, count?, sources?, tool?, args?, result?, error?, retryOf?, actor?,
|
|
3544
|
+
to?, at?}`. A retry names the step it repeats with `retryOf`; a hand-off names `actor` and `to`.
|
|
3545
|
+
- **States** — runs and steps are `queued`, `running`, `waiting`, `paused`, `done`, `failed`,
|
|
3546
|
+
`stopped`, or `skipped`; an agent's activity is `idle`, `thinking`, `working`, `needs-you`,
|
|
3547
|
+
`blocked`, or `offline`. Each is always drawn as a glyph and a word, never by colour or motion
|
|
3548
|
+
alone.
|
|
3549
|
+
|
|
3550
|
+
<!-- doc:block-view -->
|
|
3551
|
+
### BlockView — `new BlockView(target, options)` / `renderBlocks(blocks, options)`
|
|
3552
|
+
|
|
3553
|
+
An answer an agent wrote, drawn block by block as semantic elements inside `.zx-prose`, and
|
|
3554
|
+
written to as it streams. Finished blocks are never redrawn: `append()` and `appendText()` touch
|
|
3555
|
+
only the last block, so a reader's selection or focus in an earlier paragraph survives the rest of
|
|
3556
|
+
the answer arriving.
|
|
3557
|
+
|
|
3558
|
+
- **Options** — `blocks: []`, `headingLevel: 3` (the element level of a level-2 `heading` block;
|
|
3559
|
+
set it one below the heading that names the answer), `size: 'sm'|'md'` (interface or reading
|
|
3560
|
+
size), `streaming: false`, `sources: null` (names the citation buttons by title), `msg`.
|
|
3561
|
+
- **Methods** — `setBlocks(blocks, {streaming?})`, `append(block)`, `appendText(text)` (continues
|
|
3562
|
+
the last paragraph, or opens one; a blank line in the text starts a new paragraph; a marker split
|
|
3563
|
+
across two chunks resolves when its close arrives), `end()`, `stop()` (adds "Stopped here."),
|
|
3564
|
+
`setSources(sources)`, `setArtifactState(id, {expanded, controls})` (reflects whether the
|
|
3565
|
+
application has the artifact open somewhere), `getBlocks()`, `isStreaming()`, `toText()`,
|
|
3566
|
+
`toMarkdown()`, `destroy()`. A single line break in model text is kept (an address, a sign-off); a
|
|
3567
|
+
blank line starts a new paragraph.
|
|
3568
|
+
- **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
|
|
3569
|
+
`end` when a streamed answer is marked finished.
|
|
3570
|
+
- **Rendering** — code is a figure with its language, a copy button and a focusable `<pre>`
|
|
3571
|
+
(`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
|
|
3572
|
+
code read at length in an inspector),
|
|
3573
|
+
coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
|
|
3574
|
+
scrolls inside the answer and becomes a named, focusable region only while it overflows; figures
|
|
3575
|
+
are a `<dl>` with tabular numbers; a callout uses `.zx-callout` with its tone as `data-kind`.
|
|
3576
|
+
- **Static** — `renderBlocks(blocks, options)` returns a `DocumentFragment` for a transcript or a
|
|
3577
|
+
print view: citations are plain superscripts and artifacts plain cards. `blocksToMarkdown(blocks)`
|
|
3578
|
+
and `blocksToText(blocks)` export an answer for copying and search.
|
|
3579
|
+
- **State** — `data-state` is `streaming`, `done` or `stopped`; the root is `aria-busy` while it
|
|
3580
|
+
streams. Streamed text is never inside a live region.
|
|
3581
|
+
<!-- /doc -->
|
|
3582
|
+
|
|
3583
|
+
<!-- doc:agent-thread -->
|
|
3584
|
+
### AgentThread
|
|
3585
|
+
|
|
3586
|
+
A conversation with one or more agents, drawn from the items above: the person's messages, the
|
|
3587
|
+
agents' answers as they stream (`BlockView` with a `SourceList`), the steps a run took
|
|
3588
|
+
(`RunTrace`), the approvals that hold it (`ApprovalCard`), and one-line notices.
|
|
3589
|
+
|
|
3590
|
+
- **Options** — `items: []`, `authors: {}`, `me: 'me'` (the reader's author key; an item without
|
|
3591
|
+
`author` is the reader's when it is a `user` item), `label` (the feed's name, "Conversation"),
|
|
3592
|
+
`headingLevel: 3`, `emptyState: null` (`emptyState()` options shown while empty),
|
|
3593
|
+
`followOutput: true`, `scroller: null` (the element that scrolls; the nearest scrolling ancestor
|
|
3594
|
+
when null), `answerActions: ['copy', 'regenerate', 'branch']` (add `'rate'` for helpful / not
|
|
3595
|
+
helpful), `userActions: []` (`'edit'`, `'copy'` on the reader's own messages, revealed while the
|
|
3596
|
+
message is pointed at or holds focus), `icons` (glyphs for `regenerate`, `branch`, `rateUp`,
|
|
3597
|
+
`rateDown`, `edit`), `traceIcons` (handed to every `RunTrace` it draws), `now: null` (the clock
|
|
3598
|
+
"today" is measured against, for a world on fixed dates), `formatTime`, `locale`, `msg`.
|
|
3599
|
+
- **Surfaces** — a `{type: 'surface', id, document?, token?, catalog?, reply?}` item draws a
|
|
3600
|
+
`Surface`. The item comes from the application, never from a model line, so its `token` and
|
|
3601
|
+
`catalog` are the application's. `surfaceOptions` (`policy`, `resolve`, `chartAdapter`, `msg`)
|
|
3602
|
+
is handed to every surface the thread draws. `thread.surface(id)` returns it to stream into, and
|
|
3603
|
+
its one reply arrives as the thread's `reply {item, reply}`. Redrawing the item — `patch`,
|
|
3604
|
+
`upsert(thread.get(id))`, `setItems(thread.getItems())` — keeps the live surface; an item with a
|
|
3605
|
+
different `document` supersedes it, which replies `dismiss`. Removing the item or destroying the
|
|
3606
|
+
thread dismisses it. A surface that waits for an answer is announced ("Finance agent needs your
|
|
3607
|
+
answer") when it arrives, or when a streamed one begins. When a run stops, the application calls
|
|
3608
|
+
`thread.surface(id).cancel('stopped')`.
|
|
3609
|
+
- **Item extras** — any item's `refs: [{id, label, icon?, entity?}]` draws links to the
|
|
3610
|
+
application's own things after its content (`open {item, ref}`); a `user` item's `mentions`
|
|
3611
|
+
(names, or `{name, tone}`) marks each `@name` in its text; an `answer`'s `steps` show the work it
|
|
3612
|
+
did inline above its text (`stepsOpen` opens them) and, like `stopped`, `rating` and `at`, follow
|
|
3613
|
+
its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
|
|
3614
|
+
"Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
|
|
3615
|
+
(`action {item, action: id}`); an author with an `icon` is drawn as a tinted tile instead of
|
|
3616
|
+
initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an `approval`'s
|
|
3617
|
+
`editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
|
|
3618
|
+
drawn later; `sourceIcons` is handed to every `SourceList`.
|
|
3619
|
+
- **Placeholders** — a `{type: 'zx-placeholder', id, author?, lines?}` item stands for something
|
|
3620
|
+
still on its way, as a Skeleton under its author's byline; replace or remove it once the real
|
|
3621
|
+
item is there. It neither replies nor is announced. The name is reserved; `placeholder` is free
|
|
3622
|
+
for an application's own items.
|
|
3623
|
+
- **Methods** — `setItems(items)` (replaces the conversation: everything is dropped and drawn anew,
|
|
3624
|
+
except a surface already drawn, which stays so that one still matching keeps what was typed; an
|
|
3625
|
+
item bringing a `reply` that surface never gave freezes it as answered elsewhere),
|
|
3626
|
+
`upsert(item, {after?})` (adds, or replaces in place by `id`;
|
|
3627
|
+
a new item goes at the end, or right after the item `after` names — nothing else is redrawn),
|
|
3628
|
+
`patch(id, partial)` (an answer finishing, stopping or gaining sources, a trace's steps, an
|
|
3629
|
+
approval's status change in place; anything else redraws the item). Metadata patches preserve
|
|
3630
|
+
streamed answer blocks, including the selected version; explicit `blocks` or `versions`
|
|
3631
|
+
replacements remain authoritative. `appendText(id, text)`
|
|
3632
|
+
(streams into an answer, creating it when the id is new), `appendBlock(id, block)` (adds a whole
|
|
3633
|
+
block — figures, a table — without redrawing the answer), `announce(text)` (says an outcome
|
|
3634
|
+
through the thread's polite status), `setArtifactState(id, {expanded, controls})` (whether an
|
|
3635
|
+
artifact is open in an inspector, on every card naming it), `remove(id)`, `get(id)`,
|
|
3636
|
+
`getItems()`, `getComponent(id)`, `reveal(target)` (`item:<id>`, `step:<id>`, `source:<n>`,
|
|
3637
|
+
`source:<n>:<id>`, a source in the list of that answer),
|
|
3638
|
+
`scrollToEnd()`, `surface(id)` (the `Surface` of a `surface` item, to stream into), `destroy()`. The static `AgentThread.register(type, render)` draws an item type
|
|
3639
|
+
of the application's own; `render(item, {thread, author, own})` returns its content, and `own()`
|
|
3640
|
+
hands a component to the thread to destroy with the item. An application's renderer for
|
|
3641
|
+
`surface` replaces the library's drawing of that type, and `has('surface')` answers false until
|
|
3642
|
+
it does; the other built-in types cannot be replaced.
|
|
3643
|
+
- **Events** — `action {item, action, value?}` (`copy`, `regenerate`, `branch`, `rate` with
|
|
3644
|
+
`up`/`down`/null, `version` with an index — preventable for `rate` and `version`; `edit` on the
|
|
3645
|
+
reader's message; a notice's action id), `open {item, ref, step?}` (an item's link, or a trace
|
|
3646
|
+
step's),
|
|
3647
|
+
`reply {item, reply}` (a surface's one reply; the item keeps it as `reply`),
|
|
3648
|
+
`approve {item, values}`, `edit {item, values}`, `reject {item, reason}` (preventable: the card
|
|
3649
|
+
stays pending), `cite {item, n, source}` (preventable: by default the cited source is
|
|
3650
|
+
highlighted), `artifact {item, id}`, `reveal {target}`. Each reaches a listener on the thread's
|
|
3651
|
+
root once, as the thread's `zx-*` event: the cards, answers and traces inside it do not bubble
|
|
3652
|
+
their own copies past it. A source that names a `call` reveals that
|
|
3653
|
+
step in the trace.
|
|
3654
|
+
- **Turns** — consecutive items by the same agent read as one turn: the avatar and byline are drawn
|
|
3655
|
+
once, and the byline still names every article. The reader's own messages sit at the end as a
|
|
3656
|
+
bubble without an avatar.
|
|
3657
|
+
- **Following output** — while the reader is at the end, new output keeps the end in view;
|
|
3658
|
+
scrolled up, a "Jump to latest" button appears and the reader is never moved. While a streaming
|
|
3659
|
+
answer has nothing yet, a quiet line says who is writing.
|
|
3660
|
+
- **Narrow** — the thread is a size container; below 30rem the content takes the full width and
|
|
3661
|
+
the avatar stays beside the byline.
|
|
3662
|
+
- **Keyboard and semantics** — the APG feed pattern: each item is an `article` in a `role="feed"`
|
|
3663
|
+
with `aria-posinset`, `aria-setsize` and `aria-labelledby` its byline; PageDown and PageUp move
|
|
3664
|
+
between articles; Ctrl+End and Ctrl+Home move focus past the end or before the start of the feed.
|
|
3665
|
+
A control inside an item keeps those keys: they move a caret, not the feed.
|
|
3666
|
+
The feed is `aria-busy` while an answer streams. One polite status says when an agent starts
|
|
3667
|
+
writing, answers, needs approval, or is stopped — streamed text is never read aloud as it arrives.
|
|
3668
|
+
|
|
3669
|
+
#### connectUiMessageStream() — the AI SDK UI message stream
|
|
3670
|
+
|
|
3671
|
+
Draws a server's AI SDK UI message stream (the response header `x-vercel-ai-ui-message-stream: v1`;
|
|
3672
|
+
`UI_MESSAGE_STREAM_VERSION` is the version implemented) in a thread. The application keeps the
|
|
3673
|
+
request, the event source, retries, and authentication: it strips the `data: ` framing and the
|
|
3674
|
+
`[DONE]` sentinel, and hands each parsed part to `handle()`.
|
|
3675
|
+
|
|
3676
|
+
```js
|
|
3677
|
+
const stream = connectUiMessageStream(thread, {
|
|
3678
|
+
agent: 'finance',
|
|
3679
|
+
runStatus,
|
|
3680
|
+
onapproval: (approvalId, approved, reason) => sendNextRequest({ approvalId, approved, reason }),
|
|
3681
|
+
ondata: (name, data, id) => store.set(`${name}/${id}`, data)
|
|
3682
|
+
});
|
|
3683
|
+
for await (const part of parsedParts(response)) stream.handle(part);
|
|
3684
|
+
```
|
|
3685
|
+
|
|
3686
|
+
- **Options** — `runStatus` (a `RunStatus` to keep up to date), `authors`, `agent` (the author key
|
|
3687
|
+
of the assistant's output; without it, the first author who is not a person), `tools: {}`,
|
|
3688
|
+
`onapproval(approvalId, approved, reason)`, `ondata(name, data, id)`, `onmetadata(metadata)`,
|
|
3689
|
+
`onunknown(part)`, `onerror(error)`, `showReasoning: false`. It returns
|
|
3690
|
+
`{handle(part), replay(messageId), destroy()}`.
|
|
3691
|
+
- **Keep one connection for the conversation.** The answer to an approval goes out with the
|
|
3692
|
+
application's next request, and the response to it continues the same message: its `start` names
|
|
3693
|
+
a message that has finished or was stopped, and the message picks up where it stopped, once it has
|
|
3694
|
+
something to say. A `start` without a `messageId` opens a new answer, or, during an open message,
|
|
3695
|
+
joins it, because streams merged into one each send their own. `destroy()` stops a message still open and every
|
|
3696
|
+
call still going, and expires a pending approval, because no decision could reach the application
|
|
3697
|
+
any more.
|
|
3698
|
+
- **After a reconnect, call `replay(messageId)`.** A reconnect can return the whole response from its
|
|
3699
|
+
beginning. Only the application knows it reconnected, so it calls `replay()` before it feeds the
|
|
3700
|
+
stream again from the `start`: what that response drew goes and is rebuilt, with nothing doubled
|
|
3701
|
+
and nothing reported. Earlier responses of the message are not sent again, so what they drew stays.
|
|
3702
|
+
A decision stands: its card comes back with its answer, and `onapproval` does not fire twice.
|
|
3703
|
+
`ondata` and `onmetadata` hear what the replay sends again. Without an id it takes the message being
|
|
3704
|
+
read, or the one read last. Without `replay()`, a `start` for a finished message resumes it, and a
|
|
3705
|
+
second copy of a response is drawn twice.
|
|
3706
|
+
|
|
3707
|
+
```js
|
|
3708
|
+
stream.replay(lastMessageId);
|
|
3709
|
+
for await (const part of parsedParts(await reconnect())) stream.handle(part);
|
|
3710
|
+
```
|
|
3711
|
+
- **What stands in the thread stays.** A `start` for an answer this connection did not draw, restored
|
|
3712
|
+
with the conversation or drawn by an earlier connection, takes it over: the message goes on below
|
|
3713
|
+
what stands under it, and a call on one of its steps finds that step. A `start` naming any other
|
|
3714
|
+
item opens an answer of its own, and a continuation skips a number already in use.
|
|
3715
|
+
- **Message** — `start` opens an `answer` under the message id, `finish` closes it and settles
|
|
3716
|
+
`runStatus` (`waiting` while an approval is pending), `abort` closes it as stopped. Text blocks
|
|
3717
|
+
stream through `appendText`, each block a new paragraph of the same answer; blocks open side by side
|
|
3718
|
+
go out one after the other. `error` draws a
|
|
3719
|
+
`notice` with tone `danger`. `start-step` and `finish-step` draw nothing. `message-metadata`, and
|
|
3720
|
+
the `messageMetadata` of `start` and `finish`, go to `onmetadata`.
|
|
3721
|
+
- **Stream order** — the thread adds at its end, so what a message says after a card, a tile, or
|
|
3722
|
+
another item the adapter added continues in a new answer `<messageId>#<n>`, counting from 2, by
|
|
3723
|
+
the same author, and the thread draws it as the same turn. The steps stay on the message's first
|
|
3724
|
+
answer, and the sources are listed under its last, while citations in any of its answers count
|
|
3725
|
+
them all and lead to that list. Each answer is its own item: `thread.get(messageId)` is the first one alone, and an
|
|
3726
|
+
action under a continuation carries the id `<messageId>#<n>`, so strip `#<n>` to name the message.
|
|
3727
|
+
- **`reset-step`** withdraws the current step: everything the message added since its last
|
|
3728
|
+
`start-step` goes, or all of it when it has none, and the answer goes on where the step began. Its
|
|
3729
|
+
text, files, continuation answers, sources, reasoning, and tool calls with their tiles and cards
|
|
3730
|
+
go, and so does an error notice, because a step the server takes back has not failed. An earlier
|
|
3731
|
+
call keeps what the step did to it. A person can no longer answer a withdrawn card. What already
|
|
3732
|
+
went out through `ondata`, `onmetadata`, or `onapproval` stays with the application.
|
|
3733
|
+
- **Reasoning stays private.** All of a message's reasoning is one collapsed "Thought for 12 s" step.
|
|
3734
|
+
The text is not kept at all unless `showReasoning: true` puts it on the step. A `reasoning-file` is
|
|
3735
|
+
never drawn. The step says its duration in words, so the trace's "Worked for" total leaves it out.
|
|
3736
|
+
- **Tool calls** are steps of the answer: `queued` while the input streams, `running` once it is
|
|
3737
|
+
available, then `done`, `failed`, or `skipped`. The input is shown once it is complete. A
|
|
3738
|
+
preliminary output leaves the step running.
|
|
3739
|
+
- **The server asks; the person answers; the application sends.** A `tool-approval-request` draws an
|
|
3740
|
+
`ApprovalCard` and its step waits. The person's decision goes to `onapproval`, and a prevented
|
|
3741
|
+
`approve` or `reject` decides nothing. Nothing is approved by default, and an automatic decision
|
|
3742
|
+
(`isAutomatic`) draws no card, because nobody is asked. A call the server settles while its card
|
|
3743
|
+
is pending expires the card, and a `tool-approval-response` shows on it what was decided elsewhere,
|
|
3744
|
+
without `onapproval`. `onapproval` fires once per approval: a request that arrives again, from a
|
|
3745
|
+
retried step or a replay, draws its card with the answer it already has.
|
|
3746
|
+
- **No address is loaded.** A `source-url` keeps its link only when it is `https:` and passes
|
|
3747
|
+
`safeHref()`; otherwise the source stays, so `[n]` citations count the same sources, and opens
|
|
3748
|
+
nothing. A `source-document` is a `file` source. A `file` part draws its name and type, never its
|
|
3749
|
+
content.
|
|
3750
|
+
- **Tiles** — `tools` maps a tool's name to the application's own renderer: `(call) => ThreadItem|null`,
|
|
3751
|
+
called at each status change and never on an input delta, with `{id, name, args, argsText, result?,
|
|
3752
|
+
error?, status}`. `args` is `null` until the input is complete. The first result that is not null
|
|
3753
|
+
joins the thread as `tool:<toolCallId>` (a card that holds the call stays ahead of it), and later
|
|
3754
|
+
results patch it in place; the adapter sets the id. The call's step links to the tile, and the
|
|
3755
|
+
adapter answers that link with `thread.reveal()`. Draw the tile with `AgentThread.register()`. A
|
|
3756
|
+
renderer that throws is reported through `onerror`, and the step stays.
|
|
3757
|
+
- **Data parts** — `data-<name>` goes to `ondata(name, data, id)`. A part with an `id` replaces the
|
|
3758
|
+
earlier one of that name and id, so keep the latest value per name and id.
|
|
3759
|
+
- **Reported, never guessed at.** A part the adapter does not draw goes to `onunknown`, among them
|
|
3760
|
+
`custom` and a `tool-approval-response` with no card here. A delta ahead of its start creates the item, a `start`
|
|
3761
|
+
naming a message still open is ignored, a `start` naming another message stops the open one, and a
|
|
3762
|
+
`reset-step` outside a message draws nothing; each goes to `onerror`.
|
|
3763
|
+
|
|
3764
|
+
#### AG-UI event streams: `connectAgUi(thread, options)`
|
|
3765
|
+
|
|
3766
|
+
`connectAgUi()` draws an [AG-UI](https://docs.ag-ui.com) event stream in a thread. It implements
|
|
3767
|
+
AG-UI `AG_UI_VERSION` (`'1.0'`). It takes events already parsed — the application keeps the
|
|
3768
|
+
transport, retries and authentication — and returns `{handle(event), state(), destroy()}`.
|
|
3769
|
+
|
|
3770
|
+
```js
|
|
3771
|
+
const status = new RunStatus(null, { compact: true });
|
|
3772
|
+
const adapter = connectAgUi(thread, {
|
|
3773
|
+
agent: 'finance', runStatus: status, inlineSurfaces: true,
|
|
3774
|
+
requiresApproval: (call) => call.name === 'send_reminder',
|
|
3775
|
+
tools: { show_company: (call) => (call.args ? { type: 'company-card', company: call.args.id, status: call.status } : null) },
|
|
3776
|
+
ontoolresult: (id, result) => sendWithNextRun(id, result)
|
|
3777
|
+
});
|
|
3778
|
+
source.onmessage = (message) => adapter.handle(JSON.parse(message.data));
|
|
3779
|
+
```
|
|
3780
|
+
|
|
3781
|
+
- **Options** — `runStatus` (a `RunStatus` the run's lifecycle drives), `authors` (a text message
|
|
3782
|
+
whose `name` is an author key is that author's), `agent` (the author key of agent output),
|
|
3783
|
+
`requiresApproval(call)`, `ontoolresult(id, result)`, `onstate(state)`, `onunknown(event)`,
|
|
3784
|
+
`onerror(problem)` (`{code, message, event?, cause?, errors?}`), `showReasoning: false`,
|
|
3785
|
+
`surfaceEvent: 'zx.surface'`, `tools: {}` (tile renderers by tool name), `surfaceTools:
|
|
3786
|
+
['show_surface', 'ask_user']`, `inlineSurfaces: false`, `catalog` (a narrowed surface catalog).
|
|
3787
|
+
- **What is drawn** — a run drives `runStatus` (`running`, then `done`, `waiting` while a call of
|
|
3788
|
+
the run has no result, listed in `pendingToolCallIds` or not, `stopped` when cancelled, `failed`),
|
|
3789
|
+
and a run error adds a `notice` (`error:<runId>`). A run error outside an open run marks the last
|
|
3790
|
+
run failed and reports `no-run`, but closes nothing: approvals and surfaces still waiting for a
|
|
3791
|
+
person stay open. A text message is an `answer` with the message id. Tool calls are steps of a
|
|
3792
|
+
`trace` (`trace:<runId>`, a new one, `#2`, after anything else was drawn): the arguments show once
|
|
3793
|
+
complete, the result fills the step. Reasoning is one collapsed "Thought for 0.7 s" step; its text
|
|
3794
|
+
only with `showReasoning: true`. State snapshots and JSON Patch deltas keep `state()`.
|
|
3795
|
+
- **`ToolCall`** — what a tile renderer receives: `{id, name, args, argsText, result?, error?,
|
|
3796
|
+
status}`; `args` is the parsed arguments once complete, `null` before; `result` the result's
|
|
3797
|
+
`content` unchanged; `status` is `queued` while arguments arrive, `waiting`, `running`, then
|
|
3798
|
+
`done`, `failed`, `skipped` (rejected) or `stopped`.
|
|
3799
|
+
- **Tiles** — a call named in `tools` is drawn by the application's renderer, an item type
|
|
3800
|
+
registered with `AgentThread.register()`. The renderer runs at each status change, never on an
|
|
3801
|
+
argument delta; its first item that is not `null` is inserted as `tool:<toolCallId>` at the
|
|
3802
|
+
call's place — after its trace and the items of earlier calls in it, even when text was drawn
|
|
3803
|
+
below since — later items replace it in place, and the step links to it. A gated call's tile
|
|
3804
|
+
follows its card. A renderer that throws is reported and the step stays as it was. Put arguments
|
|
3805
|
+
and results on the page as text.
|
|
3806
|
+
- **Approvals** — a call `requiresApproval` answers truthy for waits at an ApprovalCard
|
|
3807
|
+
(`approval:<toolCallId>`); nothing is approved by default, so a check that throws or returns a
|
|
3808
|
+
Promise holds the call too. The decision is the call's result:
|
|
3809
|
+
`ontoolresult(id, {approved: true})` or `{approved: false, reason?}`. AG-UI 1.0 asks by ending the
|
|
3810
|
+
run with an `interrupt` outcome: keep each `interrupt.id` from that event and send the result as
|
|
3811
|
+
the next run's `resume` entry `{interruptId, status: 'resolved', payload: result}`. A `tool_call`
|
|
3812
|
+
interrupt for a call `requiresApproval` let through draws the card too; any other interrupt
|
|
3813
|
+
(`input_required`, `confirmation`, …) goes to `onunknown`. A result that arrives before the
|
|
3814
|
+
decision is drawn, the card expires, and no decision is sent; a result after a rejection only
|
|
3815
|
+
fills the step. A result for a surface tool still waiting closes its surface the same way.
|
|
3816
|
+
- **Surfaces** — a call named in `surfaceTools` is an `ask` step and a surface at the call's place,
|
|
3817
|
+
a `zx-placeholder` until its arguments are complete; its reply, plus the surface's `errors` when there are any, is the call's
|
|
3818
|
+
result through `ontoolresult` — in AG-UI 1.0 a frontend tool, answered in the next run's input as
|
|
3819
|
+
`{role: 'tool', toolCallId, content}`. A `show` surface with no actions has nothing to answer, so
|
|
3820
|
+
the call is answered at once with `{shown: true, surface, errors?}` and the surface stays on
|
|
3821
|
+
screen. Arguments that are not a surface, or a surface with no valid intent, answer at once with
|
|
3822
|
+
`{error: 'invalid-arguments'}`. Where `thread.surface(id)` gives nothing, as with an application's
|
|
3823
|
+
own `surface` renderer, an operation is reported (`surface-unavailable`) and a surface tool's call
|
|
3824
|
+
answered at once with `{error: 'surface-unavailable'}`. With `inlineSurfaces`, surface fences in answer text become
|
|
3825
|
+
surfaces after the prose before them, and the prose after continues in `<messageId>#2`; a fence
|
|
3826
|
+
still open at the message's end is reported and its surface cancelled when the run ends, and so
|
|
3827
|
+
is any surface that reaches the end of its run without its `end` (`unterminated-surface`). A
|
|
3828
|
+
`CUSTOM` event named `surfaceEvent` carries one operation or `{ops, token?}`; the token of the
|
|
3829
|
+
event that opens a surface is kept. Each surface is `surface:<runId>/<surface>`, so `s1` in two
|
|
3830
|
+
runs is two surfaces; an operation for an answered surface is refused and reported. A surface
|
|
3831
|
+
belongs to the source that opened it — custom event, surface tool or fence — and an operation
|
|
3832
|
+
from another source is refused (`not-allowed`), never merged; give custom-event surfaces ids a
|
|
3833
|
+
model cannot predict, since a server `begin` for an id the model took first is refused. A reply's
|
|
3834
|
+
token is the application's for a custom event, the tool call id for a surface tool, and the run
|
|
3835
|
+
id for an inline surface.
|
|
3836
|
+
- **Strictness** — `*_CHUNK` events are expanded into start, content and end. Content, arguments
|
|
3837
|
+
or an end for something never started is dropped and reported (`out-of-order`), never drawn. A
|
|
3838
|
+
start for a closed message or tool call reopens it, in this run or a later one, and its content
|
|
3839
|
+
continues; a reopened call stands as `queued`, loses its card or surface, and is asked about
|
|
3840
|
+
again once its arguments are complete. A start for an id still open, or for a call already
|
|
3841
|
+
decided or answered, is ignored and reported (`duplicate-start`), so `ontoolresult` fires once
|
|
3842
|
+
for a call and an answered surface's receipt stays; and a message id with one of the adapter's prefixes (`approval:`, `tool:`, `trace:`, `surface:`,
|
|
3843
|
+
`error:`, `think:`) is refused. `handle()` never throws: what it cannot read is reported and
|
|
3844
|
+
dropped. `destroy()` closes a run still open as stopped, cancels unanswered surface-tool surfaces
|
|
3845
|
+
(their replies still reach `ontoolresult`, with `reason: 'stopped'`) and expires undecided
|
|
3846
|
+
approvals before it stops listening, and reports none of that through `onerror`. Every event the thread does not draw goes to
|
|
3847
|
+
`onunknown`, including steps, message snapshots, activities, subagents and the deprecated
|
|
3848
|
+
`THINKING_*` names.
|
|
3849
|
+
<!-- /doc -->
|
|
3850
|
+
|
|
3851
|
+
<!-- doc:surface -->
|
|
3852
|
+
### Surface — `new Surface(target, options)` / `openSurface()` / `elicit()` / `surfaceText()`
|
|
3853
|
+
|
|
3854
|
+
Interface an agent composes as JSON — a rich answer, or a dialog asking the person something —
|
|
3855
|
+
validated and drawn with the library's own components. A surface declares one `intent`, which fixes
|
|
3856
|
+
its frame, default actions and reply, and composes its body from catalog nodes laid out by id. The
|
|
3857
|
+
format, the node reference and the rules a model reads are in `docs/agent-surfaces.md`; the catalog
|
|
3858
|
+
functions (`narrowCatalog`, `surfaceSchema`, `surfaceTools`, `surfacePrompt`) and the validator are
|
|
3859
|
+
in `src/components/surface/catalog.js` and `validate.js`, importable on a server.
|
|
3860
|
+
|
|
3861
|
+
- **Options** — `document` (a whole surface; leave it out to stream), `policy`, `resolve: {ref,
|
|
3862
|
+
link, asset, entities}`, `authors`, `userInitiated: false`, `headingLevel: 3`, `locale`,
|
|
3863
|
+
`catalog` (a narrowed catalog; the full one by default), `token: null` (the application's opaque
|
|
3864
|
+
string, at most 512 characters, copied unchanged into every reply), `reply: null` (a stored reply:
|
|
3865
|
+
the surface starts as its receipt), `labelledBy: null` (the id of a title shown by a host),
|
|
3866
|
+
`chartAdapter: null` (draws `chart` nodes; without one a chart shows its data table), `msg`.
|
|
3867
|
+
- **Methods** — `apply(op)`, `write(chunk)` (operation lines in chunks), `end()` (the stream is
|
|
3868
|
+
over), `getValues()`, `getErrors()`, `cancel(reason)`, `supersede()`, `focus()`, `toDocument()`,
|
|
3869
|
+
`getReply()`, `destroy()`.
|
|
3870
|
+
- **Events** — `reply {reply}` exactly once, `error {errors}` each time new problems are found,
|
|
3871
|
+
`change {name, value}`, `ready` at the first drawn state, `end`.
|
|
3872
|
+
- **Streaming** — every line is validated before it is drawn. A child that has not arrived is a
|
|
3873
|
+
skeleton line, and every action but Cancel stays disabled until the surface's `end`. What is
|
|
3874
|
+
invalid is dropped and reported; an unknown node, or one outside a narrowed catalog, draws "This
|
|
3875
|
+
part could not be shown". A surface whose stream ends without its `end` keeps its actions
|
|
3876
|
+
disabled. A node that fails while drawing shows the same line beside the rest of the surface, and
|
|
3877
|
+
is reported as `draw-failed`. One operation costs what it touches: a `data` operation redraws only
|
|
3878
|
+
the nodes bound to the path it changed.
|
|
3879
|
+
- **Limits** — 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 50 fields,
|
|
3880
|
+
64 choices, 8 actions, 1 MB of data, and 100,000 table cells across all tables, each `$data`
|
|
3881
|
+
binding counted where it is used. What is over a limit is dropped and reported, and the table
|
|
3882
|
+
budget holds while a surface streams; rows past it draw the fallback.
|
|
3883
|
+
- **Actions** — the intent's defaults (`submit`, `confirm`, `approve`/`reject`) or the surface's own,
|
|
3884
|
+
plus Cancel for `ask`, `choose`, `confirm` and `questionnaire`, and for a `review` left without
|
|
3885
|
+
its `reject`. The ids `cancel` and `dismiss` are reserved: an action using one is dropped and
|
|
3886
|
+
reported, as is any action of a `questionnaire`'s own. Escape closes whatever waits for an answer
|
|
3887
|
+
(`cancel`, or `dismiss` for a `show` surface with actions), except while it closes something
|
|
3888
|
+
inside the surface (an open picker, an expanded list) or another handler took it. The answering
|
|
3889
|
+
defaults (`submit`, `confirm`, `approve`) and an own action with `kind: 'primary'` check the
|
|
3890
|
+
visible inputs first, move focus to the first invalid one, and send the values; any other own
|
|
3891
|
+
action replies at once with `values: {}`. With several primary actions the one pressed answers,
|
|
3892
|
+
and Enter in a field presses the first. A single `choice` must be picked before an answering
|
|
3893
|
+
action replies; a `multiple` one may be empty. A questionnaire's `next` that names a dropped step,
|
|
3894
|
+
or can lead back to its own step, is dropped and reported.
|
|
3895
|
+
- **Policy** — `policy(action, surface)` returns `'allow'`, `'confirm'` (a confirmation Dialog),
|
|
3896
|
+
`'type-to-confirm'` (`Dialog.confirm({confirmText})`) or `'deny'` (the action is not drawn, and
|
|
3897
|
+
the reply lists it under `removed`), or `{level, confirmText?, message?}`. Supply `confirmText`
|
|
3898
|
+
for `type-to-confirm`: without it the person types the fixed word "confirm"
|
|
3899
|
+
(`surface.typeToConfirm`), never text from the surface. A questionnaire's own Submit is put to the
|
|
3900
|
+
policy up front, as `submit`; denied, it is hidden and reported. The policy is synchronous:
|
|
3901
|
+
nothing waits for it, so a Promise denies, like a policy that throws. Anything else counts as
|
|
3902
|
+
`confirm`. Nothing in a surface can lower it: `kind: 'danger'` is presentation only, and
|
|
3903
|
+
confirmation keys in a surface are dropped.
|
|
3904
|
+
- **Reply** — `{zx: 'reply/1', surface, action, key, values, confirmation, at, token?, removed?,
|
|
3905
|
+
reason?}`. `key` is `<surface>#<action>`; `confirmation` is `clicked`, `typed` or `null`;
|
|
3906
|
+
`reason` says why a closing reply (`cancel`, `dismiss`) was sent: `cancelled`, `escape`,
|
|
3907
|
+
`closed`, `superseded`, `stopped`, `destroyed`, or the application's. Submit and every action
|
|
3908
|
+
reply, and so do Cancel, Escape, `cancel()`, `supersede()` and destroying an unanswered surface
|
|
3909
|
+
(`dismiss`), whatever happens while its receipt is drawn. When its run stops, the application
|
|
3910
|
+
calls `surface.cancel('stopped')`. A surface
|
|
3911
|
+
whose `begin` never validated still replies once: `surface` is the id it was given when that was
|
|
3912
|
+
a valid id, `null` otherwise. A reply records what the page did; the server runs its policy again
|
|
3913
|
+
before it acts.
|
|
3914
|
+
- **Conditions** — a node's `visible` and a schema property's `x-zx.visible` are evaluated as values
|
|
3915
|
+
change. A hidden input keeps what was typed, is not required, and is left out of `getValues()`
|
|
3916
|
+
and the reply. A node that hides while it holds the focus hands it to the input whose value hid
|
|
3917
|
+
it.
|
|
3918
|
+
- **Receipt** — answered, the surface carries `data-state="answered"`: inputs become read-only
|
|
3919
|
+
displays of what was answered, tables stay with their selected rows marked, and the actions give
|
|
3920
|
+
way to a verdict line. A restored surface (`reply`) shows what that reply answered.
|
|
3921
|
+
`surfaceText(document, reply)` gives the same receipt as plain text, with choice titles rather
|
|
3922
|
+
than raw values and never a hidden input or step, whatever the reply carries.
|
|
3923
|
+
- **Field types** — a schema property's `x-zx.field` draws through `Field`. The surface registers the
|
|
3924
|
+
types it needs only where nothing draws them yet, so an adapter the application registered with
|
|
3925
|
+
`Field.register()` stays.
|
|
3926
|
+
- **Placement** — `openSurface(document, {placement, target, …})` resolves with the reply. A sheet
|
|
3927
|
+
or a dialog the document asks for is honoured only with `userInitiated`; otherwise the surface goes
|
|
3928
|
+
inline into `target`. Closing the sheet or dialog replies `cancel`. A document that cannot begin
|
|
3929
|
+
rejects with a `TypeError` (its `errors` attached) before anything opens; given its `reply`, it
|
|
3930
|
+
resolves with it at once. `signal` withdraws it: on abort the surface is cancelled with the reason
|
|
3931
|
+
`stopped` and the promise resolves that reply — a sheet or dialog closes, an inline surface stays
|
|
3932
|
+
as its receipt — and a signal already aborted resolves it without drawing anything. Removing an
|
|
3933
|
+
inline `target` is not noticed: abort the signal or destroy the surface so the promise settles.
|
|
3934
|
+
- **Elicitation** — `elicit({message, requestedSchema}, options)` draws an `ask` form in a Dialog,
|
|
3935
|
+
or inline into `options.target`, and resolves `{action: 'accept', content}`, `{action: 'decline'}`
|
|
3936
|
+
or `{action: 'cancel'}`. A schema outside the subset (a nested object, a pattern, …) rejects with
|
|
3937
|
+
a `TypeError` naming what is unsupported. The message is drawn as plain text, never as markup;
|
|
3938
|
+
the labels resolve through `msg` (by language, then flat), the host translator, then English.
|
|
3939
|
+
`options.signal` withdraws the request: it resolves `cancel`.
|
|
3940
|
+
- **MCP elicitation** — `elicitationHandler({serverName, authors?, target?, open?, msg?})` returns
|
|
3941
|
+
`(params, {signal}?) => Promise<{action, content?}>` for an MCP client to install; `MCP_ELICITATION_VERSION`
|
|
3942
|
+
(`'2026-07-28'`) names the revision it implements. Call it with the `params` of an
|
|
3943
|
+
`elicitation/create` request, or of each `inputRequests` entry whose `method` is
|
|
3944
|
+
`elicitation/create` in an `input_required` result, and send what it resolves back — in
|
|
3945
|
+
`inputResponses` under the same key, with `requestState` echoed unchanged. Fields a mode does not
|
|
3946
|
+
use, such as an `elicitationId`, are ignored. The byline says "Asked by <server>": the
|
|
3947
|
+
`authors[serverName].name` when listed, else `serverName`, which is required. Abort `signal` when
|
|
3948
|
+
the request is withdrawn (the server cancelled it, the call timed out, the session closed, or the
|
|
3949
|
+
inline `target` was removed): the surface is cancelled, nothing opens, and it resolves `cancel`.
|
|
3950
|
+
- Form mode, the default without `mode`, is `elicit()`; a schema outside the subset rejects with
|
|
3951
|
+
its `TypeError`, so the client can answer the server with an error. Single and multiple choice
|
|
3952
|
+
(`enum`, `oneOf`, `items.enum`, `items.anyOf`) and defaults are supported; the deprecated
|
|
3953
|
+
`enumNames` is reported as unsupported.
|
|
3954
|
+
- URL mode is a `confirm` surface that asks first: the server's message as plain text, the page's
|
|
3955
|
+
host emphasised, its full address, a warning for an internationalised host, and no link. Nothing
|
|
3956
|
+
is fetched or opened before the person agrees. Open page opens the address in a new tab with
|
|
3957
|
+
`noopener` and `noreferrer`, inside the click, and resolves `{action: 'accept'}`; Decline
|
|
3958
|
+
resolves `decline`; Cancel, Escape or closing the dialog resolves `cancel`. The address must be
|
|
3959
|
+
an absolute lower-case `https://` URL without credentials, checked and normalised like a surface
|
|
3960
|
+
link; anything else rejects with a `TypeError`. `open(url)` replaces the opener: it must open a
|
|
3961
|
+
browsing context that cannot reach the application, and `false` or a throw answers `cancel`.
|
|
3962
|
+
|
|
3963
|
+
```js
|
|
3964
|
+
const answer = elicitationHandler({ serverName: 'Orders server' });
|
|
3965
|
+
const inputResponses = {};
|
|
3966
|
+
for (const [key, request] of Object.entries(result.inputRequests ?? {})) {
|
|
3967
|
+
if (request.method === 'elicitation/create') inputResponses[key] = await answer(request.params);
|
|
3968
|
+
}
|
|
3969
|
+
await client.callTool({ ...call, inputResponses, requestState: result.requestState });
|
|
3970
|
+
```
|
|
3971
|
+
- **Safety** — no string reaches the page as HTML. Records are drawn through `resolve.ref` as an
|
|
3972
|
+
`EntityRef`; links are `https:` only, show their host, and pass `resolve.link`, which may refuse
|
|
3973
|
+
them; nothing is loaded from an address the surface gives.
|
|
3974
|
+
- **Accessibility** — a surface that asks is a `<form>` labelled by its title, any other a labelled
|
|
3975
|
+
region; the title is at `headingLevel` and its `heading` nodes one and two below, up to h6; a chart offers its data table; the byline says
|
|
3976
|
+
"Composed by <author>".
|
|
3977
|
+
|
|
3978
|
+
```js
|
|
3979
|
+
const surface = new Surface(null, {
|
|
3980
|
+
document, // from the model's show_surface call
|
|
3981
|
+
token: issuedToken,
|
|
3982
|
+
policy: (action) => (action.tool === 'mail.send' ? 'confirm' : 'allow'),
|
|
3983
|
+
resolve: { entities: ['company'], ref: (ref) => ({ id: ref.id, title: names[ref.id] }) },
|
|
3984
|
+
onreply: ({ detail }) => sendToolResult(detail.reply)
|
|
3985
|
+
});
|
|
3986
|
+
```
|
|
3987
|
+
<!-- /doc -->
|
|
3988
|
+
|
|
3989
|
+
<!-- doc:run-status -->
|
|
3990
|
+
### RunStatus
|
|
3991
|
+
|
|
3992
|
+
Where an agent's run stands, for a run panel or a narrow header: the state as a glyph and a word,
|
|
3993
|
+
one sentence on what is happening, the steps as a progressbar, when it started and how long the
|
|
3994
|
+
agent has worked, the tokens, and the cost against a budget. It draws the values it is given and
|
|
3995
|
+
announces nothing itself; the thread the run belongs to announces its milestones.
|
|
3996
|
+
|
|
3997
|
+
- **Options** — `state` (a run state: `queued`, `running`, `waiting`, `paused`, `blocked`, `done`,
|
|
3998
|
+
`failed`, `stopped`, `skipped`; default `'queued'`, reflected as `data-state`), `summary` (one
|
|
3999
|
+
sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
|
|
4000
|
+
(local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
|
|
4001
|
+
it is a number), `tokens: [in, out]|number|null` (the pair, or the total as one number),
|
|
4002
|
+
`tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`,
|
|
4003
|
+
`actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
|
|
4004
|
+
`now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
|
|
4005
|
+
labels).
|
|
4006
|
+
- **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
|
|
4007
|
+
"3 of 6 steps"; the actions as small buttons; and a `<dl>` of Started, Working time, Waiting
|
|
4008
|
+
since (while `waiting`) or Blocked since (while `blocked`), Finished / Failed at / Stopped at
|
|
4009
|
+
(once the run is over), Model, Tokens ("18,420 in · 1,236 out", or "22,840" for a total) and
|
|
4010
|
+
Cost. With a `budget` the cost is a `role="meter"` reading "€0.14 of €2.00" whose `data-level`
|
|
4011
|
+
is `warning` from 80% and `danger` at 100%. With a `tokenBudget` the tokens are a meter the same
|
|
4012
|
+
way, in the locale's compact figures (`Intl.NumberFormat` `notation: 'compact'`): "22.8K of 60K
|
|
4013
|
+
tokens"; without one they stay text. A time on another day than today shows its date too.
|
|
4014
|
+
- **Blocked** — `blocked` is a glyph and the word "Blocked" in the danger tone, and the steps bar
|
|
4015
|
+
takes the danger tone. A blocked run is not over: it shows "Blocked since" from `waitingSince`
|
|
4016
|
+
and never a finished time.
|
|
4017
|
+
- **Compact** — `compact: true` (reflected as `data-compact`) draws only the state, glyph and
|
|
4018
|
+
word, as a pill for a header too narrow for the panel. `compact: 'icon'`
|
|
4019
|
+
(`data-compact="icon"`) draws the glyph alone, for a list row: the word stays in the pill,
|
|
4020
|
+
visually hidden, as its accessible text, and is the pill's `title` tooltip.
|
|
4021
|
+
- **Ticking** — while `state` is `running` and `ticking` is on, the working time counts on once a
|
|
4022
|
+
second from `workMs` and the moment of the last `update()`, through one interval that sleeps
|
|
4023
|
+
while the page is hidden. Leaving `running` freezes the clock where it stands. `now` replaces
|
|
4024
|
+
the clock, both for that count and for deciding whether a time is today; a fixed `now` makes the
|
|
4025
|
+
panel deterministic for screenshots and tests. It is fixed at construction.
|
|
4026
|
+
- **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
|
|
4027
|
+
not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
|
|
4028
|
+
the action at the same index, or the nearest one left. When no action is left the panel itself
|
|
4029
|
+
holds focus (`tabindex="-1"`, removed again once focus moves on).
|
|
4030
|
+
- **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
|
|
4031
|
+
update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
|
|
4032
|
+
(the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
|
|
4033
|
+
- **Events** — `action {index, action}`, after the descriptor's own `onclick`.
|
|
4034
|
+
<!-- /doc -->
|
|
4035
|
+
|
|
4036
|
+
<!-- doc:composer -->
|
|
4037
|
+
### Composer — the message box of an agent conversation
|
|
4038
|
+
|
|
4039
|
+
A text that grows with what is written, Send (Stop while the agent works), attachments, `@`
|
|
4040
|
+
mentions, `/` commands, extra tools, removable context chips, and a queue for messages written while
|
|
4041
|
+
the agent works. It keeps only unsent messages: `send` hands the text, files, mentions and context to
|
|
4042
|
+
the application, which owns the conversation and the transport.
|
|
4043
|
+
|
|
4044
|
+
- **Constructor** — `new Composer(null, options)` creates its own root; `new Composer(element,
|
|
4045
|
+
options)` takes over an element and restores it on `destroy()`.
|
|
4046
|
+
- **Options** — `label` (accessible name of the text and of the `role="group"` root, English
|
|
4047
|
+
`Message`), `placeholder`, `value`, `submitKey: 'enter'|'mod+enter'`, `busy: false`,
|
|
4048
|
+
`queue: false`, `queueLimit: 10` (see Queue),
|
|
4049
|
+
`disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
|
|
4050
|
+
`maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
|
|
4051
|
+
description?, icon?}]` or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
|
|
4052
|
+
`tools: []` (`[{id, label, icon, pressed?, expanded?, controls?, disabled?}]` — `pressed` makes a
|
|
4053
|
+
toggle, `expanded`/`controls` a disclosure; see Tools), `icons: {}` (`attach`, `commands` glyphs),
|
|
4054
|
+
`context: [{id, label,
|
|
4055
|
+
icon?, ref?}]`, `hint` (quiet text beside Send), `note` (a quiet line under the composer, also
|
|
4056
|
+
its description), `sendLabel: null` (visible text on Send, see Send), `draftKey: null`,
|
|
4057
|
+
`minRows: 1` (the text never shrinks below it, even empty; capped at `maxRows`), `maxRows: 10`
|
|
4058
|
+
(it scrolls beyond), `msg`.
|
|
4059
|
+
- **Methods** — `focus()`, `getValue()`, `setValue(text)`, `insertText(text)` (types at the caret
|
|
4060
|
+
as the person would — text ending in `@` opens the suggestions), `clear()` (text, files and draft;
|
|
4061
|
+
context stays), `setBusy(busy)`, `isBusy()`, `setDisabled(disabled)`, `setHint(text)`,
|
|
4062
|
+
`setNote(text)` (an empty text hides either), `update(partial)`, `setTools(tools)`,
|
|
4063
|
+
`setToolPressed(id, pressed)`, `addFiles(files)`, `getFiles()`, `addContext(chip)` (replaces a
|
|
4064
|
+
chip with the same id), `removeContext(id)`, `getContext()`, `getQueue()`, `clearQueue()`,
|
|
4065
|
+
`removeQueued(id)`, `destroy()`. The setters emit nothing, except that `setBusy(false)` sends the
|
|
4066
|
+
next queued message; `clearQueue()` and `removeQueued(id)` emit `dequeue`.
|
|
4067
|
+
- **update(partial)** — changes `label`, `placeholder`, `hint`, `note`, `submitKey`, `sendLabel`,
|
|
4068
|
+
`disabled` and `busy` in place; a key left out or `undefined` is kept, other keys are ignored.
|
|
4069
|
+
The text, its caret and selection, the focus, the attachments, the context chips and the draft
|
|
4070
|
+
all stay, so a placeholder that names the chosen model follows the model picker without
|
|
4071
|
+
recreating the composer: `composer.update({placeholder: 'Message Halden 3 Deep'})`.
|
|
4072
|
+
`label: null` returns to `composer.label`; an empty `placeholder` removes it.
|
|
4073
|
+
- **Events** — `send {text, files, mentions, context}` is preventable: unless prevented, the text,
|
|
4074
|
+
files and draft clear; it never fires with an empty text and no files, nor while busy. `text` is
|
|
4075
|
+
trimmed; `mentions` are the picked items whose `@<label>` is still in the text. A message from the
|
|
4076
|
+
queue also carries `queued: true`. `queue {item, items}`, `dequeue {item, items, reason:
|
|
4077
|
+
'sent'|'removed'|'edited'|'cleared'}`; `items` is the queue as it then stands. `stop`,
|
|
4078
|
+
`input {text}`, `attach {files}` (preventable, before the files are added), `remove {kind:
|
|
4079
|
+
'file'|'context', id, file?, chip?}` (after the reader removes one), `mention {item}`,
|
|
4080
|
+
`command {item}` (the application's own item), `tool {id, tool}` (a copy of the tool as it
|
|
4081
|
+
stands, `pressed` included), `historyprevious`.
|
|
4082
|
+
- **Keyboard** — `submitKey: 'enter'`: Enter sends, Shift+Enter breaks the line;
|
|
4083
|
+
`'mod+enter'`: Cmd+Enter (Ctrl+Enter elsewhere) sends, Enter breaks the line. A key during an IME
|
|
4084
|
+
composition never sends. Escape closes the suggestions, otherwise emits `stop` while busy (and is
|
|
4085
|
+
left alone when idle, so a surrounding dialog can close). ArrowUp on an empty text emits
|
|
4086
|
+
`historyprevious`; `/` on an empty text opens the commands. In the suggestions, Up and Down move,
|
|
4087
|
+
Enter or Tab picks, Escape closes. Tools are ordinary buttons in the tab order (Enter or Space).
|
|
4088
|
+
With `queue`, the send key queues while busy. Tab reaches each queued row, a toolbar of Edit and
|
|
4089
|
+
Remove: Left and Right move between them, Home and End go to the first and last, and Delete on
|
|
4090
|
+
either removes the row. No key is bound on the document.
|
|
4091
|
+
- **Tools** — icon buttons in the bar after Attach and Commands, each named by its `label` (also
|
|
4092
|
+
its `title` tooltip). A boolean `pressed` makes a toggle with `aria-pressed`, drawn with the
|
|
4093
|
+
neutral current fill and an edge; without it the tool is a plain button. Pressing one emits
|
|
4094
|
+
`tool`; the composer never changes `pressed` itself — call `setToolPressed(id, !tool.pressed)`.
|
|
4095
|
+
`setTools(tools)` redraws them, keeping the focus on the tool with the same id (on the text when
|
|
4096
|
+
that tool is gone or disabled). An entry without `id`, `label` or `icon` is left out, as is a
|
|
4097
|
+
repeated id; other fields on a tool are handed back in `tool`. `icon` is a built-in glyph name or
|
|
4098
|
+
one the application registered with `registerIcons()`. Tools are disabled with the composer.
|
|
4099
|
+
- **Send** — one button that swaps its glyph, name and `aria-keyshortcuts` between Send and Stop.
|
|
4100
|
+
With `sendLabel` (`'Start task'`) it shows the glyph and that text, which is also its accessible
|
|
4101
|
+
name; while busy it reads `composer.stop` ("Stop"). In a composer narrower than 24rem (a phone, a
|
|
4102
|
+
side column) the text is visually hidden and Send is the square glyph again — the text stays its
|
|
4103
|
+
accessible name and its tooltip.
|
|
4104
|
+
- **Queue** — with `queue: true`, the send key while busy adds the message to the queue and clears
|
|
4105
|
+
the composer; the button stays Stop and Escape still stops the run. A queued message keeps the
|
|
4106
|
+
text, files, mentions and context chips it had when it was queued. The queue shows at the top of
|
|
4107
|
+
the box as a list labelled "Queued (2)", each row with its text on one line, Edit and Remove, and a
|
|
4108
|
+
polite status says "Queued; sends when the agent finishes" once per message. When `setBusy(false)`
|
|
4109
|
+
ends busy, the first message is sent as a normal `send`, and the next waits for the next time busy
|
|
4110
|
+
ends. Nothing is sent while the composer is disabled, and what is being written stays in the text.
|
|
4111
|
+
A prevented `send` keeps the message first in line. Edit takes the text, files and mentions back
|
|
4112
|
+
into the composer, removes the row and emits `input`; when something is already written or
|
|
4113
|
+
attached it asks first through `Dialog.confirm`. At `queueLimit` the send key is refused, the
|
|
4114
|
+
message stays where it is, and the hint says why until there is room. Stop keeps the queue, so the
|
|
4115
|
+
next message goes when the application ends busy: call `clearQueue()` in the `stop` listener to
|
|
4116
|
+
drop it with the run. The queue is session state: it is not kept with the draft, and `destroy()`
|
|
4117
|
+
drops it. Only a sent message belongs in the conversation, so queued messages are not thread items.
|
|
4118
|
+
- **Mentions** — the query is the text after the trigger up to the caret, with no whitespace;
|
|
4119
|
+
picking writes `@<label> `. An array is filtered by label prefix, word prefix, label substring,
|
|
4120
|
+
then id prefix or a word of the description, ignoring case and accents. A function answers the
|
|
4121
|
+
query itself; a stale Promise is ignored.
|
|
4122
|
+
- **Commands** — opened in a `Launcher` the composer creates on first use and destroys with
|
|
4123
|
+
itself; an item with `items` opens a page. The commands keep the order given. A Commands button
|
|
4124
|
+
in the bar opens the same list for pointer and touch.
|
|
4125
|
+
- **Files** — the Attach button, pasting files, and dropping files on the composer (the root shows
|
|
4126
|
+
`data-state="dropping"` and a drop label meanwhile) add attachments, filtered by `accept` and
|
|
4127
|
+
capped by `maxFiles`.
|
|
4128
|
+
- **Accessibility** — the `<textarea>` keeps its textbox role. While suggestions show it carries
|
|
4129
|
+
`aria-autocomplete="list"`, `aria-controls` (the listbox) and `aria-activedescendant` (the
|
|
4130
|
+
highlighted `role="option"`), and a polite status says how many there are. Attachments and
|
|
4131
|
+
context chips are labelled lists, each chip with a button named "Remove <name>". Send is never
|
|
4132
|
+
disabled while the composer is live (it is `aria-disabled` when there is nothing to send), so
|
|
4133
|
+
the focus it holds survives a run ending. A toggled tool states itself with `aria-pressed`, not
|
|
4134
|
+
colour alone. The queue is a labelled ordered list; each row's toolbar is named by its text, and
|
|
4135
|
+
when a message leaves the queue the focus stays on the row, on the row now in its place, or in the
|
|
4136
|
+
text.
|
|
4137
|
+
- **Draft** — with `draftKey`, the unsent text is kept through `storage('composer')`, restored
|
|
4138
|
+
when the composer is created without a `value`, and cleared on send and `clear()`.
|
|
4139
|
+
<!-- /doc -->
|
|
4140
|
+
|
|
4141
|
+
<!-- doc:prompt-starters -->
|
|
4142
|
+
### PromptStarters — starting points for an empty conversation
|
|
4143
|
+
|
|
4144
|
+
A labelled group of buttons, each with a title and, muted beneath it, its description or else its
|
|
4145
|
+
text. PromptStarters only reports the pick and never sends anything: the application decides
|
|
4146
|
+
whether a starter fills the composer or sends at once.
|
|
4147
|
+
|
|
4148
|
+
- **Constructor** — `new PromptStarters(null, options)` creates its own root; `new
|
|
4149
|
+
PromptStarters(element, options)` takes over an element and restores it on `destroy()`.
|
|
4150
|
+
- **Options** — `items: [{id, title, text, description?, icon?}]`, `label` (the group's accessible
|
|
4151
|
+
name, English `Suggestions`), `columns: 'auto'|1|2`, `headingLevel: null`, `msg`. An item without
|
|
4152
|
+
`id`, `title` or `text` is left out, as is a repeated id; other fields on an item are handed back
|
|
4153
|
+
in `pick`. `text` keeps its spaces and line breaks, so a prompt can end where the person goes on
|
|
4154
|
+
writing.
|
|
4155
|
+
- **Columns** — `'auto'` is two columns and one in a container narrower than 32rem, read through a
|
|
4156
|
+
container query, so it behaves the same in a split pane, a dialog or a phone. The root fills the
|
|
4157
|
+
width it is given.
|
|
4158
|
+
- **Heading** — `headingLevel: null` keeps `label` for assistive technology only. A level draws it
|
|
4159
|
+
above the starters as a heading of that level, which then names the group.
|
|
4160
|
+
- **Methods** — `setItems(items)` (the focus on a starter stays on the starter with the same id;
|
|
4161
|
+
emits nothing), `destroy()`.
|
|
4162
|
+
- **Events** — `pick {item}`, with a copy of the starter as given.
|
|
4163
|
+
- **Keyboard** — each starter is a button in the Tab order, pressed with Enter or Space. There are
|
|
4164
|
+
no custom keys.
|
|
4165
|
+
- **Accessibility** — the root is `role="group"`. Each button is named by its title and described
|
|
4166
|
+
by the line beneath it. The line is clamped to two lines on screen; its whole text stays the
|
|
4167
|
+
description. Without items the group is hidden.
|
|
4168
|
+
|
|
4169
|
+
```js
|
|
4170
|
+
const starters = new PromptStarters(null, {
|
|
4171
|
+
items: [
|
|
4172
|
+
{ id: 'reply', title: 'Draft a reply', text: 'Draft a short, friendly reply to this customer:\n\n' },
|
|
4173
|
+
{ id: 'review', title: 'Prepare the review', text: 'Summarise this week’s escalations.', icon: 'list' }
|
|
4174
|
+
],
|
|
4175
|
+
onpick: ({ detail }) => composer.setValue(detail.item.text).focus()
|
|
4176
|
+
});
|
|
4177
|
+
```
|
|
4178
|
+
<!-- /doc -->
|
|
4179
|
+
|
|
4180
|
+
<!-- doc:approval-card -->
|
|
4181
|
+
### ApprovalCard
|
|
4182
|
+
|
|
4183
|
+
A request that holds an agent's run until a person answers it: what the agent wants to do, what
|
|
4184
|
+
will happen, a preview of what it produces, and Approve, Edit, and Reject. Answered, it freezes
|
|
4185
|
+
into the record of what was decided, by whom, and when. The card never acts on its own — it emits
|
|
4186
|
+
the answer, and the application carries it out.
|
|
4187
|
+
|
|
4188
|
+
- **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
|
|
4189
|
+
'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `headingLevel: 3`,
|
|
4190
|
+
`status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
|
|
4191
|
+
amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
|
|
4192
|
+
is accepted for `content`, as the thread model spells it), `fields: Record<string,
|
|
4193
|
+
FieldOptions>|null` (the Edit form — no fields, no Edit), `values: {}`, `confirmText: null`,
|
|
4194
|
+
`reason: 'optional'|'required'|'none'` (whether Reject asks why), `answeredBy: null` (the verdict's
|
|
4195
|
+
"you" when null), `answeredAt: null` (local ISO date-time or Date), `edited: false`,
|
|
4196
|
+
`editedKeys: null` and `rejectReason: null` (for a card restored from a record), `now: null`
|
|
4197
|
+
(a `() => Date` clock), `keys: true`, and `msg`.
|
|
4198
|
+
- **Edited values** — `edited: true` lists every field under "Edited by you"; `editedKeys:
|
|
4199
|
+
['subject']` lists only those (in field order) and on its own marks the card edited. The card's
|
|
4200
|
+
own Edit flow keeps `editedKeys` as the union of every save so far, so a restored card and a
|
|
4201
|
+
card edited in place list the same thing.
|
|
4202
|
+
- **Events** — `approve {values}`, `edit {values, changed, editedKeys}`, `reject {reason}`, all
|
|
4203
|
+
**preventable** (on the component or on the bubbling `zx-*` event). Unless `approve` or `reject`
|
|
4204
|
+
is prevented the card moves to its answered state; a saved `edit` keeps it pending and adopts
|
|
4205
|
+
the values. `changed` names the fields this save changed. `editedKeys` is the union the card
|
|
4206
|
+
will list (null when it lists every field), so the application can store it with the record.
|
|
4207
|
+
Prevent an answer to refuse or defer it, then settle the card with `setStatus()`.
|
|
4208
|
+
- **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`,
|
|
4209
|
+
`details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
|
|
4210
|
+
place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
|
|
4211
|
+
now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
|
|
4212
|
+
included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
|
|
4213
|
+
`focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
|
|
4214
|
+
starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
|
|
4215
|
+
dialogs, including an open confirmation).
|
|
4216
|
+
- **Update in place** — `update()` is for a request the agent revises while it waits, or a record
|
|
4217
|
+
that changed. It redraws only what changed: values equal to what is drawn (compared by content,
|
|
4218
|
+
so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
|
|
4219
|
+
where it was. When the focused control goes away (Edit when `fields` go, the preview toggle when
|
|
4220
|
+
`preview` goes), focus moves to the card. A change closes a dialog only when the dialog no
|
|
4221
|
+
longer applies: new `fields` close the Edit form, a new `reason` closes the Reject dialog, a new
|
|
4222
|
+
`confirmText` closes the typed confirmation without approving. An open Edit form stays open over
|
|
4223
|
+
new `values`. Status goes through `setStatus()`. `update()` emits nothing.
|
|
4224
|
+
- **Approve** — with `confirmText`, Approve first opens `Dialog.confirm({confirmText, danger:
|
|
4225
|
+
true})` titled with the card's title; only a confirmed approval emits `approve`.
|
|
4226
|
+
- **Reject** — `reason: 'optional'` asks in a dialog with a textarea and accepts an empty answer;
|
|
4227
|
+
`'required'` keeps the Reject button disabled until the reason is non-empty; `'none'` rejects at
|
|
4228
|
+
once with `reason: ''`. Mod+Enter submits the Reject and Edit dialogs.
|
|
4229
|
+
- **Answered state** — no actions; the line under the title becomes the verdict ("Approved by you
|
|
4230
|
+
at 10:31"; the date is added when it is not today, by the `now` clock); the edited values and
|
|
4231
|
+
the reason (as a quote) stay. An answer given on the card, or a `setStatus()` without `at`,
|
|
4232
|
+
takes its time from `now`. `data-state` is the status, and the state pill is a `statusIcon()`
|
|
4233
|
+
glyph plus its word (waiting, done, skipped, stopped glyphs for pending, approved, rejected,
|
|
4234
|
+
expired).
|
|
4235
|
+
- **Keyboard** — A approves, E edits, R rejects, only while focus is inside the pending card, not
|
|
4236
|
+
in a text control, with no modifier held, and while none of the card's dialogs is open. The card
|
|
4237
|
+
binds no document key: an application that wants them from elsewhere forwards the event to
|
|
4238
|
+
`handleKey(event)`, which returns true and prevents the default when it used the key.
|
|
4239
|
+
`keys: false` stops the card listening on itself (and drops the key hints on its buttons).
|
|
4240
|
+
- **Accessibility** — `role="group"` labelled by the title heading and described by the
|
|
4241
|
+
description and the state line; a pending card says "The run is paused until you answer."
|
|
4242
|
+
(message `approvalCard.paused`). The preview toggle follows the APG Disclosure pattern.
|
|
4243
|
+
- **Consequence comes from the application** — whether an action needs `confirmText` (or
|
|
4244
|
+
`reason: 'required'`) is decided by the application from the tool the action triggers. It is
|
|
4245
|
+
never taken from model output: an agent that could set its own confirmation could also waive it.
|
|
4246
|
+
<!-- /doc -->
|
|
4247
|
+
|
|
4248
|
+
<!-- doc:run-trace -->
|
|
4249
|
+
### RunTrace
|
|
4250
|
+
|
|
4251
|
+
What an agent did during a run: a one-line summary ("Worked for 41 s · 5 tool calls · 9 sources ·
|
|
4252
|
+
1 retry") that opens into a timeline of its steps. A tool call opens to the arguments it was made
|
|
4253
|
+
with and what came back; a retry is drawn under the call it repeats; a hand-off shows both agents.
|
|
4254
|
+
The same component draws a plan: `task` steps under a `label` of the plan's own, the people's
|
|
4255
|
+
`ask` and `decision` steps among them, chosen one at a time with `selectable`. The trace changes
|
|
4256
|
+
only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
|
|
4257
|
+
|
|
4258
|
+
- **Options** — `steps: []` (`TraceStep[]`, in the order they started), `open: false` (the step
|
|
4259
|
+
list starts open), `label: null` (text the summary reads instead of the computed line — "Close
|
|
4260
|
+
September · 2 of 5 done"; every state but done still follows it as a word, "· Running"),
|
|
4261
|
+
`authors: {}` (who the steps' `actor` and `to` keys name), `showArguments: true`,
|
|
4262
|
+
`maxResult: 4000` (characters of a result shown before a "Show all" button; 0 shows every
|
|
4263
|
+
result whole), `summary: true` (false: no summary line, the list always shows — for a run panel
|
|
4264
|
+
whose state is told beside it), `kindIcons: null` (whether a step leads with its kind's glyph;
|
|
4265
|
+
null hides them for a plan whose steps are all `task`s), `selectable: false` (every step can be chosen, see Events), `ticking: false`
|
|
4266
|
+
(a running step that has `at` counts its time once a second, on from its `ms` when it was
|
|
4267
|
+
resumed), `now: null` (`() => Date`, the
|
|
4268
|
+
clock `ticking` counts against, for an application whose world is fixed on another date; real
|
|
4269
|
+
time when null), `formatTime: null` (`(at) => string`, how a step's start time is written;
|
|
4270
|
+
"10:31:05" when null), `icons: {}` (glyph per step kind over the built-in `search`→search,
|
|
4271
|
+
`read`→file, `query`→table, `write`→type, `run`→code, `call`→gear, `handoff`→link-2,
|
|
4272
|
+
`think`→dots, `task`→list, `ask`→mail, `decision`→check), `msg` (`runTrace.*` and the
|
|
4273
|
+
`agent.status.*` words).
|
|
4274
|
+
- **Methods** — `setSteps(steps)` (open steps stay open, focus stays on its step),
|
|
4275
|
+
`upsert(step)` (replaces the step with the same `id` and redraws only that step, keeping its
|
|
4276
|
+
retries, its open state, and focus on its row or links; a new step is appended, under the step
|
|
4277
|
+
it repeats when it has `retryOf`), `setLabel(text|null)` (null or `''` goes back to the computed
|
|
4278
|
+
line), `expand(id?)` (opens the list, and that step), `collapse(id?)` (closes the list, or only
|
|
4279
|
+
that step), `reveal(id)` (opens the list and the step, scrolls to it, focuses its row and marks
|
|
4280
|
+
it `data-state="revealed"` for 2 s; the scroll jumps under reduced motion), `getSteps()`,
|
|
4281
|
+
`isOpen()`, `destroy()` (also stops the clock).
|
|
4282
|
+
- **Events** — `toggle {id, open}` whenever the list (`id: null`) or a step opens or closes, from a
|
|
4283
|
+
click or a method; `reveal {id}`; `open {step, ref}` when one of a step's links is activated
|
|
4284
|
+
(copies; the application opens what the `ref` names); `select {id}` in a `selectable` trace when
|
|
4285
|
+
the reader activates a row with nothing to open, or opens a step's disclosure (not from
|
|
4286
|
+
`expand()` or `reveal()`, so an application can answer `select` with them).
|
|
4287
|
+
- **Rendering** — while a step runs the summary reads "Working…" with the step's `doing` line, and
|
|
4288
|
+
the step shows "Reading the policy…"; with `ticking` and an `at`, its end shows how long it has
|
|
4289
|
+
run ("41 s", "1 min 42 s"). A waiting or blocked run says so and names the step ("Blocked after
|
|
4290
|
+
12 s · 3 tool calls"); paused, stopped and failed runs say so first ("Failed after 12 s · 3
|
|
4291
|
+
tool calls"); a run no step of which has started reads "Not started · 6 steps". Counts are left
|
|
4292
|
+
out at zero, and `think`, `handoff`, `task`, `ask` and `decision` steps are not tool calls. Each
|
|
4293
|
+
step's muted meta line follows its label and wraps under it only when narrow: the `count`, a
|
|
4294
|
+
search's `sources`, the actor's name, the start time (`<time>`, tabular figures) and the
|
|
4295
|
+
`tokens` it used ("912 tokens"), each only when present. A step's `refs` (`ItemRef[]`, `{id,
|
|
4296
|
+
label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
|
|
4297
|
+
`icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
|
|
4298
|
+
name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
|
|
4299
|
+
otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
|
|
4300
|
+
`handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
|
|
4301
|
+
avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
|
|
4302
|
+
model — and its own label moves to the meta line.
|
|
4303
|
+
- **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
|
|
4304
|
+
(`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
|
|
4305
|
+
`<button>`. A step's links are buttons beside its row, never inside it, so no control holds
|
|
4306
|
+
another; each is reached with Tab. The running step carries `aria-current="step"`. Every state
|
|
4307
|
+
is a glyph and a word: visible for waiting, blocked, failed, stopped, skipped and queued steps
|
|
4308
|
+
(blocked and failed in the danger tone), visually hidden beside a finished step's duration and a
|
|
4309
|
+
running step's "…ing" line. The running glyph pulses only without a reduced-motion preference.
|
|
4310
|
+
The clock is one interval for the whole trace, running only while a counting step is in the open
|
|
4311
|
+
list and the page is visible. The trace has no live region; the thread it sits in announces
|
|
4312
|
+
milestones.
|
|
4313
|
+
- **State** — the root's `data-state` is the run's state (`running`, `waiting`, `blocked`,
|
|
4314
|
+
`paused`, `stopped`, `failed`, `queued`, `done`), and it is hidden while it has no steps. Each
|
|
4315
|
+
step's `<li>` carries `data-kind` and `data-status`.
|
|
4316
|
+
<!-- /doc -->
|
|
4317
|
+
|
|
4318
|
+
<!-- doc:source-list -->
|
|
4319
|
+
### SourceList
|
|
4320
|
+
|
|
4321
|
+
The sources an answer cites: a numbered chip (or row) for each, naming its site or title, with a
|
|
4322
|
+
card of its title, where it is, and the passage used on hover and focus. It never loads a favicon,
|
|
4323
|
+
a thumbnail, or any other remote resource.
|
|
4324
|
+
|
|
4325
|
+
- **Options** — `sources: []` (`Source[]`, numbered in order as the answer's `[n]` markers are),
|
|
4326
|
+
`label` (the visible label naming the list, by default the `sourceList.label` message; `''` or
|
|
4327
|
+
`null` drops it and names the list with that message), `layout: 'chips'|'list'` (`list` gives each source a row with
|
|
4328
|
+
its title and site), `numbered: true`, `icons: {}` (glyph per kind over the built-in
|
|
4329
|
+
`web`→link-2, `file`→file, `record`→table, `call`→gear), `msg`.
|
|
4330
|
+
- **Methods** — `setSources(sources)` (focus stays on the same source), `highlight(n)` (a number is
|
|
4331
|
+
the 1-based position, a string an `id`: scrolls to it, focuses it, and marks it
|
|
4332
|
+
`data-state="highlighted"` for 2 s — the answer to a BlockView `cite`), `getSources()`,
|
|
4333
|
+
`destroy()`.
|
|
4334
|
+
- **Events** — `select {source, n}`, **preventable** (on the component or on the bubbling
|
|
4335
|
+
`zx-select`). Unprevented, a `web` source opens its `href` in a new tab with
|
|
4336
|
+
`noopener,noreferrer`, and only when `safeHref()` accepts it and it is an absolute `https:` URL;
|
|
4337
|
+
the card shows that host. Every other kind is the application's to act on, for example
|
|
4338
|
+
`runTrace.reveal(source.call)`.
|
|
4339
|
+
- **Accessibility** — each source is a native `<button>` named "Source 1: bank.example" (the
|
|
4340
|
+
visible number and name, plus visually hidden words); its card is a `Tooltip`, so it is the
|
|
4341
|
+
button's description while open. The list is an `<ol>` labelled by the visible label. It is not
|
|
4342
|
+
a landmark, so a thread with many answers does not repeat a "Sources" region.
|
|
4343
|
+
- **Privacy** — the pure `sourceHref(source)` returns the only address a source may open, or null;
|
|
4344
|
+
nothing is fetched to draw a source.
|
|
4345
|
+
<!-- /doc -->
|
|
4346
|
+
|
|
3281
4347
|
<!-- doc:kernel -->
|
|
3282
4348
|
### Core helpers
|
|
3283
4349
|
|
|
@@ -3302,12 +4368,13 @@ bar.setBadge('mail', 8);
|
|
|
3302
4368
|
`{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
|
|
3303
4369
|
supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
|
|
3304
4370
|
so changing a placement means `destroy()` and a fresh `position()` call.
|
|
3305
|
-
- **i18n** — `setTranslator`, `setLanguage`, `getLanguage`, `translate`, `printf`, and
|
|
4371
|
+
- **i18n** — `setTranslator`, `setLanguage`, `getLanguage`, `translate`, `translatePlural`, `printf`, and
|
|
3306
4372
|
`defaultMessages`, the frozen English catalogue of every component key (`table.empty` → "No
|
|
3307
4373
|
records") that a host copies as the starting point for a locale.
|
|
3308
|
-
- **Dates** — `formatDate(d, fmt)`, `parseDate(s, fmt)` (tokens
|
|
4374
|
+
- **Dates** — `formatDate(d, fmt, {locale})`, `parseDate(s, fmt)` (tokens
|
|
3309
4375
|
`%d %m %Y %y %H %M %S %a %A %b %B %s`), `clampDate`, `isSameDay`, `addDays`, `addMonths`,
|
|
3310
|
-
`getWeekStart`.
|
|
4376
|
+
`getWeekStart`. A supported explicit `locale` takes precedence over `getLanguage()`, then
|
|
4377
|
+
English. Names and abbreviations come from `Intl`, preserving regional differences.
|
|
3311
4378
|
- **Keyboard** — `focusTrap`, `rovingTabindex`, `typeahead`.
|
|
3312
4379
|
- **Motion** — `prefersReducedMotion(element?)` → boolean, and
|
|
3313
4380
|
`watchMotion(element, fn, {signal?, immediate?})` → disposer, for code that animates in script;
|
|
@@ -3399,18 +4466,23 @@ Standalone exports with no DOM ownership and no lifecycle, importable individual
|
|
|
3399
4466
|
entry point as the components. See also the Kernel section for `Component`, `h`, `icon`, and
|
|
3400
4467
|
`position` — the substrate the components themselves are built on.
|
|
3401
4468
|
|
|
3402
|
-
- **Dates** — `formatDate(date, fmt)`, `parseDate(str, fmt)` (returns `null` when the
|
|
3403
|
-
not match, so it doubles as a validator), `clampDate(date, min, max)`,
|
|
3404
|
-
`addDays(date, n)`, `addMonths(date, n)`, `getWeekStart(lang?)` → `0` (Sunday)
|
|
3405
|
-
strftime-style tokens: `%d %m %Y %y %H %M %S %a %A %b %B %s`.
|
|
4469
|
+
- **Dates** — `formatDate(date, fmt, {locale})`, `parseDate(str, fmt)` (returns `null` when the
|
|
4470
|
+
string does not match, so it doubles as a validator), `clampDate(date, min, max)`,
|
|
4471
|
+
`isSameDay(a, b)`, `addDays(date, n)`, `addMonths(date, n)`, `getWeekStart(lang?)` → `0` (Sunday)
|
|
4472
|
+
or `1` (Monday). strftime-style tokens: `%d %m %Y %y %H %M %S %a %A %b %B %s`. Month and weekday
|
|
4473
|
+
names come from `Intl` in a supported explicit `locale`, then `getLanguage()`, then English.
|
|
4474
|
+
Regional English tags keep their own abbreviations and conventions. Explicit locale names take
|
|
4475
|
+
precedence over host date-name translations; without an explicit locale those translations apply.
|
|
4476
|
+
Short names use `Intl` unless a host supplies the corresponding short-name key.
|
|
3406
4477
|
- **Numbers, money and time** — `formatNumber(value, {locale, decimals, minDecimals, maxDecimals,
|
|
3407
4478
|
group=true})`, `formatCurrency(value, currency, {locale, decimals})`, `formatPercent(value,
|
|
3408
4479
|
{locale, decimals=0})` (takes a fraction, so `0.42` → `42%`), `formatFileSize(bytes, {locale,
|
|
3409
4480
|
decimals=1, standard='iec'})` (`'iec'` → KiB/MiB/GiB in steps of 1024, `'si'` → kB/MB/GB in steps
|
|
3410
4481
|
of 1000; `0` → `'0 B'`, trailing zeros dropped), `formatRelativeTime(date, {now=new Date(),
|
|
3411
4482
|
locale, numeric='auto'})` (picks the largest sensible unit from second to year; accepts a `Date`,
|
|
3412
|
-
Unix seconds, or an ISO string).
|
|
3413
|
-
`setLanguage()` drives all five
|
|
4483
|
+
Unix seconds, or an ISO string). A supported explicit `locale` takes precedence over
|
|
4484
|
+
`getLanguage()`, then English, so `setLanguage()` drives all five when no usable option is given.
|
|
4485
|
+
Nothing throws: `null`, `undefined` and `NaN` all format as
|
|
3414
4486
|
`''`, an invalid currency code falls back to plain number formatting, and every `Intl` instance
|
|
3415
4487
|
is cached because tables call these once per cell.
|
|
3416
4488
|
- **Utilities** — `debounce(fn, ms)` (trailing edge, preserves `this`), `throttle(fn, ms,
|
|
@@ -3424,15 +4496,23 @@ entry point as the components. See also the Kernel section for `Component`, `h`,
|
|
|
3424
4496
|
name, a `'-name'` prefix or a `{key, dir}` object for descending, or an accessor function,
|
|
3425
4497
|
comparing digit runs numerically and always sorting `null`, `undefined` and `NaN` last in either
|
|
3426
4498
|
direction; `uniqueBy(items, key?)` keeps the first occurrence.
|
|
3427
|
-
- **Escaping** — `
|
|
4499
|
+
- **Escaping** — `h()` rejects `innerHTML`, `outerHTML`, and `srcdoc` properties regardless of
|
|
4500
|
+
casing, and sanitizes `href` through `safeHref`. `htmlEscape(str)`, and `h.raw(html)` as the only
|
|
4501
|
+
sanctioned `innerHTML` path, for
|
|
3428
4502
|
component-generated markup only. `escapeRegExp(value)` makes user input safe as a literal
|
|
3429
4503
|
pattern, and `highlightMatch(text, query, {className='zx-mark'})` → `DocumentFragment` wraps
|
|
3430
4504
|
every case-insensitive occurrence in a `<mark>` built from text nodes, with no `innerHTML`
|
|
3431
4505
|
involved — the pairing every filtering list wants.
|
|
3432
|
-
- **Storage** — `storage(namespace, {area='local'})` → `{get, set, remove, keys, clear}`, a
|
|
4506
|
+
- **Storage** — `storage(namespace, {area='local'})` → `{get, set, remove, keys, clear, migrateLegacy}`, a
|
|
3433
4507
|
namespaced JSON-encoded view of `localStorage` (or `sessionStorage` with `{area: 'session'}`).
|
|
3434
|
-
Keys are written as `
|
|
3435
|
-
`clear()` empties only its own namespace; `keys()` reports
|
|
4508
|
+
Keys are written as `zx2:<namespace length>:<namespace>:<key>` (UTF-16 string length), so names
|
|
4509
|
+
containing colons cannot overlap. `clear()` empties only its own namespace; `keys()` reports
|
|
4510
|
+
namespace-relative names. To retain values from the earlier `zx:` format, call
|
|
4511
|
+
`migrateLegacy(['known-key'])` before reading them. It copies only the exact keys you name, only
|
|
4512
|
+
when they contain valid JSON and the current key is absent, and returns the names copied.
|
|
4513
|
+
Legacy values are never deleted. Migration is recorded once per key, including missing keys;
|
|
4514
|
+
removing or clearing a migrated value does not restore it on the next load. Invalid legacy JSON
|
|
4515
|
+
remains retryable. Built-in persisted components migrate their own known keys automatically.
|
|
3436
4516
|
`get(key, fallback)` returns the fallback both for a missing key and for unparseable JSON, and
|
|
3437
4517
|
`set()` drops values JSON cannot represent rather than throwing. When the area is missing or
|
|
3438
4518
|
refuses a write — private browsing, a full quota, cookies disabled — the view degrades silently
|
|
@@ -3453,16 +4533,288 @@ entry point as the components. See also the Kernel section for `Component`, `h`,
|
|
|
3453
4533
|
defaults → the default English catalogue → the key. The translator answers one key at a time;
|
|
3454
4534
|
null, undefined, or the key itself means "not translated" and English shows, so an application
|
|
3455
4535
|
without a translator never sees a raw key. `defaultMessages` is that catalogue — copy it to
|
|
3456
|
-
start a locale (`setTranslator((key) => de[key])`)
|
|
3457
|
-
table of a `msg` option and drives locale-dependent
|
|
3458
|
-
|
|
4536
|
+
start a locale (`setTranslator((key) => de[key])`), or install the German one below.
|
|
4537
|
+
`setLanguage()` also selects the language table of a `msg` option and drives locale-dependent
|
|
4538
|
+
behaviour such as the first day of the week and the month and weekday names `formatDate()` writes.
|
|
4539
|
+
`translatePlural(key, count, args, {locale}?)` and `component.msgPlural(key, count, ...args)`
|
|
4540
|
+
select cardinal forms using `Intl.PluralRules`. Pass the finite numeric count separately from
|
|
4541
|
+
display arguments: `translatePlural('items', 2, ['two'])`. At each message source, resolution
|
|
4542
|
+
tries `items.<category>`, `items.other`, then `items` (including a legacy alias). Instance overrides
|
|
4543
|
+
precede the host translator, inherited component messages, and English defaults. English fallback
|
|
4544
|
+
selects its category using English rules. Existing unsuffixed overrides remain valid.
|
|
4545
|
+
- **Keyboard** — `focusTrap(container)` → `{activate, deactivate}` confines Tab to a container;
|
|
4546
|
+
an empty trap focuses its boundary, temporarily adding `tabindex="-1"` when needed and removing
|
|
4547
|
+
it on deactivation. Deactivation restores the previous focus when it is still connected.
|
|
3459
4548
|
`rovingTabindex(container, itemSelector, {orientation, wrap, rtl: 'auto'})` → `{focusFirst,
|
|
3460
4549
|
focusLast, destroy}` keeps one tab stop in a group — horizontal arrows follow `dir="rtl"`, and a
|
|
3461
4550
|
text field, select, or contenteditable item keeps Home/End and its arrows (an arrow leaves a text
|
|
3462
4551
|
field only from the edge of its text); toggling a `<fieldset disabled>` around items inside the
|
|
3463
|
-
container moves the tab stop off them
|
|
4552
|
+
container moves the tab stop off them. Removed items regain their original tabindex and are
|
|
4553
|
+
released; reinserted items use their new baseline. `typeahead(getItems, onMatch)` →
|
|
3464
4554
|
`(event|string) => void` resolves buffered printable keystrokes to an item (500 ms buffer,
|
|
3465
4555
|
repeated-letter cycling).
|
|
4556
|
+
|
|
4557
|
+
#### Locales
|
|
4558
|
+
|
|
4559
|
+
[Open the Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales).
|
|
4560
|
+
|
|
4561
|
+
Its [live language-switching example](https://zx.zeyos.com/docs.html#getting-started/locales/try-language-switching)
|
|
4562
|
+
offers English, German, and an application-owned French catalogue. Edit the name, record, and
|
|
4563
|
+
count to try positional/named variables, plural forms, and number formatting. Switching preserves
|
|
4564
|
+
the input values and recreates the translated Select. French intentionally omits `table.empty`
|
|
4565
|
+
to demonstrate English fallback. The embedded example has its own language state, and its running
|
|
4566
|
+
source and catalogues are available under Code.
|
|
4567
|
+
|
|
4568
|
+
##### Language, locale, and catalogue
|
|
4569
|
+
|
|
4570
|
+
Zx ships English and German interface messages. Other languages can be supplied by the application.
|
|
4571
|
+
Locale tags such as `en-GB`, `de-AT`, and `fr-CA` describe language and regional conventions; adding a
|
|
4572
|
+
tag to a picker does not install a translation.
|
|
4573
|
+
|
|
4574
|
+
- `setTranslator(fn)` supplies the words. The function receives a flat message key and returns its text.
|
|
4575
|
+
- `setLanguage(tag)` selects the active language for plural rules, default formatting, and language-specific `msg` tables. It does not load a catalogue or change the page's HTML `lang` attribute.
|
|
4576
|
+
- `locale` selects formatting on helpers and components that expose this option. It does not select translated interface messages.
|
|
4577
|
+
- `displayLocale` controls the names shown by Select.locale() and Select.country(), independently of their selected value.
|
|
4578
|
+
- `msg` overrides messages for one component. Application labels, record values, and server text remain application-owned.
|
|
4579
|
+
|
|
4580
|
+
##### Enable a shipped language
|
|
4581
|
+
|
|
4582
|
+
Install the catalogue and language before creating components:
|
|
4583
|
+
|
|
4584
|
+
```js
|
|
4585
|
+
import { setLanguage, setTranslator } from '@zeyos/zx';
|
|
4586
|
+
import { de } from '@zeyos/zx/locales/de.js';
|
|
4587
|
+
|
|
4588
|
+
setTranslator((key) => de[key]);
|
|
4589
|
+
setLanguage('de-AT');
|
|
4590
|
+
document.documentElement.lang = 'de-AT';
|
|
4591
|
+
```
|
|
4592
|
+
|
|
4593
|
+
This uses German messages with Austrian formatting conventions. `setTranslator(null)` restores
|
|
4594
|
+
English message fallback; call `setLanguage('en')` as well to return formatting to English.
|
|
4595
|
+
`en` from `@zeyos/zx/locales/en.js` is the frozen `defaultMessages` object. The optional
|
|
4596
|
+
`@zeyos/zx/locales/index.js` exports `en`, `de`, and the frozen `locales` manifest. Importing that
|
|
4597
|
+
manifest includes both catalogues; the main entry does not load German automatically.
|
|
4598
|
+
|
|
4599
|
+
##### Add a new language
|
|
4600
|
+
|
|
4601
|
+
Create an application-owned module, for example `app/locales/fr.js`, served at `/app/locales/fr.js`.
|
|
4602
|
+
This intentionally partial example translates two Select messages:
|
|
4603
|
+
|
|
4604
|
+
```js
|
|
4605
|
+
export const fr = Object.freeze({
|
|
4606
|
+
'select.none': 'Aucune sélection',
|
|
4607
|
+
'select.empty': 'Aucun résultat'
|
|
4608
|
+
});
|
|
4609
|
+
```
|
|
4610
|
+
|
|
4611
|
+
```js
|
|
4612
|
+
import { setLanguage, setTranslator } from '@zeyos/zx';
|
|
4613
|
+
import { fr } from '/app/locales/fr.js';
|
|
4614
|
+
|
|
4615
|
+
setTranslator((key) => fr[key]);
|
|
4616
|
+
setLanguage('fr-FR');
|
|
4617
|
+
document.documentElement.lang = 'fr-FR';
|
|
4618
|
+
```
|
|
4619
|
+
|
|
4620
|
+
Use `defaultMessages` as the inventory of built-in keys to translate. Keep their placeholders,
|
|
4621
|
+
including each plural form's placeholders, and test the controls and accessible labels that your
|
|
4622
|
+
application uses. A partial catalogue should return `undefined` for untranslated keys so Zx can
|
|
4623
|
+
apply its English fallback with English plural rules. Do not fill a partial non-English catalogue
|
|
4624
|
+
by spreading `defaultMessages` into it. `null` and an echoed key also mean “no translation”; an
|
|
4625
|
+
empty string is an intentional empty translation.
|
|
4626
|
+
|
|
4627
|
+
Application catalogues need no change to Zx or its shipped manifest. Keep a registry of the languages
|
|
4628
|
+
your application actually supports, and pass those tags to Select.locale().
|
|
4629
|
+
|
|
4630
|
+
##### Regional variants and catalogue lookup
|
|
4631
|
+
|
|
4632
|
+
The application chooses how a regional tag maps to a catalogue. Zx does not automatically search
|
|
4633
|
+
`de-AT`, then `de`, inside your translator. Reuse a language catalogue, or create regional overrides:
|
|
4634
|
+
|
|
4635
|
+
```js
|
|
4636
|
+
import { setLanguage, setTranslator } from '@zeyos/zx';
|
|
4637
|
+
import { en, de } from '@zeyos/zx/locales/index.js';
|
|
4638
|
+
|
|
4639
|
+
const deAT = Object.freeze({ ...de, 'table.empty': 'Keine Einträge' });
|
|
4640
|
+
const catalogues = { en, de, 'de-AT': deAT };
|
|
4641
|
+
|
|
4642
|
+
function applyLocale(tag) {
|
|
4643
|
+
const locale = Intl.getCanonicalLocales(tag)[0];
|
|
4644
|
+
const language = new Intl.Locale(locale).language;
|
|
4645
|
+
const catalogue = catalogues[locale] ?? catalogues[language];
|
|
4646
|
+
setTranslator(catalogue ? (key) => catalogue[key] : null);
|
|
4647
|
+
setLanguage(locale);
|
|
4648
|
+
document.documentElement.lang = locale;
|
|
4649
|
+
}
|
|
4650
|
+
|
|
4651
|
+
applyLocale('de-AT');
|
|
4652
|
+
```
|
|
4653
|
+
|
|
4654
|
+
Here `en-GB` reuses English messages, while `de-AT` keeps its regional override. This function expects
|
|
4655
|
+
a valid BCP 47 tag; picker values are already canonical. General locale APIs use hyphenated tags.
|
|
4656
|
+
|
|
4657
|
+
##### Message keys and interpolation variables
|
|
4658
|
+
|
|
4659
|
+
Use flat string keys for your own messages. A dotted key is a name, not a nested object path.
|
|
4660
|
+
Positional placeholders are `%1`, `%2`, and so on; named placeholders use `%name%`:
|
|
4661
|
+
|
|
4662
|
+
```js
|
|
4663
|
+
import { setLanguage, setTranslator, translate } from '@zeyos/zx';
|
|
4664
|
+
import { de } from '@zeyos/zx/locales/de.js';
|
|
4665
|
+
|
|
4666
|
+
const messages = Object.freeze({
|
|
4667
|
+
...de,
|
|
4668
|
+
'app.welcome': 'Willkommen, %1!',
|
|
4669
|
+
'app.assigned': '%person% bearbeitet %record%.'
|
|
4670
|
+
});
|
|
4671
|
+
setTranslator((key) => messages[key]);
|
|
4672
|
+
setLanguage('de');
|
|
4673
|
+
|
|
4674
|
+
translate('app.welcome', ['Ada']);
|
|
4675
|
+
translate('app.assigned', { person: 'Ada', record: 'INV-42' });
|
|
4676
|
+
```
|
|
4677
|
+
|
|
4678
|
+
`component.msg(key, ...args)` takes positional arguments. For a named template, use
|
|
4679
|
+
`translate(key, values)` or `printf(component.msg(key), values)`. Interpolation produces plain text;
|
|
4680
|
+
render it with text nodes or `textContent`.
|
|
4681
|
+
|
|
4682
|
+
For a single component, pass `msg: { 'select.empty': 'Nothing found here' }`. Resolution is instance
|
|
4683
|
+
messages, host translator, inherited component messages, English catalogue, then the key.
|
|
4684
|
+
Language-specific tables such as `msg: { de: { 'select.empty': 'Nichts gefunden' } }` match the exact
|
|
4685
|
+
active language identifier; provide a `de-AT` table or a flat entry when that is the active tag.
|
|
4686
|
+
|
|
4687
|
+
##### Plural forms
|
|
4688
|
+
|
|
4689
|
+
Pass a numeric count separately from its displayed text. The selected cardinal category comes
|
|
4690
|
+
from `Intl.PluralRules`; messages remain flat strings:
|
|
4691
|
+
|
|
4692
|
+
```js
|
|
4693
|
+
import { formatNumber, setLanguage, setTranslator, translatePlural } from '@zeyos/zx';
|
|
4694
|
+
import { de } from '@zeyos/zx/locales/de.js';
|
|
4695
|
+
|
|
4696
|
+
const messages = Object.freeze({
|
|
4697
|
+
...de,
|
|
4698
|
+
'app.results.one': '%1 Ergebnis',
|
|
4699
|
+
'app.results.other': '%1 Ergebnisse'
|
|
4700
|
+
});
|
|
4701
|
+
setTranslator((key) => messages[key]);
|
|
4702
|
+
setLanguage('de');
|
|
4703
|
+
|
|
4704
|
+
const count = 1200;
|
|
4705
|
+
translatePlural('app.results', count, [formatNumber(count)]);
|
|
4706
|
+
```
|
|
4707
|
+
|
|
4708
|
+
Use `component.msgPlural(key, count, ...args)` inside a component. Supply `.other` and the categories
|
|
4709
|
+
your language needs: `.zero`, `.one`, `.two`, `.few`, and `.many` are supported too. At each message
|
|
4710
|
+
source, lookup tries the selected category, `.other`, then the unsuffixed key and any supported legacy
|
|
4711
|
+
alias before moving to the next source. Existing flat overrides therefore keep their precedence.
|
|
4712
|
+
English fallback uses English rules. Custom application keys need their own fallback text; they are
|
|
4713
|
+
not part of the built-in English catalogue. Ordinary `translate()` and `msg()` never infer a count.
|
|
4714
|
+
|
|
4715
|
+
##### Formatting and date-name overrides
|
|
4716
|
+
|
|
4717
|
+
Formatting uses a supported explicit locale, then the active language, then English. Support is
|
|
4718
|
+
checked for the particular Intl service, since a language may support numbers but not plural rules.
|
|
4719
|
+
Regional English tags retain their own conventions.
|
|
4720
|
+
|
|
4721
|
+
```js
|
|
4722
|
+
import { formatCurrency, formatDate, formatNumber } from '@zeyos/zx';
|
|
4723
|
+
|
|
4724
|
+
formatNumber(1234.5, { locale: 'en-GB', decimals: 2 });
|
|
4725
|
+
formatCurrency(1234.5, 'EUR', { locale: 'de-AT' });
|
|
4726
|
+
formatDate(new Date(2026, 8, 1), '%b', { locale: 'en-GB' });
|
|
4727
|
+
```
|
|
4728
|
+
|
|
4729
|
+
Components with a `locale` option can use the same override. For NumberField, locale-aware display
|
|
4730
|
+
and parsing apply with `group: true`; ungrouped fields retain their machine-format input behavior.
|
|
4731
|
+
Currency, time zone, week start, and display patterns are separate settings where the API exposes
|
|
4732
|
+
them; a locale tag alone does not choose them all.
|
|
4733
|
+
|
|
4734
|
+
`formatDate()` normally obtains month and weekday names from Intl. A host translator can override
|
|
4735
|
+
`date.month.0` through `date.month.11` and `date.weekday.0` through `date.weekday.6` (Sunday is zero).
|
|
4736
|
+
Use `date.month.short.0` and `date.weekday.short.0` for their short forms. Missing short names come
|
|
4737
|
+
from Intl, not a shortened translated long name. These overrides apply when no explicit locale is
|
|
4738
|
+
passed; an explicit `formatDate(..., { locale })` takes precedence. `locale: null` remains implicit.
|
|
4739
|
+
|
|
4740
|
+
##### Use the Select-based pickers
|
|
4741
|
+
|
|
4742
|
+
Select.locale() and Select.country() return ordinary Select instances. They keep its popup, keyboard map, events, field
|
|
4743
|
+
adapter, and `.zx-select` styling, adding item generation, names, flags, and value normalization.
|
|
4744
|
+
A locale selection emits `change`; it does not install translations or change the application language.
|
|
4745
|
+
|
|
4746
|
+
Using `applyLocale()` from the regional-lookup example:
|
|
4747
|
+
|
|
4748
|
+
```js
|
|
4749
|
+
import { getLanguage, Select } from '@zeyos/zx';
|
|
4750
|
+
|
|
4751
|
+
const picker = Select.locale(null, {
|
|
4752
|
+
locales: ['en-GB', 'de-DE', 'de-AT'],
|
|
4753
|
+
value: getLanguage(),
|
|
4754
|
+
displayLocale: 'en-GB',
|
|
4755
|
+
flags: 'code',
|
|
4756
|
+
filter: 'local'
|
|
4757
|
+
});
|
|
4758
|
+
picker.on('change', ({ detail }) => {
|
|
4759
|
+
if (detail.value) applyLocale(detail.value);
|
|
4760
|
+
});
|
|
4761
|
+
document.querySelector('#language').append(picker.toElement());
|
|
4762
|
+
```
|
|
4763
|
+
|
|
4764
|
+
`displayLocale` changes the language names shown, while the selected value stays a locale tag.
|
|
4765
|
+
Select.locale() filters automatically for lists longer than seven; `filter: 'local'` also enables
|
|
4766
|
+
search for short lists. For a form, use the existing Select field preset:
|
|
4767
|
+
|
|
4768
|
+
```js
|
|
4769
|
+
import { Field } from '@zeyos/zx';
|
|
4770
|
+
|
|
4771
|
+
const languageField = new Field(null, {
|
|
4772
|
+
type: 'zxselect',
|
|
4773
|
+
name: 'language',
|
|
4774
|
+
label: 'Language',
|
|
4775
|
+
value: 'de-AT',
|
|
4776
|
+
props: { preset: 'locale', locales: ['en-GB', 'de-AT'], flags: 'code' }
|
|
4777
|
+
});
|
|
4778
|
+
```
|
|
4779
|
+
|
|
4780
|
+
Use `props.preset: 'country'` for the country factory. Preset names are Field adapter options;
|
|
4781
|
+
for direct construction call `Select.locale()` or `Select.country()`.
|
|
4782
|
+
|
|
4783
|
+
##### Switching language at runtime
|
|
4784
|
+
|
|
4785
|
+
Set the translator and active language together, then refresh your application UI. Zx does not
|
|
4786
|
+
broadcast a language-change event or automatically relabel every mounted component. Preserve the
|
|
4787
|
+
application's values, destroy affected instances, and recreate them with the new messages; merely
|
|
4788
|
+
changing the picker value does not do this. Use each component's documented update methods where
|
|
4789
|
+
they cover the text being changed, rather than calling its internal `render()` method.
|
|
4790
|
+
|
|
4791
|
+
Set the document or region's HTML `lang` for pronunciation, and set `dir="rtl"` when your application
|
|
4792
|
+
selects a right-to-left language. Zx does not infer text direction from `setLanguage()`. Verify visible
|
|
4793
|
+
labels, accessible names, plural counts, date/number entry, and layout after a switch.
|
|
4794
|
+
|
|
4795
|
+
##### German catalogue glossary
|
|
4796
|
+
|
|
4797
|
+
- **Voice** — a business application. The reader is addressed formally ("Sie"), and preferably not
|
|
4798
|
+
at all ("Änderungen speichern"). Buttons and menu items use the infinitive ("Speichern",
|
|
4799
|
+
"Abbrechen").
|
|
4800
|
+
- **Typography** — quotation marks „…“; the ellipsis character attached to its word ("Wird
|
|
4801
|
+
geladen…"); a non-breaking space between a number and its unit ("Letzte 30 Tage").
|
|
4802
|
+
- **Kept as they are** — Agent, Board, Code, Swimlanes, Tags, Token, Tool, Upload; also Dashboard,
|
|
4803
|
+
Prompt, and Tab where a key needs them. A work-in-progress limit is a WIP-Limit.
|
|
4804
|
+
- **Agents** — approve → genehmigen, approval → Genehmigung, reject → ablehnen, request → Anfrage,
|
|
4805
|
+
run → Ausführung, working time → Laufzeit, step → Schritt, tool call → Tool-Aufruf, retry →
|
|
4806
|
+
Wiederholung, stop → stoppen, conversation → Unterhaltung, source → Quelle, attachment → Anhang.
|
|
4807
|
+
- **Records** — record → Datensatz, field → Feld, row → Zeile, column → Spalte, view → Ansicht,
|
|
4808
|
+
group by → gruppieren nach, no records → Keine Datensätze.
|
|
4809
|
+
- **Dates** — event → Termin, date range and period → Zeitraum, week number → Kalenderwoche.
|
|
4810
|
+
- **Actions** — choose and select → auswählen, clear → zurücksetzen (a selection: aufheben), search
|
|
4811
|
+
→ suchen, or durchsuchen with an object, expand → ausklappen, collapse → einklappen, hide →
|
|
4812
|
+
ausblenden, remove → entfernen, no matches → Keine Treffer, no results → Keine Ergebnisse.
|
|
4813
|
+
- **Parts of the interface** — message → Nachricht in a conversation and Meldung in a notice,
|
|
4814
|
+
launcher → Schnellsuche, workspace → Arbeitsbereich, panel → Bereich, sheet → Seitenbereich,
|
|
4815
|
+
breadcrumb → Pfadnavigation.
|
|
4816
|
+
- **Keys** — arrow keys → Pfeiltasten, Space → Leertaste, Enter → Eingabetaste, Escape → Esc, Ctrl →
|
|
4817
|
+
Strg, Delete → Entf.
|
|
3466
4818
|
<!-- /doc -->
|
|
3467
4819
|
|
|
3468
4820
|
<!-- doc:truncate -->
|
|
@@ -3497,6 +4849,54 @@ Registered elements: `<zx-toggle>`, `<zx-check-button>`, `<zx-select items='[…
|
|
|
3497
4849
|
`<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
|
|
3498
4850
|
`<zx-table>`, `<zx-dialog>`. `<zx-datebox>` takes `display-format` beside `format`, as the
|
|
3499
4851
|
Datebox options `displayFormat` and `format`.
|
|
4852
|
+
|
|
4853
|
+
**Agent kit and data views.** `<zx-agent-thread>`, `<zx-composer>`, `<zx-block-view>`,
|
|
4854
|
+
`<zx-run-trace>`, `<zx-approval-card>`, `<zx-source-list>`, `<zx-run-status>`, `<zx-card-view>`,
|
|
4855
|
+
`<zx-kanban-view>`, `<zx-tree>` (TreeView) and `<zx-chart>` are made for an application written in a
|
|
4856
|
+
framework: it renders the tag, sets properties, calls methods, and listens for events. None of them
|
|
4857
|
+
is form-associated.
|
|
4858
|
+
|
|
4859
|
+
```js
|
|
4860
|
+
thread.authors = authors; // data goes on the property
|
|
4861
|
+
thread.items = items;
|
|
4862
|
+
composer.addEventListener('send', (event) => {
|
|
4863
|
+
thread.upsert({ id, type: 'user', text: event.detail.text });
|
|
4864
|
+
composer.busy = true;
|
|
4865
|
+
});
|
|
4866
|
+
thread.appendText('answer-1', chunk); // forwarded to the component
|
|
4867
|
+
```
|
|
4868
|
+
|
|
4869
|
+
- **Options.** Every component option keeps its name and default. A scalar is an attribute, kebab-cased
|
|
4870
|
+
(`heading-level`, `submit-key`), and its property reflects to it. Two stay on the property: a
|
|
4871
|
+
Composer's `value`, as an input's does, and an ApprovalCard's `title`, which as an attribute
|
|
4872
|
+
would be a tooltip over the whole card. A boolean that defaults to `true` is turned off with
|
|
4873
|
+
`="false"` (`numbered="false"`, `follow-output="false"`).
|
|
4874
|
+
- **Data is a property.** Lists, items, columns and records are properties first. A JSON attribute
|
|
4875
|
+
is read for static markup, but a value set on the property is never written to an attribute, so
|
|
4876
|
+
a long thread does not pass through `JSON.stringify`. Functions, nodes and the chart `adapter`
|
|
4877
|
+
have no attribute at all: `chart.adapter = new ChartJsAdapter(ChartJs)`, `tree.load = fetchChildren`.
|
|
4878
|
+
A property set before `defineElements()` ran is taken over at upgrade.
|
|
4879
|
+
- **Methods are forwarded.** Call them on the element: `thread.upsert(item)`, `composer.setBusy(true)`,
|
|
4880
|
+
`tree.expandAll()`, not `element.component`. The streaming and update methods of every component
|
|
4881
|
+
are forwarded, and on AgentThread also `get`, `getItems` and `getComponent`. A call made before
|
|
4882
|
+
the component exists is queued and runs, in order, once it does; a queued call returns
|
|
4883
|
+
`undefined`. Once running, a call returns the component's answer, with the component replaced by
|
|
4884
|
+
the element so a chain stays on it.
|
|
4885
|
+
- **Two names shared with the DOM.** `thread.remove(id)` removes an item and `thread.remove()` the
|
|
4886
|
+
element. `blockView.append(block)` adds a block and `blockView.append(node)` a child node.
|
|
4887
|
+
- **Events.** Each event the component documents is dispatched on the host under its plain name,
|
|
4888
|
+
so `addEventListener('send', …)` and a framework's `onsend` both work. It does not bubble, and
|
|
4889
|
+
`zx-send` does; use that one to delegate. Cancelling either cancels the component's event. A
|
|
4890
|
+
DOM event of a declared name stops at the component's root, so `input` on `<zx-composer>` is the
|
|
4891
|
+
component's, with `detail.text`, once per change. Setting a property emits nothing; a forwarded
|
|
4892
|
+
method emits what the component's method emits.
|
|
4893
|
+
- **Lifecycle.** Removing the element destroys its component, and re-inserting it rebuilds one from
|
|
4894
|
+
the current properties, including what forwarded methods changed: a streamed answer, a board's
|
|
4895
|
+
moved records, a tree's selection. Unsent attachments, a tree's open branches and a stopped
|
|
4896
|
+
answer's note live only in the component and do not come back. An option the component cannot
|
|
4897
|
+
change in place rebuilds it the same way.
|
|
4898
|
+
- **Display.** A host is `display: inline` until the page says otherwise. Give it `display: block`
|
|
4899
|
+
when it must fill a height, as a scrolling thread does.
|
|
3500
4900
|
<!-- /doc -->
|
|
3501
4901
|
|
|
3502
4902
|
<!-- doc:tokens -->
|