@noxlovette/material 0.4.8 → 0.5.1

package/dist/animation/enterExit.d.ts

@@ -1,3 +1,30 @@
-import type { TransitionConfig } from 'svelte/transition';
-import type { TransitionOptions } from './transitionTypes.js';
-export declare const enterExit: (node: Element, options?: TransitionOptions) => TransitionConfig;
+import type { AnimationOptions, DOMKeyframesDefinition } from 'motion';
+/**
+ * An M3 enter/exit transition for {@link presence} / `Presence`. Keep keyframes to `transform`
+ * and `opacity` so Motion runs them on WAAPI (compositor), which is also what bits-ui's presence
+ * layer detects to delay unmounting.
+ *
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#enter-and-exit
+ *
+ * Introduces a component in the context of the current screen, modal or not
+ * (https://m3.material.io/styles/motion/transitions/applying-transitions). Never use it to navigate between hierarchical screens.
+ * Clean fades: opacity always runs on `fastEffects` so it never lingers over the content behind.
+ * Edge-anchored sheets slide without fading, as M3 asks.
+ *
+ * Required for every component that mounts a surface within the current screen: dialogs, sheets,
+ * menus, popovers, tooltips, pickers, snackbars, the FAB menu. See the ownership table in
+ * `.claude/skills/material-design/references/motion-guide.md`.
+ */
+export interface PresenceTransition {
+    /** Where the enter animation starts. */
+    hidden: DOMKeyframesDefinition;
+    shown: DOMKeyframesDefinition;
+    /** Where the exit animation ends. Defaults to `hidden`. */
+    exited?: DOMKeyframesDefinition;
+    /** `transform-origin` applied while mounted. */
+    origin?: string;
+    enter: AnimationOptions;
+    exit: AnimationOptions;
+}
+export type EnterExitPreset = 'fade' | 'scale' | 'slideUp' | 'dialog' | 'sideSheet' | 'bottomSheet';
+export declare const enterExit: Record<EnterExitPreset, PresenceTransition>;

package/dist/animation/enterExit.js

