makersclaw 0.1.0 → 0.3.0

package/registry/blocks/signature-pad/README.md

@@ -0,0 +1,137 @@
+# SignaturePad
+
+A signature field in the workspace theme. The signer adds their full
+name, then either **draws** on a paper box (smooth pen strokes that
+follow speed and pressure; undo the last stroke; clear, with Undo in a
+toast) or **types** — their name is set as a signature in the theme's
+display face. "Sign" saves it and the field turns into the signed view:
+the signature, the name and the time, with "Sign again". Nothing drawn,
+no name, a dot: it says what is missing, next to where it is missing.
+
+What comes out is a record: a PNG (transparent, cropped to the
+signature, in dark ink so it reads on a document, a PDF or an email), the
+typed name, how it was made and when.
+
+**The pad is paper.** It is whichever of the theme's background and
+foreground is lighter, inked with the other: on a light theme, the page
+itself; on a dark theme, a light sheet with dark ink. So what the signer
+sees is exactly what the PNG holds.
+
+It is [signature_pad](https://github.com/szimek/signature_pad) (MIT)
+underneath, for the drawing. The field, the modes, the states and the
+record are ours, in the kit. The blocks built on this one —
+`proposal-accept` — import it, never `signature_pad`.
+
+```jsx
+import { SignaturePad, useSignaturePad } from "../components/blocks/signature-pad";   // a Makersclaw app ("./blocks/signature-pad" from components/)
+import { SignaturePad, useSignaturePad } from "@/components/makersclaw/blocks/signature-pad";   // a shadcn project
+```
+
+`SignaturePad` is a client component: render it from a `"use client"`
+component. `signatureRecord` and `formatSignedAt` are plain functions.
+
+`makersclaw add signature-pad` adds `signature_pad` (pinned, exact) to
+package.json: run `npm install` after. It loads with the page (no
+`import()`); the pad starts in the browser, and fades in once it has
+read the theme's ink.
+
+**It records an acceptance — it is not a certified e-signature.** There
+is no identity check and no audit trail beyond what you store. Say so
+where people sign (`note`), and store the record with who was signed in,
+when, and what they were shown.
+
+## The data
+
+The record `onSubmit` receives, `getSignature()` returns and `value`
+shows:
+
+```js
+{
+  png: "data:image/png;base64,…",   // transparent, dark ink, cropped; a few KB
+  name: "Maya Chen",                // the typed full name, trimmed
+  mode: "draw",                     // "draw" | "type"
+  signedAt: "2026-09-23T14:04:11.512Z",
+}
+```
+
+Store it as it is — one `jsonb` column holds the whole record (the PNG
+is a few KB) — beside the signed-in user and the thing that was signed.
+
+## Props
+
+- `onSubmit(record)` — shows the Sign button (`submitLabel`). It shows as
+  signed at once while you save; return `{ ok: true }`, or `{ ok: false,
+  error }` (or throw) and the pad comes back as it was, strokes and name
+  kept, with a notice that says why. Without it there is no button: read
+  the signature through the handle (a field inside your own form).
+- `signer` — the name to start with ("Maya Chen"), default empty.
+- `value` — a saved record: the field opens signed, showing it. "Sign
+  again" (unless `disabled`) goes back to an empty pad.
+- `onChange({ mode, name, empty })` — after each stroke, undo, clear,
+  keystroke in the name and mode switch. No PNG (that is `toPNG()`).
+- `label` — the field's label, default "Signature" ("Received by",
+  "Customer signature").
+- `nameLabel` — the name field's label, default "Full name".
+- `modes` — `["draw", "type"]` (the default), or one of them.
+- `defaultMode` — the mode it opens in, default the first of `modes`.
+- `requireName` — a name is needed to sign by drawing too. Default
+  `true`; typing always needs one.
+- `submitLabel` — default "Sign" ("Accept and sign", "Approve").
+- `note` — a line beside the button: what signing means.
+- `disabled` — nothing can be drawn, typed or signed. Default `false`.
+- `height` — the paper's height in px, default `176`.
+- `bare` — no card around it (no border, background or padding), for a
+  field inside your own card or form. Default `false`.
+- `padRef` — a ref from `useSignaturePad()` for the handle below.
+- `className` — on the outer element.
+
+### The handle
+
+```jsx
+const pad = useSignaturePad();
+<SignaturePad padRef={pad} />;
+const record = await pad.current?.getSignature();   // null when nothing is there
+```
+
+`getSignature()` → the record or `null`; `toPNG()` → the PNG data URL
+or `null`; `getName()`, `getMode()`, `isEmpty()`; `undo()`, `clear()`
+(no toast); `submit()` (as the button, when `onSubmit` is given).
+
+### Keys and access
+
+Drawing needs a pointer (mouse, pen, finger). **Type is the keyboard
+path**: Tab to the Draw / Type switch, arrow to Type, and the name field
+is the signature; Enter in it signs (when `onSubmit` is given). The hint
+under the paper says so. Undo and clear are buttons with names.
+
+## Example
+
+Accepting a quote in a Makersclaw app.
+
+```jsx
+"use client";
+import { updateRow } from "../lib/actions";
+import { SignaturePad } from "./blocks/signature-pad";
+
+export default function AcceptQuote({ quote, me }) {
+  return (
+    <SignaturePad
+      signer={me.name}
+      value={quote.signature ?? undefined}
+      submitLabel="Accept and sign"
+      note="Signing records that you accept this quote. It is not a certified e-signature."
+      onSubmit={(signature) =>
+        updateRow({ source: "public.quotes", id: quote.id, patch: { status: "accepted", signature, signed_by: me.email }, detail: "accepted" })
+      }
+    />
+  );
+}
+```
+
+## What it will not do
+
+- Verify who signed, send the document for signature, or keep an audit
+  trail: it is a field, not an e-signature service.
+- Pick a colour or pen width: ink is the theme's, width follows speed.
+- Upload the PNG: it returns a data URL; storing it is yours.
+- Take an image of a signature to upload (use `file-upload`).

