@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,6 +1,9 @@
1
1
  /**
2
- * Attribute value types supported by the custom-element wrappers.
3
- * @typedef {'string'|'number'|'boolean'|'json'} AttributeType
2
+ * Attribute value types supported by the custom-element wrappers. `boolean` goes by presence, so
3
+ * an absent attribute means false. `flag` is the shape of HTML's `draggable="false"`, for an option
4
+ * that is on (or undecided) by default: absent keeps the default, `"false"` turns it off, anything
5
+ * else turns it on.
6
+ * @typedef {'string'|'number'|'boolean'|'flag'|'json'} AttributeType
4
7
  */
5
8
 
6
9
  /** Sentinel returned when an attribute value cannot be safely applied. */
@@ -20,6 +23,7 @@ export function coerceAttribute(value, type = 'string', warn = console.warn) {
20
23
  if (type === 'boolean') return value !== null;
21
24
  if (value === null) return undefined;
22
25
  if (type === 'string') return value;
26
+ if (type === 'flag') return value !== 'false';
23
27
 
24
28
  if (type === 'number') {
25
29
  const number = Number(value);
@@ -49,6 +53,7 @@ export function serializeAttribute(value, type = 'string', warn = console.warn)
49
53
  assertType(type);
50
54
  if (type === 'boolean') return value ? '' : null;
51
55
  if (value === null || value === undefined) return null;
56
+ if (type === 'flag') return value ? '' : 'false';
52
57
 
53
58
  if (type === 'number') {
54
59
  const number = Number(value);
@@ -73,7 +78,7 @@ export function serializeAttribute(value, type = 'string', warn = console.warn)
73
78
 
74
79
  /** @param {unknown} type @returns {asserts type is AttributeType} */
75
80
  function assertType(type) {
76
- if (!['string', 'number', 'boolean', 'json'].includes(String(type))) {
81
+ if (!['string', 'number', 'boolean', 'flag', 'json'].includes(String(type))) {
77
82
  throw new TypeError(`Unknown reflected attribute type: ${String(type)}`);
78
83
  }
79
84
  }
package/src/index.js CHANGED
@@ -54,7 +54,7 @@ export { position } from './core/position.js';
54
54
  export { breakpoints, breakpointOf, matchBreakpoint, onBreakpoint } from './core/breakpoint.js';
55
55
  export { MOTION_ATTRIBUTE, prefersReducedMotion, watchMotion } from './core/motion.js';
56
56
  export { Http, zeyosService, parseResult } from './core/http.js';
57
- export { setTranslator, setLanguage, getLanguage, translate, printf, defaultMessages } from './core/i18n.js';
57
+ export { setTranslator, setLanguage, getLanguage, translate, translatePlural, printf, defaultMessages } from './core/i18n.js';
58
58
  export { focusTrap, rovingTabindex, typeahead } from './core/keyboard.js';
59
59
  export {
60
60
  formatDate, parseDate, clampDate, isSameDay, addDays, addMonths, getWeekStart
@@ -124,6 +124,21 @@ export {
124
124
  export {
125
125
  ActivityList, groupActivityItems, normalizeActivityItems
126
126
  } from './components/activity-list/activity-list.js';
127
+ export { BlockView, renderBlocks } from './components/block-view/block-view.js';
128
+ export { blocksToMarkdown, blocksToText } from './internal/agent-model.js';
129
+ export { RunStatus } from './components/run-status/run-status.js';
130
+ export { Composer } from './components/composer/composer.js';
131
+ export { PromptStarters } from './components/prompt-starters/prompt-starters.js';
132
+ export { ApprovalCard } from './components/approval-card/approval-card.js';
133
+ export { RunTrace } from './components/run-trace/run-trace.js';
134
+ export { SourceList } from './components/source-list/source-list.js';
135
+ export { AgentThread } from './components/agent-thread/agent-thread.js';
136
+ export { UI_MESSAGE_STREAM_VERSION, connectUiMessageStream } from './components/agent-thread/ui-message-stream.js';
137
+ export { AG_UI_VERSION, connectAgUi } from './components/agent-thread/ag-ui.js';
138
+ export { Surface, openSurface } from './components/surface/surface.js';
139
+ export { elicit } from './components/surface/elicit.js';
140
+ export { MCP_ELICITATION_VERSION, elicitationHandler } from './components/surface/mcp.js';
141
+ export { surfaceText } from './components/surface/text.js';
127
142
  export { AccountMenu } from './components/account-menu/account-menu.js';
128
143
  export { WorkspaceSwitcher } from './components/workspace-switcher/workspace-switcher.js';
129
144
  export { normalizeAppItems } from './internal/app-rail.js';
@@ -140,6 +155,8 @@ export { MenuButton } from './components/menu-button/menu-button.js';
140
155
  export { ContextMenu } from './components/context-menu/context-menu.js';
141
156
  export { Select } from './components/select/select.js';
142
157
  export { statusIcon, priorityIcon } from './components/select/glyphs.js';
158
+ export { canonicalLocale } from './components/select/locale.js';
159
+ export { flag, flagEmoji, supportsFlagEmoji, COUNTRY_CODES } from './components/flag/flag.js';
143
160
  export { Checklist } from './components/checklist/checklist.js';
144
161
  export { TagPicker } from './components/tag-picker/tag-picker.js';
145
162
  export { NumberField, parseNumber, snapNumber } from './components/number-field/number-field.js';
@@ -0,0 +1,488 @@
1
+ // @ts-check
2
+ /**
3
+ * The agent data model every agent component reads: a conversation thread as a list of plain JSON
4
+ * items, the blocks an answer is made of, the steps a run took, the sources it cites, and the one
5
+ * mapping from a run or agent state to the glyph, tone, and word that show it.
6
+ *
7
+ * The model holds no functions and no DOM nodes, so an agent can produce it directly and an
8
+ * application can store, send, and replay it. Behaviour comes in through component options and
9
+ * events, never through the model.
10
+ */
11
+ import { formatNumber } from '../core/format.js';
12
+
13
+ /**
14
+ * Where a run, or one step of it, stands.
15
+ * @typedef {'queued'|'running'|'waiting'|'paused'|'blocked'|'done'|'failed'|'stopped'|'skipped'} RunState
16
+ */
17
+
18
+ /**
19
+ * What an agent is doing, shown beside its avatar.
20
+ * @typedef {'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'} AgentActivity
21
+ */
22
+
23
+ /**
24
+ * A row of figures: what it is, a muted detail, and the value. The tuple form is shorthand for the
25
+ * object form; `call` names the trace step the value came from.
26
+ * @typedef {[string, string, string]|{label: string, detail?: string, value: string, call?: string}} FigureRow
27
+ */
28
+
29
+ /**
30
+ * One block of an answer. Text runs use the inline grammar of `parseInline()`; nothing in a block
31
+ * is ever read as HTML.
32
+ * @typedef {{type: 'p', text: string}
33
+ * | {type: 'quote', text: string}
34
+ * | {type: 'heading', level?: 2|3, text: string}
35
+ * | {type: 'list', ordered?: boolean, items: string[]}
36
+ * | {type: 'code', language?: string, code: string, lines?: boolean}
37
+ * | {type: 'table', columns: string[], rows: string[][], align?: Array<'start'|'center'|'end'|null>}
38
+ * | {type: 'figures', rows: FigureRow[]}
39
+ * | {type: 'callout', tone?: 'info'|'success'|'warning'|'danger', title?: string, text: string}
40
+ * | {type: 'artifact', id: string, title: string, kind?: 'document'|'code', versions?: number}} Block
41
+ */
42
+
43
+ /**
44
+ * A source an answer draws on. `web` sources may carry an `href`; a `record` names an application
45
+ * record; a `call` names the trace step it came from.
46
+ * @typedef {Object} Source
47
+ * @property {string} id Stable identity.
48
+ * @property {string} title Full title, shown in the source card.
49
+ * @property {'web'|'file'|'record'|'call'} [kind='web'] What the source is.
50
+ * @property {string} [site] Short name shown on the chip: a host, a file name, a record type.
51
+ * @property {string} [snippet] The passage the answer used.
52
+ * @property {string} [href] Address of a `web` source.
53
+ * @property {{entity: string, id: string}} [ref] The application record a `record` source names.
54
+ * @property {string} [call] The trace step the source came from.
55
+ */
56
+
57
+ /**
58
+ * A link from an item or a step to something of the application's own — a task, a file, a
59
+ * record. The application resolves it; the components only draw the label and report the click.
60
+ * @typedef {Object} ItemRef
61
+ * @property {string} id Stable identity, handed back on activation.
62
+ * @property {string} label What the link says.
63
+ * @property {string} [icon] Glyph name.
64
+ * @property {string} [entity] What kind of thing it is, for the application: `task`, `file`, …
65
+ */
66
+
67
+ /**
68
+ * One thing an agent did during a run.
69
+ * @typedef {Object} TraceStep
70
+ * @property {string} id Stable identity.
71
+ * @property {'search'|'read'|'query'|'write'|'run'|'call'|'handoff'|'think'|'task'|'ask'|'decision'} [kind='call']
72
+ * What kind of step it is; sets the glyph and how the summary counts it. `task` is a planned step,
73
+ * `ask` a request a person made, `decision` a person's answer; with `think` and `handoff` they are
74
+ * not tool calls.
75
+ * @property {string} label What was done, in the past tense: "Read the dunning policy".
76
+ * @property {RunState} [status='done'] Where the step stands.
77
+ * @property {string} [doing] The present-tense line shown while it runs: "Reading the policy".
78
+ * @property {string} [detail] A muted detail.
79
+ * @property {number} [ms] How long it took.
80
+ * @property {string} [count] A short result count: "42 rows".
81
+ * @property {number} [sources] How many sources a search looked at.
82
+ * @property {string} [tool] The tool's name, shown in mono.
83
+ * @property {string} [args] The call's arguments, JSON or text.
84
+ * @property {string} [result] What the call returned.
85
+ * @property {string} [error] Why the call failed.
86
+ * @property {string} [retryOf] The id of the step this one repeats.
87
+ * @property {string} [actor] Author key of whoever took the step.
88
+ * @property {string} [to] Author key a `handoff` hands over to.
89
+ * @property {string} [at] Local ISO date-time it started; a running step's clock counts from it.
90
+ * @property {number} [tokens] Tokens the step used.
91
+ * @property {ItemRef[]} [refs] Links to what the step touched — a file it wrote, a record it read.
92
+ */
93
+
94
+ /**
95
+ * Who wrote an item or took a step.
96
+ * @typedef {Object} Author
97
+ * @property {string} name Display name.
98
+ * @property {'person'|'agent'|'model'} [kind='agent'] What the author is.
99
+ * @property {string} [initials] Avatar initials; derived from the name when absent.
100
+ * @property {string} [tone] Categorical avatar tone.
101
+ * @property {AgentActivity|null} [activity] What an agent is doing now.
102
+ * @property {string} [via] The model an agent answers through, shown in the byline.
103
+ * @property {string} [icon] A glyph drawn in a tinted tile instead of initials — a model's mark.
104
+ */
105
+
106
+ /** @typedef {{name: string, size?: number, type?: string}} Attachment */
107
+
108
+ /**
109
+ * One version of a regenerated answer.
110
+ * @typedef {{blocks: Block[], sources?: Source[], steps?: TraceStep[], at?: string, model?: string,
111
+ * stopped?: boolean, rating?: 'up'|'down'|null}} AnswerVersion
112
+ */
113
+
114
+ /**
115
+ * One item in a conversation thread.
116
+ * `refs` on any item draws links to the application's own things after its content; `mentions` on a
117
+ * person's message marks each `@name` in the text; an answer's `steps` show the work it did inline,
118
+ * above its text, and change with its version.
119
+ * @typedef {{id: string, type: 'user', at?: string, author?: string, text: string, files?: Attachment[],
120
+ * mentions?: Array<string|{name: string, tone?: string}>, refs?: ItemRef[]}
121
+ * | {id: string, type: 'text', at?: string, author?: string, text: string, refs?: ItemRef[]}
122
+ * | {id: string, type: 'answer', at?: string, author?: string, blocks: Block[], sources?: Source[],
123
+ * steps?: TraceStep[], stepsOpen?: boolean, streaming?: boolean, stopped?: boolean, versions?: AnswerVersion[],
124
+ * version?: number, rating?: 'up'|'down'|null, refs?: ItemRef[]}
125
+ * | {id: string, type: 'trace', at?: string, author?: string, steps: TraceStep[], open?: boolean,
126
+ * title?: string, refs?: ItemRef[]}
127
+ * | {id: string, type: 'approval', at?: string, author?: string, title: string, description?: string,
128
+ * icon?: string|null, tone?: string,
129
+ * status?: 'pending'|'approved'|'rejected'|'expired', details?: Block[],
130
+ * preview?: {label: string, blocks: Block[]}, fields?: Record<string, Record<string, unknown>>,
131
+ * values?: Record<string, unknown>, confirmText?: string|null, reason?: 'optional'|'required'|'none',
132
+ * edited?: boolean, editedKeys?: string[]|null, rejectReason?: string|null, answeredBy?: string,
133
+ * answeredAt?: string}
134
+ * | {id: string, type: 'notice', at?: string, author?: string, text: string,
135
+ * tone?: 'neutral'|'info'|'success'|'warning'|'danger', action?: {id: string, label: string}}
136
+ * | {id: string, type: string, at?: string, author?: string, [key: string]: unknown}} ThreadItem
137
+ */
138
+
139
+ /** @typedef {'neutral'|'info'|'success'|'warning'|'danger'|'muted'} StateTone */
140
+ /** @typedef {{status: string, tone: StateTone, key: string}} StateEntry */
141
+
142
+ /**
143
+ * How each run or step state is drawn: the `statusIcon()` status, its tone, and the message key of
144
+ * the word beside it. A state is always a glyph and a word; its colour never stands alone.
145
+ * @type {Readonly<Record<RunState, StateEntry>>}
146
+ */
147
+ export const STATUS = Object.freeze({
148
+ queued: { status: 'todo', tone: 'neutral', key: 'agent.status.queued' },
149
+ running: { status: 'in-progress', tone: 'info', key: 'agent.status.running' },
150
+ waiting: { status: 'waiting', tone: 'warning', key: 'agent.status.waiting' },
151
+ paused: { status: 'in-progress', tone: 'muted', key: 'agent.status.paused' },
152
+ blocked: { status: 'waiting', tone: 'danger', key: 'agent.status.blocked' },
153
+ done: { status: 'done', tone: 'success', key: 'agent.status.done' },
154
+ failed: { status: 'canceled', tone: 'danger', key: 'agent.status.failed' },
155
+ stopped: { status: 'canceled', tone: 'muted', key: 'agent.status.stopped' },
156
+ skipped: { status: 'canceled', tone: 'muted', key: 'agent.status.skipped' }
157
+ });
158
+
159
+ /**
160
+ * How each agent activity is drawn beside an avatar: the tone of its dot and the message key of
161
+ * its word.
162
+ * @type {Readonly<Record<AgentActivity, {tone: StateTone, key: string}>>}
163
+ */
164
+ export const ACTIVITY = Object.freeze({
165
+ 'needs-you': { tone: 'warning', key: 'agent.activity.needsYou' },
166
+ blocked: { tone: 'danger', key: 'agent.activity.blocked' },
167
+ working: { tone: 'success', key: 'agent.activity.working' },
168
+ thinking: { tone: 'info', key: 'agent.activity.thinking' },
169
+ idle: { tone: 'neutral', key: 'agent.activity.idle' },
170
+ offline: { tone: 'muted', key: 'agent.activity.offline' }
171
+ });
172
+
173
+ /**
174
+ * The English words for `STATUS` and `ACTIVITY`, for a component's `msg` defaults.
175
+ * @type {Readonly<Record<string, string>>}
176
+ */
177
+ export const AGENT_MESSAGES = Object.freeze({
178
+ 'agent.status.queued': 'Not started',
179
+ 'agent.status.running': 'Running',
180
+ 'agent.status.waiting': 'Waiting for you',
181
+ 'agent.status.paused': 'Paused',
182
+ 'agent.status.blocked': 'Blocked',
183
+ 'agent.status.done': 'Done',
184
+ 'agent.status.failed': 'Failed',
185
+ 'agent.status.stopped': 'Stopped',
186
+ 'agent.status.skipped': 'Skipped',
187
+ 'agent.activity.needsYou': 'Needs you',
188
+ 'agent.activity.blocked': 'Blocked',
189
+ 'agent.activity.working': 'Working',
190
+ 'agent.activity.thinking': 'Thinking',
191
+ 'agent.activity.idle': 'Idle',
192
+ 'agent.activity.offline': 'Offline'
193
+ });
194
+
195
+ /**
196
+ * Reads a state, falling back to `done` for anything the model does not know.
197
+ * @param {unknown} state
198
+ * @returns {RunState}
199
+ */
200
+ export function normalizeRunState(state) {
201
+ return typeof state === 'string' && Object.hasOwn(STATUS, state) ? /** @type {RunState} */ (state) : 'done';
202
+ }
203
+
204
+ /**
205
+ * Reads an activity, or null for none or anything unknown.
206
+ * @param {unknown} activity
207
+ * @returns {AgentActivity|null}
208
+ */
209
+ export function normalizeActivity(activity) {
210
+ return typeof activity === 'string' && Object.hasOwn(ACTIVITY, activity) ? /** @type {AgentActivity} */ (activity) : null;
211
+ }
212
+
213
+ /* ------------------------------------------------------------------ inline grammar -- */
214
+
215
+ /** @typedef {{kind: 'text'|'strong'|'code', text: string}|{kind: 'cite', text: string, n: number}} InlineSegment */
216
+
217
+ /** Characters a backslash makes literal. */
218
+ const ESCAPABLE = '*`[\\';
219
+
220
+ /**
221
+ * Splits a run of model text into plain text, `**bold**`, `` `code` ``, and `[n]` citation
222
+ * segments. That is the whole grammar: there are no links, no HTML, and no nesting. A backslash
223
+ * makes the next `*`, `` ` ``, `[`, or backslash literal; a marker that is never closed stays
224
+ * literal text, which is also what a half-streamed marker looks like until its close arrives.
225
+ * Code spans are verbatim: escapes inside them are not processed.
226
+ * @param {unknown} text
227
+ * @returns {InlineSegment[]}
228
+ */
229
+ export function parseInline(text) {
230
+ const source = text == null ? '' : String(text);
231
+ /** @type {InlineSegment[]} */
232
+ const out = [];
233
+ let buffer = '';
234
+ const flush = () => {
235
+ if (!buffer) return;
236
+ const last = out.at(-1);
237
+ if (last?.kind === 'text') last.text += buffer;
238
+ else out.push({ kind: 'text', text: buffer });
239
+ buffer = '';
240
+ };
241
+ let index = 0;
242
+ while (index < source.length) {
243
+ const char = source[index];
244
+ if (char === '\\' && index + 1 < source.length && ESCAPABLE.includes(source[index + 1])) {
245
+ buffer += source[index + 1];
246
+ index += 2;
247
+ continue;
248
+ }
249
+ if (char === '*' && source[index + 1] === '*') {
250
+ const close = findStrongClose(source, index + 2);
251
+ if (close > index + 2) {
252
+ flush();
253
+ out.push({ kind: 'strong', text: unescapeInline(source.slice(index + 2, close)) });
254
+ index = close + 2;
255
+ continue;
256
+ }
257
+ }
258
+ if (char === '`') {
259
+ const close = source.indexOf('`', index + 1);
260
+ if (close > index + 1) {
261
+ flush();
262
+ out.push({ kind: 'code', text: source.slice(index + 1, close) });
263
+ index = close + 1;
264
+ continue;
265
+ }
266
+ }
267
+ if (char === '[') {
268
+ const match = /^\[(\d{1,3})\]/.exec(source.slice(index, index + 5));
269
+ if (match && Number(match[1]) > 0) {
270
+ flush();
271
+ out.push({ kind: 'cite', text: match[0], n: Number(match[1]) });
272
+ index += match[0].length;
273
+ continue;
274
+ }
275
+ }
276
+ buffer += char;
277
+ index += 1;
278
+ }
279
+ flush();
280
+ return out;
281
+ }
282
+
283
+ /**
284
+ * Finds the `**` that closes a bold run opened just before `from`, skipping escaped asterisks.
285
+ * @param {string} source
286
+ * @param {number} from
287
+ * @returns {number} Index of the closing marker, or -1.
288
+ */
289
+ function findStrongClose(source, from) {
290
+ for (let index = from; index < source.length - 1; index += 1) {
291
+ if (source[index] === '\\') {
292
+ index += 1;
293
+ continue;
294
+ }
295
+ if (source[index] === '*' && source[index + 1] === '*') return index;
296
+ }
297
+ return -1;
298
+ }
299
+
300
+ /** @param {string} text @returns {string} The text with its backslash escapes resolved. */
301
+ function unescapeInline(text) {
302
+ return text.replace(/\\([*`[\\])/g, '$1');
303
+ }
304
+
305
+ /**
306
+ * The visible text of a run of model text: markers dropped, citations kept as `[n]`.
307
+ * @param {unknown} text
308
+ * @returns {string}
309
+ */
310
+ export function inlineText(text) {
311
+ return parseInline(text).map((segment) => segment.text).join('');
312
+ }
313
+
314
+ /* ------------------------------------------------------------------ figures -- */
315
+
316
+ /**
317
+ * Reads a figures row in either form.
318
+ * @param {FigureRow} row
319
+ * @returns {{label: string, detail: string, value: string, call: string|null}}
320
+ */
321
+ export function figureRow(row) {
322
+ if (Array.isArray(row)) return { label: String(row[0] ?? ''), detail: String(row[1] ?? ''), value: String(row[2] ?? ''), call: null };
323
+ return {
324
+ label: String(row?.label ?? ''),
325
+ detail: String(row?.detail ?? ''),
326
+ value: String(row?.value ?? ''),
327
+ call: typeof row?.call === 'string' && row.call ? row.call : null
328
+ };
329
+ }
330
+
331
+ /* ------------------------------------------------------------------ export -- */
332
+
333
+ /**
334
+ * An answer as plain text, for search and screen-reader summaries: markers dropped, one blank line
335
+ * between blocks.
336
+ * @param {Block[]} blocks
337
+ * @returns {string}
338
+ */
339
+ export function blocksToText(blocks) {
340
+ return (Array.isArray(blocks) ? blocks : []).map((block) => {
341
+ switch (block?.type) {
342
+ case 'list': return block.items.map((item) => inlineText(item)).join('\n');
343
+ case 'code': return block.code;
344
+ case 'table': return [block.columns, ...block.rows].map((row) => row.map((cell) => inlineText(cell)).join('\t')).join('\n');
345
+ case 'figures': return block.rows.map((row) => {
346
+ const { label, detail, value } = figureRow(row);
347
+ return [label, detail, value].filter(Boolean).join('\t');
348
+ }).join('\n');
349
+ case 'callout': return [block.title, inlineText(block.text)].filter(Boolean).join('\n');
350
+ case 'artifact': return block.title;
351
+ default: return inlineText(/** @type {{text?: string}} */ (block)?.text ?? '');
352
+ }
353
+ }).filter(Boolean).join('\n\n');
354
+ }
355
+
356
+ /** @param {string} cell @returns {string} A table cell safe inside a Markdown pipe row. */
357
+ function markdownCell(cell) {
358
+ return String(cell ?? '').replaceAll('|', '\\|').replaceAll('\n', ' ');
359
+ }
360
+
361
+ /**
362
+ * An answer as Markdown, for copying and export. Inline markers are already Markdown and pass
363
+ * through as written.
364
+ * @param {Block[]} blocks
365
+ * @returns {string}
366
+ */
367
+ export function blocksToMarkdown(blocks) {
368
+ return (Array.isArray(blocks) ? blocks : []).map((block) => {
369
+ switch (block?.type) {
370
+ case 'heading': return `${'#'.repeat(block.level === 3 ? 3 : 2)} ${block.text}`;
371
+ case 'quote': return block.text.split('\n').map((line) => `> ${line}`).join('\n');
372
+ case 'list': return block.items.map((item, index) => `${block.ordered ? `${index + 1}.` : '-'} ${item}`).join('\n');
373
+ case 'code': return `\`\`\`${block.language ?? ''}\n${block.code}\n\`\`\``;
374
+ case 'table': {
375
+ const rows = [block.columns, block.columns.map(() => '---'), ...block.rows];
376
+ return rows.map((row) => `| ${row.map(markdownCell).join(' | ')} |`).join('\n');
377
+ }
378
+ case 'figures': return block.rows.map((row) => {
379
+ const { label, detail, value } = figureRow(row);
380
+ return `- ${label}${detail ? ` (${detail})` : ''}: **${value}**`;
381
+ }).join('\n');
382
+ case 'callout': return `> ${block.title ? `**${block.title}** ` : ''}${block.text}`;
383
+ case 'artifact': return `**${block.title}**`;
384
+ default: return /** @type {{text?: string}} */ (block)?.text ?? '';
385
+ }
386
+ }).filter(Boolean).join('\n\n');
387
+ }
388
+
389
+ /* ------------------------------------------------------------------ runs -- */
390
+
391
+ /**
392
+ * @typedef {Object} TraceSummary
393
+ * @property {number} steps Steps that are not retries.
394
+ * @property {number} calls Tool calls made, retries included.
395
+ * @property {number} retries Steps that repeat another.
396
+ * @property {number} failed Steps that failed and were not retried successfully.
397
+ * @property {number} sources Sources looked at, across all searches.
398
+ * @property {number} ms Time spent on finished steps.
399
+ * @property {TraceStep|null} running The step running now, if any.
400
+ * @property {TraceStep|null} stopped The step the run was stopped at, if any.
401
+ */
402
+
403
+ /** Step kinds that are not tool calls. */
404
+ const NOT_CALLS = new Set(['think', 'handoff', 'task', 'ask', 'decision']);
405
+
406
+ /**
407
+ * What a run's steps add up to, for the one-line summary its trace folds into.
408
+ * @param {TraceStep[]} steps
409
+ * @returns {TraceSummary}
410
+ */
411
+ export function traceSummary(steps) {
412
+ const list = Array.isArray(steps) ? steps : [];
413
+ const retried = new Set(list.map((step) => step.retryOf).filter(Boolean));
414
+ let calls = 0;
415
+ let retries = 0;
416
+ let failed = 0;
417
+ let sources = 0;
418
+ let ms = 0;
419
+ /** @type {TraceStep|null} */
420
+ let running = null;
421
+ /** @type {TraceStep|null} */
422
+ let stopped = null;
423
+ for (const step of list) {
424
+ const status = normalizeRunState(step.status ?? 'done');
425
+ if (!NOT_CALLS.has(step.kind ?? 'call')) calls += 1;
426
+ if (step.retryOf) retries += 1;
427
+ if (status === 'failed' && !retried.has(step.id)) failed += 1;
428
+ if (typeof step.sources === 'number' && Number.isFinite(step.sources)) sources += step.sources;
429
+ if (status === 'running' && !running) running = step;
430
+ if (status === 'stopped' && !stopped) stopped = step;
431
+ if (status !== 'running' && typeof step.ms === 'number' && Number.isFinite(step.ms)) ms += step.ms;
432
+ }
433
+ return { steps: list.length - retries, calls, retries, failed, sources, ms, running, stopped };
434
+ }
435
+
436
+ /**
437
+ * How long something took, the way a person says it: "0.8 s" below ten seconds, then "12 s",
438
+ * "1 min 42 s", "1 h 5 min".
439
+ * @param {number} ms
440
+ * @param {{locale?: string}} [options]
441
+ * @returns {string}
442
+ */
443
+ export function formatDuration(ms, options = {}) {
444
+ const value = Number(ms);
445
+ if (!Number.isFinite(value) || value < 0) return '';
446
+ if (value < 10_000) return `${formatNumber(value / 1000, { decimals: 1, locale: options.locale })} s`;
447
+ return formatElapsed(value);
448
+ }
449
+
450
+ /**
451
+ * A running clock in whole units: "2 s", "41 s", "1 min 42 s", "1 h 5 min".
452
+ * @param {number} ms
453
+ * @returns {string}
454
+ */
455
+ export function formatElapsed(ms) {
456
+ const value = Number(ms);
457
+ if (!Number.isFinite(value) || value < 0) return '';
458
+ const seconds = Math.floor(value / 1000);
459
+ if (seconds < 60) return `${seconds} s`;
460
+ const minutes = Math.floor(seconds / 60);
461
+ if (minutes < 60) return `${minutes} min ${seconds % 60} s`;
462
+ return `${Math.floor(minutes / 60)} h ${minutes % 60} min`;
463
+ }
464
+
465
+ /**
466
+ * What a run cost, from its token counts and per-token prices.
467
+ * @param {[number, number]|null|undefined} tokens Input and output tokens.
468
+ * @param {{in: number, out: number}} price Price per input and per output token.
469
+ * @returns {number}
470
+ */
471
+ export function runCost(tokens, price) {
472
+ if (!Array.isArray(tokens) || !price) return 0;
473
+ const input = Number(tokens[0]) || 0;
474
+ const output = Number(tokens[1]) || 0;
475
+ return input * (Number(price.in) || 0) + output * (Number(price.out) || 0);
476
+ }
477
+
478
+ /**
479
+ * Initials for an avatar from a name: "Finance agent" → "FA".
480
+ * @param {string} name
481
+ * @returns {string}
482
+ */
483
+ export function initialsOf(name) {
484
+ const words = String(name ?? '').trim().split(/\s+/).filter(Boolean);
485
+ if (words.length === 0) return '?';
486
+ const letters = words.length === 1 ? [...words[0]].slice(0, 2) : [[...words[0]][0], [...words.at(-1) ?? ''][0]];
487
+ return letters.join('').toUpperCase();
488
+ }
@@ -0,0 +1,11 @@
1
+ import { formattingLocale } from '../core/i18n.js';
2
+
3
+ /**
4
+ * The locale `Intl` writes a date in: a supported component option, then the active language,
5
+ * including regional English, then English when neither can be used.
6
+ * @param {string|string[]|null} [option] The component's `locale` option.
7
+ * @returns {string|string[]}
8
+ */
9
+ export function dateLocale(option) {
10
+ return formattingLocale(option, Intl.DateTimeFormat);
11
+ }