apex-grid 3.5.0 → 4.0.0-beta.1

package/docs/index.html

@@ -36,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>), also inside any shadow root a grid connects in. 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>
@@ -61,16 +61,30 @@
 
 <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 on any ancestor: <code>:root</code>, a dashboard panel, or the shadow host of a web component the grid renders in (custom properties inherit through shadow boundaries, however deep). 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>See <a href="media/_token-values.scss"><code>src/styles/_token-values.scss</code></a> for the full token list and defaults (surfaces, text, semantic state colors, typography, spacing, motion).</p>
+<p><strong>Where the defaults live.</strong> The first grid to connect adopts the token defaults into its document, on <code>:where(:root)</code>, through <code>adoptedStyleSheets</code> (no <code>&lt;style&gt;</code> element, so no CSP nonce). Zero specificity means any value you set wins, and <code>var(--ag-*)</code> reads in your own CSS resolve to the defaults. If you manage your own CSS, opt out with <code>setup({ tokenStyles: false })</code> and import the same defaults as a file (also the way to get them into server-rendered HTML):</p>
+<pre><code class="ts"><span class="hl-0">import</span><span class="hl-1"> </span><span class="hl-3">&#39;apex-grid/tokens.css&#39;</span><span class="hl-1">;</span>
+</code><button type="button">Copy</button></pre>
+
+<p>The grid renders the same without the sheet; it carries the defaults as fallbacks. Three groups have no root default, so page CSS reading them needs its own fallback:</p>
+<ul>
+<li><code>--ag-brand</code> and <code>--ag-brand-strong</code>, so an Ignite UI palette set on any ancestor keeps tinting the grid (see below).</li>
+<li>The derived washes <code>--ag-brand-soft</code>, <code>--ag-brand-softer</code>, <code>--ag-brand-line</code>, <code>--ag-row-hover</code> and <code>--ag-surface-alt</code>. The grid mixes them from the brand and surface in effect, so they follow a brand set on an ancestor. Set them only to override the mix.</li>
+</ul>
+<p><strong>Dark mode.</strong> <code>theme=&quot;dark&quot;</code> reads its own colour inputs, <code>--ag-dark-*</code> (<code>--ag-dark-surface</code>, <code>--ag-dark-text</code>, <code>--ag-dark-hairline</code>, <code>--ag-dark-shadow-card</code>, and so on), so a light palette set on a shared ancestor never puts a white surface under the dark theme's light text. Sizing, typography, motion, the brand and the base state colours are shared by both modes. To theme both from one place, set both palettes:</p>
+<pre><code class="css"><span class="hl-16">.dashboard</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><br/><span class="hl-1">  </span><span class="hl-12">--ag-surface</span><span class="hl-1">: </span><span class="hl-14">#fdfcff</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-12">--ag-dark-surface</span><span class="hl-1">: </span><span class="hl-14">#140f24</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<p><code>theme=&quot;tinted&quot;</code> mixes a little brand into the surface, gridline and muted-text values in effect, including any you set. Its row separators are the brand alone, so a tinted grid ignores <code>--ag-border</code> and <code>--ag-dark-border</code>.</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>
+<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">theme</span><span class="hl-1">~=</span><span class="hl-3">&#39;dark&#39;</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-dark-shadow-card</span><span class="hl-1">); } </span><span class="hl-15">/* the same, for dark grids */</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 in an Ignite UI app, the brand tokens automatically re-tint from its palette: they read <code>--ig-primary-500</code> with the grid's own default as the fallback. That is a plain CSS variable lookup, so the grid neither depends on nor bundles Ignite UI.</p>
+<p>If you embed the grid in an Ignite UI app, the brand tokens automatically re-tint from its palette, wherever it is declared: they read <code>--ig-primary-500</code> with the grid's own default as the fallback. That is a plain CSS variable lookup, so the grid neither depends on nor bundles Ignite UI.</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>
@@ -118,6 +132,9 @@
 </tr>
 </tbody>
 </table>
+<div class="tsd-alert tsd-alert-note"><div class="tsd-alert-title"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><use href="assets/icons.svg#icon-alertNote"></use></svg><span>Note</span></div><p>
+Rows whose text wraps change height while the grid resizes or scrolls, and the browser can defer the resulting row layout by one frame. It reports each deferral as a window <code>error</code> event with the message &quot;ResizeObserver loop completed with undelivered notifications&quot; (older browsers say &quot;ResizeObserver loop limit exceeded&quot;). The event is benign, so the first grid to connect adds one window <code>error</code> listener that cancels any message containing &quot;ResizeObserver loop&quot; (Safari then stops logging it) and stops the listeners added after it from seeing it. Every other error passes through untouched. Listeners added before the first grid connects, such as error monitoring set up at page start, still receive it, and the same message raised by your own code is quieted as well, since the browser does not say which observer raised it.</p>
+</div>
 <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>
