@voidhash/mimic-react 0.0.1-alpha.10

package/src/zustand-commander/commander.ts

@@ -0,0 +1,395 @@
+/**
+ * @voidhash/mimic-react/zustand-commander
+ *
+ * Commander creation and command definition.
+ *
+ * @since 0.0.1
+ */
+
+import type { StoreApi } from "zustand";
+import {
+  COMMAND_SYMBOL,
+  UNDOABLE_COMMAND_SYMBOL,
+  isUndoableCommand,
+  type AnyEffectSchema,
+  type Command,
+  type Commander,
+  type CommanderOptions,
+  type CommanderSlice,
+  type CommandContext,
+  type CommandDispatch,
+  type CommandFn,
+  type InferSchemaType,
+  type RevertFn,
+  type UndoableCommand,
+  type UndoEntry,
+} from "./types.js";
+
+// =============================================================================
+// Default Options
+// =============================================================================
+
+const DEFAULT_OPTIONS: Required<CommanderOptions> = {
+  maxUndoStackSize: 100,
+};
+
+// =============================================================================
+// Commander Implementation
+// =============================================================================
+
+/**
+ * Creates a commander instance bound to a specific store type.
+ *
+ * @example
+ * ```ts
+ * // Create commander for your store type
+ * const commander = createCommander<StoreState>();
+ *
+ * // Define commands
+ * const addItem = commander.action(
+ *   Schema.Struct({ name: Schema.String }),
+ *   (ctx, params) => {
+ *     const { mimic } = ctx.getState();
+ *     mimic.document.transaction(root => {
+ *       // add item
+ *     });
+ *   }
+ * );
+ *
+ * // Create store with middleware
+ * const useStore = create(
+ *   commander.middleware(
+ *     mimic(document, (set, get) => ({
+ *       // your state
+ *     }))
+ *   )
+ * );
+ * ```
+ */
+export function createCommander<TStore extends object>(
+  options: CommanderOptions = {}
+): Commander<TStore & CommanderSlice> {
+  const { maxUndoStackSize } = { ...DEFAULT_OPTIONS, ...options };
+
+  // Track the store API once middleware is applied
+  let _storeApi: StoreApi<TStore & CommanderSlice> | null = null;
+
+  /**
+   * Creates the dispatch function for use within command handlers.
+   */
+  const createDispatch = (): CommandDispatch<TStore & CommanderSlice> => {
+    return <TParams, TReturn>(
+      command: Command<TStore & CommanderSlice, TParams, TReturn>
+    ) => {
+      return (params: TParams): TReturn => {
+        if (!_storeApi) {
+          throw new Error(
+            "Commander: Store not initialized. Make sure to use the commander middleware."
+          );
+        }
+
+        // Create context for the command
+        const ctx: CommandContext<TStore & CommanderSlice> = {
+          getState: () => _storeApi!.getState(),
+          setState: (partial) => _storeApi!.setState(partial as any),
+          dispatch: createDispatch(),
+        };
+
+        // Execute the command
+        const result = command.fn(ctx, params);
+
+        // If it's an undoable command, add to undo stack
+        if (isUndoableCommand(command)) {
+          const entry: UndoEntry<TParams, TReturn> = {
+            command,
+            params,
+            result,
+            timestamp: Date.now(),
+          };
+
+          _storeApi.setState((state: TStore & CommanderSlice) => {
+            const { undoStack, redoStack } = state._commander;
+
+            // Add to undo stack, respecting max size
+            const newUndoStack = [...undoStack, entry].slice(-maxUndoStackSize);
+
+            // Clear redo stack when a new command is executed
+            return {
+              ...state,
+              _commander: {
+                undoStack: newUndoStack,
+                redoStack: [],
+              },
+            };
+          });
+        }
+
+        return result;
+      };
+    };
+  };
+
+  /**
+   * Create a regular command (no undo support).
+   */
+  function action<TParamsSchema extends AnyEffectSchema, TReturn = void>(
+    paramsSchema: TParamsSchema,
+    fn: CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>
+  ): Command<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>;
+  function action<TReturn = void>(
+    fn: CommandFn<TStore & CommanderSlice, void, TReturn>
+  ): Command<TStore & CommanderSlice, void, TReturn>;
+  function action<TParamsSchema extends AnyEffectSchema, TReturn = void>(
+    paramsSchemaOrFn:
+      | TParamsSchema
+      | CommandFn<TStore & CommanderSlice, void, TReturn>,
+    maybeFn?: CommandFn<
+      TStore & CommanderSlice,
+      InferSchemaType<TParamsSchema>,
+      TReturn
+    >
+  ): Command<TStore & CommanderSlice, any, TReturn> {
+    // Check if we have two arguments (schema + fn) or just one (fn only)
+    if (maybeFn !== undefined) {
+      // First arg is schema, second is fn
+      return {
+        [COMMAND_SYMBOL]: true,
+        fn: maybeFn,
+        paramsSchema: paramsSchemaOrFn as TParamsSchema,
+      };
+    }
+
+    // Single argument - must be the action function (no params schema)
+    if (typeof paramsSchemaOrFn !== "function") {
+      throw new Error("Commander: action requires a function");
+    }
+
+    return {
+      [COMMAND_SYMBOL]: true,
+      fn: paramsSchemaOrFn as CommandFn<TStore & CommanderSlice, void, TReturn>,
+      paramsSchema: null,
+    };
+  }
+
+  /**
+   * Create an undoable command with undo/redo support.
+   */
+  function undoableAction<TParamsSchema extends AnyEffectSchema, TReturn>(
+    paramsSchema: TParamsSchema,
+    fn: CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>,
+    revert: RevertFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>
+  ): UndoableCommand<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>;
+  function undoableAction<TReturn>(
+    fn: CommandFn<TStore & CommanderSlice, void, TReturn>,
+    revert: RevertFn<TStore & CommanderSlice, void, TReturn>
+  ): UndoableCommand<TStore & CommanderSlice, void, TReturn>;
+  function undoableAction<TParamsSchema extends AnyEffectSchema, TReturn>(
+    paramsSchemaOrFn:
+      | TParamsSchema
+      | CommandFn<TStore & CommanderSlice, void, TReturn>,
+    fnOrRevert:
+      | CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>
+      | RevertFn<TStore & CommanderSlice, void, TReturn>,
+    maybeRevert?: RevertFn<
+      TStore & CommanderSlice,
+      InferSchemaType<TParamsSchema>,
+      TReturn
+    >
+  ): UndoableCommand<TStore & CommanderSlice, any, TReturn> {
+    // Check if we have three arguments (schema + fn + revert) or two (fn + revert)
+    if (maybeRevert !== undefined) {
+      // First arg is schema, second is fn, third is revert
+      return {
+        [COMMAND_SYMBOL]: true,
+        [UNDOABLE_COMMAND_SYMBOL]: true,
+        fn: fnOrRevert as CommandFn<
+          TStore & CommanderSlice,
+          InferSchemaType<TParamsSchema>,
+          TReturn
+        >,
+        paramsSchema: paramsSchemaOrFn as TParamsSchema,
+        revert: maybeRevert,
+      };
+    }
+
+    // Two arguments - fn + revert (no params schema)
+    if (typeof paramsSchemaOrFn !== "function") {
+      throw new Error("Commander: undoableAction requires a function");
+    }
+
+    return {
+      [COMMAND_SYMBOL]: true,
+      [UNDOABLE_COMMAND_SYMBOL]: true,
+      fn: paramsSchemaOrFn as CommandFn<TStore & CommanderSlice, void, TReturn>,
+      paramsSchema: null,
+      revert: fnOrRevert as RevertFn<TStore & CommanderSlice, void, TReturn>,
+    };
+  }
+
+  /**
+   * Zustand middleware that adds commander functionality.
+   */
+  const middleware = <T extends object>(
+    config: (
+      set: StoreApi<T & CommanderSlice>["setState"],
+      get: StoreApi<T & CommanderSlice>["getState"],
+      api: StoreApi<T & CommanderSlice>
+    ) => T
+  ) => {
+    return (
+      set: StoreApi<T & CommanderSlice>["setState"],
+      get: StoreApi<T & CommanderSlice>["getState"],
+      api: StoreApi<T & CommanderSlice>
+    ): T & CommanderSlice => {
+      // Store the API reference for dispatch
+      _storeApi = api as unknown as StoreApi<TStore & CommanderSlice>;
+
+      // Get user's state
+      const userState = config(set, get, api);
+
+      // Add commander slice
+      return {
+        ...userState,
+        _commander: {
+          undoStack: [],
+          redoStack: [],
+        },
+      };
+    };
+  };
+
+  return {
+    action,
+    undoableAction,
+    middleware: middleware as Commander<TStore & CommanderSlice>["middleware"],
+  };
+}
+
+// =============================================================================
+// Undo/Redo Functions
+// =============================================================================
+
+/**
+ * Perform an undo operation on the store.
+ * Returns true if an undo was performed, false if undo stack was empty.
+ */
+export function performUndo<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>
+): boolean {
+  const state = storeApi.getState();
+  const { undoStack, redoStack } = state._commander;
+
+  // Pop the last entry from undo stack
+  const entry = undoStack[undoStack.length - 1];
+  if (!entry) {
+    return false;
+  }
+
+  const newUndoStack = undoStack.slice(0, -1);
+
+  // Create context for the revert function
+  const ctx: CommandContext<TStore> = {
+    getState: () => storeApi.getState(),
+    setState: (partial) => storeApi.setState(partial as any),
+    dispatch: createDispatchForUndo(storeApi),
+  };
+
+  // Execute the revert function
+  entry.command.revert(ctx, entry.params, entry.result);
+
+  // Move entry to redo stack
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      undoStack: newUndoStack,
+      redoStack: [...redoStack, entry],
+    },
+  }));
+
+  return true;
+}
+
+/**
+ * Perform a redo operation on the store.
+ * Returns true if a redo was performed, false if redo stack was empty.
+ */
+export function performRedo<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>
+): boolean {
+  const state = storeApi.getState();
+  const { undoStack, redoStack } = state._commander;
+
+  // Pop the last entry from redo stack
+  const entry = redoStack[redoStack.length - 1];
+  if (!entry) {
+    return false;
+  }
+
+  const newRedoStack = redoStack.slice(0, -1);
+
+  // Create context for re-executing the command
+  const ctx: CommandContext<TStore> = {
+    getState: () => storeApi.getState(),
+    setState: (partial) => storeApi.setState(partial as any),
+    dispatch: createDispatchForUndo(storeApi),
+  };
+
+  // Re-execute the command
+  const result = entry.command.fn(ctx, entry.params);
+
+  // Create new entry with potentially new result
+  const newEntry: UndoEntry = {
+    command: entry.command,
+    params: entry.params,
+    result,
+    timestamp: Date.now(),
+  };
+
+  // Move entry back to undo stack
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      undoStack: [...undoStack, newEntry],
+      redoStack: newRedoStack,
+    },
+  }));
+
+  return true;
+}
+
+/**
+ * Creates a dispatch function for use during undo/redo operations.
+ * This dispatch does NOT add to undo stack (to avoid infinite loops).
+ */
+function createDispatchForUndo<TStore>(
+  storeApi: StoreApi<TStore>
+): CommandDispatch<TStore> {
+  return <TParams, TReturn>(command: Command<TStore, TParams, TReturn>) => {
+    return (params: TParams): TReturn => {
+      const ctx: CommandContext<TStore> = {
+        getState: () => storeApi.getState(),
+        setState: (partial) => storeApi.setState(partial as any),
+        dispatch: createDispatchForUndo(storeApi),
+      };
+
+      // Execute without adding to undo stack
+      return command.fn(ctx, params);
+    };
+  };
+}
+
+/**
+ * Clear the undo and redo stacks.
+ */
+export function clearUndoHistory<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>
+): void {
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      undoStack: [],
+      redoStack: [],
+    },
+  }));
+}
+

