@passui/react 0.1.26 → 0.1.28

package/dist/types/src/components/segmented-control/segmented-control.d.ts

@@ -10,6 +10,8 @@ export interface SegmentedControlProps<T extends string> {
     onChange: (value: NoInfer<T>) => void;
     /** Accessible name for the group and its compact picker. */
     label: string;
+    /** Custom classes for the control container. */
+    className?: string;
 }
 /**
  * Mutually exclusive choices with a sliding selection, as on Apple
@@ -17,4 +19,4 @@ export interface SegmentedControlProps<T extends string> {
  * translation, a narrow pane) it becomes a pop-up button instead of
  * squeezing or spilling its text.
  */
-export declare function SegmentedControl<T extends string>({ value, options, onChange, label, }: SegmentedControlProps<T>): import("react").JSX.Element;
+export declare function SegmentedControl<T extends string>({ value, options, onChange, label, className, }: SegmentedControlProps<T>): import("react").JSX.Element;

package/dist/types/src/components/stat-tile/stat-tile.d.ts

@@ -10,6 +10,8 @@ export interface StatTileProps {
     /** Makes the tile a toggle, e.g. a filter. */
     onClick?: () => void;
     active?: boolean;
+    /** Custom classes for the tile container. */
+    className?: string;
 }
 /** One number with its label, optionally a toggle. */
-export declare function StatTile({ label, value, caption, tone, onClick, active }: StatTileProps): import("react").JSX.Element;
+export declare function StatTile({ label, value, caption, tone, onClick, active, className, }: StatTileProps): import("react").JSX.Element;

package/dist/types/src/components/swatch-picker/swatch-picker.d.ts

@@ -12,6 +12,8 @@ export interface SwatchPickerProps<T extends string> {
     onChange: (value: T) => void;
     /** Accessible name for the group. */
     label: string;
+    /** Custom classes for the swatch container. */
+    className?: string;
 }
 /** Colour swatches with a check on the chosen one. */
-export declare function SwatchPicker<T extends string>({ value, options, onChange, label, }: SwatchPickerProps<T>): import("react").JSX.Element;
+export declare function SwatchPicker<T extends string>({ value, options, onChange, label, className, }: SwatchPickerProps<T>): import("react").JSX.Element;

package/dist/types/src/components/text-field/text-field.d.ts

@@ -1,6 +1,9 @@
 import { type ComponentProps, type ReactNode } from "react";
+/** Shared text control classes for components that reuse TextField's surface. */
 export declare const textControlClasses: string;
-export type TextFieldProps = ComponentProps<"input"> & {
+/** Size scale shared across TextField, SecureField, and form fields. */
+export type TextFieldSize = "xs" | "sm" | "md" | "lg";
+export type TextFieldProps = Omit<ComponentProps<"input">, "size"> & {
     label: string;
     description?: ReactNode;
     errors?: string[];
@@ -16,5 +19,7 @@ export type TextFieldProps = ComponentProps<"input"> & {
     };
     /** Float the label into the outline on focus or when filled. @default "above" */
     labelPlacement?: "above" | "floating";
+    /** Field height and text scale. @default "md" */
+    size?: TextFieldSize;
 };
-export declare function TextField({ label, description, errors, icon, trailingIcon, action, revealLabels, labelPlacement, placeholder, type, id: suppliedId, className, ...props }: TextFieldProps): import("react").JSX.Element;
+export declare function TextField({ label, description, errors, icon, trailingIcon, action, revealLabels, labelPlacement, size, placeholder, type, id: suppliedId, className, ...props }: TextFieldProps): import("react").JSX.Element;

package/dist/types/src/components/toggle/toggle.d.ts

@@ -13,5 +13,7 @@ export interface ToggleProps {
     mixed?: boolean;
     /** Keeps the accessible name while hiding the visible label. @default false */
     labelHidden?: boolean;
+    /** Custom classes for the toggle container. */
+    className?: string;
 }
-export declare function Toggle({ checked, onChange, label, disabled, style, mixed, labelHidden, }: ToggleProps): import("react").JSX.Element;
+export declare function Toggle({ checked, onChange, label, disabled, style, mixed, labelHidden, className, }: ToggleProps): import("react").JSX.Element;

package/dist/types/src/motion/transitions.d.ts

@@ -19,12 +19,37 @@ export declare const spring: {
         readonly type: "spring";
     };
 };