@@ -142,11 +159,19 @@
 <pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">pagination</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-2">pageSize:</span><span class="hl-1"> </span><span class="hl-8">25</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">pageSizeOptions:</span><span class="hl-1"> [</span><span class="hl-8">10</span><span class="hl-1">, </span><span class="hl-8">25</span><span class="hl-1">, </span><span class="hl-8">50</span><span class="hl-1">, </span><span class="hl-8">100</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">gotoPage</span><span class="hl-1">(</span><span class="hl-8">2</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">setPageSize</span><span class="hl-1">(</span><span class="hl-8">50</span><span class="hl-1">);</span><br/><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">nextPage</span><span class="hl-1">(); </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">previousPage</span><span class="hl-1">(); </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">firstPage</span><span class="hl-1">(); </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">lastPage</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
 
-<p>Remote mode:</p>
+<p>The paginator never clips its controls: on a narrow grid it drops the page size select first, then the first and last buttons, so previous and next stay reachable. <code>paginator: 'compact'</code> always uses that narrow layout (&quot;start-end of total&quot;, previous, &quot;page / count&quot;, next), for example in a small dashboard tile:</p>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">pagination</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">pageSize:</span><span class="hl-1"> </span><span class="hl-8">5</span><span class="hl-1">, </span><span class="hl-2">paginator:</span><span class="hl-1"> </span><span class="hl-3">&#39;compact&#39;</span><span class="hl-1"> };</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Style it through the grid with <code>apex-grid::part(...)</code>: <code>paginator-host</code> (the element), <code>paginator</code>, <code>paginator-size</code>, <code>paginator-info</code>, <code>paginator-controls</code>, <code>paginator-page</code>, and <code>paginator-button</code> on each button, which also carries <code>paginator-first</code>, <code>paginator-prev</code>, <code>paginator-next</code> or <code>paginator-last</code>:</p>
+<pre><code class="css"><span class="hl-10">apex-grid</span><span class="hl-1">::part(</span><span class="hl-10">paginator-first</span><span class="hl-1">),</span><br/><span class="hl-10">apex-grid</span><span class="hl-1">::part(</span><span class="hl-10">paginator-last</span><span class="hl-1">) { </span><span class="hl-12">display</span><span class="hl-1">: </span><span class="hl-14">none</span><span class="hl-1">; }</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Remote mode: the grid does not slice <code>data</code>, it renders whatever <code>data</code> holds as the current page. Fetch the page on <code>pageChanged</code>, and keep <code>pagination.totalItems</code> at the number of rows the server holds for the current filter (update it when a server side filter changes that number), so the paginator can count the pages:</p>
 <pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">pagination</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;remote&#39;</span><span class="hl-1">, </span><span class="hl-2">pageSize:</span><span class="hl-1"> </span><span class="hl-8">25</span><span class="hl-1">, </span><span class="hl-2">totalItems:</span><span class="hl-1"> </span><span class="hl-8">1280</span><span class="hl-1"> };</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;pageChanged&#39;</span><span class="hl-1">, </span><span class="hl-5">async</span><span class="hl-1"> (</span><span class="hl-2">e</span><span class="hl-1">) </span><span class="hl-5">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">data</span><span class="hl-1"> = </span><span class="hl-0">await</span><span class="hl-1"> </span><span class="hl-4">fetchPage</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">page</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">pageSize</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
-<p>Properties: <code>page</code>, <code>pageSize</code>, <code>pageCount</code>, <code>totalItems</code>, <code>pageItems</code>. Events: <code>pageChanging</code> (cancellable), <code>pageChanged</code>.</p>
+<p>Properties: <code>page</code>, <code>pageSize</code>, <code>pageCount</code>, <code>totalItems</code>, <code>pageItems</code>. <code>totalItems</code> is the post-filter, post-sort row count; with pagination enabled it counts the rows paged through, without pinned rows, which show on every page (in remote mode, the <code>pagination.totalItems</code> you supplied), and <code>pageChanged</code> carries the same number in <code>detail.totalItems</code>. Events: <code>pageChanging</code> (cancellable), <code>pageChanged</code>.</p>
 <h3 id="column-pinning" class="tsd-anchor-link">Column pinning<a href="#column-pinning" 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;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>
@@ -167,6 +192,12 @@
 </code><button type="button">Copy</button></pre>
 
 <p>Theme the line with <code>--ag-header-separator</code> (or the <code>--header-separator-color</code> override hook) 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="hiding-the-header" class="tsd-anchor-link">Hiding the header<a href="#hiding-the-header" 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>For a compact table, such as a short dashboard tile, leave out the header rows and give their room to the data rows:</p>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-2">showHeader</span><span class="hl-1"> = </span><span class="hl-5">false</span><span class="hl-1">;                          </span><span class="hl-15">// or &lt;apex-grid show-header=&quot;false&quot;&gt;</span>
+</code><button type="button">Copy</button></pre>
+
+<p>The column header row, the column group row and the filter panel take no space, paint nothing and take no pointer, and the built-in header controls leave the tab order, so resizing, the column menu and drag reorder are unavailable while the header is hidden (an open column menu closes). A focusable control you render in a <code>headerTemplate</code> stays in the tab order: give it <code>tabindex=&quot;-1&quot;</code> while the header is hidden. The column header row stays in the accessibility tree, so screen readers still announce the column names, and <code>aria-rowcount</code> and <code>aria-rowindex</code> do not change. Sort, filter, column widths and the current page are kept and come back unchanged with <code>grid.showHeader = true</code>. Attribute: <code>show-header</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>
@@ -190,6 +221,12 @@ re-renders. The returned tally splits <code>applied</code> from <code>unchanged<
 <code>cancelled</code>, and <code>skipped</code>, so a rejected batch is distinguishable from a no-op
 one. Edits naming a row out of range or a column the user could not edit either
 are skipped rather than throwing.</p>
+<p><code>rowIndex</code> is view-relative, so it reaches the current page only. To edit rows
+anywhere (other pages, pinned rows, rows under a collapsed tree parent), name
+the record itself with <code>row</code>:</p>
+<pre><code class="ts"><span class="hl-2">grid</span><span class="hl-1">.</span><span class="hl-4">applyEdits</span><span class="hl-1">(</span><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-4">map</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">column:</span><span class="hl-1"> </span><span class="hl-3">&#39;discount&#39;</span><span class="hl-1">, </span><span class="hl-2">value:</span><span class="hl-1"> </span><span class="hl-8">0</span><span class="hl-1"> })));</span>
+</code><button type="button">Copy</button></pre>
+
 <h3 id="keyboard-navigation-and-accessibility" class="tsd-anchor-link">Keyboard navigation and accessibility<a href="#keyboard-navigation-and-accessibility" 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 body is a single tab stop: Tab enters the grid, and the active cell
 holds real focus (a roving tabindex), so screen readers follow the cursor as
@@ -244,15 +281,27 @@ it moves. Keys, with editing enabled where relevant:</p>
 continues from where you were. Sorting, filtering, selection, paging, row
 pinning, reorder, expansion, and undo / redo are announced through a polite
 live region, and every announcement and control label is localizable (the
-<code>announce.*</code> and <code>header.*</code> locale keys). The host gets a localized
-<code>aria-label</code> (&quot;Data grid&quot;) unless you provide <code>aria-label</code> /
-<code>aria-labelledby</code> yourself.</p>
+<code>announce.*</code> and <code>header.*</code> locale keys).</p>
+<p>The <code>grid</code> role (<code>treegrid</code> for tree data, master-detail and other expandable
+rows), <code>aria-rowcount</code>, <code>aria-colcount</code> and <code>aria-multiselectable</code> sit on the
+element exposed as <code>part=&quot;table&quot;</code> inside the shadow root, not on the
+<code>&lt;apex-grid&gt;</code> host. It holds only the header rows and the body, so the toolbar,
+paginator and live region around it are not read as table content. It gets a
+localized <code>aria-label</code> (&quot;Data grid&quot;) unless you put <code>aria-label</code> or
+<code>aria-labelledby</code> on the host, which then names it. An <code>aria-describedby</code> on
+the host becomes its description. The references are resolved when the grid
+renders, so if you add the referenced element later (a heading shown
+conditionally), set the attribute again afterwards to pick it up.</p>
+<blockquote>
+<p>Changed in 4.0.0: the role and the row and column counts used to be on the
+host. Query <code>grid.shadowRoot.querySelector('[part~=&quot;table&quot;]')</code> instead.</p>
+</blockquote>
 <blockquote>
 <p>Changed in 3.4.0: Home / End used to jump to the first / last row; they now
 stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.</p>
 </blockquote>
 <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>
+<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-17">/</span><span class="hl-18">^</span><span class="hl-19">[^</span><span class="hl-17">@\s</span><span class="hl-19">]</span><span class="hl-20">+</span><span class="hl-17">@</span><span class="hl-19">[^</span><span class="hl-17">@\s</span><span class="hl-19">]</span><span class="hl-20">+</span><span class="hl-18">$</span><span class="hl-17">/</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>
@@ -265,17 +314,18 @@ stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.</p>
 <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>Every row is selectable by default, pinned rows included. <code>selection.isRowSelectable: (row) =&gt; boolean</code> keeps rows out of the selection (a pinned total row, for example): such a row renders no checkbox and no <code>aria-selected</code>, every selection path skips it (clicks, Space, Select all, <code>selectRow</code>, <code>selectedRows = ...</code>, <code>setState</code>), and the header checkbox counts only selectable rows. Reassigning <code>selection</code> or <code>data</code> drops selected rows the predicate now rejects; a selected row it comes to reject otherwise (pinned or edited in place) keeps its checkbox until deselected.</p>
 <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>
+<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. Replacing <code>grid.data</code> carries the pins onto the new rows (by <code>rowId</code> when set, else a pin whose row left the data is dropped). While <code>rowPinning.enabled</code> is false the pinned rows return to the body and <code>pinnedRows</code> reports none, but the pins are kept (<code>getState</code> still saves them) and re-enabling brings them back. 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>
+<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, and a move clears the sort). Rows hidden by a filter keep their place when a visible row moves, and the order follows <code>grid.data</code> when it is replaced (by <code>rowId</code> when set). 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, position, toIndex, data }</code>, where <code>toIndex</code> is the view index the row lands at.</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>
@@ -286,7 +336,7 @@ stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.</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>
+<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 grid's <code>part=&quot;table&quot;</code> element advertises <code>role=&quot;treegrid&quot;</code>.</p>
 <h3 id="csv-export" class="tsd-anchor-link">CSV export<a href="#csv-export" 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>Programmatic:</p>
 <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>
