@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
@@ -11,18 +11,22 @@
11
11
  * @property {(key: string) => void} remove Deletes a single key.
12
12
  * @property {() => string[]} keys Lists the namespace's keys without their prefix.
13
13
  * @property {() => void} clear Deletes every key in the namespace, leaving other namespaces alone.
14
+ * @property {(keys: string[]) => string[]} migrateLegacy Copies listed valid legacy keys once if absent.
14
15
  */
15
16
 
16
17
  /** Every key written by this module carries this prefix plus its namespace. */
17
- const PREFIX = 'zx:';
18
+ const PREFIX = 'zx2:';
19
+ /** The previous format cannot distinguish namespace separators from key separators. */
20
+ const LEGACY_PREFIX = 'zx:';
18
21
  /** Written and removed once to detect an area that exists but refuses writes. */
19
22
  const PROBE_KEY = 'zx:__probe__';
20
23
 
21
24
  /**
22
25
  * Creates a namespaced, JSON-encoded view of `localStorage` or `sessionStorage`.
23
26
  *
24
- * Every key is stored as `zx:<namespace>:<key>`, so several features can share one origin without
25
- * colliding, and `clear()` only touches the namespace it belongs to. When the storage area is
27
+ * Keys use `zx2:<namespace length>:<namespace>:<key>`, so namespaces cannot overlap. Existing
28
+ * `zx:` keys are copied only when explicitly requested through `migrateLegacy(keys)`; they are
29
+ * never deleted. `clear()` only touches the current namespace. When the storage area is
26
30
  * unavailable or refuses a write — private browsing, a full quota, cookies disabled — the view
27
31
  * transparently falls back to an in-memory map that lives as long as the page, so callers never
28
32
  * need a try/catch and never see an exception.
@@ -33,7 +37,10 @@ const PROBE_KEY = 'zx:__probe__';
33
37
  */
