@rovula/ui 0.1.28 → 0.1.30

package/dist/esm/types/components/DataTable/DataTable.d.ts

@@ -1,9 +1,200 @@
-import { ColumnDef, SortingState } from "@tanstack/react-table";
-export interface DataTableProps<TData, TValue> {
-    columns: ColumnDef<TData, TValue>[];
+import { Cell, ColumnDef, ExpandedState, Header, PaginationState, Row, RowSelectionState, RowData, SortingState } from "@tanstack/react-table";
+import React from "react";
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData extends RowData, TValue> {
+        exactWidth?: number | string;
+        align?: "left" | "center" | "right";
+        cellClassName?: string;
+        headerCellClassName?: string;
+        colSpan?: number | ((row: Row<TData>) => number);
+    }
+}
+/** TanStack Table types used by `DataTable` props — import from `@rovula/ui` to stay aligned with this package and `ColumnMeta` augmentation. */
+export type { Cell, ColumnDef, ExpandedState, Header, PaginationState, Row, RowData, RowSelectionState, SortingState, Table as TanstackTable, } from "@tanstack/react-table";
+export type { EditableColumnDef, EditDisplayMode, EditTrigger, DataTableEditingProps, } from "./DataTable.editing.types";
+import type { EditableColumnDef, DataTableEditingProps } from "./DataTable.editing.types";
+export type DataTablePaginationMode = "server" | "client" | "infinite";
+export interface DataTableProps<TData, TValue> extends DataTableEditingProps<TData> {
+    columns: (ColumnDef<TData, TValue> | EditableColumnDef<TData, TValue>)[];
     data: TData[];
     manualSorting?: boolean;
     onSorting?: (sorting: SortingState) => void;
+    /**
+     * "client"   – DataTable manages page state internally with TanStack
+     * "server"   – caller controls page state; pass pageIndex/pageSize/totalCount
+     * "infinite" – no pagination bar; fetchMoreData enables infinite scroll
+     */
+    paginationMode?: DataTablePaginationMode;
+    /** Required for "server" mode */
+    totalCount?: number;
+    pageIndex?: number;
+    pageSize?: number;
+    onPaginationChange?: (state: PaginationState) => void;
+    pageSizeOptions?: number[];
+    /** Called when user scrolls near bottom (infinite mode). */
     fetchMoreData?: () => void;
+    /**
+     * Threshold in pixels from the bottom of the scroll container at which
+     * `fetchMoreData` is triggered. Defaults to 10px.
+     */
+    fetchMoreOffset?: number;
+    /**
+     * When `paginationMode` is `"infinite"`, shows a built-in footer row (spinner +
+     * label) and suppresses additional `fetchMoreData` calls until this is false again.
+     */
+    fetchingMore?: boolean;
+    /** Accessible label next to the spinner (default: "Loading more…"). */
+    fetchingMoreLabel?: string;
+    /**
+     * When there are no rows yet, shows a built-in loading state instead of the
+     * empty placeholder. Also suppresses `fetchMoreData` while true (infinite mode).
+     */
+    loading?: boolean;
+    /** Label for the initial-loading state (default: "Loading…"). */
+    loadingLabel?: string;
+    /**
+     * When true, DataTable will only render a vertical window of rows based on
+     * the scroll position of its internal scroll container. This is a basic
+     * fixed-row-height virtualizer intended for large but finite lists.
+     *
+     * Notes / limitations:
+     * - Only vertical row virtualization is supported.
+     * - Assumes approximately fixed row height; pass `virtualRowEstimate` to tune.
+     * - Works with selection, row actions, and basic infinite scroll, but more
+     *   complex combinations (tree rows, reorder, etc.) may have visual quirks.
+     */
+    virtualized?: boolean;
+    /**
+     * Estimated height in pixels for a single table row when `virtualized` is
+     * true. Used to compute how many rows fit in the viewport and the spacer
+     * heights above/below the rendered window.
+     * @default 40
+     */
+    virtualRowEstimate?: number;
+    /**
+     * Optional row id(s) to highlight visually. Highlighting is purely cosmetic
+     * and does not affect selection state.
+     */
+    highlightRowId?: string | string[];
+    /**
+     * When true and `highlightRowId` is set, moving the mouse pointer out of the
+     * scroll area will automatically scroll the first highlighted row back into
+     * view (centered).
+     */
+    scrollToHighlightOnMouseLeave?: boolean;
+    selectable?: boolean;
+    onRowSelectionChange?: (rows: RowSelectionState) => void;
+    /** Render actions into the last fixed-width column. Receives the TanStack Row. */
+    rowActions?: (row: Row<TData>) => React.ReactNode;
+    /**
+     * Enable drag-to-reorder rows. A grip handle column is prepended automatically.
+     * Requires each data item to have a unique `id` field (string | number)
+     * or supply `getRowId` to derive one.
+     */
+    reorderable?: boolean;
+    /** Return a unique string id for each row. Defaults to `(row) => row.id`. */
+    getRowId?: (row: TData) => string;
+    /** Called after the user drops a row into a new position. Receives the reordered data array. */
+    onRowReorder?: (data: TData[]) => void;
+    /**
+     * When `reorderable`, rows that return `true` are not draggable and are
+     * omitted from the sortable context (e.g. a pinned footer "add" row).
+     * Those rows are also kept **after** all sortable rows whenever column sort
+     * is applied (order among locked rows follows original `data` order).
+     */
+    isRowReorderLocked?: (row: Row<TData>) => boolean;
+    /** Fired when a body row is clicked. */
+    onRowClick?: (row: Row<TData>, event: React.MouseEvent) => void;
+    /** Fired when an individual body cell is clicked. */
+    onCellClick?: (cell: Cell<TData, unknown>, row: Row<TData>, event: React.MouseEvent) => void;
+    /** Return child rows to enable tree expansion */
+    getSubRows?: (row: TData) => TData[] | undefined;
+    /** Initial expanded state — `true` = all expanded, `{}` = all collapsed (uncontrolled) */
+    defaultExpanded?: ExpandedState | boolean;
+    /** Controlled expanded state — omit to let DataTable manage internally */
+    expanded?: ExpandedState;
+    onExpandedChange?: (expanded: ExpandedState) => void;
+    /**
+     * Rounded frame + `border-table-c-border` around the scroll area and pagination
+     * (same token as primitive `Table` `bordered`). Set `false` when embedding in
+     * another bordered surface.
+     */
+    bordered?: boolean;
+    /**
+     * `"panel"` sets `data-surface="panel"` for table token overrides (modal /
+     * drawer). `"default"` leaves surface to ancestors.
+     */
+    surface?: "default" | "panel";
+    /** Alternate row background colours (RowA / RowB) */
+    striped?: boolean;
+    /** Add vertical column dividers */
+    divided?: boolean;
+    /** Return a className string to apply to a specific body row. */
+    rowClassName?: string | ((row: Row<TData>, index: number) => string | undefined);
+    /** Return a className string to apply to a specific body cell. */
+    cellClassName?: string | ((cell: Cell<TData, unknown>, row: Row<TData>) => string | undefined);
+    /** Return a className string to apply to a specific column header cell (`<th>`). */
+    headerCellClassName?: string | ((header: Header<TData, unknown>) => string | undefined);
+    /** Additional className for the header section (`<thead>`). */
+    headerClassName?: string;
+    /** Additional className for the header row (`<tr>` inside `<thead>`). */
+    headerRowClassName?: string;
+    /**
+     * Controls when the sort indicator button is visible on sortable columns.
+     * - `"hover"` – shown only when hovering the column header (default)
+     * - `"always"` – always visible
+     */
+    sortIndicatorVisibility?: "always" | "hover";
+    /**
+     * CSS `table-layout` mode.
+     * - `"auto"` – browser sizes columns based on content (default)
+     * - `"fixed"` – non-`exactWidth` columns use their `size` as pixel widths;
+     *   the **last** visible non-exact column absorbs leftover width so the table
+     *   stays full-width. `meta.exactWidth` (px) columns stay locked.
+     * - `"equal"` – all visible columns without `meta.exactWidth` share the
+     *   remaining table width equally via
+     *   `calc((100% - <sum of exactWidth>px) / <flex column count>)`.
+     *   Columns with `meta.exactWidth` are still locked to their exact value.
+     *   With `resizable`, drag-to-resize is disabled for `equal` so widths stay
+     *   equal; `fixed`/`auto` keep column resize handles.
+     */
+    tableLayout?: "auto" | "fixed" | "equal";
+    /**
+     * Show a column menu (⋮) on each hideable column header: first a dropdown
+     * (“Hide … column”, “Manage columns”), then the full manage panel from the
+     * second action. Pass `true` or `ColumnManagementOptions` to tune features.
+     */
+    columnManagement?: boolean | ColumnManagementOptions;
+    /** Allow user to drag-resize column widths */
+    resizable?: boolean;
+    /**
+     * Global minimum column width in pixels when `resizable` is true.
+     * Individual columns can override with `minSize` in their column def.
+     * @default 60
+     */
+    columnMinSize?: number;
+    /**
+     * Global maximum column width in pixels when `resizable` is true.
+     * Individual columns can override with `maxSize` in their column def.
+     * @default Number.MAX_SAFE_INTEGER (no limit)
+     */
+    columnMaxSize?: number;
+    className?: string;
+    /**
+     * Sets `data-testid` on the root container and derives sub-ids for the
+     * table (`{testId}-table`), header (`{testId}-thead`), body (`{testId}-tbody`),
+     * rows (`{testId}-row-{rowId}`), and cells (`{testId}-cell-{rowId}-{colId}`).
+     */
+    testId?: string;
+}
+export interface ColumnManagementOptions {
+    /** Show drag-handle to reorder columns. @default true */
+    reorder?: boolean;
+    /** Show per-column visibility Switch. @default true */
+    visibility?: boolean;
+    /** Show "Hide all" button. @default true */
+    hideAll?: boolean;
+    /** Show "Show all" button. @default true */
+    showAll?: boolean;
 }
