@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

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

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

package/types/src/externalBook/ExternalBookCollection.d.ts

@@ -0,0 +1,36 @@
+import { IExternalBook } from './IExternalBook';
+import { IExternalBookCollection } from './IExternalBookCollection';
+/**
+ * Implementation for {@link IExternalBookCollection}.
+ */
+export declare class ExternalBookCollection implements IExternalBookCollection {
+    /**
+     * Positional, `[n]`-indexed (`_items[0]` is `[1]`) — `null` at a position is a DDE/OLE link or
+     * otherwise unmodeled. Gaps carry meaning (the position still counts), so this is never compacted.
+     */
+    private _items;
+    constructor(options?: ExternalBookCollection.ConstructorOptions);
+    [Symbol.iterator](): IterableIterator<IExternalBook>;
+    /** Only the modeled books — gaps (DDE/OLE) are omitted, not positional. Use {@link getByIndex} for `[n]` lookup. */
+    getItems(): IExternalBook[];
+    getCount(): number;
+    getByIndex(n: number): IExternalBook | null;
+    toJSON(): (IExternalBook.JSON | null)[] | null;
+    readonly isIExternalBookCollection: true;
+}
+export declare namespace ExternalBookCollection {
+    interface ConstructorOptions {
+        /**
+         * Books to hydrate at construction, in `IWorkbook.JSON.externalBooks` order — which IS `[n]`
+         * order (1-based). A `null` entry is a preserved gap (see {@link IExternalBookCollection.getByIndex}).
+         *
+         * @remarks
+         * Taken here rather than through a separate `fromJSON()` call — mirrors
+         * `NamedFormulaCollection`'s reasoning: this collection owns the items, so hydrating at
+         * construction avoids a pre-load lifecycle state. Unlike named formulas, nothing here is
+         * mutable yet, so there is no transactional persist scope to speak of either.
+         */
+        json?: (IExternalBook.JSON | null)[];
+    }
+}
+//# sourceMappingURL=ExternalBookCollection.d.ts.map

package/types/src/externalBook/IExternalBook.d.ts

