@box-kite/react 0.0.1 → 1.0.0

package/components/dataGrid/models/gridModel.d.ts

@@ -0,0 +1,206 @@
+import { ComponentsAndVariants } from '../../../types';
+import { ColumnFilters, DataGridProps, FilterValue, Key, PaginationState, PinPositionInput, SortDirection } from '../contracts/dataGridContract';
+import { default as ColumnModel } from './columnModel';
+import { default as ColumnVisibilityModel } from './columnVisibilityModel';
+import { default as DetailRowModel } from './detailRowModel';
+import { default as FilterModel } from './filterModel';
+import { default as GroupRowModel } from './groupRowModel';
+import { default as PaginationModel } from './paginationModel';
+import { default as RowModel } from './rowModel';
+import { default as ViewportModel } from './viewportModel';
+export declare const ROW_NUMBER_CELL_KEY: Key;
+export declare const DEFAULT_ROW_NUMBER_COLUMN_WIDTH = 70;
+export declare const ROW_SELECTION_CELL_KEY: Key;
+export declare const GROUPING_CELL_KEY: Key;
+export declare const ROW_DETAIL_CELL_KEY: Key;
+export default class GridModel<TRow> {
+    props: DataGridProps<TRow>;
+    constructor(props: DataGridProps<TRow>, onChange?: () => void);
+    private _version;
+    private readonly listeners;
+    /** Subscribe to changes; returns an unsubscribe function. */
+    subscribe: (listener: () => void) => (() => void);
+    /** Monotonic snapshot version — stable between changes, increments on notify(). */
+    getSnapshot: () => number;
+    /** Signal subscribers that state changed and a re-render is needed. */
+    notify: () => void;
+    /**
+     * Sync incoming props. Called during render by the framework adapter — clears
+     * the affected memos but does NOT notify (no extra render cycle; memos recompute
+     * lazily on next access).
+     */
+    setProps(props: DataGridProps<TRow>): void;
+    get componentName(): keyof ComponentsAndVariants;
+    private _identifier;
+    /**
+     * A unique prefix for the ids this grid wires ARIA with. Supplied by the adapter, because only
+     * the adapter can produce one that survives hydration — `useIdentifier` in React's case.
+     */
+    get identifier(): string;
+    setIdentifier(identifier: string): void;
+    /** The title's id: a grid is not named by the rows in it, so it is named by this. */
+    get titleId(): string;
+    get resizerStyle(): 'visible' | 'hover' | 'hidden';
+    get resizeMode(): 'smooth' | 'instant';
+    readonly sourceColumns: import('../../../utils/memo').Memo<ColumnModel<TRow>[]>;
+    readonly columns: import('../../../utils/memo').Memo<{
+        start: ColumnModel<TRow>[];
+        middle: ColumnModel<TRow>[];
+        end: ColumnModel<TRow>[];
+        flat: ColumnModel<TRow>[];
+        leafs: ColumnModel<TRow>[];
+        visibleLeafs: ColumnModel<TRow>[];
+        userVisibleLeafs: ColumnModel<TRow>[];
+        maxDeath: number;
+    }>;
+    readonly headerRows: import('../../../utils/memo').Memo<ColumnModel<TRow>[][]>;
+    readonly gridTemplateColumns: import('../../../utils/memo').Memo<string>;
+    private _globalFilterValue;
+    get globalFilterValue(): string;
+    private _columnFilters;
+    get columnFilters(): ColumnFilters<TRow>;
+    /**
+     * Apply global filter (fuzzy search across all or specified columns)
+     */
+    private applyGlobalFilter;
+    /**
+     * Apply column-level filters
+     */
+    private applyColumnFilters;
+    /**
+     * Check if a cell value matches a filter
+     */
+    private matchesFilter;
+    /**
+     * Apply external predicate filters from the filters prop
+     */
+    private applyExternalFilters;
+    /**
+     * Get filtered data (applies external, global, then column filters)
+     */
+    get filteredData(): TRow[];
+    private fireServerStateChange;
+    /**
+     * Set global filter value
+     */
+    setGlobalFilter: (value: string) => void;
+    /**
+     * Set a single column filter
+     */
+    setColumnFilter: (columnKey: Key, filter: FilterValue | undefined) => void;
+    /**
+     * Clear all column filters
+     */
+    clearColumnFilters: () => void;
+    /**
+     * Clear all filters (global + column)
+     */
+    clearAllFilters: () => void;
+    /**
+     * Get unique values for a column (used for multiselect filter options)
+     */
+    getColumnUniqueValues: (columnKey: Key) => (string | number | boolean | null)[];
+    /**
+     * Check if any filter is active
+     */
+    get hasActiveFilters(): boolean;
+    /**
+     * Get count of filtered rows vs total rows
+     */
+    get filterStats(): {
+        filtered: number;
+        total: number;
+    };
+    readonly rows: import('../../../utils/memo').Memo<GroupRowModel<TRow>[] | RowModel<TRow>[]>;
+    readonly flatRows: import('../../../utils/memo').Memo<(GroupRowModel<TRow> | RowModel<TRow> | DetailRowModel<TRow>)[]>;
+    get rowHeight(): number;
+    readonly sizes: import('../../../utils/memo').Memo<Record<string, string>>;
+    private _containerWidth;
+    get containerWidth(): number;
+    /**
+     * The DOM element that carries the column-sizing CSS variables (the grid container).
+     * Set by the React adapter. During a resize drag the adapter writes the width vars
+     * here directly — bypassing React re-renders — and only commits to state on release.
+     */
+    private _sizingElement;
+    get sizingElement(): HTMLElement | null;
+    setSizingElement: (el: HTMLElement | null) => void;
+    /**
+     * Which way the grid reads, resolved off the element the widths are written to. A model with no
+     * element yet — a server render, a headless host — reads as left to right, the initial value.
+     */
+    get isRtl(): boolean;
+    setContainerWidth: (width: number) => void;
+    readonly flexWidths: import('../../../utils/memo').Memo<Record<Key, number>>;
+    getFlexWidth(key: Key): number | undefined;
+    readonly DEFAULT_ROW_HEIGHT_PX = 48;
+    readonly MIN_COLUMN_WIDTH_PX = 48;
+    readonly DEFAULT_COLUMN_WIDTH_PX = 200;
+    expandedGroupRow: Set<Key>;
+    private _expandedDetailRows;
+    get expandedDetailRows(): Set<Key>;
+    toggleDetailRow: (rowKey: Key) => void;
+    private _page;
+    private _pageSize?;
+    get page(): number;
+    get pageSize(): number;
+    get pageSizeOptions(): number[] | undefined;
+    get isPaginated(): boolean;
+    get paginationState(): PaginationState | undefined;
+    changePage: (page: number) => void;
+    changePageSize: (size: number) => void;
+    readonly rowOffsets: import('../../../utils/memo').Memo<{
+        offsets: number[];
+        totalHeight: number;
+    }>;
+    /** Headless virtualization (windowing math; scrollTop is owned by the adapter). */
+    readonly viewport: ViewportModel<TRow>;
+    /** Backs the top-bar column-visibility menu. */
+    readonly columnVisibility: ColumnVisibilityModel<TRow>;
+    /** Filtering concern (grid-level state + derived flags). */
+    readonly filter: FilterModel<TRow>;
+    /** Pagination concern (navigation + row-range derivations). */
+    readonly pagination: PaginationModel<TRow>;
+    /** Whether any user-facing column is currently visible (else the empty-columns state shows). */
+    get hasVisibleColumns(): boolean;
+    get isEmpty(): boolean;
+    /** Header select-all checkbox state. */
+    get allRowsSelected(): boolean;
+    get someRowsSelected(): boolean;
+    private _selectionAnnounced;
+    /**
+     * What the grid's live region says. Ticking a checkbox halfway down a virtualized grid changes nothing a
+     * screen reader would read, so the count is announced instead — and it stays empty until a selection has
+     * happened, since some readers announce a region that already holds text on mount.
+     */
+    get selectionAnnouncement(): string;
+    /** The columns currently grouped, resolved from groupColumns keys (backs the top-bar group chips). */
+    get groupedColumns(): ColumnModel<TRow>[];
+    selectedRows: Set<Key>;
+    get inlineStartEdge(): number;
+    get inlineEndEdge(): number;
+    readonly inlineStartEdgeVarName = "--inline-start-edge";
+    readonly rowHeightVarName = "--row-height";
+    readonly viewportWidthVarName = "--viewport-width";
+    private readonly _idMap;
+    private _autoId;
+    private readonly _idFactory;
+    getRowKey(row: TRow): Key;
+    setSortColumn: (columnKey: Key, sortDirection?: SortDirection) => void;
+    pinColumn: (uniqueKey: string, pin?: PinPositionInput) => void;
+    toggleGrouping: (columnKey: Key) => void;
+    unGroupAll: () => void;
+    toggleGroupRow: (groupRowKey: Key) => void;
+    toggleRowSelection: (rowKey: Key) => void;
+    toggleRowsSelection: (rowKeys: Key[]) => void;
+    toggleSelectAllRows: () => void;
+    toggleColumnVisibility: (columnKey: Key) => void;
+    setWidth: (columnKey: Key, width: number) => void;
+    groupColumns: Set<Key>;
+    hiddenColumns: Set<Key>;
+    columnWidths: Map<Key, number>;
+    private _sortColumn?;
+    get sortColumn(): Key | undefined;
+    private _sortDirection?;
+    get sortDirection(): SortDirection | undefined;
+}

