@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/font/IFont.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Namespace for fonts
+ *
+ * {@link IFont}
+ */
+export declare namespace IFont {
+    /**
+     * Specifies the style of the font (normal, italic).
+     */
+    const Style: {
+        /**
+         * The standard, non-italicized font style.
+         */
+        readonly Normal: "normal";
+        /**
+         * The italicized font style.
+         */
+        readonly Italic: "italic";
+    };
+    type Style = typeof Style[keyof typeof Style];
+    /**
+     * Specifies the font scheme, indicating its role in the document's typography.
+     */
+    const Scheme: {
+        /**
+         * The primary font used for headings and major text elements.
+         */
+        readonly Major: "major";
+        /**
+         * The secondary font used for body text and less prominent elements.
+         */
+        readonly Minor: "minor";
+        /**
+         * No specific font scheme is assigned.
+         */
+        readonly None: "none";
+    };
+    type Scheme = typeof Scheme[keyof typeof Scheme];
+    /**
+     * The character set a font was authored against.
+     *
+     * @remarks
+     * These are the Windows `LOGFONT.lfCharSet` values. The character set does not change which
+     * characters a cell contains - the text is always Unicode - it is a hint used to pick a
+     * substitute face when the named one is not installed, so a workbook authored in a Simplified
+     * Chinese locale still resolves to a font with the glyphs it needs.
+     *
+     * Any value in `0-255` is legal; the named ones are the sets Excel writes.
+     */
+    const Charset: {
+        /** Windows-1252 / Latin-1. */
+        readonly Ansi: 0;
+        /** Whatever the system locale implies. */
+        readonly Default: 1;
+        /** The face is a symbol font (Symbol, Wingdings); its code points are not Unicode text. */
+        readonly Symbol: 2;
+        /** Mac OS Roman. */
+        readonly Mac: 77;
+        /** Japanese (Shift-JIS). */
+        readonly ShiftJIS: 128;
+        /** Korean (Wansung). */
+        readonly Hangul: 129;
+        /** Korean (Johab). */
+        readonly Johab: 130;
+        /** Simplified Chinese (GB2312). */
+        readonly GB2312: 134;
+        /** Traditional Chinese (Big5). */
+        readonly ChineseBig5: 136;
+        /** Greek. */
+        readonly Greek: 161;
+        /** Turkish. */
+        readonly Turkish: 162;
+        /** Vietnamese. */
+        readonly Vietnamese: 163;
+        /** Hebrew. */
+        readonly Hebrew: 177;
+        /** Arabic. */
+        readonly Arabic: 178;
+        /** Baltic. */
+        readonly Baltic: 186;
+        /** Cyrillic. */
+        readonly Russian: 204;
+        /** Thai. */
+        readonly Thai: 222;
+        /** Central European. */
+        readonly EastEurope: 238;
+        /** The font's own OEM code page. */
+        readonly Oem: 255;
+    };
+    /**
+     * A {@link IFont.Charset} value. Not narrowed to the named sets - any `0-255` value is legal.
+     */
+    type Charset = number;
+    /**
+     * Specifies the style of underline applied to text.
+     */
+    const UnderlineStyle: {
+        /**
+         * No underline.
+         */
+        readonly None: "none";
+        /**
+         * A double underline.
+         */
+        readonly Double: "double";
+        /**
+         * A double underline used in accounting contexts (typically thicker and below the descenders).
+         */
+        readonly DoubleAccounting: "doubleAccounting";
+        /**
+         * A single underline.
+         */
+        readonly Single: "single";
+        /**
+         * A single underline used in accounting contexts (typically below the descenders).
+         */
+        readonly SingleAccounting: "singleAccounting";
+    };
+    type UnderlineStyle = typeof UnderlineStyle[keyof typeof UnderlineStyle];
+    /**
+     * Vertical alignment of text within a line.
+     * @see
+     * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align}
+     */
+    const VerticalAlignment: {
+        /**
+         * Aligns the baseline of the cell with the baseline of all other cells in the row that are baseline-aligned.
+         */
+        readonly Baseline: "baseline";
+        /**
+         * Aligns the baseline of the element with the subscript-baseline of its parent.
+         */
+        readonly Sub: "sub";
+        /**
+         * Aligns the baseline of the element with the superscript-baseline of its parent.
+         */
+        readonly Super: "super";
+    };
+    type VerticalAlignment = typeof VerticalAlignment[keyof typeof VerticalAlignment];
+    /**
+     * Advanced text metrics.
+     */
+    interface ExtendedMetrics extends Partial<TextMetrics>, Partial<IFont.Metrics> {
+        /**
+         * This is the lineHeight and includes the lineGap
+         */
+        readonly lineHeight: number;
+    }
+    interface Metrics {
+        readonly underlinePosition?: number;
+        readonly underlineThickness?: number;
+        readonly strikePosition?: number;
+        readonly strikeThickness?: number;
+        readonly italicAngle?: number;
+        readonly lineHeight: number;
+        readonly baseline: number;
+        readonly lineGap: number;
+    }
+    interface MetricOptions {
+        isBold?: boolean;
+        isItalic?: boolean;
+        letterSpacing?: number;
+    }
+    interface Measurer {
+        (text: string, size: number, family: string, options?: IFont.MetricOptions): IFont.ExtendedMetrics;
+    }
+    /**
+     * The contract a per-environment measurer module must satisfy. The active default is resolved
+     * via the `@sheetxl/sdk/font/FontMeasurer` conditional export:
+     * `browser` -> canvas, `node` -> fontkit, `default` -> simple (the zero-dependency char counter,
+     * the only universally-safe fallback - never pull a native/node-only measurer through `default`).
+     *
+     * Override the active measurer at runtime with {@link setSharedMeasurer} (e.g. force the simple
+     * measurer in unit tests), or at build time by aliasing the `@sheetxl/sdk/font/FontMeasurer`
+     * import in the bundler config.
+     */
+    interface MeasurerProvider {
+        /** The best measurer for the current environment (may itself fall back to the simple measurer). */
+        getInstance(): IFont.Measurer;
+        /** The device scale for the current environment. */
+        getDeviceScale(): number;
+    }
+    /**
+     * Override the default mechanism for measuring text.
+     *
+     * @param measurer {@link IFont.Measurer}
+     */
+    function setSharedMeasurer(measurer: IFont.Measurer): void;
+    /**
+     * Returns the {@link IFont.Measurer} used for measuring text.
+     *
+     * @see
+     * {@link setSharedMeasurer}
+     */
+    function getSharedMeasurer(): IFont.Measurer;
+    /**
+     * Returns scaling to use for the current device.
+     */
+    function getDeviceScale(): number;
+    /**
+     * Provides a font-family fallback based on the PANOSE hex string.
+     *
+     * @param hexPanose The PANOSE string.
+     * @returns a font-family fallback.
+     */
+    function getPanoseFallback(hexPanose: string): string;
+    /**
+     * Represents a font face, encapsulating information about a specific typeface.
+     */
+    interface IFontFace {
+        /**
+         * Serializes the font face information into a JSON-compatible object.
+         *
+         * @returns A plain JavaScript object representing the font face data.
+         */
+        toJSON(): any;
+        /**
+         * The name of the font face (e.g., 'Arial', 'Times New Roman').
+         */
+        getFamily(): string;
+        /**
+         * The pitch (or classification) of the font face (e.g., 'variable', 'fixed').
+         */
+        getPitch(): string;
+        /**
+         * The Panose classification string for the font face, providing information about its visual characteristics.
+         * @returns `null` if unable to generate.
+         */
+        getPanose(): string | null;
+        /**
+         * Returns a string representation of the font face.
+         */
+        toString(): string;
+        /**
+         * A flag indicating that this object is an `IFont` instance.
+         * Useful for runtime type checking.
+         */
+        readonly isIFont: true;
+    }
+    /**
+     * Font families supported by all/most browsers/platforms.
+     */
+    const GenericName: {
+        readonly Serif: "serif";
+        readonly SanSerif: "sans-serif";
+        readonly MonoSpace: "monospace";
+        readonly Cursive: "cursive";
+        readonly Fantasy: "fantasy";
+        readonly SystemUI: "system-ui";
+        readonly UISystem: "ui-system";
+        readonly UISerif: "ui-serif";
+        readonly UISanSerif: "ui-sans-serif";
+        readonly UIMonoSpace: "ui-monospace";
+        readonly UIRounded: "ui-rounded";
+        readonly Math: "math";
+        readonly Emoji: "emoji";
+        readonly Fangsong: "fangsong";
+    };
+    type GenericName = typeof GenericName[keyof typeof GenericName];
+}
+//# sourceMappingURL=IFont.d.ts.map

