@zeyos/zx 5.5.0 → 5.6.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 (48) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  3. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  4. package/dist/types/components/avatar/avatar.d.ts +91 -4
  5. package/dist/types/components/block-view/block-view.d.ts +205 -0
  6. package/dist/types/components/composer/composer.d.ts +736 -0
  7. package/dist/types/components/run-status/run-status.d.ts +393 -0
  8. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  9. package/dist/types/components/source-list/source-list.d.ts +177 -0
  10. package/dist/types/core/messages.d.ts +135 -0
  11. package/dist/types/index.d.ts +8 -0
  12. package/dist/types/internal/agent-model.d.ts +587 -0
  13. package/dist/types/internal/highlight.d.ts +24 -0
  14. package/dist/types/internal/presence-loop.d.ts +148 -0
  15. package/dist/zx-zeyos.esm.js +4648 -4513
  16. package/dist/zx-zeyos.esm.min.js +2 -2
  17. package/dist/zx.css +1927 -1
  18. package/dist/zx.esm.js +15769 -9194
  19. package/dist/zx.esm.min.js +27 -8
  20. package/dist/zx.global.js +15769 -9194
  21. package/dist/zx.global.min.js +27 -8
  22. package/dist/zx.min.css +1 -1
  23. package/docs/api.json +1166 -5
  24. package/docs/llms.md +455 -2
  25. package/docs/llms.txt +10 -1
  26. package/package.json +1 -1
  27. package/src/components/agent-thread/agent-thread.css +417 -0
  28. package/src/components/agent-thread/agent-thread.js +1365 -0
  29. package/src/components/approval-card/approval-card.css +289 -0
  30. package/src/components/approval-card/approval-card.js +1377 -0
  31. package/src/components/avatar/avatar.css +56 -1
  32. package/src/components/avatar/avatar.js +148 -26
  33. package/src/components/block-view/block-view.css +300 -0
  34. package/src/components/block-view/block-view.js +523 -0
  35. package/src/components/composer/composer.css +403 -0
  36. package/src/components/composer/composer.js +1441 -0
  37. package/src/components/run-status/run-status.css +208 -0
  38. package/src/components/run-status/run-status.js +782 -0
  39. package/src/components/run-trace/run-trace.css +443 -0
  40. package/src/components/run-trace/run-trace.js +1209 -0
  41. package/src/components/source-list/source-list.css +208 -0
  42. package/src/components/source-list/source-list.js +355 -0
  43. package/src/core/messages.js +143 -0
  44. package/src/index.js +8 -0
  45. package/src/internal/agent-model.js +488 -0
  46. package/src/internal/highlight.js +104 -0
  47. package/src/internal/presence-loop.js +343 -0
  48. package/styles/zx.css +7 -0
