mtrl 0.3.3 → 0.3.6

package/src/core/layout/array.ts

@@ -98,10 +98,9 @@ export function processArraySchema(
         itemOptions = {};
       }
       
-      // We should NOT automatically set the tag to match the name
-      // If tag is not provided in options, a default like 'div' should be used
+      // Default to div if no tag is specified
       if (creator === createElement && !('tag' in itemOptions)) {
-        itemOptions.tag = 'div'; // Default to div if no tag is specified
+        itemOptions.tag = 'div';
       }
     }
     // Case 3: Item is an object (options for default creator with no name)
@@ -178,4 +177,4 @@ export function processArraySchema(
 
   layout.components = components;
   return createLayoutResult(layout);
-}
+}

package/src/core/layout/config.ts

@@ -0,0 +1,193 @@
+// src/core/layout/config.ts
+/**
+ * @module core/layout
+ * @description Layout configuration utilities
+ */
+
+import { addClass, removeClass, hasClass } from '../dom/classes';
+
+/**
+ * Helper function to clean up previous layout classes from an element
+ * 
+ * @param element - Element to clean layout classes from
+ */
+export function cleanupLayoutClasses(element: HTMLElement): void {
+  if (!element) return;
+  
+  // Get all classes from the element
+  const classList = Array.from(element.classList);
+  
+  // Find and remove layout-related classes
+  const layoutClasses = classList.filter(cls => 
+    cls.startsWith('layout--') || 
+    cls.includes('-layout--')
+  );
+  
+  // Remove each layout class
+  layoutClasses.forEach(cls => {
+    element.classList.remove(cls);
+  });
+}
+
+/**
+ * Helper function to get the layout type from element classes
+ * 
+ * @param element - Element to check
+ * @returns Layout type if found, empty string otherwise
+ */
+export function getLayoutType(element: HTMLElement): string {
+  return hasClass(element, 'layout--stack') ? 'stack' : 
+         hasClass(element, 'layout--row') ? 'row' : 
+         hasClass(element, 'layout--grid') ? 'grid' : '';
+}
+
+/**
+ * Applies layout classes based on the layout configuration
+ * 
+ * @param element - Element to apply layout classes to
+ * @param layoutConfig - Layout configuration
+ * @param cleanupFirst - Whether to clean up previous layout classes first
+ */
+export function applyLayoutClasses(
+  element: HTMLElement, 
+  layoutConfig: any,
+  cleanupFirst: boolean = true
+): void {
+  if (!element || !layoutConfig) return;
+  
+  // First remove any existing layout classes to avoid accumulation
+  if (cleanupFirst) {
+    cleanupLayoutClasses(element);
+  }
+  
+  // Apply base layout type
+  if (layoutConfig.type) {
+    addClass(element, `layout--${layoutConfig.type}`);
+  }
+  
+  // Apply common layout properties
+  if (layoutConfig.gap !== undefined) {
+    // Get current layout type for prefixed gap class
+    const layoutType = layoutConfig.type || getLayoutType(element);
+       
+    if (layoutType) {
+      // Add the new gap class
+      addClass(element, `layout--${layoutType}-gap-${layoutConfig.gap}`);
+    }
+  }
+  
+  // Apply alignment properties
+  if (layoutConfig.align) {
+    const layoutType = layoutConfig.type || getLayoutType(element);
+       
+    if (layoutType) {
+      addClass(element, `layout--${layoutType}-${layoutConfig.align}`);
+    }
+  }
+  
+  // Apply justification
+  if (layoutConfig.justify) {
+    const layoutType = layoutConfig.type || getLayoutType(element);
+       
+    if (layoutType) {
+      addClass(element, `layout--${layoutType}-justify-${layoutConfig.justify}`);
+    }
+  }
+  
+  // Apply grid-specific properties
+  if (layoutConfig.type === 'grid' || getLayoutType(element) === 'grid') {
+    // Grid columns
+    if (typeof layoutConfig.columns === 'number') {
+      addClass(element, `layout--grid-cols-${layoutConfig.columns}`);
+    } else if (layoutConfig.columns === 'auto-fill') {
+      addClass(element, 'layout--grid-fill');
+    } else if (layoutConfig.columns === 'auto-fit') {
+      addClass(element, 'layout--grid-cols-auto-fit');
+    }
+    
+    // Other grid properties
+    if (layoutConfig.dense) {
+      addClass(element, 'layout--grid-dense');
+    }
+    
+    if (layoutConfig.autoHeight) {
+      addClass(element, 'layout--grid-auto-height');
+    }
+  }
+  
+  // Apply row-specific properties
+  if (layoutConfig.type === 'row' || getLayoutType(element) === 'row') {
+    // Wrap behavior
+    if (layoutConfig.wrap === false || layoutConfig.wrap === 'nowrap') {
+      addClass(element, 'layout--row-nowrap');
+    } else if (layoutConfig.wrap === 'reverse') {
+      addClass(element, 'layout--row-wrap-reverse');
+    }
+    
+    // Mobile responsiveness
+    if (layoutConfig.mobileStack) {
+      addClass(element, 'layout--row-mobile-stack');
+    }
+    
+    if (layoutConfig.mobileScroll) {
+      addClass(element, 'layout--row-mobile-scroll');
+    }
+  }
+  
+  // No masonry, split or sidebar specific properties anymore
+  
+  // Add any additional custom classes
+  if (layoutConfig.class) {
+    layoutConfig.class.split(' ').filter(Boolean).forEach(cls => {
+      // Don't prefix these classes as they're user-defined
+      element.classList.add(cls);
+    });
+  }
+}
+
+/**
+ * Applies layout item classes based on the configuration
+ * 
+ * @param element - Element to apply layout item classes to
+ * @param itemConfig - Layout item configuration
+ */
+export function applyLayoutItemClasses(element: HTMLElement, itemConfig: any): void {
+  if (!element || !itemConfig) return;
+  
+  // Add the base layout item class
+  addClass(element, 'layout__item');
+  
+  // Add width classes
+  if (itemConfig.width && itemConfig.width >= 1 && itemConfig.width <= 12) {
+    addClass(element, `layout__item--${itemConfig.width}`);
+  }
+  
+  // Add responsive classes
+  if (itemConfig.sm) addClass(element, `layout__item--sm-${itemConfig.sm}`);
+  if (itemConfig.md) addClass(element, `layout__item--md-${itemConfig.md}`);
+  if (itemConfig.lg) addClass(element, `layout__item--lg-${itemConfig.lg}`);
+  if (itemConfig.xl) addClass(element, `layout__item--xl-${itemConfig.xl}`);
+  
+  // Add grid span classes
+  if (itemConfig.span) addClass(element, `layout__item--span-${itemConfig.span}`);
+  if (itemConfig.rowSpan) addClass(element, `layout__item--row-span-${itemConfig.rowSpan}`);
+  
+  // Add ordering
+  if (itemConfig.order) {
+    if (typeof itemConfig.order === 'number') {
+      addClass(element, `layout__item--order-${itemConfig.order}`);
+    } else {
+      addClass(element, `layout__item--order-${itemConfig.order}`);
+    }
+  }
+  
+  // Add alignment
+  if (itemConfig.align) {
+    addClass(element, `layout__item--self-${itemConfig.align}`);
+  }
+  
+  // Add auto class
+  if (itemConfig.auto) {
+    addClass(element, 'layout__item--auto');
+  }
+}

