mtrl 0.2.9 → 0.3.0

package/src/components/switch/features.ts

@@ -0,0 +1,198 @@
+// src/components/switch/features.ts
+import { BaseComponent, ElementComponent } from '../../core/compose/component';
+
+/**
+ * Configuration for supporting text feature
+ */
+export interface SupportingTextConfig {
+  /**
+   * Supporting text content
+   */
+  supportingText?: string;
+  
+  /**
+   * Whether supporting text indicates an error
+   */
+  error?: boolean;
+  
+  /**
+   * CSS class prefix
+   */
+  prefix?: string;
+  
+  /**
+   * Component name
+   */
+  componentName?: string;
+  
+  [key: string]: any;
+}
+
+/**
+ * Component with supporting text capabilities
+ */
+export interface SupportingTextComponent extends BaseComponent {
+  /**
+   * Supporting text element
+   */
+  supportingTextElement: HTMLElement | null;
+  
+  /**
+   * Sets supporting text content
+   * @param text - Text content
+   * @param isError - Whether text represents an error
+   * @returns Component instance for chaining
+   */
+  setSupportingText: (text: string, isError?: boolean) => SupportingTextComponent;
+  
+  /**
+   * Removes supporting text
+   * @returns Component instance for chaining
+   */
+  removeSupportingText: () => SupportingTextComponent;
+}
+
+/**
+ * Helper to ensure the switch has the proper container/content structure
+ * @param component - The component to enhance
+ * @param prefix - CSS class prefix
+ * @param componentName - Component name
+ * @returns The container and content elements
+ */
+const ensureSwitchStructure = (
+  component: ElementComponent, 
+  prefix: string, 
+  componentName: string
+) => {
+  const PREFIX = prefix || 'mtrl';
+  const COMPONENT = componentName || 'switch';
+  
+  // Create or find container
+  let container = component.element.querySelector(`.${PREFIX}-${COMPONENT}-container`);
+  if (!container) {
+    container = document.createElement('div');
+    container.className = `${PREFIX}-${COMPONENT}-container`;
+    
+    // Find input and track to move them to container
+    const input = component.element.querySelector(`.${PREFIX}-${COMPONENT}-input`);
+    const track = component.element.querySelector(`.${PREFIX}-${COMPONENT}-track`);
+    
+    // Gather all elements except container
+    const elementsToMove = [];
+    if (input) elementsToMove.push(input);
+    if (track) elementsToMove.push(track);
+    
+    // Create content wrapper
+    const contentWrapper = document.createElement('div');
+    contentWrapper.className = `${PREFIX}-${COMPONENT}-content`;
+    
+    // Find label and move to content
+    const label = component.element.querySelector(`.${PREFIX}-${COMPONENT}-label`);
+    if (label) {
+      contentWrapper.appendChild(label);
+    }
+    
+    // Add content wrapper to container first
+    container.appendChild(contentWrapper);
+    
+    // Add other elements to container
+    elementsToMove.forEach(el => container.appendChild(el));
+    
+    // Add container to component
+    component.element.appendChild(container);
+    
+    return { container, contentWrapper };
+  }
+  
+  // Container exists, find or create content wrapper
+  let contentWrapper = component.element.querySelector(`.${PREFIX}-${COMPONENT}-content`);
+  if (!contentWrapper) {
+    contentWrapper = document.createElement('div');
+    contentWrapper.className = `${PREFIX}-${COMPONENT}-content`;
+    
+    // Find label to move to content
+    const label = component.element.querySelector(`.${PREFIX}-${COMPONENT}-label`);
+    if (label) {
+      contentWrapper.appendChild(label);
+    }
+    
+    // Insert content wrapper at beginning of container
+    container.insertBefore(contentWrapper, container.firstChild);
+  }
+  
+  return { container, contentWrapper };
+};
+
+/**
+ * Creates and manages supporting text for a component
+ * @param config - Configuration object with supporting text settings
+ * @returns Function that enhances a component with supporting text functionality
+ */
+export const withSupportingText = <T extends SupportingTextConfig>(config: T) => 
+  <C extends ElementComponent>(component: C): C & SupportingTextComponent => {
+    const PREFIX = config.prefix || 'mtrl';
+    const COMPONENT = config.componentName || 'switch';
+    
+    // Ensure we have the proper container/content structure
+    const { contentWrapper } = ensureSwitchStructure(component, PREFIX, COMPONENT);
+    
+    // Create supporting text element if needed
+    let supportingElement = null;
+    if (config.supportingText) {
+      supportingElement = document.createElement('div');
+      supportingElement.className = `${PREFIX}-${COMPONENT}-helper`;
+      supportingElement.textContent = config.supportingText;
+      
+      if (config.error) {
+        supportingElement.classList.add(`${PREFIX}-${COMPONENT}-helper--error`);
+        component.element.classList.add(`${PREFIX}-${COMPONENT}--error`);
+      }
+      
+      // Add supporting text to the content wrapper
+      contentWrapper.appendChild(supportingElement);
+    }
+    
+    // Add lifecycle integration if available
+    if ('lifecycle' in component && component.lifecycle?.destroy && supportingElement) {
+      const originalDestroy = component.lifecycle.destroy;
+      component.lifecycle.destroy = () => {
+        if (supportingElement) supportingElement.remove();
+        originalDestroy.call(component.lifecycle);
+      };
+    }
+
+    return {
+      ...component,
+      supportingTextElement: supportingElement,
+      
+      setSupportingText(text: string, isError = false) {
+        const { contentWrapper } = ensureSwitchStructure(component, PREFIX, COMPONENT);
+        let supportingElement = this.supportingTextElement;
+        
+        if (!supportingElement) {
+          // Create if it doesn't exist
+          supportingElement = document.createElement('div');
+          supportingElement.className = `${PREFIX}-${COMPONENT}-helper`;
+          contentWrapper.appendChild(supportingElement);
+          this.supportingTextElement = supportingElement;
+        }
+        
+        supportingElement.textContent = text;
+        
+        // Handle error state
+        supportingElement.classList.toggle(`${PREFIX}-${COMPONENT}-helper--error`, isError);
+        component.element.classList.toggle(`${PREFIX}-${COMPONENT}--error`, isError);
+        
+        return this;
+      },
+      
+      removeSupportingText() {
+        if (this.supportingTextElement && this.supportingTextElement.parentNode) {
+          this.supportingTextElement.remove();
+          this.supportingTextElement = null;
+          component.element.classList.remove(`${PREFIX}-${COMPONENT}--error`);
+        }
+        return this;
+      }
+    };
+  };

