@zeyos/zx 5.6.0 → 5.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (227) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  11. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  12. package/dist/types/components/calendar/calendar.d.ts +12 -4
  13. package/dist/types/components/chart/chart.d.ts +25 -13
  14. package/dist/types/components/checklist/checklist.d.ts +29 -0
  15. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  16. package/dist/types/components/composer/composer.d.ts +206 -4
  17. package/dist/types/components/composer/queue.d.ts +76 -0
  18. package/dist/types/components/copy/copy-button.d.ts +6 -4
  19. package/dist/types/components/copy/copy-input.d.ts +10 -6
  20. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  21. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  22. package/dist/types/components/dialog/dialog.d.ts +2 -2
  23. package/dist/types/components/dock/dock.d.ts +12 -3
  24. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  25. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  26. package/dist/types/components/file-item/file-item.d.ts +3 -2
  27. package/dist/types/components/file-list/file-list.d.ts +14 -8
  28. package/dist/types/components/filter/filter-model.d.ts +31 -1
  29. package/dist/types/components/filter/filter.d.ts +20 -2
  30. package/dist/types/components/finder/finder.d.ts +14 -6
  31. package/dist/types/components/flag/flag.d.ts +99 -0
  32. package/dist/types/components/grid/grid.d.ts +1 -1
  33. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  34. package/dist/types/components/launcher/launcher.d.ts +2 -0
  35. package/dist/types/components/modal/modal.d.ts +34 -8
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +41 -7
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/select/country.d.ts +106 -0
  45. package/dist/types/components/select/field-adapter.d.ts +2 -1
  46. package/dist/types/components/select/locale.d.ts +102 -0
  47. package/dist/types/components/select/select.d.ts +41 -2
  48. package/dist/types/components/sheet/sheet.d.ts +2 -2
  49. package/dist/types/components/slider/slider.d.ts +1 -0
  50. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  51. package/dist/types/components/source-list/source-list.d.ts +7 -5
  52. package/dist/types/components/split-view/split-view.d.ts +5 -3
  53. package/dist/types/components/surface/catalog.d.ts +260 -0
  54. package/dist/types/components/surface/elicit.d.ts +81 -0
  55. package/dist/types/components/surface/mcp.d.ts +165 -0
  56. package/dist/types/components/surface/schema.d.ts +314 -0
  57. package/dist/types/components/surface/stream.d.ts +118 -0
  58. package/dist/types/components/surface/surface.d.ts +718 -0
  59. package/dist/types/components/surface/text.d.ts +277 -0
  60. package/dist/types/components/surface/validate.d.ts +339 -0
  61. package/dist/types/components/table/table.d.ts +55 -3
  62. package/dist/types/components/table/window.d.ts +203 -0
  63. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  64. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  65. package/dist/types/components/tree/tree.d.ts +20 -13
  66. package/dist/types/core/component.d.ts +10 -0
  67. package/dist/types/core/date.d.ts +8 -1
  68. package/dist/types/core/dom.d.ts +15 -0
  69. package/dist/types/core/http.d.ts +10 -0
  70. package/dist/types/core/i18n.d.ts +38 -0
  71. package/dist/types/core/messages.d.ts +344 -1
  72. package/dist/types/core/storage.d.ts +7 -2
  73. package/dist/types/elements/define.d.ts +21 -46
  74. package/dist/types/elements/definitions.d.ts +147 -0
  75. package/dist/types/elements/kit.d.ts +7 -0
  76. package/dist/types/elements/reflect.d.ts +6 -3
  77. package/dist/types/index.d.ts +10 -1
  78. package/dist/types/internal/date-locale.d.ts +7 -0
  79. package/dist/types/internal/json-patch.d.ts +146 -0
  80. package/dist/types/locales/de.d.ts +13 -0
  81. package/dist/types/locales/en.d.ts +2 -0
  82. package/dist/types/locales/index.d.ts +823 -0
  83. package/dist/types/zeyos/view.d.ts +8 -1
  84. package/dist/zx-zeyos.esm.js +16852 -15131
  85. package/dist/zx-zeyos.esm.min.js +5 -5
  86. package/dist/zx.core.css +1276 -0
  87. package/dist/zx.core.min.css +1 -0
  88. package/dist/zx.css +520 -143
  89. package/dist/zx.esm.js +40940 -29684
  90. package/dist/zx.esm.min.js +36 -23
  91. package/dist/zx.global.js +40940 -29684
  92. package/dist/zx.global.min.js +36 -23
  93. package/dist/zx.layered.css +17315 -0
  94. package/dist/zx.layered.min.css +1 -0
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +12501 -0
  97. package/docs/agent-surfaces.md +340 -0
  98. package/docs/api.json +909 -137
  99. package/docs/llms.md +1046 -80
  100. package/docs/llms.txt +30 -9
  101. package/package.json +29 -6
  102. package/src/components/account-menu/account-menu.js +6 -3
  103. package/src/components/activity-item/activity-item.js +2 -1
  104. package/src/components/activity-list/activity-list.js +16 -10
  105. package/src/components/agent-thread/ag-ui.js +1439 -0
  106. package/src/components/agent-thread/agent-thread.js +359 -54
  107. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  108. package/src/components/app-sidebar/app-sidebar.js +18 -8
  109. package/src/components/approval-card/approval-card.js +3 -2
  110. package/src/components/block-view/block-view.js +7 -6
  111. package/src/components/breadcrumb/breadcrumb.js +8 -5
  112. package/src/components/button/button.css +24 -11
  113. package/src/components/calendar/calendar-model.js +8 -2
  114. package/src/components/calendar/calendar.js +53 -18
  115. package/src/components/chart/chart.js +54 -23
  116. package/src/components/checklist/checklist.css +9 -1
  117. package/src/components/checklist/checklist.js +59 -3
  118. package/src/components/checklist/field-adapter.js +2 -11
  119. package/src/components/code-editor/code-editor.js +45 -8
  120. package/src/components/code-editor/field-adapter.js +1 -1
  121. package/src/components/composer/composer.css +80 -1
  122. package/src/components/composer/composer.js +390 -16
  123. package/src/components/composer/queue.js +78 -0
  124. package/src/components/context-menu/context-menu.js +12 -1
  125. package/src/components/copy/copy-button.js +9 -7
  126. package/src/components/copy/copy-input.js +10 -6
  127. package/src/components/date-picker/date-picker.js +2 -1
  128. package/src/components/date-picker/date-range-picker.js +8 -7
  129. package/src/components/datebox/date-range-box.js +3 -9
  130. package/src/components/datebox/datebox.js +18 -21
  131. package/src/components/datebox/placeholder.js +18 -0
  132. package/src/components/dialog/dialog.js +4 -5
  133. package/src/components/dock/dock.js +34 -13
  134. package/src/components/entity-ref/entity-ref.js +16 -5
  135. package/src/components/field-upload/field-upload.js +81 -38
  136. package/src/components/file-item/file-item.js +70 -40
  137. package/src/components/file-list/file-list.js +15 -9
  138. package/src/components/filter/filter-model.js +46 -8
  139. package/src/components/filter/filter.css +3 -3
  140. package/src/components/filter/filter.js +29 -10
  141. package/src/components/filter-panel/filter-panel.js +13 -5
  142. package/src/components/finder/finder.js +50 -26
  143. package/src/components/flag/flag.css +40 -0
  144. package/src/components/flag/flag.js +177 -0
  145. package/src/components/form/form.js +1 -1
  146. package/src/components/grid/grid.js +22 -8
  147. package/src/components/kanban-view/kanban-view.js +51 -81
  148. package/src/components/launcher/launcher.js +17 -2
  149. package/src/components/list-toolbar/list-toolbar.js +2 -1
  150. package/src/components/master-panel/master-panel.js +1 -1
  151. package/src/components/menu-button/menu-button.js +4 -0
  152. package/src/components/message/message.js +3 -0
  153. package/src/components/modal/modal.js +62 -8
  154. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  155. package/src/components/navigation-bar/navigation-bar.js +3 -3
  156. package/src/components/number-field/number-field.js +98 -29
  157. package/src/components/prompt-starters/prompt-starters.css +91 -0
  158. package/src/components/prompt-starters/prompt-starters.js +206 -0
  159. package/src/components/prose/prose.js +14 -10
  160. package/src/components/questionnaire/conditions.js +666 -0
  161. package/src/components/questionnaire/items.js +150 -41
  162. package/src/components/questionnaire/questionnaire.js +126 -32
  163. package/src/components/rating/rating.js +5 -4
  164. package/src/components/run-status/run-status.js +2 -2
  165. package/src/components/select/country.js +136 -0
  166. package/src/components/select/field-adapter.js +7 -2
  167. package/src/components/select/locale.js +219 -0
  168. package/src/components/select/select.css +20 -22
  169. package/src/components/select/select.js +94 -12
  170. package/src/components/sheet/sheet-stack.js +10 -1
  171. package/src/components/sheet/sheet.js +12 -5
  172. package/src/components/slider/slider.js +7 -2
  173. package/src/components/sort-control/sort-control.js +15 -5
  174. package/src/components/source-list/source-list.js +7 -4
  175. package/src/components/split-view/split-view.js +5 -3
  176. package/src/components/surface/catalog.js +1334 -0
  177. package/src/components/surface/elicit.js +107 -0
  178. package/src/components/surface/mcp.js +243 -0
  179. package/src/components/surface/schema.js +644 -0
  180. package/src/components/surface/stream.js +245 -0
  181. package/src/components/surface/surface.css +308 -0
  182. package/src/components/surface/surface.js +2291 -0
  183. package/src/components/surface/text.js +513 -0
  184. package/src/components/surface/validate.js +2218 -0
  185. package/src/components/tabbox/tabbox.js +9 -0
  186. package/src/components/table/table.css +63 -3
  187. package/src/components/table/table.js +167 -28
  188. package/src/components/table/window.js +317 -0
  189. package/src/components/toolbar/toolbar.js +12 -7
  190. package/src/components/tooltip/tooltip.css +2 -3
  191. package/src/components/tooltip/tooltip.js +32 -5
  192. package/src/components/tree/tree.js +53 -23
  193. package/src/core/component.js +25 -1
  194. package/src/core/date.js +62 -16
  195. package/src/core/dom.js +67 -4
  196. package/src/core/format.js +15 -13
  197. package/src/core/http.js +29 -20
  198. package/src/core/i18n.js +83 -10
  199. package/src/core/icons.js +13 -2
  200. package/src/core/keyboard.js +79 -8
  201. package/src/core/messages.js +376 -2
  202. package/src/core/overlay-host.js +1 -0
  203. package/src/core/position.js +3 -2
  204. package/src/core/storage.js +59 -6
  205. package/src/elements/define.js +178 -130
  206. package/src/elements/definitions.js +229 -0
  207. package/src/elements/kit.js +444 -0
  208. package/src/elements/reflect.js +8 -3
  209. package/src/index.js +10 -1
  210. package/src/internal/date-locale.js +11 -0
  211. package/src/internal/json-patch.js +405 -0
  212. package/src/locales/de.js +911 -0
  213. package/src/locales/en.js +2 -0
  214. package/src/locales/index.js +7 -0
  215. package/src/zeyos/calendar.js +2 -1
  216. package/src/zeyos/form.js +2 -1
  217. package/src/zeyos/launcher.js +7 -6
  218. package/src/zeyos/module-bar.js +2 -1
  219. package/src/zeyos/schema.js +37 -23
  220. package/src/zeyos/select.js +4 -3
  221. package/src/zeyos/table.js +2 -13
  222. package/src/zeyos/view.js +57 -17
  223. package/styles/core.css +11 -0
  224. package/styles/tokens/semantic.css +1 -0
  225. package/styles/zeyos.css +2 -0
  226. package/styles/zx.css +4 -8
  227. package/styles/zx.layered.css +1 -0
