mtrl 0.1.2 → 0.2.0

package/src/core/state/lifecycle.ts

@@ -0,0 +1,131 @@
+// src/core/state/lifecycle.ts
+
+import { createEmitter, Emitter } from './emitter';
+
+/**
+ * Component managers that can be managed by the lifecycle
+ */
+export interface LifecycleManagers {
+  events?: {
+    destroy: () => void;
+  };
+  text?: {
+    getElement: () => HTMLElement | null;
+  };
+  icon?: {
+    getElement: () => HTMLElement | null;
+  };
+  [key: string]: any;
+}
+
+/**
+ * Lifecycle manager interface
+ */
+export interface LifecycleManager {
+  /**
+   * Registers a handler for mount event
+   * @param handler - Function to call when component is mounted
+   * @returns Unsubscribe function
+   */
+  onMount: (handler: () => void) => () => void;
+  
+  /**
+   * Registers a handler for unmount event
+   * @param handler - Function to call when component is unmounted
+   * @returns Unsubscribe function
+   */
+  onUnmount: (handler: () => void) => () => void;
+  
+  /**
+   * Mounts the component
+   */
+  mount: () => void;
+  
+  /**
+   * Unmounts the component
+   */
+  unmount: () => void;
+  
+  /**
+   * Checks if component is mounted
+   * @returns true if mounted
+   */
+  isMounted: () => boolean;
+  
+  /**
+   * Destroys the component
+   */
+  destroy: () => void;
+}
+
+/**
+ * Creates a lifecycle manager for a component
+ * 
+ * @param element - Component's DOM element
+ * @param managers - Optional component managers to integrate with lifecycle
+ * @returns Lifecycle manager interface
+ */
+export const createLifecycle = (
+  element: HTMLElement, 
+  managers: LifecycleManagers = {}
+): LifecycleManager => {
+  let mounted = false;
+  const emitter: Emitter = createEmitter();
+
+  return {
+    // Mount/Unmount state management
+    onMount: (handler: () => void) => emitter.on('mount', handler),
+    onUnmount: (handler: () => void) => emitter.on('unmount', handler),
+    
+    mount: () => {
+      if (!mounted) {
+        mounted = true;
+        emitter.emit('mount');
+      }
+    },
+
+    unmount: () => {
+      if (mounted) {
+        mounted = false;
+        emitter.emit('unmount');
+        emitter.clear();
+      }
+    },
+
+    isMounted: () => mounted,
+
+    // Cleanup and destruction
+    destroy() {
+      // First trigger unmount
+      if (mounted) {
+        this.unmount();
+      }
+
+      // Clean up all event listeners
+      if (managers.events) {
+        managers.events.destroy();
+      }
+      
+      // Clean up text element
+      if (managers.text) {
+        const textElement = managers.text.getElement();
+        if (textElement) {
+          textElement.remove();
+        }
+      }
+      
+      // Clean up icon element
+      if (managers.icon) {
+        const iconElement = managers.icon.getElement();
+        if (iconElement) {
+          iconElement.remove();
+        }
+      }
+      
+      // Remove the main element
+      if (element) {
+        element.remove();
+      }
+    }
+  };
+};

package/src/core/state/store.ts

