motion-ui-skill 2.0.0

package/components/widgets/wifi-toggle-widget.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import { forwardRef, useState, type ComponentPropsWithoutRef } from "react";
+
+import { cn } from "@/lib/cn";
+import { Wifi } from "lucide-react";
+
+// iOS-style Wi-Fi card with a status dot, network label, and on/off switch.
+export type WiFiToggleWidgetProps = Readonly<
+  {
+    // Network name shown when Wi-Fi is on.
+    networkName?: string;
+    // Initial toggle state when the widget first renders.
+    defaultOn?: boolean;
+  } & ComponentPropsWithoutRef<"div">
+>;
+
+// iOS-style Wi-Fi card with a status dot, network label, and on/off switch.
+export const WiFiToggleWidget = forwardRef<
+  HTMLDivElement,
+  WiFiToggleWidgetProps
+>(
+  (
+    { className, networkName = "Studio-5G", defaultOn = false, ...props },
+    ref,
+  ) => {
+    const [on, setOn] = useState(defaultOn);
+
+    return (
+      <div
+        ref={ref}
+        data-slot="wifi-toggle-widget"
+        className={cn(
+          "flex h-44 w-44 flex-col overflow-hidden rounded-3xl border border-neutral-100 bg-white p-4 font-sans shadow-lg shadow-black/5 select-none",
+          className,
+        )}
+        {...props}
+      >
+        <div className="flex items-center justify-between gap-2">
+          <p className="text-[10px] font-semibold tracking-widest text-neutral-400 uppercase">
+            Wi-Fi
+          </p>
+          {/* Green dot = connected, gray dot = off. */}
+          <span
+            aria-hidden
+            className={cn(
+              "h-2 w-2 shrink-0 rounded-full transition-colors",
+              on ? "bg-emerald-500" : "bg-neutral-300",
+            )}
+          />
+          <span className="sr-only">{on ? "Connected" : "Off"}</span>
+        </div>
+
+        {/* Icon and network details update based on the toggle state. */}
+        <div className="flex flex-1 flex-col items-center justify-center gap-1 py-2">
+          <div
+            className={cn(
+              "flex h-11 w-11 items-center justify-center rounded-full transition-colors",
+              on ? "bg-neutral-100" : "bg-neutral-50",
+            )}
+          >
+            <Wifi
+              size={22}
+              className={cn(
+                "transition-colors",
+                on ? "text-neutral-900" : "text-neutral-300",
+              )}
+            />
+          </div>
+          <p
+            className={cn(
+              "max-w-full truncate text-xs font-semibold",
+              on ? "text-neutral-900" : "text-neutral-400",
+            )}
+          >
+            {on ? networkName : "No network"}
+          </p>
+          <p className="text-[10px] text-neutral-400">
+            {on ? "WPA3 · 5 GHz" : "Tap to connect"}
+          </p>
+        </div>
+
+        {/* Bottom switch — slides right when Wi-Fi is on. */}
+        <div className="flex justify-center">
+          <button
+            type="button"
+            aria-label="Toggle Wi-Fi"
+            aria-pressed={on}
+            onClick={() => setOn(!on)}
+            className={cn(
+              "flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full p-0.5 transition-colors",
+              on ? "bg-emerald-400" : "bg-neutral-200",
+            )}
+          >
+            <span
+              className={cn(
+                "h-5 w-5 rounded-full bg-white shadow-sm transition-transform duration-200 ease-out",
+                on ? "translate-x-5" : "translate-x-0",
+              )}
+            />
+          </button>
+        </div>
+      </div>
+    );
+  },
+);
+
+WiFiToggleWidget.displayName = "WiFiToggleWidget";

package/lib/cn.ts

@@ -0,0 +1 @@
+export { cn } from "./utils";

package/lib/ease.ts

