@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.12

package/types/src/print/PageLayout.d.ts

@@ -0,0 +1,258 @@
+import { IRange } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ICalculation } from '../calculation';
+import { IResource } from '../resource';
+import { IEmbeddedPart } from '../io/IEmbeddedPart';
+import { IWorksheet } from '../sheet/IWorksheet';
+import { IPageLayout } from './IPageLayout';
+interface State {
+    /** Everything but the printer settings, which hold a resource. Defaults left out. */
+    json: Readonly<IPageLayout.JSON>;
+    printerSettings: IEmbeddedPart | null;
+}
+type HeaderFooterKind = 'odd' | 'even' | 'first';
+type HeaderFooterKey = keyof Pick<IPageLayout.HeaderFooterJSON, 'oddHeader' | 'oddFooter' | 'evenHeader' | 'evenFooter' | 'firstHeader' | 'firstFooter'>;
+/** The left, center and right sections of a header or footer string. */
+type Sections = [string, string, string];
+/**
+ * The print layout of a sheet.
+ *
+ * @remarks
+ * Holds the settings as JSON, an absent value being its default, so `toJSON` returns what the file
+ * said plus what was set since. The print area and titles are the sheet's names, not state here.
+ */
+export declare class PageLayout implements IPageLayout {
+    protected _options: PageLayout.ConstructorOptions;
+    protected _transactions: ITransaction.IStore;
+    protected _id: string;
+    protected _headersFooters: HeaderFooterGroup | null;
+    constructor(options: PageLayout.ConstructorOptions);
+    protected _getState(): Readonly<State>;
+    /** @internal */
+    _getJSON(): Readonly<IPageLayout.JSON>;
+    /**
+     * Writes the fields given, leaving out any that are `undefined` (a default) and dropping an
+     * empty header/footer block.
+     * @internal
+     */
+    _update(update: Partial<IPageLayout.JSON>, options?: ITransaction.OperationOptions, description?: string): this;
+    protected _sheet(): IWorksheet;
+    /** @internal */
+    _getSheet(): IWorksheet;
+    /** {@inheritDoc IPageLayout.getOrientation} */
+    getOrientation(): IPageLayout.Orientation;
+    /** {@inheritDoc IPageLayout.setOrientation} */
+    setOrientation(orientation: IPageLayout.Orientation, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getPaperSize} */
+    getPaperSize(): IPageLayout.PaperType | null;
+    /** {@inheritDoc IPageLayout.getPaperSizeCode} */
+    getPaperSizeCode(): number;
+    /** {@inheritDoc IPageLayout.setPaperSize} */
+    setPaperSize(paperSize: IPageLayout.PaperType | number, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getZoom} */
+    getZoom(): IPageLayout.ZoomOptions;
+    /** {@inheritDoc IPageLayout.setZoom} */
+    setZoom(zoom: IPageLayout.ZoomOptions, options?: ITransaction.OperationOptions): this;
+    protected _margins(): Readonly<IPageLayout.MarginsJSON>;
+    protected _setMargins(inches: IPageLayout.MarginOptions, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getTopMargin} */
+    getTopMargin(): number;
+    /** {@inheritDoc IPageLayout.setTopMargin} */
+    setTopMargin(topMargin: number, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getBottomMargin} */
+    getBottomMargin(): number;
+    /** {@inheritDoc IPageLayout.setBottomMargin} */
+    setBottomMargin(bottomMargin: number, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getLeftMargin} */
+    getLeftMargin(): number;
+    /** {@inheritDoc IPageLayout.setLeftMargin} */
+    setLeftMargin(leftMargin: number, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getRightMargin} */
+    getRightMargin(): number;
+    /** {@inheritDoc IPageLayout.setRightMargin} */
+    setRightMargin(rightMargin: number, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getHeaderMargin} */
+    getHeaderMargin(): number;
+    /** {@inheritDoc IPageLayout.setHeaderMargin} */
+    setHeaderMargin(headerMargin: number, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getFooterMargin} */
+    getFooterMargin(): number;
+    /** {@inheritDoc IPageLayout.setFooterMargin} */
+    setFooterMargin(footerMargin: number, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.setPrintMargins} */
+    setPrintMargins(unit: IPageLayout.PrintMarginUnit, marginOptions: IPageLayout.MarginOptions, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getCenterHorizontally} */
+    getCenterHorizontally(): boolean;
+    /** {@inheritDoc IPageLayout.setCenterHorizontally} */
+    setCenterHorizontally(centerHorizontally: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getCenterVertically} */
+    getCenterVertically(): boolean;
+    /** {@inheritDoc IPageLayout.setCenterVertically} */
+    setCenterVertically(centerVertically: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getPrintGridlines} */
+    getPrintGridlines(): boolean;
+    /** {@inheritDoc IPageLayout.setPrintGridlines} */
+    setPrintGridlines(printGridlines: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getPrintHeadings} */
+    getPrintHeadings(): boolean;
+    /** {@inheritDoc IPageLayout.setPrintHeadings} */
+    setPrintHeadings(printHeadings: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getBlackAndWhite} */
+    getBlackAndWhite(): boolean;
+    /** {@inheritDoc IPageLayout.setBlackAndWhite} */
+    setBlackAndWhite(blackAndWhite: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getDraftMode} */
+    getDraftMode(): boolean;
+    /** {@inheritDoc IPageLayout.setDraftMode} */
+    setDraftMode(draftMode: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getFirstPageNumber} */
+    getFirstPageNumber(): number | '';
+    /** {@inheritDoc IPageLayout.setFirstPageNumber} */
+    setFirstPageNumber(firstPageNumber: number | '' | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getPrintOrder} */
+    getPrintOrder(): IPageLayout.PrintOrder;
+    /** {@inheritDoc IPageLayout.setPrintOrder} */
+    setPrintOrder(printOrder: IPageLayout.PrintOrder, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getPrintComments} */
+    getPrintComments(): IPageLayout.PrintComments;
+    /** {@inheritDoc IPageLayout.setPrintComments} */
+    setPrintComments(printComments: IPageLayout.PrintComments, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getPrintErrors} */
+    getPrintErrors(): IPageLayout.PrintErrorType;
+    /** {@inheritDoc IPageLayout.setPrintErrors} */
+    setPrintErrors(printErrors: IPageLayout.PrintErrorType, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getHeadersFooters} */
+    getHeadersFooters(): IPageLayout.IHeaderFooterGroup;
+    /** The sheet's own name of this kind; a global one of the same name is not the sheet's. */
+    protected _getName(name: string): ICalculation.INamedFormula | null;
+    /** Writes the name, or deletes it when `expression` is `null`. */
+    protected _setName(name: string, expression: string | null): void;
+    /** The absolute, sheet-qualified reference to each range, as Excel writes these names. */
+    protected _toReference(coords: readonly Readonly<IRange.Coords>[]): string;
+    /**
+     * The ranges a print name designates, read from its text: the engine answers `getRanges()` only
+     * once it has compiled the name, and a setter reads the titles straight after writing them.
+     * `null` when the name is not a list of references on this sheet.
+     */
+    protected _nameCoords(name: string): IRange.Coords[] | null;
+    /** {@inheritDoc IPageLayout.getPrintArea} */
+    getPrintArea(): ICellRanges | null;
+    /** {@inheritDoc IPageLayout.setPrintArea} */
+    setPrintArea(printArea: ICellRanges.Address | null, _options?: ITransaction.OperationOptions): this;
+    /** The title rows and columns, each the first block of its kind in `_xlnm.Print_Titles`. */
+    protected _titles(): {
+        rows: ICellRange | null;
+        columns: ICellRange | null;
+    };
+    /** Writes the titles as Excel does: columns first, then rows. */
+    protected _setTitles(rows: IRange.Coords | null, columns: IRange.Coords | null): void;
+    /** The entire rows or columns a title setter was given, or `null` to clear them. */
+    protected _toTitle(title: ICellRange | string | null, axis: IRange.Axis): IRange.Coords | null;
+    /** {@inheritDoc IPageLayout.getPrintTitleRows} */
+    getPrintTitleRows(): ICellRange | null;
+    /** {@inheritDoc IPageLayout.setPrintTitleRows} */
+    setPrintTitleRows(printTitleRows: ICellRange | string | null, _options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.getPrintTitleColumns} */
+    getPrintTitleColumns(): ICellRange | null;
+    /** {@inheritDoc IPageLayout.setPrintTitleColumns} */
+    setPrintTitleColumns(printTitleColumns: ICellRange | string | null, _options?: ITransaction.OperationOptions): this;
+    /** @internal */
+    _getHeaderFooter(key: HeaderFooterKey): string;
+    /** @internal */
+    _updateHeaderFooter(update: Partial<IPageLayout.HeaderFooterJSON>, options?: ITransaction.OperationOptions): this;
+    /** The manual and automatic breaks before rows (`Row`) or columns (`Column`), in order. @internal */
+    _getBreaks(axis: IRange.Axis): readonly IPageLayout.BreakJSON[];
+    /** @internal */
+    _setBreaks(axis: IRange.Axis, breaks: IPageLayout.BreakJSON[], options?: ITransaction.OperationOptions): this;
+    /**
+     * Moves the breaks as rows (or columns) `start` to `end` are inserted or deleted: a break at or
+     * after an insert moves with it, a break before a deleted row goes with it, and a break past a
+     * delete moves back. Excel's behavior (`scripts/openpy-parity/probe-print-setup.ps1`).
+     * @internal
+     */
+    _shiftBreaks(axis: IRange.Axis, start: number, end: number, isInsert: boolean): void;
+    /** The manual breaks on an axis. */
+    protected _getPageBreaks(axis: IRange.Axis): IPageLayout.IPageBreak[];
+    /** {@inheritDoc IPageLayout.getHorizontalPageBreaks} */
+    getHorizontalPageBreaks(): IPageLayout.IPageBreak[];
+    /** {@inheritDoc IPageLayout.getVerticalPageBreaks} */
+    getVerticalPageBreaks(): IPageLayout.IPageBreak[];
+    /** {@inheritDoc IPageLayout.addHorizontalPageBreak} */
+    addHorizontalPageBreak(pageBreakRange: ICellRange.Address, options?: ITransaction.OperationOptions): IPageLayout.IPageBreak;
+    /** {@inheritDoc IPageLayout.addVerticalPageBreak} */
+    addVerticalPageBreak(pageBreakRange: ICellRange.Address, options?: ITransaction.OperationOptions): IPageLayout.IPageBreak;
+    /** {@inheritDoc IPageLayout.removeAllHorizontalPageBreaks} */
+    removeAllHorizontalPageBreaks(options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.removeAllVerticalPageBreaks} */
+    removeAllVerticalPageBreaks(options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPageLayout.isIPageLayout} */
+    get isIPageLayout(): true;
+    /**
+     * Adds a manual break before `index`, spanning the whole sheet the way Excel writes a new one.
+     * An automatic break already there becomes manual.
+     */
+    protected _addPageBreak(axis: IRange.Axis, index: number, options?: ITransaction.OperationOptions): IPageLayout.IPageBreak;
+    /** @internal */
+    _removePageBreak(axis: IRange.Axis, index: number, options?: ITransaction.OperationOptions): void;
+    /** Removes every break on an axis, the automatic ones the file carried included. */
+    protected _removeAllPageBreaks(axis: IRange.Axis, options?: ITransaction.OperationOptions): void;
+    /** @internal */
+    _getPrinterSettings(): IEmbeddedPart | null;
+    /** The layout as JSON, or `null` when every setting is its default. */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPageLayout.JSON | null;
+    /** @internal */
+    _sections(key: HeaderFooterKey): Sections;
+    /** @internal */
+    _setSection(key: HeaderFooterKey, section: 0 | 1 | 2, text: string, options?: ITransaction.OperationOptions): this;
+}
+/** @see {@link IPageLayout.IHeaderFooterGroup} */
+declare class HeaderFooterGroup implements IPageLayout.IHeaderFooterGroup {
+    protected _layout: PageLayout;
+    protected _sets: Record<HeaderFooterKind, HeaderFooter>;
+    constructor(layout: PageLayout);
+    getState(): IPageLayout.HeaderFooterState;
+    setState(state: IPageLayout.HeaderFooterState, options?: ITransaction.OperationOptions): this;
+    getDefaultForAllPages(): IPageLayout.IHeaderFooter;
+    getOddPages(): IPageLayout.IHeaderFooter;
+    getEvenPages(): IPageLayout.IHeaderFooter;
+    getFirstPage(): IPageLayout.IHeaderFooter;
+    getUseSheetMargins(): boolean;
+    setUseSheetMargins(useSheetMargins: boolean, options?: ITransaction.OperationOptions): this;
+    getUseSheetScale(): boolean;
+    setUseSheetScale(useSheetScale: boolean, options?: ITransaction.OperationOptions): this;
+}
+/** @see {@link IPageLayout.IHeaderFooter} */
+declare class HeaderFooter implements IPageLayout.IHeaderFooter {
+    protected _layout: PageLayout;
+    protected _header: HeaderFooterKey;
+    protected _footer: HeaderFooterKey;
+    constructor(layout: PageLayout, kind: HeaderFooterKind);
+    getLeftHeader(): string;
+    setLeftHeader(leftHeader: string, options?: ITransaction.OperationOptions): this;
+    getCenterHeader(): string;
+    setCenterHeader(centerHeader: string, options?: ITransaction.OperationOptions): this;
+    getRightHeader(): string;
+    setRightHeader(rightHeader: string, options?: ITransaction.OperationOptions): this;
+    getLeftFooter(): string;
+    setLeftFooter(leftFooter: string, options?: ITransaction.OperationOptions): this;
+    getCenterFooter(): string;
+    setCenterFooter(centerFooter: string, options?: ITransaction.OperationOptions): this;
+    getRightFooter(): string;
+    setRightFooter(rightFooter: string, options?: ITransaction.OperationOptions): this;
+    getHeader(): string;
+    setHeader(header: string, options?: ITransaction.OperationOptions): this;
+    getFooter(): string;
+    setFooter(footer: string, options?: ITransaction.OperationOptions): this;
+}
+export declare namespace PageLayout {
+    interface ConstructorOptions {
+        /** The sheet the layout prints, for its names and ranges. */
+        getSheet: () => IWorksheet;
+        transactions?: ITransaction.IStore;
+        json?: IPageLayout.JSON;
+        fromResourceId?: (resourceId: number) => IResource;
+    }
+}
+export {};
+//# sourceMappingURL=PageLayout.d.ts.map

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

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

