@voidhash/mimic-react 1.0.0-beta.13 → 1.0.0-beta.15

package/src/zustand-commander/commander.ts

@@ -7,6 +7,8 @@
  */
 
 import type { StoreApi } from "zustand";
+import type { Primitive } from "@voidhash/mimic";
+import type { ClientDocument } from "@voidhash/mimic/client";
 import {
   COMMAND_SYMBOL,
   UNDOABLE_COMMAND_SYMBOL,
@@ -31,6 +33,34 @@ const DEFAULT_OPTIONS: Required<CommanderOptions> = {
   maxUndoStackSize: 100,
 };
 
+// =============================================================================
+// Transaction Helper
+// =============================================================================
+
+/**
+ * Build a transaction function that routes to draft or document.
+ */
+function buildTransaction<TStore extends CommanderSlice, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive>(
+  storeApi: StoreApi<TStore>
+): (fn: (root: Primitive.InferProxy<TSchema>) => void) => void {
+  return (fn) => {
+    const state = storeApi.getState();
+    const draft = state._commander.activeDraft;
+    if (draft) {
+      draft.update(fn);
+    } else {
+      // Access mimic.document from the store
+      const mimic = (state as any).mimic;
+      if (!mimic?.document) {
+        throw new Error(
+          "Commander: No active draft and no mimic document found on the store."
+        );
+      }
+      mimic.document.transaction(fn);
+    }
+  };
+}
+
 // =============================================================================
 // Commander Implementation
 // =============================================================================
@@ -47,8 +77,7 @@ const DEFAULT_OPTIONS: Required<CommanderOptions> = {
  * const addItem = commander.action(
  *   Schema.Struct({ name: Schema.String }),
  *   (ctx, params) => {
- *     const { mimic } = ctx.getState();
- *     mimic.document.transaction(root => {
+ *     ctx.transaction(root => {
  *       // add item
  *     });
  *   }
@@ -64,9 +93,9 @@ const DEFAULT_OPTIONS: Required<CommanderOptions> = {
  * );
  * ```
  */
-export function createCommander<TStore extends object>(
+export function createCommander<TStore extends object, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive>(
   options: CommanderOptions = {}
-): Commander<TStore & CommanderSlice> {
+): Commander<TStore & CommanderSlice, TSchema> {
   const { maxUndoStackSize } = { ...DEFAULT_OPTIONS, ...options };
 
   // Track the store API once middleware is applied
@@ -75,9 +104,9 @@ export function createCommander<TStore extends object>(
   /**
    * Creates the dispatch function for use within command handlers.
    */
-  const createDispatch = (): CommandDispatch<TStore & CommanderSlice> => {
+  const createDispatch = (): CommandDispatch<TStore & CommanderSlice, TSchema> => {
     return <TParams, TReturn>(
-      command: Command<TStore & CommanderSlice, TParams, TReturn>
+      command: Command<TStore & CommanderSlice, TParams, TReturn, TSchema>
     ) => {
       return (params: TParams): TReturn => {
         if (!_storeApi) {
@@ -87,17 +116,21 @@ export function createCommander<TStore extends object>(
         }
 
         // Create context for the command
-        const ctx: CommandContext<TStore & CommanderSlice> = {
+        const ctx: CommandContext<TStore & CommanderSlice, TSchema> = {
           getState: () => _storeApi!.getState(),
           setState: (partial) => _storeApi!.setState(partial as any),
           dispatch: createDispatch(),
+          transaction: buildTransaction<TStore & CommanderSlice, TSchema>(_storeApi!),
         };
 
         // Execute the command
         const result = command.fn(ctx, params);
 
-        // If it's an undoable command, add to undo stack
-        if (isUndoableCommand(command)) {
+        // Skip undo stack when a draft is active
+        const hasDraft = _storeApi!.getState()._commander.activeDraft !== null;
+
+        // If it's an undoable command and no draft is active, add to undo stack
+        if (isUndoableCommand(command) && !hasDraft) {
           const entry: UndoEntry<TParams, TReturn> = {
             command,
             params,
@@ -106,7 +139,7 @@ export function createCommander<TStore extends object>(
           };
 
           _storeApi.setState((state: TStore & CommanderSlice) => {
-            const { undoStack, redoStack } = state._commander;
+            const { undoStack, redoStack: _redoStack } = state._commander;
 
             // Add to undo stack, respecting max size
             const newUndoStack = [...undoStack, entry].slice(-maxUndoStackSize);
@@ -115,6 +148,7 @@ export function createCommander<TStore extends object>(
             return {
               ...state,
               _commander: {
+                ...state._commander,
                 undoStack: newUndoStack,
                 redoStack: [],
               },
@@ -131,8 +165,8 @@ export function createCommander<TStore extends object>(
    * Create a regular command (no undo support).
    */
   function action<TParams, TReturn = void>(
-    fn: CommandFn<TStore & CommanderSlice, TParams, TReturn>
-  ): Command<TStore & CommanderSlice, TParams, TReturn> {
+    fn: CommandFn<TStore & CommanderSlice, TParams, TReturn, TSchema>
+  ): Command<TStore & CommanderSlice, TParams, TReturn, TSchema> {
     return {
       [COMMAND_SYMBOL]: true,
       fn,
@@ -143,9 +177,9 @@ export function createCommander<TStore extends object>(
    * Create an undoable command with undo/redo support.
    */
   function undoableAction<TParams, TReturn>(
-    fn: CommandFn<TStore & CommanderSlice, TParams, TReturn>,
-    revert: RevertFn<TStore & CommanderSlice, TParams, TReturn>
-  ): UndoableCommand<TStore & CommanderSlice, TParams, TReturn> {
+    fn: CommandFn<TStore & CommanderSlice, TParams, TReturn, TSchema>,
+    revert: RevertFn<TStore & CommanderSlice, TParams, TReturn, TSchema>
+  ): UndoableCommand<TStore & CommanderSlice, TParams, TReturn, TSchema> {
     return {
       [COMMAND_SYMBOL]: true,
       [UNDOABLE_COMMAND_SYMBOL]: true,
@@ -181,6 +215,7 @@ export function createCommander<TStore extends object>(
         _commander: {
           undoStack: [],
           redoStack: [],
+          activeDraft: null,
         },
       };
     };
@@ -189,23 +224,64 @@ export function createCommander<TStore extends object>(
   return {
     action,
     undoableAction,
-    middleware: middleware as Commander<TStore & CommanderSlice>["middleware"],
+    middleware: middleware as Commander<TStore & CommanderSlice, TSchema>["middleware"],
   };
 }
 
+// =============================================================================
+// Draft Helpers
+// =============================================================================
+
+/**
+ * Set the active draft on the commander slice.
+ * While a draft is active, transactions route through `draft.update()` and undo is disabled.
+ */
+export function setActiveDraft<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>,
+  draft: ClientDocument.DraftHandle<any>
+): void {
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      ...state._commander,
+      activeDraft: draft,
+    },
+  }));
+}
+
+/**
+ * Clear the active draft from the commander slice.
+ */
+export function clearActiveDraft<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>
+): void {
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      ...state._commander,
+      activeDraft: null,
+    },
+  }));
+}
+
 // =============================================================================
 // Undo/Redo Functions
 // =============================================================================
 
 /**
  * Perform an undo operation on the store.
- * Returns true if an undo was performed, false if undo stack was empty.
+ * Returns true if an undo was performed, false if undo stack was empty or a draft is active.
  */
 export function performUndo<TStore extends CommanderSlice>(
   storeApi: StoreApi<TStore>
 ): boolean {
   const state = storeApi.getState();
-  const { undoStack, redoStack } = state._commander;
+  const { undoStack, redoStack, activeDraft } = state._commander;
+
+  // Undo is disabled while a draft is active
+  if (activeDraft) {
+    return false;
+  }
 
   // Pop the last entry from undo stack
   const entry = undoStack[undoStack.length - 1];
@@ -220,6 +296,7 @@ export function performUndo<TStore extends CommanderSlice>(
     getState: () => storeApi.getState(),
     setState: (partial) => storeApi.setState(partial as any),
     dispatch: createDispatchForUndo(storeApi),
+    transaction: buildTransaction(storeApi),
   };
 
   // Execute the revert function
@@ -229,6 +306,7 @@ export function performUndo<TStore extends CommanderSlice>(
   storeApi.setState((state: TStore) => ({
     ...state,
     _commander: {
+      ...state._commander,
       undoStack: newUndoStack,
       redoStack: [...redoStack, entry],
     },
@@ -239,13 +317,18 @@ export function performUndo<TStore extends CommanderSlice>(
 
 /**
  * Perform a redo operation on the store.
- * Returns true if a redo was performed, false if redo stack was empty.
+ * Returns true if a redo was performed, false if redo stack was empty or a draft is active.
  */
 export function performRedo<TStore extends CommanderSlice>(
   storeApi: StoreApi<TStore>
 ): boolean {
   const state = storeApi.getState();
-  const { undoStack, redoStack } = state._commander;
+  const { undoStack, redoStack, activeDraft } = state._commander;
+
+  // Redo is disabled while a draft is active
+  if (activeDraft) {
+    return false;
+  }
 
   // Pop the last entry from redo stack
   const entry = redoStack[redoStack.length - 1];
@@ -260,6 +343,7 @@ export function performRedo<TStore extends CommanderSlice>(
     getState: () => storeApi.getState(),
     setState: (partial) => storeApi.setState(partial as any),
     dispatch: createDispatchForUndo(storeApi),
+    transaction: buildTransaction(storeApi),
   };
 
   // Re-execute the command
@@ -277,6 +361,7 @@ export function performRedo<TStore extends CommanderSlice>(
   storeApi.setState((state: TStore) => ({
     ...state,
     _commander: {
+      ...state._commander,
       undoStack: [...undoStack, newEntry],
       redoStack: newRedoStack,
     },
@@ -298,6 +383,7 @@ function createDispatchForUndo<TStore>(
         getState: () => storeApi.getState(),
         setState: (partial) => storeApi.setState(partial as any),
         dispatch: createDispatchForUndo(storeApi),
+        transaction: buildTransaction(storeApi),
       };
 
       // Execute without adding to undo stack
@@ -315,9 +401,9 @@ export function clearUndoHistory<TStore extends CommanderSlice>(
   storeApi.setState((state: TStore) => ({
     ...state,
     _commander: {
+      ...state._commander,
       undoStack: [],
       redoStack: [],
     },
   }));
 }
-

package/src/zustand-commander/hooks.ts

@@ -8,7 +8,8 @@
 
 import { useCallback, useEffect, useMemo } from "react";
 import { useStore, type StoreApi, type UseBoundStore } from "zustand";
-import { performRedo, performUndo, clearUndoHistory } from "./commander";
+import type { Primitive } from "@voidhash/mimic";
+import { performRedo, performUndo, clearUndoHistory, setActiveDraft, clearActiveDraft } from "./commander";
 import {
   isUndoableCommand,
   type Command,
@@ -26,26 +27,50 @@ import {
  * Creates a dispatch function for commands.
  * This is for use outside of React components (e.g., in command handlers).
  */
-function createDispatchFromApi<TStore extends CommanderSlice>(
+function buildTransactionFromApi<TStore extends CommanderSlice, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive>(
+  storeApi: StoreApi<TStore>
+): (fn: (root: Primitive.InferProxy<TSchema>) => void) => void {
+  return (fn) => {
+    const state = storeApi.getState();
+    const draft = state._commander.activeDraft;
+    if (draft) {
+      draft.update(fn);
+    } else {
+      const mimic = (state as any).mimic;
+      if (!mimic?.document) {
+        throw new Error(
+          "Commander: No active draft and no mimic document found on the store."
+        );
+      }
+      mimic.document.transaction(fn);
+    }
+  };
+}
+
+function createDispatchFromApi<TStore extends CommanderSlice, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive>(
   storeApi: StoreApi<TStore>,
   maxUndoStackSize = 100
-): CommandDispatch<TStore> {
-  const dispatch: CommandDispatch<TStore> = <TParams, TReturn>(
-    command: Command<TStore, TParams, TReturn>
+): CommandDispatch<TStore, TSchema> {
+  const dispatch: CommandDispatch<TStore, TSchema> = <TParams, TReturn>(
+    command: Command<TStore, TParams, TReturn, TSchema>
   ) => {
     return (params: TParams): TReturn => {
       // Create context for the command
-      const ctx: CommandContext<TStore> = {
+      const ctx: CommandContext<TStore, TSchema> = {
         getState: () => storeApi.getState(),
         setState: (partial) => storeApi.setState(partial as Partial<TStore>),
         dispatch,
+        transaction: buildTransactionFromApi<TStore, TSchema>(storeApi),
       };
 
       // Execute the command
       const result = command.fn(ctx, params);
 
-      // If it's an undoable command, add to undo stack
-      if (isUndoableCommand(command)) {
+      // Skip undo stack when a draft is active
+      const hasDraft = storeApi.getState()._commander.activeDraft !== null;
+
+      // If it's an undoable command and no draft is active, add to undo stack
+      if (isUndoableCommand(command) && !hasDraft) {
         storeApi.setState((state: TStore) => {
           const { undoStack } = state._commander;
 
@@ -64,6 +89,7 @@ function createDispatchFromApi<TStore extends CommanderSlice>(
           return {
             ...state,
             _commander: {
+              ...state._commander,
               undoStack: newUndoStack,
               redoStack: [],
             },
@@ -91,9 +117,9 @@ function createDispatchFromApi<TStore extends CommanderSlice>(
  * };
  * ```
  */
-export function useCommander<TStore extends CommanderSlice>(
+export function useCommander<TStore extends CommanderSlice, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive>(
   store: UseBoundStore<StoreApi<TStore>>
-): CommandDispatch<TStore> {
+): CommandDispatch<TStore, TSchema> {
   // Get the store API
   const storeApi = useMemo(() => {
     // UseBoundStore has the StoreApi attached
@@ -102,11 +128,11 @@ export function useCommander<TStore extends CommanderSlice>(
 
   // Create a stable dispatch function
   const dispatch = useMemo(
-    () => createDispatchFromApi<TStore>(storeApi),
+    () => createDispatchFromApi<TStore, TSchema>(storeApi),
     [storeApi]
   );
 
-  return dispatch as CommandDispatch<TStore>;
+  return dispatch as CommandDispatch<TStore, TSchema>;
 }
 
 // =============================================================================

package/src/zustand-commander/index.ts

@@ -80,6 +80,8 @@ export {
   performUndo,
   performRedo,
   clearUndoHistory,
+  setActiveDraft,
+  clearActiveDraft,
 } from "./commander";
 
 // =============================================================================

package/src/zustand-commander/types.ts

@@ -7,6 +7,8 @@
  */
 
 import type { StoreApi, UseBoundStore } from "zustand";
+import type { Primitive } from "@voidhash/mimic";
+import type { ClientDocument } from "@voidhash/mimic/client";
 
 // =============================================================================
 // Command Symbol & Type Guard
@@ -32,7 +34,7 @@ export const UNDOABLE_COMMAND_SYMBOL = Symbol.for(
  * Context provided to command functions.
  * Gives access to store state and dispatch capabilities.
  */
-export interface CommandContext<TStore> {
+export interface CommandContext<TStore, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> {
   /**
    * Get the current store state.
    */
@@ -50,7 +52,13 @@ export interface CommandContext<TStore> {
    * @example
    * dispatch(otherCommand)({ param: "value" });
    */
-  readonly dispatch: CommandDispatch<TStore>;
+  readonly dispatch: CommandDispatch<TStore, TSchema>;
+
+  /**
+   * Run a transaction on the document.
+   * Routes to the active draft if one is linked, otherwise to the document directly.
+   */
+  readonly transaction: (fn: (root: Primitive.InferProxy<TSchema>) => void) => void;
 }
 
 // =============================================================================
@@ -60,8 +68,8 @@ export interface CommandContext<TStore> {
 /**
  * The function signature for a command handler.
  */
-export type CommandFn<TStore, TParams, TReturn> = (
-  ctx: CommandContext<TStore>,
+export type CommandFn<TStore, TParams, TReturn, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> = (
+  ctx: CommandContext<TStore, TSchema>,
   params: TParams
 ) => TReturn;
 
@@ -69,8 +77,8 @@ export type CommandFn<TStore, TParams, TReturn> = (
  * The function signature for an undoable command's revert handler.
  * Receives the original params and the result from the forward execution.
  */
-export type RevertFn<TStore, TParams, TReturn> = (
-  ctx: CommandContext<TStore>,
+export type RevertFn<TStore, TParams, TReturn, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> = (
+  ctx: CommandContext<TStore, TSchema>,
   params: TParams,
   result: TReturn
 ) => void;
@@ -83,19 +91,19 @@ export type RevertFn<TStore, TParams, TReturn> = (
  * A command that can be dispatched to modify store state.
  * Regular commands do not support undo/redo.
  */
-export interface Command<TStore, TParams, TReturn> {
+export interface Command<TStore, TParams, TReturn, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> {
   readonly [COMMAND_SYMBOL]: true;
-  readonly fn: CommandFn<TStore, TParams, TReturn>;
+  readonly fn: CommandFn<TStore, TParams, TReturn, TSchema>;
 }
 
 /**
  * An undoable command that supports undo/redo.
  * Must provide a revert function that knows how to undo the change.
  */
-export interface UndoableCommand<TStore, TParams, TReturn>
-  extends Command<TStore, TParams, TReturn> {
+export interface UndoableCommand<TStore, TParams, TReturn, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive>
+  extends Command<TStore, TParams, TReturn, TSchema> {
   readonly [UNDOABLE_COMMAND_SYMBOL]: true;
-  readonly revert: RevertFn<TStore, TParams, TReturn>;
+  readonly revert: RevertFn<TStore, TParams, TReturn, TSchema>;
 }
 
 /**
@@ -119,8 +127,8 @@ export type AnyUndoableCommand = UndoableCommand<any, any, any>;
  * @example
  * const result = dispatch(myCommand)({ param: "value" });
  */
-export type CommandDispatch<TStore> = <TParams, TReturn>(
-  command: Command<TStore, TParams, TReturn>
+export type CommandDispatch<TStore, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> = <TParams, TReturn>(
+  command: Command<TStore, TParams, TReturn, TSchema>
 ) => (params: TParams) => TReturn;
 
 // =============================================================================
@@ -151,6 +159,8 @@ export interface CommanderSlice {
     readonly undoStack: ReadonlyArray<UndoEntry>;
     /** Stack of commands that can be redone */
     readonly redoStack: ReadonlyArray<UndoEntry>;
+    /** Active draft handle, if any. When set, transactions route through the draft and undo is disabled. */
+    readonly activeDraft: ClientDocument.DraftHandle<any> | null;
   };
 }
 
@@ -173,7 +183,7 @@ export interface CommanderOptions {
  * A commander instance bound to a specific store type.
  * Used to create commands and the middleware.
  */
-export interface Commander<TStore> {
+export interface Commander<TStore, TSchema extends Primitive.AnyPrimitive = Primitive.AnyPrimitive> {
   /**
    * Create a regular command (no undo support).
    *
@@ -193,13 +203,13 @@ export interface Commander<TStore> {
   readonly action: {
     // With params (explicit type parameter)
     <TParams, TReturn = void>(
-      fn: CommandFn<TStore, TParams, TReturn>
-    ): Command<TStore, TParams, TReturn>;
+      fn: CommandFn<TStore, TParams, TReturn, TSchema>
+    ): Command<TStore, TParams, TReturn, TSchema>;
 
     // Without params (void) - inferred when no type param provided
     <TReturn = void>(
-      fn: CommandFn<TStore, void, TReturn>
-    ): Command<TStore, void, TReturn>;
+      fn: CommandFn<TStore, void, TReturn, TSchema>
+    ): Command<TStore, void, TReturn, TSchema>;
   };
 
   /**
@@ -222,15 +232,15 @@ export interface Commander<TStore> {
   readonly undoableAction: {
     // With params (explicit type parameter)
     <TParams, TReturn>(
-      fn: CommandFn<TStore, TParams, TReturn>,
-      revert: RevertFn<TStore, TParams, TReturn>
-    ): UndoableCommand<TStore, TParams, TReturn>;
+      fn: CommandFn<TStore, TParams, TReturn, TSchema>,
+      revert: RevertFn<TStore, TParams, TReturn, TSchema>
+    ): UndoableCommand<TStore, TParams, TReturn, TSchema>;
 
     // Without params (void)
     <TReturn>(
-      fn: CommandFn<TStore, void, TReturn>,
-      revert: RevertFn<TStore, void, TReturn>
-    ): UndoableCommand<TStore, void, TReturn>;
+      fn: CommandFn<TStore, void, TReturn, TSchema>,
+      revert: RevertFn<TStore, void, TReturn, TSchema>
+    ): UndoableCommand<TStore, void, TReturn, TSchema>;
   };
 
   /**