-export declare function DataTable<TData, TValue>({ data, columns, manualSorting, onSorting, fetchMoreData, }: DataTableProps<TData, TValue>): import("react/jsx-runtime").JSX.Element;
+export declare function DataTable<TData, TValue>({ data, columns, manualSorting, onSorting, paginationMode, totalCount, pageIndex: controlledPageIndex, pageSize: controlledPageSize, onPaginationChange, pageSizeOptions, fetchMoreData, fetchMoreOffset, fetchingMore, fetchingMoreLabel, loading, loadingLabel, highlightRowId, scrollToHighlightOnMouseLeave, selectable, onRowSelectionChange, rowActions, reorderable, getRowId: getRowIdProp, onRowReorder, isRowReorderLocked, onRowClick, onCellClick, getSubRows, defaultExpanded, expanded: controlledExpanded, onExpandedChange, bordered, surface, striped, divided, rowClassName, cellClassName, headerCellClassName, headerClassName, headerRowClassName, sortIndicatorVisibility, tableLayout, columnManagement: columnManagementProp, resizable, columnMinSize, columnMaxSize, virtualized, virtualRowEstimate, className, enableEditing, editDisplayMode, editTrigger, onCellCommit, alwaysEditing, enableCellTabTraversal, editableColumnIds: editableColumnIdsProp, testId, }: DataTableProps<TData, TValue>): import("react/jsx-runtime").JSX.Element;