package/types/src/protectedRange/IProtectedRange.d.ts

@@ -9,7 +9,7 @@ import { ITransaction } from '../transaction';
  * @remarks
  * Excel surfaces these as *Review → Allow Edit Ranges*, and OOXML persists them as
  * `<protectedRange>` inside `<protectedRanges>`. Despite the name, a protected range **relaxes**
- * protection rather than adding it: it is only consulted while {@link ISheetProtection.isLocked}
+ * protection rather than adding it: it is only consulted while {@link IWorksheetProtection.isLocked}
  * is true, and it grants an exemption for the cells it covers — optionally behind a password.
  *
  * * Like {@link IConditionalFormat} and {@link IDataValidation}, one entry may be anchored to
@@ -47,7 +47,7 @@ export interface IProtectedRange extends IAnchored {
     /**
      * Re-anchors this protected range to `address`, REPLACING every range it currently covers.
      *
-     * @param address The range or ranges to cover — anything `ISheet.getRanges` accepts
+     * @param address The range or ranges to cover — anything `IWorksheet.getRanges` accepts
      *   (`'A1:C20'`, `'A1:A5, C1:C5'`, coords). Resolved against this protected range's own sheet.
      * @param options Transaction options; `description` names the entry in undo history.
      *

package/types/src/protection/IProtection.d.ts

@@ -187,6 +187,12 @@ export declare namespace IProtection {
          * @defaultValue `100000`.
          */
         spinCount?: number;
+        /**
+         * The 16-bit hash older applications write instead of {@link hash} (Excel 2010 and earlier,
+         * LibreOffice, openpyxl), as hex digits. A password is checked against it when there is no
+         * {@link hash}. A password set through the API is never stored this way.
+         */
+        legacyHash?: string;
     }
     /**
      * **PLACEHOLDER** - Will integrate into the user identity system.

package/types/src/protection/PasswordHasher.d.ts

@@ -1,3 +1,4 @@
+import { IProtection } from './IProtection';
 export interface SaltAndHash {
     salt: string;
     hash: string;
@@ -27,6 +28,18 @@ export declare class PasswordHasher {
      * @returns The encryption key as a base64 string.
      */
     static verifyPassword(password: string, saltAndHash: SaltAndHash, algorithm?: string, spinCount?: number): Promise<boolean>;
