mtrl 0.6.2 → 0.7.0

package/README.md

@@ -61,6 +61,45 @@ yarn add mtrl
 bun add mtrl
 ```
 
+## Tree-Shaking Optimized Imports
+
+mtrl is optimized for tree-shaking. Constants are exported separately from component creators to minimize bundle size.
+
+### Import Patterns
+
+| Import Type | Path |
+|-------------|------|
+| Component creators | `import { createButton } from 'mtrl'` |
+| Button constants | `import { BUTTON_VARIANTS } from 'mtrl/components/button/constants'` |
+| Slider constants | `import { SLIDER_SIZES } from 'mtrl/components/slider/constants'` |
+| Card constants | `import { CARD_VARIANTS } from 'mtrl/components/card/constants'` |
+| Direct component import | `import createButton from 'mtrl/components/button'` |
+| Core utilities | `import { addClass, removeClass } from 'mtrl/core/dom'` |
+
+### Example
+
+```typescript
+// ✅ Optimal - only imports what you need
+import { createButton } from 'mtrl';
+import { BUTTON_VARIANTS, BUTTON_SIZES } from 'mtrl/components/button/constants';
+
+const button = createButton({
+  text: 'Submit',
+  variant: BUTTON_VARIANTS.FILLED,
+  size: BUTTON_SIZES.LARGE
+});
+
+// ✅ Also optimal - direct component import
+import createSlider from 'mtrl/components/slider';
+import { SLIDER_COLORS } from 'mtrl/components/slider/constants';
+
+const slider = createSlider({
+  color: SLIDER_COLORS.PRIMARY
+});
+```
+
+**Note:** Constants are NOT exported from main entry points. Always import them from the component's constants file.
+
 ## Component Architecture
 
 Let's look at how mtrl components are constructed:

package/dist/README.md

@@ -61,6 +61,45 @@ yarn add mtrl
 bun add mtrl
 ```
 
+## Tree-Shaking Optimized Imports
+
+mtrl is optimized for tree-shaking. Constants are exported separately from component creators to minimize bundle size.
+
+### Import Patterns
+
+| Import Type | Path |
+|-------------|------|
+| Component creators | `import { createButton } from 'mtrl'` |
+| Button constants | `import { BUTTON_VARIANTS } from 'mtrl/components/button/constants'` |
+| Slider constants | `import { SLIDER_SIZES } from 'mtrl/components/slider/constants'` |
+| Card constants | `import { CARD_VARIANTS } from 'mtrl/components/card/constants'` |
+| Direct component import | `import createButton from 'mtrl/components/button'` |
+| Core utilities | `import { addClass, removeClass } from 'mtrl/core/dom'` |
+
+### Example
+
+```typescript
+// ✅ Optimal - only imports what you need
+import { createButton } from 'mtrl';
+import { BUTTON_VARIANTS, BUTTON_SIZES } from 'mtrl/components/button/constants';
+
+const button = createButton({
+  text: 'Submit',
+  variant: BUTTON_VARIANTS.FILLED,
+  size: BUTTON_SIZES.LARGE
+});
+
+// ✅ Also optimal - direct component import
+import createSlider from 'mtrl/components/slider';
+import { SLIDER_COLORS } from 'mtrl/components/slider/constants';
+
+const slider = createSlider({
+  color: SLIDER_COLORS.PRIMARY
+});
+```
+
+**Note:** Constants are NOT exported from main entry points. Always import them from the component's constants file.
+
 ## Component Architecture
 
 Let's look at how mtrl components are constructed:

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

@@ -4,5 +4,5 @@
  * @description A small element that communicates status, shows a count,
  * or highlights an element requiring attention.
  */
-export { default } from './badge';
-export type { BadgeConfig, BadgeComponent, BadgeVariant, BadgeColor, BadgePosition } from './types';
+export { default } from "./badge";
+export type { BadgeConfig, BadgeComponent, BadgeVariant, BadgeColor, BadgePosition, } from "./types";

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

@@ -4,3 +4,4 @@
  */
 export { default } from "./button";
 export type { ButtonConfig, ButtonComponent, ButtonVariant } from "./types";
+export type { ButtonSize, ButtonShape } from "./constants";

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

