mtrl-addons 0.4.2 → 0.4.4

package/dist/components/colorpicker/api.d.ts

@@ -0,0 +1,45 @@
+import { ColorPickerComponent, ColorPickerConfig, ColorPickerState } from "./types";
+import { AreaFeature } from "./features/area";
+import { HueFeature } from "./features/hue";
+import { SwatchesFeature } from "./features/swatches";
+import { InputFeature } from "./features/input";
+import { VariantFeature } from "./features/variant";
+/**
+ * API configuration options for color picker component
+ * @category Components
+ * @internal
+ */
+interface ApiOptions {
+    element: HTMLElement;
+    config: ColorPickerConfig;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => unknown;
+    off: (event: string, handler: (...args: unknown[]) => void) => unknown;
+    disabled: {
+        enable: () => void;
+        disable: () => void;
+        isDisabled: () => boolean;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+    state?: ColorPickerState;
+    area?: AreaFeature;
+    hue?: HueFeature;
+    swatches?: SwatchesFeature;
+    input?: InputFeature;
+    variant?: VariantFeature;
+}
+/**
+ * Enhances a color picker component with API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
+ *
+ * @param options - API configuration options
+ * @returns Higher-order function that adds API methods to component
+ * @category Components
+ * @internal
+ */
+export declare const withAPI: (options: ApiOptions) => (component: unknown) => ColorPickerComponent;
+export {};

package/dist/components/colorpicker/colorpicker.d.ts

@@ -0,0 +1,47 @@
+import { ColorPickerConfig, ColorPickerComponent } from "./types";
+/**
+ * Creates a new ColorPicker component with the specified configuration.
+ *
+ * A color picker with optional saturation/brightness area, hue slider,
+ * hex input, and color swatches. Supports inline, dropdown, and dialog variants.
+ *
+ * The ColorPicker component is created using a functional composition pattern,
+ * applying various features through the pipe function.
+ *
+ * @param {ColorPickerConfig} config - Configuration options for the color picker
+ * @returns {ColorPickerComponent} A fully configured color picker component instance
+ * @throws {Error} Throws an error if color picker creation fails
+ *
+ * @example
+ * ```ts
+ * // Inline variant (default) - always visible
+ * const picker = createColorPicker({
+ *   value: '#ff5722',
+ *   swatches: ['#f44336', '#e91e63', '#9c27b0'],
+ *   onChange: (color) => console.log('Color:', color)
+ * });
+ * document.body.appendChild(picker.element);
+ *
+ * // Dropdown variant with trigger element
+ * const dropdown = createColorPicker({
+ *   variant: 'dropdown',
+ *   trigger: document.getElementById('color-button'),
+ *   value: '#ff5722',
+ *   onChange: (color) => console.log('Color:', color)
+ * });
+ *
+ * // Minimal picker with only swatches
+ * const swatchPicker = createColorPicker({
+ *   variant: 'dropdown',
+ *   trigger: myButton,
+ *   showArea: false,
+ *   showHue: false,
+ *   showInput: false,
+ *   swatches: ['#ff0000', '#00ff00', '#0000ff']
+ * });
+ * ```
+ *
+ * @category Components
+ */
+declare const createColorPicker: (config?: ColorPickerConfig) => ColorPickerComponent;
+export default createColorPicker;

package/dist/components/colorpicker/config.d.ts

@@ -0,0 +1,145 @@
+import { ColorPickerConfig, ColorPickerState } from "./types";
+/**
+ * Default configuration for the ColorPicker component.
+ * These values will be used when not explicitly specified by the user.
+ *
+ * @category Components
+ */
+export declare const defaultConfig: ColorPickerConfig;
+/**
+ * Creates the base configuration for ColorPicker component by merging
+ * user-provided config with default values.
+ *
+ * @param config - User provided configuration
+ * @returns Complete configuration with defaults applied
+ * @category Components
+ * @internal
+ */
+export declare const createBaseConfig: (config?: ColorPickerConfig) => Required<Pick<ColorPickerConfig, "value" | "variant" | "size" | "swatchSize" | "showInput" | "showPreview" | "showSwatches" | "showHue" | "showArea" | "maxSwatches" | "closeOnSelect" | "disabled" | "prefix" | "componentName">> & ColorPickerConfig;
+/**
+ * Gets the element configuration for withElement.
+ *
+ * @param config - Color picker configuration
+ * @returns Element configuration object
+ * @category Components
+ * @internal
+ */
+export declare const getElementConfig: (config: ColorPickerConfig) => {
+    tag: string;
+    componentName: any;
+    className: string[];
+    style: string;
+};
+/**
+ * Gets the size dimensions based on the size configuration
+ *
+ * @param size - Size key ('s', 'm', 'l')
+ * @returns Dimension object with width, areaHeight, hueHeight
+ * @category Components
+ * @internal
+ */
+export declare const getSizeDimensions: (size: string) => {
+    width: number;
+    areaHeight: number;
+    hueHeight: number;
+};
+/**
+ * Creates the initial state for the color picker
+ *
+ * @param config - Color picker configuration
+ * @returns Initial state object
+ * @category Components
+ * @internal
+ */
+export declare const createInitialState: (config: ColorPickerConfig) => ColorPickerState;
+/**
+ * Creates the API configuration for the ColorPicker component.
+ * This connects the core component features to the public API methods.
+ *
+ * @param comp - Component with features applied
+ * @returns API configuration object
+ * @category Components
+ * @internal
+ */
+export declare const getApiConfig: (comp: {
+    element: HTMLElement;
+    config: ColorPickerConfig;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => unknown;
+    off: (event: string, handler: (...args: unknown[]) => void) => unknown;
+    disabled: {
+        enable: () => void;
+        disable: () => void;
+        isDisabled: () => boolean;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+    state?: ColorPickerState;
+    area?: {
+        updateBackground: () => void;
+        updateHandle: () => void;
+    };
+    hue?: {
+        updateHandle: () => void;
+    };
+    swatches?: {
+        update: () => void;
+        set: (swatches: unknown[]) => void;
+        add: (color: string, label?: string) => void;
+        remove: (color: string) => void;
+        clear: () => void;
+        get: () => unknown[];
+    };
+    input?: {
+        update: () => void;
+    };
+    variant?: {
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
+        isOpen: () => boolean;
+    };
+}) => {
+    element: HTMLElement;
+    config: ColorPickerConfig;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    on: (event: string, handler: (...args: unknown[]) => void) => unknown;
+    off: (event: string, handler: (...args: unknown[]) => void) => unknown;
+    disabled: {
+        enable: () => void;
+        disable: () => void;
+        isDisabled: () => boolean;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+    state: ColorPickerState | undefined;
+    area: {
+        updateBackground: () => void;
+        updateHandle: () => void;
+    } | undefined;
+    hue: {
+        updateHandle: () => void;
+    } | undefined;
+    swatches: {
+        update: () => void;
+        set: (swatches: unknown[]) => void;
+        add: (color: string, label?: string) => void;
+        remove: (color: string) => void;
+        clear: () => void;
+        get: () => unknown[];
+    } | undefined;
+    input: {
+        update: () => void;
+    } | undefined;
+    variant: {
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
+        isOpen: () => boolean;
+    } | undefined;
+};
+export default defaultConfig;

package/dist/components/colorpicker/constants.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Color picker component constants
+ * @module components/colorpicker
+ */
+/**
+ * Color picker events
+ */
+export declare const COLORPICKER_EVENTS: {
+    /** Fired when color value changes (committed) */
+    readonly CHANGE: "change";
+    /** Fired during color selection (live preview) */
+    readonly INPUT: "input";
+    /** Fired when a swatch is clicked */
+    readonly SWATCH_SELECT: "swatchSelect";
+    /** Fired when swatches are updated */
+    readonly SWATCHES_CHANGE: "swatchesChange";
+    /** Fired when picker opens (dropdown/dialog variants) */
+    readonly OPEN: "open";
+    /** Fired when picker closes (dropdown/dialog variants) */
+    readonly CLOSE: "close";
+};
+/**
+ * Color picker variants
+ */
+export declare const COLORPICKER_VARIANTS: {
+    /** Inline - always visible, no trigger */
+    readonly INLINE: "inline";
+    /** Dropdown - attached to trigger, opens below/above */
+    readonly DROPDOWN: "dropdown";
+    /** Dialog - modal overlay centered on screen */
+    readonly DIALOG: "dialog";
+};
+/**
+ * Color picker sizes
+ */
+export declare const COLORPICKER_SIZES: {
+    /** Small - 200px wide */
+    readonly S: "s";
+    /** Medium - 280px wide (default) */
+    readonly M: "m";
+    /** Large - 360px wide */
+    readonly L: "l";
+};
+/**
+ * Swatch sizes in pixels
+ */
+export declare const SWATCH_SIZES: {
+    readonly S: 24;
+    readonly M: 32;
+    readonly L: 40;
+};
+/**
+ * CSS classes used by the color picker component
+ */
+export declare const COLORPICKER_CLASSES: {
+    readonly ROOT: "colorpicker";
+    readonly AREA: "colorpicker__area";
+    readonly AREA_GRADIENT: "colorpicker__area-gradient";
+    readonly AREA_HANDLE: "colorpicker__area-handle";
+    readonly HUE: "colorpicker__hue";
+    readonly HUE_SLIDER: "colorpicker__hue-slider";
+    readonly HUE_HANDLE: "colorpicker__hue-handle";
+    readonly SWATCHES: "colorpicker__swatches";
+    readonly SWATCH: "colorpicker__swatch";
+    readonly SWATCH_SELECTED: "colorpicker__swatch--selected";
+    readonly SWATCH_ADD: "colorpicker__swatch--add";
+    readonly PREVIEW: "colorpicker__preview";
+    readonly VALUE: "colorpicker__value";
+    readonly VALUE_INPUT: "colorpicker__value-input";
+    readonly CONTAINER: "colorpicker__container";
+    readonly BACKDROP: "colorpicker__backdrop";
+    readonly DISABLED: "colorpicker--disabled";
+    readonly DRAGGING: "colorpicker--dragging";
+    readonly OPEN: "colorpicker--open";
+    readonly POSITION_TOP: "colorpicker--position-top";
+    readonly INLINE: "colorpicker--inline";
+    readonly DROPDOWN: "colorpicker--dropdown";
+    readonly DIALOG: "colorpicker--dialog";
+};
+/**
+ * Default color picker configuration
+ */
+export declare const COLORPICKER_DEFAULTS: {
+    /** Default color value */
+    readonly VALUE: "#ff0000";
+    /** Default component size */
+    readonly SIZE: "m";
+    /** Default swatch size */
+    readonly SWATCH_SIZE: 32;
+    /** Whether to show the hex input */
+    readonly SHOW_INPUT: true;
+    /** Whether to show the preview square */
+    readonly SHOW_PREVIEW: true;
+    /** Whether to show swatches */
+    readonly SHOW_SWATCHES: true;
+    /** Maximum number of swatches */
+    readonly MAX_SWATCHES: 8;
+    /** Default variant */
+    readonly VARIANT: "inline";
+    /** Close on swatch select (dropdown/dialog) */
+    readonly CLOSE_ON_SELECT: true;
+};
+/**
+ * Size dimensions in pixels
+ */
+export declare const SIZE_DIMENSIONS: {
+    readonly s: {
+        readonly width: 200;
+        readonly areaHeight: 120;
+        readonly hueHeight: 16;
+    };
+    readonly m: {
+        readonly width: 280;
+        readonly areaHeight: 160;
+        readonly hueHeight: 20;
+    };
+    readonly l: {
+        readonly width: 360;
+        readonly areaHeight: 200;
+        readonly hueHeight: 24;
+    };
+};
+/**
+ * Vibrant palette swatch keys in order of preference
+ */
+export declare const PALETTE_SWATCH_ORDER: readonly ["Vibrant", "Muted", "DarkVibrant", "DarkMuted", "LightVibrant", "LightMuted"];
+export type ColorPickerEvent = (typeof COLORPICKER_EVENTS)[keyof typeof COLORPICKER_EVENTS];
+export type ColorPickerSize = (typeof COLORPICKER_SIZES)[keyof typeof COLORPICKER_SIZES];
+export type ColorPickerVariant = (typeof COLORPICKER_VARIANTS)[keyof typeof COLORPICKER_VARIANTS];
+export type SwatchSize = (typeof SWATCH_SIZES)[keyof typeof SWATCH_SIZES];

package/dist/components/colorpicker/features/area.d.ts

@@ -0,0 +1,27 @@
+import { ColorPickerConfig, ColorPickerState } from "../types";
+/**
+ * Area feature interface
+ */
+export interface AreaFeature {
+    element: HTMLElement;
+    gradient: HTMLElement;
+    handle: HTMLElement;
+    updateBackground: () => void;
+    updateHandle: () => void;
+}
+/**
+ * Adds the saturation/brightness area to a color picker component
+ *
+ * @param config - Color picker configuration
+ * @returns Component enhancer function
+ */
+export declare const withArea: (config: ColorPickerConfig) => <T extends {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    state?: ColorPickerState;
+    pickerContent?: HTMLElement;
+}>(component: T) => T & {
+    area: AreaFeature;
+    state: ColorPickerState;
+};

package/dist/components/colorpicker/features/hue.d.ts

@@ -0,0 +1,31 @@
+import { createSlider } from "mtrl";
+import { ColorPickerConfig, ColorPickerState } from "../types";
+/**
+ * Hue feature interface
+ */
+export interface HueFeature {
+    element: HTMLElement;
+    slider: ReturnType<typeof createSlider>;
+    updateHandle: () => void;
+}
+/**
+ * Adds the hue slider to a color picker component using mtrl slider
+ *
+ * @param config - Color picker configuration
+ * @returns Component enhancer function
+ */
+export declare const withHue: (config: ColorPickerConfig) => <T extends {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    state?: ColorPickerState;
+    pickerContent?: HTMLElement;
+    area?: {
+        element: HTMLElement;
+        updateBackground: () => void;
+        updateHandle: () => void;
+    };
+}>(component: T) => T & {
+    hue: HueFeature;
+    state: ColorPickerState;
+};

package/dist/components/colorpicker/features/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ColorPicker features module
+ * @module components/colorpicker/features
+ */
+export { withArea } from "./area";
+export type { AreaFeature } from "./area";
+export { withHue } from "./hue";
+export type { HueFeature } from "./hue";
+export { withSwatches } from "./swatches";
+export type { SwatchesFeature } from "./swatches";
+export { withInput } from "./input";
+export type { InputFeature } from "./input";
+export { withVariant } from "./variant";
+export type { VariantFeature } from "./variant";

package/dist/components/colorpicker/features/input.d.ts

@@ -0,0 +1,37 @@
+import { createTextfield } from "mtrl";
+import { ColorPickerConfig, ColorPickerState } from "../types";
+/**
+ * Input feature interface
+ */
+export interface InputFeature {
+    element: HTMLElement;
+    textfield: ReturnType<typeof createTextfield> | null;
+    preview: HTMLElement | null;
+    update: () => void;
+}
+/**
+ * Adds the hex input field (using mtrl textfield) and color preview to a color picker component
+ *
+ * @param config - Color picker configuration
+ * @returns Component enhancer function
+ */
+export declare const withInput: (config: ColorPickerConfig) => <T extends {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    state?: ColorPickerState;
+    pickerContent?: HTMLElement;
+    variant?: {
+        close: () => void;
+    };
+    area?: {
+        updateBackground: () => void;
+        updateHandle: () => void;
+    };
+    hue?: {
+        updateHandle: () => void;
+    };
+}>(component: T) => T & {
+    input: InputFeature;
+    state: ColorPickerState;
+};

package/dist/components/colorpicker/features/popup.d.ts

@@ -0,0 +1,39 @@
+import { ColorPickerState } from "../types";
+/**
+ * Component interface for popup feature
+ */
+interface PopupComponent {
+    element: HTMLElement;
+    state: ColorPickerState;
+    getClass: (name: string) => string;
+    emit: (event: string, ...args: unknown[]) => void;
+    config: {
+        variant?: string;
+        trigger?: HTMLElement;
+        disabled?: boolean;
+        prefix?: string;
+    };
+    pickerContent: HTMLElement;
+    updateUI?: () => void;
+}
+/**
+ * Popup feature interface
+ */
+export interface PopupFeature {
+    backdrop: HTMLElement | null;
+    popup: HTMLElement;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    isOpen: () => boolean;
+    position: () => void;
+}
+/**
+ * Adds popup functionality (dropdown/dialog) to a color picker component
+ *
+ * @returns Component enhancer function
+ */
+export declare const withPopup: () => <T extends PopupComponent>(component: T) => T & {
+    popup: PopupFeature;
+};
+export {};

package/dist/components/colorpicker/features/swatches.d.ts

@@ -0,0 +1,42 @@
+import { ColorPickerConfig, ColorPickerState, ColorSwatch } from "../types";
+/**
+ * Swatches feature interface
+ */
+export interface SwatchesFeature {
+    element: HTMLElement;
+    update: () => void;
+    set: (swatches: string[] | ColorSwatch[]) => void;
+    add: (color: string, label?: string) => void;
+    remove: (color: string) => void;
+    clear: () => void;
+    get: () => ColorSwatch[];
+}
+/**
+ * Adds swatches (color presets) to a color picker component
+ *
+ * @param config - Color picker configuration
+ * @returns Component enhancer function
+ */
+export declare const withSwatches: (config: ColorPickerConfig) => <T extends {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    state?: ColorPickerState;
+    pickerContent?: HTMLElement;
+    variant?: {
+        close: () => void;
+    };
+    area?: {
+        updateBackground: () => void;
+        updateHandle: () => void;
+    };
+    hue?: {
+        updateHandle: () => void;
+    };
+    input?: {
+        update: () => void;
+    };
+}>(component: T) => T & {
+    swatches: SwatchesFeature;
+    state: ColorPickerState;
+};

package/dist/components/colorpicker/features/variant.d.ts

@@ -0,0 +1,30 @@
+import { ColorPickerConfig, ColorPickerState } from "../types";
+/**
+ * Variant feature interface
+ */
+export interface VariantFeature {
+    backdrop: HTMLElement | null;
+    container: HTMLElement;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    isOpen: () => boolean;
+    position: () => void;
+}
+/**
+ * Adds variant-specific behavior (dropdown/dialog) to a color picker component.
+ * Handles positioning, open/close, backdrop, and event management that CSS cannot handle.
+ *
+ * @param config - Color picker configuration
+ * @returns Component enhancer function
+ */
+export declare const withVariant: (config: ColorPickerConfig) => <T extends {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    state?: ColorPickerState;
+}>(component: T) => T & {
+    variant: VariantFeature;
+    pickerContent: HTMLElement;
+    state: ColorPickerState;
+};

package/dist/components/colorpicker/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ColorPicker component module
+ * @module components/colorpicker
+ */
+export { default as createColorPicker } from "./colorpicker";
+export { COLORPICKER_EVENTS, COLORPICKER_SIZES, COLORPICKER_VARIANTS, COLORPICKER_CLASSES, COLORPICKER_DEFAULTS, SWATCH_SIZES, SIZE_DIMENSIONS, PALETTE_SWATCH_ORDER, } from "./constants";
+export type { ColorPickerConfig, ColorPickerComponent, ColorPickerState, HSVColor, RGBColor, ColorSwatch, } from "./types";
+export { defaultConfig, createBaseConfig, getSizeDimensions, createInitialState, getApiConfig, } from "./config";
+export { hsvToRgb, rgbToHsv, hsvToHex, hexToHsv, rgbToHex, hexToRgb, isValidHex, normalizeHex, getContrastColor, clamp, } from "./utils";
+export { withArea } from "./features/area";
+export type { AreaFeature } from "./features/area";
+export { withHue } from "./features/hue";
+export type { HueFeature } from "./features/hue";
+export { withSwatches } from "./features/swatches";
+export type { SwatchesFeature } from "./features/swatches";
+export { withInput } from "./features/input";
+export type { InputFeature } from "./features/input";
+export { withVariant } from "./features/variant";
+export type { VariantFeature } from "./features/variant";
+export { withAPI } from "./api";