@sheetxl/query 0.8.0-beta.11 → 0.8.0-beta.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.11",
+  "version": "0.8.0-beta.13",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -42,8 +42,8 @@
     "query"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.11",
-    "@sheetxl/sdk": "^0.8.0-beta.11"
+    "@sheetxl/primitives": "^0.8.0-beta.13",
+    "@sheetxl/sdk": "^0.8.0-beta.13"
   },
   "devDependencies": {
     "@types/node": "^26.6.4"

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

@@ -61,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'
 /**
@@ -238,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.
      */
@@ -290,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;
     /**
@@ -312,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;
@@ -325,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/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/appendSections.d.ts

@@ -207,6 +207,17 @@ export interface AppendNamesOptions {
      * since a bare `Sales` in an expression is a `named` token that resolves to a table.
      */
     symbols?: readonly INamed[];
+    /**
+     * Gives rows only to the names some formula reads; the rest are one count on the closing line.
+     *
+     * @defaultValue `false` — every name gets a row (a name manager must be complete)
+     *
+     * @remarks
+     * For a report whose job is routing. A name nothing reads changes no value and breaks no cell,
+     * and a decades-old model carries them by the ten thousand (macro-sheet constants, dead
+     * `#REF!`s): listed, they are the whole section; counted, the section is the names that matter.
+     */
+    omitUnread?: boolean;
 }
 /**
  * A name's spelling as a formula would write it — qualified when it is scoped to one sheet.

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

@@ -13,7 +13,16 @@ export declare const anomalyLabel: (check: string) => string;
  */
 export declare function describeAnomaly(anomaly: ICell.Anomaly, cell: ICell): string;
 /** Every finding at `cell`, `;`-joined; `null` when none fires. */
-export declare function describeAnomalies(cell: ICell): string | null;
+export declare function describeAnomalies(cell: ICell, options?: {
+    constants?: boolean;
+}): string | null;
+/** A `constantFrequency` finding's constant as a formula types it: `12`, `"Total"`, `FALSE`. */
+export declare const describeConstant: (evidence: ICell.Anomaly["evidence"]) => string;
+/**
+ * Whether a region's findings are constants alone: the reports count those in the `Constants`
+ * census rather than listing each region among the breaks.
+ */
+export declare const isConstantOnly: (anomalies: readonly ICell.Anomaly[]) => boolean;
 /**
  * R1C1 references in `text` as A1, read from `at`: `=R[-1]C*2` at `B3` is `=B2*2`. Absolute
  * parts take a `$`, as Excel writes them.

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

@@ -50,7 +50,15 @@ export declare function appendRegionList(md: MarkdownBuilder, regions: readonly
     payload?: RegionPayload;
     profile?: boolean;
     series?: boolean;
+    collapse?: RegionKey;
 }): void;
+/** What a region says, as a key two regions saying the same thing share; `null` keeps it on its own. */
+export type RegionKey = (region: ICellRegion) => string | null;
+/**
+ * An `anomalies` region's key: its findings, check and evidence, without the rank. Two regions
+ * with the same findings are one line of the listing.
+ */
+export declare const anomalyRegionKey: RegionKey;
 /**
  * Renders a partition — the unit `getRegions` returns, so an agent addresses structure instead
  * of guessing ranges.