mtrl 0.1.2 → 0.2.0

package/src/core/compose/component.ts

@@ -0,0 +1,247 @@
+// src/core/compose/component.ts
+/**
+ * @module core/compose/component
+ * @description Core utilities for component composition and creation with built-in mobile support
+ */
+
+import { createElement, CreateElementOptions } from '../dom/create';
+import {
+  normalizeEvent,
+  hasTouchSupport,
+  TOUCH_CONFIG,
+  PASSIVE_EVENTS
+} from '../utils/mobile';
+
+/**
+ * Touch state interface to track touch interactions
+ */
+export interface TouchState {
+  startTime: number;
+  startPosition: { x: number; y: number };
+  isTouching: boolean;
+  activeTarget: EventTarget | null;
+}
+
+/**
+ * Base component interface with prefix utilities
+ */
+export interface BaseComponent {
+  config: Record<string, any>;
+  componentName?: string;
+  getClass: (name: string) => string;
+  getModifierClass: (base: string, modifier: string) => string;
+  getElementClass: (base: string, element: string) => string;
+  touchState: TouchState;
+  updateTouchState: (event: Event, status: 'start' | 'end') => void;
+}
+
+/**
+ * Element component extends base with element
+ */
+export interface ElementComponent extends BaseComponent {
+  element: HTMLElement;
+  addClass: (...classes: string[]) => ElementComponent;
+  destroy: () => void;
+}
+
+/**
+ * Options for withElement enhancer
+ */
+export interface WithElementOptions {
+  tag?: string;
+  componentName?: string;
+  attrs?: Record<string, any>;
+  className?: string | string[];
+  forwardEvents?: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+  interactive?: boolean;
+}
+
+/**
+ * Creates helper functions for managing CSS class names with a prefix
+ * @param {string} prefix - Prefix to apply to class names
+ * @returns {Object} Class name utilities
+ */
+const withPrefix = (prefix: string) => ({
+  /**
+   * Gets a prefixed class name
+   * @param {string} name - Base class name
+   * @returns {string} Prefixed class name
+   */
+  getClass: (name: string): string => `${prefix}-${name}`,
+  
+  /**
+   * Gets a prefixed modifier class name
+   * @param {string} base - Base class name
+   * @param {string} modifier - Modifier name
+   * @returns {string} Prefixed modifier class
+   */
+  getModifierClass: (base: string, modifier: string): string => `${base}--${modifier}`,
+  
+  /**
+   * Gets a prefixed element class name
+   * @param {string} base - Base class name
+   * @param {string} element - Element name
+   * @returns {string} Prefixed element class
+   */
+  getElementClass: (base: string, element: string): string => `${base}-${element}`
+});
+
+/**
+ * Creates a base component with configuration and prefix utilities.
+ * This forms the foundation for all components in the system.
+ *
+ * @param {Object} config - Component configuration
+ * @returns {BaseComponent} Base component with prefix utilities
+ */
+export const createBase = (config: Record<string, any> = {}): BaseComponent => ({
+  config,
+  componentName: config.componentName,
+  ...withPrefix(config.prefix || 'mtrl'),
+
+  /**
+   * Manages the touch interaction state for the component.
+   */
+  touchState: {
+    startTime: 0,
+    startPosition: { x: 0, y: 0 },
+    isTouching: false,
+    activeTarget: null
+  },
+
+  /**
+   * Updates the component's touch state based on user interactions.
+   * Tracks touch position and timing for gesture recognition.
+   */
+  updateTouchState(event: Event, status: 'start' | 'end'): void {
+    const normalized = normalizeEvent(event);
+
+    if (status === 'start') {
+      this.touchState = {
+        startTime: Date.now(),
+        startPosition: {
+          x: normalized.clientX,
+          y: normalized.clientY
+        },
+        isTouching: true,
+        activeTarget: normalized.target
+      };
+    } else if (status === 'end') {
+      this.touchState.isTouching = false;
+      this.touchState.activeTarget = null;
+    }
+  }
+});
+
+/**
+ * Higher-order function that adds a DOM element to a component
+ * @param {WithElementOptions} options - Element creation options
+ * @returns {Function} Component enhancer
+ */
+export const withElement = (options: WithElementOptions = {}) => 
+  (base: BaseComponent): ElementComponent => {
+    /**
+     * Handles the start of a touch interaction.
+     */
+    const handleTouchStart = (event: Event): void => {
+      base.updateTouchState(event, 'start');
+      element.classList.add(`${base.getClass('touch-active')}`);
+
+      if (options.forwardEvents?.touchstart && base.config?.emit) {
+        base.config.emit('touchstart', normalizeEvent(event));
+      }
+    };
+
+    /**
+     * Handles the end of a touch interaction.
+     */
+    const handleTouchEnd = (event: Event): void => {
+      if (!base.touchState.isTouching) return;
+
+      const touchDuration = Date.now() - base.touchState.startTime;
+      element.classList.remove(`${base.getClass('touch-active')}`);
+      base.updateTouchState(event, 'end');
+
+      // Emit tap event for short touches
+      if (touchDuration < TOUCH_CONFIG.TAP_THRESHOLD && base.config?.emit) {
+        base.config.emit('tap', normalizeEvent(event));
+      }
+
+      if (options.forwardEvents?.touchend && base.config?.emit) {
+        base.config.emit('touchend', normalizeEvent(event));
+      }
+    };
+
+    /**
+     * Handles touch movement.
+     */
+    const handleTouchMove = (event: Event): void => {
+      if (!base.touchState.isTouching) return;
+
+      const normalized = normalizeEvent(event);
+      const deltaX = normalized.clientX - base.touchState.startPosition.x;
+      const deltaY = normalized.clientY - base.touchState.startPosition.y;
+
+      // Detect and emit swipe gestures
+      if (Math.abs(deltaX) > TOUCH_CONFIG.SWIPE_THRESHOLD && base.config?.emit) {
+        base.config.emit('swipe', {
+          direction: deltaX > 0 ? 'right' : 'left',
+          deltaX,
+          deltaY
+        });
+      }
+
+      if (options.forwardEvents?.touchmove && base.config?.emit) {
+        base.config.emit('touchmove', { ...normalized, deltaX, deltaY });
+      }
+    };
+
+    // Create element options from component options
+    const elementOptions: CreateElementOptions = {
+      tag: options.tag || 'div',
+      className: [
+        base.getClass(options.componentName || base.componentName || 'component'),
+        hasTouchSupport() && options.interactive ? base.getClass('interactive') : null,
+        options.className
+      ].filter(Boolean),
+      attrs: options.attrs || {},
+      context: base
+    };
+
+    // Create the element with appropriate classes
+    const element = createElement(elementOptions);
+
+    // Add event listeners only if touch is supported and the component is interactive
+    if (hasTouchSupport() && options.interactive) {
+      element.addEventListener('touchstart', handleTouchStart, PASSIVE_EVENTS);
+      element.addEventListener('touchend', handleTouchEnd);
+      element.addEventListener('touchmove', handleTouchMove, PASSIVE_EVENTS);
+    }
+
+    return {
+      ...base,
+      element,
+
+      /**
+       * Adds CSS classes to the element
+       * @param {...string} classes - CSS classes to add
+       * @returns {ElementComponent} Component instance for chaining
+       */
+      addClass(...classes: string[]): ElementComponent {
+        element.classList.add(...classes.filter(Boolean));
+        return this;
+      },
+
+      /**
+       * Removes the element and cleans up event listeners.
+       * Ensures proper resource cleanup when the component is destroyed.
+       */
+      destroy(): void {
+        if (hasTouchSupport() && options.interactive) {
+          element.removeEventListener('touchstart', handleTouchStart);
+          element.removeEventListener('touchend', handleTouchEnd);
+          element.removeEventListener('touchmove', handleTouchMove);
+        }
+        element.remove();
+      }
+    };
+  };

