mtrl 0.2.9 → 0.3.0

package/src/core/layout/object.ts

@@ -0,0 +1,124 @@
+// src/core/layout/object.ts
+/**
+ * @module core/layout
+ * @description Processor for object-based layout schemas
+ */
+
+import { createElement } from '../dom/create';
+import { Schema, LayoutResult, LayoutOptions } from './types';
+import { isComponent, createFragment, processClassNames } from './utils';
+import { createLayoutResult } from './result';
+import { createComponentInstance } from './processor';
+import { processArraySchema } from './array';
+
+/**
+ * Processes an object-based layout definition
+ * 
+ * @param schema - Object-based layout definition
+ * @param parentElement - Optional parent element to attach layout to
+ * @param options - Layout creation options
+ * @returns Layout result object
+ */
+export function processObjectSchema(
+  schema: Schema, 
+  parentElement: HTMLElement | null = null,
+  options: LayoutOptions = {}
+): LayoutResult {
+  const layout = {};
+  
+  // Get default creator function from options or use createElement
+  const defaultCreator = options.creator || createElement;
+
+  // Handle root element creation
+  if (schema.element && !parentElement) {
+    const elementDef = schema.element;
+    const createElementFn = elementDef.creator || defaultCreator;
+    
+    // Process class names based on prefix option
+    const elementOptions = elementDef.options || {};
+    const processedOptions = options.prefix !== false ? 
+      processClassNames(elementOptions) : 
+      { ...elementOptions };
+      
+    const rootComponent = createComponentInstance(createElementFn, processedOptions, options);
+    const rootElement = isComponent(rootComponent) ? rootComponent.element : rootComponent;
+    
+    layout.element = rootComponent;
+    if (elementDef.name) layout[elementDef.name] = rootComponent;
+    
+    // Process children
+    if (elementDef.children) {
+      const fragment = createFragment();
+      const childLayouts = [];
+      
+      for (const key in elementDef.children) {
+        const childResult = processObjectSchema(
+          { [key]: elementDef.children[key] }, 
+          fragment,
+          options
+        );
+        childLayouts.push(childResult.layout);
+      }
+      
+      rootElement.appendChild(fragment);
+      
+      // Merge child layouts
+      for (const childLayout of childLayouts) {
+        Object.assign(layout, childLayout);
+      }
+    }
+    
+    return createLayoutResult(layout);
+  }
+  
+  // Process normal schema elements
+  const fragment = parentElement ? createFragment() : null;
+  const childLayouts = [];
+  
+  for (const key in schema) {
+    const def = schema[key];
+    if (!def) continue;
+    
+    // Use appropriate creator
+    const elementCreator = def.creator || defaultCreator;
+    
+    // Process class names based on prefix option
+    const elementOptions = def.options || {};
+    const shouldApplyPrefix = 
+      'prefix' in elementOptions ? elementOptions.prefix : options.prefix !== false;
+      
+    const processedOptions = shouldApplyPrefix ? 
+      processClassNames(elementOptions) : 
+      { ...elementOptions };
+      
+    // Create element
+    const created = createComponentInstance(elementCreator, processedOptions, options);
+    
+    // Store in layout
+    layout[key] = created;
+    if (def.name && def.name !== key) layout[def.name] = created;
+    
+    // Handle DOM operations
+    const element = isComponent(created) ? created.element : created;
+    if (fragment) fragment.appendChild(element);
+    
+    // Process children
+    if (def.children) {
+      const childResult = processObjectSchema(def.children, element, options);
+      childLayouts.push(childResult.layout);
+    }
+  }
+  
+  // Append to parent
+  if (parentElement && fragment) {
+    const parentDom = isComponent(parentElement) ? parentElement.element : parentElement;
+    parentDom.appendChild(fragment);
+  }
+  
+  // Merge child layouts
+  for (const childLayout of childLayouts) {
+    Object.assign(layout, childLayout);
+  }
+  
+  return createLayoutResult(layout);
+}

package/src/core/layout/processor.ts

