@aceshooting/lyra-ui 2.1.0 → 2.3.0

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

@@ -1,210 +1,2 @@
-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;
-}
-/** 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 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 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
- * 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.** 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
- *   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 group - A positioned group label.
- * @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;
-    /** 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. 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 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 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
-     *  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;
-    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 readonly observedRowKeys;
-    private readonly observedRowIndices;
-    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;
-    private renderGroups;
-    render(): TemplateResult;
-}
-declare global {
-    interface HTMLElementTagNameMap {
-        'lyra-virtual-list': LyraVirtualList;
-    }
-}
-export {};
+export * from './virtual-list.class.js';
+//# sourceMappingURL=virtual-list.d.ts.map

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

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