@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/kbd/kbd.d.ts

@@ -0,0 +1,77 @@
+import { type TemplateResult } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/** A single rendered key token: the compact glyph shown in the key cap, and
+ *  the spelled-out word used in the chip's `aria-label` (glyphs like `⌘`/
+ *  `⇧`/`⌥` are not reliably announced across every screen reader/platform
+ *  combination, so the accessible name always spells them out in full). */
+export interface KbdKeyLabel {
+    visual: string;
+    word: string;
+}
+/**
+ * Resolves one `+`-separated token of a `keys` string to its rendered glyph
+ * and spelled-out word, given whether the shortcut is being shown on macOS.
+ *
+ * Exported as a pure function (parameterized on `isMac` rather than reading
+ * the module-scope platform constant directly) so both the macOS and
+ * non-macOS branches are directly unit-testable without having to spoof
+ * `navigator` in a browser test environment that only ever runs as one
+ * platform.
+ */
+export declare function shortcutTokenLabel(rawToken: string, isMac: boolean): KbdKeyLabel;
+/** Splits a `keys` string (e.g. `'mod+shift+p'`) into its resolved token
+ *  labels, dropping empty segments from stray/leading/trailing `+`s. */
+export declare function parseShortcut(keys: string, isMac: boolean): KbdKeyLabel[];
+/**
+ * `<lyra-kbd>` — a small chip representing a keyboard shortcut, rendering
+ * the platform-appropriate glyph for cross-platform modifier keys (⌘ on
+ * macOS, "Ctrl" elsewhere) from a single platform-neutral `keys` string.
+ *
+ * `keys` is a `+`-separated sequence of tokens, e.g. `"mod+k"` or
+ * `"mod+shift+p"`. Recognized modifier tokens: `mod` (the platform-neutral
+ * primary modifier — ⌘ on macOS, "Ctrl" elsewhere), `alt` (⌥ / "Alt"),
+ * `shift` (⇧ on every platform), and `ctrl` (always the literal Control
+ * key, distinct from `mod`, for a shortcut that's specifically Ctrl even on
+ * macOS). Any other token renders as typed, except a bare single
+ * letter/digit which is upper-cased, with a small built-in map of friendly
+ * labels for common named keys (`enter` → `↵`, `esc` → "Esc", the four
+ * arrow keys → arrow glyphs, plus `tab`/`space`/`backspace`/`delete`/`home`/
+ * `end`/`pageup`/`pagedown`/`plus`/`minus`). `enter` renders as its `↵`
+ * glyph (not the word "Enter") to match the other single-glyph modifier/
+ * arrow keys visually — its spelled-out word form still appears in the
+ * computed `aria-label`.
+ *
+ * Each token renders as its own key cap (`part="key"`); consecutive caps
+ * are joined by a small "+" separator between them, matching how most
+ * cross-platform shortcut documentation (including on macOS, despite the
+ * OS's own native shortcut hints usually running the glyphs together with
+ * no separator) reads unambiguously regardless of how many/which glyphs are
+ * involved.
+ *
+ * The default slot is not used for the normal glyph rendering above — it's
+ * an escape hatch for fully custom content (e.g. an icon instead of a text
+ * glyph) that, when non-empty, replaces the `keys`-driven rendering
+ * entirely and stops this component from asserting its own `aria-label`,
+ * leaving the slotted content to carry its own accessible name.
+ *
+ * @customElement lyra-kbd
+ * @slot - Optional override for fully custom key-cap content, replacing the
+ * `keys`-driven rendering. Leave empty to use `keys`.
+ * @csspart base - The chip's root element.
+ * @csspart key - Each rendered key cap (one per token in `keys`).
+ */
+export declare class LyraKbd extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** A `+`-separated shortcut, e.g. `'mod+k'`. See the class doc for the
+     *  full token grammar. */
+    keys: string;
+    private hasCustomContent;
+    protected willUpdate(): void;
+    private onSlotChange;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-kbd': LyraKbd;
+    }
+}

package/dist/components/kbd/kbd.js

