react-native-image-stitcher 0.1.0

package/src/camera/CameraShutter.tsx

@@ -0,0 +1,292 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CameraShutter — dual-mode shutter button for the SDK's panorama UX.
+ *
+ *     ┌──────────────────────────────────────────────────┐
+ *     │  TAP   → take a single photo (existing flow)      │
+ *     │  HOLD  → start recording video                    │
+ *     │  RELEASE → stop recording → return video file     │
+ *     └──────────────────────────────────────────────────┘
+ *
+ * The button is "pure" UI — it owns gesture detection + visual
+ * feedback (idle / pressing / recording / processing rings) but
+ * NOT the recording / stitching pipeline itself.  Host apps wire
+ * the resulting `onTap` / `onHoldComplete` callbacks to whatever
+ * `useCapture` / `useVideoCapture` instance they've configured.
+ *
+ * Why expose just the button (not the full surface)?
+ *   Different audit screens want different layouts (thumbnails,
+ *   quality badges, mode chips); pinning them all to one
+ *   "PanoramaCaptureSurface" would overfit one customer's UX.  The
+ *   button is the only piece every screen needs identical, so it
+ *   ships in the SDK.  The orchestration helpers ship as
+ *   `<PanoramaCaptureSurface>` next door — host apps that want full
+ *   plug-and-play use that; the rest stitch this button into their
+ *   own layout.
+ *
+ * Gesture detection
+ *   onPressIn fires immediately on touch down; we start a
+ *   ``HOLD_THRESHOLD_MS`` timer.  Two outcomes:
+ *
+ *     - onPressOut fires before the timer → it was a tap.
+ *     - timer fires before onPressOut → transition to recording
+ *       state, fire ``onHoldStart``.  When onPressOut eventually
+ *       fires we call ``onHoldComplete``.
+ *
+ *   We deliberately do NOT use react-native-gesture-handler — the
+ *   Pressable + setTimeout pattern stays in the SDK's existing dep
+ *   surface (RN core only).  Adds zero new peer deps for host apps.
+ */
+
+import React, {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+  forwardRef,
+} from 'react';
+import { Pressable, StyleSheet, View, type ViewStyle } from 'react-native';
+
+
+/// Time the user must hold before tap → hold mode flip.  250 ms is
+/// the iOS native "long press" default; matches user muscle memory
+/// for distinguishing "snap" from "stay".
+const HOLD_THRESHOLD_MS = 250;
+
+
+export interface CameraShutterProps {
+  /** Called when the user taps (press-and-release before the threshold). */
+  onTap: () => void;
+  /** Called when the press crosses the threshold and recording should start. */
+  onHoldStart: () => void;
+  /** Called on release while in the hold state — recording should stop. */
+  onHoldComplete: () => void;
+  /**
+   * Maximum hold duration in milliseconds.  When the timer fires
+   * we auto-fire `onHoldComplete` — same behaviour as the user
+   * releasing the button.  Default 8000 ms; keeps recording
+   * within the stitcher's adjacent-frame-overlap budget
+   * (16 frames × 2 fps = 8 s upper bound).  Pass 0 / undefined
+   * to disable the auto-stop.
+   *
+   * Pair with `<CaptureStatusOverlay countdownMs>` so the user
+   * sees how much hold time is left.
+   */
+  maxHoldMs?: number;
+  /**
+   * Optional state-driven visual override.  When the host has its own
+   * processing indicator (e.g. "Stitching... 70%") set this to true to
+   * paint the button in the disabled-while-processing visual.
+   */
+  isProcessing?: boolean;
+  /** Disable the whole button (e.g. while permissions are loading). */
+  disabled?: boolean;
+  /** Optional style applied to the outer touch target. */
+  style?: ViewStyle;
+}
+
+
+/**
+ * Imperative handle so a parent can force-release (e.g. on unmount
+ * during a long press).  Exposed via forwardRef.
+ */
+export interface CameraShutterHandle {
+  /** Cancel any in-flight hold without calling onHoldComplete. */
+  cancelHold: () => void;
+}
+
+
+export const CameraShutter = forwardRef<CameraShutterHandle, CameraShutterProps>(
+  function CameraShutter(
+    {
+      onTap,
+      onHoldStart,
+      onHoldComplete,
+      maxHoldMs,
+      isProcessing = false,
+      disabled = false,
+      style,
+    },
+    ref,
+  ) {
+    type Phase = 'idle' | 'pressing' | 'holding';
+
+    // Phase machine.  We use a state value for re-render-driven
+    // visuals AND a ref so onPressOut can read the up-to-date phase
+    // without waiting on React's render cycle (otherwise the
+    // tap-vs-hold decision can race the timer).
+    const [phase, setPhase] = useState<Phase>('idle');
+    const phaseRef = useRef<Phase>('idle');
+    const holdTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    // Separate timer for the auto-stop (max hold).  Distinct from
+    // the tap-vs-hold detection timer so each can fire independently.
+    const maxHoldTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    const setPhaseBoth = useCallback((next: Phase) => {
+      phaseRef.current = next;
+      setPhase(next);
+    }, []);
+
+    const clearHoldTimer = useCallback(() => {
+      if (holdTimerRef.current !== null) {
+        clearTimeout(holdTimerRef.current);
+        holdTimerRef.current = null;
+      }
+    }, []);
+
+    const clearMaxHoldTimer = useCallback(() => {
+      if (maxHoldTimerRef.current !== null) {
+        clearTimeout(maxHoldTimerRef.current);
+        maxHoldTimerRef.current = null;
+      }
+    }, []);
+
+    const cancelHold = useCallback(() => {
+      clearHoldTimer();
+      clearMaxHoldTimer();
+      setPhaseBoth('idle');
+    }, [clearHoldTimer, clearMaxHoldTimer, setPhaseBoth]);
+
+    useImperativeHandle(ref, () => ({ cancelHold }), [cancelHold]);
+
+    // Belt-and-suspenders: clean both timers on unmount so a
+    // fast navigation away from the camera doesn't leave one
+    // firing into a stale closure.
+    useEffect(() => () => {
+      clearHoldTimer();
+      clearMaxHoldTimer();
+    }, [clearHoldTimer, clearMaxHoldTimer]);
+
+    const handlePressIn = useCallback(() => {
+      if (disabled || isProcessing) return;
+      setPhaseBoth('pressing');
+      holdTimerRef.current = setTimeout(() => {
+        // Threshold elapsed → enter hold mode + notify.
+        if (phaseRef.current === 'pressing') {
+          setPhaseBoth('holding');
+          onHoldStart();
+          // Schedule the auto-stop if maxHoldMs is set.  Same
+          // outcome as the user releasing the button manually —
+          // fires onHoldComplete + drops back to idle.
+          if (maxHoldMs && maxHoldMs > 0) {
+            maxHoldTimerRef.current = setTimeout(() => {
+              // Auto-stop unconditionally after maxHoldMs.  Earlier
+              // versions gated this on `phase === 'holding'`, which
+              // skipped the fire when iOS' gesture recogniser had
+              // already flipped the phase to 'idle' due to finger
+              // drift from camera motion — leaving the engine running
+              // for hundreds of frames after the user thought they
+              // released.  An extra onHoldComplete call when nothing
+              // is recording is a safe no-op (`!incremental.isRunning`
+              // early-returns).
+              if (phaseRef.current === 'holding') setPhaseBoth('idle');
+              onHoldComplete();
+            }, maxHoldMs);
+          }
+        }
+      }, HOLD_THRESHOLD_MS);
+    }, [disabled, isProcessing, onHoldStart, onHoldComplete, maxHoldMs, setPhaseBoth]);
+
+    const handlePressOut = useCallback(() => {
+      // CRITICAL: release ALWAYS stops the recording, regardless of
+      // disabled/isProcessing state.  The previous version returned
+      // early when `isProcessing === true`, silently swallowing the
+      // release.  When that happened mid-recording, `onHoldComplete`
+      // never fired, the engine kept ingesting AR frames forever
+      // (hundreds of frames stacked up before the user even noticed),
+      // and the final stitch ran on data the user never intended.
+      //
+      // The release event is the user's primary signal that they
+      // want this capture to end.  No internal state is allowed to
+      // block it.  `onHoldComplete` itself is idempotent (it
+      // early-returns when there's nothing running), so an extra
+      // call when the engine is already finishing is a safe no-op.
+      const wasHolding = phaseRef.current === 'holding';
+      clearHoldTimer();
+      clearMaxHoldTimer();
+      setPhaseBoth('idle');
+      if (wasHolding) {
+        onHoldComplete();
+      } else if (!disabled && !isProcessing) {
+        // It was a tap (released before the threshold).  Suppress
+        // the tap when the camera is busy — taps trigger photos and
+        // we don't want to fire-and-forget into a busy pipeline.
+        onTap();
+      }
+    }, [disabled, isProcessing, onTap, onHoldComplete, clearHoldTimer, clearMaxHoldTimer, setPhaseBoth]);
+
+    // Visuals.  Three layered circles so the inner colour can swap
+    // without animating the outer ring (smoother on lower-end phones).
+    const innerStyle =
+      isProcessing
+        ? styles.innerProcessing
+        : phase === 'holding'
+          ? styles.innerRecording
+          : phase === 'pressing'
+            ? styles.innerPressing
+            : styles.innerIdle;
+
+    return (
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={
+          phase === 'holding'
+            ? 'Recording — release to stitch panorama'
+            : 'Tap for photo, hold for panorama'
+        }
+        accessibilityState={{ disabled: disabled || isProcessing }}
+        disabled={disabled || isProcessing}
+        onPressIn={handlePressIn}
+        onPressOut={handlePressOut}
+        style={[styles.outer, disabled && styles.disabled, style]}
+      >
+        <View style={styles.ring} />
+        <View style={[styles.inner, innerStyle]} />
+      </Pressable>
+    );
+  },
+);
+
+
+const styles = StyleSheet.create({
+  outer: {
+    width: 76,
+    height: 76,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  disabled: {
+    opacity: 0.4,
+  },
+  ring: {
+    position: 'absolute',
+    width: 76,
+    height: 76,
+    borderRadius: 38,
+    borderWidth: 4,
+    borderColor: '#ffffff',
+  },
+  inner: {
+    width: 60,
+    height: 60,
+    borderRadius: 30,
+  },
+  innerIdle: {
+    backgroundColor: '#ffffff',
+  },
+  innerPressing: {
+    // Subtle shrink-effect via colour shift; opacity dims confirm
+    // touch landed without committing to a mode yet.
+    backgroundColor: 'rgba(255,255,255,0.7)',
+  },
+  innerRecording: {
+    // Apple-native panorama / shutter recording uses red.
+    backgroundColor: '#FF3B30',
+  },
+  innerProcessing: {
+    // Greyed mid-tone with reduced contrast — clearly "busy, can't
+    // press me" without being alarming.
+    backgroundColor: '#9aa0a6',
+  },
+});

package/src/camera/CameraView.tsx

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CameraView — the SDK's drop-in replacement for the raw
+ * vision-camera ``<Camera />``.
+ *
+ * Why wrap it?
+ *   1. **Default props** — always ``isActive={true}``, ``photo={true}``,
+ *      and honouring the hook's flash state.  Every call-site in the
+ *      mobile app repeated the same tuple; the SDK canonicalises it.
+ *   2. **Branded guidance overlay** — optional ``guidance`` prop renders
+ *      a themed banner over the preview without the host app having to
+ *      know about positioning / contrast.
+ *   3. **Forward ref** — so ``useCapture``'s ref attaches cleanly.
+ *
+ * The component is intentionally thin — anything more elaborate goes
+ * into a separate screen (e.g. AuditCaptureSurface that combines this
+ * view with thumbnails and a shutter button).  Keeping CameraView at
+ * the vision-camera layer means host apps that want a highly-custom
+ * UI can still use it as their building block.
+ */
+
+import React, { forwardRef, useImperativeHandle, useRef } from 'react';
+import { StyleSheet, Text, View, type ViewStyle } from 'react-native';
+import {
+  Camera,
+  type CameraDevice,
+  type CameraProps,
+} from 'react-native-vision-camera';
+
+
+export interface CameraViewProps {
+  /** Output of ``useCapture().device``.  If null, a placeholder is shown. */
+  device: CameraDevice | null | undefined;
+  /** Flash / torch state from ``useCapture().flash``. */
+  flash?: 'off' | 'on';
+  /** Whether the preview is actively rendering.  Defaults to true. */
+  isActive?: boolean;
+  /**
+   * Enable video recording on the underlying camera.  Required for
+   * `useVideoCapture().startRecording()` — vision-camera throws
+   * `capture/video-not-enabled` if you call startRecording without
+   * this flag set.  Defaults to `false` so apps that only take photos
+   * don't pay the video-pipeline allocation cost.
+   *
+   * Photo capture remains enabled regardless of this flag, so a
+   * single `<CameraView video />` can do both tap (photo) and
+   * hold (video → stitch) flows.
+   */
+  video?: boolean;
+  /** Optional themed guidance banner.  Renders over the preview at the top. */
+  guidance?: string;
+  /** Extra style layer applied on top of the default full-screen layout. */
+  style?: ViewStyle;
+  /** Pass-through to vision-camera for anything custom. */
+  cameraProps?: Partial<CameraProps>;
+  /**
+   * Called when the user taps the preview.  Host apps may use this to
+   * drive focus-on-tap, AE/AF lock, etc.  Not wired into vision-camera's
+   * focus API by this component on purpose — host apps have different
+   * preferences (focus-on-tap vs. tap-to-lock).
+   */
+  onPreviewTap?: (event: { x: number; y: number }) => void;
+}
+
+
+/**
+ * A forwardRef'd wrapper that exposes the underlying Camera ref
+ * to callers (so ``cameraRef.current.takePhoto()`` keeps working),
+ * while presenting a smaller API on the outside.
+ */
+export const CameraView = forwardRef<Camera | null, CameraViewProps>(function CameraView(
+  {
+    device,
+    flash = 'off',
+    isActive = true,
+    video = false,
+    guidance,
+    style,
+    cameraProps,
+  },
+  ref,
+): React.JSX.Element {
+  // Internal ref so we can both attach to <Camera> and forward outward.
+  const innerRef = useRef<Camera>(null);
+  useImperativeHandle(ref, () => innerRef.current as Camera);
+
+  if (!device) {
+    return (
+      <View style={[styles.placeholder, style]} accessibilityLabel="Camera initialising">
+        <Text style={styles.placeholderText}>Initialising camera…</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={[styles.root, style]}>
+      <Camera
+        ref={innerRef}
+        style={StyleSheet.absoluteFill}
+        device={device}
+        isActive={isActive}
+        photo
+        video={video}
+        // Bake the device orientation into the captured pixels.
+        // Without this, vision-camera writes the file in the camera
+        // sensor's native landscape and relies on EXIF metadata to
+        // tell viewers "rotate me" — but RN's <Image> on iOS often
+        // ignores EXIF, leading to thumbnails / previews appearing
+        // sideways even though the user shot in portrait.  Setting
+        // `outputOrientation="device"` rotates the pixels to match
+        // how the user is holding the phone, so the saved JPEG is
+        // "what you see is what was taken".
+        outputOrientation="device"
+        torch={flash === 'on' ? 'on' : 'off'}
+        {...cameraProps}
+      />
+      {guidance ? (
+        <View style={styles.guidance} pointerEvents="none" accessible accessibilityRole="text">
+          <Text style={styles.guidanceText} numberOfLines={2}>
+            {guidance}
+          </Text>
+        </View>
+      ) : null}
+    </View>
+  );
+});
+
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+    overflow: 'hidden',
+  },
+  placeholder: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: '#000',
+  },
+  placeholderText: {
+    color: '#ffffff',
+    fontSize: 14,
+  },
+  guidance: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    backgroundColor: 'rgba(0, 0, 0, 0.55)',
+  },
+  guidanceText: {
+    color: '#ffffff',
+    fontSize: 13,
+  },
+});

