mtrl 0.1.2 → 0.2.0

package/src/core/dom/events.ts

@@ -0,0 +1,209 @@
+// src/core/dom/events.ts
+/**
+ * @module core/dom
+ * @description DOM manipulation utilities
+ */
+
+/**
+ * Event manager interface for handling DOM events
+ */
+export interface EventManager {
+  /**
+   * Add an event listener with options
+   * @param event - Event name
+   * @param handler - Event handler
+   * @param options - addEventListener options
+   * @returns EventManager instance for chaining
+   */
+  on: <T extends Event>(event: string, handler: (e: T) => void, options?: AddEventListenerOptions) => EventManager;
+  
+  /**
+   * Remove an event listener
+   * @param event - Event name
+   * @param handler - Event handler
+   * @returns EventManager instance for chaining
+   */
+  off: <T extends Event>(event: string, handler: (e: T) => void) => EventManager;
+  
+  /**
+   * Temporarily disable all event listeners
+   * @returns EventManager instance for chaining
+   */
+  pause: () => EventManager;
+  
+  /**
+   * Re-enable all event listeners
+   * @returns EventManager instance for chaining
+   */
+  resume: () => EventManager;
+  
+  /**
+   * Remove all event listeners and clean up
+   */
+  destroy: () => void;
+  
+  /**
+   * Get all active handlers
+   * @returns Map of active handlers
+   */
+  getHandlers: () => Map<string, HandlerInfo>;
+  
+  /**
+   * Check if a specific handler exists
+   * @param event - Event name
+   * @param handler - Event handler
+   * @returns Whether handler exists
+   */
+  hasHandler: <T extends Event>(event: string, handler: (e: T) => void) => boolean;
+}
+
+/**
+ * Handler information
+ */
+interface HandlerInfo {
+  original: EventListener;
+  enhanced: EventListener;
+  event: string;
+  options: AddEventListenerOptions;
+}
+
+/**
+ * Creates an event manager to handle DOM events with enhanced functionality.
+ * Provides a robust interface for managing event listeners with error handling,
+ * cleanup, and lifecycle management.
+ *
+ * @param element - DOM element to attach events to
+ * @returns Event manager interface
+ */
+export const createEventManager = (element: HTMLElement): EventManager => {
+  // Store handlers with their metadata
+  const handlers = new Map<string, HandlerInfo>();
+
+  /**
+   * Creates a unique handler identifier
+   * @param event - Event name
+   * @param handler - EventListener
+   * @returns Unique identifier
+   */
+  const createHandlerId = (event: string, handler: EventListener): string =>
+    `${event}_${handler.toString()}`;
+
+  /**
+   * Wraps an event handler with error boundary and logging
+   * @param handler - Original event handler
+   * @param event - Event name for error context
+   * @returns Enhanced handler with error boundary
+   */
+  const enhanceHandler = (handler: EventListener, event: string): EventListener => (e: Event) => {
+    try {
+      handler(e);
+    } catch (error) {
+      console.error(`Error in ${event} handler:`, error);
+    }
+  };
+
+  /**
+   * Safely removes event listener
+   * @param event - Event name
+   * @param handler - Event handler
+   */
+  const safeRemoveListener = (event: string, handler: EventListener): void => {
+    try {
+      element.removeEventListener(event, handler);
+    } catch (error) {
+      console.warn(`Failed to remove ${event} listener:`, error);
+    }
+  };
+
+  return {
+    /**
+     * Adds an event listener with options
+     * @param event - Event name
+     * @param handler - Event handler
+     * @param options - addEventListener options
+     * @returns EventManager instance for chaining
+     */
+    on<T extends Event>(event: string, handler: (e: T) => void, options: AddEventListenerOptions = {}): EventManager {
+      const enhanced = enhanceHandler(handler as EventListener, event);
+      const id = createHandlerId(event, handler as EventListener);
+
+      handlers.set(id, {
+        original: handler as EventListener,
+        enhanced,
+        event,
+        options
+      });
+
+      element.addEventListener(event, enhanced, options);
+      return this;
+    },
+
+    /**
+     * Removes an event listener
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns EventManager instance for chaining
+     */
+    off<T extends Event>(event: string, handler: (e: T) => void): EventManager {
+      const id = createHandlerId(event, handler as EventListener);
+      const stored = handlers.get(id);
+
+      if (stored) {
+        safeRemoveListener(event, stored.enhanced);
+        handlers.delete(id);
+      }
+      return this;
+    },
+
+    /**
+     * Temporarily disables all event listeners
+     * @returns EventManager instance for chaining
+     */
+    pause(): EventManager {
+      handlers.forEach(({ enhanced, event }) => {
+        safeRemoveListener(event, enhanced);
+      });
+      return this;
+    },
+
+    /**
+     * Re-enables all event listeners
+     * @returns EventManager instance for chaining
+     */
+    resume(): EventManager {
+      handlers.forEach(({ enhanced, event, options }) => {
+        element.addEventListener(event, enhanced, options);
+      });
+      return this;
+    },
+
+    /**
+     * Removes all event listeners and cleans up
+     */
+    destroy(): void {
+      handlers.forEach(({ enhanced, event }) => {
+        safeRemoveListener(event, enhanced);
+      });
+      handlers.clear();
+    },
+
+    /**
+     * Gets all active handlers
+     * @returns Map of active handlers
+     */
+    getHandlers(): Map<string, HandlerInfo> {
+      return new Map(handlers);
+    },
+
+    /**
+     * Checks if a specific handler exists
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns Whether handler exists
+     */
+    hasHandler<T extends Event>(event: string, handler: (e: T) => void): boolean {
+      const id = createHandlerId(event, handler as EventListener);
+      return handlers.has(id);
+    }
+  };
+};

