dsh-project-mcp 0.2.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.
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The translate seat of the sidebar tab.
3
+ *
4
+ * The native Settings page registers through `settings.section` / `slots`,
5
+ * which hands its component the framework's own `t` seat. The tab has neither:
6
+ * it is created by the sidebar service, so its
7
+ * panel used to render the module's English dictionary while the rest of the
8
+ * shell followed the language preference.
9
+ *
10
+ * The tab's translator is built here, out of the one locale face the shell
11
+ * publishes on the client context (`ctx.get('locale')` — the DSH `LocaleRuntime`
12
+ * every dictionary registers into): the component binds the plugin's namespace
13
+ * to it, subscribes to the locale snapshot, and repaints on a language switch.
14
+ * The same namespace is registered from `./index.ts` with the merged
15
+ * three-language dictionary, so a key the shell translates wins, and the
16
+ * fallback inside {@link uiTranslate} is only the last resort for a composition
17
+ * without a locale service — a test, or a browser half newer than the host.
18
+ *
19
+ * @module dsh-project-mcp/client/tab-locale
20
+ */
21
+
22
+ import { useEffect, useState } from 'react'
23
+ import { uiTranslate } from './locales/ui.ts'
24
+ import type { Translate } from './view.ts'
25
+
26
+ /**
27
+ * The slice of the client locale service the tab needs, mirrored structurally.
28
+ *
29
+ * The DSH client packages are provided by the web shell and are not dependencies
30
+ * of this one, so the seat is bound by shape rather than by import — the same
31
+ * reason the settings page mirrors its slot services. `subscribe` is optional:
32
+ * a service that publishes no snapshot never notifies, and the tab then renders
33
+ * whatever language it was opened in.
34
+ */
35
+ export interface TabLocale {
36
+ /** Bind one namespace to a translate function that follows the active locale. */
37
+ bind(namespace: string): Translate
38
+ /** Subscribe to locale changes (a language switch or a late registration). */
39
+ subscribe?(listener: () => void): () => void
40
+ }
41
+
42
+ /**
43
+ * The locale service out of the client context, when the composition has one.
44
+ *
45
+ * The read goes through `ctx.get`, never through a property: Cordis throws
46
+ * `cannot get property "locale" without inject` for a service this fiber did not
47
+ * declare, and that throw takes the whole web client boot down with it. A
48
+ * composition without a locale service answers `undefined`, and the tab keeps
49
+ * its own English table.
50
+ * @param ctx - the client context `apply` was called with.
51
+ * @returns the locale service, or undefined when there is none.
52
+ */
53
+ export function localeServiceOf(ctx: unknown): TabLocale | undefined {
54
+ if (ctx === null || typeof ctx !== 'object') return undefined
55
+ const get = (ctx as { get?: unknown }).get
56
+ if (typeof get !== 'function') return undefined
57
+ const candidate = (get as (name: string) => unknown).call(ctx, 'locale')
58
+ if (candidate === null || typeof candidate !== 'object') return undefined
59
+ return typeof (candidate as Partial<TabLocale>).bind === 'function'
60
+ ? (candidate as TabLocale)
61
+ : undefined
62
+ }
63
+
64
+ /**
65
+ * The tab's translator, bound to the shell's locale service.
66
+ *
67
+ * A thin delegate to {@link uiTranslate}, the one translator both seats share:
68
+ * the bound namespace answers first, the merged English table answers a key
69
+ * the active language lacks, and the raw key shows only when even English has
70
+ * nothing for it.
71
+ * @param locale - the locale service, when there is one.
72
+ * @returns a translate function that always answers.
73
+ */
74
+ export function tabTranslate(locale: TabLocale | undefined): Translate {
75
+ return uiTranslate(locale)
76
+ }
77
+
78
+ /**
79
+ * The tab's translator as a hook: bound once, re-bound when the language
80
+ * changes.
81
+ *
82
+ * The tab component is the one surface of this plugin rendered outside the slot
83
+ * framework, so it is the one place a repaint has to be asked for explicitly.
84
+ * @param locale - the locale service, when there is one.
85
+ * @returns the translate seat the panel renders through.
86
+ */
87
+ export function useTabTranslate(locale: TabLocale | undefined): Translate {
88
+ const [seat, setSeat] = useState<Translate>(() => tabTranslate(locale))
89
+ useEffect(() => {
90
+ setSeat(tabTranslate(locale))
91
+ return locale?.subscribe?.(() => setSeat(tabTranslate(locale)))
92
+ }, [locale])
93
+ return seat
94
+ }
@@ -0,0 +1,553 @@
1
+ /**
2
+ * `dsh-project-mcp`, frame-wide toasts: one banner per MCP server that comes
3
+ * up, fails, or is released — announced wherever the user is, rather than only
4
+ * inside the sidebar tab's «Logs» mode.
5
+ *
6
+ * The seat is `shell.overlay` (`kind: 'list'`, `scope: 'root'`), DSH's
7
+ * frame-wide floating layer: additive, owned by no feature, and click-through
8
+ * until an entry opts into pointer events. Its catalog names a toast stack as
9
+ * one of the things that belong there, so this module adds an entry **beside**
10
+ * the shipped ones and declares no slot of its own. The composer dock that
11
+ * F-05 removed is not coming back: nothing here paints into a surface this
12
+ * plugin does not own.
13
+ *
14
+ * The source is the host's status channel, `GET /project-mcp/events` (see
15
+ * `createEventStream` in `src/ui.ts`), the same stream the sidebar panel falls
16
+ * back from polling to. A toast is not a second source of truth: every frame
17
+ * carries the whole snapshot, and this module only diffs the picture it already
18
+ * had for {@link ServerRow.status} transitions, so a missed frame costs one
19
+ * banner rather than a wrong one.
20
+ *
21
+ * What a toast cannot say: a **stall** is not a lifecycle transition in the
22
+ * snapshot — the row stays `connecting` and only its `detail` wording changes —
23
+ * so stalls stay in the «Logs» tab and in the DSH log instead of becoming
24
+ * banners.
25
+ *
26
+ * A draft carries dictionary keys and parameters, never a finished sentence:
27
+ * the stack resolves them at render through the tab's translate seat
28
+ * (`useTabTranslate`), so a language switch repaints the banners already on
29
+ * screen instead of freezing the language of whatever the store holds (F-47).
30
+ *
31
+ * @module dsh-project-mcp/client/toasts
32
+ */
33
+
34
+ import { createElement as h, useEffect, useState } from 'react'
35
+ import type { CSSProperties, ReactNode } from 'react'
36
+ import { ROUTE_ACTIONS, ROUTE_PREFIX } from '../shared.ts'
37
+ import type { McpSnapshot, ServerRow, SnapshotChange } from '../types.ts'
38
+ import type { UiKey } from './locales/ui.ts'
39
+ import { hostTranslate, resolveHost } from './locales/host.ts'
40
+ import { useTabTranslate } from './tab-locale.ts'
41
+ import type { TabLocale } from './tab-locale.ts'
42
+ import { STATUS_COLOR, STATUS_HINT, basename, translateOf } from './view.ts'
43
+ import type { Translate } from './view.ts'
44
+
45
+ /** Slot the stack registers into: DSH's frame-wide floating layer. */
46
+ export const TOASTS_SLOT = 'shell.overlay'
47
+
48
+ /** Registration id, unique among the layer's entries, and the cell it owns. */
49
+ export const TOASTS_ID = 'dsh-project-mcp:toasts'
50
+
51
+ /** Position among the layer's entries, ascending. */
52
+ export const TOASTS_ORDER = 60
53
+
54
+ /** Full-opacity hold before a banner starts to fade, matching DSH's own toast. */
55
+ export const TOAST_HOLD_MS = 3_000
56
+
57
+ /** Fade duration, matching the `transition` the banner carries. */
58
+ export const TOAST_FADE_MS = 1_000
59
+
60
+ /**
61
+ * Banners kept on screen at once.
62
+ *
63
+ * A pass can start every server of a project in one go, and a stack taller than
64
+ * the window is a stack nobody reads: the newest {@link MAX_TOASTS} are kept
65
+ * and older ones drop, the same way a notification centre ages out its tail.
66
+ */
67
+ export const MAX_TOASTS = 3
68
+
69
+ /** Which lifecycle moment a banner reports. */
70
+ export type ToastLevel =
71
+ /** The server reached `active`: mounted, its tools are visible. */
72
+ | 'up'
73
+ /** The server landed in `error`: the entry or its mount failed. */
74
+ | 'error'
75
+ /** An active server went back to `idle`: its mounts were dropped. */
76
+ | 'released'
77
+
78
+ /** One banner before the store stamps it with an identity. */
79
+ export interface ToastDraft {
80
+ readonly level: ToastLevel
81
+ /** `serverName` the transition belongs to. */
82
+ readonly server: string
83
+ /** Basename of the project root, so a banner fits on one line. */
84
+ readonly project: string
85
+ /**
86
+ * Dictionary key of the one line — what happened to the server — resolved
87
+ * through the seat at render, so a stored banner follows a language switch.
88
+ */
89
+ readonly textKey: UiKey
90
+ /** Parameters of that line (`{server}`). */
91
+ readonly textParams?: Record<string, unknown> | undefined
92
+ /**
93
+ * Dictionary key of the fact the quieter line explains — a status hint —
94
+ * with the project woven around it (`toastDetail`). Absent, the quieter line
95
+ * is just {@link ToastDraft.detail}, a language-neutral string.
96
+ */
97
+ readonly detailKey?: UiKey | undefined
98
+ /**
99
+ * The host's own fact sentence, shown instead of the keyed hint when the row
100
+ * carries one; when {@link ToastDraft.detailKey} is absent, the whole
101
+ * quieter line (the project basename).
102
+ */
103
+ readonly detail?: string | undefined
104
+ /**
105
+ * Wire companions of {@link ToastDraft.detail} (F-48): the row's
106
+ * `detailCode`/`detailParams`, carried through so the quieter line resolves
107
+ * through the host namespace at render and falls back to the prose when the
108
+ * code is absent or unknown.
109
+ */
110
+ readonly detailCode?: string | undefined
111
+ /** Flat params of {@link ToastDraft.detailCode}. */
112
+ readonly detailParams?: Record<string, string> | undefined
113
+ }
114
+
115
+ /** One banner on screen. */
116
+ export interface Toast extends ToastDraft {
117
+ /** Identity the store mints; also the React key and the dismiss handle. */
118
+ readonly id: number
119
+ }
120
+
121
+ /**
122
+ * The stack's own state.
123
+ *
124
+ * A plain observable rather than React state, because the writer is the status
125
+ * channel and the reader is the slot entry: they are not in one component tree,
126
+ * and only the store has to survive the slot re-registering.
127
+ */
128
+ export interface ToastStore {
129
+ /** Current banners, newest first. */
130
+ getSnapshot(): readonly Toast[]
131
+ /** Listen for changes; returns the unsubscribe. */
132
+ subscribe(listener: () => void): () => void
133
+ /** Add one banner, dropping the tail beyond the limit. */
134
+ push(draft: ToastDraft): void
135
+ /** Retire one banner; an unknown id is a no-op. */
136
+ dismiss(id: number): void
137
+ }
138
+
139
+ /**
140
+ * Build one stack's store.
141
+ * @param limit - banners kept at once; defaults to {@link MAX_TOASTS}.
142
+ * @returns the store the entry renders from.
143
+ */
144
+ export function createToastStore(limit: number = MAX_TOASTS): ToastStore {
145
+ let toasts: readonly Toast[] = []
146
+ let minted = 0
147
+ const listeners = new Set<() => void>()
148
+ /** Publish one new array: the snapshot identity is what React compares. */
149
+ const publish = (next: readonly Toast[]): void => {
150
+ toasts = next
151
+ for (const listener of [...listeners]) listener()
152
+ }
153
+ return {
154
+ getSnapshot: () => toasts,
155
+ subscribe(listener) {
156
+ listeners.add(listener)
157
+ return () => {
158
+ listeners.delete(listener)
159
+ }
160
+ },
161
+ push(draft) {
162
+ minted += 1
163
+ publish([{ ...draft, id: minted }, ...toasts].slice(0, Math.max(0, limit)))
164
+ },
165
+ dismiss(id) {
166
+ const next = toasts.filter((toast) => toast.id !== id)
167
+ if (next.length !== toasts.length) publish(next)
168
+ },
169
+ }
170
+ }
171
+
172
+ /** Identity of one row across frames: a server name is unique per project. */
173
+ function keyOf(row: ServerRow): string {
174
+ return `${row.projectRoot}\u0000${row.name}`
175
+ }
176
+
177
+ /**
178
+ * Every row of one picture, keyed by project and server.
179
+ * @param snapshot - a picture.
180
+ * @returns the keyed rows.
181
+ */
182
+ function rowsOf(snapshot: McpSnapshot): Map<string, ServerRow> {
183
+ const rows = new Map<string, ServerRow>()
184
+ for (const project of snapshot.projects) {
185
+ for (const row of project.rows) rows.set(keyOf(row), row)
186
+ }
187
+ return rows
188
+ }
189
+
190
+ /** The banner one row's new state earns, when it earns one. */
191
+ function transitionToast(was: ServerRow | undefined, row: ServerRow): ToastDraft | undefined {
192
+ const project = basename(row.projectRoot)
193
+ if (row.status === 'active') {
194
+ return {
195
+ level: 'up',
196
+ server: row.name,
197
+ project,
198
+ textKey: 'toastUp',
199
+ textParams: { server: row.name },
200
+ detail: project,
201
+ }
202
+ }
203
+ if (row.status === 'error') {
204
+ return {
205
+ level: 'error',
206
+ server: row.name,
207
+ project,
208
+ textKey: 'toastFailed',
209
+ textParams: { server: row.name },
210
+ detailKey: STATUS_HINT.error,
211
+ detail: row.detail,
212
+ ...(row.detailCode === undefined ? {} : { detailCode: row.detailCode }),
213
+ ...(row.detailParams === undefined ? {} : { detailParams: row.detailParams }),
214
+ }
215
+ }
216
+ // Only an active server *loses* mounts; `idle` reached from `connecting` or
217
+ // `disabled` is a picture of a server that never came up, not a release.
218
+ if (row.status === 'idle' && was?.status === 'active') {
219
+ return {
220
+ level: 'released',
221
+ server: row.name,
222
+ project,
223
+ textKey: 'toastReleased',
224
+ textParams: { server: row.name },
225
+ detailKey: STATUS_HINT.idle,
226
+ }
227
+ }
228
+ return undefined
229
+ }
230
+
231
+ /**
232
+ * The banners two consecutive pictures earn.
233
+ *
234
+ * Read from status alone, and only when the status actually changed: a rescan
235
+ * that re-derives the same rows announces nothing, and a row that moves between
236
+ * two non-terminal states (`idle → connecting` on the next turn's lazy mount)
237
+ * is not a lifecycle moment worth a banner.
238
+ * @param previous - the picture already applied; `undefined` makes `next` the baseline.
239
+ * @param next - the picture a `change` frame just delivered.
240
+ * @returns banners, oldest transition first; empty for a baseline or a quiet frame.
241
+ */
242
+ export function serverTransitions(previous: McpSnapshot | undefined, next: McpSnapshot): ToastDraft[] {
243
+ if (previous === undefined) return []
244
+ const before = rowsOf(previous)
245
+ const drafts: ToastDraft[] = []
246
+ for (const [key, row] of rowsOf(next)) {
247
+ const was = before.get(key)
248
+ if (was?.status === row.status) continue
249
+ const draft = transitionToast(was, row)
250
+ if (draft !== undefined) drafts.push(draft)
251
+ }
252
+ return drafts
253
+ }
254
+
255
+ /**
256
+ * Read one frame's payload.
257
+ *
258
+ * A frame this plugin cannot read is dropped, not guessed at: the stream is
259
+ * whole-picture, so the next frame is a complete answer, and a half-parsed
260
+ * snapshot would produce phantom transitions.
261
+ * @param data - `MessageEvent.data` of a `hello`/`change` frame.
262
+ * @returns the change, or `undefined` when the payload is not one.
263
+ */
264
+ export function parseChange(data: unknown): SnapshotChange | undefined {
265
+ if (typeof data !== 'string') return undefined
266
+ let parsed: unknown
267
+ try {
268
+ parsed = JSON.parse(data)
269
+ } catch {
270
+ return undefined
271
+ }
272
+ if (parsed === null || typeof parsed !== 'object') return undefined
273
+ const { revision, snapshot } = parsed as { revision?: unknown; snapshot?: unknown }
274
+ if (typeof revision !== 'number') return undefined
275
+ if (snapshot === null || typeof snapshot !== 'object') return undefined
276
+ if (!Array.isArray((snapshot as { projects?: unknown }).projects)) return undefined
277
+ return { revision, snapshot: snapshot as McpSnapshot }
278
+ }
279
+
280
+ /** The part of `EventSource` this module uses, so a test can hand it a stand-in. */
281
+ export interface FollowSource {
282
+ addEventListener(type: string, listener: (event: Event) => void): void
283
+ close(): void
284
+ }
285
+
286
+ /**
287
+ * How the channel is opened.
288
+ *
289
+ * A seam for tests: the channel is the one thing in this module that talks to
290
+ * the browser, so a test hands it a stand-in rather than patching a global, and
291
+ * the default is the only place that reaches for `EventSource`.
292
+ */
293
+ export type OpenSource = (url: string) => FollowSource | undefined
294
+
295
+ /** Open the status channel, or nothing in an environment without `EventSource`. */
296
+ function defaultOpen(url: string): FollowSource | undefined {
297
+ return typeof EventSource === 'undefined' ? undefined : new EventSource(url)
298
+ }
299
+
300
+ /**
301
+ * Follow the host's status channel and raise one banner per transition.
302
+ *
303
+ * The stream carries two frame kinds: `hello` is the picture as it is — on
304
+ * open and on every reconnect the browser's `EventSource` performs — and
305
+ * `change` is one announced change. `hello` only resets the baseline, so a page
306
+ * load, a dropped connection and a late join never read as twenty servers
307
+ * starting at once. A frame whose revision is not newer than the last applied
308
+ * one is repeated or replayed, and is ignored for the same reason.
309
+ * @param store - the stack to push banners into.
310
+ * @param open - channel factory; defaults to a real `EventSource`.
311
+ * @returns the disposer that closes the channel.
312
+ */
313
+ export function followServers(store: ToastStore, open: OpenSource = defaultOpen): () => void {
314
+ const source = open(`${ROUTE_PREFIX}/${ROUTE_ACTIONS.events}`)
315
+ if (source === undefined) return () => undefined
316
+ let previous: McpSnapshot | undefined
317
+ let revision = Number.NEGATIVE_INFINITY
318
+ /** Apply one frame's picture; `raise` is false for the baseline `hello`. */
319
+ const apply = (event: Event, raise: boolean): void => {
320
+ const change = parseChange((event as MessageEvent).data)
321
+ if (change === undefined || change.revision <= revision) return
322
+ if (raise) {
323
+ for (const draft of serverTransitions(previous, change.snapshot)) store.push(draft)
324
+ }
325
+ previous = change.snapshot
326
+ revision = change.revision
327
+ }
328
+ source.addEventListener('hello', (event) => apply(event, false))
329
+ source.addEventListener('change', (event) => apply(event, true))
330
+ return () => source.close()
331
+ }
332
+
333
+ /** The slot service, as this registrant uses it; mirrored structurally, not imported. */
334
+ export interface ToastSlots {
335
+ inject(slot: string, callback: () => unknown): unknown
336
+ register<Props>(
337
+ options: { name: string; id: string; order: number },
338
+ component: (props: Props) => ReactNode,
339
+ ): () => void
340
+ }
341
+
342
+ /**
343
+ * The one client service the stack needs.
344
+ *
345
+ * It is optional in a composition — a shell without the floating layer simply
346
+ * has no banners — which is why registration goes through `ctx.inject` rather
347
+ * than a module-level `inject` list: a composition without `slots` must keep
348
+ * the sidebar tab and the settings page, and must not leave this entry pending.
349
+ * The locale service is the tab's own seat: with it, a language switch repaints
350
+ * the banners on screen; without it, the stack renders its English fallback.
351
+ */
352
+ export interface ToastsServices {
353
+ slots: ToastSlots
354
+ /** The shell's locale service, when the composition has one. */
355
+ locale?: TabLocale | undefined
356
+ }
357
+
358
+ /**
359
+ * Contribute the stack to the frame's floating layer.
360
+ *
361
+ * `slots.register` throws on a duplicate list id, so the entry and the channel
362
+ * are installed behind one disposer and that disposer is returned to
363
+ * `slots.inject`: a second run — the layer's declaration collapsing and coming
364
+ * back, or an HMR reload — tears the first activation down before the second
365
+ * registers, instead of throwing away the whole entry or following the channel
366
+ * twice.
367
+ * @param services - the injected `slots` service, and the locale seat.
368
+ */
369
+ export function registerToasts(services: ToastsServices): void {
370
+ const store = createToastStore()
371
+ /** The live activation, so a repeat of the injection can never leave two. */
372
+ let stop: (() => void) | undefined
373
+ services.slots.inject(TOASTS_SLOT, () => {
374
+ stop?.()
375
+ const entry = services.slots.register({ name: TOASTS_SLOT, id: TOASTS_ID, order: TOASTS_ORDER }, () =>
376
+ h(ToastStack, { store, locale: services.locale }),
377
+ )
378
+ const channel = followServers(store)
379
+ stop = () => {
380
+ channel()
381
+ entry()
382
+ stop = undefined
383
+ }
384
+ return stop
385
+ })
386
+ }
387
+
388
+ /** The tones a banner's dot takes, from the panel's own status palette. */
389
+ const LEVEL_COLOR: Record<ToastLevel, string> = {
390
+ up: STATUS_COLOR.active,
391
+ error: STATUS_COLOR.error,
392
+ released: STATUS_COLOR.idle,
393
+ }
394
+
395
+ /**
396
+ * The stack's own styles.
397
+ *
398
+ * The banner mirrors DSH's shipped `Toast` (`ui-primitives`): the same alias
399
+ * variables, radius, padding and type, so a banner reads as a shell surface
400
+ * rather than a plugin's own invention. The difference is placement — that
401
+ * toast portals to the body and centers itself on the viewport, while this one
402
+ * is an entry of the floating layer, which spans the frame and already sits
403
+ * above every column.
404
+ */
405
+ const STYLE = {
406
+ stack: {
407
+ position: 'absolute',
408
+ top: 12,
409
+ left: '50%',
410
+ transform: 'translateX(-50%)',
411
+ display: 'flex',
412
+ flexDirection: 'column',
413
+ alignItems: 'center',
414
+ gap: 8,
415
+ // Same bound as one banner: the frame's center is where a long failure
416
+ // sentence would otherwise size itself against half the window.
417
+ maxWidth: 'min(640px, calc(100vw - 48px))',
418
+ // Announcements never intercept clicks: the layer is click-through until an
419
+ // entry opts in, and this entry opts back out for its whole subtree.
420
+ pointerEvents: 'none',
421
+ } satisfies CSSProperties,
422
+ banner: {
423
+ display: 'flex',
424
+ alignItems: 'center',
425
+ gap: 10,
426
+ width: 'max-content',
427
+ maxWidth: 'min(640px, calc(100vw - 48px))',
428
+ padding: '12px 16px',
429
+ borderRadius: 14,
430
+ background: 'var(--dsw-alias-button-contrast-fill, rgba(20, 22, 26, 0.92))',
431
+ color: 'var(--dsw-alias-label-primary-inverted, #fff)',
432
+ fontSize: 14,
433
+ lineHeight: '22px',
434
+ boxShadow: 'var(--dsw-shadow-lv3, 0 8px 24px rgba(0, 0, 0, 0.28))',
435
+ transition: `opacity ${TOAST_FADE_MS}ms ease`,
436
+ } satisfies CSSProperties,
437
+ /** The tail of a banner's life: it is already retired, only the fade is left. */
438
+ fading: { opacity: 0 } satisfies CSSProperties,
439
+ dot: {
440
+ flex: 'none',
441
+ width: 8,
442
+ height: 8,
443
+ borderRadius: 999,
444
+ } satisfies CSSProperties,
445
+ body: { minWidth: 0 } satisfies CSSProperties,
446
+ detail: { opacity: 0.75, fontSize: 12, lineHeight: '18px' } satisfies CSSProperties,
447
+ } as const
448
+
449
+ /** Read one banner off the store and follow it while the entry is mounted. */
450
+ function useToasts(store: ToastStore): readonly Toast[] {
451
+ const [toasts, setToasts] = useState<readonly Toast[]>(store.getSnapshot())
452
+ useEffect(() => store.subscribe(() => setToasts(store.getSnapshot())), [store])
453
+ return toasts
454
+ }
455
+
456
+ /**
457
+ * The stack the floating layer renders.
458
+ *
459
+ * Nothing is rendered while there is nothing to say, so the layer holds no
460
+ * empty box between banners. The live-region role is on the stack rather than
461
+ * on a banner, because a banner mounts and unmounts on its own timer. The
462
+ * translate seat is bound here: drafts carry keys, and `useTabTranslate`
463
+ * re-reads them when the shell's language changes, so the banners on screen
464
+ * repaint without the store re-deriving anything.
465
+ * @param props.store - the stack's state.
466
+ * @param props.locale - the shell's locale service, when there is one.
467
+ * @returns the banners, newest first, or `null`.
468
+ */
469
+ export function ToastStack(props: { store: ToastStore; locale?: TabLocale | undefined }): ReactNode {
470
+ const toasts = useToasts(props.store)
471
+ const t = useTabTranslate(props.locale)
472
+ // The host namespace beside the UI one: a banner whose row carried a coded
473
+ // detail (F-48) resolves it through this seat, and the repaint still rides
474
+ // on `t`'s re-bind.
475
+ const hostT = hostTranslate(props.locale)
476
+ if (toasts.length === 0) return null
477
+ return h(
478
+ 'div',
479
+ { style: STYLE.stack, role: 'status', 'aria-live': 'polite' },
480
+ toasts.map((toast) => h(ToastRow, { key: toast.id, toast, store: props.store, t, hostT })),
481
+ )
482
+ }
483
+
484
+ /**
485
+ * The quieter line of one banner, resolved through the seat at render time.
486
+ *
487
+ * A keyed fact is a status hint the project is woven around (`toastDetail`);
488
+ * the host's own detail sentence wins over the hint when the row carries one;
489
+ * a draft with no key at all shows its language-neutral line as it is. A coded
490
+ * detail (F-48) resolves through the host seat first and falls back to its
491
+ * prose when the code is absent or unknown, so an uncoded banner reads exactly
492
+ * as before.
493
+ * @param toast - the banner to read.
494
+ * @param t - the translate seat.
495
+ * @param hostT - the host-namespace seat; the echo seat answers without one.
496
+ * @returns the line, or `undefined` when the banner has none.
497
+ */
498
+ function detailLine(toast: ToastDraft, t: Translate, hostT: Translate): string | undefined {
499
+ if (toast.detailKey === undefined) {
500
+ if (toast.detail === undefined && toast.detailCode === undefined) return undefined
501
+ return resolveHost(hostT, toast.detailCode, toast.detailParams, toast.detail)
502
+ }
503
+ const fact =
504
+ toast.detailCode === undefined
505
+ ? toast.detail ?? t(toast.detailKey)
506
+ : resolveHost(hostT, toast.detailCode, toast.detailParams, toast.detail ?? t(toast.detailKey))
507
+ return t('toastDetail', { project: toast.project, detail: fact })
508
+ }
509
+
510
+ /**
511
+ * One banner: full opacity for {@link TOAST_HOLD_MS}, then a fade of
512
+ * {@link TOAST_FADE_MS}, then retired from the store.
513
+ *
514
+ * Two timers rather than one, because the fade is a real transition the user
515
+ * sees; a single timer would drop the banner from full opacity to nothing.
516
+ * @param props.toast - the banner to draw.
517
+ * @param props.store - the stack it belongs to, so it can retire itself.
518
+ * @param props.t - the translate seat the stack bound; the panel's English
519
+ * fallback answers without one.
520
+ * @returns the banner element.
521
+ */
522
+ export function ToastRow(props: {
523
+ toast: Toast
524
+ store: ToastStore
525
+ t?: Translate | undefined
526
+ /** Host-namespace seat for a coded detail (F-48); the echo seat answers without one. */
527
+ hostT?: Translate | undefined
528
+ }): ReactNode {
529
+ const [fading, setFading] = useState(false)
530
+ const { store, toast } = props
531
+ const t = translateOf(props.t)
532
+ const detail = detailLine(toast, t, props.hostT ?? hostTranslate(undefined))
533
+ useEffect(() => {
534
+ const hold = setTimeout(() => setFading(true), TOAST_HOLD_MS)
535
+ return () => clearTimeout(hold)
536
+ }, [])
537
+ useEffect(() => {
538
+ if (!fading) return
539
+ const fade = setTimeout(() => store.dismiss(props.toast.id), TOAST_FADE_MS)
540
+ return () => clearTimeout(fade)
541
+ }, [fading, store, props.toast.id])
542
+ return h(
543
+ 'div',
544
+ { style: fading ? { ...STYLE.banner, ...STYLE.fading } : STYLE.banner },
545
+ h('span', { style: { ...STYLE.dot, background: LEVEL_COLOR[toast.level] } }),
546
+ h(
547
+ 'span',
548
+ { style: STYLE.body },
549
+ h('div', null, t(toast.textKey, toast.textParams)),
550
+ detail === undefined ? null : h('div', { style: STYLE.detail }, detail),
551
+ ),
552
+ )
553
+ }