@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,299 @@
|
|
|
1
|
+
# Xenon Design System (Zx) — small reference
|
|
2
|
+
|
|
3
|
+
> Xenon is a dependency-free design system for browser applications; Zx is its vanilla-JavaScript
|
|
4
|
+
> implementation. This is the small tier of its agent documentation: how every component works,
|
|
5
|
+
> which layout and which component a screen needs, what never to build, and how a model composes
|
|
6
|
+
> surfaces at runtime. Each component has its own file, listed at the end; the complete reference is
|
|
7
|
+
> https://zx.zeyos.com/docs/llms.md.
|
|
8
|
+
|
|
9
|
+
## Mental model
|
|
10
|
+
|
|
11
|
+
Every visual component is an ES class extending `Component`, instantiated identically:
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
import { Table, Dialog, Toggle } from '/assets/zx.esm.js'; // or window.zx.* from zx.global.js
|
|
15
|
+
const t = new Table(target, options);
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- **`target`** — an `Element`, a selector string, or `null`. `null` means the component creates and
|
|
19
|
+
**owns** its root element; retrieve it with `t.toElement()` (or `t.el`) and insert it. A non-null
|
|
20
|
+
target is *enhanced in place* and restored on `destroy()`.
|
|
21
|
+
- **Options** — a plain object; each component declares `static defaults`. Never mutate the passed
|
|
22
|
+
object. An option passed as `undefined` is an option not passed: it keeps the declared default,
|
|
23
|
+
at the top level and inside `msg`, so a wrapper can forward `{ label: props.label }` without
|
|
24
|
+
filtering unset props. `null` is a value and overrides the default. The merged options are
|
|
25
|
+
frozen; change a live component through its methods (see "Using Zx from a framework").
|
|
26
|
+
- **Value/data** — set via constructor options and mutated via methods (`set`, `setData`, …);
|
|
27
|
+
read via getters/methods (`.value`, `getValues()`, …).
|
|
28
|
+
|
|
29
|
+
### Events & lifecycle
|
|
30
|
+
|
|
31
|
+
- Subscribe with `t.on('change', fn)` (alias `addEvent`), `t.once(...)`, or an `on<type>` function
|
|
32
|
+
**option** (`onchange`, `onrowclick`, …). Handlers receive a `CustomEvent`; read `event.detail`
|
|
33
|
+
(always an object, e.g. `{ value, item }`).
|
|
34
|
+
- Every `emit` also dispatches a **bubbling, composed** `zx-<type>` `CustomEvent` on `t.el`, so
|
|
35
|
+
`t.el.addEventListener('zx-change', …)` and event delegation work.
|
|
36
|
+
- Mutation boundaries may opt into honoring cancellation of that mirrored DOM event; Kanban's
|
|
37
|
+
`zx-recordmove` does, so delegated hosts can veto a move without a component reference.
|
|
38
|
+
- `t.destroy()` aborts all listeners (one AbortController), unregisters the element, and removes an
|
|
39
|
+
owned root. `Component.from(el)` returns the component for a root element (replaces the legacy
|
|
40
|
+
`el.retrieve('com')`).
|
|
41
|
+
|
|
42
|
+
## Start from a layout, not a blank page
|
|
43
|
+
|
|
44
|
+
Every layout in the gallery (<https://zx.zeyos.com/layouts>, `layouts.html#<id>` opens one,
|
|
45
|
+
`layout.html#<id>` shows it alone) is a complete, working screen on one shared application shell,
|
|
46
|
+
and its source is public: `https://zx.zeyos.com/layouts/<id>.layout.js` with `<id>.layout.css`
|
|
47
|
+
(in the repository, `website/layouts/`). Open the closest one, keep its anatomy — the columns,
|
|
48
|
+
the pane headers, the toolbar, the drawers, the states, the keyboard map — and change the data,
|
|
49
|
+
the fields, and the copy.
|
|
50
|
+
|
|
51
|
+
The helpers a layout imports are public too, and meant to be copied beside application code
|
|
52
|
+
(they are documentation-site modules, not package exports; import them relatively):
|
|
53
|
+
|
|
54
|
+
- `layouts/kit.js` + `kit.css` — the shell: `.shell` and its columns, `paneHeader()`,
|
|
55
|
+
`propList()`, `.list-row`, `.surface`, `suiteNav()` (module strip + module menu, with a
|
|
56
|
+
`workspace` switcher), `adaptiveShell()` (every column stays reachable at any width),
|
|
57
|
+
`shortcuts()` and `shortcutSheet()` (`?`), `toast()`, `loadChartJs()`.
|
|
58
|
+
- `layouts/overview.js` + `overview.css` — `createOverview()`: one toolbar over one record set
|
|
59
|
+
shown as table, list, cards, gallery, or board; search; filters as editable chips with a Filters
|
|
60
|
+
drawer; a View settings drawer; grouping, sorting, paging, selection and bulk actions; a base
|
|
61
|
+
filter for tabs and scopes; split empty states. The record collection, CRM, and issue tracker
|
|
62
|
+
are all this one composition.
|
|
63
|
+
|
|
64
|
+
Which layout a screen is:
|
|
65
|
+
|
|
66
|
+
| The screen | Start from | Not from |
|
|
67
|
+
| --- | --- | --- |
|
|
68
|
+
| A list of records of one type (companies, tickets, orders, files) | **Record collection** (`record-collection`) — the toolbar, chips, drawers and pager come with it | a bare `Table` under a heading |
|
|
69
|
+
| A list beside the record being edited | **Master–detail** (`master-detail`) | two unrelated panes |
|
|
70
|
+
| One record on its own page | **Record page** (`record-page`) | a form |
|
|
71
|
+
| Figures, charts, a period switch | **Dashboard** (`dashboard`) | cards of big numbers |
|
|
72
|
+
| Settings in sections | **Settings workspace** (`settings-workspace`) | one long form |
|
|
73
|
+
| Creating something in steps | **Record wizard** (`record-wizard`, vertical steps) or **Checkout wizard** (`checkout-wizard`, horizontal) | tabs |
|
|
74
|
+
| Conversations, triage | **Inbox** (`inbox`) or the **Mail** template | — |
|
|
75
|
+
| An assistant | **Agent chat** (`agent-chat`, one run with tools and approvals) or the **AI chat** template | a chat bubble list |
|
|
76
|
+
| Empty, loading, error, offline, confirmation | **System states** (`system-states`) — every screen needs these; copy them | ad-hoc messages |
|
|
77
|
+
| A whole application | the closest **template** below; they share one shell | a new shell |
|
|
78
|
+
|
|
79
|
+
Templates — complete applications with navigation, lists, records, and editors together:
|
|
80
|
+
|
|
81
|
+
| id | Screen | Use it for |
|
|
82
|
+
| --- | --- | --- |
|
|
83
|
+
| `mail` | Mail | a keyboard-first inbox: split streams, one-key triage, snooze, inline reply |
|
|
84
|
+
| `issue-tracker` | Issue tracker | work items grouped by status or on a board, chips, sub-items, activity, properties edited in place |
|
|
85
|
+
| `wiki` | Knowledge base | nested pages in spaces, a reading column with a live outline, comments, Markdown editing |
|
|
86
|
+
| `ai-chat` | AI chat | chat with an assistant: tool steps, sources, artifacts with versions, per-chat settings |
|
|
87
|
+
| `agent-workspace` | Agent workspace | a team of agents: roster with presence, plans and logs, approvals, a palette, a terminal |
|
|
88
|
+
| `invoice-editor` | Invoice editor | a document edited beside its live page, totals per rate, a send step that locks it |
|
|
89
|
+
| `item-inventory` | Item & inventory | one master-data record: levels per location, linked documents, tabbed settings, a log |
|
|
90
|
+
| `workflows` | Workflows | recurring processes as step flows: built, run, measured |
|
|
91
|
+
| `infrastructure` | Infrastructure | monitoring: health, alerts, traffic, drill-down to the unit |
|
|
92
|
+
| `crm` | CRM | companies, people, deals: editable collections with saved views, record pages, a stage board |
|
|
93
|
+
|
|
94
|
+
Patterns — single screens that recur in every application:
|
|
95
|
+
|
|
96
|
+
| id | Screen | What it shows |
|
|
97
|
+
| --- | --- | --- |
|
|
98
|
+
| `master-detail` | Master–detail | a filterable list beside the record being edited; save, revert, unsaved-change checks |
|
|
99
|
+
| `record-collection` | Record collection | one record type as table, list, cards, gallery, and board under one toolbar; filter chips and drawers |
|
|
100
|
+
| `dashboard` | Dashboard | figures, a chart, tabbed detail, one period switch redrawing all of it |
|
|
101
|
+
| `inbox` | Inbox | three panes: folders, conversations, the open thread with a reply |
|
|
102
|
+
| `record-page` | Record page | one record: summary header, tabs for lines, files and history, editable details |
|
|
103
|
+
| `agent-chat` | Agent chat | one agent run: plan, tool calls, an approval that holds it, a streamed answer with sources |
|
|
104
|
+
| `agent-canvas` | Agent canvas | every answer a `surface/1` document — figures and a chart, a review, forms, a questionnaire — with its JSON, versions and reply in a panel |
|
|
105
|
+
| `record-wizard` | Record wizard | creation in validated vertical steps with a running total and a review |
|
|
106
|
+
| `checkout-wizard` | Checkout wizard | a focused horizontal flow beside a live summary |
|
|
107
|
+
| `settings-workspace` | Settings workspace | personal settings in sections, saved together |
|
|
108
|
+
| `system-states` | System states | every empty, loading, error, and confirmation state, with an offline switch |
|
|
109
|
+
| `zeyos-invoices` | ZeyOS invoices | a table and a form generated from the ZeyOS schema, beside the ZeyOS module navigation |
|
|
110
|
+
|
|
111
|
+
Every application shares one shell: `AppSidebar` (or `ModuleBar` for the module level) with
|
|
112
|
+
`AccountMenu`, a `WorkspaceSwitcher` where users have several workspaces, a `Launcher` as the
|
|
113
|
+
command palette, `?` for the shortcut sheet, and `data-zx-theme` honoured throughout. Do not design
|
|
114
|
+
a second navigation.
|
|
115
|
+
|
|
116
|
+
## The component for the job
|
|
117
|
+
|
|
118
|
+
| Job | Use | Rather than |
|
|
119
|
+
| --- | --- | --- |
|
|
120
|
+
| Records the user scans, sorts, selects | `Table`; `TableView` when the same records also appear as cards or a board | a styled `<table>`, a list of `<div>`s |
|
|
121
|
+
| Records as cards or a gallery | `CardView` (`keyboard: 'roving'`, `groupBy`, `collapsibleGroups`) | `Card`s in a CSS grid |
|
|
122
|
+
| Records by stage, dragged between columns | `KanbanView` | — |
|
|
123
|
+
| One record set, several presentations, one state | `RecordView` family + `ListToolbar` + `ViewSettings` + `Pagination` — `createOverview()` wires them | three components with three states |
|
|
124
|
+
| The bar above a record view | `ListToolbar` (search, live count, view switch, badged tools) | a row of buttons |
|
|
125
|
+
| Sorting outside a header | `SortControl` | two selects |
|
|
126
|
+
| Paging | `Pagination` (`paginationRange()` for the numbers) | — |
|
|
127
|
+
| Filters, quick and client-side | `DataFilter` | — |
|
|
128
|
+
| Filters typed from a server's field metadata | `FilterPanel` (`mode: 'draft'|'live'`) | — |
|
|
129
|
+
| Filters the user composes, nested, serialisable | `Filter` (an AST; `parseFilterAst()`/`stringifyFilterAst()`) | — |
|
|
130
|
+
| A spreadsheet-like editable grid (lines, positions) | `Grid` (`Grid.BillingItems()`) | `Table` with `editMode` — that is for occasional cell edits |
|
|
131
|
+
| A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
|
|
132
|
+
| Events over time | `Calendar` (agenda, day, week, month, year) | — |
|
|
133
|
+
| One number with context | `StatTile` (delta, sparkline, loading; plain and one leading for a record's figures) | a card with a big figure |
|
|
134
|
+
| A chart | `Chart` with `SvgChartAdapter` (bar, line, pie, doughnut; no dependency), or `ChartJsAdapter` for other types (Chart.js injected, never bundled) | a hand-drawn SVG |
|
|
135
|
+
| A linked record inline | `EntityRef` | a link |
|
|
136
|
+
| Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
|
|
137
|
+
| History, comments, a feed | `ActivityItem` / `ActivityList` | — |
|
|
138
|
+
| Choose one of many | `Select` (`filter: 'local'` or async for long lists; `Select.entity()` for records; `Select.priority()` / `Select.status()` presets); native radios for a handful of visible options | a custom dropdown |
|
|
139
|
+
| Choose many | `TagPicker` (identity, colour, icons), `Checklist` (a plain list) | — |
|
|
140
|
+
| On or off | `Toggle` (takes effect at once), `CheckButton` (a mode in a toolbar), a native checkbox inside a form | — |
|
|
141
|
+
| Search | `Search` | an input with an icon |
|
|
142
|
+
| Number, date, time, range | `NumberField`, `Datebox` / `DateTimeBox`, `Timebox`, `DateRangeBox`, `Slider`, `Rating` | plain inputs |
|
|
143
|
+
| A form | `Form` → `Fieldset` → `Field` (the type registry); `Questionnaire` for one question at a time | hand-laid inputs |
|
|
144
|
+
| Structured text, code | `CodeEditor` | a textarea |
|
|
145
|
+
| Repeating values | `ValueList`, `MultiValueEditor` | — |
|
|
146
|
+
| Confirm, alert, prompt | `Dialog.confirm()` / `Dialog.alert()` / `Dialog.prompt()` (Promises) | `window.confirm` |
|
|
147
|
+
| A task in a window | `Dialog` (header, footer, buttons); `Modal` is the bare surface | — |
|
|
148
|
+
| Edit without leaving the list | `Sheet` (`side: 'end'`); drill-down: `SheetStack`; a persistent pane: `Dock` | a dialog |
|
|
149
|
+
| Transient status | `Message.success()` / `.info()` / `.warning()` / `.error()` (toasts); inline `Message` for a region | an alert bar built by hand |
|
|
150
|
+
| Actions on a thing | `MenuButton`; `ContextMenu` (right-click and Shift+F10; one instance per table via `selector`) | a floating `<div>` |
|
|
151
|
+
| Anchored content, hints | `Dropdown`; `tooltip()` / `describe()` | `title` attributes alone |
|
|
152
|
+
| A row of actions | `Toolbar` (overflow menu, one Tab stop) | a flex row of buttons |
|
|
153
|
+
| Navigation | `AppSidebar` (tree, sections, `layout: 'modules'`), `ModuleBar`, `NavigationBar`, `Tabbox` (in-page), `Breadcrumb` (where am I), `Stepper` (a sequence) | — |
|
|
154
|
+
| Commands by keyboard | `Launcher` | — |
|
|
155
|
+
| Account and workspace | `AccountMenu`, `WorkspaceSwitcher` | — |
|
|
156
|
+
| Grouping content | `Card`, `Panel` (actions in the header or footer), `Groupbox`, `MasterPanel`, `SplitView`, `stack()` / `grid()` / `aspect()` | ad-hoc wrappers |
|
|
157
|
+
| Identity and status marks | `Avatar`, `AppIcon`, `badge()` (`kind` says how it is doing, `tone` what it is) | coloured spans |
|
|
158
|
+
| Nothing yet, loading, failed | `emptyState()`, `skeleton()` / `skeletonText()` / `skeletonTable()`, `InlineLoading`, `spinner()`, `ProgressBar` | a blank area |
|
|
159
|
+
| Ambient colour behind a hero, a login, a launcher | `Aurora` | CSS gradients |
|
|
160
|
+
| Icons | `icon(name)` — the bundled set or Font Awesome, whichever the application opted into | inline SVG |
|
|
161
|
+
|
|
162
|
+
## Never
|
|
163
|
+
|
|
164
|
+
- No raw colours (`#hex`, `rgb()`, named), no tier-1 tokens (`--zx-gray-*`, `--zx-emerald-*`,
|
|
165
|
+
`--zx-tone-*`), no hard-coded sizes the geometry tokens cover.
|
|
166
|
+
- No application CSS on component internals (`.zx-<component>__<part>` selectors); override a
|
|
167
|
+
token, or use a published hook.
|
|
168
|
+
- No hand-built dropdowns, menus, dialogs, tooltips, tables, date pickers, or toasts.
|
|
169
|
+
- No `innerHTML` with data; `h()` and text nodes.
|
|
170
|
+
- No state classes; state is ARIA and `data-state`, which the stylesheets already match.
|
|
171
|
+
- No second shell, second navigation, or second keyboard convention inside one application.
|
|
172
|
+
|
|
173
|
+
The theming decisions — theme, accent, geometry, material, motion, colour roles, type — are in "Choosing what to build with" in https://zx.zeyos.com/docs/llms.md.
|
|
174
|
+
|
|
175
|
+
## Composing surfaces at runtime
|
|
176
|
+
|
|
177
|
+
At runtime, a model composes interface as `surface/1` JSON — never HTML — and the application validates it and draws it with Zx components. Each surface declares one intent and ends in exactly one reply; treat a reply as the person's answer, not as proof that anything happened. When validation reports errors, return them to the model so it can correct the surface.
|
|
178
|
+
|
|
179
|
+
| Intent | Needs | Default actions | Reply values |
|
|
180
|
+
| --- | --- | --- | --- |
|
|
181
|
+
| `show` | — | — | No values. Actions are optional; closing the surface replies `dismiss`. |
|
|
182
|
+
| `ask` | a `fields` | Submit, Cancel | The values of its inputs, by name. |
|
|
183
|
+
| `choose` | a `choice` | Submit, Cancel | The picked value under the choice's name; a list when `multiple`. |
|
|
184
|
+
| `confirm` | — | Confirm, Cancel | `{}`. The application may ask the person to type a confirmation. |
|
|
185
|
+
| `review` | a `diff` or a `table` | Approve selected, Reject | The ids of the accepted diff rows or selected table rows, under the input's name. |
|
|
186
|
+
| `questionnaire` | a `questionnaire` | Cancel | `{answers, path}`: the answers by step name and the steps taken. |
|
|
187
|
+
|
|
188
|
+
Give the model the narrowest profile that does the job — `surfacePrompt(CATALOG, { profile })`, `surfaceTools(CATALOG, { profile })`, `narrowCatalog(CATALOG, { profile })`; leaving it out is the whole catalog:
|
|
189
|
+
|
|
190
|
+
- `answer` — intents `show`; nodes `text`, `heading`, `list`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`.
|
|
191
|
+
- `ask` — intents `show`, `ask`, `choose`, `confirm`; nodes `text`, `heading`, `list`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`, `fields`, `choice`.
|
|
192
|
+
- `review` — intents `show`, `ask`, `choose`, `confirm`, `review`; nodes `text`, `heading`, `list`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`, `fields`, `choice`, `diff`.
|
|
193
|
+
- `full` — intents `show`, `ask`, `choose`, `confirm`, `review`, `questionnaire`; nodes `text`, `heading`, `list`, `quote`, `code`, `callout`, `figures`, `table`, `stat`, `badge`, `ref`, `link`, `chart`, `empty`, `stack`, `columns`, `group`, `fields`, `choice`, `diff`, `questionnaire`.
|
|
194
|
+
|
|
195
|
+
Limits per surface: 400 nodes, 8 actions, 20,000 characters per string. Every node says when to use it and when not to in the guide and the catalogue.
|
|
196
|
+
|
|
197
|
+
- Model-facing guide: https://zx.zeyos.com/docs/agent-surfaces.md
|
|
198
|
+
- Catalogue, JSON Schema and tool definitions: https://zx.zeyos.com/docs/agent-catalog.json
|
|
199
|
+
- The Surface component: https://zx.zeyos.com/docs/components/surface.md
|
|
200
|
+
|
|
201
|
+
## Component files
|
|
202
|
+
|
|
203
|
+
Each is the component's section of the full reference: https://zx.zeyos.com/docs/components/<id>.md.
|
|
204
|
+
|
|
205
|
+
- [ZeyOS binding (zx-zeyos)](https://zx.zeyos.com/docs/components/zeyos.md)
|
|
206
|
+
- [Prose](https://zx.zeyos.com/docs/components/prose.md)
|
|
207
|
+
- [Kbd](https://zx.zeyos.com/docs/components/kbd.md)
|
|
208
|
+
- [Button](https://zx.zeyos.com/docs/components/button.md)
|
|
209
|
+
- [Badge](https://zx.zeyos.com/docs/components/badge.md)
|
|
210
|
+
- [Toolbar](https://zx.zeyos.com/docs/components/toolbar.md)
|
|
211
|
+
- [EmptyState](https://zx.zeyos.com/docs/components/empty-state.md)
|
|
212
|
+
- [Spinner / ProgressBar / InlineLoading](https://zx.zeyos.com/docs/components/loading.md)
|
|
213
|
+
- [Skeleton](https://zx.zeyos.com/docs/components/skeleton.md)
|
|
214
|
+
- [CheckButton](https://zx.zeyos.com/docs/components/check-button.md)
|
|
215
|
+
- [Toggle](https://zx.zeyos.com/docs/components/toggle.md)
|
|
216
|
+
- [Search](https://zx.zeyos.com/docs/components/search.md)
|
|
217
|
+
- [Launcher](https://zx.zeyos.com/docs/components/launcher.md)
|
|
218
|
+
- [AppIcon](https://zx.zeyos.com/docs/components/app-icon.md)
|
|
219
|
+
- [Avatar](https://zx.zeyos.com/docs/components/avatar.md)
|
|
220
|
+
- [AgentAvatar](https://zx.zeyos.com/docs/components/agent-avatar.md)
|
|
221
|
+
- [EntityRef](https://zx.zeyos.com/docs/components/entity-ref.md)
|
|
222
|
+
- [FileItem](https://zx.zeyos.com/docs/components/file-item.md)
|
|
223
|
+
- [FileList](https://zx.zeyos.com/docs/components/file-list.md)
|
|
224
|
+
- [ActivityItem](https://zx.zeyos.com/docs/components/activity-item.md)
|
|
225
|
+
- [ActivityList](https://zx.zeyos.com/docs/components/activity-list.md)
|
|
226
|
+
- [AccountMenu](https://zx.zeyos.com/docs/components/account-menu.md)
|
|
227
|
+
- [WorkspaceSwitcher](https://zx.zeyos.com/docs/components/workspace-switcher.md)
|
|
228
|
+
- [Select](https://zx.zeyos.com/docs/components/select.md)
|
|
229
|
+
- [SortControl](https://zx.zeyos.com/docs/components/sort-control.md)
|
|
230
|
+
- [Checklist](https://zx.zeyos.com/docs/components/checklist.md)
|
|
231
|
+
- [NumberField](https://zx.zeyos.com/docs/components/number-field.md)
|
|
232
|
+
- [Rating](https://zx.zeyos.com/docs/components/rating.md)
|
|
233
|
+
- [Slider](https://zx.zeyos.com/docs/components/slider.md)
|
|
234
|
+
- [copyButton() / CopyInput](https://zx.zeyos.com/docs/components/copy.md)
|
|
235
|
+
- [DatePicker / MonthPicker / TimePicker](https://zx.zeyos.com/docs/components/date-picker.md)
|
|
236
|
+
- [Datebox / DateTimeBox](https://zx.zeyos.com/docs/components/datebox.md)
|
|
237
|
+
- [DateRangePicker / DateRangeBox](https://zx.zeyos.com/docs/components/date-range.md)
|
|
238
|
+
- [Timebox](https://zx.zeyos.com/docs/components/timebox.md)
|
|
239
|
+
- [Message](https://zx.zeyos.com/docs/components/message.md)
|
|
240
|
+
- [Modal](https://zx.zeyos.com/docs/components/modal.md)
|
|
241
|
+
- [Dialog (extends Modal)](https://zx.zeyos.com/docs/components/dialog.md)
|
|
242
|
+
- [Sheet](https://zx.zeyos.com/docs/components/sheet.md)
|
|
243
|
+
- [SheetStack](https://zx.zeyos.com/docs/components/sheet-stack.md)
|
|
244
|
+
- [Dropdown](https://zx.zeyos.com/docs/components/dropdown.md)
|
|
245
|
+
- [MenuButton](https://zx.zeyos.com/docs/components/menu-button.md)
|
|
246
|
+
- [ContextMenu](https://zx.zeyos.com/docs/components/context-menu.md)
|
|
247
|
+
- [Tooltip](https://zx.zeyos.com/docs/components/tooltip.md)
|
|
248
|
+
- [SplitView](https://zx.zeyos.com/docs/components/split-view.md)
|
|
249
|
+
- [Table](https://zx.zeyos.com/docs/components/table.md)
|
|
250
|
+
- [TableView and the shared RecordView contract](https://zx.zeyos.com/docs/components/table-view.md)
|
|
251
|
+
- [CardView](https://zx.zeyos.com/docs/components/card-view.md)
|
|
252
|
+
- [KanbanView](https://zx.zeyos.com/docs/components/kanban-view.md)
|
|
253
|
+
- [Grid and Grid.BillingItems()](https://zx.zeyos.com/docs/components/grid.md)
|
|
254
|
+
- [Chart, SvgChartAdapter and ChartJsAdapter](https://zx.zeyos.com/docs/components/chart.md)
|
|
255
|
+
- [Calendar](https://zx.zeyos.com/docs/components/calendar.md)
|
|
256
|
+
- [DataFilter](https://zx.zeyos.com/docs/components/data-filter.md)
|
|
257
|
+
- [FilterPanel](https://zx.zeyos.com/docs/components/filter-panel.md)
|
|
258
|
+
- [Filter](https://zx.zeyos.com/docs/components/filter.md)
|
|
259
|
+
- [TreeView](https://zx.zeyos.com/docs/components/tree.md)
|
|
260
|
+
- [Finder](https://zx.zeyos.com/docs/components/finder.md)
|
|
261
|
+
- [Form / Fieldset / Field](https://zx.zeyos.com/docs/components/form.md)
|
|
262
|
+
- [Field widget types](https://zx.zeyos.com/docs/components/form-widgets.md)
|
|
263
|
+
- [CodeEditor](https://zx.zeyos.com/docs/components/code-editor.md)
|
|
264
|
+
- [Questionnaire](https://zx.zeyos.com/docs/components/questionnaire.md)
|
|
265
|
+
- [ValueList](https://zx.zeyos.com/docs/components/value-list.md)
|
|
266
|
+
- [MultiValueEditor](https://zx.zeyos.com/docs/components/multi-value-editor.md)
|
|
267
|
+
- [FieldUpload](https://zx.zeyos.com/docs/components/field-upload.md)
|
|
268
|
+
- [TagPicker](https://zx.zeyos.com/docs/components/tag-picker.md)
|
|
269
|
+
- [Groupbox](https://zx.zeyos.com/docs/components/groupbox.md)
|
|
270
|
+
- [Card](https://zx.zeyos.com/docs/components/card.md)
|
|
271
|
+
- [StatTile](https://zx.zeyos.com/docs/components/stat-tile.md)
|
|
272
|
+
- [Aurora](https://zx.zeyos.com/docs/components/aurora.md)
|
|
273
|
+
- [Panel / MasterPanel](https://zx.zeyos.com/docs/components/panel.md)
|
|
274
|
+
- [stack() / grid() / aspect()](https://zx.zeyos.com/docs/components/layout.md)
|
|
275
|
+
- [Dock](https://zx.zeyos.com/docs/components/dock.md)
|
|
276
|
+
- [Tabbox](https://zx.zeyos.com/docs/components/tabbox.md)
|
|
277
|
+
- [Stepper](https://zx.zeyos.com/docs/components/stepper.md)
|
|
278
|
+
- [Breadcrumb](https://zx.zeyos.com/docs/components/breadcrumb.md)
|
|
279
|
+
- [ListToolbar](https://zx.zeyos.com/docs/components/list-toolbar.md)
|
|
280
|
+
- [ViewSettings](https://zx.zeyos.com/docs/components/view-settings.md)
|
|
281
|
+
- [Pagination](https://zx.zeyos.com/docs/components/pagination.md)
|
|
282
|
+
- [NavigationBar](https://zx.zeyos.com/docs/components/navigation-bar.md)
|
|
283
|
+
- [AppSidebar](https://zx.zeyos.com/docs/components/app-sidebar.md)
|
|
284
|
+
- [ModuleBar](https://zx.zeyos.com/docs/components/module-bar.md)
|
|
285
|
+
- [BlockView](https://zx.zeyos.com/docs/components/block-view.md)
|
|
286
|
+
- [AgentThread](https://zx.zeyos.com/docs/components/agent-thread.md)
|
|
287
|
+
- [Surface](https://zx.zeyos.com/docs/components/surface.md)
|
|
288
|
+
- [RunStatus](https://zx.zeyos.com/docs/components/run-status.md)
|
|
289
|
+
- [Composer](https://zx.zeyos.com/docs/components/composer.md)
|
|
290
|
+
- [PromptStarters](https://zx.zeyos.com/docs/components/prompt-starters.md)
|
|
291
|
+
- [ApprovalCard](https://zx.zeyos.com/docs/components/approval-card.md)
|
|
292
|
+
- [RunTrace](https://zx.zeyos.com/docs/components/run-trace.md)
|
|
293
|
+
- [SourceList](https://zx.zeyos.com/docs/components/source-list.md)
|
|
294
|
+
- [Core helpers](https://zx.zeyos.com/docs/components/kernel.md)
|
|
295
|
+
- [Icons](https://zx.zeyos.com/docs/components/icons.md)
|
|
296
|
+
- [Helper functions](https://zx.zeyos.com/docs/components/helpers.md)
|
|
297
|
+
- [truncate()](https://zx.zeyos.com/docs/components/truncate.md)
|
|
298
|
+
- [Custom elements](https://zx.zeyos.com/docs/components/elements.md)
|
|
299
|
+
- [Design tokens](https://zx.zeyos.com/docs/components/tokens.md)
|