package/types/src/font/IFontCollection.d.ts

@@ -0,0 +1,31 @@
+import { IFont } from './IFont';
+export interface FontHandle {
+    /** `null` is used as a cached 'no match' sentinel (see {@link findBestMatch}). */
+    fontRef: IFont.IFontFace | null;
+    loaded: boolean;
+}
+export declare function setFontList(fontList: IFont.IFontFace[] | string[]): void;
+export declare function getFontList(): readonly FontHandle[];
+export interface FindBestMatchOptions {
+    /**
+     * Defaults to false
+     */
+    bold?: boolean;
+    /**
+     * Defaults to false
+     */
+    italic?: boolean;
+    /**
+     * A list of font names or generic font family
+     */
+    fallbacks?: string[];
+    panose?: string;
+}
+/**
+ * Tries to find a font that match the fontName exactly. If this is not found then it will use the fallback
+ * options if provided. If there is no font and no font fallback it will return null.
+ * @param fontName The font name to find
+ * @returns The FontHandle
+ */
+export declare function findBestMatch(fontName: string, options?: FindBestMatchOptions): FontHandle | null;
+//# sourceMappingURL=IFontCollection.d.ts.map

package/types/src/font/SimpleFontMeasurer.d.ts

@@ -0,0 +1,4 @@
+import { IFont } from './IFont';
+export declare function getInstance(): IFont.Measurer;
+export declare function getDeviceScale(): number;
+//# sourceMappingURL=SimpleFontMeasurer.d.ts.map