package/src/core/layout/create.ts

@@ -1,7 +1,7 @@
 // src/core/layout/create.ts
 /**
  * @module core/layout
- * @description Main layout creation functionality with optimized DOM operations
+ * @description Main layout creation functionality
  */
 
 import { Schema, LayoutResult, LayoutOptions } from './types';
@@ -10,7 +10,6 @@ import { createLayoutResult } from './result';
 
 /**
  * Creates a DOM or component layout based on a layout definition
- * Uses batched DOM operations for better performance
  * 
  * @param schema - Layout definition (array-based, object-based, or HTML string)
  * @param parentElement - Optional parent element to attach layout to

package/src/core/layout/index.ts

@@ -1,7 +1,7 @@
 // src/core/layout/index.ts
 /**
  * @module core/layout
- * @description Optimized layout creation system with simplified API
+ * @description Layout creation system with simplified API
  */
 
 // Export essential types
@@ -10,7 +10,9 @@ export type {
   ElementDefinition, 
   Schema, 
   LayoutResult,
-  LayoutOptions 
+  LayoutOptions,
+  LayoutConfig,
+  LayoutItemConfig
 } from './types';
 
 // Export utility functions
@@ -21,6 +23,14 @@ export { createLayout } from './create';
 export { createLayoutResult } from './result';
 export { processSchema, createComponentInstance } from './processor';
 