@@ -75,9 +75,10 @@ export type FileItemOptions = {
75
75
  */
76
76
  wrap?: boolean;
77
77
  /**
78
- * Accessible name for secondary actions.
78
+ * Accessible name for secondary actions; null reads the
79
+ * `fileItem.actions` message ("File actions").
79
80
  */
80
- actionsLabel?: string;
81
+ actionsLabel?: string | null;
81
82
  /**
82
83
  * Locale passed to `formatFileSize`.
83
84
  */
@@ -8,9 +8,10 @@ export type FileListOptions = {
8
8
  */
9
9
  items?: FileItemOptions[];
10
10
  /**
11
- * Accessible collection name.
11
+ * Accessible collection name; null reads the `fileList.label`
12
+ * message ("Files").
12
13
  */
13
- label?: string;
14
+ label?: string | null;
14
15
  /**
15
16
  * Whether initial or incremental files are loading.
16
17
  */
@@ -20,11 +21,13 @@ export type FileListOptions = {
20
21
  */
21
22
  loadingCount?: number;
22
23
  /**
23
- * Loading status text.
24
+ * Loading status text, by default the `fileList.loading`
25
+ * message ("Loading files"). Null shows none.
24
26
  */
25
- loadingText?: string;
27
+ loadingText?: string | null;
26
28
  /**
27
- * Empty-state content.
29
+ * Empty-state content, by default the
30
+ * `fileList.empty` message ("No files"). Null shows none.
28
31
  */
29
32
  emptyText?: string | number | Node | Component | null;
30
33
  /**
@@ -60,11 +63,14 @@ export type FileListOptions = {
60
63
  /**
61
64
  * @typedef {Object} FileListOptions
62
65
  * @property {FileItemOptions[]} [items=[]] Initial files in host-supplied order.
63
- * @property {string} [label='Files'] Accessible collection name.
66
+ * @property {string|null} [label=null] Accessible collection name; null reads the `fileList.label`
67
+ * message ("Files").
64
68
  * @property {boolean} [loading=false] Whether initial or incremental files are loading.
65
69
  * @property {number} [loadingCount=3] Placeholder rows shown for an empty loading list.
66
- * @property {string} [loadingText='Loading files'] Loading status text.
67
- * @property {string|number|Node|Component|null} [emptyText='No files'] Empty-state content.
70
+ * @property {string|null} [loadingText] Loading status text, by default the `fileList.loading`
71
+ * message ("Loading files"). Null shows none.
72
+ * @property {string|number|Node|Component|null} [emptyText] Empty-state content, by default the
73
+ * `fileList.empty` message ("No files"). Null shows none.
68
74
  * @property {(event: CustomEvent<{id: unknown, index: number, file: Readonly<FileItemState>, href: string, event: MouseEvent}>) => void} [onactivate]
69
75
  * Preventable native-file-link listener.
70
76
  * @property {(event: CustomEvent<{id: string, fileId: unknown, index: number, action: object, file: Readonly<FileItemState>, event: MouseEvent}>) => void} [onaction]
@@ -37,6 +37,7 @@ export type FilterValidationError = {
37
37
  code: string;
38
38
  message: string;
39
39
  };
40
+ export type FilterText = (key: string, ...args: unknown[]) => string;
40
41
  /** @typedef {null|boolean|number|string|FilterJson[]|{[key:string]: FilterJson}} FilterJson */
41
42
  /** @typedef {{kind:'condition', id:string, field:string, operator:string, value:FilterJson}} FilterCondition */
42
43
  /** @typedef {{kind:'group', id:string, logic:'and'|'or', children:FilterNode[]}} FilterGroup */
@@ -45,8 +46,25 @@ export type FilterValidationError = {
45
46
  /** @typedef {{id:string, label:string, arity:'none'|'single'|'pair'|'many', types:string[]}} FilterOperator */
46
47
  /** @typedef {{id:string, label:string, type:string, operators?:string[], defaultOperator?:string}} FilterField */
47
48
  /** @typedef {{nodeId:string, code:string, message:string}} FilterValidationError */
48
- /** Core operators are application-neutral IDs; an adapter maps them to executable query syntax. */
49
+ /** @typedef {(key:string, ...args:unknown[]) => string} FilterText Resolves a message; a component passes its `msg()`. */
50
+ /**
51
+ * Core operators are application-neutral IDs; an adapter maps them to executable query syntax. The
52
+ * labels here are English data that hosts read. What `Filter` shows for a built-in is the
53
+ * `filter.op.<id>` message, see {@link filterOperatorLabel}.
54
+ */
49
55
  export declare const filterOperators: readonly FilterOperator[];
56
+ /** The catalogue, for code that runs without a component. @type {FilterText} */
57
+ export declare const filterText: FilterText;
58
+ /**
59
+ * The name to show for an operator. A built-in reads its `filter.op.<id>` message. A host-supplied
60
+ * operator keeps its own label, or its lack of one, unless that label is the built-in text for its
61
+ * ID: labels are compared rather than objects so that `operators: filterOperators`, or a spread of a
62
+ * built-in that changes something else, translates too.
63
+ * @param {FilterOperator} operator
64
+ * @param {FilterText} [text=filterText]
65
+ * @returns {string}
66
+ */
67
+ export declare function filterOperatorLabel(operator: FilterOperator, text?: FilterText): string;
50
68
  /** @returns {FilterAst} */
51
69
  export declare function emptyFilterAst(): FilterAst;
52
70
  /** @param {Partial<FilterCondition>} [initial={}] @returns {FilterCondition} */
@@ -85,3 +103,15 @@ export declare function validateFilterAst(ast: FilterAst, fields: FilterField[],
85
103
  valid: boolean;
86
104
  errors: FilterValidationError[];
87
105
  };
106
+ /**
107
+ * {@link validateFilterAst} with the messages of a component, not exported from the package.
108
+ * @param {FilterAst} ast
109
+ * @param {FilterField[]} fields
110
+ * @param {FilterOperator[]} operators
111
+ * @param {FilterText} [text=filterText] Resolves the messages of the errors.
112
+ * @returns {{valid:boolean, errors:FilterValidationError[]}}
113
+ */
114
+ export declare function checkFilterAst(ast: FilterAst, fields: FilterField[], operators: FilterOperator[], text?: FilterText): {
115
+ valid: boolean;
116
+ errors: FilterValidationError[];
117
+ };
@@ -196,6 +196,21 @@ export type FilterValueMessages = {
196
196
  };
197
197
  /** Units a relative date span may be counted in, in the order the editor offers them. */
198
198
  export declare const RELATIVE_DATE_UNITS: readonly string[];
199
+ /** What an empty picker asks for, by the part of the condition it sets. */
200
+ declare const PART_PROMPTS: Readonly<{
201
+ field: {
202
+ key: string;
203
+ fallback: string;
204
+ };
205
+ operator: {
206
+ key: string;
207
+ fallback: string;
208
+ };
209
+ value: {
210
+ key: string;
211
+ fallback: string;
212
+ };
213
+ }>;
199
214
  /**
200
215
  * Backend-neutral dynamic filter expression editor.
201
216
  * @fires Filter#change
@@ -246,6 +261,8 @@ export declare class Filter extends Component<FilterOptions> {
246
261
  debounce?: number;
247
262
  }[];
248
263
  _operators: any[];
264
+ /** @type {import('./filter-model.js').FilterText} */
265
+ _text: import('./filter-model.js').FilterText;
249
266
  _readonly: boolean;
250
267
  _disabled: boolean;
251
268
  _async: Map<any, any>;
@@ -336,14 +353,14 @@ export declare class Filter extends Component<FilterOptions> {
336
353
  * @param {unknown} value Selected value.
337
354
  * @param {string} label Accessible name.
338
355
  * @param {string} nodeId Condition ID.
339
- * @param {string} part Focus target name.
356
+ * @param {keyof typeof PART_PROMPTS} part Focus target name, which also picks the placeholder.
340
357
  * @param {(value:unknown)=>void} changed Selection handler.
341
358
  * @returns {HTMLElement} Picker root.
342
359
  */
343
360
  _searchSelect(items: Array<{
344
361
  value: unknown;
345
362
  label: string;
346
- }>, value: unknown, label: string, nodeId: string, part: string, changed: (value: unknown) => void): HTMLElement;
363
+ }>, value: unknown, label: string, nodeId: string, part: keyof typeof PART_PROMPTS, changed: (value: unknown) => void): HTMLElement;
347
364
  /**
348
365
  * Owns a themed multi-value picker for a many-valued operator on a field with static choices:
349
366
  * the chosen values as removable tags, the rest in a searchable list. It writes the value without
@@ -508,3 +525,4 @@ export declare function withFilterMessage(msg: Record<string, any> | null | unde
508
525
  * @returns {Record<string,string>|null} Actionable validation error, or null.
509
526
  */
510
527
  export declare function rootLogicError(value: FilterAst, logic: 'and' | 'or' | null): Record<string, string> | null;
528
+ export {};
@@ -50,9 +50,10 @@ export type FinderOptions = {
50
50
  */
51
51
  renderItem?: ((node: TreeNode) => Node | string) | null;
52
52
  /**
53
- * Text shown in an empty column.
53
+ * Text shown in an empty column, by default the `finder.noItems`
54
+ * message ("Empty"). Null shows none.
54
55
  */
55
- emptyText?: string;
56
+ emptyText?: string | null;
56
57
  /**
57
58
  * Localized messages.
58
59
  */
@@ -96,7 +97,8 @@ export type FinderOptions = {
96
97
  * @property {number|string|null} [height=320] Component height in pixels or any CSS length.
97
98
  * @property {boolean} [icons=true] Whether to render folder and file icons.
98
99
  * @property {((node: TreeNode) => Node|string)|null} [renderItem=null] Row renderer.
99
- * @property {string} [emptyText='Empty'] Text shown in an empty column.
100
+ * @property {string|null} [emptyText] Text shown in an empty column, by default the `finder.noItems`
101
+ * message ("Empty"). Null shows none.
100
102
  * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
101
103
  * @property {(event: CustomEvent<{path: unknown[], nodes: TreeNode[], node: TreeNode|null}>) => void} [onchange] Path listener.
102
104
  * @property {(event: CustomEvent<{node: TreeNode, id: unknown}>) => void} [onactivate] Activation listener.
@@ -123,8 +125,13 @@ export declare class Finder extends Component<FinderOptions> {
123
125
  owner: TreeNode | null;
124
126
  }[];
125
127
  _activeColumn: any;
126
- /** @type {Map<unknown, Promise<void>>} In-flight lazy loads, keyed by node ID. */
127
- _loading: Map<unknown, Promise<void>>;
128
+ /** @type {Map<unknown, Promise<{children?: TreeNode[], error?: Error}>>} In-flight lazy loads, keyed by node ID. */
129
+ _loading: Map<unknown, Promise<{
130
+ children?: TreeNode[];
131
+ error?: Error;
132
+ }>>;
133
+ _loadGeneration: number;
134
+ _destroyed: boolean;
128
135
  _pathSequence: any;
129
136
  _createdRoot: boolean;
130
137
  _snapshot: import("../../core/dom.js").TargetSnapshot;
@@ -226,9 +233,10 @@ export declare class Finder extends Component<FinderOptions> {
226
233
  /**
227
234
  * Loads a branch's children through the configured loader, once.
228
235
  * @param {TreeNode} node Branch node.
236
+ * @param {number} sequence Navigation that requested the children.
229
237
  * @returns {Promise<void>}
230
238
  */
231
- _ensureChildren(node: TreeNode): Promise<void>;
239
+ _ensureChildren(node: TreeNode, sequence: number): Promise<void>;
232
240
  /** @param {number} column @returns {TreeNode[]} */
233
241
  _columnNodes(column: number): TreeNode[];
234
242
  /** @param {Element} row @returns {{column: number, index: number}} */
@@ -0,0 +1,99 @@
1
+ export type FlagKind = 'auto' | 'emoji' | 'code' | 'image';
2
+ export type FlagOptions = {
3
+ /**
4
+ * Drawing; `src` implies `image`.
5
+ */
6
+ kind?: FlagKind;
7
+ /**
8
+ * Image URL. `{code}` in it is replaced by the lower-case region
9
+ * code and `{CODE}` by the upper-case one, so `'/flags/{code}.svg'` serves a whole flag set.
10
+ */
11
+ src?: string | null;
12
+ /**
13
+ * Text of the code chip, by default the region code. A chip
14
+ * also stands in for a flag when there is no valid region, as for a language without a country.
15
+ */
16
+ text?: string | null;
17
+ /**
18
+ * Accessible name. Without one the flag is decorative
19
+ * (`aria-hidden`) and must sit beside text that names the country or language.
20
+ */
21
+ label?: string | null;
22
+ };
23
+ export type FlagMode = 'auto' | 'emoji' | 'code' | 'none' | ((region: string | null, item: Record<string, any>) => Node | string | null);
24
+ /**
25
+ * How a flag is drawn: `emoji` is the platform's flag glyph, `code` a small chip carrying the code
26
+ * as text, `image` an `<img>` from a URL the application supplies, and `auto` the emoji where the
27
+ * platform draws flag glyphs and the chip where it does not.
28
+ * @typedef {'auto'|'emoji'|'code'|'image'} FlagKind
29
+ */
30
+ /**
31
+ * @typedef {Object} FlagOptions
32
+ * @property {FlagKind} [kind='auto'] Drawing; `src` implies `image`.
33
+ * @property {string|null} [src=null] Image URL. `{code}` in it is replaced by the lower-case region
34
+ * code and `{CODE}` by the upper-case one, so `'/flags/{code}.svg'` serves a whole flag set.
35
+ * @property {string|null} [text=null] Text of the code chip, by default the region code. A chip
36
+ * also stands in for a flag when there is no valid region, as for a language without a country.
37
+ * @property {string|null} [label=null] Accessible name. Without one the flag is decorative
38
+ * (`aria-hidden`) and must sit beside text that names the country or language.
39
+ */
40
+ /**
41
+ * What a picker draws in front of each choice: a {@link FlagKind} other than `image`, `none` for
42
+ * nothing, or a function returning the content itself.
43
+ * @typedef {'auto'|'emoji'|'code'|'none'|((region: string|null, item: Record<string, any>) => Node|string|null)} FlagMode
44
+ */
45
+ /**
46
+ * Every officially assigned ISO 3166-1 alpha-2 code, and `XK` (Kosovo), which is user-assigned but
47
+ * in common use, in alphabetical order. `Select.country()` lists these when given no `countries`.
48
+ * @type {ReadonlyArray<string>}
49
+ */
50
+ export declare const COUNTRY_CODES: ReadonlyArray<string>;
51
+ /**
52
+ * Settles a region code: two ASCII letters, upper-cased. Anything else — a numeric UN M.49 region
53
+ * such as `419`, an empty value — is not a flag and reads as null.
54
+ * @param {unknown} code Candidate region code.
55
+ * @returns {string|null}
56
+ */
57
+ export declare function normalizeRegion(code: unknown): string | null;
58
+ /**
59
+ * Spells a region as its flag emoji: the pair of regional indicator symbols the platform's emoji
60
+ * font draws as a flag (`'DE'` → 🇩🇪). Where the font has no flags the pair shows as two letters.
61
+ * @param {unknown} code ISO 3166-1 alpha-2 region code.
62
+ * @returns {string} The emoji, or `''` when the code is not two letters.
63
+ */
64
+ export declare function flagEmoji(code: unknown): string;
65
+ /**
66
+ * Reports whether this platform draws flag emoji as flags. Windows, for one, draws the regional
67
+ * indicators as plain letters. The test draws a flag into a small canvas and looks for colour,
68
+ * which costs a little each call, so a picker asks once and keeps the answer.
69
+ * @param {Document|null} [doc=globalThis.document] Document to test in.
70
+ * @returns {boolean} False without a document or a 2D canvas, as in Node.
71
+ */
72
+ export declare function supportsFlagEmoji(doc?: Document | null): boolean;
73
+ /**
74
+ * Fills a flag URL template: `{code}` becomes the lower-case region code, `{CODE}` the upper-case.
75
+ * @param {string} template URL template, such as `'/flags/{code}.svg'`.
76
+ * @param {string} region Two-letter region code.
77
+ * @returns {string}
78
+ */
79
+ export declare function flagSource(template: string, region: string): string;
80
+ /**
81
+ * Draws a country flag, for a picker row, a table cell, or a profile — so a country reads the same
82
+ * wherever it appears. The flag is decorative unless `label` is given: put the country's name
83
+ * beside it.
84
+ *
85
+ * Zx ships no flag artwork. The default is the platform's flag emoji, and a code chip where the
86
+ * platform has none; pass `src` to draw from any flag set the application serves.
87
+ *
88
+ * @param {string|null|undefined} code ISO 3166-1 alpha-2 region code (`'DE'`, `'at'`).
89
+ * @param {FlagOptions} [options={}] Drawing and accessible-name options.
90
+ * @returns {HTMLSpanElement} A `.zx-flag` element whose `data-kind` says how it was drawn.
91
+ */
92
+ export declare function flag(code: string | null | undefined, options?: FlagOptions): HTMLSpanElement;
93
+ /**
94
+ * Builds the function a picker draws its flags with, resolving `auto` once rather than per row.
95
+ * @param {FlagMode} mode What to draw.
96
+ * @param {string|null} template Flag URL template; wins over the emoji and chip modes.
97
+ * @returns {(region: string|null, text: string, item: Record<string, any>) => Node|string|null}
98
+ */
99
+ export declare function flagRenderer(mode: FlagMode, template: string | null): (region: string | null, text: string, item: Record<string, any>) => Node | string | null;
@@ -162,7 +162,7 @@ export declare function isBillingLine(row: BillingRow, fields?: BillingFields):
162
162
  * @param {{units: unknown, currencies: unknown, currency: string, locale?: string, decimals: number, columnOverrides: Record<string, object>}} options Formatting/editor options.
163
163
  * @returns {import('../table/table.js').TableColumn[]}
164
164
  */
165
- export declare function billingColumns(fields: BillingFields, { units, currencies, currency, locale, decimals, columnOverrides }: {
165
+ export declare function billingColumns(fields: BillingFields, options: {
166
166
  units: unknown;
167
167
  currencies: unknown;
168
168
  currency: string;
@@ -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;
@@ -15,7 +15,8 @@ export type ModalOptions = {
15
15
  */
16
16
  closable?: boolean;
17
17
  /**
18
- * Whether a backdrop click closes the modal.
18
+ * Whether a backdrop click closes the modal. Like every
19
+ * dismissal by the reader, it raises a preventable `cancel` first.
19
20
  */
20
21
  lightDismiss?: boolean;
21
22
  /**
@@ -39,20 +40,32 @@ export type ModalOptions = {
39
40
  /**
40
41
  * Cancel event listener.
41
42
  */
42
- oncancel?: (event: CustomEvent<Record<string, never>>) => void;
43
+ oncancel?: (event: CustomEvent<ModalCancelDetail>) => void;
44
+ };
45
+ export type ModalDismissReason = 'escape' | 'close-button' | 'button' | 'backdrop' | 'outside' | 'drag';
46
+ export type ModalCancelDetail = {
47
+ reason: ModalDismissReason;
43
48
  };
44
49
  /**
45
50
  * @typedef {Object} ModalOptions
46
51
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Modal content.
47
52
  * @property {string|number} [width='auto'] CSS width, or a pixel width when numeric.
48
53
  * @property {boolean} [closable=true] Whether Escape may close the modal.
49
- * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal.
54
+ * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal. Like every
55
+ * dismissal by the reader, it raises a preventable `cancel` first.
50
56
  * @property {boolean} [destroyOnClose=false] Whether to destroy the modal after it closes.
51
57
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
52
58
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
53
59
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
54
- * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
60
+ * @property {(event: CustomEvent<ModalCancelDetail>) => void} [oncancel] Cancel event listener.
61
+ */
62
+ /**
63
+ * What the reader did to ask for dismissal: pressed Escape, used a header close button, chose a
64
+ * footer button whose action is `'cancel'`, clicked the backdrop, pressed outside a non-modal
65
+ * overlay, or dragged it away.
66
+ * @typedef {'escape'|'close-button'|'button'|'backdrop'|'outside'|'drag'} ModalDismissReason
55
67
  */
68
+ /** @typedef {{reason: ModalDismissReason}} ModalCancelDetail */
56
69
  /**
57
70
  * Thin native-dialog overlay with lifecycle-safe content and dismissal behavior.
58
71
  * The constructor always creates and appends a new dialog; its target argument is ignored.
@@ -114,12 +127,23 @@ export declare class Modal extends Component<ModalOptions> {
114
127
  * Describes the current presentation for the overlay stack, or returns null to stay off it.
115
128
  *
116
129
  * The kind is read from the platform like `aria-modal` is: a `showModal()` dialog is `modal`,
117
- * and its Escape and backdrop stay the browser's; anything else is `non-modal`, and a subclass
118
- * presenting that way adds the Escape and outside-press handling it wants.
130
+ * and the stack leaves its Escape alone (this class answers it, see the constructor); anything
131
+ * else is `non-modal`, and a subclass presenting that way adds the Escape and outside-press
132
+ * handling it wants.
119
133
  * @returns {import('../../core/overlay-stack.js').OverlayEntryOptions|null}
120
134
  * @protected
121
135
  */
122
136
  protected _overlayEntry(): import('../../core/overlay-stack.js').OverlayEntryOptions | null;
137
+ /**
138
+ * Asks to close on the reader's behalf: emits a preventable `cancel` naming what they did, and
139
+ * closes unless a listener prevented it. Every dismissal gesture goes through here; `close()`
140
+ * itself stays unconditional, for the application's own decisions.
141
+ * @param {ModalDismissReason} reason What the reader did.
142
+ * @returns {boolean} Whether the overlay is closing.
143
+ * @fires Modal#cancel
144
+ * @protected
145
+ */
146
+ protected _requestDismiss(reason: ModalDismissReason): boolean;
123
147
  /**
124
148
  * Re-registers the current presentation on the overlay stack: called after every presentation,
125
149
  * including a subclass's change of address that bypasses `open()`.
@@ -237,9 +261,11 @@ export declare class Modal extends Component<ModalOptions> {
237
261
  * @type {CustomEvent<{result: unknown}>}
238
262
  */
239
263
  /**
240
- * Fired when Escape requests cancellation. Preventing it keeps the modal open.
264
+ * Fired when the reader asks to dismiss the modal — Escape, a header close button, a `'cancel'`
265
+ * footer button, a backdrop click, a press outside a non-modal overlay, a drag — with the gesture
266
+ * in `detail.reason`. Preventing it keeps the modal open. A programmatic `close()` does not raise it.
241
267
  * @event Modal#cancel
242
- * @type {CustomEvent<Record<string, never>>}
268
+ * @type {CustomEvent<ModalCancelDetail>}
243
269
  */
244
270
  /**
245
271
  * Picks the control initial focus belongs on inside an overlay panel: an `autofocus` control when
@@ -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.