@sheetxl/query 0.8.0-beta.2 → 0.8.0-beta.21

package/package.json

@@ -1,21 +1,20 @@
 {
   "name": "@sheetxl/query",
   "description": "SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface",
-  "version": "0.8.0-beta.2",
-  "license": "SEE LICENSE IN <LICENSE>",
+  "version": "0.8.0-beta.21",
+  "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "browser": "./browser/esm/index.mjs",
       "node": "./node/esm/index.mjs",
-      "import": "./browser/esm/index.mjs",
-      "require": "./browser/cjs/index.cjs"
+      "default": "./browser/esm/index.mjs"
     }
   },
   "types": "./types/index.d.ts",
   "module": "./browser/esm/index.mjs",
-  "main": "./browser/cjs/index.cjs",
+  "main": "./browser/esm/index.mjs",
   "sideEffects": false,
   "engines": {
     "node": ">=20 <21 || >=22"
@@ -43,10 +42,10 @@
     "query"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.2",
-    "@sheetxl/sdk": "^0.8.0-beta.2"
+    "@sheetxl/primitives": "^0.8.0-beta.21",
+    "@sheetxl/sdk": "^0.8.0-beta.21"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2"
+    "@types/node": "^26.6.4"
   }
 }

package/types/src/api/_aliases.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Names a script reaches for from another spreadsheet API — Excel's, Office Scripts', openpyxl's —
+ * and where SheetXL keeps that concept. Each answer names the member it relies on, and is offered
+ * only while the index still has it.
+ */
+export declare const API_ALIASES: readonly {
+    readonly match: RegExp;
+    readonly relies: [string, string];
+    readonly hint: string;
+}[];
+/**
+ * The answer to a member called on a plain array (`wb.getSheets().getAt(0)`): `getAt`/`getItems`
+ * belong to a collection, and an array is indexed.
+ */
+export declare const arrayReceiverHint: (elementType: string) => string;
+//# sourceMappingURL=_aliases.d.ts.map

package/types/src/api/_offered.d.ts

@@ -0,0 +1,13 @@
+import { ScriptingApi } from '@sheetxl/sdk';
+/**
+ * Whether a declaration is offered. A `@deprecated` or `@hidden` one stays declared so a script that
+ * calls it still type-checks, and a lookup of its exact name still answers with its replacement; it
+ * is left out of listings, searches and suggestions, so nothing leads a reader to it.
+ */
+export declare const isOffered: (declared: {
+    readonly deprecated?: true;
+    readonly hidden?: true;
+}) => boolean;
+/** The members of `entry` that are {@link isOffered | offered}. */
+export declare const offeredMembers: (entry: ScriptingApi.Entry) => ScriptingApi.Member[];
+//# sourceMappingURL=_offered.d.ts.map

package/types/src/api/lookupApi.d.ts

@@ -60,7 +60,43 @@ export declare namespace ApiLookup {
         /** Matches beyond the caps, not listed. */
         readonly omitted: number;
     }
-    type Result = Overview | Type | Member | Search;
+    /**
+     * `Type.member` where the API has no such thing — the type, the member, or both — answered
+     * with what is nearest rather than with a search for the member's name across every type.
+     *
+     * @remarks
+     * A dotted name is a claim about where something lives, and the claim is what the reader needs
+     * corrected: `ISheets.add` wants to hear that the collection is `IWorksheetCollection`, and
+     * `ICellRange.setStyle` that a range's style is reached through `getStyle()`. A bare search for
+     * `add` or `setStyle` lists every type that has one and leaves the claim standing.
+     */
+    interface Miss {
+        readonly kind: 'miss';
+        /** The type as typed, and the index key it resolved to — `null` when no type matched. */
+        readonly owner: {
+            readonly text: string;
+            readonly key: string | null;
+        };
+        /** The member as typed. */
+        readonly text: string;
+        /** When the type is unknown: the nearest type names, those with the member first. */
+        readonly nearestTypes: readonly {
+            readonly key: string;
+            readonly hasMember: boolean;
+        }[];
+        /** When the type is known: its members nearest the name, inherited ones included. */
+        readonly nearest: readonly ScriptingApi.Member[];
+        /** Where SheetXL keeps a concept another API spells this way, when the name is one of those. */
+        readonly hints: readonly string[];
+        /** Types that do have a member of exactly this name. */
+        readonly elsewhere: readonly {
+            readonly key: string;
+            readonly member: ScriptingApi.Member;
+        }[];
+        /** `elsewhere` entries beyond the cap, not listed. */
+        readonly elsewhereOmitted: number;
+    }
+    type Result = Overview | Type | Member | Search | Miss;
 }
 /**
  * The names an overview leads with — where a script's reach into a workbook starts.
@@ -108,6 +144,14 @@ export declare function apiTypeOf(index: ScriptingApi.Index, target: unknown): s
  * generic or a primitive is not something the index answers for.
  */
 export declare function apiPointerFor(message: string, command: string): string | null;
