apex-grid 3.1.0 → 3.3.0

package/docs/index.html

@@ -5,22 +5,29 @@
 <p>A Lit-based, framework-agnostic web component data grid. Ships as a single custom element <code>&lt;apex-grid&gt;</code> with a rich, opt-in feature set and full TypeScript types.</p>
 <h2 id="features" class="tsd-anchor-link">Features<a href="#features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <ul>
-<li><strong>Row virtualization</strong> via <code>@lit-labs/virtualizer</code> — only ~20 rows in the DOM at any time, regardless of dataset size.</li>
-<li><strong>Sorting</strong> — single or multi-column, tri-state (asc / desc / none), per-column comparers.</li>
-<li><strong>Filtering</strong> — per-column filter chips with string / number / boolean / date operands, plus a quick-filter (global search) input.</li>
-<li><strong>Pagination</strong> — local slicing or remote mode with a <code>pageChanging</code> / <code>pageChanged</code> event pair; built-in <code>&lt;apex-grid-paginator&gt;</code>.</li>
-<li><strong>Column pinning</strong> — pin to start or end; visual reordering only, source <code>columns</code> array is preserved.</li>
-<li><strong>Column reordering</strong> — drag-and-drop with per-column opt-out, constrained to the column's pinning group.</li>
-<li><strong>Column resizing</strong> — pointer-driven, with a min-width safeguard.</li>
-<li><strong>Inline editing</strong> — cell or row mode, click or double-click trigger, per-column opt-in.</li>
-<li><strong>Row selection</strong> — single or multiple, optional checkbox column, full programmatic API.</li>
-<li><strong>Row expansion (master-detail)</strong> — opt-in chevron column with a <code>detailTemplate</code>.</li>
-<li><strong>Tree data (nested rows)</strong> — AG Grid–style <code>getDataPath</code> pattern over a flat array.</li>
-<li><strong>CSV export</strong> — programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in <code>apex-grid-enterprise</code>.)</li>
-<li><strong>Toolbar</strong> — opt-in <code>&lt;apex-grid-toolbar&gt;</code> with debounced quick filter and export menu.</li>
-<li><strong>Templating</strong> — slot-based templates for cells, headers, editors, and detail panels.</li>
-<li><strong>Theming</strong> — styled out-of-the-box; fully customizable through <code>--ag-*</code> CSS custom properties (no theme import or build step). Auto-matches an <code>igniteui-webcomponents</code> host app when one is present.</li>
-<li><strong>Accessibility</strong> — WCAG 2.2 AA semantics (<code>role=&quot;grid&quot;</code> / <code>role=&quot;treegrid&quot;</code>, <code>aria-rowcount</code>, <code>aria-colcount</code>, focus + keyboard navigation).</li>
+<li><strong>Row virtualization</strong> via <code>@lit-labs/virtualizer</code>: only ~20 rows in the DOM at any time, regardless of dataset size.</li>
+<li><strong>Sorting</strong>: single or multi-column, tri-state (asc / desc / none), per-column comparers.</li>
+<li><strong>Filtering</strong>: per-column filter chips with string / number / boolean / date operands, plus a quick-filter (global search) input.</li>
+<li><strong>Pagination</strong>: local slicing or remote mode with a <code>pageChanging</code> / <code>pageChanged</code> event pair; built-in <code>&lt;apex-grid-paginator&gt;</code>.</li>
+<li><strong>Column pinning</strong>: pin to start or end; visual reordering only, source <code>columns</code> array is preserved.</li>
+<li><strong>Column reordering</strong>: drag-and-drop with per-column opt-out, constrained to the column's pinning group.</li>
+<li><strong>Column resizing</strong>: pointer-driven, with a min-width safeguard.</li>
+<li><strong>Column groups</strong>: spanning multi-level headers over a flat <code>columns</code> array, respecting pin regions.</li>
+<li><strong>Inline editing</strong>: cell or row mode, click or double-click trigger, per-column opt-in.</li>
+<li><strong>Cell validation</strong>: declarative per-column <code>validators</code> (built-ins plus custom), surfaced with <code>aria-invalid</code> and an event.</li>
+<li><strong>Undo / redo</strong>: opt-in history for cell edits, with keyboard shortcuts (Ctrl/Cmd+Z, etc.).</li>
+<li><strong>Row selection</strong>: single or multiple, optional checkbox column, full programmatic API.</li>
+<li><strong>Row pinning</strong>: sticky top / bottom bands rendered outside the virtualizer.</li>
+<li><strong>Row drag-reorder</strong>: pointer and keyboard reordering with a manual order, mutually exclusive with sorting.</li>
+<li><strong>Row expansion (master-detail)</strong>: opt-in chevron column with a <code>detailTemplate</code>.</li>
+<li><strong>Tree data (nested rows)</strong>: <code>getDataPath</code> pattern over a flat array.</li>
+<li><strong>State &amp; persistence</strong>: <code>getState()</code> / <code>setState()</code> snapshot round-trip, a <code>stateChanged</code> event, and a <code>getSchema()</code> capability descriptor.</li>
+<li><strong>Localization (i18n)</strong>: override any built-in string via <code>localeText</code>; bundled dictionaries (e.g. <code>esLocale</code>).</li>
+<li><strong>CSV export</strong>: programmatic method plus an optional toolbar dropdown. (Excel/XLSX export is in <code>apex-grid-enterprise</code>.)</li>
+<li><strong>Toolbar</strong>: opt-in <code>&lt;apex-grid-toolbar&gt;</code> with debounced quick filter and export menu.</li>
+<li><strong>Templating</strong>: slot-based templates for cells, headers, editors, and detail panels.</li>
+<li><strong>Theming</strong>: styled out-of-the-box; fully customizable through <code>--ag-*</code> CSS custom properties (no theme import or build step). Auto-matches an <code>igniteui-webcomponents</code> host app when one is present.</li>
+<li><strong>Accessibility</strong>: WCAG 2.2 AA semantics (<code>role=&quot;grid&quot;</code> / <code>role=&quot;treegrid&quot;</code>, <code>aria-rowcount</code>, <code>aria-colcount</code>, focus + keyboard navigation).</li>
 <li><strong>Provenance-signed npm releases</strong> with OIDC trusted publishing.</li>
 </ul>
 <hr>
@@ -29,7 +36,7 @@
 <pre><code class="ts"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">setup</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&#39;apex-grid&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-4">setup</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
 
