material 1.0.4 → 3.0.0-next.1

package/dist/core/config/global.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Lightweight Global Configuration System for mtrl
+ *
+ * This system allows setting default configurations for all components
+ * without adding complexity or performance overhead.
+ */
+export interface ComponentConfigMap {
+}
+/**
+ * Sets global defaults for a specific component
+ *
+ * @param component - Component name
+ * @param config - Default configuration to apply
+ *
+ * @example
+ * ```typescript
+ * // Set all buttons to be square by default
+ * setComponentDefaults('button', {
+ *   shape: 'square',
+ *   size: 'm'
+ * });
+ * ```
+ */
+export declare function setComponentDefaults<K extends keyof ComponentConfigMap>(component: K, config: ComponentConfigMap[K]): void;
+/**
+ * Gets global defaults for a component
+ *
+ * @param component - Component name
+ * @returns Component defaults or empty object
+ */
+export declare function getComponentDefaults<K extends keyof ComponentConfigMap>(component: K): ComponentConfigMap[K];
+/**
+ * Sets global defaults for multiple components at once
+ *
+ * @param configs - Map of component names to their default configs
+ *
+ * @example
+ * ```typescript
+ * setGlobalDefaults({
+ *   button: { shape: 'square', size: 'm' },
+ *   "text-field": { variant: 'outlined' }
+ * });
+ * ```
+ */
+export declare function setGlobalDefaults(configs: Partial<ComponentConfigMap>): void;
+/**
+ * Clears all global defaults
+ */
+export declare function clearGlobalDefaults(): void;

package/dist/core/config/global.js

@@ -0,0 +1,15 @@
+const configStore = {};
+export function setComponentDefaults(component, config) {
+    configStore[component] = config;
+}
+export function getComponentDefaults(component) {
+    return configStore[component] || {};
+}
+export function setGlobalDefaults(configs) {
+    Object.assign(configStore, configs);
+}
+export function clearGlobalDefaults() {
+    Object.keys(configStore).forEach(key => {
+        delete configStore[key];
+    });
+}

package/dist/core/config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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;
+/**
+ * Theme configuration interface
+ */
+export interface ThemeConfig {
+    /**
+     * Theme name
+     */
+    name: string;
+    /**
+     * Theme CSS variables
+     */
+    variables: Record<string, string>;
+    /**
+     * Theme variants
+     */
+    variants: Record<string, unknown>;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+};

package/dist/core/config.js

@@ -0,0 +1,15 @@
+export const PREFIX = 'mtrl';
+export const getComponentClass = (type) => `${PREFIX}-${type}`;
+export const getModifierClass = (baseClass, modifier) => `${baseClass}--${modifier}`;
+export const getElementClass = (baseClass, element) => `${baseClass}__${element}`;
+export const classNames = {
+    bem: (block, element, modifier) => {
+        let className = block;
+        if (element)
+            className += `-${element}`;
+        if (modifier)
+            className += `--${modifier}`;
+        return className;
+    },
+    join: (...classes) => classes.filter(Boolean).join(' ')
+};

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

