meno-core 1.0.0

package/lib/shared/propResolver.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared prop resolution utility
+ * Resolves component props by applying defaults from interface definitions
+ * Used by both client (React) and server (SSR) rendering
+ */
+
+import type { StructuredComponentDefinition, ComponentNode, PropDefinition, I18nConfig } from './types';
+import { validateComponentProps } from './validation/propValidator';
+import { resolveI18nInProps } from './i18n';
+
+export interface ResolvePropsOptions {
+  propDefs: Record<string, PropDefinition>;
+  passedProps: Record<string, unknown>;
+  children: Array<ComponentNode | string> | string | ComponentNode | null | undefined;
+  locale?: string;
+  i18nConfig?: I18nConfig;
+}
+
+/**
+ * Resolves component props by applying defaults and merging with passed props
+ * Now includes validation for type safety
+ * 
+ * @param options - Object containing prop definitions, passed props, and children
+ * @returns Resolved props object with defaults applied and validated
+ */
+export function resolveComponentProps(options: ResolvePropsOptions): Record<string, unknown> {
+  const { propDefs, passedProps, children = [], locale, i18nConfig } = options;
+  
+  // Validate props against interface definition
+  // This provides runtime type checking while maintaining backward compatibility
+  try {
+    const validationResult = validateComponentProps(propDefs, passedProps);
+    
+    if (!validationResult.valid && validationResult.errors.length > 0) {
+      // Log validation errors but continue (graceful degradation)
+    }
+    
+    // Use validated props (includes coerced values and defaults)
+    const validatedProps = validationResult.props;
+    
+    // Handle children prop separately (not validated by prop validator)
+    const resolvedProps: Record<string, unknown> = { ...validatedProps };
+    
+    // Apply children handling
+    if ('children' in propDefs) {
+      const childrenPropDef = propDefs.children;
+      if (childrenPropDef && typeof childrenPropDef === 'object' && 'default' in childrenPropDef) {
+        resolvedProps.children = Array.isArray(children) && children.length > 0 
+          ? children 
+          : childrenPropDef.default;
+      } else {
+        resolvedProps.children = Array.isArray(children) && children.length > 0 
+          ? children 
+          : undefined;
+      }
+    } else if (Array.isArray(children) && children.length > 0) {
+      // Children passed but not in interface - allow it (backward compatibility)
+      resolvedProps.children = children;
+    }
+
+    // Resolve i18n translations if locale and config are provided
+    if (locale && i18nConfig) {
+      return resolveI18nInProps(resolvedProps, locale, i18nConfig);
+    }
+
+    return resolvedProps;
+  } catch (error) {
+    // Fallback to original behavior if validation fails (backward compatibility)
+    const resolvedProps: Record<string, unknown> = {};
+    
+    // Apply defaults and passed props (original logic)
+    for (const [propName, propDef] of Object.entries(propDefs)) {
+      if (propDef && typeof propDef === 'object' && 'default' in propDef) {
+        if (propName === 'children') {
+          resolvedProps.children = Array.isArray(children) && children.length > 0 
+            ? children 
+            : propDef.default;
+        } else {
+          resolvedProps[propName] = passedProps[propName] !== undefined 
+            ? passedProps[propName] 
+            : propDef.default;
+        }
+      } else {
+        if (propName === 'children') {
+          resolvedProps.children = Array.isArray(children) && children.length > 0 
+            ? children 
+            : undefined;
+        } else {
+          resolvedProps[propName] = passedProps[propName];
+        }
+      }
+    }
+    
+    return resolvedProps;
+  }
+}
+
+/**
+ * Resolves props from a structured component definition
+ *
+ * @param componentDef - Structured component definition
+ * @param passedProps - Props passed to the component instance
+ * @param children - Children passed to the component instance
+ * @param locale - Optional locale for i18n resolution
+ * @param i18nConfig - Optional i18n configuration
+ * @returns Resolved props object
+ */
+export function resolvePropsFromDefinition(
+  componentDef: StructuredComponentDefinition,
+  passedProps: Record<string, unknown> = {},
+  children: Array<ComponentNode | string> | string | ComponentNode | null | undefined = [],
+  locale?: string,
+  i18nConfig?: I18nConfig
+): Record<string, unknown> {
+  const propDefs = componentDef.interface || {};
+  return resolveComponentProps({
+    propDefs,
+    passedProps,
+    children,
+    locale,
+    i18nConfig,
+  });
+}
+

