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

package/types/src/scripting/declarations.d.ts

@@ -0,0 +1,49 @@
+export declare function getScriptingDeclarations(): Promise<string>;
+/**
+ * The signature index of the script authoring surface — the shipped `scripting-api.json`.
+ *
+ * @remarks
+ * `scripting.d.ts` carries every declaration with its full documentation, which is what an editor
+ * wants. This is the same surface as a lookup table: one entry per declared name, one line per
+ * member, each with where its full declaration sits in `scripting.d.ts`. Both files are written by
+ * one build step from one text, so a name listed here is a name a script type-checks against.
+ */
+export declare namespace ScriptingApi {
+    /** One callable or readable member of a declaration. */
+    interface Member {
+        /** The member's name; `new`, `(call)` and `[index]` for the unnamed signature forms. */
+        readonly name: string;
+        /** The declaration on one line, without its documentation. */
+        readonly signature: string;
+        /** The first sentence of the member's documentation. */
+        readonly summary?: string;
+        readonly deprecated?: true;
+        /** 1-based, inclusive line span in `scripting.d.ts`, documentation included. */
+        readonly lines: readonly [start: number, end: number];
+    }
+    /** One declared name. */
+    interface Entry {
+        readonly kind: 'interface' | 'class' | 'enum' | 'type' | 'const' | 'function' | 'namespace';
+        /** The first sentence of the declaration's documentation. */
+        readonly summary?: string;
+        readonly deprecated?: true;
+        /** The type parameter list as written, e.g. `<T = any>`. */
+        readonly typeParams?: string;
+        /** The types this one extends, as written. Their members are reachable on this type too. */
+        readonly extends?: readonly string[];
+        /** The declaration on one line — present when there is no member list to show instead. */
+        readonly signature?: string;
+        readonly members?: readonly Member[];
+        /** Names declared in the namespace merged with this one; each is indexed as `<this>.<name>`. */
+        readonly nested?: readonly string[];
+        /** 1-based, inclusive line span in `scripting.d.ts`, documentation included. */
+        readonly lines: readonly [start: number, end: number];
+    }
+    interface Index {
+        readonly version: 1;
+        /** Keyed by the dotted path below `SheetXL` — `ICellRange`, `ICellRange.Coords`. */
+        readonly types: Readonly<Record<string, Entry>>;
+    }
+}
+export declare function getScriptingApi(): Promise<ScriptingApi.Index>;
+//# sourceMappingURL=declarations.d.ts.map

package/types/src/scripting/declarations.node.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Node loaders for the script authoring surface (`scripting.d.ts`) and its signature index
+ * (`scripting-api.json`).
+ *
+ * Selected via the `@sheetxl/sdk/scripting/declarations` conditional export (the `node` condition).
+ */
+export declare function loadScriptingDeclarations(): Promise<string>;
+export declare function loadScriptingApi(): Promise<string>;
+//# sourceMappingURL=declarations.node.d.ts.map

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

@@ -1,4 +1,7 @@
 export * from './IScript';
 export * from './IModule';
+export * from './IModuleCollection';
 export * from './IFunctionCollection';
+export * from './declarations';
+export { getScriptRuntime, withScriptRuntime } from './Runtime';
 //# sourceMappingURL=index.d.ts.map

package/types/src/selection/IMovableSelection.d.ts