package/types/src/font/_FontUtils.d.ts

@@ -0,0 +1,22 @@
+import { IFont } from './IFont';
+export declare const DefaultMinFontSize: number;
+export declare const DefaultMaxFontSize: number;
+export declare const DefaultMaxFontPrecision: number;
+export declare const DefaultLineHeightMultiplier: number;
+export declare function defaultHorizontalPadding(fontSize: number): number;
+export declare function defaultVerticalPadding(_fontSize: number): number;
+/**
+ * The size to scale a font for super/sub text.
+ * @remarks
+ * **NOT IMPLEMENTED** This should read from the font but is currently hardcoded to `0.6`.
+ * * This will be moved to 'Measurer'
+ */
+export declare function superSubScale(_fontFamily: string, _fontSize?: number, _verticalAlign?: IFont.VerticalAlignment): number;
+/**
+ * The distance in pixels to shift a font for super/sub text.
+ * @remarks
+ * **NOT IMPLEMENTED** This should read from the font but is currently hardcoded to `+1/5 -1/5`.
+ * * This will be moved to 'Measurer'
+ */
+export declare function superSubShift(fontFamily: string, fontSize?: number, verticalAlign?: IFont.VerticalAlignment): number;
+//# sourceMappingURL=_FontUtils.d.ts.map

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

@@ -0,0 +1,5 @@
+export * as IFontCollection from './IFontCollection';
+export * from './IFont';
+export * from './Font';
+export * as FontUtils from './FontUtils';
+//# sourceMappingURL=index.d.ts.map

