@toclocoinc/lattice-grid 1.27.0 → 1.28.0

package/LICENSE

@@ -27,25 +27,25 @@ and ::1 -- no watermark is shown and no key is required. Development needs no
 paperwork.
 
 --------------------------------------------------------------------------
-3. WHAT REQUIRES A KEY
+3. SERVING ON OTHER HOSTS, AND WHAT A KEY REMOVES
 --------------------------------------------------------------------------
 
-Serving Lattice Grid from any host other than a loopback host requires a valid
-licence key issued by TOCLOCO Inc. This includes production, staging, internal
-tools, intranets and private networks. A corporate intranet is a deployment
-like any other; .local, .internal and private IP ranges are not exempt.
+You may serve Lattice Grid from any host -- including production, staging,
+internal tools, intranets and private networks -- without a licence key and
+without charge. On any host other than a loopback host (section 2), the grid
+renders in full and displays a trial watermark. Nothing is disabled, degraded
+or withheld: every capability works, watermarked, for as long as you like.
+
+A valid licence key issued by TOCLOCO Inc removes that watermark. Removing the
+watermark is the only thing a key does (section 1), so you need one when, and
+only when, you want the watermark gone -- typically for a production or
+customer-facing deployment. Serving watermarked, without a key, is permitted
+rather than a breach.
 
 Keys are issued per deployment rather than per developer or per seat. A key
-names the domains it covers and one key covers every developer, every build and
+names the domains it covers, and one key covers every developer, every build and
 every user on them.
 
-Without a valid key, the grid renders in full and displays a trial watermark.
-Nothing is disabled, degraded or withheld. That behaviour exists to protect
-your production screens from a licence lapsing at an inconvenient moment; it is
-a courtesy, not a grant of licence. Deploying to a non-loopback host without a
-valid key is a breach of these terms whether or not the software continues to
-work.
-
 --------------------------------------------------------------------------
 4. GRANT
 --------------------------------------------------------------------------

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

package/docs/API.html

@@ -848,7 +848,7 @@ autoInit(document); <span class="cmt">// builds every [data-lattice-grid] under
         <tbody>
           <tr><td class="name">statusBar</td><td class="type">boolean | { panels }</td><td class="desc">Composable panels along the bottom. Default set: <code>rowCount</code>, <code>selectedCount</code>, <code>aggregation</code>, <code>comments</code>, <code>updates</code>, <code>progress</code>. Each is silent when it has nothing to report.</td></tr>
           <tr><td class="name">maximise</td><td class="type">boolean</td><td class="dflt">true</td><td class="desc"><code>false</code> removes the rail button and <code>grid.maximise</code>, for an application with its own full-screen mode.</td></tr>
