@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
@@ -1,6 +1,34 @@
1
1
  import { Component } from '../../core/component.js';
2
2
  import { Field } from '../field/field.js';
3
3
  import { ProgressBar } from '../loading/progress-bar.js';
4
+ /**
5
+ * The message key of each declarative rule's default text, as `checkRules()` names the rule.
6
+ * `required` is absent: an item words it itself (`questionnaire.required`,
7
+ * `questionnaire.requiredInput`).
8
+ */
9
+ export declare const RULE_MESSAGE_KEYS: Readonly<{
10
+ minLength: "questionnaire.rule.minLength";
11
+ maxLength: "questionnaire.rule.maxLength";
12
+ minItems: "questionnaire.rule.minItems";
13
+ maxItems: "questionnaire.rule.maxItems";
14
+ minimum: "questionnaire.rule.minimum";
15
+ maximum: "questionnaire.rule.maximum";
16
+ oneOf: "questionnaire.rule.oneOf";
17
+ date: "questionnaire.rule.date";
18
+ 'date-time': "questionnaire.rule.dateTime";
19
+ time: "questionnaire.rule.time";
20
+ email: "questionnaire.rule.email";
21
+ uri: "questionnaire.rule.uri";
22
+ }>;
23
+ /**
24
+ * A rule's default message through a component's `msg()`: its catalogue key when it has one, the
25
+ * English of `ruleMessage()` otherwise.
26
+ * @param {(key: string, ...args: unknown[]) => string} msg The component's message lookup.
27
+ * @param {string} key The rule key `checkRules()` reports.
28
+ * @param {...unknown} args Its interpolation values.
29
+ * @returns {string}
30
+ */
31
+ export declare function ruleText(msg: (key: string, ...args: unknown[]) => string, key: string, ...args: unknown[]): string;
4
32
  export type QuestionnaireItem = import('./items.js').QuestionnaireItem;
5
33
  export type QuestionnaireChoice = import('./items.js').QuestionnaireChoice;
6
34
  export type NormalizedItem = import('./items.js').NormalizedItem;
