@aceshooting/lyra-ui 2.1.0 → 2.3.0

package/dist/components/stepper/stepper.styles.js

@@ -0,0 +1,67 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+  }
+  [part='base'] {
+    display: flex;
+    gap: var(--lyra-space-m);
+    overflow-x: auto;
+  }
+  :host([orientation='vertical']) [part='base'] {
+    flex-direction: column;
+    overflow-x: visible;
+  }
+  [part='step'] {
+    display: flex;
+    align-items: center;
+    gap: var(--lyra-space-xs);
+    flex: 0 0 auto;
+    border: none;
+    background: transparent;
+    color: var(--lyra-color-text-quiet);
+    font: inherit;
+    cursor: pointer;
+    padding: var(--lyra-space-2xs);
+    border-radius: var(--lyra-radius);
+  }
+  [part='step'][aria-disabled='true'] {
+    opacity: var(--lyra-opacity-disabled);
+    cursor: not-allowed;
+  }
+  [part='step']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    outline-offset: var(--lyra-focus-ring-offset);
+  }
+  [part='step'][data-state='current'] {
+    color: var(--lyra-color-text);
+    font-weight: var(--lyra-font-weight-semibold);
+  }
+  [part='step'][data-state='error'] {
+    color: var(--lyra-color-danger);
+  }
+  [part='step-index'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--lyra-size-1-5rem);
+    block-size: var(--lyra-size-1-5rem);
+    border-radius: var(--lyra-radius-pill);
+    background: var(--lyra-color-border);
+    color: var(--lyra-color-text);
+    font-size: var(--lyra-font-size-xs);
+    flex: 0 0 auto;
+  }
+  [part='step'][data-state='current'] [part='step-index'] {
+    background: var(--lyra-color-brand);
+    color: var(--lyra-color-surface);
+  }
+  [part='step-check'] {
+    color: var(--lyra-color-success);
+    flex: 0 0 auto;
+  }
+  [part='step-label'] {
+    white-space: nowrap;
+  }
+`;
+//# sourceMappingURL=stepper.styles.js.map

package/dist/components/stepper/stepper.styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepper.styles.js","sourceRoot":"","sources":["../../../src/components/stepper/stepper.styles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE1B,MAAM,CAAC,MAAM,MAAM,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgExB,CAAC"}

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

@@ -0,0 +1,131 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../live-region/live-region.class.js';
+export type StreamStatusPhase = 'idle' | 'connecting' | 'streaming' | 'stalled';
+export interface LyraStreamStatusEventMap {
+    'lyra-stall': CustomEvent<undefined>;
+    'lyra-recover': CustomEvent<undefined>;
+}
+/**
+ * `<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<LyraStreamStatusEventMap> {
+    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;
+    }
+}
+//# sourceMappingURL=stream-status.class.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream-status.class.d.ts","sourceRoot":"","sources":["../../../src/components/stream-status/stream-status.class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE9E,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7D,OAAO,qCAAqC,CAAC;AAG7C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC;AA2BhF,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACrC,cAAc,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;CACxC;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,qBAAa,gBAAiB,SAAQ,WAAW,CAAC,wBAAwB,CAAC;IACzE,MAAM,CAAC,MAAM,iCAAgC;IAE7C;kFAC8E;IACjD,KAAK,EAAE,iBAAiB,CAAU;IAE/D;qDACiD;IACY,gBAAgB,SAAS;IAGtF,OAAO,CAAC,UAAU,CAAC,CAAgC;IAE1C,OAAO,CAAC,cAAc,CAAS;IAM/B,OAAO,CAAC,iBAAiB,CAAS;IAEhB,OAAO,CAAC,UAAU,CAAC,CAAiB;IAE/D,SAAS,CAAC,UAAU,IAAI,IAAI,CAK3B;IAgBD,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAW/C;IAED,iBAAiB,IAAI,IAAI,CAUxB;IAED,oBAAoB,IAAI,IAAI,CAG3B;IAED;;;;;;;;;;;OAWG;IACH,cAAc,IAAI,IAAI,CAMrB;IAED,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,mBAAmB,CAEzB;IAEF,OAAO,CAAC,mBAAmB,CAEzB;IAEF,MAAM,IAAI,cAAc,CAiBvB;CACF;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,oBAAoB,EAAE,gBAAgB,CAAC;KACxC;CACF"}

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

