@box-kite/react 0.0.1 → 1.0.0

package/components/dataGrid/contracts/dataGridContract.d.ts

@@ -0,0 +1,213 @@
+import { ComponentsAndVariants } from '../../../types';
+import { SortDirection } from '../../../utils/array/arrayUtils';
+import { default as CellModel } from '../models/cellModel';
+export type { SortDirection };
+export type Key = string | number;
+/**
+ * Which edge a column is pinned to, named by the reading order rather than by the screen: `START` is the
+ * left edge of a left-to-right grid and the right edge of a right-to-left one, so a pinned column stays
+ * where the reading starts under either `dir`. `LEFT`/`RIGHT` are the older spelling of the same two.
+ */
+export type PinPosition = 'START' | 'END';
+/** What `pin` accepts — the logical pair, plus the physical names it used to be spelled with. */
+export type PinPositionInput = PinPosition | 'LEFT' | 'RIGHT';
+/** The logical side behind whichever spelling the caller used. */
+export declare function pinPositionOf(pin?: PinPositionInput): PinPosition | undefined;
+export declare const NO_PIN = "NO_PIN";
+export type SortColumnType<TRow> = {
+    key: keyof TRow;
+    dir: SortDirection;
+};
+export type KeysMatching<T, V> = {
+    [K in keyof T]-?: T[K] extends V ? K : never;
+}[keyof T];
+export interface PaginationState {
+    pageSize: number;
+    page: number;
+    totalItems: number;
+    totalPages: number;
+}
+/** Server-side pagination configuration on GridDefinition */
+export interface PaginationConfig {
+    /** Total number of items across all pages (from server response) */
+    totalCount: number;
+    /** Page size override. If omitted, defaults to visibleRowsCount (or 10). */
+    pageSize?: number;
+    /** Options shown in the page size selector dropdown. If omitted, no selector is shown. */
+    pageSizeOptions?: number[];
+}
+/** Snapshot of all server-relevant grid state, passed to onServerStateChange */
+export interface ServerState<TRow> {
+    page: number;
+    pageSize: number;
+    sortColumn: Key | undefined;
+    sortDirection: SortDirection | undefined;
+    columnFilters: ColumnFilters<TRow>;
+    globalFilterValue: string;
+}
+/** Filter type for column-level filtering */
+export type ColumnFilterType = 'text' | 'number' | 'multiselect';
+/** Text filter configuration (fuzzy search) */
+export interface TextFilterValue {
+    type: 'text';
+    value: string;
+}
+/** Number filter configuration with comparison operators */
+export interface NumberFilterValue {
+    type: 'number';
+    operator: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'between';
+    value: number;
+    valueTo?: number;
+}
+/** Multi-select filter configuration */
+export interface MultiselectFilterValue {
+    type: 'multiselect';
+    values: (string | number | boolean | null)[];
+}
+/** Union type for all filter values */
+export type FilterValue = TextFilterValue | NumberFilterValue | MultiselectFilterValue;
+/** Column filters record - maps column key to filter value */
+export type ColumnFilters<TRow> = Partial<Record<keyof TRow | Key, FilterValue>>;
+/** Filter configuration for a column */
+export interface ColumnFilterConfig {
+    type: ColumnFilterType;
+    /** Placeholder text for input */
+    placeholder?: string;
+    /** For multiselect: custom options. If not provided, unique values are computed from data */
+    options?: {
+        label: string;
+        value: string | number | boolean | null;
+    }[];
+    /** For number: step value for input */
+    step?: number;
+    /** For number: min value */
+    min?: number;
+    /** For number: max value */
+    max?: number;
+}
+/** Configuration for expandable row detail panel */
+export interface RowDetailConfig<TRow> {
+    /** Render function for the detail content */
+    content: (row: TRow) => React.ReactNode;
+    /** Height of the detail row. 'auto' sizes to content. Default: 'auto' */
+    height?: 'auto' | number | ((row: TRow) => number);
+    /** Whether clicking the row also toggles expansion. Default: false */
+    expandOnRowClick?: boolean;
+    /** Pin the expand column to LEFT. Default: false */
+    pinned?: boolean;
+    /** Width of the expand column. Default: 50 */
+    expandColumnWidth?: number;
+    /** Header text for the expand column. Default: '' (empty) */
+    expandColumnHeader?: string;
+}
+/** Controls which sections appear in the column header context menu */
+export interface ContextMenuConfig {
+    /** Show sort actions (Sort Ascending, Sort Descending, Clear Sort). Default: true */
+    sort?: boolean;
+    /** Show pin actions (pin to start, pin to end, unpin). Default: true */
+    pin?: boolean;
+    /** Show group actions (Group By, Un-Group All). Default: true */
+    group?: boolean;
+}
+export interface ColumnType<TRow> {
+    key: Key;
+    header?: string;
+    pin?: PinPositionInput;
+    width?: number;
+    columns?: ColumnType<TRow>[];
+    /** `start`/`end` follow the reading order; `left`/`right` stay on the screen side they name. */
+    align?: 'start' | 'end' | 'center' | 'left' | 'right';
+    Cell?: React.ComponentType<{
+        cell: CellModel<TRow>;
+    }>;
+    /** Enable filtering for this column. Set to true for default text filter, or provide config */
+    filterable?: boolean | ColumnFilterConfig;
+    /** Enable sorting for this column. If undefined, inherits from GridDefinition.sortable */
+    sortable?: boolean;
+    /** Enable resizing for this column. If undefined, inherits from GridDefinition.resizable */
+    resizable?: boolean;
+    /** If false, column stays fixed at its width and doesn't participate in flex distribution. Default: true */
+    flexible?: boolean;
+    /** Control the header context menu. false hides it entirely. Object controls individual sections. Inherits from GridDefinition.contextMenu if undefined. */
+    contextMenu?: boolean | ContextMenuConfig;
+}
+export interface GridDefinition<TRow> {
+    rowKey?: KeysMatching<TRow, Key> | ((rowData: TRow) => Key);
+    columns: ColumnType<TRow>[];
+    showRowNumber?: boolean | {
+        pinned?: boolean;
+        width?: number;
+    };
+    rowSelection?: boolean | {
+        pinned?: boolean;
+    };
+    rowHeight?: number;
+    /** Number of visible rows. Set to 'all' to render all rows without virtualization or vertical scrollbar. */
+    visibleRowsCount?: number | 'all';
+    topBar?: boolean;
+    bottomBar?: boolean;
+    /** Title displayed in the top bar */
+    title?: React.ReactNode;
+    /** Custom filters or actions rendered in the top bar */
+    topBarContent?: React.ReactNode;
+    /** Enable global filter with fuzzy search */
+    globalFilter?: boolean;
+    /** Keys of columns to search in global filter. If not provided, all columns are searched */
+    globalFilterKeys?: (keyof TRow | Key)[];
+    /** Enable sorting for all columns. Default is true. Individual column settings take priority. */
+    sortable?: boolean;
+    /** Enable resizing for all columns. Default is true. Individual column settings take priority. */
+    resizable?: boolean;
+    /** Controls the visual style of column resizer handles. 'visible' (default): always shown. 'hover': visible on header cell hover. 'hidden': invisible but resize still works. */
+    resizerStyle?: 'visible' | 'hover' | 'hidden';
+    /** How the column follows the pointer during a resize drag. 'smooth' (default): updates batched once per animation frame (~60fps, ~1 frame behind the cursor). 'instant': updates synchronously on every pointer move so the column tracks the cursor with no added latency. */
+    resizeMode?: 'smooth' | 'instant';
+    /** Control the header context menu for all columns. false hides it entirely. Object controls individual sections. Default: true. Individual column settings take priority. */
+    contextMenu?: boolean | ContextMenuConfig;
+    /** Custom component to render when data is empty */
+    noDataComponent?: React.ReactNode;
+    /** Enable expandable row detail panel */
+    rowDetail?: RowDetailConfig<TRow>;
+    /** Server-side pagination. Provide totalCount from the API response. */
+    pagination?: PaginationConfig;
+}
+export interface DataGridProps<TRow> {
+    /** Component name for style resolution. Default: 'datagrid'. Set to a custom name to use a different component style tree. */
+    component?: keyof ComponentsAndVariants;
+    data: TRow[];
+    def: GridDefinition<TRow>;
+    loading?: boolean;
+    onSelectionChange?: (event: SelectionChangeEvent<TRow>) => void;
+    /** Controlled global filter value */
+    globalFilterValue?: string;
+    /** Callback when global filter changes */
+    onGlobalFilterChange?: (value: string) => void;
+    /** Controlled column filters */
+    columnFilters?: ColumnFilters<TRow>;
+    /** Callback when column filters change */
+    onColumnFiltersChange?: (filters: ColumnFilters<TRow>) => void;
+    /** External predicate filters applied before global/column filters. Memoize with useMemo for performance. */
+    filters?: ((row: TRow) => boolean)[];
+    /** Controlled expanded detail row keys */
+    expandedRowKeys?: Key[];
+    /** Callback when expanded detail rows change */
+    onExpandedRowKeysChange?: (keys: Key[]) => void;
+    /** Controlled current page (1-indexed). Used with pagination. */
+    page?: number;
+    /** Callback when page changes. Receives page (1-indexed) and pageSize. */
+    onPageChange?: (page: number, pageSize: number) => void;
+    /** Controlled page size. Used with pagination and pageSizeOptions. */
+    pageSize?: number;
+    /** Callback when the user changes the page size. */
+    onPageSizeChange?: (pageSize: number) => void;
+    /** Callback when sort changes. For server-side sorting with pagination. */
+    onSortChange?: (columnKey: Key | undefined, direction: SortDirection | undefined) => void;
+    /** Fires on any server-relevant state change (page, sort, filter). Provides full state snapshot for API calls. */
+    onServerStateChange?: (state: ServerState<TRow>) => void;
+}
+interface SelectionChangeEvent<TRow, TKey = TRow[keyof TRow] | number | string> {
+    action: 'select' | 'deselect';
+    selectedRowKeys: TKey[];
+    affectedRowKeys: TKey[];
+    isAllSelected: boolean;
+}

