meno-core 1.0.0

package/lib/shared/paths/PathConverter.ts

@@ -0,0 +1,141 @@
+/**
+ * Path Conversion Utilities
+ * Handles conversion between array paths and string paths
+ */
+
+import type { Path } from './Path';
+import { ROOT_STRING, ROOT_0_STRING, CHILDREN_SEPARATOR, ROOT_PREFIX, CHILDREN_TOKEN, PATH_SEPARATOR } from './Path';
+import { validatePath, PathConversionError } from './PathValidator';
+
+/**
+ * Normalize path input to Path array
+ * Accepts both Path arrays and string paths, converts to Path array
+ * @param input - Path array or string path
+ * @returns Normalized Path array
+ */
+export function normalizePathInput(input: Path | string): Path {
+  if (typeof input === 'string') {
+    return stringToPath(input);
+  }
+  if (!Array.isArray(input)) {
+    throw new PathConversionError('Path input must be an array or string', input);
+  }
+  return input;
+}
+
+/**
+ * Convert array path to string for Map keys and DOM attributes
+ * [0,0,1] -> "0,0,1"
+ */
+export function pathToString(path: Path): string {
+  return path.join(',');
+}
+
+/**
+ * Convert string path to array path
+ * "0,0,1" -> [0,0,1] (comma-separated format from pathToString)
+ * "0" -> [0]
+ * "root" -> [0]
+ */
+export function stringToPath(str: string): Path {
+  if (!str || str === ROOT_STRING || str === ROOT_0_STRING) {
+    return [0];
+  }
+
+  // Parse comma-separated format: "0,0,1" -> [0, 0, 1]
+  return str.split(',').map(s => {
+    const num = parseInt(s, 10);
+    if (isNaN(num)) {
+      throw new PathConversionError(`Invalid numeric index: ${s}`, str);
+    }
+    return num;
+  });
+}
+
+/**
+ * Convert array path to legacy string format (for backward compatibility)
+ * Converts Path arrays to legacy string format used by TreeNode.path and iframe messages
+ * 
+ * @param path - Path array to convert (e.g., [0,0,1])
+ * @returns Legacy string path (e.g., "root_0_children_0_children_1")
+ */
+export function pathToLegacyString(path: Path): string {
+  if (path.length === 0 || (path.length === 1 && path[0] === 0)) {
+    return ROOT_0_STRING;
+  }
+  
+  // Build: root_0_children_0_children_1
+  let result = ROOT_0_STRING;
+  for (let i = 1; i < path.length; i++) {
+    result += `${CHILDREN_SEPARATOR}${path[i]}`;
+  }
+  
+  return result;
+}
+
+/**
+ * Convert DOM path string to tree path array
+ * DOM paths: "root", "root_children_0"
+ * Tree paths: [0], [0,0]
+ */
+export function domPathStringToTreePath(domPath: string): Path {
+  if (domPath === ROOT_STRING || domPath === '') {
+    return [0];
+  }
+  
+  // Remove "root_" prefix and parse
+  const cleanPath = domPath.startsWith(ROOT_PREFIX) 
+    ? domPath.substring(ROOT_PREFIX.length)
+    : domPath;
+  
+  // Parse "children_0_children_1" -> [0, 1]
+  const parts = cleanPath.split(PATH_SEPARATOR);
+  const path: Path = [0]; // Tree paths always start with [0]
+  
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === CHILDREN_TOKEN && i + 1 < parts.length) {
+      const indexStr = parts[i + 1];
+      const index = parseInt(indexStr, 10);
+      if (!isNaN(index) && indexStr === String(index)) {
+        // Valid numeric index
+        path.push(index);
+        i++;
+      }
+      // Invalid index segments are silently skipped
+    }
+  }
+  
+  return path;
+}
+
+/**
+ * Convert tree path array to DOM path string
+ * Converts Path arrays to DOM path strings used for element registration and highlighting
+ * 
+ * @param path - Path array or string (e.g., [0,0,1] or "root_0_children_0_children_1")
+ * @returns DOM path string (e.g., "root_children_0_children_1")
+ * @throws {InvalidPathError} If path contains invalid values
+ */
+export function treePathToDomPathString(path: Path | string): string {
+  // Handle string input (backward compatibility)
+  if (typeof path === 'string') {
+    const pathArray = stringToPath(path);
+    return treePathToDomPathString(pathArray);
+  }
+  
+  // Validate path before processing
+  validatePath(path);
+  
+  if (path.length === 0 || (path.length === 1 && path[0] === 0)) {
+    return ROOT_STRING;
+  }
+  
+  // Build: root_children_0_children_1
+  let result = ROOT_STRING;
+  for (let i = 1; i < path.length; i++) {
+    result += `${CHILDREN_SEPARATOR}${path[i]}`;
+  }
+  
+  return result;
+}
+

