@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
@@ -1,5 +1,6 @@
1
1
  import { Component } from '../../core/component.js';
2
2
  export type AvatarTone = 'blue' | 'teal' | 'green' | 'amber' | 'orange' | 'red' | 'pink' | 'violet' | 'slate';
3
+ export type AgentActivity = import('../../internal/agent-model.js').AgentActivity;
3
4
  export type AvatarOptions = {
4
5
  /**
5
6
  * Image URL.
@@ -33,18 +34,54 @@ export type AvatarOptions = {
33
34
  */
34
35
  tone?: AvatarTone | null;
35
36
  /**
36
- * Optional presence state.
37
+ * Optional presence state of a
38
+ * person. An agent's `activity` takes its place: when both are given, only the activity is drawn
39
+ * and named.
37
40
  */
38
41
  status?: 'online' | 'away' | 'busy' | 'offline' | null;
39
42
  /**
40
43
  * Text alternative for the presence state.
41
44
  */
42
45
  statusLabel?: string | null;
46
+ /**
47
+ * What an agent is doing: `'idle'`, `'thinking'`,
48
+ * `'working'`, `'needs-you'`, `'blocked'` or `'offline'`. Drawn as a dot whose shape and tone
49
+ * differ per activity (a square for blocked, a hollow ring for idle, a dashed ring for offline);
50
+ * its word joins the accessible name and the dot's tooltip. Wins over `status`.
51
+ */
52
+ activity?: AgentActivity | null;
53
+ /**
54
+ * The activity's word, when the default ("Working",
55
+ * "Needs you", …) is not the one to show.
56
+ */
57
+ activityLabel?: string | null;
58
+ /**
59
+ * Moves the avatar with its activity — idle breathes, thinking
60
+ * sways, working bobs, needs-you leans and blinks — in the one animation loop every animated
61
+ * avatar on the page shares. Motion is never the only signal, stops off screen and while the page
62
+ * is hidden, and returns the avatar to rest under reduced motion (the system's, or a
63
+ * `data-zx-motion="reduced"` region). While it is on, the root's `transform` belongs to the loop.
64
+ */
65
+ animate?: boolean;
66
+ /**
67
+ * Where in its activity's cycle the avatar moves, as a
68
+ * fraction from 0 up to 1 (whole turns wrap): two avatars of the same agent on one screen — a
69
+ * roster and an inspector — at different phases never move in step, and 0.5 puts them half a cycle
70
+ * apart. `null` derives the phase from the name (or the initials), so the same agent always moves
71
+ * the same way.
72
+ */
73
+ phase?: number | null;
74
+ /**
75
+ * Localized
76
+ * messages: the activity words, `agent.activity.<activity>`.
77
+ */
78
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
43
79
  };
44
80
  /**
45
81
  * A categorical tone from the design system's tone palette (`--zx-color-tone-*`).
46
82
  * @typedef {'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'} AvatarTone
47
83
  */
84
+ /** @typedef {import('../../internal/agent-model.js').AgentActivity} AgentActivity */
48
85
  /**
49
86
  * @typedef {Object} AvatarOptions
50
87
  * @property {string|null} [src=null] Image URL.
@@ -57,8 +94,28 @@ export type AvatarOptions = {
57
94
  * @property {AvatarTone|null} [tone=null] Fallback colour from the tone palette. `null` derives a
58
95
  * stable tone from the name (or the initials when there is no name), so the same person gets the
59
96
  * same colour on every screen; see {@link avatarTone}.
60
- * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state.
97
+ * @property {'online'|'away'|'busy'|'offline'|null} [status=null] Optional presence state of a
98
+ * person. An agent's `activity` takes its place: when both are given, only the activity is drawn
99
+ * and named.
61
100
  * @property {string|null} [statusLabel=null] Text alternative for the presence state.
101
+ * @property {AgentActivity|null} [activity=null] What an agent is doing: `'idle'`, `'thinking'`,
102
+ * `'working'`, `'needs-you'`, `'blocked'` or `'offline'`. Drawn as a dot whose shape and tone
103
+ * differ per activity (a square for blocked, a hollow ring for idle, a dashed ring for offline);
104
+ * its word joins the accessible name and the dot's tooltip. Wins over `status`.
105
+ * @property {string|null} [activityLabel=null] The activity's word, when the default ("Working",
106
+ * "Needs you", …) is not the one to show.
107
+ * @property {boolean} [animate=false] Moves the avatar with its activity — idle breathes, thinking
108
+ * sways, working bobs, needs-you leans and blinks — in the one animation loop every animated
109
+ * avatar on the page shares. Motion is never the only signal, stops off screen and while the page
110
+ * is hidden, and returns the avatar to rest under reduced motion (the system's, or a
111
+ * `data-zx-motion="reduced"` region). While it is on, the root's `transform` belongs to the loop.
112
+ * @property {number|null} [phase=null] Where in its activity's cycle the avatar moves, as a
113
+ * fraction from 0 up to 1 (whole turns wrap): two avatars of the same agent on one screen — a
114
+ * roster and an inspector — at different phases never move in step, and 0.5 puts them half a cycle
115
+ * apart. `null` derives the phase from the name (or the initials), so the same agent always moves
116
+ * the same way.
117
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
118
+ * messages: the activity words, `agent.activity.<activity>`.
62
119
  */