@@ -0,0 +1,197 @@
+// src/core/state/store.ts
+
+import { createEmitter, Emitter } from './emitter';
+
+/**
+ * State store options
+ */
+export interface StoreOptions<T> {
+  /**
+   * Middleware functions that process state changes
+   */
+  middleware?: Array<(newState: T, oldState: T) => T>;
+}
+
+/**
+ * State selector function type
+ */
+export type Selector<T, R> = (state: T) => R;
+
+/**
+ * State computation function type for derived state
+ */
+export type Computation<T, R> = (state: T) => R;
+
+/**
+ * State updater function type
+ */
+export type Updater<T> = (state: T) => T;
+
+/**
+ * State store interface
+ */
+export interface Store<T> {
+  /**
+   * Gets current state including derived values
+   * @returns Current state
+   */
+  getState: () => T;
+  
+  /**
+   * Updates state
+   * @param update - State update object or updater function
+   */
+  setState: (update: Partial<T> | Updater<T>) => void;
+  
+  /**
+   * Subscribes to state changes
+   * @param listener - Change listener
+   * @returns Unsubscribe function
+   */
+  subscribe: (listener: (state: T, oldState: T) => void) => () => void;
+  
+  /**
+   * Creates a derived state value
+   * @param key - Derived state key
+   * @param computation - Function to compute derived value
+   * @returns Function to remove derived state
+   */
+  derive: <K extends string, R>(key: K, computation: Computation<T, R>) => () => void;
+  
+  /**
+   * Selects a specific slice of state
+   * @param selector - State selector function
+   * @returns Selected state
+   */
+  select: <R>(selector: Selector<T, R>) => R;
+  
+  /**
+   * Resets state to initial values
+   */
+  reset: () => void;
+}
+
+/**
+ * Creates a state store with support for derived state and middleware
+ * 
+ * @param initialState - Initial state object
+ * @param options - Store options
+ * @returns State store interface
+ */
+export const createStore = <T extends Record<string, any>>(
+  initialState: T = {} as T, 
+  options: StoreOptions<T> = {}
+): Store<T> => {
+  let state = { ...initialState };
+  const emitter: Emitter = createEmitter();
+  const derivedStates = new Map<string, Computation<T, any>>();
+  const middleware = options.middleware || [];
+
+  const notifyListeners = (newState: T, oldState: T): void => {
+    emitter.emit('change', newState, oldState);
+  };
+
+  const applyMiddleware = (newState: T, oldState: T): T => {
+    return middleware.reduce((state, fn) => fn(state, oldState), newState);
+  };
+
+  return {
+    /**
+     * Gets current state including derived values
+     * @returns Current state
+     */
+    getState: (): T => {
+      const derivedValues: Record<string, any> = {};
+      derivedStates.forEach((compute, key) => {
+        derivedValues[key] = compute(state);
+      });
+      return { ...state, ...derivedValues };
+    },
+
+    /**
+     * Updates state
+     * @param update - State update object or updater function
+     */
+    setState: (update: Partial<T> | Updater<T>): void => {
+      const oldState = { ...state };
+      const newState = typeof update === 'function' 
+        ? update(state)
+        : { ...state, ...update };
+
+      state = applyMiddleware(newState as T, oldState);
+      notifyListeners(state, oldState);
+    },
+
+    /**
+     * Subscribes to state changes
+     * @param listener - Change listener
+     * @returns Unsubscribe function
+     */
+    subscribe: (listener: (state: T, oldState: T) => void): (() => void) => 
+      emitter.on('change', listener),
+
+    /**
+     * Creates a derived state value
+     * @param key - Derived state key
+     * @param computation - Function to compute derived value
+     * @returns Function to remove derived state
+     */
+    derive: <K extends string, R>(key: K, computation: Computation<T, R>): (() => void) => {
+      derivedStates.set(key, computation);
+      return () => {
+        derivedStates.delete(key);
+      };
+    },
+
+    /**
+     * Selects a specific slice of state
+     * @param selector - State selector function
+     * @returns Selected state
+     */
+    select: <R>(selector: Selector<T, R>): R => selector(state),
+
+    /**
+     * Resets state to initial values
+     */
+    reset: (): void => {
+      state = { ...initialState };
+      notifyListeners(state, {} as T);
+    }
+  };
+};
+
+/**
+ * Example middleware that logs state changes
+ * 
+ * @param newState - New state after change
+ * @param oldState - Previous state before change
+ * @returns Processed state (unchanged in this middleware)
+ */
+export const loggingMiddleware = <T extends Record<string, any>>(newState: T, oldState: T): T => {
+  console.log('State change:', { 
+    old: oldState, 
+    new: newState, 
+    diff: Object.keys(newState).reduce((acc, key) => {
+      if (newState[key] !== oldState[key]) {
+        acc[key] = { from: oldState[key], to: newState[key] };
+      }
+      return acc;
+    }, {} as Record<string, { from: any; to: any }>)
+  });
+  return newState;
+};
+
+/**
+ * Creates a derived state selector for filtering objects
+ * 
+ * @param predicate - Filter predicate function
+ * @returns Computation function for derived state
+ */
+export const deriveFiltered = <T>(predicate: (value: any, key: string) => boolean) => 
+  (state: Record<string, T>): Record<string, T> => 
+    Object.keys(state).reduce((acc, key) => {
+      if (predicate(state[key], key)) {
+        acc[key] = state[key];
+      }
+      return acc;
+    }, {} as Record<string, T>);

package/src/core/utils/index.ts

@@ -0,0 +1,45 @@
+// src/core/utils/index.ts
+
+export { isObject, byString } from './object';
+export { normalizeEvent, hasTouchSupport, TOUCH_CONFIG, PASSIVE_EVENTS } from './mobile';
+
+/**
+ * Normalizes class names by handling various input formats
+ * @param {...(string|string[])} classes - Classes to normalize
+ * @returns {string[]} 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 transformer that only runs if a condition is met
+ * @param {Function} predicate - Condition to check
+ * @param {Function} transformer - Transformer to run if condition is true
+ * @returns {Function} Conditional transformer
+ */
+export const when = <T, C>(
+  predicate: (obj: T, context: C) => boolean, 
+  transformer: (obj: T, context: C) => T
+) => 
+  (obj: T, context: C): T =>
+    predicate(obj, context) ? transformer(obj, context) : obj;
+
+/**
+ * Joins class names, filtering out falsy values
+ * @param {...(string | undefined | null | false)} classes - Class names to join
+ * @returns {string} Joined class names
+ */
+export const classNames = (...classes: (string | undefined | null | false)[]): string => 
+  classes.filter(Boolean).join(' ');