package/components/dataGrid/gridNavigationContext.d.ts

@@ -0,0 +1,24 @@
+import { RovingFocusItemProps } from '../../react/a11y/useRovingFocus';
+/**
+ * The grid's keyboard coordinates, shared with every cell. Rows are numbered as `aria-rowindex` is —
+ * headers, then the filter row, then the body — and a cell asks for its roving tabindex by that pair, so
+ * the numbering has to be one thing the whole grid agrees on rather than three local ones.
+ */
+export interface GridNavigation {
+    /** `aria-rowcount`: every row the grid has, not the window of them that is rendered. */
+    rowCount: number;
+    /** `aria-colcount`: the visible leaf columns. */
+    columnCount: number;
+    /** How many rows sit above the body — the offset from a body row's index to its row number. */
+    headerRowCount: number;
+    /** The roving tabindex and the ref for one cell, in the coordinates above. */
+    cellProps: (row: number, column: number) => RovingFocusItemProps;
+}
+/**
+ * Absent outside a DataGrid, and absent on purpose: `DataGridCell` is rendered by the grid and by
+ * nothing else, so a missing provider is a bug rather than a supported way to use the component.
+ */
+declare const GridNavigationContext: import('react').Context<GridNavigation | null>;
+export default GridNavigationContext;
+/** The grid navigation a cell belongs to. */
+export declare function useGridNavigationContext(): GridNavigation | null;

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