@@ -0,0 +1,108 @@
+// Shared motion tokens. Easing curves mirror the CSS custom properties in
+// globals.css; springs are the canonical physics used across components.
+// Strong custom variants — defaults like `ease-in`/`ease-out` feel weak.
+
+export const EASE_OUT = [0.16, 1, 0.3, 1] as const;
+export const EASE_IN_OUT = [0.77, 0, 0.175, 1] as const;
+export const EASE_DRAWER = [0.32, 0.72, 0, 1] as const;
+
+/** CSS string form of EASE_OUT for inline style transitions. */
+export const EASE_OUT_CSS = "cubic-bezier(0.16, 1, 0.3, 1)";
+
+export type SpringConfig = Readonly<{
+  type: "spring";
+  stiffness: number;
+  damping: number;
+  mass: number;
+}>;
+
+/** Press feedback on buttons and other tappable surfaces. */
+export const SPRING_PRESS = {
+  type: "spring",
+  stiffness: 500,
+  damping: 30,
+  mass: 0.6,
+} as const;
+
+/** Content swaps — label/icon slots trading places inside a control. */
+export const SPRING_SWAP = {
+  type: "spring",
+  stiffness: 460,
+  damping: 30,
+  mass: 0.55,
+} as const;
+
+/** Overlay panel entrances — modals and sheets summoned by pointer. */
+export const SPRING_PANEL = {
+  type: "spring",
+  stiffness: 420,
+  damping: 40,
+  mass: 0.5,
+} as const;
+
+/** Shared-layout glides — pills, indicators and panels morphing between positions. */
+export const SPRING_LAYOUT = {
+  type: "spring",
+  stiffness: 360,
+  damping: 32,
+  mass: 0.6,
+} as const;
+
+/** Cursor-follow physics for decorative mouse tracking (magnetic, tilt, dock). */
+export const SPRING_MOUSE = {
+  stiffness: 200,
+  damping: 15,
+  mass: 0.3,
+} as const;
+
+/** Dragged handles and fills (sliders) — critically damped `useSpring` config,
+ * so the value follows the pointer butterily and never rebounds off an end. */
+export const SPRING_GLIDE = {
+  stiffness: 700,
+  damping: 50,
+  mass: 0.5,
+} as const;
+
+/** Playful bounce for badges, celebration checks, stars, and micro-pops. */
+export const SPRING_BOUNCE = {
+  type: "spring",
+  stiffness: 300,
+  damping: 18,
+  mass: 0.8,
+} as const;
+
+/** Gentle, natural spring for spacious card expansions and drawer reveals. */
+export const SPRING_GENTLE = {
+  type: "spring",
+  stiffness: 180,
+  damping: 24,
+  mass: 1.0,
+} as const;
+
+/** Snappy, high-velocity spring for fast toggles, segmented pills, and tabs. */
+export const SPRING_SNAPPY = {
+  type: "spring",
+  stiffness: 600,
+  damping: 35,
+  mass: 0.5,
+} as const;
+
+/** Soft floating physics for tooltips, hover cards, and ambient elevation. */
+export const SPRING_FLOAT = {
+  type: "spring",
+  stiffness: 120,
+  damping: 14,
+  mass: 0.8,
+} as const;
+
+/** Emphasized cubic bezier for expressive spatial navigation. */
+export const EASE_EMPHASIZED = [0.2, 0, 0, 1] as const;
+export const EASE_EMPHASIZED_CSS = "cubic-bezier(0.2, 0, 0, 1)";
+
+/** Deceleration curve for incoming elements that enter at high velocity and brake. */
+export const EASE_DECELERATE = [0.05, 0.7, 0.1, 1] as const;
+export const EASE_DECELERATE_CSS = "cubic-bezier(0.05, 0.7, 0.1, 1)";
+
+/** Acceleration curve for dismissed elements that exit without lingering. */
+export const EASE_ACCELERATE = [0.3, 0, 0.8, 0.15] as const;
+export const EASE_ACCELERATE_CSS = "cubic-bezier(0.3, 0, 0.8, 0.15)";

package/lib/favicon.ts

@@ -0,0 +1,8 @@
+/** Resolve a website URL to its conventional root favicon location. */
+export function getFaviconUrl(value: string) {
+  try {
+    return new URL("/favicon.ico", value).toString();
+  } catch {
+    return null;
+  }
+}

package/lib/hooks/use-dismiss.ts

