@craftile/core 0.10.0 → 1.0.0

package/package.json

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

package/src/commands/duplicate-block.ts

@@ -1,4 +1,5 @@
 import type { Command, EngineEmitFn } from '../types';
+import { getRegionId } from '../utils';
 import type { Block, Page } from '@craftile/types';
 import { generateId } from '../utils';
 
@@ -16,7 +17,7 @@ export class DuplicateBlockCommand implements Command {
   private duplicatedBlock?: Block;
   private parentId?: string | null;
   private insertIndex!: number;
-  private regionName?: string | null;
+  private regionId?: string | null;
   private emit: EngineEmitFn;
 
   constructor(page: Page, options: DuplicateBlockOptions) {
@@ -45,7 +46,7 @@ export class DuplicateBlockCommand implements Command {
       newBlock: this.duplicatedBlock,
       parentId: this.parentId || undefined,
       index: this.insertIndex,
-      regionName: this.regionName || undefined,
+      regionId: this.regionId || undefined,
     });
   }
 
@@ -77,8 +78,8 @@ export class DuplicateBlockCommand implements Command {
     return this.insertIndex;
   }
 
-  getRegionName(): string | null | undefined {
-    return this.regionName;
+  getRegionId(): string | null | undefined {
+    return this.regionId;
   }
 
   private cloneBlockWithNewIds(block: Block, newId: string, newParentId?: string): Block {
@@ -125,10 +126,10 @@ export class DuplicateBlockCommand implements Command {
       const region = this.page.regions.find((r) => r.blocks.includes(this.blockId));
       if (region) {
         const index = region.blocks.indexOf(this.blockId);
-        this.regionName = region.name;
+        this.regionId = getRegionId(region);
         this.insertIndex = index + 1;
       } else {
-        this.regionName = this.page.regions[0].name || 'main';
+        this.regionId = getRegionId(this.page.regions[0]) || 'main';
         this.insertIndex = this.page.regions[0].blocks.length || 0;
       }
     }
@@ -147,10 +148,10 @@ export class DuplicateBlockCommand implements Command {
 
       targetParent.children.splice(this.insertIndex, 0, this.duplicatedBlockId);
     } else {
-      let targetRegion = this.page.regions.find((r) => r.name === this.regionName);
+      let targetRegion = this.page.regions.find((r) => r.name === this.regionId);
 
       if (!targetRegion) {
-        targetRegion = { name: this.regionName || 'main', blocks: [] };
+        targetRegion = { name: this.regionId || 'main', blocks: [] };
         this.page.regions.push(targetRegion);
       }
 
@@ -177,7 +178,7 @@ export class DuplicateBlockCommand implements Command {
     } else {
       // Remove from region
       if (this.page.regions) {
-        const targetRegion = this.page.regions.find((r) => r.name === this.regionName);
+        const targetRegion = this.page.regions.find((r) => r.name === this.regionId);
         if (targetRegion) {
           const index = targetRegion.blocks.indexOf(this.duplicatedBlockId);
           if (index !== -1) {

package/src/commands/insert-block-from-preset.ts

@@ -1,4 +1,5 @@
 import type { Block, BlockProperties, BlockSchema, BlockStructure, Page } from '@craftile/types';
+import { getRegionId } from '../utils';
 import type { Command, EngineEmitFn } from '../types';
 import { generateId } from '../utils';
 import type { BlocksManager } from '../blocks-manager';
@@ -8,7 +9,7 @@ export interface InsertBlockFromPresetOptions {
   presetIndex?: number;
   presetData?: BlockStructure;
   parentId?: string;
-  regionName?: string;
+  regionId?: string;
   index?: number;
   blocksManager: BlocksManager;
   emit: EngineEmitFn;
@@ -20,7 +21,7 @@ export class InsertBlockFromPresetCommand implements Command {
   private presetIndex?: number;
   private presetData?: BlockStructure;
   private parentId?: string;
-  private regionName?: string;
+  private regionId?: string;
   private index?: number;
   private blockId: string;
   private properties: Record<string, any>;
@@ -36,7 +37,7 @@ export class InsertBlockFromPresetCommand implements Command {
     this.presetIndex = options.presetIndex;
     this.presetData = options.presetData;
     this.parentId = options.parentId;
-    this.regionName = options.regionName;
+    this.regionId = options.regionId;
     this.index = options.index;
     this.blockId = generateId();
     this.blocksManager = options.blocksManager;
@@ -139,11 +140,11 @@ export class InsertBlockFromPresetCommand implements Command {
       }
     } else {
       // Insert as top-level block
-      const targetRegionName = this.regionName || this.page.regions[0].name;
-      let targetRegion = this.page.regions.find((r) => r.name === targetRegionName);
+      const targetRegionId = this.regionId || getRegionId(this.page.regions[0]);
+      let targetRegion = this.page.regions.find((r) => getRegionId(r) === targetRegionId);
 
       if (!targetRegion) {
-        targetRegion = { name: targetRegionName, blocks: [] };
+        targetRegion = { id: targetRegionId, name: targetRegionId, blocks: [] };
         this.page.regions.push(targetRegion);
       }
 
@@ -161,7 +162,7 @@ export class InsertBlockFromPresetCommand implements Command {
       block: this.insertedBlock,
       parentId: this.parentId,
       index: this.actualIndex,
-      regionName: this.regionName || this.page.regions[0].name,
+      regionId: this.regionId || getRegionId(this.page.regions[0]),
     });
   }
 
@@ -181,8 +182,8 @@ export class InsertBlockFromPresetCommand implements Command {
         parent.children.splice(this.actualIndex, 1);
       }
     } else {
-      const targetRegionName = this.regionName || this.page.regions[0].name;
-      const targetRegion = this.page.regions.find((r) => r.name === targetRegionName);
+      const targetRegionId = this.regionId || getRegionId(this.page.regions[0]);
+      const targetRegion = this.page.regions.find((r) => getRegionId(r) === targetRegionId);
 
       if (targetRegion && this.actualIndex !== undefined) {
         targetRegion.blocks.splice(this.actualIndex, 1);

package/src/commands/insert-block.ts

@@ -1,11 +1,12 @@
 import type { Block, BlockSchema, Page } from '@craftile/types';
+import { getRegionId } from '../utils';
 import type { Command, EngineEmitFn } from '../types';
 import { generateId } from '../utils';
 
 export interface InsertBlockOptions {
   blockType: string;
   parentId?: string;
-  regionName?: string;
+  regionId?: string;
   index?: number;
   properties?: Record<string, any>;
   blockSchema?: BlockSchema;
@@ -16,7 +17,7 @@ export class InsertBlockCommand implements Command {
   private page: Page;
   private blockType: string;
   private parentId?: string;
-  private regionName?: string;
+  private regionId?: string;
   private index?: number;
   private blockId: string;
   private properties: Record<string, any>;
@@ -29,7 +30,7 @@ export class InsertBlockCommand implements Command {
     this.page = page;
     this.blockType = options.blockType;
     this.parentId = options.parentId;
-    this.regionName = options.regionName;
+    this.regionId = options.regionId;
     this.index = options.index;
     this.blockId = generateId();
     this.emit = options.emit;
@@ -70,11 +71,11 @@ export class InsertBlockCommand implements Command {
       }
     } else {
       // Insert as top-level block (to the specified region)
-      const targetRegionName = this.regionName || this.page.regions[0].name;
-      let targetRegion = this.page.regions.find((r) => r.name === targetRegionName);
+      const targetRegionId = this.regionId || getRegionId(this.page.regions[0]);
+      let targetRegion = this.page.regions.find((r) => getRegionId(r) === targetRegionId);
 
       if (!targetRegion) {
-        targetRegion = { name: targetRegionName, blocks: [] };
+        targetRegion = { id: targetRegionId, name: targetRegionId, blocks: [] };
         this.page.regions.push(targetRegion);
       }
 
@@ -92,7 +93,7 @@ export class InsertBlockCommand implements Command {
       block: this.insertedBlock,
       parentId: this.parentId,
       index: this.actualIndex,
-      regionName: this.regionName || this.page.regions[0].name,
+      regionId: this.regionId || getRegionId(this.page.regions[0]),
     });
   }
 
@@ -109,8 +110,8 @@ export class InsertBlockCommand implements Command {
         parent.children.splice(this.actualIndex, 1);
       }
     } else {
-      const targetRegionName = this.regionName || this.page.regions[0].name;
-      const targetRegion = this.page.regions.find((r) => r.name === targetRegionName);
+      const targetRegionId = this.regionId || getRegionId(this.page.regions[0]);
+      const targetRegion = this.page.regions.find((r) => getRegionId(r) === targetRegionId);
 
       if (targetRegion && this.actualIndex !== undefined) {
         targetRegion.blocks.splice(this.actualIndex, 1);

package/src/commands/move-block.ts

@@ -1,11 +1,12 @@
 import type { Block, Page } from '@craftile/types';
 import type { Command, EngineEmitFn } from '../types';
+import { getRegionId } from '../utils';
 
 export interface MoveBlockOptions {
   blockId: string;
   targetParentId?: string;
   targetIndex?: number;
-  targetRegionName?: string;
+  targetRegionId?: string;
   emit: EngineEmitFn;
 }
 
@@ -14,13 +15,13 @@ export class MoveBlockCommand implements Command {
   private blockId: string;
   private targetParentId?: string;
   private targetIndex?: number;
-  private targetRegionName?: string;
+  private targetRegionId?: string;
 
   // State for reverting
   private blockToMove?: Block;
   private originalParentId?: string;
   private originalIndex!: number;
-  private originalRegionName?: string;
+  private originalRegionId?: string;
 
   private emit: EngineEmitFn;
 
@@ -29,7 +30,7 @@ export class MoveBlockCommand implements Command {
     this.blockId = options.blockId;
     this.targetParentId = options.targetParentId;
     this.targetIndex = options.targetIndex;
-    this.targetRegionName = options.targetRegionName;
+    this.targetRegionId = options.targetRegionId;
     this.emit = options.emit;
   }
 
@@ -60,7 +61,7 @@ export class MoveBlockCommand implements Command {
       const region = this.page.regions.find((r) => r.blocks.includes(this.blockId));
       if (region) {
         this.originalIndex = region.blocks.indexOf(this.blockId);
-        this.originalRegionName = region.name;
+        this.originalRegionId = getRegionId(region);
         region.blocks.splice(this.originalIndex, 1);
       }
     }
@@ -78,11 +79,11 @@ export class MoveBlockCommand implements Command {
     } else {
       this.blockToMove.parentId = undefined;
 
-      const regionName = this.targetRegionName || this.page.regions[0].name || 'main';
-      let targetRegion = this.page.regions.find((r) => r.name === regionName);
+      const regionId = this.targetRegionId || getRegionId(this.page.regions[0]) || 'main';
+      let targetRegion = this.page.regions.find((r) => getRegionId(r) === regionId);
 
       if (!targetRegion) {
-        targetRegion = { name: regionName, blocks: [] };
+        targetRegion = { id: regionId, name: regionId, blocks: [] };
         this.page.regions.push(targetRegion);
       }
 
@@ -97,9 +98,9 @@ export class MoveBlockCommand implements Command {
       blockId: this.blockId,
       targetParentId: this.targetParentId,
       targetIndex: this.targetIndex,
-      targetRegionName: this.targetRegionName,
+      targetRegionId: this.targetRegionId,
       sourceParentId: this.originalParentId || null,
-      sourceRegionName: this.originalRegionName || null,
+      sourceRegionId: this.originalRegionId || null,
       sourceIndex: this.originalIndex,
     });
   }
@@ -134,8 +135,8 @@ export class MoveBlockCommand implements Command {
       if (originalParent) {
         originalParent.children.splice(this.originalIndex, 0, this.blockId);
       }
-    } else if (this.originalRegionName) {
-      const region = this.page.regions.find((r) => r.name === this.originalRegionName);
+    } else if (this.originalRegionId) {
+      const region = this.page.regions.find((r) => getRegionId(r) === this.originalRegionId);
       if (region) {
         region.blocks.splice(this.originalIndex, 0, this.blockId);
       }
@@ -145,9 +146,9 @@ export class MoveBlockCommand implements Command {
       blockId: this.blockId,
       targetParentId: this.originalParentId,
       targetIndex: this.originalIndex,
-      targetRegionName: this.originalRegionName,
+      targetRegionId: this.originalRegionId,
       sourceParentId: this.targetParentId || null,
-      sourceRegionName: this.targetRegionName || null,
+      sourceRegionId: this.targetRegionId || null,
       sourceIndex: this.targetIndex || 0,
     });
   }
@@ -164,16 +165,16 @@ export class MoveBlockCommand implements Command {
     return this.targetIndex;
   }
 
-  getTargetRegionName(): string | undefined {
-    return this.targetRegionName;
+  getTargetRegionId(): string | undefined {
+    return this.targetRegionId;
   }
 
   getSourceParentId(): string | null {
     return this.originalParentId || null;
   }
 
-  getSourceRegionName(): string | null {
-    return this.originalRegionName || null;
+  getSourceRegionId(): string | null {
+    return this.originalRegionId || null;
   }
 
   getSourceIndex(): number {

package/src/commands/remove-block.ts

@@ -1,4 +1,5 @@
 import type { Block, Page } from '@craftile/types';
+import { getRegionId } from '../utils';
 import type { Command, EngineEmitFn } from '../types';
 
 export interface RemoveBlockOptions {
@@ -12,7 +13,7 @@ export class RemoveBlockCommand implements Command {
   private removedBlock?: Block;
   private originalIndex?: number;
   private originalParentId?: string;
-  private regionName?: string;
+  private regionId?: string;
   private emit: EngineEmitFn;
 
   constructor(page: Page, options: RemoveBlockOptions) {
@@ -42,7 +43,7 @@ export class RemoveBlockCommand implements Command {
       const region = this.page.regions.find((r) => r.blocks.includes(this.blockId));
       if (region) {
         this.originalIndex = region.blocks.indexOf(this.blockId);
-        this.regionName = region.name;
+        this.regionId = getRegionId(region);
         region.blocks.splice(this.originalIndex, 1);
       }
     }
@@ -68,8 +69,8 @@ export class RemoveBlockCommand implements Command {
       if (parent) {
         parent.children.splice(this.originalIndex, 0, this.blockId);
       }
-    } else if (this.regionName) {
-      const region = this.page.regions.find((r) => r.name === this.regionName);
+    } else if (this.regionId) {
+      const region = this.page.regions.find((r) => getRegionId(r) === this.regionId);
       if (region) {
         region.blocks.splice(this.originalIndex, 0, this.blockId);
       }
@@ -80,7 +81,7 @@ export class RemoveBlockCommand implements Command {
       block: this.removedBlock,
       parentId: this.originalParentId,
       index: this.originalIndex,
-      regionName: this.regionName,
+      regionId: this.regionId,
     });
   }
 

package/src/engine.ts

@@ -22,7 +22,7 @@ export class Engine extends EventBus<EngineEvents> {
 
     this.blocksManager = config.blocksManager || new BlocksManager();
     this.historyManager = new HistoryManager();
-    this.setPage(config.page ? config.page : { blocks: {}, regions: [{ name: 'main', blocks: [] }] });
+    this.setPage(config.page ? config.page : { blocks: {}, regions: [{ id: 'main', name: 'main', blocks: [] }] });
 
     if (config.blockSchemas && config.blockSchemas.length > 0) {
       config.blockSchemas.forEach((schema) => {
@@ -37,7 +37,7 @@ export class Engine extends EventBus<EngineEvents> {
    * @param blockType - The type of block to insert (must be registered)
    * @param options - Optional configuration for block insertion
    * @param options.parentId - ID of parent block (for nested blocks)
-   * @param options.regionName - Target region name (defaults to 'main')
+   * @param options.regionId - Target region id (defaults to 'main')
    * @param options.index - Position to insert at (defaults to end)
    * @returns The ID of the newly inserted block
    * @throws {Error} When block type is not registered or parent-child relationship is invalid
@@ -47,7 +47,7 @@ export class Engine extends EventBus<EngineEvents> {
     blockType: string,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ): string {
@@ -70,7 +70,7 @@ export class Engine extends EventBus<EngineEvents> {
     const command = new InsertBlockCommand(this.page, {
       blockType,
       parentId: options?.parentId,
-      regionName: options?.regionName,
+      regionId: options?.regionId,
       index: options?.index,
       blockSchema,
       emit: this.emit.bind(this),
@@ -89,7 +89,7 @@ export class Engine extends EventBus<EngineEvents> {
    * @param presetIndex - Index of the preset in the block schema's presets array
    * @param options - Optional configuration for block insertion
    * @param options.parentId - ID of parent block (for nested blocks)
-   * @param options.regionName - Target region name (defaults to 'main')
+   * @param options.regionId - Target region id (defaults to 'main')
    * @param options.index - Position to insert at (defaults to end)
    * @returns The ID of the newly inserted block
    * @throws {Error} When block type is not registered, preset not found, or parent-child relationship is invalid
@@ -100,7 +100,7 @@ export class Engine extends EventBus<EngineEvents> {
     presetIndex: number,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ): string {
@@ -128,7 +128,7 @@ export class Engine extends EventBus<EngineEvents> {
       blockType,
       presetIndex,
       parentId: options?.parentId,
-      regionName: options?.regionName,
+      regionId: options?.regionId,
       index: options?.index,
       blocksManager: this.blocksManager,
       emit: this.emit.bind(this),
@@ -164,14 +164,14 @@ export class Engine extends EventBus<EngineEvents> {
    * @param options - Optional configuration for block move operation
    * @param options.targetParentId - ID of target parent block
    * @param options.targetIndex - position in the target parent block children
-   * @param options.targetRegionName - target region name
+   * @param options.targetRegionId - target region id
    */
   moveBlock(
     blockId: string,
     options?: {
       targetParentId?: string;
       targetIndex?: number;
-      targetRegionName?: string;
+      targetRegionId?: string;
     }
   ): void {
     const block = this.page.blocks[blockId];
@@ -191,7 +191,7 @@ export class Engine extends EventBus<EngineEvents> {
       blockId,
       targetParentId: options?.targetParentId,
       targetIndex: options?.targetIndex,
-      targetRegionName: options?.targetRegionName,
+      targetRegionId: options?.targetRegionId,
       emit: this.emit.bind(this),
     });
 
@@ -307,7 +307,7 @@ export class Engine extends EventBus<EngineEvents> {
    * @param structure - The block structure to paste
    * @param options - Optional configuration for block insertion
    * @param options.parentId - ID of parent block (for nested blocks)
-   * @param options.regionName - Target region name (defaults to 'main')
+   * @param options.regionId - Target region id (defaults to 'main')
    * @param options.index - Position to insert at (defaults to end)
    * @returns The ID of the newly inserted block
    * @throws {Error} When block type is not registered or parent-child relationship is invalid
@@ -317,7 +317,7 @@ export class Engine extends EventBus<EngineEvents> {
     structure: BlockStructure,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ): string {
@@ -341,7 +341,7 @@ export class Engine extends EventBus<EngineEvents> {
       blockType: structure.type,
       presetData: structure,
       parentId: options?.parentId,
-      regionName: options?.regionName,
+      regionId: options?.regionId,
       index: options?.index,
       blocksManager: this.blocksManager,
       emit: this.emit.bind(this),
@@ -373,13 +373,14 @@ export class Engine extends EventBus<EngineEvents> {
     this.page = structuredClone(newPage);
 
     if (this.page.regions.length === 0) {
-      this.page.regions = [{ name: 'main', blocks: Object.keys(this.page.blocks) }];
+      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)

package/src/index.ts

@@ -1,3 +1,3 @@
 export * from './types';
+export * from './utils';
 export { Engine } from './engine';
-// export { Engine }

package/src/types.ts

@@ -15,8 +15,8 @@ export interface Command {
 // Event system types
 export interface EngineEvents {
   'page:set': { previousPage?: Page; newPage: Page };
-  'block:insert': { blockId: string; block: Block; parentId?: string; index?: number; regionName?: string };
-  'block:remove': { blockId: string; block: Block; parentId?: string };
+  '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 };
   'block:property:set': { blockId: string; key: string; value: any; oldValue: any };
   'block:update': { blockId: string; block: Block; property: string; value: any; oldValue: any };
@@ -24,9 +24,9 @@ export interface EngineEvents {
     blockId: string;
     targetParentId?: string;
     targetIndex?: number;
-    targetRegionName?: string;
+    targetRegionId?: string;
     sourceParentId?: string | null;
-    sourceRegionName?: string | null;
+    sourceRegionId?: string | null;
     sourceIndex: number;
   };
   'block:duplicate': {
@@ -35,7 +35,7 @@ export interface EngineEvents {
     newBlock: Block;
     parentId?: string;
     index?: number;
-    regionName?: string;
+    regionId?: string;
   };
   undo: { command: any };
   redo: { command: any };

package/src/utils.ts

@@ -1,3 +1,5 @@
+import type { Region } from '@craftile/types';
+
 export const generateId = (): string => {
   if (crypto.randomUUID) {
     return crypto.randomUUID();
@@ -5,3 +7,11 @@ export const generateId = (): string => {
 
   return Date.now().toString(36) + Math.random().toString(36).substr(2);
 };
+
+/**
+ * Get the unique identifier for a region.
+ * Falls back to name if id is not provided.
+ */
+export const getRegionId = (region: Region): string => {
+  return region.id || region.name;
+};

package/src/vue/useBlocksEngine.ts

@@ -28,7 +28,7 @@ export interface UseBlocksEngineReturn {
     blockType: string,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ) => string;
@@ -37,7 +37,7 @@ export interface UseBlocksEngineReturn {
     presetIndex: number,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ) => string;
@@ -47,7 +47,7 @@ export interface UseBlocksEngineReturn {
     options: {
       targetParentId?: string;
       targetIndex?: number;
-      targetRegionName?: string;
+      targetRegionId?: string;
     }
   ) => void;
   setBlockProperty: (blockId: string, propertyKey: string, propertyValue: any) => void;
@@ -58,7 +58,7 @@ export interface UseBlocksEngineReturn {
     structure: BlockStructure,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ) => string;
@@ -195,7 +195,7 @@ export function useBlocksEngine(
     blockType: string,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ): string => {
@@ -213,7 +213,7 @@ export function useBlocksEngine(
     presetIndex: number,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ): string => {
@@ -239,7 +239,7 @@ export function useBlocksEngine(
     options: {
       targetParentId?: string;
       targetIndex?: number;
-      targetRegionName?: string;
+      targetRegionId?: string;
     }
   ): void => {
     engine.moveBlock(blockId, options);
@@ -287,7 +287,7 @@ export function useBlocksEngine(
     structure: BlockStructure,
     options?: {
       parentId?: string;
-      regionName?: string;
+      regionId?: string;
       index?: number;
     }
   ): string => {