meno-core 1.0.0

package/lib/shared/treePathUtils.ts

@@ -0,0 +1,339 @@
+/**
+ * Tree path utilities for parsing and navigating tree structure paths
+ */
+
+import { ComponentNode, PageData, JSONPage } from './types';
+import type { PropDefinition } from './types';
+import type { Path } from './pathArrayUtils';
+import { stringToPath } from './pathArrayUtils';
+
+// Type for page data that can have component structure
+type PageDataWithComponent = PageData & {
+  component?: {
+    structure?: ComponentNode;
+    interface?: Record<string, PropDefinition>;
+  };
+};
+
+export interface NodeLocation {
+  parent: ComponentNode | PageData | null;
+  index: number;
+  node: ComponentNode | null;
+}
+
+/**
+ * Validate that component data has a valid structure
+ * @param pageData - PageData to validate
+ * @returns true if component has valid structure, false otherwise
+ */
+export function validateComponentStructure(pageData: PageData | null): boolean {
+  if (!pageData) return false;
+  
+  // Check for page format (has root property)
+  if ('root' in pageData && pageData.root) {
+    return true;
+  }
+  
+  // Check for component format (has component.structure property)
+  if ('component' in pageData && pageData.component) {
+    if ('structure' in pageData.component && pageData.component.structure) {
+      return true;
+    }
+    // Component exists but structure is missing
+    return false;
+  }
+  
+  return false;
+}
+
+/**
+ * Get the root data from pageData (handles both page and component structures
+ * Logs warnings when structure is missing for better debugging
+ */
+export function getRootData(pageData: PageData | null): ComponentNode | null {
+  if (!pageData) return null;
+  
+  // Check for page format (has root property)
+  if ('root' in pageData && pageData.root) {
+    return pageData.root;
+  }
+  
+  // Check for component format (has component.structure property)
+  if ('component' in pageData && pageData.component) {
+    if ('structure' in pageData.component) {
+      const structure = pageData.component.structure;
+      if (structure) {
+        return structure;
+      }
+      // Structure field exists but is null/undefined
+    } else {
+      // Component exists but structure field is missing
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Parse a tree path and return the parent, index, and node
+ * Handles paths like: root_0, root_0_children_0, root_0_children_0_children_1
+ * Also accepts array paths: [0], [0,0], [0,0,1]
+ */
+export function getParentAndIndexFromPath(
+  path: Path | string, 
+  pageData: PageData
+): NodeLocation | null {
+  const rootData = getRootData(pageData);
+  if (!rootData) return null;
+
+  // Convert string to array if needed
+  const pathArray = typeof path === 'string' ? stringToPath(path) : path;
+
+  // Handle root [0] specially
+  if (pathArray.length === 1 && pathArray[0] === 0) {
+    return {
+      parent: pageData,
+      index: 0,
+      node: rootData
+    };
+  }
+
+  // Navigate through path array
+  let current: ComponentNode = rootData;
+  let parent: ComponentNode | PageData | null = null;
+  let lastIndex = -1;
+
+  // Skip first element (root index 0), navigate through rest
+  for (let i = 1; i < pathArray.length; i++) {
+    const childIndex = pathArray[i];
+
+      if (!current || !('children' in current) || !Array.isArray(current.children)) {
+        return null;
+      }
+      
+      if (isNaN(childIndex) || childIndex < 0 || childIndex >= current.children.length) {
+        return null;
+      }
+
+    parent = current;
+      const child = current.children[childIndex];
+      if (typeof child === 'string') {
+        return null;
+      }
+      current = child;
+      lastIndex = childIndex;
+
+      // If this is the last navigation step, we found our node
+    if (i === pathArray.length - 1) {
+        return { parent, index: childIndex, node: current };
+    }
+  }
+
+  // Return the last valid location if we got here
+  if (parent && lastIndex >= 0) {
+    return { parent, index: lastIndex, node: current };
+  }
+
+  return null;
+}
+
+/**
+ * Extract structure without styles/props for tree comparison
+ * This allows tree to only regenerate when structure changes, not styles
+ */
+export function extractStructureWithoutStyles(node: ComponentNode | string | null | undefined): ComponentNode | string | null | undefined {
+  if (!node || typeof node === 'string') {
+    return node;
+  }
+
+  if (typeof node !== 'object') {
+    return node;
+  }
+
+  // Create a new object with only structure-relevant properties
+  const { type } = node;
+  const tag = 'tag' in node ? node.tag : undefined;
+  const children = 'children' in node ? node.children : undefined;
+  
+  // Recursively process children
+  const processedChildren = children
+    ? Array.isArray(children)
+      ? children.map((child: ComponentNode | string) => 
+          typeof child === 'string' ? child : extractStructureWithoutStyles(child) as ComponentNode
+        )
+      : typeof children === 'string' 
+        ? children 
+        : extractStructureWithoutStyles(children) as ComponentNode
+    : undefined;
+
+  return {
+    type,
+    ...(tag !== undefined ? { tag } : {}),
+    ...(processedChildren !== undefined ? { children: processedChildren } : {})
+  } as ComponentNode;
+}
+
+/**
+ * Calculate insertion index based on drop target information
+ */
+export function calculateInsertionIndex(
+  target: {
+    childIndex?: number;
+    childAfterItem?: { index: string };
+    childBeforeItem?: { index: string };
+    linearIndex?: number;
+  },
+  parentChildren: Array<ComponentNode | string>,
+  nodeDataMap: Map<string, ComponentNode | string>
+): number {
+  if (target.childIndex !== undefined && target.childIndex >= 0) {
+    // Most reliable: use childIndex directly
+    return Math.min(Math.max(0, target.childIndex), parentChildren.length);
+  }
+
+  if (target.childAfterItem?.index) {
+    const afterPath = target.childAfterItem.index;
+    const afterNode = nodeDataMap.get(afterPath);
+    if (afterNode) {
+      const afterIndex = parentChildren.findIndex((child: ComponentNode | string) => child === afterNode);
+      if (afterIndex >= 0) {
+        return afterIndex + 1;
+      }
+    }
+    // Fallback: append
+    return parentChildren.length;
+  }
+
+  if (target.childBeforeItem?.index) {
+    const beforePath = target.childBeforeItem.index;
+    const beforeNode = nodeDataMap.get(beforePath);
+    if (beforeNode) {
+      const beforeIndex = parentChildren.findIndex((child: ComponentNode | string) => child === beforeNode);
+      if (beforeIndex >= 0) {
+        return beforeIndex;
+      }
+    }
+    // Fallback: prepend
+    return 0;
+  }
+
+  // Last resort: use linearIndex or append
+  if (target.linearIndex !== undefined) {
+    return Math.min(Math.max(0, target.linearIndex), parentChildren.length);
+  }
+
+  return parentChildren.length;
+}
+
+/**
+ * Type guard to check if a value is a valid NodeLocation
+ */
+export function isValidNodeLocation(location: unknown): location is NodeLocation {
+  if (!location || typeof location !== 'object') {
+    return false;
+  }
+  
+  // Use proper type narrowing instead of assertion
+  const loc = location as Record<string, unknown>;
+  const hasParent = 'parent' in loc && (loc.parent === null || typeof loc.parent === 'object');
+  const hasIndex = 'index' in loc && typeof loc.index === 'number' && loc.index >= 0;
+  const hasNode = 'node' in loc && (loc.node === null || typeof loc.node === 'object');
+  
+  return hasParent && hasIndex && hasNode;
+}
+
+/**
+ * Type guard to check if a value is a valid Path
+ */
+export function isValidPath(path: unknown): path is Path {
+  if (!Array.isArray(path)) {
+    return false;
+  }
+  
+  // Path is an array of numbers
+  return path.every((item): item is number => typeof item === 'number' && item >= 0);
+}
+
+/**
+ * Type guard to check if parent is PageData
+ */
+export function isPageDataParent(
+  parent: ComponentNode | PageData | null
+): parent is PageData {
+  if (!parent) return false;
+  
+  // Check for JSONPage format (has root property)
+  if ('root' in parent) return true;
+  
+  // Check for component format - component must be an object, not a string
+  if ('component' in parent) {
+    return typeof parent.component === 'object' && parent.component !== null;
+  }
+  
+  return false;
+}
+
+/**
+ * Type guard to check if parent is ComponentNode
+ */
+export function isComponentNodeParent(
+  parent: ComponentNode | PageData | null
+): parent is ComponentNode {
+  if (!parent) return false;
+  // Check for 'type' property (all ComponentNodes have it)
+  // Then check for specific node types that can have children:
+  // - HtmlNode: has 'tag' property
+  // - ComponentInstanceNode: has 'component' property
+  // - SlotMarker: type === 'slot'
+  // - ObjectLinkNode: type === 'object-link'
+  // - EmbedNode: type === 'embed'
+  return 'type' in parent && (
+    'tag' in parent ||
+    'component' in parent ||
+    parent.type === 'slot' ||
+    parent.type === 'object-link' ||
+    parent.type === 'embed'
+  );
+}
+
+/**
+ * Get children array from parent (handles both PageData and ComponentNode)
+ */
+export function getParentChildren(
+  parent: ComponentNode | PageData | null
+): Array<ComponentNode | string> | null {
+  if (!parent) return null;
+  
+  if (isPageDataParent(parent)) {
+    const rootData = getRootData(parent);
+    return rootData && 'children' in rootData ? rootData.children || null : null;
+  }
+  
+  if (isComponentNodeParent(parent)) {
+    return 'children' in parent ? parent.children || null : null;
+  }
+  
+  return null;
+}
+
+/**
+ * Set children array on parent (handles both PageData and ComponentNode)
+ */
+export function setParentChildren(
+  parent: ComponentNode | PageData | null,
+  children: Array<ComponentNode | string>
+): void {
+  if (!parent) return;
+  
+  if (isPageDataParent(parent)) {
+    const rootData = getRootData(parent);
+    if (rootData && 'children' in rootData) {
+      rootData.children = children;
+    }
+  } else if (isComponentNodeParent(parent)) {
+    if ('children' in parent) {
+      parent.children = children;
+    }
+  }
+}
+

package/lib/shared/types/api.ts

@@ -0,0 +1,58 @@
+/**
+ * API Types
+ */
+
+import type { I18nValue } from './components';
+import type { CMSFieldDefinition } from './cms';
+
+export interface HMRMessage {
+  type: 'hmr:update' | 'hmr:colors-update';
+  path?: string;
+}
+
+export interface PageListResponse {
+  pages: string[];
+}
+
+export interface RouteHandler {
+  pattern: string | RegExp;
+  handler: (req: Request, url: URL) => Response | Promise<Response> | undefined;
+}
+
+/** Value that can be either a plain string or an i18n object */
+type StringOrI18n = string | I18nValue;
+
+/** CMS configuration embedded in page meta (includes full schema) */
+export interface PageCmsConfig {
+  /** Unique identifier for the collection */
+  id: string;
+  /** Display name for the collection */
+  name: string;
+  /** Which field to use for URL slug */
+  slugField: string;
+  /** URL pattern, e.g., "/blog/{{slug}}" */
+  urlPattern: string;
+  /** Field definitions */
+  fields: Record<string, CMSFieldDefinition>;
+}
+
+/**
+ * Page metadata structure
+ * Text fields can be either plain strings or i18n objects
+ */
+export interface PageMetaData {
+  title?: StringOrI18n;
+  description?: StringOrI18n;
+  keywords?: StringOrI18n;
+  ogTitle?: StringOrI18n;
+  ogDescription?: StringOrI18n;
+  ogImage?: string;
+  ogType?: string;
+  /** Translated slugs for each locale, e.g., { "en": "about", "pl": "o-nas" } */
+  slugs?: Record<string, string>;
+  /** Data source: 'static' (default) or 'cms' */
+  source?: 'static' | 'cms';
+  /** CMS configuration with embedded schema (required when source: 'cms') */
+  cms?: PageCmsConfig;
+}
+

package/lib/shared/types/cms.ts

@@ -0,0 +1,95 @@
+/**
+ * CMS Types
+ * Defines schema structure and content items for CMS collections
+ */
+
+/** Field types supported by CMS */
+export type CMSFieldType =
+  | 'string'   // Single-line text
+  | 'text'     // Multi-line text / rich text
+  | 'number'   // Numeric value
+  | 'boolean'  // True/false
+  | 'image'    // Image URL/path
+  | 'date'     // ISO date string
+  | 'select'   // Single selection from options
+  | 'reference' // Reference to another collection item
+  | 'i18n'     // Internationalized text (single-line)
+  | 'i18n-text'; // Internationalized text (multi-line)
+
+/** Single field definition in a schema */
+export interface CMSFieldDefinition {
+  type: CMSFieldType;
+  required?: boolean;
+  default?: unknown;
+  label?: string;           // Display label in editor
+  description?: string;     // Help text
+  options?: string[];       // For 'select' type
+  collection?: string;      // For 'reference' type
+}
+
+/** CMS Schema - defines collection structure (embedded in page meta.cms) */
+export interface CMSSchema {
+  /** Unique identifier for the collection */
+  id: string;
+  /** Display name for the collection */
+  name: string;
+  /** Which field to use for URL slug */
+  slugField: string;
+  /** URL pattern, e.g., "/blog/{{slug}}" */
+  urlPattern: string;
+  /** Field definitions */
+  fields: Record<string, CMSFieldDefinition>;
+}
+
+/** CMS Item - actual content entry (stored as individual JSON file) */
+export interface CMSItem {
+  _id: string;
+  _slug?: string;           // Derived from filename (e.g., hello-world.json -> "hello-world")
+  _createdAt?: string;      // ISO timestamp
+  _updatedAt?: string;      // ISO timestamp
+  [field: string]: unknown;
+}
+
+/** CMS Collection - schema + items */
+export interface CMSCollection {
+  schema: CMSSchema;
+  items: CMSItem[];
+}
+
+/** Resolved CMS route match */
+export interface CMSRouteMatch {
+  collection: string;
+  slug: string;
+  item: CMSItem;
+  pagePath: string;  // Path to the template page file
+}
+
+/** Filter operators for CMS queries */
+export type CMSFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'in';
+
+/** Single filter condition */
+export interface CMSFilterCondition {
+  field: string;
+  operator?: CMSFilterOperator;  // defaults to 'eq'
+  value: unknown;
+}
+
+/** Sort configuration */
+export interface CMSSortConfig {
+  field: string;
+  order?: 'asc' | 'desc';  // defaults to 'asc'
+}
+
+/** CMSList query configuration */
+export interface CMSListQuery {
+  collection: string;
+  filter?: CMSFilterCondition | CMSFilterCondition[] | Record<string, unknown>;
+  sort?: CMSSortConfig | CMSSortConfig[];
+  limit?: number;
+  offset?: number;
+}
+
+/** CMSList component props (in JSON page) */
+export interface CMSListProps extends CMSListQuery {
+  /** Children are repeated for each item with {{item.field}} context */
+}

package/lib/shared/types/colors.ts

@@ -0,0 +1,45 @@
+/**
+ * Color Variables Types
+ * Handles color variable definitions and configuration
+ */
+
+/**
+ * Color variables configuration
+ * Maps semantic color names to their hex/rgb values
+ */
+export interface ColorVariables {
+  colors: Record<string, string>;
+}
+
+/**
+ * Theme configuration with color set and metadata
+ */
+export interface Theme {
+  label: string;
+  colors: Record<string, string>;
+}
+
+/**
+ * Theme configuration file structure
+ * Supports multiple named themes with a default theme
+ */
+export interface ThemeConfig {
+  default: string;
+  themes: Record<string, Theme>;
+}
+
+/**
+ * Color variable entry for editor display
+ */
+export interface ColorVariableEntry {
+  name: string;
+  value: string;
+}
+
+/**
+ * Theme entry for theme selector
+ */
+export interface ThemeEntry {
+  name: string;
+  label: string;
+}

package/lib/shared/types/components.ts

@@ -0,0 +1,121 @@
+/**
+ * Component Definition Types
+ * Improved type safety with stricter types
+ */
+
+import type { ComponentNode } from './nodes';
+
+/**
+ * Prop type definitions
+ */
+export type PropType = 'string' | 'select' | 'boolean' | 'number' | 'link' | 'file';
+
+/**
+ * Internationalization (i18n) value object
+ * Keys are locale codes (e.g., 'en', 'pl', 'de')
+ */
+export interface I18nValue {
+  _i18n: true;
+  [locale: string]: string | true;  // true is for the _i18n marker itself
+}
+
+/**
+ * Locale configuration with metadata
+ */
+export interface LocaleConfig {
+  code: string;        // URL prefix & translation key (e.g., "en", "pl")
+  name: string;        // English name for admin UI (e.g., "Polish")
+  nativeName: string;  // Native name for public UI (e.g., "Polski")
+  langTag: string;     // BCP 47 language tag for SEO (e.g., "pl-PL")
+  icon?: string;       // Optional flag icon path (e.g., "/icons/flag-en.svg")
+}
+
+/**
+ * Internationalization configuration
+ */
+export interface I18nConfig {
+  defaultLocale: string;
+  locales: LocaleConfig[];
+}
+
+/**
+ * Link prop value type
+ */
+export interface LinkPropValue {
+  href: string;
+  target?: '_blank';
+}
+
+/**
+ * Prop definition with improved type safety
+ */
+export interface PropDefinition {
+  type: PropType;
+  default?: string | number | boolean | I18nValue | LinkPropValue;
+  options?: readonly string[];  // Required for "select" type
+  accept?: string;  // For "file" type: MIME pattern like "image/*", "video/*"
+}
+
+/**
+ * Structured component definition
+ */
+export interface StructuredComponentDefinition {
+  interface?: Record<string, PropDefinition>;
+  structure?: ComponentNode;
+  javascript?: string;  // Vanilla JS code to be rendered at end of HTML
+  css?: string;  // CSS code to be rendered in <style> tag in <head>
+  category?: string;  // Component category for organization
+}
+
+/**
+ * Component definition
+ * Supports both new format (just component) and legacy format (type/props/children/component)
+ */
+export interface ComponentDefinition {
+  type?: string;  // Legacy format
+  props?: Record<string, unknown>;  // Legacy format
+  children?: unknown[];  // Legacy format
+  component: StructuredComponentDefinition;
+}
+
+/**
+ * Line range for element line number tracking
+ */
+export interface LineRange {
+  startLine: number;
+  endLine: number;
+}
+
+/**
+ * JSON page structure
+ */
+export interface JSONPage {
+  meta?: import('./api').PageMetaData;
+  components?: Record<string, ComponentDefinition>;
+  root?: ComponentNode;
+  _lineMap?: Record<string, LineRange>;
+}
+
+/**
+ * Page data type that can be either a JSONPage or a component definition structure
+ */
+export type PageData = JSONPage | { 
+  component: { 
+    structure?: ComponentNode; 
+    interface?: Record<string, PropDefinition>;
+    javascript?: string;
+    css?: string;
+  } 
+};
+
+/**
+ * Page data with component structure (for type narrowing)
+ */
+export interface PageDataWithComponent {
+  component: {
+    structure?: ComponentNode;
+    interface?: Record<string, PropDefinition>;
+    javascript?: string;
+    css?: string;
+  };
+}