@toclocoinc/lattice-grid 1.45.0 → 1.46.1

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.45.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.46.1 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/docs/API.html

@@ -872,6 +872,8 @@ autoInit(document); <span class="cmt">// builds every [data-lattice-grid] under
           <tr><td class="name">gridLines</td><td class="type">boolean | 'both' | 'horizontal' | 'vertical' | 'none'</td><td class="dflt">'horizontal'</td><td class="desc">Which rules are drawn between cells. Horizontal is what the grid has always drawn; vertical rules are additive. <code>'rows'</code> and <code>'columns'</code> are accepted aliases. Only the rules between data are affected, the header underline and pinned seams are structure.</td></tr>
           <tr><td class="name">cornerRadius</td><td class="type">boolean | number | string</td><td class="dflt">, </td><td class="desc">Round the grid's outer corners. <code>true</code> adopts the theme's radius, a number is pixels, a string is used as written.</td></tr>
           <tr><td class="name">stripedRows</td><td class="type">boolean</td><td class="dflt">false</td><td class="desc">Shade alternate data rows (zebra striping). Strictly opt-in, so an existing grid is unchanged on upgrade. Parity follows each row's logical index, so a stripe survives a scroll; group headings, footers and the grand total are never striped; selection and hover still win. Uses the theme's <code>--lattice-surface-alt</code>, so dark, high-contrast and terminal come for free.</td></tr>
+          <tr><td class="name">verticalAlign</td><td class="type">'top' | 'middle' | 'bottom'</td><td class="dflt">, </td><td class="desc">Vertical alignment of cell content within a row, as a default for every column &mdash; the vertical counterpart to the per-column <code>align</code>. A column's own <code>verticalAlign</code> (or <code>cell.verticalAlign</code>) overrides it. Omitted, the grid keeps its historical placement (centred in a fixed-height row, top in an <code>autoHeight</code> row), so an existing grid is unchanged on upgrade. Setting a value aligns every column uniformly, including auto-height rows, unless a column opts out. See <a href="api-detail.html#vertical-align">Vertical alignment</a>.</td></tr>
+          <tr><td class="name">scrollbars</td><td class="type">'auto' | 'always' | { x, y }</td><td class="dflt">'auto'</td><td class="desc">Keep the scroll viewport's scrollbars visible. <code>'auto'</code> is the platform's native behaviour, where overlay scrollbars fade when idle; <code>'always'</code> keeps both axes shown whether or not the pointer is over the grid. The object form <code>{ x, y }</code> pins each axis on its own, so <code>{ y: 'always' }</code> keeps the vertical bar while the horizontal one stays native. Omitted, the grid is unchanged on upgrade. See <a href="api-detail.html#scrollbars">Always-visible scrollbars</a>.</td></tr>
           <tr><td class="name">columnTagFilter</td><td class="type">boolean | { multiple, label }</td><td class="dflt">, </td><td class="desc">A bar above the headings for showing only the columns carrying a chosen tag. Draws nothing unless some column has <code>tags</code>. See <a href="api-detail.html#column-tags">Column tags</a>.</td></tr>
           <tr><td class="name">rowTemplate</td><td class="type">string | { template, cardsPerRow, maxCardWidth, gap, className, role, itemRole }</td><td class="dflt">, </td><td class="desc">Draw each row with a template instead of dividing it into columns, a card list, a feed, a search-result list. Compiles once; binds with <code>{{data.field}}</code>. <code>cardsPerRow</code> or <code>maxCardWidth</code> puts several on a line. The pipeline underneath is unchanged. See <a href="api-detail.html#cards">Cards, lists and feeds</a>.</td></tr>
           <tr><td class="name">gallery</td><td class="type">boolean | { template, tileWidth, tileHeight, cardsPerRow, gap, className, role, itemRole }</td><td class="dflt">, </td><td class="desc">Present rows as a gallery of tiles, laid out by the same 2-D virtualisation the grid runs. <code>true</code> generates a tile per row from the columns; <code>tileWidth</code> sizes them and the count across follows the container, or <code>cardsPerRow</code> fixes it. Presentation only &mdash; sort, filter, group and export are unchanged. See <a href="api-detail.html#cards">Cards, lists and feeds</a>.</td></tr>