package/lib/shared/registry/BaseNodeTypeRegistry.test.ts

@@ -0,0 +1,190 @@
+/**
+ * BaseNodeTypeRegistry Tests
+ */
+
+import { describe, it, expect, beforeEach } from 'bun:test';
+import { ClientNodeTypeRegistry } from './ClientNodeTypeRegistry';
+import { SSRNodeTypeRegistry } from './SSRNodeTypeRegistry';
+import { NodeTypeManager, globalNodeTypeManager } from './NodeTypeManager';
+import { defineNodeType } from './defineNodeType';
+import { registerBuiltInNodeTypes, builtInNodeTypes } from './nodeTypes';
+import { NODE_TYPE } from '../constants';
+import type { HtmlNode, SlotMarker } from '../types/nodes';
+
+describe('BaseNodeTypeRegistry', () => {
+  let registry: ClientNodeTypeRegistry;
+
+  beforeEach(() => {
+    registry = new ClientNodeTypeRegistry();
+  });
+
+  describe('register', () => {
+    it('should register a node type definition', () => {
+      const mockDefinition = defineNodeType<HtmlNode>({
+        type: 'test-node',
+        displayName: 'Test Node',
+        category: 'core',
+        schema: {} as any,
+        typeGuard: (node): node is HtmlNode =>
+          node !== null && typeof node === 'object' && 'type' in node && node.type === 'test-node',
+        defaultFactory: () => ({ type: 'node', tag: 'div' }),
+        treeDisplay: { icon: 'HTML_ELEMENT', getLabel: () => 'Test' },
+        clientRenderer: () => null,
+        ssrRenderer: () => '',
+      });
+
+      registry.register(mockDefinition);
+      expect(registry.has('test-node')).toBe(true);
+      expect(registry.get('test-node')).toBe(mockDefinition);
+    });
+  });
+
+  describe('registerAll', () => {
+    it('should register multiple node type definitions', () => {
+      registry.registerAll(builtInNodeTypes);
+      expect(registry.size).toBe(7);
+      expect(registry.has(NODE_TYPE.NODE)).toBe(true);
+      expect(registry.has(NODE_TYPE.COMPONENT)).toBe(true);
+      expect(registry.has(NODE_TYPE.EMBED)).toBe(true);
+    });
+  });
+
+  describe('findByNode', () => {
+    beforeEach(() => {
+      registry.registerAll(builtInNodeTypes);
+    });
+
+    it('should find node type for HtmlNode', () => {
+      const htmlNode: HtmlNode = { type: 'node', tag: 'div' };
+      const definition = registry.findByNode(htmlNode);
+      expect(definition).toBeDefined();
+      expect(definition?.type).toBe(NODE_TYPE.NODE);
+    });
+
+    it('should find node type for SlotMarker', () => {
+      const slotNode: SlotMarker = { type: 'slot' };
+      const definition = registry.findByNode(slotNode);
+      expect(definition).toBeDefined();
+      expect(definition?.type).toBe(NODE_TYPE.SLOT);
+    });
+
+    it('should return undefined for unknown nodes', () => {
+      const unknownNode = { type: 'unknown' } as any;
+      const definition = registry.findByNode(unknownNode);
+      expect(definition).toBeUndefined();
+    });
+  });
+
+  describe('isType', () => {
+    beforeEach(() => {
+      registry.registerAll(builtInNodeTypes);
+    });
+
+    it('should return true for matching types', () => {
+      const htmlNode = { type: 'node', tag: 'div' };
+      expect(registry.isType(htmlNode, NODE_TYPE.NODE)).toBe(true);
+    });
+
+    it('should return false for non-matching types', () => {
+      const htmlNode = { type: 'node', tag: 'div' };
+      expect(registry.isType(htmlNode, NODE_TYPE.COMPONENT)).toBe(false);
+    });
+  });
+
+  describe('getNodeLabel', () => {
+    beforeEach(() => {
+      registry.registerAll(builtInNodeTypes);
+    });
+
+    it('should return label info for html node', () => {
+      const htmlNode: HtmlNode = { type: 'node', tag: 'header' };
+      const labelInfo = registry.getNodeLabel(htmlNode);
+      expect(labelInfo).toEqual({ label: 'header', icon: 'HTML_ELEMENT' });
+    });
+
+    it('should return label info for embed node', () => {
+      const embedNode = { type: 'embed', html: '<div>test</div>' };
+      const labelInfo = registry.getNodeLabel(embedNode as any);
+      expect(labelInfo).toEqual({ label: 'Embed', icon: 'HTML_ELEMENT' });
+    });
+  });
+
+  describe('createDefault', () => {
+    beforeEach(() => {
+      registry.registerAll(builtInNodeTypes);
+    });
+
+    it('should create default html node', () => {
+      const node = registry.createDefault(NODE_TYPE.NODE);
+      expect(node).toBeDefined();
+      expect(node?.type).toBe('node');
+      expect((node as HtmlNode).tag).toBe('div');
+    });
+
+    it('should create default embed node', () => {
+      const node = registry.createDefault(NODE_TYPE.EMBED);
+      expect(node).toBeDefined();
+      expect(node?.type).toBe('embed');
+    });
+
+    it('should return undefined for unknown type', () => {
+      const node = registry.createDefault('unknown');
+      expect(node).toBeUndefined();
+    });
+  });
+
+  describe('subscribe', () => {
+    it('should notify listeners on registration', () => {
+      let called = false;
+      registry.subscribe(() => { called = true; });
+      registry.registerAll(builtInNodeTypes);
+      expect(called).toBe(true);
+    });
+
+    it('should allow unsubscribing', () => {
+      let callCount = 0;
+      const unsubscribe = registry.subscribe(() => { callCount++; });
+      registry.registerAll(builtInNodeTypes);
+      expect(callCount).toBe(1);
+
+      unsubscribe();
+      registry.clear();
+      expect(callCount).toBe(1); // Should not increment after unsubscribe
+    });
+  });
+
+  describe('getByCategory', () => {
+    beforeEach(() => {
+      registry.registerAll(builtInNodeTypes);
+    });
+
+    it('should filter by category', () => {
+      const coreTypes = registry.getByCategory('core');
+      expect(coreTypes.length).toBeGreaterThan(0);
+      expect(coreTypes.every(t => t.category === 'core')).toBe(true);
+    });
+  });
+});
+
+describe('NodeTypeManager', () => {
+  it('should register types in both client and SSR registries', () => {
+    const manager = new NodeTypeManager();
+    manager.registerAll(builtInNodeTypes);
+
+    expect(manager.getClient().has(NODE_TYPE.NODE)).toBe(true);
+    expect(manager.getSSR().has(NODE_TYPE.NODE)).toBe(true);
+  });
+});
+
+describe('globalNodeTypeManager', () => {
+  beforeEach(() => {
+    globalNodeTypeManager.clear();
+  });
+
+  it('should be a singleton', () => {
+    registerBuiltInNodeTypes();
+    expect(globalNodeTypeManager.has(NODE_TYPE.NODE)).toBe(true);
+    expect(globalNodeTypeManager.has(NODE_TYPE.EMBED)).toBe(true);
+    expect(globalNodeTypeManager.getAll().length).toBe(7);
+  });
+});

