mtrl 0.2.8 → 0.2.9

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

@@ -0,0 +1,156 @@
+// 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 structure definition with a label element
+ * Unlike the traditional withLabel, this modifies the structure definition
+ * without creating actual DOM elements.
+ * 
+ * @param config Configuration containing label information
+ * @returns Component enhancer that adds label to structure definition
+ * 
+ * @example
+ * ```ts
+ * // Add label to a structure definition
+ * const component = pipe(
+ *   createBase,
+ *   withStructure(config),
+ *   withLabel(config)
+ * )(config);
+ * ```
+ */
+export const withLabel = (config: LabelConfig) => component => {
+  // If no label or missing structure definition, return unmodified
+
+  if (!config.label || !component.structureDefinition) {
+    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 structure definition
+    const structureDefinition = JSON.parse(JSON.stringify(component.structureDefinition));
+    
+    // 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 structure definition 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
+      structureDefinition.element.children.label = labelDef;
+    } else {
+      // Add at beginning of root element (start/top)
+      const existingChildren = { ...structureDefinition.element.children };
+      structureDefinition.element.children = {
+        label: labelDef,
+        ...existingChildren
+      };
+    }
+    
+    // Return component with updated structure definition
+    return {
+      ...component,
+      structureDefinition
+    };
+  } catch (error) {
+    console.warn('Error enhancing structure with label:', error);
+    return component;
+  }
+};

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

