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

package/types/src/calculation/symbol/ISymbolRegistry.d.ts

@@ -10,6 +10,29 @@ export declare const SymbolType: {
 };
 export type SymbolType = typeof SymbolType[keyof typeof SymbolType];
 export interface SheetCtx {
+    /**
+     * Resolve to the form a READER sees rather than the form a formula is stored as.
+     *
+     * @remarks
+     * The two differ only for an external book: stored is `[n]Sheet1`, where `n` is a position
+     * projected from the book's place in the collection, and display is the book's own spelling
+     * (`'C:\dir\[Book.xlsx]Sheet1'`). A local sheet has one name and ignores this.
+     */
+    display?: boolean;
+    /**
+     * Bind is AUTHORING: a scope that names an external book this workbook has none of may create
+     * one (`'C:\dir\[Book.xlsx]Sheet1'` typed into a cell is how a link is made — DESIGN-EXTERNAL-LINKS
+     * §5 step 13). Off by default, and off for an editing compile, so a keystroke mints nothing; a
+     * local sheet is never minted.
+     */
+    mint?: boolean;
+    /**
+     * The formula being linked belongs to an external BOOK — a cached defined name's body — so a
+     * plain sheet name (`Alpha`) is that book's sheet, never one of this workbook's, and a `[n]`
+     * position cites the source's own links, which this workbook cannot see (`null`). Nothing is
+     * minted inside a book.
+     */
+    book?: string;
 }
 export interface NamedFormulaCtx {
     /** The stableId of the sheet that owns the formula scope, if any. */

package/types/src/calculation/symbol/IndirectSymbolProvider.d.ts

@@ -57,6 +57,11 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      */
     private readonly _getByName;
     private readonly _getById;
+    /**
+     * The name an item goes by for this provider's reader - what a bind matches and a resolve
+     * displays. The item's own name unless the reader holds a copy of the names of its own.
+     */
+    private readonly _nameOf;
     private _byName;
     private _byId;
     /**
@@ -79,7 +84,12 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      * shadowing (a name scoped to that sheet beats a global of the same name). Providers with no
      * scoped items — tables — may ignore it.
      */
-    _getByName: (name: string, scope?: string | null) => T | null, _getById: (id: string) => T | null);
+    _getByName: (name: string, scope?: string | null) => T | null, _getById: (id: string) => T | null, 
+    /**
+     * The name an item goes by for this provider's reader - what a bind matches and a resolve
+     * displays. The item's own name unless the reader holds a copy of the names of its own.
+     */
+    _nameOf?: (item: T) => string);
     /**
      * @inheritdoc ISymbolProvider.bind
      *
@@ -98,8 +108,12 @@ export declare class IndirectSymbolProvider<T extends INamed.INamedValue = IName
      * it heals to turns out to be scoped.
      *
      * A miss on `_byName` is not proof the item has no proxy — see {@link _byRealId}.
+     *
+     * `ctx.existing: true` asks only whether the name is an item NOW: it answers `null` rather than
+     * minting a proxy for a name nothing holds. For a caller deciding what a spelling IS (a bare name
+     * that may be a table) — a proxy minted for every other name would never heal into anything.
      */
-    bind(displayName: string, ctx?: Record<string, unknown>): string;
+    bind(displayName: string, ctx?: Record<string, unknown>): string | null;
     /** Points a proxy at its real item, keeping {@link _byRealId} in step. */
     private _adopt;
     /** Moves a proxy to the `_byName` key its current name/scope spell. */

package/types/src/calculation/symbol/SheetSymbolProvider.d.ts

