@zeyos/zx 5.6.0 → 5.7.1

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 (227) hide show
  1. package/CHANGELOG.md +188 -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 +142 -14
  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/breadcrumb/breadcrumb.d.ts +3 -3
  11. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  12. package/dist/types/components/calendar/calendar.d.ts +12 -4
  13. package/dist/types/components/chart/chart.d.ts +25 -13
  14. package/dist/types/components/checklist/checklist.d.ts +29 -0
  15. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  16. package/dist/types/components/composer/composer.d.ts +206 -4
  17. package/dist/types/components/composer/queue.d.ts +76 -0
  18. package/dist/types/components/copy/copy-button.d.ts +6 -4
  19. package/dist/types/components/copy/copy-input.d.ts +10 -6
  20. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  21. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  22. package/dist/types/components/dialog/dialog.d.ts +2 -2
  23. package/dist/types/components/dock/dock.d.ts +12 -3
  24. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  25. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  26. package/dist/types/components/file-item/file-item.d.ts +3 -2
  27. package/dist/types/components/file-list/file-list.d.ts +14 -8
  28. package/dist/types/components/filter/filter-model.d.ts +31 -1
  29. package/dist/types/components/filter/filter.d.ts +20 -2
  30. package/dist/types/components/finder/finder.d.ts +14 -6
  31. package/dist/types/components/flag/flag.d.ts +99 -0
  32. package/dist/types/components/grid/grid.d.ts +1 -1
  33. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  34. package/dist/types/components/launcher/launcher.d.ts +2 -0
  35. package/dist/types/components/modal/modal.d.ts +34 -8
  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 +41 -7
  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/select/country.d.ts +106 -0
  45. package/dist/types/components/select/field-adapter.d.ts +2 -1
  46. package/dist/types/components/select/locale.d.ts +102 -0
  47. package/dist/types/components/select/select.d.ts +41 -2
  48. package/dist/types/components/sheet/sheet.d.ts +2 -2
  49. package/dist/types/components/slider/slider.d.ts +1 -0
  50. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  51. package/dist/types/components/source-list/source-list.d.ts +7 -5
  52. package/dist/types/components/split-view/split-view.d.ts +5 -3
  53. package/dist/types/components/surface/catalog.d.ts +260 -0
  54. package/dist/types/components/surface/elicit.d.ts +81 -0
  55. package/dist/types/components/surface/mcp.d.ts +165 -0
  56. package/dist/types/components/surface/schema.d.ts +314 -0
  57. package/dist/types/components/surface/stream.d.ts +118 -0
  58. package/dist/types/components/surface/surface.d.ts +718 -0
  59. package/dist/types/components/surface/text.d.ts +277 -0
  60. package/dist/types/components/surface/validate.d.ts +339 -0
  61. package/dist/types/components/table/table.d.ts +55 -3
  62. package/dist/types/components/table/window.d.ts +203 -0
  63. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  64. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  65. package/dist/types/components/tree/tree.d.ts +20 -13
  66. package/dist/types/core/component.d.ts +10 -0
  67. package/dist/types/core/date.d.ts +8 -1
  68. package/dist/types/core/dom.d.ts +15 -0
  69. package/dist/types/core/http.d.ts +10 -0
  70. package/dist/types/core/i18n.d.ts +38 -0
  71. package/dist/types/core/messages.d.ts +344 -1
  72. package/dist/types/core/storage.d.ts +7 -2
  73. package/dist/types/elements/define.d.ts +21 -46
  74. package/dist/types/elements/definitions.d.ts +147 -0
  75. package/dist/types/elements/kit.d.ts +7 -0
  76. package/dist/types/elements/reflect.d.ts +6 -3
  77. package/dist/types/index.d.ts +10 -1
  78. package/dist/types/internal/date-locale.d.ts +7 -0
  79. package/dist/types/internal/json-patch.d.ts +146 -0
  80. package/dist/types/locales/de.d.ts +13 -0
  81. package/dist/types/locales/en.d.ts +2 -0
  82. package/dist/types/locales/index.d.ts +823 -0
  83. package/dist/types/zeyos/view.d.ts +8 -1
  84. package/dist/zx-zeyos.esm.js +16852 -15131
  85. package/dist/zx-zeyos.esm.min.js +5 -5
  86. package/dist/zx.core.css +1276 -0
  87. package/dist/zx.core.min.css +1 -0
  88. package/dist/zx.css +520 -143
  89. package/dist/zx.esm.js +40940 -29684
  90. package/dist/zx.esm.min.js +36 -23
  91. package/dist/zx.global.js +40940 -29684
  92. package/dist/zx.global.min.js +36 -23
  93. package/dist/zx.layered.css +17315 -0
  94. package/dist/zx.layered.min.css +1 -0
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +12501 -0
  97. package/docs/agent-surfaces.md +340 -0
  98. package/docs/api.json +909 -137
  99. package/docs/llms.md +1046 -80
  100. package/docs/llms.txt +30 -9
  101. package/package.json +29 -6
  102. package/src/components/account-menu/account-menu.js +6 -3
  103. package/src/components/activity-item/activity-item.js +2 -1
  104. package/src/components/activity-list/activity-list.js +16 -10
  105. package/src/components/agent-thread/ag-ui.js +1439 -0
  106. package/src/components/agent-thread/agent-thread.js +359 -54
  107. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  108. package/src/components/app-sidebar/app-sidebar.js +18 -8
  109. package/src/components/approval-card/approval-card.js +3 -2
  110. package/src/components/block-view/block-view.js +7 -6
  111. package/src/components/breadcrumb/breadcrumb.js +8 -5
  112. package/src/components/button/button.css +24 -11
  113. package/src/components/calendar/calendar-model.js +8 -2
  114. package/src/components/calendar/calendar.js +53 -18
  115. package/src/components/chart/chart.js +54 -23
  116. package/src/components/checklist/checklist.css +9 -1
  117. package/src/components/checklist/checklist.js +59 -3
  118. package/src/components/checklist/field-adapter.js +2 -11
  119. package/src/components/code-editor/code-editor.js +45 -8
  120. package/src/components/code-editor/field-adapter.js +1 -1
  121. package/src/components/composer/composer.css +80 -1
  122. package/src/components/composer/composer.js +390 -16
  123. package/src/components/composer/queue.js +78 -0
  124. package/src/components/context-menu/context-menu.js +12 -1
  125. package/src/components/copy/copy-button.js +9 -7
  126. package/src/components/copy/copy-input.js +10 -6
  127. package/src/components/date-picker/date-picker.js +2 -1
  128. package/src/components/date-picker/date-range-picker.js +8 -7
  129. package/src/components/datebox/date-range-box.js +3 -9
  130. package/src/components/datebox/datebox.js +18 -21
  131. package/src/components/datebox/placeholder.js +18 -0
  132. package/src/components/dialog/dialog.js +4 -5
  133. package/src/components/dock/dock.js +34 -13
  134. package/src/components/entity-ref/entity-ref.js +16 -5
  135. package/src/components/field-upload/field-upload.js +81 -38
  136. package/src/components/file-item/file-item.js +70 -40
  137. package/src/components/file-list/file-list.js +15 -9
  138. package/src/components/filter/filter-model.js +46 -8
  139. package/src/components/filter/filter.css +3 -3
  140. package/src/components/filter/filter.js +29 -10
  141. package/src/components/filter-panel/filter-panel.js +13 -5
  142. package/src/components/finder/finder.js +50 -26
  143. package/src/components/flag/flag.css +40 -0
  144. package/src/components/flag/flag.js +177 -0
  145. package/src/components/form/form.js +1 -1
  146. package/src/components/grid/grid.js +22 -8
  147. package/src/components/kanban-view/kanban-view.js +51 -81
  148. package/src/components/launcher/launcher.js +17 -2
  149. package/src/components/list-toolbar/list-toolbar.js +2 -1
  150. package/src/components/master-panel/master-panel.js +1 -1
  151. package/src/components/menu-button/menu-button.js +4 -0
  152. package/src/components/message/message.js +3 -0
  153. package/src/components/modal/modal.js +62 -8
  154. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  155. package/src/components/navigation-bar/navigation-bar.js +3 -3
  156. package/src/components/number-field/number-field.js +98 -29
  157. package/src/components/prompt-starters/prompt-starters.css +91 -0
  158. package/src/components/prompt-starters/prompt-starters.js +206 -0
  159. package/src/components/prose/prose.js +14 -10
  160. package/src/components/questionnaire/conditions.js +666 -0
  161. package/src/components/questionnaire/items.js +150 -41
  162. package/src/components/questionnaire/questionnaire.js +126 -32
  163. package/src/components/rating/rating.js +5 -4
  164. package/src/components/run-status/run-status.js +2 -2
  165. package/src/components/select/country.js +136 -0
  166. package/src/components/select/field-adapter.js +7 -2
  167. package/src/components/select/locale.js +219 -0
  168. package/src/components/select/select.css +20 -22
  169. package/src/components/select/select.js +94 -12
  170. package/src/components/sheet/sheet-stack.js +10 -1
  171. package/src/components/sheet/sheet.js +12 -5
  172. package/src/components/slider/slider.js +7 -2
  173. package/src/components/sort-control/sort-control.js +15 -5
  174. package/src/components/source-list/source-list.js +7 -4
  175. package/src/components/split-view/split-view.js +5 -3
  176. package/src/components/surface/catalog.js +1334 -0
  177. package/src/components/surface/elicit.js +107 -0
  178. package/src/components/surface/mcp.js +243 -0
  179. package/src/components/surface/schema.js +644 -0
  180. package/src/components/surface/stream.js +245 -0
  181. package/src/components/surface/surface.css +308 -0
  182. package/src/components/surface/surface.js +2291 -0
  183. package/src/components/surface/text.js +513 -0
  184. package/src/components/surface/validate.js +2218 -0
  185. package/src/components/tabbox/tabbox.js +9 -0
  186. package/src/components/table/table.css +63 -3
  187. package/src/components/table/table.js +167 -28
  188. package/src/components/table/window.js +317 -0
  189. package/src/components/toolbar/toolbar.js +12 -7
  190. package/src/components/tooltip/tooltip.css +2 -3
  191. package/src/components/tooltip/tooltip.js +32 -5
  192. package/src/components/tree/tree.js +53 -23
  193. package/src/core/component.js +25 -1
  194. package/src/core/date.js +62 -16
  195. package/src/core/dom.js +67 -4
  196. package/src/core/format.js +15 -13
  197. package/src/core/http.js +29 -20
  198. package/src/core/i18n.js +83 -10
  199. package/src/core/icons.js +13 -2
  200. package/src/core/keyboard.js +79 -8
  201. package/src/core/messages.js +376 -2
  202. package/src/core/overlay-host.js +1 -0
  203. package/src/core/position.js +3 -2
  204. package/src/core/storage.js +59 -6
  205. package/src/elements/define.js +178 -130
  206. package/src/elements/definitions.js +229 -0
  207. package/src/elements/kit.js +444 -0
  208. package/src/elements/reflect.js +8 -3
  209. package/src/index.js +10 -1
  210. package/src/internal/date-locale.js +11 -0
  211. package/src/internal/json-patch.js +405 -0
  212. package/src/locales/de.js +911 -0
  213. package/src/locales/en.js +2 -0
  214. package/src/locales/index.js +7 -0
  215. package/src/zeyos/calendar.js +2 -1
  216. package/src/zeyos/form.js +2 -1
  217. package/src/zeyos/launcher.js +7 -6
  218. package/src/zeyos/module-bar.js +2 -1
  219. package/src/zeyos/schema.js +37 -23
  220. package/src/zeyos/select.js +4 -3
  221. package/src/zeyos/table.js +2 -13
  222. package/src/zeyos/view.js +57 -17
  223. package/styles/core.css +11 -0
  224. package/styles/tokens/semantic.css +1 -0
  225. package/styles/zeyos.css +2 -0
  226. package/styles/zx.css +4 -8
  227. package/styles/zx.layered.css +1 -0
