mtrl 0.3.1 → 0.3.2

package/src/components/carousel/carousel.ts

@@ -1,14 +1,18 @@
-// src/components/carousel/factory.ts
+// src/components/carousel/carousel.ts
 /**
- * Carousel Factory - Creates different types of carousel layouts based on Material Design 3 guidelines
+ * Creates carousels with different layouts based on Material Design 3 guidelines.
  * 
- * This factory implements four carousel layout types:
- * - Multi-browse: For browsing many visual items at once (photos, event feeds)
- * - Uncontained: For highly customized or text-heavy carousels (traditional behavior)
- * - Hero: For spotlighting very large visual items (featured content)
+ * This module implements a carousel component that supports four layout types:
+ * - Multi-browse: For browsing many visual items at once (photos, feeds)
+ * - Uncontained: For customized or text-heavy carousels (traditional)
+ * - Hero: For spotlighting large visual items (featured content)
  * - Full-screen: For immersive vertical-scrolling experiences
  * 
- * @module CarouselFactory
+ * Each layout is optimized for different content types and presentation needs,
+ * following the Material Design 3 component guidelines.
+ * 
+ * @module components/carousel
+ * @category Components
  */
 
 import { pipe } from '../../core/compose';
@@ -26,15 +30,22 @@ import { createBaseConfig, getElementConfig } from './config';
 import { CAROUSEL_DEFAULTS } from './constants';
 
 /**
- * Creates a new carousel with specified layout and scroll behavior
+ * Creates a new carousel component with the specified configuration.
  * 
- * @param {CarouselConfig} config - Carousel configuration
- * @returns {CarouselComponent} The configured carousel component
+ * The carousel supports different layout types for various content
+ * presentation needs, from image galleries to full-screen experiences.
+ * It handles gesture interactions, keyboard navigation, and responsive
+ * behavior following Material Design 3 guidelines.
+ * 
+ * @param {CarouselConfig} config - Configuration options for the carousel
+ * @returns {CarouselComponent} A fully configured carousel component instance
+ * @throws {Error} Throws an error if carousel creation fails
+ * 
+ * @category Components
  * 
  * @example
- * ```typescript
- * // Create a multi-browse carousel with snap scrolling
- * const carousel = createCarousel({
+ * // Create a multi-browse carousel for a photo gallery
+ * const photoGallery = createCarousel({
  *   layout: 'multi-browse',
  *   scrollBehavior: 'snap',
  *   slides: [
@@ -44,9 +55,36 @@ import { CAROUSEL_DEFAULTS } from './constants';
  *   showAllLink: true
  * });
  * 
- * // Add the carousel to the DOM
- * document.getElementById('container').appendChild(carousel.element);
- * ```
+ * document.getElementById('gallery-container').appendChild(photoGallery.element);
+ * 
+ * @example
+ * // Create a hero carousel for featured content
+ * const featuredContent = createCarousel({
+ *   layout: 'hero',
+ *   centered: true,
+ *   gap: 16,
+ *   slides: [
+ *     { image: 'hero1.jpg', title: 'Featured Story', buttonText: 'Read More' },
+ *     { image: 'hero2.jpg', title: 'Special Offer', buttonText: 'Shop Now' }
+ *   ]
+ * });
+ * 
+ * // Listen for slide changes
+ * featuredContent.on('slide-changed', (index) => {
+ *   console.log(`Now showing featured item ${index}`);
+ * });
+ * 
+ * @example
+ * // Create a full-screen immersive carousel
+ * const storyViewer = createCarousel({
+ *   layout: 'full-screen',
+ *   loop: false,
+ *   transition: 'fade',
+ *   slides: [
+ *     { image: 'story1.jpg', description: 'Chapter 1' },
+ *     { image: 'story2.jpg', description: 'Chapter 2' }
+ *   ]
+ * });
  */
 export const createCarousel = (config: CarouselConfig = {}): CarouselComponent => {
   // Ensure layout and scrollBehavior have defaults
@@ -106,72 +144,98 @@ export const createCarousel = (config: CarouselConfig = {}): CarouselComponent =
 };
 
 /**
- * Get default scroll behavior based on layout type
+ * Determines the optimal scroll behavior based on the selected layout type.
+ * 
+ * Material Design 3 recommendations suggest different scroll behaviors
+ * for each layout type to provide the best user experience.
  * 
  * @param {CarouselLayout} layout - Carousel layout type
- * @returns {CarouselScrollBehavior} Recommended scroll behavior
+ * @returns {CarouselScrollBehavior} The recommended scroll behavior
+ * @category Components
+ * @internal
  */
 function getDefaultScrollBehavior(layout: CarouselLayout): CarouselScrollBehavior {
   switch (layout) {
+    // These layouts work best with snap scrolling for defined stops
     case 'multi-browse':
     case 'hero':
     case 'full-screen':
       return 'snap';
+      
+    // Uncontained layout works best with standard scrolling
     case 'uncontained':
       return 'default';
+      
+    // Default to standard scrolling for unknown layouts
     default:
       return 'default';
   }
 }
 
 /**
- * Apply layout-specific configurations to the component
+ * Applies layout-specific configurations and styling to the carousel component.
+ * 
+ * Each carousel layout has specific CSS properties, data attributes,
+ * and behaviors that optimize it for different content types.
+ * This function sets up those properties based on the selected layout.
  * 
  * @param {any} component - The component to configure
  * @param {CarouselConfig} config - Carousel configuration
+ * @category Components
+ * @internal
  */
 function applyLayoutConfig(component: any, config: CarouselConfig): void {
-  // Add layout-specific class
+  // Add layout-specific class for CSS targeting
   component.element.classList.add(`${component.getClass('carousel')}-layout--${config.layout}`);
   
-  // Apply additional layout-specific styling
+  // Apply layout-specific configurations
   switch (config.layout) {
     case 'multi-browse':
-      // Configure for browsing many items with different sizes
+      // Multi-browse layout: For browsing many visual items at once
+      // Shows items of varying sizes with parallax scrolling effect
       component.element.dataset.enableParallax = 'true';
+      component.element.dataset.layout = 'multi-browse';
       break;
       
     case 'uncontained':
-      // Configure for same-sized items that flow past edge
+      // Uncontained layout: For text-heavy or consistent-sized items
+      // Allows content to flow past the viewport edges
       component.element.style.overflow = 'visible';
+      component.element.dataset.layout = 'uncontained';
       break;
       
     case 'hero':
-      // Configure for spotlight content with preview of next item
+      // Hero layout: For spotlighting featured content
+      // Large central item with preview of adjacent items
       component.element.dataset.largeItemFocus = 'true';
+      component.element.dataset.layout = 'hero';
       
-      // Apply center alignment if specified
+      // Optionally center items for balanced presentation
       if (config.centered) {
         component.element.dataset.centered = 'true';
       }
       break;
       
     case 'full-screen':
-      // Configure for immersive experience
+      // Full-screen layout: For immersive experiences
+      // Takes up entire viewport and supports vertical scrolling
       component.element.style.width = '100%';
       component.element.style.height = '100%';
       component.element.style.maxWidth = '100vw';
       component.element.style.maxHeight = '100vh';
       component.element.dataset.verticalScroll = 'true';
+      component.element.dataset.layout = 'full-screen';
       
-      // Force snap scrolling for full-screen layout
+      // Full-screen layout always uses snap scrolling for controlled navigation
       config.scrollBehavior = 'snap';
       break;
   }
   
-  // Apply scroll behavior
+  // Apply scroll behavior data attribute for CSS targeting
   if (config.scrollBehavior === 'snap') {
     component.element.dataset.snapScroll = 'true';
+  } else {
+    component.element.dataset.snapScroll = 'false';
   }
 }
 

