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

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

@@ -1,5 +1,6 @@
 import { IResource, IResourceCollection } from '../resource';
 import { IModel, AbstractModel } from '../model';
+import { ITextFrame } from '../text/ITextFrame';
 import { IShape } from './IShape';
 interface State extends AbstractModel.State {
     data?: any;
@@ -8,6 +9,9 @@ interface State extends AbstractModel.State {
  * Implementation for {@link IShape}.
  */
 export declare class Shape extends AbstractModel<State, IShape.JSON> implements IShape {
+    /** The state `_facts` was read from; a new state object is a new read. */
+    private _factsSource;
+    private _facts;
     constructor(options: Shape.ConstructorOptions);
     /** {@inheritDoc IModel.getType} */
     getType(): string;
@@ -15,6 +19,12 @@ export declare class Shape extends AbstractModel<State, IShape.JSON> implements
     getName(): string;
     /** {@inheritDoc Movable.Content.getDescription} */
     getDescription(): string;
+    /** {@inheritDoc IShape.getShapeType} */
+    getShapeType(): string;
+    /** {@inheritDoc IShape.getTextFrame} */
+    getTextFrame(): ITextFrame.IText | null;
+    /** The captured fragment is read once per state, on first ask; most shapes are never asked. */
+    private _getFacts;
     /** {@inheritDoc Movable.Content.toJSON} */
     toJSON(_toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
     /** {@inheritDoc Movable.Content.getTypeDescription} */

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

@@ -0,0 +1,28 @@
+/**
+ * Reads the two facts a shape's captured DrawingML fragment can answer without a model behind
+ * it: the text written on the shape, and its preset geometry.
+ *
+ * @remarks
+ * An imported shape is kept as the source's markup ({@link IShape.JSON.xml}) and replayed on
+ * save, so this is a reader over a small fragment, not an XML library: elements, attributes and
+ * character data, matched by LOCAL name — prefixes are the producer's choice (`xdr:sp` and `a:t`
+ * are only Excel's). The fragment is a few kilobytes and was already parsed once, as part of a
+ * whole document, by the reader that captured it.
+ */
+/** What {@link readShapeXml} answers with. */
+export interface ShapeXmlFacts {
+    /** The root element's local name: `sp`, `cxnSp` or `grpSp`. */
+    element: string;
+    /** `prstGeom/@prst`, `'custom'` for a `custGeom`, or `null` when the fragment states neither. */
+    geometry: string | null;
+    /** The plain text, or `null` when the fragment has no text body at all. */
+    text: string | null;
+}
+/**
+ * Reads a captured shape fragment.
+ *
+ * @param xml The fragment as captured on import.
+ * @returns `null` when `xml` holds no element.
+ */
+export declare const readShapeXml: (xml: string) => ShapeXmlFacts | null;
+//# sourceMappingURL=_ShapeXml.d.ts.map

package/types/src/sheet/CellRegion.d.ts

@@ -12,6 +12,12 @@ import { ISheetInternal } from './Sheet';
  * from a date-formatted blank. The three scalars were retired from the vocabulary entirely —
  * `getStats()` already answers "how many numbers" better — and `Date` was replaced by
  * `DateFormat`, a real, directly indexed feature that just means what it says.)
+ *
+ * A name that is not a feature throws, with the vocabulary. An untyped caller — a script, an
+ * agent's expression — is not stopped by the type, and a name the partition does not know matches
+ * no cells: `getRegions('NumberFormat')` came back empty, which reads as "this sheet has no number
+ * formats". Spelling is matched case-insensitively and the canonical value is what comes back, so
+ * the enum's key (`NumberFormat`) resolves the same as its value (`numberFormat`).
  * @internal
  */
 export declare const resolveRegionFeatures: (features?: ICellRange.Feature | readonly ICellRange.Feature[]) => readonly ICellRange.Feature[];

package/types/src/sheet/ICellContainerOptions.d.ts

@@ -1,4 +1,5 @@
 import { IRuntime } from '@sheetxl/primitives';
+import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../transaction';
 import { IResourceCollection } from '../resource';
 import { IStringCollection } from '../string';
@@ -6,6 +7,7 @@ import { ICellRange } from '../cellRange';
 import { INamedCollection } from '../named';
 import { IStyleCollection } from '../style';
 import { ICalculation } from '../calculation';
+import { IExternalBook } from '../externalBook';
 import { IWorkbook } from '../workbook';
 /**
  * Contains a set of resources that can be shared across multiple cell containers.
@@ -49,8 +51,52 @@ export interface ICellContainerOptions {
     names?: INamedCollection;
     /**
      * Option to provide a custom calculation.
+     *
+     * @remarks
+     * Supplying one hands the container an engine it does not own. {@link functions},
+     * {@link formulaTransform} and {@link calcOnLoad} describe how to build the engine the
+     * container owns, so they are ignored when this is provided.
      */
     calculation?: ICalculation;
+    /**
+     * Additional custom formula function providers, bound after the built-ins (so they override
+     * built-ins on name collision). Each provider is the `initialize` binder produced by the
+     * FormulaCompiler (`@sheetxl/scripting`) for a folder of formula sources.
+     *
+     * @remarks
+     * Ignored when {@link calculation} is provided.
+     *
+     * @see {@link FunctionProvider}
+     */
+    functions?: readonly FunctionProvider[];
+    /**
+     * Opens the source of an external book on {@link IExternalBook.refresh} — see
+     * {@link IExternalBook.IResolver} for what it answers and the trust boundary it sits behind.
+     *
+     * @remarks
+     * Fixed for the workbook's life, as the engine it feeds is: a resolver is part of how a host
+     * sets a workbook up, not a setting a document carries. Without one every refresh answers
+     * `'unavailable'` and the caches stand. Ignored when {@link calculation} is provided.
+     */
+    externalBookResolver?: IExternalBook.IResolver;
+    /**
+     * What loading is allowed to calculate.
+     *
+     * @defaultValue `'auto'`
+     *
+     * @remarks
+     * - `'auto'` — the engine starts, cached values are trusted, and the load pass runs: a formula
+     *   cell with no cached value is evaluated (a repair) and volatiles refresh. Everything is
+     *   recalculated only when the file asks (`json.calc.fullCalcOnLoad`, workbooks only).
+     * - `'full'` — as `'auto'`, then everything is recalculated.
+     * - `'none'` — the engine is not started. Nothing is compiled or calculated; values stand as
+     *   loaded and formulas pass through to a save exactly as read. The first mutation, or an
+     *   explicit {@link ICalculation.calculate} / {@link IWorkbook.whenCalculationReady}, starts
+     *   the engine and applies what was deferred. Until then a formula READ answers `null`.
+     *
+     * Ignored when {@link calculation} is provided — a borrowed engine is started by its owner.
+     */
+    calcOnLoad?: ICellContainerOptions.CalcOnLoad;
     /**
      * If the parent has a workbook
      */
@@ -94,4 +140,8 @@ export interface ICellContainerOptions {
      */
     opener?: (url: string, target?: string, features?: string) => void;
 }
+export declare namespace ICellContainerOptions {
+    /** See {@link ICellContainerOptions.calcOnLoad}. */
+    type CalcOnLoad = 'auto' | 'full' | 'none';
+}
 //# sourceMappingURL=ICellContainerOptions.d.ts.map

package/types/src/sheet/ISheet.d.ts

@@ -4,32 +4,33 @@ import { ITypes } from '../type';
 import { ITransaction } from '../transaction';
 import { Tuple } from '../collections';
 import { IWorkbook } from '../workbook';
-import { IResourceCollection, IResource } from '../resource';
-import { IStringCollection } from '../string';
-import { IComment } from '../comment';
 import { IPrint } from '../print';
 import { IColor } from '../color';
 import { IListener } from '../listener';
 import { IHyperlink } from '../hyperlink';
-import { IMovable, IMovableCollection } from '../movable';
 import { IPicture } from '../picture';
+import { ISlicer } from '../slicer';
 import { ICell, ICellHeader } from '../cell';
 import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
+import { IRangeSelection } from '../selection';
 import { IStyleCollection } from '../style';
-import { ITableCollection, ITable } from '../table';
-import { IDataValidationCollection, IDataValidation } from '../dataValidation';
-import { ISlicer } from '../slicer';
+import { IStringCollection } from '../string';
+import { IResource, IResourceCollection } from '../resource';
+import { IMovable, IMovableCollection } from '../movable';
+import { IPivotTable, IPivotTableCollection } from '../pivot';
+import { IComment, ICommentCollection } from '../comment';
+import { ITable, ITableCollection } from '../table';
+import { IDataValidation, IDataValidationCollection } from '../dataValidation';
+import { IConditionalFormat, IConditionalFormatCollection } from '../conditionalFormat';
+import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
+import { IModule, IModuleCollection } from '../scripting';
+import { IChartCollection } from '../chart';
 import { INamedCollection } from '../named';
 import { ICalculation } from '../calculation';
-import { IRangeSelection } from '../selection';
 import { ISheetView } from '../sheetView';
 import { ISheetHeader } from '../sheetHeader';
 import { ISheetProtection } from '../sheetProtection';
 import { ICellContainerOptions } from './ICellContainerOptions';
-import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
-import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
-import { IProtectedRange } from '../protectedRange/IProtectedRange';
-import { IProtectedRangeCollection } from '../protectedRange/IProtectedRangeCollection';
 /**
  * An `ISheet` represents a collection of elements (such as {@link ICellRange | ranges},
  * {@link ITable | tables}, etc) contained within and visualized through a {@link ISheetView | view}.
@@ -197,10 +198,26 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * {@link ISheetProtection.isLocked} is true.
      */
     getProtectedRanges(): IProtectedRangeCollection;
+    /**
+     * Returns the comments and notes on this sheet.
+     *
+     * @remarks
+     * One per cell. The workbook's {@link IWorkbook.getComments} walks every sheet's.
+     */
+    getComments(): ICommentCollection;
     /**
      * Returns a collection of movables that are embedded in this sheet.
      */
     getMovables(): IMovableCollection;
+    /**
+     * Returns the charts on this sheet.
+     *
+     * @remarks
+     * A view over {@link ISheet.getMovables}: every chart is the content of a movable, which is what
+     * places and names it. Read-only for now — a chart is added by adding a movable with chart
+     * content.
+     */
+    getCharts(): IChartCollection;
     /**
      * Returns the row headers managed by the sheet.
      */
@@ -225,6 +242,64 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * * The tab color is not used by the sheet but rather by the workbook.
      */
     setTabColor(color: IColor | string | null): this;
+    /**
+     * The sheet's VBA code name, or `null` if it has none.
+     *
+     * @defaultValue null
+     *
+     * @remarks
+     * The identifier VBA binds a sheet through — `Sheet1.Range("A1")` in a macro resolves by code
+     * name, never by tab name. It is a **second, independent identity** for the sheet: renaming the
+     * tab does not change it, and it is not the sheet's position. Excel's default happens to look
+     * positional (`Sheet1`, `Sheet2`, …) but drifts from position the moment sheets are reordered,
+     * inserted or deleted, so it can only be carried — never derived.
+     *
+     * Present on any workbook that has, or has ever had, a VBA project: it survives the project
+     * being stripped, so an `.xlsx` saved down from an `.xlsm` still carries code names. A workbook
+     * that never had one has none, and this is `null` throughout.
+     *
+     * **Read-only.** SheetXL preserves what a file declared and never mints one — a code name is
+     * assigned by the VBA editor, and inventing one would create a binding target no macro refers
+     * to. There is deliberately no `setCodeName`.
+     */
+    getCodeName(): string | null;
+    /**
+     * How row and column groups are laid out on this sheet.
+     *
+     * @remarks
+     * Always fully populated: a sheet that declares nothing reports the defaults.
+     */
+    getOutlineSettings(): Readonly<ISheet.OutlineSettings>;
+    /**
+     * Whether conditional formats on this sheet are recalculated as the sheet changes.
+     *
+     * @defaultValue true
+     *
+     * @remarks
+     * Excel exposes this only to VBA (`Worksheet.EnableFormatConditionsCalculation`). It is carried
+     * so a workbook that turned it off keeps it off when saved; SheetXL still evaluates conditional
+     * formats either way.
+     */
+    isConditionalFormatCalculationEnabled(): boolean;
+    /**
+     * Returns the modules this sheet owns.
+     *
+     * @remarks
+     * A sheet's modules are stored by the sheet rather than tagged with its name, so the state a
+     * tag would allow — a module left behind pointing at a sheet that no longer exists — cannot
+     * occur: delete the sheet and its modules go with it, which is also what Excel does.
+     *
+     * These modules are scoped to the sheet ({@link IModule.getScope}), and scope is a visibility
+     * rule: a function declared here is **not** callable from a cell formula, on this sheet or any
+     * other. Only globally scoped modules contribute to the formula namespace.
+     *
+     * The VBA document module for this sheet lands here, joined to it by
+     * {@link ISheet.getCodeName} — for a document module the module name *is* the code name.
+     *
+     * As with {@link IWorkbook.getScripts}, the collection filters to TypeScript unless asked
+     * otherwise; imported VBA is read with `getItems({ language: 'vba' })`.
+     */
+    getModules(): IModuleCollection;
     /**
      * Returns the sheet protection.
      */
@@ -307,15 +382,16 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      *
      * @param expression The formula expression to parse.
      * @param coords Optional anchor coordinates.
+     * @param options Optional parse options; the expression is storage text unless `target` is `'display'`.
      *
      * @remarks
-     * This is a convenience method for `getCalculation().createFormula(expression, coords)`;
+     * This is a convenience method for `getCalculation().createFormula(expression, coords, options)`;
      * like everything reached through the sheet's {@link getCalculation}, a bare reference (`A2`)
      * resolves against THIS sheet rather than the selected one.
      *
      * @see {@link ICalculation.createFormula}
      */
-    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /**
      * Add Listeners.
      *
@@ -400,12 +476,15 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * @remarks
      * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
      */
-    evaluate(formula: string, options?: ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    evaluate(formula: string, options?: ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /**
      * Returns when all calculations are complete and there are no pending calculations.
      *
      * @remarks
-     * * This is a convenience method `getCalculation().ready()`.
+     * * Also waits for the load-time start: the pass {@link ICellContainerOptions.calcOnLoad} asks
+     *   for. This is the settle point after constructing from JSON.
+     * * Otherwise a convenience method for `getCalculation().ready()`, which starts the engine if
+     *   it has not been started.
      */
     whenCalculationReady(): Promise<ICalculation.Status>;
     /**
@@ -465,6 +544,14 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * Returns the picture interface for the sheet.
      */
     getPicture(): IPicture | null;
+    /**
+     * Returns the pivot tables laid out on this sheet, in the order they were read.
+     *
+     * @remarks
+     * Read-only for now: each table is carried as it was read and written back unchanged. The
+     * workbook's {@link IWorkbook.getPivotTables} walks every sheet's.
+     */
+    getPivotTables(): IPivotTableCollection;
     /**
      * Set the picture interface for the entire sheet.
      * @param picture The picture interface to set for the sheet, or null to remove it.
@@ -649,6 +736,14 @@ export declare namespace ISheet {
          * Always accompanied by the coarse {@link onProtectionChange}.
          */
         onProtectedRangesChange?(source: ISheet): void;
+        /**
+         * Called when a comment is added, removed, edited, resolved, replied to or re-anchored.
+         *
+         * @remarks
+         * Always accompanied by the coarse {@link onStyleChange}, since a cell paints its comment
+         * indicator.
+         */
+        onCommentsChange?(source: ISheet): void;
         /**
          * Called when the auto table is added or removed.
          */
@@ -823,13 +918,17 @@ export declare namespace ISheet {
          */
         ignoreData?: boolean;
         /**
-         * If `true` the resources will not be included in the JSON.
+         * How resources — images and the other binaries the sheet references — are written.
          *
-         * @remarks
-         * This is useful when exporting resources to another location and
-         * converting to base64 is not required.
+         * * `'embed'` serializes each one into the JSON, base64 encoded.
+         * * `'ignore'` writes every id as `0` and no resources.
+         * * An {@link IResource.Writer} puts each one wherever the caller wants and records what it
+         *   returns, so resources can be stored outside the JSON — uploaded and referenced by `uri`,
+         *   or emitted as parts of another format and referenced by id alone.
+         *
+         * @defaultValue 'embed'
          */
-        ignoreResources?: boolean;
+        resources?: 'embed' | 'ignore' | IResource.Writer;
         /**
          * If `true` the resources will not include formatting.
          *
@@ -860,17 +959,6 @@ export declare namespace ISheet {
          * Ignored if ignoreStyles is `true`.
          */
         splitDirectBorders?: boolean;
-        /**
-         * A structural transform applied to each formula as it serializes.
-         *
-         * @remarks
-         * Runs ONCE per formula block on the compiled AST (per-cell re-anchoring/re-imaging are
-         * unaffected); an all-`void` transform costs no recompile.
-         * Ignored if ignoreFormulas is `true`.
-         *
-         * @see {@link ICalculation.FormulaTransform}
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
     }
     /**
      * Optional values used in the construction of am {@link ISheet}.
@@ -896,12 +984,6 @@ export declare namespace ISheet {
          * Initial JSON.
          */
         json?: ISheet.JSON;
-        /**
-         * A structural transform applied once to each formula parsed from {@link json} — the READ
-         * half of the format-dialect hook (see `IWorkbook.ConstructorOptions.formulaTransform`).
-         * Load-time only; never applied to text typed or set after construction.
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
     }
     /**
      * Options needed for embedding a sheet into another container such as a workbook.
@@ -983,8 +1065,6 @@ export declare namespace ISheet {
         pageSetUpPr?: IPrint.PageSetUpProperties;
         /** {@inheritDoc IPrint.PrintOptions} */
         printOptions?: IPrint.PrintOptions;
-        /** {@inheritDoc IPrint.OutlineProperties} */
-        outlinePr?: IPrint.OutlineProperties;
         rowBreaks?: IPrint.Break[];
         colBreaks?: IPrint.Break[];
         phoneticPr?: {
@@ -993,6 +1073,60 @@ export declare namespace ISheet {
             type: string;
         };
     }
+    /**
+     * How row and column groups are laid out.
+     *
+     * @see {@link ISheet.getOutlineSettings}
+     */
+    interface OutlineSettings {
+        /**
+         * Whether a group's summary row sits below its detail rows. When `false` it sits above them.
+         *
+         * @defaultValue true
+         */
+        summaryBelow: boolean;
+        /**
+         * Whether a group's summary column sits to the right of its detail columns. When `false` it
+         * sits to the left.
+         *
+         * @defaultValue true
+         */
+        summaryRight: boolean;
+        /**
+         * Whether the expand and collapse buttons for groups are shown.
+         *
+         * @defaultValue true
+         */
+        showOutlineSymbols: boolean;
+        /**
+         * Whether the automatic outline styles are applied to summary rows and columns.
+         *
+         * @defaultValue false
+         */
+        applyStyles: boolean;
+    }
+    /**
+     * A drawing whose shapes are described in the origin format's own legacy vector markup rather
+     * than through {@link IMovable | movables}.
+     *
+     * @remarks
+     * A carrier, not a concept: what a spreadsheet keeps out of its main drawing — the box a note is
+     * displayed in, a form control's shape, and the pictures placed in a header or footer — held as
+     * one unit and put back on save, so a document that has them survives a round trip. Each piece
+     * folds into its own model as that lands (the note's box onto the note, the control's shape onto
+     * the control, the pictures onto the print header), and the carrier goes with the last of them.
+     *
+     * The markup is opaque: it is held as it was read and replayed unchanged, which also means the
+     * positions in it do not follow rows and columns that are inserted or deleted. Its images are
+     * carried by {@link IResource} id, each under the id the markup references it by.
+     */
+    interface LegacyDrawingJSON {
+        xml: string;
+        images?: {
+            id: string;
+            resId: number;
+        }[];
+    }
     /**
      * JSON representation of an `ISheet` used for serialization and deserialization.
      */
@@ -1031,7 +1165,17 @@ export declare namespace ISheet {
         styles?: IStyleCollection.JSON;
         resources?: IResource.JSON[];
         strings?: string[];
-        people?: IComment.PersonJSON[];
+        /**
+         * Modules owned by this sheet, keyed by module name.
+         *
+         * @see {@link ISheet.getModules}
+         */
+        modules?: Record<string, IModule.JSON>;
+        /**
+         * The comments and notes, one per cell, each thread with its replies.
+         *
+         * @see {@link ISheet.getComments}
+         */
         comments?: IRange.JSONReference<IComment.JSON>[];
         hyperlinks?: IRange.JSONReference<IHyperlink.JSON>[];
         /**
@@ -1061,7 +1205,46 @@ export declare namespace ISheet {
         protectedRanges?: IRange.JSONReference<IProtectedRange.JSON>[];
         movables?: IMovable.JSON[];
         tabColor?: string;
+        /**
+         * The sheet's VBA code name. Absent when it has none.
+         *
+         * @see {@link ISheet.getCodeName}
+         */
+        codeName?: string;
+        /**
+         * The outline settings that differ from their defaults.
+         *
+         * @see {@link ISheet.getOutlineSettings}
+         */
+        outline?: Partial<OutlineSettings>;
+        /**
+         * Present, as `false`, only when conditional format calculation is turned off.
+         *
+         * @see {@link ISheet.isConditionalFormatCalculationEnabled}
+         */
+        conditionalFormatCalculation?: boolean;
+        /**
+         * The sheet's picture.
+         */
         picture?: IPicture.JSON;
+        /**
+         * The sheet's legacy drawing: note boxes and form control shapes.
+         *
+         * @see {@link ISheet.LegacyDrawingJSON}
+         */
+        legacyDrawing?: LegacyDrawingJSON;
+        /**
+         * The legacy drawing for the sheet's header and footer, which holds their pictures.
+         *
+         * @see {@link ISheet.LegacyDrawingJSON}
+         */
+        legacyDrawingHF?: LegacyDrawingJSON;
+        /**
+         * The sheet's pivot tables.
+         *
+         * @see {@link ISheet.getPivotTables}
+         */
+        pivotTables?: IPivotTable.JSON[];
         protection?: ISheetProtection.JSON;
         view?: ISheetView.JSON;
         pageMargins?: Partial<IPrint.PageMargin>;

package/types/src/sheet/ISheetCollection.d.ts

@@ -17,11 +17,6 @@ export interface ISheetCollection extends ICollection<ISheet> {
      * @param options {@link ISheetCollection.GetItemsOptions}
      */
     getItems(options?: ISheetCollection.GetItemsOptions): ISheet[];
-    /**
-     * Returns the sheet at the given index.
-     * @param index
-     * @returns
-     */
     /**
      * Convenience method for filtering by name. This is
      * functionally equivalent to getItems({ name });
@@ -29,6 +24,8 @@ export interface ISheetCollection extends ICollection<ISheet> {
      * @param name The name to search for This is case insensitive.
      */
     getByName(name: string): ISheet | null;
+    /** For runtime type checking. */
+    readonly isISheetCollection: true;
 }
 /**
  * {@inheritDoc ISheetCollection}

package/types/src/sheet/NamedCellRange.d.ts

@@ -1,5 +1,6 @@
 import { ICellRanges } from '../cellRange';
-import { _NamedGraphNode } from '../cellRange/_GraphNode';
+import { NamedNodeInfo } from '../calculation/Types';
+import { INamedFormulasCollection } from '../calculation/INamedFormulasCollection';
 import { NamedRange } from './NamedRange';
 import { ISheetInternal } from './Sheet';
 import { SheetRangeOptions } from './SheetRange';
@@ -18,10 +19,18 @@ import { SheetRangeOptions } from './SheetRange';
  * The anchor matters to precedents (relative references in the body resolve from it) and is only
  * a label for dependents (the symbol index is global). Lead with the name when displaying one —
  * two names authored from the same active cell share an anchor address, and the name is the fact.
+ *
+ * Built from a {@link NamedNodeInfo} — plain data — and answers its five name questions by
+ * resolving the id against the collection when asked. It does NOT capture the name object: a name
+ * can be redefined or deleted while a graph answer is still held, and re-resolving means the
+ * answer follows the definition rather than a snapshot of it. A name that is gone answers `null`.
  */
 export declare class NamedCellRange extends NamedRange {
-    private readonly _node;
-    constructor(node: _NamedGraphNode, internal: ISheetInternal, options: SheetRangeOptions | null);
+    private readonly _info;
+    private readonly _namedFormulas;
+    constructor(info: NamedNodeInfo, namedFormulas: INamedFormulasCollection | null, internal: ISheetInternal, options: SheetRangeOptions | null);
+    /** The name this node stands for, or `null` if it no longer exists. @internal */
+    private _named;
     /**
      * {@inheritDoc INamedRange.getRanges}
      *
@@ -33,13 +42,13 @@ export declare class NamedCellRange extends NamedRange {
      */
     getRanges(): ICellRanges | null;
     /** {@inheritDoc ICellRange.getDirectPrecedents} */
-    getDirectPrecedents(): ICellRanges | null;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getPrecedents} */
-    getPrecedents(): ICellRanges | null;
+    getPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getDirectDependents} */
-    getDirectDependents(): ICellRanges | null;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getDependents} */
-    getDependents(): ICellRanges | null;
+    getDependents(): Promise<ICellRanges | null>;
     get [Symbol.toStringTag](): string;
 }
 //# sourceMappingURL=NamedCellRange.d.ts.map