@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/camera/DocumentCapture.tsx

@@ -0,0 +1,505 @@
+/**
+ * @fileoverview Full-screen document camera with an ID-1 frame guide.
+ *
+ * Uses `react-native-vision-camera` v4 in `photo` mode. Tapping the shutter
+ * triggers `takePhoto()` with `qualityPrioritization: 'balanced'`; the file
+ * URI is returned to the caller via `onCaptured`.
+ *
+ * Visual: dark scrim with a transparent rectangular cutout (ID-1 16:10 ratio
+ * by default). The cutout is the visible-only guide — we do NOT crop the
+ * image client-side because the server's OCR pipeline rejects soft crops.
+ * The user is asked to fill the frame; the backend handles edge detection.
+ *
+ * No edge detection / OpenCV port (intentional MVP scope per the brief).
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  ActivityIndicator,
+  Pressable,
+  StyleSheet,
+  Text,
+  useWindowDimensions,
+  View,
+} from 'react-native';
+import Svg, { Defs, Mask, Rect } from 'react-native-svg';
+import {
+  Camera,
+  useCameraDevice,
+  useCameraPermission,
+  type PhotoFile,
+} from 'react-native-vision-camera';
+import type { DocumentOrientation, DocumentSide } from '../types';
+import { useTheme, withAlpha } from '../ui/theme';
+import { Button } from '../ui/primitives/Button';
+
+export interface DocumentCaptureProps {
+  side: DocumentSide;
+  orientation: DocumentOrientation;
+  /** Localized instruction shown above the cutout. */
+  instructions: string;
+  /** Localized "Take photo" label for the shutter button. */
+  captureLabel: string;
+  /** Localized error string when permission is denied. */
+  permissionDeniedLabel: string;
+  /** Localized "Try again" label. */
+  retryLabel: string;
+  /** Localized "Cancel" / back label. */
+  cancelLabel: string;
+  onCaptured: (photo: PhotoFile, side: DocumentSide) => void;
+  onCancel: () => void;
+}
+
+export function DocumentCapture({
+  side,
+  orientation,
+  instructions,
+  captureLabel,
+  permissionDeniedLabel,
+  retryLabel,
+  cancelLabel,
+  onCaptured,
+  onCancel,
+}: DocumentCaptureProps) {
+  const theme = useTheme();
+  const cameraRef = useRef<Camera>(null);
+  // Cross-platform back-camera selection.
+  //
+  // iOS (especially 15 Pro / Pro Max with multi-lens systems): asking for
+  // just 'back' returns the *wide-angle* device, whose ~20 cm minimum focus
+  // distance produces blurry frames when the user holds the ID closer.
+  // Passing the `physicalDevices` array makes vision-camera pick the
+  // *virtual multi-camera* device, which lets iOS auto-switch to the
+  // ultra-wide lens for macro / close-range subjects. Order = preference.
+  //
+  // Android: vision-camera's Android implementation ignores the
+  // `physicalDevices` filter (Android cameras are addressed by ID, not by
+  // physical-lens type) and returns the same default back camera it would
+  // return without the filter. So the filter is a no-op there but doesn't
+  // harm anything. Continuous AF is the default focus mode on both
+  // platforms, so cross-platform behaviour stays consistent.
+  const device = useCameraDevice('back', {
+    physicalDevices: [
+      'ultra-wide-angle-camera',
+      'wide-angle-camera',
+      'telephoto-camera',
+    ],
+  });
+  const { hasPermission, requestPermission } = useCameraPermission();
+  const [requestedOnce, setRequestedOnce] = useState(false);
+  const [shooting, setShooting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // After ~4s without a device, surface a clear error instead of an
+  // infinite spinner. The most common cause is running the SDK in the
+  // iOS Simulator, which has no real camera.
+  const [deviceTimeout, setDeviceTimeout] = useState(false);
+  const [focusPoint, setFocusPoint] = useState<
+    { x: number; y: number; key: number } | null
+  >(null);
+
+  useEffect(() => {
+    if (!hasPermission && !requestedOnce) {
+      setRequestedOnce(true);
+      void requestPermission();
+    }
+  }, [hasPermission, requestedOnce, requestPermission]);
+
+  useEffect(() => {
+    if (device || !hasPermission) {
+      setDeviceTimeout(false);
+      return;
+    }
+    const t = setTimeout(() => setDeviceTimeout(true), 4000);
+    return () => clearTimeout(t);
+  }, [device, hasPermission]);
+
+  // NOTE: we intentionally do NOT call `cameraRef.current.focus()` on mount
+  // or before each shutter. iOS's continuous auto-focus runs by default and
+  // is what makes the native Camera app feel sharp at any distance. Calling
+  // `focus()` switches the device into single-shot/locked mode and DOES NOT
+  // restore continuous AF afterwards (vision-camera v4 has no "resume AF"
+  // API). The previous "autofocus on mount" + "autofocus before shutter"
+  // calls were the cause of blurry captures on iPhone 15 Pro Max: they
+  // pinned focus to the centre even after the user moved the phone, and
+  // never re-engaged continuous AF.
+  //
+  // Tap-to-focus is the one user-initiated override — when the user taps,
+  // they're explicitly asking us to lock focus on that point.
+  const supportsFocus = Boolean(device?.supportsFocus);
+
+  const handleTapToFocus = useCallback(
+    (event: { nativeEvent: { locationX: number; locationY: number } }) => {
+      if (!supportsFocus || !cameraRef.current) return;
+      const { locationX, locationY } = event.nativeEvent;
+      cameraRef.current.focus({ x: locationX, y: locationY }).catch(() => {
+        // Ignore — focus rejection is non-fatal.
+      });
+      setFocusPoint({ x: locationX, y: locationY, key: Date.now() });
+    },
+    [supportsFocus],
+  );
+
+  // Auto-hide the focus indicator after a short period.
+  useEffect(() => {
+    if (!focusPoint) return;
+    const t = setTimeout(() => setFocusPoint(null), 700);
+    return () => clearTimeout(t);
+  }, [focusPoint]);
+
+  const handleShutter = useCallback(async () => {
+    if (!cameraRef.current || shooting) return;
+    setShooting(true);
+    setError(null);
+    try {
+      const photo = await cameraRef.current.takePhoto({
+        flash: 'off',
+        enableShutterSound: false,
+      });
+      onCaptured(photo, side);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setShooting(false);
+    }
+  }, [onCaptured, side, shooting]);
+
+  if (!hasPermission) {
+    return (
+      <View style={[styles.permission, { backgroundColor: theme.backgroundColor }]}>
+        <Text style={[styles.permissionText, { color: theme.textColor }]}>
+          {permissionDeniedLabel}
+        </Text>
+        <View style={styles.row}>
+          <Button
+            variant="ghost"
+            label={cancelLabel}
+            onPress={onCancel}
+            fullWidth={false}
+            style={styles.actionBtn}
+          />
+          <Button
+            label={retryLabel}
+            onPress={() => {
+              void requestPermission();
+            }}
+            fullWidth={false}
+            style={styles.actionBtn}
+          />
+        </View>
+      </View>
+    );
+  }
+
+  if (!device) {
+    if (deviceTimeout) {
+      return (
+        <View style={[styles.permission, { backgroundColor: theme.backgroundColor }]}>
+          <Text style={[styles.permissionText, { color: theme.textColor }]}>
+            No camera detected. The iOS Simulator does not provide a real
+            camera — please run on a physical device to capture documents.
+          </Text>
+          <View style={styles.row}>
+            <Button
+              variant="ghost"
+              label={cancelLabel}
+              onPress={onCancel}
+              fullWidth={false}
+              style={styles.actionBtn}
+            />
+          </View>
+        </View>
+      );
+    }
+    return (
+      <View style={[styles.permission, { backgroundColor: theme.backgroundColor }]}>
+        <ActivityIndicator color={theme.primaryColor} />
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.root}>
+      <Camera
+        ref={cameraRef}
+        style={StyleSheet.absoluteFill}
+        device={device}
+        photo
+        photoQualityBalance="quality"
+        enableZoomGesture={false}
+        isActive
+      />
+      {/* Invisible pressable layer over the camera preview for tap-to-focus.
+          Sits below the mask + chrome so the user can tap anywhere except
+          the bottom shutter / top close button. */}
+      <Pressable
+        style={StyleSheet.absoluteFill}
+        onPress={handleTapToFocus}
+        accessibilityLabel="Tap to focus"
+      />
+      <DocumentMaskOverlay orientation={orientation} />
+      {focusPoint ? (
+        <View
+          pointerEvents="none"
+          style={[
+            styles.focusRing,
+            {
+              left: focusPoint.x - FOCUS_RING_SIZE / 2,
+              top: focusPoint.y - FOCUS_RING_SIZE / 2,
+            },
+          ]}
+        />
+      ) : null}
+      <View style={styles.topBar}>
+        <Pressable onPress={onCancel} style={styles.iconBtn} accessibilityLabel={cancelLabel}>
+          <Text style={styles.iconBtnText}>✕</Text>
+        </Pressable>
+      </View>
+      <View style={styles.instructions} pointerEvents="none">
+        <Text style={styles.instructionsText}>{instructions}</Text>
+      </View>
+      <View style={styles.bottomBar}>
+        {error ? <Text style={styles.errorText}>{error}</Text> : null}
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={captureLabel}
+          accessibilityState={{ disabled: shooting }}
+          disabled={shooting}
+          onPress={handleShutter}
+          style={[
+            styles.shutter,
+            { borderColor: '#FFFFFF', backgroundColor: withAlpha('#FFFFFF', 0.18) },
+            shooting && styles.shutterDisabled,
+          ]}
+        >
+          <View
+            style={[styles.shutterCore, { backgroundColor: '#FFFFFF' }]}
+          />
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+const FOCUS_RING_SIZE = 64;
+
+interface MaskProps {
+  orientation: DocumentOrientation;
+}
+
+const CUTOUT_WIDTH_RATIO = 0.85; // 85% of screen width
+const CUTOUT_MAX_HEIGHT_RATIO = 0.62; // never taller than 62% of screen height
+const CORNER_LENGTH = 28;
+const CORNER_THICKNESS = 3;
+/**
+ * Radius of the rounded cutout AND of the corner brackets. The SVG mask uses
+ * it for the inner rounded rect; each bracket's outward corner radius is the
+ * same value so the brackets sit flush on the curve.
+ */
+const CUTOUT_RADIUS = 16;
+const DIM_COLOR = 'rgba(0,0,0,0.55)';
+
+function DocumentMaskOverlay({ orientation }: MaskProps) {
+  const { width: screenW, height: screenH } = useWindowDimensions();
+  const aspectRatio = orientation === 'portrait' ? 0.625 : 1.586;
+
+  // Compute the cutout proportionally. Width is the primary dimension; if
+  // the resulting height would overflow the screen budget (mostly portrait
+  // ID-1 = 0.625 aspect on tall phones), shrink it back to fit.
+  let cutoutW = screenW * CUTOUT_WIDTH_RATIO;
+  let cutoutH = cutoutW / aspectRatio;
+  const maxH = screenH * CUTOUT_MAX_HEIGHT_RATIO;
+  if (cutoutH > maxH) {
+    cutoutH = maxH;
+    cutoutW = cutoutH * aspectRatio;
+  }
+  const left = (screenW - cutoutW) / 2;
+  const top = (screenH - cutoutH) / 2;
+  const R = CUTOUT_RADIUS;
+
+  // SVG mask: opaque outer rect minus a rounded inner rect. The mask paints
+  // white where dim should render and black where the cutout is transparent;
+  // the rounded inner Rect (rx/ry = R) produces exact concave curves at each
+  // corner — no quarter-circle fillers, no curve inversion.
+  return (
+    <View pointerEvents="none" style={StyleSheet.absoluteFill}>
+      <Svg width={screenW} height={screenH} style={StyleSheet.absoluteFill}>
+        <Defs>
+          <Mask id="documentCutout">
+            <Rect x={0} y={0} width={screenW} height={screenH} fill="white" />
+            <Rect
+              x={left}
+              y={top}
+              width={cutoutW}
+              height={cutoutH}
+              rx={R}
+              ry={R}
+              fill="black"
+            />
+          </Mask>
+        </Defs>
+        <Rect
+          x={0}
+          y={0}
+          width={screenW}
+          height={screenH}
+          fill={DIM_COLOR}
+          mask="url(#documentCutout)"
+        />
+      </Svg>
+
+      {/* Corner brackets, anchored to the cutout bounding box. Each bracket's
+          outward corner uses the same radius as the cutout so it sits flush
+          on the curve. */}
+      <View
+        style={{
+          position: 'absolute',
+          left,
+          top,
+          width: cutoutW,
+          height: cutoutH,
+        }}
+      >
+        <View style={[styles.corner, styles.cornerTL, { borderTopLeftRadius: R }]} />
+        <View style={[styles.corner, styles.cornerTR, { borderTopRightRadius: R }]} />
+        <View style={[styles.corner, styles.cornerBL, { borderBottomLeftRadius: R }]} />
+        <View style={[styles.corner, styles.cornerBR, { borderBottomRightRadius: R }]} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+    backgroundColor: '#000',
+  },
+  permission: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 32,
+    gap: 16,
+  },
+  permissionText: {
+    textAlign: 'center',
+    fontSize: 15,
+    lineHeight: 22,
+  },
+  row: {
+    flexDirection: 'row',
+    gap: 12,
+    width: '100%',
+    maxWidth: 380,
+  },
+  actionBtn: {
+    flex: 1,
+  },
+  topBar: {
+    position: 'absolute',
+    top: 12,
+    left: 12,
+    right: 12,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'flex-end',
+  },
+  iconBtn: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    backgroundColor: 'rgba(0,0,0,0.5)',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  iconBtnText: {
+    color: '#FFFFFF',
+    fontSize: 16,
+    fontWeight: '700',
+  },
+  instructions: {
+    position: 'absolute',
+    top: 60,
+    left: 24,
+    right: 24,
+    alignItems: 'center',
+  },
+  instructionsText: {
+    color: '#FFFFFF',
+    fontSize: 14,
+    textAlign: 'center',
+    backgroundColor: 'rgba(0,0,0,0.5)',
+    paddingHorizontal: 12,
+    paddingVertical: 6,
+    borderRadius: 16,
+    overflow: 'hidden',
+  },
+  bottomBar: {
+    position: 'absolute',
+    bottom: 32,
+    left: 0,
+    right: 0,
+    alignItems: 'center',
+    gap: 12,
+  },
+  errorText: {
+    color: '#FCA5A5',
+    fontSize: 13,
+    textAlign: 'center',
+    paddingHorizontal: 24,
+  },
+  shutter: {
+    width: 76,
+    height: 76,
+    borderRadius: 38,
+    borderWidth: 4,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  shutterDisabled: {
+    opacity: 0.5,
+  },
+  shutterCore: {
+    width: 56,
+    height: 56,
+    borderRadius: 28,
+  },
+  corner: {
+    position: 'absolute',
+    width: CORNER_LENGTH,
+    height: CORNER_LENGTH,
+    borderColor: '#FFFFFF',
+  },
+  cornerTL: {
+    top: 0,
+    left: 0,
+    borderTopWidth: CORNER_THICKNESS,
+    borderLeftWidth: CORNER_THICKNESS,
+  },
+  cornerTR: {
+    top: 0,
+    right: 0,
+    borderTopWidth: CORNER_THICKNESS,
+    borderRightWidth: CORNER_THICKNESS,
+  },
+  cornerBL: {
+    bottom: 0,
+    left: 0,
+    borderBottomWidth: CORNER_THICKNESS,
+    borderLeftWidth: CORNER_THICKNESS,
+  },
+  cornerBR: {
+    bottom: 0,
+    right: 0,
+    borderBottomWidth: CORNER_THICKNESS,
+    borderRightWidth: CORNER_THICKNESS,
+  },
+  focusRing: {
+    position: 'absolute',
+    width: FOCUS_RING_SIZE,
+    height: FOCUS_RING_SIZE,
+    borderRadius: FOCUS_RING_SIZE / 2,
+    borderWidth: 2,
+    borderColor: '#FFFFFF',
+    backgroundColor: 'transparent',
+  },
+});