@schnsrw/casual-sheets 0.2.0

package/src/signing/captures.tsx

@@ -0,0 +1,316 @@
+/**
+ * Three signature-capture surfaces: drawn (canvas), typed (input
+ * rendered in a script font), uploaded (image file picker).
+ *
+ * Each one emits an `{ bytes, mime }` pair that the parent feeds
+ * into SigningContext.signField. The components are presentation +
+ * input only — they don't know about the controller or the field
+ * they're capturing for.
+ */
+
+import { useEffect, useRef, useState, type CSSProperties } from 'react';
+
+export interface CapturedSignature {
+  bytes: ArrayBuffer;
+  mime: string;
+}
+
+// ---------------------------------------------------------------
+// Drawn — canvas
+// ---------------------------------------------------------------
+
+export interface DrawnSignaturePadProps {
+  /** Fired when the user clicks "Use this signature". */
+  onCapture: (sig: CapturedSignature) => void;
+  /** Optional clear-button label override. */
+  clearLabel?: string;
+  /** Optional save-button label override. */
+  saveLabel?: string;
+  /** Canvas pixel size. Default 480 × 160. */
+  width?: number;
+  height?: number;
+}
+
+export function DrawnSignaturePad({
+  onCapture,
+  clearLabel = 'Clear',
+  saveLabel = 'Use this signature',
+  width = 480,
+  height = 160,
+}: DrawnSignaturePadProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const drawingRef = useRef(false);
+  const [hasInk, setHasInk] = useState(false);
+
+  // Set up a clean canvas on mount. Background is transparent so
+  // the stamped image composites cleanly over the document.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.strokeStyle = '#0f172a';
+    ctx.lineWidth = 2;
+    ctx.lineCap = 'round';
+    ctx.lineJoin = 'round';
+  }, []);
+
+  const start = (e: React.PointerEvent<HTMLCanvasElement>) => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+    const { x, y } = pointerPos(e, canvas);
+    ctx.beginPath();
+    ctx.moveTo(x, y);
+    drawingRef.current = true;
+    canvas.setPointerCapture(e.pointerId);
+  };
+
+  const move = (e: React.PointerEvent<HTMLCanvasElement>) => {
+    if (!drawingRef.current) return;
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+    const { x, y } = pointerPos(e, canvas);
+    ctx.lineTo(x, y);
+    ctx.stroke();
+    if (!hasInk) setHasInk(true);
+  };
+
+  const end = (e: React.PointerEvent<HTMLCanvasElement>) => {
+    drawingRef.current = false;
+    canvasRef.current?.releasePointerCapture(e.pointerId);
+  };
+
+  const clear = () => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    setHasInk(false);
+  };
+
+  const save = async () => {
+    const canvas = canvasRef.current;
+    if (!canvas || !hasInk) return;
+    const blob = await new Promise<Blob | null>((resolve) => {
+      canvas.toBlob((b) => resolve(b), 'image/png');
+    });
+    if (!blob) return;
+    const bytes = await blob.arrayBuffer();
+    onCapture({ bytes, mime: 'image/png' });
+    clear();
+  };
+
+  return (
+    <div style={padWrapStyle} data-testid="drawn-signature-pad">
+      <canvas
+        ref={canvasRef}
+        width={width}
+        height={height}
+        style={padCanvasStyle(width, height)}
+        onPointerDown={start}
+        onPointerMove={move}
+        onPointerUp={end}
+        onPointerLeave={end}
+        data-testid="drawn-signature-canvas"
+      />
+      <div style={padActionsStyle}>
+        <button type="button" onClick={clear} style={secondaryBtnStyle(false)}>
+          {clearLabel}
+        </button>
+        <button
+          type="button"
+          onClick={save}
+          disabled={!hasInk}
+          style={primaryBtnStyle(!hasInk)}
+          data-testid="drawn-signature-save"
+        >
+          {saveLabel}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function pointerPos(e: React.PointerEvent<HTMLCanvasElement>, canvas: HTMLCanvasElement) {
+  const rect = canvas.getBoundingClientRect();
+  const scaleX = canvas.width / rect.width;
+  const scaleY = canvas.height / rect.height;
+  return {
+    x: (e.clientX - rect.left) * scaleX,
+    y: (e.clientY - rect.top) * scaleY,
+  };
+}
+
+// ---------------------------------------------------------------
+// Typed
+// ---------------------------------------------------------------
+
+export interface TypedSignatureFieldProps {
+  onCapture: (sig: CapturedSignature) => void;
+  defaultText?: string;
+  saveLabel?: string;
+}
+
+export function TypedSignatureField({
+  onCapture,
+  defaultText = '',
+  saveLabel = 'Use this signature',
+}: TypedSignatureFieldProps) {
+  const [value, setValue] = useState(defaultText);
+  const save = () => {
+    const trimmed = value.trim();
+    if (!trimmed) return;
+    const bytes = new TextEncoder().encode(trimmed).buffer;
+    onCapture({ bytes, mime: 'text/plain' });
+    setValue('');
+  };
+  return (
+    <div style={padWrapStyle} data-testid="typed-signature-field">
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        placeholder="Type your full name"
+        style={typedInputStyle}
+        data-testid="typed-signature-input"
+        autoFocus
+      />
+      <div style={padActionsStyle}>
+        <button
+          type="button"
+          onClick={save}
+          disabled={!value.trim()}
+          style={primaryBtnStyle(!value.trim())}
+          data-testid="typed-signature-save"
+        >
+          {saveLabel}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------
+// Uploaded
+// ---------------------------------------------------------------
+
+export interface UploadedSignatureFieldProps {
+  onCapture: (sig: CapturedSignature) => void;
+  /** Accept attribute. Default image/*. */
+  accept?: string;
+}
+
+export function UploadedSignatureField({
+  onCapture,
+  accept = 'image/png,image/jpeg,image/svg+xml',
+}: UploadedSignatureFieldProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [fileName, setFileName] = useState<string | null>(null);
+  const onChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    const bytes = await file.arrayBuffer();
+    onCapture({ bytes, mime: file.type || 'application/octet-stream' });
+    setFileName(file.name);
+    if (inputRef.current) inputRef.current.value = '';
+  };
+  return (
+    <div style={padWrapStyle} data-testid="uploaded-signature-field">
+      <label style={uploadLabelStyle}>
+        <input
+          ref={inputRef}
+          type="file"
+          accept={accept}
+          onChange={onChange}
+          style={{ display: 'none' }}
+          data-testid="uploaded-signature-input"
+        />
+        <span>{fileName ?? 'Choose image…'}</span>
+      </label>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------
+// Shared styles
+// ---------------------------------------------------------------
+
+const padWrapStyle: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 10,
+};
+
+const padCanvasStyle = (w: number, h: number): CSSProperties => ({
+  width: w,
+  height: h,
+  maxWidth: '100%',
+  border: '1px dashed var(--doc-border, #cbd5e1)',
+  borderRadius: 8,
+  background: 'var(--doc-surface, #fff)',
+  cursor: 'crosshair',
+  touchAction: 'none',
+});
+
+const padActionsStyle: CSSProperties = {
+  display: 'flex',
+  justifyContent: 'flex-end',
+  gap: 8,
+};
+
+const typedInputStyle: CSSProperties = {
+  width: '100%',
+  padding: '10px 12px',
+  border: '1px solid var(--doc-border, #cbd5e1)',
+  borderRadius: 6,
+  fontSize: 18,
+  fontFamily: '"Caveat", "Dancing Script", "Brush Script MT", cursive',
+  background: 'var(--doc-surface, #fff)',
+  color: 'var(--doc-text, #0f172a)',
+};
+
+const uploadLabelStyle: CSSProperties = {
+  display: 'inline-flex',
+  padding: '8px 14px',
+  border: '1px dashed var(--doc-border, #cbd5e1)',
+  borderRadius: 6,
+  background: 'var(--doc-surface, #fff)',
+  color: 'var(--doc-text, #0f172a)',
+  fontSize: 13,
+  cursor: 'pointer',
+  alignSelf: 'flex-start',
+};
+
+function primaryBtnStyle(disabled: boolean): CSSProperties {
+  return {
+    padding: '8px 16px',
+    borderRadius: 6,
+    border: '1px solid transparent',
+    background: disabled ? 'var(--doc-border, #cbd5e1)' : 'var(--doc-accent, #2563eb)',
+    color: disabled ? 'var(--doc-text-muted, #64748b)' : '#fff',
+    fontSize: 13,
+    fontWeight: 600,
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    fontFamily: 'inherit',
+  };
+}
+
+function secondaryBtnStyle(disabled: boolean): CSSProperties {
+  return {
+    padding: '8px 16px',
+    borderRadius: 6,
+    border: '1px solid var(--doc-border, #cbd5e1)',
+    background: 'transparent',
+    color: 'var(--doc-text, #0f172a)',
+    fontSize: 13,
+    fontWeight: 500,
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    fontFamily: 'inherit',
+  };
+}

package/src/signing/controller.ts

@@ -0,0 +1,151 @@
+/**
+ * Signing state machine — pure with respect to React so bun-test
+ * can exercise it without a renderer. The React wrappers
+ * (SigningProvider / SigningPane) sit on top of this.
+ *
+ * Single source of truth for "which field is the signer on,
+ * which fields are done, can we complete yet" — the React layer
+ * never recomputes these from scratch.
+ */
+
+import type { SignedFieldPayload, SignatureField, SignatureMode } from './types';
+
+export interface SigningSnapshot {
+  fields: SignatureField[];
+  mode: SignatureMode;
+  /** Fields completed in order they were signed. */
+  signed: Record<string, SignedFieldPayload>;
+  /** Index into `fields` of the field the signer should focus on
+   *  next. -1 once everything required is done. */
+  activeFieldIndex: number;
+  /** True once every required field has a payload. */
+  canComplete: boolean;
+  /** True once the controller has received a completion command. */
+  isComplete: boolean;
+  /** True if a cancel has been emitted. */
+  isCancelled: boolean;
+}
+
+export interface SigningController {
+  snapshot(): SigningSnapshot;
+  subscribe(listener: (s: SigningSnapshot) => void): () => void;
+  /** Record a signed field. Throws if the field id is unknown. */
+  signField(payload: SignedFieldPayload): void;
+  /** Move focus to a specific field (concurrent mode let users
+   *  pick); in sequential mode the controller silently no-ops if
+   *  the requested field isn't the next required. */
+  focusField(fieldId: string): void;
+  /** Mark the session complete. Returns the snapshot at the
+   *  moment of completion; throws if not yet canComplete. */
+  complete(): SigningSnapshot;
+  /** Mark the session cancelled. Idempotent. */
+  cancel(): void;
+}
+
+export function createSigningController(
+  fields: SignatureField[],
+  mode: SignatureMode,
+): SigningController {
+  if (fields.length === 0) {
+    throw new Error('createSigningController: at least one field required');
+  }
+  const fieldIds = new Set(fields.map((f) => f.fieldId));
+  if (fieldIds.size !== fields.length) {
+    throw new Error('createSigningController: duplicate fieldId');
+  }
+
+  const signed: Record<string, SignedFieldPayload> = {};
+  let activeFieldIndex = nextRequiredIndex(fields, signed);
+  let isComplete = false;
+  let isCancelled = false;
+  const listeners = new Set<(s: SigningSnapshot) => void>();
+
+  function emit() {
+    const snap = snapshotInternal();
+    for (const l of listeners) l(snap);
+  }
+
+  function snapshotInternal(): SigningSnapshot {
+    return {
+      fields,
+      mode,
+      signed: { ...signed },
+      activeFieldIndex,
+      canComplete: allRequiredSigned(fields, signed),
+      isComplete,
+      isCancelled,
+    };
+  }
+
+  return {
+    snapshot: snapshotInternal,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    signField(payload) {
+      if (isComplete || isCancelled) return;
+      if (!fieldIds.has(payload.fieldId)) {
+        throw new Error(`signField: unknown fieldId ${payload.fieldId}`);
+      }
+      signed[payload.fieldId] = payload;
+      activeFieldIndex = nextRequiredIndex(fields, signed);
+      emit();
+    },
+    focusField(fieldId) {
+      if (isComplete || isCancelled) return;
+      const idx = fields.findIndex((f) => f.fieldId === fieldId);
+      if (idx < 0) return;
+      if (mode === 'sequential') {
+        // Sequential mode: only the next-required field is focusable.
+        const next = nextRequiredIndex(fields, signed);
+        if (idx !== next) return;
+      }
+      activeFieldIndex = idx;
+      emit();
+    },
+    complete() {
+      if (!allRequiredSigned(fields, signed)) {
+        throw new Error('complete: required fields are still unsigned');
+      }
+      isComplete = true;
+      activeFieldIndex = -1;
+      emit();
+      return snapshotInternal();
+    },
+    cancel() {
+      if (isComplete || isCancelled) return;
+      isCancelled = true;
+      activeFieldIndex = -1;
+      emit();
+    },
+  };
+}
+
+// ---------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------
+
+function allRequiredSigned(
+  fields: SignatureField[],
+  signed: Record<string, SignedFieldPayload>,
+): boolean {
+  return fields.every((f) => !f.required || signed[f.fieldId] !== undefined);
+}
+
+function nextRequiredIndex(
+  fields: SignatureField[],
+  signed: Record<string, SignedFieldPayload>,
+): number {
+  for (let i = 0; i < fields.length; i++) {
+    if (fields[i].required && !signed[fields[i].fieldId]) return i;
+  }
+  // Either all required are done OR no required exists; pick the
+  // first unsigned optional.
+  for (let i = 0; i < fields.length; i++) {
+    if (!signed[fields[i].fieldId]) return i;
+  }
+  return -1;
+}

package/src/signing/controller.unit.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Signing controller — pure state-machine tests. Mirrors the
+ * document/ repo's controller.test.ts; the controller code itself
+ * is byte-identical across both products (signing is a uniform
+ * concern). When you change controller.ts here, change it there
+ * too.
+ */
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import { createSigningController } from './controller';
+import type { SignatureField, SignedFieldPayload } from './types';
+
+const ALICE: SignatureField = {
+  fieldId: 'alice',
+  label: 'Alice',
+  required: true,
+  anchor: { kind: 'sheet', sheet: 'Sheet1', cell: 'B2' },
+  methods: ['drawn'],
+};
+
+const BOB: SignatureField = {
+  fieldId: 'bob',
+  label: 'Bob',
+  required: true,
+  anchor: { kind: 'sheet', sheet: 'Sheet1', cell: 'B3' },
+  methods: ['typed'],
+};
+
+const CAROL_OPTIONAL: SignatureField = {
+  fieldId: 'carol',
+  label: 'Carol (witness)',
+  required: false,
+  anchor: { kind: 'sheet', sheet: 'Sheet1', cell: 'B4' },
+  methods: ['drawn', 'typed'],
+};
+
+function payload(fieldId: string): SignedFieldPayload {
+  return {
+    fieldId,
+    method: 'drawn',
+    bytes: new Uint8Array([1, 2, 3]).buffer,
+    mime: 'image/png',
+    signedAt: '2026-06-08T00:00:00Z',
+  };
+}
+
+test('createSigningController: starts with the first required field active', () => {
+  const c = createSigningController([ALICE, BOB], 'sequential');
+  assert.equal(c.snapshot().activeFieldIndex, 0);
+  assert.equal(c.snapshot().canComplete, false);
+  assert.equal(c.snapshot().isComplete, false);
+});
+
+test('signField advances activeFieldIndex to the next required', () => {
+  const c = createSigningController([ALICE, BOB], 'sequential');
+  c.signField(payload('alice'));
+  assert.equal(c.snapshot().activeFieldIndex, 1);
+  assert.equal(c.snapshot().canComplete, false);
+});
+
+test('canComplete flips true once every required field is signed', () => {
+  const c = createSigningController([ALICE, BOB, CAROL_OPTIONAL], 'sequential');
+  c.signField(payload('alice'));
+  c.signField(payload('bob'));
+  assert.equal(c.snapshot().canComplete, true);
+  assert.equal(c.snapshot().signed['carol'], undefined);
+});
+
+test('complete throws when required fields are still unsigned', () => {
+  const c = createSigningController([ALICE, BOB], 'sequential');
+  c.signField(payload('alice'));
+  assert.throws(() => c.complete());
+});
+
+test('complete succeeds when all required done', () => {
+  const c = createSigningController([ALICE, BOB], 'sequential');
+  c.signField(payload('alice'));
+  c.signField(payload('bob'));
+  const snap = c.complete();
+  assert.equal(snap.isComplete, true);
+  assert.equal(snap.activeFieldIndex, -1);
+});
+
+test('cancel is idempotent and prevents further signField', () => {
+  const c = createSigningController([ALICE, BOB], 'sequential');
+  c.cancel();
+  c.cancel();
+  assert.equal(c.snapshot().isCancelled, true);
+  c.signField(payload('alice'));
+  assert.equal(c.snapshot().signed['alice'], undefined);
+});
+
+test('focusField in sequential mode rejects jumps to non-active fields', () => {
+  const c = createSigningController([ALICE, BOB], 'sequential');
+  c.focusField('bob');
+  assert.equal(c.snapshot().activeFieldIndex, 0);
+});
+
+test('focusField in concurrent mode allows any unsigned field', () => {
+  const c = createSigningController([ALICE, BOB], 'concurrent');
+  c.focusField('bob');
+  assert.equal(c.snapshot().activeFieldIndex, 1);
+});
+
+test('subscribers receive snapshots on every change', () => {
+  const c = createSigningController([ALICE, BOB], 'sequential');
+  const events: number[] = [];
+  const unsub = c.subscribe((s) => events.push(s.activeFieldIndex));
+  c.signField(payload('alice'));
+  c.signField(payload('bob'));
+  c.complete();
+  unsub();
+  assert.deepEqual(events, [1, -1, -1]);
+});
+
+test('signField throws on unknown fieldId', () => {
+  const c = createSigningController([ALICE], 'sequential');
+  assert.throws(() =>
+    c.signField({
+      ...payload('not-a-field'),
+      fieldId: 'not-a-field',
+    }),
+  );
+});
+
+test('rejects duplicate fieldId at construction', () => {
+  assert.throws(() => createSigningController([ALICE, { ...BOB, fieldId: 'alice' }], 'sequential'));
+});
+
+test('rejects empty field array at construction', () => {
+  assert.throws(() => createSigningController([], 'sequential'));
+});

package/src/signing/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Signing — document-signature pipeline.
+ *
+ * Surfaces:
+ *   - SigningProvider + useSigning — React context wrapping the
+ *     pure controller.
+ *   - SigningPane — floating sidebar walking the signer through
+ *     fields.
+ *   - DrawnSignaturePad / TypedSignatureField / UploadedSignatureField
+ *     — capture surfaces emitting { bytes, mime } pairs.
+ *
+ * Types mirror the iframe envelopes from
+ * `docs/internal/13-iframe-protocol.md` — same shape across docs
+ * and sheet.
+ */
+
+export { SigningProvider, useSigning, type SigningProviderProps } from './SigningProvider';
+export { SigningPane, type SigningPaneProps } from './SigningPane';
+export {
+  DrawnSignaturePad,
+  TypedSignatureField,
+  UploadedSignatureField,
+  type CapturedSignature,
+  type DrawnSignaturePadProps,
+  type TypedSignatureFieldProps,
+  type UploadedSignatureFieldProps,
+} from './captures';
+export {
+  createSigningController,
+  type SigningController,
+  type SigningSnapshot,
+} from './controller';
+export type {
+  CancelReason,
+  DocAnchor,
+  SheetAnchor,
+  SignatureAnchor,
+  SignatureCompletePayload,
+  SignatureField,
+  SignatureMethod,
+  SignatureMode,
+  SignedFieldPayload,
+  SigningSessionConfig,
+} from './types';