mtrl 0.3.8 → 0.4.0

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

@@ -0,0 +1,165 @@
+/**
+ * Carousel layout types as defined by Material Design 3
+ *
+ * Material Design 3 defines specific layout patterns for carousels
+ * to accommodate different content presentation needs.
+ *
+ * @category Components
+ * @see https://material.io/components/carousel
+ */
+export declare const CAROUSEL_LAYOUTS: {
+    /**
+     * Multi-browse layout: Best for browsing many visual items at once
+     * Ideal for photo galleries, product collections, or event feeds
+     * Shows multiple items in a single view with varying sizes
+     */
+    readonly MULTI_BROWSE: "multi-browse";
+    /**
+     * Uncontained layout: For highly customized or text-heavy carousels
+     * Traditional horizontal scrolling behavior without special styling
+     * Content can extend beyond viewport edges with consistent sizing
+     */
+    readonly UNCONTAINED: "uncontained";
+    /**
+     * Hero layout: For spotlighting very large visual items
+     * Highlights featured content with a large central item
+     * Shows a partial preview of the next/previous items
+     */
+    readonly HERO: "hero";
+    /**
+     * Full-screen layout: For immersive vertical-scrolling experiences
+     * Takes up entire viewport with snap scrolling between items
+     * Suited for immersive content or focused presentations
+     */
+    readonly FULL_SCREEN: "full-screen";
+};
+/**
+ * Carousel scroll behaviors
+ *
+ * Controls how scrolling behaves when moving between items.
+ * Each layout type has a recommended default behavior.
+ *
+ * @category Components
+ */
+export declare const CAROUSEL_SCROLL_BEHAVIORS: {
+    /**
+     * Default: Standard smooth scrolling without snapping
+     * Users can stop at any position between items
+     * Recommended for uncontained layouts and content browsing
+     */
+    readonly DEFAULT: "default";
+    /**
+     * Snap: Items snap to predefined positions when scrolling
+     * Ensures items are properly aligned for viewing
+     * Recommended for multi-browse, hero, and full-screen layouts
+     */
+    readonly SNAP: "snap";
+};
+/**
+ * Carousel item size constants
+ *
+ * Defines the available sizes for carousel items.
+ * These are used to control the relative sizing of
+ * items within different carousel layouts.
+ *
+ * @category Components
+ */
+export declare const CAROUSEL_ITEM_SIZES: {
+    /** Large featured items (primary content) */
+    readonly LARGE: "large";
+    /** Medium-sized items (secondary content) */
+    readonly MEDIUM: "medium";
+    /** Small items (tertiary content or thumbnails) */
+    readonly SMALL: "small";
+};
+/**
+ * Transition effects for carousel slides
+ *
+ * Controls the visual transition when moving between slides.
+ *
+ * @category Components
+ */
+export declare const CAROUSEL_TRANSITIONS: {
+    /** Horizontal sliding animation (default) */
+    readonly SLIDE: "slide";
+    /** Fade in/out transition between slides */
+    readonly FADE: "fade";
+    /** No animation, immediate change */
+    readonly NONE: "none";
+};
+/**
+ * Event names for the carousel component
+ *
+ * These events can be listened to using the carousel's
+ * `on()` method for custom behavior.
+ *
+ * @example
+ * carousel.on(CAROUSEL_EVENTS.SLIDE_CHANGED, (index) => {
+ *   console.log(`Now showing slide ${index}`);
+ * });
+ *
+ * @category Components
+ */
+export declare const CAROUSEL_EVENTS: {
+    /** Fired when a slide change begins */
+    readonly SLIDE_CHANGE: "slide-change";
+    /** Fired when a slide change completes */
+    readonly SLIDE_CHANGED: "slide-changed";
+    /** Fired when the carousel is resized */
+    readonly RESIZE: "resize";
+};
+/**
+ * Default values for carousel configuration
+ *
+ * These values will be used when not explicitly specified
+ * in the configuration object passed to createCarousel().
+ *
+ * @category Components
+ */
+export declare const CAROUSEL_DEFAULTS: {
+    /** Start displaying from the first slide (index 0) */
+    readonly INITIAL_SLIDE: 0;
+    /** Enable infinite looping by default */
+    readonly LOOP: true;
+    /** Default transition effect is sliding */
+    readonly TRANSITION: "slide";
+    /** Transition duration in milliseconds */
+    readonly TRANSITION_DURATION: 300;
+    /** Border radius for slides following Material Design 3 */
+    readonly BORDER_RADIUS: 16;
+    /** Gap between slides in pixels */
+    readonly GAP: 8;
+    /** Default layout is multi-browse for browsing visual content */
+    readonly LAYOUT: "multi-browse";
+    /** Default scroll behavior is snap for controlled movement */
+    readonly SCROLL_BEHAVIOR: "snap";
+    /** Small item width in pixels (40-56dp range per MD3 guidelines) */
+    readonly SMALL_ITEM_WIDTH: 48;
+    /**
+     * Item widths for different layouts in pixels
+     * These values are optimized for each layout type
+     * based on Material Design 3 guidelines
+     */
+    readonly ITEM_WIDTHS: {
+        readonly "multi-browse": {
+            readonly LARGE: 240;
+            readonly MEDIUM: 180;
+            readonly SMALL: 48;
+        };
+        readonly uncontained: {
+            readonly LARGE: 240;
+            readonly MEDIUM: 240;
+            readonly SMALL: 240;
+        };
+        readonly hero: {
+            readonly LARGE: 300;
+            readonly MEDIUM: 240;
+            readonly SMALL: 48;
+        };
+        readonly "full-screen": {
+            readonly LARGE: "100%";
+            readonly MEDIUM: "100%";
+            readonly SMALL: "100%";
+        };
+    };
+};