+    /**
+     * Verify a password against the 16-bit hash older applications write.
+     *
+     * @param password The password.
+     * @param legacyHash The hash, as hex digits.
+     */
+    static verifyLegacyPassword(password: string, legacyHash: string): boolean;
+    /**
+     * Verify a password against a stored one: its {@link IProtection.EncryptedPassword.hash} when it
+     * has one, else its {@link IProtection.EncryptedPassword.legacyHash}. `true` when it has neither.
+     */
+    static verifyStoredPassword(password: string, stored: Partial<IProtection.EncryptedPassword>): Promise<boolean>;
     /**
      * For unit testing against existing salt and hash keys.
      */

package/types/src/resource/IResource.d.ts

@@ -12,6 +12,11 @@ export interface IResource extends JSONSerializableAsync<IResource.JSON> {
      * An optional name for the resource.
      */
     getName(): string | null;
+    /**
+     * The URL the bytes were fetched from, when the resource is a picture the workbook keeps for it
+     * (an `IMAGE` source): a fetch of that URL answers from these bytes. `null` otherwise.
+     */
+    getFetchedFrom(): string | null;
     /**
      * For saving to json resources.
      */
@@ -113,6 +118,10 @@ export declare namespace IResource {
          * This is optional but if provided then resource lookup will use this as a cache key.
          */
         name?: string;
+        /**
+         * The URL the embedded bytes were fetched from: the workbook keeps them as that URL's picture.
+         */
+        fetchedFrom?: string;
     }
 }
 //# sourceMappingURL=IResource.d.ts.map

