@aceshooting/lyra-ui 4.1.0 → 5.0.0

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

@@ -0,0 +1,96 @@
+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';
+/**
+ * `<lr-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 `<lr-live-region>` per page/surface
+ * (much like `<lr-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 -->
+ * <lr-live-region id="chat-live" mode="polite"></lr-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('lr-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 lr-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?;
+    /** `throttleMs` normalized to a finite timer duration before it reaches `Announcer`'s own
+     *  `setTimeout(..., throttleMs)` call -- an invalid attribute value would otherwise schedule a
+     *  same-tick flush (NaN/negative both clamp to 0 per the `setTimeout` spec) or hit browsers'
+     *  32-bit `setTimeout` ceiling unpredictably (`Infinity`/an absurdly large value). */
+    private get safeThrottleMs();
+    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 {
+        'lr-live-region': LyraLiveRegion;
+    }
+}
+//# sourceMappingURL=live-region.class.d.ts.map

package/dist/components/utility/live-region/live-region.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-region.class.d.ts","sourceRoot":"","sources":["../../../../src/components/utility/live-region/live-region.class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAGhE,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,MAAM,CAAC,MAAM,iCAAwC;IAErD;;;;;;;;gCAQ4B;IACC,IAAI,EAAE,cAAc,CAAY;IAE7D,0EAA0E;IACpB,UAAU,SAAO;IAEvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAMtC,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,QAAQ,CAAC,CAAc;IAC/B,OAAO,CAAC,gBAAgB,CAAC,CAA2C;IACpE,OAAO,CAAC,cAAc,CAAC,CAAS;IAOhC,OAAO,CAAC,YAAY,CAAC,CAAS;IAE9B;;;0FAGsF;IACtF,OAAO,KAAK,cAAc,GAEzB;IAED,cASC;IAED,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAI/C;IAED,YAAY,IAAI,IAAI,CAOnB;IAED,oBAAoB,IAAI,IAAI,CAK3B;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAEtD;IAED,OAAO,CAAC,KAAK;IAgDb,OAAO,CAAC,gBAAgB;IAOxB,MAAM,IAAI,cAAc,CASvB;CACF;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,gBAAgB,EAAE,cAAc,CAAC;KAClC;CACF"}

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

@@ -0,0 +1,196 @@
+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 { srOnly } from '../../../internal/a11y.js';
+import { finiteDuration } from '../../../internal/numbers.js';
+import { Announcer } from '../../../internal/announcer.js';
+import { styles } from './live-region.styles.js';
+/**
+ * `<lr-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 `<lr-live-region>` per page/surface
+ * (much like `<lr-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 -->
+ * <lr-live-region id="chat-live" mode="polite"></lr-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('lr-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 lr-live-region
+ * @csspart region - The visually-hidden element carrying `role`/`aria-live`.
+ */
+export class LyraLiveRegion extends LyraElement {
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    /** `throttleMs` normalized to a finite timer duration before it reaches `Announcer`'s own
+     *  `setTimeout(..., throttleMs)` call -- an invalid attribute value would otherwise schedule a
+     *  same-tick flush (NaN/negative both clamp to 0 per the `setTimeout` spec) or hit browsers'
+     *  32-bit `setTimeout` ceiling unpredictably (`Infinity`/an absurdly large value). */
+    get safeThrottleMs() {
+        return finiteDuration(this.throttleMs, 500);
+    }
+    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.safeThrottleMs,
+            onFlush: (text) => this.write(text),
+        });
+    }
+    updated(changed) {
+        if (changed.has('throttleMs')) {
+            this.announcer.throttleMs = this.safeThrottleMs;
+        }
+    }
+    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);
+//# sourceMappingURL=live-region.class.js.map

