@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.2

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

@@ -1,3 +1,5 @@
+import { InteropScalarType, IRange } from '@sheetxl/primitives';
+import { DateUnit } from '../date/DateUtils';
 /**
  * The `IAutoFill` namespace provides capabilities for applying and managing auto-fill operations
  * within a spreadsheet. Auto-fill enables automatic generation of data based on patterns in existing data.
@@ -30,17 +32,80 @@ export declare namespace IAutoFill {
      */
     interface Filler<T = any> {
         /**
-         * Determines if the Filler can add value to the current fill.
+         * Identifies the filler. Must be unique among the fillers in use.
          *
-         * @param value The value to test. Can be any type or `null`.
-         * @param prev The previous value in the candidate set that is not a null. This is `undefined` for the first element.
-         * @returns `true` if the value should be added.
+         * @remarks
+         * This is what names the fill in a menu, survives into a transaction's
+         * {@link ITransaction.Operation.params}, and lets a script ask for a fill type by name — so it
+         * is a stable key, not a display label.
+         */
+        readonly id: string;
+        /**
+         * The value type this filler reads.
+         *
+         * @remarks
+         * * The filler is only ever offered values of this type — a claim that runs past the type is
+         *   trimmed back, so {@link matches} does not have to re-check what the caller already knows.
+         *   Blanks carry no type and never split a series.
+         * * Leave it `undefined` to be offered a segment of ANY type (still one type at a time).
+         * * Dates are {@link InteropScalarType.Date}: cell values are serial numbers, and it is the
+         *   cell's number format — not the runtime type — that makes one a date.
+         * * A filler that reads more than one type registers once per type; where it sits in each
+         *   {@link Composite}'s list is its priority for that type.
+         */
+        readonly type?: InteropScalarType;
+        /**
+         * How many values starting at `from` this filler claims as ONE series, or `0` for none.
+         *
+         * @param values The whole segment. Treat as readonly.
+         * @param from The first value to consider.
+         * @param options The options the fill would run with — notably {@link Options.types}, without
+         * which a serial date is indistinguishable from any other number.
+         *
+         * @remarks
+         * * Blanks inside a claim are gaps in the series, not terminators; trailing blanks are left
+         *   out of the count.
+         * * A claim is trimmed to the run of values matching {@link type}, so it is safe to simply
+         *   claim as far as the series goes.
+         * * A template may hold several series of the same type — `Test 1, Test 3, Wow 1` is two —
+         *   so returning the length lets the caller resolve the whole template in one pass rather
+         *   than growing a run and re-asking.
+         * * Claiming a segment is not a promise to fill it: {@link createFillAt} may still decide the
+         *   values are not a series and return `null`.
+         */
+        matches: (values: readonly T[], from?: number, options?: IAutoFill.Options) => number;
+        /**
+         * Whether {@link Options.stepValue} means anything to this filler.
+         *
+         * @defaultValue false — the field is hidden.
+         *
+         * @remarks
+         * These three say only which fields an authoring surface should OFFER; they say nothing about
+         * whether the filler can be applied to a given selection (see {@link Preset}). The step's
+         * meaning is the filler's own — an addend for a linear series, a RATIO for a growth one, a
+         * count of units for a date one — so the value is passed through uninterpreted.
+         */
+        readonly supportsStep?: boolean;
+        /**
+         * Whether {@link Options.stopValue} means anything to this filler.
+         *
+         * @defaultValue false — the field is hidden.
+         *
+         * @remarks
+         * Only an ordered series can be stopped; a list or an ordinal one has nothing to compare.
+         */
+        readonly supportsStop?: boolean;
+        /**
+         * Whether this filler can fit its series to the values rather than stepping from them
+         * ({@link Options.trend}).
+         *
+         * @defaultValue false — the field is hidden.
          *
          * @remarks
-         * * The fill array should be treated as readonly.
-         * * The value may be any type and should return `false` if it's not supported.
+         * A fit needs at least two values, so a preset that turns it on carries that arity — see
+         * {@link Preset.minValues}.
          */
-        canFill: (value: any, prev: any | undefined) => boolean;
+        readonly supportsTrend?: boolean;
         /**
          * Create a {@link IAutoFill.FillAt} function using the provided values and options.
          *
@@ -50,6 +115,110 @@ export declare namespace IAutoFill {
          */
         createFillAt: (values: readonly T[], options?: IAutoFill.Options) => FillAt<T> | null;
     }
