@textcortex/slidewise 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textcortex/slidewise",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Embeddable React PPTX editor.",
   "license": "MIT",
   "type": "module",

package/src/SlidewiseEditor.tsx

@@ -1,5 +1,10 @@
 import { forwardRef, type CSSProperties } from "react";
-import { Root, type SlidewiseRootHandle, type SlidewiseRootProps } from "./compound/SlidewiseRoot";
+import {
+  Root,
+  type SlidewiseRootHandle,
+  type SlidewiseRootProps,
+  type HistoryState,
+} from "./compound/SlidewiseRoot";
 import {
   TopBar,
   SlideRail,
@@ -30,6 +35,11 @@ export interface SlidewiseEditorProps {
   onExport?: (deck: Deck) => void;
   /** Fires when the dirty flag flips. Useful for "unsaved changes" banners. */
   onDirtyChange?: (dirty: boolean) => void;
+  /**
+   * Fires whenever the undo/redo stack depths change. Use this to enable/disable
+   * Undo and Redo buttons reactively without polling `api.canUndo()`.
+   */
+  onHistoryChange?: (state: HistoryState) => void;
   /** Reserved for future use; not enforced yet. */
   readOnly?: boolean;
   /** "light" or "dark"; defaults to "light". Ignored after first render. */
@@ -86,6 +96,7 @@ export const SlidewiseEditor = forwardRef<
     onSave,
     onExport,
     onDirtyChange,
+    onHistoryChange,
     readOnly,
     theme,
     initialSlideId,
@@ -104,6 +115,7 @@ export const SlidewiseEditor = forwardRef<
     onSave,
     onExport,
     onDirtyChange,
+    onHistoryChange,
     readOnly,
     theme,
     initialSlideId,

package/src/SlidewiseFileEditor.tsx

@@ -10,6 +10,7 @@ import { SlidewiseEditor, type SlidewiseEditorHandle } from "./SlidewiseEditor";
 import { parsePptx, serializeDeck } from "@/lib/pptx";
 import type { Deck } from "@/lib/types";
 import type { SlidewiseIcons } from "./compound/IconContext";
+import type { HistoryState } from "./compound/SlidewiseRoot";
 
 export interface SlidewiseFileEditorProps {
   /**
@@ -48,6 +49,12 @@ export interface SlidewiseFileEditorProps {
    * `api.isDirty()` for "unsaved changes" UI.
    */
   onDirtyChange?: (dirty: boolean) => void;
+  /**
+   * Fires whenever the undo/redo stack depths change. Use this to enable/
+   * disable host-rendered Undo/Redo buttons reactively without polling
+   * `api.canUndo()` / `api.canRedo()`.
+   */
+  onHistoryChange?: (state: HistoryState) => void;
   /**
    * Fires when `loadBlob` or `parse` throws on mount. The default render
    * still shows an in-editor "Could not open file" message, but hosts that
@@ -94,6 +101,19 @@ export interface SlidewiseFileEditorApi {
   stop(): void;
   undo(): void;
   redo(): void;
+  /** True iff there's at least one snapshot to undo back to. */
+  canUndo(): boolean;
+  /** True iff there's at least one snapshot to redo forward to. */
+  canRedo(): boolean;
+  /** Current undo/redo stack depths. */
+  getHistorySize(): { undo: number; redo: number };
+  /**
+   * End the in-flight coalesce burst. Call on natural commit boundaries
+   * (mouseup after drag, blur on a text input) so the next mutation starts
+   * a fresh history step. Most hosts won't need this — a 500ms idle window
+   * handles typical typing/drag bursts automatically.
+   */
+  endCoalesce(): void;
   /** Live deck snapshot. Hosts use this for header badges (slide count, etc.). */
   getDeck(): Deck | null;
   getInitialSha256(): string | null;
@@ -117,6 +137,7 @@ export const SlidewiseFileEditor = forwardRef<
     onChange,
     onDirtyChange,
     onLoadError,
+    onHistoryChange,
     theme,
     initialSlideId,
     showTopBar,
@@ -185,6 +206,11 @@ export const SlidewiseFileEditor = forwardRef<
       stop: () => editorRef.current?.stop(),
       undo: () => editorRef.current?.undo(),
       redo: () => editorRef.current?.redo(),
+      canUndo: () => editorRef.current?.canUndo() ?? false,
+      canRedo: () => editorRef.current?.canRedo() ?? false,
+      getHistorySize: () =>
+        editorRef.current?.getHistorySize() ?? { undo: 0, redo: 0 },
+      endCoalesce: () => editorRef.current?.endCoalesce(),
       getDeck: () => editorRef.current?.getDeck() ?? state.deck,
       getInitialSha256: () => initialSha256,
     };
@@ -210,6 +236,11 @@ export const SlidewiseFileEditor = forwardRef<
       stop: () => editorRef.current?.stop(),
       undo: () => editorRef.current?.undo(),
       redo: () => editorRef.current?.redo(),
+      canUndo: () => editorRef.current?.canUndo() ?? false,
+      canRedo: () => editorRef.current?.canRedo() ?? false,
+      getHistorySize: () =>
+        editorRef.current?.getHistorySize() ?? { undo: 0, redo: 0 },
+      endCoalesce: () => editorRef.current?.endCoalesce(),
       getDeck: () =>
         state.status === "ready"
           ? editorRef.current?.getDeck() ?? state.deck
@@ -255,6 +286,7 @@ export const SlidewiseFileEditor = forwardRef<
           setDirty(d);
           onDirtyChangeRef.current?.(d);
         }}
