@sheetxl/sdk 0.8.0-beta.7 → 0.8.0-beta.9

package/types/src/condition/ICondition.d.ts

@@ -59,6 +59,11 @@ export interface ICondition<P = any> {
      * **UI Guidance:**
      * - Show "Ignore Blanks" checkbox for DataValidation (common use case)
      * - Hide for ConditionalFormat/TableFilter (default behavior is usually correct)
+     *
+     * **What is blank:**
+     * - Filters and ConditionalFormat: an empty cell, a `""` result, or a string of only spaces
+     *   (Excel's `LEN(TRIM(x))=0`). A tab, a non-breaking space, `0` and an error are values.
+     * - DataValidation: an empty cell only. A `""` result is a value and is judged.
      */
     isIncludeBlanks(): boolean;
     /**
@@ -383,6 +388,7 @@ export declare namespace ICondition {
         readonly NextMonth: "nextMonth";
         readonly NextQuarter: "nextQuarter";
         readonly NextWeek: "nextWeek";
+        readonly NextYear: "nextYear";
         readonly Null: "null";
         readonly Q1: "Q1";
         readonly Q2: "Q2";
@@ -391,6 +397,7 @@ export declare namespace ICondition {
         readonly ThisMonth: "thisMonth";
         readonly ThisQuarter: "thisQuarter";
         readonly ThisWeek: "thisWeek";
+        readonly ThisYear: "thisYear";
         readonly Today: "today";
         readonly Tomorrow: "tomorrow";
         readonly YearToDate: "yearToDate";
@@ -463,9 +470,30 @@ export declare namespace ICondition {
     }
     interface InSetOption {
         /**
-         * If true this filter by blank.
+         * OOXML's `filters/@blank`, carried for the file. The condition's `includeBlanks` is what
+         * keeps a blank row: a reader sets both, the engine reads `includeBlanks`.
          */
         blank?: boolean;
+        /**
+         * Match string items against the text a cell SHOWS rather than the value it holds.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * The identity is the value: `items: [1]` keeps every cell holding 1 however it is
+         * formatted, and `items: ['1']` keeps the cells holding the text `1`. Under `byDisplay` a
+         * string item is instead the displayed text, which is what a spreadsheet's filter list
+         * holds: `'1.50'` keeps a cell holding 1.5 under `0.00`, and `'$1'` one under `$0`. A typed
+         * item is matched by value in both modes.
+         *
+         * `byDisplay` is a filter's option, the one the column dropdown sets. A conditional format
+         * or a data validation has no displayed text to read, so the flag is inert there. Under a
+         * filter it also widens what is blank: a string of only spaces shows as nothing and is
+         * settled as a blank cell, and a whitespace-only item means `includeBlanks`. A port of
+         * Office Scripts' `applyValuesFilter` or Apps Script's `setVisibleValues` passes strings
+         * and sets it.
+         */
+        byDisplay?: boolean;
         /**
          * The values that match: an array, or a list validation's source as formula text.
          *
@@ -481,7 +509,7 @@ export declare namespace ICondition {
          *   evaluated for each cell, so a relative reference gives each cell its own list, and the
          *   source follows inserts and deletes as any formula does.
          *
-         * An array matches as a filter's list of values does.
+         * An array's items match by value, or by displayed text under {@link byDisplay}.
          */
         items?: Scalar[] | string;
         /**
@@ -558,17 +586,17 @@ export declare namespace ICondition {
          */
         toType<T extends InteropScalar>(value: Scalar, type: InteropScalarType): T;
         /**
-         * The text the current cell shows, when the evaluation matches by text; `null` otherwise.
+         * The text the current cell shows, under a filter; `null` elsewhere.
          *
          * @remarks
-         * A filter matches by shown text unless asked not to ({@link ICondition.RangeOptions.match}):
-         * a cell holding `1.5` and showing `1.50` is the item `1.50`. Conditional formats and data
-         * validations match by value, so this answers `null` for them. An operator that compares
-         * text reads `ctx.getText() ?? value`.
+         * Read by an operator asked to match displayed text ({@link InSetOption.byDisplay}): a cell
+         * holding `1.5` and showing `1.50` is the item `1.50`. A conditional format or a data
+         * validation has no displayed text, so this answers `null` there and the operator compares
+         * the value.
          *
          * Formatted on demand, so an operator that never asks pays nothing.
          */
-        getText(): string | null;
+        getDisplayText(): string | null;
         /**
          * Resolves a condition input to a fully-built ICondition instance.
          *
@@ -995,26 +1023,6 @@ export declare namespace ICondition {
          * with no explicit `hasHeader` evaluates the entire range, header row included.
          */
         hasHeader?: boolean;
-        /**
-         * What a filter's list items and `equalTo` text are compared with: the text a cell shows, or
-         * the value it holds.
-         *
-         * @defaultValue `'text'`
-         *
-         * @remarks
-         * `'text'` is a spreadsheet's AutoFilter: the item `1.50` keeps a cell holding `1.5` under the
-         * format `0.00`, and the item `1.5` does not. A number passed as an item or operand still
-         * matches the cells holding that number, however they are formatted.
-         *
-         * `'value'` compares typed values only, so the text `"1"` never matches the number `1`.
-         *
-         * Comparisons (`>`, `between`), Top N, averages, date periods and date groups read the value
-         * either way, and the text operators (contains, starts with, ends with) only ever match a
-         * cell that holds text.
-         *
-         * Read by filters. Conditional formats and data validations match by value.
-         */
-        match?: 'text' | 'value';
     }
     /**
      * JSON for serialization and round-tripping.

package/types/src/condition/_ConditionUtils.d.ts

@@ -144,15 +144,29 @@ export declare class UnresolvedCondition<P = any> implements ICondition<P> {
  * of an exception that costs the caller the entire rule.
  */
 export declare function fromJSON<P = any>(json: ICondition.JSON<P> | null | undefined): ICondition<P> | null;
-/**
- * Per-condition options shared by the single-condition ({@link evalConditions}) and
- * multi-condition ({@link evalRangeConditions}) drivers.
- */
 /**
  * The condition's answer for the BLANK cells of a range, asked per cell — lazily, by the caller,
  * for the cells it actually reads. Blank cells are never visited by the engine.
  */
 export type BlankResolver = (rowIndex: number, colIndex: number) => boolean;
+/**
+ * Whether a value is blank by Excel's AutoFilter rule (`LEN(TRIM(x))=0`, DESIGN-FILTER.md §3.3):
+ * nothing, an empty string, or a string of only U+0020 spaces. A tab, a non-breaking space, `0`
+ * and an error are values.
+ */
+export declare function isBlankValue(value: Scalar): boolean;
+/**
+ * The calc engine's blank: an empty cell, or the `""` a formula returns (`=A1=""` is TRUE for
+ * both). A string of spaces is a string. The filter's rule for a value-shaped level
+ * (DESIGN-FILTER §3.3); {@link isBlankValue} is the display rule.
+ */
+export declare function isBlankByValue(value: Scalar): boolean;
+/**
+ * Whether a filter level matches displayed text somewhere in it — an `InSet` or a `blank`
+ * carrying `byDisplay` — and so takes the display rule for blanks (a string of only spaces is a
+ * blank cell). Anything else takes the calc engine's.
+ */
+export declare function isDisplayShaped(condition: ICondition | ICondition.JSON | null | undefined): boolean;
 /**
  * Iterates through all values executing a single condition (`conditions[0]`) and calling the
  * appropriate callbacks. Used by Data Validation and Conditional Formatting.
@@ -179,11 +193,11 @@ export interface DoRunRangeConditionsOptions extends ICondition.RangeOptions {
     coords: Readonly<IRange.Coords>;
     getHiddenRuns?: (axis: IRange.Axis) => readonly RunCoords[];
     /**
-     * The text a cell shows, backing {@link ICondition.IContext.getText}. Supplied by the sheet;
-     * asked only when {@link ICondition.RangeOptions.match} is not `'value'`, and only for the
-     * cells a text-comparing operator reads. `value` is the cell's, which the driver holds already.
+     * The text a cell shows, backing {@link ICondition.IContext.getDisplayText}. Supplied by the
+     * sheet; asked only for the cells an operator matching displayed text reads. `value` is the
+     * cell's, which the driver holds already.
      */
-    getText?: (rowIndex: number, colIndex: number, value: Scalar) => string;
+    getDisplayText?: (rowIndex: number, colIndex: number, value: Scalar) => string;
     /**
      * Called once per contiguous run of rows/columns (per {@link ICondition.RangeOptions.axis})
      * that remain visible once every condition has been applied, in ascending order.
@@ -259,5 +273,15 @@ export interface DoRunConditionsOptions extends ICondition.RangeOptions {
      * FALSE in others, and the formula's own block evaluation already holds each one.
      */
     onBlank?: (resolve: BlankResolver) => void;
+    /**
+     * Whether a stored value that is blank by Excel's AutoFilter rule ({@link isBlankValue}: a
+     * `""` result, a string of only spaces) is answered as the blank cell it shows as, never shown
+     * to the selector or the operator. Conditional Formatting sets it (`containsBlanks` is
+     * `LEN(TRIM(x))=0`); Data Validation does not, since there a blank is an empty cell and a
+     * `""` result is judged (DESIGN-DV §5). The filter driver decides per level: a display-shaped
+     * one ({@link isDisplayShaped}) takes this rule, any other the calc engine's, where only `""`
+     * is blank (DESIGN-FILTER §3.3).
+     */
+    spacesAreBlank?: boolean;
 }
 //# sourceMappingURL=_ConditionUtils.d.ts.map

