motion-ui-skill 2.0.0

package/components/motion/overflow-actions.tsx

@@ -0,0 +1,375 @@
+"use client";
+
+import { MoreHorizontal, X } from "lucide-react";
+import {
+  AnimatePresence,
+  motion,
+  useReducedMotion,
+  type Transition,
+  type Variants,
+} from "motion/react";
+import {
+  useCallback,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { EASE_OUT } from "@/lib/ease";
+import { useHoverCapable } from "@/lib/hooks/use-hover-capable";
+import { cn } from "@/lib/utils";
+
+export type OverflowActionsSize = "sm" | "md";
+
+export type OverflowActionItem = {
+  id: string;
+  label: ReactNode;
+  icon?: ReactNode;
+  onClick?: () => void;
+  disabled?: boolean;
+  ariaLabel?: string;
+};
+
+export type OverflowActionsClassNames = {
+  root?: string;
+  track?: string;
+  action?: string;
+  primaryAction?: string;
+  overflowAction?: string;
+  toggle?: string;
+  icon?: string;
+  label?: string;
+};
+
+export interface OverflowActionsProps {
+  primaryActions: OverflowActionItem[];
+  overflowActions: OverflowActionItem[];
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  onAction?: (item: OverflowActionItem) => void;
+  collapseOnAction?: boolean;
+  size?: OverflowActionsSize;
+  openLabel?: string;
+  closeLabel?: string;
+  className?: string;
+  classNames?: OverflowActionsClassNames;
+}
+
+// This needs a softer layout spring than the app defaults so the overflow group
+// stays visually attached to the toggle while entering and leaving.
+const SHELL_TRANSITION: Transition = {
+  type: "spring",
+  stiffness: 220,
+  damping: 17,
+  mass: 0.85,
+};
+
+const ICON_VARIANTS: Variants = {
+  hidden: { opacity: 0, filter: "blur(3px)" },
+  visible: {
+    opacity: 1,
+    filter: "blur(0px)",
+    transition: { duration: 0.18, ease: EASE_OUT },
+  },
+  exit: {
+    opacity: 0,
+    filter: "blur(3px)",
+    transition: { duration: 0.18, ease: EASE_OUT },
+  },
+};
+
+const OVERFLOW_ACTION_VARIANTS: Variants = {
+  hidden: { opacity: 0, filter: "blur(4px)" },
+  visible: { opacity: 1, filter: "blur(0px)" },
+  exit: { opacity: 0, filter: "blur(4px)" },
+};
+
+const TRACK_SIZE_CLASS: Record<OverflowActionsSize, string> = {
+  sm: "gap-1 p-1 text-xs",
+  md: "gap-1.5 p-1.5 text-sm",
+};
+
+const GROUP_GAP_CLASS: Record<OverflowActionsSize, string> = {
+  sm: "gap-1",
+  md: "gap-1.5",
+};
+
+const ACTION_SIZE_CLASS: Record<OverflowActionsSize, string> = {
+  sm: "h-8 min-w-8 gap-1.5 px-3",
+  md: "h-9 min-w-9 gap-2 px-3.5",
+};
+
+const TOGGLE_SIZE_CLASS: Record<OverflowActionsSize, string> = {
+  sm: "h-8 w-8",
+  md: "h-9 w-9",
+};
+
+const ICON_SIZE_CLASS: Record<OverflowActionsSize, string> = {
+  sm: "h-3.5 w-3.5",
+  md: "h-4 w-4",
+};
+
+function useControllableExpanded({
+  expanded,
+  defaultExpanded,
+  onExpandedChange,
+}: {
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+}) {
+  const [internalExpanded, setInternalExpanded] = useState(
+    defaultExpanded ?? false,
+  );
+  const isControlled = expanded !== undefined;
+  const value = expanded ?? internalExpanded;
+
+  const setValue = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setInternalExpanded(next);
+      onExpandedChange?.(next);
+    },
+    [isControlled, onExpandedChange],
+  );
+
+  return [value, setValue] as const;
+}
+
+export function OverflowActions({
+  primaryActions,
+  overflowActions,
+  expanded,
+  defaultExpanded = false,
+  onExpandedChange,
+  onAction,
+  collapseOnAction = false,
+  size = "md",
+  openLabel = "Show extra actions",
+  closeLabel = "Hide extra actions",
+  className,
+  classNames,
+}: OverflowActionsProps) {
+  const reduce = useReducedMotion();
+  const canHover = useHoverCapable();
+  const overflowId = useId();
+  const overflowWrapperRef = useRef<HTMLDivElement>(null);
+  const overflowWrapperLeftRef = useRef(0);
+  const [isExpanded, setIsExpanded] = useControllableExpanded({
+    expanded,
+    defaultExpanded,
+    onExpandedChange,
+  });
+
+  const transition = reduce ? { duration: 0 } : SHELL_TRANSITION;
+
+  useLayoutEffect(() => {
+    const overflowNode = overflowWrapperRef.current;
+    if (!overflowNode) return;
+
+    if (!isExpanded) {
+      overflowNode.style.left = `${
+        overflowWrapperLeftRef.current -
+        overflowNode.getBoundingClientRect().left
+      }px`;
+      return;
+    }
+
+    overflowNode.style.left = "";
+    overflowWrapperLeftRef.current = overflowNode.getBoundingClientRect().left;
+  }, [isExpanded]);
+
+  const handleAction = (item: OverflowActionItem) => {
+    item.onClick?.();
+    onAction?.(item);
+    if (collapseOnAction) setIsExpanded(false);
+  };
+
+  return (
+    <motion.div
+      layout
+      transition={transition}
+      className={cn("inline-flex", classNames?.root, className)}
+    >
+      <motion.div
+        layout
+        transition={transition}
+        className={cn(
+          "relative inline-flex items-center overflow-hidden rounded-full border border-border bg-card",
+          TRACK_SIZE_CLASS[size],
+          classNames?.track,
+        )}
+      >
+        <motion.div
+          layout
+          transition={transition}
+          className={cn("inline-flex items-center", GROUP_GAP_CLASS[size])}
+        >
+          {primaryActions.map((item) => (
+            <ActionButton
+              key={item.id}
+              item={item}
+              size={size}
+              reduce={reduce}
+              canHover={canHover}
+              onAction={handleAction}
+              layoutTransition={transition}
+              className={cn(classNames?.action, classNames?.primaryAction)}
+              iconClassName={classNames?.icon}
+              labelClassName={classNames?.label}
+            />
+          ))}
+        </motion.div>
+
+        <AnimatePresence mode="popLayout" initial={false}>
+          {isExpanded ? (
+            <motion.div
+              key="overflow-actions"
+              ref={overflowWrapperRef}
+              id={overflowId}
+              layout
+              aria-hidden={!isExpanded}
+              transition={transition}
+              className={cn(
+                "relative inline-flex w-max items-center",
+                GROUP_GAP_CLASS[size],
+              )}
+            >
+              {overflowActions.map((item) => (
+                <ActionButton
+                  key={item.id}
+                  item={item}
+                  size={size}
+                  reduce={reduce}
+                  canHover={canHover}
+                  overflow
+                  visible={isExpanded}
+                  variants={OVERFLOW_ACTION_VARIANTS}
+                  onAction={handleAction}
+                  layoutTransition={transition}
+                  className={cn(classNames?.action, classNames?.overflowAction)}
+                  iconClassName={classNames?.icon}
+                  labelClassName={classNames?.label}
+                />
+              ))}
+            </motion.div>
+          ) : null}
+        </AnimatePresence>
+
+        <motion.button
+          type="button"
+          layout
+          aria-expanded={isExpanded}
+          aria-controls={isExpanded ? overflowId : undefined}
+          aria-label={isExpanded ? closeLabel : openLabel}
+          title={isExpanded ? closeLabel : openLabel}
+          onClick={() => setIsExpanded(!isExpanded)}
+          whileTap={reduce ? undefined : { scale: 0.96 }}
+          whileHover={reduce || !canHover ? undefined : { scale: 1.03 }}
+          transition={transition}
+          className={cn(
+            "relative inline-grid shrink-0 place-items-center rounded-full bg-primary text-primary-foreground outline-none disabled:pointer-events-none disabled:opacity-50",
+            "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+            TOGGLE_SIZE_CLASS[size],
+            classNames?.toggle,
+          )}
+        >
+          <AnimatePresence mode="popLayout" initial={false}>
+            <motion.span
+              key={isExpanded ? "close" : "open"}
+              variants={ICON_VARIANTS}
+              initial={reduce ? { opacity: 0 } : "hidden"}
+              animate={reduce ? { opacity: 1 } : "visible"}
+              exit={reduce ? { opacity: 0 } : "exit"}
+              className="inline-grid place-items-center"
+            >
+              {isExpanded ? (
+                <X className={ICON_SIZE_CLASS[size]} />
+              ) : (
+                <MoreHorizontal className={ICON_SIZE_CLASS[size]} />
+              )}
+            </motion.span>
+          </AnimatePresence>
+        </motion.button>
+      </motion.div>
+    </motion.div>
+  );
+}
+
+function ActionButton({
+  item,
+  size,
+  reduce,
+  canHover,
+  overflow,
+  visible = true,
+  variants,
+  onAction,
+  layoutTransition,
+  className,
+  iconClassName,
+  labelClassName,
+}: {
+  item: OverflowActionItem;
+  size: OverflowActionsSize;
+  reduce: boolean | null;
+  canHover: boolean;
+  overflow?: boolean;
+  visible?: boolean;
+  variants?: Variants;
+  onAction: (item: OverflowActionItem) => void;
+  layoutTransition: Transition;
+  className?: string;
+  iconClassName?: string;
+  labelClassName?: string;
+}) {
+  const label = typeof item.label === "string" ? item.label : undefined;
+
+  return (
+    <motion.span
+      layout="position"
+      variants={variants}
+      initial={variants ? (reduce ? { opacity: 0 } : "hidden") : undefined}
+      animate={variants ? (reduce ? { opacity: 1 } : "visible") : undefined}
+      exit={variants ? (reduce ? { opacity: 0 } : "exit") : undefined}
+      whileTap={reduce || item.disabled ? undefined : { scale: 0.97 }}
+      whileHover={
+        reduce || !canHover || item.disabled ? undefined : { scale: 1.008 }
+      }
+      transition={layoutTransition}
+      className="inline-flex shrink-0"
+    >
+      <button
+        type="button"
+        disabled={item.disabled}
+        aria-label={item.ariaLabel}
+        tabIndex={overflow && !visible ? -1 : undefined}
+        title={label}
+        onClick={() => onAction(item)}
+        className={cn(
+          "inline-flex shrink-0 items-center justify-center rounded-full bg-background font-medium text-foreground outline-none",
+          "disabled:pointer-events-none disabled:opacity-45",
+          "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+          ACTION_SIZE_CLASS[size],
+          className,
+        )}
+      >
+        {item.icon ? (
+          <span
+            className={cn(
+              "inline-flex shrink-0 items-center justify-center",
+              ICON_SIZE_CLASS[size],
+              iconClassName,
+            )}
+          >
+            {item.icon}
+          </span>
+        ) : null}
+        <span className={cn("whitespace-nowrap", labelClassName)}>
+          {item.label}
+        </span>
+      </button>
+    </motion.span>
+  );
+}