package/src/core/dom/index.ts

@@ -0,0 +1,10 @@
+// src/core/dom/index.ts
+
+export { createElement, withAttributes, withClasses, withContent } from './create';
+export type { CreateElementOptions } from './create';
+
+export { setAttributes, removeAttributes } from './attributes';
+export { addClass, removeClass, toggleClass, hasClass } from './classes';
+
+export { createEventManager } from './events';
+export type { EventManager } from './events';

package/src/core/dom/utils.ts

@@ -0,0 +1,97 @@
+// src/core/dom/utils.ts
+
+/**
+ * Normalizes class names input by handling various formats:
+ * - String with space-separated classes
+ * - Array of strings
+ * - Mixed array of strings and space-separated classes
+ * 
+ * @param classes - Classes to normalize
+ * @returns Array of unique, non-empty class names
+ */
+export const normalizeClasses = (...classes: (string | string[])[]): string[] => {
+  return [...new Set(
+    classes
+      .flat()
+      .reduce((acc: string[], cls) => {
+        if (typeof cls === 'string') {
+          // Split space-separated classes and add them individually
+          acc.push(...cls.split(/\s+/));
+        }
+        return acc;
+      }, [])
+      .filter(Boolean) // Remove empty strings
+  )];
+};
+
+/**
+ * Creates a DOM element with attributes
+ * 
+ * @param tag - Element tag name
+ * @param attributes - Element attributes
+ * @returns Created element
+ */
+export const createElement = <T extends HTMLElement>(tag: string, attributes: Record<string, any> = {}): T => {
+  const element = document.createElement(tag) as T;
+  
+  Object.entries(attributes).forEach(([key, value]) => {
+    if (key === 'className') {
+      element.className = value;
+    } else if (key === 'style' && typeof value === 'object') {
+      Object.assign(element.style, value);
+    } else if (key === 'data' && typeof value === 'object') {
+      Object.entries(value).forEach(([dataKey, dataValue]) => {
+        element.dataset[dataKey] = String(dataValue);
+      });
+    } else if (key === 'children' && Array.isArray(value)) {
+      value.forEach(child => {
+        if (child instanceof Node) {
+          element.appendChild(child);
+        } else if (child != null) {
+          element.appendChild(document.createTextNode(String(child)));
+        }
+      });
+    } else if (key.startsWith('on') && typeof value === 'function') {
+      const eventName = key.slice(2).toLowerCase();
+      element.addEventListener(eventName, value);
+    } else if (value !== null && value !== undefined) {
+      element.setAttribute(key, String(value));
+    }
+  });
+  
+  return element;
+};
+
+/**
+ * Sets inline styles on an element
+ * 
+ * @param element - Target element
+ * @param styles - Styles to set
+ * @returns Modified element
+ */
+export const setStyles = <T extends HTMLElement>(element: T, styles: Partial<CSSStyleDeclaration>): T => {
+  Object.assign(element.style, styles);
+  return element;
+};
+
+/**
+ * Checks if an element matches a selector
+ * 
+ * @param element - Element to check
+ * @param selector - CSS selector
+ * @returns Whether element matches selector
+ */
+export const matches = (element: Element, selector: string): boolean => {
+  return element.matches(selector);
+};
+
+/**
+ * Finds the closest ancestor matching a selector
+ * 
+ * @param element - Starting element
+ * @param selector - CSS selector
+ * @returns Matching ancestor or null
+ */
+export const closest = <T extends HTMLElement>(element: Element, selector: string): T | null => {
+  return element.closest(selector) as T | null;
+};