package/types/src/resource/IResourceCollection.d.ts

@@ -52,6 +52,10 @@ export declare namespace IResourceCollection {
          * This is optional and purely for human consumption and is not used by the system.
          */
         name?: string;
+        /**
+         * The URL the bytes were fetched from, for a picture the workbook keeps for it.
+         */
+        fetchedFrom?: string;
     }
     /**
      * A type that represents the various ways to provide a resource source.

package/types/src/resource/Resource.d.ts

@@ -2,6 +2,7 @@ import { IResource } from './IResource';
 import { IResourceCollection } from './IResourceCollection';
 export declare class Resource implements IResource {
     private _name;
+    private _fetchedFrom;
     private _refs;
     private _listeners;
     private _isClosed;
@@ -17,6 +18,7 @@ export declare class Resource implements IResource {
     protected _resolveArrayBuffer(): Promise<ArrayBuffer>;
     /** {@inheritDoc IResource.getName} */
     getName(): string | null;
+    getFetchedFrom(): string | null;
     /** {@inheritDoc IResource.toJSONAsync} */
     toJSONAsync(): Promise<IResource.JSON>;
     /** {@inheritDoc IResource.toBuffer} */

package/types/src/resource/_AddResource.d.ts

@@ -0,0 +1,13 @@
+import { IResource } from './IResource';
+import { IResourceCollection } from './IResourceCollection';
+/**
+ * Adds bytes to `resources` as a resource. With `fetchedFrom` the resource is the collection's copy
+ * of that URL, so adding the URL again answers the one already there. With no collection, a
+ * resource of no workbook.
+ *
+ * @internal
+ */
+export declare const addResource: (resources: IResourceCollection | null, buffer: ArrayBuffer, options?: {
+    fetchedFrom?: string;
+}) => IResource;
+//# sourceMappingURL=_AddResource.d.ts.map

