mtrl 0.2.2 → 0.2.3

package/src/components/carousel/api.ts

@@ -0,0 +1,147 @@
+// src/components/carousel/api.ts
+import { CarouselComponent, CarouselSlide } from './types';
+
+interface ApiOptions {
+  slides: {
+    addSlide: (slide: CarouselSlide, index?: number) => any;
+    removeSlide: (index: number) => any;
+    updateSlide: (index: number, slide: CarouselSlide) => any;
+    getCount: () => number;
+    getElements: () => HTMLElement[];
+  };
+  lifecycle: {
+    destroy: () => void;
+  };
+}
+
+interface ComponentWithElements {
+  element: HTMLElement;
+  getClass: (name: string) => string;
+  getCurrentSlide: () => number;
+  goTo: (index: number) => any;
+  next: () => any;
+  prev: () => any;
+  enableLoop: () => any;
+  disableLoop: () => any;
+  setBorderRadius?: (radius: number) => any;
+  setGap?: (gap: number) => any;
+}
+
+/**
+ * Enhances a carousel 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 Carousel component
+ */
+export const withAPI = (options: ApiOptions) => 
+  (component: ComponentWithElements): CarouselComponent => {
+    // Create the API component
+    const apiComponent: CarouselComponent = {
+      element: component.element,
+      
+      slides: {
+        addSlide: options.slides.addSlide,
+        removeSlide: options.slides.removeSlide,
+        updateSlide: options.slides.updateSlide,
+        getSlide: (index: number): CarouselSlide | null => {
+          if (component['slideData'] && index >= 0 && index < component['slideData'].length) {
+            return component['slideData'][index];
+          }
+          return null;
+        },
+        getCount: options.slides.getCount,
+        getElements: options.slides.getElements
+      },
+      
+      lifecycle: {
+        destroy: options.lifecycle.destroy
+      },
+      
+      getClass: component.getClass,
+      
+      next() {
+        component.next();
+        return this;
+      },
+      
+      prev() {
+        component.prev();
+        return this;
+      },
+      
+      goTo(index: number) {
+        component.goTo(index);
+        return this;
+      },
+      
+      getCurrentSlide: component.getCurrentSlide,
+      
+      addSlide(slide: CarouselSlide, index?: number) {
+        options.slides.addSlide(slide, index);
+        return this;
+      },
+      
+      removeSlide(index: number) {
+        options.slides.removeSlide(index);
+        return this;
+      },
+      
+      enableLoop() {
+        component.enableLoop();
+        return this;
+      },
+      
+      disableLoop() {
+        component.disableLoop();
+        return this;
+      },
+      
+      setBorderRadius(radius: number) {
+        if (component.setBorderRadius) {
+          component.setBorderRadius(radius);
+        }
+        return this;
+      },
+      
+      setGap(gap: number) {
+        if (component.setGap) {
+          component.setGap(gap);
+        }
+        return this;
+      },
+      
+      destroy() {
+        options.lifecycle.destroy();
+      },
+      
+      // Add event handling and class methods from component
+      on(event: string, handler: Function) {
+        if (typeof (component as any).on === 'function') {
+          (component as any).on(event, handler);
+        } else if (component.element.addEventListener) {
+          component.element.addEventListener(event, handler as EventListener);
+        }
+        return this;
+      },
+      
+      off(event: string, handler: Function) {
+        if (typeof (component as any).off === 'function') {
+          (component as any).off(event, handler);
+        } else if (component.element.removeEventListener) {
+          component.element.removeEventListener(event, handler as EventListener);
+        }
+        return this;
+      },
+      
+      addClass(...classes: string[]) {
+        if (typeof (component as any).addClass === 'function') {
+          (component as any).addClass(...classes);
+        } else {
+          classes.forEach(cls => component.element.classList.add(cls));
+        }
+        return this;
+      }
+    };
+    
+    return apiComponent;
+  };

package/src/components/carousel/carousel.ts