package/dist/components/carousel/features/drag.d.ts

@@ -0,0 +1,8 @@
+import { CarouselConfig } from '../types';
+/**
+ * Adds drag functionality to the carousel component with Material Design 3 scroll behavior support
+ *
+ * @param {CarouselConfig} config - Carousel configuration
+ * @returns {Function} Higher-order function that adds drag navigation feature
+ */
+export declare const withDrag: (config: CarouselConfig) => (component: any) => any;

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

@@ -1,8 +1,5 @@
-// src/components/carousel/features/index.ts
-
 /**
  * Entry point for Carousel component features
  */
-
 export { withSlides } from './slides';
-export { withDrag } from './drag';
+export { withDrag } from './drag';

package/dist/components/carousel/features/slides.d.ts

@@ -0,0 +1,8 @@
+import { CarouselConfig } from '../types';
+/**
+ * Adds slide functionality to the carousel component with Material Design 3 layout types support
+ *
+ * @param {CarouselConfig} config - Carousel configuration
+ * @returns {Function} Higher-order function that adds slides feature
+ */
+export declare const withSlides: (config: CarouselConfig) => (component: any) => any;

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

@@ -1,56 +1,37 @@
-// src/components/carousel/index.ts
-
 /**
  * Carousel Component Module
- * 
+ *
  * A Material Design 3 compatible carousel implementation that supports
  * various layout types and scroll behaviors to accommodate different
  * content presentation needs.
- * 
+ *
  * @module components/carousel
  * @category Components
  */
-
-// Main factory function
 export { default } from './carousel';
-
 /**
  * Constants for carousel configuration
- * 
+ *
  * Use these constants instead of string literals for better
  * code completion, type safety, and to follow best practices.
- * 
+ *
  * @example
  * import { createCarousel, CAROUSEL_LAYOUTS } from 'mtrl';
- * 
+ *
  * const carousel = createCarousel({
  *   layout: CAROUSEL_LAYOUTS.MULTI_BROWSE,
  *   // Other configuration options...
  * });
- * 
+ *
  * @category Components
  */
-export { 
-  CAROUSEL_LAYOUTS, 
-  CAROUSEL_SCROLL_BEHAVIORS, 
-  CAROUSEL_TRANSITIONS, 
-  CAROUSEL_EVENTS, 
-  CAROUSEL_DEFAULTS,
-  CAROUSEL_ITEM_SIZES
-} from './constants';
-
+export { CAROUSEL_LAYOUTS, CAROUSEL_SCROLL_BEHAVIORS, CAROUSEL_TRANSITIONS, CAROUSEL_EVENTS, CAROUSEL_DEFAULTS, CAROUSEL_ITEM_SIZES } from './constants';
 /**
  * TypeScript types and interfaces for the Carousel component
- * 
+ *
  * These provide proper type checking and IntelliSense support
  * when using the carousel component in TypeScript projects.
- * 
+ *
  * @category Components
  */
