@aceshooting/lyra-ui 1.2.0 → 2.0.0

package/dist/components/virtual-list/virtual-list.js

@@ -0,0 +1,461 @@
+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 { repeat } from 'lit/directives/repeat.js';
+import { styleMap } from 'lit/directives/style-map.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import { styles } from './virtual-list.styles.js';
+/** Fallback per-row height (px) used for any row that hasn't been measured
+ *  yet in `row-height="auto"` mode -- close enough to a typical single-line
+ *  chat-list row that the initial scrollbar/spacer size doesn't jump wildly
+ *  once real measurements arrive. Irrelevant in fixed-`row-height` mode. */
+const DEFAULT_ROW_ESTIMATE_PX = 48;
+function prefersReducedMotion() {
+    return typeof window !== 'undefined' && !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+}
+/**
+ * `<lyra-virtual-list>` — a generic windowed/virtualized list host. Renders
+ * only the items within the current viewport (plus `overscan` padding rows
+ * on each side) as real DOM, regardless of how large `items` is, so a
+ * multi-thousand-row chat history sidebar (or, in a later phase, a long
+ * message thread) stays cheap to scroll.
+ *
+ * Content is entirely caller-supplied: `renderItem(item, index)` returns
+ * whatever `lit-html` value should represent that row (typically a
+ * `TemplateResult`), and `keyFunction(item, index)` gives it a stable
+ * identity for `repeat()`'s DOM-reconciliation key, so scroll position and
+ * any per-row state (e.g. an `<audio>` element's playback position) survive
+ * an `items` mutation instead of every row remounting from scratch.
+ *
+ * **Windowing math.** Every row — in both `row-height` modes — is positioned
+ * by a `transform: translateY(offset)` computed from a single cumulative
+ * `offsets` array (`offsets[i]` = the pixel top of row `i`), rather than by
+ * page flow. This is what lets only a small DOM window exist while the
+ * scrollbar still reflects the *true* total content height:
+ * - **`row-height="auto"` (default).** Each currently-rendered row is
+ *   watched by a `ResizeObserver`; its real height lands in a per-key
+ *   `Map`, and any row not yet measured contributes `DEFAULT_ROW_ESTIMATE_PX`
+ *   to the offsets array until it has been. `offsets` is *not* the same
+ *   thing as a page-count-based `padding-top`/`padding-bottom` spacer pair —
+ *   that approach reflows every unmeasured row's position on every new
+ *   measurement, which is exactly what per-row transform offsets avoid: only
+ *   the rows *after* a newly-measured one shift, and even that shift is a
+ *   cheap style recompute, not a layout-affecting padding change.
+ * - **Fixed numeric `row-height`.** No measurement needed — `offsets[i]` is
+ *   just `i * rowHeightPx`, computed by the exact same cumulative-array code
+ *   path (a dedicated "single spacer + start-index" special case was
+ *   considered and would work too, but reusing one code path for both modes
+ *   avoids maintaining two parallel rendering strategies for a difference
+ *   that's otherwise just "how is row *i*'s height looked up").
+ *
+ * The `offsets` array is rebuilt on every update. For the list sizes this
+ * component is meant for (a scrollable history sidebar, realistically
+ * hundreds to a few thousand rows) that's a trivial `O(n)` arithmetic loop,
+ * even at scroll-driven ~60fps; it is *not* the right approach for a
+ * hundred-thousand-row list without further work (e.g. a Fenwick/segment
+ * tree for `O(log n)` offset queries+updates), which is out of scope here.
+ *
+ * **Accessibility.** The scroll container is `role="list"` and each rendered
+ * row is `role="listitem"`, deliberately *not* `listbox`/`option` — this
+ * component only provides windowing, not the roving-tabindex/
+ * `aria-activedescendant` keyboard-interaction contract ARIA requires
+ * alongside a real `listbox`. A consumer that wants full single-select
+ * listbox semantics on top of this should compose that behavior itself (see
+ * `<lyra-select>`'s pattern), the same way this component's `active-id`
+ * only *scrolls* the matching row into view and marks it `aria-current` —
+ * it never claims to be a selection widget. `aria-setsize`/`aria-posinset`
+ * are computed from the row's real index in the full `items` array (not its
+ * position among the currently-rendered DOM window), so a screen reader
+ * still announces e.g. "item 12 of 340" correctly. `[part="base"]` itself
+ * carries `tabindex="0"` — `renderItem`'s content is caller-supplied and not
+ * guaranteed to contain a focusable element, and a scrollable region with no
+ * focusable content of its own is otherwise unreachable by keyboard (native
+ * arrow/Page Up/Page Down scrolling included).
+ *
+ * **Grouping.** `groups` is accepted for forward API compatibility with a
+ * later phase's sticky-header sectioning feature (paired with a
+ * `groupByRecency()` helper that doesn't exist yet) but is not read or
+ * rendered by this pass — every row still renders flat, in `items` order.
+ *
+ * @customElement lyra-virtual-list
+ * @event lyra-load-more - Fired once per approach to the bottom of the list
+ *   while `has-more` is true and `loading` is false. Deliberately does not
+ *   refire on every scroll tick while still near the bottom (`loading`
+ *   gates the in-flight case; scrolling back away from the bottom and
+ *   returning, or `items` growing enough to move the window away from the
+ *   end, re-arms it) — a consumer wanting an automatic retry after a failed
+ *   fetch should surface its own retry affordance rather than relying on
+ *   this firing again unprompted.
+ * @event lyra-visible-range-changed - `detail: { start, end }` (see
+ *   `VirtualListRange`) — the current visible (non-overscanned) item index
+ *   range, fired only when it actually changes.
+ * @csspart base - The scrollable container (`role="list"`).
+ * @csspart spacer - The full-content-height inner element that gives the
+ *   container its true scrollable extent.
+ * @csspart row - One rendered row's absolutely-positioned wrapper
+ *   (`role="listitem"`); `renderItem`'s return value renders inside it.
+ */
+export class LyraVirtualList extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** The full (non-windowed) item collection. */
+        this.items = [];
+        /** Renders one row's content — typically returns a `lit-html` `TemplateResult`. */
+        this.renderItem = () => nothing;
+        /** `'auto'` (default) measures each row's real height via `ResizeObserver`;
+         *  a numeric string fixes every row to that many pixels. */
+        this.rowHeight = 'auto';
+        /** Extra rows rendered beyond the visible viewport on each side, to reduce blank-frame risk during fast scrolling. */
+        this.overscan = 6;
+        /** When set and it matches a row's `keyFunction` result, that row is smoothly scrolled into view whenever this changes. */
+        this.activeId = '';
+        this.loading = false;
+        /** When true, scrolling near the bottom fires `lyra-load-more`. */
+        this.hasMore = false;
+        // Named distinctly from the inherited DOM `scrollTop` (a `HTMLElement`
+        // property this class would otherwise shadow) -- this tracks the *scroll
+        // container's* scrollTop, not the host element's own (the host never
+        // scrolls itself; [part="base"] does).
+        this.containerScrollTop = 0;
+        this.viewportHeight = 0;
+        /** `offsets[i]` = row `i`'s pixel top; `offsets[items.length]` = total content height. Rebuilt every update. */
+        this.offsets = [0];
+        /** Parsed `rowHeight`: a positive pixel number, or `null` for `'auto'` (measured) mode. */
+        this.fixedRowHeight = null;
+        /** `row-height="auto"` per-row measured heights, keyed by `String(keyFunction(item, index))`. */
+        this.measuredHeights = new Map();
+        this.renderStart = 0;
+        this.renderEnd = -1;
+        this.visibleStart = 0;
+        this.visibleEnd = -1;
+        this.lastEmittedStart = -1;
+        this.lastEmittedEnd = -1;
+        /** Re-armed whenever the window moves away from the end of `items` -- see the `lyra-load-more` event doc. */
+        this.loadMoreArmed = true;
+        this.isFirstUpdate = true;
+        this.observedRows = new Map();
+        this.pendingScrollTop = null;
+        this.onScroll = (e) => {
+            this.pendingScrollTop = e.currentTarget.scrollTop;
+            if (this.scrollRafId !== undefined)
+                return;
+            // Coalesce to one recompute per animation frame -- native `scroll`
+            // events can fire far faster than that under a fast trackpad/touch
+            // fling, and each recompute is a full Lit update.
+            this.scrollRafId = requestAnimationFrame(() => {
+                this.scrollRafId = undefined;
+                if (this.pendingScrollTop !== null) {
+                    this.containerScrollTop = this.pendingScrollTop;
+                    this.pendingScrollTop = null;
+                }
+            });
+        };
+        this.onRowsResized = (entries) => {
+            if (this.fixedRowHeight != null)
+                return;
+            let changed = false;
+            for (const entry of entries) {
+                const key = entry.target.dataset.rowKey;
+                if (key === undefined)
+                    continue;
+                const height = entry.borderBoxSize?.[0]?.blockSize ?? entry.target.getBoundingClientRect().height;
+                const prev = this.measuredHeights.get(key);
+                // A sub-pixel-only difference (common with fractional layout/zoom)
+                // isn't worth a full offsets rebuild + re-render.
+                if (prev === undefined || Math.abs(prev - height) > 0.5) {
+                    this.measuredHeights.set(key, height);
+                    changed = true;
+                }
+            }
+            if (changed)
+                this.requestUpdate();
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    connectedCallback() {
+        super.connectedCallback();
+        this.rowResizeObserver = new ResizeObserver(this.onRowsResized);
+        // firstUpdated() only ever fires once per element instance -- a
+        // disconnect/reconnect (e.g. a reparenting drag) needs its own
+        // re-attach here, since the container observer/scroll listener were
+        // torn down in disconnectedCallback below.
+        if (this.hasUpdated)
+            this.attachContainerListeners();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.rowResizeObserver?.disconnect();
+        this.rowResizeObserver = undefined;
+        this.observedRows.clear();
+        this.containerResizeObserver?.disconnect();
+        this.containerResizeObserver = undefined;
+        if (this.scrollRafId !== undefined) {
+            cancelAnimationFrame(this.scrollRafId);
+            this.scrollRafId = undefined;
+        }
+        this.renderRoot.querySelector('[part="base"]')?.removeEventListener('scroll', this.onScroll);
+    }
+    firstUpdated() {
+        this.attachContainerListeners();
+    }
+    willUpdate(changed) {
+        this.isFirstUpdate = !this.hasUpdated;
+        if (changed.has('rowHeight')) {
+            this.fixedRowHeight = this.parseRowHeight(this.rowHeight);
+        }
+        this.recomputeOffsets();
+        this.computeRange();
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.syncRowObservers();
+        if (changed.has('activeId') && !this.isFirstUpdate)
+            this.scrollActiveIntoView();
+        this.emitRangeChangeIfNeeded();
+        this.maybeFireLoadMore();
+    }
+    parseRowHeight(value) {
+        if (value === 'auto')
+            return null;
+        const n = Number(value);
+        // Anything that isn't 'auto' or a positive finite number falls back to
+        // auto mode rather than throwing or producing a zero/negative-height
+        // row -- matches this library's generally-permissive attribute parsing.
+        return Number.isFinite(n) && n > 0 ? n : null;
+    }
+    keyOf(item, index) {
+        return this.keyFunction ? this.keyFunction(item, index) : index;
+    }
+    recomputeOffsets() {
+        const n = this.items.length;
+        const offsets = new Array(n + 1);
+        offsets[0] = 0;
+        for (let i = 0; i < n; i++) {
+            const h = this.fixedRowHeight ??
+                this.measuredHeights.get(String(this.keyOf(this.items[i], i))) ??
+                DEFAULT_ROW_ESTIMATE_PX;
+            offsets[i + 1] = offsets[i] + h;
+        }
+        this.offsets = offsets;
+    }
+    /** First item index whose bottom edge is at/after `offset`. */
+    findIndexAtOrAfter(offset) {
+        const offsets = this.offsets;
+        let lo = 0;
+        let hi = offsets.length - 2;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (offsets[mid + 1] <= offset)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo;
+    }
+    /** Last item index whose top edge is at/before `offset`. */
+    findIndexAtOrBefore(offset) {
+        const offsets = this.offsets;
+        let lo = 0;
+        let hi = offsets.length - 2;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (offsets[mid] < offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo;
+    }
+    computeRange() {
+        const n = this.items.length;
+        if (n === 0 || this.viewportHeight <= 0) {
+            this.visibleStart = 0;
+            this.visibleEnd = -1;
+            this.renderStart = 0;
+            this.renderEnd = -1;
+            return;
+        }
+        const viewTop = this.containerScrollTop;
+        const viewBottom = viewTop + this.viewportHeight;
+        this.visibleStart = this.findIndexAtOrAfter(viewTop);
+        this.visibleEnd = this.findIndexAtOrBefore(viewBottom);
+        this.renderStart = Math.max(0, this.visibleStart - this.overscan);
+        this.renderEnd = Math.min(n - 1, this.visibleEnd + this.overscan);
+    }
+    attachContainerListeners() {
+        const base = this.renderRoot.querySelector('[part="base"]');
+        if (!base)
+            return;
+        this.containerResizeObserver = new ResizeObserver((entries) => {
+            const entry = entries[0];
+            if (!entry)
+                return;
+            this.viewportHeight = entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height;
+        });
+        this.containerResizeObserver.observe(base);
+        base.addEventListener('scroll', this.onScroll, { passive: true });
+        // Read synchronously too -- ResizeObserver's first callback is
+        // asynchronous, so without this the very first render would otherwise
+        // sit at viewportHeight=0 (rendering no rows at all) until that callback
+        // eventually fires. This is called from firstUpdated(), so setting a
+        // reactive property here schedules a second update on top of the one
+        // that just finished -- Lit's dev-mode console flags that pattern, but
+        // it's the documented exception ("the next update can only be scheduled
+        // as a side effect of the previous update"): the container's real size
+        // genuinely isn't knowable until after the first layout.
+        this.viewportHeight = base.clientHeight;
+        this.containerScrollTop = base.scrollTop;
+    }
+    /** Keeps the row `ResizeObserver` watching exactly the currently-rendered
+     *  rows in `row-height="auto"` mode -- rows that scroll out of the
+     *  rendered window are unobserved so the observer doesn't accumulate
+     *  references to detached elements it can never usefully report on again. */
+    syncRowObservers() {
+        const ro = this.rowResizeObserver;
+        if (!ro)
+            return;
+        if (this.fixedRowHeight != null) {
+            for (const el of this.observedRows.values())
+                ro.unobserve(el);
+            this.observedRows.clear();
+            return;
+        }
+        const current = new Map();
+        this.renderRoot.querySelectorAll('[part="row"]').forEach((el) => {
+            const key = el.dataset.rowKey;
+            if (key !== undefined)
+                current.set(key, el);
+        });
+        for (const [key, el] of this.observedRows) {
+            if (current.get(key) !== el) {
+                ro.unobserve(el);
+                this.observedRows.delete(key);
+            }
+        }
+        for (const [key, el] of current) {
+            if (!this.observedRows.has(key)) {
+                this.observedRows.set(key, el);
+                ro.observe(el);
+            }
+        }
+    }
+    scrollActiveIntoView() {
+        if (!this.activeId)
+            return;
+        const index = this.items.findIndex((item, i) => String(this.keyOf(item, i)) === this.activeId);
+        if (index < 0)
+            return;
+        const base = this.renderRoot.querySelector('[part="base"]');
+        if (!base)
+            return;
+        const top = this.offsets[index] ?? 0;
+        const bottom = this.offsets[index + 1] ?? top;
+        const viewTop = base.scrollTop;
+        const viewBottom = viewTop + base.clientHeight;
+        let target = null;
+        if (top < viewTop)
+            target = top;
+        else if (bottom > viewBottom)
+            target = bottom - base.clientHeight;
+        if (target === null)
+            return;
+        base.scrollTo({ top: Math.max(0, target), behavior: prefersReducedMotion() ? 'auto' : 'smooth' });
+    }
+    emitRangeChangeIfNeeded() {
+        if (this.visibleEnd < this.visibleStart)
+            return;
+        if (this.visibleStart === this.lastEmittedStart && this.visibleEnd === this.lastEmittedEnd)
+            return;
+        this.lastEmittedStart = this.visibleStart;
+        this.lastEmittedEnd = this.visibleEnd;
+        this.emit('lyra-visible-range-changed', {
+            start: this.visibleStart,
+            end: this.visibleEnd,
+        });
+    }
+    maybeFireLoadMore() {
+        const n = this.items.length;
+        const nearBottom = n > 0 && this.visibleEnd >= n - 1;
+        if (!nearBottom) {
+            this.loadMoreArmed = true;
+            return;
+        }
+        if (!this.hasMore || this.loading || !this.loadMoreArmed)
+            return;
+        this.loadMoreArmed = false;
+        this.emit('lyra-load-more');
+    }
+    renderRow(item, index, total) {
+        const key = String(this.keyOf(item, index));
+        const top = this.offsets[index] ?? 0;
+        const isActive = this.activeId !== '' && key === this.activeId;
+        return html `
+      <div
+        part="row"
+        role="listitem"
+        data-row-key=${key}
+        aria-setsize=${total}
+        aria-posinset=${index + 1}
+        aria-current=${isActive ? 'true' : nothing}
+        style=${styleMap({ transform: `translateY(${top}px)` })}
+      >
+        ${this.renderItem(item, index)}
+      </div>
+    `;
+    }
+    render() {
+        const n = this.items.length;
+        const totalHeight = this.offsets[n] ?? 0;
+        const windowed = [];
+        for (let i = this.renderStart; i <= this.renderEnd; i++) {
+            windowed.push({ item: this.items[i], index: i });
+        }
+        return html `
+      <div part="base" role="list" tabindex="0" aria-busy=${this.loading ? 'true' : nothing}>
+        <div part="spacer" style=${styleMap({ height: `${totalHeight}px` })}>
+          ${repeat(windowed, (w) => this.keyOf(w.item, w.index), (w) => this.renderRow(w.item, w.index, n))}
+        </div>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property({ attribute: false })
+], LyraVirtualList.prototype, "items", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraVirtualList.prototype, "renderItem", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraVirtualList.prototype, "keyFunction", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraVirtualList.prototype, "groups", void 0);
+__decorate([
+    property({ attribute: 'row-height' })
+], LyraVirtualList.prototype, "rowHeight", void 0);
+__decorate([
+    property({ type: Number })
+], LyraVirtualList.prototype, "overscan", void 0);
+__decorate([
+    property({ attribute: 'active-id' })
+], LyraVirtualList.prototype, "activeId", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], LyraVirtualList.prototype, "loading", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'has-more', reflect: true })
+], LyraVirtualList.prototype, "hasMore", void 0);
+__decorate([
+    state()
+], LyraVirtualList.prototype, "containerScrollTop", void 0);
+__decorate([
+    state()
+], LyraVirtualList.prototype, "viewportHeight", void 0);
+defineElement('virtual-list', LyraVirtualList);

package/dist/components/virtual-list/virtual-list.styles.d.ts

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

package/dist/components/virtual-list/virtual-list.styles.js

@@ -0,0 +1,44 @@
+import { css } from 'lit';
+export const styles = css `
+  :host {
+    display: block;
+    /* Consumer-tunable viewport height, same pattern as --lyra-chart-height --
+       a virtualized list is meaningless without a bounded scroll extent, so
+       this ships a sane default rather than collapsing to 0 when a caller
+       forgets to size the host. */
+    --lyra-virtual-list-height: 24rem;
+  }
+  [part='base'] {
+    position: relative;
+    block-size: var(--lyra-virtual-list-height);
+    overflow-x: hidden;
+    overflow-y: auto;
+    /* A fast fling shouldn't also scroll the page behind this list once it
+       hits either end. */
+    overscroll-behavior: contain;
+  }
+  [part='base']:focus-visible {
+    outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
+    /* Negative (inward) so the ring isn't clipped by this element's own
+       overflow:auto -- an outward ring (every other component's convention)
+       would otherwise be cut off along the scrolling edges. */
+    outline-offset: calc(-1 * var(--lyra-focus-ring-offset));
+  }
+  [part='spacer'] {
+    position: relative;
+    inline-size: 100%;
+  }
+  [part='row'] {
+    position: absolute;
+    inset-inline-start: 0;
+    inset-block-start: 0;
+    inline-size: 100%;
+    box-sizing: border-box;
+    /* Every row's position updates via this transform on every scroll-driven
+       re-render -- hinting the compositor avoids a full repaint per frame. */
+    will-change: transform;
+  }
+  :host([loading]) [part='base'] {
+    cursor: progress;
+  }
+`;

package/dist/components/word-cloud/word-cloud-layout.js

@@ -9,6 +9,18 @@ const RADIUS_STEP_PER_RADIAN = 3;
  *  generous enough that only a pathological input (e.g. one giant word
  *  repeated many times) ever exhausts it. */
 const MAX_RADIUS_AREA_FACTOR = 6;
+/** Fallback used by `resolveFontSizeBounds()` for any non-finite/non-positive
+ *  `minFontSize`/`maxFontSize` input. */
+const MIN_SANE_FONT_SIZE = 1;
+/** Normalizes possibly-invalid minFontSize/maxFontSize into a finite,
+ *  positive, correctly-ordered pair — non-finite/negative inputs fall back
+ *  to MIN_SANE_FONT_SIZE, and a reversed pair (max < min) is swapped rather
+ *  than left to invert the weight-to-size mapping. */
+function resolveFontSizeBounds(minFontSize, maxFontSize) {
+    const min = Number.isFinite(minFontSize) && minFontSize > 0 ? minFontSize : MIN_SANE_FONT_SIZE;
+    const max = Number.isFinite(maxFontSize) && maxFontSize > 0 ? maxFontSize : MIN_SANE_FONT_SIZE;
+    return min <= max ? [min, max] : [max, min];
+}
 /** Clamps a (possibly negative/non-finite) input weight for scale math only —
  *  never fed back to callers, who should still see their own original `weight`. */
 function effectiveWeight(weight) {
@@ -29,7 +41,8 @@ function rectsOverlap(ax, ay, aw, ah, bx, by, bw, bh) {
  * any word already placed). Deterministic given a deterministic `random`.
  */
 export function layoutWordCloud(words, options) {
-    const { minFontSize, maxFontSize, scale, orientations, measureText } = options;
+    const { scale, orientations, measureText } = options;
+    const [minFontSize, maxFontSize] = resolveFontSizeBounds(options.minFontSize, options.maxFontSize);
     const random = options.random ?? Math.random;
     const skipped = [];
     const decorated = words

package/dist/components/word-cloud/word-cloud.d.ts

@@ -50,6 +50,12 @@ export declare class LyraWordCloud extends LyraElement {
      *  independent of the weight-sorted placement order. */
     private navOrder;
     protected willUpdate(changed: PropertyValues): void;
+    private relayout;
+    /** Forces a relayout so the font-family theme token (`--lyra-font`) is
+     *  re-read from computed style — mirrors `lyra-chart`'s `refreshTheme()`.
+     *  No global theme-broadcast event exists in lyra-ui to subscribe to
+     *  automatically; call this from a consumer's own theme-toggle handler. */
+    refreshTheme(): void;
     private activate;
     private announce;
     private onWordClick;

package/dist/components/word-cloud/word-cloud.js

@@ -150,22 +150,33 @@ export class LyraWordCloud extends LyraElement {
             changed.has('maxFontSize') ||
             changed.has('scale') ||
             changed.has('orientations')) {
-            this.cachedLayout = layoutWordCloud(this.words, {
-                minFontSize: this.minFontSize,
-                maxFontSize: this.maxFontSize,
-                scale: this.scale,
-                orientations: this.orientations,
-                measureText: this.measureText,
-            });
-            if (this.cachedLayout.skipped.length > 0)
-                warnSkippedWords(this.cachedLayout.skipped.length);
-            // The previous focus cursor may no longer address a real word once the
-            // data changes out from under it.
-            this.focusedIndex = null;
-            this.liveText = '';
+            this.relayout();
         }
         this.setAttribute('role', 'group');
-        this.setAttribute('aria-label', `Word cloud of ${this.words.length} word${this.words.length === 1 ? '' : 's'}`);
+        this.setAttribute('aria-label', `Word cloud of ${this.cachedLayout.placed.length} word${this.cachedLayout.placed.length === 1 ? '' : 's'}`);
+    }
+    relayout() {
+        this.cachedLayout = layoutWordCloud(this.words, {
+            minFontSize: this.minFontSize,
+            maxFontSize: this.maxFontSize,
+            scale: this.scale,
+            orientations: this.orientations,
+            measureText: this.measureText,
+        });
+        if (this.cachedLayout.skipped.length > 0)
+            warnSkippedWords(this.cachedLayout.skipped.length);
+        // The previous focus cursor may no longer address a real word once the
+        // data changes out from under it.
+        this.focusedIndex = null;
+        this.liveText = '';
+    }
+    /** Forces a relayout so the font-family theme token (`--lyra-font`) is
+     *  re-read from computed style — mirrors `lyra-chart`'s `refreshTheme()`.
+     *  No global theme-broadcast event exists in lyra-ui to subscribe to
+     *  automatically; call this from a consumer's own theme-toggle handler. */
+    refreshTheme() {
+        this.relayout();
+        this.requestUpdate();
     }
     activate(word) {
         this.emit('lyra-word-click', { text: word.text, weight: word.weight, group: word.group });

package/dist/components/word-cloud/word-cloud.styles.js

@@ -37,10 +37,11 @@ export const styles = css `
     font-weight: 600;
     text-anchor: middle;
     dominant-baseline: middle;
-    transition: opacity var(--lyra-transition-fast);
+    transition: text-decoration-color var(--lyra-transition-fast);
+    text-decoration: underline transparent;
   }
   [part='word']:hover {
-    opacity: 0.75;
+    text-decoration-color: currentColor;
   }
   [part='focus-ring'] {
     fill: none;

package/dist/internal/announcer.d.ts

@@ -0,0 +1,57 @@
+/** Options for a single `Announcer.announce()` call. */
+export interface AnnounceOptions {
+    /** Bypass any in-progress throttle window and flush this text immediately. */
+    force?: boolean;
+}
+export interface AnnouncerOptions {
+    /** Throttle window in ms. Repeated `announce()` calls arriving within this
+     *  window of the first call in a burst collapse to one trailing-edge flush
+     *  of the latest text. Defaults to 500. */
+    throttleMs?: number;
+    /** Invoked with the coalesced text whenever a burst flushes (on the
+     *  trailing edge, or immediately for a `{ force: true }` call). */
+    onFlush: (text: string) => void;
+}
+/**
+ * Trailing-edge debounce/coalesce for screen-reader announcements.
+ *
+ * Streaming UIs (token-by-token chat responses, progress ticks, etc.)
+ * naturally produce far more candidate announcements than a screen-reader
+ * user can usefully absorb — reading every incremental chunk aloud is spam,
+ * not information. `Announcer` collapses a burst of `announce()` calls
+ * arriving within `throttleMs` of the *first* call in that burst down to a
+ * single flush of the latest text: superseded intermediate text is dropped
+ * outright, never queued or concatenated. Passing `{ force: true }` always
+ * flushes immediately regardless of any window in progress, so a final or
+ * terminal message (e.g. "response complete") is never swallowed mid-burst.
+ *
+ * This is pure timing/state logic with no DOM dependency — it knows nothing
+ * about ARIA, elements, or Lit. `<lyra-live-region>`
+ * (`../components/live-region/live-region.js`) is the DOM-facing wrapper
+ * that composes one of these with an actual live-region element. Other
+ * components that need throttled announcements (a stream-status indicator,
+ * a tool-call chip's status transitions, a chat message's streaming state)
+ * should reuse that wrapper rather than instantiating `Announcer` directly.
+ */
+export declare class Announcer {
+    /** Throttle window in ms. Safe to change between bursts; a flush already
+     *  scheduled keeps the deadline it was scheduled with. */
+    throttleMs: number;
+    private readonly onFlush;
+    private timer?;
+    private pending?;
+    constructor(options: AnnouncerOptions);
+    /** The latest text awaiting flush, if a burst is currently in progress. */
+    get pendingText(): string | undefined;
+    /** Whether a flush is currently scheduled (a burst is in progress). */
+    get isPending(): boolean;
+    /**
+     * Queue `text` for announcement. Within a single throttle window, only the
+     * latest text queued survives — this call always overwrites whatever an
+     * earlier call in the same burst queued.
+     */
+    announce(text: string, options?: AnnounceOptions): void;
+    /** Cancel any pending (not yet flushed) announcement without flushing it. */
+    cancel(): void;
+    private flush;
+}