mtrl 0.3.8 → 0.4.0

package/dist/core/layout/template.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module core/layout/template
+ * @description Template literal-based layout creation without compilation requirements
+ */
+/**
+ * Tagged template function for creating layouts
+ */
+export declare function html(strings: TemplateStringsArray, ...values: any[]): any;
+/**
+ * Creates a layout from a template literal
+ */
+export declare function createTemplateLayout(templateResult: any[], parentElement?: HTMLElement | null): import("./types").LayoutResult;

package/dist/core/layout/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @module core/layout
+ * @description Type definitions for layout creation system
+ */
+/**
+ * Layout configuration options
+ */
+export interface LayoutConfig {
+    /** Base layout type */
+    type?: 'stack' | 'row' | 'grid' | string;
+    /** Spacing between elements */
+    gap?: number | string;
+    /** Additional CSS classes */
+    class?: string;
+    /** Alignment of items along the cross axis */
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    /** Alignment of items along the main axis */
+    justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+    /** Whether and how items should wrap */
+    wrap?: boolean | 'reverse' | 'nowrap';
+    /** Whether row items should stack vertically on mobile */
+    mobileStack?: boolean;
+    /** Whether row items should scroll horizontally on mobile */
+    mobileScroll?: boolean;
+    /** Number of columns or automatic sizing method */
+    columns?: number | 'auto-fit' | 'auto-fill';
+    /** Minimum item width for grid layouts */
+    minWidth?: string | number;
+    /** Whether to use dense packing algorithm for grid */
+    dense?: boolean;
+    /** Whether grid items should adjust height automatically */
+    autoHeight?: boolean;
+}
+/**
+ * Configuration for individual layout items
+ */
+export interface LayoutItemConfig {
+    /** Column width in a 12-column grid */
+    width?: number;
+    /** Width on small screens */
+    sm?: number;
+    /** Width on medium screens */
+    md?: number;
+    /** Width on large screens */
+    lg?: number;
+    /** Width on extra-large screens */
+    xl?: number;
+    /** Number of grid columns to span */
+    span?: number;
+    /** Number of grid rows to span */
+    rowSpan?: number;
+    /** Display order */
+    order?: number | 'first' | 'last';
+    /** Self-alignment within container */
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    /** Whether item should automatically size */
+    auto?: boolean;
+}
+/**
+ * Interface for component-like objects
+ */
+export interface ComponentLike {
+    /** DOM element reference */
+    element: HTMLElement;
+    /** Optional method to clean up resources */
+    destroy?: () => void;
+    /** Allow additional properties */
+    [key: string]: any;
+}
+/**
+ * Extended options for element creation
+ */
+export interface ElementOptions extends Record<string, any> {
+    /** Layout configuration for the element */
+    layout?: LayoutConfig;
+    /** Layout item configuration */
+    layoutItem?: LayoutItemConfig;
+}
+/**
+ * Definition for a single element in the layout
+ */
+export interface ElementDefinition {
+    /** Optional name to reference the element */
+    name?: string;
+    /** Creator function that produces an HTMLElement or ComponentLike */
+    creator?: (options?: Record<string, any>) => HTMLElement | ComponentLike;
+    /** Options to pass to the creator function */
+    options?: ElementOptions;
+    /** Child elements to create and attach */
+    children?: Record<string, ElementDefinition>;
+}
+/**
+ * Schema for layout creation
+ */
+export interface Schema {
+    /** Root element definition */
+    element?: ElementDefinition;
+    /** Additional elements */
+    [key: string]: ElementDefinition | undefined;
+}
+/**
+ * Options for layout creation
+ */
+export interface LayoutOptions {
+    /** Default creator function to use if not specified in schema */
+    creator?: (options?: Record<string, any>) => HTMLElement | ComponentLike;
+    /** Whether to apply CSS class prefix @default true */
+    prefix?: boolean;
+    /** Additional options */
+    [key: string]: any;
+}
+/**
+ * Result object returned after creating a layout
+ */
+export interface LayoutResult {
+    /** The raw layout object with all components */
+    layout: Record<string, any>;
+    /** Reference to the root element for convenience */
+    element: HTMLElement | ComponentLike;
+    /** Flattened component map */
+    component: Record<string, any>;
+    /**
+     * Gets a component by name
+     * @param name - Component name
+     * @returns Component if found, null otherwise
+     */
+    get(name: string): any;
+    /**
+     * Gets all components in a flattened map
+     * @returns Object with all components
+     */
+    getAll(): Record<string, any>;
+    /**
+     * Destroys the layout, cleaning up all components
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * @module core/layout
+ * @description Utility functions for layout creation
+ */
+import { ComponentLike } from './types';
+/**
+ * Checks if a value is a component object (has an element property)
+ *
+ * @param value - Value to check
+ * @returns True if the value is a component-like object
+ */
+export declare function isComponent(value: any): value is ComponentLike;
+/**
+ * Creates a document fragment for faster DOM operations
+ *
+ * @returns New DocumentFragment
+ */
+export declare function createFragment(): DocumentFragment;
+/**
+ * Normalizes class values into an array of strings
+ */
+export declare function normalizeClasses(...classes: (string | string[])[]): string[];
+/**
+ * Processes className options to add prefix if needed
+ *
+ * @param options - Element options
+ * @param skipPrefix - Whether to skip adding prefixes
+ * @param useBEM - Whether to respect BEM naming conventions
+ * @returns Updated options with prefixed classNames
+ */
+export declare function processClassNames(options: Record<string, any>, skipPrefix?: boolean, useBEM?: boolean): Record<string, any>;
+/**
+ * Flattens a nested layout into a simple object with element and component references
+ *
+ * @param layout - Layout object
+ * @returns Flattened layout with all elements and components
+ */
+export declare function flattenLayout(layout: Record<string, any>): Record<string, any>;

package/dist/core/state/disabled.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare const createDisabled: (element: HTMLElement) => DisabledState;

package/dist/core/state/emitter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 declare const createEmitter: () => Emitter;

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

@@ -0,0 +1,36 @@
+/**
+ * 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 declare const createEventManager: (element: HTMLElement) => EventManagerState;

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

@@ -1,16 +1,10 @@
-// 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';
+export type { EventManagerState } from './events';

package/dist/core/state/lifecycle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare const createLifecycle: (element: HTMLElement, managers?: LifecycleManagers) => LifecycleManager;

package/dist/core/state/store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 declare const createStore: <T extends Record<string, any>>(initialState?: T, options?: StoreOptions<T>) => Store<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 declare const loggingMiddleware: <T extends Record<string, any>>(newState: T, oldState: T) => T;
+/**
+ * Creates a derived state selector for filtering objects
+ *
+ * @param predicate - Filter predicate function
+ * @returns Computation function for derived state
+ */
+export declare const deriveFiltered: <T>(predicate: (value: any, key: string) => boolean) => (state: Record<string, T>) => Record<string, T>;

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

@@ -0,0 +1,40 @@
+/**
+ * Result interface for background color lookup
+ */
+export interface BackgroundResult {
+    /** The computed background color value */
+    color: string;
+    /** The element from which the color was obtained */
+    element: HTMLElement | null;
+}
+/**
+ * Gets the computed background color of an element or its ancestors.
+ * Recursively traverses the DOM tree upward until it finds a non-transparent background.
+ * Resolves CSS variables if used in background color.
+ *
+ * @param {HTMLElement} element - The starting element to check
+ * @param {number} [maxDepth=20] - Maximum number of parent levels to check
+ * @returns {BackgroundResult} Object containing the color and source element
+ *
+ * @example
+ * // Get the inherited background color and its source element
+ * const { color, element: sourceElement } = getInheritedBackground(myElement);
+ * console.log(color); // 'rgb(255, 255, 255)' or '#1c2526' for dark mode
+ *
+ * // Observe the source element for changes
+ * if (sourceElement) {
+ *   const observer = new MutationObserver(() => {
+ *     const { color } = getInheritedBackground(myElement);
+ *     myElement.style.backgroundColor = color;
+ *   });
+ *
+ *   observer.observe(sourceElement, { attributes: true, attributeFilter: ['style', 'class'] });
+ * }
+ */
+export declare const getInheritedBackground: (element: HTMLElement, maxDepth?: number) => BackgroundResult;
+/**
+ * For backwards compatibility
+ * @deprecated Use getInheritedBackground instead
+ */
+export declare const getInheritedBG: (element: HTMLElement, maxDepth?: number) => string;
+export default getInheritedBackground;

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

@@ -0,0 +1,18 @@
+export { isObject, byString } from './object';
+export { normalizeEvent, hasTouchSupport, TOUCH_CONFIG, PASSIVE_EVENTS } from './mobile';
+export { getInheritedBackground } from './background';
+export { throttle, debounce, once } from './performance';
+export { getThemeColor } from './theme';
+/**
+ * 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 declare const when: <T, C>(predicate: (obj: T, context: C) => boolean, transformer: (obj: T, context: C) => T) => (obj: T, context: C) => T;
+/**
+ * Joins class names, filtering out falsy values
+ * @param {...(string | undefined | null | false)} classes - Class names to join
+ * @returns {string} Joined class names
+ */
+export declare const classNames: (...classes: (string | undefined | null | false)[]) => string;

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

@@ -0,0 +1,54 @@
+/**
+ * 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 declare const isMobileDevice: () => boolean;
+/**
+ * Options for passive event listeners
+ */
+export declare const PASSIVE_EVENTS: AddEventListenerOptions;
+/**
+ * Configuration constants for mobile interactions
+ * Following WCAG guidelines and touch interaction best practices
+ */
+export declare const TOUCH_CONFIG: {
+    TARGET_SIZE: number;
+    FEEDBACK_DURATION: number;
+    TAP_THRESHOLD: number;
+    SWIPE_THRESHOLD: number;
+};
+/**
+ * Accessibility-minded touch target sizes
+ * Based on WCAG guidelines for touch targets
+ */
+export declare const TOUCH_TARGETS: {
+    MINIMUM: number;
+    COMFORTABLE: number;
+    LARGE: number;
+};
+/**
+ * Detects if the current device supports touch events
+ */
+export declare const hasTouchSupport: () => boolean;
+/**
+ * Normalizes both mouse and touch events into a consistent format
+ * This allows components to handle interactions uniformly
+ */
+export declare const normalizeEvent: (event: Event) => NormalizedEvent;

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

@@ -0,0 +1,13 @@
+/**
+ * Checks if a value is a plain object
+ * @param value - The value to check
+ * @returns true if the value is a plain object
+ */
+export declare const isObject: (value: unknown) => value is Record<string, any>;
+/**
+ * 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 declare const byString: <T extends Record<string, any>, R = any>(obj: T, path: string) => R | undefined;

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

@@ -0,0 +1,79 @@
+/**
+ * @module core/utils/performance
+ * @description Performance utilities for optimizing high-frequency event handlers
+ */
+/**
+ * Creates a throttled function that only invokes the provided function
+ * at most once per every specified wait milliseconds.
+ *
+ * Throttling ensures that the function executes at a regular interval,
+ * which is useful for limiting the rate of execution for expensive operations.
+ *
+ * @param {Function} fn - The function to throttle
+ * @param {number} wait - The number of milliseconds to throttle invocations to
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.leading - Specify invoking on the leading edge of the timeout (default: true)
+ * @param {boolean} options.trailing - Specify invoking on the trailing edge of the timeout (default: true)
+ * @returns {Function} The throttled function
+ *
+ * @example
+ * // Throttle scroll handler to execute at most once every 100ms
+ * const throttledScroll = throttle((e) => {
+ *   updateScrollPosition(window.scrollY);
+ * }, 100);
+ *
+ * window.addEventListener('scroll', throttledScroll);
+ */
+export declare const throttle: <T extends (...args: any[]) => any>(fn: T, wait: number, options?: {
+    leading?: boolean;
+    trailing?: boolean;
+}) => ((...args: Parameters<T>) => void);
+/**
+ * Creates a debounced function that delays invoking the provided function
+ * until after the specified wait milliseconds have elapsed since the last time
+ * it was invoked.
+ *
+ * Debouncing groups multiple sequential calls into a single execution at the end,
+ * which is useful for handling rapid-fire events like resize or input.
+ *
+ * @param {Function} fn - The function to debounce
+ * @param {number} wait - The number of milliseconds to delay
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.leading - Specify invoking on the leading edge of the timeout (default: false)
+ * @param {boolean} options.maxWait - Maximum time function can be delayed before execution in milliseconds
+ * @returns {Function} The debounced function
+ *
+ * @example
+ * // Debounced search that executes 300ms after the user stops typing
+ * const debouncedSearch = debounce((query) => {
+ *   performSearch(query);
+ * }, 300);
+ *
+ * searchInput.addEventListener('input', (e) => {
+ *   debouncedSearch(e.target.value);
+ * });
+ */
+export declare const debounce: <T extends (...args: any[]) => any>(fn: T, wait: number, options?: {
+    leading?: boolean;
+    maxWait?: number;
+}) => ((...args: Parameters<T>) => void);
+/**
+ * Creates a function that is restricted to invoking the provided function once.
+ * Repeat calls to the function return the value of the first invocation.
+ *
+ * @param {Function} fn - The function to restrict
+ * @returns {Function} The restricted function
+ *
+ * @example
+ * // Initialize app only once
+ * const initApp = once(() => {
+ *   console.log('App initialized');
+ *   setupEventListeners();
+ *   loadInitialData();
+ * });
+ *
+ * // Can be called multiple times, but executes only once
+ * button1.addEventListener('click', initApp);
+ * button2.addEventListener('click', initApp);
+ */
+export declare const once: <T extends (...args: any[]) => any>(fn: T) => ((...args: Parameters<T>) => ReturnType<T>);