package/components/dataGrid/models/groupRowCellModel.d.ts

@@ -0,0 +1,26 @@
+import { default as ColumnModel } from './columnModel';
+import { default as GridModel } from './gridModel';
+import { default as GroupRowModel } from './groupRowModel';
+/**
+ * How a cell participates in a group row's layout: `grouping` is the expand/label cell spanning the
+ * grouped columns, `selection` the select-all cell, `spacer` a pinned or leading cell with its own value,
+ * and `hidden` a data column absorbed into the grouping cell's span.
+ */
+export type GroupRowCellKind = 'grouping' | 'selection' | 'spacer' | 'hidden';
+export default class GroupRowCellModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    readonly row: GroupRowModel<TRow>;
+    readonly column: ColumnModel<TRow>;
+    constructor(grid: GridModel<TRow>, row: GroupRowModel<TRow>, column: ColumnModel<TRow>);
+    get value(): string | number | null;
+    get isExpanded(): boolean;
+    get isFirst(): boolean;
+    get isLast(): boolean;
+    get cellKind(): GroupRowCellKind;
+    get depthPadding(): number;
+    get gridColumnSpan(): number;
+    get widthVar(): string;
+    get isEndPinned(): boolean;
+    /** Grouping cell shows a right border only when the grouping column is left-pinned. */
+    get hasGroupingBorder(): boolean;
+}