@@ -0,0 +1,231 @@
+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 } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { styles } from './kbd.styles.js';
+// A deliberately small map — just the modifier-adjacent/navigation keys
+// common enough in real shortcuts to be worth a friendly glyph. Anything not
+// listed here (e.g. 'f1', 'k', a punctuation key) falls through to the
+// generic "render as typed, upper-case single letters" rule in
+// `shortcutTokenLabel` below, per this component's spec.
+//
+// 'plus'/'minus' exist specifically so a shortcut that includes a literal
+// "+" or "-" key (e.g. the classic zoom-in shortcut) has a way to say so:
+// the '+'-separated `keys` grammar can't itself carry a literal "+" token
+// (it's the delimiter), so callers spell it as the word instead.
+const NAMED_KEY_LABELS = {
+    enter: { visual: '↵', word: 'Enter' },
+    esc: { visual: 'Esc', word: 'Escape' },
+    escape: { visual: 'Esc', word: 'Escape' },
+    tab: { visual: 'Tab', word: 'Tab' },
+    space: { visual: 'Space', word: 'Space' },
+    backspace: { visual: '⌫', word: 'Backspace' },
+    delete: { visual: 'Del', word: 'Delete' },
+    home: { visual: 'Home', word: 'Home' },
+    end: { visual: 'End', word: 'End' },
+    pageup: { visual: 'PgUp', word: 'Page Up' },
+    pagedown: { visual: 'PgDn', word: 'Page Down' },
+    arrowup: { visual: '↑', word: 'Arrow Up' },
+    arrowdown: { visual: '↓', word: 'Arrow Down' },
+    arrowleft: { visual: '←', word: 'Arrow Left' },
+    arrowright: { visual: '→', word: 'Arrow Right' },
+    plus: { visual: '+', word: 'Plus' },
+    minus: { visual: '−', word: 'Minus' },
+};
+/**
+ * Resolves one `+`-separated token of a `keys` string to its rendered glyph
+ * and spelled-out word, given whether the shortcut is being shown on macOS.
+ *
+ * Exported as a pure function (parameterized on `isMac` rather than reading
+ * the module-scope platform constant directly) so both the macOS and
+ * non-macOS branches are directly unit-testable without having to spoof
+ * `navigator` in a browser test environment that only ever runs as one
+ * platform.
+ */
+export function shortcutTokenLabel(rawToken, isMac) {
+    const token = rawToken.trim();
+    const lower = token.toLowerCase();
+    // 'mod' is the platform-neutral primary modifier: Command on macOS,
+    // Control everywhere else. 'ctrl' is deliberately distinct — it always
+    // means the literal Control key, even on macOS, for shortcuts that are
+    // specifically Ctrl-based (e.g. terminal Ctrl+C) rather than
+    // platform-adapted.
+    if (lower === 'mod')
+        return isMac ? { visual: '⌘', word: 'Command' } : { visual: 'Ctrl', word: 'Control' };
+    if (lower === 'ctrl' || lower === 'control')
+        return { visual: 'Ctrl', word: 'Control' };
+    if (lower === 'alt')
+        return isMac ? { visual: '⌥', word: 'Option' } : { visual: 'Alt', word: 'Alt' };
+    if (lower === 'shift')
+        return { visual: '⇧', word: 'Shift' };
+    const named = NAMED_KEY_LABELS[lower];
+    if (named)
+        return named;
+    // Anything else renders as typed (preserving the caller's own casing),
+    // except a bare single letter/digit, which is upper-cased for a
+    // consistent key-cap look ('k' and 'K' both render 'K').
+    if (token.length === 1) {
+        const upper = token.toUpperCase();
+        return { visual: upper, word: upper };
+    }
+    return { visual: token, word: token };
+}
+/** Splits a `keys` string (e.g. `'mod+shift+p'`) into its resolved token
+ *  labels, dropping empty segments from stray/leading/trailing `+`s. */
+export function parseShortcut(keys, isMac) {
+    return keys
+        .split('+')
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0)
+        .map((t) => shortcutTokenLabel(t, isMac));
+}
+/**
+ * Detects macOS to decide whether `mod`/`alt` render their Mac glyphs (⌘/⌥)
+ * or their generic-platform text (Ctrl/Alt). Prefers the modern
+ * `navigator.userAgentData` (Client Hints) API when the browser exposes it,
+ * falling back through `navigator.platform` and finally a `navigator.userAgent`
+ * substring check — all three are deprecated/non-standard to varying
+ * degrees (`userAgentData` is Chromium-only so far; `platform` is
+ * long-deprecated; `userAgent` sniffing is a last resort) but remain, in
+ * combination, the practical cross-browser way to answer "is this macOS"
+ * today with no dependency.
+ */
+function detectIsMac() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const uaData = navigator.userAgentData;
+    if (uaData?.platform)
+        return uaData.platform.toLowerCase().includes('mac');
+    if (navigator.platform)
+        return /mac/i.test(navigator.platform);
+    return /mac/i.test(navigator.userAgent ?? '');
+}
+// Computed once at module scope, not per-instance/per-render — a page's
+// platform never changes mid-session, so there is nothing to gain (and a
+// little cost, however small) from re-detecting it on every <lyra-kbd>
+// instance or every re-render.
+const IS_MAC = detectIsMac();
+// The one "is there real content" predicate shared by both the initial
+// synchronous seed (willUpdate, reading light-DOM childNodes) and the
+// runtime slotchange handler (reading assignedNodes) — using two different
+// predicates for the same question let them disagree: a text-only check
+// would seed correctly for whitespace-only text but (wrongly) treat a
+// content-less icon element as empty, and a node-count-only check would
+// treat *any* assigned node — including a whitespace-only text node — as
+// real content. Counting every element node as real content (regardless of
+// its own text) while requiring non-whitespace text from text nodes gets
+// both cases right in one place.
+const hasRealContent = (nodes) => Array.from(nodes).some((n) => n.nodeType === Node.ELEMENT_NODE || (n.textContent ?? '').trim().length > 0);
+/**
+ * `<lyra-kbd>` — a small chip representing a keyboard shortcut, rendering
+ * the platform-appropriate glyph for cross-platform modifier keys (⌘ on
+ * macOS, "Ctrl" elsewhere) from a single platform-neutral `keys` string.
+ *
+ * `keys` is a `+`-separated sequence of tokens, e.g. `"mod+k"` or
+ * `"mod+shift+p"`. Recognized modifier tokens: `mod` (the platform-neutral
+ * primary modifier — ⌘ on macOS, "Ctrl" elsewhere), `alt` (⌥ / "Alt"),
+ * `shift` (⇧ on every platform), and `ctrl` (always the literal Control
+ * key, distinct from `mod`, for a shortcut that's specifically Ctrl even on
+ * macOS). Any other token renders as typed, except a bare single
+ * letter/digit which is upper-cased, with a small built-in map of friendly
+ * labels for common named keys (`enter` → `↵`, `esc` → "Esc", the four
+ * arrow keys → arrow glyphs, plus `tab`/`space`/`backspace`/`delete`/`home`/
+ * `end`/`pageup`/`pagedown`/`plus`/`minus`). `enter` renders as its `↵`
+ * glyph (not the word "Enter") to match the other single-glyph modifier/
+ * arrow keys visually — its spelled-out word form still appears in the
+ * computed `aria-label`.
+ *
+ * Each token renders as its own key cap (`part="key"`); consecutive caps
+ * are joined by a small "+" separator between them, matching how most
+ * cross-platform shortcut documentation (including on macOS, despite the
+ * OS's own native shortcut hints usually running the glyphs together with
+ * no separator) reads unambiguously regardless of how many/which glyphs are
+ * involved.
+ *
+ * The default slot is not used for the normal glyph rendering above — it's
+ * an escape hatch for fully custom content (e.g. an icon instead of a text
+ * glyph) that, when non-empty, replaces the `keys`-driven rendering
+ * entirely and stops this component from asserting its own `aria-label`,
+ * leaving the slotted content to carry its own accessible name.
+ *
+ * @customElement lyra-kbd
+ * @slot - Optional override for fully custom key-cap content, replacing the
+ * `keys`-driven rendering. Leave empty to use `keys`.
+ * @csspart base - The chip's root element.
+ * @csspart key - Each rendered key cap (one per token in `keys`).
+ */
+export class LyraKbd extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** A `+`-separated shortcut, e.g. `'mod+k'`. See the class doc for the
+         *  full token grammar. */
+        this.keys = '';
+        // Real (non-whitespace) light-DOM content overrides the keys-driven
+        // rendering below — same "seed synchronously, refine on slotchange"
+        // pattern as lyra-checkbox's hasLabelSlot/lyra-citation-badge's
+        // hasPreviewSlot, so a declaratively-slotted override doesn't flash the
+        // keys rendering for one frame before the first slotchange event.
+        this.hasCustomContent = false;
+        this.onSlotChange = (e) => {
+            this.hasCustomContent = hasRealContent(e.target.assignedNodes({ flatten: true }));
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate() {
+        if (!this.hasUpdated) {
+            this.hasCustomContent = hasRealContent(this.childNodes);
+        }
+    }
+    render() {
+        const explicitLabel = this.getAttribute('aria-label');
+        if (this.hasCustomContent) {
+            return html `
+        <span part="base" aria-label=${explicitLabel || nothing}>
+          <slot @slotchange=${this.onSlotChange}></slot>
+        </span>
+      `;
+        }
+        const tokens = parseShortcut(this.keys, IS_MAC);
+        // role="img" treats the chip as one opaque unit (matching
+        // lyra-context-meter's/lyra-chart's canvas usage of the same pattern):
+        // the individual glyphs and "+" separators aren't real words, so
+        // exposing them as separate accessible-tree text would read worse than
+        // the single spelled-out aria-label below. An empty `keys` (and no
+        // explicit override) renders nothing visible, so it's marked
+        // aria-hidden instead of exposed as a nameless image.
+        //
+        // role/aria-hidden are both derived from this same `ariaLabel` value
+        // (rather than each independently re-deriving "is there a label" from
+        // tokens.length/explicitLabel) so role="img" can never be absent while
+        // aria-label is present — that combination is an aria-prohibited-attr
+        // violation (a nameless-but-labeled, role-less element).
+        const ariaLabel = explicitLabel || tokens.map((t) => t.word).join('+');
+        return html `
+      <span
+        part="base"
+        role=${ariaLabel ? 'img' : nothing}
+        aria-hidden=${ariaLabel ? nothing : 'true'}
+        aria-label=${ariaLabel || nothing}
+      >
+        ${tokens.map((t, i) => html `
+            ${i > 0 ? html `<span class="sep" aria-hidden="true">+</span>` : nothing}
+            <span part="key">${t.visual}</span>
+          `)}
+        <slot @slotchange=${this.onSlotChange} hidden></slot>
+      </span>
+    `;
+    }
+}
+__decorate([
+    property()
+], LyraKbd.prototype, "keys", void 0);
+__decorate([
+    state()
+], LyraKbd.prototype, "hasCustomContent", void 0);
+defineElement('kbd', LyraKbd);

