@zeyos/zx 5.7.1 → 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 +296 -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 +19 -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 +13 -2
- 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 +11 -0
- 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 +7 -0
- 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 +18 -4
- 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/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 +2998 -451
- 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 +948 -48
- package/dist/zx.esm.js +7432 -3408
- package/dist/zx.esm.min.js +26 -26
- package/dist/zx.global.js +7432 -3408
- package/dist/zx.global.min.js +26 -26
- package/dist/zx.layered.css +950 -48
- 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 +3122 -528
- 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 +697 -100
- 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/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.js +46 -17
- package/src/components/checklist/field-adapter.js +4 -1
- 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 +22 -30
- 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 +70 -25
- 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 +2 -1
- 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 +27 -8
- 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/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 +51 -10
- package/src/core/keyboard.js +83 -9
- package/src/core/messages.js +3 -0
- package/src/core/position.js +2 -2
- 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
|
|
@@ -841,7 +1045,9 @@ yet: an optional decorative icon, a headline, a sentence, and optional actions.
|
|
|
841
1045
|
paragraph rather than a heading, so dropping one into a Table's empty slot or a Panel body never
|
|
842
1046
|
disturbs the page's heading outline.
|
|
843
1047
|
|
|
844
|
-
- **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`,
|
|
845
1051
|
`description`, `actions: [Element | buttonOptions]`, `size: 'md'|'sm'`, `align: 'center'|'start'`.
|
|
846
1052
|
- **Methods** — none. `emptyState(options)` → `HTMLDivElement`, which you own and place yourself.
|
|
847
1053
|
- **Events** — none; action buttons carry their own `onclick`.
|
|
@@ -940,11 +1146,17 @@ a stronger border, the text colour); only the check glyph, the mark, keeps the a
|
|
|
940
1146
|
|
|
941
1147
|
Switch (`role="switch"`, `aria-checked`).
|
|
942
1148
|
|
|
943
|
-
- **Options** — `checked: false`, `value: true`, `label: null`, `
|
|
1149
|
+
- **Options** — `checked: false`, `value: true`, `label: null`, `hideLabel: false`,
|
|
1150
|
+
`disabled: false`.
|
|
944
1151
|
- **Label** — start-aligned and wrapping like text within the available width, the track level
|
|
945
|
-
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.
|
|
946
1157
|
- **Methods** — `get()`, `set(checked, {silent})`, `toggle()`, `getValue()` (returns
|
|
947
|
-
`options.value` when on, `false` when off), `
|
|
1158
|
+
`options.value` when on, `false` when off), `setLabel(label)` (null removes it),
|
|
1159
|
+
`enable()`/`disable()`.
|
|
948
1160
|
- **Events** — `change {checked, value}`.
|
|
949
1161
|
- **Keyboard** — Space/Enter.
|
|
950
1162
|
<!-- /doc -->
|
|
@@ -977,8 +1189,10 @@ permissions, recent-history/cache policy, and the route or command ultimately in
|
|
|
977
1189
|
`false`), and `scope` to explicitly select an element whose nearest Zx theme scope owns the launcher.
|
|
978
1190
|
- **Items** — `{id, label, description?, keywords?, group?, icon?, badge?, hint?, shortcut?, keys?,
|
|
979
1191
|
value?, href?, target?, invoke?, pinned?, disabled?, kind?, current?, when?, groupOrder?,
|
|
980
|
-
itemOrder?, items?, placeholder?, order?}`. `icon` accepts a bundled icon name, Node, or
|
|
981
|
-
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;
|
|
982
1196
|
non-link commands may provide an application-owned `invoke` callback. Malformed and executable
|
|
983
1197
|
URL schemes are stripped; a descriptor with no safe link or callback is disabled. `hint` is muted
|
|
984
1198
|
text at the end of the row (a current value, a project); `shortcut: ['⌘', 'K']` (or Button's
|
|
@@ -1093,6 +1307,64 @@ and the component is decorative by default so adjacent identity text is not anno
|
|
|
1093
1307
|
status, not the account's accessible name; supply `statusLabel` when it conveys information.
|
|
1094
1308
|
<!-- /doc -->
|
|
1095
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
|
+
|
|
1096
1368
|
<!-- doc:entity-ref -->
|
|
1097
1369
|
### EntityRef
|
|
1098
1370
|
|
|
@@ -1173,7 +1445,9 @@ One chronological activity entry. It owns actor/avatar anatomy, semantic time, s
|
|
|
1173
1445
|
attachments, and actions; the application owns posting, reactions, permissions, routing,
|
|
1174
1446
|
persistence, and sanitization before any rich content becomes a Node.
|
|
1175
1447
|
|
|
1176
|
-
- **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`,
|
|
1177
1451
|
`timestamp`, `timeLabel`, `metadata`, `attachments`, `actions`, `kind`, and
|
|
1178
1452
|
`headingLevel: 1..6`. Content slots accept text, Nodes, or Components and never parse HTML.
|
|
1179
1453
|
- **Actions** — Elements pass through; descriptors accept
|
|
@@ -1532,12 +1806,14 @@ to a hidden textarea when the async Clipboard API is unavailable or denied.
|
|
|
1532
1806
|
|
|
1533
1807
|
#### copyButton()
|
|
1534
1808
|
|
|
1535
|
-
- **Signature** — `copyButton({text, label, title, feedback, feedbackDuration, size, kind, oncopy})`
|
|
1809
|
+
- **Signature** — `copyButton({text, label, title, feedback, feedbackDuration, size, kind, oncopy, signal})`
|
|
1536
1810
|
→ `HTMLButtonElement`.
|
|
1537
1811
|
- **Options** — `text: ''` — a string, or **a function returning one**, which is what a button
|
|
1538
1812
|
beside a live value needs so the copy is never stale; `label: ''` (empty renders an icon-only
|
|
1539
1813
|
ghost button), `title`, `feedback` (by default the `copy.copy` and `copy.copied` messages, and `null` gives no text), `feedbackDuration: 2000`,
|
|
1540
|
-
`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).
|
|
1541
1817
|
- **Events** — `oncopy(text, copied)` is called for every attempt; `copied` is `false` when the
|
|
1542
1818
|
clipboard refused the write, and the button then stays untouched rather than claiming a copy
|
|
1543
1819
|
that did not happen.
|
|
@@ -1657,24 +1933,63 @@ use `TimePicker` or `DateTimeBox`.
|
|
|
1657
1933
|
|
|
1658
1934
|
Floating toasts come from statics; `new Message(target)` gives an inline, non-floating area with
|
|
1659
1935
|
the same `.show()`. The toast region is `role="status"`/`aria-live` (`role="alert"` for errors).
|
|
1660
|
-
|
|
1661
|
-
|
|
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**).
|
|
1662
1941
|
|
|
1663
1942
|
- **Statics** — `Message.info/success/warning/error(msg, opts)`,
|
|
1664
|
-
`Message.show(msg, { kind, timeout=4000, closable, scope? })` → `{ close() }`,
|
|
1665
|
-
`Message.progress(text, {scope?})` → `{ update(pct, text?), done(), fail(text?) }
|
|
1666
|
-
|
|
1667
|
-
|
|
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`.
|
|
1668
1960
|
- **Region lifecycle** — a floating region is created on the first toast for its scope and removed
|
|
1669
1961
|
when its last toast closes. One whose host was emptied or left the document is replaced on the
|
|
1670
1962
|
next toast rather than reused, and a scope that is itself detached falls back to the focused
|
|
1671
|
-
element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's
|
|
1672
|
-
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
|
|
1673
1965
|
Sheet is open the region moves into the topmost one, so toasts and their actions stay visible
|
|
1674
1966
|
and clickable above it, and moves back when it closes. A press on a toast dismisses no open menu
|
|
1675
1967
|
or drawer.
|
|
1676
1968
|
- **Per-message options** — `kind: 'info'`, `timeout`, `closable: true`, `maxVisible: 5` (extras
|
|
1677
|
-
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)`.
|
|
1678
1993
|
- **Action** — `action: { label, onclick?, kind? }` renders one small button (`.zx-btn`,
|
|
1679
1994
|
`data-size="sm"`, secondary unless `kind` is `primary`/`danger`/`ghost`) in a toast or an inline
|
|
1680
1995
|
message; activating it runs `onclick(event)` and closes the message. A message with an action
|
|
@@ -1707,6 +2022,11 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
|
|
|
1707
2022
|
A programmatic `close()` raises no `cancel`. Escape is handled by Zx rather than by the browser's
|
|
1708
2023
|
close request, so preventing it holds however often the key is pressed; a handler that calls
|
|
1709
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.
|
|
1710
2030
|
<!-- /doc -->
|
|
1711
2031
|
|
|
1712
2032
|
<!-- doc:dialog -->
|
|
@@ -1716,6 +2036,8 @@ Structured modal: a header with title and close button, a body, and footer butto
|
|
|
1716
2036
|
|
|
1717
2037
|
- **Options** — `title`, `size: 'sm'|'md'|'lg'|number`,
|
|
1718
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()`.
|
|
1719
2041
|
- **Methods** — `setTitle()`, `setContent()`, `setButtons()`,
|
|
1720
2042
|
`addView(key, { content, buttons? })`, `showView(key)`.
|
|
1721
2043
|
- **Statics returning Promises** — `Dialog.alert({ title, message, okLabel })`,
|
|
@@ -1742,8 +2064,9 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
|
|
|
1742
2064
|
|
|
1743
2065
|
- **Options** — `side: 'end'` (`'start' | 'end' | 'top' | 'bottom'`, logical), `modal: true`
|
|
1744
2066
|
(`true | 'trap-focus' | false`), `backdrop: 'dim'` (`'dim' | 'blur' | 'none'`), `size: null`
|
|
1745
|
-
(CSS length or px number, applied to whichever axis `side` implies), `closeButton: true
|
|
1746
|
-
|
|
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`
|
|
1747
2070
|
(defaults to `true` here, unlike Modal), `destroyOnClose`, `scope`.
|
|
1748
2071
|
- **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
|
|
1749
2072
|
`isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
|
|
@@ -1773,7 +2096,9 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
|
|
|
1773
2096
|
dialog while open, so it stays usable above it, closes when the dialog closes, and goes back to
|
|
1774
2097
|
its theme scope when it closes. Their top-layer backdrop is
|
|
1775
2098
|
explicitly transparent and non-filtering; `backdrop` is meaningful only when `modal` is `true`.
|
|
1776
|
-
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.
|
|
1777
2102
|
- **Resizing and detents** — `resizable` makes the inner edge draggable between `min` and `max`.
|
|
1778
2103
|
`snap` gives it detents: a number at or below 1 is a fraction of the viewport along the sheet's
|
|
1779
2104
|
axis, anything larger is pixels, and a string is any CSS length (`'320px'`, `'90%'`). With
|
|
@@ -1893,8 +2218,11 @@ A button that opens a `role="menu"`.
|
|
|
1893
2218
|
- `href`, `target`, and `rel` render a genuine safe native link, preserving modifier clicks and
|
|
1894
2219
|
targets. Executable URL schemes are rejected; `_blank` receives `noopener noreferrer` by
|
|
1895
2220
|
default.
|
|
1896
|
-
- `role: 'menuitemcheckbox'|'menuitemradio'` with `checked` exposes an APG checked action.
|
|
1897
|
-
|
|
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.
|
|
1898
2226
|
- `{type: 'choice', label, value, options: [{value, label, icon|glyph}], onselect(value, entry,
|
|
1899
2227
|
menu)}` draws a setting chosen in place — a theme, a layout: the label, then a small segmented
|
|
1900
2228
|
group of `menuitemradio` options named by it. Choosing an option checks it and calls
|
|
@@ -1957,7 +2285,7 @@ parked at the pointer, so it flips near a viewport edge like every other floatin
|
|
|
1957
2285
|
<!-- doc:tooltip -->
|
|
1958
2286
|
### Tooltip
|
|
1959
2287
|
|
|
1960
|
-
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.
|
|
1961
2289
|
|
|
1962
2290
|
- **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
|
|
1963
2291
|
(`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
|
|
@@ -1996,7 +2324,8 @@ Sortable, selectable, sticky-header data table. `fr` widths fill the container w
|
|
|
1996
2324
|
widths scroll horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
|
|
1997
2325
|
range select.
|
|
1998
2326
|
|
|
1999
|
-
- **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,
|
|
2000
2329
|
type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
|
|
2001
2330
|
render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
|
|
2002
2331
|
`sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
|
|
@@ -2011,6 +2340,38 @@ range select.
|
|
|
2011
2340
|
the selected row of a `selectable: 'single'` table is the current record of a master–detail list
|
|
2012
2341
|
and takes the neutral `--zx-color-bg-current` fill. Sortable and plain headers set the same type,
|
|
2013
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.
|
|
2014
2375
|
- **Columns in the DOM** — every header and body cell carries `data-column="<id>"` in every mode,
|
|
2015
2376
|
read-only included, so a table can be styled per column. A column with `label: ''` (icons,
|
|
2016
2377
|
actions) keeps a blank header named by `ariaLabel`, or by its id; `ariaLabel` also names the
|
|
@@ -2025,6 +2386,11 @@ range select.
|
|
|
2025
2386
|
- **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
|
|
2026
2387
|
`selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
|
|
2027
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.
|
|
2028
2394
|
- **Keyboard** — an *interactive* table implements the WAI-ARIA APG **Grid** pattern
|
|
2029
2395
|
(`role="grid"`, with `aria-multiselectable` for `selectable: 'multi'`), or the **Treegrid**
|
|
2030
2396
|
pattern with `hierarchy`. A table is interactive when it is `selectable`, has `editMode` or
|
|
@@ -2066,7 +2432,13 @@ range select.
|
|
|
2066
2432
|
editing/mutation APIs stay flat and ID-based. Orphans become roots, cycles render once, local
|
|
2067
2433
|
sort reorders siblings without mixing levels, and growing counts visible rows. Use
|
|
2068
2434
|
`toggleRow()`, `expandRow()`, `collapseRow()`, `expandAll()`, `collapseAll()`, and
|
|
2069
|
-
`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
|
|
2070
2442
|
or clicking the row.
|
|
2071
2443
|
- **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set),
|
|
2072
2444
|
plus `editTrigger: 'double'|'single'` (Table defaults to double; Grid defaults to single).
|
|
@@ -2137,7 +2509,8 @@ range select.
|
|
|
2137
2509
|
height for all, following `--zx-row-height`, so rows of differing height are not supported, and
|
|
2138
2510
|
long text is cut short with an ellipsis rather than wrapped. Column widths cannot follow content
|
|
2139
2511
|
that is not drawn, so the layout is fixed: `auto` columns share the width evenly, and a column that
|
|
2140
|
-
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
|
|
2141
2514
|
the drawn rows only.
|
|
2142
2515
|
- **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
|
|
2143
2516
|
label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
|
|
@@ -2305,7 +2678,8 @@ cards, advisory work-in-progress limits, and equivalent pointer/programmatic/key
|
|
|
2305
2678
|
and action controls reveal on hover/focus/selection/grab, and remain visible on touch devices.
|
|
2306
2679
|
- **Assignees** — `assignees` faces (a name, names, or `{name, src?, initials?, tone?}`) are drawn
|
|
2307
2680
|
like a small Avatar: initials on the tint `avatarTone(name)` picks, so a person has the same
|
|
2308
|
-
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.
|
|
2309
2683
|
- **Movement boundary** — `recordmove {record,id,from,to,column,swimlane,limitExceeded}` is
|
|
2310
2684
|
cancelable and fires before a commit/request; either the component event or bubbling
|
|
2311
2685
|
`zx-recordmove` mirror may veto it. `accept` is a hard eligibility gate; WIP is visual advice.
|
|
@@ -2328,7 +2702,9 @@ without forking its implementation, so sorting, selection, hierarchy, responsive
|
|
|
2328
2702
|
editable cells/rows, loading, events, and teardown keep the Table contract.
|
|
2329
2703
|
|
|
2330
2704
|
- **Constructor** — `new Grid(target, tableOptions)` accepts the complete `Table` API and defaults
|
|
2331
|
-
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.
|
|
2332
2708
|
- **Preset** — `Grid.BillingItems(target, options)` supplies an editable hierarchical billing
|
|
2333
2709
|
schema for item, quantity, unit, unit price, currency, and line total. It enables single-click
|
|
2334
2710
|
editing, hierarchy, row reorder handles, and the column visibility chooser. It returns a `Grid`.
|
|
@@ -2344,33 +2720,111 @@ editable cells/rows, loading, events, and teardown keep the Table contract.
|
|
|
2344
2720
|
<!-- /doc -->
|
|
2345
2721
|
|
|
2346
2722
|
<!-- doc:chart -->
|
|
2347
|
-
### Chart and `ChartJsAdapter`
|
|
2723
|
+
### Chart, `SvgChartAdapter` and `ChartJsAdapter`
|
|
2348
2724
|
|
|
2349
2725
|
An accessible, engine-neutral chart host. Zx renders state, canvas, semantic data summary, tokens,
|
|
2350
|
-
and lifecycle; an
|
|
2351
|
-
|
|
2352
|
-
|
|
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
|
+
```
|
|
2353
2739
|
|
|
2354
2740
|
- **Options** — `adapter`, `type: 'bar'`, `data`, engine-specific `chartOptions`, `label`,
|
|
2355
|
-
`description`, `summary: 'hidden'|'visible'`, `
|
|
2356
|
-
`aspectRatio: '16 / 9'`.
|
|
2741
|
+
`description`, `summary: 'hidden'|'visible'`, `summaryFormat: null`, `loading`,
|
|
2742
|
+
loading/empty/error text, `aspectRatio: '16 / 9'`, and `fill: false`.
|
|
2357
2743
|
- **Methods** — `setData()`, `setType()`, `update(chartOptions)`, `setAdapter()`, `setLoading()`,
|
|
2358
|
-
`setError()`, `clearError()`, `
|
|
2744
|
+
`setError()`, `clearError()`, `setLabel()`, `setDescription()`, `setSummary()`,
|
|
2745
|
+
`setAspectRatio()`, `setFill()`, `resize()`, `refreshTheme()`, `getInstance()`, `destroy()`.
|
|
2359
2746
|
- **Events** — `ready {instance}`, `update {data, type}`, `select {datasetIndex, index, dataset,
|
|
2360
2747
|
label, value, nativeEvent}`, and `error {error}`.
|
|
2361
|
-
- **
|
|
2362
|
-
|
|
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
|
|
2363
2787
|
resources and must not retain the component after teardown. `reducedMotion` is true under the
|
|
2364
2788
|
system preference or inside a `data-zx-motion="reduced"` region, and an adapter must then turn its
|
|
2365
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.
|
|
2366
2808
|
- **`ChartJsAdapter`** — construct it with a Chart.js constructor or namespace:
|
|
2367
2809
|
`new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development dependency and copies it to its
|
|
2368
2810
|
self-hosted vendor assets during the website build; `package.json` has no runtime dependencies and application builds explicitly choose how
|
|
2369
2811
|
the engine is loaded. Under reduced motion it sets `animation: false`, over any animation the
|
|
2370
|
-
application configured.
|
|
2371
|
-
|
|
2372
|
-
|
|
2373
|
-
|
|
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.
|
|
2374
2828
|
<!-- /doc -->
|
|
2375
2829
|
|
|
2376
2830
|
<!-- doc:calendar -->
|
|
@@ -2385,8 +2839,10 @@ windowed loader.
|
|
|
2385
2839
|
- **Options** — `events`, `date`, `view: 'month'`, `views: ['agenda','day','week','month','year']`,
|
|
2386
2840
|
`locale`, `weekStart: 1`, `weekNumbers: true`, `workweek: false`, `agendaDays: 14`,
|
|
2387
2841
|
`slotDuration: 30`, `slotMinTime: 0`, `slotMaxTime: 1440`, `scrollTime: 480`, `eventLimit: 3`,
|
|
2388
|
-
`selectable: false`, `editable: false`, `eventStartEditable
|
|
2389
|
-
`
|
|
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)`.
|
|
2390
2846
|
- **Messages** — every key is namespaced `calendar.*`: `calendar.today`, `calendar.previous`,
|
|
2391
2847
|
`calendar.next`, `calendar.new`, `calendar.agenda`/`day`/`week`/`month`/`year` (the view
|
|
2392
2848
|
switch), `calendar.viewSwitch`, `calendar.label` (the root's name), `calendar.loading`,
|
|
@@ -2431,7 +2887,9 @@ windowed loader.
|
|
|
2431
2887
|
text announces the edit and its proposed times.
|
|
2432
2888
|
- **ZeyOS binding** — `zeyosCalendar()` maps current appointment occurrence rows (`ID`, `name`,
|
|
2433
2889
|
`location`, `color`, `datefrom`, `dateto`, and association text). `calendarEventToZeyosPatch()`
|
|
2434
|
-
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
|
|
2435
2893
|
the requested window; recurrence rules, DAV synchronization, permissions, and routes therefore
|
|
2436
2894
|
remain in ZeyOS instead of being reimplemented in core.
|
|
2437
2895
|
<!-- /doc -->
|
|
@@ -2552,7 +3010,9 @@ mutate the caller's data.
|
|
|
2552
3010
|
- **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
|
|
2553
3011
|
`expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
|
|
2554
3012
|
(tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
|
|
2555
|
-
(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`,
|
|
2556
3016
|
`rowActions: (node) => actions`, `moreLabel`. Unset, `label`, `emptyText` and `moreLabel` read the
|
|
2557
3017
|
`tree.label`, `tree.noItems` and `tree.more` messages; `tree.empty` still wins over `emptyText`, and
|
|
2558
3018
|
`emptyText: null` shows no text.
|
|
@@ -2697,10 +3157,37 @@ Beyond the built-in field types, these widget types wrap whole components, used
|
|
|
2697
3157
|
`registerFieldAdapters()`, which `src/index.js` calls by default.
|
|
2698
3158
|
|
|
2699
3159
|
- `zxselect` (Select), `checklist` (Checklist), `tagpicker` (TagPicker), `number` (NumberField),
|
|
2700
|
-
`rating` (Rating).
|
|
2701
|
-
- `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).
|
|
2702
3163
|
- `valuelist` (ValueList), `multivalueeditor` (MultiValueEditor), `upload` (FieldUpload),
|
|
2703
|
-
`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`.
|
|
2704
3191
|
<!-- /doc -->
|
|
2705
3192
|
|
|
2706
3193
|
<!-- doc:code-editor -->
|
|
@@ -2712,17 +3199,32 @@ surface for structured text — templates, queries, configuration — while rich
|
|
|
2712
3199
|
stays a separate policy decision.
|
|
2713
3200
|
|
|
2714
3201
|
- **Options** — `value`, `name`, `language` (shown to the reader and exposed as data),
|
|
2715
|
-
`label`, `placeholder`, `rows` (clamped 2–100), `indent` (inserted by Tab, removed by
|
|
2716
|
-
Shift+Tab), `wrap: 'off'|'soft'|'hard'`,
|
|
2717
|
-
`status` (the line/column readout).
|
|
2718
|
-
- **Methods** — `setValue()
|
|
2719
|
-
|
|
2720
|
-
|
|
2721
|
-
|
|
2722
|
-
|
|
2723
|
-
|
|
2724
|
-
or
|
|
2725
|
-
|
|
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.
|
|
2726
3228
|
<!-- /doc -->
|
|
2727
3229
|
|
|
2728
3230
|
<!-- doc:questionnaire -->
|
|
@@ -2993,6 +3495,11 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
|
|
|
2993
3495
|
decoration and saying the delta twice is worse than saying it once.
|
|
2994
3496
|
- **The element follows the behaviour** — `href` renders an `<a>`, `onclick` without `href` a
|
|
2995
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.
|
|
2996
3503
|
- **`loading: true` renders a skeleton shaped like the tile**, not a spinner.
|
|
2997
3504
|
|
|
2998
3505
|
Nothing in it assumes a fixed set of buckets or a fixed label: the content of a dashboard tile
|
|
@@ -3007,18 +3514,27 @@ the target in place: it does not wrap, replace, or relocate the surface's conten
|
|
|
3007
3514
|
own routing, overlays, or interaction. Its gradients sit behind the target's children, so raised
|
|
3008
3515
|
Cards and other Liquid Glass surfaces can pick up the underlying colour naturally.
|
|
3009
3516
|
|
|
3010
|
-
- **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'`,
|
|
3517
|
+
- **Options** — `preset: 'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'|'mesh'|'ribbon'|'bloom'`,
|
|
3011
3518
|
`colors: []` (zero to four concrete CSS colours),
|
|
3012
|
-
`intensity: 'subtle'|'balanced'|'vivid'`.
|
|
3013
|
-
- **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)`.
|
|
3014
3522
|
- **Palette** — an empty list uses semantic accent, info, success, and warning colours. One colour
|
|
3015
3523
|
fills all four fields; two alternate; three repeat the second colour in the fourth field; four
|
|
3016
3524
|
map directly. Network/image-bearing CSS values and palettes longer than four are rejected.
|
|
3017
3525
|
- **Geometry** — Source starts at the leading chrome; Confluence meets from the corners; Horizon
|
|
3018
3526
|
forms a shallow top band; Diagonal crosses the surface; Edge preserves a neutral centre; Curtain
|
|
3019
|
-
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.
|
|
3020
3535
|
- **Lifecycle** — `destroy()` removes an owned root or restores every original attribute and child
|
|
3021
|
-
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.
|
|
3022
3538
|
- **Accessibility** — the light field is pointer-transparent and purely decorative. Forced-colour
|
|
3023
3539
|
and reduced-transparency preferences remove it entirely.
|
|
3024
3540
|
<!-- /doc -->
|
|
@@ -3178,7 +3694,9 @@ complete, or errored. It promotes the markup the checkout and record wizards use
|
|
|
3178
3694
|
Advancing past a step marks it complete automatically, and only steps the `clickable` policy allows
|
|
3179
3695
|
are rendered as real buttons — the rest are not focusable at all. A horizontal rail fills the width
|
|
3180
3696
|
it is given: the labels keep their own width and the connectors stretch to take the slack, wrapping
|
|
3181
|
-
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.
|
|
3182
3700
|
|
|
3183
3701
|
- **Options** — `steps: [{name, title, description?, optional?, disabled?}]`, `active` (defaults to
|
|
3184
3702
|
the first enabled step), `orientation: 'horizontal'|'vertical'`, `clickable:
|
|
@@ -3327,16 +3845,48 @@ pager.on('change', async ({ detail }) => {
|
|
|
3327
3845
|
|
|
3328
3846
|
In `mode: 'loadmore'` each `change` is one `binding.loadMore()`, which appends.
|
|
3329
3847
|
|
|
3330
|
-
|
|
3331
|
-
|
|
3332
|
-
|
|
3333
|
-
|
|
3334
|
-
|
|
3335
|
-
|
|
3336
|
-
|
|
3337
|
-
|
|
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.
|
|
3338
3887
|
- **Also exported** — `paginationRange({page, pages, siblings, boundaries})` → `Array<number|'…'>`,
|
|
3339
|
-
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.
|
|
3340
3890
|
- **Semantics** — `<nav aria-label="Pagination">`; the current page carries `aria-current="page"`;
|
|
3341
3891
|
previous/next are labelled icon buttons that go `disabled` at the ends; the ellipses are
|
|
3342
3892
|
`aria-hidden` spans, not buttons.
|
|
@@ -3382,6 +3932,11 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
|
|
|
3382
3932
|
`header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
|
|
3383
3933
|
`moreLabel` (by default the `appSidebar.more` message), and `renderIcon(item, context)`. Icon values may also be names,
|
|
3384
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.
|
|
3385
3940
|
- **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
|
|
3386
3941
|
disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
|
|
3387
3942
|
rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
|
|
@@ -3480,7 +4035,10 @@ bar.setBadge('mail', 8);
|
|
|
3480
4035
|
pinned, unpinned ones are under "All modules" only), `group` (the catalogue heading), and
|
|
3481
4036
|
`description`. Children are the module's menu. A `section` at the top level heads its modules:
|
|
3482
4037
|
a caption over them while names are printed beside the tiles, a short rule between groups on an
|
|
3483
|
-
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.
|
|
3484
4042
|
- **Options** — `items`, `active` (a module or anything in a module's menu),
|
|
3485
4043
|
`orientation: 'vertical'|'horizontal'`, `side`, `appearance: 'tint'|'solid'|'plain'` (the glyph
|
|
3486
4044
|
on a tint of the module colour; the solid identity tile; monochrome glyphs),
|
|
@@ -3632,7 +4190,9 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
|
|
|
3632
4190
|
its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
|
|
3633
4191
|
"Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
|
|
3634
4192
|
(`action {item, action: id}`); an author with an `icon` is drawn as a tinted tile instead of
|
|
3635
|
-
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
|
|
3636
4196
|
`editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
|
|
3637
4197
|
drawn later; `sourceIcons` is handed to every `SourceList`.
|
|
3638
4198
|
- **Placeholders** — a `{type: 'zx-placeholder', id, author?, lines?}` item stands for something
|
|
@@ -3690,7 +4250,9 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
|
|
|
3690
4250
|
Draws a server's AI SDK UI message stream (the response header `x-vercel-ai-ui-message-stream: v1`;
|
|
3691
4251
|
`UI_MESSAGE_STREAM_VERSION` is the version implemented) in a thread. The application keeps the
|
|
3692
4252
|
request, the event source, retries, and authentication: it strips the `data: ` framing and the
|
|
3693
|
-
`[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.
|
|
3694
4256
|
|
|
3695
4257
|
```js
|
|
3696
4258
|
const stream = connectUiMessageStream(thread, {
|
|
@@ -3784,7 +4346,9 @@ for await (const part of parsedParts(response)) stream.handle(part);
|
|
|
3784
4346
|
|
|
3785
4347
|
`connectAgUi()` draws an [AG-UI](https://docs.ag-ui.com) event stream in a thread. It implements
|
|
3786
4348
|
AG-UI `AG_UI_VERSION` (`'1.0'`). It takes events already parsed — the application keeps the
|
|
3787
|
-
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.
|
|
3788
4352
|
|
|
3789
4353
|
```js
|
|
3790
4354
|
const status = new RunStatus(null, { compact: true });
|
|
@@ -3882,7 +4446,9 @@ in `src/components/surface/catalog.js` and `validate.js`, importable on a server
|
|
|
3882
4446
|
`catalog` (a narrowed catalog; the full one by default), `token: null` (the application's opaque
|
|
3883
4447
|
string, at most 512 characters, copied unchanged into every reply), `reply: null` (a stored reply:
|
|
3884
4448
|
the surface starts as its receipt), `labelledBy: null` (the id of a title shown by a host),
|
|
3885
|
-
`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`.
|
|
3886
4452
|
- **Methods** — `apply(op)`, `write(chunk)` (operation lines in chunks), `end()` (the stream is
|
|
3887
4453
|
over), `getValues()`, `getErrors()`, `cancel(reason)`, `supersede()`, `focus()`, `toDocument()`,
|
|
3888
4454
|
`getReply()`, `destroy()`.
|
|
@@ -3895,6 +4461,17 @@ in `src/components/surface/catalog.js` and `validate.js`, importable on a server
|
|
|
3895
4461
|
disabled. A node that fails while drawing shows the same line beside the rest of the surface, and
|
|
3896
4462
|
is reported as `draw-failed`. One operation costs what it touches: a `data` operation redraws only
|
|
3897
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`.
|
|
3898
4475
|
- **Limits** — 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 50 fields,
|
|
3899
4476
|
64 choices, 8 actions, 1 MB of data, and 100,000 table cells across all tables, each `$data`
|
|
3900
4477
|
binding counted where it is used. What is over a limit is dropped and reported, and the table
|
|
@@ -4018,8 +4595,10 @@ announces nothing itself; the thread the run belongs to announces its milestones
|
|
|
4018
4595
|
sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
|
|
4019
4596
|
(local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
|
|
4020
4597
|
it is a number), `tokens: [in, out]|number|null` (the pair, or the total as one number),
|
|
4021
|
-
`tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`,
|
|
4022
|
-
`
|
|
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'`,
|
|
4023
4602
|
`now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
|
|
4024
4603
|
labels).
|
|
4025
4604
|
- **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
|
|
@@ -4067,7 +4646,8 @@ the application, which owns the conversation and the transport.
|
|
|
4067
4646
|
`queue: false`, `queueLimit: 10` (see Queue),
|
|
4068
4647
|
`disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
|
|
4069
4648
|
`maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
|
|
4070
|
-
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[]`,
|
|
4071
4651
|
`tools: []` (`[{id, label, icon, pressed?, expanded?, controls?, disabled?}]` — `pressed` makes a
|
|
4072
4652
|
toggle, `expanded`/`controls` a disclosure; see Tools), `icons: {}` (`attach`, `commands` glyphs),
|
|
4073
4653
|
`context: [{id, label,
|
|
@@ -4205,7 +4785,9 @@ into the record of what was decided, by whom, and when. The card never acts on i
|
|
|
4205
4785
|
the answer, and the application carries it out.
|
|
4206
4786
|
|
|
4207
4787
|
- **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
|
|
4208
|
-
'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`,
|
|
4209
4791
|
`status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
|
|
4210
4792
|
amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
|
|
4211
4793
|
is accepted for `content`, as the thread model spells it), `fields: Record<string,
|
|
@@ -4224,7 +4806,7 @@ the answer, and the application carries it out.
|
|
|
4224
4806
|
the values. `changed` names the fields this save changed. `editedKeys` is the union the card
|
|
4225
4807
|
will list (null when it lists every field), so the application can store it with the record.
|
|
4226
4808
|
Prevent an answer to refuse or defer it, then settle the card with `setStatus()`.
|
|
4227
|
-
- **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`,
|
|
4809
|
+
- **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`, `agent`,
|
|
4228
4810
|
`details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
|
|
4229
4811
|
place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
|
|
4230
4812
|
now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
|
|
@@ -4318,7 +4900,8 @@ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
|
|
|
4318
4900
|
otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
|
|
4319
4901
|
`handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
|
|
4320
4902
|
avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
|
|
4321
|
-
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.
|
|
4322
4905
|
- **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
|
|
4323
4906
|
(`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
|
|
4324
4907
|
`<button>`. A step's links are buttons beside its row, never inside it, so no control holds
|
|
@@ -4367,7 +4950,9 @@ a thumbnail, or any other remote resource.
|
|
|
4367
4950
|
### Core helpers
|
|
4368
4951
|
|
|
4369
4952
|
- **Component** — the base class: `on`/`off`/`once`/`emit`, `listen`, `toElement`, `msg`,
|
|
4370
|
-
`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
|
|
4371
4956
|
instance's `msg` option (a `{[lang]: {…}}` table for the active language, then flat keys), else
|
|
4372
4957
|
the host translator, else the class's built-in `msg` defaults, else the default English
|
|
4373
4958
|
catalogue, and only then the key itself; `%1`, `%2`, … are filled from `args`.
|
|
@@ -4381,7 +4966,7 @@ a thumbnail, or any other remote resource.
|
|
|
4381
4966
|
newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
|
|
4382
4967
|
triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
|
|
4383
4968
|
these functions globally or compose them into their own UI and routing layer.
|
|
4384
|
-
- **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
|
|
4385
4970
|
Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
|
|
4386
4971
|
- **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
|
|
4387
4972
|
`{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
|
|
@@ -4424,7 +5009,12 @@ registerIcons({ anchor: ['0 0 24 24', 'M12 6v16…', 'stroke'] }); // an outlin
|
|
|
4424
5009
|
domains configured in the Font Awesome account.
|
|
4425
5010
|
- `useFontAwesome(opts)` / `useBuiltinIcons()` / `configureIcons(opts)` / `getIconConfig()` —
|
|
4426
5011
|
switch or read the renderer without touching the network.
|
|
4427
|
-
- `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))`.
|
|
4428
5018
|
- `registerIcons(map)` adds or replaces inline glyphs. `[viewBox, path]` is a filled shape — the
|
|
4429
5019
|
form Font Awesome path data comes in. `[viewBox, path, 'stroke']` is an outline drawn with the
|
|
4430
5020
|
bundled pen; its stroke scales with the view box, so a 24-unit outline set such as Lucide renders
|
|
@@ -4442,6 +5032,10 @@ is how a state such as a set star or a liked heart is shown without a second gly
|
|
|
4442
5032
|
**Names decide their own renderer.** A bare name (`'check'`) follows the active provider, and the
|
|
4443
5033
|
built-in names are translated to their Font Awesome counterparts (`x` → `fa-xmark`, `search` →
|
|
4444
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.
|
|
4445
5039
|
Prefixes override: `'fa:user'`, `'fas:user'`/`'regular:user'`/`'duotone:user'`/`'thin:user'`,
|
|
4446
5040
|
`'kit:zeyos-notes'` (custom kit icons), `'builtin:check'` (force the inline SVG). A literal class
|
|
4447
5041
|
list — `'fa-sharp fa-solid fa-user'` — is used verbatim. Unknown names under Font Awesome are
|
|
@@ -4973,7 +5567,10 @@ in component CSS.
|
|
|
4973
5567
|
properties for restyling one component without touching its internals. Each falls back to the
|
|
4974
5568
|
semantic token it replaces, so setting none of them changes nothing:
|
|
4975
5569
|
`--zx-table-header-bg`, `--zx-table-row-hover-bg`, `--zx-table-row-selected-bg`,
|
|
4976
|
-
`--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.
|
|
4977
5574
|
Reach for the least specific override that works: a global semantic token first, one of these
|
|
4978
5575
|
second, an internal selector never. Component CSS declares many other `--zx-<component>-*`
|
|
4979
5576
|
properties — those are internal geometry, not API, and will change without notice.
|