package/dist/components/utility/live-region/live-region.class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-region.class.js","sourceRoot":"","sources":["../../../../src/components/utility/live-region/live-region.class.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,IAAI,EAA4C,MAAM,KAAK,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAwB,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;aACtC,WAAM,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,AAAvC,CAAwC;IAkCrD;;;0FAGsF;IACtF,IAAY,cAAc;QACxB,OAAO,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED;QACE,KAAK,EAAE,CAAC;QAzCV;;;;;;;;oCAQ4B;QACC,SAAI,GAAmB,QAAQ,CAAC;QAE7D,0EAA0E;QACpB,eAAU,GAAG,GAAG,CAAC;QAIvE,mEAAmE;QACnE,mEAAmE;QACnE,uEAAuE;QACvE,yBAAyB;QACjB,gBAAW,GAAG,EAAE,CAAC;QAsBvB,uEAAuE;QACvE,qEAAqE;QACrE,gDAAgD;QAChD,IAAI,CAAC,SAAS,GAAG,IAAI,SAAS,CAAC;YAC7B,UAAU,EAAE,IAAI,CAAC,cAAc;YAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;SACpC,CAAC,CAAC;IACL,CAAC;IAES,OAAO,CAAC,OAAuB;QACvC,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,SAAS,CAAC,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC;QAClD,CAAC;IACH,CAAC;IAED,YAAY;QACV,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,aAAa,CAAc,iBAAiB,CAAC,IAAI,SAAS,CAAC;QAC3F,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC;YAC/B,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;YAC9B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IAED,oBAAoB;QAClB,KAAK,CAAC,oBAAoB,EAAE,CAAC;QAC7B,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;QACxB,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,IAAY,EAAE,OAAyB;QAC9C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAEO,KAAK,CAAC,IAAY;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC7B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,OAAO;QACT,CAAC;QACD,uEAAuE;QACvE,sEAAsE;QACtE,oEAAoE;QACpE,qEAAqE;QACrE,gEAAgE;QAChE,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;QAC5C,IAAI,IAAI,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;YAC9B,oEAAoE;YACpE,iEAAiE;YACjE,kEAAkE;YAClE,kEAAkE;YAClE,mEAAmE;YACnE,2DAA2D;YAC3D,EAAE;YACF,8DAA8D;YAC9D,iEAAiE;YACjE,kEAAkE;YAClE,sEAAsE;YACtE,4CAA4C;YAC5C,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAC5D,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YACrE,MAAM,CAAC,WAAW,GAAG,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC;YAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC;gBAC1B,OAAO;YACT,CAAC;YACD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAC3B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,qBAAqB,CAAC,GAAG,EAAE;gBACtD,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;gBAClC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;gBAChC,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAC5D,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YACrE,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAEO,gBAAgB;QACtB,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS;YAAE,OAAO;QAChD,IAAI,CAAC,cAAc,EAAE,oBAAoB,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACjE,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;IAClC,CAAC;IAED,MAAM;QACJ,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;QAC5C,OAAO,IAAI,CAAA;;;aAGF,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ;kBACzB,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ;;YAExC,CAAC;IACX,CAAC;CACF;AA5I8B;IAA5B,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;4CAAiC;AAGP;IAArD,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;kDAAkB"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"live-region.d.ts","sourceRoot":"","sources":["../../../../src/components/utility/live-region/live-region.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

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

@@ -0,0 +1,5 @@
+export * from './live-region.class.js';
+import { LyraLiveRegion } from './live-region.class.js';
+import { defineElement } from '../../../internal/prefix.js';
+defineElement('live-region', LyraLiveRegion);
+//# sourceMappingURL=live-region.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"live-region.js","sourceRoot":"","sources":["../../../../src/components/utility/live-region/live-region.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"live-region.styles.d.ts","sourceRoot":"","sources":["../../../../src/components/utility/live-region/live-region.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM,yBAQlB,CAAC"}

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

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

package/dist/components/utility/mention-popover/mention-popover.class.d.ts

