@dowel-ui/react 0.5.0 → 0.8.0

package/src/components/gooey-popover/gooey-popover.tsx

@@ -0,0 +1,332 @@
+"use client";
+
+// Ported from SmoothUI Gooey Popover (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import {
+  useCallback,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  type PopoverContentProps,
+} from "@/components/popover";
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A round trigger whose popover pours out of it: the panel starts as a circle
+ * over the trigger and stretches into a rectangle, while an SVG "goo" filter
+ * (blur + alpha threshold) melts the two shapes together where they meet.
+ *
+ * The source ran this on a GSAP timeline and positioned itself by hand. Here
+ * Radix Popover (through Dowel's `popover`) owns placement, collision, focus
+ * and dismissal, and the timeline is CSS keyframes driven by data-state:
+ * Radix's Presence waits for the content's own exit animation — a "hold" as
+ * long as the whole close sequence — before unmounting it.
+ *
+ * Because the content is portalled, the blob that sits under the trigger is
+ * drawn inside the portal too, at the trigger's measured position, with an
+ * aria-hidden copy of the trigger's icon on top so nothing visibly changes.
+ * Under reduced motion the goo layer is dropped and the panel simply appears.
+ */
+
+const STYLES = `
+@keyframes dowel-gooey-popover-grow {
+  from {
+    left: calc(var(--gooey-x, var(--gooey-gx)) - var(--gooey-size) / 2);
+    top: calc(var(--gooey-y, var(--gooey-gy)) - var(--gooey-size) / 2);
+    width: var(--gooey-size); height: var(--gooey-size); border-radius: calc(var(--gooey-size) / 2);
+  }
+  to { left: 0; top: 0; width: 100%; height: 100%; border-radius: var(--gooey-radius); }
+}
+@keyframes dowel-gooey-popover-shrink {
+  from { left: 0; top: 0; width: 100%; height: 100%; border-radius: var(--gooey-radius); opacity: 1; }
+  70% { opacity: 1; }
+  to {
+    left: calc(var(--gooey-x, var(--gooey-gx)) - var(--gooey-size) / 2);
+    top: calc(var(--gooey-y, var(--gooey-gy)) - var(--gooey-size) / 2);
+    width: var(--gooey-size); height: var(--gooey-size); border-radius: calc(var(--gooey-size) / 2);
+    opacity: 0;
+  }
+}
+@keyframes dowel-gooey-popover-reveal {
+  from { opacity: 0; translate: 0 1rem; }
+  to { opacity: 1; translate: 0 0; }
+}
+@keyframes dowel-gooey-popover-conceal {
+  from { opacity: 1; translate: 0 0; }
+  to { opacity: 0; translate: 0 0.5rem; }
+}
+@keyframes dowel-gooey-popover-hold {
+  from { opacity: 1; }
+  to { opacity: 1; }
+}
+[data-slot="gooey-popover-content"][data-state="open"] { animation: none; }
+[data-slot="gooey-popover-content"][data-state="closed"] {
+  animation: dowel-gooey-popover-hold calc(var(--gooey-speed) * 1.2 * var(--motion-scale)) linear both;
+}
+[data-slot="gooey-popover-content"][data-state="open"] [data-slot="gooey-popover-shape"] {
+  animation: dowel-gooey-popover-grow calc(var(--gooey-speed) * var(--motion-scale))
+    var(--ease-in-out-quint) both;
+}
+[data-slot="gooey-popover-content"][data-state="closed"] [data-slot="gooey-popover-shape"] {
+  animation: dowel-gooey-popover-shrink calc(var(--gooey-speed) * var(--motion-scale))
+    var(--ease-in-quint) calc(var(--gooey-speed) * 0.2 * var(--motion-scale)) both;
+}
+[data-slot="gooey-popover-content"][data-state="open"] [data-slot="gooey-popover-body"] {
+  animation: dowel-gooey-popover-reveal calc(var(--gooey-speed) * 0.75 * var(--motion-scale))
+    var(--ease-out-quint) calc(var(--gooey-speed) * 0.575 * var(--motion-scale)) both;
+}
+[data-slot="gooey-popover-content"][data-state="closed"] [data-slot="gooey-popover-body"] {
+  animation: dowel-gooey-popover-conceal calc(var(--gooey-speed) * 0.4 * var(--motion-scale))
+    var(--ease-in-quint) both;
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="gooey-popover-goo"], [data-slot="gooey-popover-ghost"] { display: none; }
+}
+`;
+
+const gooeyPopoverVariants = cva("", {
+  variants: {
+    tone: {
+      /** The source's near-black blob on a light page, inverted in dark mode. */
+      inverted: "bg-foreground text-background",
+      primary: "bg-primary text-primary-foreground",
+      card: "bg-card text-card-foreground",
+    },
+  },
+  defaultVariants: {
+    tone: "inverted",
+  },
+});
+
+export interface GooeyPopoverProps
+  extends
+    Omit<PopoverContentProps, "children" | "content">,
+    VariantProps<typeof gooeyPopoverVariants> {
+  /** The popover's content. */
+  children: ReactNode;
+  /** The trigger's icon. A plus by default. */
+  trigger?: ReactNode;
+  /** The trigger's accessible name — it is icon-only. Also names the content by default. */
+  triggerLabel: string;
+  /** The trigger's diameter in pixels. */
+  triggerSize?: number;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** The content's width. Numbers are pixels. */
+  contentWidth?: number | string;
+  /** Length of the morph in milliseconds; the rest of the sequence scales with it. */
+  duration?: number;
+  /** Classes for the trigger button. */
+  triggerClassName?: string;
+}
+
+const PLUS = (
+  <svg
+    viewBox="0 0 24 24"
+    width={20}
+    height={20}
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2}
+    strokeLinecap="round"
+    aria-hidden="true"
+  >
+    <path d="M12 5v14M5 12h14" />
+  </svg>
+);
+
+/** Where the trigger's centre sits relative to the content, before measuring. */
+function guess(side: GooeyPopoverProps["side"], offset: number) {
+  switch (side) {
+    case "bottom":
+      return { x: "50%", y: `${String(-offset)}px` };
+    case "left":
+      return { x: `calc(100% + ${String(offset)}px)`, y: "50%" };
+    case "right":
+      return { x: `${String(-offset)}px`, y: "50%" };
+    default:
+      return { x: "50%", y: `calc(100% + ${String(offset)}px)` };
+  }
+}
+
+/** A popover that pours out of its round trigger through an SVG goo filter. */
+export function GooeyPopover({
+  ref,
+  className,
+  style,
+  children,
+  trigger = PLUS,
+  triggerLabel,
+  triggerSize = 44,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  contentWidth = 240,
+  duration = 250,
+  side = "top",
+  sideOffset = 24,
+  tone,
+  triggerClassName,
+  ...props
+}: GooeyPopoverProps) {
+  const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+  const open = openProp ?? uncontrolled;
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const filterId = `dowel-goo-${useId().replace(/:/g, "")}`;
+
+  const setOpen = (next: boolean) => {
+    if (openProp === undefined) setUncontrolled(next);
+    onOpenChange?.(next);
+  };
+
+  const setContentRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      contentRef.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref],
+  );
+
+  // Measure the trigger's centre relative to the placed content.
+  useLayoutEffect(() => {
+    if (!open) return;
+    let frames = 0;
+    let handle = 0;
+    const measure = () => {
+      const content = contentRef.current;
+      const button = triggerRef.current;
+      if (content && button) {
+        const c = content.getBoundingClientRect();
+        const t = button.getBoundingClientRect();
+        content.style.setProperty("--gooey-x", `${String(t.left + t.width / 2 - c.left)}px`);
+        content.style.setProperty("--gooey-y", `${String(t.top + t.height / 2 - c.top)}px`);
+      }
+      // The portal mounts, then Radix places the content, over the next frames.
+      if (++frames < 4) handle = requestAnimationFrame(measure);
+    };
+    measure();
+    return () => cancelAnimationFrame(handle);
+  }, [open]);
+
+  const tones = gooeyPopoverVariants({ tone });
+  const initial = guess(side, sideOffset + triggerSize / 2);
+  const atTrigger: CSSProperties = {
+    left: `calc(var(--gooey-x, var(--gooey-gx)) - ${String(triggerSize / 2)}px)`,
+    top: `calc(var(--gooey-y, var(--gooey-gy)) - ${String(triggerSize / 2)}px)`,
+    width: triggerSize,
+    height: triggerSize,
+  };
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <style href="dowel-gooey-popover" precedence="dowel">
+        {STYLES}
+      </style>
+      <PopoverTrigger asChild>
+        <button
+          ref={triggerRef}
+          type="button"
+          aria-label={triggerLabel}
+          data-slot="gooey-popover-trigger"
+          className={cn(
+            "relative inline-flex shrink-0 items-center justify-center rounded-full transition-[scale] duration-[var(--duration-fast)] active:scale-95",
+            tones,
+            focusRing,
+            triggerClassName,
+          )}
+          style={{ width: triggerSize, height: triggerSize }}
+        >
+          {trigger}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent
+        ref={setContentRef}
+        side={side}
+        sideOffset={sideOffset}
+        aria-label={props["aria-labelledby"] ? undefined : triggerLabel}
+        {...props}
+        data-slot="gooey-popover-content"
+        className={cn(
+          "relative w-auto overflow-visible rounded-none border-0 bg-transparent p-0 shadow-none",
+          className,
+        )}
+        style={
+          {
+            width: contentWidth,
+            "--gooey-size": `${String(triggerSize)}px`,
+            "--gooey-speed": `${String(duration)}ms`,
+            "--gooey-gx": initial.x,
+            "--gooey-gy": initial.y,
+            ...style,
+          } as CSSProperties
+        }
+      >
+        <svg aria-hidden="true" className="absolute size-0">
+          <defs>
+            <filter id={filterId} x="-100%" y="-100%" width="300%" height="300%">
+              <feGaussianBlur in="SourceGraphic" stdDeviation="10" result="blur" />
+              <feColorMatrix
+                in="blur"
+                type="matrix"
+                values="1 0 0 0 0  0 1 0 0 0  0 0 1 0 0  0 0 0 24 -10"
+                result="goo"
+              />
+              <feComposite in="SourceGraphic" in2="goo" operator="atop" />
+            </filter>
+          </defs>
+        </svg>
+        <div
+          aria-hidden="true"
+          data-slot="gooey-popover-goo"
+          className="pointer-events-none absolute inset-0"
+          style={{ filter: `url(#${filterId})` }}
+        >
+          <div className={cn("absolute rounded-full", tones)} style={atTrigger} />
+          <div
+            data-slot="gooey-popover-shape"
+            className={cn("absolute", tones)}
+            style={{ "--gooey-radius": "0px" } as CSSProperties}
+          />
+        </div>
+        <div
+          aria-hidden="true"
+          data-slot="gooey-popover-shape"
+          className={cn("pointer-events-none absolute", tones)}
+          style={{ "--gooey-radius": "1.125rem" } as CSSProperties}
+        />
+        <div
+          aria-hidden="true"
+          data-slot="gooey-popover-ghost"
+          className={cn(
+            "pointer-events-none absolute flex items-center justify-center rounded-full",
+            tones,
+          )}
+          style={atTrigger}
+        >
+          {trigger}
+        </div>
+        <div
+          data-slot="gooey-popover-body"
+          className={cn("relative p-4", tones, "bg-transparent")}
+        >
+          {children}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export { gooeyPopoverVariants };

