@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
@@ -0,0 +1,136 @@
1
+ import { Component } from '../../core/component.js';
2
+ import { h } from '../../core/dom.js';
3
+ import { getLanguage } from '../../core/i18n.js';
4
+ import { COUNTRY_CODES, flagRenderer, normalizeRegion } from '../flag/flag.js';
5
+
6
+ /** @typedef {import('./select.js').SelectOptions} SelectOptions */
7
+ /** @typedef {import('../flag/flag.js').FlagMode} FlagMode */
8
+
9
+ /**
10
+ * A country the picker offers, when a bare code is not enough.
11
+ * @typedef {Object} CountryItem
12
+ * @property {string} code ISO 3166-1 alpha-2 code (`'DE'`).
13
+ * @property {string} [name] Label, replacing the one `Intl.DisplayNames` gives.
14
+ * @property {string} [description] Secondary text, such as a calling code or a currency.
15
+ */
16
+ /**
17
+ * @typedef {Object} CountrySelectOptions
18
+ * @property {Array<string|CountryItem>} [countries] The countries to offer. Without it, every
19
+ * ISO 3166-1 country (`COUNTRY_CODES`). A code that is not two letters is left out.
20
+ * @property {Array<string|CountryItem>} [preferred=[]] Countries pinned above the list, in the
21
+ * order given and kept through filtering — the markets an application serves, say.
22
+ * @property {string|null} [preferredLabel=null] Heading above the pinned countries.
23
+ * @property {string|null} [displayLocale=null] The language country names are written in. By
24
+ * default the component's `lang` option, then the library language (`setLanguage()`).
25
+ * @property {FlagMode} [flags='auto'] What stands before each country: its flag (`auto` draws flag
26
+ * emoji where the platform has them and a code chip where it does not; `emoji` forces the emoji),
27
+ * the code chip (`code`), nothing (`none`), or a function returning the content.
28
+ * @property {string|null} [flagUrl=null] Flag image URL template, such as `'/flags/{code}.svg'`;
29
+ * `{code}` is the lower-case code, `{CODE}` the upper-case. Draws flags from the application's
30
+ * own flag set instead of emoji.
31
+ * @property {boolean} [showCode=false] Shows the ISO code as secondary text.
32
+ * @property {boolean} [sort=true] Orders the countries by name in the display language; `false`
33
+ * keeps the order given.
34
+ */
35
+
36
+ /**
37
+ * Builds the items a country picker lists, without the DOM: one `{ID, name, description, alias}`
38
+ * per valid code, where `alias` is the English name. Exposed for a table or a summary that names
39
+ * countries the same way.
40
+ * @param {Array<string|CountryItem>} [countries=COUNTRY_CODES] Codes or country items.
41
+ * @param {Pick<CountrySelectOptions, 'displayLocale'|'showCode'|'sort'>} [options={}] Naming options.
42
+ * @returns {Array<{ID: string, name: string, description: string, alias: string}>}
43
+ */
44
+ export function countryItems(countries = COUNTRY_CODES, options = {}) {
45
+ const displayLocale = options.displayLocale || getLanguage() || 'en';
46
+ const names = displayNames(displayLocale);
47
+ const english = displayNames('en');
48
+ const seen = new Set();
49
+ const items = [];
50
+ for (const entry of Array.isArray(countries) ? countries : []) {
51
+ const spec = typeof entry === 'string' ? { code: entry } : entry;
52
+ const code = normalizeRegion(spec?.code);
53
+ if (!code || seen.has(code)) continue;
54
+ seen.add(code);
55
+ items.push({
56
+ ID: code,
57
+ name: String(spec.name ?? names?.of(code) ?? code),
58
+ description: String(spec.description ?? (options.showCode ? code : '')),
59
+ alias: String(english?.of(code) ?? code)
60
+ });
61
+ }
62
+ if (options.sort ?? true) {
63
+ const collator = new Intl.Collator(displayLocale);
64
+ items.sort((a, b) => collator.compare(a.name, b.name));
65
+ }
66
+ return items;
67
+ }
68
+
69
+ /**
70
+ * Turns country preset options into the Select options behind them.
71
+ * @param {CountrySelectOptions & SelectOptions} options Country preset options.
72
+ * @returns {SelectOptions}
73
+ */
74
+ export function countrySelectOptions(options) {
75
+ const {
76
+ countries = COUNTRY_CODES, preferred = [], preferredLabel = null, displayLocale = null,
77
+ flags = 'auto', flagUrl = null, showCode = false, sort = true, value = null, ...rest
78
+ } = options ?? {};
79
+ const naming = { displayLocale: displayLocale || rest.lang || rest.language || getLanguage(), showCode };
80
+ const items = countryItems(countries, { ...naming, sort });
81
+ const pinned = countryItems(preferred, { ...naming, sort: false });
82
+ const drawFlag = flagRenderer(flags, flagUrl);
83
+ const visual = (item) => drawFlag(item.ID, item.ID, item);
84
+ return {
85
+ filter: 'local',
86
+ ...rest,
87
+ label: rest.label || message('countryPicker.label', options),
88
+ placeholder: rest.placeholder || message('countryPicker.placeholder', options),
89
+ items,
90
+ fixedItems: pinned,
91
+ fixedLabel: pinned.length ? preferredLabel : null,
92
+ valueKey: 'ID',
93
+ labelKey: 'name',
94
+ searchKeys: ['name', 'ID', 'alias', 'description'],
95
+ value: typeof value === 'string' ? normalizeRegion(value) ?? value : value,
96
+ renderItem: (item) => pickerRow(visual(item), item.name, item.description),
97
+ renderValueAdornment: (item) => visual(item)
98
+ };
99
+ }
100
+
101
+ /**
102
+ * Draws one picker row with the Select entity anatomy: a visual, a label, and secondary text.
103
+ * @param {Node|string|null} visual Flag or chip.
104
+ * @param {string} label Primary text.
105
+ * @param {string} subtitle Secondary text, or `''`.
106
+ * @returns {HTMLElement}
107
+ */
108
+ function pickerRow(visual, label, subtitle) {
109
+ return h('span', { class: 'zx-select__entity' },
110
+ visual ? h('span', { class: 'zx-select__entity-icon', ariaHidden: 'true' }, visual) : null,
111
+ h('span', { class: 'zx-select__entity-copy' },
112
+ h('span', { class: 'zx-select__entity-label' }, label),
113
+ subtitle ? h('span', { class: 'zx-select__entity-subtitle' }, subtitle) : null));
114
+ }
115
+
116
+ /**
117
+ * @param {string} locale Display locale.
118
+ * @returns {Intl.DisplayNames|null}
119
+ */
120
+ function displayNames(locale) {
121
+ try {
122
+ return new Intl.DisplayNames([locale, 'en'], { type: 'region', fallback: 'code' });
123
+ } catch {
124
+ return null;
125
+ }
126
+ }
127
+
128
+ /**
129
+ * Resolves a message before the instance exists, honouring the picker's own `msg` option.
130
+ * @param {string} key Message key.
131
+ * @param {Record<string, any>} options Options the picker was given.
132
+ * @returns {string}
133
+ */
134
+ function message(key, options) {
135
+ return Component.prototype.msg.call({ options }, key);
136
+ }
@@ -2,7 +2,8 @@ import { Field } from '../field/field.js';
2
2
  import { Select } from './select.js';
