@streamsai/ui 0.0.0-stage → 0.1.1

package/dist/motion/config.js

@@ -0,0 +1,429 @@
+/** Seconds (what `motion` takes). tokens.css carries the same numbers in ms. */
+export const duration = {
+    /** Sense `short-100`: a small element leaving (`presets.scaleIn`'s exit). */
+    short: 0.1,
+    /** Hover washes, icon swaps, press feedback: anything the pointer is already on. */
+    fast: 0.12,
+    /** The default: popups, panels, rows entering, route content, collapses. */
+    base: 0.2,
+    /** Large surfaces travelling a long way: sheets, the details pane, the viewer. */
+    slow: 0.32,
+    /** One orchestrated page-load moment (brand and auth pages, `presets.reveal`). */
+    reveal: 0.48,
+};
+export const ease = {
+    /** Symmetric, for things that change in place (colour, width, rotation). */
+    standard: [0.4, 0, 0.2, 1],
+    /** Entrances: fast start, long soft landing. */
+    out: [0.16, 1, 0.3, 1],
+    /** Exits: leave quickly, no lingering. */
+    in: [0.4, 0, 1, 1],
+    /** Sense `ease-enter`: decelerates into place, for scale entrances. */
+    enter: [0, 0, 0.2, 1],
+    /** Sense `ease-exit`: accelerates away, for scale exits. */
+    exit: [0.6, 0, 1, 1],
+};
+/** Springs for things that move because the layout moved (reorders, pills, indicators). */
+export const spring = {
+    /** Layout shifts, reorders, a tab indicator sliding: settles in about `base`. */
+    snappy: { type: 'spring', visualDuration: 0.22, bounce: 0.12 },
+    /** Small things popping into place (reactions, badges): a touch of overshoot. */
+    pop: { type: 'spring', visualDuration: 0.24, bounce: 0.28 },
+};
+/** Pixels of travel. Motion here suggests direction, it never carries content across the screen. */
+export const distance = {
+    /** Rows, route content, toasts: the default rise. */
+    nudge: 4,
+    /** Cards and empty states arriving on their own. */
+    rise: 8,
+    /** Panels and drawers sliding in from an edge. */
+    slide: 16,
+};
+/** Scale a popping element starts from. */
+export const scale = {
+    pop: 0.94,
+    /** Popups and dialogs growing out of their trigger. */
+    popup: 0.96,
+    subtle: 0.98,
+    /** Sense `scale-enter` / `scale-exit`: never from 0, always from 95%. */
+    enter: 0.95,
+};
+/** Seconds between siblings in a staggered group, and the ceiling on the whole cascade. */
+export const stagger = {
+    step: 0.03,
+    /** Sense `short-20`: the offset between peers entering together, and an exit's fade delay. */
+    offset: 0.02,
+    /** Items beyond this delay arrive together, so a long list never takes long to appear. */
+    max: 0.18,
+};
+/** Ready-made transitions for the common cases. */
+export const transitions = {
+    fast: { duration: duration.fast, ease: ease.standard },
+    base: { duration: duration.base, ease: ease.standard },
+    enter: { duration: duration.base, ease: ease.out },
+    /** Popups, menus and tooltips: they answer a click, so they arrive at `fast`. */
+    enterFast: { duration: duration.fast, ease: ease.out },
+    exit: { duration: duration.fast, ease: ease.in },
+    slow: { duration: duration.slow, ease: ease.out },
+    /** A meter that follows a clock ticking every `base`: each step is linear so the sum drains evenly. */
+    meter: { duration: duration.base, ease: 'linear' },
+    layout: spring.snappy,
+    pop: spring.pop,
+};
+/**
+ * Pointer / tap press feedback. Use on a `motion.*` element as
+ * `whileTap={press.whileTap}` (and `transition={press.transition}`), never CSS
+ * `active:scale-*`. Reduced motion is honoured by `MotionProvider`.
+ *
+ * `commit.scale` stays a mutable `number[]` so it is assignable to motion's
+ * `animate` keyframes (a `readonly` tuple from `as const` is not).
+ */
+export const press = {
+    /** Scale while the pointer is down — quiet shrink, not a bounce. */
+    scale: scale.pop,
+    whileTap: { scale: scale.pop },
+    transition: transitions.fast,
+    /**
+     * One-shot shrink→grow for keyboard / programmatic commit (e.g. Enter-to-send)
+     * where `whileTap` never fires. Drive `animate` from a short-lived flag.
+     */
+    commit: {
+        scale: [1, scale.pop, 1],
+        transition: spring.pop,
+    },
+};
+/**
+ * Prop bags for `motion.*` elements: `<motion.div {...presets.rise} />`. Each carries its own
+ * enter and exit, so it behaves the same inside `AnimatePresence` or on its own. Reach for these
+ * before writing an inline `initial` / `animate`; add a preset here rather than tuning one call site.
+ */
+export const presets = {
+    /** Opacity only. Overlays, content swapping in place, anything that should not move. */
+    fade: {
+        initial: { opacity: 0 },
+        animate: { opacity: 1, transition: transitions.enter },
+        exit: { opacity: 0, transition: transitions.exit },
+    },
+    /** The default entrance: fade plus a small rise. Rows, route content, messages. */
+    rise: {
+        initial: { opacity: 0, y: distance.nudge },
+        animate: { opacity: 1, y: 0, transition: transitions.enter },
+        exit: { opacity: 0, y: -distance.nudge / 2, transition: transitions.exit },
+    },
+    /** A card or empty state arriving on its own, a little more travel than `rise`. */
+    lift: {
+        initial: { opacity: 0, y: distance.rise },
+        animate: { opacity: 1, y: 0, transition: transitions.slow },
+        exit: { opacity: 0, y: distance.nudge, transition: transitions.exit },
+    },
+    /** Small elements appearing (reaction pills, badges, counters, indicators). */
+    pop: {
+        initial: { opacity: 0, scale: scale.pop },
+        animate: { opacity: 1, scale: 1, transition: transitions.pop },
+        exit: { opacity: 0, scale: scale.pop, transition: transitions.exit },
+    },
+    /** One piece of content replacing another in the same spot (Copy → Copied, icon swaps). */
+    swap: {
+        initial: { opacity: 0, scale: scale.subtle, filter: 'blur(2px)' },
+        // `transitionEnd` drops the settled filter, so resting text is not left on a filtered layer.
+        animate: {
+            opacity: 1,
+            scale: 1,
+            filter: 'blur(0px)',
+            transition: transitions.fast,
+            transitionEnd: { filter: 'none' },
+        },
+        exit: { opacity: 0, scale: scale.subtle, filter: 'blur(2px)', transition: transitions.exit },
+    },
+    /**
+     * Odometer roll for a rising count: new value enters from the top, old exits downward.
+     * Clip the parent (`overflow-hidden`) so the travel stays inside the glyph box.
+     */
+    wheelUp: {
+        initial: { y: '-100%', opacity: 0 },
+        animate: { y: 0, opacity: 1, transition: transitions.fast },
+        exit: { y: '100%', opacity: 0, transition: { duration: duration.short, ease: ease.in } },
+    },
+    /** Reverse of `wheelUp` — a falling count rolls the other way. */
+    wheelDown: {
+        initial: { y: '100%', opacity: 0 },
+        animate: { y: 0, opacity: 1, transition: transitions.fast },
+        exit: { y: '-100%', opacity: 0, transition: { duration: duration.short, ease: ease.in } },
+    },
+    /** A dialog arriving over its backdrop: a fade, a slight grow and a short rise. */
+    dialog: {
+        initial: { opacity: 0, scale: scale.popup, y: distance.nudge },
+        animate: { opacity: 1, scale: 1, y: 0, transition: transitions.enter },
+        exit: { opacity: 0, scale: scale.subtle, transition: transitions.exit },
+    },
+    /** One-off page-load moment for brand surfaces (sign-in, the landing hero). */
+    reveal: {
+        initial: { opacity: 0, y: distance.rise, filter: 'blur(4px)' },
+        animate: {
+            opacity: 1,
+            y: 0,
+            filter: 'blur(0px)',
+            transition: { duration: duration.reveal, ease: ease.out },
+            transitionEnd: { filter: 'none' },
+        },
+        exit: { opacity: 0, transition: transitions.exit },
+    },
+    /** Height 0 ↔ auto, for disclosure content and rows that expand in place. */
+    collapse: {
+        initial: { height: 0, opacity: 0 },
+        animate: {
+            height: 'auto',
+            opacity: 1,
+            transition: { height: transitions.enter, opacity: { ...transitions.enter, delay: 0.04 } },
+        },
+        exit: {
+            height: 0,
+            opacity: 0,
+            transition: { height: transitions.base, opacity: transitions.exit },
+        },
+    },
+    /**
+     * Width 0 ↔ auto, for side panels that take space from their neighbour (the details pane): the
+     * neighbour narrows with the panel instead of snapping to its final width in one frame. The
+     * panel is an opaque surface, so it slides in solid with its edge. A fade on its own clock made
+     * the neighbour move while the panel was still invisible (and after it had gone), which read as
+     * two animations instead of one.
+     */
+    collapseX: {
+        initial: { width: 0 },
+        animate: { width: 'auto', transition: transitions.enter },
+        exit: { width: 0, transition: transitions.base },
+    },
+    /**
+     * Sense `scale-enter` / `scale-exit`: grows from 95% on `ease.enter` with a linear fade over
+     * `base`, and leaves faster (`short`) on `ease.exit` with its fade a beat behind. Chips, thumbnails
+     * and cards that appear in place without travelling.
+     */
+    scaleIn: {
+        initial: { opacity: 0, scale: scale.enter },
+        animate: {
+            opacity: 1,
+            scale: 1,
+            transition: {
+                scale: { duration: duration.base, ease: ease.enter },
+                opacity: { duration: duration.base, ease: 'linear' },
+            },
+        },
+        exit: {
+            opacity: 0,
+            scale: scale.enter,
+            transition: {
+                scale: { duration: duration.short, ease: ease.exit },
+                opacity: { duration: duration.short, ease: 'linear', delay: stagger.offset },
+            },
+        },
+    },
+};
+/**
+ * Menus, popovers, selects, tooltips and hover cards: a quick scale-and-fade that drifts a few
+ * pixels out from the trigger. `side` is where the popup sits relative to its trigger.
+ */
+export const popup = (side = 'bottom', dir = 'ltr') => {
+    const physical = side === 'inline-start'
+        ? dir === 'rtl'
+            ? 'right'
+            : 'left'
+        : side === 'inline-end'
+            ? dir === 'rtl'
+                ? 'left'
+                : 'right'
+            : side;
+    const n = distance.nudge;
+    const from = { top: { y: n }, bottom: { y: -n }, left: { x: n }, right: { x: -n }, none: {} }[physical];
+    return {
+        initial: { opacity: 0, scale: scale.popup, x: 0, y: 0, ...from },
+        animate: { opacity: 1, scale: 1, x: 0, y: 0, transition: transitions.enterFast },
+        exit: { opacity: 0, scale: scale.popup, transition: transitions.exit },
+    };
+};
+/**
+ * A popup that fades and drifts a few pixels from the side it opens on, without the scale of
+ * `popup`. For a surface that reads as part of the form it belongs to: the dropdown lists and
+ * pickers of a dense editor. `tip` arrives faster than a list; `fade` does not move at all (a
+ * list that opens on hover).
+ */
+export const drift = (side = 'bottom', kind = 'list') => {
+    const seconds = kind === 'tip' ? duration.short : kind === 'fade' ? duration.fast : 0.18;
+    const from = kind === 'fade' ? 0 : side === 'top' ? distance.nudge : side === 'bottom' ? -distance.nudge : 0;
+    // The CSS `ease` curve, which the design's fade-and-rise is specified with.
+    const transition = { duration: seconds, ease: [0.25, 0.1, 0.25, 1] };
+    return {
+        initial: { opacity: 0, y: from },
+        animate: { opacity: 1, y: 0, transition },
+        exit: { opacity: 0, y: from, transition },
+    };
+};
+/** Sheets and drawers: the whole panel travels in from its edge and back out. */
+export const sheet = (side) => {
+    const off = {
+        top: { y: '-100%' },
+        bottom: { y: '100%' },
+        left: { x: '-100%' },
+        right: { x: '100%' },
+    }[side];
+    const home = 'x' in off ? { x: 0 } : { y: 0 };
+    return {
+        initial: off,
+        animate: { ...home, transition: transitions.slow },
+        exit: { ...off, transition: { duration: duration.base, ease: ease.in } },
+    };
+};
+/** Inline-start / end slides for panels, drawers and pane swaps. `dir` flips them in RTL. */
+export const slide = (from, dir = 'ltr') => {
+    const sign = (from === 'end' ? 1 : -1) * (dir === 'rtl' ? -1 : 1);
+    return {
+        initial: { opacity: 0, x: sign * distance.slide },
+        animate: { opacity: 1, x: 0, transition: transitions.enter },
+        exit: { opacity: 0, x: sign * distance.slide, transition: transitions.exit },
+    };
+};
+/**
+ * Height changes of content that stays in place, driven by `AutoHeight`. Symmetric, because a card
+ * that grows and shrinks should not snap on either leg (`ease.out` front-loads nearly all of the
+ * movement into the first frames). `reveal` is for small things appearing in a card (an error, an
+ * input, a list expanding); `step` is for a whole question changing, so it matches `stepSwap`.
+ */
+export const resize = {
+    reveal: { duration: 0.25, ease: ease.standard },
+    step: { duration: 0.35, ease: ease.standard },
+};
+/**
+ * A diagram re-flowing around a change (a branch added or removed in the cycle builder): nodes,
+ * connectors, chips and the line joining them all travel on this one clock, so they arrive together
+ * and nothing is seen jumping. Slightly slower than a card moving alone, because the whole picture moves.
+ */
+export const reflow = { duration: 0.3, ease: ease.standard };
+/**
+ * A row gliding into a list that follows its end (a cycle divider): the rows above rise as it grows,
+ * so it is deliberately slower than `reflow`, and symmetric so the lift starts and lands softly.
+ */
+export const glide = { duration: 0.65, ease: ease.standard };
+/**
+ * The edit button of a connector sliding out from behind its "+" (cycle builder). `shift` is the
+ * button's width plus the 6px gap. The slide is quick and decelerates hard; the fade is `fast`.
+ * Reduced motion drops the transform and keeps the fade (`MotionProvider`).
+ */
+export const edgeReveal = {
+    shift: 42,
+    transition: {
+        x: { duration: 0.18, ease: [0.2, 0, 0, 1] },
+        opacity: { duration: duration.fast, ease: ease.standard },
+    },
+};
+/**
+ * One step of a multi-step flow replacing another, cross-fading (use with `AnimatePresence
+ * mode="popLayout" custom={dir}`). `dir` is 1 for forward and -1 for back: the old step leaves
+ * toward the side it came from and the new one arrives a beat later from the other, so the two
+ * overlap and nothing pops. Travel is `distance.slide`.
+ */
+export const stepSwap = {
+    initial: (dir) => ({ opacity: 0, x: dir * distance.slide }),
+    animate: {
+        opacity: 1,
+        x: 0,
+        transition: { duration: 0.3, delay: stagger.step + stagger.offset, ease: ease.standard },
+    },
+    exit: (dir) => ({
+        opacity: 0,
+        x: -dir * distance.slide,
+        transition: { duration: 0.2, ease: ease.standard },
+    }),
+};
+/**
+ * A clipped one-line label (sidebar stream and session titles) sliding the rest of itself into
+ * view while hovered, then holding at the end. `to(px)` runs at a steady reading pace, so a long
+ * title takes longer than a short one, after a rest that keeps a pointer sweeping past rows from
+ * setting them all moving. `back` snaps home at once when the pointer leaves: no rewind.
+ */
+export const scrollReveal = {
+    /** Seconds the pointer rests on the row before the title starts moving. */
+    delay: 0.3,
+    /** Pixels per second. */
+    speed: 48,
+    to: (px) => ({
+        duration: px / scrollReveal.speed,
+        delay: scrollReveal.delay,
+        ease: 'linear',
+    }),
+    back: { duration: 0 },
+};
+/** Delay for the `index`-th item of a staggered group, `step` apart and capped at `stagger.max`. */
+export const staggerDelay = (index, step = stagger.step) => Math.min(index * step, stagger.max);
+/**
+ * Infinite-loop transitions for loading indicators. These run forever at a steady cadence so the
+ * loading state is always perceptible. Under reduced motion anything that moves stops (the spinner
+ * stops turning) and the opacity pulses carry on, so loading still shows.
+ */
+export const loops = {
+    /** Spinner: one full clockwise turn per second, linear. Animate `transform`, not `rotate`, so
+     *  the browser runs it (motion drives `rotate` in JS, every frame). */
+    spin: { repeat: Infinity, repeatType: 'loop', ease: 'linear', duration: 1 },
+    /**
+     * Skeleton and status-dot: smooth opacity float, slow enough to read as "still loading". Give it
+     * keyframes that come back to where they start (`[1, 0.4, 1]`): it loops rather than mirrors, so
+     * the browser runs it off the main thread (motion drives a mirrored loop in JS, every frame).
+     */
+    pulse: { repeat: Infinity, repeatType: 'loop', ease: ease.standard, duration: 1.4 },
+    /** Text caret while an agent streams its reply: a soft on/off at a typing cadence. */
+    blink: { repeat: Infinity, repeatType: 'mirror', ease: ease.standard, duration: 0.53 },
+    /**
+     * AI shimmer text (shadcn AI Shimmer / AI Elements): animate `backgroundPosition` from
+     * `100% center` → `0% center` forever so a clipped gradient sweeps across the glyphs.
+     * Duration matches the AI Elements default (2s).
+     */
+    shimmer: { repeat: Infinity, repeatType: 'loop', ease: 'linear', duration: 2 },
+    /** Vibe skeleton wave: a highlight band crosses the placeholder, then rests before the next. */
+    sweep: {
+        repeat: Infinity,
+        repeatType: 'loop',
+        ease: ease.standard,
+        duration: 1.6,
+        repeatDelay: 0.4,
+    },
+};
+/**
+ * `RunningIndicator`: the 8px core scales 0.88 to 1 and the 2px halo fades out and in, on the same
+ * 2s loop as the iOS dot (`RunningIndicator.swift`), cosine-like so both ends rest. Nothing fades
+ * the core. The core animates a whole `transform` string, not `scale`, so motion hands the loop to
+ * the Web Animations API and it keeps running on the compositor while a phone webview scrolls or
+ * its main thread is busy. Reduced motion stops the whole loop (the dot renders static, no halo),
+ * unlike `loops.pulse`, which carries on.
+ */
+const runningIndicatorEase = [0.37, 0, 0.63, 1];
+export const runningIndicator = {
+    core: { transform: ['scale(1)', 'scale(0.88)', 'scale(1)'] },
+    halo: { opacity: [1, 0, 1] },
+    transition: { repeat: Infinity, repeatType: 'loop', ease: runningIndicatorEase, duration: 2 },
+};
+/**
+ * Stable `animate` / `transition` bags for infinite loops. Pass these by reference — never build
+ * a fresh `{ opacity: [1, 0.55, 1], … }` object (or a fresh keyframe array) inside render.
+ * Motion treats a new `animate` identity as a new animation and restarts the loop; chat Trace /
+ * ShimmerText re-render on every agent chunk, so inline targets look "stuck" until a full refresh.
+ * Mutable arrays (not `as const`) so they stay assignable to motion's keyframe types.
+ */
+const spinnerOpacityPulse = [1, 0.55, 1];
+export const loopAnimate = {
+    /** Spinner / Trace running icon: opacity pulse + WAAPI spin. */
+    spinner: {
+        opacity: spinnerOpacityPulse,
+        transform: ['rotate(0deg)', 'rotate(360deg)'],
+    },
+    /** Same pulse without the turn (reduced motion / `prefers-reduced-motion`). */
+    spinnerReduced: {
+        opacity: spinnerOpacityPulse,
+    },
+    /** ShimmerText / Trace running title: gradient sweep across glyphs. */
+    shimmer: {
+        backgroundPosition: ['100% center', '0% center'],
+    },
+};
+export const loopTransition = {
+    spinner: { transform: loops.spin, opacity: loops.pulse },
+    shimmer: loops.shimmer,
+};

