@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
@@ -79,7 +79,15 @@ export class SheetStack extends EventTarget {
79
79
  this.#closers.set(sheet, onClose);
80
80
  sheet.on('close', onClose);
81
81
  }
82
+ // Clear the former covered state before presenting: an inert dialog cannot take focus.
83
+ this.#sync();
82
84
  if (!sheet.isOpen()) sheet.open();
85
+ else {
86
+ // Native top-layer order follows presentation order. Rehosting uses Modal's generation
87
+ // guard so its queued close is not a stack pop or a new user-visible lifecycle.
88
+ sheet._rehost();
89
+ sheet._focusInitial();
90
+ }
83
91
  this.#sync();
84
92
  this.#emit('push', { sheet, depth: 0 });
85
93
  return this;
@@ -97,8 +105,9 @@ export class SheetStack extends EventTarget {
97
105
  pop() {
98
106
  const sheet = this.top();
99
107
  if (!sheet) return null;
100
- this.#remove(sheet);
108
+ // Dismiss this presentation before pop listeners can re-push and open a new one.
101
109
  sheet.close();
110
+ this.#remove(sheet);
102
111
  return sheet;
103
112
  }
104
113
 
@@ -160,6 +160,7 @@ export class Slider extends Component {
160
160
  const value = this._snap(next);
161
161
  const changed = value !== this._value;
162
162
  this._value = value;
163
+ this._committedValue = value;
163
164
  this._paint();
164
165
  if (changed && !silent) this.emit('change', { value });
165
166
  return this;
@@ -246,7 +247,7 @@ export class Slider extends Component {
246
247
  step: String(this._step),
247
248
  disabled: Boolean(this.options.disabled),
248
249
  readOnly: this._readonly,
249
- ariaLabel: String(this.options.label ?? 'Value')
250
+ ariaLabel: String(this.options.label ?? this.msg('slider.value'))
250
251
  }));
251
252
  this.listen(number, 'input', () => {
252
253
  if (this._readonly) return;
@@ -263,7 +264,10 @@ export class Slider extends Component {
263
264
  number.value = String(this._value);
264
265
  return;
265
266
  }
266
- this.set(number.value === '' ? this._min : Number(number.value));
267
+ const value = this._snap(number.value === '' ? this._min : Number(number.value));
268
+ const changed = value !== this._committedValue;
269
+ this.set(value, { silent: true });
270
+ if (changed) this.emit('change', { value });
267
271
  });
268
272
  return number;
269
273
  }
@@ -303,6 +307,7 @@ export class Slider extends Component {
303
307
  this.refs.input.value = String(this._value);
304
308
  return;
305
309
  }
310
+ this._committedValue = this._value;
306
311
  this.emit('change', { value: this._value });
307
312
  }
308
313
 
@@ -10,7 +10,8 @@ import { Select } from '../select/select.js';
10
10
  * @typedef {Object} SortControlOptions
11
11
  * @property {SortField[]} [fields=[]] Available sort fields, in display order.
12
12
  * @property {SortValue|null} [value=null] Initial sort; null chooses the first field ascending.
13
- * @property {string} [label='Sort by'] Accessible field label and direction-name prefix.
13
+ * @property {string|null} [label] Accessible field label and direction-name prefix, by default the
14
+ * `sortControl.label` message ("Sort by"). Null gives neither.
14
15
  * @property {{asc?:string,desc?:string}} [labels={}] Current/next direction labels, defaulting to Ascending/Descending.
15
16
  * @property {boolean} [disabled=false] Whether interaction is disabled.
16
17
  * @property {(event:CustomEvent<{value:SortValue}>)=>void} [onchange] Atomic field/direction change.
