mtrl 0.3.8 → 0.4.0

package/src/components/carousel/carousel.ts

@@ -1,242 +0,0 @@
-// src/components/carousel/carousel.ts
-/**
- * Creates carousels with different layouts based on Material Design 3 guidelines.
- * 
- * 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
- * 
- * 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';
-import { createBase, withElement } from '../../core/compose/component';
-import { withEvents, withLifecycle } from '../../core/compose/features';
-import { withSlides, withDrag } from './features';
-import { withAPI } from './api';
-import { 
-  CarouselConfig, 
-  CarouselComponent, 
-  CarouselLayout,
-  CarouselScrollBehavior
-} from './types';
-import { createBaseConfig, getElementConfig } from './config';
-import { CAROUSEL_DEFAULTS } from './constants';
-
-/**
- * Creates a new carousel component with the specified configuration.
- * 
- * 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
- * // Create a multi-browse carousel for a photo gallery
- * const photoGallery = createCarousel({
- *   layout: 'multi-browse',
- *   scrollBehavior: 'snap',
- *   slides: [
- *     { image: 'image1.jpg', title: 'Recent highlights', accent: '#3C4043' },
- *     { image: 'image2.jpg', title: 'La Familia', accent: '#7E5260' }
- *   ],
- *   showAllLink: true
- * });
- * 
- * 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
-  config.layout = config.layout || 'multi-browse';
-  config.scrollBehavior = config.scrollBehavior || getDefaultScrollBehavior(config.layout);
-  
-  const baseConfig = createBaseConfig(config);
-
-  try {
-    // Create a safer composition order to avoid circular dependencies
-    // First build the core functionality
-    const coreComponent = pipe(
-      createBase,
-      withEvents(),
-      withElement(getElementConfig(baseConfig))
-    )(baseConfig);
-    
-    // Define the enhanced component early to avoid circular references
-    const enhancedComponent = { ...coreComponent };
-    
-    // Apply layout-specific adjustments
-    applyLayoutConfig(enhancedComponent, config);
-    
-    // Then add the features that depend on the core
-    const slidesComponent = withSlides(baseConfig)(enhancedComponent);
-    
-    // Add drag navigation
-    const withDragComponent = withDrag(baseConfig)(slidesComponent);
-    const withLifecycleComponent = withLifecycle()(withDragComponent);
-    
-    // Create a simplified API config
-    const apiConfig = {
-      slides: {
-        addSlide: withLifecycleComponent.slides.addSlide,
-        removeSlide: withLifecycleComponent.slides.removeSlide,
-        updateSlide: withLifecycleComponent.slides.updateSlide,
-        getCount: withLifecycleComponent.slides.getCount,
-        getElements: withLifecycleComponent.slides.getElements
-      },
-      lifecycle: {
-        destroy: withLifecycleComponent.lifecycle.destroy
-      }
-    };
-    
-    // Add the API
-    const carousel = withAPI(apiConfig)(withLifecycleComponent);
-
-    // Add layout data attribute for CSS targeting
-    carousel.element.dataset.layout = config.layout;
-    carousel.element.dataset.scrollBehavior = config.scrollBehavior;
-
-    return carousel;
-  } catch (error) {
-    console.error('Carousel creation error:', error);
-    throw new Error(`Failed to create carousel: ${(error as Error).message}`);
-  }
-};
-
-/**
- * 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} 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';
-  }
-}
-
-/**
- * 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 for CSS targeting
-  component.element.classList.add(`${component.getClass('carousel')}-layout--${config.layout}`);
-  
-  // Apply layout-specific configurations
-  switch (config.layout) {
-    case 'multi-browse':
-      // 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':
-      // 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':
-      // Hero layout: For spotlighting featured content
-      // Large central item with preview of adjacent items
-      component.element.dataset.largeItemFocus = 'true';
-      component.element.dataset.layout = 'hero';
-      
-      // Optionally center items for balanced presentation
-      if (config.centered) {
-        component.element.dataset.centered = 'true';
-      }
-      break;
-      
-    case 'full-screen':
-      // 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';
-      
-      // Full-screen layout always uses snap scrolling for controlled navigation
-      config.scrollBehavior = 'snap';
-      break;
-  }
-  
-  // Apply scroll behavior data attribute for CSS targeting
-  if (config.scrollBehavior === 'snap') {
-    component.element.dataset.snapScroll = 'true';
-  } else {
-    component.element.dataset.snapScroll = 'false';
-  }
-}
-
-export default createCarousel;

package/src/components/carousel/config.ts

@@ -1,91 +0,0 @@
-// src/components/carousel/config.ts
-import { 
-  createComponentConfig, 
-  createElementConfig,
-  BaseComponentConfig 
-} from '../../core/config/component-config';
-import { CarouselConfig } from './types';
-import { CAROUSEL_DEFAULTS, CAROUSEL_TRANSITIONS } from './constants';
-
-/**
- * Default configuration for the Carousel component
- */
-export const defaultConfig: CarouselConfig = {
-  initialSlide: CAROUSEL_DEFAULTS.INITIAL_SLIDE,
-  loop: CAROUSEL_DEFAULTS.LOOP,
-  transition: CAROUSEL_TRANSITIONS.SLIDE as 'slide' | 'fade' | 'none',
-  transitionDuration: CAROUSEL_DEFAULTS.TRANSITION_DURATION,
-  borderRadius: CAROUSEL_DEFAULTS.BORDER_RADIUS,
-  gap: CAROUSEL_DEFAULTS.GAP,
-  prefix: 'carousel',
-  showAllLink: true // Show "Show all" button by default
-};
-
-/**
- * Creates the base configuration for Carousel component
- * @param {CarouselConfig} config - User provided configuration
- * @returns {CarouselConfig} Complete configuration with defaults applied
- */
-export const createBaseConfig = (config: CarouselConfig = {}): CarouselConfig => 
-  createComponentConfig(defaultConfig, config, 'carousel') as CarouselConfig;
-
-/**
- * Generates element configuration for the Carousel component
- * @param {CarouselConfig} config - Carousel configuration
- * @returns {Object} Element configuration object for withElement
- */
-export const getElementConfig = (config: CarouselConfig) => {
-  // Create the attributes object
-  const attrs: Record<string, any> = {
-    role: 'region',
-    'aria-roledescription': 'carousel',
-    'aria-live': 'polite'
-  };
-  
-  // Create data attributes for configuration
-  const dataAttrs = {
-    'data-transition': config.transition,
-    'data-loop': config.loop ? 'true' : 'false'
-  };
-  
-  return createElementConfig(config, {
-    tag: 'div',
-    attrs: { ...attrs, ...dataAttrs },
-    className: config.class,
-    forwardEvents: {
-      keydown: true,
-      focus: true,
-      blur: true
-    },
-    style: {
-      position: 'relative',
-      overflow: 'hidden',
-      borderRadius: `${config.borderRadius}px`,
-      width: '100%',
-      height: 'auto',
-      display: 'flex',
-      flexDirection: 'column'
-    }
-  });
-};
-
-/**
- * Creates API configuration for the Carousel component
- * @param {Object} comp - Component with slides and lifecycle features
- * @returns {Object} API configuration object
- */
-export const getApiConfig = (comp) => ({
-  // Empty navigation API for compatibility
-  slides: {
-    addSlide: comp.slides.addSlide,
-    removeSlide: comp.slides.removeSlide,
-    updateSlide: comp.slides.updateSlide,
-    getCount: comp.slides.getCount,
-    getElements: comp.slides.getElements
-  },
-  lifecycle: {
-    destroy: comp.lifecycle.destroy
-  }
-});
-
-export default defaultConfig;

package/src/components/carousel/constants.ts

@@ -1,181 +0,0 @@
-// src/components/carousel/constants.ts
-
-/**
- * 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 = {
-  /** 
-   * 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',
-  
-  /** 
-   * 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',
-  
-  /** 
-   * 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',
-  
-  /** 
-   * 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 = {
-  /** 
-   * Default: Standard smooth scrolling without snapping
-   * Users can stop at any position between items
-   * Recommended for uncontained layouts and content browsing
-   */
-  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
-   */
-  SNAP: 'snap'
-} as const;
-
-/**
- * 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 in pixels (40-56dp range per MD3 guidelines) */
-  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
-   */
-  ITEM_WIDTHS: {
-    // Multi-browse layout uses varying sizes
-    [CAROUSEL_LAYOUTS.MULTI_BROWSE]: {
-      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,  // All items same size
-      MEDIUM: 240, // for consistent scrolling
-      SMALL: 240   // experience
-    },
-    // Hero layout emphasizes the main item
-    [CAROUSEL_LAYOUTS.HERO]: {
-      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 immersive
-      MEDIUM: '100%', // experience with all
-      SMALL: '100%'   // items filling viewport
-    }
-  }
-} as const;