package/src/core/compose/features/checkable.ts

@@ -0,0 +1,155 @@
+// src/core/compose/features/checkable.ts
+
+import { BaseComponent } from '../component';
+
+/**
+ * Configuration for checkable feature
+ */
+export interface CheckableConfig {
+  checked?: boolean;
+  [key: string]: any;
+}
+
+/**
+ * Component with input element
+ */
+export interface InputComponent extends BaseComponent {
+  input: HTMLInputElement;
+  emit?: (event: string, data: any) => InputComponent;
+}
+
+/**
+ * Checkable state manager interface
+ */
+export interface CheckableManager {
+  /**
+   * Sets the checked state to true
+   * Emits change event if state changes
+   * @returns CheckableManager instance for chaining
+   */
+  check: () => CheckableManager;
+  
+  /**
+   * Sets the checked state to false
+   * Emits change event if state changes
+   * @returns CheckableManager instance for chaining
+   */
+  uncheck: () => CheckableManager;
+  
+  /**
+   * Toggles the current checked state
+   * Always emits change event
+   * @returns CheckableManager instance for chaining
+   */
+  toggle: () => CheckableManager;
+  
+  /**
+   * Gets the current checked state
+   * @returns Whether component is checked
+   */
+  isChecked: () => boolean;
+}
+
+/**
+ * Component with checkable capabilities
+ */
+export interface CheckableComponent extends BaseComponent {
+  checkable: CheckableManager;
+}
+
+/**
+ * Adds checked state management to a component with an input
+ * Manages visual state and event emission for checked changes
+ *
+ * @param config - Checkable configuration
+ * @returns Function that enhances a component with checkable functionality
+ */
+export const withCheckable = <T extends CheckableConfig>(config: T = {} as T) => 
+  <C extends InputComponent>(component: C): C & CheckableComponent => {
+    if (!component.input) return component as C & CheckableComponent;
+
+    /**
+     * Updates component classes to reflect checked state
+     */
+    const updateStateClasses = (): void => {
+      component.element.classList.toggle(
+        `${component.getClass('switch')}--checked`,
+        component.input.checked
+      );
+    };
+
+    // Set initial state
+    if (config.checked) {
+      component.input.checked = true;
+      updateStateClasses();
+    }
+
+    // Update classes whenever checked state changes
+    if (component.emit) {
+      component.on?.('change', updateStateClasses);
+    }
+
+    const checkable: CheckableManager = {
+      /**
+       * Sets the checked state to true
+       * Emits change event if state changes
+       * @returns CheckableManager instance for chaining
+       */
+      check() {
+        if (!component.input.checked) {
+          component.input.checked = true;
+          updateStateClasses();
+          component.emit?.('change', {
+            checked: true,
+            value: component.input.value
+          });
+        }
+        return this;
+      },
+
+      /**
+       * Sets the checked state to false
+       * Emits change event if state changes
+       * @returns CheckableManager instance for chaining
+       */
+      uncheck() {
+        if (component.input.checked) {
+          component.input.checked = false;
+          updateStateClasses();
+          component.emit?.('change', {
+            checked: false,
+            value: component.input.value
+          });
+        }
+        return this;
+      },
+
+      /**
+       * Toggles the current checked state
+       * Always emits change event
+       * @returns CheckableManager instance for chaining
+       */
+      toggle() {
+        component.input.checked = !component.input.checked;
+        updateStateClasses();
+        component.emit?.('change', {
+          checked: component.input.checked,
+          value: component.input.value
+        });
+        return this;
+      },
+
+      /**
+       * Gets the current checked state
+       * @returns Whether component is checked
+       */
+      isChecked() {
+        return component.input.checked;
+      }
+    };
+
+    return {
+      ...component,
+      checkable
+    };
+  };

