@ahrowe/ui 0.35.0 → 0.36.0

package/dist/cjs-types/common/virtualList/useColumns.d.ts

@@ -0,0 +1,52 @@
+import { default as React } from 'react';
+import { VirtualListColumn } from './virtualList.types.js';
+interface UseColumnsArgs<T> {
+    columns?: VirtualListColumn<T>[];
+    items: T[];
+    multiSelect: boolean;
+    visibleColumnKeys?: string[];
+    onVisibleColumnsChange?: (keys: string[]) => void;
+    persistColumnsKey?: string;
+    showColumnToggle?: boolean;
+    /** User-set column widths, from `useColumnResize`. */
+    userWidths: Record<string, number>;
+    /** Whether those widths have taken over the layout. */
+    isFrozen: boolean;
+    rootRef: React.RefObject<HTMLDivElement | null>;
+    /** Visible-window bounds — re-measure `fit` columns as new cells scroll in. */
+    startIndex: number;
+    endIndex: number;
+    containerHeight: number;
+    /** Re-measure `fit` columns when the container width settles (e.g. after a route transition). */
+    containerWidth: number;
+}
+export interface UseColumnsResult<T> {
+    hasColumns: boolean;
+    visibleColumns: VirtualListColumn<T>[];
+    columnTemplate: string | undefined;
+    /**
+     * Custom properties for the list element: the total width of a frozen layout,
+     * as a `calc()` over the per-column properties so that rewriting one width
+     * during a drag updates the total without any bookkeeping.
+     */
+    widthVars: React.CSSProperties;
+    shouldShowToggle: boolean;
+    effectiveVisible: Set<string>;
+    /** How many default-visible columns the user has hidden (excludes defaultHidden). */
+    manuallyHiddenCount: number;
+    toggleOpen: boolean;
+    setToggleOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    handleToggleColumn: (key: string) => void;
+    /** Imperative escape hatch: drop fit-column pins so they re-measure on the
+     *  next layout. For out-of-band content changes that don't flow through a new
+     *  `items` array or `columns` set (which reset automatically). */
+    recalculateColumns: () => void;
+}
+/**
+ * Table-mode column logic: visibility (controlled or uncontrolled, with
+ * localStorage persistence and runtime reconciliation), the toggle popover, and
+ * `fit`-column width measurement that pins one shared px track across the header
+ * and every row grid so they stay aligned.
+ */
+export declare function useColumns<T>({ columns, items, multiSelect, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, showColumnToggle, userWidths, isFrozen, rootRef, startIndex, endIndex, containerHeight, containerWidth, }: UseColumnsArgs<T>): UseColumnsResult<T>;
+export {};

package/dist/cjs-types/common/virtualList/useHeaderNavigation.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+interface StationProps {
+    tabIndex: number;
+    ref: (el: HTMLElement | null) => void;
+    onFocus: () => void;
+}
+interface UseHeaderNavigationResult {
+    getStationProps: (index: number) => StationProps;
+    /** True when the key moved the focus, so the caller stops handling it. */
+    handleNavigationKey: (event: React.KeyboardEvent, index: number) => boolean;
+}
+/**
+ * Roving tab stop across the header: the select-all cell, every column header,
+ * and the column menu are stations, and arrow keys move between them.
+ *
+ * Without it each of those is its own tab stop, so a table with eight sortable,
+ * resizable columns takes seventeen presses of Tab before the data. The stops
+ * also belong together: they all act on the same header, which is exactly the
+ * case the roving pattern exists for.
+ */
+export declare function useHeaderNavigation(stationCount: number): UseHeaderNavigationResult;
+export {};

package/dist/cjs-types/common/virtualList/useRowDrag.d.ts