@@ -0,0 +1,50 @@
+/**
+ * @module core/dom
+ * @description DOM attribute helpers
+ */
+/**
+ * Set attributes on an element with performance optimizations
+ * Fast path for single attribute, efficient iteration for multiple
+ *
+ * @param {HTMLElement | SVGElement} element - Element to set attributes on
+ * @param {object} attributes - Attributes to set
+ * @returns {HTMLElement | SVGElement} The element for chaining
+ */
+export declare const setAttributes: <E extends HTMLElement | SVGElement>(element: E, attributes?: object) => E;
+/**
+ * Remove attributes from an element
+ * Standard for loop is fastest for array iteration
+ *
+ * @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;
+/**
+ * Batch attribute operations for better performance when setting many attributes
+ * Single pass through operations array for optimal performance
+ *
+ * @param {HTMLElement} element - Element to modify
+ * @param {Array<{action: "set" | "remove", key: string, value?: unknown}>} operations - Array of attribute operations
+ * @returns {HTMLElement} The element for chaining
+ */
+export declare const batchAttributes: (element: HTMLElement, operations: Array<{
+    action: "set" | "remove";
+    key: string;
+    value?: unknown;
+}>) => HTMLElement;
+/**
+ * Check if element has attribute
+ * @param element - Element to check
+ * @param attribute - Attribute name to check
+ * @returns True if element has the attribute
+ */
+export declare const hasAttribute: (element: HTMLElement, attribute: string) => boolean;
+/**
+ * Get attribute value with default
+ * @param element - Element to get attribute from
+ * @param attribute - Attribute name
+ * @param defaultValue - Default value if attribute doesn't exist
+ * @returns Attribute value or default
+ */
+export declare const getAttribute: (element: HTMLElement, attribute: string, defaultValue?: string) => string;

package/dist/core/dom/attributes.js

@@ -0,0 +1,48 @@
+import { omitsAttribute } from "../utils/attributes.js";
+import { safeUrl, URL_ATTRIBUTES } from "../utils/url.js";
+export const setAttributes = (element, attributes = {}) => {
+    if (!attributes)
+        return element;
+    const values = attributes;
+    const attributeValue = (key, value) => URL_ATTRIBUTES.has(key.toLowerCase()) ? safeUrl(String(value)) : String(value);
+    const keys = Object.keys(attributes);
+    if (keys.length === 1) {
+        const value = values[keys[0]];
+        if (value != null &&
+            keys[0] !== "style" &&
+            !omitsAttribute(keys[0], value)) {
+            element.setAttribute(keys[0], attributeValue(keys[0], value));
+        }
+        return element;
+    }
+    for (const key in attributes) {
+        const value = values[key];
+        if (value != null && key !== "style" && !omitsAttribute(key, value)) {
+            element.setAttribute(key, attributeValue(key, value));
+        }
+    }
+    return element;
+};
+export const removeAttributes = (element, attributes = []) => {
+    for (let i = 0; i < attributes.length; i++) {
+        element.removeAttribute(attributes[i]);
+    }
+    return element;
+};
+export const batchAttributes = (element, operations) => {
+    for (let i = 0; i < operations.length; i++) {
+        const op = operations[i];
+        if (op.action === "set" &&
+            op.value != null &&
+            op.key !== "style" &&
+            !omitsAttribute(op.key, op.value)) {
+            element.setAttribute(op.key, URL_ATTRIBUTES.has(op.key.toLowerCase()) ? safeUrl(String(op.value)) : String(op.value));
+        }
+        else if (op.action === "remove") {
+            element.removeAttribute(op.key);
+        }
+    }
+    return element;
+};
+export const hasAttribute = (element, attribute) => element.hasAttribute(attribute);
+export const getAttribute = (element, attribute, defaultValue = "") => element.getAttribute(attribute) ?? defaultValue;

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