@@ -0,0 +1,58 @@
+// src/core/layout/processor.ts
+/**
+ * @module core/layout
+ * @description Lightweight processor for layout creation, optimized for bundle size
+ */
+
+import { Schema, LayoutResult, LayoutOptions } from './types';
+import { isComponent } from './utils';
+import { processArraySchema } from './array';
+import { processObjectSchema } from './object';
+import { isObject } from '../utils';
+
+/**
+ * Creates a component from a constructor or factory function
+ * 
+ * @param Component - Component constructor or factory function
+ * @param options - Component creation options 
+ * @param layoutOptions - Global layout options
+ * @returns Created component instance
+ */
+export function createComponentInstance(
+  Component: any, 
+  options: Record<string, any> = {}, 
+  layoutOptions: LayoutOptions = {}
+): any {
+  // Check if Component is a class constructor
+  const isClass = typeof Component === 'function' && 
+                 Component.prototype && 
+                 Component.prototype.constructor === Component &&
+                 // Exclude native constructors like Object, Array, etc.
+                 Object.getPrototypeOf(Component) !== Function.prototype;
+
+  // Use 'new' for class constructors, call directly for function factories
+  return isClass
+    ? new Component(options)
+    : Component(options);
+}
+
+/**
+ * Processes any type of layout definition (array or object)
+ * This is the main entry point for schema processing
+ * 
+ * @param schema - Layout schema to process
+ * @param parentElement - Parent element to attach to
+ * @param level - Current nesting level 
+ * @param options - Layout creation options
+ * @returns Layout result object
+ */
+export function processSchema(
+  schema: any, 
+  parentElement: HTMLElement | null = null, 
+  level: number = 0,
+  options: LayoutOptions = {}
+): LayoutResult {
+  return Array.isArray(schema)
+    ? processArraySchema(schema, parentElement, level, options)
+    : processObjectSchema(schema, parentElement, options);
+}

package/src/core/layout/result.ts

@@ -0,0 +1,85 @@
+// src/core/layout/result.ts
+/**
+ * @module core/layout
+ * @description Simplified layout result creation and management
+ */
+
+import { LayoutResult } from './types';
+import { isComponent, flattenLayout } from './utils';
+
+/**
+ * Creates a result object with the layout and utility functions
+ * Simplified API for better usability and reduced overhead
+ * 
+ * @param layout - The raw layout object
+ * @returns Result object with layout and utility functions
+ */
+export function createLayoutResult(layout: Record<string, any>): LayoutResult {
+  // Pre-compute flattened layout for better performance
+  const flattenedComponents = flattenLayout(layout);
+  
+  // Create the result object with layout correctly exposed
+  const result: LayoutResult = {
+    // Raw layout object
+    layout,
+    
+    // Root element reference for convenience
+    element: layout.element,
+    
+    // Flattened component map
+    component: flattenedComponents,
+
+    /**
+     * Gets a component by name
+     * 
+     * @param name - Component name
+     * @returns Component if found, null otherwise
+     */
+    get(name: string): any {
+      return layout[name] ?? null;
+    },
+    
+    /**
+     * Gets all components in a flattened map
+     * 
+     * @returns Object with all components
+     */
+    getAll(): Record<string, any> {
+      return flattenedComponents;
+    },
+    
+    /**
+     * Destroys the layout, cleaning up all components
+     */
+    destroy(): void {
+      // Handle root element
+      const root = layout.element;
+      if (root) {
+        // Component with destroy method
+        if (isComponent(root) && typeof root.destroy === 'function') {
+          root.destroy();
+        } 
+        // Component without destroy method
+        else if (isComponent(root) && root.element?.parentNode) {
+          root.element.parentNode.removeChild(root.element);
+        }
+        // Direct DOM element
+        else if (root instanceof HTMLElement && root.parentNode) {
+          root.parentNode.removeChild(root);
+        }
+      }
+      
+      // Clean up other components that have a destroy method
+      for (const key in layout) {
+        if (key === 'element') continue;
+        
+        const item = layout[key];
+        if (isComponent(item) && typeof item.destroy === 'function') {
+          item.destroy();
+        }
+      }
+    }
+  };
+  
+  return result;
+}

