@freegridjs/core 0.1.0 → 0.7.0

package/dist/types-DZ66BpLd.d.ts

@@ -0,0 +1,603 @@
+type Row = Record<string, any>;
+type Region = 'left' | 'center' | 'right';
+type ColumnType = 'text' | 'number' | 'date' | 'boolean';
+type FilterType = 'text' | 'number' | 'date' | 'set';
+type SortDir = 'asc' | 'desc';
+type TextOp = 'contains' | 'equals' | 'notEquals' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank';
+type NumberOp = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'between' | 'blank' | 'notBlank';
+type DateOp = 'equals' | 'before' | 'after' | 'between' | 'blank' | 'notBlank';
+type FilterOp = TextOp | NumberOp | DateOp;
+interface TextFilterModel {
+    type: 'text';
+    op: TextOp;
+    value?: string;
+}
+interface NumberFilterModel {
+    type: 'number';
+    op: NumberOp;
+    value?: number;
+    valueTo?: number;
+}
+/** Dates are compared as local `YYYY-MM-DD` keys. */
+interface DateFilterModel {
+    type: 'date';
+    op: DateOp;
+    value?: string;
+    valueTo?: string;
+}
+/** Rows pass when their value is one of `values`. */
+interface SetFilterModel {
+    type: 'set';
+    values: unknown[];
+}
+type FilterModel = TextFilterModel | NumberFilterModel | DateFilterModel | SetFilterModel;
+interface SortItem {
+    colId: string;
+    dir: SortDir;
+}
+interface CellParams {
+    value: unknown;
+    formatted: string;
+    row: Row;
+    rowIndex: number;
+    column: ColumnDef;
+}
+interface ColumnDef {
+    /** Column id; defaults to `field`. Required when `field` is absent. */
+    id?: string;
+    field?: string;
+    header?: string;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    /** Share leftover width proportionally. A user resize turns it into a fixed width. */
+    flex?: number;
+    pinned?: 'left' | 'right';
+    hide?: boolean;
+    type?: ColumnType;
+    /** number: '#,##0.00' | 'integer' | 'percent' | 'currency:USD' | Intl options; date: 'date' | 'datetime' | 'time' | 'short' | 'medium' | 'long' | Intl options */
+    format?: string | Intl.NumberFormatOptions | Intl.DateTimeFormatOptions;
+    align?: 'left' | 'center' | 'right';
+    sortable?: boolean;
+    resizable?: boolean;
+    filter?: FilterType | false;
+    comparator?: (a: unknown, b: unknown, rowA: Row, rowB: Row) => number;
+    valueGetter?: (row: Row) => unknown;
+    /** Return a string (inserted as HTML — escape untrusted data) or an element. */
+    renderer?: (params: CellParams) => string | HTMLElement;
+    cellClass?: string | ((params: CellParams) => string | undefined);
+    children?: ColumnDef[];
+    /** Set false to keep this column out of the column chooser / side bar. */
+    chooser?: boolean;
+    /** Users cannot hide this column from the UI (API still can). */
+    lockVisible?: boolean;
+    /** Allow editing and pasting into this column (requires `field`). */
+    editable?: boolean;
+    /** Editor for editable columns; defaults by type (text, number, date, boolean toggle). */
+    editor?: EditorSpec;
+    /** Reject blank values on edit. */
+    required?: boolean;
+    /** Return true to accept, or a message to reject the edited value. */
+    validate?: (value: unknown, row: Row) => true | string;
+    /** Merge consecutive rows with the same value into one tall cell (or decide with a function). */
+    merge?: boolean | ((a: unknown, b: unknown, rowA: Row, rowB: Row) => boolean);
+    /** Let a long header label wrap onto more lines. */
+    wrapHeaderText?: boolean;
+    /** Aggregate shown in group rows: 'sum' | 'avg' | 'min' | 'max' | 'count' | (values, rows) => value. */
+    aggFunc?: Aggregator;
+}
+type SelectOption = unknown | {
+    value: unknown;
+    label?: string;
+};
+interface EditorParams {
+    value: unknown;
+    row: Row;
+    column: ColumnDef;
+    /** The key that started the edit, when typing replaced the value. */
+    initialText?: string;
+}
+interface CustomEditor {
+    el: HTMLElement;
+    getValue(): unknown;
+    focus?(): void;
+    destroy?(): void;
+}
+type EditorSpec = {
+    type: 'select';
+    options: SelectOption[] | ((row: Row) => SelectOption[]);
+} | {
+    type: 'textarea';
+} | ((params: EditorParams) => CustomEditor);
+type KeyAction = 'edit' | 'clear' | 'undo' | 'redo' | 'copy' | 'paste' | 'selectAll' | 'find' | 'none';
+interface ColumnState {
+    colId: string;
+    width: number;
+    hide: boolean;
+    pinned: 'left' | 'right' | null;
+}
+interface Messages {
+    noRows: string;
+    filter: string;
+    apply: string;
+    reset: string;
+    selectAll: string;
+    search: string;
+    blanks: string;
+    value: string;
+    valueTo: string;
+    sortAsc: string;
+    sortDesc: string;
+    clearSort: string;
+    pinLeft: string;
+    pinRight: string;
+    unpin: string;
+    columnMenu: string;
+    selectRow: string;
+    selectAllRows: string;
+    chooseColumns: string;
+    columns: string;
+    autosizeThis: string;
+    autosizeAll: string;
+    resetColumns: string;
+    hideColumn: string;
+    close: string;
+    copy: string;
+    copyWithHeaders: string;
+    paste: string;
+    pasteHint: string;
+    required: string;
+    invalidValue: string;
+    undo: string;
+    redo: string;
+    deleteRows: string;
+    copyRows: string;
+    statusRows: string;
+    statusFiltered: string;
+    statusSelected: string;
+    count: string;
+    sum: string;
+    avg: string;
+    min: string;
+    max: string;
+    findPlaceholder: string;
+    noMatches: string;
+    findNext: string;
+    findPrevious: string;
+    groupPanelHint: string;
+    groupByThis: string;
+    ungroup: string;
+    expandAll: string;
+    collapseAll: string;
+    pagerRange: string;
+    pageOf: string;
+    pageSize: string;
+    firstPage: string;
+    previousPage: string;
+    nextPage: string;
+    lastPage: string;
+    loading: string;
+    loadFailed: string;
+    filters: string;
+    clearFilters: string;
+    exportCsv: string;
+    exportExcel: string;
+    pivot: string;
+    pivotMode: string;
+    pivotRows: string;
+    pivotColumns: string;
+    pivotValues: string;
+    total: string;
+    addColumn: string;
+    chartBar: string;
+    chartStacked: string;
+    chartLine: string;
+    chartArea: string;
+    chartPie: string;
+    ops: Record<FilterOp, string>;
+}
+interface LocalePack extends Messages {
+    /** BCP 47 tag, also used for Intl formatting and collation. */
+    code: string;
+}
+type Aggregator = 'sum' | 'avg' | 'min' | 'max' | 'count' | ((values: unknown[], rows: Row[]) => unknown);
+interface SummaryCell {
+    agg: Aggregator;
+    /** Text shown before the value, e.g. "Avg". */
+    prefix?: string;
+    /** Overrides the column format for this cell. */
+    format?: ColumnDef['format'];
+}
+interface SummaryRowDef {
+    /** Shown in the first displayed column that has no aggregator in this row. */
+    label?: string;
+    columns: Record<string, Aggregator | SummaryCell>;
+}
+interface SummaryOptions {
+    /** Default 'bottom'. */
+    position?: 'top' | 'bottom';
+    /** true (default): fixed outside the scroll area. false: scrolls with the rows. */
+    pinned?: boolean;
+    /** Rows to aggregate. Default 'filtered'. */
+    scope?: 'filtered' | 'all' | 'selected';
+    rows: SummaryRowDef[];
+}
+/** A rectangular cell range; rows are displayed indexes, columns are column ids. */
+interface GridRange {
+    start: {
+        rowIndex: number;
+        colId: string;
+    };
+    end: {
+        rowIndex: number;
+        colId: string;
+    };
+}
+type ContextMenuItem = 'separator' | {
+    label: string;
+    action: () => void;
+    disabled?: boolean;
+    shortcut?: string;
+};
+interface ContextMenuParams {
+    row: Row | null;
+    rowIndex: number;
+    colId: string;
+    value: unknown;
+    /** The built-in items, so you can keep, reorder or extend them. */
+    defaultItems: ContextMenuItem[];
+}
+/** What the grid asks a server for: rows [start, end) under the current sort and filters. */
+interface ServerParams {
+    start: number;
+    end: number;
+    sort: SortItem[];
+    filters: Record<string, FilterModel>;
+    quickFilter: string;
+}
+interface Datasource {
+    /** Return the rows of the range; `total` is the row count when known (omit it for infinite scroll). */
+    getRows(params: ServerParams): Promise<{
+        rows: Row[];
+        total?: number;
+    }>;
+}
+interface ExportOptions {
+    /** Column ids in order (hidden columns allowed); default: the displayed data columns. */
+    columns?: string[];
+    /** 'filtered' (default, current sort and filters), 'all' (source order) or 'selected' (checked rows). */
+    rows?: 'filtered' | 'all' | 'selected';
+    /** Include the header row(s). Default true. */
+    headers?: boolean;
+    /** xlsx sheet name. */
+    sheetName?: string;
+    /** CSV separator, default ','. */
+    separator?: string;
+}
+interface PivotConfig {
+    /** Row fields; every field but the last becomes a group level. */
+    rows: string[];
+    /** Fields whose values become column groups. */
+    columns?: string[];
+    values: {
+        colId: string;
+        aggFunc?: Aggregator;
+    }[];
+    /** Add a Total column group (default true). */
+    totals?: boolean;
+}
+interface ChartOptions {
+    type?: 'bar' | 'stackedBar' | 'line' | 'area' | 'pie';
+    /** 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. */
+    container?: HTMLElement;
+    title?: string;
+}
+interface ChartHandle {
+    /** Element the SVG is drawn in. */
+    el: HTMLElement;
+    setType(type: 'bar' | 'stackedBar' | 'line' | 'area' | 'pie'): void;
+    update(): void;
+    destroy(): void;
+}
+interface GridOptions {
+    columns: ColumnDef[];
+    data?: Row[];
+    rowHeight?: number;
+    headerHeight?: number;
+    rowSelection?: 'single' | 'multiple';
+    getRowId?: (row: Row) => string;
+    theme?: string;
+    locale?: string | Partial<LocalePack>;
+    /** Font size in px (default 13). Row/header heights follow it unless set explicitly. */
+    fontSize?: number;
+    /** CSS font-family list (default: the theme's system font stack). */
+    fontFamily?: string;
+    /** Dock a Columns panel on the right. `{ open: true }` starts expanded. */
+    sideBar?: boolean | {
+        open?: boolean;
+        panels?: ('columns' | 'filters' | 'pivot')[];
+    };
+    /** Summary rows (totals, averages, …). */
+    summary?: SummaryOptions;
+    /** Excel-style cell ranges: mouse drag, Shift+click, Shift+arrows, Ctrl+A. Default true. */
+    rangeSelection?: boolean;
+    /** false keeps the browser menu; a function customizes the right-click menu. */
+    contextMenu?: false | ((params: ContextMenuParams) => ContextMenuItem[]);
+    /** Remap or disable keys, e.g. `{ Enter: false, 'Ctrl+E': 'edit' }`. */
+    keymap?: Record<string, KeyAction | false>;
+    /** Bar under the grid with row counts and totals of the selected cells. */
+    statusBar?: boolean;
+    /** Drag the corner of the selection to fill cells (editable columns). Default true. */
+    fillHandle?: boolean;
+    /** Data rows fixed above / below the scrolling rows. */
+    pinnedTopRows?: Row[];
+    pinnedBottomRows?: Row[];
+    /** Ctrl+F opens a find bar inside the grid. Default true. */
+    findBar?: boolean;
+    /** Wrap long header labels for every column. */
+    wrapHeaderText?: boolean;
+    /** Group rows by these column ids, in order. */
+    groupBy?: string[];
+    /** Group and tree levels expanded at start: 0 none (default), n levels, -1 all. */
+    groupDefaultExpanded?: number;
+    /** Bar above the header where column headers can be dropped to group by them. */
+    groupPanel?: boolean;
+    /** Nest rows under their parent. Needs `getRowId`; `getParentId` returns the parent's id or null. */
+    treeData?: {
+        getParentId: (row: Row) => unknown;
+    };
+    /** Content of the expandable panel under a master row. */
+    detailRenderer?: (params: {
+        row: Row;
+        rowIndex: number;
+    }) => HTMLElement | string;
+    /** Height of the detail panel in px (default 240). */
+    detailHeight?: number;
+    /** Which rows can expand a detail panel (default: all rows). */
+    isRowMaster?: (row: Row) => boolean;
+    /** Add a handle column for dragging rows into a new order. */
+    rowDrag?: boolean;
+    /** Show rows one page at a time with a pager under the grid. */
+    pagination?: boolean | {
+        pageSize?: number;
+        pageSizes?: number[];
+    };
+    /** Load rows from a server in blocks instead of `data`; sorting and filtering happen on the server. */
+    datasource?: Datasource;
+    /** Rows per server request (default 100). */
+    blockSize?: number;
+    /** Most blocks kept in memory (default 100). */
+    maxBlocks?: number;
+    /** Show the data as a pivot table. */
+    pivot?: PivotConfig;
+    /** Add the Pivot panel to the side bar. */
+    pivotPanel?: boolean;
+    /** Company license key for this domain (free for personal use; see freegrid.app/pricing). */
+    licenseKey?: string;
+}
+interface CellEvent {
+    row: Row;
+    rowIndex: number;
+    colId: string;
+    value: unknown;
+    event: MouseEvent;
+}
+interface GridEvents {
+    cellClick: CellEvent;
+    cellDoubleClick: CellEvent;
+    selectionChange: {
+        selected: Row[];
+    };
+    sortChange: {
+        sort: SortItem[];
+    };
+    filterChange: {
+        filters: Record<string, FilterModel>;
+    };
+    columnResize: {
+        colId: string;
+        width: number;
+    };
+    columnMove: {
+        colId: string;
+        toIndex: number;
+    };
+    focusChange: {
+        rowIndex: number;
+        colId: string;
+    };
+    columnVisible: {
+        colId: string;
+        visible: boolean;
+    };
+    rangeChange: {
+        range: GridRange | null;
+    };
+    cellValueChanged: {
+        row: Row;
+        rowIndex: number;
+        colId: string;
+        oldValue: unknown;
+        newValue: unknown;
+    };
+    paste: {
+        changed: number;
+        skipped: number;
+    };
+    editStart: {
+        rowIndex: number;
+        colId: string;
+    };
+    editStop: {
+        rowIndex: number;
+        colId: string;
+        committed: boolean;
+    };
+    validationFailed: {
+        rowIndex: number;
+        colId: string;
+        value: unknown;
+        message: string;
+    };
+    rowsAdded: {
+        rows: Row[];
+    };
+    rowsRemoved: {
+        rows: Row[];
+    };
+    groupChange: {
+        groupBy: string[];
+    };
+    groupToggle: {
+        key: string;
+        expanded: boolean;
+    };
+    detailToggle: {
+        row: Row;
+        expanded: boolean;
+    };
+    rowDragEnd: {
+        row: Row;
+        fromIndex: number;
+        toIndex: number;
+    };
+    pageChange: {
+        page: number;
+        pageSize: number;
+        pageCount: number;
+    };
+    rowsLoaded: {
+        start: number;
+        end: number;
+        total?: number;
+    };
+    rowsLoadFailed: {
+        start: number;
+        end: number;
+        error: unknown;
+    };
+    pivotChange: {
+        pivot: PivotConfig | null;
+    };
+}
+interface GridApi {
+    setData(rows: Row[]): void;
+    getData(): Row[];
+    setColumns(columns: ColumnDef[]): void;
+    getColumnState(): ColumnState[];
+    applyColumnState(state: ColumnState[]): void;
+    setSort(sort: SortItem[]): void;
+    getSort(): SortItem[];
+    setFilter(colId: string, model: FilterModel | null): void;
+    getFilterModel(): Record<string, FilterModel>;
+    setQuickFilter(text: string): void;
+    getSelectedRows(): Row[];
+    selectAll(): void;
+    deselectAll(): void;
+    getDisplayedRowCount(): number;
+    scrollToRow(index: number): void;
+    setTheme(theme: string): void;
+    setLocale(locale: string | Partial<LocalePack>): void;
+    setFont(font: {
+        size?: number;
+        family?: string | null;
+    }): void;
+    setColumnVisible(colId: string, visible: boolean): void;
+    autoSizeColumns(colIds?: string[]): void;
+    resetColumnState(): void;
+    openColumnChooser(): void;
+    closeColumnChooser(): void;
+    toggleSideBar(open?: boolean, panel?: 'columns' | 'filters' | 'pivot'): void;
+    setSummary(summary: SummaryOptions | null): void;
+    /** Raw aggregate values per summary row, keyed by column id. */
+    getSummaryValues(): Record<string, unknown>[];
+    getRange(): GridRange | null;
+    setRange(range: GridRange | null): void;
+    /** Copy the range (or checked rows, or the focused cell) as Excel TSV; also writes the clipboard when allowed. */
+    copySelection(options?: {
+        headers?: boolean;
+        rows?: boolean;
+    }): string;
+    /** Paste Excel/TSV text at the range or focused cell into editable columns. */
+    pasteText(text: string): {
+        changed: number;
+        skipped: number;
+    };
+    startEdit(rowIndex: number, colId: string): boolean;
+    stopEdit(cancel?: boolean): void;
+    addRows(rows: Row[], index?: number): Row[];
+    removeRows(rows: Row[] | ((row: Row) => boolean)): Row[];
+    removeSelectedRows(): Row[];
+    getModifiedRows(): {
+        created: Row[];
+        updated: Row[];
+        deleted: Row[];
+    };
+    getChanges(): {
+        row: Row;
+        colId: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }[];
+    hasChanges(): boolean;
+    commitChanges(): void;
+    revertChanges(): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Fill from the current selection into `target` (which must contain it), like dragging the fill handle. */
+    fillRange(target: GridRange): void;
+    setPinnedRows(rows: {
+        top?: Row[];
+        bottom?: Row[];
+    }): void;
+    /** Highlight cells containing `text`; returns the number of matches and focuses the first. */
+    find(text: string): number;
+    findNext(): void;
+    findPrevious(): void;
+    clearFind(): void;
+    setGroupBy(colIds: string[]): void;
+    getGroupBy(): string[];
+    /** Expand or collapse one group (key like "country:KR|city:Seoul") or tree row (its id). */
+    setGroupExpanded(key: string, expanded: boolean): void;
+    expandAll(): void;
+    collapseAll(): void;
+    setDetailExpanded(row: Row, expanded: boolean): void;
+    isDetailExpanded(row: Row): boolean;
+    /** Move a row to a new index in the source data. False while sorting, filtering or grouping is active. */
+    moveRow(row: Row, toIndex: number): boolean;
+    /** 0-based page; clamped to the available pages. */
+    setPage(page: number): void;
+    getPage(): number;
+    getPageCount(): number;
+    setPageSize(size: number): void;
+    getPageSize(): number;
+    /** Server data: drop cached rows and load them again. */
+    refreshRows(): void;
+    /** Show a pivot table of the data (null returns to the normal view). */
+    setPivot(pivot: PivotConfig | null): void;
+    getPivot(): PivotConfig | null;
+    /** Chart the range (or the whole view) as SVG; updates when cells change. */
+    createChart(options?: ChartOptions): ChartHandle;
+    getCsv(options?: ExportOptions): string;
+    /** Download a CSV file (UTF-8 with BOM so Excel reads non-Latin text). */
+    exportCsv(filename?: string, options?: ExportOptions): void;
+    /** An .xlsx workbook of the rows. */
+    getXlsx(options?: ExportOptions): Uint8Array;
+    exportXlsx(filename?: string, options?: ExportOptions): void;
+    /** Read an .xlsx or CSV file whose first row holds headers; append (default) or replace the rows. */
+    importFile(file: Blob | ArrayBuffer | Uint8Array, options?: {
+        mode?: 'append' | 'replace';
+        sheet?: number | string;
+    }): Promise<{
+        rows: Row[];
+        skipped: number;
+    }>;
+    on<K extends keyof GridEvents>(type: K, fn: (payload: GridEvents[K]) => void): () => void;
+    destroy(): void;
+}
+
+export type { Aggregator as A, SummaryRowDef as B, CellEvent as C, Datasource as D, EditorParams as E, FilterModel as F, GridOptions as G, TextOp as H, KeyAction as K, LocalePack as L, Messages as M, NumberFilterModel as N, PivotConfig as P, Region as R, SelectOption as S, TextFilterModel as T, 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, ServerParams as u, SetFilterModel as v, SortDir as w, SortItem as x, SummaryCell as y, SummaryOptions as z };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@freegridjs/core",
-  "version": "0.1.0",
-  "description": "FreeGrid — a fast, free, MIT-licensed data grid for the web: virtual scrolling, pinning, filters, column customization, summary rows, 7 languages.",
-  "license": "MIT",
+  "version": "0.7.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",
   "sideEffects": [
     "*.css"