motion-ui-skill 2.0.0

package/components/motion/table/use-column-resize.ts

@@ -0,0 +1,81 @@
+import {
+  type PointerEvent as ReactPointerEvent,
+  useCallback,
+  useRef,
+  useState,
+} from "react";
+import { capturePointer, releasePointer } from "@/lib/touch";
+import type { HeaderCellRefs, TableColumn } from "./types";
+
+export function useColumnResize<T>({
+  orderedColumns,
+  thRefs,
+  minColumnWidth,
+  onColumnResize,
+}: {
+  orderedColumns: TableColumn<T>[];
+  thRefs: HeaderCellRefs;
+  minColumnWidth: number;
+  onColumnResize?: (key: string, width: number) => void;
+}) {
+  const resizeRef = useRef<{
+    key: string;
+    startX: number;
+    startWidth: number;
+  } | null>(null);
+  const [widths, setWidths] = useState<Record<string, number>>({});
+
+  const startResize = useCallback(
+    (key: string, e: ReactPointerEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      // Freeze every column to its current pixel width so resizing one only
+      // moves the trailing spacer, never the other columns.
+      const snapshot = { ...widths };
+      for (const column of orderedColumns) {
+        if (snapshot[column.key] == null) {
+          const measured = thRefs.current[column.key]?.getBoundingClientRect()
+            .width;
+          snapshot[column.key] = measured
+            ? Math.round(measured)
+            : minColumnWidth;
+        }
+      }
+      resizeRef.current = {
+        key,
+        startX: e.clientX,
+        startWidth: snapshot[key],
+      };
+      setWidths(snapshot);
+      capturePointer(e.currentTarget, e.pointerId);
+    },
+    [minColumnWidth, orderedColumns, thRefs, widths],
+  );
+
+  const moveResize = useCallback(
+    (e: ReactPointerEvent) => {
+      const state = resizeRef.current;
+      if (!state) return;
+      const width = Math.max(
+        minColumnWidth,
+        state.startWidth + (e.clientX - state.startX),
+      );
+      setWidths((prev) => ({ ...prev, [state.key]: width }));
+    },
+    [minColumnWidth],
+  );
+
+  const endResize = useCallback(
+    (e: ReactPointerEvent) => {
+      const state = resizeRef.current;
+      resizeRef.current = null;
+      releasePointer(e.currentTarget, e.pointerId);
+      if (state) {
+        onColumnResize?.(state.key, widths[state.key] ?? state.startWidth);
+      }
+    },
+    [onColumnResize, widths],
+  );
+
+  return { widths, startResize, moveResize, endResize };
+}

package/components/motion/table/use-column-sort.ts

@@ -0,0 +1,64 @@
+import { useCallback, useMemo, useState } from "react";
+import type { SortState, TableColumn, TableRow } from "./types";
+import { readSortValue } from "./utils";
+
+export function useColumnSort<T>({
+  rows,
+  columns,
+  sort: sortProp,
+  defaultSort = null,
+  onSortChange,
+}: {
+  rows: TableRow<T>[];
+  columns: TableColumn<T>[];
+  sort?: SortState | null;
+  defaultSort?: SortState | null;
+  onSortChange?: (sort: SortState | null) => void;
+}) {
+  const [internalSort, setInternalSort] = useState<SortState | null>(
+    defaultSort,
+  );
+  const sort = sortProp !== undefined ? sortProp : internalSort;
+
+  const commit = useCallback(
+    (next: SortState | null) => {
+      if (sortProp === undefined) setInternalSort(next);
+      onSortChange?.(next);
+    },
+    [sortProp, onSortChange],
+  );
+
+  const toggleSort = useCallback(
+    (key: string) => {
+      if (!sort || sort.key !== key) {
+        commit({ key, direction: "asc" });
+      } else if (sort.direction === "asc") {
+        commit({ key, direction: "desc" });
+      } else {
+        commit(null);
+      }
+    },
+    [sort, commit],
+  );
+
+  const sortedRows = useMemo(() => {
+    if (!sort) return rows;
+    const column = columns.find((c) => c.key === sort.key);
+    if (!column) return rows;
+    const copy = [...rows];
+    copy.sort((a, b) => {
+      const av = readSortValue(a.row, column);
+      const bv = readSortValue(b.row, column);
+      let cmp: number;
+      if (typeof av === "number" && typeof bv === "number") {
+        cmp = av - bv;
+      } else {
+        cmp = String(av).localeCompare(String(bv));
+      }
+      return sort.direction === "asc" ? cmp : -cmp;
+    });
+    return copy;
+  }, [rows, sort, columns]);
+
+  return { sort, sortedRows, toggleSort };
+}

