mtrl 0.7.0 → 0.8.0-next.4

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

@@ -1,165 +1,39 @@
 /**
- * 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
+ * Material 3 carousel layouts (m3.material.io carousel specs)
  */
-export declare 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
-     */
+export declare const CAROUSEL_VARIANTS: {
+    /** At least one large, one medium and one small item; the default */
     readonly 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
-     */
+    /** Items keep one size and run off the trailing edge */
     readonly 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
-     */
+    /** One large item and a small preview of the next */
     readonly 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
-     */
+    /** One large item centred between two small ones */
+    readonly HERO_CENTER: "hero-center";
+    /** One edge-to-edge item at a time, scrolling vertically */
     readonly FULL_SCREEN: "full-screen";
 };
-/**
- * Carousel scroll behaviors
- *
- * Controls how scrolling behaves when moving between items.
- * Each layout type has a recommended default behavior.
- *
- * @category Components
- */
-export declare 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
-     */
-    readonly 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
-     */
-    readonly SNAP: "snap";
-};
-/**
- * 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 declare const CAROUSEL_ITEM_SIZES: {
-    /** Large featured items (primary content) */
-    readonly LARGE: "large";
-    /** Medium-sized items (secondary content) */
-    readonly MEDIUM: "medium";
-    /** Small items (tertiary content or thumbnails) */
-    readonly SMALL: "small";
-};
-/**
- * Transition effects for carousel slides
- *
- * Controls the visual transition when moving between slides.
- *
- * @category Components
- */
-export declare const CAROUSEL_TRANSITIONS: {
-    /** Horizontal sliding animation (default) */
-    readonly SLIDE: "slide";
-    /** Fade in/out transition between slides */
-    readonly FADE: "fade";
-    /** No animation, immediate change */
-    readonly NONE: "none";
-};
-/**
- * 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 declare const CAROUSEL_EVENTS: {
-    /** Fired when a slide change begins */
-    readonly SLIDE_CHANGE: "slide-change";
-    /** Fired when a slide change completes */
-    readonly SLIDE_CHANGED: "slide-changed";
-    /** Fired when the carousel is resized */
-    readonly RESIZE: "resize";
+    /** The snapped item changed; detail carries the index */
+    readonly CHANGE: "change";
 };
 /**
- * Default values for carousel configuration
- *
- * These values will be used when not explicitly specified
- * in the configuration object passed to createCarousel().
- *
- * @category Components
+ * Defaults from the Compose Material 3 carousel (CarouselDefaults) and the
+ * carousel specs: 8dp between items, 16dp container padding, 28dp corners,
+ * small items between 40 and 56dp, 10dp anchors just outside the container.
  */
 export declare const CAROUSEL_DEFAULTS: {
-    /** Start displaying from the first slide (index 0) */
-    readonly INITIAL_SLIDE: 0;
-    /** Enable infinite looping by default */
-    readonly LOOP: true;
-    /** Default transition effect is sliding */
-    readonly TRANSITION: "slide";
-    /** Transition duration in milliseconds */
-    readonly TRANSITION_DURATION: 300;
-    /** Border radius for slides following Material Design 3 */
-    readonly BORDER_RADIUS: 16;
-    /** Gap between slides in pixels */
+    readonly VARIANT: "multi-browse";
+    /** Preferred width of a large item; hero layouts use it as a maximum */
+    readonly ITEM_WIDTH: 280;
     readonly GAP: 8;
-    /** Default layout is multi-browse for browsing visual content */
-    readonly LAYOUT: "multi-browse";
-    /** Default scroll behavior is snap for controlled movement */
-    readonly SCROLL_BEHAVIOR: "snap";
-    /** Small item width in pixels (40-56dp range per MD3 guidelines) */
-    readonly 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
-     */
-    readonly ITEM_WIDTHS: {
-        readonly "multi-browse": {
-            readonly LARGE: 240;
-            readonly MEDIUM: 180;
-            readonly SMALL: 48;
-        };
-        readonly uncontained: {
-            readonly LARGE: 240;
-            readonly MEDIUM: 240;
-            readonly SMALL: 240;
-        };
-        readonly hero: {
-            readonly LARGE: 300;
-            readonly MEDIUM: 240;
-            readonly SMALL: 48;
-        };
-        readonly "full-screen": {
-            readonly LARGE: "100%";
-            readonly MEDIUM: "100%";
-            readonly SMALL: "100%";
-        };
-    };
+    /** Full-screen layouts space items 16dp apart */
+    readonly GAP_FULL_SCREEN: 16;
+    readonly PADDING: 16;
+    readonly CORNER_RADIUS: 28;
+    readonly MIN_SMALL_ITEM_WIDTH: 40;
+    readonly MAX_SMALL_ITEM_WIDTH: 56;
+    readonly ANCHOR_SIZE: 10;
+    readonly MEDIUM_LARGE_THRESHOLD: 0.85;
+    readonly INITIAL_SLIDE: 0;
 };