@@ -0,0 +1,148 @@
+import { IListener } from '../listener';
+import { IMovable } from '../movable';
+import { ISheet } from '../sheet';
+/**
+ * The drawings selected on a sheet's view: shapes, pictures, charts, controls, groups and the
+ * members of groups.
+ *
+ * @remarks
+ * The counterpart of {@link IRangeSelection}. A view holds both, independently: selecting a
+ * drawing does not change the range selection and selecting cells does not clear this one. Which
+ * of the two the keyboard acts on is a matter of focus, which belongs to the UI.
+ *
+ * Empty is the usual state, when the cells have the selection.
+ *
+ * Every selected movable has the same parent, its {@link getContainer | container}: the sheet,
+ * or one group. Selecting a movable from another container replaces the selection.
+ */
+export interface IMovableSelection {
+    /**
+     * Returns the sheet the selection is on.
+     */
+    getSheet(): ISheet;
+    /**
+     * Returns what every selected movable shares as its parent: `null` for the sheet, else the
+     * group's movable.
+     *
+     * @remarks
+     * `null` when the selection is empty.
+     */
+    getContainer(): IMovable | null;
+    /**
+     * Returns the selected movables, back to front.
+     *
+     * @remarks
+     * Empty when the cells have the selection.
+     */
+    getItems(): readonly IMovable[];
+    /**
+     * Returns the movable selected most recently, or `null` when the selection is empty.
+     *
+     * @remarks
+     * The one a Format pane shows.
+     */
+    getActive(): IMovable | null;
+    /**
+     * Returns `true` if `movable` is selected.
+     */
+    isSelected(movable: IMovable): boolean;
+    /**
+     * Returns `true` if no movable is selected.
+     */
+    isEmpty(): boolean;
+    /**
+     * Selects `movables`, replacing the selection.
+     *
+     * @param movables The movables to select, the last one the active one.
+     * @param options With `add`, extends the selection instead.
+     *
+     * @remarks
+     * Movables are taken in order, as picks: one in another container than those selected before it
+     * replaces them.
+     *
+     * @throws If a movable is not on this sheet, or has been deleted.
+     */
+    select(movables: readonly IMovable[], options?: IMovableSelection.SelectOptions): this;
+    /**
+     * Removes `movables` from the selection. Movables not selected are ignored.
+     */
+    unselect(movables: readonly IMovable[]): this;
+    /**
+     * Empties the selection.
+     */
+    clear(): this;
+    /**
+     * Selects the next drawing on the sheet, alone.
+     *
+     * @param reverse Selects the previous one instead.
+     *
+     * @remarks
+     * Visits every drawing back to front, a group and then its members in the group's order. A
+     * hidden drawing is not visited. Wraps at the ends. With nothing selected, starts from the first
+     * (or, in reverse, the last).
+     *
+     * Useful for pressing Tab from the UI.
+     */
+    traverse(reverse?: boolean): this;
+    /**
+     * Returns `true` if `other` selects the same movables, with the same one active.
+     */
+    isEquals(other: IMovableSelection): boolean;
+    /**
+     * Adds listeners to the selection.
+     *
+     * @param listeners The listeners to add.
+     * @param options Options for the listeners.
+     * @returns A function to remove the listeners.
+     */
+    addListeners(listeners: IMovableSelection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isIMovableSelection: true;
+}
+/**
+ * {@inheritDoc IMovableSelection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IMovableSelection}
+ */
+export declare namespace IMovableSelection {
+    /**
+     * Options for {@link IMovableSelection.select}.
+     */
+    interface SelectOptions {
+        /**
+         * Extend the selection rather than replace it.
+         *
+         * @remarks
+         * The equivalent of Ctrl+click in the UI.
+         *
+         * @defaultValue false
+         */
+        add?: boolean;
+    }
+    /**
+     * Events for {@link IMovableSelection}.
+     */
+    interface Events {
+        /**
+         * Called when the selected movables, or the active one, change.
+         */
+        onChange?(source: IMovableSelection): void;
+    }
+    /**
+     * Listeners for {@link IMovableSelection} events.
+     */
+    interface IListeners extends IListener.Callbacks<IMovableSelection, Events> {
+    }
+    /**
+     * Options for constructing an {@link IMovableSelection}.
+     */
+    interface ConstructorOptions {
+        /**
+         * The sheet the selection is on.
+         */
+        sheet: ISheet;
+    }
+}
+//# sourceMappingURL=IMovableSelection.d.ts.map

package/types/src/selection/IRangeSelection.d.ts

@@ -23,11 +23,14 @@ export interface IRangeSelection {
      * @param axis The axis to traverse. Default is `ICellRange.Axis.Row`.
      * @param reverse Whether to traverse in reverse. Default is false.
      * @param region An optional bounding region to *wrap within* when there is no explicit selection (a
-     *   bare cursor) — e.g. a table's data range, so Tab/Enter cycle inside it instead of walking off its
-     *   edge. Resolving this region is the caller's job (the view's `getRegionBounds`); omit it (the bare
-     *   sheet) and a bare-cursor traverse is a plain move.
+     *   bare cursor), so the move cycles inside it instead of walking off its edge. Omit it and a
+     *   bare-cursor traverse is a plain move.
      *