package/types/src/fill/IFill.d.ts

@@ -87,7 +87,7 @@ export declare namespace IFill {
          * @remarks
          * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint).
          */
-        readonly Image: "pattern";
+        readonly Image: "image";
         /**
          * An Image.
          * @remarks
@@ -574,22 +574,57 @@ export declare namespace IFill {
     }
     interface PatternJSON extends PatternProperties<string> {
     }
+    /**
+     * Insets of a rectangle from the edges of another, as percentages of its width and height
+     * (an inset of `-10` on the right extends past the edge by a tenth of the width).
+     */
+    interface RectInsets {
+        left?: number;
+        top?: number;
+        right?: number;
+        bottom?: number;
+    }
+    /** How a tiled image fill repeats (DrawingML `tile`). */
+    interface ImageTileProperties {
+        /** Offset of the first tile from the fill rectangle's origin, in pixels. */
+        offsetX?: number;
+        offsetY?: number;
+        /** Scale of each tile as a percentage (100 = natural size). */
+        scaleX?: number;
+        scaleY?: number;
+        /** Which tiles are mirrored: `none`, `x`, `y` or `xy`. */
+        flip?: string;
+        /** Where the tiles align in the shape: `tl`, `t`, `tr`, `l`, `ctr`, `r`, `bl`, `b`, `br`. */
+        alignment?: string;
+    }
+    /**
+     * An image fill: a workbook resource stretched over the shape or tiled across it.
+     *
+     * @remarks
+     * `resId` names the resource the way `IPicture.JSON.resId` names a placed picture's image and,
+     * like it, is meaningful only inside the persist scope the JSON was made in. A shape resolves it
+     * to the resource when it is created and names the resource again when it is serialized.
+     */
     interface ImageProperties extends IFill.Properties {
+        /** The resource id of the image. */
+        resId?: number;
+        /** The part of the image used (`srcRect`), as insets from its edges. Absent for the whole image. */
+        sourceRect?: RectInsets;
         /**
-         * A reference to the image resource.
-         *
-         * @remarks
-         * This is a placeholder
-         */
-        ref?: any;
-        /**
-         * Indicates whether the image fill should be tiled.
+         * The image is stretched to a rectangle inset from the shape's bounds (`stretch/fillRect`);
+         * `{}` for the whole shape. Absent when the image is tiled.
          */
-        tile?: boolean;
+        stretch?: RectInsets;
+        /** The image is tiled (`tile`). Absent when it is stretched. */
+        tile?: ImageTileProperties;
         /**
-         * The resolution of the image in dots per inch (DPI).
+         * The resolution the image is rendered at, in dots per inch (`dpi`); `0` for the image's own.
          */
         dpi?: number;
+        /** The compression the image was stored for (`blip/@cstate`): `email`, `screen`, `print`, `hqprint`, `none`. */
+        compressionState?: string;
+        /** `blip/extLst` as the file states it: an opaque DrawingML fragment, written back as it was. */
+        extLst?: string;
     }
     interface ImageJSON extends ImageProperties {
     }