package/components/dataGrid/models/groupRowModel.d.ts

@@ -0,0 +1,48 @@
+import { Key } from '../contracts/dataGridContract';
+import { default as ColumnModel } from './columnModel';
+import { default as DetailRowModel } from './detailRowModel';
+import { default as GridModel } from './gridModel';
+import { default as GroupRowCellModel } from './groupRowCellModel';
+import { default as RowModel } from './rowModel';
+export default class GroupRowModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    readonly groupColumn: ColumnModel<TRow>;
+    readonly rows: RowModel<TRow>[] | GroupRowModel<TRow>[];
+    readonly rowIndex: number;
+    readonly groupValue: Key;
+    constructor(grid: GridModel<TRow>, groupColumn: ColumnModel<TRow>, rows: RowModel<TRow>[] | GroupRowModel<TRow>[], rowIndex: number, groupValue: Key);
+    get key(): Key;
+    parentRow?: GroupRowModel<TRow>;
+    private readonly _cells;
+    get cells(): GroupRowCellModel<TRow>[];
+    /**
+     * The cells this row actually renders, each with the column it starts at. A `hidden` cell is a
+     * data column the grouping cell has absorbed into its span: no element, and nothing to navigate
+     * to — which is why a group row's cell positions and its `aria-colindex` values differ.
+     */
+    private readonly _renderedCells;
+    get renderedCells(): {
+        cell: GroupRowCellModel<TRow>;
+        columnIndex: number;
+    }[];
+    /** Fewer than the column count — the width the grid navigation sees for this row. */
+    get cellCount(): number;
+    /**
+     * Where a cell starts in column-index space. The cells the grouping cell spans are not rendered
+     * at all, so an ordinal here is short of its column by however many of them came before it.
+     */
+    columnOf(cell: number): number;
+    get selected(): boolean;
+    get indeterminate(): boolean;
+    get expanded(): boolean;
+    get depth(): number;
+    get count(): number;
+    get flatRows(): (RowModel<TRow> | GroupRowModel<TRow> | DetailRowModel<TRow>)[];
+    get allRows(): RowModel<TRow>[];
+    get groupingColumn(): ColumnModel<TRow>;
+    get groupingColumnGridColumn(): number;
+    readonly kind: "group";
+    toggleRow(): void;
+    /** Select/deselect every leaf row under this group. */
+    toggleSelectAll: () => void;
+}