+// Export configuration utilities
+export { 
+  applyLayoutClasses, 
+  applyLayoutItemClasses, 
+  getLayoutType,
+  cleanupLayoutClasses
+} from './config';
+
 // Default export for backward compatibility and simpler usage
 import { createLayout } from './create';
 export default createLayout;

package/src/core/layout/object.ts

@@ -8,8 +8,7 @@ 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';
+import { createComponentInstance } from './processor'; 
 
 /**
  * Processes an object-based layout definition
@@ -121,4 +120,4 @@ export function processObjectSchema(
   }
   
   return createLayoutResult(layout);
-}
+}

package/src/core/layout/processor.ts

@@ -1,7 +1,7 @@
 // src/core/layout/processor.ts
 /**
  * @module core/layout
- * @description Lightweight processor for layout creation, optimized for bundle size
+ * @description Processor for layout creation
  */
 
 import { Schema, LayoutResult, LayoutOptions } from './types';
@@ -9,6 +9,7 @@ import { isComponent } from './utils';
 import { processArraySchema } from './array';
 import { processObjectSchema } from './object';
 import { isObject } from '../utils';
+import { applyLayoutClasses, applyLayoutItemClasses } from './config';
 
 /**
  * Creates a component from a constructor or factory function
@@ -23,22 +24,55 @@ export function createComponentInstance(
   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;
+  try {
+    // Save layout and layoutItem configs before creating component
+    const layoutConfig = options.layout;
+    const layoutItemConfig = options.layoutItem;
+    
+    // Remove layout and layoutItem from options to prevent them becoming attributes
+    const cleanOptions = { ...options };
+    delete cleanOptions.layout;
+    delete cleanOptions.layoutItem;
+    
+    // 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);
+    // Create the component with clean options
+    const component = isClass
+      ? new Component(cleanOptions)
+      : Component(cleanOptions);
+      
+    // Apply layout configuration to the created component
+    if (component) {
+      // Get the actual DOM element
+      const element = component.element || (component instanceof HTMLElement ? component : null);
+      if (element) {
+        // Apply layout classes if layout config exists
+        if (layoutConfig) {
+          applyLayoutClasses(element, layoutConfig);
+        }
+        
+        // Apply layout item classes if layoutItem config exists
+        if (layoutItemConfig) {
+          applyLayoutItemClasses(element, layoutItemConfig);
+        }
+      }
+    }
+    
+    return component;
+  } catch (error) {
+    console.error('Error creating component instance:', error);
+    // Return a basic element as fallback
+    return document.createElement('div');
+  }
 }
 
 /**
  * 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
@@ -52,6 +86,20 @@ export function processSchema(
   level: number = 0,
   options: LayoutOptions = {}
 ): LayoutResult {
+  // Validate input to provide helpful error messages
+  if (!schema) {
+    console.warn('Empty schema provided to layout processor');
+    return {
+      layout: {},
+      element: document.createElement('div'),
+      component: {},
+      get: () => null,
+      getAll: () => ({}),
+      destroy: () => {}
+    };
+  }
+  
+  // Process based on schema type
   return Array.isArray(schema)
     ? processArraySchema(schema, parentElement, level, options)
     : processObjectSchema(schema, parentElement, options);

package/src/core/layout/result.ts

@@ -1,7 +1,7 @@
 // src/core/layout/result.ts
 /**
  * @module core/layout
- * @description Simplified layout result creation and management
+ * @description Layout result creation and management
  */
 
 import { LayoutResult } from './types';
@@ -9,7 +9,6 @@ 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

package/src/core/layout/types.ts

@@ -1,51 +1,124 @@
 // src/core/layout/types.ts
 /**
  * @module core/layout
- * @description Optimized type definitions for layout creation system
+ * @description Type definitions for layout creation system
  */
 
