@helix-x/datagrid-ui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,502 @@
+import * as react from 'react';
+import { ReactNode, Ref } from 'react';
+
+/**
+ * The wire shapes below intentionally mirror what ag-grid's server-side row
+ * model posts, because most existing backends that speak "grid" already parse
+ * them. Keeping them identical is what lets a screen swap grids without a
+ * backend change.
+ */
+type TextFilterType = 'contains' | 'notContains' | 'equals' | 'notEqual' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank';
+type NumberFilterType = 'equals' | 'notEqual' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'inRange' | 'blank' | 'notBlank';
+type DateFilterType = 'equals' | 'notEqual' | 'before' | 'after' | 'inRange' | 'blank' | 'notBlank';
+interface TextFilterModel {
+    filterType: 'text';
+    type: TextFilterType;
+    filter?: string;
+}
+interface NumberFilterModel {
+    filterType: 'number';
+    type: NumberFilterType;
+    filter?: number;
+    filterTo?: number;
+}
+interface DateFilterModel {
+    filterType: 'date';
+    type: DateFilterType;
+    /** `YYYY-MM-DD` */
+    dateFrom?: string;
+    dateTo?: string;
+}
+interface SetFilterModel {
+    filterType: 'set';
+    values: string[];
+}
+type HxFilterModel = TextFilterModel | NumberFilterModel | DateFilterModel | SetFilterModel;
+type FilterModelMap = Record<string, HxFilterModel>;
+type FilterKind = 'text' | 'number' | 'date' | 'set';
+type SortDirection = 'asc' | 'desc';
+interface SortModelItem {
+    colId: string;
+    sort: SortDirection;
+}
+/**
+ * Structurally compatible with ag-grid's `IServerSideGetRowsRequest`, so an
+ * endpoint written for that model accepts this verbatim. The grouping/pivot
+ * fields are always sent empty — this grid does not implement them — but they
+ * are present so servers that destructure them do not fall over.
+ */
+interface HxRowsRequest {
+    startRow: number;
+    endRow: number;
+    sortModel: SortModelItem[];
+    filterModel: FilterModelMap;
+    rowGroupCols: never[];
+    valueCols: never[];
+    pivotCols: never[];
+    pivotMode: false;
+    groupKeys: never[];
+}
+interface HxRowsResponse<T> {
+    rows: T[];
+    /** Total row count across all pages, or -1 when unknown. */
+    lastRow: number;
+}
+interface HxDataSource<T> {
+    getRows(request: HxRowsRequest, signal: AbortSignal): Promise<HxRowsResponse<T>>;
+}
+type Pinned = 'left' | 'right';
+interface CellRendererParams<T, C = unknown> {
+    row: T;
+    rowIndex: number;
+    value: unknown;
+    formatted: string;
+    column: ColumnDef<T, C>;
+    /**
+     * Arbitrary app state handed to every renderer. Put volatile things here
+     * (in-flight ids, permission checks, handlers) so column definitions can stay
+     * memoised on `[]` and never rebuild.
+     */
+    context: C;
+    api: GridApi<T>;
+}
+interface EditorParams<T, C = unknown> {
+    value: unknown;
+    row: T;
+    column: ColumnDef<T, C>;
+    context: C;
+    /** Writes into the row draft. Never hits the network. */
+    onChange: (value: unknown) => void;
+    /** Commit the whole row. */
+    onCommit: () => void;
+    onCancel: () => void;
+    error?: string;
+    autoFocus?: boolean;
+}
+type EditorComponent<T, C = unknown> = (params: EditorParams<T, C>) => ReactNode;
+type BuiltinEditor = 'text' | 'number' | 'select' | 'date' | 'checkbox';
+interface SelectOption {
+    label: string;
+    value: unknown;
+}
+interface ColumnDef<T, C = unknown> {
+    /** Stable identity. Falls back to `field` when omitted. */
+    colId?: string;
+    /** Dotted path into the row. Also used as the server-side filter/sort key. */
+    field?: string;
+    header: ReactNode;
+    /** Plain-text header, used for exports when `header` is a node. */
+    headerName?: string;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    /** Share of the leftover horizontal space. */
+    flex?: number;
+    pinned?: Pinned;
+    hide?: boolean;
+    sortable?: boolean;
+    resizable?: boolean;
+    /** Prevent the user dragging this column out of position. */
+    lockPosition?: boolean;
+    filter?: FilterKind | false;
+    filterParams?: {
+        /** Static values, or a loader for a set filter whose options come from an API. */
+        values?: string[] | (() => Promise<string[]>);
+        /** Hide the always-visible filter input under the header for this column. */
+        suppressFloatingFilter?: boolean;
+    };
+    /** Alternative flat keys to try when the server flattens nested fields. */
+    fieldAliases?: string[];
+    valueGetter?: (row: T) => unknown;
+    valueFormatter?: (value: unknown, row: T) => string;
+    cellRenderer?: (params: CellRendererParams<T, C>) => ReactNode;
+    editable?: boolean | ((row: T) => boolean);
+    editor?: BuiltinEditor | EditorComponent<T, C>;
+    editorParams?: {
+        options?: SelectOption[];
+        placeholder?: string;
+    };
+    exportValue?: (row: T) => string;
+    suppressExport?: boolean;
+    cellClassName?: string | ((row: T) => string);
+    headerClassName?: string;
+    /** Horizontal alignment of the cell content. */
+    align?: 'left' | 'center' | 'right';
+}
+/** A column with every default resolved. Internal, but exported for renderers. */
+interface ResolvedColumn<T, C = unknown> extends ColumnDef<T, C> {
+    colId: string;
+    width: number;
+    minWidth: number;
+    sortable: boolean;
+    resizable: boolean;
+}
+/** Geometry for one visible column, computed once per layout change. */
+interface ColumnLayoutItem<T, C = unknown> {
+    column: ResolvedColumn<T, C>;
+    colId: string;
+    width: number;
+    /** Offset from the left edge of the full (unscrolled) column strip. */
+    left: number;
+    pinned?: Pinned;
+    /** `left`/`right` offset to use for `position: sticky` on pinned columns. */
+    stickyOffset: number;
+}
+interface ColumnLayout<T, C = unknown> {
+    items: ColumnLayoutItem<T, C>[];
+    totalWidth: number;
+    leftPinnedWidth: number;
+    rightPinnedWidth: number;
+}
+type RowCommitResult = {
+    ok: true;
+    row?: unknown;
+} | {
+    ok: false;
+    errors: Record<string, string>;
+    message?: string;
+};
+declare const GRID_STATE_VERSION = 1;
+interface PersistedGridState {
+    v: number;
+    columns: {
+        order: string[];
+        hidden: string[];
+        widths: Record<string, number>;
+        pinned: Record<string, Pinned>;
+    };
+    sort: SortModelItem[];
+    filters: FilterModelMap;
+    pagination: {
+        pageSize: number;
+    };
+}
+interface ExportCsvOptions {
+    onlySelected?: boolean;
+    fileName?: string;
+    /** Field separator. Defaults to `,`. */
+    separator?: string;
+}
+interface GridApi<T> {
+    /** Re-fetch. `purge` drops every cached block first. */
+    refresh(options?: {
+        purge?: boolean;
+    }): void;
+    getDisplayedRows(): T[];
+    getSelectedRows(): T[];
+    getSelectedIds(): Array<string | number>;
+    clearSelection(): void;
+    selectAll(): void;
+    exportCsv(options?: ExportCsvOptions): void;
+    copySelectionToClipboard(): Promise<void>;
+    getFilterModel(): FilterModelMap;
+    setFilterModel(model: FilterModelMap): void;
+    getSortModel(): SortModelItem[];
+    setSortModel(model: SortModelItem[]): void;
+    resetColumns(): void;
+    /** Patch rows already on screen without a round trip. */
+    updateRows(rows: T[]): void;
+    startEditing(rowId: string | number): void;
+    stopEditing(): void;
+}
+
+type RowId = string | number;
+interface UseSelectionModelResult<T> {
+    selectedIds: Set<RowId>;
+    isSelected: (id: RowId) => boolean;
+    /** True when every row currently on screen is selected. */
+    allVisibleSelected: boolean;
+    someVisibleSelected: boolean;
+    toggleRow: (id: RowId, index: number, shiftKey: boolean) => void;
+    toggleAllVisible: () => void;
+    clear: () => void;
+    selectAllVisible: () => void;
+    getSelectedRows: () => T[];
+}
+/**
+ * Selection lives here as a real React model rather than being read back out of
+ * persisted grid state -- that indirection is what made the previous
+ * implementation's "is anything selected?" check unreliable.
+ */
+declare function useSelectionModel<T>(rows: T[], getRowId: (row: T) => RowId, onSelectionChanged?: (ids: RowId[]) => void): UseSelectionModelResult<T>;
+
+interface DataGridProps<T, C = unknown> {
+    columns: ColumnDef<T, C>[];
+    dataSource: HxDataSource<T>;
+    getRowId: (row: T) => RowId;
+    /** Volatile app state handed to every cell renderer. */
+    context?: C;
+    /** localStorage key for column/sort/filter/page-size preferences. */
+    storageKey?: string;
+    rowHeight?: number;
+    headerHeight?: number;
+    /** Show the always-visible filter inputs under the header. */
+    floatingFilter?: boolean;
+    selectable?: boolean;
+    defaultPageSize?: number;
+    pageSizeOptions?: number[];
+    /** Enables row editing. Return `{ ok:false, errors }` to keep the row open. */
+    onRowCommit?: (draft: T, original: T) => Promise<RowCommitResult> | RowCommitResult;
+    onSelectionChanged?: (ids: RowId[]) => void;
+    /** Enables dropping files onto a row (e.g. to attach documents to it). */
+    onRowFilesDropped?: (row: T, files: File[]) => void;
+    onError?: (error: unknown) => void;
+    /** Rendered above the header; receives the live api. */
+    toolbar?: (api: GridApi<T>) => ReactNode;
+    emptyMessage?: ReactNode;
+    exportFileName?: string;
+    className?: string;
+    /** Height of the scrolling area. Defaults to `70vh`. */
+    height?: number | string;
+    apiRef?: Ref<GridApi<T>>;
+}
+declare function DataGrid<T, C = unknown>({ columns, dataSource, getRowId, context, storageKey, rowHeight, headerHeight, floatingFilter, selectable, defaultPageSize, pageSizeOptions, onRowCommit, onSelectionChanged, onRowFilesDropped, onError, toolbar, emptyMessage, exportFileName, className, height, apiRef, }: DataGridProps<T, C>): react.JSX.Element;
+
+interface GridPaginationProps {
+    page: number;
+    pageSize: number;
+    totalRows: number;
+    pageSizeOptions: number[];
+    isLoading: boolean;
+    onPageChange: (page: number) => void;
+    onPageSizeChange: (pageSize: number) => void;
+}
+declare function GridPagination({ page, pageSize, totalRows, pageSizeOptions, isLoading, onPageChange, onPageSizeChange, }: GridPaginationProps): react.JSX.Element;
+
+interface GridOverlayProps {
+    kind: 'loading' | 'empty' | 'error';
+    message?: ReactNode;
+}
+/**
+ * Sits over the row area rather than replacing it, so the header and column
+ * widths stay put while a refetch is in flight.
+ */
+declare function GridOverlay({ kind, message }: GridOverlayProps): react.JSX.Element;
+
+interface ColumnsPanelProps<T, C> {
+    columns: ResolvedColumn<T, C>[];
+    isHidden: (colId: string) => boolean;
+    onToggle: (colId: string, hidden: boolean) => void;
+    onMove: (colId: string, toIndex: number) => void;
+    onPin: (colId: string, pinned: Pinned | undefined) => void;
+    onReset: () => void;
+    onClose: () => void;
+}
+/** Show/hide, reorder and pin, plus the "reset my preferences" escape hatch. */
+declare function ColumnsPanel<T, C>({ columns, isHidden, onToggle, onMove, onPin, onReset, onClose, }: ColumnsPanelProps<T, C>): react.JSX.Element;
+
+interface FilterPopoverProps {
+    kind: FilterKind;
+    value: HxFilterModel | undefined;
+    setValues?: string[] | (() => Promise<string[]>);
+    onApply: (filter: HxFilterModel | null) => void;
+    onClose: () => void;
+}
+/** Header filter menu. Emits the wire-format model directly. */
+declare function FilterPopover({ kind, value, setValues, onApply, onClose, }: FilterPopoverProps): react.JSX.Element;
+
+declare function TextEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, column, }: EditorParams<T, C>): react.JSX.Element;
+declare function NumberEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, }: EditorParams<T, C>): react.JSX.Element;
+declare function DateEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, }: EditorParams<T, C>): react.JSX.Element;
+declare function SelectEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, column, }: EditorParams<T, C>): react.JSX.Element;
+declare function CheckboxEditor<T, C>({ value, onChange, onCommit, onCancel, autoFocus, }: EditorParams<T, C>): react.JSX.Element;
+
+/** Maps a `ColumnDef.editor` string to its component. */
+declare const BUILTIN_EDITORS: {
+    readonly text: typeof TextEditor;
+    readonly number: typeof NumberEditor;
+    readonly date: typeof DateEditor;
+    readonly select: typeof SelectEditor;
+    readonly checkbox: typeof CheckboxEditor;
+};
+
+interface UseGridStateResult {
+    /** Read once on mount; never re-read, so it is safe as an initial value. */
+    initial: PersistedGridState | undefined;
+    saveColumns: (columns: PersistedGridState['columns']) => void;
+    saveSort: (sort: SortModelItem[]) => void;
+    saveFilters: (filters: FilterModelMap) => void;
+    savePageSize: (pageSize: number) => void;
+    clear: () => void;
+    hasSavedState: boolean;
+}
+/** Versioned, lean localStorage persistence for one grid. */
+declare function useGridState(storageKey: string | undefined): UseGridStateResult;
+
+interface UseServerDataSourceOptions<T> {
+    dataSource: HxDataSource<T>;
+    pageSize: number;
+    page: number;
+    sortModel: SortModelItem[];
+    filterModel: FilterModelMap;
+    /** Blocks to keep around so paging back and forth does not refetch. */
+    maxCachedBlocks?: number;
+    onError?: (error: unknown) => void;
+}
+interface UseServerDataSourceResult<T> {
+    rows: T[];
+    totalRows: number;
+    isLoading: boolean;
+    error: unknown;
+    refresh: (options?: {
+        purge?: boolean;
+    }) => void;
+    /** Patch loaded rows in place, keyed by the grid's row id. */
+    patchRows: (rows: T[], getRowId: (row: T) => string | number) => void;
+}
+/**
+ * Server-side paging with a small block cache.
+ *
+ * Two things here that the ag-grid screen this replaces did not do: every
+ * request carries an AbortController and a sequence number, so a slow response
+ * for an old sort/filter can never overwrite a newer one; and the cache is
+ * dropped wholesale when the query changes, so stale blocks are never mixed
+ * with fresh ones.
+ */
+declare function useServerDataSource<T>({ dataSource, pageSize, page, sortModel, filterModel, maxCachedBlocks, onError, }: UseServerDataSourceOptions<T>): UseServerDataSourceResult<T>;
+
+interface VirtualWindow {
+    startIndex: number;
+    endIndex: number;
+}
+interface UseVirtualRowsOptions {
+    rowCount: number;
+    rowHeight: number;
+    overscan?: number;
+}
+interface UseVirtualRowsResult {
+    window: VirtualWindow;
+    totalHeight: number;
+    /** Attach to the scrolling element. */
+    onScroll: (event: {
+        currentTarget: HTMLElement;
+    }) => void;
+    /** Call when the viewport is measured or resized. */
+    setViewportHeight: (height: number) => void;
+    scrollTopRef: React.RefObject<number>;
+}
+/**
+ * Fixed-height row windowing.
+ *
+ * Fixed heights are a deliberate constraint: they make the visible range O(1)
+ * to compute and remove the measure-then-reflow pass that variable heights
+ * force. Scroll position is tracked in a ref and only promoted to state when
+ * the computed window actually changes, so scrolling within a row does not
+ * re-render anything.
+ */
+declare function useVirtualRows({ rowCount, rowHeight, overscan, }: UseVirtualRowsOptions): UseVirtualRowsResult;
+
+interface ColumnStateValue {
+    order: string[];
+    hidden: string[];
+    widths: Record<string, number>;
+    pinned: Record<string, Pinned>;
+}
+interface UseColumnStateResult<T, C> {
+    /** Every column, in user order, including hidden ones (for the columns panel). */
+    allColumns: ResolvedColumn<T, C>[];
+    visibleColumns: ResolvedColumn<T, C>[];
+    layout: ColumnLayout<T, C>;
+    state: ColumnStateValue;
+    isHidden: (colId: string) => boolean;
+    setHidden: (colId: string, hidden: boolean) => void;
+    setWidth: (colId: string, width: number) => void;
+    setPinned: (colId: string, pinned: Pinned | undefined) => void;
+    moveColumn: (colId: string, toIndex: number) => void;
+    reset: () => void;
+}
+declare function useColumnState<T, C>(columns: ColumnDef<T, C>[], persisted: PersistedGridState['columns'] | undefined, onChange: (state: ColumnStateValue) => void, availableWidth: number): UseColumnStateResult<T, C>;
+
+interface EditState<T> {
+    rowId: RowId;
+    draft: T;
+    original: T;
+    errors: Record<string, string>;
+    isSaving: boolean;
+}
+interface UseEditModelResult<T> {
+    edit: EditState<T> | null;
+    isEditing: (rowId: RowId) => boolean;
+    start: (rowId: RowId, row: T) => void;
+    setField: (field: string, value: unknown) => void;
+    cancel: () => void;
+    commit: () => Promise<void>;
+}
+/**
+ * Row-level editing against a draft copy.
+ *
+ * The draft never touches the data source, and the editors never call an API --
+ * the single `onCommit` callback owns validation and persistence, so the app can
+ * plug in whatever schema library it uses without the grid knowing about it.
+ */
+declare function useEditModel<T>(onCommit: (draft: T, original: T) => Promise<RowCommitResult> | RowCommitResult): UseEditModelResult<T>;
+
+/**
+ * Resolves a cell value.
+ *
+ * Servers that flatten joined relations hand back `{"customer.businessName": x}`
+ * rather than a nested object -- and some flatten with a different prefix when
+ * grouping is on. So: explicit getter, then the dotted path, then the literal
+ * flat key, then any declared aliases.
+ */
+declare function resolveValue<T>(row: T, column: ColumnDef<T, never>): unknown;
+/** The display string for a cell, independent of any custom renderer. */
+declare function formatValue<T>(value: unknown, row: T, column: ColumnDef<T, never>): string;
+/** The string written to CSV / clipboard for a cell. */
+declare function exportValue<T>(row: T, column: ColumnDef<T, never>): string;
+/** Plain-text header, for exports and aria labels. */
+declare function headerText<T>(column: ColumnDef<T, never>): string;
+declare function columnId<T, C>(column: ColumnDef<T, C>): string;
+/** Fills in the defaults every other module assumes are present. */
+declare function resolveColumn<T, C>(column: ColumnDef<T, C>): ResolvedColumn<T, C>;
+declare function isEditable<T, C>(column: ColumnDef<T, C>, row: T): boolean;
+
+/**
+ * Every wire-format filter shape is built here, so the contract with the server
+ * is defined in exactly one place.
+ */
+declare const TEXT_FILTER_TYPES: TextFilterType[];
+declare const NUMBER_FILTER_TYPES: NumberFilterType[];
+declare const DATE_FILTER_TYPES: DateFilterType[];
+declare const FILTER_TYPE_LABELS: Record<string, string>;
+/** Filter types that need no operand. */
+declare function isUnaryFilter(type: string): boolean;
+declare function isRangeFilter(type: string): boolean;
+declare function defaultFilterType(kind: FilterKind): string;
+declare function buildTextFilter(type: TextFilterType, filter: string): HxFilterModel | null;
+declare function buildNumberFilter(type: NumberFilterType, filter: string, filterTo?: string): HxFilterModel | null;
+declare function buildDateFilter(type: DateFilterType, dateFrom: string, dateTo?: string): HxFilterModel | null;
+declare function buildSetFilter(values: string[]): HxFilterModel | null;
+/** Sets or clears one column's entry, returning a new map. */
+declare function withFilter(model: FilterModelMap, colId: string, filter: HxFilterModel | null): FilterModelMap;
+/** A short label for the floating filter / header indicator. */
+declare function describeFilter(filter: HxFilterModel): string;
+
+declare function toDelimited<T>(rows: T[], columns: Array<ResolvedColumn<T, never> | ColumnDef<T, never>>, separator: string): string;
+declare function toCsv<T>(rows: T[], columns: Array<ResolvedColumn<T, never> | ColumnDef<T, never>>, separator?: string): string;
+/** Tab-separated, which is what spreadsheets expect from the clipboard. */
+declare function toTsv<T>(rows: T[], columns: Array<ResolvedColumn<T, never> | ColumnDef<T, never>>): string;
+declare function downloadCsv(content: string, fileName: string): void;
+declare function copyToClipboard(text: string): Promise<void>;
+
+export { BUILTIN_EDITORS, type BuiltinEditor, type CellRendererParams, CheckboxEditor, type ColumnDef, type ColumnLayout, type ColumnLayoutItem, ColumnsPanel, DATE_FILTER_TYPES, DataGrid, type DataGridProps, DateEditor, type DateFilterModel, type DateFilterType, type EditorComponent, type EditorParams, type ExportCsvOptions, FILTER_TYPE_LABELS, type FilterKind, type FilterModelMap, FilterPopover, GRID_STATE_VERSION, type GridApi, GridOverlay, GridPagination, type HxDataSource, type HxFilterModel, type HxRowsRequest, type HxRowsResponse, NUMBER_FILTER_TYPES, NumberEditor, type NumberFilterModel, type NumberFilterType, type PersistedGridState, type Pinned, type ResolvedColumn, type RowCommitResult, type RowId, SelectEditor, type SelectOption, type SetFilterModel, type SortDirection, type SortModelItem, TEXT_FILTER_TYPES, TextEditor, type TextFilterModel, type TextFilterType, buildDateFilter, buildNumberFilter, buildSetFilter, buildTextFilter, columnId, copyToClipboard, defaultFilterType, describeFilter, downloadCsv, exportValue, formatValue, headerText, isEditable, isRangeFilter, isUnaryFilter, resolveColumn, resolveValue, toCsv, toDelimited, toTsv, useColumnState, useEditModel, useGridState, useSelectionModel, useServerDataSource, useVirtualRows, withFilter };