@tribe-nest/forge 1.13.0

package/src/ui/headless/dialog.tsx

@@ -0,0 +1,14 @@
+// Unstyled dialog primitives — thin re-export of Radix Dialog so the headless
+// blocks get portal + focus-trap + a11y + keyboard for free, with zero styling.
+export {
+  Root as DialogRoot,
+  Trigger as DialogTrigger,
+  Portal as DialogPortal,
+  Overlay as DialogOverlay,
+  Content as DialogContent,
+  Close as DialogClose,
+  Title as DialogTitle,
+  Description as DialogDescription,
+} from "@radix-ui/react-dialog";
+
+export { Slot } from "@radix-ui/react-slot";

package/src/ui/headless/document/index.ts

@@ -0,0 +1,7 @@
+// Public document-signing headless primitives (Tier 1). NOTE: this is a
+// lane-local aggregator — the integrator re-exports it from
+// `ui/headless/index.ts` (`export * from "./document"`).
+export { useDocumentSigningFlow, type DocumentSigningStage } from "./useDocumentSigningFlow";
+export { useSignaturePad, type SignaturePadApi, type UseSignaturePadOptions } from "./useSignaturePad";
+export { useOtpCodeInput, OTP_LENGTH } from "./useOtpCodeInput";
+export { useContractSignature, type SignatureMode } from "./useContractSignature";

package/src/ui/headless/document/useContractSignature.ts

@@ -0,0 +1,68 @@
+import { useState } from "react";
+import { getDocumentApiErrorMessage, useSignDocument } from "../../../data/queries/useDocuments";
+
+export type SignatureMode = "draw" | "type";
+
+/**
+ * Headless contract signature capture: draw (pair with `useSignaturePad`) or
+ * type. The signer's legal name is set by the sender (admin) and is read-only
+ * here — exposed as `legalName` for display, never editable and never sent to
+ * the server (the backend derives the signed name from the invited recipient).
+ * Both modes require the explicit e-signature consent checkbox (the backend
+ * rejects sign requests without `consent: true`; typed mode omits
+ * `signatureImage`). `submit` resolves to `{ ok, error }` so the view layer
+ * decides how to surface failures.
+ */
+export function useContractSignature(
+  token: string,
+  {
+    defaultName = "",
+    getDrawnSignature,
+  }: {
+    /** The signer's read-only legal name (the invited `recipient.name`). */
+    defaultName?: string;
+    /** Returns the drawn PNG data-URL (a `useSignaturePad`'s `toDataURL`) —
+     * required for draw mode. */
+    getDrawnSignature?: () => string | null;
+  } = {},
+) {
+  const sign = useSignDocument(token);
+  const [mode, setMode] = useState<SignatureMode>("draw");
+  // Read-only — the sender sets the legal name; the signer cannot change it.
+  const legalName = defaultName;
+  const [consent, setConsent] = useState(false);
+  const [hasInk, setHasInk] = useState(false);
+
+  const canSubmit = consent && (mode === "type" || hasInk) && !sign.isPending;
+
+  const submit = async (): Promise<{ ok: boolean; error?: string }> => {
+    if (!consent) return { ok: false, error: "Please agree to the electronic signature consent." };
+    let signatureImage: string | undefined;
+    if (mode === "draw") {
+      const dataUrl = getDrawnSignature?.();
+      if (!dataUrl) return { ok: false, error: "Draw your signature, or switch to the typed option." };
+      signatureImage = dataUrl;
+    }
+    try {
+      await sign.mutateAsync({ signatureImage });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, error: getDocumentApiErrorMessage(error, "Signing failed. Please try again.") };
+    }
+  };
+
+  return {
+    mode,
+    setMode,
+    /** The signer's read-only legal name (set by the sender). */
+    legalName,
+    consent,
+    setConsent,
+    /** Wire to the signature pad's `hasInk` (drives draw-mode submit gating). */
+    hasInk,
+    setHasInk,
+    canSubmit,
+    isSigning: sign.isPending,
+    submit,
+  };
+}

package/src/ui/headless/document/useDocumentSigningFlow.ts

