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

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

@@ -0,0 +1,207 @@
+import { Properties as CSSProperties } from 'csstype';
+import { IColor } from '../color';
+import { ITransaction } from '../transaction';
+import { IFont } from './IFont';
+/**
+ * How text is drawn: its typeface, size, weight, slant, lines, color, spacing and baseline.
+ *
+ * @remarks
+ * A cell's font (`range.getStyle().getFont()`) and the text of a chart part
+ * (`title.getStyle().getFont()` on a title, legend, axis or data labels) are both text styles, so
+ * the same code formats either.
+ *
+ * What a style does not state it takes from the text around it: a cell's from the Normal style, a
+ * chart title's from the chart, the chart's from the theme. Reads answer what is drawn, stated or
+ * not.
+ *
+ * Setters return the text style to keep chaining on. A cell's font is a snapshot of the cell, so
+ * its setters return the updated font rather than the one they were called on.
+ *
+ * @example
+ * ```ts
+ * range.getStyle().getFont().setBold(true).setColor('accent2');
+ * chart.getTitle().getStyle().getFont().update({ size: 18, family: IFontStyle.ThemeFamily.Heading });
+ * ```
+ */
+export interface IFontStyle {
+    /**
+     * Returns the typeface drawn: the one stated, or the theme's font when the style names
+     * {@link IFontStyle.ThemeFamily | a theme font} or none.
+     */
+    getFamily(): string;
+    /**
+     * Sets the typeface: a family name, or a {@link IFontStyle.ThemeFamily} to follow the theme's
+     * heading or body font. `null` clears it.
+     */
+    setFamily(family: string | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getFamily}.
+     * @hidden
+     */
+    getName(): string;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link setFamily}.
+     * @hidden
+     */
+    setName(name: string | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /**
+     * Returns the theme font the style follows, or `null` when it names its own family.
+     */
+    getThemeFamily(): IFontStyle.ThemeFamily | null;
+    /**
+     * Returns the families drawn when {@link IFontStyle.getFamily} cannot draw a character, in order.
+     */
+    getFallbacks(): string[];
+    /** @see {@link IFontStyle.getFallbacks} */
+    setFallbacks(fallbacks: string[] | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns the size in points. */
+    getSize(): number;
+    /** Sets the size in points. */
+    setSize(size: number | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns the weight, `400` being regular and `700` bold. */
+    getWeight(): number;
+    /** @see {@link IFontStyle.getWeight} */
+    setWeight(weight: number | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns whether the text is bold: a weight above `400`. */
+    getBold(): boolean;
+    /** Sets the weight to bold (`700`) or regular (`400`). */
+    setBold(bold: boolean | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns whether the text is italic. */
+    getItalic(): boolean;
+    /** @see {@link IFontStyle.getItalic} */
+    setItalic(italic: boolean | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns how the text is underlined; `'none'` when it is not. */
+    getUnderline(): IFont.UnderlineStyle;
+    /** Sets how the text is underlined; `'none'` removes the underline. */
+    setUnderline(underline: IFont.UnderlineStyle | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns how the text is struck through; `'none'` when it is not. */
+    getStrike(): IFont.StrikeStyle;
+    /** Sets how the text is struck through; `'none'` removes the line. */
+    setStrike(strike: IFont.StrikeStyle | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns the text color. */
+    getColor(): IColor;
+    /** Sets the color: an {@link IColor}, `#FF0000`, `rgb(…)`, or a theme color such as `accent1`. */
+    setColor(color: IColor | string | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Returns the space added between characters, in points; `0` for none, negative to condense. */
+    getLetterSpacing(): number;
+    /** @see {@link IFontStyle.getLetterSpacing} */
+    setLetterSpacing(spacing: number | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /**
+     * Returns how far the text is raised, as a percentage of its size: positive for superscript,
+     * negative for subscript, `0` on the baseline.
+     */
+    getBaseline(): number;
+    /** Raises or lowers the text by a percentage of its size; `0` puts it back on the baseline. */
+    setBaseline(baseline: number | null, options?: ITransaction.OperationOptions): IFontStyle;
+    /** Sets several properties at once, as one step to undo. */
+    update(update: IFontStyle.Update, options?: ITransaction.OperationOptions): IFontStyle;
+    /**
+     * Returns `true` when `other` measures text the same, so a measured width can be reused.
+     */
+    isEqualMeasure(other: IFontStyle): boolean;
+    /**
+     * Returns the style as CSS properties.
+     *
+     * @param mode How colors are written.
+     * @param zoom Scales the font size.
+     * @param ignoreNormal Leaves out what equals the Normal style's font, where there is one.
+     */
+    toCSS(mode?: IColor.CSSMode, zoom?: number, ignoreNormal?: boolean): CSSProperties;
+    /** Serializes to a JSON object. */
+    toJSON(): IFontStyle.JSON;
+    /** For runtime type checking. */
+    readonly isIFontStyle: true;
+}
+/**
+ * {@inheritDoc IFontStyle}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFontStyle}
+ */
+export declare namespace IFontStyle {
+    /**
+     * A family that follows the theme: its heading font or its body font.
+     */
+    const ThemeFamily: {
+        readonly Heading: "theme:heading";
+        readonly Body: "theme:body";
+    };
+    type ThemeFamily = typeof ThemeFamily[keyof typeof ThemeFamily];
+    /**
+     * The {@link IFontStyle.getBaseline | baselines} superscript and subscript text take by default.
+     */
+    const Baseline: {
+        readonly Superscript: 30;
+        readonly Subscript: -25;
+    };
+    /**
+     * The stored shape of a text style.
+     *
+     * @remarks
+     * One spelling per concept: bold is a {@link Properties.weight | weight}, italic a
+     * {@link Properties.style | style}, a theme font a {@link ThemeFamily} in `family`. Updates
+     * accept the more forgiving {@link Update}, which is normalized to this before it is stored.
+     */
+    interface Properties<C = IColor.Serializable> {
+        /** A family name, or a {@link ThemeFamily}. */
+        family?: string;
+        /** {@inheritDoc IFontStyle.getFallbacks} */
+        fallbacks?: string[];
+        /** {@inheritDoc IFontStyle.getSize} */
+        size?: number;
+        /** {@inheritDoc IFontStyle.getWeight} */
+        weight?: number;
+        /** `italic` or `normal`. */
+        style?: IFont.Style;
+        /** {@inheritDoc IFontStyle.getColor} */
+        color?: C;
+        /** {@inheritDoc IFontStyle.getLetterSpacing} */
+        letterSpacing?: number;
+        /** {@inheritDoc IFontStyle.getUnderline} */
+        underline?: IFont.UnderlineStyle;
+        /** {@inheritDoc IFontStyle.getStrike} */
+        strike?: IFont.StrikeStyle;
+        /** {@inheritDoc IFontStyle.getBaseline} */
+        baseline?: number;
+        /**
+         * The character set the font was authored against, a font-substitution hint.
+         *
+         * @remarks
+         * An **opaque passthrough**. The model carries the value so it survives a round trip and never
+         * interprets it.
+         */
+        charset?: number;
+        /**
+         * @remarks
+         * An **opaque passthrough**, not drawn. The model carries the value so it survives a round
+         * trip.
+         */
+        shadow?: boolean;
+        /** {@inheritDoc IFontStyle.Properties.shadow} */
+        outline?: boolean;
+    }
+    /**
+     * What {@link IFontStyle.update} and a cell style's `font` accept: {@link Properties} with
+     * shorthands. `null` clears a property.
+     */
+    type Update<C = IColor.Serializable | IColor> = {
+        [K in keyof Omit<Properties<C>, 'weight' | 'underline'>]?: Properties<C>[K] | null;
+    } & {
+        /** A number (`400`, `700`) or a CSS keyword (`'bold'`). */
+        weight?: number | string | null;
+        /** `true` for `'single'`, `false` for `'none'`. */
+        underline?: IFont.UnderlineStyle | boolean | null;
+        /** Sets the weight to `700` or `400`. Ignored when `weight` is also given. */
+        bold?: boolean | null;
+        /** Sets the style to `italic` or `normal`. Ignored when `style` is also given. */
+        italic?: boolean | null;
+    };
+    interface JSON extends Properties<string> {
+    }
+}
+//# sourceMappingURL=IFontStyle.d.ts.map

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

@@ -0,0 +1,36 @@
+import { AdvanceBuilder } from './AdvanceBuilder';
+import { AdvanceTable } from './AdvanceTable';
+/**
+ * The resource path of a face's table: `calibri-bold-italic.metrics.json`.
+ *
+ * @remarks
+ * The family is lowercased and its spaces become hyphens; a weight of 600 or more reads as bold,
+ * the only weight spreadsheets name.
+ */
+export declare function metricsFileName(face: AdvanceTable.Face): string;
+/**
+ * Builds tables from `.metrics.json` files in the `fonts` resource kind: the SDK's shipped tables,
+ * and any a user captured into a resource root, which take precedence.
+ */
+export declare class TableFileAdvanceBuilder implements AdvanceBuilder {
+    readonly name = "table-file";
+    readonly kind = "table";
+    private readonly _base;
+    private readonly _pending;
+    /**
+     * @param base A base to search after the user resource roots, or `null` for none (the default).
+     */
+    constructor(base?: string | null);
+    build(face: AdvanceTable.Face): Promise<AdvanceTable | null>;
+    /**
+     * Gives `table` the hinted widths of its `.hinted.json` companion and Excel's row heights from
+     * its `.rows.json`, those it has.
+     *
+     * @returns Whether the table is hinted now.
+     */
+    hint(table: AdvanceTable): Promise<boolean>;
+    /** A companion file of a face, or `null` when there is none. */
+    private _companion;
+    private _load;
+}
+//# sourceMappingURL=TableFileAdvanceBuilder.d.ts.map

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

@@ -0,0 +1,10 @@
+import { AdvanceTable } from './AdvanceTable';
+/**
+ * The tables measuring works with before anything loads: Calibri (Excel's default before Aptos, and
+ * Aptos's stand-in) and Arial (the generic sans-serif), regular and bold. About 15 KB gzip.
+ *
+ * Imported as text (`?raw`, declared in `global.d.ts`) and parsed when the shared collection is
+ * first made.
+ */
+export declare function builtinFontTables(): AdvanceTable[];
+//# sourceMappingURL=_BuiltinFontTables.d.ts.map

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

@@ -1,9 +1,16 @@
-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;
+/**
+ * Excel's horizontal padding a side for a cell whose font's widest digit is `digitWidth` px: a
+ * quarter of that digit, rounded up (2 px at Calibri 11, 17 at Calibri 100, 56 at Arial 300).
+ * Exact against Excel's own autofit over 130 cells, Calibri and Arial, 8 to 48 pt
+ * (`private-assets/design/rust/tools/sweep-excel-autofit.ps1`), and against the column at which
+ * Excel stops showing a number as `#` from 20 to 300 pt (`tools/oracle-excel-overflow.ps1`:
+ * content + 2 x this + 1 every time).
+ */
+export declare function defaultHorizontalPadding(digitWidth: number): number;
 export declare function defaultVerticalPadding(_fontSize: number): number;
 /**
  * The size to scale a font for super/sub text.
@@ -11,12 +18,12 @@ export declare function defaultVerticalPadding(_fontSize: number): number;
  * **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;
+export declare function superSubScale(_fontFamily: string, _fontSize?: number, _baseline?: number): 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;
+export declare function superSubShift(fontFamily: string, fontSize?: number, baseline?: number): number;
 //# sourceMappingURL=_FontUtils.d.ts.map

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

@@ -0,0 +1,7 @@
+/**
+ * A number that changes whenever the shared {@link IFontCollection} does (a table or its hinted
+ * widths arrived): part of the key of any cache of measurements, so a cached measure taken before a
+ * font loaded is not served after. Listens from its first call on.
+ */
+export declare function fontsVersion(): number;
+//# sourceMappingURL=_FontsVersion.d.ts.map

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

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

package/types/src/font/platform.browser.d.ts

@@ -0,0 +1,15 @@
+import { AdvanceBuilder } from './AdvanceBuilder';
+/**
+ * The browser's builders: a canvas, for installed families we have no captured table for. Known
+ * families never reach it; the shipped tables and the built-ins answer first.
+ */
+export declare function getAdvanceBuilders(): AdvanceBuilder[];
+/**
+ * Returns scaling to use for the current device.
+ *
+ * @remarks
+ * **TODO** This is hardcoded to Non-HD DPI. Revisit: `window.devicePixelRatio`, with a listener
+ * for the `(resolution: ...dppx)` media query so a window moving between screens is noticed.
+ */
+export declare function getDeviceScale(): number;
+//# sourceMappingURL=platform.browser.d.ts.map

package/types/src/font/platform.node.d.ts

@@ -0,0 +1,5 @@
+import { AdvanceBuilder } from './AdvanceBuilder';
+export declare function getDeviceScale(): number;
+/** No platform builders here: the shipped tables and the built-ins are all there is. */
+export declare function getAdvanceBuilders(): AdvanceBuilder[];
+//# sourceMappingURL=platform.node.d.ts.map

package/types/src/group/Group.d.ts

@@ -0,0 +1,141 @@
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { ITextFrame } from '../text';
+import { IFill } from '../fill';
+import { IMovable, IMovableCollection } from '../movable';
+import { MovableContentRegistry } from '../movable/MovableContentRegistry';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { GroupMember } from '../movable/GroupMember';
+import { FrameRect } from '../movable/_DrawnBounds';
+import { InsertableCollection } from '../movable/_InsertableCollection';
+import { IGroup } from './IGroup';
+/** The group's own JSON: everything but the members, which are models of their own. */
+type GroupData = Omit<IGroup.JSON, 'members' | 'name'>;
+interface State extends AbstractMovableContent.State {
+    data: GroupData;
+    /** The members in z-order. */
+    members: readonly GroupMember[];
+}
+/**
+ * Implementation for {@link IGroup}.
+ */
+export declare class Group extends AbstractMovableContent<State, IGroup.JSON, IGroup.Events> implements IGroup {
+    private _members;
+    private _createOptions;
+    /** What each member asked to be told, for as long as the member lives: an undo can restore it. */
+    private _memberCallbacks;
+    /** The member order the members were last told of. */
+    private _toldOrder;
+    constructor(options: MovableContentRegistry.CreateOptions);
+    /** {@inheritDoc IModel.getType} */
+    getType(): string;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
+    getTypeDescription(): string;
+    /** {@inheritDoc MovableContentRegistry.Content.getMovables} */
+    getMovables(): IMovableCollection;
+    /** The child space the members' placements are stated in: the file's, else the frame at the origin. */
+    private _childBounds;
+    /**
+     * Fits the group to its members after one of them changed, as Excel does: the child space
+     * becomes the union of the members' boxes (each frame with its sides swapped within 45 degrees of a
+     * quarter turn), growing or shrinking, and the frame follows it at the scale the group has, so
+     * no member moves on the canvas and a stretched group stays stretched.
+     */
+    private _rebound;
+    /** Where the group is drawn; `null` before it is laid out. */
+    private _drawnPlacement;
+    /** {@inheritDoc IGroup.getFill} */
+    getFill(): IFill.JSON | null;
+    /** {@inheritDoc IGroup.getTextFrame} */
+    getTextFrame(): ITextFrame.IText | null;
+    /**
+     * {@inheritDoc IMovable.IContent.acceptRotation}
+     *
+     * @remarks
+     * A group turns only when every member can: Excel will not turn a group that holds a chart or a
+     * control. A member that can turn still turns on its own.
+     */
+    get acceptRotation(): ((degrees: number) => number) | undefined;
+    /**
+     * {@inheritDoc IMovable.IContent.acceptFlip}
+     *
+     * @remarks
+     * A group mirrors only when every member can, as for {@link acceptRotation}.
+     */
+    get acceptFlip(): ((flip: IMovable.Flip) => IMovable.Flip) | undefined;
+    /** Whether every member's content defines `capability`; a nested group asks its own. */
+    private _isEveryMember;
+    /** {@inheritDoc IGroup.ungroup} */
+    ungroup(options?: IMovable.OperationOptions): Promise<IMovable[]>;
+    /**
+     * Places a copy of each of `members` in the group's container where it is drawn - through one
+     * level - and in the group's place in the z-order, as Excel does, and answers them. The members
+     * themselves stay; the caller deletes the group.
+     */
+    private _free;
+    /**
+     * {@inheritDoc IMovable.IContent.getConnections}
+     *
+     * @remarks
+     * A group has none: Excel glues a connector to a member of a group, never to the group.
+     */
+    getConnections(): readonly IMovable.Connection[];
+    /** {@inheritDoc Movable.Content.toJSON} */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IGroup.JSON;
+    /**
+     * What the group paints in its `width` by `height` frame: the union of its members' drawn
+     * boxes, each placed in the frame.
+     * @internal
+     */
+    _getDrawnRect(width: number, height: number, onReady: () => void): FrameRect | null;
+    /** The members in z-order. @internal */
+    _getMembers(): readonly IMovable[];
+    private _members_;
+    /**
+     * Places a movable in the group.
+     * @internal
+     */
+    _addMember(options: IMovableCollection.AddOptions): Promise<IMovable>;
+    /**
+     * What an added member waits for - its kind loaded - before the insert opens its transaction.
+     * @internal
+     */
+    _prepareMember(options: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /**
+     * Places a movable whose content kind is already loaded in the group, without waiting.
+     * @internal
+     */
+    _insertMember(options: InsertableCollection.InsertOptions): IMovable;
+    /**
+     * Groups members of this group into a group of their own, inside it, as the sheet groups its
+     * movables: the new group's frame is the union of the boxes they occupy as rotated, its child
+     * space equals its frame, and each keeps its frame, rotation and flips. One undo step; the new
+     * group is selected unless `autoSelect` is `false`.
+     * @internal
+     */
+    _groupMembers(movables: readonly IMovable[], options?: IMovableCollection.GroupOptions): Promise<IMovable>;
+    /**
+     * Takes a member out. Down to one, the group dissolves, as Excel's does: the survivor is freed
+     * where it is drawn, as an ungroup frees it, in the same operation. The group goes with its last
+     * member.
+     */
+    private _removeMember;
+    /** Moves a member to `to` in the z-order. */
+    private _moveMember;
+    /** A member movable with its content, from its JSON. */
+    private _createMember;
+    /**
+     * Tells each member whose place in the order changed since the members were last told: by a
+     * move, or by an undo or a redo of one, which restores the order without moving anything.
+     */
+    private _tellZIndex;
+    /** Runs `callback` folded into the current commit. */
+    private _amend;
+    protected _processAfterStateChange(state: State, commit: ITransaction.ICommit): void;
+    /** {@inheritDoc IGroup.isIGroup} */
+    get isIGroup(): true;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}
+export {};
+//# sourceMappingURL=Group.d.ts.map

package/types/src/group/GroupMovableCollection.d.ts

@@ -0,0 +1,41 @@
+import { ITransaction } from '../transaction';
+import { AbstractCollection } from '../type';
+import { IResource, IResourceCollection } from '../resource';
+import { IMovable, IMovableCollection } from '../movable';
+import { InsertableCollection } from '../movable/_InsertableCollection';
+import { Group } from './Group';
+/**
+ * The members of a group: an {@link IMovableCollection} whose container is the group.
+ *
+ * @remarks
+ * Members answer canvas placements, but the collection keeps no spatial index: the cell filters
+ * of a sheet's collection (`address`, `bounds`) are not applied; `type`, `ignoreHidden` and
+ * `deep` are.
+ */
+export declare class GroupMovableCollection extends AbstractCollection<IMovable, IMovableCollection.GetItemsOptions> implements IMovableCollection, InsertableCollection {
+    private readonly _group;
+    constructor(_group: Group, transactions?: ITransaction.IStore);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IMovableCollection.GetItemsOptions): IMovable[];
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IMovableCollection.add} */
+    add(options?: IMovableCollection.AddOptions): Promise<IMovable>;
+    /** {@inheritDoc InsertableCollection._prepare} */
+    _prepare(options: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /** {@inheritDoc InsertableCollection._preparePicture} */
+    _preparePicture(picture: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /** {@inheritDoc InsertableCollection._insertNow} */
+    _insertNow(options: InsertableCollection.InsertOptions): IMovable;
+    /** {@inheritDoc IMovableCollection.addPicture} */
+    addPicture(picture: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise<IMovable>;
+    /** {@inheritDoc IMovableCollection.group} */
+    group(movables: readonly IMovable[], options?: IMovableCollection.GroupOptions): Promise<IMovable>;
+    /** {@inheritDoc IMovableCollection.updateSelected} */
+    updateSelected(update: (movable: IMovable) => void, action?: string): void;
+    /** Announces that the members changed. @internal */
+    _notifyChange(): void;
+    /** {@inheritDoc IMovableCollection.isIMovableCollection} */
+    get isIMovableCollection(): true;
+}
+//# sourceMappingURL=GroupMovableCollection.d.ts.map

package/types/src/group/IGroup.d.ts

@@ -0,0 +1,129 @@
+import { Bounds } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { IModel } from '../model';
+import { IMovable } from '../movable';
+import { IFill, IEffect } from '../fill';
+import { IHyperlink } from '../hyperlink';
+import { ITextFrame } from '../text';
+import { IShape } from '../shape';
+/**
+ * A group: a movable that holds movables.
+ *
+ * @remarks
+ * A group is the content of an {@link IMovable} — `movable.getContent<IGroup>()` for a movable
+ * whose content type is `'group'`. Its members are ordinary movables, each with its own content
+ * (a shape, a picture, a chart, another group), held by the group's movable in z-order
+ * ({@link IMovable.getMovables}). A member's {@link IMovable.getParent} is the group's movable.
+ *
+ * A member is read and edited where it is drawn, like any movable; the group keeps its
+ * placement in the child space the file states ({@link IGroup.JSON.childBounds}) and maps it
+ * through its own frame. Resizing the group changes its frame only: the members keep what they
+ * store, and are drawn at the new scale, as Excel's Size pane shows it.
+ *
+ * @example
+ * ```ts
+ * for (const member of movable.getMovables()?.getItems() ?? []) {
+ *   console.log(member.getContent().getName?.(), member.getBounds());
+ * }
+ * ```
+ */
+export interface IGroup extends IModel, IMovable.IContent {
+    toJSON(toResourceId?: (resource: IResource) => number | null): IGroup.JSON;
+    /**
+     * Returns the name of the group.
+     */
+    getName(): string | null;
+    /**
+     * Returns the text written on the members, in z-order.
+     *
+     * @returns `null` when no member has a text body at all.
+     */
+    getTextFrame(): ITextFrame.IText | null;
+    /**
+     * The fill the group states for members that take the group's fill, or `null` for none.
+     */
+    getFill(): IFill.JSON | null;
+    /**
+     * Dissolves the group: each member is placed in the group's container where it is drawn, and
+     * the group is deleted.
+     *
+     * @returns The freed movables, in z-order.
+     *
+     * @remarks
+     * One level: a nested group is freed as a group. One undo step. A group whose last member is
+     * deleted is deleted with it.
+     *
+     * The freed movables are selected unless `autoSelect` is `false`.
+     */
+    ungroup(options?: IMovable.OperationOptions): Promise<IMovable[]>;
+    /**
+     * Deletes the group and its members, and with them the movable that places the group.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
+    /** For runtime type checking. */
+    readonly isIGroup: true;
+}
+/**
+ * {@inheritDoc IGroup}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IGroup}
+ */
+export declare namespace IGroup {
+    /**
+     * A JSON representation useful for persistence.
+     */
+    interface JSON {
+        /**
+         * The name of the group.
+         */
+        name?: string;
+        /**
+         * The child space (`chOff`/`chExt`), in pixels: what the members' anchors are stated in,
+         * mapped onto the group's frame by a scale per axis. Absent, the group's frame at the origin.
+         *
+         * @remarks
+         * A group made from a selection has a child space equal to its frame; resizing the group
+         * afterwards leaves it as it was.
+         */
+        childBounds?: Bounds;
+        /**
+         * The members in z-order. A member is an ordinary movable whose anchor is absolute in the
+         * child space: `anchor.tl` its top-left and `anchor.br` its size, with no cells.
+         */
+        members?: IMovable.JSON[];
+        /**
+         * The fill members that take the group's fill draw with (`grpSpPr`). A nested group may itself
+         * take its group's fill.
+         */
+        fill?: IFill.SolidJSON | IFill.GradientJSON | IFill.PatternJSON | IFill.ImageJSON | IFill.NoneJSON | IFill.GroupJSON;
+        /**
+         * The group's effects (`grpSpPr/effectLst`).
+         */
+        effects?: IEffect.JSON[];
+        /** The 3-D scene (`grpSpPr/scene3d`) as the file states it: an opaque DrawingML fragment. */
+        scene3d?: string;
+        /** Extension lists kept as the file states them, by the element each extends. */
+        extLst?: IShape.ExtLstJSON;
+        /** The hyperlink on the whole group (`cNvPr/hlinkClick`). */
+        hyperlink?: IHyperlink.JSON;
+        /** The hyperlink followed on hover (`cNvPr/hlinkHover`). */
+        hoverHyperlink?: IHyperlink.JSON;
+        /** The title (`cNvPr/@title`), beside the description. */
+        title?: string;
+        /**
+         * Edit locks (`grpSpLocks`) by the file's own names: `noGrp`, `noUngrp`, `noSelect`, `noRot`,
+         * `noChangeAspect`, `noMove`, `noResize`.
+         */
+        locks?: Record<string, boolean>;
+        /**
+         * The id the file gave the group (`cNvPr/@id`). Kept and written again, as a shape's is.
+         */
+        sourceId?: number;
+    }
+    interface Events extends IMovable.ContentEvents {
+    }
+}
+//# sourceMappingURL=IGroup.d.ts.map

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

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