@gridkitjs/dom 0.0.0-dev-20261106222533

package/dist/index.d.ts

@@ -0,0 +1,901 @@
+import { ColumnResizeSession, ColumnOrderState, GroupByState, GridFocus, NavigationModifiers, VisibleRange, ResolvedToolbarItem, PrintPage } 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;
+
+interface ChecklistOptions {
+    /**
+     * The item at `index` — its place in the whole list — asks to be checked
+     * or unchecked: Space on it, or a click. The caller flips it in its own
+     * state and draws the new `aria-checked`.
+     */
+    readonly onToggle: (index: number) => void;
+    /** Focus moved to the item at `index`, by a key, a click or a script. */
+    readonly onFocusChange?: ((index: number) => void) | undefined;
+    /**
+     * Bring the item at `index` into view, mounting it if the list's window
+     * does not hold it. A virtualized renderer forwards this to its
+     * virtualizer's `scrollToIndex`, with `{ block: "nearest" }` so a move of
+     * one item scrolls by one item.
+     */
+    readonly scrollToIndex: (index: number) => void;
+}
+interface AttachedChecklist {
+    /**
+     * How many items the whole list holds, mounted or not. Starts at 0, so a
+     * renderer calls this straight after attaching, and again whenever the
+     * list changes — a search narrowing it, say. A focused place past the new
+     * end moves back to the last item.
+     */
+    readonly setCount: (count: number) => void;
+    /**
+     * Focuses the item at `index`, clamped to the list, scrolling to it first.
+     * An item outside the mounted window is focused once it mounts.
+     */
+    readonly focusItem: (index: number) => void;
+    /** Removes every listener and observer. The items keep their `tabindex`. */
+    readonly detach: () => void;
+}
+/**
+ * Makes `list` — a `role="listbox"` the renderer drew, usually virtualized
+ * so that only a window of a long list is mounted — behave as a
+ * multi-select checklist with one tab stop: the arrow keys, Home, End,
+ * PageUp and PageDown move focus among its items, and Space or a click asks
+ * for the focused item to be toggled. It decides; the caller is told through
+ * the callbacks and draws the outcome, `aria-checked` included.
+ *
+ * Items are the list's descendants with `data-gridkit-checklist-item` and a
+ * `data-gridkit-checklist-index`: their place in the whole list rather than
+ * in the window, since an item's place is all that survives it being
+ * unmounted and mounted again. The list is the element that scrolls: PageUp
+ * and PageDown move by as many items as it shows whole.
+ *
+ * One item at a time has `tabindex="0"` — the focused one, or the first
+ * mounted while the focused one is scrolled away — and the rest `-1`, kept
+ * so as items mount by an observer of the list's children rather than by
+ * the renderer. A move to an item outside the window asks `scrollToIndex`
+ * for it and focuses it once it mounts, unless focus has gone somewhere
+ * else in the meantime.
+ *
+ * Enter is not handled, so a form around the list hears it and applies;
+ * Escape is the overlay stack's.
+ */
+declare function attachChecklist(list: HTMLElement, options: ChecklistOptions): AttachedChecklist;
+
+/**
+ * How a context menu was asked for: by a pointer — a right-click, or a touch
+ * held still — or by the keyboard.
+ */
+type ContextMenuSource = "pointer" | "keyboard";
+/** A context menu asked for inside the root, as `onRequest` hears of it. */
+interface ContextMenuRequest {
+    /** The element it was asked for on: the one under the pointer, or the one focused for a key. */
+    readonly target: Element;
+    /**
+     * Where the pointer was, in viewport coordinates — where a menu opened by
+     * it goes. `null` from the keyboard, which has no point: a menu it opens
+     * goes beside the focused element instead.
+     */
+    readonly point: {
+        readonly x: number;
+        readonly y: number;
+    } | null;
+    readonly source: ContextMenuSource;
+}
+interface ContextMenuTriggerOptions {
+    /**
+     * A context menu was asked for inside the root. Returns whether the caller
+     * opened one of its own: if so the browser's menu is prevented, and if not
+     * it shows as it would have.
+     */
+    readonly onRequest: (request: ContextMenuRequest) => boolean;
+}
+/**
+ * Reports every context menu the user asks for inside `root` — a right-click,
+ * Shift+F10, the ContextMenu key, or a touch held still for half a second —
+ * through `onRequest`, and returns the function that stops it.
+ *
+ * Each gesture asks once. Pressing a key, or holding a touch, also makes some
+ * browsers fire `contextmenu` of their own, and that event is taken, not
+ * reported again, once the gesture opened a menu. The click a touch brings
+ * as it lifts is taken too: the menu opened under the finger, and the click
+ * would land in it.
+ *
+ * An event something already prevented is left alone, so a cell template
+ * that shows a menu of its own keeps it. That is why the listeners are on the
+ * document, in the bubble phase: a framework that handles events at its own
+ * root container — React does — hears them before the document does, where
+ * a listener on `root` itself would hear them first. Only events whose target
+ * is inside `root` count.
+ */
+declare function attachContextMenuTrigger(root: Element, options: ContextMenuTriggerOptions): () => void;
+
+/**
+ * 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 `writeClipboard` puts on the clipboard: the same copy as plain text and as HTML. */
+interface ClipboardContent {
+    readonly text: string;
+    readonly html: string;
+}
+/**
+ * Whether a copy key pressed at `target` belongs to the browser: pressed in a
+ * text field, or with text highlighted anywhere on the page. Either way the
+ * user means the text in front of them, and a grid copying its own cell
+ * instead would take that from them.
+ */
+declare function isNativeCopy(target: EventTarget | null): boolean;
+/**
+ * Puts `content` on the clipboard as both `text/plain` and `text/html`, so a
+ * paste into a spreadsheet splits into cells and one into a word processor
+ * keeps its table. Call it from a user's gesture — a key press, a menu
+ * choice — as browsers allow the clipboard only then.
+ *
+ * Tries each way a browser offers, best first: the async Clipboard API with
+ * a `ClipboardItem` holding both types; then its `writeText`, plain text
+ * alone, where `ClipboardItem` is missing or refused; then the legacy `copy`
+ * event, for a page outside a secure context, where the async API is not
+ * there at all. Rejects only when every one fails.
+ */
+declare function writeClipboard(content: ClipboardContent): Promise<void>;
+
+/**
+ * Saves `blob` as a file named `fileName` — the browser's own download, as a
+ * link with a `download` attribute starts one, so nothing is opened or
+ * navigated to.
+ *
+ * The link is put in the document for the click, as Firefox has needed, and
+ * taken out straight after. Its object URL is revoked a task later rather
+ * than at once: Safari starts the download from the URL after the click
+ * returns, and a URL revoked synchronously is gone before it does.
+ */
+declare function downloadBlob(blob: Blob, fileName: string): void;
+
+/** 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;
+
+/**
+ * Where focus goes when a submenu opens: its first item, or nowhere — it
+ * stays on the item that opened it, as when the pointer opened it.
+ */
+type MenuSubmenuFocus = "first" | "none";
+/** Why a menu asked for every menu to close. */
+type MenuCloseReason = "tab";
+interface MenuOptions {
+    /**
+     * An enabled item that opens no submenu was chosen — Enter, Space or a
+     * click. The caller runs it, and closes every menu.
+     */
+    readonly onActivate: (id: string) => void;
+    /**
+     * An enabled submenu item asks for its submenu: Enter, Space or ArrowRight
+     * on it want its first item focused (`"first"`), a click or the pointer
+     * resting on it want focus left where it is (`"none"`). It may come for a
+     * submenu already open — ArrowRight on one the pointer opened — when a
+     * `"first"` asks for focus to move into it (`focusItem(0)` on its menu).
+     * Opening it closes any other submenu open from this menu.
+     */
+    readonly onOpenSubmenu?: ((id: string, options: {
+        readonly focus: MenuSubmenuFocus;
+    }) => void) | undefined;
+    /**
+     * The pointer came to rest on an item that opens no submenu, or a disabled
+     * one: close whatever submenu is open from this menu, if any. Moving on to
+     * another item is how a pointer user leaves a submenu they did not want.
+     */
+    readonly onCollapseSubmenu?: (() => void) | undefined;
+    /**
+     * ArrowLeft was pressed in this menu, which is a submenu: close it, and
+     * focus goes back to the item that opened it. Passed only for a submenu —
+     * in a menu without it, ArrowLeft does nothing.
+     */
+    readonly onCloseSubmenu?: (() => void) | undefined;
+    /**
+     * Tab or Shift+Tab was pressed: close every menu, so focus returns to where
+     * the first one was opened from rather than moving on past it.
+     */
+    readonly onClose: (reason: MenuCloseReason) => void;
+}
+interface AttachedMenu {
+    /**
+     * Focuses an item, by its `data-gridkit-menu-item` id or its place among
+     * the items. Does nothing for an item the menu does not have.
+     */
+    readonly focusItem: (item: string | number) => void;
+    /** Removes every listener. The items keep the `tabindex` they had. */
+    readonly detach: () => void;
+}
+/**
+ * Makes `panel` — a `role="menu"` element the renderer drew — behave as a
+ * menu: the arrow keys, Home, End and typeahead move focus among its items,
+ * Enter, Space and a click choose one, ArrowRight and ArrowLeft open and
+ * close submenus, and the pointer moves focus to the item under it. It
+ * decides; the caller is told through the callbacks and draws the outcome —
+ * runs the item, opens or closes a submenu.
+ *
+ * Items are the panel's descendants with a menu item role (`menuitem`,
+ * `menuitemcheckbox`, `menuitemradio`) and a `data-gridkit-menu-item` id,
+ * read afresh on every key so items drawn since attaching count. A submenu
+ * item says so with `aria-haspopup="menu"`; an item with
+ * `aria-disabled="true"` takes focus, so a screen reader finds it, but is
+ * never chosen. One item at a time has `tabindex="0"` — the focused one, or
+ * the first — and the rest `-1`: every item can take focus, and the first is
+ * what an overlay's initial focus finds when the menu is attached before it.
+ *
+ * Escape is not handled: a menu is shown with `attachOverlay`, whose stack
+ * gives Escape to the topmost overlay. A submenu is a menu of its own, in an
+ * overlay of its own anchored to its item, attached when it opens.
+ */
+declare function attachMenu(panel: HTMLElement, options: MenuOptions): AttachedMenu;
+
+/** 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;
+    /**
+     * Pixels to shift the overlay along the anchor's edge — down beside a
+     * `left`/`right` side, right beside `top`/`bottom`; negative goes the other
+     * way. A submenu opened `right-start` takes its own top padding, negated,
+     * so its first item lines up with the item that opened it. The overlay is
+     * still kept on screen. Defaults to `0`.
+     */
+    readonly offset?: 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;
+};
+/**
+ * Where focus goes when an overlay attaches: its first focusable descendant,
+ * the panel itself, nowhere — focus stays where it was — or a given element.
+ */
+type OverlayInitialFocus = "first" | "panel" | "none" | HTMLElement;
+/** Why an overlay asked to close. */
+type OverlayDismissReason = "escape" | "outside" | "scroll" | "resize" | "blur" | "parent";
+interface OverlayOptions extends OverlayPlacementOptions {
+    /**
+     * The overlay asks to close: Escape was pressed while it was the topmost
+     * overlay, a pointer went down outside it, something outside it scrolled,
+     * the window resized or lost focus, focus moved outside it, or the overlay
+     * it was opened above detached. The caller closes it — removes the panel
+     * and detaches — or keeps it open by doing nothing, except after
+     * `"parent"`, which detaches it regardless.
+     */
+    readonly onDismiss: (reason: OverlayDismissReason) => void;
+    /**
+     * Where focus goes on attaching. Defaults to `"first"`: a menu focuses its
+     * first item. A panel whose first control is not where the user starts — a
+     * filter editor's operator picker before its value box — passes that
+     * element, or `"panel"` to land on the panel itself; `"none"` leaves focus
+     * where it was, as a suggestion list does while typing goes on in the
+     * field that opened it.
+     */
+    readonly initialFocus?: OverlayInitialFocus | undefined;
+    /**
+     * 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;
+    /**
+     * Whether a scroll outside the panel just after input inside it — an
+     * `input` or `change` event, in the two animation frames that follow it —
+     * leaves it open. A panel whose controls change the page under it opts
+     * in: a column chooser hiding a column narrows the grid it opened from,
+     * and the browser scrolls that grid back within its narrower content.
+     * Defaults to `false`, where every scroll outside the panel dismisses it.
+     */
+    readonly ignoreScrollAfterInput?: boolean | undefined;
+    /**
+     * Whether Tab and Shift+Tab stay inside the panel: from its last tabbable
+     * element Tab moves to its first, and Shift+Tab from its first to its last,
+     * as a dialog keeps them. Defaults to `false`, where tabbing out of the
+     * panel moves focus outside it, which dismisses it with `"blur"`. Only
+     * the keys are kept: a pointer down outside still dismisses it, and so
+     * does focus moved out by any other route.
+     */
+    readonly trapFocus?: boolean | 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. Whenever the panel's size changes — a list
+ * that shrinks under a search — it is placed again beside the anchor, so a
+ * panel flipped above its anchor keeps its bottom edge there — or beside
+ * where the anchor was, once it has left the page. Focus moves
+ * where `initialFocus` says.
+ *
+ * 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.
+ *
+ * Overlays stack in the order they attach. Escape belongs to the topmost
+ * alone, which takes it: it closes a submenu without closing the menu under
+ * it, and nothing else on the page — a grid that clears its selection on
+ * Escape — hears it. An overlay counts everything in the overlays above it
+ * as inside itself, so a click in a submenu keeps its menu open while a click
+ * elsewhere in the menu closes only the submenu.
+ *
+ * Detaching removes every listener and returns focus, but only when focus is
+ * still in the panel, in an overlay above it, or nowhere — a click that
+ * dismissed it by landing on another control leaves focus on that control.
+ * Any overlay still above it is dismissed with `"parent"` and detached first.
+ */
+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;
+
+/**
+ * Makes `toolbar` — a `role="toolbar"` element the renderer drew — one tab
+ * stop that the arrow keys move within, following the WAI-ARIA toolbar
+ * pattern: ArrowRight and ArrowLeft move focus to the next and previous
+ * control, wrapping round the ends, and Home and End to the first and last.
+ * Returns the function that stops it.
+ *
+ * The toolbar's entries are its descendants with a `data-gridkit-toolbar-item`,
+ * and each entry's control is the entry itself when it can take focus, else
+ * the first element in it that can; an entry with none — a separator, a
+ * spacer — is passed over. They are read afresh on every key. One control at
+ * a time has `tabindex="0"` — the focused one, or the first — and the rest
+ * `-1`, kept so as entries come and go; a control with
+ * `aria-disabled="true"` stays one of them, so a screen reader finds it.
+ *
+ * A text field keeps the keys it needs: Home and End, and an arrow while
+ * the caret has text to move through in that direction. At the start or end
+ * of its text, the arrow moves on to the next control.
+ */
+declare function attachToolbar(toolbar: HTMLElement): () => void;
+
+/**
+ * A toolbar entry as the overflow reads it: its kind, the key its element
+ * carries and, for a button or a dropdown, its label — a change to which,
+ * while the entry is in "More" and not drawn, makes the width remembered for
+ * it stale.
+ */
+type ToolbarOverflowItem = Pick<ResolvedToolbarItem, "type" | "key"> & {
+    readonly label?: string | undefined;
+};
+interface ToolbarOverflowOptions {
+    /**
+     * Every entry of the toolbar, in order — those drawn and those moved into
+     * "More" alike — as `resolveToolbar` gave them.
+     */
+    readonly items: readonly ToolbarOverflowItem[];
+    /**
+     * How many entries fit, as `fitToolbarItems` counts them: called once
+     * straight away, then whenever the count changes.
+     */
+    readonly onChange: (fit: number) => void;
+}
+interface ToolbarOverflow {
+    /**
+     * Call whenever the items change, with the current options: measures
+     * again, and reports a changed count.
+     */
+    readonly update: (options: ToolbarOverflowOptions) => void;
+    /** Stops observing. */
+    readonly detach: () => void;
+}
+/**
+ * Measures how many of a toolbar's entries fit in it, reporting the count
+ * through `onChange` straight away — so a renderer calling this before
+ * paint draws the right entries from the first frame — and again whenever a
+ * resize changes it. The arithmetic is @gridkitjs/core's `fitToolbarItems`:
+ * the search box and custom entries always stay, and room for "More" is kept
+ * only when something does not fit.
+ *
+ * Entries are found by their `data-gridkit-toolbar-item`, holding each
+ * item's `key`, and the "More" button by `data-gridkit-toolbar-more`. An
+ * entry moved into "More" is no longer drawn, so each width is remembered
+ * by key from the last time it was; one never drawn yet counts as nothing,
+ * which lets it be drawn, measured, and moved back out if it does not fit —
+ * as one whose label changed while it was not drawn counts again.
+ * A spacer counts as nothing too: its width is only the room left over. The
+ * toolbar's padding and the `column-gap` between entries are allowed for.
+ *
+ * It measures again whenever the toolbar or an entry resizes and whenever
+ * entries are drawn or taken away — the ones the count it reported let in,
+ * or the "More" button — so a renderer only has to draw what it is told,
+ * and to pass new items to `update`.
+ */
+declare function observeToolbarOverflow(toolbar: HTMLElement, options: ToolbarOverflowOptions): ToolbarOverflow;
+
+/** What `printDocument` prints: a document's title, its body's markup and its stylesheet. */
+interface PrintDocumentOptions {
+    /** The document's title, as text — what the browser puts in a page's header and names a saved PDF. */
+    readonly title: string;
+    /** The `<body>`'s markup, as `buildPrintDocument` writes it. */
+    readonly bodyHtml: string;
+    /** The document's whole stylesheet — `printStyles(page)`, and anything added after it. */
+    readonly styles: string;
+}
+/**
+ * Prints a document through a hidden frame: its own page, holding only
+ * `bodyHtml` under `styles`, so what is printed is what was built — every
+ * row, not the slice of them a virtualised grid has drawn — and nothing of
+ * the page around it. The frame loads, waits for its fonts, opens the
+ * print dialog, and is removed once the dialog closes, when the promise
+ * resolves; focus goes back where it was. A frame rather than a new window,
+ * which a popup blocker would stop.
+ *
+ * One print at a time: a call while a print is open resolves at once
+ * without printing.
+ */
+declare function printDocument(options: PrintDocumentOptions): Promise<void>;
+
+/**
+ * The stylesheet a print of `buildPrintDocument`'s markup needs, for `page`.
+ * A print frame sees none of the page's CSS, so this carries what makes the
+ * table read on paper and nothing of a theme: the paper's size and
+ * orientation; a header row repeated at the top of every page; rows kept
+ * whole across a page break; neutral one-pixel borders; group headers
+ * stepped in by depth; backgrounds printed as they are rather than dropped
+ * to save ink; page numbers in the bottom-right margin, where the browser
+ * draws `@page` margin boxes; and for `fitToWidth`, a smaller font in fixed
+ * columns that wrap their text.
+ *
+ * The grand total prints once, after the last row — not repeated at the
+ * foot of every page, where browsers repeat a `<tfoot>`, as a total of
+ * rows the page does not hold would mislead. Add CSS after it to restyle.
+ */
+declare function printStyles(page: PrintPage): string;
+
+export { type AttachedChecklist, type AttachedMenu, type BodyCellTarget, type BodyRowTarget, type ChecklistOptions, type ClipboardContent, type ColumnDropContext, type ColumnDropTarget, type ColumnResizeGestureHandlers, type ContextMenuRequest, type ContextMenuSource, type ContextMenuTriggerOptions, type DragReorderHandlers, type DragReorderState, type FocusVirtualRange, type GridFocusController, type GridFocusOptions, type GridFocusRows, type GroupByDropTarget, type GroupRowTarget, type InfiniteScroll, type InfiniteScrollOptions, type LiveAnnouncer, type MenuCloseReason, type MenuOptions, type MenuSubmenuFocus, NO_DRAG, type OverlayAlign, type OverlayAnchor, type OverlayDismissReason, type OverlayInitialFocus, type OverlayOptions, type OverlayPlacement, type OverlayPlacementOptions, type OverlayPosition, type OverlayRect, type OverlaySide, type OverlaySize, type PointerPress, type PrintDocumentOptions, type RowVirtualizer, type RowVirtualizerOptions, type ToolbarOverflow, type ToolbarOverflowItem, type ToolbarOverflowOptions, attachChecklist, attachContextMenuTrigger, attachInfiniteScroll, attachMenu, attachOverlay, attachToolbar, bodyCellFrom, bodyRowFrom, createGridFocus, createLiveAnnouncer, createRowVirtualizer, downloadBlob, findBodyRow, groupRowFrom, isNativeCopy, measureColumnContent, measurePageSize, observeElementWidth, observeToolbarOverflow, placeOverlay, printDocument, printStyles, resolveColumnDropTarget, resolveGroupByDropTarget, startColumnResizeGesture, startDragReorder, writeClipboard };