@rovula/ui 0.1.28 → 0.1.29

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?: (row: Row<TData>, index: number) => string | undefined;
+    /** Return a className string to apply to a specific body cell. */
+    cellClassName?: (cell: Cell<TData, unknown>, row: Row<TData>) => string | undefined;
+    /** Return a className string to apply to a specific column header cell (`<th>`). */
+    headerCellClassName?: (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";
+}

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

@@ -1,5 +1,8 @@
+import React from "react";
+import type { StoryObj } from "@storybook/react";
+import { ColumnDef, Row } from "@tanstack/react-table";
 import { DataTable } from "./DataTable";
-import { ColumnDef } from "@tanstack/react-table";
+import type { EditableColumnDef } from "./DataTable.editing.types";
 declare const meta: {
     title: string;
     component: typeof DataTable;
@@ -7,16 +10,275 @@ declare const meta: {
     parameters: {
         layout: string;
     };
+    argTypes: {
+        bordered: {
+            control: "boolean";
+        };
+        surface: {
+            control: "radio";
+            options: string[];
+        };
+        divided: {
+            control: "boolean";
+        };
+        striped: {
+            control: "boolean";
+        };
+        fetchingMore: {
+            control: "boolean";
+        };
+        loading: {
+            control: "boolean";
+        };
+    };
     decorators: ((Story: import("@storybook/csf").PartialStoryFn<import("@storybook/react").ReactRenderer, {
-        columns: ColumnDef<unknown, unknown>[];
+        columns: (ColumnDef<unknown, unknown> | EditableColumnDef<unknown, unknown>)[];
         data: unknown[];
         manualSorting?: boolean | undefined;
         onSorting?: ((sorting: import("@tanstack/react-table").SortingState) => void) | undefined;
+        paginationMode?: import("./DataTable").DataTablePaginationMode | undefined;
+        totalCount?: number | undefined;
+        pageIndex?: number | undefined;
+        pageSize?: number | undefined;
+        onPaginationChange?: ((state: import("@tanstack/react-table").PaginationState) => void) | undefined;
+        pageSizeOptions?: number[] | undefined;
         fetchMoreData?: (() => void) | undefined;
+        fetchMoreOffset?: number | undefined;
+        fetchingMore?: boolean | undefined;
+        fetchingMoreLabel?: string | undefined;
+        loading?: boolean | undefined;
+        loadingLabel?: string | undefined;
+        virtualized?: boolean | undefined;
+        virtualRowEstimate?: number | undefined;
+        highlightRowId?: string | string[] | undefined;
+        scrollToHighlightOnMouseLeave?: boolean | undefined;
+        selectable?: boolean | undefined;
+        onRowSelectionChange?: ((rows: import("@tanstack/react-table").RowSelectionState) => void) | undefined;
+        rowActions?: ((row: Row<unknown>) => React.ReactNode) | undefined;
+        reorderable?: boolean | undefined;
+        getRowId?: ((row: unknown) => string) | undefined;
+        onRowReorder?: ((data: unknown[]) => void) | undefined;
+        isRowReorderLocked?: ((row: Row<unknown>) => boolean) | undefined;
+        onRowClick?: ((row: Row<unknown>, event: React.MouseEvent) => void) | undefined;
+        onCellClick?: ((cell: import("@tanstack/react-table").Cell<unknown, unknown>, row: Row<unknown>, event: React.MouseEvent) => void) | undefined;
+        getSubRows?: ((row: unknown) => unknown[] | undefined) | undefined;
+        defaultExpanded?: (import("@tanstack/react-table").ExpandedState | boolean) | undefined;
+        expanded?: import("@tanstack/react-table").ExpandedState | undefined;
+        onExpandedChange?: ((expanded: import("@tanstack/react-table").ExpandedState) => void) | undefined;
+        bordered?: boolean | undefined;
+        surface?: "default" | "panel" | undefined;
+        striped?: boolean | undefined;
+        divided?: boolean | undefined;
+        rowClassName?: ((row: Row<unknown>, index: number) => string | undefined) | undefined;
+        cellClassName?: ((cell: import("@tanstack/react-table").Cell<unknown, unknown>, row: Row<unknown>) => string | undefined) | undefined;
+        headerCellClassName?: ((header: import("@tanstack/react-table").Header<unknown, unknown>) => string | undefined) | undefined;
+        headerClassName?: string | undefined;
+        headerRowClassName?: string | undefined;
+        sortIndicatorVisibility?: "always" | "hover" | undefined;
+        tableLayout?: "auto" | "fixed" | "equal" | undefined;
+        columnManagement?: (boolean | import("./DataTable").ColumnManagementOptions) | undefined;
+        resizable?: boolean | undefined;
+        columnMinSize?: number | undefined;
+        columnMaxSize?: number | undefined;
+        className?: string | undefined;
+        testId?: string | undefined;
+        enableEditing?: boolean | undefined;
+        editDisplayMode?: import("./DataTable.editing.types").EditDisplayMode | undefined;
+        editTrigger?: import("./DataTable.editing.types").EditTrigger | undefined;
+        onCellCommit?: ((rowId: string, columnId: string, patch: Partial<unknown>) => void) | undefined;
+        alwaysEditing?: ((row: Row<unknown>) => boolean) | undefined;
+        enableCellTabTraversal?: boolean | undefined;
+        editableColumnIds?: string[] | undefined;
     }>) => import("react/jsx-runtime").JSX.Element)[];
 };
 export default meta;
-export declare const Default: {
-    args: {};
-    render: (args: {}) => import("react/jsx-runtime").JSX.Element;
-};
+/** Default — striped rows + column dividers, all columns sortable. */
+export declare const Default: StoryObj;
+/** Empty state — displayed when `data` is an empty array. */
+export declare const Empty: StoryObj;
+/** Non-striped with column dividers only. */
+export declare const Divided: StoryObj;
+/**
+ * DataTable inside a panel — matches modal spec: horizontal row separators only
+ * (no vertical column rules), compact height without a stretched empty body.
+ */
+export declare const OnPanelSurface: StoryObj;
+/** Panel + client pagination — footer sits in the same surface scope as the table body. */
+export declare const OnPanelSurfaceWithPagination: StoryObj;
+/** Client-side pagination — DataTable manages page index & size internally. */
+export declare const WithClientPagination: StoryObj;
+/**
+ * Server-side pagination — the caller controls `pageIndex` / `pageSize` and
+ * slices data accordingly. `totalCount` drives the page-count calculation.
+ */
+export declare const WithServerPagination: StoryObj;
+/**
+ * Infinite mode (default) — no pagination bar; the table body scrolls inside a
+ * fixed height. Use when the caller already passes the full (or windowed) dataset.
+ */
+export declare const WithInfiniteScrollStatic: StoryObj;
+/**
+ * Infinite scroll + load more — DataTable calls{" "}
+ * <code className="typography-mono">fetchMoreData</code> when the scroll position
+ * is within 10px of the bottom (see <code className="typography-mono">DataTable</code>{" "}
+ * <code className="typography-mono">useEffect</code> on <code className="typography-mono">scrollRef</code>).
+ * This story simulates an async page append.
+ */
+export declare const WithInfiniteScrollLoadMore: StoryObj;
+/**
+ * Initial load — pass `loading={true}` with `data={[]}` until the first page
+ * arrives; then set `loading={false}` and pass rows. Infinite `fetchMoreData`
+ * does not run while `loading` is true.
+ */
+export declare const WithInfiniteScrollInitialLoading: StoryObj;
+/**
+ * **What this library does *not* do:** `DataTable` has **no built-in row
+ * virtualization** — every row in `data` is rendered in the DOM (TanStack
+ * `getRowModel`). Very large `data.length` will cost more paint/layout work.
+ *
+ * **What to use instead:**
+ * - `paginationMode="client"` or `"server"` to cap rows per page
+ * - `paginationMode="infinite"` + `fetchMoreData` and **slice/window data in the parent**
+ * - Or wrap your own virtualizer (e.g. `@tanstack/react-virtual`) if you need
+ *   millions of rows in one scroll view
+ *
+ * This story mounts **800** synthetic rows so you can feel scroll/render cost
+ * in Storybook (dev builds are slower than production).
+ */
+export declare const PerformanceLargeDataset: StoryObj;
+/**
+ * Built-in **`virtualized`** — only a vertical window of rows is mounted; the
+ * rest are represented by spacer rows. Tune **`virtualRowEstimate`** (px) to
+ * match your row height so scroll position stays aligned.
+ *
+ * Limitations: fixed-height assumption; incompatible with **`reorderable`** in
+ * the virtualized path (use non-virtualized mode for drag-reorder).
+ */
+export declare const WithVirtualizedRows: StoryObj;
+/** Checkbox selection — header checkbox selects all; row checkboxes select individually. */
+export declare const WithSelection: StoryObj;
+/**
+ * Row highlight + scroll — use `highlightRowId` to visually mark important rows
+ * (uses the same token as selected rows) and automatically scroll them into view.
+ */
+export declare const WithRowHighlightAndScroll: StoryObj;
+/**
+ * Censor-style list — large, virtualized table where `highlightRowId` moves
+ * automatically over time (e.g. matching the latest event / time).
+ */
+export declare const WithVirtualizedCensorTimeline: StoryObj;
+/** Fixed actions column at the far right — rendered via `rowActions` prop. */
+export declare const WithRowActions: StoryObj;
+/**
+ * Uncontrolled tree rows — `defaultExpanded={true}` opens all nodes on mount.
+ * The user can collapse/expand rows freely; state is managed internally.
+ */
+export declare const WithExpandableRows: StoryObj;
+/**
+ * Controlled expand — the caller owns `expanded` state via `expanded` +
+ * `onExpandedChange`. Collapsing a row in the table calls `onExpandedChange`;
+ * if the parent doesn't update the state, the row "springs back" open.
+ */
+export declare const WithControlledExpand: StoryObj;
+/**
+ * Column management panel — click ⋮ on any column header.
+ *  - Toggle per-column visibility with the Switch
+ *  - "Hide all" hides everything except one column
+ *  - "Show all" restores all columns
+ *  - Drag the ⠿ grip to reorder columns
+ */
+export declare const WithColumnManagement: StoryObj;
+/**
+ * Column management with restricted options:
+ *  - `reorder: false` — drag handle hidden, column order is fixed
+ *  - `hideAll: false` — "Hide all" button removed
+ *
+ * Pass any subset of `ColumnManagementOptions` to tailor the panel.
+ */
+export declare const WithColumnManagementOptions: StoryObj;
+/**
+ * Resizable columns — drag the right edge of any column header.
+ *
+ * Global bounds via `columnMinSize` / `columnMaxSize`.
+ * Per-column overrides in the column def (`minSize`, `maxSize`):
+ *  - "Asset name": `minSize: 120`
+ *  - "KPI (%)": `maxSize: 160`
+ */
+export declare const WithColumnResize: StoryObj;
+/**
+ * All features combined:
+ *  - Checkbox selection
+ *  - Sortable columns
+ *  - Client-side pagination
+ *  - Column management (visibility + reorder)
+ *  - Column resize
+ *  - Row actions
+ */
+export declare const KitchenSink: StoryObj;
+/**
+ * Drag-to-reorder rows — a grip handle is prepended automatically.
+ * `onRowReorder` fires with the new data array after a drop.
+ */
+export declare const WithRowReorder: StoryObj;
+/** Row click — clicking any row fires `onRowClick`. Rows show `cursor-pointer`. */
+export declare const WithRowClick: StoryObj;
+/**
+ * Cell click — `onCellClick` fires for individual cells.
+ * Use `event.stopPropagation()` to prevent `onRowClick` from also firing.
+ */
+export declare const WithCellClick: StoryObj;
+/**
+ * Sort indicator always visible — `sortIndicatorVisibility="always"` shows the
+ * sort icon on every sortable column, not just on hover.
+ */
+export declare const SortIndicatorAlwaysVisible: StoryObj;
+/**
+ * Side-by-side comparison of `tableLayout="auto"` vs `"fixed"` vs `"equal"`.
+ *
+ * - **auto** — browser distributes width based on cell content; `size` is ignored.
+ * - **fixed** — `size` is used as px per column; the last non-exact column grows
+ *   so the table stays full-width (here: Status absorbs the remainder).
+ * - **equal** — all columns without `meta.exactWidth` share the remaining width equally.
+ *   With `resizable`, drag handles are off for this row so equal widths are preserved.
+ */
+export declare const TableLayoutComparison: StoryObj;
+/**
+ * `rowClassName` and `cellClassName` let you style individual rows and cells
+ * based on their data.
+ *
+ * - Rows with status **"Completed"** get a green-tinted background.
+ * - Rows with status **"To do"** get a subtle white/opacity background.
+ * - The **"Status"** column cells are bold.
+ * - The **"Type"** cells for ROV are highlighted with an info tint.
+ */
+export declare const WithCustomRowAndCellClassName: StoryObj;
+/**
+ * Data management table — Figma **Xspector-New**:
+ * [full frame](https://www.figma.com/design/99rq6FbfPx6hgPS0VCvHJh/Xspector-New?node-id=11965-17125),
+ * [row / field spec](https://www.figma.com/design/99rq6FbfPx6hgPS0VCvHJh/Xspector-New?node-id=11965-17883).
+ *
+ * Uses the **DataTable editing API** (`enableEditing` + `editDisplayMode` +
+ * `editVariant` per column). Edit scope and trigger are toggleable via the
+ * toolbar at the top of the story.
+ */
+export declare const DataManagement: StoryObj;
+/** Data Management — empty state when no columns have been configured yet. */
+export declare const DataManagementEmpty: StoryObj;
+/**
+ * **Editing Field Showcase** — demonstrates every editing feature:
+ *
+ * | Feature | Where |
+ * |---|---|
+ * | `editVariant: "text"` | Product name, Notes |
+ * | `editVariant: "select"` | Category |
+ * | `editVariant: "number"` | Quantity, Price |
+ * | `editVariant: "checkbox"` | Active |
+ * | `editVariant: "custom"` + `editCustomCell` | Priority (inline button picker → Badge display) |
+ * | `editError` | Name (required + min length), Category (required), Price (> 0) |
+ * | `displayCell` | Price (formatted), Active (badge), Notes (italic placeholder) |
+ * | `testId` | Root container has `data-testid="edit-showcase"` |
+ * | Row / Cell mode toggle | Toolbar radio buttons |
+ * | Click / Double-click trigger | Toolbar radio buttons |
+ * | Tab traversal | Tab/Shift+Tab moves between editable fields |
+ */
+export declare const EditingFieldShowcase: StoryObj;