package/components/motion/table/use-row-selection.ts

@@ -0,0 +1,59 @@
+import { useCallback, useMemo, useState } from "react";
+import type { TableRow } from "./types";
+
+export function useRowSelection<T>({
+  sortedRows,
+  selectedRowIds,
+  defaultSelectedRowIds,
+  onSelectionChange,
+}: {
+  sortedRows: TableRow<T>[];
+  selectedRowIds?: string[];
+  defaultSelectedRowIds?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+}) {
+  const [internalSelected, setInternalSelected] = useState<Set<string>>(
+    () => new Set(defaultSelectedRowIds),
+  );
+  const selected = useMemo(
+    () =>
+      selectedRowIds !== undefined
+        ? new Set(selectedRowIds)
+        : internalSelected,
+    [selectedRowIds, internalSelected],
+  );
+
+  const commit = useCallback(
+    (next: Set<string>) => {
+      if (selectedRowIds === undefined) setInternalSelected(next);
+      onSelectionChange?.([...next]);
+    },
+    [selectedRowIds, onSelectionChange],
+  );
+
+  const allSelected =
+    sortedRows.length > 0 && sortedRows.every((r) => selected.has(r.id));
+  const someSelected = sortedRows.some((r) => selected.has(r.id));
+
+  const toggleAll = useCallback(() => {
+    const next = new Set(selected);
+    if (allSelected) {
+      for (const r of sortedRows) next.delete(r.id);
+    } else {
+      for (const r of sortedRows) next.add(r.id);
+    }
+    commit(next);
+  }, [allSelected, sortedRows, selected, commit]);
+
+  const toggleRow = useCallback(
+    (id: string) => {
+      const next = new Set(selected);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      commit(next);
+    },
+    [selected, commit],
+  );
+
+  return { selected, allSelected, someSelected, toggleAll, toggleRow };
+}

package/components/motion/table/utils.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import type { TableColumn } from "./types";
+
+export const CHECKBOX_PX = 48;
+export const CHECKBOX_WIDTH = `${CHECKBOX_PX}px`;
+
+/** Highlights the top edge of the active column's header cell. */
+export const COLUMN_ACTIVE_SHADOW = "inset 0 1px 0 var(--color-primary)";
+
+export function alignFlex(align: TableColumn<unknown>["align"]) {
+  if (align === "right") return "justify-end";
+  if (align === "center") return "justify-center";
+  return "justify-start";
+}
+
+export function alignText(align: TableColumn<unknown>["align"]) {
+  if (align === "right") return "text-right";
+  if (align === "center") return "text-center";
+  return "text-left";
+}
+
+export function readCell<T>(row: T, column: TableColumn<T>): ReactNode {
+  if (column.cell) return column.cell(row);
+  return (row as Record<string, ReactNode>)[column.key];
+}
+
+export function readSortValue<T>(
+  row: T,
+  column: TableColumn<T>,
+): string | number {
+  if (column.sortValue) return column.sortValue(row);
+  return (row as Record<string, string | number>)[column.key];
+}

package/components/motion/tabs.tsx

