beez-ui 0.5.6 → 0.6.1

package/dist/motion/surface-keyframes.d.ts

@@ -0,0 +1,13 @@
+/** Resolves entry and exit playback for floating and modal surfaces from their rendered placement. */
+import type { AnimationOptions, DOMKeyframesDefinition } from "motion/react";
+/** Surface kinds whose presence is animated on mount and before removal. */
+export type SurfaceKind = "tooltip" | "surface" | "dialog" | "sheet" | "overlay";
+/** Keyframes plus the transition that plays them. */
+export interface MotionStep {
+    keyframes: DOMKeyframesDefinition;
+    transition: AnimationOptions;
+}
+/** Entrance playback matching the beui surface family for each kind. */
+export declare function surfaceEnter(element: Element, kind: SurfaceKind): MotionStep;
+/** Exit playback: brief and eased so dismissal never blocks the next interaction. */
+export declare function surfaceExit(element: Element, kind: SurfaceKind): MotionStep;

package/dist/motion/surface-keyframes.js

@@ -0,0 +1,205 @@
+import { MOTION_DIALOG_DISTANCE, MOTION_EASE, MOTION_SURFACE_CLIP_PERCENT, MOTION_SURFACE_SCALE, MOTION_TIMING, MOTION_TOOLTIP_DISTANCE, SPRING_PANEL, SPRING_TOOLTIP } from "./tokens.js";
+const EASE_OUT = [...MOTION_EASE];
+const SIDES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+const ALIGNS = [
+	"start",
+	"center",
+	"end"
+];
+/** Reads Radix placement attributes, tolerating primitives that do not position with a popper. */
+function readPlacement(element) {
+	const side = element.getAttribute("data-side");
+	const align = element.getAttribute("data-align");
+	return {
+		side: SIDES.includes(side) ? side : undefined,
+		align: ALIGNS.includes(align) ? align : "center"
+	};
+}
+/** Builds a transform with explicit identity parts, so Motion never reads a missing scale as zero. */
+function transform(x, y, scale = 1) {
+	const unit = (value) => typeof value === "number" ? `${value}px` : value;
+	return `translate(${unit(x)}, ${unit(y)}) scale(${scale})`;
+}
+/** Offset pointing away from the trigger, so content appears to emerge from it. */
+function offsetAwayFromTrigger(side, distance) {
+	if (side === "top") return {
+		x: 0,
+		y: distance
+	};
+	if (side === "left") return {
+		x: distance,
+		y: 0
+	};
+	if (side === "right") return {
+		x: -distance,
+		y: 0
+	};
+	if (side === "bottom") return {
+		x: 0,
+		y: -distance
+	};
+	return {
+		x: 0,
+		y: 0
+	};
+}
+/** Collapsed clip anchored at the corner or edge closest to the trigger. */
+function collapsedClip(side, align) {
+	const hidden = `${MOTION_SURFACE_CLIP_PERCENT}%`;
+	const half = `${MOTION_SURFACE_CLIP_PERCENT / 2}%`;
+	/** Maps an alignment to the inset kept on the leading and trailing edges of the cross axis. */
+	const crossAxis = (value) => value === "start" ? ["0%", hidden] : value === "end" ? [hidden, "0%"] : [half, half];
+	if (side === "bottom" || side === "top") {
+		const [left, right] = crossAxis(align);
+		return side === "bottom" ? `inset(0% ${right} ${hidden} ${left})` : `inset(${hidden} ${right} 0% ${left})`;
+	}
+	const [top, bottom] = crossAxis(align);
+	return side === "right" ? `inset(${top} ${hidden} ${bottom} 0%)` : `inset(${top} 0% ${bottom} ${hidden})`;
+}
+/** Edge-panel travel: fully off-screen on the side the sheet is attached to. */
+function sheetOffset(element) {
+	const side = readPlacement(element).side ?? "right";
+	if (side === "left") return {
+		x: "-100%",
+		y: "0%"
+	};
+	if (side === "top") return {
+		x: "0%",
+		y: "-100%"
+	};
+	if (side === "bottom") return {
+		x: "0%",
+		y: "100%"
+	};
+	return {
+		x: "100%",
+		y: "0%"
+	};
+}
+/** Entrance playback matching the beui surface family for each kind. */
+export function surfaceEnter(element, kind) {
+	const { side, align } = readPlacement(element);
+	if (kind === "overlay") {
+		return {
+			keyframes: { opacity: [0, 1] },
+			transition: {
+				duration: MOTION_TIMING.overlay,
+				ease: EASE_OUT
+			}
+		};
+	}
+	if (kind === "tooltip") {
+		const offset = offsetAwayFromTrigger(side, MOTION_TOOLTIP_DISTANCE);
+		return {
+			keyframes: {
+				opacity: [0, 1],
+				transform: [transform(offset.x, offset.y, .9), transform(0, 0)],
+				filter: ["blur(5px)", "blur(0px)"]
+			},
+			transition: {
+				...SPRING_TOOLTIP,
+				opacity: {
+					duration: MOTION_TIMING.fast,
+					ease: EASE_OUT
+				},
+				filter: {
+					duration: MOTION_TIMING.enter,
+					ease: EASE_OUT
+				}
+			}
+		};
+	}
+	if (kind === "dialog") {
+		return {
+			keyframes: {
+				opacity: [0, 1],
+				transform: [transform(0, MOTION_DIALOG_DISTANCE, .97), transform(0, 0)]
+			},
+			transition: SPRING_PANEL
+		};
+	}
+	if (kind === "sheet") {
+		const offset = sheetOffset(element);
+		return {
+			keyframes: { transform: [transform(offset.x, offset.y), transform("0%", "0%")] },
+			transition: SPRING_PANEL
+		};
+	}
+	const keyframes = {
+		opacity: [0, 1],
+		transform: [transform(0, 0, MOTION_SURFACE_SCALE), transform(0, 0)]
+	};
+	// Primitives aligned over their trigger (Select item-aligned) have no side to reveal from.
+	if (side) {
+		keyframes.clipPath = [collapsedClip(side, align), "inset(0% 0% 0% 0%)"];
+	}
+	return {
+		keyframes,
+		transition: {
+			...SPRING_PANEL,
+			opacity: {
+				duration: MOTION_TIMING.enter,
+				ease: EASE_OUT
+			},
+			clipPath: {
+				duration: MOTION_TIMING.surfaceClip,
+				ease: EASE_OUT
+			}
+		}
+	};
+}
+/** Exit playback: brief and eased so dismissal never blocks the next interaction. */
+export function surfaceExit(element, kind) {
+	const exitTween = {
+		duration: MOTION_TIMING.exit,
+		ease: EASE_OUT
+	};
+	if (kind === "overlay") {
+		return {
+			keyframes: { opacity: [1, 0] },
+			transition: exitTween
+		};
+	}
+	if (kind === "tooltip") {
+		const offset = offsetAwayFromTrigger(readPlacement(element).side, MOTION_TOOLTIP_DISTANCE * .6);
+		return {
+			keyframes: {
+				opacity: [1, 0],
+				transform: [transform(0, 0), transform(offset.x, offset.y, .94)],
+				filter: ["blur(0px)", "blur(3px)"]
+			},
+			transition: exitTween
+		};
+	}
+	if (kind === "dialog") {
+		return {
+			keyframes: {
+				opacity: [1, 0],
+				transform: [transform(0, 0), transform(0, MOTION_DIALOG_DISTANCE, .98)]
+			},
+			transition: {
+				duration: MOTION_TIMING.enter,
+				ease: EASE_OUT
+			}
+		};
+	}
+	if (kind === "sheet") {
+		const offset = sheetOffset(element);
+		return {
+			keyframes: { transform: [transform("0%", "0%"), transform(offset.x, offset.y)] },
+			transition: SPRING_PANEL
+		};
+	}
+	return {
+		keyframes: {
+			opacity: [1, 0],
+			transform: [transform(0, 0), transform(0, 0, MOTION_SURFACE_SCALE)]
+		},
+		transition: exitTween
+	};
+}