package/lib/shared/paths/PathUtils.ts

@@ -0,0 +1,290 @@
+/**
+ * Path Utility Functions
+ * Common operations on paths
+ */
+
+import type { Path } from './Path';
+import type { ComponentNode } from '../types';
+import { isRootPath } from './PathValidator';
+import { normalizePathInput } from './PathConverter';
+import { isSlotMarker } from '../nodeUtils';
+
+/**
+ * Calculate path offset caused by slot expansion
+ *
+ * When a component structure contains {type: "children"} markers,
+ * they are replaced with actual instance children during rendering.
+ * This changes indices for all subsequent elements.
+ *
+ * Example:
+ *   Component structure: [children_marker, Card, Button]
+ *   If children_marker expands to 3 children: [child1, child2, child3, Card, Button]
+ *   Original indices:    [0,              1,    2]
+ *   Actual indices:      [0,1,2,          3,    4]
+ *   Offset for index 1:  +2 (expanded from 1 to 3 children)
+ *   Offset for index 2:  +2
+ *
+ * @param componentPath - Path in component context (e.g., [0, 0, 2])
+ * @param componentStructure - Component definition structure
+ * @param instanceChildren - Actual children from component instance
+ * @returns Offset to add to path indices due to slot expansion
+ */
+function calculateChildrenExpansionOffset(
+  componentPath: Path,
+  componentStructure: ComponentNode | undefined,
+  instanceChildren: ComponentNode['children'] | undefined
+): number {
+  if (!componentStructure || !Array.isArray(instanceChildren)) {
+    return 0;
+  }
+
+  // Count actual children (accounting for marker expansion)
+  const childrenCount = Array.isArray(instanceChildren) ? instanceChildren.length : (instanceChildren ? 1 : 0);
+
+  let offset = 0;
+  let currentNode = componentStructure;
+
+  // Walk the component structure following the path
+  for (let i = 1; i < componentPath.length; i++) {
+    const index = componentPath[i];
+
+    // Get children of current node
+    if (!currentNode || !Array.isArray((currentNode as any).children)) {
+      break;
+    }
+
+    const children = (currentNode as any).children;
+
+    // Check if first level has a slot marker that affects the index
+    if (i === 1 && Array.isArray(children) && children.length > 0 && isSlotMarker(children[0])) {
+      // Children marker is at index 0, so indices 0 to (childrenCount - 1) map to children
+      const pageFirstIndex = index;
+
+      // If page index is within the children range, it's a child (no offset)
+      if (pageFirstIndex < childrenCount) {
+        // Keep original offset (0)
+      } else {
+        // Page index is after slot expansion
+        // Subtract the offset (childrenCount - 1) to get component index
+        offset = childrenCount - 1;
+      }
+    }
+
+    // Move to next node in the path
+    if (index < children.length) {
+      currentNode = (children[index] as any) as ComponentNode;
+    } else {
+      break;
+    }
+  }
+
+  return offset;
+}
+
+/**
+ * Get parent path
+ * [0,0,1] -> [0,0]
+ * [0] -> [0] (root has no parent, return itself)
+ */
+export function getParentPath(path: Path): Path {
+  if (path.length <= 1) {
+    return [0]; // Root
+  }
+  return path.slice(0, -1);
+}
+
+/**
+ * Get child path by appending index
+ * [0,0] + 1 -> [0,0,1]
+ */
+export function getChildPath(parent: Path, index: number): Path {
+  return [...parent, index];
+}
+
+/**
+ * Check if path1 is ancestor of path2
+ * [0,0] is ancestor of [0,0,1] -> true
+ */
+export function isAncestorPath(ancestor: Path, descendant: Path): boolean {
+  if (ancestor.length >= descendant.length) {
+    return false;
+  }
+  return ancestor.every((val, idx) => val === descendant[idx]);
+}
+
+/**
+ * Get depth of path
+ * [0] -> 0, [0,1] -> 1, [0,1,2] -> 2
+ */
+export function getPathDepth(path: Path): number {
+  return Math.max(0, path.length - 1);
+}
+
+/**
+ * Build all parent paths for tree expansion
+ * [0,0,1] -> [[0], [0,0]]
+ */
+export function buildParentPaths(path: Path): Path[] {
+  if (isRootPath(path)) {
+    return [];
+  }
+  
+  const parents: Path[] = [];
+  for (let i = 1; i < path.length; i++) {
+    parents.push(path.slice(0, i));
+  }
+  
+  return parents;
+}
+
+/**
+ * Compare two paths for equality
+ * Accepts both Path arrays and strings, normalizes before comparison
+ *
+ * @param path1 - First path (Path array or string)
+ * @param path2 - Second path (Path array or string)
+ * @returns True if paths are equal
+ */
+export function pathsEqual(path1: Path | string, path2: Path | string): boolean {
+  const normalizedPath1 = normalizePathInput(path1);
+  const normalizedPath2 = normalizePathInput(path2);
+
+  if (normalizedPath1.length !== normalizedPath2.length) {
+    return false;
+  }
+  return normalizedPath1.every((val, idx) => val === normalizedPath2[idx]);
+}
+
+/**
+ * Convert page-context path to component-context path
+ *
+ * When editing a component, paths from the canvas are in page context
+ * (full path including component instance location). This function converts
+ * them to component-context paths (relative to component definition root).
+ *
+ * Accounts for {type: "children"} expansion when provided with component
+ * structure and instance children.
+ *
+ * @param pagePath - Path in page context (e.g., [0, 0, 1, 0, 0])
+ * @param componentInstancePath - Path to component instance in page (e.g., [0, 0, 1])
+ * @param componentStructure - Component definition structure (for children offset calculation)
+ * @param instanceChildren - Actual children from component instance (for children offset calculation)
+ * @returns Path in component context (e.g., [0, 0, 0]) or null if not within component
+ *
+ * @example
+ * convertPagePathToComponentPath([0, 0, 1, 0, 0], [0, 0, 1])
+ * // Returns: [0, 0, 0]
+ *
+ * convertPagePathToComponentPath([0, 0, 2], [0, 0, 1])
+ * // Returns: null (not within component instance)
+ *
+ * convertPagePathToComponentPath([0, 0, 1, 4], [0, 0, 1], structure, [child1, child2, child3])
+ * // If structure has slot marker at index 0:
+ * // Returns: [0, 1] (not [0, 4] - offset back by -3)
+ */
+export function convertPagePathToComponentPath(
+  pagePath: Path,
+  componentInstancePath: Path,
+  componentStructure?: ComponentNode,
+  instanceChildren?: ComponentNode['children']
+): Path | null {
+  // Check if pagePath starts with componentInstancePath
+  // Path must be within or equal to component instance
+  const isWithinComponent = isAncestorPath(componentInstancePath, pagePath) ||
+                             pathsEqual(pagePath, componentInstancePath);
+
+  if (!isWithinComponent) {
+    return null; // Path is not within the component instance
+  }
+
+  // Extract suffix (indices after component instance path)
+  const suffix = pagePath.slice(componentInstancePath.length);
+
+  // If we need to account for slot expansion, build the component path to calculate offset
+  let adjustedSuffix = suffix;
+  if (suffix.length > 0 && componentStructure && Array.isArray(instanceChildren)) {
+    const childrenCount = instanceChildren.length;
+
+    // Check if first level has a slot marker that affects the index
+    if (
+      Array.isArray(componentStructure.children) &&
+      componentStructure.children.length > 0 &&
+      isSlotMarker(componentStructure.children[0])
+    ) {
+      // Children marker is at index 0, so indices 0 to (childrenCount - 1) map to children
+      const pageFirstIndex = suffix[0];
+
+      // If page index is within the children range, it's a child (no component path)
+      if (pageFirstIndex < childrenCount) {
+        // This element is from instance children, not part of component structure
+        // We can still return the path but know it's an instance child
+        // Keep the original suffix
+        adjustedSuffix = suffix;
+      } else {
+        // Page index is after slot expansion
+        // Subtract the offset (childrenCount - 1) to get component index
+        const offset = childrenCount - 1;
+        adjustedSuffix = [suffix[0] - offset, ...suffix.slice(1)];
+      }
+    }
+  }
+
+  // Component paths always start with [0] (component root)
+  return [0, ...adjustedSuffix];
+}
+
+/**
+ * Convert component-context path to page-context path
+ *
+ * When editing a component, tree selections use component-context paths.
+ * To highlight in the canvas, we need to convert them to page-context paths
+ * (full path including component instance location).
+ *
+ * Accounts for {type: "children"} expansion when provided with component
+ * structure and instance children.
+ *
+ * @param componentPath - Path in component context (e.g., [0, 0, 0])
+ * @param componentInstancePath - Path to component instance in page (e.g., [0, 0, 1])
+ * @param componentStructure - Component definition structure (for children offset calculation)
+ * @param instanceChildren - Actual children from component instance (for children offset calculation)
+ * @returns Path in page context (e.g., [0, 0, 1, 0, 0])
+ *
+ * @example
+ * convertComponentPathToPagePath([0, 0, 0], [0, 0, 1])
+ * // Returns: [0, 0, 1, 0, 0]
+ *
+ * convertComponentPathToPagePath([0], [0, 0, 1])
+ * // Returns: [0, 0, 1] (component root maps to instance)
+ *
+ * convertComponentPathToPagePath([0, 1], [0, 0, 1], structure, [child1, child2, child3])
+ * // If structure has slot marker at index 0:
+ * // Returns: [0, 0, 1, 4] (not [0, 0, 1, 1] - offset by +3)
+ */
+export function convertComponentPathToPagePath(
+  componentPath: Path,
+  componentInstancePath: Path,
+  componentStructure?: ComponentNode,
+  instanceChildren?: ComponentNode['children']
+): Path {
+  // Component paths start with [0] (component root)
+  if (componentPath.length === 1 && componentPath[0] === 0) {
+    // Component root maps to the component instance path
+    return componentInstancePath;
+  }
+
+  // Extract suffix (everything after component root [0])
+  const suffix = componentPath.slice(1);
+
+  // Calculate offset caused by slot expansion
+  const offset = calculateChildrenExpansionOffset(componentPath, componentStructure, instanceChildren);
+
+  // Apply offset to first level index if slot expansion occurred
+  let adjustedSuffix = suffix;
+  if (offset > 0 && suffix.length > 0) {
+    adjustedSuffix = [suffix[0] + offset, ...suffix.slice(1)];
+  }
+
+  // Append adjusted suffix to component instance path
+  return [...componentInstancePath, ...adjustedSuffix];
+}
+