63
120
  /**
64
121
  * The tone palette, in hash order. Every entry is a valid `tone`; the hash picks among the
@@ -69,7 +126,7 @@ export type AvatarOptions = {
69
126
  export declare const AVATAR_TONES: ReadonlyArray<AvatarTone>;
70
127
  /**
71
128
  * Stable-size user image with a deterministic fallback — initials on a tone picked from the name —
72
- * and an optional presence state.
129
+ * and an optional presence state for a person, or activity for an agent.
73
130
  * @extends {Component<AvatarOptions>}
74
131
  */
75
132
  export declare class Avatar extends Component<AvatarOptions> {
@@ -88,20 +145,37 @@ export declare class Avatar extends Component<AvatarOptions> {
88
145
  tone: AvatarTone;
89
146
  status: "away" | "busy" | "offline" | "online";
90
147
  statusLabel: string;
148
+ activity: import("../../internal/agent-model.js").AgentActivity;
149
+ activityLabel: string;
150
+ animate: boolean;
151
+ phase: number;
91
152
  };
153
+ /** @type {import('../../internal/presence-loop.js').PresenceHandle|null} */
154
+ _presence: import('../../internal/presence-loop.js').PresenceHandle | null;
92
155
  static cssName: string;
93
156
  /** @type {Readonly<AvatarOptions>} */
94
157
  static defaults: Readonly<AvatarOptions>;
95
158
  /** @returns {HTMLElement} */
96
159
  render(): HTMLElement;
97
160
  /**
98
- * Replaces avatar identity and presentation values.
161
+ * Replaces avatar identity and presentation values: any option but `msg`, `phase` included, so
162
+ * an animated avatar can be moved out of step with another of the same agent while it runs.
99
163
  * @param {Partial<AvatarOptions>} values New values.
100
164
  * @returns {this}
101
165
  */
102
166
  set(values?: Partial<AvatarOptions>): this;
103
167
  /** Sets the presence state and its text alternative. @param {AvatarOptions['status']} status @param {string|null} [label=null] @returns {this} */
104
168
  setStatus(status: AvatarOptions['status'], label?: string | null): this;
169
+ /**
170
+ * Sets what an agent is doing and, optionally, the word for it. `null` clears the activity, and
171
+ * a person's `status` shows again if one is set.
172
+ * @param {AgentActivity|null} activity
173
+ * @param {string|null} [label=null] The word, when the default is not the one to show.
174
+ * @returns {this}
175
+ */
176
+ setActivity(activity: AgentActivity | null, label?: string | null): this;
177
+ /** @returns {AgentActivity|null} What the agent is doing, or null. */
178
+ getActivity(): AgentActivity | null;
105
179
  /** Returns whether the image is currently visible. @returns {boolean} */
106
180
  hasImage(): boolean;
107
181
  /** Restores an enhanced target or removes an owned root. @returns {void} */
@@ -114,8 +188,21 @@ export declare class Avatar extends Component<AvatarOptions> {
114
188
  _showImage(visible: boolean): void;
115
189
  /** Ignores a late load/error from a source that has already been replaced. @returns {boolean} */
116
190
  _isCurrentImageSource(): boolean;
191
+ /** The word for the current activity, or null without one. @returns {string|null} */
192
+ _activityWord(): string | null;
117
193
  /** @returns {void} */
118
194
  _syncStatus(): void;
195
+ /**
196
+ * Joins, follows, or leaves the shared presence loop.
197
+ * @param {AgentActivity|null} activity
198
+ * @returns {void}
199
+ */
200
+ _syncMotion(activity: AgentActivity | null): void;
201
+ /**
202
+ * The phase the avatar moves at: the `phase` option, or one derived from the name or initials.
203
+ * @returns {number} A fraction of the cycle.
204
+ */
205
+ _phase(): number;
119
206
  }
120
207
  /**
121
208
  * Derives uppercase initials from the first and last words of a name.
@@ -0,0 +1,205 @@
1
+ import { Component } from '../../core/component.js';
2
+ export type Block = import('../../internal/agent-model.js').Block;
3
+ export type Source = import('../../internal/agent-model.js').Source;
4
+ export type BlockViewOptions = {
5
+ /**
6
+ * The answer's blocks. Model text is data: every string reaches
7
+ * the page as text, through the inline grammar of `**bold**`, `` `code` `` and `[n]` citations.
8
+ */
9
+ blocks?: Block[];
10
+ /**
11
+ * Element level of a `heading` block of level 2; a level-3
12
+ * heading goes one deeper. Set it one below the heading that names the answer.
13
+ */
14
+ headingLevel?: 2 | 3 | 4 | 5;
15
+ /**
16
+ * Prose size: `'sm'` sets the answer at the interface size, for
17
+ * a conversation; `'md'` at the reading size, for a document.
18
+ */
19
+ size?: 'sm' | 'md';
20
+ /**
21
+ * Whether more is still being written. The last block stays
22
+ * open to `appendText()`, and the root is busy until `end()` or `stop()`.
23
+ */
24
+ streaming?: boolean;
25
+ /**
26
+ * The sources citations point at; their titles name the
27
+ * citation buttons.
28
+ */
29
+ sources?: Source[] | null;
30
+ /**
31
+ * Localized messages.
32
+ */
33
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
34
+ /**
35
+ * Citation listener.
36
+ */
37
+ oncite?: (event: CustomEvent<{
38
+ n: number;
39
+ source: Source | null;
40
+ }>) => void;
41
+ /**
42
+ * Artifact listener.
43
+ */
44
+ onartifact?: (event: CustomEvent<{
45
+ id: string;
46
+ }>) => void;
47
+ /**
48
+ * End-of-stream listener.
49
+ */
50
+ onend?: (event: CustomEvent<Record<string, never>>) => void;
51
+ };
52
+ export type RenderBlocksOptions = {
53
+ /**
54
+ * Element level of a level-2 `heading` block.
55
+ */
56
+ headingLevel?: 2 | 3 | 4 | 5;
57
+ /**
58
+ * Message lookup for the few words
59
+ * the blocks add (code copy, artifact kinds).
60
+ */
61
+ msg?: (key: string, ...args: unknown[]) => string;
62
+ };
63
+ /**
64
+ * An answer an agent wrote, drawn block by block as semantic elements inside `.zx-prose`, and
65
+ * written to as it streams. Finished blocks are never redrawn: `appendText()` and `append()` touch
66
+ * only the last block, so a reader's selection or focus in an earlier paragraph survives the rest
67
+ * of the answer arriving.
68
+ *
69
+ * @fires BlockView#cite
70
+ * @fires BlockView#artifact
71
+ * @fires BlockView#end
72
+ * @extends {Component<BlockViewOptions>}
73
+ */
74
+ export declare class BlockView extends Component<BlockViewOptions> {
75
+ _original: import("../../core/dom.js").TargetSnapshot;
76
+ /** @type {Block[]} */
77
+ _blocks: Block[];
78
+ /** @type {HTMLElement[]} */
79
+ _nodes: HTMLElement[];
80
+ /** @type {Source[]} */
81
+ _sources: Source[];
82
+ _streaming: boolean;
83
+ _stopped: boolean;
84
+ /** @type {HTMLElement|null} */
85
+ _stoppedNote: HTMLElement | null;
86
+ _observer: ResizeObserver;
87
+ _destroyed: boolean;
88
+ static cssName: string;
89
+ /** @type {Readonly<BlockViewOptions>} */
90
+ static defaults: Readonly<BlockViewOptions>;
91
+ /** @returns {HTMLElement} */
92
+ render(): HTMLElement;
93
+ /**
94
+ * Replaces every block, clearing a stopped state.
95
+ * @param {Block[]} blocks
96
+ * @param {{streaming?: boolean}} [options={}] `streaming: true` starts a new streamed answer
97
+ * from these blocks; otherwise the streaming state is kept.
98
+ * @returns {this}
99
+ */
100
+ setBlocks(blocks: Block[], options?: {
101
+ streaming?: boolean;
102
+ }): this;
103
+ /**
104
+ * Adds a block after the last one. The blocks before it are left as they are.
105
+ * @param {Block} block
106
+ * @returns {this}
107
+ */
108
+ append(block: Block): this;
109
+ /**
110
+ * Streams text into the answer. It continues the last paragraph, or opens one when the answer
111
+ * ends in anything else; a blank line in the text starts a new paragraph. Only the last
112
+ * paragraph is redrawn, so a marker split across two calls (`**bo` … `ld**`) resolves as soon as
113
+ * its close arrives.
114
+ * @param {string} text
115
+ * @returns {this}
116
+ */
117
+ appendText(text: string): this;
118
+ /**
119
+ * Marks the answer finished.
120
+ * @returns {this}
121
+ */
122
+ end(): this;
123
+ /**
124
+ * Marks the answer stopped where it is, with a line saying so.
125
+ * @returns {this}
126
+ */
127
+ stop(): this;
128
+ /**
129
+ * Sets the sources citations point at.
130
+ * @param {Source[]} sources
131
+ * @returns {this}
132
+ */
133
+ setSources(sources: Source[]): this;
134
+ /**
135
+ * Says whether an artifact's card has its artifact open somewhere — an inspector, a drawer — so
136
+ * the card reads as pressed and names what it controls. The application owns the open state;
137
+ * the card only reflects it.
138
+ * @param {string} id Artifact id.
139
+ * @param {{expanded?: boolean|null, controls?: string|null}} state `expanded` sets or (null)
140
+ * removes `aria-expanded`; `controls` sets or (null) removes `aria-controls`.
141
+ * @returns {this}
142
+ */
143
+ setArtifactState(id: string, state?: {
144
+ expanded?: boolean | null;
145
+ controls?: string | null;
146
+ }): this;
147
+ /** @returns {Block[]} A copy of the blocks. */
148
+ getBlocks(): Block[];
149
+ /** @returns {boolean} Whether more is still being written. */
150
+ isStreaming(): boolean;
151
+ /** @returns {string} The answer as plain text. */
152
+ toText(): string;
153
+ /** @returns {string} The answer as Markdown. */
154
+ toMarkdown(): string;
155
+ /** @returns {void} */
156
+ destroy(): void;
157
+ /**
158
+ * @private
159
+ * @param {Block} block
160
+ * @returns {void}
161
+ */
162
+ private _push;
163
+ /** @private @returns {void} */
164
+ private _redrawLast;
165
+ /** @private @returns {RenderBlocksOptions & {cite: (n: number) => Node, artifact: boolean}} */
166
+ private _renderOptions;
167
+ /** @private @param {number} n @returns {string} */
168
+ private _citeLabel;
169
+ /** @private @param {number} n @returns {Source|null} */
170
+ private _sourceAt;
171
+ /** @private @returns {void} */
172
+ private _syncState;
173
+ /**
174
+ * A wide table scrolls inside the answer; while it does, its wrapper is a named, focusable
175
+ * region so the keyboard can scroll it too. A table that fits is not a tab stop.
176
+ * @private
177
+ * @returns {void}
178
+ */
179
+ private _syncScrollers;
180
+ /** @private @param {MouseEvent} event @returns {void} */
181
+ private _onClick;
182
+ }
183
+ /**
184
+ * Citation listener payload.
185
+ * @event BlockView#cite
186
+ * @type {CustomEvent<{n: number, source: Source|null}>}
187
+ */
188
+ /**
189
+ * Artifact card listener payload.
190
+ * @event BlockView#artifact
191
+ * @type {CustomEvent<{id: string}>}
192
+ */
193
+ /**
194
+ * Fired when a streaming answer is marked finished.
195
+ * @event BlockView#end
196
+ * @type {CustomEvent<Record<string, never>>}
197
+ */
198
+ /**
199
+ * Draws blocks without a component, for a static answer: a transcript, a print view, a preview.
200
+ * Citations are plain superscripts and artifacts plain cards; use `BlockView` for them to act.
201
+ * @param {Block[]} blocks
202
+ * @param {RenderBlocksOptions} [options={}]
203
+ * @returns {DocumentFragment}
204
+ */
205
+ export declare function renderBlocks(blocks: Block[], options?: RenderBlocksOptions): DocumentFragment;
@@ -179,10 +179,10 @@ export declare class Breadcrumb extends Component<BreadcrumbOptions> {
179
179
  _renderSeparator(): HTMLElement;
180
180
  /**
181
181
  * @param {string|undefined} name Item name from a control's `data-crumb`.
182
- * @returns {void}
182
+ * @returns {CustomEvent<BreadcrumbSelectDetail>|undefined}
183
183
  * @fires Breadcrumb#select
184
184
  */
185
- _select(name: string | undefined): void;
185
+ _select(name: string | undefined): CustomEvent<BreadcrumbSelectDetail> | undefined;
186
186
  /**
187
187
  * Resolves a message through the host translator, falling back to the built-in English text.
188
188
  * @param {string} key Message key.
@@ -194,7 +194,7 @@ export declare class Breadcrumb extends Component<BreadcrumbOptions> {
194
194
  }
195
195
  /**
196
196
  * Fired when an interactive crumb is chosen, from the trail itself or from the overflow menu. A
197
- * crumb with an `href` still navigates: the event reports the choice, it does not gate it.
197
+ * crumb with an `href` navigates natively unless the selection is prevented.
198
198
  * @event Breadcrumb#select
199
199
  * @type {CustomEvent<BreadcrumbSelectDetail>}
200
200
  */
@@ -1,5 +1,3 @@
1
- /** @typedef {'agenda'|'day'|'week'|'month'|'year'} CalendarView */
2
- /** @typedef {string|((record: Record<string, any>) => unknown)} CalendarReader */
3
1
  export type CalendarView = 'agenda' | 'day' | 'week' | 'month' | 'year';
4
2
  export type CalendarReader = string | ((record: Record<string, any>) => unknown);
5
3
  export type CalendarEvent = {
@@ -85,7 +83,14 @@ export type CalendarNormalizeOptions = {
85
83
  * Unit used for numeric dates.
86
84
  */
87
85
  dateUnit?: 'milliseconds' | 'seconds';
86
+ /**
87
+ * Title of an event without one, by default the `calendar.untitled`
88
+ * message ("Untitled event").
89
+ */
90
+ untitledTitle?: string;
88
91
  };
92
+ /** @typedef {'agenda'|'day'|'week'|'month'|'year'} CalendarView */
93
+ /** @typedef {string|((record: Record<string, any>) => unknown)} CalendarReader */
89
94
  /**
90
95
  * @typedef {Object} CalendarEvent
91
96
  * @property {string|number} id Stable event identifier.
@@ -111,6 +116,8 @@ export type CalendarNormalizeOptions = {
111
116
  * @property {CalendarReader} [eventEditable='editable'] Move-policy reader.
112
117
  * @property {CalendarReader} [eventDurationEditable='durationEditable'] Resize-policy reader.
113
118
  * @property {'milliseconds'|'seconds'} [dateUnit='milliseconds'] Unit used for numeric dates.
119
+ * @property {string} [untitledTitle] Title of an event without one, by default the `calendar.untitled`
120
+ * message ("Untitled event").
114
121
  */
115
122
  /** @type {readonly CalendarView[]} */
116
123
  export declare const CALENDAR_VIEWS: readonly CalendarView[];
@@ -20,7 +20,8 @@ export type CalendarOptions = {
20
20
  */
21
21
  views?: CalendarView[];
22
22
  /**
23
- * Intl locale override.
23
+ * Intl locale override. Unset, dates follow `setLanguage()`, and
24
+ * the browser's language under an English one.
24
25
  */
25
26
  locale?: string | string[];
26
27
  /**
@@ -259,7 +260,8 @@ export type CalendarSetOptions = {
259
260
  * @property {Date|string|number|null} [date=null] Initial local anchor date; null uses today.
260
261
  * @property {CalendarView} [view='month'] Initial view.
261
262
  * @property {CalendarView[]} [views=['agenda','day','week','month','year']] Allowed views.
262
- * @property {string|string[]} [locale] Intl locale override.
263
+ * @property {string|string[]} [locale] Intl locale override. Unset, dates follow `setLanguage()`, and
264
+ * the browser's language under an English one.
263
265
  * @property {number} [weekStart=1] First weekday, 0 (Sunday) through 6 (Saturday).
264
266
  * @property {boolean} [weekNumbers=true] Show ISO week numbers in month view.
265
267
  * @property {boolean} [workweek=false] Show Monday–Friday in the week time grid.
@@ -540,6 +542,8 @@ export declare class Calendar extends Component<CalendarOptions> {
540
542
  _eventLabel(event: CalendarEvent): string;
541
543
  /** @param {Date} date @returns {string} */
542
544
  _dateTimeLabel(date: Date): string;
545
+ /** @returns {string|string[]|undefined} The locale this calendar writes its dates in. */
546
+ _locale(): string | string[] | undefined;
543
547
  /** @param {Date} date @param {Intl.DateTimeFormatOptions} options @returns {string} */
544
548
  _format(date: Date, options: Intl.DateTimeFormatOptions): string;
545
549
  /** @returns {Date} */
@@ -548,19 +552,23 @@ export declare class Calendar extends Component<CalendarOptions> {
548
552
  _dateFromTarget(target: HTMLElement): Date | null;
549
553
  /** @param {HTMLElement} target @returns {void} */
550
554
  _rememberFocusedDate(target: HTMLElement): void;
551
- /** @returns {{eventId?: string, eventAction?: string, date?: string, slot?: string}|null} */
555
+ /** @returns {{eventId?: string, eventAction?: string, date?: string, slot?: string, row?: string, column?: string}|null} */
552
556
  _focusIdentity(): {
553
557
  eventId?: string;
554
558
  eventAction?: string;
555
559
  date?: string;
556
560
  slot?: string;
561
+ row?: string;
562
+ column?: string;
557
563
  } | null;
558
- /** @param {{eventId?: string, eventAction?: string, date?: string, slot?: string}} identity @returns {void} */
564
+ /** @param {{eventId?: string, eventAction?: string, date?: string, slot?: string, row?: string, column?: string}} identity @returns {void} */
559
565
  _restoreFocus(identity: {
560
566
  eventId?: string;
561
567
  eventAction?: string;
562
568
  date?: string;
563
569
  slot?: string;
570
+ row?: string;
571
+ column?: string;
564
572
  }): void;
565
573
  /** @returns {void} */
566
574
  _scrollTimeGrid(): void;
@@ -9,6 +9,7 @@ export type ChartData = {
9
9
  datasets?: ChartDataset[];
10
10
  [key: string]: unknown;
11
11
  };
12
+ export type ChartText = (key: string, ...args: unknown[]) => string;
12
13
  export type ChartSpec = {
13
14
  /**
14
15
  * Chart type.
@@ -99,9 +100,10 @@ export type ChartOptions = {
99
100
  */
100
101
  chartOptions?: Record<string, unknown>;
101
102
  /**
102
- * Accessible canvas and summary label; blank text falls back to `Chart`.
103
+ * Accessible canvas and summary label; null or blank text reads
104
+ * the `chart.label` message ("Chart").
103
105
  */
104
- label?: string;
106
+ label?: string | null;
105
107
  /**
106
108
  * Accessible description.
107
109
  */
@@ -115,17 +117,20 @@ export type ChartOptions = {
115
117
  */
116
118
  loading?: boolean;
117
119
  /**
118
- * Empty-state text.
120
+ * Empty-state text, by default the `chart.empty` message
121
+ * ("No chart data"). Null shows none.
119
122
  */
120
- emptyText?: string;
123
+ emptyText?: string | null;
121
124
  /**
122
- * Loading-state text.
125
+ * Loading-state text, by default the `chart.loading` message
126
+ * ("Loading chart…"). Null shows none.
123
127
  */
124
- loadingText?: string;
128
+ loadingText?: string | null;
125
129
  /**
126
- * Error fallback text.
130
+ * Error fallback text, by default the `chart.error` message
131
+ * ("Unable to render chart"). Null shows none.
127
132
  */
128
- errorText?: string;
133
+ errorText?: string | null;
129
134
  /**
130
135
  * Responsive container aspect ratio.
131
136
  */
@@ -156,6 +161,7 @@ export type ChartOptions = {
156
161
  };
157
162
  /** @typedef {{label?: string, data?: unknown[], [key: string]: unknown}} ChartDataset */
158
163
  /** @typedef {{labels?: unknown[], datasets?: ChartDataset[], [key: string]: unknown}} ChartData */
164
+ /** @typedef {(key: string, ...args: unknown[]) => string} ChartText Resolves a message. */
159
165
  /**
160
166
  * @typedef {Object} ChartSpec
161
167
  * @property {string} type Chart type.
@@ -194,13 +200,17 @@ export type ChartOptions = {
194
200
  * @property {string} [type='bar'] Chart type passed to the adapter.
195
201
  * @property {ChartData} [data={labels: [], datasets: []}] Chart data.
196
202
  * @property {Record<string, unknown>} [chartOptions={}] Engine-specific options.
197
- * @property {string} [label='Chart'] Accessible canvas and summary label; blank text falls back to `Chart`.
203
+ * @property {string|null} [label=null] Accessible canvas and summary label; null or blank text reads
204
+ * the `chart.label` message ("Chart").
198
205
  * @property {string} [description=''] Accessible description.
199
206
  * @property {'hidden'|'visible'} [summary='hidden'] Semantic data-table presentation.
200
207
  * @property {boolean} [loading=false] Initial loading state.
201
- * @property {string} [emptyText='No chart data'] Empty-state text.
202
- * @property {string} [loadingText='Loading chart…'] Loading-state text.
203
- * @property {string} [errorText='Unable to render chart'] Error fallback text.
208
+ * @property {string|null} [emptyText] Empty-state text, by default the `chart.empty` message
209
+ * ("No chart data"). Null shows none.
210
+ * @property {string|null} [loadingText] Loading-state text, by default the `chart.loading` message
211
+ * ("Loading chart…"). Null shows none.
212
+ * @property {string|null} [errorText] Error fallback text, by default the `chart.error` message
213
+ * ("Unable to render chart"). Null shows none.
204
214
  * @property {string} [aspectRatio='16 / 9'] Responsive container aspect ratio.
205
215
  * @property {(event: CustomEvent<{instance: unknown}>) => void} [onready] Engine-ready listener.
206
216
  * @property {(event: CustomEvent<{data: ChartData, type: string}>) => void} [onupdate] Update listener.
@@ -274,6 +284,8 @@ export declare class Chart extends Component<ChartOptions> {
274
284
  _destroyHandle(): void;
275
285
  /** @returns {void} */
276
286
  _syncState(): void;
287
+ /** @returns {string} What an error without a message of its own says. */
288
+ _errorText(): string;
277
289
  /** @returns {void} */
278
290
  _renderSummary(): void;
279
291
  }
@@ -310,7 +322,7 @@ export declare function isEmptyChartData(data: ChartData): boolean;
310
322
  /**
311
323
  * Builds the semantic table mirrored alongside the canvas.
312
324
  * @param {ChartData} data Chart data.
313
- * @param {string} label Caption.
325
+ * @param {string} [label] Caption, by default the `chart.summary` message ("Chart data").
314
326
  * @returns {HTMLTableElement}
315
327
  */
316
328
  export declare function chartSummaryTable(data: ChartData, label?: string): HTMLTableElement;
@@ -13,9 +13,10 @@ export type CodeEditorOptions = {
13
13
  */
14
14
  language?: string;
15
15
  /**
16
- * Accessible editor label.
16
+ * Accessible editor label; null reads the `codeEditor.label`
17
+ * message ("Code editor").
17
18
  */
18
- label?: string;
19
+ label?: string | null;
19
20
  /**
20
21
  * Placeholder text.
21
22
  */
@@ -82,6 +83,8 @@ export declare class CodeEditor extends Component<CodeEditorOptions> {
82
83
  _position: HTMLElement;
83
84
  _header: HTMLElement;
84
85
  _input: HTMLTextAreaElement;
86
+ _committedValue: any;
87
+ _indentEditing: boolean;
85
88
  /** Set by Escape: the next Tab moves focus instead of indenting. */
86
89
  _tabReleased: boolean;
87
90
  static cssName: string;
@@ -112,6 +115,8 @@ export declare class CodeEditor extends Component<CodeEditorOptions> {
112
115
  setReadOnly(value: boolean): this;
113
116
  /** @param {KeyboardEvent} event @returns {void} */
114
117
  _handleKeydown(event: KeyboardEvent): void;
118
+ /** Commits once, whether the browser emits change before blur or the fallback edited text. @returns {void} */
119
+ _commitValue(): void;
115
120
  /** @returns {void} */
116
121
  _updatePosition(): void;
117
122
  /** @returns {void} */