@zeyos/zx 5.5.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 (235) hide show
  1. package/CHANGELOG.md +210 -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 +711 -0
  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/approval-card/approval-card.d.ts +596 -0
  11. package/dist/types/components/avatar/avatar.d.ts +91 -4
  12. package/dist/types/components/block-view/block-view.d.ts +205 -0
  13. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  14. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  15. package/dist/types/components/calendar/calendar.d.ts +12 -4
  16. package/dist/types/components/chart/chart.d.ts +25 -13
  17. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  18. package/dist/types/components/composer/composer.d.ts +938 -0
  19. package/dist/types/components/composer/queue.d.ts +76 -0
  20. package/dist/types/components/copy/copy-button.d.ts +6 -4
  21. package/dist/types/components/copy/copy-input.d.ts +10 -6
  22. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  23. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  24. package/dist/types/components/dock/dock.d.ts +12 -3
  25. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  26. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  27. package/dist/types/components/file-item/file-item.d.ts +3 -2
  28. package/dist/types/components/file-list/file-list.d.ts +14 -8
  29. package/dist/types/components/filter/filter-model.d.ts +31 -1
  30. package/dist/types/components/filter/filter.d.ts +20 -2
  31. package/dist/types/components/finder/finder.d.ts +14 -6
  32. package/dist/types/components/flag/flag.d.ts +99 -0
  33. package/dist/types/components/grid/grid.d.ts +1 -1
  34. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  35. package/dist/types/components/launcher/launcher.d.ts +2 -0
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +17 -6
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/run-status/run-status.d.ts +393 -0
  45. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  46. package/dist/types/components/select/country.d.ts +106 -0
  47. package/dist/types/components/select/field-adapter.d.ts +2 -1
  48. package/dist/types/components/select/locale.d.ts +102 -0
  49. package/dist/types/components/select/select.d.ts +41 -2
  50. package/dist/types/components/slider/slider.d.ts +1 -0
  51. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  52. package/dist/types/components/source-list/source-list.d.ts +179 -0
  53. package/dist/types/components/split-view/split-view.d.ts +5 -3
  54. package/dist/types/components/surface/catalog.d.ts +260 -0
  55. package/dist/types/components/surface/elicit.d.ts +81 -0
  56. package/dist/types/components/surface/mcp.d.ts +165 -0
  57. package/dist/types/components/surface/schema.d.ts +314 -0
  58. package/dist/types/components/surface/stream.d.ts +118 -0
  59. package/dist/types/components/surface/surface.d.ts +718 -0
  60. package/dist/types/components/surface/text.d.ts +277 -0
  61. package/dist/types/components/surface/validate.d.ts +339 -0
  62. package/dist/types/components/table/table.d.ts +55 -3
  63. package/dist/types/components/table/window.d.ts +203 -0
  64. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  65. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  66. package/dist/types/components/tree/tree.d.ts +20 -13
  67. package/dist/types/core/component.d.ts +10 -0
  68. package/dist/types/core/date.d.ts +8 -1
  69. package/dist/types/core/dom.d.ts +1 -0
  70. package/dist/types/core/http.d.ts +10 -0
  71. package/dist/types/core/i18n.d.ts +38 -0
  72. package/dist/types/core/messages.d.ts +479 -1
  73. package/dist/types/core/storage.d.ts +7 -2
  74. package/dist/types/elements/define.d.ts +21 -46
  75. package/dist/types/elements/definitions.d.ts +147 -0
  76. package/dist/types/elements/kit.d.ts +7 -0
  77. package/dist/types/elements/reflect.d.ts +6 -3
  78. package/dist/types/index.d.ts +18 -1
  79. package/dist/types/internal/agent-model.d.ts +587 -0
  80. package/dist/types/internal/date-locale.d.ts +7 -0
  81. package/dist/types/internal/highlight.d.ts +24 -0
  82. package/dist/types/internal/json-patch.d.ts +146 -0
  83. package/dist/types/internal/presence-loop.d.ts +148 -0
  84. package/dist/types/locales/de.d.ts +13 -0
  85. package/dist/types/locales/en.d.ts +2 -0
  86. package/dist/types/locales/index.d.ts +823 -0
  87. package/dist/types/zeyos/view.d.ts +8 -1
  88. package/dist/zx-zeyos.esm.js +20505 -18748
  89. package/dist/zx-zeyos.esm.min.js +5 -5
  90. package/dist/zx.core.css +1276 -0
  91. package/dist/zx.core.min.css +1 -0
  92. package/dist/zx.css +2424 -134
  93. package/dist/zx.esm.js +46167 -28468
  94. package/dist/zx.esm.min.js +40 -8
  95. package/dist/zx.global.js +46167 -28468
  96. package/dist/zx.global.min.js +40 -8
  97. package/dist/zx.layered.css +17302 -0
  98. package/dist/zx.layered.min.css +1 -0
  99. package/dist/zx.min.css +1 -1
  100. package/docs/agent-catalog.json +12501 -0
  101. package/docs/agent-surfaces.md +340 -0
  102. package/docs/api.json +2057 -166
  103. package/docs/llms.md +1458 -58
  104. package/docs/llms.txt +38 -8
  105. package/package.json +29 -6
  106. package/src/components/account-menu/account-menu.js +6 -3
  107. package/src/components/activity-item/activity-item.js +2 -1
  108. package/src/components/activity-list/activity-list.js +16 -10
  109. package/src/components/agent-thread/ag-ui.js +1439 -0
  110. package/src/components/agent-thread/agent-thread.css +417 -0
  111. package/src/components/agent-thread/agent-thread.js +1670 -0
  112. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  113. package/src/components/app-sidebar/app-sidebar.js +18 -8
  114. package/src/components/approval-card/approval-card.css +289 -0
  115. package/src/components/approval-card/approval-card.js +1378 -0
  116. package/src/components/avatar/avatar.css +56 -1
  117. package/src/components/avatar/avatar.js +148 -26
  118. package/src/components/block-view/block-view.css +300 -0
  119. package/src/components/block-view/block-view.js +524 -0
  120. package/src/components/breadcrumb/breadcrumb.js +8 -5
  121. package/src/components/calendar/calendar-model.js +8 -2
  122. package/src/components/calendar/calendar.js +53 -18
  123. package/src/components/chart/chart.js +54 -23
  124. package/src/components/code-editor/code-editor.js +45 -8
  125. package/src/components/code-editor/field-adapter.js +1 -1
  126. package/src/components/composer/composer.css +482 -0
  127. package/src/components/composer/composer.js +1815 -0
  128. package/src/components/composer/queue.js +78 -0
  129. package/src/components/context-menu/context-menu.js +12 -1
  130. package/src/components/copy/copy-button.js +9 -7
  131. package/src/components/copy/copy-input.js +10 -6
  132. package/src/components/date-picker/date-picker.js +2 -1
  133. package/src/components/date-picker/date-range-picker.js +8 -7
  134. package/src/components/datebox/date-range-box.js +3 -9
  135. package/src/components/datebox/datebox.js +18 -21
  136. package/src/components/datebox/placeholder.js +18 -0
  137. package/src/components/dialog/dialog.js +1 -1
  138. package/src/components/dock/dock.js +34 -13
  139. package/src/components/entity-ref/entity-ref.js +16 -5
  140. package/src/components/field-upload/field-upload.js +81 -38
  141. package/src/components/file-item/file-item.js +70 -40
  142. package/src/components/file-list/file-list.js +15 -9
  143. package/src/components/filter/filter-model.js +46 -8
  144. package/src/components/filter/filter.css +3 -3
  145. package/src/components/filter/filter.js +29 -10
  146. package/src/components/filter-panel/filter-panel.js +13 -5
  147. package/src/components/finder/finder.js +50 -26
  148. package/src/components/flag/flag.css +40 -0
  149. package/src/components/flag/flag.js +177 -0
  150. package/src/components/form/form.js +1 -1
  151. package/src/components/grid/grid.js +22 -8
  152. package/src/components/kanban-view/kanban-view.js +51 -81
  153. package/src/components/launcher/launcher.js +17 -2
  154. package/src/components/list-toolbar/list-toolbar.js +2 -1
  155. package/src/components/master-panel/master-panel.js +1 -1
  156. package/src/components/menu-button/menu-button.js +4 -0
  157. package/src/components/message/message.js +3 -0
  158. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  159. package/src/components/navigation-bar/navigation-bar.js +3 -3
  160. package/src/components/number-field/number-field.js +29 -13
  161. package/src/components/prompt-starters/prompt-starters.css +91 -0
  162. package/src/components/prompt-starters/prompt-starters.js +206 -0
  163. package/src/components/prose/prose.js +14 -10
  164. package/src/components/questionnaire/conditions.js +666 -0
  165. package/src/components/questionnaire/items.js +150 -41
  166. package/src/components/questionnaire/questionnaire.js +126 -32
  167. package/src/components/rating/rating.js +5 -4
  168. package/src/components/run-status/run-status.css +208 -0
  169. package/src/components/run-status/run-status.js +782 -0
  170. package/src/components/run-trace/run-trace.css +443 -0
  171. package/src/components/run-trace/run-trace.js +1209 -0
  172. package/src/components/select/country.js +136 -0
  173. package/src/components/select/field-adapter.js +7 -2
  174. package/src/components/select/locale.js +219 -0
  175. package/src/components/select/select.css +20 -22
  176. package/src/components/select/select.js +94 -12
  177. package/src/components/sheet/sheet-stack.js +10 -1
  178. package/src/components/slider/slider.js +7 -2
  179. package/src/components/sort-control/sort-control.js +15 -5
  180. package/src/components/source-list/source-list.css +208 -0
  181. package/src/components/source-list/source-list.js +358 -0
  182. package/src/components/split-view/split-view.js +5 -3
  183. package/src/components/surface/catalog.js +1334 -0
  184. package/src/components/surface/elicit.js +107 -0
  185. package/src/components/surface/mcp.js +243 -0
  186. package/src/components/surface/schema.js +644 -0
  187. package/src/components/surface/stream.js +245 -0
  188. package/src/components/surface/surface.css +308 -0
  189. package/src/components/surface/surface.js +2291 -0
  190. package/src/components/surface/text.js +513 -0
  191. package/src/components/surface/validate.js +2218 -0
  192. package/src/components/tabbox/tabbox.js +9 -0
  193. package/src/components/table/table.css +63 -3
  194. package/src/components/table/table.js +167 -28
  195. package/src/components/table/window.js +317 -0
  196. package/src/components/toolbar/toolbar.js +12 -7
  197. package/src/components/tooltip/tooltip.css +2 -3
  198. package/src/components/tooltip/tooltip.js +32 -5
  199. package/src/components/tree/tree.js +53 -23
  200. package/src/core/component.js +25 -1
  201. package/src/core/date.js +62 -16
  202. package/src/core/dom.js +22 -2
  203. package/src/core/format.js +15 -13
  204. package/src/core/http.js +29 -20
  205. package/src/core/i18n.js +83 -10
  206. package/src/core/keyboard.js +79 -8
  207. package/src/core/messages.js +519 -2
  208. package/src/core/overlay-host.js +1 -0
  209. package/src/core/storage.js +59 -6
  210. package/src/elements/define.js +178 -130
  211. package/src/elements/definitions.js +229 -0
  212. package/src/elements/kit.js +444 -0
  213. package/src/elements/reflect.js +8 -3
  214. package/src/index.js +18 -1
  215. package/src/internal/agent-model.js +488 -0
  216. package/src/internal/date-locale.js +11 -0
  217. package/src/internal/highlight.js +104 -0
  218. package/src/internal/json-patch.js +405 -0
  219. package/src/internal/presence-loop.js +343 -0
  220. package/src/locales/de.js +911 -0
  221. package/src/locales/en.js +2 -0
  222. package/src/locales/index.js +7 -0
  223. package/src/zeyos/calendar.js +2 -1
  224. package/src/zeyos/form.js +2 -1
  225. package/src/zeyos/launcher.js +7 -6
  226. package/src/zeyos/module-bar.js +2 -1
  227. package/src/zeyos/schema.js +37 -23
  228. package/src/zeyos/select.js +4 -3
  229. package/src/zeyos/table.js +2 -13
  230. package/src/zeyos/view.js +57 -17
  231. package/styles/core.css +11 -0
  232. package/styles/tokens/semantic.css +1 -0
  233. package/styles/zeyos.css +2 -0
  234. package/styles/zx.css +11 -8
  235. package/styles/zx.layered.css +1 -0