@@ -0,0 +1,92 @@
+import {
+  useAcceptDocument,
+  useDeclineDocument,
+  useDownloadSignedDocument,
+  usePublicDocument,
+  useRequestDocumentOtp,
+  useConfirmDocumentOtp,
+  useSignDocument,
+  type PublicDocumentResponse,
+} from "../../../data/queries/useDocuments";
+
+/** Which screen the public signing page should render. */
+export type DocumentSigningStage =
+  | "loading" // document still loading
+  | "invalid" // bad/unknown/expired token (fetch failed)
+  | "terminal" // document reached a final status (signed/accepted/declined/expired/converted)
+  | "waiting" // doc still open but THIS recipient already acted (multi-signer wait)
+  | "otp" // email verification required before acting
+  | "sign" // contract, ready for this signer
+  | "accept" // proposal, ready to accept/decline
+  | "view-only"; // recipient is a viewer — no action panel
+
+/**
+ * Headless public document-signing flow (`/documents/:token` — the emailed
+ * magic link IS the identity, no login). Owns the whole state machine:
+ * loading → invalid → terminal banners (signed/accepted/declined/expired/
+ * converted) → per-recipient waiting → OTP gate → contract-sign or
+ * proposal-accept panel, with viewers locked to read-only. Exposes the
+ * document/recipient/pricing data plus every action (request/confirm OTP,
+ * sign, accept, decline, download signed PDF) as mutations.
+ */
+export function useDocumentSigningFlow(token: string) {
+  const query = usePublicDocument(token);
+  const data: PublicDocumentResponse | undefined = query.data;
+
+  const requestOtp = useRequestDocumentOtp(token);
+  const confirmOtp = useConfirmDocumentOtp(token);
+  const sign = useSignDocument(token);
+  const accept = useAcceptDocument(token);
+  const decline = useDeclineDocument(token);
+  const download = useDownloadSignedDocument(token, data?.document.title);
+
+  const doc = data?.document ?? null;
+  const recipient = data?.recipient ?? null;
+
+  const isTerminal = !!doc && ["signed", "accepted", "declined", "expired", "converted"].includes(doc.status);
+  const recipientDone = !!recipient && ["signed", "accepted", "declined"].includes(recipient.status);
+  const needsOtp = !!recipient && recipient.requireOtp && !recipient.emailVerified;
+  const isViewer = recipient?.role === "viewer";
+  const actionable = !!doc && !isTerminal && !recipientDone && ["sent", "viewed"].includes(doc.status);
+
+  const stage: DocumentSigningStage = query.isLoading
+    ? "loading"
+    : query.error || !data || !doc || !recipient
+      ? "invalid"
+      : isTerminal
+        ? "terminal"
+        : recipientDone || !actionable
+          ? "waiting"
+          : isViewer
+            ? "view-only"
+            : needsOtp
+              ? "otp"
+              : doc.kind === "contract"
+                ? "sign"
+                : "accept";
+
+  return {
+    stage,
+    // Data
+    document: doc,
+    recipient,
+    pricingOptions: data?.pricingOptions ?? [],
+    profile: data?.profile ?? null,
+    /** The pricing option the acceptor picked (terminal accepted state). */
+    selectedPricingOption: data?.pricingOptions.find((o) => o.selected) ?? null,
+    // Derived flags (also encoded in `stage`, exposed for custom renders)
+    isTerminal,
+    recipientDone,
+    needsOtp,
+    isViewer,
+    actionable,
+    kindLabel: doc?.kind === "contract" ? "contract" : "proposal",
+    // Actions
+    requestOtp,
+    confirmOtp,
+    sign,
+    accept,
+    decline,
+    download,
+  };
+}

package/src/ui/headless/document/useOtpCodeInput.ts