@@ -0,0 +1,58 @@
+import { default as React } from 'react';
+import { TreeDropPosition, TreeDropTarget } from './virtualList.types.js';
+interface UseRowDragArgs {
+    reorderable: boolean;
+    treeReorder: boolean;
+    onReorder?: (fromIndex: number, toIndex: number) => void;
+    onTreeDrop?: (dragKey: string | number, target: TreeDropTarget) => void;
+    longPressDelay: number;
+    dragHandle: boolean;
+    treeIndentPx: number;
+    /** Current flat ordering and depth tags (mouse handlers read these directly). */
+    keys: (string | number)[];
+    depths: number[];
+    isGroupAt: (index: number) => boolean;
+    rootRef: React.RefObject<HTMLDivElement | null>;
+    /** Latest keys for async (touch / rAF) consumers — owned by useVirtualWindow. */
+    keysRef: React.RefObject<(string | number)[]>;
+}
+/** The drag-related props the parent spreads onto a given row. */
+export interface RowDragProps {
+    reorderable: boolean;
+    /** Native mouse DnD is active for the list (independent of which row is armed). */
+    mouseDragEnabled: boolean;
+    draggable: boolean | undefined;
+    isDragging: boolean;
+    onMouseDown: ((e: React.MouseEvent<HTMLDivElement>) => void) | undefined;
+    onMouseOver: ((e: React.MouseEvent<HTMLDivElement>) => void) | undefined;
+    onMouseLeave: ((e: React.MouseEvent<HTMLDivElement>) => void) | undefined;
+    onDragStart: ((e: React.DragEvent<HTMLDivElement>) => void) | undefined;
+    onDragOver: ((e: React.DragEvent<HTMLDivElement>) => void) | undefined;
+    onDragEnd: (() => void) | undefined;
+    onDrop: ((e: React.DragEvent<HTMLDivElement>) => void) | undefined;
+    onTouchStart: ((e: React.TouchEvent<HTMLDivElement>) => void) | undefined;
+    dropPosition: TreeDropPosition | undefined;
+    dropIndentPx: number | undefined;
+}
+interface UseRowDragResult {
+    /** True while a row is being dragged (for the root reordering style). */
+    draggingKey: string | number | null;
+    /** Whether either drag mode is active. */
+    dragEnabled: boolean;
+    /** Drag props for the row at `index` / `key`. */
+    getRowDragProps: (index: number, key: string | number) => RowDragProps;
+    /** Returns true (and resets) if the next click should be swallowed (post-drag). */
+    consumeSuppressedClick: () => boolean;
+}
+/**
+ * Row drag-and-drop for both modes:
+ * - `reorderable` (flat): native HTML5 drag on desktop; rows move live via
+ *   `onReorder` with midpoint hysteresis.
+ * - `treeReorder`: a drop indicator (before/after/inside) is shown during the
+ *   drag and `onTreeDrop` fires once on release; dropping onto the dragged
+ *   node's own subtree is forbidden.
+ * Touch uses a long-press → lifted-clone → pointer-move path with edge
+ * auto-scroll. `dragHandle` restricts initiation to `[data-drag-handle]`.
+ */
+export declare function useRowDrag({ reorderable, treeReorder, onReorder, onTreeDrop, longPressDelay, dragHandle, treeIndentPx, keys, depths, isGroupAt, rootRef, keysRef, }: UseRowDragArgs): UseRowDragResult;
+export {};

package/dist/cjs-types/common/virtualList/useRowNavigation.d.ts

@@ -0,0 +1,50 @@
+import { default as React } from 'react';
+import { VirtualListScrollOptions } from './virtualList.types.js';
+interface UseRowNavigationArgs {
+    enabled: boolean;
+    rowCount: number;
+    /** Row tops, from the windowing engine, used for paging and visibility. */
+    offsets: number[];
+    rootRef: React.RefObject<HTMLDivElement | null>;
+    headerRef: React.RefObject<HTMLDivElement | null>;
+    scrollToIndex: (index: number, options?: VirtualListScrollOptions) => void;
+    /** Row index the active row starts on, normally the selected one. */
+    initialIndex: number;
+    multiSelect: boolean;
+    /** Undefined when the consumer gave the rows no activation of their own. */
+    onActivate?: (index: number) => void;
+    onToggleSelect: (index: number) => void;
+}
+interface UseRowNavigationResult {
+    /** Index of the row the arrow keys are on, or -1 when navigation is off. */
+    activeIndex: number;
+    /** Keeps the arrow keys where the pointer last was. */
+    setActiveIndex: (index: number) => void;
+    /**
+     * The row currently being used, or -1. Its controls are in the tab order and
+     * it stays mounted even when it scrolls out of the window.
+     */
+    enteredIndex: number;
+    containerProps: {
+        tabIndex?: number;
+        onKeyDown?: (event: React.KeyboardEvent) => void;
+        onFocus?: (event: React.FocusEvent) => void;
+        onBlur?: (event: React.FocusEvent) => void;
+    };
+}
+/**
+ * Arrow-key navigation over the rows, with the tab stop on the list itself.
+ *
+ * The stop cannot sit on the active row, the way a roving tabindex normally
+ * would: a virtualized row unmounts when it scrolls out of the window, and the
+ * list would be left with no tab stop at all (the same reason `Tree` puts its
+ * stop on its container). Instead the list keeps the focus and points at the
+ * active row with `aria-activedescendant`.
+ *
+ * Keys are only handled when the list element itself has the focus. A cell may
+ * hold an input, a dropdown or a button, and every one of them wants the arrows,
+ * Enter and Space for itself. `F2` steps into such a row and `Escape` steps back
+ * out, which is the one pair of keys that does work from inside a cell.
+ */
+export declare function useRowNavigation({ enabled, rowCount, offsets, rootRef, headerRef, scrollToIndex, initialIndex, multiSelect, onActivate, onToggleSelect, }: UseRowNavigationArgs): UseRowNavigationResult;
+export {};