package/registry/blocks/signature-pad/block.json

@@ -0,0 +1,13 @@
+{
+  "name": "signature-pad",
+  "title": "SignaturePad",
+  "description": "A signature field (signature_pad) in the workspace theme: a full-name field, then draw on a paper box (smooth pen strokes, undo the last stroke, clear with Undo) or type the name set as a signature. Sign returns a record: a cropped transparent PNG in dark ink, the typed name, the mode and the time; the signed view shows it with Sign again. Works as a form field too, through a handle (toPNG, getSignature).",
+  "useWhen": "A screen needs someone to sign: accepting a proposal or a quote, a delivery or work-done sign-off, a waiver, a consent form, an approval on a record. The proposal-accept block is built on it. It records an acceptance with a picture of the signature — it is not a certified legal e-signature (no identity check, no audit trail beyond what you store).",
+  "tags": ["signature", "sign", "e-sign", "draw", "type", "accept", "approval", "consent", "waiver", "sign-off", "png", "form"],
+  "exports": ["SignaturePad", "useSignaturePad", "signatureRecord", "formatSignedAt"],
+  "files": ["index.js", "signature-pad.jsx", "pad.js", "colors.js", "signature.js"],
+  "requires": [],
+  "dependencies": {
+    "signature_pad": "5.1.4"
+  }
+}

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

