@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,82 @@
|
|
|
1
|
+
# Design tokens
|
|
2
|
+
|
|
3
|
+
Two tiers of CSS custom properties.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tokens · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Two tiers of CSS custom properties. Dark mode is a pure token/attribute swap
|
|
8
|
+
(`[data-zx-theme="dark"]`), there is one geometry derived from `--zx-space-unit` and
|
|
9
|
+
`--zx-radius`, and `tests/lint-tokens.js` forbids raw colour literals and tier-1 colour references
|
|
10
|
+
in component CSS.
|
|
11
|
+
|
|
12
|
+
- **Tier 1** — the global palette and primitives in `styles/tokens/global.css`: `--zx-gray-0…950`,
|
|
13
|
+
`--zx-emerald-*` (the brand ramp the default accent reads), the status ramps
|
|
14
|
+
`--zx-green/red/amber/blue-*` (green is a yellow-green, deliberately apart from the brand), the
|
|
15
|
+
tone ramps `--zx-tone-<hue>-300/500/700` — none of them referenced by components — plus the
|
|
16
|
+
spacing scale (`--zx-space-unit`, `--zx-space-1…8`), the radius scale (`--zx-radius`,
|
|
17
|
+
`--zx-radius-sm/md/lg/xl/full`), the type scale (`--zx-text-xs…3xl`, 12–30px), weights
|
|
18
|
+
(`--zx-weight-medium` 500, `--zx-weight-semibold` 600), tracking (`--zx-tracking-tight`
|
|
19
|
+
-0.01em, set on `.zx-scope`; `--zx-tracking-title` -0.015em), shadows, and motion
|
|
20
|
+
(`--zx-dur-fast` 120ms, `--zx-dur-base` 180ms — both 0ms in a reduced-motion region — and the
|
|
21
|
+
curves `--zx-ease`, `--zx-ease-spring`, `--zx-ease-drawer`).
|
|
22
|
+
- **Tier 2** — the semantic set, the only tokens components may use: `--zx-color-*`,
|
|
23
|
+
`--zx-control-*`, `--zx-focus-ring`, `--zx-surface-shadow` (the contact shadow of a resting
|
|
24
|
+
surface: a panel, an outlined card in a lane, a slider thumb), `--zx-overlay-shadow`,
|
|
25
|
+
`--zx-drag-shadow` (an item being dragged; its own value in dark, with a faint light rim). The
|
|
26
|
+
lint also rejects the accent ramp `--zx-accent-*`, the module palette `--zx-module-*`, and the
|
|
27
|
+
raw `--zx-shadow-*` steps in component and layout CSS, and any `outline: 0`/`outline: none`:
|
|
28
|
+
forced-colors mode drops the box-shadow focus ring, so components make the outline transparent
|
|
29
|
+
and `styles/base.css` repaints it in a system colour there. The roles that carry the visual
|
|
30
|
+
language:
|
|
31
|
+
- **Columns.** `--zx-color-bg-surface` is the working canvas; `--zx-color-bg-chrome` is the
|
|
32
|
+
navigation and inspector tone beside it (one step below the canvas in light, between page and
|
|
33
|
+
canvas in dark), so tone rather than a line separates them. Dividers inside a column use
|
|
34
|
+
`--zx-color-border-subtle`; `--zx-color-border` is for frames.
|
|
35
|
+
- **Current vs selected.** Where you *are* — the active navigation item, the current row, the
|
|
36
|
+
open node, the active view — is neutral: `--zx-color-bg-current` (translucent text, about 8%,
|
|
37
|
+
so it works on any column), text colour, weight 600. Hover is `--zx-color-bg-hover`, about half
|
|
38
|
+
as strong. What you have *picked* keeps the accent tint `--zx-color-bg-selected`.
|
|
39
|
+
- **Text.** `--zx-color-text`, `--zx-color-text-muted` (secondary text, 4.5:1 on every column and
|
|
40
|
+
on a current row), `--zx-color-text-subtle` (icons and non-essential meta, 3:1),
|
|
41
|
+
`--zx-color-text-placeholder`.
|
|
42
|
+
- **Solid accent.** `--zx-color-accent-solid` (`-hover`, `-active`) with
|
|
43
|
+
`--zx-color-on-accent-solid` is the one primary action per screen: the 600 stop with white ink in
|
|
44
|
+
both themes. `--zx-color-accent` is the accent as text, marks, and focus (600 in light, 400 in
|
|
45
|
+
dark) and pairs with `--zx-color-on-accent` when something is filled with it.
|
|
46
|
+
- **Status.** `--zx-color-success/warning/danger/info` and their `-bg` fills mean state and
|
|
47
|
+
nothing else; they ship with an icon or a word.
|
|
48
|
+
- **Tones.** `--zx-color-tone-{blue,teal,green,amber,orange,red,pink,violet,slate}-bg` and `-fg`:
|
|
49
|
+
categorical colour for tags, chips, icon tiles, and avatars — neither the accent nor a status. A
|
|
50
|
+
soft fill (13% of the tone over the surface in light, 20% in dark) with ink at 4.5:1 or better.
|
|
51
|
+
- **Chart series.** `--zx-color-chart-1…8`, assigned in order, never cycled: blue, orange, teal,
|
|
52
|
+
amber, pink, green, violet, red. Neighbours stay apart under red-green colour-vision deficiency
|
|
53
|
+
and every series clears 3:1 as a mark on the light and the dark surface; the list does not open
|
|
54
|
+
on the accent.
|
|
55
|
+
- **Component styling hooks** — a short, deliberately small set of component-level custom
|
|
56
|
+
properties for restyling one component without touching its internals. Each falls back to the
|
|
57
|
+
semantic token it replaces, so setting none of them changes nothing:
|
|
58
|
+
`--zx-table-header-bg`, `--zx-table-row-hover-bg`, `--zx-table-row-selected-bg`,
|
|
59
|
+
`--zx-table-border-color`, `--zx-table-pin-bg` (the opaque base of pinned columns; the header
|
|
60
|
+
background unless set), `--zx-button-radius`, `--zx-panel-header-bg`, `--zx-message-offset`
|
|
61
|
+
(the distance of floating messages from the viewport edge; `--zx-space-4` unless set).
|
|
62
|
+
`--zx-chart-min-block-size` is public as well, with a fixed 220px default rather than a token.
|
|
63
|
+
Reach for the least specific override that works: a global semantic token first, one of these
|
|
64
|
+
second, an internal selector never. Component CSS declares many other `--zx-<component>-*`
|
|
65
|
+
properties — those are internal geometry, not API, and will change without notice.
|
|
66
|
+
|
|
67
|
+
**Base typography.** `.zx-scope` sets Inter with `--zx-tracking-tight` and the `cv11` feature (the
|
|
68
|
+
single-storey a, chosen because it reads rounder and calmer at 13–14px; fonts without it ignore it).
|
|
69
|
+
|
|
70
|
+
**Quiet fields.** Put `data-zx-fields="quiet"` on a property panel, an inspector, or an inline
|
|
71
|
+
record: native inputs, selects, and textareas inside it drop their border and fill until hover
|
|
72
|
+
(`--zx-color-bg-hover`) or focus (the normal border, the control fill, and the focus ring), so values
|
|
73
|
+
read as text rather than as a wall of boxes. Read-only and disabled fields stay quiet. The rules have
|
|
74
|
+
zero specificity, so a component's own input styling still wins.
|
|
75
|
+
|
|
76
|
+
**Revealed actions.** Mark a row or a section heading `data-zx-reveal-host` and a secondary action
|
|
77
|
+
inside it `data-zx-reveal`: the action rests invisible and appears while the host is pointed at,
|
|
78
|
+
holds focus, is current or selected, or has a menu open. It keeps its space, so nothing shifts, and
|
|
79
|
+
stays in the tab order, so focusing it shows it. On touch screens, under `prefers-contrast: more`
|
|
80
|
+
and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
|
|
81
|
+
that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
|
|
82
|
+
visible. Hosts do not nest.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Toolbar — APG toolbar
|
|
2
|
+
|
|
3
|
+
One tab stop, arrow-key navigation, and an overflow menu that swallows what no longer fits.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/toolbar · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
A single non-wrapping row of controls that is one tab stop: arrows move between the controls, and
|
|
8
|
+
what no longer fits collapses into a trailing overflow menu. Items are `button()` descriptors,
|
|
9
|
+
ready-made Elements, or `'-'` for a separator; a `ResizeObserver` remeasures the row, hides the
|
|
10
|
+
items that overflow — removing them from the tab order and the roving group — and mirrors them into
|
|
11
|
+
a `MenuButton`, where choosing one activates the original control.
|
|
12
|
+
|
|
13
|
+
- **Options** — `items: [Element | '-' | {name, label, icon, kind, size, disabled, title, active,
|
|
14
|
+
onclick}]`, `align: 'start'|'end'|'between'`, `label` (accessible name, by default the `toolbar.label` message),
|
|
15
|
+
`overflow` (default `true`), `overflowLabel` (by default the `toolbar.more` message), `dense`; `null` gives either
|
|
16
|
+
no name. `active` renders the item as a pressed toggle (`aria-pressed`).
|
|
17
|
+
- **Methods** — `setItems()`, `getItem(name)`, `enable(name)`, `disable(name)`,
|
|
18
|
+
`setActive(name, active?)`, `destroy()`.
|
|
19
|
+
- **Events** — `action {name, item}`, emitted for descriptor-built items in addition to their own
|
|
20
|
+
`onclick`, from the row and from the overflow menu alike.
|
|
21
|
+
- **Keyboard** — Tab reaches the toolbar once; ArrowLeft/ArrowRight move between controls and wrap,
|
|
22
|
+
in visual order under `dir="rtl"`; Home/End jump to the first and last control. A text field, select,
|
|
23
|
+
or contenteditable item keeps its own keys: Home/End and the arrows move its caret, and an arrow
|
|
24
|
+
moves on to the neighbouring control only once the caret is at that edge of the text.
|
|
25
|
+
- **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes Button's
|
|
26
|
+
neutral pressed fill and frame, never the accent.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Tooltip
|
|
2
|
+
|
|
3
|
+
A description bubble that stays visible over its anchor or bubble: hover opens it after a beat, keyboard focus opens it at once, and touch leaves it alone.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tooltip · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor's `aria-describedby` includes its id only while it is open — opening adds the id to whatever the attribute holds then, and closing removes only that id, so ids added by others (a field error) stay. The bubble contains no focusable controls and stays visible while the pointer is over either the anchor or the bubble. Keyboard focus on the anchor independently keeps it visible. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
|
|
8
|
+
|
|
9
|
+
- **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
|
|
10
|
+
(`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
|
|
11
|
+
(400), `hideDelay` (80), `maxWidth` (260; a number is pixels, a string is any CSS length),
|
|
12
|
+
`trigger` (`'both'` default, or `'hover'`, `'focus'`, `'manual'` — `manual` installs no listeners
|
|
13
|
+
at all and leaves everything to the methods), `disabled` (false).
|
|
14
|
+
- **Methods** — `show()`, `hide()`, `toggle()`, `isOpen()`, `setContent(content)`, `enable()`, `disable()`, `isDisabled()`, `getAnchor()`, `destroy()`. Convenience factories: `tooltip(anchor, contentOrOptions)` takes either a content value or a full option object, and `describe(anchor, text)` is the one-liner replacement for a `title` attribute. Both return the instance.
|
|
15
|
+
- **Events** — `open`, `close`. Both fire only on a real transition, so a `show()` on an open tooltip is silent.
|
|
16
|
+
- **Keyboard** — Focusing the anchor opens the tooltip at once; it closes after both focus and hover have left the anchor and bubble. `Escape` closes it without moving focus (WCAG 1.4.13 "dismissible") — and only it, when it is the topmost open overlay, so one press never closes a tooltip and the menu beneath it. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it. A closed tooltip listens to nothing outside its anchor; an open one is an entry on the shared overlay stack.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# TreeView
|
|
2
|
+
|
|
3
|
+
A hierarchy following the APG tree pattern: arrow-key navigation, expand and collapse, typeahead, lazy children, and optional tri-state checkboxes.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/tree · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Hierarchical tree implementing the APG **tree** pattern. Rows render as a flat list carrying
|
|
8
|
+
`aria-level`/`aria-setsize`/`aria-posinset` (the flattened variant the APG allows) rather than
|
|
9
|
+
nested `role="group"` containers. The component clones `items`, so lazily loaded children never
|
|
10
|
+
mutate the caller's data.
|
|
11
|
+
|
|
12
|
+
- **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
|
|
13
|
+
`expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
|
|
14
|
+
(tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
|
|
15
|
+
(lazy children; mark a branch with `hasChildren: true` — it counts as open only once its
|
|
16
|
+
children are loaded, so → and `toggle()` load it, `*` loads and opens lazy siblings, and
|
|
17
|
+
`expandAll()`, filtering and `expanded` leave unloaded branches closed), `filter`, `emptyText`, `height`,
|
|
18
|
+
`rowActions: (node) => actions`, `moreLabel`. Unset, `label`, `emptyText` and `moreLabel` read the
|
|
19
|
+
`tree.label`, `tree.noItems` and `tree.more` messages; `tree.empty` still wins over `emptyText`, and
|
|
20
|
+
`emptyText: null` shows no text.
|
|
21
|
+
- **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
|
|
22
|
+
disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
|
|
23
|
+
buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
|
|
24
|
+
menu (a node never folds). They rest out of sight and keep their room, and show while the row is
|
|
25
|
+
pointed at, focused or selected, while its menu is open, and always on a touch screen, under a
|
|
26
|
+
contrast preference and in forced colours — the `data-zx-reveal` utility. Every descriptor is
|
|
27
|
+
also in the row's context menu (right-click, Shift+F10, the Menu key), and each control is named
|
|
28
|
+
after its action and its row ("Add sub-page: Onboarding"); the row's own name stays its label.
|
|
29
|
+
Use them only for repeated, secondary commands that are reachable another way too.
|
|
30
|
+
- **Methods** — `setItems()`, `getItems()`, `getNode(id)`, `getPath(id)`, `setFilter(query)` (keeps
|
|
31
|
+
matching nodes' ancestors and opens the surviving branches),
|
|
32
|
+
`expand(id)`/`collapse(id)`/`toggle(id)` (async — they await the loader),
|
|
33
|
+
`expandAll()`/`collapseAll()`, `reveal(id)`, `select(id, {additive})`,
|
|
34
|
+
`getSelection()`/`setSelection()`/`clearSelection()`, `check(id, checked)`,
|
|
35
|
+
`getChecked({leavesOnly})`, `setChecked()`, `focusNode(id)`.
|
|
36
|
+
- **Events** — `select {node, id, ids}`, `expand`, `collapse`, `activate {node, id}` (Enter or
|
|
37
|
+
double-click), `check {ids, node}`.
|
|
38
|
+
- **Keyboard** — ↑/↓ move, → expands then descends, ← collapses then ascends, Home/End, Enter
|
|
39
|
+
activates, Space selects or toggles the checkbox, `*` expands every sibling, typing jumps to the
|
|
40
|
+
next match. A typed character's default action is prevented, so find-as-you-type and page
|
|
41
|
+
shortcuts do not act on it too; typing into a control inside a row is left to that control.
|
|
42
|
+
With row actions, Tab from the focused row walks that row's actions and then leaves the tree
|
|
43
|
+
(Shift+Tab comes back); keys pressed on an action belong to it, and clicking one neither selects
|
|
44
|
+
nor focuses the row.
|
|
45
|
+
- **Appearance** — the selected node of a single-selection tree is where you are: the neutral
|
|
46
|
+
`--zx-color-bg-current` fill, the text colour, a semibold label. A `selection: 'multi'` tree is a
|
|
47
|
+
set of picks and keeps the accent tint. Icons, folders included, are drawn in
|
|
48
|
+
`--zx-color-text-subtle`; badges are plain muted counts.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# truncate()
|
|
2
|
+
|
|
3
|
+
Clamps text to a number of lines and hands the cut-off text back on hover — because a cell that silently drops the end of a value is a data-loss bug wearing a layout costume.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/truncate · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Clamps text to a number of lines and gives the cut-off text back on hover. The tooltip half is
|
|
8
|
+
what makes it more than a CSS class: a cell that silently drops the end of a value is a data-loss
|
|
9
|
+
bug wearing a layout costume, while a tooltip that is always there is noise.
|
|
10
|
+
|
|
11
|
+
- **Signature** — `truncate(target, {lines, title})` → `{update, isTruncated, destroy}`.
|
|
12
|
+
- **Options** — `lines: 1` (1–10; one line ends in an ellipsis, more clamp the block),
|
|
13
|
+
`title: true` — sets a native `title` **only while the text is actually cut off**, re-measured
|
|
14
|
+
through a `ResizeObserver` on every resize, and restores any previous title on `destroy()`.
|
|
15
|
+
- **Controller** — `update()` re-measures and returns the current state, `isTruncated()` reports
|
|
16
|
+
the last measurement, `destroy()` removes the class, the observer, and any title it set.
|
|
17
|
+
- **Exported helper** — `isTruncated(element)` compares scroll and client sizes on both axes (a
|
|
18
|
+
single line runs out of width, a clamped block runs out of height) with a one-pixel tolerance
|
|
19
|
+
for the sub-pixel difference fractional zoom produces.
|
|
20
|
+
- **Class** — `.zx-truncate` alone does the clamping from static markup with no JavaScript;
|
|
21
|
+
`data-lines` plus `--zx-truncate-lines` select the multi-line form.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# ValueList
|
|
2
|
+
|
|
3
|
+
A chip editor for a list of strings, with per-value validation and drag or keyboard reordering.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/value-list · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Tag/chip input. Enter adds a value, Backspace on an empty input removes the last one, and dragging
|
|
8
|
+
or Ctrl+Arrow reorders.
|
|
9
|
+
|
|
10
|
+
- **Options** — `values: []`, `placeholder`, `deletable: true`, `sortable: true`, `unique: true`,
|
|
11
|
+
`validate: (str)=>bool|string`.
|
|
12
|
+
- **Methods** — `getValues()`, `setValues()`, `addValue()`, `removeValue()`, `focus()`,
|
|
13
|
+
`enable()`/`disable()`.
|
|
14
|
+
- **Events** — `change {values}`, `add {value}`, `remove {value}`.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# ViewSettings — the content of a view-settings drawer
|
|
2
|
+
|
|
3
|
+
The content of a view-settings drawer: arrange and hide the shown fields, add a hidden one back, and choose grouping and the board’s columns and swim lanes.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/view-settings · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Which fields a record view shows and in what order, which hidden field to bring back, what the
|
|
8
|
+
records are grouped by, and which fields a board uses for columns and swim lanes. It is content,
|
|
9
|
+
not a container: put it in a `Sheet`, a `Dropdown`, or a settings page.
|
|
10
|
+
|
|
11
|
+
- **Options** — `fields: ViewSettingsField[]` (a `ViewField` plus `type`, `groupable`, `locked`),
|
|
12
|
+
`fieldOrder`, `hiddenFields`, `groupBy`, `grouping: boolean|{fields?}`,
|
|
13
|
+
`board: {columnBy, swimlaneBy, showEmptyColumns?, fields?}|false` (`fields` restricts the
|
|
14
|
+
Columns and Swim lanes choices; default: the Group by fields), `sections` (order and presence of
|
|
15
|
+
`'fields'|'grouping'|'board'`), `types: Record<type, {icon?, label?}>`, `searchThreshold` (8),
|
|
16
|
+
`headingLevel` (3), `label`, `msg`.
|
|
17
|
+
- **Methods** — `getState()`, `setState(partial, {silent})`, `setFields()`, `getFields()`,
|
|
18
|
+
`showField()`, `hideField()`, `moveField(id, index)`, `bind(view, {board?})`, `unbind()`,
|
|
19
|
+
`focus()`, `destroy()`.
|
|
20
|
+
- **Events** — `change {state, reason: 'order'|'visibility'|'group'|'board'}`,
|
|
21
|
+
`fieldorderchange {order}`, `fieldvisibilitychange {visible, hidden}`, `groupchange {field}`,
|
|
22
|
+
`boardchange {board}`.
|
|
23
|
+
- **State** — `{fieldOrder, hiddenFields, groupBy, board}`: JSON-safe, ready to persist.
|
|
24
|
+
|
|
25
|
+
The shown fields are listed in order, each with a drag handle, its type glyph, and a hide button;
|
|
26
|
+
the hidden ones follow with an explicit **Add** button, which puts the field at the end of the
|
|
27
|
+
shown list. Above `searchThreshold` fields a search narrows the hidden list (label, id, and type
|
|
28
|
+
name, ignoring case and accents) and Enter adds the first match. A `locked` field — the record
|
|
29
|
+
title — has neither handle nor hide button and keeps its place while the others move around it.
|
|
30
|
+
`locked` governs only what the panel offers: a bound view has no such notion, so a locked field the
|
|
31
|
+
view hides itself appears under Hidden with Add like any other. The last shown field cannot be
|
|
32
|
+
hidden.
|
|
33
|
+
|
|
34
|
+
Rows reorder by pointer (mouse, touch, and pen share one path: drag the handle, an insertion line
|
|
35
|
+
shows where it lands, Escape cancels; near the top or bottom edge of the nearest scroll container,
|
|
36
|
+
the container scrolls) and by keyboard on the focused handle: ArrowUp/ArrowDown
|
|
37
|
+
move one step, Home/End to the ends, Space or Enter picks the row up and drops it, Escape returns
|
|
38
|
+
it. Every move is announced in a polite live region ("Owner moved to position 3 of 6"). A redraw
|
|
39
|
+
from outside — `setState()`, `setFields()`, a bound view's change — cancels a pick-up or drag in
|
|
40
|
+
progress (announced) and keeps focus on the same field's control.
|
|
41
|
+
|
|
42
|
+
The type glyph comes from a built-in map that `types` extends: text, number (int, float,
|
|
43
|
+
percent), money, date, datetime, time, boolean, select (enum), status, priority, entity, tags,
|
|
44
|
+
url, email, image, file, rating. The type name is the glyph's `title` and visually hidden text,
|
|
45
|
+
so it is seen and heard. Grouping and the board offer fields with `groupable !== false` and a
|
|
46
|
+
discrete type (text, select, status, priority, boolean, entity), or `groupable: true`;
|
|
47
|
+
`grouping.fields` restricts the Group by choices.
|
|
48
|
+
|
|
49
|
+
`bind(view)` connects a `TableView`, `CardView`, or `KanbanView`: it reads the view's fields and
|
|
50
|
+
state, pushes order and visibility through `setFieldOrder()`/`setFieldVisible()`, and follows the
|
|
51
|
+
view's own `statechange`; `unbind()` releases the view. A panel given its own `fields` lists
|
|
52
|
+
those and no others (the title a card draws is not a column to offer); given none, it lists every
|
|
53
|
+
field the view has. The view's labels and types win over the panel's descriptors, which add only
|
|
54
|
+
`locked`, `groupable`, and a type where the view has just the `'text'` default. While bound the view owns the field list: call the view's `setFields()` — the
|
|
55
|
+
panel's own `setFields()` is not pushed and lasts until the view's next change. Grouping and board
|
|
56
|
+
changes are only emitted — the host applies them.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# WorkspaceSwitcher
|
|
2
|
+
|
|
3
|
+
The current workspace at the head of a navigation column — tile, name, and secondary line — opening a menu of the workspaces with the current one checked, then the application’s own actions.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/workspace-switcher · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
Composes `AppIcon` and `MenuButton` into the workspace switcher at the head of a navigation column:
|
|
8
|
+
a trigger with the current workspace's tile, name and secondary line, opening an APG menu of the
|
|
9
|
+
workspaces with the current one checked, then the application's own actions. Zx never decides
|
|
10
|
+
which workspaces a user may see, loads another workspace, or changes the session — switching is a
|
|
11
|
+
cancelable event the application acts on.
|
|
12
|
+
|
|
13
|
+
- **Options** — `workspaces: [{id, label, secondary?, icon?, tone?, color?, src?, initials?, badge?,
|
|
14
|
+
disabled?}]` (the tile is the image, else the icon, else the initial, on the tone — derived from
|
|
15
|
+
the label when neither `tone` nor `color` is given), `active` (defaults to the first enabled
|
|
16
|
+
workspace, which also replaces an id that is not listed or is disabled), `items` (actions after
|
|
17
|
+
the workspaces; the separator between them is added for you), `compact: false`, `heading` (null
|
|
18
|
+
resolves message `workspaceSwitcher.heading`, "Workspaces"; `''` leaves it out), `label` (`%1` is
|
|
19
|
+
the active workspace's name, filled in again after every switch; null resolves
|
|
20
|
+
`workspaceSwitcher.label`, "Switch workspace: %1", or `workspaceSwitcher.labelEmpty`, "Switch
|
|
21
|
+
workspace", while no workspace is active), and any `placement` (default `bottom-start`).
|
|
22
|
+
- **Messages** — `workspaceSwitcher.heading`, `workspaceSwitcher.label` (`%1` the workspace name),
|
|
23
|
+
`workspaceSwitcher.labelEmpty`; override them per instance through `msg`, or for every instance
|
|
24
|
+
through `setTranslator()`.
|
|
25
|
+
- **Methods** — `getActive()`, `setActive(id, {silent = true})` (`silent: false` emits `select`
|
|
26
|
+
first), `setWorkspaces(list)` (keeps the active workspace while it is still listed and enabled,
|
|
27
|
+
else the first enabled one becomes active), `setItems()`,
|
|
28
|
+
`setCompact(compact)`, `open()`, `close()`, `toggle()`, `isOpen()`, `focus()`, `getPanel()`,
|
|
29
|
+
`destroy()`.
|
|
30
|
+
- **Events** — cancelable `select {workspace, id, previous}`: a canceled switch keeps the previous
|
|
31
|
+
workspace active and the menu open. Cancelable `action {value, item}` for the extra items: a
|
|
32
|
+
canceled action does not run the item's callback. Both honour `preventDefault()` on the component
|
|
33
|
+
event and on the bubbling `zx-select` / `zx-action` DOM event alike. `open` and `close`. Choosing the current
|
|
34
|
+
workspace again only closes the menu.
|
|
35
|
+
- **Semantics** — one native `<button aria-haspopup="menu" aria-expanded>` trigger, named "Switch
|
|
36
|
+
workspace: <name>" (or the custom `label`) in both states; compact mode shows the tile alone and adds the name as its
|
|
37
|
+
`title`. Workspaces are `menuitemradio` rows with `aria-checked` under a presentational heading;
|
|
38
|
+
MenuButton keeps focus return, typeahead and the arrow-key map.
|
|
39
|
+
- **Appearance** — the trigger is a flat full-width row (tile, name, secondary line, chevron) with
|
|
40
|
+
the hover fill, at least a control and a space-2 tall; its tile is the module bar's tile size, so
|
|
41
|
+
as an `AppSidebar` `railHeader` it lines up with the module tiles under it. Keep it in step with a
|
|
42
|
+
modules sidebar by calling `setCompact(presentation !== 'expanded')` on `presentationchange`.
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# ZeyOS binding (zx-zeyos)
|
|
2
|
+
|
|
3
|
+
`zx-zeyos` is the optional schema-driven layer above `@zeyos/client`: inject a client instance and declare a resource to generate typed Zx controls.
|
|
4
|
+
|
|
5
|
+
Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/layouts.html#zeyos-invoices · All components: https://zx.zeyos.com/docs/components/index.md
|
|
6
|
+
|
|
7
|
+
`zx-zeyos` is the optional schema-driven layer above `@zeyos/client`: inject a client instance and
|
|
8
|
+
declare a resource to generate typed Zx controls. It is a separate ESM entry at
|
|
9
|
+
`dist/zx-zeyos.esm.js` (or `src/zeyos/index.js` during no-build development) and is deliberately
|
|
10
|
+
not re-exported from `src/index.js`. The binding has zero runtime dependencies and never imports or
|
|
11
|
+
bundles `@zeyos/client`; the application owns client creation, authentication, and transport.
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
import { createZeyosClient } from '@zeyos/client';
|
|
15
|
+
import {
|
|
16
|
+
connect, createLegacySavedViewTransport, createSavedViewRegistry,
|
|
17
|
+
dataFilterStateToFilters, legacySavedViewRequest, zeyosForm, zeyosSelect, zeyosTable, zeyosView
|
|
18
|
+
} from '/assets/zx-zeyos.esm.js';
|
|
19
|
+
import { CardView, TableView } from '/assets/zx.esm.js';
|
|
20
|
+
|
|
21
|
+
const client = createZeyosClient({ platform, auth });
|
|
22
|
+
const api = connect(client, { locale: 'en-GB' });
|
|
23
|
+
|
|
24
|
+
const list = zeyosTable(client, 'transactions', {
|
|
25
|
+
fields: ['transactionnum', 'account', 'date', 'netamount', 'status'],
|
|
26
|
+
sort: { id: 'date', dir: 'desc' },
|
|
27
|
+
selectable: 'multi'
|
|
28
|
+
});
|
|
29
|
+
await list.load();
|
|
30
|
+
|
|
31
|
+
const editor = zeyosForm(client, 'transactions', {
|
|
32
|
+
fields: ['transactionnum', 'account', 'date', 'netamount', 'status'],
|
|
33
|
+
onSaved: () => list.load()
|
|
34
|
+
});
|
|
35
|
+
await editor.load(transactionId);
|
|
36
|
+
await editor.save();
|
|
37
|
+
|
|
38
|
+
const records = zeyosView(client, 'transactions', TableView, {
|
|
39
|
+
fields: ['transactionnum', 'account', 'date', 'netamount', 'status'],
|
|
40
|
+
savedViews: {
|
|
41
|
+
transport: savedViewTransport,
|
|
42
|
+
scope: { userId: currentUserId, workspaceId: currentWorkspaceId }
|
|
43
|
+
}
|
|
44
|
+
});
|
|
45
|
+
await records.ready; // restores a compatible default before the first list request
|
|
46
|
+
await records.load();
|
|
47
|
+
await records.saveView({ name: 'My open invoices', setDefault: true });
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- `connect(client, { onError, locale })` returns `{client, list, get, create, update, reportError}`;
|
|
51
|
+
generated forms/tables use the same operation discovery and default `Message.error` reporting.
|
|
52
|
+
- `zeyosSelect(client, resource, opts)` returns an async Zx `Select`. Options include `fields`,
|
|
53
|
+
`labelKey`, `valueKey`, `searchFields`, `filters`, `limit`, and normal Select options. Its list
|
|
54
|
+
operation receives a query built by `buildListQuery`.
|
|
55
|
+
- `zeyosForm(client, resource, opts)` returns
|
|
56
|
+
`{form, ready, load(id), save(), getForm(), destroy()}`. `fields` is an ordered allow-list;
|
|
57
|
+
`exclude`, `labels`, `formats`, `timeZone`, `title`, `columns`, `value|id`, and `onSaved` curate
|
|
58
|
+
behavior. `load` maps stored timestamps to `Date`; `save` validates and creates/updates, maps back
|
|
59
|
+
to Unix seconds, calls `onSaved`, and shows a success toast. Its toasts (that confirmation and a
|
|
60
|
+
failed request's report) appear in the theme scope of `scope` — default: the form's own element,
|
|
61
|
+
so a form in a scoped dialog toasts inside that scope, and the confirmation stays there when
|
|
62
|
+
`onSaved` closes and destroys the dialog; `notify: false` raises none, leaving the
|
|
63
|
+
promise's result or rejection to the caller.
|
|
64
|
+
- `zeyosTable(client, resource, opts)` returns
|
|
65
|
+
`{table, load(), setSearch(), setFilters(), loadMore(), count, page, pageSize, hasMore, destroy()}`.
|
|
66
|
+
Columns come from schema metadata, sorting uses `sortMode:'server'`, and paging is zero-based with
|
|
67
|
+
`pageSize: 50` by default: page zero replaces rows while later pages append them using server
|
|
68
|
+
`limit`/`offset` and `count`; `load({page, pageSize, replace: true})` replaces at any page. A
|
|
69
|
+
one-based `Pagination` maps onto it as `load({page: detail.page - 1, pageSize: detail.pageSize,
|
|
70
|
+
replace: true})` (offset `(page - 1) * pageSize`), feeding `result.count` back through
|
|
71
|
+
`setTotal()`. A response that resolves after `destroy()` is ignored and later loads reject; page
|
|
72
|
+
must be a non-negative integer and page size a positive integer (`RangeError`), filters an object
|
|
73
|
+
(`TypeError`), and every argument is checked before any is applied, so a rejected call changes
|
|
74
|
+
nothing. Table presentation options and
|
|
75
|
+
listeners pass through — `variant`, `zebra`, `stickyHeader`, `responsive`, `growing`, `emptyText`,
|
|
76
|
+
`rowClass`, `rowKind(s)`, `columnVisibility`, `columnReorder`, `hiddenColumns`, `on<event>`;
|
|
77
|
+
`onrowclick` runs beside `onRowClick`. The binding owns `columns`, `data`, and `sortMode`, and
|
|
78
|
+
leaves out editing, `rowReorder`, and `hierarchy`, which change rows it never persists.
|
|
79
|
+
- `buildZeyosViewConfig(client, resource, opts)` resolves one schema to shared `ViewField[]`, a
|
|
80
|
+
complete projection, and view options. `zeyosView(client, resource, CardView|TableView|KanbanView,
|
|
81
|
+
opts)` returns `{view, load(), setSearch(), setFilters(), loadMore(), count, page, hasMore,
|
|
82
|
+
savedViews, ready, restoreDefault(), captureView(), saveView(), applyView(), destroy()}` with
|
|
83
|
+
paging and server sort. Paging is the same loader as `zeyosTable()` — same `pageSize: 50` default,
|
|
84
|
+
validation, `replace`/`pageSize` load options, and destroy guard. Title, preview, group, column, and swim-lane fields stay in the projection
|
|
85
|
+
even when hidden. Without `savedViews`, the host may persist `view.getViewState()` directly.
|
|
86
|
+
`savedViewFallback: 'error'` is the default: a saved-view initialization failure blocks loads.
|
|
87
|
+
Opt into `'baseline'` to load records using the configured query and sort when the registry
|
|
88
|
+
cannot be read. The failure is reported and `ready` still rejects; capture, save, apply, and
|
|
89
|
+
default restoration remain blocked. Later operations retry initialization so repaired storage
|
|
90
|
+
can restore its default. The unreadable document is never rewritten automatically, and a
|
|
91
|
+
failure while applying a view or query cannot fall back.
|
|
92
|
+
- `createSavedViewRegistry(transport, {userId,workspaceId,resource})` coordinates private named
|
|
93
|
+
Table/Card/Kanban configurations as one versioned, atomically replaced document. Entries capture
|
|
94
|
+
component state plus filters/search and an explicit presentation type, never records, selection,
|
|
95
|
+
pages, callbacks, or DOM. Duplicate names, defaults, migration, type mismatch, failed writes, and
|
|
96
|
+
teardown are explicit. `workspaceId:null` addresses ZeyOS's base workspace.
|
|
97
|
+
- `createLegacySavedViewTransport(request)` reuses the authenticated `fields`, `fields_save`, and
|
|
98
|
+
`fields_remove` endpoints through one reserved, namespaced `userfields` record.
|
|
99
|
+
`legacySavedViewRequest(PG.load.bind(PG))` is the optional Promise bridge for a legacy host. The
|
|
100
|
+
scope's `userId` is intentionally not sent to the endpoint; the server session remains authority.
|
|
101
|
+
|
|
102
|
+
Field mapping is schema-driven: entity/FK → async `zxselect`; enum/list → `optionlist` or native
|
|
103
|
+
`select` with readable labels (a schema `{value, label}` as given, a stored constant in sentence
|
|
104
|
+
case — `INVOICED` → "Invoiced", `PARTLYPAID` → "Partly paid"); date-only bigints (indexed `date`,
|
|
105
|
+
`duedate`, `birthdate`, `datefrom`/`dateto` outside appointments and events, `datecancel`,
|
|
106
|
+
`lastbilling`) → `date`; other date/time bigints and `lastmodified` → `datetime`;
|
|
107
|
+
`formats: { field: 'date' }` overrides the guess; money/price/numeric
|
|
108
|
+
→ right-aligned `float`/number columns (amount columns use the row currency); boolean/checked →
|
|
109
|
+
`toggle` and a check column; percent/progress → numeric percent; email/tel/url → typed text; arrays
|
|
110
|
+
→ `valuelist`; long text/JSON → `textarea`; short scalar text → `text`.
|
|
111
|
+
|
|
112
|
+
ZeyOS queries always use `filters` (plural), not `filter`. Full-text input becomes `query`; sort is
|
|
113
|
+
sent as signed server fields (`+field`/`-field`); projection supports aliases and dot joins; and
|
|
114
|
+
search/filter/sort/pagination remain server-side. ZeyOS timestamps are integer Unix seconds, so
|
|
115
|
+
forms convert them to/from `Date`. A date-only field stores midnight of a calendar day in the
|
|
116
|
+
instance's zone — a day, not an instant: tables show it with no time, and forms edit it as that day,
|
|
117
|
+
so neither the viewer's zone nor daylight saving moves it. Pass the instance's IANA zone as
|
|
118
|
+
`timeZone` (table, form, view; default: the runtime's own); `unixSecondsToCalendarDay(seconds, tz)`
|
|
119
|
+
and `calendarDayToUnixSeconds(date, tz)` do the same conversion for application code. Use
|
|
120
|
+
`dataFilterStateToFilters(state, defs, {timeZone})` before `tableBinding.setFilters(...)` when wiring
|
|
121
|
+
a `DataFilter`: with `timeZone`, a `format: 'date'` value (`Date` or `YYYY-MM-DD`) becomes that
|
|
122
|
+
day's midnight in the zone, as forms store it, while `datetime` values stay instants; without it,
|
|
123
|
+
dates convert as exact instants. `FilterPanel` takes the same `timeZone` option.
|
|
124
|
+
|
|
125
|
+
## Module icons and colours
|
|
126
|
+
|
|
127
|
+
`src/zeyos/modules.js` is the configuration file for module identity — one entry per ZeyOS module,
|
|
128
|
+
holding the icon and the colour it is drawn in:
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
notes: { label: 'Notes', icon: 'zeyos-notes', color: '#008853', fa: 'note-sticky' }
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`icon` is the glyph's name in the ZeyOS Font Awesome kit (61 custom `zeyos-*` icons, rendered as
|
|
135
|
+
`<i class="fa-kit fa-zeyos-notes">`); `fa` is a stock Font Awesome fallback that also exists in
|
|
136
|
+
Font Awesome Free. Colours are the ZeyOS runtime palette (`ICO.Colors`) where ZeyOS defines one and
|
|
137
|
+
Zx defaults elsewhere; they are also emitted as `--zx-module-*` CSS custom properties, generated
|
|
138
|
+
from this file by `tools/build-module-tokens.js` and checked by the unit tests.
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
import { moduleChip, moduleColor, registerModules, useZeyosIcons } from '/assets/zx-zeyos.esm.js';
|
|
142
|
+
|
|
143
|
+
await useZeyosIcons(); // loads ZEYOS_ICON_KIT, switches Zx to Font Awesome
|
|
144
|
+
nav.append(moduleChip('tickets', { size: 24, title: true })); // glyph on the module colour
|
|
145
|
+
moduleColor('invoices'); // '#535494' — aliases resolve to their module
|
|
146
|
+
registerModules({ tickets: '#f04639', 'my-fork': { label: 'My Fork', icon: 'zeyos-weblets' } });
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
- `moduleIcon(name, {size, label, standard})` → the bare glyph; `standard: true` uses the stock
|
|
150
|
+
Font Awesome fallback, for pages on a kit without the ZeyOS uploads. Stock Font Awesome
|
|
151
|
+
CSS or kit assets must still be loaded by the host.
|
|
152
|
+
- `moduleChip(name, {size, iconSize, label, title, standard})` → `<span class="zx-module-icon">`
|
|
153
|
+
with a centred white glyph on the module colour. `moduleGlyphColor(hex)` remains available as a
|
|
154
|
+
separate contrast helper for non-AppIcon integrations that deliberately choose their foreground.
|
|
155
|
+
- `moduleInfo`/`moduleColor`/`moduleIconName`/`moduleKeys`/`normalizeModuleName` read the config.
|
|
156
|
+
Module, entity, and API resource names are all accepted, case-insensitively, with dots and
|
|
157
|
+
underscores normalized: `'transactions.billing'`, `'invoices'`, and `'Transactions Billing'` all
|
|
158
|
+
land on `transactions-billing`. Unknown names fall back to the `default` module — lookups never
|
|
159
|
+
throw.
|
|
160
|
+
- `registerModules(map)` adds forks and weblets or overrides shipped entries (a bare string sets
|
|
161
|
+
the colour only). Runtime ZeyOS menu data is authoritative: feed its colours in at startup.
|
|
162
|
+
|
|
163
|
+
## Module bar from the ZeyOS menu
|
|
164
|
+
|
|
165
|
+
The module bar and the module-layout sidebar read the same shell state the launcher does, plus
|
|
166
|
+
each module's menu and its counts:
|
|
167
|
+
|
|
168
|
+
```js
|
|
169
|
+
import { buildZeyosAppSidebarConfig, buildZeyosModuleBarConfig } from '/assets/zx-zeyos.esm.js';
|
|
170
|
+
import { AppSidebar, ModuleBar } from '/assets/zx.esm.js';
|
|
171
|
+
|
|
172
|
+
const state = {
|
|
173
|
+
modules: ['messages', 'tasks', 'billing', 'contacts', 'calendar', 'tickets'],
|
|
174
|
+
pinned: ['messages', 'tasks', 'billing', 'tickets'], // the rest are under "All modules"
|
|
175
|
+
activeIdentifier: 'tickets',
|
|
176
|
+
active: 'tickets-mine', // a menu entry, when more precise
|
|
177
|
+
canUseModule: (module) => permissions.has(module),
|
|
178
|
+
menus: { tickets: [{ id: 'tickets-mine', label: 'My tickets' }, ['tickets-all', 'All tickets', '#tickets']] },
|
|
179
|
+
badges: { messages: 7, 'tickets-mine': 3 },
|
|
180
|
+
resolveApplication: (app) => ({ href: routeFor(app) })
|
|
181
|
+
};
|
|
182
|
+
new AppSidebar(nav, buildZeyosAppSidebarConfig(state, { onselect: route }));
|
|
183
|
+
new ModuleBar(header, buildZeyosModuleBarConfig(state, { orientation: 'horizontal', side: 'top' }));
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
- `zeyosModuleItems(state, {standardIcons})` → `ModuleItem[]`: every permitted module, fork, and
|
|
187
|
+
weblet, with its kit icon (or `renderApplicationIcon(app, normalized)`), its colour — the
|
|
188
|
+
payload's, else the registry's, so `registerModules()` reaches the bar — its menu from
|
|
189
|
+
`menus[identifier]` (objects or `[id, label, href]` arrays, sections, nesting; unsafe hrefs are
|
|
190
|
+
disabled), its badge from `badges`, `pinned` from the pinned order, and forks and weblets in
|
|
191
|
+
their own catalogue group (`labels.forks`, `labels.weblets`). A module with a menu is a panel
|
|
192
|
+
module; one without is a destination.
|
|
193
|
+
- `buildZeyosModuleBarConfig(state, options)` → ModuleBar options; `buildZeyosAppSidebarConfig()`
|
|
194
|
+
→ AppSidebar options in `layout: 'modules'`. Both draw the classic ZeyOS identity tiles
|
|
195
|
+
(`appearance: 'solid'`) unless told otherwise. `zeyosModuleBar(target, state, options)` creates
|
|
196
|
+
the bar directly.
|