package/src/core/utils/{mobile.js → mobile.ts}

@@ -1,23 +1,40 @@
-// src/core/utils/mobile.js
+// src/core/utils/mobile.ts
 
 /**
  * Mobile device detection and capability checks
  * This provides a centralized way to handle mobile-specific features and behaviors
  */
 
+/**
+ * Interface for normalized event properties
+ */
+export interface NormalizedEvent {
+  clientX: number;
+  clientY: number;
+  pageX: number;
+  pageY: number;
+  target: EventTarget;
+  preventDefault: () => void;
+  stopPropagation: () => void;
+  type: string;
+}
+
 /**
  * Detects if the current device is likely a mobile device
  * Uses a combination of user agent and screen size checks for reliability
  */
-export const isMobileDevice = () => {
+export const isMobileDevice = (): boolean => {
   const userAgent = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
     navigator.userAgent
-  )
-  const screenSize = window.innerWidth <= 768
-  return userAgent || screenSize
-}
+  );
+  const screenSize = window.innerWidth <= 768;
+  return userAgent || screenSize;
+};
 
-export const PASSIVE_EVENTS = { passive: true }
+/**
+ * Options for passive event listeners
+ */
+export const PASSIVE_EVENTS: AddEventListenerOptions = { passive: true };
 
 /**
  * Configuration constants for mobile interactions
@@ -28,7 +45,7 @@ export const TOUCH_CONFIG = {
   FEEDBACK_DURATION: 200, // Duration of touch feedback animation in ms
   TAP_THRESHOLD: 250, // Maximum duration for a touch to be considered a tap
   SWIPE_THRESHOLD: 50 // Minimum distance for a touch to be considered a swipe
-}
+};
 
 /**
  * Accessibility-minded touch target sizes
@@ -38,37 +55,44 @@ export const TOUCH_TARGETS = {
   MINIMUM: 44, // Minimum recommended size in pixels
   COMFORTABLE: 48, // Comfortable touch target size
   LARGE: 56 // Large touch target for primary actions
-}
-
-/**
- * Default passive event configuration for touch events
- * Improves scroll performance on mobile devices
- */
+};
 
 /**
  * Detects if the current device supports touch events
  */
-export const hasTouchSupport = () => {
-  return 'ontouchstart' in window || navigator.maxTouchPoints > 0
-}
+export const hasTouchSupport = (): boolean => {
+  return 'ontouchstart' in window || navigator.maxTouchPoints > 0;
+};
 
 /**
  * Normalizes both mouse and touch events into a consistent format
  * This allows components to handle interactions uniformly
  */
-export const normalizeEvent = (event) => {
-  if (event.touches) {
-    const touch = event.touches[0]
+export const normalizeEvent = (event: Event): NormalizedEvent => {
+  if ('touches' in event && event.touches.length > 0) {
+    const touch = event.touches[0];
     return {
       clientX: touch.clientX,
       clientY: touch.clientY,
       pageX: touch.pageX,
       pageY: touch.pageY,
-      target: event.target,
+      target: event.target as EventTarget,
       preventDefault: () => event.preventDefault(),
       stopPropagation: () => event.stopPropagation(),
       type: event.type
-    }
+    };
   }
-  return event
-}
+  
+  // For mouse events
+  const mouseEvent = event as MouseEvent;
+  return {
+    clientX: mouseEvent.clientX,
+    clientY: mouseEvent.clientY,
+    pageX: mouseEvent.pageX,
+    pageY: mouseEvent.pageY,
+    target: mouseEvent.target as EventTarget,
+    preventDefault: () => mouseEvent.preventDefault(),
+    stopPropagation: () => mouseEvent.stopPropagation(),
+    type: mouseEvent.type
+  };
+};

package/src/core/utils/object.ts

@@ -0,0 +1,41 @@
+// src/core/utils/object.ts
+
+/**
+ * Checks if a value is a plain object
+ * @param value - The value to check
+ * @returns true if the value is a plain object
+ */
+export const isObject = (value: unknown): value is Record<string, any> => {
+  return Boolean(
+    value &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.getPrototypeOf({})
+  );
+};
+
+/**
+ * Accesses a nested property of an object using a string path
+ * @param obj - The object to traverse
+ * @param path - The property path (e.g. 'user.address.street')
+ * @returns The value at the specified path or undefined if not found
+ */
+export const byString = <T extends Record<string, any>, R = any>(obj: T, path: string): R | undefined => {
+  // Convert indexes to properties
+  const normalizedPath = path.replace(/\[(\w+)\]/g, '.$1');
+  // Strip a leading dot
+  const cleanPath = normalizedPath.replace(/^\./, '');
+  const keys = cleanPath.split('.');
+  
+  let result: any = obj;
+  
+  for (let i = 0, n = keys.length; i < n; ++i) {
+    const key = keys[i];
+    if (key in result) {
+      result = result[key];
+    } else {
+      return undefined;
+    }
+  }
+  
+  return result as R;
+};