@@ -69,4 +69,3 @@ export { CardVariant, CardElevationLevel, CardSchema, CardHeaderConfig, CardCont
 export { createCardContent, createCardHeader, createCardActions, createCardMedia, } from "./content";
 export { withAPI } from "./api";
 export { withLoading, withExpandable, withSwipeable, withElevation, } from "./features";
-export { CARD_VARIANTS, CARD_ELEVATIONS, CARD_WIDTHS, CARD_CORNER_RADIUS, CARD_ASPECT_RATIOS, CARD_ACTION_ALIGNMENT, CARD_MEDIA_POSITION, CARD_CLASSES, } from "./constants";

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

@@ -1,4 +1,3 @@
-export { default as createChip } from './chip';
-export { default as createChips } from './chips';
-export * from './constants';
-export type { ChipConfig, ChipComponent, ChipVariant, ChipsConfig, ChipsComponent } from './types';
+export { default as createChip } from "./chip";
+export { default as createChips } from "./chips";
+export type { ChipConfig, ChipComponent, ChipVariant, ChipsConfig, ChipsComponent, } from "./types";

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

@@ -1,3 +1,3 @@
-export { default } from './datepicker';
-export type { DatePickerConfig, DatePickerComponent, DatePickerVariant, DatePickerView, DatePickerSelectionMode } from './types';
-export { DEFAULT_DATE_FORMAT } from './types';
+export { default } from "./datepicker";
+export type { DatePickerConfig, DatePickerComponent, DatePickerVariant, DatePickerView, DatePickerSelectionMode, } from "./types";
+export { DEFAULT_DATE_FORMAT } from "./types";

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

@@ -10,5 +10,5 @@
  * @module components/dialog
  * @category Components
  */
-export { default } from './dialog';
-export { DialogConfig, DialogComponent, DialogButton, DialogEvent, DialogConfirmOptions, DialogSize, DialogAnimation, DialogFooterAlignment, DialogEventType } from './types';
+export { default } from "./dialog";
+export { DialogConfig, DialogComponent, DialogButton, DialogEvent, DialogConfirmOptions, DialogSize, DialogAnimation, DialogFooterAlignment, DialogEventType, } from "./types";

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

@@ -0,0 +1,54 @@
+import { DrawerComponent, DrawerItemConfig } from './types';
+/**
+ * API configuration options for drawer component
+ * @category Components
+ * @internal
+ */
+interface ApiOptions {
+    state: {
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
+        isOpen: () => boolean;
+    };
+    items: {
+        setActive: (id: string) => void;
+        getActive: () => string | null;
+        setItems: (items: DrawerItemConfig[] | undefined) => void;
+        getItems: () => DrawerItemConfig[] | undefined;
+        setBadge: (id: string, badge: string) => void;
+    };
+    headline: {
+        setHeadline: (text: string) => void;
+        getHeadline: () => string;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+}
+/**
+ * Component with required elements and methods for API enhancement
+ * @category Components
+ * @internal
+ */
+interface ComponentWithElements {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    on?: (event: string, handler: Function) => ComponentWithElements;
+    off?: (event: string, handler: Function) => ComponentWithElements;
+    addClass?: (...classes: string[]) => ComponentWithElements;
+}
+/**
+ * Enhances a drawer component with public API methods.
+ * This follows the higher-order function pattern to add public API methods
+ * to the component, making them available to the end user.
+ *
+ * All methods that modify the component return the component for chaining.
+ *
+ * @param {ApiOptions} options - API configuration options
+ * @returns {Function} Higher-order function that adds API methods to component
+ * @category Components
+ * @internal This is an internal utility for the Drawer component
+ */
+export declare const withAPI: ({ state, items, headline, lifecycle }: ApiOptions) => (component: ComponentWithElements) => DrawerComponent;
+export {};

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

@@ -0,0 +1,106 @@
+import { DrawerConfig } from "./types";
+/**
+ * Default configuration for the Drawer component.
+ * These values will be used when not explicitly specified by the user.
+ *
+ * @category Components
+ */
+export declare const defaultConfig: DrawerConfig;
+/**
+ * Creates the base configuration for the Drawer component by merging
+ * user-provided config with default values. Global configuration is
+ * automatically applied by createComponentConfig.
+ *
+ * @param {DrawerConfig} config - User provided configuration
+ * @returns {DrawerConfig} Complete configuration with defaults applied
+ * @category Components
+ * @internal
+ */
+export declare const createBaseConfig: (config?: DrawerConfig) => DrawerConfig;
+/**
+ * Generates element configuration for the Drawer component.
+ * This function creates the necessary attributes and configuration
+ * for the DOM element creation process.
+ *
+ * @param {DrawerConfig} config - Drawer configuration
+ * @returns {Object} Element configuration object for withElement
+ * @category Components
+ * @internal
+ */
+export declare const getElementConfig: (config: DrawerConfig) => {
+    tag: string;
+    componentName: string;
+    attributes: Record<string, any>;
+    className: string[];
+    rawClass: string | string[];
+    id: string;
+    name: string;
+    title: string;
+    tabIndex: number;
+    style: string | Partial<CSSStyleDeclaration>;
+    data: Record<string, string>;
+    role: string;
+    ariaLabel: string;
+    ariaDescribedBy: string;
+    ariaLabelledBy: string;
+    ariaHidden: boolean;
+    html: string;
+    text: string;
+    forwardEvents: Record<string, boolean | ((component: any, event: Event) => boolean)>;
+    interactive: boolean;
+};
+/**
+ * Creates API configuration for the Drawer component.
+ * This connects the core component features (state, items, headline)
+ * to the public API methods exposed to users.
+ *
+ * @param {Object} comp - Component with all features applied
+ * @returns {Object} API configuration object
+ * @category Components
+ * @internal
+ */
+export declare const getApiConfig: (comp: {
+    drawerState: {
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
+        isOpen: () => boolean;
+    };
+    drawerItems: {
+        setActive: (id: string) => void;
+        getActive: () => string | null;
+        setItems: (items: DrawerConfig["items"]) => void;
+        getItems: () => DrawerConfig["items"];
+        setBadge: (id: string, badge: string) => void;
+    };
+    drawerHeadline: {
+        setHeadline: (text: string) => void;
+        getHeadline: () => string;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+    _stateCleanup?: () => void;
+}) => {
+    state: {
+        open: () => void;
+        close: () => void;
+        toggle: () => void;
+        isOpen: () => boolean;
+    };
+    items: {
+        setActive: (id: string) => void;
+        getActive: () => string;
+        setItems: (items: DrawerConfig["items"]) => void;
+        getItems: () => import("./types").DrawerItemConfig[];
+        setBadge: (id: string, badge: string) => void;
+    };
+    headline: {
+        setHeadline: (text: string) => void;
+        getHeadline: () => string;
+    };
+    lifecycle: {
+        destroy: () => void;
+    };
+};
+export default defaultConfig;

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

@@ -0,0 +1,97 @@
+/**
+ * Drawer variants matching MD3 navigation drawer specification
+ */
+export declare const DRAWER_VARIANTS: {
+    /** Standard drawer — inline, can be permanently visible or toggled */
+    readonly STANDARD: "standard";
+    /** Modal drawer — overlays content with scrim, for compact/medium screens */
+    readonly MODAL: "modal";
+};
+/**
+ * Drawer positions (anchor edge)
+ */
+export declare const DRAWER_POSITIONS: {
+    /** Start edge (left in LTR, right in RTL) — default per MD3 */
+    readonly START: "start";
+    /** End edge (right in LTR, left in RTL) */
+    readonly END: "end";
+};
+/**
+ * Drawer item types for the items configuration array
+ */
+export declare const DRAWER_ITEM_TYPES: {
+    /** Navigation destination item */
+    readonly ITEM: "item";
+    /** Visual separator between groups */
+    readonly DIVIDER: "divider";
+    /** Section label / subhead for grouping */
+    readonly SECTION: "section";
+};
+/**
+ * Drawer events
+ */
+export declare const DRAWER_EVENTS: {
+    /** Fired when the drawer opens */
+    readonly OPEN: "open";
+    /** Fired when the drawer closes */
+    readonly CLOSE: "close";
+    /** Fired when a navigation item is selected */
+    readonly SELECT: "select";
+};
+/**
+ * CSS classes used by the drawer component
+ */
+export declare const DRAWER_CLASSES: {
+    /** Root container */
+    readonly ROOT: "drawer";
+    /** Scrim overlay (modal variant only) */
+    readonly SCRIM: "drawer__scrim";
+    /** Inner sheet / panel */
+    readonly SHEET: "drawer__sheet";
+    /** Headline text */
+    readonly HEADLINE: "drawer__headline";
+    /** Scrollable items container */
+    readonly ITEMS: "drawer__items";
+    /** Single navigation item */
+    readonly ITEM: "drawer__item";
+    /** Item icon */
+    readonly ITEM_ICON: "drawer__item-icon";
+    /** Item label text */
+    readonly ITEM_LABEL: "drawer__item-label";
+    /** Item badge */
+    readonly ITEM_BADGE: "drawer__item-badge";
+    /** Active indicator shape */
+    readonly ACTIVE_INDICATOR: "drawer__active-indicator";
+    /** Dense/compact variant */
+    readonly DENSE: "drawer--dense";
+    /** Divider separator */
+    readonly DIVIDER: "drawer__divider";
+    /** Section label */
+    readonly SECTION_LABEL: "drawer__section-label";
+};
+/**
+ * Default animation configuration
+ */
+export declare const DRAWER_ANIMATION: {
+    /** Animation duration in milliseconds */
+    readonly DURATION: 300;
+    /** Easing for opening */
+    readonly EASING_OPEN: "cubic-bezier(0.0, 0.0, 0.2, 1.0)";
+    /** Easing for closing */
+    readonly EASING_CLOSE: "cubic-bezier(0.3, 0.0, 1.0, 1.0)";
+};
+/**
+ * Drawer default values
+ */
+export declare const DRAWER_DEFAULTS: {
+    /** Default variant */
+    readonly VARIANT: "standard";
+    /** Default position */
+    readonly POSITION: "start";
+    /** Whether drawer is open by default */
+    readonly OPEN: false;
+    /** Whether modal can be dismissed via scrim */
+    readonly DISMISSIBLE: true;
+    /** Default drawer width in pixels */
+    readonly WIDTH: 360;
+};

package/dist/components/drawer/drawer.d.ts

@@ -0,0 +1,59 @@
+import { DrawerConfig } from "./types";
+/**
+ * Creates a new Drawer component with the specified configuration.
+ *
+ * The Drawer component implements Material Design 3 navigation drawer with
+ * support for standard (inline) and modal (overlay) variants. It provides
+ * navigation destinations with icons, labels, badges, dividers, and section
+ * labels following the MD3 specification.
+ *
+ * The Drawer component is created using a functional composition pattern,
+ * applying various features through the pipe function.
+ *
+ * @param {DrawerConfig} config - Configuration options for the drawer
+ *  This can include variant, items, headline, position, open state,
+ *  and other drawer properties. See {@link DrawerConfig} for available options.
+ *
+ * @returns {DrawerComponent} A fully configured drawer component instance with
+ *  all requested features applied. The returned component has methods for
+ *  state management, item selection, and lifecycle management.
+ *
+ * @throws {Error} Throws an error if drawer creation fails for any reason
+ *
+ * @example
+ * ```ts
+ * // Create a standard navigation drawer
+ * const drawer = createDrawer({
+ *   variant: 'standard',
+ *   headline: 'Mail',
+ *   open: true,
+ *   items: [
+ *     { id: 'inbox', label: 'Inbox', icon: '<svg>...</svg>', badge: '24', active: true },
+ *     { id: 'outbox', label: 'Outbox', icon: '<svg>...</svg>' },
+ *     { type: 'divider' },
+ *     { type: 'section', label: 'Labels' },
+ *     { id: 'family', label: 'Family', icon: '<svg>...</svg>' },
+ *   ],
+ *   onSelect: (event) => console.log('Selected:', event.id),
+ * });
+ *
+ * document.body.appendChild(drawer.element);
+ *
+ * // Create a modal drawer
+ * const modalDrawer = createDrawer({
+ *   variant: 'modal',
+ *   headline: 'Navigation',
+ *   items: [
+ *     { id: 'home', label: 'Home', icon: '<svg>...</svg>', active: true },
+ *     { id: 'settings', label: 'Settings', icon: '<svg>...</svg>' },
+ *   ],
+ * });
+ *
+ * document.body.appendChild(modalDrawer.element);
+ * modalDrawer.open();
+ * ```
+ *
+ * @category Components
+ */
+declare const createDrawer: (config?: DrawerConfig) => any;
+export default createDrawer;

package/dist/components/drawer/features/headline.d.ts

@@ -0,0 +1,17 @@
+import { DrawerConfig } from "../types";
+/**
+ * Component shape expected by withHeadline
+ */
+interface HeadlineBaseComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    [key: string]: unknown;
+}
+/**
+ * Adds headline management to the drawer component
+ *
+ * @param config - Drawer configuration
+ * @returns Component enhancer function
+ */
+export declare const withHeadline: (config: DrawerConfig) => (component: HeadlineBaseComponent) => HeadlineBaseComponent;
+export {};

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

@@ -0,0 +1,3 @@
+export { withItems } from "./items";
+export { withState } from "./state";
+export { withHeadline } from "./headline";

package/dist/components/drawer/features/items.d.ts

@@ -0,0 +1,18 @@
+import { DrawerConfig } from "../types";
+/**
+ * Component shape expected by withItems
+ */
+interface ItemsBaseComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    [key: string]: unknown;
+}
+/**
+ * Adds item management functionality to the drawer component
+ *
+ * @param config - Drawer configuration
+ * @returns Component enhancer function
+ */
+export declare const withItems: (config: DrawerConfig) => (component: ItemsBaseComponent) => ItemsBaseComponent;
+export {};

package/dist/components/drawer/features/state.d.ts

@@ -0,0 +1,18 @@
+import { DrawerConfig } from "../types";
+/**
+ * Component shape expected by withState
+ */
+interface StateBaseComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    emit: (event: string, data?: unknown) => void;
+    [key: string]: unknown;
+}
+/**
+ * Adds open/close state management, scrim, and keyboard dismiss to the drawer
+ *
+ * @param config - Drawer configuration
+ * @returns Component enhancer function
+ */
+export declare const withState: (config: DrawerConfig) => (component: StateBaseComponent) => StateBaseComponent;
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Drawer component module
+ * @module components/drawer
+ */
+export { default } from './drawer';
+export type { DrawerConfig, DrawerComponent, DrawerVariant, DrawerPosition, DrawerItemConfig, DrawerSelectEvent, } from './types';