3
3
 
4
4
  /**
5
- * Registers the Select-backed `zxselect` field type.
5
+ * Registers the Select-backed `zxselect` field type. `props.preset` picks a preset: `'priority'`,
6
+ * `'status'`, `'locale'`, or `'country'`.
6
7
  * @returns {void}
7
8
  */
8
9
  export function registerSelectFieldAdapter() {
@@ -20,7 +21,11 @@ export function registerSelectFieldAdapter() {
20
21
  ? Select.priority(null, selectOptions)
21
22
  : preset === 'status'
22
23
  ? Select.status(null, selectOptions)
23
- : new Select(null, selectOptions));
24
+ : preset === 'locale'
25
+ ? Select.locale(null, selectOptions)
26
+ : preset === 'country'
27
+ ? Select.country(null, selectOptions)
28
+ : new Select(null, selectOptions));
24
29
  field.listen(select.el, 'change', (event) => event.stopImmediatePropagation());
25
30
  select.on('change', (event) => field.emit('change', { value: event.detail.value }));
26
31
  return {
@@ -0,0 +1,219 @@
1
+ import { Component } from '../../core/component.js';
2
+ import { h } from '../../core/dom.js';
3
+ import { getLanguage } from '../../core/i18n.js';
4
+ import { flagRenderer, normalizeRegion } from '../flag/flag.js';
5
+
6
+ /** @typedef {import('./select.js').SelectOptions} SelectOptions */
7
+ /** @typedef {import('../flag/flag.js').FlagMode} FlagMode */
8
+
9
+ /**
10
+ * A locale the picker offers, when a bare tag is not enough.
11
+ * @typedef {Object} LocaleItem
12
+ * @property {string} code BCP 47 language tag (`'de'`, `'de-AT'`, `'zh-Hant-TW'`).
13
+ * @property {string} [name] Label, replacing the one `Intl.DisplayNames` gives.
14
+ * @property {string} [description] Secondary text, replacing the localized name.
15
+ * @property {string|null} [region] Flag region, replacing the one the tag implies; `null` draws the
16
+ * language chip instead of a flag.
17
+ */
18
+ /**
19
+ * @typedef {Object} LocaleSelectOptions
20
+ * @property {Array<string|LocaleItem>} [locales] The locales to offer, in the order given. Tags are
21
+ * canonicalized (`'de_at'` → `'de-AT'`); an invalid tag is left out. Without it the picker offers
22
+ * a short list of widely used languages.
23
+ * @property {Array<string|LocaleItem>} [preferred=[]] Locales pinned above the list, kept through
24
+ * filtering — the application's own languages above a long list, say.
25
+ * @property {string|null} [preferredLabel=null] Heading above the pinned locales.
26
+ * @property {string|null} [displayLocale=null] The language the secondary name is written in. By
27
+ * default the component's `lang` option, then the library language (`setLanguage()`).
28
+ * @property {'both'|'native'|'localized'} [display='both'] `native` names each locale in its own
29
+ * language ("Deutsch"), `localized` in the display language ("German"), and `both` shows the
30
+ * native name with the localized one beneath it where the two differ — so a reader finds their
31
+ * language whichever language the interface is in.
32
+ * @property {FlagMode} [flags='auto'] What stands before each locale: the flag of its region
33
+ * (`auto` draws flag emoji where the platform has them and a language chip where it does not;
34
+ * `emoji` forces the emoji), a language chip (`code`, the honest choice where a language is not a
35
+ * country), nothing (`none`), or a function returning the content.
36
+ * @property {string|null} [flagUrl=null] Flag image URL template, such as `'/flags/{code}.svg'`;
37
+ * `{code}` is the lower-case region, `{CODE}` the upper-case. Draws flags from the application's
38
+ * own flag set instead of emoji.
39
+ * @property {Record<string, string|null>} [flagRegions={}] Flag region per tag or language, for a
40
+ * language whose likely region is not the one the application means: `{ en: 'GB' }`. A tag with
41
+ * a region of its own (`en-US`) keeps it unless it is listed here itself.
42
+ * @property {boolean} [sort=false] Orders the locales by label rather than as given.
43
+ */
44
+
45
+ /** Languages offered when the application names none, as a starting point. */
46
+ const DEFAULT_LOCALES = Object.freeze([
47
+ 'en', 'de', 'fr', 'es', 'it', 'pt', 'nl', 'pl', 'cs', 'sv', 'da', 'fi', 'nb', 'tr', 'ru', 'uk',
48
+ 'el', 'ar', 'he', 'hi', 'ja', 'ko', 'zh'
49
+ ]);
50
+
51
+ /**
52
+ * Builds the items a locale picker lists, without the DOM: one `{ID, name, nameLang, description,
53
+ * region, language}` per valid tag; `nameLang` is the language `name` is written in. Exposed for
54
+ * a table or a summary that names locales the same way.
55
+ * @param {Array<string|LocaleItem>} locales Tags or locale items.
56
+ * @param {Pick<LocaleSelectOptions, 'displayLocale'|'display'|'flagRegions'|'sort'>} [options={}]
57
+ * Naming options.
58
+ * @returns {Array<{ID: string, name: string, nameLang: string|null, description: string, region: string|null, language: string}>}
59
+ */
60
+ export function localeItems(locales, options = {}) {
61
+ const displayLocale = options.displayLocale || getLanguage() || 'en';
62
+ const display = options.display ?? 'both';
63
+ const flagRegions = options.flagRegions ?? {};
64
+ const localized = displayNames(displayLocale, 'language');
65
+ const seen = new Set();
66
+ const items = [];
67
+ for (const entry of Array.isArray(locales) ? locales : []) {
68
+ const spec = typeof entry === 'string' ? { code: entry } : entry;
69
+ const code = canonicalLocale(spec?.code);
70
+ if (!code || seen.has(code)) continue;
71
+ seen.add(code);
72
+ const locale = new Intl.Locale(code);
73
+ const base = locale.baseName;
74
+ const nativeName = capitalize(displayNames(base, 'language')?.of(base) ?? base, base);
75
+ const localizedName = capitalize(localized?.of(base) ?? base, displayLocale);
76
+ const name = spec.name ?? (display === 'localized' ? localizedName : nativeName);
77
+ const description = spec.description
78
+ ?? (display === 'both' && localizedName.toLocaleLowerCase() !== nativeName.toLocaleLowerCase() ? localizedName : '');
79
+ items.push({
80
+ ID: code,
81
+ name: String(name),
82
+ nameLang: spec.name != null ? null : display === 'localized' ? displayLocale : code,
83
+ description: String(description),
84
+ region: 'region' in spec ? normalizeRegion(spec.region) : localeRegion(locale, code, flagRegions),
85
+ language: locale.language
86
+ });
87
+ }
88
+ if (options.sort) {
89
+ const collator = new Intl.Collator(displayLocale);
90
+ items.sort((a, b) => collator.compare(a.name, b.name));
91
+ }
92
+ return items;
93
+ }
94
+
95
+ /**
96
+ * Turns locale preset options into the Select options behind them.
97
+ * @param {LocaleSelectOptions & SelectOptions} options Locale preset options.
98
+ * @returns {SelectOptions}
99
+ */
100
+ export function localeSelectOptions(options) {
101
+ const {
102
+ locales = DEFAULT_LOCALES, preferred = [], preferredLabel = null, displayLocale = null,
103
+ display = 'both', flags = 'auto', flagUrl = null, flagRegions = {}, sort = false,
104
+ value = null, ...rest
105
+ } = options ?? {};
106
+ const naming = {
107
+ displayLocale: displayLocale || rest.lang || rest.language || getLanguage(),
108
+ display,
109
+ flagRegions,
110
+ sort
111
+ };
112
+ const items = localeItems(locales, naming);
113
+ const pinned = localeItems(preferred, { ...naming, sort: false });
114
+ const drawFlag = flagRenderer(flags, flagUrl);
115
+ const visual = (item) => drawFlag(item.region, item.language.toUpperCase(), item);
116
+ return {
117
+ filter: items.length + pinned.length > 7 ? 'local' : false,
118
+ ...rest,
119
+ label: rest.label || message('localePicker.label', options),
120
+ placeholder: rest.placeholder || message('localePicker.placeholder', options),
121
+ items,
122
+ fixedItems: pinned,
123
+ fixedLabel: pinned.length ? preferredLabel : null,
124
+ valueKey: 'ID',
125
+ labelKey: 'name',
126
+ searchKeys: ['name', 'description', 'ID'],
127
+ value: typeof value === 'string' ? canonicalLocale(value) ?? value : value,
128
+ renderItem: (item) => pickerRow(visual(item), item.name, item.description, item.nameLang),
129
+ renderValueAdornment: (item) => visual(item)
130
+ };
131
+ }
132
+
133
+ /**
134
+ * Draws one picker row with the Select entity anatomy: a visual, a label, and secondary text.
135
+ * @param {Node|string|null} visual Flag or chip.
136
+ * @param {string} label Primary text.
137
+ * @param {string} subtitle Secondary text, or `''`.
138
+ * @param {string|null} labelLang Language of the label, so a screen reader speaks "Deutsch" in German.
139
+ * @returns {HTMLElement}
140
+ */
141
+ function pickerRow(visual, label, subtitle, labelLang) {
142
+ return h('span', { class: 'zx-select__entity' },
143
+ visual ? h('span', { class: 'zx-select__entity-icon', ariaHidden: 'true' }, visual) : null,
144
+ h('span', { class: 'zx-select__entity-copy' },
145
+ h('span', { class: 'zx-select__entity-label', ...(labelLang ? { lang: labelLang } : {}) }, label),
146
+ subtitle ? h('span', { class: 'zx-select__entity-subtitle' }, subtitle) : null));
147
+ }
148
+
149
+ /**
150
+ * Canonicalizes a BCP 47 tag, accepting `_` for `-`.
151
+ * @param {unknown} tag Candidate tag.
152
+ * @returns {string|null} The canonical tag, or null when it is not one.
153
+ */
154
+ export function canonicalLocale(tag) {
155
+ if (typeof tag !== 'string' || !tag.trim()) return null;
156
+ try {
157
+ return Intl.getCanonicalLocales(tag.trim().replaceAll('_', '-'))[0] ?? null;
158
+ } catch {
159
+ return null;
160
+ }
161
+ }
162
+
163
+ /**
164
+ * The flag region of a locale: an override for the tag or its language, else its own region, else
165
+ * the likely region of its language (`de` → `DE`, `ja` → `JP`).
166
+ * @param {Intl.Locale} locale Parsed locale.
167
+ * @param {string} code Canonical tag.
168
+ * @param {Record<string, string|null>} overrides `flagRegions`.
169
+ * @returns {string|null}
170
+ */
171
+ function localeRegion(locale, code, overrides) {
172
+ if (Object.hasOwn(overrides, code)) return normalizeRegion(overrides[code]);
173
+ if (locale.region) return normalizeRegion(locale.region);
174
+ if (Object.hasOwn(overrides, locale.language)) return normalizeRegion(overrides[locale.language]);
175
+ try {
176
+ return normalizeRegion(locale.maximize().region);
177
+ } catch {
178
+ return null;
179
+ }
180
+ }
181
+
182
+ /**
183
+ * @param {string} locale Display locale.
184
+ * @param {'language'|'region'} type Name type.
185
+ * @returns {Intl.DisplayNames|null}
186
+ */
187
+ function displayNames(locale, type) {
188
+ try {
189
+ return new Intl.DisplayNames([locale, 'en'], { type, fallback: 'code', languageDisplay: 'standard' });
190
+ } catch {
191
+ return null;
192
+ }
193
+ }
194
+
195
+ /**
196
+ * Upper-cases the first letter in the given locale's rules: some languages name themselves in
197
+ * lower case ("français"), which reads as a typo at the head of a list row.
198
+ * @param {string} text Name.
199
+ * @param {string} locale Locale of the name.
200
+ * @returns {string}
201
+ */
202
+ function capitalize(text, locale) {
203
+ const [first = '', ...rest] = String(text);
204
+ try {
205
+ return first.toLocaleUpperCase(locale) + rest.join('');
206
+ } catch {
207
+ return first.toUpperCase() + rest.join('');
208
+ }
209
+ }
210
+
211
+ /**
212
+ * Resolves a message before the instance exists, honouring the picker's own `msg` option.
213
+ * @param {string} key Message key.
214
+ * @param {Record<string, any>} options Options the picker was given.
215
+ * @returns {string}
216
+ */
217
+ function message(key, options) {
218
+ return Component.prototype.msg.call({ options }, key);
219
+ }
@@ -26,8 +26,8 @@
26
26
 
27
27
  .zx-select__value-adornment[hidden] { display: none; }
28
28
 
29
- .zx-select__value-adornment:not([hidden]) + .zx-select__input {
30
- padding-inline-start: var(--zx-space-2) !important;
29
+ .zx-select .zx-select__value-adornment:not([hidden]) + .zx-select__input {
30
+ padding-inline-start: var(--zx-space-2);
31
31
  }
32
32
 
33
33
  /* The ring follows keyboard focus. A text input matches :focus-visible on a click as well, so the
@@ -37,32 +37,31 @@
37
37
  box-shadow: var(--zx-focus-ring);
38
38
  }
39
39
 
40
- .zx-select__input {
40
+ .zx-select .zx-select__input {
41
41
  grid-column: 2;
42
42
  inline-size: 100%;
43
43
  min-inline-size: 0;
44
- min-block-size: calc(var(--zx-control-height) - 2px) !important;
45
- border: 0 !important;
46
- border-radius: 0 !important;
47
- background: none !important;
48
- box-shadow: none !important;
44
+ min-block-size: calc(var(--zx-control-height) - 2px);
45
+ border: 0;
46
+ border-radius: 0;
47
+ background: none;
48
+ box-shadow: none;
49
49
  }
50
50
 
51
51
  .zx-select__input:read-only {
52
52
  cursor: default;
53
53
  }
54
54
 
55
- .zx-select__clear,
56
- .zx-select__toggle {
55
+ .zx-select .zx-select__control :is(.zx-select__clear, .zx-select__toggle) {
57
56
  display: grid;
58
57
  place-items: center;
59
58
  inline-size: var(--zx-control-height);
60
- min-block-size: calc(var(--zx-control-height) - 2px) !important;
61
- border: 0 !important;
62
- border-radius: 0 !important;
63
- background: none !important;
59
+ min-block-size: calc(var(--zx-control-height) - 2px);
60
+ border: 0;
61
+ border-radius: 0;
62
+ background: none;
64
63
  color: var(--zx-color-text-muted);
65
- padding: 0 !important;
64
+ padding: 0;
66
65
  }
67
66
 
68
67
  .zx-select__clear { grid-column: 3; }
@@ -70,19 +69,19 @@
70
69
  .zx-select__toggle { grid-column: 5; align-self: stretch; }
71
70
  .zx-select__toggle > .zx-icon { display: block; }
72
71
 
73
- .zx-select__clear:hover,
74
- .zx-select__toggle:hover {
72
+ .zx-select .zx-select__clear:hover,
73
+ .zx-select .zx-select__toggle:hover {
75
74
  color: var(--zx-color-text);
76
75
  }
77
76
 
78
- .zx-select__clear[hidden],
77
+ .zx-select .zx-select__clear[hidden],
79
78
  .zx-select__loading[hidden] {
80
79
  display: none;
81
80
  }
82
81
 
83
82
  .zx-select__loading {
84
- inline-size: 14px;
85
- block-size: 14px;
83
+ inline-size: calc(var(--zx-control-height) / 2 - 1px);
84
+ block-size: calc(var(--zx-control-height) / 2 - 1px);
86
85
  border: 2px solid var(--zx-color-border);
87
86
  border-block-start-color: var(--zx-color-accent);
88
87
  border-radius: var(--zx-radius-full);
@@ -91,7 +90,7 @@
91
90
  /* Disabled reads the way a disabled Field does: text and frame fade together, nothing else
92
91
  changes. Inside a disabled Field the field has already faded, so the Select does not again. */
93
92
  .zx-select[aria-disabled="true"] {
94
- opacity: 0.65;
93
+ opacity: var(--zx-control-disabled-opacity);
95
94
  }
96
95
 
97
96
  .zx-field[data-disabled="true"] .zx-select[aria-disabled="true"] {
@@ -103,7 +102,6 @@
103
102
  }
104
103
 
105
104
  .zx-select__panel {
106
- z-index: 20;
107
105
  inline-size: max-content;
108
106
  max-inline-size: calc(100vw - var(--zx-space-4));
109
107
  overflow: hidden;
@@ -6,6 +6,9 @@ import { position } from '../../core/position.js';
6
6
  import { uid } from '../../core/util.js';
7
7
  import { itemColor } from './color.js';
8
8
  import { matchItems } from './filter.js';
9
+ import { canonicalLocale, localeItems, localeSelectOptions } from './locale.js';
10
+ import { countryItems, countrySelectOptions } from './country.js';
11
+ import { normalizeRegion } from '../flag/flag.js';
9
12
  import {
10
13
  DEFAULT_STATUSES, STATUS_INDICATORS, STATUS_TONES, normalizePriorityLevel, priorityIcon, statusIcon
11
14
  } from './glyphs.js';
@@ -50,7 +53,8 @@ import {
50
53
  /**
51
54
  * @typedef {Object} EntitySelectOptions
52
55
  * @property {SelectItem[]} [recent=[]] Choices pinned above ordinary results.
53
- * @property {string} [recentLabel='Recent'] Heading above recent choices.
56
+ * @property {string|null} [recentLabel] Heading above recent choices, by default the `select.recent`
57
+ * message ("Recent"); null shows none.
54
58
  * @property {boolean|SelectAction} [create=false] Optional create command at the bottom.
55
59
  * @property {string|((item: SelectItem)=>unknown)} [iconKey='icon'] Item icon reader.
56
60
  * @property {string|((item: SelectItem)=>unknown)} [colorKey='color'] Optional icon colour reader: a CSS
@@ -66,6 +70,9 @@ import {
66
70
  /** @typedef {{item: SelectItem|null, clear: boolean, action: SelectAction|null, element: HTMLElement}} SelectOptionEntry */
67
71
  /** @typedef {{silent?: boolean}} SelectSetOptions */
68
72
 
73
+ // Internal factory configuration; ordinary Select instances keep their IDs unchanged.
74
+ const NORMALIZE_VALUE = Symbol('normalizeSelectValue');
75
+
69
76
  const PRIORITY_KEYS = [
70
77
  'priority.lowest',
71
78
  'priority.low',
@@ -120,6 +127,8 @@ export class Select extends Component {
120
127
  // Instance state initialized here because render() runs inside the base
121
128
  // constructor, before class-field initializers would run (and clobber it).
122
129
  this._items = []; this._visibleItems = []; this._fixedItems = []; this._visibleFixed = []; this._actions = []; this._selected = null; this._optionEntries = []; this._activeIndex = -1; this._open = false; this._disabled = false; this._loading = false; this._requestSequence = 0; this._queryTimer = null; this._position = null; this._createdRoot = false; this._root = null; this._snapshot = null; this._pointerModality = false;
130
+ /** @private @type {(value: string) => string} */
131
+ this._normalizeValue = this.options[NORMALIZE_VALUE] ?? ((value) => value);
123
132
  this._createdRoot = this.el === null;
124
133
  const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
125
134
  this.el = root;
@@ -132,7 +141,7 @@ export class Select extends Component {
132
141
  class: 'zx-select__input',
133
142
  type: 'text',
134
143
  role: 'combobox',
135
- ariaLabel: String(this.options.label || this.options.placeholder || 'Select'),
144
+ ariaLabel: String(this.options.label || this.options.placeholder || this._message('select.label', 'Select')),
136
145
  autocomplete: 'off',
137
146
  spellcheck: false,
138
147
  ariaExpanded: 'false',
@@ -274,7 +283,8 @@ export class Select extends Component {
274
283
  */
275
284
  set(idOrItem, { silent = false } = {}) {
276
285
  const previousValue = this.value;
277
- const item = idOrItem == null ? null : this._findItem(idOrItem);
286
+ const candidate = typeof idOrItem === 'string' ? this._normalizeValue(idOrItem) : idOrItem;
287
+ const item = candidate == null ? null : this._findItem(candidate);
278
288
  this._selected = item;
279
289
  this._syncInputValue();
280
290
  this._renderOptions();
@@ -292,6 +302,8 @@ export class Select extends Component {
292
302
  */
293
303
  setItems(items) {
294
304
  const selectedValue = this.value;
305
+ this._cancelQuery();
306
+ this._setLoading(false);
295
307
  this._items = Array.isArray(items) ? items.slice() : [];
296
308
  this._visibleItems = this._items.slice();
297
309
  this._selected = selectedValue == null ? null : this._findItem(selectedValue);
@@ -337,6 +349,11 @@ export class Select extends Component {
337
349
 
338
350
  /** Opens the option panel. @returns {this} @fires Select#open */
339
351
  open() {
352
+ return this._openPanel(true);
353
+ }
354
+
355
+ /** @param {boolean} selectText Whether to select the existing label. @returns {this} */
356
+ _openPanel(selectText) {
340
357
  if (this._disabled || this._open) return this;
341
358
  this._open = true;
342
359
  this.el.setAttribute('data-state', 'open');
@@ -351,7 +368,7 @@ export class Select extends Component {
351
368
  // is a no-op while the panel is still hidden.
352
369
  this._setActive(this._selectedEntryIndex());
353
370
  if (this._activeIndex < 0 && this._optionEntries.length > 0) this._setActive(0);
354
- if (this.options.filter && this._selected !== null) {
371
+ if (selectText && this.options.filter && this._selected !== null) {
355
372
  /** @type {HTMLInputElement} */ (this.refs.input).select();
356
373
  }
357
374
  if (typeof this.options.filter === 'function') this._scheduleAsyncQuery('');
@@ -399,6 +416,60 @@ export class Select extends Component {
399
416
  return this;
400
417
  }
401
418
 
419
+ /**
420
+ * Creates a locale Select with native/localized names, pinned choices, and optional flags.
421
+ * Values are canonical BCP 47 tags; initial values and `set()` accept underscores and any case.
422
+ * @param {Element|string|null} target Component target.
423
+ * @param {import('./locale.js').LocaleSelectOptions & SelectOptions} [options={}] Locale options
424
+ * and Select overrides other than items, readers, and renderers.
425
+ * @returns {Select}
426
+ */
427
+ static locale(target, options = {}) {
428
+ const select = new Select(target, {
429
+ ...localeSelectOptions(options),
430
+ [NORMALIZE_VALUE]: (value) => canonicalLocale(value) ?? value
431
+ });
432
+ select.el.setAttribute('data-preset', 'locale');
433
+ return select;
434
+ }
435
+
436
+ /**
437
+ * Builds locale items without the DOM, for lists and summaries using the same names.
438
+ * @param {Array<string|import('./locale.js').LocaleItem>} locales Locale tags or specifications.
439
+ * @param {Pick<import('./locale.js').LocaleSelectOptions, 'displayLocale'|'display'|'flagRegions'|'sort'>} [options={}] Naming options.
440
+ * @returns {ReturnType<typeof localeItems>}
441
+ */
442
+ static localeItems(locales, options = {}) {
443
+ return localeItems(locales, options);
444
+ }
445
+
446
+ /**
447
+ * Creates a country Select with localized names, pinned choices, and optional flags. Search
448
+ * includes the English name, ISO code, and descriptions; initial values and `set()` accept either case.
449
+ * @param {Element|string|null} target Component target.
450
+ * @param {import('./country.js').CountrySelectOptions & SelectOptions} [options={}] Country options
451
+ * and Select overrides other than items, readers, and renderers.
452
+ * @returns {Select}
453
+ */
454
+ static country(target, options = {}) {
455
+ const select = new Select(target, {
456
+ ...countrySelectOptions(options),
457
+ [NORMALIZE_VALUE]: (value) => normalizeRegion(value) ?? value
458
+ });
459
+ select.el.setAttribute('data-preset', 'country');
460
+ return select;
461
+ }
462
+
463
+ /**
464
+ * Builds country items without the DOM, defaulting to the ISO country catalogue.
465
+ * @param {Array<string|import('./country.js').CountryItem>} [countries] Country codes or specifications.
466
+ * @param {Pick<import('./country.js').CountrySelectOptions, 'displayLocale'|'showCode'|'sort'>} [options={}] Naming options.
467
+ * @returns {ReturnType<typeof countryItems>}
468
+ */
469
+ static countryItems(countries, options = {}) {
470
+ return countryItems(countries, options);
471
+ }
472
+
402
473
  /**
403
474
  * Creates the five-level priority preset: values 0 (lowest) to 4 (highest), each drawn as grey
404
475
  * signal bars filled to its level, except the highest, which is the one coloured level — a
@@ -480,8 +551,8 @@ export class Select extends Component {
480
551
  */
481
552
  static entity(target, options = {}) {
482
553
  const {
483
- recent = [], recentLabel = 'Recent', create = false, iconKey = 'icon', colorKey = 'color',
484
- subtitleKey = 'description', renderIcon = null,
554
+ recent = [], recentLabel = message('select.recent', options), create = false, iconKey = 'icon',
555
+ colorKey = 'color', subtitleKey = 'description', renderIcon = null,
485
556
  fixedItems = [], actions = [], renderItem = null, renderValueAdornment = null,
486
557
  ...rest
487
558
  } = options;
@@ -497,7 +568,7 @@ export class Select extends Component {
497
568
  ariaHidden: 'true'
498
569
  }, icon(value, { size: 14 }));
499
570
  };
500
- const createAction = create ? normalizeEntityCreateAction(create) : null;
571
+ const createAction = create ? normalizeEntityCreateAction(create, options) : null;
501
572
  const select = new Select(target, {
502
573
  ...rest,
503
574
  fixedItems: [...(Array.isArray(recent) ? recent : []), ...(Array.isArray(fixedItems) ? fixedItems : [])],
@@ -627,7 +698,7 @@ export class Select extends Component {
627
698
  if (!this.options.filter) return;
628
699
  const query = /** @type {HTMLInputElement} */ (this.refs.input).value;
629
700
  this._syncValueAdornment();
630
- if (!this._open) this.open();
701
+ if (!this._open) this._openPanel(false);
631
702
  if (this.options.filter === 'local') {
632
703
  this._visibleFixed = this._matchFixed(query);
633
704
  this._visibleItems = matchItems(this._items, query, this._searchKeys());
@@ -985,12 +1056,23 @@ function readSelectItem(item, reader) {
985
1056
  return null;
986
1057
  }
987
1058
 
988
- /** @param {boolean|SelectAction} value @returns {SelectAction} */
989
- function normalizeEntityCreateAction(value) {
1059
+ /**
1060
+ * Resolves a message for a preset, which hands text to the constructor before an instance exists.
1061
+ * `msg()` reads the `msg` option off whatever object borrows it, so the preset's own option counts.
1062
+ * @param {string} key Message key.
1063
+ * @param {SelectOptions} options Options the preset was given.
1064
+ * @returns {string}
1065
+ */
1066
+ function message(key, options) {
1067
+ return Component.prototype.msg.call({ options }, key);
1068
+ }
1069
+
1070
+ /** @param {boolean|SelectAction} value @param {SelectOptions} options @returns {SelectAction} */
1071
+ function normalizeEntityCreateAction(value, options) {
990
1072
  const descriptor = value === true ? {} : value;
991
1073
  return {
992
- id: descriptor.id ?? 'create', label: descriptor.label ?? 'Create new…',
993
- description: descriptor.description, group: descriptor.group ?? 'New',
1074
+ id: descriptor.id ?? 'create', label: descriptor.label ?? message('select.create', options),
1075
+ description: descriptor.description, group: descriptor.group ?? message('select.createGroup', options),
994
1076
  icon: descriptor.icon ?? 'plus', invoke: descriptor.invoke
995
1077
  };
996
1078
  }