@zakkster/lite-table 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to `@zakkster/lite-table` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] — 2026-09-13
+
+### Added — View-state persistence seam
+
+Two additive `TableCore` methods that snapshot and restore the table's layout and query as plain JSON. This is the seam `@zakkster/lite-headless` `createSavedViews` (G-03) consumes; the named-view manager lives there, not here. Purely additive: the default path and every existing setter/signal/computed are byte-identical.
+
+- **`table.getViewState(): ViewState`** — a JSON-serializable snapshot of the layout + query: `v` (schema version, always `1`), `sort`, `columnOrder`, full per-column `columns` layout (`width` / `hidden` / `pin` / `flex` for every current column, not deltas), active `filters` (empty/whitespace queries omitted), `groupBy`, and `collapsedGroups`. No live signal refs, no `Map`/`Set` instances — `filters` is a plain object, `collapsedGroups` an array. Selection/focus/edit state are transient and excluded.
+- **`table.setViewState(view, opts?): void`** — restore a `ViewState` with REPLACE semantics, applied atomically inside a single `batch()` so downstream computeds recompute once. Throws `TypeError` before any mutation on a non-object, a missing `v`, or a `v` other than `1`. Within a v1 view a single malformed entry (bad sort dir, non-number width, unknown key) is skipped and the rest applied. `columnOrder` is reconciled against the live column set — saved keys still present are kept in order, new columns appended, dead keys dropped — so a stale order never trips `setColumnOrder`'s non-permutation guard. Columns absent from `view.columns` keep their current values. `opts` is reserved (no merge mode in v1) and ignored.
+- **`ViewState` / `ViewColumnState` / `SetViewStateOptions`** — exported type declarations.
+
+`setViewState(getViewState())` is an identity round-trip. Views are keyed (not positional), so they survive column-set drift. `batch` is now imported from `@zakkster/lite-signal`.
+
 ## [1.2.0] — 2026-07-03
 
 Row grouping, per-column aggregation, sticky group headers, and a sticky grand-total row. All feature additions are opt-in; consumers of 1.1.0 who don't pass `groupBy` are on the identical fast path they had in 1.1.0.

package/Table.d.ts

@@ -132,6 +132,42 @@ export interface SortEntry {
     dir: SortDir;
 }
 
+/** Per-column layout snapshot inside a {@link ViewState}. */
+export interface ViewColumnState {
+    width: number;
+    hidden: boolean;
+    pin: PinSide;
+    flex: number;
+}
+
+/**
+ * A JSON-serializable snapshot of the table's LAYOUT + QUERY -- sort,
+ * per-column layout, order, filters, grouping. Produced by
+ * `getViewState()` and consumed by `setViewState()`. No live signal refs,
+ * no `Map`/`Set` instances: `filters` is a plain object, `collapsedGroups`
+ * an array. This is the persistence seam lite-headless `createSavedViews`
+ * consumes; selection/focus/edit state are transient and excluded.
+ */
+export interface ViewState {
+    /** Schema version. Always `1` in this release. */
+    v: 1;
+    /** Sort chain, outermost key first. */
+    sort: SortEntry[];
+    /** Column order by key. */
+    columnOrder: string[];
+    /** Full per-column layout for every current column, keyed by column key. */
+    columns: { [key: string]: ViewColumnState };
+    /** Active column filters by key; empty/whitespace queries are omitted. */
+    filters: { [key: string]: string };
+    /** Group-by keys, outermost first. */
+    groupBy: string[];
+    /** Collapsed group path-strings (U+001F separator). */
+    collapsedGroups: string[];
+}
+
+/** Reserved options for {@link TableCore.setViewState}. Ignored in v1. */
+export interface SetViewStateOptions {}
+
 export type SelectMode = "set" | "add" | "toggle" | "range";
 
 /** Selection state is a PREDICATE, not a list of IDs.
@@ -438,6 +474,24 @@ export interface TableCore<Row = any> {
     // ---- Methods: focus ----
     moveFocus(direction: FocusDirection, opts?: { pageSize?: number }): void;
 
+    // ---- Methods: view state (persistence seam) ----
+    /**
+     * Snapshot the full layout + query as a JSON-serializable {@link ViewState}
+     * -- deep-copied, no live signal refs, no `Map`/`Set` instances. Persist
+     * it, then restore it with {@link TableCore.setViewState}.
+     */
+    getViewState(): ViewState;
+    /**
+     * Restore a {@link ViewState} with REPLACE semantics, applied atomically
+     * inside a single batch. Throws `TypeError` before any mutation on a
+     * non-object, a missing `v`, or a `v` other than `1`. Within a v1 view a
+     * single malformed entry (bad sort dir, non-number width, unknown key) is
+     * skipped and the rest applied. Stale column orders are reconciled, so a
+     * dropped/added column never rejects the restore. `opts` is reserved and
+     * ignored in v1.
+     */
+    setViewState(view: ViewState, opts?: SetViewStateOptions): void;
+
     // ---- Lifecycle ----
     dispose(): void;
 