package/src/components/switch/index.ts

@@ -1,3 +1,4 @@
 // src/components/switch/index.ts
 export { default } from './switch'
 export { SwitchConfig, SwitchComponent } from './types'
+export { withSupportingText, SupportingTextComponent } from './features'

package/src/components/switch/switch.ts

@@ -11,11 +11,11 @@ import {
   withCheckable
 } from '../../core/compose/features';
 import { withAPI } from './api';
+import { withSupportingText } from './features';
 import { SwitchConfig, SwitchComponent, BaseComponent } from './types';
 import { 
   createBaseConfig, 
   getElementConfig, 
-  withLabelPosition,
   getApiConfig
 } from './config';
 
@@ -32,10 +32,10 @@ const createSwitch = (config: SwitchConfig = {}): SwitchComponent => {
       createBase,
       withEvents(), // Move events first to ensure system is available
       withElement(getElementConfig(baseConfig)),
+      withTextLabel(baseConfig),
       withInput(baseConfig),
       withTrack(baseConfig),
-      withTextLabel(baseConfig),
-      withLabelPosition(baseConfig),
+      withSupportingText(baseConfig),
       withCheckable(baseConfig),
       withDisabled(baseConfig),
       withLifecycle(),

package/src/components/switch/types.ts

@@ -24,8 +24,11 @@ export interface SwitchConfig {
   /** Label text */
   label?: string;
   
-  /** Label position (start/end) */
-  labelPosition?: SwitchPosition | string;
+  /** Supporting text content */
+  supportingText?: string;
+  
+  /** Whether supporting text indicates an error */
+  error?: boolean;
   
   /** Additional CSS classes */
   class?: string;
@@ -77,6 +80,15 @@ export interface SwitchComponent {
   /** Gets the switch's label text */
   getLabel: () => string;
   
+  /** Supporting text element */
+  supportingTextElement: HTMLElement | null;
+  
+  /** Sets supporting text content */
+  setSupportingText: (text: string, isError?: boolean) => SwitchComponent;
+  
+  /** Removes supporting text */
+  removeSupportingText: () => SwitchComponent;
+  
   /** Adds event listener */
   on: (event: string, handler: Function) => SwitchComponent;
   

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

@@ -1,33 +1,45 @@
 // src/core/composition/features/dom.ts
-import { createStructure, flattenStructure } from '../../structure';
+import createLayout from '../../layout';
 
 /**
- * Creates DOM elements from structure definition using the core createStructure utility
- * This is a key feature that bridges the gap between declarative structure and actual DOM
+ * Creates DOM elements from component schema using the core createLayout utility
+ * This is a key feature that bridges the gap between declarative schema and actual DOM
  * 
- * @returns Component enhancer that creates DOM structure
+ * @returns Component enhancer that creates DOM structure from schema
+ * 
+ * @example
+ * ```ts
+ * // Materialize component schema into DOM
+ * const component = pipe(
+ *   createBase,
+ *   withLayout(config),
+ *   withIcon(config),
+ *   withLabel(config),
+ *   withDom()
+ * )(config);
+ * ```
  */
 export const withDom = () => component => {
-  // Return unmodified component if no structure definition
-  if (!component.structureDefinition) {
+  // Return unmodified component if no schema
+  if (!component.schema) {
     return component;
   }
   
   try {
-    // Use the existing createStructure function to build the DOM
-    const structure = createStructure(component.structureDefinition);
+    // Use the createLayout function to build the DOM from schema
+    const layout = createLayout(component.schema);
     
-    // Use the existing flattenStructure function to create a flat reference map
-    const components = structure.getAll();
+    // Use the layout's utility functions to get components
+    const components = layout.getAll();
 
-    // Return enhanced component with DOM structure
+    // Return enhanced component with DOM layout
     return {
       ...component,
-      element: structure.element, // Root element
-      components                  // All component elements
+      element: layout.element, // Root element
+      components               // All component elements
     };
   } catch (error) {
     console.error('Failed to create DOM structure:', error);
-    throw new Error(`Failed to create slider DOM: ${error.message}`);
+    throw new Error(`Failed to create component DOM: ${error.message}`);
   }
 };

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

@@ -34,26 +34,26 @@ export interface IconConfig {
 }
 
 /**
- * Enhances structure definition with an icon element
- * Unlike the traditional withIcon, this modifies the structure definition
+ * 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 structure definition
+ * @returns Component enhancer that adds icon to schema
  * 
  * @example
  * ```ts
- * // Add icon to a structure definition
+ * // Add icon to a component schema
  * const component = pipe(
  *   createBase,
- *   withStructure(config),
+ *   withLayout(config),
  *   withIcon(config)
  * )(config);
  * ```
  */
 export const withIcon = (config: IconConfig) => component => {
-  // If no icon or missing structure definition, return unmodified
-  if (!config.icon || !component.structureDefinition) {
+  // If no icon or missing schema, return unmodified
+  if (!config.icon || !component.schema) {
     return component;
   }
   
@@ -62,14 +62,14 @@ export const withIcon = (config: IconConfig) => component => {
     const prefix = config.prefix || component.config?.prefix || 'mtrl';
     const componentName = config.componentName || component.componentName || 'component';
     
-    // Clone the structure definition
-    const structureDefinition = JSON.parse(JSON.stringify(component.structureDefinition));
+    // 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 = structureDefinition.element.options.className || [];
+    const elementClasses = schema.element.options.className || [];
     const iconModifierClass = `${prefix}-${componentName}--icon`;
     
     if (Array.isArray(elementClasses)) {
@@ -78,10 +78,10 @@ export const withIcon = (config: IconConfig) => component => {
       }
     } else if (typeof elementClasses === 'string') {
       if (!elementClasses.includes(iconModifierClass)) {
-        structureDefinition.element.options.className = `${elementClasses} ${iconModifierClass}`.trim();
+        schema.element.options.className = `${elementClasses} ${iconModifierClass}`.trim();
       }
     } else {
-      structureDefinition.element.options.className = [iconModifierClass];
+      schema.element.options.className = [iconModifierClass];
     }
     
     // Create icon element definition with component-specific class
@@ -109,23 +109,23 @@ export const withIcon = (config: IconConfig) => component => {
     // Add icon directly to the main element's children
     if (position === 'start') {
       // Create new children object with icon first
-      const existingChildren = { ...structureDefinition.element.children };
-      structureDefinition.element.children = {
+      const existingChildren = { ...schema.element.children };
+      schema.element.children = {
         icon: iconDef,
         ...existingChildren
       };
     } else {
       // Add icon after existing children
-      structureDefinition.element.children.icon = iconDef;
+      schema.element.children.icon = iconDef;
     }
     
-    // Return component with updated structure definition
+    // Return component with updated schema
     return {
       ...component,
-      structureDefinition
+      schema
     };
   } catch (error) {
-    console.warn('Error enhancing structure with icon:', error);
+    console.warn('Error enhancing schema with icon:', error);
     return component;
   }
 };

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

@@ -1,11 +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';
-export { withStructure } from './structure';
 
 // Re-export interface types for better developer experience
 export type { IconConfig } from './icon';
-export type { LabelConfig } from './label';
+export type { LabelConfig } from './label';
+export type { LayoutConfig } from './layout';

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

@@ -39,27 +39,26 @@ export interface LabelConfig {
 }
 
 /**
- * Enhances structure definition with a label element
- * Unlike the traditional withLabel, this modifies the structure definition
+ * 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 structure definition
+ * @returns Component enhancer that adds label to schema
  * 
  * @example
  * ```ts
- * // Add label to a structure definition
+ * // Add label to a component schema
  * const component = pipe(
  *   createBase,
- *   withStructure(config),
+ *   withLayout(config),
  *   withLabel(config)
  * )(config);
  * ```
  */
 export const withLabel = (config: LabelConfig) => component => {
-  // If no label or missing structure definition, return unmodified
-
-  if (!config.label || !component.structureDefinition) {
+  // If no label or missing schema, return unmodified
+  if (!config.label || !component.schema) {
     return component;
   }
   
@@ -77,8 +76,8 @@ export const withLabel = (config: LabelConfig) => component => {
     const prefix = config.prefix || component.config?.prefix || 'mtrl';
     const componentName = config.componentName || component.componentName || 'component';
     
-    // Clone the structure definition
-    const structureDefinition = JSON.parse(JSON.stringify(component.structureDefinition));
+    // Clone the schema
+    const schema = JSON.parse(JSON.stringify(component.schema));
     
     // Determine position (default to 'start')
     const position = config.labelPosition || 'start';
@@ -89,7 +88,7 @@ export const withLabel = (config: LabelConfig) => component => {
     
     // Add required indicator if specified
     if (config.required) {
-      // For structure definition we need to define a child element
+      // For schema we need to define a child element
       labelChildren = {
         requiredIndicator: {
           name: 'requiredIndicator',
@@ -134,23 +133,23 @@ export const withLabel = (config: LabelConfig) => component => {
     // Add label to root element's children
     if (position === 'end' || position === 'bottom') {
       // Add at end of root element
-      structureDefinition.element.children.label = labelDef;
+      schema.element.children.label = labelDef;
     } else {
       // Add at beginning of root element (start/top)
-      const existingChildren = { ...structureDefinition.element.children };
-      structureDefinition.element.children = {
+      const existingChildren = { ...schema.element.children };
+      schema.element.children = {
         label: labelDef,
         ...existingChildren
       };
     }
     
-    // Return component with updated structure definition
+    // Return component with updated schema
     return {
       ...component,
-      structureDefinition
+      schema
     };
   } catch (error) {
-    console.warn('Error enhancing structure with label:', 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

@@ -6,10 +6,10 @@
  * 
  * The composition module provides features that work with the structure definition
  * mechanism. Unlike traditional features that directly modify the DOM, these
- * features modify a structure definition that is later used to create DOM elements.
+ * features modify a layout schema that is later used to create DOM elements.
  * 
  * This approach provides several advantages:
- * - Clearer separation between structure definition and DOM creation
+ * - Clearer separation between layout and DOM creation
  * - More predictable component creation process
  * - Better support for server-side rendering
  * - Enhanced testability
@@ -17,8 +17,8 @@
 
 // Export features
 export {
-  withStructure
-  withDom
+  withLayout,
+  withDom,
   withIcon,
   withLabel,
 } from './features';