@joewinke/jatui 0.21.0 → 0.22.0

package/CLAUDE.md

@@ -252,6 +252,12 @@ import { snapResume, resumeLabel } from "jatui"                       // resume
 import { createQuietChain, amountFor } from "jatui"                   // loudness-compensated tone (WebAudio)
 import { qrMatrix, qrCanvas } from "jatui"                            // deep-link QR, ISO 18004 v1–10, no deps
 
+// Snapshot undo/redo history (wayflow-core, generic over any JSON-shaped state G).
+// Also importable as 'jatui/history'. Snapshots are JSON-deep-cloned (safe on $state proxies).
+// beginChange/endChange = push-on-first-move for drag gestures; untracked() = compound op, no pushes.
+import { createHistory, pushState, undo, redo, beginChange, endChange, untracked, clearHistory, MAX_UNDO_DEPTH } from "jatui"
+import type { History } from "jatui"
+
 // Date formatting
 import { formatRelativeTime, formatDate, formatShortDate, formatDateTime } from "jatui"
 

package/dist/history.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Snapshot undo/redo history. Forked from @wayflow/core's history.ts (see
+ * README.md) and generalized to any graph type `G` — this module only
+ * deep-clones snapshots, it never inspects node/edge shape.
+ *
+ * Adds two things upstream keeps outside `core` (in its DOM editor package):
+ * push-on-first-move (`beginChange`/`endChange`) so a drag/resize gesture
+ * pushes exactly one pre-change snapshot no matter how many move events it
+ * fires, and `untracked()` to run a compound multi-step mutation (e.g.
+ * paste = add nodes + add edges) without each step pushing its own entry.
+ *
+ * CANONICAL HOME: this is the shared copy (jatui-00jfh, rebuilding the lost
+ * jat-gjw72 upstream half). The JAT IDE (ide/src/lib/utils/history.ts) and
+ * JST (src/lib/workflows/core/history.ts) carry vendored copies that
+ * repoint their imports at 'jatui' and are deleted at the swap.
+ */
+export declare const MAX_UNDO_DEPTH = 50;
+export interface History<G> {
+    undoStack: G[];
+    redoStack: G[];
+    /** True while a push-on-first-move gesture is in progress (see beginChange). */
+    changing: boolean;
+    /** Suppression depth for untracked(). Pushes no-op while > 0. */
+    suppressed: number;
+}
+export declare function createHistory<G>(): History<G>;
+/** Deep-clones `graph` onto the undo stack (capped at maxDepth) and clears redo. No-ops while suppressed. */
+export declare function pushState<G>(history: History<G>, graph: G, maxDepth?: number): void;
+/**
+ * Push-on-first-move: call on every move event of a drag/resize gesture.
+ * Pushes the pre-gesture snapshot only the first time it's called since the
+ * last endChange() — a click that never drags won't add a history entry.
+ */
+export declare function beginChange<G>(history: History<G>, graph: G, maxDepth?: number): void;
+/** Ends the current push-on-first-move gesture so the next beginChange() can push again. */
+export declare function endChange<G>(history: History<G>): void;
+/** Runs `fn` with history pushes suppressed — for compound ops that should land as zero or one entries (pair with a manual pushState before calling). */
+export declare function untracked<G>(history: History<G>, fn: () => void): void;
+/** Pops the most recent undo entry, pushing `currentGraph` onto redo. Returns null if nothing to undo. */
+export declare function undo<G>(history: History<G>, currentGraph: G): G | null;
+/** Pops the most recent redo entry, pushing `currentGraph` onto undo. Returns null if nothing to redo. */
+export declare function redo<G>(history: History<G>, currentGraph: G): G | null;
+/** Clears both stacks and any in-progress gesture/suppression state. */
+export declare function clearHistory<G>(history: History<G>): void;

package/dist/history.js

