@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

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

@@ -0,0 +1,230 @@
+import { ICollection } from '../type';
+import { IListener } from '../listener';
+import { ICellRanges } from '../cellRange';
+import { INamed } from './INamed';
+/**
+ * A collection of `INamed` items — defined names AND tables.
+ *
+ * @remarks
+ * **Which items it holds is decided by where you got it from, not by an option.** There is no scope
+ * argument anywhere on this interface:
+ *
+ * | 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 |
+ *
+ * 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.
+ * Both get it from `getItems()` with no arguments, which is the point — the scope question is
+ * answered by the call you make, so it cannot be got wrong by omitting an option.
+ *
+ * **Scope is visibility, never location.** A defined name lives on no sheet and may be visible
+ * 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
+ * the location question, and it has its own call.
+ *
+ * **Porting from Excel's Office Scripts.** Deliberately close but not identical. There,
+ * `Workbook.getNames()` is global-scoped names ONLY and `Worksheet.getNames()` is that sheet's own
+ * ONLY, with tables kept out of names entirely. Both of ours are supersets of their counterpart, so a
+ * direct port is over-inclusive rather than wrong — it will never see another sheet's private names.
+ * Filter on {@link INamed.getScope} (`null` = global) for exact parity.
+ */
+export interface INamedCollection extends ICollection<INamed> {
+    /**
+     * Define a name.
+     *
+     * @param name The name. Case insensitive, must be unique, and must not contain spaces.
+     * @param expression The expression to bind it to, with or without a leading `=`. A plain range
+     * address (`Sheet1!$A$1:$B$2`) is simply a reference expression.
+     * @param replaceExisting If `true`, redefine an existing name instead of throwing. *default* `false`.
+     * @throws `Error` if the name is invalid, or already exists and `replaceExisting` is not set.
+     *
+     * @remarks
+     * Created in the registry that owns defined names — the calculation engine — so it is the same
+     * kind of item as one loaded from a file, and `getType()` is `'formula'`. Use
+     * `ICalculation.INamedFormula.setExpression` to redefine it afterwards.
+     */
+    addFormula(name: string, expression: string, replaceExisting?: boolean): INamed;
+    /**
+     * Return the named items.
+     * These are sorted by type then by name.
+     */
+    getItems(options?: INamedCollection.GetItemsOptions): INamed[];
+    /**
+     * The reference text for every name that designates *exactly* the given ranges.
+     *
+     * @param ranges The ranges to match. Unqualified coords are read as being on the current scope
+     * (the selected sheet), which is what lets a sheet's own selection be passed straight through.
+     * @param options `includeParts` additionally matches the insides of an item — see
+     * {@link INamedCollection.GetByRangesOptions.includeParts}.
+     *
+     * @returns The names, whole-item matches first, then part references. Empty when nothing matches.
+     *
+     * @remarks
+     * The inverse of resolving a name: given a region, what is it called? This is what lets a name
+     * box show `Sales` in place of `$B$2:$C$3`, and what lets a formula editor substitute the name
+     * for an address the user picked by dragging.
+     *
+     * **Exact, not containing.** A selection *inside* `Sales` is not `Sales` — the ranges must
+     * coincide. Multi-range names match irrespective of the order the ranges are given in.
+     *
+     * **Text, not items.** A part has no `INamed` to return (`Sales[Amount]` is a structured
+     * reference, not an entry in this collection), so every match comes back as the text a formula
+     * would use. Several names may share one region, hence an array; callers wanting a single answer
+     * take the first.
+     */
+    getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
+    /**
+     * Lookup a named range with a given name.
+     *
+     * @param name Case insensitive name to lookup.
+     * @param global If `true` then will search all scopes. *default* `false`.
+     */
+    getByName(name: string, global?: boolean): INamed | null;
+    /**
+     * Lookup a named item by its unique stable id.
+     *
+     * @param id The id returned by {@link INamed.getId}.
+     */
+    getById(id: string): INamed | null;
+    /**
+     * Returns a new valid name given the name return a valid name that closely matches.
+     * This function works by incrementing either the last number or append a number.
+     *
+     * @param template The range to used as a template.
+     * @param scope The scope of the range. If null then this will look for a globally scoped. *default* `null`.
+     * @param ignoreExisting If true then won't check to see if the name is already used. *default* `false`.
+     * @throws `Error` If the template name is invalid.
+     * @returns A valid name. If the name used is valid then will return the same name.
+     */
+    findValidName(template: string, scope?: string, ignoreExisting?: boolean): string;
+    /**
+     * Validates a name is valid. This is a convenience method That calls `findValidName`
+     * and throws an error if the name returned is not the same.
+     *
+     * @throws `Error` If `findValidName` does not return the same value as the name checking.
+     *
+     * @see
+     * {@link INamedCollection.findValidName}
+     */
+    validateName(name: string, scope?: string, ignoreExisting?: boolean): void;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: INamedCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ITransaction.ITransactional.isClosed} */
+    isClosed(): boolean;
+    /** {@inheritDoc ITransaction.ITransactional.close} */
+    close(): void;
+    /**
+     * For runtime type checking.
+     */
+    readonly isINamedCollection: true;
+}
+/**
+ * {@inheritDoc INamedCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link INamedCollection}
+ */
+export declare namespace INamedCollection {
+    type JSON = INamed.JSON[];
+    interface Events {
+        /**
+         * Called when the names this collection holds, or the regions they designate, change.
+         *
+         * @remarks
+         * Not a per-item change event: editing a name's comment or hiding it does not surface here,
+         * and a consumer wanting that listens to the item.
+         *
+         * What a name *refers to* does surface, though — it is part of what the collection holds, and a
+         * consumer asking "what is this region called?" ({@link INamedCollection.getByRanges}) has
+         * nowhere else to hear about it. It cannot subscribe to an item it does not yet hold, and
+         * defining a name is two steps: it is added, and then bound to a region. Both are announced,
+         * as are a redefinition and an undo that moves one. So this can fire more than once for a
+         * single definition, and a listener that re-reads the collection is the intended response.
+         */
+        onCollectionChange?(source: INamedCollection): void;
+        /**
+         * Transaction items have a close event.
+         */
+        onClose?(source: INamedCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<INamedCollection, INamedCollection.Events> {
+    }
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * A string indicating the type.
+         */
+        type?: string;
+        /**
+         * Only items with this name, compared case-insensitively.
+         *
+         * @remarks
+         * Several items can share a name (a global and a sheet-scoped `Rate`), which is what makes
+         * this a filter rather than a lookup — {@link INamedCollection.getByName} answers the
+         * "which one wins" question; this returns every holder of the name. Mirrors
+         * `INamedFormulasCollection.getItems`.
+         */
+        name?: string;
+        /**
+         * Only items with this scope: a sheet name, or `null` for globally scoped items only.
+         *
+         * @remarks
+         * Filters on {@link INamed.getScope} — visibility, never location — and the KEY being present
+         * is what turns it on: `{ scope: null }` returns only global items, while omitting `scope`
+         * applies no filter at all. Mirrors `INamedFormulasCollection.getItems`.
+         */
+        scope?: string | null;
+        /**
+         * The search area.
+         *
+         * @defaultValue Search the global scope of the NamedCollection.
+         */
+        address?: ICellRanges.Address;
+        /**
+         * If true return any Named that is in the bounds even if only partially bounded.
+         *
+         * @defaultValue false
+         */
+        allowExtrudes?: boolean;
+        /**
+         * If 'true' then include hidden named ranges.
+         */
+        includeHidden?: boolean;
+    }
+    /**
+     * Options for {@link INamedCollection.getByRanges}.
+     *
+     * @remarks
+     * The same filters {@link GetItemsOptions} offers, minus the two that describe a *spatial* query:
+     * `address` is the method's own argument, and `allowExtrudes` loosens a match that this method
+     * defines as exact. Neither has a meaning here, so neither is accepted.
+     */
+    interface GetByRangesOptions extends Omit<GetItemsOptions, 'address' | 'allowExtrudes'> {
+        /**
+         * If `true` also match the *insides* of an item, returning a reference to the part.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * A table's column, header row, totals row and full extent are all addressable
+         * (`Sales[Amount]`, `Sales[#Headers]`, `Sales[#Totals]`, `Sales[#All]`) without being names in
+         * their own right. Off by default because the two consumers genuinely differ: a name box shows
+         * the address for a column selection, whereas a formula editor substituting a dragged range
+         * wants `Sales[Amount]`.
+         *
+         * Part references sort after whole-item matches — a real name beats a synthesized reference to
+         * the same region.
+         */
+        includeParts?: boolean;
+    }
+}
+//# sourceMappingURL=INamedCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"INamedCollection.d.ts","sourceRoot":"","sources":["../../../../src/named/INamedCollection.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,302 @@
+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>;
+    private _options;
+    private _transactions;
+    private _closed;
+    private _lastLookup;
+    private _lastLookupAddress;
+    private _lastLookupType;
+    private _lastIncludeHidden;
+    private _lastAllowExtrudes;
+    private _lastLookupName;
+    /** `undefined` means the scope key was absent — `null` is a real query (global items only). */
+    private _lastLookupScope;
+    private _lastLookupHasScope;
+    /** Resolves the registries to aggregate. Lazy — see {@link NamedCollection.ConstructorOptions.getSources}. */
+    private _getSources;
+    /** Last resolved set, and the subscriptions held against it. */
+    private _sources;
+    private _sourcesRemoveListeners;
+    constructor(options: NamedCollection.ConstructorOptions);
+    /**
+     * The registries to aggregate, resolving the callback and reconciling subscriptions.
+     *
+     * @remarks
+     * Resolved on every query rather than once at construction: the calculation engine takes this
+     * collection, so it does not exist yet when this is built. Laziness is what breaks that cycle —
+     * see {@link NamedCollection.ConstructorOptions.getSources}.
+     *
+     * **Push events.** A source mutating behind us has to drop the lookup memo and reach our
+     * listeners, or a cached result outlives the data it was built from. Subscriptions are rebuilt
+     * only when the resolved set actually changes, so re-resolving stays cheap and listeners are not
+     * churned on every read.
+     */
+    private _resolveSources;
+    /**
+     * The source that owns defined names — the one able to create them.
+     *
+     * @remarks
+     * `null` before the owner has wired one up — the sources resolve lazily, so this is reachable
+     * mid-construction. {@link addFormula} throws in that window rather than inventing a home for
+     * the name.
+     */
+    private _getOwningSource;
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<INamed>;
+    /** {@inheritDoc INamedCollection.getItems} */
+    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}. */
+    _getByRanges(ranges: ICellRanges.Address, options: INamedCollection.GetByRangesOptions | undefined, anchor: NamedCollection.Anchor | null): string[];
+    /**
+     * The address as sorted, sheet-qualified coords — the form an exact match can be made against.
+     *
+     * @remarks
+     * A named item's coords are always sheet-qualified, because a name is workbook-addressable and
+     * may span sheets. A *sheet's* coords — a selection, most of all — are local and carry no
+     * `scope` at all. Since `scope` is part of coords identity (`CoordUtils.isEqualRanges`, where the
+     * same row/col on two sheets are deliberately not equal), the two can never compare equal until
+     * the local side is qualified. An unqualified coord is read as being on the current scope, which
+     * is what lets `sheet.getSelection().getRanges()` be passed straight in.
+     *
+     * Sorted so that a multi-range name matches however the ranges were given — a user shift-picking
+     * the second range first still selected the same region.
+     */
+    private _qualifyCoords;
+    /**
+     * Every candidate item, across the pushed store and the injected sources.
+     *
+     * @param searchCoords The address filter, or `null` for everything.
+     */
+    private _collectCandidates;
+    /**
+     * Whether a source item overlaps the address filter.
+     *
+     * @remarks
+     * An item that designates no ranges — a value name like `=1`, or one whose formula has not been
+     * wired yet — is never a positional match, so an address query simply does not see it. It is
+     * still returned by an unfiltered query.
+     */
+    private _matchesCoords;
+    /** {@inheritDoc INamedCollection.getByName} */
+    getByName(name: string, global?: boolean): INamed | null;
+    /** {@link getByName}, against an explicit `scope` — see {@link _scopedTo}. */
+    _getByName(name: string, global?: boolean, scope?: string | null): INamed | null;
+    /** 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.
+     *
+     * @remarks
+     * The collection a sheet inside a workbook is given IS the workbook's, whose current scope is
+     * whichever sheet the UI has selected. Anything resolved against that scope — `getByName`, and
+     * `getByRanges`'s qualification of unqualified coords — therefore answered about the sheet on
+     * SCREEN rather than the sheet the caller reached it through. Same call, same arguments, different
+     * answer depending on which tab was active.
+     *
+     * Reached through a sheet, the sheet IS the context, so bind it. Mirrors the identical fix on
+     * `Sheet.getCalculation`; `IWorkbook.getNames()` is unchanged and stays workbook-current.
+     *
+     * The anchor is the live sheet, not a captured name, so the view keeps working across a rename.
+     * Everything not scope-sensitive is bound straight through to the real instance — one memo, one
+     * subscription set, so a source's invalidation can never leave a view holding a stale result.
+     *
+     * `getItems` filters rather than re-queries, so the underlying memo still serves every sheet's
+     * view; the filter itself is a linear pass over the tens of items a workbook has.
+     */
+    _scopedTo(anchor: NamedCollection.Anchor): INamedCollection;
+    /** {@inheritDoc INamedCollection.getById} */
+    getById(id: string): INamed | null;
+    /**
+     * First source item satisfying `predicate`, preferring one scoped to `preferScope` over a
+     * global one — matching how the pushed store is keyed.
+     */
+    private _findInSources;
+    /**
+     * Source item whose name AND scope match exactly — the same identity the pushed store keys on.
+     *
+     * @remarks
+     * Unlike {@link _findInSources} there is no global fallback: `Total` and `Sheet1!Total` are
+     * 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} */
+    validateName(named: string, scope?: string | null, ignoreExisting?: boolean): void;
+    _validateName(name: string, scope: string | null, ignoreExisting?: boolean): void;
+    /**
+     * {@inheritDoc INamedCollection.addFormula}
+     *
+     * @remarks
+     * 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
+     * {@link _scopedTo}.
+     */
+    addFormula(name: string, expression: string, replaceExisting?: boolean): INamed;
+    /** {@link addFormula}, against an explicit `scope` — see {@link _scopedTo}. */
+    _addFormula(name: string, expression: string, replaceExisting?: boolean, scope?: string | null): INamed;
+    /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
+    beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    /**
+     * Drops the memoized `getItems` result.
+     *
+     * @remarks
+     * Invoked for a local write AND for a source's `onCollectionChange` — the memo is keyed only on
+     * the query arguments, so anything that changes the underlying items has to clear it.
+     */
+    private _invalidateLookup;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: INamedCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    isClosed(): boolean;
+    close(): void;
+    /**
+     * {@inheritDoc INamedCollection.isINamedCollection}
+     *
+     * @remarks
+     * A getter rather than a field so it survives {@link _scopedTo}: the proxy returns non-function
+     * properties straight through, which is what lets a sheet-scoped view be brand-checked like the
+     * real collection.
+     */
+    get isINamedCollection(): true;
+}
+/**
+ * {@inheritDoc NamedCollection}
+ */
+export declare namespace NamedCollection {
+    /**
+     * The sheet a {@link NamedCollection._scopedTo} view is anchored to — what "here" means for a query
+     * that does not say.
+     *
+     * @remarks
+     * Structural rather than `ISheet` 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.
+     */
+    interface Anchor {
+        getName(): string;
+        getRanges(address: ICellRanges.Address): ICellRanges | null;
+    }
+    /**
+     * A registry that contributes named items to the aggregating collection.
+     *
+     * @remarks
+     * `NamedCollection` is a pure aggregator: it owns nothing and queries its sources — defined names
+     * from the calculation engine, tables from their own collection, later shapes / charts / pictures.
+     * Each source keeps its own items; nothing is mirrored here, so there is only ever one copy of a
+     * name.
+     *
+     * **Pull data, push events.** {@link Source.getItems} is called on demand rather than cached, and
+     * {@link Source.addListeners} lets the aggregator invalidate and re-emit when a source changes.
+     *
+     * Deliberately minimal: a source returns everything it has and the aggregator does all filtering
+     * (by address, scope, type, hidden). Defined names number in the tens, so a linear scan beats
+     * making every source maintain a query surface — or a second index.
+     *
+     * Not on `INamedCollection`: how the aggregate is assembled is an implementation concern, and
+     * consumers only ever see the aggregate.
+     */
+    interface Source {
+        /**
+         * Every item this source contributes, unfiltered.
+         */
+        getItems(): readonly INamed[];
+        /**
+         * Notified when items are added, removed, renamed or re-scoped.
+         *
+         * @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.
+         */
+        addListeners(listeners: {
+            onCollectionChange?: (...args: any[]) => void;
+        }, options?: IListener.Options): IListener.Remove;
+        /**
+         * Creates a name owned by this source, if it can own one.
+         *
+         * @remarks
+         * Only the source that owns *defined names* implements this — the calculation engine. It backs
+         * {@link INamedCollection.addFormula}, so a name added through the workbook API lands in the
+         * same registry as one loaded from a file. A source of derived names (tables, and later shapes
+         * / charts) leaves it undefined; those are named by the thing they belong to.
+         */
+        add?(options: NamedCollection.AddNamedOptions): INamed;
+    }
+    /**
+     * What {@link Source.add} needs to define a name.
+     *
+     * @remarks
+     * Structurally a subset of the calculation engine's own add options, so
+     * `ICalculation.getNamedFormulas()` satisfies {@link Source} with no adapter.
+     */
+    interface AddNamedOptions {
+        name: string;
+        /** The expression the name is bound to. A plain range address is just a reference expression. */
+        expression: string;
+        scope?: string | null;
+        comment?: string;
+        hidden?: boolean;
+        /** Redefine an existing name in the same scope instead of throwing. */
+        replaceExisting?: boolean;
+    }
+    interface ConstructorOptions {
+        /**
+         * The registries this collection aggregates — see {@link Source}.
+         *
+         * @remarks
+         * A callback, not an array, because ownership is genuinely circular: the calculation engine
+         * takes this collection (it resolves table symbols through it), so it cannot exist when this
+         * is constructed. Resolving lazily lets the owner close the loop without a second wiring call.
+         *
+         * **Must tolerate being called before the other side exists.** It runs on every query and on
+         * `addListeners`, and the engine subscribes to this collection while it is still constructing —
+         * so the first call happens mid-cycle, by design. Return an empty array until ready; the next
+         * call picks the sources up.
+         *
+         * ```ts
+         * let workbook: IWorkbook;
+         * const names = new NamedCollection({
+         *   getSources: () => workbook ? [workbook.getCalculation().getNamedFormulas()] : [],
+         *   ...
+         * });
+         * workbook = new Workbook({ names });
+         * ```
+         *
+         * Re-invoked on each query and cheap to implement — the result is compared against the live
+         * subscriptions, and only an actual change re-subscribes.
+         */
+        getSources?: () => readonly NamedCollection.Source[];
+        /**
+         * Required to resolve ranges.
+         */
+        addressToRanges: (address: ICellRanges.Address) => ICellRanges;
+        /**
+         * Returns the current scope.
+         */
+        getCurrentScope?: () => string;
+        /**
+         * A transaction store that can be used to undo/redo changes to the names.
+         */
+        transactions?: ITransaction.IStore;
+        /**
+         * If the collection is readonly.
+         */
+        isReadOnly?: () => boolean;
+    }
+}
+//# sourceMappingURL=NamedCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NamedCollection.d.ts","sourceRoot":"","sources":["../../../../src/named/NamedCollection.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,6 @@
+/** These all start with '_xlnm'. and are case-insensitive. */
+export declare const _BuiltInNamed: {
+    key: string;
+    description: string;
+}[];
+//# sourceMappingURL=_BuiltInNamed.d.ts.map

