mtrl 0.3.8 → 0.4.0

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

@@ -0,0 +1,63 @@
+/**
+ * Visual variants for checkbox styling
+ *
+ * Material Design 3 checkboxes can use different visual styles
+ * while maintaining the same functionality.
+ *
+ * @category Components
+ */
+export declare const CHECKBOX_VARIANTS: {
+    /** Checkbox with filled background when checked */
+    readonly FILLED: "filled";
+    /** Checkbox with outlined style (less prominent) */
+    readonly OUTLINED: "outlined";
+};
+/**
+ * Label position options for the checkbox
+ *
+ * Controls whether the label appears before or after the checkbox.
+ *
+ * @category Components
+ */
+export declare const CHECKBOX_LABEL_POSITION: {
+    /** Label appears before (to the left of) the checkbox */
+    readonly START: "start";
+    /** Label appears after (to the right of) the checkbox (default) */
+    readonly END: "end";
+};
+/**
+ * Checkbox state classes
+ *
+ * These classes are applied to the checkbox element to reflect its current state.
+ * They can be used for styling or for selection in tests.
+ *
+ * @category Components
+ */
+export declare const CHECKBOX_STATES: {
+    /** Applied when the checkbox is checked */
+    readonly CHECKED: "checked";
+    /** Applied when the checkbox is in indeterminate state */
+    readonly INDETERMINATE: "indeterminate";
+    /** Applied when the checkbox is disabled */
+    readonly DISABLED: "disabled";
+    /** Applied when the checkbox has focus */
+    readonly FOCUSED: "focused";
+};
+/**
+ * Checkbox element classes
+ *
+ * These classes are applied to different parts of the checkbox component.
+ * They follow the BEM naming convention used throughout the library.
+ *
+ * @category Components
+ */
+export declare const CHECKBOX_CLASSES: {
+    /** The main checkbox container element */
+    readonly ROOT: "checkbox";
+    /** The actual input element (usually hidden) */
+    readonly INPUT: "checkbox-input";
+    /** The visual checkbox icon */
+    readonly ICON: "checkbox-icon";
+    /** The text label associated with the checkbox */
+    readonly LABEL: "checkbox-label";
+};

package/{src/components/checkbox/index.ts → dist/components/checkbox/index.d.ts}

@@ -1,45 +1,28 @@
-// src/components/checkbox/index.ts
-
 /**
  * Checkbox Component Module
- * 
+ *
  * A Material Design 3 checkbox implementation with support
  * for different variants, indeterminate state, and label positioning.
- * 
+ *
  * @module components/checkbox
  * @category Components
  */
-
-// Main factory function
 export { default } from './checkbox';
-
-// TypeScript types and interfaces
-export type { 
-  CheckboxConfig, 
-  CheckboxComponent, 
-  CheckboxVariant, 
-  CheckboxLabelPosition
-} from './types';
-
+export type { CheckboxConfig, CheckboxComponent, CheckboxVariant, CheckboxLabelPosition } from './types';
 /**
  * Constants for checkbox configuration
- * 
+ *
  * Use these constants instead of string literals for better
  * code completion, type safety, and to follow best practices.
- * 
+ *
  * @example
  * import { createCheckbox, CHECKBOX_VARIANTS } from 'mtrl';
- * 
+ *
  * const checkbox = createCheckbox({
  *   variant: CHECKBOX_VARIANTS.OUTLINED,
  *   label: 'Accept terms'
  * });
- * 
+ *
  * @category Components
  */
-export { 
-  CHECKBOX_VARIANTS,
-  CHECKBOX_LABEL_POSITION,
-  CHECKBOX_STATES,
-  CHECKBOX_CLASSES
-} from './types';
+export { CHECKBOX_VARIANTS, CHECKBOX_LABEL_POSITION, CHECKBOX_STATES, CHECKBOX_CLASSES } from './constants';

