import type { ReactNode } from "react";
import type { GridLayout } from "../AdaptiveGrid/chooseColumns.ts";
import type { BlockSizeResolver } from "../AdaptiveGrid/useAdaptiveColumns.ts";
export type VirtualizedGridProps<Item> = {
    /**
     * Where the available block size is read from. Defaults to the
     * viewport, which is the only thing that can answer "will this
     * scroll".
     */
    blockSizeResolver?: BlockSizeResolver;
    /**
     * Everything down the page that is not this grid, in CSS px —
     * header, rails, filter rows. Subtracted before asking how many
     * items stack.
     */
    chromeBlockSize?: number;
    className?: string;
    /**
     * Draw this many columns instead of the automatic answer — the
     * manual override, for a page that hoisted `useAdaptiveColumns`
     * itself.
     */
    columns?: number;
    /** The gap between tracks and rows, in CSS px. */
    gap?: number;
    /**
     * A stable identity per item. Without one the key is the index,
     * which is wrong the moment the list is filtered or an item
     * leaves the middle — React reuses the mounted subtree and the
     * wrong tile inherits the wrong open menu.
     */
    getItemKey?: (item: Item, index: number) => string | number;
    /**
     * One row's block size in CSS px, as a starting guess.
     *
     * Unlike `AdaptiveGrid`'s, this is an *estimate* and not a
     * commitment: every mounted row is measured and the estimate
     * corrected. It still wants to be close, because it is what the
     * scrollbar is sized from before anything has been measured — a
     * bad guess makes the bar jump under the thumb on first scroll.
     */
    itemBlockSize: number;
    /** Every item, mounted or not. */
    items: readonly Item[];
    /**
     * An accessible name for the list. Worth giving: a windowed list
     * is one whose length a reader cannot count for itself.
     */
    label?: string;
    /** Opt in to width-first media layout. */
    layout?: GridLayout;
    /** The most columns the automatic answer will take. */
    maxColumns?: number;
    /** The narrowest a column may be, in CSS px. */
    minColumnInlineSize?: number;
    /**
     * How many rows to mount above and below the viewport.
     *
     * Four rather than `@tanstack/react-virtual`'s default of one:
     * these are media tiles whose images load over the network, and
     * a row that mounts at the moment it becomes visible shows a
     * blank box while the image arrives. Overscan buys the load a
     * head start.
     */
    overscanRows?: number;
    /** Draw one item. */
    renderItem: (item: Item, index: number) => ReactNode;
    /**
     * The `localStorage` key a manual column choice is remembered
     * under. Namespace it to the app; omit it and nothing is
     * written.
     */
    storageKey?: string;
};
/**
 * `AdaptiveGrid`'s layout, with only the rows you can see mounted.
 *
 * The fleet's grids render every item they are given. That is the
 * right default, and it stops being right somewhere in the low
 * thousands: QueuePilot's Pending page put **2,162** tiles on one
 * screen — 19,933 DOM nodes, 2,162 `<img>`, 4,371 `<button>`, 7.8
 * seconds to settle, and roughly 43fps while scrolling on a machine
 * with no GPU to lose. Nothing about that page was wrong except how
 * much of it existed at once.
 *
 * ### It is the same grid, and deliberately so
 *
 * Columns come from `useAdaptiveColumns` — the identical
 * height-first rule `AdaptiveGrid` uses, with the identical two-box
 * structure protecting it (an uncapped outer box is measured, an
 * inner box carries the cap). Windowing is the only difference. A
 * second column heuristic that windowed lists followed and flow
 * lists did not would be a fleet where the same content lays out
 * two ways depending on how many of it there are.
 *
 * ### The window is padding, not absolute positioning
 *
 * The obvious build — absolutely position a row per visible row —
 * is the one this does not do, and the reason is the markup. A
 * `<ul>` whose children are positioning wrappers is not a list any
 * more; the cards stop being `<li>`, and the structure a screen
 * reader walks becomes a fiction maintained by ARIA roles.
 *
 * So there are no row elements at all. One real CSS grid holds the
 * visible items as ordinary `<li>` children, and the thousands of
 * rows above and below it are two numbers:
 * `padding-block-start` for everything scrolled past and
 * `padding-block-end` for everything still to come. The grid then
 * does its own job — tracks on the inline axis, rows sized to
 * their tallest item — instead of being reimplemented in
 * `transform`s.
 *
 * ### How a row gets measured without existing
 *
 * A CSS grid stretches every cell in a row to the row's height
 * (`align-items: stretch`, which is the default and is not
 * overridden here). So **any** cell in a row is exactly as tall as
 * the row, and measuring the first one measures the row. That is
 * what `data-index` and the `measureElement` ref are doing on the
 * leading cell of each row, and it is why tile heights are allowed
 * to vary — a two-line title, a wrapped pair of buttons, a badge
 * only some items carry.
 *
 * The row gap sits between two measured boxes and so is in
 * neither. `measureRow` adds it back, which keeps the virtualizer's
 * idea of the distance from one row to the next and the browser's
 * the same number.
 *
 * ### It follows the page's existing scroll owner
 *
 * A standalone grid follows the browser window. Inside `Shell`, it
 * follows `Main`, which is the shell's one vertical scroll region.
 * It never creates a scroll box of its own. The cost is
 * `scrollMargin`: the virtualizer has to be told how far down its
 * scroll owner the grid starts, which is measured below.
 *
 * ### What windowing costs, and what is done about it
 *
 * The true length is stated rather than implied — `aria-setsize` on
 * every cell carries the full count and `aria-posinset` its real
 * position, so a reader announces "3 of 2,162" instead of "3 of
 * 40". Two costs have no fix at this layer and are the caller's to
 * answer: the browser's `Ctrl+F` only searches what is mounted, and
 * so does "select all". A page that needs either owes its users a
 * search field of its own.
 *
 * ### Nothing is mounted until there is a box to measure
 *
 * `display: none` gives an element no boxes at all, so every
 * measurement taken through one reads zero — and zero is the
 * absence of a measurement, not a measurement of nothing. A grid
 * inside a `hidden` tab panel, a collapsed disclosure or a closed
 * `<details>` therefore measures a 0px container (one column) and
 * 0px-tall rows, and the virtualizer stores those as facts.
 *
 * Revealing the panel corrects all of them at once, and the
 * virtualizer reads a correction as a **resize**. That is the one
 * event it is entitled to move the scroll position for: an item
 * above the viewport that grows must be compensated for, or the
 * page slides under the reader. So it compensates — for a growth
 * that never happened — and scrolls the shared scroll owner down
 * by roughly the distance from the top of the region to the top of
 * the grid.
 *
 * Whether the compensation lands is a race between the
 * `ResizeObserver` delivering the real row heights and the layout
 * effect correcting `scrollMargin`, so the symptom is intermittent
 * and its size varies. Docket's Triage bar is where it was found:
 * one switch moved `Main` 266px, another 190px, another 1,190px,
 * and the tab bar went off the top of the screen. The cause is not
 * the tab bar, and fixing it there would have left every other
 * host of a hidden grid broken.
 *
 * `isLaidOut` is the gate. While the container has no box the
 * windowed grid is not mounted, so there is nothing to measure
 * wrongly and no virtualizer to mislead; it mounts when the box
 * arrives and measures once, correctly. The cost is that a
 * revealed grid re-measures from its estimate instead of resuming
 * a cache — the same thing a routed tab does, and the reason a
 * routed tab never had this bug.
 */
export declare const VirtualizedGrid: <Item>({ blockSizeResolver, chromeBlockSize, className, columns, gap, getItemKey, itemBlockSize, items, label, layout: gridLayout, maxColumns, minColumnInlineSize, overscanRows, renderItem, storageKey, }: VirtualizedGridProps<Item>) => ReactNode;
//# sourceMappingURL=VirtualizedGrid.d.ts.map