package/components/dataGrid/models/headerCellModel.d.ts

@@ -0,0 +1,83 @@
+import { SortDirection } from '../contracts/dataGridContract';
+import { default as ColumnModel } from './columnModel';
+/** All derived state for rendering a column's header cell and its context menu. */
+export default class HeaderCellModel<TRow> {
+    readonly column: ColumnModel<TRow>;
+    constructor(column: ColumnModel<TRow>);
+    private get grid();
+    /** Header label. `null` for the row-number and selection cells (rendered specially). */
+    get label(): string | number | null;
+    /**
+     * A name for a header that draws nothing. The row-number and row-detail columns are blank on
+     * screen by design, and a blank column header leaves every cell under it unlabelled — which is
+     * the one thing a screen reader relies on when it reads a cell out.
+     */
+    get hiddenLabel(): string | undefined;
+    get isSortable(): boolean;
+    get isSorted(): boolean;
+    get sortDirection(): SortDirection | undefined;
+    get showResizer(): boolean;
+    get showContextMenu(): boolean;
+    /** Grid column span: a leaf occupies one column, a group header spans its leaf count. */
+    get gridColumn(): number;
+    /** 1-based `aria-colindex`: the first column this header covers. */
+    get columnIndex(): number;
+    /** `aria-colspan`, left off when the header covers a single column. */
+    get columnSpan(): number | undefined;
+    /** `aria-rowspan`: a leaf declared above the deepest level reaches down to the bottom row. */
+    get rowSpan(): number | undefined;
+    /**
+     * `aria-sort`. A sortable column that is not the sorted one still carries `none`: that is what
+     * tells a screen reader the column *can* be sorted, and leaving it off says the opposite.
+     */
+    get ariaSort(): 'ascending' | 'descending' | 'none' | undefined;
+    /** What the resizer names itself. A separator carries no text, so it has nothing else to go on. */
+    get resizerLabel(): string;
+    /** `aria-valuenow`: how wide the column is right now, in px. */
+    get width(): number;
+    /** `aria-valuemin`: every leaf the header covers at the narrowest the grid allows. */
+    get minWidth(): number;
+    /**
+     * `aria-valuemax`. There is no width the grid refuses — a drag can take a column past the
+     * viewport and scroll to it — so the ceiling the keyboard offers is the grid's own width, raised
+     * to whatever a drag has already made it so that `aria-valuenow` stays inside the range.
+     */
+    get maxWidth(): number;
+    /** Room for the sort icon, which sits where the reading ends — so an end-aligned header needs it in front. */
+    get paddingStart(): number | undefined;
+    get paddingEnd(): number | undefined;
+    /** Variant flags for the header cell. */
+    get variant(): {
+        isPinned: boolean;
+        isFirstStartPinned: boolean;
+        isLastStartPinned: boolean;
+        isFirstEndPinned: boolean;
+        isLastEndPinned: boolean;
+        isSortable: boolean;
+        isRowNumber: boolean;
+        isFirstLeaf: boolean;
+        isLastLeaf: boolean;
+    };
+    /** Variant flags for the context-menu trigger button. */
+    get contextMenuButtonVariant(): {
+        isPinned: boolean;
+        isFirstStartPinned: boolean;
+        isLastStartPinned: boolean;
+        isFirstEndPinned: boolean;
+        isLastEndPinned: boolean;
+        isSortable: boolean;
+        isRowNumber: boolean;
+    };
+    private get sections();
+    get canSortAsc(): boolean;
+    get canSortDesc(): boolean;
+    get canClearSort(): boolean;
+    get canPinStart(): boolean;
+    get canPinEnd(): boolean;
+    get canUnpin(): boolean;
+    get canGroupBy(): boolean;
+    get canUnGroupAll(): boolean;
+    get hasSortSection(): boolean;
+    get hasPinSection(): boolean;
+    get hasGroupSection(): boolean;
+}

