mtrl 0.3.8 → 0.4.0

package/{src/core/composition/index.ts → dist/core/composition/index.d.ts}

@@ -1,26 +1,16 @@
-// src/core/composition/index.ts
-
 /**
  * @module core/composition
  * @description Composition utilities for creating components using the structure-based approach
- * 
+ *
  * The composition module provides features that work with the structure definition
  * mechanism. Unlike traditional features that directly modify the DOM, these
  * features modify a layout schema that is later used to create DOM elements.
- * 
+ *
  * This approach provides several advantages:
  * - Clearer separation between layout and DOM creation
  * - More predictable component creation process
  * - Better support for server-side rendering
  * - Enhanced testability
  */
-
-// Export features
-export {
-  withLayout,
-  withDom,
-  withIcon,
-  withLabel,
-} from './features';
-
-export type { IconConfig, LabelConfig } from './features';
+export { withLayout, withDom, withIcon, withLabel, } from './features';
+export type { IconConfig, LabelConfig } from './features';

package/{src/core/config/component-config.ts → dist/core/config/component.d.ts}

@@ -1,136 +1,88 @@
-// src/core/config/component-config.ts
-import { PREFIX } from '../config';
-
 /**
  * Base component configuration interface
  * Common configuration properties shared by all components
  */
 export interface BaseComponentConfig {
-  componentName?: string;
-  prefix?: string;
-  class?: string;
-  [key: string]: any;
+    componentName?: string;
+    prefix?: string;
+    class?: string | string[];
+    className?: string | string[];
+    rawClass?: string | string[];
+    [key: string]: any;
 }
-
 /**
  * Creates a base configuration for any component
- * 
+ *
  * @param {BaseComponentConfig} defaults - Default configuration for the component
  * @param {BaseComponentConfig} userConfig - User provided configuration
  * @param {string} componentName - The name of the component
  * @returns {BaseComponentConfig} Complete configuration with defaults applied
- * 
+ *
  * @example
  * // In button/config.ts
- * export const createBaseConfig = (config: ButtonConfig = {}) => 
+ * export const createBaseConfig = (config: ButtonConfig = {}) =>
  *   createComponentConfig(defaultConfig, config, 'button');
  */
-export const createComponentConfig = (
-  defaults: BaseComponentConfig, 
-  userConfig: BaseComponentConfig = {}, 
-  componentName: string
-): BaseComponentConfig => {
-  // Create a new object with defaults and user config
-  const config = {
-    ...defaults,
-    ...userConfig,
-    // Force these values to ensure consistency
-    componentName,
-    prefix: PREFIX
-  };
-
-  return config;
-};
-
+export declare const createComponentConfig: (defaults: BaseComponentConfig, userConfig: BaseComponentConfig, componentName: string) => BaseComponentConfig;
 /**
  * Creates a class name with proper prefixing
- * 
+ *
  * @param {string} componentName - The name of the component
  * @param {string} [element] - Optional element name for BEM notation
  * @param {string} [modifier] - Optional modifier name for BEM notation
  * @returns {string} Properly formatted class name
- * 
+ *
  * @example
  * // Returns 'mtrl-button'
  * createClassName('button');
- * 
+ *
  * // Returns 'mtrl-button__icon'
  * createClassName('button', 'icon');
- * 
+ *
  * // Returns 'mtrl-button--primary'
  * createClassName('button', null, 'primary');
- * 
+ *
  * // Returns 'mtrl-button__icon--small'
  * createClassName('button', 'icon', 'small');
  */
-export const createClassName = (
-  componentName: string,
-  element?: string | null,
-  modifier?: string | null
-): string => {
-  let className = `${PREFIX}-${componentName}`;
-  
-  if (element) {
-    className += `__${element}`;
-  }
-  
-  if (modifier) {
-    className += `--${modifier}`;
-  }
-  
-  return className;
-};
-
+export declare const createClassName: (componentName: string, element?: string | null, modifier?: string | null) => string;
 /**
  * Processes class names for an element, handling arrays, nulls and conditional classes
- * 
+ *
  * @param {string | string[] | null} classNames - Class names to process
  * @returns {string} Space-separated class names as a string
- * 
+ *
  * @example
  * // Returns 'mtrl-card mtrl-card--elevated custom-class'
  * processClassNames(['mtrl-card', 'mtrl-card--elevated', 'custom-class']);
- * 
+ *
  * // Returns 'mtrl-card'
  * processClassNames(['mtrl-card', null, undefined]);
  */