@@ -302,7 +352,7 @@ stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.</p>
 
 <p>Renders a download icon in the toolbar's trailing actions area; the menu has an &quot;Export CSV&quot; entry (the enterprise grid adds &quot;Export XLSX&quot;). Toolbar <code>exportFilename</code> overrides the default <code>data</code> filename. Attribute: <code>show-export</code>.</p>
 <h3 id="toolbar" class="tsd-anchor-link">Toolbar<a href="#toolbar" 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>Rendered automatically above the header row when at least one of <code>show-quick-filter</code> or <code>show-export</code> is on. CSS parts:</p>
+<p>Rendered automatically above the header row when at least one of <code>show-quick-filter</code> or <code>show-export</code> is on. The grid re-exports its CSS parts, so <code>apex-grid::part(name)</code> reaches them:</p>
 <table>
 <thead>
 <tr>
@@ -312,6 +362,10 @@ stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.</p>
 </thead>
 <tbody>
 <tr>
+<td><code>toolbar-host</code></td>
+<td>The <code>&lt;apex-grid-toolbar&gt;</code> element</td>
+</tr>
+<tr>
 <td><code>toolbar</code></td>
 <td>Root container</td>
 </tr>
@@ -332,8 +386,16 @@ stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.</p>
 <td>Trailing actions area</td>
 </tr>
 <tr>