+/**
+ * A compiler finding without its `Did you mean '…'?` when TypeScript means a member the index does
+ * not offer — a deprecated alias is still declared, so the compiler finds it nearest.
+ *
+ * @param message A compiler finding, e.g. `Property 'setFormat' does not exist on type 'ICellRange'.
+ * Did you mean 'getFormat'?`
+ */
+export declare function withoutHiddenSuggestion(index: ScriptingApi.Index, message: string): string;
 /**
  * The members nearest a name the script used and the API does not have — the answer an `api`
  * lookup would be asked for next, inline.

package/types/src/delta/describeDelta.d.ts

@@ -0,0 +1,148 @@
+import { IRange } from '@sheetxl/primitives';
+import { IWorkbook, IWorksheet } from '@sheetxl/sdk';
+/**
+ * What one commit did to a workbook, at region altitude: the structured half of the run delta.
+ *
+ * @remarks
+ * JSON-safe, so a host can send it as it is; {@link renderDelta} is its markdown. Every address is
+ * sheet-qualified and every list is capped, with the uncounted rest in a `more` field.
+ */
+export interface RunDelta {
+    /** The commit described. */
+    commitId: string;
+    /** One entry per sheet whose cells the commit changed. */
+    sheets: RunDelta.SheetChange[];
+    /** The cells downstream of the written ones, or `null` when nothing reads them. */
+    dependents: RunDelta.Dependents | null;
+    /** Errors now in the written and dependent cells, by region. */
+    errors: RunDelta.ErrorRegion[];
+    /** Error regions past {@link RunDelta.errors}. */
+    errorsMore: number;
+    /** Written cells that held an error before the commit and hold none now. */
+    errorsCleared: number;
+    /** What is not a cell, over the written or dependent cells. */
+    touches: RunDelta.Touches;
+}
+export declare namespace RunDelta {
+    /** What a commit did to one sheet. */
+    interface SheetChange {
+        /** The sheet, quoted as a reference would quote it. */
+        sheet: string;
+        /** The cells whose values or formulas were written, or `null` when none were. */
+        written: string | null;
+        /** Cells in {@link written}. */
+        cells: number;
+        /** Written cells that now hold a formula. */
+        formulas: number;
+        /** Written cells that now hold a value that is not a formula. */
+        values: number;
+        /** Written cells that are now empty. */
+        cleared: number;
+        /**
+         * What the write replaced, from the sheet as it was: populated cells and formulas among the
+         * written ones. `null` when it cannot be told: the commit moved cells, or the store no longer
+         * keeps the state before it.
+         */
+        replaced: {
+            populated: number;
+            formulas: number;
+        } | null;
+        /** The inserts and deletes of cells, in the order they ran. */
+        shifts: Shift[];
+        /** Ranges whose formatting changed, or `null`. */
+        styles: string | null;
+        /** The written formulas, one per block of the same formula. */
+        blocks: FormulaBlock[];
+        /** Blocks past {@link blocks}. */
+        blocksMore: number;
+    }
+    /** One insert or delete of cells. */
+    interface Shift {
+        kind: IWorksheet.ShiftKind;
+        /** The axis the neighboring cells moved along. */
+        axis: IRange.Axis;
+        /** The cells inserted or deleted, sheet-qualified; `null` when the state before was not kept. */
+        address: string | null;
+        /** Whole rows or columns, rather than cells within them. */
+        whole: boolean;
+    }
+    /** One written formula and the results it computed. */
+    interface FormulaBlock {
+        /** The block, sheet-qualified. */
+        address: string;
+        /** The formula as its first cell shows it, `=` included. */
+        formula: string;
+        /** Cells in the block. */
+        cells: number;
+        /** Results in reading order: all of them for a small block, else the first few and the last. */
+        values: string[];
+        /** `true` when {@link values} skips some, between its last two entries. */
+        sampled: boolean;
+    }
+    /** The cells downstream of the write. */
+    interface Dependents {
+        /** Populated dependent cells. */
+        cells: number;
+        /** The sheets they are on, with their cells. */
+        sheets: {
+            sheet: string;
+            cells: number;
+        }[];
+        /** Their areas, sheet-qualified. */
+        areas: string[];
+        /** Areas past {@link areas}. */
+        areasMore: number;
+    }
+    /** A region of one error, with its count. */
+    interface ErrorRegion {
+        /** Sheet-qualified. */
+        address: string;
+        /** The error as a cell shows it: `#VALUE!`, `#REF!`, … */
+        error: string;
+        /** Cells in the region. */
+        cells: number;
+    }
+    /** Objects over the written or dependent cells: listed, never evaluated. */
+    interface Touches {
+        /** Defined names over the written or dependent cells, or read through by a dependent. */
+        names: string[];
+        /** Conditional formats over the written or dependent cells, by their anchors. */
+        conditionalFormats: string[];
+        /** Data validations over the written or dependent cells, by their anchors. */
+        dataValidations: string[];
+        /** Charts that read the written cells or their dependents. */
+        charts: string[];
+    }
+}
+/** Options for {@link describeDelta}. */
+export interface DescribeDeltaOptions {
+    /**
+     * How many entries a list holds before the rest is counted: formula blocks, dependent areas,
+     * error regions.
+     *
+     * @defaultValue 20
+     */
+    maxEntries?: number;
+    /**
+     * How many results a formula block lists in full; a longer block lists its first few and its
+     * last.
+     *
+     * @defaultValue 8
+     */
+    maxBlockValues?: number;
+}
+/**
+ * Describes what a commit did, read from the workbook after its calculation settled.
+ *
+ * @param workbook The workbook the commit landed on, settled.
+ * @param commitId The commit. Omit for the current one.
+ * @returns `null` when the commit changed no cells.
+ *
+ * @remarks
+ * Nothing here is collected on the write path. The written ranges come from the commit
+ * ({@link IWorkbook.getChanges}), what they replaced from the sheet as it was at the commit before
+ * ({@link IWorksheet.ChangeEvent.getPreviousRanges}), and everything else is a read of the settled
+ * workbook bounded by what was written.
+ */
+export declare function describeDelta(workbook: IWorkbook, commitId?: string, options?: DescribeDeltaOptions): Promise<RunDelta | null>;
+//# sourceMappingURL=describeDelta.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './describeDelta';
+export * from './renderDelta';
+export * from './readRunDelta';
+//# sourceMappingURL=index.d.ts.map