@@ -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,355 @@
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} [label='Sources'] The visible label the list is named by. Empty hides it and
21
+ * names the list with the `sourceList.label` message instead.
22
+ * @property {'chips'|'list'} [layout='chips'] `'chips'` wraps short chips beside the label;
23
+ * `'list'` gives each source a full-width row with its title and site.
24
+ * @property {boolean} [numbered=true] Whether each source shows its number.
25
+ * @property {Partial<Record<SourceKind, string>>} [icons={}] Icon names per source kind, over the
26
+ * built-in `SOURCE_ICONS`.
27
+ * @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized messages.
28
+ * @property {(event: CustomEvent<{source: Source, n: number}>) => void} [onselect] Activation
29
+ * listener; `preventDefault()` keeps a web source from opening.
30
+ */
31
+
32
+ /** Built-in glyph per source kind. */
33
+ export const SOURCE_ICONS = Object.freeze({
34
+ web: 'link-2',
35
+ file: 'file',
36
+ record: 'table',
37
+ call: 'gear'
38
+ });
39
+
40
+ const MESSAGES = Object.freeze({
41
+ 'sourceList.label': 'Sources',
42
+ 'sourceList.source': 'Source'
43
+ });
44
+
45
+ /** How long a highlighted source stays marked, in milliseconds. */
46
+ const HIGHLIGHT_MS = 2000;
47
+
48
+ /**
49
+ * The sources an answer cites: a numbered chip (or row) for each, naming its site or title, with a
50
+ * card of its title, site, and the passage used on hover and focus.
51
+ *
52
+ * Activating a source emits a preventable `select`. Unless it is prevented, a `web` source opens
53
+ * its address in a new tab — only an absolute `https:` address, and never with access back to this
54
+ * page; every other kind is left to the application, which might reveal the trace step the source
55
+ * came from. The list never loads a favicon, a thumbnail, or any other remote resource.
56
+ *
57
+ * @fires SourceList#select
58
+ * @extends {Component<SourceListOptions>}
59
+ */
60
+ export class SourceList extends Component {
61
+ static cssName = 'source-list';
62
+
63
+ /** @type {Readonly<SourceListOptions>} */
64
+ static defaults = {
65
+ sources: [],
66
+ label: 'Sources',
67
+ layout: 'chips',
68
+ numbered: true,
69
+ icons: {},
70
+ msg: MESSAGES
71
+ };
72
+
73
+ /** @returns {HTMLElement} */
74
+ render() {
75
+ const created = !this.el;
76
+ const root = /** @type {HTMLElement} */ (this.el ?? h('div'));
77
+ this.el = root;
78
+ this._original = created ? null : snapshotTarget(root);
79
+ if (!created) root.replaceChildren();
80
+ this._destroyed = false;
81
+ /** @type {Array<Source & {id: string}>} */
82
+ this._sources = [];
83
+ /** @type {HTMLButtonElement[]} */
84
+ this._buttons = [];
85
+ /** @type {Tooltip[]} */
86
+ this._tooltips = [];
87
+ /** @type {ReturnType<typeof setTimeout>|null} */
88
+ this._highlightTimer = null;
89
+ this._layout = this.options.layout === 'list' ? 'list' : 'chips';
90
+ root.dataset.layout = this._layout;
91
+
92
+ const label = typeof this.options.label === 'string' ? this.options.label.trim() : '';
93
+ const labelId = uid('zx-source-list');
94
+ const heading = label ? h('span', { class: 'zx-source-list__label', id: labelId }, label) : null;
95
+ this._list = h('ol', {
96
+ class: 'zx-source-list__items',
97
+ 'aria-labelledby': heading ? labelId : null,
98
+ 'aria-label': heading ? null : this.msg('sourceList.label')
99
+ });
100
+ root.append(...[heading, this._list].filter((node) => node !== null));
101
+
102
+ this.listen(root, 'click', (event) => this._onClick(/** @type {MouseEvent} */ (event)));
103
+ this._build(this.options.sources);
104
+ return root;
105
+ }
106
+
107
+ /**
108
+ * Replaces every source. Focus on a source stays on the source with the same `id`.
109
+ * @param {Source[]} sources
110
+ * @returns {this}
111
+ */
112
+ setSources(sources) {
113
+ this._build(sources);
114
+ return this;
115
+ }
116
+
117
+ /**
118
+ * Points at one source, as a citation `[n]` in the answer does: scrolls it into view, puts focus
119
+ * on it, and marks it with `data-state="highlighted"` for two seconds. A number is the source's
120
+ * position, from 1; a string is its `id`. Anything else does nothing.
121
+ * @param {number|string} n
122
+ * @returns {this}
123
+ */
124
+ highlight(n) {
125
+ const index = typeof n === 'number'
126
+ ? Math.trunc(n) - 1
127
+ : this._sources.findIndex((source) => source.id === String(n));
128
+ const button = this._buttons[index];
129
+ if (!button) return this;
130
+ if (typeof button.scrollIntoView === 'function') {
131
+ button.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: prefersReducedMotion(this.el) ? 'auto' : 'smooth' });
132
+ }
133
+ button.focus({ preventScroll: true });
134
+ if (this._highlightTimer) clearTimeout(this._highlightTimer);
135
+ for (const other of this._buttons) if (other !== button) delete other.dataset.state;
136
+ button.dataset.state = 'highlighted';
137
+ this._highlightTimer = setTimeout(() => {
138
+ this._highlightTimer = null;
139
+ if (button.dataset.state === 'highlighted') delete button.dataset.state;
140
+ }, HIGHLIGHT_MS);
141
+ return this;
142
+ }
143
+
144
+ /** @returns {Source[]} Copies of the sources, in order. */
145
+ getSources() {
146
+ return this._sources.map(cloneSource);
147
+ }
148
+
149
+ /** @returns {void} */
150
+ destroy() {
151
+ if (this._destroyed) return;
152
+ this._destroyed = true;
153
+ if (this._highlightTimer) clearTimeout(this._highlightTimer);
154
+ this._highlightTimer = null;
155
+ this._releaseTooltips();
156
+ super.destroy();
157
+ if (this._original) restoreTarget(this.el, this._original);
158
+ }
159
+
160
+ /**
161
+ * @private
162
+ * @param {unknown} sources
163
+ * @returns {void}
164
+ */
165
+ _build(sources) {
166
+ const active = this.el.ownerDocument?.activeElement ?? null;
167
+ const focused = active && this._list.contains(active)
168
+ ? /** @type {HTMLElement|null} */ (active.closest('[data-source]'))?.dataset.source ?? null
169
+ : null;
170
+ if (this._highlightTimer) clearTimeout(this._highlightTimer);
171
+ this._highlightTimer = null;
172
+ this._releaseTooltips();
173
+ this._sources = normalizeSources(sources);
174
+ this._buttons = [];
175
+ this._list.replaceChildren(...this._sources.map((source, index) => this._item(source, index)));
176
+ const root = /** @type {HTMLElement} */ (this.el);
177
+ if (this._sources.length) delete root.dataset.empty;
178
+ else root.dataset.empty = '';
179
+ if (focused) this._buttons.find((button) => button.dataset.source === focused)?.focus({ preventScroll: true });
180
+ }
181
+
182
+ /**
183
+ * @private
184
+ * @param {Source & {id: string}} source
185
+ * @param {number} index
186
+ * @returns {HTMLElement}
187
+ */
188
+ _item(source, index) {
189
+ const kind = sourceKind(source);
190
+ const n = index + 1;
191
+ const numbered = this.options.numbered !== false;
192
+ const where = sourcePlace(source);
193
+ const button = /** @type {HTMLButtonElement} */ (h('button', {
194
+ type: 'button',
195
+ class: 'zx-source-list__source',
196
+ dataset: { source: source.id, n: String(n), kind }
197
+ },
198
+ // Named "Source 1: bank.example", which keeps the visible "1" and name in the accessible name.
199
+ numbered ? [
200
+ h('span', { class: 'zx-source-list__sr' }, `${this.msg('sourceList.source')} `),
201
+ h('span', { class: 'zx-source-list__n' }, String(n)),
202
+ h('span', { class: 'zx-source-list__sr' }, ': ')
203
+ ] : null,
204
+ h('span', { class: 'zx-source-list__glyph', 'aria-hidden': 'true' }, icon(this._icon(kind), { size: 14 })),
205
+ this._layout === 'list'
206
+ ? h('span', { class: 'zx-source-list__copy' },
207
+ h('span', { class: 'zx-source-list__title' }, source.title || sourceName(source)),
208
+ where && where !== source.title ? h('span', { class: 'zx-source-list__site' }, where) : null)
209
+ : h('span', { class: 'zx-source-list__name' }, sourceName(source))));
210
+ this._buttons.push(button);
211
+ this._tooltips.push(new Tooltip(button, {
212
+ content: () => this._card(source),
213
+ placement: 'top-start',
214
+ maxWidth: 320
215
+ }));
216
+ return h('li', { class: 'zx-source-list__item' }, button);
217
+ }
218
+
219
+ /**
220
+ * The card a source shows on hover and focus: its title, where it is (the host of a web
221
+ * address), and the passage used.
222
+ * @private
223
+ * @param {Source & {id: string}} source
224
+ * @returns {HTMLElement}
225
+ */
226
+ _card(source) {
227
+ const kind = sourceKind(source);
228
+ const where = sourcePlace(source);
229
+ return h('span', { class: 'zx-source-list__card' },
230
+ h('span', { class: 'zx-source-list__card-title' }, source.title || sourceName(source)),
231
+ // A file named by its own title would say its name twice.
232
+ where && where !== (source.title || sourceName(source))
233
+ ? h('span', { class: 'zx-source-list__card-site' }, icon(this._icon(kind), { size: 12 }), where) : null,
234
+ source.snippet ? h('span', { class: 'zx-source-list__card-snippet' }, String(source.snippet)) : null);
235
+ }
236
+
237
+ /** @private @param {SourceKind} kind @returns {string} */
238
+ _icon(kind) {
239
+ const custom = this.options.icons?.[kind];
240
+ return typeof custom === 'string' && custom ? custom : SOURCE_ICONS[kind];
241
+ }
242
+
243
+ /** @private @returns {void} */
244
+ _releaseTooltips() {
245
+ for (const tooltip of this._tooltips) tooltip.destroy();
246
+ this._tooltips = [];
247
+ }
248
+
249
+ /**
250
+ * @private
251
+ * @param {MouseEvent} event
252
+ * @returns {void}
253
+ */
254
+ _onClick(event) {
255
+ const target = event.target instanceof Element ? event.target : null;
256
+ const button = /** @type {HTMLElement|null} */ (target?.closest('[data-source]') ?? null);
257
+ if (!button || !this._list.contains(button)) return;
258
+ const index = Number(button.dataset.n) - 1;
259
+ const source = this._sources[index];
260
+ if (!source) return;
261
+ const selected = this.emit('select', { source: cloneSource(source), n: index + 1 }, { honorDomCancellation: true });
262
+ if (selected.defaultPrevented) return;
263
+ const href = sourceHref(source);
264
+ if (href) window.open(href, '_blank', 'noopener,noreferrer');
265
+ }
266
+ }
267
+
268
+ /**
269
+ * Fired when a source is activated. Preventable: `preventDefault()` keeps a web source from
270
+ * opening its address.
271
+ * @event SourceList#select
272
+ * @type {CustomEvent<{source: Source, n: number}>}
273
+ */
274
+
275
+ /* ------------------------------------------------------------------ pure helpers -- */
276
+
277
+ /**
278
+ * @param {unknown} sources
279
+ * @returns {Array<Source & {id: string}>}
280
+ */
281
+ function normalizeSources(sources) {
282
+ /** @type {Array<Source & {id: string}>} */
283
+ const out = [];
284
+ (Array.isArray(sources) ? sources : []).forEach((source, index) => {
285
+ if (!source || typeof source !== 'object') return;
286
+ const id = source.id == null || source.id === '' ? `source-${index + 1}` : String(source.id);
287
+ out.push({ ...cloneSource(source), id, title: source.title == null ? '' : String(source.title) });
288
+ });
289
+ return out;
290
+ }
291
+
292
+ /** @param {Source} source @returns {Source} A copy that shares nothing with the original. */
293
+ function cloneSource(source) {
294
+ const copy = { ...source };
295
+ if (source.ref && typeof source.ref === 'object') copy.ref = { ...source.ref };
296
+ return copy;
297
+ }
298
+
299
+ /**
300
+ * A source's kind; a source without one is a web source.
301
+ * @param {Source|null|undefined} source
302
+ * @returns {SourceKind}
303
+ */
304
+ export function sourceKind(source) {
305
+ const kind = source?.kind ?? 'web';
306
+ return Object.hasOwn(SOURCE_ICONS, kind) ? kind : 'web';
307
+ }
308
+
309
+ /**
310
+ * The address a source may open: a `web` source's `href`, only when it is an absolute `https:`
311
+ * URL that `safeHref()` accepts. Anything else — another kind, a relative or `http:` address, a
312
+ * script scheme — gives null.
313
+ * @param {Source|null|undefined} source
314
+ * @returns {string|null}
315
+ */
316
+ export function sourceHref(source) {
317
+ if (!source || typeof source !== 'object' || sourceKind(source) !== 'web') return null;
318
+ const href = safeHref(source.href);
319
+ if (!href) return null;
320
+ try {
321
+ const url = new URL(href);
322
+ return url.protocol === 'https:' ? url.href : null;
323
+ } catch {
324
+ return null;
325
+ }
326
+ }
327
+
328
+ /**
329
+ * The host a web source opens, for its card: "bank.example". Null when it opens nothing.
330
+ * @param {Source|null|undefined} source
331
+ * @returns {string|null}
332
+ */
333
+ export function sourceHost(source) {
334
+ const href = sourceHref(source);
335
+ return href ? new URL(href).host : null;
336
+ }
337
+
338
+ /**
339
+ * The short name a chip shows: the source's `site`, else its title.
340
+ * @param {Source|null|undefined} source
341
+ * @returns {string}
342
+ */
343
+ export function sourceName(source) {
344
+ const site = source?.site == null ? '' : String(source.site).trim();
345
+ return site || (source?.title == null ? '' : String(source.title));
346
+ }
347
+
348
+ /**
349
+ * Where a source is, for its card and list row: the host a web source opens, else its `site`.
350
+ * @param {Source} source
351
+ * @returns {string}
352
+ */
353
+ function sourcePlace(source) {
354
+ return sourceHost(source) ?? (source.site == null ? '' : String(source.site));
355
+ }