@@ -0,0 +1,178 @@
+// src/components/carousel/factory.ts
+/**
+ * Carousel Factory - Creates different types of carousel 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)
+ * - Full-screen: For immersive vertical-scrolling experiences
+ * 
+ * @module CarouselFactory
+ */
+
+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 with specified layout and scroll behavior
+ * 
+ * @param {CarouselConfig} config - Carousel configuration
+ * @returns {CarouselComponent} The configured carousel component
+ * 
+ * @example
+ * ```typescript
+ * // Create a multi-browse carousel with snap scrolling
+ * const carousel = 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
+ * });
+ * 
+ * // Add the carousel to the DOM
+ * document.getElementById('container').appendChild(carousel.element);
+ * ```
+ */
+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}`);
+  }
+};
+
+/**
+ * Get default scroll behavior based on layout type
+ * 
+ * @param {CarouselLayout} layout - Carousel layout type
+ * @returns {CarouselScrollBehavior} Recommended scroll behavior
+ */
+function getDefaultScrollBehavior(layout: CarouselLayout): CarouselScrollBehavior {
+  switch (layout) {
+    case 'multi-browse':
+    case 'hero':
+    case 'full-screen':
+      return 'snap';
+    case 'uncontained':
+      return 'default';
+    default:
+      return 'default';
+  }
+}
+
+/**
+ * Apply layout-specific configurations to the component
+ * 
+ * @param {any} component - The component to configure
+ * @param {CarouselConfig} config - Carousel configuration
+ */
+function applyLayoutConfig(component: any, config: CarouselConfig): void {
+  // Add layout-specific class
+  component.element.classList.add(`${component.getClass('carousel')}-layout--${config.layout}`);
+  
+  // Apply additional layout-specific styling
+  switch (config.layout) {
+    case 'multi-browse':
+      // Configure for browsing many items with different sizes
+      component.element.dataset.enableParallax = 'true';
+      break;
+      
+    case 'uncontained':
+      // Configure for same-sized items that flow past edge
+      component.element.style.overflow = 'visible';
+      break;
+      
+    case 'hero':
+      // Configure for spotlight content with preview of next item
+      component.element.dataset.largeItemFocus = 'true';
+      
+      // Apply center alignment if specified
+      if (config.centered) {
+        component.element.dataset.centered = 'true';
+      }
+      break;
+      
+    case 'full-screen':
+      // Configure for immersive experience
+      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';
+      
+      // Force snap scrolling for full-screen layout
+      config.scrollBehavior = 'snap';
+      break;
+  }
+  
+  // Apply scroll behavior
+  if (config.scrollBehavior === 'snap') {
+    component.element.dataset.snapScroll = 'true';
+  }
+}
+
+export default createCarousel;

package/src/components/carousel/config.ts

@@ -0,0 +1,91 @@
+// 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

@@ -0,0 +1,95 @@
+// src/components/carousel/constants.ts
+
+/**
+ * Carousel layout types as defined by Material Design 3
+ */
+export const CAROUSEL_LAYOUTS = {
+  /** Best for browsing many visual items at once (photos, event feeds) */
+  MULTI_BROWSE: 'multi-browse',
+  
+  /** For highly customized or text-heavy carousels (traditional behavior) */
+  UNCONTAINED: 'uncontained',
+  
+  /** For spotlighting very large visual items (featured content) */
+  HERO: 'hero',
+  
+  /** For immersive vertical-scrolling experiences */
+  FULL_SCREEN: 'full-screen'
+} as const;
+
+/**
+ * Carousel scroll behaviors
+ */
+export const CAROUSEL_SCROLL_BEHAVIORS = {
+  /** Standard scrolling without snapping */
+  DEFAULT: 'default',
+  
+  /** Items snap to carousel layout */
+  SNAP: 'snap'
+} as const;
+
+/**
+ * Carousel item sizes
+ */
+export const CAROUSEL_ITEM_SIZES = {
+  LARGE: 'large',
+  MEDIUM: 'medium',
+  SMALL: 'small'
+} as const;
+
+/**
+ * Transition effects for carousel slides
+ */
+export const CAROUSEL_TRANSITIONS = {
+  SLIDE: 'slide',
+  FADE: 'fade',
+  NONE: 'none'
+} as const;
+
+/**
+ * Event names for the carousel component
+ */
+export const CAROUSEL_EVENTS = {
+  SLIDE_CHANGE: 'slide-change',
+  SLIDE_CHANGED: 'slide-changed',
+  RESIZE: 'resize'
+} as const;
+
+/**
+ * Default values for carousel configuration
+ */
+export const CAROUSEL_DEFAULTS = {
+  INITIAL_SLIDE: 0,
+  LOOP: true,
+  TRANSITION: CAROUSEL_TRANSITIONS.SLIDE,
+  TRANSITION_DURATION: 300,
+  BORDER_RADIUS: 16,
+  GAP: 8,
+  LAYOUT: CAROUSEL_LAYOUTS.MULTI_BROWSE,
+  SCROLL_BEHAVIOR: CAROUSEL_SCROLL_BEHAVIORS.SNAP,
+  SMALL_ITEM_WIDTH: 48, // 40-56dp range as per MD3
+  
+  // Item widths for different layouts in px
+  ITEM_WIDTHS: {
+    [CAROUSEL_LAYOUTS.MULTI_BROWSE]: {
+      LARGE: 240,
+      MEDIUM: 180,
+      SMALL: 48
+    },
+    [CAROUSEL_LAYOUTS.UNCONTAINED]: {
+      LARGE: 240,
+      MEDIUM: 240,
+      SMALL: 240 // All same size in uncontained
+    },
+    [CAROUSEL_LAYOUTS.HERO]: {
+      LARGE: 300,
+      MEDIUM: 240,
+      SMALL: 48
+    },
+    [CAROUSEL_LAYOUTS.FULL_SCREEN]: {
+      LARGE: '100%', // Full width
+      MEDIUM: '100%',
+      SMALL: '100%'
+    }
+  }
+} as const;