@aceshooting/lyra-ui 1.1.0 → 2.0.0

package/dist/components/tree/tree-node.js

@@ -8,7 +8,7 @@ import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { LyraElement } from '../../internal/lyra-element.js';
-import { defineElement } from '../../internal/prefix.js';
+import { defineElement, tag } from '../../internal/prefix.js';
 import { chevronIcon } from '../../internal/icons.js';
 import { css } from 'lit';
 import { cascadeUpdateComplete } from './update-cascade.js';
@@ -89,7 +89,7 @@ const styles = css `
  *
  * @customElement lyra-tree-node
  * @event lyra-node-toggle - `detail: { id, expanded }`, fired when this node is expanded or collapsed (via `expand()`/`collapse()`, the toggle button, or ArrowRight/ArrowLeft).
- * @event lyra-node-select - `detail: { id }`, fired when this node's primary action is activated (via `select()`, clicking its label, or Enter/Space).
+ * @event lyra-node-select - `detail: { id }`, fired when this node's primary action is activated (via `select()`, clicking anywhere in its row, or Enter/Space).
  * @csspart row, toggle, label, badge
  */
 export class LyraTreeNode extends LyraElement {
@@ -145,19 +145,29 @@ export class LyraTreeNode extends LyraElement {
         this.expanded = false;
         this.emit('lyra-node-toggle', { id: this.item.id, expanded: false });
     }
-    /** Fire this item's primary "select" action (Enter/Space, or clicking the label). */
+    /**
+     * Fire this item's primary "select" action (Enter/Space, or clicking
+     * anywhere in the row). Emits *before* calling `.focus()`: `<lyra-tree>`'s
+     * `onNodeActivate` listener for `lyra-node-select` runs synchronously
+     * (native `dispatchEvent` is sync) and updates `activeId`, which pushes
+     * `tabIndex = 0` down onto this node via its own render -- calling
+     * `.focus()` after that emit, rather than before, means real DOM focus
+     * lands correctly the very first time a previously-inactive node is
+     * clicked, not one render late.
+     */
     select() {
         this.emit('lyra-node-select', { id: this.item.id });
+        this.focus();
     }
     /** See `cascadeUpdateComplete` and the matching override on `<lyra-tree>`. */
     async getUpdateComplete() {
         const result = await super.getUpdateComplete();
-        await cascadeUpdateComplete(this.shadowRoot?.querySelectorAll('lyra-tree-node') ?? []);
+        await cascadeUpdateComplete([...(this.shadowRoot?.querySelectorAll(tag('tree-node')) ?? [])]);
         return result;
     }
     render() {
         return html `
-      <div part="row" style=${`--lyra-tree-depth:${this.depth}`}>
+      <div part="row" style=${`--lyra-tree-depth:${this.depth}`} @click=${() => this.select()}>
         <button
           part="toggle"
           type="button"