@@ -0,0 +1,120 @@
+"use client";
+
+import { type RefObject, useEffect } from "react";
+
+/**
+ * What the dismissing gesture does to the control it landed on.
+ *
+ * `"pass-through"` is the platform norm (native popover light-dismiss): the
+ * tap closes the overlay *and* activates whatever was under it. Use
+ * `"consume"` where the open overlay sits over or beside controls that would
+ * be costly to trigger by accident — the dismissal then swallows the
+ * activation too, so the gesture only closes.
+ */
+export type DismissBehavior = "pass-through" | "consume";
+
+export interface DismissOptions {
+  /** Default `"pass-through"`. */
+  behavior?: DismissBehavior;
+  /** Dismiss on Escape as well. Default true. */
+  escape?: boolean;
+  /** Return true for an outside target that should *not* dismiss. Must be stable. */
+  ignore?: (target: Element) => boolean;
+}
+
+/**
+ * What every currently open dismiss scope counts as inside itself. A consumed
+ * dismissal reads this to tell a stray gesture from one that belongs to an
+ * overlay in front of it: overlays have no shared z-order to consult, but the
+ * one the gesture landed in has said as much by registering it.
+ */
+const openScopes = new Set<(target: Element) => boolean>();
+
+function claimedByAnotherScope(
+  self: (target: Element) => boolean,
+  target: Element,
+) {
+  for (const scope of openScopes) {
+    if (scope !== self && scope(target)) return true;
+  }
+  return false;
+}
+
+// preventDefault on pointerdown does not suppress the click that follows, so
+// consuming a gesture means swallowing that click itself. The swallower
+// deliberately outlives the effect that installed it — the dismissal it
+// belongs to has already unmounted or re-rendered by the time the click lands.
+// It releases on that click, or on the next gesture if the pointer is dragged
+// away and no click ever arrives, so it can never eat a later one. A keydown
+// releases it too: a gesture that ends with neither a click nor a cancel would
+// otherwise leave it armed, and the click Enter synthesizes on some focused
+// control is not the one this dismissal was owed.
+function consumeActivation(source: Event) {
+  const swallow = (event: MouseEvent) => {
+    event.preventDefault();
+    event.stopPropagation();
+    release();
+  };
+  const restart = (event: Event) => {
+    if (event !== source) release();
+  };
+  const release = () => {
+    window.removeEventListener("click", swallow, true);
+    window.removeEventListener("pointerdown", restart, true);
+    window.removeEventListener("pointercancel", restart, true);
+    window.removeEventListener("keydown", release, true);
+  };
+  window.addEventListener("click", swallow, true);
+  window.addEventListener("pointerdown", restart, true);
+  window.addEventListener("pointercancel", restart, true);
+  window.addEventListener("keydown", release, true);
+}
+
+/**
+ * Close an open overlay on Escape or a pointerdown outside `ref`. Pass `null`
+ * for `ref` when what counts as inside isn't one element, and say so with
+ * `ignore` instead.
+ *
+ * The pointerdown listener is capture-phase: a bubble-phase one is blinded by
+ * any handler in between that stops propagation, and an overlay cannot know
+ * what it is layered over. `onDismiss` and `ignore` must be stable (wrap in
+ * useCallback) so the listeners aren't re-bound every render while open.
+ */
+export function useDismiss(
+  open: boolean,
+  onDismiss: () => void,
+  ref: RefObject<HTMLElement | null> | null,
+  {
+    behavior = "pass-through",
+    escape: dismissOnEscape = true,
+    ignore,
+  }: DismissOptions = {},
+) {
+  useEffect(() => {
+    if (!open) return;
+    const inside = (target: Element) =>
+      Boolean(ref?.current?.contains(target)) || Boolean(ignore?.(target));
+    const onKey = (event: KeyboardEvent) => {
+      if (dismissOnEscape && event.key === "Escape") onDismiss();
+    };
+    const onPointer = (event: PointerEvent) => {
+      const target = event.target as Element | null;
+      if (!target || inside(target)) return;
+      // Outside this overlay, but inside one that is also open: the gesture is
+      // that overlay's to answer, and swallowing its click from behind would
+      // cost the user the control they actually aimed at.
+      if (behavior === "consume" && !claimedByAnotherScope(inside, target)) {
+        consumeActivation(event);
+      }
+      onDismiss();
+    };
+    openScopes.add(inside);
+    window.addEventListener("keydown", onKey);
+    window.addEventListener("pointerdown", onPointer, true);
+    return () => {
+      openScopes.delete(inside);
+      window.removeEventListener("keydown", onKey);
+      window.removeEventListener("pointerdown", onPointer, true);
+    };
+  }, [open, onDismiss, ref, behavior, dismissOnEscape, ignore]);
+}

