@zeyos/zx 5.6.0 → 5.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/CHANGELOG.md +154 -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/code-editor/code-editor.d.ts +7 -2
  15. package/dist/types/components/composer/composer.d.ts +206 -4
  16. package/dist/types/components/composer/queue.d.ts +76 -0
  17. package/dist/types/components/copy/copy-button.d.ts +6 -4
  18. package/dist/types/components/copy/copy-input.d.ts +10 -6
  19. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  20. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  21. package/dist/types/components/dock/dock.d.ts +12 -3
  22. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  23. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  24. package/dist/types/components/file-item/file-item.d.ts +3 -2
  25. package/dist/types/components/file-list/file-list.d.ts +14 -8
  26. package/dist/types/components/filter/filter-model.d.ts +31 -1
  27. package/dist/types/components/filter/filter.d.ts +20 -2
  28. package/dist/types/components/finder/finder.d.ts +14 -6
  29. package/dist/types/components/flag/flag.d.ts +99 -0
  30. package/dist/types/components/grid/grid.d.ts +1 -1
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  32. package/dist/types/components/launcher/launcher.d.ts +2 -0
  33. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  34. package/dist/types/components/number-field/number-field.d.ts +17 -6
  35. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  36. package/dist/types/components/prose/prose.d.ts +9 -6
  37. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  38. package/dist/types/components/questionnaire/items.d.ts +52 -30
  39. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  40. package/dist/types/components/rating/rating.d.ts +5 -3
  41. package/dist/types/components/select/country.d.ts +106 -0
  42. package/dist/types/components/select/field-adapter.d.ts +2 -1
  43. package/dist/types/components/select/locale.d.ts +102 -0
  44. package/dist/types/components/select/select.d.ts +41 -2
  45. package/dist/types/components/slider/slider.d.ts +1 -0
  46. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  47. package/dist/types/components/source-list/source-list.d.ts +7 -5
  48. package/dist/types/components/split-view/split-view.d.ts +5 -3
  49. package/dist/types/components/surface/catalog.d.ts +260 -0
  50. package/dist/types/components/surface/elicit.d.ts +81 -0
  51. package/dist/types/components/surface/mcp.d.ts +165 -0
  52. package/dist/types/components/surface/schema.d.ts +314 -0
  53. package/dist/types/components/surface/stream.d.ts +118 -0
  54. package/dist/types/components/surface/surface.d.ts +718 -0
  55. package/dist/types/components/surface/text.d.ts +277 -0
  56. package/dist/types/components/surface/validate.d.ts +339 -0
  57. package/dist/types/components/table/table.d.ts +55 -3
  58. package/dist/types/components/table/window.d.ts +203 -0
  59. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  60. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  61. package/dist/types/components/tree/tree.d.ts +20 -13
  62. package/dist/types/core/component.d.ts +10 -0
  63. package/dist/types/core/date.d.ts +8 -1
  64. package/dist/types/core/dom.d.ts +1 -0
  65. package/dist/types/core/http.d.ts +10 -0
  66. package/dist/types/core/i18n.d.ts +38 -0
  67. package/dist/types/core/messages.d.ts +344 -1
  68. package/dist/types/core/storage.d.ts +7 -2
  69. package/dist/types/elements/define.d.ts +21 -46
  70. package/dist/types/elements/definitions.d.ts +147 -0
  71. package/dist/types/elements/kit.d.ts +7 -0
  72. package/dist/types/elements/reflect.d.ts +6 -3
  73. package/dist/types/index.d.ts +10 -1
  74. package/dist/types/internal/date-locale.d.ts +7 -0
  75. package/dist/types/internal/json-patch.d.ts +146 -0
  76. package/dist/types/locales/de.d.ts +13 -0
  77. package/dist/types/locales/en.d.ts +2 -0
  78. package/dist/types/locales/index.d.ts +823 -0
  79. package/dist/types/zeyos/view.d.ts +8 -1
  80. package/dist/zx-zeyos.esm.js +16802 -15180
  81. package/dist/zx-zeyos.esm.min.js +5 -5
  82. package/dist/zx.core.css +1276 -0
  83. package/dist/zx.core.min.css +1 -0
  84. package/dist/zx.css +498 -134
  85. package/dist/zx.esm.js +40778 -29654
  86. package/dist/zx.esm.min.js +36 -23
  87. package/dist/zx.global.js +40778 -29654
  88. package/dist/zx.global.min.js +36 -23
  89. package/dist/zx.layered.css +17302 -0
  90. package/dist/zx.layered.min.css +1 -0
  91. package/dist/zx.min.css +1 -1
  92. package/docs/agent-catalog.json +12501 -0
  93. package/docs/agent-surfaces.md +340 -0
  94. package/docs/api.json +851 -121
  95. package/docs/llms.md +1018 -71
  96. package/docs/llms.txt +30 -9
  97. package/package.json +29 -6
  98. package/src/components/account-menu/account-menu.js +6 -3
  99. package/src/components/activity-item/activity-item.js +2 -1
  100. package/src/components/activity-list/activity-list.js +16 -10
  101. package/src/components/agent-thread/ag-ui.js +1439 -0
  102. package/src/components/agent-thread/agent-thread.js +359 -54
  103. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  104. package/src/components/app-sidebar/app-sidebar.js +18 -8
  105. package/src/components/approval-card/approval-card.js +3 -2
  106. package/src/components/block-view/block-view.js +7 -6
  107. package/src/components/breadcrumb/breadcrumb.js +8 -5
  108. package/src/components/calendar/calendar-model.js +8 -2
  109. package/src/components/calendar/calendar.js +53 -18
  110. package/src/components/chart/chart.js +54 -23
  111. package/src/components/code-editor/code-editor.js +45 -8
  112. package/src/components/code-editor/field-adapter.js +1 -1
  113. package/src/components/composer/composer.css +80 -1
  114. package/src/components/composer/composer.js +390 -16
  115. package/src/components/composer/queue.js +78 -0
  116. package/src/components/context-menu/context-menu.js +12 -1
  117. package/src/components/copy/copy-button.js +9 -7
  118. package/src/components/copy/copy-input.js +10 -6
  119. package/src/components/date-picker/date-picker.js +2 -1
  120. package/src/components/date-picker/date-range-picker.js +8 -7
  121. package/src/components/datebox/date-range-box.js +3 -9
  122. package/src/components/datebox/datebox.js +18 -21
  123. package/src/components/datebox/placeholder.js +18 -0
  124. package/src/components/dialog/dialog.js +1 -1
  125. package/src/components/dock/dock.js +34 -13
  126. package/src/components/entity-ref/entity-ref.js +16 -5
  127. package/src/components/field-upload/field-upload.js +81 -38
  128. package/src/components/file-item/file-item.js +70 -40
  129. package/src/components/file-list/file-list.js +15 -9
  130. package/src/components/filter/filter-model.js +46 -8
  131. package/src/components/filter/filter.css +3 -3
  132. package/src/components/filter/filter.js +29 -10
  133. package/src/components/filter-panel/filter-panel.js +13 -5
  134. package/src/components/finder/finder.js +50 -26
  135. package/src/components/flag/flag.css +40 -0
  136. package/src/components/flag/flag.js +177 -0
  137. package/src/components/form/form.js +1 -1
  138. package/src/components/grid/grid.js +22 -8
  139. package/src/components/kanban-view/kanban-view.js +51 -81
  140. package/src/components/launcher/launcher.js +17 -2
  141. package/src/components/list-toolbar/list-toolbar.js +2 -1
  142. package/src/components/master-panel/master-panel.js +1 -1
  143. package/src/components/menu-button/menu-button.js +4 -0
  144. package/src/components/message/message.js +3 -0
  145. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  146. package/src/components/navigation-bar/navigation-bar.js +3 -3
  147. package/src/components/number-field/number-field.js +29 -13
  148. package/src/components/prompt-starters/prompt-starters.css +91 -0
  149. package/src/components/prompt-starters/prompt-starters.js +206 -0
  150. package/src/components/prose/prose.js +14 -10
  151. package/src/components/questionnaire/conditions.js +666 -0
  152. package/src/components/questionnaire/items.js +150 -41
  153. package/src/components/questionnaire/questionnaire.js +126 -32
  154. package/src/components/rating/rating.js +5 -4
  155. package/src/components/run-status/run-status.js +2 -2
  156. package/src/components/select/country.js +136 -0
  157. package/src/components/select/field-adapter.js +7 -2
  158. package/src/components/select/locale.js +219 -0
  159. package/src/components/select/select.css +20 -22
  160. package/src/components/select/select.js +94 -12
  161. package/src/components/sheet/sheet-stack.js +10 -1
  162. package/src/components/slider/slider.js +7 -2
  163. package/src/components/sort-control/sort-control.js +15 -5
  164. package/src/components/source-list/source-list.js +7 -4
  165. package/src/components/split-view/split-view.js +5 -3
  166. package/src/components/surface/catalog.js +1334 -0
  167. package/src/components/surface/elicit.js +107 -0
  168. package/src/components/surface/mcp.js +243 -0
  169. package/src/components/surface/schema.js +644 -0
  170. package/src/components/surface/stream.js +245 -0
  171. package/src/components/surface/surface.css +308 -0
  172. package/src/components/surface/surface.js +2291 -0
  173. package/src/components/surface/text.js +513 -0
  174. package/src/components/surface/validate.js +2218 -0
  175. package/src/components/tabbox/tabbox.js +9 -0
  176. package/src/components/table/table.css +63 -3
  177. package/src/components/table/table.js +167 -28
  178. package/src/components/table/window.js +317 -0
  179. package/src/components/toolbar/toolbar.js +12 -7
  180. package/src/components/tooltip/tooltip.css +2 -3
  181. package/src/components/tooltip/tooltip.js +32 -5
  182. package/src/components/tree/tree.js +53 -23
  183. package/src/core/component.js +25 -1
  184. package/src/core/date.js +62 -16
  185. package/src/core/dom.js +22 -2
  186. package/src/core/format.js +15 -13
  187. package/src/core/http.js +29 -20
  188. package/src/core/i18n.js +83 -10
  189. package/src/core/keyboard.js +79 -8
  190. package/src/core/messages.js +376 -2
  191. package/src/core/overlay-host.js +1 -0
  192. package/src/core/storage.js +59 -6
  193. package/src/elements/define.js +178 -130
  194. package/src/elements/definitions.js +229 -0
  195. package/src/elements/kit.js +444 -0
  196. package/src/elements/reflect.js +8 -3
  197. package/src/index.js +10 -1
  198. package/src/internal/date-locale.js +11 -0
  199. package/src/internal/json-patch.js +405 -0
  200. package/src/locales/de.js +911 -0
  201. package/src/locales/en.js +2 -0
  202. package/src/locales/index.js +7 -0
  203. package/src/zeyos/calendar.js +2 -1
  204. package/src/zeyos/form.js +2 -1
  205. package/src/zeyos/launcher.js +7 -6
  206. package/src/zeyos/module-bar.js +2 -1
  207. package/src/zeyos/schema.js +37 -23
  208. package/src/zeyos/select.js +4 -3
  209. package/src/zeyos/table.js +2 -13
  210. package/src/zeyos/view.js +57 -17
  211. package/styles/core.css +11 -0
  212. package/styles/tokens/semantic.css +1 -0
  213. package/styles/zeyos.css +2 -0
  214. package/styles/zx.css +4 -8
  215. package/styles/zx.layered.css +1 -0
