@toclocoinc/lattice-grid 1.44.1 → 1.45.0

package/README.md

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

package/docs/API.html

@@ -880,6 +880,7 @@ autoInit(document); <span class="cmt">// builds every [data-lattice-grid] under
           <tr><td class="name">responsive</td><td class="type">{ maxWidth, template, rowHeight }</td><td class="dflt">, </td><td class="desc">Collapse to cards when the <em>container</em> is at or below <code>maxWidth</code> (640 by default), and return to a table above it. Sorting, filtering and export keep working. Emits <code>presentation:changed</code>. See <a href="api-detail.html#cards">Cards, lists and feeds</a>.</td></tr>
           <tr><td class="name">rowForm</td><td class="type">boolean | { mode, load, fields, title, width, trigger, timeout, container }</td><td class="dflt">, </td><td class="desc">Open a row for editing on a form. <code>mode: 'drawer'</code> (default) or <code>'dialog'</code>; without <code>load</code> the fields are the grid's own columns. A field entry is <code>{ field, label, editor, type, props, lookup }</code>: any editor, including your own. Takes double-click on the row unless <code>trigger: false</code>. A load that has not answered within <code>timeout</code> milliseconds (2000; <code>false</code> waits indefinitely) is reported as a failure with a retry. <code>container</code> builds the form in an element of your own instead of over the grid. See <a href="api-detail.html#row-form">Editing a row on a form</a>.</td></tr>
           <tr><td class="name">showColumnFunctions</td><td class="type">boolean</td><td class="dflt">true</td><td class="desc"><code>false</code> leaves each heading as its label, with no sort, filter or menu control. Those remain reachable through the API, the keyboard and the tool panel.</td></tr>
+          <tr><td class="name">headerControls</td><td class="type">'hover' | 'always' | 'hidden'</td><td class="dflt">'hover'</td><td class="desc">When the per-column header controls &mdash; the sort arrow, the filter funnel and the menu button &mdash; are shown, as a default for every column. <code>'hover'</code> reveals them on hover or keyboard focus (the historical behaviour); <code>'always'</code> keeps them visible; <code>'hidden'</code> draws none of them for a clean read-only heading and leaves them out of the tab order. A column's own <code>headerControls</code> overrides this default for that column. Distinct from <code>showColumnFunctions: false</code>, which also drops the furniture but keeps the functions reachable from the keyboard; <code>'hidden'</code> is the read-only choice.</td></tr>
           <tr><td class="name">significantFigures</td><td class="type">number</td><td class="dflt">, </td><td class="desc">On a unit column, render to this many significant figures rather than a fixed number of decimals, so precision is the same on every rung of the ladder. Rounding is applied before the unit is chosen. Set inside the unit configuration a data type is built from. See <a href="api-detail.html#units">Units</a>.</td></tr>
           <tr><td class="name">typeOptions</td><td class="type">object</td><td class="dflt">, </td><td class="desc">Per-column options a data type reads. <code>ratio</code> and <code>percentRate</code> use <code>{ weight }</code> to name the column their average is weighted by. See <a href="api-detail.html#aggregate-safety">Aggregate safety</a>.</td></tr>
           <tr><td class="name">highlightOnChange</td><td class="type">boolean | string | object</td><td class="desc">Flash a cell when its value changes. <code>{ colour, duration }</code>; <code>duration: 0</code> stays until cleared.</td></tr>
@@ -6977,6 +6978,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">spec</td><td class="type">{ lower?: number; upper?: number; target?: number }</td><td class="desc">The customer's tolerance, for process capability and control charts. Declared here rather than passed to each call so the capability figures, a control chart and any rule marking an out-of-tolerance cell cannot disagree about what the tolerance is. <small>(optional)</small></td></tr>
           <tr><td class="name">layout</td><td class="type">ColumnLayoutSpec | number</td><td class="desc">Width, pinning and flex. A bare number is the width in pixels. <small>(optional)</small></td></tr>
           <tr><td class="name">header</td><td class="type">ColumnHeaderSpec | string</td><td class="desc">The header cell: its text, tooltip, menu and any header chart. <small>(optional)</small></td></tr>