package/src/core/layout/types.ts

@@ -0,0 +1,125 @@
+// src/core/layout/types.ts
+/**
+ * @module core/layout
+ * @description Optimized type definitions for layout creation system
+ */
+
+/**
+ * Interface for component-like objects
+ */
+export interface ComponentLike {
+  /**
+   * DOM element reference
+   */
+  element: HTMLElement;
+  
+  /**
+   * Optional method to clean up resources
+   */
+  destroy?: () => void;
+  
+  /**
+   * Allow additional properties
+   */
+  [key: string]: any;
+}
+
+/**
+ * Definition for a single element in the layout
+ */
+export interface ElementDefinition {
+  /**
+   * Optional name to reference the element
+   */
+  name?: string;
+  
+  /**
+   * Creator function that produces an HTMLElement or ComponentLike
+   */
+  creator?: (options?: Record<string, any>) => HTMLElement | ComponentLike;
+  
+  /**
+   * Options to pass to the creator function
+   */
+  options?: Record<string, any>;
+  
+  /**
+   * Child elements to create and attach
+   */
+  children?: Record<string, ElementDefinition>;
+}
+
+/**
+ * Schema for layout creation
+ */
+export interface Schema {
+  /**
+   * Root element definition
+   */
+  element?: ElementDefinition;
+  
+  /**
+   * Additional elements
+   */
+  [key: string]: ElementDefinition | undefined;
+}
+
+/**
+ * Options for layout creation
+ */
+export interface LayoutOptions {
+  /**
+   * Default creator function to use if not specified in schema
+   */
+  creator?: (options?: Record<string, any>) => HTMLElement | ComponentLike;
+  
+  /**
+   * Whether to apply CSS class prefix
+   * @default true
+   */
+  prefix?: boolean;
+
+  /**
+   * Additional options
+   */
+  [key: string]: any;
+}
+
+/**
+ * Result object returned after creating a layout
+ * Simplified API with essential methods
+ */
+export interface LayoutResult {
+  /**
+   * The raw layout object with all components
+   */
+  layout: Record<string, any>;
+  
+  /**
+   * Reference to the root element for convenience
+   */
+  element: HTMLElement | ComponentLike;
+  
+  /**
+   * Flattened component map
+   */
+  component: Record<string, any>;
+  
+  /**
+   * Gets a component by name
+   * @param name - Component name
+   * @returns Component if found, null otherwise
+   */
+  get(name: string): any;
+  
+  /**
+   * Gets all components in a flattened map
+   * @returns Object with all components
+   */
+  getAll(): Record<string, any>;
+  
+  /**
+   * Destroys the layout, cleaning up all components
+   */
+  destroy(): void;
+}

package/src/core/layout/utils.ts

