@zeyos/zx 5.5.0 → 5.7.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 +210 -0
- package/README.md +73 -7
- package/bin/zx-css.js +328 -0
- package/dist/types/components/account-menu/account-menu.d.ts +4 -2
- package/dist/types/components/activity-list/activity-list.d.ts +14 -8
- package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
- package/dist/types/components/agent-thread/agent-thread.d.ts +711 -0
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
- package/dist/types/components/approval-card/approval-card.d.ts +596 -0
- package/dist/types/components/avatar/avatar.d.ts +91 -4
- package/dist/types/components/block-view/block-view.d.ts +205 -0
- package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
- package/dist/types/components/calendar/calendar-model.d.ts +9 -2
- package/dist/types/components/calendar/calendar.d.ts +12 -4
- package/dist/types/components/chart/chart.d.ts +25 -13
- package/dist/types/components/code-editor/code-editor.d.ts +7 -2
- package/dist/types/components/composer/composer.d.ts +938 -0
- package/dist/types/components/composer/queue.d.ts +76 -0
- package/dist/types/components/copy/copy-button.d.ts +6 -4
- package/dist/types/components/copy/copy-input.d.ts +10 -6
- package/dist/types/components/datebox/date-range-box.d.ts +33 -0
- package/dist/types/components/datebox/placeholder.d.ts +7 -0
- package/dist/types/components/dock/dock.d.ts +12 -3
- package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
- package/dist/types/components/field-upload/field-upload.d.ts +3 -2
- package/dist/types/components/file-item/file-item.d.ts +3 -2
- package/dist/types/components/file-list/file-list.d.ts +14 -8
- package/dist/types/components/filter/filter-model.d.ts +31 -1
- package/dist/types/components/filter/filter.d.ts +20 -2
- package/dist/types/components/finder/finder.d.ts +14 -6
- package/dist/types/components/flag/flag.d.ts +99 -0
- package/dist/types/components/grid/grid.d.ts +1 -1
- package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
- package/dist/types/components/launcher/launcher.d.ts +2 -0
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
- package/dist/types/components/number-field/number-field.d.ts +17 -6
- package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
- package/dist/types/components/prose/prose.d.ts +9 -6
- package/dist/types/components/questionnaire/conditions.d.ts +270 -0
- package/dist/types/components/questionnaire/items.d.ts +52 -30
- package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
- package/dist/types/components/rating/rating.d.ts +5 -3
- package/dist/types/components/run-status/run-status.d.ts +393 -0
- package/dist/types/components/run-trace/run-trace.d.ts +624 -0
- package/dist/types/components/select/country.d.ts +106 -0
- package/dist/types/components/select/field-adapter.d.ts +2 -1
- package/dist/types/components/select/locale.d.ts +102 -0
- package/dist/types/components/select/select.d.ts +41 -2
- package/dist/types/components/slider/slider.d.ts +1 -0
- package/dist/types/components/sort-control/sort-control.d.ts +7 -3
- package/dist/types/components/source-list/source-list.d.ts +179 -0
- package/dist/types/components/split-view/split-view.d.ts +5 -3
- package/dist/types/components/surface/catalog.d.ts +260 -0
- package/dist/types/components/surface/elicit.d.ts +81 -0
- package/dist/types/components/surface/mcp.d.ts +165 -0
- package/dist/types/components/surface/schema.d.ts +314 -0
- package/dist/types/components/surface/stream.d.ts +118 -0
- package/dist/types/components/surface/surface.d.ts +718 -0
- package/dist/types/components/surface/text.d.ts +277 -0
- package/dist/types/components/surface/validate.d.ts +339 -0
- package/dist/types/components/table/table.d.ts +55 -3
- package/dist/types/components/table/window.d.ts +203 -0
- package/dist/types/components/toolbar/toolbar.d.ts +10 -6
- package/dist/types/components/tooltip/tooltip.d.ts +2 -2
- package/dist/types/components/tree/tree.d.ts +20 -13
- package/dist/types/core/component.d.ts +10 -0
- package/dist/types/core/date.d.ts +8 -1
- package/dist/types/core/dom.d.ts +1 -0
- package/dist/types/core/http.d.ts +10 -0
- package/dist/types/core/i18n.d.ts +38 -0
- package/dist/types/core/messages.d.ts +479 -1
- package/dist/types/core/storage.d.ts +7 -2
- package/dist/types/elements/define.d.ts +21 -46
- package/dist/types/elements/definitions.d.ts +147 -0
- package/dist/types/elements/kit.d.ts +7 -0
- package/dist/types/elements/reflect.d.ts +6 -3
- package/dist/types/index.d.ts +18 -1
- package/dist/types/internal/agent-model.d.ts +587 -0
- package/dist/types/internal/date-locale.d.ts +7 -0
- package/dist/types/internal/highlight.d.ts +24 -0
- package/dist/types/internal/json-patch.d.ts +146 -0
- package/dist/types/internal/presence-loop.d.ts +148 -0
- package/dist/types/locales/de.d.ts +13 -0
- package/dist/types/locales/en.d.ts +2 -0
- package/dist/types/locales/index.d.ts +823 -0
- package/dist/types/zeyos/view.d.ts +8 -1
- package/dist/zx-zeyos.esm.js +20505 -18748
- package/dist/zx-zeyos.esm.min.js +5 -5
- package/dist/zx.core.css +1276 -0
- package/dist/zx.core.min.css +1 -0
- package/dist/zx.css +2424 -134
- package/dist/zx.esm.js +46167 -28468
- package/dist/zx.esm.min.js +40 -8
- package/dist/zx.global.js +46167 -28468
- package/dist/zx.global.min.js +40 -8
- package/dist/zx.layered.css +17302 -0
- package/dist/zx.layered.min.css +1 -0
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +12501 -0
- package/docs/agent-surfaces.md +340 -0
- package/docs/api.json +2057 -166
- package/docs/llms.md +1458 -58
- package/docs/llms.txt +38 -8
- package/package.json +29 -6
- package/src/components/account-menu/account-menu.js +6 -3
- package/src/components/activity-item/activity-item.js +2 -1
- package/src/components/activity-list/activity-list.js +16 -10
- package/src/components/agent-thread/ag-ui.js +1439 -0
- package/src/components/agent-thread/agent-thread.css +417 -0
- package/src/components/agent-thread/agent-thread.js +1670 -0
- package/src/components/agent-thread/ui-message-stream.js +1281 -0
- package/src/components/app-sidebar/app-sidebar.js +18 -8
- package/src/components/approval-card/approval-card.css +289 -0
- package/src/components/approval-card/approval-card.js +1378 -0
- package/src/components/avatar/avatar.css +56 -1
- package/src/components/avatar/avatar.js +148 -26
- package/src/components/block-view/block-view.css +300 -0
- package/src/components/block-view/block-view.js +524 -0
- package/src/components/breadcrumb/breadcrumb.js +8 -5
- package/src/components/calendar/calendar-model.js +8 -2
- package/src/components/calendar/calendar.js +53 -18
- package/src/components/chart/chart.js +54 -23
- package/src/components/code-editor/code-editor.js +45 -8
- package/src/components/code-editor/field-adapter.js +1 -1
- package/src/components/composer/composer.css +482 -0
- package/src/components/composer/composer.js +1815 -0
- package/src/components/composer/queue.js +78 -0
- package/src/components/context-menu/context-menu.js +12 -1
- package/src/components/copy/copy-button.js +9 -7
- package/src/components/copy/copy-input.js +10 -6
- package/src/components/date-picker/date-picker.js +2 -1
- package/src/components/date-picker/date-range-picker.js +8 -7
- package/src/components/datebox/date-range-box.js +3 -9
- package/src/components/datebox/datebox.js +18 -21
- package/src/components/datebox/placeholder.js +18 -0
- package/src/components/dialog/dialog.js +1 -1
- package/src/components/dock/dock.js +34 -13
- package/src/components/entity-ref/entity-ref.js +16 -5
- package/src/components/field-upload/field-upload.js +81 -38
- package/src/components/file-item/file-item.js +70 -40
- package/src/components/file-list/file-list.js +15 -9
- package/src/components/filter/filter-model.js +46 -8
- package/src/components/filter/filter.css +3 -3
- package/src/components/filter/filter.js +29 -10
- package/src/components/filter-panel/filter-panel.js +13 -5
- package/src/components/finder/finder.js +50 -26
- package/src/components/flag/flag.css +40 -0
- package/src/components/flag/flag.js +177 -0
- package/src/components/form/form.js +1 -1
- package/src/components/grid/grid.js +22 -8
- package/src/components/kanban-view/kanban-view.js +51 -81
- package/src/components/launcher/launcher.js +17 -2
- package/src/components/list-toolbar/list-toolbar.js +2 -1
- package/src/components/master-panel/master-panel.js +1 -1
- package/src/components/menu-button/menu-button.js +4 -0
- package/src/components/message/message.js +3 -0
- package/src/components/multi-value-editor/multi-value-editor.js +10 -9
- package/src/components/navigation-bar/navigation-bar.js +3 -3
- package/src/components/number-field/number-field.js +29 -13
- package/src/components/prompt-starters/prompt-starters.css +91 -0
- package/src/components/prompt-starters/prompt-starters.js +206 -0
- package/src/components/prose/prose.js +14 -10
- package/src/components/questionnaire/conditions.js +666 -0
- package/src/components/questionnaire/items.js +150 -41
- package/src/components/questionnaire/questionnaire.js +126 -32
- package/src/components/rating/rating.js +5 -4
- package/src/components/run-status/run-status.css +208 -0
- package/src/components/run-status/run-status.js +782 -0
- package/src/components/run-trace/run-trace.css +443 -0
- package/src/components/run-trace/run-trace.js +1209 -0
- package/src/components/select/country.js +136 -0
- package/src/components/select/field-adapter.js +7 -2
- package/src/components/select/locale.js +219 -0
- package/src/components/select/select.css +20 -22
- package/src/components/select/select.js +94 -12
- package/src/components/sheet/sheet-stack.js +10 -1
- package/src/components/slider/slider.js +7 -2
- package/src/components/sort-control/sort-control.js +15 -5
- package/src/components/source-list/source-list.css +208 -0
- package/src/components/source-list/source-list.js +358 -0
- package/src/components/split-view/split-view.js +5 -3
- package/src/components/surface/catalog.js +1334 -0
- package/src/components/surface/elicit.js +107 -0
- package/src/components/surface/mcp.js +243 -0
- package/src/components/surface/schema.js +644 -0
- package/src/components/surface/stream.js +245 -0
- package/src/components/surface/surface.css +308 -0
- package/src/components/surface/surface.js +2291 -0
- package/src/components/surface/text.js +513 -0
- package/src/components/surface/validate.js +2218 -0
- package/src/components/tabbox/tabbox.js +9 -0
- package/src/components/table/table.css +63 -3
- package/src/components/table/table.js +167 -28
- package/src/components/table/window.js +317 -0
- package/src/components/toolbar/toolbar.js +12 -7
- package/src/components/tooltip/tooltip.css +2 -3
- package/src/components/tooltip/tooltip.js +32 -5
- package/src/components/tree/tree.js +53 -23
- package/src/core/component.js +25 -1
- package/src/core/date.js +62 -16
- package/src/core/dom.js +22 -2
- package/src/core/format.js +15 -13
- package/src/core/http.js +29 -20
- package/src/core/i18n.js +83 -10
- package/src/core/keyboard.js +79 -8
- package/src/core/messages.js +519 -2
- package/src/core/overlay-host.js +1 -0
- package/src/core/storage.js +59 -6
- package/src/elements/define.js +178 -130
- package/src/elements/definitions.js +229 -0
- package/src/elements/kit.js +444 -0
- package/src/elements/reflect.js +8 -3
- package/src/index.js +18 -1
- package/src/internal/agent-model.js +488 -0
- package/src/internal/date-locale.js +11 -0
- package/src/internal/highlight.js +104 -0
- package/src/internal/json-patch.js +405 -0
- package/src/internal/presence-loop.js +343 -0
- package/src/locales/de.js +911 -0
- package/src/locales/en.js +2 -0
- package/src/locales/index.js +7 -0
- package/src/zeyos/calendar.js +2 -1
- package/src/zeyos/form.js +2 -1
- package/src/zeyos/launcher.js +7 -6
- package/src/zeyos/module-bar.js +2 -1
- package/src/zeyos/schema.js +37 -23
- package/src/zeyos/select.js +4 -3
- package/src/zeyos/table.js +2 -13
- package/src/zeyos/view.js +57 -17
- package/styles/core.css +11 -0
- package/styles/tokens/semantic.css +1 -0
- package/styles/zeyos.css +2 -0
- package/styles/zx.css +11 -8
- package/styles/zx.layered.css +1 -0
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
# Composing surfaces
|
|
2
|
+
|
|
3
|
+
A surface is a piece of interface you compose from JSON: a rich answer, or a dialog that asks the person something. The application validates it and draws it with its own components, and the person's input comes back to you as structured data. A surface carries no HTML, script, style or expression; every string is shown as text.
|
|
4
|
+
|
|
5
|
+
## Delivery
|
|
6
|
+
|
|
7
|
+
Call `show_surface` or `ask_user` with the whole surface as the arguments. The call's result is the person's reply. The tools' schemas require every key: give `null` for one that does not apply. In the arguments, a `fields` schema lists its properties as `[{"name": …, …}]`, and table rows are lists of cells in column order.
|
|
8
|
+
|
|
9
|
+
Use `ask_user` when you only need values from the person, `show_surface` for everything else.
|
|
10
|
+
|
|
11
|
+
## Intents
|
|
12
|
+
|
|
13
|
+
A surface declares one intent. It fixes the frame, the default actions and the reply.
|
|
14
|
+
|
|
15
|
+
| Intent | Needs | Default actions | Reply values |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `show` | — | — | No values. Actions are optional; closing the surface replies `dismiss`. |
|
|
18
|
+
| `ask` | a `fields` | Submit, Cancel | The values of its inputs, by name. |
|
|
19
|
+
| `choose` | a `choice` | Submit, Cancel | The picked value under the choice's name; a list when `multiple`. |
|
|
20
|
+
| `confirm` | — | Confirm, Cancel | `{}`. The application may ask the person to type a confirmation. |
|
|
21
|
+
| `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. |
|
|
22
|
+
| `questionnaire` | a `questionnaire` | Cancel | `{answers, path}`: the answers by step name and the steps taken. |
|
|
23
|
+
|
|
24
|
+
A reply is `{"zx": "reply/1", "surface", "action", "key", "values", "confirmation", "at"}`. `action` is the id of the action taken: one of yours, a default one (`submit`, `confirm`, `approve`, `reject`), or `cancel` or `dismiss` when the person closed the surface. Those two ids are reserved: an action of yours using one is dropped. Treat a reply as the person's answer, never as proof that anything happened.
|
|
25
|
+
|
|
26
|
+
## Nodes
|
|
27
|
+
|
|
28
|
+
Nodes are addressed by `id` and laid out by lists of ids: `root` holds the top level and a layout node's `children` its own. Any node may carry `visible` (see Conditions).
|
|
29
|
+
|
|
30
|
+
### `text`
|
|
31
|
+
|
|
32
|
+
A paragraph.
|
|
33
|
+
|
|
34
|
+
- `text`: text, at most 20,000 characters, required
|
|
35
|
+
|
|
36
|
+
### `heading`
|
|
37
|
+
|
|
38
|
+
A heading inside the surface; level 2 or 3.
|
|
39
|
+
|
|
40
|
+
- `text`: text, at most 200 characters, required
|
|
41
|
+
- `level`: one of `2`, `3`
|
|
42
|
+
|
|
43
|
+
### `list`
|
|
44
|
+
|
|
45
|
+
A bulleted list, or numbered with `ordered`.
|
|
46
|
+
|
|
47
|
+
- `items`: list of texts, at most 1,000, required
|
|
48
|
+
- `ordered`: `true` or `false`
|
|
49
|
+
|
|
50
|
+
### `quote`
|
|
51
|
+
|
|
52
|
+
A quotation.
|
|
53
|
+
|
|
54
|
+
- `text`: text, at most 20,000 characters, required
|
|
55
|
+
|
|
56
|
+
### `code`
|
|
57
|
+
|
|
58
|
+
A code block.
|
|
59
|
+
|
|
60
|
+
- `code`: text, at most 20,000 characters, required
|
|
61
|
+
- `language`: text, at most 32 characters
|
|
62
|
+
|
|
63
|
+
### `callout`
|
|
64
|
+
|
|
65
|
+
A paragraph set apart, with a tone.
|
|
66
|
+
|
|
67
|
+
- `text`: text, at most 20,000 characters, required
|
|
68
|
+
- `title`: text, at most 200 characters
|
|
69
|
+
- `tone`: one of `"info"`, `"success"`, `"warning"`, `"danger"`
|
|
70
|
+
|
|
71
|
+
### `figures`
|
|
72
|
+
|
|
73
|
+
Rows of `{"label", "value", "detail"?}`: amounts, dates, counts.
|
|
74
|
+
|
|
75
|
+
- `rows`: list of figure rows, at most 1,000, required
|
|
76
|
+
|
|
77
|
+
### `table`
|
|
78
|
+
|
|
79
|
+
A table. `columns` are `{"id", "label", "align"?, "format"?, "currency"?}`; each row is an object keyed by column id. With `selectable` it is an input: give it a `name` and a `rowId` column, and the reply holds the selected row ids.
|
|
80
|
+
|
|
81
|
+
- `columns`: list of columns, at most 50, required
|
|
82
|
+
- `rows`: list of rows, at most 1,000, required
|
|
83
|
+
- `rowId`: text, at most 64 characters
|
|
84
|
+
- `selectable`: one of `"single"`, `"multi"`
|
|
85
|
+
- `name`: text, at most 64 characters
|
|
86
|
+
- `label`: text, at most 200 characters
|
|
87
|
+
|
|
88
|
+
### `stat`
|
|
89
|
+
|
|
90
|
+
One figure with its label, drawn as a tile.
|
|
91
|
+
|
|
92
|
+
- `label`: text, at most 200 characters, required
|
|
93
|
+
- `value`: number or text, at most 200 characters, required
|
|
94
|
+
- `format`: one of `"number"`, `"currency"`, `"percent"`
|
|
95
|
+
- `currency`: text, at most 3 characters
|
|
96
|
+
- `delta`: number or text, at most 200 characters
|
|
97
|
+
- `caption`: text, at most 200 characters
|
|
98
|
+
|
|
99
|
+
### `badge`
|
|
100
|
+
|
|
101
|
+
A short status word.
|
|
102
|
+
|
|
103
|
+
- `label`: text, at most 64 characters, required
|
|
104
|
+
- `kind`: one of `"neutral"`, `"accent"`, `"success"`, `"warning"`, `"danger"`, `"info"`
|
|
105
|
+
|
|
106
|
+
### `ref`
|
|
107
|
+
|
|
108
|
+
A record of the application, drawn with its own name and icon.
|
|
109
|
+
|
|
110
|
+
- `ref`: record `{"$ref", "id"}`, required
|
|
111
|
+
|
|
112
|
+
### `link`
|
|
113
|
+
|
|
114
|
+
An external link.
|
|
115
|
+
|
|
116
|
+
- `text`: text, at most 200 characters, required
|
|
117
|
+
- `href`: `https:` address, at most 2,000 characters, required
|
|
118
|
+
|
|
119
|
+
### `chart`
|
|
120
|
+
|
|
121
|
+
A chart; its data table is always offered. `data` is `{"labels": […], "datasets": [{"label", "data": […]}]}`.
|
|
122
|
+
|
|
123
|
+
- `kind`: one of `"bar"`, `"line"`, `"pie"`, `"doughnut"`, required
|
|
124
|
+
- `data`: chart data, required
|
|
125
|
+
- `label`: text, at most 200 characters, required
|
|
126
|
+
- `description`: text, at most 2,000 characters
|
|
127
|
+
|
|
128
|
+
### `empty`
|
|
129
|
+
|
|
130
|
+
An empty state: nothing to show, and why.
|
|
131
|
+
|
|
132
|
+
- `title`: text, at most 200 characters, required
|
|
133
|
+
- `description`: text, at most 2,000 characters
|
|
134
|
+
|
|
135
|
+
### `stack`
|
|
136
|
+
|
|
137
|
+
Lays out its children one under the other.
|
|
138
|
+
|
|
139
|
+
- `gap`: one of `"sm"`, `"md"`, `"lg"`
|
|
140
|
+
- `children`: list of node ids.
|
|
141
|
+
|
|
142
|
+
### `columns`
|
|
143
|
+
|
|
144
|
+
Lays out its children side by side, one column when narrow.
|
|
145
|
+
|
|
146
|
+
- `count`: one of `1`, `2`, `3`
|
|
147
|
+
- `children`: list of node ids.
|
|
148
|
+
|
|
149
|
+
### `group`
|
|
150
|
+
|
|
151
|
+
A titled section around its children.
|
|
152
|
+
|
|
153
|
+
- `title`: text, at most 200 characters, required
|
|
154
|
+
- `children`: list of node ids.
|
|
155
|
+
|
|
156
|
+
### `fields`
|
|
157
|
+
|
|
158
|
+
A form: a JSON Schema whose properties become fields (see Inputs).
|
|
159
|
+
|
|
160
|
+
- `schema`: input schema, required
|
|
161
|
+
- `title`: text, at most 200 characters
|
|
162
|
+
|
|
163
|
+
### `choice`
|
|
164
|
+
|
|
165
|
+
Options to pick from: `choices` are `{"value", "label", "description"?, "icon"?}`; `multiple` allows several.
|
|
166
|
+
|
|
167
|
+
- `name`: text, at most 64 characters, required
|
|
168
|
+
- `label`: text, at most 200 characters, required
|
|
169
|
+
- `choices`: list of choices, at most 64, required
|
|
170
|
+
- `multiple`: `true` or `false`
|
|
171
|
+
|
|
172
|
+
### `diff`
|
|
173
|
+
|
|
174
|
+
Proposed changes, one row per value: `{"id", "field", "label", "before", "after", "ref"?}`. The reply holds the ids of the accepted rows. Only in a `review` surface.
|
|
175
|
+
|
|
176
|
+
- `name`: text, at most 64 characters, required
|
|
177
|
+
- `rows`: list of changes, at most 1,000, required
|
|
178
|
+
- `label`: text, at most 200 characters
|
|
179
|
+
|
|
180
|
+
### `questionnaire`
|
|
181
|
+
|
|
182
|
+
Steps asked one at a time: `{"name", "prompt", "choices"?, "input"?, "required"?, "multiple"?, "when"?, "next"?, "validate"?}`. `next` is a step name, `$review`, `$submit`, or `[{"if": condition, "goto": name}, …]`, and is dropped if it names a step that was dropped or can lead back to its own step; `validate` lists rules (`required`, `minLength`, `maxLength`, `minimum`, `maximum`, `format`, `oneOf`, each with an optional `message`). Only in a `questionnaire` surface.
|
|
183
|
+
|
|
184
|
+
- `steps`: list of steps, at most 50, required
|
|
185
|
+
- `review`: `true` or `false`
|
|
186
|
+
|
|
187
|
+
### Values
|
|
188
|
+
|
|
189
|
+
- **Text** uses `**bold**`, `` `code` `` and `[n]` citation markers, and nothing else. A backslash escapes `*`, `` ` ``, `[` and itself.
|
|
190
|
+
- **Records** are `{"$ref": "<entity>", "id": "…"}`, never a link. Use the entity names the application gives you; others are refused.
|
|
191
|
+
- **Table cells** are strings, numbers, booleans, `null` or a record.
|
|
192
|
+
- **Links** are `link` nodes with an `https:` address. The host is shown beside the text, and the application may refuse the link.
|
|
193
|
+
- **No images and no URLs** to load or navigate to, anywhere else.
|
|
194
|
+
|
|
195
|
+
## Inputs
|
|
196
|
+
|
|
197
|
+
Each input lands in the reply's `values` under its name; names are unique within a surface.
|
|
198
|
+
|
|
199
|
+
A `fields` node's `schema` is one flat JSON Schema object with `required`. Properties are:
|
|
200
|
+
|
|
201
|
+
- `string`, with `minLength`/`maxLength`, a `format` (`date` as `YYYY-MM-DD`, `date-time`, `time` as `HH:MM`, `email`, `uri`), or choices as `enum` or `oneOf: [{"const", "title"}]`;
|
|
202
|
+
- `number` or `integer`, with `minimum`/`maximum`;
|
|
203
|
+
- `boolean`;
|
|
204
|
+
- a multiple choice: `array` with `items: {"enum": […]}` or `items: {"anyOf": [{"const", "title"}]}`, and `minItems`/`maxItems`.
|
|
205
|
+
|
|
206
|
+
Every property has a `title`, and may have `description` and `default`. `x-zx: {"field": …}` picks how it is drawn:
|
|
207
|
+
|
|
208
|
+
- text: `text`, `textarea`; choices: `select`, `optionlist`, `zxselect`;
|
|
209
|
+
- numbers: `number`, `slider`, `rating` (a slider needs `minimum` and `maximum`; a rating is an integer up to 10);
|
|
210
|
+
- booleans: `checkbox`, `toggle`; multiple choices: `checklist`, `tagpicker`.
|
|
211
|
+
|
|
212
|
+
There are no nested objects, no patterns and no password or secret fields: never ask for credentials, keys or payment card numbers.
|
|
213
|
+
|
|
214
|
+
### Conditions
|
|
215
|
+
|
|
216
|
+
`visible` on a node, or `x-zx.visible` on a schema property, shows it only while a condition holds:
|
|
217
|
+
|
|
218
|
+
- `{"field": <input name>, "op": …, "value": …}` with ops `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `empty`, `filled`, `contains`; `in` and `nin` take a list, `empty` and `filled` no value;
|
|
219
|
+
- combined with `{"all": […]}`, `{"any": […]}` and `{"not": …}`, at most four levels deep.
|
|
220
|
+
|
|
221
|
+
A condition may only name inputs that come earlier in the surface: depth first from `root`, and in property order within a schema. A hidden input is not required and is left out of the reply.
|
|
222
|
+
|
|
223
|
+
## Rules
|
|
224
|
+
|
|
225
|
+
- The application decides what an action needs before it runs. An action may name the `tool` it triggers; you cannot skip, lower or claim a confirmation, and `kind: "danger"` only changes how it looks.
|
|
226
|
+
- At most 8 actions. Every action has an `id` and a `label`.
|
|
227
|
+
- Your own actions replace the default ones. Only an action with `kind: "primary"` checks the inputs and sends their values, as the default answering actions do; any other action of yours replies with empty `values`, so use it for "Not now" or "Skip".
|
|
228
|
+
- A `choice` without `multiple` must be picked before an answering action replies; a `multiple` choice may be left empty.
|
|
229
|
+
- A surface says it was composed by its `author`. It cannot show notifications, navigate or change the application around it.
|
|
230
|
+
- `placement` (`inline`, `sheet` or `dialog`) is a request; the application decides.
|
|
231
|
+
- Every surface ends in exactly one reply, also when the person closes it or it is replaced. Wait for it before you act on it.
|
|
232
|
+
- Limits per surface: 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 100,000 table cells in all, 50 fields, 64 choices, and 8 actions.
|
|
233
|
+
- Anything invalid is dropped and reported. When the application returns the errors, correct the surface and send it again.
|
|
234
|
+
|
|
235
|
+
## Examples
|
|
236
|
+
|
|
237
|
+
### A review of reminders to send
|
|
238
|
+
|
|
239
|
+
Three invoices are overdue. The surface lists them for selection and asks which template to use.
|
|
240
|
+
|
|
241
|
+
Call `show_surface` with:
|
|
242
|
+
|
|
243
|
+
```json
|
|
244
|
+
{
|
|
245
|
+
"zx": "surface/1",
|
|
246
|
+
"surface": "s1",
|
|
247
|
+
"intent": "review",
|
|
248
|
+
"title": "Send 3 first reminders?",
|
|
249
|
+
"author": "finance",
|
|
250
|
+
"root": ["why","list","opts"],
|
|
251
|
+
"nodes": [
|
|
252
|
+
{"id":"why","type":"text","text":"Three invoices are more than **14 days** overdue [1]."},
|
|
253
|
+
{
|
|
254
|
+
"id": "list",
|
|
255
|
+
"type": "table",
|
|
256
|
+
"name": "invoices",
|
|
257
|
+
"selectable": "multi",
|
|
258
|
+
"rowId": "invoice",
|
|
259
|
+
"columns": [
|
|
260
|
+
{"id":"invoice","label":"Invoice"},
|
|
261
|
+
{"id":"customer","label":"Customer"},
|
|
262
|
+
{"id":"amount","label":"Amount","align":"end","format":"currency","currency":"EUR"}
|
|
263
|
+
],
|
|
264
|
+
"rows": [
|
|
265
|
+
["RE-2026-0121","Helios Energie",4860],
|
|
266
|
+
["RE-2026-0127","Nordlicht Logistik",1275.5],
|
|
267
|
+
["RE-2026-0130","Atelier Brun",620]
|
|
268
|
+
]
|
|
269
|
+
},
|
|
270
|
+
{
|
|
271
|
+
"id": "opts",
|
|
272
|
+
"type": "fields",
|
|
273
|
+
"schema": {
|
|
274
|
+
"type": "object",
|
|
275
|
+
"required": ["template"],
|
|
276
|
+
"properties": [
|
|
277
|
+
{
|
|
278
|
+
"name": "template",
|
|
279
|
+
"type": "string",
|
|
280
|
+
"title": "Template",
|
|
281
|
+
"oneOf": [
|
|
282
|
+
{"const":"reminder-1","title":"First reminder"},
|
|
283
|
+
{"const":"reminder-2","title":"Second reminder, €5.00 fee"}
|
|
284
|
+
]
|
|
285
|
+
},
|
|
286
|
+
{"name":"sendOn","type":"string","format":"date","title":"Send on"}
|
|
287
|
+
]
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
],
|
|
291
|
+
"actions": [
|
|
292
|
+
{"id":"send","label":"Send reminders","kind":"primary","tool":"mail.send"},
|
|
293
|
+
{"id":"later","label":"Not now"}
|
|
294
|
+
],
|
|
295
|
+
"sources": [{"n":1,"call":"invoices"}]
|
|
296
|
+
}
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
### A payment form with a conditional field
|
|
300
|
+
|
|
301
|
+
The IBAN is asked for only when the person pays by transfer.
|
|
302
|
+
|
|
303
|
+
Call `ask_user` with:
|
|
304
|
+
|
|
305
|
+
```json
|
|
306
|
+
{
|
|
307
|
+
"zx": "surface/1",
|
|
308
|
+
"surface": "pay",
|
|
309
|
+
"intent": "ask",
|
|
310
|
+
"title": "How will the customer pay?",
|
|
311
|
+
"author": "orders",
|
|
312
|
+
"root": ["form"],
|
|
313
|
+
"nodes": [
|
|
314
|
+
{
|
|
315
|
+
"id": "form",
|
|
316
|
+
"type": "fields",
|
|
317
|
+
"schema": {
|
|
318
|
+
"type": "object",
|
|
319
|
+
"required": ["method"],
|
|
320
|
+
"properties": [
|
|
321
|
+
{
|
|
322
|
+
"name": "method",
|
|
323
|
+
"type": "string",
|
|
324
|
+
"title": "Payment",
|
|
325
|
+
"oneOf": [{"const":"card","title":"Card"},{"const":"transfer","title":"Bank transfer"}]
|
|
326
|
+
},
|
|
327
|
+
{
|
|
328
|
+
"name": "iban",
|
|
329
|
+
"type": "string",
|
|
330
|
+
"title": "IBAN",
|
|
331
|
+
"maxLength": 34,
|
|
332
|
+
"x-zx": {"visible":{"field":"method","op":"eq","value":"transfer"}}
|
|
333
|
+
},
|
|
334
|
+
{"name":"note","type":"string","title":"Note for the invoice","x-zx":{"field":"textarea"}}
|
|
335
|
+
]
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
]
|
|
339
|
+
}
|
|
340
|
+
```
|