mtrl 0.2.8 → 0.3.0

package/src/core/layout/README.md

@@ -0,0 +1,350 @@
+# Layout Module
+
+A lightweight, flexible system for creating and managing visual arrangements and component hierarchies.
+
+## Overview
+
+The Layout Module provides a declarative approach to building UI layouts using either arrays or objects. It efficiently handles DOM operations, component instantiation, and visual arrangement in a bundle-optimized way.
+
+## Features
+
+- **Multiple Schema Formats** - Support for array-based, object-based, and HTML string schemas
+- **Efficient DOM Operations** - Batched DOM manipulations with DocumentFragment
+- **Component Management** - Easy access to component instances via consistent API
+- **Customizable Creation** - Control class prefixing and specify default creators
+- **Optimized for Bundle Size** - Minimal footprint with maximum functionality
+- **TypeScript Support** - Full type definitions for developer experience
+
+## Basic Usage
+
+### Array-based Layout
+
+```javascript
+import { createLayout, createButton, createDialog, createList, createListItem } from 'mtrl';
+
+const layout = createLayout([
+  // Root level contains primary components
+  createButton, 'submitButton', { text: 'Submit', variant: 'primary' },
+  
+  // Dialog is a root component, not nested inside other elements
+  createDialog, 'confirmDialog', { 
+    title: 'Confirm Action',
+    closeOnBackdrop: true,
+    width: '350px' 
+  }
+]);
+
+// Add content to the dialog separately
+const dialogContent = createLayout([
+  createList, 'actionsList', {},
+  [
+    createListItem, 'confirmAction', { text: 'Confirm', leading: 'check' },
+    createListItem, 'cancelAction', { text: 'Cancel', leading: 'close' }
+  ]
+], layout.get('confirmDialog').contentElement);
+
+// Access components
+const submitButton = layout.get('submitButton');
+const confirmDialog = layout.get('confirmDialog');
+
+// Handle events
+submitButton.on('click', () => confirmDialog.open());
+```
+
+### Object-based Layout
+
+```javascript
+import { createLayout, createTopAppBar, createNavigation, createList, createListItem, createTextfield, createButton } from 'mtrl';
+
+const layout = createLayout({
+  element: {
+    creator: createTopAppBar,
+    options: { 
+      title: 'Profile Settings',
+      variant: 'small' 
+    },
+    children: {
+      navigation: {
+        creator: createNavigation,
+        options: { variant: 'drawer', persistent: true },
+        children: {
+          navList: {
+            creator: createList,
+            options: { interactive: true },
+            children: {
+              profileLink: {
+                creator: createListItem,
+                options: { text: 'Profile', leading: 'person' }
+              },
+              settingsLink: {
+                creator: createListItem,
+                options: { text: 'Settings', leading: 'settings' }
+              },
+              logoutLink: {
+                creator: createListItem,
+                options: { text: 'Logout', leading: 'logout' }
+              }
+            }
+          }
+        }
+      },
+      form: {
+        creator: createElement,
+        options: { tag: 'form', className: 'profile-form' },
+        children: {
+          nameField: {
+            creator: createTextfield,
+            options: { label: 'Full Name', required: true }
+          },
+          emailField: {
+            creator: createTextfield,
+            options: { label: 'Email', type: 'email', required: true }
+          },
+          saveButton: {
+            creator: createButton,
+            options: { text: 'Save Changes', variant: 'filled' }
+          }
+        }
+      }
+    }
+  }
+});
+
+// Access components
+const topAppBar = layout.element;
+const nameField = layout.get('nameField');
+const saveButton = layout.get('saveButton');
+
+// Use the components
+nameField.setValue('John Doe');
+saveButton.on('click', () => console.log('Profile updated'));
+```
+
+### HTML String Layout
+
+```javascript
+import createLayout from 'core/layout';
+
+const layout = createLayout(`
+  <div class="notification">
+    <h3>Welcome!</h3>
+    <p>Thank you for joining our platform.</p>
+  </div>
+`);
+
+// Access the root element
+const notification = layout.element;
+document.body.appendChild(notification);
+```
+
+### Using Options Parameter
+
+```javascript
+import { createLayout, createButton, createTextfield, createCard, createChip, createTopAppBar, createBottomAppBar } from 'mtrl';
+
+// With default creator and disabled prefix
+const formLayout = createLayout(
+  [
+    // Using string keys relies on the default creator
+    'nameField', { label: 'Name', required: true },
+    'emailField', { label: 'Email', type: 'email', required: true },
+    'phoneField', { label: 'Phone', type: 'tel' },
+    
+    // Explicitly override the default creator
+    createButton, 'submitButton', { text: 'Submit', variant: 'filled' }
+  ],
+  document.getElementById('form-container'),
+  {
+    creator: createTextfield, // Default creator for all elements without a specific constructor
+    prefix: false // Disable automatic class prefixing
+  }
+);
+
+// With theme options for a complete dashboard layout
+const dashboardLayout = createLayout(
+  [
+    createTopAppBar, 'header', { 
+      title: 'Dashboard', 
+      actions: ['notifications', 'account'] 
+    },
+    
+    createCard, 'statsCard', { 
+      title: 'Performance Metrics',
+      outlined: true 
+    },
+    [
+      createChip, 'visitsChip', { text: 'Visits: 1.2K', leadingIcon: 'visibility' },
+      createChip, 'conversionChip', { text: 'Conversion: 5.4%', leadingIcon: 'trending_up' }
+    ],
+    
+    createCard, 'activityCard', { 
+      title: 'Recent Activity',
+      outlined: true
+    },
+    
+    createBottomAppBar, 'footer', {
+      actions: [
+        { icon: 'home', label: 'Home' },
+        { icon: 'search', label: 'Search' },
+        { icon: 'settings', label: 'Settings' }
+      ]
+    }
+  ],
+  document.getElementById('app'),
+  {
+    theme: 'dark', // Custom theme option
+    density: 'comfortable', // Custom density option
+    animations: true // Custom animation option
+  }
+);
+
+// Access and use the layout
+const nameField = formLayout.get('nameField');
+nameField.setValue('John Doe');
+
+const statsCard = dashboardLayout.get('statsCard');
+statsCard.setTitle('Updated Metrics - ' + new Date().toLocaleDateString());
+```
+
+## API Reference
+
+### Core Functions
+
+#### `createLayout(schema, parentElement?, options?)`
+
+Creates a layout from a schema definition.
+
+- **Parameters**:
+  - `schema`: Array, object, HTML string, or function returning one of these
+  - `parentElement` (optional): Parent element to attach the layout to
+  - `options` (optional): Configuration options for layout creation:
+    - `creator`: Default creator function to use when not specified in schema
+    - `prefix`: Boolean to control whether CSS class prefixing is applied (default: true)
+    - Custom options can be added and accessed in component creators
+- **Returns**: Layout result object with components and utility methods
+
+#### `processSchema(schema, parentElement?, level?, options?)`
+
+Low-level function for processing schemas directly.
+
+- **Parameters**:
+  - `schema`: Array or object schema
+  - `parentElement` (optional): Parent element to attach to
+  - `level` (optional): Current recursion level
+  - `options` (optional): Layout creation options
+- **Returns**: Layout result object
+
+#### `createComponentInstance(Component, options?, layoutOptions?)`
+
+Creates a component instance from a constructor or factory function.
+
+- **Parameters**:
+  - `Component`: Constructor or factory function
+  - `options` (optional): Options to pass to the component
+  - `layoutOptions` (optional): Global layout options
+- **Returns**: Component instance
+
+### Utility Functions
+
+#### `isComponent(value)`
+
+Checks if a value is a component-like object.
+
+- **Parameters**:
+  - `value`: Value to check
+- **Returns**: Boolean indicating if the value is a component
+
+#### `processClassNames(options, skipPrefix?)`
+
+Processes class names in options to add prefixes.
+
+- **Parameters**:
+  - `options`: Element options containing className
+  - `skipPrefix` (optional): Whether to skip adding prefixes
+- **Returns**: Updated options with prefixed classNames
+
+#### `flattenLayout(layout)`
+
+Flattens a nested layout for easier component access.
+
+- **Parameters**:
+  - `layout`: Layout object to flatten
+- **Returns**: Flattened layout with components
+
+### Result Object
+
+The layout result object contains:
+
+- `layout`: Raw layout object with all components
+- `element`: Reference to the root element
+- `component`: Flattened component map for easy access
+- `get(name)`: Function to get a component by name
+- `getAll()`: Function to get all components
+- `destroy()`: Function to clean up the layout
+
+## Integrating with Layout Manager
+
+This module works well with the Layout Manager for advanced application layouts:
+
+```javascript
+import createLayout from 'core/layout';
+import createLayoutManager from 'client/core/layout/layout-manager';
+
+// Create application layout
+const appLayout = createLayout([
+  // Application components...
+]);
+
+// Create layout manager with the layout
+const layoutManager = createLayoutManager({
+  layout: appLayout.layout,
+  layoutAPI: appLayout
+});
+
+// Use layout manager API
+layoutManager.setContent('<h1>Welcome to the app</h1>');
+layoutManager.setPageTitle('Dashboard');
+```
+
+## Performance Considerations
+
+### Schema Format Performance
+
+**Array-based schemas** generally outperform object-based schemas:
+
+- **Faster processing**: 15-30% faster for large layouts
+- **Lower memory usage**: Requires less memory without property names
+- **Better bundle size**: More compact representation in code
+- **Efficient iteration**: Arrays are optimized for sequential access
+
+**Object-based schemas** excel in:
+
+- **Readability**: More explicit structure with named properties
+- **Maintainability**: Easier to understand complex nested structures
+- **Self-documentation**: Property names describe the layout's purpose
+
+**Recommendations**:
+- For **performance-critical** applications, prefer array-based schemas
+- For **complex, deeply nested** structures where maintainability is key, consider object-based schemas
+- For the **best balance**, use array-based schemas for large structures and object-based for complex configurations
+
+### Options Performance Considerations
+
+- Setting `prefix: false` can improve performance slightly by avoiding class name processing
+- Providing a `creator` function in options is more efficient than having many duplicate creator references in the schema
+- Consider memoizing layout creation for frequently used UI patterns with the same options
+
+### General Optimization Tips
+
+- Use DocumentFragment for batch DOM operations
+- Create components only when needed
+- Consider memoizing frequently created layouts
+- For large applications, lazy-load secondary layouts
+
+## Browser Compatibility
+
+The Layout Module is compatible with all modern browsers (Chrome, Firefox, Safari, Edge).
+
+## License
+
+MIT