@@ -0,0 +1,136 @@
+// src/core/layout/utils.ts
+/**
+ * @module core/layout
+ * @description Optimized utility functions for layout creation
+ */
+
+import { PREFIX } from '../config';
+import { ComponentLike } from './types';
+
+/**
+ * Checks if a value is a component object (has an element property)
+ * Optimized fast path check by only validating that element property exists
+ * 
+ * @param value - Value to check
+ * @returns True if the value is a component-like object
+ */
+export function isComponent(value: any): value is ComponentLike {
+  return value && 
+         typeof value === 'object' && 
+         'element' in value;
+}
+
+/**
+ * Creates a document fragment for faster DOM operations
+ * 
+ * @returns New DocumentFragment
+ */
+export function createFragment(): DocumentFragment {
+  return document.createDocumentFragment();
+}
+
+/**
+ * Processes className options to add prefix if needed
+ * Supports BEM naming conventions when enabled
+ * 
+ * @param options - Element options
+ * @param skipPrefix - Whether to skip adding prefixes
+ * @param useBEM - Whether to respect BEM naming conventions
+ * @returns Updated options with prefixed classNames
+ */
+export function processClassNames(
+  options: Record<string, any>, 
+  skipPrefix: boolean = false,
+  useBEM: boolean = false
+): Record<string, any> {
+  // Fast path - if no options or skipping prefix, return as is
+  if (!options || skipPrefix) return { ...options };
+  
+  // Clone options to avoid mutating the original
+  const processed = { ...options };
+  
+  /**
+   * Processes a single class name with optional BEM handling
+   * 
+   * @param cls - Class name to process
+   * @returns Processed class name with prefix
+   */
+  const processClass = (cls: string): string => {
+    // Already prefixed - leave it as is
+    if (cls.startsWith(`${PREFIX}-`)) {
+      return cls;
+    }
+    
+    if (useBEM) {
+      // For BEM classes (with __ or --), only prefix the block part
+      if (cls.includes('__')) {
+        // This is a BEM element, prefix only the block part
+        const [block, element] = cls.split('__');
+        return `${PREFIX}-${block}__${element}`;
+      } else if (cls.includes('--')) {
+        // This is a BEM modifier, prefix only the block part
+        const [block, modifier] = cls.split('--');
+        return `${PREFIX}-${block}--${modifier}`;
+      }
+    }
+    
+    // Standard case - prefix the entire class name
+    return `${PREFIX}-${cls}`;
+  };
+  
+  /**
+   * Process a class property (either 'class' or 'className')
+   * 
+   * @param prop - Property name to process
+   */
+  const processProperty = (prop: string): void => {
+    if (!processed[prop]) return;
+    
+    // Handle string class names
+    if (typeof processed[prop] === 'string') {
+      processed[prop] = processed[prop]
+        .split(' ')
+        .map(cls => cls ? processClass(cls) : '')
+        .filter(Boolean)
+        .join(' ');
+    }
+    // Handle array class names
+    else if (Array.isArray(processed[prop])) {
+      processed[prop] = processed[prop]
+        .map(cls => typeof cls === 'string' ? processClass(cls) : cls)
+        .filter(Boolean)
+        .join(' ');
+    }
+  };
+  
+  // Process both possible class properties for compatibility
+  processProperty('class');
+  processProperty('className');
+  
+  return processed;
+}
+
+/**
+ * Flattens a nested layout into a simple object with element and component references
+ * Optimized by using a direct property access loop and early exits
+ * 
+ * @param layout - Layout object
+ * @returns Flattened layout with all elements and components
+ */
+export function flattenLayout(layout: Record<string, any>): Record<string, any> {
+  const flattened: Record<string, any> = {};
+  
+  for (const key in layout) {
+    const value = layout[key];
+    
+    // Only include components, elements, and non-functions
+    // Fast path with fewer type checks
+    if (value && 
+        typeof value !== 'function' && 
+        (value instanceof HTMLElement || 'element' in value)) {
+      flattened[key] = value;
+    }
+  }
+  
+  return flattened;
+}

package/src/styles/abstract/_variables.scss

@@ -207,6 +207,34 @@ $button: (
   'transition-easing': map.get($motion, 'easing-standard')
 ) !default;
 
+
+// Define spacing scale (this might already exist, if not, add it)
+$spacing-scale: (
+  '0': 0,
+  '1': 4px,
+  '2': 8px,
+  '3': 12px,
+  '4': 16px,
+  '5': 20px,
+  '6': 24px,
+  '8': 32px,
+  '10': 40px,
+  '12': 48px,
+  '14': 56px,
+  '16': 64px,
+  '20': 80px,
+  '24': 96px,
+  '32': 128px
+);
+
+// Add spacing function
+@function spacing($key) {
+  @if not map.has-key($spacing-scale, $key) {
+    @error 'Spacing key "#{$key}" not found in spacing scale.';
+  }
+  @return map.get($spacing-scale, $key);
+}
+
 // Helper functions for easier token access
 @function state($key) {
   @return map.get($state, $key);