+          <tr><td class="name">headerControls</td><td class="type">'hover' | 'always' | 'hidden'</td><td class="desc">When this column's header controls — its sort arrow, filter funnel and menu button — are shown, overriding the grid-level `headerControls` default for this column alone (BACKLOG-0000982). `'hover'` reveals them on hover or focus, `'always'` keeps them visible, `'hidden'` draws none of them and leaves them out of the tab order. Omitted, the column follows the grid default, which is itself `'hover'`. <small>(optional)</small></td></tr>
           <tr><td class="name">export</td><td class="type">ColumnExportSpec</td><td class="desc">How the column leaves the grid, where that differs from how it is shown. <small>(optional)</small></td></tr>
           <tr><td class="name">allowGroup</td><td class="type">boolean</td><td class="desc">Whether the user may group by this column from the interface. <small>(optional)</small></td></tr>
           <tr><td class="name">allowPivot</td><td class="type">boolean</td><td class="desc">Whether the user may pivot on it. <small>(optional)</small></td></tr>
@@ -8231,6 +8233,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">responsive</td><td class="type">{</td><td class="desc">Present rows as cards when the grid's container is too narrow to be a table honestly, a phone, or a narrow panel on a wide screen. Measured on the container, not the viewport, so a grid in a sidebar collapses and a grid filling a small tablet does not. Sorting, filtering and export continue to work; the tool panel is where they live when there are no column headings to click. Emits `presentation:changed`. <small>(optional)</small></td></tr>
           <tr><td class="name">rowForm</td><td class="type">boolean | {</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">showColumnFunctions</td><td class="type">boolean</td><td class="desc">Draw the sort, filter and menu controls in the column headings. `true` by default. `false` leaves each heading as its label alone, which is what a dense grid wants: three affordances take roughly fifty pixels, and on an eighty-pixel column that leaves the heading nothing and the label disappears entirely. Only the furniture goes. Sorting, filtering and the column menu are still reachable through the API, the keyboard and the tool panel. <small>(optional)</small></td></tr>
+          <tr><td class="name">headerControls</td><td class="type">'hover' | 'always' | 'hidden'</td><td class="desc">When the per-column header controls — the sort arrow, the filter funnel and the menu button — are shown, as a default for every column (BACKLOG-0000982). - `'hover'` (the default) reveals them when the heading is hovered or a keyboard user focuses into it, which is the historical behaviour: a wide header does not read as a row of identical icons. - `'always'` keeps them visible unconditionally, for a grid where the controls are the point and the discoverability of hover is not wanted. - `'hidden'` draws none of them, for a clean read-only heading; they leave the tab order with the elements that carried them. An active filter and a live sort are still reflected by the heading's state attributes, but no control furniture is built. A column's own `headerControls` overrides this default for that column. Distinct from `showColumnFunctions: false`, which also drops the furniture but keeps sorting, filtering and the menu reachable from the keyboard; `'hidden'` is the read-only choice that removes them outright. <small>(optional)</small></td></tr>
           <tr><td class="name">rowHeight</td><td class="type">number | ((row: Row) =&gt; number)</td><td class="desc">Row height in pixels, or a function of the row. A function makes the grid measure rather than assume, which costs a pass over what is on screen: worth it for wrapped text, wasteful for a uniform grid. <small>(optional)</small></td></tr>
           <tr><td class="name">title</td><td class="type">string</td><td class="desc">A caption for the grid, drawn above the column headings. Inside the grid rather than an element the host places above it: a title outside does not scroll with the grid, is not in the region a screen reader announces, and is left behind by image capture and print. <small>(optional)</small></td></tr>
           <tr><td class="name">showHeader</td><td class="type">boolean</td><td class="desc">Draw the column headings at all. `true` by default. `false` removes the row, and removes it from the accessibility tree rather than only from view, a heading a screen reader still announces is invisible, not hidden. What a small dashboard tile wants when its `title` already says what the panel is. Distinct from `showColumnFunctions`, which keeps the headings and drops only the sort, filter and menu controls inside them. <small>(optional)</small></td></tr>

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.44.1</p>
+    <p class="rail__sub">Developer guide · v1.45.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -2194,6 +2194,49 @@ grid.destroy();
       reporting a value it is unsure of.
     </p>
 
+    <h3 id="header-controls">headerControls</h3>
+    <p class="lead-in">
+      The per-column header controls &mdash; the sort arrow, the filter funnel and the menu button
+      &mdash; appear on hover by default, which keeps a wide header from reading as a row of identical
+      icons. <code>headerControls</code> makes that a mode: <code>'hover'</code> (the default,
+      unchanged), <code>'always'</code> to keep them visible, and <code>'hidden'</code> for a clean
+      read-only heading that draws none of them and leaves them out of the tab order. It is a
+      grid-level default; a column's own <code>headerControls</code> overrides it for that column.
+    </p>
+    <p class="lead-in">
+      Each leaf heading carries the resolved mode as <code>data-controls</code>, and the theme keys
+      the reveal off it, so <code>'always'</code> shows the controls without a hover and
+      <code>'hidden'</code> removes them from the layout. This differs from
+      <code>showColumnFunctions: false</code>, which also drops the furniture but keeps sorting,
+      filtering and the menu reachable from the keyboard; <code>'hidden'</code> is the read-only
+      choice that takes them away outright (BACKLOG-0000982).
+    </p>
+    <div class="example">
+      <p class="example__label">A grid that hides its controls by default, with one column that keeps them</p>
+      <pre data-run="js" data-expect="1" data-covers="config:headerControls"><code><span class="kw">const</span> { createHeadlessGrid } = <span class="kw">await</span> import('../packages/core/src/index.js');
+
+<span class="kw">const</span> grid = createHeadlessGrid({
+  headerControls: 'hidden',                       <span class="cmt">// the read-only default for every column</span>
+  columns: [
+    { field: 'name' },                            <span class="cmt">// follows the default: hidden</span>
+    { field: 'region', headerControls: 'always' }, <span class="cmt">// this column overrides the default</span>
+    { field: 'qty', type: 'number' },             <span class="cmt">// follows the default: hidden</span>
+  ],
+  rows: [{ name: 'a', region: 'x', qty: 1 }],
+  rowKey: 'name',
+});
+
+<span class="cmt">// Resolve each column the way the header renderer does: its own value wins,</span>
+<span class="cmt">// then the grid default. Only the overriding column shows its controls.</span>
+<span class="kw">function</span> shown(id) {
+  <span class="kw">const</span> own = grid.columns.get(id).def.headerControls;
+  <span class="kw">return</span> (own || 'hidden') !== 'hidden';
+}
+<span class="kw">const</span> visible = ['name', 'region', 'qty'].filter(shown).length;
+grid.destroy();
+<span class="kw">return</span> visible;</code></pre>
+    </div>
+
     <h3 id="show-total-in-header">showTotalInHeader</h3>
     <p class="lead-in">
       Under grouping or pivot, a totalled column's cells hold an aggregate rather than a row's own

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.44.1, type declarations
+ * Lattice Grid 1.45.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -823,6 +823,15 @@ export interface Column {
   layout?: ColumnLayoutSpec | number;
   /** The header cell: its text, tooltip, menu and any header chart. */
   header?: ColumnHeaderSpec | string;
+  /**
+   * When this column's header controls — its sort arrow, filter funnel and menu
+   * button — are shown, overriding the grid-level `headerControls` default for
+   * this column alone (BACKLOG-0000982). `'hover'` reveals them on hover or
+   * focus, `'always'` keeps them visible, `'hidden'` draws none of them and
+   * leaves them out of the tab order. Omitted, the column follows the grid
+   * default, which is itself `'hover'`.
+   */
+  headerControls?: 'hover' | 'always' | 'hidden';
   /** How the column leaves the grid, where that differs from how it is shown. */
   export?: ColumnExportSpec;
   /** Whether the user may group by this column from the interface. */
@@ -1733,6 +1742,26 @@ export interface GridConfig {
    * reachable through the API, the keyboard and the tool panel.
    */
   showColumnFunctions?: boolean;
+  /**
+   * When the per-column header controls — the sort arrow, the filter funnel and
+   * the menu button — are shown, as a default for every column (BACKLOG-0000982).
+   *
+   * - `'hover'` (the default) reveals them when the heading is hovered or a
+   *   keyboard user focuses into it, which is the historical behaviour: a wide
+   *   header does not read as a row of identical icons.
+   * - `'always'` keeps them visible unconditionally, for a grid where the
+   *   controls are the point and the discoverability of hover is not wanted.
+   * - `'hidden'` draws none of them, for a clean read-only heading; they leave
+   *   the tab order with the elements that carried them. An active filter and a
+   *   live sort are still reflected by the heading's state attributes, but no
+   *   control furniture is built.
+   *
+   * A column's own `headerControls` overrides this default for that column.
+   * Distinct from `showColumnFunctions: false`, which also drops the furniture
+   * but keeps sorting, filtering and the menu reachable from the keyboard;
+   * `'hidden'` is the read-only choice that removes them outright.
+   */
+  headerControls?: 'hover' | 'always' | 'hidden';
   /**
    * Row height in pixels, or a function of the row. A function makes the
    * grid measure rather than assume, which costs a pass over what is on