@@ -0,0 +1,97 @@
+import { Tuple } from '../collections';
+import { ICell } from '../cell';
+/**
+ * A cached snapshot of another workbook, referenced from a formula as `[n]Sheet1!$A$1`.
+ *
+ * @remarks
+ * Excel's external link is not a live reference — it is the cache plus enough identity to go
+ * re-fetch the source. See the design doc for the full model:
+ * `private-assets/design/calc/DESIGN-EXTERNAL-LINKS.md`.
+ *
+ * Read-only. There is no `setPath`/`breakLinks` here yet — authoring lands with the resolver API
+ * (design doc §4C), not this phase.
+ */
+export interface IExternalBook {
+    /**
+     * The book's identity, as read from its part's own relationships — an ORDERED list, not a single
+     * path with optional alternates. A book can carry several of these at once (`externalLinkPath`,
+     * `xlExternalLinkPath/xlPathMissing`, `externalLinkLongPath`, and the xxl21 `alternateUrls`
+     * extension are all instances of this one shape).
+     */
+    getIdentity(): readonly IExternalBook.IdentityEntry[];
+    /**
+     * The source book's sheet names, in its own order — the ONLY names the book is known by.
+     *
+     * @remarks
+     * `[n]Sheet1!...` addresses a sheet by its position in THIS list, not by a stable id — the source
+     * workbook has no idea SheetXL exists.
+     */
+    getSheetNames(): readonly string[];
+    /**
+     * The source book's own defined names, as seen at cache time — raw, uncompiled text.
+     *
+     * @remarks
+     * Parsing `refersTo` into something evaluable is phase 2/3's job (design doc §5). Kept verbatim
+     * here so nothing is lost between read and then.
+     */
+    getDefinedNames(): readonly IExternalBook.DefinedNameEntry[];
+    /**
+     * The cached cell values for one of the book's sheets, or `null` if that sheet was never cached.
+     *
+     * @remarks
+     * **Sparse, and uncached is not the same as empty.** Values only — no format, no style, no
+     * comment; a cached date is a plain serial (design doc §2.5).
+     *
+     * @param sheetIndex Position in {@link getSheetNames}, matching the XML's `sheetId` (0-based).
+     */
+    getSheetData(sheetIndex: number): IExternalBook.SheetData | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIExternalBook: true;
+    toJSON?(): IExternalBook.JSON | null;
+}
+export declare namespace IExternalBook {
+    /**
+     * One `(relTypeUri, target)` pair from the book part's own relationships.
+     *
+     * @remarks
+     * `type` is the full relationship-type URI (not a shorthand) — it is what tells apart an
+     * `externalLinkPath`, an `xlExternalLinkPath/xlPathMissing` (a bare name, not a URI), an
+     * `externalLinkLongPath`, and an xxl21 `alternateUrls` entry. Emitting one under a hard-coded rel
+     * type would silently rewrite what the source file said.
+     */
+    interface IdentityEntry {
+        type: string;
+        target: string;
+    }
+    interface DefinedNameEntry {
+        name: string;
+        /** The raw `[0]Sheet1!$A$1`-style text — not parsed or compiled in this phase. */
+        refersTo: string;
+        /** Position in {@link IExternalBook.getSheetNames}, when the name is sheet-scoped. */
+        sheetIndex?: number;
+    }
+    interface SheetData {
+        /** Position in {@link IExternalBook.getSheetNames} this cache belongs to — the XML's `sheetId`, 0-based. */
+        sheetIndex: number;
+        /** `<sheetData refreshError="1">` — Excel could not refresh this sheet's cache last time it tried. */
+        refreshError?: boolean;
+        /**
+         * Sparse cell values — the same encoding `ISheet.JSON.data` uses (`ICell.JSON` is already just
+         * the value+type pair; style/formula live in sibling fields there, none of which apply to a
+         * values-only cache — design doc §2.5).
+         */
+        data: Tuple.GridTuple<ICell.JSON>;
+    }
+    interface JSON {
+        identity: IdentityEntry[];
+        sheetNames: string[];
+        definedNames?: DefinedNameEntry[];
+        /** One entry per CACHED sheet, not per sheet — a sheet absent here was never cached (not empty). */
+        sheetDataSet?: SheetData[];
+        /** `mc:Ignorable="x14 xxl21"` was present on the part root — preserved so a future writer round-trips it. */
+        mceIgnorable?: boolean;
+    }
+}
+//# sourceMappingURL=IExternalBook.d.ts.map

package/types/src/externalBook/IExternalBookCollection.d.ts