package/components/motion/page-transition.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import {
+  AnimatePresence,
+  motion,
+  useReducedMotion,
+  type HTMLMotionProps,
+} from "motion/react";
+import React from "react";
+import { EASE_EMPHASIZED, EASE_OUT, SPRING_PANEL } from "@/lib/ease";
+import { cn } from "@/lib/utils";
+
+export type TransitionMode = "fade" | "slide" | "scale" | "push" | "flip";
+
+export interface PageTransitionProps extends HTMLMotionProps<"div"> {
+  transitionKey: string | number;
+  mode?: TransitionMode;
+  direction?: 1 | -1; // 1 for forward, -1 for back
+  children: React.ReactNode;
+  className?: string;
+}
+
+const VARIANTS = {
+  fade: {
+    initial: { opacity: 0, scale: 0.98 },
+    animate: { opacity: 1, scale: 1, transition: { duration: 0.24, ease: EASE_OUT } },
+    exit: { opacity: 0, scale: 0.99, transition: { duration: 0.16, ease: EASE_EMPHASIZED } },
+  },
+  slide: (dir: number) => ({
+    initial: { opacity: 0, x: dir * 30 },
+    animate: { opacity: 1, x: 0, transition: SPRING_PANEL },
+    exit: { opacity: 0, x: dir * -30, transition: { duration: 0.18, ease: EASE_EMPHASIZED } },
+  }),
+  scale: {
+    initial: { opacity: 0, scale: 0.92, filter: "blur(4px)" },
+    animate: { opacity: 1, scale: 1, filter: "blur(0px)", transition: SPRING_PANEL },
+    exit: { opacity: 0, scale: 1.04, filter: "blur(4px)", transition: { duration: 0.18 } },
+  },
+  push: (dir: number) => ({
+    initial: { x: dir * 100 + "%" },
+    animate: { x: "0%", transition: SPRING_PANEL },
+    exit: { x: dir * -30 + "%", opacity: 0.7, transition: { duration: 0.22 } },
+  }),
+  flip: {
+    initial: { opacity: 0, rotateX: -15, transformPerspective: 1000 },
+    animate: { opacity: 1, rotateX: 0, transition: SPRING_PANEL },
+    exit: { opacity: 0, rotateX: 15, transition: { duration: 0.18 } },
+  },
+};
+
+export function PageTransition({
+  transitionKey,
+  mode = "fade",
+  direction = 1,
+  children,
+  className,
+  ...props
+}: PageTransitionProps) {
+  const shouldReduceMotion = useReducedMotion();
+
+  const getVariant = () => {
+    if (shouldReduceMotion) {
+      return {
+        initial: { opacity: 0 },
+        animate: { opacity: 1, transition: { duration: 0.15 } },
+        exit: { opacity: 0, transition: { duration: 0.1 } },
+      };
+    }
+
+    if (mode === "slide" || mode === "push") {
+      return VARIANTS[mode](direction);
+    }
+    return VARIANTS[mode];
+  };
+
+  const variant = getVariant();
+
+  return (
+    <AnimatePresence mode="wait" initial={false}>
+      <motion.div
+        key={transitionKey}
+        initial={variant.initial}
+        animate={variant.animate}
+        exit={variant.exit}
+        className={cn("w-full min-h-full", className)}
+        {...props}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  );
+}

