@smileid/usesmileid 12.0.0-beta01 → 12.0.1

package/src/presentation/components/use_smile_id_document_capture_controls.tsx

@@ -1,7 +1,7 @@
 import { Pressable, StyleSheet, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
 import { defaultLightTheme } from "../theme/theme";
-import { SiGallery } from "./icons";
-import { UseSmileIDCaptureSpinner } from "./use_smile_id_capture_spinner";
+import { SiGallery, SiOutlineClose } from "./icons";
 
 export type UseSmileIDDocumentCaptureControlsProps = {
   /** Manual shutter — taps capture a still through the document pipeline. */
@@ -9,30 +9,43 @@ export type UseSmileIDDocumentCaptureControlsProps = {
   /** Gallery upload — taps open the photo library to import a document. */
   readonly showGallery: boolean;
   /**
-   * Landscape: controls form a trailing-edge column; portrait: a bottom row.
-   * Driven by the measured canvas aspect (not the lock) so it follows what renders.
+   * Landscape → trailing-edge lane (✕ top, controls centred); portrait →
+   * centred bottom row (✕ in the top chrome). From the measured canvas aspect.
    */
   readonly isLandscape: boolean;
   /** Disables presses (e.g. a delivery is already in flight). */
   readonly enabled: boolean;
-  /** Capture is committing — the slot shows the progress spinner instead of shutter/gallery. */
-  readonly capturing: boolean;
+  /**
+   * Close/cancel the whole flow. Rendered at the top of the landscape lane so it
+   * shares the shutter's centre-x; in portrait the top chrome renders it instead.
+   */
+  readonly onClose?: (() => void) | undefined;
   readonly onManualShutter: () => void;
   readonly onGallery: () => void;
   /** Localized screen-reader label for the shutter (`si_cd_document_capture_shutter`). */
   readonly shutterAccessibilityLabel: string;
   /** Localized screen-reader label for the gallery button (`si_cd_document_gallery`). */
   readonly galleryAccessibilityLabel: string;
+  /** Localized screen-reader label for the close button (`si_cd_close`). */
+  readonly closeAccessibilityLabel: string;
 };
 
-const SHUTTER_SIZE = 72;
-const SHUTTER_INNER_SIZE = 56;
-const GALLERY_SIZE = 52;
-const CONTROL_GAP = 20;
+const SHUTTER_SIZE = 64;
+const SHUTTER_INNER_SIZE = 46;
+const GALLERY_SIZE = 56;
+const CONTROL_GAP = 24;
+const CLOSE_SIZE = 40;
+/** Trailing-edge inset for the landscape lane (spacing.large). */
+const LANE_EDGE = 24;
+/** Bottom inset for the portrait control row above the safe area (spacing.large). */
+const PORTRAIT_ROW_BOTTOM = 24;
+/** Top/bottom inset bounding the ✕ and the centred controls inside the lane. */
+const LANE_VERTICAL_PADDING = 16;
 
 /**
- * Document capture controls — manual shutter + gallery upload, a trailing-edge
- * column in landscape and a centred bottom row in portrait (matches the capture design).
+ * Document capture controls — manual shutter + gallery upload, plus the close ✕
+ * in landscape (laid out as a trailing-edge lane; portrait is a centred bottom
+ * row with the ✕ in the top chrome).
  */
 export function UseSmileIDDocumentCaptureControls(
   props: UseSmileIDDocumentCaptureControlsProps,
@@ -40,10 +53,33 @@ export function UseSmileIDDocumentCaptureControls(
   // Light-palette forced: overlay is locked to light mode so brand-blue reads over the dim feed.
   const theme = defaultLightTheme;
 
-  if (!props.capturing && !props.showManualShutter && !props.showGallery) {
+  const controlsVisible = props.showManualShutter || props.showGallery;
+  // The lane keeps the ✕ even when shutter/gallery hide (during capture); portrait
+  // renders nothing here once the controls are hidden.
+  const showCloseInLane = props.isLandscape && props.onClose !== undefined;
+  if (!controlsVisible && !showCloseInLane) {
     return null;
   }
 
+  const closeButton = props.onClose ? (
+    <Pressable
+      onPress={props.onClose}
+      accessibilityRole="button"
+      accessibilityLabel={props.closeAccessibilityLabel}
+      testID="si_document_close_button"
+      style={({ pressed }) => [
+        styles.closeButton,
+        {
+          backgroundColor: theme.colors.offBlack,
+          borderColor: theme.colors.backButtonBorder,
+          opacity: pressed ? 0.7 : 1,
+        },
+      ]}
+    >
+      <SiOutlineClose size={20} color={theme.colors.offWhite} />
+    </Pressable>
+  ) : null;
+
   const shutter = props.showManualShutter ? (
     <Pressable
       onPress={props.onManualShutter}
@@ -81,60 +117,88 @@ export function UseSmileIDDocumentCaptureControls(
     </Pressable>
   ) : null;
 
+  if (props.isLandscape) {
+    // Trailing-edge lane: ✕ at the top, shutter/gallery vertically centred
+    // between two flex spacers so the controls hold the lane's vertical centre.
+    return (
+      <SafeAreaView
+        edges={["top", "right", "bottom", "left"]}
+        style={styles.landscapeLane}
+        pointerEvents="box-none"
+        testID="si_document_capture_controls"
+      >
+        {/* Fixed-width slot keeps the ✕ on the shutter's centre-x even when the
+            shutter/gallery hide during capture (matches the native lane width). */}
+        <View style={styles.laneSlot}>{closeButton}</View>
+        <View style={styles.laneSpacer} />
+        {controlsVisible ? (
+          <View style={styles.landscapeControls}>
+            {shutter}
+            {gallery}
+          </View>
+        ) : null}
+        <View style={styles.laneSpacer} />
+      </SafeAreaView>
+    );
+  }
+
+  // Portrait: centred bottom row (gallery left of shutter).
   return (
-    <View
-      style={props.isLandscape ? styles.landscapeColumn : styles.portraitRow}
+    <SafeAreaView
+      edges={["top", "right", "bottom", "left"]}
+      style={styles.portraitRow}
       pointerEvents="box-none"
       testID="si_document_capture_controls"
     >
-      {props.capturing ? (
-        <UseSmileIDCaptureSpinner
-          color={theme.colors.ovalActive}
-          testID="si_document_capture_spinner"
-        />
-      ) : props.isLandscape ? (
-        // Landscape: shutter above gallery (trailing column).
-        <>
-          {shutter}
-          {gallery}
-        </>
-      ) : (
-        // Portrait: gallery left of shutter (bottom row).
-        <>
-          {gallery}
-          {shutter}
-        </>
-      )}
-    </View>
+      {gallery}
+      {shutter}
+    </SafeAreaView>
   );
 }
 
 const styles = StyleSheet.create({
-  landscapeColumn: {
+  // No fixed width: the lane sizes to its (≤ SHUTTER_SIZE-wide) content so the
+  // additive horizontal safe-area inset SHIFTS it inward instead of squeezing the
+  // controls (RN is border-box; padding inside a fixed width would clip them).
+  landscapeLane: {
     position: "absolute",
     top: 0,
     bottom: 0,
-    end: 24,
+    end: LANE_EDGE,
+    flexDirection: "column",
+    alignItems: "center",
+    paddingVertical: LANE_VERTICAL_PADDING,
+  },
+  laneSpacer: { flex: 1 },
+  laneSlot: { width: SHUTTER_SIZE, alignItems: "center" },
+  landscapeControls: {
     flexDirection: "column",
     alignItems: "center",
-    justifyContent: "center",
     gap: CONTROL_GAP,
   },
   portraitRow: {
     position: "absolute",
     start: 0,
     end: 0,
-    bottom: 96,
+    bottom: PORTRAIT_ROW_BOTTOM,
     flexDirection: "row",
     alignItems: "center",
     justifyContent: "center",
     gap: CONTROL_GAP * 1.6,
   },
+  closeButton: {
+    width: CLOSE_SIZE,
+    height: CLOSE_SIZE,
+    borderRadius: CLOSE_SIZE / 2,
+    borderWidth: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
   shutterOuter: {
     width: SHUTTER_SIZE,
     height: SHUTTER_SIZE,
     borderRadius: SHUTTER_SIZE / 2,
-    borderWidth: 3,
+    borderWidth: 4,
     borderColor: "#FFFFFF",
     alignItems: "center",
     justifyContent: "center",

package/src/presentation/components/use_smile_id_document_overlay.tsx

@@ -1,5 +1,6 @@
 import { memo } from "react";
 import { StyleSheet, Text, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
 import Svg, { Path } from "react-native-svg";
 import type { UseSmileIDTheme } from "../theme/theme";
 import { useUseSmileIDTheme } from "../theme/theme_context";
@@ -7,7 +8,10 @@ import {
   isDocumentCaptureActive,
   type UseSmileIDOverlayState as OverlayState,
 } from "../state/use_smile_id_overlay_state";
-import { UseSmileIDDocumentFrameGlyph } from "./use_smile_id_document_frame_glyph";
+import type { DocumentType } from "../../core/models/document_type";
+import { UseSmileIDOvalBorderPalette } from "./use_smile_id_oval_border_palette";
+import { UseSmileIDDocumentShimmer } from "./use_smile_id_document_shimmer";
+import { UseSmileIDCaptureSpinner } from "./use_smile_id_capture_spinner";
 
 export type UseSmileIDDocumentOverlayProps = {
   readonly state: OverlayState;
@@ -15,6 +19,10 @@ export type UseSmileIDDocumentOverlayProps = {
   readonly containerHeight: number;
   /** Optional aspect ratio hint — e.g. CR-80 ID card = 1.586. */
   readonly knownIdAspectRatio?: number;
+  /** Document type — selects the in-frame shimmer skeleton. */
+  readonly documentTypeKind?: DocumentType["kind"];
+  /** Generic-document back side — swaps the front skeleton for the back. */
+  readonly isBackSide?: boolean;
   /**
    * Coaching copy shown in the dark pill below the frame. Rendered here so it
    * tracks the frame geometry instead of a fixed screen offset.
@@ -28,50 +36,88 @@ export type UseSmileIDDocumentOverlayProps = {
 const CHIP_TOP_GAP = 16;
 
 /**
- * Fraction of the container width the document frame spans, per orientation.
- * Matches the Figma capture frames: landscape ID-1 card ≈ 0.53 of the (wide)
- * screen; portrait booklet / passport ≈ 0.68 of the (narrow) screen.
+ * Frame spans ≤71% of container width, height capped at 61% (re-deriving width
+ * from aspect when the cap bites — keeps a wide ID-1 card from overflowing in
+ * landscape). One ratio pair drives both orientations.
  */
-const FRAME_WIDTH_FRACTION_LANDSCAPE = 0.53;
-const FRAME_WIDTH_FRACTION_PORTRAIT = 0.68;
+const FRAME_MAX_WIDTH_RATIO = 0.71;
+const FRAME_MAX_HEIGHT_RATIO = 0.61;
 /** Frame corner radius (matches the bordered frame's `borderRadius`). */
-const FRAME_CORNER_RADIUS = 8;
+const FRAME_CORNER_RADIUS = 16;
+/** Guide-rect border thickness; drawn straddling the frame edge (centred stroke, matching the other SDKs). */
+const FRAME_BORDER_WIDTH = 4;
+/** Capture-progress spinner shown beside the frame (landscape) or bottom-centre (portrait). */
+const SPINNER_SIZE = 48;
+/** Portrait spinner gap above the safe-area bottom (spacing.large) — matches the shutter row. */
+const PORTRAIT_SPINNER_BOTTOM_GAP = 24;
+
+/** Default document aspect (CR-80 ID-1 card) when no known ratio is supplied. */
+export const DEFAULT_DOCUMENT_ASPECT = 1.586;
+
 /**
- * Faint black tint over the WHOLE live feed (net ~0.15 inside the frame). A
- * component constant, not a theme colour — the surround dim (`documentOverlayScrim`)
- * is the partner-overridable layer.
+ * Centred document guide rectangle (container px) for a document [aspect] and
+ * viewport. Single source of truth shared by the overlay (draws the frame) and
+ * the capture screen (derives the native crop region), so the saved capture
+ * matches the frame the user saw.
+ */
+export function documentGuideRect(
+  aspect: number,
+  containerWidth: number,
+  containerHeight: number,
+): {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+} {
+  let width = containerWidth * FRAME_MAX_WIDTH_RATIO;
+  let height = width / aspect;
+  const maxHeight = containerHeight * FRAME_MAX_HEIGHT_RATIO;
+  if (height > maxHeight) {
+    height = maxHeight;
+    width = height * aspect;
+  }
+  return {
+    left: (containerWidth - width) / 2,
+    top: (containerHeight - height) / 2,
+    width,
+    height,
+  };
+}
+/**
+ * Faint black tint over the whole live feed (~0.15 inside the frame). Component
+ * constant, not a theme colour — the surround dim is the overridable layer.
  */
 const DOCUMENT_CAMERA_TINT = "#00000026"; // black @15%
 /** Fallback surround dim when the theme omits `documentOverlayScrim`. */
 const DEFAULT_DOCUMENT_OVERLAY_SCRIM = "#00000066"; // black @40%
 
 /**
- * Document capture frame — two-layer dim (faint full-feed tint + darker surround
- * outside the cutout, ~0.15 inside / ~0.49 outside) plus a border that flips to
- * `ovalActive` on `DOCUMENT_READY`. The cutout is one even-odd path, NOT a `<Mask>`:
- * masks rasterize the full-screen layer to a bitmap on the UI thread per invalidation,
- * freezing the camera preview. Respects `knownIdAspectRatio`; the frame stays centred.
+ * Document capture frame — two-layer dim + a border that flips to `ovalActive`
+ * on `DOCUMENT_READY`. The cutout is one even-odd path, NOT a `<Mask>` (masks
+ * rasterize the full-screen layer per invalidation, freezing the preview).
  */
 export function UseSmileIDDocumentOverlay(
   props: UseSmileIDDocumentOverlayProps,
 ) {
   const themeFromContext = useUseSmileIDTheme();
   const theme = props.theme ?? themeFromContext;
-  const aspect = props.knownIdAspectRatio ?? 1.586;
-  const isLandscapeFrame = aspect >= 1;
-  const frameWidth =
-    props.containerWidth *
-    (isLandscapeFrame
-      ? FRAME_WIDTH_FRACTION_LANDSCAPE
-      : FRAME_WIDTH_FRACTION_PORTRAIT);
-  const frameHeight = frameWidth / aspect;
-  const left = (props.containerWidth - frameWidth) / 2;
-  const top = (props.containerHeight - frameHeight) / 2;
-  // Two-state border: neutral light while idle/positioning, green once committing.
+  const insets = useSafeAreaInsets();
+  const aspect = props.knownIdAspectRatio ?? DEFAULT_DOCUMENT_ASPECT;
+  const isPortrait = aspect < 1;
+  const {
+    left,
+    top,
+    width: frameWidth,
+    height: frameHeight,
+  } = documentGuideRect(aspect, props.containerWidth, props.containerHeight);
+  // Three-state border, shared with the selfie oval (UseSmileIDOvalBorderPalette):
+  // green once the document is correctly framed (ready / capturing / processing),
+  // red while detected but mispositioned (too far / close / off-centre / not
+  // steady), neutral while idle.
   const captureActive = isDocumentCaptureActive(props.state);
-  const borderColor = captureActive
-    ? theme.colors.ovalActive
-    : theme.colors.stroke;
+  const borderColor =
+    theme.colors[UseSmileIDOvalBorderPalette.tokenFor(props.state, false)];
   const surroundColor =
     theme.colors.documentOverlayScrim ?? DEFAULT_DOCUMENT_OVERLAY_SCRIM;
 
@@ -104,37 +150,81 @@ export function UseSmileIDDocumentOverlay(
         cornerRadius={FRAME_CORNER_RADIUS}
         color={surroundColor}
       />
-      {/* In-frame document glyph (placeholder for the per-type capture Lottie). */}
+      {/* In-frame document shimmer — per-type skeleton hint while positioning. */}
       {!captureActive ? (
         <View
           style={{
+            // Inset 10% per axis so the shimmer guide never touches the frame edge.
             position: "absolute",
-            left,
-            top,
-            width: frameWidth,
-            height: frameHeight,
+            left: left + frameWidth * 0.1,
+            top: top + frameHeight * 0.1,
+            width: frameWidth * 0.8,
+            height: frameHeight * 0.8,
           }}
           pointerEvents="none"
         >
-          <UseSmileIDDocumentFrameGlyph
-            width={frameWidth}
-            height={frameHeight}
-            isLandscape={isLandscapeFrame}
+          <UseSmileIDDocumentShimmer
+            width={frameWidth * 0.8}
+            height={frameHeight * 0.8}
+            isBackSide={props.isBackSide ?? false}
+            {...(props.documentTypeKind !== undefined
+              ? { documentTypeKind: props.documentTypeKind }
+              : {})}
           />
         </View>
       ) : null}
       <View
         style={{
           position: "absolute",
-          left,
-          top,
-          width: frameWidth,
-          height: frameHeight,
-          borderWidth: 1.5,
-          borderRadius: FRAME_CORNER_RADIUS,
+          left: left - FRAME_BORDER_WIDTH / 2,
+          top: top - FRAME_BORDER_WIDTH / 2,
+          width: frameWidth + FRAME_BORDER_WIDTH,
+          height: frameHeight + FRAME_BORDER_WIDTH,
+          borderWidth: FRAME_BORDER_WIDTH,
+          borderRadius: FRAME_CORNER_RADIUS + FRAME_BORDER_WIDTH / 2,
           borderColor,
         }}
       />
+      {/* Capture-progress spinner: beside the frame in landscape; bottom-centre in portrait
+          (e.g. Green Book), where the near-full-width frame leaves no side margin. */}
+      {captureActive ? (
+        isPortrait ? (
+          <View
+            style={{
+              position: "absolute",
+              left: 0,
+              right: 0,
+              bottom: insets.bottom + PORTRAIT_SPINNER_BOTTOM_GAP,
+              alignItems: "center",
+            }}
+            pointerEvents="none"
+          >
+            <UseSmileIDCaptureSpinner
+              size={SPINNER_SIZE}
+              color={theme.colors.ovalActive}
+              testID="si_document_capture_spinner"
+            />
+          </View>
+        ) : (
+          <View
+            style={{
+              position: "absolute",
+              left:
+                left +
+                frameWidth +
+                (props.containerWidth - (left + frameWidth) - SPINNER_SIZE) / 2,
+              top: top + (frameHeight - SPINNER_SIZE) / 2,
+            }}
+            pointerEvents="none"
+          >
+            <UseSmileIDCaptureSpinner
+              size={SPINNER_SIZE}
+              color={theme.colors.ovalActive}
+              testID="si_document_capture_spinner"
+            />
+          </View>
+        )
+      ) : null}
       {/* Coaching pill, anchored just below the frame (Figma off-black pill). */}
       {props.feedbackText ? (
         <View

package/src/presentation/components/use_smile_id_document_shimmer.tsx

@@ -0,0 +1,51 @@
+import { memo } from "react";
+import { SvgXml } from "react-native-svg";
+import type { DocumentType } from "../../core/models/document_type";
+import {
+  SI_DOCUMENT_BACK_SHIMMER,
+  SI_DOCUMENT_FRONT_SHIMMER,
+  SI_DOCUMENT_GREEN_BOOK_SHIMMER,
+  SI_DOCUMENT_PASSPORT_SHIMMER,
+} from "../assets/svg/document_shimmer_strings";
+
+/** Translucent in-frame document shimmer — the per-type "align here" skeleton, scaled to fit the capture frame. */
+export type UseSmileIDDocumentShimmerProps = {
+  readonly width: number;
+  readonly height: number;
+  /** Selects the skeleton; the green book and passport ignore `isBackSide`. */
+  readonly documentTypeKind?: DocumentType["kind"];
+  /** Generic documents only: show the back-side skeleton instead of the front. */
+  readonly isBackSide?: boolean;
+  readonly testID?: string;
+};
+
+/** Shimmer skeleton for a document type + side. Only generic documents have front/back; passport and green book ignore the side. */
+export function documentShimmerXml(
+  documentTypeKind: DocumentType["kind"] | undefined,
+  isBackSide: boolean,
+): string {
+  switch (documentTypeKind) {
+    case "passport":
+      return SI_DOCUMENT_PASSPORT_SHIMMER;
+    case "southAfricaGreenBook":
+      return SI_DOCUMENT_GREEN_BOOK_SHIMMER;
+    default:
+      return isBackSide ? SI_DOCUMENT_BACK_SHIMMER : SI_DOCUMENT_FRONT_SHIMMER;
+  }
+}
+
+export const UseSmileIDDocumentShimmer = memo(
+  function UseSmileIDDocumentShimmer(props: UseSmileIDDocumentShimmerProps) {
+    const { width, height, documentTypeKind, isBackSide = false } = props;
+    if (width <= 0 || height <= 0) return null;
+    // Default preserveAspectRatio (meet) fits the skeleton in the frame, undistorted.
+    return (
+      <SvgXml
+        xml={documentShimmerXml(documentTypeKind, isBackSide)}
+        width={width}
+        height={height}
+        {...(props.testID !== undefined ? { testID: props.testID } : {})}
+      />
+    );
+  },
+);

package/src/presentation/components/use_smile_id_enhanced_smart_selfie_clip.tsx

@@ -5,7 +5,6 @@ import type { AnimationObject } from "lottie-react-native";
 import { useReducedMotion } from "../utils/use_reduced_motion";
 import { FaceOvalDefaults } from "./face_oval_defaults";
 import {
-  ENHANCED_SMART_SELFIE_ANIMATION_OPACITY,
   ENHANCED_SMART_SELFIE_ANIMATION_SPEED,
   ENHANCED_SMART_SELFIE_TOTAL_FRAMES,
 } from "./helpers/enhanced_smart_selfie_animation_frames";
@@ -14,8 +13,11 @@ import {
 export const ESS_ALL_DIRECTIONS_ANIMATION =
   require("../assets/si_ess_animation_all_directions.json") as AnimationObject;
 
-/** Square box the Enhanced Smart Selfie cues render in, centred on the oval. */
-export const ENHANCED_SMART_SELFIE_ANIMATION_SIZE = 383;
+/**
+ * Box width as a multiple of the oval width; the baked arrow tips touch the
+ * oval boundary at ≈1.19× — keep this factor below that.
+ */
+export const ENHANCED_SMART_SELFIE_ARROW_FIT = 1.15;
 /** Nudge so the composition's face lands on the oval centre. */
 export const VERTICAL_ALIGNMENT_OFFSET = -15;
 
@@ -47,7 +49,10 @@ export function UseSmileIDEnhancedSmartSelfieClip(
     return null;
   }
 
-  const size = ENHANCED_SMART_SELFIE_ANIMATION_SIZE;
+  const size =
+    containerWidth *
+    FaceOvalDefaults.ovalWidthRatio *
+    ENHANCED_SMART_SELFIE_ARROW_FIT;
   const ovalCenterY = containerHeight * FaceOvalDefaults.ovalCenterYRatio;
 
   const containerStyle = {
@@ -56,8 +61,6 @@ export function UseSmileIDEnhancedSmartSelfieClip(
     top: ovalCenterY - size / 2 + VERTICAL_ALIGNMENT_OFFSET,
     width: size,
     height: size,
-    // Translucent so the face stays the focal point behind the arrow cue.
-    opacity: ENHANCED_SMART_SELFIE_ANIMATION_OPACITY,
   };
 
   if (reducedMotion) {