package/types/src/richData/CellImage.d.ts

@@ -0,0 +1,95 @@
+import { IRichData, IRichType, Scalar } from '@sheetxl/primitives';
+import { IResource } from '../resource';
+import { IRichDataKind } from './IRichDataKind';
+/**
+ * A picture as a cell value: what `IMAGE()` returns.
+ *
+ * @remarks
+ * It reads as nothing where a primitive is needed, so `LEN`, `&` and `+` over it are `#VALUE!`,
+ * and a reference carries it whole: `=A1` over an image is the image.
+ *
+ * It holds where the picture comes from and, once they are in, the resource holding its bytes:
+ * `IMAGE` adds the picture it fetched, and a picture placed in a cell brings its own. The workbook
+ * saves a resource while a value holds it. A value with no resource fetches its source to draw.
+ *
+ * Immutable.
+ */
+export declare class CellImage implements IRichData {
+    /** The name of the kind of every `CellImage` ({@link CellImageKind}). */
+    static readonly Type = "image";
+    private readonly _source;
+    private readonly _altText;
+    private readonly _sizing;
+    private readonly _height;
+    private readonly _width;
+    private readonly _resource;
+    /**
+     * @param source Where the picture comes from: a URL.
+     */
+    constructor(source: string, options?: CellImage.Options);
+    /** {@inheritDoc IRichData.getKind} */
+    getKind(): IRichType;
+    /** Where the picture comes from. */
+    getSource(): string;
+    /** The text that describes the picture, for accessibility, or `null`. */
+    getAltText(): string | null;
+    /** How the picture is sized in its cell. */
+    getSizing(): CellImage.Sizing;
+    /** The height in pixels for {@link CellImage.Sizing.Custom}, or `null`. */
+    getHeight(): number | null;
+    /** The width in pixels for {@link CellImage.Sizing.Custom}, or `null`. */
+    getWidth(): number | null;
+    /** {@inheritDoc IRichData.getProperty} */
+    getProperty(_name: string): Scalar;
+    /** {@inheritDoc IRichData.toString} */
+    toString(): string;
+    /** The resource holding the picture's bytes, or `null` when it has none and fetches its source. */
+    getResource(): IResource | null;
+    /** {@inheritDoc IRichData.toJSON} */
+    toJSON(toResourceId?: IRichData.ToResourceId): IRichData.JSON;
+    /** {@inheritDoc IRichData.isIRichData} */
+    get isIRichData(): true;
+}
+export declare namespace CellImage {
+    /**
+     * How a picture sits in its cell: `IMAGE()`'s `sizing` argument.
+     */
+    const Sizing: {
+        /** Fits inside the cell, keeping its aspect ratio. */
+        readonly Fit: 0;
+        /** Fills the cell, ignoring its aspect ratio. */
+        readonly Fill: 1;
+        /** At its own size, which may overflow the cell. */
+        readonly Original: 2;
+        /** At the height and width given. */
+        readonly Custom: 3;
+    };
+    type Sizing = typeof Sizing[keyof typeof Sizing];
+    /** What an image holds besides its source. */
+    interface Options {
+        altText?: string | null;
+        sizing?: Sizing;
+        height?: number | null;
+        width?: number | null;
+        /** The resource holding the picture's bytes. */
+        resource?: IResource | null;
+    }
+    /** The `data` of an image's JSON. */
+    interface Data {
+        source: string;
+        altText?: string;
+        sizing?: Sizing;
+        height?: number;
+        width?: number;
+        /** The resource holding the picture's bytes, by the id the file gave it. */
+        resId?: number;
+        /**
+         * The resource itself, in place of `resId`, where a value is made in memory rather than read
+         * (`createRichData`, `setValue`).
+         */
+        resource?: IResource;
+    }
+}
+/** The {@link IRichDataKind} of {@link CellImage}. */
+export declare const CellImageKind: IRichDataKind<CellImage>;
+//# sourceMappingURL=CellImage.d.ts.map