@@ -463,7 +463,9 @@ export type KanbanViewOptions = {
463
463
  count: number;
464
464
  }) => Node | null | undefined) | null;
465
465
  /**
466
- * Overrides for every visible and announced string.
466
+ * Per-instance overrides of the board's text. Each key is
467
+ * the part after `kanbanView.` in the message catalogue, where every visible and announced string
468
+ * lives, and a value may reorder or drop the named placeholders.
467
469
  */
468
470
  labels?: Record<string, string>;
469
471
  /**
@@ -495,9 +497,10 @@ export type KanbanViewOptions = {
495
497
  */
496
498
  variant?: 'outlined' | 'raised' | 'filled';
497
499
  /**
498
- * Accessible board label.
500
+ * Accessible board label, by default the `kanbanView.label` message
501
+ * ("Kanban board"). Null leaves the board unnamed.
499
502
  */
500
- label?: string;
503
+ label?: string | null;
501
504
  onrecordmove?: (event: CustomEvent<Record<string, unknown>>) => void;
502
505
  onmovereject?: (event: CustomEvent<Record<string, unknown>>) => void;
503
506
  onrecordaction?: (event: CustomEvent<Record<string, unknown>>) => void;
@@ -566,66 +569,6 @@ export type KanbanCardSources = {
566
569
  */
567
570
  any: boolean;
568
571
  };