@@ -0,0 +1,86 @@
+import { useCallback, useRef, useState } from "react";
+
+export const OTP_LENGTH = 6;
+
+/**
+ * Headless N-digit OTP input state machine (segmented boxes): per-digit state,
+ * paste of the whole code into any box, auto-focus advance, backspace-to-
+ * previous, and auto-submit when all digits are filled. Consumer renders the
+ * inputs and spreads `getInputProps(index)`.
+ */
+export function useOtpCodeInput({
+  length = OTP_LENGTH,
+  onComplete,
+  disabled = false,
+}: {
+  length?: number;
+  /** Called with the full code once every digit is filled. */
+  onComplete?: (code: string) => void;
+  /** Disable all inputs (e.g. while the confirm mutation is pending). */
+  disabled?: boolean;
+} = {}) {
+  const [digits, setDigits] = useState<string[]>(Array(length).fill(""));
+  const inputsRef = useRef<(HTMLInputElement | null)[]>([]);
+
+  const reset = useCallback(() => {
+    setDigits(Array(length).fill(""));
+    inputsRef.current[0]?.focus();
+  }, [length]);
+
+  const setDigit = useCallback(
+    (index: number, raw: string) => {
+      // Support paste of the full code into any box. State updaters must stay
+      // pure (React may replay them), so focus + auto-submit happen out here on
+      // a locally computed `next` instead of inside setDigits.
+      const clean = raw.replace(/\D/g, "");
+      if (!clean) {
+        const next = [...digits];
+        next[index] = "";
+        setDigits(next);
+        return;
+      }
+      const next = [...digits];
+      for (let i = 0; i < clean.length && index + i < length; i++) {
+        next[index + i] = clean[i];
+      }
+      setDigits(next);
+      const focusIndex = Math.min(index + clean.length, length - 1);
+      inputsRef.current[focusIndex]?.focus();
+      if (next.every((d) => d !== "") && !disabled) {
+        onComplete?.(next.join(""));
+      }
+    },
+    [digits, length, disabled, onComplete],
+  );
+
+  const getInputProps = useCallback(
+    (index: number) => ({
+      ref: (el: HTMLInputElement | null) => {
+        inputsRef.current[index] = el;
+      },
+      type: "text" as const,
+      inputMode: "numeric" as const,
+      autoComplete: index === 0 ? "one-time-code" : "off",
+      maxLength: length,
+      value: digits[index],
+      disabled,
+      onChange: (e: React.ChangeEvent<HTMLInputElement>) => setDigit(index, e.target.value),
+      onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => {
+        if (e.key === "Backspace" && !digits[index] && index > 0) {
+          inputsRef.current[index - 1]?.focus();
+        }
+      },
+      "aria-label": `Digit ${index + 1}`,
+    }),
+    [digits, length, disabled, setDigit],
+  );
+
+  return {
+    digits,
+    /** The code entered so far (join of the digits). */
+    code: digits.join(""),
+    isComplete: digits.every((d) => d !== ""),
+    getInputProps,
+    reset,
+  };
+}

package/src/ui/headless/document/useSignaturePad.ts

