# Integrate `Dial` from Motion Garden

You are helping me add the **Dial** component to an existing project.
Everything you need is below — full source, dependencies, props and the
behavioural contract. Read it all before writing anything.

- **Component:** Dial
- **Category:** Micro-interactions
- **Summary:** A machined rotary knob: angular drag with detents you can feel on the way past, inertia on a flick, and a spring that settles into the nearest stop. The angle lives in a motion value rather than in React state, because a drag writes it sixty times a second and a spring more often than that, so the only thing React holds is the detent index, and only when that integer actually changes. Arrow keys step through the same spring the hand does, so the keyboard is not a second, worse path to the same control.
- **Reference:** https://motion-garden.netlify.app/components/dial
- **Full catalog (for you, the agent):** https://motion-garden.netlify.app/llms.txt

## Stack this source assumes

- React 19 with the Next.js App Router (never the `pages/` directory)
- TypeScript, strict
- Tailwind CSS v4, CSS-first config (utilities are inline; no `tailwind.config` needed)

If my project differs, adapt the integration — but do not rewrite the animation math to suit a different stack. Ask me first.

## Dependencies

```bash
bun add motion
```

## Design tokens this source uses

Some classes in the source are Motion Garden theme tokens, not stock Tailwind (`text-ink`, `bg-panel`, `font-display` and the like). Without them, parts of the component render unstyled. Add this to my global CSS, after the Tailwind import:

```css
@theme {
  --font-display: "Space Mono", ui-monospace, "SFMono-Regular", monospace;
}

@theme inline {
  --color-ink-mute: var(--sg-ink-mute);
}

:root {
  --sg-ink-mute: #878e97;
}

.dark {
  --sg-ink-mute: #6c737c;
}
```

The values are Motion Garden's own light and dark themes. If my project already has tokens for these roles, point the `--sg-*` variables at mine instead and tell me which you mapped. `.dark` assumes class-based dark mode — adapt the selector to how my project switches themes.

`font-display` expects Space Mono, and this CSS only names it. Load the font (with `next/font/google`, for example) or put my own display face first in the stack; until then it falls back to the system monospace.

## Files to create

One file. Paths are as shipped; the component may live anywhere in my project, but keep every peer file at the exact path shown so the import aliases resolve.

### 1. `components/registry/dial/dial.tsx`