package/dist/components/carousel/features/index.d.ts

@@ -1,5 +1,2 @@
-/**
- * Entry point for Carousel component features
- */
-export { withSlides } from './slides';
-export { withDrag } from './drag';
+export { withSlides } from "./slides";
+export { withScroll } from "./scroll";

package/dist/components/carousel/features/scroll.d.ts

@@ -0,0 +1,19 @@
+import { CarouselConfig, CarouselVariant } from "../types";
+import type { SlidesComponent } from "./slides";
+interface ScrollComponent {
+    getCurrentSlide: () => number;
+    getVariant: () => CarouselVariant;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    lifecycle: {
+        destroy: () => void;
+    };
+}
+export declare const withScroll: (config: CarouselConfig) => <C extends SlidesComponent & {
+    emit?: (event: string, data?: unknown) => unknown;
+    lifecycle?: {
+        destroy: () => void;
+    };
+}>(component: C) => C & ScrollComponent;
+export {};

package/dist/components/carousel/features/slides.d.ts

@@ -1,8 +1,18 @@
-import { CarouselConfig } from "../types";
-/**
- * Adds slide functionality to the carousel component with Material Design 3 layout types support
- *
- * @param {CarouselConfig} config - Carousel configuration
- * @returns {Function} Higher-order function that adds slides feature
- */
-export declare const withSlides: (config: CarouselConfig) => (component: any) => any;
+import { CarouselConfig, SlidesAPI } from "../types";
+export interface SlidesComponent {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+    /** Scroll container holding the track */
+    scroller: HTMLElement;
+    /** Positioned parent of the items */
+    track: HTMLElement;
+    slides: SlidesAPI;
+    slideElements: HTMLElement[];
+    /** Registers the callback run when items are added or removed (the scroll feature rebuilds) */
+    onSlidesChanged: (handler: () => void) => void;
+    [key: string]: unknown;
+}
+export declare const withSlides: (config: CarouselConfig) => <C extends {
+    element: HTMLElement;
+    getClass: (name: string) => string;
+}>(component: C) => C & SlidesComponent;

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