package/types/src/richData/Hyperlink.d.ts

@@ -0,0 +1,49 @@
+import { IRichData, IRichType, Scalar } from '@sheetxl/primitives';
+import { IRichDataKind } from './IRichDataKind';
+/**
+ * A link as a cell value: what `HYPERLINK()` returns.
+ *
+ * @remarks
+ * It reads as its friendly name, or as its address when it has none, so `LEN`, `&` and comparison
+ * see the text a user sees. A reference carries it whole, so `=A1` and `IF(c, HYPERLINK(...), "")`
+ * are links too.
+ *
+ * This is the link a cell's value is. The link a cell carries beside its value is
+ * {@link ICell.getHyperlink}; a cell may have both.
+ *
+ * Immutable.
+ */
+export declare class Hyperlink implements IRichData {
+    /** The name of the kind of every `Hyperlink` ({@link HyperlinkKind}). */
+    static readonly Type = "hyperlink";
+    private readonly _address;
+    private readonly _friendly;
+    /**
+     * @param address Where the link goes: a URL, a file path, or a location in the workbook
+     * (`#Sheet1!A1`). `null` when it is not known until the formula that made the link
+     * recalculates (a link read from a file whose address is computed).
+     * @param friendly What the cell shows. Omitted, the address.
+     */
+    constructor(address: string | null, friendly?: string | number | boolean | null);
+    /** From the JSON {@link toJSON} wrote. */
+    static fromJSON(json: IRichData.JSON): Hyperlink;
+    /** {@inheritDoc IRichData.getKind} */
+    getKind(): IRichType;
+    /** Where the link goes, or `null` when that is not known yet: the link goes nowhere. */
+    getAddress(): string | null;
+    /** What the cell shows, or `null` when it shows the address. */
+    getFriendlyName(): string | number | boolean | null;
+    /** {@inheritDoc IRichData.getProperty} */
+    getProperty(_name: string): Scalar;
+    /** {@inheritDoc IRichData.toString} */
+    toString(): string;
+    /** {@inheritDoc IRichData.toPrimitive} */
+    toPrimitive(): string | number | boolean;
+    /** {@inheritDoc IRichData.toJSON} */
+    toJSON(): IRichData.JSON;
+    /** {@inheritDoc IRichData.isIRichData} */
+    get isIRichData(): true;
+}
+/** The {@link IRichDataKind} of {@link Hyperlink}. */
+export declare const HyperlinkKind: IRichDataKind<Hyperlink>;
+//# sourceMappingURL=Hyperlink.d.ts.map