package/src/components/gooey-popover/index.ts

@@ -0,0 +1 @@
+export { GooeyPopover, gooeyPopoverVariants, type GooeyPopoverProps } from "./gooey-popover";

package/src/components/gooey-popover/meta.ts

@@ -0,0 +1,20 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "gooey-popover",
+  title: "Gooey Popover",
+  description:
+    "A round trigger whose popover pours out of it, melted together by an SVG goo filter.",
+  category: "overlay",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["popover"],
+  files: ["gooey-popover.tsx"],
+  a11y:
+    "Built on Dowel's Popover (Radix): the icon-only trigger is named by `triggerLabel` and exposes " +
+    'aria-expanded; the content is a role="dialog" named by `triggerLabel` unless given aria-label or ' +
+    "aria-labelledby. Opens from pointer or keyboard, moves focus into the content, closes on Escape or an " +
+    "outside press, and returns focus to the trigger. The blob, goo layer and the copy of the trigger icon " +
+    "drawn over it are aria-hidden and ignore the pointer. Under reduced motion the goo layer is dropped and " +
+    "the panel appears in place.",
+});

package/src/components/gradient-orb/gradient-orb.tsx

@@ -0,0 +1,230 @@
+// Ported from SmoothUI Siri Orb (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import type { ComponentPropsWithRef, CSSProperties } from "react";
+
+import { cn } from "@/lib/utils";
+
+/*
+ * A mesh of rotating conic gradients, blurred and contrast-boosted into a
+ * glowing orb, with a dot screen, a drifting specular sheen and a lit rim on
+ * top.
+ *
+ * All of it is CSS. The rotation animates a registered custom property
+ * (`@property`), so the gradients turn without the element turning — nothing
+ * here needs JavaScript per frame, and the component renders on the server.
+ *
+ * It is decoration. It is aria-hidden unless named, carries no
+ * data-motion="indicator", and under reduced motion the global blanket stops
+ * every loop, leaving the settled first frame. An orb that is meant to report
+ * that an assistant is busy should sit beside a text status, never replace one.
+ */
+
+const PREFIX = "dowel-gradient-orb";
+
+/** A duration in milliseconds, scaled so reduced motion collapses it. */
+function scaled(ms: number): string {
+  return `calc(${ms.toFixed(0)}ms * var(--motion-scale, 1))`;
+}
+
+const STYLES = `
+@property --${PREFIX}-angle{syntax:"<angle>";inherits:false;initial-value:0deg}
+.${PREFIX}{position:relative;display:inline-block;flex-shrink:0;width:var(--orb-size);height:var(--orb-size)}
+.${PREFIX}[data-state=idle]{animation:${PREFIX}-breathe var(--orb-breathe) var(--ease-in-out-quint) infinite}
+.${PREFIX}[data-state=error]{animation:${PREFIX}-shake var(--orb-shake) var(--ease-in-out-quint) 1}
+.${PREFIX} [data-slot=gradient-orb-glow]{position:absolute;inset:-12%;border-radius:9999px;pointer-events:none;background:radial-gradient(circle at 50% 50%,var(--orb-c2) 0%,transparent 64%);filter:blur(calc(var(--orb-size) * .28));opacity:var(--orb-glow);transition:opacity var(--duration-slow) var(--ease-out-quint)}
+.${PREFIX} [data-slot=gradient-orb-disc]{position:relative;display:grid;width:100%;height:100%;overflow:hidden;border-radius:9999px;isolation:isolate;filter:saturate(var(--orb-saturation)) hue-rotate(var(--orb-hue));scale:calc(var(--orb-scale) + var(--orb-amplitude) * var(--orb-reactivity) * .12);transition:scale var(--duration-slow) var(--ease-out-quint),filter var(--duration-slow) var(--ease-out-quint)}
+.${PREFIX} [data-slot=gradient-orb-disc]::before,.${PREFIX} [data-slot=gradient-orb-disc]::after,.${PREFIX} [data-slot=gradient-orb-disc]>span{content:"";display:block;grid-area:1/1;width:100%;height:100%;border-radius:9999px}
+.${PREFIX} [data-slot=gradient-orb-disc]::before{background:conic-gradient(from calc(var(--${PREFIX}-angle) * 2) at 25% 70%,var(--orb-c3),transparent 20% 80%,var(--orb-c3)),conic-gradient(from calc(var(--${PREFIX}-angle) * 2) at 45% 75%,var(--orb-c2),transparent 30% 60%,var(--orb-c2)),conic-gradient(from calc(var(--${PREFIX}-angle) * -3) at 80% 20%,var(--orb-c1),transparent 40% 60%,var(--orb-c1)),conic-gradient(from calc(var(--${PREFIX}-angle) * 1.5) at 60% 35%,var(--orb-c4),transparent 25% 75%,var(--orb-c4)),conic-gradient(from calc(var(--${PREFIX}-angle) * 2) at 15% 5%,var(--orb-c2),transparent 10% 90%,var(--orb-c2)),conic-gradient(from calc(var(--${PREFIX}-angle) * 1) at 20% 80%,var(--orb-c1),transparent 10% 90%,var(--orb-c1)),conic-gradient(from calc(var(--${PREFIX}-angle) * -2) at 85% 10%,var(--orb-c3),transparent 20% 80%,var(--orb-c3));box-shadow:inset var(--orb-bg) 0 0 var(--orb-shadow) calc(var(--orb-shadow) * .2);filter:blur(calc(var(--orb-blur) * (1 - var(--orb-amplitude) * var(--orb-reactivity) * .45))) contrast(var(--orb-contrast)) saturate(1.4);animation:${PREFIX}-rotate var(--orb-period) linear infinite}
+.${PREFIX} [data-slot=gradient-orb-disc]::after{background-image:radial-gradient(circle at center,var(--orb-bg) var(--orb-dot),transparent var(--orb-dot));background-size:calc(var(--orb-dot) * 2) calc(var(--orb-dot) * 2);backdrop-filter:blur(calc(var(--orb-blur) * 2)) contrast(calc(var(--orb-contrast) * 2));mix-blend-mode:overlay;mask-image:radial-gradient(var(--orb-c1) var(--orb-mask),transparent 75%)}
+.${PREFIX}[data-tiny] [data-slot=gradient-orb-disc]::after{mask-image:none}
+.${PREFIX} [data-slot=gradient-orb-sheen]{background:radial-gradient(circle at 30% 24%,color-mix(in oklab,var(--orb-highlight) 32%,transparent),transparent 34%),radial-gradient(circle at 72% 80%,color-mix(in oklab,var(--orb-highlight) 7%,transparent),transparent 48%);mix-blend-mode:screen;animation:${PREFIX}-drift var(--orb-drift) var(--ease-in-out-quint) infinite alternate}
+.${PREFIX} [data-slot=gradient-orb-rim]{pointer-events:none;box-shadow:inset 0 0 0 1px color-mix(in oklab,var(--orb-highlight) 16%,transparent),inset 0 var(--orb-rim) calc(var(--orb-rim) * 2) color-mix(in oklab,var(--orb-highlight) 22%,transparent),inset 0 calc(var(--orb-rim) * -1.2) calc(var(--orb-rim) * 2.4) color-mix(in oklab,var(--color-overlay) 40%,transparent)}
+@keyframes ${PREFIX}-rotate{to{--${PREFIX}-angle:360deg}}
+@keyframes ${PREFIX}-drift{0%{transform:translate(-6%,-4%) scale(1.05)}100%{transform:translate(7%,6%) scale(1.12)}}
+@keyframes ${PREFIX}-breathe{0%,100%{scale:1}50%{scale:1.035}}
+@keyframes ${PREFIX}-shake{0%,100%{translate:0}33%{translate:-3px}66%{translate:3px}}
+`;
+
+export type GradientOrbState =
+  "idle" | "listening" | "thinking" | "streaming" | "speaking" | "done" | "error";
+
+interface StatePreset {
+  /** Loop speed multiplier. */
+  speed: number;
+  /** Resting scale of the disc. Thinking stays at 1 so layout stays calm. */
+  scale: number;
+  saturation: number;
+  /** Degrees of hue rotation, a mood shift rather than a new palette. */
+  hue: number;
+  /** Bloom opacity, 0–1. */
+  glow: number;
+  /** How much `amplitude` reaches the surface. */
+  reactivity: number;
+}
+
+/** No state: plain decoration at its base tempo, with no bloom. */
+const AMBIENT: StatePreset = {
+  speed: 1,
+  scale: 1,
+  saturation: 1,
+  hue: 0,
+  glow: 0,
+  reactivity: 0.6,
+};
+
+/** SmoothUI's shared AI state presets, as the orb reads them. */
+const STATES: Record<GradientOrbState, StatePreset> = {
+  idle: { speed: 0.6, scale: 0.94, saturation: 0.75, hue: 0, glow: 0.15, reactivity: 0 },
+  listening: { speed: 1, scale: 1.06, saturation: 1.05, hue: 0, glow: 0.6, reactivity: 1 },
+  thinking: { speed: 2.4, scale: 1, saturation: 1, hue: 18, glow: 0.35, reactivity: 0.15 },
+  streaming: { speed: 1.4, scale: 1.02, saturation: 1, hue: -10, glow: 0.45, reactivity: 0.6 },
+  speaking: { speed: 1.4, scale: 1.02, saturation: 1, hue: -10, glow: 0.45, reactivity: 0.6 },
+  done: { speed: 0.8, scale: 1.1, saturation: 1, hue: 0, glow: 0.7, reactivity: 0 },
+  // Error desaturates rather than growing: a state change, not an alarm.
+  error: { speed: 1, scale: 0.96, saturation: 0.3, hue: 0, glow: 0.25, reactivity: 0 },
+};
+
+export interface GradientOrbColors {
+  /** The field behind the mesh, and the dot screen over it. */
+  bg?: string;
+  c1?: string;
+  c2?: string;
+  c3?: string;
+  /** Fourth mesh stop. More stops means fewer visible repeats per turn. */
+  c4?: string;
+  /** Specular sheen and the lit top edge. */
+  highlight?: string;
+}
+
+/** Theme tokens, so the orb follows the palette and dark mode. */
+const DEFAULT_COLORS: Required<GradientOrbColors> = {
+  bg: "color-mix(in oklab, var(--color-primary) 12%, var(--color-background))",
+  c1: "var(--color-primary)",
+  c2: "var(--color-info)",
+  c3: "color-mix(in oklab, var(--color-primary) 55%, var(--color-info))",
+  c4: "color-mix(in oklab, var(--color-info) 60%, var(--color-success))",
+  // Screen-blended, so any hue lightens: a light token would vanish in dark mode.
+  highlight: "var(--color-info)",
+};
+
+type Geometry = Record<
+  "--orb-blur" | "--orb-contrast" | "--orb-dot" | "--orb-shadow" | "--orb-mask" | "--orb-rim",
+  string
+> & { tiny: boolean };
+
+/**
+ * Size-dependent tuning. At 24px the large-orb blur and dot screen turn it to
+ * mud, so small sizes get less of each — exact when `size` is a number.
+ */
+function geometry(size: number | string): Geometry {
+  if (typeof size === "string") {
+    return {
+      "--orb-blur": "max(calc(var(--orb-size) * .015), 4px)",
+      "--orb-contrast": "1.5",
+      "--orb-dot": "max(calc(var(--orb-size) * .008), .1px)",
+      "--orb-shadow": "max(calc(var(--orb-size) * .008), 2px)",
+      "--orb-mask": "25%",
+      "--orb-rim": "max(calc(var(--orb-size) * .06), 1.5px)",
+      tiny: false,
+    };
+  }
+  const small = size < 50;
+  const contrast = small ? Math.max(size * 0.004, 1.2) : Math.max(size * 0.008, 1.5);
+  const px = (value: number) => `${value.toFixed(2)}px`;
+  return {
+    "--orb-blur": px(small ? Math.max(size * 0.008, 1) : Math.max(size * 0.015, 4)),
+    "--orb-contrast": (size < 30
+      ? 1.1
+      : small
+        ? Math.max(contrast * 1.2, 1.3)
+        : contrast
+    ).toFixed(3),
+    "--orb-dot": px(small ? Math.max(size * 0.004, 0.05) : Math.max(size * 0.008, 0.1)),
+    "--orb-shadow": px(small ? Math.max(size * 0.004, 0.5) : Math.max(size * 0.008, 2)),
+    "--orb-mask": size < 30 ? "0%" : small ? "5%" : size < 100 ? "15%" : "25%",
+    "--orb-rim": px(Math.max(size * 0.06, 1.5)),
+    tiny: size < 30,
+  };
+}
+
+export interface GradientOrbProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  /** Diameter. A number is pixels; a string is any CSS length. */
+  size?: number | string;
+  /**
+   * Shared AI state: changes tempo, scale, saturation and bloom. Omit it for
+   * plain decoration at the base tempo.
+   */
+  state?: GradientOrbState;
+  /**
+   * Live audio level, 0–1. Tightens the blur and swells the disc while the
+   * state listens (`listening`, `streaming`, `speaking`, and — faintly —
+   * `thinking`). For a 60fps signal, skip the re-render: set the
+   * `--orb-amplitude` custom property on the element through its ref.
+   */
+  amplitude?: number;
+  /** Seconds per rotation of the mesh at the base tempo. */
+  duration?: number;
+  /** Any CSS colours — tokens by default. */
+  colors?: GradientOrbColors;
+}
+
+/** An animated gradient orb — the voice-assistant blob. Decorative. */
+export function GradientOrb({
+  className,
+  size = 192,
+  state,
+  amplitude = 0,
+  duration = 20,
+  colors,
+  style,
+  ...props
+}: GradientOrbProps) {
+  const preset = state ? STATES[state] : AMBIENT;
+  const palette = { ...DEFAULT_COLORS, ...colors };
+  const { tiny, ...tuning } = geometry(size);
+  const named = props["aria-label"] != null || props["aria-labelledby"] != null;
+
+  const variables = {
+    "--orb-size": typeof size === "number" ? `${String(size)}px` : size,
+    "--orb-bg": palette.bg,
+    "--orb-c1": palette.c1,
+    "--orb-c2": palette.c2,
+    "--orb-c3": palette.c3,
+    "--orb-c4": palette.c4,
+    "--orb-highlight": palette.highlight,
+    "--orb-period": scaled((duration * 1000) / preset.speed),
+    "--orb-drift": scaled((12 / (1 + preset.speed)) * 2 * 1000),
+    "--orb-breathe": scaled(5500),
+    "--orb-shake": scaled(180),
+    "--orb-scale": String(preset.scale),
+    "--orb-saturation": String(preset.saturation),
+    "--orb-hue": `${String(preset.hue)}deg`,
+    "--orb-glow": String(preset.glow),
+    "--orb-reactivity": String(preset.reactivity),
+    "--orb-amplitude": String(Math.min(1, Math.max(0, amplitude))),
+    ...tuning,
+  } as CSSProperties;
+
+  return (
+    <>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <div
+        data-slot="gradient-orb"
+        data-state={state}
+        data-tiny={tiny ? "" : undefined}
+        role={named ? "img" : undefined}
+        aria-hidden={named ? undefined : true}
+        className={cn(PREFIX, className)}
+        style={{ ...variables, ...style }}
+        {...props}
+      >
+        <span data-slot="gradient-orb-glow" />
+        <span data-slot="gradient-orb-disc">
+          <span data-slot="gradient-orb-sheen" />
+          <span data-slot="gradient-orb-rim" />
+        </span>
+      </div>
+    </>
+  );
+}

package/src/components/gradient-orb/index.ts

@@ -0,0 +1,6 @@
+export {
+  GradientOrb,
+  type GradientOrbColors,
+  type GradientOrbProps,
+  type GradientOrbState,
+} from "./gradient-orb";

package/src/components/gradient-orb/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "gradient-orb",
+  title: "Gradient Orb",
+  description:
+    "An animated gradient orb — a rotating conic mesh with a dot screen, sheen and bloom — that can follow an AI state and a live audio level.",
+  category: "effects",
+  status: "beta",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["gradient-orb.tsx"],
+  a11y:
+    'Decorative: aria-hidden unless given aria-label or aria-labelledby, when it becomes role="img". It never ' +
+    "reports state on its own — pair it with a text status. Pure CSS; under reduced motion every loop stops and " +
+    "the orb shows its settled first frame.",
+});