makersclaw 0.1.0 → 0.3.0

package/registry/blocks/signature-pad/signature-pad.jsx

@@ -0,0 +1,434 @@
+"use client";
+
+// SignaturePad — sign by drawing or by typing your name, in the workspace
+// theme (signature_pad underneath for the drawing). A full-name field, a
+// paper box to draw on (undo the last stroke, clear with Undo), or the
+// name set in the theme's display face; then "Sign". What comes out is a
+// PNG (transparent, dark ink, cropped to the signature) and the typed
+// name, with when and how it was made.
+//
+// The pad is paper: whichever of the theme's background and foreground is
+// lighter, inked with the other (colors.js). On a dark theme that is a
+// light sheet — the way a signature looks on a page — and the PNG is what
+// you see.
+//
+// Client only in effect, not in import: the pad is created in an effect.
+// The server (and the first paint) shows the same frame, faded in once
+// the ink is known.
+import { useCallback, useEffect, useId, useImperativeHandle, useRef, useState } from "react";
+import { Button, Field, Icon, IconButton, Input, Notice, ToggleGroup, Tooltip, cx, toast } from "../../ui";
+import { SignaturePadEngine } from "./pad";
+import { paperAndInk, readTokens, watchTheme } from "./colors";
+import { formatSignedAt, missing, pointCount, signatureRecord, strokeBounds, withInk, withoutLast } from "./signature";
+
+/** A ref for the pad's handle: `const pad = useSignaturePad()`, then
+ *  `<SignaturePad padRef={pad} />` and `await pad.current?.toPNG()`. */
+export function useSignaturePad() {
+  return useRef(null);
+}
+
+const MODES = [
+  { value: "draw", label: "Draw", icon: "pencil" },
+  { value: "type", label: "Type", icon: "type" },
+];
+
+// Class names written out whole (Tailwind reads them literally), per paper.
+const PAPER = {
+  background: { box: "bg-background", hint: "text-muted-foreground", line: "bg-border", ink: "text-foreground", mark: "text-muted-foreground" },
+  foreground: { box: "bg-foreground", hint: "text-background/60", line: "bg-background/25", ink: "text-background", mark: "text-background/50" },
+};
+
+export function SignaturePad({
+  signer = "",
+  label = "Signature",
+  nameLabel = "Full name",
+  modes = ["draw", "type"],
+  defaultMode,
+  requireName = true,
+  value,
+  onChange,
+  onSubmit,
+  submitLabel = "Sign",
+  note,
+  disabled = false,
+  height = 176,
+  bare = false,
+  padRef,
+  className,
+}) {
+  const id = useId();
+  const rootRef = useRef(null);
+  const boxRef = useRef(null);
+  const canvasRef = useRef(null);
+  const typedRef = useRef(null);
+  const engine = useRef(null);
+  const strokes = useRef([]); // survives the canvas going away (signed view, mode switch)
+
+  const allowed = MODES.filter((m) => modes.includes(m.value));
+  const [mode, setMode] = useState(defaultMode && modes.includes(defaultMode) ? defaultMode : allowed[0]?.value ?? "draw");
+  const [name, setName] = useState(signer);
+  const nameRef = useRef(name);
+  nameRef.current = name;
+  const [drawn, setDrawn] = useState(0);
+  const [look, setLook] = useState({ paper: "background", ink: "foreground", inkColour: null, known: false });
+  const [errors, setErrors] = useState(null);
+  const [signed, setSigned] = useState(value?.png ? value : null);
+  const [saving, setSaving] = useState(false);
+  const [failed, setFailed] = useState(null);
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+
+  // A new `value` from the parent (a saved signature) shows as signed.
+  useEffect(() => {
+    if (value?.png) setSigned(value);
+  }, [value]);
+
+  const cbs = useRef({});
+  cbs.current = { onChange };
+  const tell = useCallback((next) => cbs.current.onChange?.(next), []);
+
+  // ---- the ink, from the theme ----------------------------------------------
+
+  useEffect(() => {
+    return watchTheme(rootRef.current, () => {
+      const next = paperAndInk(readTokens(rootRef.current, ["background", "foreground"]));
+      setLook((prev) => (prev.known && prev.inkColour === next.inkColour && prev.paper === next.paper ? prev : { ...next, known: true }));
+    });
+  }, []);
+
+  // ---- the drawing engine ---------------------------------------------------
+
+  const drawing = mode === "draw" && !signed;
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!drawing || !canvas || !look.inkColour) return;
+    const pad = new SignaturePadEngine(canvas, { penColor: look.inkColour, minWidth: 0.8, maxWidth: 2.6, velocityFilterWeight: 0.6 });
+    engine.current = pad;
+
+    // The canvas holds device pixels; strokes are kept in CSS pixels and
+    // redrawn at every size change (a phone rotating, a panel resizing).
+    const fit = () => {
+      const box = boxRef.current?.getBoundingClientRect();
+      if (!box || !box.width) return;
+      const ratio = Math.max(window.devicePixelRatio || 1, 1);
+      canvas.width = Math.round(box.width * ratio);
+      canvas.height = Math.round(box.height * ratio);
+      canvas.getContext("2d")?.scale(ratio, ratio);
+      pad.fromData(withInk(strokes.current, look.inkColour));
+    };
+    fit();
+    const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(fit) : null;
+    ro?.observe(boxRef.current);
+
+    const end = () => {
+      strokes.current = pad.toData();
+      const n = pointCount(strokes.current);
+      setDrawn(n);
+      setErrors((e) => (e?.pad ? { ...e, pad: undefined } : e));
+      tell({ mode: "draw", name: nameRef.current, empty: n === 0 });
+    };
+    pad.addEventListener("endStroke", end);
+    if (disabled) pad.off();
+    return () => {
+      pad.removeEventListener("endStroke", end);
+      pad.off();
+      ro?.disconnect();
+      engine.current = null;
+    };
+  }, [drawing, look.inkColour, disabled, tell]);
+
+  const undo = useCallback(() => {
+    strokes.current = withoutLast(strokes.current);
+    engine.current?.fromData(withInk(strokes.current, look.inkColour));
+    const n = pointCount(strokes.current);
+    setDrawn(n);
+    tell({ mode: "draw", name, empty: n === 0 });
+  }, [look.inkColour, name, tell]);
+
+  const clear = useCallback(
+    (quiet) => {
+      const before = strokes.current;
+      if (!before.length) return;
+      strokes.current = [];
+      engine.current?.clear();
+      setDrawn(0);
+      tell({ mode: "draw", name, empty: true });
+      if (quiet === true) return;
+      toast("Signature cleared", {
+        action: {
+          label: "Undo",
+          onClick: () => {
+            strokes.current = before;
+            engine.current?.fromData(withInk(before, look.inkColour));
+            setDrawn(pointCount(before));
+          },
+        },
+      });
+    },
+    [look.inkColour, name, tell],
+  );
+
+  // ---- the picture ----------------------------------------------------------
+
+  /** The signature as a PNG data URL (transparent, inked, cropped), or null. */
+  const toPNG = useCallback(async () => {
+    if (mode === "type") {
+      const text = name.trim();
+      const el = typedRef.current;
+      if (!text || typeof document === "undefined") return null;
+      try {
+        await document.fonts?.ready;
+      } catch {}
+      const family = el ? getComputedStyle(el).fontFamily : "serif";
+      const size = 64;
+      const scale = 2;
+      const c = document.createElement("canvas");
+      const ctx = c.getContext("2d");
+      const font = `italic 400 ${size}px ${family}`;
+      ctx.font = font;
+      const m = ctx.measureText(text);
+      const w = Math.ceil(m.width + size * 0.6);
+      const h = Math.ceil(size * 1.5);
+      c.width = w * scale;
+      c.height = h * scale;
+      ctx.scale(scale, scale);
+      ctx.font = font;
+      ctx.fillStyle = look.inkColour ?? getComputedStyle(el ?? document.body).color;
+      ctx.textBaseline = "alphabetic";
+      ctx.fillText(text, size * 0.3, size * 1.05);
+      return c.toDataURL("image/png");
+    }
+    const canvas = canvasRef.current;
+    const box = boxRef.current?.getBoundingClientRect();
+    const b = strokeBounds(strokes.current, 6, box ? { width: box.width, height: box.height } : undefined);
+    if (!canvas || !b) return null;
+    const ratio = canvas.width / (box?.width || canvas.width);
+    const out = document.createElement("canvas");
+    out.width = Math.round(b.width * ratio);
+    out.height = Math.round(b.height * ratio);
+    out.getContext("2d").drawImage(canvas, b.x * ratio, b.y * ratio, b.width * ratio, b.height * ratio, 0, 0, out.width, out.height);
+    return out.toDataURL("image/png");
+  }, [mode, name, look.inkColour]);
+
+  // ---- sign -----------------------------------------------------------------
+
+  const submit = useCallback(async () => {
+    if (!onSubmit || saving || disabled) return;
+    const gaps = missing({ mode, drawn, name, requireName });
+    setErrors(gaps);
+    if (gaps) {
+      if (gaps.name) document.getElementById(`${id}-name`)?.focus();
+      return;
+    }
+    const png = await toPNG();
+    if (!png) return setErrors({ pad: "Draw your signature in the box." });
+    const record = signatureRecord({ png, name, mode });
+    // Optimistic: it shows as signed at once; a failed save puts the pad
+    // back as it was, with the reason.
+    setFailed(null);
+    setSigned(record);
+    setSaving(true);
+    let res;
+    try {
+      res = await onSubmit(record);
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    setSaving(false);
+    if (!res?.ok) {
+      setSigned(null);
+      setFailed(res?.error || "The signature wasn't saved. Try again.");
+    }
+  }, [onSubmit, saving, disabled, mode, drawn, name, requireName, toPNG, id]);
+
+  const signAgain = useCallback(() => {
+    setSigned(null);
+    setFailed(null);
+    strokes.current = [];
+    setDrawn(0);
+  }, []);
+
+  useImperativeHandle(
+    padRef,
+    () => ({
+      toPNG,
+      clear: () => clear(true),
+      undo,
+      isEmpty: () => (mode === "type" ? !name.trim() : pointCount(strokes.current) === 0),
+      getName: () => name.trim(),
+      getMode: () => mode,
+      /** { png, name, mode, signedAt } now, or null when nothing is there. */
+      getSignature: async () => {
+        const png = await toPNG();
+        return png ? signatureRecord({ png, name, mode }) : null;
+      },
+      submit,
+    }),
+    [toPNG, clear, undo, mode, name, submit],
+  );
+
+  // ---- render ---------------------------------------------------------------
+
+  const paper = PAPER[look.paper] ?? PAPER.background;
+  const frame = bare ? "" : "rounded-lg border border-border bg-card p-4 sm:p-5";
+  const nameId = `${id}-name`;
+  const hintId = `${id}-hint`;
+  const typed = name.trim();
+
+  if (signed) {
+    return (
+      <div ref={rootRef} className={cx(frame, "text-card-foreground", className)}>
+        <div className="flex items-center justify-between gap-3">
+          <p className="text-sm font-medium">{label}</p>
+          {saving ? (
+            <span className="text-xs text-muted-foreground">Saving…</span>
+          ) : (
+            <span className="inline-flex items-center gap-1.5 text-xs font-medium text-success">
+              <Icon name="circle-check" size={14} /> Signed
+            </span>
+          )}
+        </div>
+        <div className={cx("mt-3 grid place-items-center rounded-md border border-border px-4 py-5 transition-opacity duration-150 motion-reduce:transition-none", paper.box, look.known ? "opacity-100" : "opacity-0")} style={{ minHeight: Math.round(height * 0.7) }}>
+          {/* raw: the signature on its paper — a transparent PNG over the paper token; the kit Image paints a muted fill and a skeleton under it */}
+          <img src={signed.png} alt={`Signature of ${signed.name || "the signer"}`} className="max-h-28 max-w-full object-contain" />
+        </div>
+        <div className="mt-3 flex flex-wrap items-center justify-between gap-2">
+          <p className="min-w-0 text-sm text-muted-foreground">
+            <span className="font-medium text-foreground">{signed.name || "Signed"}</span>
+            {mounted && signed.signedAt ? <span> · {formatSignedAt(signed.signedAt)}</span> : null}
+            {signed.mode === "type" ? <span> · typed</span> : null}
+          </p>
+          {!disabled && !saving ? (
+            <Button variant="quiet" size="sm" icon="refresh" onClick={signAgain}>
+              Sign again
+            </Button>
+          ) : null}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div ref={rootRef} className={cx(frame, "text-card-foreground", className)}>
+      <div className="flex items-center justify-between gap-3">
+        <p className="text-sm font-medium" id={`${id}-label`}>
+          {label}
+        </p>
+        {allowed.length > 1 ? (
+          <ToggleGroup
+            size="sm"
+            aria-label="How to sign"
+            value={mode}
+            onChange={(m) => {
+              setMode(m);
+              setErrors(null);
+              tell({ mode: m, name, empty: m === "type" ? !typed : pointCount(strokes.current) === 0 });
+            }}
+            disabled={disabled}
+            items={allowed}
+          />
+        ) : null}
+      </div>
+
+      <Field id={nameId} label={nameLabel} error={errors?.name} className="mt-3">
+        <Input
+          id={nameId}
+          value={name}
+          disabled={disabled}
+          autoComplete="name"
+          placeholder="Your full name"
+          invalid={Boolean(errors?.name)}
+          aria-describedby={errors?.name ? `${nameId}-error` : undefined}
+          onChange={(e) => {
+            const v = e.target.value;
+            setName(v);
+            if (errors?.name && v.trim()) setErrors((x) => ({ ...x, name: undefined }));
+            tell({ mode, name: v, empty: mode === "type" ? !v.trim() : pointCount(strokes.current) === 0 });
+          }}
+          onKeyDown={(e) => {
+            if (e.key === "Enter" && mode === "type" && onSubmit) {
+              e.preventDefault();
+              submit();
+            }
+          }}
+        />
+      </Field>
+
+      {/* The paper. */}
+      <div
+        ref={boxRef}
+        className={cx(
+          "relative mt-3 overflow-hidden rounded-md border transition-[opacity,border-color] duration-150 motion-reduce:transition-none",
+          paper.box,
+          errors?.pad ? "border-destructive" : "border-border",
+          look.known ? "opacity-100" : "opacity-0",
+          disabled && "opacity-60",
+        )}
+        style={{ height }}
+      >
+        {/* The line to sign on, and its cross. */}
+        <span aria-hidden="true" className={cx("pointer-events-none absolute right-6 left-6 h-px", paper.line)} style={{ bottom: Math.round(height * 0.26) }} />
+        <span aria-hidden="true" className={cx("pointer-events-none absolute left-6 text-sm select-none", paper.mark)} style={{ bottom: Math.round(height * 0.26) + 4 }}>
+          ×
+        </span>
+
+        {mode === "draw" ? (
+          <>
+            {!drawn ? (
+              <p aria-hidden="true" className={cx("pointer-events-none absolute inset-x-0 top-1/2 -translate-y-1/2 px-6 text-center text-sm select-none", paper.hint)}>
+                Sign here with your mouse, pen or finger
+              </p>
+            ) : null}
+            {/* raw: the drawing surface — signature_pad draws on a canvas; no kit part is one */}
+            <canvas
+              ref={canvasRef}
+              role="img"
+              aria-labelledby={`${id}-label`}
+              aria-describedby={hintId}
+              className={cx("absolute inset-0 block size-full touch-none", disabled ? "cursor-not-allowed" : "cursor-crosshair")}
+            />
+            {drawn && !disabled ? (
+              <div className="absolute top-2 right-2 flex gap-1">
+                <Tooltip label="Undo last stroke">
+                  <IconButton icon="undo" label="Undo last stroke" size="sm" variant="secondary" onClick={undo} />
+                </Tooltip>
+                <Tooltip label="Clear">
+                  <IconButton icon="eraser" label="Clear the signature" size="sm" variant="secondary" onClick={() => clear()} />
+                </Tooltip>
+              </div>
+            ) : null}
+          </>
+        ) : (
+          <div className="absolute inset-x-6 flex items-end justify-center" style={{ bottom: Math.round(height * 0.26) + 6, top: 12 }}>
+            <p ref={typedRef} className={cx("truncate pb-1 font-display text-4xl leading-tight italic sm:text-5xl", typed ? paper.ink : paper.hint)} aria-live="polite">
+              {typed || <span className="text-base not-italic">Type your name above</span>}
+            </p>
+          </div>
+        )}
+      </div>
+
+      <p id={hintId} className={cx("mt-1.5 text-xs", errors?.pad ? "text-destructive" : "text-muted-foreground")} role={errors?.pad ? "alert" : undefined}>
+        {errors?.pad ?? (mode === "draw" ? (allowed.some((m) => m.value === "type") ? "Prefer the keyboard? Switch to Type." : "Draw inside the box.") : "Your name, set as a signature.")}
+      </p>
+
+      {failed ? (
+        <Notice tone="danger" title="Not signed yet" className="mt-3" onDismiss={() => setFailed(null)}>
+          {failed}
+        </Notice>
+      ) : null}
+
+      {note || onSubmit ? (
+        <div className="mt-4 flex flex-col-reverse gap-3 sm:flex-row sm:items-center sm:justify-between">
+          {note ? <p className="text-xs text-muted-foreground sm:max-w-md">{note}</p> : <span />}
+          {onSubmit ? (
+            <Button variant="primary" icon="pencil" onClick={submit} disabled={disabled} className="w-full sm:w-auto">
+              {submitLabel}
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+

package/registry/blocks/signature-pad/signature.js

@@ -0,0 +1,68 @@
+// Plain helpers for a signature: its strokes, what is missing before it
+// can be signed, the record it becomes. No DOM, so they run anywhere.
+//
+// Strokes are signature_pad's point groups, in CSS pixels of the pad:
+//   [{ points: [{ x, y, pressure, time }], penColor, minWidth, maxWidth, … }]
+
+/** The box around every point, grown by `pad` px on each side (a stroke
+ *  has width); clipped to 0,0 and, when given, to the pad's size. Null
+ *  when there is nothing drawn. */
+export function strokeBounds(groups, pad = 6, size) {
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const g of groups ?? []) {
+    for (const p of g?.points ?? []) {
+      if (p.x < x0) x0 = p.x;
+      if (p.y < y0) y0 = p.y;
+      if (p.x > x1) x1 = p.x;
+      if (p.y > y1) y1 = p.y;
+    }
+  }
+  if (!Number.isFinite(x0)) return null;
+  const maxX = size?.width ?? Infinity;
+  const maxY = size?.height ?? Infinity;
+  const x = Math.max(0, Math.floor(x0 - pad));
+  const y = Math.max(0, Math.floor(y0 - pad));
+  const right = Math.min(maxX, Math.ceil(x1 + pad));
+  const bottom = Math.min(maxY, Math.ceil(y1 + pad));
+  return { x, y, width: Math.max(1, right - x), height: Math.max(1, bottom - y) };
+}
+
+/** Every stroke inked in `colour` (a theme change repaints the pad). */
+export const withInk = (groups, colour) => (colour ? (groups ?? []).map((g) => ({ ...g, penColor: colour })) : groups ?? []);
+
+/** The strokes without the last one. */
+export const withoutLast = (groups) => (groups ?? []).slice(0, -1);
+
+/** How many points were drawn: a tap is 1, a real signature dozens. */
+export const pointCount = (groups) => (groups ?? []).reduce((n, g) => n + (g?.points?.length ?? 0), 0);
+
+/** What stops this from being signed, as the words to show, or null.
+ *    mode         "draw" | "type"
+ *    drawn        how many points are on the pad
+ *    name         the typed full name
+ *    requireName  a name is needed in draw mode too */
+export function missing({ mode, drawn, name, requireName = true }) {
+  const hasName = Boolean(String(name ?? "").trim());
+  if (mode === "type") return hasName ? null : { name: "Type your full name to sign." };
+  const out = {};
+  if (requireName && !hasName) out.name = "Add your full name.";
+  if (!drawn) out.pad = "Draw your signature in the box.";
+  else if (drawn < 4) out.pad = "That looks like a dot — draw your signature in the box.";
+  return Object.keys(out).length ? out : null;
+}
+
+/** The record a signature becomes (what onSubmit receives, what `value`
+ *  shows): the picture, the name, how it was made, when. */
+export function signatureRecord({ png, name, mode, signedAt }) {
+  return { png, name: String(name ?? "").trim(), mode, signedAt: signedAt ?? new Date().toISOString() };
+}
+
+/** "Sep 23, 2026, 2:04 PM" in the reader's own locale. */
+export function formatSignedAt(iso, locale) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toLocaleString(locale, { month: "short", day: "numeric", year: "numeric", hour: "numeric", minute: "2-digit" });
+}