@@ -0,0 +1,87 @@
+/**
+ * Snapshot undo/redo history. Forked from @wayflow/core's history.ts (see
+ * README.md) and generalized to any graph type `G` — this module only
+ * deep-clones snapshots, it never inspects node/edge shape.
+ *
+ * Adds two things upstream keeps outside `core` (in its DOM editor package):
+ * push-on-first-move (`beginChange`/`endChange`) so a drag/resize gesture
+ * pushes exactly one pre-change snapshot no matter how many move events it
+ * fires, and `untracked()` to run a compound multi-step mutation (e.g.
+ * paste = add nodes + add edges) without each step pushing its own entry.
+ *
+ * CANONICAL HOME: this is the shared copy (jatui-00jfh, rebuilding the lost
+ * jat-gjw72 upstream half). The JAT IDE (ide/src/lib/utils/history.ts) and
+ * JST (src/lib/workflows/core/history.ts) carry vendored copies that
+ * repoint their imports at 'jatui' and are deleted at the swap.
+ */
+export const MAX_UNDO_DEPTH = 50;
+/**
+ * Deep-clones plain JSON-shaped state. Not `structuredClone` — callers pass
+ * Svelte 5 `$state` proxies (e.g. the canvas's reactive nodes/edges arrays),
+ * and `structuredClone` throws `DataCloneError` on those in real browsers
+ * (verified in-browser). A JSON round-trip reads through the proxy's
+ * property getters like any other consumer and is safe for graph data (no
+ * Date/Map/Set/functions).
+ */
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export function createHistory() {
+    return { undoStack: [], redoStack: [], changing: false, suppressed: 0 };
+}
+/** Deep-clones `graph` onto the undo stack (capped at maxDepth) and clears redo. No-ops while suppressed. */
+export function pushState(history, graph, maxDepth = MAX_UNDO_DEPTH) {
+    if (history.suppressed > 0)
+        return;
+    if (history.undoStack.length >= maxDepth) {
+        history.undoStack.shift();
+    }
+    history.undoStack.push(deepClone(graph));
+    history.redoStack = [];
+}
+/**
+ * Push-on-first-move: call on every move event of a drag/resize gesture.
+ * Pushes the pre-gesture snapshot only the first time it's called since the
+ * last endChange() — a click that never drags won't add a history entry.
+ */
+export function beginChange(history, graph, maxDepth = MAX_UNDO_DEPTH) {
+    if (history.changing)
+        return;
+    history.changing = true;
+    pushState(history, graph, maxDepth);
+}
+/** Ends the current push-on-first-move gesture so the next beginChange() can push again. */
+export function endChange(history) {
+    history.changing = false;
+}
+/** Runs `fn` with history pushes suppressed — for compound ops that should land as zero or one entries (pair with a manual pushState before calling). */
+export function untracked(history, fn) {
+    history.suppressed++;
+    try {
+        fn();
+    }
+    finally {
+        history.suppressed--;
+    }
+}
+/** Pops the most recent undo entry, pushing `currentGraph` onto redo. Returns null if nothing to undo. */
+export function undo(history, currentGraph) {
+    if (history.undoStack.length === 0)
+        return null;
+    history.redoStack.push(deepClone(currentGraph));
+    return history.undoStack.pop();
+}
+/** Pops the most recent redo entry, pushing `currentGraph` onto undo. Returns null if nothing to redo. */
+export function redo(history, currentGraph) {
+    if (history.redoStack.length === 0)
+        return null;
+    history.undoStack.push(deepClone(currentGraph));
+    return history.redoStack.pop();
+}
+/** Clears both stacks and any in-progress gesture/suppression state. */
+export function clearHistory(history) {
+    history.undoStack = [];
+    history.redoStack = [];
+    history.changing = false;
+    history.suppressed = 0;
+}

package/dist/index.d.ts

@@ -225,3 +225,5 @@ export { computeActiveSection, DEFAULT_ACTIVATION_RATIO } from './components/bas
 export type { SectionRect, SpyViewport, SpyScrollState } from './components/basic/sectionNavSpy';
 export { default as Slider } from './components/basic/Slider.svelte';
 export { default as Pagination } from './components/basic/Pagination.svelte';
+export { MAX_UNDO_DEPTH, createHistory, pushState, beginChange, endChange, untracked, undo, redo, clearHistory } from './history';
+export type { History } from './history';

package/dist/index.js

@@ -260,3 +260,5 @@ export { default as SectionNav } from './components/basic/SectionNav.svelte';
 export { computeActiveSection, DEFAULT_ACTIVATION_RATIO } from './components/basic/sectionNavSpy';
 export { default as Slider } from './components/basic/Slider.svelte';
 export { default as Pagination } from './components/basic/Pagination.svelte';
+// Snapshot undo/redo history (wayflow-core) — also importable as 'jatui/history' (jatui-00jfh).
+export { MAX_UNDO_DEPTH, createHistory, pushState, beginChange, endChange, untracked, undo, redo, clearHistory } from './history';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -17,6 +17,10 @@
       "svelte": "./dist/dnd/index.js",
       "default": "./dist/dnd/index.js"
     },
+    "./history": {
+      "types": "./dist/history.d.ts",
+      "default": "./dist/history.js"
+    },
     "./styles/rail.css": "./dist/styles/rail.css",
     "./showcase": {
       "types": "./dist/showcase/index.d.ts",