@ashley-shrok/viewmodel-shell 0.12.0 → 0.14.0

package/dist/browser.d.ts

@@ -10,6 +10,12 @@ export declare class BrowserAdapter implements Adapter {
      *  contentType is informational — the Blob's own .type takes precedence in
      *  browsers. We accept the arg for adapter symmetry (other adapters use it). */
     saveFile(data: Blob, filename: string, _contentType: string): void;
+    /** 0.14.0 — install / clear the browser's `beforeunload` guard. The shell
+     *  calls this on every response with `response.preventUnload ?? false`, so
+     *  the lock-and-clear cycle is just "server sets preventUnload:true while
+     *  work is pending, omits it (or sets false) when done." Idempotent. */
+    private unloadHandler;
+    setPreventUnload(active: boolean): void;
     transport(input: string, init: {
         method?: string;
         headers?: Record<string, string>;

package/dist/browser.js

@@ -105,6 +105,28 @@ export class BrowserAdapter {
             setTimeout(() => URL.revokeObjectURL(url), 0);
         }
     }
+    /** 0.14.0 — install / clear the browser's `beforeunload` guard. The shell
+     *  calls this on every response with `response.preventUnload ?? false`, so
+     *  the lock-and-clear cycle is just "server sets preventUnload:true while
+     *  work is pending, omits it (or sets false) when done." Idempotent. */
+    unloadHandler = null;
+    setPreventUnload(active) {
+        if (active && this.unloadHandler == null) {
+            this.unloadHandler = (e) => {
+                // Two signals because browsers historically disagreed on which they
+                // honor; modern Chromium/Firefox honor preventDefault, older Safari
+                // and ancient browsers look at returnValue. The dialog text itself is
+                // browser-controlled ("Leave site?…") and cannot be customized.
+                e.preventDefault();
+                e.returnValue = "";
+            };
+            window.addEventListener("beforeunload", this.unloadHandler);
+        }
+        else if (!active && this.unloadHandler != null) {
+            window.removeEventListener("beforeunload", this.unloadHandler);
+            this.unloadHandler = null;
+        }
+    }
     async transport(input, init, hooks) {
         const onUploadProgress = hooks?.onUploadProgress;
         if (!onUploadProgress) {
@@ -651,8 +673,26 @@ export class BrowserAdapter {
             box.className = "vms-table__select vms-table__select--all";
             box.checked = allOnPage;
             box.indeterminate = someOnPage && !allOnPage;
-            const selAction = sel.action;
-            box.addEventListener("change", () => on({ name: selAction.name, context: { ...(selAction.context ?? {}), all: true, checked: box.checked } }));
+            box.addEventListener("change", () => {
+                const selAction = sel.action;
+                if (selAction) {
+                    // Server-truth mode: dispatch; server re-renders with new selectedIds.
+                    on({ name: selAction.name, context: { ...(selAction.context ?? {}), all: true, checked: box.checked } });
+                }
+                else {
+                    // Local mode (0.13.0): toggle every row checkbox + class in this table
+                    // to match the header. No dispatch — the dispatch guard can't drop anything.
+                    const want = box.checked;
+                    table.querySelectorAll("tbody input.vms-table__select").forEach(rowBox => {
+                        if (rowBox.disabled)
+                            return;
+                        rowBox.checked = want;
+                        const tr = rowBox.closest(".vms-table__row");
+                        if (tr)
+                            tr.classList.toggle("vms-table__row--selected", want);
+                    });
+                }
+            });
             th.appendChild(box);
             headerRow.appendChild(th);
         }
@@ -740,8 +780,28 @@ export class BrowserAdapter {
                 box.checked = isSelected;
                 if (row.id != null) {
                     const rowId = row.id;
-                    const selAction = sel.action;
-                    box.addEventListener("change", () => on({ name: selAction.name, context: { ...(selAction.context ?? {}), id: rowId, checked: box.checked } }));
+                    // data-id is what selection.buttons[] harvest reads on click.
+                    box.dataset.id = rowId;
+                    box.addEventListener("change", () => {
+                        const selAction = sel.action;
+                        if (selAction) {
+                            on({ name: selAction.name, context: { ...(selAction.context ?? {}), id: rowId, checked: box.checked } });
+                        }
+                        else {
+                            // Local mode (0.13.0): flip the row class to mirror the box, then
+                            // reconcile the header select-all (could now be all / some / none).
+                            tr.classList.toggle("vms-table__row--selected", box.checked);
+                            const headerBox = table.querySelector("thead input.vms-table__select--all");
+                            if (headerBox) {
+                                const all = table.querySelectorAll("tbody input.vms-table__select:not(:disabled)");
+                                let checked = 0;
+                                all.forEach(b => { if (b.checked)
+                                    checked++; });
+                                headerBox.checked = all.length > 0 && checked === all.length;
+                                headerBox.indeterminate = checked > 0 && checked < all.length;
+                            }
+                        }
+                    });
                 }
                 else {
                     box.disabled = true; // selection addresses rows by id; a row without one can't be selected
@@ -773,6 +833,25 @@ export class BrowserAdapter {
         });
         table.appendChild(tbody);
         wrapper.appendChild(table);
+        // 0.13.0 — bulk-action toolbar rendered ABOVE the table. Each button's
+        // click harvests the table's currently-checked row ids and merges them as
+        // `selectedIds` into the action's context. Works with both server-truth
+        // mode (the DOM mirrors selectedIds so the harvest matches state) and
+        // local mode (the DOM is the only source of selection truth).
+        if (sel?.buttons && sel.buttons.length > 0) {
+            const toolbar = document.createElement("div");
+            toolbar.className = "vms-table__bulk-actions";
+            const harvest = (action) => {
+                const ids = [];
+                table.querySelectorAll("tbody input.vms-table__select:checked").forEach(b => {
+                    if (b.dataset.id)
+                        ids.push(b.dataset.id);
+                });
+                on({ name: action.name, context: { ...(action.context ?? {}), selectedIds: ids } });
+            };
+            sel.buttons.forEach(btn => this.button(btn, toolbar, harvest));
+            wrapper.insertBefore(toolbar, table);
+        }
         if (n.pagination) {
             const pg = n.pagination;
             const footer = document.createElement("div");

package/dist/index.d.ts

@@ -32,6 +32,16 @@ export interface Adapter {
      *  May return void or Promise<void>; the shell awaits the return value so
      *  async I/O errors surface via onError. */
     saveFile?(data: Blob, filename: string, contentType: string): void | Promise<void>;
+    /** 0.14.0 — install / clear a "warn before navigating away" guard, driven
+     *  by `ShellResponse.preventUnload` on every response (load, dispatch,
+     *  push). Idempotent: the shell calls with the boolean from each response,
+     *  the adapter installs when true / clears when false. Designed for
+     *  long-running server actions where an accidental tab close would lose
+     *  in-flight work. Fail-quiet by absence (unlike navigate/storage/saveFile)
+     *  — this is a UX safety net, not a security guarantee, and non-browser
+     *  targets (TUI) have no terminal equivalent. Modern browsers show a
+     *  generic "Leave site?" dialog; the message is not customizable. */
+    setPreventUnload?(active: boolean): void;
 }
 export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode;
 export interface PageNode {
@@ -203,18 +213,32 @@ export interface TableRow {
     variant?: string;
 }
 export interface TableSelection {
-    /** Row ids currently selected — server-truth. The adapter checks each row
-     *  whose `id` is in this list and emits `.vms-table__row--selected` on it.
-     *  Selection survives sort/filter/pagination because it round-trips in state,
-     *  independent of which rows are currently in `rows`. */
+    /** Row ids that should render PRE-SELECTED on this render. In server-truth
+     *  mode (`action` set) this is the live selection, round-tripped in state and
+     *  authoritative every render. In local mode (`action` omitted) this is the
+     *  server's initial pre-selection only — subsequent toggles are purely
+     *  client-side DOM state and the server doesn't see them until a `buttons[]`
+     *  click harvests them. */
     selectedIds: string[];
-    /** Dispatched on a selection toggle. The adapter merges `{ id, checked }` for
-     *  a per-row checkbox, or `{ all: true, checked }` for the header select-all
-     *  checkbox (where "all" means the rows currently rendered — i.e. the current
-     *  page, never unloaded rows). The "select all N matching" affordance, when an
-     *  app wants it, is the app's own node composed above the table — the
-     *  framework gives the primitive, not the policy. */
-    action: ActionEvent;
+    /** OPTIONAL (0.13.0). When present: server-truth mode — every checkbox toggle
+     *  dispatches this action with merged `{ id, checked }` per row or
+     *  `{ all: true, checked }` for the header select-all (where "all" = the
+     *  rendered page). Selection survives sort/filter/pagination via the state
+     *  round-trip. When OMITTED: local mode — the adapter toggles the DOM
+     *  checkbox + `.vms-table__row--selected` class purely client-side with no
+     *  dispatch. Local mode is the recommended pattern for rapid-selection
+     *  workflows (no dropped clicks under the dispatch guard); see `buttons` for
+     *  how bulk actions read the resulting selection. */
+    action?: ActionEvent;
+    /** OPTIONAL (0.13.0). When present, the adapter renders these as a bulk-action
+     *  toolbar ABOVE the table. On click, each button harvests the currently
+     *  checked rows from the DOM and dispatches its `action` with
+     *  `{ selectedIds: [...] }` merged into its `context`. Designed primarily to
+     *  pair with local mode (`action` absent) — it's how the server learns the
+     *  selection without a per-toggle round-trip — but works in server-truth mode
+     *  too (the harvest matches `selectedIds` since the DOM reflects server-truth
+     *  after each render). */
+    buttons?: ButtonNode[];
 }
 export interface TablePagination {
     /** 1-based current page. */
@@ -306,6 +330,12 @@ export interface ShellResponse {
     sideEffects?: ShellSideEffect[];
     /** When set, schedules the next poll at this delay (ms). Overrides pollInterval for one tick. */
     nextPollIn?: number;
+    /** 0.14.0 — when true, the shell asks the adapter to install a "warn before
+     *  unload" guard; when false / absent, the guard is cleared. Drives long-
+     *  running-work workflows: while server-side work is in flight, return
+     *  `preventUnload: true` from each response; clear it when the work
+     *  completes (typically via polling). See `Adapter.setPreventUnload`. */
+    preventUnload?: boolean;
 }
 export declare class ViewModelShell {
     private options;

package/dist/index.js

@@ -21,6 +21,10 @@ export class ViewModelShell {
             const body = (await res.json());
             this.currentVm = body.vm;
             this.currentState = body.state;
+            // 0.14.0 — apply the unload guard from the initial-load response too. The
+            // server may legitimately want it on at first paint (e.g. the page was
+            // refreshed mid-work and the long action is still pending server-side).
+            adapter.setPreventUnload?.(body.preventUnload ?? false);
             adapter.render(body.vm, (action) => this.dispatch(action));
             this.schedulePoll(body.nextPollIn);
         }
@@ -138,6 +142,11 @@ export class ViewModelShell {
                 void this.download(effect.url, effect.filename);
             }
         }
+        // 0.14.0 — apply the unload guard before the redirect/render branch so it's
+        // in place (or cleared) consistently across both branches. A server that
+        // wants a redirect to NOT be blocked by its own guard simply omits
+        // preventUnload (or sets it false) on that response — standard pattern.
+        adapter.setPreventUnload?.(body.preventUnload ?? false);
         if (body.redirect) {
             if (this.options.onRedirect) {
                 this.options.onRedirect(body.redirect);

package/dist/server.d.ts

@@ -18,6 +18,10 @@ export interface ShellResponseBody<TState> {
     redirect?: string;
     sideEffects?: ShellSideEffect[];
     nextPollIn?: number;
+    /** 0.14.0 — install / clear the browser's "warn before unload" guard. Omit
+     *  (or set false) to clear; set true while a long-running server action is
+     *  in flight so an accidental tab-close doesn't lose work. */
+    preventUnload?: boolean;
 }
 /** Build a redirect response (Vm and State omitted; shell navigates the browser). */
 export declare function shellRedirect<TState = unknown>(url: string): ShellResponseBody<TState>;

package/dist/tui.js

@@ -915,24 +915,42 @@ function TableView({ node, ctx }) {
         });
     };
     // Selection — leading [x]/[ ] column. Dispatch payloads match BrowserAdapter:
-    // { id, checked } per row, { all: true, checked } for select-all.
+    // { id, checked } per row, { all: true, checked } for select-all (server-truth
+    // mode). 0.13.0: if `action` is omitted, this is LOCAL mode. The TUI renders
+    // checkboxes from `selectedIds` (the server's pre-selection); clicks are
+    // inert because the TUI doesn't track DOM-equivalent state across the
+    // hook-less conformance walker. The browser carries the real local-mode
+    // workflow; TUI is experimental — use the browser for interactive bulk
+    // selection. The selection.buttons[] toolbar still renders below.
     const sel = node.selection;
-    const selectedSet = sel ? new Set(sel.selectedIds) : null;
+    const effectiveSet = sel ? new Set(sel.selectedIds) : null;
     const allOnPage = sel != null && node.rows.length > 0 &&
-        node.rows.every((r) => r.id != null && selectedSet.has(r.id));
-    const onToggleAll = sel
+        node.rows.every((r) => r.id != null && effectiveSet.has(r.id));
+    const onToggleAll = sel?.action
         ? () => ctx.onAction({
             name: sel.action.name,
             context: { ...(sel.action.context ?? {}), all: true, checked: !allOnPage },
         })
         : undefined;
-    const onToggleRow = sel
+    const onToggleRow = sel?.action
         ? (rowId, checked) => ctx.onAction({
             name: sel.action.name,
             context: { ...(sel.action.context ?? {}), id: rowId, checked },
         })
         : undefined;
-    return (_jsx("scrollbox", { focused: focused, focusable: isPaneFocusable, borderColor: focused ? "#88aaff" : "#555555", focusedBorderColor: "#88aaff", flexGrow: 1, flexShrink: 1, children: _jsxs("box", { flexDirection: "column", children: [_jsxs("box", { flexDirection: "row", gap: 2, children: [sel ? (_jsx("text", { attributes: 1 /* BOLD */, ...(onToggleAll ? { onMouseDown: onToggleAll } : {}), children: allOnPage ? "[x]" : "[ ]" })) : null, node.columns.map((c) => {
+    return (_jsx("scrollbox", { focused: focused, focusable: isPaneFocusable, borderColor: focused ? "#88aaff" : "#555555", focusedBorderColor: "#88aaff", flexGrow: 1, flexShrink: 1, children: _jsxs("box", { flexDirection: "column", children: [sel?.buttons && sel.buttons.length > 0 ? (_jsx("box", { flexDirection: "row", gap: 1, children: sel.buttons.map((btn, i) => {
+                        const harvestCtx = {
+                            ...ctx,
+                            onAction: (action) => {
+                                const ids = [...effectiveSet];
+                                ctx.onAction({
+                                    name: action.name,
+                                    context: { ...(action.context ?? {}), selectedIds: ids },
+                                });
+                            },
+                        };
+                        return _jsx(ButtonView, { node: btn, ctx: harvestCtx }, i);
+                    }) })) : null, _jsxs("box", { flexDirection: "row", gap: 2, children: [sel ? (_jsx("text", { attributes: 1 /* BOLD */, ...(onToggleAll ? { onMouseDown: onToggleAll } : {}), children: allOnPage ? "[x]" : "[ ]" })) : null, node.columns.map((c) => {
                             const isSorted = node.sortColumn === c.key;
                             const caret = isSorted ? (node.sortDirection === "desc" ? " ↓" : " ↑") : "";
                             // B5 — only sortable headers respond to clicks (matches BrowserAdapter).
@@ -945,7 +963,7 @@ function TableView({ node, ctx }) {
                         ? () => ctx.onAction(row.action)
                         : undefined;
                     return (_jsxs("box", { flexDirection: "row", gap: 2, ...(onRowClick ? { onMouseDown: onRowClick } : {}), children: [sel ? (() => {
-                                const isSel = row.id != null && selectedSet.has(row.id);
+                                const isSel = row.id != null && effectiveSet.has(row.id);
                                 const rowId = row.id;
                                 const onBox = rowId != null && onToggleRow
                                     ? () => onToggleRow(rowId, !isSel)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic — a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",

package/styles/default.css

@@ -624,6 +624,17 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
 .vms-table__row--selected { background: color-mix(in srgb, var(--vms-accent) 12%, transparent); }
 .vms-table__row--selected.vms-table__row--clickable:hover { background: color-mix(in srgb, var(--vms-accent) 18%, transparent); }
 
+/* 0.13.0 — bulk-action toolbar rendered ABOVE the table (when
+   TableNode.selection.buttons[] is set). Reuses .vms-button styling; only
+   layout is added — flex row, wrap on narrow, gap from the spacing rhythm. */
+.vms-table__bulk-actions {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  gap: var(--vms-space-sm);
+  padding-bottom: var(--vms-space-sm);
+}
+
 /* Pagination footer — range label + prev/next, separated from the table by a
    hairline. Buttons reuse .vms-button styling; only sizing/disabled is added. */
 .vms-table__pagination {