-export const processClassNames = (classNames: string | string[] | null): string => {
-  if (!classNames) return '';
-  
-  if (typeof classNames === 'string') return classNames;
-  
-  return classNames
-    .filter(Boolean) // Remove null, undefined, empty strings
-    .join(' ');
-};
-
+export declare const processClassNames: (classNames: string | string[] | null) => string;
 /**
  * Creates a configuration object for withElement HOC
- * 
+ *
  * @param {BaseComponentConfig} config - Component configuration
  * @param {Object} options - Element options
  * @returns {Object} Configuration object for withElement
  */
-export const createElementConfig = (
-  config: BaseComponentConfig,
-  options: {
+export declare const createElementConfig: (config: BaseComponentConfig, options: {
     tag: string;
-    attrs?: Record<string, any>;
+    attributes?: Record<string, any>;
     className?: string | string[] | null;
     html?: string;
     text?: string;
-    forwardEvents?: Record<string, boolean | Function>;
+    forwardEvents?: Record<string, boolean | ((component: any, event: Event) => boolean)>;
     interactive?: boolean;
-  }
-) => {
-  return {
-    tag: options.tag,
-    componentName: config.componentName,
-    attrs: options.attrs || {},
-    className: options.className,
-    html: options.html,
-    text: options.text,
-    forwardEvents: options.forwardEvents || {},
-    interactive: options.interactive
-  };
-};
+}) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};

package/dist/core/config.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Library prefix used for all components
+ */
+export declare const PREFIX = "mtrl";
+/**
+ * Gets a prefixed component class name
+ * @param type - Component type
+ * @returns Prefixed class name
+ */
+export declare const getComponentClass: (type: string) => string;
+/**
+ * Gets a BEM modifier class name
+ * @param baseClass - Base class name
+ * @param modifier - Modifier name
+ * @returns Modifier class name
+ */
+export declare const getModifierClass: (baseClass: string, modifier: string) => string;
+/**
+ * Gets a BEM element class name
+ * @param baseClass - Base class name
+ * @param element - Element name
+ * @returns Element class name
+ */
+export declare const getElementClass: (baseClass: string, element: string) => string;
+/**
+ * Component type identifiers
+ */
+export declare enum COMPONENTS {
+    BUTTON = "button",
+    TEXTFIELD = "textfield",
+    CONTAINER = "container",
+    SNACKBAR = "snackbar",
+    SWITCH = "switch"
+}
+/**
+ * Theme configuration interface
+ */
+export interface ThemeConfig {
+    /**
+     * Theme name
+     */
+    name: string;
+    /**
+     * Theme CSS variables
+     */
+    variables: Record<string, string>;
+    /**
+     * Theme variants
+     */
+    variants: Record<string, any>;
+}
+/**
+ * Component configuration interface
+ */
+export interface ComponentConfig {
+    prefix: string;
+    type: string;
+    baseClass: string;
+    getClass: () => string;
+    getModifierClass: (modifier: string) => string;
+    getElementClass: (element: string) => string;
+    withTheme: (theme: string) => ThemedComponentConfig;
+    withVariants: (...variants: string[]) => VariantComponentConfig;
+    withStates: (...states: string[]) => StateComponentConfig;
+}
+/**
+ * Themed component configuration interface
+ */
+export interface ThemedComponentConfig extends ComponentConfig {
+    theme: string;
+    getThemeClass: (variant: string) => string;
+    getCssVariables: () => Record<string, string>;
+}
+/**
+ * Variant component configuration interface
+ */
+export interface VariantComponentConfig extends ComponentConfig {
+    variants: string[];
+    hasVariant: (variant: string) => boolean;
+    getVariantClass: (variant: string) => string | null;
+}
+/**
+ * State component configuration interface
+ */
+export interface StateComponentConfig extends ComponentConfig {
+    states: string[];
+    getStateClass: (state: string) => string | null;
+}
+/**
+ * Creates a component configuration object
+ * @param type - Component type
+ * @returns Component configuration interface
+ */
+export declare const createComponentConfig: (type: string) => ComponentConfig;
+/**
+ * Common component states
+ */
+export declare enum STATES {
+    DISABLED = "disabled",
+    FOCUSED = "focused",
+    ACTIVE = "active",
+    LOADING = "loading",
+    ERROR = "error"
+}
+/**
+ * CSS class generation utilities
+ */
+export declare const classNames: {
+    /**
+     * Creates a BEM-style class name
+     * @param block - Block name
+     * @param element - Element name
+     * @param modifier - Modifier name
+     * @returns BEM class name
+     */
+    bem: (block: string, element?: string, modifier?: string) => string;
+    /**
+     * Joins class names, filtering out falsy values
+     * @param classes - Class names to join
+     * @returns Joined class names
+     */
+    join: (...classes: (string | undefined | null | false)[]) => string;
+};
+/**
+ * Creates a themed component configuration
+ * @param type - Component type
+ * @param theme - Theme configuration
+ * @returns Themed component configuration
+ */
+export declare const createThemedComponent: (type: string, theme: ThemeConfig) => ThemedComponentConfig;

