mtrl 0.7.0 → 0.8.0-next.4

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

@@ -1,276 +1,70 @@
+export type CarouselVariant = "multi-browse" | "uncontained" | "hero" | "hero-center" | "full-screen";
 /**
- * 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
+ * Content of one carousel item. Either an image with optional text and a
+ * call to action, or arbitrary content.
  */
 export interface CarouselSlide {
-    /** Image URL for the slide */
-    image: string;
-    /** Optional title text for the slide */
+    image?: string;
+    /** Alternative text for the image; empty when the image is decorative */
+    alt?: string;
     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';
+    /** Custom content, replaces the image and text */
+    content?: HTMLElement | string;
 }
-/**
- * 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' }]
-     */
+    /** Layout, "multi-browse" by default */
+    variant?: CarouselVariant;
     slides?: CarouselSlide[];
     /**
-     * Border radius for slides in pixels
-     * @default 16
-     */
-    borderRadius?: number;
-    /**
-     * Gap between slides in pixels
-     * @default 8
+     * Width of a large item in px. Multi-browse and uncontained layouts
+     * treat it as the preferred width, hero layouts as a maximum (the
+     * container width by default).
      */
+    itemWidth?: number;
+    /** Space between items, 8 by default (16 for full-screen) */
     gap?: number;
-    /**
-     * Additional CSS classes to add to the carousel
-     * @example 'hero-carousel featured-carousel'
-     */
-    class?: string;
-    /**
-     * Component prefix for class names
-     * @default 'carousel'
-     */
+    /** Space between the container edges and the items, 16 by default (0 for full-screen) */
+    padding?: number;
+    /** Corner radius of the items, 28 by default */
+    cornerRadius?: number;
+    /** Snap to items after scrolling; on by default except for uncontained layouts */
+    snap?: boolean;
+    initialSlide?: number;
+    minSmallItemWidth?: number;
+    maxSmallItemWidth?: number;
+    /** Accessible name of the carousel */
+    ariaLabel?: string;
     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[];
+    class?: string;
 }
-/**
- * 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
-     */
+    getVariant: () => CarouselVariant;
     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;
 }
+export interface SlidesAPI {
+    addSlide: (slide: CarouselSlide, index?: number) => SlidesAPI;
+    removeSlide: (index: number) => SlidesAPI;
+    updateSlide: (index: number, slide: CarouselSlide) => SlidesAPI;
+    getSlide: (index: number) => CarouselSlide | null;
+    getCount: () => number;
+    getElements: () => HTMLElement[];
+}

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