package/types/src/delta/readRunDelta.d.ts

@@ -0,0 +1,21 @@
+import { IWorkbook } from '@sheetxl/sdk';
+import { DescribeDeltaOptions, RunDelta } from './describeDelta';
+/** What {@link readRunDelta} hands a run report. */
+export interface RunDeltaReport {
+    /** The delta, JSON-safe; absent when the commit changed no cells or it could not be read. */
+    delta?: RunDelta;
+    /** The report's lines: the delta rendered, or why it could not be read. */
+    markdown?: string;
+}
+/**
+ * The delta of a run's commit, as a run report carries it: the structure and its lines.
+ *
+ * @param workbook The workbook the run committed to, settled.
+ * @param commitId The run's commit; nothing is read without one (a run that wrote nothing).
+ *
+ * @remarks
+ * Never throws. The run has already committed, and a delta that cannot be read must not turn a
+ * write that landed into a reported failure, so the reason is reported in its place.
+ */
+export declare function readRunDelta(workbook: IWorkbook, commitId: string | undefined, options?: DescribeDeltaOptions): Promise<RunDeltaReport>;
+//# sourceMappingURL=readRunDelta.d.ts.map

package/types/src/delta/renderDelta.d.ts

@@ -0,0 +1,20 @@
+import { RunDelta } from './describeDelta';
+/**
+ * Renders a {@link RunDelta} as the lines a run report appends.
+ *
+ * @remarks
+ * One line per fact, labeled, so a reader scans the labels: what was written and what it
+ * replaced, the formulas with their results, what moved, what reads the write, the errors, and
+ * what sits over it that is not a cell.
+ *
+ * @example
+ * ```
+ * Changed:      Sheet1!H7:H38 — 32 formulas, 0 populated cells replaced
+ *   Sheet1!H7:H38  =B7*C7  → 12, 15, 18 … 90 (32 cells)
+ * Structure:    Sheet1!5:7 rows inserted
+ * Dependents:   212 cells on 2 sheets — Sheet1!K7:K38, Summary!B4:B9
+ * Errors:       Sheet1!K9:K12 #VALUE! (4)
+ * ```
+ */
+export declare function renderDelta(delta: RunDelta): string;
+//# sourceMappingURL=renderDelta.d.ts.map