@@ -0,0 +1,221 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../../internal/lyra-element.js';
+/** One candidate row — an `@`-mentionable person/entity, or a `/`-command. */
+export interface MentionItem {
+    id: string;
+    label: string;
+    description?: string;
+    /** Literal icon hint (e.g. an emoji), rendered next to `label` -- same
+     *  "opaque string, not a registry lookup" convention as
+     *  `<lr-tool-call-chip>`'s/`<lr-tool-select-dialog>`'s own `icon`. */
+    icon?: string;
+}
+/** Predicate deciding whether `item` matches a (already-trimmed, already-lowercased) `query`.
+ *  Mirrors `<lr-combobox>`'s `OptionFilter` convention -- override `filter` to replace the
+ *  built-in case-insensitive label/description substring match entirely. */
+export type MentionFilter = (item: MentionItem, query: string) => boolean;
+export interface MentionSelectDetail {
+    id: string;
+    label: string;
+}
+export interface LyraMentionPopoverEventMap {
+    'lr-mention-select': CustomEvent<MentionSelectDetail>;
+    'lr-mention-close': CustomEvent<undefined>;
+}
+/**
+ * `<lr-mention-popover>` — a caret-anchored, keyboard-navigable popover for
+ * `@`-mention and `/`-slash-command autocomplete inside a plain-text
+ * `<textarea>`/`<input>` the host owns (e.g. `<lr-chat-composer>`'s own
+ * textarea, though this component has no dependency on that or any other
+ * specific input). It never takes DOM focus itself — the same "focus stays
+ * put, `aria-activedescendant` conveys the active row" pattern
+ * `<lr-select>`/`<lr-combobox>` use for their own listbox — so a host
+ * must apply `aria-activedescendant` to its *own* input element, pointing at
+ * whatever `activeDescendantId` currently returns.
+ *
+ * Integration contract (entirely the host's responsibility — this component
+ * never inspects the text control's value or listens to it directly):
+ * 1. Detect a mention/command trigger (e.g. `@`/`/` at the start of a word)
+ *    in the host's own `input` handling.
+ * 2. Set `anchor` (the `<textarea>`/`<input>` itself, or any element for
+ *    plain whole-element anchoring — see "Positioning" below), `items`, and
+ *    `query` (the text typed since the trigger character), then flip
+ *    `open = true`.
+ * 3. Forward every `keydown` the input receives, while `open`, through
+ *    `handleKeyDown()` — it returns `true` when it consumed the key (so the
+ *    host's own handler should stop, e.g. skip submitting the message on an
+ *    Enter that actually picked a mention) and `false` otherwise.
+ * 4. Set `open = false` whenever the query stops looking like an active
+ *    mention context (a space typed, the trigger character deleted, the
+ *    input blurred, …) — `lr-mention-close` fires automatically from that
+ *    (see below), there is no separate "tell it to close" call needed.
+ * 5. Keep the host's own input's `aria-activedescendant` (and, optionally,
+ *    `aria-controls`, via `listboxId`) in sync with `activeDescendantId` —
+ *    this component has no DOM of the host's to attach that to itself.
+ *
+ * Positioning: when `anchor` is a plain `<textarea>` or single-line text
+ * `<input>`, this component measures exactly where the caret currently
+ * paints (`caretClientRect()`, the standard hidden-mirror-element technique
+ * — see that function's own doc) and positions against that single point
+ * with `internal/positioner.js`'s `place()`, so the popup tracks the caret
+ * rather than sitting under the whole textarea. Any other `anchor` element
+ * (or a text control this component fails to measure, e.g. one with
+ * `display: none`) falls back to `place(anchor, popup)` against the whole
+ * element — the same whole-element anchoring `<lr-combobox>`/
+ * `<lr-select>` use for their own popups. Re-measures on every `anchor`/
+ * `query` change while open (a keystroke moves the caret, so a fresh `query`
+ * is the proxy for "the caret may have moved"); a caret that moves for a
+ * reason other than typing (e.g. a mouse click elsewhere in the text while
+ * the popover happens to still be open) is not separately tracked — the
+ * host can force a re-measure by toggling `open` or reassigning `anchor`.
+ *
+ * Filtering happens internally against `items` (mirroring `<lr-combobox>`'s
+ * filter-predicate convention via `filter`, rather than requiring the host to
+ * pre-filter): the default predicate is a case-insensitive substring match
+ * against `label`/`description`, overridable via `filter`.
+ *
+ * There is no persisted "selection" the way a real listbox has one — a
+ * mention is either committed (closing the popover) or the popover is
+ * dismissed with nothing chosen — so `aria-selected="true"` marks whichever
+ * row is currently *active* (what Enter/Tab would commit right now), per the
+ * WAI-ARIA combobox-with-list-autocomplete pattern, rather than tracking a
+ * separate persisted value the way `<lr-combobox>`'s own `aria-selected`
+ * does.
+ *
+ * @example
+ * ```html
+ * <textarea id="composer"></textarea>
+ * <lr-mention-popover id="mentions"></lr-mention-popover>
+ * <script>
+ *   const textarea = document.getElementById('composer');
+ *   const popover = document.getElementById('mentions');
+ *
+ *   textarea.addEventListener('keydown', (e) => {
+ *     if (popover.open && popover.handleKeyDown(e)) return; // consumed
+ *     // ...the host's own Enter-to-send handling, etc.
+ *   });
+ *   textarea.addEventListener('input', () => {
+ *     // host's own '@'/'/' + query detection, then:
+ *     popover.anchor = textarea;
+ *     popover.items = candidates;
+ *     popover.query = detectedQuery;
+ *     popover.open = detectedQuery !== null;
+ *   });
+ *   textarea.addEventListener('blur', () => (popover.open = false));
+ *
+ *   popover.addEventListener('lr-mention-select', (e) => {
+ *     // splice `${e.detail.label}` into the textarea at the trigger offset
+ *   });
+ *   popover.addEventListener('lr-mention-close', () => {
+ *     textarea.removeAttribute('aria-activedescendant');
+ *   });
+ *
+ *   // Whenever the popover re-renders its active row (e.g. after every
+ *   // ArrowUp/ArrowDown handleKeyDown() call above), sync the host's own
+ *   // input so assistive tech announces the current candidate:
+ *   const syncActiveDescendant = () => {
+ *     if (popover.open && popover.activeDescendantId) {
+ *       textarea.setAttribute('aria-activedescendant', popover.activeDescendantId);
+ *     } else {
+ *       textarea.removeAttribute('aria-activedescendant');
+ *     }
+ *   };
+ * </script>
+ * ```
+ *
+ * @customElement lr-mention-popover
+ * @event lr-mention-select - An item was committed (Enter/Tab/click). `detail: { id, label }`.
+ * @event lr-mention-close - The popover was dismissed with no selection — Escape, or `open`
+ * transitioning to `false` by any other means (a direct host assignment included). Never fires
+ * for a close that followed a `lr-mention-select` commit.
+ * @csspart listbox - The popover's root element (`role="listbox"`).
+ * @csspart option - A candidate row (`role="option"`).
+ * @csspart option-icon - A row's leading icon glyph, when `icon` is set.
+ * @csspart option-label - Wrapper around a row's label/description.
+ * @csspart option-description - A row's optional secondary line, when `description` is set.
+ * @csspart empty - The "no matches" message, shown when `items`/`query` produce zero rows.
+ */
+export declare class LyraMentionPopover extends LyraElement<LyraMentionPopoverEventMap> {
+    static styles: import("lit").CSSResultGroup[];
+    /** The element to position the popup relative to. When this is a plain
+     *  `<textarea>`/single-line text `<input>`, positioning is caret-precise
+     *  (see the class doc); any other element anchors the whole popup under
+     *  that element's own box, the same as `<lr-combobox>`'s trigger. */
+    anchor?: HTMLElement;
+    /** The full candidate set, pre-`query`-filtering. */
+    items: MentionItem[];
+    /** The text typed since the trigger character (`@`/`/`/…) — drives the
+     *  built-in internal filtering (see `filter` to override it). */
+    query: string;
+    /** Whether the popover is shown. */
+    open: boolean;
+    /** Overrides the built-in case-insensitive label/description substring match. */
+    filter: MentionFilter | null;
+    /** Message shown when `items` (post-`query`-filtering) is empty. */
+    emptyText: string;
+    /** Accessible name for the `role="listbox"` popup. Also settable as a plain `aria-label`
+     *  attribute on `<lr-mention-popover>` itself, which takes precedence over this property when
+     *  present -- matches `<lr-combobox>`'s/`<lr-table>`'s identical host `aria-label` fallback. */
+    label: string;
+    private activeIndex;
+    private readonly _listboxId;
+    private cleanup?;
+    private virtualAnchor;
+    private _isFirstUpdate;
+    private _suppressCloseEvent;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    /** The current candidate set: `items` filtered by `query` via `filter`
+     *  (or the built-in default). Empty `query` returns `items` unfiltered. */
+    get filteredItems(): MentionItem[];
+    /** The `id` of the currently-highlighted row for the host to apply as its
+     *  own input's `aria-activedescendant` — `null` while closed or when
+     *  `filteredItems` is empty (nothing to point at). See the class doc's
+     *  `@example` for the full wiring. */
+    get activeDescendantId(): string | null;
+    /** The `id` of the `role="listbox"` popup, for a host that also wants to
+     *  wire `aria-controls` on its own input (screen-reader support for
+     *  `aria-controls` is inconsistent, so `activeDescendantId` remains the
+     *  load-bearing piece; this is a supplementary nicety). */
+    get listboxId(): string;
+    /**
+     * The host's own text-control keydown handler calls this while the
+     * popover is open. Returns `true` when the key was intercepted
+     * (`preventDefault()` already called) and the host should not also act on
+     * it; `false` when the host's normal handling should proceed untouched --
+     * including ArrowDown/ArrowUp/Enter/Tab when there are zero filtered rows
+     * to act on, so e.g. the host's own textarea still moves its caret a line
+     * normally rather than having the keystroke silently eaten.
+     */
+    handleKeyDown(e: KeyboardEvent): boolean;
+    private clampedIndex;
+    private rowId;
+    private commit;
+    private reposition;
+    /** Resolves what to actually hand `place()` -- a caret-precise virtual
+     *  point for a measurable text control, `anchor` itself otherwise. See the
+     *  class doc's "Positioning" section. */
+    private resolveAnchorElement;
+    private onListboxMouseDown;
+    private onListboxClick;
+    /** Resolves `emptyText`'s effective text: an explicit override wins verbatim; left at the
+     *  built-in default it instead routes through `this.localize()` so a locale/`.strings`
+     *  override applies without requiring `emptyText` itself to be set. */
+    private get effectiveEmptyText();
+    /** Resolves `label`'s effective text: a host-level plain `aria-label` attribute on
+     *  `<lr-mention-popover>` itself wins first (checked via a plain `getAttribute()` read, not a
+     *  reactive property, matching `<lr-combobox>`'s/`<lr-table>`'s identical fallback); failing
+     *  that, an explicit `label` override wins verbatim; left at the built-in default it instead
+     *  routes through `this.localize()` so a locale/`.strings` override applies without requiring
+     *  `label` itself to be set. */
+    private get effectiveLabel();
+    private renderRow;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lr-mention-popover': LyraMentionPopover;
+    }
+}
+//# sourceMappingURL=mention-popover.class.d.ts.map

