@dowel-ui/react 0.7.0 → 0.8.0

package/src/components/effect-button/effect-button.tsx

@@ -0,0 +1,310 @@
+// Ported from amicro "Buttons" (MIT, © 2026 Syed Subhan Uddin) and the SmoothUI Clip Corners Button (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { cva } from "class-variance-authority";
+import { cloneElement, isValidElement, type ReactElement, type ReactNode } from "react";
+
+import { Button, type ButtonProps } from "@/components/button";
+import { mirrorForDirection } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * One mechanism, eight effects (ADR 0014). Every effect is a response to the
+ * button being hovered OR keyboard-focused — never hover alone, or a keyboard
+ * user gets a flatter control than a mouse user.
+ *
+ * - Transitions are Tailwind `group-hover/effect:` + `group-focus-visible/effect:`
+ *   pairs on the parts, so a consumer can restyle any of them.
+ * - One-shot and looping motions (pulse, shake, glare, ring) are keyframes in
+ *   the hoisted stylesheet, keyed on `[data-slot][data-effect]`. Their
+ *   resting state is the "off" frame, so when the reduced-motion blanket
+ *   collapses an animation to one instant iteration, the part simply rests.
+ * - Nothing waits on a JavaScript timer: the effect is the CSS state.
+ */
+
+const PREFIX = "dowel-effect-button";
+
+/** A duration scaled by --motion-scale: decoration stops under reduced motion. */
+function scaled(ms: number): string {
+  return `calc(${String(ms)}ms * var(--motion-scale, 1))`;
+}
+
+/** A rule that applies while the root is hovered (on hover devices) or focus-visible. */
+function whenActive(effect: string, part: string, declarations: string): string {
+  const root = `[data-slot=effect-button][data-effect=${effect}]`;
+  const child = `>[data-slot=effect-button-${part}]`;
+  return (
+    `@media (hover:hover){${root}:hover${child}{${declarations}}}` +
+    `${root}:focus-visible${child}{${declarations}}`
+  );
+}
+
+const STYLES = `
+@keyframes ${PREFIX}-pulse{0%,100%{scale:1}50%{scale:1.25}}
+@keyframes ${PREFIX}-shake{0%,100%{translate:0 0;rotate:0deg}25%,75%{translate:0 -2px;rotate:-10deg}50%{translate:0 0;rotate:10deg}}
+@keyframes ${PREFIX}-glare{0%{translate:-100% 0}46%,100%{translate:100% 0}}
+@keyframes ${PREFIX}-ring{from{opacity:1;scale:1}to{opacity:0;scale:1.15}}
+${whenActive("pulse", "icon", `animation:${PREFIX}-pulse ${scaled(400)} ease-in-out`)}
+${whenActive("shake", "icon", `animation:${PREFIX}-shake ${scaled(400)} ease-in-out`)}
+${whenActive("glare", "glare", `animation:${PREFIX}-glare ${scaled(1850)} ease-in-out infinite`)}
+${whenActive("expand-ring", "ring", `animation:${PREFIX}-ring ${scaled(600)} ease-out`)}
+`;
+
+export const effectButtonEffects = [
+  "slide-arrow",
+  "pulse",
+  "rotate",
+  "shake",
+  "glare",
+  "text-reveal",
+  "expand-ring",
+  "clip-corners",
+] as const;
+
+export type EffectButtonEffect = (typeof effectButtonEffects)[number];
+
+export type EffectButtonTone =
+  "current" | "primary" | "success" | "warning" | "destructive" | "info";
+
+const effectButtonVariants = cva("group/effect relative", {
+  variants: {
+    effect: {
+      // The icons carry their own spacing so the leaving one can take its gap with it.
+      "slide-arrow": "gap-0",
+      pulse: "",
+      rotate: "",
+      shake: "",
+      glare: "overflow-hidden",
+      "text-reveal": "",
+      "expand-ring": "",
+      "clip-corners": "",
+    },
+  },
+  defaultVariants: { effect: "slide-arrow" },
+});
+
+/** The colour a toned part takes while the button is active. Literal, so Tailwind can see it. */
+const TONE: Record<EffectButtonTone, string> = {
+  current: "",
+  primary: "group-hover/effect:text-primary group-focus-visible/effect:text-primary",
+  success: "group-hover/effect:text-success group-focus-visible/effect:text-success",
+  warning: "group-hover/effect:text-warning group-focus-visible/effect:text-warning",
+  destructive:
+    "group-hover/effect:text-destructive group-focus-visible/effect:text-destructive",
+  info: "group-hover/effect:text-info group-focus-visible/effect:text-info",
+};
+
+const settle = "duration-[var(--duration-slow)] ease-[var(--ease-overshoot)]";
+const fade = "duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]";
+
+/** Classes for the leading icon wrapper, per effect. */
+const ICON: Record<EffectButtonEffect, string> = {
+  "slide-arrow": cn(
+    "me-2 grid grid-cols-[1fr] transition-[grid-template-columns,margin,opacity,translate]",
+    settle,
+    "group-hover/effect:me-0 group-hover/effect:-translate-x-2.5 group-hover/effect:grid-cols-[0fr] group-hover/effect:opacity-0 group-hover/effect:rtl:translate-x-2.5",
+    "group-focus-visible/effect:me-0 group-focus-visible/effect:-translate-x-2.5 group-focus-visible/effect:grid-cols-[0fr] group-focus-visible/effect:opacity-0 group-focus-visible/effect:rtl:translate-x-2.5",
+  ),
+  pulse: cn(
+    "transition-colors [&_svg]:transition-[fill,color]",
+    fade,
+    "group-hover/effect:[&_svg]:fill-current group-focus-visible/effect:[&_svg]:fill-current",
+  ),
+  rotate: cn(
+    "transition-[rotate]",
+    settle,
+    "group-hover/effect:rotate-180 group-focus-visible/effect:rotate-180",
+  ),
+  shake: cn("transition-colors", fade),
+  glare: "",
+  "text-reveal": cn(
+    "transition-[rotate]",
+    settle,
+    "group-hover/effect:rotate-45 group-focus-visible/effect:rotate-45",
+  ),
+  "expand-ring": cn(
+    "transition-[scale]",
+    settle,
+    "group-hover/effect:scale-110 group-focus-visible/effect:scale-110",
+  ),
+  "clip-corners": "",
+};
+
+const TRAILING = cn(
+  "ms-0 grid translate-x-2.5 grid-cols-[0fr] opacity-0 transition-[grid-template-columns,margin,opacity,translate] rtl:-translate-x-2.5",
+  settle,
+  "group-hover/effect:ms-2 group-hover/effect:translate-x-0 group-hover/effect:grid-cols-[1fr] group-hover/effect:opacity-100 group-hover/effect:rtl:translate-x-0",
+  "group-focus-visible/effect:ms-2 group-focus-visible/effect:translate-x-0 group-focus-visible/effect:grid-cols-[1fr] group-focus-visible/effect:opacity-100 group-focus-visible/effect:rtl:translate-x-0",
+);
+
+const REVEAL = cn(
+  "block transition-[translate]",
+  settle,
+  "group-hover/effect:-translate-y-full group-focus-visible/effect:-translate-y-full",
+);
+
+/*
+ * The corners move inward by animating their logical inset, so the travel
+ * follows the reading direction without a per-direction translate. Each
+ * triangle is drawn for LTR and mirrored in RTL, where start and end swap.
+ */
+const CORNER_MOVE = cn("transition-[top,bottom,inset-inline-start,inset-inline-end]", settle);
+const CORNERS = [
+  {
+    name: "top-start",
+    className:
+      "top-1.5 start-1.5 [clip-path:polygon(0_0,100%_0,0_100%)] group-hover/effect:top-2.5 group-hover/effect:start-2.5 group-focus-visible/effect:top-2.5 group-focus-visible/effect:start-2.5",
+  },
+  {
+    name: "top-end",
+    className:
+      "top-1.5 end-1.5 [clip-path:polygon(0_0,100%_0,100%_100%)] group-hover/effect:top-2.5 group-hover/effect:end-2.5 group-focus-visible/effect:top-2.5 group-focus-visible/effect:end-2.5",
+  },
+  {
+    name: "bottom-start",
+    className:
+      "bottom-1.5 start-1.5 [clip-path:polygon(0_0,0_100%,100%_100%)] group-hover/effect:bottom-2.5 group-hover/effect:start-2.5 group-focus-visible/effect:bottom-2.5 group-focus-visible/effect:start-2.5",
+  },
+  {
+    name: "bottom-end",
+    className:
+      "bottom-1.5 end-1.5 [clip-path:polygon(100%_0,100%_100%,0_100%)] group-hover/effect:bottom-2.5 group-hover/effect:end-2.5 group-focus-visible/effect:bottom-2.5 group-focus-visible/effect:end-2.5",
+  },
+] as const;
+
+export interface EffectButtonProps extends ButtonProps {
+  /** The micro-interaction played while the button is hovered or keyboard-focused. */
+  effect?: EffectButtonEffect;
+  /** Leading icon. Decorative: the label (or `aria-label`) names the button. */
+  icon?: ReactNode;
+  /**
+   * Icon that slides in at the end for `effect="slide-arrow"`. It is treated as
+   * directional and mirrored in right-to-left layouts.
+   */
+  trailingIcon?: ReactNode;
+  /** Colour the icon (`pulse`) or icon and label (`shake`) take while active. */
+  tone?: EffectButtonTone;
+}
+
+/** A Button with a hover and focus micro-interaction on its icon or surface. */
+export function EffectButton({
+  effect = "slide-arrow",
+  icon,
+  trailingIcon,
+  tone = "current",
+  asChild = false,
+  loading = false,
+  className,
+  children,
+  ...props
+}: EffectButtonProps) {
+  // Pulse tones its icon; shake tones icon and label, as a warning of what the click does.
+  const toned = effect === "pulse" || effect === "shake" ? TONE[tone] : "";
+  const labelToned = effect === "shake" ? TONE[tone] : "";
+
+  function inner(label: ReactNode): ReactNode {
+    const hasLabel = label !== undefined && label !== null && label !== false && label !== "";
+    return (
+      <>
+        {icon && !loading ? (
+          <span
+            data-slot="effect-button-icon"
+            aria-hidden="true"
+            className={cn("inline-flex shrink-0", ICON[effect], toned)}
+          >
+            {effect === "slide-arrow" ? (
+              <span className="flex min-w-0 overflow-hidden">{icon}</span>
+            ) : (
+              icon
+            )}
+          </span>
+        ) : null}
+        {hasLabel ? (
+          effect === "text-reveal" ? (
+            <span
+              data-slot="effect-button-label"
+              className="relative inline-flex overflow-hidden"
+            >
+              <span className={REVEAL}>{label}</span>
+              <span aria-hidden="true" className={cn("absolute start-0 top-full", REVEAL)}>
+                {label}
+              </span>
+            </span>
+          ) : (
+            <span
+              data-slot="effect-button-label"
+              className={cn("transition-colors", fade, labelToned)}
+            >
+              {label}
+            </span>
+          )
+        ) : null}
+        {effect === "slide-arrow" && trailingIcon ? (
+          <span data-slot="effect-button-trailing-icon" aria-hidden="true" className={TRAILING}>
+            <span className={cn("flex min-w-0 overflow-hidden", mirrorForDirection)}>
+              {trailingIcon}
+            </span>
+          </span>
+        ) : null}
+        {effect === "glare" ? (
+          <span
+            data-slot="effect-button-glare"
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-0 z-10 -translate-x-full bg-[linear-gradient(110deg,transparent_35%,color-mix(in_oklab,currentColor_22%,transparent)_50%,transparent_65%)]"
+          />
+        ) : null}
+        {effect === "expand-ring" ? (
+          <span
+            data-slot="effect-button-ring"
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-0 rounded-[inherit] border border-current/25 opacity-0"
+          />
+        ) : null}
+        {effect === "clip-corners"
+          ? CORNERS.map((corner) => (
+              <span
+                key={corner.name}
+                data-slot="effect-button-corner"
+                data-corner={corner.name}
+                aria-hidden="true"
+                className={cn(
+                  "pointer-events-none absolute size-2 bg-current",
+                  mirrorForDirection,
+                  CORNER_MOVE,
+                  corner.className,
+                )}
+              />
+            ))
+          : null}
+      </>
+    );
+  }
+
+  // With asChild the consumer's element becomes the button, so the parts go
+  // inside it rather than beside it: Slot accepts exactly one child.
+  let content: ReactNode;
+  if (asChild && isValidElement<{ children?: ReactNode }>(children)) {
+    const child = children as ReactElement<{ children?: ReactNode }>;
+    content = cloneElement(child, undefined, inner(child.props.children));
+  } else {
+    content = inner(children);
+  }
+
+  return (
+    <>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <Button
+        data-slot="effect-button"
+        data-effect={effect}
+        asChild={asChild}
+        loading={loading}
+        className={cn(effectButtonVariants({ effect }), className)}
+        {...props}
+      >
+        {content}
+      </Button>
+    </>
+  );
+}
+
+export { effectButtonVariants };