@@ -6979,6 +6981,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <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">verticalAlign</td><td class="type">VAlign</td><td class="desc">Vertical alignment of this column's cell content within the row (BACKLOG-0000989). Overrides the grid-level `verticalAlign` for this column alone; `top`, `middle` or `bottom`. Also accepted as `cell.verticalAlign`, the way `align` is. Omitted, the column follows the grid default. <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>
@@ -7003,6 +7006,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">style</td><td class="type">CellStyle | ((p: CellParams) =&gt; CellStyle)</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">tooltip</td><td class="type">string | ((p: CellParams) =&gt; string)</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">align</td><td class="type">Align</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">verticalAlign</td><td class="type">VAlign</td><td class="desc">Vertical alignment of this column's cell content, overriding the grid-level `verticalAlign` for this column alone (BACKLOG-0000989). Accepted at the top level of the column too, as `align` is. <small>(optional)</small></td></tr>
           <tr><td class="name">wrap</td><td class="type">boolean</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">autoHeight</td><td class="type">boolean</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">flash</td><td class="type">boolean</td><td class="desc"><small>(optional)</small></td></tr>
@@ -8222,6 +8226,8 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">gridLines</td><td class="type">boolean | 'both' | 'horizontal' | 'vertical' | 'none' | 'rows' | 'columns'</td><td class="desc">Which rules are drawn between cells. `'both'` by default. The two axes are separate decisions: horizontal rules help the eye track along a row, vertical ones stop adjacent values running together. `false` or `'none'` draws neither. Only the rules *between data* are affected, the header's underline, the pinned seams and the totals separator are structure, not grid lines. <small>(optional)</small></td></tr>
           <tr><td class="name">cornerRadius</td><td class="type">boolean | number | string</td><td class="desc">Round the grid's outer corners. Square by default. `true` adopts the theme's own radius; a number is pixels; a string is used as written, so a host can pass its own token or a relative unit. <small>(optional)</small></td></tr>
           <tr><td class="name">stripedRows</td><td class="type">boolean</td><td class="desc">Shade alternate data rows (zebra striping). Off by default, and strictly opt-in: an existing grid must look exactly the same on upgrade. When `true`, every other data row takes the theme's `--lattice-surface-alt` background, which every palette already defines, so dark, high-contrast and terminal stripe correctly without extra work. Parity follows the row's *logical* index, not its position in the DOM, so a row keeps its stripe across a scroll even though the rows are recycled. Structural rows — group headings, group footers and the grand total — are never striped, and both selection and hover still win over the stripe. <small>(optional)</small></td></tr>
