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

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

@@ -0,0 +1,37 @@
+import { Bounds } from '@sheetxl/utils';
+/** Edges of a box in a movable's frame, in pixels; they may lie outside the frame. */
+export interface FrameRect {
+    l: number;
+    t: number;
+    r: number;
+    b: number;
+}
+/**
+ * Content that can paint outside its frame (a shape: a callout's tail, its line).
+ *
+ * @remarks
+ * Answers synchronously from what it last evaluated, or `null` before it has; `onReady` is called
+ * when a newer answer is ready.
+ */
+export interface DrawnContent {
+    _getDrawnRect(width: number, height: number, onReady: () => void): FrameRect | null;
+}
+export declare const isDrawnContent: (content: unknown) => content is DrawnContent;
+/**
+ * The box a movable paints on the sheet: `rect` (its frame when absent), mirrored in the frame as
+ * `flip` states, placed in the unrotated `frame`, turned by `rotation` degrees clockwise about the
+ * frame's center.
+ */
+export declare const drawnBounds: (frame: Bounds, rect: FrameRect | null, rotation: number, flip?: {
+    horizontal: boolean;
+    vertical: boolean;
+}) => Bounds;
+/**
+ * How far `drawn` reaches past `anchor` on its farthest side, in pixels; `0` when it stays inside.
+ */
+export declare const overhang: (anchor: Bounds, drawn: Bounds) => number;
+/** Whether two boxes overlap or touch. */
+export declare const isBoundsIntersect: (a: Bounds, b: Bounds) => boolean;
+export declare const getDrawnVersion: () => number;
+export declare const bumpDrawnVersion: () => void;
+//# sourceMappingURL=_DrawnBounds.d.ts.map

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