package/dist/cjs-types/common/virtualList/useSelection.d.ts

@@ -0,0 +1,24 @@
+interface UseSelectionArgs<T> {
+    items: T[];
+    getKey: (item: T, index: number) => string | number;
+    multiSelect: boolean;
+    /** Controlled selected keys. When provided, internal state is ignored. */
+    selectedKeys?: Set<string | number>;
+    onSelectionChange?: (keys: Set<string | number>) => void;
+}
+interface UseSelectionResult {
+    effectiveSelectedKeys: Set<string | number>;
+    /** Toggle one row's membership in the selection. */
+    handleRowSelect: (key: string | number) => void;
+    /** Select all rows, or clear if all are already selected. */
+    handleSelectAll: () => void;
+    allSelected: boolean;
+    someSelected: boolean;
+}
+/**
+ * Multi-row selection, controlled or uncontrolled. `allSelected`/`someSelected`
+ * (for the header checkbox) are O(n) scans, so they're only computed when
+ * `multiSelect` is on.
+ */
+export declare function useSelection<T>({ items, getKey, multiSelect, selectedKeys, onSelectionChange, }: UseSelectionArgs<T>): UseSelectionResult;
+export {};

package/dist/cjs-types/common/virtualList/useSorting.d.ts

@@ -0,0 +1,26 @@
+import { VirtualListColumn, VirtualListSort } from './virtualList.types.js';
+interface UseSortingArgs<T> {
+    items: T[];
+    columns?: VirtualListColumn<T>[];
+    /** Controlled sort. When provided, internal state is ignored. */
+    sort?: VirtualListSort | null;
+    defaultSort?: VirtualListSort | null;
+    onSortChange?: (sort: VirtualListSort | null) => void;
+}
+interface UseSortingResult<T> {
+    /** `items`, reordered when the sorted column carries a comparator. */
+    rows: T[];
+    effectiveSort: VirtualListSort | null;
+    /** True only when this hook reordered the rows, not when it merely reported. */
+    isSorted: boolean;
+    handleHeaderSort: (key: string) => void;
+}
+/**
+ * Header sorting, controlled or uncontrolled. Whether the list reorders the data
+ * or only reports the click is the column's decision, not a prop: a column with
+ * `sortValue`/`compare` is sorted here, a bare `sortable` one is left alone so a
+ * server-side sort can own it. Sorting a paginated list here would silently
+ * order only the rows loaded so far.
+ */
+export declare function useSorting<T>({ items, columns, sort, defaultSort, onSortChange, }: UseSortingArgs<T>): UseSortingResult<T>;
+export {};

package/dist/cjs-types/common/virtualList/useVirtualWindow.d.ts