+/**
+ * Apple's fluid overshoot: cubic-bezier(0.34, 1.56, 0.1, 1).
+ * Replaces traditional ease profiles with an authentic fluid bounce
+ * that overshoots and settles, matching Apple's custom interface physics.
+ * Used for zoom/matched-geometry transitions where the surface emerges
+ * from the trigger and snaps into place with a physical bounce.
+ */
+export declare const fluidOvershoot: {
+    readonly duration: 0.4;
+    readonly ease: [number, number, number, number];
+};
+/**
+ * Exit motion: content collapses back toward its source.
+ * The surface shrinks toward the trigger's position while fading,
+ * like a water drop absorbing back into its origin.
+ */
+export declare const fluidCollapse: {
+    readonly duration: 0.28;
+    readonly ease: [number, number, number, number];
+};
 export type FloatingPanelSide = "above" | "below";
-/** Anchored panels settle toward their source without shrinking their text. */
+/**
+ * Anchored panels settle toward their source without shrinking their text.
+ * Now uses origin-based scaling: the panel grows from the trigger's
+ * position (transform-origin set by the caller) with a scale + opacity
+ * crossfade, rather than a plain slide.
+ */
 export declare function floatingPanelMotion(side?: FloatingPanelSide): {
     readonly initial: {
         readonly opacity: 0;
-        readonly scale: 1;
+        readonly scale: 0.92;
         readonly y: number;
     };
     readonly animate: {
@@ -34,16 +59,15 @@ export declare function floatingPanelMotion(side?: FloatingPanelSide): {
     };
     readonly exit: {
         readonly opacity: 0;
-        readonly scale: 1;
+        readonly scale: 0.95;
         readonly y: number;
     };
     readonly transition: {
-        readonly damping: 26;
-        readonly stiffness: 240;
-        readonly mass: 1;
-        readonly type: "spring";
+        readonly duration: 0.4;
+        readonly ease: [number, number, number, number];
         readonly opacity: {
             readonly duration: 0.16;
+            readonly ease: [number, number, number, number];
         };
     };
 };
@@ -51,7 +75,7 @@ export declare function floatingPanelMotion(side?: FloatingPanelSide): {
 export declare const popoverMotion: {
     readonly initial: {
         readonly opacity: 0;
-        readonly scale: 1;
+        readonly scale: 0.92;
         readonly y: number;
     };
     readonly animate: {
@@ -61,19 +85,68 @@ export declare const popoverMotion: {
     };
     readonly exit: {
         readonly opacity: 0;
-        readonly scale: 1;
+        readonly scale: 0.95;
         readonly y: number;
     };
     readonly transition: {
-        readonly damping: 26;
-        readonly stiffness: 240;
-        readonly mass: 1;
-        readonly type: "spring";
+        readonly duration: 0.4;
+        readonly ease: [number, number, number, number];
         readonly opacity: {
             readonly duration: 0.16;
+            readonly ease: [number, number, number, number];
         };
     };
 };
+/**
+ * Zoom/matched-geometry transition for dialogs and center-placed sheets.
+ * The surface starts small (scale 0.88) and invisible, then grows to
+ * full size with the fluid overshoot bounce. Content elements inside
+ * crossfade in slightly delayed so they phase into visibility
+ * asynchronously — not a harsh switch.
+ */
+export declare const zoomReveal: {
+    readonly initial: {
+        readonly opacity: 0;
+        readonly scale: 0.88;
+    };
+    readonly animate: {
+        readonly opacity: 1;
+        readonly scale: 1;
+    };
+    readonly exit: {
+        readonly opacity: 0;
+        readonly scale: 0.92;
+    };
+    readonly transition: {
+        readonly duration: 0.4;
+        readonly ease: [number, number, number, number];
+    };
+};
+/**
+ * Content crossfade for elements inside an overlay.
+ * Rather than a harsh switch, sub-elements scale and phase into
+ * visibility asynchronously. Use for children of dialogs, sheets,
+ * and popovers — the container arrives first, then content fades in.
+ */
+export declare const contentCrossfade: {
+    readonly initial: {
+        readonly opacity: 0;
+        readonly scale: 0.96;
+    };
+    readonly animate: {
+        readonly opacity: 1;
+        readonly scale: 1;
+    };
+    readonly exit: {
+        readonly opacity: 0;
+        readonly scale: 0.98;
+    };
+    readonly transition: {
+        readonly duration: 0.24;
+        readonly ease: [number, number, number, number];
+        readonly delay: 0.04;
+    };
+};
 /** Floating bars that rise from the bottom edge. */
 export declare const riseMotion: {
     readonly initial: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@passui/react",
-    "version": "0.1.26",
+    "version": "0.1.28",
     "description": "Passui: native React controls, design tokens, presentation and appearance.",
     "license": "MIT",
     "repository": {

package/src/components/dialog/dialog.tsx

@@ -2,7 +2,7 @@ import { Sheet } from "../sheet/sheet"
 import { AnimatePresence, motion, useReducedMotion } from "motion/react"
 import { Button } from "../button/button"
 import { cn } from "../../lib/class-names"
-import { spring } from "../../motion/transitions"
+import { contentCrossfade, spring, zoomReveal } from "../../motion/transitions"
 import { createContext, useContext, useId, type FormEvent, type ReactNode } from "react"
 
 const CloseContext = createContext<() => void>(() => {})
@@ -81,19 +81,31 @@ export function Dialog({
                         initial={{
                             height: reducedMotion ? "auto" : 0,
                             opacity: 0,
+                            scale: reducedMotion ? 1 : 0.97,
                         }}
                         animate={{
                             height: "auto",
                             opacity: 1,
+                            scale: 1,
                         }}
                         exit={{
                             height: reducedMotion ? "auto" : 0,
                             opacity: 0,
+                            scale: reducedMotion ? 1 : 0.98,
                         }}
-                        transition={reducedMotion ? { duration: 0 } : spring.smooth}
+                        transition={reducedMotion ? { duration: 0 } : spring.bouncy}
                         className="overflow-hidden"
+                        style={{ transformOrigin: "top center" }}
                     >
-                        {body}
+                        <motion.div
+                            initial={reducedMotion ? false : contentCrossfade.initial}
+                            animate={reducedMotion ? undefined : contentCrossfade.animate}
+                            transition={
+                                reducedMotion ? { duration: 0 } : contentCrossfade.transition
+                            }
+                        >
+                            {body}
+                        </motion.div>
                     </motion.div>
                 )}
             </AnimatePresence>

package/src/components/popover/popover.tsx

@@ -10,7 +10,12 @@ import { concealMenuSource } from "../context-menu/conceal-menu-source"
 import { menuSurfaceExit, menuSurfaceReveal } from "../context-menu/menu-reveal"
 import { cn } from "../../lib/class-names"
 import { screenEdges } from "../../lib/screen-edges"
-import { floatingPanelMotion, spring } from "../../motion/transitions"
+import {
+    contentCrossfade,
+    floatingPanelMotion,
+    fluidOvershoot,
+    spring,
+} from "../../motion/transitions"
 import { fitPopover, type PopoverFit } from "./popover-fit"
 
 export type PopoverOrigin = "top-left" | "top-right"
@@ -56,6 +61,11 @@ function OpenPopover({
     const [reveal, setReveal] = useState<ReturnType<typeof menuSurfaceReveal> | null>(null)
     const popoverMotion = floatingPanelMotion(fit.above ? "above" : "below")
 
+    // For anchored popovers, the surface morphs from the trigger via
+    // menuSurfaceReveal. For non-anchored popovers, we use scale + the
+    // fluid overshoot spring so the panel grows from the origin corner
+    // with a physical bounce — Apple's matched-geometry feel.
+
     useLayoutEffect(() => {
         const refit = () => {
             const element = ref.current
@@ -283,11 +293,17 @@ function OpenPopover({
                     transition={
                         reducedMotion
                             ? { duration: 0 }
-                            : { ...spring.smooth, opacity: { duration: 0.16 } }
+                            : { ...fluidOvershoot, opacity: { duration: 0.16 } }
                     }
                 />
             )}
-            {children}
+            <motion.div
+                initial={reducedMotion ? false : anchorRef ? { opacity: 0 } : undefined}
+                animate={reducedMotion ? undefined : anchorRef ? { opacity: 1 } : undefined}
+                transition={reducedMotion ? { duration: 0 } : { duration: 0.16, delay: 0.06 }}
+            >
+                {children}
+            </motion.div>
         </motion.div>
     )
 }

package/src/components/segmented-control/segmented-control.tsx

@@ -14,6 +14,8 @@ export interface SegmentedControlProps<T extends string> {
     onChange: (value: NoInfer<T>) => void
     /** Accessible name for the group and its compact picker. */
     label: string
+    /** Custom classes for the control container. */
+    className?: string
 }
 
 /**
@@ -27,6 +29,7 @@ export function SegmentedControl<T extends string>({
     options,
     onChange,
     label,
+    className,
 }: SegmentedControlProps<T>) {
     const id = useId()
     const reducedMotion = useReducedMotion()
@@ -47,7 +50,7 @@ export function SegmentedControl<T extends string>({
     }, [])
 
     return (
-        <div ref={frame} className="relative w-full min-w-0">
+        <div ref={frame} className={cn("relative w-full min-w-0", className)}>
             {/* The control at its natural size, to know whether it fits. */}
             <div
                 ref={measure}

package/src/components/sheet/sheet.tsx

@@ -2,7 +2,7 @@ import { AnimatePresence, motion, useReducedMotion } from "motion/react"
 import { type ReactNode, useRef } from "react"
 import { useVisualViewport } from "../../hooks/use-visual-viewport"
 import { cn } from "../../lib/class-names"
-import { spring } from "../../motion/transitions"
+import { contentCrossfade, spring, zoomReveal } from "../../motion/transitions"
 import { SheetPortal } from "./sheet-portal"
 import { useSheetFocus } from "./use-sheet-focus"
 
@@ -95,12 +95,47 @@ function OpenSheet({
                     placement === "center" ? "rounded-sheet" : "rounded-t-sheet sm:rounded-sheet",
                     className
                 )}
-                initial={reducedMotion ? { opacity: 0 } : { y: 40, opacity: 0 }}
-                animate={{ y: 0, opacity: 1 }}
-                exit={reducedMotion ? { opacity: 0 } : { y: 30, opacity: 0 }}
-                transition={reducedMotion ? { duration: 0 } : spring.smooth}
+                style={{
+                    transformOrigin: placement === "center" ? "center center" : "bottom center",
+                }}
+                initial={
+                    reducedMotion
+                        ? { opacity: 0 }
+                        : placement === "center"
+                          ? zoomReveal.initial
+                          : { y: 40, opacity: 0, scale: 0.96 }
+                }
+                animate={
+                    reducedMotion
+                        ? { opacity: 1 }
+                        : placement === "center"
+                          ? zoomReveal.animate
+                          : { y: 0, opacity: 1, scale: 1 }
+                }
+                exit={
+                    reducedMotion
+                        ? { opacity: 0 }
+                        : placement === "center"
+                          ? zoomReveal.exit
+                          : { y: 30, opacity: 0, scale: 0.98 }
+                }
+                transition={
+                    reducedMotion
+                        ? { duration: 0 }
+                        : placement === "center"
+                          ? zoomReveal.transition
+                          : { ...spring.bouncy, opacity: { duration: 0.18 } }
+                }
             >
-                {children}
+                <motion.div
+                    className="flex min-h-0 flex-1 flex-col overflow-y-auto"
+                    initial={reducedMotion ? false : contentCrossfade.initial}
+                    animate={reducedMotion ? undefined : contentCrossfade.animate}
+                    exit={reducedMotion ? undefined : contentCrossfade.exit}
+                    transition={reducedMotion ? { duration: 0 } : contentCrossfade.transition}
+                >
+                    {children}
+                </motion.div>
             </motion.div>
         </div>
     )

package/src/components/stat-tile/stat-tile.tsx

@@ -13,10 +13,20 @@ export interface StatTileProps {
     /** Makes the tile a toggle, e.g. a filter. */
     onClick?: () => void
     active?: boolean
+    /** Custom classes for the tile container. */
+    className?: string
 }
 
 /** One number with its label, optionally a toggle. */
-export function StatTile({ label, value, caption, tone, onClick, active = false }: StatTileProps) {
+export function StatTile({
+    label,
+    value,
+    caption,
+    tone,
+    onClick,
+    active = false,
+    className,
+}: StatTileProps) {
     const body = (
         <>
             <span className="text-label-secondary">{label}</span>
@@ -26,17 +36,19 @@ export function StatTile({ label, value, caption, tone, onClick, active = false
             {caption && <span className="text-label-secondary">{caption}</span>}
         </>
     )
-    const className =
-        "flex min-w-0 flex-col gap-2 rounded-2xl border border-separator/35 bg-elevated p-4 text-left shadow-xs"
+    const tileClass = cn(
+        "flex min-w-0 flex-col gap-2 rounded-2xl border border-separator/35 bg-elevated p-4 text-left shadow-xs",
+        className
+    )
 
-    if (!onClick) return <div className={className}>{body}</div>
+    if (!onClick) return <div className={tileClass}>{body}</div>
     return (
         <button
             type="button"
             aria-pressed={active}
             onClick={onClick}
             className={cn(
-                className,
+                tileClass,
                 "ring-1 ring-transparent transition-colors hover:bg-fill/60",
                 active && "bg-fill/70 ring-label/15"
             )}

package/src/components/swatch-picker/swatch-picker.tsx

@@ -20,6 +20,8 @@ export interface SwatchPickerProps<T extends string> {
     onChange: (value: T) => void
     /** Accessible name for the group. */
     label: string
+    /** Custom classes for the swatch container. */
+    className?: string
 }
 
 /** Colour swatches with a check on the chosen one. */
@@ -28,10 +30,11 @@ export function SwatchPicker<T extends string>({
     options,
     onChange,
     label,
+    className,
 }: SwatchPickerProps<T>) {
     const name = useId()
     return (
-        <fieldset className="flex flex-wrap gap-3">
+        <fieldset className={cn("flex flex-wrap gap-3", className)}>
             <legend className="sr-only">{label}</legend>
             {options.map((option) => {
                 const selected = option.value === value

package/src/components/text-field/text-field.tsx

@@ -2,6 +2,7 @@ import { type ComponentProps, type ReactNode, useId, useState } from "react"
 import { Button } from "../button/button"
 import { cn } from "../../lib/class-names"
 
+/** Shared text control classes for components that reuse TextField's surface. */
 export const textControlClasses = cn(
     "w-full min-w-0 rounded-xl border border-separator bg-elevated",
     "px-3 py-2 text-body text-label placeholder:text-label-tertiary",
@@ -11,7 +12,55 @@ export const textControlClasses = cn(
 
 const fieldIconClasses = "flex shrink-0 items-center text-label-secondary"
 
-export type TextFieldProps = ComponentProps<"input"> & {
+/** Size scale shared across TextField, SecureField, and form fields. */
+export type TextFieldSize = "xs" | "sm" | "md" | "lg"
+
+interface FieldSize {
+    height: string
+    floatingHeight: string
+    padding: string
+    text: string
+    radius: string
+}
+
+function fieldSize(size: TextFieldSize): FieldSize {
+    switch (size) {
+        case "xs":
+            return {
+                height: "h-8",
+                floatingHeight: "h-9",
+                padding: "px-2.5",
+                text: "text-caption",
+                radius: "rounded-lg",
+            }
+        case "sm":
+            return {
+                height: "h-9",
+                floatingHeight: "h-10",
+                padding: "px-3",
+                text: "text-subheadline",
+                radius: "rounded-xl",
+            }
+        case "lg":
+            return {
+                height: "h-12",
+                floatingHeight: "h-14",
+                padding: "px-4",
+                text: "text-body",
+                radius: "rounded-xl",
+            }
+        default:
+            return {
+                height: "h-11",
+                floatingHeight: "h-12",
+                padding: "px-3",
+                text: "text-body",
+                radius: "rounded-xl",
+            }
+    }
+}
+
+export type TextFieldProps = Omit<ComponentProps<"input">, "size"> & {
     label: string
     description?: ReactNode
     errors?: string[]
@@ -24,6 +73,8 @@ export type TextFieldProps = ComponentProps<"input"> & {
     revealLabels?: { show: string; hide: string }
     /** Float the label into the outline on focus or when filled. @default "above" */
     labelPlacement?: "above" | "floating"
+    /** Field height and text scale. @default "md" */
+    size?: TextFieldSize
 }
 
 export function TextField({
@@ -35,6 +86,7 @@ export function TextField({
     action,
     revealLabels,
     labelPlacement = "above",
+    size = "md",
     placeholder,
     type = "text",
     id: suppliedId,
@@ -46,6 +98,7 @@ export function TextField({
     const [revealed, setRevealed] = useState(false)
     const messages = Array.from(new Set(errors))
     const reveal = type === "password" && revealLabels
+    const dims = fieldSize(size)
     return (
         <div className="not-typeset flex flex-col gap-2">
             {labelPlacement === "above" && (
@@ -55,7 +108,7 @@ export function TextField({
             )}
             <div
                 className={cn(
-                    "relative flex items-center gap-2 rounded-xl bg-elevated px-3",
+                    `relative flex items-center gap-2 ${dims.padding} ${dims.radius} bg-elevated`,
                     labelPlacement === "floating"
                         ? "passui-floating-field"
                         : "border border-separator focus-within:ring-1 focus-within:ring-accent/40 has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-accent-text/70"
@@ -99,8 +152,9 @@ export function TextField({
                             .join(" ") || undefined
                     }
                     className={cn(
-                        "h-11 w-full min-w-0 bg-transparent text-body text-label outline-none",
-                        labelPlacement === "floating" && "h-12",
+                        labelPlacement === "floating" ? dims.floatingHeight : dims.height,
+                        "w-full min-w-0 bg-transparent text-label outline-none",
+                        dims.text,
                         "placeholder:text-label-tertiary disabled:opacity-40",
                         className
                     )}

package/src/components/toggle/toggle.tsx

@@ -28,6 +28,8 @@ export interface ToggleProps {
     mixed?: boolean
     /** Keeps the accessible name while hiding the visible label. @default false */
     labelHidden?: boolean
+    /** Custom classes for the toggle container. */
+    className?: string
 }
 
 export function Toggle({
@@ -38,6 +40,7 @@ export function Toggle({
     style = "switch",
     mixed = false,
     labelHidden = false,
+    className,
 }: ToggleProps) {
     const input = useRef<HTMLInputElement>(null)
     useEffect(() => {
@@ -48,7 +51,8 @@ export function Toggle({
             <label
                 className={cn(
                     "flex cursor-pointer items-center gap-3 text-subheadline",
-                    disabled && "cursor-not-allowed opacity-40"
+                    disabled && "cursor-not-allowed opacity-40",
+                    className
                 )}
             >
                 <span className="relative inline-flex size-5 shrink-0">
@@ -82,7 +86,15 @@ export function Toggle({
             </label>
         )
     }
-    return <SwitchToggle checked={checked} onChange={onChange} label={label} disabled={disabled} />
+    return (
+        <SwitchToggle
+            checked={checked}
+            onChange={onChange}
+            label={label}
+            disabled={disabled}
+            className={className}
+        />
+    )
 }
 
 function SwitchToggle({
@@ -90,7 +102,8 @@ function SwitchToggle({
     onChange,
     label,
     disabled,
-}: Pick<ToggleProps, "checked" | "onChange" | "label" | "disabled">) {
+    className,
+}: Pick<ToggleProps, "checked" | "onChange" | "label" | "disabled" | "className">) {
     const reducedMotion = useReducedMotion()
     const id = `toggle-goo-${useId().replace(/:/g, "")}`
     const x = useMotionValue(checked ? 22 : 2)
@@ -163,7 +176,8 @@ function SwitchToggle({
             className={cn(
                 "relative h-[30px] w-[50px] shrink-0 touch-pan-y rounded-full transition-colors duration-normal motion-reduce:transition-none",
                 "shadow-[inset_0_1px_2px_rgb(0_0_0/0.10)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/70 focus-visible:ring-offset-1 focus-visible:ring-offset-background disabled:opacity-45",
-                checked ? "bg-accent" : "bg-separator/80"
+                checked ? "bg-accent" : "bg-separator/80",
+                className
             )}
         >
             <svg aria-hidden="true" width="0" height="0" className="absolute">

package/src/motion/transitions.ts

@@ -8,18 +8,45 @@ export const spring = {
     bouncy: { type: "spring", ...springs.bouncy },
 } as const satisfies Record<keyof typeof springs, Transition>
 
+/**
+ * Apple's fluid overshoot: cubic-bezier(0.34, 1.56, 0.1, 1).
+ * Replaces traditional ease profiles with an authentic fluid bounce
+ * that overshoots and settles, matching Apple's custom interface physics.
+ * Used for zoom/matched-geometry transitions where the surface emerges
+ * from the trigger and snaps into place with a physical bounce.
+ */
+export const fluidOvershoot = {
+    duration: 0.4,
+    ease: [0.34, 1.56, 0.1, 1] as [number, number, number, number],
+} as const
+
+/**
+ * Exit motion: content collapses back toward its source.
+ * The surface shrinks toward the trigger's position while fading,
+ * like a water drop absorbing back into its origin.
+ */
+export const fluidCollapse = {
+    duration: 0.28,
+    ease: [0.4, 0, 0.6, 1] as [number, number, number, number],
+} as const
+
 export type FloatingPanelSide = "above" | "below"
 
-/** Anchored panels settle toward their source without shrinking their text. */
+/**
+ * Anchored panels settle toward their source without shrinking their text.
+ * Now uses origin-based scaling: the panel grows from the trigger's
+ * position (transform-origin set by the caller) with a scale + opacity
+ * crossfade, rather than a plain slide.
+ */
 export function floatingPanelMotion(side: FloatingPanelSide = "below") {
     const direction = side === "above" ? 1 : -1
     return {
-        initial: { opacity: 0, scale: 1, y: direction * 6 },
+        initial: { opacity: 0, scale: 0.92, y: direction * 6 },
         animate: { opacity: 1, scale: 1, y: 0 },
-        exit: { opacity: 0, scale: 1, y: direction * 4 },
+        exit: { opacity: 0, scale: 0.95, y: direction * 4 },
         transition: {
-            ...spring.smooth,
-            opacity: { duration: 0.16 },
+            ...fluidOvershoot,
+            opacity: { duration: 0.16, ease: [0.4, 0, 0.2, 1] as [number, number, number, number] },
         },
     } as const
 }
@@ -27,6 +54,37 @@ export function floatingPanelMotion(side: FloatingPanelSide = "below") {
 /** Default below-anchor presentation, retained for existing consumers. */
 export const popoverMotion = floatingPanelMotion()
 
+/**
+ * Zoom/matched-geometry transition for dialogs and center-placed sheets.
+ * The surface starts small (scale 0.88) and invisible, then grows to
+ * full size with the fluid overshoot bounce. Content elements inside
+ * crossfade in slightly delayed so they phase into visibility
+ * asynchronously — not a harsh switch.
+ */
+export const zoomReveal = {
+    initial: { opacity: 0, scale: 0.88 },
+    animate: { opacity: 1, scale: 1 },
+    exit: { opacity: 0, scale: 0.92 },
+    transition: fluidOvershoot,
+} as const
+
+/**
+ * Content crossfade for elements inside an overlay.
+ * Rather than a harsh switch, sub-elements scale and phase into
+ * visibility asynchronously. Use for children of dialogs, sheets,
+ * and popovers — the container arrives first, then content fades in.
+ */
+export const contentCrossfade = {
+    initial: { opacity: 0, scale: 0.96 },
+    animate: { opacity: 1, scale: 1 },
+    exit: { opacity: 0, scale: 0.98 },
+    transition: {
+        duration: 0.24,
+        ease: [0.4, 0, 0.2, 1] as [number, number, number, number],
+        delay: 0.04,
+    },
+} as const
+
 /** Floating bars that rise from the bottom edge. */
 export const riseMotion = {
     initial: { opacity: 0, y: 32 },