package/components/dataGrid/models/paginationModel.d.ts

@@ -0,0 +1,32 @@
+import { PaginationState } from '../contracts/dataGridContract';
+import { default as GridModel } from './gridModel';
+/**
+ * Pagination concern: navigation state + derived row range for the bottom bar / pager.
+ * The coupled mutations (page-reset on filter/sort, server-state events) live on GridModel;
+ * this model owns the navigation behavior and derivations the UI needs.
+ */
+export default class PaginationModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    constructor(grid: GridModel<TRow>);
+    get isPaginated(): boolean;
+    get state(): PaginationState | undefined;
+    get pageSizeOptions(): number[] | undefined;
+    get page(): number;
+    get pageSize(): number;
+    get totalPages(): number;
+    get totalItems(): number;
+    get canGoPrev(): boolean;
+    get canGoNext(): boolean;
+    /** 1-based index of the first row on the current page. */
+    get startItem(): number;
+    /** 1-based index of the last row on the current page (clamped to totalItems). */
+    get endItem(): number;
+    changePage: (page: number) => void;
+    changePageSize: (size: number) => void;
+    firstPage: () => void;
+    prevPage: () => void;
+    nextPage: () => void;
+    lastPage: () => void;
+    /** Parse a raw page-jump input and navigate (clamped to [1, totalPages]); ignores non-numeric input. */
+    jumpToPage: (raw: string) => void;
+}

package/components/dataGrid/models/rowModel.d.ts

@@ -0,0 +1,34 @@
+import { Key } from '../contracts/dataGridContract';
+import { default as CellModel } from './cellModel';
+import { default as DetailRowModel } from './detailRowModel';
+import { default as GridModel } from './gridModel';
+import { default as GroupRowModel } from './groupRowModel';
+export default class RowModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    readonly data: TRow;
+    readonly rowIndex: number;
+    constructor(grid: GridModel<TRow>, data: TRow, rowIndex: number);
+    private _key?;
+    /**
+     * Resolved lazily: getRowKey() can call crypto.randomUUID(), so building a model for every
+     * row would generate a key for thousands of off-screen rows. Only rows that actually render
+     * (or are otherwise inspected) pay the cost. getRowKey itself is idempotent per row.
+     */
+    get key(): Key;
+    parentRow?: GroupRowModel<TRow>;
+    readonly count = 1;
+    readonly kind: "row";
+    /** Whether clicking the row toggles its detail panel. */
+    get expandOnRowClick(): boolean;
+    toggleDetail: () => void;
+    private readonly _cells;
+    get cells(): CellModel<TRow>[];
+    /** One cell per visible column — the width the grid navigation sees for this row. */
+    get cellCount(): number;
+    /** Where a cell starts in column-index space: one cell per column, so its own ordinal. */
+    columnOf(cell: number): number;
+    get selected(): boolean;
+    get expanded(): boolean;
+    get flatRows(): (RowModel<TRow> | DetailRowModel<TRow>)[];
+    get allRows(): this;
+}