package/types/src/richData/IRichDataCollection.d.ts

@@ -0,0 +1,76 @@
+import { IRichData, IRichType } from '@sheetxl/primitives';
+import { ICollection } from '../type';
+import { IRichDataKind } from './IRichDataKind';
+/**
+ * The rich values a workbook's cells hold, interned: a cell run stores a rich value as its id here,
+ * as it stores a string as its id in the string collection.
+ *
+ * @remarks
+ * Equal values share one id (equal JSON; a resource counts by identity), so recalculating a
+ * formula that makes a new but equal value adds nothing. Values are not removed: a save writes only
+ * the ones a cell holds.
+ */
+export interface IRichDataCollection extends ICollection<IRichData> {
+    /**
+     * The id of `value`, added when no equal value is here.
+     *
+     * @param value A rich value. Never an error: an error is stored by its code.
+     */
+    add(value: IRichData): number;
+    /**
+     * The value for an id, or `null` if not found.
+     *
+     * @param id The id {@link add} answered.
+     */
+    getById(id: number): IRichData | null;
+    /**
+     * Starts saving or loading the rich values cells name. Scopes begun while one is open share its
+     * ids, so a workbook and its sheets agree on them.
+     */
+    beginPersist(): IRichDataCollection.IPersistScope;
+    /** For runtime type checking. */
+    readonly isIRichDataCollection: true;
+}
+/**
+ * {@inheritDoc IRichDataCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IRichDataCollection}
+ */
+export declare namespace IRichDataCollection {
+    /** A saved rich value: its kind's JSON. */
+    type JSON = IRichData.JSON;
+    /**
+     * One save or load of the rich values cells name. Ids are positions in the saved table, not the
+     * collection's own.
+     */
+    interface IPersistScope {
+        /** The saved id of `value`, added to the table when new. */
+        add(value: IRichData): number;
+        /** The value a loaded id names, or `null`. */
+        at(id: number): IRichData | null;
+        /**
+         * Loads a saved table: each entry made by its kind, its ids then answered by {@link at}.
+         *
+         * @param ctx What the values are made for: the workbook's resources, and the file's resource ids.
+         * @param kinds The kinds saved with the table ({@link toKindsJSON}), made before the values
+         * that name them.
+         */
+        fromJSON(json: readonly JSON[] | undefined, ctx: IRichDataKind.Context, kinds?: readonly IRichType.JSON[]): void;
+        /**
+         * The table, in id order.
+         *
+         * @param toResourceId The saved id of a resource a value holds.
+         */
+        toJSONAsync(toResourceId?: IRichData.ToResourceId): Promise<JSON[]>;
+        /**
+         * The kinds the table's values name, nested values included, that are not registered in code
+         * and so are saved with it.
+         */
+        toKindsJSON(): IRichType.JSON[];
+        /** Ends the scope. The last to end lets the table go. */
+        endPersist(): void;
+    }
+}
+//# sourceMappingURL=IRichDataCollection.d.ts.map