package/src/core/compose/features/disabled.ts

@@ -0,0 +1,116 @@
+// src/core/compose/features/disabled.ts
+
+import { BaseComponent, ElementComponent } from '../component';
+
+/**
+ * Configuration for disabled feature
+ */
+export interface DisabledConfig {
+  disabled?: boolean;
+  componentName?: string;
+  [key: string]: any;
+}
+
+/**
+ * Disabled state manager interface
+ */
+export interface DisabledManager {
+  /**
+   * Enables the component
+   * @returns DisabledManager instance for chaining
+   */
+  enable(): DisabledManager;
+  
+  /**
+   * Disables the component
+   * @returns DisabledManager instance for chaining
+   */
+  disable(): DisabledManager;
+  
+  /**
+   * Toggles the disabled state
+   * @returns DisabledManager instance for chaining
+   */
+  toggle(): DisabledManager;
+  
+  /**
+   * Checks if the component is disabled
+   * @returns true if disabled
+   */
+  isDisabled(): boolean;
+}
+
+/**
+ * Component with disabled state capabilities
+ */
+export interface DisabledComponent extends BaseComponent {
+  disabled: DisabledManager;
+}
+
+/**
+ * Adds disabled state management to a component
+ * 
+ * @param config - Configuration object
+ * @returns Function that enhances a component with disabled state management
+ */
+export const withDisabled = <T extends DisabledConfig>(config: T) => 
+  <C extends ElementComponent>(component: C): C & DisabledComponent => {
+    // Get the disabled class based on component name
+    const disabledClass = `${component.getClass(config.componentName || component.componentName || 'component')}--disabled`;
+
+    // Directly implement disabled functionality
+    const disabled: DisabledManager = {
+      enable() {
+        component.element.classList.remove(disabledClass);
+        if ('input' in component && component.input instanceof HTMLElement) {
+          component.input.disabled = false;
+          component.input.removeAttribute('disabled');
+        } else {
+          (component.element as HTMLButtonElement).disabled = false;
+          component.element.removeAttribute('disabled');
+        }
+        return this;
+      },
+
+      disable() {
+        component.element.classList.add(disabledClass);
+        if ('input' in component && component.input instanceof HTMLElement) {
+          component.input.disabled = true;
+          component.input.setAttribute('disabled', 'true');
+        } else {
+          (component.element as HTMLButtonElement).disabled = true;
+          component.element.setAttribute('disabled', 'true');
+        }
+        return this;
+      },
+
+      toggle() {
+        if (this.isDisabled()) {
+          this.enable();
+        } else {
+          this.disable();
+        }
+        return this;
+      },
+
+      isDisabled() {
+        if ('input' in component && component.input instanceof HTMLElement) {
+          return component.input.disabled;
+        }
+        return (component.element as HTMLButtonElement).disabled;
+      }
+    };
+
+    // Initialize disabled state if configured
+    if (config.disabled) {
+      // Use requestAnimationFrame to ensure DOM is ready
+      requestAnimationFrame(() => {
+        disabled.disable();
+      });
+    }
+
+    return {
+      ...component,
+      disabled
+    };
+  };