package/dist/esm/types/components/DataTable/DataTable.editing.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import type { EditableColumnDef, EditDisplayMode, EditTrigger, EditingState } from "./DataTable.editing.types";
+export declare const EditContext: React.Context<EditingState | null>;
+export declare function useDataTableEditing<TData extends RowData>(opts: {
+    enabled: boolean;
+    editDisplayMode: EditDisplayMode;
+    editTrigger: EditTrigger;
+    editableColumnIds: string[];
+}): EditingState;
+type ResolveOpts<TData extends RowData> = {
+    editing: EditingState;
+    onCellCommit?: (rowId: string, columnId: string, patch: Partial<TData>) => void;
+    alwaysEditing?: (row: Row<TData>) => boolean;
+    enableCellTabTraversal: boolean;
+    editableColumnIds: string[];
+};
+export declare function resolveEditableColumns<TData extends RowData>(columns: EditableColumnDef<TData>[], opts: ResolveOpts<TData>): ColumnDef<TData, unknown>[];
+export declare function detectEditableColumnIds<TData extends RowData>(columns: EditableColumnDef<TData>[]): string[];
+export {};

package/dist/esm/types/components/DataTable/DataTable.editing.types.d.ts

@@ -0,0 +1,145 @@
+import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import type { Options } from "@/components/Dropdown/Dropdown";
+export type EditDisplayMode = "cell" | "row";
+export type EditTrigger = "click" | "doubleClick";
+export type EditableColumnDef<TData extends RowData = RowData, TValue = unknown> = ColumnDef<TData, TValue> & {
+    /**
+     * Enable inline editing for this column.
+     * - `true` — always editable
+     * - `(row) => boolean` — conditionally editable (e.g. dependent fields)
+     */
+    enableEditing?: boolean | ((row: Row<TData>) => boolean);
+    /**
+     * Which built-in editor to render.
+     * - `"text"` — `TextInput` (default when `enableEditing` is truthy)
+     * - `"select"` — `Dropdown`
+     * - `"number"` — `NumberInput`
+     * - `"checkbox"` — `Checkbox`
+     * - `"custom"` — user-provided renderer via `editCustomCell`
+     */
+    editVariant?: "text" | "select" | "number" | "checkbox" | "custom";
+    /** Props forwarded to the `TextInput` editor (variant `"text"`). */
+    editTextProps?: {
+        placeholder?: string;
+    };
+    /** Props forwarded to the `Dropdown` editor (variant `"select"`). */
+    editSelectProps?: {
+        options: Options[] | ((row: Row<TData>) => Options[]);
+        placeholder?: string;
+    };
+    /** Props forwarded to the `NumberInput` editor (variant `"number"`). */
+    editNumberProps?: {
+        placeholder?: string;
+        min?: number;
+        max?: number;
+        step?: number;
+        precision?: number;
+        allowDecimal?: boolean;
+        allowNegative?: boolean;
+    };
+    /** Props forwarded to the `Checkbox` editor (variant `"checkbox"`). */
+    editCheckboxProps?: {
+        label?: string;
+    };
+    /**
+     * Render function for a fully custom edit cell (variant `"custom"`).
+     *
+     * Receives the current row and a `commit` callback. Call `commit(rawValue)`
+     * to persist the change — the engine will run `onCommit` / `buildPatch`
+     * as usual.
+     *
+     * ```tsx
+     * editCustomCell: (row, { commit, errorMessage }) => (
+     *   <MyColorPicker
+     *     value={row.original.color}
+     *     onChange={(c) => commit(c)}
+     *     error={errorMessage}
+     *   />
+     * )
+     * ```
+     */
+    editCustomCell?: (row: Row<TData>, ctx: {
+        /** Persist the edited value — runs `onCommit` / `buildPatch` as usual. */
+        commit: (rawValue: string) => void;
+        /** Exit edit mode without committing (same as pressing Escape). */
+        blur: () => void;
+        columnId: string;
+        autoFocus: boolean;
+        errorMessage?: string;
+        onKeyDown?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    }) => React.ReactNode;
+    /**
+     * Return an error message for the current cell value to display inline
+     * validation feedback. Return `undefined` or empty string when valid.
+     */
+    editError?: (row: Row<TData>) => string | undefined;
+    /**
+     * Build a custom `Partial<TData>` patch from the raw committed value.
+     * When omitted the engine defaults to `{ [columnId]: rawValue }`.
+     *
+     * Use this for dependent-field resets, value transforms, etc.
+     *
+     * ```ts
+     * onCommit: (_row, value) => ({
+     *   dataCategory: value,
+     *   dataType: "", format: "", source: "",
+     * })
+     * ```
+     */
+    onCommit?: (row: Row<TData>, value: string) => Partial<TData>;
+    /**
+     * When `true`, a cell whose `enableEditing` returns `false` renders a
+     * **disabled** TextInput / Dropdown (matching `editVariant`) instead of
+     * falling back to `displayCell` or plain text.
+     */
+    editShowDisabledField?: boolean;
+    /**
+     * Custom preview renderer shown when the cell is **not** in edit mode.
+     * Defaults to the plain string value of `row.original[key]`.
+     */
+    displayCell?: (row: Row<TData>) => React.ReactNode;
+};
+export interface DataTableEditingProps<TData extends RowData = RowData> {
+    /** Master switch — set `true` to enable editing features. */
+    enableEditing?: boolean;
+    /** How editing is activated visually. @default "cell" */
+    editDisplayMode?: EditDisplayMode;
+    /** Gesture that enters edit mode. @default "click" */
+    editTrigger?: EditTrigger;
+    /**
+     * Called every time a cell commits a new value.  The `patch` object is
+     * built from the column's `commitResets` / `mapCommitValue` or defaults
+     * to `{ [columnId]: rawValue }`.
+     */
+    onCellCommit?: (rowId: string, columnId: string, patch: Partial<TData>) => void;
+    /**
+     * Rows that return `true` render their editable columns in edit mode
+     * **permanently** (e.g. an "add" footer row).
+     */
+    alwaysEditing?: (row: Row<TData>) => boolean;
+    /**
+     * When `true` (the default when `enableEditing` is set), Tab / Shift+Tab
+     * inside an editing cell moves focus to the next / previous editable
+     * column in the same row.
+     */
+    enableCellTabTraversal?: boolean;
+    /**
+     * Explicit ordered list of column ids for Tab traversal.  When omitted
+     * the engine auto-detects editable columns in definition order.
+     */
+    editableColumnIds?: string[];
+}
+export interface EditingState {
+    editingRowId: string | null;
+    editingCell: {
+        rowId: string;
+        columnId: string;
+    } | null;
+    editDisplayMode: EditDisplayMode;
+    editTrigger: EditTrigger;
+    requestRowEdit: (rowId: string) => void;
+    requestCellEdit: (rowId: string, columnId: string) => void;
+    clearEdit: () => void;
+    onFieldBlur: (rowId: string, columnId: string) => void;
+    moveCellEdit: (rowId: string, fromColumnId: string, delta: -1 | 1) => "moved" | "exited";
+}