package/lib/shared/paths/PathValidator.test.ts

@@ -0,0 +1,193 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  validatePath,
+  isRootPath,
+  InvalidPathError,
+  PathConversionError
+} from './PathValidator';
+
+describe('PathValidator', () => {
+  describe('validatePath', () => {
+    test('validates valid path', () => {
+      expect(() => validatePath([0, 1, 2])).not.toThrow();
+    });
+
+    test('validates empty path', () => {
+      expect(() => validatePath([])).not.toThrow();
+    });
+
+    test('validates single element path', () => {
+      expect(() => validatePath([0])).not.toThrow();
+    });
+
+    test('validates path with zero', () => {
+      expect(() => validatePath([0, 0, 0])).not.toThrow();
+    });
+
+    test('validates path with large numbers', () => {
+      expect(() => validatePath([100, 200, 300])).not.toThrow();
+    });
+
+    test('throws on non-array path', () => {
+      expect(() => validatePath('not an array' as any)).toThrow(InvalidPathError);
+    });
+
+    test('throws on path with string value', () => {
+      expect(() => validatePath([0, '1' as any, 2])).toThrow(InvalidPathError);
+    });
+
+    test('throws on path with NaN', () => {
+      expect(() => validatePath([0, NaN, 2])).toThrow(InvalidPathError);
+    });
+
+    test('throws on path with Infinity', () => {
+      expect(() => validatePath([0, Infinity, 2])).toThrow(InvalidPathError);
+    });
+
+    test('throws on path with negative Infinity', () => {
+      expect(() => validatePath([0, -Infinity, 2])).toThrow(InvalidPathError);
+    });
+
+    test('throws on path with null', () => {
+      expect(() => validatePath([0, null as any, 2])).toThrow(InvalidPathError);
+    });
+
+    test('throws on path with undefined', () => {
+      expect(() => validatePath([0, undefined as any, 2])).toThrow(InvalidPathError);
+    });
+
+    test('throws on path with object', () => {
+      expect(() => validatePath([0, {} as any, 2])).toThrow(InvalidPathError);
+    });
+
+    test('InvalidPathError includes path in error', () => {
+      const invalidPath = [0, 'invalid' as any, 2];
+      try {
+        validatePath(invalidPath);
+        expect(true).toBe(false); // Should not reach here
+      } catch (error) {
+        expect(error).toBeInstanceOf(InvalidPathError);
+        if (error instanceof InvalidPathError) {
+          expect(error.path).toBe(invalidPath);
+          expect(error.index).toBe(1);
+        }
+      }
+    });
+
+    test('InvalidPathError includes index', () => {
+      try {
+        validatePath([0, 1, 'bad' as any, 3]);
+      } catch (error) {
+        if (error instanceof InvalidPathError) {
+          expect(error.index).toBe(2);
+        }
+      }
+    });
+
+    test('allows negative numbers', () => {
+      expect(() => validatePath([0, -1, -5])).not.toThrow();
+    });
+
+    test('allows decimal numbers', () => {
+      expect(() => validatePath([0, 1.5, 2.7])).not.toThrow();
+    });
+  });
+
+  describe('isRootPath', () => {
+    test('returns true for empty path', () => {
+      expect(isRootPath([])).toBe(true);
+    });
+
+    test('returns true for [0] path', () => {
+      expect(isRootPath([0])).toBe(true);
+    });
+
+    test('returns false for [0, 1] path', () => {
+      expect(isRootPath([0, 1])).toBe(false);
+    });
+
+    test('returns false for [1] path', () => {
+      expect(isRootPath([1])).toBe(false);
+    });
+
+    test('returns false for multi-element path', () => {
+      expect(isRootPath([0, 1, 2])).toBe(false);
+    });
+
+    test('returns false for non-zero single element', () => {
+      expect(isRootPath([5])).toBe(false);
+    });
+
+    test('returns false for path starting with non-zero', () => {
+      expect(isRootPath([1, 0])).toBe(false);
+    });
+  });
+
+  describe('InvalidPathError', () => {
+    test('creates error with message and path', () => {
+      const path = [0, 'bad' as any];
+      const error = new InvalidPathError('Test message', path);
+      expect(error.message).toBe('Test message');
+      expect(error.path).toBe(path);
+      expect(error.name).toBe('InvalidPathError');
+    });
+
+    test('creates error with index', () => {
+      const error = new InvalidPathError('Test', [0, 'bad' as any], 1);
+      expect(error.index).toBe(1);
+    });
+
+    test('is instance of Error', () => {
+      const error = new InvalidPathError('Test', [0]);
+      expect(error instanceof Error).toBe(true);
+    });
+
+    test('has proper prototype chain', () => {
+      const error = new InvalidPathError('Test', [0]);
+      expect(error instanceof InvalidPathError).toBe(true);
+      expect(error instanceof Error).toBe(true);
+    });
+
+    test('allows undefined index', () => {
+      const error = new InvalidPathError('Test', [0]);
+      expect(error.index).toBeUndefined();
+    });
+  });
+
+  describe('PathConversionError', () => {
+    test('creates error with message and input', () => {
+      const input = 'invalid input';
+      const error = new PathConversionError('Test message', input);
+      expect(error.message).toBe('Test message');
+      expect(error.input).toBe(input);
+      expect(error.name).toBe('PathConversionError');
+    });
+
+    test('is instance of Error', () => {
+      const error = new PathConversionError('Test', 'input');
+      expect(error instanceof Error).toBe(true);
+    });
+
+    test('has proper prototype chain', () => {
+      const error = new PathConversionError('Test', 'input');
+      expect(error instanceof PathConversionError).toBe(true);
+      expect(error instanceof Error).toBe(true);
+    });
+
+    test('stores any input type', () => {
+      const inputs = [
+        'string',
+        123,
+        null,
+        undefined,
+        {},
+        [],
+        true
+      ];
+      for (const input of inputs) {
+        const error = new PathConversionError('Test', input);
+        expect(error.input).toBe(input);
+      }
+    });
+  });
+});