package/components/motion/pagination.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+import { ChevronLeft, ChevronRight, MoreHorizontal } from "lucide-react";
+import {
+  motion,
+  useReducedMotion,
+  type HTMLMotionProps,
+} from "motion/react";
+import React, { useId } from "react";
+import { SPRING_LAYOUT, SPRING_PRESS } from "@/lib/ease";
+import { useHaptic } from "@/lib/hooks/use-haptic";
+import { cn } from "@/lib/utils";
+
+export interface PaginationProps extends Omit<HTMLMotionProps<"nav">, "onChange"> {
+  currentPage: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+  siblingCount?: number;
+  className?: string;
+}
+
+export function Pagination({
+  currentPage,
+  totalPages,
+  onPageChange,
+  siblingCount = 1,
+  className,
+  ...props
+}: PaginationProps) {
+  const layoutId = useId();
+  const shouldReduceMotion = useReducedMotion();
+  const triggerHaptic = useHaptic();
+
+  const handlePageSelect = (page: number) => {
+    if (page >= 1 && page <= totalPages && page !== currentPage) {
+      onPageChange(page);
+      triggerHaptic("selection");
+    }
+  };
+
+  // Generate page numbers range
+  const generatePages = () => {
+    const totalNumbers = siblingCount * 2 + 3;
+    const totalBlocks = totalNumbers + 2;
+
+    if (totalPages <= totalBlocks) {
+      return Array.from({ length: totalPages }, (_, i) => i + 1);
+    }
+
+    const leftSiblingIndex = Math.max(currentPage - siblingCount, 1);
+    const rightSiblingIndex = Math.min(currentPage + siblingCount, totalPages);
+
+    const shouldShowLeftDots = leftSiblingIndex > 2;
+    const shouldShowRightDots = rightSiblingIndex < totalPages - 2;
+
+    const firstPageIndex = 1;
+    const lastPageIndex = totalPages;
+
+    if (!shouldShowLeftDots && shouldShowRightDots) {
+      const leftItemCount = 3 + 2 * siblingCount;
+      const leftRange = Array.from({ length: leftItemCount }, (_, i) => i + 1);
+      return [...leftRange, "dots-right", totalPages];
+    }
+
+    if (shouldShowLeftDots && !shouldShowRightDots) {
+      const rightItemCount = 3 + 2 * siblingCount;
+      const rightRange = Array.from(
+        { length: rightItemCount },
+        (_, i) => totalPages - rightItemCount + i + 1
+      );
+      return [firstPageIndex, "dots-left", ...rightRange];
+    }
+
+    if (shouldShowLeftDots && shouldShowRightDots) {
+      const middleRange = Array.from(
+        { length: rightSiblingIndex - leftSiblingIndex + 1 },
+        (_, i) => leftSiblingIndex + i
+      );
+      return [firstPageIndex, "dots-left", ...middleRange, "dots-right", lastPageIndex];
+    }
+
+    return [];
+  };
+
+  const pages = generatePages();
+
+  return (
+    <motion.nav
+      role="navigation"
+      aria-label="Pagination"
+      className={cn("flex items-center justify-center gap-1", className)}
+      {...props}
+    >
+      {/* Previous Button */}
+      <motion.button
+        type="button"
+        disabled={currentPage <= 1}
+        onClick={() => handlePageSelect(currentPage - 1)}
+        whileTap={shouldReduceMotion || currentPage <= 1 ? undefined : { scale: 0.92 }}
+        transition={SPRING_PRESS}
+        aria-label="Previous page"
+        className="flex size-8 items-center justify-center rounded-lg border border-border bg-background text-muted-foreground hover:bg-muted hover:text-foreground disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+      >
+        <ChevronLeft className="size-4" />
+      </motion.button>
+
+      {/* Page Items */}
+      {pages.map((p, idx) => {
+        if (typeof p === "string") {
+          return (
+            <span
+              key={`${p}-${idx}`}
+              aria-hidden="true"
+              className="flex size-8 items-center justify-center text-muted-foreground"
+            >
+              <MoreHorizontal className="size-3.5" />
+            </span>
+          );
+        }
+
+        const isCurrent = p === currentPage;
+
+        return (
+          <motion.button
+            key={p}
+            type="button"
+            aria-current={isCurrent ? "page" : undefined}
+            onClick={() => handlePageSelect(p)}
+            whileTap={shouldReduceMotion ? undefined : { scale: 0.92 }}
+            transition={SPRING_PRESS}
+            className={cn(
+              "relative flex size-8 items-center justify-center rounded-lg text-xs font-medium tabular-nums transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring select-none",
+              isCurrent ? "text-primary-foreground font-semibold" : "text-muted-foreground hover:bg-muted hover:text-foreground"
+            )}
+          >
+            {/* Active Sliding Indicator */}
+            {isCurrent && (
+              <motion.div
+                layoutId={`pagination-active-${layoutId}`}
+                transition={shouldReduceMotion ? { duration: 0 } : SPRING_LAYOUT}
+                className="absolute inset-0 z-[-1] rounded-lg bg-primary shadow-sm shadow-primary/20"
+              />
+            )}
+            <span>{p}</span>
+          </motion.button>
+        );
+      })}
+
+      {/* Next Button */}
+      <motion.button
+        type="button"
+        disabled={currentPage >= totalPages}
+        onClick={() => handlePageSelect(currentPage + 1)}
+        whileTap={shouldReduceMotion || currentPage >= totalPages ? undefined : { scale: 0.92 }}
+        transition={SPRING_PRESS}
+        aria-label="Next page"
+        className="flex size-8 items-center justify-center rounded-lg border border-border bg-background text-muted-foreground hover:bg-muted hover:text-foreground disabled:opacity-30 disabled:cursor-not-allowed transition-colors"
+      >
+        <ChevronRight className="size-4" />
+      </motion.button>
+    </motion.nav>
+  );
+}