34
38
  export function storage(namespace, options = {}) {
35
39
  const { area = 'local' } = options;
36
- const prefix = `${PREFIX}${String(namespace ?? '')}:`;
40
+ const name = String(namespace ?? '');
41
+ const prefix = `${PREFIX}${name.length}:${name}:`;
42
+ const legacyPrefix = `${LEGACY_PREFIX}${name}:`;
43
+ const migratedPrefix = `zx2m:${name.length}:${name}:`;
37
44
  /** @type {Map<string, string>} */
38
45
  const memory = new Map();
39
46
  let backing = resolveArea(area);
@@ -42,7 +49,10 @@ export function storage(namespace, options = {}) {
42
49
  const readRaw = (key) => {
43
50
  if (backing !== null) {
44
51
  try {
45
- return backing.getItem(key);
52
+ const raw = backing.getItem(key);
53
+ if (raw === null) memory.delete(key);
54
+ else memory.set(key, raw);
55
+ return raw;
46
56
  } catch {
47
57
  backing = null;
48
58
  }
@@ -52,16 +62,27 @@ export function storage(namespace, options = {}) {
52
62
 
53
63
  /** @param {string} key @param {string} raw @returns {void} */
54
64
  const writeRaw = (key, raw) => {
65
+ // Retain successful writes as well: a later quota failure must not hide this view's data.
66
+ memory.set(key, raw);
55
67
  if (backing !== null) {
56
68
  try {
57
69
  backing.setItem(key, raw);
58
70
  return;
59
71
  } catch {
72
+ // Reconcile entries that another storage user may have changed or removed, while reads
73
+ // still work. The failed write itself stays in memory as the caller's intended value.
74
+ for (const cached of memory.keys()) {
75
+ if (cached === key) continue;
76
+ try {
77
+ const current = backing.getItem(cached);
78
+ if (current === null) memory.delete(cached);
79
+ else memory.set(cached, current);
80
+ } catch { break; }
81
+ }
60
82
  // A quota error mid-session degrades this view to memory rather than throwing.
61
83
  backing = null;
62
84
  }
63
85
  }
64
- memory.set(key, raw);
65
86
  };
66
87
 
67
88
  /** @param {string} key @returns {void} */
@@ -94,6 +115,38 @@ export function storage(namespace, options = {}) {
94
115
  };
95
116
 
96
117
  return {
118
+ /**
119
+ * Copies exact legacy keys once without removing the originals. Existing current values win;
120
+ * missing keys are also marked handled. Invalid legacy JSON remains eligible for a later retry.
121
+ * Handled markers survive `remove()` and `clear()`, preventing a deleted value from returning.
122
+ * @param {string[]} keys Legacy keys known to belong to this caller.
123
+ * @returns {string[]} Names copied successfully.
124
+ */
125
+ migrateLegacy(keys) {
126
+ const migrated = [];
127
+ for (const key of new Set(Array.isArray(keys) ? keys.map(String) : [])) {
128
+ const destination = prefix + key;
129
+ const marker = migratedPrefix + key;
130
+ if (readRaw(marker) != null) continue;
131
+ if (readRaw(destination) != null) {
132
+ writeRaw(marker, '1');
133
+ continue;
134
+ }
135
+ const raw = readRaw(legacyPrefix + key);
136
+ if (raw == null) {
137
+ writeRaw(marker, '1');
138
+ continue;
139
+ }
140
+ try { JSON.parse(raw); } catch { continue; }
141
+ writeRaw(destination, raw);
142
+ if (readRaw(destination) === raw) {
143
+ writeRaw(marker, '1');
144
+ migrated.push(key);
145
+ }
146
+ }
147
+ return migrated;
148
+ },
149
+
97
150
  /**
98
151
  * Reads a value, returning the fallback for a missing key or unparseable JSON.
99
152
  * @param {string} key Key within the namespace.
@@ -10,30 +10,25 @@ import { Table } from '../components/table/table.js';
10
10
  import { Timebox } from '../components/timebox/timebox.js';
11
11
  import { Toggle } from '../components/toggle/toggle.js';
12
12
  import { formatDate, parseDate } from '../core/date.js';
13
+ import {
14
+ attributes, bool, createCallQueue, forwardedResult, isDomCall, json, normalizeAttributes,
15
+ normalizeNumberOrString, normalizeSelectable, number, text
16
+ } from './definitions.js';
17
+ import { KIT_ELEMENTS } from './kit.js';
13
18
  import { INVALID_ATTRIBUTE, coerceAttribute, serializeAttribute } from './reflect.js';
14
19
 
15
- /** @typedef {'string'|'number'|'boolean'|'json'} AttributeType */
16
- /**
17
- * @typedef {Object} ElementAttribute
18
- * @property {AttributeType} [type='string'] Attribute representation.
19
- * @property {string|null} [option] Component option name; null keeps the value on the host only.
20
- * @property {string} [property] Host property name; defaults to camel-cased attribute name.
21
- * @property {unknown} [default] Property value used while the attribute is absent.
22
- * @property {boolean} [always=false] Pass the default to the component during initial creation.
23
- * @property {boolean} [rebuild=false] Recreate the component when this value changes.
24
- * @property {(value: unknown, host: HTMLElement) => unknown} [normalize] Value adapter.
25
- * @property {(value: unknown, host: HTMLElement) => string|null|typeof INVALID_ATTRIBUTE} [serialize]
26
- * Property serializer override.
27
- * @property {(component: InstanceType<typeof import('../core/component.js').Component>, value: any, host: HTMLElement) => void} [set]
28
- * Live component setter.
29
- * @property {(component: InstanceType<typeof import('../core/component.js').Component>, host: HTMLElement) => unknown} [get]
30
- * Live component getter.
31
- */
32
- /** @typedef {Record<string, AttributeType|ElementAttribute>} ElementAttributeMap */
20
+ /** @typedef {import('./definitions.js').ElementAttribute} ElementAttribute */
21
+ /** @typedef {import('./definitions.js').ElementAttributeMap} ElementAttributeMap */
22
+ /** @typedef {import('./definitions.js').ElementMethodMap} ElementMethodMap */
33
23
  /**
34
24
  * @typedef {Object} ElementWrapperOptions
35
25
  * @property {boolean} [formAssociated=false] Whether the element participates in native forms.
36
26
  * @property {ElementAttributeMap} [attrs={}] Reflected attribute definitions.
27
+ * @property {string[]|null} [events=null] The component's events. Declared, each also reaches the
28
+ * host under its plain name, and no DOM event of that name passes through from inside the
29
+ * component. Left out, the common `zx-*` set is bridged.
30
+ * @property {ElementMethodMap|null} [methods=null] Component methods the element forwards. Declared,
31
+ * the element also carries its live values across a rebuild and across removal.
37
32
  */
38
33
 
39
34
  const COMPONENT_EVENTS = Object.freeze([
@@ -41,6 +36,9 @@ const COMPONENT_EVENTS = Object.freeze([
41
36
  'query', 'loaded', 'rowclick', 'rowdblclick', 'sort', 'selectionchange', 'datachange'
42
37
  ]);
43
38
 
39
+ /** Form-control accessors every wrapper carries; an element that is no form control may reuse the names. */
40
+ const FORM_ACCESSORS = Object.freeze(['form', 'labels', 'validity', 'validationMessage', 'willValidate']);
41
+
44
42
  const TOGGLE_ATTRS = attributes({
45
43
  checked: bool({ always: true, set: (component, value) => component.set(value, { silent: true }), get: (component) => component.get() }),
46
44
  value: text({ default: true }),
@@ -158,7 +156,8 @@ const ELEMENTS = Object.freeze([
158
156
  ['groupbox', Groupbox, { formAssociated: false, attrs: GROUPBOX_ATTRS }],
159
157
  ['tabbox', Tabbox, { formAssociated: false, attrs: TABBOX_ATTRS }],
160
158
  ['table', Table, { formAssociated: false, attrs: TABLE_ATTRS }],
161
- ['dialog', Dialog, { formAssociated: false, attrs: DIALOG_ATTRS }]
159
+ ['dialog', Dialog, { formAssociated: false, attrs: DIALOG_ATTRS }],
160
+ ...KIT_ELEMENTS
162
161
  ]);
163
162
 
164
163
  /**
@@ -166,13 +165,23 @@ const ELEMENTS = Object.freeze([
166
165
  * Groupbox and Dialog wrappers adopt their host's initial children as component content;
167
166
  * other wrappers leave unrelated host children untouched and append their component root.
168
167
  *
168
+ * A wrapper that declares `methods` forwards them: `element.upsert(item)` calls the component, and
169
+ * a call made while no component exists is queued and runs, in order, once it does. A forwarded
170
+ * call returns the component's answer, with the component itself replaced by the element; a
171
+ * queued call returns undefined. A wrapper that declares `events` dispatches each one on the host
172
+ * under its plain name as well as `zx-<type>`. The plain event does not bubble; `zx-<type>` does.
173
+ *
169
174
  * @param {typeof import('../core/component.js').Component} ComponentClass Component constructor.
170
175
  * @param {ElementWrapperOptions} [wrapperOptions={}] Wrapper behavior.
171
176
  * @returns {typeof HTMLElement} Custom-element constructor.
172
177
  */
173
- export function elementFor(ComponentClass, { formAssociated = false, attrs = {} } = {}) {
178
+ export function elementFor(ComponentClass, {
179
+ formAssociated = false, attrs = {}, events = null, methods = null
180
+ } = {}) {
174
181
  const definitions = normalizeAttributes(attrs);
175
- const attributeNames = Object.freeze(Object.keys(definitions));
182
+ const attributeNames = Object.freeze(
183
+ Object.keys(definitions).filter((name) => definitions[name].observed));
184
+ const byProperty = new Map(Object.values(definitions).map((definition) => [definition.property, definition]));
176
185
  const contentElement = ComponentClass === Groupbox || ComponentClass === Dialog;
177
186
 
178
187
  class ZxElement extends HTMLElement {
@@ -193,16 +202,18 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
193
202
  this._contentNodes = null;
194
203
  this._disabledByForm = false;
195
204
  this._applying = false;
205
+ this._calls = createCallQueue();
196
206
  this._internals = formAssociated && typeof this.attachInternals === 'function' ? this.attachInternals() : null;
197
207
  }
198
208
 
199
- /** Instantiates and mounts the backing component. @returns {void} */
209
+ /** Instantiates and mounts the backing component, then runs the calls queued for it. @returns {void} */
200
210
  connectedCallback() {
201
211
  if (this._component) return;
202
212
  this._upgradeProperties(definitions);
203
213
  if (contentElement && this._contentNodes === null) this._contentNodes = Array.from(this.childNodes);
204
214
  if (formAssociated && this._defaults === null) this._captureDefaults(definitions);
205
215
  this._createComponent(ComponentClass, definitions, contentElement);
216
+ this._calls.drain((name, args) => this._invoke(name, args), () => this._component !== null);
206
217
  }
207
218
 
208
219
  /** Destroys the backing component and all bridged listeners. @returns {void} */
@@ -331,12 +342,15 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
331
342
  _createComponent(Constructor, defs, adoptsContent) {
332
343
  const options = {};
333
344
  for (const [name, definition] of Object.entries(defs)) {
334
- const supplied = this._propertyValues.has(definition.property) || this.hasAttribute(name) || definition.always;
335
- if (!supplied || definition.option === null) continue;
345
+ if (!this._supplied(name, definition) || definition.option === null) continue;
336
346
  const value = this._currentValue(name, definition);
337
347
  if (value === INVALID_ATTRIBUTE || value === undefined) continue;
338
348
  options[definition.option] = normalizeValue(definition, value, this);
339
349
  }
350
+ // As options, so an event fired during construction (a chart's `ready`) is heard as well.
351
+ for (const type of events ?? []) {
352
+ options[`on${type}`] = (event) => this._dispatchBridged(Constructor, type, event, true);
353
+ }
340
354
 
341
355
  let content = null;
342
356
  if (adoptsContent) {
@@ -353,8 +367,7 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
353
367
 
354
368
  for (const [name, definition] of Object.entries(defs)) {
355
369
  if (definition.option !== null || !definition.set) continue;
356
- const supplied = this._propertyValues.has(definition.property) || this.hasAttribute(name) || definition.always;
357
- if (!supplied) continue;
370
+ if (!this._supplied(name, definition)) continue;
358
371
  const value = this._currentValue(name, definition);
359
372
  if (value !== INVALID_ATTRIBUTE && value !== undefined) this._applyValue(name, definition, value, true);
360
373
  }
@@ -362,6 +375,17 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
362
375
  this._syncFormState(ComponentClass);
363
376
  }
364
377
 
378
+ /**
379
+ * @param {string} name
380
+ * @param {ElementAttribute} definition
381
+ * @returns {boolean} Whether a value was given for this definition, or its default always applies.
382
+ */
383
+ _supplied(name, definition) {
384
+ return this._propertyValues.has(definition.property)
385
+ || (definition.observed && this.hasAttribute(name))
386
+ || definition.always;
387
+ }
388
+
365
389
  /**
366
390
  * @param {InstanceType<typeof import('../core/component.js').Component>} component
367
391
  * @param {typeof import('../core/component.js').Component} Constructor
@@ -370,42 +394,107 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
370
394
  _bridgeEvents(component, Constructor) {
371
395
  this._bridgeAbort?.abort();
372
396
  this._bridgeAbort = new AbortController();
373
- for (const type of COMPONENT_EVENTS) {
374
- component.on(type, (event) => {
375
- if (this._applying) return;
376
- this._syncFormState(Constructor);
377
- const bridged = new CustomEvent(`zx-${type}`, {
378
- detail: event.detail ?? {},
379
- bubbles: true,
380
- composed: true,
381
- cancelable: true
382
- });
383
- this.dispatchEvent(bridged);
384
- if (bridged.defaultPrevented) event.preventDefault();
385
- });
386
- component.el.addEventListener(`zx-${type}`, (event) => event.stopPropagation(), {
387
- signal: this._bridgeAbort.signal
388
- });
397
+ const stop = (event) => event.stopPropagation();
398
+ const { signal } = this._bridgeAbort;
399
+ for (const type of events ?? COMPONENT_EVENTS) {
400
+ component.el.addEventListener(`zx-${type}`, stop, { signal });
401
+ if (events) component.el.addEventListener(type, stop, { signal });
402
+ else component.on(type, (event) => this._dispatchBridged(Constructor, type, event, false));
403
+ }
404
+ }
405
+
406
+ /**
407
+ * Re-dispatches a component event on the host. Either copy being cancelled cancels the original.
408
+ * @param {typeof import('../core/component.js').Component} Constructor
409
+ * @param {string} type Component event name.
410
+ * @param {Event & {detail?: Record<string, unknown>}} event Component event.
411
+ * @param {boolean} plain Whether the plain name is dispatched too.
412
+ * @returns {void}
413
+ */
414
+ _dispatchBridged(Constructor, type, event, plain) {
415
+ if (this._applying) return;
416
+ this._syncFormState(Constructor);
417
+ const detail = event.detail ?? {};
418
+ const bridged = new CustomEvent(`zx-${type}`, { detail, bubbles: true, composed: true, cancelable: true });
419
+ this.dispatchEvent(bridged);
420
+ if (bridged.defaultPrevented) event.preventDefault();
421
+ if (!plain) return;
422
+ const named = new CustomEvent(type, { detail, cancelable: true });
423
+ this.dispatchEvent(named);
424
+ if (named.defaultPrevented) event.preventDefault();
425
+ }
426
+
427
+ /**
428
+ * Runs a forwarded call, or queues it until a component exists.
429
+ * @param {string} name Method name.
430
+ * @param {unknown[]} args Call arguments.
431
+ * @returns {unknown}
432
+ */
433
+ _forward(name, args) {
434
+ if (this._component) return this._invoke(name, args);
435
+ this._calls.push(name, args);
436
+ return undefined;
437
+ }
438
+
439
+ /** @param {string} name @param {unknown[]} args @returns {unknown} */
440
+ _invoke(name, args) {
441
+ const component = this._component;
442
+ const result = component[name](...args);
443
+ this._recordProperties(methods?.[name]?.(args));
444
+ return forwardedResult(result, component, this);
445
+ }
446
+
447
+ /**
448
+ * Brings properties in step with what a forwarded method changed, without applying it again.
449
+ * @param {Record<string, unknown>|null|undefined} changed Values by property name.
450
+ * @returns {void}
451
+ */
452
+ _recordProperties(changed) {
453
+ for (const [property, value] of Object.entries(changed ?? {})) {
454
+ const definition = byProperty.get(property);
455
+ if (!definition || value === undefined) continue;
456
+ this._propertyValues.set(property, value);
457
+ this._reflectProperty(definition, value);
458
+ }
459
+ }
460
+
461
+ /**
462
+ * Copies the component's live values to the host, so the next component starts where this one
463
+ * stopped. Only an element that forwards methods can drift from what it was given.
464
+ * @param {ElementAttribute|null} changed The definition being replaced, which keeps its new value.
465
+ * @returns {void}
466
+ */
467
+ _keepLiveValues(changed) {
468
+ if (!methods) return;
469
+ for (const definition of Object.values(definitions)) {
470
+ if (!definition.get || definition === changed) continue;
471
+ this._propertyValues.set(definition.property, definition.get(this._component, this));
389
472
  }
390
473
  }
391
474
 
392
- /** @returns {void} */
393
- _destroyComponent() {
475
+ /** @param {ElementAttribute|null} [changed=null] @returns {void} */
476
+ _destroyComponent(changed = null) {
394
477
  this._bridgeAbort?.abort();
395
478
  this._bridgeAbort = null;
396
479
  if (!this._component) return;
480
+ this._keepLiveValues(changed);
397
481
  this._component.destroy();
398
482
  this._component = null;
399
483
  }
400
484
 
401
- /** @param {Record<string, ElementAttribute>} defs @param {boolean} adoptsContent @returns {void} */
402
- _rebuildComponent(defs, adoptsContent = contentElement) {
485
+ /**
486
+ * @param {Record<string, ElementAttribute>} defs
487
+ * @param {boolean} [adoptsContent]
488
+ * @param {ElementAttribute|null} [changed=null] The definition that asked for the rebuild.
489
+ * @returns {void}
490
+ */
491
+ _rebuildComponent(defs, adoptsContent = contentElement, changed = null) {
403
492
  if (!this._component) return;
404
493
  if (adoptsContent && this._contentNodes) {
405
494
  const fragment = document.createDocumentFragment();
406
495
  fragment.append(...this._contentNodes);
407
496
  }
408
- this._destroyComponent();
497
+ this._destroyComponent(changed);
409
498
  this._createComponent(ComponentClass, defs, adoptsContent);
410
499
  }
411
500
 
@@ -419,7 +508,7 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
419
508
  _applyValue(name, definition, value, initial = false) {
420
509
  if (!this._component) return;
421
510
  if (definition.rebuild && !initial) {
422
- this._rebuildComponent(definitions);
511
+ this._rebuildComponent(definitions, contentElement, definition);
423
512
  return;
424
513
  }
425
514
  if (!definition.set) {
@@ -453,7 +542,7 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
453
542
  const { formValue, state, empty } = currentFormValue(Constructor, this._component, this);
454
543
  this._internals.setFormValue(formValue, state);
455
544
  if ((Constructor === Select || Constructor === Datebox) && this.hasAttribute('required') && empty) {
456
- const message = Constructor === Datebox ? 'Please enter a date.' : 'Please select a value.';
545
+ const message = this._component.msg(Constructor === Datebox ? 'datebox.required' : 'select.required');
457
546
  this._internals.setValidity({ valueMissing: true }, message, this._component.refs.input);
458
547
  } else {
459
548
  this._internals.setValidity({});
@@ -472,10 +561,17 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
472
561
  this._applyValue(entry[0], entry[1], value);
473
562
  }
474
563
 
564
+ /** @param {ElementAttribute} definition @returns {unknown} The attribute's value; undefined without one. */
565
+ _attributeValue(definition) {
566
+ return definition.observed
567
+ ? coerceAttribute(this.getAttribute(definition.attribute), definition.type)
568
+ : undefined;
569
+ }
570
+
475
571
  /** @param {string} name @param {ElementAttribute} definition @returns {unknown} */
476
572
  _currentValue(name, definition) {
477
573
  if (this._propertyValues.has(definition.property)) return this._propertyValues.get(definition.property);
478
- const value = coerceAttribute(this.getAttribute(name), definition.type);
574
+ const value = this._attributeValue(definition);
479
575
  return value === undefined ? definition.default : value;
480
576
  }
481
577
 
@@ -483,7 +579,7 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
483
579
  _readProperty(definition) {
484
580
  if (this._component && definition.get) return definition.get(this._component, this);
485
581
  if (this._propertyValues.has(definition.property)) return this._propertyValues.get(definition.property);
486
- const value = coerceAttribute(this.getAttribute(definition.attribute), definition.type);
582
+ const value = this._attributeValue(definition);
487
583
  if (value === INVALID_ATTRIBUTE || value === undefined) return cloneDefault(definition.default);
488
584
  return value;
489
585
  }
@@ -491,23 +587,29 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
491
587
  /** @param {ElementAttribute} definition @param {unknown} value @returns {void} */
492
588
  _writeProperty(definition, value) {
493
589
  this._propertyValues.set(definition.property, value);
590
+ this._reflectProperty(definition, value);
591
+ this._applyValue(definition.attribute, definition, value);
592
+ }
593
+
594
+ /** @param {ElementAttribute} definition @param {unknown} value @returns {void} */
595
+ _reflectProperty(definition, value) {
596
+ if (!definition.reflect) return;
494
597
  const serialized = definition.serialize ?
495
598
  definition.serialize(value, this) : serializeAttribute(value, definition.type);
496
- if (serialized !== INVALID_ATTRIBUTE) {
497
- this._reflecting.add(definition.attribute);
498
- try {
499
- if (serialized === null) this.removeAttribute(definition.attribute);
500
- else this.setAttribute(definition.attribute, serialized);
501
- } finally {
502
- this._reflecting.delete(definition.attribute);
503
- }
599
+ if (serialized === INVALID_ATTRIBUTE) return;
600
+ this._reflecting.add(definition.attribute);
601
+ try {
602
+ if (serialized === null) this.removeAttribute(definition.attribute);
603
+ else this.setAttribute(definition.attribute, serialized);
604
+ } finally {
605
+ this._reflecting.delete(definition.attribute);
504
606
  }
505
- this._applyValue(definition.attribute, definition, value);
506
607
  }
507
608
  }
508
609
 
509
610
  for (const definition of Object.values(definitions)) {
510
- if (Object.prototype.hasOwnProperty.call(ZxElement.prototype, definition.property)) continue;
611
+ const owned = Object.prototype.hasOwnProperty.call(ZxElement.prototype, definition.property);
612
+ if (owned && (formAssociated || !FORM_ACCESSORS.includes(definition.property))) continue;
511
613
  Object.defineProperty(ZxElement.prototype, definition.property, {
512
614
  configurable: true,
513
615
  enumerable: true,
@@ -516,6 +618,16 @@ export function elementFor(ComponentClass, { formAssociated = false, attrs = {}
516
618
  });
517
619
  }
518
620
 
621
+ for (const name of Object.keys(methods ?? {})) {
622
+ Object.defineProperty(ZxElement.prototype, name, {
623
+ configurable: true,
624
+ writable: true,
625
+ value(...args) {
626
+ return isDomCall(name, args) ? HTMLElement.prototype[name].apply(this, args) : this._forward(name, args);
627
+ }
628
+ });
629
+ }
630
+
519
631
  return ZxElement;
520
632
  }
521
633
 
@@ -537,59 +649,6 @@ export function defineElements(prefix = 'zx') {
537
649
  }
538
650
  }
539
651
 
540
- /** @param {ElementAttributeMap} attrs @returns {Readonly<Record<string, ElementAttribute>>} */
541
- function normalizeAttributes(attrs) {
542
- const normalized = {};
543
- for (const [attribute, definition] of Object.entries(attrs)) {
544
- const details = typeof definition === 'string' ? { type: definition } : { ...definition };
545
- const property = details.property ?? camelCase(attribute);
546
- normalized[attribute] = Object.freeze({
547
- type: details.type ?? 'string',
548
- option: Object.prototype.hasOwnProperty.call(details, 'option') ? details.option : property,
549
- property,
550
- default: details.default,
551
- always: Boolean(details.always),
552
- rebuild: Boolean(details.rebuild),
553
- normalize: details.normalize,
554
- serialize: details.serialize,
555
- set: details.set,
556
- get: details.get,
557
- attribute
558
- });
559
- }
560
- return Object.freeze(normalized);
561
- }
562
-
563
- /** @param {Record<string, ElementAttribute>} value @returns {Readonly<Record<string, ElementAttribute>>} */
564
- function attributes(value) {
565
- return normalizeAttributes(value);
566
- }
567
-
568
- /** @param {Partial<ElementAttribute>} [options={}] @returns {ElementAttribute} */
569
- function text(options = {}) {
570
- return { type: 'string', ...options };
571
- }
572
-
573
- /** @param {Partial<ElementAttribute>} [options={}] @returns {ElementAttribute} */
574
- function number(options = {}) {
575
- return { type: 'number', ...options };
576
- }
577
-
578
- /** @param {Partial<ElementAttribute>} [options={}] @returns {ElementAttribute} */
579
- function bool(options = {}) {
580
- return { type: 'boolean', default: false, always: true, ...options };
581
- }
582
-
583
- /** @param {Partial<ElementAttribute>} [options={}] @returns {ElementAttribute} */
584
- function json(options = {}) {
585
- return { type: 'json', ...options };
586
- }
587
-
588
- /** @param {string} value @returns {string} */
589
- function camelCase(value) {
590
- return value.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
591
- }
592
-
593
652
  /** @param {ElementAttribute} definition @param {unknown} value @param {HTMLElement} host @returns {unknown} */
594
653
  function normalizeValue(definition, value, host) {
595
654
  return definition.normalize ? definition.normalize(value, host) : value;
@@ -615,20 +674,6 @@ function normalizeFilter(value) {
615
674
  return value;
616
675
  }
617
676
 
618
- /** @param {unknown} value @returns {unknown} */
619
- function normalizeSelectable(value) {
620
- if (value === '' || value === 'true') return 'single';
621
- if (value === 'false') return false;
622
- return value;
623
- }
624
-
625
- /** @param {unknown} value @returns {unknown} */
626
- function normalizeNumberOrString(value) {
627
- if (typeof value !== 'string' || value.trim() === '') return value;
628
- const numeric = Number(value);
629
- return Number.isFinite(numeric) ? numeric : value;
630
- }
631
-
632
677
  /** @param {unknown} value @returns {unknown} */
633
678
  function normalizeTabs(value) {
634
679
  if (!Array.isArray(value)) return value;
@@ -708,9 +753,12 @@ function restoredFormValue(Constructor, state) {
708
753
  return state;
709
754
  }
710
755
 
711
- /** @param {unknown} value @returns {unknown} */
756
+ /** @param {unknown} value @returns {unknown} A copy, so a caller can never reach the shared default. */
712
757
  function cloneDefault(value) {
713
- if (Array.isArray(value)) return value.slice();
758
+ if (Array.isArray(value)) return value.map(cloneDefault);
714
759
  if (value instanceof Date) return new Date(value.getTime());
760
+ if (value && Object.getPrototypeOf(value) === Object.prototype) {
761
+ return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneDefault(entry)]));
762
+ }
715
763
  return value;
716
764
  }