@@ -0,0 +1,291 @@
+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;
+}
+/**
+ * `<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);
+//# 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":";;;;;;AAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAA4C,MAAM,KAAK,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7D,OAAO,qCAAqC,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAInD,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAC1D,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AACjD,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AACpD,6EAA6E;AAC7E,gEAAgE;AAChE,6EAA6E;AAC7E,uCAAuC;AACvC,MAAM,0BAA0B,GAAG,oBAAoB,CAAC;AAExD,yEAAyE;AACzE,sEAAsE;AACtE,mEAAmE;AACnE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,4EAA4E;AAC5E,8EAA8E;AAC9E,2EAA2E;AAC3E,iDAAiD;AACjD,SAAS,iBAAiB,CAAC,CAAO;IAChC,OAAO,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,YAAY;QACrC,CAAC,CAAC,CAAE,CAAa,CAAC,YAAY,CAAC,MAAM,CAAC;QACtC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9C,CAAC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AACH,MAAM,OAAO,gBAAiB,SAAQ,WAAqC;IAA3E;;QAGE;sFAC8E;QACjD,UAAK,GAAsB,MAAM,CAAC;QAE/D;yDACiD;QACY,qBAAgB,GAAG,KAAK,CAAC;QAKrE,mBAAc,GAAG,KAAK,CAAC;QAExC,2EAA2E;QAC3E,6DAA6D;QAC7D,2EAA2E;QAC3E,2DAA2D;QAC1C,sBAAiB,GAAG,KAAK,CAAC;QAgInC,wBAAmB,GAAG,CAAC,CAAQ,EAAQ,EAAE;YAC/C,IAAI,CAAC,cAAc,GAAI,CAAC,CAAC,MAA0B,CAAC,gBAAgB,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QACrG,CAAC,CAAC;QAEM,wBAAmB,GAAG,CAAC,CAAQ,EAAQ,EAAE;YAC/C,IAAI,CAAC,iBAAiB,GAAI,CAAC,CAAC,MAA0B,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAClH,CAAC,CAAC;IAoBJ,CAAC;aA7KQ,WAAM,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,AAA/B,CAAgC;IAuBnC,UAAU;QAClB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YACjD,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,oEAAoE;IACpE,0EAA0E;IAC1E,wEAAwE;IACxE,qEAAqE;IACrE,wEAAwE;IACxE,gCAAgC;IAChC,EAAE;IACF,2EAA2E;IAC3E,mEAAmE;IACnE,2EAA2E;IAC3E,2EAA2E;IAC3E,eAAe;IACL,OAAO,CAAC,OAAuB;QACvC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAkC,CAAC,CAAC;QAC7E,CAAC;aAAM,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YACzE,wEAAwE;YACxE,oEAAoE;YACpE,+DAA+D;YAC/D,qEAAqE;YACrE,mEAAmE;YACnE,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED,iBAAiB;QACf,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC1B,oEAAoE;QACpE,yEAAyE;QACzE,uEAAuE;QACvE,wEAAwE;QACxE,uEAAuE;QACvE,qEAAqE;QACrE,WAAW;QACX,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW;YAAE,IAAI,CAAC,aAAa,EAAE,CAAC;IACvD,CAAC;IAED,oBAAoB;QAClB,KAAK,CAAC,oBAAoB,EAAE,CAAC;QAC7B,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,cAAc;QACZ,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC;aAAM,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;QAC3B,CAAC;IACH,CAAC;IAEO,cAAc,CAAC,QAAuC;QAC5D,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;QAED,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO;QAEnC,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACvD,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACxB,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;QAC3D,CAAC;aAAM,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9D,oEAAoE;YACpE,qEAAqE;YACrE,kEAAkE;YAClE,qEAAqE;YACrE,sEAAsE;YACtE,kDAAkD;YAClD,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,0BAA0B,CAAC;YAC5F,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC;YAAE,OAAO;QAC1D,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;YAC5B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,CAAC,EAAE,SAAS,CAAC,CAAC;IAChB,CAAC;IAEO,gBAAgB;QACtB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC9B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC9B,CAAC;IACH,CAAC;IAEO,kBAAkB,CAAC,IAA4B,EAAE,IAAY;QACnE,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/B,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAEO,UAAU,CAAC,IAAY;QAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;IAClF,CAAC;IAUD,MAAM;QACJ,OAAO,IAAI,CAAA;;;UAGL,IAAI,CAAC,KAAK,KAAK,SAAS;YACxB,CAAC,CAAC,IAAI,CAAA;kCACkB,IAAI,CAAC,mBAAmB,WAAW,IAAI,CAAC,iBAAiB;gBAC3E,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,qBAAqB;mBACpB;YACT,CAAC,CAAC,OAAO;sCACmB,CAAC,IAAI,CAAC,cAAc;6CACb,IAAI,CAAC,mBAAmB;;;;KAIhE,CAAC;IACJ,CAAC;CACF;AAzK8B;IAA5B,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;+CAAmC;AAIF;IAA5D,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC;0DAA0B;AAKrE;IAAhB,KAAK,EAAE;wDAAgC;AAMvB;IAAhB,KAAK,EAAE;2DAAmC;AAER;IAAlC,KAAK,CAAC,kBAAkB,CAAC;oDAAqC"}

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"}