@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,76 @@
|
|
|
1
|
+
# Message — toasts, inline, progress
|
|
2
|
+
|
|
3
|
+
Transient notifications: a floating region for toasts, a progress handle for long work, and an inline area for messages that belong to one part of the screen.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/message · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Floating toasts come from statics; `new Message(target)` gives an inline, non-floating area with
|
|
8
|
+
the same `.show()`. The toast region is `role="status"`/`aria-live` (`role="alert"` for errors).
|
|
9
|
+
A floating region sits at the top of the viewport on the inline-end side by default (`top-end`:
|
|
10
|
+
the upper right in a left-to-right page), sizes to its messages rather than the page, and uses the
|
|
11
|
+
translucent glass surface tokens with a solid fallback. A message is a plain card with a neutral
|
|
12
|
+
border; its kind shows in the icon. Floating messages pile into a stack that opens on hover, focus,
|
|
13
|
+
or a press (see **Stack**).
|
|
14
|
+
|
|
15
|
+
- **Statics** — `Message.info/success/warning/error(msg, opts)`,
|
|
16
|
+
`Message.show(msg, { kind, timeout=4000, closable, highlight?, scope?, placement? })` → `{ close() }`,
|
|
17
|
+
`Message.progress(text, {scope?, placement?, highlight?})` → `{ update(pct, text?), done(), fail(text?) }`,
|
|
18
|
+
`Message.setPlacement(placement)` / `Message.getPlacement()`,
|
|
19
|
+
`Message.setStack(enabled)` / `Message.getStack()`. `scope` is an element or selector
|
|
20
|
+
whose nearest Zx theme scope owns that floating region; without it the focused opener supplies
|
|
21
|
+
the scope.
|
|
22
|
+
- **Placement** — `placement: 'top-start'|'top'|'top-end'|'bottom-start'|'bottom'|'bottom-end'`
|
|
23
|
+
per call, default `'top-end'`: the block edge, then the inline position, logical, so `start` and
|
|
24
|
+
`end` follow the writing direction and `top`/`bottom` alone are centred.
|
|
25
|
+
`Message.setPlacement(placement)` sets the default for calls that name none and returns the
|
|
26
|
+
placement now in effect (anything unknown restores `'top-end'`); it applies to messages shown
|
|
27
|
+
from then on. Messages of one placement share a region, so a scope has one region per placement
|
|
28
|
+
in use, each carrying `data-placement`. At the foot the newest toast is nearest the edge. The
|
|
29
|
+
distance from the viewport edge is the `--zx-message-offset` custom property (default
|
|
30
|
+
`var(--zx-space-4)`), read from the region's theme scope: set it there or on `:root` to clear a
|
|
31
|
+
header or a status bar. At 640px and narrower every placement spans the foot of the viewport,
|
|
32
|
+
full width. An inline area ignores `placement`.
|
|
33
|
+
- **Region lifecycle** — a floating region is created on the first toast for its scope and removed
|
|
34
|
+
when its last toast closes. One whose host was emptied or left the document is replaced on the
|
|
35
|
+
next toast rather than reused, and a scope that is itself detached falls back to the focused
|
|
36
|
+
element's scope. `Message.disposeRegion(scope)` → boolean removes a scope's regions at once — all
|
|
37
|
+
placements, toasts and all — for a host torn down while toasts are still showing. While a modal Dialog or
|
|
38
|
+
Sheet is open the region moves into the topmost one, so toasts and their actions stay visible
|
|
39
|
+
and clickable above it, and moves back when it closes. A press on a toast dismisses no open menu
|
|
40
|
+
or drawer.
|
|
41
|
+
- **Per-message options** — `kind: 'info'`, `timeout`, `closable: true`, `maxVisible: 5` (extras
|
|
42
|
+
queue, and hovering pauses dismissal), `highlight: false`.
|
|
43
|
+
- **Highlight** — `highlight: 'border'` (or `true`) draws the message's border in the kind colour;
|
|
44
|
+
`highlight: 'animated'` draws it faintly with a light travelling round it, and is the still
|
|
45
|
+
kind-coloured border under `prefers-reduced-motion: reduce`. Per message, or as an inline area's
|
|
46
|
+
default; the message carries it as `data-highlight`. `false` (the default) is the plain card.
|
|
47
|
+
- **Stack** — floating regions stack by default, and `stack: true` makes an inline area stack:
|
|
48
|
+
the visible messages pile into one stack, the newest in front, the next two peeking out behind
|
|
49
|
+
it a step smaller, the rest out of sight. `Message.setStack(false)` lists floating messages one
|
|
50
|
+
below another instead (at once, those on screen included; `getStack()` reads it). It
|
|
51
|
+
opens — every visible message laid out with its own height — while the pointer is over it or
|
|
52
|
+
focus is inside it; a press on it that is not on a button (a tap included) keeps it open until a
|
|
53
|
+
press outside it, Escape (which returns focus to where it came from), or `collapse()`. While it
|
|
54
|
+
is open by any of these no message in it times out. The outside press is handled after its own
|
|
55
|
+
click handlers, so a button elsewhere can toggle the stack with
|
|
56
|
+
`isExpanded() ? collapse() : expand()`. Closing a message from the keyboard moves focus to the
|
|
57
|
+
same control of the next message, and from the last one back to where it was before it came
|
|
58
|
+
into the stack. An open floating stack taller than the viewport becomes a scrolling list
|
|
59
|
+
(`data-overflow`) with the newest message in view. `expanded: true` keeps it open without
|
|
60
|
+
holding the timers. Instance methods: `expand()` (opens and keeps it open), `collapse()`,
|
|
61
|
+
`isExpanded()`, `setStack(enabled)`; events `expand` and `collapse`. The root carries
|
|
62
|
+
`data-stack` and `data-state="collapsed"|"expanded"`; document order follows the visual order,
|
|
63
|
+
so Tab meets the messages as they are seen. A stack at the top (inline areas, `top*`) piles
|
|
64
|
+
downwards, one at the foot (`bottom*`, and every region at 640px and narrower) upwards. The
|
|
65
|
+
geometry is the exported pure helper `messageStackLayout(heights, expanded)`.
|
|
66
|
+
- **Action** — `action: { label, onclick?, kind? }` renders one small button (`.zx-btn`,
|
|
67
|
+
`data-size="sm"`, secondary unless `kind` is `primary`/`danger`/`ghost`) in a toast or an inline
|
|
68
|
+
message; activating it runs `onclick(event)` and closes the message. A message with an action
|
|
69
|
+
stays at least 8000ms (`timeout: 0` still persists). Every message holds its timer while the
|
|
70
|
+
pointer is over it or focus is inside it (WCAG 2.2.1) and resumes once neither is; the region is
|
|
71
|
+
not modal, so Tab moves between the action and the close button, and closing a message that holds
|
|
72
|
+
focus returns focus to where it came from. The live region still announces the text.
|
|
73
|
+
- **Leading** — `leading: Node | component` (an Avatar, say) replaces the kind icon. It is
|
|
74
|
+
decorative; the text must name what it shows.
|
|
75
|
+
- **Handle** — every `show()` (static or inline) and `info/success/warning/error()` return
|
|
76
|
+
`{ close() }`; closing twice, or a queued message, is safe.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Modal
|
|
2
|
+
|
|
3
|
+
A bare top-layer surface you fill yourself — Dialog’s unopinionated sibling, for overlays that supply their own chrome.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/modal · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Thin overlay on the native `<dialog>` element. The surface uses the shared, reading-sized overlay
|
|
8
|
+
panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus returns to the opener on close.
|
|
9
|
+
|
|
10
|
+
- **Options** — `content`, `width: 'auto'`, `closable: true`, `lightDismiss: false`,
|
|
11
|
+
`destroyOnClose: false`, `scope: null` (the opener's nearest Zx theme scope by default). The
|
|
12
|
+
scope is resolved again on every `open()`; a `scope` element not yet in the document leaves the
|
|
13
|
+
dialog detached until then, rather than parking it on `<body>` outside the theme.
|
|
14
|
+
- **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
|
|
15
|
+
- **Events** — `open`, `close {result}`, `cancel {reason}`.
|
|
16
|
+
- **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
|
|
17
|
+
`reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
|
|
18
|
+
action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
|
|
19
|
+
`event.preventDefault()` keeps it open, which is the place for an "unsaved changes" check.
|
|
20
|
+
A programmatic `close()` raises no `cancel`. Escape is handled by Zx rather than by the browser's
|
|
21
|
+
close request, so preventing it holds however often the key is pressed; a handler that calls
|
|
22
|
+
`preventDefault()` on the Escape keydown (a popup inside the dialog, your own) keeps the key.
|
|
23
|
+
- **Without `showModal()`** — in a DOM that has `<dialog>` but not `showModal()` (jsdom, for unit
|
|
24
|
+
tests), Modal, Dialog and Sheet present themselves through the `open` attribute instead.
|
|
25
|
+
`open()`, `close(result)`, `isOpen()`, Escape, `cancel`, the events and `destroy()` work the
|
|
26
|
+
same; there is no top layer, no inert page, no backdrop and no `aria-modal`, so modality itself
|
|
27
|
+
is not testable there.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# ModuleBar — the module level of an application
|
|
2
|
+
|
|
3
|
+
The module level of an application: one colour-coded tile per module in a vertical strip or a horizontal bar.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/module-bar · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
One colour-coded tile per module, in a vertical strip or a horizontal bar: the level above an
|
|
8
|
+
application's menus. Use it on its own — the classic module bar in an application header, beside
|
|
9
|
+
a tree-layout `AppSidebar` — or through `AppSidebar`'s `layout: 'modules'`, which composes it.
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
import { ModuleBar } from '/assets/zx.esm.js';
|
|
13
|
+
|
|
14
|
+
const bar = new ModuleBar(null, {
|
|
15
|
+
items: [
|
|
16
|
+
{ id: 'mail', label: 'Mail', icon: 'envelope', tone: 'blue', badge: 7, children: [
|
|
17
|
+
{ id: 'inbox', label: 'Inbox', href: '#inbox' }, { id: 'sent', label: 'Sent', href: '#sent' }
|
|
18
|
+
] },
|
|
19
|
+
{ id: 'billing', label: 'Billing', icon: 'file-invoice', color: '#535494', href: '#billing' }
|
|
20
|
+
],
|
|
21
|
+
active: 'inbox',
|
|
22
|
+
onselect: (event) => { event.preventDefault(); route(event.detail.id); }
|
|
23
|
+
});
|
|
24
|
+
bar.setBadge('mail', 8);
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- **Items** (`ModuleItem`) — the `AppNavItem` shape plus `tone` (a categorical tone that follows
|
|
28
|
+
the theme) or `color` (any CSS colour; it wins), `pinned: true|number` (when any module is
|
|
29
|
+
pinned, unpinned ones are under "All modules" only), `group` (the catalogue heading), and
|
|
30
|
+
`description`. Children are the module's menu. A `section` at the top level heads its modules:
|
|
31
|
+
a caption over them while names are printed beside the tiles, a short rule between groups on an
|
|
32
|
+
icon strip or bar, and their group in the catalogue. `agent` (AgentAvatar options, or `true`)
|
|
33
|
+
draws the module as an agent: its `AgentAvatar` at the size of the tile in place of the tile,
|
|
34
|
+
whatever the `appearance`, at rest, with the activity's word in the tile's accessible name
|
|
35
|
+
("Ledger, Needs you (2)"); `tone` and `color` then do not apply.
|
|
36
|
+
- **Options** — `items`, `active` (a module or anything in a module's menu),
|
|
37
|
+
`orientation: 'vertical'|'horizontal'`, `side`, `appearance: 'tint'|'solid'|'plain'` (the glyph
|
|
38
|
+
on a tint of the module colour; the solid identity tile; monochrome glyphs),
|
|
39
|
+
`labels: 'hidden'|'below'|'beside'` (names under the tiles of a vertical strip, or beside them —
|
|
40
|
+
a navigation column of its own, a row per module with its count at the end),
|
|
41
|
+
`menus: 'flyout'|'none'`, `expanded`, `controls`, `allModules: 'auto'|'always'|'never'`,
|
|
42
|
+
`header`, `footer`, `label` (default "Modules"), `openDelay`, `closeDelay`, `renderIcon`.
|
|
43
|
+
- **Menus** — with `menus: 'flyout'` a module's children open beside its tile on hover, focus,
|
|
44
|
+
click, or the arrow toward the workspace, exactly like a rail. With `menus: 'none'` an adjacent
|
|
45
|
+
panel the application owns shows them: every module then fires `select`, `setExpanded(id)`
|
|
46
|
+
names the module the panel shows, and each tile with a menu reports `aria-expanded` and
|
|
47
|
+
`aria-controls` the `controls` id.
|
|
48
|
+
- **Overflow** — modules that do not fit move behind the "All modules" button; the current module
|
|
49
|
+
(and the expanded one) always stays. The catalogue lists every module as a labelled tile,
|
|
50
|
+
grouped by `group`, with a filter field past twelve modules. `partitionModules(items, capacity,
|
|
51
|
+
keep, reserve)` is the pure function deciding what shows; `reserve` keeps the button's slot for
|
|
52
|
+
`allModules: 'always'`.
|
|
53
|
+
- **Methods** — `setItems()`, `getItems()`, `setActive()`, `setBadge(id, badge)` (in place, on the
|
|
54
|
+
tile, in its menu, and in the catalogue), `setExpanded(id)`, `setLabels(labels)` (how a column
|
|
55
|
+
expands to names and collapses to icons), `setLayout({orientation, side})`,
|
|
56
|
+
`openFlyout()`, `closeFlyout()`, `closeAllFlyouts()`, `isFlyoutOpen()`, `openAllModules()`,
|
|
57
|
+
`closeAllModules()`, `isAllModulesOpen()`, `focus()`, `destroy()`.
|
|
58
|
+
- **Events** — cancelable `select {item, id, value, href, event}`, `flyoutchange {item, id, open}`,
|
|
59
|
+
`overflowchange {visible, overflow}`, and `allmodules {open}`.
|
|
60
|
+
- **Keyboard** — the bar is one Tab stop, on the current module. Arrow keys along the bar move
|
|
61
|
+
between tiles and wrap; Home and End go to the first and last control; typing jumps to the next
|
|
62
|
+
module whose name starts with the letters typed; the arrow toward the workspace opens a menu and
|
|
63
|
+
moves into it; Escape, or the arrow back toward the strip, closes a menu onto its tile; Escape
|
|
64
|
+
closes the catalogue onto its button, and so does tabbing out of it. In the catalogue, arrows
|
|
65
|
+
move across the grid, typing goes to the filter field (past twelve modules), and Enter chooses.
|
|
66
|
+
- **Semantics** — a `<nav>` of native links and buttons, never a menu or menubar. The module that
|
|
67
|
+
is or holds the current page carries `aria-current` (`page` or `true`); an icon-only tile's
|
|
68
|
+
accessible name is its label, with its count ("Mail (7)"), and it has a tooltip. Current is
|
|
69
|
+
the neutral `--zx-color-bg-current` fill behind the tile, never the accent or an edge bar.
|
|
70
|
+
- **Geometry** — a target is one control plus a space step, a tile one control less one, so
|
|
71
|
+
`--zx-control-height` resizes the bar; a coarse pointer keeps a 40px target.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# MultiValueEditor
|
|
2
|
+
|
|
3
|
+
A stack of rows for an ordered list of values, each row with its own remove and reorder controls — for a field that repeats.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/multi-value-editor · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Ordered value editor with explicit rows (add / remove / move).
|
|
8
|
+
|
|
9
|
+
- **Options** — `values`, `options` (allowed values, which turns the rows into selects),
|
|
10
|
+
`addLabel`, `reorder: 'both'` (`'both'` | `'buttons'` | `'drag'` | `'none'` — a drag handle, the
|
|
11
|
+
up/down buttons, both, or neither).
|
|
12
|
+
- **Methods** — `getValues()`, `setValues()`.
|
|
13
|
+
- **Events** — `change {values}`.
|
|
14
|
+
- Dragging goes through a dedicated handle, so text selection inside a row's input still works. The
|
|
15
|
+
handle is also a keyboard control (Arrow keys, Home, End), which is what keeps `reorder: 'drag'`
|
|
16
|
+
operable without a pointer.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# NavigationBar
|
|
2
|
+
|
|
3
|
+
The application header: a brand, one row of destinations with badges, and the actions that stay reachable at every width.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/navigation-bar · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Application navigation bar: brand, items, and right-aligned actions. Items overflow into a "More"
|
|
8
|
+
menu on narrow widths.
|
|
9
|
+
|
|
10
|
+
- **Options** — `title`, `items: [{ name, title, badge? }]`, `active`, `actions: []`,
|
|
11
|
+
`overflow: true`, `overflowBelow: '44rem'`, `minVisible: 0`.
|
|
12
|
+
- **Methods** — `setTitle()`, `setItems()`, `setActive()`, `setBadge()`, `setActions()`.
|
|
13
|
+
- **Events** — `change {name}`.
|
|
14
|
+
|
|
15
|
+
**Overflow is a default, not a law.** Collapsing every item behind "More" is right for a top app
|
|
16
|
+
bar and wrong for a phone bottom bar, where the navigation is the point. `overflow: false` keeps
|
|
17
|
+
every item at every width; `overflowBelow` moves the threshold; `minVisible: n` pins the first `n`
|
|
18
|
+
items and overflows the rest. At the default the collapse is a container query with no observer
|
|
19
|
+
installed; any other threshold installs a `ResizeObserver`, which is the cost of asking for one.
|
|
20
|
+
|
|
21
|
+
The current item is the neutral `--zx-color-bg-current` fill with the text colour and a semibold
|
|
22
|
+
label; item badges are neutral counts. Only the brand mark keeps the accent.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# NumberField
|
|
2
|
+
|
|
3
|
+
A spinbutton with step buttons: bounded ranges, fractional steps, units, and wrapping.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/number-field · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Numeric input with decrement/increment buttons, following the APG **spinbutton** pattern. The step
|
|
8
|
+
buttons are `tabindex="-1"`/`aria-hidden` pointer affordances — the input itself is the spinbutton.
|
|
9
|
+
Field type: `number`.
|
|
10
|
+
|
|
11
|
+
- **Options** — `value` (number|null), `min`, `max`, `step: 1`, `largeStep: 10` (PageUp/PageDown
|
|
12
|
+
multiplier), `precision` (decimals; derived from `step` when null), `snap: true` (see
|
|
13
|
+
**Snapping**), `wrap: false` (stepping past
|
|
14
|
+
a bound jumps to the other one), `placeholder`, `unit` (suffix rendered inside the control),
|
|
15
|
+
`group: false` (thousands separators while idle), `locale`, `disabled`, `readonly`, `required`,
|
|
16
|
+
`name`.
|
|
17
|
+
- **Methods** — `get()`, `set(value, {silent})` (parses strings, snaps to the step grid, clamps to
|
|
18
|
+
the range; `''`/null clear it), `stepUp(n)`, `stepDown(n)`, `setRange(min, max)`,
|
|
19
|
+
`setReadonly()`, `reset()`, `focus()`, `getInput()`, `enable()`/`disable()`.
|
|
20
|
+
- **Events** — `change {value}` (committed), `input {value}` (per keystroke, possibly unsnapped).
|
|
21
|
+
- **Snapping** — by default a typed or assigned value is moved onto the `step` grid (step 2 turns
|
|
22
|
+
123 into 124) and rounded to the step's decimals. That suits quantities; it is wrong for a value
|
|
23
|
+
that is not a multiple of anything — an identifier, a seed, a measurement. `snap: false` keeps
|
|
24
|
+
the value exactly as entered: `step` is then only what the buttons and arrow keys add, decimals
|
|
25
|
+
are rounded only to an explicit `precision`, and `min`/`max` still clamp.
|
|
26
|
+
- **Keyboard** — ↑/↓ one step, PageUp/PageDown `largeStep` steps, Home/End jump to `min`/`max` when
|
|
27
|
+
set (otherwise they keep their caret meaning), Enter commits, wheel steps while focused.
|
|
28
|
+
- **Also exported** — `parseNumber(raw)` (accepts `.` and `,` as the decimal separator, ignores
|
|
29
|
+
grouping, returns null for junk) and `snapNumber(value, {min, max, step, precision})`.
|
|
30
|
+
- **In a Field** — field type `number` fills the control column like a text input and takes the
|
|
31
|
+
field key as its `name`.
|
|
32
|
+
- **Quiet fields** — inside `[data-zx-fields="quiet"]` the number reads as text: no border, no
|
|
33
|
+
fill, the value start-aligned with the quiet values around it, both steppers at the trailing end
|
|
34
|
+
and hidden (kept in the layout so nothing moves) until hover or focus; full chrome on focus.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Pagination
|
|
2
|
+
|
|
3
|
+
The footer bar of a server-backed list: a page window that never changes width, a page-size select with an Auto size that fits the viewport, a row summary, an append-style Load more mode, and an Auto-load switch for infinite scrolling.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/pagination · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
The pager for a server-backed list. It owns no data: `getState()` and every `change` hand back
|
|
8
|
+
the `page`, `pageSize`, and zero-based `offset = (page - 1) * pageSize` a query needs. `page` is
|
|
9
|
+
1-based and always clamped into `[1, pages]`; a `total` of 0 is treated as one empty page rather
|
|
10
|
+
than zero pages.
|
|
11
|
+
|
|
12
|
+
The ZeyOS bindings page differently — zero-based, `pageSize: 50`, appending pages above zero — so
|
|
13
|
+
driving `zeyosTable()` (or `zeyosView()`) takes one mapping in the `change` listener:
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
const binding = zeyosTable(client, 'contacts', { pageSize: 25 });
|
|
17
|
+
const pager = new Pagination(host, { pageSize: binding.pageSize });
|
|
18
|
+
pager.on('change', async ({ detail }) => {
|
|
19
|
+
const result = await binding.load({ page: detail.page - 1, pageSize: detail.pageSize, replace: true });
|
|
20
|
+
pager.setTotal(result.count ?? 0); // silent, so it cannot loop
|
|
21
|
+
});
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
In `mode: 'loadmore'` each `change` is one `binding.loadMore()`, which appends.
|
|
25
|
+
|
|
26
|
+
**Fitting the page.** `pageSize: 'auto'` (and `'auto'` among `pageSizes`, shown as "Auto (14)")
|
|
27
|
+
shows as many rows as fit `viewport`, the element the rows scroll in, below its sticky `thead`. It
|
|
28
|
+
measures again whenever the viewport or its content changes size — a window, a drawer, the row height,
|
|
29
|
+
a table stacking into cards — and keeps the page's first row on the new page. A Zx Table is
|
|
30
|
+
measured by its first body row, anything else by `--zx-row-height`; `rowHeight`, `perRow` (a card
|
|
31
|
+
grid's columns) and `reserve` take numbers or functions of the viewport for other content. Call
|
|
32
|
+
`refit()` after swapping what the viewport shows.
|
|
33
|
+
|
|
34
|
+
**Auto-load.** `autoLoad: true` turns paging into infinite scroll: the next page loads by itself
|
|
35
|
+
when the end of the viewport (or, without one, the pager) comes within `autoLoadMargin` pixels —
|
|
36
|
+
half the viewport by default. `showAutoLoad: true` adds an Auto-load switch, so the reader chooses;
|
|
37
|
+
switching between paging and appending returns to page 1. Load more stays as the keyboard's way on.
|
|
38
|
+
Disable the pager while a page is in flight and enable it when the rows land; auto-load waits:
|
|
39
|
+
|
|
40
|
+
```js
|
|
41
|
+
const pager = new Pagination(footer, { pageSize: 'auto', pageSizes: ['auto', 25, 50], viewport: list, showAutoLoad: true });
|
|
42
|
+
pager.on('change', async ({ detail }) => {
|
|
43
|
+
pager.disable();
|
|
44
|
+
// Appending adds one page; paging shows one; restarting an appending list shows all loaded so far.
|
|
45
|
+
const from = detail.append || detail.mode === 'pages' ? detail.offset : 0;
|
|
46
|
+
const rows = await fetchRows(from, detail.offset + detail.pageSize - from);
|
|
47
|
+
if (detail.append) table.addData(rows); else table.setData(rows);
|
|
48
|
+
pager.enable();
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- **Options** — `page: 1`, `pageSize: 25` (or `'auto'`), `total: 0`, `pageSizes: [25, 50, 100]`
|
|
53
|
+
(may include `'auto'`), `siblings: 1`, `boundaries: 1`, `showPageSize: true`, `showSummary: true`
|
|
54
|
+
(renders "26–50 of 312"), `mode: 'pages'|'loadmore'`, `autoLoad: false`, `showAutoLoad: false`,
|
|
55
|
+
`viewport: null` (element, selector, or function), `rowHeight`, `perRow: 1`, `reserve`,
|
|
56
|
+
`minPageSize: 5`, `maxPageSize: 200`, `autoLoadMargin: null`, `disabled: false`.
|
|
57
|
+
- **Methods** — `setPage(n)`, `setTotal(n)`, `setPageSize(n|'auto')`, `setState({page, pageSize,
|
|
58
|
+
total}, {silent})`, `setAutoLoad(on, {silent})`, `refit()`, `getState()` → `{page, pageSize,
|
|
59
|
+
total, pages, offset, auto, autoLoad, mode}`, `enable()`/`disable()`, `destroy()`.
|
|
60
|
+
- **Events** — `change {page, pageSize, offset, total, pages, auto, autoLoad, mode, reason,
|
|
61
|
+
append}`, where `reason` is `page`, `pageSize`, `fit`, `more`, `scroll`, `mode`, or `state`, and
|
|
62
|
+
`append` means "add rows `offset … offset + pageSize` after the shown ones" (otherwise show rows
|
|
63
|
+
`offset …` while paging, `0 … page × pageSize` while appending). `autoload {autoLoad}` when the
|
|
64
|
+
switch flips.
|
|
65
|
+
- **Also exported** — `paginationRange({page, pages, siblings, boundaries})` → `Array<number|'…'>`,
|
|
66
|
+
the pure page-window calculation, and `fitPageSize({available, rowHeight, perRow, reserve, min,
|
|
67
|
+
max})` → the fitted size (0 when nothing can be measured), both usable on their own.
|
|
68
|
+
- **Semantics** — `<nav aria-label="Pagination">`; the current page carries `aria-current="page"`;
|
|
69
|
+
previous/next are labelled icon buttons that go `disabled` at the ends; the ellipses are
|
|
70
|
+
`aria-hidden` spans, not buttons.
|
|
71
|
+
- **Appearance** — the summary and the page-size select sit together at the start of the bar,
|
|
72
|
+
the pager alone at the end; the current page is the neutral `--zx-color-bg-current` fill with a
|
|
73
|
+
semibold figure: where you are, not a call to action.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Panel / MasterPanel
|
|
2
|
+
|
|
3
|
+
A raised surface with a title, an optional collapse control, header actions, and a footer — plus MasterPanel, its full-height variant.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/panel · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
## Panel
|
|
8
|
+
|
|
9
|
+
Framed, optionally collapsible section. Its header is a row rather than one big button: the chevron
|
|
10
|
+
and title form the collapse control and `buttons` sit at the trailing edge beside it, so clicking
|
|
11
|
+
an action never collapses the panel. The footer bar appears as soon as it has `footer` content,
|
|
12
|
+
`footerButtons`, or both, and its buttons are right-aligned.
|
|
13
|
+
|
|
14
|
+
- **Options** — `title`, `content`, `open: true`, `collapsible: true`, `buttons: []` (elements or
|
|
15
|
+
`button()` descriptors, right-aligned in the header), `footer`, `footerButtons: []`
|
|
16
|
+
(right-aligned in the footer).
|
|
17
|
+
- **Methods** — `setTitle()`, `setContent()`, `setButtons()`, `setFooter()`, `setFooterButtons()`,
|
|
18
|
+
`open()`/`close()`/`toggle()`, `isOpen()`.
|
|
19
|
+
- **Events** — `open`, `close`.
|
|
20
|
+
|
|
21
|
+
## MasterPanel
|
|
22
|
+
|
|
23
|
+
Full-height application panel with a fixed header (title plus action buttons) and an optional
|
|
24
|
+
fixed footer, while the body scrolls.
|
|
25
|
+
|
|
26
|
+
- **Options** — `title`, `content`, `buttons: []`,
|
|
27
|
+
`module: <ZeyOS module name → accent token>`, `footer`.
|
|
28
|
+
- **Methods** — `setTitle()`, `setContent()`, `setButtons()`, `setFooter()`.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# PromptStarters — starting points for an empty conversation
|
|
2
|
+
|
|
3
|
+
Starting points for an empty conversation.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/prompt-starters · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
A labelled group of buttons, each with a title and, muted beneath it, its description or else its
|
|
8
|
+
text. PromptStarters only reports the pick and never sends anything: the application decides
|
|
9
|
+
whether a starter fills the composer or sends at once.
|
|
10
|
+
|
|
11
|
+
- **Constructor** — `new PromptStarters(null, options)` creates its own root; `new
|
|
12
|
+
PromptStarters(element, options)` takes over an element and restores it on `destroy()`.
|
|
13
|
+
- **Options** — `items: [{id, title, text, description?, icon?}]`, `label` (the group's accessible
|
|
14
|
+
name, English `Suggestions`), `columns: 'auto'|1|2`, `headingLevel: null`, `msg`. An item without
|
|
15
|
+
`id`, `title` or `text` is left out, as is a repeated id; other fields on an item are handed back
|
|
16
|
+
in `pick`. `text` keeps its spaces and line breaks, so a prompt can end where the person goes on
|
|
17
|
+
writing.
|
|
18
|
+
- **Columns** — `'auto'` is two columns and one in a container narrower than 32rem, read through a
|
|
19
|
+
container query, so it behaves the same in a split pane, a dialog or a phone. The root fills the
|
|
20
|
+
width it is given.
|
|
21
|
+
- **Heading** — `headingLevel: null` keeps `label` for assistive technology only. A level draws it
|
|
22
|
+
above the starters as a heading of that level, which then names the group.
|
|
23
|
+
- **Methods** — `setItems(items)` (the focus on a starter stays on the starter with the same id;
|
|
24
|
+
emits nothing), `destroy()`.
|
|
25
|
+
- **Events** — `pick {item}`, with a copy of the starter as given.
|
|
26
|
+
- **Keyboard** — each starter is a button in the Tab order, pressed with Enter or Space. There are
|
|
27
|
+
no custom keys.
|
|
28
|
+
- **Accessibility** — the root is `role="group"`. Each button is named by its title and described
|
|
29
|
+
by the line beneath it. The line is clamped to two lines on screen; its whole text stays the
|
|
30
|
+
description. Without items the group is hidden.
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
const starters = new PromptStarters(null, {
|
|
34
|
+
items: [
|
|
35
|
+
{ id: 'reply', title: 'Draft a reply', text: 'Draft a short, friendly reply to this customer:\n\n' },
|
|
36
|
+
{ id: 'review', title: 'Prepare the review', text: 'Summarise this week’s escalations.', icon: 'list' }
|
|
37
|
+
],
|
|
38
|
+
onpick: ({ detail }) => composer.setValue(detail.item.text).focus()
|
|
39
|
+
});
|
|
40
|
+
```
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Prose — `.zx-prose` and `.zx-callout`
|
|
2
|
+
|
|
3
|
+
The reading register for authored content: its own typeface, size, line height, and measure.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/prose · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
The reading register: a class, not a component, that sets authored content — a document, a
|
|
8
|
+
record's notes, a message body, an assistant's answer — in the reading tokens rather than the
|
|
9
|
+
interface ones. Write plain HTML inside it: `h1`–`h4`, `p`, `ul`/`ol`, `blockquote`, `hr`, links,
|
|
10
|
+
inline `code`, `pre`, `kbd`, `mark`, tables, `figure`/`figcaption`, `img`.
|
|
11
|
+
|
|
12
|
+
- **Tokens** — `--zx-font-prose` (the interface stack by default; a serif here leaves the interface
|
|
13
|
+
alone), `--zx-prose-size` (16px, `--zx-text-lg`), `--zx-prose-leading` (1.7), `--zx-prose-measure`
|
|
14
|
+
(62ch, the reading width). Headings scale with the reading size and read `--zx-weight-title`.
|
|
15
|
+
- **Attributes** — `data-size="sm"` sets prose at the interface size, for comments, previews, and
|
|
16
|
+
panels; `data-zx-measure="full"` drops the measure where the column already sets the width.
|
|
17
|
+
- **Rhythm** — one gap between blocks, more above a heading and less below it; links in the body
|
|
18
|
+
colour over a quiet underline, accent on hover; tables without a frame, a muted header over
|
|
19
|
+
hairline rows, `data-align="end"` cells in tabular figures.
|
|
20
|
+
- **Content colour** — a bare `mark` highlights in the amber tone; `mark[data-tone]` in any of the
|
|
21
|
+
nine tones; a bare `span[data-tone]` colours its text, and `data-fill` highlights it as well.
|
|
22
|
+
- **Callout** — `.zx-callout` with an optional `.zx-callout__icon` and a `.zx-callout__body`
|
|
23
|
+
(`.zx-callout__title` for a bold first line): a tinted fill, no frame, at the interface size.
|
|
24
|
+
Neutral by default, because most callouts are emphasis; `data-kind="info|success|warning|danger"`
|
|
25
|
+
makes it a status and `data-tone` a category. Works inside or outside prose.
|
|
26
|
+
- **Specificity** — every rule is `.zx-prose` plus `:where()`, and the stylesheet loads before the
|
|
27
|
+
components, so a badge, an entity reference, or a table placed in prose keeps its own styles,
|
|
28
|
+
while an application's bare element reset cannot undo the rhythm.
|
|
29
|
+
- **Section links** — `proseAnchors(root, options)` ends every `h2`–`h4` with an `id` inside a
|
|
30
|
+
`.zx-prose` under `root` with a small link to itself (`a.zx-prose__anchor`, "Copy link to …").
|
|
31
|
+
It shows while the heading is pointed at or the link has focus (and always on a touch screen or
|
|
32
|
+
under a contrast preference). A click copies the address with the section's hash — the current
|
|
33
|
+
address by default, `href(id)` to build another — and confirms with a tick and a polite "Link
|
|
34
|
+
copied"; it never changes the location, and a middle or modified click is left to the browser.
|
|
35
|
+
Options: `selector`, `label` (`%1` is the heading), `title`, `feedback`, `feedbackDuration`,
|
|
36
|
+
`href`, `oncopy(url, copied)`. It returns `{refresh(), destroy()}`: call `refresh()` after
|
|
37
|
+
re-rendering the content. Headings without an id are skipped — give the ones worth linking a
|
|
38
|
+
stable id. `sectionHref(base, id)` builds the address.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Questionnaire
|
|
2
|
+
|
|
3
|
+
One question at a time, with branching, a path-aware progress bar, and any Zx field type as the answer.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/questionnaire · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
A guided, one-question-at-a-time flow: onboarding intake, a service-call checklist, an audit form,
|
|
8
|
+
a feedback survey. The questionnaire owns the ordered items, the active one, the answers,
|
|
9
|
+
validation, progress and navigation; the page, card, dialog or drawer around it owns closing,
|
|
10
|
+
persistence and transport.
|
|
11
|
+
|
|
12
|
+
The created root is a real `<form>`, so `new FormData(questionnaire.toElement())` reads the
|
|
13
|
+
applicable answers. When enhancing a non-form target, pass its contained `<form>` to `FormData`
|
|
14
|
+
or call `toFormData()`. Choices are native radios and checkboxes carrying the item name, and
|
|
15
|
+
arrow keys inside a choice group use the browser's navigation. Three
|
|
16
|
+
things separate it from a `Form` with one `Fieldset` per question: it branches, its answer control
|
|
17
|
+
can be any registered `Field` type, and its validation may be asynchronous.
|
|
18
|
+
|
|
19
|
+
- **Options** — `items: [{name, prompt, description?, section?, required?, multiple?, skippable?,
|
|
20
|
+
choices?, input?, field?, when?, next?, validate?}]`, `answers: {}` and `active: null` (the
|
|
21
|
+
resume pair), `progress: true`, `review: false`, `advance: 'manual'|'auto'`, `shortcuts: true`,
|
|
22
|
+
`allowBack: true`.
|
|
23
|
+
- **Choices** — `[{value, label, description?, icon?, key?, disabled?, exclusive?}]`. `exclusive`
|
|
24
|
+
is the "None of the above" behaviour: picking it clears the rest of a `multiple` item, and
|
|
25
|
+
picking anything else clears it.
|
|
26
|
+
- **Methods** — `setItems()`, `getItems()`, `goTo(name)`, `next()`, `previous()`, `skip()`,
|
|
27
|
+
`submit()`, `getAnswers()`, `getAnswer(name)`, `setAnswers(values, {silent})`,
|
|
28
|
+
`setAnswer(name, value, {silent})`, `getActive()`, `getPath()`, `getProgress()`, `getState()`,
|
|
29
|
+
`toFormData()`, `reset()`, `focus()`, `destroy()`. `next()`, `skip()` and `submit()` return
|
|
30
|
+
**promises** — `next()` because an item's `validate` may be asynchronous, and `skip()` because
|
|
31
|
+
skipping the last question submits. Everything else is synchronous. Async validation applies
|
|
32
|
+
only to the answer and step it started on; editing, navigating, replacing items, resetting, or
|
|
33
|
+
destroying the questionnaire invalidates a pending result. The last answer is validated once,
|
|
34
|
+
and skipping an optional last question does not validate it again.
|
|
35
|
+
- **Events** — `change {name, value, answers}`, `navigate {from, to, reason}` **preventable**,
|
|
36
|
+
`skip {name}`, `invalid {name, message}`, `submit {answers, path}` **preventable**,
|
|
37
|
+
`complete {answers, path}`.
|
|
38
|
+
- **Branching** — `when(answers)` decides whether an item is asked at all, and `next` (a name, or
|
|
39
|
+
`(answer, answers) => name`) decides what follows. Conditions **cascade**: each predicate sees
|
|
40
|
+
only the answers of visible items declared before it, so hiding the VAT question also hides
|
|
41
|
+
whatever depended on the VAT id. An answer to a conditioned-out question is kept internally —
|
|
42
|
+
walk back into the branch and it is still there — but is left out of `getAnswers()` and
|
|
43
|
+
`toFormData()` and native `new FormData(questionnaire.toElement())`, so an abandoned branch
|
|
44
|
+
never submits stale data. Native form data includes applicable answers from earlier steps too. A `next` naming a hidden item
|
|
45
|
+
walks forward from it rather than stranding the reader; naming an item that does not exist
|
|
46
|
+
throws `RangeError`. `next: '$review'` opens the review screen and `next: '$submit'` submits at
|
|
47
|
+
once, wherever the item stands; an item of that name goes first. A `when`, `next` or `validate`
|
|
48
|
+
that is neither a function nor a declarative form (`false`, `[]`, `{}`) reads as absent, so
|
|
49
|
+
`validate: strict && check` is safe.
|
|
50
|
+
- **Declarative logic** — `when`, `next` and `validate` also take plain JSON, so a questionnaire can
|
|
51
|
+
be stored, sent, or written by an agent; the function forms keep working beside them.
|
|
52
|
+
- A condition is `{field, op, value?}` with `op` one of `eq`, `ne`, `in`, `nin`, `gt`, `gte`,
|
|
53
|
+
`lt`, `lte`, `empty`, `filled`, `contains`, combined with `{all: […]}`, `{any: […]}` and
|
|
54
|
+
`{not: …}`, at most four levels deep. A `when` condition may only name items declared before
|
|
55
|
+
it, and sees only their visible answers, so it cascades like a predicate. A `value` is never
|
|
56
|
+
`null`: an unanswered item has no answer to compare, so test it with `empty` or `filled`. A
|
|
57
|
+
`Date` answer compares by its local date against `YYYY-MM-DD`, and by its local
|
|
58
|
+
`YYYY-MM-DDTHH:MM` against a date-time.
|
|
59
|
+
- `next` may be a list of branches, `[{if: condition, goto: name}, …, {goto: name}]`; the first
|
|
60
|
+
match wins, and no match falls through to the next visible item. A branch condition may also
|
|
61
|
+
name the item itself.
|
|
62
|
+
- `validate` may be a list of rules, each one key plus an optional `message`: `{required: true}`,
|
|
63
|
+
`{minLength: n}`, `{maxLength: n}` (characters, or entries of a multiple answer),
|
|
64
|
+
`{minimum: n}`, `{maximum: n}`, `{format: 'date'|'date-time'|'time'|'email'|'uri'}`,
|
|
65
|
+
`{oneOf: [values]}`. Rules other than `required` pass an empty answer; there are no patterns.
|
|
66
|
+
A `{required: true}` rule marks the item required, like `required: true`.
|
|
67
|
+
A rule's own `message` wins; otherwise its text resolves through `msg()` under
|
|
68
|
+
`questionnaire.rule.<rule>` (`minLength`, `maxLength`, `minItems`, `maxItems`, `minimum`,
|
|
69
|
+
`maximum`, `oneOf`, `date`, `dateTime`, `time`, `email`, `uri`), the same keys a Surface's
|
|
70
|
+
fields use.
|
|
71
|
+
- A malformed condition, branch list or rule list throws `TypeError` when the items are set.
|
|
72
|
+
`evaluate(condition, answers)`, `resolveNext(next, answer, answers)`, `checkRules(rules,
|
|
73
|
+
value)` and the shape checks `checkCondition()`, `checkNext()` and `checkRuleList()` are pure
|
|
74
|
+
exports of `src/components/questionnaire/conditions.js`, for evaluating the same JSON elsewhere.
|
|
75
|
+
|
|
76
|
+
```js
|
|
77
|
+
items: [
|
|
78
|
+
{ name: 'method', prompt: 'How will you pay?', required: true,
|
|
79
|
+
choices: [{ value: 'card', label: 'Card' }, { value: 'transfer', label: 'Bank transfer' }],
|
|
80
|
+
next: [{ if: { field: 'method', op: 'eq', value: 'card' }, goto: '$submit' }] },
|
|
81
|
+
{ name: 'iban', prompt: 'IBAN', input: {},
|
|
82
|
+
when: { field: 'method', op: 'eq', value: 'transfer' },
|
|
83
|
+
validate: [{ required: true }, { minLength: 15, message: 'An IBAN has at least 15 characters.' }] }
|
|
84
|
+
]
|
|
85
|
+
```
|
|
86
|
+
- **Path and progress** — `getPath()` is the questionnaire's memory of the route walked, and
|
|
87
|
+
`previous()` pops it: once a branch has been taken, "previous" is not `index - 1`. `getProgress()`
|
|
88
|
+
returns `{index, answered, total, percent, section}` where `total` is the path plus the items
|
|
89
|
+
still reachable — exact for a static flow, an estimate once a function `next` can jump somewhere
|
|
90
|
+
the forward walk cannot predict.
|
|
91
|
+
- **Field answers** — `field: {type: 'date'|'number'|'zxselect'|'rating'|'upload'|…}` hands the
|
|
92
|
+
answer to a `Field`, so any registered field type works, including ones an application registered
|
|
93
|
+
itself. The `<legend>` already asks the question, so the Field's own label is hidden from sight
|
|
94
|
+
but kept as the control's accessible name unless the item gives `field.label` explicitly; the
|
|
95
|
+
Field draws its own highlight, so a failing answer shows one message, not two.
|
|
96
|
+
- **Validation** — `required` and declarative rules are checked synchronously; a function
|
|
97
|
+
`validate(answer, answers)` may return a message, `null`, or a **promise** of either, and a rejection is reported as its message.
|
|
98
|
+
While the check is pending the root carries `data-state="checking"` and `aria-busy="true"` and
|
|
99
|
+
the actions are disabled.
|
|
100
|
+
- **Review** — `review: true` shows a summary of every answer on the path before submitting, each
|
|
101
|
+
with an Edit that reopens that question; Continue from an edited question comes straight back to
|
|
102
|
+
the review rather than replaying the tail.
|
|
103
|
+
- **Semantics** — the item is a `<fieldset>` and the prompt its `<legend>`; the description and the
|
|
104
|
+
error are associated through `aria-describedby`, the error is a `role="alert"`, and a failing
|
|
105
|
+
item carries `aria-invalid="true"`. `data-state` on the root is
|
|
106
|
+
`asking`, `checking`, `review`, or `complete`. Submitting does not replace the content: it sets
|
|
107
|
+
`data-state="complete"`, hides the actions, and emits `complete`, leaving the thank-you screen to
|
|
108
|
+
the application.
|
|
109
|
+
- **Keyboard** — `1`–`9` then `a`–`z` pick the matching answer, assigned in choice order (an
|
|
110
|
+
explicit `key` is reserved first, so adding one never renumbers the others) and shown as a key
|
|
111
|
+
cap on each choice; the caps are `aria-hidden`, since a screen-reader user moves through the
|
|
112
|
+
group with the arrow keys the radios already provide. `Enter` continues, except in a `multiline`
|
|
113
|
+
input. Shortcuts are suppressed while focus is in a text control. Navigating moves focus to the
|
|
114
|
+
new question's fieldset, which is what gets the prompt announced; failing validation moves it to
|
|
115
|
+
the first answer control instead.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Rating
|
|
2
|
+
|
|
3
|
+
A star rating built as a radio group: one tab stop, arrow-key selection, optional half steps, and a read-only display mode.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/rating · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Star rating built as an APG **radio group**: one radio per selectable step, a single tab stop,
|
|
8
|
+
arrow-key selection. Field type: `rating`.
|
|
9
|
+
|
|
10
|
+
- **Options** — `value: 0` (0 = unrated), `max: 5`, `allowHalf: false` (renders two radios per
|
|
11
|
+
symbol so every reachable value has a nameable control), `clearable: true` (re-selecting the
|
|
12
|
+
current value clears it), `readonly`, `disabled`, `label: 'Rating'`, `icon: 'star'`,
|
|
13
|
+
`labels: []` (per-step accessible names, lowest first), `showValue: false`, `count` (rating
|
|
14
|
+
count shown beside the value), `size: 'sm'|'md'|'lg'`.
|
|
15
|
+
- **Methods** — `get()`, `set(value, {silent})`, `clear()`, `reset()`, `setCount()`,
|
|
16
|
+
`setReadonly()`, `focus()`, `enable()`/`disable()`.
|
|
17
|
+
- **Events** — `change {value}`, `hover {value|null}` (pointer or focus preview; null on leave).
|
|
18
|
+
- **Keyboard** — ←/↓ and →/↑ step, Home selects the first step, End the last, Delete/Backspace
|
|
19
|
+
clear.
|