-<td><code>export-trigger</code></td>
-<td>Export menu button</td>
+<td><code>toolbar-action</code></td>
+<td>A host-contributed action button</td>
+</tr>
+<tr>
+<td><code>export</code></td>
+<td>Export menu wrapper</td>
+</tr>
+<tr>
+<td><code>export-trigger</code>, <code>export-icon</code>, <code>export-caret</code></td>
+<td>Export menu button and its icons</td>
 </tr>
 <tr>
 <td><code>export-menu</code></td>
@@ -347,9 +409,52 @@ stay within the row. Use Ctrl/Cmd+Home / Ctrl/Cmd+End for the grid corners.</p>
 </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. Where an Ignite UI palette is present, the brand tokens auto-tint from <code>--ig-primary-500</code>.</p>
+<p>The grid styles itself through <code>--ag-*</code> CSS custom properties; override them on <code>apex-grid</code> or any ancestor (shadow hosts included) to rebrand, and use <code>--ag-dark-*</code> for dark grids. See <a href="#3-optional-customize-the-look">Customize the look</a> and <a href="media/_token-values.scss"><code>src/styles/_token-values.scss</code></a> for the full list. Where an Ignite UI palette is present, the brand tokens auto-tint from <code>--ig-primary-500</code>.</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>
+<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</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>
+
+<p>Body rows re-export these parts, so <code>apex-grid::part(name)</code> reaches them:</p>
+<table>
+<thead>
+<tr>
+<th>Part</th>
+<th>What</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>cell</code></td>
+<td>A data cell</td>
+</tr>
+<tr>
+<td><code>selection-cell</code>, <code>selection-checkbox</code></td>
+<td>Selection column cell and its checkbox</td>
+</tr>
+<tr>
+<td><code>expansion-cell</code>, <code>expansion-toggle</code>, <code>expansion-chevron</code></td>
+<td>Expansion column cell, its button and the chevron icon</td>
+</tr>
+<tr>
+<td><code>detail-panel</code></td>
+<td>Expanded detail panel container</td>
+</tr>
+<tr>
+<td><code>row-number-cell</code>, <code>row-number</code></td>
+<td>Row-number gutter cell and its label (<code>coordinateHints</code>)</td>
+</tr>
+<tr>
+<td><code>reorder-handle-cell</code>, <code>reorder-handle</code>, <code>reorder-grip</code></td>
+<td>Row-reorder grip cell, handle and icon (handle mode)</td>
+</tr>
+<tr>
+<td><code>group-row</code></td>
+<td>Default container of a row a feature module renders full width</td>
+</tr>
+</tbody>
+</table>
+<p>Parts used inside your own <code>detailTemplate</code> content are re-exported when you list them in <code>expansion.exportParts</code>:</p>
+<pre><code class="js"><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-2">exportParts:</span><span class="hl-1"> [</span><span class="hl-3">&#39;order-summary&#39;</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;div part=&quot;order-summary&quot;&gt;</span><span class="hl-5">${</span><span class="hl-2">data</span><span class="hl-11">.</span><span class="hl-2">total</span><span class="hl-5">}</span><span class="hl-3">&lt;/div&gt;`</span><span class="hl-1">,</span><br/><span class="hl-1">};</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="right-to-left" class="tsd-anchor-link">Right-to-left<a href="#right-to-left" 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>
@@ -375,6 +480,22 @@ on the side the cursor actually crossed.</p>
 </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="row-recycling" class="tsd-anchor-link">Row recycling<a href="#row-recycling" 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">rowRecycling</span><span class="hl-1"> = </span><span class="hl-5">false</span><span class="hl-1">; </span><span class="hl-15">// opt out</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">row-recycling</span><span class="hl-1">=</span><span class="hl-13">&quot;false&quot;</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>On by default. A scroll, sort or filter re-binds the rendered body rows to the records now in view instead of building new rows, which makes long jumps and sorts cheaper on large grids. A row element, and its cells, then shows another record later, so cell and editor templates follow these rules:</p>
