@x12i/data 0.0.0-stage → 1.1.0

package/dist/react.d.ts

@@ -0,0 +1,328 @@
+import * as react from 'react';
+import { ReactNode, Ref, MouseEvent } from 'react';
+import { DensityName } from '@x12i/tokens';
+import { C as ColumnDef, r as DataGridMessages, i as ServerDataSource, x as GridViewState, D as DataGridMessageOverrides, S as SortModelItem, f as FilterModelItem, G as GroupModelItem, I as SelectionState, B as SavedViewStore, z as SavedView } from './messages-BF20Mq97.js';
+import { DelimitedOptions, ColumnPinning, SavedViewSummary } from './index.js';
+export { a as CellType, b as ColumnAlign, n as ColumnOption, o as ColumnPin, e as FilterOperator, M as StatusTone, Z as defaultMessages, _ as defineColumns, ag as resolveMessages } from './messages-BF20Mq97.js';
+
+/** What a custom cell renderer receives. */
+interface CellContext<Row> {
+    row: Row;
+    /** The id from `getRowId`. */
+    rowId: string;
+    /** Index into the `rows` array (client mode) or the server row index. */
+    rowIndex: number;
+    column: DataGridColumn<Row>;
+    /** The raw value, including a pending edit. */
+    value: unknown;
+    /** The formatted text: what export, copy and quick search see. */
+    text: string;
+    selected: boolean;
+    /** The grid's messages, already merged with the overrides. */
+    messages: DataGridMessages;
+    locale: string | undefined;
+}
+/** What a custom header renderer receives. */
+interface HeaderContext<Row> {
+    column: DataGridColumn<Row>;
+    sortDirection: "asc" | "desc" | null;
+    messages: DataGridMessages;
+}
+/** What a custom footer (totals) renderer receives. */
+interface FooterContext<Row> {
+    column: DataGridColumn<Row>;
+    /** The column's aggregate over the filtered rows, or `undefined` when it has none. */
+    value: unknown;
+    /** `value` formatted for display. */
+    text: string;
+    messages: DataGridMessages;
+}
+/** One entry of a row-actions menu. */
+interface RowAction<Row> {
+    id: string;
+    /** Pass a translated string. */
+    label: string;
+    onSelect: (row: Row) => void;
+    disabled?: boolean;
+    tone?: "default" | "danger";
+}
+/**
+ * A grid column: everything in `ColumnDef` plus the renderers that only make
+ * sense in React. A `DataGridColumn` is a `ColumnDef`, so it works with the
+ * headless functions of `@x12i/data` too.
+ */
+interface DataGridColumn<Row> extends ColumnDef<Row> {
+    /** Replaces the default cell. Runs for every rendered cell, so keep it cheap. */
+    cell?: (context: CellContext<Row>) => ReactNode;
+    /** Replaces the header label. The sort, filter and menu buttons stay. */
+    headerCell?: (context: HeaderContext<Row>) => ReactNode;
+    /** Replaces the totals-row content of this column. */
+    footerCell?: (context: FooterContext<Row>) => ReactNode;
+    /** Menu entries for `actions` cells. Return an empty list to show no menu for a row. */
+    actions?: (row: Row) => RowAction<Row>[];
+    /** Target of `link` cells. Without it a string value that looks like a URL is linked. */
+    href?: (row: Row) => string | undefined;
+}
+interface PaginationState {
+    /** Zero-based page index. */
+    page: number;
+    pageSize: number;
+}
+/** What `onCellEdit` receives. Throw or reject to roll the edit back. */
+interface CellEdit<Row> {
+    row: Row;
+    rowId: string;
+    column: DataGridColumn<Row>;
+    /** The parsed new value. */
+    value: unknown;
+    previousValue: unknown;
+}
+type ToolbarOptions = {
+    search?: boolean;
+    columns?: boolean;
+    export?: boolean;
+    copy?: boolean;
+};
+interface DataGridSlots {
+    /** Replaces the "no rows" content. */
+    empty?: ReactNode;
+    /** Replaces the first-load content. */
+    loading?: ReactNode;
+    /** Replaces the error content. Receives the error and a retry function. */
+    error?: (error: unknown, retry: () => void) => ReactNode;
+}
+interface DataGridHandle<Row> {
+    /** Scrolls so the row at a display index is visible. */
+    scrollToIndex(index: number): void;
+    /** Scrolls to a data row by id, when it is in the current view. */
+    scrollToRow(rowId: string): void;
+    /** Moves the cursor and focus. Row 0 is the header, column 0 the first column. */
+    focusCell(row: number, column: number): void;
+    /** CSV of the current view: filtered and sorted rows, visible columns. Server mode fetches every page. */
+    exportCsv(options?: DelimitedOptions): Promise<string>;
+    /** Copies the selected rows, or the focused cell, as tab-separated text. */
+    copySelection(): Promise<boolean>;
+    /** The selected rows that are loaded. */
+    getSelectedRows(): Row[];
+    /** Server mode: drops loaded rows and fetches again. */
+    reload(): void;
+    getViewState(): GridViewState;
+}
+interface DataGridProps<Row> {
+    columns: readonly DataGridColumn<Row>[];
+    /** Client mode: all the rows. The grid sorts, filters, groups and pages them. */
+    rows?: readonly Row[];
+    /** Server mode: the grid asks this for blocks of rows. Give `rows` or `dataSource`, not both. */
+    dataSource?: ServerDataSource<Row>;
+    /** A stable id per row. Used for selection, expansion, editing and React keys. */
+    getRowId: (row: Row, index: number) => string;
+    /** Names the grid for assistive technology. Give one of the two. */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    className?: string;
+    ref?: Ref<DataGridHandle<Row>>;
+    /** Block size of the grid. A number is in pixels. Without it the grid grows up to `maxHeight`. */
+    height?: number | string;
+    maxHeight?: number | string;
+    density?: DensityName;
+    dir?: "ltr" | "rtl";
+    /** Row height to assume until the `--kit-grid-row-height` token can be measured. */
+    estimateRowHeight?: number;
+    /** `auto` virtualizes rows above 100 and columns above 24. */
+    virtualize?: "auto" | boolean;
+    overscan?: number;
+    columnOverscan?: number;
+    locale?: string;
+    timeZone?: string;
+    messages?: DataGridMessageOverrides;
+    sort?: SortModelItem[];
+    defaultSort?: SortModelItem[];
+    onSortChange?: (sort: SortModelItem[]) => void;
+    /** Shift+click adds columns to the sort. Default `true`. */
+    multiSort?: boolean;
+    filter?: FilterModelItem[];
+    defaultFilter?: FilterModelItem[];
+    onFilterChange?: (filter: FilterModelItem[]) => void;
+    quickFilter?: string;
+    defaultQuickFilter?: string;
+    onQuickFilterChange?: (text: string) => void;
+    /** Server mode: wait this long (ms) after the last keystroke before asking the server. Default 250. */
+    quickFilterDelay?: number;
+    group?: GroupModelItem[];
+    defaultGroup?: GroupModelItem[];
+    onGroupChange?: (group: GroupModelItem[]) => void;
+    /** Expanded state per group id. Groups without an entry follow `groupsExpandedByDefault`. */
+    groupExpansion?: Record<string, boolean>;
+    defaultGroupExpansion?: Record<string, boolean>;
+    onGroupExpansionChange?: (expansion: Record<string, boolean>) => void;
+    groupsExpandedByDefault?: boolean;
+    columnVisibility?: Record<string, boolean>;
+    defaultColumnVisibility?: Record<string, boolean>;
+    onColumnVisibilityChange?: (visibility: Record<string, boolean>) => void;
+    columnOrder?: string[];
+    defaultColumnOrder?: string[];
+    onColumnOrderChange?: (order: string[]) => void;
+    columnSizing?: Record<string, number>;
+    defaultColumnSizing?: Record<string, number>;
+    onColumnSizingChange?: (sizing: Record<string, number>) => void;
+    columnPinning?: ColumnPinning;
+    defaultColumnPinning?: ColumnPinning;
+    onColumnPinningChange?: (pinning: ColumnPinning) => void;
+    selectionMode?: "none" | "single" | "multiple";
+    selection?: SelectionState;
+    defaultSelection?: SelectionState;
+    onSelectionChange?: (selection: SelectionState) => void;
+    /** Rows that cannot be selected get no checkbox. */
+    isRowSelectable?: (row: Row) => boolean;
+    /** Renders a detail panel under an expanded row and adds the expander column. */
+    renderDetail?: (row: Row) => ReactNode;
+    /** Height to assume for a detail panel until it is measured. */
+    detailHeight?: number;
+    isRowExpandable?: (row: Row) => boolean;
+    /** Ids of rows whose detail is open. */
+    expanded?: Record<string, boolean>;
+    defaultExpanded?: Record<string, boolean>;
+    onExpandedChange?: (expanded: Record<string, boolean>) => void;
+    /** Called when a data row is clicked, except for clicks on a control inside it (checkbox, button, link, input). */
+    onRowClick?: (row: Row, event: MouseEvent<HTMLElement>) => void;
+    /** Page the rows and show the pagination footer. Without it the grid scrolls. */
+    paginated?: boolean;
+    pagination?: PaginationState;
+    defaultPagination?: PaginationState;
+    onPaginationChange?: (pagination: PaginationState) => void;
+    pageSizeOptions?: number[];
+    /** Server mode without pagination: rows per request. Default 100. */
+    blockSize?: number;
+    /** Called when a cell edit is committed. Reject to roll the edit back. */
+    onCellEdit?: (edit: CellEdit<Row>) => void | Promise<void>;
+    toolbar?: boolean | ToolbarOptions;
+    toolbarStart?: ReactNode;
+    toolbarEnd?: ReactNode;
+    /** Show a totals row from the columns' `aggregate`. */
+    showTotals?: boolean;
+    /** Server mode: totals computed by the server, keyed by column id. */
+    totals?: Record<string, unknown>;
+    /** Client-mode loading flag, for rows that are still being fetched. */
+    loading?: boolean;
+    /** Client-mode error, shown with a retry button when `onRetry` is given. */
+    error?: unknown;
+    onRetry?: () => void;
+    slots?: DataGridSlots;
+    /** Called with the CSV text when the user presses Export, instead of a download. */
+    onExport?: (csv: string) => void;
+    exportFileName?: string;
+}
+
+/**
+ * An accessible, virtualized data grid. See the package README for the full
+ * prop reference; this component owns the layout, the keyboard model and the
+ * state, and delegates the data work to the headless engine of `@x12i/data`.
+ */
+declare function DataGrid<Row>(props: DataGridProps<Row>): react.JSX.Element;
+
+interface PaginationProps {
+    /** Zero-based page index. */
+    page: number;
+    pageSize: number;
+    /** Total rows, or `null` when the server has not said yet. */
+    total: number | null;
+    pageSizeOptions?: number[];
+    onPageChange: (page: number) => void;
+    /** Shows the page-size select when given. */
+    onPageSizeChange?: (pageSize: number) => void;
+    messages?: DataGridMessageOverrides;
+    locale?: string;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * Page controls for a grid or any list: the visible range, a page-size select,
+ * and first, previous, next and last buttons. Pages are zero-based. Use it with
+ * `DataGrid` (which shows it for `paginated`) or on its own.
+ */
+declare function Pagination({ page, pageSize, total, pageSizeOptions, onPageChange, onPageSizeChange, messages: overrides, locale, disabled, className, }: PaginationProps): react.JSX.Element;
+
+interface UseGridStateOptions<Row> {
+    columns: readonly ColumnDef<Row>[];
+    /** Starting values for any part of the view. Columns' `hidden` and `pinned` apply for the rest. */
+    initial?: Partial<GridViewState>;
+    /** Starting page size. Default 25. */
+    initialPageSize?: number;
+}
+/** The controlled props of `DataGrid` that `useGridState` fills in. Spread them: `<DataGrid {...grid.props} />`. */
+interface GridStateProps {
+    sort: SortModelItem[];
+    onSortChange: (sort: SortModelItem[]) => void;
+    filter: FilterModelItem[];
+    onFilterChange: (filter: FilterModelItem[]) => void;
+    quickFilter: string;
+    onQuickFilterChange: (text: string) => void;
+    group: GroupModelItem[];
+    onGroupChange: (group: GroupModelItem[]) => void;
+    columnOrder: string[];
+    onColumnOrderChange: (order: string[]) => void;
+    columnVisibility: Record<string, boolean>;
+    onColumnVisibilityChange: (visibility: Record<string, boolean>) => void;
+    columnSizing: Record<string, number>;
+    onColumnSizingChange: (sizing: Record<string, number>) => void;
+    columnPinning: ColumnPinning;
+    onColumnPinningChange: (pinning: ColumnPinning) => void;
+    selection: SelectionState;
+    onSelectionChange: (selection: SelectionState) => void;
+    pagination: PaginationState;
+    onPaginationChange: (pagination: PaginationState) => void;
+}
+interface UseGridStateResult {
+    /** Spread onto `DataGrid` to control it from outside. */
+    props: GridStateProps;
+    /** The part of the state a saved view keeps. */
+    view: GridViewState;
+    /** Replaces the whole view, for example with the result of `applySavedView`. */
+    setView: (view: GridViewState) => void;
+    /** Back to what the column definitions say. Clears quick search and selection too. */
+    reset: () => void;
+}
+/**
+ * All of the grid's state in one hook, so an app can read it, persist it, put
+ * it in the URL, or reset it. `DataGrid` works without it; use it when you need
+ * to see the sort, filters or selection outside the grid.
+ */
+declare function useGridState<Row>({ columns, initial, initialPageSize }: UseGridStateOptions<Row>): UseGridStateResult;
+
+/** Anything that holds a grid view: the result of `useGridState` fits. */
+interface GridViewController {
+    view: GridViewState;
+    setView: (view: GridViewState) => void;
+}
+interface UseSavedViewsOptions<Row> {
+    store: SavedViewStore;
+    columns: readonly ColumnDef<Row>[];
+    grid: GridViewController;
+}
+interface UseSavedViewsResult {
+    /** The views in the store, from the last refresh. */
+    views: SavedViewSummary[];
+    loading: boolean;
+    /** The error of the last failed store call, or `null`. */
+    error: unknown;
+    /** The id of the view last applied or saved, or `null`. */
+    activeId: string | null;
+    refresh: () => Promise<void>;
+    /** Saves the grid's current view under an id and refreshes the list. */
+    save: (id: string, name?: string) => Promise<void>;
+    /** Loads a view and applies it to the grid. Resolves to `false` when the id has no valid view. */
+    apply: (id: string) => Promise<boolean>;
+    remove: (id: string) => Promise<void>;
+    /** The grid's current view as a `SavedView`, without saving it. */
+    capture: (name?: string) => SavedView;
+}
+/**
+ * Saved views for a grid: list, save the current view, apply one, delete one.
+ * The store is any `SavedViewStore` (`createLocalStorageSavedViewStore`, your
+ * API, the Flowix adapter). A view saved against other columns still applies;
+ * ids the grid does not have are ignored.
+ */
+declare function useSavedViews<Row>({ store, columns, grid }: UseSavedViewsOptions<Row>): UseSavedViewsResult;
+
+export { ColumnDef, DataGrid, DataGridMessageOverrides, DataGridMessages, FilterModelItem, GridViewState, GroupModelItem, Pagination, SavedView, SavedViewStore, SelectionState, ServerDataSource, SortModelItem, useGridState, useSavedViews };
+export type { CellContext, CellEdit, DataGridColumn, DataGridHandle, DataGridProps, DataGridSlots, FooterContext, GridStateProps, GridViewController, HeaderContext, PaginationProps, PaginationState, RowAction, ToolbarOptions, UseGridStateOptions, UseGridStateResult, UseSavedViewsOptions, UseSavedViewsResult };