@svgrid/grid 1.0.0

package/dist/core.d.ts

@@ -0,0 +1,370 @@
+import type { SparklineConfig } from './sparkline';
+export type RowData = Record<string, unknown>;
+export type Updater<T> = T | ((prev: T) => T);
+export type SortingState = Array<{
+    id: string;
+    desc: boolean;
+}>;
+export type ColumnFilter = {
+    id: string;
+    value: unknown;
+    fn?: keyof typeof filterFns;
+};
+export type ColumnFiltersState = Array<ColumnFilter>;
+export type PaginationState = {
+    pageIndex: number;
+    pageSize: number;
+};
+export type GroupingState = Array<string>;
+export type ExpandedState = Record<string, boolean>;
+export type RowSelectionState = Record<string, boolean>;
+export type ActiveCellState = {
+    rowIndex: number;
+    colIndex: number;
+    cellId: string | null;
+};
+export type TableFeatures = Record<string, unknown>;
+export type CellData = unknown;
+export type HeaderContext<TData extends RowData> = {
+    header: Header<TData>;
+    column: Column<TData>;
+    table: SvGrid<TData>;
+};
+export type CellContext<TData extends RowData> = {
+    cell: Cell<TData>;
+    row: Row<TData>;
+    column: Column<TData>;
+    table: SvGrid<TData>;
+    getValue: () => unknown;
+};
+/**
+ * Context passed to a custom `cellEditor` snippet/component. Three write
+ * helpers cover the lifecycle:
+ *
+ *   - `update(next)`  - stage `next` as the draft, keep the editor open.
+ *                       Use this for live-preview controls (sliders,
+ *                       color pickers) so the user can keep adjusting.
+ *   - `commit(next?)` - write the value AND close the editor. The
+ *                       argument is optional; when omitted, the most
+ *                       recently `update()`d value is saved. Use this
+ *                       for "done" gestures (Enter, picking an option).
+ *   - `cancel()`      - discard the draft and close the editor.
+ */
+export type EditorContext<TData extends RowData> = CellContext<TData> & {
+    value: unknown;
+    update: (next: unknown) => void;
+    commit: (next?: unknown) => void;
+    cancel: () => void;
+};
+export type CellFormatConfig = {
+    type: 'number';
+    locales?: string | Array<string>;
+    options?: Intl.NumberFormatOptions;
+} | {
+    type: 'currency';
+    /** ISO 4217 (default USD) */
+    currency?: string;
+    locales?: string | Array<string>;
+    options?: Omit<Intl.NumberFormatOptions, 'style' | 'currency'>;
+} | {
+    type: 'percent';
+    locales?: string | Array<string>;
+    options?: Omit<Intl.NumberFormatOptions, 'style'>;
+    /**
+     * If true, numeric cell values are 0–100 (e.g. 42 → 42%) instead of Intl’s 0–1 fraction (0.42 → 42%).
+     * Default false.
+     */
+    valueIsPercentPoints?: boolean;
+} | {
+    type: 'date' | 'datetime';
+    locales?: string | Array<string>;
+    /**
+     * Shortcut patterns merged with `options`:
+     * `'d'` short numeric date, `'D'` long date, `'y-m-d'` yyyy/mm/dd-style,
+     * `'short'`|`'medium'`|`'long'` use dateStyle/timeStyle presets.
+     */
+    pattern?: string;
+    options?: Intl.DateTimeFormatOptions;
+};
+export type CellFormatter<TData extends RowData> = (context: {
+    value: unknown;
+    row: Row<TData>;
+    column: Column<TData>;
+    table: SvGrid<TData>;
+}) => string;
+export type ColumnDefTemplate<TContext> = string | ((context: TContext) => unknown);
+/**
+ * How a column's value is aggregated for a group row when `columnGrouping`
+ * is active. Built-in reducers cover the common cases; pass a function for
+ * anything custom (weighted average, median, percentile, distinct count).
+ * The function receives the finite numeric values AND the raw leaf rows.
+ */
+export type GroupAggregator<TData = any> = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct' | 'extent' | 'first' | ((values: number[], rows: Array<TData>) => unknown);
+/** Apply a group aggregator over a bucket's leaf rows for one column. */
+export declare function applyGroupAggregate<TData extends RowData>(agg: GroupAggregator<TData>, columnId: string, rows: ReadonlyArray<Row<TData>>): unknown;
+export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> = {
+    id?: string;
+    field?: keyof TData & string;
+    accessorFn?: (row: TData) => unknown;
+    header?: ColumnDefTemplate<HeaderContext<TData>>;
+    footer?: ColumnDefTemplate<HeaderContext<TData>>;
+    cell?: ColumnDefTemplate<CellContext<TData>>;
+    columns?: Array<ColumnDef<TFeatures, TData>>;
+    editorType?: 'text' | 'number' | 'date' | 'datetime' | 'time' | 'password' | 'checkbox' | 'list' | 'chips' | 'select' | 'rich-select' | 'textarea' | 'color' | 'rating';
+    /**
+     * Custom in-cell editor. Receives the cell context PLUS a `commit(value)`
+     * and `cancel()` helper. Use when none of the built-in `editorType`s fit;
+     * the snippet's outer element is mounted inside the editing cell and
+     * inherits keyboard handling (Esc cancels, Enter commits unless your
+     * snippet preventDefaults it).
+     *
+     * Coexists with `editorType`: when both are set, `cellEditor` wins and
+     * `editorType` is treated as a hint for parsing the saved value.
+     */
+    cellEditor?: ColumnDefTemplate<EditorContext<TData>>;
+    /**
+     * Per-column tooltip. String shows as a native `title=`; `(ctx) => string`
+     * runs per cell so the tooltip can reflect the value. Returning an empty
+     * string skips the tooltip.
+     */
+    tooltip?: string | ((ctx: CellContext<TData>) => string | null | undefined);
+    /**
+     * Gate editing per column or per cell.
+     *
+     *   - `true` (or omitted): the column is fully editable.
+     *   - `false`: the column is read-only - double-click, type-to-edit,
+     *     fill-handle drag, Delete, and clipboard paste all skip it.
+     *   - `(ctx) => boolean`: evaluated for each cell, so you can lock
+     *     individual rows (e.g. by role, status, ownership). Returning
+     *     `false` opts the cell out of every editing path, identical to
+     *     setting `editable: false` on the whole column for that row.
+     *
+     * The grid-wide `enableInlineEditing` prop still wins when set to
+     * `false`.
+     */
+    editable?: boolean | ((context: CellContext<TData>) => boolean);
+    /**
+     * When `false`, this column never shows a sort indicator and clicking
+     * its header is a no-op - `api.setSort(thisColumn, ...)` is also
+     * ignored. Defaults to `true` (the column participates in sorting as
+     * long as `rowSortingFeature` is registered).
+     */
+    sortable?: boolean;
+    /**
+     * When `false`, this column never shows a filter funnel / menu and
+     * `api.setFilter(thisColumn, ...)` is ignored. Defaults to `true` (the
+     * column is filterable as long as `columnFilteringFeature` is
+     * registered).
+     */
+    filterable?: boolean;
+    /**
+     * Options for `editorType: 'list' | 'chips'`. Either bare values (the
+     * string is both value and label) or `{ value, label }` objects.
+     * For `chips` this is optional - when omitted, the chips editor becomes
+     * free-form (user types and presses Enter to commit a chip).
+     *
+     * Pass a function `(row) => options` for row-dependent (cascading)
+     * options - e.g. City options that depend on Country in the same row.
+     */
+    editorOptions?: ReadonlyArray<string | number | {
+        value: string | number;
+        label?: string;
+        color?: string;
+    }> | ((row: TData) => ReadonlyArray<string | number | {
+        value: string | number;
+        label?: string;
+        color?: string;
+    }>);
+    /** When true, list/chips allow multiple selections. Cell value becomes an array. */
+    editorMultiple?: boolean;
+    /** Separator used when joining array values for the readonly cell display. Defaults to ', '. */
+    editorSeparator?: string;
+    format?: CellFormatConfig;
+    formatter?: CellFormatter<TData>;
+    /**
+     * Aggregate this column's values into the group row when grouping is
+     * active. `'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct' |
+     * 'extent' | 'first'`, or a custom `(values, rows) => unknown`. The result
+     * is formatted with this column's `format` and shown in the group header.
+     */
+    aggregate?: GroupAggregator<TData>;
+    /**
+     * Render the cell as an in-cell sparkline chart. The cell value should be
+     * an array of numbers (or a comma/space separated string). Mutually
+     * exclusive with a custom `cell` renderer (a `cell` wins if both are set).
+     *
+     *   { sparkline: { type: 'line' } }                 // default line
+     *   { sparkline: { type: 'bar', color: '#16a34a' } }
+     *   { sparkline: { type: 'winloss' } }              // sign-only up/down
+     *
+     * See `SparklineConfig` for the full option set (type, color,
+     * negativeColor, width, height, fixed min/max).
+     */
+    sparkline?: SparklineConfig;
+    /** Initial column width in pixels. Falls back to the grid's `columnWidth` prop. */
+    width?: number;
+    /**
+     * Horizontal alignment for header and body cells. When omitted, the
+     * default is inferred from `editorType`:
+     *   - `'number' | 'date' | 'datetime'` → `'right'`
+     *   - `'checkbox'`                     → `'center'`
+     *   - everything else                  → `'left'`
+     */
+    align?: 'left' | 'center' | 'right';
+    /**
+     * Per-cell conditional CSS. Two shapes:
+     *
+     *   - **String** (or array of strings): class name(s) added to the
+     *     cell's `<td>` for every row in this column.
+     *   - **Function**: invoked per cell with the same `CellContext` shape
+     *     the `cell` renderer receives. Return a string, an array of
+     *     strings, or an object mapping class names to booleans.
+     *
+     * Use it for status tinting, conditional bold, "negative number"
+     * coloring - anything that's a function of the row's value. Cells
+     * still receive their format / cell renderer; the class just
+     * augments the rendered `<td>`.
+     */
+    cellClass?: string | ReadonlyArray<string> | ((ctx: CellContext<TData>) => string | ReadonlyArray<string> | Record<string, boolean> | undefined | null);
+};
+export type Column<TData extends RowData> = {
+    id: string;
+    columnDef: ColumnDef<any, TData>;
+    depth: number;
+    parentId?: string;
+    getCanSort: () => boolean;
+    getCanFilter: () => boolean;
+    getIsSorted: () => false | 'asc' | 'desc';
+    getToggleSortingHandler: () => () => void;
+};
+export type Header<TData extends RowData> = {
+    id: string;
+    isPlaceholder: boolean;
+    colSpan: number;
+    column: Column<TData>;
+    getContext: () => HeaderContext<TData>;
+};
+export type HeaderGroup<TData extends RowData> = {
+    id: string;
+    headers: Array<Header<TData>>;
+};
+export type Cell<TData extends RowData> = {
+    id: string;
+    row: Row<TData>;
+    column: Column<TData>;
+    getValue: () => unknown;
+    getContext: () => CellContext<TData>;
+};
+export type Row<TData extends RowData> = {
+    id: string;
+    index: number;
+    original: TData;
+    depth: number;
+    subRows?: Array<Row<TData>>;
+    /** Total leaf (data) rows under this group row. Undefined for data rows. */
+    leafCount?: number;
+    getCanExpand: () => boolean;
+    getIsExpanded: () => boolean;
+    toggleExpanded: () => void;
+    getIsSelected: () => boolean;
+    toggleSelected: () => void;
+    getAllCells: () => Array<Cell<TData>>;
+    getCellValueByColumnId: (columnId: string) => unknown;
+};
+export type RowModel<TData extends RowData> = {
+    rows: Array<Row<TData>>;
+};
+export type Store<T> = {
+    readonly state: T;
+    setState: (updater: (prev: T) => T) => void;
+    subscribe: (listener: () => void) => () => void;
+};
+export declare const rowSortingFeature: {
+    key: string;
+};
+export declare const columnFilteringFeature: {
+    key: string;
+};
+export declare const rowPaginationFeature: {
+    key: string;
+};
+export declare const columnGroupingFeature: {
+    key: string;
+};
+export declare const rowSelectionFeature: {
+    key: string;
+};
+export declare const rowExpandingFeature: {
+    key: string;
+};
+export declare function tableFeatures<T extends TableFeatures>(features: T): T;
+export declare const sortFns: {
+    auto: (a: unknown, b: unknown) => number;
+    number: (a: unknown, b: unknown) => number;
+    date: (a: unknown, b: unknown) => number;
+};
+export declare const filterFns: {
+    includesString: (value: unknown, query: string) => boolean;
+    equals: (value: unknown, query: unknown) => boolean;
+};
+export type RowModelFactory<TData extends RowData> = (args: {
+    table: SvGrid<TData>;
+    rows: Array<Row<TData>>;
+}) => Array<Row<TData>>;
+export declare function createCoreRowModel<TData extends RowData>(): RowModelFactory<TData>;
+export declare function createFilteredRowModel<TData extends RowData>(): RowModelFactory<TData>;
+export declare function createPaginatedRowModel<TData extends RowData>(): RowModelFactory<TData>;
+export declare function createGroupedRowModel<TData extends RowData>(): RowModelFactory<TData>;
+export declare function createExpandedRowModel<TData extends RowData>(): RowModelFactory<TData>;
+export declare function createSortedRowModel<TData extends RowData>(localSortFns?: typeof sortFns): RowModelFactory<TData>;
+export type SvGridOptions<TFeatures extends TableFeatures, TData extends RowData> = {
+    _features: TFeatures;
+    _rowModels?: {
+        coreRowModel?: RowModelFactory<TData>;
+        filteredRowModel?: RowModelFactory<TData>;
+        sortedRowModel?: RowModelFactory<TData>;
+        paginatedRowModel?: RowModelFactory<TData>;
+        groupedRowModel?: RowModelFactory<TData>;
+        expandedRowModel?: RowModelFactory<TData>;
+    };
+    columns: Array<ColumnDef<TFeatures, TData>>;
+    data: ReadonlyArray<TData>;
+    /**
+     * Optional row-id resolver. When set, the value it returns becomes
+     * `row.id` (and therefore the selection / expansion / edit key). When
+     * omitted, ids fall back to the row's array index as a string. Use a
+     * stable id (database PK, UUID, etc.) so selection survives reorders.
+     */
+    getRowId?: (row: TData, index: number) => string;
+    state?: Partial<Record<string, any>>;
+    onSortingChange?: (updater: Updater<SortingState>) => void;
+    onColumnFiltersChange?: (updater: Updater<ColumnFiltersState>) => void;
+    onPaginationChange?: (updater: Updater<PaginationState>) => void;
+    onGroupingChange?: (updater: Updater<GroupingState>) => void;
+    onExpandedChange?: (updater: Updater<ExpandedState>) => void;
+    onRowSelectionChange?: (updater: Updater<RowSelectionState>) => void;
+    onActiveCellChange?: (updater: Updater<ActiveCellState>) => void;
+};
+export type SvGrid<TData extends RowData> = {
+    store: Store<Record<string, any>>;
+    optionsStore: Store<Record<string, any>>;
+    state: Record<string, any>;
+    getState: () => Record<string, any>;
+    setOptions: (updater: Updater<Record<string, any>>) => void;
+    setColumnFilters: (updater: Updater<ColumnFiltersState>) => void;
+    setPagination: (updater: Updater<PaginationState>) => void;
+    setGrouping: (updater: Updater<GroupingState>) => void;
+    setExpanded: (updater: Updater<ExpandedState>) => void;
+    setRowSelection: (updater: Updater<RowSelectionState>) => void;
+    setActiveCell: (updater: Updater<ActiveCellState>) => void;
+    moveActiveCell: (next: {
+        rowDelta?: number;
+        colDelta?: number;
+    }) => void;
+    getAllColumns: () => Array<Column<TData>>;
+    getHeaderGroups: () => Array<HeaderGroup<TData>>;
+    getFooterGroups: () => Array<HeaderGroup<TData>>;
+    getRowModel: () => RowModel<TData>;
+};
+export declare function createSvGridCore<TFeatures extends TableFeatures, TData extends RowData>(options: SvGridOptions<TFeatures, TData>): SvGrid<TData>;
+export declare function isFunction(value: unknown): value is (...args: Array<any>) => any;