@rowsncolumns/spreadsheet-state 28.0.73 → 28.0.75

package/dist/esm/api/fill.d.ts

@@ -3,11 +3,73 @@ import type { GridRange } from "@rowsncolumns/common-types";
 import { Direction } from "@rowsncolumns/common-types";
 import type { SelectionAttributes } from "@rowsncolumns/spreadsheet";
 import type { CellData } from "@rowsncolumns/spreadsheet";
+import type { FillModifier, FillSeriesSpec } from "@rowsncolumns/spreadsheet";
 import type { CanvasGridProps } from "@rowsncolumns/spreadsheet";
 import type { Draft } from "immer";
 import type { CellXfsRegistry } from "../hooks/use-cellxfs-registry";
 import type { useSheetProperties } from "../hooks/use-sheet-properties";
-export type AutoFillType = "FillCopy" | "FillCustomList" | "FillDays" | "FillDefault" | "FillFormats" | "FillMonths" | "FillSeries" | "FillValues" | "FillWeekdays" | "FillYears" | "FlashFill" | "GrowthTrend" | "LinearTrend";
+export type AutoFillType = "FillCopy" | "FillCustomList" | "FillDays" | "FillDefault" | "FillFormats" | "FillHours" | "FillMonths" | "FillSeries" | "FillValues" | "FillWeekdays"
+/** Alias of Excel's `xlFillValues` under the Auto Fill Options label ("Fill Without Formatting"). */
+ | "FillWithoutFormatting" | "FillYears" | "FlashFill" | "GrowthTrend" | "LinearTrend";
+/**
+ * Resolve the Ctrl/Cmd fill-handle toggle the way Excel does — ONE fill type
+ * for the whole drag, decided from what auto-detection would have done per
+ * fill line (each column of a vertical fill / row of a horizontal one).
+ * If ANY line would extend a series (2+ numbers, a date, a list name,
+ * "Item 1"), the toggle means Copy Cells for every line; only when every
+ * line would copy (lone numbers) does it mean Fill Series. Formula lines
+ * never vote (formulas always copy with relative-ref adjustment) and empty
+ * lines are ignored.
+ */
+export declare const resolveToggledFillType: (detectedPerLine: (AutoFillType | undefined)[]) => AutoFillType;
+/**
+ * Excel's Auto Fill Options payload modifiers: "Fill Formatting Only" (`FillFormats`) and
+ * "Fill Without Formatting" (`FillWithoutFormatting`; `FillValues` is the VBA `xlFillValues`
+ * spelling the AI fill tool uses). Neither is a series mode — the series is detected exactly as
+ * for a plain drag; they only change WHAT lands in each target cell.
+ */
+export declare const isFormatsOnlyFillType: (fillType: AutoFillType | undefined) => fillType is "FillFormats";
+export declare const isValuesOnlyFillType: (fillType: AutoFillType | undefined) => fillType is "FillValues" | "FillWithoutFormatting";
+/**
+ * Thrown when a fill source is touched by merges that don't tile it with identically sized
+ * blocks — Excel refuses the fill with this exact message and writes nothing.
+ */
+export declare class MergedFillSizeError extends Error {
+    constructor();
+}
+/**
+ * Marks a target cell the fill leaves exactly as it is: a Series-dialog `stop` value was reached
+ * before the selection's end, and Excel writes nothing into the remaining selected cells.
+ */
+export declare const FILL_UNTOUCHED: unique symbol;
+export type AutoFillCellValue<T extends CellData> = T | string | number | null | undefined | Draft<T> | typeof FILL_UNTOUCHED;
+/** A seed cell rewritten by the fill (absolute coordinates on the sheet). */
+export type AutoFillSeedCell<T extends CellData> = {
+    rowIndex: number;
+    columnIndex: number;
+    cell: T;
+};
+/**
+ * The per-target-cell payload (indexed `[row][column]` relative to the filled area — the target
+ * rectangle beyond the source). A merged seed additionally reports the merge blocks to land and
+ * the fill extent snapped to whole blocks (the area `applyFill` actually writes). A Series-dialog
+ * Trend reports the seed cells it rewrites with the fitted values (Excel replaces the starting
+ * values) in `seedCells`.
+ */
+export type AutoFillResult<T extends CellData> = AutoFillCellValue<T>[][] & {
+    fillMerges?: GridRange[];
+    snappedFillBounds?: GridRange;
+    seedCells?: AutoFillSeedCell<T>[];
+};
+/**
+ * The merged-block geometry of a fill source: `undefined` when no merge touches it, the block
+ * size when identically sized merges tile it exactly (every merge inside the source, on the block
+ * lattice, and together covering it), else a {@link MergedFillSizeError}.
+ */
+export declare const resolveMergedFillBlock: (range: GridRange, merges: GridRange[] | null | undefined) => {
+    rows: number;
+    cols: number;
+} | undefined;
 /**
  * User-defined autofill lists. Each list is an array of strings that
  * the autofill engine treats as a cyclic sequence — e.g. starting from
@@ -36,6 +98,11 @@ export type GetAutoFillValuesProps<T extends CellData> = {
      * Area user is trying to fill
      */
     fillBounds: GridRange;