-     * @remarks Useful for pressing tab or enter from the UI.
+     * @remarks
+     * Useful for pressing tab or enter from the UI.
+     *
+     * A bare cursor in a table wraps a row traverse (Tab) within the table's data range without being
+     * given a region; a column traverse (Enter) moves on out of the table.
      */
     traverse(axis?: IRange.Axis, reverse?: boolean, region?: IRange.Coords): this;
     /**
@@ -177,6 +180,8 @@ export interface IRangeSelection {
      * @returns A function to remove the listeners.
      */
     addListeners(listeners: IRangeSelection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isIRangeSelection: true;
 }
 /**
  * {@inheritDoc IRangeSelection}

package/types/src/selection/MovableSelection.d.ts

@@ -0,0 +1,48 @@
+import { IListener } from '../listener';
+import { IMovable } from '../movable';
+import { ISheet } from '../sheet';
+import { IMovableSelection } from './IMovableSelection';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+/**
+ * The movable selection of a sheet's view.
+ */
+export declare class MovableSelection implements IMovableSelection {
+    protected _sheet: ISheet;
+    protected _emitter: ListenerEmitter<MovableSelection, IMovableSelection.IListeners>;
+    /** The selected movables in the order they were picked; the last is the active one. */
+    protected _picks: readonly IMovable[];
+    protected _container: IMovable | null;
+    /** {@link _picks} back to front, handed out again while the z-order holds. */
+    protected _items: readonly IMovable[];
+    constructor(options: IMovableSelection.ConstructorOptions);
+    /** {@inheritDoc IMovableSelection.getSheet} */
+    getSheet(): ISheet;
+    /** {@inheritDoc IMovableSelection.getContainer} */
+    getContainer(): IMovable | null;
+    /** {@inheritDoc IMovableSelection.getItems} */
+    getItems(): readonly IMovable[];
+    /** {@inheritDoc IMovableSelection.getActive} */
+    getActive(): IMovable | null;
+    /** {@inheritDoc IMovableSelection.isSelected} */
+    isSelected(movable: IMovable): boolean;
+    /** {@inheritDoc IMovableSelection.isEmpty} */
+    isEmpty(): boolean;
+    /** {@inheritDoc IMovableSelection.select} */
+    select(movables: readonly IMovable[], options?: IMovableSelection.SelectOptions): this;
+    /** {@inheritDoc IMovableSelection.unselect} */
+    unselect(movables: readonly IMovable[]): this;
+    /** {@inheritDoc IMovableSelection.clear} */
+    clear(): this;
+    /** {@inheritDoc IMovableSelection.traverse} */
+    traverse(reverse?: boolean): this;
+    /** {@inheritDoc IMovableSelection.isEquals} */
+    isEquals(other: IMovableSelection): boolean;
+    /** {@inheritDoc IMovableSelection.addListeners} */
+    addListeners(listeners: IMovableSelection.IListeners, options?: IListener.Options): IListener.Remove;
+    protected _checkOnSheet(movable: IMovable): void;
+    protected _update(picks: readonly IMovable[], container: IMovable | null): this;
+    get [Symbol.toStringTag](): string;
+    /** {@inheritDoc IMovableSelection.isIMovableSelection} */
+    get isIMovableSelection(): true;
+}
+//# sourceMappingURL=MovableSelection.d.ts.map

package/types/src/selection/RangeSelection.d.ts