package/src/core/compose/features/events.ts

@@ -0,0 +1,65 @@
+// src/core/compose/features/events.ts
+/**
+ * @module core/compose/features
+ */
+
+import { createEmitter, Emitter } from '../../state/emitter';
+import { BaseComponent } from '../component';
+
+/**
+ * Component with event capabilities
+ */
+export interface EventComponent extends BaseComponent {
+  /**
+   * Subscribe to an event
+   * @param event - Event name
+   * @param handler - Event handler
+   * @returns Component instance for chaining
+   */
+  on(event: string, handler: (...args: any[]) => void): EventComponent;
+  
+  /**
+   * Unsubscribe from an event
+   * @param event - Event name
+   * @param handler - Event handler
+   * @returns Component instance for chaining
+   */
+  off(event: string, handler: (...args: any[]) => void): EventComponent;
+  
+  /**
+   * Emit an event
+   * @param event - Event name
+   * @param data - Event data
+   * @returns Component instance for chaining
+   */
+  emit(event: string, data?: any): EventComponent;
+}
+
+/**
+ * Adds event handling capabilities to a component
+ * Returns event system ready to use immediately
+ * 
+ * @returns Function that enhances a component with event capabilities
+ */
+export const withEvents = () => 
+  <T extends BaseComponent>(component: T): T & EventComponent => {
+    const emitter: Emitter = createEmitter();
+
+    return {
+      ...component,
+      on(event: string, handler: (...args: any[]) => void) {
+        emitter.on(event, handler);
+        return this;
+      },
+
+      off(event: string, handler: (...args: any[]) => void) {
+        emitter.off(event, handler);
+        return this;
+      },
+
+      emit(event: string, data?: any) {
+        emitter.emit(event, data);
+        return this;
+      }
+    };
+  };

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