package/src/core/layout/array.ts

@@ -0,0 +1,181 @@
+// src/core/layout/array.ts
+/**
+ * @module core/layout
+ * @description Processor for array-based layout schemas
+ */
+
+import { createElement } from '../dom/create';
+import { LayoutResult, LayoutOptions } from './types';
+import { isComponent, createFragment, processClassNames } from './utils';
+import { createLayoutResult } from './result';
+import { createComponentInstance } from './processor';
+import { isObject } from '../utils';
+
+/**
+ * Processes an array-based layout definition
+ * 
+ * @param schema - Array-based layout definition
+ * @param parentElement - Optional parent element to attach layout to
+ * @param level - Current recursion level
+ * @param options - Layout creation options
+ * @returns Layout result object
+ */
+export function processArraySchema(
+  schema: any[], 
+  parentElement: HTMLElement | null = null, 
+  level: number = 0,
+  options: LayoutOptions = {}
+): LayoutResult {
+  level++;
+  const layout = {};
+  const components = [];
+  const fragment = createFragment();
+  let component = null;
+
+  if (!Array.isArray(schema)) {
+    console.error('Schema is not an array!', parentElement, level, schema);
+    return createLayoutResult(layout);
+  }
+
+  // Get default creator function from options or use createElement
+  const defaultCreator = options.creator || createElement;
+
+  for (let i = 0; i < schema.length; i++) {
+    const item = schema[i];
+    if (!item) continue;
+
+    // Handle nested arrays recursively
+    if (Array.isArray(item)) {
+      const container = component || parentElement;
+      // Use this function for recursion, not the external processSchema
+      const result = processArraySchema(item, container, level, options);
+      Object.assign(layout, result.layout);
+      continue;
+    }
+
+    // Handle different item types
+    let creator, name, itemOptions;
+
+    // Case 1: Item is a function (component creator)
+    if (typeof item === 'function') {
+      creator = item;
+      
+      // Check next items for name (string) and options (object)
+      const nextItem = schema[i+1];
+      const afterNextItem = schema[i+2];
+      
+      if (typeof nextItem === 'string') {
+        name = nextItem;
+        i++; // Skip the name on next iteration
+        
+        // Check if options are provided after the name
+        if (isObject(afterNextItem)) {
+          itemOptions = afterNextItem;
+          i++; // Skip the options on next iteration
+        } else {
+          itemOptions = {};
+        }
+      } else if (isObject(nextItem)) {
+        // No name provided, just options
+        itemOptions = nextItem;
+        i++; // Skip the options on next iteration
+      } else {
+        // No name or options
+        itemOptions = {};
+      }
+    }
+    // Case 2: Item is a string (component name using default creator)
+    else if (typeof item === 'string') {
+      creator = defaultCreator;
+      name = item;
+      
+      // Check next item for options
+      const nextItem = schema[i+1];
+      if (isObject(nextItem)) {
+        itemOptions = nextItem;
+        i++; // Skip the options on next iteration
+      } else {
+        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
+      if (creator === createElement && !('tag' in itemOptions)) {
+        itemOptions.tag = 'div'; // Default to div if no tag is specified
+      }
+    }
+    // Case 3: Item is an object (options for default creator with no name)
+    else if (isObject(item)) {
+      creator = defaultCreator;
+      itemOptions = item;
+    } 
+    else {
+      // Skip unsupported item types
+      console.warn('Skipping unsupported item type:', item);
+      continue;
+    }
+    
+    // Check for additional options object after main options
+    const maybeAdditionalOptions = schema[i+1];
+    if (isObject(maybeAdditionalOptions) && !Array.isArray(maybeAdditionalOptions) && 
+        typeof maybeAdditionalOptions.prefix !== 'undefined') {
+      // Merge the additional options into main options
+      Object.assign(itemOptions, maybeAdditionalOptions);
+      i++; // Skip on next iteration
+    }
+
+    // Process options based on prefix setting
+    const shouldApplyPrefix = 
+      // Use item-specific prefix setting if available
+      'prefix' in itemOptions ? 
+        itemOptions.prefix : 
+        // Otherwise use global options prefix setting (default to true)
+        options.prefix !== false;
+
+    const processedOptions = shouldApplyPrefix ? 
+      processClassNames(itemOptions) : 
+      { ...itemOptions };
+
+    // Add name to options if needed and not a DOM element tag
+    if (name && !('name' in processedOptions) && 
+        !(creator === createElement || creator.isElement)) {
+      processedOptions.name = name;
+    }
+
+    // Create and store component
+    component = createComponentInstance(creator, processedOptions, options);
+    const element = isComponent(component) ? component.element : component;
+    
+    if (level === 1) layout.element = element;
+    if (name) {
+      layout[name] = component;
+      components.push([name, component]);
+    }
+
+    // Append to DOM
+    if (component) {
+      if ('insert' in component && typeof component.insert === 'function') {
+        component.insert(fragment);
+      } else {
+        fragment.appendChild(element);
+      }
+
+      if (parentElement) {
+        component._container = parentElement;
+        
+        if ('onInserted' in component && typeof component.onInserted === 'function') {
+          component.onInserted(parentElement);
+        }
+      }
+    }
+  }
+
+  // Append fragment to parent in a single operation
+  if (parentElement && fragment.hasChildNodes()) {
+    const wrapper = isComponent(parentElement) ? parentElement.element : parentElement;
+    wrapper.appendChild(fragment);
+  }
+
+  layout.components = components;
+  return createLayoutResult(layout);
+}

package/src/core/layout/create.ts

@@ -0,0 +1,55 @@
+// src/core/layout/create.ts
+/**
+ * @module core/layout
+ * @description Main layout creation functionality with optimized DOM operations
+ */
+
+import { Schema, LayoutResult, LayoutOptions } from './types';
+import { processSchema } from './processor';
+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
+ * @param options - Additional options for layout creation
+ * @returns Object containing the layout and utility functions
+ */
+export function createLayout(
+  schema: Schema | any[] | string | Function, 
+  parentElement: HTMLElement | null = null,
+  options: LayoutOptions = {}
+): LayoutResult {
+  // If schema is a function, execute it to get the actual schema
+  if (typeof schema === 'function') {
+    schema = schema();
+  }
+  
+  // Parse HTML string into a layout if needed
+  if (typeof schema === 'string') {
+    // Create a temporary element to parse HTML
+    const template = document.createElement('template');
+    template.innerHTML = schema.trim();
+    
+    // Use the parsed DOM structure directly
+    const fragment = template.content;
+    
+    if (parentElement && fragment.hasChildNodes()) {
+      // Batch DOM operation - append all nodes at once
+      parentElement.appendChild(fragment);
+    }
+    
+    // Create a basic layout for HTML string
+    const layout = { 
+      element: fragment.firstElementChild as HTMLElement 
+    };
+    
+    // Create layout result with HTML content
+    return createLayoutResult(layout);
+  }
+  
+  // Process the schema using our unified processor with options
+  return processSchema(schema, parentElement, 0, options);
+}

package/src/core/layout/index.ts

@@ -0,0 +1,26 @@
+// src/core/layout/index.ts
+/**
+ * @module core/layout
+ * @description Optimized layout creation system with simplified API
+ */
+
+// Export essential types
+export type { 
+  ComponentLike, 
+  ElementDefinition, 
+  Schema, 
+  LayoutResult,
+  LayoutOptions 
+} from './types';
+
+// Export utility functions
+export { isComponent, processClassNames, flattenLayout } from './utils';
+
+// Export core functionality
+export { createLayout } from './create';
+export { createLayoutResult } from './result';
+export { processSchema, createComponentInstance } from './processor';
+
+// Default export for backward compatibility and simpler usage
+import { createLayout } from './create';
+export default createLayout;