package/Table.js

@@ -58,7 +58,7 @@
  */
 
 import {
-    signal, computed, effect, untrack,
+    signal, computed, effect, untrack, batch,
     dispose as disposeNode
 } from "@zakkster/lite-signal";
 import { virtualAxis } from "@zakkster/lite-virtual";
@@ -1624,6 +1624,165 @@ export function createTable(config) {
         return indent > 0 ? JSON.stringify(out, null, indent) : JSON.stringify(out);
     }
 
+    // =========================================================================
+    // --- View state (persistence seam, v1.3.0) -------------------------------
+    // =========================================================================
+    //
+    // getViewState() snapshots the LAYOUT + QUERY (sort, per-column layout,
+    // order, filters, grouping) to plain JSON-safe data -- no live signal
+    // refs, no Map/Set instances. setViewState() restores it with REPLACE
+    // semantics, atomically inside batch(), fail-closed on garbage. This is
+    // the seam lite-headless createSavedViews (G-03) consumes; the named-view
+    // MANAGER lives there, not here. Cold user-gesture path, not a hot path.
+
+    // Reconcile a saved column order against the CURRENT column set: keep saved
+    // keys still present (in saved order), append current keys absent from the
+    // saved order, drop saved keys no longer present. Always returns a
+    // permutation of the current columns, so setColumnOrder's non-permutation
+    // guard never trips on a stale-but-valid order.
+    function _reconcileOrder(savedOrder) {
+        const result = [];
+        const used = new Set();
+        if (Array.isArray(savedOrder)) {
+            for (let i = 0; i < savedOrder.length; i++) {
+                const k = savedOrder[i];
+                if (columnsByKey.has(k) && !used.has(k)) {
+                    result.push(k);
+                    used.add(k);
+                }
+            }
+        }
+        const cur = columnOrder();
+        for (let i = 0; i < cur.length; i++) {
+            const k = cur[i];
+            if (!used.has(k)) {
+                result.push(k);
+                used.add(k);
+            }
+        }
+        return result;
+    }
+
+    function getViewState() {
+        // Full per-column layout for EVERY current column -- restore is
+        // default-independent (never a delta against unknown defaults).
+        const cols = {};
+        for (let i = 0; i < columns.length; i++) {
+            const c = columns[i];
+            cols[c.key] = {
+                width: c.width(),
+                hidden: c.hidden(),
+                pin: c.pin(),
+                flex: c.flex()
+            };
+        }
+        // Map -> object; skip empty/whitespace queries (they carry no state).
+        const filters = {};
+        for (const [key, q] of columnFilters()) {
+            if (typeof q === "string" && q.trim() !== "") filters[key] = q;
+        }
+        // Copy each sort entry -- no shared refs to the live chain.
+        const sort = [];
+        const chain = sortChain();
+        for (let i = 0; i < chain.length; i++) {
+            sort.push({ key: chain[i].key, dir: chain[i].dir });
+        }
+        // Set -> array of pathStr.
+        const collapsed = [];
+        for (const p of collapsedGroups()) collapsed.push(p);
+        return {
+            v: 1,
+            sort,
+            columnOrder: columnOrder().slice(),
+            columns: cols,
+            filters,
+            groupBy: groupBy().slice(),
+            collapsedGroups: collapsed
+        };
+    }
+
+    function setViewState(view, opts) {
+        // Whole-view fail-closed BEFORE any mutation: garbage must never brick
+        // the table, and a future major version must not partially apply.
+        // null is not zero.
+        if (view === null || typeof view !== "object" || Array.isArray(view)) {
+            throw new TypeError("setViewState: view must be a plain object");
+        }
+        if (view.v !== 1) {
+            throw new TypeError(
+                "setViewState: unsupported view version " + String(view.v) +
+                " (expected 1)"
+            );
+        }
+        // `opts` is accepted and reserved for future use (e.g. a merge mode);
+        // ignored in v1. REPLACE semantics only.
+        void opts;
+        // Atomic: one batch so downstream computeds (visibleRows,
+        // visibleColumns, colTemplate, offsets) recompute ONCE, not per field.
+        batch(() => {
+            // 1. Column order -- reconcile first so the guard never trips.
+            setColumnOrder(_reconcileOrder(view.columnOrder));
+            // 2. Per-column layout via the four public setters. Skip malformed
+            //    entries; columns absent from view.columns keep current values.
+            const cols = view.columns;
+            if (cols !== null && typeof cols === "object" && !Array.isArray(cols)) {
+                const keys = Object.keys(cols);
+                for (let i = 0; i < keys.length; i++) {
+                    const key = keys[i];
+                    if (!columnsByKey.has(key)) continue;
+                    const c = cols[key];
+                    if (c === null || typeof c !== "object") continue;
+                    if (typeof c.width === "number" && Number.isFinite(c.width)) {
+                        setColumnWidth(key, c.width);
+                    }
+                    if (typeof c.hidden === "boolean") setColumnHidden(key, c.hidden);
+                    if (c.pin === "left" || c.pin === "right" || c.pin === "none") {
+                        setColumnPin(key, c.pin);
+                    }
+                    if (typeof c.flex === "number" && Number.isFinite(c.flex)) {
+                        setColumnFlex(key, c.flex);
+                    }
+                }
+            }
+            // 3. Filters (REPLACE) -- clear, then set each named entry.
+            clearColumnFilters();
+            const filters = view.filters;
+            if (filters !== null && typeof filters === "object" && !Array.isArray(filters)) {
+                const keys = Object.keys(filters);
+                for (let i = 0; i < keys.length; i++) {
+                    const key = keys[i];
+                    const q = filters[key];
+                    if (typeof q === "string") setColumnFilter(key, q);
+                }
+            }
+            // 4. Sort (REPLACE) -- clear, then add each valid entry.
+            clearSort();
+            const sort = view.sort;
+            if (Array.isArray(sort)) {
+                for (let i = 0; i < sort.length; i++) {
+                    const e = sort[i];
+                    if (e === null || typeof e !== "object") continue;
+                    if (e.dir !== "asc" && e.dir !== "desc") continue;
+                    addSort(e.key, e.dir);
+                }
+            }
+            // 5. Grouping (REPLACE) -- _normalizeGroupBy drops unknown keys.
+            setGroupBy(view.groupBy);
+            // 6. Collapsed groups (REPLACE) -- expand all, then collapse each
+            //    saved path. Saved pathStr strings split back to path arrays;
+            //    collapseGroup re-joins them to the identical pathStr.
+            expandAllGroups();
+            const collapsed = view.collapsedGroups;
+            if (Array.isArray(collapsed)) {
+                for (let i = 0; i < collapsed.length; i++) {
+                    const p = collapsed[i];
+                    if (typeof p === "string") collapseGroup(p.split(GROUP_PATH_SEP));
+                    else if (Array.isArray(p)) collapseGroup(p);
+                }
+            }
+        });
+    }
+
     return {
         // Static
         columns,
@@ -1695,6 +1854,9 @@ export function createTable(config) {
         // Methods: focus
         moveFocus,
 
+        // Methods: view state (persistence seam)
+        getViewState, setViewState,
+
         // Lifecycle
         dispose,
         _scope: scope

package/llms.txt

@@ -351,6 +351,48 @@ TableCore lifecycle:
   returns to the registry pool. 50 createTable+dispose cycles round-trip
   cleanly with activeNodes flat.
 
+View state (persistence seam):
+  Two TableCore methods (v1.3.0+) snapshot and restore the LAYOUT + QUERY
+  as plain JSON. Selection/focus/edit state are transient and excluded.
+  This is the seam @zakkster/lite-headless createSavedViews (G-03) consumes;
+  the named-view MANAGER lives there, not here. Cold user-gesture path.
+
+    getViewState() -> ViewState        JSON-safe snapshot; no live signal
+                                       refs, no Map/Set. Map -> object,
+                                       Set -> array. Full per-column layout
+                                       for EVERY current column (not deltas)
+                                       so restore is default-independent.
+    setViewState(view, opts?)          REPLACE semantics, atomic inside one
+                                       batch() (computeds recompute once).
+                                       opts reserved (no merge mode in v1),
+                                       ignored. Throws TypeError BEFORE any
+                                       mutation on a non-object, missing v,
+                                       or v !== 1. Within a v1 view a single
+                                       malformed entry is skipped, the rest
+                                       applied. columnOrder is reconciled
+                                       against the live column set (keep saved
+                                       keys still present, append new columns,
+                                       drop dead keys) so a stale order never
+                                       trips setColumnOrder's guard. Filters
+                                       and sort are cleared then re-applied;
+                                       groupBy replaced (unknown keys dropped);
+                                       collapsed groups expanded then
+                                       re-collapsed per saved path.
+
+  ViewState shape:
+    {
+      v: 1,                             // schema version (integer)
+      sort: [{ key, dir }],             // outermost key first
+      columnOrder: [key, ...],
+      columns: { [key]: { width, hidden, pin, flex } },  // full layout
+      filters: { [key]: query },        // empty/whitespace omitted
+      groupBy: [key, ...],
+      collapsedGroups: [pathStr, ...]   // U+001F separator
+    }
+
+  Round-trip: setViewState(getViewState()) is identity. Keyed (not
+  positional) so a view survives column-set drift.
+
 ### mountTable(host, table, options?) -> TableMount
 
 options: { injectStyles?=true, initialViewportHeight?=480 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-table",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Headless reactive data tables on @zakkster/lite-signal. CSS Grid (no <table>), pooled slots that never reparent, aria-activedescendant focus model. Zero-GC scroll path on @zakkster/lite-virtual. Grouping, aggregation, sticky group headers, and grand totals in v1.2.",
   "sideEffects": false,
   "keywords": [