@aceshooting/lyra-ui 2.0.0 → 2.1.0

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

@@ -1,22 +1,26 @@
 import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
+/** Largest accepted overscan on either side of the visible range. This keeps
+ *  an accidental huge value from defeating virtualization. */
+export declare const MAX_OVERSCAN_ROWS = 100;
 /** `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. */
+/** A visible group label anchored to the first row in its group. */
 export interface VirtualListGroup {
     key: string | number;
     label?: string;
     startIndex: number;
 }
+type VirtualListKey = string | 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.
+ * multi-thousand-row chat history sidebar or 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
@@ -46,12 +50,18 @@ export interface VirtualListGroup {
  *   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.
+ * The `offsets` array is rebuilt only when `items`, `row-height`, or
+ * `keyFunction` change, or a row's measured height changes -- not on every
+ * update, so a pure scroll-position tick (potentially every rAF while
+ * scrolling) only re-runs the cheap range/visibility math in
+ * `computeRange()`, never the `O(n)` offsets rebuild (which, in
+ * `row-height="auto"` mode, also means a `keyFunction` call per item). For
+ * the list sizes this component is meant for (a scrollable history sidebar,
+ * realistically hundreds to a few thousand rows) that rebuild is a trivial
+ * `O(n)` arithmetic loop even when it does run; 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
@@ -70,10 +80,10 @@ export interface VirtualListGroup {
  * 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.
+ * **Grouping.** When supplied, `groups` renders a labeled group marker at the
+ * corresponding `startIndex`. Group markers are positioned independently of
+ * the row window, so they remain available when the first row in a group is
+ * outside the current overscanned range.
  *
  * @customElement lyra-virtual-list
  * @event lyra-load-more - Fired once per approach to the bottom of the list
@@ -90,6 +100,7 @@ export interface VirtualListGroup {
  * @csspart base - The scrollable container (`role="list"`).
  * @csspart spacer - The full-content-height inner element that gives the
  *   container its true scrollable extent.
+ * @csspart group - A positioned group label.
  * @csspart row - One rendered row's absolutely-positioned wrapper
  *   (`role="listitem"`); `renderItem`'s return value renders inside it.
  */
@@ -105,26 +116,48 @@ export declare class LyraVirtualList extends LyraElement {
      *  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. */
+    /** Group labels positioned at their first row's `startIndex`. Invalid or
+     * duplicate indexes are ignored during rendering. */
     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. */
+    /** Extra rows rendered beyond the visible viewport on each side, to reduce
+     *  blank-frame risk during fast scrolling. Normalized to a whole number in
+     *  the inclusive range 0–`MAX_OVERSCAN_ROWS`; non-finite values use the
+     *  default. */
     overscan: number;
-    /** When set and it matches a row's `keyFunction` result, that row is smoothly scrolled into view whenever this changes. */
-    activeId: string;
+    /** When set and it matches a row's typed `keyFunction` result, that row is
+     * smoothly scrolled into view whenever this changes. Attribute values are
+     * strings; assign the property for a numeric key. */
+    activeId: VirtualListKey | '';
     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. */
+    /** `offsets[i]` = row `i`'s pixel top; `offsets[items.length]` = total content height. Rebuilt only when `offsetsDirty` is set -- see `willUpdate()`. */
     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))`. */
+    /** `row-height="auto"` per-row measured heights, keyed by
+     *  keyFunction result. Pruned to the current `items`'
+     *  live keys whenever `items` changes (see `recomputeOffsets()`), so a
+     *  long-lived instance handed many wholly different `items` arrays over
+     *  its life doesn't grow this map without bound. */
     private readonly measuredHeights;
+    /** True whenever `offsets` needs rebuilding before the next render --
+     *  set initially and whenever `items`/`rowHeight`/`keyFunction` change or
+     *  a row's measured height changes, but *not* on a pure scroll-position
+     *  update, so the `O(n)` rebuild (including a `keyFunction` call per item
+     *  in `row-height="auto"` mode) only runs when something that actually
+     *  affects row heights or ordering changed. */
+    private offsetsDirty;
+    /** Set alongside `offsetsDirty` specifically when `items` changed (not
+     *  just `rowHeight`/`keyFunction`/a measurement) -- consumed by the next
+     *  `recomputeOffsets()` call to prune `measuredHeights` entries for keys
+     *  no longer present in `items`. */
+    private itemsChangedPendingPrune;
     private renderStart;
     private renderEnd;
     private visibleStart;
@@ -137,6 +170,8 @@ export declare class LyraVirtualList extends LyraElement {
     private rowResizeObserver?;
     private containerResizeObserver?;
     private readonly observedRows;
+    private readonly observedRowKeys;
+    private readonly observedRowIndices;
     private scrollRafId?;
     private pendingScrollTop;
     connectedCallback(): void;
@@ -164,6 +199,7 @@ export declare class LyraVirtualList extends LyraElement {
     private emitRangeChangeIfNeeded;
     private maybeFireLoadMore;
     private renderRow;
+    private renderGroups;
     render(): TemplateResult;
 }
 declare global {
@@ -171,3 +207,4 @@ declare global {
         'lyra-virtual-list': LyraVirtualList;
     }
 }
+export {};

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

@@ -16,15 +16,43 @@ import { styles } from './virtual-list.styles.js';
  *  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;
+const DEFAULT_OVERSCAN_ROWS = 6;
+/** Largest accepted overscan on either side of the visible range. This keeps
+ *  an accidental huge value from defeating virtualization. */
+export const MAX_OVERSCAN_ROWS = 100;
+function normalizeOverscan(value) {
+    if (value === null)
+        return DEFAULT_OVERSCAN_ROWS;
+    const numeric = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(numeric))
+        return DEFAULT_OVERSCAN_ROWS;
+    return Math.min(MAX_OVERSCAN_ROWS, Math.max(0, Math.floor(numeric)));
+}
+const overscanConverter = {
+    fromAttribute(value) {
+        return normalizeOverscan(value);
+    },
+};
 function prefersReducedMotion() {
     return typeof window !== 'undefined' && !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
 }
+/** A typed key is used in maps and active-row matching; this token is only for
+ * DOM attributes, where every value is necessarily a string. */
+function domKeyToken(key) {
+    if (typeof key === 'number') {
+        if (Number.isNaN(key))
+            return 'number:NaN';
+        if (Object.is(key, -0))
+            return 'number:-0';
+    }
+    return `${typeof key}:${String(key)}`;
+}
 /**
  * `<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.
+ * multi-thousand-row chat history sidebar or 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
@@ -54,12 +82,18 @@ function prefersReducedMotion() {
  *   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.
+ * The `offsets` array is rebuilt only when `items`, `row-height`, or
+ * `keyFunction` change, or a row's measured height changes -- not on every
+ * update, so a pure scroll-position tick (potentially every rAF while
+ * scrolling) only re-runs the cheap range/visibility math in
+ * `computeRange()`, never the `O(n)` offsets rebuild (which, in
+ * `row-height="auto"` mode, also means a `keyFunction` call per item). For
+ * the list sizes this component is meant for (a scrollable history sidebar,
+ * realistically hundreds to a few thousand rows) that rebuild is a trivial
+ * `O(n)` arithmetic loop even when it does run; 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
@@ -78,10 +112,10 @@ function prefersReducedMotion() {
  * 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.
+ * **Grouping.** When supplied, `groups` renders a labeled group marker at the
+ * corresponding `startIndex`. Group markers are positioned independently of
+ * the row window, so they remain available when the first row in a group is
+ * outside the current overscanned range.
  *
  * @customElement lyra-virtual-list
  * @event lyra-load-more - Fired once per approach to the bottom of the list
@@ -98,6 +132,7 @@ function prefersReducedMotion() {
  * @csspart base - The scrollable container (`role="list"`).
  * @csspart spacer - The full-content-height inner element that gives the
  *   container its true scrollable extent.
+ * @csspart group - A positioned group label.
  * @csspart row - One rendered row's absolutely-positioned wrapper
  *   (`role="listitem"`); `renderItem`'s return value renders inside it.
  */
@@ -111,9 +146,14 @@ export class LyraVirtualList extends LyraElement {
         /** `'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. */
+        /** Extra rows rendered beyond the visible viewport on each side, to reduce
+         *  blank-frame risk during fast scrolling. Normalized to a whole number in
+         *  the inclusive range 0–`MAX_OVERSCAN_ROWS`; non-finite values use the
+         *  default. */
+        this.overscan = DEFAULT_OVERSCAN_ROWS;
+        /** When set and it matches a row's typed `keyFunction` result, that row is
+         * smoothly scrolled into view whenever this changes. Attribute values are
+         * strings; assign the property for a numeric key. */
         this.activeId = '';
         this.loading = false;
         /** When true, scrolling near the bottom fires `lyra-load-more`. */
@@ -124,12 +164,28 @@ export class LyraVirtualList extends LyraElement {
         // 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. */
+        /** `offsets[i]` = row `i`'s pixel top; `offsets[items.length]` = total content height. Rebuilt only when `offsetsDirty` is set -- see `willUpdate()`. */
         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))`. */
+        /** `row-height="auto"` per-row measured heights, keyed by
+         *  keyFunction result. Pruned to the current `items`'
+         *  live keys whenever `items` changes (see `recomputeOffsets()`), so a
+         *  long-lived instance handed many wholly different `items` arrays over
+         *  its life doesn't grow this map without bound. */
         this.measuredHeights = new Map();
+        /** True whenever `offsets` needs rebuilding before the next render --
+         *  set initially and whenever `items`/`rowHeight`/`keyFunction` change or
+         *  a row's measured height changes, but *not* on a pure scroll-position
+         *  update, so the `O(n)` rebuild (including a `keyFunction` call per item
+         *  in `row-height="auto"` mode) only runs when something that actually
+         *  affects row heights or ordering changed. */
+        this.offsetsDirty = true;
+        /** Set alongside `offsetsDirty` specifically when `items` changed (not
+         *  just `rowHeight`/`keyFunction`/a measurement) -- consumed by the next
+         *  `recomputeOffsets()` call to prune `measuredHeights` entries for keys
+         *  no longer present in `items`. */
+        this.itemsChangedPendingPrune = false;
         this.renderStart = 0;
         this.renderEnd = -1;
         this.visibleStart = 0;
@@ -140,6 +196,8 @@ export class LyraVirtualList extends LyraElement {
         this.loadMoreArmed = true;
         this.isFirstUpdate = true;
         this.observedRows = new Map();
+        this.observedRowKeys = new WeakMap();
+        this.observedRowIndices = new WeakMap();
         this.pendingScrollTop = null;
         this.onScroll = (e) => {
             this.pendingScrollTop = e.currentTarget.scrollTop;
@@ -159,10 +217,15 @@ export class LyraVirtualList extends LyraElement {
         this.onRowsResized = (entries) => {
             if (this.fixedRowHeight != null)
                 return;
+            const base = this.renderRoot.querySelector('[part="base"]');
+            const oldScrollTop = base?.scrollTop ?? this.containerScrollTop;
+            let scrollAdjustment = 0;
             let changed = false;
             for (const entry of entries) {
-                const key = entry.target.dataset.rowKey;
-                if (key === undefined)
+                const row = entry.target;
+                const key = this.observedRowKeys.get(row);
+                const index = this.observedRowIndices.get(row);
+                if (key === undefined || index === undefined)
                     continue;
                 const height = entry.borderBoxSize?.[0]?.blockSize ?? entry.target.getBoundingClientRect().height;
                 const prev = this.measuredHeights.get(key);
@@ -170,11 +233,25 @@ export class LyraVirtualList extends LyraElement {
                 // isn't worth a full offsets rebuild + re-render.
                 if (prev === undefined || Math.abs(prev - height) > 0.5) {
                     this.measuredHeights.set(key, height);
+                    // Keep the first visible row anchored while a row fully above it
+                    // changes size. Otherwise auto-height measurement makes the viewport
+                    // jump as soon as an earlier row is laid out.
+                    const oldHeight = prev ?? DEFAULT_ROW_ESTIMATE_PX;
+                    if (this.offsets[index + 1] <= oldScrollTop)
+                        scrollAdjustment += height - oldHeight;
                     changed = true;
                 }
             }
-            if (changed)
+            if (changed) {
+                if (base && scrollAdjustment !== 0) {
+                    const nextScrollTop = Math.max(0, oldScrollTop + scrollAdjustment);
+                    base.scrollTop = nextScrollTop;
+                    this.containerScrollTop = nextScrollTop;
+                    this.pendingScrollTop = null;
+                }
+                this.offsetsDirty = true;
                 this.requestUpdate();
+            }
         };
     }
     static { this.styles = [LyraElement.styles, styles]; }
@@ -184,9 +261,15 @@ export class LyraVirtualList extends LyraElement {
         // 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)
+        // torn down in disconnectedCallback below. syncRowObservers() is called
+        // directly here (rather than left for the next Lit render) because a
+        // reconnect that doesn't also change some other reactive property never
+        // triggers one, which would otherwise leave every already-rendered row
+        // permanently unwatched by the freshly created ResizeObserver above.
+        if (this.hasUpdated) {
             this.attachContainerListeners();
+            this.syncRowObservers();
+        }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -206,10 +289,21 @@ export class LyraVirtualList extends LyraElement {
     }
     willUpdate(changed) {
         this.isFirstUpdate = !this.hasUpdated;
+        if (changed.has('items') || changed.has('rowHeight') || changed.has('keyFunction')) {
+            this.offsetsDirty = true;
+        }
+        if (changed.has('items')) {
+            this.itemsChangedPendingPrune = true;
+        }
         if (changed.has('rowHeight')) {
             this.fixedRowHeight = this.parseRowHeight(this.rowHeight);
         }
-        this.recomputeOffsets();
+        if (this.offsetsDirty) {
+            this.recomputeOffsets();
+            this.offsetsDirty = false;
+        }
+        // Always cheap: just arithmetic over the already-current offsets +
+        // scroll/viewport state, so this runs on a pure scroll-driven update too.
         this.computeRange();
     }
     updated(changed) {
@@ -230,19 +324,40 @@ export class LyraVirtualList extends LyraElement {
         return Number.isFinite(n) && n > 0 ? n : null;
     }
     keyOf(item, index) {
-        return this.keyFunction ? this.keyFunction(item, index) : index;
+        const key = this.keyFunction ? this.keyFunction(item, index) : index;
+        return typeof key === 'string' || typeof key === 'number' ? key : index;
     }
     recomputeOffsets() {
         const n = this.items.length;
         const offsets = new Array(n + 1);
         offsets[0] = 0;
+        // Only build the live-keys set (and only when in row-height="auto" mode,
+        // where measuredHeights is actually populated) when items itself changed
+        // -- a measurement-only or rowHeight/keyFunction-only recompute has no
+        // stale entries to prune, so skipping this keeps those cases as cheap as
+        // before.
+        const pruneStale = this.itemsChangedPendingPrune && this.fixedRowHeight == null;
+        const liveKeys = pruneStale ? new Set() : null;
         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;
+            let h;
+            if (this.fixedRowHeight != null) {
+                h = this.fixedRowHeight;
+            }
+            else {
+                const key = this.keyOf(this.items[i], i);
+                liveKeys?.add(key);
+                h = this.measuredHeights.get(key) ?? DEFAULT_ROW_ESTIMATE_PX;
+            }
             offsets[i + 1] = offsets[i] + h;
         }
         this.offsets = offsets;
+        this.itemsChangedPendingPrune = false;
+        if (liveKeys) {
+            for (const key of this.measuredHeights.keys()) {
+                if (!liveKeys.has(key))
+                    this.measuredHeights.delete(key);
+            }
+        }
     }
     /** First item index whose bottom edge is at/after `offset`. */
     findIndexAtOrAfter(offset) {
@@ -285,8 +400,12 @@ export class LyraVirtualList extends LyraElement {
         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);
+        // Property assignments bypass Lit's attribute converter, so normalize at
+        // the arithmetic boundary too. This preserves virtualization even when
+        // JavaScript writes Infinity, NaN, a negative, or an excessive number.
+        const overscan = normalizeOverscan(this.overscan);
+        this.renderStart = Math.max(0, this.visibleStart - overscan);
+        this.renderEnd = Math.min(n - 1, this.visibleEnd + overscan);
     }
     attachContainerListeners() {
         const base = this.renderRoot.querySelector('[part="base"]');
@@ -328,9 +447,13 @@ export class LyraVirtualList extends LyraElement {
         }
         const current = new Map();
         this.renderRoot.querySelectorAll('[part="row"]').forEach((el) => {
-            const key = el.dataset.rowKey;
-            if (key !== undefined)
-                current.set(key, el);
+            const index = Number(el.getAttribute('aria-posinset')) - 1;
+            if (!Number.isInteger(index) || index < 0 || index >= this.items.length)
+                return;
+            const key = this.keyOf(this.items[index], index);
+            current.set(key, el);
+            this.observedRowKeys.set(el, key);
+            this.observedRowIndices.set(el, index);
         });
         for (const [key, el] of this.observedRows) {
             if (current.get(key) !== el) {
@@ -346,9 +469,9 @@ export class LyraVirtualList extends LyraElement {
         }
     }
     scrollActiveIntoView() {
-        if (!this.activeId)
+        if (this.activeId === '')
             return;
-        const index = this.items.findIndex((item, i) => String(this.keyOf(item, i)) === this.activeId);
+        const index = this.items.findIndex((item, i) => Object.is(this.keyOf(item, i), this.activeId));
         if (index < 0)
             return;
         const base = this.renderRoot.querySelector('[part="base"]');
@@ -392,14 +515,14 @@ export class LyraVirtualList extends LyraElement {
         this.emit('lyra-load-more');
     }
     renderRow(item, index, total) {
-        const key = String(this.keyOf(item, index));
+        const key = this.keyOf(item, index);
         const top = this.offsets[index] ?? 0;
-        const isActive = this.activeId !== '' && key === this.activeId;
+        const isActive = this.activeId !== '' && Object.is(key, this.activeId);
         return html `
       <div
         part="row"
         role="listitem"
-        data-row-key=${key}
+        data-row-key=${domKeyToken(key)}
         aria-setsize=${total}
         aria-posinset=${index + 1}
         aria-current=${isActive ? 'true' : nothing}
@@ -409,6 +532,28 @@ export class LyraVirtualList extends LyraElement {
       </div>
     `;
     }
+    renderGroups() {
+        const seen = new Set();
+        return (this.groups ?? [])
+            .filter((group) => {
+            const index = group.startIndex;
+            if (!Number.isInteger(index) || index < 0 || index >= this.items.length || seen.has(index))
+                return false;
+            seen.add(index);
+            return true;
+        })
+            .sort((a, b) => a.startIndex - b.startIndex)
+            .map((group) => html `
+          <div
+            part="group"
+            role="heading"
+            aria-level="2"
+            style=${styleMap({ transform: `translateY(${this.offsets[group.startIndex] ?? 0}px)` })}
+          >
+            ${group.label ?? String(group.key)}
+          </div>
+        `);
+    }
     render() {
         const n = this.items.length;
         const totalHeight = this.offsets[n] ?? 0;
@@ -419,6 +564,7 @@ export class LyraVirtualList extends LyraElement {
         return html `
       <div part="base" role="list" tabindex="0" aria-busy=${this.loading ? 'true' : nothing}>
         <div part="spacer" style=${styleMap({ height: `${totalHeight}px` })}>
+          ${this.renderGroups()}
           ${repeat(windowed, (w) => this.keyOf(w.item, w.index), (w) => this.renderRow(w.item, w.index, n))}
         </div>
       </div>
@@ -441,7 +587,7 @@ __decorate([
     property({ attribute: 'row-height' })
 ], LyraVirtualList.prototype, "rowHeight", void 0);
 __decorate([
-    property({ type: Number })
+    property({ converter: overscanConverter })
 ], LyraVirtualList.prototype, "overscan", void 0);
 __decorate([
     property({ attribute: 'active-id' })

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

@@ -38,6 +38,18 @@ export const styles = css `
        re-render -- hinting the compositor avoids a full repaint per frame. */
     will-change: transform;
   }
+  [part='group'] {
+    position: absolute;
+    inset-inline: 0;
+    inset-block-start: 0;
+    z-index: 1;
+    padding: var(--lyra-space-xs) var(--lyra-space-s);
+    background: var(--lyra-color-surface);
+    color: var(--lyra-color-text-quiet);
+    font-size: 0.875em;
+    font-weight: 600;
+    pointer-events: none;
+  }
   :host([loading]) [part='base'] {
     cursor: progress;
   }

package/dist/components/widget/widget.d.ts

@@ -42,18 +42,19 @@ export declare class LyraWidget extends LyraElement {
     compact: boolean;
     private hasActionsSlot;
     private releaseScrollLock?;
-    private lastTrigger?;
+    private overlayHandle?;
+    private explicitTrigger?;
     private readonly bodyId;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    private activateFullscreenOverlay;
+    private deactivateFullscreenOverlay;
     private onActionsSlotChange;
     private toggleCollapsed;
     private toggleFullscreen;
-    private onDocKeyDown;
-    private getFocusableElements;
-    private getActiveElement;
+    private dismissFullscreen;
     private onBackdropClick;
     render(): TemplateResult;
 }