-export { 
-  CarouselConfig, 
-  CarouselComponent, 
-  CarouselSlide,
-  CarouselLayout,
-  CarouselScrollBehavior
-} from './types';
+export { CarouselConfig, CarouselComponent, CarouselSlide, CarouselLayout, CarouselScrollBehavior } from './types';

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

@@ -0,0 +1,276 @@
+/**
+ * Material Design 3 Carousel Layout Types
+ * @category Components
+ */
+export type CarouselLayout = 
+/** Best for browsing many visual items at once (photos, event feeds) */
+'multi-browse'
+/** For highly customized or text-heavy carousels (traditional behavior) */
+ | 'uncontained'
+/** For spotlighting very large visual items (featured content) */
+ | 'hero'
+/** For immersive vertical-scrolling experiences */
+ | 'full-screen';
+/**
+ * Carousel Scrolling Behaviors
+ * @category Components
+ */
+export type CarouselScrollBehavior = 
+/** Standard scrolling without snapping, recommended for uncontained layouts */
+'default'
+/** Items snap to carousel layout, recommended for multi-browse, hero, and full-screen layouts */
+ | 'snap';
+/**
+ * Slide data interface
+ * @category Components
+ */
+export interface CarouselSlide {
+    /** Image URL for the slide */
+    image: string;
+    /** Optional title text for the slide */
+    title?: string;
+    /** Optional accent color in hexadecimal or RGB format */
+    accent?: string;
+    /** Optional description text */
+    description?: string;
+    /** Optional action button text */
+    buttonText?: string;
+    /** Optional action button URL */
+    buttonUrl?: string;
+    /** Optional size designation for the item, will be auto-calculated if not provided */
+    size?: 'large' | 'medium' | 'small';
+}
+/**
+ * Configuration interface for the Carousel component
+ * @category Components
+ */
+export interface CarouselConfig {
+    /**
+     * Initial slide index to display
+     * @default 0
+     */
+    initialSlide?: number;
+    /**
+     * Whether to loop the carousel
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Transition effect for slide changes
+     * @default 'slide'
+     */
+    transition?: 'slide' | 'fade' | 'none';
+    /**
+     * Transition duration in milliseconds
+     * @default 300
+     */
+    transitionDuration?: number;
+    /**
+     * Slides configuration for the carousel
+     * @example [{ image: 'image1.jpg', title: 'Title', accent: '#E6E1E5' }]
+     */
+    slides?: CarouselSlide[];
+    /**
+     * Border radius for slides in pixels
+     * @default 16
+     */
+    borderRadius?: number;
+    /**
+     * Gap between slides in pixels
+     * @default 8
+     */
+    gap?: number;
+    /**
+     * Additional CSS classes to add to the carousel
+     * @example 'hero-carousel featured-carousel'
+     */
+    class?: string;
+    /**
+     * Component prefix for class names
+     * @default 'carousel'
+     */
+    prefix?: string;
+    /**
+     * Component name used in class generation
+     * @default 'carousel'
+     */
+    componentName?: string;
+    /**
+     * Callback for "Show all" action when present
+     */
+    onShowAll?: () => void;
+    /**
+     * Whether to show a "Show all" link at the end
+     * MD3 recommends adding this for accessibility on vertical scrolling pages
+     * @default true
+     */
+    showAllLink?: boolean;
+    /**
+     * MD3 carousel layout type
+     * @default 'multi-browse'
+     */
+    layout?: CarouselLayout;
+    /**
+     * Scrolling behavior for the carousel
+     * @default depends on layout (snap for multi-browse, hero, full-screen; default for uncontained)
+     */
+    scrollBehavior?: CarouselScrollBehavior;
+    /**
+     * Whether to center the carousel items (applies to hero layout)
+     * @default false
+     */
+    centered?: boolean;
+    /**
+     * Maximum width of large items (affects how many items fit on screen)
+     * Large items should remain big enough to be easily recognizable
+     */
+    largeItemMaxWidth?: number;
+    /**
+     * Width for small items in pixels
+     * @default 40-56dp range as per MD3 guidelines
+     */
+    smallItemWidth?: number;
+}
+/**
+ * Slides API interface for carousel
+ * @category Components
+ */
+export interface SlidesAPI {
+    /**
+     * Adds a new slide to the carousel
+     * @param slide - CarouselSlide object with slide data
+     * @param index - Optional position to insert the slide
+     * @returns The slides API for chaining
+     */
+    addSlide: (slide: CarouselSlide, index?: number) => SlidesAPI;
+    /**
+     * Removes a slide at the specified index
+     * @param index - Index of the slide to remove
+     * @returns The slides API for chaining
+     */
+    removeSlide: (index: number) => SlidesAPI;
+    /**
+     * Updates an existing slide
+     * @param index - Index of the slide to update
+     * @param slide - Updated CarouselSlide object
+     * @returns The slides API for chaining
+     */
+    updateSlide: (index: number, slide: CarouselSlide) => SlidesAPI;
+    /**
+     * Gets a slide at the specified index
+     * @param index - Index of the slide
+     * @returns CarouselSlide object or null if not found
+     */
+    getSlide: (index: number) => CarouselSlide | null;
+    /**
+     * Gets the total number of slides
+     * @returns Number of slides
+     */
+    getCount: () => number;
+    /**
+     * Gets all slide elements
+     * @returns Array of slide elements
+     */
+    getElements: () => HTMLElement[];
+}
+/**
+ * Carousel component interface
+ * @category Components
+ */
+export interface CarouselComponent {
+    /** The carousel's root DOM element */
+    element: HTMLElement;
+    /** API for managing carousel slides */
+    slides: SlidesAPI;
+    /** API for managing component lifecycle */
+    lifecycle: {
+        /** Destroys the component and cleans up resources */
+        destroy: () => void;
+    };
+    /**
+     * Gets a class name with the component's prefix
+     * @param name - Base class name
+     * @returns Prefixed class name
+     */
+    getClass: (name: string) => string;
+    /**
+     * Goes to the next slide
+     * @returns The carousel component for chaining
+     */
+    next: () => CarouselComponent;
+    /**
+     * Goes to the previous slide
+     * @returns The carousel component for chaining
+     */
+    prev: () => CarouselComponent;
+    /**
+     * Goes to a specific slide
+     * @param index - Slide index
+     * @returns The carousel component for chaining
+     */
+    goTo: (index: number) => CarouselComponent;
+    /**
+     * Gets the current slide index
+     * @returns Current slide index
+     */
+    getCurrentSlide: () => number;
+    /**
+     * Adds a new slide
+     * @param slide - CarouselSlide object with slide data
+     * @param index - Optional position to insert the slide
+     * @returns The carousel component for chaining
+     */
+    addSlide: (slide: CarouselSlide, index?: number) => CarouselComponent;
+    /**
+     * Removes a slide
+     * @param index - Index of the slide to remove
+     * @returns The carousel component for chaining
+     */
+    removeSlide: (index: number) => CarouselComponent;
+    /**
+     * Enables the loop mode
+     * @returns The carousel component for chaining
+     */
+    enableLoop: () => CarouselComponent;
+    /**
+     * Disables the loop mode
+     * @returns The carousel component for chaining
+     */
+    disableLoop: () => CarouselComponent;
+    /**
+     * Sets the carousel border radius
+     * @param radius - Border radius in pixels
+     * @returns The carousel component for chaining
+     */
+    setBorderRadius: (radius: number) => CarouselComponent;
+    /**
+     * Sets the gap between slides
+     * @param gap - Gap size in pixels
+     * @returns The carousel component for chaining
+     */
+    setGap: (gap: number) => CarouselComponent;
+    /**
+     * Destroys the carousel component and cleans up resources
+     */
+    destroy: () => void;
+    /**
+     * Adds an event listener to the carousel
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns The carousel component for chaining
+     */
+    on: (event: string, handler: Function) => CarouselComponent;
+    /**
+     * Removes an event listener from the carousel
+     * @param event - Event name
+     * @param handler - Event handler function
+     * @returns The carousel component for chaining
+     */
+    off: (event: string, handler: Function) => CarouselComponent;
+    /**
+     * Adds CSS classes to the carousel element
+     * @param classes - One or more class names to add
+     * @returns The carousel component for chaining
+     */
+    addClass: (...classes: string[]) => CarouselComponent;
+}

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