569
- /**
570
- * Every user-visible and announced string, so a host can translate the board without patching it.
571
- * Values run through `printf`, so named placeholders may be reordered or dropped by a translation.
572
- */
573
- declare const DEFAULT_LABELS: Readonly<{
574
- fields: "Fields";
575
- search: "Search board";
576
- searchPlaceholder: "Search cards";
577
- clearSearch: "Clear search";
578
- searchSummary: "%count% of %total% cards match.";
579
- undo: "Undo";
580
- redo: "Redo";
581
- add: "Add card";
582
- addTo: "Add card to %target%";
583
- move: "Move %name%";
584
- moveMultiple: "Move %count% selected cards";
585
- collapseColumn: "Collapse column %label%";
586
- expandColumn: "Expand column %label%";
587
- collapseLane: "Collapse swim lane %label%";
588
- expandLane: "Expand swim lane %label%";
589
- count: "%count% records";
590
- countFiltered: "%count% of %total% records";
591
- countLimit: "%count% records, work-in-progress limit %limit%";
592
- countLimitInLane: "%count% records in this lane, %total% of work-in-progress limit %limit% in the column";
593
- empty: "No records";
594
- columnEmpty: "Drop a card here";
595
- identifier: "Record";
596
- priorityLabel: "Priority";
597
- statusLabel: "Status";
598
- progress: "Progress";
599
- progressValue: "%percent%%";
600
- assignees: "Assigned to %names%";
601
- assigneeOverflow: "+%count%";
602
- selected: "Selected";
603
- notSelected: "Not selected";
604
- noMatches: "No cards match the current search.";
605
- record: "record";
606
- grabbed: "Grabbed %name%. Use left and right for columns, up and down for position, and Alt plus up or down for swim lanes.";
607
- grabbedMultiple: "Grabbed %count% cards. Use left and right for columns, up and down for position, and Alt plus up or down for swim lanes.";
608
- target: "Target %target%, position %position% of %total%.";
609
- moved: "Moved %name% to %target%.%wip%";
610
- movedMultiple: "Moved %count% cards to %target%.%wip%";
611
- moveRequested: "Move requested for %name% to %target%.%wip%";
612
- moveCanceled: "Move canceled for %name%.";
613
- moveCanceledPlain: "Move canceled.";
614
- limitReached: " Work-in-progress limit %limit% reached.";
615
- limitExceeded: " Work-in-progress limit %limit% exceeded.";
616
- rejectAccept: "Move rejected: %target% does not accept %name%.";
617
- rejectTransition: "Move rejected: %target% does not accept cards from %origin%.";
618
- rejectWip: "Move rejected: %target% is at its work-in-progress limit of %limit%.";
619
- rejectDestination: "Move rejected: the destination is not available.";
620
- rejectGrouping: "Move rejected: callback grouping requires external move mode.";
621
- undone: "Move undone.";
622
- redone: "Move redone.";
623
- nothingToUndo: "Nothing to undo.";
624
- nothingToRedo: "Nothing to redo.";
625
- menuMoveTo: "Move to %target%";
626
- menuMoveToLane: "Move to lane %target%";
627
- dragPreview: "%count% cards";
628
- }>;
629
572
  /**
630
573
  * A field consumed by the card head or footer — the `identifier`, `status`, `priority`,
631
574
  * `progress`, or `assignees` source — is dropped from the shared metadata list so the same value
@@ -1283,11 +1226,11 @@ export declare class KanbanView extends RecordView {
1283
1226
  _wipAnnouncement(evaluation: KanbanMoveEvaluation): string;
1284
1227
  /**
1285
1228
  * Resolves one localizable string.
1286
- * @param {keyof typeof DEFAULT_LABELS|string} key Label key.
1229
+ * @param {string} key Label key.
1287
1230
  * @param {Record<string, unknown>} [args] Placeholder values.
1288
1231
  * @returns {string} Resolved text.
1289
1232
  */