package/dist/components/utility/mention-popover/mention-popover.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mention-popover.class.d.ts","sourceRoot":"","sources":["../../../../src/components/utility/mention-popover/mention-popover.class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE9E,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAKhE,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;0EAEsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;4EAE4E;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAqGD,MAAM,WAAW,0BAA0B;IACzC,mBAAmB,EAAE,WAAW,CAAC,mBAAmB,CAAC,CAAC;IACtD,kBAAkB,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;CAC5C;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AACH,qBAAa,kBAAmB,SAAQ,WAAW,CAAC,0BAA0B,CAAC;IAC7E,MAAM,CAAC,MAAM,iCAAgC;IAE7C;;;yEAGqE;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;IAErD,qDAAqD;IACrB,KAAK,EAAE,WAAW,EAAE,CAAM;IAE1D;qEACiE;IACrD,KAAK,SAAM;IAEvB,oCAAoC;IACQ,IAAI,UAAS;IAEzD,iFAAiF;IACjD,MAAM,EAAE,aAAa,GAAG,IAAI,CAAQ;IAEpE,oEAAoE;IAC7B,SAAS,SAAgB;IAEhE;;oGAEgG;IACpF,KAAK,SAAiB;IAQzB,OAAO,CAAC,WAAW,CAAK;IAEjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;IAChE,OAAO,CAAC,OAAO,CAAC,CAAa;IAK7B,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,cAAc,CAAQ;IAM9B,OAAO,CAAC,mBAAmB,CAAS;IAEpC,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAOlD;IAED,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CA4B/C;IAED,oBAAoB,IAAI,IAAI,CAc3B;IAED;+EAC2E;IAC3E,IAAI,aAAa,IAAI,WAAW,EAAE,CAKjC;IAED;;;0CAGsC;IACtC,IAAI,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAItC;IAED;;;+DAG2D;IAC3D,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAkCvC;IAED,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,UAAU;IAQlB;;6CAEyC;IACzC,OAAO,CAAC,oBAAoB;IAuB5B,OAAO,CAAC,kBAAkB,CAKxB;IAEF,OAAO,CAAC,cAAc,CAMpB;IAEF;;2EAEuE;IACvE,OAAO,KAAK,kBAAkB,GAE7B;IAED;;;;;oCAKgC;IAChC,OAAO,KAAK,cAAc,GAKzB;IAED,OAAO,CAAC,SAAS;IAcjB,MAAM,IAAI,cAAc,CAmBvB;CACF;AAGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,oBAAoB,EAAE,kBAAkB,CAAC;KAC1C;CACF"}