meno-core 1.0.21 → 1.0.22

package/lib/server/services/componentService.ts

@@ -7,7 +7,9 @@
  */
 
 import { join } from 'path';
+import { existsSync, mkdirSync, unlinkSync, readdirSync, rmdirSync } from 'fs';
 import { loadComponentDirectory, loadJSONFile, parseJSON } from '../jsonLoader';
+import type { ComponentWithCategory } from '../jsonLoader';
 import { projectPaths } from '../projectContext';
 import type { ComponentDefinition } from '../../shared/types';
 
@@ -29,8 +31,17 @@ export interface ComponentLoader {
   loadFile(path: string): Promise<string | null>;
 }
 
+/**
+ * Component info with category metadata
+ */
+export interface ComponentInfo {
+  definition: ComponentDefinition;
+  category?: string;
+}
+
 export class ComponentService {
   private components = new Map<string, ComponentDefinition>();
+  private componentCategories = new Map<string, string | undefined>();
   private fs?: ComponentServiceFs;
   private loader?: ComponentLoader;
 
@@ -48,13 +59,14 @@ export class ComponentService {
 
   /**
    * Load all components from the components directory
-   * 
-   * Scans the ./components directory and loads all component definitions.
-   * Clears existing components before loading. Components are loaded from .json files,
-   * and associated .js and .css files are automatically loaded if they exist.
-   * 
+   *
+   * Scans the ./components directory recursively and loads all component definitions.
+   * Subdirectories are treated as category folders. Clears existing components before loading.
+   * Components are loaded from .json files, and associated .js and .css files are
+   * automatically loaded if they exist.
+   *
    * @returns Promise that resolves when all components are loaded
-   * 
+   *
    * @example
    * ```typescript
    * await componentService.loadAllComponents();
@@ -63,11 +75,23 @@ export class ComponentService {
    */
   async loadAllComponents(): Promise<void> {
     this.components.clear();
+    this.componentCategories.clear();
+
     const loadedComponents = this.loader
       ? await this.loader.loadDirectory(projectPaths.components())
       : await loadComponentDirectory(projectPaths.components());
+
     loadedComponents.forEach((value, key) => {
-      this.components.set(key, value);
+      // Extract category from the loaded component (set by recursive loader)
+      const componentWithCategory = value as ComponentWithCategory;
+      const category = componentWithCategory._category;
+
+      // Store category mapping
+      this.componentCategories.set(key, category);
+
+      // Remove internal metadata before storing
+      const { _category, _relativePath, ...cleanDef } = componentWithCategory;
+      this.components.set(key, cleanDef as ComponentDefinition);
     });
   }
 
@@ -108,12 +132,12 @@ export class ComponentService {
 
   /**
    * Get all components as a Record
-   * 
+   *
    * Returns all loaded components as a plain object for easy iteration
    * or serialization.
-   * 
+   *
    * @returns Record mapping component names to ComponentDefinition objects
-   * 
+   *
    * @example
    * ```typescript
    * const allComponents = componentService.getAllComponents();
@@ -130,6 +154,42 @@ export class ComponentService {
     return record;
   }
 
+  /**
+   * Get all components with their category information
+   *
+   * Returns all loaded components with category metadata derived from folder structure.
+   *
+   * @returns Record mapping component names to ComponentInfo objects (definition + category)
+   *
+   * @example
+   * ```typescript
+   * const components = componentService.getAllComponentsWithCategories();
+   * Object.entries(components).forEach(([name, info]) => {
+   *   console.log(`${name}: category=${info.category || 'uncategorized'}`);
+   * });
+   * ```
+   */
+  getAllComponentsWithCategories(): Record<string, ComponentInfo> {
+    const record: Record<string, ComponentInfo> = {};
+    this.components.forEach((value, key) => {
+      record[key] = {
+        definition: value,
+        category: this.componentCategories.get(key)
+      };
+    });
+    return record;
+  }
+
+  /**
+   * Get category for a component
+   *
+   * @param name - Component name
+   * @returns Category string if component is in a category folder, undefined otherwise
+   */
+  getComponentCategory(name: string): string | undefined {
+    return this.componentCategories.get(name);
+  }
+
   /**
    * Validate that a component has a valid structure
    * 
@@ -180,6 +240,16 @@ export class ComponentService {
     return true;
   }
 
+  /**
+   * Get the directory path for a component based on its category
+   * @internal
+   */
+  private getComponentDir(name: string, category?: string): string {
+    const componentsDir = projectPaths.components();
+    const cat = category ?? this.componentCategories.get(name);
+    return cat ? join(componentsDir, cat) : componentsDir;
+  }
+
   /**
    * Get component JavaScript from .js file
    *
@@ -198,7 +268,8 @@ export class ComponentService {
    * ```
    */
   async getComponentJavaScript(name: string): Promise<string | null> {
-    const jsFilePath = join(projectPaths.components(), `${name}.js`);
+    const componentDir = this.getComponentDir(name);
+    const jsFilePath = join(componentDir, `${name}.js`);
     try {
       const file = Bun.file(jsFilePath);
       if (await file.exists()) {
@@ -212,28 +283,32 @@ export class ComponentService {
 
   /**
    * Save component definition
-   * 
+   *
    * Saves component definition to a .json file and updates the cache.
    * The javascript field is automatically removed from the saved data
    * (JavaScript should only be in .js files).
-   * 
+   *
+   * If category is provided, the component is saved to the category subfolder.
+   * If category is undefined and component exists, it stays in its current location.
+   * If category is empty string '', component is saved to root (uncategorized).
+   *
    * @param name - Component name (without .json extension)
    * @param data - ComponentDefinition object to save
+   * @param category - Optional category folder name (empty string for root/uncategorized)
    * @returns Promise that resolves when the component is saved
-   * 
+   *
    * @throws {Error} If file write fails
-   * 
+   *
    * @example
    * ```typescript
-   * await componentService.saveComponent('Button', {
-   *   component: {
-   *     interface: { label: { type: 'string', default: 'Click me' } },
-   *     structure: { type: 'node', tag: 'button', children: [] }
-   *   }
-   * });
+   * // Save to root (uncategorized)
+   * await componentService.saveComponent('Button', buttonDef);
+   *
+   * // Save to 'ui' category folder
+   * await componentService.saveComponent('Card', cardDef, 'ui');
    * ```
    */
-  async saveComponent(name: string, data: ComponentDefinition): Promise<void> {
+  async saveComponent(name: string, data: ComponentDefinition, category?: string): Promise<void> {
     const writeFile = this.fs
       ? this.fs.writeFile.bind(this.fs)
       : (await import('fs/promises')).writeFile;
@@ -244,11 +319,26 @@ export class ComponentService {
       delete dataWithoutJS.component.javascript;
     }
 
-    const filePath = join(projectPaths.components(), `${name}.json`);
+    // Determine target directory
+    // If category is explicitly provided (including ''), use it
+    // Otherwise, use existing category or root
+    const targetCategory = category !== undefined
+      ? (category || undefined)  // Convert '' to undefined for root
+      : this.componentCategories.get(name);
+
+    const componentDir = this.getComponentDir(name, targetCategory);
+
+    // Create category directory if needed
+    if (targetCategory && !existsSync(componentDir)) {
+      mkdirSync(componentDir, { recursive: true });
+    }
+
+    const filePath = join(componentDir, `${name}.json`);
     await writeFile(filePath, JSON.stringify(dataWithoutJS, null, 2), 'utf-8');
 
     // Update in-memory cache
     this.components.set(name, dataWithoutJS);
+    this.componentCategories.set(name, targetCategory);
   }
 
   /**
@@ -272,12 +362,12 @@ export class ComponentService {
     const writeFile = this.fs
       ? this.fs.writeFile.bind(this.fs)
       : (await import('fs/promises')).writeFile;
-    const componentsDir = projectPaths.components();
-    const jsFilePath = join(componentsDir, `${name}.js`);
+    const componentDir = this.getComponentDir(name);
+    const jsFilePath = join(componentDir, `${name}.js`);
     await writeFile(jsFilePath, javascript || '', 'utf-8');
 
     // Reload the component to update the registry with the new JS
-    const componentPath = join(componentsDir, `${name}.json`);
+    const componentPath = join(componentDir, `${name}.json`);
     const componentData = await loadJSONFile(componentPath);
     if (componentData) {
       const parsed = parseJSON<ComponentDefinition>(componentData);
@@ -318,12 +408,12 @@ export class ComponentService {
     const writeFile = this.fs
       ? this.fs.writeFile.bind(this.fs)
       : (await import('fs/promises')).writeFile;
-    const componentsDir = projectPaths.components();
-    const cssFilePath = join(componentsDir, `${name}.css`);
+    const componentDir = this.getComponentDir(name);
+    const cssFilePath = join(componentDir, `${name}.css`);
     await writeFile(cssFilePath, css || '', 'utf-8');
 
     // Reload the component to update the registry with the new CSS
-    const componentPath = join(componentsDir, `${name}.json`);
+    const componentPath = join(componentDir, `${name}.json`);
     const componentData = await loadJSONFile(componentPath);
     if (componentData) {
       const parsed = parseJSON<ComponentDefinition>(componentData);
@@ -342,5 +432,141 @@ export class ComponentService {
       this.components.set(name, parsed);
     }
   }
+
+  /**
+   * Get all component folders (including empty ones)
+   *
+   * Scans the components directory for subdirectories.
+   * Returns all folder names, whether they contain components or not.
+   *
+   * @returns Array of folder names
+   *
+   * @example
+   * ```typescript
+   * const folders = componentService.getAllFolders();
+   * // ['ui', 'layout', 'content']
+   * ```
+   */
+  getAllFolders(): string[] {
+    const componentsDir = projectPaths.components();
+    if (!existsSync(componentsDir)) {
+      return [];
+    }
+
+    try {
+      const entries = readdirSync(componentsDir, { withFileTypes: true });
+      return entries
+        .filter(entry => entry.isDirectory())
+        .map(entry => entry.name)
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Create a component folder
+   *
+   * Creates an empty folder in the components directory.
+   * Useful for pre-creating category folders before moving components.
+   *
+   * @param folderName - Name of the folder to create
+   * @returns Promise that resolves when folder is created
+   *
+   * @throws {Error} If folder creation fails
+   *
+   * @example
+   * ```typescript
+   * await componentService.createFolder('ui');
+   * ```
+   */
+  async createFolder(folderName: string): Promise<void> {
+    if (!folderName || folderName.trim() === '') {
+      throw new Error('Folder name cannot be empty');
+    }
+
+    // Validate folder name (alphanumeric, dashes, underscores only)
+    const sanitized = folderName.trim().toLowerCase().replace(/[^a-z0-9-_]/g, '-');
+    if (sanitized !== folderName.trim()) {
+      throw new Error('Folder name can only contain lowercase letters, numbers, dashes, and underscores');
+    }
+
+    const componentsDir = projectPaths.components();
+    const folderPath = join(componentsDir, folderName);
+
+    if (existsSync(folderPath)) {
+      throw new Error('Folder already exists');
+    }
+
+    mkdirSync(folderPath, { recursive: true });
+  }
+
+  /**
+   * Move component to a different category folder
+   *
+   * Moves all component files (.json, .js, .css) from current location to new category folder.
+   * If newCategory is empty string or undefined, moves to root (uncategorized).
+   *
+   * @param name - Component name
+   * @param newCategory - Target category folder (empty string or undefined for root)
+   * @returns Promise that resolves when move is complete
+   *
+   * @throws {Error} If component doesn't exist or move fails
+   *
+   * @example
+   * ```typescript
+   * // Move Button from root to 'ui' category
+   * await componentService.moveComponent('Button', 'ui');
+   *
+   * // Move Card from 'ui' to root (uncategorized)
+   * await componentService.moveComponent('Card', '');
+   * ```
+   */
+  async moveComponent(name: string, newCategory: string | undefined): Promise<void> {
+    const currentCategory = this.componentCategories.get(name);
+    const targetCategory = newCategory || undefined;
+
+    // No-op if category unchanged
+    if (currentCategory === targetCategory) {
+      return;
+    }
+
+    const componentsDir = projectPaths.components();
+    const sourceDir = currentCategory ? join(componentsDir, currentCategory) : componentsDir;
+    const targetDir = targetCategory ? join(componentsDir, targetCategory) : componentsDir;
+
+    // Create target directory if needed
+    if (targetCategory && !existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+
+    // Move all component files (.json, .js, .css)
+    const extensions = ['.json', '.js', '.css'];
+    const { rename } = await import('fs/promises');
+
+    for (const ext of extensions) {
+      const sourcePath = join(sourceDir, `${name}${ext}`);
+      const targetPath = join(targetDir, `${name}${ext}`);
+
+      if (existsSync(sourcePath)) {
+        await rename(sourcePath, targetPath);
+      }
+    }
+
+    // Update category mapping
+    this.componentCategories.set(name, targetCategory);
+
+    // Clean up empty source directory (only if it's a category folder, not root)
+    if (currentCategory) {
+      try {
+        const remaining = readdirSync(sourceDir);
+        if (remaining.length === 0) {
+          rmdirSync(sourceDir);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
 }
 

package/lib/server/services/configService.ts

@@ -24,6 +24,12 @@ export interface IconsConfig {
   appleTouchIcon?: string;
 }
 
+/**
+ * Project-level enum definitions
+ * Keys are enum names, values are arrays of options
+ */
+export type EnumsConfig = Record<string, string[]>;
+
 /**
  * Raw project config structure from project.config.json
  */
@@ -34,6 +40,7 @@ interface RawProjectConfig {
   icons?: IconsConfig;
   libraries?: LibrariesConfig;
   csp?: CSPConfig;
+  enums?: EnumsConfig;
 }
 
 /**
@@ -241,6 +248,26 @@ export class ConfigService {
     return this.config.csp;
   }
 
+  /**
+   * Get project-level enums configuration
+   * Returns empty object if not configured
+   */
+  getEnums(): EnumsConfig {
+    if (!this.config?.enums || typeof this.config.enums !== 'object') {
+      return {};
+    }
+
+    // Validate that all values are string arrays
+    const result: EnumsConfig = {};
+    for (const [key, value] of Object.entries(this.config.enums)) {
+      if (Array.isArray(value) && value.every(item => typeof item === 'string')) {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Get raw config value by key (for extension)
    */

package/lib/server/services/index.ts

@@ -4,7 +4,7 @@
  */
 
 export { PageService } from './pageService';
-export { ComponentService } from './componentService';
+export { ComponentService, type ComponentInfo } from './componentService';
 export { FileWatcherService } from './fileWatcherService';
 export { CMSService, type ReferenceLocation } from './cmsService';
 

package/lib/server/ssr/ssrRenderer.ts

@@ -114,6 +114,28 @@ function getI18nResolver(ctx: SSRContext): ValueResolver | undefined {
   return createI18nResolver(ctx.locale, ctx.i18nConfig);
 }
 
+/**
+ * Process style templates and convert to utility classes.
+ * Handles {{item.field}} patterns within list contexts.
+ */
+function processStyleToClasses(
+  style: StyleObject | ResponsiveStyleObject | undefined,
+  ctx: SSRContext
+): string[] {
+  if (!style) return [];
+
+  let processedStyle = style;
+  const templateCtx = getTemplateContext(ctx);
+  if (templateCtx && !ctx.templateMode) {
+    processedStyle = processItemPropsTemplate(
+      style as Record<string, unknown>,
+      templateCtx,
+      getI18nResolver(ctx)
+    ) as StyleObject | ResponsiveStyleObject;
+  }
+  return responsiveStylesToClasses(processedStyle as ResponsiveStyleObject);
+}
+
 /**
  * Evaluate the if condition on a node with full SSR context.
  * Handles boolean, mapping, and string template values.
@@ -551,6 +573,14 @@ async function processList(node: ListNode, ctx: SSRContext): Promise<string> {
   }
 
   // Use configurable tag (defaults to 'div')
+  // If tag is explicitly false (or string "false" for backwards compatibility),
+  // render children without a container (fragment mode)
+  if (node.tag === false || node.tag === 'false') {
+    // Fragment mode - no container element, just children
+    // Note: emitTemplate requires a container, so templateHtml is not included
+    return childrenHTML;
+  }
+
   const tag = node.tag || 'div';
   return `<${tag}${classAttr}${listStyleAttr}${attrsStr}>${childrenHTML}${templateHtml}</${tag}>`;
 }
@@ -775,9 +805,9 @@ async function renderNode(
     // Build className array
     const classNames: string[] = ['oem'];
 
-    // Convert styles to utility classes
+    // Convert styles to utility classes (process templates in style values)
     if (nodeStyle) {
-      const utilityClasses = responsiveStylesToClasses(nodeStyle as ResponsiveStyleObject);
+      const utilityClasses = processStyleToClasses(nodeStyle, ctx);
       classNames.push(...utilityClasses);
     }
 
@@ -894,9 +924,9 @@ async function renderNode(
     // Build className array - start with olink base class
     const classNames: string[] = ['olink'];
 
-    // Convert styles to utility classes
+    // Convert styles to utility classes (process templates in style values)
     if (nodeStyle) {
-      const utilityClasses = responsiveStylesToClasses(nodeStyle as ResponsiveStyleObject);
+      const utilityClasses = processStyleToClasses(nodeStyle, ctx);
       classNames.push(...utilityClasses);
     }
 
@@ -1013,8 +1043,8 @@ async function renderNode(
     // Validate that all styles can generate utility classes (build-time warnings)
     validateStyleCoverage(nodeStyle, `Node: ${nodeType || 'unknown'}`);
 
-    // Convert style object to utility class names
-    utilityClasses = responsiveStylesToClasses(nodeStyle as ResponsiveStyleObject);
+    // Convert style object to utility class names (process templates in style values)
+    utilityClasses = processStyleToClasses(nodeStyle, ctx);
   } else if (nodeProps.style) {
     // If no node.style but props have style, keep it for backward compatibility
     if (isResponsiveStyle(nodeProps.style) && breakpoints && viewportWidth) {

package/lib/shared/constants.ts

@@ -21,6 +21,9 @@ export const API_ROUTES = {
   SAVE_COMPONENT: '/api/save-component',
   SAVE_COMPONENT_JS: '/api/save-component-js', // Save JavaScript to .js file
   SAVE_COMPONENT_CSS: '/api/save-component-css', // Save CSS to .css file
+  COMPONENT_CATEGORY: '/api/component-category', // Move component to category folder
+  COMPONENT_FOLDER: '/api/component-folder', // Create component folder
+  COMPONENT_FOLDERS: '/api/component-folders', // List all component folders
   COMPONENT_JS: '/api/component-js', // Get JavaScript from .js file
   CONFIG: '/api/config', // Get project config
   SAVE_CONFIG: '/api/save-config', // Save project config

package/lib/shared/i18n.test.ts

@@ -162,6 +162,79 @@ describe('i18n', () => {
       const value: I18nValue = { _i18n: true };
       expect(resolveTranslation(value, 'en', testConfig)).toBe('');
     });
+
+    // List props i18n tests
+    test('should resolve i18n list props (arrays)', () => {
+      const listValue = {
+        _i18n: true,
+        en: [{ title: 'English Item' }],
+        pl: [{ title: 'Polish Item' }],
+      } as I18nValue;
+
+      expect(resolveTranslation(listValue, 'en', testConfig)).toEqual([{ title: 'English Item' }]);
+      expect(resolveTranslation(listValue, 'pl', testConfig)).toEqual([{ title: 'Polish Item' }]);
+    });
+
+    test('should fallback to default locale for i18n list props', () => {
+      const listValue = {
+        _i18n: true,
+        en: [{ title: 'English Item' }],
+        pl: [{ title: 'Polish Item' }],
+      } as I18nValue;
+
+      // 'de' doesn't exist, should fallback to default 'en'
+      expect(resolveTranslation(listValue, 'de', testConfig)).toEqual([{ title: 'English Item' }]);
+    });
+
+    test('should fallback to first available for i18n list props when no default', () => {
+      const listValue = {
+        _i18n: true,
+        pl: [{ title: 'Polish Item' }],
+      } as I18nValue;
+
+      // 'fr' doesn't exist and 'en' (default) doesn't exist, should fallback to first available
+      expect(resolveTranslation(listValue, 'fr', testConfig)).toEqual([{ title: 'Polish Item' }]);
+    });
+
+    test('should return empty array if no translation available for list i18n', () => {
+      const listValue = {
+        _i18n: true,
+        en: [],  // Add empty array to make it a list i18n
+      } as I18nValue;
+      // Remove the empty array to test empty fallback detection
+      delete (listValue as any).en;
+
+      // For pure list i18n with no values, we need to detect array type from other values
+      // Since there are no values, it defaults to empty string
+      // Let's test with a value that was removed
+      const listValueWithRemoved = {
+        _i18n: true,
+      } as I18nValue;
+      expect(resolveTranslation(listValueWithRemoved, 'en', testConfig)).toBe('');
+    });
+
+    test('should handle multi-item list props per locale', () => {
+      const listValue = {
+        _i18n: true,
+        en: [
+          { title: 'First EN', desc: 'Desc 1' },
+          { title: 'Second EN', desc: 'Desc 2' },
+        ],
+        pl: [
+          { title: 'First PL', desc: 'Opis 1' },
+          { title: 'Second PL', desc: 'Opis 2' },
+          { title: 'Third PL', desc: 'Opis 3' },
+        ],
+      } as I18nValue;
+
+      const enResult = resolveTranslation(listValue, 'en', testConfig);
+      expect(Array.isArray(enResult)).toBe(true);
+      expect((enResult as any[]).length).toBe(2);
+
+      const plResult = resolveTranslation(listValue, 'pl', testConfig);
+      expect(Array.isArray(plResult)).toBe(true);
+      expect((plResult as any[]).length).toBe(3);
+    });
   });
 
   describe('resolveI18nValue', () => {
@@ -179,6 +252,16 @@ describe('i18n', () => {
       expect(resolveI18nValue(123, 'pl', testConfig)).toBe(123);
       expect(resolveI18nValue(null, 'pl', testConfig)).toBeNull();
     });
+
+    test('should resolve i18n list props (arrays)', () => {
+      const listValue = {
+        _i18n: true,
+        en: [{ title: 'English' }],
+        pl: [{ title: 'Polish' }],
+      };
+      expect(resolveI18nValue(listValue, 'pl', testConfig)).toEqual([{ title: 'Polish' }]);
+      expect(resolveI18nValue(listValue, 'en', testConfig)).toEqual([{ title: 'English' }]);
+    });
   });
 
   describe('resolveI18nInProps', () => {
@@ -232,6 +315,29 @@ describe('i18n', () => {
       expect(resolved.enabled).toBe(true);
       expect((resolved.data as any).value).toBe(100);
     });
+
+    test('should resolve i18n list props correctly', () => {
+      const props = {
+        items: {
+          _i18n: true,
+          en: [{ title: 'EN Item 1' }, { title: 'EN Item 2' }],
+          pl: [{ title: 'PL Item 1' }, { title: 'PL Item 2' }, { title: 'PL Item 3' }],
+        },
+        title: { _i18n: true, en: 'Hello', pl: 'Cześć' },
+      };
+
+      const resolvedPL = resolveI18nInProps(props, 'pl', testConfig);
+      expect(resolvedPL.title).toBe('Cześć');
+      expect(Array.isArray(resolvedPL.items)).toBe(true);
+      expect((resolvedPL.items as any[]).length).toBe(3);
+      expect((resolvedPL.items as any[])[0].title).toBe('PL Item 1');
+
+      const resolvedEN = resolveI18nInProps(props, 'en', testConfig);
+      expect(resolvedEN.title).toBe('Hello');
+      expect(Array.isArray(resolvedEN.items)).toBe(true);
+      expect((resolvedEN.items as any[]).length).toBe(2);
+      expect((resolvedEN.items as any[])[0].title).toBe('EN Item 1');
+    });
   });
 
   describe('extractLocaleFromPath', () => {