@inandu-solutions/grid-react 0.1.2 → 0.1.4

package/dist/hooks/useInanduGrid.d.ts

@@ -0,0 +1,197 @@
+import { InanduColumnAggregate, InanduColumnStickySide, InanduColumnType, InanduGridColumnFilterValue, InanduGridRow, TreeVisibleRow } from '../core';
+/**
+ * Plain-value column definition for the React API — friendlier than the core's `ColumnConfig`
+ * getter shape (`field()`, `type()`, ...), which exists to match grid-angular's signal-based
+ * columns. `toColumnConfig` below adapts one to the other so the ported core needs no changes.
+ */
+export interface InanduGridColumn {
+    field: string;
+    headerText?: string;
+    type?: InanduColumnType;
+    format?: string;
+    order?: number;
+    aggregate?: InanduColumnAggregate;
+    /** Whether this column can be picked in the "group by" control. Default: true. */
+    groupable?: boolean;
+    /** Whether this field shows an editable control while its row is in edit/add mode. Default: false. */
+    editable?: boolean;
+    required?: boolean;
+    /** `'number'` columns only. */
+    min?: number;
+    /** `'number'` columns only. */
+    max?: number;
+    /** Checked against the raw (unparsed) draft value, `'string'`/`'number'`/`'date'` columns only. */
+    pattern?: string;
+    /** Runs after required/min/max/pattern all pass, against the parsed value and the row's other parsed fields (for cross-field checks). */
+    validator?: (parsed: unknown, parsedRow: Record<string, unknown>) => string | null;
+    /** Runs only once every synchronous rule (above) has already passed for this field; every field's async check runs concurrently. */
+    asyncValidator?: (parsed: unknown, parsedRow: Record<string, unknown>) => Promise<string | null>;
+    /** Whether this column can be hidden via the column-visibility toggle. Default: true. */
+    hideable?: boolean;
+    /** Pins the column to that side of the table, `position: sticky`, regardless of scroll. Unset: not pinned. */
+    pinned?: InanduColumnStickySide;
+    /** Fixed column width in px — also what `stickyOffset`/`stickyOffsetRight` stack against. Default (unset): 80, same fallback grid-angular's `effectiveWidth() || 80` uses. */
+    width?: number;
+    /** Whether this column's header can be dragged to reorder columns. Default: true. */
+    reorder?: boolean;
+}
+/** Passed to `onRowSave` — everything `saveRow()` parsed and validated for one already-existing row. */
+export interface InanduGridRowSave {
+    row: InanduGridRow;
+    values: Record<string, unknown>;
+}
+/** One cell update from a `pasteAt()` call — one entry per pasted cell that landed on an existing row and an editable column. */
+export interface InanduGridCellPaste {
+    row: InanduGridRow;
+    field: string;
+    value: unknown;
+}
+export interface InanduGridSort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+/** One bucket of `useInanduGrid`'s `groups` — mirrors grid-angular's `groupedRows`. */
+export interface InanduGridGroup {
+    /** The grouped column's *formatted* display value for every row in this bucket. */
+    key: string;
+    rows: InanduGridRow[];
+    /** One entry per column with `aggregate` set, keyed by that column's field. */
+    aggregates: Record<string, number>;
+}
+export interface UseInanduGridOptions {
+    rows: InanduGridRow[];
+    columns: InanduGridColumn[];
+    locale?: string;
+    /** Drives validation-message translation. Default: `locale`'s primary subtag. */
+    lang?: string;
+    /** 0 disables pagination — `visibleRows` is the full sorted/filtered set. Default: 0. */
+    pageSize?: number;
+    /** Whether the caller renders a select-checkbox column — `stickyOffset()` needs to know, since that column (when present) is always sticky-left too. Default: false. */
+    selectable?: boolean;
+    /** `window.confirm()`-gates `deleteRow()`, same as grid-angular. Unset: deletes immediately. */
+    deleteConfirmMessage?: string;
+    /** `window.confirm()`-gates `deleteSelectedRows()`. Unset: deletes immediately. */
+    bulkDeleteConfirmMessage?: string;
+    /** Emitted by `saveRow()` once validation passes — the grid never mutates `rows` itself; applying the change is the caller's job. */
+    onRowSave?: (event: InanduGridRowSave) => void;
+    /** Emitted by `saveNewRow()` once validation passes. No row reference — it doesn't exist in `rows` yet. */
+    onRowCreate?: (values: Record<string, unknown>) => void;
+    /** Emitted by `deleteRow()` (after confirmation, if any). */
+    onRowDelete?: (row: InanduGridRow) => void;
+    /** Emitted by `deleteSelectedRows()` (after confirmation, if any) — every currently-selected row. */
+    onRowsDelete?: (rows: InanduGridRow[]) => void;
+    /** Emitted by `pasteAt()` with every parsed cell update — the grid never mutates `rows` itself. */
+    onCellsPaste?: (updates: InanduGridCellPaste[]) => void;
+    /** Emitted by `onRowDrop()` with the fully reordered row array — the grid never mutates `rows` itself. */
+    onRowOrderChange?: (rows: InanduGridRow[]) => void;
+    /**
+     * Turns on tree mode: the name of the field on each row holding its child rows (a nested array
+     * of the same shape). `rows` is then the root rows; free-text/column filters keep a node when it
+     * or any descendant matches, and the active sort orders each level of siblings. Auto-disabled
+     * while grouped, same restriction grid-angular's `treeChildrenKey` has (there it also excludes
+     * virtual-scroll/server-side, neither of which this port has). Unset (default): tree mode off.
+     */
+    treeChildrenKey?: string;
+    /** Initial expand state for tree mode: `'none'` (default), `'all'`, or a max depth to open to. */
+    treeDefaultExpanded?: 'none' | 'all' | number;
+    /** Whether master-detail is on — the caller checks this itself (by passing a `renderDetail`), this only controls `toggleRowExpanded`'s accordion behavior. Off (any number of rows can be expanded at once) by default. */
+    singleDetailExpand?: boolean;
+    /**
+     * Opt-in row virtualization for large datasets — bypasses pagination entirely (same as grouping),
+     * feeding the windowing logic the full sorted/filtered set instead. Auto-disables grouping,
+     * master-detail, tree data, row drag-reorder and clipboard, same restrictions grid-angular's
+     * `virtualScroll` has (there it also covers server-side infinite-scroll, which this port doesn't
+     * have). The actual DOM windowing (which rows are mounted, given a real scroll position) is the
+     * `<InanduGrid>` component's job, not this hook's — it has no way to observe scroll state itself.
+     */
+    virtualScroll?: boolean;
+    /** An extra per-row predicate ANDed onto the free-text + column filters — same as grid-angular's `extraRowFilter`. Lets a caller layer its own filtering (e.g. an advanced-filter query) on top of the grid's own. Unset: no extra filtering. */
+    extraRowFilter?: (row: InanduGridRow) => boolean;
+}
+/**
+ * Headless engine for the grid: owns sort + per-column filter + pagination state and derives
+ * `visibleRows` (the current page) and `filteredRowCount` (before pagination) from `rows` using
+ * the same pure core as grid-angular. No rendering — `<InanduGrid>` is one consumer of this hook,
+ * not the only way to use it.
+ */
+export declare function useInanduGrid({ rows, columns, locale, lang, pageSize, selectable, deleteConfirmMessage, bulkDeleteConfirmMessage, onRowSave, onRowCreate, onRowDelete, onRowsDelete, onCellsPaste, onRowOrderChange, treeChildrenKey, treeDefaultExpanded, singleDetailExpand, virtualScroll, extraRowFilter, }: UseInanduGridOptions): {
+    visibleColumns: InanduGridColumn[];
+    /** Every column in current drag-reorder order, hidden ones included — same as grid-angular's `displayColumns()`. Most rendering should use `visibleColumns` instead; this is for callers (like a saved-view restore) that need to address a currently-hidden column too. */
+    allColumns: InanduGridColumn[];
+    stickyOffset: (field: string) => number;
+    stickyOffsetRight: (field: string) => number;
+    columnPinnedSide: (field: string) => InanduColumnStickySide | undefined;
+    setColumnPinned: (field: string, side: InanduColumnStickySide | undefined) => void;
+    hideableColumns: InanduGridColumn[];
+    isColumnHidden: (field: string) => boolean;
+    toggleColumnVisibility: (field: string) => void;
+    setColumnOrder: (fields: readonly string[]) => void;
+    draggingField: string | undefined;
+    onColumnDragStart: (field: string) => void;
+    onColumnDrop: (targetField: string) => void;
+    effectiveWidth: (field: string) => number;
+    isColumnResized: (field: string) => boolean;
+    setColumnWidth: (field: string, width: number) => void;
+    draggingRow: InanduGridRow | undefined;
+    onRowDragStart: (row: InanduGridRow) => void;
+    onRowDrop: (targetRow: InanduGridRow) => void;
+    hasTreeData: boolean;
+    treeRows: TreeVisibleRow<InanduGridRow>[];
+    isTreeRowExpanded: (row: InanduGridRow) => boolean;
+    toggleTreeRow: (row: InanduGridRow) => void;
+    setAllTreeRowsExpanded: (expanded: boolean) => void;
+    isRowExpanded: (row: InanduGridRow) => boolean;
+    toggleRowExpanded: (row: InanduGridRow) => void;
+    hasVirtualScroll: boolean;
+    visibleRows: InanduGridRow[];
+    /** Same "what's on screen right now" set the select-all checkbox and CSV/Excel/PDF export use — the current page, or every group's rows while grouped. */
+    exportRows: InanduGridRow[];
+    /** Every row matching the current filter and sort, in sort order, regardless of pagination or grouping — same as grid-angular's `sortedData()`. Unlike `exportRows`, this never stops at one page: a full-dataset export/print reads from here instead. */
+    sortedRows: InanduGridRow[];
+    filteredRowCount: number;
+    locale: string;
+    sortCriteria: InanduGridSort[];
+    setSort: import('react').Dispatch<import('react').SetStateAction<InanduGridSort[]>>;
+    toggleSort: (field: string, additive?: boolean) => void;
+    sortDirectionFor: (field: string) => "asc" | "desc" | undefined;
+    sortPriorityFor: (field: string) => number | undefined;
+    filterValues: Record<string, InanduGridColumnFilterValue>;
+    setFilterValue: (field: string, value: InanduGridColumnFilterValue) => void;
+    clearAllFilters: () => void;
+    filterQuery: string;
+    setFilterQuery: (query: string) => void;
+    page: number;
+    setPage: import('react').Dispatch<import('react').SetStateAction<number>>;
+    pageCount: number;
+    groupByField: string | undefined;
+    setGroupByField: import('react').Dispatch<import('react').SetStateAction<string | undefined>>;
+    groups: InanduGridGroup[] | null;
+    totals: Record<string, number>;
+    selectedRows: Set<InanduGridRow>;
+    isRowSelected: (row: InanduGridRow) => boolean;
+    toggleRowSelection: (row: InanduGridRow) => void;
+    allSelected: boolean;
+    someSelected: boolean;
+    toggleSelectAll: () => void;
+    clearSelection: () => void;
+    editableColumns: InanduGridColumn[];
+    editingRow: InanduGridRow | undefined;
+    isAddingRow: boolean;
+    rowDraft: Record<string, unknown>;
+    fieldErrors: Record<string, string>;
+    isValidating: boolean;
+    isEditingRow: (row: InanduGridRow) => boolean;
+    isAnotherRowEditing: (row: InanduGridRow) => boolean;
+    startEditingRow: (row: InanduGridRow) => void;
+    cancelRowEdit: () => void;
+    setRowDraftValue: (field: string, value: unknown) => void;
+    saveRow: (row: InanduGridRow) => Promise<void>;
+    deleteRow: (row: InanduGridRow) => void;
+    deleteSelectedRows: () => void;
+    startAddingRow: () => void;
+    cancelAddRow: () => void;
+    saveNewRow: () => Promise<void>;
+    validateCell: (column: InanduGridColumn, value: unknown, row?: Record<string, unknown>) => string | null;
+    copyCellText: (rowIndex: number, field: string) => string;
+    pasteAt: (anchorRowIndex: number, anchorField: string, text: string) => void;
+};