package/dist/motion/tokens.d.ts

@@ -1,13 +1,96 @@
-/** Defines the restrained timing and movement shared by Motion animations. */
+/** Defines the timing, curves and physics shared by Motion animations, aligned with beui.dev/components/motion. */
 export declare const MOTION_TIMING: {
     readonly fast: 0.14;
     readonly enter: 0.18;
+    readonly message: 0.2;
     readonly panel: 0.22;
+    readonly overlay: 0.2;
     readonly exit: 0.12;
+    readonly surfaceClip: 0.32;
+    readonly shake: 0.45;
+    readonly checkDraw: 0.3;
+    readonly checkDrawDelay: 0.04;
+    readonly iconSwap: 0.2;
+    readonly listItem: 0.18;
+    readonly listDelay: 0.05;
+    readonly listStagger: 0.035;
+    readonly closeEnter: 0.2;
+    readonly closeDelay: 0.16;
     readonly skeleton: 1.8;
 };
-export declare const MOTION_EASE: readonly [0.22, 1, 0.36, 1];
-export declare const MOTION_PRESS_SCALE = 0.98;
-export declare const MOTION_SURFACE_DISTANCE = 4;
-export declare const MOTION_PANEL_DISTANCE = 12;
-export type MotionKind = "press" | "fade" | "card" | "row" | "field" | "thumb" | "selection" | "skeleton" | "link" | "icon" | "surface" | "dialog" | "sheet" | "overlay";
+/** Items beyond this position share the last stagger delay, so long lists never lag behind. */
+export declare const MOTION_LIST_STAGGER_LIMIT = 10;
+/** Strong ease-out used for entrances; weak defaults such as `ease-out` feel sluggish. */
+export declare const MOTION_EASE: readonly [0.16, 1, 0.3, 1];
+/** Symmetric curve for looping or reversible effects. */
+export declare const MOTION_EASE_IN_OUT: readonly [0.77, 0, 0.175, 1];
+/** Drawer curve for edge panels leaving the viewport. */
+export declare const MOTION_EASE_DRAWER: readonly [0.32, 0.72, 0, 1];
+/** Press feedback on buttons and other tappable surfaces. */
+export declare const SPRING_PRESS: {
+    readonly type: "spring";
+    readonly stiffness: 500;
+    readonly damping: 30;
+    readonly mass: 0.6;
+};
+/** Overlay panel entrances — dialogs, sheets and floating surfaces. */
+export declare const SPRING_PANEL: {
+    readonly type: "spring";
+    readonly stiffness: 420;
+    readonly damping: 40;
+    readonly mass: 0.5;
+};
+/** Shared-layout glides — indicators and highlights moving between items. */
+export declare const SPRING_LAYOUT: {
+    readonly type: "spring";
+    readonly stiffness: 360;
+    readonly damping: 32;
+    readonly mass: 0.6;
+};
+/** Tab indicator glide, tuned to settle without overshooting the list edges. */
+export declare const SPRING_TABS: {
+    readonly type: "spring";
+    readonly stiffness: 245;
+    readonly damping: 36;
+    readonly mass: 1.2;
+};
+/** Lighter spawn for small tooltip surfaces. */
+export declare const SPRING_TOOLTIP: {
+    readonly type: "spring";
+    readonly stiffness: 380;
+    readonly damping: 30;
+    readonly mass: 0.7;
+};
+/** Disclosure chevrons rotate with a little bounce, as if flicked. */
+export declare const SPRING_CHEVRON: {
+    readonly type: "spring";
+    readonly duration: 0.4;
+    readonly bounce: 0.3;
+};
+/** Heavy, deliberate switch thumb — high mass keeps the travel weighty without wobble. */
+export declare const SPRING_THUMB: {
+    readonly type: "spring";
+    readonly stiffness: 800;
+    readonly damping: 80;
+    readonly mass: 4;
+};
+/** Primary actions compress noticeably; dense navigation items stay subtle. */
+export declare const MOTION_PRESS_SCALE = 0.93;
+export declare const MOTION_SUBTLE_PRESS_SCALE = 0.98;
+export declare const MOTION_TOGGLE_PRESS_SCALE = 0.92;
+export declare const MOTION_HOVER_SCALE = 1.02;
+export declare const MOTION_THUMB_SQUISH_SCALE = 0.9;
+export declare const MOTION_ITEM_CHECK_SCALE = 0.75;
+export declare const MOTION_ICON_SWAP_SCALE = 0.25;
+export declare const MOTION_CLOSE_BUTTON_SCALE = 0.8;
+export declare const MOTION_LIST_ITEM_DISTANCE = 6;
+export declare const MOTION_SURFACE_SCALE = 0.96;
+/** Fraction of the surface kept hidden by the clip at the start of its reveal, in percent. */
+export declare const MOTION_SURFACE_CLIP_PERCENT = 92;
+export declare const MOTION_TOOLTIP_DISTANCE = 8;
+export declare const MOTION_DIALOG_DISTANCE = 20;
+export declare const MOTION_CONTENT_DISTANCE = 4;
+export declare const MOTION_INVALID_SHAKE_PX: readonly [0, -6, 6, -4, 4, -2, 0];
+/** Time after an item loses its active state during which a new active item still glides from it. */
+export declare const GLIDE_CONTINUITY_MS = 300;
+export type MotionKind = "press" | "subtle-press" | "toggle" | "fade" | "content" | "message" | "card" | "row" | "field" | "thumb" | "check" | "selection" | "item-check" | "rotate" | "list-item" | "icon-swap" | "delayed-pop" | "skeleton" | "link" | "icon" | "tooltip" | "surface" | "dialog" | "sheet" | "overlay";

