mtrl 0.2.8 → 0.3.0

package/src/core/composition/features/icon.ts

@@ -0,0 +1,131 @@
+// src/core/composition/features/icon.ts
+import { createElement } from '../../dom/create';
+
+/**
+ * Configuration for icon feature
+ */
+export interface IconConfig {
+  /**
+   * Icon HTML content
+   */
+  icon?: string;
+  
+  /**
+   * Position of the icon ('start' or 'end')
+   */
+  iconPosition?: 'start' | 'end';
+  
+  /**
+   * Size variant for the icon
+   */
+  iconSize?: string;
+  
+  /**
+   * CSS class prefix
+   */
+  prefix?: string;
+  
+  /**
+   * Component name for class generation
+   */
+  componentName?: string;
+  
+  [key: string]: any;
+}
+
+/**
+ * Enhances component schema with an icon element
+ * Unlike the traditional withIcon, this modifies the schema
+ * without creating actual DOM elements.
+ * 
+ * @param config Configuration containing icon information
+ * @returns Component enhancer that adds icon to schema
+ * 
+ * @example
+ * ```ts
+ * // Add icon to a component schema
+ * const component = pipe(
+ *   createBase,
+ *   withLayout(config),
+ *   withIcon(config)
+ * )(config);
+ * ```
+ */
+export const withIcon = (config: IconConfig) => component => {
+  // If no icon or missing schema, return unmodified
+  if (!config.icon || !component.schema) {
+    return component;
+  }
+  
+  try {
+    // Get component details for class names
+    const prefix = config.prefix || component.config?.prefix || 'mtrl';
+    const componentName = config.componentName || component.componentName || 'component';
+    
+    // Clone the schema
+    const schema = JSON.parse(JSON.stringify(component.schema));
+    
+    // Determine icon position
+    const position = config.iconPosition || 'start';
+    
+    // Add the --icon modifier class to the main element
+    const elementClasses = schema.element.options.className || [];
+    const iconModifierClass = `${prefix}-${componentName}--icon`;
+    
+    if (Array.isArray(elementClasses)) {
+      if (!elementClasses.includes(iconModifierClass)) {
+        elementClasses.push(iconModifierClass);
+      }
+    } else if (typeof elementClasses === 'string') {
+      if (!elementClasses.includes(iconModifierClass)) {
+        schema.element.options.className = `${elementClasses} ${iconModifierClass}`.trim();
+      }
+    } else {
+      schema.element.options.className = [iconModifierClass];
+    }
+    
+    // Create icon element definition with component-specific class
+    const iconDef = {
+      name: 'icon',
+      creator: createElement,
+      options: {
+        tag: 'span',
+        className: [
+          `${prefix}-${componentName}-icon`,
+          `${prefix}-${componentName}-icon--${position}`
+        ],
+        html: config.icon
+      }
+    };
+    
+    // Add size class if specified
+    if (config.iconSize) {
+      const classes = iconDef.options.className;
+      if (Array.isArray(classes)) {
+        classes.push(`${prefix}-${componentName}-icon--${config.iconSize}`);
+      }
+    }
+    
+    // Add icon directly to the main element's children
+    if (position === 'start') {
+      // Create new children object with icon first
+      const existingChildren = { ...schema.element.children };
+      schema.element.children = {
+        icon: iconDef,
+        ...existingChildren
+      };
+    } else {
+      // Add icon after existing children
+      schema.element.children.icon = iconDef;
+    }
+    
+    // Return component with updated schema
+    return {
+      ...component,
+      schema
+    };
+  } catch (error) {
+    console.warn('Error enhancing schema with icon:', error);
+    return component;
+  }
+};

package/src/core/composition/features/index.ts

@@ -0,0 +1,12 @@
+// src/core/composition/features/index.ts
+
+// Export composition features
+export { withLayout } from './layout';
+export { withIcon } from './icon';
+export { withLabel } from './label';
+export { withDom } from './dom';
+
+// Re-export interface types for better developer experience
+export type { IconConfig } from './icon';
+export type { LabelConfig } from './label';
+export type { LayoutConfig } from './layout';

package/src/core/composition/features/label.ts