package/components/dataGrid/models/viewportModel.d.ts

@@ -0,0 +1,44 @@
+import { default as GridModel } from './gridModel';
+/** Windowing parameters for the virtualized body. Rows are sliced by the adapter from these. */
+export interface ViewportWindow {
+    /** Index of the first row to render. */
+    startIndex: number;
+    /** Number of rows to render starting at `startIndex`. */
+    take: number;
+    /** Pixel offset to translate the rendered slice down to its scroll position. */
+    translateY: number;
+    /** Total scrollable height of all rows. */
+    totalHeight: number;
+    /** Fixed viewport height, or undefined when rendering all rows. */
+    viewHeight: number | undefined;
+}
+/**
+ * Headless virtualization: given a scrollTop, computes which rows are visible and how
+ * to position them. Pure math — `scrollTop` is owned by the adapter (so scrolling does
+ * not notify the store / re-render the whole grid).
+ */
+export default class ViewportModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    static readonly DEFAULT_VISIBLE_ROWS_COUNT = 10;
+    static readonly ROWS_TO_PRELOAD = 20;
+    constructor(grid: GridModel<TRow>);
+    get showAll(): boolean;
+    get hasDetailRows(): boolean;
+    get isEmpty(): boolean;
+    /** Number of rows the viewport shows at once (all rows when `visibleRowsCount === 'all'`). */
+    get visibleRowsCount(): number;
+    /**
+     * Rows a PageUp/PageDown moves. Deliberately not `visibleRowsCount`, which is every row when
+     * `visibleRowsCount === 'all'` — a Page key that jumps to the end of the grid is the End key.
+     */
+    get pageRows(): number;
+    get viewHeight(): number | undefined;
+    get totalHeight(): number;
+    /** Height to reserve for the empty/no-data state. */
+    get emptyHeight(): number;
+    /** Where a row sits inside the scrolled body — what a keyboard jump scrolls to. */
+    rowTop(index: number): number;
+    /** Binary search for the first row whose offset is <= scrollTop (variable-height rows). */
+    private findStartIndex;
+    window(scrollTop: number): ViewportWindow;
+}

package/components/dataGrid/useGrid.d.ts

@@ -0,0 +1,8 @@
+import { DataGridProps } from './contracts/dataGridContract';
+import { default as GridModel } from './models/gridModel';
+/**
+ * React binding for the headless GridModel store: the model owns all state and behaviour, React only
+ * subscribes. `setProps` syncs incoming props during render, and `useSyncExternalStore` re-renders
+ * whenever the model notifies.
+ */
+export default function useGrid<TRow>(props: DataGridProps<TRow>): GridModel<TRow>;

package/components/dataGrid/useGridNavigation.d.ts

@@ -0,0 +1,21 @@
+import { GridNavigation } from './gridNavigationContext';
+import { default as GridModel } from './models/gridModel';
+export interface GridNavigationOptions<TRow> {
+    grid: GridModel<TRow>;
+    /** The scrolling element — a jump to a row outside the rendered window has to scroll first. */
+    scrollerRef: React.RefObject<HTMLElement | null>;
+    scrollTop: number;
+    onScrollTo: (top: number) => void;
+}
+export interface GridNavigator extends GridNavigation {
+    /** Put this on the `role="grid"` element: cell keystrokes bubble to it. */
+    onKeyDown: (event: React.KeyboardEvent) => void;
+}
+/**
+ * APG's grid pattern over a virtualized body. Focus lives on the cells, one in the tab order at a time,
+ * and `useRovingFocus` owns which; what belongs here is what virtualization adds — a jump to a row nobody
+ * has scrolled to has no element to focus, so the move scrolls, waits for the render it caused, and
+ * focuses from a layout effect. Inside a cell the grid steps back: the widget keeps every key, and Enter
+ * or F2 got focus there while Escape takes it out.
+ */
+export default function useGridNavigation<TRow>(options: GridNavigationOptions<TRow>): GridNavigator;