meno-core 1.0.0

package/lib/shared/pathUtils.ts

@@ -0,0 +1,244 @@
+/**
+ * Shared path utility functions
+ * Used by both build system and server router
+ */
+
+import type { Path } from './paths';
+import { 
+  stringToPath, 
+  pathToLegacyString, 
+  getParentPath as getParentPathArray,
+  buildParentPaths as buildParentPathsArray,
+  pathsEqual,
+  isRootPath as isRootPathArray,
+  ROOT_STRING,
+  domPathStringToTreePath,
+  treePathToDomPathString,
+  isAncestorPath
+} from './paths';
+
+/**
+ * Convert a page path to static HTML file path
+ * 
+ * @example
+ * getStaticFilePath("/") -> "./dist/index.html"
+ * getStaticFilePath("/about") -> "./dist/about.html"
+ * getStaticFilePath("/blog/post-1") -> "./dist/blog-post-1.html"
+ */
+export function getStaticFilePath(pagePath: string, distDir: string = "./dist"): string {
+  if (pagePath === "/") {
+    return `${distDir}/index.html`;
+  }
+  
+  // Convert /about -> about.html
+  // Convert /blog/post-1 -> blog-post-1.html (flat structure)
+  const pathParts = pagePath.substring(1).split("/");
+  const fileName = pathParts.join("-") + ".html";
+  
+  return `${distDir}/${fileName}`;
+}
+
+/**
+ * Convert a page path to a page name (for file system)
+ * 
+ * @example
+ * pathToPageName("/") -> "index"
+ * pathToPageName("/about") -> "about"
+ */
+export function pathToPageName(pagePath: string): string {
+  return pagePath === "/" ? "index" : pagePath.substring(1);
+}
+
+/**
+ * Convert a page name to a page path
+ * 
+ * @example
+ * pageNameToPath("index") -> "/"
+ * pageNameToPath("about") -> "/about"
+ */
+export function pageNameToPath(pageName: string): string {
+  return pageName === "index" ? "/" : `/${pageName}`;
+}
+
+/**
+ * Convert tree path to DOM path
+ * The tree adds a synthetic "root" container, so "root_0" in the tree corresponds to "root" in the DOM
+ * Also accepts array paths: [0] -> "root", [0,0] -> "root_children_0"
+ * 
+ * Uses array operations internally for conversion.
+ * 
+ * @example
+ * treePathToDomPath("root_0") -> "root"
+ * treePathToDomPath("root_0_children_0") -> "root_children_0"
+ * treePathToDomPath([0]) -> "root"
+ * treePathToDomPath([0,0]) -> "root_children_0"
+ */
+export function treePathToDomPath(treePath: Path | string): string {
+  // Convert to array if needed, then use array-based conversion
+  const pathArray = typeof treePath === 'string' ? stringToPath(treePath) : treePath;
+  return treePathToDomPathString(pathArray);
+}
+
+/**
+ * Convert DOM path back to tree path
+ * The tree adds a synthetic "root" container, so "root" in the DOM corresponds to "root_0" in the tree
+ * Returns legacy string format for backward compatibility
+ * 
+ * Uses array operations internally for conversion.
+ * 
+ * @example
+ * domPathToTreePath("root") -> "root_0"
+ * domPathToTreePath("root_children_0") -> "root_0_children_0"
+ */
+export function domPathToTreePath(domPath: string): string {
+  // Convert DOM path to array, then to legacy tree path string
+  const pathArray = domPathStringToTreePath(domPath);
+  return pathToLegacyString(pathArray);
+}
+
+/**
+ * Build parent paths for expanding tree nodes
+ * Returns all parent path segments for a given tree path
+ * Also accepts array paths
+ * 
+ * @example
+ * buildParentPaths("root_0_children_0_children_1") -> ["root_0", "root_0_children_0"]
+ * buildParentPaths([0,0,1]) -> ["root_0", "root_0_children_0"]
+ */
+export function buildParentPaths(treePath: Path | string): string[] {
+  const pathArray = typeof treePath === 'string' ? stringToPath(treePath) : treePath;
+  
+  if (isRootPathArray(pathArray)) {
+    return [];
+  }
+  
+  const parentArrays = buildParentPathsArray(pathArray);
+  return parentArrays.map(pathToLegacyString);
+}
+
+/**
+ * Calculate parent path from a child path
+ * Also accepts array paths
+ * Example: root_0_children_0 -> root_0
+ * Example: root_0_children_0_children_1 -> root_0_children_0
+ * Example: [0,0] -> "root_0"
+ * Example: [0,0,1] -> "root_0_children_0"
+ */
+export function getParentPathFromChildPath(childPath: Path | string): string {
+  const pathArray = typeof childPath === 'string' ? stringToPath(childPath) : childPath;
+  const parentArray = getParentPathArray(pathArray);
+  return pathToLegacyString(parentArray);
+}
+
+/**
+ * Convert component instance path to component structure path
+ * When editing a component, elements clicked inside the component instance on the page
+ * need to be converted to their paths within the component structure.
+ * 
+ * Uses array operations internally for path manipulation.
+ * 
+ * @example
+ * componentInstancePath: "root_children_0" (component instance on page)
+ * instancePath: "root_children_0_children_1" (element inside instance)
+ * Returns: "root_children_1" (component structure path)
+ * 
+ * @param instancePath - Path of element within component instance on page (DOM path string)
+ * @param componentInstancePath - Path of the component instance root on the page (DOM path string)
+ * @returns Component structure path (always starts with "root")
+ */
+export function componentInstancePathToStructurePath(
+  instancePath: string,
+  componentInstancePath: string
+): string {
+  // Convert DOM paths to arrays for manipulation
+  const instancePathArray = domPathStringToTreePath(instancePath);
+  const componentInstancePathArray = domPathStringToTreePath(componentInstancePath);
+  
+  // Check if instancePath is inside componentInstancePath using array operations
+  if (!isAncestorPath(componentInstancePathArray, instancePathArray)) {
+    // Not inside component instance - return as-is (shouldn't happen, but handle gracefully)
+    return instancePath;
+  }
+  
+  // Extract relative path using array operations
+  // componentInstancePathArray: [0, 0] -> instancePathArray: [0, 0, 1]
+  // relative: [1] -> convert to DOM path: "root_children_1"
+  const relativePathArray = instancePathArray.slice(componentInstancePathArray.length);
+  
+  // Convert relative path array back to DOM path string
+  // If relative is empty, return root
+  if (relativePathArray.length === 0) {
+    return ROOT_STRING;
+  }
+  
+  // Build component structure path: root + relative path
+  return treePathToDomPathString(relativePathArray);
+}
+
+/**
+ * Convert component structure path to component instance path
+ * When selecting an element in the component structure tree, convert it to
+ * the path within the component instance on the page.
+ * 
+ * Uses array operations internally for path manipulation.
+ * 
+ * @example
+ * componentInstancePath: "root_children_0" (component instance on page)
+ * structurePath: "root_children_1" (element in component structure)
+ * Returns: "root_children_0_children_1" (path within instance on page)
+ * 
+ * @param structurePath - Path within component structure (starts with "root", DOM path string)
+ * @param componentInstancePath - Path of the component instance root on the page (DOM path string)
+ * @returns Path within component instance on page (DOM path string)
+ */
+export function componentStructurePathToInstancePath(
+  structurePath: string,
+  componentInstancePath: string
+): string {
+  // Convert DOM paths to arrays for manipulation
+  const structurePathArray = domPathStringToTreePath(structurePath);
+  const componentInstancePathArray = domPathStringToTreePath(componentInstancePath);
+  
+  // Extract relative path from structure path (skip root [0])
+  // structurePathArray: [0, 1] -> relative: [1]
+  const relativePathArray = structurePathArray.slice(1);
+  
+  // Combine component instance path with relative path using array operations
+  // componentInstancePathArray: [0, 0] + relativePathArray: [1] -> [0, 0, 1]
+  const instancePathArray: Path = [...componentInstancePathArray, ...relativePathArray];
+  
+  // Convert back to DOM path string
+  return treePathToDomPathString(instancePathArray);
+}
+
+/**
+ * Convert path for component editing context
+ * When editing a component, converts component instance paths to component structure paths
+ * 
+ * Uses array operations internally for path manipulation.
+ * 
+ * @param path - Path array from canvas
+ * @param isEditingComponent - Whether we're editing a component
+ * @param componentInstancePath - Path of component instance on page (if editing component, Path array)
+ * @returns Path array for selection/hover (converted for component context if needed)
+ */
+export function convertPathForComponentContext(
+  path: Path,
+  isEditingComponent: boolean,
+  componentInstancePath: Path | null
+): Path {
+  if (isEditingComponent && componentInstancePath) {
+    // Check if path is inside componentInstancePath using array operations
+    if (isAncestorPath(componentInstancePath, path)) {
+      // Extract relative path: componentInstancePath: [0, 0] -> path: [0, 0, 1]
+      // relative: [1] -> component structure path: [0, 1]
+      const relativePath = path.slice(componentInstancePath.length);
+      
+      // Build component structure path: [0] + relative path
+      return [0, ...relativePath];
+    }
+  }
+  
+  // Regular page editing - return path as-is
+  return path;
+}

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