-          <tr><td class="name">toolPanel</td><td class="type">boolean | object</td><td class="desc">Side dock. <code>panels</code>: <code>columns</code>, <code>filters</code>, <code>views</code>, <code>quick</code>, <code>formatting</code>, <code>statistics</code>. <code>side: 'left'</code> makes it the icon rail, which also turns on <code>actions</code> (<code>undo</code>, <code>redo</code>, <code>pause</code>, <code>restore</code>, <code>maximise</code>, then the export group: <code>export</code>, <code>excel</code>, <code>clipboard</code>, <code>print</code>: nine in all, and an array takes these names rather than the button labels) and <code>icons</code>. An explicit array <em>replaces</em> that list rather than extending it; a bare <code>'-'</code> in it renders a divider between groups. <code>exportName</code> names the CSV.</td></tr>
+          <tr><td class="name">toolPanel</td><td class="type">boolean | object</td><td class="desc">Side dock. <code>panels</code>: <code>columns</code>, <code>filters</code>, <code>views</code>, <code>quick</code>, <code>formatting</code>, <code>statistics</code>. <code>side: 'left'</code> makes it the icon rail, which also turns on <code>actions</code> (<code>undo</code>, <code>redo</code>, <code>pause</code>, <code>restore</code>, <code>maximise</code>, then the export group: <code>export</code>, <code>excel</code>, <code>clipboard</code>, <code>print</code>: nine in all, and an array takes these names rather than the button labels) and <code>icons</code>. An explicit array <em>replaces</em> that list rather than extending it; a bare <code>'-'</code> in it renders a divider between groups. <code>exportName</code> names the CSV. <code>annotate: true</code> adds the native annotation tools — <code>pen</code>, <code>arrow</code>, <code>rect</code>, <code>highlight</code> — to the rail as toggle buttons (pressed while in use, pressed again to exit); they also appear automatically for the duration of a presentation.</td></tr>
           <tr><td class="name">groupPanel</td><td class="type">boolean | object</td><td class="desc">A drag-and-drop group-by strip above the column header — the row-group panel. Drag a heading into it to group by that column; the active groups show as removable, reorderable chips, and reordering the chips changes the nesting order. It is keyboard-operable — arrows move between chips, <code>Shift</code> with an arrow reorders, <code>Delete</code> ungroups, and an add control groups any column — and every change is announced through the live region. Off by default and non-breaking; it drives the same model as <code>grid.columns.group()</code> and reimplements nothing. The object form takes <code>hint</code>, the placeholder shown while nothing is grouped.</td></tr>
           <tr><td class="name">kpis</td><td class="type">StatConfig[]</td><td class="desc">A built-in KPI/stat strip: a labelled band of stat tiles the grid places for you above the column header. Each entry is a <code>createStat</code> spec — <code>of</code>, <code>fn</code>, <code>title</code>, <code>interval</code>, <code>footer</code>, <code>format</code> and the rest, minus <code>grid</code> and <code>container</code>, which the grid supplies — so a strip tile and a hand-placed one are the same object. The tiles follow the grid's filters, recomputing on every change like a stand-alone stat does. Off by default and non-breaking; it reuses <code>createStat</code> and reimplements no compute.</td></tr>
           <tr><td class="name">timeZone</td><td class="type">string</td><td class="desc">An IANA zone every date column formats and parses in, so a grid shows one zone whatever the viewer's machine says. Individual columns may override it.</td></tr>
