@ahrowe/ui 0.35.0 → 0.37.0

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

@@ -0,0 +1,59 @@
+import { default as React } from 'react';
+import { VirtualListColumn } from './virtualList.types.js';
+interface UseColumnResizeArgs<T> {
+    columns?: VirtualListColumn<T>[];
+    /**
+     * The columns currently rendered, in order. A ref rather than a value because
+     * the visible set is derived one hook later, and only the freeze reads it, at
+     * event time.
+     */
+    visibleColumnsRef: React.RefObject<VirtualListColumn<T>[]>;
+    resizableColumns: boolean;
+    /** Controlled widths. When provided, internal state is ignored. */
+    columnWidths?: Record<string, number>;
+    onColumnWidthsChange?: (widths: Record<string, number>) => void;
+    /** Restores widths saved under this key. Uncontrolled mode only. */
+    persistColumnsKey?: string;
+    rootRef: React.RefObject<HTMLDivElement | null>;
+}
+export interface UseColumnResizeResult<T> {
+    widths: Record<string, number>;
+    /**
+     * True once every visible column has an exact px width. Nothing moves at that
+     * moment, but from then on the layout is pixels rather than `fr`/`fit`.
+     */
+    isFrozen: boolean;
+    isResizing: boolean;
+    /** Drops every user width and hands the layout back to the column definitions. */
+    reset: () => void;
+    /** Whether this column takes a resize at all, by handle or by keyboard. */
+    isResizable: (col: VirtualListColumn<T>) => boolean;
+    /** Widens (or, negative, narrows) one column. The keyboard entry point. */
+    resizeBy: (key: string, delta: number) => void;
+    /** Takes one column down to its minimum. */
+    resizeToMin: (key: string) => void;
+    /** Sizes one column to its widest rendered cell. */
+    autoFit: (key: string) => void;
+    /** Pointer props for one column's handle, or null when that column can't be resized. */
+    getHandleProps: (col: VirtualListColumn<T>) => React.HTMLAttributes<HTMLDivElement> | null;
+}
+/**
+ * User column resizing: the width state, and a drag that doesn't go through
+ * React.
+ *
+ * A pointer move writes the dragged column's custom property straight onto the
+ * list element. The header and every row read that same property, so one DOM
+ * write resizes all of them in a single layout pass. Going through state
+ * instead would re-render the header plus every visible row on every frame, and
+ * the handle would trail the cursor by one frame, which is the whole difference
+ * between this feeling attached to the pointer and feeling cheap. React is told
+ * once, on release.
+ *
+ * The first resize **freezes** every visible column to its measured width. A
+ * `fr` track can't express "this one column is now 240px" without the others
+ * silently absorbing the difference, and once they hit their minimum the dragged
+ * edge stops following the cursor, which is the worst moment for it to happen.
+ * Frozen, the table is exact pixels and simply scrolls horizontally instead.
+ */
+export declare function useColumnResize<T>({ columns, visibleColumnsRef, resizableColumns, columnWidths, onColumnWidthsChange, persistColumnsKey, rootRef, }: UseColumnResizeArgs<T>): UseColumnResizeResult<T>;
+export {};

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,63 @@
+import { default as React } from 'react';
+import { TreeDropPosition, TreeDropTarget } from './virtualList.types.js';
+import { ListViewportRect } from './useVirtualWindow.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)[]>;
+    /** Where the list is on screen, which is not its own box once it rides a
+     *  scrollport — owned by useVirtualWindow, as is `scrollBy`. */
+    getVisibleRect: () => ListViewportRect | null;
+    scrollBy: (dy: number) => void;
+}
+/** 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, getVisibleRect, scrollBy, }: UseRowDragArgs): UseRowDragResult;
+export {};

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

@@ -0,0 +1,60 @@
+import { default as React } from 'react';
+import { VirtualListScrollOptions } from './virtualList.types.js';
+import { VisibleSlice } from './useVirtualWindow.js';
+interface UseRowNavigationArgs {
+    enabled: boolean;
+    tabAcrossRows: 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>;
+    /** Read live: a held arrow key moves the slice faster than the state commits. */
+    getVisibleSlice: () => VisibleSlice;
+    /** The whole scrollport, which is what one PageDown covers. */
+    viewportHeight: number;
+    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.
+ *
+ * `tabAcrossRows` adds the second pair, Tab and Shift+Tab, which the browser
+ * cannot carry across a row boundary itself: the next row may not be in the DOM
+ * when it looks for the next stop.
+ */
+export declare function useRowNavigation({ enabled, tabAcrossRows, rowCount, offsets, rootRef, headerRef, getVisibleSlice, viewportHeight, 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,55 @@
+import { default as React } from 'react';
+import { VirtualListHandle, VirtualListScrollParent } 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;
+    scrollParent?: VirtualListScrollParent;
+}
+/** Where the list is on screen, which is not its own box once it rides a scrollport. */
+export interface ListViewportRect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+/** The list-space slice currently on screen, read live for keyboard navigation. */
+export interface VisibleSlice {
+    top: number;
+    height: number;
+}
+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;
+    /** The list's visible slice, which is what decides which rows are rendered. */
+    containerHeight: number;
+    /** The whole scrollport, which is what a scroll target is aimed within. */
+    viewportHeight: number;
+    containerWidth: number;
+    startIndex: number;
+    endIndex: number;
+    showLoadMoreSpinner: boolean;
+    isWindowed: boolean;
+    getVisibleSlice: () => VisibleSlice;
+    getVisibleRect: () => ListViewportRect | null;
+    scrollBy: (dy: number) => void;
+    /** 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, scrollParent, }: 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>(props: VirtualListProps<T>): React.JSX.Element;
+export default VirtualList;