@zeyos/zx 5.7.0 → 5.8.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 +330 -0
- package/README.md +47 -9
- package/dist/types/components/activity-item/activity-item.d.ts +14 -3
- package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
- package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
- package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
- package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
- package/dist/types/components/approval-card/approval-card.d.ts +31 -2
- package/dist/types/components/aurora/aurora.d.ts +31 -5
- package/dist/types/components/calendar/calendar.d.ts +39 -26
- package/dist/types/components/chart/chart.d.ts +250 -20
- package/dist/types/components/chart/color.d.ts +66 -0
- package/dist/types/components/chart/svg-adapter.d.ts +103 -0
- package/dist/types/components/chart/svg-geometry.d.ts +203 -0
- package/dist/types/components/check-button/check-button.d.ts +1 -4
- package/dist/types/components/checklist/checklist.d.ts +48 -5
- package/dist/types/components/code-editor/code-editor.d.ts +55 -1
- package/dist/types/components/composer/composer.d.ts +41 -6
- package/dist/types/components/context-menu/context-menu.d.ts +36 -8
- package/dist/types/components/copy/copy-button.d.ts +6 -0
- package/dist/types/components/copy/copy-input.d.ts +1 -0
- package/dist/types/components/date-picker/date-picker.d.ts +14 -0
- package/dist/types/components/date-picker/time-picker.d.ts +26 -17
- package/dist/types/components/datebox/datebox.d.ts +8 -4
- package/dist/types/components/dialog/dialog.d.ts +15 -4
- package/dist/types/components/empty-state/empty-state.d.ts +10 -1
- package/dist/types/components/field/field.d.ts +4 -2
- package/dist/types/components/form/form.d.ts +2 -1
- package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
- package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
- package/dist/types/components/launcher/launcher.d.ts +26 -0
- package/dist/types/components/master-panel/master-panel.d.ts +9 -4
- package/dist/types/components/menu-button/menu-button.d.ts +29 -5
- package/dist/types/components/message/message.d.ts +308 -5
- package/dist/types/components/modal/modal.d.ts +45 -8
- package/dist/types/components/modal/native-dialog.d.ts +40 -0
- package/dist/types/components/module-bar/module-bar.d.ts +9 -2
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
- package/dist/types/components/number-field/number-field.d.ts +31 -1
- package/dist/types/components/pagination/pagination.d.ts +341 -19
- package/dist/types/components/run-status/run-status.d.ts +26 -0
- package/dist/types/components/run-trace/run-trace.d.ts +10 -6
- package/dist/types/components/search/search.d.ts +16 -4
- package/dist/types/components/select/select.d.ts +19 -1
- package/dist/types/components/sheet/sheet.d.ts +20 -6
- package/dist/types/components/slider/slider.d.ts +2 -1
- package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
- package/dist/types/components/stepper/stepper.d.ts +17 -4
- package/dist/types/components/surface/catalog.d.ts +61 -17
- package/dist/types/components/surface/surface.d.ts +6 -4
- package/dist/types/components/table/table.d.ts +207 -5
- package/dist/types/components/table/window.d.ts +25 -1
- package/dist/types/components/toggle/toggle.d.ts +38 -6
- package/dist/types/components/tooltip/tooltip.d.ts +5 -4
- package/dist/types/components/tree/tree.d.ts +43 -6
- package/dist/types/components/truncate/truncate.d.ts +4 -2
- package/dist/types/components/value-list/value-list.d.ts +9 -2
- package/dist/types/core/date.d.ts +2 -1
- package/dist/types/core/dom.d.ts +14 -0
- package/dist/types/core/drag-axis.d.ts +10 -5
- package/dist/types/core/export.d.ts +2 -2
- package/dist/types/core/format.d.ts +3 -1
- package/dist/types/core/icons.d.ts +36 -3
- package/dist/types/core/keyboard.d.ts +7 -3
- package/dist/types/core/messages.d.ts +3 -0
- package/dist/types/core/storage.d.ts +4 -3
- package/dist/types/core/util.d.ts +3 -1
- package/dist/types/elements/define.d.ts +5 -2
- package/dist/types/index.d.ts +6 -4
- package/dist/types/internal/agent-model.d.ts +99 -0
- package/dist/types/internal/app-rail.d.ts +37 -2
- package/dist/types/internal/collections.d.ts +18 -0
- package/dist/types/internal/menu-items.d.ts +27 -0
- package/dist/types/internal/overlay-content.d.ts +23 -0
- package/dist/types/internal/presence-loop.d.ts +5 -2
- package/dist/types/locales/index.d.ts +3 -0
- package/dist/types/zeyos/calendar.d.ts +43 -7
- package/dist/types/zeyos/connect.d.ts +4 -0
- package/dist/types/zeyos/form.d.ts +13 -5
- package/dist/types/zeyos/select.d.ts +5 -2
- package/dist/types/zeyos/table.d.ts +16 -8
- package/dist/types/zeyos/view.d.ts +2 -1
- package/dist/zx-zeyos.esm.js +3161 -515
- package/dist/zx-zeyos.esm.min.js +4 -4
- package/dist/zx.core.css +4 -0
- package/dist/zx.core.min.css +1 -1
- package/dist/zx.css +970 -57
- package/dist/zx.esm.js +6405 -2249
- package/dist/zx.esm.min.js +26 -26
- package/dist/zx.global.js +6405 -2249
- package/dist/zx.global.min.js +26 -26
- package/dist/zx.layered.css +972 -57
- package/dist/zx.layered.min.css +1 -1
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +159 -1
- package/docs/agent-surfaces.md +21 -21
- package/docs/api.json +3154 -518
- package/docs/components/account-menu.md +24 -0
- package/docs/components/activity-item.md +23 -0
- package/docs/components/activity-list.md +28 -0
- package/docs/components/agent-avatar.md +59 -0
- package/docs/components/agent-thread.md +275 -0
- package/docs/components/app-icon.md +36 -0
- package/docs/components/app-sidebar.md +92 -0
- package/docs/components/approval-card.md +71 -0
- package/docs/components/aurora.md +34 -0
- package/docs/components/avatar.md +37 -0
- package/docs/components/badge.md +36 -0
- package/docs/components/block-view.md +34 -0
- package/docs/components/breadcrumb.md +20 -0
- package/docs/components/button.md +23 -0
- package/docs/components/calendar.md +68 -0
- package/docs/components/card-view.md +73 -0
- package/docs/components/card.md +25 -0
- package/docs/components/chart.md +109 -0
- package/docs/components/check-button.md +16 -0
- package/docs/components/checklist.md +19 -0
- package/docs/components/code-editor.md +38 -0
- package/docs/components/composer.md +107 -0
- package/docs/components/context-menu.md +32 -0
- package/docs/components/copy.md +37 -0
- package/docs/components/data-filter.md +16 -0
- package/docs/components/date-picker.md +31 -0
- package/docs/components/date-range.md +21 -0
- package/docs/components/datebox.md +31 -0
- package/docs/components/dialog.md +25 -0
- package/docs/components/dock.md +57 -0
- package/docs/components/dropdown.md +39 -0
- package/docs/components/elements.md +63 -0
- package/docs/components/empty-state.md +17 -0
- package/docs/components/entity-ref.md +26 -0
- package/docs/components/field-upload.md +18 -0
- package/docs/components/file-item.md +27 -0
- package/docs/components/file-list.md +23 -0
- package/docs/components/filter-panel.md +45 -0
- package/docs/components/filter.md +47 -0
- package/docs/components/finder.md +25 -0
- package/docs/components/form-widgets.md +42 -0
- package/docs/components/form.md +80 -0
- package/docs/components/grid.md +26 -0
- package/docs/components/groupbox.md +11 -0
- package/docs/components/helpers.md +359 -0
- package/docs/components/icons.md +87 -0
- package/docs/components/index.md +99 -0
- package/docs/components/kanban-view.md +42 -0
- package/docs/components/kbd.md +23 -0
- package/docs/components/kernel.md +41 -0
- package/docs/components/launcher.md +66 -0
- package/docs/components/layout.md +33 -0
- package/docs/components/list-toolbar.md +38 -0
- package/docs/components/loading.md +48 -0
- package/docs/components/menu-button.md +47 -0
- package/docs/components/message.md +76 -0
- package/docs/components/modal.md +27 -0
- package/docs/components/module-bar.md +71 -0
- package/docs/components/multi-value-editor.md +16 -0
- package/docs/components/navigation-bar.md +22 -0
- package/docs/components/number-field.md +34 -0
- package/docs/components/pagination.md +73 -0
- package/docs/components/panel.md +28 -0
- package/docs/components/prompt-starters.md +40 -0
- package/docs/components/prose.md +38 -0
- package/docs/components/questionnaire.md +115 -0
- package/docs/components/rating.md +19 -0
- package/docs/components/run-status.md +50 -0
- package/docs/components/run-trace.md +72 -0
- package/docs/components/search.md +11 -0
- package/docs/components/select.md +129 -0
- package/docs/components/sheet-stack.md +39 -0
- package/docs/components/sheet.md +77 -0
- package/docs/components/skeleton.md +27 -0
- package/docs/components/slider.md +29 -0
- package/docs/components/sort-control.md +21 -0
- package/docs/components/source-list.md +30 -0
- package/docs/components/split-view.md +12 -0
- package/docs/components/stat-tile.md +49 -0
- package/docs/components/stepper.md +27 -0
- package/docs/components/surface.md +152 -0
- package/docs/components/tabbox.md +33 -0
- package/docs/components/table-view.md +43 -0
- package/docs/components/table.md +232 -0
- package/docs/components/tag-picker.md +39 -0
- package/docs/components/timebox.md +16 -0
- package/docs/components/toggle.md +21 -0
- package/docs/components/tokens.md +82 -0
- package/docs/components/toolbar.md +26 -0
- package/docs/components/tooltip.md +16 -0
- package/docs/components/tree.md +48 -0
- package/docs/components/truncate.md +21 -0
- package/docs/components/value-list.md +14 -0
- package/docs/components/view-settings.md +56 -0
- package/docs/components/workspace-switcher.md +42 -0
- package/docs/components/zeyos.md +196 -0
- package/docs/llms-small.txt +299 -0
- package/docs/llms.md +725 -109
- package/docs/llms.txt +46 -19
- package/package.json +9 -4
- package/src/components/activity-item/activity-item.js +21 -2
- package/src/components/agent-avatar/agent-avatar.css +195 -0
- package/src/components/agent-avatar/agent-avatar.js +333 -0
- package/src/components/agent-avatar/agent-face.js +292 -0
- package/src/components/agent-thread/ag-ui.js +44 -11
- package/src/components/agent-thread/agent-thread.js +103 -11
- package/src/components/agent-thread/ui-message-stream.js +3 -1
- package/src/components/app-rail/app-rail.css +5 -0
- package/src/components/app-sidebar/app-sidebar.css +3 -0
- package/src/components/app-sidebar/app-sidebar.js +4 -3
- package/src/components/approval-card/approval-card.css +6 -0
- package/src/components/approval-card/approval-card.js +55 -7
- package/src/components/aurora/aurora.css +149 -14
- package/src/components/aurora/aurora.js +49 -6
- package/src/components/button/button.css +24 -11
- package/src/components/calendar/calendar.css +6 -2
- package/src/components/calendar/calendar.js +127 -47
- package/src/components/card-view/card-view.js +5 -6
- package/src/components/chart/chart.css +159 -1
- package/src/components/chart/chart.js +450 -62
- package/src/components/chart/color.js +297 -0
- package/src/components/chart/svg-adapter.js +576 -0
- package/src/components/chart/svg-geometry.js +323 -0
- package/src/components/check-button/check-button.js +3 -18
- package/src/components/checklist/checklist.css +9 -1
- package/src/components/checklist/checklist.js +105 -20
- package/src/components/checklist/field-adapter.js +6 -12
- package/src/components/code-editor/code-editor.css +33 -0
- package/src/components/code-editor/code-editor.js +97 -8
- package/src/components/code-editor/field-adapter.js +3 -0
- package/src/components/composer/composer.css +3 -0
- package/src/components/composer/composer.js +100 -22
- package/src/components/context-menu/context-menu.js +41 -5
- package/src/components/copy/copy-button.js +9 -1
- package/src/components/copy/copy-input.js +5 -0
- package/src/components/data-filter/filter-core.js +0 -1
- package/src/components/date-picker/date-picker.css +8 -0
- package/src/components/date-picker/date-picker.js +47 -8
- package/src/components/date-picker/date-range-picker.js +1 -1
- package/src/components/date-picker/month-picker.js +19 -3
- package/src/components/date-picker/time-picker.js +54 -19
- package/src/components/datebox/date-range-box.js +7 -3
- package/src/components/datebox/datebox.js +32 -6
- package/src/components/dialog/dialog.css +6 -0
- package/src/components/dialog/dialog.js +24 -33
- package/src/components/dropdown/dropdown.js +1 -18
- package/src/components/empty-state/empty-state.js +21 -2
- package/src/components/field/field.js +19 -3
- package/src/components/fieldset/fieldset.js +3 -1
- package/src/components/filter/filter.js +9 -0
- package/src/components/form/form.js +19 -2
- package/src/components/kanban-view/kanban-card.js +15 -2
- package/src/components/kanban-view/kanban-view.css +21 -0
- package/src/components/kanban-view/kanban-view.js +29 -16
- package/src/components/launcher/launcher.css +14 -0
- package/src/components/launcher/launcher.js +54 -9
- package/src/components/master-panel/master-panel.js +24 -22
- package/src/components/menu-button/menu-button.js +26 -4
- package/src/components/message/message.css +228 -29
- package/src/components/message/message.js +664 -30
- package/src/components/modal/modal.js +129 -30
- package/src/components/modal/native-dialog.js +91 -0
- package/src/components/module-bar/module-bar.css +3 -0
- package/src/components/module-bar/module-bar.js +17 -4
- package/src/components/multi-value-editor/multi-value-editor.css +7 -2
- package/src/components/multi-value-editor/multi-value-editor.js +3 -2
- package/src/components/navigation-bar/navigation-bar.js +13 -1
- package/src/components/number-field/field-adapter.js +3 -0
- package/src/components/number-field/number-field.js +70 -16
- package/src/components/pagination/pagination.css +26 -2
- package/src/components/pagination/pagination.js +551 -65
- package/src/components/prose/prose.js +7 -1
- package/src/components/rating/field-adapter.js +3 -0
- package/src/components/run-status/run-status.js +43 -3
- package/src/components/run-trace/run-trace.js +15 -7
- package/src/components/search/search.js +3 -18
- package/src/components/select/field-adapter.js +8 -1
- package/src/components/select/select.js +68 -13
- package/src/components/sheet/sheet.js +39 -13
- package/src/components/slider/field-adapter.js +3 -0
- package/src/components/slider/slider.js +4 -6
- package/src/components/stat-tile/stat-tile.js +24 -9
- package/src/components/stepper/stepper.css +15 -0
- package/src/components/stepper/stepper.js +34 -2
- package/src/components/surface/catalog.js +185 -28
- package/src/components/surface/surface.js +10 -5
- package/src/components/tabbox/tabbox.js +13 -1
- package/src/components/table/table.css +160 -2
- package/src/components/table/table.js +479 -52
- package/src/components/table/window.js +46 -4
- package/src/components/table-view/table-view.js +1 -10
- package/src/components/tag-picker/field-adapter.js +3 -0
- package/src/components/tag-picker/tag-picker.js +2 -0
- package/src/components/timebox/field-adapter.js +3 -0
- package/src/components/toggle/toggle.js +51 -27
- package/src/components/tooltip/tooltip.js +21 -14
- package/src/components/tree/tree.js +87 -14
- package/src/components/truncate/truncate.js +21 -5
- package/src/components/value-list/value-list.js +37 -9
- package/src/components/view-settings/view-settings.js +1 -5
- package/src/core/component.js +34 -2
- package/src/core/date.js +5 -4
- package/src/core/dom.js +45 -2
- package/src/core/drag-axis.js +24 -7
- package/src/core/export.js +4 -4
- package/src/core/fontawesome.js +34 -3
- package/src/core/format.js +3 -1
- package/src/core/http.js +23 -11
- package/src/core/icons.js +60 -8
- package/src/core/keyboard.js +83 -9
- package/src/core/messages.js +3 -0
- package/src/core/position.js +4 -3
- package/src/core/storage.js +80 -31
- package/src/core/util.js +16 -5
- package/src/elements/define.js +82 -47
- package/src/elements/kit.js +46 -35
- package/src/index.js +8 -4
- package/src/internal/agent-model.js +152 -0
- package/src/internal/app-rail.js +53 -2
- package/src/internal/collections.js +25 -0
- package/src/internal/menu-items.js +59 -0
- package/src/internal/overlay-content.js +35 -0
- package/src/internal/presence-loop.js +61 -14
- package/src/locales/de.js +3 -0
- package/src/zeyos/calendar.js +81 -19
- package/src/zeyos/connect.js +5 -1
- package/src/zeyos/form.js +29 -10
- package/src/zeyos/select.js +36 -12
- package/src/zeyos/table.js +43 -11
- package/src/zeyos/view.js +2 -1
- package/styles/tokens/semantic.css +7 -1
- package/styles/zx.css +1 -0
package/docs/llms.md
CHANGED
|
@@ -8,14 +8,18 @@
|
|
|
8
8
|
> its component, and lists the theme settings to decide. Each
|
|
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
|
+
> A smaller first read is `docs/llms-small.txt` (under 8k tokens), and each section is also its own
|
|
12
|
+
> file, `docs/components/<name>.md`.
|
|
11
13
|
|
|
12
14
|
## Optional integration requirements
|
|
13
15
|
|
|
14
16
|
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`
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
Optional integrations still need application-provided assets or clients. `Chart` draws through an
|
|
18
|
+
adapter: the built-in `SvgChartAdapter` draws bar, line, pie and doughnut charts as SVG with nothing
|
|
19
|
+
else loaded, and `Surface` draws its `chart` nodes with it by default; `ChartJsAdapter` draws any
|
|
20
|
+
Chart.js 4 type with a Chart.js the host supplies. Chart.js 4.5.1 is pinned as a development
|
|
21
|
+
dependency and copied to the documentation site's self-hosted vendor assets during its build; it is
|
|
22
|
+
not bundled into Zx.
|
|
19
23
|
Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
|
|
20
24
|
ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
|
|
21
25
|
ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
|
|
@@ -34,7 +38,10 @@ const t = new Table(target, options);
|
|
|
34
38
|
**owns** its root element; retrieve it with `t.toElement()` (or `t.el`) and insert it. A non-null
|
|
35
39
|
target is *enhanced in place* and restored on `destroy()`.
|
|
36
40
|
- **Options** — a plain object; each component declares `static defaults`. Never mutate the passed
|
|
37
|
-
object.
|
|
41
|
+
object. An option passed as `undefined` is an option not passed: it keeps the declared default,
|
|
42
|
+
at the top level and inside `msg`, so a wrapper can forward `{ label: props.label }` without
|
|
43
|
+
filtering unset props. `null` is a value and overrides the default. The merged options are
|
|
44
|
+
frozen; change a live component through its methods (see "Using Zx from a framework").
|
|
38
45
|
- **Value/data** — set via constructor options and mutated via methods (`set`, `setData`, …);
|
|
39
46
|
read via getters/methods (`.value`, `getValues()`, …).
|
|
40
47
|
|
|
@@ -55,8 +62,18 @@ const t = new Table(target, options);
|
|
|
55
62
|
|
|
56
63
|
- ESM: `import { … } from '/assets/zx.esm.js'` (or `../src/index.js` in-repo, no build).
|
|
57
64
|
- Granular: `import { Slider } from '@zeyos/zx/src/components/slider/slider.js'` — one component
|
|
58
|
-
rather than the whole library, for consumers running a bundler.
|
|
59
|
-
|
|
65
|
+
rather than the whole library, for consumers running a bundler. Measured with esbuild 0.28.1
|
|
66
|
+
(`--bundle --minify --format=esm --target=es2022`): `Slider` and `Toggle` from their own files
|
|
67
|
+
bundle to about 49 kB (14 kB gzip), against about 276 kB (76 kB gzip) imported from the package
|
|
68
|
+
entry; `button()` alone is 15 kB against 279 kB. The package entry is one module that registers
|
|
69
|
+
the Field adapters, so a bundler keeps what those registrations reach and drops the rest; the
|
|
70
|
+
whole library is about 1.3 MB minified. Import `dist/zx.esm.js` (what `@zeyos/zx` resolves to),
|
|
71
|
+
not `dist/zx.esm.min.js`: a bundler given the minified file keeps most of it (about 0.9 MB for
|
|
72
|
+
one `button()`). The core modules
|
|
73
|
+
are importable the same way — `setTranslator` from `@zeyos/zx/src/core/i18n.js`, `registerIcons`
|
|
74
|
+
and `icon` from `@zeyos/zx/src/core/icons.js` — and they are the module instances the
|
|
75
|
+
per-component files import, so a translator or a glyph registered there reaches every component
|
|
76
|
+
imported granularly. `zx-css` does the same for the stylesheet.
|
|
60
77
|
- Global: `<script src="/assets/zx.global.js">` → `window.zx.*`.
|
|
61
78
|
- Styles: load `/assets/zx.css` once, or one of the stylesheets below.
|
|
62
79
|
- Build bundles with `npm run build` (esbuild). No build is needed to develop against `src/`.
|
|
@@ -91,8 +108,9 @@ source of any module it imports, because a component may draw another's markup w
|
|
|
91
108
|
A name is the file name of a stylesheet under `src/components/`: `select`, `progress-bar`,
|
|
92
109
|
`button` for `button()`, `layout` for `stack()` and `grid()`. An unknown name fails and lists the
|
|
93
110
|
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
|
|
95
|
-
part of a subset: a page that prints loads
|
|
111
|
+
`form select`, because a field type is registered at run time, not imported — "Field widget types"
|
|
112
|
+
lists the name for every type. The print rules are not part of a subset: a page that prints loads
|
|
113
|
+
`@zeyos/zx/styles/print.css` after it.
|
|
96
114
|
|
|
97
115
|
**The layered build** puts the whole library in `@layer zx`, and an unlayered rule beats any layered
|
|
98
116
|
one whatever its specificity, so `button { padding: 0 }` overrides `.zx-btn[data-size="sm"]` with no
|
|
@@ -172,6 +190,7 @@ Patterns — single screens that recur in every application:
|
|
|
172
190
|
| `inbox` | Inbox | three panes: folders, conversations, the open thread with a reply |
|
|
173
191
|
| `record-page` | Record page | one record: summary header, tabs for lines, files and history, editable details |
|
|
174
192
|
| `agent-chat` | Agent chat | one agent run: plan, tool calls, an approval that holds it, a streamed answer with sources |
|
|
193
|
+
| `agent-canvas` | Agent canvas | every answer a `surface/1` document — figures and a chart, a review, forms, a questionnaire — with its JSON, versions and reply in a panel |
|
|
175
194
|
| `record-wizard` | Record wizard | creation in validated vertical steps with a running total and a review |
|
|
176
195
|
| `checkout-wizard` | Checkout wizard | a focused horizontal flow beside a live summary |
|
|
177
196
|
| `settings-workspace` | Settings workspace | personal settings in sections, saved together |
|
|
@@ -201,7 +220,7 @@ a second navigation.
|
|
|
201
220
|
| A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
|
|
202
221
|
| Events over time | `Calendar` (agenda, day, week, month, year) | — |
|
|
203
222
|
| One number with context | `StatTile` (delta, sparkline, loading; plain and one leading for a record's figures) | a card with a big figure |
|
|
204
|
-
| A chart | `Chart` with `ChartJsAdapter` (Chart.js injected, never bundled) |
|
|
223
|
+
| A chart | `Chart` with `SvgChartAdapter` (bar, line, pie, doughnut; no dependency), or `ChartJsAdapter` for other types (Chart.js injected, never bundled) | a hand-drawn SVG |
|
|
205
224
|
| A linked record inline | `EntityRef` | a link |
|
|
206
225
|
| Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
|
|
207
226
|
| History, comments, a feed | `ActivityItem` / `ActivityList` | — |
|
|
@@ -675,6 +694,191 @@ new ModuleBar(header, buildZeyosModuleBarConfig(state, { orientation: 'horizonta
|
|
|
675
694
|
the bar directly.
|
|
676
695
|
<!-- /doc -->
|
|
677
696
|
|
|
697
|
+
## Using Zx from a framework
|
|
698
|
+
|
|
699
|
+
The class API is imperative: `new Component(target, options)` builds DOM, methods change it, and
|
|
700
|
+
`destroy()` takes it away. A framework component wraps that in its mount and unmount hooks. The
|
|
701
|
+
`<zx-*>` elements (next section) are the alternative where a framework should render a tag and
|
|
702
|
+
set properties instead.
|
|
703
|
+
|
|
704
|
+
**Mount and unmount.** Create the component when the host element exists and destroy it when the
|
|
705
|
+
host goes away. Nothing else is needed for cleanup: `destroy()` aborts every listener, removes a
|
|
706
|
+
root the component created, and restores a target it enhanced.
|
|
707
|
+
|
|
708
|
+
```jsx
|
|
709
|
+
// React
|
|
710
|
+
import { useEffect, useRef } from 'react';
|
|
711
|
+
import { Toggle } from '@zeyos/zx';
|
|
712
|
+
|
|
713
|
+
export function ZxToggle({ checked, label, onChange }) {
|
|
714
|
+
const host = useRef(null);
|
|
715
|
+
const toggle = useRef(null);
|
|
716
|
+
const handler = useRef(onChange);
|
|
717
|
+
handler.current = onChange;
|
|
718
|
+
|
|
719
|
+
useEffect(() => {
|
|
720
|
+
const instance = new Toggle(null, { checked, label });
|
|
721
|
+
instance.on('change', (event) => handler.current?.(event.detail.checked));
|
|
722
|
+
host.current.append(instance.toElement());
|
|
723
|
+
toggle.current = instance;
|
|
724
|
+
return () => { instance.destroy(); toggle.current = null; };
|
|
725
|
+
}, []);
|
|
726
|
+
|
|
727
|
+
// Props that arrive later go through setters.
|
|
728
|
+
// `silent` keeps the write from coming back as a `change` event.
|
|
729
|
+
useEffect(() => {
|
|
730
|
+
toggle.current?.set(Boolean(checked), { silent: true });
|
|
731
|
+
}, [checked]);
|
|
732
|
+
useEffect(() => {
|
|
733
|
+
toggle.current?.setLabel(label ?? null);
|
|
734
|
+
}, [label]);
|
|
735
|
+
|
|
736
|
+
return <span ref={host} />;
|
|
737
|
+
}
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
```vue
|
|
741
|
+
<!-- Vue -->
|
|
742
|
+
<script setup>
|
|
743
|
+
import { onBeforeUnmount, onMounted, ref, watch } from 'vue';
|
|
744
|
+
import { Toggle } from '@zeyos/zx';
|
|
745
|
+
|
|
746
|
+
const props = defineProps({ modelValue: Boolean, label: String });
|
|
747
|
+
const emit = defineEmits(['update:modelValue']);
|
|
748
|
+
const host = ref(null);
|
|
749
|
+
let toggle = null;
|
|
750
|
+
|
|
751
|
+
onMounted(() => {
|
|
752
|
+
toggle = new Toggle(null, { checked: props.modelValue, label: props.label });
|
|
753
|
+
toggle.on('change', (event) => emit('update:modelValue', event.detail.checked));
|
|
754
|
+
host.value.append(toggle.toElement());
|
|
755
|
+
});
|
|
756
|
+
watch(() => props.modelValue, (value) => toggle?.set(Boolean(value), { silent: true }));
|
|
757
|
+
watch(() => props.label, (value) => toggle?.setLabel(value ?? null));
|
|
758
|
+
onBeforeUnmount(() => { toggle?.destroy(); toggle = null; });
|
|
759
|
+
</script>
|
|
760
|
+
|
|
761
|
+
<template><span ref="host" /></template>
|
|
762
|
+
```
|
|
763
|
+
|
|
764
|
+
- **Target `null`, then append.** The component owns its root and `destroy()` removes it, so the
|
|
765
|
+
framework's own element is left exactly as it rendered it. Passing the framework's element as the
|
|
766
|
+
target enhances it in place — Zx then writes classes, attributes and children the framework did
|
|
767
|
+
not render, and puts them back on `destroy()`. A Groupbox given anything but a `<details>`
|
|
768
|
+
replaces that element in the document with one until it is destroyed, so give it `null`.
|
|
769
|
+
- **Unset props.** `{ label: props.label }` with the prop unset passes `undefined`, which keeps
|
|
770
|
+
the default. Pass `null` to mean "none".
|
|
771
|
+
- **Events.** Subscribe with `on()` or an `on<type>` option; both end with `destroy()`. Read the
|
|
772
|
+
current callback from a ref, as above, instead of re-creating the component when a callback's
|
|
773
|
+
identity changes.
|
|
774
|
+
|
|
775
|
+
**The effect runs twice in development.** React's StrictMode mounts, unmounts, and mounts again;
|
|
776
|
+
a component created in the first mount and not destroyed in its cleanup is a second set of DOM and
|
|
777
|
+
listeners beside the first. Returning `destroy()` from the effect is the whole fix, and it is safe
|
|
778
|
+
to call more than once. Where a component enhances an existing element and the code cannot be sure
|
|
779
|
+
the previous one is gone, `Component.from(element)` returns the component registered on a root
|
|
780
|
+
element, or null: `Component.from(element)?.destroy()` before constructing. Floating toasts
|
|
781
|
+
outlive the code that showed them; a view that unmounts its themed shell while toasts are on
|
|
782
|
+
screen calls `Message.disposeRegion(shell)` in the same cleanup.
|
|
783
|
+
|
|
784
|
+
**Framework content inside a component.** Options such as a Dialog's, Sheet's, Modal's, Panel's or
|
|
785
|
+
Card's `content`, and a Panel's or Card's `footer`, take a DOM node. Create an element, hand it to
|
|
786
|
+
the component, and let the framework render into it through a portal, so the content stays part
|
|
787
|
+
of the framework's tree (context, events, updates) while Zx decides where it sits:
|
|
788
|
+
|
|
789
|
+
```jsx
|
|
790
|
+
// React
|
|
791
|
+
import { useEffect, useRef, useState } from 'react';
|
|
792
|
+
import { createPortal } from 'react-dom';
|
|
793
|
+
import { Dialog } from '@zeyos/zx';
|
|
794
|
+
|
|
795
|
+
export function ZxDialog({ open, title, onClose, children }) {
|
|
796
|
+
const [body] = useState(() => document.createElement('div'));
|
|
797
|
+
const [dialog, setDialog] = useState(null);
|
|
798
|
+
const closed = useRef(onClose);
|
|
799
|
+
closed.current = onClose;
|
|
800
|
+
|
|
801
|
+
useEffect(() => {
|
|
802
|
+
const instance = new Dialog(null, { title, content: body });
|
|
803
|
+
instance.on('close', () => closed.current?.());
|
|
804
|
+
setDialog(instance);
|
|
805
|
+
return () => instance.destroy();
|
|
806
|
+
}, []);
|
|
807
|
+
|
|
808
|
+
useEffect(() => { dialog?.setTitle(title ?? ''); }, [dialog, title]);
|
|
809
|
+
useEffect(() => {
|
|
810
|
+
if (!dialog || dialog.isOpen() === Boolean(open)) return;
|
|
811
|
+
if (open) dialog.open(); else dialog.close();
|
|
812
|
+
}, [dialog, open]);
|
|
813
|
+
|
|
814
|
+
return createPortal(children, body);
|
|
815
|
+
}
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
In Vue the same element is the target of `<Teleport :to="body">`. Do not let the framework render
|
|
819
|
+
into an element the component fills itself (a table body, a select's list): the next render of
|
|
820
|
+
either side removes the other's nodes. Cell and item renderers (`render`, `renderCard`, …) return
|
|
821
|
+
nodes; build those with the framework only if it can render into a detached element you create.
|
|
822
|
+
|
|
823
|
+
**Controlled wrappers.** A wrapper that owns the value writes it down with a setter and hears it
|
|
824
|
+
back through an event, and the two must not chase each other:
|
|
825
|
+
|
|
826
|
+
- Write with `{ silent: true }` where the setter takes it — `set(value, { silent })` on Toggle,
|
|
827
|
+
CheckButton, Select and the other value controls, `Table#setSort(id, dir, { silent })`,
|
|
828
|
+
`Table#setExpanded(ids, { silent })` — so the write raises no event. Check the method's
|
|
829
|
+
signature: not every setter emits, and not every one that does takes `silent`.
|
|
830
|
+
- Compare before writing an open state: `if (dialog.isOpen() !== open)`. `open()` and `close()`
|
|
831
|
+
emit, and `close` after a programmatic `close()` would otherwise be reported back as the user's.
|
|
832
|
+
- Which options have a setter is stated per option: the documentation's Options tables carry a
|
|
833
|
+
**Change** column, generated into `docs/api.json` as `update: { methods: ['setTitle()'] }` or
|
|
834
|
+
`update: { rebuild: true }`. `rebuild` means the option is read at construction — destroy the
|
|
835
|
+
component and create it again with the new options (in React, a `key` made of those options does
|
|
836
|
+
it). An option with neither is not stated: look for a method under another name before
|
|
837
|
+
rebuilding.
|
|
838
|
+
|
|
839
|
+
**Groupbox reports `open` and `close` later.** Groupbox is a native `<details>`; its events come
|
|
840
|
+
from the element's `toggle` event, which the browser dispatches in a later task, after the click
|
|
841
|
+
that changed the state. Between the two, `isOpen()` already reports the new state and the wrapper's
|
|
842
|
+
`open` prop still holds the old one. A wrapper that writes its prop back on every render —
|
|
843
|
+
`open ? box.open() : box.close()` — therefore reverts the reader's click whenever anything
|
|
844
|
+
re-renders in that gap, and then receives no event at all, because the state is back where it was.
|
|
845
|
+
Write `open` only when the prop itself changes, and take the state from the event:
|
|
846
|
+
|
|
847
|
+
```jsx
|
|
848
|
+
useEffect(() => { // runs when the prop changes, not on every render
|
|
849
|
+
if (box.current && box.current.isOpen() !== open) {
|
|
850
|
+
if (open) box.current.open(); else box.current.close();
|
|
851
|
+
}
|
|
852
|
+
}, [open]);
|
|
853
|
+
// constructed with: onopen: () => setOpen(true), onclose: () => setOpen(false)
|
|
854
|
+
```
|
|
855
|
+
|
|
856
|
+
A programmatic `open()` or `close()` is reported the same way, one task later, and has no
|
|
857
|
+
`silent` form; setting the state to what it already is reports nothing.
|
|
858
|
+
|
|
859
|
+
**Chart creates its engine when it can be measured.** `new Chart(...)` followed by
|
|
860
|
+
`chart.getInstance()` in the same effect returns the engine only if the chart is already in the
|
|
861
|
+
document and laid out; a chart appended later creates it then. Listen for `ready` (the `onready`
|
|
862
|
+
option) to reach the engine, or call `getInstance()` after appending, which creates it on the
|
|
863
|
+
spot. `setLoading(true)` and `setError()` destroy the engine and a later `setData()`,
|
|
864
|
+
`setLoading(false)` or `clearError()` creates a new one and fires `ready` again, so never keep the
|
|
865
|
+
instance across them. Theme changes reach the engine without a call.
|
|
866
|
+
|
|
867
|
+
**Testing under jsdom.** The components construct, open, close and destroy in a DOM without
|
|
868
|
+
layout or top layer:
|
|
869
|
+
|
|
870
|
+
- Modal, Dialog, Sheet and Launcher fall back to the `open` attribute where `showModal()` or
|
|
871
|
+
`showPopover()` is missing. `open()`, `close(result)`, `isOpen()`, Escape, `cancel`, the `open`
|
|
872
|
+
and `close` events and `destroy()` behave as in a browser. There is no top layer, no inert
|
|
873
|
+
page, no backdrop, and no `aria-modal` in the fallback, so a test cannot assert focus
|
|
874
|
+
containment or that the rest of the page is unreachable — use a browser for those. `close` is
|
|
875
|
+
reported asynchronously, as in a browser: `await` a tick before asserting on it.
|
|
876
|
+
- `Table` with `virtual: true` works without `ResizeObserver`: it draws for an assumed row height
|
|
877
|
+
(36px) and viewport. Stepper keeps every connector, and Chart creates its engine as soon as it
|
|
878
|
+
has data, since nothing will ever report a size.
|
|
879
|
+
- Everything measured is zero, so assertions on geometry (pinned-column offsets, a wrapped
|
|
880
|
+
stepper, an overflow menu) belong in a browser test.
|
|
881
|
+
|
|
678
882
|
## Custom elements
|
|
679
883
|
|
|
680
884
|
`defineElements()` (not auto-called) registers light-DOM `<zx-*>` wrappers with attribute↔option
|
|
@@ -768,7 +972,9 @@ accept.
|
|
|
768
972
|
`--zx-color-accent-solid*` roles, so in dark it keeps the deep stop with white ink rather than a
|
|
769
973
|
bright slab. A `ghost` button's icon is drawn in `--zx-color-text-subtle` until hovered. A button
|
|
770
974
|
with `aria-pressed="true"` (a Toolbar item with `active`, a view toggle) is a mode, not a pick:
|
|
771
|
-
it
|
|
975
|
+
it stays neutral, never the accent, and is drawn with a stronger fill plus a frame in
|
|
976
|
+
`--zx-color-text-subtle` (3:1 against its neighbours in both themes), so a pressed segment of a
|
|
977
|
+
`buttonGroup` is told apart without relying on the fill alone.
|
|
772
978
|
<!-- /doc -->
|
|
773
979
|
|
|
774
980
|
<!-- doc:badge -->
|
|
@@ -827,8 +1033,8 @@ a `MenuButton`, where choosing one activates the original control.
|
|
|
827
1033
|
in visual order under `dir="rtl"`; Home/End jump to the first and last control. A text field, select,
|
|
828
1034
|
or contenteditable item keeps its own keys: Home/End and the arrows move its caret, and an arrow
|
|
829
1035
|
moves on to the neighbouring control only once the caret is at that edge of the text.
|
|
830
|
-
- **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes
|
|
831
|
-
|
|
1036
|
+
- **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes Button's
|
|
1037
|
+
neutral pressed fill and frame, never the accent.
|
|
832
1038
|
<!-- /doc -->
|
|
833
1039
|
|
|
834
1040
|
<!-- doc:empty-state -->
|
|
@@ -839,7 +1045,9 @@ yet: an optional decorative icon, a headline, a sentence, and optional actions.
|
|
|
839
1045
|
paragraph rather than a heading, so dropping one into a Table's empty slot or a Panel body never
|
|
840
1046
|
disturbs the page's heading outline.
|
|
841
1047
|
|
|
842
|
-
- **Options** — `icon` (an icon name, `null` for none; default `'folder-open'`), `
|
|
1048
|
+
- **Options** — `icon` (an icon name, `null` for none; default `'folder-open'`), `agent`
|
|
1049
|
+
(`{seed?, name?, tone?, body?, eyes?, material?}` or `true`: an agent's AgentAvatar face, at rest,
|
|
1050
|
+
in place of the icon — an empty conversation, an agent with nothing to do yet), `title`,
|
|
843
1051
|
`description`, `actions: [Element | buttonOptions]`, `size: 'md'|'sm'`, `align: 'center'|'start'`.
|
|
844
1052
|
- **Methods** — none. `emptyState(options)` → `HTMLDivElement`, which you own and place yourself.
|
|
845
1053
|
- **Events** — none; action buttons carry their own `onclick`.
|
|
@@ -938,11 +1146,17 @@ a stronger border, the text colour); only the check glyph, the mark, keeps the a
|
|
|
938
1146
|
|
|
939
1147
|
Switch (`role="switch"`, `aria-checked`).
|
|
940
1148
|
|
|
941
|
-
- **Options** — `checked: false`, `value: true`, `label: null`, `
|
|
1149
|
+
- **Options** — `checked: false`, `value: true`, `label: null`, `hideLabel: false`,
|
|
1150
|
+
`disabled: false`.
|
|
942
1151
|
- **Label** — start-aligned and wrapping like text within the available width, the track level
|
|
943
|
-
with its first line.
|
|
1152
|
+
with its first line. It is the switch's accessible name. `hideLabel: true` keeps it for assistive
|
|
1153
|
+
technology only: no visible text, and the label becomes the switch's `aria-label` — for a switch
|
|
1154
|
+
whose meaning the layout already shows, such as a table cell under a column header. With no
|
|
1155
|
+
label at all, name the switch from outside: a Field or `<label for>` around it, or
|
|
1156
|
+
`aria-labelledby` on the element.
|
|
944
1157
|
- **Methods** — `get()`, `set(checked, {silent})`, `toggle()`, `getValue()` (returns
|
|
945
|
-
`options.value` when on, `false` when off), `
|
|
1158
|
+
`options.value` when on, `false` when off), `setLabel(label)` (null removes it),
|
|
1159
|
+
`enable()`/`disable()`.
|
|
946
1160
|
- **Events** — `change {checked, value}`.
|
|
947
1161
|
- **Keyboard** — Space/Enter.
|
|
948
1162
|
<!-- /doc -->
|
|
@@ -975,8 +1189,10 @@ permissions, recent-history/cache policy, and the route or command ultimately in
|
|
|
975
1189
|
`false`), and `scope` to explicitly select an element whose nearest Zx theme scope owns the launcher.
|
|
976
1190
|
- **Items** — `{id, label, description?, keywords?, group?, icon?, badge?, hint?, shortcut?, keys?,
|
|
977
1191
|
value?, href?, target?, invoke?, pinned?, disabled?, kind?, current?, when?, groupOrder?,
|
|
978
|
-
itemOrder?, items?, placeholder?, order?}`. `icon` accepts a bundled icon name, Node, or
|
|
979
|
-
factory.
|
|
1192
|
+
itemOrder?, items?, placeholder?, order?, agent?}`. `icon` accepts a bundled icon name, Node, or
|
|
1193
|
+
factory. `agent` (AgentAvatar options, or `true`) draws the item as the agent's still face
|
|
1194
|
+
instead — a tile's size for an `application` — with its activity's word, visually hidden, after
|
|
1195
|
+
the label in the option's name. Links stay native so modified and middle clicks work;
|
|
980
1196
|
non-link commands may provide an application-owned `invoke` callback. Malformed and executable
|
|
981
1197
|
URL schemes are stripped; a descriptor with no safe link or callback is disabled. `hint` is muted
|
|
982
1198
|
text at the end of the row (a current value, a project); `shortcut: ['⌘', 'K']` (or Button's
|
|
@@ -1091,6 +1307,64 @@ and the component is decorative by default so adjacent identity text is not anno
|
|
|
1091
1307
|
status, not the account's accessible name; supply `statusLabel` when it conveys information.
|
|
1092
1308
|
<!-- /doc -->
|
|
1093
1309
|
|
|
1310
|
+
<!-- doc:agent-avatar -->
|
|
1311
|
+
### AgentAvatar
|
|
1312
|
+
|
|
1313
|
+
A generated face for an agent that has no picture: a coloured geometric silhouette with eyes that
|
|
1314
|
+
take the agent's activity. Everything about it is derived from a
|
|
1315
|
+
seed, so the same agent has the same face on every screen; it is decorative by default, like
|
|
1316
|
+
Avatar.
|
|
1317
|
+
|
|
1318
|
+
- **Options** — `seed` (the agent's stable id; `null` uses `name`, but a rename then changes the
|
|
1319
|
+
face), `name`, `tone` (the Avatar tones, or `null` to derive it), `body` and `eyes` (fix one
|
|
1320
|
+
trait instead of deriving it), `spacing: 0|1|2` (the eye spacing), `material: 'flat'|'soft'`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 / 40px at the default
|
|
1321
|
+
spacing unit), `label`, `activity: 'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`,
|
|
1322
|
+
`activityLabel`, `indicator: true`, `animate: false`, and `phase: null|number`.
|
|
1323
|
+
- **Silhouettes** — fourteen, filled with the tone's `-solid`: circle, squircle, hexagon,
|
|
1324
|
+
triangle, drop, tilted pill, clover, dome, wedge, pentagon, trapezoid, cross, diamond and
|
|
1325
|
+
octagon; polygons round their corners. Eyes are `round`, `oval` or `square`, white with dark
|
|
1326
|
+
pupils, in `--zx-color-agent-eye` and `--zx-color-agent-pupil`, which keep their
|
|
1327
|
+
colour in both themes.
|
|
1328
|
+
- **Material** — `material: 'soft'` paints the body with a quiet vertical ramp: 10% toward the eye
|
|
1329
|
+
white at the top, the plain tone from 30% to 50% — across the eyes, which keep their flat-fill
|
|
1330
|
+
contrast — and 14% toward the pupil ink at the foot. It is an application-wide choice, not a
|
|
1331
|
+
trait. A soft avatar is drawn flat below 28px, when offline, in print and in forced colours; the
|
|
1332
|
+
root carries `data-material`.
|
|
1333
|
+
- **Traits** — `agentTraits(seed, overrides?)` returns `{tone, body, eyes, spacing}`. The tone is
|
|
1334
|
+
`avatarTone(seed)`, so the face matches an initials Avatar keyed the same way; each other trait
|
|
1335
|
+
hashes the same normalised key with its own salt. The tables `AGENT_BODIES` and `AGENT_EYES` are
|
|
1336
|
+
contract, order and length included. `agentFace(traits, activity, px)` returns the
|
|
1337
|
+
drawing as plain data (`{tag, part, attrs, children?}` in a 64-unit view box), for tests or a
|
|
1338
|
+
server.
|
|
1339
|
+
- **Sizes** — small sizes draw less: no pupils below 20px, and larger eyes at 24px and below.
|
|
1340
|
+
- **Activity** — the eyes take a static expression: open (idle), looking up and aside (thinking),
|
|
1341
|
+
lowered (working), wide (needs you), flat bars (blocked), closed on a faded, colourless face
|
|
1342
|
+
(offline). No mouths and nothing angry or sad. The Avatar activity dot (`indicator`) and the
|
|
1343
|
+
activity word in the accessible name stay the primary signal; the root carries `data-activity`.
|
|
1344
|
+
The dot is notched out of the face with a mask rather than ringed in a surface colour, so it reads
|
|
1345
|
+
on any background, glass navigation included.
|
|
1346
|
+
`animate: true` moves the root in the shared presence loop exactly as Avatar does and lets the eyes
|
|
1347
|
+
blink, drift and scan — never without the motion preference, and not inside a
|
|
1348
|
+
`data-zx-motion="reduced"` region. `phase` offsets both.
|
|
1349
|
+
- **Methods** — `set(values)` (any option above), `setActivity(activity, label?)`,
|
|
1350
|
+
`getActivity()`, `getActivityWord()` (the localized word, for a host that names its own
|
|
1351
|
+
control), `getTraits()`, `destroy()`. No events: wrap it in a button or link to make it
|
|
1352
|
+
interactive.
|
|
1353
|
+
- **In navigation** — `AppSidebar` and `ModuleBar` items take `agent` (these options, or `true`)
|
|
1354
|
+
and draw the AgentAvatar in place of their icon or tile, with the activity in the control's
|
|
1355
|
+
name; Composer mention items and Launcher items take `agent` too; AgentThread and RunTrace authors and ActivityItem
|
|
1356
|
+
avatar descriptors take `face`. Only a
|
|
1357
|
+
face's trait strings are read, so agent-supplied data cannot animate or name it.
|
|
1358
|
+
- **Elsewhere** — `emptyState()`, ApprovalCard and RunStatus take `agent` (traits and `name`, or
|
|
1359
|
+
`true`) in place of their icon: still and decorative, ApprovalCard's face looking up at you while
|
|
1360
|
+
the request waits, RunStatus's with the run's expression. KanbanView assignee descriptors take
|
|
1361
|
+
`face`, so an agent on a card's team is drawn as its face. The thread adapters
|
|
1362
|
+
(`connectAgUi()`, `connectUiMessageStream()`) draw the faces the thread's own `authors` give.
|
|
1363
|
+
Message `leading` and Card `media` accept an AgentAvatar like any other component.
|
|
1364
|
+
- **Accessibility** — the SVG is always hidden. With `label` the root is `role="img"`, named
|
|
1365
|
+
"label, activity word"; without one it is `aria-hidden`, for use beside the agent's name.
|
|
1366
|
+
<!-- /doc -->
|
|
1367
|
+
|
|
1094
1368
|
<!-- doc:entity-ref -->
|
|
1095
1369
|
### EntityRef
|
|
1096
1370
|
|
|
@@ -1171,7 +1445,9 @@ One chronological activity entry. It owns actor/avatar anatomy, semantic time, s
|
|
|
1171
1445
|
attachments, and actions; the application owns posting, reactions, permissions, routing,
|
|
1172
1446
|
persistence, and sanitization before any rich content becomes a Node.
|
|
1173
1447
|
|
|
1174
|
-
- **Options** — `id`, `actor`, `avatar` (Avatar options or Element
|
|
1448
|
+
- **Options** — `id`, `actor`, `avatar` (Avatar options or Element; with `face` — `{seed, tone,
|
|
1449
|
+
body, eyes, material}` or `true` — an agent's `AgentAvatar`, taking `name`, `label`, `size`,
|
|
1450
|
+
`tone`, `activity`, `activityLabel`, `animate` and `phase`), `title`, `content`,
|
|
1175
1451
|
`timestamp`, `timeLabel`, `metadata`, `attachments`, `actions`, `kind`, and
|
|
1176
1452
|
`headingLevel: 1..6`. Content slots accept text, Nodes, or Components and never parse HTML.
|
|
1177
1453
|
- **Actions** — Elements pass through; descriptors accept
|
|
@@ -1430,12 +1706,15 @@ from `Select`, with its themed popover and keyboard behavior.
|
|
|
1430
1706
|
Searchable multi-check list with optional async loading.
|
|
1431
1707
|
|
|
1432
1708
|
- **Options** — `items`, `valueKey: 'ID'`, `labelKey: 'name'`, `checkedKey: 'on'`, `search: true`,
|
|
1433
|
-
`height: 280`, `defaultChecked: false`, `
|
|
1434
|
-
|
|
1709
|
+
`height: 280`, `defaultChecked: false`, `label: null` (heading text and the group's accessible
|
|
1710
|
+
name; null uses the `checklist.label` message), `disabled: false`, `hideLabel: false` (leaves out
|
|
1711
|
+
the heading; the group keeps its text as `aria-label`), `load: async ()=>items`.
|
|
1435
1712
|
- **In a Field** — field type `checklist` draws no heading of its own: the field's label names the
|
|
1436
1713
|
group (`aria-labelledby`).
|
|
1437
1714
|
- **Methods** — `setItems()`, `getValues()`, `setValues(ids)`, `checkAll()`/`uncheckAll()`,
|
|
1438
|
-
`search(query)`, `reload()`.
|
|
1715
|
+
`search(query)`, `reload()`, `setLabel(text)`, `enable()`/`disable()`, `isDisabled()`. Disabled,
|
|
1716
|
+
the search field and every checkbox are disabled (`aria-disabled="true"` on the group) through
|
|
1717
|
+
searches, `setItems()` and reloads; values can still be set from code.
|
|
1439
1718
|
- **Events** — `change {values}`, `loaded`.
|
|
1440
1719
|
<!-- /doc -->
|
|
1441
1720
|
|
|
@@ -1447,7 +1726,8 @@ buttons are `tabindex="-1"`/`aria-hidden` pointer affordances — the input itse
|
|
|
1447
1726
|
Field type: `number`.
|
|
1448
1727
|
|
|
1449
1728
|
- **Options** — `value` (number|null), `min`, `max`, `step: 1`, `largeStep: 10` (PageUp/PageDown
|
|
1450
|
-
multiplier), `precision` (decimals; derived from `step` when null), `
|
|
1729
|
+
multiplier), `precision` (decimals; derived from `step` when null), `snap: true` (see
|
|
1730
|
+
**Snapping**), `wrap: false` (stepping past
|
|
1451
1731
|
a bound jumps to the other one), `placeholder`, `unit` (suffix rendered inside the control),
|
|
1452
1732
|
`group: false` (thousands separators while idle), `locale`, `disabled`, `readonly`, `required`,
|
|
1453
1733
|
`name`.
|
|
@@ -1455,6 +1735,11 @@ Field type: `number`.
|
|
|
1455
1735
|
the range; `''`/null clear it), `stepUp(n)`, `stepDown(n)`, `setRange(min, max)`,
|
|
1456
1736
|
`setReadonly()`, `reset()`, `focus()`, `getInput()`, `enable()`/`disable()`.
|
|
1457
1737
|
- **Events** — `change {value}` (committed), `input {value}` (per keystroke, possibly unsnapped).
|
|
1738
|
+
- **Snapping** — by default a typed or assigned value is moved onto the `step` grid (step 2 turns
|
|
1739
|
+
123 into 124) and rounded to the step's decimals. That suits quantities; it is wrong for a value
|
|
1740
|
+
that is not a multiple of anything — an identifier, a seed, a measurement. `snap: false` keeps
|
|
1741
|
+
the value exactly as entered: `step` is then only what the buttons and arrow keys add, decimals
|
|
1742
|
+
are rounded only to an explicit `precision`, and `min`/`max` still clamp.
|
|
1458
1743
|
- **Keyboard** — ↑/↓ one step, PageUp/PageDown `largeStep` steps, Home/End jump to `min`/`max` when
|
|
1459
1744
|
set (otherwise they keep their caret meaning), Enter commits, wheel steps while focused.
|
|
1460
1745
|
- **Also exported** — `parseNumber(raw)` (accepts `.` and `,` as the decimal separator, ignores
|
|
@@ -1521,12 +1806,14 @@ to a hidden textarea when the async Clipboard API is unavailable or denied.
|
|
|
1521
1806
|
|
|
1522
1807
|
#### copyButton()
|
|
1523
1808
|
|
|
1524
|
-
- **Signature** — `copyButton({text, label, title, feedback, feedbackDuration, size, kind, oncopy})`
|
|
1809
|
+
- **Signature** — `copyButton({text, label, title, feedback, feedbackDuration, size, kind, oncopy, signal})`
|
|
1525
1810
|
→ `HTMLButtonElement`.
|
|
1526
1811
|
- **Options** — `text: ''` — a string, or **a function returning one**, which is what a button
|
|
1527
1812
|
beside a live value needs so the copy is never stale; `label: ''` (empty renders an icon-only
|
|
1528
1813
|
ghost button), `title`, `feedback` (by default the `copy.copy` and `copy.copied` messages, and `null` gives no text), `feedbackDuration: 2000`,
|
|
1529
|
-
`size: 'md'|'sm'`, `kind: 'default'|'primary'|'ghost'
|
|
1814
|
+
`size: 'md'|'sm'`, `kind: 'default'|'primary'|'ghost'`, `signal` (an `AbortSignal`: aborting
|
|
1815
|
+
removes the button's listener and timer, and a copy still waiting on the clipboard then reports
|
|
1816
|
+
nothing — what a component owning the button passes from its own lifecycle).
|
|
1530
1817
|
- **Events** — `oncopy(text, copied)` is called for every attempt; `copied` is `false` when the
|
|
1531
1818
|
clipboard refused the write, and the button then stays untouched rather than claiming a copy
|
|
1532
1819
|
that did not happen.
|
|
@@ -1646,24 +1933,63 @@ use `TimePicker` or `DateTimeBox`.
|
|
|
1646
1933
|
|
|
1647
1934
|
Floating toasts come from statics; `new Message(target)` gives an inline, non-floating area with
|
|
1648
1935
|
the same `.show()`. The toast region is `role="status"`/`aria-live` (`role="alert"` for errors).
|
|
1649
|
-
|
|
1650
|
-
|
|
1936
|
+
A floating region sits at the top of the viewport on the inline-end side by default (`top-end`:
|
|
1937
|
+
the upper right in a left-to-right page), sizes to its messages rather than the page, and uses the
|
|
1938
|
+
translucent glass surface tokens with a solid fallback. A message is a plain card with a neutral
|
|
1939
|
+
border; its kind shows in the icon. Floating messages pile into a stack that opens on hover, focus,
|
|
1940
|
+
or a press (see **Stack**).
|
|
1651
1941
|
|
|
1652
1942
|
- **Statics** — `Message.info/success/warning/error(msg, opts)`,
|
|
1653
|
-
`Message.show(msg, { kind, timeout=4000, closable, scope? })` → `{ close() }`,
|
|
1654
|
-
`Message.progress(text, {scope?})` → `{ update(pct, text?), done(), fail(text?) }
|
|
1655
|
-
|
|
1656
|
-
|
|
1943
|
+
`Message.show(msg, { kind, timeout=4000, closable, highlight?, scope?, placement? })` → `{ close() }`,
|
|
1944
|
+
`Message.progress(text, {scope?, placement?, highlight?})` → `{ update(pct, text?), done(), fail(text?) }`,
|
|
1945
|
+
`Message.setPlacement(placement)` / `Message.getPlacement()`,
|
|
1946
|
+
`Message.setStack(enabled)` / `Message.getStack()`. `scope` is an element or selector
|
|
1947
|
+
whose nearest Zx theme scope owns that floating region; without it the focused opener supplies
|
|
1948
|
+
the scope.
|
|
1949
|
+
- **Placement** — `placement: 'top-start'|'top'|'top-end'|'bottom-start'|'bottom'|'bottom-end'`
|
|
1950
|
+
per call, default `'top-end'`: the block edge, then the inline position, logical, so `start` and
|
|
1951
|
+
`end` follow the writing direction and `top`/`bottom` alone are centred.
|
|
1952
|
+
`Message.setPlacement(placement)` sets the default for calls that name none and returns the
|
|
1953
|
+
placement now in effect (anything unknown restores `'top-end'`); it applies to messages shown
|
|
1954
|
+
from then on. Messages of one placement share a region, so a scope has one region per placement
|
|
1955
|
+
in use, each carrying `data-placement`. At the foot the newest toast is nearest the edge. The
|
|
1956
|
+
distance from the viewport edge is the `--zx-message-offset` custom property (default
|
|
1957
|
+
`var(--zx-space-4)`), read from the region's theme scope: set it there or on `:root` to clear a
|
|
1958
|
+
header or a status bar. At 640px and narrower every placement spans the foot of the viewport,
|
|
1959
|
+
full width. An inline area ignores `placement`.
|
|
1657
1960
|
- **Region lifecycle** — a floating region is created on the first toast for its scope and removed
|
|
1658
1961
|
when its last toast closes. One whose host was emptied or left the document is replaced on the
|
|
1659
1962
|
next toast rather than reused, and a scope that is itself detached falls back to the focused
|
|
1660
|
-
element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's
|
|
1661
|
-
toasts and all
|
|
1963
|
+
element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's regions at once — all
|
|
1964
|
+
placements, toasts and all — for a host torn down while toasts are still showing. While a modal Dialog or
|
|
1662
1965
|
Sheet is open the region moves into the topmost one, so toasts and their actions stay visible
|
|
1663
1966
|
and clickable above it, and moves back when it closes. A press on a toast dismisses no open menu
|
|
1664
1967
|
or drawer.
|
|
1665
1968
|
- **Per-message options** — `kind: 'info'`, `timeout`, `closable: true`, `maxVisible: 5` (extras
|
|
1666
|
-
queue, and hovering pauses dismissal)
|
|
1969
|
+
queue, and hovering pauses dismissal), `highlight: false`.
|
|
1970
|
+
- **Highlight** — `highlight: 'border'` (or `true`) draws the message's border in the kind colour;
|
|
1971
|
+
`highlight: 'animated'` draws it faintly with a light travelling round it, and is the still
|
|
1972
|
+
kind-coloured border under `prefers-reduced-motion: reduce`. Per message, or as an inline area's
|
|
1973
|
+
default; the message carries it as `data-highlight`. `false` (the default) is the plain card.
|
|
1974
|
+
- **Stack** — floating regions stack by default, and `stack: true` makes an inline area stack:
|
|
1975
|
+
the visible messages pile into one stack, the newest in front, the next two peeking out behind
|
|
1976
|
+
it a step smaller, the rest out of sight. `Message.setStack(false)` lists floating messages one
|
|
1977
|
+
below another instead (at once, those on screen included; `getStack()` reads it). It
|
|
1978
|
+
opens — every visible message laid out with its own height — while the pointer is over it or
|
|
1979
|
+
focus is inside it; a press on it that is not on a button (a tap included) keeps it open until a
|
|
1980
|
+
press outside it, Escape (which returns focus to where it came from), or `collapse()`. While it
|
|
1981
|
+
is open by any of these no message in it times out. The outside press is handled after its own
|
|
1982
|
+
click handlers, so a button elsewhere can toggle the stack with
|
|
1983
|
+
`isExpanded() ? collapse() : expand()`. Closing a message from the keyboard moves focus to the
|
|
1984
|
+
same control of the next message, and from the last one back to where it was before it came
|
|
1985
|
+
into the stack. An open floating stack taller than the viewport becomes a scrolling list
|
|
1986
|
+
(`data-overflow`) with the newest message in view. `expanded: true` keeps it open without
|
|
1987
|
+
holding the timers. Instance methods: `expand()` (opens and keeps it open), `collapse()`,
|
|
1988
|
+
`isExpanded()`, `setStack(enabled)`; events `expand` and `collapse`. The root carries
|
|
1989
|
+
`data-stack` and `data-state="collapsed"|"expanded"`; document order follows the visual order,
|
|
1990
|
+
so Tab meets the messages as they are seen. A stack at the top (inline areas, `top*`) piles
|
|
1991
|
+
downwards, one at the foot (`bottom*`, and every region at 640px and narrower) upwards. The
|
|
1992
|
+
geometry is the exported pure helper `messageStackLayout(heights, expanded)`.
|
|
1667
1993
|
- **Action** — `action: { label, onclick?, kind? }` renders one small button (`.zx-btn`,
|
|
1668
1994
|
`data-size="sm"`, secondary unless `kind` is `primary`/`danger`/`ghost`) in a toast or an inline
|
|
1669
1995
|
message; activating it runs `onclick(event)` and closes the message. A message with an action
|
|
@@ -1688,7 +2014,19 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
|
|
|
1688
2014
|
scope is resolved again on every `open()`; a `scope` element not yet in the document leaves the
|
|
1689
2015
|
dialog detached until then, rather than parking it on `<body>` outside the theme.
|
|
1690
2016
|
- **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
|
|
1691
|
-
- **Events** — `open`, `close {result}`, `cancel
|
|
2017
|
+
- **Events** — `open`, `close {result}`, `cancel {reason}`.
|
|
2018
|
+
- **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
|
|
2019
|
+
`reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
|
|
2020
|
+
action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
|
|
2021
|
+
`event.preventDefault()` keeps it open, which is the place for an "unsaved changes" check.
|
|
2022
|
+
A programmatic `close()` raises no `cancel`. Escape is handled by Zx rather than by the browser's
|
|
2023
|
+
close request, so preventing it holds however often the key is pressed; a handler that calls
|
|
2024
|
+
`preventDefault()` on the Escape keydown (a popup inside the dialog, your own) keeps the key.
|
|
2025
|
+
- **Without `showModal()`** — in a DOM that has `<dialog>` but not `showModal()` (jsdom, for unit
|
|
2026
|
+
tests), Modal, Dialog and Sheet present themselves through the `open` attribute instead.
|
|
2027
|
+
`open()`, `close(result)`, `isOpen()`, Escape, `cancel`, the events and `destroy()` work the
|
|
2028
|
+
same; there is no top layer, no inert page, no backdrop and no `aria-modal`, so modality itself
|
|
2029
|
+
is not testable there.
|
|
1692
2030
|
<!-- /doc -->
|
|
1693
2031
|
|
|
1694
2032
|
<!-- doc:dialog -->
|
|
@@ -1698,6 +2036,8 @@ Structured modal: a header with title and close button, a body, and footer butto
|
|
|
1698
2036
|
|
|
1699
2037
|
- **Options** — `title`, `size: 'sm'|'md'|'lg'|number`,
|
|
1700
2038
|
`buttons: [{ label, kind, action: 'close'|'cancel'|fn(dialog), autofocus, shortcut }]`, `closable: true`.
|
|
2039
|
+
`closable: false` refuses Escape and takes the header ✕ away entirely: it is not displayed, not
|
|
2040
|
+
focusable, and closes nothing. Close such a dialog from a footer button or with `close()`.
|
|
1701
2041
|
- **Methods** — `setTitle()`, `setContent()`, `setButtons()`,
|
|
1702
2042
|
`addView(key, { content, buttons? })`, `showView(key)`.
|
|
1703
2043
|
- **Statics returning Promises** — `Dialog.alert({ title, message, okLabel })`,
|
|
@@ -1724,13 +2064,15 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
|
|
|
1724
2064
|
|
|
1725
2065
|
- **Options** — `side: 'end'` (`'start' | 'end' | 'top' | 'bottom'`, logical), `modal: true`
|
|
1726
2066
|
(`true | 'trap-focus' | false`), `backdrop: 'dim'` (`'dim' | 'blur' | 'none'`), `size: null`
|
|
1727
|
-
(CSS length or px number, applied to whichever axis `side` implies), `closeButton: true
|
|
1728
|
-
|
|
2067
|
+
(CSS length or px number, applied to whichever axis `side` implies), `closeButton: true`
|
|
2068
|
+
(independent of `closable`, which governs Escape; when false the ✕ is not displayed, not
|
|
2069
|
+
focusable, and closes nothing), plus everything Dialog takes — `title`, `content`, `buttons`, `closable`, `lightDismiss`
|
|
1729
2070
|
(defaults to `true` here, unlike Modal), `destroyOnClose`, `scope`.
|
|
1730
2071
|
- **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
|
|
1731
2072
|
`isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
|
|
1732
2073
|
`setButtons()`, `addView()`, `showView()`.
|
|
1733
|
-
- **Events** — `open`, `close {result}`, `cancel` (preventable
|
|
2074
|
+
- **Events** — `open`, `close {result}`, `cancel {reason}` (preventable; raised by Escape, the ✕,
|
|
2075
|
+
a backdrop click or outside press, and a dismissing drag — see Modal's **Dismissal**),
|
|
1734
2076
|
`resize {size, ratio}`, `dockchange {docked, dock}`.
|
|
1735
2077
|
- **Docked** — a sheet has two lives, and it does not choose between them: `Dock.adopt(sheet)`
|
|
1736
2078
|
makes it a track in that dock's flow instead of an overlay, and the dock then owns its side,
|
|
@@ -1754,7 +2096,9 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
|
|
|
1754
2096
|
dialog while open, so it stays usable above it, closes when the dialog closes, and goes back to
|
|
1755
2097
|
its theme scope when it closes. Their top-layer backdrop is
|
|
1756
2098
|
explicitly transparent and non-filtering; `backdrop` is meaningful only when `modal` is `true`.
|
|
1757
|
-
A docked Sheet remains a native non-modal dialog in its Dock's flow.
|
|
2099
|
+
A docked Sheet remains a native non-modal dialog in its Dock's flow. Where the platform has no
|
|
2100
|
+
`showPopover()` (jsdom), a floating non-modal sheet is presented the same in-flow way, without
|
|
2101
|
+
the top layer.
|
|
1758
2102
|
- **Resizing and detents** — `resizable` makes the inner edge draggable between `min` and `max`.
|
|
1759
2103
|
`snap` gives it detents: a number at or below 1 is a fraction of the viewport along the sheet's
|
|
1760
2104
|
axis, anything larger is pixels, and a string is any CSS length (`'320px'`, `'90%'`). With
|
|
@@ -1874,8 +2218,11 @@ A button that opens a `role="menu"`.
|
|
|
1874
2218
|
- `href`, `target`, and `rel` render a genuine safe native link, preserving modifier clicks and
|
|
1875
2219
|
targets. Executable URL schemes are rejected; `_blank` receives `noopener noreferrer` by
|
|
1876
2220
|
default.
|
|
1877
|
-
- `role: 'menuitemcheckbox'|'menuitemradio'` with `checked` exposes an APG checked action.
|
|
1878
|
-
|
|
2221
|
+
- `role: 'menuitemcheckbox'|'menuitemradio'` with `checked` exposes an APG checked action.
|
|
2222
|
+
Choosing one updates it in place — a checkbox toggles, a radio is checked and the other radio
|
|
2223
|
+
items of its section (between separators or headings) are unchecked — and `select` reports the
|
|
2224
|
+
new state as `detail.checked`. Preventing `select` leaves the state as it was; the item objects
|
|
2225
|
+
passed in are not modified, so call `setItems()` to keep the model in step.
|
|
1879
2226
|
- `{type: 'choice', label, value, options: [{value, label, icon|glyph}], onselect(value, entry,
|
|
1880
2227
|
menu)}` draws a setting chosen in place — a theme, a layout: the label, then a small segmented
|
|
1881
2228
|
group of `menuitemradio` options named by it. Choosing an option checks it and calls
|
|
@@ -1938,7 +2285,7 @@ parked at the pointer, so it flips near a viewport edge like every other floatin
|
|
|
1938
2285
|
<!-- doc:tooltip -->
|
|
1939
2286
|
### Tooltip
|
|
1940
2287
|
|
|
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
|
|
2288
|
+
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's `aria-describedby` includes its id only while it is open — opening adds the id to whatever the attribute holds then, and closing removes only that id, so ids added by others (a field error) stay. 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.
|
|
1942
2289
|
|
|
1943
2290
|
- **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
|
|
1944
2291
|
(`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
|
|
@@ -1977,7 +2324,8 @@ Sortable, selectable, sticky-header data table. `fr` widths fill the container w
|
|
|
1977
2324
|
widths scroll horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
|
|
1978
2325
|
range select.
|
|
1979
2326
|
|
|
1980
|
-
- **Options** — `columns: [{ id, label, ariaLabel?, sortable?, width ('120px'|'2fr'|'auto'),
|
|
2327
|
+
- **Options** — `columns: [{ id, label, ariaLabel?, sortable?, width ('120px'|'2fr'|'auto'),
|
|
2328
|
+
minWidth?, pin?: 'start'|'end', group?, align,
|
|
1981
2329
|
type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
|
|
1982
2330
|
render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
|
|
1983
2331
|
`sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
|
|
@@ -1992,6 +2340,38 @@ range select.
|
|
|
1992
2340
|
the selected row of a `selectable: 'single'` table is the current record of a master–detail list
|
|
1993
2341
|
and takes the neutral `--zx-color-bg-current` fill. Sortable and plain headers set the same type,
|
|
1994
2342
|
and the scroll region reserves no scrollbar gutter until the table actually scrolls.
|
|
2343
|
+
- **Column widths** — `fr` columns share what the columns with a CSS length leave over, and never
|
|
2344
|
+
less than their `minWidth` (a CSS length or a number of pixels, default `'5rem'`; `0` lifts the
|
|
2345
|
+
floor). The table takes a minimum width from those floors, so a container too narrow for them
|
|
2346
|
+
scrolls the table inline instead of squeezing the `fr` columns to nothing — in a windowed table
|
|
2347
|
+
as well. `minWidth` is also honoured on an `auto` column of a table with a fixed layout (one
|
|
2348
|
+
with `fr` columns, or `virtual`), where it has no default; a column with a CSS length `width`
|
|
2349
|
+
ignores it.
|
|
2350
|
+
- **Sticky header** — `stickyHeader: true` sticks the column headers to the top of the table's
|
|
2351
|
+
**own scroll region** while its rows scroll. That takes a bounded region: set `height`, or use
|
|
2352
|
+
`virtual`, which caps the region at the window height. A table without one grows to the height
|
|
2353
|
+
of its rows, never scrolls itself, and its header leaves with the page; to keep a header in view
|
|
2354
|
+
while the *page* scrolls, give the table the height of the area it sits in. Header cells sit at
|
|
2355
|
+
`z-index: 2` inside the scroll region.
|
|
2356
|
+
- **Pinned columns** — `pin: 'start'|'end'` on a column keeps it in view at that inline edge of
|
|
2357
|
+
the scroll region while the table scrolls sideways (`position: sticky`, so it follows the
|
|
2358
|
+
writing direction). A pinned column stays where the column order puts it and sticks once it
|
|
2359
|
+
reaches the edge: declare a `'start'` column before the columns it should stay in front of and
|
|
2360
|
+
an `'end'` column after them. Several pinned columns stack in column order, and the row handle
|
|
2361
|
+
and selection checkbox columns are pinned along with the first `'start'` column. Give a pinned
|
|
2362
|
+
column a `width` or keep it short — what is pinned is taken from the room the others scroll in.
|
|
2363
|
+
A cell focused by keyboard scrolls clear of the pinned columns. Pinning is not applied while
|
|
2364
|
+
the table is stacked (`responsive`). Pinned cells are opaque and paint the row's fill
|
|
2365
|
+
themselves; `--zx-table-pin-bg` sets their base, the header background unless set. Cells carry
|
|
2366
|
+
`data-pin="start"|"end"`, and `data-pin-edge` on the column next to the scrolling ones.
|
|
2367
|
+
- **Header groups** — `group: 'Label'` on adjacent visible columns (with the same `pin`) gives
|
|
2368
|
+
them one shared header cell in a second header row above the column labels: a
|
|
2369
|
+
`<th scope="col">` with the right `colspan`, so assistive technology announces the group with
|
|
2370
|
+
every cell beneath it. Columns without a `group` have a blank above them. The group row holds
|
|
2371
|
+
no controls and takes no part in sorting or keyboard navigation; it counts as a row in
|
|
2372
|
+
`aria-rowcount`/`aria-rowindex`. Hiding or reordering columns regroups what is left: a group
|
|
2373
|
+
interrupted by another column becomes two cells. It works in plain, hierarchical and windowed
|
|
2374
|
+
tables, and sticks with the header.
|
|
1995
2375
|
- **Columns in the DOM** — every header and body cell carries `data-column="<id>"` in every mode,
|
|
1996
2376
|
read-only included, so a table can be styled per column. A column with `label: ''` (icons,
|
|
1997
2377
|
actions) keeps a blank header named by `ariaLabel`, or by its id; `ariaLabel` also names the
|
|
@@ -2006,6 +2386,11 @@ range select.
|
|
|
2006
2386
|
- **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
|
|
2007
2387
|
`selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
|
|
2008
2388
|
`rowclick` fires for Enter on a focused row as well as for a click; `event` is then the keydown.
|
|
2389
|
+
A click on a control inside a cell belongs to that control: it raises neither `rowclick` nor
|
|
2390
|
+
`rowdblclick` and does not select the row in a `single` selection. A control is a button, link,
|
|
2391
|
+
field or `<label>`, an element with a widget role or in the Tab order, editable content, or
|
|
2392
|
+
anything marked `data-zx-table-no-edit` — so a Toggle, a menu button or a link rendered into a
|
|
2393
|
+
cell needs no `stopPropagation()`. Mark a custom clickable element the same way.
|
|
2009
2394
|
- **Keyboard** — an *interactive* table implements the WAI-ARIA APG **Grid** pattern
|
|
2010
2395
|
(`role="grid"`, with `aria-multiselectable` for `selectable: 'multi'`), or the **Treegrid**
|
|
2011
2396
|
pattern with `hierarchy`. A table is interactive when it is `selectable`, has `editMode` or
|
|
@@ -2047,7 +2432,13 @@ range select.
|
|
|
2047
2432
|
editing/mutation APIs stay flat and ID-based. Orphans become roots, cycles render once, local
|
|
2048
2433
|
sort reorders siblings without mixing levels, and growing counts visible rows. Use
|
|
2049
2434
|
`toggleRow()`, `expandRow()`, `collapseRow()`, `expandAll()`, `collapseAll()`, and
|
|
2050
|
-
`getExpanded()`.
|
|
2435
|
+
`getExpanded()`. `hierarchy.expanded` is read at construction only; `setExpanded(ids, {silent})`
|
|
2436
|
+
replaces the whole set afterwards in one render, which is what to call when restoring a saved
|
|
2437
|
+
state (a loop over `expandRow()` renders once per branch). `true` expands every branch, `false`
|
|
2438
|
+
or `[]` collapses them all; ids are compared as `rowId` returns them (`1` is not `'1'`), and ids
|
|
2439
|
+
that are not branches of the current data are dropped. Unless silent it emits one `rowtoggle`
|
|
2440
|
+
per branch whose state changed, after the render; a set equal to the current one renders and
|
|
2441
|
+
fires nothing. The native disclosure button works by pointer and keyboard without selecting
|
|
2051
2442
|
or clicking the row.
|
|
2052
2443
|
- **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set),
|
|
2053
2444
|
plus `editTrigger: 'double'|'single'` (Table defaults to double; Grid defaults to single).
|
|
@@ -2118,7 +2509,8 @@ range select.
|
|
|
2118
2509
|
height for all, following `--zx-row-height`, so rows of differing height are not supported, and
|
|
2119
2510
|
long text is cut short with an ellipsis rather than wrapped. Column widths cannot follow content
|
|
2120
2511
|
that is not drawn, so the layout is fixed: `auto` columns share the width evenly, and a column that
|
|
2121
|
-
needs more sets `width`.
|
|
2512
|
+
needs more sets `width`. It needs no `ResizeObserver`: where there is none (jsdom) the window
|
|
2513
|
+
draws for an assumed row height and viewport. **Find-in-page does not see rows that are not drawn**, and printing prints
|
|
2122
2514
|
the drawn rows only.
|
|
2123
2515
|
- **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
|
|
2124
2516
|
label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
|
|
@@ -2286,7 +2678,8 @@ cards, advisory work-in-progress limits, and equivalent pointer/programmatic/key
|
|
|
2286
2678
|
and action controls reveal on hover/focus/selection/grab, and remain visible on touch devices.
|
|
2287
2679
|
- **Assignees** — `assignees` faces (a name, names, or `{name, src?, initials?, tone?}`) are drawn
|
|
2288
2680
|
like a small Avatar: initials on the tint `avatarTone(name)` picks, so a person has the same
|
|
2289
|
-
colour on the board as in every Avatar; a descriptor's own `tone` wins.
|
|
2681
|
+
colour on the board as in every Avatar; a descriptor's own `tone` wins. A descriptor with `face`
|
|
2682
|
+
(AgentAvatar traits, or `true`) is an agent, drawn as its generated face.
|
|
2290
2683
|
- **Movement boundary** — `recordmove {record,id,from,to,column,swimlane,limitExceeded}` is
|
|
2291
2684
|
cancelable and fires before a commit/request; either the component event or bubbling
|
|
2292
2685
|
`zx-recordmove` mirror may veto it. `accept` is a hard eligibility gate; WIP is visual advice.
|
|
@@ -2309,7 +2702,9 @@ without forking its implementation, so sorting, selection, hierarchy, responsive
|
|
|
2309
2702
|
editable cells/rows, loading, events, and teardown keep the Table contract.
|
|
2310
2703
|
|
|
2311
2704
|
- **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API and defaults
|
|
2312
|
-
editable cells to a single-click trigger.
|
|
2705
|
+
editable cells to a single-click trigger. Pinned columns, header groups, `minWidth`,
|
|
2706
|
+
`setExpanded()` and the rule that a click on a control inside a cell raises no `rowclick` are
|
|
2707
|
+
Table's and apply unchanged.
|
|
2313
2708
|
- **Preset** — `Grid.BillingItems(target, options)` supplies an editable hierarchical billing
|
|
2314
2709
|
schema for item, quantity, unit, unit price, currency, and line total. It enables single-click
|
|
2315
2710
|
editing, hierarchy, row reorder handles, and the column visibility chooser. It returns a `Grid`.
|
|
@@ -2325,33 +2720,111 @@ editable cells/rows, loading, events, and teardown keep the Table contract.
|
|
|
2325
2720
|
<!-- /doc -->
|
|
2326
2721
|
|
|
2327
2722
|
<!-- doc:chart -->
|
|
2328
|
-
### Chart and `ChartJsAdapter`
|
|
2723
|
+
### Chart, `SvgChartAdapter` and `ChartJsAdapter`
|
|
2329
2724
|
|
|
2330
2725
|
An accessible, engine-neutral chart host. Zx renders state, canvas, semantic data summary, tokens,
|
|
2331
|
-
and lifecycle; an
|
|
2332
|
-
|
|
2333
|
-
|
|
2726
|
+
and lifecycle; an adapter owns the drawing. Two are supplied: `SvgChartAdapter` draws bar, line,
|
|
2727
|
+
pie and doughnut charts as SVG and needs nothing else; `ChartJsAdapter` draws any Chart.js type
|
|
2728
|
+
with a Chart.js 4 the host supplies (the Zx runtime imports no Chart.js code). Without an adapter
|
|
2729
|
+
Chart draws nothing, and the data lives in its summary table alone.
|
|
2730
|
+
|
|
2731
|
+
```js
|
|
2732
|
+
const chart = new Chart(null, {
|
|
2733
|
+
adapter: new SvgChartAdapter(),
|
|
2734
|
+
type: 'bar',
|
|
2735
|
+
label: 'Invoiced and collected per week',
|
|
2736
|
+
data: { labels: ['Week 1', 'Week 2'], datasets: [{ label: 'Invoiced', data: [52300, 61200] }] }
|
|
2737
|
+
});
|
|
2738
|
+
```
|
|
2334
2739
|
|
|
2335
2740
|
- **Options** — `adapter`, `type: 'bar'`, `data`, engine-specific `chartOptions`, `label`,
|
|
2336
|
-
`description`, `summary: 'hidden'|'visible'`, `
|
|
2337
|
-
`aspectRatio: '16 / 9'`.
|
|
2741
|
+
`description`, `summary: 'hidden'|'visible'`, `summaryFormat: null`, `loading`,
|
|
2742
|
+
loading/empty/error text, `aspectRatio: '16 / 9'`, and `fill: false`.
|
|
2338
2743
|
- **Methods** — `setData()`, `setType()`, `update(chartOptions)`, `setAdapter()`, `setLoading()`,
|
|
2339
|
-
`setError()`, `clearError()`, `
|
|
2744
|
+
`setError()`, `clearError()`, `setLabel()`, `setDescription()`, `setSummary()`,
|
|
2745
|
+
`setAspectRatio()`, `setFill()`, `resize()`, `refreshTheme()`, `getInstance()`, `destroy()`.
|
|
2340
2746
|
- **Events** — `ready {instance}`, `update {data, type}`, `select {datasetIndex, index, dataset,
|
|
2341
2747
|
label, value, nativeEvent}`, and `error {error}`.
|
|
2342
|
-
- **
|
|
2343
|
-
|
|
2748
|
+
- **When the engine exists** — the engine is created once the chart is in a document, its
|
|
2749
|
+
viewport has a size, and it has data and an adapter; `ready` fires then, not necessarily inside
|
|
2750
|
+
the constructor. A chart constructed on a target that is already laid out mounts synchronously;
|
|
2751
|
+
one built with `null` and appended later mounts when the browser reports its size.
|
|
2752
|
+
`getInstance()` and `resize()` do not wait: called after the chart is appended, they create the
|
|
2753
|
+
engine on the spot, and `getInstance()` returns null while there is none. A chart that is
|
|
2754
|
+
loading, empty, or in error has no engine. Where there is no `ResizeObserver` or no layout at
|
|
2755
|
+
all (jsdom), nothing can report a size and the engine is created as soon as there is data.
|
|
2756
|
+
- **State changes and the engine** — `setData()` clears both the loading state and an error.
|
|
2757
|
+
`setLoading(true)` and `setError()` destroy the engine; the next `setData()`,
|
|
2758
|
+
`setLoading(false)` or `clearError()` creates a new one and fires `ready` again, so do not hold
|
|
2759
|
+
on to an instance across them. `setAdapter()` replaces the engine as well.
|
|
2760
|
+
- **Sizing** — by default the viewport takes the width it is given and derives its height from
|
|
2761
|
+
`aspectRatio` (`setAspectRatio()` changes it; null restores the default), never less than
|
|
2762
|
+
`--zx-chart-min-block-size` (220px unless set, on the chart or any ancestor). `fill: true` (or
|
|
2763
|
+
`setFill()`) takes the block size of the container instead: the root is 100% tall, the viewport
|
|
2764
|
+
takes what the description and a visible summary leave, `aspectRatio` is not used, and there is
|
|
2765
|
+
no minimum unless `--zx-chart-min-block-size` sets one. The container needs a height of its
|
|
2766
|
+
own. The chart follows its viewport; `resize()` is for an engine that needs telling after
|
|
2767
|
+
something else changed.
|
|
2768
|
+
- **Theme** — the chart resolves `--zx-color-text`, `--zx-color-border` and the categorical
|
|
2769
|
+
palette `--zx-color-chart-1`…`-8` on its root and hands them to the adapter as values. It does
|
|
2770
|
+
so again by itself when a `data-zx-theme` or `data-zx-preset` attribute changes anywhere in the
|
|
2771
|
+
document, when the system colour scheme or contrast preference changes, and when the chart is
|
|
2772
|
+
shown again after being hidden or moved. `refreshTheme()` is only for changes none of those
|
|
2773
|
+
cover: a stylesheet swap, a class, an inline custom property.
|
|
2774
|
+
- **Adapter contract** — `adapter.create(canvas, {type, data, options, theme, reducedMotion, onSelect})`
|
|
2775
|
+
returns `{update(spec), resize(), destroy(), instance?}`; `update(spec)` is called for new data,
|
|
2776
|
+
type or options and whenever the theme or the motion preference changes. An adapter that draws
|
|
2777
|
+
an element of its own implements `mount(viewport, spec)` instead, with the same spec and handle:
|
|
2778
|
+
Chart calls `mount()` when an adapter has it, `create()` otherwise. The canvas then stays in
|
|
2779
|
+
place, empty, keeping the chart's accessible name and description; what `mount()` appends lies
|
|
2780
|
+
over it, is presentational (`aria-hidden="true"`), and goes with the handle's `destroy()`. `spec.theme` is
|
|
2781
|
+
`{color?, borderColor?, palette}`: text colour, grid and axis colour, and the series colours in
|
|
2782
|
+
order (empty where the tokens are not defined; series beyond the eighth start over).
|
|
2783
|
+
`spec.options` is the application's `chartOptions` over `color` and `borderColor`, the same two
|
|
2784
|
+
strings in the shape Chart.js reads. Every colour is `#rrggbb` when opaque and
|
|
2785
|
+
`rgba(r, g, b, a)` when translucent — never `color()`, `oklch()`, `light-dark()` or a `var()` —
|
|
2786
|
+
so an engine with its own colour parser reads it. Implementations must destroy engine
|
|
2344
2787
|
resources and must not retain the component after teardown. `reducedMotion` is true under the
|
|
2345
2788
|
system preference or inside a `data-zx-motion="reduced"` region, and an adapter must then turn its
|
|
2346
2789
|
engine's animation off; Chart watches for the answer changing and updates the mounted engine.
|
|
2790
|
+
- **`SvgChartAdapter`** — `new SvgChartAdapter({animation: true, legend: null})` draws `bar`
|
|
2791
|
+
(grouped), `line`, `pie` and `doughnut`; any other type puts the chart in its error state, and
|
|
2792
|
+
`SvgChartAdapter.supports(type)` answers first. A value is a number, or the `y` (else `r`) of a
|
|
2793
|
+
point object; null and anything not finite is a gap — no bar, a break in the line, no slice.
|
|
2794
|
+
Bars stand on zero; a line's scale spans its data; ticks fall on 1, 2 or 5 × 10ⁿ and are written
|
|
2795
|
+
compactly in the active language ("250K"). Pie and doughnut draw one ring per dataset, a slice
|
|
2796
|
+
per positive value. The legend lists the series (the labels, for pie and doughnut) when there are
|
|
2797
|
+
two or more and for the arc kinds; `legend: true|false` forces it. Colours come through CSS from
|
|
2798
|
+
`--zx-color-chart-1`…`-8`, so a theme or preset switch repaints without a redraw; a dataset's own
|
|
2799
|
+
colour keys are not read, and series past the eighth take the palette again, lighter (dashed, for
|
|
2800
|
+
a line). The plot's `viewBox` is its size in pixels, so text keeps its size: it scales with the
|
|
2801
|
+
viewport and is laid out again on the next resize, thinning category labels rather than
|
|
2802
|
+
overlapping them. Each mark has a `<title>` ("Week 1 · Invoiced: 52,300") and pressing one fires
|
|
2803
|
+
`select` with the usual detail; there is no keyboard path through the marks — the summary table is
|
|
2804
|
+
the accessible one. The first drawing grows in unless motion is reduced (system, or a
|
|
2805
|
+
`data-zx-motion="reduced"` region) or `animation` is false; per chart, `chartOptions.animation` and
|
|
2806
|
+
`chartOptions.legend` decide over the adapter's options. `getInstance()` returns the drawing
|
|
2807
|
+
element. One adapter serves any number of charts.
|
|
2347
2808
|
- **`ChartJsAdapter`** — construct it with a Chart.js constructor or namespace:
|
|
2348
2809
|
`new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development dependency and copies it to its
|
|
2349
2810
|
self-hosted vendor assets during the website build; `package.json` has no runtime dependencies and application builds explicitly choose how
|
|
2350
2811
|
the engine is loaded. Under reduced motion it sets `animation: false`, over any animation the
|
|
2351
|
-
application configured.
|
|
2352
|
-
|
|
2353
|
-
|
|
2354
|
-
|
|
2812
|
+
application configured. A dataset that names neither `backgroundColor` nor `borderColor` is
|
|
2813
|
+
coloured from the theme palette: one colour per series (a bar filled with it, a line, radar or
|
|
2814
|
+
point series stroked with it and filled at half opacity), or one per value for `pie`,
|
|
2815
|
+
`doughnut` and `polarArea`. A dataset that names either is left exactly as written.
|
|
2816
|
+
- **Accessibility** — the canvas always has a name and optional description, whichever adapter
|
|
2817
|
+
draws, while synchronized labels and dataset values live in a semantic table.
|
|
2818
|
+
`summary: 'hidden'` keeps it visually hidden for assistive technology; `'visible'` makes exact
|
|
2819
|
+
values part of the interface. `setLabel()`
|
|
2820
|
+
renames the canvas and the table's caption, `setDescription()` and `setSummary()` change the
|
|
2821
|
+
other two.
|
|
2822
|
+
- **Summary values** — a number is written for the active language (the chart's `lang`, else
|
|
2823
|
+
`getLanguage()`) with grouping and up to twelve significant digits: `1234567.5` reads
|
|
2824
|
+
"1,234,567.5" and `0.1 + 0.2` reads "0.3". For a point object the value is its `y`, else its
|
|
2825
|
+
`r`. `summaryFormat(value, context)` returns the text of one cell instead — a currency, a unit,
|
|
2826
|
+
a percentage — with `context` `{dataset, datasetIndex, index, label, raw, formatted}`, where
|
|
2827
|
+
`formatted` is the default text; returning null or undefined keeps it.
|
|
2355
2828
|
<!-- /doc -->
|
|
2356
2829
|
|
|
2357
2830
|
<!-- doc:calendar -->
|
|
@@ -2366,8 +2839,10 @@ windowed loader.
|
|
|
2366
2839
|
- **Options** — `events`, `date`, `view: 'month'`, `views: ['agenda','day','week','month','year']`,
|
|
2367
2840
|
`locale`, `weekStart: 1`, `weekNumbers: true`, `workweek: false`, `agendaDays: 14`,
|
|
2368
2841
|
`slotDuration: 30`, `slotMinTime: 0`, `slotMaxTime: 1440`, `scrollTime: 480`, `eventLimit: 3`,
|
|
2369
|
-
`selectable: false`, `editable: false`, `eventStartEditable
|
|
2370
|
-
`
|
|
2842
|
+
`selectable: false`, `editable: false`, `eventStartEditable` (`true`/`false` overrides
|
|
2843
|
+
`editable` for moving), `eventDurationEditable` (`true`/`false` overrides `editable` for
|
|
2844
|
+
resizing; a string or function instead names the per-event resize field, `'durationEditable'`
|
|
2845
|
+
by default), `optimistic: true`, `nowIndicator: true`, `now`, `disabled`, `msg`, and `renderEvent(event)`.
|
|
2371
2846
|
- **Messages** — every key is namespaced `calendar.*`: `calendar.today`, `calendar.previous`,
|
|
2372
2847
|
`calendar.next`, `calendar.new`, `calendar.agenda`/`day`/`week`/`month`/`year` (the view
|
|
2373
2848
|
switch), `calendar.viewSwitch`, `calendar.label` (the root's name), `calendar.loading`,
|
|
@@ -2412,7 +2887,9 @@ windowed loader.
|
|
|
2412
2887
|
text announces the edit and its proposed times.
|
|
2413
2888
|
- **ZeyOS binding** — `zeyosCalendar()` maps current appointment occurrence rows (`ID`, `name`,
|
|
2414
2889
|
`location`, `color`, `datefrom`, `dateto`, and association text). `calendarEventToZeyosPatch()`
|
|
2415
|
-
returns the base `ID` with Unix-second dates.
|
|
2890
|
+
returns the base `ID` with Unix-second dates. Pass the instance's `timeZone` to both so an all-day
|
|
2891
|
+
appointment is recognised from midnight in that zone and lands on the right days for a viewer
|
|
2892
|
+
elsewhere; without it the viewer's own midnight is used. The current server already expands recurrence into
|
|
2416
2893
|
the requested window; recurrence rules, DAV synchronization, permissions, and routes therefore
|
|
2417
2894
|
remain in ZeyOS instead of being reimplemented in core.
|
|
2418
2895
|
<!-- /doc -->
|
|
@@ -2533,7 +3010,9 @@ mutate the caller's data.
|
|
|
2533
3010
|
- **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
|
|
2534
3011
|
`expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
|
|
2535
3012
|
(tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
|
|
2536
|
-
(lazy children; mark a branch with `hasChildren: true`
|
|
3013
|
+
(lazy children; mark a branch with `hasChildren: true` — it counts as open only once its
|
|
3014
|
+
children are loaded, so → and `toggle()` load it, `*` loads and opens lazy siblings, and
|
|
3015
|
+
`expandAll()`, filtering and `expanded` leave unloaded branches closed), `filter`, `emptyText`, `height`,
|
|
2537
3016
|
`rowActions: (node) => actions`, `moreLabel`. Unset, `label`, `emptyText` and `moreLabel` read the
|
|
2538
3017
|
`tree.label`, `tree.noItems` and `tree.more` messages; `tree.empty` still wins over `emptyText`, and
|
|
2539
3018
|
`emptyText: null` shows no text.
|
|
@@ -2678,10 +3157,37 @@ Beyond the built-in field types, these widget types wrap whole components, used
|
|
|
2678
3157
|
`registerFieldAdapters()`, which `src/index.js` calls by default.
|
|
2679
3158
|
|
|
2680
3159
|
- `zxselect` (Select), `checklist` (Checklist), `tagpicker` (TagPicker), `number` (NumberField),
|
|
2681
|
-
`rating` (Rating).
|
|
2682
|
-
- `date`/`month`/`datetime` (Datebox/MonthPicker — pass a `Date` value), `
|
|
3160
|
+
`rating` (Rating), `slider` (Slider).
|
|
3161
|
+
- `date`/`month`/`datetime` (Datebox/MonthPicker — pass a `Date` value), `daterange`
|
|
3162
|
+
(DateRangeBox — a `{start, end}` value), `time` (Timebox).
|
|
2683
3163
|
- `valuelist` (ValueList), `multivalueeditor` (MultiValueEditor), `upload` (FieldUpload),
|
|
2684
|
-
`toggle` (Toggle).
|
|
3164
|
+
`toggle` (Toggle), `code` (CodeEditor).
|
|
3165
|
+
|
|
3166
|
+
**Stylesheet names for `zx-css`.** A field type is registered at run time, so `zx-css` cannot
|
|
3167
|
+
follow it from `form` to the component that draws it: name that component's stylesheet beside
|
|
3168
|
+
`form`. Each line is field type — component — the name to pass, and the stylesheets that name
|
|
3169
|
+
depends on come with it.
|
|
3170
|
+
|
|
3171
|
+
- `zxselect` — Select — `select`
|
|
3172
|
+
- `checklist` — Checklist — `checklist`
|
|
3173
|
+
- `tagpicker` — TagPicker — `tag-picker`
|
|
3174
|
+
- `number` — NumberField — `number-field`
|
|
3175
|
+
- `rating` — Rating — `rating`
|
|
3176
|
+
- `slider` — Slider — `slider`
|
|
3177
|
+
- `date` — Datebox — `datebox`
|
|
3178
|
+
- `datetime` — DateTimeBox — `datebox`
|
|
3179
|
+
- `month` — MonthPicker — `date-picker`
|
|
3180
|
+
- `daterange` — DateRangeBox — `date-range-box`
|
|
3181
|
+
- `time` — Timebox — `timebox`
|
|
3182
|
+
- `valuelist` — ValueList — `value-list`
|
|
3183
|
+
- `multivalueeditor` — MultiValueEditor — `multi-value-editor`
|
|
3184
|
+
- `upload` — FieldUpload — `field-upload`
|
|
3185
|
+
- `toggle` — Toggle — `toggle`
|
|
3186
|
+
- `code` — CodeEditor — `code-editor`
|
|
3187
|
+
|
|
3188
|
+
The built-in types — `text`, `password`, `textarea`, `checkbox`, `int`, `float`, `select`,
|
|
3189
|
+
`optionlist`, `hidden`, `html`, `custom` — are drawn by Field itself and need `form` alone. A form
|
|
3190
|
+
with a Select and a date field is `npx zx-css form select datebox --out public/zx.css`.
|
|
2685
3191
|
<!-- /doc -->
|
|
2686
3192
|
|
|
2687
3193
|
<!-- doc:code-editor -->
|
|
@@ -2693,17 +3199,32 @@ surface for structured text — templates, queries, configuration — while rich
|
|
|
2693
3199
|
stays a separate policy decision.
|
|
2694
3200
|
|
|
2695
3201
|
- **Options** — `value`, `name`, `language` (shown to the reader and exposed as data),
|
|
2696
|
-
`label`, `placeholder`, `rows` (clamped 2–100), `indent` (inserted by Tab, removed by
|
|
2697
|
-
Shift+Tab), `wrap: 'off'|'soft'|'hard'`,
|
|
2698
|
-
`status` (the line/column readout).
|
|
2699
|
-
- **Methods** — `setValue()
|
|
2700
|
-
|
|
2701
|
-
|
|
2702
|
-
|
|
2703
|
-
|
|
2704
|
-
|
|
2705
|
-
or
|
|
2706
|
-
|
|
3202
|
+
`label`, `placeholder`, `rows` (clamped 2–100), `indent: '\t'` (inserted by Tab, removed by
|
|
3203
|
+
Shift+Tab; `' '` for two spaces, `''` to leave Tab alone), `wrap: 'off'|'soft'|'hard'`,
|
|
3204
|
+
`spellcheck`, `readOnly`, `disabled`, `status` (the line/column readout).
|
|
3205
|
+
- **Methods** — `setValue()`, `getValue()`, `setLanguage()`, `setReadOnly()`,
|
|
3206
|
+
`enable()`/`disable()`, `getInput()` (the
|
|
3207
|
+
native textarea: the element that carries the name, validity and description, and the one a
|
|
3208
|
+
`<label for>` names), `setHighlight(message, kind = 'danger')`, `clearHighlight()`, `focus()`.
|
|
3209
|
+
- **Events** — `input {value}`, `change {value}`, `invalid {message}`.
|
|
3210
|
+
- **Tab** — while `indent` is non-empty the editor captures Tab: Tab inserts the indent at the
|
|
3211
|
+
caret or indents every selected line, Shift+Tab outdents them, and focus stays in the editor.
|
|
3212
|
+
That is what a code surface has to do and what makes it a keyboard trap if nothing else is
|
|
3213
|
+
arranged — so Escape releases the capture until the next keystroke in the editor: Escape then
|
|
3214
|
+
Tab (or Shift+Tab) leaves the field, and any other key, or leaving the editor, restores
|
|
3215
|
+
indentation. `indent: ''` switches the capture off: Tab and Shift+Tab move focus as in any other
|
|
3216
|
+
field and nothing is indented. Tab with Ctrl, Alt or Meta, and Tab in a read-only or disabled
|
|
3217
|
+
editor, are never captured.
|
|
3218
|
+
- **Error state** — a standalone editor reports a validation or status message the way a Field
|
|
3219
|
+
does. `setHighlight(message, kind)` shows it under the text and reflects `kind`
|
|
3220
|
+
(`'danger'|'warning'|'success'`) as `data-state` on the root. `'danger'` is the error state: the
|
|
3221
|
+
textarea gets `aria-invalid="true"`, the message is announced as an alert, the frame takes the
|
|
3222
|
+
danger colour, and `invalid {message}` is emitted. The message describes the textarea
|
|
3223
|
+
(`aria-describedby`) for as long as it is shown; an empty message, or `clearHighlight()`, clears
|
|
3224
|
+
it.
|
|
3225
|
+
- **In a Form** — a `code` field adapter is registered by `registerFieldAdapters()`. Set the
|
|
3226
|
+
Field's own message there (`field.setHighlight()`), not the editor's: the Field labels the
|
|
3227
|
+
textarea, marks it invalid and describes it with its message, and the editor's frame follows.
|
|
2707
3228
|
<!-- /doc -->
|
|
2708
3229
|
|
|
2709
3230
|
<!-- doc:questionnaire -->
|
|
@@ -2974,6 +3495,11 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
|
|
|
2974
3495
|
decoration and saying the delta twice is worse than saying it once.
|
|
2975
3496
|
- **The element follows the behaviour** — `href` renders an `<a>`, `onclick` without `href` a
|
|
2976
3497
|
`<button>`, neither a `<div>` with `role="group"`. Never a div with a click handler.
|
|
3498
|
+
`clickable: true` renders the button without an `onclick` option, for subscribing with
|
|
3499
|
+
`on('click', …)`. An explicit `clickable: false` wins over `onclick`: the tile stays a `<div>`
|
|
3500
|
+
and the handler is never called, for a caller that always passes a handler and decides per tile
|
|
3501
|
+
whether it applies. It never turns a tile with an `href` into anything but a link. Leave
|
|
3502
|
+
`onclick` out, rather than passing an empty function, for a tile that does nothing.
|
|
2977
3503
|
- **`loading: true` renders a skeleton shaped like the tile**, not a spinner.
|
|
2978
3504
|
|
|
2979
3505
|
Nothing in it assumes a fixed set of buckets or a fixed label: the content of a dashboard tile
|
|
@@ -2988,18 +3514,27 @@ the target in place: it does not wrap, replace, or relocate the surface's conten
|
|
|
2988
3514
|
own routing, overlays, or interaction. Its gradients sit behind the target's children, so raised
|
|
2989
3515
|
Cards and other Liquid Glass surfaces can pick up the underlying colour naturally.
|
|
2990
3516
|
|
|
2991
|
-
- **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'`,
|
|
3517
|
+
- **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'|'mesh'|'ribbon'|'bloom'`,
|
|
2992
3518
|
`colors: []` (zero to four concrete CSS colours),
|
|
2993
|
-
`intensity: 'subtle'|'balanced'|'vivid'`.
|
|
2994
|
-
- **Methods** — `setPreset(preset)`, `setColors(colors)`, `setIntensity(intensity)
|
|
3519
|
+
`intensity: 'subtle'|'balanced'|'vivid'`, `motion: 'none'|'drift'|'flow'`.
|
|
3520
|
+
- **Methods** — `setPreset(preset)`, `setColors(colors)`, `setIntensity(intensity)`,
|
|
3521
|
+
`setMotion(motion)`.
|
|
2995
3522
|
- **Palette** — an empty list uses semantic accent, info, success, and warning colours. One colour
|
|
2996
3523
|
fills all four fields; two alternate; three repeat the second colour in the fourth field; four
|
|
2997
3524
|
map directly. Network/image-bearing CSS values and palettes longer than four are rejected.
|
|
2998
3525
|
- **Geometry** — Source starts at the leading chrome; Confluence meets from the corners; Horizon
|
|
2999
3526
|
forms a shallow top band; Diagonal crosses the surface; Edge preserves a neutral centre; Curtain
|
|
3000
|
-
descends as four elongated fields
|
|
3527
|
+
descends as four elongated fields; Mesh binds four fields with a wash in the middle; Ribbon hangs
|
|
3528
|
+
two arcs of light from above the top edge; Bloom rises from below the bottom edge. All are
|
|
3529
|
+
ordinary CSS gradients, written into `--zx-aurora-image`.
|
|
3530
|
+
- **Motion** — `drift` lets the field breathe while two lights wander across it; `flow` turns a disc
|
|
3531
|
+
of colour slowly behind it. For either, Aurora adds one `<span class="zx-aurora__motion"
|
|
3532
|
+
aria-hidden="true">` as the target's first child, clipped to the surface, and moves its layers by
|
|
3533
|
+
transform alone, so nothing repaints. `--zx-aurora-duration` (18s) sets the pace. Readers who ask
|
|
3534
|
+
for reduced motion see the static field.
|
|
3001
3535
|
- **Lifecycle** — `destroy()` removes an owned root or restores every original attribute and child
|
|
3002
|
-
of an enhanced target. Content is never rebuilt when a setter changes the effect
|
|
3536
|
+
of an enhanced target. Content is never rebuilt when a setter changes the effect; `setMotion()`
|
|
3537
|
+
adds or removes only the motion element.
|
|
3003
3538
|
- **Accessibility** — the light field is pointer-transparent and purely decorative. Forced-colour
|
|
3004
3539
|
and reduced-transparency preferences remove it entirely.
|
|
3005
3540
|
<!-- /doc -->
|
|
@@ -3159,7 +3694,9 @@ complete, or errored. It promotes the markup the checkout and record wizards use
|
|
|
3159
3694
|
Advancing past a step marks it complete automatically, and only steps the `clickable` policy allows
|
|
3160
3695
|
are rendered as real buttons — the rest are not focusable at all. A horizontal rail fills the width
|
|
3161
3696
|
it is given: the labels keep their own width and the connectors stretch to take the slack, wrapping
|
|
3162
|
-
onto more lines only when the container is too narrow to hold them.
|
|
3697
|
+
onto more lines only when the container is too narrow to hold them. A wrapped row ends at its last
|
|
3698
|
+
step: no connector runs on from it to the container's edge. The component marks that step with
|
|
3699
|
+
`data-row-end` as the layout changes.
|
|
3163
3700
|
|
|
3164
3701
|
- **Options** — `steps: [{name, title, description?, optional?, disabled?}]`, `active` (defaults to
|
|
3165
3702
|
the first enabled step), `orientation: 'horizontal'|'vertical'`, `clickable:
|
|
@@ -3308,16 +3845,48 @@ pager.on('change', async ({ detail }) => {
|
|
|
3308
3845
|
|
|
3309
3846
|
In `mode: 'loadmore'` each `change` is one `binding.loadMore()`, which appends.
|
|
3310
3847
|
|
|
3311
|
-
|
|
3312
|
-
|
|
3313
|
-
|
|
3314
|
-
|
|
3315
|
-
|
|
3316
|
-
|
|
3317
|
-
|
|
3318
|
-
|
|
3848
|
+
**Fitting the page.** `pageSize: 'auto'` (and `'auto'` among `pageSizes`, shown as "Auto (14)")
|
|
3849
|
+
shows as many rows as fit `viewport`, the element the rows scroll in, below its sticky `thead`. It
|
|
3850
|
+
measures again whenever the viewport or its content changes size — a window, a drawer, the row height,
|
|
3851
|
+
a table stacking into cards — and keeps the page's first row on the new page. A Zx Table is
|
|
3852
|
+
measured by its first body row, anything else by `--zx-row-height`; `rowHeight`, `perRow` (a card
|
|
3853
|
+
grid's columns) and `reserve` take numbers or functions of the viewport for other content. Call
|
|
3854
|
+
`refit()` after swapping what the viewport shows.
|
|
3855
|
+
|
|
3856
|
+
**Auto-load.** `autoLoad: true` turns paging into infinite scroll: the next page loads by itself
|
|
3857
|
+
when the end of the viewport (or, without one, the pager) comes within `autoLoadMargin` pixels —
|
|
3858
|
+
half the viewport by default. `showAutoLoad: true` adds an Auto-load switch, so the reader chooses;
|
|
3859
|
+
switching between paging and appending returns to page 1. Load more stays as the keyboard's way on.
|
|
3860
|
+
Disable the pager while a page is in flight and enable it when the rows land; auto-load waits:
|
|
3861
|
+
|
|
3862
|
+
```js
|
|
3863
|
+
const pager = new Pagination(footer, { pageSize: 'auto', pageSizes: ['auto', 25, 50], viewport: list, showAutoLoad: true });
|
|
3864
|
+
pager.on('change', async ({ detail }) => {
|
|
3865
|
+
pager.disable();
|
|
3866
|
+
// Appending adds one page; paging shows one; restarting an appending list shows all loaded so far.
|
|
3867
|
+
const from = detail.append || detail.mode === 'pages' ? detail.offset : 0;
|
|
3868
|
+
const rows = await fetchRows(from, detail.offset + detail.pageSize - from);
|
|
3869
|
+
if (detail.append) table.addData(rows); else table.setData(rows);
|
|
3870
|
+
pager.enable();
|
|
3871
|
+
});
|
|
3872
|
+
```
|
|
3873
|
+
|
|
3874
|
+
- **Options** — `page: 1`, `pageSize: 25` (or `'auto'`), `total: 0`, `pageSizes: [25, 50, 100]`
|
|
3875
|
+
(may include `'auto'`), `siblings: 1`, `boundaries: 1`, `showPageSize: true`, `showSummary: true`
|
|
3876
|
+
(renders "26–50 of 312"), `mode: 'pages'|'loadmore'`, `autoLoad: false`, `showAutoLoad: false`,
|
|
3877
|
+
`viewport: null` (element, selector, or function), `rowHeight`, `perRow: 1`, `reserve`,
|
|
3878
|
+
`minPageSize: 5`, `maxPageSize: 200`, `autoLoadMargin: null`, `disabled: false`.
|
|
3879
|
+
- **Methods** — `setPage(n)`, `setTotal(n)`, `setPageSize(n|'auto')`, `setState({page, pageSize,
|
|
3880
|
+
total}, {silent})`, `setAutoLoad(on, {silent})`, `refit()`, `getState()` → `{page, pageSize,
|
|
3881
|
+
total, pages, offset, auto, autoLoad, mode}`, `enable()`/`disable()`, `destroy()`.
|
|
3882
|
+
- **Events** — `change {page, pageSize, offset, total, pages, auto, autoLoad, mode, reason,
|
|
3883
|
+
append}`, where `reason` is `page`, `pageSize`, `fit`, `more`, `scroll`, `mode`, or `state`, and
|
|
3884
|
+
`append` means "add rows `offset … offset + pageSize` after the shown ones" (otherwise show rows
|
|
3885
|
+
`offset …` while paging, `0 … page × pageSize` while appending). `autoload {autoLoad}` when the
|
|
3886
|
+
switch flips.
|
|
3319
3887
|
- **Also exported** — `paginationRange({page, pages, siblings, boundaries})` → `Array<number|'…'>`,
|
|
3320
|
-
the pure page-window calculation,
|
|
3888
|
+
the pure page-window calculation, and `fitPageSize({available, rowHeight, perRow, reserve, min,
|
|
3889
|
+
max})` → the fitted size (0 when nothing can be measured), both usable on their own.
|
|
3321
3890
|
- **Semantics** — `<nav aria-label="Pagination">`; the current page carries `aria-current="page"`;
|
|
3322
3891
|
previous/next are labelled icon buttons that go `disabled` at the ends; the ellipses are
|
|
3323
3892
|
`aria-hidden` spans, not buttons.
|
|
@@ -3363,6 +3932,11 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
|
|
|
3363
3932
|
`header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
|
|
3364
3933
|
`moreLabel` (by default the `appSidebar.more` message), and `renderIcon(item, context)`. Icon values may also be names,
|
|
3365
3934
|
nodes, components, or factories.
|
|
3935
|
+
- **Agents** — an item's `agent` (AgentAvatar options, or `true`) draws the destination as an
|
|
3936
|
+
agent: an `AgentAvatar` in place of its icon, in the tree, on the rail and in flyouts, sized by
|
|
3937
|
+
the icon slot, `name` defaulting to the label. It is drawn at rest and flat, at the small level of
|
|
3938
|
+
detail whatever the slot measures — the activity is the face and the dot, never motion — and the activity's word joins the control's accessible name, with the
|
|
3939
|
+
count when there is one ("Ledger, Needs you (1)"). Redraw with `setItems()` when it changes.
|
|
3366
3940
|
- **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
|
|
3367
3941
|
disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
|
|
3368
3942
|
rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
|
|
@@ -3461,7 +4035,10 @@ bar.setBadge('mail', 8);
|
|
|
3461
4035
|
pinned, unpinned ones are under "All modules" only), `group` (the catalogue heading), and
|
|
3462
4036
|
`description`. Children are the module's menu. A `section` at the top level heads its modules:
|
|
3463
4037
|
a caption over them while names are printed beside the tiles, a short rule between groups on an
|
|
3464
|
-
icon strip or bar, and their group in the catalogue.
|
|
4038
|
+
icon strip or bar, and their group in the catalogue. `agent` (AgentAvatar options, or `true`)
|
|
4039
|
+
draws the module as an agent: its `AgentAvatar` at the size of the tile in place of the tile,
|
|
4040
|
+
whatever the `appearance`, at rest, with the activity's word in the tile's accessible name
|
|
4041
|
+
("Ledger, Needs you (2)"); `tone` and `color` then do not apply.
|
|
3465
4042
|
- **Options** — `items`, `active` (a module or anything in a module's menu),
|
|
3466
4043
|
`orientation: 'vertical'|'horizontal'`, `side`, `appearance: 'tint'|'solid'|'plain'` (the glyph
|
|
3467
4044
|
on a tint of the module colour; the solid identity tile; monochrome glyphs),
|
|
@@ -3613,7 +4190,9 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
|
|
|
3613
4190
|
its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
|
|
3614
4191
|
"Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
|
|
3615
4192
|
(`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
|
|
4193
|
+
initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an agent author with
|
|
4194
|
+
`face` (`{seed, tone, body, eyes, material}` or `true`) is drawn as its generated `AgentAvatar`,
|
|
4195
|
+
with the author's `activity` — `face` wins over `icon`; an `approval`'s
|
|
3617
4196
|
`editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
|
|
3618
4197
|
drawn later; `sourceIcons` is handed to every `SourceList`.
|
|
3619
4198
|
- **Placeholders** — a `{type: 'zx-placeholder', id, author?, lines?}` item stands for something
|
|
@@ -3671,7 +4250,9 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
|
|
|
3671
4250
|
Draws a server's AI SDK UI message stream (the response header `x-vercel-ai-ui-message-stream: v1`;
|
|
3672
4251
|
`UI_MESSAGE_STREAM_VERSION` is the version implemented) in a thread. The application keeps the
|
|
3673
4252
|
request, the event source, retries, and authentication: it strips the `data: ` framing and the
|
|
3674
|
-
`[DONE]` sentinel, and hands each parsed part to `handle()`.
|
|
4253
|
+
`[DONE]` sentinel, and hands each parsed part to `handle()`. Authors are drawn from the thread's own
|
|
4254
|
+
`authors`: an agent given a `face` there is drawn as its AgentAvatar in every item the stream
|
|
4255
|
+
writes, and the stream can never set or change one.
|
|
3675
4256
|
|
|
3676
4257
|
```js
|
|
3677
4258
|
const stream = connectUiMessageStream(thread, {
|
|
@@ -3765,7 +4346,9 @@ for await (const part of parsedParts(response)) stream.handle(part);
|
|
|
3765
4346
|
|
|
3766
4347
|
`connectAgUi()` draws an [AG-UI](https://docs.ag-ui.com) event stream in a thread. It implements
|
|
3767
4348
|
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()}`.
|
|
4349
|
+
transport, retries and authentication — and returns `{handle(event), state(), destroy()}`. As with
|
|
4350
|
+
the UI message stream, faces come from the thread's own `authors`, never from the events, and a
|
|
4351
|
+
`runStatus` given an `agent` keeps it while the run's states change its expression.
|
|
3769
4352
|
|
|
3770
4353
|
```js
|
|
3771
4354
|
const status = new RunStatus(null, { compact: true });
|
|
@@ -3863,7 +4446,9 @@ in `src/components/surface/catalog.js` and `validate.js`, importable on a server
|
|
|
3863
4446
|
`catalog` (a narrowed catalog; the full one by default), `token: null` (the application's opaque
|
|
3864
4447
|
string, at most 512 characters, copied unchanged into every reply), `reply: null` (a stored reply:
|
|
3865
4448
|
the surface starts as its receipt), `labelledBy: null` (the id of a title shown by a host),
|
|
3866
|
-
`chartAdapter
|
|
4449
|
+
`chartAdapter` (draws `chart` nodes: a shared `SvgChartAdapter` by default, offering each chart's
|
|
4450
|
+
data table behind a toggle; pass another adapter to draw with it, or `null` to draw none and show
|
|
4451
|
+
each chart's data table instead), `msg`.
|
|
3867
4452
|
- **Methods** — `apply(op)`, `write(chunk)` (operation lines in chunks), `end()` (the stream is
|
|
3868
4453
|
over), `getValues()`, `getErrors()`, `cancel(reason)`, `supersede()`, `focus()`, `toDocument()`,
|
|
3869
4454
|
`getReply()`, `destroy()`.
|
|
@@ -3876,6 +4461,17 @@ in `src/components/surface/catalog.js` and `validate.js`, importable on a server
|
|
|
3876
4461
|
disabled. A node that fails while drawing shows the same line beside the rest of the surface, and
|
|
3877
4462
|
is reported as `draw-failed`. One operation costs what it touches: a `data` operation redraws only
|
|
3878
4463
|
the nodes bound to the path it changed.
|
|
4464
|
+
- **Catalog and profiles** — every node in `CATALOG` carries `use` (one sentence: when to pick it)
|
|
4465
|
+
and `avoid` (one sentence naming the node or intent to use instead); the guide `surfacePrompt()`
|
|
4466
|
+
writes both under each node, and leaves out an `avoid` whose alternative the catalog lacks.
|
|
4467
|
+
`PROFILES` names four nested sets: `answer` (a `show` surface of `text`, `heading`, `list`,
|
|
4468
|
+
`callout`, `figures`, `table`, `stat`, `badge`, `chart`, `code`, `link`, `ref`, `empty`, `stack`,
|
|
4469
|
+
`columns` and `group`), `ask` (adds the `ask`, `choose` and `confirm` intents with `fields` and
|
|
4470
|
+
`choice`), `review` (adds the `review` intent with `diff`) and `full` (everything, also `quote`
|
|
4471
|
+
and `questionnaire`). `narrowCatalog(CATALOG, { profile })` starts from one, and `intents` and
|
|
4472
|
+
`nodes` narrow within it; `surfaceSchema()`, `surfaceTools()` and `surfacePrompt()` take the same
|
|
4473
|
+
`profile` option, and leaving it out keeps the whole catalog. Give the model the narrowest
|
|
4474
|
+
profile that does the job: `answer` costs well under half the prompt and tools of `full`.
|
|
3879
4475
|
- **Limits** — 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 50 fields,
|
|
3880
4476
|
64 choices, 8 actions, 1 MB of data, and 100,000 table cells across all tables, each `$data`
|
|
3881
4477
|
binding counted where it is used. What is over a limit is dropped and reported, and the table
|
|
@@ -3999,8 +4595,10 @@ announces nothing itself; the thread the run belongs to announces its milestones
|
|
|
3999
4595
|
sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
|
|
4000
4596
|
(local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
|
|
4001
4597
|
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
|
-
`
|
|
4598
|
+
`tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`, `agent`
|
|
4599
|
+
(`{seed?, name?, tone?, body?, eyes?, material?}` or `true`: the agent's face before the state,
|
|
4600
|
+
working while it runs, looking up while it waits, blocked when blocked or failed, at rest
|
|
4601
|
+
otherwise; the compact pill leaves it out), `actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
|
|
4004
4602
|
`now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
|
|
4005
4603
|
labels).
|
|
4006
4604
|
- **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
|
|
@@ -4048,7 +4646,8 @@ the application, which owns the conversation and the transport.
|
|
|
4048
4646
|
`queue: false`, `queueLimit: 10` (see Queue),
|
|
4049
4647
|
`disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
|
|
4050
4648
|
`maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
|
|
4051
|
-
description?, icon?}]` or `
|
|
4649
|
+
description?, icon?, agent?}]` (`agent`: AgentAvatar options or `true` draws the item as its still
|
|
4650
|
+
face instead of the icon, with an activity's word in the option's name) or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
|
|
4052
4651
|
`tools: []` (`[{id, label, icon, pressed?, expanded?, controls?, disabled?}]` — `pressed` makes a
|
|
4053
4652
|
toggle, `expanded`/`controls` a disclosure; see Tools), `icons: {}` (`attach`, `commands` glyphs),
|
|
4054
4653
|
`context: [{id, label,
|
|
@@ -4186,7 +4785,9 @@ into the record of what was decided, by whom, and when. The card never acts on i
|
|
|
4186
4785
|
the answer, and the application carries it out.
|
|
4187
4786
|
|
|
4188
4787
|
- **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
|
|
4189
|
-
'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `
|
|
4788
|
+
'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `agent: null` (the asking
|
|
4789
|
+
agent's AgentAvatar face in place of the tile — `{seed?, name?, tone?, body?, eyes?, material?}`
|
|
4790
|
+
or `true`; it looks up at you while the request waits and rests once answered), `headingLevel: 3`,
|
|
4190
4791
|
`status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
|
|
4191
4792
|
amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
|
|
4192
4793
|
is accepted for `content`, as the thread model spells it), `fields: Record<string,
|
|
@@ -4205,7 +4806,7 @@ the answer, and the application carries it out.
|
|
|
4205
4806
|
the values. `changed` names the fields this save changed. `editedKeys` is the union the card
|
|
4206
4807
|
will list (null when it lists every field), so the application can store it with the record.
|
|
4207
4808
|
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`,
|
|
4809
|
+
- **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`, `agent`,
|
|
4209
4810
|
`details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
|
|
4210
4811
|
place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
|
|
4211
4812
|
now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
|
|
@@ -4299,7 +4900,8 @@ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
|
|
|
4299
4900
|
otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
|
|
4300
4901
|
`handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
|
|
4301
4902
|
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
|
|
4903
|
+
model, and an agent author with `face` as its still `AgentAvatar` — and its own label moves to
|
|
4904
|
+
the meta line.
|
|
4303
4905
|
- **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
|
|
4304
4906
|
(`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
|
|
4305
4907
|
`<button>`. A step's links are buttons beside its row, never inside it, so no control holds
|
|
@@ -4348,7 +4950,9 @@ a thumbnail, or any other remote resource.
|
|
|
4348
4950
|
### Core helpers
|
|
4349
4951
|
|
|
4350
4952
|
- **Component** — the base class: `on`/`off`/`once`/`emit`, `listen`, `toElement`, `msg`,
|
|
4351
|
-
`destroy`, and the static `Component.from(el)`.
|
|
4953
|
+
`destroy`, and the static `Component.from(el)`. Options are merged over the class's
|
|
4954
|
+
`static defaults`; a key passed as `undefined` keeps its default (also inside `msg`), `null`
|
|
4955
|
+
overrides it. `msg(key, ...args)` always returns text: the
|
|
4352
4956
|
instance's `msg` option (a `{[lang]: {…}}` table for the active language, then flat keys), else
|
|
4353
4957
|
the host translator, else the class's built-in `msg` defaults, else the default English
|
|
4354
4958
|
catalogue, and only then the key itself; `%1`, `%2`, … are filled from `args`.
|
|
@@ -4362,7 +4966,7 @@ a thumbnail, or any other remote resource.
|
|
|
4362
4966
|
newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
|
|
4363
4967
|
triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
|
|
4364
4968
|
these functions globally or compose them into their own UI and routing layer.
|
|
4365
|
-
- **Icons** — `icon(name, {size, label})`, `icons`, and `ICON_SIZE` (one size per role); see the
|
|
4969
|
+
- **Icons** — `icon(name, {size, label})`, `icons`, `iconAliases`, `iconNames()`, and `ICON_SIZE` (one size per role); see the
|
|
4366
4970
|
Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
|
|
4367
4971
|
- **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
|
|
4368
4972
|
`{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
|
|
@@ -4405,7 +5009,12 @@ registerIcons({ anchor: ['0 0 24 24', 'M12 6v16…', 'stroke'] }); // an outlin
|
|
|
4405
5009
|
domains configured in the Font Awesome account.
|
|
4406
5010
|
- `useFontAwesome(opts)` / `useBuiltinIcons()` / `configureIcons(opts)` / `getIconConfig()` —
|
|
4407
5011
|
switch or read the renderer without touching the network.
|
|
4408
|
-
- `iconNames()` lists every
|
|
5012
|
+
- `iconNames()` lists every name `icon()` renders as an inline glyph: the bundled set, the glyphs
|
|
5013
|
+
added with `registerIcons()`, and the aliases. A bare name that is not in the list renders the
|
|
5014
|
+
placeholder. `icons` is the bundled table and `iconAliases` the frozen `alias → bundled name`
|
|
5015
|
+
table. An alias is listed beside the glyph it draws, so the list holds more names than glyphs;
|
|
5016
|
+
for one entry per glyph, as in an icon gallery, leave them out:
|
|
5017
|
+
`iconNames().filter((name) => !Object.hasOwn(iconAliases, name))`.
|
|
4409
5018
|
- `registerIcons(map)` adds or replaces inline glyphs. `[viewBox, path]` is a filled shape — the
|
|
4410
5019
|
form Font Awesome path data comes in. `[viewBox, path, 'stroke']` is an outline drawn with the
|
|
4411
5020
|
bundled pen; its stroke scales with the view box, so a 24-unit outline set such as Lucide renders
|
|
@@ -4423,6 +5032,10 @@ is how a state such as a set star or a liked heart is shown without a second gly
|
|
|
4423
5032
|
**Names decide their own renderer.** A bare name (`'check'`) follows the active provider, and the
|
|
4424
5033
|
built-in names are translated to their Font Awesome counterparts (`x` → `fa-xmark`, `search` →
|
|
4425
5034
|
`fa-magnifying-glass`, `warning` → `fa-triangle-exclamation`, …), so component code never changes.
|
|
5035
|
+
A bare name may also be an alias, under either renderer: `archive` → `box-archive`, `edit` →
|
|
5036
|
+
`pen-to-square`, `settings` → `gear`, `clear` → `x`, `checked` → `check`, `question` → `info`,
|
|
5037
|
+
`range` → `filter`, `fields` → `list`, `grid` → `table-cells-large`. A glyph an application
|
|
5038
|
+
registered under the alias name itself wins over the alias, which is also how an alias is changed.
|
|
4426
5039
|
Prefixes override: `'fa:user'`, `'fas:user'`/`'regular:user'`/`'duotone:user'`/`'thin:user'`,
|
|
4427
5040
|
`'kit:zeyos-notes'` (custom kit icons), `'builtin:check'` (force the inline SVG). A literal class
|
|
4428
5041
|
list — `'fa-sharp fa-solid fa-user'` — is used verbatim. Unknown names under Font Awesome are
|
|
@@ -4954,7 +5567,10 @@ in component CSS.
|
|
|
4954
5567
|
properties for restyling one component without touching its internals. Each falls back to the
|
|
4955
5568
|
semantic token it replaces, so setting none of them changes nothing:
|
|
4956
5569
|
`--zx-table-header-bg`, `--zx-table-row-hover-bg`, `--zx-table-row-selected-bg`,
|
|
4957
|
-
`--zx-table-border-color`, `--zx-
|
|
5570
|
+
`--zx-table-border-color`, `--zx-table-pin-bg` (the opaque base of pinned columns; the header
|
|
5571
|
+
background unless set), `--zx-button-radius`, `--zx-panel-header-bg`, `--zx-message-offset`
|
|
5572
|
+
(the distance of floating messages from the viewport edge; `--zx-space-4` unless set).
|
|
5573
|
+
`--zx-chart-min-block-size` is public as well, with a fixed 220px default rather than a token.
|
|
4958
5574
|
Reach for the least specific override that works: a global semantic token first, one of these
|
|
4959
5575
|
second, an internal selector never. Component CSS declares many other `--zx-<component>-*`
|
|
4960
5576
|
properties — those are internal geometry, not API, and will change without notice.
|