@sheetxl/query 0.8.0-beta.6 → 0.8.0-beta.9

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

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,12 +35,14 @@ 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";
     };
@@ -137,8 +139,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`). */
@@ -109,7 +99,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 +113,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 +166,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[];
     /**

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

@@ -1,4 +1,4 @@
-import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed } from '@sheetxl/sdk';
+import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed, ISheet } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
  * Options for the feature sections.
@@ -248,6 +248,15 @@ export declare const describeQualifiedName: (named: INamed) => string;
  * row is token noise, and blank-means-normal is how these reports already speak.
  */
 export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[], options?: AppendNamesOptions): Promise<void>;
+/**
+ * The outline in a line — `rows 2 levels, 3 groups (1 collapsed) · columns 1 level, 1 group` —
+ * or `null` when nothing is grouped.
+ *
+ * @remarks
+ * Counts only: the groups themselves (level, span, summary, collapsed) are `IOutline.getGroups`,
+ * which is also what a script reads, so the report routes there instead of listing them.
+ */
+export declare function describeOutline(sheet: ISheet): string | null;
 /**
  * One rule listing — `## Conditional Formats (2)` over `  A1:D10  > 100 → fill #FFFF00` rows.
  *

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

@@ -0,0 +1,30 @@
+import { IShape } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * A shape's text as one quoted row cell.
+ *
+ * @remarks
+ * Quoted, and never paraphrased, so it reads as what it is: content of the workbook, written by
+ * whoever could edit the file, not a statement of the report's. Newlines become a visible mark
+ * rather than a space because authors break lines on purpose — a callout listing three steps is
+ * three lines.
+ *
+ * @param max The cap, or `null` to print all of it.
+ * @param recovery The call that prints the rest; only read when the text is cut.
+ */
+export declare const quoteShapeText: (text: string, max: number | null, recovery: string) => string;
+/**
+ * The facts of a shape a report states beyond its placement: what it is, what it says, how it is
+ * drawn, what it links to and what it is glued to. Each fact only where the shape states it or it
+ * is not the default, so a plain rectangle stays a few lines.
+ *
+ * @remarks
+ * Read from the shape's JSON, which is the model: the accessors cover only its type, text and
+ * adjust values. A fill or line the shape does not state is named by where it comes from (its
+ * theme style) rather than resolved to a color — the theme is the workbook's, and the report says
+ * which reference to follow.
+ */
+export declare function appendShapeFacts(md: MarkdownBuilder, shape: IShape): void;
+/** The content rotation a shape read from a file states, for a movable that has none of its own. */
+export declare const shapeRotation: (shape: IShape) => number;
+//# sourceMappingURL=describeShape.d.ts.map

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

@@ -2,6 +2,7 @@ export * from './appendDependencies';
 export * from './appendSections';
 export * from './describeRegionPayload';
 export * from './describeRule';
+export * from './describeShape';
 export * from './describeStyle';
 export * from './MarkdownBuilder';
 export * from './parseRenderOptions';

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

@@ -19,7 +19,8 @@ import { AppendDependencyOptions } from './appendDependencies';
  * Facets that are not present are omitted rather than reported as absent — merge spans on an
  * unmerged cell, a spill range on a cell that is not spilled. Zeros that ARE facts are printed:
  * a formula nothing reads is an output, and `Dependents (0)` is how the report says it. Value text
- * goes through {@link encodeCell}, so whatever this prints, grep can find.
+ * goes through {@link encodeCell}, so whatever this prints, grep can find: `Display` is grep's
+ * `display` field and `Value` — the stored scalar, what `getValue()` returns — is its `value` field.
  */
 export declare function renderCell(cell: ICell, options?: AppendDependencyOptions): Promise<string>;
 //# sourceMappingURL=renderCell.d.ts.map

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

@@ -1,4 +1,4 @@
-import { IMovable } from '@sheetxl/sdk';
+import { IMovable, IShape } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /** A shape with something written on it, the text already read. */
 export interface ShapeTextEntry {
@@ -90,4 +90,15 @@ export declare function appendMovables(md: MarkdownBuilder, movables: readonly I
  * fact rather than the title.
  */
 export declare function renderMovable(movable: IMovable): string;
+/**
+ * Renders one shape's report: its placement, as {@link renderMovable} reports it, and everything
+ * the shape model states — geometry and adjust values, text and its layout, fill and line, line
+ * ends, links, locks, what a connector is glued to, and a group's members.
+ *
+ * @remarks
+ * The same report the shape's movable gives, titled for the object that was asked about: a shape
+ * is reached as `movable.getContent()`, and the reader should not have to step back to its movable
+ * to learn where it is.
+ */
+export declare function renderShape(shape: IShape): string;
 //# sourceMappingURL=renderMovable.d.ts.map