@@ -0,0 +1,39 @@
+import { IMovable } from './IMovable';
+import { IMovableCollection } from './IMovableCollection';
+import { IResource, IResourceCollection } from '../resource';
+/**
+ * A movable collection whose add is in two parts: the waiting, then an insert that does not wait.
+ *
+ * @remarks
+ * {@link IMovableCollection.add} waits for the kind to load, and for a picture's image to decode,
+ * before it inserts. An operation that runs inside a transaction cannot wait there - a paste, or a
+ * delete that dissolves a group - so it does the waiting first ({@link _prepare},
+ * {@link _preparePicture}), or knows there is none, and then inserts with {@link _insertNow}.
+ *
+ * @internal
+ */
+export interface InsertableCollection {
+    /**
+     * Everything {@link IMovableCollection.add} waits for, answered as the options
+     * {@link _insertNow} takes: the kind loaded, the position settled.
+     */
+    _prepare(options: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /**
+     * Everything {@link IMovableCollection.addPicture} waits for, answered as the options
+     * {@link _insertNow} takes: the image decoded and sized, the kind loaded, the position settled.
+     */
+    _preparePicture(picture: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /** Inserts a movable as {@link IMovableCollection.add} does, once its kind is loaded. */
+    _insertNow(options: InsertableCollection.InsertOptions): IMovable;
+}
+export declare namespace InsertableCollection {
+    interface InsertOptions extends IMovableCollection.AddOptions {
+        /**
+         * Where in the collection's z-order the movable goes; those at and above it move up one.
+         *
+         * @defaultValue on top
+         */
+        zIndex?: number;
+    }
+}
+//# sourceMappingURL=_InsertableCollection.d.ts.map

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

@@ -1,4 +1,9 @@
 import { Point, Bounds } from '@sheetxl/utils';
 import { IMovableCollection } from './IMovableCollection';
+/**
+ * The shift that keeps a new movable from landing on one already there: while a movable's top-left
+ * is within {@link SAME_SPOT} px of the destination's, step down and right, so repeated inserts
+ * cascade instead of stacking.
+ */
 export declare function nonOverlappingOffset(movables: IMovableCollection, destination: Bounds, shiftX?: boolean, shiftY?: boolean): Point;
 //# sourceMappingURL=_MovableUtils.d.ts.map

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

@@ -0,0 +1,25 @@
+import { CustomElement } from './CustomElement';
+/**
+ * The stand-in a movable places while its content's kind is still loading
+ * ({@link MovableContentRegistry.Lazy}): positioned, named and saved as it was read, and
+ * read-only, so nothing done to it can be lost when the real content takes its place.
+ */
+export declare class PendingContent extends CustomElement {
+    constructor(options: CustomElement.ConstructorOptions & {
+        type: string;
+    });
+    /** {@inheritDoc IModel.isReadOnly} */
+    isReadOnly(): boolean;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
+    getTypeDescription(): string;
+}
+/**
+ * Tracks a content load until it settles, so a reader can wait for every movable it made to hold
+ * its real content ({@link whenContentSettled}).
+ */
+export declare function trackContentLoad(promise: Promise<unknown>): void;
+/**
+ * Resolves once every content load in flight has settled, including any a settling load starts.
+ */
+export declare function whenContentSettled(): Promise<void>;
+//# sourceMappingURL=_PendingContent.d.ts.map

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

@@ -0,0 +1,55 @@
+import { Bounds } from '@sheetxl/utils';
+import { IMovable } from './IMovable';
+import { Movable } from './Movable';
+/**
+ * The placement math of a movable that holds movables, as DrawingML states it: a group's frame
+ * maps its child space (`chOff`/`chExt`) by a scale per axis, and its rotation and flips turn and
+ * mirror what is drawn in the frame.
+ *
+ * @remarks
+ * A member's own answers ({@link IMovable.getBounds}, {@link IMovable.getRotation},
+ * {@link IMovable.getFlip}) are already where it is drawn; this is what a group maps them with.
+ */
+export declare namespace PlacementUtils {
+    /**
+     * Where a member lands in its group's container, from where the group lands there and where the
+     * member sits in the group's child space.
+     *
+     * @remarks
+     * The member's center is scaled into the frame and its unrotated size with it. Under an uneven
+     * scale a member turned by about a quarter turn takes the y factor for its width and the x
+     * factor for its height, so it is not sheared, as PowerPoint places it (SHAPES-DESIGN §11.3).
+     * The group's flips then mirror the member's position in the frame, and its rotation turns it
+     * about the frame's center. The member's rotation is composed with the group's, reversed under
+     * one mirror since a mirror conjugates a turn into its inverse, and its flips are toggled by the
+     * group's.
+     *
+     * @param parent Where the group sits in its container: its unrotated frame, rotation and flips.
+     * @param childSpace The group's child space, in which `local` is stated.
+     * @param local Where the member sits in the child space.
+     * @returns Where the member sits in the group's container.
+     */
+    const placeInParent: (parent: Movable.Placement, childSpace: Bounds, local: Movable.Placement) => Movable.Placement;
+    /**
+     * The inverse of {@link placeInParent}: where a member must sit in the child space to land at
+     * `placed` in the group's container.
+     */
+    const placeInChild: (parent: Movable.Placement, childSpace: Bounds, placed: Movable.Placement) => Movable.Placement;
+    /** The box of `bounds` turned by `rotation` degrees about its center. */
+    const rotatedBox: (bounds: Bounds, rotation: number) => Bounds;
+    /** The smallest box holding every one of `boxes`; `null` for none. */
+    const unionBounds: (boxes: readonly Bounds[]) => Bounds | null;
+    /**
+     * How far apart, in pixels, two placements may be and still be the same: far below one EMU
+     * (1/9525 px), the finest a file states, so only the noise of mapping out of a group and back
+     * is ignored.
+     */
+    const EPSILON = 0.000001;
+    /** Whether `a` and `b` are the same box, within {@link EPSILON}. */
+    const isSameBounds: (a: Bounds, b: Bounds) => boolean;
+    /** A placement with no turn and no mirror at `bounds`. */
+    const flatPlacement: (bounds: Bounds) => Movable.Placement;
+    /** Where a movable is drawn, as one placement; `null` before it is laid out. */
+    const placementOf: (movable: IMovable) => Movable.Placement | null;
+}
+//# sourceMappingURL=_PlacementUtils.d.ts.map

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

@@ -0,0 +1,20 @@
+import { Bounds } from '@sheetxl/utils';
+/**
+ * Whether a rotation is within 45° of a quarter turn (90° or 270°), in either direction.
+ *
+ * @remarks
+ * Excel's anchor of a rotated drawing is the box of the drawing as rotated, and Excel does not
+ * compute a true rotated bounding box: within 45° of a quarter turn the anchor is the unrotated
+ * frame with its width and height swapped, otherwise it is the frame itself. The same rule
+ * places a member rotated by a quarter turn in a group that is scaled unevenly.
+ */
+export declare const isQuarterTurn: (rotation: number) => boolean;
+/**
+ * Between a drawing's unrotated frame and its anchor, the box it occupies as rotated: within 45°
+ * of a quarter turn the sides are swapped about the same center, otherwise the box is unchanged.
+ *
+ * @remarks
+ * Its own inverse, so it maps a frame to its anchor and an anchor to its frame.
+ */
+export declare const swapForRotation: (bounds: Bounds, rotation: number) => Bounds;
+//# sourceMappingURL=_RotatedFrame.d.ts.map

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

@@ -1,4 +1,10 @@
 export * from './IMovable';
 export * from './IMovableCollection';
-export * from './IMovableSelection';
+export * from './IErrorContent';
+export * from './MovableContentRegistry';
+export * from './AbstractMovableContent';
+/**
+ * @hidden
+ */
+export * from './IFormControl';
 //# sourceMappingURL=index.d.ts.map

package/types/src/named/AbstractNamed.d.ts

@@ -13,7 +13,7 @@ export interface State extends AbstractModel.State {
 /**
  * Abstract implementation of `INamed`.
  */
-export declare abstract class AbstractNamed<T, S extends State, VIEW extends AbstractModel.CommitView = AbstractModel.CommitView, EVENTS extends IModel.Events = INamed.Events> extends AbstractModel<S, INamed.JSON, VIEW, EVENTS> implements INamed<T> {
+export declare abstract class AbstractNamed<T, S extends State, EVENTS extends IModel.Events = INamed.Events> extends AbstractModel<S, INamed.JSON, EVENTS> implements INamed<T> {
     /** {@inheritDoc INamed.select} */
     abstract select(options?: ITypes.SelectOptions): Promise<this>;
     /** {@inheritDoc INamed.getRanges} */

package/types/src/named/INamed.d.ts

@@ -67,6 +67,9 @@ export interface INamed<T = any> extends IModel {
      * A reference to a *part* of this item that the given coords designate exactly, or `null`.
      *
      * @param coords The coords to match, sheet-qualified (`scope`) and in row-first order.
+     * @param home The cell of the formula the reference is for, when there is one. A reference can be
+     *   written relative to it: `Sales[@Amount]` for a table cell in the formula's own row, and from
+     *   inside the table `[@Amount]` and `[Amount]`.
      *
      * @remarks
      * * Optional
@@ -79,7 +82,7 @@ export interface INamed<T = any> extends IModel {
      * Implemented by whatever owns the parts (a table), so the collection stays out of the business
      * of knowing what kinds of items have insides.
      */
-    getPartReference?(coords: readonly IRange.Coords[]): string | null;
+    getPartReference?(coords: readonly IRange.Coords[], home?: IRange.CellCoords | null): string | null;
     /**
      * If true then the name is not visible.
      *
@@ -220,6 +223,36 @@ export declare namespace INamed {
          * This is interpreted by the named item
          */
         ref?: string;
+        /** {@inheritDoc INamed.FileAttributes} */
+        fileAttributes?: INamed.FileAttributes;
+    }
+    /**
+     * What a file says about a defined name beyond its value: macro bindings, Excel 4.0 and
+     * publishing flags. Kept and written back as read; none of it changes how the name evaluates.
+     */
+    interface FileAttributes {
+        /** The name is a macro function (rather than a command). */
+        function?: boolean;
+        /** The name's macro is a VBA procedure. */
+        vbProcedure?: boolean;
+        /** The name is an Excel 4.0 (XLM) macro, or a `_xlpm.` lambda parameter Excel marks the same way. */
+        xlm?: boolean;
+        /** The category the macro function is listed under. */
+        functionGroupId?: number;
+        /** The keyboard shortcut that runs the macro. */
+        shortcutKey?: string;
+        /** The menu text for the macro. */
+        customMenu?: string;
+        /** The description of the macro. */
+        description?: string;
+        /** The help topic for the macro. */
+        help?: string;
+        /** The status bar text for the macro. */
+        statusBar?: string;
+        /** The name is published to a server with the workbook. */
+        publishToServer?: boolean;
+        /** The name is a parameter a server-side workbook takes. */
+        workbookParameter?: boolean;
     }
 }
 //# sourceMappingURL=INamed.d.ts.map

package/types/src/named/INamedCollection.d.ts

@@ -1,3 +1,4 @@
+import { IRange } from '@sheetxl/primitives';
 import { ICollection } from '../type';
 import { IListener } from '../listener';
 import { ICellRanges } from '../cellRange';
@@ -12,7 +13,7 @@ import { INamed } from './INamed';
  * | Reached through        | Holds                                                          |
  * | ---------------------- | -------------------------------------------------------------- |
  * | {@link IWorkbook.getNames} | EVERY named item in the workbook, whatever its scope        |
- * | {@link ISheet.getNames}    | only what is visible FROM that sheet — the global items (tables included) plus that sheet's own, shadowing resolved |
+ * | {@link IWorksheet.getNames}    | only what is visible FROM that sheet — the global items (tables included) plus that sheet's own, shadowing resolved |
  *
  * The two exist because the two consumers genuinely differ: a name manager lists everything that
  * exists, while a formula editor may only offer what a formula written *here* can actually refer to.
@@ -23,7 +24,7 @@ import { INamed } from './INamed';
  * everywhere or on exactly one sheet. A table lives ON a sheet but its name is always visible
  * everywhere and workbook-unique — so `getScope()` is `null` for every table, and tables appear in
  * BOTH collections. That is not a special case: they are globally visible, so they turn up wherever
- * globally visible items do. For the tables anchored to one sheet, ask `ISheet.getTables()` — that is
+ * globally visible items do. For the tables anchored to one sheet, ask `IWorksheet.getTables()` — that is
  * the location question, and it has its own call.
  *
  * **Porting from Excel's Office Scripts.** Deliberately close but not identical. There,
@@ -152,6 +153,21 @@ export declare namespace INamedCollection {
          * single definition, and a listener that re-reads the collection is the intended response.
          */
         onCollectionChange?(source: INamedCollection): void;
+        /**
+         * Called when an undo or a redo has moved what this collection presents, and a consumer holding
+         * it needs to re-read.
+         *
+         * @remarks
+         * Separate from {@link onCollectionChange} because a restore is not a write, and some listeners
+         * treat the two very differently: the calculation engine recalculates on a change, and firing
+         * that for a restore would recalculate a second time on top of the one the restore already did.
+         * A consumer rendering a LIST wants both, and subscribes to both.
+         *
+         * A derived name is what makes this necessary. A table's name is read back off the table rather
+         * than stored here, so an undo of a rename moves no state of this collection's and a
+         * change-only listener hears nothing.
+         */
+        onInvalidated?(source: INamedCollection): void;
         /**
          * Transaction items have a close event.
          */
@@ -225,6 +241,16 @@ export declare namespace INamedCollection {
          * the same region.
          */
         includeParts?: boolean;
+        /**
+         * The cell of the formula a part reference is for.
+         *
+         * @remarks
+         * Only read with `includeParts`. A table cell in the formula's own row is a this-row reference
+         * (`Sales[@Amount]`), and inside the table a single column drops the table name (`[Amount]`,
+         * `[@Amount]`). Without it every part is qualified (`Sales[Amount]`) and a row's cells are
+         * addresses.
+         */
+        home?: IRange.CellCoords | null;
     }
 }
 //# sourceMappingURL=INamedCollection.d.ts.map

package/types/src/named/NamedCollection.d.ts

@@ -1,18 +1,16 @@
+import { AbstractCollection } from '../type';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { ICellRanges } from '../cellRange';
 import { INamed, INamedCollection } from '../named';
-import { ListenerEmitter } from '../listener/ListenerEmitter';
 export declare const REGEX_INVALID_NAME_FIRST_CHARS: RegExp;
 export declare const REGEX_INVALID_NAME_TRAILING_CHARS: RegExp;
 /**
  * Implementation for `INamedCollection`.
  */
-export declare class NamedCollection implements INamedCollection {
-    protected _emitter: ListenerEmitter<this, INamedCollection.IListeners>;
+export declare class NamedCollection extends AbstractCollection<INamed, INamedCollection.GetItemsOptions> implements INamedCollection {
     private _options;
-    private _transactions;
-    private _closed;
+    protected _transactions: ITransaction.IStore;
     private _lastLookup;
     private _lastLookupAddress;
     private _lastLookupType;
@@ -51,10 +49,8 @@ export declare class NamedCollection implements INamedCollection {
      * the name.
      */
     private _getOwningSource;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<INamed>;
-    /** {@inheritDoc INamedCollection.getItems} */
-    getItems(options?: INamedCollection.GetItemsOptions): INamed[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: INamedCollection.GetItemsOptions): INamed[];
     /** {@inheritDoc INamedCollection.getByRanges} */
     getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
     /** {@link getByRanges}, against an explicit anchor — see {@link _scopedTo}. */
@@ -96,7 +92,7 @@ export declare class NamedCollection implements INamedCollection {
     /** The scope an unqualified query is read against — the collection's own, unless {@link _scopedTo}. */
     private _currentScope;
     /**
-     * A view of this collection anchored to ONE scope — what `ISheet.getNames()` hands out.
+     * A view of this collection anchored to ONE scope — what `IWorksheet.getNames()` hands out.
      *
      * @remarks
      * The collection a sheet inside a workbook is given IS the workbook's, whose current scope is
@@ -131,8 +127,6 @@ export declare class NamedCollection implements INamedCollection {
      * distinct names, so a scoped query must not report the global one as a hit.
      */
     private _findInSourcesByKey;
-    /** {@inheritDoc ICollection.getCount} */
-    getCount(): number;
     /** {@inheritDoc INamedCollection.findValidName} */
     findValidName(template: string, scope?: string | null, ignoreExisting?: boolean): string;
     /** {@inheritDoc INamedCollection.validateName} */
@@ -145,7 +139,7 @@ export declare class NamedCollection implements INamedCollection {
      * Global. Asked of the WORKBOOK, "add a name" means a workbook name — deliberately NOT
      * {@link _currentScope}, which follows the selected tab: reading against the sheet on screen is
      * right for a query and would be a trap for a write, silently scoping a name to whichever tab
-     * happened to be active. `ISheet.getNames()` is where a scoped one comes from — see
+     * happened to be active. `IWorksheet.getNames()` is where a scoped one comes from — see
      * {@link _scopedTo}.
      */
     addFormula(name: string, expression: string, replaceExisting?: boolean): INamed;
@@ -163,7 +157,7 @@ export declare class NamedCollection implements INamedCollection {
     private _invalidateLookup;
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: INamedCollection.IListeners, options?: IListener.Options): IListener.Remove;
-    isClosed(): boolean;
+    /** {@inheritDoc INamedCollection.close} */
     close(): void;
     /**
      * {@inheritDoc INamedCollection.isINamedCollection}
@@ -184,7 +178,7 @@ export declare namespace NamedCollection {
      * that does not say.
      *
      * @remarks
-     * Structural rather than `ISheet` to keep this module free of that import; a sheet satisfies it.
+     * Structural rather than `IWorksheet` to keep this module free of that import; a sheet satisfies it.
      * Both members matter and for different reasons: `getName` is the scope a name resolves against,
      * and `getRanges` is what a bare address like `'A1'` is read on.
      */
@@ -217,14 +211,21 @@ export declare namespace NamedCollection {
          */
         getItems(): readonly INamed[];
         /**
-         * Notified when items are added, removed, renamed or re-scoped.
+         * Notified when items are added, removed, renamed or re-scoped (`onCollectionChange`), and when
+         * an undo or a redo has moved them (`onInvalidated`).
          *
          * @remarks
-         * The aggregator re-emits this as its own `onCollectionChange`, which is also what drops its
-         * lookup memo — a source changing behind a cached result is otherwise invisible.
+         * The aggregator re-emits each as its own event of the same name, and either drops its lookup
+         * memo — a source changing behind a cached result is otherwise invisible.
+         *
+         * A source that has no restore of its own to report may implement only the first; one whose
+         * items are DERIVED (tables) has to report both, because an undo of a rename moves nothing this
+         * collection holds. The two stay separate all the way through: consumers of a restore and
+         * consumers of a write are not the same set.
          */
         addListeners(listeners: {
             onCollectionChange?: (...args: any[]) => void;
+            onInvalidated?: (...args: any[]) => void;
         }, options?: IListener.Options): IListener.Remove;
         /**
          * Creates a name owned by this source, if it can own one.
@@ -236,6 +237,18 @@ export declare namespace NamedCollection {
          * / charts) leaves it undefined; those are named by the thing they belong to.
          */
         add?(options: NamedCollection.AddNamedOptions): INamed;
+        /**
+         * Resolves what `items` designate in one step, ahead of a loop that asks each item's
+         * `getRanges()` in turn.
+         *
+         * @remarks
+         * For a source whose items compile on first use (a file's defined names): asked one at a time,
+         * each compile is its own operation, and a file carrying thousands of names makes an address
+         * query cost thousands of operations. The source batches them; items that are not its own, or
+         * that answer from their text already, it leaves alone. A source whose items are derived has
+         * nothing to prepare and leaves it undefined.
+         */
+        prepareRanges?(items: readonly INamed[]): void;
     }
     /**
      * What {@link Source.add} needs to define a name.
@@ -288,7 +301,7 @@ export declare namespace NamedCollection {
         /**
          * Returns the current scope.
          */
-        getCurrentScope?: () => string;
+        getCurrentScope?: () => string | null;
         /**
          * A transaction store that can be used to undo/redo changes to the names.
          */

package/types/src/numFmt/BuiltInFormats.d.ts

@@ -20,14 +20,22 @@ export declare const FIRST_CUSTOM_FORMAT_ID = 164;
 export declare const BUILT_IN_FORMAT_CODES: Readonly<Record<number, string>>;
 /**
  * Ids whose rendering adapts to the viewer's regional settings in Excel (the
- * `*`-prefixed formats in the Format Cells dialog, currency symbol ids, and
- * the regional/CJK 27-36 & 50-58 ranges).
+ * `*`-prefixed formats in the Format Cells dialog, currency symbol ids, the
+ * date/time ids Excel renders with a per-locale pattern, and the regional/CJK
+ * 27-36 & 50-58 ranges).
  *
- * Today only 14/22 render adaptively (via the Intl interception in
- * `toLocaleDateCore`); the rest resolve to their canonical en-US codes.
- * I18N-DESIGN Plane 1 substitutes LocaleProfile-derived patterns here.
+ * The date/time ids render through {@link getLocaleBuiltInFormatCode} where a
+ * locale's pattern is known, and 14/22 fall back to `Intl` otherwise
+ * (`toLocaleDateCore`). The rest resolve to their canonical en-US codes.
  */
 export declare const LOCALE_ADAPTIVE_IDS: ReadonlySet<number>;
+/**
+ * The code a built-in id renders with in `locale`, or `undefined` when the
+ * locale is not measured or renders the canonical code.
+ *
+ * @param locale BCP-47 tag. @defaultValue 'en-US'
+ */
+export declare function getLocaleBuiltInFormatCode(id: number, locale?: string): string | undefined;
 /** The raw ECMA table lookup, or `undefined` for unknown ids. */
 export declare function getBuiltInFormatCode(id: number): string | undefined;
 /**
@@ -42,8 +50,13 @@ export declare function getBuiltInFormatCode(id: number): string | undefined;
  */
 export declare function resolveNumberFormat(ref: NumberFormatRef): string;
 /**
- * Find the built-in id for a format code (exact match, lowest id wins), or
- * `undefined` if the code is not a built-in.
+ * The preset names a format may be given by (`Short Date`, `Fixed`), and the code or built-in
+ * id each stands for. A name is not a code: its letters are not tokens.
+ */
+export declare const XMLFormatMap: Readonly<Record<string, string | number>>;
+/**
+ * Find the built-in id Excel saves a format code as, or `undefined` if Excel
+ * saves it as a custom format.
  */
 export declare function findBuiltInFormatId(code: string): number | undefined;
 //# sourceMappingURL=BuiltInFormats.d.ts.map

package/types/src/numFmt/IFormatEngine.d.ts

@@ -138,6 +138,8 @@ export interface IFormatEngine {
     getFormatDateInfo(format: NumberFormatRef): FormatDateInfo | null;
     /** True if the format code parses (usable for live custom-code validation). */
     isValidFormat(format: NumberFormatRef): boolean;
+    /** For runtime type checking. */
+    readonly isIFormatEngine: true;
 }
 /**
  * The number-format engine.

package/types/src/numFmt/NumberFormatParser.d.ts

@@ -51,6 +51,11 @@ export interface ParsedRun {
     type: ParseRunType;
     width: number;
     text: string;
+    /**
+     * The CSS `letter-spacing` (px at the style's size) that paints `text` at `width`; see
+     * `IFont.ExtendedMetrics.renderLetterSpacing`. Absent or `0` where paint already matches.
+     */
+    letterSpacing?: number;
 }
 export interface ParsedRuns {
     runs: readonly ParsedRun[];

package/types/src/numFmt/NumfmtFormatEngine.d.ts

@@ -29,5 +29,7 @@ export declare class NumfmtFormatEngine implements IFormatEngine {
     getFormatDateInfo(format: NumberFormatRef): FormatDateInfo | null;
     /** @inheritdoc IFormatEngine.isValidFormat */
     isValidFormat(format: NumberFormatRef): boolean;
+    /** {@inheritDoc IFormatEngine.isIFormatEngine} */
+    get isIFormatEngine(): true;
 }
 //# sourceMappingURL=NumfmtFormatEngine.d.ts.map

package/types/src/numFmt/_FormatCell.d.ts

@@ -1,9 +1,18 @@
 import { ScalarType, Scalar, IRuntime } from '@sheetxl/primitives';
 import { IColor } from '../color';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { NumberFormatRef } from './BuiltInFormats';
 import { Parsed, ParserOptions } from './NumberFormatParser';
-export declare function parseNumberFormat(runtime: IRuntime, value: Scalar, style: IStyle, type: ScalarType, numberFormat: NumberFormatRef, parseColor: (val: any) => IColor): Parsed;
+/**
+ * The text a value shows under a number format: the `displayText` of {@link parseNumberFormat}
+ * without a cell or its style.
+ *
+ * @remarks
+ * For a reader of many cells that wants only their text (a filter judging a column): what a cell
+ * shows follows from its value and its format, and a run of cells shares the format.
+ */
+export declare function formatDisplayText(runtime: IRuntime, value: Scalar, numberFormat: NumberFormatRef): string;
+export declare function parseNumberFormat(runtime: IRuntime, value: Scalar, style: ICellStyle, type: ScalarType, numberFormat: NumberFormatRef, parseColor: (val: any) => IColor): Parsed;
 /**
  * The unformatted text for a number.
  *

package/types/src/numFmt/_NumFmtUtils.d.ts

@@ -43,7 +43,6 @@ export declare function toLocaleDateCore(format: NumberFormatRef, value: number,
     fmt: string;
     date: Date;
 } | null;
-export declare const XMLFormatMap: Readonly<Record<string, string | number>>;
 /**
  * Returns a legacy color as an rgb value
  */

package/types/src/numFmt/vendor/numfmt/_sheetxl.d.ts

@@ -13,3 +13,9 @@ export declare function roundDisplay(value: number, places: number): number;
 
 /** §3a — `String(value)` with the exponential form expanded to plain decimal notation. */
 export declare function toDecimalString(value: number): string;
+
+/**
+ * Which calendar (`date`) and clock (`time`) parts a format code evaluates, read off the
+ * parser. Neither for a code whose only date tokens are elapsed ones, and for an illegal code.
+ */
+export declare function dateTimeParts(pattern: string): { readonly date: boolean, readonly time: boolean };