@craftile/core 1.0.8 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftile/core",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Framework-agnostic block editor engine for Craftile",
   "keywords": [
     "craftile",
@@ -26,8 +26,8 @@
     "src"
   ],
   "dependencies": {
-    "@craftile/event-bus": "1.0.8",
-    "@craftile/types": "1.0.8"
+    "@craftile/event-bus": "1.1.0",
+    "@craftile/types": "1.1.0"
   },
   "devDependencies": {
     "vitest": "^3.2.4",

package/src/commands/batch.ts

@@ -0,0 +1,19 @@
+import type { Command } from '../types';
+
+export class BatchCommand implements Command {
+  private commands: Command[];
+
+  constructor(commands: Command[]) {
+    this.commands = commands;
+  }
+
+  apply(): void {
+    this.commands.forEach((command) => command.apply());
+  }
+
+  revert(): void {
+    for (let i = this.commands.length - 1; i >= 0; i--) {
+      this.commands[i].revert();
+    }
+  }
+}

package/src/commands/replace-page.ts

@@ -0,0 +1,34 @@
+import type { Page } from '@craftile/types';
+import type { Command, EngineEmitFn } from '../types';
+
+export class ReplacePageCommand implements Command {
+  private previousPage: Page;
+  private newPage: Page;
+  private setPageState: (page: Page) => void;
+  private emit: EngineEmitFn;
+
+  constructor(previousPage: Page, newPage: Page, setPageState: (page: Page) => void, emit: EngineEmitFn) {
+    this.previousPage = previousPage;
+    this.newPage = newPage;
+    this.setPageState = setPageState;
+    this.emit = emit;
+  }
+
+  apply(): void {
+    this.setPageState(this.newPage);
+
+    this.emit('page:replace', {
+      previousPage: structuredClone(this.previousPage),
+      newPage: structuredClone(this.newPage),
+    });
+  }
+
+  revert(): void {
+    this.setPageState(this.previousPage);
+
+    this.emit('page:replace', {
+      previousPage: structuredClone(this.newPage),
+      newPage: structuredClone(this.previousPage),
+    });
+  }
+}

package/src/commands/replace-region.ts

@@ -0,0 +1,145 @@
+import type { Block, BlockSchema, BlockStructure, Page } from '@craftile/types';
+import type { BlocksManager } from '../blocks-manager';
+import type { Command, EngineEmitFn } from '../types';
+import { generateId, getRegionId } from '../utils';
+
+export interface ReplaceRegionOptions {
+  regionId: string;
+  structures: BlockStructure[];
+  blocksManager: BlocksManager;
+  emit: EngineEmitFn;
+}
+
+export class ReplaceRegionCommand implements Command {
+  private page: Page;
+  private regionId: string;
+  private regionIndex: number;
+  private previousRegion: Page['regions'][number];
+  private newRegion: Page['regions'][number];
+  private removedBlocks: Record<string, Block>;
+  private newBlocks: Record<string, Block>;
+  private emit: EngineEmitFn;
+  private blocksManager: BlocksManager;
+
+  constructor(page: Page, options: ReplaceRegionOptions) {
+    this.page = page;
+    this.regionId = options.regionId;
+    this.blocksManager = options.blocksManager;
+    this.emit = options.emit;
+
+    this.regionIndex = this.page.regions.findIndex((region) => getRegionId(region) === this.regionId);
+    if (this.regionIndex === -1) {
+      throw new Error(`Region not found: ${this.regionId}`);
+    }
+
+    this.previousRegion = structuredClone(this.page.regions[this.regionIndex]);
+    this.removedBlocks = this.collectBlocksForRoots(this.previousRegion.blocks);
+
+    this.newBlocks = {};
+    const newRootIds = options.structures.map((structure) =>
+      this.createBlockFromStructure(structure, undefined, this.newBlocks)
+    );
+    this.newRegion = {
+      ...this.previousRegion,
+      blocks: newRootIds,
+    };
+  }
+
+  apply(): void {
+    this.replaceRegion(this.previousRegion, this.newRegion, this.removedBlocks, this.newBlocks);
+  }
+
+  revert(): void {
+    this.replaceRegion(this.newRegion, this.previousRegion, this.newBlocks, this.removedBlocks);
+  }
+
+  private createBlockFromStructure(
+    structure: BlockStructure,
+    parentId: string | undefined,
+    target: Record<string, Block>
+  ): string {
+    const blockSchema = this.blocksManager.get(structure.type);
+    if (!blockSchema) {
+      throw new Error(`Block type '${structure.type}' is not registered`);
+    }
+
+    const blockId = generateId();
+    const block: Block = {
+      type: structure.type,
+      id: blockId,
+      name: structure.name || blockSchema.meta?.name || structure.type,
+      semanticId: structure.semanticId || structure.id,
+      properties: this.buildProperties(blockSchema, structure.properties),
+      children: [],
+      parentId,
+      static: structure.static,
+      disabled: structure.disabled,
+      repeated: structure.repeated,
+      ghost: structure.ghost,
+    };
+
+    target[blockId] = block;
+    block.children = (structure.children ?? []).map((child) => this.createBlockFromStructure(child, blockId, target));
+
+    return blockId;
+  }
+
+  private buildProperties(blockSchema: BlockSchema, properties?: Record<string, any>): Record<string, any> {
+    const builtProperties: Record<string, any> = {};
+
+    for (const field of blockSchema.properties ?? []) {
+      if (field.default !== undefined) {
+        builtProperties[field.id] = field.default;
+      }
+    }
+
+    if (properties) {
+      Object.assign(builtProperties, properties);
+    }
+
+    return builtProperties;
+  }
+
+  private collectBlocksForRoots(rootBlockIds: string[]): Record<string, Block> {
+    const blocks: Record<string, Block> = {};
+
+    const collectBlock = (blockId: string) => {
+      const block = this.page.blocks[blockId];
+      if (!block || blocks[blockId]) {
+        return;
+      }
+
+      blocks[blockId] = block;
+      block.children.forEach(collectBlock);
+    };
+
+    rootBlockIds.forEach(collectBlock);
+
+    return blocks;
+  }
+
+  private replaceRegion(
+    previousRegion: Page['regions'][number],
+    newRegion: Page['regions'][number],
+    removedBlocks: Record<string, Block>,
+    newBlocks: Record<string, Block>
+  ): void {
+    Object.keys(removedBlocks).forEach((blockId) => {
+      delete this.page.blocks[blockId];
+    });
+
+    Object.entries(newBlocks).forEach(([blockId, block]) => {
+      this.page.blocks[blockId] = block;
+    });
+
+    this.page.regions[this.regionIndex] = newRegion;
+
+    this.emit('region:replace', {
+      regionId: this.regionId,
+      previousRegion: structuredClone(previousRegion),
+      newRegion: structuredClone(newRegion),
+      removedBlocks: structuredClone(removedBlocks),
+      newBlocks: structuredClone(newBlocks),
+    });
+  }
+}

package/src/engine.ts

@@ -1,8 +1,9 @@
 import { EventBus } from '@craftile/event-bus';
-import type { EngineConfig, EngineEvents } from './types';
+import type { Command, EngineConfig, EngineEvents } from './types';
 import type { Block, BlockSchema, BlockStructure, Page } from '@craftile/types';
 import { BlocksManager } from './blocks-manager';
 import { HistoryManager } from './history-manager';
+import { BatchCommand } from './commands/batch';
 import { InsertBlockCommand } from './commands/insert-block';
 import { InsertBlockFromPresetCommand } from './commands/insert-block-from-preset';
 import { RemoveBlockCommand } from './commands/remove-block';
@@ -11,11 +12,14 @@ import { ToggleBlockCommand } from './commands/toggle-block';
 import { SetBlockPropertyCommand } from './commands/set-block-property';
 import { DuplicateBlockCommand } from './commands/duplicate-block';
 import { SetBlockNameCommand } from './commands/set-block-name';
+import { ReplacePageCommand } from './commands/replace-page';
+import { ReplaceRegionCommand } from './commands/replace-region';
 
 export class Engine extends EventBus<EngineEvents> {
   protected page!: Page;
   protected blocksManager: BlocksManager;
   protected historyManager: HistoryManager;
+  private activeBatch: Command[] | null = null;
 
   constructor(config: EngineConfig = {}) {
     super();
@@ -76,8 +80,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
 
     return command.getBlockId();
   }
@@ -134,8 +137,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
 
     return command.getBlockId();
   }
@@ -153,8 +155,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
   }
 
   /**
@@ -195,8 +196,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
   }
 
   /**
@@ -209,8 +209,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
   }
 
   /**
@@ -230,8 +229,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
   }
 
   /**
@@ -249,8 +247,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
   }
 
   /**
@@ -262,8 +259,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
 
     return command.getDuplicatedBlockId();
   }
@@ -347,8 +343,7 @@ export class Engine extends EventBus<EngineEvents> {
       emit: this.emit.bind(this),
     });
 
-    command.apply();
-    this.historyManager.addCommand(command);
+    this.applyCommand(command);
 
     return command.getBlockId();
   }
@@ -370,26 +365,7 @@ export class Engine extends EventBus<EngineEvents> {
   setPage(newPage: Page): void {
     const beforePage = structuredClone(this.page);
 
-    this.page = structuredClone(newPage);
-
-    if (this.page.regions.length === 0) {
-      this.page.regions = [{ id: 'main', name: 'main', blocks: Object.keys(this.page.blocks) }];
-    }
-
-    // Initialize regions if not present
-    if (this.page.regions.length === 0) {
-      this.page.regions = [
-        {
-          id: 'main',
-          name: 'main',
-          blocks: Object.values(this.page.blocks)
-            .filter((block) => !block.parentId)
-            .map((block) => block.id),
-        },
-      ];
-    }
-
-    this.initializeParentChildRelationships();
+    this.page = this.normalizePage(newPage);
 
     // Clear history since we're switching to a completely new page
     // maybe we should keep a separate history per page
@@ -401,6 +377,42 @@ export class Engine extends EventBus<EngineEvents> {
     });
   }
 
+  /**
+   * Replace the current page as a single undoable operation.
+   */
+  replacePage(newPage: Page): void {
+    if (this.activeBatch) {
+      throw new Error('replacePage cannot be called inside batch');
+    }
+
+    const command = new ReplacePageCommand(
+      this.page,
+      this.normalizePage(newPage),
+      this.replacePageState.bind(this),
+      this.emit.bind(this)
+    );
+
+    this.applyCommand(command);
+  }
+
+  /**
+   * Replace an existing region's root blocks as a single undoable operation.
+   */
+  replaceRegion(regionId: string, structures: BlockStructure[]): void {
+    if (this.activeBatch) {
+      throw new Error('replaceRegion cannot be called inside batch');
+    }
+
+    const command = new ReplaceRegionCommand(this.page, {
+      regionId,
+      structures,
+      blocksManager: this.blocksManager,
+      emit: this.emit.bind(this),
+    });
+
+    this.applyCommand(command);
+  }
+
   /**
    * Get the blocks manager for this engine instance
    */
