@cosxai/ui 0.25.0 → 1.0.0-alpha.0

package/src/primitives/SignaturePad.tsx

@@ -1,461 +0,0 @@
-import {
-  forwardRef,
-  useCallback,
-  useEffect,
-  useImperativeHandle,
-  useMemo,
-  useRef,
-  useState,
-  type CSSProperties,
-  type PointerEvent as ReactPointerEvent,
-  type ReactNode,
-} from "react";
-
-/**
- * SignaturePad — legally-binding e-signature capture.
- *
- * Two modes:
- *   - `typed`  — signer types their name; canvas paints it in the
- *                Caveat cursive script + emits PNG dataURL.
- *   - `drawn`  — signer draws with mouse / trackpad / touch; captured
- *                as a smoothed stroke path + rasterised to PNG.
- *
- * Both modes produce the same output shape: `image/png` dataURL via
- * `canvas.toDataURL('image/png')`. Downstream consumer (metaroom
- * SignDocumentPage) uploads that dataURL to mesh's signing endpoint;
- * mesh stores as `signature_png` on the signing session + bakes into
- * the certified PDF client-side.
- *
- * Compose with:
- *   - SigningCommitBar (footer state machine that owns the submit
- *     transition — SignaturePad is presentation only)
- *   - FieldWalker (DOM sequencer that focuses this pad when the
- *     current field is a signature block)
- *
- * Visual: see docs/components/signature-pad.
- *
- * Design decisions:
- *   - Controlled component. Parent owns `value` + `onChange`. This
- *     lets SigningCommitBar preserve captured state across phase
- *     transitions (fill → consent → review → back to fill).
- *   - `mode` toggle is controlled by parent too — no built-in tabs.
- *     Callers usually render a small pill switcher above the pad.
- *   - Font loading uses `document.fonts.ready` before rendering typed
- *     mode. Without the await, the first typed capture paints in the
- *     browser fallback (usually Brush Script or serif italic).
- *   - Drawn mode uses `touch-action: none` + `pointerdown`
- *     preventDefault to stop iOS Safari from scrolling instead of
- *     drawing.
- *   - `imperativeHandle` exposes `clear()` for the parent's Undo
- *     button.
- */
-export interface SignaturePadProps {
-  /** Capture mode. Parent owns the toggle. */
-  mode: "typed" | "drawn";
-  /**
-   * Current captured PNG dataURL, or null when nothing captured.
-   * Controlled by the parent so state survives the parent's phase
-   * transitions.
-   */
-  value: string | null;
-  /**
-   * Fires whenever the pad captures a new dataURL (typed input
-   * changed, drawn stroke completed, cleared). null on clear.
-   */
-  onChange: (dataURL: string | null) => void;
-  /**
-   * Typed-mode input. Parent may bind this to the signer's display
-   * name for a stable signature. Ignored in drawn mode.
-   */
-  typedName?: string;
-  /**
-   * Typed-mode text change — fires ONLY in typed mode, on every
-   * keystroke. Parent updates its state; the pad reruns the typed
-   * bake on the next paint. Ignored in drawn mode.
-   */
-  onTypedNameChange?: (next: string) => void;
-  /** Canvas pixel width. Defaults to 480. */
-  width?: number;
-  /** Canvas pixel height. Defaults to 120. */
-  height?: number;
-  /**
-   * Font family used in typed mode. Defaults to `"Caveat", "Segoe
-   * Script", cursive` — Caveat is the most common signature font
-   * available across the Google Fonts CDN + Adobe Fonts.
-   */
-  typedFontFamily?: string;
-  /** Stroke color in drawn mode. Defaults to `#0b1220` (near-black). */
-  strokeColor?: string;
-  /** Stroke width in drawn mode. Defaults to 2. */
-  strokeWidth?: number;
-  /**
-   * Consumer-set className on the outer wrapper. Component ships its
-   * own inline styles; className is for layout only (grid parent
-   * spacing etc).
-   */
-  className?: string;
-}
-
-/** Imperative handle for parent-side controls (Undo, Clear buttons). */
-export interface SignaturePadHandle {
-  /** Wipe the canvas + emit null via onChange. */
-  clear: () => void;
-}
-
-const DEFAULT_WIDTH = 480;
-const DEFAULT_HEIGHT = 120;
-const DEFAULT_TYPED_FONT = '"Caveat", "Segoe Script", cursive';
-
-export const SignaturePad = forwardRef<SignaturePadHandle, SignaturePadProps>(
-  function SignaturePad(
-    {
-      mode,
-      value,
-      onChange,
-      typedName = "",
-      onTypedNameChange,
-      width = DEFAULT_WIDTH,
-      height = DEFAULT_HEIGHT,
-      typedFontFamily = DEFAULT_TYPED_FONT,
-      strokeColor = "#0b1220",
-      strokeWidth = 2,
-      className,
-    }: SignaturePadProps,
-    ref,
-  ): ReactNode {
-    const canvasRef = useRef<HTMLCanvasElement | null>(null);
-    // Track whether the currently-painted canvas is "dirty" (has
-    // strokes / typed pixels) so clear() knows whether to emit null.
-    const dirtyRef = useRef<boolean>(value !== null);
-
-    // Drawn mode point buffer — used for smoothed line via quadratic
-    // interpolation. Reset on stroke end.
-    const drawStateRef = useRef<{
-      drawing: boolean;
-      lastX: number;
-      lastY: number;
-    }>({ drawing: false, lastX: 0, lastY: 0 });
-
-    // Font-load await for typed mode. Setting to `true` triggers a
-    // re-render + re-paint of the current typedName. First mount in
-    // typed mode WITHOUT this await paints in the browser fallback
-    // font — Ben's spec called this out as a bug we must not ship.
-    const [fontReady, setFontReady] = useState<boolean>(() => {
-      if (typeof document === "undefined") return true;
-      // Best-effort: document.fonts may be absent in older browsers.
-      // Fall through as ready so we don't block the pad forever.
-      const fonts = (document as Document & { fonts?: FontFaceSet }).fonts;
-      return !fonts;
-    });
-    useEffect(() => {
-      if (fontReady) return;
-      if (typeof document === "undefined") return;
-      const fonts = (document as Document & { fonts?: FontFaceSet }).fonts;
-      if (!fonts) {
-        setFontReady(true);
-        return;
-      }
-      let cancelled = false;
-      // Actively REQUEST the typed font. @font-face registration
-      // (fontsource CSS etc.) doesn't fetch the file until some
-      // rendered text uses it — and this component's only consumer
-      // of the font is the canvas, whose fillText silently falls
-      // back to the next family when the face isn't loaded yet.
-      // fonts.load() forces the fetch; fonts.ready is the safety
-      // net for browsers without it / faces not registered.
-      const kick =
-        typeof fonts.load === "function"
-          ? fonts.load(`32px ${typedFontFamily}`).catch(() => [])
-          : Promise.resolve([]);
-      void kick
-        .then(() => fonts.ready)
-        .then(() => {
-          if (cancelled) return;
-          setFontReady(true);
-        });
-      return () => {
-        cancelled = true;
-      };
-      // typedFontFamily is config-stable per consumer; re-kicking on
-      // change is correct anyway.
-    }, [fontReady, typedFontFamily]);
-
-    // Mode switch — clear the canvas so a stale typed baseline
-    // doesn't hang around behind a drawn signature (or vice versa).
-    // MUST be declared BEFORE the typed-repaint + drawn-restore
-    // effects: effects run in declaration order, and v0.13.0 had
-    // this clear declared LAST — on switching to typed mode with a
-    // prefilled name the repaint painted first and this then wiped
-    // it (QA 2026-07-17: Type tab showed an empty pad until the
-    // signer edited the name). Skips the mount run so a parent-held
-    // captured value isn't nulled on first render.
-    const prevModeRef = useRef(mode);
-    useEffect(() => {
-      if (prevModeRef.current === mode) return;
-      prevModeRef.current = mode;
-      const canvas = canvasRef.current;
-      if (!canvas) return;
-      const ctx = canvas.getContext("2d");
-      if (!ctx) return;
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
-      dirtyRef.current = false;
-      onChange(null);
-      // Only fire when mode itself changes.
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [mode]);
-
-    // Repaint on typedName / mode / fontReady change. Drawn mode
-    // doesn't repaint imperatively — strokes are appended as the user
-    // draws.
-    useEffect(() => {
-      if (mode !== "typed") return;
-      const canvas = canvasRef.current;
-      if (!canvas) return;
-      const ctx = canvas.getContext("2d");
-      if (!ctx) return;
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
-      if (!typedName.trim()) {
-        dirtyRef.current = false;
-        onChange(null);
-        return;
-      }
-      if (!fontReady) return;
-      // Paint the name centred vertically, left-aligned horizontally.
-      // Auto-fit font size to width: start at height * 0.6 and shrink
-      // until measureText fits within `width - 24` (12px padding each
-      // side).
-      let fontSize = Math.round(height * 0.7);
-      ctx.textBaseline = "middle";
-      ctx.fillStyle = strokeColor;
-      const availableWidth = width - 24;
-      while (fontSize > 10) {
-        ctx.font = `${fontSize}px ${typedFontFamily}`;
-        if (ctx.measureText(typedName).width <= availableWidth) break;
-        fontSize -= 2;
-      }
-      ctx.fillText(typedName, 12, height / 2);
-      const dataURL = canvas.toDataURL("image/png");
-      dirtyRef.current = true;
-      onChange(dataURL);
-      // onChange is stable-by-contract from parent (React best
-      // practice); avoid feeding it into deps to prevent infinite
-      // loop.
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [
-      mode,
-      typedName,
-      fontReady,
-      width,
-      height,
-      typedFontFamily,
-      strokeColor,
-    ]);
-
-    // Restore a previously-captured value into the canvas on MOUNT
-    // only (parent phase round-trips remount the pad). Typed mode
-    // uses the repaint effect above; drawn mode needs to explicitly
-    // paint the dataURL back so subsequent strokes continue on top.
-    //
-    // Deliberately NOT re-run on mode switch: the clear effect wipes
-    // the canvas on switch, and re-painting the old capture here
-    // resurrected the TYPED baseline inside the drawn pad (v0.13.2
-    // regression — switching Type → Draw showed the handwriting-font
-    // bake as if it had been drawn).
-    const didRestoreRef = useRef(false);
-    useEffect(() => {
-      if (didRestoreRef.current) return;
-      didRestoreRef.current = true;
-      if (mode !== "drawn" || !value) return;
-      const canvas = canvasRef.current;
-      if (!canvas) return;
-      const ctx = canvas.getContext("2d");
-      if (!ctx) return;
-      const img = new Image();
-      img.onload = () => {
-        ctx.clearRect(0, 0, canvas.width, canvas.height);
-        ctx.drawImage(img, 0, 0);
-        dirtyRef.current = true;
-      };
-      img.src = value;
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
-
-    const clear = useCallback(() => {
-      const canvas = canvasRef.current;
-      if (canvas) {
-        const ctx = canvas.getContext("2d");
-        ctx?.clearRect(0, 0, canvas.width, canvas.height);
-      }
-      dirtyRef.current = false;
-      onChange(null);
-      if (mode === "typed") {
-        onTypedNameChange?.("");
-      }
-    }, [mode, onChange, onTypedNameChange]);
-
-    useImperativeHandle(ref, () => ({ clear }), [clear]);
-
-    // Drawn mode — pointer event handlers.
-    const onPointerDown = useCallback(
-      (e: ReactPointerEvent<HTMLCanvasElement>) => {
-        if (mode !== "drawn") return;
-        // touch-action: none on the canvas isn't enough on iOS
-        // Safari — need preventDefault too, otherwise the browser
-        // scrolls the page instead of drawing.
-        e.preventDefault();
-        const canvas = canvasRef.current;
-        if (!canvas) return;
-        const rect = canvas.getBoundingClientRect();
-        // Coordinate space: pointer client coords → canvas backing
-        // store coords. `rect` is CSS pixels; canvas.width is device
-        // pixels (or logical pixels when no DPR handling). Scale so
-        // strokes land at the visual point.
-        const scaleX = canvas.width / rect.width;
-        const scaleY = canvas.height / rect.height;
-        const x = (e.clientX - rect.left) * scaleX;
-        const y = (e.clientY - rect.top) * scaleY;
-        drawStateRef.current.drawing = true;
-        drawStateRef.current.lastX = x;
-        drawStateRef.current.lastY = y;
-        canvas.setPointerCapture(e.pointerId);
-      },
-      [mode],
-    );
-
-    const onPointerMove = useCallback(
-      (e: ReactPointerEvent<HTMLCanvasElement>) => {
-        if (mode !== "drawn") return;
-        if (!drawStateRef.current.drawing) return;
-        const canvas = canvasRef.current;
-        if (!canvas) return;
-        const ctx = canvas.getContext("2d");
-        if (!ctx) return;
-        const rect = canvas.getBoundingClientRect();
-        const scaleX = canvas.width / rect.width;
-        const scaleY = canvas.height / rect.height;
-        const x = (e.clientX - rect.left) * scaleX;
-        const y = (e.clientY - rect.top) * scaleY;
-        ctx.strokeStyle = strokeColor;
-        ctx.lineWidth = strokeWidth;
-        ctx.lineCap = "round";
-        ctx.lineJoin = "round";
-        ctx.beginPath();
-        ctx.moveTo(drawStateRef.current.lastX, drawStateRef.current.lastY);
-        // Simple line-to; a smoother quadratic curve is possible via
-        // buffering the last N points, but the default line-to
-        // already reads well at 2px stroke on human-scale pads.
-        ctx.lineTo(x, y);
-        ctx.stroke();
-        drawStateRef.current.lastX = x;
-        drawStateRef.current.lastY = y;
-        dirtyRef.current = true;
-      },
-      [mode, strokeColor, strokeWidth],
-    );
-
-    const onPointerUp = useCallback(
-      (e: ReactPointerEvent<HTMLCanvasElement>) => {
-        if (mode !== "drawn") return;
-        drawStateRef.current.drawing = false;
-        const canvas = canvasRef.current;
-        if (!canvas) return;
-        try {
-          canvas.releasePointerCapture(e.pointerId);
-        } catch {
-          // Some browsers throw when the pointer isn't captured
-          // (spurious pointerup); safe to ignore.
-        }
-        if (!dirtyRef.current) return;
-        const dataURL = canvas.toDataURL("image/png");
-        onChange(dataURL);
-      },
-      [mode, onChange],
-    );
-
-    // Wrapper + canvas styles. Inline (following the ck-* CSS var
-    // conventions) so consumers get a functional pad without needing
-    // to import a CSS file.
-    const wrapStyle: CSSProperties = useMemo(
-      () => ({
-        display: "flex",
-        flexDirection: "column",
-        gap: 8,
-        // fit-content sizes to the canvas's intrinsic `width` prop —
-        // which is exactly what overflowed narrow phones: the wrapper
-        // itself grew to 480px, so the canvas's own maxWidth:100%
-        // resolved against an already-overflowing parent. Cap the
-        // wrapper too; the flex-column children then shrink with it.
-        width: "fit-content",
-        maxWidth: "100%",
-      }),
-      [],
-    );
-    const canvasStyle: CSSProperties = useMemo(
-      () => ({
-        width,
-        // Never overflow a narrow container (phone signing surface) —
-        // the bitmap keeps its logical resolution and the pointer
-        // handlers already rescale via getBoundingClientRect, so CSS
-        // shrink is loss-free for drawing accuracy.
-        maxWidth: "100%",
-        height,
-        border: "1px solid var(--ck-border-subtle, #d4d4d8)",
-        borderRadius: "var(--ck-radius-sm, 6px)",
-        background: "var(--ck-bg-surface, #ffffff)",
-        // touch-action: none is the load-bearing bit for iOS Safari
-        // drawn mode — otherwise the page scrolls instead of drawing.
-        touchAction: "none",
-        cursor: mode === "drawn" ? "crosshair" : "default",
-        display: "block",
-      }),
-      [mode, width, height],
-    );
-    const typedInputStyle: CSSProperties = useMemo(
-      () => ({
-        padding: "6px 8px",
-        border: "1px solid var(--ck-border-subtle, #d4d4d8)",
-        borderRadius: "var(--ck-radius-sm, 6px)",
-        background: "var(--ck-bg-surface, #ffffff)",
-        color: "var(--ck-text-primary, #0b1220)",
-        fontSize: 14,
-        fontFamily: "inherit",
-        width,
-        maxWidth: "100%",
-        boxSizing: "border-box",
-      }),
-      [width],
-    );
-
-    return (
-      <div className={className} style={wrapStyle}>
-        {mode === "typed" ? (
-          <input
-            type="text"
-            value={typedName}
-            placeholder="Type your name"
-            onChange={(e) => onTypedNameChange?.(e.target.value)}
-            style={typedInputStyle}
-            aria-label="Type your signature"
-          />
-        ) : null}
-        <canvas
-          ref={canvasRef}
-          width={width}
-          height={height}
-          style={canvasStyle}
-          role="img"
-          aria-label={
-            mode === "typed"
-              ? "Typed signature preview"
-              : "Draw your signature"
-          }
-          onPointerDown={onPointerDown}
-          onPointerMove={onPointerMove}
-          onPointerUp={onPointerUp}
-          onPointerCancel={onPointerUp}
-          onPointerLeave={onPointerUp}
-        />
-      </div>
-    );
-  },
-);

package/src/primitives/Tag.tsx

@@ -1,56 +0,0 @@
-import type { ReactNode } from "react";
-import { cn } from "../lib/cn";
-
-// Small uppercase-mono pill — "PENDING", "LIVE", "Accepted", "3 docs".
-// Same vocabulary as ck-tag in base.css but with explicit tone variants
-// instead of inline color overrides. Use this when the tag is a status
-// indicator; use the bare .ck-tag class when it's just a caption.
-
-export type TagTone = "neutral" | "accent" | "success" | "warning" | "critical";
-
-export interface TagProps {
-  tone?: TagTone;
-  // Renders as a filled pill (background tinted) instead of a bare
-  // colored label. Default false.
-  filled?: boolean;
-  children: ReactNode;
-  className?: string;
-}
-
-const TONE_COLOR: Record<TagTone, string> = {
-  neutral: "var(--ck-text-tertiary)",
-  accent: "var(--ck-accent)",
-  success: "var(--ck-success)",
-  warning: "var(--ck-warning)",
-  critical: "var(--ck-critical)",
-};
-const TONE_BG: Record<TagTone, string> = {
-  neutral: "var(--ck-bg-muted)",
-  accent: "var(--ck-accent-muted)",
-  success: "var(--ck-success-muted)",
-  warning: "var(--ck-warning-muted)",
-  critical: "var(--ck-critical-muted)",
-};
-
-export function Tag({ tone = "neutral", filled = false, children, className }: TagProps) {
-  return (
-    <span
-      className={cn("ck-tag", className)}
-      data-ck-tag
-      data-tone={tone}
-      data-filled={filled ? "true" : undefined}
-      style={
-        filled
-          ? {
-              color: TONE_COLOR[tone],
-              background: TONE_BG[tone],
-              padding: "3px 8px",
-              borderRadius: "var(--ck-radius-sm)",
-            }
-          : { color: TONE_COLOR[tone] }
-      }
-    >
-      {children}
-    </span>
-  );
-}

package/src/primitives/Textarea.tsx

@@ -1,62 +0,0 @@
-import { forwardRef, useId, type TextareaHTMLAttributes, type ReactNode } from "react";
-import { cn } from "../lib/cn";
-
-// Same shape as Input — label + helper + error — for multiline.
-
-export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
-  label?: ReactNode;
-  helper?: ReactNode;
-  error?: string | null;
-}
-
-export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
-  function Textarea({ label, helper, error, className, id, ...rest }, ref) {
-    const autoId = useId();
-    const tid = id ?? autoId;
-    return (
-      <div
-        className={cn("ck-textarea-field", className)}
-        style={{ display: "flex", flexDirection: "column", gap: 6 }}
-      >
-        {label && (
-          <label
-            htmlFor={tid}
-            className="ck-eyebrow"
-            style={{ color: "var(--ck-text-secondary)" }}
-          >
-            {label}
-          </label>
-        )}
-        <textarea
-          ref={ref}
-          id={tid}
-          aria-invalid={error ? true : undefined}
-          {...rest}
-          className="ck-textarea"
-          style={{
-            minHeight: 80,
-            padding: "8px 12px",
-            font: "400 13px/1.5 var(--ck-font-sans)",
-            background: "var(--ck-bg-surface)",
-            color: "var(--ck-text-primary)",
-            border: `1px solid ${error ? "var(--ck-critical)" : "var(--ck-border-strong)"}`,
-            borderRadius: "var(--ck-radius-sm)",
-            outline: "none",
-            resize: "vertical",
-            transition: "border-color var(--ck-dur-fast) var(--ck-ease)",
-          }}
-        />
-        {(helper || error) && (
-          <div
-            style={{
-              font: "400 11px/1.4 var(--ck-font-sans)",
-              color: error ? "var(--ck-critical)" : "var(--ck-text-tertiary)",
-            }}
-          >
-            {error ?? helper}
-          </div>
-        )}
-      </div>
-    );
-  },
-);

package/src/primitives/ToggleSwitch.tsx

@@ -1,79 +0,0 @@
-import { cn } from "../lib/cn";
-
-// iOS-style track + knob toggle. Off-state track uses
-// --ck-text-secondary (not --ck-border-subtle which is near-invisible
-// on dark backgrounds — same lesson learned in the parent project).
-// Knob is fixed white so it reads on either accent or gray track.
-
-export interface ToggleSwitchProps {
-  checked: boolean;
-  onChange: (next: boolean) => void;
-  label?: React.ReactNode;
-  suffix?: React.ReactNode;
-  disabled?: boolean;
-  className?: string;
-}
-
-export function ToggleSwitch({
-  checked,
-  onChange,
-  label,
-  suffix,
-  disabled,
-  className,
-}: ToggleSwitchProps) {
-  return (
-    <label
-      className={cn("ck-toggle", className)}
-      style={{
-        display: "inline-flex",
-        alignItems: "center",
-        gap: 8,
-        font: "400 13px/1 var(--ck-font-sans)",
-        color: "var(--ck-text-secondary)",
-        cursor: disabled ? "not-allowed" : "pointer",
-        opacity: disabled ? 0.5 : 1,
-        userSelect: "none",
-      }}
-    >
-      <button
-        type="button"
-        role="switch"
-        aria-checked={checked}
-        disabled={disabled}
-        onClick={() => !disabled && onChange(!checked)}
-        style={{
-          position: "relative",
-          width: 34,
-          height: 20,
-          borderRadius: 999,
-          border: "1px solid var(--ck-text-tertiary)",
-          background: checked ? "var(--ck-accent)" : "var(--ck-text-secondary)",
-          padding: 0,
-          cursor: disabled ? "not-allowed" : "pointer",
-          flexShrink: 0,
-          transition: "background var(--ck-dur-fast) var(--ck-ease)",
-        }}
-      >
-        <span
-          aria-hidden
-          style={{
-            position: "absolute",
-            top: 2,
-            left: checked ? 16 : 2,
-            width: 14,
-            height: 14,
-            background: "#FFFFFF",
-            borderRadius: "50%",
-            boxShadow: "0 1px 3px rgba(0,0,0,0.35)",
-            transition: "left var(--ck-dur-fast) var(--ck-ease)",
-          }}
-        />
-      </button>
-      {label}
-      {suffix && (
-        <span style={{ color: "var(--ck-text-tertiary)" }}>{suffix}</span>
-      )}
-    </label>
-  );
-}