package/types/src/fill/IStroke.d.ts

@@ -67,32 +67,25 @@ export declare namespace IStroke {
          */
         miterLimit: number;
         /**
-         * Defines the arrowhead or shape that will be drawn at the first vertex of the given shape.
-         *
-         * @defaultValue `null`.
-         *
-         * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/marker-start}
+         * The line end drawn at the start of an open path (DrawingML `headEnd`).
          *
+         * @defaultValue `'none'`
          */
-        markerStart: IStroke.IMarker;
+        headType: IStroke.LineEndType;
+        /** The head's width, relative to the line width. @defaultValue `'med'` */
+        headWidth: IStroke.LineEndSize;
+        /** The head's length, relative to the line width. @defaultValue `'med'` */
+        headLength: IStroke.LineEndSize;
         /**
-         * Defines the arrowhead or shape that will be drawn at all interior vertices of the given shape.
-         *
-         * @defaultValue `null`.
-         *
-         * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/marker-mid}
+         * The line end drawn at the end of an open path (DrawingML `tailEnd`).
          *
+         * @defaultValue `'none'`
          */
-        markerMid: IStroke.IMarker;
-        /**
-         * Defines the arrowhead or shape that will be drawn at final vertex for the given shape.
-         *
-         * @defaultValue `null`.
-         *
-         * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/marker-end}
-         *
-         */
-        markerEnd: IStroke.IMarker;
+        tailType: IStroke.LineEndType;
+        /** The tail's width, relative to the line width. @defaultValue `'med'` */
+        tailWidth: IStroke.LineEndSize;
+        /** The tail's length, relative to the line width. @defaultValue `'med'` */
+        tailLength: IStroke.LineEndSize;
         /**
          * Custom or preset for the stroke.
          */
@@ -117,20 +110,24 @@ export declare namespace IStroke {
          */
         align: IStroke.Align;
     }
-    /**
-     * A Marker is a custom placeholder for shapes along a stroke.
-     *
-     * @remarks
-     * The Marker contains the positioning and shape of the marker.
-     *
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/marker}
-     */
-    interface IMarker {
-        width: number;
-        height: number;
-        axis: number;
-        shape: IStroke.PresetMarkerShape;
-    }
+    /** The shape drawn at an open path's end (DrawingML `ST_LineEndType`). */
+    const LineEndType: {
+        readonly None: "none";
+        readonly Triangle: "triangle";
+        readonly Stealth: "stealth";
+        readonly Diamond: "diamond";
+        readonly Oval: "oval";
+        /** An open arrowhead: two strokes of the line's width. */
+        readonly Arrow: "arrow";
+    };
+    type LineEndType = typeof LineEndType[keyof typeof LineEndType];
+    /** A line end's width or length, relative to the line width (DrawingML `ST_LineEndWidth` / `ST_LineEndLength`). */
+    const LineEndSize: {
+        readonly Small: "sm";
+        readonly Medium: "med";
+        readonly Large: "lg";
+    };
+    type LineEndSize = typeof LineEndSize[keyof typeof LineEndSize];
     /**
      * Support stroke with multiple strokes.
      * ** PLACEHOLDER **
@@ -234,13 +231,6 @@ export declare namespace IStroke {
         readonly Round: "round";
     };
     type LineJoin = typeof LineJoin[keyof typeof LineJoin];
-    const PresetMarkerShape: {
-        readonly Single: "none";
-        readonly Double: "double";
-        readonly ThickThin: "thickThin";
-        readonly ThinThick: "thinThick";
-    };
-    type PresetMarkerShape = typeof PresetMarkerShape[keyof typeof PresetMarkerShape];
     const StrokeStyle: {
         readonly None: "none";
         readonly Dashed: "dashed";
@@ -260,6 +250,8 @@ export declare namespace IStroke {
      */
     interface JSON extends Properties {
         fill: IFill.JSON;
+        /** The line's `extLst` as a file states it (DrawingML `ln/extLst`): an opaque fragment, written back as it was. */
+        extLst?: string;
     }
 }
 //# sourceMappingURL=IStroke.d.ts.map