@@ -0,0 +1,54 @@
+/**
+ * @module core/dom
+ * @description DOM manipulation utilities optimized for performance
+ */
+/**
+ * Normalize classes to array of unique strings with optimization and caching
+ * - String with space-separated classes
+ * - Array of strings
+ * - Mixed array of strings and space-separated classes
+ *
+ * @param {...(string | string[])} classes - Classes to normalize
+ * @returns {string[]} Array of unique, non-empty class names
+ */
+export declare const normalizeClasses: (...classes: (string | string[])[]) => string[];
+/**
+ * Add prefixed classes to element with optimizations
+ * Automatically adds prefix to classes that don't already have it
+ * Optimized for minimal DOM interactions and single-class scenarios
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to add
+ * @returns {HTMLElement} Modified element for chaining
+ */
+export declare const addClass: (element: HTMLElement, ...classes: (string | string[])[]) => HTMLElement;
+/**
+ * Remove prefixed classes from element with optimizations
+ * Handles exact class names as specified with automatic prefixing
+ * Optimized for single-class scenarios and batch operations
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to remove
+ * @returns {HTMLElement} Modified element for chaining
+ */
+export declare const removeClass: (element: HTMLElement, ...classes: (string | string[])[]) => HTMLElement;
+/**
+ * Toggle prefixed classes on element with optimizations
+ * Automatically adds prefix to classes that don't already have it
+ * Optimized for single-class scenarios
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {...(string | string[])} classes - Classes to toggle
+ * @returns {HTMLElement} Modified element for chaining
+ */
+export declare const toggleClass: (element: HTMLElement, ...classes: (string | string[])[]) => HTMLElement;
+/**
+ * Check if element has all specified prefixed classes with optimizations
+ * Automatically adds prefix to classes that don't already have it
+ * Returns true only if ALL specified classes are present
+ *
+ * @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/classes.js

@@ -0,0 +1,189 @@
+const classCache = new Map();
+const MAX_CACHE_SIZE = 500;
+export const normalizeClasses = (...classes) => {
+    if (classes.length === 0)
+        return [];
+    if (classes.length === 1 && typeof classes[0] === "string") {
+        const input = classes[0];
+        if (!input)
+            return [];
+        if (!input.includes(" "))
+            return [input];
+        if (classCache.has(input)) {
+            return classCache.get(input);
+        }
+    }
+    const seen = new Set();
+    const result = [];
+    for (const cls of classes) {
+        if (typeof cls === "string" && cls) {
+            if (!cls.includes(" ")) {
+                if (!seen.has(cls)) {
+                    seen.add(cls);
+                    result.push(cls);
+                }
+            }
+            else {
+                cls.split(" ").forEach((c) => {
+                    const trimmed = c.trim();
+                    if (trimmed && !seen.has(trimmed)) {
+                        seen.add(trimmed);
+                        result.push(trimmed);
+                    }
+                });
+            }
+        }
+        else if (Array.isArray(cls)) {
+            cls.forEach((c) => {
+                if (typeof c === "string" && c) {
+                    c.split(" ").forEach((part) => {
+                        const trimmed = part.trim();
+                        if (trimmed && !seen.has(trimmed)) {
+                            seen.add(trimmed);
+                            result.push(trimmed);
+                        }
+                    });
+                }
+            });
+        }
+    }
+    if (classes.length === 1 &&
+        typeof classes[0] === "string" &&
+        result.length <= 10) {
+        if (classCache.size < MAX_CACHE_SIZE) {
+            classCache.set(classes[0], result);
+        }
+    }
+    return result;
+};
+export const addClass = (element, ...classes) => {
+    if (classes.length === 0)
+        return element;
+    if (classes.length === 1 && Array.isArray(classes[0])) {
+        return addClass(element, ...classes[0]);
+    }
+    if (classes.length === 1 && typeof classes[0] === "string") {
+        const cls = classes[0];
+        if (cls && !cls.includes(" ")) {
+            const prefixed = cls;
+            if (!prefixed.includes(" ")) {
+                element.classList.add(prefixed);
+                return element;
+            }
+        }
+    }
+    const normalized = normalizeClasses(...classes);
+    for (const cls of normalized) {
+        const prefixed = cls;
+        if (prefixed.includes(" ")) {
+            prefixed.split(" ").forEach((c) => {
+                const trimmed = c.trim();
+                if (trimmed)
+                    element.classList.add(trimmed);
+            });
+        }
+        else {
+            element.classList.add(prefixed);
+        }
+    }
+    return element;
+};
+export const removeClass = (element, ...classes) => {
+    if (classes.length === 0)
+        return element;
+    if (classes.length === 1 && Array.isArray(classes[0])) {
+        return removeClass(element, ...classes[0]);
+    }
+    if (classes.length === 1 && typeof classes[0] === "string") {
+        const cls = classes[0];
+        if (cls && !cls.includes(" ")) {
+            const prefixed = cls;
+            if (!prefixed.includes(" ")) {
+                element.classList.remove(prefixed);
+                return element;
+            }
+        }
+    }
+    const normalized = normalizeClasses(...classes);
+    for (const cls of normalized) {
+        const prefixed = cls;
+        if (prefixed.includes(" ")) {
+            prefixed.split(" ").forEach((c) => {
+                const trimmed = c.trim();
+                if (trimmed)
+                    element.classList.remove(trimmed);
+            });
+        }
+        else {
+            element.classList.remove(prefixed);
+        }
+    }
+    return element;
+};
+export const toggleClass = (element, ...classes) => {
+    if (classes.length === 1 && Array.isArray(classes[0])) {
+        return toggleClass(element, ...classes[0]);
+    }
+    if (classes.length === 1 && typeof classes[0] === "string") {
+        const cls = classes[0];
+        if (cls && !cls.includes(" ")) {
+            const prefixed = cls;
+            if (!prefixed.includes(" ")) {
+                element.classList.toggle(prefixed);
+                return element;
+            }
+        }
+    }
+    const normalized = normalizeClasses(...classes);
+    for (const cls of normalized) {
+        const prefixed = cls;
+        if (prefixed.includes(" ")) {
+            prefixed.split(" ").forEach((c) => {
+                const trimmed = c.trim();
+                if (trimmed)
+                    element.classList.toggle(trimmed);
+            });
+        }
+        else {
+            element.classList.toggle(prefixed);
+        }
+    }
+    return element;
+};
+export const hasClass = (element, ...classes) => {
+    if (classes.length === 0)
+        return true;
+    if (classes.length === 1 && Array.isArray(classes[0])) {
+        return hasClass(element, ...classes[0]);
+    }
+    if (classes.length === 1 && typeof classes[0] === "string") {
+        const cls = classes[0];
+        if (cls && !cls.includes(" ")) {
+            const prefixed = cls;
+            if (!prefixed.includes(" ")) {
+                return element.classList.contains(prefixed);
+            }
+        }
+    }
+    const normalized = normalizeClasses(...classes);
+    for (const cls of normalized) {
+        const prefixed = cls;
+        if (prefixed.includes(" ")) {
+            const tokens = prefixed
+                .split(" ")
+                .map((c) => c.trim())
+                .filter(Boolean);
+            for (const token of tokens) {
+                if (!element.classList.contains(token)) {
+                    return false;
+                }
+            }
+        }
+        else {
+            if (!element.classList.contains(prefixed)) {
+                return false;
+            }
+        }
+    }
+    return true;
+};

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

@@ -0,0 +1,157 @@
+/**
+ * @module core/dom
+ * @description DOM manipulation utilities
+ */
+/**
+ * Event handler function type
+ */
+export type EventHandler = (event: Event) => void;
+/**
+ * Element type that can be either HTMLElement or SVGElement
+ */
+export type DOMElement = HTMLElement | SVGElement;
+/**
+ * Component context passed to created elements for event forwarding
+ */
+export interface ElementContext {
+    /** Emits forwarded events */
+    emit?(event: string, data: ForwardedEventPayload): void;
+    /** Subscribes to events */
+    on?(event: string, handler: (...args: unknown[]) => void): unknown;
+}
+/**
+ * Event condition type
+ * Declared through a method signature so conditions typed for a specific
+ * component or event subtype stay assignable under strictFunctionTypes
+ */
+export type EventCondition = boolean | {
+    condition(context: ElementContext & {
+        element: DOMElement;
+    }, event: Event): boolean;
+}["condition"];
+/**
+ * Options for element creation with comprehensive configuration
+ */
+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;
+    /** Form element name */
+    name?: string;
+    /** Element title (native browser tooltip on hover) */
+    title?: string;
+    /** Keyboard navigation order (-1 to remove from tab order, 0+ for custom order) */
+    tabIndex?: number;
+    /** Inline styles (string or object) */
+    /**
+     * Inline styles. Object only: a style string is written verbatim to the
+     * style attribute, so one interpolated value can carry extra declarations
+     * (FLO-111). Assigning per property confines a value to that property.
+     */
+    style?: Partial<CSSStyleDeclaration>;
+    /** Dataset attributes (e.g., { name: 'value' } → data-name="value") */
+    data?: Record<string, string>;
+    /** ARIA role (e.g., 'button', 'menuitem', 'dialog') */
+    role?: string;
+    /** Accessible label for screen readers */
+    ariaLabel?: string;
+    /** ID of element that describes this element */
+    ariaDescribedBy?: string;
+    /** ID of element that labels this element */
+    ariaLabelledBy?: string;
+    /** Hide from screen readers */
+    ariaHidden?: boolean;
+    /** 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[];
+    /** HTML attributes */
+    attributes?: object;
+    /** Events to forward when component has emit method */
+    forwardEvents?: Record<string, EventCondition>;
+    /** Callback after element creation */
+    onCreate?(element: HTMLElement, context?: ElementContext): void;
+    /** Component context */
+    context?: ElementContext & object;
+}
+/**
+ * Options for SVG element creation
+ */
+export interface CreateSVGElementOptions extends Omit<CreateElementOptions, "container" | "onCreate"> {
+    container?: DOMElement | null;
+    onCreate?(element: SVGElement, context?: ElementContext): void;
+}
+/**
+ * Event handler storage
+ */
+export interface EventHandlerStorage {
+    [eventName: string]: EventHandler;
+}
+/**
+ * What `forwardEvents` hands the component's emitter.
+ *
+ * One shape for every forwarded native event, emitted by `setupEventForwarding`
+ * below as `{ event, element, originalEvent: event }`. Eleven components
+ * configure `forwardEvents`, so this lives here rather than being redeclared
+ * per component: FLO-114 gives each component a typed event map, and without
+ * a shared payload that would mean the same three fields written out again in
+ * every one of them.
+ *
+ * `event` and `originalEvent` are the same object. Both names have always
+ * been provided and consumers use both, so neither is removed here.
+ * The default root covers HTML and SVG; component event maps can specialize
+ * it to their actual element type.
+ */
+export interface ForwardedEventPayload<E extends Event = Event, TElement extends DOMElement = DOMElement> {
+    /** The DOM event that triggered the forward. */
+    event: E;
+    /** The element the listener is attached to, which is the component root. */
+    element: TElement;
+    /** The same DOM event as `event`. */
+    originalEvent: E;
+}
+/**
+ * Create an HTML element with comprehensive options and optimizations
+ * Fast paths for common scenarios, full feature support for complex cases
+ *
+ * @param {CreateElementOptions} options - Element creation options
+ * @returns {HTMLElement} Created HTML element
+ */
+export declare const createElement: (options?: CreateElementOptions) => HTMLElement;
+/**
+ * Create a pooled HTML element
+ * @param options - Element creation options
+ * @returns Created HTML element from pool
+ */
+export declare const createElementPooled: (options?: CreateElementOptions) => HTMLElement;
+/**
+ * Release an element back to the pool
+ * @param element - Element to release
+ */
+export declare const releaseElement: (element: HTMLElement) => void;
+/**
+ * Create an SVG element
+ * @param options - SVG element creation options
+ * @returns Created SVG element
+ */
+export declare const createSVGElement: (options?: CreateSVGElementOptions) => SVGElement;
+/**
+ * Remove event handlers from an element
+ * @param element - Element to clean up
+ */
+export declare const removeEventHandlers: (element: HTMLElement | SVGElement) => void;
+declare global {
+    interface HTMLElement {
+        __eventHandlers?: EventHandlerStorage;
+    }
+    interface SVGElement {
+        __eventHandlers?: EventHandlerStorage;
+    }
+}