package/src/camera/CaptureControlsBar.tsx

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureControlsBar — bottom-of-screen controls for any capture
+ * surface.
+ *
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │  [⚡ flash]      [● shutter]      [ host slot ]            │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ * The SDK owns the flash button and the shutter button (which is
+ * `<CameraShutter>` under the hood, so tap-vs-hold gesture handling
+ * comes "for free" in any host that uses this).  The right-side
+ * action is a render-prop — host apps put a "Submit", "Done",
+ * "Save", "Next" button there as fits their flow.
+ *
+ * Why a slot for the right-side action?
+ *   The flash and shutter buttons are universally camera-shaped;
+ *   every host wants them with the same gesture, the same colors,
+ *   the same accessibility labels.  But the third action varies
+ *   wildly — submitting an audit, saving a single photo, advancing
+ *   a wizard step.  Slotting keeps the SDK from prescribing host
+ *   semantics.
+ */
+
+import React from 'react';
+import {
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { CameraShutter } from './CameraShutter';
+
+
+export interface CaptureControlsBarProps {
+  /** Current flash mode — drives the flash icon's colour. */
+  flashMode: 'off' | 'on';
+  /** Called when the flash button is pressed. */
+  onToggleFlash: () => void;
+  /**
+   * 2026-05-16 — disable the flash button.  Pass `true` when the
+   * active camera surface doesn't honour torch state — currently the
+   * AR camera (ARKit / ARCore own AVCaptureDevice and don't expose
+   * torch control through the JS bridge; toggling would silently
+   * no-op).  Renders the button at reduced opacity + ignores presses.
+   */
+  flashDisabled?: boolean;
+
+  // ── Shutter callbacks (forwarded to <CameraShutter>) ───────────────
+  /** Tap → take photo. */
+  onShutterTap: () => void;
+  /** Hold crosses threshold → start video recording. */
+  onShutterHoldStart: () => void;
+  /** Release after hold → stop recording, stitch. */
+  onShutterHoldComplete: () => void;
+  /**
+   * Disable the shutter (e.g. at-max-photos for the audit, no
+   * camera permission, etc).  Flash and the right-side action
+   * remain interactive.
+   */
+  shutterDisabled?: boolean;
+  /**
+   * Show the shutter's "processing" visual.  Use this while a
+   * stitch is in progress so the operator can't kick off a second
+   * recording mid-stitch.
+   */
+  shutterProcessing?: boolean;
+  /**
+   * Forwards to <CameraShutter maxHoldMs>.  Auto-fires
+   * onShutterHoldComplete when the timer elapses, simulating the
+   * user releasing.  Pair with <CaptureStatusOverlay countdownMs>
+   * so the user sees how long they have left.
+   */
+  shutterMaxHoldMs?: number;
+
+  /**
+   * Render-prop slot for the host's right-side action.  Typically a
+   * Pressable wrapping a "Submit" / "Done" button, but anything is
+   * fair game.  Receives no arguments — wire your callbacks in the
+   * usual way.
+   *
+   * Pass `null` to render an empty spacer instead (keeps the shutter
+   * centred when there's no action to show).
+   */
+  rightAction?: React.ReactNode;
+
+  /** Override the default colours. */
+  colors?: {
+    background?: string;
+    iconButton?: string;
+    iconActive?: string;
+    icon?: string;
+    iconAccessible?: string;
+  };
+
+  /** Bottom inset for safe-area on devices with a home indicator. */
+  bottomInset?: number;
+
+  /** Outer style passthrough. */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+export function CaptureControlsBar({
+  flashMode,
+  onToggleFlash,
+  flashDisabled = false,
+  onShutterTap,
+  onShutterHoldStart,
+  onShutterHoldComplete,
+  shutterDisabled = false,
+  shutterProcessing = false,
+  shutterMaxHoldMs,
+  rightAction = null,
+  colors,
+  bottomInset = 0,
+  style,
+}: CaptureControlsBarProps): React.JSX.Element {
+  const bg = colors?.background ?? '#000000';
+  const iconButtonBg = colors?.iconButton ?? 'rgba(255,255,255,0.12)';
+  const iconActiveBg = colors?.iconActive ?? '#FF9F0A';
+  const iconColor = colors?.icon ?? '#ffffff';
+
+  return (
+    <View
+      style={[
+        styles.bar,
+        { backgroundColor: bg, paddingBottom: bottomInset + 16 },
+        style,
+      ]}
+    >
+      {/* Flash button — colour shifts when active.  Greyed out and
+       *  inert when `flashDisabled` (e.g. AR mode owns the camera and
+       *  doesn't expose torch). */}
+      <Pressable
+        onPress={flashDisabled ? undefined : onToggleFlash}
+        accessibilityRole="button"
+        accessibilityLabel={
+          flashDisabled
+            ? 'Flash unavailable in AR mode'
+            : `Flash ${flashMode === 'on' ? 'on' : 'off'}`
+        }
+        accessibilityState={{
+          selected: flashMode === 'on',
+          disabled: flashDisabled,
+        }}
+        disabled={flashDisabled}
+        style={[
+          styles.iconButton,
+          { backgroundColor: flashMode === 'on' ? iconActiveBg : iconButtonBg },
+          flashDisabled ? { opacity: 0.35 } : null,
+        ]}
+        hitSlop={8}
+      >
+        <Text style={[styles.icon, { color: iconColor }]}>⚡</Text>
+      </Pressable>
+
+      {/* Shutter — SDK component, owns tap-vs-hold gesture. */}
+      <CameraShutter
+        onTap={onShutterTap}
+        onHoldStart={onShutterHoldStart}
+        onHoldComplete={onShutterHoldComplete}
+        maxHoldMs={shutterMaxHoldMs}
+        disabled={shutterDisabled}
+        isProcessing={shutterProcessing}
+      />
+
+      {/* Right-side host slot.  Wrapped in a fixed-width view so
+       *  the flash and shutter stay positioned identically across
+       *  hosts regardless of what the slot contains. */}
+      <View style={styles.rightSlot}>{rightAction}</View>
+    </View>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  bar: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingHorizontal: 24,
+    paddingTop: 16,
+  },
+  iconButton: {
+    width: 48,
+    height: 48,
+    borderRadius: 24,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  icon: {
+    fontSize: 22,
+  },
+  rightSlot: {
+    width: 48,
+    height: 48,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});