@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/data-table/data-table.d.ts

@@ -0,0 +1,423 @@
+import * as React from "react";
+import { type Column, type ReactTable } from "@tanstack/react-table";
+import { useLabels } from "../lib/labels.js";
+import type { MenuEntry } from "../lib/variants.js";
+import { Input } from "../components/input.js";
+import { type FilterBarProps } from "./filter-bar.js";
+import { type SavedViewsProps } from "./saved-views.js";
+import { type UrlStateOptions } from "./url-state.js";
+import { type DataTableSelection, type FieldType, type FilterFieldDef, type FilterOption, type ListDensity, type ListState, type ListStateChangeReason, type SavedView, type ViewState } from "./types.js";
+export declare const dataTableLabels: {
+    search: string;
+    searchPlaceholder: string;
+    selectPageRows: string;
+    selectRow: string;
+    selectedCount: string;
+    selectedOnPage: string;
+    selectPage: string;
+    selectAllMatching: string;
+    allSelected: string;
+    clearSelection: string;
+    clear: string;
+    selectionReset: string;
+    bulkActions: string;
+    moreActions: string;
+    rowActions: string;
+    view: string;
+    viewOptions: string;
+    columns: string;
+    findColumn: string;
+    density: string;
+    compact: string;
+    comfortable: string;
+    spacious: string;
+    resetColumns: string;
+    moveUp: string;
+    moveDown: string;
+    sortAsc: string;
+    sortDesc: string;
+    clearSort: string;
+    sortBy: string;
+    sortOrder: string;
+    pinStart: string;
+    pinEnd: string;
+    unpin: string;
+    hide: string;
+    filterBy: string;
+    columnMenu: string;
+    resize: string;
+    export: string;
+    exportPage: string;
+    exportSelected: string;
+    exportAll: string;
+    exportAllServer: string;
+    exportStarted: string;
+    exported: string;
+    emptyTitle: string;
+    emptyDescription: string;
+    noResultsTitle: string;
+    noResultsDescription: string;
+    clearFilters: string;
+    errorTitle: string;
+    retry: string;
+    loading: string;
+    refreshing: string;
+    loadMore: string;
+    noMore: string;
+    edit: string;
+    editHint: string;
+    saving: string;
+    saveFailed: string;
+    invalid: string;
+    yes: string;
+    no: string;
+    none: string;
+    cancel: string;
+    bulkDone: string;
+    bulkFailed: string;
+    undo: string;
+    undone: string;
+    rowCount: string;
+};
+export type DataTableLabels = typeof dataTableLabels;
+type LabelFn = ReturnType<typeof useLabels<DataTableLabels>>;
+export interface DataTableCellContext<T> {
+    row: T;
+    value: unknown;
+    rowId: string;
+    /** Index on the current page. */
+    index: number;
+    column: DataTableColumn<T>;
+}
+/** Inline editor of a column. Optimistic: the cell shows the new value while `onCellEdit` runs. */
+export type DataTableCellEditor<T> = {
+    type: "text" | "number" | "currency" | "date" | "select" | "boolean";
+    /** For `select`. */
+    options?: FilterOption[];
+    /** Return an error message to keep the editor open. */
+    validate?: (value: unknown, row: T) => string | null;
+} | {
+    type: "custom";
+    render: (ctx: {
+        value: unknown;
+        row: T;
+        commit: (value: unknown) => void;
+        cancel: () => void;
+    }) => React.ReactNode;
+};
+export interface DataTableColumn<T> {
+    /** Stable id (state, URL, CSV). */
+    id: string;
+    /** Header text — also the column menu, CSV header, mobile label and filter field name. */
+    header: string;
+    /** Property name or function. Omit for display-only columns (then provide `cell`). */
+    accessor?: (keyof T & string) | ((row: T) => unknown);
+    /** Custom cell. Default: formatted by `type`. */
+    cell?: (ctx: DataTableCellContext<T>) => React.ReactNode;
+    /** Decides formatting, alignment, sorting, filter operators and editor. Default `"text"`. */
+    type?: FieldType;
+    align?: "start" | "center" | "end";
+    /** Options for `enum` (labels + badge tones) — shared with the Filter bar. */
+    options?: FilterOption[];
+    /** ISO 4217 for `currency`. Default: the locale provider's currency. */
+    currency?: string;
+    /** Default: `true` when the column has an accessor. */
+    sortable?: boolean;
+    /** Value used for sorting. Default: the accessor value (enum: option order). */
+    sortValue?: (row: T) => string | number | null | undefined;
+    /** Included in the global search. Default: text, enum, user and tags columns. */
+    searchable?: boolean;
+    /** Generates a Filter bar field (`false` = not filterable). */
+    filter?: Partial<Omit<FilterFieldDef, "field" | "label" | "type">> | false;
+    edit?: DataTableCellEditor<T> | false;
+    /** Role in the mobile card. Default: the first column is the title, the rest `meta`. */
+    mobile?: "title" | "subtitle" | "meta" | "badge" | "avatar" | "hidden";
+    /** `mobile="priority"`: 3 hides first under 640px, then 2 under 480px. */
+    priority?: 1 | 2 | 3;
+    /** CSV value. Default: the raw accessor value. */
+    exportValue?: (row: T) => string | number | null;
+    /** Default `true` (the first column is never hideable). */
+    hideable?: boolean;
+    /** Default `true`. */
+    pinnable?: boolean;
+    /** Default `true`. */
+    resizable?: boolean;
+    /** Width in px. */
+    size?: number;
+    minSize?: number;
+    maxSize?: number;
+    /** Render as a row header (`<th scope="row">`). Default: the title column. */
+    rowHeader?: boolean;
+    /** Visible by default. Default `true`. */
+    defaultVisible?: boolean;
+}
+export interface DataTableBulkAction<T> {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    tone?: "default" | "danger";
+    /** Shows an Alert Dialog first. `description` receives the count. */
+    confirm?: {
+        title: string;
+        description?: (count: number) => string;
+        confirmLabel?: string;
+    };
+    /** `true` disables; a string disables and explains why (tooltip). */
+    disabled?: (selection: DataTableSelection, rows: T[]) => boolean | string;
+    /** `rows` are the selected rows that are loaded (all of them in client mode). Return `{ undo }` to offer Undo. */
+    run: (selection: DataTableSelection, rows: T[]) => Promise<void | {
+        undo?: () => Promise<void> | void;
+    }> | void | {
+        undo?: () => Promise<void> | void;
+    };
+}
+export interface DataTableExportOptions {
+    /** File name without extension. */
+    filename: string;
+    /** Write formatted values ("$4,800.00") instead of raw ones. Default `false`. */
+    formatted?: boolean;
+    /** Server mode "All matching rows" → your export endpoint. */
+    onServerExport?: (state: ListState, selection?: DataTableSelection) => Promise<void> | void;
+}
+export interface DataTableProps<T> extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "children"> {
+    columns: DataTableColumn<T>[];
+    data: T[];
+    getRowId: (row: T) => string;
+    /** Names the table for assistive tech (required). Hidden visually unless `showCaption`. */
+    caption: string;
+    showCaption?: boolean;
+    /** `"client"` (default) sorts, searches, filters and pages in the browser; `"server"` hands the state to you. */
+    mode?: "client" | "server";
+    /** Server mode: total matching rows. */
+    rowCount?: number;
+    /** Controlled list state (any subset). */
+    state?: Partial<ListState>;
+    defaultState?: Partial<ListState>;
+    /** One entry point for every change. `requestId` increases; apply only the latest response. Search is debounced 300ms. */
+    onStateChange?: (next: ListState, reason: ListStateChangeReason, requestId: number) => void;
+    /** Sync q, filters, sort, page and view with the URL. */
+    urlState?: boolean | UrlStateOptions;
+    /** Remember column visibility, order, widths, pins and density in localStorage under this key. */
+    storageKey?: string;
+    loading?: boolean;
+    error?: {
+        message: React.ReactNode;
+        onRetry?: () => void;
+    } | null;
+    pagination?: "pages" | "load-more" | "infinite" | "none";
+    /** Default `[25, 50, 100]`. */
+    pageSizes?: number[];
+    onLoadMore?: () => Promise<void> | void;
+    hasMore?: boolean;
+    /** Cursor pagination (server): the cursors around the current page. */
+    cursors?: {
+        prev: string | null;
+        next: string | null;
+    };
+    /** Render only visible rows. Use with `pagination="none"` / `"infinite"` for long lists. */
+    virtual?: boolean | {
+        estimateRowHeight?: number;
+        overscan?: number;
+        height?: string;
+    };
+    /** Checkbox column + bulk bar. `"single"` = one row at a time. */
+    selectable?: boolean | "single";
+    selection?: DataTableSelection;
+    defaultSelection?: DataTableSelection;
+    onSelectionChange?: (selection: DataTableSelection) => void;
+    bulkActions?: DataTableBulkAction<T>[];
+    /** Whether a row can be selected; a string explains why not. */
+    rowSelectable?: (row: T) => boolean | string;
+    onRowClick?: (row: T) => void;
+    /** Makes the title cell a real link; the whole row is clickable by pointer. */
+    rowHref?: (row: T) => string;
+    /** "⋯" menu in the last column. */
+    rowActions?: (row: T) => MenuEntry[];
+    /** Persist an inline edit. Reject to roll back (the message is shown). */
+    onCellEdit?: (edit: {
+        row: T;
+        rowId: string;
+        columnId: string;
+        value: unknown;
+    }) => Promise<void> | void;
+    readOnly?: boolean;
+    /** `"grid"`: ARIA grid with arrow-key cell navigation (spreadsheet-like editing). Default `"table"`. */
+    navigation?: "table" | "grid";
+    /** Accessible text of a row ("Jane Cooper"). Default: the title column. */
+    getRowLabel?: (row: T) => string;
+    /** No data at all (first use). */
+    empty?: React.ReactNode;
+    /** Data, but the search / filters match nothing. */
+    noResults?: React.ReactNode;
+    /** Under 640px of container width: `cards` (default), `priority` (drop columns) or `scroll`. */
+    mobile?: "cards" | "priority" | "scroll";
+    export?: DataTableExportOptions;
+    /** Table-local density. `"inherit"` follows the page. */
+    density?: "inherit" | ListDensity;
+    /** `card`: inside its own surface. `flush`: full width (WordPress-style list screens). */
+    variant?: "card" | "flush";
+    /** Extra toolbar content (a Filter bar, Saved views…) for the default layout. */
+    toolbar?: React.ReactNode;
+    /** `/` search, Esc clear selection, `x` toggle the focused row. Default `true`. */
+    shortcuts?: boolean;
+    /** Current user for "Me" filters on user fields. */
+    me?: {
+        id: string;
+        name: string;
+    };
+    labels?: Partial<DataTableLabels>;
+    /** Compose the parts yourself (`DataTableToolbar`, `DataTableContent`, `DataTableFooter`…). */
+    children?: React.ReactNode;
+}
+export declare function readColumnValue<T>(col: DataTableColumn<T>, row: T): unknown;
+/** Filter bar fields from Data Table columns (`filter: false` opts out; display-only columns are skipped). */
+export declare function filterFieldsFromColumns<T>(cols: DataTableColumn<T>[]): FilterFieldDef[];
+declare const features: {
+    rowSortingFeature: import("@tanstack/react-table").TableFeature;
+    rowPaginationFeature: import("@tanstack/react-table").TableFeature;
+    columnVisibilityFeature: import("@tanstack/react-table").TableFeature;
+    columnOrderingFeature: import("@tanstack/react-table").TableFeature;
+    columnSizingFeature: import("@tanstack/react-table").TableFeature;
+    columnResizingFeature: import("@tanstack/react-table").TableFeature;
+    columnPinningFeature: import("@tanstack/react-table").TableFeature;
+    sortedRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+    paginatedRowModel: (table: import("@tanstack/react-table").Table<any, any>) => () => import("@tanstack/react-table").RowModel<any, any>;
+};
+type Features = typeof features;
+type TColumn<T> = Column<Features, any, unknown>;
+interface CellStatus {
+    value: unknown;
+    status: "saving" | "saved" | "error";
+    error?: string;
+}
+export interface DataTableContextValue<T = any> {
+    /** The TanStack v9 table instance (escape hatch). */
+    table: ReactTable<Features, any>;
+    state: ListState;
+    setState: (patch: Partial<ListState>, reason?: ListStateChangeReason) => void;
+    selection: DataTableSelection;
+    setSelection: (s: DataTableSelection) => void;
+    /** Columns by id. */
+    columns: DataTableColumn<T>[];
+    /** Filter fields generated from the columns. */
+    fields: FilterFieldDef[];
+    /** Rows on the current page. */
+    pageRows: T[];
+    /** Every row after search and filters (client) or the loaded rows (server). */
+    filteredRows: T[];
+    /** Total matching rows. */
+    total: number;
+    /** Bind a Filter bar: `<FilterBar {...filterBarProps} />`. */
+    filterBarProps: Pick<FilterBarProps, "fields" | "value" | "onChange" | "q" | "onQChange" | "addRequest" | "resultCount" | "me">;
+    /** Bind Saved views: `<SavedViews {...savedViewsBinding(views)} … />`. */
+    savedViewsBinding: (views: SavedView[]) => Pick<SavedViewsProps, "activeId" | "current" | "onSelect" | "onReset">;
+    /** Download a CSV of the page, the selection or every row. */
+    exportCsv: (o?: {
+        scope?: "page" | "selected" | "all";
+        filename?: string;
+        formatted?: boolean;
+    }) => void;
+    /** Ask a bound Filter bar to open its editor for a column. */
+    requestFilter: (columnId: string) => void;
+    /** @internal */
+    props: DataTableProps<T>;
+    /** @internal */
+    internal: Internal<T>;
+}
+interface Internal<T> {
+    t: LabelFn;
+    width: number | undefined;
+    narrow: boolean;
+    cards: boolean;
+    searchRef: React.RefObject<HTMLInputElement | null>;
+    filterBound: boolean;
+    setFilterBound: (b: boolean) => void;
+    editing: {
+        rowId: string;
+        columnId: string;
+    } | null;
+    setEditing: (e: {
+        rowId: string;
+        columnId: string;
+    } | null) => void;
+    cellStatus: Record<string, CellStatus>;
+    commitEdit: (row: T, rowId: string, col: DataTableColumn<T>, value: unknown) => void;
+    announce: (msg: string) => void;
+    rowLabel: (row: T) => string;
+    titleColumn: DataTableColumn<T> | undefined;
+    orderedColumns: TColumn<T>[];
+    defaultColumns: ListState["columns"];
+    lastClicked: React.MutableRefObject<number | null>;
+    isSelectable: (row: T) => boolean | string;
+    hasQuery: boolean;
+    requestId: React.MutableRefObject<number>;
+    filterRequest: {
+        field: string;
+        key: number;
+    } | null;
+}
+/**
+ * The table's state and helpers, for custom layouts and bindings inside `<DataTable>`.
+ *
+ * ```tsx
+ * const { state, selection, exportCsv, filterBarProps } = useDataTable<Contact>();
+ * ```
+ */
+export declare function useDataTable<T = unknown>(): DataTableContextValue<T>;
+/**
+ * The backbone of every list screen: sorting, search, filters, column management, selection and
+ * bulk actions, inline editing, pagination, server mode, URL state, mobile cards and CSV.
+ * Built on TanStack Table v9 — `useDataTable().table` is the escape hatch.
+ *
+ * ```tsx
+ * <DataTable caption="Contacts" columns={columns} data={contacts} getRowId={(c) => c.id} selectable bulkActions={actions} />
+ * ```
+ */
+export declare function DataTable<T>(props: DataTableProps<T>): React.JSX.Element;
+/**
+ * The bar above the table. While rows are selected it shows the bulk bar in the same place
+ * (same height, no layout jump).
+ */
+export declare function DataTableToolbar({ className, children, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export interface DataTableSearchProps extends Omit<React.ComponentProps<typeof Input>, "value" | "onChange"> {
+    /** ms before the search applies. Default 300. */
+    debounce?: number;
+}
+/** Global search across the searchable columns. `/` focuses it. */
+export declare function DataTableSearch({ debounce, className, placeholder, ...props }: DataTableSearchProps): React.JSX.Element;
+/** A Filter bar bound to the table (fields from the columns, "Filter by this column" opens it). */
+export declare function DataTableFilterBar(props: Partial<FilterBarProps>): React.JSX.Element;
+export interface DataTableSavedViewsProps extends Omit<SavedViewsProps, "activeId" | "current" | "onSelect" | "onReset"> {
+}
+/** Saved views bound to the table: switching applies the view, edits mark it modified. */
+export declare function DataTableSavedViews(props: DataTableSavedViewsProps): React.JSX.Element;
+/** Replaces the toolbar while rows are selected: count, select-all across pages, actions. */
+export declare function DataTableBulkBar({ className }: {
+    className?: string;
+}): React.JSX.Element;
+/** "View" popover: show/hide and reorder columns, density, reset. */
+export declare function DataTableViewOptions({ className }: {
+    className?: string;
+}): React.JSX.Element;
+/** "Export" menu: rows on this page, selected rows, all rows (or your server export). */
+export declare function DataTableExport({ className }: {
+    className?: string;
+}): React.JSX.Element;
+/** Default rendering of a value by column type. */
+export declare function DataTableValue<T>({ column, value }: {
+    column: DataTableColumn<T>;
+    value: unknown;
+}): React.JSX.Element;
+/** The table (or the mobile cards) with loading, empty, no-results and error states. */
+export declare function DataTableContent({ className }: {
+    className?: string;
+}): React.JSX.Element;
+/** Mobile layout: every row a card (title, subtitle, badge, label:value meta, checkbox, actions). */
+export declare function DataTableCards({ className }: {
+    className?: string;
+}): React.JSX.Element;
+/** Pagination (pages, cursor), "Load more" or the infinite-scroll sentinel. */
+export declare function DataTableFooter({ className }: {
+    className?: string;
+}): React.JSX.Element | null;
+export type { ViewState };