@@ -1,4 +1,4 @@
-import { DialogComponent, DialogButton, DialogConfirmOptions, DialogFooterAlignment, DialogSize } from './types';
+import { DialogComponent, DialogButton, DialogConfirmOptions, DialogFooterAlignment, DialogSize } from "./types";
 interface ApiOptions {
     visibility: {
         open: () => void;

package/dist/components/index.d.ts

@@ -24,6 +24,8 @@ export { default as createExtendedFab } from "./extended-fab";
 export { default as createIconButton } from "./icon-button";
 export { default as createList } from "./list";
 export { default as createMenu } from "./menu";
+export { default as createNavigation } from "./navigation";
+export { default as createNavigationSystem } from "./navigation/system";
 export { default as createProgress } from "./progress";
 export { default as createRadios } from "./radios";
 export { default as createSearch } from "./search";

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

@@ -26,7 +26,7 @@ export declare const SLIDER_SIZES: {
     /** Large size - 56px track height */
     readonly L: 56;
     /** Extra large size - 96px track height */
-    readonly XL: 80;
+    readonly XL: 96;
 };
 /**
  * Slider component size type
@@ -40,12 +40,12 @@ export type SliderSize = keyof typeof SLIDER_SIZES | number;
 export declare const SLIDER_MEASUREMENTS: {
     /** Handle size in pixels */
     readonly HANDLE_SIZE: 16;
-    /** Handle height for XS and S sizes in pixels */
-    readonly SMALL_HANDLE_HEIGHT: 48;
-    /** Handle height offset for M, L, XL sizes (added to track height) */
-    readonly HANDLE_HEIGHT_OFFSET: 16;
-    /** Minimum container height in pixels */
-    readonly MIN_HEIGHT: 40;
+    /** Handle height for XS and S sizes in pixels (M3: 44dp) */
+    readonly SMALL_HANDLE_HEIGHT: 44;
+    /** Handle height offset for M, L, XL sizes (added to track height: 52, 68, 108dp) */
+    readonly HANDLE_HEIGHT_OFFSET: 12;
+    /** Minimum container height in pixels (M3 minimum touch target) */
+    readonly MIN_HEIGHT: 48;
     /** Track border radius in pixels */
     readonly TRACK_RADIUS: 3;
     /** External track radius for XS and S sizes in pixels */
@@ -57,7 +57,7 @@ export declare const SLIDER_MEASUREMENTS: {
     /** Dot size in pixels */
     readonly DOT_SIZE: 4;
     /** Handle gap pixels */
-    readonly HANDLE_GAP: 8;
+    readonly HANDLE_GAP: 6;
     /** Handle gap reduction when pressed in pixels */
     readonly HANDLE_GAP_PRESSED_REDUCTION: 2;
     /** Center gap pixels for centered sliders */

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

@@ -26,7 +26,10 @@ export interface SliderConfig extends BaseComponentConfig {
     step?: number;
     /** Whether the slider is disabled */
     disabled?: boolean;
-    /** Color variant of the slider */
+    /** Color variant of the slider *
+     * A stylesheet can override the drawn colours per slider with the custom
+     * properties --mtrl-slider-color and --mtrl-slider-on-color.
+     */
     color?: SliderColor;
     /** Size variant of the slider */
     size?: SliderSize;

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

@@ -4,4 +4,4 @@ import { BaseComponent, SnackbarComponent, ApiOptions } from "./types";
  * @param {ApiOptions} options - API configuration
  * @returns {Function} Higher-order function that adds API methods to component
  */
-export declare const withAPI: ({ lifecycle, queue }: ApiOptions) => (component: BaseComponent) => SnackbarComponent;
+export declare const withAPI: ({ lifecycle, queue, queueBehavior }: ApiOptions) => (component: BaseComponent) => SnackbarComponent;

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

@@ -48,6 +48,7 @@ export declare const getTextConfig: (config: SnackbarConfig) => {
     message: string;
     action?: string;
     duration?: number;
+    queueBehavior?: import("./types").SnackbarQueueBehavior;
     onAction?: (event: import("./types").SnackbarEvent) => void;
     onOpen?: (event: import("./types").SnackbarEvent) => void;
     onClose?: (event: import("./types").SnackbarEvent) => void;
@@ -62,5 +63,5 @@ export declare const getTextConfig: (config: SnackbarConfig) => {
  * @param {SnackbarQueue} queue - Snackbar queue manager
  * @returns {ApiOptions} API configuration object
  */
-export declare const getApiConfig: (comp: BaseComponent, queue: any) => ApiOptions;
+export declare const getApiConfig: (comp: BaseComponent, queue: any, config?: SnackbarConfig) => ApiOptions;
 export default defaultConfig;

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

@@ -30,6 +30,20 @@ export declare const SNACKBAR_STATES: {
     /** Snackbar is hidden */
     readonly HIDDEN: "hidden";
 };
+/**
+ * Snackbar queue behaviors
+ *
+ * Controls how a newly shown snackbar interacts with the one currently on
+ * screen and any still waiting in the queue.
+ * @category Components
+ */
+export declare const SNACKBAR_QUEUE_BEHAVIORS: {
+    /** Wait in line — shown one at a time, in order (default) */
+    readonly QUEUE: "queue";
+    /** Replace — immediately dismiss the current snackbar, drop any pending
+     *  ones, and show this snackbar right away (last-wins) */
+    readonly REPLACE: "replace";
+};
 /**
  * Snackbar event types
  * @category Components
@@ -55,6 +69,10 @@ export declare const SNACKBAR_DEFAULTS: {
     readonly POSITION: "center";
     /** Default display duration in milliseconds (4 seconds) */
     readonly DURATION: 4000;
+    /** Default queue behavior */
+    readonly QUEUE_BEHAVIOR: "queue";
+    /** Delay in milliseconds between a dismissed snackbar and the next one */
+    readonly QUEUE_GAP: 200;
     /** Default z-index for snackbars */
     readonly Z_INDEX: 1000;
     /** Default animation duration in milliseconds */

package/dist/components/snackbar/index.d.ts

@@ -1,2 +1,3 @@
 export { default } from "./snackbar";
-export { SnackbarConfig, SnackbarComponent } from "./types";
+export { SnackbarConfig, SnackbarComponent, SnackbarQueueBehavior, } from "./types";
+export { SNACKBAR_QUEUE_BEHAVIORS } from "./constants";

package/dist/components/snackbar/queue.d.ts

@@ -1,7 +1,15 @@
 import { SnackbarQueue } from './types';
 /**
  * Creates a queue manager for snackbars
- * Ensures only one snackbar is visible at a time
+ *
+ * Ensures only one snackbar is visible at a time. Supports two behaviors when
+ * a new snackbar is added (see {@link SnackbarQueueAddOptions}):
+ * - `'queue'` (default): the snackbar waits its turn and is shown in order.
+ * - `'replace'`: the snackbar evicts whatever is currently on screen, drops any
+ *   still-pending snackbars, and shows immediately. This keeps rapid, repeated
+ *   actions snappy instead of serializing a long backlog.
+ *
+ * @param {number} gap - Delay in ms between a dismissed snackbar and the next
  * @returns {SnackbarQueue} Queue manager with add/clear methods
  */
-export declare const createSnackbarQueue: () => SnackbarQueue;
+export declare const createSnackbarQueue: (gap?: number) => SnackbarQueue;

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

@@ -21,6 +21,19 @@ export declare const SNACKBAR_POSITIONS: {
     readonly START: "start";
     readonly END: "end";
 };
+/**
+ * Available snackbar queue behaviors
+ */
+export type SnackbarQueueBehavior = 'queue' | 'replace';
+/**
+ * Snackbar queue behaviors
+ */
+export declare const SNACKBAR_QUEUE_BEHAVIORS: {
+    /** Shown one at a time, in order (default) */
+    readonly QUEUE: "queue";
+    /** Replace the current snackbar and drop pending ones (last-wins) */
+    readonly REPLACE: "replace";
+};
 /**
  * Snackbar visibility states
  */
@@ -65,6 +78,14 @@ export interface SnackbarConfig {
     action?: string;
     /** Duration in milliseconds to show the snackbar (0 for indefinite) */
     duration?: number;
+    /**
+     * How this snackbar interacts with the queue when shown.
+     * - `'queue'` (default): wait in line and show one at a time, in order.
+     * - `'replace'`: immediately dismiss the current snackbar, drop any pending
+     *   ones, and show this snackbar right away. Useful for rapid, repeated
+     *   actions where only the latest message matters.
+     */
+    queueBehavior?: SnackbarQueueBehavior;
     /** Action button callback function */
     onAction?: (event: SnackbarEvent) => void;
     /** Callback function when the snackbar opens */
@@ -144,20 +165,33 @@ export interface BaseComponent {
 export interface SnackbarTimer {
     start: () => void;
     stop: () => void;
+    /** Sets the auto-dismiss duration in milliseconds */
+    setDuration: (duration: number) => void;
+    /** Gets the current auto-dismiss duration in milliseconds */
+    getDuration: () => number;
 }
 /**
  * Interface for snackbars managed by the queue
  */
 export interface QueuedSnackbar {
     _show: () => void;
+    /** Visually dismisses the snackbar without advancing the queue */
+    _hide?: () => void;
     on: (event: string, handler: () => void) => void;
     off: (event: string, handler: () => void) => void;
 }
+/**
+ * Options controlling how a snackbar is added to the queue
+ */
+export interface SnackbarQueueAddOptions {
+    /** Behavior to apply when adding this snackbar (defaults to `'queue'`) */
+    behavior?: SnackbarQueueBehavior;
+}
 /**
  * Interface for the snackbar queue manager
  */
 export interface SnackbarQueue {
-    add: (snackbar: QueuedSnackbar) => void;
+    add: (snackbar: QueuedSnackbar, options?: SnackbarQueueAddOptions) => void;
     clear: () => void;
     getLength: () => number;
 }
@@ -169,4 +203,6 @@ export interface ApiOptions {
         destroy: () => void;
     };
     queue: SnackbarQueue;
+    /** Queue behavior applied when the snackbar is shown */
+    queueBehavior?: SnackbarQueueBehavior;
 }