@toclocoinc/lattice-grid 1.20.0 → 1.22.0

package/README.md

@@ -4,7 +4,7 @@
 dependencies, no build step required. Optional adapters for React, Vue, Svelte
 and Web Components ship alongside it.
 
-Version 1.20.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.22.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/docs/API.html

@@ -4811,6 +4811,7 @@ grid.destroy();
         <tbody>
           <tr><td class="name">headers</td><td class="type">boolean</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">rows</td><td class="type">'visible' | 'all' | 'selected' | 'range'</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">sanitise</td><td class="type">boolean</td><td class="desc">Apply the CSV/Excel formula-injection guard to copied cells: prefix a field beginning with `=`, `+`, `-`, `@`, a tab or a CR with an apostrophe so a spreadsheet treats it as text. **Off by default** (unlike CSV/Excel export, which default it on), because the clipboard most often round-trips back into a grid or cell range where the apostrophe would corrupt the value. Turn it on when your users paste the clipboard into Excel or Google Sheets. <small>(optional)</small></td></tr>
         </tbody>
       </table>
     </div>
@@ -5288,6 +5289,36 @@ grid.destroy();
         </tbody>
       </table>
     </div>
+    <h3 id="type-DatasetColumnDifference">DatasetColumnDifference</h3>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">column</td><td class="type">string</td><td class="desc">The column id, present on both grids.</td></tr>
+          <tr><td class="name">name</td><td class="type">string</td><td class="desc">The column's display name, or its id.</td></tr>
+          <tr><td class="name">measure</td><td class="type">'pooledStandardMeanDifference' | 'categoricalTotalVariation'</td><td class="desc">The effect size reported for this column's family: the pooled standardised mean difference (Cohen's d) for a numeric column, the total variation of the category mix for a categorical one. Never a p-value.</td></tr>
+          <tr><td class="name">magnitude</td><td class="type">number | null</td><td class="desc">The effect size in its own terms, or null when it has no scale here.</td></tr>
+          <tr><td class="name">distance</td><td class="type">number</td><td class="desc">The total variation distance between the two datasets, 0 to 1 — the common scale both families reduce to, and what the ranking sorts by.</td></tr>
+          <tr><td class="name">direction</td><td class="type">number</td><td class="desc">+1 when dataset A sits above dataset B, −1 below, 0 for a mix.</td></tr>
+          <tr><td class="name">nA</td><td class="type">number</td><td class="desc">How many rows the first grid's side stood on.</td></tr>
+          <tr><td class="name">nB</td><td class="type">number</td><td class="desc">How many rows the second grid's side stood on.</td></tr>
+          <tr><td class="name">reliable</td><td class="type">boolean</td><td class="desc">False when either side is too small to read the difference from.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <h3 id="type-DatasetComparison">DatasetComparison</h3>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="name">ranked</td><td class="type">DatasetColumnDifference[]</td><td class="desc">Every shared column, largest difference first.</td></tr>
+          <tr><td class="name">nA</td><td class="type">number</td><td class="desc">How many rows the first grid contributed (its filtered set).</td></tr>
+          <tr><td class="name">nB</td><td class="type">number</td><td class="desc">How many rows the second grid contributed (its filtered set).</td></tr>
+          <tr><td class="name">unmatched</td><td class="type">{ onlyA: string[]; onlyB: string[] }</td><td class="desc">Columns present on only one side, which cannot be compared.</td></tr>
+          <tr><td class="name">measures</td><td class="type">{ numeric: string; categorical: string; common: string }</td><td class="desc">The measure each family reports, and the common scale, named for a legend.</td></tr>
+        </tbody>
+      </table>
+    </div>
     <h3 id="type-DataType">DataType</h3>
     <div class="table-wrap">
       <table>
@@ -7047,13 +7078,14 @@ grid.destroy();
       <table>
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
         <tbody>
