motion-ui-skill 2.0.0

package/components/motion/cascader.tsx

@@ -0,0 +1,279 @@
+"use client";
+
+import {
+  Check,
+  ChevronLeft,
+  ChevronRight,
+  Folder,
+  Layers,
+  Search,
+  X,
+} from "lucide-react";
+import {
+  AnimatePresence,
+  motion,
+  useReducedMotion,
+  type HTMLMotionProps,
+} from "motion/react";
+import React, { useEffect, useState, useMemo } from "react";
+import { EASE_OUT, SPRING_LAYOUT, SPRING_PRESS } from "@/lib/ease";
+import { cn } from "@/lib/utils";
+
+export interface CascaderOption {
+  value: string;
+  label: string;
+  children?: CascaderOption[];
+  disabled?: boolean;
+}
+
+export interface CascaderProps extends Omit<HTMLMotionProps<"div">, "onChange"> {
+  options: CascaderOption[];
+  value?: string[];
+  onChange?: (path: string[], selectedOption: CascaderOption) => void;
+  placeholder?: string;
+  searchable?: boolean;
+  className?: string;
+}
+
+export function Cascader({
+  options,
+  value: controlledValue,
+  onChange,
+  placeholder = "Select category...",
+  searchable = true,
+  className,
+  ...props
+}: CascaderProps) {
+  const [selectedPath, setSelectedPath] = useState<string[]>(controlledValue ?? []);
+  const [activeTierPath, setActiveTierPath] = useState<CascaderOption[]>([]);
+  const [searchQuery, setSearchQuery] = useState("");
+  const shouldReduceMotion = useReducedMotion();
+
+  useEffect(() => {
+    if (
+      controlledValue !== undefined &&
+      (controlledValue.length !== selectedPath.length ||
+        controlledValue.some((value, index) => value !== selectedPath[index]))
+    ) {
+      setSelectedPath(controlledValue);
+    }
+  }, [controlledValue, selectedPath]);
+
+  // Find options for current view level
+  const currentLevelOptions = useMemo(() => {
+    if (activeTierPath.length === 0) return options;
+    const parent = activeTierPath[activeTierPath.length - 1];
+    return parent.children || [];
+  }, [options, activeTierPath]);
+
+  // Flattened options for global search
+  const flatSearchMatches = useMemo(() => {
+    if (!searchQuery.trim()) return [];
+    const q = searchQuery.toLowerCase();
+    const results: Array<{ path: string[]; option: CascaderOption; fullLabel: string }> = [];
+
+    const traverse = (opts: CascaderOption[], currentTrail: string[], labelTrail: string[]) => {
+      for (const opt of opts) {
+        const nextTrail = [...currentTrail, opt.value];
+        const nextLabels = [...labelTrail, opt.label];
+        if (!opt.disabled && !opt.children?.length && opt.label.toLowerCase().includes(q)) {
+          results.push({
+            path: nextTrail,
+            option: opt,
+            fullLabel: nextLabels.join(" → "),
+          });
+        }
+        if (opt.children) {
+          traverse(opt.children, nextTrail, nextLabels);
+        }
+      }
+    };
+
+    traverse(options, [], []);
+    return results;
+  }, [options, searchQuery]);
+
+  const handleSelect = (option: CascaderOption) => {
+    if (option.disabled) return;
+
+    if (option.children && option.children.length > 0) {
+      // Step into children tier
+      setActiveTierPath([...activeTierPath, option]);
+    } else {
+      // Leaf selected
+      const finalPath = [...activeTierPath.map((o) => o.value), option.value];
+      setSelectedPath(finalPath);
+      onChange?.(finalPath, option);
+      setSearchQuery("");
+    }
+  };
+
+  const handleBack = () => {
+    if (activeTierPath.length > 0) {
+      setActiveTierPath(activeTierPath.slice(0, -1));
+    }
+  };
+
+  return (
+    <motion.div
+      className={cn(
+        "flex w-80 flex-col rounded-2xl border border-border bg-card shadow-sm overflow-hidden",
+        className
+      )}
+      {...props}
+    >
+      {/* Search & Breadcrumb Bar */}
+      <div className="border-b border-border/70 p-2.5 bg-muted/30">
+        {searchable && (
+          <div className="relative mb-2">
+            <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 size-3.5 text-muted-foreground" />
+            <input
+              type="text"
+              value={searchQuery}
+              onChange={(e) => setSearchQuery(e.target.value)}
+              placeholder="Search hierarchy..."
+              className="w-full rounded-lg border border-border bg-background pl-8 pr-7 py-1.5 text-xs text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring"
+            />
+            {searchQuery && (
+              <button
+                type="button"
+                onClick={() => setSearchQuery("")}
+                className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+              >
+                <X className="size-3.5" />
+              </button>
+            )}
+          </div>
+        )}
+
+        {/* Drill-down Breadcrumbs */}
+        {!searchQuery && (
+          <div className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground overflow-x-auto py-0.5">
+            {activeTierPath.length > 0 ? (
+              <>
+                <motion.button
+                  type="button"
+                  whileTap={shouldReduceMotion ? undefined : { scale: 0.95 }}
+                  onClick={handleBack}
+                  className="flex items-center gap-0.5 text-primary hover:underline"
+                >
+                  <ChevronLeft className="size-3.5" />
+                  <span>Back</span>
+                </motion.button>
+                <span>/</span>
+                {activeTierPath.map((tier, idx) => (
+                  <span
+                    key={tier.value}
+                    className={cn(
+                      idx === activeTierPath.length - 1
+                        ? "text-foreground font-semibold"
+                        : "text-muted-foreground"
+                    )}
+                  >
+                    {tier.label}
+                  </span>
+                ))}
+              </>
+            ) : (
+              <span className="flex items-center gap-1.5 text-foreground font-medium">
+                <Layers className="size-3.5 text-primary" />
+                <span>Root Categories</span>
+              </span>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Options Body */}
+      <div className="relative min-h-[220px] max-h-[300px] overflow-y-auto p-1.5">
+        {searchQuery ? (
+          // Search Results View
+          <div className="flex flex-col gap-1">
+            {flatSearchMatches.map((res) => (
+              <button
+                key={res.path.join("-")}
+                type="button"
+                onClick={() => {
+                  if (res.option.disabled) return;
+                  setSelectedPath(res.path);
+                  onChange?.(res.path, res.option);
+                  setSearchQuery("");
+                }}
+                className="flex items-center justify-between rounded-xl px-2.5 py-2 text-left text-xs hover:bg-muted transition-colors"
+              >
+                <span className="text-foreground">{res.fullLabel}</span>
+                {selectedPath.join("/") === res.path.join("/") && (
+                  <Check className="size-3.5 text-primary" />
+                )}
+              </button>
+            ))}
+            {flatSearchMatches.length === 0 && (
+              <div className="flex h-32 items-center justify-center text-xs text-muted-foreground">
+                No matching options found.
+              </div>
+            )}
+          </div>
+        ) : (
+          // Hierarchical Drill-down View
+          <AnimatePresence mode="wait">
+            <motion.div
+              key={activeTierPath.map((o) => o.value).join("/") || "root"}
+              initial={{ opacity: 0, x: shouldReduceMotion ? 0 : 12 }}
+              animate={{ opacity: 1, x: 0 }}
+              exit={{ opacity: 0, x: shouldReduceMotion ? 0 : -12 }}
+              transition={{ duration: 0.18, ease: EASE_OUT }}
+              className="flex flex-col gap-1"
+            >
+              {currentLevelOptions.map((opt) => {
+                const hasChildren = Boolean(opt.children && opt.children.length > 0);
+                const isSelected = selectedPath.includes(opt.value);
+
+                return (
+                  <motion.button
+                    key={opt.value}
+                    type="button"
+                    disabled={opt.disabled}
+                    whileTap={shouldReduceMotion ? undefined : { scale: 0.98 }}
+                    onClick={() => handleSelect(opt)}
+                    className={cn(
+                      "flex items-center justify-between rounded-xl px-3 py-2 text-xs font-medium transition-colors",
+                      isSelected
+                        ? "bg-primary/10 text-primary font-semibold"
+                        : "text-foreground hover:bg-muted/70",
+                      opt.disabled && "opacity-40 cursor-not-allowed"
+                    )}
+                  >
+                    <div className="flex items-center gap-2">
+                      {hasChildren ? (
+                        <Folder className="size-3.5 text-muted-foreground" />
+                      ) : (
+                        <div className="size-1.5 rounded-full bg-current" />
+                      )}
+                      <span>{opt.label}</span>
+                    </div>
+
+                    <div className="flex items-center gap-1.5">
+                      {isSelected && !hasChildren && (
+                        <Check className="size-3.5 text-primary" />
+                      )}
+                      {hasChildren && (
+                        <ChevronRight className="size-3.5 text-muted-foreground" />
+                      )}
+                    </div>
+                  </motion.button>
+                );
+              })}
+            </motion.div>
+          </AnimatePresence>
+        )}
+      </div>
+
+      {/* Footer Selected Summary */}
+      {selectedPath.length > 0 && (
+        <div className="border-t border-border/70 bg-muted/20 px-3 py-2 text-[11px] text-muted-foreground">
+          Selected: <span className="font-semibold text-foreground">{selectedPath.join(" / ")}</span>
+        </div>
+      )}
+    </motion.div>
+  );
+}

package/components/motion/center-morph-modal.tsx

@@ -0,0 +1,366 @@
+"use client";
+
+import { X } from "lucide-react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import {
+  cloneElement,
+  createContext,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { createPortal } from "react-dom";
+import { EASE_OUT } from "@/lib/ease";
+import { PresenceGate } from "@/lib/presence-gate";
+import { cn } from "@/lib/utils";
+
+type CenterMorphModalContextValue = {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  triggerId: string;
+  contentId: string;
+};
+
+const CenterMorphModalContext =
+  createContext<CenterMorphModalContextValue | null>(null);
+
+function useCenterMorphModalContext(component: string) {
+  const context = useContext(CenterMorphModalContext);
+  if (!context) {
+    throw new Error(`${component} must be used within <CenterMorphModal>`);
+  }
+  return context;
+}
+
+export interface CenterMorphModalProps {
+  children: ReactNode;
+  /** Controlled open state. */
+  open?: boolean;
+  /** Initial state when used uncontrolled. */
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * A modal whose full-size surface unfolds outward from its exact center.
+ * Supports controlled and uncontrolled state through composable primitives.
+ */
+export function CenterMorphModal({
+  children,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+}: CenterMorphModalProps) {
+  const id = useId();
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const controlled = controlledOpen !== undefined;
+  const open = controlled ? controlledOpen : internalOpen;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!controlled) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [controlled, onOpenChange],
+  );
+
+  const value = useMemo<CenterMorphModalContextValue>(
+    () => ({
+      open,
+      setOpen,
+      triggerId: `${id}-trigger`,
+      contentId: `${id}-content`,
+    }),
+    [id, open, setOpen],
+  );
+
+  return (
+    <CenterMorphModalContext.Provider value={value}>
+      {children}
+    </CenterMorphModalContext.Provider>
+  );
+}
+
+export interface CenterMorphModalTriggerProps {
+  children: ReactElement;
+}
+
+/** Wraps one interactive element and opens or closes the modal. */
+export function CenterMorphModalTrigger({
+  children,
+}: CenterMorphModalTriggerProps) {
+  const context = useCenterMorphModalContext("CenterMorphModalTrigger");
+  if (!isValidElement(children)) return children;
+
+  const child = children as ReactElement<Record<string, unknown>>;
+  const childOnClick = child.props.onClick as
+    | ((event: React.MouseEvent<HTMLElement>) => void)
+    | undefined;
+
+  return cloneElement(child, {
+    id: context.triggerId,
+    onClick: (event: React.MouseEvent<HTMLElement>) => {
+      childOnClick?.(event);
+      if (!event.defaultPrevented) context.setOpen(!context.open);
+    },
+    "aria-haspopup": "dialog",
+    "aria-expanded": context.open,
+    "aria-controls": context.open ? context.contentId : undefined,
+  });
+}
+
+export interface CenterMorphModalCloseProps {
+  children: ReactElement;
+}
+
+/** Wraps one interactive element and closes the modal. */
+export function CenterMorphModalClose({
+  children,
+}: CenterMorphModalCloseProps) {
+  const context = useCenterMorphModalContext("CenterMorphModalClose");
+  if (!isValidElement(children)) return children;
+
+  const child = children as ReactElement<Record<string, unknown>>;
+  const childOnClick = child.props.onClick as
+    | ((event: React.MouseEvent<HTMLElement>) => void)
+    | undefined;
+
+  return cloneElement(child, {
+    onClick: (event: React.MouseEvent<HTMLElement>) => {
+      childOnClick?.(event);
+      if (!event.defaultPrevented) context.setOpen(false);
+    },
+  });
+}
+
+export interface CenterMorphModalContentProps {
+  children: ReactNode;
+  /** Accessible name announced by screen readers. */
+  ariaLabel: string;
+  /** Optional id of descriptive content inside the modal. */
+  ariaDescribedBy?: string;
+  /** Close on Escape or backdrop press. Default true. */
+  dismissible?: boolean;
+  /** Render the close control inside the panel's top-right corner. Default true. */
+  showCloseButton?: boolean;
+  closeButtonLabel?: string;
+  className?: string;
+  backdropClassName?: string;
+}
+
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+const CENTER_FOLDED_CLIP =
+  "inset(48% 48% 48% 48% round 30px)";
+const CENTER_OPEN_CLIP = "inset(0% 0% 0% 0% round 30px)";
+
+// Complex clip-path strings can snap when a spring resolves its final distance.
+// Keep the radius constant so the whole duration reads as surface unfolding,
+// rather than finishing early and spending its last frames rounding corners.
+const CENTER_UNFOLD_EASE = [0.2, 0, 0.2, 1] as const;
+const CENTER_UNFOLD_TRANSITION = {
+  duration: 0.43,
+  ease: CENTER_UNFOLD_EASE,
+} as const;
+
+function getFocusableElements(root: HTMLElement | null) {
+  if (!root) return [];
+  return Array.from(
+    root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  ).filter((element) => element.tabIndex >= 0);
+}
+
+export function CenterMorphModalContent({
+  children,
+  ariaLabel,
+  ariaDescribedBy,
+  dismissible = true,
+  showCloseButton = true,
+  closeButtonLabel = "Close modal",
+  className,
+  backdropClassName,
+}: CenterMorphModalContentProps) {
+  const context = useCenterMorphModalContext("CenterMorphModalContent");
+  const reduce = useReducedMotion() ?? false;
+  const [mounted, setMounted] = useState(false);
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => setMounted(true), []);
+
+  useEffect(() => {
+    if (!context.open) return;
+
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+
+    const focusFrame = requestAnimationFrame(() => {
+      const [firstFocusable] = getFocusableElements(panelRef.current);
+      (firstFocusable ?? panelRef.current)?.focus();
+    });
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape" && dismissible) {
+        event.preventDefault();
+        context.setOpen(false);
+        return;
+      }
+
+      if (event.key !== "Tab") return;
+      const focusable = getFocusableElements(panelRef.current);
+      if (focusable.length === 0) {
+        event.preventDefault();
+        panelRef.current?.focus();
+        return;
+      }
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => {
+      cancelAnimationFrame(focusFrame);
+      window.removeEventListener("keydown", onKeyDown);
+      document.body.style.overflow = previousOverflow;
+      document.getElementById(context.triggerId)?.focus();
+    };
+  }, [context, dismissible]);
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <AnimatePresence>
+      {context.open ? (
+        <PresenceGate>
+          {({ isPresent, gate }) => (
+            <>
+              <motion.button
+                type="button"
+                aria-label="Dismiss modal"
+                tabIndex={-1}
+                disabled={!dismissible}
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                exit={{ opacity: 0 }}
+                {...gate}
+                transition={{
+                  duration: reduce ? 0.1 : 0.28,
+                  ease: EASE_OUT,
+                }}
+                onClick={() => context.setOpen(false)}
+                className={cn(
+                  "pointer-events-auto fixed inset-0 z-[100] h-full w-full cursor-default bg-background/10 backdrop-blur-sm",
+                  backdropClassName,
+                )}
+              />
+
+              {/* `inset-4` rather than `inset-0 p-4`: same content box, but the
+                  layer stays off the viewport edges. It never takes pointer
+                  events, so it carries `inert` alone. See
+                  tests/fixed-overlay-edge-sampling.test.tsx. */}
+              <div
+                inert={!isPresent}
+                className="pointer-events-none fixed inset-4 z-[100] flex items-center justify-center overflow-y-auto drop-shadow-2xl"
+              >
+                {/* Drop-shadow reads the clipped child's alpha, so depth follows the
+                    unfolding silhouette without introducing another panel layer. */}
+                <div className="flex w-full flex-col items-center py-8">
+                  <motion.div
+                    ref={panelRef}
+                    id={context.contentId}
+                    role="dialog"
+                    aria-modal="true"
+                    aria-label={ariaLabel}
+                    aria-describedby={ariaDescribedBy}
+                    tabIndex={-1}
+                    initial={
+                      reduce
+                        ? { opacity: 0, clipPath: CENTER_OPEN_CLIP }
+                        : { opacity: 1, clipPath: CENTER_FOLDED_CLIP }
+                    }
+                    animate={{
+                      opacity: 1,
+                      clipPath: CENTER_OPEN_CLIP,
+                    }}
+                    exit={
+                      reduce
+                        ? {
+                            opacity: 0,
+                            clipPath: CENTER_OPEN_CLIP,
+                          }
+                        : {
+                            opacity: 1,
+                            clipPath: CENTER_FOLDED_CLIP,
+                          }
+                    }
+                    {...gate}
+                    transition={
+                      reduce
+                        ? { duration: 0.14, ease: EASE_OUT }
+                        : CENTER_UNFOLD_TRANSITION
+                    }
+                    className={cn(
+                      "pointer-events-auto relative w-full max-w-[26rem] origin-center overflow-hidden rounded-[30px] border border-border bg-background will-change-[clip-path]",
+                      className,
+                    )}
+                  >
+                    {children}
+
+                    {showCloseButton ? (
+                      <motion.button
+                        type="button"
+                        aria-label={closeButtonLabel}
+                        onClick={() => context.setOpen(false)}
+                        initial={
+                          reduce
+                            ? { opacity: 0 }
+                            : { opacity: 0, scale: 0.8 }
+                        }
+                        animate={{ opacity: 1, scale: 1 }}
+                        exit={{
+                          opacity: 0,
+                          scale: reduce ? 1 : 0.88,
+                          transition: { duration: 0.1, ease: EASE_OUT },
+                        }}
+                        transition={{
+                          delay: reduce ? 0 : 0.16,
+                          duration: reduce ? 0.12 : 0.2,
+                          ease: EASE_OUT,
+                        }}
+                        className="absolute right-4 top-4 inline-flex h-8 w-8 items-center justify-center rounded-full bg-foreground/[0.05] text-muted-foreground transition-colors hover:bg-foreground/[0.08] hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                      >
+                        <X className="h-4 w-4" aria-hidden="true" />
+                      </motion.button>
+                    ) : null}
+                  </motion.div>
+                </div>
+              </div>
+            </>
+          )}
+        </PresenceGate>
+      ) : null}
+    </AnimatePresence>,
+    document.body,
+  );
+}