mtrl 0.2.2 → 0.2.4

package/src/components/carousel/index.ts

@@ -0,0 +1,38 @@
+// 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
+ * 
+ * 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
+ * 
+ * @module Carousel
+ */
+
+// Main factory function
+export { default } from './carousel';
+
+// Constants for use with the carousel
+export { 
+  CAROUSEL_LAYOUTS, 
+  CAROUSEL_SCROLL_BEHAVIORS, 
+  CAROUSEL_TRANSITIONS, 
+  CAROUSEL_EVENTS, 
+  CAROUSEL_DEFAULTS,
+  CAROUSEL_ITEM_SIZES
+} from './constants';
+
+// TypeScript interfaces for proper type checking
+export { 
+  CarouselConfig, 
+  CarouselComponent, 
+  CarouselSlide,
+  CarouselLayout,
+  CarouselScrollBehavior
+} from './types';

package/src/components/carousel/types.ts

@@ -0,0 +1,327 @@
+// src/components/carousel/types.ts
+
+/**
+ * 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/src/components/dialog/_styles.scss

@@ -0,0 +1,213 @@
+// src/components/dialog/_styles.scss
+@use '../../styles/abstract/base' as base;
+@use '../../styles/abstract/variables' as v;
+@use '../../styles/abstract/functions' as f;
+@use '../../styles/abstract/mixins' as m;
+@use '../../styles/abstract/theme' as t;
+
+$component: '#{base.$prefix}-dialog';
+
+// Dialog overlay - covers the entire screen
+.#{$component}-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background-color: t.alpha('scrim', 0.32);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+  padding: 24px;
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 0.15s ease, visibility 0s linear 0.15s;
+  overflow-y: auto;
+  
+  &--visible {
+    opacity: 1;
+    visibility: visible;
+    transition: opacity 0.15s ease, visibility 0s linear;
+  }
+}
+
+// Dialog container
+.#{$component} {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  min-width: 280px;
+  max-width: 90vw;
+  width: fit-content;
+  max-height: calc(100vh - 48px);
+  border-radius: 28px;
+  background-color: t.color('surface-container-high');
+  color: t.color('on-surface');
+  overflow: hidden;
+  box-sizing: border-box;
+  @include m.elevation(3);
+  transform: scale(0.8);
+  opacity: 0;
+  transition: transform 0.15s ease, opacity 0.15s ease;
+  
+  &--visible {
+    transform: scale(1);
+    opacity: 1;
+  }
+  
+  // Fullscreen variant
+  &--fullscreen {
+    width: 100vw;
+    height: 100vh;
+    max-width: 100vw;
+    max-height: 100vh;
+    border-radius: 0;
+    margin: 0;
+  }
+  
+  // Fullwidth variant
+  &--fullwidth {
+    width: 100%;
+    max-width: 560px;
+  }
+  
+  // Dialog header
+  &-header {
+    display: flex;
+    align-items: flex-start;
+    padding: 24px 24px 16px;
+    
+    &-content {
+      flex: 1;
+      min-width: 0;
+    }
+    
+    &-title {
+      @include m.typography('headline-small');
+      color: t.color('on-surface');
+      margin: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    
+    &-subtitle {
+      @include m.typography('body-medium');
+      color: t.color('on-surface-variant');
+      margin: 4px 0 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    
+    &-close {
+      margin: -8px -8px -8px 8px;
+      padding: 8px;
+      border: none;
+      background: transparent;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      border-radius: 50%;
+      color: t.color('on-surface-variant');
+      
+      &:hover {
+        background-color: t.alpha('on-surface', 0.08);
+      }
+      
+      &:active {
+        background-color: t.alpha('on-surface', 0.12);
+      }
+      
+      svg {
+        width: 24px;
+        height: 24px;
+      }
+    }
+  }
+  
+  // Dialog content
+  &-content {
+    flex: 1 1 auto;
+    padding: 0 24px;
+    overflow-y: auto;
+    -webkit-overflow-scrolling: touch;
+    @include m.typography('body-medium');
+    color: t.color('on-surface-variant');
+    
+    &:first-child {
+      padding-top: 24px;
+    }
+    
+    &:last-child {
+      padding-bottom: 24px;
+    }
+  }
+  
+  // Dialog footer
+  &-footer {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: flex-end;
+    padding: 16px 24px 24px;
+    gap: 8px;
+    
+    &--left {
+      justify-content: flex-start;
+    }
+    
+    &--center {
+      justify-content: center;
+    }
+    
+    &--space-between {
+      justify-content: space-between;
+    }
+    
+    button {
+      margin: 0;
+    }
+  }
+  
+  // Size variants
+  &--small {
+    max-width: 400px;
+  }
+  
+  &--medium {
+    max-width: 560px;
+  }
+  
+  &--large {
+    max-width: 90vw;
+    width: 800px;
+  }
+  
+  // Animation variants
+  &--slide-up {
+    transform: translateY(20px) scale(1);
+    
+    &.#{$component}--visible {
+      transform: translateY(0) scale(1);
+    }
+  }
+  
+  &--slide-down {
+    transform: translateY(-20px) scale(1);
+    
+    &.#{$component}--visible {
+      transform: translateY(0) scale(1);
+    }
+  }
+  
+  &--fade {
+    transform: scale(1);
+    
+    &.#{$component}--visible {
+      transform: scale(1);
+    }
+  }
+}