+    /**
+     * A named fill a user can be OFFERED — a {@link Filler} plus the options that configure it.
+     *
+     * @remarks
+     * A menu entry is not a filler. `Fill Days` is the date filler with no options; `Linear Trend`
+     * is the linear filler with {@link Options.trend} on. The same filler appears under several
+     * presets, and they do not all apply to the same selection: a growth series steps from a single
+     * value, where a growth *trend* needs two to fit.
+     *
+     * @see {@link AutoFill.canApply} — whether a preset can be offered for a given selection.
+     */
+    interface Preset {
+        /**
+         * Stable id — what a menu entry, a script, or a transaction's
+         * {@link ITransaction.Operation.params} names. Not a display label; those are localized
+         * against this id.
+         */
+        readonly id: string;
+        /** The filler this preset drives. */
+        readonly filler: Filler;
+        /** Options applied on top of the caller's own. */
+        readonly options?: Options;
+        /**
+         * The fewest non-blank values the preset can work from.
+         *
+         * @defaultValue 1
+         *
+         * @remarks
+         * A trend has to fit a line through the values, so it needs two — which is why Excel greys
+         * `Linear Trend` on a single cell but offers `Fill Days` there.
+         */
+        readonly minValues?: number;
+    }
+    /**
+     * What a date template turns out to be a series OF — see {@link AutoFill.Date}.
+     *
+     * @remarks
+     * A template is read at its LARGEST unit: `Jan 2020, Jan 2021` is a year series and not the
+     * twelve-month one it also is, which is what a surface has to name it as.
+     */
+    interface DateSeries {
+        /** The unit each step counts. */
+        readonly unit: DateUnit;
+        /**
+         * A month series whose values all fall on their month's LAST day — `Jan 31, Feb 28, Mar 31`,
+         * which continues `Apr 30` rather than `Apr 28`.
+         */
+        readonly monthEnd: boolean;
+    }
+    /**
+     * The default fill a selection implies — which cells it would read, which it would cover, the
+     * types that can be offered for it, and the one to open on.
+     *
+     * @see {@link ICellRange.getDefaultAutoFillCriteria}, which answers this for a range.
+     */
+    interface DefaultCriteria {
+        /**
+         * Which way the series runs — the direction asked for, or the one the range's own shape implies.
+         *
+         * @remarks
+         * A single row runs across and anything else runs down, which is Excel's own default; a block
+         * says nothing either way, so a surface still offers the choice rather than only reporting it.
+         */
+        readonly direction: IRange.Direction;
+        /**
+         * The cells the series is read from — the range's leading CONTENTFUL run along `direction`.
+         *
+         * @remarks
+         * Excel seeds from the first cell alone and overwrites everything after it. Taking the leading
+         * run instead is what lets a template say something: `1, 5` continues `9, 13, 17` where a
+         * one-cell template can only copy. A run covering the whole range would leave nothing to fill,
+         * so it falls back to the first line — which is how a column of values gets renumbered.
+         *
+         * Asked with a destination — the fill handle's drag — the template is the whole range as it is,
+         * blanks included, because the drag already said what to read.
+         */
+        readonly template: IRange.Coords;
+        /** The cells the fill covers — the range itself, or the destination that was asked about. */
+        readonly destination: IRange.Coords;
+        /** How many cells deep `template` is along `direction`. */
+        readonly templateSize: number;
+        /** How many cells deep `destination` is along `direction` — the template included. */
+        readonly size: number;
+        /**
+         * The {@link Preset.id}s that can be offered, in registry order.
+         *
+         * @remarks
+         * A preset is offered when it applies to ANY line of the range: a column of dates beside a
+         * column of numbers offers the date fills, and the numeric column falls back to a copy rather
+         * than the entry being greyed for both. WHICH of them a surface lists is its own business — a
+         * Series dialog carrying a Trend checkbox leaves the trend presets out.
+         */
+        readonly offered: readonly string[];
+        /**
+         * The {@link Preset.id} to open on — what the range's leading line already reads as.
+         *
+         * @remarks
+         * A date series is named at its largest unit ({@link DateSeries}), a numeric one is `linear`,
+         * and text falls to `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. Only a selection
+         * nothing recognizes falls through to `copy`, which is the honest answer there.
+         */
+        readonly presetId: string;
+    }
     /**
      * Represents a callback function that provides the filled value at a given offset
      * within a one-dimensional sequence (either a row or a column).
@@ -65,26 +234,74 @@ export declare namespace IAutoFill {
      */
     interface Options {
         /**
-         * Override the default increment or step value used when generating a fill.
-         * * The default it to use the existing values to determine.
+         * The type of each value, parallel to the values being filled.
+         *
+         * @remarks
+         * * Supplied by the caller because the runtime type cannot always answer it: a date is a
+         *   serial NUMBER, and only the cell's number format says so.
+         * * When omitted the type is read off each value instead, which is right for everything but
+         *   dates.
+         */
+        types?: readonly InteropScalarType[];
+        /**
+         * Whether serial dates in `values` are on the 1904 epoch.
+         *
+         * @defaultValue false
+         */
+        date1904?: boolean;
+        /**
+         * The increment between values, replacing the one the template implies.
+         *
+         * @defaultValue The step read from the existing values.
          *
          * @remarks
-         * **NOT IMPLEMENTED**
+         * * What a step MEANS is the filler's own: an addend for a linear series, a RATIO for a growth
+         *   one, a count of whatever unit a date type names. The value is passed through
+         *   uninterpreted, so only offer the field where {@link Filler.supportsStep} says to.
+         * * It counts from the LAST value of the template, not the first — an outright step replaces
+         *   the series the template implies rather than re-deriving it, so `1, 5` stepping by `2`
+         *   continues `7, 9, 11` instead of restarting `3, 5, 7` over a `5` already on the sheet. A
+         *   one-value template makes this the first value, which is what Excel's Series dialog does
+         *   with any selection.
          *
          * @example
-         * For `AutoFill.LinearFill` customize the increment between consecutive numbers
-         * in a series (e.g., 1, 3, 5 with `stepValue: 2`).
+         * `1` with `stepValue: 2` fills `3, 5, 7`; with `stepValue: -2` it fills `-1, -3, -5`.
          */
         stepValue?: number;
         /**
-         * The stopping value for autofill operations that generate a fill.
+         * The value at which the series stops.
+         *
+         * @defaultValue Unbounded — the fill covers the whole destination.
          *
          * @remarks
-         * **NOT IMPLEMENTED**
+         * * Cells past the stop are left **blank**, not clamped to it.
+         * * "Past" is judged in the direction the series travels, which comes from the series and not
+         *   from the sign of the stop. A stop sitting BEHIND the travel ends it at once and fills
+         *   nothing — `1` stepping by `2` toward a stop of `-5`.
          *
-         * - Allow users to specify the maximum value up to which the autofill series should continue.
+         * @example
+         * `1` with `stepValue: 2, stopValue: 7` fills `3, 5, 7` and then blanks.
          */
         stopValue?: number;
+        /**
+         * Fit the series to the template rather than stepping from it — a least-squares line for
+         * {@link AutoFill.Linear}, and the same fit on the logs for {@link AutoFill.Growth}.
+         *
+         * @defaultValue false — the series is stepped.
+         *
+         * @remarks
+         * * A fit is over the WHOLE template at the values' own positions, so it needs at least two of
+         *   them and a filler that cannot manage one declines (leaving the caller to repeat the
+         *   template). {@link Preset.minValues} carries that arity where a fill is offered.
+         * * {@link stepValue} and {@link stopValue} mean nothing to a fit and are ignored — an
+         *   authoring surface should hide both while this is on, which is what Excel's Series dialog
+         *   does with them.
+         * * Only offer the field where {@link Filler.supportsTrend} says to.
+         *
+         * @example
+         * `1, 2, 4` fills `5.33, 6.83, 8.33` linearly, and `8, 16, 32` as a growth trend.
+         */
+        trend?: boolean;
         /**
          * Indicates whether there is adjacent span with a different fill type.
          *

package/types/src/border/{IBorder.d.ts → IBorders.d.ts}

@@ -1,7 +1,7 @@
 import { IProperties } from '../type';
 import { IColor } from '../color';
 import { IStyle } from '../style';
-export declare namespace IBorder {
+export declare namespace IBorders {
     /**
      * @remarks
      * This is a limited implementation of border that matches OOXMl and Excel.
@@ -39,7 +39,7 @@ export declare namespace IBorder {
          * `horizontal` and `vertical` are **inner** rules: they are stored on the authored block and
          * decomposed into per-cell top/left/bottom/right when a single cell is read — a cell has no
          * inside, so at cell scope they are always null. Read them back at the scope they were
-         * written at, via {@link IBorder.getHorizontal} / {@link IBorder.getVertical} on a range.
+         * written at, via {@link IBorders.getHorizontal} / {@link IBorders.getVertical} on a range.
          */
         readonly Horizontal: "horizontal";
         /**
@@ -66,18 +66,18 @@ export declare namespace IBorder {
          *
          * @param style The stroke style.
          */
-        setStyle(style: IBorder.StrokeStyle | string | null, options?: IStyle.UpdateOptions): IBorder.IStroke;
+        setStyle(style: IBorders.StrokeStyle | string | null, options?: IStyle.UpdateOptions): IBorders.IStroke;
         getColor(): IColor;
         /**
          * Sets the stroke color.
          *
          * @param color The stroke color.
          */
-        setColor(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IBorder.IStroke;
+        setColor(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IBorders.IStroke;
         /**
          * Returns all the set properties and their values for the border.
          */
-        getProperties(): IBorder.StrokeProperties;
+        getProperties(): IBorders.StrokeProperties;
         /**
          * Returns a set of CSSStyleDeclaration that approximate the stroke.
          */
@@ -92,95 +92,96 @@ export declare namespace IBorder {
         readonly isIStroke: true;
     }
     interface StrokeProperties<C = IColor.Serializable> {
-        style?: IBorder.StrokeStyle;
+        style?: IBorders.StrokeStyle;
         color?: C;
     }
     interface StrokeJSON {
-        style?: IBorder.StrokeStyle;
+        style?: IBorders.StrokeStyle;
         color?: string;
     }
     type Properties = {
-        [key in IBorder.Edge]?: IBorder.StrokeProperties;
+        [key in IBorders.Edge]?: IBorders.StrokeProperties;
     };
     /**
      * Modifiers describe a partial list of properties that can be set with values or shorthand strings.
      */
-    type Modifiers = Partial<IBorder.Properties>;
+    type Modifiers = Partial<IBorders.Properties>;
     /**
      * Options for updating a border.
      */
-    type Update = IBorder | Modifiers | string | null;
+    type Update = IBorders | Modifiers | string | null;
     /**
      * JSON representation of a border.
      */
     type JSON = {
-        [key in IBorder.Edge]?: IBorder.StrokeJSON;
+        [key in IBorders.Edge]?: IBorders.StrokeJSON;
     };
 }
 /**
- * Provides information for describing a border around a shape.
+ * The borders of a cell or a range: the four outer edges, the two diagonals, and the inner
+ * horizontal and vertical rules between the cells of a range.
  */
-export interface IBorder {
+export interface IBorders {
     /**
      * @returns The left border.
      */
-    getLeft(): IBorder.IStroke;
+    getLeft(): IBorders.IStroke;
     /**
      * Sets the left border.
      *
      * @param stroke The border stroke.
      */
-    setLeft(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setLeft(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * @returns The top border.
      */
-    getTop(): IBorder.IStroke;
+    getTop(): IBorders.IStroke;
     /**
      * Sets the top border.
      *
      * @param stroke The border stroke.
      */
-    setTop(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setTop(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * @returns The right border.
      */
-    getRight(): IBorder.IStroke;
+    getRight(): IBorders.IStroke;
     /**
      * Sets the right border.
      *
      * @param stroke The border stroke.
      */
-    setRight(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setRight(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * @returns The bottom border.
      */
-    getBottom(): IBorder.IStroke;
+    getBottom(): IBorders.IStroke;
     /**
      * Sets the bottom border.
      *
      * @param stroke The border stroke.
      */
-    setBottom(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setBottom(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * @returns The diagonalUp border.
      */
-    getDiagonalUp(): IBorder.IStroke;
+    getDiagonalUp(): IBorders.IStroke;
     /**
      * Sets the diagonalUp border.
      *
      * @param stroke The border stroke.
      */
-    setDiagonalUp(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setDiagonalUp(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * @returns The diagonalDown border.
      */
-    getDiagonalDown(): IBorder.IStroke;
+    getDiagonalDown(): IBorders.IStroke;
     /**
      * Sets the diagonalDown border.
      *
      * @param stroke The border stroke.
      */
-    setDiagonalDown(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setDiagonalDown(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * The inner vertical rule — the border *between* columns, not around them.
      *
@@ -193,7 +194,7 @@ export interface IBorder {
      *
      * - the border was materialized from a **cell** (or a 1-column range) — a cell has no inside;
      * - the queried range is **not covered by a single authored border block**, so there is no one
-     *   answer — re-query a range that is, or partition with `getRegions('border')` to find one;
+     *   answer — re-query a range that is, or partition with `getRegions('borders')` to find one;
      * - **no inner rule is authored.** Authoring `None` deletes the property rather than storing
      *   it, so "explicitly none" and "never set" are the same stored state and cannot be told
      *   apart — by design, not by omission.
@@ -201,7 +202,7 @@ export interface IBorder {
      * The edges (`getLeft`/`getRight`/…) are unaffected: a cell read still decomposes an inner
      * rule into the per-cell edges it produces, which is what a cell actually carries.
      */
-    getVertical(): IBorder.IStroke | null;
+    getVertical(): IBorders.IStroke | null;
     /**
      * Sets the vertical borders for the range
      *
@@ -211,15 +212,15 @@ export interface IBorder {
      * @remarks
      * This has no effect on a 1x1 range or cell.
      */
-    setVertical(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setVertical(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * The inner horizontal rule — the border *between* rows, not around them.
      *
      * @returns The authored inner stroke, or `null` when there is none to report.
      *
-     * @see {@link IBorder.getVertical} for when `null` is returned.
+     * @see {@link IBorders.getVertical} for when `null` is returned.
      */
-    getHorizontal(): IBorder.IStroke | null;
+    getHorizontal(): IBorders.IStroke | null;
     /**
      * Sets the horizontal borders for the range
      *
@@ -229,42 +230,42 @@ export interface IBorder {
      * @remarks
      * This has no effect on a 1x1 range or cell.
      */
-    setHorizontal(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setHorizontal(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * Sets the border outline for the range
      * @param stroke The border stroke.
      * @param options Update options.
      */
-    setOutline(stroke: IBorder.IStroke | IProperties.ResolvableProperties<IBorder.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorder;
+    setOutline(stroke: IBorders.IStroke | IProperties.ResolvableProperties<IBorders.StrokeProperties> | string | null, options?: IStyle.UpdateOptions): IBorders;
     /**
      * If there are any borders that are not none.
      */
     isEmpty(): boolean;
-    toJSON(): IBorder.JSON;
+    toJSON(): IBorders.JSON;
     /**
      * Returns all the set properties and their values for the border.
      */
-    getProperties(): IBorder.Properties;
+    getProperties(): IBorders.Properties;
     /**
      * List of customizations modifiers for the border.
      */
     /**
      * For runtime type checking.
      */
-    readonly isIBorder: true;
+    readonly isIBorders: true;
 }
 /**
- * {@inheritDoc IBorder}
+ * {@inheritDoc IBorders}
  * @see
  * ### **Interface**
  *
- * {@link IBorder}
+ * {@link IBorders}
  */
-export declare namespace IBorder {
+export declare namespace IBorders {
     /**
      * Compare two strokes for logical equality.
      */
-    function isEqualStrokes(a: IBorder.IStroke, b: IBorder.IStroke): boolean;
+    function isEqualStrokes(a: IBorders.IStroke, b: IBorders.IStroke): boolean;
     /**
      * Returns the opposite border edge. This only works for Left,Right,Top,Bottom
      * all other edges return themselves.
@@ -281,4 +282,4 @@ export declare namespace IBorder {
      */
     const BuiltInDefinitions: Map<StrokeStyle, Definition>;
 }
-//# sourceMappingURL=IBorder.d.ts.map
+//# sourceMappingURL=IBorders.d.ts.map

package/types/src/border/index.d.ts

@@ -1,2 +1,2 @@
-export * from './IBorder';
+export * from './IBorders';
 //# sourceMappingURL=index.d.ts.map