# Button (Notchset): prompt.md (v1.0.0)

- id: `button` · version 1.0.0 · component · free
- category: Actions
- build: Base UI (this item also ships a Radix build)
- install (this build): `npx shadcn@latest add https://beautiful-ui.dev/r/button.json`
- npm dependencies: @base-ui/react@^1, class-variance-authority@^0.7
- registry dependencies: utils, https://beautiful-ui.dev/r/notchset-foundation.json
- docs: https://beautiful-ui.dev/components/button
- The install command carries everything this item needs (files, CSS, tokens, npm and registry dependencies). Prefer it to copying source by hand.

shadcn's Button in Notchset: square, mono caps, a tick ruler on hover, a five-tick scanner while it works and a check that traces itself when it's done, at a width that never moves. The Plate variant presses onto its plate; the link draws its rule from the left.

## Build it
- Stack: React 19 (`ref` is a plain prop), TypeScript, Tailwind CSS v4 utilities, a shadcn-initialised project with the `@/*` alias.
- Packages: `@base-ui/react@^1`, `class-variance-authority@^0.7` (Base UI build); `class-variance-authority@^0.7`, `radix-ui@^1` (Radix build).
- Files: `components/ui/notchset/button.tsx`, `components/ui/notchset/button-client.tsx`; shared code: `lib/beautiful-ui/notchset/button-variants.ts`, `lib/beautiful-ui/notchset/button.tsx`, `lib/beautiful-ui/notchset/instrument.tsx`, `lib/beautiful-ui/notchset/root.ts`.
- Registry dependencies, installed with it automatically: shadcn `utils` (cn), `notchset-foundation`.
- Builds: separate Base UI and Radix files. Install the one that matches the project (see Install): a free item's bare URL installs the Base UI build of it and its dependencies.
- Exports to keep: `Button`, `buttonVariants`, `ButtonClient`, and every exported type.
- CSS: the install adds the notchset foundation (tokens, keyframes, motion levels) to your global stylesheet once. Nothing to import by hand.
- Re-running `add` (or `--overwrite`) re-applies those rules: put overrides in your own CSS, never in the installed rules.
- Tokens: retheme with the `--notchset-*` custom properties (`--notchset-check`, `--notchset-control-edge`, `--notchset-draw-from`, `--notchset-ease-bloom`, `--notchset-ease-travel`, `--notchset-fade`, `--notchset-focus-color`, `--notchset-focus-inset`, `--notchset-life-from`, `--notchset-life-ms`, `--notchset-node-blink`, `--notchset-node-bloom`, `--notchset-node-delay`, `--notchset-plate-color`, `--notchset-rise-from`, `--notchset-rule`, `--notchset-scroll`, `--notchset-signal`, `--notchset-sweep-to`). Never add Tailwind colour classes inside the component.

```tsx
import { Button, buttonVariants } from "@/components/ui/notchset/button";
```

## Parts

| Part | data-slot | What it is for |
|---|---|---|
| `Button` | `button` | The button. |
| `Icon` | `button-icon` | The icon, scanner or check. |
| `Ruler` | `button-ruler` | The hover ruler. |

Style a part with `[data-slot="<slot>"]` selectors or its `className`; keep the attributes when editing.

## Sound
- Keep every `data-slot` and `data-sound` attribute: the sound layer reads them.
- Installing this item adds no audio. Nothing plays until the app mounts `SoundProvider` once (install: `npx shadcn@latest add https://beautiful-ui.dev/r/notchset-sound.json`, import from `@/components/ui/notchset/sound-provider`); `useSound()` gives `muted` and `setMuted` for a mute control. Without a provider the audio engine never loads.