package/lib/hooks/use-favicon.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { getFaviconUrl } from "@/lib/favicon";
+
+/**
+ * Resolves a site favicon and drops it once it is known to be unusable, so
+ * callers can draw their own glyph instead of a broken image. Plenty of sites
+ * answer `/favicon.ico` with a 403 or 404, and `onError` is not enough to catch
+ * it: an image the browser starts loading from server-rendered HTML usually
+ * fails before React attaches a handler, and that event is never replayed.
+ * `decode()` settles on the image's final state instead of relying on an event
+ * firing at the right moment.
+ */
+export function useFavicon(url?: string) {
+  const resolved = url ? getFaviconUrl(url) : null;
+  const [failedSrc, setFailedSrc] = useState<string | null>(null);
+  const src = resolved && resolved !== failedSrc ? resolved : null;
+
+  const ref = useCallback(
+    (img: HTMLImageElement | null) => {
+      if (!img || !src) return;
+
+      let released = false;
+      img.decode().catch(() => {
+        if (!released) setFailedSrc(src);
+      });
+
+      // The node is going away or the source changed; a late rejection then
+      // describes an image we are no longer showing.
+      return () => {
+        released = true;
+      };
+    },
+    [src],
+  );
+
+  return { src, ref };
+}

package/lib/hooks/use-haptic.ts

@@ -0,0 +1,44 @@
+"use client";
+
+import { useCallback } from "react";
+
+export type HapticType =
+  | "selection"
+  | "light"
+  | "medium"
+  | "heavy"
+  | "success"
+  | "warning"
+  | "error";
+
+const HAPTIC_PATTERNS: Record<HapticType, number | number[]> = {
+  selection: 10,
+  light: 15,
+  medium: 30,
+  heavy: 50,
+  success: [15, 60, 25],
+  warning: [30, 80, 30],
+  error: [40, 60, 40, 60, 40],
+};
+
+/**
+ * Provides semantic haptic feedback using navigator.vibrate where available.
+ * Degrades silently on desktop browsers or unsupported devices.
+ */
+export function useHaptic() {
+  const trigger = useCallback((type: HapticType = "selection") => {
+    if (typeof window === "undefined" || typeof navigator === "undefined") {
+      return;
+    }
+    if (typeof navigator.vibrate === "function") {
+      try {
+        const pattern = HAPTIC_PATTERNS[type];
+        navigator.vibrate(pattern);
+      } catch {
+        // Silently catch browsers blocking vibration
+      }
+    }
+  }, []);
+
+  return trigger;
+}

package/lib/hooks/use-hover-capable.ts

@@ -0,0 +1,23 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Returns true only on devices that have a true hover (mouse / trackpad).
+ * Touch devices fire phantom `:hover` on tap that sticks until tap-elsewhere
+ * — gate hover-only effects (scale lifts, magnetic pulls) behind this.
+ */
+export function useHoverCapable() {
+  const [canHover, setCanHover] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia("(hover: hover) and (pointer: fine)");
+    const update = () => setCanHover(mq.matches);
+    update();
+    mq.addEventListener?.("change", update);
+    return () => mq.removeEventListener?.("change", update);
+  }, []);
+
+  return canHover;
+}

package/lib/hooks/use-hover-gesture.ts