+    /**
+     * The sheet's merged ranges. A source tiled by identically sized merges fills block by block
+     * (each landed block merged like the seed); omit for plain per-cell fills.
+     */
+    merges?: GridRange[] | null;
     /**
      * Get cell data of a sheet
      */
@@ -61,6 +128,18 @@ export type GetAutoFillValuesProps<T extends CellData> = {
      * Auto fill type - if not specified, will auto-detect
      */
     fillType?: AutoFillType;
+    /**
+     * `"toggle"` when Ctrl/Cmd was held on the fill handle at release. Only
+     * consulted when `fillType` is not set: inverts the auto-detected
+     * copy↔series decision for the whole drag (see `resolveToggledFillType`).
+     */
+    modifier?: FillModifier;
+    /**
+     * Excel Series-dialog parameters. When present (and not `type:
+     * "autofill"`), the values come from the spec's generator — step/stop,
+     * trend, date unit — instead of the fill-type heuristics.
+     */
+    series?: FillSeriesSpec;
     /**
      * User-defined autofill lists. When the selection matches a
      * contiguous slice of one of these lists, the fill cycles through
@@ -72,6 +151,13 @@ export type GetAutoFillValuesProps<T extends CellData> = {
      */
     getDataValidationById?: ReturnType<typeof useSheetProperties>["getDataValidationById"];
 };
+/**
+ * Continue a text+number series ("Item 1" → "Item 2"; "001" → "002" keeps the
+ * zero padding; "1st Period" → "2nd Period" re-derives the ordinal). One seed
+ * steps by ±1 (by fill direction); two or more take the seeds' difference.
+ */
+export declare const generateTextNumberSeries: (values: string[], count: number, descending?: boolean) => string[] | null;
+export declare const generateQuarterSeries: (values: string[], count: number, descending?: boolean) => string[] | null;
 /**
  * Detect the fill type based on selection data
  */
@@ -79,10 +165,16 @@ export declare const detectFillType: (selectionData: (string | number | boolean
 /**
  * Generate fill values based on type and pattern
  */
-export declare const generateFillValues: (sourceValues: any[], fillType: AutoFillType, count: number, locale?: string, customAutofillLists?: CustomAutofillList[]) => any[];
+export declare const generateFillValues: (sourceValues: any[], fillType: AutoFillType, count: number, locale?: string, customAutofillLists?: CustomAutofillList[], 
+/**
+ * The fill walks away from the selection's start (fill up / fill left), so a
+ * single seed continues backwards: "Item 5" → "Item 4", Wednesday → Tuesday.
+ * Multi-seed lines already encode the direction in their reversed order.
+ */
+descending?: boolean) => any[];
 /**
  * Get auto fill values
  * @returns T[][]
  */
-export declare const getAutoFillValues: <T extends CellData>({ sheetId, direction, selection, fillBounds, getCellData, getEffectiveValue, getFormattedValue, getSheetName, getDataValidationById, cellXfsRegistry, locale, fillType, customAutofillLists, }: GetAutoFillValuesProps<T>) => Promise<(T | string | number | null | undefined | Draft<T>)[][]>;
+export declare const getAutoFillValues: <T extends CellData>({ sheetId, direction, selection, fillBounds, getCellData, getEffectiveValue, getFormattedValue, getSheetName, getDataValidationById, cellXfsRegistry, locale, fillType: requestedFillType, modifier, series, customAutofillLists, merges, }: GetAutoFillValuesProps<T>) => Promise<AutoFillResult<T>>;
 //# sourceMappingURL=fill.d.ts.map

package/dist/esm/api/fill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../api/fill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAEnC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,MAAM,MAAM,YAAY,GACpB,UAAU,GACV,gBAAgB,GAChB,UAAU,GACV,aAAa,GACb,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,cAAc,GACd,WAAW,GACX,WAAW,GACX,aAAa,GACb,aAAa,CAAC;AAElB;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,EAAE,CAAC;AAE1C,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,QAAQ,IAAI;IACvD;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC;IACrB;;OAEG;IACH,SAAS,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC9C;;OAEG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5D;;OAEG;IACH,iBAAiB,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACxE;;OAEG;IACH,iBAAiB,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACxE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC3C;;OAEG;IACH,qBAAqB,CAAC,EAAE,UAAU,CAChC,OAAO,kBAAkB,CAC1B,CAAC,uBAAuB,CAAC,CAAC;CAC5B,CAAC;AAqSF;;GAEG;AACH,eAAO,MAAM,cAAc,GACzB,eAAe,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC,EAAE,EAAE,EACxE,eAAa,EACb,sBAAsB,kBAAkB,EAAE,KACzC,YA6KF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,GAAG,EAAE,EACnB,UAAU,YAAY,EACtB,OAAO,MAAM,EACb,SAAS,MAAM,EACf,sBAAsB,kBAAkB,EAAE,KACzC,GAAG,EAqTL,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAU,CAAC,SAAS,QAAQ,EAAE,gMAczD,sBAAsB,CAAC,CAAC,CAAC,KAAG,OAAO,CACpC,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAyiBxD,CAAC"}
+{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../api/fill.ts"],"names":[],"mappings":"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"}