package/types/src/encode/encodeCell.d.ts

@@ -15,7 +15,7 @@ import { ICell, Scalar } from '@sheetxl/sdk';
  *
  * ---
  *
- * **Quarantine note.** `ICell.getText()` is the only SDK call this module makes, and it is on its
+ * **Quarantine note.** `ICell.getText()` is the only SDK text call this module makes, and it is on its
  * way out — its contract fuses formatting, localization, csv escaping and this encoding into one
  * method with no clear answer for large values. It is isolated to this file deliberately: when
  * the SDK splits pure number formatting away from the encoding, exactly one file changes and no
@@ -35,14 +35,26 @@ export declare namespace CellEncoding {
          */
         readonly Display: "display";
         /**
-         * The cell as the formula bar shows it — full precision, number formatting stripped.
+         * The stored scalar — what `getValue()` returns, with no number format applied.
          *
          * @remarks
-         * `1234.5678` where {@link Mode.Display | display} shows `$1,234.57`. Dates stay dates
-         * rather than decaying to serials, so the result is still searchable rather than merely
-         * lossless.
+         * `1234.5678` where {@link Mode.Display | display} shows `$1,234.57`, `0.04` where it shows
+         * `4%`, and a date as its serial. A reader wants one of two things: what the grid shows, or
+         * what a formula computes with. There is deliberately no layer in between — the formula
+         * bar's text (`4%` at full precision, dates kept) is the stored scalar restyled by the
+         * format's category, and both of those are already reported.
          */
         readonly Value: "value";
+        /**
+         * The formula text where the cell has a formula (`=SUM(B2:B9)`), else its stored
+         * {@link Mode.Value | value}.
+         *
+         * @remarks
+         * Excel's Show Formulas view: for reading a block's logic as a grid. The inputs read as the
+         * scalars the formulas compute with — `0.25`, not `25%`; a date as its serial. The text carries
+         * its leading `=`, as the formula bar shows it.
+         */
+        readonly Formula: "formula";
     };
     type Mode = typeof Mode[keyof typeof Mode];
     /**
@@ -137,8 +149,8 @@ export declare function encodeCell(cell: ICell, mode: CellEncoding.Mode): CellEn
  * The counterpart to {@link encodeCell} for the stateless value layer (`IRange`, `Scalar[][]`),
  * where there is no cell to ask for text and therefore **no number format to apply**. That is
  * the whole difference: `0.04` encodes as `0.04` here and as `4%` through a cell that formats
- * it. There is consequently no `mode` — the two modes differ only by how much formatting they
- * apply, and here there is none to strip.
+ * it. There is consequently no `mode` — this is what {@link CellEncoding.Mode.Value} produces
+ * for a cell, and the only form a bare value has.
  *
  * Everything above formatting is identical, because it is the same contract: the `'` prefix on
  * strings, `TRUE`/`FALSE`, error labels, blank elision.

package/types/src/grep/GrepTypes.d.ts

@@ -8,7 +8,7 @@
  * The rule, which predicts any future member:
  * **a grep field is a layer whose text was authored by a person or is read by one.**
  *
- * `display`, `value` and `raw` are read; `formula`, `hyperlink` and `numberFormat` are authored.
+ * `display` and `value` are read; `formula`, `hyperlink` and `numberFormat` are authored.
  * A layer that fails the rule fails it because its payload has no canonical text — a fill's
  * "red" may be stored as `FF0000`, a theme slot, or an indexed palette entry, so any pattern
  * against it silently matches less than it claims: a confident wrong answer, which is worse
@@ -40,28 +40,18 @@ export type GrepField =
  */
 'display'
 /**
- * The cell as the formula bar shows it — most formatting stripped, **category kept**.
+ * The stored scalar — what `getValue()` returns, with no number format applied.
  *
- * `1234.5678` where {@link GrepField | display} shows `$1,234.57` — but `40%` stays `40%`
- * and dates stay dates, because the formula bar keeps minimal formatting for percents,
- * dates and times (Excel's behavior, faithfully). This is *not* the underlying scalar:
- * a percent cell storing `0.4` reads `40%` here. The stored scalar is
- * {@link GrepField | raw}.
+ * `1234.5678` where {@link GrepField | display} shows `$1,234.57`, `0.4` where it shows `40%`,
+ * dates as serial numbers. This is the layer a cell report's `Value` line and the `IRange` /
+ * stats reads print, so it is the field that makes *those* printed values greppable — the
+ * round-trip that `display` provides for formatted reads. Not a default: serials and
+ * unrounded floats are noise until they are the question.
  *
  * Identical to `display` for every cell whose format only decorates (`General`, plain
- * text) — the default search dedupes that case per cell rather than reporting both.
+ * text) — a search of both dedupes that case per cell rather than reporting it twice.
  */
  | 'value'
