@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/autoFill/AutoFill.d.ts

@@ -1,46 +1,135 @@
-import { DateUnit } from '../date/_DateUtils';
+import { InteropScalarType } from '@sheetxl/primitives';
+import { DateUnit } from '../date/DateUtils';
 import { IAutoFill } from './IAutoFill';
-type JavaScriptDate = Date;
 export declare namespace AutoFill {
     /**
-     * DateFill implements IAutoFill.Filler to work with Dates.
+     * Fills date series. Values are spreadsheet SERIAL numbers, never JavaScript `Date` objects —
+     * a cell stores a date as a number, so filling one is arithmetic on that number and nothing has
+     * to be boxed and unboxed to run it.
+     *
+     * @remarks
+     * Which numbers are dates comes from {@link IAutoFill.Options.types}, because a serial is
+     * indistinguishable from any other number without the cell's format.
      */
-    class Date implements IAutoFill.Filler<JavaScriptDate> {
+    class Date implements IAutoFill.Filler<number> {
         private _options;
         constructor(options?: DateOptions);
+        /** {@inheritDoc IAutoFill.Filler.id} */
+        readonly id: string;
+        /** {@inheritDoc IAutoFill.Filler.type} */
+        readonly type: InteropScalarType;
+        /** {@inheritDoc IAutoFill.Filler.supportsStep} */
+        readonly supportsStep: boolean;
+        /** {@inheritDoc IAutoFill.Filler.supportsStop} */
+        readonly supportsStop: boolean;
         /**
-         * Returns `true` if the value is a valid `Date`.
+         * Claims every serial in the run — a date template that turns out NOT to be a series is
+         * repeated whole (Excel does the same), so it is never split into shorter ones.
          * @see
-         * {@link IAutoFill.Filler.canFill}
+         * {@link IAutoFill.Filler.matches}
          */
-        canFill(value: any, _prev: JavaScriptDate): boolean;
+        matches(values: readonly number[], from?: number): number;
         /** {@inheritDoc IAutoFill.Filler.createFillAt} */
-        createFillAt(values: readonly JavaScriptDate[], options?: DateOptions): IAutoFill.FillAt<JavaScriptDate> | null;
+        createFillAt(values: readonly number[], options?: DateOptions): IAutoFill.FillAt<number> | null;
     }
     /**
      * Adds additional fill options for Dates.
      */
     interface DateOptions extends IAutoFill.Options {
         /**
-         * If not provided the filler will attempt to determine.
-         * @defaultValue `The largest date unit found or day if one is not found.`
-         * // TODO - This doesn't support 'WeekDay'
+         * The unit each step counts, which is what makes a named date fill its own type.
+         *
+         * @defaultValue Read off the template, LARGEST unit first — years, month ends, months,
+         * weekdays, then the serial's own arithmetic (days, or hours for a bare time).
+         *
+         * @remarks
+         * {@link DateUnit.Weekday} is only ever read off a template that a plain day series can NOT
+         * explain: `Mon, Tue, Wed` is a one-day step, and so is `Fri, Mon` — Excel's three days —
+         * because two dates are always a plain step apart. `Fri, Mon, Tue` has no such reading and is a
+         * business-day series.
          */
         unit?: DateUnit;
+        /**
+         * Land every filled value on the last day of its month, rather than keeping the template's
+         * day-of-month.
+         *
+         * @defaultValue false — but a template whose values are ALL month ends is read as a month-end
+         * series anyway, so this is only needed to force one.
+         *
+         * @example
+         * `Jan 15` with `{ unit: Month, monthEnd: true }` fills `Jan 31, Feb 28, Mar 31` where the
+         * plain month fill gives `Feb 15, Mar 15`.
+         */
+        monthEnd?: boolean;
     }
     /**
-     * LinearFill implements IAutoFill.Filler to work with numbers.
-     * TODO - implements stepValue/stepTo
+     * Fills a straight numeric series — each value the previous one PLUS a step.
+     *
+     * @remarks
+     * The step is read off the template as a least-squares fit, so a template that only roughly
+     * trends still extends along its line. {@link IAutoFill.Options.stepValue} replaces that step
+     * outright, and {@link IAutoFill.Options.trend} keeps the fit while refusing any step at all.
      */
     class Linear implements IAutoFill.Filler<number> {
         private _options;
         constructor(options?: IAutoFill.Options);
+        /** {@inheritDoc IAutoFill.Filler.id} */
+        readonly id: string;
+        /** {@inheritDoc IAutoFill.Filler.type} */
+        readonly type: InteropScalarType;
+        /** {@inheritDoc IAutoFill.Filler.supportsStep} */
+        readonly supportsStep: boolean;
+        /** {@inheritDoc IAutoFill.Filler.supportsStop} */
+        readonly supportsStop: boolean;
+        /** {@inheritDoc IAutoFill.Filler.supportsTrend} */
+        readonly supportsTrend: boolean;
+        /**
+         * Claims the run of numbers — a numeric template is one series, however its values trend.
+         * @see
+         * {@link IAutoFill.Filler.matches}
+         */
+        matches(values: readonly number[], from?: number): number;
+        /** {@inheritDoc IAutoFill.Filler.createFillAt} */
+        createFillAt(values: readonly number[], options?: IAutoFill.Options): IAutoFill.FillAt<number> | null;
+    }
+    /**
+     * Fills a geometric series — each value the previous one MULTIPLIED by a ratio, where
+     * {@link Linear} adds.
+     *
+     * @remarks
+     * {@link IAutoFill.Options.stepValue} is that ratio, not an increment: `1` stepping by `2` fills
+     * `2, 4, 8, 16`. Nothing here is a special case — a ratio of `0` collapses the series to zeros,
+     * a negative one alternates the sign, and a zero anchor stays zero, all of which is just the
+     * multiplication.
+     *
+     * With {@link IAutoFill.Options.trend} the ratio is FITTED instead — a least-squares line
+     * through the logs of the values, which is a geometric curve through the values themselves.
+     *
+     * Never auto-detected: Excel offers growth only as an explicit choice, so this is not among the
+     * fillers {@link Types.Series} composes.
+     */
+    class Growth implements IAutoFill.Filler<number> {
+        private _options;
+        constructor(options?: IAutoFill.Options);
+        /** {@inheritDoc IAutoFill.Filler.id} */
+        readonly id: string;
+        /** {@inheritDoc IAutoFill.Filler.type} */
+        readonly type: InteropScalarType;
+        /** {@inheritDoc IAutoFill.Filler.supportsStep} */
+        readonly supportsStep: boolean;
+        /** {@inheritDoc IAutoFill.Filler.supportsStop} */
+        readonly supportsStop: boolean;
+        /** {@inheritDoc IAutoFill.Filler.supportsTrend} */
+        readonly supportsTrend: boolean;
         /**
-         * Returns `true` if the value is a valid number.
+         * Claims the run of numbers — but only one it could fill: with no ratio given (and no fit
+         * asked for) the numbers must already step by a constant ratio, or there is nothing to
+         * continue and the caller would only repeat them. `1, 2, 3, 4` is not offered a growth fill;
+         * `1, 2, 4, 8` and a lone `5` are.
          * @see
-         * {@link IAutoFill.Filler.canFill}
+         * {@link IAutoFill.Filler.matches}
          */
-        canFill(value: any, _prev: number): boolean;
+        matches(values: readonly number[], from?: number, options?: IAutoFill.Options): number;
         /** {@inheritDoc IAutoFill.Filler.createFillAt} */
         createFillAt(values: readonly number[], options?: IAutoFill.Options): IAutoFill.FillAt<number> | null;
     }
@@ -48,13 +137,18 @@ export declare namespace AutoFill {
      * Ordinal implements IAutoFill.Filler to handles Strings that have a Integer value.
      */
     class Ordinal implements IAutoFill.Filler<string> {
+        /** {@inheritDoc IAutoFill.Filler.id} */
+        readonly id: string;
+        /** {@inheritDoc IAutoFill.Filler.type} */
+        readonly type: InteropScalarType;
         private _template;
         /**
-         * Returns `true` if the value is a String that contains an Integer.
+         * Claims the leading run that shares one ordinal template, so `Test 1, Test 3, Wow 1` is two
+         * series rather than one.
          * @see
-         * {@link IAutoFill.Filler.canFill}
+         * {@link IAutoFill.Filler.matches}
          */
-        canFill(value: any, prev: string): boolean;
+        matches(values: readonly string[], from?: number): number;
         /** {@inheritDoc IAutoFill.Filler.createFillAt} */
         createFillAt(values: readonly string[], options?: IAutoFill.Options): IAutoFill.FillAt<string> | null;
     }
@@ -66,12 +160,14 @@ export declare namespace AutoFill {
      * being provided.
      */
     class Copy implements IAutoFill.Filler<any> {
+        /** {@inheritDoc IAutoFill.Filler.id} */
+        readonly id: string;
         /**
-         * Always returns `true`.
+         * Claims everything up to the last value that is not blank.
          * @see
-         * {@link IAutoFill.Filler.canFill}
+         * {@link IAutoFill.Filler.matches}
          */
-        canFill(_value: any, _prev: any): boolean;
+        matches(values: readonly any[], from?: number): number;
         /** {@inheritDoc IAutoFill.Filler.createFillAt} */
         createFillAt(values: readonly number[], _options?: IAutoFill.Options): IAutoFill.FillAt<number>;
     }
@@ -92,15 +188,21 @@ export declare namespace AutoFill {
      * being provided.
      */
     class List implements IAutoFill.Filler<string> {
+        /** {@inheritDoc IAutoFill.Filler.id} */
+        readonly id: string;
+        /** {@inheritDoc IAutoFill.Filler.type} */
+        readonly type: InteropScalarType;
         private _lists;
         private _map;
         constructor(options?: ListOptions);
         /**
-         * Always returns `true`.
+         * Claims the leading run whose values all belong to ONE list. A value can sit in several (`May`
+         * is in both the long and the short months), so the claim narrows the candidate lists as it
+         * goes and stops at the first value that leaves none.
          * @see
-         * {@link IAutoFill.Filler.canFill}
+         * {@link IAutoFill.Filler.matches}
          */
-        canFill(value: string, _prev: any): boolean;
+        matches(values: readonly string[], from?: number): number;
         /** {@inheritDoc IAutoFill.Filler.createFillAt} */
         createFillAt(values: readonly string[], options?: IAutoFill.Options): IAutoFill.FillAt<string> | null;
     }
@@ -108,21 +210,31 @@ export declare namespace AutoFill {
      * A specialized `Filler` that aggregates multiple `Filler` instances to handle various data types
      * during autofill operations.
      *
-     * It delegates the filling process to the first `Filler` in its collection whose `canFill` method
-     * returns `true` for the given value, enabling seamless autofill functionality for mixed data types within a range.
+     * It splits the template into series and hands each one to the first `Filler` in its collection
+     * that reads the segment's type and claims it, so a range holding several kinds of data — and
+     * several series of the same kind — fills as the sum of its parts.
      *
      * @remarks
      * This filler will also handle blanks.
      */
     class Composite<T = any> implements IAutoFill.Filler<T> {
         private _fillers;
-        constructor(fillers: IAutoFill.Filler | IAutoFill.Filler[]);
         /**
-         * Always returns `true`.
+         * The fillers that can be offered each value type, in registration order. Built once so a
+         * segment costs a lookup rather than a walk of every filler, and so a filler registered for
+         * two types keeps a separate priority in each.
+         */
+        private _byType;
+        constructor(fillers: IAutoFill.Filler | IAutoFill.Filler[], id?: string);
+        /** {@inheritDoc IAutoFill.Filler.id} */
+        readonly id: string;
+        /**
+         * Claims everything up to the last value that is not blank — a Composite splits the template
+         * into series itself rather than handing part of it back.
          * @see
-         * {@link IAutoFill.Filler.canFill}
+         * {@link IAutoFill.Filler.matches}
          */
-        canFill(_value: T, _prev: T): boolean;
+        matches(values: readonly T[], from?: number, options?: IAutoFill.Options): number;
         /** {@inheritDoc IAutoFill.Filler.createFillAt} */
         createFillAt(values: readonly T[], options?: IAutoFill.Options): IAutoFill.FillAt<T>;
     }
@@ -135,10 +247,28 @@ export declare namespace AutoFill {
          * This attempts to fill use `Dates`, `Linear`, `Ordinal`, then `List`.
          */
         readonly Series: Composite<any>;
+        /**
+         * Fills a straight numeric series — the step read from the template, or given outright.
+         */
+        readonly Linear: Linear;
+        /**
+         * Fills a geometric series — each value the previous one times a ratio.
+         */
+        readonly Growth: Growth;
         /**
          * Fills using individual days.
          */
         readonly DateDays: Date;
+        /**
+         * Fills business days, skipping Saturday and Sunday.
+         *
+         * @remarks
+         * A template that only a business-day series explains — `Fri, Mon, Tue` — fills this way under
+         * {@link Series} too; this is for asking for it outright, from a template a plain day series
+         * would otherwise account for. A weekend anchor is taken rather than refused: the fill means
+         * "give me business days from here".
+         */
+        readonly DateWeekdays: Date;
         /**
          * Fills using months.
          */
@@ -147,15 +277,169 @@ export declare namespace AutoFill {
          * Fills using years.
          */
         readonly DateYears: Date;
+        /**
+         * Fills month by month, landing on the last day of each.
+         *
+         * @remarks
+         * A template already on month ends fills this way under {@link Series} too — this is for
+         * asking for it outright, from a day-of-month the template does not otherwise imply.
+         */
+        readonly DateMonthEnd: Date;
         /**
          * Fills with a repeating values.
          */
         readonly Copy: Copy;
     };
+    /**
+     * The fills that can be OFFERED to a user — the entries of a fill menu or a Series type list.
+     *
+     * @remarks
+     * These are {@link IAutoFill.Preset}s, not fillers: the same filler appears under several of
+     * them with different options. Ids are stable and are what a menu entry, a script, or a
+     * transaction's operation params name; display labels are localized against the id.
+     *
+     * Which of these to show for a given selection is {@link canApply}.
+     */
+    const Presets: {
+        /** Repeat the template, filling nothing. Excel's `Copy Cells`. */
+        readonly Copy: {
+            readonly id: "copy";
+            readonly filler: Copy;
+        };
+        /** Read the series off the template. Excel's `Fill Series` / the Series dialog's `AutoFill`. */
+        readonly Series: {
+            readonly id: "series";
+            readonly filler: Composite<any>;
+        };
+        /** A straight numeric series. */
+        readonly Linear: {
+            readonly id: "linear";
+            readonly filler: Linear;
+        };
+        /** A geometric series — the step is a ratio. */
+        readonly Growth: {
+            readonly id: "growth";
+            readonly filler: Growth;
+        };
+        /** Year by year. */
+        readonly DateYears: {
+            readonly id: "date.years";
+            readonly filler: Date;
+        };
+        /** Month by month, landing on the last day of each. */
+        readonly DateMonthEnd: {
+            readonly id: "date.monthEnd";
+            readonly filler: Date;
+        };
+        /** Month by month, keeping the day where the month is long enough. */
+        readonly DateMonths: {
+            readonly id: "date.months";
+            readonly filler: Date;
+        };
+        /** Business day by business day, skipping weekends. */
+        readonly DateWeekdays: {
+            readonly id: "date.weekdays";
+            readonly filler: Date;
+        };
+        /** Day by day. */
+        readonly DateDays: {
+            readonly id: "date.days";
+            readonly filler: Date;
+        };
+        /**
+         * A straight numeric series FITTED to the template rather than stepped from it.
+         *
+         * @remarks
+         * A fit needs two points, which is why Excel greys `Linear Trend` on a single cell and offers
+         * `Fill Days` there. The arity belongs to the option, not to {@link Types.Linear}, which fills
+         * a single value happily enough without it.
+         */
+        readonly LinearTrend: {
+            readonly id: "linear.trend";
+            readonly filler: Linear;
+            readonly options: {
+                readonly trend: true;
+            };
+            readonly minValues: 2;
+        };
+        /** A geometric series fitted to the template — the same fit, run on the logs. */
+        readonly GrowthTrend: {
+            readonly id: "growth.trend";
+            readonly filler: Growth;
+            readonly options: {
+                readonly trend: true;
+            };
+            readonly minValues: 2;
+        };
+    };
+    /**
+     * Whether `preset` can be offered for a selection holding these value types.
+     *
+     * @param types The type of each value in the selection, `Null` for a blank.
+     *
+     * @remarks
+     * Three checks, and between them they account for every state Excel's fill menu shows:
+     * * **Type** — a filler is offered only where the values are the type it reads. This is what
+     *   greys `Fill Months` on a numeric selection, and `Linear Trend` on a date one.
+     * * **Arity** — {@link IAutoFill.Preset.minValues} against the non-blank count. This is what
+     *   greys `Linear Trend` on a single cell.
+     * * **Claim** — {@link IAutoFill.Filler.matches}. This is what greys `Fill Series` on `abc,
+     *   def` while leaving `Copy Cells` alone: nothing recognizes a series there, so the fill would
+     *   be a copy by another name.
+     *
+     * A filler's `matches` therefore has to answer *could you fill from this if asked*, which is
+     * NOT always *is this template already a series of my kind*. The two come apart for a filler
+     * that is never auto-detected: `Fill Weekdays` should be offered for a template of two weekend
+     * dates — it means "give me business days from here", and the engine happily takes a Saturday
+     * anchor — even though those two dates are not a weekday series. A filler outside
+     * {@link Types.Series}'s composite is only ever asked on the explicit path, so it should claim
+     * permissively.
+     */
+    const canApply: (preset: IAutoFill.Preset, values: readonly any[], types: readonly InteropScalarType[]) => boolean;
+    /**
+     * The preset registered under `id`, or `undefined` for one that is not.
+     *
+     * @remarks
+     * An id is what a surface, a script, or a transaction's {@link ITransaction.Operation.params}
+     * names a fill type by — it survives a round trip where a filler instance would not — so
+     * something has to resolve one again.
+     */
+    const getPreset: (id: string) => IAutoFill.Preset | undefined;
+    /**
+     * The preset that best DESCRIBES a template — what a Series dialog opens on, and what a caller
+     * asking "what is this?" is told.
+     *
+     * @param types The type of each value, `Null` for a blank — without which a serial date is
+     * indistinguishable from any other number.
+     *
+     * @remarks
+     * This is the opposite question from {@link canApply}, which asks whether a NAMED fill could be
+     * applied. Here the template names itself: a date series at its largest unit (see
+     * {@link IAutoFill.DateSeries}), a numeric one as {@link Presets.Linear}, and text as
+     * {@link Presets.Series} — reading the series off the template is the best guess text can be
+     * given, and is what makes `test 1, test 2` and `Jan, Feb` fill as series rather than repeat.
+     * Only values nothing recognizes fall through to {@link Presets.Copy}.
+     *
+     * The answer is not checked against the selection — a caller offering it should fall back to a
+     * preset {@link canApply} allows.
+     */
+    const detectPreset: (values: readonly any[], types: readonly InteropScalarType[], options?: IAutoFill.Options) => IAutoFill.Preset;
+    /**
+     * The `filler` and `fillerOptions` a chosen preset and a surface's own settings amount to — what
+     * {@link ICellRange.autoFill} is handed.
+     *
+     * @remarks
+     * A fit refuses a step and a stop, and a filler that cannot fit refuses the fit itself, so
+     * neither is passed where it means nothing — a surface hiding those fields makes that *displayed*
+     * where this makes it true.
+     */
+    const toFillOptions: (preset: IAutoFill.Preset, options?: IAutoFill.Options) => {
+        filler: IAutoFill.Filler;
+        fillerOptions: IAutoFill.Options;
+    };
     /**
      * Simple methods that builds an array from a Filler.
      */
     const fillTo: <T>(filler: IAutoFill.Filler, values: T[], to: number, options?: IAutoFill.Options) => T[];
 }
-export {};
 //# sourceMappingURL=AutoFill.d.ts.map