package/dist/components/kbd/kbd.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/kbd/kbd.styles.js

@@ -0,0 +1,52 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: inline-flex;
+    max-inline-size: 100%;
+    vertical-align: middle;
+  }
+
+  [part='base'] {
+    display: inline-flex;
+    align-items: center;
+    flex-wrap: wrap;
+    /* The body font, not a monospace stack — unlike lyra-code-block's own
+       local --lyra-code-block-font token, a key cap's content is mostly
+       single characters and modifier glyphs (⌘⇧⌥), which read more legibly
+       — and have more complete glyph coverage — in the UI font than in a
+       monospace stack that may not even ship those symbols. */
+    font-family: var(--lyra-font);
+    font-size: 0.8125rem;
+    line-height: 1.3;
+    color: var(--lyra-color-text-quiet);
+  }
+
+  [part='key'] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    min-inline-size: 1.5em;
+    padding: 0.0625rem var(--lyra-space-xs);
+    border: 1px solid var(--lyra-color-border);
+    border-radius: calc(var(--lyra-radius) * 0.6);
+    background: var(--lyra-color-surface);
+    color: var(--lyra-color-text);
+    font-weight: 500;
+    /* A subtle bottom-weighted inset shadow reads as a slightly-raised
+       physical key cap rather than a flat label chip, echoing the
+       lyra-chip/lyra-checkbox box's own bordered-box treatment. */
+    box-shadow: inset 0 -1px 0 var(--lyra-color-border);
+  }
+
+  .sep {
+    margin-inline: 0.1875rem;
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.75em;
+    user-select: none;
+  }
+
+  ::slotted(*) {
+    vertical-align: middle;
+  }
+`;

package/dist/components/live-region/live-region.d.ts

@@ -0,0 +1,90 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { type AnnounceOptions } from '../../internal/announcer.js';
+export type LiveRegionMode = 'polite' | 'assertive';
+/**
+ * `<lyra-live-region>` — a visually-hidden ARIA live region that throttles
+ * and coalesces announcements instead of relaying every call verbatim.
+ *
+ * Naive live regions plus token-by-token streaming text (a chat response, a
+ * progress readout, ...) equals screen-reader spam: every incremental chunk
+ * gets announced. This component wraps `Announcer`
+ * (`../../internal/announcer.js`) so callers can fire `announce()` as often
+ * as they like — only the latest text within each `throttle-ms` window
+ * actually reaches assistive tech, and a `{ force: true }` call (e.g. once a
+ * stream ends) always lands immediately regardless of any window in
+ * progress.
+ *
+ * A consumer typically mounts one `<lyra-live-region>` per page/surface
+ * (much like `<lyra-toast>` is one region per placement — see
+ * `../toast/toaster.ts`) and keeps a reference to call `announce()` from
+ * application code or a parent component:
+ *
+ * @example
+ * ```html
+ * <!-- once, near the root of a chat surface's shell -->
+ * <lyra-live-region id="chat-live" mode="polite"></lyra-live-region>
+ * ```
+ * ```ts
+ * const live = document.getElementById('chat-live') as LyraLiveRegion;
+ *
+ * // streaming tokens: fine to call on every chunk, only the trailing state lands
+ * live.announce(`${partialText} …`);
+ *
+ * // stream finished: always announced, even mid-throttle-window
+ * live.announce('Response complete', { force: true });
+ * ```
+ *
+ * A parent Lit component would instead hold the reference via `@query`:
+ * ```ts
+ * @query('lyra-live-region') private liveRegion!: LyraLiveRegion;
+ * ```
+ * and is exactly what later components in this family (a stream-status
+ * indicator, a tool-call chip's status transitions, a chat message's
+ * streaming state) are expected to do rather than hand-rolling their own
+ * `aria-live` element.
+ *
+ * @customElement lyra-live-region
+ * @csspart region - The visually-hidden element carrying `role`/`aria-live`.
+ */
+export declare class LyraLiveRegion extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** `polite` (role="status") waits for the user to be idle; `assertive`
+     *  (role="alert") interrupts. Mirrors native `aria-live` semantics.
+     *
+     *  `write()` also applies `role`/`aria-live` imperatively at announce time
+     *  (not only through this property's template binding) so a caller that
+     *  sets `mode` and immediately force-announces in the same synchronous
+     *  turn -- e.g. a stream-status transition -- gets the new urgency and the
+     *  new text landing together, rather than the text beating Lit's
+     *  re-render to the DOM. */
+    mode: LiveRegionMode;
+    /** Throttle window in ms — see `Announcer` in `internal/announcer.ts`. */
+    throttleMs: number;
+    private readonly announcer;
+    private lastWritten;
+    private regionEl?;
+    private reannounceHandle?;
+    private reannounceView?;
+    private pendingWrite?;
+    constructor();
+    protected updated(changed: PropertyValues): void;
+    firstUpdated(): void;
+    disconnectedCallback(): void;
+    /**
+     * Queue `text` for announcement. Calls arriving within `throttle-ms` of
+     * the first call in a burst collapse to a single announcement of the
+     * latest text; pass `{ force: true }` to bypass the window and flush
+     * immediately (e.g. for a final/terminal message that must not be
+     * dropped).
+     */
+    announce(text: string, options?: AnnounceOptions): void;
+    private write;
+    private cancelReannounce;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-live-region': LyraLiveRegion;
+    }
+}

package/dist/components/live-region/live-region.js

@@ -0,0 +1,189 @@
+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 } from 'lit';
+import { property } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { srOnly } from '../../internal/a11y.js';
+import { Announcer } from '../../internal/announcer.js';
+import { styles } from './live-region.styles.js';
+/**
+ * `<lyra-live-region>` — a visually-hidden ARIA live region that throttles
+ * and coalesces announcements instead of relaying every call verbatim.
+ *
+ * Naive live regions plus token-by-token streaming text (a chat response, a
+ * progress readout, ...) equals screen-reader spam: every incremental chunk
+ * gets announced. This component wraps `Announcer`
+ * (`../../internal/announcer.js`) so callers can fire `announce()` as often
+ * as they like — only the latest text within each `throttle-ms` window
+ * actually reaches assistive tech, and a `{ force: true }` call (e.g. once a
+ * stream ends) always lands immediately regardless of any window in
+ * progress.
+ *
+ * A consumer typically mounts one `<lyra-live-region>` per page/surface
+ * (much like `<lyra-toast>` is one region per placement — see
+ * `../toast/toaster.ts`) and keeps a reference to call `announce()` from
+ * application code or a parent component:
+ *
+ * @example
+ * ```html
+ * <!-- once, near the root of a chat surface's shell -->
+ * <lyra-live-region id="chat-live" mode="polite"></lyra-live-region>
+ * ```
+ * ```ts
+ * const live = document.getElementById('chat-live') as LyraLiveRegion;
+ *
+ * // streaming tokens: fine to call on every chunk, only the trailing state lands
+ * live.announce(`${partialText} …`);
+ *
+ * // stream finished: always announced, even mid-throttle-window
+ * live.announce('Response complete', { force: true });
+ * ```
+ *
+ * A parent Lit component would instead hold the reference via `@query`:
+ * ```ts
+ * @query('lyra-live-region') private liveRegion!: LyraLiveRegion;
+ * ```
+ * and is exactly what later components in this family (a stream-status
+ * indicator, a tool-call chip's status transitions, a chat message's
+ * streaming state) are expected to do rather than hand-rolling their own
+ * `aria-live` element.
+ *
+ * @customElement lyra-live-region
+ * @csspart region - The visually-hidden element carrying `role`/`aria-live`.
+ */
+export class LyraLiveRegion extends LyraElement {
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    constructor() {
+        super();
+        /** `polite` (role="status") waits for the user to be idle; `assertive`
+         *  (role="alert") interrupts. Mirrors native `aria-live` semantics.
+         *
+         *  `write()` also applies `role`/`aria-live` imperatively at announce time
+         *  (not only through this property's template binding) so a caller that
+         *  sets `mode` and immediately force-announces in the same synchronous
+         *  turn -- e.g. a stream-status transition -- gets the new urgency and the
+         *  new text landing together, rather than the text beating Lit's
+         *  re-render to the DOM. */
+        this.mode = 'polite';
+        /** Throttle window in ms — see `Announcer` in `internal/announcer.ts`. */
+        this.throttleMs = 500;
+        // The live region's own last-written text. Tracked separately from
+        // whatever Lit thinks the DOM looks like because `write()` mutates
+        // `regionEl.textContent` directly (outside Lit's template bindings) --
+        // see `write()` for why.
+        this.lastWritten = '';
+        // Built in the constructor (not a class-field initializer) so it reads
+        // `this.throttleMs` only after that property's own field initializer
+        // has already run and set the declared default.
+        this.announcer = new Announcer({
+            throttleMs: this.throttleMs,
+            onFlush: (text) => this.write(text),
+        });
+    }
+    updated(changed) {
+        if (changed.has('throttleMs')) {
+            this.announcer.throttleMs = this.throttleMs;
+        }
+    }
+    firstUpdated() {
+        this.regionEl = this.renderRoot.querySelector('[part="region"]') ?? undefined;
+        if (this.pendingWrite !== undefined) {
+            const text = this.pendingWrite;
+            this.pendingWrite = undefined;
+            this.write(text);
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.announcer.cancel();
+        this.pendingWrite = undefined;
+        this.cancelReannounce();
+    }
+    /**
+     * Queue `text` for announcement. Calls arriving within `throttle-ms` of
+     * the first call in a burst collapse to a single announcement of the
+     * latest text; pass `{ force: true }` to bypass the window and flush
+     * immediately (e.g. for a final/terminal message that must not be
+     * dropped).
+     */
+    announce(text, options) {
+        this.announcer.announce(text, options);
+    }
+    write(text) {
+        const region = this.regionEl;
+        if (!region) {
+            this.pendingWrite = text;
+            return;
+        }
+        // A same-text reannounce frame still in flight is now stale the moment
+        // any new write() call comes in -- if it fired later it would clobber
+        // whatever text this call is about to land with the older, already-
+        // superseded string. Cancel it up front so at most one reannounce is
+        // ever pending and it can never overwrite a newer announcement.
+        this.cancelReannounce();
+        const assertive = this.mode === 'assertive';
+        if (text === this.lastWritten) {
+            // Screen readers announce a live region on text-content *change* --
+            // re-writing the identical string is otherwise a silent no-op to
+            // assistive tech. Clearing first and re-setting on the next frame
+            // (rather than in the same task) gives the DOM an actual empty ->
+            // populated transition to observe instead of a same-tick clear+set
+            // that can coalesce into nothing ever appearing to change.
+            //
+            // role/aria-live are set imperatively here (not left to Lit's
+            // template binding) so a caller that sets `mode` and immediately
+            // force-announces -- e.g. stream-status's announceTransition() --
+            // gets the new urgency in the same synchronous operation as the text,
+            // rather than racing Lit's async re-render.
+            region.setAttribute('role', assertive ? 'alert' : 'status');
+            region.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
+            region.textContent = '';
+            const view = region.ownerDocument.defaultView;
+            if (!view) {
+                region.textContent = text;
+                return;
+            }
+            this.reannounceView = view;
+            this.reannounceHandle = view.requestAnimationFrame(() => {
+                this.reannounceHandle = undefined;
+                this.reannounceView = undefined;
+                region.textContent = text;
+            });
+        }
+        else {
+            region.setAttribute('role', assertive ? 'alert' : 'status');
+            region.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
+            region.textContent = text;
+        }
+        this.lastWritten = text;
+    }
+    cancelReannounce() {
+        if (this.reannounceHandle === undefined)
+            return;
+        this.reannounceView?.cancelAnimationFrame(this.reannounceHandle);
+        this.reannounceHandle = undefined;
+        this.reannounceView = undefined;
+    }
+    render() {
+        const assertive = this.mode === 'assertive';
+        return html `<div
+      part="region"
+      class="sr-only"
+      role=${assertive ? 'alert' : 'status'}
+      aria-live=${assertive ? 'assertive' : 'polite'}
+      aria-atomic="true"
+    ></div>`;
+    }
+}
+__decorate([
+    property({ reflect: true })
+], LyraLiveRegion.prototype, "mode", void 0);
+__decorate([
+    property({ type: Number, attribute: 'throttle-ms' })
+], LyraLiveRegion.prototype, "throttleMs", void 0);
+defineElement('live-region', LyraLiveRegion);

package/dist/components/live-region/live-region.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/components/live-region/live-region.styles.js

@@ -0,0 +1,10 @@
+import { css } from 'lit';
+export const styles = css `
+  /* The host contributes no box of its own -- \`.sr-only\` (composed in via
+     internal/a11y.ts's shared \`srOnly\`) already takes the single child out
+     of flow via absolute positioning, so a wrapping host box would just be
+     an empty, purposeless inline element sitting in the document. */
+  :host {
+    display: contents;
+  }
+`;