package/src/core/index.ts

@@ -0,0 +1,111 @@
+// src/core/index.ts
+/**
+ * @module core
+ * @description Core utilities and building blocks for the component system
+ */
+
+// Config
+export { PREFIX, COMPONENTS, STATES, classNames } from './config';
+export type { 
+  ThemeConfig, 
+  ComponentConfig, 
+  ThemedComponentConfig, 
+  VariantComponentConfig, 
+  StateComponentConfig 
+} from './config';
+
+// Build
+export { createText } from './build/text';
+export { createIcon } from './build/icon';
+export { createRipple } from './build/ripple';
+export { RIPPLE_TIMING } from './build/constants';
+
+// DOM manipulation
+export { createElement, withAttributes, withClasses, withContent } from './dom/create';
+export { setAttributes, removeAttributes } from './dom/attributes';
+export { addClass, removeClass, toggleClass, hasClass } from './dom/classes';
+
+// State Management
+export { createDisabled } from './state/disabled';
+export { createEventManager } from './state/events';
+export { createLifecycle } from './state/lifecycle';
+export { createEmitter } from './state/emitter';
+export { createStore } from './state/store';
+
+// Composition Utilities
+export { pipe, compose, transform } from './compose/pipe';
+export { createBase, withElement } from './compose/component';
+export {
+  withEvents,
+  withText,
+  withIcon,
+  withVariant,
+  withSize,
+  withPosition,
+  withDisabled,
+  withLifecycle,
+  withRipple
+} from './compose/features';
+
+// Utilities
+export { 
+  normalizeClasses, 
+  when, 
+  classNames as joinClasses, 
+  isObject, 
+  byString,
+  hasTouchSupport,
+  isMobileDevice,
+  normalizeEvent
+} from './utils';
+
+// Component feature interfaces for better developer experience
+export type { 
+  BaseComponent, 
+  ElementComponent, 
+  TouchState 
+} from './compose/component';
+
+export type {
+  EventComponent,
+  TextComponent,
+  IconComponent,
+  LifecycleComponent,
+  Lifecycle,
+  DisabledComponent,
+  DisabledManager,
+  RippleComponent
+} from './compose/features';
+
+// Other interfaces
+export type { 
+  CreateElementOptions 
+} from './dom/create';
+
+export type { 
+  TextManager, 
+  TextConfig 
+} from './build/text';
+
+export type { 
+  IconManager, 
+  IconConfig 
+} from './build/icon';
+
+export type { 
+  RippleController, 
+  RippleConfig 
+} from './build/ripple';
+
+export type { 
+  Emitter, 
+  EventCallback 
+} from './state/emitter';
+
+export type { 
+  DisabledState 
+} from './state/disabled';
+
+export type { 
+  NormalizedEvent 
+} from './utils/mobile';