@@ -0,0 +1,74 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  ROOT_STRING,
+  ROOT_0_STRING,
+  CHILDREN_SEPARATOR,
+  ROOT_PREFIX,
+  CHILDREN_TOKEN,
+  PATH_SEPARATOR,
+  type Path
+} from './Path';
+
+describe('Path types and constants', () => {
+  describe('Path type', () => {
+    test('Path is a number array', () => {
+      const path: Path = [0, 1, 2];
+      expect(Array.isArray(path)).toBe(true);
+      expect(path.every(n => typeof n === 'number')).toBe(true);
+    });
+
+    test('Root path is [0]', () => {
+      const root: Path = [0];
+      expect(root).toEqual([0]);
+      expect(root.length).toBe(1);
+    });
+
+    test('Nested path has multiple indices', () => {
+      const nested: Path = [0, 0, 1, 2];
+      expect(nested.length).toBe(4);
+    });
+  });
+
+  describe('Path constants', () => {
+    test('ROOT_STRING is "root"', () => {
+      expect(ROOT_STRING).toBe('root');
+    });
+
+    test('ROOT_0_STRING is "root_0"', () => {
+      expect(ROOT_0_STRING).toBe('root_0');
+    });
+
+    test('CHILDREN_SEPARATOR is "_children_"', () => {
+      expect(CHILDREN_SEPARATOR).toBe('_children_');
+    });
+
+    test('ROOT_PREFIX is "root_"', () => {
+      expect(ROOT_PREFIX).toBe('root_');
+    });
+
+    test('CHILDREN_TOKEN is "children"', () => {
+      expect(CHILDREN_TOKEN).toBe('children');
+    });
+
+    test('PATH_SEPARATOR is "_"', () => {
+      expect(PATH_SEPARATOR).toBe('_');
+    });
+  });
+
+  describe('Path string format', () => {
+    test('constants can build root path strings', () => {
+      expect(ROOT_0_STRING).toBe('root_0');
+    });
+
+    test('constants can build nested path strings', () => {
+      const path = `${ROOT_0_STRING}${CHILDREN_SEPARATOR}0${CHILDREN_SEPARATOR}1`;
+      expect(path).toBe('root_0_children_0_children_1');
+    });
+
+    test('CHILDREN_SEPARATOR connects indices', () => {
+      const parts = ['root_0', '0', '1'];
+      const joined = parts.join(CHILDREN_SEPARATOR);
+      expect(joined).toBe('root_0_children_0_children_1');
+    });
+  });
+});