@@ -0,0 +1,36 @@
+import { default as React } from 'react';
+import { VirtualListHandle } from './virtualList.types.js';
+interface UseVirtualWindowArgs<T> {
+    items: T[];
+    /** Stable key per row (already derived by the caller). */
+    keys: (string | number)[];
+    getItemKey?: (item: T, index: number) => string | number;
+    estimatedRowHeight: number;
+    rowGap: number | string;
+    overscan: number;
+    onLoadMore?: () => Promise<void>;
+    loadMoreThreshold: number;
+    /** Initial/filter load in progress — the body is replaced by a spinner. */
+    isLoading: boolean;
+}
+interface UseVirtualWindowResult {
+    rootRef: React.RefObject<HTMLDivElement | null>;
+    headerRef: React.RefObject<HTMLDivElement | null>;
+    /** Shared by every row to measure its height (read back via `data-index`). */
+    rowObserver: ResizeObserver | null;
+    /** Latest index → key mapping, for async consumers (e.g. the drag hook). */
+    keysRef: React.RefObject<(string | number)[]>;
+    offsets: number[];
+    totalHeight: number;
+    containerHeight: number;
+    containerWidth: number;
+    startIndex: number;
+    endIndex: number;
+    handleScroll: (e: React.UIEvent<HTMLDivElement>) => void;
+    showLoadMoreSpinner: boolean;
+    /** The scroll-related imperative methods, for the component to compose into
+     *  the forwarded handle alongside column controls. */
+    scrollApi: Omit<VirtualListHandle, 'recalculateColumns' | 'resetColumnWidths'>;
+}
+export declare function useVirtualWindow<T>({ items, keys, getItemKey, estimatedRowHeight, rowGap, overscan, onLoadMore, loadMoreThreshold, isLoading, }: UseVirtualWindowArgs<T>): UseVirtualWindowResult;
+export {};

package/dist/cjs-types/common/virtualList/virtualList.d.ts

@@ -0,0 +1,5 @@
+import { default as React } from 'react';
+import { VirtualListProps } from './virtualList.types.js';
+export { buildOffsets, findStartIndex, getVisibleRange, resolveReorderTarget, resolveTreeDropTarget, lastDescendantIndex, buildColumnTemplate, compareSortValues, isColumnSortable, isEmptySortValue, nextSort, sortItems, } from './virtualList.utils.js';
+declare function VirtualList<T>({ ref, items, renderRow, ariaRoles, columns, height, estimatedRowHeight, overscan, rowGap, rowPadding, selectedKey, getItemKey, onRowClick, keyboardNavigation, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, resizableColumns, columnWidths, onColumnWidthsChange, labels, sort, defaultSort, onSortChange, showColumnToggle, onLoadMore, loadMoreThreshold, isLoading, multiSelect, selectedKeys, onSelectionChange, reorderable, onReorder, longPressDelay, treeReorder, getItemDepth, isGroup, onTreeDrop, treeIndentPx, dragHandle, showDivider, rowHover, className, style, classNames, styles: slotStyles, ...rest }: VirtualListProps<T>): React.JSX.Element;
+export default VirtualList;

package/dist/cjs-types/common/virtualList/virtualList.types.d.ts