package/types/src/filter/IFilter.d.ts

@@ -1,4 +1,5 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
+import { RunCoordValue } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { ICondition } from '../condition';
 import { ICellRange } from '../cellRange';
@@ -101,33 +102,71 @@ export declare namespace IFilter {
          * @defaultValue `10000`
          */
         limit?: number;
+        /**
+         * Group the column by the text its cells SHOW rather than by value, as a spreadsheet's filter
+         * list does: `1` under `$0` and under `0%` are two items, and a string of only spaces is a
+         * blank. The items are then the texts an `InSet { byDisplay: true }` condition holds.
+         *
+         * @defaultValue `false` — by value, the identity {@link ICondition.InSetOption.items} has.
+         */
+        byDisplay?: boolean;
     }
     /**
      * One distinct value of a filtered column.
      */
     interface Item {
         /**
-         * The text the cells show. This is the item an `InSet` condition holds: a filter matches by
-         * shown text ({@link ICondition.RangeOptions.match}).
+         * The item's label: by value, the value as `General` shows it (a date as its date format
+         * does); by display, the text the cells show, which is then the item an
+         * `InSet { byDisplay: true }` condition holds.
          */
         text: string;
-        /** The value of the first cell showing `text`; the item's place in the order. */
+        /** The value, or by display the value of the first cell showing `text`; the item's place in the order. */
         value: Scalar;
         /** The rows holding the value. */
         count: number;
         /** Whether at least one row holding the value passes the filters. */
         checked: boolean;
     }