package/lib/shared/paths/Path.ts

@@ -0,0 +1,23 @@
+/**
+ * Path Type Definition
+ * Single source of truth for Path type
+ */
+
+/**
+ * Path is represented as a number array: [0,0,1]
+ * Root is represented as [0]
+ */
+export type Path = number[];
+
+/**
+ * Path string constants
+ */
+export const ROOT_STRING = 'root';
+export const ROOT_0_STRING = 'root_0';
+export const CHILDREN_SEPARATOR = '_children_';
+const ROOT_PREFIX = 'root_';
+const CHILDREN_TOKEN = 'children';
+const PATH_SEPARATOR = '_';
+
+export { ROOT_PREFIX, CHILDREN_TOKEN, PATH_SEPARATOR };
+

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

@@ -0,0 +1,232 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  normalizePathInput,
+  pathToString,
+  stringToPath,
+  pathToLegacyString,
+  domPathStringToTreePath,
+  treePathToDomPathString
+} from './PathConverter';
+import { PathConversionError } from './PathValidator';
+
+describe('PathConverter', () => {
+  describe('normalizePathInput', () => {
+    test('returns path array unchanged', () => {
+      const path = [0, 1, 2];
+      expect(normalizePathInput(path)).toEqual([0, 1, 2]);
+    });
+
+    test('converts string to path array', () => {
+      expect(normalizePathInput('0,1,2')).toEqual([0, 1, 2]);
+    });
+
+    test('converts root string to [0]', () => {
+      expect(normalizePathInput('root')).toEqual([0]);
+    });
+
+    test('throws on non-array non-string input', () => {
+      expect(() => normalizePathInput(123 as any)).toThrow(PathConversionError);
+      expect(() => normalizePathInput({} as any)).toThrow(PathConversionError);
+    });
+  });
+
+  describe('pathToString', () => {
+    test('converts path to comma-separated string', () => {
+      expect(pathToString([0, 1, 2])).toBe('0,1,2');
+    });
+
+    test('converts single element path', () => {
+      expect(pathToString([0])).toBe('0');
+    });
+
+    test('converts empty path', () => {
+      expect(pathToString([])).toBe('');
+    });
+
+    test('handles path with zeros', () => {
+      expect(pathToString([0, 0, 0])).toBe('0,0,0');
+    });
+
+    test('handles path with large numbers', () => {
+      expect(pathToString([100, 200, 300])).toBe('100,200,300');
+    });
+  });
+
+  describe('stringToPath', () => {
+    test('converts comma-separated string to path', () => {
+      expect(stringToPath('0,1,2')).toEqual([0, 1, 2]);
+    });
+
+    test('converts single number string', () => {
+      expect(stringToPath('5')).toEqual([5]);
+    });
+
+    test('converts root string to [0]', () => {
+      expect(stringToPath('root')).toEqual([0]);
+      expect(stringToPath('root_0')).toEqual([0]);
+    });
+
+    test('converts empty string to [0]', () => {
+      expect(stringToPath('')).toEqual([0]);
+    });
+
+    test('throws on invalid numeric string', () => {
+      expect(() => stringToPath('0,abc,2')).toThrow(PathConversionError);
+    });
+
+    test('throws on non-numeric values', () => {
+      expect(() => stringToPath('a,b,c')).toThrow(PathConversionError);
+    });
+
+    test('handles path with zeros', () => {
+      expect(stringToPath('0,0,0')).toEqual([0, 0, 0]);
+    });
+
+    test('parses negative numbers', () => {
+      expect(stringToPath('0,-1,2')).toEqual([0, -1, 2]);
+    });
+  });
+
+  describe('pathToLegacyString', () => {
+    test('converts [0] to root_0', () => {
+      expect(pathToLegacyString([0])).toBe('root_0');
+    });
+
+    test('converts empty path to root_0', () => {
+      expect(pathToLegacyString([])).toBe('root_0');
+    });
+
+    test('converts [0,0] to root_0_children_0', () => {
+      expect(pathToLegacyString([0, 0])).toBe('root_0_children_0');
+    });
+
+    test('converts [0,1,2] to root_0_children_1_children_2', () => {
+      expect(pathToLegacyString([0, 1, 2])).toBe('root_0_children_1_children_2');
+    });
+
+    test('handles deep paths', () => {
+      expect(pathToLegacyString([0, 0, 1, 2, 3])).toBe('root_0_children_0_children_1_children_2_children_3');
+    });
+
+    test('handles path with large indices', () => {
+      expect(pathToLegacyString([0, 100])).toBe('root_0_children_100');
+    });
+  });
+
+  describe('domPathStringToTreePath', () => {
+    test('converts root to [0]', () => {
+      expect(domPathStringToTreePath('root')).toEqual([0]);
+    });
+
+    test('converts empty string to [0]', () => {
+      expect(domPathStringToTreePath('')).toEqual([0]);
+    });
+
+    test('converts root_children_0 to [0,0]', () => {
+      expect(domPathStringToTreePath('root_children_0')).toEqual([0, 0]);
+    });
+
+    test('converts root_children_1_children_2 to [0,1,2]', () => {
+      expect(domPathStringToTreePath('root_children_1_children_2')).toEqual([0, 1, 2]);
+    });
+
+    test('handles deep DOM paths', () => {
+      expect(domPathStringToTreePath('root_children_0_children_1_children_2')).toEqual([0, 0, 1, 2]);
+    });
+
+    test('handles DOM path without root_ prefix', () => {
+      expect(domPathStringToTreePath('children_0_children_1')).toEqual([0, 0, 1]);
+    });
+
+    test('skips invalid segments', () => {
+      expect(domPathStringToTreePath('root_children_0_invalid_children_1')).toEqual([0, 0, 1]);
+    });
+
+    test('handles path with large indices', () => {
+      expect(domPathStringToTreePath('root_children_100')).toEqual([0, 100]);
+    });
+
+    test('handles malformed paths gracefully', () => {
+      expect(domPathStringToTreePath('root_children_abc')).toEqual([0]);
+    });
+  });
+
+  describe('treePathToDomPathString', () => {
+    test('converts [0] to root', () => {
+      expect(treePathToDomPathString([0])).toBe('root');
+    });
+
+    test('converts empty path to root', () => {
+      expect(treePathToDomPathString([])).toBe('root');
+    });
+
+    test('converts [0,0] to root_children_0', () => {
+      expect(treePathToDomPathString([0, 0])).toBe('root_children_0');
+    });
+
+    test('converts [0,1,2] to root_children_1_children_2', () => {
+      expect(treePathToDomPathString([0, 1, 2])).toBe('root_children_1_children_2');
+    });
+
+    test('handles deep paths', () => {
+      expect(treePathToDomPathString([0, 0, 1, 2, 3])).toBe('root_children_0_children_1_children_2_children_3');
+    });
+
+    test('handles string input by converting first', () => {
+      expect(treePathToDomPathString('0,1,2')).toBe('root_children_1_children_2');
+    });
+
+    test('throws on invalid path values', () => {
+      expect(() => treePathToDomPathString([0, NaN, 2])).toThrow();
+    });
+
+    test('throws on non-numeric path values', () => {
+      expect(() => treePathToDomPathString([0, 'invalid' as any, 2])).toThrow();
+    });
+
+    test('handles path with large indices', () => {
+      expect(treePathToDomPathString([0, 100])).toBe('root_children_100');
+    });
+
+    test('validates path before conversion', () => {
+      expect(() => treePathToDomPathString([0, Infinity])).toThrow();
+    });
+  });
+
+  describe('round-trip conversions', () => {
+    test('pathToString and stringToPath are inverses', () => {
+      const path = [0, 1, 2, 3];
+      const str = pathToString(path);
+      const result = stringToPath(str);
+      expect(result).toEqual(path);
+    });
+
+    test('treePathToDomPathString and domPathStringToTreePath are inverses', () => {
+      const path = [0, 1, 2, 3];
+      const str = treePathToDomPathString(path);
+      const result = domPathStringToTreePath(str);
+      expect(result).toEqual(path);
+    });
+
+    test('multiple round-trips preserve path', () => {
+      let path = [0, 1, 2];
+      for (let i = 0; i < 3; i++) {
+        const str = treePathToDomPathString(path);
+        path = domPathStringToTreePath(str);
+      }
+      expect(path).toEqual([0, 1, 2]);
+    });
+
+    test('pathToString handles empty path correctly', () => {
+      const path: number[] = [];
+      const str = pathToString(path);
+      expect(str).toBe('');
+    });
+
+    test('root path conversions are consistent', () => {
+      expect(treePathToDomPathString([0])).toBe('root');
+      expect(domPathStringToTreePath('root')).toEqual([0]);
+      expect(treePathToDomPathString([])).toBe('root');
+    });
+  });
+});