@@ -0,0 +1,207 @@
+"use client";
+
+import { motion, MotionConfig, useReducedMotion, type Transition } from "motion/react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useId,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import { EASE_OUT } from "@/lib/ease";
+import { cn } from "@/lib/utils";
+
+type Variant = "pill" | "underline" | "segment";
+
+type Ctx = {
+  value: string;
+  setValue: (v: string) => void;
+  layoutId: string;
+  variant: Variant;
+};
+
+const TabsCtx = createContext<Ctx | null>(null);
+
+function useTabs() {
+  const ctx = useContext(TabsCtx);
+  if (!ctx) throw new Error("Tabs.* must be used inside <Tabs>");
+  return ctx;
+}
+
+// Weighty spring for the active-tab indicator: a touch of overshoot so it
+// settles with life instead of snapping.
+const transition: Transition = {
+  type: "spring",
+  stiffness: 170,
+  damping: 24,
+  mass: 1.2,
+};
+
+export function Tabs({
+  defaultValue,
+  value,
+  onValueChange,
+  variant = "pill",
+  children,
+  className,
+}: {
+  defaultValue?: string;
+  value?: string;
+  onValueChange?: (v: string) => void;
+  variant?: Variant;
+  children: ReactNode;
+  className?: string;
+}) {
+  const [internal, setInternal] = useState(defaultValue ?? "");
+  const layoutId = useId();
+  const reduce = useReducedMotion();
+  const controlled = value !== undefined;
+  const current = controlled ? value : internal;
+  const setValue = useCallback(
+    (v: string) => {
+      if (!controlled) setInternal(v);
+      onValueChange?.(v);
+    },
+    [controlled, onValueChange],
+  );
+  const contextValue = useMemo(
+    () => ({ value: current, setValue, layoutId, variant }),
+    [current, layoutId, setValue, variant],
+  );
+  return (
+    <MotionConfig transition={reduce ? { duration: 0 } : transition}>
+      <TabsCtx.Provider value={contextValue}>
+        {/* layoutRoot: the indicator's layoutId measures in page coordinates, so
+            inside fixed/scrolled containers it would replay scroll offsets as
+            movement. The pill only ever travels within the list, so scoping
+            projection to the Tabs wrapper is always correct. */}
+        <motion.div layoutRoot className={className}>
+          {children}
+        </motion.div>
+      </TabsCtx.Provider>
+    </MotionConfig>
+  );
+}
+
+const listClasses: Record<Variant, string> = {
+  pill: "inline-flex items-center gap-1 rounded-full bg-card p-1",
+  underline: "inline-flex items-center gap-1 border-b border-border",
+  segment: "inline-flex items-center gap-0 rounded-lg bg-card p-0.5",
+};
+
+export function TabsList({ children, className }: { children: ReactNode; className?: string }) {
+  const { variant } = useTabs();
+  return (
+    <div role="tablist" className={cn(listClasses[variant], className)}>
+      {children}
+    </div>
+  );
+}
+
+export function TabsTrigger({
+  value,
+  children,
+  className,
+  indicatorClassName,
+}: {
+  value: string;
+  children: ReactNode;
+  className?: string;
+  indicatorClassName?: string;
+}) {
+  const { value: current, setValue, layoutId, variant } = useTabs();
+  const active = current === value;
+
+  if (variant === "underline") {
+    return (
+      <button
+        type="button"
+        role="tab"
+        aria-selected={active}
+        onClick={() => setValue(value)}
+        className={cn(
+          "relative isolate px-3 pb-2.5 pt-1 -mb-px text-sm font-medium transition-colors min-h-[44px] inline-flex items-center",
+          active ? "text-foreground" : "text-muted-foreground hover:text-foreground",
+          className,
+        )}
+      >
+        {children}
+        {active ? (
+        <motion.span
+          layoutId={layoutId}
+          layout="position"
+          className={cn(
+            "absolute -bottom-px left-0 right-0 h-px bg-primary",
+            indicatorClassName,
+          )}
+        />
+        ) : null}
+      </button>
+    );
+  }
+
+  const radius = variant === "pill" ? "rounded-full" : "rounded-md";
+
+  return (
+    <div className="relative">
+      {active ? (
+        <motion.span
+          layoutId={layoutId}
+          layout="position"
+          style={{ borderRadius: variant === "pill" ? 9999 : 8 }}
+          className={cn(
+            "absolute inset-0 bg-primary",
+            radius,
+            indicatorClassName,
+          )}
+        />
+      ) : null}
+      <button
+        type="button"
+        role="tab"
+        aria-selected={active}
+        onClick={() => setValue(value)}
+        className={cn(
+          "relative z-10 inline-flex items-center justify-center whitespace-nowrap bg-transparent px-3.5 py-1.5 text-sm font-medium outline-none",
+          "transition-colors",
+          active
+            ? "text-primary-foreground"
+            : "text-muted-foreground hover:text-foreground",
+          radius,
+          className,
+        )}
+      >
+        {children}
+      </button>
+    </div>
+  );
+}
+
+export function TabsContent({ value, children, className }: { value: string; children: ReactNode; className?: string }) {
+  const { value: current } = useTabs();
+  const reduce = useReducedMotion();
+  const active = current === value;
+  // Inactive panels stay mounted but hidden, so their content (e.g. source
+  // code) is present in the server-rendered HTML for crawlers and assistive
+  // tech, instead of being dropped from the DOM.
+  if (!active) {
+    return (
+      <div hidden className={className}>
+        {children}
+      </div>
+    );
+  }
+  return (
+    <motion.div
+      key={value}
+      initial={{ opacity: 0, y: reduce ? 0 : 4 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.18, ease: EASE_OUT }}
+      className={cn("mt-4", className)}
+    >
+      {children}
+    </motion.div>
+  );
+}

