@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.
Files changed (235) hide show
  1. package/CHANGELOG.md +210 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +711 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  11. package/dist/types/components/avatar/avatar.d.ts +91 -4
  12. package/dist/types/components/block-view/block-view.d.ts +205 -0
  13. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  14. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  15. package/dist/types/components/calendar/calendar.d.ts +12 -4
  16. package/dist/types/components/chart/chart.d.ts +25 -13
  17. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  18. package/dist/types/components/composer/composer.d.ts +938 -0
  19. package/dist/types/components/composer/queue.d.ts +76 -0
  20. package/dist/types/components/copy/copy-button.d.ts +6 -4
  21. package/dist/types/components/copy/copy-input.d.ts +10 -6
  22. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  23. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  24. package/dist/types/components/dock/dock.d.ts +12 -3
  25. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  26. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  27. package/dist/types/components/file-item/file-item.d.ts +3 -2
  28. package/dist/types/components/file-list/file-list.d.ts +14 -8
  29. package/dist/types/components/filter/filter-model.d.ts +31 -1
  30. package/dist/types/components/filter/filter.d.ts +20 -2
  31. package/dist/types/components/finder/finder.d.ts +14 -6
  32. package/dist/types/components/flag/flag.d.ts +99 -0
  33. package/dist/types/components/grid/grid.d.ts +1 -1
  34. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  35. package/dist/types/components/launcher/launcher.d.ts +2 -0
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +17 -6
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/run-status/run-status.d.ts +393 -0
  45. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  46. package/dist/types/components/select/country.d.ts +106 -0
  47. package/dist/types/components/select/field-adapter.d.ts +2 -1
  48. package/dist/types/components/select/locale.d.ts +102 -0
  49. package/dist/types/components/select/select.d.ts +41 -2
  50. package/dist/types/components/slider/slider.d.ts +1 -0
  51. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  52. package/dist/types/components/source-list/source-list.d.ts +179 -0
  53. package/dist/types/components/split-view/split-view.d.ts +5 -3
  54. package/dist/types/components/surface/catalog.d.ts +260 -0
  55. package/dist/types/components/surface/elicit.d.ts +81 -0
  56. package/dist/types/components/surface/mcp.d.ts +165 -0
  57. package/dist/types/components/surface/schema.d.ts +314 -0
  58. package/dist/types/components/surface/stream.d.ts +118 -0
  59. package/dist/types/components/surface/surface.d.ts +718 -0
  60. package/dist/types/components/surface/text.d.ts +277 -0
  61. package/dist/types/components/surface/validate.d.ts +339 -0
  62. package/dist/types/components/table/table.d.ts +55 -3
  63. package/dist/types/components/table/window.d.ts +203 -0
  64. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  65. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  66. package/dist/types/components/tree/tree.d.ts +20 -13
  67. package/dist/types/core/component.d.ts +10 -0
  68. package/dist/types/core/date.d.ts +8 -1
  69. package/dist/types/core/dom.d.ts +1 -0
  70. package/dist/types/core/http.d.ts +10 -0
  71. package/dist/types/core/i18n.d.ts +38 -0
  72. package/dist/types/core/messages.d.ts +479 -1
  73. package/dist/types/core/storage.d.ts +7 -2
  74. package/dist/types/elements/define.d.ts +21 -46
  75. package/dist/types/elements/definitions.d.ts +147 -0
  76. package/dist/types/elements/kit.d.ts +7 -0
  77. package/dist/types/elements/reflect.d.ts +6 -3
  78. package/dist/types/index.d.ts +18 -1
  79. package/dist/types/internal/agent-model.d.ts +587 -0
  80. package/dist/types/internal/date-locale.d.ts +7 -0
  81. package/dist/types/internal/highlight.d.ts +24 -0
  82. package/dist/types/internal/json-patch.d.ts +146 -0
  83. package/dist/types/internal/presence-loop.d.ts +148 -0
  84. package/dist/types/locales/de.d.ts +13 -0
  85. package/dist/types/locales/en.d.ts +2 -0
  86. package/dist/types/locales/index.d.ts +823 -0
  87. package/dist/types/zeyos/view.d.ts +8 -1
  88. package/dist/zx-zeyos.esm.js +20505 -18748
  89. package/dist/zx-zeyos.esm.min.js +5 -5
  90. package/dist/zx.core.css +1276 -0
  91. package/dist/zx.core.min.css +1 -0
  92. package/dist/zx.css +2424 -134
  93. package/dist/zx.esm.js +46167 -28468
  94. package/dist/zx.esm.min.js +40 -8
  95. package/dist/zx.global.js +46167 -28468
  96. package/dist/zx.global.min.js +40 -8
  97. package/dist/zx.layered.css +17302 -0
  98. package/dist/zx.layered.min.css +1 -0
  99. package/dist/zx.min.css +1 -1
  100. package/docs/agent-catalog.json +12501 -0
  101. package/docs/agent-surfaces.md +340 -0
  102. package/docs/api.json +2057 -166
  103. package/docs/llms.md +1458 -58
  104. package/docs/llms.txt +38 -8
  105. package/package.json +29 -6
  106. package/src/components/account-menu/account-menu.js +6 -3
  107. package/src/components/activity-item/activity-item.js +2 -1
  108. package/src/components/activity-list/activity-list.js +16 -10
  109. package/src/components/agent-thread/ag-ui.js +1439 -0
  110. package/src/components/agent-thread/agent-thread.css +417 -0
  111. package/src/components/agent-thread/agent-thread.js +1670 -0
  112. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  113. package/src/components/app-sidebar/app-sidebar.js +18 -8
  114. package/src/components/approval-card/approval-card.css +289 -0
  115. package/src/components/approval-card/approval-card.js +1378 -0
  116. package/src/components/avatar/avatar.css +56 -1
  117. package/src/components/avatar/avatar.js +148 -26
  118. package/src/components/block-view/block-view.css +300 -0
  119. package/src/components/block-view/block-view.js +524 -0
  120. package/src/components/breadcrumb/breadcrumb.js +8 -5
  121. package/src/components/calendar/calendar-model.js +8 -2
  122. package/src/components/calendar/calendar.js +53 -18
  123. package/src/components/chart/chart.js +54 -23
  124. package/src/components/code-editor/code-editor.js +45 -8
  125. package/src/components/code-editor/field-adapter.js +1 -1
  126. package/src/components/composer/composer.css +482 -0
  127. package/src/components/composer/composer.js +1815 -0
  128. package/src/components/composer/queue.js +78 -0
  129. package/src/components/context-menu/context-menu.js +12 -1
  130. package/src/components/copy/copy-button.js +9 -7
  131. package/src/components/copy/copy-input.js +10 -6
  132. package/src/components/date-picker/date-picker.js +2 -1
  133. package/src/components/date-picker/date-range-picker.js +8 -7
  134. package/src/components/datebox/date-range-box.js +3 -9
  135. package/src/components/datebox/datebox.js +18 -21
  136. package/src/components/datebox/placeholder.js +18 -0
  137. package/src/components/dialog/dialog.js +1 -1
  138. package/src/components/dock/dock.js +34 -13
  139. package/src/components/entity-ref/entity-ref.js +16 -5
  140. package/src/components/field-upload/field-upload.js +81 -38
  141. package/src/components/file-item/file-item.js +70 -40
  142. package/src/components/file-list/file-list.js +15 -9
  143. package/src/components/filter/filter-model.js +46 -8
  144. package/src/components/filter/filter.css +3 -3
  145. package/src/components/filter/filter.js +29 -10
  146. package/src/components/filter-panel/filter-panel.js +13 -5
  147. package/src/components/finder/finder.js +50 -26
  148. package/src/components/flag/flag.css +40 -0
  149. package/src/components/flag/flag.js +177 -0
  150. package/src/components/form/form.js +1 -1
  151. package/src/components/grid/grid.js +22 -8
  152. package/src/components/kanban-view/kanban-view.js +51 -81
  153. package/src/components/launcher/launcher.js +17 -2
  154. package/src/components/list-toolbar/list-toolbar.js +2 -1
  155. package/src/components/master-panel/master-panel.js +1 -1
  156. package/src/components/menu-button/menu-button.js +4 -0
  157. package/src/components/message/message.js +3 -0
  158. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  159. package/src/components/navigation-bar/navigation-bar.js +3 -3
  160. package/src/components/number-field/number-field.js +29 -13
  161. package/src/components/prompt-starters/prompt-starters.css +91 -0
  162. package/src/components/prompt-starters/prompt-starters.js +206 -0
  163. package/src/components/prose/prose.js +14 -10
  164. package/src/components/questionnaire/conditions.js +666 -0
  165. package/src/components/questionnaire/items.js +150 -41
  166. package/src/components/questionnaire/questionnaire.js +126 -32
  167. package/src/components/rating/rating.js +5 -4
  168. package/src/components/run-status/run-status.css +208 -0
  169. package/src/components/run-status/run-status.js +782 -0
  170. package/src/components/run-trace/run-trace.css +443 -0
  171. package/src/components/run-trace/run-trace.js +1209 -0
  172. package/src/components/select/country.js +136 -0
  173. package/src/components/select/field-adapter.js +7 -2
  174. package/src/components/select/locale.js +219 -0
  175. package/src/components/select/select.css +20 -22
  176. package/src/components/select/select.js +94 -12
  177. package/src/components/sheet/sheet-stack.js +10 -1
  178. package/src/components/slider/slider.js +7 -2
  179. package/src/components/sort-control/sort-control.js +15 -5
  180. package/src/components/source-list/source-list.css +208 -0
  181. package/src/components/source-list/source-list.js +358 -0
  182. package/src/components/split-view/split-view.js +5 -3
  183. package/src/components/surface/catalog.js +1334 -0
  184. package/src/components/surface/elicit.js +107 -0
  185. package/src/components/surface/mcp.js +243 -0
  186. package/src/components/surface/schema.js +644 -0
  187. package/src/components/surface/stream.js +245 -0
  188. package/src/components/surface/surface.css +308 -0
  189. package/src/components/surface/surface.js +2291 -0
  190. package/src/components/surface/text.js +513 -0
  191. package/src/components/surface/validate.js +2218 -0
  192. package/src/components/tabbox/tabbox.js +9 -0
  193. package/src/components/table/table.css +63 -3
  194. package/src/components/table/table.js +167 -28
  195. package/src/components/table/window.js +317 -0
  196. package/src/components/toolbar/toolbar.js +12 -7
  197. package/src/components/tooltip/tooltip.css +2 -3
  198. package/src/components/tooltip/tooltip.js +32 -5
  199. package/src/components/tree/tree.js +53 -23
  200. package/src/core/component.js +25 -1
  201. package/src/core/date.js +62 -16
  202. package/src/core/dom.js +22 -2
  203. package/src/core/format.js +15 -13
  204. package/src/core/http.js +29 -20
  205. package/src/core/i18n.js +83 -10
  206. package/src/core/keyboard.js +79 -8
  207. package/src/core/messages.js +519 -2
  208. package/src/core/overlay-host.js +1 -0
  209. package/src/core/storage.js +59 -6
  210. package/src/elements/define.js +178 -130
  211. package/src/elements/definitions.js +229 -0
  212. package/src/elements/kit.js +444 -0
  213. package/src/elements/reflect.js +8 -3
  214. package/src/index.js +18 -1
  215. package/src/internal/agent-model.js +488 -0
  216. package/src/internal/date-locale.js +11 -0
  217. package/src/internal/highlight.js +104 -0
  218. package/src/internal/json-patch.js +405 -0
  219. package/src/internal/presence-loop.js +343 -0
  220. package/src/locales/de.js +911 -0
  221. package/src/locales/en.js +2 -0
  222. package/src/locales/index.js +7 -0
  223. package/src/zeyos/calendar.js +2 -1
  224. package/src/zeyos/form.js +2 -1
  225. package/src/zeyos/launcher.js +7 -6
  226. package/src/zeyos/module-bar.js +2 -1
  227. package/src/zeyos/schema.js +37 -23
  228. package/src/zeyos/select.js +4 -3
  229. package/src/zeyos/table.js +2 -13
  230. package/src/zeyos/view.js +57 -17
  231. package/styles/core.css +11 -0
  232. package/styles/tokens/semantic.css +1 -0
  233. package/styles/zeyos.css +2 -0
  234. package/styles/zx.css +11 -8
  235. 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
+ ```