package/dist/motion/tokens.js

@@ -1,17 +1,118 @@
-/** Defines the restrained timing and movement shared by Motion animations. */
+/** Defines the timing, curves and physics shared by Motion animations, aligned with beui.dev/components/motion. */
 export const MOTION_TIMING = {
 	fast: .14,
 	enter: .18,
+	message: .2,
 	panel: .22,
+	overlay: .2,
 	exit: .12,
+	surfaceClip: .32,
+	shake: .45,
+	checkDraw: .3,
+	checkDrawDelay: .04,
+	iconSwap: .2,
+	listItem: .18,
+	listDelay: .05,
+	listStagger: .035,
+	closeEnter: .2,
+	closeDelay: .16,
 	skeleton: 1.8
 };
+/** Items beyond this position share the last stagger delay, so long lists never lag behind. */
+export const MOTION_LIST_STAGGER_LIMIT = 10;
+/** Strong ease-out used for entrances; weak defaults such as `ease-out` feel sluggish. */
 export const MOTION_EASE = [
-	.22,
+	.16,
 	1,
-	.36,
+	.3,
 	1
 ];
-export const MOTION_PRESS_SCALE = .98;
-export const MOTION_SURFACE_DISTANCE = 4;
-export const MOTION_PANEL_DISTANCE = 12;
+/** Symmetric curve for looping or reversible effects. */
+export const MOTION_EASE_IN_OUT = [
+	.77,
+	0,
+	.175,
+	1
+];
+/** Drawer curve for edge panels leaving the viewport. */
+export const MOTION_EASE_DRAWER = [
+	.32,
+	.72,
+	0,
+	1
+];
+/** Press feedback on buttons and other tappable surfaces. */
+export const SPRING_PRESS = {
+	type: "spring",
+	stiffness: 500,
+	damping: 30,
+	mass: .6
+};
+/** Overlay panel entrances — dialogs, sheets and floating surfaces. */
+export const SPRING_PANEL = {
+	type: "spring",
+	stiffness: 420,
+	damping: 40,
+	mass: .5
+};
+/** Shared-layout glides — indicators and highlights moving between items. */
+export const SPRING_LAYOUT = {
+	type: "spring",
+	stiffness: 360,
+	damping: 32,
+	mass: .6
+};
+/** Tab indicator glide, tuned to settle without overshooting the list edges. */
+export const SPRING_TABS = {
+	type: "spring",
+	stiffness: 245,
+	damping: 36,
+	mass: 1.2
+};
+/** Lighter spawn for small tooltip surfaces. */
+export const SPRING_TOOLTIP = {
+	type: "spring",
+	stiffness: 380,
+	damping: 30,
+	mass: .7
+};
+/** Disclosure chevrons rotate with a little bounce, as if flicked. */
+export const SPRING_CHEVRON = {
+	type: "spring",
+	duration: .4,
+	bounce: .3
+};
+/** Heavy, deliberate switch thumb — high mass keeps the travel weighty without wobble. */
+export const SPRING_THUMB = {
+	type: "spring",
+	stiffness: 800,
+	damping: 80,
+	mass: 4
+};
+/** Primary actions compress noticeably; dense navigation items stay subtle. */
+export const MOTION_PRESS_SCALE = .93;
+export const MOTION_SUBTLE_PRESS_SCALE = .98;
+export const MOTION_TOGGLE_PRESS_SCALE = .92;
+export const MOTION_HOVER_SCALE = 1.02;
+export const MOTION_THUMB_SQUISH_SCALE = .9;
+export const MOTION_ITEM_CHECK_SCALE = .75;
+export const MOTION_ICON_SWAP_SCALE = .25;
+export const MOTION_CLOSE_BUTTON_SCALE = .8;
+export const MOTION_LIST_ITEM_DISTANCE = 6;
+export const MOTION_SURFACE_SCALE = .96;
+/** Fraction of the surface kept hidden by the clip at the start of its reveal, in percent. */
+export const MOTION_SURFACE_CLIP_PERCENT = 92;
+export const MOTION_TOOLTIP_DISTANCE = 8;
+export const MOTION_DIALOG_DISTANCE = 20;
+export const MOTION_CONTENT_DISTANCE = 4;
+export const MOTION_INVALID_SHAKE_PX = [
+	0,
+	-6,
+	6,
+	-4,
+	4,
+	-2,
+	0
+];
+/** Time after an item loses its active state during which a new active item still glides from it. */
+export const GLIDE_CONTINUITY_MS = 300;