package/components/motion/text-cascade.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import { ActionSwapText } from "./action-swap";
+
+export interface TextCascadeProps {
+  /** Current text. Changing it cascades the letters to the new value. */
+  text: string;
+  className?: string;
+}
+
+/**
+ * Letter-by-letter slot roll for standalone text — the old letters drop away
+ * as the new ones land, left to right. Same motion as the action-swap
+ * cascade variant, with a text-first API.
+ */
+export function TextCascade({ text, className }: TextCascadeProps) {
+  return (
+    <ActionSwapText value={text} animation="cascade" className={className}>
+      {text}
+    </ActionSwapText>
+  );
+}

package/components/motion/text-reveal.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { motion, type Transition, useInView, useReducedMotion } from "motion/react";
+import { useRef, type ElementType, type ReactNode } from "react";
+import { EASE_OUT } from "@/lib/ease";
+import { cn } from "@/lib/utils";
+
+type SplitMode = "word" | "char";
+
+export interface TextRevealProps {
+  text: string | string[];
+  as?: ElementType;
+  className?: string;
+  split?: SplitMode;
+  stagger?: number;
+  delay?: number;
+  blur?: number;
+  yOffset?: string | number;
+  spring?: { stiffness?: number; damping?: number; mass?: number };
+  once?: boolean;
+  whileInView?: boolean;
+  children?: ReactNode;
+}
+
+const DEFAULT_SPRING = { stiffness: 140, damping: 26, mass: 1.2 };
+
+type WordGroup = { text: string; trailing: string };
+
+/**
+ * One tokenizer for both modes: a line becomes the words it is made of, each
+ * carrying the whitespace that follows it. Word mode animates a group at a
+ * time, char mode the characters inside one — so the two can't drift apart on
+ * what counts as a word or where a space belongs. Runs of whitespace and tabs
+ * survive as their own group rather than collapsing.
+ */
+function toWordGroups(line: string): WordGroup[] {
+  const chunks = line.match(/\S+\s*|\s+/g) ?? [];
+  return chunks.map((chunk) => {
+    const text = chunk.replace(/\s+$/, "");
+    return { text, trailing: chunk.slice(text.length) };
+  });
+}
+
+export function TextReveal({
+  text,
+  as: Comp = "span",
+  className,
+  split = "word",
+  stagger = 0.09,
+  delay = 0,
+  blur = 12,
+  yOffset = "40%",
+  spring,
+  once = true,
+  whileInView = false,
+  children,
+}: TextRevealProps) {
+  const ref = useRef<HTMLElement>(null);
+  const inView = useInView(ref, { once, amount: 0.4 });
+  const reduce = useReducedMotion();
+  const shouldAnimate = whileInView ? inView : true;
+
+  const lines = Array.isArray(text) ? text : [text];
+  const s = { ...DEFAULT_SPRING, ...spring };
+
+  let unitIndex = 0;
+  const lineCounts = new Map<string, number>();
+
+  return (
+    <Comp ref={ref} className={cn("block", className)}>
+      {lines.map((line) => {
+        const lineCount = lineCounts.get(line) ?? 0;
+        lineCounts.set(line, lineCount + 1);
+        const lineKey = `${line}-${lineCount}`;
+        const unitCounts = new Map<string, number>();
+
+        const renderUnit = (unit: string) => {
+          const d = delay + unitIndex * stagger;
+          unitIndex += 1;
+          const unitCount = unitCounts.get(unit) ?? 0;
+          unitCounts.set(unit, unitCount + 1);
+          const unitKey = `${unit}-${unitCount}`;
+          const initial = reduce
+            ? { opacity: 0 }
+            : { y: yOffset, opacity: 0, filter: `blur(${blur}px)` };
+          const animate = shouldAnimate
+            ? reduce
+              ? { opacity: 1 }
+              : { y: 0, opacity: 1, filter: "blur(0px)" }
+            : initial;
+          const transition: Transition = reduce
+            ? { opacity: { duration: 0.25, ease: EASE_OUT, delay: d * 0.3 } }
+            : {
+                y: { type: "spring" as const, ...s, delay: d },
+                opacity: { duration: 0.7, ease: EASE_OUT, delay: d },
+                filter: { duration: 0.9, ease: EASE_OUT, delay: d },
+              };
+          return (
+            <motion.span
+              key={unitKey}
+              initial={initial}
+              animate={animate}
+              transition={transition}
+              // `whitespace-pre` is load-bearing: a unit's trailing space is
+              // inside an inline-block and would otherwise collapse to zero
+              // width, running every word together.
+              className="inline-block whitespace-pre will-change-transform"
+            >
+              {unit}
+            </motion.span>
+          );
+        };
+
+        const groups = toWordGroups(line);
+        const groupCounts = new Map<string, number>();
+
+        return (
+          <span key={lineKey} className="block">
+            {groups.map((group) => {
+              const whole = group.text + group.trailing;
+              // Characters animate one at a time, but each word (plus the
+              // space that follows it) sits in its own inline-block so a long
+              // line wraps between words instead of mid-word.
+              if (split !== "char") return renderUnit(whole);
+
+              const groupCount = groupCounts.get(whole) ?? 0;
+              groupCounts.set(whole, groupCount + 1);
+              return (
+                <span
+                  key={`${whole}-${groupCount}`}
+                  className="inline-block whitespace-pre"
+                >
+                  {Array.from(whole).map((char) => renderUnit(char))}
+                </span>
+              );
+            })}
+          </span>
+        );
+      })}
+      {children}
+    </Comp>
+  );
+}

