@freegridjs/core 0.8.0 → 1.0.0

package/dist/{types-e45suTSB.d.ts → types-D9gm8TyF.d.ts}

@@ -1,3 +1,37 @@
+/** A cell value, optionally with an Excel number format and text styles. Colors are ARGB hex like 'FFDC2626'. */
+type XlsxValue = string | number | boolean | Date | null | undefined;
+interface XlsxStyle {
+    fmt?: string;
+    bold?: boolean;
+    align?: 'left' | 'center' | 'right';
+    color?: string;
+    fill?: string;
+    /** Header look: bold on a light gray fill. */
+    header?: boolean;
+}
+type XlsxCell = XlsxValue | ({
+    v: XlsxValue;
+} & XlsxStyle);
+interface XlsxSheet {
+    name?: string;
+    rows: XlsxCell[][];
+    /** Column widths in characters. */
+    widths?: number[];
+    /** Ranges like "A1:C1". */
+    merges?: string[];
+    /** Rows frozen at the top (also the AutoFilter row when `autoFilter` is set). */
+    freezeRows?: number;
+    autoFilter?: boolean;
+}
+/** Build an .xlsx workbook (stored zip) from rows of values. */
+declare function writeXlsx(sheets: XlsxSheet[]): Uint8Array;
+interface ReadSheet {
+    name: string;
+    rows: XlsxValue[][];
+}
+/** Read every sheet of an .xlsx file. Dates come back as Date, numbers as number, booleans as boolean. */
+declare function readXlsx(input: ArrayBuffer | Uint8Array): Promise<ReadSheet[]>;
+
 type Row = Record<string, any>;
 type Region = 'left' | 'center' | 'right';
 type ColumnType = 'text' | 'number' | 'date' | 'boolean';
@@ -30,7 +64,23 @@ interface SetFilterModel {
     type: 'set';
     values: unknown[];
 }
-type FilterModel = TextFilterModel | NumberFilterModel | DateFilterModel | SetFilterModel;
+/** Two or more conditions on the same column, joined with and / or. */
+interface CombinedFilterModel {
+    type: 'combined';
+    operator: 'and' | 'or';
+    conditions: FilterModel[];
+}
+type FilterModel = TextFilterModel | NumberFilterModel | DateFilterModel | SetFilterModel | CombinedFilterModel;
+/** A condition on one column inside an advanced filter. */
+interface AdvancedFilterCondition {
+    colId: string;
+    model: FilterModel;
+}
+/** Conditions across columns, nested as deep as needed: (a AND b) OR c. */
+interface AdvancedFilter {
+    operator: 'and' | 'or';
+    conditions: Array<AdvancedFilterCondition | AdvancedFilter>;
+}
 interface SortItem {
     colId: string;
     dir: SortDir;
@@ -111,6 +161,19 @@ interface ColumnDef {
         header: string;
         column: ColumnDef;
     }) => string | HTMLElement;
+    /** Text shown when hovering the header. */
+    headerTooltip?: string;
+    /** Hover text for cells: true shows the value; a function returns the text (or null for none). */
+    tooltip?: boolean | ((params: CellParams) => string | null | undefined);
+    /** The cell value is an array of numbers drawn as a small chart: true = line, or { type: 'line' | 'bar' | 'area', color? }. */
+    sparkline?: boolean | {
+        type?: 'line' | 'bar' | 'area';
+        color?: string;
+    };
+    /** Column groups: start opened (see columnGroupShow). */
+    openByDefault?: boolean;
+    /** Inside a group: show this column only while the group is 'open' or only while it is 'closed'. The group header gets a toggle. */
+    columnGroupShow?: 'open' | 'closed';
     /** Extra class names on the header cell (also for column groups). */
     headerClass?: string | ((column: ColumnDef) => string | undefined);
     /** Aggregate shown in group rows: 'sum' | 'avg' | 'min' | 'max' | 'count' | (values, rows) => value. */
@@ -123,6 +186,42 @@ interface InvalidCell {
     colId: string;
     message: string;
 }