@@ -0,0 +1,7 @@
+import { BaseComponent, CheckboxComponent, ApiOptions } from './types';
+/**
+ * Enhances checkbox component with API methods
+ * @param {ApiOptions} options - API configuration
+ * @returns {Function} Higher-order function that adds API methods to component
+ */
+export declare const withAPI: ({ disabled, lifecycle, checkable }: ApiOptions) => (component: BaseComponent) => CheckboxComponent;

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

@@ -0,0 +1,65 @@
+/**
+ * Checkbox Component Implementation
+ *
+ * This module implements a Material Design 3 checkbox component
+ * with support for different visual variants, indeterminate state,
+ * and configurable label positioning.
+ *
+ * @module components/checkbox
+ * @category Components
+ */
+import { CheckboxConfig, CheckboxComponent } from './types';
+/**
+ * Creates a new Checkbox component with the specified configuration.
+ *
+ * Checkboxes allow users to select one or more items from a set,
+ * or to toggle a single option on or off. This implementation follows
+ * Material Design 3 guidelines for accessible, customizable checkboxes.
+ *
+ * @param {CheckboxConfig} config - Configuration options for the checkbox
+ * @returns {CheckboxComponent} A fully configured checkbox component instance
+ * @throws {Error} Throws an error if checkbox creation fails
+ *
+ * @category Components
+ *
+ * @example
+ * // Create a basic checkbox
+ * const checkbox = createCheckbox({
+ *   label: 'Accept terms and conditions',
+ *   name: 'accept-terms'
+ * });
+ *
+ * document.querySelector('.form').appendChild(checkbox.element);
+ *
+ * @example
+ * // Create a pre-checked checkbox with custom styling
+ * const checkbox = createCheckbox({
+ *   label: 'Remember me',
+ *   checked: true,
+ *   variant: 'outlined',
+ *   labelPosition: 'start'
+ * });
+ *
+ * // Add event listener
+ * checkbox.on('change', (e) => {
+ *   console.log('Checkbox changed:', e.target.checked);
+ * });
+ *
+ * @example
+ * // Create an indeterminate checkbox for "select all" functionality
+ * const selectAll = createCheckbox({
+ *   label: 'Select All',
+ *   indeterminate: true
+ * });
+ *
+ * // Later, based on selections:
+ * if (allSelected) {
+ *   selectAll.check();
+ * } else if (noneSelected) {
+ *   selectAll.uncheck();
+ * } else {
+ *   selectAll.setIndeterminate(true);
+ * }
+ */
+declare const createCheckbox: (config?: CheckboxConfig) => CheckboxComponent;
+export default createCheckbox;

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