@@ -0,0 +1,67 @@
+// src/core/compose/features/icon.ts
+
+import { createIcon, IconManager } from '../../build/icon';
+import { BaseComponent, ElementComponent } from '../component';
+
+/**
+ * Configuration for icon feature
+ */
+export interface IconConfig {
+  icon?: string;
+  iconPosition?: 'start' | 'end';
+  iconSize?: string;
+  prefix?: string;
+  componentName?: string;
+  text?: string;
+  [key: string]: any;
+}
+
+/**
+ * Component with icon capabilities
+ */
+export interface IconComponent extends BaseComponent {
+  icon: IconManager;
+}
+
+/**
+ * Updates the component's circular style based on content
+ * Adds circular class if there's an icon but no text
+ */
+const updateCircularStyle = (component: ElementComponent, config: IconConfig): void => {
+  const hasText = config.text;
+  const hasIcon = config.icon;
+
+  const circularClass = `${component.getClass('button')}--circular`;
+  if (!hasText && hasIcon) {
+    component.element.classList.add(circularClass);
+  } else {
+    component.element.classList.remove(circularClass);
+  }
+};
+
+/**
+ * Adds icon management to a component
+ * 
+ * @param config - Configuration object containing icon information
+ * @returns Function that enhances a component with icon capabilities
+ */
+export const withIcon = <T extends IconConfig>(config: T) => 
+  <C extends ElementComponent>(component: C): C & IconComponent => {
+    const icon = createIcon(component.element, {
+      prefix: config.prefix,
+      type: config.componentName || 'component',
+      position: config.iconPosition,
+      iconSize: config.iconSize
+    });
+
+    if (config.icon) {
+      icon.setIcon(config.icon);
+    }
+
+    updateCircularStyle(component, config);
+
+    return {
+      ...component,
+      icon
+    };
+  };

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

@@ -0,0 +1,35 @@
+// src/core/compose/features/index.ts
+
+// Core features
+export { withEvents } from './events';
+export { withText } from './text';
+export { withIcon } from './icon';
+export { withVariant } from './variant';
+export { withSize } from './size';
+export { withPosition } from './position';
+export { withRipple } from './ripple';
+export { withInput } from './input';
+export { withCheckable } from './checkable';
+export { withStyle } from './style';
+export { withTextInput } from './textinput';
+export { withTextLabel } from './textlabel';
+export { withTrack } from './track';
+export { withEvents as withEnhancedEvents } from './withEvents';
+
+// State management features
+export { withDisabled } from './disabled';
+export { withLifecycle } from './lifecycle';
+
+// Re-export interfaces for better developer experience
+export type { EventComponent } from './events';
+export type { TextComponent } from './text';
+export type { IconComponent } from './icon';
+export type { LifecycleComponent, Lifecycle } from './lifecycle';
+export type { DisabledComponent, DisabledManager } from './disabled';
+export type { RippleComponent } from './ripple';
+export type { InputComponent } from './input';
+export type { CheckableComponent, CheckableManager } from './checkable';
+export type { TextInputComponent } from './textinput';
+export type { LabelComponent, LabelManager } from './textlabel';
+export type { TrackComponent } from './track';
+export type { EnhancedEventComponent } from './withEvents';