@@ -2,17 +2,77 @@ import { IRange } from '@sheetxl/primitives';
 import { ISymbolProvider, SymbolHandle } from './ISymbolRegistry';
 /**
  * Strict provider for sheet symbols.
+ *
+ * @remarks
+ * An EXTERNAL sheet is a sheet symbol too. A scope this workbook has no sheet for, and which names
+ * a book (`[1]Sheet1`, `C:\dir\[Book.xlsx]Sheet1`), falls through to `_getExternal` rather than to a
+ * `SymbolType` of its own — the twenty-odd consumers of a scope all ask this provider, and teaching
+ * one provider a second spelling touches none of them (DESIGN-EXTERNAL-LINKS §4B).
+ *
+ * So is a 3-D span (`Alpha:Gamma`, PLAN-3D-REFS §2.1): one symbol naming its two endpoint sheets,
+ * `<firstId>:<lastId>`, with the endpoints in tab order.
  */
 export declare class SheetSymbolProvider implements ISymbolProvider {
     private readonly _getId;
     private readonly _getById;
-    constructor(_getId: (displayName: string) => string | null, _getById: (sheetId: string) => SheetSymbolHandle | null);
+    private readonly _external?;
+    /** A sheet's position in tab order, hidden sheets included, or `-1`. */
+    private readonly _getIndexById?;
+    constructor(_getId: (displayName: string) => string | null, _getById: (sheetId: string) => SheetSymbolHandle | null, _external?: (ExternalSheetSymbols | null) | undefined, 
+    /** A sheet's position in tab order, hidden sheets included, or `-1`. */
+    _getIndexById?: ((sheetId: string) => number) | null | undefined);
     /** @inheritdoc ISymbolProvider.bind */
-    bind(displayName: string, _ctx: Record<string, unknown>): string | null;
+    bind(displayName: string, ctx?: Record<string, unknown>): string | null;
     /** @inheritdoc ISymbolProvider.resolve */
-    resolve(stableId: string, _ctx: Record<string, unknown>): SheetSymbolHandle | null;
+    resolve(stableId: string, ctx?: Record<string, unknown>): SheetSymbolHandle | null;
+    /**
+     * `First:Last` (names or ids) to a span id with the endpoints in tab order, the plain sheet id when
+     * both ends are one sheet (`Alpha:Alpha` is `Alpha`, as Excel normalizes it), or `null` when either
+     * end is not a sheet of this workbook.
+     */
+    private _bindSpan;
+    /** One end of a span: a sheet's id or name, never a virtual grid (which has no name). */
+    private _bindEndpoint;
+    private _resolveSpan;
+}
+/**
+ * The two endpoint sheet ids of a LOCAL span id (`<firstId>:<lastId>`), or `null` if it is not one.
+ *
+ * @remarks
+ * A sheet id is `<name>-<uuid>` and a sheet name cannot contain `:`, so a `:` in a non-external id is
+ * the separator. Both halves must end in a uuid: typed text that never bound (`Alpha:Nope`) reaches
+ * `resolve` too, and must not be mistaken for a span whose sheets are gone.
+ */
+export declare function splitSheetSpanSymbolId(stableId: string | null | undefined): [string, string] | null;
+/**
+ * What a local span id becomes when tab order changes from `before` to `after` — `undefined` when it
+ * stands.
+ *
+ * @remarks
+ * An endpoint that is gone, or that `movedId` carried across the other endpoint, is replaced by its
+ * inward neighbor in `before`: the nearest sheet between the endpoints that is still there. When both
+ * ends land on one sheet the answer is that sheet's plain id, as Excel collapses `Alpha:Beta` to
+ * `Beta!A1`. A span that lost every sheet stands too; it has nothing to shrink to.
+ */
+export declare function replaceSheetSpanEndpoints(spanId: string, before: readonly string[], after: readonly string[], movedId?: string): string | undefined;
+/** Whether a sheet stable id is a 3-D span — local `<firstId>:<lastId>` or external `ext:<bookId>:<i>:<j>`. */
+export declare function isSpanSymbolId(stableId: string | null | undefined): boolean;
+/** The external-book half of {@link SheetSymbolProvider}, supplied by `Calculation`. */
+export interface ExternalSheetSymbols {
+    /**
+     * `mint`: a scope naming a book this workbook has none of may CREATE one — see {@link SheetCtx.mint}.
+     * `withinBook`: the id of the book a plain sheet name belongs to — see {@link SheetCtx.book}.
+     */
+    bind(displayName: string, mint: boolean, withinBook?: string | null): string | null;
+    resolve(stableId: string, display: boolean): SheetSymbolHandle | null;
 }
 export interface SheetSymbolHandle extends SymbolHandle {
     getEntireCoords(): IRange.Coords | null;
+    /**
+     * The sheet's own name, `null` for a sheet that has none. `toString` is the DISPLAY form and
+     * substitutes a placeholder for a nameless sheet; a caller that means to bind or compare a
+     * name reads this instead. Absent on a handle that is not a sheet (a virtual grid).
+     */
+    getName?(): string | null;
 }
 //# sourceMappingURL=SheetSymbolProvider.d.ts.map

package/types/src/calculation/symbol/SymbolRegistry.d.ts

@@ -16,4 +16,24 @@ export declare class SymbolRegistry implements ISymbolRegistry {
     /** @inheritdoc ISymbolRegistry.resolve */
     resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
 }