package/src/components/effect-button/index.ts

@@ -0,0 +1,8 @@
+export {
+  EffectButton,
+  effectButtonEffects,
+  effectButtonVariants,
+  type EffectButtonEffect,
+  type EffectButtonProps,
+  type EffectButtonTone,
+} from "./effect-button";

package/src/components/effect-button/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "effect-button",
+  title: "Effect Button",
+  description:
+    "A Button with a hover and focus micro-interaction — slide-arrow, pulse, rotate, shake, glare, text reveal, expanding ring or clip corners.",
+  category: "form",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["button"],
+  files: ["effect-button.tsx"],
+  a11y:
+    "Every effect plays on keyboard focus-visible as well as hover. Icons and decorative " +
+    "layers are aria-hidden, and text-reveal's duplicate label is hidden so the name is read " +
+    "once. Colour (tone) never carries meaning on its own: the label does. Effects stop under " +
+    "reduced motion. Inherits Button's loading and disabled behaviour.",
+});

package/src/components/escape-button/escape-button.tsx

@@ -0,0 +1,232 @@
+"use client";
+
+// Ported from bencho Escape button (MIT, © 2026 Lorenzo Cabra). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type FocusEvent,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+
+import { Button, type ButtonProps } from "@/components/button";
+import { cn } from "@/lib/utils";
+
+/*
+ * A novelty button that scoots away from an approaching mouse, and gives up
+ * after a few escapes.
+ *
+ * The game is for a mouse or pen only, and it is never in the way:
+ *
+ * - It never moves for touch, a coarse pointer, reduced motion, or while it has
+ *   focus — so a keyboard user can always Tab to it and press it at once.
+ * - It gives up after `patience` escapes: it returns home, reads "Fine." and
+ *   stays put until it has been pressed.
+ * - A press always goes through, in every state; the dodging is visual only.
+ *
+ * Like MagneticButton, the offset is written to the element's style from
+ * pointermove (no re-render per move) and CSS transitions do the easing: a
+ * quick ease-out while fleeing, a soft overshoot drifting home.
+ */
+
+const escapeButtonVariants = cva(
+  cn(
+    "h-14 rounded-full px-7.5 text-xl font-normal tracking-[-0.012em]",
+    "bg-foreground/6 text-foreground/72 hover:bg-foreground/6 hover:text-foreground/90",
+    "data-[caught]:text-foreground",
+    "data-[done]:bg-foreground data-[done]:text-background data-[done]:hover:bg-foreground data-[done]:hover:text-background",
+    "transition-[transform,background-color,color,scale]",
+    "duration-[var(--duration-slower),var(--duration-fast),var(--duration-fast),var(--duration-fast)]",
+    "ease-[var(--ease-overshoot),var(--ease-out-quint),var(--ease-out-quint),var(--ease-out-quint)]",
+    "data-[escape=flee]:duration-[var(--duration-fast)] data-[escape=flee]:ease-[var(--ease-out-quint)]",
+  ),
+  {
+    variants: {
+      /** A hairline ring — the source's Stroke switch. */
+      stroke: {
+        true: "shadow-[inset_0_0_0_1px_var(--color-border)]",
+        false: "",
+      },
+    },
+    defaultVariants: { stroke: false },
+  },
+);
+
+/** Pointers the game never runs for. */
+function dodgeAllowed(pointerType: string): boolean {
+  if (pointerType === "touch") return false;
+  if (typeof window.matchMedia !== "function") return true;
+  return !(
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches ||
+    window.matchMedia("(pointer: coarse)").matches
+  );
+}
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+export interface EscapeButtonProps
+  extends Omit<ButtonProps, "asChild" | "variant">, VariantProps<typeof escapeButtonVariants> {
+  /** Escapes before it gives up and stays put. */
+  patience?: number;
+  /** How close, in pixels, the pointer gets before it flees. */
+  radius?: number;
+  /** Flee strength, 0–100. 0 turns the game off. */
+  skittishness?: number;
+  /** The label once it has given up. */
+  caughtLabel?: ReactNode;
+  /** Milliseconds the pressed state shows before the game resets. */
+  resetAfter?: number;
+}
+
+/** A button that dodges an approaching mouse — until it gives up. */
+export function EscapeButton({
+  className,
+  stroke,
+  patience = 4,
+  radius = 120,
+  skittishness = 55,
+  caughtLabel = "Fine.",
+  resetAfter = 600,
+  disabled,
+  children = "Touch me",
+  onClick,
+  onFocus,
+  onBlur,
+  ref,
+  ...props
+}: EscapeButtonProps) {
+  const buttonRef = useRef<HTMLButtonElement | null>(null);
+  const offset = useRef({ x: 0, y: 0 });
+  const near = useRef(false);
+  const escapes = useRef(0);
+  const focused = useRef(false);
+  const [caught, setCaught] = useState(false);
+  const [done, setDone] = useState(false);
+  const inert = Boolean(disabled) || caught || done || skittishness <= 0;
+
+  const place = useCallback((x: number, y: number, fleeing: boolean) => {
+    const element = buttonRef.current;
+    if (!element) return;
+    offset.current = { x, y };
+    element.dataset.escape = fleeing ? "flee" : "rest";
+    element.style.transform =
+      x === 0 && y === 0 ? "" : `translate(${String(x)}px, ${String(y)}px)`;
+  }, []);
+
+  const goHome = useCallback(() => {
+    if (offset.current.x !== 0 || offset.current.y !== 0) place(0, 0, false);
+  }, [place]);
+
+  useEffect(() => {
+    if (inert) {
+      near.current = false;
+      goHome();
+      return;
+    }
+
+    function handleMove(event: PointerEvent) {
+      const element = buttonRef.current;
+      if (!element || focused.current || !dodgeAllowed(event.pointerType)) return;
+
+      // Measure where it sits at rest, not where it has fled to, or it would
+      // chase its own displacement.
+      const rect = element.getBoundingClientRect();
+      const restLeft = rect.left - offset.current.x;
+      const restTop = rect.top - offset.current.y;
+      const dx = restLeft + rect.width / 2 - event.clientX;
+      const dy = restTop + rect.height / 2 - event.clientY;
+      const distance = Math.hypot(dx, dy);
+
+      if (distance >= radius) {
+        if (near.current) {
+          near.current = false;
+          escapes.current += 1;
+          if (escapes.current >= patience) setCaught(true);
+        }
+        goHome();
+        return;
+      }
+
+      near.current = true;
+      // The push grows steeply as the pointer closes in: ~14px at half the
+      // radius, ~37px at a quarter, at the default strength.
+      const closeness = 1 - distance / radius;
+      const push = closeness ** 2.5 * radius * skittishness * 0.012;
+      const unit = distance === 0 ? { x: 0, y: -1 } : { x: dx / distance, y: dy / distance };
+      let x = unit.x * push;
+      let y = unit.y * push;
+
+      const field = element.parentElement?.getBoundingClientRect();
+      if (field && field.width > 0 && field.height > 0) {
+        x = clamp(x, field.left - restLeft, field.right - (restLeft + rect.width));
+        y = clamp(y, field.top - restTop, field.bottom - (restTop + rect.height));
+      }
+      place(x, y, true);
+    }
+
+    window.addEventListener("pointermove", handleMove, { passive: true });
+    return () => {
+      window.removeEventListener("pointermove", handleMove);
+    };
+  }, [inert, radius, patience, skittishness, place, goHome]);
+
+  useEffect(() => {
+    if (!done) return;
+    const timer = setTimeout(() => {
+      escapes.current = 0;
+      setDone(false);
+      setCaught(false);
+    }, resetAfter);
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [done, resetAfter]);
+
+  function handleClick(event: MouseEvent<HTMLButtonElement>) {
+    onClick?.(event);
+    if (event.defaultPrevented) return;
+    setDone(true);
+  }
+
+  function handleFocus(event: FocusEvent<HTMLButtonElement>) {
+    onFocus?.(event);
+    // Focus pins it in place: whatever is focused must stay where it is.
+    focused.current = true;
+    goHome();
+  }
+
+  function handleBlur(event: FocusEvent<HTMLButtonElement>) {
+    onBlur?.(event);
+    focused.current = false;
+  }
+
+  return (
+    <Button
+      ref={(node) => {
+        buttonRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      }}
+      variant="ghost"
+      data-slot="escape-button"
+      data-escape="rest"
+      data-caught={caught || undefined}
+      data-done={done || undefined}
+      disabled={disabled}
+      className={cn(escapeButtonVariants({ stroke }), className)}
+      onClick={handleClick}
+      onFocus={handleFocus}
+      onBlur={handleBlur}
+      {...props}
+    >
+      {caught ? caughtLabel : children}
+    </Button>
+  );
+}
+
+export { escapeButtonVariants };

package/src/components/escape-button/index.ts

@@ -0,0 +1 @@
+export { EscapeButton, escapeButtonVariants, type EscapeButtonProps } from "./escape-button";

package/src/components/escape-button/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "escape-button",
+  title: "Escape Button",
+  description:
+    "A novelty button that scoots away from an approaching mouse, then gives up after a few escapes.",
+  category: "effects",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["button"],
+  files: ["escape-button.tsx"],
+  a11y:
+    "The dodging is a mouse-and-pen game only: it never moves for touch, a coarse pointer, reduced motion, " +
+    "or while the button has focus, so keyboard users can Tab to it and press it at once. It gives up after " +
+    "`patience` escapes (4 by default) and stays put, and a press always goes through in every state — the " +
+    "movement is visual, never a lock. It is a real button with its visible label as its name.",
+});