@@ -0,0 +1,18 @@
+import { default as ColumnModel } from './columnModel';
+import { default as GridModel } from './gridModel';
+import { default as RowModel } from './rowModel';
+export default class CellModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    readonly row: RowModel<TRow>;
+    readonly column: ColumnModel<TRow>;
+    constructor(grid: GridModel<TRow>, row: RowModel<TRow>, column: ColumnModel<TRow>);
+    get value(): number | TRow[keyof TRow];
+    get isExpanded(): boolean;
+    get selected(): boolean;
+    get isFirst(): boolean;
+    get isLast(): boolean;
+    /** Toggle this row's detail panel (used by the row-detail expand cell). */
+    toggleDetail: () => void;
+    /** Toggle this row's selection (used by the row-selection checkbox cell). */
+    toggleSelection: () => void;
+}

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

@@ -0,0 +1,150 @@
+import { ColumnFilterConfig, ColumnType, ContextMenuConfig, FilterValue, Key, NumberFilterValue, PinPosition, PinPositionInput, SortDirection } from '../contracts/dataGridContract';
+import { default as GridModel } from './gridModel';
+import { default as HeaderCellModel } from './headerCellModel';
+/** Discriminates the structural role of a column — replaces scattered `key === *_CELL_KEY` checks. */
+export type ColumnKind = 'data' | 'rowNumber' | 'rowSelection' | 'rowDetail' | 'grouping';
+export default class ColumnModel<TRow> {
+    readonly def: ColumnType<TRow>;
+    readonly grid: GridModel<TRow>;
+    private parent?;
+    constructor(def: ColumnType<TRow>, grid: GridModel<TRow>, parent?: ColumnModel<TRow> | undefined);
+    columns: ColumnModel<TRow>[];
+    get kind(): ColumnKind;
+    get isRowNumber(): boolean;
+    get isRowSelection(): boolean;
+    get isRowDetail(): boolean;
+    get isGrouping(): boolean;
+    get isData(): boolean;
+    readonly pinFlags: import('../../../utils/memo').Memo<{
+        isStartPinned: boolean;
+        isEndPinned: boolean;
+        isPinned: boolean;
+        isFirstStartPinned: boolean;
+        isLastStartPinned: boolean;
+        isFirstEndPinned: boolean;
+        isLastEndPinned: boolean;
+    }>;
+    /** Variant flags for the body cell that depend only on the column (not the row). */
+    readonly cellVariant: import('../../../utils/memo').Memo<{
+        isPinned: boolean;
+        isFirstStartPinned: boolean;
+        isLastStartPinned: boolean;
+        isFirstEndPinned: boolean;
+        isLastEndPinned: boolean;
+        isRowSelection: boolean;
+        isRowNumber: boolean;
+        isFirstLeaf: boolean;
+        isLastLeaf: boolean;
+        isRowDetail: boolean;
+    }>;
+    /** Static CSS-var references for the body/filter cell (stable string identity). */
+    readonly cellStyleVars: import('../../../utils/memo').Memo<{
+        width: string;
+        height: string;
+        insetInlineStart: string | undefined;
+        insetInlineEnd: string | undefined;
+    }>;
+    /** Derived state for this column's header cell + context menu. */
+    private readonly _headerCell;
+    get headerCell(): HeaderCellModel<TRow>;
+    get visibleColumns(): ColumnModel<TRow>[];
+    get isFirstLeaf(): boolean;
+    get isLastLeaf(): boolean;
+    get key(): Key;
+    get header(): string | undefined;
+    get align(): "left" | "right" | "center" | "end" | "start" | undefined;
+    /** End-aligned either way it is spelled — `right` is the physical name of `end` in a left-to-right grid. */
+    get isEndAligned(): boolean;
+    /** Whether an explicit `align` was provided (mirrors the original `'align' in def` check). */
+    get hasAlign(): boolean;
+    get isLeaf(): boolean;
+    get Cell(): import('react').ComponentType<{
+        cell: import('./cellModel').default<TRow>;
+    }> | undefined;
+    get filterable(): boolean | ColumnFilterConfig | undefined;
+    /** Resolved filter config, or undefined when this column isn't filterable. */
+    get filterConfig(): ColumnFilterConfig | undefined;
+    /** The active filter on this column, if any. */
+    get currentFilter(): FilterValue | undefined;
+    /** Options for a multiselect filter (config-provided, else unique values from data). */
+    get filterOptions(): {
+        label: string;
+        value: string | number | boolean | null;
+    }[];
+    setTextFilter(value: string): void;
+    setNumberFilter(operator: NumberFilterValue['operator'], value: string | number, valueTo?: string | number): void;
+    setMultiselectFilter(values: (string | number | boolean | null)[]): void;
+    clearFilter(): void;
+    /** Whether sorting is enabled for this column. Column-level setting takes priority over grid-level. */
+    get sortable(): boolean;
+    /** Whether resizing is enabled for this column. Column-level setting takes priority over grid-level. */
+    get resizable(): boolean;
+    /** Resolved context menu configuration. Column-level takes priority over grid-level. Default: true. */
+    get contextMenu(): boolean | ContextMenuConfig;
+    /** Whether the context menu button should be shown at all. */
+    get showContextMenu(): boolean;
+    /** Resolved context menu sections visibility. */
+    get contextMenuSections(): {
+        sort: boolean;
+        pin: boolean;
+        group: boolean;
+    };
+    /** Whether column participates in flex distribution. Default true unless explicitly false. */
+    get isFlexible(): boolean;
+    /** The base width before flex calculation (what user set or DEFAULT). */
+    get baseWidth(): number;
+    private _pin?;
+    get pin(): PinPosition | undefined;
+    get uniqueKey(): string;
+    getPinnedColumn(pin?: PinPosition): ColumnModel<TRow> | undefined;
+    private hasPin;
+    get death(): number;
+    get flatColumns(): ColumnModel<TRow>[];
+    private _inlineWidth?;
+    get inlineWidth(): number | undefined;
+    get startOffset(): number;
+    get endOffset(): number;
+    get isEdge(): boolean;
+    get isVisible(): boolean;
+    get leafs(): ColumnModel<TRow>[];
+    get groupColumnWidthVarName(): string;
+    get widthVarName(): string;
+    get inlineStartVarName(): string;
+    get inlineEndVarName(): string;
+    get gridRows(): number;
+    private _resizeStartX;
+    private _resizeSizes;
+    private _resizeTotalWidth;
+    /** Begin a resize drag from a pointer x-coordinate (page space). */
+    beginResize: (startX: number) => void;
+    /**
+     * A pointer moves in screen coordinates and a column grows along the inline axis, so turning one into
+     * the other takes both facts: which edge the separator sits on, and which way the reading runs. The two
+     * flips compose — an end-pinned column in a right-to-left grid resizes the way an unpinned one does.
+     */
+    private get resizeSign();
+    /**
+     * Apply the drag to a new pointer x-coordinate, distributing the delta across leafs.
+     * Does NOT notify — the caller decides how to reflect the change (the React adapter
+     * writes the resulting width CSS variables straight to the DOM for a 60fps drag).
+     */
+    applyResize: (currentX: number) => void;
+    /** Apply the drag and notify subscribers (headless API for non-DOM hosts). */
+    resizeTo: (currentX: number) => void;
+    /** End a resize drag. */
+    endResize: () => void;
+    /**
+     * Move the resize separator `delta` pixels right — one step of a keyboard resize, from the widths as they
+     * are, so pressing again carries on. Rightwards widens a column whose separator is on its right edge and
+     * narrows a right-pinned one, as dragging does. Does **not** notify: a held arrow repeats thirty times a
+     * second, so the caller paints the widths and calls `endResize()` when the gesture ends.
+     */
+    moveResizer: (delta: number) => void;
+    /** Resize to an exact total width — where Home and End on the separator land. Does not notify. */
+    resizeWidthTo: (width: number) => void;
+    pinColumn: (pin?: PinPositionInput) => void;
+    toggleGrouping: () => void;
+    sortColumn: (sortDirection?: SortDirection) => void;
+    setWidth: (width: number) => void;
+    toggleVisibility: () => void;
+}

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