+/**
+ * A registry that answers some symbol types from providers of its own and every other from a base.
+ *
+ * @remarks
+ * The model's symbol map (DESIGN-CALC-SERVICE §8) is this over the engine's: the types the engine
+ * keeps a copy of resolve through the model's live items here, while the rest resolve through the
+ * engine's providers. Registering a provider registers it on the base, so a provider that arrives
+ * late (the functions, once their module loads) is seen by both.
+ */
+export declare class OverlaidSymbolRegistry implements ISymbolRegistry {
+    private readonly _base;
+    private readonly _overrides;
+    constructor(_base: ISymbolRegistry, _overrides: ReadonlyMap<SymbolType, ISymbolProvider>);
+    /** @inheritdoc ISymbolRegistry.registerProvider */
+    registerProvider(type: SymbolType, provider: ISymbolProvider): void;
+    /** @inheritdoc ISymbolRegistry.bind */
+    bind(type: SymbolType, displayName: string, ctx?: Record<string, unknown>): string | null;
+    /** @inheritdoc ISymbolRegistry.resolve */
+    resolve(type: SymbolType, stableId: string, ctx?: Record<string, unknown>): SymbolHandle | null;
+}
 //# sourceMappingURL=SymbolRegistry.d.ts.map

package/types/src/calculation/symbol/index.d.ts

@@ -1,7 +1,8 @@
 export { type ISymbolRegistry, type ISymbolProvider, type SymbolHandle, SymbolType } from './ISymbolRegistry';
 export { type SheetCtx, type NamedFormulaCtx, type TableCtx, type ColumnCtx, type FunctionCtx } from './ISymbolRegistry';
-export { SymbolRegistry } from './SymbolRegistry';
-export { SheetSymbolProvider } from './SheetSymbolProvider';
+export { SymbolRegistry, OverlaidSymbolRegistry } from './SymbolRegistry';
+export { SheetSymbolProvider, isSpanSymbolId, splitSheetSpanSymbolId, replaceSheetSpanEndpoints, type SheetSymbolHandle, type ExternalSheetSymbols } from './SheetSymbolProvider';
+export { EXTERNAL_ID_PREFIX, isExternalSymbolId, splitExternalSymbolId, externalSymbolId, bindExternalScope, resolveExternalSymbol, mintedBookOptions, type ExternalBookMinter } from './ExternalSheetSymbols';
 export { TableSymbolProvider } from './TableSymbolProvider';
 export { IndirectSymbolProvider, IndirectProxy } from './IndirectSymbolProvider';
 export { TableColumnSymbolProvider } from './TableColumnSymbolProvider';

package/types/src/calculation/toolkit/FormulaLiteralReader.d.ts

@@ -0,0 +1,4 @@
+import { Scalar } from '@sheetxl/primitives';
+/** {@link parseFormulaLiteral}, with the toolkit loaded. */
+export declare function readFormulaLiteral(text: string): Scalar | undefined;
+//# sourceMappingURL=FormulaLiteralReader.d.ts.map

package/types/src/calculation/toolkit/FormulaTextParser.d.ts

@@ -0,0 +1,10 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { FormulaText } from '../FormulaText';
+/** {@link FormulaText.parse}, with the toolkit loaded. */
+export declare function parse(text: string, options?: FormulaText.ParseOptions): ICalculation.FormulaNode | null;
+/** {@link FormulaText.transform}, with the toolkit loaded. */
+export declare function transform(root: ICalculation.FormulaNode, transform: ICalculation.FormulaTransform): ICalculation.FormulaNode;
+/** {@link FormulaText.imager}, with the toolkit loaded. */
+export declare function imager(root: ICalculation.FormulaNode, options?: Omit<FormulaText.ImageOptions, 'at'>): (at?: IRange.CellCoords) => string;
+//# sourceMappingURL=FormulaTextParser.d.ts.map

package/types/src/calculation/toolkit/FunctionDeclarationTable.d.ts

@@ -0,0 +1,4 @@
+import { FunctionDeclarations } from '../functions/FunctionDeclarations';
+/** A built-in function's declaration, or `null` when no built-in has that name. Not case sensitive. */
+export declare function getFunctionDeclaration(name: string): FunctionDeclarations.Declared | null;
+//# sourceMappingURL=FunctionDeclarationTable.d.ts.map

package/types/src/calculation/toolkit/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The formula toolkit's code: the parser, the printer, the literal reader and the built-in
+ * declarations, behind `FormulaText`, `parseFormulaLiteral` and `FunctionDeclarations`.
+ *
+ * @remarks
+ * Loaded by `FormulaText.load()` and by a calculation's start, never carried from import
+ * (DESIGN-CALC-SERVICE §13.25). Only `_FormulaToolkit` imports it.
+ */
+export { parse, transform, imager } from './FormulaTextParser';
+export { readFormulaLiteral } from './FormulaLiteralReader';
+export { getFunctionDeclaration } from './FunctionDeclarationTable';
+//# sourceMappingURL=index.d.ts.map