@@ -0,0 +1,180 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseSignaturePadOptions {
+  /** Stroke color. The canvas needs a concrete color — pass the theme's text
+   * color. Default near-black. */
+  inkColor?: string;
+  /** Stroke width in CSS pixels. Default 2.5. */
+  lineWidth?: number;
+}
+
+export interface SignaturePadApi {
+  /** Spread onto the `<canvas>`: wires pointer drawing (mouse + touch +
+   * stylus), pointer capture, and `touch-action: none`. Give the canvas an
+   * explicit CSS height — the hook manages the backing-store size. */
+  getCanvasProps: () => {
+    ref: (el: HTMLCanvasElement | null) => void;
+    onPointerDown: (event: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerMove: (event: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerUp: (event: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerCancel: (event: React.PointerEvent<HTMLCanvasElement>) => void;
+    style: React.CSSProperties;
+  };
+  /** True once the pad has any ink — reactive, drive placeholder/submit state. */
+  hasInk: boolean;
+  /** PNG data-URL of the drawn signature, or null when the pad is empty. */
+  toDataURL: () => string | null;
+  clear: () => void;
+  isEmpty: () => boolean;
+}
+
+/**
+ * Headless signature draw pad (dependency-free — no signature-pad package).
+ * Pointer events cover mouse + touch + stylus; `touch-action: none` stops the
+ * page from scrolling mid-stroke; the backing store is scaled for
+ * devicePixelRatio so exported PNGs stay crisp, and ink survives resizes
+ * (e.g. phone rotation). Consumer renders the canvas + chrome, spreads
+ * `getCanvasProps()`, and submits `toDataURL()` as the `signatureImage`.
+ */
+export function useSignaturePad(options: UseSignaturePadOptions = {}): SignaturePadApi {
+  const { inkColor = "#111111", lineWidth = 2.5 } = options;
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const observerRef = useRef<ResizeObserver | null>(null);
+  const drawingRef = useRef(false);
+  const lastPointRef = useRef<{ x: number; y: number } | null>(null);
+  const hasInkRef = useRef(false);
+  const [hasInk, setHasInk] = useState(false);
+
+  const setupCanvas = useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const rect = canvas.getBoundingClientRect();
+    const dpr = window.devicePixelRatio || 1;
+    // Preserve existing ink across resizes (e.g. phone rotation).
+    const previous = hasInkRef.current ? canvas.toDataURL("image/png") : null;
+    canvas.width = Math.max(1, Math.round(rect.width * dpr));
+    canvas.height = Math.max(1, Math.round(rect.height * dpr));
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    ctx.scale(dpr, dpr);
+    ctx.lineWidth = lineWidth;
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+    ctx.strokeStyle = inkColor;
+    if (previous) {
+      const img = new Image();
+      img.onload = () => ctx.drawImage(img, 0, 0, rect.width, rect.height);
+      img.src = previous;
+    }
+  }, [inkColor, lineWidth]);
+
+  // Re-apply stroke settings when the ink color/width props change.
+  useEffect(() => {
+    if (canvasRef.current) setupCanvas();
+  }, [setupCanvas]);
+
+  const attachCanvas = useCallback(
+    (el: HTMLCanvasElement | null) => {
+      observerRef.current?.disconnect();
+      observerRef.current = null;
+      canvasRef.current = el;
+      if (!el) return;
+      setupCanvas();
+      if (typeof ResizeObserver !== "undefined") {
+        const observer = new ResizeObserver(() => setupCanvas());
+        observer.observe(el);
+        observerRef.current = observer;
+      }
+    },
+    [setupCanvas],
+  );
+
+  useEffect(() => () => observerRef.current?.disconnect(), []);
+
+  const markInk = useCallback((value: boolean) => {
+    if (hasInkRef.current === value) return;
+    hasInkRef.current = value;
+    setHasInk(value);
+  }, []);
+
+  const pointFromEvent = (event: React.PointerEvent<HTMLCanvasElement>) => {
+    const rect = event.currentTarget.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  };
+
+  const onPointerDown = useCallback((event: React.PointerEvent<HTMLCanvasElement>) => {
+    event.preventDefault();
+    event.currentTarget.setPointerCapture(event.pointerId);
+    drawingRef.current = true;
+    lastPointRef.current = pointFromEvent(event);
+  }, []);
+
+  const onPointerMove = useCallback(
+    (event: React.PointerEvent<HTMLCanvasElement>) => {
+      if (!drawingRef.current) return;
+      const canvas = canvasRef.current;
+      const ctx = canvas?.getContext("2d");
+      const last = lastPointRef.current;
+      if (!canvas || !ctx || !last) return;
+      const point = pointFromEvent(event);
+      ctx.beginPath();
+      ctx.moveTo(last.x, last.y);
+      ctx.lineTo(point.x, point.y);
+      ctx.stroke();
+      lastPointRef.current = point;
+      markInk(true);
+    },
+    [markInk],
+  );
+
+  const onPointerUp = useCallback(
+    (event: React.PointerEvent<HTMLCanvasElement>) => {
+      if (!drawingRef.current) return;
+      // A tap without movement still leaves a dot.
+      const canvas = canvasRef.current;
+      const ctx = canvas?.getContext("2d");
+      const last = lastPointRef.current;
+      if (ctx && last) {
+        ctx.beginPath();
+        ctx.arc(last.x, last.y, 1.25, 0, Math.PI * 2);
+        ctx.fillStyle = inkColor;
+        ctx.fill();
+        markInk(true);
+      }
+      drawingRef.current = false;
+      lastPointRef.current = null;
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    },
+    [inkColor, markInk],
+  );
+
+  const clear = useCallback(() => {
+    const canvas = canvasRef.current;
+    const ctx = canvas?.getContext("2d");
+    if (!canvas || !ctx) return;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    markInk(false);
+  }, [markInk]);
+
+  const toDataURL = useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || !hasInkRef.current) return null;
+    return canvas.toDataURL("image/png");
+  }, []);
+
+  const isEmpty = useCallback(() => !hasInkRef.current, []);
+
+  const getCanvasProps = useCallback(
+    () => ({
+      ref: attachCanvas,
+      onPointerDown,
+      onPointerMove,
+      onPointerUp,
+      onPointerCancel: onPointerUp,
+      style: { touchAction: "none" as const, cursor: "crosshair" as const, display: "block" as const, width: "100%" },
+    }),
+    [attachCanvas, onPointerDown, onPointerMove, onPointerUp],
+  );
+
+  return { getCanvasProps, hasInk, toDataURL, clear, isEmpty };
+}