package/types/src/history/IHistory.d.ts

@@ -0,0 +1,110 @@
+import { ReferenceableClipboard } from '@sheetxl/utils';
+/**
+ * Encapsulates functionalities crucial for maintaining a comprehensive version history
+ * and audit trail within the spreadsheet application. It provides mechanisms to capture, store,
+ * and manage snapshots of the spreadsheet's state at various points in time.
+ *
+ * The primary motivations behind this namespace are:
+ *
+ * - **Versioning and Undo/Redo**: Maintain a detailed history of changes, allowing for easy rollback or review.
+ * - **Copy/Paste**: Create transferable references.
+ * - **Auditing/Change logs**: Enable accountability by tracking who made changes and when they occurred.
+ * - **Snapshot Management**: Efficiently capture and restore spreadsheet states for backup,
+ *   analysis, or reuse.
+ *
+ * By offering robust versioning and auditing capabilities, this namespace contributes to a more
+ * reliable, transparent, and user-friendly spreadsheet experience.
+ */
+export declare namespace IHistory {
+    /**
+     * Represents an immutable reference to an `Record`, capturing its content and metadata.
+     * @template D The type of the destination for `copyTo`.
+     * @template S The type of the source for `getSource``.
+     * @template C The type of the coordinates the snapshot is bound to.
+     * @template J The type of the JSON for `toJSON`.
+     */
+    interface ISnapshot<D = any, S = any, C = any, J = any> {
+        /**
+         * Copies the snapshot to the specified range.
+         *
+         * @param destination The destination `Snapshot source` where the snapshot will be copied.
+         * @param options {@link IHistory.CopyToOptions}
+         *
+         * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required.
+         */
+        copyTo(destination: D, options?: IHistory.CopyToOptions): Promise<C> | C;
+        /**
+         * The source that created the snapshot.
+         * This is used to quickly do comparisons.
+         */
+        getSource(): S;
+        /**
+         * Retrieves the coordinates that bound the current snapshot.
+         *
+         * @remarks
+         * Different types of snapshots may have different coordinate systems.
+         */
+        getCoords?(): Readonly<C>;
+        /**
+         * Converts the snapshot to a plain text representation.
+         *
+         * @returns A string or promise resolving to the text representation of the snapshot.
+         */
+        toText?(): Promise<string> | string;
+        /**
+         * Converts the snapshot to an HTML representation.
+         *
+         * @returns A string or promise resolving to the HTML representation of the snapshot.
+         */
+        toHtml?(): Promise<string> | string;
+        /**
+         * Converts the snapshot to an image blob.
+         *
+         * @returns A `Blob` or promise resolving to the image representation of the snapshot.
+         */
+        toImage?(): Promise<Blob> | Blob;
+        /**
+         * Converts the snapshot to a JSON object.
+         *
+         * @returns A JSON object or promise resolving to the JSON representation of the snapshot.
+         */
+        toJSON?(): Promise<J> | J;
+        /**
+         * A user friendly name of a the snapshot item.
+         */
+        getName?(): string;
+        /**
+         * Return the options used when creating.
+         * @remarks
+         * This is done so that we can create a copy.
+         */
+        getMarkOptions(): ReferenceableClipboard.CopyOptions;
+        /**
+         * For runtime type checking.
+         */
+        readonly isISnapshot: true;
+    }
+    /**
+     * Options for creating {@link IHistory.ISnapshot}.
+     * **PLACEHOLDER**
+     */
+    interface GetSnapshotOptions {
+    }
+    /**
+     * Copy options for {@link IHistory.ISnapshot}.
+     * **PLACEHOLDER**
+     */
+    interface CopyToOptions extends GetSnapshotOptions {
+    }
+    /**
+     * Interface for objects that supports returning ISnapshot.
+     */
+    interface ISnapshotSource<D = any, S = any, C = any, J = any> {
+        /**
+         * Represents an immutable reference to an `ICellRange`, capturing its content and metadata.
+         * It may include complex objects such as tables, shapes, images, listeners, or other items.
+         */
+        getSnapshot(options?: ReferenceableClipboard.CopyOptions): IHistory.ISnapshot<D, S, C, J>;
+    }
+}
+//# sourceMappingURL=IHistory.d.ts.map

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

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