+          <tr><td class="name">verticalAlign</td><td class="type">VAlign</td><td class="desc">Vertical alignment of cell content within a row, as a default for every column (BACKLOG-0000989). `top`, `middle` or `bottom`; a column's own `verticalAlign` overrides it for that column. The horizontal counterpart is the per-column `align`. Omitted, the grid keeps its historical placement — content centred in a fixed-height row and top-aligned in an `autoHeight` row — so an existing grid is unchanged on upgrade. Setting a value aligns every column uniformly, including `autoHeight` rows, unless a column opts out. <small>(optional)</small></td></tr>
+          <tr><td class="name">scrollbars</td><td class="type">ScrollbarMode | { x?: ScrollbarMode; y?: ScrollbarMode }</td><td class="desc">Keep the scroll viewport's scrollbars visible (BACKLOG-0000990). `'auto'` (the default) is the platform's native behaviour, where overlay scrollbars fade when idle. `'always'` keeps both axes shown whether or not the pointer is over the grid. The object form controls each axis on its own — `{ y: 'always' }` pins the vertical bar while the horizontal one stays native. Omitted, the grid is unchanged on upgrade. <small>(optional)</small></td></tr>
           <tr><td class="name">columnTagFilter</td><td class="type">boolean | { multiple?: boolean; label?: string }</td><td class="desc">Show a bar above the column headings for filtering columns by tag. Off by default, and it draws nothing unless some column carries a `tags` entry. `multiple: true` lets more than one tag be chosen at once. Only tagged columns are ever hidden, so an untagged account or total column stays visible whatever is selected. <small>(optional)</small></td></tr>
           <tr><td class="name">anomalySummary</td><td class="type">boolean | { column?: string; label?: string }</td><td class="desc">Show a small chip in the grid chrome that reads how many rows an anomaly shadow column has flagged, and filters the grid to exactly those when it is clicked (BACKLOG-0000799). Off by default, and it draws nothing unless a column declares a `shadow: { kind: 'anomalyFlag' }`. The count and the filter both read that one shadow column, so the number on the chip is the number of rows the click reveals. `column` names the base column to summarise when more than one anomaly-flag shadow is present; `label` overrides the chip's wording. <small>(optional)</small></td></tr>
           <tr><td class="name">typeOptions</td><td class="type">Record&lt;string, {</td><td class="desc">Per-column options a data type reads. `ratio` and `percentRate` use `{ weight }` to name the column their average is weighted by. A unit type reads `{ significantFigures }` to render to a fixed precision rather than a fixed number of decimals. <small>(optional)</small></td></tr>
@@ -9331,6 +9337,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">dataType</td><td class="type">DataType</td><td class="desc"></td></tr>
           <tr><td class="name">nullable</td><td class="type">boolean</td><td class="desc"></td></tr>
           <tr><td class="name">align</td><td class="type">Align</td><td class="desc"></td></tr>
+          <tr><td class="name">verticalAlign</td><td class="type">VAlign</td><td class="desc">The resolved vertical alignment (BACKLOG-0000989), or `undefined` when neither the column nor the grid set one — in which case the cell keeps the grid's historical vertical placement (centred, or top for `autoHeight`). <small>(optional)</small></td></tr>
           <tr><td class="name">value</td><td class="type">Required&lt;Pick&lt;ColumnValueSpec, 'pure'&gt;&gt; &amp; ColumnValueSpec</td><td class="desc"></td></tr>
           <tr><td class="name">cell</td><td class="type">ColumnCellSpec</td><td class="desc"></td></tr>
           <tr><td class="name">edit</td><td class="type">ColumnEditSpec</td><td class="desc"></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.45.0</p>
+    <p class="rail__sub">Developer guide · v1.46.1</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>
@@ -3512,6 +3512,76 @@ grid.edit.deleteRows();</code></pre>
       both selection and hover still win over it.
     </p>
 
+    <h2 id="vertical-align">Vertical alignment</h2>
+    <p class="lead-in">
+      <code>verticalAlign</code> is the vertical counterpart to the per-column <code>align</code>:
+      where <code>align</code> places cell content across the column (<code>start</code>,
+      <code>center</code>, <code>end</code>), <code>verticalAlign</code> places it down the row &mdash;
+      <code>'top'</code>, <code>'middle'</code> or <code>'bottom'</code>. It is a grid-level default
+      with a per-column override: set it on the grid to align every column, and a column's own
+      <code>verticalAlign</code> (or <code>cell.verticalAlign</code>) wins for that column alone.
+      <code>center</code> and <code>centre</code> are accepted as synonyms for <code>middle</code>,
+      the same leniency <code>align</code> gives the horizontal names.
+    </p>
+    <p class="lead-in">
+      Omitted, the grid keeps the placement it has always had &mdash; content centred in a
+      fixed-height row and top-aligned in an <code>autoHeight</code> row &mdash; so a grid that never
+      mentions it is unchanged on upgrade. Where it earns its keep is a tall or <code>autoHeight</code>
+      grid: a wrapped-text column can sit at the top while its single-line neighbours are
+      <code>middle</code>, rather than every value floating in the middle of a tall row. The value
+      beats the auto-height rule, so a column asked to sit <code>middle</code> does so even when the
+      row is stretched to fit a wrapped sibling (BACKLOG-0000989).
+    </p>
+
+    <div class="example">
+      <p class="example__label">A grid default, with one column overriding it</p>
+      <pre data-run="js" data-expect="middle, bottom" data-covers="config:verticalAlign"><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({
+  verticalAlign: <span class="str">'middle'</span>,                 <span class="cmt">// the default for every column</span>
+  columns: [
+    { field: <span class="str">'name'</span> },                       <span class="cmt">// follows the default: middle</span>
+    { field: <span class="str">'note'</span>, verticalAlign: <span class="str">'bottom'</span> }, <span class="cmt">// this column overrides it</span>
+  ],
+  rows: [{ name: <span class="str">'a'</span>, note: <span class="str">'b'</span> }],
+  rowKey: <span class="str">'name'</span>,
+});
+
+<span class="cmt">// The resolved value the renderer reads for each column.</span>
+<span class="kw">const</span> a = grid.columns.get(<span class="str">'name'</span>).verticalAlign;
+<span class="kw">const</span> b = grid.columns.get(<span class="str">'note'</span>).verticalAlign;
+grid.destroy();
+<span class="kw">return</span> `${a}, ${b}`;</code></pre>
+    </div>
+
+    <h2 id="scrollbars">Always-visible scrollbars</h2>
+    <p class="lead-in">
+      Native scrollbars are overlay bars on most platforms now: they fade away when the pointer is
+      idle, which reads as a cleaner surface but hides the affordance &mdash; a touchpad user has no
+      standing sign that a grid scrolls at all. <code>scrollbars: 'always'</code> keeps them shown
+      whether or not the pointer is over the grid; <code>'auto'</code> (the default) leaves the
+      platform's own behaviour alone, so an existing grid is unchanged on upgrade.
+    </p>
+    <p class="lead-in">
+      The two axes are separate decisions, so the object form controls each on its own:
+      <code>{ y: 'always' }</code> pins the vertical bar while the horizontal one stays native, and
+      <code>{ x: 'always', y: 'always' }</code> is the same as the bare <code>'always'</code>. Under
+      the hood the pinned axis switches to <code>overflow: scroll</code> so its track is present even
+      when the content fits, and the scrollbar is styled as a classic, always-drawn bar rather than a
+      fading overlay (BACKLOG-0000990). The same viewport also suppresses the overscroll rubber-band
+      bounce, so a synchronised grid does not spring at its scroll boundary (BACKLOG-0000991).
+    </p>
+
+    <div class="example">
+      <p class="example__label">Pinning both axes, and one axis at a time</p>
+      <pre data-run="js" data-expect="always: always/always; y-only: auto/always" data-covers="config:scrollbars"><code><span class="cmt">// The renderer resolves `scrollbars` to a per-axis mode it stamps on the root.</span>
+<span class="kw">const</span> { resolveScrollbars } = <span class="kw">await</span> import('../packages/dom/src/renderer/renderer.js');
+
+<span class="kw">const</span> both = resolveScrollbars(<span class="str">'always'</span>);        <span class="cmt">// pins both axes</span>
+<span class="kw">const</span> onlyY = resolveScrollbars({ y: <span class="str">'always'</span> }); <span class="cmt">// pins the vertical bar only</span>
+<span class="kw">return</span> `always: ${both.x}/${both.y}; y-only: ${onlyY.x}/${onlyY.y}`;</code></pre>
+    </div>
+
     <h2 id="cards">Cards, lists and feeds</h2>
     <p class="lead-in">
       <code>rowTemplate</code> draws each row with a layout of your own instead of dividing it into

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.45.0, type declarations
+ * Lattice Grid 1.46.1, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -62,6 +62,24 @@ export type TypeName =
  * `center`.
  */
 export type Align = 'start' | 'center' | 'end' | 'left' | 'right' | 'centre';
+/**
+ * Vertical alignment of a cell's content within its row (BACKLOG-0000989).
+ *
+ * The vertical counterpart to {@link Align}. `top` sits the content at the top
+ * of the row, `middle` centres it and `bottom` drops it to the bottom. It is
+ * most visible on tall or `autoHeight` rows, where a wrapped-text column can be
+ * `top` while its single-line neighbours are `middle`.
+ */
+export type VAlign = 'top' | 'middle' | 'bottom';
+/**
+ * When the grid's scroll viewport keeps its scrollbars visible
+ * (BACKLOG-0000990).
+ *
+ * `auto` is the platform's native behaviour — overlay scrollbars fade away when
+ * idle. `always` keeps the bar shown whether or not the pointer is over the
+ * grid, so the affordance never disappears on a touchpad or an overlay OS.
+ */
+export type ScrollbarMode = 'auto' | 'always';
 /**
  * A named preset, or a raw scale where 1 is `standard`. Row heights are
  * 23.8 / 28 / 42 / 56px for the four presets; a number scales 28px.
@@ -507,6 +525,12 @@ export interface ColumnCellSpec {
   style?: CellStyle | ((p: CellParams) => CellStyle);
   tooltip?: string | ((p: CellParams) => string);
   align?: Align;
+  /**
+   * Vertical alignment of this column's cell content, overriding the grid-level
+   * `verticalAlign` for this column alone (BACKLOG-0000989). Accepted at the
+   * top level of the column too, as `align` is.
+   */
+  verticalAlign?: VAlign;
   wrap?: boolean;
   autoHeight?: boolean;
   flash?: boolean;
@@ -832,6 +856,13 @@ export interface Column {
    * default, which is itself `'hover'`.
    */
   headerControls?: 'hover' | 'always' | 'hidden';
+  /**
+   * Vertical alignment of this column's cell content within the row
+   * (BACKLOG-0000989). Overrides the grid-level `verticalAlign` for this column
+   * alone; `top`, `middle` or `bottom`. Also accepted as `cell.verticalAlign`,
+   * the way `align` is. Omitted, the column follows the grid default.
+   */
+  verticalAlign?: VAlign;
   /** 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. */
@@ -866,6 +897,12 @@ export interface ResolvedColumn {
   dataType: DataType;
   nullable: boolean;
   align: Align;
+  /**
+   * The resolved vertical alignment (BACKLOG-0000989), or `undefined` when
+   * neither the column nor the grid set one — in which case the cell keeps the
+   * grid's historical vertical placement (centred, or top for `autoHeight`).
+   */
+  verticalAlign?: VAlign;
   value: Required<Pick<ColumnValueSpec, 'pure'>> & ColumnValueSpec;
   cell: ColumnCellSpec;
   edit: ColumnEditSpec;
@@ -1475,6 +1512,30 @@ export interface GridConfig {
    */
   stripedRows?: boolean;
 
+  /**
+   * Vertical alignment of cell content within a row, as a default for every
+   * column (BACKLOG-0000989). `top`, `middle` or `bottom`; a column's own
+   * `verticalAlign` overrides it for that column.
+   *
+   * The horizontal counterpart is the per-column `align`. Omitted, the grid
+   * keeps its historical placement — content centred in a fixed-height row and
+   * top-aligned in an `autoHeight` row — so an existing grid is unchanged on
+   * upgrade. Setting a value aligns every column uniformly, including
+   * `autoHeight` rows, unless a column opts out.
+   */
+  verticalAlign?: VAlign;
+
+  /**
+   * Keep the scroll viewport's scrollbars visible (BACKLOG-0000990).
+   *
+   * `'auto'` (the default) is the platform's native behaviour, where overlay
+   * scrollbars fade when idle. `'always'` keeps both axes shown whether or not
+   * the pointer is over the grid. The object form controls each axis on its
+   * own — `{ y: 'always' }` pins the vertical bar while the horizontal one
+   * stays native. Omitted, the grid is unchanged on upgrade.
+   */
+  scrollbars?: ScrollbarMode | { x?: ScrollbarMode; y?: ScrollbarMode };
+
   /**
    * Show a bar above the column headings for filtering columns by tag.
    *