package/components/motion/text-scramble.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import { useReducedMotion } from "motion/react";
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+} from "react";
+import { cn } from "@/lib/utils";
+
+const DEFAULT_GLYPHS = "ABCDEFGHJKLMNPQRSTUVWXYZ0123456789#%&@$?/";
+
+export interface TextScrambleProps {
+  /** Final text revealed by the scramble animation. */
+  text: string;
+  /** Maximum animation duration in milliseconds. */
+  duration?: number;
+  /** Characters sampled while unresolved positions are scrambling. */
+  glyphs?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/** Character scramble that resolves to `text` and respects reduced motion. */
+export function TextScramble({
+  text,
+  duration,
+  glyphs = DEFAULT_GLYPHS,
+  className,
+  style,
+}: TextScrambleProps) {
+  const reduce = useReducedMotion() ?? false;
+  const [display, setDisplay] = useState(text);
+  const mounted = useRef(false);
+
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      setDisplay(text);
+      return;
+    }
+
+    if (reduce || !glyphs) {
+      setDisplay(text);
+      return;
+    }
+
+    const characters = text.split("");
+    const startedAt = performance.now();
+    const animationDuration = duration
+      ?? Math.min(760, Math.max(420, characters.length * 32));
+    let frame = 0;
+    let lastUpdate = 0;
+
+    const animate = (now: number) => {
+      if (now - lastUpdate >= 40) {
+        lastUpdate = now;
+        const progress = Math.min((now - startedAt) / animationDuration, 1);
+        const settled = Math.floor(progress * characters.length);
+        setDisplay(characters.map((character, index) => {
+          if (index < settled || character === " ") return character;
+          return glyphs[Math.floor(Math.random() * glyphs.length)];
+        }).join(""));
+      }
+
+      if (now - startedAt < animationDuration) {
+        frame = requestAnimationFrame(animate);
+      } else {
+        setDisplay(text);
+      }
+    };
+
+    frame = requestAnimationFrame(animate);
+    return () => cancelAnimationFrame(frame);
+  }, [duration, glyphs, reduce, text]);
+
+  return (
+    <span className={cn("inline-block whitespace-pre", className)} style={style}>
+      <span className="sr-only">{text}</span>
+      <span aria-hidden="true">{reduce ? text : display}</span>
+    </span>
+  );
+}