@freegridjs/core 1.1.0 → 1.7.0

package/dist/{types-BDvXVuCe.d.ts → types-DPOWDM8R.d.ts}

@@ -22,6 +22,8 @@ interface XlsxSheet {
     /** Rows frozen at the top (also the AutoFilter row when `autoFilter` is set). */
     freezeRows?: number;
     autoFilter?: boolean;
+    /** Rows printed at the top of every page (Excel's "rows to repeat at top"). */
+    printTitleRows?: number;
 }
 /** Build an .xlsx workbook (stored zip) from rows of values. */
 declare function writeXlsx(sheets: XlsxSheet[]): Uint8Array;
@@ -136,6 +138,8 @@ interface ColumnDef {
     required?: boolean;
     /** Cells may hold formulas like `=qty*price` (same-row fields); the result is shown, sorted and exported. */
     formulas?: boolean;
+    /** A computed column: this formula (like `=qty*price`) is worked out for every row; the column needs no field. */
+    formula?: string;
     /** Reject a value another row already has in this column (blank values are allowed). */
     unique?: boolean;
     /** Set false (or return false) to keep values out of copies: blocked cells copy as empty text. */
@@ -203,6 +207,7 @@ interface SavedGridState {
     pageSize?: number;
     /** Selected row ids (needs getRowId to survive reloads). */
     selected?: string[];
+    conditionalFormats?: ConditionalFormat[];
 }
 type SavedStatePart = keyof SavedGridState;
 /** Row changes from outside (a server push, a websocket): matched by getRowId, not undoable, not tracked as edits. */
@@ -214,6 +219,8 @@ interface RowTransaction {
     update?: Row[];
     /** Rows (or objects with the id fields) to take out. */
     remove?: Row[];
+    /** Rows to update when a row with their id exists, else to add (live feeds that send whole rows). */
+    upsert?: Row[];
 }
 interface TransactionResult {
     added: Row[];
@@ -370,6 +377,38 @@ interface Messages {
     chartArea: string;
     chartPie: string;
     freeBadge: string;
+    /** Context menu: download a PDF of the rows. */
+    exportPdf: string;
+    exportJson: string;
+    /** The assistant panel. */
+    ai: {
+        title: string;
+        placeholder: string;
+        send: string;
+        thinking: string;
+        undo: string;
+        undone: string;
+        failed: string;
+        skipped: string;
+        done: string;
+    };
+    /** Conditional formatting dialog. */
+    cf: {
+        title: string;
+        add: string;
+        clear: string;
+        none: string;
+        type: string;
+        style: string;
+        wholeRow: string;
+        count: string;
+        types: Record<ConditionalFormatType, string>;
+        ops: {
+            notBetween: string;
+            notContains: string;
+        };
+        styles: Record<'red' | 'yellow' | 'green' | 'blue' | 'redText' | 'bold', string>;
+    };
     ops: Record<FilterOp, string>;
 }
 interface LocalePack extends Messages {
@@ -448,6 +487,10 @@ interface Datasource {
     }>;
 }
 interface ExportOptions {
+    /** xlsx and print: header rows on every printed page (default true). */
+    repeatHeader?: boolean;
+    /** xlsx and print: the first n data rows also on every printed page. */
+    repeatRows?: number;
     /** 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). */
@@ -462,6 +505,20 @@ interface ExportOptions {
     styles?: boolean;
 }
 /** print() and getPrintHtml(): the export options plus how the page looks. */
+interface PdfOptions extends PrintOptions {
+    /** Pixels per CSS pixel in the page images (default 2; higher is sharper and larger). */
+    resolution?: number;
+    /** JPEG quality of the page images, 0–1 (default 0.92). */
+    quality?: number;
+}
+interface JsonExportOptions extends ExportOptions {
+    /** Object keys: column ids (default) or column headers. */
+    keys?: 'id' | 'header';
+    /** Values as shown in the grid (formatted text) instead of the raw values. */
+    formatted?: boolean;
+    /** Indentation (default 2; 0 for one line). */
+    space?: number;
+}
 interface PrintOptions extends ExportOptions {
     /** Heading above the table; also the document title. */
     title?: string;
@@ -487,6 +544,162 @@ interface PrintOptions extends ExportOptions {
     printedAt?: boolean;
     /** A row number column. Default: when the grid shows row numbers. */
     rowNumbers?: boolean;
+    /** Repeat the title block on every page. Default false. */
+    repeatTitle?: boolean;
+}
+/** Look of a cell set by a conditional format. Colours: #hex, rgb(), hsl(), names or var(--x). */
+interface CellStyle {
+    color?: string;
+    background?: string;
+    bold?: boolean;
+    italic?: boolean;
+    strike?: boolean;
+}
+type ConditionalFormatType = 'value' | 'formula' | 'top' | 'bottom' | 'aboveAverage' | 'belowAverage' | 'duplicate' | 'unique' | 'dataBar' | 'colorScale' | 'iconSet';
+type ConditionalOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'notBetween' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank';
+/** A conditional format: a rule that styles cells, or a scale drawn over a column. Later rules win on conflicts. */
+interface ConditionalFormat {
+    /** Column ids the format applies to. */
+    columns: string[];
+    /** Default 'value'. */
+    type?: ConditionalFormatType;
+    /** 'value': how the cell is compared with value (and valueTo for between). */
+    op?: ConditionalOp;
+    value?: unknown;
+    valueTo?: unknown;
+    /** 'formula': a formula over the row, true to apply, e.g. '=amount > target'. */
+    formula?: string;
+    /** 'top' / 'bottom': how many cells (default 10), or a percentage with percent: true. */
+    rank?: number;
+    percent?: boolean;
+    /** The look of matching cells. */
+    style?: CellStyle;
+    /** Style every cell of the row when the first column (or the formula) matches. */
+    row?: boolean;
+    /** Matching cells get no styles from later rules. */
+    stopIfTrue?: boolean;
+    /** 'dataBar': the bar colour (default the accent colour). */
+    color?: string;
+    /** 'colorScale': two or three #hex colours from the lowest to the highest value. */
+    colors?: string[];
+    /** 'iconSet': default 'arrows'. */
+    icons?: 'arrows' | 'traffic' | 'signs';
+    /** Scales: the values the bar or colours run between (default the column's lowest and highest). */
+    min?: number;
+    max?: number;
+}
+/** The AI assistant: the grid asks your server, your server asks the model and answers with actions. */
+interface AssistantOptions {
+    /** Your endpoint (POST JSON). It holds the model API key; the browser never sees it. */
+    url: string;
+    headers?: Record<string, string> | (() => Record<string, string>);
+    credentials?: RequestCredentials;
+    /** Rows sent as examples (default 5, max 50; 0 sends none). Columns always go as summaries, not rows. */
+    sampleRows?: number;
+    /** Extra facts for the model, such as what the screen is for. */
+    context?: () => Record<string, unknown>;
+    /** Ideas shown under the input. */
+    suggestions?: string[];
+}
+/** A column as the assistant sees it. */
+interface AssistantColumn {
+    id: string;
+    header: string;
+    type?: string;
+    formula?: string;
+    aggFunc?: string;
+    hidden?: boolean;
+    blanks?: number;
+    distinct?: number;
+    min?: number | string;
+    max?: number | string;
+    avg?: number;
+    /** Most frequent values of text columns. */
+    top?: {
+        value: string;
+        count: number;
+    }[];
+}
+/** What the grid sends to the assistant endpoint. */
+interface AssistantRequest {
+    prompt: string;
+    locale: string;
+    /** Rows after the filters. */
+    rowCount: number;
+    totalRows: number;
+    columns: AssistantColumn[];
+    sample: Row[];
+    state: {
+        sort: SortItem[];
+        filters: Record<string, FilterModel>;
+        quickFilter: string;
+        advancedFilter: AdvancedFilter | null;
+        groupBy: string[];
+        pivot: PivotConfig | null;
+        conditionalFormats: ConditionalFormat[];
+    };
+    context?: Record<string, unknown>;
+}
+/** What the assistant endpoint answers with: { message?, actions? }. */
+type AssistantAction = {
+    type: 'sort';
+    sort: SortItem[];
+} | {
+    type: 'filter';
+    colId: string;
+    model: FilterModel | null;
+} | {
+    type: 'clearFilters';
+} | {
+    type: 'quickFilter';
+    text: string;
+} | {
+    type: 'advancedFilter';
+    filter: AdvancedFilter | null;
+} | {
+    type: 'groupBy';
+    colIds: string[];
+    expand?: boolean;
+} | {
+    type: 'pivot';
+    pivot: PivotConfig | null;
+} | {
+    type: 'showColumns' | 'hideColumns';
+    colIds: string[];
+} | {
+    type: 'conditionalFormat';
+    format: ConditionalFormat;
+} | {
+    type: 'clearConditionalFormats';
+} | {
+    type: 'addColumn';
+    column: {
+        id: string;
+        header?: string;
+        formula: string;
+        type?: 'number' | 'text' | 'date';
+    };
+} | {
+    type: 'summary';
+    summary: SummaryOptions | null;
+} | {
+    type: 'chart';
+    chartType?: ChartOptions['type'];
+    colIds: string[];
+    title?: string;
+} | {
+    type: 'message';
+    text: string;
+};
+interface AssistantResult {
+    message: string;
+    applied: AssistantAction[];
+    skipped: {
+        action: unknown;
+        reason: string;
+    }[];
+    /** Put the grid back as it was before these actions. */
+    undo(): void;
 }
 interface PivotConfig {
     /** Row fields; every field but the last becomes a group level. */
@@ -581,6 +794,16 @@ interface GridOptions {
     editType?: 'cell' | 'row';
     /** Briefly highlight cells whose value changed through applyTransaction (default true). */
     flashCells?: boolean;
+    /** An AI assistant answered by your server (see AssistantOptions). */
+    assistant?: AssistantOptions;
+    /** Rules that colour cells by their values, and data bars, colour scales and icon sets. */
+    conditionalFormats?: ConditionalFormat[];
+    /** Show "Conditional formatting…" in the column menu (default true). */
+    conditionalFormatMenu?: boolean;
+    /** How long a changed cell flashes, in ms (default 1000). Numbers flash green going up and red going down. */
+    flashDuration?: number;
+    /** applyTransactionAsync: how long to collect transactions before applying them together, in ms (default 50). */
+    asyncTransactionWait?: number;
     /** 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). */
@@ -752,6 +975,19 @@ interface GridEvents {
     };
     /** applyTransaction (or a batch of applyTransactionAsync) finished. */
     transactionApplied: TransactionResult;
+    conditionalFormatsChange: {
+        formats: ConditionalFormat[];
+    };
+    /** The assistant answered and its actions were applied. */
+    assistantAnswer: {
+        prompt: string;
+        message: string;
+        applied: AssistantAction[];
+        skipped: {
+            action: unknown;
+            reason: string;
+        }[];
+    };
     /** A row was dropped on this grid (also from another grid of the same drag group). */
     rowDrop: RowDropParams & {
         fromGrid: GridApi | null;
@@ -845,6 +1081,16 @@ interface GridApi {
     applyTransaction(tx: RowTransaction): TransactionResult;
     /** Queue a transaction; queued ones are merged and applied together about every 50 ms. */
     applyTransactionAsync(tx: RowTransaction): void;
+    /** Apply the queued applyTransactionAsync transactions now. */
+    flushAsyncTransactions(): void;
+    setConditionalFormats(formats: ConditionalFormat[]): void;
+    getConditionalFormats(): ConditionalFormat[];
+    /** Ask the assistant (options.assistant) and apply its answer. */
+    askAssistant(prompt: string): Promise<AssistantResult>;
+    /** The assistant panel. */
+    openAssistant(): void;
+    /** The conditional formatting dialog for a column. */
+    openConditionalFormats(colId: string): void;
     /** Conditions across columns, applied together with the column filters; null clears it. */
     setAdvancedFilter(filter: AdvancedFilter | null): void;
     getAdvancedFilter(): AdvancedFilter | null;
@@ -861,6 +1107,10 @@ interface GridApi {
     showOverlay(kind: 'loading' | 'noRows' | null): void;
     /** Print the rows as a table (current sort and filters, group rows and summary rows) on the paper you choose. */
     print(options?: PrintOptions): void;
+    /** The print page as a PDF file (null when the browser cannot draw on a canvas). */
+    getPdf(options?: PdfOptions): Uint8Array | null;
+    /** Download getPdf() as a .pdf file. */
+    exportPdf(filename?: string, options?: PdfOptions): void;
     /** The HTML page print() would print. */
     getPrintHtml(options?: PrintOptions): string;
     /** Check every editable cell against required, unique and validate. Empty when all rows are valid. */
@@ -974,6 +1224,10 @@ interface GridApi {
     getCsv(options?: ExportOptions): string;
     /** Download a CSV file (UTF-8 with BOM so Excel reads non-Latin text). */
     exportCsv(filename?: string, options?: ExportOptions): void;
+    /** The rows as a JSON array of objects. */
+    getJson(options?: JsonExportOptions): string;
+    /** Download getJson() as a .json file. */
+    exportJson(filename?: string, options?: JsonExportOptions): void;
     /** An .xlsx workbook of the rows. */
     getXlsx(options?: ExportOptions): Uint8Array;
     exportXlsx(filename?: string, options?: ExportOptions): void;
@@ -989,4 +1243,4 @@ interface GridApi {
     destroy(): void;
 }
 
-export { type TextFilterModel as $, type AdvancedFilter as A, type RowDropPosition as B, type CellEvent as C, type Datasource as D, type ExportOptions as E, type FilterModel as F, type GridOptions as G, type RowTransaction as H, type InvalidCell as I, type SavedStatePart as J, type KeyAction as K, type LocalePack as L, type Messages as M, type NumberFilterModel as N, type ScrollPosition as O, type PivotConfig as P, type SelectOption as Q, type Row as R, type SavedGridState as S, type ServerParams as T, type SetFilterModel as U, type SortDir as V, type SortItem as W, type SpanParams as X, type SummaryCell as Y, type SummaryOptions as Z, type SummaryRowDef as _, type GridApi as a, type TextOp as a0, type TransactionResult as a1, type XlsxCell as a2, type XlsxSheet as a3, readXlsx as a4, writeXlsx as a5, 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 PrintOptions as w, type Region as x, type RowDragOptions as y, type RowDropParams as z };
+export { type SavedStatePart as $, type AdvancedFilter as A, type EditorSpec as B, type CellEvent as C, type Datasource as D, type ExportOptions as E, type FilterModel as F, type GridOptions as G, type FilterOp as H, type FilterType as I, type GridEvents as J, type GridRange as K, type LocalePack as L, type InvalidCell as M, type JsonExportOptions as N, type KeyAction as O, type Messages as P, type NumberFilterModel as Q, type Row as R, type NumberOp as S, type PdfOptions as T, type PivotConfig as U, type PrintOptions as V, type Region as W, type RowDragOptions as X, type RowDropParams as Y, type RowDropPosition as Z, type SavedGridState as _, type GridApi as a, type ScrollPosition as a0, type SelectOption as a1, type ServerParams as a2, type SetFilterModel as a3, type SortDir as a4, type SortItem as a5, type SpanParams as a6, type SummaryCell as a7, type SummaryOptions as a8, type SummaryRowDef as a9, type TextFilterModel as aa, type TextOp as ab, type TransactionResult as ac, type XlsxCell as ad, type XlsxSheet as ae, readXlsx as af, writeXlsx as ag, type RowTransaction as b, type AdvancedFilterCondition as c, type Aggregator as d, type AssistantAction as e, type AssistantColumn as f, type AssistantOptions as g, type AssistantRequest as h, type AssistantResult as i, type CellParams as j, type CellStyle as k, type ChartHandle as l, type ChartOptions as m, type ColumnDef as n, type ColumnState as o, type ColumnType as p, type CombinedFilterModel as q, type ConditionalFormat as r, type ConditionalFormatType as s, type ConditionalOp as t, type ContextMenuItem as u, type ContextMenuParams as v, type CustomEditor as w, type DateFilterModel as x, type DateOp as y, type EditorParams as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freegridjs/core",
-  "version": "1.1.0",
+  "version": "1.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",