package/components/motion/parallax.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import {
+  motion,
+  type MotionStyle,
+  useReducedMotion,
+  useScroll,
+  useSpring,
+  useTransform,
+} from "motion/react";
+import { type ReactNode, type RefObject, useRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+// Soft follow so the drift trails the scroll smoothly; looser than the UI
+// springs in lib/ease.ts on purpose.
+const PARALLAX_SPRING = { stiffness: 120, damping: 30, mass: 0.6 };
+
+export interface ParallaxProps {
+  children: ReactNode;
+  /**
+   * Drift as a fraction of the element's travel through the viewport.
+   * Positive moves with the scroll (foreground), negative against it
+   * (background). ~0.1–0.5 reads best.
+   */
+  speed?: number;
+  axis?: "x" | "y";
+  /** Scroll container for contained scroll areas. Defaults to the viewport. */
+  container?: RefObject<HTMLElement | null>;
+  /** Spring-smooth the drift. Disabled automatically under reduced motion. */
+  spring?: boolean;
+  className?: string;
+}
+
+export function Parallax({
+  children,
+  speed = 0.3,
+  axis = "y",
+  container,
+  spring = true,
+  className,
+}: ParallaxProps) {
+  const reduce = useReducedMotion();
+  const ref = useRef<HTMLDivElement>(null);
+  const { scrollYProgress } = useScroll({
+    target: ref,
+    container,
+    offset: ["start end", "end start"],
+  });
+
+  // progress 0→1 as the element crosses the viewport; map to a symmetric drift.
+  const travel = speed * 100;
+  const drift = useTransform(scrollYProgress, [0, 1], [travel, -travel]);
+  const smoothed = useSpring(drift, PARALLAX_SPRING);
+  const value = spring && !reduce ? smoothed : drift;
+
+  const style: MotionStyle = reduce ? {} : axis === "x" ? { x: value } : { y: value };
+
+  return (
+    <motion.div ref={ref} style={style} className={cn(className)}>
+      {children}
+    </motion.div>
+  );
+}