package/dist/motion/use-attached-element.d.ts

@@ -0,0 +1,7 @@
+/** Tracks the DOM node rendered through a Slot while forwarding it to the caller's ref. */
+import { type Ref } from "react";
+/**
+ * Returns the attached element and a callback ref that also feeds the caller's ref,
+ * honoring React 19 ref cleanups.
+ */
+export declare function useAttachedElement<T extends HTMLElement>(ref: Ref<T> | undefined): readonly [T | null, (node: T | null) => () => void];

package/dist/motion/use-attached-element.js

@@ -0,0 +1,22 @@
+"use client";
+/** Tracks the DOM node rendered through a Slot while forwarding it to the caller's ref. */
+import { useCallback, useState } from "react";
+/**
+* Returns the attached element and a callback ref that also feeds the caller's ref,
+* honoring React 19 ref cleanups.
+*/
+export function useAttachedElement(ref) {
+	const [element, setElement] = useState(null);
+	const attach = useCallback((node) => {
+		setElement(node);
+		const cleanup = typeof ref === "function" ? ref(node) : undefined;
+		if (ref && typeof ref !== "function") ref.current = node;
+		return () => {
+			setElement(null);
+			if (typeof cleanup === "function") cleanup();
+			else if (typeof ref === "function") ref(null);
+			else if (ref) ref.current = null;
+		};
+	}, [ref]);
+	return [element, attach];
+}