@gridkitjs/dom 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blagoja Blazhevski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @gridkitjs/dom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser behaviours a GridKit renderer needs, as framework-free
+TypeScript: pointer gestures, keyboard focus movement, the observers behind
+fit-to-width and infinite scroll, the row virtualizer's measuring, overlays,
+and a live-region announcer. Built on
+[`@gridkitjs/core`](https://www.npmjs.com/package/@gridkitjs/core) and used by
+[`@gridkitjs/react`](https://www.npmjs.com/package/@gridkitjs/react).
+
+> **Early development.** The API is still moving and may break between minor
+> versions.
+
+You only need this package to write a renderer of your own. `@gridkitjs/react`
+already depends on it, so installing that is enough to use the grid.
+
+```bash
+pnpm add @gridkitjs/dom
+```
+
+Every behaviour attaches to elements the renderer has drawn, owns its own
+listeners and observers, reports through callbacks, and returns the way to end
+it — so it maps onto any framework's lifecycle.
+
+```ts
+import { createLiveAnnouncer, observeElementWidth } from "@gridkitjs/dom";
+
+const announcer = createLiveAnnouncer(gridElement);
+const disconnect = observeElementWidth(gridElement, (width) => {
+  controller.setOptions({ ...options, viewportWidth: width });
+});
+
+announcer.announce("Amount, column 2 of 5");
+
+// when the grid goes away
+disconnect();
+announcer.destroy();
+```
+
+| Behaviour                  | What it does                                                                  |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `createLiveAnnouncer`      | A polite live region for announcements no visual cue can carry.               |
+| `observeElementWidth`      | Reports an element's width, now and on every change.                          |
+| `attachInfiniteScroll`     | Calls `onLoadMore` as a sentinel row nears the bottom of the body.            |
+| `startColumnResizeGesture` | Drags a column's edge into a new width.                                       |
+| `startDragReorder`         | Drags a header or chip to a new place, with the drop-target hit-tests.        |
+| `createRowVirtualizer`     | Windows rows of any height down to those near the scroll position.            |
+| `createGridFocus`          | Keeps the grid's single tab stop and moves the browser's focus with the keys. |
+| `bodyCellFrom` and others  | Resolve a delegated body event to the cell, row or group header it addresses. |
+| `attachOverlay`            | Positions a panel beside an anchor or point, and reports when to dismiss it.  |
+
+Full documentation: [github.com/blagojablazhevski/gridkit](https://github.com/blagojablazhevski/gridkit#readme)
+
+## License
+
+MIT © Blagoja Blazhevski

package/dist/index.d.ts

@@ -0,0 +1,515 @@
+import { ColumnResizeSession, ColumnOrderState, GroupByState, GridFocus, NavigationModifiers, VisibleRange } from '@gridkitjs/core';
+
+/** A live region to report changes through. */
+interface LiveAnnouncer {
+    /**
+     * Has assistive technology read `text` out, politely — after whatever it is
+     * already saying. The same text twice in a row is read twice.
+     */
+    readonly announce: (text: string) => void;
+    /** Removes the live region. */
+    readonly destroy: () => void;
+}
+/**
+ * Creates the one live region a grid reports through — a reorder, a resize, a
+ * bulk selection, anything no visual cue can carry to a screen reader — as
+ * the last child of `container`.
+ *
+ * Polite rather than assertive, so an announcement waits for a pause instead
+ * of cutting across what the user is already hearing. The element carries
+ * `gridkit-sr-only`, which the theme clips to nothing while leaving it in the
+ * accessibility tree.
+ *
+ * A live region speaks only when its text changes, so a message identical to
+ * the last would go unheard. A no-break space, added and dropped in turn,
+ * makes the repeat a change without changing what is read.
+ */
+declare function createLiveAnnouncer(container?: HTMLElement): LiveAnnouncer;
+
+/** The data cell an event happened in. */
+interface BodyCellTarget {
+    /** The row's place among every body row, from its `data-gridkit-row-index`. */
+    readonly rowIndex: number;
+    /** The cell's place in its row, off the table's own indices. */
+    readonly columnIndex: number;
+    readonly columnId: string;
+}
+/** The group-header row an event happened in. */
+interface GroupRowTarget {
+    readonly rowIndex: number;
+    readonly groupId: string;
+}
+/** The body row an event happened in — a data row, or a group's header or summary. */
+interface BodyRowTarget {
+    readonly rowIndex: number;
+    /** The column of the cell it happened in, `null` when it was in none. */
+    readonly columnId: string | null;
+}
+/**
+ * The data cell `target` is in — what a renderer delegating its body's
+ * events to one listener asks of each event. `closest` is what makes the
+ * whole cell the target: a click on a template's own markup resolves to the
+ * cell holding it.
+ *
+ * Never matches inside a group-header row: that row's single `<td>` carries
+ * no `data-gridkit-column` (it spans every column at once, so no one column
+ * id applies), which keeps this to data rows without a check of its own.
+ */
+declare function bodyCellFrom(target: EventTarget | null): BodyCellTarget | null;
+/** The group-header row (`tr[data-gridkit-group]`) `target` is in. */
+declare function groupRowFrom(target: EventTarget | null): GroupRowTarget | null;
+/**
+ * The row `target` is in, cell or not — all a row click needs. The column is
+ * read only off a cell of that very row, so a table inside a cell template
+ * cannot lend it one of its own.
+ */
+declare function bodyRowFrom(target: EventTarget | null): BodyRowTarget | null;
+
+/**
+ * The `pointerdown` a gesture starts from. A native `PointerEvent` is one,
+ * and so is a framework's wrapper around it, such as React's synthetic
+ * event, so a renderer passes whichever its handler received.
+ */
+interface PointerPress {
+    readonly pointerId: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly button: number;
+    readonly isPrimary: boolean;
+    preventDefault(): void;
+}
+
+interface ColumnResizeGestureHandlers {
+    /** Every pointer move, with the width the column takes there. */
+    readonly onMove: (width: number) => void;
+    /**
+     * The pointer was released. `width` is the width to commit, or `null` when
+     * it ended where it started: a click on the handle — as each half of a
+     * double-click is — is not a resize, and reporting one would fire a
+     * spurious resize on every click.
+     */
+    readonly onEnd: (width: number | null) => void;
+    /** Escape, or a cancelled pointer: the column goes back to `session.startWidth`. */
+    readonly onCancel: () => void;
+}
+/**
+ * Drags a column's edge from `press` on its resize `handle`, turning pointer
+ * positions into widths through `@gridkitjs/core`'s `session` — begun with
+ * `beginColumnResize` — and reporting them. Returns whether a resize began:
+ * only the primary button of the primary pointer starts one.
+ *
+ * Captures the pointer on `handle`, so the drag keeps reporting wherever the
+ * pointer goes, and prevents the press's default, so it does not select the
+ * header text it started on. No minimum distance, unlike a reorder drag: the
+ * handle does nothing else a press could have meant.
+ */
+declare function startColumnResizeGesture(handle: HTMLElement, press: PointerPress, session: ColumnResizeSession, handlers: ColumnResizeGestureHandlers): boolean;
+/**
+ * The width the widest cell in `columnId` needs to show its content in full,
+ * or `null` when the column has no cells — what double-clicking a resize
+ * handle sizes the column to, through `sizeColumnToContent`.
+ *
+ * Measured with a `Range` over each cell's contents rather than the cell's own
+ * `scrollWidth`. A range shrink-wraps what is actually laid out, so a column
+ * far wider than its content reports the content width and can be sized *down*;
+ * `scrollWidth` never reports less than the cell it is read from and so can
+ * only ever grow a column.
+ *
+ * Only rendered rows are measured — on a paged or virtualized grid, the ones
+ * on screen.
+ */
+declare function measureColumnContent(table: HTMLTableElement, columnId: string): number | null;
+
+/** What a renderer draws while a reorder drag is open. */
+interface DragReorderState<Target> {
+    /** The item being dragged, once the press has become a drag. */
+    readonly draggedId: string | null;
+    /** Where it would land if released now, `null` for nowhere valid. */
+    readonly dropTarget: Target | null;
+    /** Where the element trailing the pointer sits, as a CSS `transform`. */
+    readonly ghostTransform: string | null;
+}
+/** The state while nothing is dragged — the one a drag reports when it ends. */
+declare const NO_DRAG: DragReorderState<never>;
+interface DragReorderHandlers<Target> {
+    /**
+     * Where a drop at `(clientX, clientY)` would land, or `null` for nowhere
+     * valid — including a gap `id` already occupies, so a drop target only
+     * ever promises a move that happens. Called on every pointer move once the
+     * drag has opened. `resolveColumnDropTarget` and
+     * `resolveGroupByDropTarget` are the grid's own.
+     */
+    readonly resolveTarget: (clientX: number, clientY: number, id: string) => Target | null;
+    /** Every change to what the renderer draws, `NO_DRAG` once the drag ends. */
+    readonly onState: (state: DragReorderState<Target>) => void;
+    /** The pointer was released over a valid target. */
+    readonly onDrop: (target: Target, id: string) => void;
+}
+/**
+ * The pointer mechanics behind every drag-to-reorder gesture in the grid — a
+ * column header dragged among the others or into the group-by bar, a
+ * group-by chip dragged within it: capture, the drag threshold, and the ghost
+ * trailing the pointer, holding the spot it was picked up by. Returns whether
+ * a gesture began; only the main button of the primary pointer starts one.
+ *
+ * The press is left to its default, so the pressed element still takes focus;
+ * until the pointer has travelled `DRAG_THRESHOLD` pixels nothing is
+ * reported, so a press that never moves stays a click. Escape, or a cancelled
+ * pointer, leaves the order as it was.
+ *
+ * Pointer events rather than HTML5 drag-and-drop: `dragenter`/`dragleave`
+ * fire per descendant, so a dragged item's own inner markup would each report
+ * the target leaving and re-entering as the pointer crossed them.
+ */
+declare function startDragReorder<Target>(id: string, grabElement: HTMLElement, press: PointerPress, handlers: DragReorderHandlers<Target>): boolean;
+
+/** A drop into the group-by bar, in front of `beforeColumnId` — `null` to append. */
+interface GroupByDropTarget {
+    readonly kind: "group-by";
+    readonly beforeColumnId: string | null;
+}
+/**
+ * Where a dragged column header would land: among the other headers, in
+ * front of `beforeId` (`null` for the end), or in the group-by bar.
+ */
+type ColumnDropTarget = {
+    readonly kind: "column-order";
+    readonly beforeId: string | null;
+} | GroupByDropTarget;
+interface ColumnDropContext {
+    /** The ids of the columns on screen, in order — what a drop is resolved among. */
+    readonly order: ColumnOrderState;
+    /** What a drop onto the group-by bar is resolved against. */
+    readonly groupBy: GroupByState;
+    /** Column ids whose header may be dragged into the group-by bar at all. */
+    readonly groupByDraggableIds: ReadonlySet<string>;
+}
+/**
+ * Where a header or chip dropped at `(clientX, clientY)` would land within
+ * the group-by bar (`[data-gridkit-group-by-bar]`, its chips
+ * `[data-gridkit-group-chip]`), or `null` when the pointer isn't over the bar
+ * at all, or when the drop would change nothing. Shared by a header dragged
+ * in from outside the bar and a chip dragged within it, so the two can never
+ * disagree about where a drop lands.
+ */
+declare function resolveGroupByDropTarget(clientX: number, clientY: number, movedId: string, groupBy: GroupByState): GroupByDropTarget | null;
+/**
+ * Where the header of `movedId` dropped at `(clientX, clientY)` would land:
+ * before or after another header (`th[data-gridkit-column]`), by which half
+ * of it the pointer is over, or else in the group-by bar — or `null` for
+ * nowhere a drop would change anything.
+ *
+ * A column already grouped never targets the bar: reordering it there is its
+ * chip's job, not its header's.
+ */
+declare function resolveColumnDropTarget(clientX: number, clientY: number, movedId: string, { order, groupBy, groupByDraggableIds }: ColumnDropContext): ColumnDropTarget | null;
+
+/**
+ * Reports `element`'s inner width now and on every change after, until the
+ * returned function disconnects it — what `resizeMode: "fit"` fills.
+ *
+ * The first report is synchronous, so a renderer calling this before paint
+ * lays its columns out at the right width from the first frame rather than
+ * visibly jumping once the observer's first callback arrives.
+ *
+ * Reads `clientWidth` rather than the observer entry's `contentRect` so the
+ * first report and every later one come from the same, already-rounded,
+ * source.
+ */
+declare function observeElementWidth(element: HTMLElement, onWidth: (width: number) => void): () => void;
+
+/**
+ * The window of rows a row virtualizer has drawn, and a way to bring a row
+ * into it — what a focus move needs when its target row may not be mounted.
+ */
+interface FocusVirtualRange {
+    readonly startIndex: number;
+    readonly endIndex: number;
+    readonly scrollToIndex: (index: number) => void;
+}
+/** How to find the rendered rows the browser's focus moves among. */
+interface GridFocusRows {
+    /** The header row's element, `null` while none is rendered. */
+    readonly getHeaderRow: () => HTMLTableRowElement | null;
+    /** Body row `rowIndex`'s element — `findBodyRow` finds it — `null` while it is not rendered. */
+    readonly getBodyRow: (rowIndex: number) => HTMLTableRowElement | null;
+}
+interface GridFocusOptions {
+    /** Body rows, counting group headers and summaries — every row a key could step through. */
+    readonly rowCount: number;
+    readonly columnCount: number;
+    /**
+     * Rows the vertical keys step over rather than stop on — a group's own
+     * summary row, which takes a row slot but is not a stop of its own.
+     */
+    readonly isSkippableRow?: ((rowIndex: number) => boolean) | undefined;
+    /**
+     * The window the renderer drew, when rows are virtualized. A move can
+     * target a row outside it — `ArrowDown` past its end, or `Ctrl+End` — that
+     * no lookup would find until it is scrolled into range.
+     */
+    readonly virtualRange?: FocusVirtualRange | null | undefined;
+}
+interface GridFocusController {
+    /**
+     * The cell holding the grid's single tab stop, clamped into the current
+     * row and column counts. The same object until it changes, so it can serve
+     * as a renderer's snapshot.
+     */
+    readonly getFocus: () => GridFocus;
+    /** Calls `listener` whenever the focused cell moves. Returns the unsubscribe. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /**
+     * Replaces the options, as a renderer does on every render with its
+     * current counts and window. Calls no listener: the renderer calling it is
+     * already drawing.
+     */
+    readonly setOptions: (options: GridFocusOptions) => void;
+    /**
+     * Moves the tab stop, and the browser's focus with it once the renderer
+     * has drawn the move (see `focusDrawnCell`). Moving to the cell already
+     * focused does nothing, which is what lets a cell's own `focus` event
+     * report a click through here without a loop.
+     */
+    readonly focusCell: (rowIndex: number, columnIndex: number) => void;
+    /**
+     * Moves the tab stop as `key` does — the arrows, Home, End, the page keys,
+     * with Ctrl for the grid's corners. Returns whether the key was one of
+     * them, in which case the caller prevents its default: taken even when the
+     * move lands nowhere, or an arrow at the last row would scroll the page
+     * out from under the grid.
+     */
+    readonly handleKey: (key: string, modifiers: NavigationModifiers, pageSize: number) => boolean;
+    /**
+     * Connects the tab stop to the rendered rows, which the browser's focus
+     * then follows it among. Returns the function that disconnects them.
+     */
+    readonly attach: (rows: GridFocusRows) => () => void;
+    /**
+     * Called by the renderer once it has drawn `drawn` — a value `getFocus`
+     * returned — so the browser's focus follows a move to the cell now in the
+     * markup. Does nothing unless a move to exactly that drawing is pending.
+     */
+    readonly focusDrawnCell: (drawn: GridFocus) => void;
+}
+/**
+ * Body row `rowIndex` in `bodyTable`, by its `data-gridkit-row-index` rather
+ * than by its position in `tBodies[0].rows`: a virtualized body holds only a
+ * slice of the rows, behind a leading spacer `<tr>`, so once the window
+ * scrolls a DOM position no longer matches the row's index in the full array
+ * and addresses some other mounted row, or none.
+ *
+ * The attribute holds a plain integer, so the selector needs no escaping,
+ * unlike one built from a consumer's row id.
+ */
+declare function findBodyRow(bodyTable: HTMLTableElement | null, rowIndex: number): HTMLTableRowElement | null;
+/**
+ * How many rows fit `bodyTable`'s scroll wrapper — its parent, the row area
+ * alone, not the header, footer and pager around it — which is what a page
+ * key moves. Reads the first rendered row's height, and falls back to ten
+ * rows when nothing can be measured.
+ */
+declare function measurePageSize(bodyTable: HTMLTableElement | null): number;
+/**
+ * The grid's single tab stop and the keys that move it, which is what
+ * `role="grid"` obliges: arrow keys travel cell to cell and Tab passes the
+ * whole grid by. The renderer attaches its rows, draws `getFocus()` —
+ * `tabindex="0"` on that cell, `-1` on every other — re-reads it when
+ * `subscribe` calls, and calls `focusDrawnCell` after drawing.
+ *
+ * Separate from selection, because focus and selection are different states:
+ * a cell is focused while travelling before anything is selected, and every
+ * cell of a range is selected without being focused. Navigation also has to
+ * work with selection off entirely.
+ *
+ * Starts on the header row's first cell.
+ */
+declare function createGridFocus(initialOptions: GridFocusOptions): GridFocusController;
+
+interface InfiniteScrollOptions {
+    /**
+     * The element whose approach triggers a load — the always-last row of the
+     * body — or `null` while none is rendered.
+     */
+    readonly sentinel: Element | null;
+    /** Whether a further load could still return more rows. `false` stops watching altogether. */
+    readonly hasMore: boolean;
+    /**
+     * Called at most once per approach: when the sentinel comes within
+     * `rootMargin` of the root's visible area, and not again until
+     * `isLoadingMore` has gone from `true` back to `false`.
+     */
+    readonly onLoadMore?: (() => void) | undefined;
+    /** Whether a load `onLoadMore` started is still in flight. */
+    readonly isLoadingMore?: boolean | undefined;
+    /** How far ahead of the sentinel scrolling into view a load starts, as CSS margins. Defaults to `"200px"`. */
+    readonly rootMargin?: string | undefined;
+}
+interface InfiniteScroll {
+    /**
+     * Takes the current options. Cheap when nothing changed, so a renderer may
+     * call it after every render; a new sentinel or `rootMargin` restarts the
+     * observer, and `isLoadingMore` going back to `false` re-checks at once.
+     */
+    readonly update: (options: InfiniteScrollOptions) => void;
+    /** Stops watching for good. */
+    readonly detach: () => void;
+}
+/**
+ * Turns a sentinel's approach to the bottom of the scrolling `root` into
+ * `onLoadMore` calls, no more than one per "the sentinel is near and no load
+ * is in flight since the last one finished".
+ *
+ * Three facts drive it: whether the sentinel is intersecting (as of the
+ * observer's last report), whether `onLoadMore` has fired since the last
+ * load finished, and whether a load was in flight at the last update. They
+ * outlive the sentinel itself, which a renderer mounts and unmounts as
+ * `hasMore` changes, so they live here rather than on any one observer.
+ *
+ * Off means off: with `hasMore` false, or no sentinel, no observer exists.
+ */
+declare function attachInfiniteScroll(root: Element, options: InfiniteScrollOptions): InfiniteScroll;
+
+/** Which side of its anchor an overlay opens on. */
+type OverlaySide = "top" | "bottom" | "left" | "right";
+/**
+ * Which edge of the anchor the overlay lines up with along that side: its
+ * left edge (`start`) or right edge (`end`) for `top`/`bottom`, its top or
+ * bottom edge for `left`/`right`.
+ */
+type OverlayAlign = "start" | "end";
+type OverlayPlacement = `${OverlaySide}-${OverlayAlign}`;
+/** A box in viewport coordinates, as `getBoundingClientRect` reports one. */
+interface OverlayRect {
+    readonly top: number;
+    readonly left: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface OverlaySize {
+    readonly width: number;
+    readonly height: number;
+}
+interface OverlayPlacementOptions {
+    /** Where the overlay would rather open. Defaults to `"bottom-start"`. */
+    readonly placement?: OverlayPlacement | undefined;
+    /** Space between the anchor and the overlay, in pixels. Defaults to `0`. */
+    readonly gap?: number | undefined;
+}
+/** Where an overlay goes: its top-left corner, and the placement it ended up with. */
+interface OverlayPosition {
+    readonly top: number;
+    readonly left: number;
+    readonly placement: OverlayPlacement;
+}
+/**
+ * Where an overlay of size `panel` goes beside `anchor` so that it stays in
+ * `viewport`: on the preferred side unless only the opposite one has room,
+ * lined up with the preferred edge unless that runs it off screen and the
+ * other edge does not, and finally pushed back inside if it still overflows.
+ * Pure, so the rules are testable without a browser; `attachOverlay` feeds it
+ * the measurements.
+ *
+ * A point — a context menu opened where the pointer is — is an anchor with
+ * no width or height, which is what makes `start`/`end` mean "after" and
+ * "before" it.
+ */
+declare function placeOverlay(anchor: OverlayRect, panel: OverlaySize, viewport: OverlaySize, options?: OverlayPlacementOptions): OverlayPosition;
+
+/** What an overlay opens beside: an element, or a point in viewport coordinates. */
+type OverlayAnchor = Element | {
+    readonly x: number;
+    readonly y: number;
+};
+/** Why an overlay asked to close. */
+type OverlayDismissReason = "escape" | "outside" | "scroll" | "resize" | "blur";
+interface OverlayOptions extends OverlayPlacementOptions {
+    /**
+     * The overlay asks to close: Escape was pressed, a pointer went down
+     * outside it, something outside it scrolled, the window resized or lost
+     * focus, or focus moved outside it. The caller closes it — removes the
+     * panel and detaches — or keeps it open by doing nothing.
+     */
+    readonly onDismiss: (reason: OverlayDismissReason) => void;
+    /**
+     * Where focus goes when the overlay detaches. Defaults to the element that
+     * had focus when it attached; `null` leaves focus alone.
+     */
+    readonly returnFocusTo?: HTMLElement | null | undefined;
+}
+/**
+ * Shows `panel` as an overlay beside `anchor` — a menu, a popover, a filter
+ * editor — and returns the function that ends it. The caller renders the
+ * panel, usually as a child of `document.body` so no scrolling ancestor clips
+ * it; this positions it, moves focus into it, and reports through
+ * `onDismiss` when the user is done with it.
+ *
+ * The panel is positioned `fixed`, at the place `placeOverlay` picks from the
+ * anchor's and the panel's measured boxes, and carries that placement in
+ * `data-gridkit-placement` (`"top-start"` once flipped above, say) for a
+ * stylesheet to point an arrow by. Focus moves to the panel's first focusable
+ * descendant, or to the panel itself — given `tabindex="-1"` if it has no
+ * `tabindex` — when there is none.
+ *
+ * Nothing that happens on or in the anchor dismisses the overlay, so a button
+ * that toggles it can close it with its own click rather than having the
+ * overlay close and the click reopen it.
+ *
+ * Detaching removes every listener and returns focus, but only when focus is
+ * still in the panel or nowhere — a click that dismissed it by landing on
+ * another control leaves focus on that control.
+ */
+declare function attachOverlay(anchor: OverlayAnchor, panel: HTMLElement, options: OverlayOptions): () => void;
+
+interface RowVirtualizerOptions {
+    /** The height assumed for a row not yet measured. */
+    readonly estimatedRowHeight: number;
+    /** Rows rendered beyond each edge of the visible area. */
+    readonly overscan: number;
+    /**
+     * The window of rows to render moved: called whenever a scroll, a resize
+     * of the scroll element, a measured row height or a change of rows moves
+     * it, and never with a window equal to the last.
+     */
+    readonly onRange: (range: VisibleRange) => void;
+}
+interface RowVirtualizer {
+    /** How many rows there are. Measured heights of the rows that remain are kept. */
+    readonly setRowCount: (count: number) => void;
+    /** Forgets every measured height, for rows that are no longer the ones measured. */
+    readonly resetHeights: () => void;
+    /**
+     * A ref callback for the element of row `index` (its place among all the
+     * rows, not among those rendered): measured while mounted, forgotten once
+     * called with `null`. The same function for the same index every time, so
+     * a renderer re-attaching it on every render costs nothing.
+     */
+    readonly measureRow: (index: number) => (element: HTMLElement | null) => void;
+    /**
+     * Scrolls so row `index` is in view. A mounted row is scrolled to directly;
+     * one outside the window is jumped to at its estimated offset, then
+     * scrolled to properly once it mounts and can be measured.
+     */
+    readonly scrollToIndex: (index: number, options?: ScrollIntoViewOptions) => void;
+    /** Stops listening and measuring, for good. */
+    readonly destroy: () => void;
+}
+/**
+ * Windows a long list of rows inside `scrollElement` down to those near its
+ * scroll position, measuring each rendered row's real height rather than
+ * assuming a uniform one — rows are not uniform (`.is-wrapped` cells, group
+ * header and summary rows), so a fixed-height virtualizer would either break
+ * wrapping or rule it out. The renderer draws `onRange`'s window, with
+ * spacers of `offsetBefore`/`offsetAfter` around it, and hands each row's
+ * element to `measureRow`.
+ *
+ * The heights are a mutable array, not a structure rebuilt per measurement:
+ * one can arrive many times a second while scrolling. The pure arithmetic
+ * over them is `@gridkitjs/core`'s `visibleRange`; this owns only the
+ * mutability around it and the listeners that feed it — the scroll position,
+ * the scroll element's height, and one `ResizeObserver` shared by every
+ * mounted row.
+ */
+declare function createRowVirtualizer(scrollElement: HTMLElement, options: RowVirtualizerOptions): RowVirtualizer;
+
+export { type BodyCellTarget, type BodyRowTarget, type ColumnDropContext, type ColumnDropTarget, type ColumnResizeGestureHandlers, type DragReorderHandlers, type DragReorderState, type FocusVirtualRange, type GridFocusController, type GridFocusOptions, type GridFocusRows, type GroupByDropTarget, type GroupRowTarget, type InfiniteScroll, type InfiniteScrollOptions, type LiveAnnouncer, NO_DRAG, type OverlayAlign, type OverlayAnchor, type OverlayDismissReason, type OverlayOptions, type OverlayPlacement, type OverlayPlacementOptions, type OverlayPosition, type OverlayRect, type OverlaySide, type OverlaySize, type PointerPress, type RowVirtualizer, type RowVirtualizerOptions, attachInfiniteScroll, attachOverlay, bodyCellFrom, bodyRowFrom, createGridFocus, createLiveAnnouncer, createRowVirtualizer, findBodyRow, groupRowFrom, measureColumnContent, measurePageSize, observeElementWidth, placeOverlay, resolveColumnDropTarget, resolveGroupByDropTarget, startColumnResizeGesture, startDragReorder };