-/**
- * The stored scalar, encoded bare — what the stateless value layer prints.
- *
- * `0.4` where {@link GrepField | value} shows `40%`; dates as serial numbers. This is the
- * layer `IRange` / stats reads print (they have no cell to format through), so it is the
- * field that makes *those* printed values greppable — the round-trip that `display`
- * provides for formatted reads. Not a default: serials and unrounded floats are noise
- * until they are the question.
- */
- | 'raw'
 /** Formula text, A1 style (`=SUM(A1:A10)`). Cells without a formula contribute nothing. */
  | 'formula'
 /** Hyperlink target — the address, not the display text (which is already `display`). */
@@ -71,8 +61,9 @@ export type GrepField =
  *
  * Authored text (it is literally what was typed into Format Cells), canonical, and regex
  * is its native matcher. `--fields numberFormat "%"` is the well-posed form of "which
- * cells are percentages" — the rendered `40%` is not. Matches cells with a *direct*
- * format, including value-less ones (a formatted-but-empty column is a real finding).
+ * cells are percentages" — the rendered `40%` is not. Matches blocks given a format,
+ * directly or by a named style, including value-less ones (a formatted-but-empty column is
+ * a real finding).
  */
  | 'numberFormat'
 /**
@@ -109,7 +100,6 @@ export type GrepField =
 export declare const GrepField: {
     readonly Display: "display";
     readonly Value: "value";
-    readonly Raw: "raw";
     readonly Formula: "formula";
     readonly Hyperlink: "hyperlink";
     readonly NumberFormat: "numberFormat";
@@ -124,16 +114,15 @@ export declare const GREP_FIELDS: readonly GrepField[];
  * The default field set.
  *
  * @remarks
- * What you can see, what the formula bar shows, and what is structurally behind both.
- * `value` is a default *because* the search dedupes it: for the majority of cells it is
- * byte-identical to `display` and is suppressed per cell, so it only surfaces where it
- * carries new information — `1234.5678` behind `$1,234.57`. A duplicate hit costs an agent
- * a second look for no new information; a missing layer costs a silent zero-hit miss on
- * full-precision searches, which is worse.
+ * What you can see and what is structurally behind it. `value` is opt-in: a search is almost
+ * always for text as the grid shows it, and the stored scalar in a default search makes every
+ * numeric pattern hit date serials and unrounded floats nobody was looking at. The search that
+ * wants it — a full-precision number copied from a stats read or a cell report's `Value` line —
+ * knows it does, and asks with `fields: ['value']`.
  *
- * The layers off the grid are defaults by the same argument. A caller who has to ask for
- * `shape` already knows the callout is there; the search that needs it is the one that does
- * not. They cost one pass over a sheet's objects, not over its cells.
+ * The layers off the grid are defaults. A caller who has to ask for `shape` already knows the
+ * callout is there; the search that needs it is the one that does not. They cost one pass over a
+ * sheet's objects, not over its cells.
  */
 export declare const GREP_FIELDS_DEFAULT: readonly GrepField[];
 /** What a grep result should carry. */
