@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,718 @@
1
+ import { Component } from '../../core/component.js';
2
+ import { Dialog } from '../dialog/dialog.js';
3
+ import { Fieldset } from '../fieldset/fieldset.js';
4
+ import { Questionnaire } from '../questionnaire/questionnaire.js';
5
+ import { Table } from '../table/table.js';
6
+ import { lineSplitter } from './stream.js';
7
+ export type SurfaceCatalog = import('./catalog.js').SurfaceCatalog;
8
+ export type SurfaceIntent = import('./catalog.js').SurfaceIntent;
9
+ export type SurfacePlacement = import('./catalog.js').SurfacePlacement;
10
+ export type SurfaceDocument = import('./validate.js').SurfaceDocument;
11
+ export type SurfaceNode = import('./validate.js').SurfaceNode;
12
+ export type SurfaceOp = import('./validate.js').SurfaceOp;
13
+ export type SurfaceAction = import('./validate.js').SurfaceAction;
14
+ export type SurfaceError = import('./validate.js').SurfaceError;
15
+ export type SurfaceSource = import('./validate.js').SurfaceSource;
16
+ export type SurfaceReply = import('./text.js').SurfaceReply;
17
+ export type ReplyReason = import('./text.js').ReplyReason;
18
+ export type ChartAdapter = import('../chart/chart.js').ChartAdapter;
19
+ export type EntityRefOptions = import('../entity-ref/entity-ref.js').EntityRefOptions;
20
+ export type PolicyLevel = 'allow' | 'confirm' | 'type-to-confirm' | 'deny';
21
+ export type PolicyDecision = PolicyLevel | {
22
+ level: PolicyLevel;
23
+ confirmText?: string;
24
+ message?: string;
25
+ };
26
+ export type SurfacePolicy = (action: SurfaceAction, surface: SurfaceDocument) => PolicyDecision;
27
+ export type SurfaceResolve = {
28
+ /**
29
+ * A record
30
+ * to the options of the EntityRef that draws it; `null` draws its id as text.
31
+ */
32
+ ref?: (ref: {
33
+ $ref: string;
34
+ id: string;
35
+ }) => EntityRefOptions | null | undefined;
36
+ /**
37
+ * A
38
+ * link's address to the address to open: `false` or `null` refuses it, and the text is shown
39
+ * without a link; `true` or nothing keeps it.
40
+ */
41
+ link?: (href: string, context: {
42
+ text: string;
43
+ }) => string | boolean | null | undefined;
44
+ /**
45
+ * An asset name to an image address
46
+ * the application serves. No node of the current catalog shows one; reserved.
47
+ */
48
+ asset?: (asset: {
49
+ $asset: string;
50
+ }) => string | null;
51
+ /**
52
+ * The record entities `{"$ref": …}` may name; without
53
+ * them every record is refused.
54
+ */
55
+ entities?: Iterable<string> | null;
56
+ };
57
+ export type SurfaceOptions = {
58
+ /**
59
+ * A whole surface, as the
60
+ * `show_surface` and `ask_user` tools take it. Leave it out to stream with `apply()` or `write()`.
61
+ */
62
+ document?: SurfaceDocument | Record<string, unknown> | null;
63
+ /**
64
+ * What each action needs before it replies; every
65
+ * action is allowed when null. Nothing in a surface can lower what it decides.
66
+ */
67
+ policy?: SurfacePolicy | null;
68
+ /**
69
+ * How records, links and assets are resolved.
70
+ */
71
+ resolve?: SurfaceResolve;
72
+ /**
73
+ * Who may compose a surface, by the key
74
+ * its `author` names; the byline shows the name, or the key when it is not listed.
75
+ */
76
+ authors?: Record<string, {
77
+ name: string;
78
+ }>;
79
+ /**
80
+ * Whether the surface answers the person's latest
81
+ * message; only then may `openSurface()` honour a request for a sheet or a dialog.
82
+ */
83
+ userInitiated?: boolean;
84
+ /**
85
+ * The element level of the surface's title; its `heading`
86
+ * nodes go one and two deeper.
87
+ */
88
+ headingLevel?: 2 | 3 | 4 | 5;
89
+ /**
90
+ * Locale for numbers and times.
91
+ */
92
+ locale?: string;
93
+ /**
94
+ * A catalog narrowed with `narrowCatalog()`; the full
95
+ * one by default. What lies outside it is refused as unknown.
96
+ */
97
+ catalog?: SurfaceCatalog;
98
+ /**
99
+ * The application's opaque string, at most 512 characters,
100
+ * copied unchanged into every reply. A surface cannot set it.
101
+ */
102
+ token?: string | null;
103
+ /**
104
+ * A reply the surface already gave, for a surface
105
+ * restored from a stored conversation: it starts as its receipt and replies no more.
106
+ */
107
+ reply?: SurfaceReply | null;
108
+ /**
109
+ * The id of an element that already shows the title,
110
+ * such as a Dialog's; the surface then draws no title of its own and is labelled by it.
111
+ */
112
+ labelledBy?: string | null;
113
+ /**
114
+ * The engine that draws `chart` nodes; without
115
+ * one a chart shows its data table.
116
+ */
117
+ chartAdapter?: ChartAdapter | null;
118
+ /**
119
+ * Localized messages.
120
+ */
121
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
122
+ /**
123
+ * Reply listener.
124
+ */
125
+ onreply?: (event: CustomEvent<{
126
+ reply: SurfaceReply;
127
+ }>) => void;
128
+ /**
129
+ * Error listener.
130
+ */
131
+ onerror?: (event: CustomEvent<{
132
+ errors: SurfaceError[];
133
+ }>) => void;
134
+ /**
135
+ * Input listener.
136
+ */
137
+ onchange?: (event: CustomEvent<{
138
+ name: string;
139
+ value: unknown;
140
+ }>) => void;
141
+ /**
142
+ * First-render listener.
143
+ */
144
+ onready?: (event: CustomEvent<Record<string, never>>) => void;
145
+ /**
146
+ * End-of-surface listener.
147
+ */
148
+ onend?: (event: CustomEvent<Record<string, never>>) => void;
149
+ };
150
+ export type SurfaceModel = {
151
+ began: boolean;
152
+ ended: boolean;
153
+ surface: string;
154
+ intent: SurfaceIntent | null;
155
+ title?: string;
156
+ author?: string;
157
+ placement?: SurfacePlacement;
158
+ description?: string;
159
+ root: string[];
160
+ nodes: Map<string, SurfaceNode>;
161
+ order: Map<string, number>;
162
+ data: Record<string, unknown>;
163
+ actions: SurfaceAction[] | null;
164
+ sources: SurfaceSource[] | null;
165
+ };
166
+ export type NodeView = {
167
+ el: HTMLElement;
168
+ owned: Component[];
169
+ kind: 'node' | 'placeholder' | 'fallback' | 'receipt';
170
+ /**
171
+ * Where a layout node's children go.
172
+ */
173
+ container?: HTMLElement | null;
174
+ fieldset?: Fieldset;
175
+ schema?: Record<string, any>;
176
+ table?: Table;
177
+ rowId?: string;
178
+ questionnaire?: Questionnaire;
179
+ choice?: HTMLFieldSetElement;
180
+ choiceError?: HTMLElement;
181
+ /**
182
+ * A table left out for the cell budget.
183
+ */
184
+ overBudget?: boolean;
185
+ };
186
+ export type DrawnAction = SurfaceAction & {
187
+ builtin?: boolean;
188
+ };
189
+ /**
190
+ * A surface an agent composed as JSON — a rich answer, or a dialog asking the person something —
191
+ * drawn with the library's own components from validated values only. It arrives whole as a
192
+ * `document`, or as operation lines through `apply()` and `write()`, drawing what it has as it
193
+ * arrives: a child that has not arrived is a skeleton line, and every action but Cancel waits for
194
+ * the surface's `end`.
195
+ *
196
+ * Every surface ends in exactly one `reply`: an action, Submit, Cancel, Escape, being superseded
197
+ * and being destroyed unanswered all reply, and a second answer is ignored. Answered, it freezes
198
+ * into a read-only receipt (`data-state="answered"`). Whether an action needs a confirmation is
199
+ * the application's `policy`, never the surface's. An input surface is a `<form>` labelled by its
200
+ * title; any other is a labelled region.
201
+ *
202
+ * @fires Surface#reply
203
+ * @fires Surface#error
204
+ * @fires Surface#change
205
+ * @fires Surface#ready
206
+ * @fires Surface#end
207
+ * @extends {Component<SurfaceOptions>}
208
+ */
209
+ export declare class Surface extends Component<SurfaceOptions> {
210
+ _original: import("../../core/dom.js").TargetSnapshot;
211
+ _token: string;
212
+ _catalog: import("./catalog.js").SurfaceCatalog;
213
+ _uid: string;
214
+ _entities: string[];
215
+ _state: import("./validate.js").ValidationState;
216
+ /** @type {SurfaceModel} */
217
+ _model: SurfaceModel;
218
+ /** @type {SurfaceError[]} */
219
+ _errors: SurfaceError[];
220
+ _reported: Set<any>;
221
+ /** @type {Map<string, NodeView>} */
222
+ _views: Map<string, NodeView>;
223
+ /** @type {Set<string>} */
224
+ _dirty: Set<string>;
225
+ /** @type {Map<string, Map<string, unknown>>} Bound properties resolved and checked, by node. */
226
+ _bound: Map<string, Map<string, unknown>>;
227
+ /** Table cells drawn so far in this pass. */
228
+ _cells: number;
229
+ /** @type {Record<string, unknown>} Raw input values by name, kept while an input is hidden. */
230
+ _raw: Record<string, unknown>;
231
+ /** @type {Record<string, string>} JSON of the last reported value of each input. */
232
+ _reportedValues: Record<string, string>;
233
+ /** @type {import('./text.js').SurfaceVisibility|null} */
234
+ _visibility: import('./text.js').SurfaceVisibility | null;
235
+ /** @type {SurfaceReply|null} */
236
+ _reply: SurfaceReply | null;
237
+ /** @type {DrawnAction[]} */
238
+ _actions: DrawnAction[];
239
+ /** @type {Map<string, {level: PolicyLevel, confirmText?: string, message?: string}>} */
240
+ _decisions: Map<string, {
241
+ level: PolicyLevel;
242
+ confirmText?: string;
243
+ message?: string;
244
+ }>;
245
+ /** @type {string[]} */
246
+ _removed: string[];
247
+ _actionsDirty: boolean;
248
+ _busy: boolean;
249
+ /** @type {Dialog|null} */
250
+ _confirm: Dialog | null;
251
+ _ready: boolean;
252
+ _destroyed: boolean;
253
+ /** @type {ReturnType<typeof lineSplitter>|null} */
254
+ _splitter: ReturnType<typeof lineSplitter> | null;
255
+ _documentMode: boolean;
256
+ /** @type {HTMLElement|null} */
257
+ _frame: HTMLElement | null;
258
+ _asking: boolean;
259
+ /** @type {HTMLElement|null} */
260
+ _body: HTMLElement | null;
261
+ /** @type {HTMLElement|null} */
262
+ _actionsEl: HTMLElement | null;
263
+ /** @type {HTMLElement|null} */
264
+ _verdict: HTMLElement | null;
265
+ _frozen: boolean;
266
+ _endEmitted: boolean;
267
+ /** @type {string|null} The surface id an operation or the document named, before any began. */
268
+ _named: string | null;
269
+ _waiting: HTMLDivElement;
270
+ static cssName: string;
271
+ /** @type {Readonly<SurfaceOptions>} */
272
+ static defaults: Readonly<SurfaceOptions>;
273
+ /** @returns {HTMLElement} */
274
+ render(): HTMLElement;
275
+ /**
276
+ * Applies one operation, as parsed from its line. It is validated against the catalog first:
277
+ * what is invalid is dropped and reported through `error`, and only the valid rest is drawn.
278
+ * Operations for another surface, and any after the surface was answered, are ignored.
279
+ * @param {unknown} op
280
+ * @returns {this}
281
+ * @fires Surface#error
282
+ */
283
+ apply(op: unknown): this;
284
+ /**
285
+ * Takes a chunk of operation lines, as streamed: every complete line is parsed and applied.
286
+ * @param {string} chunk
287
+ * @returns {this}
288
+ * @fires Surface#error
289
+ */
290
+ write(chunk: string): this;
291
+ /**
292
+ * Ends the stream: applies a last line without a line break. A surface whose `end` never
293
+ * arrived is reported and keeps its actions disabled; Cancel still replies.
294
+ * @returns {this}
295
+ * @fires Surface#error
296
+ */
297
+ end(): this;
298
+ /**
299
+ * The values of the visible inputs by name, as a reply would carry them: JSON, hidden inputs
300
+ * left out. A questionnaire's are `{answers, path}`.
301
+ * @returns {Record<string, unknown>}
302
+ */
303
+ getValues(): Record<string, unknown>;
304
+ /**
305
+ * Every problem collected so far, in a shape an application can return to the model.
306
+ * @returns {SurfaceError[]}
307
+ */
308
+ getErrors(): SurfaceError[];
309
+ /**
310
+ * Closes the surface unanswered: replies `cancel` (`dismiss` for a `show` surface).
311
+ * @param {ReplyReason} [reason='cancelled'] Why, carried in the reply's `reason`.
312
+ * @returns {this}
313
+ * @fires Surface#reply
314
+ */
315
+ cancel(reason?: ReplyReason): this;
316
+ /**
317
+ * Ends the surface because a newer one takes its place: replies `dismiss` with the reason
318
+ * `superseded`.
319
+ * @returns {this}
320
+ * @fires Surface#reply
321
+ */
322
+ supersede(): this;
323
+ /**
324
+ * Moves focus to the first control: the first input, else the first enabled action.
325
+ * @returns {this}
326
+ */
327
+ focus(): this;
328
+ /**
329
+ * The surface as it stands, as a document: what was validated, repairs applied and invalid
330
+ * parts dropped. `null` before it began.
331
+ * @returns {SurfaceDocument|null}
332
+ */
333
+ toDocument(): SurfaceDocument | null;
334
+ /**
335
+ * The reply the surface gave, or `null` while it waits.
336
+ * @returns {SurfaceReply|null}
337
+ */
338
+ getReply(): SurfaceReply | null;
339
+ /**
340
+ * Destroys the surface. An unanswered surface replies `dismiss` first, with the reason
341
+ * `destroyed`, so a waiting agent never hangs.
342
+ * @returns {void}
343
+ * @fires Surface#reply
344
+ */
345
+ destroy(): void;
346
+ /** @private @returns {ReturnType<typeof lineSplitter>} */
347
+ private _lines;
348
+ /**
349
+ * Draws a whole document.
350
+ * @private
351
+ * @param {unknown} document
352
+ * @returns {void}
353
+ */
354
+ private _load;
355
+ /**
356
+ * Records one validated operation in the model.
357
+ * @private
358
+ * @param {SurfaceOp} op
359
+ * @returns {void}
360
+ */
361
+ private _applyValid;
362
+ /**
363
+ * Builds the frame once the intent is known: a `<form>` for a surface that asks, a region for
364
+ * any other, labelled by the title.
365
+ * @private
366
+ * @returns {void}
367
+ */
368
+ private _buildFrame;
369
+ /**
370
+ * Draws what changed: the node tree from `root`, the visibility of every node and field, and
371
+ * the actions, or the receipt once the surface is answered.
372
+ * @private
373
+ * @returns {void}
374
+ */
375
+ private _draw;
376
+ /**
377
+ * @private
378
+ * @returns {void}
379
+ */
380
+ private _paint;
381
+ /**
382
+ * What goes wrong while drawing costs the part that failed and is reported; never the rest of
383
+ * the surface, and never its reply.
384
+ * @private
385
+ * @param {unknown} error @param {string} [id] The node that failed.
386
+ * @returns {void}
387
+ */
388
+ private _drawFailed;
389
+ /**
390
+ * The element for a node id: its view, built or rebuilt when it changed, with a layout node's
391
+ * children synced inside it.
392
+ * @private
393
+ * @param {string} id @param {Set<string>} used @param {number} depth
394
+ * @returns {HTMLElement}
395
+ */
396
+ private _viewOf;
397
+ /**
398
+ * Counts a table against the cell budget as it is drawn, so the budget also holds for a stream
399
+ * that never ends.
400
+ * @private
401
+ * @param {string} id
402
+ * @returns {boolean} Whether it is left out.
403
+ */
404
+ private _overBudget;
405
+ /**
406
+ * @private
407
+ * @param {string} id
408
+ * @returns {NodeView}
409
+ */
410
+ private _safeBuild;
411
+ /**
412
+ * Builds one node's view: the component it maps to, a skeleton while what it needs has not
413
+ * arrived, a quiet fallback for what cannot be shown, or, once answered, the receipt.
414
+ * @private
415
+ * @param {string} id
416
+ * @returns {NodeView}
417
+ */
418
+ private _build;
419
+ /**
420
+ * The catalog's own entry for a type: a node of any other type, whatever it is called, has none.
421
+ * @private
422
+ * @param {string} type
423
+ * @returns {import('./catalog.js').CatalogNode|undefined}
424
+ */
425
+ private _entry;
426
+ /**
427
+ * A property's value, a `$data` binding resolved and checked as if it had been written in.
428
+ * @private
429
+ * @param {SurfaceNode} node @param {string} name
430
+ * @returns {any}
431
+ */
432
+ private _prop;
433
+ /** @private @returns {NodeView} */
434
+ private _placeholder;
435
+ /** @private @returns {NodeView} */
436
+ private _fallback;
437
+ /**
438
+ * @private
439
+ * @param {NodeView} view @param {Record<string, any>} props
440
+ * @returns {NodeView}
441
+ */
442
+ private _table;
443
+ /**
444
+ * Table columns: formats mapped, record cells drawn through `resolve.ref`.
445
+ * @private
446
+ * @param {Array<Record<string, any>>} columns @param {Record<string, unknown>[]} rows @param {NodeView} view
447
+ * @returns {Array<Record<string, unknown>>}
448
+ */
449
+ private _columns;
450
+ /**
451
+ * A record drawn as an EntityRef through `resolve.ref`, or its id as text.
452
+ * @private
453
+ * @param {{$ref: string, id: string}} ref @param {NodeView} view
454
+ * @returns {Node}
455
+ */
456
+ private _ref;
457
+ /**
458
+ * A link: the text, opening in a new tab when `resolve.link` keeps it, and the host beside it.
459
+ * @private
460
+ * @param {string} text @param {string} href
461
+ * @returns {Node[]}
462
+ */
463
+ private _link;
464
+ /**
465
+ * A chart; its data table is shown when there is no engine, and offered behind a toggle when
466
+ * there is.
467
+ * @private
468
+ * @param {NodeView} view @param {Record<string, any>} props
469
+ * @returns {NodeView}
470
+ */
471
+ private _chart;
472
+ /**
473
+ * A schema drawn as a Fieldset; what was typed survives a redraw.
474
+ * @private
475
+ * @param {NodeView} view @param {Record<string, any>} props
476
+ * @returns {NodeView}
477
+ */
478
+ private _fields;
479
+ /**
480
+ * Options to pick from, as a native group of radios or checkboxes.
481
+ * @private
482
+ * @param {NodeView} view @param {SurfaceNode} node @param {Record<string, any>} props
483
+ * @returns {NodeView}
484
+ */
485
+ private _choice;
486
+ /**
487
+ * Proposed changes as a table whose selected rows are the accepted ones.
488
+ * @private
489
+ * @param {NodeView} view @param {Record<string, any>} props
490
+ * @returns {NodeView}
491
+ */
492
+ private _diff;
493
+ /**
494
+ * @private
495
+ * @param {Array<Record<string, any>>} rows @param {NodeView} view
496
+ * @returns {Array<Record<string, unknown>>}
497
+ */
498
+ private _diffColumns;
499
+ /**
500
+ * Steps asked one at a time; the Questionnaire's own submit answers the surface.
501
+ * @private
502
+ * @param {NodeView} view @param {Record<string, any>} props
503
+ * @returns {NodeView}
504
+ */
505
+ private _questionnaire;
506
+ /**
507
+ * An input as the read-only record of what was answered.
508
+ * @private
509
+ * @param {SurfaceNode} node @param {Record<string, any>} props
510
+ * @returns {NodeView}
511
+ */
512
+ private _receipt;
513
+ /** @private @param {SurfaceReply} reply @param {string} id @param {string} name @returns {boolean} */
514
+ private _hiddenAt;
515
+ /** @private @param {unknown} value @param {Map<unknown, string>} choices @returns {string} */
516
+ private _display;
517
+ /**
518
+ * Reads every input's raw value — what its control holds, hidden inputs included.
519
+ * @private
520
+ * @returns {Record<string, unknown>}
521
+ */
522
+ private _collectRaw;
523
+ /**
524
+ * The inputs' values as JSON, empty ones left out; hidden ones included.
525
+ * @private
526
+ * @returns {Record<string, unknown>}
527
+ */
528
+ private _jsonValues;
529
+ /** @private @returns {any} The model as `surfaceVisibility()` and `createReply()` read it. */
530
+ private _docLike;
531
+ /** @private @param {Record<string, unknown>} values @returns {import('./text.js').SurfaceVisibility} */
532
+ private _visibilityFor;
533
+ /**
534
+ * Something was typed, picked or selected: reports each input whose value changed, and shows
535
+ * and hides what depends on it.
536
+ * @private
537
+ * @returns {void}
538
+ */
539
+ private _inputChanged;
540
+ /**
541
+ * Shows and hides nodes and fields for the current values. A node that hides while it holds
542
+ * the focus hands it to the input whose value hid it.
543
+ * @private
544
+ * @param {string[]} [changed=[]] The inputs that just changed.
545
+ * @returns {void}
546
+ */
547
+ private _syncVisibility;
548
+ /**
549
+ * @private
550
+ * @param {string} name
551
+ * @returns {boolean} Whether an input took the focus.
552
+ */
553
+ private _focusInput;
554
+ /** @private @param {NodeView} view @returns {void} */
555
+ private _refocus;
556
+ /**
557
+ * Checks the visible inputs before an action replies: each schema, and a pick for each choice.
558
+ * Marks what failed and returns the values to send.
559
+ * @private
560
+ * @returns {{values: Record<string, unknown>, invalid: string|null}}
561
+ */
562
+ private _check;
563
+ /** @private @param {NodeView} view @param {string} text @returns {void} */
564
+ private _choiceError;
565
+ /** @private @param {string} name @returns {void} */
566
+ private _clearError;
567
+ /** @private @returns {NodeView|null} */
568
+ private _questionnaireView;
569
+ /**
570
+ * The actions this surface draws: its own, or the intent's defaults, then Cancel where the
571
+ * intent has one. Each is put to the policy; a denied one is not drawn.
572
+ * @private
573
+ * @returns {void}
574
+ */
575
+ private _drawActions;
576
+ /** @private @returns {DrawnAction[]} */
577
+ private _actionList;
578
+ /** @private @returns {DrawnAction} */
579
+ private _cancelAction;
580
+ /**
581
+ * Runs an action: checks the inputs, asks the confirmation the policy wants, and replies.
582
+ * @private
583
+ * @param {string} id
584
+ * @returns {Promise<void>}
585
+ */
586
+ private _run;
587
+ /**
588
+ * @private
589
+ * @param {SurfaceAction} action
590
+ * @returns {Promise<void>}
591
+ */
592
+ private _answer;
593
+ /**
594
+ * Replies with a closing action, unless the surface already replied.
595
+ * @private
596
+ * @param {'cancel'|'dismiss'} action @param {ReplyReason} reason
597
+ * @returns {void}
598
+ */
599
+ private _close;
600
+ /**
601
+ * The closing reply when no fuller one can be built: nothing valid began, say. It is owed all
602
+ * the same.
603
+ * @private
604
+ * @param {'cancel'|'dismiss'} action @param {ReplyReason} reason
605
+ * @returns {SurfaceReply}
606
+ */
607
+ private _bareReply;
608
+ /**
609
+ * Whether an action answers: checks the inputs and sends their values. The intent's answering
610
+ * defaults do, and so does an action of the surface's own with `kind: 'primary'`; any other
611
+ * replies with no values.
612
+ * @private
613
+ * @param {SurfaceAction} action
614
+ * @returns {boolean}
615
+ */
616
+ private _answers;
617
+ /**
618
+ * Records the one reply, freezes the surface into its receipt, and reports it.
619
+ * @private
620
+ * @param {SurfaceReply} reply
621
+ * @returns {void}
622
+ */
623
+ private _finish;
624
+ /**
625
+ * Turns the surface into the record of its answer: inputs redrawn as what was answered, and the
626
+ * actions replaced by the verdict.
627
+ * @private
628
+ * @returns {void}
629
+ */
630
+ private _freeze;
631
+ /** @private @param {KeyboardEvent} event @returns {void} */
632
+ private _onKeydown;
633
+ /**
634
+ * @private
635
+ * @returns {boolean} Whether someone is expected to answer: every intent that asks, and a `show`
636
+ * surface with actions of its own. One without any has nothing to close.
637
+ */
638
+ private _waits;
639
+ /**
640
+ * @private
641
+ * @param {KeyboardEvent} event
642
+ * @returns {boolean} Whether a nested control owns the Escape.
643
+ */
644
+ private _escapeIsNested;
645
+ /**
646
+ * Adds problems to the list and reports the new ones.
647
+ * @private
648
+ * @param {SurfaceError[]} errors
649
+ * @returns {void}
650
+ */
651
+ private _report;
652
+ /** @private @returns {string} */
653
+ private _authorName;
654
+ }
655
+ export type OpenSurfaceOptions = SurfaceOptions & {
656
+ placement?: SurfacePlacement;
657
+ target?: Element | string | null;
658
+ side?: 'start' | 'end' | 'top' | 'bottom';
659
+ onopen?: (surface: Surface) => void;
660
+ signal?: AbortSignal | null;
661
+ };
662
+ /**
663
+ * The one reply, exactly once.
664
+ * @event Surface#reply
665
+ * @type {CustomEvent<{reply: SurfaceReply}>}
666
+ */
667
+ /**
668
+ * New problems, each time some are found.
669
+ * @event Surface#error
670
+ * @type {CustomEvent<{errors: SurfaceError[]}>}
671
+ */
672
+ /**
673
+ * An input's value changed; `value` is JSON, `null` when it was emptied.
674
+ * @event Surface#change
675
+ * @type {CustomEvent<{name: string, value: unknown}>}
676
+ */
677
+ /**
678
+ * The surface has begun and shows its first state.
679
+ * @event Surface#ready
680
+ * @type {CustomEvent<Record<string, never>>}
681
+ */
682
+ /**
683
+ * The surface's `end` arrived: it is complete, and its actions are enabled.
684
+ * @event Surface#end
685
+ * @type {CustomEvent<Record<string, never>>}
686
+ */
687
+ /**
688
+ * Options of `openSurface()`: the Surface's own, and where it goes.
689
+ * @typedef {SurfaceOptions & {
690
+ * placement?: SurfacePlacement,
691
+ * target?: Element|string|null,
692
+ * side?: 'start'|'end'|'top'|'bottom',
693
+ * onopen?: (surface: Surface) => void,
694
+ * signal?: AbortSignal|null
695
+ * }} OpenSurfaceOptions
696
+ */
697
+ /**
698
+ * Shows a surface and waits for its reply. The placement the document asks for is a request:
699
+ * a sheet or a dialog only when `userInitiated` (the surface answers the person's latest
700
+ * message), inline into `target` otherwise. An application that passes `placement` itself
701
+ * decides. Closing the sheet or dialog replies `cancel` (`dismiss` for a `show` surface). The
702
+ * first control takes the focus. A document that cannot begin at all — not an object, the wrong
703
+ * version, no usable surface id — rejects with a `TypeError` carrying `errors` before anything
704
+ * opens; a surface given its `reply` resolves with it at once.
705
+ *
706
+ * `signal` withdraws the question: when it aborts, the surface is cancelled with the reason
707
+ * `stopped` (`cancel`, or `dismiss` for a `show` surface) and the promise resolves with that reply;
708
+ * a sheet or dialog closes and is destroyed, an inline surface stays as its receipt. A signal
709
+ * already aborted resolves the same reply without drawing anything. An inline surface whose
710
+ * `target` the application removes is not noticed: abort the signal, or destroy the surface (it
711
+ * replies `dismiss`), so the promise settles.
712
+ * @throws {TypeError} Rejects for a document that cannot begin, or an inline surface without a
713
+ * `target`.
714
+ * @param {SurfaceDocument|Record<string, unknown>} document The whole surface.
715
+ * @param {OpenSurfaceOptions} [options]
716
+ * @returns {Promise<SurfaceReply>}
717
+ */
718
+ export declare function openSurface(document: SurfaceDocument | Record<string, unknown>, options?: OpenSurfaceOptions): Promise<SurfaceReply>;