@noxlovette/material 0.4.8 → 0.5.0

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. */
+    sideSheet: {
+        hidden: { transform: 'translateX(100%)' },
+        shown: { transform: 'translateX(0%)' },
+        enter: springTransition(springTokens.spatial),
+        exit: springTransition(springTokens.effects)
+    },
+    /** Bottom sheet anchored to the bottom edge. */
+    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,5 @@
-export * from './easing.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,5 @@
-export * from './easing.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/sharedAxisTransition.d.ts

@@ -1,38 +1,36 @@
-import type { TransitionOptions } from './transitionTypes.js';
-type SharedAxisOptions = {
-    direction: 'X' | 'Y';
-    /**
-     * true if this element is on the top/left of things
-     * if it's first, then use transition: and set it to true
-     * if it's last, then use transition: and set it to false
-     * if it's in between, use separate in: and out: statements:
-     * > set it to false when it's interacting with the left side, and true when interacting with its right
-     * > in order to implement this, try something like using a prevPage variable:
-     * > ```
-     * > {:else if page == 1}
-     * > <div
-     * >   in:sharedAxisTransition={{
-     * >     direction: "X",
-     * >     rightSeam: prevPage > 1, (if we're transitioning from a page on the right, rightseam is true)
-     * >   }}
-     * >   out:sharedAxisTransition={{
-     * >     direction: "X",
-     * >     rightSeam: page > 1, (if we're transitioning to a page on the right, rightseam is true)
-     * >   }}
-     * > >
-     * > ```
-     *
-     * i went insane over figuring this out :)
-     */
-    rightSeam: boolean;
-} | {
-    direction: 'Z';
-    leaving: boolean;
-};
-export declare const sharedAxisTransition: (node: Element, options: TransitionOptions & SharedAxisOptions) => {
-    delay: number | undefined;
-    duration: number;
-    easing: (t: number) => number;
-    css: (t: number, u: number) => string;
-};
+import { type ViewTransitionTargetDefinition } from 'motion';
+import { type SpringToken } from './spring.js';
+export type NavigationDirection = 'forward' | 'backward';
+interface NavigationOptions {
+    /** The region whose content changes. Omit to transition the whole page. */
+    target?: ViewTransitionTargetDefinition;
+    /** `forward` moves deeper / to the next item, `backward` returns. */
+    direction?: NavigationDirection;
+    spring?: SpringToken;
+}
+export interface SharedAxisOptions extends NavigationOptions {
+    /** `x` for horizontal steps, `y` for vertical, `z` for parent → child depth. */
+    axis?: 'x' | 'y' | 'z';
+}
+/**
+ * M3 forward and backward (shared axis): outgoing and incoming content travel together along one
+ * axis while fading through each other.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#forward-and-backward
+ *
+ * `update` performs the DOM change (`async () => { step++; await tick(); }`). Built on Motion's
+ * `animateView()` — both states never need to coexist in the DOM.
+ */
+export declare const sharedAxis: (update: () => void | Promise<void>, { target, axis, direction, spring }?: SharedAxisOptions) => import("motion-dom").ViewTransitionBuilder;
+/**
+ * M3 lateral: peer screens at the same level (tabs, carousels) slide past each other edge to edge,
+ * without fading — the new screen pushes the old one out.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#lateral
+ */
+export declare const lateral: (update: () => void | Promise<void>, { target, direction, spring }?: NavigationOptions) => import("motion-dom").ViewTransitionBuilder;
+/**
+ * M3 top level (fade through): destinations with no spatial relationship, e.g. navigation bar
+ * items. The outgoing screen fades out, then the incoming one fades in while scaling up from 92%.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#top-level
+ */
+export declare const fadeThrough: (update: () => void | Promise<void>, { target, spring }?: Omit<NavigationOptions, "direction">) => import("motion-dom").ViewTransitionBuilder;
 export {};

package/dist/animation/sharedAxisTransition.js