@@ -0,0 +1,44 @@
+import { CheckboxConfig, BaseComponent, ApiOptions } from './types';
+/**
+ * Default configuration for the Checkbox component
+ */
+export declare const defaultConfig: CheckboxConfig;
+/**
+ * Creates the base configuration for Checkbox component
+ * @param {CheckboxConfig} config - User provided configuration
+ * @returns {CheckboxConfig} Complete configuration with defaults applied
+ */
+export declare const createBaseConfig: (config?: CheckboxConfig) => CheckboxConfig;
+/**
+ * Generates element configuration for the Checkbox component
+ * @param {CheckboxConfig} config - Checkbox configuration
+ * @returns {Object} Element configuration object for withElement
+ */
+export declare const getElementConfig: (config: CheckboxConfig) => {
+    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;
+};
+/**
+ * Adds check icon to checkbox
+ * @param {CheckboxConfig} config - Component configuration
+ */
+export declare const withCheckIcon: (config: CheckboxConfig) => (component: BaseComponent) => BaseComponent;
+/**
+ * Applies label position class to the component
+ * @param {CheckboxConfig} config - Component configuration
+ */
+export declare const withLabelPosition: (config: CheckboxConfig) => (component: BaseComponent) => BaseComponent;
+/**
+ * Creates API configuration for the Checkbox component
+ * @param {BaseComponent} comp - Component with disabled, lifecycle, and checkable features
+ * @returns {ApiOptions} API configuration object
+ */
+export declare const getApiConfig: (comp: BaseComponent) => ApiOptions;
+export default defaultConfig;