@dowel-ui/react 0.5.0 → 0.8.0

package/src/components/ring-loader/ring-loader.tsx

@@ -0,0 +1,795 @@
+// Ported from amicro "Rings & Spinners" (MIT, © 2026 Syed Subhan Uddin). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, CSSProperties, ReactNode } from "react";
+
+import { cn } from "@/lib/utils";
+
+/*
+ * Same shape as the dots loader (ADR 0014): geometry in `em` (source px ÷ 8),
+ * colour from `currentColor`, keyframes shipped through React's hoisted
+ * <style>, every duration and delay scaled by --motion-scale-indicator, and
+ * `direction: ltr` on the root so a clockwise spin stays clockwise in RTL.
+ *
+ * Renamed from the source: "iOS Spinner" → `petals`.
+ *
+ * Where the source animates two properties with different easing (Dual Arc,
+ * Morphing Ring), each property gets its own keyframe and the part lists both
+ * names, so each keeps its own timing function.
+ */
+
+const PREFIX = "dowel-ring-loader";
+
+/** A delay or duration in seconds, scaled for reduced motion. */
+function scaled(seconds: number): string {
+  return `calc(${String(seconds)}s * var(--motion-scale-indicator, 1))`;
+}
+
+/** currentColor at a given strength — the faint track and secondary strokes. */
+function faint(percent: number): string {
+  return `color-mix(in oklab, currentColor ${String(percent)}%, transparent)`;
+}
+
+const STYLES = `
+.${PREFIX}{direction:ltr;position:relative;display:inline-flex;align-items:center;justify-content:center;flex-shrink:0;color:inherit}
+.${PREFIX} [data-part]{display:block;box-sizing:border-box;flex-shrink:0;border-radius:9999px;background:currentColor;animation-iteration-count:infinite;animation-timing-function:linear;animation-duration:var(--dur);animation-delay:var(--delay,0s)}
+.${PREFIX} [data-part=static]{animation:none}
+.${PREFIX} [data-part=ring],.${PREFIX} [data-part=track]{background:transparent;border-style:solid;border-color:currentColor}
+.${PREFIX} [data-part=track]{animation:none}
+.${PREFIX} [data-part=layer]{position:absolute;inset:0;background:transparent;border-radius:0}
+.${PREFIX} [data-part=frame]{background:transparent;border-radius:0;animation:none;overflow:visible}
+.${PREFIX} [data-part=svg]{background:transparent;border-radius:0;overflow:visible}
+.${PREFIX} [data-part=stroke]{background:none;border-radius:0}
+@keyframes ${PREFIX}-spin{to{transform:rotate(360deg)}}
+@keyframes ${PREFIX}-spin-reverse{to{transform:rotate(-360deg)}}
+@keyframes ${PREFIX}-half-turn{from{transform:rotate(0deg)}to{transform:rotate(180deg)}}
+@keyframes ${PREFIX}-quarter-turn{from{transform:rotate(0deg)}to{transform:rotate(90deg)}}
+@keyframes ${PREFIX}-quarters{0%{transform:rotate(0deg)}25%{transform:rotate(90deg)}50%{transform:rotate(180deg)}75%{transform:rotate(270deg)}100%{transform:rotate(360deg)}}
+@keyframes ${PREFIX}-flip{0%{transform:rotate(0deg)}50%{transform:rotate(180deg)}100%{transform:rotate(360deg)}}
+@keyframes ${PREFIX}-flip-reverse{0%{transform:rotate(0deg)}50%{transform:rotate(-180deg)}100%{transform:rotate(-360deg)}}
+@keyframes ${PREFIX}-fade-out{from{opacity:1}to{opacity:.2}}
+@keyframes ${PREFIX}-dot-pulse{0%,100%{transform:rotate(var(--angle)) scale(1);opacity:1}50%{transform:rotate(var(--angle)) scale(.5);opacity:.3}}
+@keyframes ${PREFIX}-tumble-a{from{transform:rotateX(0deg) rotateY(0deg)}to{transform:rotateX(360deg) rotateY(180deg)}}
+@keyframes ${PREFIX}-tumble-b{from{transform:rotateX(0deg) rotateY(0deg)}to{transform:rotateX(180deg) rotateY(360deg)}}
+@keyframes ${PREFIX}-pinch{0%,100%{scale:1}50%{scale:.82}}
+@keyframes ${PREFIX}-trace{0%{stroke-dashoffset:125}50%{stroke-dashoffset:0}100%{stroke-dashoffset:-125}}
+@keyframes ${PREFIX}-morph{0%,100%{border-radius:10%}50%{border-radius:50%}}
+@keyframes ${PREFIX}-expand{from{transform:scale(.1);opacity:1}to{transform:scale(1.25);opacity:0}}
+@keyframes ${PREFIX}-breathe{0%,100%{transform:scale(.8);border-width:.75em}50%{transform:scale(1.1);border-width:.25em}}
+@keyframes ${PREFIX}-spiral{0%{transform:rotate(0deg) scale(1)}50%{transform:rotate(180deg) scale(1.1)}100%{transform:rotate(360deg) scale(1)}}
+`;
+
+type Variant = {
+  /** Layout of the root, inline so it outranks the unlayered hoisted stylesheet. */
+  root: CSSProperties;
+  render: () => ReactNode;
+};
+
+type Motion = {
+  /** One keyframe name, or several separated by commas. */
+  name: string;
+  duration: number;
+  delay?: number;
+  /** One timing function, or one per keyframe name. Defaults to linear. */
+  ease?: string;
+};
+
+const EASE_IN_OUT = "ease-in-out";
+/** The source's `type: "spring", bounce: 0.4`, as an overshooting curve per step. */
+const SPRING = "cubic-bezier(0.34, 1.56, 0.64, 1)";
+
+/** A part of the loader, with its keyframes, duration and delay. */
+function part(
+  key: number | string,
+  kind: string,
+  style: CSSProperties,
+  motion?: Motion,
+  children?: ReactNode,
+): ReactNode {
+  const css: CSSProperties & Record<`--${string}`, string> = { ...style };
+  if (motion) {
+    css.animationName = motion.name
+      .split(",")
+      .map((name) => `${PREFIX}-${name.trim()}`)
+      .join(", ");
+    if (motion.ease) css.animationTimingFunction = motion.ease;
+    css["--dur"] = scaled(motion.duration);
+    css["--delay"] = scaled(motion.delay ?? 0);
+  }
+  return (
+    <span key={key} data-part={motion ? kind : kind === "ring" ? "track" : kind} style={css}>
+      {children}
+    </span>
+  );
+}
+
+/** A bordered circle; `colors` is the four-side border-color shorthand. */
+function ring(
+  key: number | string,
+  size: string,
+  width: string,
+  colors: string,
+  motion?: Motion,
+  extra: CSSProperties = {},
+): ReactNode {
+  return part(
+    key,
+    "ring",
+    { width: size, height: size, borderWidth: width, borderColor: colors, ...extra },
+    motion,
+  );
+}
+
+const ABSOLUTE: CSSProperties = { position: "absolute" };
+
+function box(size: string): CSSProperties {
+  return { width: size, height: size };
+}
+
+/** Twelve bars around a centre, fading in turn. */
+function blades(width: string, height: string, radius: string): ReactNode {
+  return Array.from({ length: 12 }, (_, index) =>
+    part(
+      index,
+      "bar",
+      {
+        position: "absolute",
+        top: 0,
+        left: `calc(50% - ${width} / 2)`,
+        width,
+        height,
+        transformOrigin: `calc(${width} / 2) ${radius}`,
+        transform: `rotate(${String(index * 30)}deg)`,
+      },
+      { name: "fade-out", duration: 1, delay: index / 12 },
+    ),
+  );
+}
+
+/** An SVG ring: a faint track and a stroked arc, in a viewBox of `view`. */
+function svg(size: string, view: number, circles: ReactNode, motion?: Motion): ReactNode {
+  const css: CSSProperties & Record<`--${string}`, string> = { width: size, height: size };
+  if (motion) {
+    css.animationName = `${PREFIX}-${motion.name}`;
+    css["--dur"] = scaled(motion.duration);
+    css["--delay"] = scaled(motion.delay ?? 0);
+  }
+  return (
+    <svg
+      data-part={motion ? "svg" : "frame"}
+      viewBox={`0 0 ${String(view)} ${String(view)}`}
+      fill="none"
+      stroke="currentColor"
+      aria-hidden="true"
+      style={css}
+    >
+      {circles}
+    </svg>
+  );
+}
+
+/** Keeps the variant names as literal keys while typing each entry as a plain Variant. */
+function defineVariants<Name extends string>(variants: Record<Name, Variant>) {
+  return variants;
+}
+
+const VARIANTS = defineVariants({
+  classic: { root: box("4em"), render: () => blades("0.5em", "1em", "2em") },
+  sweep: {
+    root: {},
+    render: () =>
+      ring(0, "5em", "0.375em", `currentColor ${faint(20)} ${faint(20)} ${faint(20)}`, {
+        name: "spin",
+        duration: 1,
+      }),
+  },
+  concentric: {
+    root: box("6em"),
+    render: () => [
+      ring(
+        0,
+        "6em",
+        "0.25em",
+        "transparent currentColor currentColor",
+        {
+          name: "spin",
+          duration: 2,
+        },
+        ABSOLUTE,
+      ),
+      ring(
+        1,
+        "4em",
+        "0.25em",
+        "currentColor currentColor transparent",
+        {
+          name: "spin-reverse",
+          duration: 1.5,
+        },
+        { ...ABSOLUTE, opacity: 0.6 },
+      ),
+      ring(
+        2,
+        "2em",
+        "0.25em",
+        "currentColor currentColor currentColor transparent",
+        {
+          name: "spin",
+          duration: 1,
+        },
+        { ...ABSOLUTE, opacity: 0.35 },
+      ),
+    ],
+  },
+  "dot-ring": {
+    root: box("6em"),
+    render: () =>
+      Array.from({ length: 8 }, (_, index) =>
+        part(
+          index,
+          "dot",
+          {
+            position: "absolute",
+            top: 0,
+            left: "calc(50% - 0.5em)",
+            width: "1em",
+            height: "1em",
+            transformOrigin: "0.5em 3em",
+            transform: `rotate(${String(index * 45)}deg)`,
+            ["--angle" as string]: `${String(index * 45)}deg`,
+          },
+          { name: "dot-pulse", duration: 1.5, delay: index * 0.15, ease: EASE_IN_OUT },
+        ),
+      ),
+  },
+  twin: {
+    root: box("6em"),
+    render: () => [
+      ring(
+        0,
+        "auto",
+        "0.25em",
+        "currentColor transparent transparent currentColor",
+        {
+          name: "spin",
+          duration: 1.5,
+        },
+        { position: "absolute", inset: 0 },
+      ),
+      ring(
+        1,
+        "auto",
+        "0.25em",
+        "transparent currentColor currentColor transparent",
+        {
+          name: "spin-reverse",
+          duration: 1.5,
+        },
+        { position: "absolute", inset: "1em", opacity: 0.7 },
+      ),
+    ],
+  },
+  comet: {
+    root: { ...box("5em"), borderRadius: "9999px", border: `0.125em solid ${faint(15)}` },
+    render: () =>
+      part(
+        0,
+        "layer",
+        {
+          borderRadius: "9999px",
+          background: `conic-gradient(from 0deg, transparent 0%, ${faint(10)} 60%, currentColor 100%)`,
+          maskImage: "radial-gradient(closest-side, transparent 84%, black 84%)",
+          WebkitMaskImage: "radial-gradient(closest-side, transparent 84%, black 84%)",
+        },
+        { name: "spin", duration: 1 },
+      ),
+  },
+  swirl: {
+    root: box("5em"),
+    render: () => [
+      ring(
+        0,
+        "auto",
+        "0.3125em",
+        `currentColor ${faint(30)} ${faint(10)} transparent`,
+        {
+          name: "spin",
+          duration: 1.3,
+        },
+        { position: "absolute", inset: 0 },
+      ),
+      ring(
+        1,
+        "3em",
+        "0.3125em",
+        `${faint(30)} ${faint(10)} currentColor transparent`,
+        {
+          name: "spin-reverse",
+          duration: 0.9,
+        },
+        ABSOLUTE,
+      ),
+    ],
+  },
+  radar: {
+    root: {
+      ...box("6em"),
+      borderRadius: "9999px",
+      border: `0.125em solid ${faint(10)}`,
+      overflow: "hidden",
+    },
+    render: () => [
+      ring("r1", "4em", "0.125em", faint(5), undefined, ABSOLUTE),
+      ring("r2", "2em", "0.125em", faint(5), undefined, ABSOLUTE),
+      part("core", "static", { ...ABSOLUTE, ...box("0.75em"), opacity: 0.8 }),
+      part(
+        "sweep",
+        "layer",
+        {
+          background: `conic-gradient(from 0deg, transparent 50%, ${faint(2)} 65%, ${faint(10)} 85%, ${faint(45)} 100%)`,
+        },
+        { name: "spin", duration: 1.8 },
+      ),
+    ],
+  },
+  orbit: {
+    root: box("5em"),
+    render: () => [
+      part("core", "static", { ...box("1em"), opacity: 0.3 }),
+      part(
+        "track",
+        "layer",
+        { borderRadius: "9999px", border: `0.125em solid ${faint(15)}` },
+        { name: "spin", duration: 2 },
+        part("dot", "static", {
+          position: "absolute",
+          top: "-0.75em",
+          left: "calc(50% - 0.75em)",
+          ...box("1.5em"),
+        }),
+      ),
+    ],
+  },
+  "orbit-pair": {
+    root: box("6em"),
+    render: () => [
+      part("core", "static", box("1.5em")),
+      ...(["spin", "spin-reverse"] as const).map((name) =>
+        part(
+          name,
+          "layer",
+          {},
+          { name, duration: 2 },
+          part("dot", "static", {
+            position: "absolute",
+            top: 0,
+            left: "calc(50% - 0.5em)",
+            ...box("1em"),
+            opacity: 0.6,
+          }),
+        ),
+      ),
+    ],
+  },
+  intersect: {
+    root: { ...box("6em"), perspective: "100em" },
+    render: () => [
+      ring(
+        0,
+        "5em",
+        "0.25em",
+        `currentColor ${faint(30)} ${faint(10)} transparent`,
+        {
+          name: "tumble-a",
+          duration: 2.2,
+        },
+        { ...ABSOLUTE, transformStyle: "preserve-3d" },
+      ),
+      ring(
+        1,
+        "5em",
+        "0.25em",
+        `${faint(30)} transparent currentColor ${faint(10)}`,
+        {
+          name: "tumble-b",
+          duration: 2.2,
+        },
+        { ...ABSOLUTE, transformStyle: "preserve-3d" },
+      ),
+    ],
+  },
+  clock: {
+    root: { ...box("5em"), borderRadius: "9999px", border: "0.25em solid currentColor" },
+    render: () =>
+      (
+        [
+          ["minute", "1.75em", 2],
+          ["hour", "1.25em", 12],
+        ] as const
+      ).map(([key, height, duration]) =>
+        part(
+          key,
+          "bar",
+          {
+            position: "absolute",
+            bottom: "50%",
+            left: "calc(50% - 0.125em)",
+            width: "0.25em",
+            height,
+            transformOrigin: "50% 100%",
+          },
+          { name: "spin", duration },
+        ),
+      ),
+  },
+  gears: {
+    root: { alignItems: "flex-start" },
+    render: () => [
+      ring(
+        0,
+        "4em",
+        "0.5em",
+        "currentColor",
+        { name: "spin", duration: 4 },
+        {
+          borderStyle: "dashed",
+        },
+      ),
+      ring(
+        1,
+        "3em",
+        "0.375em",
+        "currentColor",
+        { name: "spin-reverse", duration: 3 },
+        {
+          borderStyle: "dashed",
+          marginTop: "1.5em",
+          marginLeft: "-0.5em",
+          opacity: 0.6,
+        },
+      ),
+    ],
+  },
+  cross: {
+    root: box("4em"),
+    render: () =>
+      part(0, "layer", {}, { name: "quarters", duration: 2, ease: EASE_IN_OUT }, [
+        part("h", "static", {
+          position: "absolute",
+          top: "calc(50% - 0.375em)",
+          left: 0,
+          width: "100%",
+          height: "0.75em",
+        }),
+        part("v", "static", {
+          position: "absolute",
+          top: 0,
+          left: "calc(50% - 0.375em)",
+          width: "0.75em",
+          height: "100%",
+        }),
+      ]),
+  },
+  line: {
+    root: box("5em"),
+    render: () => [
+      ring("track", "5em", "0.25em", faint(20), undefined, ABSOLUTE),
+      part("bar", "bar", { width: "4em", height: "0.5em" }, { name: "spin", duration: 1.2 }),
+    ],
+  },
+  square: {
+    root: {},
+    render: () =>
+      part(
+        0,
+        "ring",
+        {
+          ...box("4em"),
+          borderWidth: "0.25em",
+          borderRadius: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+        },
+        { name: "quarter-turn", duration: 0.6, ease: EASE_IN_OUT },
+        part("core", "static", { ...box("1em"), borderRadius: 0 }),
+      ),
+  },
+  "dual-arc": {
+    root: box("4em"),
+    render: () =>
+      ring(
+        0,
+        "auto",
+        "0.25em",
+        "currentColor transparent",
+        {
+          name: "spin, pinch",
+          duration: 1.2,
+          ease: `linear, ${EASE_IN_OUT}`,
+        },
+        { position: "absolute", inset: 0 },
+      ),
+  },
+  "fade-arc": {
+    root: {},
+    render: () =>
+      svg(
+        "4.5em",
+        50,
+        <>
+          <circle cx="25" cy="25" r="20" strokeWidth="3.5" strokeOpacity="0.2" />
+          <circle
+            cx="25"
+            cy="25"
+            r="20"
+            strokeWidth="3.5"
+            strokeDasharray="80"
+            strokeDashoffset="28"
+            strokeLinecap="round"
+          />
+        </>,
+        { name: "spin", duration: 1 },
+      ),
+  },
+  dash: {
+    root: {},
+    render: () =>
+      svg("6em", 50, <circle cx="25" cy="25" r="20" strokeWidth="3" strokeDasharray="8 8" />, {
+        name: "spin",
+        duration: 4,
+      }),
+  },
+  tracer: {
+    root: {},
+    render: () =>
+      svg(
+        "5em",
+        50,
+        <>
+          <circle cx="25" cy="25" r="20" strokeWidth="4" strokeOpacity="0.2" />
+          <circle
+            data-part="stroke"
+            cx="25"
+            cy="25"
+            r="20"
+            strokeWidth="4"
+            strokeLinecap="round"
+            strokeDasharray="125"
+            style={
+              {
+                animationName: `${PREFIX}-trace`,
+                animationTimingFunction: EASE_IN_OUT,
+                "--dur": scaled(2),
+                "--delay": scaled(0),
+              } as CSSProperties
+            }
+          />
+        </>,
+      ),
+  },
+  petals: { root: box("4em"), render: () => blades("0.25em", "0.875em", "2em") },
+  smooth: {
+    root: {},
+    render: () =>
+      svg(
+        "4.5em",
+        32,
+        <>
+          <circle cx="16" cy="16" r="14" strokeWidth="3" strokeOpacity="0.2" />
+          <circle
+            cx="16"
+            cy="16"
+            r="14"
+            strokeWidth="3"
+            strokeDasharray="38 80"
+            strokeLinecap="round"
+          />
+        </>,
+        { name: "spin", duration: 1 },
+      ),
+  },
+  morph: {
+    root: {},
+    render: () =>
+      ring(
+        0,
+        "5em",
+        "0.375em",
+        "currentColor",
+        {
+          name: "half-turn, morph",
+          duration: 2,
+          ease: EASE_IN_OUT,
+        },
+        { borderRadius: "10%" },
+      ),
+  },
+  expand: {
+    root: box("6em"),
+    render: () =>
+      [0, 1].map((index) =>
+        ring(
+          index,
+          "5em",
+          "0.25em",
+          "currentColor",
+          {
+            name: "expand",
+            duration: 1.6,
+            delay: index * 0.8,
+            ease: "ease-out",
+          },
+          { ...ABSOLUTE, transform: "scale(0.1)" },
+        ),
+      ),
+  },
+  watch: {
+    root: box("6em"),
+    render: () =>
+      [0, 1, 2].map((index) =>
+        ring(
+          index,
+          `${String(5.5 - index * 1.5)}em`,
+          "0.375em",
+          "currentColor transparent transparent",
+          {
+            name: "spin",
+            duration: 1 + index * 0.5,
+            ease: EASE_IN_OUT,
+          },
+          ABSOLUTE,
+        ),
+      ),
+  },
+  gradient: {
+    root: {},
+    render: () =>
+      part(
+        0,
+        "dot",
+        {
+          ...box("5em"),
+          background: "conic-gradient(from 0deg, transparent, currentColor)",
+          maskImage: "radial-gradient(transparent 55%, black 60%)",
+          WebkitMaskImage: "radial-gradient(transparent 55%, black 60%)",
+        },
+        { name: "spin", duration: 1.2 },
+      ),
+  },
+  breathe: {
+    root: box("5em"),
+    render: () =>
+      ring(0, "5em", "0.5em", "currentColor", {
+        name: "breathe",
+        duration: 3,
+        ease: EASE_IN_OUT,
+      }),
+  },
+  offset: {
+    root: box("6em"),
+    render: () => [
+      ring(
+        0,
+        "6em",
+        "0.25em",
+        "currentColor transparent",
+        {
+          name: "flip",
+          duration: 2,
+          ease: EASE_IN_OUT,
+        },
+        ABSOLUTE,
+      ),
+      ring(
+        1,
+        "4em",
+        "0.25em",
+        "transparent currentColor",
+        {
+          name: "flip-reverse",
+          duration: 2,
+          delay: 0.2,
+          ease: EASE_IN_OUT,
+        },
+        { ...ABSOLUTE, opacity: 0.6 },
+      ),
+    ],
+  },
+  spiral: {
+    root: {},
+    render: () =>
+      ring(
+        0,
+        "5em",
+        "0.375em",
+        "currentColor",
+        { name: "spiral", duration: 4 },
+        {
+          borderStyle: "dashed",
+        },
+      ),
+  },
+  haptic: {
+    root: {},
+    render: () =>
+      ring(0, "5em", "0.375em", `currentColor ${faint(20)} ${faint(20)} ${faint(20)}`, {
+        name: "quarters",
+        duration: 2,
+        ease: SPRING,
+      }),
+  },
+});
+
+export type RingLoaderVariant = keyof typeof VARIANTS;
+
+/** Every variant, in catalogue order. Stories and tests iterate this. */
+export const ringLoaderVariantNames = Object.keys(VARIANTS) as RingLoaderVariant[];
+
+const ringLoaderVariants = cva("", {
+  variants: {
+    size: {
+      sm: "text-[0.25rem]",
+      md: "text-[0.375rem]",
+      lg: "text-[0.5rem]",
+      xl: "text-[0.625rem]",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+export interface RingLoaderProps
+  extends
+    Omit<ComponentPropsWithRef<"span">, "children">,
+    VariantProps<typeof ringLoaderVariants> {
+  /** Which animation to play. */
+  variant?: RingLoaderVariant;
+  /**
+   * Announced to assistive technology while the loader is visible.
+   *
+   * Omit it when the loader sits inside something that already reports its
+   * busy state — announcing twice is worse than not announcing at all.
+   */
+  label?: string;
+}
+
+/** An indeterminate loading indicator made of rings and spinners, in 30 motions. */
+export function RingLoader({
+  className,
+  size,
+  variant = "classic",
+  label,
+  style,
+  ...props
+}: RingLoaderProps) {
+  const spec: Variant = VARIANTS[variant];
+
+  return (
+    <>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <span
+        aria-hidden="true"
+        data-slot="ring-loader"
+        data-variant={variant}
+        // Exempt from the reduced-motion blanket: a loader that stops says the
+        // application has hung. It is slowed instead — see ADR 0014.
+        data-motion="indicator"
+        className={cn(PREFIX, ringLoaderVariants({ size }), className)}
+        style={{ ...spec.root, ...style }}
+        {...props}
+      >
+        {spec.render()}
+      </span>
+      {label ? (
+        <span role="status" className="sr-only">
+          {label}
+        </span>
+      ) : null}
+    </>
+  );
+}
+
+export { ringLoaderVariants };