package/dist/motion/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The only door to `motion` (motion.dev). Nothing else in the repo imports `motion/react`; apps
+ * get all of this through `@streamsai/ui`. Tune timing in `config.ts`, not at call sites.
+ */
+export { LayoutGroup, animate, motion, useMotionValue, useReducedMotion, useTransform, type HTMLMotionProps, type MotionValue, type Transition, type Variants, } from 'motion/react';
+export { duration, ease, spring, distance, scale, stagger, transitions, press, presets, loops, runningIndicator, loopAnimate, loopTransition, popup, sheet, slide, resize, reflow, glide, edgeReveal, stepSwap, scrollReveal, staggerDelay, } from './config.js';
+export { MotionProvider, disableMotion, enableMotion, enablePresenceExits, disablePresenceExits, AnimatePresence, PageTransition, Collapse, AutoHeight, usePrefersReducedMotion, Swap, swapVariants, StaggerItem, type PageTransitionProps, type CollapseProps, type AutoHeightProps, type SwapProps, type SwapPresetName, type StaggerItemProps, } from './components.js';
+export { useAnyModalOpen } from './modal-presence.js';

package/dist/motion/index.js

@@ -0,0 +1,8 @@
+/**
+ * The only door to `motion` (motion.dev). Nothing else in the repo imports `motion/react`; apps
+ * get all of this through `@streamsai/ui`. Tune timing in `config.ts`, not at call sites.
+ */
+export { LayoutGroup, animate, motion, useMotionValue, useReducedMotion, useTransform, } from 'motion/react';
+export { duration, ease, spring, distance, scale, stagger, transitions, press, presets, loops, runningIndicator, loopAnimate, loopTransition, popup, sheet, slide, resize, reflow, glide, edgeReveal, stepSwap, scrollReveal, staggerDelay, } from './config.js';
+export { MotionProvider, disableMotion, enableMotion, enablePresenceExits, disablePresenceExits, AnimatePresence, PageTransition, Collapse, AutoHeight, usePrefersReducedMotion, Swap, swapVariants, StaggerItem, } from './components.js';
+export { useAnyModalOpen } from './modal-presence.js';