package/dist/core/dom/attributes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module core/dom
+ * @description DOM attribute helpers
+ */
+/**
+ * Sets attributes on an HTML element
+ *
+ * @param {HTMLElement} element - Element to set attributes on
+ * @param {Record<string, any>} attributes - Attributes to set
+ * @returns {HTMLElement} The element for chaining
+ */
+export declare const setAttributes: (element: HTMLElement, attributes?: Record<string, any>) => HTMLElement;
+/**
+ * Removes attributes from an HTML element
+ *
+ * @param {HTMLElement} element - Element to remove attributes from
+ * @param {string[]} attributes - Attributes to remove
+ * @returns {HTMLElement} The element for chaining
+ */
+export declare const removeAttributes: (element: HTMLElement, attributes?: string[]) => HTMLElement;

package/dist/core/dom/classes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module core/dom
+ * @description DOM manipulation utilities optimized for performance
+ */
+/**
+ * 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 declare const normalizeClasses: (...classes: (string | string[])[]) => string[];
+/**
+ * Adds multiple classes to an element
+ * Automatically adds prefix to classes that don't already have it
+ * Optimized for minimal array operations and DOM interactions
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to add
+ * @returns {HTMLElement} Modified element
+ */
+export declare const addClass: (element: HTMLElement, ...classes: (string | string[])[]) => HTMLElement;
+/**
+ * Removes multiple classes from an element
+ * Handles only exact class names as specified (no automatic prefixing)
+ * For better performance, clients should know exactly which classes to remove
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to remove
+ * @returns {HTMLElement} Modified element
+ */
+export declare const removeClass: (element: HTMLElement, ...classes: (string | string[])[]) => HTMLElement;
+/**
+ * Toggles multiple classes on an element
+ * Automatically adds prefix to classes that don't already have it
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to toggle
+ * @returns {HTMLElement} Modified element
+ */
+export declare const toggleClass: (element: HTMLElement, ...classes: (string | string[])[]) => HTMLElement;
+/**
+ * Checks if an element has all specified classes
+ * Automatically adds prefix to classes that don't already have it
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to check
+ * @returns {boolean} True if element has all specified classes
+ */
+export declare const hasClass: (element: HTMLElement, ...classes: (string | string[])[]) => boolean;