-          <tr><td class="name">shadow</td><td class="type">(colId: string, kind: ShadowKind, rowKey: string, scope?: 'all' | 'filtered'): unknown</td><td class="desc">One shadow value for one row, by the column it shadows and the kind.</td></tr>
+          <tr><td class="name">shadow</td><td class="type">(colId: string, kind: ShadowKind, rowKey: string,</td><td class="desc">One shadow value for one row, by the column it shadows and the kind. For `kind: 'specStatus'`, `spec` carries the `{lower, upper, warnLower, warnUpper}` limits to judge the row's value against; other kinds ignore it.</td></tr>
           <tr><td class="name">running</td><td class="type">(colId: string, kind: 'total' | 'percent', rowKey: string): number | null</td><td class="desc">A running total at one row, down the grid as it is currently ordered.</td></tr>
           <tr><td class="name">rebase</td><td class="type">(colId?: string): void</td><td class="desc">Make the current values the new baseline: "mark all".</td></tr>
           <tr><td class="name">tracking</td><td class="type">(): { columns: string[]; rows: number; forgotten: number }</td><td class="desc">What the shadow histories are costing.</td></tr>
           <tr><td class="name">reduce</td><td class="type">(colId: string, fn: string): unknown</td><td class="desc">Reduce a column by a named kernel over the filtered rows.</td></tr>
           <tr><td class="name">profile</td><td class="type">(colId: string): ColumnProfile | null</td><td class="desc">Everything worth knowing about one column, in one pass each.</td></tr>
           <tr><td class="name">subsetVsPopulation</td><td class="type">(opts?: { columns?: string[] }): SubsetComparison</td><td class="desc">Which columns differ most between the filtered subset and the whole population it was drawn from, ranked by effect size — never by a p-value. The measure is stated per column; a numeric and a categorical column are put on one bounded scale so they rank against each other.</td></tr>
+          <tr><td class="name">datasetVsDataset</td><td class="type">(other: Grid, opts?: { columns?: string[] }): DatasetComparison</td><td class="desc">Which columns differ most between this grid and another, ranked by effect size — never by a p-value (BACKLOG-0000735). The generalisation of {@link subsetVsPopulation} from subset-vs-population to dataset-vs-dataset: two independent grids, yoked by passing one in, no shared store. A numeric column reports a pooled standardised mean difference (Cohen's d, symmetric in the two peers where Glass's delta is not); a categorical column the total variation of its category mix; both land on one bounded scale. Both sides are read over their filtered rows. Only shared columns are ranked; a column on one side alone is returned under `unmatched`.</td></tr>
           <tr><td class="name">correlation</td><td class="type">(a: string, b: string): number | null</td><td class="desc">Pearson's correlation between two columns.</td></tr>
           <tr><td class="name">covariance</td><td class="type">(a: string, b: string, opts?: { population?: boolean }): number | null</td><td class="desc">Covariance, a correlation before the scales are divided out.</td></tr>
           <tr><td class="name">regression</td><td class="type">(a: string, b: string): RegressionFit | null</td><td class="desc">Least-squares fit of `b` on `a`: in finance, beta and alpha.</td></tr>

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.20.0</p>
+    <p class="rail__sub">Developer guide · v1.22.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -4864,6 +4864,29 @@ grid.export.clipboard({ rows: 'range' });         <span class="cmt">// copy the
 grid.export.clipboard({ headers: true, rows: 'selected' });
 
 grid.edit.pasteInto(text);                        <span class="cmt">// Excel's tiling rules</span></code></pre>
+    </div>
+    <h3 id="clipboard-formula-guard">Guarding against formula injection on paste</h3>
+    <p class="lead-in">
+      By default a copied range round-trips verbatim, so a value beginning <code>=</code>,
+      <code>+</code>, <code>-</code> or <code>@</code> is carried unchanged &mdash; the right thing
+      when the paste target is another grid or cell range. When the paste target is a spreadsheet,
+      pass <code>sanitise: true</code> and a leading formula character is neutralised with an
+      apostrophe, so the value cannot be executed as a formula in Excel or Sheets.
+    </p>
+    <div class="example">
+      <p class="example__label">Opt in per copy</p>
+      <pre data-run="js" data-expect="default:=1+1 guarded:'=1+1" data-covers="config:sanitise"><code><span class="kw">const</span> { buildClipboardText } = <span class="kw">await</span> import('../packages/core/src/export/index.js');
+
+<span class="cmt">// An explicit cell matrix; the formula guard applies to data fields.</span>
+<span class="kw">const</span> cells = [['=1+1']];
+
+<span class="cmt">// Off by default: the value round-trips exactly as copied.</span>
+<span class="kw">const</span> plain = buildClipboardText({}, { rows: 'range', cells });
+
+<span class="cmt">// sanitise:true prefixes an apostrophe so a spreadsheet stores it as text.</span>
+<span class="kw">const</span> guarded = buildClipboardText({}, { rows: 'range', cells, sanitise: <span class="kw">true</span> });
+
+<span class="kw">return</span> `default:${plain} guarded:${guarded}`;</code></pre>
     </div>
     <div class="why">
       <p>Pasting follows the spreadsheet convention: one cell into a range fills the range, one row

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.20.0, type declarations
+ * Lattice Grid 1.22.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -639,6 +639,17 @@ export interface Column {
      * `'filtered'` ranks within what the filters left.
      */
     scope?: 'all' | 'filtered';
+    /**
+     * For `kind: 'specStatus'`, the hard specification the row is judged
+     * against. `lower`/`upper` are the pass limits (a value beyond either
+     * fails); the optional `warnLower`/`warnUpper` are inner thresholds that
+     * mark a still-in-spec reading `'WARN'`. Centred-target ± tolerance is a
+     * deliberate follow-up and is not read here.
+     */
+    lower?: number;
+    upper?: number;
+    warnLower?: number;
+    warnUpper?: number;
   };
   /**
    * A running total down the grid **as it is currently ordered**.
@@ -2210,8 +2221,13 @@ export interface PushdownSourceConfig {
 }
 
 export interface StatisticsApi {
-  /** One shadow value for one row, by the column it shadows and the kind. */
-  shadow(colId: string, kind: ShadowKind, rowKey: string, scope?: 'all' | 'filtered'): unknown;
+  /**
+   * One shadow value for one row, by the column it shadows and the kind. For
+   * `kind: 'specStatus'`, `spec` carries the `{lower, upper, warnLower,
+   * warnUpper}` limits to judge the row's value against; other kinds ignore it.
+   */
+  shadow(colId: string, kind: ShadowKind, rowKey: string,
+    scope?: 'all' | 'filtered', spec?: object): unknown;
   /** A running total at one row, down the grid as it is currently ordered. */
   running(colId: string, kind: 'total' | 'percent', rowKey: string): number | null;
   /** Make the current values the new baseline: "mark all". */
@@ -2229,6 +2245,18 @@ export interface StatisticsApi {
    * on one bounded scale so they rank against each other.
    */
   subsetVsPopulation(opts?: { columns?: string[] }): SubsetComparison;
+  /**
+   * Which columns differ most between this grid and another, ranked by effect
+   * size — never by a p-value (BACKLOG-0000735). The generalisation of
+   * {@link subsetVsPopulation} from subset-vs-population to dataset-vs-dataset:
+   * two independent grids, yoked by passing one in, no shared store. A numeric
+   * column reports a pooled standardised mean difference (Cohen's d, symmetric
+   * in the two peers where Glass's delta is not); a categorical column the total
+   * variation of its category mix; both land on one bounded scale. Both sides
+   * are read over their filtered rows. Only shared columns are ranked; a column
+   * on one side alone is returned under `unmatched`.
+   */
+  datasetVsDataset(other: Grid, opts?: { columns?: string[] }): DatasetComparison;
   /** Pearson's correlation between two columns. */
   correlation(a: string, b: string): number | null;
   /** Covariance, a correlation before the scales are divided out. */
@@ -2336,7 +2364,18 @@ export type ShadowKind =
   | 'rate' | 'history' | 'firstValue' | 'streak'
   /** Where the row sits among the others, over every tracked row. */
   | 'rank' | 'rankAsc' | 'rankChange' | 'percentile' | 'quartile'
-  | 'zScore' | 'shareOfTotal';
+  | 'zScore' | 'shareOfTotal'
+  /**
+   * The row's pass/fail verdict against a hard-limit spec, as a value:
+   * `'PASS'`, `'WARN'` or `'FAIL'`. Sortable, filterable, groupable and
+   * exportable, and rolled up by the `passRate`/`failureCount` totals. Reads
+   * `{lower, upper}` (and optional inner `{warnLower, warnUpper}`) off the
+   * shadow declaration; centred-target ± tolerance is a deliberate follow-up.
+   */
+  | 'specStatus';
+
+/** The three verdicts a `specStatus` shadow can report. */
+export type SpecStatus = 'PASS' | 'WARN' | 'FAIL';
 
 export interface RegressionFit {
   slope: number;
@@ -2474,6 +2513,47 @@ export interface SubsetComparison {
   measures: { numeric: string; categorical: string; common: string };
 }
 
+export interface DatasetColumnDifference {
+  /** The column id, present on both grids. */
+  column: string;
+  /** The column's display name, or its id. */
+  name: string;
+  /**
+   * The effect size reported for this column's family: the pooled standardised
+   * mean difference (Cohen's d) for a numeric column, the total variation of the
+   * category mix for a categorical one. Never a p-value.
+   */
+  measure: 'pooledStandardMeanDifference' | 'categoricalTotalVariation';
+  /** The effect size in its own terms, or null when it has no scale here. */
+  magnitude: number | null;
+  /**
+   * The total variation distance between the two datasets, 0 to 1 — the common
+   * scale both families reduce to, and what the ranking sorts by.
+   */
+  distance: number;
+  /** +1 when dataset A sits above dataset B, −1 below, 0 for a mix. */
+  direction: number;
+  /** How many rows the first grid's side stood on. */
+  nA: number;
+  /** How many rows the second grid's side stood on. */
+  nB: number;
+  /** False when either side is too small to read the difference from. */
+  reliable: boolean;
+}
+
+export interface DatasetComparison {
+  /** Every shared column, largest difference first. */
+  ranked: DatasetColumnDifference[];
+  /** How many rows the first grid contributed (its filtered set). */
+  nA: number;
+  /** How many rows the second grid contributed (its filtered set). */
+  nB: number;
+  /** Columns present on only one side, which cannot be compared. */
+  unmatched: { onlyA: string[]; onlyB: string[] };
+  /** The measure each family reports, and the common scale, named for a legend. */
+  measures: { numeric: string; categorical: string; common: string };
+}
+
 export interface FormattingApi {
   list(scope?: FormattingScope): FormattingRule[];
   all(): Record<FormattingScope, FormattingRule[]>;
@@ -2679,6 +2759,15 @@ export interface ExcelExportOptions extends Omit<CsvExportOptions, 'delimiter' |
 export interface ClipboardOptions {
   headers?: boolean;
   rows?: 'visible' | 'all' | 'selected' | 'range';
+  /**
+   * Apply the CSV/Excel formula-injection guard to copied cells: prefix a field
+   * beginning with `=`, `+`, `-`, `@`, a tab or a CR with an apostrophe so a
+   * spreadsheet treats it as text. **Off by default** (unlike CSV/Excel export,
+   * which default it on), because the clipboard most often round-trips back into
+   * a grid or cell range where the apostrophe would corrupt the value. Turn it
+   * on when your users paste the clipboard into Excel or Google Sheets.
+   */
+  sanitise?: boolean;
 }
 
 // ---------------------------------------------------------------------------