@@ -24,7 +25,7 @@ import { Select } from '../select/select.js';
24
25
  export class SortControl extends Component {
25
26
  static cssName = 'sort-control';
26
27
  /** @type {SortControlOptions} */
27
- static defaults = { fields: [], value: null, label: 'Sort by', labels: {}, disabled: false };
28
+ static defaults = { fields: [], value: null, label: undefined, labels: {}, disabled: false };
28
29
 
29
30
  /** @returns {HTMLElement} */
30
31
  render() {
@@ -42,7 +43,7 @@ export class SortControl extends Component {
42
43
  });
43
44
  this._select = new Select(null, {
44
45
  items: sortChoices(this.options.fields), valueKey: 'id', labelKey: 'label',
45
- value: this._value?.id ?? null, label: this.options.label,
46
+ value: this._value?.id ?? null, label: this._label(),
46
47
  filter: 'local', disabled: this._disabled,
47
48
  onchange: ({ detail }) => {
48
49
  if (!detail.item) return;
@@ -94,13 +95,22 @@ export class SortControl extends Component {
94
95
  _syncDirection() {
95
96
  const dir = this._value?.dir ?? 'asc';
96
97
  const next = dir === 'asc' ? 'desc' : 'asc';
97
- const labels = { asc: 'Ascending', desc: 'Descending', ...this.options.labels };
98
+ const labels = {
99
+ asc: this.msg('sortControl.ascending'), desc: this.msg('sortControl.descending'), ...this.options.labels
100
+ };
98
101
  this._direction.replaceChildren(icon(dir === 'asc' ? 'arrow-up-wide-short' : 'arrow-down-wide-short'));
99
102
  this._direction.dataset.direction = dir;
100
- this._direction.setAttribute('aria-label', `${this.options.label}: ${labels[dir]}`);
103
+ const label = this._label();
104
+ this._direction.setAttribute('aria-label', label === null ? labels[dir] : `${label}: ${labels[dir]}`);
101
105
  this._direction.title = `${labels[dir]} → ${labels[next]}`;
102
106
  }
103
107
 
108
+ /** @returns {string|null} The control's name: unset reads the catalogue, and null is no name. */
109
+ _label() {
110
+ const { label = this.msg('sortControl.label') } = this.options;
111
+ return label;
112
+ }
113
+
104
114
  /** Focuses the searchable control. @returns {this} */
105
115
  focus() { this._select.focus(); return this; }
106
116
  /** Releases the owned Select and restores an enhanced target. @returns {void} */
@@ -0,0 +1,208 @@
1
+ /*
2
+ * SourceList — the sources an answer cites. As chips, small numbered buttons wrap beside their
3
+ * label and the list drops under it when the line gets narrow; as a list, each source is a row
4
+ * with its title and site. The card a source shows renders in a tooltip, outside the root.
5
+ */
6
+ .zx-source-list {
7
+ display: flex;
8
+ flex-wrap: wrap;
9
+ align-items: flex-start;
10
+ gap: var(--zx-space-1) var(--zx-space-2);
11
+ min-inline-size: 0;
12
+ color: var(--zx-color-text);
13
+ }
14
+
15
+ .zx-source-list[data-empty] {
16
+ display: none;
17
+ }
18
+
19
+ .zx-source-list__label {
20
+ flex: 0 0 auto;
21
+ color: var(--zx-color-text-muted);
22
+ font-size: var(--zx-text-xs);
23
+ font-weight: var(--zx-weight-medium);
24
+ line-height: var(--zx-space-6);
25
+ }
26
+
27
+ .zx-source-list__items {
28
+ display: flex;
29
+ flex: 1 1 12rem;
30
+ flex-wrap: wrap;
31
+ gap: var(--zx-space-1);
32
+ min-inline-size: 0;
33
+ margin: 0;
34
+ padding: 0;
35
+ list-style: none;
36
+ }
37
+
38
+ .zx-source-list__item {
39
+ min-inline-size: 0;
40
+ max-inline-size: 100%;
41
+ }
42
+
43
+ /* ------------------------------------------------------------------ source -- */
44
+
45
+ .zx-source-list__source {
46
+ position: relative;
47
+ display: inline-flex;
48
+ align-items: center;
49
+ gap: var(--zx-space-1);
50
+ max-inline-size: min(15rem, 100%);
51
+ min-block-size: var(--zx-space-6);
52
+ padding-block: 1px;
53
+ padding-inline: 1px var(--zx-space-2);
54
+ border: 1px solid var(--zx-color-border-subtle);
55
+ border-radius: var(--zx-radius-md);
56
+ background: var(--zx-color-bg-surface);
57
+ color: var(--zx-color-text-muted);
58
+ font: inherit;
59
+ font-size: var(--zx-text-xs);
60
+ line-height: 1.3;
61
+ text-align: start;
62
+ cursor: pointer;
63
+ }
64
+
65
+ .zx-source-list__source:not(:has(.zx-source-list__n)) {
66
+ padding-inline-start: var(--zx-space-2);
67
+ }
68
+
69
+ .zx-source-list__source:hover {
70
+ border-color: var(--zx-color-border);
71
+ background: var(--zx-color-bg-hover);
72
+ color: var(--zx-color-text);
73
+ }
74
+
75
+ .zx-source-list__source:focus-visible {
76
+ outline-color: transparent;
77
+ box-shadow: var(--zx-focus-ring);
78
+ }
79
+
80
+ /* Pointed at from a citation: the accent fill, until it fades back. */
81
+ .zx-source-list__source[data-state="highlighted"] {
82
+ border-color: var(--zx-color-accent);
83
+ background: var(--zx-color-accent-subtle);
84
+ color: var(--zx-color-text);
85
+ }
86
+
87
+ .zx-source-list__n {
88
+ display: inline-grid;
89
+ flex: 0 0 auto;
90
+ place-items: center;
91
+ min-inline-size: calc(var(--zx-space-6) - 6px);
92
+ block-size: calc(var(--zx-space-6) - 6px);
93
+ padding-inline: 3px;
94
+ border-radius: var(--zx-radius-sm);
95
+ background: var(--zx-color-bg-muted);
96
+ color: var(--zx-color-text-muted);
97
+ font-weight: var(--zx-weight-medium);
98
+ font-variant-numeric: tabular-nums;
99
+ }
100
+
101
+ .zx-source-list__glyph {
102
+ display: inline-flex;
103
+ flex: 0 0 auto;
104
+ color: var(--zx-color-text-subtle);
105
+ }
106
+
107
+ .zx-source-list__name,
108
+ .zx-source-list__title,
109
+ .zx-source-list__site {
110
+ overflow: hidden;
111
+ min-inline-size: 0;
112
+ text-overflow: ellipsis;
113
+ white-space: nowrap;
114
+ }
115
+
116
+ .zx-source-list__sr {
117
+ position: absolute;
118
+ inline-size: 1px;
119
+ block-size: 1px;
120
+ overflow: hidden;
121
+ clip-path: inset(50%);
122
+ white-space: nowrap;
123
+ }
124
+
125
+ /* ------------------------------------------------------------------ list layout -- */
126
+
127
+ .zx-source-list[data-layout="list"] {
128
+ display: grid;
129
+ }
130
+
131
+ .zx-source-list[data-layout="list"] .zx-source-list__items {
132
+ display: grid;
133
+ gap: 1px;
134
+ }
135
+
136
+ .zx-source-list[data-layout="list"] .zx-source-list__source {
137
+ inline-size: calc(100% + 2 * var(--zx-space-2));
138
+ max-inline-size: none;
139
+ min-block-size: var(--zx-control-height);
140
+ margin-inline: calc(-1 * var(--zx-space-2));
141
+ padding: var(--zx-space-1) var(--zx-space-2);
142
+ gap: var(--zx-space-2);
143
+ border-color: transparent;
144
+ background: none;
145
+ color: var(--zx-color-text);
146
+ font-size: var(--zx-text-sm);
147
+ }
148
+
149
+ .zx-source-list[data-layout="list"] .zx-source-list__source:hover {
150
+ background: var(--zx-color-bg-hover);
151
+ }
152
+
153
+ .zx-source-list[data-layout="list"] .zx-source-list__source[data-state="highlighted"] {
154
+ border-color: transparent;
155
+ background: var(--zx-color-accent-subtle);
156
+ }
157
+
158
+ .zx-source-list__copy {
159
+ display: grid;
160
+ flex: 1 1 auto;
161
+ min-inline-size: 0;
162
+ line-height: 1.35;
163
+ }
164
+
165
+ .zx-source-list__title {
166
+ font-weight: var(--zx-weight-medium);
167
+ }
168
+
169
+ .zx-source-list__site {
170
+ color: var(--zx-color-text-muted);
171
+ font-size: var(--zx-text-xs);
172
+ }
173
+
174
+ /* ------------------------------------------------------------------ card -- */
175
+
176
+ .zx-source-list__card {
177
+ display: grid;
178
+ gap: 2px;
179
+ padding-block: var(--zx-space-1);
180
+ }
181
+
182
+ .zx-source-list__card-title {
183
+ font-weight: var(--zx-weight-semibold);
184
+ }
185
+
186
+ .zx-source-list__card-site {
187
+ display: flex;
188
+ align-items: center;
189
+ gap: var(--zx-space-1);
190
+ color: var(--zx-color-text-muted);
191
+ font-size: var(--zx-text-xs);
192
+ }
193
+
194
+ .zx-source-list__card-snippet {
195
+ margin-block-start: var(--zx-space-1);
196
+ color: var(--zx-color-text);
197
+ }
198
+
199
+ /* ------------------------------------------------------------------ motion -- */
200
+
201
+ @media (prefers-reduced-motion: no-preference) {
202
+ .zx-source-list__source {
203
+ transition:
204
+ background-color var(--zx-dur-base) var(--zx-ease),
205
+ border-color var(--zx-dur-base) var(--zx-ease),
206
+ color var(--zx-dur-fast) var(--zx-ease);
207
+ }
208
+ }
@@ -0,0 +1,358 @@
1
+ // @ts-check
2
+ import { Component } from '../../core/component.js';
3
+ import { h, restoreTarget, safeHref, snapshotTarget } from '../../core/dom.js';
4
+ import { icon } from '../../core/icons.js';
5
+ import { prefersReducedMotion } from '../../core/motion.js';
6
+ import { uid } from '../../core/util.js';
7
+ import { Tooltip } from '../tooltip/tooltip.js';
8
+
9
+ /** @typedef {import('../../internal/agent-model.js').Source} Source */
10
+
11
+ /**
12
+ * What a source is: it picks the glyph, and whether activating it can open an address.
13
+ * @typedef {'web'|'file'|'record'|'call'} SourceKind
14
+ */
15
+
16
+ /**
17
+ * @typedef {Object} SourceListOptions
18
+ * @property {Source[]} [sources=[]] The sources, in the order an answer's `[n]` citations number
19
+ * them. Model text is data: every string reaches the page as text.
20
+ * @property {string|null} [label] The visible label the list is named by, by default the
21
+ * `sourceList.label` message ("Sources"). Empty or null hides it and names the list with that
22
+ * message instead.
23
+ * @property {'chips'|'list'} [layout='chips'] `'chips'` wraps short chips beside the label;
24
+ * `'list'` gives each source a full-width row with its title and site.
25
+ * @property {boolean} [numbered=true] Whether each source shows its number.
26
+ * @property {Partial<Record<SourceKind, string>>} [icons={}] Icon names per source kind, over the
27
+ * built-in `SOURCE_ICONS`.
28
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
29
+ * @property {(event: CustomEvent<{source: Source, n: number}>) => void} [onselect] Activation
30
+ * listener; `preventDefault()` keeps a web source from opening.
31
+ */
32
+
33
+ /** Built-in glyph per source kind. */
34
+ export const SOURCE_ICONS = Object.freeze({
35
+ web: 'link-2',
36
+ file: 'file',
37
+ record: 'table',
38
+ call: 'gear'
39
+ });
40
+
41
+ const MESSAGES = Object.freeze({
42
+ 'sourceList.label': 'Sources',
43
+ 'sourceList.source': 'Source'
44
+ });
45
+
46
+ /** How long a highlighted source stays marked, in milliseconds. */
47
+ const HIGHLIGHT_MS = 2000;
48
+
49
+ /**
50
+ * The sources an answer cites: a numbered chip (or row) for each, naming its site or title, with a
51
+ * card of its title, site, and the passage used on hover and focus.
52
+ *
53
+ * Activating a source emits a preventable `select`. Unless it is prevented, a `web` source opens
54
+ * its address in a new tab — only an absolute `https:` address, and never with access back to this
55
+ * page; every other kind is left to the application, which might reveal the trace step the source
56
+ * came from. The list never loads a favicon, a thumbnail, or any other remote resource.
57
+ *
58
+ * @fires SourceList#select
59
+ * @extends {Component<SourceListOptions>}
60
+ */
61
+ export class SourceList extends Component {
62
+ static cssName = 'source-list';
63
+
64
+ /** @type {Readonly<SourceListOptions>} */
65
+ static defaults = {
66
+ sources: [],
67
+ // Undefined rather than null, which already hides the label.
68
+ label: undefined,
69
+ layout: 'chips',
70
+ numbered: true,
71
+ icons: {},
72
+ msg: MESSAGES
73
+ };
74
+
75
+ /** @returns {HTMLElement} */
76
+ render() {
77
+ const created = !this.el;
78
+ const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
79
+ this.el = root;
80
+ this._original = created ? null : snapshotTarget(root);
81
+ if (!created) root.replaceChildren();
82
+ this._destroyed = false;
83
+ /** @type {Array<Source & {id: string}>} */
84
+ this._sources = [];
85
+ /** @type {HTMLButtonElement[]} */
86
+ this._buttons = [];
87
+ /** @type {Tooltip[]} */
88
+ this._tooltips = [];
89
+ /** @type {ReturnType<typeof setTimeout>|null} */
90
+ this._highlightTimer = null;
91
+ this._layout = this.options.layout === 'list' ? 'list' : 'chips';
92
+ root.dataset.layout = this._layout;
93
+
94
+ const { label: option = this.msg('sourceList.label') } = this.options;
95
+ const label = typeof option === 'string' ? option.trim() : '';
96
+ const labelId = uid('zx-source-list');
97
+ const heading = label ? h('span', { class: 'zx-source-list__label', id: labelId }, label) : null;
98
+ this._list = h('ol', {
99
+ class: 'zx-source-list__items',
100
+ 'aria-labelledby': heading ? labelId : null,
101
+ 'aria-label': heading ? null : this.msg('sourceList.label')
102
+ });
103
+ root.append(...[heading, this._list].filter((node) => node !== null));
104
+
105
+ this.listen(root, 'click', (event) => this._onClick(/** @type {MouseEvent} */ (event)));
106
+ this._build(this.options.sources);
107
+ return root;
108
+ }
109
+
110
+ /**
111
+ * Replaces every source. Focus on a source stays on the source with the same `id`.
112
+ * @param {Source[]} sources
113
+ * @returns {this}
114
+ */
115
+ setSources(sources) {
116
+ this._build(sources);
117
+ return this;
118
+ }
119
+
120
+ /**
121
+ * Points at one source, as a citation `[n]` in the answer does: scrolls it into view, puts focus
122
+ * on it, and marks it with `data-state="highlighted"` for two seconds. A number is the source's
123
+ * position, from 1; a string is its `id`. Anything else does nothing.
124
+ * @param {number|string} n
125
+ * @returns {this}
126
+ */
127
+ highlight(n) {
128
+ const index = typeof n === 'number'
129
+ ? Math.trunc(n) - 1
130
+ : this._sources.findIndex((source) => source.id === String(n));
131
+ const button = this._buttons[index];
132
+ if (!button) return this;
133
+ if (typeof button.scrollIntoView === 'function') {
134
+ button.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: prefersReducedMotion(this.el) ? 'auto' : 'smooth' });
135
+ }
136
+ button.focus({ preventScroll: true });
137
+ if (this._highlightTimer) clearTimeout(this._highlightTimer);
138
+ for (const other of this._buttons) if (other !== button) delete other.dataset.state;
139
+ button.dataset.state = 'highlighted';
140
+ this._highlightTimer = setTimeout(() => {
141
+ this._highlightTimer = null;
142
+ if (button.dataset.state === 'highlighted') delete button.dataset.state;
143
+ }, HIGHLIGHT_MS);
144
+ return this;
145
+ }
146
+
147
+ /** @returns {Source[]} Copies of the sources, in order. */
148
+ getSources() {
149
+ return this._sources.map(cloneSource);
150
+ }
151
+
152
+ /** @returns {void} */
153
+ destroy() {
154
+ if (this._destroyed) return;
155
+ this._destroyed = true;
156
+ if (this._highlightTimer) clearTimeout(this._highlightTimer);
157
+ this._highlightTimer = null;
158
+ this._releaseTooltips();
159
+ super.destroy();
160
+ if (this._original) restoreTarget(this.el, this._original);
161
+ }
162
+
163
+ /**
164
+ * @private
165
+ * @param {unknown} sources
166
+ * @returns {void}
167
+ */
168
+ _build(sources) {
169
+ const active = this.el.ownerDocument?.activeElement ?? null;
170
+ const focused = active && this._list.contains(active)
171
+ ? /** @type {HTMLElement|null} */ (active.closest('[data-source]'))?.dataset.source ?? null
172
+ : null;
173
+ if (this._highlightTimer) clearTimeout(this._highlightTimer);
174
+ this._highlightTimer = null;
175
+ this._releaseTooltips();
176
+ this._sources = normalizeSources(sources);
177
+ this._buttons = [];
178
+ this._list.replaceChildren(...this._sources.map((source, index) => this._item(source, index)));
179
+ const root = /** @type {HTMLElement} */ (this.el);
180
+ if (this._sources.length) delete root.dataset.empty;
181
+ else root.dataset.empty = '';
182
+ if (focused) this._buttons.find((button) => button.dataset.source === focused)?.focus({ preventScroll: true });
183
+ }
184
+
185
+ /**
186
+ * @private
187
+ * @param {Source & {id: string}} source
188
+ * @param {number} index
189
+ * @returns {HTMLElement}
190
+ */
191
+ _item(source, index) {
192
+ const kind = sourceKind(source);
193
+ const n = index + 1;
194
+ const numbered = this.options.numbered !== false;
195
+ const where = sourcePlace(source);
196
+ const button = /** @type {HTMLButtonElement} */ (h('button', {
197
+ type: 'button',
198
+ class: 'zx-source-list__source',
199
+ dataset: { source: source.id, n: String(n), kind }
200
+ },
201
+ // Named "Source 1: bank.example", which keeps the visible "1" and name in the accessible name.
202
+ numbered ? [
203
+ h('span', { class: 'zx-source-list__sr' }, `${this.msg('sourceList.source')} `),
204
+ h('span', { class: 'zx-source-list__n' }, String(n)),
205
+ h('span', { class: 'zx-source-list__sr' }, ': ')
206
+ ] : null,
207
+ h('span', { class: 'zx-source-list__glyph', 'aria-hidden': 'true' }, icon(this._icon(kind), { size: 14 })),
208
+ this._layout === 'list'
209
+ ? h('span', { class: 'zx-source-list__copy' },
210
+ h('span', { class: 'zx-source-list__title' }, source.title || sourceName(source)),
211
+ where && where !== source.title ? h('span', { class: 'zx-source-list__site' }, where) : null)
212
+ : h('span', { class: 'zx-source-list__name' }, sourceName(source))));
213
+ this._buttons.push(button);
214
+ this._tooltips.push(new Tooltip(button, {
215
+ content: () => this._card(source),
216
+ placement: 'top-start',
217
+ maxWidth: 320
218
+ }));
219
+ return h('li', { class: 'zx-source-list__item' }, button);
220
+ }
221
+
222
+ /**
223
+ * The card a source shows on hover and focus: its title, where it is (the host of a web
224
+ * address), and the passage used.
225
+ * @private
226
+ * @param {Source & {id: string}} source
227
+ * @returns {HTMLElement}
228
+ */
229
+ _card(source) {
230
+ const kind = sourceKind(source);
231
+ const where = sourcePlace(source);
232
+ return h('span', { class: 'zx-source-list__card' },
233
+ h('span', { class: 'zx-source-list__card-title' }, source.title || sourceName(source)),
234
+ // A file named by its own title would say its name twice.
235
+ where && where !== (source.title || sourceName(source))
236
+ ? h('span', { class: 'zx-source-list__card-site' }, icon(this._icon(kind), { size: 12 }), where) : null,
237
+ source.snippet ? h('span', { class: 'zx-source-list__card-snippet' }, String(source.snippet)) : null);
238
+ }
239
+
240
+ /** @private @param {SourceKind} kind @returns {string} */
241
+ _icon(kind) {
242
+ const custom = this.options.icons?.[kind];
243
+ return typeof custom === 'string' && custom ? custom : SOURCE_ICONS[kind];
244
+ }
245
+
246
+ /** @private @returns {void} */
247
+ _releaseTooltips() {
248
+ for (const tooltip of this._tooltips) tooltip.destroy();
249
+ this._tooltips = [];
250
+ }
251
+
252
+ /**
253
+ * @private
254
+ * @param {MouseEvent} event
255
+ * @returns {void}
256
+ */
257
+ _onClick(event) {
258
+ const target = event.target instanceof Element ? event.target : null;
259
+ const button = /** @type {HTMLElement|null} */ (target?.closest('[data-source]') ?? null);
260
+ if (!button || !this._list.contains(button)) return;
261
+ const index = Number(button.dataset.n) - 1;
262
+ const source = this._sources[index];
263
+ if (!source) return;
264
+ const selected = this.emit('select', { source: cloneSource(source), n: index + 1 }, { honorDomCancellation: true });
265
+ if (selected.defaultPrevented) return;
266
+ const href = sourceHref(source);
267
+ if (href) window.open(href, '_blank', 'noopener,noreferrer');
268
+ }
269
+ }
270
+
271
+ /**
272
+ * Fired when a source is activated. Preventable: `preventDefault()` keeps a web source from
273
+ * opening its address.
274
+ * @event SourceList#select
275
+ * @type {CustomEvent<{source: Source, n: number}>}
276
+ */
277
+
278
+ /* ------------------------------------------------------------------ pure helpers -- */
279
+
280
+ /**
281
+ * @param {unknown} sources
282
+ * @returns {Array<Source & {id: string}>}
283
+ */
284
+ function normalizeSources(sources) {
285
+ /** @type {Array<Source & {id: string}>} */
286
+ const out = [];
287
+ (Array.isArray(sources) ? sources : []).forEach((source, index) => {
288
+ if (!source || typeof source !== 'object') return;
289
+ const id = source.id == null || source.id === '' ? `source-${index + 1}` : String(source.id);
290
+ out.push({ ...cloneSource(source), id, title: source.title == null ? '' : String(source.title) });
291
+ });
292
+ return out;
293
+ }
294
+
295
+ /** @param {Source} source @returns {Source} A copy that shares nothing with the original. */
296
+ function cloneSource(source) {
297
+ const copy = { ...source };
298
+ if (source.ref && typeof source.ref === 'object') copy.ref = { ...source.ref };
299
+ return copy;
300
+ }
301
+
302
+ /**
303
+ * A source's kind; a source without one is a web source.
304
+ * @param {Source|null|undefined} source
305
+ * @returns {SourceKind}
306
+ */
307
+ export function sourceKind(source) {
308
+ const kind = source?.kind ?? 'web';
309
+ return Object.hasOwn(SOURCE_ICONS, kind) ? kind : 'web';
310
+ }
311
+
312
+ /**
313
+ * The address a source may open: a `web` source's `href`, only when it is an absolute `https:`
314
+ * URL that `safeHref()` accepts. Anything else — another kind, a relative or `http:` address, a
315
+ * script scheme — gives null.
316
+ * @param {Source|null|undefined} source
317
+ * @returns {string|null}
318
+ */
319
+ export function sourceHref(source) {
320
+ if (!source || typeof source !== 'object' || sourceKind(source) !== 'web') return null;
321
+ const href = safeHref(source.href);
322
+ if (!href) return null;
323
+ try {
324
+ const url = new URL(href);
325
+ return url.protocol === 'https:' ? url.href : null;
326
+ } catch {
327
+ return null;
328
+ }
329
+ }
330
+
331
+ /**
332
+ * The host a web source opens, for its card: "bank.example". Null when it opens nothing.
333
+ * @param {Source|null|undefined} source
334
+ * @returns {string|null}
335
+ */
336
+ export function sourceHost(source) {
337
+ const href = sourceHref(source);
338
+ return href ? new URL(href).host : null;
339
+ }
340
+
341
+ /**
342
+ * The short name a chip shows: the source's `site`, else its title.
343
+ * @param {Source|null|undefined} source
344
+ * @returns {string}
345
+ */
346
+ export function sourceName(source) {
347
+ const site = source?.site == null ? '' : String(source.site).trim();
348
+ return site || (source?.title == null ? '' : String(source.title));
349
+ }
350
+
351
+ /**
352
+ * Where a source is, for its card and list row: the host a web source opens, else its `site`.
353
+ * @param {Source} source
354
+ * @returns {string}
355
+ */
356
+ function sourcePlace(source) {
357
+ return sourceHost(source) ?? (source.site == null ? '' : String(source.site));
358
+ }