@@ -1,23 +1,51 @@
-import { easeEmphasized } from './easing.js';
-/* protip: set a background color on the items, and utilize position relative + absolute to let them overlap */
-export const sharedAxisTransition = (node, options) => {
-    void node;
-    return {
-        delay: options.delay,
-        duration: options.duration ?? 500,
-        easing: options.easing ?? easeEmphasized,
-        css: (t, u) => {
-            const opacity = (t - 0.35) * (1 / 0.35);
-            if (options.direction == 'Z') {
-                const factor = options.leaving ? u * 0.1 + 1 : t * 0.2 + 0.8;
-                let css = `transform: scale(${factor.toFixed(3)});`;
-                if (!options.leaving)
-                    css += `opacity: ${opacity.toFixed(3)};`;
-                return css;
-            }
-            const factor = u * (options.rightSeam ? -30 : 30);
-            return (`transform: translate${options.direction}(${factor.toFixed(3)}px);` +
-                `opacity: ${opacity.toFixed(3)}`);
-        }
-    };
+import { animateView } from 'motion';
+import { springTokens, springTransition } from './spring.js';
+const SHARED_AXIS_OFFSET_PX = 30;
+const view = (update, target, spring) => {
+    const builder = animateView(update, springTransition(spring));
+    return target ? builder.add(target) : builder;
 };
+/* Outgoing content clears quickly; incoming content waits a beat so the two never overlap fully. */
+const fadeOut = springTransition(springTokens.fastEffects);
+const fadeIn = { ...springTransition(springTokens.effects), delay: 0.05 };
+/**
+ * M3 forward and backward (shared axis): outgoing and incoming content travel together along one
+ * axis while fading through each other.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#forward-and-backward
+ *
+ * `update` performs the DOM change (`async () => { step++; await tick(); }`). Built on Motion's
+ * `animateView()` — both states never need to coexist in the DOM.
+ */
+export const sharedAxis = (update, { target, axis = 'x', direction = 'forward', spring = springTokens.spatial } = {}) => {
+    const forward = direction === 'forward';
+    const [outgoing, incoming] = axis === 'z'
+        ? [`scale(${forward ? 1.1 : 0.8})`, `scale(${forward ? 0.8 : 1.1})`]
+        : [
+            `translate${axis.toUpperCase()}(${forward ? -SHARED_AXIS_OFFSET_PX : SHARED_AXIS_OFFSET_PX}px)`,
+            `translate${axis.toUpperCase()}(${forward ? SHARED_AXIS_OFFSET_PX : -SHARED_AXIS_OFFSET_PX}px)`
+        ];
+    const rest = axis === 'z' ? 'scale(1)' : `translate${axis.toUpperCase()}(0px)`;
+    return view(update, target, spring)
+        .old({ opacity: [1, 0], transform: [rest, outgoing] }, { opacity: fadeOut })
+        .new({ opacity: [0, 1], transform: [incoming, rest] }, { opacity: fadeIn });
+};
+/**
+ * M3 lateral: peer screens at the same level (tabs, carousels) slide past each other edge to edge,
+ * without fading — the new screen pushes the old one out.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#lateral
+ */
+export const lateral = (update, { target, direction = 'forward', spring = springTokens.spatial } = {}) => {
+    const sign = direction === 'forward' ? 1 : -1;
+    const builder = view(update, target, spring)
+        .old({ transform: ['translateX(0%)', `translateX(${-sign * 100}%)`] })
+        .new({ transform: [`translateX(${sign * 100}%)`, 'translateX(0%)'] });
+    return target ? builder.crop(true) : builder;
+};
+/**
+ * M3 top level (fade through): destinations with no spatial relationship, e.g. navigation bar
+ * items. The outgoing screen fades out, then the incoming one fades in while scaling up from 92%.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#top-level
+ */
+export const fadeThrough = (update, { target, spring = springTokens.spatial } = {}) => view(update, target, spring)
+    .old({ opacity: [1, 0] }, fadeOut)
+    .new({ opacity: [0, 1], transform: ['scale(0.92)', 'scale(1)'] }, { opacity: { ...springTransition(springTokens.effects), delay: 0.09 } });

package/dist/animation/skeleton.d.ts

@@ -0,0 +1,11 @@
+import type { Attachment } from 'svelte/attachments';
+/**
+ * M3 skeleton loader: a placeholder pulses until real content replaces it. Swap the placeholder
+ * for the content with `presence(…, enterExit.fade)` so the reveal is a fade, not a cut.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#skeleton-loaders
+ *
+ * ```svelte
+ * <div class="bg-md-sys-color-surface-container-highest h-4 rounded-sm" {@attach skeleton}></div>
+ * ```
+ */
+export declare const skeleton: Attachment<HTMLElement>;

package/dist/animation/skeleton.js

@@ -0,0 +1,23 @@
+import { animate } from 'motion';
+import { springTokens, springTransition } from './spring.js';
+/* Hold at each end of the pulse — a critically damped spring alone settles in ~370ms, which reads
+   as flicker. Not an M3 value: tune by eye. */
+const PULSE_HOLD_S = 0.5;
+/**
+ * M3 skeleton loader: a placeholder pulses until real content replaces it. Swap the placeholder
+ * for the content with `presence(…, enterExit.fade)` so the reveal is a fade, not a cut.
+ * https://m3.material.io/styles/motion/transitions/transition-patterns#skeleton-loaders
+ *
+ * ```svelte
+ * <div class="bg-md-sys-color-surface-container-highest h-4 rounded-sm" {@attach skeleton}></div>
+ * ```
+ */
+export const skeleton = (node) => {
+    const controls = animate(node, { opacity: [1, 0.4] }, {
+        ...springTransition(springTokens.slowEffects),
+        repeat: Infinity,
+        repeatType: 'reverse',
+        repeatDelay: PULSE_HOLD_S
+    });
+    return () => controls.stop();
+};

package/dist/animation/spring.d.ts

@@ -0,0 +1,61 @@
+import { spring } from 'motion';
+/**
+ * M3 Expressive spring tokens: `stiffness` plus a `dampingRatio`
+ *
+ * - **spatial** springs move things (position, size, shape) and overshoot slightly.
+ * - **effects** springs change things in place (opacity, color) and are critically damped.
+ *
+ * https://m3.material.io/styles/motion/overview/specs
+ */
+export declare const springTokens: {
+    readonly fastSpatial: {
+        readonly stiffness: 800;
+        readonly dampingRatio: 0.6;
+    };
+    readonly spatial: {
+        readonly stiffness: 380;
+        readonly dampingRatio: 0.8;
+    };
+    readonly slowSpatial: {
+        readonly stiffness: 200;
+        readonly dampingRatio: 0.8;
+    };
+    readonly fastEffects: {
+        readonly stiffness: 3800;
+        readonly dampingRatio: 1;
+    };
+    readonly effects: {
+        readonly stiffness: 1600;
+        readonly dampingRatio: 1;
+    };
+    readonly slowEffects: {
+        readonly stiffness: 800;
+        readonly dampingRatio: 1;
+    };
+};
+export type SpringToken = {
+    stiffness: number;
+    dampingRatio: number;
+};
+/**
+ * A spring token as Motion transition options, for `animate()` / `animateView()`. Physics-based
+ * (stiffness/damping, mass 1), so an animation that interrupts another inherits its velocity.
+ *
+ * ```ts
+ * animate(node, { transform: 'scale(1)' }, springTransition(springTokens.fastSpatial));
+ * ```
+ */
+export declare const springTransition: ({ stiffness, dampingRatio }: SpringToken) => {
+    readonly type: typeof spring;
+    readonly stiffness: number;
+    readonly damping: number;
+    readonly mass: 1;
+};
+/**
+ * A spring as CSS `transition` parts: a settle `duration` and a `linear()` `easing`.
+ * Used by `scripts/generate-motion-springs.ts` to bake the tokens into `styles/motion.css`.
+ */
+export declare const springCss: (token: SpringToken, resolutionMs?: number) => {
+    duration: string;
+    easing: string;
+};

package/dist/animation/spring.js

@@ -0,0 +1,53 @@
+import { generateLinearEasing, spring } from 'motion';
+/**
+ * M3 Expressive spring tokens: `stiffness` plus a `dampingRatio`
+ *
+ * - **spatial** springs move things (position, size, shape) and overshoot slightly.
+ * - **effects** springs change things in place (opacity, color) and are critically damped.
+ *
+ * https://m3.material.io/styles/motion/overview/specs
+ */
+export const springTokens = {
+    fastSpatial: { stiffness: 800, dampingRatio: 0.6 },
+    spatial: { stiffness: 380, dampingRatio: 0.8 },
+    slowSpatial: { stiffness: 200, dampingRatio: 0.8 },
+    fastEffects: { stiffness: 3800, dampingRatio: 1 },
+    effects: { stiffness: 1600, dampingRatio: 1 },
+    slowEffects: { stiffness: 800, dampingRatio: 1 }
+};
+const STEP_MS = 10;
+const MAX_MS = 5000;
+const resolveSpring = (token) => {
+    // Motion takes an absolute damping coefficient; M3 specifies a ratio (mass is 1).
+    const { stiffness, damping } = springTransition(token);
+    const generator = spring({ keyframes: [0, 1], stiffness, damping });
+    let duration = 0;
+    while (!generator.next(duration).done && duration < MAX_MS)
+        duration += STEP_MS;
+    return { duration, at: (progress) => generator.next(duration * progress).value };
+};
+/**
+ * A spring token as Motion transition options, for `animate()` / `animateView()`. Physics-based
+ * (stiffness/damping, mass 1), so an animation that interrupts another inherits its velocity.
+ *
+ * ```ts
+ * animate(node, { transform: 'scale(1)' }, springTransition(springTokens.fastSpatial));
+ * ```
+ */
+export const springTransition = ({ stiffness, dampingRatio }) => ({
+    // The generator itself, not the string 'spring': the view-transition / WAAPI path
+    // (`animateView`, NativeAnimation) only bakes springs from the function and otherwise falls
+    // back to a 300ms easeOut.
+    type: spring,
+    stiffness,
+    damping: dampingRatio * 2 * Math.sqrt(stiffness),
+    mass: 1
+});
+/**
+ * A spring as CSS `transition` parts: a settle `duration` and a `linear()` `easing`.
+ * Used by `scripts/generate-motion-springs.ts` to bake the tokens into `styles/motion.css`.
+ */
+export const springCss = (token, resolutionMs = STEP_MS) => {
+    const { duration, at } = resolveSpring(token);
+    return { duration: `${duration}ms`, easing: generateLinearEasing(at, duration, resolutionMs) };
+};

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

@@ -0,0 +1,22 @@
+import { type SpringToken } from './spring.js';
+/**
+ * A number that springs towards a reactive target — for values rendered as geometry (a progress
+ * fill, a slider handle) rather than as a Motion-animated element. Retargeting mid-flight keeps
+ * the spring's velocity. Construct during component init.
+ *
+ * ```svelte
+ * <script>
+ *   const shown = new SpringValue(() => percent, springTokens.slowEffects);
+ * </script>
+ *
+ * <div style:width="{shown.current}%"></div>
+ * ```
+ *
+ * `immediate` jumps straight to the target while it returns true — e.g. while a handle is dragged,
+ * where the value must track the pointer 1:1.
+ */
+export declare class SpringValue {
+    #private;
+    current: number;
+    constructor(target: () => number, spring: SpringToken, immediate?: () => boolean);
+}

package/dist/animation/springValue.svelte.js

@@ -0,0 +1,42 @@
+import { animate } from 'motion';
+import { untrack } from 'svelte';
+import { springTransition } from './spring.js';
+/**
+ * A number that springs towards a reactive target — for values rendered as geometry (a progress
+ * fill, a slider handle) rather than as a Motion-animated element. Retargeting mid-flight keeps
+ * the spring's velocity. Construct during component init.
+ *
+ * ```svelte
+ * <script>
+ *   const shown = new SpringValue(() => percent, springTokens.slowEffects);
+ * </script>
+ *
+ * <div style:width="{shown.current}%"></div>
+ * ```
+ *
+ * `immediate` jumps straight to the target while it returns true — e.g. while a handle is dragged,
+ * where the value must track the pointer 1:1.
+ */
+export class SpringValue {
+    current = $state(0);
+    #controls;
+    constructor(target, spring, immediate) {
+        this.current = untrack(target);
+        $effect(() => {
+            const to = target();
+            const jump = immediate?.() ?? false;
+            untrack(() => {
+                this.#controls?.stop();
+                if (jump) {
+                    this.current = to;
+                    return;
+                }
+                this.#controls = animate(this.current, to, {
+                    ...springTransition(spring),
+                    onUpdate: (latest) => (this.current = latest)
+                });
+            });
+        });
+        $effect(() => () => this.#controls?.stop());
+    }
+}

package/dist/animation/transition.d.ts

@@ -1,4 +1,6 @@
 export * from './containerTransform.js';
 export * from './enterExit.js';
-export * from './outroClass.js';
+export * from './presence.svelte.js';
 export * from './sharedAxisTransition.js';
+export * from './skeleton.js';
+export * from './springValue.svelte.js';

package/dist/animation/transition.js

@@ -1,4 +1,6 @@
 export * from './containerTransform.js';
 export * from './enterExit.js';
-export * from './outroClass.js';
+export * from './presence.svelte.js';
 export * from './sharedAxisTransition.js';
+export * from './skeleton.js';
+export * from './springValue.svelte.js';

package/dist/attachments/clickOutside.d.ts

@@ -0,0 +1,13 @@
+import type { Attachment } from 'svelte/attachments';
+/**
+ * Calls `handler` when a click lands outside the element. Listens in the capture phase so
+ * it still fires when something inside the page stops propagation.
+ *
+ * Attach it conditionally so the document listener only exists while there is something to
+ * dismiss:
+ *
+ * ```svelte
+ * <div {@attach open && clickOutside(() => (open = false))}>...</div>
+ * ```
+ */
+export declare function clickOutside(handler: (event: MouseEvent) => void): Attachment<HTMLElement>;