cenitu-table 0.2.0 → 0.4.0-beta.0

package/dist/types/grid/grid.d.ts

@@ -1,14 +1,17 @@
-import { type CellRange } from '../formula/address.js';
+import { type CellAddress, type CellRange } from '../formula/address.js';
 import { FormulaEngine } from '../formula/engine.js';
 import { type CellValue, type RawCell } from '../formula/values.js';
 import { type DataRow } from './binding.js';
 import { type CellMeta, type CellStyle, type ConditionalFormat } from './cellTypes.js';
 import { type CsvOptions } from '../export/csv.js';
+import { type ImportOptions, type ImportSheet } from '../export/xlsxRead.js';
 import type { ExportSheet } from '../export/types.js';
 import { type MenuEntry } from './contextMenu.js';
 import { type ColumnFilter, type SortOrder } from './filters.js';
 import { type MergeArea } from './merges.js';
 import { type Messages } from './messages.js';
+import { type SearchOptions } from './search.js';
+import { type QueryChangeReason, type ServerFilter, type ServerQuery } from './serverMode.js';
 export interface GridOptions {
     /** Rows as arrays, or as objects bound to columns through `columns[i].data` (edits are written back). */
     data?: RawCell[][] | DataRow[];
@@ -60,6 +63,60 @@ export interface GridOptions {
     conditionalFormats?: ConditionalFormat[];
     /** Columns hidden initially. */
     hiddenColumns?: number[];
+    /** Ctrl+F / Ctrl+H open a find and replace box (they stay the browser's shortcuts otherwise). */
+    search?: boolean;
+    /** Shows a bar above the grid with the active cell's address and content; editable. */
+    formulaBar?: boolean;
+    /**
+     * 'server': the application fetches pages; the grid never sorts or filters itself and reports
+     * what it needs through the `afterQueryChange` hook. Formulas are off unless `formulas` is set,
+     * and rows cannot be added locally. Default 'client'.
+     */
+    dataMode?: 'client' | 'server';
+    /** Server mode: object property (or function) identifying a row across pages. */
+    rowKey?: string | ((row: DataRow | RawCell[]) => unknown);
+    /** Server mode: page, sort and filters. Set again to change them from outside. */
+    query?: Partial<ServerQuery>;
+    /** Server mode: records matching the query, for the page bar. */
+    totalCount?: number;
+    /** Server mode: old rows stay visible, dimmed, until new ones arrive. */
+    loading?: boolean;
+    /** Server mode: true shows the default message, a string shows that message. */
+    loadError?: boolean | string;
+    /** Server mode: page sizes offered (default 25, 50, 100). */
+    pageSizes?: number[];
+    /** Server mode: page bar below the grid. Default true. */
+    pager?: boolean;
+    /** Server mode: fills the page bar's slot for application buttons. */
+    pagerActions?: (slot: HTMLElement) => void;
+    /** Server mode: replaces the content of the empty, loading and error messages. */
+    renderStatus?: (el: HTMLElement, state: 'empty' | 'loading' | 'error') => void;
+    /** Column widths, order and visibility to start with, from `getColumnLayout`. */
+    columnLayout?: ColumnLayout;
+}
+/** Saved column arrangement. Only columns with an id (`columns[i].id` or `data`) are included. */
+export interface ColumnLayout {
+    columns: {
+        id: string;
+        width: number;
+        hidden: boolean;
+    }[];
+}
+export interface RowEvent {
+    /** Visual row. */
+    row: number;
+    physicalRow: number;
+    col: number;
+    columnId?: string;
+    /** Needs the `rowKey` option. */
+    rowKey?: unknown;
+    /** The source object (object mode) or raw row. */
+    rowData: DataRow | RawCell[] | undefined;
+    originalEvent: MouseEvent;
+}
+export interface SortKey {
+    col: number;
+    order: SortOrder;
 }
 /** Row indexes: `row` is visual (as displayed, -1 if hidden), `physicalRow` is the data row. */
 export interface CellChange {
@@ -68,10 +125,14 @@ export interface CellChange {
     col: number;
     /** Bound property in object mode. */
     prop?: string;
+    /** Column id, when the column has one. */
+    columnId?: string;
+    /** Server mode: `rowKey` value of the row; indexes change between pages, this does not. */
+    rowKey?: unknown;
     oldValue: RawCell;
     newValue: RawCell;
 }
-export type ChangeSource = 'edit' | 'paste' | 'cut' | 'clear' | 'autofill' | 'undo' | 'redo' | 'api';
+export type ChangeSource = 'edit' | 'paste' | 'cut' | 'clear' | 'autofill' | 'replace' | 'undo' | 'redo' | 'api';
 export type AlterAction = 'insert_row_above' | 'insert_row_below' | 'remove_row' | 'insert_col_start' | 'insert_col_end' | 'remove_col';
 interface HookMap {
     /** Return false to cancel; changes may be modified in place. */
@@ -80,6 +141,16 @@ interface HookMap {
     afterSelection: (row: number, col: number, row2: number, col2: number) => void;
     afterAlter: (action: AlterAction, index: number, amount: number) => void;
     afterColumnSort: (col: number, order: SortOrder | null) => void;
+    afterSort: (keys: SortKey[]) => void;
+    afterRowClick: (e: RowEvent) => void;
+    /** Return false to keep the cell editor closed, e.g. when double click opens the record. */
+    afterRowDoubleClick: (e: RowEvent) => boolean | void;
+    /** Columns were resized, moved, hidden or shown; save the layout here. */
+    afterColumnLayout: (layout: ColumnLayout) => void;
+    /** Server mode: fetch the rows for `query`. */
+    afterQueryChange: (query: ServerQuery, reason: QueryChangeReason) => void;
+    /** Server mode: a paste did not fit the loaded rows; `lost` rows were not pasted. */
+    afterPasteClipped: (lost: number) => void;
     afterFilter: (filters: Map<number, ColumnFilter>) => void;
     afterAutofill: (source: CellRange, target: CellRange) => void;
     afterValidate: (row: number, col: number, error: string | undefined) => void;
@@ -116,7 +187,7 @@ export declare class CenituGrid {
     private cellMeta;
     private labels;
     private filters;
-    private sortState;
+    private sortKeys;
     private invalid;
     /** Custom row heights by physical row. */
     private rowHeights;
@@ -146,9 +217,33 @@ export declare class CenituGrid {
     private undoStack;
     private redoStack;
     private clipboard;
+    private searchPanel?;
+    private searchQuery;
+    private searchOptions;
+    /** Matches shown highlighted while the search box is open (physical cell keys). */
+    private searchHits;
+    private bar?;
+    private server?;
     private frame;
     private cleanup;
     constructor(container: HTMLElement, options?: GridOptions);
+    /** Current query (server mode). */
+    getQuery(): ServerQuery | undefined;
+    /** Changes the query and asks for new rows. Anything but a page change returns to page 1. */
+    setQuery(change: Partial<ServerQuery>, reason?: QueryChangeReason): void;
+    /**
+     * Shows a fetched page. Unlike `loadData`, sort marks, filters, column layout and scroll stay,
+     * and the selection follows its row by `rowKey` when the row is still there. Undo history ends
+     * here: it refers to rows that are gone.
+     */
+    setPageRows(rows: RawCell[][] | DataRow[], totalCount?: number): void;
+    private rowKeyAt;
+    /** Stable id of a column: `columns[i].id`, then its bound property. */
+    getColumnId(col: number): string | undefined;
+    private colOfId;
+    private buildServerMode;
+    /** Page bar, busy state and the empty/loading/error message. */
+    private renderServerState;
     /** Number of visible rows. */
     countRows(): number;
     countSourceRows(): number;
@@ -183,11 +278,23 @@ export declare class CenituGrid {
     setDataAtCell(row: number, col: number, value: RawCell, source?: ChangeSource): void;
     setDataAtCell(changes: [number, number, RawCell][], source?: ChangeSource): void;
     loadData(data: RawCell[][] | DataRow[]): void;
+    /**
+     * Replaces the grid's content with an imported sheet, including its formats, sizes, frozen
+     * panes and merges. Hidden rows are shown: the grid only hides rows through filters.
+     */
+    loadSheet(sheet: ImportSheet): void;
+    /**
+     * Reads one sheet of an .xlsx file into this grid (default the first) and adds the workbook's
+     * defined names to the engine. References to other sheets need all of them: see `workbookEngine`.
+     */
+    importXLSX(file: ArrayBuffer | Uint8Array | Blob, opts?: ImportOptions & {
+        sheet?: number | string;
+    }): Promise<ImportSheet>;
     /** Effective settings of a cell at a visual position. */
     getCellMeta(row: number, col: number): CellMeta;
     setCellMeta(row: number, col: number, meta: CellMeta): void;
     /** Updates a subset of options at runtime. */
-    updateSettings(s: Pick<GridOptions, 'fixedRowsTop' | 'fixedColumnsStart' | 'readOnly' | 'columns' | 'colHeaders' | 'mergeCells' | 'columnSorting' | 'filters' | 'fillHandle' | 'locale' | 'language' | 'contextMenu' | 'conditionalFormats'>): void;
+    updateSettings(s: Pick<GridOptions, 'fixedRowsTop' | 'fixedColumnsStart' | 'readOnly' | 'columns' | 'colHeaders' | 'mergeCells' | 'columnSorting' | 'filters' | 'fillHandle' | 'locale' | 'language' | 'contextMenu' | 'conditionalFormats' | 'search' | 'query' | 'totalCount' | 'loading' | 'loadError'>): void;
     selectCell(row: number, col: number, row2?: number, col2?: number): void;
     private announce;
     /** Selection as [[row, col, row2, col2]] (visual). */
@@ -205,6 +312,16 @@ export declare class CenituGrid {
     toggleCellStyle(flag: 'bold' | 'italic' | 'underline' | 'strike'): void;
     setRowHeight(row: number, height: number): void;
     getRowHeight(row: number): number;
+    /** Current widths, order and visibility; store it and give it back with `setColumnLayout`. */
+    getColumnLayout(): ColumnLayout;
+    /**
+     * Restores a saved layout. Ids that no longer exist are skipped and new columns stay after the
+     * saved ones, so a layout survives application updates. Clears undo history when columns moved:
+     * its entries refer to the old order.
+     */
+    setColumnLayout(layout: ColumnLayout): void;
+    private applyColumnLayout;
+    private layoutChanged;
     hideColumns(cols: number[]): void;
     /** Shows the given hidden columns, or all of them. */
     showColumns(cols?: number[]): void;
@@ -223,15 +340,38 @@ export declare class CenituGrid {
     downloadXLSX(fileName?: string, others?: CenituGrid[]): Promise<void>;
     /** Sorts by one column (visual order only; data and formulas are untouched). null restores data order. */
     sort(col: number, order: SortOrder | null): void;
-    getSortState(): {
-        col: number;
-        order: SortOrder;
-    } | null;
+    /** Sorts by several columns: the first key decides, later keys break ties. Empty restores data order. */
+    sortBy(keys: SortKey[]): void;
+    private applySort;
+    /** The primary sort key, or null. */
+    getSortState(): SortKey | null;
+    getSortKeys(): SortKey[];
+    /** Server mode: sets or clears the filter of a column; asks for rows from page 1. */
+    setServerFilter(columnId: string, filter: ServerFilter | null): void;
     setFilter(col: number, filter: ColumnFilter | null): void;
     clearFilters(): void;
     getFilters(): Map<number, ColumnFilter>;
     /** Re-evaluates the filters against current values (they are not re-applied automatically on edit). */
     applyFilters(): void;
+    /** Visual positions of the cells matching `query`, in reading order; hidden columns are skipped. */
+    findCells(query: string, opts?: SearchOptions): CellAddress[];
+    /** Selects the match after (or before) the active cell, wrapping around; null when there is none. */
+    findNext(query: string, opts?: SearchOptions, backward?: boolean): CellAddress | null;
+    /**
+     * Replaces the match in the active cell (when it is one) and moves to the next. Formula cells
+     * change only with `lookIn: 'formulas'`: replacing in their result would delete the formula.
+     */
+    replaceNext(query: string, replacement: string, opts?: SearchOptions): CellAddress | null;
+    /** Replaces every match in one undo step; returns the number of cells changed. */
+    replaceAll(query: string, replacement: string, opts?: SearchOptions): number;
+    /** Opens the find box (`search` option), with the replace row when `replace` is true. */
+    openSearch(replace?: boolean): void;
+    closeSearch(): void;
+    private searchText;
+    private nextHit;
+    private highlightHits;
+    private stepSearch;
+    private replaceIn;
     /** Merges an area (visual coordinates). Refused while sorting/filtering is active or across frozen edges. */
     mergeCells(row: number, col: number, rowspan: number, colspan: number): boolean;
     unmergeCells(row: number, col: number): boolean;
@@ -244,6 +384,7 @@ export declare class CenituGrid {
      * is a no-op, out of range, or would split a merged cell.
      */
     moveColumns(start: number, count: number, target: number): boolean;
+    private relocateColumns;
     canMoveColumns(start: number, count: number, target: number): boolean;
     undo(): void;
     redo(): void;
@@ -263,9 +404,11 @@ export declare class CenituGrid {
     copy(cut?: boolean): string | undefined;
     /**
      * Pastes text at the selection. Text from this grid's own copy keeps formulas, with relative
-     * references moved to the new location. A single value fills the whole selection.
+     * references moved to the new location and its cell styles. `html` is the clipboard's HTML
+     * flavour from another app; only the styles of its table are used. A single value fills the
+     * whole selection.
      */
-    paste(text: string): void;
+    paste(text: string, html?: string): void;
     /** Fills `target` (adjacent to `source`, visual coordinates) by extending the source series. */
     autofill(source: CellRange, target: CellRange): void;
     render(): void;
@@ -281,6 +424,7 @@ export declare class CenituGrid {
     private applyChanges;
     private clearRange;
     private replay;
+    private replayEntry;
     private applyMeta;
     private applyEngineOp;
     private undoEngineOp;
@@ -344,6 +488,11 @@ export declare class CenituGrid {
     openEditor(initial?: string): void;
     closeEditor(commit: boolean): void;
     private focusInput;
+    private barFocused;
+    private buildFormulaBar;
+    private onBarKey;
+    /** Shows the active cell in the bar; while editing, the bar mirrors the editor. */
+    private syncFormulaBar;
     /** Keeps the textarea over the active cell (in its pane), so IME windows appear in the right place. */
     private placeInput;
     private autoSizeInput;
@@ -360,6 +509,8 @@ export declare class CenituGrid {
     private onMouseDown;
     private onContextMenu;
     private onDoubleClick;
+    /** The row a click landed on; null for headers, checkboxes and drags that ended on another cell. */
+    private rowEventAt;
     private onDrag;
     private onMouseUp;
     private dropLine?;
@@ -370,6 +521,7 @@ export declare class CenituGrid {
     private fillToDataEnd;
     private startResize;
     private startRowResize;
+    private openServerMenu;
     private openMenu;
     private toggleCheckboxes;
     private moveActive;

package/dist/types/grid/messages.d.ts

@@ -2,6 +2,8 @@ export interface Messages {
     sortAsc: string;
     sortDesc: string;
     sortClear: string;
+    sortThenAsc: string;
+    sortThenDesc: string;
     filterByCondition: string;
     filterByValue: string;
     search: string;
@@ -42,6 +44,32 @@ export interface Messages {
     hideColumns: string;
     showColumns: string;
     cellAnnouncement: string;
+    find: string;
+    replace: string;
+    replaceAll: string;
+    replaceWith: string;
+    matchCase: string;
+    wholeCell: string;
+    lookInFormulas: string;
+    noMatches: string;
+    /** {total} is the number of matches. */
+    matchCount: string;
+    /** {count} is the number of cells changed. */
+    replacedCount: string;
+    next: string;
+    previous: string;
+    close: string;
+    formulaBar: string;
+    /** {from}, {to} and {total} are record numbers. */
+    pagerRange: string;
+    pageSize: string;
+    noRows: string;
+    loading: string;
+    loadError: string;
+    dateFrom: string;
+    dateTo: string;
+    yes: string;
+    no: string;
 }
 export declare const enUS: Messages;
 export declare const trTR: Messages;

package/dist/types/grid/search.d.ts

@@ -0,0 +1,41 @@
+import type { Messages } from './messages.js';
+export interface SearchOptions {
+    matchCase?: boolean;
+    /** Match only when the whole cell equals the query. */
+    wholeCell?: boolean;
+    /** 'values' (default) searches what cells display; 'formulas' searches what was entered. */
+    lookIn?: 'values' | 'formulas';
+}
+type Span = [number, number];
+/** Occurrences of `query` in `text` as [start, end) in `text`'s own indexes. */
+export declare function matchSpans(text: string, query: string, o?: SearchOptions, locale?: string): Span[];
+/** `text` with every occurrence of `query` replaced. */
+export declare function replaceSpans(text: string, spans: Span[], replacement: string): string;
+export interface SearchPanelOptions {
+    root: HTMLElement;
+    messages: Messages;
+    query: string;
+    options: SearchOptions;
+    /** Shows the replace row; false for read-only grids. */
+    replace: boolean;
+    /** Re-runs the search; returns the number of matches. */
+    onSearch(query: string, options: SearchOptions): number;
+    /** Moves to the next match; returns its 1-based position and the total. */
+    onNext(backward: boolean): {
+        index: number;
+        total: number;
+    };
+    onReplace(replacement: string): {
+        index: number;
+        total: number;
+    };
+    onReplaceAll(replacement: string): number;
+    onClose(): void;
+}
+export interface SearchPanel {
+    close(): void;
+    focus(replace: boolean): void;
+}
+/** Floating find/replace box over the grid's top right corner. */
+export declare function openSearchPanel(o: SearchPanelOptions): SearchPanel;
+export {};

package/dist/types/grid/serverMode.d.ts

@@ -0,0 +1,66 @@
+import type { Messages } from './messages.js';
+/** What a column can be filtered by on the server. */
+export type ServerFilterDef = {
+    kind: 'text';
+} | {
+    kind: 'list';
+    options: {
+        value: string;
+        label?: string;
+    }[];
+} | {
+    kind: 'date';
+} | {
+    kind: 'boolean';
+};
+/** A filter value in the query; date bounds are as the date inputs give them (YYYY-MM-DD). */
+export type ServerFilter = {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'list';
+    values: string[];
+} | {
+    kind: 'date';
+    from?: string;
+    to?: string;
+} | {
+    kind: 'boolean';
+    value: boolean;
+};
+export interface ServerSort {
+    field: string;
+    desc: boolean;
+}
+/** Describes the rows the application should fetch. Fields are column ids, never indexes. */
+export interface ServerQuery {
+    page: number;
+    pageSize: number;
+    sort: ServerSort[];
+    filters: Record<string, ServerFilter>;
+    search?: string;
+}
+export type QueryChangeReason = 'page' | 'pageSize' | 'sort' | 'filter' | 'search';
+export declare const DEFAULT_PAGE_SIZES: number[];
+export declare function initialQuery(q: Partial<ServerQuery> | undefined, pageSizes: number[]): ServerQuery;
+export declare const pageCount: (total: number, pageSize: number) => number;
+/** The controls for one filter; `read` gives the entered filter, or null when it is empty. */
+export declare function serverFilterSection(doc: Document, m: Messages, def: ServerFilterDef, value: ServerFilter | undefined): {
+    el: HTMLElement;
+    read(): ServerFilter | null;
+};
+/** Page bar: custom actions, record range, page size, previous and next. */
+export declare class Pager {
+    private readonly m;
+    readonly el: HTMLDivElement;
+    /** Slot for application buttons. */
+    readonly actions: HTMLDivElement;
+    private readonly range;
+    private readonly size;
+    private readonly position;
+    private readonly prev;
+    private readonly next;
+    constructor(doc: Document, m: Messages, pageSizes: number[], onPage: (delta: number) => void, onSize: (size: number) => void);
+    /** `total` undefined keeps the last figures, so the bar does not flicker while a page loads. */
+    update(q: ServerQuery, total: number | undefined): void;
+}

package/dist/types/index.d.ts

@@ -1,7 +1,9 @@
-export { CenituGrid, type GridOptions, type CellChange, type ChangeSource, type AlterAction, type HookName, } from './grid/grid.js';
+export { CenituGrid, type GridOptions, type CellChange, type ChangeSource, type AlterAction, type SortKey, type ColumnLayout, type RowEvent, type HookName, } from './grid/grid.js';
 export type { CellMeta, CellStyle, ConditionalFormat, NumericFormat, CellRenderContext, CellType as GridCellType } from './grid/cellTypes.js';
 export type { ColumnFilter, ConditionOp, SortOrder } from './grid/filters.js';
 export type { MergeArea } from './grid/merges.js';
+export type { SearchOptions } from './grid/search.js';
+export type { ServerQuery, ServerFilter, ServerFilterDef, ServerSort, QueryChangeReason } from './grid/serverMode.js';
 export type { MenuEntry, MenuItem } from './grid/contextMenu.js';
 export type { DataRow } from './grid/binding.js';
 export { enUS, trTR, type Messages } from './grid/messages.js';

package/dist/types/react/index.d.ts

@@ -1,6 +1,7 @@
 import { type CSSProperties } from 'react';
 import type { ColumnFilter, SortOrder } from '../grid/filters.js';
-import { CenituGrid, type CellChange, type ChangeSource, type GridOptions } from '../grid/grid.js';
+import { CenituGrid, type CellChange, type ChangeSource, type ColumnLayout, type GridOptions, type RowEvent } from '../grid/grid.js';
+import type { QueryChangeReason, ServerQuery } from '../grid/serverMode.js';
 export interface CenituTableProps extends GridOptions {
     className?: string;
     style?: CSSProperties;
@@ -8,6 +9,12 @@ export interface CenituTableProps extends GridOptions {
     onSelection?(row: number, col: number, row2: number, col2: number): void;
     onSort?(col: number, order: SortOrder | null): void;
     onFilter?(filters: Map<number, ColumnFilter>): void;
+    onRowClick?(event: RowEvent): void;
+    /** Return false to keep the cell editor closed. */
+    onRowDoubleClick?(event: RowEvent): boolean | void;
+    onColumnLayoutChange?(layout: ColumnLayout): void;
+    /** Server mode: fetch the rows for `query`. */
+    onQueryChange?(query: ServerQuery, reason: QueryChangeReason): void;
 }
 /**
  * React component around CenituGrid. The ref exposes the grid instance for imperative calls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cenitu-table",
-  "version": "0.2.0",
+  "version": "0.4.0-beta.0",
   "description": "Spreadsheet-like data grid with a built-in multi-sheet formula engine. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",