sdaia-ui 1.0.1

package/src/components/Signature/Signature.tsx

@@ -0,0 +1,905 @@
+'use client';
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type DragEvent,
+} from 'react';
+import { cn } from '../../lib/cn';
+import type { SignatureProps, SignatureType } from './Signature.types';
+import {
+  CARD_ROOT,
+  TAB_SECTION,
+  TAB_DIVIDER,
+  OPTIONS_ROW,
+  OPTIONS_LABEL,
+  OPTIONS_TYPEFACE_LABEL,
+  OPTIONS_SWATCH_PILL,
+  OPTIONS_SIZE_PILL,
+  DRAW_CANVAS_WRAPPER,
+  TEXT_CANVAS_WRAPPER,
+  TEXT_BASELINE,
+  TEXT_INPUT,
+  HELPER_TEXT,
+  ACTIONS_ROW,
+} from './Signature.variants';
+import { Button } from '../Button';
+import { HorizontalTabs } from '../HorizontalTabs';
+import { FileUploadBase } from '../FileUploadBase';
+
+/*
+ * Signature — a modal-style card for capturing a signature.
+ *
+ * Figma: "Signature" — node 6253:87861
+ *
+ * ## Three capture modes (tabs)
+ *   draw   → HTML5 canvas with mouse / touch drawing
+ *   text   → typed input field with font selector
+ *   upload → file drop zone (reuses FileUploadBase)
+ *
+ * ## Responsive tab sizes
+ *   mobile  < 768px  → HorizontalTabs size="sm"
+ *   tablet  768–1279px → HorizontalTabs size="md"
+ *   desktop ≥ 1280px → HorizontalTabs size="lg"
+ *
+ * ## Cancel behaviour
+ *   Clicking Cancel clears the current signature content (canvas, typed text,
+ *   or uploaded file) then fires `onCancel`. It does NOT change the active tab.
+ *
+ * ## Color picker
+ *   A custom popover (not the native browser input) opens BELOW the swatch
+ *   button. Clicking the button again closes it. Clicking outside also closes.
+ *   Presets + a "Custom" <input type="color"> live inside the popover.
+ *
+ * ## RTL
+ *   Set dir="rtl" on an ancestor. CSS direction inheritance reverses flex
+ *   row order automatically — tabs, options bar, buttons all flip without JS.
+ *
+ * ## Dark mode
+ *   Toggle html.dark — all dark: classes are in Signature.variants.ts.
+ */
+
+/* ─────────────────────────────────────────────────────────────────
+ * Icons
+ * ─────────────────────────────────────────────────────────────── */
+
+function ChevronDownIcon() {
+  return (
+    <svg width="100%" height="100%" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <path
+        d="M4 6L8 10L12 6"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+/* ─────────────────────────────────────────────────────────────────
+ * ColorPickerPopover
+ *
+ * Opens a floating panel BELOW the swatch button.
+ * Clicking the trigger again TOGGLES it closed.
+ * Clicking outside also closes it.
+ * ─────────────────────────────────────────────────────────────── */
+
+const PRESET_COLORS = [
+  '#000000', '#374151', '#1f2a37', '#111827',
+  '#1b8354', '#175cd3', '#b42318', '#7e22ce',
+  '#ffffff', '#f9fafb', '#d1d5db', '#9ca3af',
+  '#fef3c7', '#fce7f3', '#dbeafe', '#dcfce7',
+];
+
+interface ColorPickerPopoverProps {
+  value: string;
+  onChange: (color: string) => void;
+  /** Which edge of the trigger the popover aligns to.
+   *  'start' (default) → panel left-aligns with trigger (logical start).
+   *  'end'             → panel right-aligns with trigger (logical end).
+   *  Use 'end' when the trigger is near the inline-end of its container
+   *  to prevent the panel from overflowing outside the card. */
+  align?: 'start' | 'end';
+  ariaLabel?: string;
+}
+
+function ColorPickerPopover({ value, onChange, align = 'start', ariaLabel }: ColorPickerPopoverProps) {
+  const [open, setOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const customInputRef = useRef<HTMLInputElement>(null);
+  /** Tracks whether the browser-native color dialog is currently open so we
+   *  can close it programmatically on a second click of the Custom button. */
+  const nativePickerOpenRef = useRef(false);
+
+  /* Close popover on click outside */
+  useEffect(() => {
+    if (!open) return;
+    const handleOutside = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleOutside);
+    return () => document.removeEventListener('mousedown', handleOutside);
+  }, [open]);
+
+  return (
+    <div ref={containerRef} className="relative">
+      {/* Trigger — clicking toggles the popover */}
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        aria-label={ariaLabel ?? 'Pick color'}
+        aria-expanded={open}
+        aria-haspopup="dialog"
+        className={cn(OPTIONS_SWATCH_PILL, 'cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[rgba(27,131,84,0.7)]')}
+      >
+        <span
+          className="block shrink-0 size-icon-sm rounded-[4px] border border-[rgba(210,214,219,1)] dark:border-[rgba(75,85,99,1)]"
+          style={{ backgroundColor: value }}
+        />
+        <span className="size-icon-sm text-[rgba(108,115,127,1)] dark:text-[rgba(156,163,175,1)]">
+          <ChevronDownIcon />
+        </span>
+      </button>
+
+      {/* Popover panel — positioned below the trigger, RTL-safe.
+          align='start' → start-0 (panel left-edge = button left-edge, flips in RTL).
+          align='end'   → end-0   (panel right-edge = button right-edge, flips in RTL).
+          This prevents the panel from overflowing the card when the trigger is
+          near the inline-end of its container (e.g. the Background picker). */}
+      {open && (
+        <div
+          role="dialog"
+          aria-label={ariaLabel ?? 'Color picker'}
+          className={cn(
+            'absolute z-50',
+            'top-[calc(100%+4px)]',
+            align === 'end' ? 'end-0' : 'start-0',
+            'bg-white dark:bg-[rgba(17,25,39,1)]',
+            'border border-[rgba(210,214,219,1)] dark:border-[rgba(55,65,81,1)]',
+            'rounded-[8px]',
+            'shadow-[0px_4px_16px_rgba(0,0,0,0.12)]',
+            'p-spacing-md',
+            'w-[176px]',
+          )}
+        >
+          {/* Preset swatches — 4 × 4 grid */}
+          <div className="grid grid-cols-4 gap-spacing-xs">
+            {PRESET_COLORS.map((color) => (
+              <button
+                key={color}
+                type="button"
+                onClick={() => { onChange(color); setOpen(false); }}
+                className={cn(
+                  'size-icon-md rounded-[4px] border-2 shrink-0 transition-transform hover:scale-110 focus-visible:outline-none',
+                  value.toLowerCase() === color.toLowerCase()
+                    ? 'border-[rgba(27,131,84,1)]'
+                    : 'border-[rgba(210,214,219,1)] dark:border-[rgba(75,85,99,1)]',
+                )}
+                style={{ backgroundColor: color }}
+                aria-label={color}
+                title={color}
+              />
+            ))}
+          </div>
+
+          {/* Custom free-form color.
+              The input stays visible (not hidden) so the browser can position the
+              native color dialog directly adjacent to it. Toggling is handled
+              manually: first click sets nativePickerOpenRef = true (picker opens
+              via browser default); second click calls input.blur() which closes
+              the native dialog in all major browsers, then resets the flag. The
+              onBlur handler covers the case where the picker is dismissed by any
+              other means (Escape, clicking a preset, etc.). */}
+          <div className="mt-spacing-md pt-spacing-md border-t border-[rgba(210,214,219,1)] dark:border-[rgba(55,65,81,1)] flex items-center gap-spacing-xs">
+            <span className="text-text-xs font-normal text-[rgba(108,115,127,1)] dark:text-[rgba(156,163,175,1)] whitespace-nowrap">
+              Custom
+            </span>
+            <input
+              ref={customInputRef}
+              type="color"
+              value={value}
+              onChange={(e) => onChange(e.target.value)}
+              onClick={() => {
+                if (nativePickerOpenRef.current) {
+                  /* Second click — close the native dialog */
+                  customInputRef.current?.blur();
+                  nativePickerOpenRef.current = false;
+                } else {
+                  /* First click — browser will open the native dialog */
+                  nativePickerOpenRef.current = true;
+                }
+              }}
+              onBlur={() => { nativePickerOpenRef.current = false; }}
+              className="h-[20px] w-[36px] rounded-[4px] cursor-pointer border border-[rgba(210,214,219,1)] p-[1px]"
+              aria-label="Custom color"
+            />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/* ─────────────────────────────────────────────────────────────────
+ * SizePicker
+ *
+ * A styled dropdown for brush / font size.
+ * ─────────────────────────────────────────────────────────────── */
+
+interface SizePickerProps {
+  value: number;
+  onChange: (s: number) => void;
+  options: number[];
+  unit?: string;
+}
+
+function SizePicker({ value, onChange, options, unit = 'px' }: SizePickerProps) {
+  const [open, setOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const handleOutside = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleOutside);
+    return () => document.removeEventListener('mousedown', handleOutside);
+  }, [open]);
+
+  return (
+    <div ref={containerRef} className="relative">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        aria-label="Brush size"
+        className={cn(OPTIONS_SIZE_PILL, 'cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[rgba(27,131,84,0.7)]')}
+      >
+        <span className={OPTIONS_LABEL}>{value}{unit}</span>
+        <span className="size-icon-sm text-[rgba(108,115,127,1)] dark:text-[rgba(156,163,175,1)]">
+          <ChevronDownIcon />
+        </span>
+      </button>
+
+      {open && (
+        <ul
+          role="listbox"
+          aria-label="Brush size options"
+          className={cn(
+            'absolute z-50 top-[calc(100%+4px)] start-0',
+            'bg-white dark:bg-[rgba(17,25,39,1)]',
+            'border border-[rgba(210,214,219,1)] dark:border-[rgba(55,65,81,1)]',
+            'rounded-[8px] shadow-[0px_4px_16px_rgba(0,0,0,0.12)]',
+            'py-spacing-xs min-w-[80px]',
+            'list-none',
+          )}
+        >
+          {options.map((s) => (
+            <li key={s} role="option" aria-selected={value === s}>
+              <button
+                type="button"
+                onClick={() => { onChange(s); setOpen(false); }}
+                className={cn(
+                  'w-full text-start px-spacing-md py-spacing-xs text-text-xs font-normal',
+                  'hover:bg-[rgba(243,244,246,1)] dark:hover:bg-[rgba(55,65,81,1)]',
+                  value === s
+                    ? 'text-[rgba(27,131,84,1)] font-medium'
+                    : 'text-[rgba(22,22,22,1)] dark:text-[rgba(229,231,235,1)]',
+                )}
+              >
+                {s}{unit}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/* ─────────────────────────────────────────────────────────────────
+ * TypefacePicker
+ * ─────────────────────────────────────────────────────────────── */
+
+const TYPEFACES = [
+  'IBM Plex Sans Arabic',
+  'Georgia',
+  'Times New Roman',
+  'Courier New',
+];
+
+interface TypefacePickerProps {
+  value: string;
+  onChange: (t: string) => void;
+}
+
+function TypefacePicker({ value, onChange }: TypefacePickerProps) {
+  const [open, setOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const handleOutside = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handleOutside);
+    return () => document.removeEventListener('mousedown', handleOutside);
+  }, [open]);
+
+  const shortName = value.split(' ')[0]; // truncate for display
+
+  return (
+    <div ref={containerRef} className="relative flex-1 min-w-0">
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        aria-label="Select typeface"
+        className="flex items-center gap-spacing-xxs cursor-pointer focus-visible:outline-none"
+      >
+        <span className={OPTIONS_TYPEFACE_LABEL}>{shortName}</span>
+        <span className="size-icon-sm text-[rgba(108,115,127,1)] dark:text-[rgba(156,163,175,1)] shrink-0">
+          <ChevronDownIcon />
+        </span>
+      </button>
+
+      {open && (
+        <ul
+          role="listbox"
+          aria-label="Typeface options"
+          className={cn(
+            'absolute z-50 top-[calc(100%+4px)] start-0',
+            'bg-white dark:bg-[rgba(17,25,39,1)]',
+            'border border-[rgba(210,214,219,1)] dark:border-[rgba(55,65,81,1)]',
+            'rounded-[8px] shadow-[0px_4px_16px_rgba(0,0,0,0.12)]',
+            'py-spacing-xs min-w-[180px]',
+            'list-none',
+          )}
+        >
+          {TYPEFACES.map((f) => (
+            <li key={f} role="option" aria-selected={value === f}>
+              <button
+                type="button"
+                onClick={() => { onChange(f); setOpen(false); }}
+                className={cn(
+                  'w-full text-start px-spacing-md py-spacing-xs text-text-xs font-normal',
+                  'hover:bg-[rgba(243,244,246,1)] dark:hover:bg-[rgba(55,65,81,1)]',
+                  value === f
+                    ? 'text-[rgba(27,131,84,1)] font-medium'
+                    : 'text-[rgba(22,22,22,1)] dark:text-[rgba(229,231,235,1)]',
+                )}
+                style={{ fontFamily: f }}
+              >
+                {f}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/* ─────────────────────────────────────────────────────────────────
+ * DrawOptions toolbar
+ * ─────────────────────────────────────────────────────────────── */
+
+const BRUSH_SIZES = [1, 2, 3, 5, 8];
+
+interface DrawOptionsProps {
+  inkColor: string;
+  onInkColorChange: (c: string) => void;
+  brushSize: number;
+  onBrushSizeChange: (s: number) => void;
+  bgColor: string;
+  onBgColorChange: (c: string) => void;
+}
+
+function DrawOptions({
+  inkColor, onInkColorChange,
+  brushSize, onBrushSizeChange,
+  bgColor, onBgColorChange,
+}: DrawOptionsProps) {
+  return (
+    <div className={cn(OPTIONS_ROW, 'justify-end')}>
+      {/* Color */}
+      <div className="flex items-center gap-spacing-xxs">
+        <span className={OPTIONS_LABEL}>Color</span>
+        <ColorPickerPopover value={inkColor} onChange={onInkColorChange} ariaLabel="Ink color picker" />
+      </div>
+
+      {/* Size */}
+      <div className="flex items-center gap-spacing-xxs">
+        <span className={OPTIONS_LABEL}>Size</span>
+        <SizePicker value={brushSize} onChange={onBrushSizeChange} options={BRUSH_SIZES} unit="px" />
+      </div>
+
+      {/* Background — align="end" keeps the panel within the card boundary */}
+      <div className="flex items-center gap-spacing-xxs">
+        <span className={OPTIONS_LABEL}>Background</span>
+        <ColorPickerPopover value={bgColor} onChange={onBgColorChange} align="end" ariaLabel="Background color picker" />
+      </div>
+    </div>
+  );
+}
+
+/* ─────────────────────────────────────────────────────────────────
+ * TextOptions toolbar
+ * ─────────────────────────────────────────────────────────────── */
+
+const FONT_SIZES = [14, 18, 24, 32, 40];
+
+interface TextOptionsProps {
+  typeface: string;
+  onTypefaceChange: (t: string) => void;
+  inkColor: string;
+  onInkColorChange: (c: string) => void;
+  fontSize: number;
+  onFontSizeChange: (s: number) => void;
+  bgColor: string;
+  onBgColorChange: (c: string) => void;
+}
+
+function TextOptions({
+  typeface, onTypefaceChange,
+  inkColor, onInkColorChange,
+  fontSize, onFontSizeChange,
+  bgColor, onBgColorChange,
+}: TextOptionsProps) {
+  return (
+    <div className={OPTIONS_ROW}>
+      {/* Select typeface — fills remaining space on inline-start side */}
+      <TypefacePicker value={typeface} onChange={onTypefaceChange} />
+
+      {/* Color */}
+      <div className="flex items-center gap-spacing-xxs">
+        <span className={OPTIONS_LABEL}>Color</span>
+        <ColorPickerPopover value={inkColor} onChange={onInkColorChange} ariaLabel="Ink color picker" />
+      </div>
+
+      {/* Size */}
+      <div className="flex items-center gap-spacing-xxs">
+        <span className={OPTIONS_LABEL}>Size</span>
+        <SizePicker value={fontSize} onChange={onFontSizeChange} options={FONT_SIZES} unit="px" />
+      </div>
+
+      {/* Background — align="end" keeps the panel within the card boundary */}
+      <div className="flex items-center gap-spacing-xxs">
+        <span className={OPTIONS_LABEL}>Background</span>
+        <ColorPickerPopover value={bgColor} onChange={onBgColorChange} align="end" ariaLabel="Background color picker" />
+      </div>
+    </div>
+  );
+}
+
+/* ─────────────────────────────────────────────────────────────────
+ * Tab items (stable reference — never recreated)
+ * ─────────────────────────────────────────────────────────────── */
+
+const TAB_ITEMS = [
+  { value: 'draw',   label: 'Draw'   },
+  { value: 'text',   label: 'Type'   },
+  { value: 'upload', label: 'Upload' },
+];
+
+/* ─────────────────────────────────────────────────────────────────
+ * Signature — main component
+ * ─────────────────────────────────────────────────────────────── */
+
+export const Signature = forwardRef<HTMLDivElement, SignatureProps>(
+  function Signature(
+    {
+      type: controlledType,
+      defaultType = 'draw',
+      onTypeChange,
+      helperText = 'By signing this document, I certify that I have reviewed and accepted the agreement.',
+      showHelperText = true,
+      showOptions = true,
+      showTabs = true,
+      cancelLabel = 'Cancel',
+      acceptLabel = 'Accept and Sign',
+      onCancel,
+      onAccept,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    /* ── Active tab (controlled / uncontrolled) ──────────────── */
+    const isControlled = controlledType !== undefined;
+    const [internalType, setInternalType] = useState<SignatureType>(defaultType);
+    const activeType = isControlled ? controlledType! : internalType;
+
+    const handleTypeChange = useCallback(
+      (next: string) => {
+        const t = next as SignatureType;
+        if (!isControlled) setInternalType(t);
+        onTypeChange?.(t);
+      },
+      [isControlled, onTypeChange],
+    );
+
+    /* ── Draw options ────────────────────────────────────────── */
+    const [inkColor, setInkColor]       = useState('#000000');
+    const [brushSize, setBrushSize]     = useState(2);
+    const [drawBgColor, setDrawBgColor] = useState('#f3f4f6');
+
+    /* ── Text options ────────────────────────────────────────── */
+    const [typeface, setTypeface]             = useState('IBM Plex Sans Arabic');
+    const [fontSize, setFontSize]             = useState(24);
+    const [textInkColor, setTextInkColor]     = useState('#000000');
+    const [textBgColor, setTextBgColor]       = useState('#f3f4f6');
+    const [typedSignature, setTypedSignature] = useState('');
+
+    /* ── Draw canvas ─────────────────────────────────────────── */
+    const canvasRef    = useRef<HTMLCanvasElement>(null);
+    const isDrawingRef = useRef(false);
+
+    /* Keep the canvas pixel buffer in sync with its CSS size.
+     *
+     * Why ResizeObserver instead of a one-shot useEffect:
+     * A <canvas> has TWO separate size concepts:
+     *   1. CSS size  — controlled by Tailwind's `w-full h-full`; purely visual.
+     *   2. Pixel buffer — controlled by the `width` / `height` DOM attributes;
+     *      this is the actual coordinate system used when drawing.
+     *
+     * If the buffer is smaller than the CSS box (e.g. the default 300×150 px,
+     * or whatever offsetWidth returned before the flex layout settled), all
+     * drawing commands beyond that size are silently clipped — the canvas
+     * LOOKS full-size but you can only draw in a fraction of it.
+     *
+     * ResizeObserver fires AFTER layout is complete, so the measurements are
+     * always correct, even on the first paint and after any window resize.
+     *
+     * Note: setting canvas.width / canvas.height always clears the buffer —
+     * that is unavoidable HTML5 canvas behaviour. We only do it when the
+     * measured size actually changed so normal interaction never triggers it. */
+    useEffect(() => {
+      if (activeType !== 'draw') return;
+      const canvas = canvasRef.current;
+      if (!canvas) return;
+
+      const syncSize = () => {
+        const w = Math.round(canvas.offsetWidth);
+        const h = Math.round(canvas.offsetHeight);
+        /* Skip if nothing changed or container not yet laid out */
+        if (w === 0 || h === 0) return;
+        if (canvas.width === w && canvas.height === h) return;
+        canvas.width  = w;
+        canvas.height = h;
+      };
+
+      syncSize(); // best-effort immediate sync (may already be correct)
+
+      const ro = new ResizeObserver(syncSize);
+      ro.observe(canvas);
+      return () => ro.disconnect();
+    }, [activeType]);
+
+    /* Non-passive touch listeners for the draw canvas.
+     * React 17+ registers onTouchStart/onTouchMove as passive, so calling
+     * preventDefault() inside them triggers a browser warning. We attach
+     * them directly as non-passive native listeners instead. */
+    useEffect(() => {
+      if (activeType !== 'draw') return;
+      const canvas = canvasRef.current;
+      if (!canvas) return;
+
+      const onTouchStart = (e: TouchEvent) => {
+        e.preventDefault();
+        const t = e.touches[0];
+        if (!t) return;
+        const r = canvas.getBoundingClientRect();
+        const ctx = canvas.getContext('2d');
+        if (!ctx) return;
+        isDrawingRef.current = true;
+        ctx.beginPath();
+        ctx.moveTo(t.clientX - r.left, t.clientY - r.top);
+      };
+
+      const onTouchMove = (e: TouchEvent) => {
+        e.preventDefault();
+        if (!isDrawingRef.current) return;
+        const t = e.touches[0];
+        if (!t) return;
+        const r = canvas.getBoundingClientRect();
+        const ctx = canvas.getContext('2d');
+        if (!ctx) return;
+        ctx.lineTo(t.clientX - r.left, t.clientY - r.top);
+        ctx.strokeStyle = inkColor;
+        ctx.lineWidth   = brushSize;
+        ctx.lineCap     = 'round';
+        ctx.lineJoin    = 'round';
+        ctx.stroke();
+      };
+
+      const onTouchEnd = () => { isDrawingRef.current = false; };
+
+      canvas.addEventListener('touchstart', onTouchStart, { passive: false });
+      canvas.addEventListener('touchmove',  onTouchMove,  { passive: false });
+      canvas.addEventListener('touchend',   onTouchEnd);
+
+      return () => {
+        canvas.removeEventListener('touchstart', onTouchStart);
+        canvas.removeEventListener('touchmove',  onTouchMove);
+        canvas.removeEventListener('touchend',   onTouchEnd);
+      };
+    }, [activeType, inkColor, brushSize]);
+
+    /* Canvas helpers */
+    const getPos = (e: React.MouseEvent<HTMLCanvasElement>) => {
+      const r = e.currentTarget.getBoundingClientRect();
+      return { x: e.clientX - r.left, y: e.clientY - r.top };
+    };
+    const startStroke = (x: number, y: number) => {
+      const ctx = canvasRef.current?.getContext('2d');
+      if (!ctx) return;
+      isDrawingRef.current = true;
+      ctx.beginPath();
+      ctx.moveTo(x, y);
+    };
+    const continueStroke = (x: number, y: number) => {
+      if (!isDrawingRef.current) return;
+      const ctx = canvasRef.current?.getContext('2d');
+      if (!ctx) return;
+      ctx.lineTo(x, y);
+      ctx.strokeStyle = inkColor;
+      ctx.lineWidth   = brushSize;
+      ctx.lineCap     = 'round';
+      ctx.lineJoin    = 'round';
+      ctx.stroke();
+    };
+    const endStroke = () => { isDrawingRef.current = false; };
+
+    /* ── File upload ─────────────────────────────────────────── */
+    const fileInputRef   = useRef<HTMLInputElement>(null);
+    const dragDepth      = useRef(0);
+    const [uploadedFile, setUploadedFile] = useState<File | undefined>();
+    const [dragActive,   setDragActive]   = useState(false);
+
+    const handleBrowse = useCallback(() => fileInputRef.current?.click(), []);
+
+    const handleFileChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
+      const file = e.target.files?.[0];
+      if (file) setUploadedFile(file);
+    }, []);
+
+    const handleDragEnter = useCallback((e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragDepth.current += 1;
+      if (e.dataTransfer.types.includes('Files')) setDragActive(true);
+    }, []);
+
+    const handleDragLeave = useCallback((e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragDepth.current -= 1;
+      if (dragDepth.current <= 0) { dragDepth.current = 0; setDragActive(false); }
+    }, []);
+
+    const handleDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      e.stopPropagation();
+    }, []);
+
+    const handleDrop = useCallback((e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      e.stopPropagation();
+      dragDepth.current = 0;
+      setDragActive(false);
+      const file = e.dataTransfer.files?.[0];
+      if (file) setUploadedFile(file);
+    }, []);
+
+    /* ── Reset (Cancel behaviour) ────────────────────────────── */
+    const resetSignature = useCallback(() => {
+      if (activeType === 'draw') {
+        const canvas = canvasRef.current;
+        if (!canvas) return;
+        const ctx = canvas.getContext('2d');
+        if (ctx) ctx.clearRect(0, 0, canvas.width, canvas.height);
+      } else if (activeType === 'text') {
+        setTypedSignature('');
+      } else {
+        setUploadedFile(undefined);
+        if (fileInputRef.current) fileInputRef.current.value = '';
+      }
+    }, [activeType]);
+
+    const handleCancel = useCallback(() => {
+      resetSignature();
+      onCancel?.();
+    }, [resetSignature, onCancel]);
+
+    /* ── Accept ──────────────────────────────────────────────── */
+    const handleAccept = useCallback(() => {
+      let data: string | File | undefined;
+      if (activeType === 'draw')   data = canvasRef.current?.toDataURL('image/png');
+      else if (activeType === 'text') data = typedSignature || undefined;
+      else                            data = uploadedFile;
+      onAccept?.(data);
+    }, [activeType, typedSignature, uploadedFile, onAccept]);
+
+    /* ── Shared tab bar ──────────────────────────────────────── */
+    function renderTabBar(size: 'sm' | 'md' | 'lg') {
+      return (
+        <HorizontalTabs
+          items={TAB_ITEMS}
+          type="underline"
+          size={size}
+          value={activeType}
+          onValueChange={handleTypeChange}
+        />
+      );
+    }
+
+    /* ── Render ──────────────────────────────────────────────── */
+    return (
+      <div
+        ref={ref}
+        data-slot="signature"
+        className={cn(CARD_ROOT, className)}
+        {...rest}
+      >
+        {/* Tabs row */}
+        {showTabs && (
+          <div className={TAB_SECTION}>
+            <div className="block md:hidden">{renderTabBar('sm')}</div>
+            <div className="hidden md:block xl:hidden">{renderTabBar('md')}</div>
+            <div className="hidden xl:block">{renderTabBar('lg')}</div>
+            {/* Full-width grey underline beneath all tabs */}
+            <div className={TAB_DIVIDER} aria-hidden="true" />
+          </div>
+        )}
+
+        {/* ── Draw mode ──────────────────────────────────────── */}
+        {activeType === 'draw' && (
+          <>
+            {showOptions && (
+              <DrawOptions
+                inkColor={inkColor}       onInkColorChange={setInkColor}
+                brushSize={brushSize}     onBrushSizeChange={setBrushSize}
+                bgColor={drawBgColor}     onBgColorChange={setDrawBgColor}
+              />
+            )}
+            <div
+              className={DRAW_CANVAS_WRAPPER}
+              style={{ backgroundColor: drawBgColor }}
+              data-slot="draw-canvas-wrapper"
+            >
+              <canvas
+                ref={canvasRef}
+                className="block w-full h-full cursor-crosshair touch-none"
+                aria-label="Signature drawing area"
+                onMouseDown={(e) => { const p = getPos(e); startStroke(p.x, p.y); }}
+                onMouseMove={(e) => { const p = getPos(e); continueStroke(p.x, p.y); }}
+                onMouseUp={endStroke}
+                onMouseLeave={endStroke}
+              />
+            </div>
+          </>
+        )}
+
+        {/* ── Text mode ──────────────────────────────────────── */}
+        {activeType === 'text' && (
+          <>
+            {showOptions && (
+              <TextOptions
+                typeface={typeface}         onTypefaceChange={setTypeface}
+                inkColor={textInkColor}     onInkColorChange={setTextInkColor}
+                fontSize={fontSize}         onFontSizeChange={setFontSize}
+                bgColor={textBgColor}       onBgColorChange={setTextBgColor}
+              />
+            )}
+            <div
+              className={TEXT_CANVAS_WRAPPER}
+              style={{ backgroundColor: textBgColor }}
+              data-slot="text-canvas-wrapper"
+            >
+              <input
+                type="text"
+                value={typedSignature}
+                onChange={(e) => setTypedSignature(e.target.value)}
+                placeholder="Type your signature"
+                className={TEXT_INPUT}
+                style={{ fontFamily: typeface, fontSize: `${fontSize}px`, color: textInkColor }}
+                aria-label="Type your signature"
+              />
+              <div className={TEXT_BASELINE} data-slot="signature-baseline" />
+            </div>
+          </>
+        )}
+
+        {/* ── Upload mode ────────────────────────────────────── */}
+        {activeType === 'upload' && (
+          <>
+            {/* The flex-1 wrapper grows to fill all remaining vertical space in
+                the Signature card (same pattern as DRAW_CANVAS_WRAPPER). The
+                drag handlers live on the wrapper so the entire area is a drop
+                target. FileUploadBase is h-full so it fills the wrapper;
+                its built-in justify-center keeps the content vertically centred.
+                Neither FileUploadBase nor FileUploader renders <input type="file">
+                internally — the hidden input below handles file selection. */}
+            <div
+              className="flex-1 min-h-[180px] w-full"
+              data-slot="upload-zone"
+              onDragEnter={handleDragEnter}
+              onDragLeave={handleDragLeave}
+              onDragOver={handleDragOver}
+              onDrop={handleDrop}
+            >
+              <FileUploadBase
+                className="h-full w-full"
+                active={dragActive}
+                label={uploadedFile
+                  ? uploadedFile.name
+                  : 'Choose a file or drag & drop it here.'}
+                helperText="JPEG, PNG, PDF, and GIF formats, up to 2MB"
+                showHelperText={!uploadedFile}
+                browseLabel="Browse file"
+                onBrowse={handleBrowse}
+              />
+            </div>
+            <input
+              ref={fileInputRef}
+              type="file"
+              className="sr-only"
+              accept=".jpg,.jpeg,.png,.pdf,.gif"
+              onChange={handleFileChange}
+              tabIndex={-1}
+              aria-hidden="true"
+            />
+          </>
+        )}
+
+        {/* Helper text */}
+        {showHelperText && helperText && (
+          <p className={HELPER_TEXT} data-slot="helper-text">
+            {helperText}
+          </p>
+        )}
+
+        {/* Actions row
+          * DOM order: neutral first, primary second.
+          * LTR: neutral=LEFT, primary=RIGHT.
+          * RTL (direction:rtl from ancestor): visual order reverses →
+          *   neutral=RIGHT, primary=LEFT — matches Figma RTL frames. */}
+        <div className={ACTIONS_ROW} data-slot="actions">
+          <Button
+            variant="secondary-solid"
+            size="md"
+            type="button"
+            onClick={handleCancel}
+            data-slot="cancel-button"
+          >
+            {cancelLabel}
+          </Button>
+
+          <Button
+            variant="primary"
+            size="md"
+            type="button"
+            onClick={handleAccept}
+            data-slot="accept-button"
+          >
+            {acceptLabel}
+          </Button>
+        </div>
+      </div>
+    );
+  },
+);