package/lib/shared/registry/BaseNodeTypeRegistry.ts

@@ -0,0 +1,200 @@
+/**
+ * Base Node Type Registry
+ * Abstract base class for node type registries
+ * Provides common functionality for client and SSR registries
+ */
+
+import type { ComponentNode } from '../types/nodes';
+import type { NodeTypeDefinition, NodeCategory, TreeIcon } from './NodeTypeDefinition';
+
+/**
+ * Node label info returned by getNodeLabel
+ */
+export interface NodeLabelInfo {
+  label: string;
+  icon: TreeIcon;
+}
+
+/**
+ * Base registry class with common functionality
+ */
+export abstract class BaseNodeTypeRegistry {
+  protected registry: Map<string, NodeTypeDefinition> = new Map();
+  private listeners: Set<() => void> = new Set();
+  private nodeTypeCache: WeakMap<object, NodeTypeDefinition | null> = new WeakMap();
+
+  /**
+   * Register a node type definition
+   */
+  register(definition: NodeTypeDefinition): void {
+    if (!definition.type) {
+      throw new Error('Node type definition must have a type');
+    }
+    this.registry.set(definition.type, definition);
+    this.nodeTypeCache = new WeakMap(); // Clear cache on registration
+    this.notify();
+  }
+
+  /**
+   * Register multiple node type definitions at once
+   */
+  registerAll(definitions: NodeTypeDefinition[]): void {
+    for (const definition of definitions) {
+      if (!definition.type) {
+        throw new Error('Node type definition must have a type');
+      }
+      this.registry.set(definition.type, definition);
+    }
+    this.nodeTypeCache = new WeakMap(); // Clear cache on registration
+    this.notify();
+  }
+
+  /**
+   * Get a node type definition by type string
+   */
+  get(type: string): NodeTypeDefinition | undefined {
+    return this.registry.get(type);
+  }
+
+  /**
+   * Check if a node type is registered
+   */
+  has(type: string): boolean {
+    return this.registry.has(type);
+  }
+
+  /**
+   * Get all registered node types
+   */
+  getAll(): NodeTypeDefinition[] {
+    return Array.from(this.registry.values());
+  }
+
+  /**
+   * Get node types by category
+   */
+  getByCategory(category: NodeCategory): NodeTypeDefinition[] {
+    return this.getAll().filter((def) => def.category === category);
+  }
+
+  /**
+   * Get list of registered type names
+   */
+  getNames(): string[] {
+    return Array.from(this.registry.keys());
+  }
+
+  /**
+   * Find node type definition by node object using type guards
+   * Uses WeakMap caching for performance
+   */
+  findByNode(node: ComponentNode): NodeTypeDefinition | undefined {
+    if (!node || typeof node !== 'object') {
+      return undefined;
+    }
+
+    // Check cache first
+    const cached = this.nodeTypeCache.get(node);
+    if (cached !== undefined) {
+      return cached || undefined;
+    }
+
+    // Linear search through registered types
+    for (const definition of this.registry.values()) {
+      if (definition.typeGuard(node)) {
+        this.nodeTypeCache.set(node, definition);
+        return definition;
+      }
+    }
+
+    // Cache miss result too
+    this.nodeTypeCache.set(node, null);
+    return undefined;
+  }
+
+  /**
+   * Check if a node matches a specific type
+   * More efficient than findByNode when you know the type
+   */
+  isType<T extends ComponentNode>(node: unknown, type: string): node is T {
+    const definition = this.registry.get(type);
+    if (!definition) {
+      return false;
+    }
+    return definition.typeGuard(node);
+  }
+
+  /**
+   * Get node label info for tree display
+   */
+  getNodeLabel(node: ComponentNode): NodeLabelInfo | undefined {
+    const definition = this.findByNode(node);
+    if (!definition) {
+      return undefined;
+    }
+    return {
+      label: definition.treeDisplay.getLabel(node),
+      icon: definition.treeDisplay.icon,
+    };
+  }
+
+  /**
+   * Get default node for a type
+   */
+  createDefault(type: string): ComponentNode | undefined {
+    const definition = this.registry.get(type);
+    if (!definition) {
+      return undefined;
+    }
+    return definition.defaultFactory();
+  }
+
+  /**
+   * Remove a node type by type string
+   */
+  remove(type: string): boolean {
+    if (this.has(type)) {
+      this.registry.delete(type);
+      this.nodeTypeCache = new WeakMap(); // Clear cache
+      this.notify();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Clear all registered node types
+   */
+  clear(): void {
+    this.registry.clear();
+    this.nodeTypeCache = new WeakMap();
+    this.notify();
+  }
+
+  /**
+   * Subscribe to registry changes. Returns an unsubscribe function.
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Get the number of registered node types
+   */
+  get size(): number {
+    return this.registry.size;
+  }
+
+  protected notify(): void {
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch {
+        // Silent fail - don't let one listener break others
+      }
+    }
+  }
+}

package/lib/shared/registry/ClientNodeTypeRegistry.ts

@@ -0,0 +1,34 @@
+/**
+ * Client Node Type Registry
+ * Registry specialized for client-side (React) rendering
+ */
+
+import type { ReactElement } from 'react';
+import type { ComponentNode } from '../types/nodes';
+import { BaseNodeTypeRegistry } from './BaseNodeTypeRegistry';
+import type { ClientRenderContext } from './NodeTypeDefinition';
+
+/**
+ * Client-side node type registry
+ * Extends base registry with client rendering capabilities
+ */
+export class ClientNodeTypeRegistry extends BaseNodeTypeRegistry {
+  /**
+   * Render a node using the registered renderer
+   * Returns null if no renderer is found for the node type
+   */
+  renderNode(node: ComponentNode, context: ClientRenderContext): ReactElement | null {
+    const definition = this.findByNode(node);
+    if (!definition) {
+      return null;
+    }
+    return definition.clientRenderer(node as any, context);
+  }
+
+  /**
+   * Check if a node can be rendered by this registry
+   */
+  canRender(node: ComponentNode): boolean {
+    return this.findByNode(node) !== undefined;
+  }
+}

package/lib/shared/registry/ClientRegistry.test.ts

@@ -0,0 +1,26 @@
+import { describe, test, expect } from 'bun:test';
+import { ClientRegistry } from './ClientRegistry';
+
+describe('ClientRegistry', () => {
+  test('can be instantiated', () => {
+    const registry = new ClientRegistry();
+    expect(registry).toBeDefined();
+  });
+
+  test('inherits from BaseComponentRegistry', () => {
+    const registry = new ClientRegistry();
+    const def = { component: { structure: { type: 'node', tag: 'div' } } };
+
+    registry.register('Test', def);
+    expect(registry.get('Test')).toEqual(def);
+  });
+
+  test('supports all base registry methods', () => {
+    const registry = new ClientRegistry();
+    expect(typeof registry.register).toBe('function');
+    expect(typeof registry.get).toBe('function');
+    expect(typeof registry.has).toBe('function');
+    expect(typeof registry.getAll).toBe('function');
+    expect(typeof registry.clear).toBe('function');
+  });
+});

package/lib/shared/registry/ClientRegistry.ts

@@ -0,0 +1,15 @@
+/**
+ * Client Component Registry
+ * Extends base registry with client-specific functionality
+ */
+
+import { BaseComponentRegistry } from './ComponentRegistry';
+import type { ComponentDefinition } from '../types';
+
+export class ClientRegistry extends BaseComponentRegistry {
+  /**
+   * Client-specific methods can be added here
+   * For now, it's the same as base registry
+   */
+}
+