package/src/components/carousel/constants.ts

@@ -2,94 +2,180 @@
 
 /**
  * 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 const CAROUSEL_LAYOUTS = {
-  /** Best for browsing many visual items at once (photos, event feeds) */
+  /** 
+   * 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
+   */
   MULTI_BROWSE: 'multi-browse',
   
-  /** For highly customized or text-heavy carousels (traditional behavior) */
+  /** 
+   * 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
+   */
   UNCONTAINED: 'uncontained',
   
-  /** For spotlighting very large visual items (featured content) */
+  /** 
+   * 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
+   */
   HERO: 'hero',
   
-  /** For immersive vertical-scrolling experiences */
+  /** 
+   * Full-screen layout: For immersive vertical-scrolling experiences
+   * Takes up entire viewport with snap scrolling between items
+   * Suited for immersive content or focused presentations
+   */
   FULL_SCREEN: 'full-screen'
 } as const;
 
 /**
  * Carousel scroll behaviors
+ * 
+ * Controls how scrolling behaves when moving between items.
+ * Each layout type has a recommended default behavior.
+ * 
+ * @category Components
  */
 export const CAROUSEL_SCROLL_BEHAVIORS = {
-  /** Standard scrolling without snapping */
+  /** 
+   * Default: Standard smooth scrolling without snapping
+   * Users can stop at any position between items
+   * Recommended for uncontained layouts and content browsing
+   */
   DEFAULT: 'default',
   
-  /** Items snap to carousel layout */
+  /** 
+   * Snap: Items snap to predefined positions when scrolling
+   * Ensures items are properly aligned for viewing
+   * Recommended for multi-browse, hero, and full-screen layouts
+   */
   SNAP: 'snap'
 } as const;
 
 /**
- * Carousel item sizes
+ * 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 const CAROUSEL_ITEM_SIZES = {
+  /** Large featured items (primary content) */
   LARGE: 'large',