@@ -172,7 +182,7 @@ export class LyraTreeNode extends LyraElement {
         >
           ${this.hasChildren ? chevronIcon() : nothing}
         </button>
-        <span part="label" @click=${() => this.select()}>${this.item.label}</span>
+        <span part="label">${this.item.label}</span>
         ${this.item.badge != null ? html `<span part="badge">${this.item.badge}</span>` : nothing}
       </div>
       ${this.expanded && this.hasChildren

package/dist/components/tree/tree.d.ts

@@ -94,8 +94,14 @@ export declare class LyraTree extends LyraElement {
      */
     protected getUpdateComplete(): Promise<boolean>;
     private onTreeKeyDown;
-    /** Expand every node in the tree, recursively. */
-    expandAll(): void;
+    /**
+     * Expand every node in the tree, recursively. Resolves once every
+     * descendant has actually finished expanding (not just had `expanded` set)
+     * -- callers that immediately read `visibleNodeElements()`-derived state
+     * (or call `collapseAll()` right after) should `await` this instead of
+     * firing it and moving on.
+     */
+    expandAll(): Promise<void>;
     /**
      * Collapse every node in the tree, recursively. Goes through each node's
      * own `collapse()` (rather than assigning `expanded` directly) so its

package/dist/components/tree/tree.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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 { defineElement, tag } from '../../internal/prefix.js';
 import { isRtl } from '../../internal/rtl.js';
 import { styles } from './tree.styles.js';
 import { cascadeUpdateComplete } from './update-cascade.js';
@@ -133,10 +133,10 @@ export class LyraTree extends LyraElement {
     }
     static { this.styles = [LyraElement.styles, styles]; }
     get nodeElements() {
-        return [...this.querySelectorAll('lyra-tree-node')];
+        return [...this.querySelectorAll(tag('tree-node'))];
     }
     childrenOf(node) {
-        return [...(node.shadowRoot?.querySelectorAll('lyra-tree-node') ?? [])];
+        return [...(node.shadowRoot?.querySelectorAll(tag('tree-node')) ?? [])];
     }
     invalidateVisibleCache() {
         this.cachedVisible = null;
@@ -206,7 +206,7 @@ export class LyraTree extends LyraElement {
         let previousSibling = null;
         for (const item of this.data) {
             const reused = !seen.has(item.id) ? existingById.get(item.id) : undefined;
-            const node = reused ?? document.createElement('lyra-tree-node');
+            const node = reused ?? document.createElement(tag('tree-node'));
             node.item = item;
             node.depth = 0;
             seen.add(item.id);
@@ -263,16 +263,23 @@ export class LyraTree extends LyraElement {
         }
         return result;
     }
-    /** Expand every node in the tree, recursively. */
-    expandAll() {
-        const setAll = (nodes) => {
-            for (const n of nodes) {
+    /**
+     * Expand every node in the tree, recursively. Resolves once every
+     * descendant has actually finished expanding (not just had `expanded` set)
+     * -- callers that immediately read `visibleNodeElements()`-derived state
+     * (or call `collapseAll()` right after) should `await` this instead of
+     * firing it and moving on.
+     */
+    async expandAll() {
+        const setAll = async (nodes) => {
+            await Promise.all(nodes.map(async (n) => {
                 n.expanded = true;
                 this.invalidateVisibleCache();
-                void n.updateComplete.then(() => setAll(this.childrenOf(n)));
-            }
+                await n.updateComplete;
+                await setAll(this.childrenOf(n));
+            }));
         };
-        setAll(this.nodeElements);
+        await setAll(this.nodeElements);
     }
     /**
      * Collapse every node in the tree, recursively. Goes through each node's

package/dist/components/typing-indicator/typing-indicator.d.ts

@@ -0,0 +1,60 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+export type TypingIndicatorVariant = 'dots' | 'pulse' | 'cursor';
+export type TypingIndicatorSize = 'sm' | 'md';
+/**
+ * `<lyra-typing-indicator>` — a purely presentational "assistant is
+ * responding" presence cue. No events, no interactivity: a consumer mounts
+ * it while a response is being generated and removes it (or hides it) once
+ * real content has arrived.
+ *
+ * Three visual variants share one component rather than three separate tags
+ * because callers pick between them along a single axis — how the
+ * surrounding surface wants the cue to read — and nothing else about the
+ * component differs:
+ * - `dots` (default) — three dots with a staggered bounce, the classic
+ *   "typing…" affordance for a standalone status line.
+ * - `pulse` — a single breathing dot, a quieter cue for a tighter space
+ *   (e.g. next to an avatar).
+ * - `cursor` — a blinking vertical bar, meant to sit inline at the tail end
+ *   of streamed text that is still being appended to.
+ *
+ * Accessibility: this indicator typically mounts and unmounts around a real
+ * generation lifecycle (appears when a response starts, disappears once one
+ * arrives) rather than emitting a stream of updates of its own, so it does
+ * *not* route through `<lyra-live-region>`/`Announcer`
+ * (`../../internal/announcer.js`) — that machinery exists to coalesce many
+ * rapidly-changing announcements into one, and there is only ever a single
+ * announcement here: the mount itself. A plain `role="status"` plus an
+ * accessible name derived from `label` is sufficient, set both as an
+ * `aria-label` on the host *and* as a visually-hidden text node in the
+ * shadow tree, so the name survives even if only one of the two is picked up
+ * by a given assistive-tech/browser pairing. The animated dots/pulse/cursor
+ * shape is `aria-hidden="true"` — it's decorative; `label` is the entire
+ * accessible content, so nothing narrates individual animation frames.
+ *
+ * @customElement lyra-typing-indicator
+ * @csspart base - The decorative (`aria-hidden`) wrapper around the animated shape.
+ * @csspart dot - Each of the three dots in the `dots` variant.
+ * @csspart pulse - The single pulsing dot in the `pulse` variant.
+ * @csspart cursor - The blinking bar in the `cursor` variant.
+ */
+export declare class LyraTypingIndicator extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Which decorative presentation to render. */
+    variant: TypingIndicatorVariant;
+    /** Accessible name, exposed via `role="status"`. Not re-announced on every
+     *  animation frame — only mount (and any later change to this property)
+     *  produces a new announcement. */
+    label: string;
+    /** Compact sizing for dense layouts (e.g. inline with a message bubble). */
+    size: TypingIndicatorSize;
+    protected willUpdate(changed: PropertyValues): void;
+    render(): TemplateResult;
+    private renderShape;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-typing-indicator': LyraTypingIndicator;
+    }
+}

package/dist/components/typing-indicator/typing-indicator.js

@@ -0,0 +1,96 @@
+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 { styles } from './typing-indicator.styles.js';
+/**
+ * `<lyra-typing-indicator>` — a purely presentational "assistant is
+ * responding" presence cue. No events, no interactivity: a consumer mounts
+ * it while a response is being generated and removes it (or hides it) once
+ * real content has arrived.
+ *
+ * Three visual variants share one component rather than three separate tags
+ * because callers pick between them along a single axis — how the
+ * surrounding surface wants the cue to read — and nothing else about the
+ * component differs:
+ * - `dots` (default) — three dots with a staggered bounce, the classic
+ *   "typing…" affordance for a standalone status line.
+ * - `pulse` — a single breathing dot, a quieter cue for a tighter space
+ *   (e.g. next to an avatar).
+ * - `cursor` — a blinking vertical bar, meant to sit inline at the tail end
+ *   of streamed text that is still being appended to.
+ *
+ * Accessibility: this indicator typically mounts and unmounts around a real
+ * generation lifecycle (appears when a response starts, disappears once one
+ * arrives) rather than emitting a stream of updates of its own, so it does
+ * *not* route through `<lyra-live-region>`/`Announcer`
+ * (`../../internal/announcer.js`) — that machinery exists to coalesce many
+ * rapidly-changing announcements into one, and there is only ever a single
+ * announcement here: the mount itself. A plain `role="status"` plus an
+ * accessible name derived from `label` is sufficient, set both as an
+ * `aria-label` on the host *and* as a visually-hidden text node in the
+ * shadow tree, so the name survives even if only one of the two is picked up
+ * by a given assistive-tech/browser pairing. The animated dots/pulse/cursor
+ * shape is `aria-hidden="true"` — it's decorative; `label` is the entire
+ * accessible content, so nothing narrates individual animation frames.
+ *
+ * @customElement lyra-typing-indicator
+ * @csspart base - The decorative (`aria-hidden`) wrapper around the animated shape.
+ * @csspart dot - Each of the three dots in the `dots` variant.
+ * @csspart pulse - The single pulsing dot in the `pulse` variant.
+ * @csspart cursor - The blinking bar in the `cursor` variant.
+ */
+export class LyraTypingIndicator extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Which decorative presentation to render. */
+        this.variant = 'dots';
+        /** Accessible name, exposed via `role="status"`. Not re-announced on every
+         *  animation frame — only mount (and any later change to this property)
+         *  produces a new announcement. */
+        this.label = 'Thinking…';
+        /** Compact sizing for dense layouts (e.g. inline with a message bubble). */
+        this.size = 'md';
+    }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    willUpdate(changed) {
+        this.setAttribute('role', 'status');
+        if (changed.has('label')) {
+            this.setAttribute('aria-label', this.label);
+        }
+    }
+    render() {
+        return html `
+      <span part="base" aria-hidden="true">${this.renderShape()}</span>
+      <span class="sr-only">${this.label}</span>
+    `;
+    }
+    renderShape() {
+        switch (this.variant) {
+            case 'pulse':
+                return html `<span part="pulse"></span>`;
+            case 'cursor':
+                return html `<span part="cursor"></span>`;
+            case 'dots':
+            default:
+                return html `<span part="dot"></span><span part="dot"></span><span part="dot"></span>`;
+        }
+    }
+}
+__decorate([
+    property({ reflect: true })
+], LyraTypingIndicator.prototype, "variant", void 0);
+__decorate([
+    property()
+], LyraTypingIndicator.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraTypingIndicator.prototype, "size", void 0);
+defineElement('typing-indicator', LyraTypingIndicator);

package/dist/components/typing-indicator/typing-indicator.styles.d.ts

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

package/dist/components/typing-indicator/typing-indicator.styles.js

@@ -0,0 +1,132 @@
+import { css } from 'lit';
+// `--lyra-transition-base` is used (rather than `--lyra-transition-fast`) as
+// the animation-cycle length for every variant below: it's the token the
+// rest of the library reserves for slightly-more-noticeable motion (gauge
+// fill, dialog/popover open), whereas `-fast` is reserved for snappy
+// discrete state flips (checkbox check, switch thumb). A continuous ambient
+// loop reads calmer at the longer of the two. Note this token is a *compound*
+// value (`180ms ease-out`, duration + timing-function together, exactly like
+// every `transition:` shorthand elsewhere in this library) so it can only
+// ever be spliced into the `animation:` *shorthand* below, never assigned to
+// `animation-duration` alone -- that longhand requires a bare `<time>` and
+// would silently invalidate (collapsing the duration to 0) if given the
+// compound value. For the same reason no extra timing-function keyword can
+// follow it in the shorthand: the token already supplies one.
+export const styles = css `
+  :host {
+    display: inline-flex;
+    align-items: center;
+    vertical-align: middle;
+    line-height: 1;
+    --lyra-typing-dot-size: 0.5rem;
+    --lyra-typing-gap: 0.25rem;
+    --lyra-typing-cursor-width: 0.125rem;
+    --lyra-typing-cursor-height: 1em;
+  }
+  :host([size='sm']) {
+    --lyra-typing-dot-size: 0.375rem;
+    --lyra-typing-gap: 0.1875rem;
+    --lyra-typing-cursor-width: 0.09375rem;
+  }
+
+  [part='base'] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lyra-typing-gap);
+  }
+
+  /* -- dots -------------------------------------------------------------- */
+  [part='dot'] {
+    inline-size: var(--lyra-typing-dot-size);
+    block-size: var(--lyra-typing-dot-size);
+    border-radius: 50%;
+    background: currentColor;
+    opacity: 0.5;
+    animation: lyra-typing-dot-bounce var(--lyra-transition-base) infinite;
+  }
+  /* Fixed (not token-derived) stagger offsets -- --lyra-transition-base is
+     a compound "duration timing-function" value like every other transition
+     token in this library, so it can't be decomposed via calc() to derive a
+     fraction of just its duration; these two delays approximate a third and
+     two-thirds of that token's own fallback duration. */
+  [part='dot']:nth-child(2) {
+    animation-delay: 60ms;
+  }
+  [part='dot']:nth-child(3) {
+    animation-delay: 120ms;
+  }
+  @keyframes lyra-typing-dot-bounce {
+    0%,
+    80%,
+    100% {
+      transform: translateY(0);
+      opacity: 0.5;
+    }
+    40% {
+      transform: translateY(-35%);
+      opacity: 1;
+    }
+  }
+
+  /* -- pulse --------------------------------------------------------------
+     A single breathing dot, meant for tighter spaces than three dots allow. */
+  [part='pulse'] {
+    inline-size: var(--lyra-typing-dot-size);
+    block-size: var(--lyra-typing-dot-size);
+    border-radius: 50%;
+    background: currentColor;
+    opacity: 1;
+    transform: scale(1);
+    animation: lyra-typing-pulse var(--lyra-transition-base) infinite;
+  }
+  @keyframes lyra-typing-pulse {
+    0%,
+    100% {
+      transform: scale(0.85);
+      opacity: 0.55;
+    }
+    50% {
+      transform: scale(1);
+      opacity: 1;
+    }
+  }
+
+  /* -- cursor -------------------------------------------------------------
+     A blinking vertical bar for inline placement at the tail of streamed
+     text. The two adjacent keyframe stops (49% / 50%) hold identical values
+     either side of an instant flip, so the blink still reads as a sharp
+     on/off even though the token's ease-out timing-function is in effect
+     across the whole animation. */
+  [part='cursor'] {
+    inline-size: var(--lyra-typing-cursor-width);
+    block-size: var(--lyra-typing-cursor-height);
+    background: currentColor;
+    border-radius: var(--lyra-typing-cursor-width);
+    opacity: 1;
+    animation: lyra-typing-cursor-blink var(--lyra-transition-base) infinite;
+  }
+  @keyframes lyra-typing-cursor-blink {
+    0%,
+    49% {
+      opacity: 1;
+    }
+    50%,
+    100% {
+      opacity: 0;
+    }
+  }
+
+  /* Every variant collapses to its plain, fully-visible resting state
+     under reduced motion -- never a static mid-animation frame (e.g. a
+     permanently-invisible cursor, had the blink's "off" half been frozen
+     instead). */
+  @media (prefers-reduced-motion: reduce) {
+    [part='dot'],
+    [part='pulse'],
+    [part='cursor'] {
+      animation: none !important;
+      opacity: 1;
+      transform: none;
+    }
+  }
+`;

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

@@ -0,0 +1,173 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+/** `lyra-visible-range-changed` detail -- the current visible (non-overscanned) item index range. */
+export interface VirtualListRange {
+    start: number;
+    end: number;
+}
+/** Placeholder for a later phase's sticky-header sectioning feature -- see the class doc. */
+export interface VirtualListGroup {
+    key: string | number;
+    label?: string;
+    startIndex: number;
+}
+/**
+ * `<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 declare class LyraVirtualList extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** The full (non-windowed) item collection. */
+    items: unknown[];
+    /** Renders one row's content — typically returns a `lit-html` `TemplateResult`. */
+    renderItem: (item: unknown, index: number) => unknown;
+    /** Derives a row's stable `repeat()` key. Falls back to the item's index
+     *  in `items` when omitted, which is only a safe identity while `items`
+     *  never reorders/inserts/removes — provide this whenever it can, or
+     *  scroll position and any per-row DOM state can attach to the wrong row
+     *  across a mutation (same caveat as `<lyra-table>`'s `rowKey`). */
+    keyFunction?: (item: unknown, index: number) => string | number;
+    /** Reserved for a later phase's sticky-header sectioning — accepted but not yet rendered. See the class doc. */
+    groups?: VirtualListGroup[];
+    /** `'auto'` (default) measures each row's real height via `ResizeObserver`;
+     *  a numeric string fixes every row to that many pixels. */
+    rowHeight: string;
+    /** Extra rows rendered beyond the visible viewport on each side, to reduce blank-frame risk during fast scrolling. */
+    overscan: number;
+    /** When set and it matches a row's `keyFunction` result, that row is smoothly scrolled into view whenever this changes. */
+    activeId: string;
+    loading: boolean;
+    /** When true, scrolling near the bottom fires `lyra-load-more`. */
+    hasMore: boolean;
+    private containerScrollTop;
+    private viewportHeight;
+    /** `offsets[i]` = row `i`'s pixel top; `offsets[items.length]` = total content height. Rebuilt every update. */
+    private offsets;
+    /** Parsed `rowHeight`: a positive pixel number, or `null` for `'auto'` (measured) mode. */
+    private fixedRowHeight;
+    /** `row-height="auto"` per-row measured heights, keyed by `String(keyFunction(item, index))`. */
+    private readonly measuredHeights;
+    private renderStart;
+    private renderEnd;
+    private visibleStart;
+    private visibleEnd;
+    private lastEmittedStart;
+    private lastEmittedEnd;
+    /** Re-armed whenever the window moves away from the end of `items` -- see the `lyra-load-more` event doc. */
+    private loadMoreArmed;
+    private isFirstUpdate;
+    private rowResizeObserver?;
+    private containerResizeObserver?;
+    private readonly observedRows;
+    private scrollRafId?;
+    private pendingScrollTop;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    private parseRowHeight;
+    private keyOf;
+    private recomputeOffsets;
+    /** First item index whose bottom edge is at/after `offset`. */
+    private findIndexAtOrAfter;
+    /** Last item index whose top edge is at/before `offset`. */
+    private findIndexAtOrBefore;
+    private computeRange;
+    private attachContainerListeners;
+    private onScroll;
+    private onRowsResized;
+    /** 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. */
+    private syncRowObservers;
+    private scrollActiveIntoView;
+    private emitRangeChangeIfNeeded;
+    private maybeFireLoadMore;
+    private renderRow;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-virtual-list': LyraVirtualList;
+    }
+}