@@ -178,7 +167,7 @@ export interface GrepArgs {
      * Which layers to search.
      *
      * @defaultValue {@link GREP_FIELDS_DEFAULT} —
-     * `['display', 'value', 'formula', 'comment', 'shape', 'chart', 'name']`
+     * `['display', 'formula', 'comment', 'shape', 'chart', 'name']`
      */
     fields?: readonly GrepField[];
     /**
@@ -250,7 +239,8 @@ export interface GrepArgs {
      *
      * @remarks
      * Counts **cells and objects**, not match rows — a cell matching in two fields is one unit of
-     * budget, and so is a chart matching in its title and an axis.
+     * budget, and so is a chart matching in its title and an axis, and a block matching in its
+     * hyperlink or number format.
      * The search looks one match past the cap, so a result that ends exactly at `maxCount` is
      * only reported truncated when a further match actually exists.
      */
@@ -302,8 +292,9 @@ export interface GrepMatch {
      */
     sheet: string;
     /**
-     * A1 cell address within the sheet; the anchor range (`F2:H6`) for a shape or chart; the name
-     * itself for a defined name. Qualified with `sheet`, each is something a follow-up call takes.
+     * A1 cell address within the sheet; the block (`A:J`) for a hyperlink or number format; the
+     * anchor range (`F2:H6`) for a shape or chart; the name itself for a defined name. Qualified
+     * with `sheet`, each is something a follow-up call takes.
      */
     address: string;
     /**
@@ -324,7 +315,7 @@ export interface GrepMatch {
 export interface GrepSheetMatches {
     /** Sheet name. */
     sheet: string;
-    /** Distinct cells that produced at least one match in this sheet. */
+    /** Cells that produced a match in this sheet, counted as {@link GrepResult.cellCount} is. */
     cells: number;
     /** Shapes and charts on this sheet that produced at least one match. */
     objects: number;
@@ -337,7 +328,10 @@ export interface GrepResult {
     /** Resolved human-readable scope, e.g. `Sheet1!A1:D847` or `workbook`. */
     scope: string;
     matches: readonly GrepMatch[];
-    /** Distinct cells that produced at least one match. */
+    /**
+     * Cells that produced a match. A hyperlink or number format block counts all of its cells, and
+     * a cell also matching in another field is counted again.
+     */
     cellCount: number;
     /** Shapes, charts and names that produced at least one match. */
     objectCount: number;

package/types/src/grep/grep.d.ts

@@ -4,8 +4,9 @@ import { GrepArgs, GrepResult } from './GrepTypes';
  * Searches a workbook's text by pattern — its cells, and what is written off the grid.
  *
  * @remarks
- * Per sheet: the cells in reading order (a comment rides its cell), then the shapes and charts
- * in reading order of their anchors. Defined names follow every sheet, since they belong to none.
+ * Per sheet: the cells in reading order (a comment rides its cell), then the blocks a hyperlink or
+ * number format is stated over, then the shapes and charts in reading order of their anchors.
+ * Defined names follow every sheet, since they belong to none.
  *
  * Deliberately shaped after ripgrep — args, defaults and vocabulary are pretrained, and every
  * novel idiom is paid for in error loops.

package/types/src/index.d.ts

@@ -4,6 +4,7 @@ export * from './encode';
 export * from './grep';
 export * from './api';
 export * from './markdown';
+export * from './delta';
 /**
  * The read surface, defined once.
  *

package/types/src/markdown/appendDataTables.d.ts

@@ -0,0 +1,39 @@
+import { ICellRange, IWorksheet } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/** One what-if data table on a sheet: a `TABLE` formula and the results it spills. */
+export interface DataTableListing {
+    /** The results: the spill, or what the counts state when the spill is blocked. */
+    extent: ICellRange;
+    /** The formula at the anchor, `=TABLE(...)`. */
+    formula: string;
+    /** The row input's address, `#REF!` when deleted; `null` for a one-input table down a column. */
+    rowInput: string | null;
+    /** The column input's address, `#REF!` when deleted; `null` for a one-input table along a row. */
+    columnInput: string | null;
+    /** The extent is blocked (`#SPILL!`). */
+    blocked: boolean;
+}
+/**
+ * The sheet's what-if data tables: every formula region whose formula is one whole `TABLE(...)`
+ * call. Read per region of the formula partition, never cell by cell.
+ */
+export declare function findDataTables(sheet: IWorksheet): DataTableListing[];
+/**
+ * The formula cells of a data table, as an address: the corner of a two-input table, the row above
+ * a one-input table down a column, the column left of one along a row.
+ */
+export declare const describeDataTableFormula: (table: DataTableListing) => string;
+/** `=TABLE(B1,C1,3,3)  row input B1, column input C1, formula E2` - one table's listing row. */
+export declare const describeDataTable: (table: DataTableListing) => string;
+/**
+ * `## Data Tables (1)` over `  F3:H5  =TABLE(B1,C1,3,3)  row input B1, column input C1, formula E2`
+ * rows.
+ *
+ * @remarks
+ * A what-if data table is a spilling formula, so the formula and spill partitions already list it.
+ * This section is what says its results are the formula cells evaluated once per axis pair, and
+ * names the cells an edit should reach instead: the inputs, the axes beside the results and the
+ * formula.
+ */
+export declare function appendDataTables(md: MarkdownBuilder, tables: readonly DataTableListing[]): void;
+//# sourceMappingURL=appendDataTables.d.ts.map

package/types/src/markdown/appendDependencies.d.ts

@@ -1,4 +1,4 @@
-import { ICellRange, ICellRanges, IRange, ISheet } from '@sheetxl/sdk';
+import { ICellRange, ICellRanges, IRange, IWorksheet } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
  * Options for the dependency sections.
@@ -36,7 +36,7 @@ export interface DependencyContext {
     /** Print `## Dependents (0)` rather than omitting the section. */
     zeroDependents?: boolean;
     /** The sheet the report is about; members elsewhere are listed as crossings. */
-    home?: ISheet | null;
+    home?: IWorksheet | null;
     /** The cells the report is about, when it is about cells: charts that plot them are dependents too. */
     subject?: ICellRange | null;
 }

package/types/src/markdown/appendPivotTables.d.ts

@@ -1,22 +1,23 @@
 import { IPivotTable } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
- * Where a pivot table is laid out, as the address its markup declares — or `''`.
- *
- * @remarks
- * Read from {@link IPivotTable.getXML} because the table has no model yet and that markup is the
- * documented way to what it does not expose. The address is as the file wrote it: it does not
- * follow rows and columns inserted since, which is the table's own stated limit and not this
- * report's.
+ * Where a pivot table is laid out, as an address — or `''` once it is deleted.
  */
 export declare const describePivotLocation: (pivot: IPivotTable) => string;
 /**
- * `## Pivot Tables (2)` over `  A3:D20  PivotTable1` rows.
+ * `rows: Region > Product · columns: Year · filters: Channel · values: Sum of Sales` — the
+ * fields on each axis, outermost first, or `''` for a table SheetXL does not model.
+ */
+export declare const describePivotFields: (pivot: IPivotTable) => string;
+/**
+ * `## Pivot Tables (2)` over `  A3:D20  PivotTable1  from Data!A1:H500` rows, each followed by its
+ * fields. The source is written as `IPivotTableCollection.add` takes it.
  *
  * @remarks
  * A pivot table's output is ordinary cells, so `Contentful` already lists the block — as numbers
  * and labels, with nothing to say they are a summary of data held elsewhere and will be
- * overwritten by the next refresh in Excel. This section is what says so.
+ * overwritten by the next refresh. This section is what says so, and which tables no longer match
+ * their source.
  */
 export declare function appendPivotTables(md: MarkdownBuilder, pivots: readonly IPivotTable[]): void;
 //# sourceMappingURL=appendPivotTables.d.ts.map