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

package/types/src/picture/IPicture.d.ts

@@ -1,16 +1,78 @@
 import { Size } from '@sheetxl/utils';
 import { IListener } from '../listener';
-import { IResource } from '../resource';
+import { ITransaction } from '../transaction';
+import { IResource, IResourceCollection } from '../resource';
 import { IModel } from '../model';
+import { IMovable } from '../movable';
+import { IFill, IStroke, IEffect } from '../fill';
+import { IHyperlink } from '../hyperlink';
+import { IGeometry, IShape, IShapeStyle } from '../shape';
 /**
  * Interface for working with Pictures (both Images and SVG).
  */
-export interface IPicture extends IModel {
+export interface IPicture extends IModel, IMovable.IContent {
     toJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
+    /**
+     * Deletes the picture, and with it the movable that places it.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
     /**
      * Returns the resource associated with this picture.
      */
     getResource(): IResource;
+    /**
+     * Shows another image, as Excel's Change Picture does: the frame's size and placement and the
+     * picture's formatting stay; only the image changes.
+     *
+     * The resource is taken as it is, not read: a source that cannot be fetched shows nothing. Read
+     * it first (`toBuffer()`) to be sure of it.
+     *
+     * @param picture A url, a resource, or the options to add one with. A url or options take the
+     * sheet's resources, so a picture that is not on a sheet takes a resource.
+     *
+     * @example
+     * ```ts
+     * picture.setResource('https://example.com/logo.png');
+     * ```
+     */
+    setResource(picture: string | IResource | IResourceCollection.AddOptions, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the shape the picture is cropped to: its preset geometry.
+     *
+     * @remarks
+     * A DrawingML preset id ({@link IGeometry.Preset}): `rect` for a picture that is not cropped to
+     * a shape, which is most of them. A file may name a preset this SDK does not know; it is
+     * returned as the file states it.
+     */
+    getShapeType(): string;
+    /**
+     * Crops the picture to a shape, as Excel's Crop to Shape does: the image, its frame, border and
+     * effects stay; the picture is clipped to the preset's outline.
+     *
+     * A picture takes any closed preset; a line or connector preset is refused.
+     *
+     * @param shapeType A DrawingML preset id ({@link IGeometry.Preset}); `rect` crops to nothing.
+     * @throws ExpectedError for a preset the picture cannot take.
+     *
+     * @example
+     * ```ts
+     * picture.setShapeType(IGeometry.Preset.Ellipse);
+     * ```
+     */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /**
+     * What the picture's frame draws with: the fill behind the image and the border around it.
+     * A picture has no theme style, so each is only what the picture states; by default neither
+     * draws, and a border shows only once it has a color (a width alone draws nothing, as in
+     * Excel). The same object answers for the life of the picture.
+     *
+     * @example
+     * ```ts
+     * picture.getStyle().getStroke().setWidth(2.25);
+     * picture.getStyle().setFill('#ffd966');
+     * ```
+     */
+    getStyle(): IShapeStyle;
     /**
      * Returns an image blob.
      */
@@ -23,6 +85,8 @@ export interface IPicture extends IModel {
      * Returns a local object URL for placing in an image tag.
      */
     getDetails(): Promise<IPicture.Details>;
+    /** For runtime type checking. */
+    readonly isIPicture: true;
 }
 /**
  * {@inheritDoc IPicture}
@@ -40,12 +104,75 @@ export declare namespace IPicture {
      */
     interface Properties {
     }
+    /**
+     * How the image is placed in the picture's frame (`blipFill`): the part of it shown, whether
+     * that part is stretched over the frame or tiled across it, and the adjustments made to the
+     * image itself. The same slots as an {@link IFill.ImageJSON | image fill}, without the image:
+     * a picture names its image by {@link JSON.resId}.
+     */
+    type ImageJSON = Omit<IFill.ImageProperties, 'type' | 'resId'>;
     interface JSON {
         /**
          * The resource id of the picture.
          */
         resId?: number;
-        effects?: string[];
+        /**
+         * The id the file gave the picture (`cNvPr/@id`), which a connector's glued ends name it by.
+         * Written again with the file; a picture without one takes the next when a connector first
+         * glues to it.
+         */
+        sourceId?: number;
+        /**
+         * How the image fills the frame: the crop (`srcRect`), stretch insets or tiling, and the
+         * image's own adjustments. Absent for the whole image stretched over the whole frame, which
+         * is what an inserted picture is.
+         */
+        image?: ImageJSON;
+        /**
+         * The shape the picture is cropped to (`prstGeom`); absent for a rectangle, i.e. not cropped
+         * to a shape.
+         */
+        geometry?: string | IGeometry.Def;
+        /** The adjust values of {@link geometry}, by name, where a handle moved them off the preset's defaults. */
+        adjustments?: Record<string, number>;
+        /**
+         * The fill behind the image (`spPr`); a transparent image shows it. Absent for none.
+         */
+        fill?: IFill.SolidJSON | IFill.GradientJSON | IFill.PatternJSON | IFill.ImageJSON | IFill.NoneJSON;
+        /** The border around the frame (`spPr/ln`). Absent for none. */
+        stroke?: IStroke.JSON;
+        /** The frame's effects (`spPr/effectLst`): a shadow, a glow, a reflection, soft edges. */
+        effects?: IEffect.JSON[];
+        /** The 3-D scene (`spPr/scene3d`) as the file states it: an opaque DrawingML fragment. */
+        scene3d?: string;
+        /** The 3-D shape properties (`spPr/sp3d`) as the file states it: an opaque DrawingML fragment. */
+        shape3d?: string;
+        /** Extension lists kept as the file states them, by the element each extends. */
+        extLst?: IShape.ExtLstJSON;
+        /** The hyperlink on the picture (`cNvPr/hlinkClick`). */
+        hyperlink?: IHyperlink.JSON;
+        /** The hyperlink followed on hover (`cNvPr/hlinkHover`). */
+        hoverHyperlink?: IHyperlink.JSON;
+        /** The title (`cNvPr/@title`), beside the description. */
+        title?: string;
+        /** The macro assigned to the picture (`pic/@macro`), as the file states it. */
+        macro?: string;
+        /** `pic/@fPublished`. */
+        published?: boolean;
+        /**
+         * Edit locks (`picLocks`) by the file's own names: `noChangeAspect`, `noCrop`, `noGrp`,
+         * `noSelect`, `noRot`, `noMove`, `noResize`, `noEditPoints`, `noAdjustHandles`,
+         * `noChangeArrowheads`, `noChangeShapeType`. `noChangeAspect` is also the movable's
+         * {@link IMovable.JSON.lockAspect | aspect lock}, which wins when both are stated.
+         */
+        locks?: Record<string, boolean>;
+        /**
+         * Resizing is not relative to the original picture size (`cNvPicPr/@preferRelativeResize="0"`,
+         * Excel's "Relative to original picture size" unticked). Carried for the file.
+         *
+         * @defaultValue false
+         */
+        noRelativeResize?: boolean;
     }
     interface Details {
         /**
@@ -61,7 +188,7 @@ export declare namespace IPicture {
          */
         asSVGText(): string | null;
     }
-    interface Events extends IModel.Events {
+    interface Events extends IMovable.ContentEvents {
     }
     interface IListeners extends IListener.Callbacks<IPicture, IPicture.Events> {
     }

package/types/src/picture/Picture.d.ts

@@ -1,20 +1,49 @@
-import { IResource } from '../resource';
-import { AbstractModel, IModel } from '../model';
+import { ITransaction } from '../transaction';
+import { IResource, IResourceCollection } from '../resource';
+import { IAnchored } from '../anchored';
+import { IMovable } from '../movable/IMovable';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IGeometry, IShapeStyle } from '../shape';
 import { IPicture } from './IPicture';
-interface State extends AbstractModel.State {
-    effects?: string[];
+/** The picture's JSON beyond its image: everything {@link IPicture.JSON} states but `resId`. */
+type Data = Omit<IPicture.JSON, 'resId'>;
+interface State extends AbstractMovableContent.State {
+    /** The image shown. In the state so that a change of picture undoes with the rest. */
+    resource: IResource;
+    /** What the picture states of itself beyond the image; absent for an inserted picture. */
+    data?: Data;
 }
 /**
  * Implementation for {@link IPicture}.
  */
-export declare class Picture extends AbstractModel<State, IPicture.JSON> implements IPicture {
-    private _resource;
+export declare class Picture extends AbstractMovableContent<State, IPicture.JSON> implements IPicture {
+    /** The resource {@link _details} and {@link _dataUrl} were read from; another resource is another read. */
+    private _detailsSource;
     private _details?;
     private _dataUrl?;
+    private _getStyles;
+    private _style;
     constructor(options: Picture.ConstructorOptions);
     /** {@inheritDoc IPicture.getType} */ getType(): string;
     toJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
     getTypeDescription(): string;
+    /** {@inheritDoc IPicture.getShapeType} */
+    getShapeType(): string;
+    /** {@inheritDoc IPicture.setShapeType} */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPicture.getStyle} */
+    getStyle(): IShapeStyle;
+    /** Writes what the picture states of its fill and border: a key `undefined` is removed. */
+    private _writeStyle;
+    /** {@inheritDoc IMovable.IContent.acceptRotation} */
+    acceptRotation(degrees: number): number;
+    /** {@inheritDoc IMovable.IContent.acceptFlip} */
+    acceptFlip(flip: IMovable.Flip): IMovable.Flip;
+    /** {@inheritDoc IMovable.IContent.getDefaultAnchorType} */
+    getDefaultAnchorType(): IAnchored.Type;
+    /** {@inheritDoc IMovable.IContent.isDefaultLockAspectRatio} */
+    isDefaultLockAspectRatio(): boolean;
     /** @internal */
     protected _asDataUrl(): Promise<string>;
     /** {@inheritDoc IPicture.toHtml} */
@@ -25,6 +54,10 @@ export declare class Picture extends AbstractModel<State, IPicture.JSON> impleme
     toArrayBuffer(): Promise<ArrayBuffer>;
     /** {@inheritDoc IPicture.getResource} */
     getResource(): IResource;
+    /** {@inheritDoc IPicture.setResource} */
+    setResource(picture: string | IResource | IResourceCollection.AddOptions, options?: ITransaction.OperationOptions): this;
+    /** The resource shown, dropping what was read from another one. */
+    private _readFrom;
     /** {@inheritDoc IPicture.getDetails} */
     getDetails(): Promise<IPicture.Details>;
     /** @internal */
@@ -35,6 +68,8 @@ export declare class Picture extends AbstractModel<State, IPicture.JSON> impleme
     protected _toDrawingJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
     /** @internal */
     protected _processDelete(): void;
+    /** {@inheritDoc IPicture.isIPicture} */
+    get isIPicture(): true;
 }
 /**
  * Interfaces for creating `Picture` items.
@@ -48,19 +83,12 @@ export declare namespace Picture {
     /**
      * Options for creating an IPicture.
      */
-    interface ConstructorOptions extends IModel.ConstructorOptions<IPicture.JSON> {
+    interface ConstructorOptions extends AbstractMovableContent.ConstructorOptions<IPicture.JSON> {
         resource?: IResource;
         /**
          * Returns an IResource from the resourceId or null if not found.
          */
         fromResourceId?: (resourceId: number) => IResource;
-        /**
-         * Useful for load/save/copying.
-         */
-        /**
-         * Allow for the default lock aspect ratio to be overwritten.
-         */
-        defaultLockAspectRatio?: boolean;
     }
 }
 export {};

package/types/src/pivot/IPivotTable.d.ts

@@ -0,0 +1,72 @@
+import { IResource } from '../resource';
+import { IWorksheet } from '../sheet';
+import { ICellRange } from '../cellRange';
+import { IAnchored } from '../anchored';
+import { IEmbeddedPart } from '../io';
+/**
+ * A pivot table laid out on a sheet: the part it was read from, anchored at its location.
+ *
+ * @remarks
+ * The table is not modeled yet beyond where it sits and what it summarizes: its markup is kept
+ * as read and written back as read, with the location restated. Where it sits follows
+ * structural edits as a table's range does; an edit that would move only part of it is refused,
+ * as Excel refuses it, and one that takes every cell of it deletes it.
+ */
+export interface IPivotTable extends IAnchored {
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.JSON | null;
+    /**
+     * Returns the name, unique across the workbook as Excel keeps it.
+     */
+    getName(): string;
+    /**
+     * Returns the sheet the table is laid out on.
+     */
+    getWorksheet(): IWorksheet;
+    /**
+     * Returns the cells the table is laid out on.
+     *
+     * @remarks
+     * The anchor: an insert or delete before the table moves it, one taking every cell of it
+     * deletes it ({@link IAnchored.isDeleted}), and one that would move part of it - a row deleted
+     * or inserted inside it, a column cut through it - is refused.
+     */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns the markup of the table's part, with the location as it is now.
+     */
+    getXML(): string | null;
+    /**
+     * Returns the id of the cache this table summarizes.
+     *
+     * @remarks
+     * The cache is the workbook's, written once and referenced from each table by id.
+     *
+     * @internal
+     */
+    getCacheId(): number;
+    /** For runtime type checking. */
+    readonly isIPivotTable: true;
+}
+export declare namespace IPivotTable {
+    /**
+     * A pivot cache as the workbook carries it: the part, by the id the tables name.
+     */
+    interface CacheJSON {
+        cacheId: number;
+        part?: IEmbeddedPart.JSON;
+    }
+    /**
+     * JSON representation of a pivot table.
+     */
+    interface JSON {
+        name?: string;
+        cacheId: number;
+        part?: IEmbeddedPart.JSON;
+    }
+    /**
+     * `Events` for {@link IPivotTable}.
+     */
+    interface Events extends IAnchored.Events<IPivotTable> {
+    }
+}
+//# sourceMappingURL=IPivotTable.d.ts.map

package/types/src/pivot/IPivotTableCollection.d.ts

@@ -0,0 +1,25 @@
+import { ICollection } from '../type';
+import { IPivotTable } from './IPivotTable';
+/**
+ * Holds {@link IPivotTable | pivot tables} — a sheet's, or every sheet's in the workbook.
+ *
+ * @remarks
+ * Read-only for now: a table is carried as it was read and written back unchanged. Adding,
+ * deleting and refreshing wait on the table having a model of its own.
+ */
+export interface IPivotTableCollection extends ICollection<IPivotTable> {
+    /**
+     * Returns the pivot tables, in the order they were read; the workbook's walks its sheets in
+     * sheet order.
+     */
+    getItems(options?: ICollection.GetItemsOptions): IPivotTable[];
+    /**
+     * Returns the pivot table with the given name, or `null` if there is none.
+     *
+     * @param name The name of the pivot table. This is case insensitive.
+     */
+    getByName(name: string): IPivotTable | null;
+    /** For runtime type checking. */
+    readonly isIPivotTableCollection: true;
+}
+//# sourceMappingURL=IPivotTableCollection.d.ts.map

package/types/src/pivot/PivotCache.d.ts

@@ -0,0 +1,34 @@
+import { IResource } from '../resource';
+import { IEmbeddedPart } from '../io';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IPivotTable } from './IPivotTable';
+/**
+ * A pivot cache as the workbook holds it: the part it was read from, and its source held in the
+ * calculation engine so it follows the cells it names.
+ *
+ * @remarks
+ * The cache is workbook-level and shared by every table on it. Its `<cacheSource>
+ * <worksheetSource ref sheet>` is the one thing in the part that names cells; it is held through
+ * the seam of the sheet it names ({@link _hold}), once the sheets exist, and restated in place by
+ * {@link getXML}. A source that is a defined name or an external book holds nothing and is
+ * written as read.
+ * @internal
+ */
+export declare class PivotCache {
+    readonly cacheId: number;
+    readonly part: IEmbeddedPart | null;
+    /** The source as the engine holds it; `null` while nothing is held. */
+    private _source;
+    constructor(cacheId: number, part: IEmbeddedPart | null);
+    /**
+     * Holds the source through the sheet it names. Asked once the sheets exist; a source naming no
+     * sheet of the workbook is left as read.
+     *
+     * @param resolve The seam of the sheet with that name, or `null` when there is none.
+     */
+    _hold(resolve: (sheetName: string) => AbstractMovableContent.AddWatch | null): void;
+    /** The part's markup, its source restated where the engine has moved it. */
+    getXML(): string | null;
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.CacheJSON;
+}
+//# sourceMappingURL=PivotCache.d.ts.map

package/types/src/pivot/PivotTable.d.ts

@@ -0,0 +1,61 @@
+import { IRange } from '@sheetxl/primitives';
+import { IResource } from '../resource';
+import { IWorksheet } from '../sheet';
+import { Anchored } from '../anchored/Anchored';
+import { AbstractAnchored } from '../anchored/AbstractAnchored';
+import { IEmbeddedPart } from '../io';
+import { IPivotTable } from './IPivotTable';
+interface State extends AbstractAnchored.State {
+    anchorCoords: IRange.Coords;
+    cacheId: number;
+    name: string | null;
+}
+/**
+ * Implementation for {@link IPivotTable}: the part it was read from, anchored on the sheet at its
+ * `<location ref>`.
+ *
+ * @remarks
+ * The location is where the table SITS, so it is the anchor, as a table's range is, and the
+ * sheet's anchored map moves it with structural edits inside their commit. The table rules on
+ * those edits as a table does ({@link _processContainerShift}), with Excel's rule: an edit before
+ * it moves it whole, one taking every cell of it deletes it, anything that would move part of it
+ * is refused. {@link getXML} restates the anchor into the part; the rest of the part is as read.
+ */
+export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Events> implements IPivotTable {
+    protected _sheet: IWorksheet;
+    protected _part: IEmbeddedPart | null;
+    /** The location as the part spells it. While the anchor still says the same, the part is as read. */
+    private _ref;
+    constructor(options: PivotTable.ConstructorOptions);
+    protected _initialize(options: PivotTable.ConstructorOptions): void;
+    /** {@inheritDoc IPivotTable.getName} */
+    getName(): string;
+    /** {@inheritDoc IPivotTable.getWorksheet} */
+    getWorksheet(): IWorksheet;
+    /** {@inheritDoc IPivotTable.getXML} */
+    getXML(): string | null;
+    /** {@inheritDoc IPivotTable.getCacheId} */
+    getCacheId(): number;
+    /** {@inheritDoc IPivotTable.toJSON} */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IPivotTable.JSON | null;
+    /**
+     * Excel's rule, from `pivot-probes/probe-pivot-structural.ps1` (2026-10-15): the table moves
+     * whole or goes whole. A shift that would split it or change its extent - a row or column cut
+     * through it, an insert inside it, a shift of some of its columns - is refused with Excel's own
+     * refusal, as a user error, before anything of the edit commits.
+     * @internal
+     */
+    protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /** @internal */
+    protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
+    /** {@inheritDoc IPivotTable.isIPivotTable} */
+    get isIPivotTable(): true;
+}
+export declare namespace PivotTable {
+    interface ConstructorOptions extends Anchored.ConstructorOptions<IPivotTable.JSON> {
+        sheet: IWorksheet;
+        fromResourceId?: (resourceId: number) => IResource;
+    }
+}
+export {};
+//# sourceMappingURL=PivotTable.d.ts.map

package/types/src/pivot/PivotTableCollection.d.ts

@@ -0,0 +1,25 @@
+import { AbstractCollection } from '../type';
+import { IPivotTable } from './IPivotTable';
+import { IPivotTableCollection } from './IPivotTableCollection';
+/**
+ * Implementation for {@link IPivotTableCollection}.
+ *
+ * @remarks
+ * A front over storage held elsewhere — the sheet's own tables, or a walk over every sheet's for
+ * the workbook — so the same class serves both. Nothing edits a pivot table yet, so there is
+ * nothing to announce.
+ */
+export declare class PivotTableCollection extends AbstractCollection<IPivotTable> implements IPivotTableCollection {
+    private _getItemsDelegate;
+    /**
+     * @param getItems Returns the tables, as an array the caller may keep.
+     */
+    constructor(getItems: () => IPivotTable[]);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(): IPivotTable[];
+    /** {@inheritDoc IPivotTableCollection.getByName} */
+    getByName(name: string): IPivotTable | null;
+    /** {@inheritDoc IPivotTableCollection.isIPivotTableCollection} */
+    get isIPivotTableCollection(): true;
+}
+//# sourceMappingURL=PivotTableCollection.d.ts.map

package/types/src/pivot/_PivotXml.d.ts

@@ -0,0 +1,24 @@
+import { IRange } from '@sheetxl/primitives';
+import { IPivotTable } from './IPivotTable';
+/** Character data as the markup spells it, decoded. */
+export declare function decodeXml(text: string): string;
+/** `text` as an attribute value spells it. */
+export declare function encodeXml(text: string): string;
+/**
+ * A plain A1 reference as the part spells it (`B3`, `A1:A7`, relative) made absolute, which is how
+ * it is held: a relative endpoint in a body that has no position is left where it is written,
+ * and these name fixed cells.
+ */
+export declare function absoluteA1(ref: string): string;
+/** The held text back in the part's spelling: relative. */
+export declare function relativeA1(ref: string): string;
+/**
+ * The cells a pivot table's part says it is laid out on (`<location ref>`), as coords on its own
+ * sheet, or `null` when the part states none it can be anchored at.
+ */
+export declare function locationCoordsOf(json: IPivotTable.JSON | undefined): IRange.Coords | null;
+/** `attribute` of the first `element` in `xml`, decoded, or `null` when either is absent. */
+export declare function readAttribute(xml: string, element: string, attribute: string): string | null;
+/** `xml` with `attribute` of the first `element` restated as `value`; unchanged when either is absent. */
+export declare function writeAttribute(xml: string, element: string, attribute: string, value: string): string;
+//# sourceMappingURL=_PivotXml.d.ts.map

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

@@ -0,0 +1,6 @@
+/**
+ * @hidden
+ */
+export * from './IPivotTable';
+export * from './IPivotTableCollection';
+//# sourceMappingURL=index.d.ts.map

package/types/src/primitives/CompositeRangeStats.d.ts

@@ -24,6 +24,8 @@ export declare class CompositeRangeStats implements IRangeStats {
     protected _typedCounts: Readonly<Record<ScalarType, number>> | undefined;
     protected _frequencies: Readonly<IRangeStats.IFrequency> | undefined;
     constructor(children: readonly IRangeStats[]);
+    /** @inheritdoc IRangeStats.getCoords */
+    getCoords(): IRange.Coords | null;
     /** @inheritdoc IRangeStats.getSize */
     getSize(): number;
     /** @inheritdoc IRangeStats.getCount */

package/types/src/primitives/Criteria.d.ts

@@ -30,6 +30,6 @@ export declare const Criteria: {
      * Parse criteria and return a predicate function for testing values against it.
      * Each operator gets its own closure, avoiding repeated branching on every call.
      */
-    createEvaluator: (context: IFormulaContext, criteria: Scalar) => IFormulaContext.CriteriaEvaluator;
+    createEvaluator: (context: IFormulaContext, criteria: Scalar, options?: IFormulaContext.CriteriaOptions) => IFormulaContext.CriteriaEvaluator;
 };
 //# sourceMappingURL=Criteria.d.ts.map

package/types/src/primitives/Grouping.d.ts

@@ -0,0 +1,65 @@
+import { IFormulaContext, IRange, Scalar } from '@sheetxl/primitives';
+/**
+ * Builds the column a group's members come back in: `size` rows, with `values[i]` at `rows[i]`
+ * and every other row blank.
+ */
+export type GroupingColumnFactory = (size: number, rows: ArrayLike<number>, values: ArrayLike<Scalar>, count: number) => IRange;
+/**
+ * Records grouped by key — see {@link IFormulaContext.createGrouping}.
+ *
+ * @remarks
+ * ### Not public API
+ *
+ * Reached as `IFormulaContext.createGrouping`, the same arrangement `Criteria` has.
+ *
+ * ### Shape of the work
+ *
+ * Every key column is read once, by its non-blank entries, into one small id per record. A record
+ * the entries never reached is blank in that column, so a whole-column key over a short table
+ * costs the table, not the column. The ids then assign each kept record a group, and a counting
+ * sort numbers each record within its group.
+ *
+ * A value column is bucketed the same way the first time it is asked for, so a group's members are
+ * one bucket rather than a scan of the column. Blank members are not stored at all: the member
+ * column is created at the group's size and only the non-blank rows are written.
+ */
+export declare class Grouping implements IFormulaContext.Grouping {
+    private readonly _createColumn;
+    private readonly _recordCount;
+    /** Per record, its group, or -1 when the filter left it out. */
+    private readonly _groupOf;
+    /** Per group, the number of records. */
+    private readonly _sizes;
+    /** Per group, its key (first record's spelling). */
+    private readonly _keys;
+    /** Records kept, in record order — `null` when every record is kept. */
+    private readonly _kept;
+    /** Kept records ordered by group, record order within each group. */
+    private readonly _order;
+    /** Per group, where its records start in `_order`. */
+    private readonly _offsets;
+    /** Per record, its place within its group. */
+    private readonly _rankInGroup;
+    /** Per group, its first record. */
+    private readonly _firstRecord;
+    private readonly _buckets;
+    constructor(keys: IRange, createColumn: GroupingColumnFactory, options?: IFormulaContext.GroupingOptions);
+    /** @inheritdoc IFormulaContext.Grouping.getRecordCount */
+    getRecordCount(): number;
+    /** @inheritdoc IFormulaContext.Grouping.getGroupCount */
+    getGroupCount(): number;
+    /** @inheritdoc IFormulaContext.Grouping.getSize */
+    getSize(group: number): number;
+    /** @inheritdoc IFormulaContext.Grouping.getKeys */
+    getKeys(group: number): readonly Scalar[];
+    /** @inheritdoc IFormulaContext.Grouping.getGroup */
+    getGroup(record: number): number;
+    /** @inheritdoc IFormulaContext.Grouping.getFirstRecord */
+    getFirstRecord(group: number): number;
+    /** @inheritdoc IFormulaContext.Grouping.getMembers */
+    getMembers(values: IRange, groups?: readonly number[]): IRange;
+    /** The records of some groups, ascending. */
+    private _recordsOf;
+    private _getBuckets;
+}
+//# sourceMappingURL=Grouping.d.ts.map

package/types/src/primitives/LambdaBrand.d.ts

@@ -0,0 +1,26 @@
+import { IFunction } from '@sheetxl/primitives';
+import { LambdaCallable } from '../calculation/formula/LambdaValue';
+/**
+ * The brand a function value carries — what `LAMBDA(…)` evaluates to (`LambdaValue`) and what a
+ * bare function name eta-reduces to (`FunctionValue`).
+ *
+ * @remarks
+ * A function value IS an {@link IFunction}: a body whose untyped (`any`) parameter receives one — or
+ * an array of them, `HSTACK(SUM, AVERAGE)` — calls it like any other function (`GROUPBY`'s `fn`).
+ * A lambda-typed parameter instead receives a plain callable (`Lambda`). The brand exists so that
+ * the value-layer sites — coercion, the operators, a range's typed read — can RECOGNIZE a function
+ * value and refuse it without importing the calculation layer — the same structural pattern, and for
+ * the same reason, as `CalcSignal`.
+ *
+ * The brand is `isFunctionValue`, not `isLambda`: {@link IFunction.isLambda} is a method, and an
+ * eta-reduced built-in is a function value whose `isLambda()` is `false`.
+ */
+export interface ILambdaValue extends IFunction {
+    /** The brand itself — the property every recognizing site reads. */
+    readonly isFunctionValue: true;
+    /** Marshals the value into the callable a lambda-typed parameter receives. */
+    makeCallable(): LambdaCallable;
+}
+/** `true` for a function value — see {@link ILambdaValue}. */
+export declare const isLambdaValue: (value: unknown) => value is ILambdaValue;
+//# sourceMappingURL=LambdaBrand.d.ts.map