@cosxai/ui 0.11.2 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "COSX design system — React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",

package/src/primitives/CopyField.tsx

@@ -0,0 +1,139 @@
+import { forwardRef, useCallback, useRef, useState, type HTMLAttributes, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// CopyField — read-only value field with an embedded Copy button.
+//
+// One bordered frame (same 36px field chrome as Input-with-addon):
+// the value renders mono + ellipsized on the left, the Copy button
+// sits INSIDE the frame flush right on a muted slab (mirrors Input's
+// suffix addon). Clicking copies to the clipboard and flips the
+// label to "Copied ✓" for a beat; clicking the value text selects it
+// (manual-copy fallback for non-secure origins where the Clipboard
+// API is unavailable).
+//
+// Use for share links, signing URLs, tokens, API keys — anywhere the
+// user's next action is overwhelmingly "copy this". Compose with:
+// dialog bodies (share link rows), sidebar token reveals, settings
+// pages (API-key display).
+//
+// Forwards ref to the copy <button>. Spreads `...rest` on the frame
+// so consumers can pass data-* / aria-* / style / className.
+
+export interface CopyFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, "onCopy"> {
+  // The string shown + copied. Rendered mono, single-line, ellipsized.
+  value: string;
+  // Copy-button label; flips to `copiedLabel` after a click.
+  copyLabel?: ReactNode;
+  copiedLabel?: ReactNode;
+  // How long the copied state lingers before flipping back (ms).
+  copiedForMs?: number;
+  // Notified after a successful clipboard write. Clipboard failures
+  // are silent by design — the value stays selectable in the field.
+  onCopied?: (value: string) => void;
+}
+
+export const CopyField = forwardRef<HTMLButtonElement, CopyFieldProps>(function CopyField(
+  {
+    value,
+    copyLabel = "Copy",
+    copiedLabel = "Copied ✓",
+    copiedForMs = 1500,
+    onCopied,
+    className,
+    style,
+    ...rest
+  },
+  ref,
+) {
+  const [copied, setCopied] = useState(false);
+  const valueRef = useRef<HTMLElement | null>(null);
+
+  const handleCopy = useCallback(() => {
+    void navigator.clipboard
+      ?.writeText(value)
+      .then(() => onCopied?.(value))
+      .catch(() => {
+        // Clipboard rejected (permissions / non-secure origin). The
+        // value stays visible + selectable in the field — no error UI.
+      });
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), copiedForMs);
+  }, [value, copiedForMs, onCopied]);
+
+  // Click-to-select on the value — the manual-copy fallback.
+  const handleSelectAll = useCallback(() => {
+    const node = valueRef.current;
+    if (!node) return;
+    const range = document.createRange();
+    range.selectNodeContents(node);
+    const sel = window.getSelection();
+    sel?.removeAllRanges();
+    sel?.addRange(range);
+  }, []);
+
+  return (
+    <div
+      {...rest}
+      className={cn("ck-copy-field", className)}
+      style={{
+        display: "flex",
+        alignItems: "stretch",
+        height: 36,
+        background: "var(--ck-bg-surface)",
+        border: "1px solid var(--ck-border-strong)",
+        borderRadius: "var(--ck-radius-sm)",
+        overflow: "hidden",
+        minWidth: 0,
+        ...(style ?? {}),
+      }}
+    >
+      <code
+        ref={valueRef}
+        title={value}
+        onClick={handleSelectAll}
+        style={{
+          flex: 1,
+          minWidth: 0,
+          alignSelf: "center",
+          padding: "0 12px",
+          font: "400 12px/1.5 var(--ck-font-mono, ui-monospace, monospace)",
+          color: "var(--ck-text-primary)",
+          whiteSpace: "nowrap",
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+          cursor: "text",
+        }}
+      >
+        {value}
+      </code>
+      <button
+        ref={ref}
+        type="button"
+        onClick={handleCopy}
+        disabled={copied}
+        className="ck-copy-field-btn"
+        style={{
+          flex: "0 0 auto",
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: "0 14px",
+          // Reserve the wider copied-label footprint so the value
+          // column doesn't shift mid-flash.
+          minWidth: 84,
+          border: "none",
+          borderLeft: "1px solid var(--ck-border-strong)",
+          background: "var(--ck-bg-muted)",
+          color: copied ? "var(--ck-text-secondary)" : "var(--ck-text-primary)",
+          font: "500 11px/1 var(--ck-font-sans)",
+          letterSpacing: "0.04em",
+          textTransform: "uppercase",
+          cursor: copied ? "default" : "pointer",
+          transition: "color var(--ck-dur-fast) var(--ck-ease)",
+        }}
+      >
+        {copied ? copiedLabel : copyLabel}
+      </button>
+    </div>
+  );
+});

package/src/primitives/SignaturePad.tsx

@@ -0,0 +1,415 @@
+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;
+      void fonts.ready.then(() => {
+        if (cancelled) return;
+        setFontReady(true);
+      });
+      return () => {
+        cancelled = true;
+      };
+    }, [fontReady]);
+
+    // 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 remount.
+    // Typed mode uses the effect above; drawn mode needs to explicitly
+    // paint the dataURL back onto the canvas so subsequent strokes
+    // continue on top of it (rather than starting from blank).
+    useEffect(() => {
+      if (mode !== "drawn") return;
+      if (!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
+    }, [mode]);
+
+    // Mode switch — clear the canvas so a stale typed baseline
+    // doesn't hang around behind a drawn signature (or vice versa).
+    useEffect(() => {
+      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]);
+
+    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,
+        width: "fit-content",
+      }),
+      [],
+    );
+    const canvasStyle: CSSProperties = useMemo(
+      () => ({
+        width,
+        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,
+      }),
+      [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/index.ts

@@ -28,3 +28,7 @@ export { PageHeader } from "./PageHeader";
 export type { PageHeaderProps } from "./PageHeader";
 export { MentionCombobox, findActiveMentionStart, extractQuery } from "./MentionCombobox";
 export type { MentionComboboxProps, MentionComboboxHandle } from "./MentionCombobox";
+export { SignaturePad } from "./SignaturePad";
+export type { SignaturePadProps, SignaturePadHandle } from "./SignaturePad";
+export { CopyField } from "./CopyField";
+export type { CopyFieldProps } from "./CopyField";