## Match the original
- Read `components/ui/notchset/button.tsx`, `components/ui/notchset/button-client.tsx` as the reference implementation before changing or recreating anything, and match it: sizes, colours per theme, motion timings, copy and behaviour.
- If you deviate (a prop you can't honour, a style you changed, a dependency you swapped), say so in your reply, part by part.
- Keep the accessibility contract, the keyboard map and the motion levels listed below.

## Use it when
- button, action, run, deploy, async button, loading button, shadcn button, link button, Notchset
- Every action in a Notchset interface
- A drop-in for shadcn's Button: same exports, variants, sizes and data-slot
- Async work: return a Promise from onClick and it runs loading → done → idle

### Not when
- Starting and stopping a run: use Run Button
- Destroying something that matters: use Confirm Button

## Mistakes
- Use one destructive (signal) button per view, for stop and destroy
- Install the Notchset theme for the exact look; without it the button uses your shadcn tokens

## Usage

```tsx
"use client";

import { Button, buttonVariants } from "@/components/ui/notchset/button";

export function EvalActions({ runEval, deploy }: { runEval: () => Promise<void>; deploy: () => void }) {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {/* Async onClick: the button shows its loading and success states on its own. */}
      <Button icon="play" kbd="⌘↵" loadingLabel="Running" successLabel="Done" onClick={runEval}>
        Run eval
      </Button>
      <Button variant="plate" icon="arrow" onClick={deploy}>
        Deploy
      </Button>
      <a className={buttonVariants({ variant: "link" })} href="/docs">
        Docs
      </a>
    </div>
  );
}
```

## Props

| Prop | Type | Default | What it does |
|---|---|---|---|
| `variant` | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link" \| "plate"` |  | shadcn's six, plus Plate: a key that rests on a 1px plate and presses onto it. |
| `size` | `"default" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"` |  | 32 / 24 / 28 / 40px; icon sizes are squares. 44px on coarse pointers via your own className if needed. |
| `icon` | `"play" \| "arrow" \| "plus" \| "trace" \| "stop" \| "copy" \| "external" \| ReactNode` |  | A Notchset glyph or your own svg; the scanner and check take its place. |
| `iconPosition` | `"left" \| "right"` |  | Default left. |
| `kbd` | `string` |  | A shortcut hint in a box; sets aria-keyshortcuts. |
| `loading / success` | `boolean` |  | Controlled states. |
| `loadingLabel / successLabel` | `string` |  | The words while working and when done; the widest label sets the width. |
| `successHold` | `number` |  | How long an automatic success shows (ms). Default 1400. |
| `flat` | `boolean` |  | No hover ruler, and no plate on Plate. |
| `onClick` | `(event) => unknown` |  | Return a Promise and the button runs itself. |
| `render (Base UI) / asChild (Radix)` | `as shadcn` |  | Render as a link or your own element. |

Full docs: https://beautiful-ui.dev/components/button

## Customising
- Colours: the component reads your shadcn tokens (`--background`, `--foreground`, `--border` …), refined by the `--notchset-*` tokens. The signal colour is `--notchset-signal` (it falls back to `--destructive`). Set tokens on `:root`, or on any container to retheme one area.
- Dark mode follows the `.dark` class on an ancestor (the shadcn and next-themes convention).
- Update later by re-running the install with `--overwrite` (review the diff if you edited it). Changelog: https://beautiful-ui.dev/r/changelog.json

## Keyboard

| Keys | Action |
|---|---|
| Enter / Space | Activate |

## Performance

- One native button; press, hover and the link rule are CSS transitions on transform, background and scale.
- The scanner and check draw only while loading or done; an idle button runs no JavaScript.
- Motion off (reduced motion or data-motion="off") lands every transition at once.

## Responsive

- Fixed heights per size (24, 28, 32, 40px); icon sizes are squares.
- On touch screens every size grows to at least 44px tall.

## Motion inventory

| Interaction | What moves |
|---|---|
| Hover | The fill changes and a 4px tick ruler fades in (not on touch, flat or link) |
| Press | Plate: the key travels 2px onto its plate in 40ms and springs back in 200ms |
| Loading | The scanner: five ticks fading in turn, 700ms |
| Done | The check traces in over 260ms; it holds 1400ms, then idle |
| Link | Ink draws across the rule from the left in 280ms (retracting to the right); the arrow steps 4px |

## Accessibility contract (preserve when editing)
- A native button through Base UI or Radix, as shadcn builds it
- aria-busy while loading; only the current label is read (the others are hidden)
- kbd sets aria-keyshortcuts (⌘ also as Ctrl)
- Focus shows crop marks, keyboard only

## Install

Base UI project (a base-* style in components.json):

```bash
npx shadcn@latest add https://beautiful-ui.dev/r/button.json
```

Radix project (a radix-*, new-york or default style):

```bash
npx shadcn@latest add https://beautiful-ui.dev/r/radix-nova/button.json
```

Or add the `@beautiful-ui` registry to components.json and run `npx shadcn@latest add @beautiful-ui/button`: the CLI picks the build from your style.

## Credits
- Built on shadcn/ui (https://ui.shadcn.com)

## Source (Base UI build)

### components/ui/notchset/button.tsx

```tsx
/**
 * Button (Notchset) v1.0.0 · Beautiful UI, by Chimpy (https://x.com/stochastichimp)
 * Docs: https://beautiful-ui.dev/components/button · Agent prompt: https://beautiful-ui.dev/md/button.md
 * MIT licensed: free to use, change and share.
 */
import { ButtonClient, type ButtonProps } from "@/components/ui/notchset/button-client";
import { buttonVariants } from "@/lib/beautiful-ui/notchset/button-variants";

/*
 * Notchset Button (Base UI build). Server-safe like shadcn's: buttonVariants() works anywhere, and the
 * interactive part (phases, sound, the plate) lives in button-client.tsx.
 */

function Button(props: ButtonProps) {
  return <ButtonClient {...props} />;
}

export { Button, buttonVariants };
export type { ButtonProps };
```

### components/ui/notchset/button-client.tsx

```tsx
"use client";

/**
 * Button (Notchset) v1.0.0 · Beautiful UI, by Chimpy (https://x.com/stochastichimp)
 * Docs: https://beautiful-ui.dev/components/button · Agent prompt: https://beautiful-ui.dev/md/button.md
 * MIT licensed: free to use, change and share.
 */

import * as React from "react";
import { Button as ButtonPrimitive } from "@base-ui/react/button";
import { cn } from "@/lib/utils";
import { buttonVariants } from "@/lib/beautiful-ui/notchset/button-variants";
import { NOTCHSET_ROOT, kbdToShortcut, playCue, useComposedRefs } from "@/lib/beautiful-ui/notchset/instrument";
import { ButtonContent, ButtonPlate, iconSize, useButtonPhase, type ButtonExtras, type ButtonSize, type ButtonVariant } from "@/lib/beautiful-ui/notchset/button";

/*
 * Notchset Button (Base UI build). shadcn's Button, same exports, variants, sizes and data-slot, in
 * Notchset: square, mono caps, a tick ruler on hover, the scanner while it works, a traced check when
 * done, and the Plate variant that presses onto its plate. Return a Promise from onClick and it
 * runs loading → done → idle by itself. Use `render` for links, as in shadcn's Base UI build.
 */

type ButtonProps = Omit<ButtonPrimitive.Props, "onClick"> &
  ButtonExtras & {
    variant?: ButtonVariant;
    size?: ButtonSize;
    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => unknown;
  };

function ButtonClient({ className, variant = "default", size = "default", icon, iconPosition, kbd, loading, success, loadingLabel, successLabel, successHold, flat, onClick, children, ref, ...props }: ButtonProps) {
  const own = React.useRef<HTMLButtonElement>(null);
  const refs = useComposedRefs<HTMLButtonElement>(ref as React.Ref<HTMLButtonElement>, own);
  const [phase, run] = useButtonPhase({ loading, success, successHold });
  const busy = phase === "loading";
  const button = (
    <ButtonPrimitive
      {...NOTCHSET_ROOT}
      ref={refs}
      data-slot="button"
      data-variant={variant}
      data-size={size}
      data-state={phase}
      aria-busy={busy || undefined}
      aria-keyshortcuts={kbdToShortcut(kbd)}
      onClick={(e: React.MouseEvent<HTMLButtonElement>) => {
        if (busy) return;
        playCue(own.current, variant === "destructive" ? "signal" : variant === "plate" ? "latch" : variant === "ghost" || variant === "link" ? "tick" : "tap");
        run(own.current, onClick?.(e));
      }}
      className={(state) => cn(`notchset-focus`, buttonVariants({ variant, size }), typeof className === "function" ? className(state) : className)}
      {...props}
    >
      <ButtonContent phase={phase} icon={icon} iconPosition={iconPosition} kbd={kbd} loadingLabel={loadingLabel} successLabel={successLabel} ruler={!flat && variant !== "link"} iconOnly={iconSize(size)}>
        {children}
      </ButtonContent>
    </ButtonPrimitive>
  );
  return variant === "plate" && !flat ? <ButtonPlate>{button}</ButtonPlate> : button;
}

export { ButtonClient };
export type { ButtonProps };
```

### lib/beautiful-ui/notchset/button-variants.ts

```tsx
import { cva } from "class-variance-authority";

/*
 * Notchset Button's variants, server-safe like shadcn's: call buttonVariants() from a Server Component
 * (links styled as buttons). The interactive Button lives in a client module.
 */

export const buttonVariants = cva(
  "group/button relative inline-flex shrink-0 cursor-pointer items-center justify-center gap-(--b-gap) rounded-none border-0 font-mono font-medium tracking-[0.07em] whitespace-nowrap uppercase outline-none select-none transition-[background-color,color,transform,border-color] duration-[120ms,120ms,var(--notchset-key-up),120ms] ease-[linear,linear,var(--notchset-ease-key-up),linear] disabled:cursor-not-allowed disabled:opacity-40 aria-disabled:cursor-not-allowed aria-disabled:opacity-40 aria-busy:cursor-progress [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-(--b-ic)",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-[var(--notchset-primary-hover,color-mix(in_oklab,var(--primary)_86%,var(--background)))] active:bg-[var(--notchset-primary-press,var(--primary))] [--b-tick:var(--notchset-tick-on-primary,color-mix(in_oklab,var(--primary-foreground)_34%,transparent))] [--b-kbd:var(--notchset-kbd-on-primary,color-mix(in_oklab,var(--primary-foreground)_45%,transparent))]",
        destructive:
          "bg-[var(--notchset-signal,var(--destructive))] text-[color:var(--notchset-on-signal,white)] hover:bg-[var(--notchset-signal-hover,var(--destructive))] active:bg-[var(--notchset-signal-press,var(--destructive))] [--b-tick:var(--notchset-tick-on-primary,color-mix(in_oklab,white_34%,transparent))] [--b-kbd:var(--notchset-kbd-on-signal,color-mix(in_oklab,black_40%,transparent))] [--notchset-focus-color:var(--notchset-signal-text,var(--destructive))]",
        outline: "border border-solid border-foreground bg-transparent text-foreground hover:bg-accent active:bg-[var(--notchset-tint-press,var(--accent))]",
        secondary: "bg-secondary text-secondary-foreground hover:bg-[var(--notchset-secondary-hover,var(--secondary))] active:bg-[var(--notchset-secondary-press,var(--secondary))]",
        ghost: "bg-transparent text-foreground hover:bg-accent active:bg-[var(--notchset-tint-press,var(--accent))]",
        link: "h-auto min-w-0 justify-start bg-transparent px-0.5 pt-[3px] pb-1.5 text-foreground active:text-[var(--notchset-signal-text,var(--destructive))]",
        plate: "bg-primary text-primary-foreground hover:bg-[var(--notchset-primary-hover,color-mix(in_oklab,var(--primary)_86%,var(--background)))] active:translate-x-[2px] active:translate-y-[2px] active:duration-[var(--notchset-key-down)] active:ease-linear",
      },
      size: {
        default: "h-8 min-w-8 px-3 text-[11px] [--b-gap:8px] [--b-ic:16px] [--b-kh:18px] [--b-kfs:9px]",
        xs: "h-6 min-w-6 px-2 text-[9.5px] [--b-gap:6px] [--b-ic:14px] [--b-kh:14px] [--b-kfs:8px]",
        sm: "h-7 min-w-7 px-2.5 text-[10px] [--b-gap:7px] [--b-ic:16px] [--b-kh:16px] [--b-kfs:8.5px]",
        lg: "h-10 min-w-10 px-4 text-[12px] [--b-gap:10px] [--b-ic:20px] [--b-kh:20px] [--b-kfs:10px]",
        icon: "size-8 [--b-ic:16px]",
        "icon-xs": "size-6 [--b-ic:14px]",
        "icon-sm": "size-7 [--b-ic:16px]",
        "icon-lg": "size-10 [--b-ic:20px]",
      },
    },
    // The link's drawn rule lives in the Notchset foundation (a system class, kept out of the utilities).
    compoundVariants: [{ variant: "link", class: `notchset-link` }],
    defaultVariants: { variant: "default", size: "default" },
  },
);

export type ButtonVariant = NonNullable<Parameters<typeof buttonVariants>[0]>["variant"];
export type ButtonSize = NonNullable<Parameters<typeof buttonVariants>[0]>["size"];
```

### lib/beautiful-ui/notchset/button.tsx

```tsx
"use client";

import * as React from "react";
import { cn } from "@/lib/utils";
import { buttonVariants, type ButtonSize } from "@/lib/beautiful-ui/notchset/button-variants";
import { Check, Scanner, playCue } from "@/lib/beautiful-ui/notchset/instrument";

/*
 * Notchset Button, shared by both builds (handoff 1.2, the base Button). shadcn's Button in Notchset:
 * square, mono caps, flat at rest, a tick ruler along the bottom on hover, a five-tick scanner while
 * it works and a check that traces in when it's done. The Plate variant rests on a 1px plate offset
 * 2px and presses onto it. The width never moves: the idle, loading and done labels share one grid
 * cell, so the widest sets it (no measuring).
 */

export type ButtonPhase = "idle" | "loading" | "success";

/** Line glyphs on a 24 grid, 1.5 stroke, square caps. */
export const BUTTON_ICONS = {
  play: "M7 4 V20 L19 12 Z",
  arrow: "M4 12 H19 M13 6 L19 12 L13 18",
  plus: "M12 4 V20 M4 12 H20",
  trace: "M4 18 H10 V6 H20",
  stop: "M6 6 H18 V18 H6 Z",
  copy: "M8 8 H20 V20 H8 Z M4 16 V4 H16",
  external: "M14 4 H20 V10 M20 4 L11 13 M17 14 V20 H4 V7 H10",
} as const;
export type ButtonIconName = keyof typeof BUTTON_ICONS;

export type { ButtonSize, ButtonVariant } from "@/lib/beautiful-ui/notchset/button-variants";

/** What Notchset adds to shadcn's Button props. All optional. */
export type ButtonExtras = {
  /** A Notchset glyph, or your own icon (an svg). shadcn-style icon children work too. */
  icon?: ButtonIconName | React.ReactNode;
  iconPosition?: "left" | "right";
  /** A shortcut hint in a box (e.g. "⌘↵"); display only. */
  kbd?: string;
  /** Controlled working state: the scanner and loadingLabel; clicks are ignored. */
  loading?: boolean;
  /** Controlled done state: the check and successLabel. */
  success?: boolean;
  loadingLabel?: string;
  successLabel?: string;
  /** How long an automatic success shows before idle (ms). Default 1400. */
  successHold?: number;
  /** No hover ruler and, on Plate, no plate. */
  flat?: boolean;
};

/** Runs an async click: loading while the Promise is pending, then success for successHold, then idle. */
export function useButtonPhase({ loading, success, successHold = 1400 }: Pick<ButtonExtras, "loading" | "success" | "successHold">) {
  const [own, setOwn] = React.useState<ButtonPhase>("idle");
  React.useEffect(() => {
    if (own !== "success") return;
    const t = setTimeout(() => setOwn("idle"), successHold);
    return () => clearTimeout(t);
  }, [own, successHold]);
  const phase: ButtonPhase = loading ? "loading" : success ? "success" : own;
  const run = (el: HTMLElement | null, result: unknown) => {
    if (!result || typeof (result as Promise<unknown>).then !== "function" || loading !== undefined) return;
    setOwn("loading");
    (result as Promise<unknown>).then(
      () => {
        playCue(el, "done");
        setOwn("success");
      },
      () => setOwn("idle"),
    );
  };
  return [phase, run] as const;
}

function Glyph({ icon }: { icon: ButtonExtras["icon"] }) {
  if (typeof icon === "string" && icon in BUTTON_ICONS) {
    return (
      <svg aria-hidden viewBox="0 0 24 24">
        <path d={BUTTON_ICONS[icon as ButtonIconName]} fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="square" strokeLinejoin="miter" />
      </svg>
    );
  }
  return <>{icon as React.ReactNode}</>;
}

/**
 * The inside: the icon slot (icon, scanner or check), the labels stacked in one grid cell (the
 * widest sets the width; only the current one is visible and read), the kbd box, and the ruler.
 */
function ButtonContent({ phase, icon, iconPosition = "left", kbd, loadingLabel, successLabel, children, ruler, iconOnly }: ButtonExtras & { phase: ButtonPhase; children?: React.ReactNode; ruler: boolean; iconOnly: boolean }) {
  const hasStates = loadingLabel !== undefined || successLabel !== undefined;
  const iconSlot =
    phase === "loading" ? (
      <Scanner height={12} />
    ) : phase === "success" ? (
      <Check />
    ) : icon !== undefined ? (
      <Glyph icon={icon} />
    ) : null;
  const label = (text: React.ReactNode, on: boolean) => (
    <span data-slot="button-label" aria-hidden={!on || undefined} className={cn("col-start-1 row-start-1 transition-opacity duration-[90ms]", on ? "opacity-100" : "invisible opacity-0")}>
      {text}
    </span>
  );
  return (
    <>
      {iconPosition === "left" && iconSlot && (
        <span data-slot="button-icon" className="flex size-(--b-ic) items-center justify-center">
          {iconSlot}
        </span>
      )}
      {!iconOnly &&
        (hasStates ? (
          <span className="grid">
            {label(children, phase === "idle")}
            {label(loadingLabel ?? children, phase === "loading")}
            {label(successLabel ?? children, phase === "success")}
          </span>
        ) : (
          children
        ))}
      {iconPosition === "right" && iconSlot && (
        <span data-slot="button-icon" className="flex size-(--b-ic) items-center justify-center">
          {iconSlot}
        </span>
      )}
      {iconOnly && phase === "idle" && !iconSlot && children}
      {kbd && !iconOnly && phase !== "success" && (
        <span
          aria-hidden
          data-slot="button-kbd"
          className="flex h-(--b-kh) items-center border border-solid border-(--b-kbd,color-mix(in_oklab,currentColor_32%,transparent)) px-[5px] text-(length:--b-kfs) font-normal tracking-[0.02em] tabular-nums pointer-coarse:hidden"
        >
          {kbd}
        </span>
      )}
      {ruler && (
        <span
          aria-hidden
          data-slot="button-ruler"
          className="pointer-events-none absolute inset-x-0 bottom-0 h-1 opacity-0 transition-opacity duration-[120ms] [background-image:repeating-linear-gradient(90deg,var(--b-tick,color-mix(in_oklab,currentColor_30%,transparent))_0_1px,transparent_1px_4px)] group-hover/button:opacity-100 group-aria-busy/button:!opacity-0 pointer-coarse:hidden"
        />
      )}
    </>
  );
}

/** The plate under a Plate button: a 1px frame offset 2px that the key presses onto. */
function ButtonPlate({ children, className }: { children: React.ReactNode; className?: string }) {
  return (
    <span
      data-slot="button-plated"
      className={cn(
        "relative inline-flex [--notchset-plate-color:var(--notchset-control-edge,var(--input))] has-[:hover,:focus-visible,[aria-busy=true]]:[--notchset-plate-color:var(--foreground)] has-[:disabled,[aria-disabled=true]]:[--notchset-plate-color:var(--notchset-rule,var(--border))]",
        className,
      )}
    >
      <span aria-hidden data-slot="plate" className={`notchset-plate`} />
      {children}
    </span>
  );
}

const iconSize = (size: ButtonSize) => typeof size === "string" && size.startsWith("icon");

export { ButtonContent, ButtonPlate, buttonVariants, iconSize };
```

### lib/beautiful-ui/notchset/instrument.tsx

```tsx
"use client";

import * as React from "react";
import { cn } from "@/lib/utils";

/*
 * Notchset instrument parts, shared by every member of a pack: the node (a round light that reports
 * state), the legend printed above a control, the plate a key presses onto, the traced check, the
 * five-tick scanner, and the glyph flip that lands a changed label left to right. Nodes and checks
 * are inline SVG (round at every DPR); the CSS lives in the Notchset foundation. Also: the one motion
 * policy (reduced motion or a data-motion="off" ancestor), ref composition, the portal container
 * and the sound attributes every Notchset root carries.
 */

// ---------------------------------------------------------------------------------------------
// Motion, refs, portals, sound
// ---------------------------------------------------------------------------------------------

/** True under prefers-reduced-motion or inside a data-motion="off" scope. Checked when an effect runs. */
/**
 * Whether motion is off for an element, kept live: it follows the OS reduced-motion setting and any
 * data-motion attribute change above it, so a preference switched mid-playback stops decoration at once.
 */
export function useMotionOff(ref: React.RefObject<Element | null>) {
  const [off, setOff] = React.useState(false);
  React.useEffect(() => {
    const read = () => setOff(motionOff(ref.current));
    const r = requestAnimationFrame(read);
    const mq = window.matchMedia?.("(prefers-reduced-motion: reduce)");
    mq?.addEventListener?.("change", read);
    const mo = new MutationObserver(read);
    mo.observe(document.documentElement, { attributes: true, attributeFilter: ["data-motion"], subtree: true });
    return () => {
      cancelAnimationFrame(r);
      mq?.removeEventListener?.("change", read);
      mo.disconnect();
    };
  }, [ref]);
  return off;
}

/**
 * The microphone, or a rejection after `timeoutMs` (a prompt left open, a denied permission). A stream
 * that arrives after the timeout is stopped at once, so a late "Allow" never leaves the mic on.
 */
export function requestMic(timeoutMs = 5000): Promise<MediaStream> {
  if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) return Promise.reject(new Error("no mic"));
  const ask = navigator.mediaDevices.getUserMedia({ audio: true });
  return new Promise((resolve, reject) => {
    let late = false;
    const t = setTimeout(() => {
      late = true;
      reject(new Error("timeout"));
    }, timeoutMs);
    ask.then(
      (stream) => {
        clearTimeout(t);
        if (late) stream.getTracks().forEach((track) => track.stop());
        else resolve(stream);
      },
      (err) => {
        clearTimeout(t);
        reject(err);
      },
    );
  });
}

export function motionOff(el: Element | null | undefined) {
  if (typeof window === "undefined") return true;
  if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return true;
  return Boolean(el?.closest('[data-motion="off"]'));
}

function assignRef<T>(ref: React.Ref<T> | undefined, node: T | null): () => void {
  if (typeof ref === "function") {
    const cleanup = ref(node);
    return typeof cleanup === "function" ? cleanup : () => ref(null);
  }
  if (ref) (ref as React.RefObject<T | null>).current = node;
  return () => {
    if (ref) (ref as React.RefObject<T | null>).current = null;
  };
}

/** Composes two refs, keeping React 19 ref cleanups. */
export function useComposedRefs<T>(a: React.Ref<T> | undefined, b: React.Ref<T> | undefined): React.RefCallback<T> {
  return React.useCallback(
    (node: T | null) => {
      const release = [assignRef(a, node), assignRef(b, node)];
      return () => release.forEach((f) => f());
    },
    [a, b],
  );
}

/** Runs ours after theirs, unless theirs called preventDefault. */
export function composeHandler<E extends { defaultPrevented: boolean }>(theirs: ((e: E) => void) | undefined, ours: (e: E) => void) {
  return (e: E) => {
    theirs?.(e);
    if (!e.defaultPrevented) ours(e);
  };
}

/** Keeps the latest value in a ref, for callbacks read inside timers and animation frames. */
export function useLatest<T>(value: T) {
  const ref = React.useRef(value);
  React.useLayoutEffect(() => {
    ref.current = value;
  });
  return ref;
}

/*
 * Where Notchset overlays (menus, popovers, tooltips) portal to. Unset, document.body, as shadcn's
 * do. Provide an element to keep them inside a scoped theme: a preview, a widget, a shadow root.
 */
export const NotchsetPortalContext = React.createContext<HTMLElement | null>(null);
export function useNotchsetPortal(): HTMLElement | undefined {
  return React.useContext(NotchsetPortalContext) ?? undefined;
}

export { NOTCHSET_ROOT, OWN_SOUND } from "@/lib/beautiful-ui/notchset/root";

// ---------------------------------------------------------------------------------------------
// Parts
// ---------------------------------------------------------------------------------------------

export type NodeState = "off" | "on" | "live" | "signal";

/** The node: a 9×9 ring whose dot blooms on (`on`), blinks (`live`) or turns signal. */
function Node({ state = "off", delay, className, style, ...props }: Omit<React.ComponentProps<"svg">, "children"> & { state?: NodeState; delay?: number }) {
  return (
    <svg
      aria-hidden
      data-slot="indicator"
      data-state={state}
      width="9"
      height="9"
      viewBox="0 0 9 9"
      className={cn(`notchset-node`, className)}
      style={delay ? ({ "--notchset-node-delay": `${delay}ms`, ...style } as React.CSSProperties) : style}
      {...props}
    >
      <circle data-slot="indicator-ring" cx="4.5" cy="4.5" r="3.25" fill="none" strokeWidth="1" />
      <circle data-slot="indicator-dot" cx="4.5" cy="4.5" />
    </svg>
  );
}

/** A small solid round mark (the node where a leader meets a popup, a pointer): SVG, round at every DPR. */
function Dot({ size = 7, className, style }: { size?: number; className?: string; style?: React.CSSProperties }) {
  return (
    <svg aria-hidden width={size} height={size} viewBox={`0 0 ${size} ${size}`} className={cn("pointer-events-none absolute overflow-visible", className)} style={style}>
      <circle cx={size / 2} cy={size / 2} r={size / 2} fill="currentColor" />
    </svg>
  );
}

/** The legend: a mono label above a control, with an optional node (or any trailing reading). */
function Legend({ label, node, children, className, ...props }: React.ComponentProps<"div"> & { label?: React.ReactNode; node?: NodeState }) {
  return (
    <div data-slot="legend" className={cn(`notchset-legend`, className)} {...props}>
      <span data-slot="legend-label">{label}</span>
      {(children != null || node) && (
        <span data-slot="legend-reading" className="flex items-center gap-2">
          {children}
          {node && <Node state={node} />}
        </span>
      )}
    </div>
  );
}

/** A key on its plate: the plate is an offset frame behind the child; `--notchset-plate-color` tints it. */
function Plated({ className, children, ...props }: React.ComponentProps<"span">) {
  return (
    <span data-slot="plated" className={cn("relative inline-flex", className)} {...props}>
      <span aria-hidden data-slot="plate" className={`notchset-plate`} />
      {children}
    </span>
  );
}

/**
 * The success check. Mounted, it traces itself in over --notchset-check (instant under reduced
 * motion); pass `drawn` to drive the trace yourself.
 */
function Check({ drawn, size = 16 }: { drawn?: boolean; size?: number }) {
  return (
    <svg aria-hidden data-slot="check" width={size} height={size} viewBox="0 0 24 24">
      <path
        d="M4 12.5 L9.5 18 L20 6"
        fill="none"
        stroke="currentColor"
        strokeWidth={1.75}
        strokeLinecap="square"
        pathLength={1}
        strokeDasharray={1}
        className={drawn === undefined ? `notchset-check-draw` : undefined}
        style={drawn === undefined ? undefined : { strokeDashoffset: drawn ? 0 : 1, transition: "stroke-dashoffset var(--notchset-check) var(--notchset-ease-travel)" }}
      />
    </svg>
  );
}

/** The scanner: five 1px ticks fading in turn while something works (static, centre lit, when motion is off). */
function Scanner({ height = 12 }: { height?: number }) {
  return (
    <span aria-hidden data-slot="scanner" className={cn(`notchset-scanner`, "inline-flex items-end gap-[2px]")} style={{ height }}>
      {[0.82, 0.66, 1, 0.66, 0.82].map((h, i) => (
        <span key={i} className="w-px bg-current" style={{ height: height * h, animationDelay: `${i * 140 - 700}ms` }} />
      ))}
    </span>
  );
}

// ---------------------------------------------------------------------------------------------
// Glyph flip: each character cycles through glyphs and lands at 110 + i·14ms, left to right
// ---------------------------------------------------------------------------------------------

const GLYPHS = "ABCDEFGHJKLMNPRSTUVWXYZ0123456789#/+=";
const STILL = new Set([" ", "·", "/", ".", ":"]);

export function scramble(text: string, elapsed: number) {
  let out = "";
  for (let i = 0; i < text.length; i++) {
    const ch = text[i]!;
    out += STILL.has(ch) || elapsed >= 110 + i * 14 ? ch : GLYPHS[(Math.floor(elapsed / 36) * 5 + i * 11) % GLYPHS.length];
  }
  return out;
}

/**
 * The text to show for `text`: when it changes, a few frames of glyphs that land left to right.
 * Runs on requestAnimationFrame only while a flip is active; the settled text is never state. Off
 * under reduced motion, inside data-motion="off" (pass the element) or with `off`.
 */
export function useGlyphFlip(text: string, { off = false, el }: { off?: boolean; el?: React.RefObject<Element | null> } = {}) {
  const [frame, setFrame] = React.useState<{ for: string; shown: string } | null>(null);
  const first = React.useRef(true);
  React.useEffect(() => {
    if (first.current) {
      first.current = false;
      return;
    }
    if (off || motionOff(el?.current)) return;
    let raf = 0;
    const t0 = performance.now();
    const end = 110 + text.length * 14 + 40;
    const step = (now: number) => {
      const elapsed = now - t0;
      if (elapsed >= end) return setFrame(null);
      setFrame({ for: text, shown: scramble(text, elapsed) });
      raf = requestAnimationFrame(step);
    };
    raf = requestAnimationFrame(step);
    return () => cancelAnimationFrame(raf);
  }, [text, off, el]);
  return frame && frame.for === text ? frame.shown : text;
}

/** A label that flips when its text changes; screen readers read the final text only. */
function FlipText({ children, off, className, ...props }: Omit<React.ComponentProps<"span">, "children"> & { children: string; off?: boolean }) {
  const ref = React.useRef<HTMLSpanElement>(null);
  const shown = useGlyphFlip(children, { off, el: ref });
  return (
    <span ref={ref} data-slot="flip-text" className={cn("relative whitespace-nowrap", className)} {...props}>
      <span aria-hidden>{shown}</span>
      <span className="sr-only">{children}</span>
    </span>
  );
}

// ---------------------------------------------------------------------------------------------
// Sound: Notchset components announce cues; the page's beautiful-ui-sound layer (opt-in) plays them.
// ---------------------------------------------------------------------------------------------

/** The Notchset cues, in the shared sound layer's names (played in the mechanical voice). */
export const NOTCHSET_CUES = { tap: "tap", latch: "lock", signal: "destructive", confirm: "halt", done: "success", tick: "tick" } as const;
export type NotchsetCue = keyof typeof NOTCHSET_CUES;

export function playCue(el: Element | null, cue: NotchsetCue) {
  if (!el || typeof CustomEvent === "undefined" || el.closest('[data-sound="off"]')) return;
  el.dispatchEvent(new CustomEvent("beautiful-ui:sound", { bubbles: true, detail: { cue: NOTCHSET_CUES[cue] } }));
}

// ---------------------------------------------------------------------------------------------
// Shortcuts: "⌘↵" → "Meta+Enter Control+Enter" (aria-keyshortcuts)
// ---------------------------------------------------------------------------------------------

const KEY_NAMES: Record<string, string> = { "⌘": "Meta", "⌃": "Control", "⌥": "Alt", "⇧": "Shift", "↵": "Enter", "⏎": "Enter", "⎋": "Escape", "⌫": "Backspace", "⇥": "Tab", "␣": "Space" };

export function kbdToShortcut(kbd: string | undefined): string | undefined {
  if (!kbd) return undefined;
  const parts = [...kbd.replace(/\s+/g, "")].map((c) => KEY_NAMES[c] ?? c.toUpperCase());
  if (!parts.length) return undefined;
  const combo = parts.join("+");
  // ⌘ on a Mac is Ctrl elsewhere: announce both.
  return combo.includes("Meta") ? `${combo} ${combo.replace("Meta", "Control")}` : combo;
}

/**
 * A number that rolls: each digit is a 0–9 strip; the ones digit moves first and each digit to its left
 * 40ms later (620ms, a small overshoot). `delay` offsets the whole number (rows 60ms apart). Non-digits
 * (",", "$", "%") sit still. Screen readers get the plain value.
 */
function RollingNumber({ value, height = 32, delay = 0, className }: { value: string | number; height?: number; delay?: number; className?: string }) {
  const text = String(value);
  const digits = text.split("");
  const lastDigit = digits.reduce((n, d, i) => (/\d/.test(d) ? i : n), -1);
  return (
    <span className={cn("relative inline-flex overflow-hidden tabular-nums", className)} style={{ height, lineHeight: `${height}px` }}>
      <span className="sr-only">{text}</span>
      <span aria-hidden className="flex">
        {digits.map((d, i) =>
          /\d/.test(d) ? (
            <span
              key={digits.length - i}
              className="flex flex-col transition-transform duration-[620ms] ease-[cubic-bezier(.34,1.15,.5,1)]"
              style={{ transform: `translateY(${-Number(d) * height}px)`, transitionDelay: `${delay + (lastDigit - i) * 40}ms` }}
            >
              {Array.from({ length: 10 }, (_, n) => (
                <span key={n} style={{ height }}>
                  {n}
                </span>
              ))}
            </span>
          ) : (
            <span key={`s${digits.length - i}`}>{d}</span>
          ),
        )}
      </span>
    </span>
  );
}

export { Check, Dot, FlipText, Legend, Node, Plated, RollingNumber, Scanner };
```

### lib/beautiful-ui/notchset/root.ts

```tsx
/*
 * Notchset's root attributes, server-safe (no client directive), so server components can spread
 * them too. Every Notchset root (and portalled popup) carries data-notchset (the motion policy's
 * scope), plays its own cues in the mechanical voice, and keeps the page's click layer out.
 */
export const NOTCHSET_ROOT = { "data-notchset": "", "data-sound": "none", "data-sound-voice": "analogue" } as const;

/** On every interactive element: it plays its own cues, so the page's click layer adds no tap. */
export const OWN_SOUND = { "data-sound": "none" } as const;
```

The notchset foundation (the tokens listed above, keyframes and motion levels) installs once with the first component; its CSS is public at https://beautiful-ui.dev/r/notchset-foundation.json.