1290
- _text(key: keyof typeof DEFAULT_LABELS | string, args?: Record<string, unknown>): string;
1233
+ _text(key: string, args?: Record<string, unknown>): string;
1291
1234
  /** @param {string} message @returns {void} */
1292
1235
  _announce(message: string): void;
1293
1236
  /** @param {string} reason @returns {void} */
@@ -1349,7 +1292,6 @@ export declare function reorderKanbanData(records: KanbanRecord[], id: unknown,
1349
1292
  from: KanbanMovePoint;
1350
1293
  to: KanbanMovePoint;
1351
1294
  } | null;
1352
- export {};
1353
1295
  /**
1354
1296
  * Record movement event emitted before a local commit or external request. `record`, `id`, and
1355
1297
  * `from` describe the primary record; `records`, `ids`, and `moves` describe the whole atomic move.
@@ -423,6 +423,8 @@ export declare class Launcher extends Component<LauncherOptions> {
423
423
  _announcePending: boolean;
424
424
  _announceToggle: boolean;
425
425
  _destroyed: boolean;
426
+ _presentation: number;
427
+ _closingPresentations: any[];
426
428
  _label: string;
427
429
  _placeholder: string;
428
430
  static cssName: string;
@@ -9,9 +9,10 @@ export type MultiValueEditorOptions = {
9
9
  */
10
10
  options?: unknown[] | Record<string, string> | null;
11
11
  /**
12
- * Add-row button text.
12
+ * Add-row button text; null reads the `multiValueEditor.add`
13
+ * message ("Add value").
13
14
  */
14
- addLabel?: string;
15
+ addLabel?: string | null;
15
16
  /**
16
17
  * Reordering affordances each row gets:
17
18
  * a drag handle, the up/down buttons, both, or neither.
@@ -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[];