@dhtmlx/trial-react-spreadsheet 6.0.0

package/dist/spreadsheet.react.es.d.ts

@@ -0,0 +1,633 @@
+import * as react from 'react';
+import react__default from 'react';
+
+// --- Simple type aliases ---
+
+type Id = string | number;
+type FileFormat = "json" | "csv" | "xlsx";
+type formatAliases = "common" | "number" | "currency" | "percent" | "text" | "date" | "time";
+type ToolbarBlocks = "default" | "undo" | "colors" | "columns" | "rows" | "cell" | "lock" | "align" | "decoration" | "clear" | "help" | "format" | "actions" | "file";
+
+// --- Enums ---
+
+declare enum FilterConditions {
+	e = "e",
+	ne = "ne",
+	tc = "tc",
+	tdc = "tdc",
+	ts = "ts",
+	te = "te",
+	tex = "tex",
+	d = "d",
+	db = "db",
+	da = "da",
+	gt = "gt",
+	geq = "geq",
+	lt = "lt",
+	leq = "leq",
+	eq = "eq",
+	neq = "neq",
+	ib = "ib",
+	inb = "inb",
+}
+
+// --- Small interfaces ---
+
+interface IFormats {
+	id: formatAliases | string;
+	mask: string;
+	name?: string;
+	example?: string;
+	timeFormat?: number;
+	$value?: any;
+}
+
+interface ISheet {
+	name: string;
+	id: Id;
+}
+
+interface CellEditor {
+	type: "select";
+	options?: string | string[];
+}
+
+interface ILink {
+	text?: string;
+	href: string;
+}
+
+interface ICellInfo {
+	cell: string;
+	value?: string | number | Date;
+	css?: string;
+	format?: string;
+	editor?: CellEditor;
+	link?: ILink;
+}
+
+interface IFilterRules {
+	condition?: {
+		factor: FilterConditions;
+		value?: any;
+	};
+	exclude?: any[];
+}
+
+interface IFilter {
+	cell: string;
+	rules: IFilterRules[];
+}
+
+interface IStylesList {
+	[key: string]: string;
+}
+
+interface ICell {
+	row: string;
+	col: string;
+}
+
+// --- Composite interfaces ---
+
+interface ISheetData {
+	data: ICellInfo[];
+	name?: string;
+	id?: string;
+	cols?: {
+		width?: number;
+		hidden?: boolean;
+	}[];
+	rows?: {
+		height?: number;
+		hidden?: boolean;
+	}[];
+	merged?: {
+		from: {
+			row: number;
+			column: number;
+		};
+		to: {
+			row: number;
+			column: number;
+		};
+	}[];
+	freeze?: {
+		row?: number;
+		col?: number;
+	};
+}
+
+interface IDataWithStyles {
+	data?: ICellInfo[];
+	styles: {
+		[key: string]: any;
+	};
+	formats?: IFormats[];
+	sheets?: ISheetData[];
+}
+
+interface ILocalization {
+	decimal?: "." | ",";
+	thousands?: "." | "," | " " | "";
+	currency?: string;
+	dateFormat?: string;
+	timeFormat?: 12 | 24;
+}
+
+interface ISpreadsheetConfig {
+	toolbarBlocks?: ToolbarBlocks[];
+	rowsCount?: number;
+	colsCount?: number;
+	editLine?: boolean;
+	menu?: boolean;
+	readonly?: boolean;
+	multiSheets?: boolean;
+	localization?: ILocalization;
+	importModulePath?: string;
+	exportModulePath?: string;
+	formats?: IFormats[];
+	leftSplit?: number;
+	topSplit?: number;
+	dateFormat?: string;
+	timeFormat?: number;
+}
+
+interface ISelection {
+	setSelectedCell(cell: string, scroll?: boolean): any;
+	getSelectedCell(): string;
+	setFocusedCell(cell: string, scroll?: boolean): any;
+	getFocusedCell(): string;
+	removeSelectedCell(cell: string): any;
+}
+
+interface ISheetManager {
+	parseSheets: (sheets: ISheet[]) => void;
+	add: (name?: string) => Id;
+	remove: (id: Id) => void;
+	getAll: () => ISheet[];
+	getActive: () => ISheet;
+	setActive: (id: Id) => void;
+	clear: (id?: Id) => void;
+	get: (id: Id) => ISheet;
+}
+
+// --- Main interface (external deps replaced with any) ---
+
+interface ISpreadsheet {
+	selection: ISelection;
+	events: any;
+	config: ISpreadsheetConfig;
+	toolbar: any;
+	sheets: ISheetManager;
+	menu: any;
+	contextMenu: any;
+	container: HTMLElement;
+	export: any;
+	keyManager: any;
+	getFormula: (cell: string) => string | string[];
+	getValue: (cell: string) => any | any[];
+	setValue: (cell: string, value: any | any[]) => void;
+	getStyle: (cell: string) => IStylesList | IStylesList[];
+	setStyle: (cell: string, styles: string | string[] | IStylesList | IStylesList[]) => void;
+	getFormat: (cell: string) => string | string[];
+	setFormat: (cell: string, format: string | string[]) => void;
+	clear: () => void;
+	getCellIndex: (cell1: string, cell2: string) => ICell;
+	lock: (cell: string) => void;
+	unlock: (cell: string) => void;
+	isLocked: (cell: string) => boolean;
+	deleteColumn: (cell: string) => void;
+	deleteRow: (cell: string) => void;
+	addColumn: (cell: string) => void;
+	addRow: (cell: string) => void;
+	load: (url: string, type?: FileFormat) => Promise<any>;
+	parse: (data: any) => void;
+	serialize: () => any[] | IDataWithStyles;
+	eachCell: (cb: (cellName: string, cellValue: any) => any, range?: string) => void;
+	setValidation: (cell: string, options: string | string[]) => void;
+	sortCells: (cell: string, dir?: 1 | -1) => void;
+	undo(): void;
+	redo(): void;
+	startEdit(cell?: string, initialValue?: string): any;
+	endEdit(withoutSave?: boolean): void;
+	setFilter: (cell?: string, filter?: IFilterRules[]) => void;
+	getFilter: (id: Id) => IFilter;
+	search: (text: string, openSearch?: boolean, sheetId?: Id) => string[];
+	hideSearch: () => void;
+	insertLink: (cell: string, link: ILink) => void;
+	fitColumn: (cell: string) => void;
+	mergeCells: (cell: string, remove?: boolean) => void;
+	freezeCols: (cell?: string) => void;
+	unfreezeCols: (cell?: string) => void;
+	freezeRows: (cell?: string) => void;
+	unfreezeRows: (cell?: string) => void;
+	hideCols: (cell?: string) => void;
+	showCols: (cell?: string) => void;
+	hideRows: (cell?: string) => void;
+	showRows: (cell?: string) => void;
+	clearSheet: (id?: string) => void;
+	removeSheet: (id: string) => void;
+	addSheet: (name?: string) => string;
+	getSheets: () => ISheet[];
+	getActiveSheet: () => ISheet;
+	setActiveSheet: (id: Id) => void;
+	paint: () => void;
+	destructor: () => void;
+}
+
+/**
+ * Known spreadsheet action identifiers.
+ * Used in `onBeforeAction`/`onAfterAction` for type-safe action matching.
+ * The `| string` union on handler params allows forward-compat with new actions.
+ */
+declare enum Actions {
+    setCellStyle = "setCellStyle",
+    setCellValue = "setCellValue",
+    setCellFormat = "setCellFormat",
+    removeCellStyles = "removeCellStyles",
+    lockCell = "lockCell",
+    deleteRow = "deleteRow",
+    addRow = "addRow",
+    deleteColumn = "deleteColumn",
+    addColumn = "addColumn",
+    groupAction = "groupAction",
+    groupRowAction = "groupRowAction",
+    groupColAction = "groupColAction",
+    addSheet = "addSheet",
+    deleteSheet = "deleteSheet",
+    renameSheet = "renameSheet",
+    clearSheet = "clearSheet",
+    clear = "clear",
+    resizeCol = "resizeCol",
+    resizeRow = "resizeRow",
+    setValidation = "setValidation",
+    sortCells = "sortCells",
+    insertLink = "insertLink",
+    fitColumn = "fitColumn",
+    filter = "filter",
+    merge = "merge",
+    unmerge = "unmerge",
+    toggleFreeze = "toggleFreeze",
+    toggleVisibility = "toggleVisibility"
+}
+/**
+ * Action execution configuration passed to `onBeforeAction`/`onAfterAction`.
+ * Shape varies by action type — use the `action` param to narrow.
+ */
+interface IExecuteConfig {
+    row?: number;
+    col?: number;
+    target?: unknown;
+    val?: unknown;
+    prev?: unknown;
+    action?: Actions | string;
+    groupAction?: Actions | string;
+    cell?: string;
+    pageId?: Id;
+    pageName?: string;
+    [key: string]: unknown;
+}
+/**
+ * A single cell's declarative state.
+ * All properties are optional — omitted properties retain their current value
+ * during diff-based updates.
+ */
+interface CellData {
+    /** Cell value: text, number, or formula string (prefixed with `=`). */
+    value?: string | number;
+    /** CSS class name(s) referencing keys in the top-level `styles` map. */
+    css?: string;
+    /** Number format mask or alias (e.g. `"currency"`, `"#,##0.00"`). */
+    format?: string;
+    /** Whether the cell is locked (protected from editing). */
+    locked?: boolean;
+    /** Data validation dropdown options. */
+    validation?: string | string[];
+}
+/**
+ * Row metadata. Only rows with non-default config need entries.
+ * Keys are 0-indexed row numbers.
+ */
+interface RowConfig {
+    /** Row height in pixels. */
+    height?: number;
+    /** Whether the row is hidden. */
+    hidden?: boolean;
+}
+/**
+ * Column metadata. Only columns with non-default config need entries.
+ * Keys are 0-indexed column numbers.
+ */
+interface ColConfig {
+    /** Column width in pixels. */
+    width?: number;
+    /** Whether the column is hidden. */
+    hidden?: boolean;
+}
+/** Defines a merged cell range using 0-indexed row/column coordinates. */
+interface MergedRange {
+    /** Top-left corner of the merge (0-indexed). */
+    from: {
+        row: number;
+        column: number;
+    };
+    /** Bottom-right corner of the merge (0-indexed). */
+    to: {
+        row: number;
+        column: number;
+    };
+}
+/** Freeze pane configuration for a sheet. */
+interface FreezeConfig {
+    /** Freeze columns up to this 0-indexed column number. `undefined` = no column freeze. */
+    col?: number;
+    /** Freeze rows up to this 0-indexed row number. `undefined` = no row freeze. */
+    row?: number;
+}
+/** Filter configuration for a column within a sheet. */
+interface SheetFilter {
+    /** Cell reference identifying the filtered column (e.g. `"A1"`). */
+    cell: string;
+    /** Filter rules to apply. Empty array clears the filter. */
+    rules: IFilterRules[];
+}
+/** Sort configuration for a column within a sheet. */
+interface SheetSort {
+    /** Cell reference or range for the sort operation (e.g. `"B1"` or `"A1:E8"`).
+     * Use a range to sort multiple columns together while maintaining row integrity. */
+    cell: string;
+    /** Sort direction: `1` = ascending, `-1` = descending. */
+    dir: 1 | -1;
+}
+/**
+ * Complete declarative state for a single spreadsheet sheet.
+ */
+interface SheetData {
+    /** Unique sheet identifier. */
+    id: Id;
+    /** Display name shown on the sheet tab. */
+    name: string;
+    /**
+     * Cell data keyed by cell reference (e.g. `"A1"`, `"B2"`).
+     * Only cells with non-default data need entries.
+     */
+    cells: Record<string, CellData>;
+    /**
+     * Row configuration keyed by 0-indexed row number.
+     * Only rows with custom height or hidden state need entries.
+     */
+    rows?: Record<number, RowConfig>;
+    /**
+     * Column configuration keyed by 0-indexed column number.
+     * Only columns with custom width or hidden state need entries.
+     */
+    cols?: Record<number, ColConfig>;
+    /**
+     * Merged cell ranges. The wrapper diffs the array and calls
+     */
+    merged?: MergedRange[];
+    /**
+     * Frozen pane configuration. Diff triggers
+     */
+    freeze?: FreezeConfig;
+    /**
+     * Column filter configuration.
+     * Set to `undefined` to clear filters for this sheet.
+     */
+    filter?: SheetFilter;
+    /**
+     * Sort configuration.
+     */
+    sort?: SheetSort;
+}
+/**
+ * Controlled search state.
+ * Pass an object to trigger/update search, pass `undefined` to dismiss.
+ */
+interface SearchConfig {
+    /** Text to search for. */
+    query: string;
+    /** Whether to open the built-in search UI. Default: `false`. */
+    open?: boolean;
+    /** Restrict search to a specific sheet by id. */
+    sheetId?: Id;
+}
+/**
+ * Localization configuration for UI labels and formula names.
+ */
+interface SpreadsheetLocale {
+    /** UI string overrides. Keys match the library's locale dictionary. */
+    locale: Record<string, string>;
+    /**
+     * Localized formula names grouped by category.
+     * Each entry is a tuple: `[localizedName, optionalDescription?]`.
+     */
+    formulas: Record<string, [string, string?][]>;
+}
+/** Spreadsheet color theme. Built-in themes or a custom theme name string. */
+type SpreadsheetTheme = "light" | "dark" | "contrast-light" | "contrast-dark" | string;
+type BeforeActionHandler = (action: Actions | string, config: IExecuteConfig) => boolean | void;
+type AfterActionHandler = (action: Actions | string, config: IExecuteConfig) => void;
+type BeforeCellHandler = (cell: string) => boolean | void;
+type AfterCellHandler = (cell: string) => void;
+type BeforeEditHandler = (cell: string, value: string) => boolean | void;
+type AfterEditHandler = (cell: string, value: string) => void;
+type BeforeSheetHandler = (sheet: ISheet) => boolean | void;
+type AfterSheetHandler = (sheet: ISheet) => void;
+type SpreadsheetConfigProps = Omit<ISpreadsheetConfig, "leftSplit" | "topSplit" | "dateFormat" | "timeFormat">;
+interface SpreadsheetProps extends SpreadsheetConfigProps {
+    /**
+     * Whether to show the context menu.
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    menu?: boolean;
+    /**
+     * Whether to show the formula/edit line above the grid.
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    editLine?: boolean;
+    /**
+     * Toolbar blocks to display. Default: `"default"` (all blocks).
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    toolbarBlocks?: ToolbarBlocks[];
+    /**
+     * Whether to enable multiple sheet tabs.
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    multiSheets?: boolean;
+    /**
+     * Custom number format definitions.
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    formats?: IFormats[];
+    /**
+     * Number/date formatting locale (decimal separator, currency symbol, etc.).
+     * This is separate from `spreadsheetLocale` which handles UI translations.
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    localization?: ISpreadsheetConfig["localization"];
+    /**
+     * Path to the XLSX import module.
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    importModulePath?: string;
+    /**
+     * Path to the XLSX export module.
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    exportModulePath?: string;
+    /**
+     * Number of rows in the grid.
+     */
+    rowsCount?: number;
+    /**
+     * Number of columns in the grid.
+     */
+    colsCount?: number;
+    /**
+     * Whether the spreadsheet is in read-only mode.
+     */
+    readonly?: boolean;
+    /**
+     * The single source of truth for all spreadsheet data.
+     * Each entry represents a sheet with its cells, structure, and metadata.
+     */
+    sheets?: SheetData[];
+    /**
+     * Shared CSS style definitions referenced by `CellData.css`.
+     * Keys are class names, values are CSS property maps.
+     *
+     * @remarks ⚠️ Changing style definitions triggers a full data re-parse
+     * (`instance.parse()`). User data is preserved via `serialize()`, but
+     * undo/redo history and UI state (selection, scroll) are reset.
+     *
+     * @example
+     * ```ts
+     * styles={{
+     *   bold: { "font-weight": "bold" },
+     *   highlight: { background: "#ffeb3b", color: "#333" },
+     * }}
+     * ```
+     */
+    styles?: Record<string, Record<string, string>>;
+    /**
+     * Id of the active (visible) sheet.
+     */
+    activeSheet?: Id;
+    /**
+     * Controlled search state.
+     * Pass a `SearchConfig` object to trigger/update search.
+     * Pass `undefined` to dismiss the search bar.
+     */
+    search?: SearchConfig;
+    /**
+     * URL to load spreadsheet data from.
+     * Mutually exclusive with `sheets` — if both provided, `sheets` takes precedence.
+     */
+    loadUrl?: string;
+    /** File format hint for `loadUrl`. Default: `"json"`. */
+    loadFormat?: FileFormat;
+    /**
+     * UI locale and formula name translations.
+     * This is separate from `localization` (which handles number/date formatting).
+     * Both can be used together.
+     *
+     * @remarks ⚠️ Init-only. Changing this prop destroys and recreates the
+     * Spreadsheet instance. User data is preserved via serialize/parse,
+     * but undo/redo history and UI state (selection, scroll) are reset.
+     */
+    spreadsheetLocale?: SpreadsheetLocale;
+    /**
+     * Fires before any user action executes.
+     * Return `false` to cancel the action.
+     */
+    onBeforeAction?: BeforeActionHandler;
+    /** Fires after any user action completes successfully. */
+    onAfterAction?: AfterActionHandler;
+    /** Fires before a cell is added to the selection. Return `false` to cancel. */
+    onBeforeSelectionSet?: BeforeCellHandler;
+    /** Fires after a cell is added to the selection. */
+    onAfterSelectionSet?: AfterCellHandler;
+    /** Fires before a cell is removed from the selection. Return `false` to cancel. */
+    onBeforeSelectionRemove?: BeforeCellHandler;
+    /** Fires after a cell is removed from the selection. */
+    onAfterSelectionRemove?: AfterCellHandler;
+    /** Fires before the focused cell changes. Return `false` to cancel. */
+    onBeforeFocusSet?: BeforeCellHandler;
+    /** Fires after the focused cell changes. */
+    onAfterFocusSet?: AfterCellHandler;
+    /** Fires before cell editing begins. Return `false` to cancel. */
+    onBeforeEditStart?: BeforeEditHandler;
+    /** Fires after cell editing begins. */
+    onAfterEditStart?: AfterEditHandler;
+    /** Fires before cell editing ends. Return `false` to cancel and keep editing. */
+    onBeforeEditEnd?: BeforeEditHandler;
+    /** Fires after cell editing ends and the value is committed. */
+    onAfterEditEnd?: AfterEditHandler;
+    /** Fires before the active sheet changes. Return `false` to cancel. */
+    onBeforeSheetChange?: BeforeSheetHandler;
+    /** Fires after the active sheet changes. */
+    onAfterSheetChange?: AfterSheetHandler;
+    /** Fires after `parse()` or `load()` completes. */
+    onAfterDataLoaded?: () => void;
+    /** Fires during auto-fill (drag-fill) operations. */
+    onGroupFill?: (focusedCell: string, selectedCell: string) => void;
+    /** Fires on input in the formula/edit line. */
+    onEditLineInput?: (value: string) => void;
+    /** Fires on input in a cell during editing. */
+    onCellInput?: (cell: string, value: string) => void;
+    /**
+     * Notifies when undo/redo availability changes.
+     * Use to enable/disable external undo/redo buttons.
+     */
+    onStateChange?: (state: {
+        canUndo: boolean;
+        canRedo: boolean;
+    }) => void;
+    /** Notifies with matching cell references when `search` prop is active. */
+    onSearchResults?: (cells: string[]) => void;
+    /**
+     * Notifies when the user changes filters via the UI.
+     * Useful for syncing external filter state.
+     */
+    onFilterChange?: (filter: SheetFilter) => void;
+    /** Spreadsheet color theme. */
+    theme?: SpreadsheetTheme;
+    /** CSS class name appended to the container div. */
+    className?: string;
+    /** Inline styles applied to the container div. */
+    style?: react__default.CSSProperties;
+}
+/**
+ * Imperative handle exposed via `React.forwardRef`.
+ * Provides direct access to the underlying DHTMLX Spreadsheet instance
+ * for operations that don't map to declarative props (export,
+ * programmatic selection, etc.).
+ */
+interface SpreadsheetRef {
+    /** The underlying DHTMLX Spreadsheet instance. `null` before init and after unmount. */
+    readonly instance: ISpreadsheet | null;
+}
+
+declare const ReactSpreadsheet: react.ForwardRefExoticComponent<SpreadsheetProps & react.RefAttributes<SpreadsheetRef>>;
+
+export { Actions, FilterConditions, ReactSpreadsheet, ReactSpreadsheet as default };
+export type { AfterActionHandler, AfterCellHandler, AfterEditHandler, AfterSheetHandler, BeforeActionHandler, BeforeCellHandler, BeforeEditHandler, BeforeSheetHandler, CellData, ColConfig, FileFormat, FreezeConfig, ICellInfo, IDataWithStyles, IExecuteConfig, IFilter, IFilterRules, IFormats, ISheet, ISpreadsheet, ISpreadsheetConfig, IStylesList, Id, MergedRange, RowConfig, SearchConfig, SheetData, SheetFilter, SheetSort, SpreadsheetConfigProps, SpreadsheetLocale, SpreadsheetProps, SpreadsheetRef, SpreadsheetTheme, ToolbarBlocks };