@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
|
@@ -24,6 +24,14 @@ export type NumberFieldOptions = {
|
|
|
24
24
|
* Decimal places; derived from `step` when null.
|
|
25
25
|
*/
|
|
26
26
|
precision?: number | null;
|
|
27
|
+
/**
|
|
28
|
+
* Whether a typed or assigned value is moved onto the `step` grid.
|
|
29
|
+
* With `false` the value is kept exactly as entered — `step` is then only the increment of the
|
|
30
|
+
* buttons and arrow keys, and decimals are rounded only to an explicit `precision`. `min` and
|
|
31
|
+
* `max` still apply. Use it for values that are not multiples of anything: an identifier, a
|
|
32
|
+
* seed, a measurement.
|
|
33
|
+
*/
|
|
34
|
+
snap?: boolean;
|
|
27
35
|
/**
|
|
28
36
|
* Whether stepping past a bound wraps to the other one.
|
|
29
37
|
*/
|
|
@@ -61,7 +69,7 @@ export type NumberFieldOptions = {
|
|
|
61
69
|
*/
|
|
62
70
|
group?: boolean;
|
|
63
71
|
/**
|
|
64
|
-
* Locale for formatting; defaults to the
|
|
72
|
+
* Locale for formatting; defaults to the active language.
|
|
65
73
|
*/
|
|
66
74
|
locale?: string | null;
|
|
67
75
|
/**
|
|
@@ -89,6 +97,11 @@ export type NumberFieldOptions = {
|
|
|
89
97
|
* @property {number} [step=1] Increment applied by the buttons and arrow keys.
|
|
90
98
|
* @property {number} [largeStep=10] Multiple of `step` applied by PageUp/PageDown.
|
|
91
99
|
* @property {number|null} [precision=null] Decimal places; derived from `step` when null.
|
|
100
|
+
* @property {boolean} [snap=true] Whether a typed or assigned value is moved onto the `step` grid.
|
|
101
|
+
* With `false` the value is kept exactly as entered — `step` is then only the increment of the
|
|
102
|
+
* buttons and arrow keys, and decimals are rounded only to an explicit `precision`. `min` and
|
|
103
|
+
* `max` still apply. Use it for values that are not multiples of anything: an identifier, a
|
|
104
|
+
* seed, a measurement.
|
|
92
105
|
* @property {boolean} [wrap=false] Whether stepping past a bound wraps to the other one.
|
|
93
106
|
* @property {string} [placeholder=''] Empty-state text.
|
|
94
107
|
* @property {string|null} [label=null] Accessible name for the spinbutton.
|
|
@@ -98,7 +111,7 @@ export type NumberFieldOptions = {
|
|
|
98
111
|
* @property {boolean} [required=false] Whether an empty value is invalid.
|
|
99
112
|
* @property {string|null} [name=null] Native form field name.
|
|
100
113
|
* @property {boolean} [group=false] Whether to render thousands separators while idle.
|
|
101
|
-
* @property {string|null} [locale=null] Locale for formatting; defaults to the
|
|
114
|
+
* @property {string|null} [locale=null] Locale for formatting; defaults to the active language.
|
|
102
115
|
* @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
|
|
103
116
|
* @property {(event: CustomEvent<{value: number|null}>) => void} [onchange] Committed-value listener.
|
|
104
117
|
* @property {(event: CustomEvent<{value: number|null}>) => void} [oninput] Per-keystroke listener.
|
|
@@ -122,13 +135,21 @@ export declare class NumberField extends Component<NumberFieldOptions> {
|
|
|
122
135
|
_createdRoot: boolean;
|
|
123
136
|
_snapshot: import("../../core/dom.js").TargetSnapshot;
|
|
124
137
|
_step: number;
|
|
138
|
+
_snap: boolean;
|
|
125
139
|
_precision: number;
|
|
140
|
+
_fixedPrecision: boolean;
|
|
126
141
|
_min: number;
|
|
127
142
|
_max: number;
|
|
143
|
+
_separatorLocale: string;
|
|
128
144
|
_localeSeparators: {
|
|
129
145
|
group: string;
|
|
130
146
|
decimal: string;
|
|
147
|
+
minus: string;
|
|
148
|
+
digits: {
|
|
149
|
+
[k: string]: string;
|
|
150
|
+
};
|
|
131
151
|
};
|
|
152
|
+
_inputLocale: string | string[];
|
|
132
153
|
static cssName: string;
|
|
133
154
|
/** @type {NumberFieldOptions} */
|
|
134
155
|
static defaults: NumberFieldOptions;
|
|
@@ -144,7 +165,8 @@ export declare class NumberField extends Component<NumberFieldOptions> {
|
|
|
144
165
|
*/
|
|
145
166
|
get(): number | null;
|
|
146
167
|
/**
|
|
147
|
-
* Sets the value,
|
|
168
|
+
* Sets the value, clamping it into `[min, max]` and — unless `snap` is off — moving it onto the
|
|
169
|
+
* `step` grid.
|
|
148
170
|
* @param {number|string|null} next Next value; empty strings and null clear the field.
|
|
149
171
|
* @param {{silent?: boolean}} [options={}] Set `silent` to suppress `change`.
|
|
150
172
|
* @returns {this}
|
|
@@ -215,12 +237,15 @@ export declare class NumberField extends Component<NumberFieldOptions> {
|
|
|
215
237
|
*/
|
|
216
238
|
_stepBy(count: number): this;
|
|
217
239
|
/**
|
|
218
|
-
* The grouping and decimal separators of the
|
|
219
|
-
* @
|
|
240
|
+
* The grouping and decimal separators of the effective formatting locale.
|
|
241
|
+
* @param {string|string[]} [locale] Locale of the text being parsed.
|
|
242
|
+
* @returns {{group: string, decimal: string, minus: string, digits: Record<string, string>}}
|
|
220
243
|
*/
|
|
221
|
-
_separators(): {
|
|
244
|
+
_separators(locale?: string | string[]): {
|
|
222
245
|
group: string;
|
|
223
246
|
decimal: string;
|
|
247
|
+
minus: string;
|
|
248
|
+
digits: Record<string, string>;
|
|
224
249
|
};
|
|
225
250
|
/** @returns {void} */
|
|
226
251
|
_onInput(): void;
|
|
@@ -241,6 +266,13 @@ export declare class NumberField extends Component<NumberFieldOptions> {
|
|
|
241
266
|
* @returns {string}
|
|
242
267
|
*/
|
|
243
268
|
_format(value: number, editing: boolean): string;
|
|
269
|
+
/**
|
|
270
|
+
* Decimal places a value is held and shown at: the field's precision, widened to the value's
|
|
271
|
+
* own decimals when nothing fixed the precision (`snap: false` without `precision`).
|
|
272
|
+
* @param {number} value Value in question.
|
|
273
|
+
* @returns {number}
|
|
274
|
+
*/
|
|
275
|
+
_decimalsFor(value: number): number;
|
|
244
276
|
/**
|
|
245
277
|
* @param {string} key Message key.
|
|
246
278
|
* @param {string} fallback Text used when the host has no translation.
|
|
@@ -271,12 +303,14 @@ export declare class NumberField extends Component<NumberFieldOptions> {
|
|
|
271
303
|
* which is the best available guess for free-form typing.
|
|
272
304
|
*
|
|
273
305
|
* @param {unknown} raw Value to parse.
|
|
274
|
-
* @param {{group: string, decimal: string}|null} [separators=null] Known locale separators.
|
|
306
|
+
* @param {{group: string, decimal: string, minus?: string, digits?: Record<string, string>}|null} [separators=null] Known locale separators, minus sign, and digit mappings.
|
|
275
307
|
* @returns {number|null} The number, or null when the input is empty or unparseable.
|
|
276
308
|
*/
|
|
277
309
|
export declare function parseNumber(raw: unknown, separators?: {
|
|
278
310
|
group: string;
|
|
279
311
|
decimal: string;
|
|
312
|
+
minus?: string;
|
|
313
|
+
digits?: Record<string, string>;
|
|
280
314
|
} | null): number | null;
|
|
281
315
|
/**
|
|
282
316
|
* Snaps a number onto the step grid and clamps it into the accepted range.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { Component } from '../../core/component.js';
|
|
2
|
+
export type PromptStarter = {
|
|
3
|
+
/**
|
|
4
|
+
* Stable identifier.
|
|
5
|
+
*/
|
|
6
|
+
id: string | number;
|
|
7
|
+
/**
|
|
8
|
+
* What the starter is called: its visible title and accessible name.
|
|
9
|
+
*/
|
|
10
|
+
title: string;
|
|
11
|
+
/**
|
|
12
|
+
* The prompt it stands for, handed back in `pick`. Shown beneath the title
|
|
13
|
+
* when there is no `description`.
|
|
14
|
+
*/
|
|
15
|
+
text: string;
|
|
16
|
+
/**
|
|
17
|
+
* What is shown beneath the title in place of `text`.
|
|
18
|
+
*/
|
|
19
|
+
description?: string;
|
|
20
|
+
/**
|
|
21
|
+
* Icon name drawn before the title.
|
|
22
|
+
*/
|
|
23
|
+
icon?: string;
|
|
24
|
+
};
|
|
25
|
+
export type PromptStartersOptions = {
|
|
26
|
+
/**
|
|
27
|
+
* The starters. An entry without `id`, `title` or `text` is
|
|
28
|
+
* left out, as is a repeated id; any other field on an item is handed back in `pick`.
|
|
29
|
+
*/
|
|
30
|
+
items?: PromptStarter[];
|
|
31
|
+
/**
|
|
32
|
+
* Accessible name of the group. Omitted resolves
|
|
33
|
+
* `promptStarters.label`, English `Suggestions`.
|
|
34
|
+
*/
|
|
35
|
+
label?: string | null;
|
|
36
|
+
/**
|
|
37
|
+
* Columns of starters. `'auto'` is two, and one in a
|
|
38
|
+
* container narrower than 32rem.
|
|
39
|
+
*/
|
|
40
|
+
columns?: 'auto' | 1 | 2;
|
|
41
|
+
/**
|
|
42
|
+
* Shows `label` above the starters as a heading of
|
|
43
|
+
* this level, which then names the group. Null keeps the label for assistive technology only.
|
|
44
|
+
*/
|
|
45
|
+
headingLevel?: 1 | 2 | 3 | 4 | 5 | 6 | null;
|
|
46
|
+
/**
|
|
47
|
+
* Localized messages.
|
|
48
|
+
*/
|
|
49
|
+
msg?: Record<string, string> | Record<string, Record<string, string>>;
|
|
50
|
+
/**
|
|
51
|
+
* Listener for a starter
|
|
52
|
+
* being picked.
|
|
53
|
+
*/
|
|
54
|
+
onpick?: (event: CustomEvent<{
|
|
55
|
+
item: PromptStarter;
|
|
56
|
+
}>) => void;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* Starting points for an empty conversation: a labelled group of buttons, each with a title and a
|
|
60
|
+
* muted line beneath it. A pick is only reported. Whether it fills the composer or sends at once
|
|
61
|
+
* is the application's decision, and PromptStarters never sends anything itself.
|
|
62
|
+
*
|
|
63
|
+
* @fires PromptStarters#pick
|
|
64
|
+
* @extends {Component<PromptStartersOptions>}
|
|
65
|
+
*/
|
|
66
|
+
export declare class PromptStarters extends Component<PromptStartersOptions> {
|
|
67
|
+
_original: import("../../core/dom.js").TargetSnapshot;
|
|
68
|
+
_destroyed: boolean;
|
|
69
|
+
/** @type {PromptStarter[]} */
|
|
70
|
+
_items: PromptStarter[];
|
|
71
|
+
_list: HTMLElement;
|
|
72
|
+
static cssName: string;
|
|
73
|
+
/** @type {Readonly<PromptStartersOptions>} */
|
|
74
|
+
static defaults: Readonly<PromptStartersOptions>;
|
|
75
|
+
/** @returns {HTMLElement} */
|
|
76
|
+
render(): HTMLElement;
|
|
77
|
+
/**
|
|
78
|
+
* Replaces the starters. The focus on a starter stays on the starter with the same `id`. Emits
|
|
79
|
+
* nothing.
|
|
80
|
+
* @param {PromptStarter[]} items
|
|
81
|
+
* @returns {this}
|
|
82
|
+
*/
|
|
83
|
+
setItems(items: PromptStarter[]): this;
|
|
84
|
+
/** Removes what was drawn and stops listening. @returns {void} */
|
|
85
|
+
destroy(): void;
|
|
86
|
+
/**
|
|
87
|
+
* @private
|
|
88
|
+
* @param {unknown} items
|
|
89
|
+
* @returns {void}
|
|
90
|
+
*/
|
|
91
|
+
private _build;
|
|
92
|
+
/**
|
|
93
|
+
* A starter's button: named by its title, described by the line beneath it.
|
|
94
|
+
* @private
|
|
95
|
+
* @param {PromptStarter} item
|
|
96
|
+
* @returns {HTMLElement}
|
|
97
|
+
*/
|
|
98
|
+
private _button;
|
|
99
|
+
/**
|
|
100
|
+
* @private
|
|
101
|
+
* @param {MouseEvent} event
|
|
102
|
+
* @returns {void}
|
|
103
|
+
* @fires PromptStarters#pick
|
|
104
|
+
*/
|
|
105
|
+
private _onClick;
|
|
106
|
+
}
|
|
107
|
+
/** Fired when a starter is picked. Nothing is sent: the application decides what a pick does. @event PromptStarters#pick @type {CustomEvent<{item: PromptStarter}>} */
|
|
@@ -5,17 +5,20 @@ export type ProseAnchorsOptions = {
|
|
|
5
5
|
*/
|
|
6
6
|
selector?: string;
|
|
7
7
|
/**
|
|
8
|
-
* The link's accessible name; `%1` is the heading.
|
|
8
|
+
* The link's accessible name; `%1` is the heading. By default the
|
|
9
|
+
* `prose.copyLinkTo` message ("Copy link to %1"). Null gives none.
|
|
9
10
|
*/
|
|
10
|
-
label?: string;
|
|
11
|
+
label?: string | null;
|
|
11
12
|
/**
|
|
12
|
-
* The link's tooltip.
|
|
13
|
+
* The link's tooltip, by default the `prose.copyLink` message
|
|
14
|
+
* ("Copy link"). Null gives none.
|
|
13
15
|
*/
|
|
14
|
-
title?: string;
|
|
16
|
+
title?: string | null;
|
|
15
17
|
/**
|
|
16
|
-
* What the live region says after a copy
|
|
18
|
+
* What the live region says after a copy, by default the
|
|
19
|
+
* `prose.copied` message ("Link copied"). Null says nothing.
|
|
17
20
|
*/
|
|
18
|
-
feedback?: string;
|
|
21
|
+
feedback?: string | null;
|
|
19
22
|
/**
|
|
20
23
|
* Milliseconds the tick and the message stay.
|
|
21
24
|
*/
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Declarative questionnaire logic: conditions, branch targets and validation rules written as
|
|
3
|
+
* plain JSON instead of functions, so they can be stored, sent and written by an agent.
|
|
4
|
+
*
|
|
5
|
+
* Everything here is pure and touches no DOM. The Questionnaire evaluates its items' `when`,
|
|
6
|
+
* `next` and `validate` with these functions, and so does anything else that shows or hides an
|
|
7
|
+
* input on a condition, so the two cannot drift.
|
|
8
|
+
* @module questionnaire/conditions
|
|
9
|
+
*/
|
|
10
|
+
export type ConditionOp = 'eq' | 'ne' | 'in' | 'nin' | 'gt' | 'gte' | 'lt' | 'lte' | 'empty' | 'filled' | 'contains';
|
|
11
|
+
export type ConditionValue = string | number | boolean | null;
|
|
12
|
+
export type FieldCondition = {
|
|
13
|
+
/**
|
|
14
|
+
* Name of the answer tested.
|
|
15
|
+
*/
|
|
16
|
+
field: string;
|
|
17
|
+
/**
|
|
18
|
+
* The comparison.
|
|
19
|
+
*/
|
|
20
|
+
op: ConditionOp;
|
|
21
|
+
/**
|
|
22
|
+
* What the answer is compared with: a list
|
|
23
|
+
* for `in` and `nin`, nothing for `empty` and `filled`, one value otherwise.
|
|
24
|
+
*/
|
|
25
|
+
value?: ConditionValue | ConditionValue[];
|
|
26
|
+
};
|
|
27
|
+
export type Condition = FieldCondition | {
|
|
28
|
+
all: Condition[];
|
|
29
|
+
} | {
|
|
30
|
+
any: Condition[];
|
|
31
|
+
} | {
|
|
32
|
+
not: Condition;
|
|
33
|
+
};
|
|
34
|
+
export type NextBranch = {
|
|
35
|
+
/**
|
|
36
|
+
* Condition to test. Only the last entry may leave it out.
|
|
37
|
+
*/
|
|
38
|
+
if?: Condition;
|
|
39
|
+
/**
|
|
40
|
+
* Item name, `$review` or `$submit`.
|
|
41
|
+
*/
|
|
42
|
+
goto: string;
|
|
43
|
+
};
|
|
44
|
+
export type NextTarget = string | NextBranch[];
|
|
45
|
+
export type ValidationRule = {
|
|
46
|
+
/**
|
|
47
|
+
* Whether an answer is needed.
|
|
48
|
+
*/
|
|
49
|
+
required?: boolean;
|
|
50
|
+
/**
|
|
51
|
+
* Fewest characters or entries.
|
|
52
|
+
*/
|
|
53
|
+
minLength?: number;
|
|
54
|
+
/**
|
|
55
|
+
* Most characters or entries.
|
|
56
|
+
*/
|
|
57
|
+
maxLength?: number;
|
|
58
|
+
/**
|
|
59
|
+
* Lowest number.
|
|
60
|
+
*/
|
|
61
|
+
minimum?: number;
|
|
62
|
+
/**
|
|
63
|
+
* Highest number.
|
|
64
|
+
*/
|
|
65
|
+
maximum?: number;
|
|
66
|
+
/**
|
|
67
|
+
* Named format the text must follow.
|
|
68
|
+
*/
|
|
69
|
+
format?: RuleFormat;
|
|
70
|
+
/**
|
|
71
|
+
* Allowed values.
|
|
72
|
+
*/
|
|
73
|
+
oneOf?: ConditionValue[];
|
|
74
|
+
/**
|
|
75
|
+
* Text shown when this rule fails.
|
|
76
|
+
*/
|
|
77
|
+
message?: string;
|
|
78
|
+
};
|
|
79
|
+
export type RuleFormat = 'date' | 'date-time' | 'time' | 'email' | 'uri';
|
|
80
|
+
export type ConditionProblem = {
|
|
81
|
+
/**
|
|
82
|
+
* Where the problem is.
|
|
83
|
+
*/
|
|
84
|
+
path: string;
|
|
85
|
+
/**
|
|
86
|
+
* What is wrong.
|
|
87
|
+
*/
|
|
88
|
+
message: string;
|
|
89
|
+
};
|
|
90
|
+
export type RuleMessage = (key: string, ...args: unknown[]) => string;
|
|
91
|
+
/**
|
|
92
|
+
* The comparison a leaf condition makes.
|
|
93
|
+
* - `eq`, `ne`: equal, not equal. A number compares with a numeric string by value.
|
|
94
|
+
* - `in`, `nin`: the answer is (is not) one of `value`, a list. A multiple answer is "in" when any
|
|
95
|
+
* of its entries is.
|
|
96
|
+
* - `gt`, `gte`, `lt`, `lte`: two numbers by value, two strings in code-point order (so ISO dates
|
|
97
|
+
* and times compare correctly). Anything else is never greater or less.
|
|
98
|
+
* - A `Date` answer meets a string value in that value's shape: its local `YYYY-MM-DD` against a
|
|
99
|
+
* date, its local `YYYY-MM-DDTHH:MM` (`:SS` only when not zero) against a date-time.
|
|
100
|
+
* - A value is never `null`: an unanswered item has no answer to compare, so test it with `empty`.
|
|
101
|
+
* - `empty`, `filled`: the answer is (is not) absent: `null`, an empty or blank string, or a list
|
|
102
|
+
* with no non-empty entry. `false` and `0` are answers. These take no `value`.
|
|
103
|
+
* - `contains`: a multiple answer holds `value`, or a text answer contains the string `value`.
|
|
104
|
+
* @typedef {'eq'|'ne'|'in'|'nin'|'gt'|'gte'|'lt'|'lte'|'empty'|'filled'|'contains'} ConditionOp
|
|
105
|
+
*/
|
|
106
|
+
/** @typedef {string|number|boolean|null} ConditionValue */
|
|
107
|
+
/**
|
|
108
|
+
* A test of one answer.
|
|
109
|
+
* @typedef {Object} FieldCondition
|
|
110
|
+
* @property {string} field Name of the answer tested.
|
|
111
|
+
* @property {ConditionOp} op The comparison.
|
|
112
|
+
* @property {ConditionValue|ConditionValue[]} [value] What the answer is compared with: a list
|
|
113
|
+
* for `in` and `nin`, nothing for `empty` and `filled`, one value otherwise.
|
|
114
|
+
*/
|
|
115
|
+
/**
|
|
116
|
+
* A condition: a field test, or `{all: […]}`, `{any: […]}` or `{not: …}` around further
|
|
117
|
+
* conditions, at most four levels deep counting the field test itself.
|
|
118
|
+
* @typedef {FieldCondition|{all: Condition[]}|{any: Condition[]}|{not: Condition}} Condition
|
|
119
|
+
*/
|
|
120
|
+
/**
|
|
121
|
+
* One entry of a branch list: `goto` is taken when `if` holds, or always when there is no `if`.
|
|
122
|
+
* @typedef {Object} NextBranch
|
|
123
|
+
* @property {Condition} [if] Condition to test. Only the last entry may leave it out.
|
|
124
|
+
* @property {string} goto Item name, `$review` or `$submit`.
|
|
125
|
+
*/
|
|
126
|
+
/**
|
|
127
|
+
* Where an item leads: an item name, `$review` (the review screen), `$submit` (straight to
|
|
128
|
+
* submission), or a list of branches whose first match wins. No match falls through to the next
|
|
129
|
+
* visible item.
|
|
130
|
+
* @typedef {string|NextBranch[]} NextTarget
|
|
131
|
+
*/
|
|
132
|
+
/**
|
|
133
|
+
* One validation rule. Each rule object carries exactly one rule key, and optionally the `message`
|
|
134
|
+
* shown when it fails in place of the default.
|
|
135
|
+
* - `{required: true}`: an answer must be given.
|
|
136
|
+
* - `{minLength: n}`, `{maxLength: n}`: characters of a text answer, or entries of a multiple one.
|
|
137
|
+
* - `{minimum: n}`, `{maximum: n}`: a number, or a numeric text answer.
|
|
138
|
+
* - `{format: 'date'|'date-time'|'time'|'email'|'uri'}`: `YYYY-MM-DD`, an ISO 8601 date and time,
|
|
139
|
+
* `HH:MM` or `HH:MM:SS`, an email address, an absolute URI.
|
|
140
|
+
* - `{oneOf: [values]}`: the answer, or every entry of a multiple one, is one of the values.
|
|
141
|
+
*
|
|
142
|
+
* Rules other than `required` pass an empty answer; there are no patterns.
|
|
143
|
+
* @typedef {Object} ValidationRule
|
|
144
|
+
* @property {boolean} [required] Whether an answer is needed.
|
|
145
|
+
* @property {number} [minLength] Fewest characters or entries.
|
|
146
|
+
* @property {number} [maxLength] Most characters or entries.
|
|
147
|
+
* @property {number} [minimum] Lowest number.
|
|
148
|
+
* @property {number} [maximum] Highest number.
|
|
149
|
+
* @property {RuleFormat} [format] Named format the text must follow.
|
|
150
|
+
* @property {ConditionValue[]} [oneOf] Allowed values.
|
|
151
|
+
* @property {string} [message] Text shown when this rule fails.
|
|
152
|
+
*/
|
|
153
|
+
/** @typedef {'date'|'date-time'|'time'|'email'|'uri'} RuleFormat */
|
|
154
|
+
/**
|
|
155
|
+
* A problem found in a declarative condition, branch list or rule list. `path` is a JSON Pointer
|
|
156
|
+
* into the checked value (`''` for the value itself).
|
|
157
|
+
* @typedef {Object} ConditionProblem
|
|
158
|
+
* @property {string} path Where the problem is.
|
|
159
|
+
* @property {string} message What is wrong.
|
|
160
|
+
*/
|
|
161
|
+
/**
|
|
162
|
+
* Turns a message key and its arguments into text. Keys are the rule names, `minItems` and
|
|
163
|
+
* `maxItems` for the list forms of `minLength` and `maxLength`, and the format name itself
|
|
164
|
+
* (`date`, `date-time`, `time`, `email`, `uri`) for a failed `format`.
|
|
165
|
+
* Called with the key and the interpolation values for `%1`, `%2`, ….
|
|
166
|
+
* @typedef {(key: string, ...args: unknown[]) => string} RuleMessage
|
|
167
|
+
*/
|
|
168
|
+
/** Deepest a condition may nest, counting the field test itself. */
|
|
169
|
+
export declare const MAX_CONDITION_DEPTH = 4;
|
|
170
|
+
/** Every comparison a field condition may make. */
|
|
171
|
+
export declare const CONDITION_OPS: readonly ConditionOp[];
|
|
172
|
+
/** Every validation rule. */
|
|
173
|
+
export declare const RULE_NAMES: readonly string[];
|
|
174
|
+
/** Every named format the `format` rule knows. */
|
|
175
|
+
export declare const RULE_FORMATS: readonly RuleFormat[];
|
|
176
|
+
/** The `next` target that opens the review screen. */
|
|
177
|
+
export declare const NEXT_REVIEW = "$review";
|
|
178
|
+
/** The `next` target that submits at once, skipping any review screen. */
|
|
179
|
+
export declare const NEXT_SUBMIT = "$submit";
|
|
180
|
+
/** English texts of the rule messages, keyed as `RuleMessage` describes. */
|
|
181
|
+
export declare const RULE_MESSAGES: Readonly<{
|
|
182
|
+
required: "Enter an answer to continue.";
|
|
183
|
+
minLength: "Enter at least %1 characters.";
|
|
184
|
+
maxLength: "Enter at most %1 characters.";
|
|
185
|
+
minItems: "Choose at least %1.";
|
|
186
|
+
maxItems: "Choose at most %1.";
|
|
187
|
+
minimum: "Enter a number of at least %1.";
|
|
188
|
+
maximum: "Enter a number of at most %1.";
|
|
189
|
+
oneOf: "Choose one of the offered answers.";
|
|
190
|
+
date: "Enter a date as YYYY-MM-DD.";
|
|
191
|
+
'date-time': "Enter a date and time as YYYY-MM-DDTHH:MM.";
|
|
192
|
+
time: "Enter a time as HH:MM.";
|
|
193
|
+
email: "Enter an email address.";
|
|
194
|
+
uri: "Enter a full address, such as https://example.com.";
|
|
195
|
+
}>;
|
|
196
|
+
/**
|
|
197
|
+
* The English rule message for a key, with `%1` filled in. The default `RuleMessage`.
|
|
198
|
+
* @param {string} key Message key.
|
|
199
|
+
* @param {...unknown} args Interpolation values for `%1`, `%2`, ….
|
|
200
|
+
* @returns {string}
|
|
201
|
+
*/
|
|
202
|
+
export declare function ruleMessage(key: string, ...args: unknown[]): string;
|
|
203
|
+
/**
|
|
204
|
+
* Reports whether an answer counts as absent. An empty or blank string, a list with no non-empty
|
|
205
|
+
* entry, `null` and `undefined` are "no answer"; `false` and `0` are answers.
|
|
206
|
+
* @param {unknown} value Answer value.
|
|
207
|
+
* @returns {boolean}
|
|
208
|
+
*/
|
|
209
|
+
export declare function isEmptyAnswer(value: unknown): boolean;
|
|
210
|
+
/**
|
|
211
|
+
* Evaluates a condition against a set of answers. The caller decides which answers a condition
|
|
212
|
+
* may see; the Questionnaire hands each item only the answers of visible items declared before it.
|
|
213
|
+
* @param {Condition} condition Condition to evaluate.
|
|
214
|
+
* @param {Record<string, unknown>} answers Answers by name.
|
|
215
|
+
* @returns {boolean}
|
|
216
|
+
* @throws {TypeError} When the condition is malformed or nests deeper than four levels; check it
|
|
217
|
+
* first with `checkCondition()` to report rather than throw.
|
|
218
|
+
*/
|
|
219
|
+
export declare function evaluate(condition: Condition, answers: Record<string, unknown>): boolean;
|
|
220
|
+
/**
|
|
221
|
+
* Checks a condition's shape without evaluating it, and lists every problem rather than stopping
|
|
222
|
+
* at the first. With `fields`, a field test may only name one of them — how a caller limits a
|
|
223
|
+
* condition to the inputs declared before it.
|
|
224
|
+
* @param {unknown} condition Condition to check.
|
|
225
|
+
* @param {{fields?: Iterable<string>|null, maxDepth?: number}} [options]
|
|
226
|
+
* @returns {ConditionProblem[]} Empty when the condition is well-formed.
|
|
227
|
+
*/
|
|
228
|
+
export declare function checkCondition(condition: unknown, options?: {
|
|
229
|
+
fields?: Iterable<string> | null;
|
|
230
|
+
maxDepth?: number;
|
|
231
|
+
}): ConditionProblem[];
|
|
232
|
+
/**
|
|
233
|
+
* Resolves where an item leads, given its answer. A list's first entry whose `if` holds — or that
|
|
234
|
+
* has no `if` — wins; no match, like no `next`, gives `null`. A function form is called with the
|
|
235
|
+
* answer and the answers and its result returned as a name.
|
|
236
|
+
* @param {NextTarget|((answer: unknown, answers: Record<string, unknown>) => string|null)|null|undefined} next
|
|
237
|
+
* Branch target.
|
|
238
|
+
* @param {unknown} answer The item's own answer.
|
|
239
|
+
* @param {Record<string, unknown>} answers Answers the branch conditions may see.
|
|
240
|
+
* @returns {string|null} An item name, `$review`, `$submit`, or `null` to fall through.
|
|
241
|
+
* @throws {TypeError} When `next` or one of its conditions is malformed.
|
|
242
|
+
*/
|
|
243
|
+
export declare function resolveNext(next: NextTarget | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null | undefined, answer: unknown, answers: Record<string, unknown>): string | null;
|
|
244
|
+
/**
|
|
245
|
+
* Checks a declarative `next` without resolving it. With `targets`, every name must be one of
|
|
246
|
+
* them or a sentinel; with `fields`, branch conditions may only name those.
|
|
247
|
+
* @param {unknown} next Branch target to check.
|
|
248
|
+
* @param {{targets?: Iterable<string>|null, fields?: Iterable<string>|null}} [options]
|
|
249
|
+
* @returns {ConditionProblem[]} Empty when well-formed.
|
|
250
|
+
*/
|
|
251
|
+
export declare function checkNext(next: unknown, options?: {
|
|
252
|
+
targets?: Iterable<string> | null;
|
|
253
|
+
fields?: Iterable<string> | null;
|
|
254
|
+
}): ConditionProblem[];
|
|
255
|
+
/**
|
|
256
|
+
* Runs validation rules in order and returns the first failure's message: the rule's own
|
|
257
|
+
* `message`, or the default from `message`. Rules other than `required` pass an empty answer.
|
|
258
|
+
* @param {ValidationRule[]} rules Rules to run.
|
|
259
|
+
* @param {unknown} value The answer.
|
|
260
|
+
* @param {RuleMessage} [message=ruleMessage] Resolves a default message.
|
|
261
|
+
* @returns {string|null} The message, or `null` when every rule passes.
|
|
262
|
+
* @throws {TypeError} When a rule is malformed; check them first with `checkRuleList()`.
|
|
263
|
+
*/
|
|
264
|
+
export declare function checkRules(rules: ValidationRule[], value: unknown, message?: RuleMessage): string | null;
|
|
265
|
+
/**
|
|
266
|
+
* Checks a rule list's shape without running it, and lists every problem.
|
|
267
|
+
* @param {unknown} rules Rules to check.
|
|
268
|
+
* @returns {ConditionProblem[]} Empty when well-formed.
|
|
269
|
+
*/
|
|
270
|
+
export declare function checkRuleList(rules: unknown): ConditionProblem[];
|
|
@@ -1,9 +1,8 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
*/
|
|
1
|
+
import { isEmptyAnswer } from './conditions.js';
|
|
2
|
+
export { isEmptyAnswer };
|
|
3
|
+
export type Condition = import('./conditions.js').Condition;
|
|
4
|
+
export type NextTarget = import('./conditions.js').NextTarget;
|
|
5
|
+
export type ValidationRule = import('./conditions.js').ValidationRule;
|
|
7
6
|
export type QuestionnaireChoice = {
|
|
8
7
|
/**
|
|
9
8
|
* Answer value, unique within its item.
|
|
@@ -95,17 +94,24 @@ export type QuestionnaireItem = {
|
|
|
95
94
|
*/
|
|
96
95
|
field?: any | null;
|
|
97
96
|
/**
|
|
98
|
-
* Visibility
|
|
97
|
+
* Visibility:
|
|
98
|
+
* a declarative condition, or a predicate. Either sees only the answers of visible items declared
|
|
99
|
+
* before this one, and a declarative condition may only name those items. Anything else, such as
|
|
100
|
+
* `false` or `{}`, reads as absent.
|
|
99
101
|
*/
|
|
100
|
-
when?: ((answers: Record<string, unknown>) => boolean) | null;
|
|
102
|
+
when?: Condition | ((answers: Record<string, unknown>) => boolean) | null;
|
|
101
103
|
/**
|
|
102
|
-
* Branch target: an item name,
|
|
104
|
+
* Branch target: an item name, `$review`, `$submit`, a list of `{if, goto}` branches whose first
|
|
105
|
+
* match wins, or a function returning a name. A branch condition may name this item and the
|
|
106
|
+
* items declared before it. An item named `$review` or `$submit` takes the name's place; anything
|
|
107
|
+
* else, such as `false` or `[]`, reads as absent.
|
|
103
108
|
*/
|
|
104
|
-
next?:
|
|
109
|
+
next?: NextTarget | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
|
|
105
110
|
/**
|
|
106
|
-
* Extra validation
|
|
111
|
+
* Extra validation: a list of declarative rules, or a function returning an error message, or
|
|
112
|
+
* null when the answer is acceptable. Anything else, such as `false` or `[]`, reads as absent.
|
|
107
113
|
*/
|
|
108
|
-
validate?: ((answer: unknown, answers: Record<string, unknown>) => string | null | Promise<string | null>) | null;
|
|
114
|
+
validate?: ValidationRule[] | ((answer: unknown, answers: Record<string, unknown>) => string | null | Promise<string | null>) | null;
|
|
109
115
|
};
|
|
110
116
|
export type NormalizedItem = {
|
|
111
117
|
/**
|
|
@@ -149,17 +155,18 @@ export type NormalizedItem = {
|
|
|
149
155
|
*/
|
|
150
156
|
field: any | null;
|
|
151
157
|
/**
|
|
152
|
-
* Visibility
|
|
158
|
+
* Visibility
|
|
159
|
+
* condition or predicate.
|
|
153
160
|
*/
|
|
154
|
-
when: ((answers: Record<string, unknown>) => boolean) | null;
|
|
161
|
+
when: Condition | ((answers: Record<string, unknown>) => boolean) | null;
|
|
155
162
|
/**
|
|
156
163
|
* Branch target.
|
|
157
164
|
*/
|
|
158
|
-
next:
|
|
165
|
+
next: NextTarget | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
|
|
159
166
|
/**
|
|
160
|
-
*
|
|
167
|
+
* Extra validation.
|
|
161
168
|
*/
|
|
162
|
-
validate: ((answer: unknown, answers: Record<string, unknown>) => string | null | Promise<string | null>) | null;
|
|
169
|
+
validate: ValidationRule[] | ((answer: unknown, answers: Record<string, unknown>) => string | null | Promise<string | null>) | null;
|
|
163
170
|
};
|
|
164
171
|
export type NormalizedChoice = {
|
|
165
172
|
/**
|
|
@@ -226,12 +233,23 @@ export type QuestionnaireProgress = {
|
|
|
226
233
|
section: string;
|
|
227
234
|
};
|
|
228
235
|
/**
|
|
229
|
-
* Normalizes and validates a list of item definitions. Never mutates its input
|
|
236
|
+
* Normalizes and validates a list of item definitions. Never mutates its input; declarative
|
|
237
|
+
* `when`, `next` and `validate` forms are copied.
|
|
230
238
|
* @param {QuestionnaireItem[]} list Item definitions.
|
|
231
239
|
* @returns {NormalizedItem[]}
|
|
232
|
-
* @throws {TypeError} When the list, an item, or a name is malformed,
|
|
240
|
+
* @throws {TypeError} When the list, an item, or a name is malformed, a name repeats, or a
|
|
241
|
+
* declarative condition, branch list or rule list is malformed — including a condition naming
|
|
242
|
+
* an item that is not declared before it. A `when`, `next` or `validate` that is neither
|
|
243
|
+
* declarative nor a function does not throw: it reads as absent.
|
|
233
244
|
*/
|
|
234
245
|
export declare function normalizeItems(list: QuestionnaireItem[]): NormalizedItem[];
|
|
246
|
+
/**
|
|
247
|
+
* {@link normalizeItems} with the messages of a component.
|
|
248
|
+
* @param {QuestionnaireItem[]} list Item definitions.
|
|
249
|
+
* @param {(key: string) => string} text Resolves the default label of a free-form input.
|
|
250
|
+
* @returns {NormalizedItem[]}
|
|
251
|
+
*/
|
|
252
|
+
export declare function normalizeItemList(list: QuestionnaireItem[], text: (key: string) => string): NormalizedItem[];
|
|
235
253
|
/**
|
|
236
254
|
* Normalizes an item's choices and hands out the shortcut keys. Explicit keys are reserved before
|
|
237
255
|
* any are assigned, so adding one to the third choice never renumbers the others.
|
|
@@ -242,9 +260,9 @@ export declare function normalizeItems(list: QuestionnaireItem[]): NormalizedIte
|
|
|
242
260
|
*/
|
|
243
261
|
export declare function normalizeChoices(list: QuestionnaireChoice[], itemName?: string): NormalizedChoice[];
|
|
244
262
|
/**
|
|
245
|
-
* Reports whether an item's `when` predicate passes for a given set of answers. An
|
|
246
|
-
* one is always visible, and a
|
|
247
|
-
* strand the reader mid-questionnaire.
|
|
263
|
+
* Reports whether an item's `when` condition or predicate passes for a given set of answers. An
|
|
264
|
+
* item without one is always visible, and a condition that throws hides nothing — a broken
|
|
265
|
+
* condition must not strand the reader mid-questionnaire.
|
|
248
266
|
* @param {NormalizedItem} item Item to test.
|
|
249
267
|
* @param {Record<string, unknown>} answers Answers visible to the predicate.
|
|
250
268
|
* @returns {boolean}
|
|
@@ -275,23 +293,27 @@ export declare function visibleItems(items: NormalizedItem[], raw: Record<string
|
|
|
275
293
|
/**
|
|
276
294
|
* Resolves which item follows the given one.
|
|
277
295
|
*
|
|
278
|
-
* A `next` of `null
|
|
279
|
-
*
|
|
280
|
-
*
|
|
296
|
+
* A `next` of `null`, or a branch list where nothing matches, falls through to the next visible
|
|
297
|
+
* item in declaration order. A string, a matching branch, or a function returning a string names a
|
|
298
|
+
* target: when that target is currently hidden the walk continues forward from it rather than
|
|
299
|
+
* stranding the reader on an invisible question. `$review` and `$submit` are returned as they are,
|
|
300
|
+
* for the caller to open the review screen or submit, unless an item bears that name.
|
|
281
301
|
* @param {NormalizedItem[]} items All items.
|
|
282
302
|
* @param {NormalizedItem} item Item being left.
|
|
283
303
|
* @param {Record<string, unknown>} raw Every answer given.
|
|
284
|
-
* @returns {string|null} Name of the next item, or null at the end of the
|
|
304
|
+
* @returns {string|null} Name of the next item, `$review`, `$submit`, or null at the end of the
|
|
305
|
+
* questionnaire.
|
|
285
306
|
* @throws {RangeError} When `next` names an item that does not exist.
|
|
286
307
|
*/
|
|
287
308
|
export declare function resolveNext(items: NormalizedItem[], item: NormalizedItem, raw: Record<string, unknown>): string | null;
|
|
288
309
|
/**
|
|
289
|
-
* Reports whether
|
|
290
|
-
*
|
|
291
|
-
* @param {
|
|
310
|
+
* Reports whether a resolved target ends the walk rather than naming an item: `$review` or
|
|
311
|
+
* `$submit`, unless an item bears that name, which then goes first.
|
|
312
|
+
* @param {NormalizedItem[]} items All items.
|
|
313
|
+
* @param {string|null} target What `resolveNext()` returned.
|
|
292
314
|
* @returns {boolean}
|
|
293
315
|
*/
|
|
294
|
-
export declare function
|
|
316
|
+
export declare function endsFlow(items: NormalizedItem[], target: string | null): boolean;
|
|
295
317
|
/**
|
|
296
318
|
* Runs the synchronous part of validation: the required check. An item's own `validate` may be
|
|
297
319
|
* asynchronous and is awaited by the component instead.
|