package/types/src/hyperlink/IHyperlink.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Represents a hyperlink for linking to either a URL or a cell address.
+ */
+export interface IHyperlink {
+    /**
+     * Open the hyperlink.
+     *
+     * @param target Specifies where to open the linked document. DefaultValue `getTarget()`.
+     * @param features Passed to the window open context for external resource.
+     *
+     * @see
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/open)
+     */
+    open(target?: '_self' | '_blank', features?: string): Promise<boolean>;
+    /**
+     * The text shown for the link. This is the text of the cell it is attached to,
+     * falling back to `getAddress()` when the cell has none.
+     */
+    getTextToDisplay(): string;
+    /**
+     * Where the link points; a url, a location within this workbook, or both.
+     *
+     * @remarks
+     * The two destinations are folded into this single value and separated by a `#`:
+     *
+     * * `https://sheetxl.com/` - a url.
+     * * `#Sheet1!A1` - a location within this workbook. (nothing precedes the `#`)
+     * * `https://sheetxl.com/#pricing` - a url with a fragment.
+     *
+     * Excel keeps the two apart as an address and a document reference; folding them is
+     * a deliberate difference and a leading `#` is the only way to write an internal link.
+     *
+     * A location within this workbook is a string and not a reference. It does not follow
+     * the cells it points at when rows or columns are inserted, deleted, or moved. (The
+     * cell the link is attached to does move.)
+     */
+    getAddress(): string;
+    /**
+     * Text showing additional information about the link that will be
+     * displayed as a tooltip.
+     *
+     * @remarks
+     * Excel has an undocumented screen tip length limit of 255 characters.
+     */
+    getScreenTip(): string | null;
+    /**
+     * Specifies the target frame to use when opening this hyperlink.
+     *
+     * @remarks
+     * This has no counterpart in Excel; it is ours and applies to links opened in a browser.
+     *
+     * @defaultValue `_self` for a location within this workbook, otherwise `_blank`.
+     */
+    getTarget(): string;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIHyperlink: true;
+}
+/**
+ * {@inheritDoc IHyperlink}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IHyperlink}
+ */
+export declare namespace IHyperlink {
+    /**
+     * Modifiers describe a partial list of properties that can be set with values or shorthand strings.
+     */
+    type Modifiers = Partial<IHyperlink.Properties>;
+    /**
+     * Used when updating the the value.
+     * @see
+     * `ICellRange.setHyperlink`
+     */
+    type Update = IHyperlink.Modifiers | IHyperlink | string | null;
+    /**
+     * Properties available to `IHyperlinks`.
+     */
+    interface Properties {
+        /** {@inheritDoc IHyperlink.getTextToDisplay} */
+        textToDisplay?: string;
+        /** {@inheritDoc IHyperlink.getAddress} */
+        address: string;
+        /** {@inheritDoc IHyperlink.getScreenTip} */
+        screenTip?: string;
+        /** {@inheritDoc IHyperlink.getTarget} */
+        target?: string;
+    }
+    /**
+     * A JSON representation useful for persistence.
+     */
+    type JSON = Partial<Omit<IHyperlink.Properties, 'textToDisplay'>> | string;
+}
+//# sourceMappingURL=IHyperlink.d.ts.map

package/types/src/hyperlink/_Hyperlink.d.ts