@@ -0,0 +1,115 @@
+// The pad's colours are the workspace's tokens.
+//
+// signature_pad draws on a <canvas>, and a canvas needs a concrete colour —
+// it cannot read var(--color-foreground). So the ink is read from the CSS
+// variables in effect where the pad sits, at run time, and read again when
+// the theme or the scheme changes (the pad watches for that). No colour
+// value is written in this file: every one comes from the page. Same
+// method as sketch-canvas's palette.js and audio-player's colors.js.
+//
+// The pad is PAPER: whichever of the theme's background and foreground is
+// lighter, with the other one as ink. On a light theme that is the page
+// itself; on a dark theme it is a light sheet with dark ink. Either way
+// what you see is what the PNG holds — dark ink on a transparent ground,
+// which reads on a document, a PDF, an email.
+//
+// Everything but readTokens() and watchTheme() is a plain function, so it
+// runs in node.
+
+const byte = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+
+/** [r, g, b, a(0-255)] → "#rrggbb", or "#rrggbbaa" when not opaque. */
+export function toHex([r, g, b, a = 255]) {
+  return "#" + byte(r) + byte(g) + byte(b) + (a >= 255 ? "" : byte(a));
+}
+
+/** Relative luminance (WCAG) of [r, g, b], 0 (black) to 1 (white). */
+export function luminance([r, g, b]) {
+  const lin = (c) => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** Which token is the paper and which the ink, from the two read off the
+ *  page. Unknown (the server, a missing slot): the page is the paper. */
+export function paperAndInk(slots) {
+  const bg = slots?.background;
+  const fg = slots?.foreground;
+  if (!bg || !fg) return { paper: "background", ink: "foreground", inkColour: fg ? toHex(fg) : null };
+  return luminance(fg) > luminance(bg) ? { paper: "foreground", ink: "background", inkColour: toHex(bg) } : { paper: "background", ink: "foreground", inkColour: toHex(fg) };
+}
+
+// ---- the browser half -------------------------------------------------------
+
+/** Read `slots` (token names: "primary", "muted-foreground"…) from the CSS
+ *  variables in effect at `root`, as [r, g, b, a] bytes. A probe takes
+ *  `color: var(--color-<slot>)`; the browser resolves var(), color-mix()
+ *  and light-dark() into its computed colour, and a 1×1 canvas turns that
+ *  into bytes whatever syntax it came back in. */
+export function readTokens(root, slots) {
+  const out = {};
+  if (typeof document === "undefined" || !root) return out;
+  const probe = document.createElement("span");
+  probe.setAttribute("aria-hidden", "true");
+  probe.style.position = "absolute";
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  root.appendChild(probe);
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  try {
+    for (const slot of slots) {
+      probe.style.color = "";
+      probe.style.color = `var(--color-${slot})`;
+      const computed = getComputedStyle(probe).color;
+      if (!computed || !ctx) continue;
+      ctx.clearRect(0, 0, 1, 1);
+      ctx.fillStyle = "transparent";
+      ctx.fillStyle = computed;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+      if (a === 0) continue;
+      out[slot] = [r, g, b, a];
+    }
+  } finally {
+    probe.remove();
+  }
+  return out;
+}
+
+/** Call `fn` (soon, once) whenever something that sets the tokens may have
+ *  changed: a data-theme / class / style on <html> or the nearest themed
+ *  ancestor, a stylesheet added to <head>, the OS scheme. Returns the
+ *  cleanup. */
+export function watchTheme(root, fn) {
+  if (typeof document === "undefined") return () => {};
+  let t = 0;
+  const soon = () => {
+    clearTimeout(t);
+    t = setTimeout(fn, 30);
+  };
+  const obs = new MutationObserver((records) => {
+    for (const r of records) for (const n of r.addedNodes ?? []) if (n.tagName === "LINK") n.addEventListener("load", soon, { once: true });
+    soon();
+  });
+  const attrs = { attributes: true, attributeFilter: ["data-theme", "class", "style"] };
+  obs.observe(document.documentElement, attrs);
+  obs.observe(document.head, { childList: true });
+  const scoped = root?.closest?.("[data-theme]");
+  if (scoped && scoped !== document.documentElement) {
+    obs.observe(scoped, attrs);
+    obs.observe(scoped, { childList: true });
+  }
+  const mq = typeof matchMedia !== "undefined" ? matchMedia("(prefers-color-scheme: dark)") : null;
+  mq?.addEventListener("change", soon);
+  soon();
+  return () => {
+    clearTimeout(t);
+    obs.disconnect();
+    mq?.removeEventListener("change", soon);
+  };
+}

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

@@ -0,0 +1,94 @@
+"use client";
+
+// SignaturePad two ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Accept a proposal   the block with its own Sign button (onSubmit); a
+//                       switch makes the save fail; what was saved is
+//                       listed under it.
+//   Delivery sign-off   the block as a field in a larger form: no Sign
+//                       button, the form's own button reads the signature
+//                       through the handle.
+import { useState } from "react";
+import { Button, Card, Notice, Switch } from "../components/ui";
+import { SignaturePad, formatSignedAt, useSignaturePad } from "../components/blocks/signature-pad";
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+const kb = (dataUrl) => `${Math.max(1, Math.round((dataUrl.length * 3) / 4 / 1024))} KB`;
+
+function AcceptProposal() {
+  const [fail, setFail] = useState(false);
+  const [saved, setSaved] = useState(null);
+
+  async function accept(signature) {
+    await wait(700);
+    if (fail) return { ok: false, error: "The server didn't answer. Your signature is still here — try again." };
+    setSaved(signature);
+    return { ok: true };
+  }
+
+  return (
+    <div className="grid content-start gap-3">
+      <Card>
+        <p className="text-xs text-muted-foreground">Proposal · Q-1042</p>
+        <p className="mt-1 text-sm font-medium">Northwind Logistics — annual plan, 40 seats</p>
+        <p className="mt-1 text-sm text-muted-foreground tabular-nums">18,400 USD a year · starts Oct 1</p>
+      </Card>
+      <SignaturePad
+        signer="Maya Chen"
+        onSubmit={accept}
+        submitLabel="Accept and sign"
+        note="Signing records that you accept this proposal. It is an acceptance record, not a certified e-signature."
+      />
+      <Switch id="sign-fail" checked={fail} onChange={(e) => setFail(e.target.checked)} label="Make the save fail" />
+      {saved ? (
+        <p className="text-xs text-muted-foreground">
+          Saved: {saved.name}, {saved.mode === "type" ? "typed" : "drawn"}, {formatSignedAt(saved.signedAt)}, a {kb(saved.png)} PNG.
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+function DeliverySignOff() {
+  const pad = useSignaturePad();
+  const [result, setResult] = useState(null);
+  const [busy, setBusy] = useState(false);
+
+  async function confirm() {
+    setBusy(true);
+    const signature = await pad.current?.getSignature();
+    setBusy(false);
+    if (!signature || !signature.name) {
+      setResult({ ok: false, text: "Ask the recipient to add their name and sign before you confirm." });
+      return;
+    }
+    setResult({ ok: true, text: `Delivery confirmed — received by ${signature.name}.` });
+  }
+
+  return (
+    <Card className="grid content-start gap-4 sm:p-5">
+      <div>
+        <p className="text-sm font-medium">Delivery DL-2291 · 3 pallets</p>
+        <p className="mt-0.5 text-xs text-muted-foreground">Halden & Co, Unit 4, Riverside Park</p>
+      </div>
+      <SignaturePad label="Received by" padRef={pad} defaultMode="type" height={144} bare />
+      {result ? (
+        <Notice tone={result.ok ? "success" : "warning"} onDismiss={() => setResult(null)}>
+          {result.text}
+        </Notice>
+      ) : null}
+      <Button variant="primary" icon="check" loading={busy} onClick={confirm} className="w-full sm:w-auto sm:justify-self-end">
+        Confirm delivery
+      </Button>
+    </Card>
+  );
+}
+
+export default function SignaturePadDemo() {
+  return (
+    <div className="grid gap-6 lg:grid-cols-2">
+      <AcceptProposal />
+      <DeliverySignOff />
+    </div>
+  );
+}

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

@@ -0,0 +1,6 @@
+// The SignaturePad block — `makersclaw add signature-pad`. Fixed: compose
+// it through its props (README.md beside this file). The blocks built on
+// this one (proposal-accept…) import it, never signature_pad directly.
+// The helpers are plain functions and work on the server.
+export { SignaturePad, useSignaturePad } from "./signature-pad";
+export { signatureRecord, formatSignedAt } from "./signature";

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

@@ -0,0 +1,7 @@
+// The one door to signature_pad (MIT). Every file in this block reaches
+// the library through here, and the blocks built on this one
+// (proposal-accept…) reach it through SignaturePad — never the package.
+//
+// No shim is needed: the package loads on the server without touching
+// `window` (checked in node); the pad is only created in an effect.
+export { default as SignaturePadEngine } from "signature_pad";