@@ -1,23 +1,70 @@
-import { easeEmphasized } from './easing.js';
-export const enterExit = (node, options = {}) => {
-    const mode = options.mode ?? 'fade';
-    return {
-        delay: options.delay ?? 0,
-        duration: options.duration ?? 300,
-        easing: options.easing ?? easeEmphasized,
-        css: (t) => {
-            switch (mode) {
-                case 'scale':
-                    return `opacity: ${t}; transform: scale(${0.85 + t * 0.15});`;
-                case 'slide-up':
-                    return `opacity: ${t}; transform: translateY(${(1 - t) * 12}px);`;
-                case 'dialog':
-                    return `opacity: ${t}; transform: translateY(${(1 - t) * -24}px) scale(${0.9 + t * 0.1});`;
-                case 'dialog-m3':
-                    return `opacity: ${t}; transform: scale(${0.9 + t * 0.1});`;
-                default:
-                    return `opacity: ${t};`;
-            }
-        }
-    };
+import { springTokens, springTransition } from './spring.js';
+/*
+  Scale and offset values come from Material Components Android, the reference implementation of
+  the M3 transition patterns (github.com/material-components/material-components-android,
+  lib/java/com/google/android/material/transition):
+  - MaterialFade: enters from 0.8 scale, opacity done in the first 30%; exits by fading only.
+  - BaseTransientBottomBar (snackbar), slide mode: translates by its own full height.
+  Spring timings replace MDC's duration/easing pairs.
+*/
+const MATERIAL_FADE_START_SCALE = 0.8;
+/* Spatial spring for the movement; the fade uses the fast effects spring so opacity lands early
+   (MDC fades in over the first 30% of the enter) and never overshoots. */
+const enterWith = (spatial) => ({
+    ...springTransition(spatial),
+    opacity: springTransition(springTokens.fastEffects)
+});
+/* Exits leave quickly and don't bounce on the way out: critically damped throughout. */
+const exit = {
+    ...springTransition(springTokens.effects),
+    opacity: springTransition(springTokens.fastEffects)
+};
+/* bits-ui sets this on every floating wrapper: the side of the content facing its anchor. */
+const ANCHOR_ORIGIN = 'var(--bits-floating-transform-origin, center)';
+export const enterExit = {
+    /** Opacity only — scrims, overlays, content swapped in place. */
+    fade: {
+        hidden: { opacity: 0 },
+        shown: { opacity: 1 },
+        enter: springTransition(springTokens.effects),
+        exit: springTransition(springTokens.fastEffects)
+    },
+    /** Anchored surfaces — menus, popovers, tooltips, pickers. Grows out of its anchor (MaterialFade). */
+    scale: {
+        hidden: { opacity: 0, transform: `scale(${MATERIAL_FADE_START_SCALE})` },
+        shown: { opacity: 1, transform: 'scale(1)' },
+        exited: { opacity: 0 },
+        origin: ANCHOR_ORIGIN,
+        enter: enterWith(springTokens.fastSpatial),
+        exit
+    },
+    /** Snackbars — slide in from below by their own height (MDC slide mode). */
+    slideUp: {
+        hidden: { opacity: 0, transform: 'translateY(100%)' },
+        shown: { opacity: 1, transform: 'translateY(0%)' },
+        enter: enterWith(springTokens.fastSpatial),
+        exit
+    },
+    /** Modal dialogs — MaterialFade from the center. */
+    dialog: {
+        hidden: { opacity: 0, transform: `scale(${MATERIAL_FADE_START_SCALE})` },
+        shown: { opacity: 1, transform: 'scale(1)' },
+        exited: { opacity: 0 },
+        enter: enterWith(springTokens.spatial),
+        exit
+    },
+    /** Side sheet anchored to the inline-end edge. Slides only: no opacity (M3: don't fade sheets). */
+    sideSheet: {
+        hidden: { transform: 'translateX(100%)' },
+        shown: { transform: 'translateX(0%)' },
+        enter: springTransition(springTokens.spatial),
+        exit: springTransition(springTokens.effects)
+    },
+    /** Bottom sheet anchored to the bottom edge. Slides only: no opacity (M3: don't fade sheets). */
+    bottomSheet: {
+        hidden: { transform: 'translateY(100%)' },
+        shown: { transform: 'translateY(0%)' },
+        enter: springTransition(springTokens.spatial),
+        exit: springTransition(springTokens.effects)
+    }
 };

package/dist/animation/index.d.ts

@@ -1,5 +1,6 @@
-export * from './easing.js';
+export * from './shapeMorph.svelte.js';
 export * from './shapes.js';
 export * from './shapesAnimatable.js';
 export * from './shapesAnimatableSmall.js';
+export * from './spring.js';
 export * from './transition.js';

package/dist/animation/index.js

@@ -1,5 +1,6 @@
-export * from './easing.js';
+export * from './shapeMorph.svelte.js';
 export * from './shapes.js';
 export * from './shapesAnimatable.js';
 export * from './shapesAnimatableSmall.js';
+export * from './spring.js';
 export * from './transition.js';

package/dist/animation/presence.svelte.d.ts

@@ -0,0 +1,47 @@
+import type { Attachment } from 'svelte/attachments';
+import type { PresenceTransition } from './enterExit.js';
+/**
+ * Enter/exit attachment driven by Motion's `animate()`. Plays `transition.enter` from `hidden` to
+ * `shown` when the element mounts open, and `transition.exit` to `exited` (default `hidden`) when
+ * `isOpen()` turns false. Applies `transition.origin` as the element's `transform-origin`. Reopening mid-exit (or closing mid-enter) retargets from the current value — the
+ * spring keeps its velocity instead of restarting.
+ *
+ * Inside bits-ui content (`Popover.Content`, `DropdownMenu.Content`, `Dialog.Content`, …) drop
+ * `forceMount` and attach this to the element receiving `props`: bits-ui's presence layer waits
+ * for that element's `getAnimations()` before unmounting, and Motion runs transform/opacity
+ * through WAAPI, so the exit plays out in full.
+ *
+ * ```svelte
+ * <Popover.Content>
+ *   {#snippet child({ wrapperProps, props, open })}
+ *     <div {...wrapperProps}>
+ *       <div {...props} {@attach presence(() => open, enterExit.scale)}>…</div>
+ *     </div>
+ *   {/snippet}
+ * </Popover.Content>
+ * ```
+ *
+ * Outside bits-ui, use {@link Presence} so the element stays mounted until the exit finishes.
+ */
+export declare const presence: (isOpen: () => boolean, transition: PresenceTransition, onExitComplete?: () => void) => Attachment<HTMLElement>;
+/**
+ * Keeps an element mounted until its exit animation finishes — the Motion replacement for a
+ * Svelte `out:` transition. Construct during component init.
+ *
+ * ```svelte
+ * <script>
+ *   const sheet = new Presence(() => open);
+ * </script>
+ *
+ * {#if sheet.mounted}
+ *   <div {@attach sheet.attach(enterExit.sideSheet)}>…</div>
+ * {/if}
+ * ```
+ */
+export declare class Presence {
+    #private;
+    constructor(isOpen: () => boolean);
+    /** True while open, and while the exit animation is still playing. */
+    mounted: boolean;
+    attach: (transition: PresenceTransition) => Attachment<HTMLElement>;
+}

package/dist/animation/presence.svelte.js

@@ -0,0 +1,84 @@
+import { animate } from 'motion';
+import { untrack } from 'svelte';
+const fromTo = (from, to) => Object.fromEntries(Object.entries(to).map(([key, value]) => [key, [from[key], value]]));
+/**
+ * Enter/exit attachment driven by Motion's `animate()`. Plays `transition.enter` from `hidden` to
+ * `shown` when the element mounts open, and `transition.exit` to `exited` (default `hidden`) when
+ * `isOpen()` turns false. Applies `transition.origin` as the element's `transform-origin`. Reopening mid-exit (or closing mid-enter) retargets from the current value — the
+ * spring keeps its velocity instead of restarting.
+ *
+ * Inside bits-ui content (`Popover.Content`, `DropdownMenu.Content`, `Dialog.Content`, …) drop
+ * `forceMount` and attach this to the element receiving `props`: bits-ui's presence layer waits
+ * for that element's `getAnimations()` before unmounting, and Motion runs transform/opacity
+ * through WAAPI, so the exit plays out in full.
+ *
+ * ```svelte
+ * <Popover.Content>
+ *   {#snippet child({ wrapperProps, props, open })}
+ *     <div {...wrapperProps}>
+ *       <div {...props} {@attach presence(() => open, enterExit.scale)}>…</div>
+ *     </div>
+ *   {/snippet}
+ * </Popover.Content>
+ * ```
+ *
+ * Outside bits-ui, use {@link Presence} so the element stays mounted until the exit finishes.
+ */
+export const presence = (isOpen, transition, onExitComplete) => (node) => {
+    let controls;
+    let started = false;
+    if (transition.origin)
+        node.style.transformOrigin = transition.origin;
+    $effect(() => {
+        const open = isOpen();
+        untrack(() => {
+            const { hidden, shown, exited = hidden, enter, exit } = transition;
+            if (open) {
+                controls = animate(node, started ? shown : fromTo(hidden, shown), enter);
+            }
+            else {
+                const current = (controls = animate(node, exited, exit));
+                current.then(() => {
+                    if (controls === current)
+                        onExitComplete?.();
+                });
+            }
+            started = true;
+        });
+    });
+    return () => controls?.stop();
+};
+/**
+ * Keeps an element mounted until its exit animation finishes — the Motion replacement for a
+ * Svelte `out:` transition. Construct during component init.
+ *
+ * ```svelte
+ * <script>
+ *   const sheet = new Presence(() => open);
+ * </script>
+ *
+ * {#if sheet.mounted}
+ *   <div {@attach sheet.attach(enterExit.sideSheet)}>…</div>
+ * {/if}
+ * ```
+ */
+export class Presence {
+    #isOpen;
+    // Plain field on purpose: set while open, read after close to hold the element for its exit.
+    #held = false;
+    #exits = $state(0);
+    constructor(isOpen) {
+        this.#isOpen = isOpen;
+    }
+    /** True while open, and while the exit animation is still playing. */
+    mounted = $derived.by(() => {
+        void this.#exits;
+        if (this.#isOpen())
+            this.#held = true;
+        return this.#held;
+    });
+    attach = (transition) => presence(this.#isOpen, transition, () => {
+        this.#held = false;
+        this.#exits++;
+    });
+}

package/dist/animation/shapeMorph.svelte.d.ts

@@ -0,0 +1,52 @@
+import { type AnimationPlaybackControls } from 'motion';
+import type { Attachment } from 'svelte/attachments';
+import { type SpringToken } from './spring.js';
+/**
+ * The 35 shapes of the M3 Expressive shape library, in the order of the spec sheet.
+ * https://m3.material.io/styles/shape
+ */
+export declare const shapeNames: readonly ["circle", "square", "slanted", "arch", "semicircle", "oval", "pill", "triangle", "arrow", "fan", "diamond", "clamshell", "pentagon", "gem", "verySunny", "sunny", "fourSidedCookie", "sixSidedCookie", "sevenSidedCookie", "nineSidedCookie", "twelveSidedCookie", "fourLeafClover", "eightLeafClover", "burst", "softBurst", "boom", "softBoom", "flower", "puffy", "puffyDiamond", "ghostish", "pixelCircle", "pixelTriangle", "bun", "heart"];
+export type ShapeName = (typeof shapeNames)[number];
+/**
+ * Every shape as a 720-point path in a 380 × 380 viewBox (`<svg viewBox="0 0 380 380">`). All
+ * share one command structure, start point and winding, so any two morph cleanly. Use these for
+ * large, hero-sized shapes; for anything icon-sized prefer {@link animatableShapesSmall}.
+ *
+ * Importing the map pulls in all 35 paths (~315 KB unminified). To ship only a few, import the
+ * individual `pathAnimatable*` constants instead.
+ */
+export declare const animatableShapes: Record<"circle" | "square" | "slanted" | "arch" | "semicircle" | "oval" | "pill" | "triangle" | "arrow" | "fan" | "diamond" | "clamshell" | "pentagon" | "gem" | "verySunny" | "sunny" | "fourSidedCookie" | "sixSidedCookie" | "sevenSidedCookie" | "nineSidedCookie" | "twelveSidedCookie" | "fourLeafClover" | "eightLeafClover" | "burst" | "softBurst" | "boom" | "softBoom" | "flower" | "puffy" | "puffyDiamond" | "ghostish" | "pixelCircle" | "pixelTriangle" | "bun" | "heart", string>;
+/**
+ * Every shape as a 120-point path in a 48 × 48 viewBox (38 × 38 shape, centred). Same guarantees
+ * as {@link animatableShapes} at an eighth of the size: the set for icons, avatars, indicators and
+ * FABs. Never mix paths from the two sets in one morph — their point counts differ.
+ */
+export declare const animatableShapesSmall: Record<"circle" | "square" | "slanted" | "arch" | "semicircle" | "oval" | "pill" | "triangle" | "arrow" | "fan" | "diamond" | "clamshell" | "pentagon" | "gem" | "verySunny" | "sunny" | "fourSidedCookie" | "sixSidedCookie" | "sevenSidedCookie" | "nineSidedCookie" | "twelveSidedCookie" | "fourLeafClover" | "eightLeafClover" | "burst" | "softBurst" | "boom" | "softBoom" | "flower" | "puffy" | "puffyDiamond" | "ghostish" | "pixelCircle" | "pixelTriangle" | "bun" | "heart", string>;
+/**
+ * Morphs an SVG `<path>` from its current `d` to `to` on an M3 spring (default `fastSpatial`,
+ * the token for shape morphs). Both paths must come from the same animatable set. Motion drives
+ * the progress; the spring's overshoot carries through into the shape. Under
+ * `prefers-reduced-motion` the shape swaps instantly (M3: turn off shape morphing).
+ *
+ * Starting a new morph mid-flight picks up from the in-between shape on screen, so stop the
+ * previous controls first — {@link shapeMorph} does this for you.
+ *
+ * ```ts
+ * morphShape(path, animatableShapesSmall.heart);
+ * ```
+ */
+export declare const morphShape: (path: SVGPathElement, to: string, spring?: SpringToken) => AnimationPlaybackControls | undefined;
+/**
+ * Attachment that keeps a `<path>` on `shape()` and morphs whenever it changes. The first shape
+ * renders without animating.
+ *
+ * ```svelte
+ * <svg viewBox="0 0 48 48">
+ *   <path
+ *     fill="currentColor"
+ *     {@attach shapeMorph(() => animatableShapesSmall[selected ? 'sunny' : 'circle'])}
+ *   />
+ * </svg>
+ * ```
+ */
+export declare const shapeMorph: (shape: () => string, spring?: SpringToken) => Attachment<SVGPathElement>;

package/dist/animation/shapeMorph.svelte.js

@@ -0,0 +1,112 @@
+import { animate, mix } from 'motion';
+import { untrack } from 'svelte';
+import * as large from './shapesAnimatable.js';
+import * as small from './shapesAnimatableSmall.js';
+import { springTokens, springTransition } from './spring.js';
+/**
+ * The 35 shapes of the M3 Expressive shape library, in the order of the spec sheet.
+ * https://m3.material.io/styles/shape
+ */
+export const shapeNames = [
+    'circle',
+    'square',
+    'slanted',
+    'arch',
+    'semicircle',
+    'oval',
+    'pill',
+    'triangle',
+    'arrow',
+    'fan',
+    'diamond',
+    'clamshell',
+    'pentagon',
+    'gem',
+    'verySunny',
+    'sunny',
+    'fourSidedCookie',
+    'sixSidedCookie',
+    'sevenSidedCookie',
+    'nineSidedCookie',
+    'twelveSidedCookie',
+    'fourLeafClover',
+    'eightLeafClover',
+    'burst',
+    'softBurst',
+    'boom',
+    'softBoom',
+    'flower',
+    'puffy',
+    'puffyDiamond',
+    'ghostish',
+    'pixelCircle',
+    'pixelTriangle',
+    'bun',
+    'heart'
+];
+const byName = (paths, prefix) => Object.fromEntries(shapeNames.map((name) => [name, paths[prefix + name[0].toUpperCase() + name.slice(1)]]));
+/**
+ * Every shape as a 720-point path in a 380 × 380 viewBox (`<svg viewBox="0 0 380 380">`). All
+ * share one command structure, start point and winding, so any two morph cleanly. Use these for
+ * large, hero-sized shapes; for anything icon-sized prefer {@link animatableShapesSmall}.
+ *
+ * Importing the map pulls in all 35 paths (~315 KB unminified). To ship only a few, import the
+ * individual `pathAnimatable*` constants instead.
+ */
+export const animatableShapes = byName(large, 'pathAnimatable');
+/**
+ * Every shape as a 120-point path in a 48 × 48 viewBox (38 × 38 shape, centred). Same guarantees
+ * as {@link animatableShapes} at an eighth of the size: the set for icons, avatars, indicators and
+ * FABs. Never mix paths from the two sets in one morph — their point counts differ.
+ */
+export const animatableShapesSmall = byName(small, 'pathAnimatableSmall');
+const prefersReducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+/**
+ * Morphs an SVG `<path>` from its current `d` to `to` on an M3 spring (default `fastSpatial`,
+ * the token for shape morphs). Both paths must come from the same animatable set. Motion drives
+ * the progress; the spring's overshoot carries through into the shape. Under
+ * `prefers-reduced-motion` the shape swaps instantly (M3: turn off shape morphing).
+ *
+ * Starting a new morph mid-flight picks up from the in-between shape on screen, so stop the
+ * previous controls first — {@link shapeMorph} does this for you.
+ *
+ * ```ts
+ * morphShape(path, animatableShapesSmall.heart);
+ * ```
+ */
+export const morphShape = (path, to, spring = springTokens.fastSpatial) => {
+    const from = path.getAttribute('d');
+    if (!from || from === to || prefersReducedMotion()) {
+        path.setAttribute('d', to);
+        return;
+    }
+    const shape = mix(from, to);
+    return animate(0, 1, {
+        ...springTransition(spring),
+        onUpdate: (progress) => path.setAttribute('d', shape(progress))
+    });
+};
+/**
+ * Attachment that keeps a `<path>` on `shape()` and morphs whenever it changes. The first shape
+ * renders without animating.
+ *
+ * ```svelte
+ * <svg viewBox="0 0 48 48">
+ *   <path
+ *     fill="currentColor"
+ *     {@attach shapeMorph(() => animatableShapesSmall[selected ? 'sunny' : 'circle'])}
+ *   />
+ * </svg>
+ * ```
+ */
+export const shapeMorph = (shape, spring) => (path) => {
+    let controls;
+    $effect(() => {
+        const to = shape();
+        untrack(() => {
+            controls?.stop();
+            controls = morphShape(path, to, spring);
+        });
+    });
+    return () => controls?.stop();
+};