@@ -0,0 +1,61 @@
+"use client";
+
+import { useMemo, useRef } from "react";
+import { isHoveringPointer } from "@/lib/touch";
+
+interface BoundaryEvent {
+  pointerId: number;
+  pointerType: string;
+  buttons: number;
+}
+
+export interface HoverGesture {
+  /** True when this enter starts a hover: the pointer arrived resting, not pressing. */
+  enter: (event: BoundaryEvent) => boolean;
+  /** True when this leave ends a hover that entered as one. */
+  leave: (event: BoundaryEvent) => boolean;
+}
+
+/**
+ * Pairs a surface's enter with its leave, per pointer.
+ *
+ * `isHoveringPointer` answers the question the *enter* asks — is this pointer
+ * resting on the surface or pressing it — and both boundary cases go wrong if
+ * the leave is asked the same question again:
+ *
+ * - A pen with no hover never rests. It arrives in contact, taps, and the spec
+ *   then requires its boundary events after `pointerup`, so the leave carries
+ *   `buttons: 0` and reads as a mouse gliding off. Hover teardown then undid
+ *   the tap — the panel the pen had just opened closed under it.
+ * - A mouse pressed on the surface and dragged off leaves with `buttons: 1`.
+ *   Skipping teardown there strands the surface open: the release happens
+ *   outside, and no second leave ever comes.
+ *
+ * So the state a hover holds is released by the pointer that took it, whatever
+ * the buttons say at the boundary, and a pointer that arrived in contact never
+ * took it in the first place. Contact is the exception tracked here, not
+ * hover: a leave from a pointer this surface never saw enter — mounted under
+ * the cursor, say — still counts, since the alternative is state with no way
+ * out.
+ */
+export function useHoverGesture(): HoverGesture {
+  const contact = useRef(new Set<number>());
+
+  return useMemo(
+    () => ({
+      enter: (event) => {
+        if (isHoveringPointer(event)) {
+          contact.current.delete(event.pointerId);
+          return true;
+        }
+        contact.current.add(event.pointerId);
+        return false;
+      },
+      leave: (event) => {
+        const arrivedInContact = contact.current.delete(event.pointerId);
+        return !arrivedInContact && event.pointerType !== "touch";
+      },
+    }),
+    [],
+  );
+}

package/lib/hooks/use-in-view-animation.ts

@@ -0,0 +1,35 @@
+"use client";
+
+import { useInView, useReducedMotion, type UseInViewOptions } from "motion/react";
+import { useRef, type RefObject } from "react";
+
+type InViewMargin = NonNullable<UseInViewOptions["margin"]>;
+
+export interface UseInViewAnimationOptions {
+  once?: boolean;
+  amount?: "some" | "all" | number;
+  margin?: InViewMargin;
+}
+
+/**
+ * Hook to trigger motion animations when an element scrolls into view.
+ * Automatically respects reduced-motion preferences.
+ */
+export function useInViewAnimation<T extends HTMLElement = HTMLElement>(
+  options: UseInViewAnimationOptions = {}
+): {
+  ref: RefObject<T | null>;
+  isInView: boolean;
+  shouldAnimate: boolean;
+} {
+  const { once = true, amount = 0.2, margin = "0px" } = options;
+  const ref = useRef<T | null>(null);
+  const isInView = useInView(ref, { once, amount, margin });
+  const prefersReduced = useReducedMotion();
+
+  return {
+    ref,
+    isInView,
+    shouldAnimate: isInView && !prefersReduced,
+  };
+}

package/lib/hooks/use-measure.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { useCallback, useEffect, useState, type RefCallback } from "react";
+
+export interface Dimensions {
+  width: number;
+  height: number;
+}
+
+/**
+ * Measure DOM element dimensions using ResizeObserver without layout thrashing.
+ */
+export function useMeasure<T extends HTMLElement = HTMLElement>(): [
+  RefCallback<T>,
+  Dimensions
+] {
+  const [element, setElement] = useState<T | null>(null);
+  const [bounds, setBounds] = useState<Dimensions>({ width: 0, height: 0 });
+  const ref = useCallback<RefCallback<T>>((next) => setElement(next), []);
+
+  useEffect(() => {
+    if (!element || typeof ResizeObserver === "undefined") return;
+
+    const observer = new ResizeObserver(([entry]) => {
+      if (entry && entry.contentRect) {
+        const { width, height } = entry.contentRect;
+        setBounds({
+          width: Math.round(width),
+          height: Math.round(height),
+        });
+      }
+    });
+
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [element]);
+
+  return [ref, bounds];
+}

package/lib/hooks/use-on-open.ts

@@ -0,0 +1,24 @@
+"use client";
+
+import { useState } from "react";
+
+/**
+ * Runs `start` during the render in which `open` becomes true.
+ *
+ * Opening a list starts a fresh session — an empty query, the highlight back at
+ * the top — and that is a resolution, not a side effect: a passive effect runs
+ * after the commit, so the new session would carry the last one's state for a
+ * window in which a key press can land.
+ *
+ * `start` may only set state belonging to the calling component. Anything that
+ * reaches outside it — a consumer's callback, a DOM write, moving focus — is a
+ * side effect, and React rejects a callback that sets another component's state
+ * during this one's render. Put those in an effect keyed to `open`.
+ */
+export function useOnOpen(open: boolean, start: () => void) {
+  const [wasOpen, setWasOpen] = useState(open);
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (open) start();
+  }
+}