+/**
+ * Layout configuration options
+ */
+export interface LayoutConfig {
+  /** Base layout type */
+  type?: 'stack' | 'row' | 'grid' | string;
+  
+  /** Spacing between elements */
+  gap?: number | string;
+  
+  /** Additional CSS classes */
+  class?: string;
+  
+  /** Alignment of items along the cross axis */
+  align?: 'start' | 'center' | 'end' | 'stretch';
+  
+  /** Alignment of items along the main axis */
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+  
+  /** Whether and how items should wrap */
+  wrap?: boolean | 'reverse' | 'nowrap';
+  
+  /** Whether row items should stack vertically on mobile */
+  mobileStack?: boolean;
+  
+  /** Whether row items should scroll horizontally on mobile */
+  mobileScroll?: boolean;
+  
+  /** Number of columns or automatic sizing method */
+  columns?: number | 'auto-fit' | 'auto-fill';
+  
+  /** Minimum item width for grid layouts */
+  minWidth?: string | number;
+  
+  /** Whether to use dense packing algorithm for grid */
+  dense?: boolean;
+  
+  /** Whether grid items should adjust height automatically */
+  autoHeight?: boolean;
+}
+
+/**
+ * Configuration for individual layout items
+ */
+export interface LayoutItemConfig {
+  /** Column width in a 12-column grid */
+  width?: number;
+  
+  /** Width on small screens */
+  sm?: number;
+  
+  /** Width on medium screens */
+  md?: number;
+  
+  /** Width on large screens */
+  lg?: number;
+  
+  /** Width on extra-large screens */
+  xl?: number;
+  
+  /** Number of grid columns to span */
+  span?: number;
+  
+  /** Number of grid rows to span */
+  rowSpan?: number;
+  
+  /** Display order */
+  order?: number | 'first' | 'last';
+  
+  /** Self-alignment within container */
+  align?: 'start' | 'center' | 'end' | 'stretch';
+  
+  /** Whether item should automatically size */
+  auto?: boolean;
+}
+
 /**
  * Interface for component-like objects
  */
 export interface ComponentLike {
-  /**
-   * DOM element reference
-   */
+  /** DOM element reference */
   element: HTMLElement;
   
-  /**
-   * Optional method to clean up resources
-   */
+  /** Optional method to clean up resources */
   destroy?: () => void;
   
-  /**
-   * Allow additional properties
-   */
+  /** Allow additional properties */
   [key: string]: any;
 }
 
+/**
+ * Extended options for element creation
+ */
+export interface ElementOptions extends Record<string, any> {
+  /** Layout configuration for the element */
+  layout?: LayoutConfig;
+  
+  /** Layout item configuration */
+  layoutItem?: LayoutItemConfig;
+}
+
 /**
  * Definition for a single element in the layout
  */
 export interface ElementDefinition {
-  /**
-   * Optional name to reference the element
-   */
+  /** Optional name to reference the element */
   name?: string;
   
-  /**
-   * Creator function that produces an HTMLElement or ComponentLike
-   */
+  /** 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>;
+  /** Options to pass to the creator function */
+  options?: ElementOptions;
   
-  /**
-   * Child elements to create and attach
-   */
+  /** Child elements to create and attach */
   children?: Record<string, ElementDefinition>;
 }
 
@@ -53,14 +126,10 @@ export interface ElementDefinition {
  * Schema for layout creation
  */
 export interface Schema {
-  /**
-   * Root element definition
-   */
+  /** Root element definition */
   element?: ElementDefinition;
   
-  /**
-   * Additional elements
-   */
+  /** Additional elements */
   [key: string]: ElementDefinition | undefined;
 }
 
@@ -68,41 +137,27 @@ export interface Schema {
  * Options for layout creation
  */
 export interface LayoutOptions {
-  /**
-   * Default creator function to use if not specified in schema
-   */
+  /** 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
-   */
+  /** Whether to apply CSS class prefix @default true */
   prefix?: boolean;
-
-  /**
-   * Additional options
-   */
+  
+  /** 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
-   */
+  /** The raw layout object with all components */
   layout: Record<string, any>;
   
-  /**
-   * Reference to the root element for convenience
-   */
+  /** Reference to the root element for convenience */
   element: HTMLElement | ComponentLike;
   
-  /**
-   * Flattened component map
-   */
+  /** Flattened component map */
   component: Record<string, any>;
   
   /**