+        onHistoryChange={onHistoryChange}
         onSave={async (next) => {
           const blob = await serialize(next);
           await saveBlob(blob);

package/src/compound/SlidewiseRoot.tsx

@@ -36,6 +36,11 @@ export interface SlidewiseRootProps {
   onExport?: (deck: Deck) => void;
   /** Fires when the dirty flag flips. */
   onDirtyChange?: (dirty: boolean) => void;
+  /**
+   * Fires whenever the undo/redo stacks change depth. Use this to update
+   * "Undo"/"Redo" button enabled state without polling `canUndo()`/`canRedo()`.
+   */
+  onHistoryChange?: (state: HistoryState) => void;
   /**
    * Hide editing affordances (save / undo / redo) and disable canvas
    * mutations. Use this when the host viewer doesn't have write access.
@@ -59,11 +64,32 @@ export interface SlidewiseRootProps {
   style?: CSSProperties;
 }
 
+export interface HistoryState {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Snapshot counts. Useful for "X steps to redo" indicators. */
+  undoSize: number;
+  redoSize: number;
+}
+
 export interface SlidewiseRootHandle {
   play(): void;
   stop(): void;
   undo(): void;
   redo(): void;
+  /** True iff there's at least one snapshot to undo back to. */
+  canUndo(): boolean;
+  /** True iff there's at least one snapshot to redo forward to. */
+  canRedo(): boolean;
+  /** Current undo/redo stack depths. */
+  getHistorySize(): { undo: number; redo: number };
+  /**
+   * End the in-flight coalesce burst. Call on natural commit boundaries
+   * (mouseup after drag, blur on a text input) so the next mutation starts
+   * a fresh history step. Most hosts won't need this — the 500ms idle
+   * window handles typical typing/drag bursts.
+   */
+  endCoalesce(): void;
   getDeck(): Deck;
   isDirty(): boolean;
   resetDirty(): void;
@@ -95,6 +121,7 @@ function RootInner({
   onSave,
   onExport,
   onDirtyChange,
+  onHistoryChange: props_onHistoryChange,
   readOnly = false,
   theme,
   initialSlideId,
@@ -114,13 +141,15 @@ function RootInner({
   const onDirtyChangeRef = useRef(onDirtyChange);
   const onSaveRef = useRef(onSave);
   const onExportRef = useRef(onExport);
+  const onHistoryChangeRef = useRef(props_onHistoryChange);
 
   useEffect(() => {
     onChangeRef.current = onChange;
     onDirtyChangeRef.current = onDirtyChange;
     onSaveRef.current = onSave;
     onExportRef.current = onExport;
-  }, [onChange, onDirtyChange, onSave, onExport]);
+    onHistoryChangeRef.current = props_onHistoryChange;
+  }, [onChange, onDirtyChange, onSave, onExport, props_onHistoryChange]);
 
   useEffect(() => {
     if (theme) {
@@ -159,6 +188,21 @@ function RootInner({
       collectFontFamilies(store.getState().deck)
     );
     return store.subscribe((state, prev) => {
+      // Fire onHistoryChange whenever stack depths change. Independent of
+      // deck identity so undo/redo always emit, even if the resulting deck
+      // happens to be reference-equal (shouldn't, but defensive).
+      const prevHist = prev.history.length;
+      const prevFut = prev.future.length;
+      const nextHist = state.history.length;
+      const nextFut = state.future.length;
+      if (prevHist !== nextHist || prevFut !== nextFut) {
+        onHistoryChangeRef.current?.({
+          canUndo: nextHist > 0,
+          canRedo: nextFut > 0,
+          undoSize: nextHist,
+          redoSize: nextFut,
+        });
+      }
       if (state.deck === prev.deck) return;
       onChangeRef.current?.(state.deck);
       const nextDirty = state.deck !== savedDeckRef.current;
@@ -183,6 +227,13 @@ function RootInner({
       stop: () => store.getState().stop(),
       undo: () => store.getState().undo(),
       redo: () => store.getState().redo(),
+      canUndo: () => store.getState().canUndo(),
+      canRedo: () => store.getState().canRedo(),
+      getHistorySize: () => {
+        const s = store.getState();
+        return { undo: s.history.length, redo: s.future.length };
+      },
+      endCoalesce: () => store.getState().endCoalesce(),
       getDeck: () => store.getState().deck,
       isDirty: () => dirtyRef.current,
       resetDirty: () => {

package/src/compound/index.ts

@@ -27,6 +27,7 @@ export {
   Root,
   type SlidewiseRootProps,
   type SlidewiseRootHandle,
+  type HistoryState,
 } from "./SlidewiseRoot";
 export {
   TopBar,

package/src/index.ts

@@ -47,6 +47,7 @@ export {
   useReadOnly,
   type SlidewiseRootProps,
   type SlidewiseRootHandle,
+  type HistoryState,
   type SlidewiseHostCallbacks,
   type SlidewiseIcons,
   type RegionProps,

package/src/lib/__tests__/history.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { createEditorStore } from "../store";
+import { CURRENT_DECK_VERSION } from "../schema/migrate";
+import type { Deck } from "../types";
+
+const baseElement = { rotation: 0, z: 1 } as const;
+
+function fixtureDeck(): Deck {
+  return {
+    version: CURRENT_DECK_VERSION,
+    title: "Hist test",
+    slides: [
+      {
+        id: "s1",
+        background: "#FFFFFF",
+        elements: [
+          {
+            ...baseElement,
+            id: "t1",
+            type: "text",
+            x: 100,
+            y: 100,
+            w: 400,
+            h: 80,
+            text: "Hello",
+            fontFamily: "Inter",
+            fontSize: 24,
+            fontWeight: 400,
+            italic: false,
+            underline: false,
+            strike: false,
+            color: "#000000",
+            align: "left",
+            vAlign: "top",
+            lineHeight: 1.2,
+            letterSpacing: 0,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+describe("editor store history", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ now: 1_000_000 });
+  });
+
+  it("undo reverts an updateElement", () => {
+    const store = createEditorStore(fixtureDeck());
+    expect(store.getState().canUndo()).toBe(false);
+
+    store.getState().updateElement("t1", { x: 200 });
+    expect(store.getState().canUndo()).toBe(true);
+    const slide = () => store.getState().deck.slides[0];
+    expect((slide().elements[0] as { x: number }).x).toBe(200);
+
+    store.getState().undo();
+    expect((slide().elements[0] as { x: number }).x).toBe(100);
+    expect(store.getState().canUndo()).toBe(false);
+    expect(store.getState().canRedo()).toBe(true);
+  });
+
+  it("undo reverts a setTitle", () => {
+    const store = createEditorStore(fixtureDeck());
+    store.getState().setTitle("Renamed");
+    expect(store.getState().deck.title).toBe("Renamed");
+    store.getState().undo();
+    expect(store.getState().deck.title).toBe("Hist test");
+  });
+
+  it("coalesces a typing burst into one undo step", () => {
+    const store = createEditorStore(fixtureDeck());
+    // simulate keystrokes within the idle window
+    store.getState().updateElement("t1", { x: 110 });
+    vi.advanceTimersByTime(50);
+    store.getState().updateElement("t1", { x: 120 });
+    vi.advanceTimersByTime(50);
+    store.getState().updateElement("t1", { x: 130 });
+
+    expect(store.getState().history.length).toBe(1);
+
+    store.getState().undo();
+    const elX = (store.getState().deck.slides[0].elements[0] as { x: number }).x;
+    expect(elX).toBe(100);
+  });
+
+  it("starts a new history step after the idle window expires", () => {
+    const store = createEditorStore(fixtureDeck());
+    store.getState().updateElement("t1", { x: 110 });
+    expect(store.getState().history.length).toBe(1);
+
+    // advance past the 500ms idle window
+    vi.advanceTimersByTime(600);
+
+    store.getState().updateElement("t1", { x: 120 });
+    expect(store.getState().history.length).toBe(2);
+
+    store.getState().undo();
+    expect((store.getState().deck.slides[0].elements[0] as { x: number }).x).toBe(110);
+
+    store.getState().undo();
+    expect((store.getState().deck.slides[0].elements[0] as { x: number }).x).toBe(100);
+  });
+
+  it("endCoalesce starts a fresh step on the next mutation", () => {
+    const store = createEditorStore(fixtureDeck());
+    store.getState().updateElement("t1", { x: 110 });
+    store.getState().updateElement("t1", { x: 120 });
+    expect(store.getState().history.length).toBe(1);
+
+    store.getState().endCoalesce();
+    store.getState().updateElement("t1", { x: 130 });
+    expect(store.getState().history.length).toBe(2);
+  });
+
+  it("different patch keys on the same element start a fresh step", () => {
+    const store = createEditorStore(fixtureDeck());
+    store.getState().updateElement("t1", { x: 110 });
+    store.getState().updateElement("t1", { y: 110 });
+    // Different keys → different coalesce key → second step pushed.
+    expect(store.getState().history.length).toBe(2);
+  });
+
+  it("setDeck clears history", () => {
+    const store = createEditorStore(fixtureDeck());
+    store.getState().updateElement("t1", { x: 200 });
+    expect(store.getState().history.length).toBe(1);
+
+    store.getState().setDeck(fixtureDeck());
+    expect(store.getState().history.length).toBe(0);
+    expect(store.getState().future.length).toBe(0);
+    expect(store.getState().canUndo()).toBe(false);
+  });
+
+  it("undo/redo update canUndo/canRedo correctly", () => {
+    const store = createEditorStore(fixtureDeck());
+    store.getState().updateElement("t1", { x: 200 });
+    expect(store.getState().canUndo()).toBe(true);
+    expect(store.getState().canRedo()).toBe(false);
+
+    store.getState().undo();
+    expect(store.getState().canUndo()).toBe(false);
+    expect(store.getState().canRedo()).toBe(true);
+
+    store.getState().redo();
+    expect(store.getState().canUndo()).toBe(true);
+    expect(store.getState().canRedo()).toBe(false);
+  });
+
+  it("undo replaces the deck reference (so subscribers see a change)", () => {
+    const store = createEditorStore(fixtureDeck());
+    const before = store.getState().deck;
+    store.getState().updateElement("t1", { x: 200 });
+    const afterEdit = store.getState().deck;
+    expect(afterEdit).not.toBe(before);
+
+    store.getState().undo();
+    const afterUndo = store.getState().deck;
+    expect(afterUndo).not.toBe(afterEdit);
+    // value matches the pre-edit deck even if the reference is a clone
+    expect((afterUndo.slides[0].elements[0] as { x: number }).x).toBe(100);
+  });
+});

package/src/lib/store.ts

@@ -29,6 +29,17 @@ interface HistorySnapshot {
 type Theme = "light" | "dark";
 type View = "editor" | "grid";
 
+/**
+ * Idle window in ms during which consecutive mutations with the same coalesce
+ * key collapse into a single history step. After this many ms with no edit,
+ * the next edit starts a fresh step. Drags on a single element typically run
+ * 60+ frames in well under this window; typing pauses around word boundaries
+ * usually exceed it. Hosts that want stricter granularity can call
+ * `endCoalesce()` explicitly (e.g. on mouseup or input blur).
+ */
+const COALESCE_IDLE_MS = 500;
+const HISTORY_LIMIT = 50;
+
 export interface EditorState {
   deck: Deck;
   currentSlideId: string;
@@ -41,6 +52,14 @@ export interface EditorState {
   view: View;
   history: HistorySnapshot[];
   future: HistorySnapshot[];
+  /**
+   * Coalesce key for the in-flight mutation burst. Two consecutive mutations
+   * with the same key (within `COALESCE_IDLE_MS`) collapse into one history
+   * step. `null` means "no burst in progress" — the next edit pushes a fresh
+   * snapshot.
+   */
+  _coalesceKey: string | null;
+  _coalesceUntil: number;
 
   // selectors
   currentSlide: () => Slide;
@@ -68,6 +87,23 @@ export interface EditorState {
   undo: () => void;
   redo: () => void;
   pushHistory: () => void;
+  /**
+   * Push a history snapshot, but only if `key` differs from the in-flight
+   * coalesce key OR more than `COALESCE_IDLE_MS` have passed since the last
+   * mutation. Use this for high-frequency edits (text typing, drag) so the
+   * burst collapses into one undo step.
+   */
+  pushHistoryCoalesced: (key: string) => void;
+  /**
+   * End the current coalesce burst. Hosts call this on natural commit
+   * boundaries (mouseup after a drag, blur on a text input) so the next
+   * mutation starts a fresh history step even within `COALESCE_IDLE_MS`.
+   */
+  endCoalesce: () => void;
+  /** True iff there's at least one snapshot to undo back to. */
+  canUndo: () => boolean;
+  /** True iff there's at least one snapshot to redo forward to. */
+  canRedo: () => boolean;
   setDeck: (deck: Deck) => void;
   setTheme: (t: Theme) => void;
   toggleTheme: () => void;
@@ -107,6 +143,8 @@ export function createEditorStore(initialDeck: Deck): EditorStore {
     view: "editor",
     history: [],
     future: [],
+    _coalesceKey: null,
+    _coalesceUntil: 0,
 
     currentSlide: () => {
       const s = get();
@@ -118,20 +156,48 @@ export function createEditorStore(initialDeck: Deck): EditorStore {
 
     pushHistory: () => {
       set((s) => ({
-        history: [...s.history, snap(s)].slice(-50),
+        history: [...s.history, snap(s)].slice(-HISTORY_LIMIT),
         future: [],
+        _coalesceKey: null,
+        _coalesceUntil: 0,
       }));
     },
 
+    pushHistoryCoalesced: (key) => {
+      const now = Date.now();
+      set((s) => {
+        // Same burst within the idle window → don't push, just extend.
+        if (s._coalesceKey === key && now < s._coalesceUntil) {
+          return { _coalesceUntil: now + COALESCE_IDLE_MS };
+        }
+        // New burst — snapshot the pre-mutation state and start coalescing.
+        return {
+          history: [...s.history, snap(s)].slice(-HISTORY_LIMIT),
+          future: [],
+          _coalesceKey: key,
+          _coalesceUntil: now + COALESCE_IDLE_MS,
+        };
+      });
+    },
+
+    endCoalesce: () => {
+      set({ _coalesceKey: null, _coalesceUntil: 0 });
+    },
+
+    canUndo: () => get().history.length > 0,
+    canRedo: () => get().future.length > 0,
+
     setTool: (t) => set({ tool: t }),
     setTitle: (t) => {
+      get().pushHistoryCoalesced("setTitle");
       set((s) => ({ deck: { ...s.deck, title: t } }));
     },
     setZoom: (z) =>
       set({ zoom: Math.max(0.1, Math.min(4, z)), fitMode: "manual" }),
     setFitMode: (f) => set({ fitMode: f }),
 
-    selectSlide: (id) => set({ currentSlideId: id, selectedIds: [] }),
+    selectSlide: (id) =>
+      set({ currentSlideId: id, selectedIds: [], _coalesceKey: null }),
     selectElement: (id, additive) =>
       set((s) => {
         if (id == null) return { selectedIds: [] };
@@ -228,6 +294,11 @@ export function createEditorStore(initialDeck: Deck): EditorStore {
     },
 
     updateElement: (id, patch) => {
+      // Coalesce key: same element, same patch shape = same burst.
+      // Drag (x,y) coalesces; resize (w,h) starts a new burst even on the
+      // same element; switching elements also starts fresh.
+      const key = `updateElement:${id}:${Object.keys(patch).sort().join(",")}`;
+      get().pushHistoryCoalesced(key);
       set((s) => {
         const slides = s.deck.slides.map((sl) => {
           if (sl.id !== s.currentSlideId) return sl;
@@ -320,8 +391,10 @@ export function createEditorStore(initialDeck: Deck): EditorStore {
           deck: last.deck,
           currentSlideId: last.currentSlideId,
           history: s.history.slice(0, -1),
-          future: [...s.future, snapshot].slice(-50),
+          future: [...s.future, snapshot].slice(-HISTORY_LIMIT),
           selectedIds: survivingIds,
+          _coalesceKey: null,
+          _coalesceUntil: 0,
         };
       });
     },
@@ -342,9 +415,11 @@ export function createEditorStore(initialDeck: Deck): EditorStore {
         return {
           deck: next.deck,
           currentSlideId: next.currentSlideId,
-          history: [...s.history, snapshot].slice(-50),
+          history: [...s.history, snapshot].slice(-HISTORY_LIMIT),
           future: s.future.slice(0, -1),
           selectedIds: survivingIds,
+          _coalesceKey: null,
+          _coalesceUntil: 0,
         };
       });
     },
@@ -357,6 +432,8 @@ export function createEditorStore(initialDeck: Deck): EditorStore {
         selectedIds: [],
         history: [],
         future: [],
+        _coalesceKey: null,
+        _coalesceUntil: 0,
       });
     },