@@ -466,14 +478,54 @@ export class Engine extends EventBus<EngineEvents> {
   }
 
   /**
-   * Initialize parent-child relationships for blocks that have children but missing parentId
-   * Handles deep nesting recursively
+   * Group multiple operations into a single undo/redo history entry.
    */
-  private initializeParentChildRelationships(): void {
+  batch<T>(callback: () => T): T {
+    const isOuterBatch = this.activeBatch === null;
+
+    if (isOuterBatch) {
+      this.activeBatch = [];
+    }
+
+    const batch = this.activeBatch!;
+    const startIndex = batch.length;
+
+    try {
+      const result = callback();
+
+      if (isOuterBatch && batch.length > 0) {
+        this.historyManager.addCommand(new BatchCommand(batch.slice()));
+      }
+
+      return result;
+    } catch (error) {
+      this.rollbackCommands(batch.slice(startIndex));
+      batch.splice(startIndex);
+      throw error;
+    } finally {
+      if (isOuterBatch) {
+        this.activeBatch = null;
+      }
+    }
+  }
+
+  private normalizePage(page: Page): Page {
+    const normalizedPage = structuredClone(page);
+
+    if (normalizedPage.regions.length === 0) {
+      normalizedPage.regions = [{ id: 'main', name: 'main', blocks: Object.keys(normalizedPage.blocks) }];
+    }
+
+    this.initializeParentChildRelationshipsForPage(normalizedPage);
+
+    return normalizedPage;
+  }
+
+  private initializeParentChildRelationshipsForPage(page: Page): void {
     const processBlock = (block: Block): void => {
       if (block.children && block.children.length > 0) {
         block.children.forEach((childId: string) => {
-          const childBlock = this.page.blocks[childId];
+          const childBlock = page.blocks[childId];
           if (childBlock) {
             if (!childBlock.parentId) {
               childBlock.parentId = block.id;
@@ -485,6 +537,30 @@ export class Engine extends EventBus<EngineEvents> {
       }
     };
 
-    Object.values(this.page.blocks).forEach(processBlock);
+    Object.values(page.blocks).forEach(processBlock);
+  }
+
+  private replacePageState(page: Page): void {
+    this.page = page;
+  }
+
+  private applyCommand(command: Command): void {
+    command.apply();
+    this.recordCommand(command);
+  }
+
+  private recordCommand(command: Command): void {
+    if (this.activeBatch) {
+      this.activeBatch.push(command);
+      return;
+    }
+
+    this.historyManager.addCommand(command);
+  }
+
+  private rollbackCommands(commands: Command[]): void {
+    for (let i = commands.length - 1; i >= 0; i--) {
+      commands[i].revert();
+    }
   }
 }

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { Block, BlockSchema, Page } from '@craftile/types';
+import type { Block, BlockSchema, Page, Region } from '@craftile/types';
 import type { BlocksManager } from './blocks-manager';
 
 export interface EngineConfig {
@@ -15,6 +15,14 @@ export interface Command {
 // Event system types
 export interface EngineEvents {
   'page:set': { previousPage?: Page; newPage: Page };
+  'page:replace': { previousPage: Page; newPage: Page };
+  'region:replace': {
+    regionId: string;
+    previousRegion: Region;
+    newRegion: Region;
+    removedBlocks: Record<string, Block>;
+    newBlocks: Record<string, Block>;
+  };
   'block:insert': { blockId: string; block: Block; parentId?: string; index?: number; regionId?: string };
   'block:remove': { blockId: string; block: Block; parentId?: string; regionId?: string };
   'block:toggle': { blockId: string; disabled: boolean; oldValue?: boolean };

package/src/vue/useBlocksEngine.ts

@@ -1,4 +1,4 @@
-import { ref, onUnmounted, computed, toRaw, nextTick, type Ref } from 'vue';
+import { ref, onUnmounted, computed, toRaw, nextTick, getCurrentInstance, type Ref } from 'vue';
 import type { Block, BlockStructure, Page, Region } from '@craftile/types';
 import type { EngineConfig } from '../types';
 import { Engine } from '../engine';
@@ -62,9 +62,12 @@ export interface UseBlocksEngineReturn {
       index?: number;
     }
   ) => string;
+  replacePage: (newPage: Page) => void;
+  replaceRegion: (regionId: string, structures: BlockStructure[]) => void;
 
   undo: () => boolean;
   redo: () => boolean;
+  batch: <T>(callback: () => T) => T;
   canUndo: Ref<boolean>;
   canRedo: Ref<boolean>;
 
@@ -171,6 +174,8 @@ export function useBlocksEngine(
   if (autoSync) {
     const eventTypes = [
       'page:set',
+      'page:replace',
+      'region:replace',
       'block:insert',
       'block:remove',
       'block:move',
@@ -300,6 +305,22 @@ export function useBlocksEngine(
     return blockId;
   };
 
+  const replacePage = (newPage: Page): void => {
+    engine.replacePage(newPage);
+
+    if (!autoSync) {
+      syncStateFromEngine();
+    }
+  };
+
+  const replaceRegion = (regionId: string, structures: BlockStructure[]): void => {
+    engine.replaceRegion(regionId, structures);
+
+    if (!autoSync) {
+      syncStateFromEngine();
+    }
+  };
+
   const undo = (): boolean => {
     const result = engine.undo();
 
@@ -320,6 +341,16 @@ export function useBlocksEngine(
     return result;
   };
 
+  const batch = <T>(callback: () => T): T => {
+    const result = engine.batch(callback);
+
+    if (!autoSync) {
+      syncStateFromEngine();
+    }
+
+    return result;
+  };
+
   const refresh = () => {
     syncStateFromEngine();
   };
@@ -329,9 +360,11 @@ export function useBlocksEngine(
     eventCleanups.length = 0;
   };
 
-  onUnmounted(() => {
-    destroy();
-  });
+  if (getCurrentInstance()) {
+    onUnmounted(() => {
+      destroy();
+    });
+  }
 
   return {
     // Reactive state
@@ -358,10 +391,13 @@ export function useBlocksEngine(
     toggleBlock,
     duplicateBlock,
     pasteBlock,
+    replacePage,
+    replaceRegion,
 
     // History methods
     undo,
     redo,
+    batch,
     canUndo,
     canRedo,