@@ -0,0 +1,29 @@
+import { ICollection } from '../type';
+import { IExternalBook } from './IExternalBook';
+/**
+ * The workbook's external books, in `[n]` order.
+ *
+ * @remarks
+ * **Positional, not an identity — see {@link IExternalBook}.** `[n]` in a formula is this
+ * collection's index at read time; nothing in the source file names a book any other way. Read-only
+ * for now: there is no `add`/`remove` here yet, matching the design doc's phase 1 scope (authoring
+ * arrives with the resolver API in a later phase).
+ */
+export interface IExternalBookCollection extends ICollection<IExternalBook> {
+    /**
+     * The book that formula text `[n]` (1-based) addresses, or `null` if `n` is beyond what was
+     * preserved on read, or its position is a DDE/OLE link (unmodeled — see {@link getItems}).
+     */
+    getByIndex(n: number): IExternalBook | null;
+    /**
+     * @returns The positional array, gaps included — `null` at index `i` means `[i+1]` is a DDE/OLE
+     * link or otherwise unmodeled, not that it is absent. `null` overall if there are no entries at
+     * all (nothing to preserve).
+     */
+    toJSON(): (IExternalBook.JSON | null)[] | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIExternalBookCollection: true;
+}
+//# sourceMappingURL=IExternalBookCollection.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from './IExternalBook';
+export * from './IExternalBookCollection';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,389 @@
+import { Properties as CSSProperties } from 'csstype';
+import { IColor } from '../color';
+/**
+ * *** **PLACEHOLDER** - Not yet implemented.
+ *
+ * Defines a single visual effect (shadow, glow, etc.) that can be applied to a shape, or to a
+ * theme's `effectStyleLst` entry.
+ *
+ * @remarks
+ * Covers DrawingML's "common" effect set — the effects real documents actually use on a shape or
+ * theme effect style: outer/inner/preset shadow, glow, soft edge, reflection. The broader
+ * alpha-/color-transform effect family (`alphaMod`, `duotone`, `blend`, etc.) is picture/blip
+ * adjustment territory, not modeled here.
+ */
+export interface IEffect {
+    /**
+     * Returns the type of effect.
+     */
+    getType(): IEffect.Type;
+    /**
+     * Returns the effect as a set of css strings that are suitable for css.
+     *
+     * @remarks
+     * Not all effect types will offer an exact css equivalent.
+     */
+    toCSS(mode?: IColor.CSSMode): CSSProperties;
+    /**
+     * Returns `true` if the effect is equal to the other effect.
+     */
+    isEqual(other: IEffect | null): boolean;
+    /**
+     * Returns the effect as a JSON object.
+     */
+    toJSON(): IEffect.JSON;
+}
+/**
+ * {@inheritDoc IEffect}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IEffect}
+ */
+export declare namespace IEffect {
+    /**
+     * Types of effects that can be applied to a shape or theme effect style.
+     */
+    const Type: {
+        /**
+         * A shadow cast outside the shape's outline.
+         */
+        readonly OuterShadow: "outerShadow";
+        /**
+         * A shadow cast inside the shape's outline.
+         */
+        readonly InnerShadow: "innerShadow";
+        /**
+         * One of a fixed set of built-in shadow presets (perspective shadows, etc.).
+         */
+        readonly PresetShadow: "presetShadow";
+        /**
+         * A colored, blurred outline drawn around the shape.
+         */
+        readonly Glow: "glow";
+        /**
+         * Blurs the edges of the shape.
+         */
+        readonly SoftEdge: "softEdge";
+        /**
+         * A reflection of the shape.
+         */
+        readonly Reflection: "reflection";
+    };
+    type Type = typeof Type[keyof typeof Type];
+    interface Properties {
+        /**
+         * @see
+         * {@link IEffect.getType}
+         */
+        type: IEffect.Type;
+    }
+    /**
+     * Modifiers describe a partial list of properties that can be set with values or shorthand strings.
+     */
+    type Modifiers = Partial<IEffect.Properties>;
+    /**
+     * Options for updating an effect.
+     */
+    type Update = IEffect | Modifiers | null;
+    /**
+     * A JSON representation useful for persistence.
+     */
+    interface JSON extends Properties {
+    }
+    /**
+     * Shared shape for the shadow family (`outerShdw`/`innerShdw`/`prstShdw`).
+     */
+    interface ShadowProperties<C = IColor.Serializable> extends IEffect.Properties {
+        /**
+         * The color of the shadow.
+         */
+        color: C;
+        /**
+         * How far the shadow is offset from the shape.
+         *
+         * @remarks
+         * Points. (`dist` in OOXML, EMU.)
+         */
+        distance?: number;
+        /**
+         * The direction the shadow is offset toward, in degrees.
+         *
+         * @remarks
+         * (`dir` in OOXML, 60,000ths of a degree.)
+         */
+        angle?: number;
+    }
+    /**
+     * A shadow cast outside the shape's outline.
+     */
+    interface IOuterShadow extends IEffect {
+        /**
+         * Effect type is always {@link IEffect.Type.OuterShadow}.
+         */
+        getType(): typeof IEffect.Type.OuterShadow;
+        toJSON(): OuterShadowJSON;
+    }
+    interface OuterShadowProperties<C = IColor.Serializable> extends IEffect.ShadowProperties<C> {
+        type: typeof IEffect.Type.OuterShadow;
+        /**
+         * The blur radius of the shadow.
+         *
+         * @remarks
+         * Points. (`blurRad` in OOXML, EMU.)
+         */
+        blur?: number;
+        /**
+         * The alignment of the shadow relative to the shape.
+         *
+         * @remarks
+         * (`algn` in OOXML — e.g. `'tl'`, `'ctr'`, `'br'`.)
+         */
+        alignment?: string;
+        /**
+         * Whether the shadow should rotate with the shape when the shape is rotated.
+         *
+         * @remarks
+         * (`rotWithShape` in OOXML.)
+         */
+        isRotatedWithShape?: boolean;
+        /**
+         * Horizontal scaling factor applied to the shadow.
+         *
+         * @remarks
+         * (`sx` in OOXML, a percentage.)
+         */
+        scaleX?: number;
+        /**
+         * Vertical scaling factor applied to the shadow.
+         *
+         * @remarks
+         * (`sy` in OOXML, a percentage.)
+         */
+        scaleY?: number;
+        /**
+         * Horizontal skew applied to the shadow, in degrees.
+         *
+         * @remarks
+         * (`kx` in OOXML.)
+         */
+        skewX?: number;
+        /**
+         * Vertical skew applied to the shadow, in degrees.
+         *
+         * @remarks
+         * (`ky` in OOXML.)
+         */
+        skewY?: number;
+    }
+    interface OuterShadowJSON extends OuterShadowProperties<string> {
+    }
+    /**
+     * A shadow cast inside the shape's outline.
+     */
+    interface IInnerShadow extends IEffect {
+        /**
+         * Effect type is always {@link IEffect.Type.InnerShadow}.
+         */
+        getType(): typeof IEffect.Type.InnerShadow;
+        toJSON(): InnerShadowJSON;
+    }
+    interface InnerShadowProperties<C = IColor.Serializable> extends IEffect.ShadowProperties<C> {
+        type: typeof IEffect.Type.InnerShadow;
+        /**
+         * The blur radius of the shadow.
+         *
+         * @remarks
+         * Points. (`blurRad` in OOXML, EMU.)
+         */
+        blur?: number;
+    }
+    interface InnerShadowJSON extends InnerShadowProperties<string> {
+    }
+    /**
+     * One of a fixed set of built-in shadow presets.
+     *
+     * @see {@link https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_PresetShadowVal_topic_ID0EN2WOB.html#topic_ID0EN2WOB}
+     */
+    interface IPresetShadow extends IEffect {
+        /**
+         * Effect type is always {@link IEffect.Type.PresetShadow}.
+         */
+        getType(): typeof IEffect.Type.PresetShadow;
+        toJSON(): PresetShadowJSON;
+    }
+    interface PresetShadowProperties<C = IColor.Serializable> extends IEffect.ShadowProperties<C> {
+        type: typeof IEffect.Type.PresetShadow;
+        /**
+         * The preset shadow to use.
+         *
+         * @remarks
+         * (`prst` in OOXML, `ST_PresetShadowVal`.)
+         */
+        preset: string;
+    }
+    interface PresetShadowJSON extends PresetShadowProperties<string> {
+    }
+    /**
+     * A colored, blurred outline drawn around the shape.
+     */
+    interface IGlow extends IEffect {
+        /**
+         * Effect type is always {@link IEffect.Type.Glow}.
+         */
+        getType(): typeof IEffect.Type.Glow;
+        toJSON(): GlowJSON;
+    }
+    interface GlowProperties<C = IColor.Serializable> extends IEffect.Properties {
+        type: typeof IEffect.Type.Glow;
+        /**
+         * The color of the glow.
+         */
+        color: C;
+        /**
+         * The radius of the glow.
+         *
+         * @remarks
+         * Points. (`rad` in OOXML, EMU.)
+         */
+        radius?: number;
+    }
+    interface GlowJSON extends GlowProperties<string> {
+    }
+    /**
+     * Blurs the edges of the shape.
+     */
+    interface ISoftEdge extends IEffect {
+        /**
+         * Effect type is always {@link IEffect.Type.SoftEdge}.
+         */
+        getType(): typeof IEffect.Type.SoftEdge;
+        toJSON(): SoftEdgeJSON;
+    }
+    interface SoftEdgeProperties extends IEffect.Properties {
+        type: typeof IEffect.Type.SoftEdge;
+        /**
+         * The radius of the soft edge.
+         *
+         * @remarks
+         * Points. (`rad` in OOXML, EMU.)
+         */
+        radius?: number;
+    }
+    interface SoftEdgeJSON extends SoftEdgeProperties {
+    }
+    /**
+     * A reflection of the shape.
+     */
+    interface IReflection extends IEffect {
+        /**
+         * Effect type is always {@link IEffect.Type.Reflection}.
+         */
+        getType(): typeof IEffect.Type.Reflection;
+        toJSON(): ReflectionJSON;
+    }
+    interface ReflectionProperties extends IEffect.Properties {
+        type: typeof IEffect.Type.Reflection;
+        /**
+         * The blur radius of the reflection.
+         *
+         * @remarks
+         * Points. (`blurRad` in OOXML, EMU.)
+         */
+        blur?: number;
+        /**
+         * How far the reflection is offset from the shape.
+         *
+         * @remarks
+         * Points. (`dist` in OOXML, EMU.)
+         */
+        distance?: number;
+        /**
+         * The direction the reflection is offset toward, in degrees.
+         *
+         * @remarks
+         * (`dir` in OOXML.)
+         */
+        angle?: number;
+        /**
+         * The direction to offset the reflection's fade, in degrees.
+         *
+         * @remarks
+         * (`fadeDir` in OOXML.)
+         */
+        fadeAngle?: number;
+        /**
+         * The starting opacity of the reflection, as a percentage.
+         *
+         * @remarks
+         * (`stA` in OOXML.)
+         */
+        startAlpha?: number;
+        /**
+         * The starting position of the reflection's opacity fade, as a percentage.
+         *
+         * @remarks
+         * (`stPos` in OOXML.)
+         */
+        startPosition?: number;
+        /**
+         * The ending opacity of the reflection, as a percentage.
+         *
+         * @remarks
+         * (`endA` in OOXML.)
+         */
+        endAlpha?: number;
+        /**
+         * The ending position of the reflection's opacity fade, as a percentage.
+         *
+         * @remarks
+         * (`endPos` in OOXML.)
+         */
+        endPosition?: number;
+        /**
+         * Horizontal scaling factor applied to the reflection.
+         *
+         * @remarks
+         * (`sx` in OOXML, a percentage.)
+         */
+        scaleX?: number;
+        /**
+         * Vertical scaling factor applied to the reflection.
+         *
+         * @remarks
+         * (`sy` in OOXML, a percentage.)
+         */
+        scaleY?: number;
+        /**
+         * Horizontal skew applied to the reflection, in degrees.
+         *
+         * @remarks
+         * (`kx` in OOXML.)
+         */
+        skewX?: number;
+        /**
+         * Vertical skew applied to the reflection, in degrees.
+         *
+         * @remarks
+         * (`ky` in OOXML.)
+         */
+        skewY?: number;
+        /**
+         * The alignment of the reflection relative to the shape.
+         *
+         * @remarks
+         * (`algn` in OOXML.)
+         */
+        alignment?: string;
+        /**
+         * Whether the reflection should rotate with the shape when the shape is rotated.
+         *
+         * @remarks
+         * (`rotWithShape` in OOXML.)
+         */
+        isRotatedWithShape?: boolean;
+    }
+    interface ReflectionJSON extends ReflectionProperties {
+    }
+}
+//# sourceMappingURL=IEffect.d.ts.map