@@ -0,0 +1,277 @@
1
+ export type SurfaceDocument = import('./validate.js').SurfaceDocument;
2
+ export type SurfaceNode = import('./validate.js').SurfaceNode;
3
+ export type SurfaceAction = import('./validate.js').SurfaceAction;
4
+ export type SurfaceIntent = import('./catalog.js').SurfaceIntent;
5
+ export type ReplyConfirmation = 'clicked' | 'typed' | null;
6
+ export type ReplyReason = 'cancelled' | 'escape' | 'closed' | 'superseded' | 'stopped' | 'destroyed' | string;
7
+ export type SurfaceReply = {
8
+ /**
9
+ * The reply format.
10
+ */
11
+ zx: 'reply/1';
12
+ /**
13
+ * The surface's id; `null` when a surface that never began had
14
+ * no valid id to name.
15
+ */
16
+ surface: string | null;
17
+ /**
18
+ * The action taken: an action id of the surface's own, a default one
19
+ * (`submit`, `confirm`, `approve`, `reject`), or `cancel` / `dismiss` when it was closed.
20
+ */
21
+ action: string;
22
+ /**
23
+ * The idempotency key, `<surface>#<action>` (`#<action>` without a surface
24
+ * id): the same answer twice has the same key, so a server acts on it once.
25
+ */
26
+ key: string;
27
+ /**
28
+ * The visible inputs' values by name; `{answers, path}`
29
+ * for a questionnaire; `{}` for `show`, `confirm`, `reject` and a closed surface.
30
+ */
31
+ values: Record<string, unknown>;
32
+ /**
33
+ * How the person confirmed.
34
+ */
35
+ confirmation: ReplyConfirmation;
36
+ /**
37
+ * Local ISO date-time of the answer, `YYYY-MM-DDTHH:MM:SS`.
38
+ */
39
+ at: string;
40
+ /**
41
+ * The application's token, unchanged; only when it gave one.
42
+ */
43
+ token?: string;
44
+ /**
45
+ * The ids of actions the application's policy denied, which were
46
+ * not drawn; only when there were any.
47
+ */
48
+ removed?: string[];
49
+ /**
50
+ * Why a closing reply (`cancel`, `dismiss`) was sent.
51
+ */
52
+ reason?: ReplyReason;
53
+ };
54
+ export type ReplyDetails = {
55
+ /**
56
+ * The action id.
57
+ */
58
+ action: string;
59
+ /**
60
+ * The values, before they are shaped for the intent.
61
+ */
62
+ values?: Record<string, unknown>;
63
+ confirmation?: ReplyConfirmation;
64
+ token?: string | null;
65
+ removed?: string[];
66
+ reason?: ReplyReason;
67
+ /**
68
+ * The time of the answer; now when left out.
69
+ */
70
+ at?: Date | string;
71
+ };
72
+ export type SurfaceVisibility = {
73
+ /**
74
+ * Ids of nodes hidden by their own condition or an ancestor's.
75
+ */
76
+ hiddenNodes: Set<string>;
77
+ /**
78
+ * Per `fields` node, the properties hidden by
79
+ * their `x-zx.visible` (not counting a hidden node).
80
+ */
81
+ hiddenFields: Map<string, Set<string>>;
82
+ /**
83
+ * The visible inputs' names, in the order they are declared.
84
+ */
85
+ names: string[];
86
+ /**
87
+ * The node holding each input name.
88
+ */
89
+ owners: Map<string, string>;
90
+ };
91
+ /** @typedef {import('./validate.js').SurfaceDocument} SurfaceDocument */
92
+ /** @typedef {import('./validate.js').SurfaceNode} SurfaceNode */
93
+ /** @typedef {import('./validate.js').SurfaceAction} SurfaceAction */
94
+ /** @typedef {import('./catalog.js').SurfaceIntent} SurfaceIntent */
95
+ /**
96
+ * How the person confirmed the action: `clicked` in a confirmation dialog, `typed` the text a
97
+ * type-to-confirm dialog asked for, or `null` when the application's policy asked for nothing, or
98
+ * the surface was closed.
99
+ * @typedef {'clicked'|'typed'|null} ReplyConfirmation
100
+ */
101
+ /**
102
+ * Why a surface ended without an action of its own: closed by the person, superseded by a newer
103
+ * surface, stopped with its run, or destroyed unanswered.
104
+ * @typedef {'cancelled'|'escape'|'closed'|'superseded'|'stopped'|'destroyed'|string} ReplyReason
105
+ */
106
+ /**
107
+ * What every surface ends in, exactly once. It records what the page did; it proves nothing, so
108
+ * the application's server runs its policy again for the named tool before acting.
109
+ * @typedef {Object} SurfaceReply
110
+ * @property {'reply/1'} zx The reply format.
111
+ * @property {string|null} surface The surface's id; `null` when a surface that never began had
112
+ * no valid id to name.
113
+ * @property {string} action The action taken: an action id of the surface's own, a default one
114
+ * (`submit`, `confirm`, `approve`, `reject`), or `cancel` / `dismiss` when it was closed.
115
+ * @property {string} key The idempotency key, `<surface>#<action>` (`#<action>` without a surface
116
+ * id): the same answer twice has the same key, so a server acts on it once.
117
+ * @property {Record<string, unknown>} values The visible inputs' values by name; `{answers, path}`
118
+ * for a questionnaire; `{}` for `show`, `confirm`, `reject` and a closed surface.
119
+ * @property {ReplyConfirmation} confirmation How the person confirmed.
120
+ * @property {string} at Local ISO date-time of the answer, `YYYY-MM-DDTHH:MM:SS`.
121
+ * @property {string} [token] The application's token, unchanged; only when it gave one.
122
+ * @property {string[]} [removed] The ids of actions the application's policy denied, which were
123
+ * not drawn; only when there were any.
124
+ * @property {ReplyReason} [reason] Why a closing reply (`cancel`, `dismiss`) was sent.
125
+ */
126
+ /**
127
+ * What `createReply()` takes.
128
+ * @typedef {Object} ReplyDetails
129
+ * @property {string} action The action id.
130
+ * @property {Record<string, unknown>} [values] The values, before they are shaped for the intent.
131
+ * @property {ReplyConfirmation} [confirmation=null]
132
+ * @property {string|null} [token=null]
133
+ * @property {string[]} [removed=[]]
134
+ * @property {ReplyReason} [reason]
135
+ * @property {Date|string} [at] The time of the answer; now when left out.
136
+ */
137
+ /**
138
+ * Which nodes and inputs of a surface are visible for a set of answers.
139
+ * @typedef {Object} SurfaceVisibility
140
+ * @property {Set<string>} hiddenNodes Ids of nodes hidden by their own condition or an ancestor's.
141
+ * @property {Map<string, Set<string>>} hiddenFields Per `fields` node, the properties hidden by
142
+ * their `x-zx.visible` (not counting a hidden node).
143
+ * @property {string[]} names The visible inputs' names, in the order they are declared.
144
+ * @property {Map<string, string>} owners The node holding each input name.
145
+ */
146
+ /**
147
+ * The English texts of every message the surface shows: the `surface.*` entries of the library's
148
+ * catalogue, read from it so there is one source. A host translates them through the Surface's
149
+ * `msg` option or its translator; `surfaceText()` takes a `msg` function.
150
+ * @type {Readonly<Record<string, string>>}
151
+ */
152
+ export declare const SURFACE_MESSAGES: Readonly<Record<string, string>>;
153
+ /** Actions that close a surface rather than answer it. */
154
+ export declare const CLOSING_ACTIONS: readonly string[];
155
+ /**
156
+ * The English message for a key, with `%1`, `%2`, … filled in. The default `msg` of
157
+ * `surfaceText()`.
158
+ * @param {string} key
159
+ * @param {...unknown} args
160
+ * @returns {string}
161
+ */
162
+ export declare function surfaceMessage(key: string, ...args: unknown[]): string;
163
+ /**
164
+ * A message resolver that answers the way a Surface's own `msg()` does: the `msg` table for the
165
+ * active language, then its flat entries, then the host translator (`setTranslator()`), then the
166
+ * English catalogue, then the key.
167
+ * @param {Record<string, any>|null|undefined} msg The `msg` option, flat or by language.
168
+ * @param {string} [lang] The language; `getLanguage()` when absent, read at each call.
169
+ * @returns {(key: string, ...args: unknown[]) => string}
170
+ */
171
+ export declare function messageResolver(msg: Record<string, any> | null | undefined, lang?: string): (key: string, ...args: unknown[]) => string;
172
+ /**
173
+ * Escapes the characters inline text reads as markup (`*`, `` ` ``, `[`, `\`), so untrusted text
174
+ * — a server's message, an address — is drawn exactly as given by a `text` node. With `max`, the
175
+ * escaped text is cut to at most that many characters, never between an escape and the character
176
+ * it escapes, nor inside a surrogate pair.
177
+ * @param {string} value
178
+ * @param {number} [max=Infinity] The most characters the result may hold.
179
+ * @returns {string}
180
+ */
181
+ export declare function plainInline(value: string, max?: number): string;
182
+ /**
183
+ * Reads a node property, resolving a `{"$data": "/pointer"}` binding against the surface data.
184
+ * @param {SurfaceNode} node
185
+ * @param {string} prop
186
+ * @param {unknown} data
187
+ * @returns {unknown} The value, or `undefined` when it is absent or its pointer finds nothing.
188
+ */
189
+ export declare function readProp(node: SurfaceNode, prop: string, data: unknown): unknown;
190
+ /**
191
+ * The input names a node declares, in order: a `fields` node's schema properties, or the `name`
192
+ * of any other input node (a table only while it is selectable).
193
+ * @param {SurfaceNode} node
194
+ * @param {unknown} data
195
+ * @returns {string[]}
196
+ */
197
+ export declare function inputNames(node: SurfaceNode, data: unknown): string[];
198
+ /**
199
+ * Decides which nodes and inputs are visible, walking the tree depth first from `root` as the
200
+ * conditions are declared. A condition sees only the answers of visible inputs that come before
201
+ * it, so hiding an input also hides what depends on it. A malformed condition counts as true:
202
+ * the node stays visible, as validation reports it.
203
+ * @param {SurfaceDocument|{root: string[], nodes: SurfaceNode[]|Map<string, SurfaceNode>, data?: unknown}} document
204
+ * @param {Record<string, unknown>} answers The inputs' values by name, hidden ones included.
205
+ * @returns {SurfaceVisibility}
206
+ */
207
+ export declare function surfaceVisibility(document: SurfaceDocument | {
208
+ root: string[];
209
+ nodes: SurfaceNode[] | Map<string, SurfaceNode>;
210
+ data?: unknown;
211
+ }, answers: Record<string, unknown>): SurfaceVisibility;
212
+ /**
213
+ * Builds a reply. Values are shaped for the intent: `show` and `confirm` reply `{}`, as do
214
+ * `reject` and a closed surface; a questionnaire's `submit` keeps `{answers, path}` for the steps
215
+ * visible for those answers; every other reply keeps only the inputs that are visible for the
216
+ * values given, so a hidden input never leaves the page.
217
+ * @param {SurfaceDocument} document The surface, as validated.
218
+ * @param {ReplyDetails} details
219
+ * @returns {SurfaceReply}
220
+ */
221
+ export declare function createReply(document: SurfaceDocument, details: ReplyDetails): SurfaceReply;
222
+ export type SurfaceTextOptions = {
223
+ /**
224
+ * Resolves a message key; English
225
+ * by default (`SURFACE_MESSAGES`).
226
+ */
227
+ msg?: (key: string, ...args: unknown[]) => string;
228
+ /**
229
+ * The record entities the document may name, as
230
+ * the Surface's `resolve.entities`.
231
+ */
232
+ entities?: Iterable<string> | null;
233
+ };
234
+ /**
235
+ * Options of `surfaceText()`.
236
+ * @typedef {Object} SurfaceTextOptions
237
+ * @property {(key: string, ...args: unknown[]) => string} [msg] Resolves a message key; English
238
+ * by default (`SURFACE_MESSAGES`).
239
+ * @property {Iterable<string>|null} [entities=null] The record entities the document may name, as
240
+ * the Surface's `resolve.entities`.
241
+ */
242
+ /**
243
+ * The receipt of an answered surface as plain text, for an audit log or a notification: the
244
+ * title, each answered value under its label (choice and enum titles rather than raw values), the
245
+ * selected rows by their row id, the verdict and the time. Inputs hidden for the reply's values
246
+ * are never included, whatever the reply carries. Pure.
247
+ * @param {SurfaceDocument} document The surface, as given to the Surface or from `toDocument()`.
248
+ * @param {SurfaceReply} reply Its reply.
249
+ * @param {SurfaceTextOptions} [options]
250
+ * @returns {string} Lines separated by `\n`.
251
+ */
252
+ export declare function surfaceText(document: SurfaceDocument, reply: SurfaceReply, options?: SurfaceTextOptions): string;
253
+ /**
254
+ * The verdict of an action: "Submitted", "Cancelled", …, or "Chose “<label>”" for an action of
255
+ * the surface's own.
256
+ * @param {string} action
257
+ * @param {SurfaceAction[]} actions The surface's own actions.
258
+ * @param {(key: string, ...args: unknown[]) => string} [msg]
259
+ * @returns {string}
260
+ */
261
+ export declare function verdictText(action: string, actions: SurfaceAction[], msg?: (key: string, ...args: unknown[]) => string): string;
262
+ /**
263
+ * A questionnaire's answers and path, limited to the steps visible for those answers, by the
264
+ * Questionnaire's own rule. Without steps to read, what was given stands.
265
+ * @param {Array<Record<string, any>>} steps @param {Record<string, unknown>} answers @param {string[]} path
266
+ * @returns {{answers: Record<string, unknown>, path: string[]}}
267
+ */
268
+ export declare function visibleSteps(steps: Array<Record<string, any>>, answers: Record<string, unknown>, path: string[]): {
269
+ answers: Record<string, unknown>;
270
+ path: string[];
271
+ };
272
+ /**
273
+ * A local ISO date-time without a zone, `YYYY-MM-DDTHH:MM:SS`.
274
+ * @param {Date|string} value
275
+ * @returns {string}
276
+ */
277
+ export declare function localDateTime(value: Date | string): string;
@@ -0,0 +1,339 @@
1
+ export type SurfaceCatalog = import('./catalog.js').SurfaceCatalog;
2
+ export type CatalogNode = import('./catalog.js').CatalogNode;
3
+ export type CatalogProp = import('./catalog.js').CatalogProp;
4
+ export type SurfaceIntent = import('./catalog.js').SurfaceIntent;
5
+ export type SurfacePlacement = import('./catalog.js').SurfacePlacement;
6
+ export type Condition = import('../questionnaire/conditions.js').Condition;
7
+ export type SurfaceErrorCode = 'invalid-op' | 'unknown-op' | 'version' | 'no-begin' | 'duplicate-begin' | 'ended' | 'unknown-intent' | 'unknown-type' | 'not-allowed' | 'unknown-node' | 'unknown-key' | 'token-refused' | 'confirmation-ignored' | 'forbidden-key' | 'not-finite' | 'limit' | 'invalid-value' | 'missing' | 'link-refused' | 'ref-refused' | 'pointer-invalid' | 'data-path' | 'condition' | 'unsupported-schema' | 'untitled-property' | 'duplicate-name' | 'cycle' | 'missing-node' | 'unreachable' | 'needs' | 'wrapped-list' | 'pointer-slash' | 'lifted-child' | 'draw-failed';
8
+ export type SurfaceError = {
9
+ /**
10
+ * What went wrong.
11
+ */
12
+ code: SurfaceErrorCode;
13
+ /**
14
+ * What went wrong, for the model.
15
+ */
16
+ message: string;
17
+ /**
18
+ * The surface it concerns.
19
+ */
20
+ surface?: string;
21
+ /**
22
+ * The node or action it concerns.
23
+ */
24
+ id?: string;
25
+ /**
26
+ * JSON Pointer to the problem inside the operation line, or inside the
27
+ * document for `validateDocument()`.
28
+ */
29
+ path?: string;
30
+ /**
31
+ * Present when the problem was repaired rather than dropped.
32
+ */
33
+ repaired?: true;
34
+ };
35
+ export type SurfaceNode = {
36
+ id: string;
37
+ type: string;
38
+ visible?: Condition;
39
+ children?: string[];
40
+ [key: string]: unknown;
41
+ };
42
+ export type SurfaceOp = {
43
+ op: 'begin';
44
+ zx: string;
45
+ surface: string;
46
+ intent: SurfaceIntent | null;
47
+ title?: string;
48
+ author?: string;
49
+ root: string[];
50
+ placement?: SurfacePlacement;
51
+ description?: string;
52
+ } | ({
53
+ op: 'node';
54
+ surface: string;
55
+ } & SurfaceNode) | {
56
+ op: 'patch';
57
+ surface: string;
58
+ id: string;
59
+ props: Record<string, unknown>;
60
+ } | {
61
+ op: 'append';
62
+ surface: string;
63
+ id: string;
64
+ text: string;
65
+ } | {
66
+ op: 'remove';
67
+ surface: string;
68
+ id: string;
69
+ } | {
70
+ op: 'data';
71
+ surface: string;
72
+ path: string;
73
+ value?: unknown;
74
+ remove?: true;
75
+ } | {
76
+ op: 'actions';
77
+ surface: string;
78
+ items: SurfaceAction[];
79
+ } | {
80
+ op: 'end';
81
+ surface: string;
82
+ sources?: SurfaceSource[];
83
+ };
84
+ export type SurfaceAction = {
85
+ /**
86
+ * Reported as the reply's `action`.
87
+ */
88
+ id: string;
89
+ /**
90
+ * The button text.
91
+ */
92
+ label: string;
93
+ /**
94
+ * How it looks; `danger` is presentation only.
95
+ */
96
+ kind?: 'primary' | 'secondary' | 'danger';
97
+ /**
98
+ * The tool the action triggers, for the application's policy.
99
+ */
100
+ tool?: string;
101
+ /**
102
+ * A supporting line.
103
+ */
104
+ description?: string;
105
+ };
106
+ export type SurfaceSource = {
107
+ /**
108
+ * The marker's number, `[n]`.
109
+ */
110
+ n: number;
111
+ /**
112
+ * What the source is.
113
+ */
114
+ title?: string;
115
+ /**
116
+ * The trace step it came from.
117
+ */
118
+ call?: string;
119
+ /**
120
+ * The record it is.
121
+ */
122
+ ref?: {
123
+ $ref: string;
124
+ id: string;
125
+ };
126
+ };
127
+ export type SurfaceDocument = {
128
+ /**
129
+ * The format version.
130
+ */
131
+ zx: 'surface/1';
132
+ /**
133
+ * The surface's id.
134
+ */
135
+ surface: string;
136
+ /**
137
+ * The intent; `null` after validation when it was invalid.
138
+ */
139
+ intent: SurfaceIntent | null;
140
+ /**
141
+ * What the surface is about; also its accessible name.
142
+ */
143
+ title?: string;
144
+ /**
145
+ * Who composed it, a key into the application's authors.
146
+ */
147
+ author?: string;
148
+ /**
149
+ * The ids of the top-level nodes, in order.
150
+ */
151
+ root: string[];
152
+ /**
153
+ * Where the surface asks to be placed.
154
+ */
155
+ placement?: SurfacePlacement;
156
+ /**
157
+ * A supporting line under the title.
158
+ */
159
+ description?: string;
160
+ /**
161
+ * Every node, each once.
162
+ */
163
+ nodes: SurfaceNode[];
164
+ /**
165
+ * Data that `{"$data": "/pointer"}` properties bind to.
166
+ */
167
+ data?: Record<string, unknown>;
168
+ /**
169
+ * The surface's own actions.
170
+ */
171
+ actions?: SurfaceAction[];
172
+ /**
173
+ * The sources of its citation markers.
174
+ */
175
+ sources?: SurfaceSource[];
176
+ };
177
+ export type OpResult = {
178
+ /**
179
+ * The operation as it may be applied, or `null` when it is refused.
180
+ */
181
+ op: SurfaceOp | null;
182
+ /**
183
+ * Everything found, repairs included.
184
+ */
185
+ errors: SurfaceError[];
186
+ /**
187
+ * Every operation to apply, in order.
188
+ */
189
+ ops: SurfaceOp[];
190
+ };
191
+ export type ValidationSettings = {
192
+ /**
193
+ * The record entities `{"$ref": …}` may name, as
194
+ * the Surface's `resolve.entities`. Without them every record is refused.
195
+ */
196
+ entities?: Iterable<string> | null;
197
+ };
198
+ export type ValidationState = {
199
+ /**
200
+ * The entities records may name.
201
+ */
202
+ entities: Set<string> | null;
203
+ /**
204
+ * The surfaces begun so far.
205
+ */
206
+ surfaces: Map<string, SurfaceTrack>;
207
+ };
208
+ export type SurfaceTrack = {
209
+ id: string;
210
+ intent: SurfaceIntent | null;
211
+ title?: string;
212
+ author?: string;
213
+ placement?: SurfacePlacement;
214
+ description?: string;
215
+ root: string[];
216
+ nodes: Map<string, SurfaceNode>;
217
+ /**
218
+ * Arrival order of each node id.
219
+ */
220
+ seq: Map<string, number>;
221
+ counter: number;
222
+ /**
223
+ * Parent id of each child id; `ROOT` for the top level.
224
+ */
225
+ parent: Map<string, string>;
226
+ /**
227
+ * Input names and the node holding them.
228
+ */
229
+ names: Map<string, {
230
+ owner: string;
231
+ seq: number;
232
+ }>;
233
+ data: Record<string, unknown>;
234
+ /**
235
+ * Characters of `data` written as JSON.
236
+ */
237
+ dataSize: number;
238
+ actions: SurfaceAction[] | null;
239
+ sources: SurfaceSource[] | null;
240
+ ended: boolean;
241
+ };
242
+ export type Context = {
243
+ surface: string;
244
+ errors: SurfaceError[];
245
+ /**
246
+ * Maps a path inside the operation to the reported path.
247
+ */
248
+ at: (path: string) => string;
249
+ entities: Set<string> | null;
250
+ };
251
+ /**
252
+ * Creates the state one stream's operations are validated against.
253
+ * @param {ValidationSettings} [options]
254
+ * @returns {ValidationState}
255
+ */
256
+ export declare function createValidationState(options?: ValidationSettings): ValidationState;
257
+ /**
258
+ * Validates one operation against the stream's state and the catalog, and records it in the state.
259
+ * @param {unknown} op The operation, as parsed from its line.
260
+ * @param {ValidationState} state From `createValidationState()`.
261
+ * @param {SurfaceCatalog} [catalog=CATALOG] The catalog, or a narrowed one.
262
+ * @returns {OpResult}
263
+ * @throws {TypeError} When the state or the catalog is not one of the library's.
264
+ */
265
+ export declare function validateOp(op: unknown, state: ValidationState, catalog?: SurfaceCatalog): OpResult;
266
+ /**
267
+ * Validates a whole document. The result is the document as it may be rendered: repairs applied,
268
+ * inline children lifted, invalid parts dropped, `null` members removed.
269
+ * @param {unknown} document The document.
270
+ * @param {SurfaceCatalog} [catalog=CATALOG] The catalog, or a narrowed one.
271
+ * @param {ValidationSettings} [options]
272
+ * @returns {{document: SurfaceDocument|null, errors: SurfaceError[]}} `document` is `null` when
273
+ * the document could not be read as a surface at all.
274
+ * @throws {TypeError} When the catalog is not one of the library's.
275
+ */
276
+ export declare function validateDocument(document: unknown, catalog?: SurfaceCatalog, options?: ValidationSettings): {
277
+ document: SurfaceDocument | null;
278
+ errors: SurfaceError[];
279
+ };
280
+ /**
281
+ * Reads one surface back from a validation state as a document.
282
+ * @param {ValidationState} state
283
+ * @param {string} surface The surface's id.
284
+ * @returns {SurfaceDocument|null} `null` when the surface has not begun.
285
+ */
286
+ export declare function stateToDocument(state: ValidationState, surface: string): SurfaceDocument | null;
287
+ /**
288
+ * The cells a node draws as a table, for the budget of `LIMITS.cells`. Rows bound to data count
289
+ * for every node they are drawn in.
290
+ * @param {SurfaceNode} node @param {unknown} data The surface's data.
291
+ * @returns {number} `0` for anything that is not a table, or has no rows yet.
292
+ */
293
+ export declare function tableCells(node: SurfaceNode, data: unknown): number;
294
+ /**
295
+ * @param {string} id A table's node id.
296
+ * @returns {string} What a table past the budget is told, here and by the surface drawing it.
297
+ */
298
+ export declare function cellLimitMessage(id: string): string;
299
+ /**
300
+ * Checks a value bound with `{"$data": …}` once it is resolved, as it would have been checked had
301
+ * the model written it into the node.
302
+ * @param {string} type The node type.
303
+ * @param {string} prop The property.
304
+ * @param {unknown} value The resolved value.
305
+ * @param {ValidationSettings & {node?: SurfaceNode}} [options] `node` gives a table's columns, for
306
+ * rows written as lists.
307
+ * @returns {{value: unknown, errors: SurfaceError[]}} `value` is `undefined` when it was dropped.
308
+ */
309
+ export declare function validateValue(type: string, prop: string, value: unknown, options?: ValidationSettings & {
310
+ node?: SurfaceNode;
311
+ }): {
312
+ value: unknown;
313
+ errors: SurfaceError[];
314
+ };
315
+ /**
316
+ * A link address, checked and normalised: `https:` only, absolute, in lower case, without
317
+ * credentials, spaces, backslashes, control or invisible formatting characters, at most
318
+ * `LIMITS.href` characters, and passing `safeHref()`. The address returned is the parsed one
319
+ * (`url.href`: Punycode host, default port dropped), so the host shown and the address opened come
320
+ * from the same string. Pure: it reports nothing, and is shared by every place that opens an
321
+ * address a surface or a server gave.
322
+ * @param {unknown} value The address as given.
323
+ * @returns {{href: string, problem: null}|{href: null, problem: string}} The normalised address,
324
+ * or why it is refused (English, written for the model).
325
+ */
326
+ export declare function normaliseLink(value: unknown): {
327
+ href: string;
328
+ problem: null;
329
+ } | {
330
+ href: null;
331
+ problem: string;
332
+ };
333
+ /**
334
+ * Names a value that has not been sanitized yet, for a message, without walking into it: it may
335
+ * nest deeper than the stack can follow, and be as long as a line.
336
+ * @param {unknown} value
337
+ * @returns {string}
338
+ */
339
+ export declare function describeValue(value: unknown): string;