@smileid/usesmileid 12.0.0-beta01 → 12.0.0

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";
@@ -56,8 +55,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) {

package/src/presentation/components/use_smile_id_guideline_thumbnail.tsx

@@ -1,4 +1,5 @@
-import { StyleSheet, Text, View } from "react-native";
+import { useState } from "react";
+import { StyleSheet, Text, View, type LayoutChangeEvent } from "react-native";
 import type { UseSmileIDTheme } from "../theme/theme";
 import { useUseSmileIDTheme } from "../theme/theme_context";
 import { useUseSmileIDLocalizations } from "../../l10n/use_smile_id_localizations_provider";
@@ -17,6 +18,15 @@ const BADGE_ICON_SIZE = 14;
 // The badge overhangs the top-end corner of the card.
 const BADGE_OVERHANG = -10;
 
+// Document card SVGs carry a transparent bleed around the visible card (3px
+// L/R, 2px top, 4px bottom); the tile offsets the SVG by it so the card fills
+// the framed box exactly.
+const DOC_CARD_RADIUS = 4;
+const DOC_BLEED_X = 3;
+const DOC_BLEED_TOP = 2;
+const DOC_BLEED_BOTTOM = 4;
+const DOC_BADGE_OVERHANG = -8;
+
 export type UseSmileIDGuidelineThumbnailProps = {
   readonly guideline: InstructionGuideline;
   readonly theme?: UseSmileIDTheme;
@@ -33,12 +43,96 @@ export function UseSmileIDGuidelineThumbnail({
   const themeFromContext = useUseSmileIDTheme();
   const theme = themeProp ?? themeFromContext;
   const localizations = useUseSmileIDLocalizations();
+  // Measured card width — the card scales to its column, so the SVG size and
+  // bleed offset scale with it.
+  const [measuredCardWidth, setMeasuredCardWidth] = useState(0);
   const allowed = guideline.status === "allowed";
   const Illustration = guideline.image;
   const Badge = allowed ? SiFilledCheckCircle : SiFilledCloseCircle;
   const badgeLabel = allowed
     ? localizations.siCdGuidelineAllowed
     : localizations.siCdGuidelineBlocked;
+  const caption = guideline.label(localizations);
+
+  // Document tile: one of four equal columns (so all four fit one row); the
+  // self-contained card SVG fills the column, framed by a border + shadow with
+  // an overhanging badge (no pill).
+  if (guideline.card) {
+    const { width: figmaCardWidth, height: figmaCardHeight } = guideline.card;
+    const scale =
+      measuredCardWidth > 0 ? measuredCardWidth / figmaCardWidth : 0;
+    return (
+      <View style={styles.documentTile}>
+        {/* No `overflow: hidden` so the badge can overhang the card corner. */}
+        <View style={[styles.documentCardWrap, { maxWidth: figmaCardWidth }]}>
+          <View
+            style={[
+              styles.documentCard,
+              {
+                aspectRatio: figmaCardWidth / figmaCardHeight,
+                backgroundColor: theme.colors.cardBackground,
+              },
+            ]}
+            onLayout={(event: LayoutChangeEvent) => {
+              const width = event.nativeEvent.layout.width;
+              setMeasuredCardWidth((previous) =>
+                Math.abs(previous - width) < 0.5 ? previous : width,
+              );
+            }}
+          >
+            {scale > 0 ? (
+              <View
+                style={{
+                  position: "absolute",
+                  left: -DOC_BLEED_X * scale,
+                  top: -DOC_BLEED_TOP * scale,
+                }}
+              >
+                <Illustration
+                  width={(figmaCardWidth + DOC_BLEED_X * 2) * scale}
+                  height={
+                    (figmaCardHeight + DOC_BLEED_TOP + DOC_BLEED_BOTTOM) * scale
+                  }
+                />
+              </View>
+            ) : null}
+            {/* Border drawn over the art so the SVG can't paint over it. */}
+            <View
+              pointerEvents="none"
+              style={[
+                styles.documentCardBorder,
+                { borderColor: theme.colors.stroke },
+              ]}
+            />
+          </View>
+          <View
+            style={[
+              styles.badge,
+              styles.documentBadge,
+              { backgroundColor: theme.colors.cardBackground },
+            ]}
+            accessibilityRole="image"
+            accessibilityLabel={badgeLabel}
+          >
+            <Badge size={BADGE_ICON_SIZE} />
+          </View>
+        </View>
+        <Text
+          numberOfLines={1}
+          style={{
+            ...theme.typography.cardCaption,
+            fontSize: 10,
+            lineHeight: 12,
+            color: theme.colors.cardText,
+            textAlign: "center",
+            marginTop: theme.spacing.extraSmall,
+          }}
+        >
+          {caption}
+        </Text>
+      </View>
+    );
+  }
 
   return (
     <View style={styles.container}>
@@ -86,7 +180,7 @@ export function UseSmileIDGuidelineThumbnail({
           marginTop: theme.spacing.extraSmall,
         }}
       >
-        {guideline.label(localizations)}
+        {caption}
       </Text>
     </View>
   );
@@ -131,4 +225,39 @@ const styles = StyleSheet.create({
     shadowOffset: { width: 0, height: 1 },
     elevation: 1,
   },
+  // One of four equal columns so the document guidelines always fit one row.
+  documentTile: {
+    width: "25%",
+    alignItems: "center",
+    paddingHorizontal: 3,
+  },
+  // Capped at the artwork's natural width (inline maxWidth) so it never grows
+  // past its design size on wide screens.
+  documentCardWrap: {
+    width: "100%",
+    alignSelf: "center",
+  },
+  documentCard: {
+    width: "100%",
+    borderRadius: DOC_CARD_RADIUS,
+    // No `overflow: hidden` — would clip the SVG's bleed and the shadow.
+    shadowColor: "#000000",
+    shadowOpacity: 0.1,
+    shadowRadius: 3,
+    shadowOffset: { width: 0, height: 1 },
+    elevation: 1,
+  },
+  documentCardBorder: {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    start: 0,
+    end: 0,
+    borderRadius: DOC_CARD_RADIUS,
+    borderWidth: 1,
+  },
+  documentBadge: {
+    top: DOC_BADGE_OVERHANG,
+    end: DOC_BADGE_OVERHANG,
+  },
 });