package/src/core/state/disabled.ts

@@ -0,0 +1,81 @@
+// src/core/state/disabled.ts
+
+/**
+ * Disabled state manager interface
+ */
+export interface DisabledState {
+  /**
+   * Enables the element
+   * @returns DisabledState instance for chaining
+   */
+  enable(): DisabledState;
+  
+  /**
+   * Disables the element
+   * @returns DisabledState instance for chaining
+   */
+  disable(): DisabledState;
+  
+  /**
+   * Toggles the disabled state
+   * @returns DisabledState instance for chaining
+   */
+  toggle(): DisabledState;
+  
+  /**
+   * Checks if the element is disabled
+   * @returns true if disabled
+   */
+  isDisabled(): boolean;
+}
+
+/**
+ * Creates a controller for managing the disabled state of an element
+ * 
+ * @param element - The element to control
+ * @returns Disabled state controller
+ */
+export const createDisabled = (element: HTMLElement): DisabledState => {
+  return {
+    /**
+     * Enables the element
+     * @returns DisabledState instance for chaining
+     */
+    enable() {
+      (element as HTMLButtonElement | HTMLInputElement).disabled = false;
+      element.removeAttribute('disabled');
+      return this;
+    },
+
+    /**
+     * Disables the element
+     * @returns DisabledState instance for chaining
+     */
+    disable() {
+      (element as HTMLButtonElement | HTMLInputElement).disabled = true;
+      element.setAttribute('disabled', 'true');
+      return this;
+    },
+
+    /**
+     * Toggles the disabled state
+     * @returns DisabledState instance for chaining
+     */
+    toggle() {
+      if ((element as HTMLButtonElement | HTMLInputElement).disabled) {
+        this.enable();
+      } else {
+        this.disable();
+      }
+      return this;
+    },
+
+    /**
+     * Checks if the element is disabled
+     * @returns true if disabled
+     */
+    isDisabled() {
+      return (element as HTMLButtonElement | HTMLInputElement).disabled === true;
+    }
+  };
+};

package/src/core/state/emitter.ts

@@ -0,0 +1,94 @@
+// src/core/state/emitter.ts
+/**
+ * @module core/state
+ */
+
+/**
+ * Type definition for event callback functions
+ */
+export type EventCallback = (...args: any[]) => void;
+
+/**
+ * Interface for the event emitter
+ */
+export interface Emitter {
+  /**
+   * Subscribe to an event
+   * @param event - Event name
+   * @param callback - Event handler
+   * @returns Unsubscribe function
+   */
+  on(event: string, callback: EventCallback): () => void;
+  
+  /**
+   * Unsubscribe from an event
+   * @param event - Event name
+   * @param callback - Event handler to remove
+   */
+  off(event: string, callback: EventCallback): void;
+  
+  /**
+   * Emit an event
+   * @param event - Event name
+   * @param args - Event arguments
+   */
+  emit(event: string, ...args: any[]): void;
+  
+  /**
+   * Clear all event listeners
+   */
+  clear(): void;
+}
+
+/**
+ * Creates an event emitter with subscription management
+ * @returns Event emitter interface
+ */
+export const createEmitter = (): Emitter => {
+  const events = new Map<string, EventCallback[]>();
+
+  return {
+    /**
+     * Subscribe to an event
+     * @param event - Event name
+     * @param callback - Event handler
+     * @returns Unsubscribe function
+     */
+    on: (event: string, callback: EventCallback): (() => void) => {
+      const callbacks = events.get(event) || [];
+      events.set(event, [...callbacks, callback]);
+
+      return () => {
+        const callbacks = events.get(event) || [];
+        events.set(event, callbacks.filter(cb => cb !== callback));
+      };
+    },
+
+    /**
+     * Unsubscribe from an event
+     * @param event - Event name 
+     * @param callback - Event handler to remove
+     */
+    off(event: string, callback: EventCallback): void {
+      const callbacks = events.get(event) || [];
+      events.set(event, callbacks.filter(cb => cb !== callback));
+    },
+
+    /**
+     * Emit an event
+     * @param event - Event name
+     * @param args - Event arguments
+     */
+    emit: (event: string, ...args: any[]): void => {
+      const callbacks = events.get(event) || [];
+      callbacks.forEach(cb => cb(...args));
+    },
+
+    /**
+     * Clear all event listeners
+     */
+    clear: (): void => {
+      events.clear();
+    }
+  };
+};

