@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/commands.d.ts

@@ -0,0 +1,691 @@
+import type { CellData, CellInterface, Citation, Color, Direction, GridRange, SelectionArea, SheetRange, SortOrder } from "@rowsncolumns/common-types";
+import type { AXIS, BandedDefinition, BandedRange, BorderLocation, BorderStyle, CellFormat, ColorFilterCriteria, ConditionalFormatRule, ConditionType, ConditionValue, IconFilterCriteria, DataValidationRuleRecord, EmbeddedChart, EmbeddedObject, FilterView, NamedRange, PivotTable, ProtectedRange, SelectionAttributes, Sheet, Slicer, SpreadsheetTheme, TableTheme, TableView, TextFormatRun } from "@rowsncolumns/spreadsheet";
+import type { AutoFillType } from "./api/fill";
+import type { ChangeBatchOptions } from "./interface/change-batch";
+import type { ClearType } from "./interface/delete-cells";
+/**
+ * High-level operation issued by `useSpreadsheetState` whenever the user (or
+ * a programmatic caller) performs a meaningful action on the spreadsheet.
+ *
+ * Commands are emitted alongside `onChangeHistory` (which carries the
+ * low-level immer patches). They give a semantic, replayable description
+ * of intent that collaboration layers (e.g. y-spreadsheet v3) can apply
+ * to their own data structures without interpreting immer patches.
+ *
+ * Convention: the payload of each command **mirrors the arguments of the
+ * underlying handler's `useCallback`** verbatim, with a `command`
+ * discriminator added. So if a handler is `(sheetId, activeCell, selections)`,
+ * the command is `{ command, sheetId, activeCell, selections }`.
+ */
+export type Command = {
+    command: "set-value";
+    sheetId: number;
+    coords: CellInterface;
+    value: string;
+    textFormatRuns: TextFormatRun[] | undefined | null;
+    previousValue?: string | boolean | undefined;
+    isDirty?: boolean;
+} | {
+    command: "delete-cells";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    clearType?: ClearType;
+} | {
+    command: "change-batch";
+    sheetId: number;
+    ranges: GridRange[] | GridRange;
+    values: (string | boolean | number | null | undefined)[][] | string | boolean | number | null | undefined;
+    formatting?: (CellFormat | undefined | null)[][] | CellFormat | null | undefined;
+    citations?: (string | undefined | null)[][] | string | null | undefined;
+    options?: ChangeBatchOptions;
+} | {
+    command: "paste";
+    sheetId: number;
+    /** Destination top-left (the active cell at paste time). */
+    target: CellInterface;
+    /** Source top-left of the copied range — relative formula refs shift by (target − source). */
+    source: CellInterface;
+    /** The copied rectangle, row-major. Each cell carries its user-entered value (formula text or a
+     *  literal, as a string) plus optional format and optional hyperlink target (a pasted link
+     *  stays clickable); `null` = a blank cell within the copied range. */
+    cells: ({
+        value: string | null;
+        format?: CellFormat | null;
+        hyperlink?: string | null;
+    } | null)[][];
+    /** When the clipboard came from a CUT, the source range to clear after the paste lands. */
+    cut?: {
+        sheetId: number;
+        range: GridRange;
+    } | null;
+    /** Paste Special "formatting only": apply each cell's `format`, leave destination values intact. */
+    formatOnly?: boolean;
+} | {
+    command: "fill";
+    sheetId: number;
+    activeCell: CellInterface;
+    fillSelection: SelectionArea;
+    selections: SelectionArea<SelectionAttributes>[];
+    fillableSelections?: SelectionArea<SelectionAttributes>[];
+    fillType?: AutoFillType;
+} | {
+    command: "remove-duplicates";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    columnIndices?: number[];
+} | {
+    command: "split-text-to-columns";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    delimiter: string;
+} | {
+    command: "find-replace";
+    ranges: SheetRange[];
+    find: string;
+    replace: string;
+    matchCase?: boolean;
+    wholeWord?: boolean;
+    useRegex?: boolean;
+} | {
+    command: "change-formatting";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    cellFormat: CellFormat | undefined | null | (CellFormat | undefined | null)[][];
+    options?: {
+        replace?: boolean;
+    };
+} | {
+    command: "change-border";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    location: BorderLocation;
+    color: Color | undefined;
+    style: BorderStyle | undefined;
+} | {
+    command: "clear-formatting";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "change-decimals";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    type: "increment" | "decrement";
+} | {
+    command: "increase-indent";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "decrease-indent";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "change-indent";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    shouldIncrease: boolean;
+} | {
+    command: "insert-autosum";
+    sheetId: number;
+    activeCell: CellInterface;
+    /** Aggregate to insert (default `SUM`). The engine scans the contiguous numeric run above the
+     * cell — else to its left — and writes `=FN(range)` into the active cell. */
+    functionName?: "SUM" | "AVERAGE" | "COUNT" | "MAX" | "MIN";
+} | {
+    command: "set-effective-value";
+    sheetId: number;
+    coords: CellInterface;
+    /** The host-computed effective value (custom-formula / structured result, e.g. from
+     * `getEffectiveStructuredValue`) — an `ExtendedValue & StructuredValue`. The engine writes it
+     * verbatim onto the cell's `ev` (incl. `structuredValue`), feeds the scalar to dependents, and
+     * protects it from recalc until the cell is edited. The Option-B analog of `setEffectiveValue`. */
+    effectiveValue: NonNullable<CellData["ev"]>;
+} | {
+    command: "merge-cells";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    direction?: Direction;
+} | {
+    command: "unmerge-cells";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "insert-row";
+    sheetId: number;
+    referenceRowIndex: number;
+    numRows?: number;
+} | {
+    command: "insert-column";
+    sheetId: number;
+    referenceColumnIndex: number;
+    numColumns?: number;
+} | {
+    command: "delete-row";
+    sheetId: number;
+    rowIndexes: number[];
+} | {
+    command: "delete-column";
+    sheetId: number;
+    columnIndexes: number[];
+} | {
+    command: "move-rows";
+    sheetId: number;
+    rows: number[];
+    referenceRowIndex: number;
+} | {
+    command: "move-columns";
+    sheetId: number;
+    columns: number[];
+    referenceColumnIndex: number;
+} | {
+    command: "move-range";
+    sheetId: number;
+    from: GridRange;
+    to: GridRange;
+} | {
+    command: "hide-row";
+    sheetId: number;
+    rowIndexes: number[];
+} | {
+    command: "show-row";
+    sheetId: number;
+    rowIndexes: number[];
+} | {
+    command: "hide-column";
+    sheetId: number;
+    columnIndexes: number[];
+} | {
+    command: "show-column";
+    sheetId: number;
+    columnIndexes: number[];
+} | {
+    command: "group-rows";
+    sheetId: number;
+    rowIndexes: number[];
+} | {
+    command: "ungroup-rows";
+    sheetId: number;
+    rowIndexes: number[];
+} | {
+    command: "collapse-row-group";
+    sheetId: number;
+    summaryRowIndex: number;
+} | {
+    command: "expand-row-group";
+    sheetId: number;
+    summaryRowIndex: number;
+} | {
+    command: "group-columns";
+    sheetId: number;
+    columnIndexes: number[];
+} | {
+    command: "ungroup-columns";
+    sheetId: number;
+    columnIndexes: number[];
+} | {
+    command: "collapse-column-group";
+    sheetId: number;
+    summaryColumnIndex: number;
+} | {
+    command: "expand-column-group";
+    sheetId: number;
+    summaryColumnIndex: number;
+} | {
+    command: "set-outline-depth";
+    sheetId: number;
+    axis: "row" | "column";
+    depth: number;
+} | {
+    command: "resize";
+    sheetId: number;
+    indexes: number[];
+    dimension: number;
+    axis: AXIS;
+    autoFit?: boolean;
+} | {
+    command: "auto-resize";
+    sheetId: number;
+    indexes: number[];
+    axis: AXIS;
+    /** Measured fit sizes (px) per index, parallel to `indexes`. The renderer (CanvasGrid) measures
+     * with the real font (family/size/weight/glyph widths) and sends them; when present the engine
+     * applies them directly. Omitted → the engine falls back to a coarse character-count heuristic. */
+    sizes?: number[];
+} | {
+    command: "freeze-row";
+    sheetId: number;
+    rowIndex: number;
+} | {
+    command: "freeze-column";
+    sheetId: number;
+    columnIndex: number;
+} | {
+    command: "insert-cells-shift-down";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "insert-cells-shift-right";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "delete-cells-shift-up";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "delete-cells-shift-left";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "create-sheet";
+    sheetSpec?: Partial<Sheet>;
+} | {
+    command: "update-sheet";
+    sheetId: number;
+    sheetSpec: Partial<Sheet>;
+} | {
+    command: "delete-sheet";
+    sheetId: number;
+} | {
+    command: "rename-sheet";
+    sheetId: number;
+    name: string;
+    oldName: string;
+} | {
+    command: "move-sheet";
+    sheetId: number;
+    currentPosition: number;
+    newPosition: number;
+} | {
+    command: "duplicate-sheet";
+    sheetId: number;
+} | {
+    command: "hide-sheet";
+    sheetId: number;
+} | {
+    command: "show-sheet";
+    sheetId: number;
+} | {
+    command: "change-sheet-tab-color";
+    sheetId: number;
+    color: Color | undefined;
+} | {
+    command: "set-active-sheet";
+    sheetId: number;
+} | {
+    command: "sort-range";
+    sheetId: number;
+    selections: SelectionArea<SelectionAttributes>[];
+    sortOrder: SortOrder;
+} | {
+    command: "sort-column";
+    sheetId: number;
+    sortedColumnIndex: number;
+    sortOrder: SortOrder;
+} | {
+    command: "sort-table";
+    sheetId: number;
+    filter: TableView | FilterView;
+    dimensionIndex: number;
+    sortOrder: SortOrder;
+} | {
+    command: "filter-table";
+    sheetId: number;
+    filter: TableView | FilterView;
+    columnIndex: number;
+    conditionType: ConditionType | undefined;
+    conditionValue: ConditionValue[] | undefined;
+    visibleValues: string[] | undefined | null;
+    /** Filter-by-color criterion. Absent → carry the column's existing one; `null` → clear. */
+    colorFilter?: ColorFilterCriteria | null;
+    /** Filter-by-CF-icon criterion. Absent → carry the column's existing one; `null` → clear. */
+    iconFilter?: IconFilterCriteria | null;
+} | {
+    command: "delete-filter";
+    sheetId: number;
+    filter: TableView | FilterView;
+    columnIndex: number;
+} | {
+    command: "create-basic-filter";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    basicFilterSpec?: Partial<FilterView>;
+} | {
+    command: "create-table";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+    tableSpec?: Partial<TableView>;
+    theme?: TableTheme;
+    bandedRange?: BandedDefinition;
+} | {
+    command: "remove-table";
+    tableView: TableView;
+} | {
+    command: "update-table";
+    sheetId: number;
+    tableId: TableView["id"];
+    updatedTable: Partial<TableView>;
+} | {
+    command: "insert-table-row";
+    tableView: TableView;
+    relativeRowIndex?: number;
+    rowData?: Record<string, string | undefined | null>[];
+} | {
+    command: "delete-table-row";
+    tableView: TableView;
+    rowIndexes: number[];
+} | {
+    command: "insert-table-column";
+    tableView: TableView;
+    dimensionIndex: number;
+    direction: Direction.Left | Direction.Right;
+} | {
+    command: "delete-table-column";
+    tableView: TableView;
+    dimensionIndex: number;
+} | {
+    command: "resize-table";
+    sheetId: number;
+    table: TableView;
+    range: GridRange;
+} | {
+    command: "move-table-columns";
+    sheetId: number;
+    tableId: TableView["id"];
+    columns: number[];
+    referenceColumnIndex: number;
+} | {
+    command: "change-table-column";
+    sheetId: number;
+    tableId: TableView["id"];
+    columnIndex: number;
+    name: string;
+} | {
+    command: "calculated-column";
+    sheetId: number;
+    tableId: TableView["id"];
+    columnIndex: number;
+    formula: string;
+    fromRowIndex: number;
+} | {
+    command: "create-named-range";
+    sheetId: number;
+    namedRange: NamedRange;
+} | {
+    command: "update-named-range";
+    sheetId: number;
+    namedRange: NamedRange;
+    previousNamedRange: NamedRange;
+} | {
+    command: "delete-named-range";
+    namedRangeId: NamedRange["namedRangeId"];
+} | {
+    command: "update-note";
+    sheetId: number;
+    activeCell: CellInterface;
+    note?: string;
+} | {
+    command: "insert-comment";
+    sheetId: number;
+    rowIndex: number;
+    columnIndex: number;
+    commentThreadId: string | number | undefined;
+} | {
+    command: "remove-comment";
+    sheetId: number;
+    rowIndex: number;
+    columnIndex: number;
+} | {
+    command: "create-citation";
+    sheetId: number;
+    rowIndex: number;
+    columnIndex: number;
+    citation: Citation;
+} | {
+    command: "update-citation";
+    citationId: Citation["id"];
+    updates: Partial<Omit<Citation, "id">>;
+} | {
+    command: "delete-citation";
+    citationId: Citation["id"];
+} | {
+    command: "remove-citation-from-cell";
+    sheetId: number;
+    rowIndex: number;
+    columnIndex: number;
+} | {
+    command: "insert-checkbox";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "insert-link";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[] | undefined;
+    url: string;
+    title?: string;
+} | {
+    command: "remove-link";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections?: SelectionArea<SelectionAttributes>[];
+} | {
+    command: "insert-image";
+    sheetId: number;
+    activeCell: CellInterface;
+    imageUrl: string;
+    width: number;
+    height: number;
+    insertOverCells?: boolean;
+    embedId?: string | number;
+} | {
+    command: "create-conditional-format";
+    sheetId: number;
+    rule: ConditionalFormatRule;
+} | {
+    command: "update-conditional-format";
+    ruleId: string | number;
+    rule: Partial<ConditionalFormatRule>;
+} | {
+    command: "delete-conditional-format";
+    ruleId: string | number;
+} | {
+    command: "preview-conditional-format";
+    rule: ConditionalFormatRule | null;
+} | {
+    command: "create-data-validation";
+    sheetId: number;
+    range: SheetRange;
+    rule: DataValidationRuleRecord;
+} | {
+    command: "update-data-validation";
+    ruleId: string | number;
+    rule: Partial<DataValidationRuleRecord>;
+} | {
+    command: "delete-data-validation";
+    ruleId: string | number;
+} | {
+    command: "add-banded-range";
+    sheetId: number;
+    bandedRange: BandedRange;
+} | {
+    command: "remove-banded-range";
+    sheetId: number;
+    bandedRange: BandedRange;
+} | {
+    command: "protect-range";
+    sheetId: number;
+    activeCell: CellInterface;
+    selections: SelectionArea<SelectionAttributes>[] | undefined;
+} | {
+    command: "unprotect-range";
+    sheetId: number;
+    protectedRangeId: ProtectedRange["protectedRangeId"];
+} | {
+    command: "protect-sheet";
+    sheetId: number;
+} | {
+    command: "unprotect-sheet";
+    sheetId: number;
+} | {
+    command: "create-embed";
+    spec: EmbeddedObject;
+} | {
+    command: "update-embed";
+    embed: EmbeddedObject;
+} | {
+    command: "delete-embed";
+    embedId: EmbeddedObject["embedId"];
+} | {
+    command: "move-embed";
+    embedId: EmbeddedObject["embedId"];
+    sheetId: number;
+    anchorCell: CellInterface;
+    offsetXPixels: number;
+    offsetYPixels: number;
+} | {
+    command: "resize-embed";
+    embedId: EmbeddedObject["embedId"];
+    sheetId: number;
+    anchorCell: CellInterface;
+    offsetXPixels: number;
+    offsetYPixels: number;
+    width: number;
+    height: number;
+} | {
+    command: "create-slicer";
+    slicer: Slicer;
+} | {
+    command: "update-slicer";
+    slicer: Slicer;
+} | {
+    command: "delete-slicer";
+    slicerId: Slicer["slicerId"];
+} | {
+    command: "move-slicer";
+    slicerId: Slicer["slicerId"];
+    sheetId: number;
+    anchorCell: CellInterface;
+    offsetXPixels: number;
+    offsetYPixels: number;
+} | {
+    command: "resize-slicer";
+    slicerId: Slicer["slicerId"];
+    sheetId: number;
+    anchorCell: CellInterface;
+    offsetXPixels: number;
+    offsetYPixels: number;
+    width: number;
+    height: number;
+} | {
+    command: "change-theme";
+    theme: SpreadsheetTheme;
+} | {
+    command: "change-locale";
+    locale: string;
+} | {
+    command: "create-chart";
+    spec: EmbeddedChart;
+} | {
+    command: "update-chart";
+    chart: EmbeddedChart;
+} | {
+    command: "delete-chart";
+    chartId: EmbeddedChart["chartId"];
+} | {
+    command: "move-chart";
+    chartId: EmbeddedChart["chartId"];
+    sheetId: number;
+    anchorCell: CellInterface;
+    offsetXPixels: number;
+    offsetYPixels: number;
+} | {
+    command: "resize-chart";
+    chartId: EmbeddedChart["chartId"];
+    sheetId: number;
+    anchorCell: CellInterface;
+    offsetXPixels: number;
+    offsetYPixels: number;
+    width: number;
+    height: number;
+} | {
+    command: "create-pivot-table";
+    pivotTable: PivotTable;
+} | {
+    command: "update-pivot-table";
+    pivotId: PivotTable["pivotId"];
+    pivotTable: PivotTable;
+} | {
+    command: "delete-pivot-table";
+    pivotId: PivotTable["pivotId"];
+} | {
+    command: "refresh-pivot";
+    pivotId: PivotTable["pivotId"];
+} | {
+    command: "expand-pivot-row";
+    pivotId: PivotTable["pivotId"];
+    groupKeys: string[];
+} | {
+    command: "collapse-pivot-row";
+    pivotId: PivotTable["pivotId"];
+    groupKeys: string[];
+} | {
+    command: "expand-pivot-column";
+    pivotId: PivotTable["pivotId"];
+    path: (string | number | boolean | null)[];
+} | {
+    command: "collapse-pivot-column";
+    pivotId: PivotTable["pivotId"];
+    path: (string | number | boolean | null)[];
+} | {
+    command: "drill-down-pivot";
+    pivotId: PivotTable["pivotId"];
+    /** UI-resolved equality filters — optional when `cell` is given. */
+    filters?: Record<string, string | number | null | undefined>;
+    /** The clicked pivot output cell: the engine resolves the filters from
+     * its own computed layout (rnc-pivot drill-down). */
+    cell?: {
+        rowIndex: number;
+        columnIndex: number;
+    };
+} | {
+    command: "undo";
+} | {
+    command: "redo";
+} | {
+    command: "recalculate";
+};
+export type CommandType = Command["command"];
+/**
+ * Extract the payload type for a specific command.
+ *
+ * @example
+ * type SetValueCmd = CommandOf<"set-value">
+ */
+export type CommandOf<K extends CommandType> = Extract<Command, {
+    command: K;
+}>;
+/**
+ * Callback emitted by `useSpreadsheetState` whenever a high-level user
+ * intent is applied. Forward to the y-spreadsheet (or any other
+ * collaboration) hook for semantic-level sync.
+ */
+export type OnCommand = (command: Command) => void;
+//# sourceMappingURL=commands.d.ts.map