@aceshooting/lyra-ui 2.1.0 → 2.2.0

package/dist/components/stream-status/stream-status.class.js

@@ -0,0 +1,212 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+import { property, state, query } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../live-region/live-region.class.js';
+import { styles } from './stream-status.styles.js';
+const DEFAULT_STALL_MESSAGE = 'Taking longer than usual…';
+const STALL_ANNOUNCEMENT = 'Connection stalled.';
+const RECOVER_ANNOUNCEMENT = 'Connection restored.';
+// Used instead of RECOVER_ANNOUNCEMENT when a stall is left behind by moving
+// to 'idle'/'connecting' rather than back to 'streaming' -- see
+// announceTransition()'s caller in onPhaseChanged() for why "restored" would
+// be actively misleading in that case.
+const STALL_CLEARED_ANNOUNCEMENT = 'No longer stalled.';
+// The default slot's stalled-message content is often plain text with no
+// wrapping element at all (see the CustomStalledMessage story), so an
+// Element-only check never counts it, and ordinary indented-markup
+// whitespace (a newline + indentation before a slotted `actions` button, as
+// in the DefaultStalledMessage story) must not count either -- native <slot>
+// fallback content is suppressed by *any* assigned node, whitespace or not,
+// which previously left the message area blank in exactly that common case.
+// Mirrors lyra-citation-badge's identical isRealPreviewNode: a node counts as
+// real message content if it's an element not assigned to some other named
+// slot (e.g. `actions`), or non-whitespace text.
+function isRealMessageNode(n) {
+    return n.nodeType === Node.ELEMENT_NODE
+        ? !n.hasAttribute('slot')
+        : (n.textContent ?? '').trim().length > 0;
+}
+export class LyraStreamStatus extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Current connection phase. Settable directly by the host at any time —
+         *  see the class doc for how that interacts with the internal stall timer. */
+        this.phase = 'idle';
+        /** How long `phase` may stay `'streaming'` with no `recordActivity()` call
+         *  before this component declares it stalled. */
+        this.stallThresholdMs = 10000;
+        this.hasActionsSlot = false;
+        // Seeded from light-DOM childNodes in willUpdate() (mirrors hasActionsSlot
+        // above), then kept current via onMessageSlotChange() -- see
+        // isRealMessageNode()'s doc comment for why native <slot> fallback content
+        // can't be relied on for the default stalled-message text.
+        this.hasMessageContent = false;
+        this.onActionsSlotChange = (e) => {
+            this.hasActionsSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+        this.onMessageSlotChange = (e) => {
+            this.hasMessageContent = e.target.assignedNodes({ flatten: true }).some(isRealMessageNode);
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate() {
+        if (!this.hasUpdated) {
+            this.hasActionsSlot = this.hasSlotted('actions');
+            this.hasMessageContent = Array.from(this.childNodes).some(isRealMessageNode);
+        }
+    }
+    // `changed.get('phase')` is `undefined` on the very first update, for the
+    // same reason documented on lyra-chat-message's identical `updated()`
+    // guard: Lit only records the *first* old value seen since the last
+    // completed update, and the constructor's field-initializer assignment is
+    // that first change, from the truly-unset internal slot. That naturally
+    // skips firing an event/announcement for whatever phase this element
+    // happens to mount with, while still arming the stall timer below if it
+    // mounts already `'streaming'`.
+    //
+    // The `else if` below only matters while `phase` itself didn't also change
+    // in this same update -- if it did, onPhaseChanged() above already
+    // (re)armed the timer with the current `stallThresholdMs`, so re-arming it
+    // again here would just be redundant, not wrong, but the `else` skips that
+    // double work.
+    updated(changed) {
+        if (changed.has('phase')) {
+            this.onPhaseChanged(changed.get('phase'));
+        }
+        else if (changed.has('stallThresholdMs') && this.phase === 'streaming') {
+            // Unlike `phase` itself, `stallThresholdMs` has no dedicated handler --
+            // the already-armed timer was scheduled against the *old* value and
+            // keeps counting down against it otherwise, so a shortened (or
+            // lengthened) threshold would silently have no effect until the next
+            // recordActivity() call or phase transition happened to re-arm it.
+            this.armStallTimer();
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // A disconnect always disarms the timer (see disconnectedCallback()
+        // below), but reparenting this element elsewhere in the page while still
+        // `'streaming'` fires disconnectedCallback then connectedCallback with
+        // `phase` unchanged -- no `updated()` cycle runs in between, so nothing
+        // else would ever re-arm it. Without this, a reparent mid-stream would
+        // permanently disable stall detection for the rest of that streaming
+        // session.
+        if (this.phase === 'streaming')
+            this.armStallTimer();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.disarmStallTimer();
+    }
+    /**
+     * Call on every semantic (non-heartbeat) frame received while streaming.
+     * - While `phase === 'streaming'`: (re)arms the stall timer, pushing the
+     *   stall deadline `stall-threshold-ms` further out.
+     * - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'`
+     *   again, `lyra-recover` fires, and the stall timer is armed fresh (same
+     *   as the bullet above), all via the same `updated()` transition handling
+     *   a direct host assignment would also go through.
+     * - While `phase` is `'idle'` or `'connecting'`: a no-op. A host may call
+     *   this defensively before formally flipping to `'streaming'`; it must
+     *   never throw or start a timer early.
+     */
+    recordActivity() {
+        if (this.phase === 'streaming') {
+            this.armStallTimer();
+        }
+        else if (this.phase === 'stalled') {
+            this.phase = 'streaming';
+        }
+    }
+    onPhaseChanged(previous) {
+        if (this.phase === 'streaming') {
+            this.armStallTimer();
+        }
+        else {
+            this.disarmStallTimer();
+        }
+        if (previous === undefined)
+            return;
+        if (this.phase === 'stalled' && previous !== 'stalled') {
+            this.emit('lyra-stall');
+            this.announceTransition('assertive', STALL_ANNOUNCEMENT);
+        }
+        else if (previous === 'stalled' && this.phase !== 'stalled') {
+            // `lyra-recover` fires unconditionally -- a host may still want the
+            // event for any exit from 'stalled' -- but the *announced text* must
+            // not claim the connection was "restored" when the destination is
+            // 'idle'/'connecting': that's the host abandoning the stream, not it
+            // recovering, and telling a screen-reader user otherwise would be the
+            // opposite of what a sighted user sees on screen.
+            this.emit('lyra-recover');
+            const text = this.phase === 'streaming' ? RECOVER_ANNOUNCEMENT : STALL_CLEARED_ANNOUNCEMENT;
+            this.announceTransition('polite', text);
+        }
+    }
+    armStallTimer() {
+        this.disarmStallTimer();
+        const threshold = this.stallThresholdMs;
+        if (!Number.isFinite(threshold) || threshold <= 0)
+            return;
+        this.stallTimer = setTimeout(() => {
+            this.stallTimer = undefined;
+            this.phase = 'stalled';
+        }, threshold);
+    }
+    disarmStallTimer() {
+        if (this.stallTimer !== undefined) {
+            clearTimeout(this.stallTimer);
+            this.stallTimer = undefined;
+        }
+    }
+    announceTransition(mode, text) {
+        const region = this.liveRegion;
+        if (!region)
+            return;
+        region.mode = mode;
+        region.announce(text, { force: true });
+    }
+    hasSlotted(name) {
+        return Array.from(this.children).some((el) => el.getAttribute('slot') === name);
+    }
+    render() {
+        return html `
+      <div part="base">
+        <span part="indicator" aria-hidden="true"></span>
+        ${this.phase === 'stalled'
+            ? html `<div part="message">
+              <slot @slotchange=${this.onMessageSlotChange}></slot>${this.hasMessageContent
+                ? nothing
+                : DEFAULT_STALL_MESSAGE}
+            </div>`
+            : nothing}
+        <div part="actions" ?hidden=${!this.hasActionsSlot}>
+          <slot name="actions" @slotchange=${this.onActionsSlotChange}></slot>
+        </div>
+        <lyra-live-region></lyra-live-region>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property({ reflect: true })
+], LyraStreamStatus.prototype, "phase", void 0);
+__decorate([
+    property({ type: Number, attribute: 'stall-threshold-ms' })
+], LyraStreamStatus.prototype, "stallThresholdMs", void 0);
+__decorate([
+    state()
+], LyraStreamStatus.prototype, "hasActionsSlot", void 0);
+__decorate([
+    state()
+], LyraStreamStatus.prototype, "hasMessageContent", void 0);
+__decorate([
+    query('lyra-live-region')
+], LyraStreamStatus.prototype, "liveRegion", void 0);
+//# sourceMappingURL=stream-status.class.js.map

package/dist/components/stream-status/stream-status.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-status.class.js","sourceRoot":"","sources":["../../../src/components/stream-status/stream-status.class.ts"],"names":[],"mappings":"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"}

package/dist/components/stream-status/stream-status.d.ts

@@ -1,126 +1,3 @@
-import { type TemplateResult, type PropertyValues } from 'lit';
-import { LyraElement } from '../../internal/lyra-element.js';
-import '../live-region/live-region.js';
-export type StreamStatusPhase = 'idle' | 'connecting' | 'streaming' | 'stalled';
-/**
- * `<lyra-stream-status>` — a compact status indicator for a single streaming
- * connection (SSE, WebSocket, long-poll, …), with built-in heartbeat-aware
- * stall detection.
- *
- * The host drives `phase` directly for `idle`/`connecting`/`streaming`, and
- * calls `recordActivity()` on every *semantic* frame received while
- * streaming — a real content chunk, never a transport-level keep-alive ping.
- * This component has no payload-inspection logic of its own: "ignore
- * heartbeats" is entirely a call-site discipline — the host simply never
- * calls `recordActivity()` for a ping, so pings never reset the stall timer
- * and a connection that's only sending keep-alives (no real content) for
- * longer than `stall-threshold-ms` correctly reads as stalled.
- *
- * Internally, an inactivity timer runs only while `phase === 'streaming'`.
- * It's (re)armed whenever the phase transitions to `'streaming'` (directly,
- * or via `recordActivity()` recovering from `'stalled'`), on every
- * subsequent `recordActivity()` call while already streaming, whenever
- * `stall-threshold-ms` itself changes while already streaming (the new
- * value takes effect immediately, the same way `<lyra-toast-item>`'s
- * `duration` re-applies mid-flight, rather than waiting for the next
- * `recordActivity()`/phase change), and whenever this element (re)connects
- * to the DOM while `phase` is still `'streaming'` (a disconnect always
- * disarms it, so moving the element elsewhere in the page — disconnect then
- * reconnect with `phase` unchanged — must resume detection rather than
- * silently disabling it for the rest of the streaming session). It's
- * disarmed the instant `phase` becomes anything else, including a
- * host-driven reassignment away from `'streaming'` — so a stale timer can
- * never fire a stall transition after the host has already moved on. If it
- * ever fires, `phase` becomes `'stalled'` and `lyra-stall` is dispatched.
- *
- * `phase` remains a fully public, directly settable property at all times —
- * a host can assign `'stalled'` (or any other phase) itself as a manual
- * override, and this component never fights that assignment. `lyra-stall`/
- * `lyra-recover` fire on *any* transition into/out of `'stalled'`
- * respectively, whether timer-driven or host-driven, and never for a
- * reassignment to the same value (Lit's default `hasChanged` already skips a
- * no-op set, same as every other reflected `@property` in this library).
- * Like `<lyra-chat-message>`'s `status`, whatever phase this element happens
- * to *mount* with is never itself treated as an eventful transition — only a
- * later change fires an event or an announcement.
- *
- * Accessibility: phase transitions into/out of `'stalled'` are announced
- * through an internal `<lyra-live-region>` (see that component for the
- * throttled/coalesced-announcement machinery this composes) rather than a
- * hand-rolled `aria-live` region. `recordActivity()` itself never announces
- * anything, no matter how often the host calls it — only the *transition*
- * announces, exactly once per transition, which is the entire point of
- * routing through the throttled announcer instead of writing to a live
- * region on every call. Entering `'stalled'` announces with `mode="assertive"`
- * (a stall can need the user's attention, e.g. before they give up and
- * navigate away); leaving `'stalled'` always announces with `mode="polite"`
- * (good news doesn't need to interrupt), but the *wording* depends on where
- * it lands: `"Connection restored."` only when the destination is
- * `'streaming'` (a genuine recovery), or a neutral `"No longer stalled."`
- * when the destination is `'idle'`/`'connecting'` instead — that's the host
- * giving up on the stream, not the stream recovering, and a screen-reader
- * user must never be told the opposite of what a sighted user sees on
- * screen. The decorative indicator dot is `aria-hidden` — it's a
- * color/motion cue only, never the sole carrier of state.
- *
- * Visual: `'stalled'` is styled as a warning, not a danger — a stall is
- * usually recoverable (the stream may resume on its own, or the host's own
- * retry logic may kick in), so treating it as an actionable warning rather
- * than a hard failure keeps the tone proportionate. A host that wants to
- * escalate to danger styling after N stalls can scope its own CSS off
- * `[phase="stalled"]`, or simply stop rendering this component and show its
- * own danger-styled error state instead.
- *
- * @customElement lyra-stream-status
- * @slot - Custom copy shown only while `phase="stalled"` (e.g. "Taking longer than usual…"). A sensible built-in default is used when nothing is slotted.
- * @slot actions - A stop/retry button row. Always present in the template regardless of `phase` — visibility is driven purely by whether anything is slotted, not by `phase`; what to put here, and when, is entirely the host's call.
- * @event lyra-stall - Fired whenever `phase` transitions into `'stalled'` from anything else (timer-driven, or a direct host assignment).
- * @event lyra-recover - Fired whenever `phase` transitions out of `'stalled'` to anything else (via `recordActivity()`, or a direct host assignment) — fired unconditionally regardless of destination phase, even though the accompanying announcement's wording varies (see the class doc's "Accessibility" section).
- * @csspart base - The root layout container.
- * @csspart indicator - The decorative (`aria-hidden`) status dot.
- * @csspart message - Wrapper around the default slot; only rendered while `phase="stalled"`.
- * @csspart actions - Wrapper around the `actions` slot.
- */
-export declare class LyraStreamStatus extends LyraElement {
-    static styles: import("lit").CSSResultGroup[];
-    /** Current connection phase. Settable directly by the host at any time —
-     *  see the class doc for how that interacts with the internal stall timer. */
-    phase: StreamStatusPhase;
-    /** How long `phase` may stay `'streaming'` with no `recordActivity()` call
-     *  before this component declares it stalled. */
-    stallThresholdMs: number;
-    private stallTimer?;
-    private hasActionsSlot;
-    private hasMessageContent;
-    private liveRegion?;
-    protected willUpdate(): void;
-    protected updated(changed: PropertyValues): void;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    /**
-     * Call on every semantic (non-heartbeat) frame received while streaming.
-     * - While `phase === 'streaming'`: (re)arms the stall timer, pushing the
-     *   stall deadline `stall-threshold-ms` further out.
-     * - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'`
-     *   again, `lyra-recover` fires, and the stall timer is armed fresh (same
-     *   as the bullet above), all via the same `updated()` transition handling
-     *   a direct host assignment would also go through.
-     * - While `phase` is `'idle'` or `'connecting'`: a no-op. A host may call
-     *   this defensively before formally flipping to `'streaming'`; it must
-     *   never throw or start a timer early.
-     */
-    recordActivity(): void;
-    private onPhaseChanged;
-    private armStallTimer;
-    private disarmStallTimer;
-    private announceTransition;
-    private hasSlotted;
-    private onActionsSlotChange;
-    private onMessageSlotChange;
-    render(): TemplateResult;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        'lyra-stream-status': LyraStreamStatus;
-    }
-}
+export * from './stream-status.class.js';
+import "../live-region/live-region.js";
+//# sourceMappingURL=stream-status.d.ts.map

package/dist/components/stream-status/stream-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-status.d.ts","sourceRoot":"","sources":["../../../src/components/stream-status/stream-status.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AAGzC,OAAO,+BAA+B,CAAC"}

package/dist/components/stream-status/stream-status.js

@@ -1,292 +1,6 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { html, nothing } from 'lit';
-import { property, state, query } from 'lit/decorators.js';
-import { LyraElement } from '../../internal/lyra-element.js';
+export * from './stream-status.class.js';
+import { LyraStreamStatus } from './stream-status.class.js';
 import { defineElement } from '../../internal/prefix.js';
-import '../live-region/live-region.js';
-import { styles } from './stream-status.styles.js';
-const DEFAULT_STALL_MESSAGE = 'Taking longer than usual…';
-const STALL_ANNOUNCEMENT = 'Connection stalled.';
-const RECOVER_ANNOUNCEMENT = 'Connection restored.';
-// Used instead of RECOVER_ANNOUNCEMENT when a stall is left behind by moving
-// to 'idle'/'connecting' rather than back to 'streaming' -- see
-// announceTransition()'s caller in onPhaseChanged() for why "restored" would
-// be actively misleading in that case.
-const STALL_CLEARED_ANNOUNCEMENT = 'No longer stalled.';
-// The default slot's stalled-message content is often plain text with no
-// wrapping element at all (see the CustomStalledMessage story), so an
-// Element-only check never counts it, and ordinary indented-markup
-// whitespace (a newline + indentation before a slotted `actions` button, as
-// in the DefaultStalledMessage story) must not count either -- native <slot>
-// fallback content is suppressed by *any* assigned node, whitespace or not,
-// which previously left the message area blank in exactly that common case.
-// Mirrors lyra-citation-badge's identical isRealPreviewNode: a node counts as
-// real message content if it's an element not assigned to some other named
-// slot (e.g. `actions`), or non-whitespace text.
-function isRealMessageNode(n) {
-    return n.nodeType === Node.ELEMENT_NODE
-        ? !n.hasAttribute('slot')
-        : (n.textContent ?? '').trim().length > 0;
-}
-/**
- * `<lyra-stream-status>` — a compact status indicator for a single streaming
- * connection (SSE, WebSocket, long-poll, …), with built-in heartbeat-aware
- * stall detection.
- *
- * The host drives `phase` directly for `idle`/`connecting`/`streaming`, and
- * calls `recordActivity()` on every *semantic* frame received while
- * streaming — a real content chunk, never a transport-level keep-alive ping.
- * This component has no payload-inspection logic of its own: "ignore
- * heartbeats" is entirely a call-site discipline — the host simply never
- * calls `recordActivity()` for a ping, so pings never reset the stall timer
- * and a connection that's only sending keep-alives (no real content) for
- * longer than `stall-threshold-ms` correctly reads as stalled.
- *
- * Internally, an inactivity timer runs only while `phase === 'streaming'`.
- * It's (re)armed whenever the phase transitions to `'streaming'` (directly,
- * or via `recordActivity()` recovering from `'stalled'`), on every
- * subsequent `recordActivity()` call while already streaming, whenever
- * `stall-threshold-ms` itself changes while already streaming (the new
- * value takes effect immediately, the same way `<lyra-toast-item>`'s
- * `duration` re-applies mid-flight, rather than waiting for the next
- * `recordActivity()`/phase change), and whenever this element (re)connects
- * to the DOM while `phase` is still `'streaming'` (a disconnect always
- * disarms it, so moving the element elsewhere in the page — disconnect then
- * reconnect with `phase` unchanged — must resume detection rather than
- * silently disabling it for the rest of the streaming session). It's
- * disarmed the instant `phase` becomes anything else, including a
- * host-driven reassignment away from `'streaming'` — so a stale timer can
- * never fire a stall transition after the host has already moved on. If it
- * ever fires, `phase` becomes `'stalled'` and `lyra-stall` is dispatched.
- *
- * `phase` remains a fully public, directly settable property at all times —
- * a host can assign `'stalled'` (or any other phase) itself as a manual
- * override, and this component never fights that assignment. `lyra-stall`/
- * `lyra-recover` fire on *any* transition into/out of `'stalled'`
- * respectively, whether timer-driven or host-driven, and never for a
- * reassignment to the same value (Lit's default `hasChanged` already skips a
- * no-op set, same as every other reflected `@property` in this library).
- * Like `<lyra-chat-message>`'s `status`, whatever phase this element happens
- * to *mount* with is never itself treated as an eventful transition — only a
- * later change fires an event or an announcement.
- *
- * Accessibility: phase transitions into/out of `'stalled'` are announced
- * through an internal `<lyra-live-region>` (see that component for the
- * throttled/coalesced-announcement machinery this composes) rather than a
- * hand-rolled `aria-live` region. `recordActivity()` itself never announces
- * anything, no matter how often the host calls it — only the *transition*
- * announces, exactly once per transition, which is the entire point of
- * routing through the throttled announcer instead of writing to a live
- * region on every call. Entering `'stalled'` announces with `mode="assertive"`
- * (a stall can need the user's attention, e.g. before they give up and
- * navigate away); leaving `'stalled'` always announces with `mode="polite"`
- * (good news doesn't need to interrupt), but the *wording* depends on where
- * it lands: `"Connection restored."` only when the destination is
- * `'streaming'` (a genuine recovery), or a neutral `"No longer stalled."`
- * when the destination is `'idle'`/`'connecting'` instead — that's the host
- * giving up on the stream, not the stream recovering, and a screen-reader
- * user must never be told the opposite of what a sighted user sees on
- * screen. The decorative indicator dot is `aria-hidden` — it's a
- * color/motion cue only, never the sole carrier of state.
- *
- * Visual: `'stalled'` is styled as a warning, not a danger — a stall is
- * usually recoverable (the stream may resume on its own, or the host's own
- * retry logic may kick in), so treating it as an actionable warning rather
- * than a hard failure keeps the tone proportionate. A host that wants to
- * escalate to danger styling after N stalls can scope its own CSS off
- * `[phase="stalled"]`, or simply stop rendering this component and show its
- * own danger-styled error state instead.
- *
- * @customElement lyra-stream-status
- * @slot - Custom copy shown only while `phase="stalled"` (e.g. "Taking longer than usual…"). A sensible built-in default is used when nothing is slotted.
- * @slot actions - A stop/retry button row. Always present in the template regardless of `phase` — visibility is driven purely by whether anything is slotted, not by `phase`; what to put here, and when, is entirely the host's call.
- * @event lyra-stall - Fired whenever `phase` transitions into `'stalled'` from anything else (timer-driven, or a direct host assignment).
- * @event lyra-recover - Fired whenever `phase` transitions out of `'stalled'` to anything else (via `recordActivity()`, or a direct host assignment) — fired unconditionally regardless of destination phase, even though the accompanying announcement's wording varies (see the class doc's "Accessibility" section).
- * @csspart base - The root layout container.
- * @csspart indicator - The decorative (`aria-hidden`) status dot.
- * @csspart message - Wrapper around the default slot; only rendered while `phase="stalled"`.
- * @csspart actions - Wrapper around the `actions` slot.
- */
-export class LyraStreamStatus extends LyraElement {
-    constructor() {
-        super(...arguments);
-        /** Current connection phase. Settable directly by the host at any time —
-         *  see the class doc for how that interacts with the internal stall timer. */
-        this.phase = 'idle';
-        /** How long `phase` may stay `'streaming'` with no `recordActivity()` call
-         *  before this component declares it stalled. */
-        this.stallThresholdMs = 10000;
-        this.hasActionsSlot = false;
-        // Seeded from light-DOM childNodes in willUpdate() (mirrors hasActionsSlot
-        // above), then kept current via onMessageSlotChange() -- see
-        // isRealMessageNode()'s doc comment for why native <slot> fallback content
-        // can't be relied on for the default stalled-message text.
-        this.hasMessageContent = false;
-        this.onActionsSlotChange = (e) => {
-            this.hasActionsSlot = e.target.assignedElements({ flatten: true }).length > 0;
-        };
-        this.onMessageSlotChange = (e) => {
-            this.hasMessageContent = e.target.assignedNodes({ flatten: true }).some(isRealMessageNode);
-        };
-    }
-    static { this.styles = [LyraElement.styles, styles]; }
-    willUpdate() {
-        if (!this.hasUpdated) {
-            this.hasActionsSlot = this.hasSlotted('actions');
-            this.hasMessageContent = Array.from(this.childNodes).some(isRealMessageNode);
-        }
-    }
-    // `changed.get('phase')` is `undefined` on the very first update, for the
-    // same reason documented on lyra-chat-message's identical `updated()`
-    // guard: Lit only records the *first* old value seen since the last
-    // completed update, and the constructor's field-initializer assignment is
-    // that first change, from the truly-unset internal slot. That naturally
-    // skips firing an event/announcement for whatever phase this element
-    // happens to mount with, while still arming the stall timer below if it
-    // mounts already `'streaming'`.
-    //
-    // The `else if` below only matters while `phase` itself didn't also change
-    // in this same update -- if it did, onPhaseChanged() above already
-    // (re)armed the timer with the current `stallThresholdMs`, so re-arming it
-    // again here would just be redundant, not wrong, but the `else` skips that
-    // double work.
-    updated(changed) {
-        if (changed.has('phase')) {
-            this.onPhaseChanged(changed.get('phase'));
-        }
-        else if (changed.has('stallThresholdMs') && this.phase === 'streaming') {
-            // Unlike `phase` itself, `stallThresholdMs` has no dedicated handler --
-            // the already-armed timer was scheduled against the *old* value and
-            // keeps counting down against it otherwise, so a shortened (or
-            // lengthened) threshold would silently have no effect until the next
-            // recordActivity() call or phase transition happened to re-arm it.
-            this.armStallTimer();
-        }
-    }
-    connectedCallback() {
-        super.connectedCallback();
-        // A disconnect always disarms the timer (see disconnectedCallback()
-        // below), but reparenting this element elsewhere in the page while still
-        // `'streaming'` fires disconnectedCallback then connectedCallback with
-        // `phase` unchanged -- no `updated()` cycle runs in between, so nothing
-        // else would ever re-arm it. Without this, a reparent mid-stream would
-        // permanently disable stall detection for the rest of that streaming
-        // session.
-        if (this.phase === 'streaming')
-            this.armStallTimer();
-    }
-    disconnectedCallback() {
-        super.disconnectedCallback();
-        this.disarmStallTimer();
-    }
-    /**
-     * Call on every semantic (non-heartbeat) frame received while streaming.
-     * - While `phase === 'streaming'`: (re)arms the stall timer, pushing the
-     *   stall deadline `stall-threshold-ms` further out.
-     * - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'`
-     *   again, `lyra-recover` fires, and the stall timer is armed fresh (same
-     *   as the bullet above), all via the same `updated()` transition handling
-     *   a direct host assignment would also go through.
-     * - While `phase` is `'idle'` or `'connecting'`: a no-op. A host may call
-     *   this defensively before formally flipping to `'streaming'`; it must
-     *   never throw or start a timer early.
-     */
-    recordActivity() {
-        if (this.phase === 'streaming') {
-            this.armStallTimer();
-        }
-        else if (this.phase === 'stalled') {
-            this.phase = 'streaming';
-        }
-    }
-    onPhaseChanged(previous) {
-        if (this.phase === 'streaming') {
-            this.armStallTimer();
-        }
-        else {
-            this.disarmStallTimer();
-        }
-        if (previous === undefined)
-            return;
-        if (this.phase === 'stalled' && previous !== 'stalled') {
-            this.emit('lyra-stall');
-            this.announceTransition('assertive', STALL_ANNOUNCEMENT);
-        }
-        else if (previous === 'stalled' && this.phase !== 'stalled') {
-            // `lyra-recover` fires unconditionally -- a host may still want the
-            // event for any exit from 'stalled' -- but the *announced text* must
-            // not claim the connection was "restored" when the destination is
-            // 'idle'/'connecting': that's the host abandoning the stream, not it
-            // recovering, and telling a screen-reader user otherwise would be the
-            // opposite of what a sighted user sees on screen.
-            this.emit('lyra-recover');
-            const text = this.phase === 'streaming' ? RECOVER_ANNOUNCEMENT : STALL_CLEARED_ANNOUNCEMENT;
-            this.announceTransition('polite', text);
-        }
-    }
-    armStallTimer() {
-        this.disarmStallTimer();
-        const threshold = this.stallThresholdMs;
-        if (!Number.isFinite(threshold) || threshold <= 0)
-            return;
-        this.stallTimer = setTimeout(() => {
-            this.stallTimer = undefined;
-            this.phase = 'stalled';
-        }, threshold);
-    }
-    disarmStallTimer() {
-        if (this.stallTimer !== undefined) {
-            clearTimeout(this.stallTimer);
-            this.stallTimer = undefined;
-        }
-    }
-    announceTransition(mode, text) {
-        const region = this.liveRegion;
-        if (!region)
-            return;
-        region.mode = mode;
-        region.announce(text, { force: true });
-    }
-    hasSlotted(name) {
-        return Array.from(this.children).some((el) => el.getAttribute('slot') === name);
-    }
-    render() {
-        return html `
-      <div part="base">
-        <span part="indicator" aria-hidden="true"></span>
-        ${this.phase === 'stalled'
-            ? html `<div part="message">
-              <slot @slotchange=${this.onMessageSlotChange}></slot>${this.hasMessageContent
-                ? nothing
-                : DEFAULT_STALL_MESSAGE}
-            </div>`
-            : nothing}
-        <div part="actions" ?hidden=${!this.hasActionsSlot}>
-          <slot name="actions" @slotchange=${this.onActionsSlotChange}></slot>
-        </div>
-        <lyra-live-region></lyra-live-region>
-      </div>
-    `;
-    }
-}
-__decorate([
-    property({ reflect: true })
-], LyraStreamStatus.prototype, "phase", void 0);
-__decorate([
-    property({ type: Number, attribute: 'stall-threshold-ms' })
-], LyraStreamStatus.prototype, "stallThresholdMs", void 0);
-__decorate([
-    state()
-], LyraStreamStatus.prototype, "hasActionsSlot", void 0);
-__decorate([
-    state()
-], LyraStreamStatus.prototype, "hasMessageContent", void 0);
-__decorate([
-    query('lyra-live-region')
-], LyraStreamStatus.prototype, "liveRegion", void 0);
+import "../live-region/live-region.js";
 defineElement('stream-status', LyraStreamStatus);
+//# sourceMappingURL=stream-status.js.map

package/dist/components/stream-status/stream-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-status.js","sourceRoot":"","sources":["../../../src/components/stream-status/stream-status.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,+BAA+B,CAAC;AACvC,aAAa,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC"}