package/src/core/state/events.ts

@@ -0,0 +1,88 @@
+// src/core/state/events.ts
+
+/**
+ * Event manager interface for handling component events
+ */
+export interface EventManagerState {
+  /**
+   * Adds an event listener
+   * @param event - Event name
+   * @param handler - Event handler
+   * @returns EventManagerState instance for chaining
+   */
+  on: (event: string, handler: (...args: any[]) => void) => EventManagerState;
+  
+  /**
+   * Removes an event listener
+   * @param event - Event name
+   * @param handler - Event handler
+   * @returns EventManagerState instance for chaining
+   */
+  off: (event: string, handler: (...args: any[]) => void) => EventManagerState;
+  
+  /**
+   * Removes all event listeners and cleans up
+   */
+  destroy: () => void;
+  
+  /**
+   * Gets all active handlers
+   * @returns Map of event names to handlers
+   */
+  getHandlers: () => Map<(...args: any[]) => void, string>;
+}
+
+/**
+ * Creates an event manager for a component
+ * Simple event handling mechanism for components
+ * 
+ * @param element - Component's DOM element
+ * @returns Event manager interface
+ */
+export const createEventManager = (element: HTMLElement): EventManagerState => {
+  const handlers = new Map<(...args: any[]) => void, string>();
+
+  return {
+    /**
+     * Adds an event listener
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns EventManagerState instance for chaining
+     */
+    on(event: string, handler: (...args: any[]) => void): EventManagerState {
+      element.addEventListener(event, handler as EventListener);
+      handlers.set(handler, event);
+      return this;
+    },
+
+    /**
+     * Removes an event listener
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns EventManagerState instance for chaining
+     */
+    off(event: string, handler: (...args: any[]) => void): EventManagerState {
+      element.removeEventListener(event, handler as EventListener);
+      handlers.delete(handler);
+      return this;
+    },
+
+    /**
+     * Removes all event listeners and cleans up
+     */
+    destroy(): void {
+      handlers.forEach((event, handler) => {
+        element.removeEventListener(event, handler as EventListener);
+      });
+      handlers.clear();
+    },
+
+    /**
+     * Gets all active handlers
+     * @returns Map of handlers to event names
+     */
+    getHandlers(): Map<(...args: any[]) => void, string> {
+      return new Map(handlers);
+    }
+  };
+};

package/src/core/state/index.ts

@@ -0,0 +1,16 @@
+// src/core/state/index.ts
+
+export { createEmitter } from './emitter';
+export type { Emitter, EventCallback } from './emitter';
+
+export { createStore, loggingMiddleware, deriveFiltered } from './store';
+export type { Store, StoreOptions, Selector, Computation, Updater } from './store';
+
+export { createLifecycle } from './lifecycle';
+export type { LifecycleManager, LifecycleManagers } from './lifecycle';
+
+export { createDisabled } from './disabled';
+export type { DisabledState } from './disabled';
+
+export { createEventManager } from './events';
+export type { EventManagerState } from './events';