@@ -1,37 +1,3 @@
-/**
- * Carousel Component Module
- *
- * A Material Design 3 compatible carousel implementation that supports
- * various layout types and scroll behaviors to accommodate different
- * content presentation needs.
- *
- * @module components/carousel
- * @category Components
- */
-export { default } from './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, CAROUSEL_TRANSITIONS, CAROUSEL_EVENTS, CAROUSEL_DEFAULTS, CAROUSEL_ITEM_SIZES } from './constants';
-/**
- * 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, CarouselSlide, CarouselLayout, CarouselScrollBehavior } from './types';
+export { default, createCarousel } from "./carousel";
+export { CAROUSEL_VARIANTS, CAROUSEL_EVENTS, CAROUSEL_DEFAULTS, } from "./constants";
+export type { CarouselConfig, CarouselComponent, CarouselSlide, CarouselVariant, SlidesAPI, } from "./types";

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

@@ -0,0 +1,65 @@
+export interface Keyline {
+    size: number;
+    /** Centre of the item along the axis, in container coordinates */
+    offset: number;
+    /** Centre the item would have if every item were large */
+    unadjustedOffset: number;
+    isFocal: boolean;
+    isAnchor: boolean;
+    isPivot: boolean;
+    /** How much of the item hangs outside the container */
+    cutoff: number;
+}
+export type KeylineList = Keyline[];
+interface TmpKeyline {
+    size: number;
+    isAnchor: boolean;
+}
+export interface KeylineRules {
+    minSmallSize: number;
+    maxSmallSize: number;
+    anchorSize: number;
+    /** A medium item wider than this share of a large one is cut differently in uncontained layouts */
+    mediumLargeThreshold: number;
+}
+export declare const firstFocalIndex: (list: KeylineList) => number;
+export declare const lastFocalIndex: (list: KeylineList) => number;
+export declare const firstNonAnchorIndex: (list: KeylineList) => number;
+export declare const lastNonAnchorIndex: (list: KeylineList) => number;
+export declare const pivotIndex: (list: KeylineList) => number;
+export declare const focalCount: (list: KeylineList) => number;
+export declare const minSize: (list: KeylineList) => number;
+export declare const maxSize: (list: KeylineList) => number;
+export declare const isFirstFocalItemAtStartOfContainer: (list: KeylineList) => boolean;
+export declare const isLastFocalItemAtEndOfContainer: (list: KeylineList, containerSize: number) => boolean;
+export declare const firstIndexAfterFocalRangeWithSize: (list: KeylineList, size: number) => number;
+export declare const lastIndexBeforeFocalRangeWithSize: (list: KeylineList, size: number) => number;
+export declare const keylineBefore: (list: KeylineList, unadjustedOffset: number) => Keyline;
+export declare const keylineAfter: (list: KeylineList, unadjustedOffset: number) => Keyline;
+export declare const lerpKeyline: (a: Keyline, b: Keyline, t: number) => Keyline;
+export declare const lerpKeylineList: (from: KeylineList, to: KeylineList, t: number) => KeylineList;
+/** Builds a keyline list with an explicit pivot (used for the shifted start and end steps) */
+export declare const keylineListWithPivot: (containerSize: number, gap: number, pivotIdx: number, pivotOffset: number, tmp: TmpKeyline[]) => KeylineList;
+/** Builds a keyline list aligned to the start or centre of the container */
+export declare const keylineListAligned: (containerSize: number, gap: number, alignment: "start" | "center", tmp: TmpKeyline[]) => KeylineList;
+/**
+ * Multi-browse: at least one large, one medium and one small item; a small
+ * item aims for a third of a large one within the 40–56dp range and the
+ * medium item sits halfway. More large items appear as the container grows.
+ */
+export declare const multiBrowseKeylines: (containerSize: number, preferredItemSize: number, gap: number, count: number, rules: KeylineRules) => KeylineList;
+/**
+ * Hero: one large item (or more on wide containers) and one small item; the
+ * centred variant places the large item between two small ones.
+ */
+export declare const heroKeylines: (containerSize: number, maxItemSize: number | null, gap: number, count: number, centered: boolean, rules: KeylineRules) => KeylineList;
+/**
+ * Uncontained: every item keeps its width and the last visible one is cut
+ * off at the trailing edge, about a third of it hidden. Compose folds the
+ * spacing into the item size; here the gaps stay between the items so the
+ * spec's 8dp holds and the cut-off item keeps two thirds visible.
+ */
+export declare const uncontainedKeylines: (containerSize: number, itemSize: number, gap: number, rules: KeylineRules) => KeylineList;
+/** Full-screen: one item fills the container edge to edge */
+export declare const fullScreenKeylines: (containerSize: number, gap: number, rules: KeylineRules) => KeylineList;
+export {};

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

@@ -0,0 +1,36 @@
+import { Keyline, KeylineList } from './keylines';
+export interface Strategy {
+    defaultKeylines: KeylineList;
+    startSteps: KeylineList[];
+    endSteps: KeylineList[];
+    availableSpace: number;
+    gap: number;
+    beforePadding: number;
+    afterPadding: number;
+    /** Size of a large item: the unit every item is measured in before adjustment */
+    itemSize: number;
+    minItemSize: number;
+    maxItemSize: number;
+    valid: boolean;
+    startShiftDistance: number;
+    endShiftDistance: number;
+    startShiftPoints: number[];
+    endShiftPoints: number[];
+}
+export interface ItemPlacement {
+    /** Visible size of the item along the axis */
+    size: number;
+    /** Centre of the visible part, in container coordinates */
+    center: number;
+    /** Interpolated keyline the item sits on */
+    keyline: Keyline;
+}
+export declare const createStrategy: (defaultKeylines: KeylineList, availableSpace: number, gap: number, beforePadding: number, afterPadding: number) => Strategy;
+/** Keylines in effect for a scroll offset: default, or interpolated within the start or end shift range */
+export declare const keylinesForScrollOffset: (s: Strategy, scrollOffset: number, maxScrollOffset: number, roundToNearestStep?: boolean) => KeylineList;
+/** Distance from the container start to an item's start when that item is snapped */
+export declare const snapPositionOffset: (s: Strategy, index: number, count: number) => number;
+/** Largest scroll offset: the content laid out at large size minus the container */
+export declare const maxScrollOffset: (s: Strategy, count: number) => number;
+/** Where an item sits and how much of it shows for the keylines in effect */
+export declare const placeItem: (s: Strategy, keylines: KeylineList, index: number, scrollOffset: number) => ItemPlacement;