@@ -0,0 +1,22 @@
+// src/core/composition/features/structure.ts
+
+/**
+ * Adds structure definition to component without creating DOM
+ * Now uses the structure from the baseConfig
+ * 
+ * @param configuration
+ * @returns Component enhancer with structure definition
+ */
+export const withStructure = (config: SliderConfig) => component => {
+  // Use the structure definition from the config
+  if (!config.structureDefinition) {
+    console.warn('No structure definition found in slider config');
+    return component;
+  }
+  
+  // Return enhanced component with structure definition
+  return {
+    ...component,
+    structureDefinition: config.structureDefinition
+  };
+};

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 structure definition that is later used to create DOM elements.
+ * 
+ * This approach provides several advantages:
+ * - Clearer separation between structure definition and DOM creation
+ * - More predictable component creation process
+ * - Better support for server-side rendering
+ * - Enhanced testability
+ */
+
+// Export features
+export {
+  withStructure
+  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

package/src/core/structure.ts

@@ -0,0 +1,288 @@
+// src/core/structure.ts
+import { createElement } from './dom/create';
+
+/**
+ * Type definitions for structure creation
+ */
+export interface ComponentLike {
+  element: HTMLElement;
+  destroy?: () => void;
+  [key: string]: any;
+}
+
+export interface ElementDefinition {
+  name?: string;
+  creator?: Function;
+  options?: Record<string, any>;
+  children?: Record<string, ElementDefinition>;
+}
+
+export interface StructureDefinition {
+  element?: ElementDefinition;
+  [key: string]: ElementDefinition | any;
+}
+
+/**
+ * Structure result interface with separated structure and utility functions
+ */
+export interface StructureResult {
+  // The raw structure object with all components
+  structure: Record<string, any>;
+  
+  // Reference to the root element for convenience 
+  element: HTMLElement | ComponentLike;
+  
+  // Utility functions
+  get: (name: string) => any;
+  getAll: () => Record<string, any>;
+  destroy: () => void;
+}
+
+/**
+ * Checks if a value is a component object (has an element property)
+ * Uses a faster property check before the instanceof check
+ * @param value Value to check
+ * @returns True if the value is a component-like object
+ */
+function isComponentLike(value: any): value is ComponentLike {
+  return value && 
+         typeof value === 'object' && 
+         'element' in value && 
+         value.element instanceof HTMLElement;
+}
+
+/**
+ * Creates a document fragment for faster DOM operations when appending multiple children
+ * @returns DocumentFragment
+ */
+function createFragment(): DocumentFragment {
+  return document.createDocumentFragment();
+}
+
+/**
+ * Creates a DOM or component structure based on a structure definition
+ * @param definition Structure definition object
+ * @param parentElement Optional parent element to attach structure to
+ * @returns Object containing the structure and utility functions
+ */
+export function createStructure(
+  definition: StructureDefinition, 
+  parentElement: HTMLElement | null = null
+): StructureResult {
+  // Use object literal instead of empty object for faster property access
+  const structure: Record<string, any> = Object.create(null);
+  
+  // Special case for root component creation
+  if (definition.element && !parentElement) {
+    const elementDef = definition.element;
+    const createElementFn = elementDef.creator || createElement;
+    const rootComponent = createElementFn(elementDef.options);
+    const rootElement = isComponentLike(rootComponent) ? rootComponent.element : rootComponent;
+    
+    structure.element = rootComponent;
+    
+    if (elementDef.name) {
+      structure[elementDef.name] = rootComponent;
+    }
+    
+    if (elementDef.children) {
+      // Use fragment for better performance when appending multiple children
+      const fragment = createFragment();
+      let childKeys = Object.keys(elementDef.children);
+      
+      // Process all children first and collect their structures
+      const childStructures = new Array(childKeys.length);
+      
+      for (let i = 0; i < childKeys.length; i++) {
+        const key = childKeys[i];
+        const childDef = elementDef.children[key];
+        
+        // Create child structure and attach to fragment temporarily
+        const childResult = createStructure({ [key]: childDef }, fragment);
+        childStructures[i] = childResult.structure;
+      }
+      
+      // Append fragment to root element (single DOM operation)
+      rootElement.appendChild(fragment);
+      
+      // Now merge all child structures into the main structure
+      for (let i = 0; i < childStructures.length; i++) {
+        Object.assign(structure, childStructures[i]);
+      }
+    }
+    
+    // Create and return the result object with utility functions
+    return createStructureResult(structure);
+  }
+  
+  // Use fragment if we have multiple elements to append to the parent
+  const fragment = parentElement ? createFragment() : null;
+  const keys = Object.keys(definition);
+  const keyLength = keys.length;
+  
+  // Pre-allocate arrays for better performance
+  const elements = new Array(keyLength);
+  const childStructuresToMerge = [];
+  
+  // First pass: create all elements
+  for (let i = 0; i < keyLength; i++) {
+    const key = keys[i];
+    const def = definition[key];
+    
+    // Skip if no definition
+    if (!def) {
+      elements[i] = null;
+      continue;
+    }
+    
+    // Create the element
+    const createElementFn = def.creator || createElement;
+    const created = createElementFn(def.options);
+    elements[i] = created;
+    
+    // Add to structure
+    structure[key] = created;
+    
+    // Add element to structure with its name if different from key
+    if (def.name && def.name !== key) {
+      structure[def.name] = created;
+    }
+  }
+  
+  // Second pass: handle children and append to parent
+  for (let i = 0; i < keyLength; i++) {
+    const key = keys[i];
+    const def = definition[key];
+    const created = elements[i];
+    
+    if (!created || !def) continue;
+    
+    // Get the actual DOM element
+    const element = isComponentLike(created) ? created.element : created;
+    
+    // Append to fragment
+    if (fragment) {
+      fragment.appendChild(element);
+    }
+    
+    // Process children recursively
+    if (def.children) {
+      const childResult = createStructure(def.children, element);
+      childStructuresToMerge.push(childResult.structure);
+    }
+  }
+  
+  // Append fragment to parent (single DOM operation)
+  if (parentElement && fragment) {
+    parentElement.appendChild(fragment);
+  }
+  
+  // Merge all child structures at once
+  for (let i = 0; i < childStructuresToMerge.length; i++) {
+    Object.assign(structure, childStructuresToMerge[i]);
+  }
+  
+  // Create and return the result object with utility functions
+  return createStructureResult(structure);
+}
+
+/**
+ * Creates a result object with the structure and utility functions
+ * @param structure The raw structure object
+ * @returns Result object with structure and utility functions
+ */
+function createStructureResult(structure: Record<string, any>): StructureResult {
+  return {
+    // Raw structure object
+    structure,
+    
+    // Root element reference for convenience
+    element: structure.element,
+    
+    /**
+     * Gets a component by name
+     * @param name Component name
+     * @returns Component if found, null otherwise
+     */
+    get: (name: string): any => {
+      return structure[name] || null;
+    },
+    
+    /**
+     * Gets all components in a flattened map
+     * @returns Object with all components
+     */
+    getAll: (): Record<string, any> => {
+      return flattenStructure(structure);
+    },
+    
+    /**
+     * Destroys the structure, cleaning up all components
+     */
+    destroy: (): void => {
+      // Clean up the root element if it exists
+      if (structure.element) {
+        // If element is a component with a destroy method, call it
+        if (isComponentLike(structure.element) && typeof structure.element.destroy === 'function') {
+          structure.element.destroy();
+        } 
+        // Otherwise, if it's a DOM element or component, remove it from the DOM
+        else if (isComponentLike(structure.element) && structure.element.element.parentNode) {
+          structure.element.element.parentNode.removeChild(structure.element.element);
+        }
+        else if (structure.element instanceof HTMLElement && structure.element.parentNode) {
+          structure.element.parentNode.removeChild(structure.element);
+        }
+      }
+      
+      // Clean up all other components in the structure
+      Object.keys(structure).forEach(key => {
+        if (key === 'element') {
+          return; // Already handled element
+        }
+        
+        const item = structure[key];
+        
+        // Handle component objects
+        if (isComponentLike(item) && typeof item.destroy === 'function') {
+          item.destroy();
+        }
+        // Handle DOM elements
+        else if (item instanceof HTMLElement && item.parentNode) {
+          item.parentNode.removeChild(item);
+        }
+      });
+    }
+  };
+}
+
+/**
+ * Flattens a nested structure into a simple object with element and component references
+ * Optimized version that avoids unnecessary type checks where possible
+ * @param structure Structure object
+ * @returns Flattened structure with all elements and components
+ */
+export function flattenStructure(structure: Record<string, any>): Record<string, any> {
+  const flattened: Record<string, any> = Object.create(null);
+  const keys = Object.keys(structure);
+  
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const value = structure[key];
+    
+    // Fast path for common cases
+    if (value instanceof HTMLElement || 
+        (value && typeof value === 'object' && 'element' in value)) {
+      flattened[key] = value;
+      continue;
+    }
+    
+    // Skip functions and other non-element/component objects
+    if (typeof value !== 'function' && 
+        (value instanceof Element || isComponentLike(value))) {
+      flattened[key] = value;
+    }
+  }
+  
+  return flattened;
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export { default as createDialog } from './components/dialog'
 export { default as createDivider } from './components/divider'
 export { default as createMenu } from './components/menu'
 export { default as createNavigation } from './components/navigation'
+export { default as createNavigationSystem } from './components/navigation'
 export { default as createProgress } from './components/progress'
 export { default as createRadios } from './components/radios'
 export { default as createSearch } from './components/search'