import{type TemplateResult,type PropertyValues}from'lit';import{LyraElement}from'../../../internal/lyra-element.js';import'../../utility/live-region/live-region.class.js';import type{LyraStreamPhase}from'../../../internal/stream-phase.js';export type StreamConnectionState=Exclude;export interface LyraStreamStatusEventMap{'lr-stall':CustomEvent;'lr-recover':CustomEvent;} /** * `` — a compact status indicator for a single streaming * connection (SSE, WebSocket, long-poll, …), with built-in heartbeat-aware * stall detection. * * The host owns `connectionState` 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 the effective readonly `phase` is `streaming`. * It's (re)armed whenever `connectionState` enters `streaming` or * `recordActivity()` recovers 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 ``'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 `connectionState` 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 `lr-stall` is dispatched. * * `phase` is a readonly effective value: it mirrors `connectionState` unless inactivity has * stalled a streaming connection. A host that detects a semantic stall through another signal * calls `markStalled()` instead of writing component-owned state. `recordActivity()` clears that * override and resumes the timer. `lr-stall`/`lr-recover` fire exactly once for actual effective * transitions into/out of `stalled`. * Like ``'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 `` (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 after N stalls can listen for `lr-stall` and show its own danger-styled error state. * * @customElement lr-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 by whether anything is slotted. * @event lr-stall - Fired whenever the effective phase transitions into `stalled`. * @event lr-recover - Fired whenever the effective phase transitions out of `stalled`. * @csspart base - The root layout container. * @csspart indicator - The decorative (`aria-hidden`) status dot. * @csspart phase - Persistent localized phase text. * @csspart message - Wrapper around the default slot; only rendered while readonly `phase` is `stalled`. * @csspart actions - Wrapper around the `actions` slot. * @cssprop [--lr-stream-status-dot-color=var(--lr-color-text-quiet)] - `indicator` dot color. * Its private default changes with reflected `connection-state` and the component-owned * `data-stalled` state: `var(--lr-color-brand)` for * `connecting`/`streaming`, `var(--lr-color-warning)` for `stalled`. Set it on the element or * any ancestor; an element value wins. * @cssprop [--lr-stream-status-dot-opacity=0.35] - `indicator` dot opacity. Its private default * changes with those same host states: `0.6` for `connecting`, `1` for `streaming` and `stalled`. * Set it on the element or any ancestor; an element value wins. * @cssprop [--lr-stream-status-stalled-bg=var(--lr-color-warning-quiet)] - `base` row background * while `data-stalled` is present. * @cssprop [--lr-stream-status-stalled-border-color=var(--lr-color-warning)] - `base` row border * color while `data-stalled` is present. * @cssprop [--lr-stream-status-message-color=var(--lr-color-warning)] - `phase` and `message` text * color while `data-stalled` is present. Decoupled from * `--lr-stream-status-stalled-border-color` even though both fall back to the same shared token * today. * @status stable * @since 4.0.0 */ export declare class LyraStreamStatus extends LyraElement{static styles:import("lit").CSSResultGroup[];private _connectionState; /** Host-owned transport state. Invalid attribute and JavaScript writes normalize to `idle`. */ get connectionState():StreamConnectionState;set connectionState(next:StreamConnectionState); /** Readonly effective status, including the component-owned stalled override. */ get phase():LyraStreamPhase; /** How long `phase` may stay `'streaming'` with no `recordActivity()` call * before this component declares it stalled. */ stallThresholdMs:number;private _stalled;private stallTimer?;private stallTimerOwner?;private stallTimerDocument?;private stallTimerGeneration;private hasActionsSlot;private hasMessageContent;private liveRegion?;private lastRenderedPhase?;private phaseAtDisconnect?;constructor();protected willUpdate(changed:PropertyValues):void;protected updated(changed:PropertyValues):void;connectedCallback():void;disconnectedCallback():void;adoptedCallback():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, `lr-recover` fires, and the stall timer is armed fresh (same * as the bullet above), all via the same effective transition handler. * - 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; /** Installs the component-owned stalled override for an active stream. No-op unless the * host-owned `connectionState` is `streaming`, or when already stalled. */ markStalled():void;private onPhaseChanged;private armStallTimer;private disarmStallTimer;private announceTransition;private hasSlotted;private onActionsSlotChange;private onMessageSlotChange;private get phaseText();render():TemplateResult;}declare global{interface HTMLElementTagNameMap{'lr-stream-status':LyraStreamStatus;}}