@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.
- package/CHANGELOG.md +188 -0
- package/README.md +73 -7
- package/bin/zx-css.js +328 -0
- package/dist/types/components/account-menu/account-menu.d.ts +4 -2
- package/dist/types/components/activity-list/activity-list.d.ts +14 -8
- package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
- package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
- package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
- package/dist/types/components/calendar/calendar-model.d.ts +9 -2
- package/dist/types/components/calendar/calendar.d.ts +12 -4
- package/dist/types/components/chart/chart.d.ts +25 -13
- package/dist/types/components/checklist/checklist.d.ts +29 -0
- package/dist/types/components/code-editor/code-editor.d.ts +7 -2
- package/dist/types/components/composer/composer.d.ts +206 -4
- package/dist/types/components/composer/queue.d.ts +76 -0
- package/dist/types/components/copy/copy-button.d.ts +6 -4
- package/dist/types/components/copy/copy-input.d.ts +10 -6
- package/dist/types/components/datebox/date-range-box.d.ts +33 -0
- package/dist/types/components/datebox/placeholder.d.ts +7 -0
- package/dist/types/components/dialog/dialog.d.ts +2 -2
- package/dist/types/components/dock/dock.d.ts +12 -3
- package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
- package/dist/types/components/field-upload/field-upload.d.ts +3 -2
- package/dist/types/components/file-item/file-item.d.ts +3 -2
- package/dist/types/components/file-list/file-list.d.ts +14 -8
- package/dist/types/components/filter/filter-model.d.ts +31 -1
- package/dist/types/components/filter/filter.d.ts +20 -2
- package/dist/types/components/finder/finder.d.ts +14 -6
- package/dist/types/components/flag/flag.d.ts +99 -0
- package/dist/types/components/grid/grid.d.ts +1 -1
- package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
- package/dist/types/components/launcher/launcher.d.ts +2 -0
- package/dist/types/components/modal/modal.d.ts +34 -8
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
- package/dist/types/components/number-field/number-field.d.ts +41 -7
- package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
- package/dist/types/components/prose/prose.d.ts +9 -6
- package/dist/types/components/questionnaire/conditions.d.ts +270 -0
- package/dist/types/components/questionnaire/items.d.ts +52 -30
- package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
- package/dist/types/components/rating/rating.d.ts +5 -3
- package/dist/types/components/select/country.d.ts +106 -0
- package/dist/types/components/select/field-adapter.d.ts +2 -1
- package/dist/types/components/select/locale.d.ts +102 -0
- package/dist/types/components/select/select.d.ts +41 -2
- package/dist/types/components/sheet/sheet.d.ts +2 -2
- package/dist/types/components/slider/slider.d.ts +1 -0
- package/dist/types/components/sort-control/sort-control.d.ts +7 -3
- package/dist/types/components/source-list/source-list.d.ts +7 -5
- package/dist/types/components/split-view/split-view.d.ts +5 -3
- package/dist/types/components/surface/catalog.d.ts +260 -0
- package/dist/types/components/surface/elicit.d.ts +81 -0
- package/dist/types/components/surface/mcp.d.ts +165 -0
- package/dist/types/components/surface/schema.d.ts +314 -0
- package/dist/types/components/surface/stream.d.ts +118 -0
- package/dist/types/components/surface/surface.d.ts +718 -0
- package/dist/types/components/surface/text.d.ts +277 -0
- package/dist/types/components/surface/validate.d.ts +339 -0
- package/dist/types/components/table/table.d.ts +55 -3
- package/dist/types/components/table/window.d.ts +203 -0
- package/dist/types/components/toolbar/toolbar.d.ts +10 -6
- package/dist/types/components/tooltip/tooltip.d.ts +2 -2
- package/dist/types/components/tree/tree.d.ts +20 -13
- package/dist/types/core/component.d.ts +10 -0
- package/dist/types/core/date.d.ts +8 -1
- package/dist/types/core/dom.d.ts +15 -0
- package/dist/types/core/http.d.ts +10 -0
- package/dist/types/core/i18n.d.ts +38 -0
- package/dist/types/core/messages.d.ts +344 -1
- package/dist/types/core/storage.d.ts +7 -2
- package/dist/types/elements/define.d.ts +21 -46
- package/dist/types/elements/definitions.d.ts +147 -0
- package/dist/types/elements/kit.d.ts +7 -0
- package/dist/types/elements/reflect.d.ts +6 -3
- package/dist/types/index.d.ts +10 -1
- package/dist/types/internal/date-locale.d.ts +7 -0
- package/dist/types/internal/json-patch.d.ts +146 -0
- package/dist/types/locales/de.d.ts +13 -0
- package/dist/types/locales/en.d.ts +2 -0
- package/dist/types/locales/index.d.ts +823 -0
- package/dist/types/zeyos/view.d.ts +8 -1
- package/dist/zx-zeyos.esm.js +16852 -15131
- package/dist/zx-zeyos.esm.min.js +5 -5
- package/dist/zx.core.css +1276 -0
- package/dist/zx.core.min.css +1 -0
- package/dist/zx.css +520 -143
- package/dist/zx.esm.js +40940 -29684
- package/dist/zx.esm.min.js +36 -23
- package/dist/zx.global.js +40940 -29684
- package/dist/zx.global.min.js +36 -23
- package/dist/zx.layered.css +17315 -0
- package/dist/zx.layered.min.css +1 -0
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +12501 -0
- package/docs/agent-surfaces.md +340 -0
- package/docs/api.json +909 -137
- package/docs/llms.md +1046 -80
- package/docs/llms.txt +30 -9
- package/package.json +29 -6
- package/src/components/account-menu/account-menu.js +6 -3
- package/src/components/activity-item/activity-item.js +2 -1
- package/src/components/activity-list/activity-list.js +16 -10
- package/src/components/agent-thread/ag-ui.js +1439 -0
- package/src/components/agent-thread/agent-thread.js +359 -54
- package/src/components/agent-thread/ui-message-stream.js +1281 -0
- package/src/components/app-sidebar/app-sidebar.js +18 -8
- package/src/components/approval-card/approval-card.js +3 -2
- package/src/components/block-view/block-view.js +7 -6
- package/src/components/breadcrumb/breadcrumb.js +8 -5
- package/src/components/button/button.css +24 -11
- package/src/components/calendar/calendar-model.js +8 -2
- package/src/components/calendar/calendar.js +53 -18
- package/src/components/chart/chart.js +54 -23
- package/src/components/checklist/checklist.css +9 -1
- package/src/components/checklist/checklist.js +59 -3
- package/src/components/checklist/field-adapter.js +2 -11
- package/src/components/code-editor/code-editor.js +45 -8
- package/src/components/code-editor/field-adapter.js +1 -1
- package/src/components/composer/composer.css +80 -1
- package/src/components/composer/composer.js +390 -16
- package/src/components/composer/queue.js +78 -0
- package/src/components/context-menu/context-menu.js +12 -1
- package/src/components/copy/copy-button.js +9 -7
- package/src/components/copy/copy-input.js +10 -6
- package/src/components/date-picker/date-picker.js +2 -1
- package/src/components/date-picker/date-range-picker.js +8 -7
- package/src/components/datebox/date-range-box.js +3 -9
- package/src/components/datebox/datebox.js +18 -21
- package/src/components/datebox/placeholder.js +18 -0
- package/src/components/dialog/dialog.js +4 -5
- package/src/components/dock/dock.js +34 -13
- package/src/components/entity-ref/entity-ref.js +16 -5
- package/src/components/field-upload/field-upload.js +81 -38
- package/src/components/file-item/file-item.js +70 -40
- package/src/components/file-list/file-list.js +15 -9
- package/src/components/filter/filter-model.js +46 -8
- package/src/components/filter/filter.css +3 -3
- package/src/components/filter/filter.js +29 -10
- package/src/components/filter-panel/filter-panel.js +13 -5
- package/src/components/finder/finder.js +50 -26
- package/src/components/flag/flag.css +40 -0
- package/src/components/flag/flag.js +177 -0
- package/src/components/form/form.js +1 -1
- package/src/components/grid/grid.js +22 -8
- package/src/components/kanban-view/kanban-view.js +51 -81
- package/src/components/launcher/launcher.js +17 -2
- package/src/components/list-toolbar/list-toolbar.js +2 -1
- package/src/components/master-panel/master-panel.js +1 -1
- package/src/components/menu-button/menu-button.js +4 -0
- package/src/components/message/message.js +3 -0
- package/src/components/modal/modal.js +62 -8
- package/src/components/multi-value-editor/multi-value-editor.js +10 -9
- package/src/components/navigation-bar/navigation-bar.js +3 -3
- package/src/components/number-field/number-field.js +98 -29
- package/src/components/prompt-starters/prompt-starters.css +91 -0
- package/src/components/prompt-starters/prompt-starters.js +206 -0
- package/src/components/prose/prose.js +14 -10
- package/src/components/questionnaire/conditions.js +666 -0
- package/src/components/questionnaire/items.js +150 -41
- package/src/components/questionnaire/questionnaire.js +126 -32
- package/src/components/rating/rating.js +5 -4
- package/src/components/run-status/run-status.js +2 -2
- package/src/components/select/country.js +136 -0
- package/src/components/select/field-adapter.js +7 -2
- package/src/components/select/locale.js +219 -0
- package/src/components/select/select.css +20 -22
- package/src/components/select/select.js +94 -12
- package/src/components/sheet/sheet-stack.js +10 -1
- package/src/components/sheet/sheet.js +12 -5
- package/src/components/slider/slider.js +7 -2
- package/src/components/sort-control/sort-control.js +15 -5
- package/src/components/source-list/source-list.js +7 -4
- package/src/components/split-view/split-view.js +5 -3
- package/src/components/surface/catalog.js +1334 -0
- package/src/components/surface/elicit.js +107 -0
- package/src/components/surface/mcp.js +243 -0
- package/src/components/surface/schema.js +644 -0
- package/src/components/surface/stream.js +245 -0
- package/src/components/surface/surface.css +308 -0
- package/src/components/surface/surface.js +2291 -0
- package/src/components/surface/text.js +513 -0
- package/src/components/surface/validate.js +2218 -0
- package/src/components/tabbox/tabbox.js +9 -0
- package/src/components/table/table.css +63 -3
- package/src/components/table/table.js +167 -28
- package/src/components/table/window.js +317 -0
- package/src/components/toolbar/toolbar.js +12 -7
- package/src/components/tooltip/tooltip.css +2 -3
- package/src/components/tooltip/tooltip.js +32 -5
- package/src/components/tree/tree.js +53 -23
- package/src/core/component.js +25 -1
- package/src/core/date.js +62 -16
- package/src/core/dom.js +67 -4
- package/src/core/format.js +15 -13
- package/src/core/http.js +29 -20
- package/src/core/i18n.js +83 -10
- package/src/core/icons.js +13 -2
- package/src/core/keyboard.js +79 -8
- package/src/core/messages.js +376 -2
- package/src/core/overlay-host.js +1 -0
- package/src/core/position.js +3 -2
- package/src/core/storage.js +59 -6
- package/src/elements/define.js +178 -130
- package/src/elements/definitions.js +229 -0
- package/src/elements/kit.js +444 -0
- package/src/elements/reflect.js +8 -3
- package/src/index.js +10 -1
- package/src/internal/date-locale.js +11 -0
- package/src/internal/json-patch.js +405 -0
- package/src/locales/de.js +911 -0
- package/src/locales/en.js +2 -0
- package/src/locales/index.js +7 -0
- package/src/zeyos/calendar.js +2 -1
- package/src/zeyos/form.js +2 -1
- package/src/zeyos/launcher.js +7 -6
- package/src/zeyos/module-bar.js +2 -1
- package/src/zeyos/schema.js +37 -23
- package/src/zeyos/select.js +4 -3
- package/src/zeyos/table.js +2 -13
- package/src/zeyos/view.js +57 -17
- package/styles/core.css +11 -0
- package/styles/tokens/semantic.css +1 -0
- package/styles/zeyos.css +2 -0
- package/styles/zx.css +4 -8
- 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;
|