package/dist/motion/modal-presence.d.ts

@@ -0,0 +1,5 @@
+/** Called while a modal popup (dialog, alert dialog, sheet) is mounted; returns its cleanup. */
+declare function registerModal(): () => void;
+/** True while any modal popup is mounted, including through its exit animation. */
+declare function useAnyModalOpen(): boolean;
+export { registerModal, useAnyModalOpen };

package/dist/motion/modal-presence.js

@@ -0,0 +1,27 @@
+import { useSyncExternalStore } from 'react';
+let openModals = 0;
+const listeners = new Set();
+function emit() {
+    for (const listener of listeners)
+        listener();
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/** Called while a modal popup (dialog, alert dialog, sheet) is mounted; returns its cleanup. */
+function registerModal() {
+    openModals += 1;
+    emit();
+    return () => {
+        openModals -= 1;
+        emit();
+    };
+}
+/** True while any modal popup is mounted, including through its exit animation. */
+function useAnyModalOpen() {
+    return useSyncExternalStore(subscribe, () => openModals > 0, () => false);
+}
+export { registerModal, useAnyModalOpen };

package/dist/motion/popup.d.ts

@@ -0,0 +1,77 @@
+import type { HTMLMotionProps, TargetAndTransition } from 'motion/react';
+import type { RefObject } from 'react';
+import { popup } from './config.js';
+/**
+ * Base UI popups (dialog, sheet, popover, menu, select, tooltip, hover card) animate with `motion`,
+ * not CSS. Base UI owns open state, focus and positioning; `motion` owns the animation. The
+ * handshake: the Root wrapper asks Base UI to keep a closing popup mounted
+ * (`usePopupExit`), the Popup renders through `MotionSurface`, and when its exit animation
+ * settles it calls back to unmount.
+ */
+interface MotionPreset {
+    initial: TargetAndTransition;
+    animate: TargetAndTransition;
+    exit: TargetAndTransition;
+}
+/** The nearest popup Root's unmount, for its Popup to call once the exit animation has played. */
+declare const PopupExitContext: import("react").Context<(() => void) | null>;
+interface Unmountable {
+    unmount: () => void;
+}
+/**
+ * For a Base UI Root wrapper: keeps the popup mounted when it closes and returns the `unmount`
+ * its `MotionSurface` calls after the exit. Pass the result's `actionsRef` and `onOpenChange` to
+ * the Root and provide `unmount` through `PopupExitContext`.
+ */
+declare function usePopupExit<Actions extends Unmountable, Details>(actionsRef: RefObject<Actions | null> | undefined, onOpenChange: ((open: boolean, details: Details) => void) | undefined): {
+    actionsRef: RefObject<Actions | null>;
+    onOpenChange: (open: boolean, details: Details) => void;
+    unmount: () => void | undefined;
+};
+declare function usePopupExitComplete(): (() => void) | null;
+interface MotionSurfaceProps extends Omit<HTMLMotionProps<'div'>, 'initial' | 'animate' | 'exit'> {
+    open: boolean;
+    preset: MotionPreset;
+    /** Show and hide without animating (a tooltip moving between adjacent triggers). */
+    instant?: boolean;
+    /** Called once when the closing animation settles. */
+    onExitComplete?: (() => void) | null;
+}
+/**
+ * The element a Base UI popup part renders as: `render={(props, state) => <MotionSurface
+ * {...props} open={state.open} … />}`. Animates to `preset.animate` while open and to
+ * `preset.exit` while closing, then reports the exit so Base UI can unmount.
+ */
+declare function MotionSurface({ open, preset, instant, onExitComplete, onAnimationComplete, ...props }: MotionSurfaceProps): import("react").JSX.Element;
+type PopupSide = Parameters<typeof popup>[0];
+/**
+ * `scale` is the default scale-and-fade; `drift` and `drift-tip` fade and drift only (a dropdown
+ * list, and a tip that arrives faster) and `fade` only fades, for a popup that belongs to a dense form.
+ */
+export type PopupVariant = 'scale' | 'drift' | 'drift-tip' | 'fade';
+interface PopupPartState {
+    open: boolean;
+    side?: PopupSide;
+    /** Tooltips only: set when Base UI wants the change shown without a transition. */
+    instant?: string | undefined;
+}
+/**
+ * `render` for a positioned popup (popover, menu, select, tooltip, hover card): scales and fades
+ * out of the trigger on whichever side Base UI placed it, and hands unmounting back on close.
+ */
+declare function usePopupRender(variant?: PopupVariant): (props: object, state: PopupPartState) => import("react").JSX.Element;
+/** `render` for a modal Popup (dialog, alert dialog, sheet) with the given preset. */
+declare function useModalRender(preset: MotionPreset): (props: object, state: PopupPartState) => import("react").JSX.Element;
+/** `render` for a Backdrop: fades with its popup, which owns the unmount. */
+declare function renderBackdrop(props: object, state: PopupPartState): import("react").JSX.Element;
+interface MotionCollapsePanelProps extends Omit<HTMLMotionProps<'div'>, 'initial' | 'animate'> {
+    open: boolean;
+}
+/**
+ * Collapsible content. Base UI's Panel is kept mounted so the close can animate; this element
+ * then renders nothing once the collapse settles, so closed content is not in the DOM. Content
+ * that starts open does not grow in on first render; every later open does.
+ */
+declare function MotionCollapsePanel({ open, hidden: _hidden, style, ...props }: MotionCollapsePanelProps): import("react").JSX.Element | null;
+export { MotionSurface, MotionCollapsePanel, PopupExitContext, usePopupExit, usePopupExitComplete, usePopupRender, useModalRender, renderBackdrop, };
+export type { MotionPreset, MotionSurfaceProps, MotionCollapsePanelProps };

package/dist/motion/popup.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { motion } from 'motion/react';
+import { createContext, use, useCallback, useEffect, useRef, useState } from 'react';
+import { useTextDirection } from '../direction/index.js';
+import { drift, duration, popup, presets } from './config.js';
+import { registerModal } from './modal-presence.js';
+/** How long a closing popup may take before it is unmounted regardless (a missed animation end). */
+const EXIT_FALLBACK_MS = Math.round((duration.slow + duration.base) * 1000);
+/** The nearest popup Root's unmount, for its Popup to call once the exit animation has played. */
+const PopupExitContext = createContext(null);
+/**
+ * For a Base UI Root wrapper: keeps the popup mounted when it closes and returns the `unmount`
+ * its `MotionSurface` calls after the exit. Pass the result's `actionsRef` and `onOpenChange` to
+ * the Root and provide `unmount` through `PopupExitContext`.
+ */
+function usePopupExit(actionsRef, onOpenChange) {
+    const ownRef = useRef(null);
+    const ref = actionsRef ?? ownRef;
+    const handleOpenChange = useCallback((open, details) => {
+        onOpenChange?.(open, details);
+        // Select has no such method: passing `actionsRef` alone already hands it unmounting.
+        if (!open)
+            details.preventUnmountOnClose?.();
+    }, [onOpenChange]);
+    const unmount = useCallback(() => ref.current?.unmount(), [ref]);
+    return { actionsRef: ref, onOpenChange: handleOpenChange, unmount };
+}
+function usePopupExitComplete() {
+    return use(PopupExitContext);
+}
+/**
+ * The element a Base UI popup part renders as: `render={(props, state) => <MotionSurface
+ * {...props} open={state.open} … />}`. Animates to `preset.animate` while open and to
+ * `preset.exit` while closing, then reports the exit so Base UI can unmount.
+ */
+function MotionSurface({ open, preset, instant = false, onExitComplete, onAnimationComplete, ...props }) {
+    const exited = useRef(false);
+    const completeExit = useCallback(() => {
+        if (exited.current || !onExitComplete)
+            return;
+        exited.current = true;
+        onExitComplete();
+    }, [onExitComplete]);
+    useEffect(() => {
+        if (open) {
+            exited.current = false;
+            return;
+        }
+        const timer = setTimeout(completeExit, EXIT_FALLBACK_MS);
+        return () => clearTimeout(timer);
+    }, [open, completeExit]);
+    const target = open ? preset.animate : preset.exit;
+    return (_jsx(motion.div, { initial: instant ? false : preset.initial, animate: instant ? { ...target, transition: { duration: 0 } } : target, onAnimationComplete: (definition) => {
+            onAnimationComplete?.(definition);
+            if (!open)
+                completeExit();
+        }, ...props }));
+}
+/**
+ * `render` for a positioned popup (popover, menu, select, tooltip, hover card): scales and fades
+ * out of the trigger on whichever side Base UI placed it, and hands unmounting back on close.
+ */
+function usePopupRender(variant = 'scale') {
+    const onExitComplete = usePopupExitComplete();
+    const dir = useTextDirection();
+    return useCallback((props, state) => (_jsx(MotionSurface, { ...props, open: state.open, preset: variant === 'scale'
+            ? popup(state.side, dir)
+            : drift(state.side, variant === 'drift-tip' ? 'tip' : variant === 'fade' ? 'fade' : 'list'), instant: Boolean(state.instant), onExitComplete: onExitComplete })), [onExitComplete, dir, variant]);
+}
+/** A modal popup's surface; it exists only while the popup is mounted, so it is the presence signal. */
+function ModalSurface(props) {
+    useEffect(registerModal, []);
+    return _jsx(MotionSurface, { ...props });
+}
+/** `render` for a modal Popup (dialog, alert dialog, sheet) with the given preset. */
+function useModalRender(preset) {
+    const onExitComplete = usePopupExitComplete();
+    return useCallback((props, state) => (_jsx(ModalSurface, { ...props, open: state.open, preset: preset, onExitComplete: onExitComplete })), [onExitComplete, preset]);
+}
+/** `render` for a Backdrop: fades with its popup, which owns the unmount. */
+function renderBackdrop(props, state) {
+    return (_jsx(MotionSurface, { ...props, open: state.open, preset: presets.fade }));
+}
+/**
+ * Collapsible content. Base UI's Panel is kept mounted so the close can animate; this element
+ * then renders nothing once the collapse settles, so closed content is not in the DOM. Content
+ * that starts open does not grow in on first render; every later open does.
+ */
+function MotionCollapsePanel({ open, hidden: _hidden, style, ...props }) {
+    const [closed, setClosed] = useState(!open);
+    const [growOnMount, setGrowOnMount] = useState(!open);
+    if (open && closed)
+        setClosed(false);
+    if (closed)
+        return null;
+    return (_jsx(motion.div, { initial: growOnMount ? presets.collapse.initial : false, animate: open ? presets.collapse.animate : presets.collapse.exit, onAnimationComplete: () => {
+            if (open)
+                return;
+            setClosed(true);
+            setGrowOnMount(true);
+        }, inert: !open, style: { overflow: 'hidden', ...style }, ...props }));
+}
+export { MotionSurface, MotionCollapsePanel, PopupExitContext, usePopupExit, usePopupExitComplete, usePopupRender, useModalRender, renderBackdrop, };