material 1.0.4 → 3.0.0-next.0

package/dist/core/compose/features/debounce.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module core/compose/features
+ * @description Adds debounced event handling capabilities to components
+ */
+import { BaseComponent, ElementComponent } from "../component.js";
+/**
+ * Interface for components with lifecycle
+ */
+export interface ComponentWithLifecycle extends ElementComponent {
+    lifecycle: {
+        destroy: () => void;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Configuration for debounced event handlers
+ */
+export interface DebounceConfig {
+    /**
+     * Event handlers with debounce settings
+     */
+    debouncedEvents?: Record<string, {
+        handler: (event: Event) => void;
+        wait: number;
+        options?: {
+            leading?: boolean;
+            maxWait?: number;
+        };
+    }>;
+}
+/**
+ * Component with debounced event capabilities
+ */
+export interface DebounceComponent extends BaseComponent {
+    /**
+     * Adds a debounced event listener
+     * @param event - Event name
+     * @param handler - Event handler
+     * @param wait - Debounce delay in milliseconds
+     * @param options - Debounce options
+     * @returns DebounceComponent for chaining
+     */
+    addDebouncedEvent: (event: string, handler: (event: Event) => void, wait: number, options?: {
+        leading?: boolean;
+        maxWait?: number;
+    }) => DebounceComponent;
+    /**
+     * Removes a debounced event listener
+     * @param event - Event name
+     * @returns DebounceComponent for chaining
+     */
+    removeDebouncedEvent: (event: string) => DebounceComponent;
+}
+/**
+ * Adds debounced event handling capabilities to a component
+ *
+ * @param config - Configuration object containing debounced event settings
+ * @returns Function that enhances a component with debounced event handling
+ *
+ * @example
+ * ```ts
+ * // Add debounced events to a component
+ * const component = pipe(
+ *   createBase,
+ *   withElement(...),
+ *   withDebounce({
+ *     debouncedEvents: {
+ *       'input': {
+ *         handler: handleInput,
+ *         wait: 300
+ *       },
+ *       'resize': {
+ *         handler: handleResize,
+ *         wait: 200,
+ *         options: { maxWait: 1000 }
+ *       }
+ *     }
+ *   })
+ * )(config);
+ * ```
+ */
+export declare const withDebounce: <T extends DebounceConfig & object>(config?: T) => <C extends ElementComponent>(component: C) => C & DebounceComponent;
+export default withDebounce;

package/dist/core/compose/features/debounce.js

@@ -0,0 +1,44 @@
+import { getCleanup } from "../cleanup.js";
+import { debounce } from "../../utils/performance.js";
+export const withDebounce = (config = {}) => (component) => {
+    const debouncedHandlers = {};
+    const addDebouncedEvent = (event, handler, wait, options = {}) => {
+        if (resources.destroyed)
+            return enhancedComponent;
+        if (debouncedHandlers[event]) {
+            removeDebouncedEvent(event);
+        }
+        const debounced = debounce(handler, wait, options);
+        component.element.addEventListener(event, debounced);
+        debouncedHandlers[event] = {
+            original: handler,
+            debounced: debounced
+        };
+        return enhancedComponent;
+    };
+    const removeDebouncedEvent = (event) => {
+        const handler = debouncedHandlers[event];
+        if (handler) {
+            handler.debounced.cancel();
+            component.element.removeEventListener(event, handler.debounced);
+            delete debouncedHandlers[event];
+        }
+        return enhancedComponent;
+    };
+    const resources = getCleanup(component);
+    resources.add(() => {
+        Object.keys(debouncedHandlers).forEach(event => removeDebouncedEvent(event));
+    });
+    const enhancedComponent = {
+        ...component,
+        addDebouncedEvent,
+        removeDebouncedEvent
+    };
+    if (config.debouncedEvents) {
+        Object.entries(config.debouncedEvents).forEach(([event, settings]) => {
+            addDebouncedEvent(event, settings.handler, settings.wait, settings.options);
+        });
+    }
+    return enhancedComponent;
+};
+export default withDebounce;

package/dist/core/compose/features/disabled.d.ts

@@ -0,0 +1,46 @@
+import { BaseComponent, ElementComponent } from "../component.js";
+/**
+ * Configuration for disabled feature
+ */
+export interface DisabledConfig {
+    disabled?: boolean;
+    componentName?: string;
+}
+/**
+ * Disabled state manager interface
+ */
+export interface DisabledManager {
+    /**
+     * Enables the component
+     * @returns DisabledManager instance for chaining
+     */
+    enable(): DisabledManager;
+    /**
+     * Disables the component
+     * @returns DisabledManager instance for chaining
+     */
+    disable(): DisabledManager;
+    /**
+     * Toggles the disabled state
+     * @returns DisabledManager instance for chaining
+     */
+    toggle(): DisabledManager;
+    /**
+     * Checks if the component is disabled
+     * @returns true if disabled
+     */
+    isDisabled(): boolean;
+}
+/**
+ * Component with disabled state capabilities
+ */
+export interface DisabledComponent extends BaseComponent {
+    disabled: DisabledManager;
+}
+/**
+ * Adds disabled state management to a component
+ *
+ * @param config - Configuration object
+ * @returns Function that enhances a component with disabled state management
+ */
+export declare const withDisabled: <T extends DisabledConfig & object>(config: T) => <C extends ElementComponent>(component: C) => C & DisabledComponent;

package/dist/core/compose/features/disabled.js

@@ -0,0 +1,66 @@
+const isFormControl = (element) => 'disabled' in element;
+function hasDisableableInput(component) {
+    return 'input' in component &&
+        component.input instanceof HTMLElement &&
+        ('disabled' in component.input);
+}
+export const withDisabled = (config) => (component) => {
+    const disabledClass = `${component.getClass(config.componentName || component.componentName || 'component')}--disabled`;
+    const disabled = {
+        enable() {
+            component.element.classList.remove(disabledClass);
+            if (hasDisableableInput(component)) {
+                component.input.disabled = false;
+                component.input.removeAttribute('disabled');
+            }
+            else if (isFormControl(component.element)) {
+                component.element.disabled = false;
+                component.element.removeAttribute('disabled');
+            }
+            else {
+                component.element.removeAttribute('aria-disabled');
+            }
+            return this;
+        },
+        disable() {
+            component.element.classList.add(disabledClass);
+            if (hasDisableableInput(component)) {
+                component.input.disabled = true;
+                component.input.setAttribute('disabled', 'true');
+            }
+            else if (isFormControl(component.element)) {
+                component.element.disabled = true;
+                component.element.setAttribute('disabled', 'true');
+            }
+            else {
+                component.element.setAttribute('aria-disabled', 'true');
+            }
+            return this;
+        },
+        toggle() {
+            if (this.isDisabled()) {
+                this.enable();
+            }
+            else {
+                this.disable();
+            }
+            return this;
+        },
+        isDisabled() {
+            if (hasDisableableInput(component)) {
+                return component.input.disabled;
+            }
+            if (isFormControl(component.element)) {
+                return component.element.disabled;
+            }
+            return component.element.getAttribute('aria-disabled') === 'true';
+        }
+    };
+    if (config.disabled) {
+        disabled.disable();
+    }
+    return {
+        ...component,
+        disabled
+    };
+};

package/dist/core/compose/features/events.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module core/compose/features
+ */
+import { EventCallback } from "../../state/emitter.js";
+import { BaseComponent } from "../component.js";
+/**
+ * A component's events, by name: each one's handler. Without a map a
+ * component takes any event name, and its handlers get `unknown` payloads.
+ */
+export type EventMap<E> = {
+    [K in keyof E]: EventCallback;
+};
+/** The map of a component that does not name its events. */
+export type AnyEvents = Record<string, EventCallback>;
+/**
+ * Component with event capabilities
+ */
+export interface EventComponent<E extends EventMap<E> = AnyEvents> extends BaseComponent {
+    /**
+     * Subscribe to an event
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns Component instance for chaining
+     */
+    on<K extends keyof E & string>(event: K, handler: E[K]): this;
+    /**
+     * Unsubscribe from an event
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns Component instance for chaining
+     */
+    off<K extends keyof E & string>(event: K, handler: E[K]): this;
+    /**
+     * Emit an event
+     * @param event - Event name
+     * @param data - Event data
+     * @returns Component instance for chaining
+     */
+    emit(event: string, data?: unknown): this;
+}
+/**
+ * Adds event handling capabilities to a component
+ * Returns event system ready to use immediately
+ *
+ * `withEvents<Events>()` names the component's events (FLO-295): `on` and
+ * `off` then check each name and its handler's payload.
+ *
+ * @returns Function that enhances a component with event capabilities
+ */
+export declare const withEvents: <E extends EventMap<E> = AnyEvents>() => <T extends BaseComponent>(component: T) => T & EventComponent<E>;

package/dist/core/compose/features/events.js

@@ -0,0 +1,23 @@
+import { getCleanup } from "../cleanup.js";
+import { createEmitter } from "../../state/emitter.js";
+export const withEvents = () => (component) => {
+    const emitter = createEmitter();
+    const resources = getCleanup(component);
+    resources.add(() => emitter.clear());
+    return {
+        ...component,
+        on(event, handler) {
+            if (!resources.destroyed)
+                emitter.on(event, handler);
+            return this;
+        },
+        off(event, handler) {
+            emitter.off(event, handler);
+            return this;
+        },
+        emit(event, data) {
+            emitter.emit(event, data);
+            return this;
+        }
+    };
+};

package/dist/core/compose/features/icon.d.ts

@@ -0,0 +1,67 @@
+import { BaseComponent, ElementComponent } from "../component.js";
+/**
+ * Icon manager interface
+ */
+export interface IconManager {
+    /**
+     * Sets icon HTML content
+     * @param html - Icon HTML content
+     * @returns IconManager instance for chaining
+     */
+    setIcon: (html: string) => IconManager;
+    /**
+     * Gets current icon HTML content
+     * @returns Current icon HTML
+     */
+    getIcon: () => string;
+    /**
+     * Gets icon element
+     * @returns Icon element or null if not created
+     */
+    getElement: () => HTMLElement | null;
+}
+/**
+ * Configuration for icon feature
+ */
+export interface IconConfig {
+    /**
+     * Initial icon HTML content
+     */
+    icon?: string;
+    /**
+     * Icon position ('start' or 'end')
+     */
+    iconPosition?: "start" | "end";
+    /**
+     * Icon size variant
+     */
+    iconSize?: string;
+    /**
+     * CSS class prefix
+     */
+    prefix?: string;
+    /**
+     * Component name for class generation
+     */
+    componentName?: string;
+    /**
+     * Text content (for determining button styling)
+     */
+    text?: string | Node;
+}
+/**
+ * Component with icon capabilities
+ */
+export interface IconComponent extends BaseComponent {
+    /**
+     * Icon manager
+     */
+    icon: IconManager;
+}
+/**
+ * Adds icon management to a component
+ *
+ * @param config - Configuration object containing icon information
+ * @returns Function that enhances a component with icon capabilities
+ */
+export declare const withIcon: <T extends IconConfig & object>(config: T) => <C extends ElementComponent>(component: C) => C & IconComponent;

package/dist/core/compose/features/icon.js

@@ -0,0 +1,71 @@
+import { setHTML } from "../../dom/html.js";
+const createIcon = (element, config = {}) => {
+    let iconElement = null;
+    const PREFIX = config.prefix || "mtrl";
+    const createIconElement = (html) => {
+        const iconEl = document.createElement("span");
+        iconEl.className = `${PREFIX}-icon`;
+        const componentClass = `${PREFIX}-${config.componentName || "component"}__icon`;
+        iconEl.classList.add(componentClass);
+        if (config.iconPosition) {
+            iconEl.classList.add(`${componentClass}--${config.iconPosition}`);
+        }
+        if (config.iconSize) {
+            iconEl.classList.add(`${PREFIX}-icon--${config.iconSize}`);
+        }
+        setHTML(iconEl, html);
+        return iconEl;
+    };
+    return {
+        setIcon(html) {
+            if (!iconElement && html) {
+                iconElement = createIconElement(html);
+                if (config.iconPosition === "end") {
+                    element.appendChild(iconElement);
+                }
+                else {
+                    const labelElement = element.querySelector(`[class*="${PREFIX}-${config.componentName || "component"}__label"]`);
+                    if (labelElement) {
+                        if (labelElement.nextSibling) {
+                            element.insertBefore(iconElement, labelElement.nextSibling);
+                        }
+                        else {
+                            element.appendChild(iconElement);
+                        }
+                    }
+                    else {
+                        element.insertBefore(iconElement, element.firstChild);
+                    }
+                }
+            }
+            else if (iconElement && html) {
+                setHTML(iconElement, html);
+            }
+            return this;
+        },
+        getIcon() {
+            return iconElement ? iconElement.innerHTML : "";
+        },
+        getElement() {
+            return iconElement;
+        },
+    };
+};
+export const withIcon = (config) => (component) => {
+    const icon = createIcon(component.element, {
+        prefix: config.prefix,
+        componentName: config.componentName || "component",
+        iconPosition: config.iconPosition,
+        iconSize: config.iconSize,
+    });
+    if (config.icon) {
+        icon.setIcon(config.icon);
+    }
+    if (component.componentName === "button" && config.icon && config.text) {
+        component.element.classList.add(`${component.getClass("button")}--icon`);
+    }
+    return {
+        ...component,
+        icon,
+    };
+};

package/dist/core/compose/features/index.d.ts

@@ -0,0 +1,34 @@
+export { withEvents } from "./events.js";
+export { withText } from "./text.js";
+export { withIcon } from "./icon.js";
+export { withVariant } from "./variant.js";
+export { withSize } from "./size.js";
+export { withPosition } from "./position.js";
+export { withRipple } from "./ripple.js";
+export { withInput } from "./input.js";
+export { withCheckable } from "./checkable.js";
+export { withStyle } from "./style.js";
+export { withTextInput } from "./textinput.js";
+export { withTextLabel } from "./textlabel.js";
+export { withTrack } from "./track.js";
+export { withEvents as withEnhancedEvents } from "./withEvents.js";
+export { withBadge } from "./badge.js";
+export { withThrottle } from "./throttle.js";
+export { withDebounce } from "./debounce.js";
+export { withDisabled } from "./disabled.js";
+export { withLifecycle } from "./lifecycle.js";
+export type { EventComponent } from "./events.js";
+export type { TextComponent } from "./text.js";
+export type { IconComponent } from "./icon.js";
+export type { LifecycleComponent, Lifecycle } from "./lifecycle.js";
+export type { DisabledComponent, DisabledManager } from "./disabled.js";
+export type { RippleComponent } from "./ripple.js";
+export type { InputComponent } from "./input.js";
+export type { CheckableComponent, CheckableManager } from "./checkable.js";
+export type { TextInputComponent } from "./textinput.js";
+export type { LabelComponent, LabelManager } from "./textlabel.js";
+export type { TrackComponent } from "./track.js";
+export type { EnhancedEventComponent } from "./withEvents.js";
+export type { BadgeComponent, BadgeConfig } from "./badge.js";
+export type { ThrottleComponent, ThrottleConfig } from "./throttle.js";
+export type { DebounceComponent, DebounceConfig } from "./debounce.js";

package/dist/core/compose/features/index.js

@@ -0,0 +1,19 @@
+export { withEvents } from "./events.js";
+export { withText } from "./text.js";
+export { withIcon } from "./icon.js";
+export { withVariant } from "./variant.js";
+export { withSize } from "./size.js";
+export { withPosition } from "./position.js";
+export { withRipple } from "./ripple.js";
+export { withInput } from "./input.js";
+export { withCheckable } from "./checkable.js";
+export { withStyle } from "./style.js";
+export { withTextInput } from "./textinput.js";
+export { withTextLabel } from "./textlabel.js";
+export { withTrack } from "./track.js";
+export { withEvents as withEnhancedEvents } from "./withEvents.js";
+export { withBadge } from "./badge.js";
+export { withThrottle } from "./throttle.js";
+export { withDebounce } from "./debounce.js";
+export { withDisabled } from "./disabled.js";
+export { withLifecycle } from "./lifecycle.js";

package/dist/core/compose/features/input.d.ts

@@ -0,0 +1,105 @@
+import { ElementComponent } from "../component.js";
+/**
+ * Input configuration options
+ */
+export interface InputConfig {
+    /**
+     * Input name attribute
+     */
+    name?: string;
+    /**
+     * Initial checked state
+     */
+    checked?: boolean;
+    /**
+     * Whether input is required
+     */
+    required?: boolean;
+    /**
+     * Whether input is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Input value attribute
+     */
+    value?: string;
+    /**
+     * Accessibility label text
+     */
+    label?: string | Node;
+    /**
+     * Alternative accessibility label
+     */
+    ariaLabel?: string;
+    /**
+     * Component name for classes
+     */
+    componentName?: string;
+    /**
+     * Whether Enter toggles the input as Space does
+     * @default true
+     */
+    enterToggles?: boolean;
+}
+/**
+ * What withInput adds to a component.
+ *
+ * Declared apart from InputComponent because the enhancer returns
+ * `C & InputFeature`, and C -- the component being enhanced -- already carries
+ * the element half. Naming the whole of InputComponent on the way out is what
+ * narrowed `addClass` back to a bare ElementComponent. It has to be its own
+ * interface rather than a Pick of InputComponent: an indexed access binds
+ * `this` to the type being indexed, so the methods below would report
+ * InputComponent and the polymorphism would be lost at the step that needs it.
+ */
+export interface InputFeature {
+    /**
+     * Input element
+     */
+    input: HTMLInputElement;
+    /**
+     * Gets the checked state: the `value` a `change` carries
+     * @returns Whether the input is checked
+     */
+    getValue: () => boolean;
+    /**
+     * Checks or unchecks the input. Silent: only the user's change emits `change`
+     * @param value - Whether the input is checked
+     * @returns Component instance for chaining
+     */
+    setValue(value: boolean): this;
+    /**
+     * Gets the input's `value` attribute: the string a form submits while checked
+     * @returns The input's string value
+     */
+    getValueAttribute: () => string;
+    /**
+     * Sets the input's `value` attribute. Silent
+     * @param value - The string a form submits while checked
+     * @returns Component instance for chaining
+     */
+    setValueAttribute(value: string): this;
+    /**
+     * Event emission method if available
+     */
+    emit?(event: string, data: unknown): this;
+}
+/**
+ * Component with input element and related methods
+ */
+export interface InputComponent extends ElementComponent, InputFeature {
+}
+/**
+ * Creates an input element and adds it to a component
+ * Handles both input creation and event emission for state changes
+ *
+ * `change` carries `{ checked, value, valueAttribute, nativeEvent }`: `value` is
+ * the checked boolean, as the checkbox and the switch report it, and
+ * `valueAttribute` the input's string value. The methods match: `getValue()`
+ * and `setValue()` work on the checked boolean, `getValueAttribute()` and
+ * `setValueAttribute()` on the string. Both setters are silent.
+ *
+ * @param config - Input configuration
+ * @returns Function that enhances a component with input functionality
+ */
+export declare const withInput: <T extends InputConfig & object>(config?: T) => <C extends ElementComponent>(component: C) => C & InputFeature;

package/dist/core/compose/features/input.js

@@ -0,0 +1,68 @@
+import { omitsAttribute } from "../../utils/attributes.js";
+function hasEmit(component) {
+    return "emit" in component && typeof component.emit === "function";
+}
+export const withInput = (config = {}) => (component) => {
+    const input = document.createElement("input");
+    const name = component.componentName || "component";
+    input.type = "checkbox";
+    input.className = `${component.getClass(name)}__input`;
+    input.style.position = "absolute";
+    input.style.opacity = "0";
+    input.style.cursor = "pointer";
+    component.element.setAttribute("role", "presentation");
+    input.setAttribute("role", name);
+    const attributes = {
+        name: config.name,
+        checked: config.checked,
+        required: config.required,
+        disabled: config.disabled,
+        value: config.value || "on",
+        "aria-label": config.ariaLabel || (typeof config.label === "string" ? config.label : undefined),
+    };
+    Object.entries(attributes).forEach(([key, value]) => {
+        if (value !== null && value !== undefined && !omitsAttribute(key, value)) {
+            if (key === "disabled" && value === true) {
+                input.disabled = true;
+                input.setAttribute("disabled", "true");
+            }
+            else if (value === true) {
+                input.setAttribute(key, key);
+            }
+            else {
+                input.setAttribute(key, String(value));
+            }
+        }
+    });
+    input.addEventListener("change", (event) => {
+        if (hasEmit(component)) {
+            component.emit("change", {
+                checked: input.checked,
+                value: input.checked,
+                valueAttribute: input.value,
+                nativeEvent: event,
+            });
+        }
+    });
+    input.addEventListener("keydown", (event) => {
+        if (event.key === " " || (event.key === "Enter" && config.enterToggles !== false)) {
+            event.preventDefault();
+            input.click();
+        }
+    });
+    component.element.appendChild(input);
+    return {
+        ...component,
+        input,
+        getValue: () => input.checked,
+        setValue(value) {
+            input.checked = value;
+            return this;
+        },
+        getValueAttribute: () => input.value,
+        setValueAttribute(value) {
+            input.value = value;
+            return this;
+        },
+    };
+};