@@ -121,14 +149,18 @@ export type QuestionnaireCompleteDetail = {
121
149
  * persistence and transport.
122
150
  *
123
151
  * Three things separate it from a `Form` with one `Fieldset` per question. It **branches**: an item
124
- * carries a `when` predicate and a `next` target, conditions cascade, and Back retraces the path
152
+ * carries a `when` condition and a `next` target, conditions cascade, and Back retraces the path
125
153
  * actually walked rather than an array index. Its answer control is **any registered Zx `Field`
126
154
  * type**, so a question can ask for a date, a number, a rating or an upload instead of a choice.
127
155
  * And its `validate` may be asynchronous, which is what lets a question be gated on a server check.
128
156
  *
129
- * The root is a real `<form>` and choices are native radios and checkboxes carrying the item name,
130
- * so `new FormData(questionnaire.toElement())` reads the answers, arrow-key navigation inside a
131
- * choice group is the browser's rather than ours, and nothing depends on JavaScript for semantics.
157
+ * `when`, `next` and `validate` each take a function or the same logic written as plain JSON (see
158
+ * `conditions.js`), so a whole questionnaire can be stored, sent, or composed by an agent.
159
+ *
160
+ * A created root is a real `<form>`; an enhanced non-form target contains one. Choices are native
161
+ * radios and checkboxes carrying the item name,
162
+ * and arrow-key navigation inside a choice group is the browser's. Form data includes every
163
+ * applicable answer, including answers from earlier steps.
132
164
  *
133
165
  * @fires Questionnaire#change
134
166
  * @fires Questionnaire#navigate
@@ -156,6 +188,7 @@ export declare class Questionnaire extends Component<QuestionnaireOptions> {
156
188
  _status: QuestionnaireStatus;
157
189
  _returnToReview: any;
158
190
  _busy: boolean;
191
+ _revision: number;
159
192
  _error: string;
160
193
  _advanceTimer: number;
161
194
  _uid: string;
@@ -232,6 +265,8 @@ export declare class Questionnaire extends Component<QuestionnaireOptions> {
232
265
  * @fires Questionnaire#complete
233
266
  */
234
267
  submit(): Promise<boolean>;
268
+ /** @returns {boolean} */
269
+ _finishSubmit(): boolean;
235
270
  /**
236
271
  * Returns the answers of every visible question that carries one, in declaration order.
237
272
  * Questions conditioned out are left out, so an abandoned branch never submits stale data.
@@ -332,6 +367,11 @@ export declare class Questionnaire extends Component<QuestionnaireOptions> {
332
367
  _field(item: NormalizedItem): Field;
333
368
  /** @param {string} name @param {QuestionnaireNavigateDetail['reason']} reason @returns {boolean} */
334
369
  _navigate(name: string, reason: QuestionnaireNavigateDetail['reason']): boolean;
370
+ /**
371
+ * Follows a resolved branch target: an item, the review screen, or submission.
372
+ * @param {string|null} target @param {'next'|'skip'} reason @returns {Promise<boolean>|boolean}
373
+ */
374
+ _leave(target: string | null, reason: 'next' | 'skip'): Promise<boolean> | boolean;
335
375
  /** @returns {boolean} */
336
376
  _enterReview(): boolean;
337
377
  /** @returns {Promise<boolean>} */
@@ -25,9 +25,10 @@ export type RatingOptions = {
25
25
  */
26
26
  disabled?: boolean;
27
27
  /**
28
- * Accessible name of the group.
28
+ * Accessible name of the group; null reads the `rating.label`
29
+ * message ("Rating").
29
30
  */
30
- label?: string;
31
+ label?: string | null;
31
32
  /**
32
33
  * Icon name used for each symbol.
33
34
  */
@@ -73,7 +74,8 @@ export type RatingOptions = {
73
74
  * @property {boolean} [clearable=true] Whether re-selecting the current value clears it.
74
75
  * @property {boolean} [readonly=false] Whether the rating is display-only.
75
76
  * @property {boolean} [disabled=false] Whether interaction is disabled.
76
- * @property {string} [label='Rating'] Accessible name of the group.
77
+ * @property {string|null} [label=null] Accessible name of the group; null reads the `rating.label`
78
+ * message ("Rating").
77
79
  * @property {string} [icon='star'] Icon name used for each symbol.
78
80
  * @property {string[]|null} [labels=null] Per-step accessible names, lowest first.
79
81
  * @property {boolean} [showValue=false] Whether to render the numeric value beside the symbols.
@@ -0,0 +1,106 @@
1
+ export type SelectOptions = import('./select.js').SelectOptions;
2
+ export type FlagMode = import('../flag/flag.js').FlagMode;
3
+ export type CountryItem = {
4
+ /**
5
+ * ISO 3166-1 alpha-2 code (`'DE'`).
6
+ */
7
+ code: string;
8
+ /**
9
+ * Label, replacing the one `Intl.DisplayNames` gives.
10
+ */
11
+ name?: string;
12
+ /**
13
+ * Secondary text, such as a calling code or a currency.
14
+ */
15
+ description?: string;
16
+ };
17
+ export type CountrySelectOptions = {
18
+ /**
19
+ * The countries to offer. Without it, every
20
+ * ISO 3166-1 country (`COUNTRY_CODES`). A code that is not two letters is left out.
21
+ */
22
+ countries?: Array<string | CountryItem>;
23
+ /**
24
+ * Countries pinned above the list, in the
25
+ * order given and kept through filtering — the markets an application serves, say.
26
+ */
27
+ preferred?: Array<string | CountryItem>;
28
+ /**
29
+ * Heading above the pinned countries.
30
+ */
31
+ preferredLabel?: string | null;
32
+ /**
33
+ * The language country names are written in. By
34
+ * default the component's `lang` option, then the library language (`setLanguage()`).
35
+ */
36
+ displayLocale?: string | null;
37
+ /**
38
+ * What stands before each country: its flag (`auto` draws flag
39
+ * emoji where the platform has them and a code chip where it does not; `emoji` forces the emoji),
40
+ * the code chip (`code`), nothing (`none`), or a function returning the content.
41
+ */
42
+ flags?: FlagMode;
43
+ /**
44
+ * Flag image URL template, such as `'/flags/{code}.svg'`;
45
+ * `{code}` is the lower-case code, `{CODE}` the upper-case. Draws flags from the application's
46
+ * own flag set instead of emoji.
47
+ */
48
+ flagUrl?: string | null;
49
+ /**
50
+ * Shows the ISO code as secondary text.
51
+ */
52
+ showCode?: boolean;
53
+ /**
54
+ * Orders the countries by name in the display language; `false`
55
+ * keeps the order given.
56
+ */
57
+ sort?: boolean;
58
+ };
59
+ /** @typedef {import('./select.js').SelectOptions} SelectOptions */
60
+ /** @typedef {import('../flag/flag.js').FlagMode} FlagMode */
61
+ /**
62
+ * A country the picker offers, when a bare code is not enough.
63
+ * @typedef {Object} CountryItem
64
+ * @property {string} code ISO 3166-1 alpha-2 code (`'DE'`).
65
+ * @property {string} [name] Label, replacing the one `Intl.DisplayNames` gives.
66
+ * @property {string} [description] Secondary text, such as a calling code or a currency.
67
+ */
68
+ /**
69
+ * @typedef {Object} CountrySelectOptions
70
+ * @property {Array<string|CountryItem>} [countries] The countries to offer. Without it, every
71
+ * ISO 3166-1 country (`COUNTRY_CODES`). A code that is not two letters is left out.
72
+ * @property {Array<string|CountryItem>} [preferred=[]] Countries pinned above the list, in the
73
+ * order given and kept through filtering — the markets an application serves, say.
74
+ * @property {string|null} [preferredLabel=null] Heading above the pinned countries.
75
+ * @property {string|null} [displayLocale=null] The language country names are written in. By
76
+ * default the component's `lang` option, then the library language (`setLanguage()`).
77
+ * @property {FlagMode} [flags='auto'] What stands before each country: its flag (`auto` draws flag
78
+ * emoji where the platform has them and a code chip where it does not; `emoji` forces the emoji),
79
+ * the code chip (`code`), nothing (`none`), or a function returning the content.
80
+ * @property {string|null} [flagUrl=null] Flag image URL template, such as `'/flags/{code}.svg'`;
81
+ * `{code}` is the lower-case code, `{CODE}` the upper-case. Draws flags from the application's
82
+ * own flag set instead of emoji.
83
+ * @property {boolean} [showCode=false] Shows the ISO code as secondary text.
84
+ * @property {boolean} [sort=true] Orders the countries by name in the display language; `false`
85
+ * keeps the order given.
86
+ */
87
+ /**
88
+ * Builds the items a country picker lists, without the DOM: one `{ID, name, description, alias}`
89
+ * per valid code, where `alias` is the English name. Exposed for a table or a summary that names
90
+ * countries the same way.
91
+ * @param {Array<string|CountryItem>} [countries=COUNTRY_CODES] Codes or country items.
92
+ * @param {Pick<CountrySelectOptions, 'displayLocale'|'showCode'|'sort'>} [options={}] Naming options.
93
+ * @returns {Array<{ID: string, name: string, description: string, alias: string}>}
94
+ */
95
+ export declare function countryItems(countries?: Array<string | CountryItem>, options?: Pick<CountrySelectOptions, 'displayLocale' | 'showCode' | 'sort'>): Array<{
96
+ ID: string;
97
+ name: string;
98
+ description: string;
99
+ alias: string;
100
+ }>;
101
+ /**
102
+ * Turns country preset options into the Select options behind them.
103
+ * @param {CountrySelectOptions & SelectOptions} options Country preset options.
104
+ * @returns {SelectOptions}
105
+ */
106
+ export declare function countrySelectOptions(options: CountrySelectOptions & SelectOptions): SelectOptions;
@@ -1,5 +1,6 @@
1
1
  /**
2
- * Registers the Select-backed `zxselect` field type.
2
+ * Registers the Select-backed `zxselect` field type. `props.preset` picks a preset: `'priority'`,
3
+ * `'status'`, `'locale'`, or `'country'`.
3
4
  * @returns {void}
4
5
  */
5
6
  export declare function registerSelectFieldAdapter(): void;
@@ -0,0 +1,102 @@
1
+ export type SelectOptions = import('./select.js').SelectOptions;
2
+ export type FlagMode = import('../flag/flag.js').FlagMode;
3
+ export type LocaleItem = {
4
+ /**
5
+ * BCP 47 language tag (`'de'`, `'de-AT'`, `'zh-Hant-TW'`).
6
+ */
7
+ code: string;
8
+ /**
9
+ * Label, replacing the one `Intl.DisplayNames` gives.
10
+ */
11
+ name?: string;
12
+ /**
13
+ * Secondary text, replacing the localized name.
14
+ */
15
+ description?: string;
16
+ /**
17
+ * Flag region, replacing the one the tag implies; `null` draws the
18
+ * language chip instead of a flag.
19
+ */
20
+ region?: string | null;
21
+ };
22
+ export type LocaleSelectOptions = {
23
+ /**
24
+ * The locales to offer, in the order given. Tags are
25
+ * canonicalized (`'de_at'` → `'de-AT'`); an invalid tag is left out. Without it the picker offers
26
+ * a short list of widely used languages.
27
+ */
28
+ locales?: Array<string | LocaleItem>;
29
+ /**
30
+ * Locales pinned above the list, kept through
31
+ * filtering — the application's own languages above a long list, say.
32
+ */
33
+ preferred?: Array<string | LocaleItem>;
34
+ /**
35
+ * Heading above the pinned locales.
36
+ */
37
+ preferredLabel?: string | null;
38
+ /**
39
+ * The language the secondary name is written in. By
40
+ * default the component's `lang` option, then the library language (`setLanguage()`).
41
+ */
42
+ displayLocale?: string | null;
43
+ /**
44
+ * `native` names each locale in its own
45
+ * language ("Deutsch"), `localized` in the display language ("German"), and `both` shows the
46
+ * native name with the localized one beneath it where the two differ — so a reader finds their
47
+ * language whichever language the interface is in.
48
+ */
49
+ display?: 'both' | 'native' | 'localized';
50
+ /**
51
+ * What stands before each locale: the flag of its region
52
+ * (`auto` draws flag emoji where the platform has them and a language chip where it does not;
53
+ * `emoji` forces the emoji), a language chip (`code`, the honest choice where a language is not a
54
+ * country), nothing (`none`), or a function returning the content.
55
+ */
56
+ flags?: FlagMode;
57
+ /**
58
+ * Flag image URL template, such as `'/flags/{code}.svg'`;
59
+ * `{code}` is the lower-case region, `{CODE}` the upper-case. Draws flags from the application's
60
+ * own flag set instead of emoji.
61
+ */
62
+ flagUrl?: string | null;
63
+ /**
64
+ * Flag region per tag or language, for a
65
+ * language whose likely region is not the one the application means: `{ en: 'GB' }`. A tag with
66
+ * a region of its own (`en-US`) keeps it unless it is listed here itself.
67
+ */
68
+ flagRegions?: Record<string, string | null>;
69
+ /**
70
+ * Orders the locales by label rather than as given.
71
+ */
72
+ sort?: boolean;
73
+ };
74
+ /**
75
+ * Builds the items a locale picker lists, without the DOM: one `{ID, name, nameLang, description,
76
+ * region, language}` per valid tag; `nameLang` is the language `name` is written in. Exposed for
77
+ * a table or a summary that names locales the same way.
78
+ * @param {Array<string|LocaleItem>} locales Tags or locale items.
79
+ * @param {Pick<LocaleSelectOptions, 'displayLocale'|'display'|'flagRegions'|'sort'>} [options={}]
80
+ * Naming options.
81
+ * @returns {Array<{ID: string, name: string, nameLang: string|null, description: string, region: string|null, language: string}>}
82
+ */
83
+ export declare function localeItems(locales: Array<string | LocaleItem>, options?: Pick<LocaleSelectOptions, 'displayLocale' | 'display' | 'flagRegions' | 'sort'>): Array<{
84
+ ID: string;
85
+ name: string;
86
+ nameLang: string | null;
87
+ description: string;
88
+ region: string | null;
89
+ language: string;
90
+ }>;
91
+ /**
92
+ * Turns locale preset options into the Select options behind them.
93
+ * @param {LocaleSelectOptions & SelectOptions} options Locale preset options.
94
+ * @returns {SelectOptions}
95
+ */
96
+ export declare function localeSelectOptions(options: LocaleSelectOptions & SelectOptions): SelectOptions;
97
+ /**
98
+ * Canonicalizes a BCP 47 tag, accepting `_` for `-`.
99
+ * @param {unknown} tag Candidate tag.
100
+ * @returns {string|null} The canonical tag, or null when it is not one.
101
+ */
102
+ export declare function canonicalLocale(tag: unknown): string | null;
@@ -1,4 +1,6 @@
1
1
  import { Component } from '../../core/component.js';
2
+ import { localeItems } from './locale.js';
3
+ import { countryItems } from './country.js';
2
4
  export type Primitive = string | number | boolean | symbol | bigint | null | undefined;
3
5
  export type SelectItem = Record<string, any> | Primitive;
4
6
  export type SelectValueReader = string | ((item: SelectItem) => unknown);
@@ -135,9 +137,10 @@ export type EntitySelectOptions = {
135
137
  */
136
138
  recent?: SelectItem[];
137
139
  /**
138
- * Heading above recent choices.
140
+ * Heading above recent choices, by default the `select.recent`
141
+ * message ("Recent"); null shows none.
139
142
  */
140
- recentLabel?: string;
143
+ recentLabel?: string | null;
141
144
  /**
142
145
  * Optional create command at the bottom.
143
146
  */
@@ -217,6 +220,8 @@ export declare class Select extends Component<SelectOptions> {
217
220
  _root: HTMLElement;
218
221
  _snapshot: import("../../core/dom.js").TargetSnapshot;
219
222
  _pointerModality: boolean;
223
+ /** @private @type {(value: string) => string} */
224
+ _normalizeValue;
220
225
  _handleTypeahead: (event: KeyboardEvent | string) => void;
221
226
  static cssName: string;
222
227
  /** @type {SelectOptions} */
@@ -267,6 +272,8 @@ export declare class Select extends Component<SelectOptions> {
267
272
  }): this;
268
273
  /** Opens the option panel. @returns {this} @fires Select#open */
269
274
  open(): this;
275
+ /** @param {boolean} selectText Whether to select the existing label. @returns {this} */
276
+ _openPanel(selectText: boolean): this;
270
277
  /** Closes the option panel and restores the selected label. @returns {this} @fires Select#close */
271
278
  close(): this;
272
279
  /** Enables user interaction. @returns {this} */
@@ -275,6 +282,38 @@ export declare class Select extends Component<SelectOptions> {
275
282
  disable(): this;
276
283
  /** Moves focus to the combobox input. @returns {this} */
277
284
  focus(): this;
285
+ /**
286
+ * Creates a locale Select with native/localized names, pinned choices, and optional flags.
287
+ * Values are canonical BCP 47 tags; initial values and `set()` accept underscores and any case.
288
+ * @param {Element|string|null} target Component target.
289
+ * @param {import('./locale.js').LocaleSelectOptions & SelectOptions} [options={}] Locale options
290
+ * and Select overrides other than items, readers, and renderers.
291
+ * @returns {Select}
292
+ */
293
+ static locale(target: Element | string | null, options?: import('./locale.js').LocaleSelectOptions & SelectOptions): Select;
294
+ /**
295
+ * Builds locale items without the DOM, for lists and summaries using the same names.
296
+ * @param {Array<string|import('./locale.js').LocaleItem>} locales Locale tags or specifications.
297
+ * @param {Pick<import('./locale.js').LocaleSelectOptions, 'displayLocale'|'display'|'flagRegions'|'sort'>} [options={}] Naming options.
298
+ * @returns {ReturnType<typeof localeItems>}
299
+ */
300
+ static localeItems(locales: Array<string | import('./locale.js').LocaleItem>, options?: Pick<import('./locale.js').LocaleSelectOptions, 'displayLocale' | 'display' | 'flagRegions' | 'sort'>): ReturnType<typeof localeItems>;
301
+ /**
302
+ * Creates a country Select with localized names, pinned choices, and optional flags. Search
303
+ * includes the English name, ISO code, and descriptions; initial values and `set()` accept either case.
304
+ * @param {Element|string|null} target Component target.
305
+ * @param {import('./country.js').CountrySelectOptions & SelectOptions} [options={}] Country options
306
+ * and Select overrides other than items, readers, and renderers.
307
+ * @returns {Select}
308
+ */
309
+ static country(target: Element | string | null, options?: import('./country.js').CountrySelectOptions & SelectOptions): Select;
310
+ /**
311
+ * Builds country items without the DOM, defaulting to the ISO country catalogue.
312
+ * @param {Array<string|import('./country.js').CountryItem>} [countries] Country codes or specifications.
313
+ * @param {Pick<import('./country.js').CountrySelectOptions, 'displayLocale'|'showCode'|'sort'>} [options={}] Naming options.
314
+ * @returns {ReturnType<typeof countryItems>}
315
+ */
316
+ static countryItems(countries?: Array<string | import('./country.js').CountryItem>, options?: Pick<import('./country.js').CountrySelectOptions, 'displayLocale' | 'showCode' | 'sort'>): ReturnType<typeof countryItems>;
278
317
  /**
279
318
  * Creates the five-level priority preset: values 0 (lowest) to 4 (highest), each drawn as grey
280
319
  * signal bars filled to its level, except the highest, which is the one coloured level — a
@@ -97,7 +97,7 @@ export type SheetOptions = {
97
97
  /**
98
98
  * Cancel event listener.
99
99
  */
100
- oncancel?: (event: CustomEvent<Record<string, never>>) => void;
100
+ oncancel?: (event: CustomEvent<import('../modal/modal.js').ModalCancelDetail>) => void;
101
101
  /**
102
102
  * Resize listener.
103
103
  */
@@ -145,7 +145,7 @@ export type SheetOptions = {
145
145
  * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns a floating sheet; defaults to the opener.
146
146
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
147
147
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
148
- * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
148
+ * @property {(event: CustomEvent<import('../modal/modal.js').ModalCancelDetail>) => void} [oncancel] Cancel event listener.
149
149
  * @property {(event: CustomEvent<{size: number, ratio: number}>) => void} [onresize] Resize listener.
150
150
  * @property {(event: CustomEvent<{docked: boolean, dock: import('../dock/dock.js').Dock|null}>) => void} [ondockchange] Dock-state listener.
151
151
  */
@@ -131,6 +131,7 @@ export declare class Slider extends Component<SliderOptions> {
131
131
  _max: number;
132
132
  _step: number;
133
133
  _id: string;
134
+ _committedValue: number;
134
135
  static cssName: string;
135
136
  /** @type {SliderOptions} */
136
137
  static defaults: SliderOptions;
@@ -18,9 +18,10 @@ export type SortControlOptions = {
18
18
  */
19
19
  value?: SortValue | null;
20
20
  /**
21
- * Accessible field label and direction-name prefix.
21
+ * Accessible field label and direction-name prefix, by default the
22
+ * `sortControl.label` message ("Sort by"). Null gives neither.
22
23
  */
23
- label?: string;
24
+ label?: string | null;
24
25
  /**
25
26
  * Current/next direction labels, defaulting to Ascending/Descending.
26
27
  */
@@ -45,7 +46,8 @@ export type SortControlOptions = {
45
46
  * @typedef {Object} SortControlOptions
46
47
  * @property {SortField[]} [fields=[]] Available sort fields, in display order.
47
48
  * @property {SortValue|null} [value=null] Initial sort; null chooses the first field ascending.
48
- * @property {string} [label='Sort by'] Accessible field label and direction-name prefix.
49
+ * @property {string|null} [label] Accessible field label and direction-name prefix, by default the
50
+ * `sortControl.label` message ("Sort by"). Null gives neither.
49
51
  * @property {{asc?:string,desc?:string}} [labels={}] Current/next direction labels, defaulting to Ascending/Descending.
50
52
  * @property {boolean} [disabled=false] Whether interaction is disabled.
51
53
  * @property {(event:CustomEvent<{value:SortValue}>)=>void} [onchange] Atomic field/direction change.
@@ -84,6 +86,8 @@ export declare class SortControl extends Component<SortControlOptions> {
84
86
  disable(): this;
85
87
  /** Updates the icon and accessible current/next direction text. @private @returns {void} */
86
88
  private _syncDirection;
89
+ /** @returns {string|null} The control's name: unset reads the catalogue, and null is no name. */
90
+ _label(): string | null;
87
91
  /** Focuses the searchable control. @returns {this} */
88
92
  focus(): this;
89
93
  /** Releases the owned Select and restores an enhanced target. @returns {void} */
@@ -9,10 +9,11 @@ export type SourceListOptions = {
9
9
  */
10
10
  sources?: Source[];
11
11
  /**
12
- * The visible label the list is named by. Empty hides it and
13
- * names the list with the `sourceList.label` message instead.
12
+ * The visible label the list is named by, by default the
13
+ * `sourceList.label` message ("Sources"). Empty or null hides it and names the list with that
14
+ * message instead.
14
15
  */
15
- label?: string;
16
+ label?: string | null;
16
17
  /**
17
18
  * `'chips'` wraps short chips beside the label;
18
19
  * `'list'` gives each source a full-width row with its title and site.
@@ -49,8 +50,9 @@ export type SourceListOptions = {
49
50
  * @typedef {Object} SourceListOptions
50
51
  * @property {Source[]} [sources=[]] The sources, in the order an answer's `[n]` citations number
51
52
  * them. Model text is data: every string reaches the page as text.
52
- * @property {string} [label='Sources'] The visible label the list is named by. Empty hides it and
53
- * names the list with the `sourceList.label` message instead.
53
+ * @property {string|null} [label] The visible label the list is named by, by default the
54
+ * `sourceList.label` message ("Sources"). Empty or null hides it and names the list with that
55
+ * message instead.
54
56
  * @property {'chips'|'list'} [layout='chips'] `'chips'` wraps short chips beside the label;
55
57
  * `'list'` gives each source a full-width row with its title and site.
56
58
  * @property {boolean} [numbered=true] Whether each source shows its number.
@@ -53,9 +53,10 @@ export type SplitViewOptions = {
53
53
  */
54
54
  disabled?: boolean;
55
55
  /**
56
- * Accessible name of the divider.
56
+ * Accessible name of the divider; null reads the
57
+ * `splitView.resize` message ("Resize panes").
57
58
  */
58
- label?: string;
59
+ label?: string | null;
59
60
  /**
60
61
  * Resize listener.
61
62
  */
@@ -101,7 +102,8 @@ export type SplitViewOptions = {
101
102
  * @property {string|null} [storageKey=null] Key under which the size is remembered between visits.
102
103
  * Storage failures degrade to memory rather than throwing.
103
104
  * @property {boolean} [disabled=false] Whether resizing is blocked.
104
- * @property {string} [label='Resize panes'] Accessible name of the divider.
105
+ * @property {string|null} [label=null] Accessible name of the divider; null reads the
106
+ * `splitView.resize` message ("Resize panes").
105
107
  * @property {(event: CustomEvent<{size: number, ratio: number}>) => void} [onresize] Resize listener.
106
108
  * @property {(event: CustomEvent<{size: number, ratio: number}>) => void} [onresizeend] Resize-end listener.
107
109
  * @property {(event: CustomEvent<{pane: 'start'|'end'}>) => void} [oncollapse] Collapse listener.