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;
/** `lr-visible-range-change` detail -- the current visible (non-overscanned) item index range. */
export interface LyraVirtualListRange{start:number;end:number;}
/** A visible group label anchored to the first row in its group. */
export interface LyraVirtualListGroup{key:string|number;label?:string;startIndex:number;}
/** The ARIA role pairing each rendered row participates in -- see `itemRole`'s own doc for what
*  each value maps to. */
export type LyraVirtualListItemRole='listitem'|'row';
/**
* Where `renderItem`'s output is instantiated.
*
* - `'shadow'` (the default) stamps it inside this component's shadow root, where only inherited
*   custom properties and an explicitly exported part reach it.
* - `'light'` stamps it into the HOST'S OWN light DOM, assigned back into the windowed row wrapper
*   through an internal named slot, so an ordinary document stylesheet styles a virtualized row.
*   Windowing, measurement, spacer sizing, `scrollToIndex()`, the external-scroller mode and the
*   ARIA contract all stay with this component either way.
*/
export type LyraVirtualListRowProjection='shadow'|'light';
/**
* Reserved attribute marking a light-DOM row wrapper this component created in
* `row-projection="light"` mode, so consumer CSS, DOM diffing and snapshot tests can recognise a
* library-owned light-DOM node. `::part()` cannot address one -- a projected row is in the
* document's tree, not a shadow tree -- so this replaces `closest('[part="row"]')` for a delegated
* listener in that mode. Built through `tag()`, exactly like `ANNOUNCEMENT_SINK_ATTRIBUTE`.
*/
export declare const VIRTUAL_LIST_ROW_ATTRIBUTE:string;
/** Reserved attribute marking the projected sticky-band wrapper. Same rationale as
*  {@linkcode VIRTUAL_LIST_ROW_ATTRIBUTE}. */
export declare const VIRTUAL_LIST_STICKY_ATTRIBUTE:string;
/** A fixed positive pixel height, or live per-row measurement. */
export type LyraVirtualListRowHeight=number|'auto';type VirtualListKey=string|number;
/** A random-access collection that does not have to materialize one JavaScript value per row. */
export interface LyraVirtualListIndexedSource<T=unknown>{
/** Number of addressable rows. Fractional, negative, and non-finite values normalize safely. */
readonly count:number;
/** Returns the value at `index`. The component calls this only for rows it needs to render. */
itemAt(index:number):T;
/** Returns a stable identity without first allocating or reading the row value. */
keyAt?(index:number):string|number;
/**
* Resolves a stable key back to its row index without a count-sized scan. Use this alongside
* `keyAt` whenever `active-item-id` should target an indexed collection. Indexed sources deliberately
* do not fall back to a count-sized scan when this is absent. Invalid and out-of-range results
* are treated as a missing key.
*/
indexOfKey?(key:string|number):number;}
/** Either an ordinary readonly array or a count/index-backed random-access collection. */
export type LyraVirtualListSource<T=unknown> =readonly T[]|LyraVirtualListIndexedSource<T>;
/** `lr-virtual-scroll` detail -- the scroll position and height after a coalesced tick. */
export interface LyraVirtualListScroll{scrollTop:number;viewportHeight:number;}export interface LyraVirtualListEventMap{'lr-visible-range-change':CustomEvent<LyraVirtualListRange>;'lr-load-more':CustomEvent<null>;'lr-virtual-scroll':CustomEvent<LyraVirtualListScroll>;}
/**
* `<lr-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 its effective source 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`). That value is instantiated inside this component's shadow root, not in the
* caller's light DOM; style callback output in its own template/custom element, through inherited
* custom properties, or through an explicitly exported part. `keyFunction(item, index)` gives the
* row a stable `repeat()` reconciliation key, so scroll position and any per-row state (e.g. an
* `<audio>` element's playback position) survive an array/source mutation instead of every row
* remounting from scratch.
*
* **Narrow allocations.** Row wrappers allow their content to shrink and use
* `overflow-wrap: anywhere` by default, so a normal long value wraps inside
* the list rather than widening a narrow panel; its resulting height is what
* `row-height="auto"` measures. A consumer that deliberately needs an
* unbroken value can set `white-space: nowrap` on its own rendered content:
* the scroll container remains horizontally scrollable for that opt-out.
*
* **Windowing math.** Every row is positioned by a `transform: translateY(offset)`, rather than by
* page flow. Array sources use a cumulative offsets cache. Count/index sources stay sparse: fixed
* row offsets are direct arithmetic and auto-height offsets add only mounted-row measurements to
* the default estimate. This is what lets only a small DOM window exist while the scrollbar still
* reflects the full content height without synthesizing count-sized item/key/offset arrays:
* - **`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`
*   until it has been. This 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 — the offset is `i * rowHeightPx` for an
*   indexed source, while arrays retain the same cached cumulative path as auto-height arrays.
*
* An array source's offsets cache is rebuilt only when `items`/`source`, `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
* indexed sources skip that count-sized rebuild entirely.
*
* Before a viewport can be measured, including during server rendering, one bounded deterministic
* first window (the first row plus `overscan`) is emitted instead of a false empty list. Hydration
* preserves that server window on its first pass, then reconciles it with the measured viewport;
* an ordinary browser-only mount retains its empty-until-measured range-event behavior.
*
* **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
* `<lr-select>`'s pattern), the same way this component's `active-item-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 effective source (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, measured virtual entry immediately
* before the corresponding `startIndex` row. Its live block size contributes to following offsets,
* so an opaque variable-height marker cannot cover that first row. Markers are windowed with the
* rows, while normalized metadata stays cached for sticky lookup; one-group-per-row catalogs remain
* bounded.
*
* **Sticky group headers.** `renderStickyGroup` adds a `[part="sticky-group"]` overlay pinned to the
* top of the scroll viewport, showing the `groups` entry the viewport is currently inside; as the
* next group's header arrives it is pushed out by the overlap rather than swapped abruptly. Unset
* (the default) renders no overlay element at all, and the list renders exactly as it does without
* this feature. Four properties of the overlay matter to a consumer:
* - It is a **strictly presentational visual copy** of content that already exists in the list, so
*   the copy itself is both `aria-hidden` and `inert`. The real row keeps sole ownership of heading
*   semantics, focus and activation without this component traversing or mutating caller-rendered
*   descendants (including arbitrary open shadow roots).
* - It is **pointer-transparent**. Put interactive group actions in the real row; the sticky copy
*   deliberately cannot be opted into a pointer-only interaction state.
* - It is **never measured as a row or real marker.** It contributes nothing to offsets, so the
*   presentational copy is not counted twice.
* - Its measured height becomes a `scroll-padding-block-start` on the scroll container, so both
*   `active-item-id`/`scrollToIndex` and native keyboard scrolling stop *below* the band instead of
*   parking the target row behind it. Scrolled above the first group the band shows nothing but
*   stays mounted, so that height is known before the first jump rather than after it. Under an
*   external `scrollElement` that inset is written on an element that no longer scrolls: the
*   programmatic paths still clear the band (they subtract it arithmetically), but the consumer
*   owns mirroring `scroll-padding-block-start` onto their own scroller for the native one.
* A host that renders its own group headers as ordinary rows supplies `groups` purely as position
* anchors, with `label: ''` so no duplicate `[part="group"]` marker renders.
*
* **Position queries.** `offsetForIndex(index)` and `indexAtOffset(px)` expose the windowing math
* itself: they translate between an item index and the pixel offset that row renders at, in the same
* coordinate space as the scroll container's `scrollTop`. A host doing its own scroll-linked layout
* (a pinned group header, a scrollbar minimap, a "jump to here" affordance) needs those numbers and
* would otherwise have to duplicate the offsets array.
*
* **External scroll container.** `scrollElement` points the whole windowing loop at an ancestor
* element (or the `Window`) that already owns a scrollbar, for a list embedded in a longer scrolling
* page rather than sized as its own panel. `[part="base"]` then stops scrolling and grows to the
* list's full virtual extent, so the page scrollbar spans the whole list, the visible band is the
* external scroller's height, and `[part="sticky-group"]` sticks to that scrollport. Every
* list-coordinate API (`offsetForIndex()`, `indexAtOffset()`, `scrollToIndex()`, `active-item-id`,
* `lr-virtual-scroll`) keeps answering in the list's own offsets; this component converts. There is
* no ancestor auto-detection, deliberately: a detected scroller would silently change this
* component's behavior the day an unrelated `overflow` rule landed on a wrapper in between.
*
* **Programmatic scrolling.** `scrollToIndex()` is the public counterpart to `active-item-id`'s automatic
* scroll-into-view -- used by `<lr-chat-viewport>`'s virtual mode and any other host that needs to
* scroll to a specific row without also changing which row is "active."
*
* **`item-role="row"` mode.** Additive to the default `'listitem'` mapping above: `[part="base"]`
* becomes `role="rowgroup"`, `[part="spacer"]` becomes `role="presentation"`, and each row becomes
* `role="row"` with `aria-rowindex` (the row's 1-based index plus `row-index-offset`) instead of
* `aria-setsize`/`aria-posinset`. For a consumer composing its own `role="table"` wrapper and header
* row around this component (see `<lr-dataset-viewer>`), where `row-index-offset="1"` accounts for
* that external header row occupying `aria-rowindex="1"`.
*
* Public collection properties take bounded, clone-owned readonly snapshots. Create a new
* collection and reassign it after changes; mutating the assigned array does not update the view.
*
* @customElement lr-virtual-list
* @event lr-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 the effective source 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 lr-visible-range-change - `detail: { start, end }` (see
*   `LyraVirtualListRange`) — the current visible (non-overscanned) item index
*   range, fired only when it actually changes.
* @event lr-virtual-scroll - `detail: { scrollTop, viewportHeight }` (see
*   `LyraVirtualListScroll`) — the scroll container moved. `scrollTop` is always in the list's own
*   offset space (`offsetForIndex()`'s space), including under an external `scrollElement`, where it
*   is how far the list has scrolled past the top of that scroller rather than the scroller's own
*   position. Emitted from the same
*   `requestAnimationFrame` tick that already coalesces native `scroll`
*   events, so a fling that fires dozens of native events produces at most one
*   of these per frame, and none at all when the position did not actually
*   change. Unlike `lr-visible-range-change` this reports *sub-row*
*   movement, which is what a scroll-linked layout (a pinned header, a
*   minimap) needs.
*
* A host `aria-label` attribute on this element is forwarded onto the internal `role="list"`
* container, since `aria-label` set on a custom-element host does not by itself name a role living
* on an internal shadow element. Used by `<lr-activity-feed>`'s virtualized mode.
* @csspart base - The scrollable container (`role="list"`), including the horizontal scrollport
*   used when consumer-rendered row content explicitly opts out of wrapping. Under an external
*   `scrollElement` it stops scrolling, drops its `tabindex` and hover outline, and sizes itself to
*   the list's full virtual extent instead of `--lr-virtual-list-height`.
* @csspart spacer - The full-content-height inner element that gives the
*   container its true scrollable extent.
* @csspart group - A positioned group label. Not rendered for a `groups` entry whose `label` is the
*   empty string (a position-anchor-only entry).
* @csspart sticky-group - The pinned copy of the current group, rendered only while
*   `renderStickyGroup` is set (and showing nothing while the viewport is above the first group,
*   where there is no group to pin). Always `aria-hidden`, `inert`, and pointer-transparent; put
*   interactive actions in the real group row.
* @csspart row - One rendered row's absolutely-positioned wrapper
*   (`role="listitem"`); `renderItem`'s return value renders inside it. Normal content wraps
*   within the row; consumer content can opt out with `white-space: nowrap`.
* @cssprop [--lr-virtual-list-height=var(--lr-size-24rem)] - The scroll viewport's height. A
*   virtualized list needs a bounded scroll extent, so this ships a default rather than
*   collapsing to zero when a caller does not size the host. Ignored while `scrollElement` names an
*   external scroller, whose own height is the visible band.
* @cssprop [--lr-virtual-list-hover-outline-width=var(--lr-border-width-thin)] - Outline width of
*   the mouse-hover preview on `[part="base"]`.
* @cssprop [--lr-virtual-list-hover-outline-style=solid] - Outline style of the mouse-hover preview
*   on `[part="base"]`.
* @cssprop [--lr-virtual-list-hover-outline-color=var(--lr-color-border-strong)] - Outline color of
*   the mouse-hover preview on `[part="base"]` (a subtler, always-focusable-target preview of its
*   own `:focus-visible` ring). Set to `transparent` to opt out of the hover treatment entirely.
* @cssprop [--lr-virtual-list-hover-outline-offset=calc(-1 * var(--lr-border-width-thin))] -
*   Inward offset of the mouse-hover preview on `[part="base"]`, keeping the outline inside its
*   own scrollport so it is not clipped at the edge.
* @cssprop [--lr-theme-scrollbar-width=auto] - Opt-in theme-level scrollbar width honored by the
*   `base` scroll viewport; unset, renders identically to before. Set on `:root` or any ancestor
*   to retune every internal scroll container in the library at once.
* @cssprop [--lr-theme-scrollbar-gutter=auto] - Opt-in theme-level scrollbar gutter honored by the
*   `base` scroll viewport; see `--lr-theme-scrollbar-width`.
* @status stable
* @since 4.0.0
*/
export declare class LyraVirtualList extends LyraElement<LyraVirtualListEventMap>{protected static readonly ownedCollectionProperties:readonly string[];
/** Generic rows are keyed/rendered by caller identity; only their containing sequence is owned. */
protected static readonly identityCollectionProperties:readonly string[];
/** Count/index providers are opaque imperative sources; array-valued sources still snapshot. */
protected static readonly identityCollectionObjectProperties:readonly string[];static styles:import("lit").CSSResultGroup[];
/**
* The full (non-windowed) item collection. Preserved as the array-compatible source when
* `source` is unset.
*/
items:readonly unknown[];
/**
* A readonly array or count/index-backed collection. An array assignment is copied, bounded,
* and frozen while retaining each generic row's identity; reassign a new array after sequence
* changes. Indexed-source objects pass through by identity. When set, this takes precedence over
* `items`; an indexed source lets synthetic or remote models expose a large row count without
* allocating an `Array(0…count)` merely to feed the virtualizer.
*/
source?:LyraVirtualListSource;
/** Renders one row's content — typically a `lit-html` `TemplateResult` — inside this component's
*  shadow root. The returned value is not light-DOM content: style it in its own template/custom
*  element, with inherited custom properties, or through a part this component exports. */
renderItem:(item:unknown,index:number)=>unknown;
/** Derives a row's stable `repeat()` key. Falls back to the item's index
*  in the effective source when omitted, which is only a safe identity while the collection
*  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 `<lr-table>`'s `rowKey`). Duplicate keys remain distinct
*  by occurrence for rendering and measurement; `activeItemId` targets the first occurrence. */
keyFunction?:(item:unknown,index:number)=>string|number;
/** Measured group markers inserted immediately before their first row's `startIndex`. Non-object
* entries, invalid indexes, and duplicate indexes are ignored during rendering. An entry whose `label` is
* the empty string renders no `[part="group"]` marker at all — it is a pure
* position anchor, for a host that renders its own group header as an
* ordinary row (and would otherwise get two stacked headers) but still needs
* this component to know where each group starts, e.g. to drive
* `renderStickyGroup`. Omitting `label` entirely still falls back to `key`. */
groups?:readonly LyraVirtualListGroup[];
/** Renders the pinned copy of whichever `groups` entry the viewport is
*  currently inside, into a `[part="sticky-group"]` overlay layer that stays
*  at the top of the scroll viewport. Unset (the default) renders no overlay
*  element whatsoever. See the class doc's "Sticky group headers" section for
*  the accessibility and interactivity contract.
*
*  Called on every scroll-driven update, so keep it cheap and side-effect
*  free — including while the viewport is above the first group, where it is
*  called with the *first* group and the result rendered hidden, purely to
*  keep the band's height measurable for the scroll inset. */
renderStickyGroup?:(group:LyraVirtualListGroup)=>unknown;
/** `'auto'` (default) measures each row's real height via `ResizeObserver`;
*  a positive number fixes every row to that many pixels. Numeric markup attributes are parsed
*  into numbers; invalid markup safely canonicalizes to `'auto'`. */
rowHeight:LyraVirtualListRowHeight;
/** `'listitem'` (default) preserves today's `role="list"`/`role="listitem"` mapping with
*  `aria-setsize`/`aria-posinset`. `'row'` maps to `role="rowgroup"`/`role="row"` with
*  `aria-rowindex` instead -- for a consumer composing a virtualized `role="table"` (see
*  `<lr-dataset-viewer>`). */
itemRole:LyraVirtualListItemRole;
/** Where `renderItem`'s output is instantiated: `'shadow'` (the default) inside this component's
*  shadow root, or `'light'` as a child of the host itself so ordinary document CSS reaches it.
*  See the class doc's "Light-DOM row projection" section for the full contract. Unsupported
*  attribute values and untyped property writes normalize back to `'shadow'`; the property is
*  deliberately not reflected, matching `itemRole`. */
private _rowProjection;get rowProjection():LyraVirtualListRowProjection;set rowProjection(next:LyraVirtualListRowProjection);
/** Added to a row's 1-based index to compute `aria-rowindex` in `item-role="row"` mode (e.g. `1`
*  when a consumer renders its own header row occupying `aria-rowindex="1"` outside this
*  component). No effect in `'listitem'` mode. */
rowIndexOffset:number;
/** 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. */
activeItemId:VirtualListKey|'';loading:boolean;
/** When true, scrolling near the bottom fires `lr-load-more`. */
hasMore:boolean;
/**
* An ancestor element — or the `Window` — that already owns the scrollbar, for a list that is
* part of a longer scrolling page rather than a self-contained panel. While set, this component's
* own `[part="base"]` viewport stops scrolling (it grows to the list's full virtual extent) and
* the windowing math tracks the named scroller's position instead, so one page scrollbar moves
* the whole page *and* re-windows the list.
*
* There is deliberately **no ancestor auto-detection**: the scroller is whichever element you
* name and nothing else. A detected ancestor would silently change this component's behavior the
* day an unrelated `overflow` rule lands on some wrapper between the two.
*
* Everything expressed in list coordinates keeps working unchanged — `offsetForIndex()`,
* `indexAtOffset()`, `scrollToIndex()`, `active-item-id`, and `lr-virtual-scroll`'s `scrollTop`
* are all still relative to the top of the list itself, not to the external scroller; the
* component converts between the two. What changes hands is the scrollbar, the visible band's
* height (the scroller's, not `--lr-virtual-list-height`'s), and `[part="sticky-group"]`'s
* sticky container, which becomes the external scrollport.
*
* Four consequences worth knowing before reaching for this:
* - `[part="base"]` drops its `tabindex` and its hover outline, because it is no longer a
*   scrollable region. Keyboard scrolling belongs to the external scroller, and a focus stop that
*   scrolls nothing is worse than none.
* - Horizontal scrolling of row content that opted out of wrapping (`white-space: nowrap`)
*   becomes the external scroller's responsibility: CSS cannot leave one axis visible while the
*   other scrolls.
* - The list's position inside the scroller is re-read on scroll, on the scroller's own resize,
*   when the list's own rendered extent resizes, and whenever this property *changes*. A layout
*   change *above* the list that shifts it without any of those happening is not observable. To
*   force a re-read, clear the property and set it again
*   (`el.scrollElement = undefined; el.scrollElement = scroller`) -- assigning the same value
*   twice does nothing, because an unchanged value is not a change as far as Lit is concerned.
* - While `renderStickyGroup` is set, mirror `scroll-padding-block-start` onto the external
*   scroller yourself. This component writes that inset on `[part="base"]`, where it stops having
*   any effect once that element no longer scrolls, and it will not write style on an element it
*   does not own. Programmatic scrolling is unaffected -- `scrollToIndex()` and `active-item-id`
*   subtract the band's height arithmetically -- but native keyboard scrolling can otherwise park
*   the row it lands on underneath `[part="sticky-group"]`.
*
* A value that is neither an `Element` nor a `Window` is ignored (the component keeps scrolling
* its own viewport) rather than throwing — a consumer wiring this from a ref commonly passes
* `null`/`undefined` on its first render.
*/
scrollElement?:Element|Window;
/**
* The real scroll container — the `[part="base"]` element, the box whose `scrollTop`/
* `clientHeight` this component's windowing math is expressed against. `undefined` until the
* first render (and for a never-connected element), since the element does not exist before then.
*
* While `scrollElement` is set this element still exists and still hosts every row, but it no
* longer scrolls: the named external scroller does. Read and write the scroll position there, or
* keep using `scrollToIndex()`, which targets whichever of the two is currently in charge.
*
* Exposed so a host that needs the live scroll position, or needs to scroll the list itself, can
* do it without reaching into this component's shadow root. Pair it with `lr-virtual-scroll` (change
* notifications), `offsetForIndex()`/`indexAtOffset()` (coordinate conversion), and
* `scrollToIndex()` (which expresses "show row N" without any manual arithmetic at all, and is
* the better choice whenever that is the actual intent).
*/
get scrollContainer():HTMLElement|undefined;
/**
* The row wrappers (`[part="row"]`) that currently exist as real DOM, in item order — the current
* window, not the whole `items` collection, and empty before the first render. Each one carries
* its own `data-row-index`, and `renderItem`'s output for that item is inside it.
*
* For a host that has to *reach* a rendered row rather than style it: focus management across a
* windowed list is the motivating case, since the row that a keyboard command needs to focus may
* not have existed a frame earlier. `exportparts` cannot serve that — it forwards styling, not
* element references. Treat the returned elements as read-only: their positioning, keys, and
* lifetime belong to the windowing math, and any of them can be recycled or removed on the next
* update.
*/
get renderedRows():HTMLElement[];
/**
* The projected light-DOM row wrappers (`[data-lr-virtual-list-row]`) that currently exist as
* direct children of this host, in item order — the `row-projection="light"` counterpart of
* {@linkcode renderedRows}, and always empty in the default `'shadow'` mode.
*
* Each one pairs 1:1 with the `[part="row"]` wrapper it is slotted into and mirrors that
* wrapper's `data-row-index`/`data-row-key`. Only direct children are considered, so a nested
* `<lr-virtual-list>` inside a projected row never contributes its own rows here. Treat the
* returned elements as read-only: their lifetime belongs to the windowing math, and any of them
* can be recycled or removed on the next update.
*/
get projectedRows():HTMLElement[];
/** The configured external scroller once it is usable, or `undefined` whenever this component
*  scrolls its own `[part="base"]` viewport. See `scrollElement` for why a non-`Element`,
*  non-`Window` assignment resolves to "no external scroller" instead of throwing. */
private get externalScroller();
/** The full-extent inner element every row offset is measured from — the origin of this
*  component's own scroll-coordinate space, and therefore the thing an external scroller's
*  position has to be expressed relative to. */
private get spacerElement();
/**
* The current scroll position in this list's *own* offset space (the space `offsetForIndex()`
* answers in) plus the height of the band visible over it, whichever element is scrolling.
* `null` before the container exists.
*
* For an external scroller the position is a rect delta rather than a `scrollTop` read, because
* the list generally does not start at the top of that scroller's content. That delta is genuinely
* negative while the scroller still sits above the list, so it is reported twice: `scrollTop` is
* clamped at zero, which is what windowing wants (the window stays pinned to the first row while
* the list is still below the scroller's top edge), and `rawScrollTop` keeps the signed value,
* which is what any *conversion* wants. Converting through the clamped number would silently drop
* exactly the lead-in distance from every absolute scroll target and from every anchoring
* comparison, landing each one short by however far the scroller is above the list.
* The band is reported as the scroller's whole height even when the list occupies only part of
* it, which over-renders slightly at the edges and never under-renders.
*/
private readScrollMetrics;
/** Moves whichever element is scrolling so this list's own offset space lands at `top`. Omit
*  `behavior` for the direct `scrollTop` write the measurement-anchoring paths need. */
private applyScrollPosition;
/** Re-reads the external scroller's geometry into the reactive windowing state. Writes only on a
*  real change, so the render this can trigger converges instead of looping. */
private syncExternalScrollMetrics;
/** A finite, nonnegative whole-row count before it reaches ARIA arithmetic. */
private get safeRowIndexOffset();private computedAriaRowIndex;private containerScrollTop;private viewportHeight;
/** SSR has no viewport to measure, so its first render exposes a bounded deterministic window.
* A normal browser mount preserves the established empty-until-measured event contract; a
* hydrating mount keeps the server window for exactly its first render, then returns to that
* browser contract through LyraElement's hydration-aware seed helper. */
private renderUnmeasuredWindow;
/** `offsets[i]` = row `i`'s pixel top for array sources. Indexed sources compute offsets from
* their count plus sparse measurements and never allocate this array at source cardinality. */
private offsets;
/** Occurrence-safe internal identities. Public duplicate keys remain visible as distinct rows,
* while the first occurrence alone owns `activeItemId`. */
private rowIdentities;
/** Parsed `rowHeight`: a positive pixel number, or `null` for `'auto'` (measured) mode. */
private fixedRowHeight;
/** `row-height="auto"` per-row measured heights, keyed by internal row identity. Array sources
* are pruned to their current live identities whenever `items` changes; indexed sources retain
* only a bounded window around the rendered range. */
private readonly measuredHeights;
/** Index ownership for each retained measurement. Pruned in lockstep with `measuredHeights`. */
private readonly measuredIndices;
/** Sorted retained indexes and their cumulative height deltas. Indexed offset queries binary
* search this cache instead of rescanning every retained measurement. */
private indexedMeasurementIndices;private indexedMeasurementDeltaPrefix;private indexedMeasurementIndexDirty;
/** 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;
/** The window the most recent shadow `render()` emitted, with each row's identity already
*  resolved. `row-projection="light"` renders the SAME array, keyed by the SAME identity, so the
*  two sides can never disagree about which rows exist or what they are called. */
private renderedWindow;
/** Trailing comment bounding the light-DOM render part; also where lit-html caches that part. */
private projectionAnchor?;private projectionPart?;
/**
* True until the first render is safely past. A server render can never produce projected rows --
* `@lit-labs/ssr` calls `connectedCallback()`, `willUpdate()` and `render()`, never
* `update()`/`updated()`, and there is no DOM to render into -- so activating projection
* unconditionally would serialize this component's bounded deterministic first window EMPTY and
* make the browser's first render disagree with the markup it is hydrating.
*
* Released through `seedFirstRenderState()`, the same helper `renderUnmeasuredWindow` uses: a
* browser-only mount clears it synchronously inside `connectedCallback()` (so the very first
* render is already projected, with no flash and no extra update), while a hydrating mount keeps
* the server's shadow-rendered window for exactly its first render and swaps into the light DOM
* one task later.
*/
private projectionDeferred;
/** Stable reference so `seedFirstRenderState()`'s pending set dedupes the re-arm below. */
private readonly releaseRowProjection;private visibleStart;private visibleEnd;private lastEmittedStart;private lastEmittedEnd;
/** Re-armed whenever the window moves away from the end of `items` -- see the `lr-load-more` event doc. */
private loadMoreArmed;
/** Identity- and source-bound correction transaction for estimate-based programmatic scrolling. */
private pendingScrollCorrection?;private measurementGeneration;private isFirstUpdate;
/** The sticky overlay's measured block size, used both for the push-off overlap math and for the
*  scroll inset that keeps a scrolled-to row from landing underneath the band. Measured by its own
*  `ResizeObserver` -- deliberately never by `rowResizeObserver`, which would fold this *copy* of a
*  row into `offsets` and double-count the group header's height. */
private stickyHeight;private rowResizeObserver?;private groupResizeObserver?;private containerResizeObserver?;private stickyResizeObserver?;private observedSticky?;private readonly observedRows;private readonly observedRowKeys;private readonly observedRowIndices;private readonly observedGroups;private readonly observedGroupIndices;private scrollRafId?;private scrollRafOwner?;private scrollRafDocument?;
/** Whatever this component last bound its scroll/intent listeners to -- its own `[part="base"]`,
*  an external `scrollElement`, or a `Window`. Detaching reads this stored target rather than
*  re-deriving one, so re-pointing `scrollElement` can never strand a listener on the old target. */
private scrollListenerTarget?;
/** Set only for a `Window` scroller, which has no box a `ResizeObserver` could watch. */
private viewportResizeTarget?;
/** An external scroll happened and its rect-delta position is still to be read, in the coalescing
*  frame below rather than once per native `scroll` event. */
private externalMetricsPending;private ownerRealmGeneration;
/** True for the remainder of the frame in which any of this component's `ResizeObserver`s
*  delivered -- so `syncRowObservers()` can tell that a re-render it is running inside is still
*  part of the browser's current resize-observation loop, and the measurement callbacks can tell
*  that folding a new height into the offsets would resize an observed box from inside one. See
*  `beginResizeDelivery()`. */
private inResizeDelivery;
/** Row heights observed during a delivery whose offsets rebuild waits for the frame flush, keyed
*  by row identity exactly like `measuredHeights`. A raw observation, not yet a measurement: the
*  0.5px compare, the cache write, and the scroll anchoring all still happen in one place, in
*  `applyPendingRowMeasurements()`. See `beginResizeDelivery()`. */
private readonly pendingRowMeasurements;
/** The same, for real group markers, keyed by `startIndex` like `measuredGroupHeights`. */
private readonly pendingGroupMeasurements;
/** Rows that entered the window during such a re-render: already owned by `observedRows`, but not
*  yet handed to `rowResizeObserver`. Always a subset of `observedRows` -- `syncRowObservers()`
*  drops an entry here whenever it drops the same identity there. */
private readonly deferredRowObservations;private readonly deferredGroupObservations;private rowObserveRafId?;private rowObserveRafOwner?;private rowObserveRafDocument?;
/** Reference-keyed memo for `activeItemId`'s resolved index. `render()` re-runs on every scroll
*  frame (`scrollTop` drives reactive state), and resolving an array source means scanning it
*  with `keyOf` -- O(items) *per frame* without this memo. Indexed sources never scan their
*  declared count: they use `indexOfKey`, or decline the match when it is absent/overridden by a
*  consumer `keyFunction`. The inputs are source identity, `activeItemId`, count, and `keyFunction`.
*  Mutable array length is keyed too: that catches an in-place
*  insert/remove followed by a manual `requestUpdate()`. An in-place *reorder* of the same length
*  is not detected -- the same identity caveat `keyFunction` already documents. */
private activeIndexFor?;private activeIndexForLength;private activeIndexForId;private activeIndexForKeyFn?;private activeIndexCache;
/** `activeItemId`'s index in the effective source, or -1. Memoized -- see `activeIndexFor`. */
private get activeIndex();private pendingScrollTop;
/** Normalized once per `groups`/source assignment, then shared by marker and sticky paths. */
private normalizedGroups;private readonly normalizedGroupByIndex;
/** Live block sizes for real group markers. Position-only anchors (`label: ''`) never enter it. */
private readonly measuredGroupHeights;
/** Cumulative marker heights in normalized-group order, used by sparse indexed sources. */
private groupHeightPrefix;connectedCallback():void;disconnectedCallback():void;adoptedCallback():void;private isCurrentOwnerWork;private resetOwnerRealmWork;firstUpdated(changed:PropertyValues):void;protected willUpdate(changed:PropertyValues):void;protected updated(changed:PropertyValues):void;private parseRowHeight;private get effectiveSource();private get itemCount();private itemAt;private keyOf;private rowIdentity;private identityAt;private groupHeightAt;private rowHeightAt;
/** Marker height before and at `index`, from the sparse normalized group metadata. */
private groupContributionThrough;private recomputeGroupHeightPrefix;private indexedOffsetForIndex;private rebuildIndexedMeasurementIndex;private pruneIndexedMeasurements;private offsetAt;private recomputeOffsets;private groupTopAt;private rowBottomAt;private entryTopAt;
/** First item index whose bottom edge is at/after `offset`. */
private findIndexAtOrAfter;
/** Last item index whose top edge is at/before `offset`. */
private findIndexAtOrBefore;
/**
* Row `index`'s pixel top in this list's own scroll-coordinate space — the exact value the row is
* positioned at (`transform: translateY(...)`), and therefore directly comparable with
* `scrollContainer.scrollTop`. `index` is clamped to `0…count`, so
* `offsetForIndex(count)` is the total content height (`[part="spacer"]`'s height) and an
* empty list always answers `0`.
*
* In `row-height="auto"` mode an unmeasured row contributes a fixed estimate. A real group marker
* likewise contributes a bounded estimate until its own `ResizeObserver` measurement arrives.
* Values converge as those measurements land; fixed numeric `row-height` makes row sizes exact
* immediately, while any group-marker sizes still converge independently. This reflects the most
* recent render, so `await el.updateComplete` after assigning `items` or `source` before querying.
*/
offsetForIndex(index:number):number;
/**
* The index of the row whose box contains `px`, expressed in the same scroll-coordinate space
* `offsetForIndex()` returns — so `indexAtOffset(offsetForIndex(i))` round-trips to `i`, and
* `indexAtOffset(scrollContainer.scrollTop)` is the row at the top of the viewport. Clamped: a
* negative offset resolves to `0` and an offset past the end of the content to the last row.
* Returns `-1` when the effective source is empty. Same `row-height="auto"` estimate caveat as
* `offsetForIndex()`.
*/
indexAtOffset(px:number):number;private computeRange;private attachContainerListeners;private detachContainerListeners;private onExternalViewportResize;private onUserScrollIntent;private onScroll;private onRowsResized;
/** Folds every stashed row observation into `measuredHeights`, anchoring and re-rendering once
*  for the batch. Byte-for-byte the work `onRowsResized()` used to do inline. */
private applyPendingRowMeasurements;private onGroupsResized;
/** The group-marker half of `applyPendingRowMeasurements()`, on the same terms. */
private applyPendingGroupMeasurements;
/** True while folding a fresh measurement into the offsets would resize a box one of this
*  component's own `ResizeObserver`s is watching, from inside that observer's own delivery.
*  See `beginResizeDelivery()`. */
private get defersMeasurementApplication();
/**
* Marks the rest of this frame as "inside a resize-observation delivery", and schedules the
* flush that ends it. Called from every one of this component's `ResizeObserver` callbacks,
* because each of them writes reactive state (`measuredHeights` + `requestUpdate()`,
* `viewportHeight`, `stickyHeight`) and so can re-render the list -- and a re-render can move the
* window.
*
* Two things must not happen inside a delivery, and both end the same way. Calling `observe()`
* registers a brand-new observation, which is always active at a DOM depth the browser has
* already broadcast this frame. Changing the list's *extent* does the same from the other
* direction: `render()` writes it as `[part="spacer"]`'s block size, and under an external
* `scrollElement` `[part="base"][data-external-scroll]` takes its own block size from that spacer
* while `containerResizeObserver` watches it -- a box shallower in the tree than the rows just
* broadcast. Either way the observation is recorded as a *skipped* one, the loop ends, and an
* uncaught `ErrorEvent` reading "ResizeObserver loop completed with undelivered notifications" is
* dispatched. Nothing is actually wrong -- but the error is uncaught, so it lands on whatever is
* running at the time, which is why it showed up as unattributable flake in this component's
* *consumers* rather than here.
*
* So this frame carries the deferred `observe()` calls and the stashed measurements, and the
* measurement callbacks only *read* while the delivery is in flight. Renders are never held: an
* update that lands mid-delivery re-reads offsets nothing has changed, so it writes the extent
* already in the DOM, resizes no observed box, and cannot produce a skipped observation. That
* matters beyond this component -- holding a render would move this element's `updateComplete`
* out from under every parent composing it, which used to resolve in the same microtask run.
*
* Only the external-`scrollElement` case defers, because that is the only one where the extent
* write reaches an observed box; with this component's own viewport scrolling, `[part="base"]`
* takes its block size from `--lr-virtual-list-height` instead, so every measurement there stays
* exactly as immediate as it was. What a row whose measurement is waiting shows during that one
* frame is the same `DEFAULT_ROW_ESTIMATE_PX` geometry it already would have shown, and the
* scroll-anchor correction travels with the measurement that causes it, so no frame is ever
* painted with one applied and the other still pending.
*/
private beginResizeDelivery;
/** 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;
/** Watches only the real, windowed group markers; position-only anchors have no box to measure. */
private syncGroupObservers;
/** How much of the viewport's top edge the sticky overlay covers. `0` whenever there is no sticky
*  layer at all, which is what keeps every scroll path byte-identical to its pre-sticky behavior.
*  Deliberately *not* conditioned on a group being pinned right now: a scroll target must not
*  depend on whether the band happens to be showing at the moment the scroll is requested. */
private get stickyInset();private scrollActiveIntoView;
/**
* Scrolls row `index` into view. `align` (default `'auto'`) chooses `'start'` (row's top edge
* flush with the viewport top), `'end'` (row's bottom edge flush with the viewport bottom), or
* `'auto'` (the same minimal-distance scroll `scrollActiveIntoView()` already uses for
* `active-item-id` -- no scroll at all when the row is already fully visible). `behavior` (default
* `'smooth'`) is forced to `'auto'` under `prefers-reduced-motion: reduce` regardless of what's
* passed. `index` is clamped to `0…count-1`; a call against an empty source is a no-op.
*
* Estimate-based geometry is corrected as measurements arrive, including changes to rows before
* the target and to real group markers. The transaction is bound to the target identity, source,
* and key function, and is canceled by replacement data, a new target, manual scroll intent, or
* disconnect, so a late observation can never drag a newer view back to a stale row.
*/
scrollToIndex(index:number,options?:{align?:'start'|'end'|'auto';behavior?:'auto'|'smooth';}):void;private hasUnmeasuredGroupThrough;private beginPendingScrollCorrection;private performScrollTo;private maybeCorrectPendingScroll;private emitRangeChangeIfNeeded;private maybeFireLoadMore;
/** True whenever `renderItem`'s output belongs in the host's light DOM for THIS render. */
private get projectionActive();
/** The internal slot name pairing one shadow row wrapper with its projected light-DOM row.
*  Keyed by the component's own row identity -- already the `repeat()` key on both sides -- so a
*  scroll or a reorder moves rows without rewriting a single `slot`/`name` attribute. Slot
*  matching is exact whole-value string comparison, so an identity containing a space or a colon
*  still pairs correctly, and the name is never empty so it can never collide with a default
*  slot (of which this component renders none). */
private rowSlotName;
/**
* Mounts, updates or tears down the light-DOM render root that holds `renderItem`'s output in
* `row-projection="light"` mode.
*
* The container is the HOST ITSELF — a slottable must be a direct child of the host — bounded by
* a trailing comment anchor, so the part only ever owns `[startMarker … anchor)`. Anything a
* consumer appends to this element later lands after the anchor and is never cleared by a
* re-render, which is also what keeps a server-rendered light child alive across hydration.
* `host: this` matches `ReactiveElement`'s own render options, so a `renderItem` template whose
* event binding is a method reference gets the same `this` it gets in shadow mode.
*/
private syncRowProjection;private ensureProjectionAnchor;
/**
* Removes the projection completely, using public API only: `render(nothing, …)` so lit-html
* detaches its own child parts and their directives, then the part's start marker, then the
* anchor. Discarding the anchor discards lit's cached root part with it (the cache lives on the
* `renderBefore` node), so no private-field poking is ever required and a later re-projection
* starts from a genuinely fresh part.
*
* After this the host's light DOM holds exactly what the consumer put there: no rows, no lit
* markers, no anchor. The accepted cost is that per-row DOM state inside a projected row does not
* survive a disconnect/reconnect; scroll position, measurements and the window are unaffected,
* because they live in component state rather than in the rows.
*/
private teardownRowProjection;
/**
* One light-DOM wrapper per windowed row, over the same array and keyed by the same identity the
* shadow window used. The wrapper carries no `part` (a `part` attribute outside a shadow tree is
* inert), no `role` and no inline positioning — the `[part="row"]` wrapper it is slotted into
* keeps sole ownership of absolute positioning, the per-frame transform and every ARIA
* attribute, so consumer CSS cannot break windowing. `data-row-index`/`data-row-key` are mirrored
* so document CSS and delegated listeners can still address a specific row.
*/
private renderProjectedRows;private renderRow;
/** Normalizes group definitions only when their inputs change. */
private recomputeGroups;private renderGroups;
/** The group the viewport is currently inside -- the last one whose first row's offset is at or
*  above the current scroll position -- plus how far the incoming group's header has already
*  pushed it out of the band. `null` when there are no groups to pin at all.
*
* Scrolled *above* the first group there is nothing to pin, but the band is still rendered
* (`active: false`, visually hidden) rather than dropped: its measured height is what the scroll
* inset is sized from, and a band that only exists once it has first been shown would let the
* very first `active-item-id`/`scrollToIndex` jump park its target underneath it. */
private currentStickyGroup;private renderStickyLayer;
/** Keeps the overlay's measured height current. Focus/activation ownership is declarative through
* the overlay's `inert` attribute, so no caller-rendered subtree traversal is needed here. */
private syncStickyOverlay;private onStickyResized;render():TemplateResult;}declare global{interface HTMLElementTagNameMap{'lr-virtual-list':LyraVirtualList;}}export{};