@@ -111,6 +111,19 @@ export declare class RangeSelection {
     protected _setSelectionCell(activeCell: IRange.CellCoords | null): this;
     protected _isCellOutOfBounds(cell: IRange.CellCoords): boolean;
     protected _cellToRangeActual(start: IRange.CellCoords, end: IRange.CellCoords): IRange.Coords;
+    /** `range` grown until it cuts through no merge — see `_SheetUtils.closeOverMerges`. */
+    protected _closeOverMerges<T extends IRange.Coords>(range: T): T;
+    /**
+     * Keeps the selection off merge interiors, whoever wrote it: every range is grown until it cuts
+     * through no merge, and a bare anchor on a merged cell becomes that merge as a range (a merged cell
+     * is never a 1×1). The grid writes selections straight through {@link updateCoords} — a click, a
+     * tap, a fill — so this is the one place that sees them all.
+     *
+     * @remarks
+     * Ranges carrying a `scope` belong to another sheet's geometry (a reference picker's cross-sheet
+     * range) and are left as given — see {@link _localCoords}.
+     */
+    protected _resolveMerges(coords: Required<IRangeSelection.Coords>): Required<IRangeSelection.Coords>;
     protected _rangesFromCellOptional(selection: Required<IRangeSelection.Coords>, cell: Partial<IRange.CellCoords>, cellPivot: Partial<IRange.CellCoords>): IRange.Coords | undefined;
     protected _getEntireRange(): IRange.Coords;
     protected _hiddenRowsAt(index: number, reverse?: boolean): number;
@@ -135,6 +148,8 @@ export declare class RangeSelection {
     protected _scrollCellCoordsIntoView(coords: Partial<IRange.Coords>, options?: globalThis.ScrollIntoViewOptions | boolean): Promise<boolean>;
     get [Symbol.toStringTag](): string;
     toString(): string;
+    /** {@inheritDoc IRangeSelection.isIRangeSelection} */
+    get isIRangeSelection(): true;
 }
 interface _ReadCache {
     range: ICellRange | null;

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

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

package/types/src/shape/GeometryPreset.d.ts

@@ -0,0 +1,197 @@
+/**
+ * GENERATED by scripts/shapes/encodePresetShapes.mts - do not edit.
+ *
+ * Source: scripts/shapes/source/presetShapeDefinitions.xml (sha256 eaff19f4405b3be6822428c96ef46cc685499217366fd58e5e63a5a24739f02f, LF-normalized)
+ * Patches: scripts/shapes/presetShapes.patch.json
+ */
+/** Every preset's `prstGeom/@prst` name, by a PascalCase key: `IGeometry.Preset`. */
+export declare const GeometryPreset: Readonly<{
+    readonly AccentBorderCallout1: "accentBorderCallout1";
+    readonly AccentBorderCallout2: "accentBorderCallout2";
+    readonly AccentBorderCallout3: "accentBorderCallout3";
+    readonly AccentCallout1: "accentCallout1";
+    readonly AccentCallout2: "accentCallout2";
+    readonly AccentCallout3: "accentCallout3";
+    readonly ActionButtonBackPrevious: "actionButtonBackPrevious";
+    readonly ActionButtonBeginning: "actionButtonBeginning";
+    readonly ActionButtonBlank: "actionButtonBlank";
+    readonly ActionButtonDocument: "actionButtonDocument";
+    readonly ActionButtonEnd: "actionButtonEnd";
+    readonly ActionButtonForwardNext: "actionButtonForwardNext";
+    readonly ActionButtonHelp: "actionButtonHelp";
+    readonly ActionButtonHome: "actionButtonHome";
+    readonly ActionButtonInformation: "actionButtonInformation";
+    readonly ActionButtonMovie: "actionButtonMovie";
+    readonly ActionButtonReturn: "actionButtonReturn";
+    readonly ActionButtonSound: "actionButtonSound";
+    readonly Arc: "arc";
+    readonly BentArrow: "bentArrow";
+    readonly BentConnector2: "bentConnector2";
+    readonly BentConnector3: "bentConnector3";
+    readonly BentConnector4: "bentConnector4";
+    readonly BentConnector5: "bentConnector5";
+    readonly BentUpArrow: "bentUpArrow";
+    readonly Bevel: "bevel";
+    readonly BlockArc: "blockArc";
+    readonly BorderCallout1: "borderCallout1";
+    readonly BorderCallout2: "borderCallout2";
+    readonly BorderCallout3: "borderCallout3";
+    readonly BracePair: "bracePair";
+    readonly BracketPair: "bracketPair";
+    readonly Callout1: "callout1";
+    readonly Callout2: "callout2";
+    readonly Callout3: "callout3";
+    readonly Can: "can";
+    readonly ChartPlus: "chartPlus";
+    readonly ChartStar: "chartStar";
+    readonly ChartX: "chartX";
+    readonly Chevron: "chevron";
+    readonly Chord: "chord";
+    readonly CircularArrow: "circularArrow";
+    readonly Cloud: "cloud";
+    readonly CloudCallout: "cloudCallout";
+    readonly Corner: "corner";
+    readonly CornerTabs: "cornerTabs";
+    readonly Cube: "cube";
+    readonly CurvedConnector2: "curvedConnector2";
+    readonly CurvedConnector3: "curvedConnector3";
+    readonly CurvedConnector4: "curvedConnector4";
+    readonly CurvedConnector5: "curvedConnector5";
+    readonly CurvedDownArrow: "curvedDownArrow";
+    readonly CurvedLeftArrow: "curvedLeftArrow";
+    readonly CurvedRightArrow: "curvedRightArrow";
+    readonly CurvedUpArrow: "curvedUpArrow";
+    readonly Decagon: "decagon";
+    readonly DiagStripe: "diagStripe";
+    readonly Diamond: "diamond";
+    readonly Dodecagon: "dodecagon";
+    readonly Donut: "donut";
+    readonly DoubleWave: "doubleWave";
+    readonly DownArrow: "downArrow";
+    readonly DownArrowCallout: "downArrowCallout";
+    readonly Ellipse: "ellipse";
+    readonly EllipseRibbon: "ellipseRibbon";
+    readonly EllipseRibbon2: "ellipseRibbon2";
+    readonly FlowChartAlternateProcess: "flowChartAlternateProcess";
+    readonly FlowChartCollate: "flowChartCollate";
+    readonly FlowChartConnector: "flowChartConnector";
+    readonly FlowChartDecision: "flowChartDecision";
+    readonly FlowChartDelay: "flowChartDelay";
+    readonly FlowChartDisplay: "flowChartDisplay";
+    readonly FlowChartDocument: "flowChartDocument";
+    readonly FlowChartExtract: "flowChartExtract";
+    readonly FlowChartInputOutput: "flowChartInputOutput";
+    readonly FlowChartInternalStorage: "flowChartInternalStorage";
+    readonly FlowChartMagneticDisk: "flowChartMagneticDisk";
+    readonly FlowChartMagneticDrum: "flowChartMagneticDrum";
+    readonly FlowChartMagneticTape: "flowChartMagneticTape";
+    readonly FlowChartManualInput: "flowChartManualInput";
+    readonly FlowChartManualOperation: "flowChartManualOperation";
+    readonly FlowChartMerge: "flowChartMerge";
+    readonly FlowChartMultidocument: "flowChartMultidocument";
+    readonly FlowChartOfflineStorage: "flowChartOfflineStorage";
+    readonly FlowChartOffpageConnector: "flowChartOffpageConnector";
+    readonly FlowChartOnlineStorage: "flowChartOnlineStorage";
+    readonly FlowChartOr: "flowChartOr";
+    readonly FlowChartPredefinedProcess: "flowChartPredefinedProcess";
+    readonly FlowChartPreparation: "flowChartPreparation";
+    readonly FlowChartProcess: "flowChartProcess";
+    readonly FlowChartPunchedCard: "flowChartPunchedCard";
+    readonly FlowChartPunchedTape: "flowChartPunchedTape";
+    readonly FlowChartSort: "flowChartSort";
+    readonly FlowChartSummingJunction: "flowChartSummingJunction";
+    readonly FlowChartTerminator: "flowChartTerminator";
+    readonly FoldedCorner: "foldedCorner";
+    readonly Frame: "frame";
+    readonly Funnel: "funnel";
+    readonly Gear6: "gear6";
+    readonly Gear9: "gear9";
+    readonly HalfFrame: "halfFrame";
+    readonly Heart: "heart";
+    readonly Heptagon: "heptagon";
+    readonly Hexagon: "hexagon";
+    readonly HomePlate: "homePlate";
+    readonly HorizontalScroll: "horizontalScroll";
+    readonly IrregularSeal1: "irregularSeal1";
+    readonly IrregularSeal2: "irregularSeal2";
+    readonly LeftArrow: "leftArrow";
+    readonly LeftArrowCallout: "leftArrowCallout";
+    readonly LeftBrace: "leftBrace";
+    readonly LeftBracket: "leftBracket";
+    readonly LeftCircularArrow: "leftCircularArrow";
+    readonly LeftRightArrow: "leftRightArrow";
+    readonly LeftRightArrowCallout: "leftRightArrowCallout";
+    readonly LeftRightCircularArrow: "leftRightCircularArrow";
+    readonly LeftRightRibbon: "leftRightRibbon";
+    readonly LeftRightUpArrow: "leftRightUpArrow";
+    readonly LeftUpArrow: "leftUpArrow";
+    readonly LightningBolt: "lightningBolt";
+    readonly Line: "line";
+    readonly LineInv: "lineInv";
+    readonly MathDivide: "mathDivide";
+    readonly MathEqual: "mathEqual";
+    readonly MathMinus: "mathMinus";
+    readonly MathMultiply: "mathMultiply";
+    readonly MathNotEqual: "mathNotEqual";
+    readonly MathPlus: "mathPlus";
+    readonly Moon: "moon";
+    readonly NoSmoking: "noSmoking";
+    readonly NonIsoscelesTrapezoid: "nonIsoscelesTrapezoid";
+    readonly NotchedRightArrow: "notchedRightArrow";
+    readonly Octagon: "octagon";
+    readonly Parallelogram: "parallelogram";
+    readonly Pentagon: "pentagon";
+    readonly Pie: "pie";
+    readonly PieWedge: "pieWedge";
+    readonly Plaque: "plaque";
+    readonly PlaqueTabs: "plaqueTabs";
+    readonly Plus: "plus";
+    readonly QuadArrow: "quadArrow";
+    readonly QuadArrowCallout: "quadArrowCallout";
+    readonly Rect: "rect";
+    readonly Ribbon: "ribbon";
+    readonly Ribbon2: "ribbon2";
+    readonly RightArrow: "rightArrow";
+    readonly RightArrowCallout: "rightArrowCallout";
+    readonly RightBrace: "rightBrace";
+    readonly RightBracket: "rightBracket";
+    readonly Round1Rect: "round1Rect";
+    readonly Round2DiagRect: "round2DiagRect";
+    readonly Round2SameRect: "round2SameRect";
+    readonly RoundRect: "roundRect";
+    readonly RtTriangle: "rtTriangle";
+    readonly SmileyFace: "smileyFace";
+    readonly Snip1Rect: "snip1Rect";
+    readonly Snip2DiagRect: "snip2DiagRect";
+    readonly Snip2SameRect: "snip2SameRect";
+    readonly SnipRoundRect: "snipRoundRect";
+    readonly SquareTabs: "squareTabs";
+    readonly Star10: "star10";
+    readonly Star12: "star12";
+    readonly Star16: "star16";
+    readonly Star24: "star24";
+    readonly Star32: "star32";
+    readonly Star4: "star4";
+    readonly Star5: "star5";
+    readonly Star6: "star6";
+    readonly Star7: "star7";
+    readonly Star8: "star8";
+    readonly StraightConnector1: "straightConnector1";
+    readonly StripedRightArrow: "stripedRightArrow";
+    readonly Sun: "sun";
+    readonly SwooshArrow: "swooshArrow";
+    readonly Teardrop: "teardrop";
+    readonly Trapezoid: "trapezoid";
+    readonly Triangle: "triangle";
+    readonly UpArrow: "upArrow";
+    readonly UpArrowCallout: "upArrowCallout";
+    readonly UpDownArrow: "upDownArrow";
+    readonly UpDownArrowCallout: "upDownArrowCallout";
+    readonly UturnArrow: "uturnArrow";
+    readonly VerticalScroll: "verticalScroll";
+    readonly Wave: "wave";
+    readonly WedgeEllipseCallout: "wedgeEllipseCallout";
+    readonly WedgeRectCallout: "wedgeRectCallout";
+    readonly WedgeRoundRectCallout: "wedgeRoundRectCallout";
+}>;
+//# sourceMappingURL=GeometryPreset.d.ts.map