+    /**
+     * One level of the date tree {@link Items.dates}: the nodes, each the run of items it spans,
+     * in the order the items are listed.
+     */
+    interface DateLevel {
+        /** The part this level groups by. */
+        group: ICondition.DateItemGroupingType;
+        /**
+         * The nodes. A run's `value` is the group item selecting exactly its items: the parts down
+         * to this level (`{ group: 'month', year: 1995, month: 10 }`).
+         */
+        runs: readonly RunCoordValue<ICondition.DateGroupItem>[];
+    }
     /**
      * What {@link IFilter.getItems} answers.
      */
     interface Items {
         /**
-         * The distinct texts, ascending by the workbook's comparison of their values. Values that
-         * show alike are one item. Blanks are not an item.
+         * The distinct values, or the distinct texts under `byDisplay`. The dates come first (the tree in {@link dates}), newest year first
+         * and ascending within a year, as Excel's date tree lists them; the rest follow, ascending
+         * by the workbook's comparison of their values. Values that show alike are one item. Blanks
+         * are not an item.
          */
         items: readonly Item[];
-        /** Whether a listed row is blank. */
+        /**
+         * The date tree over the leading items, one level per entry: year, month and day, then hour,
+         * minute and second when a date carries a time. Absent when the column shows no date.
+         *
+         * @remarks
+         * A date is a number shown under a date format; a time-only format is a number. Every level
+         * covers the same items, `0` to the last date, and a finer level's runs nest inside the
+         * coarser's. A node's checkbox is the state of its items; a checked node is written as its
+         * run's value, in {@link ICondition.InSetOption.dateGroups}.
+         */
+        dates?: readonly DateLevel[];
+        /**
+         * Whether a listed row is blank: empty, or showing nothing (a `""` result, a string of only
+         * spaces). The same rows `includeBlanks` keeps.
+         */
         hasBlanks: boolean;
         /** Whether at least one blank row passes the filters. */
         blanksChecked: boolean;
@@ -135,6 +174,12 @@ export declare namespace IFilter {
         truncated: boolean;
         /** The rows read. */
         total: number;
+        /**
+         * The mode the list was read in, so a caller writes the items back under the same one:
+         * `{ operator: 'inSet', param: { items, byDisplay } }`. A list read by value fed back as
+         * texts under `byDisplay` would match nothing for a number.
+         */
+        byDisplay: boolean;
     }
     /**
      * Interface indicating the ability to filter data.

package/types/src/hyperlink/IHyperlink.d.ts

@@ -89,6 +89,14 @@ export declare namespace IHyperlink {
         screenTip?: string;
         /** {@inheritDoc IHyperlink.getTarget} */
         target?: string;
+        /**
+         * An action the link performs instead of, or beside, following its address, as a file states
+         * it (`hlinkClick/@action`). Office's own (`ppaction://…`) mean nothing in a workbook; kept so
+         * the file reads back as written.
+         */
+        action?: string;
+        /** Whether following the link adds it to the browsing history (`hlinkClick/@history`). */
+        history?: boolean;
     }
     /**
      * A JSON representation useful for persistence.

package/types/src/index.d.ts

@@ -53,6 +53,7 @@ export * from './table';
 export { Table } from './table/Table';
 export * from './theme';
 export * from './sheet';
+export * from './outline';
 export * from './sheetHeader';
 export * from './sheetProtection';
 export * from './sheetView';

package/types/src/movable/AbstractMovableContent.d.ts

@@ -1,4 +1,5 @@
 import { AbstractModel, IModel } from '../model';
+import { IStyleCollection } from '../style';
 import { IMovable } from './IMovable';
 /**
  * What every content shares: its name, its description and the movable that places it.
@@ -49,6 +50,11 @@ export declare namespace AbstractMovableContent {
          * Returns the movable that places the content. Not provided for content that has none.
          */
         getMovable?: () => IMovable | null;
+        /**
+         * Returns the styles the content's theme references resolve against. Not provided for
+         * content outside a workbook.
+         */
+        getStyles?: () => IStyleCollection | null;
     }
 }
 //# sourceMappingURL=AbstractMovableContent.d.ts.map