@@ -61,7 +61,7 @@ export type NumberFieldOptions = {
61
61
  */
62
62
  group?: boolean;
63
63
  /**
64
- * Locale for formatting; defaults to the document locale.
64
+ * Locale for formatting; defaults to the active language.
65
65
  */
66
66
  locale?: string | null;
67
67
  /**
@@ -98,7 +98,7 @@ export type NumberFieldOptions = {
98
98
  * @property {boolean} [required=false] Whether an empty value is invalid.
99
99
  * @property {string|null} [name=null] Native form field name.
100
100
  * @property {boolean} [group=false] Whether to render thousands separators while idle.
101
- * @property {string|null} [locale=null] Locale for formatting; defaults to the document locale.
101
+ * @property {string|null} [locale=null] Locale for formatting; defaults to the active language.
102
102
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
103
103
  * @property {(event: CustomEvent<{value: number|null}>) => void} [onchange] Committed-value listener.
104
104
  * @property {(event: CustomEvent<{value: number|null}>) => void} [oninput] Per-keystroke listener.
@@ -125,10 +125,16 @@ export declare class NumberField extends Component<NumberFieldOptions> {
125
125
  _precision: number;
126
126
  _min: number;
127
127
  _max: number;
128
+ _separatorLocale: string;
128
129
  _localeSeparators: {
129
130
  group: string;
130
131
  decimal: string;
132
+ minus: string;
133
+ digits: {
134
+ [k: string]: string;
135
+ };
131
136
  };
137
+ _inputLocale: string | string[];
132
138
  static cssName: string;
133
139
  /** @type {NumberFieldOptions} */
134
140
  static defaults: NumberFieldOptions;
@@ -215,12 +221,15 @@ export declare class NumberField extends Component<NumberFieldOptions> {
215
221
  */
216
222
  _stepBy(count: number): this;
217
223
  /**
218
- * The grouping and decimal separators of the configured locale.
219
- * @returns {{group: string, decimal: string}}
224
+ * The grouping and decimal separators of the effective formatting locale.
225
+ * @param {string|string[]} [locale] Locale of the text being parsed.
226
+ * @returns {{group: string, decimal: string, minus: string, digits: Record<string, string>}}
220
227
  */
221
- _separators(): {
228
+ _separators(locale?: string | string[]): {
222
229
  group: string;
223
230
  decimal: string;
231
+ minus: string;
232
+ digits: Record<string, string>;
224
233
  };
225
234
  /** @returns {void} */
226
235
  _onInput(): void;
@@ -271,12 +280,14 @@ export declare class NumberField extends Component<NumberFieldOptions> {
271
280
  * which is the best available guess for free-form typing.
272
281
  *
273
282
  * @param {unknown} raw Value to parse.
274
- * @param {{group: string, decimal: string}|null} [separators=null] Known locale separators.
283
+ * @param {{group: string, decimal: string, minus?: string, digits?: Record<string, string>}|null} [separators=null] Known locale separators, minus sign, and digit mappings.
275
284
  * @returns {number|null} The number, or null when the input is empty or unparseable.
276
285
  */
277
286
  export declare function parseNumber(raw: unknown, separators?: {
278
287
  group: string;
279
288
  decimal: string;
289
+ minus?: string;
290
+ digits?: Record<string, string>;
280
291
  } | null): number | null;
281
292
  /**
282
293
  * 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
- * Pure questionnaire logic: normalization, visibility, branch resolution, validation, and
3
- * progress. Nothing here touches the DOM, so the rules a branching questionnaire lives or dies by
4
- * are testable in Node.
5
- * @module questionnaire/items
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 predicate.
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, or a function returning one.
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?: string | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
109
+ next?: NextTarget | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
105
110
  /**
106
- * Extra validation returning an error message, or null when the answer is acceptable.
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 predicate.
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: string | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
165
+ next: NextTarget | ((answer: unknown, answers: Record<string, unknown>) => string | null) | null;
159
166
  /**
160
- * Extra validation.
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, or a name repeats.
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 item without
246
- * one is always visible, and a predicate that throws hides nothing — a broken condition must not
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` falls through to the next visible item in declaration order. A string, or a
279
- * function returning a string, names a target: when that target is currently hidden the walk
280
- * continues forward from it rather than stranding the reader on an invisible question.
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 questionnaire.
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 an answer counts as absent. An empty string, an empty array, null, and undefined
290
- * are all "no answer"; `false` and `0` are answers.
291
- * @param {unknown} value Answer value.
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 isEmptyAnswer(value: unknown): boolean;
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.