+/** Everything a person can change in the grid, as plain JSON (save it per user, restore it later). */
+interface SavedGridState {
+    columns?: ColumnState[];
+    sort?: SortItem[];
+    filters?: Record<string, FilterModel>;
+    quickFilter?: string;
+    groupBy?: string[];
+    pivot?: PivotConfig | null;
+    advancedFilter?: AdvancedFilter | null;
+    /** Opened (true) or closed column groups, by group id. */
+    columnGroups?: Record<string, boolean>;
+    /** Expanded or collapsed groups and tree rows, by key. */
+    expanded?: Record<string, boolean>;
+    page?: number;
+    pageSize?: number;
+    /** Selected row ids (needs getRowId to survive reloads). */
+    selected?: string[];
+}
+type SavedStatePart = keyof SavedGridState;
+/** Row changes from outside (a server push, a websocket): matched by getRowId, not undoable, not tracked as edits. */
+interface RowTransaction {
+    add?: Row[];
+    /** Where to insert added rows in the source data (default: the end). */
+    addIndex?: number;
+    /** Rows with the id of an existing row; their fields are copied onto it. */
+    update?: Row[];
+    /** Rows (or objects with the id fields) to take out. */
+    remove?: Row[];
+}
+interface TransactionResult {
+    added: Row[];
+    updated: Row[];
+    removed: Row[];
+    /** Update or remove entries whose id matched no row. */
+    notFound: Row[];
+}
 interface ScrollPosition {
     top: number;
     left: number;
@@ -175,7 +274,7 @@ type EditorSpec = {
  | {
     type: 'datetime';
 } | ((params: EditorParams) => CustomEditor);
-type KeyAction = 'edit' | 'clear' | 'undo' | 'redo' | 'copy' | 'paste' | 'selectAll' | 'find' | 'none';
+type KeyAction = 'edit' | 'clear' | 'undo' | 'redo' | 'copy' | 'cut' | 'paste' | 'selectAll' | 'find' | 'none';
 interface ColumnState {
     colId: string;
     width: number;
@@ -210,10 +309,15 @@ interface Messages {
     close: string;
     copy: string;
     copyWithHeaders: string;
+    cut: string;
     paste: string;
     pasteHint: string;
     required: string;
     invalidValue: string;
+    and: string;
+    or: string;
+    advancedFilter: string;
+    addCondition: string;
     duplicate: string;
     undo: string;
     redo: string;
@@ -258,6 +362,9 @@ interface Messages {
     addColumn: string;
     chartBar: string;
     chartStacked: string;
+    chartDonut: string;
+    chartCombo: string;
+    chartScatter: string;
     chartLine: string;
     chartArea: string;
     chartPie: string;
@@ -322,6 +429,15 @@ interface ServerParams {
     sort: SortItem[];
     filters: Record<string, FilterModel>;
     quickFilter: string;
+    /** setAdvancedFilter, when set. */
+    advancedFilter?: AdvancedFilter | null;
+    /**
+     * Server-side grouping (groupBy with a datasource): the grouped columns, and the values of the open
+     * groups above this request. While groupKeys.length < groupBy.length, answer one row per group of
+     * groupBy[groupKeys.length], e.g. { status: 'new', count: 12, qty: 340 } (count and aggregates by column id).
+     */
+    groupBy?: string[];
+    groupKeys?: unknown[];
 }
 interface Datasource {
     /** Return the rows of the range; `total` is the row count when known (omit it for infinite scroll). */
@@ -357,7 +473,7 @@ interface PivotConfig {
     totals?: boolean;
 }
 interface ChartOptions {
-    type?: 'bar' | 'stackedBar' | 'line' | 'area' | 'pie';
+    type?: 'bar' | 'stackedBar' | 'line' | 'area' | 'pie' | 'donut' | 'combo' | 'scatter';
     /** Cells to chart; default: the current range, else every displayed row. */
     range?: GridRange;
     /** Draw into this element instead of a floating panel inside the grid. */
@@ -367,7 +483,7 @@ interface ChartOptions {
 interface ChartHandle {
     /** Element the SVG is drawn in. */
     el: HTMLElement;
-    setType(type: 'bar' | 'stackedBar' | 'line' | 'area' | 'pie'): void;
+    setType(type: 'bar' | 'stackedBar' | 'line' | 'area' | 'pie' | 'donut' | 'combo' | 'scatter'): void;
     update(): void;
     destroy(): void;
 }
@@ -433,6 +549,35 @@ interface GridOptions {
     detailHeight?: number;
     /** Which rows can expand a detail panel (default: all rows). */
     isRowMaster?: (row: Row) => boolean;
+    /** 'row': editing a row keeps it open across its cells (Tab stays in the row); Enter or leaving the row saves it, Escape puts the whole row back. */
+    editType?: 'cell' | 'row';
+    /** Briefly highlight cells whose value changed through applyTransaction (default true). */
+    flashCells?: boolean;
+    /** Row spacing: 'compact', 'normal' (default) or 'comfortable'. Fixed rowHeight / headerHeight win. */
+    density?: 'compact' | 'normal' | 'comfortable';
+    /** Shown when there are no rows: text, or a function returning text or an element (filtered: the filters hide every row). */
+    noRowsOverlay?: string | ((params: {
+        filtered: boolean;
+    }) => string | HTMLElement);
+    /** Shown while server rows load. */
+    loadingOverlay?: string | ((params: {
+        filtered: boolean;
+    }) => string | HTMLElement);
+    /** The grid grows with its rows instead of scrolling inside (no height needed on the container). Best for up to a few hundred rows. */
+    autoHeight?: boolean;
+    /** Height in px for this row; return nothing for the default rowHeight. */
+    getRowHeight?: (row: Row) => number | null | undefined;
+    /** false hides "Advanced filter…" in the right-click menu (setAdvancedFilter still works). */
+    advancedFilter?: boolean;
+    /** Show the full text of cells that are cut off when hovered (default true). */
+    overflowTooltip?: boolean;
+    /** Boxes under the header that filter as you type: text contains; numbers >10, <=5, 10~20; dates >2026-01-01; a list for set columns. */
+    filterRow?: boolean;
+    /** A pinned column numbering the data rows 1, 2, 3… (continues across pages). Click a number to select the row. */
+    rowNumbers?: boolean | {
+        width?: number;
+        header?: string;
+    };
     /** Add a handle column for dragging rows into a new order (and between grids with the same `group`). */
     rowDrag?: boolean | RowDragOptions;
     /** Show rows as cards (header: value lines) when the grid is narrower than this many px; true = 640. */
@@ -443,6 +588,8 @@ interface GridOptions {
     autoRowHeight?: boolean;
     /** Rows that may be checked; others show a disabled checkbox and are skipped by select-all. */
     isRowSelectable?: (row: Row) => boolean;
+    /** Tree data: checking a parent row also checks (or unchecks) all of its children. Group rows always do. */
+    groupSelectsChildren?: boolean;
     /** Show the select-all checkbox in the header (default true). */
     headerCheckbox?: boolean;
     /** Show rows one page at a time with a pager under the grid. */
@@ -551,6 +698,32 @@ interface GridEvents {
     };
     /** The rows area scrolled (also from setScrollPosition). */
     scroll: ScrollPosition;
+    /** editType 'row': a row started or finished editing; `changes` lists the cells that differ from before. */
+    rowEditStart: {
+        row: Row;
+        rowIndex: number;
+    };
+    rowEditStop: {
+        row: Row;
+        rowIndex: number;
+        committed: boolean;
+        changes: {
+            colId: string;
+            oldValue: unknown;
+            newValue: unknown;
+        }[];
+    };
+    /** setAdvancedFilter or the filter builder changed the advanced filter. */
+    advancedFilterChange: {
+        advancedFilter: AdvancedFilter | null;
+    };
+    /** A collapsible column group was opened or closed. */
+    columnGroupOpened: {
+        groupId: string;
+        open: boolean;
+    };
+    /** applyTransaction (or a batch of applyTransactionAsync) finished. */
+    transactionApplied: TransactionResult;
     /** A row was dropped on this grid (also from another grid of the same drag group). */
     rowDrop: RowDropParams & {
         fromGrid: GridApi | null;
@@ -620,7 +793,10 @@ interface GridApi {
     getData(): Row[];
     setColumns(columns: ColumnDef[]): void;
     getColumnState(): ColumnState[];
-    applyColumnState(state: ColumnState[]): void;
+    /** Entries may be partial: only the fields given change. */
+    applyColumnState(state: (Partial<ColumnState> & {
+        colId: string;
+    })[]): void;
     setSort(sort: SortItem[]): void;
     getSort(): SortItem[];
     setFilter(colId: string, model: FilterModel | null): void;
@@ -631,6 +807,38 @@ interface GridApi {
     deselectAll(): void;
     getDisplayedRowCount(): number;
     scrollToRow(index: number): void;
+    /** The grid's current view (columns, sort, filters, grouping, page, selection…) as plain JSON. */
+    getState(): SavedGridState;
+    /** Restore a saved view; `parts` limits what is applied. Unknown columns are skipped. */
+    setState(state: SavedGridState, options?: {
+        parts?: SavedStatePart[];
+    }): void;
+    /** Add, update and remove rows by id in one go (for live data). Changed cells flash unless flashCells is false. */
+    applyTransaction(tx: RowTransaction): TransactionResult;
+    /** Queue a transaction; queued ones are merged and applied together about every 50 ms. */
+    applyTransactionAsync(tx: RowTransaction): void;
+    /** Conditions across columns, applied together with the column filters; null clears it. */
+    setAdvancedFilter(filter: AdvancedFilter | null): void;
+    getAdvancedFilter(): AdvancedFilter | null;
+    /** Dialog for building an advanced filter. */
+    openFilterBuilder(): void;
+    /** Open or close a column group that has columnGroupShow children. */
+    setColumnGroupOpened(groupId: string, open: boolean): void;
+    isColumnGroupOpened(groupId: string): boolean;
+    /** One worksheet of the rows, for buildWorkbook / exportWorkbook. */
+    getXlsxSheet(options?: ExportOptions): XlsxSheet;
+    setDensity(density: 'compact' | 'normal' | 'comfortable'): void;
+    getDensity(): 'compact' | 'normal' | 'comfortable';
+    /** Show the 'loading' or 'noRows' overlay yourself (for example while your own request runs); null goes back to automatic. */
+    showOverlay(kind: 'loading' | 'noRows' | null): void;
+    /** Print the rows as a table (current sort and filters; same options as the exports, plus a title). */
+    print(options?: ExportOptions & {
+        title?: string;
+    }): void;
+    /** The HTML page print() would print. */
+    getPrintHtml(options?: ExportOptions & {
+        title?: string;
+    }): string;
     /** Check every editable cell against required, unique and validate. Empty when all rows are valid. */
     validate(): InvalidCell[];
     /** Scroll offsets of the rows area in px. */
@@ -664,6 +872,10 @@ interface GridApi {
         headers?: boolean;
         rows?: boolean;
     }): string;
+    /** Copy the range like copySelection, then clear its editable cells (one undo step). */
+    cutSelection(): string;
+    /** editType 'row': finish the row being edited (cancel puts it back). */
+    stopRowEdit(cancel?: boolean): void;
     /** Paste Excel/TSV text at the range or focused cell into editable columns. */
     pasteText(text: string): {
         changed: number;
@@ -746,4 +958,4 @@ interface GridApi {
     destroy(): void;
 }
 
-export type { Aggregator as A, SortDir as B, CellEvent as C, Datasource as D, EditorParams as E, FilterModel as F, GridOptions as G, SortItem as H, InvalidCell as I, SpanParams as J, KeyAction as K, LocalePack as L, Messages as M, NumberFilterModel as N, SummaryCell as O, PivotConfig as P, SummaryOptions as Q, Region as R, ScrollPosition as S, SummaryRowDef as T, TextFilterModel as U, TextOp as V, GridApi as a, CellParams as b, ChartHandle as c, ChartOptions as d, ColumnDef as e, ColumnState as f, ColumnType as g, ContextMenuItem as h, ContextMenuParams as i, CustomEditor as j, DateFilterModel as k, DateOp as l, EditorSpec as m, ExportOptions as n, FilterOp as o, FilterType as p, GridEvents as q, GridRange as r, NumberOp as s, Row as t, RowDragOptions as u, RowDropParams as v, RowDropPosition as w, SelectOption as x, ServerParams as y, SetFilterModel as z };
+export { type TextOp as $, type AdvancedFilter as A, type RowTransaction as B, type CellEvent as C, type Datasource as D, type ExportOptions as E, type FilterModel as F, type GridOptions as G, type SavedStatePart as H, type InvalidCell as I, type ScrollPosition as J, type KeyAction as K, type LocalePack as L, type Messages as M, type NumberFilterModel as N, type SelectOption as O, type PivotConfig as P, type ServerParams as Q, type Row as R, type SavedGridState as S, type SetFilterModel as T, type SortDir as U, type SortItem as V, type SpanParams as W, type SummaryCell as X, type SummaryOptions as Y, type SummaryRowDef as Z, type TextFilterModel as _, type GridApi as a, type TransactionResult as a0, type XlsxCell as a1, type XlsxSheet as a2, readXlsx as a3, writeXlsx as a4, type AdvancedFilterCondition as b, type Aggregator as c, type CellParams as d, type ChartHandle as e, type ChartOptions as f, type ColumnDef as g, type ColumnState as h, type ColumnType as i, type CombinedFilterModel as j, type ContextMenuItem as k, type ContextMenuParams as l, type CustomEditor as m, type DateFilterModel as n, type DateOp as o, type EditorParams as p, type EditorSpec as q, type FilterOp as r, type FilterType as s, type GridEvents as t, type GridRange as u, type NumberOp as v, type Region as w, type RowDragOptions as x, type RowDropParams as y, type RowDropPosition as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freegridjs/core",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "FreeGrid — a fast data grid for the web (free for personal use): virtual scrolling, grouping, pivot, charts, Excel export, 7 languages.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",