@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
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# Surface — `new Surface(target, options)` / `openSurface()` / `elicit()` / `surfaceText()`
|
|
2
|
+
|
|
3
|
+
Interface an agent composes as JSON — a rich answer, or a dialog asking the person something — validated and drawn with the library’s own components.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/surface · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Interface an agent composes as JSON — a rich answer, or a dialog asking the person something —
|
|
8
|
+
validated and drawn with the library's own components. A surface declares one `intent`, which fixes
|
|
9
|
+
its frame, default actions and reply, and composes its body from catalog nodes laid out by id. The
|
|
10
|
+
format, the node reference and the rules a model reads are in `docs/agent-surfaces.md`; the catalog
|
|
11
|
+
functions (`narrowCatalog`, `surfaceSchema`, `surfaceTools`, `surfacePrompt`) and the validator are
|
|
12
|
+
in `src/components/surface/catalog.js` and `validate.js`, importable on a server.
|
|
13
|
+
|
|
14
|
+
- **Options** — `document` (a whole surface; leave it out to stream), `policy`, `resolve: {ref,
|
|
15
|
+
link, asset, entities}`, `authors`, `userInitiated: false`, `headingLevel: 3`, `locale`,
|
|
16
|
+
`catalog` (a narrowed catalog; the full one by default), `token: null` (the application's opaque
|
|
17
|
+
string, at most 512 characters, copied unchanged into every reply), `reply: null` (a stored reply:
|
|
18
|
+
the surface starts as its receipt), `labelledBy: null` (the id of a title shown by a host),
|
|
19
|
+
`chartAdapter` (draws `chart` nodes: a shared `SvgChartAdapter` by default, offering each chart's
|
|
20
|
+
data table behind a toggle; pass another adapter to draw with it, or `null` to draw none and show
|
|
21
|
+
each chart's data table instead), `msg`.
|
|
22
|
+
- **Methods** — `apply(op)`, `write(chunk)` (operation lines in chunks), `end()` (the stream is
|
|
23
|
+
over), `getValues()`, `getErrors()`, `cancel(reason)`, `supersede()`, `focus()`, `toDocument()`,
|
|
24
|
+
`getReply()`, `destroy()`.
|
|
25
|
+
- **Events** — `reply {reply}` exactly once, `error {errors}` each time new problems are found,
|
|
26
|
+
`change {name, value}`, `ready` at the first drawn state, `end`.
|
|
27
|
+
- **Streaming** — every line is validated before it is drawn. A child that has not arrived is a
|
|
28
|
+
skeleton line, and every action but Cancel stays disabled until the surface's `end`. What is
|
|
29
|
+
invalid is dropped and reported; an unknown node, or one outside a narrowed catalog, draws "This
|
|
30
|
+
part could not be shown". A surface whose stream ends without its `end` keeps its actions
|
|
31
|
+
disabled. A node that fails while drawing shows the same line beside the rest of the surface, and
|
|
32
|
+
is reported as `draw-failed`. One operation costs what it touches: a `data` operation redraws only
|
|
33
|
+
the nodes bound to the path it changed.
|
|
34
|
+
- **Catalog and profiles** — every node in `CATALOG` carries `use` (one sentence: when to pick it)
|
|
35
|
+
and `avoid` (one sentence naming the node or intent to use instead); the guide `surfacePrompt()`
|
|
36
|
+
writes both under each node, and leaves out an `avoid` whose alternative the catalog lacks.
|
|
37
|
+
`PROFILES` names four nested sets: `answer` (a `show` surface of `text`, `heading`, `list`,
|
|
38
|
+
`callout`, `figures`, `table`, `stat`, `badge`, `chart`, `code`, `link`, `ref`, `empty`, `stack`,
|
|
39
|
+
`columns` and `group`), `ask` (adds the `ask`, `choose` and `confirm` intents with `fields` and
|
|
40
|
+
`choice`), `review` (adds the `review` intent with `diff`) and `full` (everything, also `quote`
|
|
41
|
+
and `questionnaire`). `narrowCatalog(CATALOG, { profile })` starts from one, and `intents` and
|
|
42
|
+
`nodes` narrow within it; `surfaceSchema()`, `surfaceTools()` and `surfacePrompt()` take the same
|
|
43
|
+
`profile` option, and leaving it out keeps the whole catalog. Give the model the narrowest
|
|
44
|
+
profile that does the job: `answer` costs well under half the prompt and tools of `full`.
|
|
45
|
+
- **Limits** — 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 50 fields,
|
|
46
|
+
64 choices, 8 actions, 1 MB of data, and 100,000 table cells across all tables, each `$data`
|
|
47
|
+
binding counted where it is used. What is over a limit is dropped and reported, and the table
|
|
48
|
+
budget holds while a surface streams; rows past it draw the fallback.
|
|
49
|
+
- **Actions** — the intent's defaults (`submit`, `confirm`, `approve`/`reject`) or the surface's own,
|
|
50
|
+
plus Cancel for `ask`, `choose`, `confirm` and `questionnaire`, and for a `review` left without
|
|
51
|
+
its `reject`. The ids `cancel` and `dismiss` are reserved: an action using one is dropped and
|
|
52
|
+
reported, as is any action of a `questionnaire`'s own. Escape closes whatever waits for an answer
|
|
53
|
+
(`cancel`, or `dismiss` for a `show` surface with actions), except while it closes something
|
|
54
|
+
inside the surface (an open picker, an expanded list) or another handler took it. The answering
|
|
55
|
+
defaults (`submit`, `confirm`, `approve`) and an own action with `kind: 'primary'` check the
|
|
56
|
+
visible inputs first, move focus to the first invalid one, and send the values; any other own
|
|
57
|
+
action replies at once with `values: {}`. With several primary actions the one pressed answers,
|
|
58
|
+
and Enter in a field presses the first. A single `choice` must be picked before an answering
|
|
59
|
+
action replies; a `multiple` one may be empty. A questionnaire's `next` that names a dropped step,
|
|
60
|
+
or can lead back to its own step, is dropped and reported.
|
|
61
|
+
- **Policy** — `policy(action, surface)` returns `'allow'`, `'confirm'` (a confirmation Dialog),
|
|
62
|
+
`'type-to-confirm'` (`Dialog.confirm({confirmText})`) or `'deny'` (the action is not drawn, and
|
|
63
|
+
the reply lists it under `removed`), or `{level, confirmText?, message?}`. Supply `confirmText`
|
|
64
|
+
for `type-to-confirm`: without it the person types the fixed word "confirm"
|
|
65
|
+
(`surface.typeToConfirm`), never text from the surface. A questionnaire's own Submit is put to the
|
|
66
|
+
policy up front, as `submit`; denied, it is hidden and reported. The policy is synchronous:
|
|
67
|
+
nothing waits for it, so a Promise denies, like a policy that throws. Anything else counts as
|
|
68
|
+
`confirm`. Nothing in a surface can lower it: `kind: 'danger'` is presentation only, and
|
|
69
|
+
confirmation keys in a surface are dropped.
|
|
70
|
+
- **Reply** — `{zx: 'reply/1', surface, action, key, values, confirmation, at, token?, removed?,
|
|
71
|
+
reason?}`. `key` is `<surface>#<action>`; `confirmation` is `clicked`, `typed` or `null`;
|
|
72
|
+
`reason` says why a closing reply (`cancel`, `dismiss`) was sent: `cancelled`, `escape`,
|
|
73
|
+
`closed`, `superseded`, `stopped`, `destroyed`, or the application's. Submit and every action
|
|
74
|
+
reply, and so do Cancel, Escape, `cancel()`, `supersede()` and destroying an unanswered surface
|
|
75
|
+
(`dismiss`), whatever happens while its receipt is drawn. When its run stops, the application
|
|
76
|
+
calls `surface.cancel('stopped')`. A surface
|
|
77
|
+
whose `begin` never validated still replies once: `surface` is the id it was given when that was
|
|
78
|
+
a valid id, `null` otherwise. A reply records what the page did; the server runs its policy again
|
|
79
|
+
before it acts.
|
|
80
|
+
- **Conditions** — a node's `visible` and a schema property's `x-zx.visible` are evaluated as values
|
|
81
|
+
change. A hidden input keeps what was typed, is not required, and is left out of `getValues()`
|
|
82
|
+
and the reply. A node that hides while it holds the focus hands it to the input whose value hid
|
|
83
|
+
it.
|
|
84
|
+
- **Receipt** — answered, the surface carries `data-state="answered"`: inputs become read-only
|
|
85
|
+
displays of what was answered, tables stay with their selected rows marked, and the actions give
|
|
86
|
+
way to a verdict line. A restored surface (`reply`) shows what that reply answered.
|
|
87
|
+
`surfaceText(document, reply)` gives the same receipt as plain text, with choice titles rather
|
|
88
|
+
than raw values and never a hidden input or step, whatever the reply carries.
|
|
89
|
+
- **Field types** — a schema property's `x-zx.field` draws through `Field`. The surface registers the
|
|
90
|
+
types it needs only where nothing draws them yet, so an adapter the application registered with
|
|
91
|
+
`Field.register()` stays.
|
|
92
|
+
- **Placement** — `openSurface(document, {placement, target, …})` resolves with the reply. A sheet
|
|
93
|
+
or a dialog the document asks for is honoured only with `userInitiated`; otherwise the surface goes
|
|
94
|
+
inline into `target`. Closing the sheet or dialog replies `cancel`. A document that cannot begin
|
|
95
|
+
rejects with a `TypeError` (its `errors` attached) before anything opens; given its `reply`, it
|
|
96
|
+
resolves with it at once. `signal` withdraws it: on abort the surface is cancelled with the reason
|
|
97
|
+
`stopped` and the promise resolves that reply — a sheet or dialog closes, an inline surface stays
|
|
98
|
+
as its receipt — and a signal already aborted resolves it without drawing anything. Removing an
|
|
99
|
+
inline `target` is not noticed: abort the signal or destroy the surface so the promise settles.
|
|
100
|
+
- **Elicitation** — `elicit({message, requestedSchema}, options)` draws an `ask` form in a Dialog,
|
|
101
|
+
or inline into `options.target`, and resolves `{action: 'accept', content}`, `{action: 'decline'}`
|
|
102
|
+
or `{action: 'cancel'}`. A schema outside the subset (a nested object, a pattern, …) rejects with
|
|
103
|
+
a `TypeError` naming what is unsupported. The message is drawn as plain text, never as markup;
|
|
104
|
+
the labels resolve through `msg` (by language, then flat), the host translator, then English.
|
|
105
|
+
`options.signal` withdraws the request: it resolves `cancel`.
|
|
106
|
+
- **MCP elicitation** — `elicitationHandler({serverName, authors?, target?, open?, msg?})` returns
|
|
107
|
+
`(params, {signal}?) => Promise<{action, content?}>` for an MCP client to install; `MCP_ELICITATION_VERSION`
|
|
108
|
+
(`'2026-07-28'`) names the revision it implements. Call it with the `params` of an
|
|
109
|
+
`elicitation/create` request, or of each `inputRequests` entry whose `method` is
|
|
110
|
+
`elicitation/create` in an `input_required` result, and send what it resolves back — in
|
|
111
|
+
`inputResponses` under the same key, with `requestState` echoed unchanged. Fields a mode does not
|
|
112
|
+
use, such as an `elicitationId`, are ignored. The byline says "Asked by <server>": the
|
|
113
|
+
`authors[serverName].name` when listed, else `serverName`, which is required. Abort `signal` when
|
|
114
|
+
the request is withdrawn (the server cancelled it, the call timed out, the session closed, or the
|
|
115
|
+
inline `target` was removed): the surface is cancelled, nothing opens, and it resolves `cancel`.
|
|
116
|
+
- Form mode, the default without `mode`, is `elicit()`; a schema outside the subset rejects with
|
|
117
|
+
its `TypeError`, so the client can answer the server with an error. Single and multiple choice
|
|
118
|
+
(`enum`, `oneOf`, `items.enum`, `items.anyOf`) and defaults are supported; the deprecated
|
|
119
|
+
`enumNames` is reported as unsupported.
|
|
120
|
+
- URL mode is a `confirm` surface that asks first: the server's message as plain text, the page's
|
|
121
|
+
host emphasised, its full address, a warning for an internationalised host, and no link. Nothing
|
|
122
|
+
is fetched or opened before the person agrees. Open page opens the address in a new tab with
|
|
123
|
+
`noopener` and `noreferrer`, inside the click, and resolves `{action: 'accept'}`; Decline
|
|
124
|
+
resolves `decline`; Cancel, Escape or closing the dialog resolves `cancel`. The address must be
|
|
125
|
+
an absolute lower-case `https://` URL without credentials, checked and normalised like a surface
|
|
126
|
+
link; anything else rejects with a `TypeError`. `open(url)` replaces the opener: it must open a
|
|
127
|
+
browsing context that cannot reach the application, and `false` or a throw answers `cancel`.
|
|
128
|
+
|
|
129
|
+
```js
|
|
130
|
+
const answer = elicitationHandler({ serverName: 'Orders server' });
|
|
131
|
+
const inputResponses = {};
|
|
132
|
+
for (const [key, request] of Object.entries(result.inputRequests ?? {})) {
|
|
133
|
+
if (request.method === 'elicitation/create') inputResponses[key] = await answer(request.params);
|
|
134
|
+
}
|
|
135
|
+
await client.callTool({ ...call, inputResponses, requestState: result.requestState });
|
|
136
|
+
```
|
|
137
|
+
- **Safety** — no string reaches the page as HTML. Records are drawn through `resolve.ref` as an
|
|
138
|
+
`EntityRef`; links are `https:` only, show their host, and pass `resolve.link`, which may refuse
|
|
139
|
+
them; nothing is loaded from an address the surface gives.
|
|
140
|
+
- **Accessibility** — a surface that asks is a `<form>` labelled by its title, any other a labelled
|
|
141
|
+
region; the title is at `headingLevel` and its `heading` nodes one and two below, up to h6; a chart offers its data table; the byline says
|
|
142
|
+
"Composed by <author>".
|
|
143
|
+
|
|
144
|
+
```js
|
|
145
|
+
const surface = new Surface(null, {
|
|
146
|
+
document, // from the model's show_surface call
|
|
147
|
+
token: issuedToken,
|
|
148
|
+
policy: (action) => (action.tool === 'mail.send' ? 'confirm' : 'allow'),
|
|
149
|
+
resolve: { entities: ['company'], ref: (ref) => ({ id: ref.id, title: names[ref.id] }) },
|
|
150
|
+
onreply: ({ detail }) => sendToolResult(detail.reply)
|
|
151
|
+
});
|
|
152
|
+
```
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Tabbox — APG tabs
|
|
2
|
+
|
|
3
|
+
Manual-activation tabs following the APG pattern: arrow keys move focus, Enter or Space selects, and panels can be built lazily.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tabbox · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Four appearances, all square-cornered. `divided` (the default) sets flat blocks on a muted track,
|
|
8
|
+
split by hairline dividers, above a bordered panel, with the active block lifted onto the panel
|
|
9
|
+
surface. `bracket` outlines folder tabs that fuse into that same panel, the active tab bridging
|
|
10
|
+
the seam. `line` underlines the active tab in the text colour across a full-width rule, for page-
|
|
11
|
+
and section-level navigation. `segmented` renders a compact framed group with the active tab on
|
|
12
|
+
the neutral `--zx-color-bg-current` fill, so the row reads as one control inside a toolbar or card
|
|
13
|
+
header. The active tab is where you are, not a pick: every variant gives it the text colour and a
|
|
14
|
+
semibold label, and none uses the accent. Tab badges are neutral counts, not accent bubbles.
|
|
15
|
+
|
|
16
|
+
`divided` and `bracket` draw the panel box themselves; `line` and `segmented` leave the panel bare
|
|
17
|
+
for the surrounding layout to frame. The boxed variants read `--zx-tabbox-radius` (default `0px`)
|
|
18
|
+
from the component root, so `el.style.setProperty('--zx-tabbox-radius', 'var(--zx-radius-lg)')`
|
|
19
|
+
restores rounded corners without forking the stylesheet.
|
|
20
|
+
|
|
21
|
+
- **Options** — `tabs: [{ name, title, content, icon?, closable?, disabled? }]`, `active`,
|
|
22
|
+
`variant: 'divided'|'bracket'|'line'|'segmented'`, `keepAlive: true`, `label` (the tab list's
|
|
23
|
+
accessible name — give one whenever a page has more than one tab list).
|
|
24
|
+
- **Methods** — `addTab()`, `removeTab()`, `openTab(name)`, `getActive()`, `setTitle()`,
|
|
25
|
+
`setBadge(name, text|null)`, `enableTab()`/`disableTab()`.
|
|
26
|
+
- **Events** — `change {name, previous}` (preventable), `close {name}`.
|
|
27
|
+
- **Behaviour** — a `closable` tab renders a × that closes it on click, and `close` fires for that
|
|
28
|
+
gesture just as it does for Delete. `removeTab()` is the silent programmatic path. Closing the
|
|
29
|
+
active tab activates its neighbour through the usual `change` event, so a `preventDefault()` on
|
|
30
|
+
that change also vetoes the close.
|
|
31
|
+
- **Keyboard** — ArrowLeft/Right and Home/End move focus, Enter/Space activate, Delete closes a
|
|
32
|
+
closable tab. The × is a plain glyph rather than a nested button (buttons cannot nest), so
|
|
33
|
+
keyboard and screen-reader users close through Delete; focus lands on the neighbouring tab.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# TableView and the shared RecordView contract
|
|
2
|
+
|
|
3
|
+
A schema-friendly record view that composes the full Table: one field contract drives sorting, selection, editable cells, visibility, and stable column order.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/table-view · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
**`fieldControls` takes an object.** `true` and `false` behave as they always have; a
|
|
8
|
+
`{label, target}` object names the chooser's trigger and mounts the disclosure into a host
|
|
9
|
+
element — a list toolbar, say — instead of the view's own. `label` omitted resolves
|
|
10
|
+
`recordView.fields`. This is what lets a translated application use the chooser at all: the
|
|
11
|
+
trigger used to be the literal `Fields`, with no way to change it or move it. `TableView`,
|
|
12
|
+
`CardView`, and `KanbanView` all honour `target`.
|
|
13
|
+
|
|
14
|
+
**The chooser is public.** `getFieldControls()` returns the view's field chooser — the shared
|
|
15
|
+
disclosure, or for a `TableView` with `fieldControls: true` its Table's column chooser — and
|
|
16
|
+
`mountFieldControls(target)` moves it into a host element (`null` hands it back). The view keeps
|
|
17
|
+
owning it wherever it sits and removes it on `destroy()`; `ListToolbar.bind()` uses exactly this.
|
|
18
|
+
In the shared chooser the move buttons keep focus on the field they moved (or its other button once
|
|
19
|
+
one end disables), a polite live region announces "Name moved to position 2 of 5"
|
|
20
|
+
(`recordView.fieldMoved`), and Escape closes the disclosure and returns focus to its trigger.
|
|
21
|
+
|
|
22
|
+
`TableView` is the record-oriented entry point above the lower-level `Table`. It extends
|
|
23
|
+
`RecordView` and composes one complete `Table`, so editing, hierarchy, growing, row movement,
|
|
24
|
+
responsive stacking, loading, and advanced table events remain available through `getTable()`.
|
|
25
|
+
|
|
26
|
+
- **Shared fields** — every view accepts `fields: [{id,label,get?,render?,sortValue?,sortable?,
|
|
27
|
+
visible?,duplicate?,type?,view?}]`. Primitive rendered values become text; an explicit Node is
|
|
28
|
+
adopted. `field.view.table` carries Table-only column keys without changing CardView or KanbanView.
|
|
29
|
+
- **Shared options** — `data`, `recordId: 'ID'`, `sort`, `sortMode: 'local'|'server'`,
|
|
30
|
+
`selectable: false|'single'|'multi'`, `selection`, `fieldOrder`, `hiddenFields`,
|
|
31
|
+
`fieldControls: true`, and `emptyText`. At least one field remains visible.
|
|
32
|
+
- **Shared methods** — `setData()`, `addData()`, `updateRecord()`, `removeRecord()`, `getRecord()`,
|
|
33
|
+
`getData()`, field getters/order/visibility methods, `setSort()`/`getSort()`, selection methods,
|
|
34
|
+
`setLoading()`, `getViewState()`, `setViewState()`, `getFieldControls()`, and
|
|
35
|
+
`mountFieldControls(target)`.
|
|
36
|
+
- **Portable state** — `{version:1,fieldOrder,hiddenFields,sort}` is JSON-safe configuration only.
|
|
37
|
+
Records, selection, DOM nodes, rendered values, and callbacks are never serialized. A state from
|
|
38
|
+
one record view may seed another; unknown fields are ignored and new fields append.
|
|
39
|
+
- **TableView composition** — `table: {...}` forwards every advanced Table option, while shared
|
|
40
|
+
fields/data/id/sort/selection/visibility/order win on overlaps. `getTable()` returns the composed
|
|
41
|
+
instance. Row events become shared `recordclick`/`recorddblclick` details.
|
|
42
|
+
- **Events** — `recordclick`, `recorddblclick`, `datachange`, `selectionchange`, `sortchange`,
|
|
43
|
+
`fieldvisibilitychange`, `fieldorderchange`, and `statechange {state,reason}`.
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
# Table
|
|
2
|
+
|
|
3
|
+
A sortable, selectable, editable data table with a sticky header for dense records, transactions, and operational workflows.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/table · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
**Group and section rows.** `rowKind` names the field (or a callback) that classifies a row, and
|
|
8
|
+
`rowKinds` maps a kind to `{span, render, class}`. A `span: true` row renders one
|
|
9
|
+
`<th scope="colgroup">` across every rendered cell — including the selection and reorder columns —
|
|
10
|
+
and carries no others, which is what a heading row in a billing document actually is. Both
|
|
11
|
+
default to null, so a table that sets neither renders exactly as before. While any spanning row is
|
|
12
|
+
present the header sort controls are withheld and `setSort()` is a no-op: sorting a grouped table
|
|
13
|
+
scatters its positions out of their sections, and silently doing so is worse than not offering it.
|
|
14
|
+
The stacked presentation renders the heading alone rather than a row of labelled blanks.
|
|
15
|
+
|
|
16
|
+
Sortable, selectable, sticky-header data table. `fr` widths fill the container while px/auto
|
|
17
|
+
widths scroll horizontally, and multi-select adds a tri-state header checkbox plus Shift+click
|
|
18
|
+
range select.
|
|
19
|
+
|
|
20
|
+
- **Options** — `columns: [{ id, label, ariaLabel?, sortable?, width ('120px'|'2fr'|'auto'),
|
|
21
|
+
minWidth?, pin?: 'start'|'end', group?, align,
|
|
22
|
+
type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
|
|
23
|
+
render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
|
|
24
|
+
`sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
|
|
25
|
+
`stickyHeader: true`, `height`, `virtual: false`, `emptyText`, `rowClass`, `zebra: true`, `variant:
|
|
26
|
+
'default'|'plain'`, `hierarchy: false|{parentId, column?, expanded?}`, `interactive: false`,
|
|
27
|
+
and `label`/`labelledBy`. Locale, currency, unit, and decimals may be row callbacks; values
|
|
28
|
+
remain numbers in row data while display formatting is locale-aware.
|
|
29
|
+
- **Appearance** — the header sits on the table's surface (no band) in the muted text colour at a
|
|
30
|
+
medium weight, sentence case; the sorted column's label takes the text colour beside its arrow.
|
|
31
|
+
Rows are divided by `--zx-color-border-subtle`, the header by the ordinary border, and every cell
|
|
32
|
+
uses tabular figures. Checked rows of a multi-selection keep the accent tint (`--zx-color-bg-selected`);
|
|
33
|
+
the selected row of a `selectable: 'single'` table is the current record of a master–detail list
|
|
34
|
+
and takes the neutral `--zx-color-bg-current` fill. Sortable and plain headers set the same type,
|
|
35
|
+
and the scroll region reserves no scrollbar gutter until the table actually scrolls.
|
|
36
|
+
- **Column widths** — `fr` columns share what the columns with a CSS length leave over, and never
|
|
37
|
+
less than their `minWidth` (a CSS length or a number of pixels, default `'5rem'`; `0` lifts the
|
|
38
|
+
floor). The table takes a minimum width from those floors, so a container too narrow for them
|
|
39
|
+
scrolls the table inline instead of squeezing the `fr` columns to nothing — in a windowed table
|
|
40
|
+
as well. `minWidth` is also honoured on an `auto` column of a table with a fixed layout (one
|
|
41
|
+
with `fr` columns, or `virtual`), where it has no default; a column with a CSS length `width`
|
|
42
|
+
ignores it.
|
|
43
|
+
- **Sticky header** — `stickyHeader: true` sticks the column headers to the top of the table's
|
|
44
|
+
**own scroll region** while its rows scroll. That takes a bounded region: set `height`, or use
|
|
45
|
+
`virtual`, which caps the region at the window height. A table without one grows to the height
|
|
46
|
+
of its rows, never scrolls itself, and its header leaves with the page; to keep a header in view
|
|
47
|
+
while the *page* scrolls, give the table the height of the area it sits in. Header cells sit at
|
|
48
|
+
`z-index: 2` inside the scroll region.
|
|
49
|
+
- **Pinned columns** — `pin: 'start'|'end'` on a column keeps it in view at that inline edge of
|
|
50
|
+
the scroll region while the table scrolls sideways (`position: sticky`, so it follows the
|
|
51
|
+
writing direction). A pinned column stays where the column order puts it and sticks once it
|
|
52
|
+
reaches the edge: declare a `'start'` column before the columns it should stay in front of and
|
|
53
|
+
an `'end'` column after them. Several pinned columns stack in column order, and the row handle
|
|
54
|
+
and selection checkbox columns are pinned along with the first `'start'` column. Give a pinned
|
|
55
|
+
column a `width` or keep it short — what is pinned is taken from the room the others scroll in.
|
|
56
|
+
A cell focused by keyboard scrolls clear of the pinned columns. Pinning is not applied while
|
|
57
|
+
the table is stacked (`responsive`). Pinned cells are opaque and paint the row's fill
|
|
58
|
+
themselves; `--zx-table-pin-bg` sets their base, the header background unless set. Cells carry
|
|
59
|
+
`data-pin="start"|"end"`, and `data-pin-edge` on the column next to the scrolling ones.
|
|
60
|
+
- **Header groups** — `group: 'Label'` on adjacent visible columns (with the same `pin`) gives
|
|
61
|
+
them one shared header cell in a second header row above the column labels: a
|
|
62
|
+
`<th scope="col">` with the right `colspan`, so assistive technology announces the group with
|
|
63
|
+
every cell beneath it. Columns without a `group` have a blank above them. The group row holds
|
|
64
|
+
no controls and takes no part in sorting or keyboard navigation; it counts as a row in
|
|
65
|
+
`aria-rowcount`/`aria-rowindex`. Hiding or reordering columns regroups what is left: a group
|
|
66
|
+
interrupted by another column becomes two cells. It works in plain, hierarchical and windowed
|
|
67
|
+
tables, and sticks with the header.
|
|
68
|
+
- **Columns in the DOM** — every header and body cell carries `data-column="<id>"` in every mode,
|
|
69
|
+
read-only included, so a table can be styled per column. A column with `label: ''` (icons,
|
|
70
|
+
actions) keeps a blank header named by `ariaLabel`, or by its id; `ariaLabel` also names the
|
|
71
|
+
column in the chooser and its cell editors.
|
|
72
|
+
- **`variant: 'plain'`** — for a table inside a card or panel that already draws the box: no outer
|
|
73
|
+
frame, no header band, no zebra, hairline row dividers. Reflected as `data-variant="plain"` on the
|
|
74
|
+
root; TableView passes it through `table: { variant: 'plain' }`.
|
|
75
|
+
- **Methods** — `setData()`, `addData()`, `updateRow(id,row)`, `removeRow(id)`, `getRow(id)`,
|
|
76
|
+
`getData()`, `empty()`, `setSort(id,dir)`, `getSort()`, `clearSort()`, `getSelection()`, `setSelection(ids)`,
|
|
77
|
+
`clearSelection()`, `reveal(id)`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an
|
|
78
|
+
indeterminate top bar, sets `aria-busy`, and is cleared by the next `setData`).
|
|
79
|
+
- **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
|
|
80
|
+
`selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
|
|
81
|
+
`rowclick` fires for Enter on a focused row as well as for a click; `event` is then the keydown.
|
|
82
|
+
A click on a control inside a cell belongs to that control: it raises neither `rowclick` nor
|
|
83
|
+
`rowdblclick` and does not select the row in a `single` selection. A control is a button, link,
|
|
84
|
+
field or `<label>`, an element with a widget role or in the Tab order, editable content, or
|
|
85
|
+
anything marked `data-zx-table-no-edit` — so a Toggle, a menu button or a link rendered into a
|
|
86
|
+
cell needs no `stopPropagation()`. Mark a custom clickable element the same way.
|
|
87
|
+
- **Keyboard** — an *interactive* table implements the WAI-ARIA APG **Grid** pattern
|
|
88
|
+
(`role="grid"`, with `aria-multiselectable` for `selectable: 'multi'`), or the **Treegrid**
|
|
89
|
+
pattern with `hierarchy`. A table is interactive when it is `selectable`, has `editMode` or
|
|
90
|
+
`hierarchy`, sets `interactive: true`, or has a `rowclick`/`rowdblclick` listener attached through
|
|
91
|
+
`on()` or an `onrowclick`/`onrowdblclick` option (attaching one later turns the grid on). A host
|
|
92
|
+
that listens only for the bubbling `zx-rowclick` DOM event passes `interactive: true`. TableView
|
|
93
|
+
always bridges `rowclick` to `recordclick`, so its table is always a grid. Any other table keeps
|
|
94
|
+
plain `<table>` semantics, no grid role, no name unless `label` is given, and no row Tab stop.
|
|
95
|
+
In a grid the rows are one Tab stop with a roving `tabindex`; the row checkboxes and disclosure
|
|
96
|
+
buttons leave the Tab order because the row keys cover them (links and buttons a host renders
|
|
97
|
+
in cells keep theirs). Focus is on rows by default and on cells when `editMode` is set —
|
|
98
|
+
reflected as `data-focus="row"|"cell"` on the root. ArrowUp/ArrowDown move a row,
|
|
99
|
+
ArrowLeft/ArrowRight a cell (cell focus), Home/End go to the first/last row (cell focus:
|
|
100
|
+
first/last cell of the row) and Ctrl+Home/End to the first/last row's corner cell,
|
|
101
|
+
PageUp/PageDown move by the rows visible in the scroll region (10 when the table does not scroll
|
|
102
|
+
itself). Enter activates exactly like a click (`rowclick`; selects in `single`), Enter/F2 on an
|
|
103
|
+
editable cell opens its editor, Space toggles the row's selection when `selectable` (activates
|
|
104
|
+
otherwise), Shift+ArrowUp/Down extends a `multi` selection from its anchor, and Ctrl/Cmd+A
|
|
105
|
+
selects the rows in the DOM — like the header checkbox, not the rows `growing` holds back nor the
|
|
106
|
+
children of collapsed branches. A sort, new data, or a change in expansion starts the anchor
|
|
107
|
+
over. Treegrid: ArrowRight expands a collapsed row, then moves into its first child; ArrowLeft
|
|
108
|
+
collapses an expanded row, then moves to its parent. With cell focus, ArrowLeft from the first
|
|
109
|
+
cell lands on the row and ArrowRight from the row goes back to its first cell. The focused row
|
|
110
|
+
(and column) is kept by id across `setData`, sorting, expansion, growing, and `updateRow`; when
|
|
111
|
+
a collapsed ancestor hides it, the ancestor takes focus, and when it is gone, its neighbour does.
|
|
112
|
+
Focus is only restored when the body had it, and without scrolling, so a polling refresh never
|
|
113
|
+
pulls the page back to the table. An emptied table keeps focus on its frame until rows return.
|
|
114
|
+
Column headers keep their sort buttons in the Tab order rather than joining arrow navigation —
|
|
115
|
+
the one deliberate departure from the APG grid, which puts the header row inside it. Rows and
|
|
116
|
+
cells show an inset `--zx-focus-ring` with a transparent outline that forced colours paint.
|
|
117
|
+
- **Naming** — `label` or `labelledBy` (an element id) names the table; a grid without either is
|
|
118
|
+
named by the `table.label` message (English "Table"), so pass a real name. Row controls are named
|
|
119
|
+
after the row's first cell with text through `table.selectRow` (`Select %1`), `table.expandRow`,
|
|
120
|
+
`table.collapseRow`, and `table.moveRow`; `table.row` (`row %1`) stands in for a row without
|
|
121
|
+
text, and `table.selectAll` names the header checkbox. Sort buttons and selection checkboxes are
|
|
122
|
+
at least 24×24 px targets; the checkbox is drawn so the glyph stays `--zx-space-4` while a
|
|
123
|
+
transparent border makes up the target.
|
|
124
|
+
- **Hierarchy** — flat parent references are projected as an ARIA `treegrid`; `getData()` and all
|
|
125
|
+
editing/mutation APIs stay flat and ID-based. Orphans become roots, cycles render once, local
|
|
126
|
+
sort reorders siblings without mixing levels, and growing counts visible rows. Use
|
|
127
|
+
`toggleRow()`, `expandRow()`, `collapseRow()`, `expandAll()`, `collapseAll()`, and
|
|
128
|
+
`getExpanded()`. `hierarchy.expanded` is read at construction only; `setExpanded(ids, {silent})`
|
|
129
|
+
replaces the whole set afterwards in one render, which is what to call when restoring a saved
|
|
130
|
+
state (a loop over `expandRow()` renders once per branch). `true` expands every branch, `false`
|
|
131
|
+
or `[]` collapses them all; ids are compared as `rowId` returns them (`1` is not `'1'`), and ids
|
|
132
|
+
that are not branches of the current data are dropped. Unless silent it emits one `rowtoggle`
|
|
133
|
+
per branch whose state changed, after the render; a set equal to the current one renders and
|
|
134
|
+
fires nothing. The native disclosure button works by pointer and keyboard without selecting
|
|
135
|
+
or clicking the row.
|
|
136
|
+
- **Editing** — `editMode: false|'cell'|'row'` (default `false`, and completely inert until set),
|
|
137
|
+
plus `editTrigger: 'double'|'single'` (Table defaults to double; Grid defaults to single).
|
|
138
|
+
`'cell'` edits one cell, `'row'` opens every editable cell of the row and commits them as a unit.
|
|
139
|
+
Editors are sized into the cell without changing row height, and an editing cell carries
|
|
140
|
+
`data-editing="true"` (`data-invalid="true"` plus an `aria-live` message when a validator rejects).
|
|
141
|
+
Text, number, and date editors select their content on entry, so typing replaces the value
|
|
142
|
+
("6" over "1.00" gives 6); a textarea keeps its caret.
|
|
143
|
+
- **Editable columns** — extra column keys: `editable: false|true|'text'|'number'|'select'|'date'|
|
|
144
|
+
'checkbox'|'textarea'|((row)=>boolean)` (`true` infers `'number'` for number/currency/percent/unit
|
|
145
|
+
columns and `'text'` otherwise; a function is evaluated per row, so individual rows stay
|
|
146
|
+
read-only), `options` for `'select'` (`[{value,label}]`, a `{value: label}` map
|
|
147
|
+
whose keys are always strings, or `(row)=>items`), `editorProps` (forwarded to the underlying
|
|
148
|
+
NumberField/Select/Datebox/Toggle or to the generated `<input>`/`<textarea>`),
|
|
149
|
+
`editor: (row, api)=>Node` for a fully custom editor (`api` is `{value, commit(value), cancel(),
|
|
150
|
+
row, column}`; it wins over `editable`, but a per-row `editable` function returning `false` still
|
|
151
|
+
marks the cell read-only), `parse: (raw,row)=>value` and `format: (value,row)=>string` (`format`
|
|
152
|
+
seeds the text of a `'text'`/`'textarea'` editor, `parse` converts every editor's raw output back),
|
|
153
|
+
and `validate: (value,row)=>true|string` (a returned string marks the cell invalid, shows the
|
|
154
|
+
message, and refuses the commit).
|
|
155
|
+
- **Transaction editors** — currency and unit columns reuse `NumberField` and show the resolved
|
|
156
|
+
currency/unit as its suffix unless `editorProps.unit` overrides it. This is a generic typed-grid
|
|
157
|
+
contract: application code remains responsible for tax, discount, subtotal, and accounting
|
|
158
|
+
formula rules.
|
|
159
|
+
- **Editing methods** — `startEdit(rowId, columnId)`, `commitEdit()`, `cancelEdit()`, `isEditing()`,
|
|
160
|
+
`getEditing()` → `{id, columnId}|null`.
|
|
161
|
+
- **Editing events** — `editstart {row, id, column, columnId, value}`;
|
|
162
|
+
`editcommit {row, id, column, columnId, value, previous, changes}` — **cancelable**:
|
|
163
|
+
`preventDefault()` on the component event (`table.on('editcommit', …)` or the `oneditcommit` option,
|
|
164
|
+
not the mirrored `zx-editcommit` DOM event) keeps the editor open so a server round-trip can reject
|
|
165
|
+
the change (`changes` is the `{columnId: value}` map and holds every changed cell in row mode);
|
|
166
|
+
`editcancel {row, id, column, columnId}`;
|
|
167
|
+
`editinvalid {row, id, column, columnId, value, message}`. A committed change is written
|
|
168
|
+
back through `updateRow()`, so `datachange` fires exactly as for a programmatic row update — a
|
|
169
|
+
commit with no changes emits `editcommit` with an empty `changes` map and leaves the data alone.
|
|
170
|
+
Sorting, filtering, or `setData()` while editing cancels the edit cleanly and emits `editcancel`.
|
|
171
|
+
- **Editing keyboard** — Enter or F2 on a focused editable cell starts editing (editable cells share
|
|
172
|
+
one roving tab stop); the configured single/double pointer gesture starts it without emitting
|
|
173
|
+
`rowdblclick`. Enter commits and
|
|
174
|
+
returns focus to the cell (Shift+Enter stays a newline in a `'textarea'`, Space toggles a
|
|
175
|
+
`'checkbox'`), Escape cancels and returns focus to the cell, Tab commits and moves to the next
|
|
176
|
+
editable cell (Shift+Tab the previous), wrapping across rows, and tabbing past the last editable
|
|
177
|
+
cell commits and leaves the table normally. Clicking outside the editor commits rather than
|
|
178
|
+
discarding what was typed.
|
|
179
|
+
- **Growing** — `growing: <number>` renders that many rows and offers a control for the next batch,
|
|
180
|
+
instead of laying out a result set nobody will scroll through. `growBy(count?)`, `showAll()`,
|
|
181
|
+
`getRenderedCount()`, and `grow {rendered, total}`. `setData()` starts the batch over, since a new
|
|
182
|
+
result set is not the old one grown. Row indices stay absolute — a row's index is its place in the
|
|
183
|
+
data, not in what is on screen. **Select-all covers the rendered rows, not the whole result set**;
|
|
184
|
+
call `showAll()` first to mean all of them. While growing, the table carries `aria-rowcount` and
|
|
185
|
+
each row an `aria-rowindex`, so assistive technology hears the real total rather than the size of
|
|
186
|
+
the batch.
|
|
187
|
+
- **Windowed rendering** — `virtual: true` draws only the rows in view and one viewport of overscan
|
|
188
|
+
above and below; spacer rows keep the scroll height, so what the table costs stops depending on
|
|
189
|
+
how many rows it holds. It is off by default, and a table that does not ask for it renders exactly
|
|
190
|
+
as before. A windowed table is one grid over all of its rows, so `virtual` implies `interactive`:
|
|
191
|
+
the table carries `aria-rowcount`, every drawn row an `aria-rowindex`, and the whole keyboard map
|
|
192
|
+
moves through every row, drawing the one it lands on. The focused row and the row being edited
|
|
193
|
+
stay drawn wherever the reader scrolls. Sorting, filtering through `setData()`, section rows,
|
|
194
|
+
hierarchy, row-level controls in cells, inline editing, and the sticky header work as usual, and
|
|
195
|
+
`getData()`, `getSelection()`, and exports built on them read the data, not the DOM. Selection
|
|
196
|
+
reaches rows that are not drawn: a Shift range covers them, and **the header checkbox and
|
|
197
|
+
Ctrl/Cmd+A take every row**, not only the drawn ones. `reveal(id)` scrolls a row into view, drawing
|
|
198
|
+
it first, and returns whether it could; it works without `virtual` too, on any row in the DOM.
|
|
199
|
+
`getRenderedCount()` reports the rows drawn. `virtual` wins over `growing`, and the conflict is
|
|
200
|
+
reported once through the console. Limits: give the table a `height`, or its scroll region stops at
|
|
201
|
+
the height of the window. **Rows have one height:** the table measures one row and takes that
|
|
202
|
+
height for all, following `--zx-row-height`, so rows of differing height are not supported, and
|
|
203
|
+
long text is cut short with an ellipsis rather than wrapped. Column widths cannot follow content
|
|
204
|
+
that is not drawn, so the layout is fixed: `auto` columns share the width evenly, and a column that
|
|
205
|
+
needs more sets `width`. It needs no `ResizeObserver`: where there is none (jsdom) the window
|
|
206
|
+
draws for an assumed row height and viewport. **Find-in-page does not see rows that are not drawn**, and printing prints
|
|
207
|
+
the drawn rows only.
|
|
208
|
+
- **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
|
|
209
|
+
label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
|
|
210
|
+
hidden behind it. The width measured is **the table's own container**, not the viewport, so this
|
|
211
|
+
triggers inside a narrow split pane on a wide screen. A column with `popin: false` leads the card
|
|
212
|
+
instead of becoming another labelled line — the identifying column usually wants that. Every cell
|
|
213
|
+
carries `data-label`, so the labels are there whether or not the option is on. `isStacked()`
|
|
214
|
+
reports the current state and `stackedchange {stacked}` fires on each crossing. Stacking drops
|
|
215
|
+
`display: table`, which drops the implicit ARIA roles, so the component states
|
|
216
|
+
`table`/`rowgroup`/`row`/`cell`/`columnheader` explicitly for exactly as long as the mode is on.
|
|
217
|
+
- **Empty state** — `emptyText` takes a string, a Node, or a function returning one, so an empty
|
|
218
|
+
table can carry an icon, an explanation, and the action that resolves it (`emptyState({…})`).
|
|
219
|
+
A function is re-called on every render, which is what to use when the placeholder holds controls.
|
|
220
|
+
- **Row order** — `rowReorder: true` adds a dedicated drag handle. Pointer drag moves rows before
|
|
221
|
+
or after a sibling; Space/Enter grabs/releases the same handle and ArrowUp/ArrowDown moves it for
|
|
222
|
+
keyboard users. `moveRow(id, targetId, position)` exposes the same guarded operation. Hierarchical
|
|
223
|
+
rows only move among siblings, and an active local sort disables manual order. A cancelable
|
|
224
|
+
`rowmove {row,id,target,targetId,position}` fires before `datachange`.
|
|
225
|
+
- **Column visibility** — `columnVisibility: true` renders a chooser; `hiddenColumns` seeds it.
|
|
226
|
+
`getVisibleColumns()`, `getHiddenColumns()`, `setColumnVisible()`, and `toggleColumn()` preserve
|
|
227
|
+
caller column order and never allow the final visible column to disappear.
|
|
228
|
+
- **Column order** — `columnReorder: true` adds up/down buttons to the chooser and ArrowUp/
|
|
229
|
+
ArrowDown support while a column option is focused. `getColumns()`, `setColumns()`,
|
|
230
|
+
`getColumnOrder()`, `setColumnOrder()`, and `moveColumn()` reconcile stale saved IDs and keep
|
|
231
|
+
hidden/sorted state attached to stable column IDs. `columnorderchange {order}` fires after a
|
|
232
|
+
user or non-silent programmatic change.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# TagPicker
|
|
2
|
+
|
|
3
|
+
A multi-select combobox that keeps its selection visible as removable tags inside the control — for picking several values out of a large catalogue.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tag-picker · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Multi-select combobox that renders its selection as removable tags inside the control (APG combobox
|
|
8
|
+
plus multi-selectable listbox). Use it when the catalogue is too large to show in full: `Checklist`
|
|
9
|
+
shows a fixed set, and `ValueList` takes free text with no catalogue. Unknown IDs passed to
|
|
10
|
+
`setValues` still render as tags, so a stored selection survives a catalogue that has not loaded
|
|
11
|
+
yet. Field type: `tagpicker`.
|
|
12
|
+
|
|
13
|
+
- **Options** — `items`, `values: []`, `valueKey: 'ID'`, `labelKey: 'name'`, `iconKey: 'icon'`,
|
|
14
|
+
`colorKey: 'color'`, `toneKey: 'tone'`, `searchKeys`,
|
|
15
|
+
`filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
|
|
16
|
+
`max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
|
|
17
|
+
`placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
|
|
18
|
+
- **Tags are Badges** — every selected tag is built by `badge()` (`.zx-badge.zx-tag-picker__tag`):
|
|
19
|
+
the Badge's height from the row, 12px medium type, padding and one fill, with the tag shape's
|
|
20
|
+
small corners. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
|
|
21
|
+
`green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`), so a toned tag is exactly the
|
|
22
|
+
`badge({ tone })` a list row or record header shows for the same item; a tone wins over a colour.
|
|
23
|
+
An untoned tag keeps the text ink, because in a field it is the value.
|
|
24
|
+
- **Tag identity** — icon values accept a bundled icon name or Node; colors (a CSS colour or a token
|
|
25
|
+
reference such as `var(--zx-color-tone-blue-fg)`) are scoped to the tag and its option through
|
|
26
|
+
`--zx-tag-color`. An option shows its icon on a tile of its colour; inside a tag the icon is a bare
|
|
27
|
+
glyph, since the tag is already the fill. Custom `renderItem`/`renderTag` remain authoritative.
|
|
28
|
+
- **Read-only** — `readonly` (or `setReadonly(true)`) shows only the tags: no input, chevron, or
|
|
29
|
+
remove buttons, so a full row of tags never wraps onto an empty line.
|
|
30
|
+
- **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
|
|
31
|
+
`removeValue()`, `clear()`, `reset()`, `setItems()`, `isFull()`, `open()`/`close()`, `focus()`,
|
|
32
|
+
`setReadonly()`, `enable()`/`disable()`.
|
|
33
|
+
- **Events** — `change {values, items}`, `add {value, item}`, `remove {value, item}`,
|
|
34
|
+
`create {value, item}`, `query {query}`, `open`, `close`.
|
|
35
|
+
- **Keyboard** — ↓ opens and moves, ↑ moves, Enter toggles the active option (or creates one from
|
|
36
|
+
the query), Escape closes, Backspace on an empty input removes the last tag, Home/End jump
|
|
37
|
+
within the list.
|
|
38
|
+
- **Quiet fields** — inside `[data-zx-fields="quiet"]` the tags read as the value: no border, fill
|
|
39
|
+
or chevron until hover; full field chrome while focused or open.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Timebox
|
|
2
|
+
|
|
3
|
+
A duration field.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/timebox · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Duration input (H:MM[:SS], optional sign) — a length of time, not a time of day. For a time of day
|
|
8
|
+
use `TimePicker` or `DateTimeBox`.
|
|
9
|
+
|
|
10
|
+
- **Options** — `value: 0`, `unit: 'minutes'|'seconds'|'hours'`, `seconds: false`, `signed: false`,
|
|
11
|
+
`disabled`.
|
|
12
|
+
- **Methods** — `get(unit)`, `set(value, unit?, {silent})`, `enable()`/`disable()`.
|
|
13
|
+
- **Events** — `change {value}`, in `options.unit`.
|
|
14
|
+
- **Also exported** — the pure helpers `splitTime` and `joinTime`.
|
|
15
|
+
- **Quiet fields** — inside `[data-zx-fields="quiet"]` the segments (native inputs) and the sign
|
|
16
|
+
button drop their border and fill until hover or focus; the sign keeps its colour.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Toggle
|
|
2
|
+
|
|
3
|
+
A labelled switch for settings that take effect immediately.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/toggle · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Switch (`role="switch"`, `aria-checked`).
|
|
8
|
+
|
|
9
|
+
- **Options** — `checked: false`, `value: true`, `label: null`, `hideLabel: false`,
|
|
10
|
+
`disabled: false`.
|
|
11
|
+
- **Label** — start-aligned and wrapping like text within the available width, the track level
|
|
12
|
+
with its first line. It is the switch's accessible name. `hideLabel: true` keeps it for assistive
|
|
13
|
+
technology only: no visible text, and the label becomes the switch's `aria-label` — for a switch
|
|
14
|
+
whose meaning the layout already shows, such as a table cell under a column header. With no
|
|
15
|
+
label at all, name the switch from outside: a Field or `<label for>` around it, or
|
|
16
|
+
`aria-labelledby` on the element.
|
|
17
|
+
- **Methods** — `get()`, `set(checked, {silent})`, `toggle()`, `getValue()` (returns
|
|
18
|
+
`options.value` when on, `false` when off), `setLabel(label)` (null removes it),
|
|
19
|
+
`enable()`/`disable()`.
|
|
20
|
+
- **Events** — `change {checked, value}`.
|
|
21
|
+
- **Keyboard** — Space/Enter.
|