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

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.
      *
@@ -120,6 +120,10 @@ export interface IProtectedRange extends IAnchored {
      * stack, and resets when the workbook is reopened — the same shape as
      * {@link IProtection.isPaused}. This is what lets the write path consult it synchronously; a
      * password check is async and cannot be awaited per cell.
+     *
+     * It lasts for one protection period: unprotecting the sheet revokes it (protecting again asks
+     * for the password afresh), while a {@link IProtection.pause} keeps it. Changing the password
+     * revokes it too.
      */
     isUnlocked(): boolean;
     /**

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

@@ -30,6 +30,8 @@ export interface IProtectedRangeCollection extends ICollection<IProtectedRange>
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IProtectedRange): IProtectedRange;
+    /** For runtime type checking. */
+    readonly isIProtectedRangeCollection: true;
 }
 /**
  * {@inheritDoc IProtectedRangeCollection}

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

@@ -13,7 +13,7 @@ import { IProtectedRange } from './IProtectedRange';
  * Extends {@link AbstractAnchored} directly rather than `AnchoredConditional`: a protected range
  * has no condition and does not depend on cell values, so it never subscribes to range events.
  */
-export declare class ProtectedRange extends AbstractAnchored<State, CommitView, IProtectedRange.Events> implements IProtectedRange {
+export declare class ProtectedRange extends AbstractAnchored<State, IProtectedRange.Events> implements IProtectedRange {
     /**
      * Session edit access — set by {@link unlock}, cleared by {@link relock}.
      *
@@ -94,8 +94,5 @@ interface State extends AbstractAnchored.State {
     securityDescriptor: string | null;
     password: Partial<IProtection.EncryptedPassword> | null;
 }
-/** @internal */
-interface CommitView extends AbstractAnchored.CommitView {
-}
 export {};
 //# sourceMappingURL=ProtectedRange.d.ts.map

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

@@ -1,21 +1,32 @@
 import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { IProtectedRangeCollection } from './IProtectedRangeCollection';
 import { IProtectedRange } from './IProtectedRange';
-export declare class ProtectedRangeCollection implements IProtectedRangeCollection {
+/**
+ * Implementation for {@link IProtectedRangeCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own protected-range state — the sheet keeps the store and the
+ * events, this class keeps the API. `onCollectionChange` is the sheet's
+ * `onProtectedRangesChange`, forwarded with this collection as the source.
+ */
+export declare class ProtectedRangeCollection extends AbstractCollection<IProtectedRange, IProtectedRangeCollection.GetItemsOptions> implements IProtectedRangeCollection {
     private _add;
     private _get;
     private _getByName;
     private _createItem;
-    constructor(add: (address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions) => IProtectedRange, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IProtectedRange[], getByName: (name: string) => IProtectedRange | null, createItem: (template?: IProtectedRange | null) => IProtectedRange);
+    private _addListeners;
+    constructor(add: (address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions) => IProtectedRange, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IProtectedRange[], getByName: (name: string) => IProtectedRange | null, createItem: (template?: IProtectedRange | null) => IProtectedRange, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
     /** {@inheritDoc IProtectedRangeCollection.add} */
     add(address: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions): IProtectedRange;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IProtectedRange>;
-    /** {@inheritDoc IProtectedRangeCollection.getItems} */
-    getItems(options?: IProtectedRangeCollection.GetItemsOptions): IProtectedRange[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IProtectedRangeCollection.GetItemsOptions): IProtectedRange[];
     /** {@inheritDoc IProtectedRangeCollection.createItem} */
     createItem(template?: IProtectedRange | null): IProtectedRange;
-    /** {@inheritDoc IProtectedRangeCollection.getCount} */
-    getCount(): number;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IProtectedRangeCollection.isIProtectedRangeCollection} */
+    get isIProtectedRangeCollection(): true;
 }
 //# sourceMappingURL=ProtectedRangeCollection.d.ts.map

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

@@ -1,9 +1,11 @@
 import { IListener } from '../listener';
 import { IProtection } from './IProtection';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
-export declare class DefaultProtection<T, P extends IProtection.Properties, J extends IProtection.JSON> implements IProtection<T, P, J> {
+export declare abstract class DefaultProtection<T, P extends IProtection.Properties, J extends IProtection.JSON> implements IProtection<T, P, J> {
     protected _emitter: ListenerEmitter<this, IProtection.IListeners>;
     protected _isPaused: boolean;
+    /** Not protected, but keeping `_properties` for the next lock. Saved as {@link _getAllowedKey}. */
+    protected _isDisabled: boolean;
     protected _password: Partial<IProtection.EncryptedPassword> | null;
     protected _identities: IProtection.IdentityProvider[] | null;
     protected _properties: Partial<P> | null;
@@ -21,6 +23,8 @@ export declare class DefaultProtection<T, P extends IProtection.Properties, J ex
     pause(password?: string): Promise<IProtection<T, P, J>>;
     /** {@inheritDoc IProtection.resume} */
     resume(): IProtection<T, P, J>;
+    /** {@inheritDoc IProtection.setProperties} */
+    setProperties(properties: Partial<P>): Promise<IProtection<T, P, J>>;
     /** {@inheritDoc IProtection.isPaused} */
     isPaused(): boolean;
     /** {@inheritDoc IProtection.isLocked} */
@@ -35,9 +39,16 @@ export declare class DefaultProtection<T, P extends IProtection.Properties, J ex
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove;
     fromJSON(json?: J): void;
+    /**
+     * The JSON key that says the whole object stays allowed: unprotected, keeping its options. Named
+     * for the object (`sheet`, `workbook`), like the allowances beside it.
+     */
+    protected abstract _getAllowedKey(): string;
     protected _fromJSON(_json: J | null): void;
     protected _toJSON(json: Partial<J>): Partial<J>;
     /** {@inheritDoc IWorkbookProtection.toJSON} */
     toJSON(): J | null;
+    /** {@inheritDoc IProtection.isIProtection} */
+    get isIProtection(): true;
 }
 //# sourceMappingURL=DefaultProtection.d.ts.map

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

@@ -8,13 +8,15 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * Locks the object (workbook or sheet or range) with the specified options and password.
      *
      * @param password The password required to unlock the object.
-     * @param properties The properties to allow to remain unlocked.
+     * @param properties The properties to allow to remain unlocked. Omitted, the options the object
+     * already carries are used (see {@link unlock} and {@link setProperties}).
      * @param algorithm The algorithm for encrypting the password.
      * @param spinCount The spin count for encrypting the password.
      * @returns The `IProtection` instance for method chaining.
      *
      * @remarks
      * By default all properties are locked but you can specify which properties to remain unlocked.
+     * Throws when the object is already protected, paused included.
      */
     lock(properties?: Partial<P>, password?: string, algorithm?: string, spinCount?: number): Promise<IProtection<T, P, J>>;
     /**
@@ -24,9 +26,31 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * @returns The `IProtection` instance for method chaining.
      *
      * @remarks
-     * If the correct password is provided, protection is removed from the object.
+     * If the correct password is provided, protection is removed from the object and the password is
+     * cleared. The options are kept, and saved, so a later {@link lock} with no properties protects
+     * the same way again.
      */
     unlock(password?: string): Promise<IProtection<T, P, J>>;
+    /**
+     * Replaces the options of an unprotected or paused object. On a paused object they apply when it
+     * resumes; on an unprotected one, when it is next locked.
+     *
+     * @param properties The properties to allow to remain unlocked.
+     * @returns The `IProtection` instance for method chaining.
+     *
+     * @remarks
+     * Throws while the object is locked: unprotect or {@link pause} first. Neither asks for the
+     * password here, since an unprotected object has none and a pause already asked for it.
+     */
+    setProperties(properties: Partial<P>): Promise<IProtection<T, P, J>>;
+    /**
+     * The object's options, kept while it is unlocked; `null` when it has none.
+     *
+     * @remarks
+     * A property names what stays **allowed** while locked - it is not a list of what is forbidden.
+     * Whether the options are in force is {@link isLocked}.
+     */
+    getProperties(): Partial<P> | null;
     /**
      * Temporarily disables protection with the provided password.
      *
@@ -36,6 +60,14 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      * @remarks
      * This method allows temporarily pausing protection without permanently unlocking the object.
      * Use {@link resume} to restore protection.
+     *
+     * Not a shortcut for {@link unlock}, even on a lock without a password: unlocking is a document
+     * change (the file saves unprotected, and the password is gone), whereas a pause
+     * keeps the whole configuration - password, options, and any session access already granted to
+     * an {@link IProtectedRange} - and {@link resume} restores it exactly. The password is required
+     * only when one is set. Throws when the object is not locked.
+     *
+     * The paused state is session-only and is never serialized.
      */
     pause(password?: string): Promise<IProtection<T, P, J>>;
     /**
@@ -91,6 +123,8 @@ export interface IProtection<T, P extends IProtection.Properties, J extends IPro
      */
     addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove;
     toJSON(): IProtection.JSON | null;
+    /** For runtime type checking. */
+    readonly isIProtection: true;
 }
 /**
  * {@inheritDoc IProtection}
@@ -153,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/reference/ReferenceUtils.d.ts

@@ -0,0 +1,80 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * The rules a reference follows when the cells around it change.
+ *
+ * @remarks
+ * A reference is a rectangle that names cells - a formula's precedent, a range listener's
+ * subscription, a watch's location. Everything that holds one has to answer the same questions
+ * when the sheet is restructured: where is it after an insert or a delete, when does it become
+ * `#REF!`, and when does a cut carry it along. These are those answers, and they live here rather
+ * than in the calc graph so that the graph's precedents and the sheet's listeners map cannot
+ * disagree - they call the same functions.
+ *
+ * Nothing here knows about formulas, blocks or grids. A reference is two numbers per axis plus,
+ * for a formula, which of its endpoints a structural change is allowed to move.
+ *
+ * @internal
+ */
+/**
+ * Shift one axis of a reference the way a structural change shifts a formula precedent.
+ *
+ * @remarks
+ * This is the rule `shiftPrecedents` applies, per axis, to every reference it rewrites, and the
+ * rule a range listener's reference follows so that the two can never disagree. A reference is
+ * judged on the shifted axis alone - whether it overlaps the inserted or deleted band on the OTHER
+ * axis plays no part - which is why `=SUM(A1:C3)` reads `A2:C4` after one cell is inserted at A1
+ * shifting down: the whole reference moves, it does not come apart.
+ *
+ * * An insert (`shiftBy` > 0) moves every endpoint at or past `shiftStart` by `shiftBy`; an
+ *   endpoint before it stays, so a reference straddling the insert line grows.
+ * * A delete (`shiftBy` < 0) whose zone covers the whole reference makes it `#REF!` (`null`); one
+ *   that covers an end trims that end to the zone's edge; one entirely before the reference moves
+ *   it whole.
+ *
+ * An immune endpoint is left exactly as it is, and a reference with an immune endpoint is never
+ * `#REF!`: that is a relative endpoint of an unanchored block (a named formula's body), which
+ * names no cell for a structural change to move. See the note in `shiftPrecedents`.
+ *
+ * @param start The reference's absolute start on this axis.
+ * @param end The reference's absolute end on this axis.
+ * @param shiftStart The first index of the inserted or deleted band.
+ * @param shiftBy How far the band moves cells: positive for an insert, negative for a delete.
+ * @param deleteEnd The last index of the deleted band; ignored for an insert.
+ * @param immuneStart `true` if the start endpoint must not move.
+ * @param immuneEnd `true` if the end endpoint must not move.
+ * @returns The shifted `[start, end]`, or `null` when the delete removed the whole reference.
+ */
+export declare function shiftReferenceAxis(start: number, end: number, shiftStart: number, shiftBy: number, deleteEnd: number, immuneStart?: boolean, immuneEnd?: boolean): [start: number, end: number] | null;
+/**
+ * Move one axis of a reference the way a cut moves a formula precedent.
+ *
+ * @remarks
+ * A move is a rigid translation, so unlike a shift there is no zone to compare against and no
+ * `#REF!`: both endpoints travel the same distance or neither does. Whether this reference travels
+ * at all is {@link isReferenceEnclosed}'s question, asked before this one.
+ *
+ * An immune endpoint is left exactly as it is. That is a relative endpoint whose own cells are
+ * moving by the same amount - the formula and its target translate together, so the offset between
+ * them is already right - or one of an unanchored block, which names no cell to re-point.
+ *
+ * @param start The reference's start on this axis.
+ * @param end The reference's end on this axis.
+ * @param moveBy How far the cut carries the cells on this axis.
+ * @param immuneStart `true` if the start endpoint must not move.
+ * @param immuneEnd `true` if the end endpoint must not move.
+ */
+export declare function moveReferenceAxis(start: number, end: number, moveBy: number, immuneStart?: boolean, immuneEnd?: boolean): [start: number, end: number];
+/**
+ * Whether a cut of `from` carries `reference` with it.
+ *
+ * @remarks
+ * Excel's test, and the graph's: a reference moves only when the cut rectangle FULLY ENCLOSES it.
+ * Cut A1:C3 and `=SUM(A1:B2)` follows to the destination; `=SUM(A1:C5)` reaches outside the cut
+ * and so is left exactly where it is, pointing at cells that are now empty. There is no partial
+ * answer and no split - a reference that is only half carried would name two different rectangles.
+ *
+ * A formula BLOCK asks a longer version of this question, because each of its cells has a
+ * reference of its own and all of them have to be enclosed; see `movePrecedents`.
+ */
+export declare function isReferenceEnclosed(reference: Readonly<IRange.Coords>, from: Readonly<IRange.Coords>): boolean;
+//# sourceMappingURL=ReferenceUtils.d.ts.map

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

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

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

@@ -1,4 +1,4 @@
-import { JSONSerializableAsync } from '@sheetxl/utils';
+import { JSONSerializableAsync, MaybePromise } from '@sheetxl/utils';
 /**
  * A resource is an item referenced elsewhere with the application.
  * This will track when a resource is no longer being used and can be removed.
@@ -63,6 +63,26 @@ export interface IResource extends JSONSerializableAsync<IResource.JSON> {
  * {@link IResource}
  */
 export declare namespace IResource {
+    /**
+     * Writes a single resource wherever the caller wants it, and returns the {@link IResource.JSON}
+     * that should stand for it in the serialized model.
+     *
+     * @param resource The resource being written.
+     * @param id The id the serialized model references this resource by.
+     *
+     * @returns The JSON to record for the resource, or `null` to record nothing.
+     *
+     * @remarks
+     * Called once per resource that the write actually touched, never for unused ones.
+     *
+     * Returning `{ uri }` is the useful case: the bytes go wherever the writer put them and the
+     * model keeps a pointer, which reads back as an external resource with no reader changes.
+     *
+     * Ids are positions, so a `null` leaves a `{}` placeholder rather than shifting the resources
+     * after it. If every resource returns `null` no resources are recorded at all — for a writer
+     * that emits the bytes itself and only needs the ids, such as the xlsx writer.
+     */
+    type Writer = (resource: IResource, id: number) => MaybePromise<IResource.JSON | null>;
     interface IUnloadListener {
         onUnload: (ref: IResource) => void;
     }