-<p>That single call registers <code>&lt;apex-grid&gt;</code> and adopts a default host stylesheet (<code>height: 100%; min-height: 240px</code>). The grid is styled out-of-the-box — no theme CSS import is required.</p>
+<p>That single call registers <code>&lt;apex-grid&gt;</code> and adopts a default host stylesheet (<code>height: 100%; min-height: 240px</code>). The grid is styled out-of-the-box; no theme CSS import is required.</p>
 <h3 id="render-the-grid" class="tsd-anchor-link">Render the grid<a href="#render-the-grid" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">html</span><span class="hl-1">, </span><span class="hl-2">render</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&#39;lit&#39;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> </span><span class="hl-3">&#39;apex-grid/define&#39;</span><span class="hl-1">;</span><br/><span class="hl-0">import</span><span class="hl-1"> </span><span class="hl-0">type</span><span class="hl-1"> { </span><span class="hl-2">ColumnConfiguration</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&#39;apex-grid&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">type</span><span class="hl-1"> </span><span class="hl-6">User</span><span class="hl-1"> = { </span><span class="hl-2">id</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">; </span><span class="hl-2">name</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">; </span><span class="hl-2">age</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">; </span><span class="hl-2">subscribed</span><span class="hl-1">: </span><span class="hl-6">boolean</span><span class="hl-1"> };</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">data</span><span class="hl-1">: </span><span class="hl-6">User</span><span class="hl-1">[] = [</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">1</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Ada Lovelace&#39;</span><span class="hl-1">, </span><span class="hl-2">age:</span><span class="hl-1"> </span><span class="hl-8">36</span><span class="hl-1">, </span><span class="hl-2">subscribed:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">2</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Carl Sagan&#39;</span><span class="hl-1">,   </span><span class="hl-2">age:</span><span class="hl-1"> </span><span class="hl-8">62</span><span class="hl-1">, </span><span class="hl-2">subscribed:</span><span class="hl-1"> </span><span class="hl-5">false</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">3</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Grace Hopper&#39;</span><span class="hl-1">, </span><span class="hl-2">age:</span><span class="hl-1"> </span><span class="hl-8">85</span><span class="hl-1">, </span><span class="hl-2">subscribed:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">columns</span><span class="hl-1">: </span><span class="hl-6">ColumnConfiguration</span><span class="hl-1">&lt;</span><span class="hl-6">User</span><span class="hl-1">&gt;[] = [</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;id&#39;</span><span class="hl-1">,         </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&#39;number&#39;</span><span class="hl-1">,  </span><span class="hl-2">headerText:</span><span class="hl-1"> </span><span class="hl-3">&#39;ID&#39;</span><span class="hl-1">,         </span><span class="hl-2">width:</span><span class="hl-1"> </span><span class="hl-3">&#39;80px&#39;</span><span class="hl-1">,  </span><span class="hl-2">sort:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">filter:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">,       </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&#39;string&#39;</span><span class="hl-1">,  </span><span class="hl-2">headerText:</span><span class="hl-1"> </span><span class="hl-3">&#39;Name&#39;</span><span class="hl-1">,       </span><span class="hl-2">width:</span><span class="hl-1"> </span><span class="hl-3">&#39;240px&#39;</span><span class="hl-1">, </span><span class="hl-2">sort:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">filter:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;age&#39;</span><span class="hl-1">,        </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&#39;number&#39;</span><span class="hl-1">,  </span><span class="hl-2">headerText:</span><span class="hl-1"> </span><span class="hl-3">&#39;Age&#39;</span><span class="hl-1">,        </span><span class="hl-2">width:</span><span class="hl-1"> </span><span class="hl-3">&#39;100px&#39;</span><span class="hl-1">, </span><span class="hl-2">sort:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">filter:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;subscribed&#39;</span><span class="hl-1">, </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&#39;boolean&#39;</span><span class="hl-1">, </span><span class="hl-2">headerText:</span><span class="hl-1"> </span><span class="hl-3">&#39;Subscribed&#39;</span><span class="hl-1">, </span><span class="hl-2">width:</span><span class="hl-1"> </span><span class="hl-3">&#39;140px&#39;</span><span class="hl-1">, </span><span class="hl-2">sort:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">filter:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-4">render</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-4">html</span><span class="hl-3">`&lt;apex-grid .data=</span><span class="hl-5">${</span><span class="hl-2">data</span><span class="hl-5">}</span><span class="hl-3"> .columns=</span><span class="hl-5">${</span><span class="hl-2">columns</span><span class="hl-5">}</span><span class="hl-3">&gt;&lt;/apex-grid&gt;`</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">document</span><span class="hl-1">.</span><span class="hl-4">getElementById</span><span class="hl-1">(</span><span class="hl-3">&#39;app&#39;</span><span class="hl-1">)!,</span><br/><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
@@ -44,7 +51,7 @@
 <pre><code class="bash"><span class="hl-4">npm</span><span class="hl-1"> </span><span class="hl-3">install</span><span class="hl-1"> </span><span class="hl-3">apex-grid</span><span class="hl-1"> </span><span class="hl-3">lit</span>
 </code><button type="button">Copy</button></pre>
 
-<p><code>igniteui-webcomponents</code> ships as a transitive dependency — no separate install.</p>
+<p><code>igniteui-webcomponents</code> ships as a transitive dependency; no separate install.</p>
 <h3 id="2-register-the-custom-element" class="tsd-anchor-link">2. Register the custom element<a href="#2-register-the-custom-element" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-0">import</span><span class="hl-1"> </span><span class="hl-3">&#39;apex-grid/define&#39;</span><span class="hl-1">;</span>
 </code><button type="button">Copy</button></pre>
@@ -55,16 +62,16 @@
 
 <p>Without this, <code>&lt;apex-grid&gt;</code> is an inert unknown element.</p>
 <h3 id="3-optional-customize-the-look" class="tsd-anchor-link">3. (Optional) Customize the look<a href="#3-optional-customize-the-look" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>The grid is styled out-of-the-box — there is no theme to import. Customize it by overriding the <code>--ag-*</code> CSS custom properties on <code>apex-grid</code> (or any ancestor); a one-line brand override cascades to every tint:</p>
+<p>The grid is styled out-of-the-box; there is no theme to import. Customize it by overriding the <code>--ag-*</code> CSS custom properties on <code>apex-grid</code> (or any ancestor); a one-line brand override cascades to every tint:</p>
 <pre><code class="css"><span class="hl-10">apex-grid</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-12">--ag-brand</span><span class="hl-1">: </span><span class="hl-14">#7c3aed</span><span class="hl-1">;        </span><span class="hl-15">/* selection, focus, accents */</span><br/><span class="hl-1">  </span><span class="hl-12">--ag-brand-strong</span><span class="hl-1">: </span><span class="hl-14">#6d28d9</span><span class="hl-1">; </span><span class="hl-15">/* hover / pressed */</span><br/><span class="hl-1">  </span><span class="hl-12">--ag-radius</span><span class="hl-1">: </span><span class="hl-8">12px</span><span class="hl-1">;          </span><span class="hl-15">/* outer card radius */</span><br/><span class="hl-1">  </span><span class="hl-12">--ag-row-h</span><span class="hl-1">: </span><span class="hl-8">40px</span><span class="hl-1">;           </span><span class="hl-15">/* row height */</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <p>See <a href="media/_tokens.scss"><code>src/styles/_tokens.scss</code></a> for the full token list (brand, surfaces, text, semantic state colors, typography, spacing, motion).</p>
-<p><strong>Grid edge / shadow.</strong> By default the grid shows a flat 1px hairline edge (no drop shadow). Control it with the <code>--ag-grid-shadow</code> hook — this is an opt-in override, not one of the <code>_tokens.scss</code> defaults:</p>
+<p><strong>Grid edge / shadow.</strong> By default the grid shows a flat 1px hairline edge (no drop shadow). Control it with the <code>--ag-grid-shadow</code> hook, an opt-in override that is not one of the <code>_tokens.scss</code> defaults:</p>
 <pre><code class="css"><span class="hl-10">apex-grid</span><span class="hl-1"> { </span><span class="hl-12">--ag-grid-shadow</span><span class="hl-1">: </span><span class="hl-4">var</span><span class="hl-1">(</span><span class="hl-12">--ag-shadow-card</span><span class="hl-1">); } </span><span class="hl-15">/* elevated floating-card look */</span><br/><span class="hl-10">apex-grid</span><span class="hl-1"> { </span><span class="hl-12">--ag-grid-shadow</span><span class="hl-1">: </span><span class="hl-14">none</span><span class="hl-1">; }                  </span><span class="hl-15">/* remove the edge entirely */</span>
 </code><button type="button">Copy</button></pre>
 
-<p>If you embed the grid alongside <code>igniteui-webcomponents</code>, the brand tokens automatically re-tint from the igniteui palette (<code>--ig-primary-500</code>) — no configuration needed.</p>
+<p>If you embed the grid alongside <code>igniteui-webcomponents</code>, the brand tokens automatically re-tint from the igniteui palette (<code>--ig-primary-500</code>); no configuration needed.</p>
 <h3 id="4-size-the-host" class="tsd-anchor-link">4. Size the host<a href="#4-size-the-host" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p><code>@lit-labs/virtualizer</code> requires a <strong>bounded height</strong>. Without one, the virtualizer collapses to its natural content height (~150px) and only a few rows ever render.</p>
 <pre><code class="css"><span class="hl-10">apex-grid</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-12">height</span><span class="hl-1">: </span><span class="hl-8">480px</span><span class="hl-1">;   </span><span class="hl-15">/* any explicit pixel height; % works if the parent has a height */</span><br/><span class="hl-1">}</span>
@@ -83,7 +90,7 @@
 <li><strong>Sort arrows</strong> (↕) next to each header when <code>sort: true</code>.</li>
 <li>A <strong>filter row</strong> below the headers with a &quot;Filter&quot; chip per column when <code>filter: true</code>.</li>
 <li><strong>Hover state</strong> on rows.</li>
-<li><strong>Smooth scrolling</strong> — DevTools shows only ~20 <code>&lt;apex-grid-row&gt;</code> elements at any time.</li>
+<li><strong>Smooth scrolling</strong>: DevTools shows only ~20 <code>&lt;apex-grid-row&gt;</code> elements at any time.</li>
 </ul>
 <h3 id="troubleshooting" class="tsd-anchor-link">Troubleshooting<a href="#troubleshooting" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <table>
@@ -96,35 +103,37 @@
 <tbody>
 <tr>
 <td>Want a different look / brand color</td>
-<td>Step 3 — override the <code>--ag-*</code> CSS variables</td>
+<td>Step 3: override the <code>--ag-*</code> CSS variables</td>
 </tr>
 <tr>
 <td>Only ~3 rows visible regardless of data size</td>
-<td>Step 4 — no bounded height, <strong>or</strong> consumer CSS sets <code>display</code> on <code>&lt;apex-grid&gt;</code> (check console for the warning)</td>
+<td>Step 4: no bounded height, <strong>or</strong> consumer CSS sets <code>display</code> on <code>&lt;apex-grid&gt;</code> (check console for the warning)</td>
 </tr>
 <tr>
 <td><code>&lt;apex-grid&gt;</code> blank tag in DOM</td>
-<td>Step 2 — element not registered</td>
+<td>Step 2: element not registered</td>
 </tr>
 <tr>
 <td>Columns shown as literal <code>[object Object]</code></td>
-<td><code>columns=</code> used as an attribute — must be a <strong>property</strong> (<code>.columns=${...}</code> in Lit, <code>[columns]=</code> in Angular, <code>:columns.prop=</code> in Vue, <code>el.columns = ...</code> in vanilla JS)</td>
+<td><code>columns=</code> used as an attribute; must be a <strong>property</strong> (<code>.columns=${...}</code> in Lit, <code>[columns]=</code> in Angular, <code>:columns.prop=</code> in Vue, <code>el.columns = ...</code> in vanilla JS)</td>
 </tr>
 </tbody>
 </table>
 <hr>
 <h2 id="features-in-depth" class="tsd-anchor-link">Features in depth<a href="#features-in-depth" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
-<p>Each feature below is fully opt-in — you only pay for what you turn on. Snippets assume <code>const grid = document.querySelector('apex-grid')!</code>.</p>
+<p>Each feature below is fully opt-in: you only pay for what you turn on. Snippets assume <code>const grid = document.querySelector('apex-grid')!</code>.</p>
 <h3 id="sorting" class="tsd-anchor-link">Sorting<a href="#sorting" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">columns</span><span class="hl-1"> = [</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">, </span><span class="hl-2">sort:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },                            </span><span class="hl-15">// UI sort + tri-state</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;age&#39;</span><span class="hl-1">,  </span><span class="hl-2">sort:</span><span class="hl-1"> { </span><span class="hl-2">direction:</span><span class="hl-1"> </span><span class="hl-3">&#39;desc&#39;</span><span class="hl-1"> } },           </span><span class="hl-15">// initial state</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">sortConfiguration</span><span class="hl-1"> = { </span><span class="hl-2">multiple:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">triState:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> };</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">sort</span><span class="hl-1">({ </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;age&#39;</span><span class="hl-1">, </span><span class="hl-2">direction:</span><span class="hl-1"> </span><span class="hl-3">&#39;asc&#39;</span><span class="hl-1"> });</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">clearSort</span><span class="hl-1">();                                          </span><span class="hl-15">// or grid.clearSort(&#39;age&#39;)</span>
 </code><button type="button">Copy</button></pre>
 
-<p>Events: <code>sorting</code> (cancellable), <code>sorted</code>.</p>
+<p>When <code>multiple</code> is enabled, a plain header click sorts by that column alone; hold Ctrl/Cmd and click to append additional columns as lower-priority sort keys. Events: <code>sorting</code> (cancellable), <code>sorted</code>.</p>
+<p>Columns show a column menu (the three-dot / kebab button) in the header. Out of the box it offers <strong>Sort Ascending</strong>, <strong>Sort Descending</strong>, and <strong>Autosize Column</strong> (on sortable or resizable columns). A feature module can supply the menu instead through the <code>ColumnMenuProvider</code> seam: <code>apex-grid-enterprise</code> fills it with pin, hide, group, and chart actions on every column, shared with the right-click context menu. The button is always visible; set <code>columnMenu</code> to <code>false</code> to hide it entirely (a module's menu stays reachable by right-click).</p>
 <h3 id="filtering" class="tsd-anchor-link">Filtering<a href="#filtering" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">columns</span><span class="hl-1"> = [</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">, </span><span class="hl-2">filter:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },                          </span><span class="hl-15">// UI filter chip</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;age&#39;</span><span class="hl-1">,  </span><span class="hl-2">filter:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&#39;number&#39;</span><span class="hl-1"> },          </span><span class="hl-15">// operands by type</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">StringOperands</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&#39;apex-grid&#39;</span><span class="hl-1">;</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">filter</span><span class="hl-1">({ </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">, </span><span class="hl-2">condition:</span><span class="hl-1"> </span><span class="hl-2">StringOperands</span><span class="hl-1">.</span><span class="hl-2">contains</span><span class="hl-1">, </span><span class="hl-2">searchTerm:</span><span class="hl-1"> </span><span class="hl-3">&#39;Ada&#39;</span><span class="hl-1"> });</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">clearFilter</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
 
 <p>Operand classes: <code>StringOperands</code>, <code>NumberOperands</code>, <code>BooleanOperands</code>. Events: <code>filtering</code> (cancellable), <code>filtered</code>.</p>
+<p>Filterable columns show a per-column filter button in the header that opens the filter panel; an active filter is highlighted (with a count badge when more than one condition is set).</p>
 <h3 id="quick-filter-global-search" class="tsd-anchor-link">Quick filter (global search)<a href="#quick-filter-global-search" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">showQuickFilter</span><span class="hl-1"> = </span><span class="hl-5">true</span><span class="hl-1">;       </span><span class="hl-15">// renders the toolbar input</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">quickFilter</span><span class="hl-1"> = </span><span class="hl-3">&#39;ada&#39;</span><span class="hl-1">;          </span><span class="hl-15">// or: await grid.setQuickFilter(&#39;ada&#39;)</span>
 </code><button type="button">Copy</button></pre>
@@ -143,7 +152,7 @@
 <pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">columns</span><span class="hl-1"> = [</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;id&#39;</span><span class="hl-1">,   </span><span class="hl-2">pinned:</span><span class="hl-1"> </span><span class="hl-3">&#39;start&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;actions&#39;</span><span class="hl-1">, </span><span class="hl-2">pinned:</span><span class="hl-1"> </span><span class="hl-3">&#39;end&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">pinColumn</span><span class="hl-1">(</span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">, </span><span class="hl-3">&#39;start&#39;</span><span class="hl-1">);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">unpinColumn</span><span class="hl-1">(</span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">);                 </span><span class="hl-15">// or pinColumn(&#39;name&#39;, null)</span>
 </code><button type="button">Copy</button></pre>
 
-<p>The source <code>columns</code> array is <strong>not</strong> reordered — only the visual render order changes. Read <code>grid.displayColumns</code> for the render order. Events: <code>columnPinning</code> (cancellable), <code>columnPinned</code>.</p>
+<p>The source <code>columns</code> array is <strong>not</strong> reordered; only the visual render order changes. Read <code>grid.displayColumns</code> for the render order. Events: <code>columnPinning</code> (cancellable), <code>columnPinned</code>.</p>
 <h3 id="column-reordering" class="tsd-anchor-link">Column reordering<a href="#column-reordering" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="html"><span class="hl-9">&lt;</span><span class="hl-10">apex-grid</span><span class="hl-1"> </span><span class="hl-12">column-reordering</span><span class="hl-9">&gt;&lt;/</span><span class="hl-10">apex-grid</span><span class="hl-9">&gt;</span>
 </code><button type="button">Copy</button></pre>
@@ -153,24 +162,55 @@
 </code><button type="button">Copy</button></pre>
 
 <p>Per-column opt-out: <code>{ key: 'id', reorderable: false }</code>. Reordering is constrained to the column's own pinning group (start / unpinned / end). Events: <code>columnMoving</code> (cancellable), <code>columnMoved</code>. Attribute: <code>column-reordering</code>.</p>
+<h3 id="column-separators" class="tsd-anchor-link">Column separators<a href="#column-separators" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p>A persistent vertical divider on each column header's trailing edge, on by default. On columns that opt into resizing (<code>{ key, resizable: true }</code>) the divider doubles as the resize handle: it takes the <code>col-resize</code> cursor and can be dragged.</p>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">columnSeparator</span><span class="hl-1"> = </span><span class="hl-5">false</span><span class="hl-1">;                     </span><span class="hl-15">// hide the dividers</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Theme the line with <code>--ag-header-separator</code> (or the <code>--header-separator-color</code> / <code>--igx-header-separator-color</code> override hooks) and set its vertical inset with <code>--apex-header-separator-inset</code>. Because the default is <code>true</code>, disable it through the property rather than markup (a default-on boolean attribute cannot be turned off by attribute alone). Attribute: <code>column-separator</code>.</p>
+<h3 id="column-groups-spanning-headers" class="tsd-anchor-link">Column groups (spanning headers)<a href="#column-groups-spanning-headers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">columns</span><span class="hl-1"> = [</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;first&#39;</span><span class="hl-1">, </span><span class="hl-2">group:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;last&#39;</span><span class="hl-1">,  </span><span class="hl-2">group:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;city&#39;</span><span class="hl-1">,  </span><span class="hl-2">group:</span><span class="hl-1"> </span><span class="hl-3">&#39;address&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;zip&#39;</span><span class="hl-1">,   </span><span class="hl-2">group:</span><span class="hl-1"> </span><span class="hl-3">&#39;address&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">];</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">columnGroups</span><span class="hl-1"> = [</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">,    </span><span class="hl-2">headerText:</span><span class="hl-1"> </span><span class="hl-3">&#39;Name&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-3">&#39;address&#39;</span><span class="hl-1">, </span><span class="hl-2">headerText:</span><span class="hl-1"> </span><span class="hl-3">&#39;Address&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">];</span>
+</code><button type="button">Copy</button></pre>
+
+<p>A spanning header row renders above the column headers. <code>columns</code> stays flat, so width / pinning / resize / reorder are unaffected; membership is by reference (<code>column.group</code> points at a <code>columnGroups</code> entry). A group's members must be contiguous within one pin region (non-contiguous groups warn and skip the spanning cell); ungrouped columns get a blank spacer. Member reordering is confined to its group.</p>
 <h3 id="inline-editing" class="tsd-anchor-link">Inline editing<a href="#inline-editing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">columns</span><span class="hl-1"> = [</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">, </span><span class="hl-2">editable:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;age&#39;</span><span class="hl-1">,  </span><span class="hl-2">editable:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&#39;number&#39;</span><span class="hl-1"> },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">editing</span><span class="hl-1"> = { </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">mode:</span><span class="hl-1"> </span><span class="hl-3">&#39;cell&#39;</span><span class="hl-1">, </span><span class="hl-2">trigger:</span><span class="hl-1"> </span><span class="hl-3">&#39;doubleClick&#39;</span><span class="hl-1"> };</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">editCell</span><span class="hl-1">(</span><span class="hl-8">0</span><span class="hl-1">, </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">commitEdit</span><span class="hl-1">();</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">cancelEdit</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
 
 <p><code>mode: 'row'</code> puts all editable cells in the row into edit together. Properties: <code>editingCell</code>, <code>editingRow</code>. Events: <code>cellValueChanging</code> (cancellable), <code>cellValueChanged</code>, plus <code>rowEditStarted</code> / <code>rowEditEnded</code> in row mode.</p>
+<h3 id="cell-validation" class="tsd-anchor-link">Cell validation<a href="#cell-validation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="ts"><span class="hl-0">import</span><span class="hl-1"> { </span><span class="hl-2">required</span><span class="hl-1">, </span><span class="hl-2">min</span><span class="hl-1">, </span><span class="hl-2">max</span><span class="hl-1">, </span><span class="hl-2">pattern</span><span class="hl-1">, </span><span class="hl-2">custom</span><span class="hl-1"> } </span><span class="hl-0">from</span><span class="hl-1"> </span><span class="hl-3">&#39;apex-grid&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">columns</span><span class="hl-1"> = [</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">,  </span><span class="hl-2">editable:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">validators:</span><span class="hl-1"> [</span><span class="hl-4">required</span><span class="hl-1">(</span><span class="hl-3">&#39;Name is required&#39;</span><span class="hl-1">)] },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;age&#39;</span><span class="hl-1">,   </span><span class="hl-2">editable:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">type:</span><span class="hl-1"> </span><span class="hl-3">&#39;number&#39;</span><span class="hl-1">, </span><span class="hl-2">validators:</span><span class="hl-1"> [</span><span class="hl-4">min</span><span class="hl-1">(</span><span class="hl-8">18</span><span class="hl-1">), </span><span class="hl-4">max</span><span class="hl-1">(</span><span class="hl-8">99</span><span class="hl-1">)] },</span><br/><span class="hl-1">  { </span><span class="hl-2">key:</span><span class="hl-1"> </span><span class="hl-3">&#39;email&#39;</span><span class="hl-1">, </span><span class="hl-2">editable:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">validators:</span><span class="hl-1"> [</span><span class="hl-4">pattern</span><span class="hl-1">(</span><span class="hl-16">/</span><span class="hl-17">^</span><span class="hl-18">[^</span><span class="hl-16">@\s</span><span class="hl-18">]</span><span class="hl-19">+</span><span class="hl-16">@</span><span class="hl-18">[^</span><span class="hl-16">@\s</span><span class="hl-18">]</span><span class="hl-19">+</span><span class="hl-17">$</span><span class="hl-16">/</span><span class="hl-1">, </span><span class="hl-3">&#39;Invalid email&#39;</span><span class="hl-1">)] },</span><br/><span class="hl-1">];</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Validators run inside the commit path, before the cancellable <code>cellValueChanging</code> gate. A failure keeps the editor open, marks the cell (<code>aria-invalid</code> + an error message node), and fires <code>cellValidationFailed { key, rowIndex, data, value, errors }</code>. Built-ins: <code>required</code>, <code>min</code>, <code>max</code>, <code>pattern</code>, <code>custom</code>, or any <code>(value, ctx) =&gt; string | null</code>. In row mode all pending cells are validated atomically (no partial write); enterprise paste / fill validate per cell.</p>
+<h3 id="undo-redo" class="tsd-anchor-link">Undo / redo<a href="#undo-redo" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">editing</span><span class="hl-1"> = { </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">mode:</span><span class="hl-1"> </span><span class="hl-3">&#39;cell&#39;</span><span class="hl-1">, </span><span class="hl-2">history:</span><span class="hl-1"> { </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> } };</span><br/><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">undo</span><span class="hl-1">();          </span><span class="hl-15">// or Ctrl/Cmd+Z</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">redo</span><span class="hl-1">();          </span><span class="hl-15">// or Ctrl/Cmd+Shift+Z / Ctrl+Y</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">clearHistory</span><span class="hl-1">();</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">canUndo</span><span class="hl-1">; </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">canRedo</span><span class="hl-1">;</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Opt in via <code>editing.history</code>. Every committed cell edit is recorded (single, row-mode, and enterprise paste / fill collapse to one step). Keyboard shortcuts work while the grid body has focus, so an open editor's native undo is untouched. The stack holds 100 commands by default (<code>history: { enabled: true, stackSize: 200 }</code>). Event: <code>historyChanged { canUndo, canRedo }</code>.</p>
 <h3 id="row-selection" class="tsd-anchor-link">Row selection<a href="#row-selection" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">selection</span><span class="hl-1"> = { </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">, </span><span class="hl-2">mode:</span><span class="hl-1"> </span><span class="hl-3">&#39;multiple&#39;</span><span class="hl-1">, </span><span class="hl-2">showCheckboxColumn:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> };</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">selectRow</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">]);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">toggleRowSelection</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">1</span><span class="hl-1">]);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">selectAllRows</span><span class="hl-1">();</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">clearSelection</span><span class="hl-1">();</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">selectedRows</span><span class="hl-1">;                  </span><span class="hl-15">// snapshot</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">selectedRows</span><span class="hl-1"> = [</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">2</span><span class="hl-1">]];      </span><span class="hl-15">// replace selection (goes through `rowSelecting`)</span>
 </code><button type="button">Copy</button></pre>
 
 <p>Events: <code>rowSelecting</code> (cancellable), <code>rowSelected</code>.</p>
+<h3 id="row-pinning-top-bottom" class="tsd-anchor-link">Row pinning (top / bottom)<a href="#row-pinning-top-bottom" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">rowPinning</span><span class="hl-1"> = { </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> };</span><br/><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">pinRow</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">], </span><span class="hl-3">&#39;top&#39;</span><span class="hl-1">);</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">pinRow</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">5</span><span class="hl-1">], </span><span class="hl-3">&#39;bottom&#39;</span><span class="hl-1">);</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">unpinRow</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">]);</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">pinnedRows</span><span class="hl-1">;                    </span><span class="hl-15">// { top: T[], bottom: T[] }</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Pinned rows render in sticky top / bottom bands outside the virtualizer and are lifted out of the scrollable set (no duplication). Selection and styling work by row reference. Events: <code>rowPinning</code> (cancellable), <code>rowPinned</code>.</p>
+<h3 id="row-drag-reorder" class="tsd-anchor-link">Row drag-reorder<a href="#row-drag-reorder" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">rowReordering</span><span class="hl-1"> = { </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1"> };   </span><span class="hl-15">// add applyToData: true to splice grid.data in place</span><br/><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">moveRow</span><span class="hl-1">(</span><span class="hl-8">0</span><span class="hl-1">, </span><span class="hl-8">4</span><span class="hl-1">, </span><span class="hl-3">&#39;after&#39;</span><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+
+<p>By default (<code>rowReordering.handle</code>, boolean, default <code>true</code>) a six-dot grip handle shows at the start of every reorderable row, and dragging lifts a full-row floating ghost that follows the cursor. Both interaction modes are supported: <strong>handle mode</strong> (only the grip starts a drag, so the rest of the row stays free for selection and editing) and <strong>whole-row mode</strong> (set <code>handle: false</code> to drag from anywhere on the row, excluding interactive sub-parts like inputs and buttons). Or use the keyboard: focus a row, <strong>Space</strong> to grab, <strong>Arrow</strong> keys to move, <strong>Space / Enter</strong> to drop, <strong>Esc</strong> to cancel. The grid holds a manual order that is mutually exclusive with sorting (applying a sort clears it). By default the app persists the order via the <code>rowMoved</code> event; set <code>applyToData: true</code> to splice <code>grid.data</code> directly. Events: <code>rowMoving</code> (cancellable), <code>rowMoved { from, to, data }</code>.</p>
 <h3 id="row-expansion-master-detail" class="tsd-anchor-link">Row expansion (master-detail)<a href="#row-expansion-master-detail" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">expansion</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">detailTemplate</span><span class="hl-2">:</span><span class="hl-1"> ({ </span><span class="hl-2">data</span><span class="hl-1"> }) </span><span class="hl-5">=&gt;</span><span class="hl-1"> </span><span class="hl-4">html</span><span class="hl-3">`&lt;order-summary .order=</span><span class="hl-5">${</span><span class="hl-2">data</span><span class="hl-5">}</span><span class="hl-3">&gt;&lt;/order-summary&gt;`</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">isExpandable</span><span class="hl-2">:</span><span class="hl-1"> (</span><span class="hl-2">row</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> </span><span class="hl-2">row</span><span class="hl-1">.</span><span class="hl-2">hasDetails</span><span class="hl-1">,</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">expandRow</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">]);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">toggleRowExpansion</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">]);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">expandAllRows</span><span class="hl-1">();</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">collapseAllRows</span><span class="hl-1">();</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">expandedRows</span><span class="hl-1">;                  </span><span class="hl-15">// snapshot</span>
 </code><button type="button">Copy</button></pre>
 
 <p>Events: <code>rowExpanding</code> (cancellable), <code>rowExpanded</code>.</p>
 <h3 id="tree-data-nested-rows" class="tsd-anchor-link">Tree data (nested rows)<a href="#tree-data-nested-rows" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>The data array stays <strong>flat</strong>. The grid derives the hierarchy from a <code>getDataPath(row)</code> callback that returns the path from root to that row — AG Grid's &quot;tree data&quot; pattern.</p>
-<pre><code class="ts"><span class="hl-5">type</span><span class="hl-1"> </span><span class="hl-6">Person</span><span class="hl-1"> = { </span><span class="hl-2">id</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">; </span><span class="hl-2">name</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">; </span><span class="hl-2">title</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">; </span><span class="hl-2">path</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">[] };</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">data</span><span class="hl-1">: </span><span class="hl-6">Person</span><span class="hl-1">[] = [</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">1</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">,  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&#39;CEO&#39;</span><span class="hl-1">,     </span><span class="hl-2">path:</span><span class="hl-1"> [</span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">] },</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">2</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Bryan&#39;</span><span class="hl-1">,   </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&#39;VP Eng&#39;</span><span class="hl-1">,  </span><span class="hl-2">path:</span><span class="hl-1"> [</span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">, </span><span class="hl-3">&#39;Bryan&#39;</span><span class="hl-1">] },</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">3</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Cara&#39;</span><span class="hl-1">,    </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&#39;Manager&#39;</span><span class="hl-1">, </span><span class="hl-2">path:</span><span class="hl-1"> [</span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">, </span><span class="hl-3">&#39;Bryan&#39;</span><span class="hl-1">, </span><span class="hl-3">&#39;Cara&#39;</span><span class="hl-1">] },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">tree</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">getDataPath</span><span class="hl-2">:</span><span class="hl-1"> (</span><span class="hl-2">row</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> </span><span class="hl-2">row</span><span class="hl-1">.</span><span class="hl-2">path</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">defaultExpanded:</span><span class="hl-1"> </span><span class="hl-8">1</span><span class="hl-1">,              </span><span class="hl-15">// boolean | number — depth to expand</span><br/><span class="hl-1">  </span><span class="hl-2">groupColumnKey:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">,          </span><span class="hl-15">// which column shows the chevron + indent</span><br/><span class="hl-1">  </span><span class="hl-2">childIndent:</span><span class="hl-1"> </span><span class="hl-8">20</span><span class="hl-1">,                 </span><span class="hl-15">// px per depth level</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">toggleTreeRow</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">]);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">expandAllTreeRows</span><span class="hl-1">();</span>
+<p>The data array stays <strong>flat</strong>. The grid derives the hierarchy from a <code>getDataPath(row)</code> callback that returns the path from root to that row, the flat-array &quot;tree data&quot; pattern.</p>
+<pre><code class="ts"><span class="hl-5">type</span><span class="hl-1"> </span><span class="hl-6">Person</span><span class="hl-1"> = { </span><span class="hl-2">id</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">; </span><span class="hl-2">name</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">; </span><span class="hl-2">title</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">; </span><span class="hl-2">path</span><span class="hl-1">: </span><span class="hl-6">string</span><span class="hl-1">[] };</span><br/><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">data</span><span class="hl-1">: </span><span class="hl-6">Person</span><span class="hl-1">[] = [</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">1</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">,  </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&#39;CEO&#39;</span><span class="hl-1">,     </span><span class="hl-2">path:</span><span class="hl-1"> [</span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">] },</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">2</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Bryan&#39;</span><span class="hl-1">,   </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&#39;VP Eng&#39;</span><span class="hl-1">,  </span><span class="hl-2">path:</span><span class="hl-1"> [</span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">, </span><span class="hl-3">&#39;Bryan&#39;</span><span class="hl-1">] },</span><br/><span class="hl-1">  { </span><span class="hl-2">id:</span><span class="hl-1"> </span><span class="hl-8">3</span><span class="hl-1">, </span><span class="hl-2">name:</span><span class="hl-1"> </span><span class="hl-3">&#39;Cara&#39;</span><span class="hl-1">,    </span><span class="hl-2">title:</span><span class="hl-1"> </span><span class="hl-3">&#39;Manager&#39;</span><span class="hl-1">, </span><span class="hl-2">path:</span><span class="hl-1"> [</span><span class="hl-3">&#39;Adrian&#39;</span><span class="hl-1">, </span><span class="hl-3">&#39;Bryan&#39;</span><span class="hl-1">, </span><span class="hl-3">&#39;Cara&#39;</span><span class="hl-1">] },</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">tree</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-2">enabled:</span><span class="hl-1"> </span><span class="hl-5">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-4">getDataPath</span><span class="hl-2">:</span><span class="hl-1"> (</span><span class="hl-2">row</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> </span><span class="hl-2">row</span><span class="hl-1">.</span><span class="hl-2">path</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">defaultExpanded:</span><span class="hl-1"> </span><span class="hl-8">1</span><span class="hl-1">,              </span><span class="hl-15">// boolean | number, depth to expand</span><br/><span class="hl-1">  </span><span class="hl-2">groupColumnKey:</span><span class="hl-1"> </span><span class="hl-3">&#39;name&#39;</span><span class="hl-1">,          </span><span class="hl-15">// which column shows the chevron + indent</span><br/><span class="hl-1">  </span><span class="hl-2">childIndent:</span><span class="hl-1"> </span><span class="hl-8">20</span><span class="hl-1">,                 </span><span class="hl-15">// px per depth level</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">toggleTreeRow</span><span class="hl-1">(</span><span class="hl-2">data</span><span class="hl-1">[</span><span class="hl-8">0</span><span class="hl-1">]);</span><br/><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">expandAllTreeRows</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
 
 <p>Methods: <code>toggleTreeRow</code>, <code>expandTreeRow</code>, <code>collapseTreeRow</code>, <code>expandAllTreeRows</code>, <code>collapseAllTreeRows</code>, <code>isTreeRowExpanded</code>. Events: <code>treeRowExpanding</code> (cancellable), <code>treeRowExpanded</code>. When tree mode is active, the host element advertises <code>role=&quot;treegrid&quot;</code>.</p>
@@ -179,7 +219,7 @@
 <pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">exportToCSV</span><span class="hl-1">();                                            </span><span class="hl-15">// downloads data.csv</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">exportToCSV</span><span class="hl-1">({ </span><span class="hl-2">filename:</span><span class="hl-1"> </span><span class="hl-3">&#39;users&#39;</span><span class="hl-1">, </span><span class="hl-2">source:</span><span class="hl-1"> </span><span class="hl-3">&#39;selected&#39;</span><span class="hl-1"> });</span><br/><span class="hl-5">const</span><span class="hl-1"> </span><span class="hl-7">text</span><span class="hl-1"> = </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">exportToCSV</span><span class="hl-1">({ </span><span class="hl-2">filename:</span><span class="hl-1"> </span><span class="hl-3">&#39;&#39;</span><span class="hl-1"> });               </span><span class="hl-15">// no download, returns the string</span>
 </code><button type="button">Copy</button></pre>
 
-<p><code>source</code> can be <code>'view'</code> (default — post-filter/post-sort), <code>'page'</code>, <code>'selected'</code>, or <code>'all'</code>. Per-column opt-out: <code>{ key: 'secret', exportable: false }</code>.</p>
+<p><code>source</code> can be <code>'view'</code> (default, post-filter/post-sort), <code>'page'</code>, <code>'selected'</code>, or <code>'all'</code>. Per-column opt-out: <code>{ key: 'secret', exportable: false }</code>.</p>
 <blockquote>
 <p><strong>XLSX (Excel) export</strong> moved to <a href="https://www.npmjs.com/package/apex-grid-enterprise"><code>apex-grid-enterprise</code></a> in v3. <code>&lt;apex-grid-enterprise&gt;</code> adds <code>grid.exportToXLSX(...)</code> and an &quot;Export XLSX&quot; entry to this same toolbar menu. CSV stays free.</p>
 </blockquote>
@@ -234,11 +274,28 @@
 </table>
 <p>Search input has a <code>debounce</code> attribute (default <code>200</code>ms).</p>
 <h3 id="theming" class="tsd-anchor-link">Theming<a href="#theming" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>The grid styles itself through <code>--ag-*</code> CSS custom properties — override them on <code>apex-grid</code> (or any ancestor) to rebrand; see <a href="media/_tokens.scss"><code>src/styles/_tokens.scss</code></a> for the full list. When <code>igniteui-webcomponents</code> is present, the brand tokens auto-tint from its palette.</p>
+<p>The grid styles itself through <code>--ag-*</code> CSS custom properties; override them on <code>apex-grid</code> (or any ancestor) to rebrand; see <a href="media/_tokens.scss"><code>src/styles/_tokens.scss</code></a> for the full list. When <code>igniteui-webcomponents</code> is present, the brand tokens auto-tint from its palette.</p>
 <p>Style with CSS parts on the grid, paginator, and toolbar:</p>
 <pre><code class="css"><span class="hl-10">apex-grid</span><span class="hl-1">::part(paginator) { </span><span class="hl-12">background</span><span class="hl-1">: </span><span class="hl-4">var</span><span class="hl-1">(</span><span class="hl-12">--surface-2</span><span class="hl-1">); }</span><br/><span class="hl-10">apex-grid-toolbar</span><span class="hl-1">::part(</span><span class="hl-10">search-input</span><span class="hl-1">) { </span><span class="hl-12">font-family</span><span class="hl-1">: </span><span class="hl-4">var</span><span class="hl-1">(</span><span class="hl-12">--font-mono</span><span class="hl-1">); }</span>
 </code><button type="button">Copy</button></pre>
 
+<h3 id="spreadsheet-coordinates" class="tsd-anchor-link">Spreadsheet coordinates<a href="#spreadsheet-coordinates" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">coordinateHints</span><span class="hl-1"> = </span><span class="hl-5">true</span><span class="hl-1">;</span>
+</code><button type="button">Copy</button></pre>
+
+<pre><code class="html"><span class="hl-9">&lt;</span><span class="hl-10">apex-grid</span><span class="hl-1"> </span><span class="hl-12">coordinate-hints</span><span class="hl-9">&gt;&lt;/</span><span class="hl-10">apex-grid</span><span class="hl-9">&gt;</span>
+</code><button type="button">Copy</button></pre>
+
+<p>When <code>coordinateHints</code> is on, the grid shows a leading row-number gutter (1, 2, 3, and so on) and A / B / C column-letter chips in the headers, so cell references are discoverable (a spreadsheet-style look). Set it directly for a persistent spreadsheet look. <code>apex-grid-enterprise</code> turns it on by default for any grid that has an <code>allowFormula</code> column, so the gutter is reserved up front and entering a formula never shifts the layout. Reflected to the <code>coordinate-hints</code> attribute (default <code>false</code>).</p>
+<h3 id="state-persistence" class="tsd-anchor-link">State &amp; persistence<a href="#state-persistence" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<p><code>getState()</code> returns a JSON-safe snapshot of the grid's restorable view and <code>setState()</code> applies one back. The snapshot covers column layout (order, width, pinning, visibility), sort, filter, quick filter, pagination, selection, expansion, tree expansion, pinned rows, the manual drag-reorder order, and any feature-module state (enterprise grouping / pivot / aggregation / ranges). Functions and templates are never serialized: sort comparers, filter condition functions, and cell/header/editor templates re-bind from the live <code>columns</code> config on restore (filter conditions are captured by operand name).</p>
+<pre><code class="js"><span class="hl-15">// Save and restore a view.</span><br/><span class="hl-2">localStorage</span><span class="hl-1">.</span><span class="hl-4">setItem</span><span class="hl-1">(</span><span class="hl-3">&#39;view&#39;</span><span class="hl-1">, </span><span class="hl-7">JSON</span><span class="hl-1">.</span><span class="hl-4">stringify</span><span class="hl-1">(</span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">getState</span><span class="hl-1">()));</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">setState</span><span class="hl-1">(</span><span class="hl-7">JSON</span><span class="hl-1">.</span><span class="hl-4">parse</span><span class="hl-1">(</span><span class="hl-2">localStorage</span><span class="hl-1">.</span><span class="hl-4">getItem</span><span class="hl-1">(</span><span class="hl-3">&#39;view&#39;</span><span class="hl-1">)));</span><br/><br/><span class="hl-15">// Persist automatically: stateChanged fires (debounced) after every settled</span><br/><span class="hl-15">// change, and only while something is listening.</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">addEventListener</span><span class="hl-1">(</span><span class="hl-3">&#39;stateChanged&#39;</span><span class="hl-1">, (</span><span class="hl-2">e</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><br/><span class="hl-1">  </span><span class="hl-2">localStorage</span><span class="hl-1">.</span><span class="hl-4">setItem</span><span class="hl-1">(</span><span class="hl-3">&#39;view&#39;</span><span class="hl-1">, </span><span class="hl-7">JSON</span><span class="hl-1">.</span><span class="hl-4">stringify</span><span class="hl-1">(</span><span class="hl-2">e</span><span class="hl-1">.</span><span class="hl-2">detail</span><span class="hl-1">.</span><span class="hl-2">state</span><span class="hl-1">))</span><br/><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+
+<p><strong>Row identity.</strong> Selection, expansion, pinned rows, and the manual order are captured as row references. Set <code>grid.rowId = (row) =&gt; row.id</code> for durable references that survive a data reload; without it, rows are referenced by position (index), which round-trips within a session but not across a reload.</p>
+<p><strong><code>setState</code> is defensive.</strong> It is meant to accept persisted-and-possibly-stale blobs and AI output, so it never throws on bad input (unless you pass <code>{ strict: true }</code>): unknown columns / operands are dropped, out-of-range pages clamped, unresolvable rows skipped, and a wrong snapshot <code>version</code> applied best-effort. It returns a <code>SetStateResult</code> (<code>{ applied, skipped, warnings }</code>) so you can see exactly what happened. <code>setState</code> is partial: pass only the slices you want to change.</p>
+<p><strong><code>getSchema()</code></strong> returns a machine-readable description of the grid (columns + data types, available sort directions and filter operands per column, grid-level capabilities) with the current state embedded. It is the contract an AI layer feeds an LLM and validates a patch against, but it equally drives a view-editor UI or documentation.</p>
+<p>See <a href="media/state-persistence.html"><code>demo/state-persistence.html</code></a> for a save / restore / live-snapshot example.</p>
 <hr>
 <h2 id="api-reference" class="tsd-anchor-link">API Reference<a href="#api-reference" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="properties" class="tsd-anchor-link">Properties<a href="#properties" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -279,13 +336,13 @@
 <tr>
 <td><code>dataPipelineConfiguration</code></td>
 <td><code>DataPipelineConfiguration&lt;T&gt;</code></td>
-<td>—</td>
+<td></td>
 <td>Custom sort/filter/pagination hooks</td>
 </tr>
 <tr>
 <td><code>pagination</code></td>
 <td><code>PaginationConfiguration</code></td>
-<td>—</td>
+<td></td>
 <td></td>
 </tr>
 <tr>
@@ -313,93 +370,141 @@
 <td>Attr <code>column-reordering</code></td>
 </tr>
 <tr>
+<td><code>columnGroups</code></td>
+<td><code>ColumnGroupConfiguration[]</code></td>
+<td></td>
+<td>Spanning header groups (<code>column.group</code> references an <code>id</code>)</td>
+</tr>
+<tr>
 <td><code>editing</code></td>
 <td><code>GridEditingConfiguration</code></td>
-<td>—</td>
 <td></td>
+<td>Includes <code>history</code> for undo/redo; per-column <code>validators</code></td>
 </tr>
 <tr>
 <td><code>selection</code></td>
 <td><code>GridSelectionConfiguration</code></td>
-<td>—</td>
+<td></td>
 <td></td>
 </tr>
 <tr>
 <td><code>expansion</code></td>
 <td><code>GridExpansionConfiguration&lt;T&gt;</code></td>
-<td>—</td>
+<td></td>
 <td></td>
 </tr>
 <tr>
 <td><code>tree</code></td>
 <td><code>GridTreeConfiguration&lt;T&gt;</code></td>
-<td>—</td>
 <td></td>
+<td></td>
+</tr>
+<tr>
+<td><code>rowPinning</code></td>
+<td><code>GridRowPinningConfiguration</code></td>
+<td></td>
+<td><code>{ enabled }</code></td>
+</tr>
+<tr>
+<td><code>rowReordering</code></td>
+<td><code>GridRowReorderingConfiguration</code></td>
+<td></td>
+<td><code>{ enabled, applyToData?, handle? }</code> (<code>handle</code> default <code>true</code>: grip-only drag)</td>
+</tr>
+<tr>
+<td><code>coordinateHints</code></td>
+<td><code>boolean</code></td>
+<td><code>false</code></td>
+<td>Show a row-number gutter + A / B / C header chips (spreadsheet look). Attr <code>coordinate-hints</code></td>
+</tr>
+<tr>
+<td><code>columnMenu</code></td>
+<td><code>boolean</code></td>
+<td><code>true</code></td>
+<td>Show the always-visible column-menu (kebab) button on headers; <code>false</code> hides it</td>
+</tr>
+<tr>
+<td><code>rowId</code></td>
+<td><code>(row: T) =&gt; string | number</code></td>
+<td></td>
+<td>Durable row identity for <code>getState</code> / <code>setState</code></td>
+</tr>
+<tr>
+<td><code>localeText</code></td>
+<td><code>GridLocaleText</code></td>
+<td></td>
+<td>Override map for built-in strings (e.g. <code>esLocale</code>)</td>
+</tr>
+<tr>
+<td><code>canUndo</code>, <code>canRedo</code></td>
+<td><code>boolean</code></td>
+<td></td>
+<td>Get (history)</td>
 </tr>
 <tr>
 <td><code>sortExpressions</code></td>
 <td><code>SortExpression&lt;T&gt;[]</code></td>
-<td>—</td>
+<td></td>
 <td>Get/set</td>
 </tr>
 <tr>
 <td><code>filterExpressions</code></td>
 <td><code>FilterExpression&lt;T&gt;[]</code></td>
-<td>—</td>
+<td></td>
 <td>Get/set</td>
 </tr>
 <tr>
 <td><code>selectedRows</code></td>
 <td><code>T[]</code></td>
-<td>—</td>
+<td></td>
 <td>Get/set</td>
 </tr>
 <tr>
 <td><code>expandedRows</code></td>
 <td><code>T[]</code></td>
-<td>—</td>
+<td></td>
 <td>Get/set</td>
 </tr>
 <tr>
 <td><code>page</code>, <code>pageSize</code>, <code>pageCount</code>, <code>totalItems</code></td>
 <td><code>number</code></td>
-<td>—</td>
+<td></td>
 <td></td>
 </tr>
 <tr>
 <td><code>pageItems</code></td>
 <td><code>readonly T[]</code></td>
-<td>—</td>
+<td></td>
 <td>Currently rendered slice</td>
 </tr>
 <tr>
 <td><code>dataView</code></td>
 <td><code>readonly T[]</code></td>
-<td>—</td>
+<td></td>
 <td>Post-filter, post-sort</td>
 </tr>
 <tr>
 <td><code>displayColumns</code></td>
 <td><code>readonly ColumnConfiguration&lt;T&gt;[]</code></td>
-<td>—</td>
+<td></td>
 <td>Render order (pinned start → unpinned → pinned end)</td>
 </tr>
 <tr>
 <td><code>editingCell</code></td>
 <td><code>{ rowIndex, columnKey } | null</code></td>
-<td>—</td>
+<td></td>
 <td></td>
 </tr>
 <tr>
 <td><code>editingRow</code></td>
 <td><code>number | null</code></td>
-<td>—</td>
+<td></td>
 <td>Row-mode only</td>
 </tr>
 </tbody>
 </table>
 <h3 id="methods" class="tsd-anchor-link">Methods<a href="#methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<pre><code class="ts"><span class="hl-4">sort</span><span class="hl-1">(</span><span class="hl-2">expr</span><span class="hl-1">): </span><span class="hl-5">void</span><br/><span class="hl-4">filter</span><span class="hl-1">(</span><span class="hl-2">expr</span><span class="hl-1">): </span><span class="hl-5">void</span><br/><span class="hl-4">clearSort</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">?): </span><span class="hl-5">void</span><br/><span class="hl-4">clearFilter</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">?): </span><span class="hl-5">void</span><br/><span class="hl-4">setQuickFilter</span><span class="hl-1">(</span><span class="hl-2">value</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><br/><span class="hl-4">getColumn</span><span class="hl-1">(</span><span class="hl-2">keyOrIndex</span><span class="hl-1">): </span><span class="hl-2">ColumnConfiguration</span><span class="hl-1">&lt;</span><span class="hl-7">T</span><span class="hl-1">&gt; | </span><span class="hl-5">undefined</span><br/><span class="hl-4">updateColumns</span><span class="hl-1">(</span><span class="hl-2">columns</span><span class="hl-1">): </span><span class="hl-5">void</span><br/><span class="hl-4">pinColumn</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">, </span><span class="hl-3">&#39;start&#39;</span><span class="hl-1"> | </span><span class="hl-3">&#39;end&#39;</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">unpinColumn</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">moveColumn</span><span class="hl-1">(</span><span class="hl-2">fromKey</span><span class="hl-1">, </span><span class="hl-2">toKey</span><span class="hl-1">, </span><span class="hl-3">&#39;before&#39;</span><span class="hl-1"> | </span><span class="hl-3">&#39;after&#39;</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><br/><span class="hl-4">gotoPage</span><span class="hl-1">(</span><span class="hl-2">page</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">setPageSize</span><span class="hl-1">(</span><span class="hl-2">size</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">nextPage</span><span class="hl-1">(); </span><span class="hl-4">previousPage</span><span class="hl-1">(); </span><span class="hl-4">firstPage</span><span class="hl-1">(); </span><span class="hl-4">lastPage</span><span class="hl-1">()</span><br/><br/><span class="hl-4">editCell</span><span class="hl-1">(</span><span class="hl-2">rowIndex</span><span class="hl-1">, </span><span class="hl-2">columnKey</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">editRow</span><span class="hl-1">(</span><span class="hl-2">rowIndex</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">commitEdit</span><span class="hl-1">(): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">cancelEdit</span><span class="hl-1">(): </span><span class="hl-5">void</span><br/><br/><span class="hl-4">selectRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">deselectRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">toggleRowSelection</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><span class="hl-4">selectAllRows</span><span class="hl-1">(); </span><span class="hl-4">clearSelection</span><span class="hl-1">(); </span><span class="hl-4">isRowSelected</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><br/><span class="hl-4">expandRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">collapseRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">toggleRowExpansion</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><span class="hl-4">expandAllRows</span><span class="hl-1">(); </span><span class="hl-4">collapseAllRows</span><span class="hl-1">(); </span><span class="hl-4">isRowExpanded</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><br/><span class="hl-4">toggleTreeRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">expandTreeRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">collapseTreeRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><span class="hl-4">expandAllTreeRows</span><span class="hl-1">(); </span><span class="hl-4">collapseAllTreeRows</span><span class="hl-1">(); </span><span class="hl-4">isTreeRowExpanded</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><br/><span class="hl-4">exportToCSV</span><span class="hl-1">(</span><span class="hl-2">options</span><span class="hl-1">?): </span><span class="hl-2">string</span><br/><span class="hl-4">exportAs</span><span class="hl-1">(</span><span class="hl-2">formatId</span><span class="hl-1">, </span><span class="hl-2">options</span><span class="hl-1">?): </span><span class="hl-5">void</span><span class="hl-1">   </span><span class="hl-15">// toolbar dispatch; &#39;csv&#39; (community), &#39;xlsx&#39; (enterprise)</span>
+<pre><code class="ts"><span class="hl-4">sort</span><span class="hl-1">(</span><span class="hl-2">expr</span><span class="hl-1">): </span><span class="hl-5">void</span><br/><span class="hl-4">filter</span><span class="hl-1">(</span><span class="hl-2">expr</span><span class="hl-1">): </span><span class="hl-5">void</span><br/><span class="hl-4">clearSort</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">?): </span><span class="hl-5">void</span><br/><span class="hl-4">clearFilter</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">?): </span><span class="hl-5">void</span><br/><span class="hl-4">setQuickFilter</span><span class="hl-1">(</span><span class="hl-2">value</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><br/><span class="hl-4">getColumn</span><span class="hl-1">(</span><span class="hl-2">keyOrIndex</span><span class="hl-1">): </span><span class="hl-2">ColumnConfiguration</span><span class="hl-1">&lt;</span><span class="hl-7">T</span><span class="hl-1">&gt; | </span><span class="hl-5">undefined</span><br/><span class="hl-4">updateColumns</span><span class="hl-1">(</span><span class="hl-2">columns</span><span class="hl-1">): </span><span class="hl-5">void</span><br/><span class="hl-4">pinColumn</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">, </span><span class="hl-3">&#39;start&#39;</span><span class="hl-1"> | </span><span class="hl-3">&#39;end&#39;</span><span class="hl-1"> | </span><span class="hl-5">null</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">unpinColumn</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">moveColumn</span><span class="hl-1">(</span><span class="hl-2">fromKey</span><span class="hl-1">, </span><span class="hl-2">toKey</span><span class="hl-1">, </span><span class="hl-3">&#39;before&#39;</span><span class="hl-1"> | </span><span class="hl-3">&#39;after&#39;</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><br/><span class="hl-4">gotoPage</span><span class="hl-1">(</span><span class="hl-2">page</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">setPageSize</span><span class="hl-1">(</span><span class="hl-2">size</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">nextPage</span><span class="hl-1">(); </span><span class="hl-4">previousPage</span><span class="hl-1">(); </span><span class="hl-4">firstPage</span><span class="hl-1">(); </span><span class="hl-4">lastPage</span><span class="hl-1">()</span><br/><br/><span class="hl-4">editCell</span><span class="hl-1">(</span><span class="hl-2">rowIndex</span><span class="hl-1">, </span><span class="hl-2">columnKey</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">editRow</span><span class="hl-1">(</span><span class="hl-2">rowIndex</span><span class="hl-1">): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">commitEdit</span><span class="hl-1">(): </span><span class="hl-6">Promise</span><span class="hl-1">&lt;</span><span class="hl-2">boolean</span><span class="hl-1">&gt;</span><br/><span class="hl-4">cancelEdit</span><span class="hl-1">(): </span><span class="hl-5">void</span><br/><br/><span class="hl-4">selectRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">deselectRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">toggleRowSelection</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><span class="hl-4">selectAllRows</span><span class="hl-1">(); </span><span class="hl-4">clearSelection</span><span class="hl-1">(); </span><span class="hl-4">isRowSelected</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><br/><span class="hl-4">expandRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">collapseRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">toggleRowExpansion</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><span class="hl-4">expandAllRows</span><span class="hl-1">(); </span><span class="hl-4">collapseAllRows</span><span class="hl-1">(); </span><span class="hl-4">isRowExpanded</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><br/><span class="hl-4">toggleTreeRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">expandTreeRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">); </span><span class="hl-4">collapseTreeRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><span class="hl-4">expandAllTreeRows</span><span class="hl-1">(); </span><span class="hl-4">collapseAllTreeRows</span><span class="hl-1">(); </span><span class="hl-4">isTreeRowExpanded</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)</span><br/><br/><span class="hl-4">pinRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">, </span><span class="hl-3">&#39;top&#39;</span><span class="hl-1"> | </span><span class="hl-3">&#39;bottom&#39;</span><span class="hl-1">); </span><span class="hl-4">unpinRow</span><span class="hl-1">(</span><span class="hl-2">row</span><span class="hl-1">)   </span><span class="hl-15">// pinnedRows getter</span><br/><span class="hl-4">moveRow</span><span class="hl-1">(</span><span class="hl-2">from</span><span class="hl-1">, </span><span class="hl-2">to</span><span class="hl-1">, </span><span class="hl-3">&#39;before&#39;</span><span class="hl-1"> | </span><span class="hl-3">&#39;after&#39;</span><span class="hl-1">)</span><br/><br/><span class="hl-4">undo</span><span class="hl-1">(); </span><span class="hl-4">redo</span><span class="hl-1">(); </span><span class="hl-4">clearHistory</span><span class="hl-1">()                 </span><span class="hl-15">// canUndo / canRedo getters</span><br/><br/><span class="hl-4">localize</span><span class="hl-1">(</span><span class="hl-2">key</span><span class="hl-1">, </span><span class="hl-2">params</span><span class="hl-1">?, </span><span class="hl-2">fallback</span><span class="hl-1">?): </span><span class="hl-2">string</span><span class="hl-1">      </span><span class="hl-15">// resolve a locale string</span><br/><br/><span class="hl-4">exportToCSV</span><span class="hl-1">(</span><span class="hl-2">options</span><span class="hl-1">?): </span><span class="hl-2">string</span><br/><span class="hl-4">exportAs</span><span class="hl-1">(</span><span class="hl-2">formatId</span><span class="hl-1">, </span><span class="hl-2">options</span><span class="hl-1">?): </span><span class="hl-5">void</span><span class="hl-1">   </span><span class="hl-15">// toolbar dispatch; &#39;csv&#39; (community), &#39;xlsx&#39; (enterprise)</span><br/><br/><span class="hl-4">getState</span><span class="hl-1">(</span><span class="hl-2">options</span><span class="hl-1">?): </span><span class="hl-2">GridState</span><br/><span class="hl-4">setState</span><span class="hl-1">(</span><span class="hl-2">state</span><span class="hl-1">, </span><span class="hl-2">options</span><span class="hl-1">?): </span><span class="hl-2">SetStateResult</span><span class="hl-1">   </span><span class="hl-15">// partial + defensive; never throws unless { strict: true }</span><br/><span class="hl-4">getSchema</span><span class="hl-1">(): </span><span class="hl-2">GridSchema</span><span class="hl-1">                      </span><span class="hl-15">// machine-readable capability descriptor</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="events" class="tsd-anchor-link">Events<a href="#events" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -449,16 +554,36 @@
 <td><code>{ row, column, value, newValue }</code></td>
 </tr>
 <tr>
+<td><code>cellValidationFailed</code></td>
+<td>no</td>
+<td><code>{ key, rowIndex, data, value, errors }</code></td>
+</tr>
+<tr>
 <td><code>rowEditStarted</code> / <code>rowEditEnded</code></td>
 <td>no / no</td>
 <td>row context</td>
 </tr>
 <tr>
+<td><code>historyChanged</code></td>
+<td>no</td>
+<td><code>{ canUndo, canRedo }</code></td>
+</tr>
+<tr>
 <td><code>rowSelecting</code> / <code>rowSelected</code></td>
 <td>yes / no</td>
 <td><code>{ added, removed }</code></td>
 </tr>
 <tr>
+<td><code>rowPinning</code> / <code>rowPinned</code></td>
+<td>yes / no</td>
+<td><code>{ row, position }</code></td>
+</tr>
+<tr>
+<td><code>rowMoving</code> / <code>rowMoved</code></td>
+<td>yes / no</td>
+<td><code>{ from, to, data }</code></td>
+</tr>
+<tr>
 <td><code>rowExpanding</code> / <code>rowExpanded</code></td>
 <td>yes / no</td>
 <td>row context</td>
@@ -468,11 +593,16 @@
 <td>yes / no</td>
 <td>row context</td>
 </tr>
+<tr>
+<td><code>stateChanged</code></td>
+<td>no</td>
+<td><code>{ state }</code> (debounced; only while listened)</td>
+</tr>
 </tbody>
 </table>
-<p>Programmatic <code>sort()</code> / <code>filter()</code> calls are silent — only UI-initiated changes emit <code>sorting</code> / <code>filtering</code>.</p>
+<p>Programmatic <code>sort()</code> / <code>filter()</code> calls are silent; only UI-initiated changes emit <code>sorting</code> / <code>filtering</code>.</p>
 <h3 id="attributes" class="tsd-anchor-link">Attributes<a href="#attributes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p><code>auto-generate</code>, <code>quick-filter</code>, <code>show-quick-filter</code>, <code>show-export</code>, <code>column-reordering</code>.</p>
+<p><code>auto-generate</code>, <code>quick-filter</code>, <code>show-quick-filter</code>, <code>show-export</code>, <code>column-reordering</code>, <code>coordinate-hints</code>.</p>
 <h3 id="css-parts" class="tsd-anchor-link">CSS parts<a href="#css-parts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <table>
 <thead>
@@ -537,12 +667,12 @@
 <h2 id="releasing" class="tsd-anchor-link">Releasing<a href="#releasing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>Releases are automated by <a href=".github/workflows/publish.yml">.github/workflows/publish.yml</a>:</p>
 <ol>
-<li>Bump <code>&quot;version&quot;</code> in <a href="media/package.json">package.json</a> — the single source of truth. The build injects it into <code>dist/package.json</code>.</li>
+<li>Bump <code>&quot;version&quot;</code> in <a href="media/package.json">package.json</a>, the single source of truth. The build injects it into <code>dist/package.json</code>.</li>
 <li>Commit with a message starting with <code>release:</code> and the same version, e.g. <code>release: 2.0.0</code> or <code>release: 2.0.0-rc.1</code>.</li>
 <li>Push to <code>main</code>.</li>
 </ol>
-<p>The workflow then verifies the version triple-match, runs lint + tests + build, publishes <code>dist/</code> to npm with <code>--provenance</code> (OIDC trusted publishing — no token in secrets), and creates a <code>vX.Y.Z</code> git tag and GitHub Release with auto-generated notes. Pre-release versions (containing <code>-</code>) publish under the <code>next</code> dist-tag; stable versions under <code>latest</code>.</p>
+<p>The workflow then verifies the version triple-match, runs lint + tests + build, publishes <code>dist/</code> to npm with <code>--provenance</code> (OIDC trusted publishing, no token in secrets), and creates a <code>vX.Y.Z</code> git tag and GitHub Release with auto-generated notes. Pre-release versions (containing <code>-</code>) publish under the <code>next</code> dist-tag; stable versions under <code>latest</code>.</p>
 <p>Any push whose head commit does not start with <code>release:</code> is a no-op for the workflow.</p>
 <h2 id="license" class="tsd-anchor-link">License<a href="#license" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>See <a href="media/LICENSE">LICENSE</a>.</p>
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#apex-grid"><span>Apex <wbr/>Grid</span></a><ul><li><a href="#features"><span>Features</span></a></li><li><a href="#quick-start"><span>Quick <wbr/>Start</span></a></li><li><ul><li><a href="#one-call-setup"><span>One-<wbr/>call setup</span></a></li><li><a href="#render-the-grid"><span>Render the grid</span></a></li></ul></li><li><a href="#manual-setup-four-steps"><span>Manual setup (four steps)</span></a></li><li><ul><li><a href="#1-install"><span>1. <wbr/>Install</span></a></li><li><a href="#2-register-the-custom-element"><span>2. <wbr/>Register the custom element</span></a></li><li><a href="#3-optional-customize-the-look"><span>3. (<wbr/>Optional) <wbr/>Customize the look</span></a></li><li><a href="#4-size-the-host"><span>4. <wbr/>Size the host</span></a></li><li><a href="#what-success-looks-like"><span>What success looks like</span></a></li><li><a href="#troubleshooting"><span>Troubleshooting</span></a></li></ul></li><li><a href="#features-in-depth"><span>Features in depth</span></a></li><li><ul><li><a href="#sorting"><span>Sorting</span></a></li><li><a href="#filtering"><span>Filtering</span></a></li><li><a href="#quick-filter-global-search"><span>Quick filter (global search)</span></a></li><li><a href="#pagination"><span>Pagination</span></a></li><li><a href="#column-pinning"><span>Column pinning</span></a></li><li><a href="#column-reordering"><span>Column reordering</span></a></li><li><a href="#inline-editing"><span>Inline editing</span></a></li><li><a href="#row-selection"><span>Row selection</span></a></li><li><a href="#row-expansion-master-detail"><span>Row expansion (master-<wbr/>detail)</span></a></li><li><a href="#tree-data-nested-rows"><span>Tree data (nested rows)</span></a></li><li><a href="#csv-export"><span>CSV export</span></a></li><li><a href="#toolbar"><span>Toolbar</span></a></li><li><a href="#theming"><span>Theming</span></a></li></ul></li><li><a href="#api-reference"><span>API <wbr/>Reference</span></a></li><li><ul><li><a href="#properties"><span>Properties</span></a></li><li><a href="#methods"><span>Methods</span></a></li><li><a href="#events"><span>Events</span></a></li><li><a href="#attributes"><span>Attributes</span></a></li><li><a href="#css-parts"><span>CSS parts</span></a></li></ul></li><li><a href="#framework-integration"><span>Framework integration</span></a></li><li><a href="#local-development"><span>Local development</span></a></li><li><a href="#releasing"><span>Releasing</span></a></li><li><a href="#license"><span>License</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">apex-grid</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#apex-grid"><span>Apex <wbr/>Grid</span></a><ul><li><a href="#features"><span>Features</span></a></li><li><a href="#quick-start"><span>Quick <wbr/>Start</span></a></li><li><ul><li><a href="#one-call-setup"><span>One-<wbr/>call setup</span></a></li><li><a href="#render-the-grid"><span>Render the grid</span></a></li></ul></li><li><a href="#manual-setup-four-steps"><span>Manual setup (four steps)</span></a></li><li><ul><li><a href="#1-install"><span>1. <wbr/>Install</span></a></li><li><a href="#2-register-the-custom-element"><span>2. <wbr/>Register the custom element</span></a></li><li><a href="#3-optional-customize-the-look"><span>3. (<wbr/>Optional) <wbr/>Customize the look</span></a></li><li><a href="#4-size-the-host"><span>4. <wbr/>Size the host</span></a></li><li><a href="#what-success-looks-like"><span>What success looks like</span></a></li><li><a href="#troubleshooting"><span>Troubleshooting</span></a></li></ul></li><li><a href="#features-in-depth"><span>Features in depth</span></a></li><li><ul><li><a href="#sorting"><span>Sorting</span></a></li><li><a href="#filtering"><span>Filtering</span></a></li><li><a href="#quick-filter-global-search"><span>Quick filter (global search)</span></a></li><li><a href="#pagination"><span>Pagination</span></a></li><li><a href="#column-pinning"><span>Column pinning</span></a></li><li><a href="#column-reordering"><span>Column reordering</span></a></li><li><a href="#column-separators"><span>Column separators</span></a></li><li><a href="#column-groups-spanning-headers"><span>Column groups (spanning headers)</span></a></li><li><a href="#inline-editing"><span>Inline editing</span></a></li><li><a href="#cell-validation"><span>Cell validation</span></a></li><li><a href="#undo-redo"><span>Undo / redo</span></a></li><li><a href="#row-selection"><span>Row selection</span></a></li><li><a href="#row-pinning-top-bottom"><span>Row pinning (top / bottom)</span></a></li><li><a href="#row-drag-reorder"><span>Row drag-<wbr/>reorder</span></a></li><li><a href="#row-expansion-master-detail"><span>Row expansion (master-<wbr/>detail)</span></a></li><li><a href="#tree-data-nested-rows"><span>Tree data (nested rows)</span></a></li><li><a href="#csv-export"><span>CSV export</span></a></li><li><a href="#toolbar"><span>Toolbar</span></a></li><li><a href="#theming"><span>Theming</span></a></li><li><a href="#spreadsheet-coordinates"><span>Spreadsheet coordinates</span></a></li><li><a href="#state-persistence"><span>State &amp; persistence</span></a></li></ul></li><li><a href="#api-reference"><span>API <wbr/>Reference</span></a></li><li><ul><li><a href="#properties"><span>Properties</span></a></li><li><a href="#methods"><span>Methods</span></a></li><li><a href="#events"><span>Events</span></a></li><li><a href="#attributes"><span>Attributes</span></a></li><li><a href="#css-parts"><span>CSS parts</span></a></li></ul></li><li><a href="#framework-integration"><span>Framework integration</span></a></li><li><a href="#local-development"><span>Local development</span></a></li><li><a href="#releasing"><span>Releasing</span></a></li><li><a href="#license"><span>License</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">apex-grid</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>