```tsx
"use client";

import { memo, useCallback, useRef, useState } from "react";
import {
  animate,
  motion,
  useMotionValue,
  useMotionValueEvent,
} from "motion/react";

export type DialTicks = "line" | "dot" | "none";

interface DialProps {
  detents?: number;
  sweep?: number;
  stiffness?: number;
  damping?: number;
  inertia?: number;
  detentPull?: number;
  ticks?: DialTicks;
  readout?: boolean;
  accent?: string;
  size?: number;
  reducedMotion?: boolean;
  className?: string;
}

const GIVE = 16;

const SAMPLES = 4;

const DEG = 180 / Math.PI;

const arc = (a: number, b: number) => {
  let d = (b - a) % 360;
  if (d > 180) d -= 360;
  if (d < -180) d += 360;
  return d;
};

const rubber = (over: number) => GIVE * (1 - Math.exp(-over / GIVE));

const Dial = memo(
  ({
    detents = 12,
    sweep = 270,
    stiffness = 380,
    damping = 26,
    inertia = 0.6,
    detentPull = 0.5,
    ticks = "line",
    readout = true,
    accent = "#a855f7",
    size = 160,
    reducedMotion = false,
    className,
  }: DialProps) => {
    const stops = Math.max(2, Math.round(detents));
    const half = sweep / 2;
    const spacing = sweep / (stops - 1);

    const angle = useMotionValue(-half);
    const [index, setIndex] = useState(0);

    const drag = useRef({
      active: false,
      raw: -half,
      last: 0,
      samples: [] as Array<{ t: number; a: number }>,
    });

    const angleFor = useCallback(
      (i: number) => -half + i * spacing,
      [half, spacing],
    );

    const indexFor = useCallback(
      (a: number) =>
        Math.min(stops - 1, Math.max(0, Math.round((a + half) / spacing))),
      [half, spacing, stops],
    );

    useMotionValueEvent(angle, "change", (v) => {
      const i = indexFor(v);
      setIndex((prev) => (prev === i ? prev : i));
    });

    const settle = useCallback(
      (target: number, velocity = 0) => {
        const clamped = Math.min(half, Math.max(-half, target));
        if (reducedMotion) {
          angle.set(clamped);
          return;
        }
        animate(angle, clamped, {
          type: "spring",
          stiffness,
          damping,
          velocity,
          restDelta: 0.01,
        });
      },
      [angle, damping, half, reducedMotion, stiffness],
    );

    const pointerAngle = (
      event: React.PointerEvent<SVGSVGElement>,
    ): number => {
      const rect = event.currentTarget.getBoundingClientRect();
      const dx = event.clientX - (rect.left + rect.width / 2);
      const dy = event.clientY - (rect.top + rect.height / 2);
      return Math.atan2(dx, -dy) * DEG;
    };

    const onPointerDown = (event: React.PointerEvent<SVGSVGElement>) => {
      event.currentTarget.setPointerCapture(event.pointerId);
      const d = drag.current;
      d.active = true;
      d.raw = angle.get();
      d.last = pointerAngle(event);
      d.samples = [{ t: event.timeStamp, a: d.raw }];
    };

    const onPointerMove = (event: React.PointerEvent<SVGSVGElement>) => {
      const d = drag.current;
      if (!d.active) return;

      const now = pointerAngle(event);
      d.raw += arc(d.last, now);
      d.last = now;

      let shown = d.raw;
      if (shown > half) shown = half + rubber(shown - half);
      else if (shown < -half) shown = -half - rubber(-half - shown);

      if (detentPull > 0) {
        const nearest = angleFor(indexFor(shown));
        const gap = nearest - shown;
        const strength = detentPull * Math.max(0, 1 - Math.abs(gap) / (spacing * 0.5));
        shown += gap * strength;
      }

      angle.set(shown);

      d.samples.push({ t: event.timeStamp, a: shown });
      if (d.samples.length > SAMPLES) d.samples.shift();
    };

    const onPointerUp = () => {
      const d = drag.current;
      if (!d.active) return;
      d.active = false;

      const first = d.samples[0];
      const last = d.samples[d.samples.length - 1];
      const span = last && first ? last.t - first.t : 0;
      const velocity = span > 8 ? ((last.a - first.a) / span) * 1000 : 0;

      const thrown = angle.get() + velocity * inertia * 0.15;
      settle(angleFor(indexFor(thrown)), velocity);
      d.raw = angle.get();
    };

    const step = (delta: number) => {
      const next = Math.min(stops - 1, Math.max(0, index + delta));
      settle(angleFor(next));
      drag.current.raw = angleFor(next);
    };

    const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
      const key = event.key;
      if (key === "ArrowRight" || key === "ArrowUp") step(1);
      else if (key === "ArrowLeft" || key === "ArrowDown") step(-1);
      else if (key === "Home") step(-stops);
      else if (key === "End") step(stops);
      else return;
      event.preventDefault();
    };

    const marks = Array.from({ length: stops }, (_, i) => i);
    const knurl = Array.from({ length: 48 }, (_, i) => i);

    return (
      <div
        className={`flex select-none flex-col items-center gap-4 outline-none ${className ?? ""}`}
        role="slider"
        tabIndex={0}
        aria-label="Dial"
        aria-valuemin={0}
        aria-valuemax={stops - 1}
        aria-valuenow={index}
        aria-orientation="horizontal"
        onKeyDown={onKeyDown}
      >
        <svg
          viewBox="0 0 100 100"
          width={size}
          height={size}
          className="touch-none cursor-grab active:cursor-grabbing"
          onPointerDown={onPointerDown}
          onPointerMove={onPointerMove}
          onPointerUp={onPointerUp}
          onPointerCancel={onPointerUp}
        >
          <defs>
            <radialGradient id="dial-face" cx="38%" cy="30%" r="78%">
              <stop offset="0%" stopColor="#3a3a46" />
              <stop offset="55%" stopColor="#23232c" />
              <stop offset="100%" stopColor="#141419" />
            </radialGradient>
            <linearGradient id="dial-bevel" x1="0" y1="0" x2="0" y2="1">
              <stop offset="0%" stopColor="#5a5a68" />
              <stop offset="100%" stopColor="#1a1a20" />
            </linearGradient>
          </defs>

          {ticks !== "none" &&
            marks.map((i) => {
              const a = (angleFor(i) - 90) / DEG;
              const lit = i === index;
              const r1 = ticks === "dot" ? 45 : 43;
              const r2 = 47.5;
              const cx = 50 + Math.cos(a) * r1;
              const cy = 50 + Math.sin(a) * r1;
              if (ticks === "dot") {
                return (
                  <circle
                    key={i}
                    cx={cx}
                    cy={cy}
                    r={lit ? 1.9 : 1.1}
                    fill={lit ? accent : "#4a4a58"}
                  />
                );
              }
              return (
                <line
                  key={i}
                  x1={cx}
                  y1={cy}
                  x2={50 + Math.cos(a) * r2}
                  y2={50 + Math.sin(a) * r2}
                  stroke={lit ? accent : "#4a4a58"}
                  strokeWidth={lit ? 2 : 1.1}
                  strokeLinecap="round"
                />
              );
            })}

          <circle cx="50" cy="50" r="38" fill="url(#dial-bevel)" />
          <circle cx="50" cy="50" r="35.5" fill="url(#dial-face)" />

          <motion.g
            style={{ rotate: angle, transformBox: "view-box", transformOrigin: "50% 50%" }}
          >
            {knurl.map((i) => {
              const a = ((i / knurl.length) * 360 - 90) / DEG;
              return (
                <line
                  key={i}
                  x1={50 + Math.cos(a) * 32.5}
                  y1={50 + Math.sin(a) * 32.5}
                  x2={50 + Math.cos(a) * 35.2}
                  y2={50 + Math.sin(a) * 35.2}
                  stroke="#0d0d12"
                  strokeWidth="0.9"
                  opacity="0.55"
                />
              );
            })}
            <circle cx="50" cy="50" r="22" fill="#1c1c23" />
            <circle cx="50" cy="50" r="22" fill="none" stroke="#3d3d4a" strokeWidth="0.8" />
            <line
              x1="50"
              y1="30"
              x2="50"
              y2="17"
              stroke={accent}
              strokeWidth="2.6"
              strokeLinecap="round"
            />
            <circle cx="50" cy="50" r="3.4" fill="#2c2c36" />
          </motion.g>
        </svg>

        {readout && (
          <p className="font-display text-[11px] tracking-[0.28em] text-ink-mute tabular-nums uppercase">
            <span style={{ color: accent }}>
              {String(index + 1).padStart(2, "0")}
            </span>
            {" / "}
            {String(stops).padStart(2, "0")}
          </p>
        )}
      </div>
    );
  },
);

Dial.displayName = "Dial";

export default Dial;
```


## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `detents` | `number` | `12` | Stops across the sweep. This is the resolution of the control and it changes how the drag feels as much as how it reads: few stops far apart give a decisive click between settings, many close together give something closer to a continuous ramp with a texture. Range 2–36. |
| `sweep` | `number` | `270` | Angular range, centred on twelve o'clock. Two hundred and seventy is the instrument convention because it leaves a visible gap at the bottom — the eye reads the gap as the end of the scale, so both limits are legible without a label. At a full turn there are no ends to see. Range 90–360 °. |
| `stiffness` | `number` | `380` | How hard the spring pulls toward the chosen stop after release. High makes a knob that arrives the instant you let go; low makes one with weight, where a flick keeps travelling for a moment after the finger is gone. Range 50–900. |
| `damping` | `number` | `26` | How much of that spring's energy is absorbed. Below about fifteen the knob overshoots its stop and comes back, which reads as a loose detent rather than a machined one. Range 5–60. |
| `inertia` | `number` | `0.6` | How far a flick carries past the point the hand let go. The throw is projected first and the nearest stop chosen second, so a fast spin travels several detents and settles — at zero the knob stops at whichever stop it happened to be passing, which throws the whole gesture away. Range 0–1. |
| `detentPull` | `number` | `0.5` | Magnetism felt during the drag itself, before any release. The pull falls off toward the midpoint between two stops, so the exact centre is an unstable point the knob slides off rather than a flat spot it can rest in — which is what makes a detent feel like a notch instead of a suggestion. Range 0–1. |
| `ticks` | `"line" | "dot" | "none"` | `"line"` | How the stops are marked on the panel around the knob. The scale never turns with the pointer — a mark that moves with the thing it is measuring tells you nothing about where you are. |
| `readout` | `boolean` | `true` | The value under the knob, set in tabular figures so the number does not shuffle sideways as it counts. |
| `accent` | `string (hex)` | `"#a855f7"` | The lit tick, the pointer line, and the live half of the readout. |
| `size` | `number` | `160` | Knob diameter. Everything inside is drawn against a fixed grid and scaled, so the knurling, the bevel and the pointer keep their proportions at any size. Range 96–280 px. |

## Usage

```tsx
import Dial from "@/components/registry/dial/dial";

<Dial
  detents={12}
  sweep={270}
  stiffness={380}
  damping={26}
  inertia={0.6}
  detentPull={0.5}
  ticks="line"
  readout={true}
  accent="#a855f7"
  size={160}
/>
```

The import path matches the file path above; change it if you move the component. Every value shown is the documented default — pass only what you actually want to change. The snippet lists the tunable props only: if the component's props type in the source requires others (content, handlers, data), pass those too.

## Integration rules

- Keep the `"use client"` directive. This is a client component and will not render as a Server Component.
- It fills its parent. Give the wrapper an explicit height (or a definite grid area) — against a height-auto parent it collapses to nothing.
- It takes a `reducedMotion` prop and quiesces when true. Wire it to a `prefers-reduced-motion` listener rather than hardcoding `false`.
- The `touch-action: none` on the hit target is load-bearing — without it a finger drag scrolls the page instead of driving the effect. Do not strip it as a stray utility class.

## Your task

1. Tell me where in my project this should live and why.
2. Create the files above verbatim.
3. Add the design tokens to my global CSS, or map them to tokens I already have.
4. Wire the component into the place I point you at, with sensible props for that context.
5. Flag anything in my setup that conflicts with the stack assumptions above.

Do not restyle the component or alter the animation math unless I ask.