package/lib/shared/paths/PathValidator.ts

@@ -0,0 +1,53 @@
+/**
+ * Path Validation
+ * Validates path arrays and provides error handling
+ */
+
+import type { Path } from './Path';
+
+/**
+ * Custom error classes for path operations
+ */
+export class InvalidPathError extends Error {
+  constructor(message: string, public readonly path: unknown, public readonly index?: number) {
+    super(message);
+    this.name = 'InvalidPathError';
+  }
+}
+
+export class PathConversionError extends Error {
+  constructor(message: string, public readonly input: unknown) {
+    super(message);
+    this.name = 'PathConversionError';
+  }
+}
+
+/**
+ * Validate that a path contains only valid numeric values
+ * @throws {InvalidPathError} If path contains invalid values
+ */
+export function validatePath(path: Path): void {
+  if (!Array.isArray(path)) {
+    throw new InvalidPathError('Path must be an array', path);
+  }
+  
+  for (let i = 0; i < path.length; i++) {
+    const value = path[i];
+    if (typeof value !== 'number' || isNaN(value) || !isFinite(value)) {
+      throw new InvalidPathError(
+        `Invalid path value at index ${i}: expected number, got ${typeof value}`,
+        path,
+        i
+      );
+    }
+  }
+}
+
+/**
+ * Check if path is root
+ * [0] -> true, [] -> true, [0,1] -> false
+ */
+export function isRootPath(path: Path): boolean {
+  return path.length === 0 || (path.length === 1 && path[0] === 0);
+}
+