@toclocoinc/lattice-grid 1.20.0 → 1.21.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.21.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>

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.21.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.21.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -2679,6 +2679,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;
 }
 
 // ---------------------------------------------------------------------------