package/dist/core/dom/create.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @module core/dom
+ * @description DOM manipulation utilities
+ */
+/**
+ * Event handler function type
+ */
+export type EventHandler = (event: Event) => void;
+/**
+ * Event condition type - either a boolean or a function that returns a boolean
+ */
+export type EventCondition = boolean | ((context: any, event: Event) => boolean);
+/**
+ * Element type that can be either HTMLElement or SVGElement
+ */
+export type DOMElement = HTMLElement | SVGElement;
+/**
+ * Options for element creation
+ */
+export interface CreateElementOptions {
+    /**
+     * HTML tag name
+     */
+    tag?: string;
+    /**
+     * Container to append element to
+     */
+    container?: HTMLElement | null;
+    /**
+     * Inner HTML content
+     */
+    html?: string;
+    /**
+     * Text content
+     */
+    text?: string;
+    /**
+     * Element ID
+     */
+    id?: string;
+    /**
+     * Element ariaLabel
+     */
+    ariaLabel?: string;
+    /**
+     * Dataset attributes
+     */
+    data?: Record<string, string>;
+    /**
+     * CSS classes (will be automatically prefixed with 'mtrl-')
+     * Alias for 'className'
+     */
+    class?: string | string[];
+    /**
+     * CSS classes (will be automatically prefixed with 'mtrl-')
+     * Alias for 'class'
+     */
+    className?: string | string[];
+    /**
+     * CSS classes that will NOT be prefixed
+     * Added as-is to the element
+     */
+    rawClass?: string | string[];
+    /**
+     * HTML attributes
+     */
+    attributes?: Record<string, any>;
+    /**
+     * Events to forward when component has emit method
+     */
+    forwardEvents?: Record<string, EventCondition>;
+    /**
+     * Callback after element creation
+     */
+    onCreate?: (element: HTMLElement, context?: any) => void;
+    /**
+     * Component context
+     */
+    context?: any;
+    /**
+     * Additional attributes
+     */
+    [key: string]: any;
+}
+/**
+ * Options for SVG element creation, extends regular element options
+ */
+export interface CreateSVGElementOptions extends Omit<CreateElementOptions, 'container' | 'onCreate'> {
+    /**
+     * Container to append element to
+     */
+    container?: DOMElement | null;
+    /**
+     * Callback after element creation
+     */
+    onCreate?: (element: SVGElement, context?: any) => void;
+}
+/**
+ * Event handler storage to facilitate cleanup
+ */
+export interface EventHandlerStorage {
+    [eventName: string]: EventHandler;
+}
+/**
+ * Creates an HTML element with the specified options
+ *
+ * @param {CreateElementOptions} options - Element creation options
+ * @returns {HTMLElement} Created HTML element
+ */
+export declare const createElement: (options?: CreateElementOptions) => HTMLElement;
+/**
+ * Creates an SVG element with the specified options
+ *
+ * @param {CreateSVGElementOptions} options - SVG element creation options
+ * @returns {SVGElement} Created SVG element
+ */
+export declare const createSVGElement: (options?: CreateSVGElementOptions) => SVGElement;
+/**
+ * Removes event handlers from an element
+ * @param element - Element to cleanup
+ */
+export declare const removeEventHandlers: (element: HTMLElement | SVGElement) => void;
+/**
+ * Higher-order function to add attributes to an element
+ * @param {Record<string, any>} attributes - Attributes to add
+ * @returns {(element: HTMLElement) => HTMLElement} Element transformer
+ */
+export declare const withAttributes: (attributes: Record<string, any>) => (element: HTMLElement) => HTMLElement;
+/**
+ * Higher-order function to add classes to an element
+ * @param {...(string | string[])} classes - Classes to add
+ * @returns {(element: HTMLElement) => HTMLElement} Element transformer
+ */
+export declare const withClasses: (...classes: (string | string[])[]) => (element: HTMLElement) => HTMLElement;
+/**
+ * Higher-order function to add content to an element
+ * @param {Node|string} content - Content to add
+ * @returns {(element: HTMLElement) => HTMLElement} Element transformer
+ */
+export declare const withContent: (content: Node | string) => (element: HTMLElement) => HTMLElement;
+declare global {
+    interface HTMLElement {
+        /**
+         * Storage for event handlers to enable cleanup
+         */
+        __eventHandlers?: EventHandlerStorage;
+    }
+    interface SVGElement {
+        /**
+         * Storage for event handlers to enable cleanup
+         */
+        __eventHandlers?: EventHandlerStorage;
+    }
+}

package/dist/core/dom/events.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @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 declare const createEventManager: (element: HTMLElement) => EventManager;
+export {};

package/dist/core/dom/index.d.ts

@@ -0,0 +1,6 @@
+export { createElement, createSVGElement } from './create';
+export type { CreateElementOptions } from './create';
+export { setAttributes, removeAttributes } from './attributes';
+export { addClass, removeClass, toggleClass, hasClass, normalizeClasses } from './classes';
+export { createEventManager } from './events';
+export type { EventManager } from './events';

package/dist/core/dom/utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 declare const normalizeClasses: (...classes: (string | string[])[]) => string[];
+/**
+ * Creates a DOM element with attributes
+ *
+ * @param tag - Element tag name
+ * @param attributes - Element attributes
+ * @returns Created element
+ */
+export declare const createElement: <T extends HTMLElement>(tag: string, attributes?: Record<string, any>) => T;
+/**
+ * Sets inline styles on an element
+ *
+ * @param element - Target element
+ * @param styles - Styles to set
+ * @returns Modified element
+ */
+export declare const setStyles: <T extends HTMLElement>(element: T, styles: Partial<CSSStyleDeclaration>) => T;
+/**
+ * Checks if an element matches a selector
+ *
+ * @param element - Element to check
+ * @param selector - CSS selector
+ * @returns Whether element matches selector
+ */
+export declare const matches: (element: Element, selector: string) => boolean;
+/**
+ * Finds the closest ancestor matching a selector
+ *
+ * @param element - Starting element
+ * @param selector - CSS selector
+ * @returns Matching ancestor or null
+ */
+export declare const closest: <T extends HTMLElement>(element: Element, selector: string) => T | null;

package/dist/core/gestures/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module core/gestures
+ * @description Modular gesture recognition system for touch and mouse interactions
+ */
+export { createGestureManager, GESTURE_TYPES, SWIPE_DIRECTIONS } from './manager';
+export { detectTap } from './tap';
+export { detectSwipe } from './swipe';
+export { detectLongPress } from './longpress';
+export { detectPinch } from './pinch';
+export { detectRotate } from './rotate';
+export { detectPan } from './pan';
+export type { GestureManager, GestureConfig, GestureEvent, TapEvent, SwipeEvent, LongPressEvent, PinchEvent, RotateEvent, PanEvent, AnyGestureEvent, GestureHandler, GestureState, GestureDetectionContext } from './types';