package/src/zustand-commander/hooks.ts

@@ -0,0 +1,259 @@
+/**
+ * @voidhash/mimic-react/zustand-commander
+ *
+ * React hooks for zustand-commander.
+ *
+ * @since 0.0.1
+ */
+
+import { useCallback, useEffect, useMemo } from "react";
+import { useStore, type StoreApi, type UseBoundStore } from "zustand";
+import { performRedo, performUndo, clearUndoHistory } from "./commander";
+import {
+  isUndoableCommand,
+  type Command,
+  type CommandContext,
+  type CommandDispatch,
+  type CommanderSlice,
+  type ExtractState,
+} from "./types.js";
+
+// =============================================================================
+// useCommander Hook
+// =============================================================================
+
+/**
+ * Creates a dispatch function for commands.
+ * This is for use outside of React components (e.g., in command handlers).
+ */
+function createDispatchFromApi<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>,
+  maxUndoStackSize = 100
+): CommandDispatch<TStore> {
+  const dispatch: CommandDispatch<TStore> = <TParams, TReturn>(
+    command: Command<TStore, TParams, TReturn>
+  ) => {
+    return (params: TParams): TReturn => {
+      // Create context for the command
+      const ctx: CommandContext<TStore> = {
+        getState: () => storeApi.getState(),
+        setState: (partial) => storeApi.setState(partial as Partial<TStore>),
+        dispatch,
+      };
+
+      // Execute the command
+      const result = command.fn(ctx, params);
+
+      // If it's an undoable command, add to undo stack
+      if (isUndoableCommand(command)) {
+        storeApi.setState((state: TStore) => {
+          const { undoStack } = state._commander;
+
+          // Add to undo stack, respecting max size
+          const newUndoStack = [
+            ...undoStack,
+            {
+              command,
+              params,
+              result,
+              timestamp: Date.now(),
+            },
+          ].slice(-maxUndoStackSize);
+
+          // Clear redo stack when a new command is executed
+          return {
+            ...state,
+            _commander: {
+              undoStack: newUndoStack,
+              redoStack: [],
+            },
+          } as TStore;
+        });
+      }
+
+      return result;
+    };
+  };
+
+  return dispatch;
+}
+
+/**
+ * React hook to get a dispatch function for commands.
+ * The dispatch function executes commands and manages undo/redo state.
+ *
+ * @example
+ * ```tsx
+ * const dispatch = useCommander(useStore);
+ *
+ * const handleClick = () => {
+ *   dispatch(addCard)({ columnId: "col-1", title: "New Card" });
+ * };
+ * ```
+ */
+export function useCommander<TStore extends CommanderSlice>(
+  store: UseBoundStore<StoreApi<TStore>>
+): CommandDispatch<TStore> {
+  // Get the store API
+  const storeApi = useMemo(() => {
+    // UseBoundStore has the StoreApi attached
+    return store as unknown as StoreApi<TStore>;
+  }, [store]);
+
+  // Create a stable dispatch function
+  const dispatch = useMemo(
+    () => createDispatchFromApi<TStore>(storeApi),
+    [storeApi]
+  );
+
+  return dispatch as CommandDispatch<TStore>;
+}
+
+// =============================================================================
+// useUndoRedo Hook
+// =============================================================================
+
+/**
+ * State and actions for undo/redo functionality.
+ */
+export interface UndoRedoState {
+  /** Whether there are actions that can be undone */
+  readonly canUndo: boolean;
+  /** Whether there are actions that can be redone */
+  readonly canRedo: boolean;
+  /** Number of items in the undo stack */
+  readonly undoCount: number;
+  /** Number of items in the redo stack */
+  readonly redoCount: number;
+  /** Undo the last action */
+  readonly undo: () => boolean;
+  /** Redo the last undone action */
+  readonly redo: () => boolean;
+  /** Clear the undo/redo history */
+  readonly clear: () => void;
+}
+
+/**
+ * React hook for undo/redo functionality.
+ * Provides state (canUndo, canRedo) and actions (undo, redo, clear).
+ *
+ * @example
+ * ```tsx
+ * const { canUndo, canRedo, undo, redo } = useUndoRedo(useStore);
+ *
+ * return (
+ *   <>
+ *     <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *     <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *   </>
+ * );
+ * ```
+ */
+export function useUndoRedo<TStore extends CommanderSlice>(
+  store: UseBoundStore<StoreApi<TStore>>
+): UndoRedoState {
+  // Get the store API
+  const storeApi = useMemo(() => {
+    return store as unknown as StoreApi<TStore>;
+  }, [store]);
+
+  // Subscribe to commander state
+  const commanderState = useStore(
+    store,
+    (state: TStore) => state._commander
+  );
+
+  const canUndo = commanderState.undoStack.length > 0;
+  const canRedo = commanderState.redoStack.length > 0;
+  const undoCount = commanderState.undoStack.length;
+  const redoCount = commanderState.redoStack.length;
+
+  const undo = useCallback(() => {
+    return performUndo(storeApi);
+  }, [storeApi]);
+
+  const redo = useCallback(() => {
+    return performRedo(storeApi);
+  }, [storeApi]);
+
+  const clear = useCallback(() => {
+    clearUndoHistory(storeApi);
+  }, [storeApi]);
+
+  return {
+    canUndo,
+    canRedo,
+    undoCount,
+    redoCount,
+    undo,
+    redo,
+    clear,
+  };
+}
+
+// =============================================================================
+// Keyboard Shortcut Hook
+// =============================================================================
+
+/**
+ * Options for the keyboard shortcut hook.
+ */
+export interface UseUndoRedoKeyboardOptions {
+  /** Enable Ctrl/Cmd+Z for undo (default: true) */
+  readonly enableUndo?: boolean;
+  /** Enable Ctrl/Cmd+Shift+Z or Ctrl+Y for redo (default: true) */
+  readonly enableRedo?: boolean;
+}
+
+/**
+ * React hook that adds keyboard shortcuts for undo/redo.
+ * Listens for Ctrl/Cmd+Z (undo) and Ctrl/Cmd+Shift+Z or Ctrl+Y (redo).
+ *
+ * @example
+ * ```tsx
+ * // In your app component
+ * useUndoRedoKeyboard(useStore);
+ * ```
+ */
+export function useUndoRedoKeyboard<TStore extends CommanderSlice>(
+  store: UseBoundStore<StoreApi<TStore>>,
+  options: UseUndoRedoKeyboardOptions = {}
+): void {
+  const { enableUndo = true, enableRedo = true } = options;
+
+  const storeApi = useMemo(() => {
+    return store as unknown as StoreApi<TStore>;
+  }, [store]);
+
+  // Set up keyboard listener
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const isMac = navigator.platform.toUpperCase().indexOf("MAC") >= 0;
+      const modKey = isMac ? event.metaKey : event.ctrlKey;
+
+      if (!modKey) return;
+
+      // Undo: Ctrl/Cmd + Z (without Shift)
+      if (enableUndo && event.key === "z" && !event.shiftKey) {
+        event.preventDefault();
+        performUndo(storeApi);
+        return;
+      }
+
+      // Redo: Ctrl/Cmd + Shift + Z or Ctrl + Y
+      if (enableRedo) {
+        if ((event.key === "z" && event.shiftKey) || event.key === "y") {
+          event.preventDefault();
+          performRedo(storeApi);
+        }
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [storeApi, enableUndo, enableRedo]);
+}