+  /** Medium-sized items (secondary content) */
   MEDIUM: 'medium',
+  /** Small items (tertiary content or thumbnails) */
   SMALL: 'small'
 } as const;
 
 /**
  * Transition effects for carousel slides
+ * 
+ * Controls the visual transition when moving between slides.
+ * 
+ * @category Components
  */
 export const CAROUSEL_TRANSITIONS = {
+  /** Horizontal sliding animation (default) */
   SLIDE: 'slide',
+  /** Fade in/out transition between slides */
   FADE: 'fade',
+  /** No animation, immediate change */
   NONE: 'none'
 } as const;
 
 /**
  * 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 const CAROUSEL_EVENTS = {
+  /** Fired when a slide change begins */
   SLIDE_CHANGE: 'slide-change',
+  /** Fired when a slide change completes */
   SLIDE_CHANGED: 'slide-changed',
+  /** Fired when the carousel is resized */
   RESIZE: 'resize'
 } as const;
 
 /**
  * Default values for carousel configuration
+ * 
+ * These values will be used when not explicitly specified
+ * in the configuration object passed to createCarousel().
+ * 
+ * @category Components
  */
 export const CAROUSEL_DEFAULTS = {
+  /** Start displaying from the first slide (index 0) */
   INITIAL_SLIDE: 0,
+  /** Enable infinite looping by default */
   LOOP: true,
+  /** Default transition effect is sliding */
   TRANSITION: CAROUSEL_TRANSITIONS.SLIDE,
+  /** Transition duration in milliseconds */
   TRANSITION_DURATION: 300,
+  /** Border radius for slides following Material Design 3 */
   BORDER_RADIUS: 16,
+  /** Gap between slides in pixels */
   GAP: 8,
+  /** Default layout is multi-browse for browsing visual content */
   LAYOUT: CAROUSEL_LAYOUTS.MULTI_BROWSE,
+  /** Default scroll behavior is snap for controlled movement */
   SCROLL_BEHAVIOR: CAROUSEL_SCROLL_BEHAVIORS.SNAP,
-  SMALL_ITEM_WIDTH: 48, // 40-56dp range as per MD3
+  /** Small item width in pixels (40-56dp range per MD3 guidelines) */
+  SMALL_ITEM_WIDTH: 48,
   
-  // Item widths for different layouts in px
+  /**
+   * Item widths for different layouts in pixels
+   * These values are optimized for each layout type
+   * based on Material Design 3 guidelines
+   */
   ITEM_WIDTHS: {
+    // Multi-browse layout uses varying sizes
     [CAROUSEL_LAYOUTS.MULTI_BROWSE]: {
-      LARGE: 240,
-      MEDIUM: 180,
-      SMALL: 48
+      LARGE: 240,  // Large featured items
+      MEDIUM: 180, // Medium secondary items
+      SMALL: 48    // Small thumbnail/preview items
     },
+    // Uncontained layout uses consistent sizing
     [CAROUSEL_LAYOUTS.UNCONTAINED]: {
-      LARGE: 240,
-      MEDIUM: 240,
-      SMALL: 240 // All same size in uncontained
+      LARGE: 240,  // All items same size
+      MEDIUM: 240, // for consistent scrolling
+      SMALL: 240   // experience
     },
+    // Hero layout emphasizes the main item
     [CAROUSEL_LAYOUTS.HERO]: {
-      LARGE: 300,
-      MEDIUM: 240,
-      SMALL: 48
+      LARGE: 300,  // Very large for hero spotlight
+      MEDIUM: 240, // Medium for preview items
+      SMALL: 48    // Small for navigation thumbnails
     },
+    // Full-screen takes entire viewport width
     [CAROUSEL_LAYOUTS.FULL_SCREEN]: {
-      LARGE: '100%', // Full width
-      MEDIUM: '100%',
-      SMALL: '100%'
+      LARGE: '100%',  // Full width immersive
+      MEDIUM: '100%', // experience with all
+      SMALL: '100%'   // items filling viewport
     }
   }
 } as const;

package/src/components/carousel/index.ts

@@ -1,24 +1,35 @@
 // src/components/carousel/index.ts