+<ul>
+<li>Derive everything a template renders from its context on each render, and keep no state in the elements it creates.</li>
+<li>Read <code>ctx.data</code> for the record, also after an <code>await</code>. <code>ctx.row</code> and <code>ctx.parent</code> are row and cell elements that may show another record by then, so do not hold them across an <code>await</code>.</li>
+<li>Wrap a template that has to keep element state in <code>keyed(ctx.data, ...)</code> from <code>lit/directives/keyed.js</code>. The state then never shows on the wrong record, but it is rebuilt every time the row shows another record, including after a sort or <code>moveRow</code>.</li>
+<li>Code that holds <code>grid.rows</code> elements across a scroll or a sort should read each element's <code>data</code> again rather than assume it still shows the same record.</li>
+</ul>
+<p>Set <code>rowRecycling</code> to <code>false</code> (or the <code>row-recycling=&quot;false&quot;</code> attribute) to restore record-keyed rows, where each row element stays with its record. Do that for templates that must keep element state across a sort or a move, such as some third-party widgets.</p>
+<p>Detail templates are different: their content follows its record into whichever row shows it, and keeps its DOM state (typed text, a nested grid's sort) across a scroll within the rendered rows, a sort or a <code>moveRow</code>, so it needs neither <code>keyed()</code> nor the opt-out. It is rebuilt when the record leaves the rendered rows or is collapsed, as before. <code>ctx.parent</code> in a detail context is the grid itself. A grid created inside a <code>detailTemplate</code> has its own <code>rowRecycling</code> setting, so set it there too when you opt out.</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>
@@ -425,7 +546,7 @@ on the side the cursor actually crossed.</p>
 <td><code>dataPipelineConfiguration</code></td>
 <td><code>DataPipelineConfiguration&lt;T&gt;</code></td>
 <td></td>
-<td>Custom sort/filter/pagination hooks</td>
+<td>Custom sort, filter and quick filter hooks</td>
 </tr>
 <tr>
 <td><code>pagination</code></td>
@@ -512,6 +633,18 @@ on the side the cursor actually crossed.</p>
 <td>Show the always-visible column-menu (kebab) button on headers; <code>false</code> hides it</td>
 </tr>
 <tr>
+<td><code>showHeader</code></td>
+<td><code>boolean</code></td>
+<td><code>true</code></td>
+<td><code>false</code> hides the header rows (kept for screen readers). Attr <code>show-header=&quot;false&quot;</code></td>
+</tr>
+<tr>
+<td><code>rowRecycling</code></td>
+<td><code>boolean</code></td>
+<td><code>true</code></td>
+<td>Re-binds body row elements across records on scroll, sort and filter; <code>false</code> restores record-keyed rows. See <a href="#row-recycling">Row recycling</a>. Attr <code>row-recycling=&quot;false&quot;</code></td>
+</tr>
+<tr>
 <td><code>rowId</code></td>
 <td><code>(row: T) =&gt; string | number</code></td>
 <td></td>
@@ -669,7 +802,7 @@ on the side the cursor actually crossed.</p>
 <tr>
 <td><code>rowMoving</code> / <code>rowMoved</code></td>
 <td>yes / no</td>
-<td><code>{ from, to, data }</code></td>
+<td><code>{ from, to, position, toIndex, data }</code></td>
 </tr>
 <tr>
 <td><code>rowExpanding</code> / <code>rowExpanded</code></td>
@@ -690,7 +823,7 @@ on the side the cursor actually crossed.</p>
 </table>
 <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>, <code>coordinate-hints</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>, <code>show-header</code>, <code>row-recycling</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>
@@ -702,11 +835,11 @@ on the side the cursor actually crossed.</p>
 <tbody>
 <tr>
 <td><code>&lt;apex-grid-toolbar&gt;</code></td>
-<td><code>toolbar</code>, <code>toolbar-search</code>, <code>search-field</code>, <code>search-icon</code>, <code>search-input</code>, <code>toolbar-actions</code>, <code>export-trigger</code>, <code>export-menu</code>, <code>export-menu-item</code></td>
+<td><code>toolbar</code>, <code>toolbar-search</code>, <code>search-field</code>, <code>search-icon</code>, <code>search-input</code>, <code>toolbar-actions</code>, <code>toolbar-action</code>, <code>export</code>, <code>export-trigger</code>, <code>export-icon</code>, <code>export-caret</code>, <code>export-menu</code>, <code>export-menu-item</code> (re-exported by the grid, which names the element <code>toolbar-host</code>)</td>
 </tr>
 <tr>
 <td><code>&lt;apex-grid-paginator&gt;</code></td>
-<td><code>paginator</code>, <code>paginator-size</code>, <code>paginator-info</code>, <code>paginator-controls</code>, <code>paginator-page</code></td>
+<td><code>paginator</code>, <code>paginator-size</code>, <code>paginator-info</code>, <code>paginator-controls</code>, <code>paginator-page</code>, <code>paginator-button</code>, <code>paginator-first</code>, <code>paginator-prev</code>, <code>paginator-next</code>, <code>paginator-last</code> (re-exported by the grid, which names the element <code>paginator-host</code>)</td>
 </tr>
 <tr>
 <td><code>&lt;apex-grid-cell&gt;</code></td>
@@ -762,5 +895,5 @@ on the side the cursor actually crossed.</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="#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="#keyboard-navigation-and-accessibility"><span>Keyboard navigation and accessibility</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="#right-to-left"><span>Right-<wbr/>to-<wbr/>left</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>
+<p>See <a href="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="#column-separators"><span>Column separators</span></a></li><li><a href="#hiding-the-header"><span>Hiding the header</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="#keyboard-navigation-and-accessibility"><span>Keyboard navigation and accessibility</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="#right-to-left"><span>Right-<wbr/>to-<wbr/>left</span></a></li><li><a href="#spreadsheet-coordinates"><span>Spreadsheet coordinates</span></a></li><li><a href="#row-recycling"><span>Row recycling</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>