package/types/src/named/_BuiltInNamed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_BuiltInNamed.d.ts","sourceRoot":"","sources":["../../../../src/named/_BuiltInNamed.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAE9D,eAAO,MAAM,aAAa;;;GAgBzB,CAAC"}

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

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

package/types/src/named/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/named/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC"}

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

@@ -0,0 +1,49 @@
+/**
+ * ECMA-376 §18.8.30 built-in number formats (numFmtId -> format code).
+ *
+ * Engine-agnostic DATA shared by the format engines, IO (xlsx numFmtId
+ * round-trip), and the UI preset tables.
+ *
+ * Storage model styles STORE the numeric id when the format is a built-in
+ * (Excel's own model — styles.xml only writes ids >= 164) and a format-code
+ * string otherwise.
+ * Resolution to a code happens at the render/classification boundary via
+ * {@link resolveNumberFormat}.
+ */
+/**
+ * A number format reference: either an ECMA-376 built-in id (number) or a
+ * format-code string.
+ */
+export type NumberFormatRef = string | number;
+/** The first id available for custom formats (ids below are reserved built-ins). */
+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).
+ *
+ * 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.
+ */
+export declare const LOCALE_ADAPTIVE_IDS: ReadonlySet<number>;
+/** The raw ECMA table lookup, or `undefined` for unknown ids. */
+export declare function getBuiltInFormatCode(id: number): string | undefined;
+/**
+ * Resolve a {@link NumberFormatRef} to a format-code string.
+ *
+ * Strings pass through; built-in ids resolve via the ECMA table (unknown ids
+ * resolve to `'General'`, matching Excel's behavior for unmapped ids).
+ *
+ * @remarks Locale-ADAPTIVE rendering of ids 14/22 is a value-level concern
+ * handled before engines format (see `toLocaleDateCore`) — this function
+ * always returns the canonical code.
+ */
+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.
+ */
+export declare function findBuiltInFormatId(code: string): number | undefined;
+//# sourceMappingURL=BuiltInFormats.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BuiltInFormats.d.ts","sourceRoot":"","sources":["../../../../src/numFmt/BuiltInFormats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuFjE,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAKlD,CAAC;AAEH,iEAAiE;AACjE,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAGhE;AAWD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE"}