@@ -0,0 +1,21 @@
+import { ITypes } from '../type';
+import { IHyperlink } from './IHyperlink';
+export declare class Hyperlink implements IHyperlink {
+    protected _t: () => string;
+    protected _p: IHyperlink.Properties;
+    protected _r: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>;
+    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON);
+    /** {@inheritDoc IHyperlink.open} */
+    open(target?: '_self' | '_blank', features?: string): Promise<boolean>;
+    /** {@inheritDoc IHyperlink.getTarget} */
+    getTarget(): string;
+    /** {@inheritDoc IHyperlink.getTextToDisplay} */
+    getTextToDisplay(): string;
+    /** {@inheritDoc IHyperlink.getAddress} */
+    getAddress(): string;
+    /** {@inheritDoc IHyperlink.getScreenTip} */
+    getScreenTip(): string | null;
+    /** {@inheritDoc IHyperlink.isIHyperlink} */
+    get isIHyperlink(): true;
+}
+//# sourceMappingURL=_Hyperlink.d.ts.map

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

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

package/types/src/i18n/LanguagePack.d.ts

@@ -0,0 +1,97 @@
+import { FormulaError } from '@sheetxl/primitives';
+import { MinifiedDescriptor } from '@sheetxl/scripting';
+import { LanguagePack as BaseLanguagePack, LanguageTag } from '@sheetxl/utils';
+/**
+ * The **spreadsheet-language plane** of a language pack (I18N-DESIGN.md Plane 3): function names,
+ * error values, boolean literals, and function help.
+ *
+ * Plain interface extension, NOT module augmentation. The previous version declared these fields
+ * onto `@sheetxl/utils`'s `LanguagePack`, which was wrong in four ways: it gave a utils type
+ * knowledge of spreadsheets (an inverted dependency), applied ambiently to anyone who merely
+ * compiled the SDK anywhere in their program, made the fields look supported by the base type when
+ * no SDK is present, and gave no ownership boundary if a second package ever wanted its own plane.
+ *
+ * The runtime is unchanged — still ONE plain pack object, no shape copies — because a pack carrying
+ * these fields is structurally a valid {@link BaseLanguagePack} and registers as one.
+ *
+ * `@sheetxl/sdk` re-exports `@sheetxl/utils`, and an explicit local export takes precedence over a
+ * star re-export, so `import { LanguagePack } from '@sheetxl/sdk'` yields THIS one while
+ * `from '@sheetxl/utils'` still yields the generic base. Consumers inside the spreadsheet SDK get
+ * the spreadsheet flavour without asking.
+ */
+/**
+ * Localized structured-reference specifier words, keyed by canonical section. German Excel writes
+ * `[#All]`→`[#Alle]`, `[#Data]`→`[#Daten]`, `[#Headers]`→`[#Kopfzeilen]`, `[#Totals]`→`[#Ergebnisse]`,
+ * `[#This Row]`→`[#Diese Zeile]`. Consumed by the SR lexer (builds its specifier regex alternates) and
+ * the parse/emit path (localized ⇄ canonical); canonical English is always accepted. Storage stays
+ * canonical (`[#All]`).
+ */
+export interface SRSpecifiers {
+    all: string;
+    data: string;
+    headers: string;
+    totals: string;
+    thisRow: string;
+}
+export interface LanguagePack extends BaseLanguagePack {
+    /**
+     * Localized spreadsheet function names by canonical name (`SUM` → `SUMME`).
+     * Consumed by `FunctionSymbolProvider`: bind accepts localized AND canonical
+     * (round-trip never breaks); resolve displays localized. Identity entries are
+     * unnecessary (canonical is the fallback). Custom/UDF names are never localized.
+     */
+    functions?: Record<string, string>;
+    /** Localized formula error values by canonical id (`Value` → `#WERT!`). */
+    errors?: Record<string, string>;
+    /** Localized boolean literals (`WAHR`/`FALSCH`). */
+    booleans?: {
+        true: string;
+        false: string;
+    };
+    /** Localized structured-reference specifier words (`[#All]` → `[#Alle]`). */
+    specifiers?: SRSpecifiers;
+    /**
+     * Function help (summaries/parameter copy, ~2k strings) — a nested lazy chunk keyed by
+     * canonical function name, loaded only when a tooltip/insert-function dialog resolves a
+     * descriptor. Values are {@link MinifiedDescriptor}s — the SAME shape the built-in
+     * descriptor modules compile to, so a generated per-locale module IS a pack chunk with
+     * no reshaping; `initializeFunctions` overlays it per-field over the built-in English.
+     */
+    functionHelp?: () => Promise<Record<string, MinifiedDescriptor> | {
+        default: Record<string, MinifiedDescriptor>;
+    }>;
+}
+/**
+ * The active (or `tag`'s) spreadsheet-language pack — the MERGE of every contributor's plane: the
+ * function-owning packages (`@sheetxl/formulas`, `@sheetxl/formulas-extended`) supply function names
+ * and help via {@link DefaultLanguagePackService.registerPack}; the SDK supplies error/boolean literals;
+ * the host app's pack overrides any of them. utils returns the packs opaquely ({@link getPacks}); the
+ * merge semantics (which fields deep-merge, how `functionHelp` loaders compose) live HERE, the one
+ * layer that knows what these fields mean.
+ *
+ * The merged pack is cached per tag and invalidated on language change, so it is a STABLE object for a
+ * given (tag, contributor-set) — `FunctionSymbolProvider` and the function-help overlay both key their
+ * caches on the pack identity, which requires that stability.
+ */
+export declare function getLanguagePack(tag?: LanguageTag): LanguagePack | undefined;
+/**
+ * The boolean literal in the active spreadsheet language (`WAHR`/`FALSCH`), for DISPLAY and text
+ * coercion (`=TRUE&""`). Falls back to canonical English. Storage/APIs stay canonical.
+ */
+export declare function localizeBoolean(value: boolean, tag?: LanguageTag): string;
+/**
+ * A formula error's label in the active spreadsheet language (`#WERT!`), for DISPLAY. Falls back to
+ * the canonical label when the language does not translate that error. Files/APIs stay canonical.
+ */
+export declare function localizeErrorLabel(error: FormulaError.Known, tag?: LanguageTag): string;
+/**
+ * Parse a typed boolean literal in the active spreadsheet language. English `TRUE`/`FALSE` are ALWAYS
+ * accepted; the pack's words (`WAHR`/`FALSCH`) are accepted too. Returns `undefined` for anything else.
+ */
+export declare function parseBooleanLocal(str: string, tag?: LanguageTag): boolean | undefined;
+/**
+ * Parse a typed error literal in the active spreadsheet language. Canonical labels (`#VALUE!`) are
+ * ALWAYS accepted; the pack's localized labels (`#WERT!`) are accepted too. `undefined` otherwise.
+ */
+export declare function parseErrorLocal(str: string, tag?: LanguageTag): FormulaError.Known | undefined;
+//# sourceMappingURL=LanguagePack.d.ts.map

package/types/src/i18n/LocaleProfile.d.ts

@@ -0,0 +1,15 @@
+import { LocaleProfile, LocaleProfileOverrides } from '@sheetxl/primitives';
+export type { LocaleProfile };
+/** --- Public factory ----------------------------------------------------- */
+export declare function makeLocaleProfile(tag: string, overrides?: LocaleProfileOverrides | null): LocaleProfile;
+/**
+ * Memoized {@link makeLocaleProfile}.
+ *
+ * @remarks
+ * Building a profile probes `Intl` a dozen times, which is measurably expensive.
+ * Callers on hot paths (input parsing, formatting) should use this rather than
+ * constructing a profile per call. `overrides` participate in the cache key, so a
+ * workbook's customized profile is memoized just like a plain-tag one.
+ */
+export declare function getLocaleProfile(tag: string, overrides?: LocaleProfileOverrides | null): LocaleProfile;
+//# sourceMappingURL=LocaleProfile.d.ts.map