package/src/ui/headless/donation/Donation.tsx

@@ -0,0 +1,115 @@
+import type { CSSProperties, ReactNode } from "react";
+import {
+  DialogRoot,
+  DialogTrigger,
+  DialogPortal,
+  DialogOverlay,
+  DialogContent,
+  DialogClose,
+  DialogTitle,
+} from "../dialog";
+import {
+  DonationProvider,
+  useDonationContext,
+  type DonationProviderProps,
+} from "./DonationContext";
+
+/** Render-prop payload for `<Donation.PaymentStep>`. The app supplies the
+ * actual payment UI (e.g. Stripe Elements) — the SDK owns only the data. */
+export interface DonationPaymentRenderProps {
+  clientSecret?: string;
+  returnUrl: string;
+  amount: number;
+  onSucceeded: () => void;
+  onFailed: (message?: string) => void;
+}
+
+type DonationComponent = ((props: DonationProviderProps) => React.ReactElement) & {
+  Trigger: (props: { children: ReactNode; asChild?: boolean }) => React.ReactElement;
+  Modal: (props: {
+    children: ReactNode;
+    className?: string;
+    overlayClassName?: string;
+    style?: CSSProperties;
+    overlayStyle?: CSSProperties;
+  }) => React.ReactElement;
+  Title: (props: { children: ReactNode; className?: string }) => React.ReactElement;
+  Close: (props: { children: ReactNode; asChild?: boolean }) => React.ReactElement;
+  AmountStep: (props: { children: ReactNode }) => React.ReactElement | null;
+  PaymentStep: (props: {
+    children: ReactNode | ((p: DonationPaymentRenderProps) => ReactNode);
+  }) => React.ReactElement | null;
+  Result: (props: { children: ReactNode }) => React.ReactElement | null;
+};
+
+function DonationRoot({ children }: { children: ReactNode }) {
+  const { open, setOpen } = useDonationContext();
+  return (
+    <DialogRoot open={open} onOpenChange={setOpen}>
+      {children}
+    </DialogRoot>
+  );
+}
+
+/**
+ * Headless donation flow. Owns interaction state, the multi-step machine, fee
+ * math and payment orchestration; renders no styling. Compose the slots and
+ * style them yourself, or use the Tier-2 `<DonationButton>`.
+ */
+export const Donation = (({ donationId, returnUrl, onSuccess, children }: DonationProviderProps) => (
+  <DonationProvider donationId={donationId} returnUrl={returnUrl} onSuccess={onSuccess}>
+    <DonationRoot>{children}</DonationRoot>
+  </DonationProvider>
+)) as DonationComponent;
+
+Donation.Trigger = function DonationTrigger({ children, asChild }) {
+  return <DialogTrigger asChild={asChild}>{children}</DialogTrigger>;
+};
+
+Donation.Modal = function DonationModal({ children, className, overlayClassName, style, overlayStyle }) {
+  return (
+    <DialogPortal>
+      <DialogOverlay className={overlayClassName} style={overlayStyle} />
+      <DialogContent className={className} style={style}>
+        {children}
+      </DialogContent>
+    </DialogPortal>
+  );
+};
+
+Donation.Title = function DonationModalTitle({ children, className }) {
+  return <DialogTitle className={className}>{children}</DialogTitle>;
+};
+
+Donation.Close = function DonationModalClose({ children, asChild }) {
+  return <DialogClose asChild={asChild}>{children}</DialogClose>;
+};
+
+Donation.AmountStep = function DonationAmountStep({ children }) {
+  const { step } = useDonationContext();
+  return step === "amount" ? <>{children}</> : null;
+};
+
+Donation.PaymentStep = function DonationPaymentStep({ children }) {
+  const ctx = useDonationContext();
+  if (ctx.step !== "payment") return null;
+  if (typeof children === "function") {
+    return (
+      <>
+        {children({
+          clientSecret: ctx.startResult?.paymentSecret,
+          returnUrl: ctx.returnUrl,
+          amount: ctx.startResult?.totalAmount ?? ctx.estimatedTotal,
+          onSucceeded: ctx.onPaymentSucceeded,
+          onFailed: ctx.onPaymentFailed,
+        })}
+      </>
+    );
+  }
+  return <>{children}</>;
+};
+
+Donation.Result = function DonationResult({ children }) {
+  const { step } = useDonationContext();
+  return step === "result" ? <>{children}</> : null;
+};