@@ -0,0 +1,317 @@
+import { CSSProperties, ReactNode, Ref } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+export type ColumnWidthFixed = {
+    type: 'fixed';
+    px: number;
+};
+export type ColumnWidthFlex = {
+    type: 'flex';
+    weight?: number;
+};
+export type ColumnWidthFit = {
+    type: 'fit';
+};
+export type ColumnWidthSpec = ColumnWidthFixed | ColumnWidthFlex | ColumnWidthFit;
+/** A value the built-in comparator can order. */
+export type SortValue = string | number | boolean | Date | null | undefined;
+export type SortDirection = 'asc' | 'desc';
+/** The column being sorted and the direction. `null` anywhere this appears means unsorted. */
+export interface VirtualListSort {
+    /** `key` of the sorted column. */
+    key: string;
+    direction: SortDirection;
+}
+export interface VirtualListColumn<T> {
+    key: string;
+    label: ReactNode;
+    width: ColumnWidthSpec;
+    renderCell: (item: T, rowIndex: number) => ReactNode;
+    defaultHidden?: boolean;
+    /**
+     * Text shown for this column in the gear toggle menu. Falls back to `label`.
+     * Useful for columns with an empty header (e.g. an actions column) so their
+     * menu entry reads as something meaningful instead of being blank.
+     */
+    toggleLabel?: ReactNode;
+    /**
+     * Prevent this column from being hidden via the toggle menu. It always stays
+     * visible (overriding `defaultHidden` and any controlled/persisted state), and
+     * its menu entry is rendered checked and disabled. Overrides `defaultHidden`.
+     */
+    lockVisible?: boolean;
+    /**
+     * Omit this column from the gear toggle menu entirely — no entry is shown for
+     * it. Unlike `lockVisible` (which shows a checked, disabled entry), the column
+     * simply isn't listed. Its visibility then follows `defaultHidden` /
+     * controlled / persisted state as usual; combine with `lockVisible` to keep it
+     * always visible and out of the menu. The gear button hides automatically if
+     * no column remains toggleable.
+     */
+    hideFromToggle?: boolean;
+    /**
+     * Value this column is ordered by. Its presence makes the column sortable and
+     * lets the list sort `items` itself. `null`/`undefined`/`NaN` sort last, in
+     * both directions.
+     */
+    sortValue?: (item: T) => SortValue;
+    /**
+     * Ascending comparator, for an order `sortValue` can't express. Wins over
+     * `sortValue`, and also makes the column sortable. Descending negates its
+     * result, so it has no equivalent of the empty-values-last rule.
+     */
+    compare?: (a: T, b: T) => number;
+    /**
+     * Floor this column can be dragged to, in px. Default 48.
+     */
+    minWidth?: number;
+    /** Opt this column out of resizing while the list has `resizableColumns`. */
+    resizable?: boolean;
+    /**
+     * Makes the header clickable without the list reordering anything: the sort is
+     * only reported through `onSortChange`. For server-side or paginated sorting,
+     * where sorting the loaded rows would silently sort part of the data. Ignored
+     * when `sortValue` or `compare` is given.
+     */
+    sortable?: boolean;
+}
+export interface VirtualListScrollOptions {
+    /** Where the target row lands in the viewport. Default: 'start'. */
+    align?: 'start' | 'center' | 'end';
+    /** Native scroll behaviour. Default: 'auto'. */
+    behavior?: ScrollBehavior;
+}
+/** Imperative handle exposed via `ref`. */
+export interface VirtualListHandle {
+    /** Scroll so the row at `index` is visible. */
+    scrollToIndex: (index: number, options?: VirtualListScrollOptions) => void;
+    /** Scroll to the row whose `getItemKey` matches `key` (no-op if not found). */
+    scrollToKey: (key: string | number, options?: VirtualListScrollOptions) => void;
+    /** Scroll back to the top. */
+    scrollToTop: (options?: Pick<VirtualListScrollOptions, 'behavior'>) => void;
+    /** The underlying scroll container element, for advanced use. */
+    getScrollElement: () => HTMLDivElement | null;
+    /**
+     * Re-measure `fit` columns on the next layout. Call this after an out-of-band
+     * content change that doesn't flow through a new `items` array or `columns`
+     * set (those reset automatically) — e.g. a cell's content grew in place.
+     */
+    recalculateColumns: () => void;
+    /**
+     * Drops every user-set column width and returns the table to the widths its
+     * columns declare. Also clears them from `persistColumnsKey` storage.
+     */
+    resetColumnWidths: () => void;
+}
+export type VirtualListSlots = 'root' | 'header' | 'headerCell' | 'headerToggle' | 'headerSort' | 'sortIcon' | 'resizeHandle' | 'activeRow' | 'togglePopover' | 'toggleItem' | 'toggleReset' | 'body' | 'row' | 'cell' | 'selectCell' | 'loadingIndicator' | 'dropIndicator' | 'columnChip';
+/** Where a tree-reorder drop lands relative to the row it is over. */
+export type TreeDropPosition = 'before' | 'inside' | 'after';
+/** The resolved drop target reported to `onTreeDrop`. */
+export interface TreeDropTarget {
+    /** `getItemKey` of the row the drop lands on. */
+    key: string | number;
+    /**
+     * `before`/`after` place the dragged node as a sibling of the target (at the
+     * target's depth); `inside` makes it a child of the target (only offered when
+     * `isGroup` returns true for that row).
+     */
+    position: TreeDropPosition;
+}
+/** Text VirtualList renders of its own, for translating it. */
+export interface VirtualListLabels {
+    /** A row's select checkbox, read out by screen readers. */
+    selectRow?: string;
+    /** The header's select-all checkbox, read out by screen readers. */
+    selectAllRows?: string;
+    /** The gear that opens the column menu, read out by screen readers. */
+    toggleColumns?: string;
+    /** The badge on the gear, given how many columns the user has hidden. */
+    columnsHidden?: (count: number) => string;
+    /** The entry in the column menu that undoes the user's column widths. */
+    resetColumnWidths?: ReactNode;
+}
+export interface VirtualListProps<T> extends HtmlProps {
+    items: T[];
+    /** Render function for list mode (no columns). Ignored when `columns` is provided. */
+    renderRow?: (item: T, index: number) => ReactNode;
+    /** Column definitions — presence enables table/header mode. */
+    columns?: VirtualListColumn<T>[];
+    /**
+     * Replaces the roles put on the container and rows (default `list`/`listitem`, or `grid`/`row`
+     * with columns). Pass `'none'` for both when the rows carry their own semantics, as `Tree` does.
+     */
+    ariaRoles?: {
+        container: string;
+        row: string;
+    };
+    /** Height of the scroll viewport. Defaults to '100%' to fill the parent container. */
+    height?: number | string;
+    /** Estimated row height before measurement. Default: 40. */
+    estimatedRowHeight?: number;
+    /** Extra rows to render above/below the visible window. Default: 3. */
+    overscan?: number;
+    /**
+     * Gap between rows. A number is treated as px; a string may be any CSS length
+     * (`'1em'`, `'0.5rem'`, `'1px'`, or a custom property like `'var(--spacing-s)'`).
+     * Non-px units / custom properties are resolved against the list element.
+     * Default: 0.
+     */
+    rowGap?: number | string;
+    /**
+     * Padding applied to every row. A number is treated as px; a string may be any
+     * CSS padding value (`'8px 12px'`, `'1em'`, `'var(--spacing-s)'`). Because each
+     * row's height is measured after layout, the padding is reflected in the
+     * virtualization automatically — no layout math is affected.
+     */
+    rowPadding?: number | string;
+    /** Show a divider line between rows. Default: true. */
+    showDivider?: boolean;
+    /**
+     * Highlight rows on hover. Default: true. Set false when the row content
+     * handles its own hover affordance (e.g. a Card per row), so the list's
+     * background doesn't fight it.
+     */
+    rowHover?: boolean;
+    /** Controlled selected row key. Matched against `getItemKey`. */
+    selectedKey?: string | number | null;
+    /** Returns a stable key per item. Defaults to row index. */
+    getItemKey?: (item: T, index: number) => string | number;
+    /** Called when a row is clicked. */
+    onRowClick?: (item: T, index: number) => void;
+    /**
+     * Arrow-key navigation over the rows, on by default. The list takes one tab
+     * stop, the arrows move an active row, Enter fires `onRowClick` and Space
+     * toggles the selection in `multiSelect`. Keys are ignored while the focus is
+     * inside a cell, so a control in a row keeps its own.
+     *
+     * Turn it off for a list whose rows already handle their own keys, the way
+     * `Tree` does.
+     */
+    keyboardNavigation?: boolean;
+    /** Controlled visible column keys. When provided, internal state is ignored. */
+    visibleColumnKeys?: string[];
+    /** Called when the user toggles a column in the popover. */
+    onVisibleColumnsChange?: (keys: string[]) => void;
+    /**
+     * When set, column visibility is saved to `localStorage` under this key and
+     * restored on the next mount of a list with the same key. Only applies in
+     * uncontrolled mode (ignored when `visibleColumnKeys` is provided). Newly
+     * added columns that weren't present when the settings were saved fall back
+     * to their `defaultHidden` value rather than the saved set.
+     */
+    persistColumnsKey?: string;
+    /**
+     * Controlled sort state. `null` is unsorted (source order). When provided,
+     * internal state is ignored.
+     */
+    sort?: VirtualListSort | null;
+    /** Initial sort in uncontrolled mode. Default: `null`. */
+    defaultSort?: VirtualListSort | null;
+    /**
+     * Called on each header click with the next step of the asc → desc → unsorted
+     * cycle. The list reorders `items` itself for columns that define `sortValue`
+     * or `compare`; for a `sortable` column it only reports, and sorting the data
+     * is yours to do.
+     */
+    onSortChange?: (sort: VirtualListSort | null) => void;
+    /**
+     * Lets the user drag a column's right edge to resize it, double-click it to fit
+     * the column to its content, or resize it from the keyboard once the handle has
+     * focus. The first resize pins every visible column to its current pixel width
+     * (nothing moves at that moment), after which the table is an exact pixel
+     * layout that scrolls horizontally rather than redistributing space.
+     */
+    resizableColumns?: boolean;
+    /** Controlled column widths in px, keyed by column key. */
+    columnWidths?: Record<string, number>;
+    /** Overrides the text VirtualList renders of its own. Merged per key. */
+    labels?: VirtualListLabels;
+    /** Called with the full width map whenever the user resizes or auto-fits a column. */
+    onColumnWidthsChange?: (widths: Record<string, number>) => void;
+    /** Show the gear column-toggle button in the header. Default: true when columns present. */
+    showColumnToggle?: boolean;
+    /**
+     * Called when the user scrolls within `loadMoreThreshold` px of the bottom, and
+     * repeatedly while the rows don't fill the viewport — a list too short to scroll
+     * would otherwise never ask for a second batch. Each row count is asked at most
+     * once, so the loop ends as soon as a call appends nothing; pass `undefined`
+     * once the source is exhausted to skip even that final probe.
+     * Must return a Promise that resolves once new items have been appended to `items`.
+     * A spinner is shown at the bottom while the Promise is pending.
+     */
+    onLoadMore?: () => Promise<void>;
+    /** Distance in px from the bottom that triggers `onLoadMore`. Default: 100. */
+    loadMoreThreshold?: number;
+    /** Replaces the list body with a full-height spinner (for initial/filter loads). */
+    isLoading?: boolean;
+    /** Enables multi-row selection with a checkbox column on the far left. */
+    multiSelect?: boolean;
+    /** Controlled set of selected item keys. When provided, internal state is ignored. */
+    selectedKeys?: Set<string | number>;
+    /** Called when the selection changes. */
+    onSelectionChange?: (keys: Set<string | number>) => void;
+    /**
+     * Enables drag-and-drop row reordering (native HTML5 drag — desktop/mouse).
+     * The whole row becomes draggable; pair with `onReorder` to apply the move.
+     * Provide `getItemKey` so reordered rows keep their measured heights.
+     */
+    reorderable?: boolean;
+    /**
+     * Called while the user drags a row over a new position. Fires live (on each
+     * change), so apply it immediately — e.g. `setItems(prev => move(prev, from, to))`.
+     */
+    onReorder?: (fromIndex: number, toIndex: number) => void;
+    /**
+     * Touch only: how long (ms) the user must press-and-hold a row before drag
+     * mode activates, so a normal swipe still scrolls the list. Default: 400.
+     */
+    longPressDelay?: number;
+    /**
+     * Enables tree drag-and-drop: instead of a flat reorder, a dragged row can be
+     * dropped `before`, `after`, or `inside` another row. Mutually exclusive with
+     * `reorderable` (if both are set, `treeReorder` wins). Unlike `reorderable`,
+     * rows are NOT moved live — a drop indicator is shown during the drag and
+     * `onTreeDrop` fires once on release. The list is still a flat array: hold the
+     * real tree in your own state, flatten the expanded nodes into `items` (each
+     * tagged with its depth), and re-flatten after applying the drop.
+     * Provide `getItemKey` so rows keep their measured heights across re-flattens.
+     */
+    treeReorder?: boolean;
+    /**
+     * Depth of each row in the tree (0 = root). Used to align the drop indicator
+     * and to forbid dropping a node onto itself or its own descendants. Defaults
+     * to 0 for every row.
+     */
+    getItemDepth?: (item: T, index: number) => number;
+    /**
+     * Whether a row can receive children — i.e. whether an `inside` drop is
+     * offered when hovering its middle third. Defaults to false (leaf) for every
+     * row, so only `before`/`after` are offered.
+     */
+    isGroup?: (item: T, index: number) => boolean;
+    /**
+     * Called once when a tree-reorder drag is released on a valid target. Apply
+     * the move to your tree state and re-flatten. Not called when the drop target
+     * is the dragged node itself or one of its descendants.
+     */
+    onTreeDrop?: (dragKey: string | number, target: TreeDropTarget) => void;
+    /**
+     * Indent (px per depth level) used to position the `before`/`after` drop
+     * indicator line so it aligns with where the dropped content will start.
+     * Match this to the per-level padding you apply to row content. Default: 24.
+     */
+    treeIndentPx?: number;
+    /**
+     * Restrict drag initiation to elements marked `data-drag-handle` within a row
+     * (rather than the whole row). Essential for rows containing editable inputs
+     * or other interactive controls, so clicking/typing/selecting text in them
+     * doesn't start a drag. Applies to both `reorderable` and `treeReorder`, mouse
+     * and touch. Render a handle in your row, e.g. `<span data-drag-handle>⠿</span>`.
+     */
+    dragHandle?: boolean;
+    /** Imperative handle for scrolling and for recalculating column layout. */
+    ref?: Ref<VirtualListHandle>;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<VirtualListSlots>;
+    styles?: SlotStyles<VirtualListSlots>;
+}