package/dist/components/checkbox/types.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Checkbox variant types - controls the visual style of the checkbox
+ *
+ * @category Components
+ * @remarks
+ * - filled: Checkbox with filled background when checked (default)
+ * - outlined: Checkbox with outline only, for less visual emphasis
+ */
+export type CheckboxVariant = 'filled' | 'outlined';
+/**
+ * Checkbox label position types - controls where the label appears
+ *
+ * @category Components
+ * @remarks
+ * - start: Label appears before (to the left of) the checkbox
+ * - end: Label appears after (to the right of) the checkbox (default)
+ */
+export type CheckboxLabelPosition = 'start' | 'end';
+/**
+ * Configuration interface for the Checkbox component
+ *
+ * @category Components
+ * @description
+ * Defines the appearance and behavior of a checkbox component.
+ * All properties are optional with sensible defaults.
+ */
+export interface CheckboxConfig {
+    /**
+     * Input name attribute, used for form submission
+     * @example "accept-terms"
+     */
+    name?: string;
+    /**
+     * Initial checked state
+     * @default false
+     */
+    checked?: boolean;
+    /**
+     * Initial indeterminate state (partially checked)
+     * Used when a checkbox represents a mixed selection state
+     * @default false
+     */
+    indeterminate?: boolean;
+    /**
+     * Whether input is required for form validation
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Whether checkbox is disabled (non-interactive)
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Input value attribute, used for form submission
+     * @example "true" | "selected" | "1"
+     */
+    value?: string;
+    /**
+     * Label text displayed next to the checkbox
+     * @example "Accept terms and conditions"
+     */
+    label?: string;
+    /**
+     * Label position (start/end)
+     * Controls whether the label appears before or after the checkbox
+     * @default "end"
+     */
+    labelPosition?: CheckboxLabelPosition | string;
+    /**
+     * Visual variant (filled/outlined)
+     * @default "filled"
+     */
+    variant?: CheckboxVariant | string;
+    /**
+     * Additional CSS classes to apply to the checkbox
+     * @example "terms-checkbox primary-checkbox"
+     */
+    class?: string;
+    /**
+     * CSS class prefix for all checkbox classes
+     * @default "mtrl"
+     */
+    prefix?: string;
+    /**
+     * Component name used in CSS class generation
+     * @default "checkbox"
+     * @internal
+     */
+    componentName?: string;
+}
+/**
+ * Checkbox component interface
+ *
+ * Provides methods for controlling a Material Design 3 checkbox
+ *
+ * @category Components
+ */
+export interface CheckboxComponent {
+    /**
+     * The checkbox's root DOM element (container)
+     */
+    element: HTMLElement;
+    /**
+     * The actual input element (native checkbox)
+     */
+    input: HTMLInputElement;
+    /**
+     * Gets the checkbox's current value attribute
+     * @returns Current value of the checkbox
+     */
+    getValue: () => string;
+    /**
+     * Sets the checkbox's value attribute
+     * @param value - New value to set
+     * @returns Checkbox component for method chaining
+     */
+    setValue: (value: string) => CheckboxComponent;
+    /**
+     * Checks the checkbox (sets checked=true)
+     * @returns Checkbox component for method chaining
+     */
+    check: () => CheckboxComponent;
+    /**
+     * Unchecks the checkbox (sets checked=false)
+     * @returns Checkbox component for method chaining
+     */
+    uncheck: () => CheckboxComponent;
+    /**
+     * Toggles the checkbox's checked state
+     * @returns Checkbox component for method chaining
+     */
+    toggle: () => CheckboxComponent;
+    /**
+     * Checks if the checkbox is currently checked
+     * @returns True if checkbox is checked, false otherwise
+     */
+    isChecked: () => boolean;
+    /**
+     * Sets the checkbox's indeterminate state
+     * An indeterminate checkbox appears partially checked
+     * and is used to represent a mixed selection state
+     *
+     * @param state - Whether to set indeterminate state
+     * @returns Checkbox component for method chaining
+     */
+    setIndeterminate: (state: boolean) => CheckboxComponent;
+    /**
+     * Sets the checkbox's label text
+     * @param text - New label text
+     * @returns Checkbox component for method chaining
+     */
+    setLabel: (text: string) => CheckboxComponent;
+    /**
+     * Gets the checkbox's current label text
+     * @returns Current label text
+     */
+    getLabel: () => string;
+    /**
+     * Adds an event listener to the checkbox
+     * @param event - Event name ('change', 'click', etc.)
+     * @param handler - Event handler function
+     * @returns Checkbox component for method chaining
+     * @example
+     * checkbox.on('change', (e) => console.log('Checkbox state:', e.target.checked));
+     */
+    on: (event: string, handler: Function) => CheckboxComponent;
+    /**
+     * Removes an event listener from the checkbox
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns Checkbox component for method chaining
+     */
+    off: (event: string, handler: Function) => CheckboxComponent;
+    /**
+     * Enables the checkbox, making it interactive
+     * @returns Checkbox component for method chaining
+     */
+    enable: () => CheckboxComponent;
+    /**
+     * Disables the checkbox, making it non-interactive
+     * @returns Checkbox component for method chaining
+     */
+    disable: () => CheckboxComponent;
+    /**
+     * Destroys the checkbox component and cleans up resources
+     * Removes event listeners and DOM references
+     */
+    destroy: () => void;
+}
+/**
+ * API options interface for internal use
+ * @category Components
+ * @internal
+ */
+export interface ApiOptions {
+    disabled: {
+        enable: () => any;
+        disable: () => any;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+    checkable: {
+        check: () => any;
+        uncheck: () => any;
+        toggle: () => any;
+        isChecked: () => boolean;
+    };
+}
+/**
+ * Base component interface for internal composition
+ * @category Components
+ * @internal
+ */
+export interface BaseComponent {
+    element: HTMLElement;
+    input?: HTMLInputElement;
+    getValue?: () => string;
+    setValue?: (value: string) => any;
+    setIndeterminate?: (state: boolean) => any;
+    text?: {
+        setText: (content: string) => any;
+        getText: () => string;
+    };
+    on?: (event: string, handler: Function) => any;
+    off?: (event: string, handler: Function) => any;
+    disabled?: {
+        enable: () => any;
+        disable: () => any;
+    };
+    lifecycle?: {
+        destroy: () => void;
+    };
+    checkable?: {
+        check: () => any;
+        uncheck: () => any;
+        toggle: () => any;
+        isChecked: () => boolean;
+    };
+    [key: string]: any;
+}

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

@@ -0,0 +1,49 @@
+import { ChipsComponent, ChipComponent } from './types';
+/**
+ * API options interface - structured by feature area
+ */
+interface ApiOptions {
+    chips: {
+        addChip: (chipConfig: any) => ChipComponent;
+        removeChip: (chipOrIndex: ChipComponent | number) => void;
+        getChips: () => ChipComponent[];
+        getSelectedChips: () => ChipComponent[];
+        getSelectedValues: () => (string | null)[];
+        selectByValue: (values: string | string[], triggerEvent?: boolean) => void;
+        clearSelection: () => void;
+        scrollToChip: (chipOrIndex: ChipComponent | number) => void;
+    };
+    layout: {
+        setScrollable: (isScrollable: boolean) => any;
+        isScrollable: () => boolean;
+        setVertical: (isVertical: boolean) => any;
+        isVertical: () => boolean;
+    };
+    label: {
+        setText: (text: string) => any;
+        getText: () => string;
+        setPosition: (position: 'start' | 'end') => any;
+        getPosition: () => string;
+    };
+    keyboard: {
+        enableKeyboardNavigation: () => void;
+        disableKeyboardNavigation: () => void;
+    };
+    events: {
+        on: (event: string, handler: Function) => void;
+        off: (event: string, handler: Function) => void;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+}
+/**
+ * Enhances a chips component with a streamlined API
+ * @param {ApiOptions} options - API configuration options
+ * @returns {Function} Higher-order function that adds API methods to component
+ * @internal This is an internal utility for the Chips component
+ */
+export declare const withAPI: (options: ApiOptions) => (component: {
+    element: HTMLElement;
+}) => ChipsComponent;
+export {};

package/dist/components/chips/chip/api.d.ts

@@ -0,0 +1,23 @@
+import { ApiOptions, ChipComponent } from './types';
+interface ComponentWithElements {
+    element: HTMLElement;
+    text?: {
+        setText: (content: string) => any;
+        getText: () => string;
+        getElement: () => HTMLElement | null;
+    };
+    icon?: {
+        setIcon: (html: string) => any;
+        getIcon: () => string;
+        getElement: () => HTMLElement | null;
+    };
+    getClass: (name: string) => string;
+}
+/**
+ * Enhances a chip component with API methods
+ * @param {ApiOptions} options - API configuration options
+ * @returns {Function} Higher-order function that adds API methods to component
+ * @internal This is an internal utility for the Chip component
+ */
+export declare const withAPI: ({ disabled, lifecycle }: ApiOptions) => (component: ComponentWithElements) => ChipComponent;
+export {};

package/dist/components/chips/chip/chip.d.ts

@@ -0,0 +1,8 @@
+import { ChipConfig, ChipComponent } from '../types';
+/**
+ * Creates a new Chip component
+ * @param {ChipConfig} config - Chip configuration
+ * @returns {ChipComponent} Chip component instance
+ */
+declare const createChip: (config?: ChipConfig) => ChipComponent;
+export default createChip;

package/dist/components/chips/chip/config.d.ts

@@ -0,0 +1,57 @@
+import { ChipConfig } from '../types';
+/**
+ * Component with required elements and methods
+ * @internal
+ */
+interface BaseComponent {
+    element: HTMLElement;
+    disabled?: {
+        enable: () => any;
+        disable: () => any;
+    };
+    lifecycle?: {
+        destroy: () => void;
+    };
+    [key: string]: any;
+}
+/**
+ * Default configuration for the Chip component
+ */
+export declare const defaultConfig: ChipConfig;
+/**
+ * Creates the base configuration for Chip component
+ * @param {ChipConfig} config - User provided configuration
+ * @returns {ChipConfig} Complete configuration with defaults applied
+ */
+export declare const createBaseConfig: (config?: ChipConfig) => ChipConfig;
+/**
+ * Generates element configuration for the Chip component
+ * @param {ChipConfig} config - Chip configuration
+ * @returns {Object} Element configuration object for withElement
+ */
+export declare const getElementConfig: (config: ChipConfig) => {
+    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;
+};
+/**
+ * Creates API configuration for the Chip component
+ * @param {BaseComponent} comp - Component with disabled and lifecycle features
+ * @returns {Object} API configuration object
+ */
+export declare const getApiConfig: (comp: BaseComponent) => {
+    disabled: {
+        enable: () => any;
+        disable: () => any;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+};
+export default defaultConfig;

package/dist/components/chips/chip/constants.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CSS classes used in the Chip component
+ */
+export declare const CHIP_CLASSES: {
+    /** The main chip container element */
+    readonly ROOT: "chip";
+    /** The chip content container */
+    readonly CONTENT: "chip-content";
+    /** The text label within the chip */
+    readonly LABEL: "chip-label";
+    /** The leading icon container */
+    readonly LEADING_ICON: "chip-leading-icon";
+    /** The trailing icon container */
+    readonly TRAILING_ICON: "chip-trailing-icon";
+    /** Applied when chip is selected */
+    readonly SELECTED: "chip--selected";
+    /** Applied when chip is disabled */
+    readonly DISABLED: "chip--disabled";
+    /** Applied when chip is focused */
+    readonly FOCUSED: "chip--focused";
+    /** Applied when chip is hovered */
+    readonly HOVERED: "chip--hovered";
+};
+/**
+ * Chip states
+ */
+export declare const CHIP_STATES: {
+    /** Default state */
+    readonly DEFAULT: "default";
+    /** Selected state */
+    readonly SELECTED: "selected";
+    /** Disabled state */
+    readonly DISABLED: "disabled";
+    /** Focused state */
+    readonly FOCUSED: "focused";
+    /** Hovered state */
+    readonly HOVERED: "hovered";
+};

package/dist/components/chips/chip/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './chip';
+export * from './config';

package/dist/components/chips/chip/types.d.ts

@@ -0,0 +1,11 @@
+import { ChipConfig, ChipComponent, ChipVariant } from '../types';
+export { ChipConfig, ChipComponent, ChipVariant };
+export interface ApiOptions {
+    disabled: {
+        enable: () => void;
+        disable: () => void;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+}

package/dist/components/chips/chips.d.ts

@@ -0,0 +1,17 @@
+import { ChipsConfig, ChipsComponent } from './types';
+/**
+ * Creates a chips container for grouping related chips
+ *
+ * Chips follows a clear architectural pattern:
+ * 1. Structure definition - Describes the DOM structure declaratively
+ * 2. Feature enhancement - Adds specific capabilities (container, items, etc.)
+ * 3. DOM creation - Turns the structure into actual DOM elements
+ * 4. Controller - Manages behavior, events, and UI rendering
+ * 5. Lifecycle - Handles component lifecycle events
+ * 6. Public API - Exposes a clean, consistent API
+ *
+ * @param {ChipsConfig} config - Chips configuration object
+ * @returns {ChipsComponent} Chips component instance
+ */
+declare const createChips: (config?: ChipsConfig) => ChipsComponent;
+export default createChips;

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

@@ -0,0 +1,67 @@
+import { ChipsConfig } from './types';
+/**
+ * Default configuration for the Chips component
+ */
+export declare const defaultConfig: ChipsConfig;
+/**
+ * Creates the base configuration for Chips component
+ * @param {ChipsConfig} config - User provided configuration
+ * @returns {ChipsConfig} Complete configuration with defaults applied
+ */
+export declare const createBaseConfig: (config?: ChipsConfig) => ChipsConfig;
+/**
+ * Generates element configuration for the Chips component
+ * @param {ChipsConfig} config - Chips configuration
+ * @returns {Object} Element configuration object for withElement
+ */
+export declare const getElementConfig: (config: ChipsConfig) => {
+    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;
+};
+/**
+ * Creates API configuration for the Chips component
+ * @param {Object} comp - Component with chips features
+ * @returns {Object} API configuration object
+ */
+export declare const getApiConfig: (comp: any) => {
+    chips: {
+        addChip: (chipConfig: any) => any;
+        removeChip: (chipOrIndex: any) => any;
+        getChips: () => any;
+        getSelectedChips: () => any;
+        getSelectedValues: () => any;
+        selectByValue: (values: any) => any;
+        clearSelection: () => any;
+        scrollToChip: (chipOrIndex: any) => any;
+    };
+    layout: {
+        setScrollable: (isScrollable: any) => any;
+        isScrollable: () => any;
+        setVertical: (isVertical: any) => any;
+        isVertical: () => any;
+    };
+    label: {
+        setText: (t: any) => any;
+        getText: () => any;
+        setPosition: (p: any) => any;
+        getPosition: () => any;
+    };
+    keyboard: {
+        enableKeyboardNavigation: () => any;
+        disableKeyboardNavigation: () => any;
+    };
+    events: {
+        on: (e: any, h: any) => any;
+        off: (e: any, h: any) => any;
+    };
+    lifecycle: {
+        destroy: () => any;
+    };
+};

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

@@ -0,0 +1,46 @@
+/**
+ * Available variants for the Chip component
+ * @enum {string}
+ */
+export declare const CHIP_VARIANTS: {
+    /** Standard filled chip with solid background */
+    FILLED: string;
+    /** Outlined chip with transparent background and border */
+    OUTLINED: string;
+    /** Elevated chip with shadow */
+    ELEVATED: string;
+    /** Assist chip for suggesting actions */
+    ASSIST: string;
+    /** Filter chip for filtering content */
+    FILTER: string;
+    /** Input chip for representing user input */
+    INPUT: string;
+    /** Suggestion chip for presenting options */
+    SUGGESTION: string;
+};
+/**
+ * Available event types for Chip component
+ * @enum {string}
+ */
+export declare const CHIP_EVENTS: {
+    /** Fired when chip selection state changes */
+    CHANGE: string;
+    /** Fired when chip is selected */
+    SELECT: string;
+    /** Fired when chip is deselected */
+    DESELECT: string;
+    /** Fired when chip is about to be removed */
+    REMOVE: string;
+};
+/**
+ * Available event types for Chips container component
+ * @enum {string}
+ */
+export declare const CHIPS_EVENTS: {
+    /** Fired when any chip selection changes */
+    CHANGE: string;
+    /** Fired when a chip is added to the container */
+    ADD: string;
+    /** Fired when a chip is removed from the container */
+    REMOVE: string;
+};