@@ -0,0 +1,24 @@
+import { default as ColumnModel } from './columnModel';
+import { default as GridModel } from './gridModel';
+export interface ColumnVisibilityEntry<TRow> {
+    id: string;
+    label: string;
+    column: ColumnModel<TRow>;
+    visible: boolean;
+}
+/**
+ * Backs the top-bar column-visibility menu: the toggleable (user data) columns, which
+ * are currently shown, and a diff-based bulk setter.
+ */
+export default class ColumnVisibilityModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    constructor(grid: GridModel<TRow>);
+    /** All user data leafs (visible and hidden) — excludes row-number/selection/detail/grouping. */
+    get entries(): ColumnVisibilityEntry<TRow>[];
+    get selectedIds(): string[];
+    get total(): number;
+    get hiddenCount(): number;
+    get hasHidden(): boolean;
+    /** Make exactly the columns in `ids` visible, toggling only those whose state must change. */
+    setVisibility: (ids: string[]) => void;
+}

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

@@ -0,0 +1,22 @@
+import { Key } from '../contracts/dataGridContract';
+import { default as GridModel } from './gridModel';
+import { default as RowModel } from './rowModel';
+export default class DetailRowModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    readonly parentRow: RowModel<TRow>;
+    constructor(grid: GridModel<TRow>, parentRow: RowModel<TRow>);
+    readonly kind: "detail";
+    get key(): Key;
+    get isAutoHeight(): boolean;
+    static readonly AUTO_HEIGHT_ESTIMATE = 200;
+    get height(): 'auto' | number;
+    /** Numeric height for virtualization offset calculations. Uses estimate for 'auto'. */
+    get heightForOffset(): number;
+    readonly count = 0;
+    /** One cell, spanning every column — the width the grid navigation sees for this row. */
+    readonly cellCount = 1;
+    /** That one cell starts at the first column and covers the rest of them. */
+    columnOf(): number;
+    get flatRows(): this[];
+    get allRows(): RowModel<TRow>[];
+}

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

@@ -0,0 +1,22 @@
+import { ColumnFilters } from '../contracts/dataGridContract';
+import { default as GridModel } from './gridModel';
+/**
+ * Filtering concern: grid-level filter state + the derived flags the UI needs. Per-column
+ * filter config/value/parse helpers live on ColumnModel; the coupled mutations (page-reset,
+ * server-state events, filteredData) live on GridModel.
+ */
+export default class FilterModel<TRow> {
+    readonly grid: GridModel<TRow>;
+    constructor(grid: GridModel<TRow>);
+    get globalFilterValue(): string;
+    get columnFilters(): ColumnFilters<TRow>;
+    get hasActiveFilters(): boolean;
+    get filterStats(): {
+        filtered: number;
+        total: number;
+    };
+    /** Whether any visible column is filterable (controls the filter row's visibility). */
+    get hasFilterableColumns(): boolean;
+    setGlobalFilter: (value: string) => void;
+    clearAllFilters: () => void;
+}