@@ -3755,10 +3755,11 @@ const chart = createChart({
     </div>
 
     <h3>Clicking a chart</h3>
-    <p>A chart emits <code>point:click</code>, <code>point:hover</code> and <code>series:toggle</code>. The common use is filtering the grid from a mark, which makes the pair two views of one selection rather than a chart beside a table.</p>
-    <pre><code>chart.on('point:click', ({ point }) =&gt; {
-  grid.filters.set({ col: 'region', op: 'eq', value: point.x });
+    <p>A chart emits <code>click</code>, <code>hover</code>, <code>leave</code>, <code>focus</code>, <code>draw</code>, <code>drill</code>, <code>brush</code> and <code>legend</code> — there is no <code>point:click</code>, <code>point:hover</code> or <code>series:toggle</code>. The common use is filtering the grid from a mark, which makes the pair two views of one selection rather than a chart beside a table. The <code>click</code> and <code>hover</code> payload is <strong>flat</strong> — <code>{ label, category, column, value, series, rowKeys, native, preventDefault }</code>, with no <code>point</code> wrapper — where <code>column</code> is the grid column the mark filters on and <code>category</code> the value to filter it to.</p>
+    <pre><code>chart.on('click', ({ column, category }) =&gt; {
+  grid.filters.set({ col: column, op: 'eq', value: category });
 });</code></pre>
+    <p>Simplest of all, set <code>filterOnClick: true</code> in the spec and the chart applies exactly that filter itself on the clicked mark. The <code>click</code> event still fires first, so a handler that calls <code>preventDefault()</code> on the payload takes the click over instead.</p>
 
     <h3 id="chart-a-range">Chart a selected range</h3>
     <p>A user who drags out a block of cells — a text column and the numbers beside it — is asking a question a spreadsheet answers with one gesture: chart this. <code>chartRange</code> is that gesture. It reads the selected range, derives the chart from its shape, and returns the same live <code>Chart</code> <code>createChart</code> does, so nothing about it is a second kind of chart.</p>
@@ -7138,6 +7139,7 @@ return `methods ${ANOMALY_METHODS.length}; flagged ${z.flagged}; upper ${fence.u
           <tr><td class="name">icon</td><td class="type">string | (() =&gt; string)</td><td class="desc"><small>(optional)</small></td></tr>
           <tr><td class="name">run</td><td class="type">(params: RailActionParams): void</td><td class="desc"></td></tr>
           <tr><td class="name">enabled</td><td class="type">(): boolean</td><td class="desc"><small>(optional)</small></td></tr>
+          <tr><td class="name">active</td><td class="type">(): boolean</td><td class="desc">Marks the action as a toggle and reports whether it is currently on. When present the rail renders `aria-pressed` and a pressed style, re-read on every repaint; a one-shot action omits it and is unchanged. This is the hook the native annotation tools use, and it is available to a host button that is itself a toggle. <small>(optional)</small></td></tr>
         </tbody>
       </table>
     </div>

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.27.0</p>
+    <p class="rail__sub">Developer guide · v1.28.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.27.0, type declarations
+ * Lattice Grid 1.28.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -1928,6 +1928,14 @@ export interface GridConfig {
     actions?: false | (RailActionName | '-' | RailAction)[];
     /** File name for the export action, without the extension. */
     exportName?: string;
+    /**
+     * Put the native annotation tools — pen, arrow, rectangle, highlighter — on
+     * the rail. Off by default; each is a real toggle button that shows pressed
+     * while it is the tool in use and turns off when pressed again. The tools
+     * also appear automatically for the duration of a presentation, so this is
+     * only needed to keep them available outside one.
+     */
+    annotate?: boolean;
   };
   /**
    * A drag-and-drop group-by strip above the column header — the pattern AG
@@ -4218,7 +4226,10 @@ export interface ColumnMenuParams {
 /** The rail's built-in action names, plus `'-'` for a divider. */
 export type RailActionName =
   | 'undo' | 'redo' | 'pause' | 'restore' | 'maximise'
-  | 'export' | 'excel' | 'clipboard' | 'print';
+  | 'export' | 'excel' | 'clipboard' | 'print'
+  // The native annotation tools, on the rail when `toolPanel.annotate` is set
+  // or while a presentation runs. Each is toggleable (see `RailAction.active`).
+  | 'pen' | 'arrow' | 'rect' | 'highlight';
 
 /** What a host rail action's `run` is handed. */
 export interface RailActionParams {
@@ -4233,6 +4244,14 @@ export interface RailAction {
   icon?: string | (() => string);
   run(params: RailActionParams): void;
   enabled?(): boolean;
+  /**
+   * Marks the action as a toggle and reports whether it is currently on. When
+   * present the rail renders `aria-pressed` and a pressed style, re-read on
+   * every repaint; a one-shot action omits it and is unchanged. This is the
+   * hook the native annotation tools use, and it is available to a host button
+   * that is itself a toggle.
+   */
+  active?(): boolean;
 }
 
 /** The result of evaluating a formula a user typed into a cell (spec 8.11). */
@@ -5323,8 +5342,22 @@ export interface ChartSpec {
  * The events a chart raises.
  *
  * A chart's own, not the grid's: `grid.on` takes {@link EventName} and knows
- * nothing about these. `point:click` is the one most callers want, it is how a
- * click on a mark becomes a filter on the grid.
+ * nothing about these. There is no `point:click`, `point:hover` or
+ * `series:toggle`; the events are the flat names below and `click` is the one
+ * most callers want, it is how a click on a mark becomes a filter on the grid.
+ *
+ * `click` and `hover` carry a **flat** payload — there is no `point` wrapper:
+ * `{ label, category, column, value, series, rowKeys, native, preventDefault }`.
+ * `column` is the grid column the mark filters on and `category` the value to
+ * filter it to; `value` is the measure when a single series sits under the mark,
+ * otherwise null with the per-series numbers in `series`; `rowKeys` are the
+ * source rows behind the mark; `native` is the DOM event.
+ *
+ * `click` fires whether or not the spec sets `filterOnClick`, and it fires
+ * *before* any filter is applied: call `preventDefault()` on the payload to stop
+ * the chart filtering the grid and take the click over yourself. With
+ * `filterOnClick: true` in the spec the chart filters the grid itself on the
+ * clicked mark's `column`/`category` unless a handler prevented it.
  */
 export type ChartEventName =
   | 'click' | 'hover' | 'leave' | 'focus'