@@ -0,0 +1,155 @@
+// src/core/composition/features/label.ts
+import { createElement } from '../../dom/create';
+
+/**
+ * Configuration for label feature
+ */
+export interface LabelConfig {
+  /**
+   * Label text content
+   */
+  label?: string;
+  
+  /**
+   * Position of the label ('start', 'end', 'top', or 'bottom')
+   */
+  labelPosition?: 'start' | 'end' | 'top' | 'bottom';
+  
+  /**
+   * CSS class prefix
+   */
+  prefix?: string;
+  
+  /**
+   * Component name for class generation
+   */
+  componentName?: string;
+  
+  /**
+   * ID for the input element this label is associated with
+   */
+  id?: string;
+  
+  /**
+   * Whether the labeled element is required
+   */
+  required?: boolean;
+  
+  [key: string]: any;
+}
+
+/**
+ * Enhances component schema with a label element
+ * Unlike the traditional withLabel, this modifies the schema
+ * without creating actual DOM elements.
+ * 
+ * @param config Configuration containing label information
+ * @returns Component enhancer that adds label to schema
+ * 
+ * @example
+ * ```ts
+ * // Add label to a component schema
+ * const component = pipe(
+ *   createBase,
+ *   withLayout(config),
+ *   withLabel(config)
+ * )(config);
+ * ```
+ */
+export const withLabel = (config: LabelConfig) => component => {
+  // If no label or missing schema, return unmodified
+  if (!config.label || !component.schema) {
+    return component;
+  }
+  
+  try {
+    // Get class name generator
+    const getClass = (className) => {
+      if (typeof component.getClass === 'function') {
+        return component.getClass(className);
+      }
+      const prefix = config.prefix || 'mtrl';
+      return `${prefix}-${className}`;
+    };
+    
+    // Get component details
+    const prefix = config.prefix || component.config?.prefix || 'mtrl';
+    const componentName = config.componentName || component.componentName || 'component';
+    
+    // Clone the schema
+    const schema = JSON.parse(JSON.stringify(component.schema));
+    
+    // Determine position (default to 'start')
+    const position = config.labelPosition || 'start';
+    
+    // Create the label element definition
+    let labelContent = config.label;
+    let labelChildren = null;
+    
+    // Add required indicator if specified
+    if (config.required) {
+      // For schema we need to define a child element
+      labelChildren = {
+        requiredIndicator: {
+          name: 'requiredIndicator',
+          creator: createElement,
+          options: {
+            tag: 'span',
+            className: `${prefix}-${componentName}-label-required`,
+            text: '*',
+            attrs: {
+              'aria-hidden': 'true'
+            }
+          }
+        }
+      };
+      
+      // Clear the content since we'll use children instead
+      labelContent = config.label;
+    }
+    
+    // Create label element definition
+    const labelDef = {
+      name: 'label',
+      creator: createElement,
+      options: {
+        tag: 'label',
+        className: [
+          `${prefix}-${componentName}-label`,
+          `${prefix}-${componentName}-label--${position}`
+        ],
+        attrs: {
+          'for': config.id // Optional connection to input by ID
+        },
+        text: labelContent
+      }
+    };
+    
+    // Add children if we have them
+    if (labelChildren) {
+      labelDef.children = labelChildren;
+    }
+    
+    // Add label to root element's children
+    if (position === 'end' || position === 'bottom') {
+      // Add at end of root element
+      schema.element.children.label = labelDef;
+    } else {
+      // Add at beginning of root element (start/top)
+      const existingChildren = { ...schema.element.children };
+      schema.element.children = {
+        label: labelDef,
+        ...existingChildren
+      };
+    }
+    
+    // Return component with updated schema
+    return {
+      ...component,
+      schema
+    };
+  } catch (error) {
+    console.warn('Error enhancing schema with label:', error);
+    return component;
+  }
+};

package/src/core/composition/features/layout.ts

@@ -0,0 +1,47 @@
+// src/core/composition/features/layout.ts
+
+/**
+ * Configuration that includes a component schema
+ */
+export interface LayoutConfig {
+  /**
+   * Component schema definition
+   */
+  schema?: any;
+  
+  [key: string]: any;
+}
+
+/**
+ * Adds schema definition to component without creating DOM
+ * This establishes the blueprint for the component's layout
+ * before materializing it with withDom
+ * 
+ * @param config Configuration containing schema definition
+ * @returns Component enhancer with schema definition
+ * 
+ * @example
+ * ```ts
+ * // Add layout to a component
+ * const component = pipe(
+ *   createBase,
+ *   withLayout(config),
+ *   withIcon(config),
+ *   withLabel(config),
+ *   withDom()
+ * )(config);
+ * ```
+ */
+export const withLayout = (config: LayoutConfig) => component => {
+  // Use the schema definition from the config
+  if (!config.schema) {
+    console.warn('No schema definition found in component config');
+    return component;
+  }
+  
+  // Return enhanced component with schema definition
+  return {
+    ...component,
+    schema: config.schema
+  };
+};

package/src/core/composition/index.ts

@@ -0,0 +1,26 @@
+// src/core/composition/index.ts
+
+/**
+ * @module core/composition
+ * @description Composition utilities for creating components using the structure-based approach
+ * 
+ * The composition module provides features that work with the structure definition
+ * mechanism. Unlike traditional features that directly modify the DOM, these
+ * features modify a layout schema that is later used to create DOM elements.
+ * 
+ * This approach provides several advantages:
+ * - Clearer separation between layout and DOM creation
+ * - More predictable component creation process
+ * - Better support for server-side rendering
+ * - Enhanced testability
+ */
+
+// Export features
+export {
+  withLayout,
+  withDom,
+  withIcon,
+  withLabel,
+} from './features';
+
+export type { IconConfig, LabelConfig } from './features';

package/src/core/index.ts

@@ -11,7 +11,7 @@ export type {
   ComponentConfig, 
   ThemedComponentConfig, 
   VariantComponentConfig, 
-  StateComponentConfig 
+  StateComponentConfig
 } from './config';
 
 // Build