+
 /**
- * Carousel Component - Material Design 3 compatible carousel implementation
- * 
- * This module exports a carousel component with four layout types:
- * - Multi-browse: For browsing many visual items at once (photos, event feeds)
- * - Uncontained: For highly customized or text-heavy carousels (traditional behavior)
- * - Hero: For spotlighting very large visual items (featured content)
- * - Full-screen: For immersive vertical-scrolling experiences
+ * Carousel Component Module
  * 
- * And two scroll behaviors:
- * - Default: Standard scrolling without snapping, recommended for uncontained layouts
- * - Snap: Items snap to carousel layout, recommended for multi-browse, hero, and full-screen layouts
+ * A Material Design 3 compatible carousel implementation that supports
+ * various layout types and scroll behaviors to accommodate different
+ * content presentation needs.
  * 
- * @module Carousel
+ * @module components/carousel
+ * @category Components
  */
 
 // Main factory function
 export { default } from './carousel';
 
-// Constants for use with the 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, 
@@ -28,7 +39,14 @@ export {
   CAROUSEL_ITEM_SIZES
 } from './constants';
 
-// TypeScript interfaces for proper type checking
+/**
+ * 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, 

package/src/components/checkbox/checkbox.ts

@@ -1,4 +1,15 @@
 // src/components/checkbox/checkbox.ts
+/**
+ * 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 { pipe } from '../../core/compose';
 import { createBase, withElement } from '../../core/compose/component';
 import {
@@ -20,19 +31,26 @@ import {
 } from './config';
 
 /**
- * Enhances a component with checkable features and indeterminate state
+ * Enhances a component with checkable features and indeterminate state support
+ * 
+ * The indeterminate state is a third visual state for checkboxes that represents
+ * a mixed or partial selection (neither fully checked nor unchecked).
+ * 
  * @param {BaseComponent} component - The component to enhance
  * @param {CheckboxConfig} config - Configuration options
  * @returns {BaseComponent} The enhanced component
+ * @category Components
+ * @internal
  */
 const enhanceWithCheckable = (component: BaseComponent, config: CheckboxConfig): BaseComponent => {
   const enhanced = withCheckable(config)(component);
 
-  // Add indeterminate state handling
+  // Set initial indeterminate state if specified in config
   if (config.indeterminate) {
     enhanced.input.indeterminate = true;
   }
 
+  // Add method to control indeterminate state
   enhanced.setIndeterminate = (state: boolean) => {
     enhanced.input.indeterminate = state;
     enhanced.element.classList.toggle(`${config.prefix}-checkbox--indeterminate`, state);
@@ -43,26 +61,75 @@ const enhanceWithCheckable = (component: BaseComponent, config: CheckboxConfig):
 };
 
 /**
- * Creates a new Checkbox component
- * @param {CheckboxConfig} config - Checkbox configuration
- * @returns {CheckboxComponent} Checkbox component instance
+ * 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);
+ * }
  */
 const createCheckbox = (config: CheckboxConfig = {}): CheckboxComponent => {
   const baseConfig = createBaseConfig(config);
 
   try {
+    // Create the checkbox through functional composition
+    // Each function in the pipe adds specific features to the component
     const checkbox = pipe(
-      createBase,
-      withEvents(),
-      withElement(getElementConfig(baseConfig)),
-      withInput(baseConfig),
-      withCheckIcon(baseConfig),
-      withTextLabel(baseConfig),
-      withLabelPosition(baseConfig),
-      component => enhanceWithCheckable(component, baseConfig),
-      withDisabled(baseConfig),
-      withLifecycle(),
-      comp => withAPI(getApiConfig(comp))(comp)
+      createBase,                                            // Base component
+      withEvents(),                                          // Event handling
+      withElement(getElementConfig(baseConfig)),             // DOM element
+      withInput(baseConfig),                                 // Input element
+      withCheckIcon(baseConfig),                             // Checkbox icon
+      withTextLabel(baseConfig),                             // Text label
+      withLabelPosition(baseConfig),                         // Label positioning
+      component => enhanceWithCheckable(component, baseConfig), // Checkable state
+      withDisabled(baseConfig),                              // Disabled state
+      withLifecycle(),                                       // Lifecycle management
+      comp => withAPI(getApiConfig(comp))(comp)              // Public API
     )(baseConfig);
 
     return checkbox as CheckboxComponent;

package/src/components/checkbox/index.ts

@@ -1,3 +1,45 @@
 // 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';
-export { CheckboxConfig, CheckboxComponent, CheckboxVariant, CheckboxLabelPosition } from './types';
+
+// TypeScript types and interfaces
+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';