react-native-image-stitcher 0.1.0

package/src/camera/CaptureStatusOverlay.tsx

@@ -0,0 +1,391 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureStatusOverlay — screen-level visual feedback for the
+ * panorama capture lifecycle.
+ *
+ * Lives in the SDK because the existing shutter-button colour change
+ * is hidden by the user's finger during a hold.  An overlay above
+ * the preview is the only reliable channel for "you ARE recording
+ * right now" feedback.
+ *
+ *   ┌──────────────────────────────────────────────────┐
+ *   │  ● REC  Hold steady, pan slowly…                 │ ← banner
+ *   ├──────────────────────────────────────────────────┤
+ *   │ ┌──────────────────────────────────────────────┐ │
+ *   │ │                                              │ │
+ *   │ │           ⬛  red glow border                 │ │
+ *   │ │           around the preview                 │ │
+ *   │ │                                              │ │
+ *   │ └──────────────────────────────────────────────┘ │
+ *   └──────────────────────────────────────────────────┘
+ *
+ * The component is intentionally pure-presentational: it takes a
+ * `phase` prop and renders the matching UI.  Recording vs stitching
+ * vs idle is the host's source of truth — typically derived from
+ * `useVideoCapture().state` and a local "isStitching" boolean.
+ *
+ * The overlay renders nothing in `idle` so the host can render it
+ * unconditionally without conditional layout shifts.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import {
+  Animated,
+  Easing,
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { useDeviceOrientation, type DeviceOrientation } from './useDeviceOrientation';
+
+
+export type CaptureStatusPhase = 'idle' | 'recording' | 'stitching';
+
+
+export interface CaptureStatusOverlayProps {
+  /**
+   * Current phase.  `idle` renders nothing.  `recording` shows the
+   * REC banner + red glowing border.  `stitching` swaps to a neutral
+   * "Stitching..." banner with no border (recording is over; UI
+   * cue should de-escalate).
+   */
+  phase: CaptureStatusPhase;
+  /**
+   * Optional override for the recording-phase message.  Defaults to
+   * "Hold steady — pan slowly".  Useful if the host wants direction
+   * hints (e.g. "Pan down across the rack") for a specific audit
+   * type.
+   */
+  recordingMessage?: string;
+  /**
+   * Optional override for the stitching-phase message.  Defaults to
+   * "Stitching panorama…".
+   */
+  stitchingMessage?: string;
+  /**
+   * If set, the recording-phase banner shows a live countdown
+   * ("REC 4s left") computed against this value.  Set to the
+   * shutter's `maxHoldMs` so the user can see how long they have
+   * left before the auto-stop fires.  Pair with a fresh value
+   * each time recording starts so the timer resets per capture.
+   *
+   * `recordingStartedAt` is the timestamp (Date.now()) when the
+   * recording phase began — required for the countdown math.
+   */
+  countdownMs?: number;
+  recordingStartedAt?: number;
+  /**
+   * Top inset to offset the banner below the status bar / notch.
+   * Defaults to 0 — host apps using `react-native-safe-area-context`
+   * should pass `insets.top` here so the banner doesn't disappear
+   * behind the notch.
+   */
+  topInset?: number;
+  /** Outer style passthrough. */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+export function CaptureStatusOverlay({
+  phase,
+  recordingMessage = 'Hold steady — pan slowly',
+  stitchingMessage = 'Stitching panorama…',
+  countdownMs,
+  recordingStartedAt,
+  topInset = 0,
+  style,
+}: CaptureStatusOverlayProps): React.JSX.Element | null {
+  // Countdown ticker — re-renders every 250 ms while recording so
+  // the "REC 4s left" text stays current without flooding render
+  // calls.  Disabled (no interval) when not in recording phase or
+  // when countdown isn't configured.
+  const [, setTick] = React.useState(0);
+  React.useEffect(() => {
+    if (phase !== 'recording' || !countdownMs || !recordingStartedAt) return;
+    const id = setInterval(() => setTick((t) => t + 1), 250);
+    return () => clearInterval(id);
+  }, [phase, countdownMs, recordingStartedAt]);
+  // Pulse animation for the REC dot.  Driven by a single Animated
+  // value that loops 0→1→0.  Cheap (no listeners, runs on the
+  // native driver) and only spins up while recording.
+  const pulse = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (phase !== 'recording') {
+      pulse.setValue(0);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(pulse, {
+          toValue: 1,
+          duration: 600,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+        Animated.timing(pulse, {
+          toValue: 0,
+          duration: 600,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [phase, pulse]);
+
+  // Always call the hook — even when phase is 'idle' — so React's
+  // hook-order rule isn't violated.  The accelerometer subscription
+  // is cheap and stays alive for the screen's lifetime.
+  const deviceOrientation = useDeviceOrientation();
+
+  if (phase === 'idle') return null;
+
+  // Interpolate pulse → opacity & scale so the dot breathes 0.6→1.0
+  // opacity and 1.0→1.3 scale.  Subtle; not distracting.
+  const dotOpacity = pulse.interpolate({
+    inputRange: [0, 1],
+    outputRange: [0.5, 1],
+  });
+  const dotScale = pulse.interpolate({
+    inputRange: [0, 1],
+    outputRange: [1, 1.3],
+  });
+
+  // The red border appears only during recording — once the user
+  // releases and we move to stitching the recording is over and a
+  // bright red border would be misleading.
+  const showBorder = phase === 'recording';
+
+  // Compute remaining seconds for the countdown.  Re-rendered
+  // every 250 ms by the tick interval above.  If countdownMs or
+  // recordingStartedAt are missing we just render the base
+  // message without a "Xs left" suffix.
+  let baseMessage =
+    phase === 'recording' ? recordingMessage : stitchingMessage;
+  if (
+    phase === 'recording'
+    && countdownMs
+    && recordingStartedAt
+  ) {
+    const elapsedMs = Date.now() - recordingStartedAt;
+    const remainingMs = Math.max(0, countdownMs - elapsedMs);
+    const remainingSec = Math.ceil(remainingMs / 1000);
+    baseMessage = `${recordingMessage} · ${remainingSec}s left`;
+  }
+  const message = baseMessage;
+
+  // Orientation-aware banner placement via DIRECT absolute positioning
+  // + percentage transforms.
+  //
+  // Why this instead of a rotated-wrapper approach: the previous
+  // wrapper approach (sized to user-view dims, positioned to align
+  // center, rotated) is geometrically correct on paper but rendered
+  // off-center on device (probably a RN flex+rotation interaction).
+  // Direct absolute positioning of the banner with translateX/Y('-50%')
+  // for self-centering is simpler, doesn't depend on useWindowDimensions,
+  // and uses only well-trodden RN style features.
+  //
+  // Border is rendered separately because it hugs the physical camera
+  // preview (in layout coords) — it must not rotate with the banner.
+  const bannerOrientationStyle = bannerStyleForOrientation(
+    deviceOrientation,
+    topInset,
+  );
+
+  return (
+    <View
+      // pointerEvents=box-none so the overlay never steals taps from
+      // the underlying camera / shutter / preview.  The banner and
+      // border are read-only.
+      pointerEvents="box-none"
+      style={[StyleSheet.absoluteFill, style]}
+      accessibilityLiveRegion="polite"
+    >
+      {showBorder ? (
+        <View pointerEvents="none" style={styles.recordBorder} />
+      ) : null}
+
+      <View
+        pointerEvents="none"
+        style={[
+          styles.banner,
+          phase === 'recording' ? styles.bannerRecording : styles.bannerStitching,
+          bannerOrientationStyle,
+        ]}
+      >
+        {phase === 'recording' ? (
+          <Animated.View
+            style={[
+              styles.recDot,
+              { opacity: dotOpacity, transform: [{ scale: dotScale }] },
+            ]}
+          />
+        ) : (
+          <View style={styles.stitchSpinner} />
+        )}
+        <Text style={styles.bannerText} numberOfLines={1}>
+          {phase === 'recording' ? 'REC' : '•••'}{'  '}{message}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+
+/**
+ * Compute the style placing the banner at user-perceived top-center
+ * with text reading in the user's view direction.
+ *
+ * Approach: direct absolute positioning + percentage-translate self-
+ * centering (works on the banner's own measured dimensions, so the
+ * banner's text content can be any width).
+ *
+ * For each orientation, anchor the banner to the layout edge that
+ * corresponds to user-perceived top:
+ *
+ *   portrait              → layout-top    + horizontally centered + 0°
+ *   portrait-upside-down  → layout-bottom + horizontally centered + 180°
+ *   landscape-left        → layout-right  + vertically centered   + 90°
+ *   landscape-right       → layout-left   + vertically centered   + -90°
+ *
+ * In landscape, the banner is rotated around its center so its text
+ * (originally horizontal in layout) reads horizontally in the user's
+ * view.  The translateY('-50%') aligns the banner's center with the
+ * layout's vertical center, which maps to user-horizontal-center
+ * post-rotation.
+ *
+ * RN supports `'50%'` for absolute positions and percentage values in
+ * translateX/Y since 0.70 — the percentage in a translate is relative
+ * to the element's OWN dimensions, which is exactly what self-
+ * centering an unknown-width element needs.
+ */
+function bannerStyleForOrientation(
+  orientation: DeviceOrientation,
+  topInset: number,
+): ViewStyle {
+  switch (orientation) {
+    case 'landscape-left':
+      // 2026-05-18 round 2 — pre-rotation `right: 8` put the
+      // banner's right edge at layout right minus 8; after 90° CW
+      // rotation around banner CENTER, the banner's bbox center
+      // ended up at layout-x = W - 8 - banner_width/2.  The
+      // banner's user-top edge (post-rotation max layout-x) then
+      // landed at user_y = (banner_width - banner_height) / 2 + 8
+      // ≈ 130 px from user-top — way too far down, hence the
+      // "appearing in center vertically" complaint.
+      //
+      // Fix: shift banner's center to layout-x = W - 34 (= 8 +
+      // estimated banner_height/2 ≈ 26).  Achieved by anchoring
+      // at `right: 34` (banner right edge = W-34) and then
+      // `translateX('50%')` (shifts center right by banner_width/
+      // 2 = back to W-34).  Post-rotation max layout-x = W - 34 +
+      // banner_height/2 = W - 8 → user_y = 8 px from user-top.
+      // Works regardless of banner_width because the translateX
+      // percentage cancels the W_b/2 offset.
+      //
+      // Landscape user-top has no notch (the Dynamic Island sits
+      // on user-LEFT in landscape-left, user-RIGHT in landscape-
+      // right), so we don't add topInset here — 8 px is the tight
+      // visual minimum the user asked for.
+      return {
+        position: 'absolute',
+        right: 34,
+        top: '50%',
+        transform: [
+          { translateY: '-50%' },
+          { translateX: '50%' },
+          { rotate: '90deg' },
+        ],
+      };
+    case 'landscape-right':
+      return {
+        position: 'absolute',
+        left: 34,
+        top: '50%',
+        transform: [
+          { translateY: '-50%' },
+          { translateX: '-50%' },
+          { rotate: '-90deg' },
+        ],
+      };
+    case 'portrait-upside-down':
+      return {
+        position: 'absolute',
+        bottom: topInset + 8,
+        left: '50%',
+        transform: [
+          { translateX: '-50%' },
+          { rotate: '180deg' },
+        ],
+      };
+    case 'portrait':
+    default:
+      return {
+        position: 'absolute',
+        top: topInset + 8,
+        left: '50%',
+        transform: [
+          { translateX: '-50%' },
+        ],
+      };
+  }
+}
+
+
+const styles = StyleSheet.create({
+  banner: {
+    // position: 'absolute' is added back so the orientation-specific
+    // style (returned by bannerStyleForOrientation) can position the
+    // banner at the layout edge for that orientation using top/right/
+    // bottom/left.  The transform array on the same style does the
+    // self-centering via translateX/Y('-50%') and applies rotation.
+    position: 'absolute',
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+    borderRadius: 22,
+    minHeight: 36,
+  },
+  bannerRecording: {
+    backgroundColor: 'rgba(255,59,48,0.92)',
+  },
+  bannerStitching: {
+    // Neutral grey while we wait for the stitcher; communicates
+    // "still working" without the alarming red of active recording.
+    backgroundColor: 'rgba(0,0,0,0.78)',
+  },
+  bannerText: {
+    color: '#ffffff',
+    fontSize: 13,
+    fontWeight: '600',
+    marginLeft: 8,
+  },
+  recDot: {
+    width: 10,
+    height: 10,
+    borderRadius: 5,
+    backgroundColor: '#ffffff',
+  },
+  stitchSpinner: {
+    // Static dot for now — RN's ActivityIndicator is fine here too,
+    // but a calm static dot keeps visual noise low when the user
+    // already gets the spinner via the shutter-button "processing"
+    // state below.
+    width: 8,
+    height: 8,
+    borderRadius: 4,
+    backgroundColor: '#ffffff',
+    opacity: 0.7,
+  },
+  recordBorder: {
+    ...StyleSheet.absoluteFillObject,
+    borderWidth: 4,
+    borderColor: 'rgba(255,59,48,0.9)',
+  },
+});

package/src/camera/CaptureThumbnailStrip.tsx

@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureThumbnailStrip — horizontal thumbnail strip with built-in
+ * tap-to-preview modal, designed for the audit capture surface.
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  [thumb 4:3]  [thumb 9:16]  [thumb pano]  …             │
+ *   │  3 / 5 min · 10 max                                     │
+ *   └─────────────────────────────────────────────────────────┘
+ *
+ * Two reasons this lives in the SDK rather than the host:
+ *   1. The thumbnail UX is camera-shaped — tightly coupled to the
+ *      `CaptureResult` dimension fields the SDK introduced for
+ *      aspect-ratio rendering.  Any host that uses `useCapture`
+ *      benefits from the same display logic, so the SDK is the
+ *      right home.
+ *   2. The preview modal is a non-trivial chunk of UI (full-screen
+ *      Image with close affordance + safe-area handling).  Hosts
+ *      were inevitably going to re-implement it with subtly
+ *      different gesture handling; centralising avoids drift.
+ *
+ * The strip is intentionally headless about persistence: it knows
+ * nothing about WatermelonDB, the host's DB schema, or sync state.
+ * Callers pass an array of plain objects with `id`, `uri`, and
+ * optional `width`/`height` and the strip handles the rest.
+ *
+ * Aspect-ratio rendering:
+ *   - Thumbnails are anchored at a fixed height (default 60 px)
+ *     and width is computed from `width / height` * height.
+ *   - Width is clamped to [40, 180] so a tall portrait doesn't
+ *     squish to a sliver and a 5000 px panorama doesn't push
+ *     siblings off-screen.
+ *   - Items missing dimensions (legacy captures saved before the
+ *     SDK exposed them) fall back to square — matches prior
+ *     behaviour and avoids visual jumps when scrolling mixed
+ *     histories.
+ */
+
+import React, { useCallback, useMemo, useState } from 'react';
+import {
+  FlatList,
+  Image,
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { CapturePreview } from './CapturePreview';
+
+
+export interface CaptureThumbnailItem {
+  /** Stable id for FlatList keying. */
+  id: string;
+  /** `file://` or remote URI of the captured image. */
+  uri: string;
+  /** Image width in pixels.  Optional; falls back to square. */
+  width?: number;
+  /** Image height in pixels.  Optional; falls back to square. */
+  height?: number;
+}
+
+
+export interface CaptureThumbnailStripProps {
+  /** Captures to render, in the order they should appear. */
+  items: CaptureThumbnailItem[];
+  /**
+   * Optional minimum-photos hint for the count line.  When `count >=
+   * minPhotos` the count text uses the success colour, otherwise it
+   * uses the warning colour.  Pass undefined to suppress the hint.
+   */
+  minPhotos?: number;
+  /** Optional maximum-photos hint for the count line. */
+  maxPhotos?: number;
+  /** Strip background colour (defaults to translucent black). */
+  backgroundColor?: string;
+  /** Text colour applied to the count line and "No photos" placeholder. */
+  textColor?: string;
+  /** Colour used when count meets `minPhotos`. */
+  successColor?: string;
+  /** Colour used when count is below `minPhotos`. */
+  warningColor?: string;
+  /**
+   * Disable tap-to-preview.  When true, thumbnails are still rendered
+   * but tapping them is a no-op.  Default false (preview enabled).
+   */
+  disablePreview?: boolean;
+  /**
+   * Custom tap handler.  When provided, tapping a thumbnail calls
+   * this instead of opening the strip's built-in preview modal.
+   * Use this when the host wants to show its own preview UI (e.g.
+   * with delete / recapture buttons gated on capture sync state).
+   */
+  onItemPress?: (item: CaptureThumbnailItem) => void;
+  /**
+   * Optional outer style.  Layout-related props (height, padding)
+   * stay under the strip's control to keep the count line consistent.
+   */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+/// Fixed thumbnail height — width varies with aspect ratio.
+const THUMB_HEIGHT = 60;
+/// Width clamps protect the strip from extreme aspect ratios (very
+/// tall portraits squishing to a sliver, very wide panoramas pushing
+/// siblings off-screen).
+const THUMB_MIN_WIDTH = 40;
+const THUMB_MAX_WIDTH = 180;
+
+
+function thumbWidth(item: CaptureThumbnailItem): number {
+  const { width, height } = item;
+  if (!width || !height || width <= 0 || height <= 0) {
+    // Legacy capture without dimensions — fall back to square.
+    return THUMB_HEIGHT;
+  }
+  const ratio = width / height;
+  const computed = Math.round(THUMB_HEIGHT * ratio);
+  return Math.max(THUMB_MIN_WIDTH, Math.min(THUMB_MAX_WIDTH, computed));
+}
+
+
+export function CaptureThumbnailStrip({
+  items,
+  minPhotos,
+  maxPhotos,
+  backgroundColor = 'rgba(0,0,0,0.85)',
+  textColor = '#ffffff',
+  successColor = '#34C759',
+  warningColor = '#FF9F0A',
+  disablePreview = false,
+  onItemPress,
+  style,
+}: CaptureThumbnailStripProps): React.JSX.Element {
+  // Built-in preview state — only used when the host hasn't
+  // provided its own onItemPress handler.  Letting the host pass a
+  // handler is how the AuditCaptureScreen unifies thumbnail
+  // preview with post-stitch confirmation.
+  const [previewItem, setPreviewItem] =
+    useState<CaptureThumbnailItem | null>(null);
+
+  // Memoise so FlatList doesn't see a fresh callback identity every
+  // render and re-render every row.
+  const handleItemPress = useCallback(
+    (item: CaptureThumbnailItem) => {
+      if (disablePreview) return;
+      if (onItemPress) {
+        onItemPress(item);
+        return;
+      }
+      setPreviewItem(item);
+    },
+    [disablePreview, onItemPress],
+  );
+
+  const closePreview = useCallback(() => setPreviewItem(null), []);
+
+  const countLine = useMemo(() => {
+    if (minPhotos === undefined && maxPhotos === undefined) return null;
+    const meetsMin =
+      minPhotos === undefined ? true : items.length >= minPhotos;
+    const text =
+      minPhotos !== undefined && maxPhotos !== undefined
+        ? `${items.length} / ${minPhotos} min · ${maxPhotos} max`
+        : minPhotos !== undefined
+          ? `${items.length} / ${minPhotos} min`
+          : `${items.length} / ${maxPhotos} max`;
+    return (
+      <Text
+        style={[
+          styles.count,
+          { color: meetsMin ? successColor : warningColor },
+        ]}
+        accessibilityLabel={`Captured ${items.length} photos`}
+      >
+        {text}
+      </Text>
+    );
+  }, [items.length, minPhotos, maxPhotos, successColor, warningColor]);
+
+  return (
+    <View style={[styles.root, { backgroundColor }, style]}>
+      <FlatList
+        data={items}
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        keyExtractor={(item) => item.id}
+        contentContainerStyle={styles.listContent}
+        ListEmptyComponent={
+          <View
+            style={[styles.placeholder, { borderColor: textColor }]}
+            accessibilityLabel="No photos captured"
+          >
+            <Text style={[styles.placeholderText, { color: textColor }]}>
+              No photos
+            </Text>
+          </View>
+        }
+        renderItem={({ item }) => (
+          <Pressable
+            onPress={() => handleItemPress(item)}
+            disabled={disablePreview}
+            accessibilityRole="imagebutton"
+            accessibilityLabel="Open preview"
+            // Resolve the width per-item — done at render rather than
+            // inside renderItem's style prop so the function isn't
+            // re-created on every parent render.
+            style={[
+              styles.thumbWrapper,
+              { width: thumbWidth(item), height: THUMB_HEIGHT },
+            ]}
+          >
+            <Image
+              source={{ uri: item.uri }}
+              style={styles.thumbImage}
+              resizeMode="cover"
+            />
+          </Pressable>
+        )}
+      />
+      {countLine}
+
+      {/* Built-in preview — only shown when host didn't pass
+       *  onItemPress.  When the host owns the preview, the strip's
+       *  job is just to surface taps via the callback. */}
+      <CapturePreview
+        visible={previewItem !== null}
+        imageUri={previewItem?.uri ?? ''}
+        imageWidth={previewItem?.width}
+        imageHeight={previewItem?.height}
+        onClose={closePreview}
+      />
+    </View>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  root: {
+    paddingVertical: 8,
+  },
+  listContent: {
+    paddingHorizontal: 12,
+    alignItems: 'center',
+  },
+  thumbWrapper: {
+    marginRight: 8,
+    borderRadius: 4,
+    overflow: 'hidden',
+    backgroundColor: '#222',
+  },
+  thumbImage: {
+    width: '100%',
+    height: '100%',
+  },
+  placeholder: {
+    height: THUMB_HEIGHT,
+    paddingHorizontal: 16,
+    borderRadius: 4,
+    borderWidth: 1,
+    borderStyle: 'dashed',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  placeholderText: {
+    fontSize: 12,
+    opacity: 0.6,
+  },
+  count: {
+    fontSize: 12,
+    paddingHorizontal: 16,
+    paddingTop: 4,
+  },
+});