@smileid/usesmileid 12.0.0-beta01

package/src/presentation/state/use_smile_id_overlay_state.ts

@@ -0,0 +1,70 @@
+/**
+ * Overlay state machine — drives the face / document oval's border.
+ * Derived from the analyzer's feedback keys plus lifecycle states;
+ * `UseSmileIDOvalBorderPalette` holds the state → colour-token table.
+ */
+export const UseSmileIDOverlayState = {
+  // Lifecycle states
+  INSTRUCTION: "INSTRUCTION",
+  IDLE: "IDLE",
+  READY: "READY",
+  CAPTURING: "CAPTURING",
+  PROCESSING: "PROCESSING",
+
+  // Face feedback
+  FACE_DETECTED: "FACE_DETECTED",
+  TOO_CLOSE: "TOO_CLOSE",
+  TOO_FAR: "TOO_FAR",
+  MULTIPLE_FACES: "MULTIPLE_FACES",
+  HEAD_TURN: "HEAD_TURN",
+  FACE_NOT_CENTERED: "FACE_NOT_CENTERED",
+  LOW_LIGHT: "LOW_LIGHT",
+  BRIGHT_LIGHT: "BRIGHT_LIGHT",
+  WRONG_ORIENTATION: "WRONG_ORIENTATION",
+  NOT_SMILING: "NOT_SMILING",
+
+  // Directional hints — neutral rim + red arc on the crowded edge
+  MOVE_LEFT: "MOVE_LEFT",
+  MOVE_RIGHT: "MOVE_RIGHT",
+  MOVE_UP: "MOVE_UP",
+  MOVE_DOWN: "MOVE_DOWN",
+
+  // Document feedback
+  DOCUMENT_READY: "DOCUMENT_READY",
+  DOCUMENT_NOT_CENTERED: "DOCUMENT_NOT_CENTERED",
+  DOCUMENT_TOO_FAR: "DOCUMENT_TOO_FAR",
+  DOCUMENT_TOO_CLOSE: "DOCUMENT_TOO_CLOSE",
+  DOCUMENT_HOLD_STILL: "DOCUMENT_HOLD_STILL",
+} as const;
+
+export type UseSmileIDOverlayState =
+  (typeof UseSmileIDOverlayState)[keyof typeof UseSmileIDOverlayState];
+
+/** Total state count — pinned in tests to catch a missed addition/drop at PR time. */
+export const OVERLAY_STATE_COUNT = 24 as const;
+
+/**
+ * True once document capture is committing (green-border states). Drives border
+ * colour, glyph visibility, and the controls→spinner swap together: the manual
+ * shutter + gallery controls hide here, since a manual shutter is moot once
+ * auto-capture is finalising and the controls would collide with the spinner.
+ */
+export function isDocumentCaptureActive(
+  state: UseSmileIDOverlayState,
+): boolean {
+  return (
+    state === UseSmileIDOverlayState.DOCUMENT_READY ||
+    state === UseSmileIDOverlayState.CAPTURING ||
+    state === UseSmileIDOverlayState.PROCESSING
+  );
+}
+
+/** True for the directional MOVE_* hints. */
+export function isDirectional(state: UseSmileIDOverlayState): boolean {
+  return (
+    state === UseSmileIDOverlayState.MOVE_LEFT ||
+    state === UseSmileIDOverlayState.MOVE_RIGHT ||
+    state === UseSmileIDOverlayState.MOVE_UP ||
+    state === UseSmileIDOverlayState.MOVE_DOWN
+  );
+}

package/src/presentation/theme/theme.ts

@@ -0,0 +1,399 @@
+/**
+ * Visual design tokens — the single source of truth for colours, typography,
+ * spacing, and shapes used by every `usesmileid` screen. Alpha is 8-digit hex
+ * `#RRGGBBAA` (RN's native format); opaque colours stay 6-digit for readability.
+ */
+export type UseSmileIDColors = {
+  // --- Brand / partner-overridable -------------------------------
+  primary: string;
+  primaryForeground: string;
+  secondary: string;
+  accent: string;
+
+  // --- Surfaces --------------------------------------------------
+  background: string;
+  cardBackground: string;
+  instructionCardBackground: string;
+
+  // --- Text ------------------------------------------------------
+  titleText: string;
+  cardText: string;
+
+  // --- Disabled / inactive ---------------------------------------
+  /**
+   * Neutral grey fill for a disabled button container. Optional so pre-existing
+   * partner themes still type-check; components fall back to neutral grey if absent.
+   */
+  disabledBackground?: string;
+  /** Neutral grey label for a disabled button. See `disabledBackground`. */
+  disabledForeground?: string;
+
+  // --- Borders / dividers ----------------------------------------
+  stroke: string;
+
+  // --- Semantic --------------------------------------------------
+  warningFill: string;
+  warningIcon: string;
+  warningStroke: string;
+  successFill: string;
+  successIcon: string;
+
+  // --- Capture overlay -------------------------------------------
+  captureOverlayBackground: string;
+  /**
+   * Document capture surround dim — black drawn only OUTSIDE the frame cutout,
+   * composited over the full-feed tint so the framed document stays lightly visible
+   * (net ~0.49 outside, ~0.15 inside). Optional; falls back to black @40% if absent.
+   */
+  documentOverlayScrim?: string;
+  captureOverlayStroke: string;
+  captureFeedbackBackground: string;
+  captureFeedbackText: string;
+  captureProgressIndicator: string;
+
+  // --- Oval guides (capture / preview / processing) --------------
+  ovalDefault: string;
+  ovalActive: string;
+  ovalWarning: string;
+  /** Red arc on the oval edge during a "move your device" hint. Theme-static. */
+  ovalDirectionalIndicator: string;
+
+  // --- Preview accept / reject -----------------------------------
+  previewAcceptBackground: string;
+  previewAcceptIcon: string;
+  previewAcceptBorder: string;
+  previewRejectBackground: string;
+  previewRejectIcon: string;
+  previewRejectBorder: string;
+
+  // --- Capture review (preview + processing page surface) --------
+  /** Uniform light page behind the capture-review screens. Theme-static. */
+  captureReviewBackground: string;
+
+  // --- Processing / cards ----------------------------------------
+  submittingIndicator: string;
+  cardShadow: string;
+  backButtonBorder: string;
+
+  // --- Branding --------------------------------------------------
+  smileIdYellow: string;
+  offBlack: string;
+  offWhite: string;
+};
+
+/** Font weights used by the SDK's typography scale. */
+export type UseSmileIDFontWeight = "400" | "500" | "600" | "700" | "800";
+
+/** One typography token: a concrete font face plus size metrics; spread into a `Text` style. */
+export type UseSmileIDTextStyle<W extends UseSmileIDFontWeight> = {
+  fontFamily: string;
+  fontSize: number;
+  lineHeight: number;
+  fontWeight: W;
+  /** Tracking in dp; omitted means the platform default (0). */
+  letterSpacing?: number;
+};
+
+/** Ten typography styles spanning page heading down to button caption. */
+export type UseSmileIDTypography = {
+  fontFamily: string;
+  pageHeading: UseSmileIDTextStyle<"800">;
+  sectionHeading: UseSmileIDTextStyle<"600">;
+  subHeading: UseSmileIDTextStyle<"500">;
+  cardHeading: UseSmileIDTextStyle<"800">;
+  cardTitle: UseSmileIDTextStyle<"700">;
+  cardSubTitle: UseSmileIDTextStyle<"400">;
+  cardCaption: UseSmileIDTextStyle<"500">;
+  body: UseSmileIDTextStyle<"400">;
+  button: UseSmileIDTextStyle<"700">;
+  buttonCaption: UseSmileIDTextStyle<"700">;
+};
+
+/** Bundled DM Sans family — used as the default when no override is set. */
+export const DEFAULT_FONT_FAMILY = "DMSans";
+
+/**
+ * Weight-specific face names for the bundled DM Sans set. Each weight is its own
+ * registered face because RN cannot match a numeric weight within a single family
+ * for fonts loaded from files.
+ */
+export const DM_SANS_FONT_NAMES: Record<UseSmileIDFontWeight, string> = {
+  "400": "DMSans-Regular",
+  "500": "DMSans-Medium",
+  "600": "DMSans-SemiBold",
+  "700": "DMSans-Bold",
+  "800": "DMSans-ExtraBold",
+};
+
+/**
+ * Resolve the concrete `fontFamily` for a token: DM Sans maps each weight to its
+ * own registered face; a partner-supplied family is used as-is.
+ */
+export function resolveFontFamily(
+  fontFamily: string,
+  weight: UseSmileIDFontWeight,
+): string {
+  return fontFamily === DEFAULT_FONT_FAMILY
+    ? DM_SANS_FONT_NAMES[weight]
+    : fontFamily;
+}
+
+/**
+ * Rebuild a typography scale against a (partner-supplied) font family.
+ * With the default family this returns weight-resolved DM Sans faces.
+ */
+export function typographyWithFontFamily(
+  base: UseSmileIDTypography,
+  fontFamily: string,
+): UseSmileIDTypography {
+  const token = <W extends UseSmileIDFontWeight>(
+    style: UseSmileIDTextStyle<W>,
+  ): UseSmileIDTextStyle<W> => ({
+    ...style,
+    fontFamily: resolveFontFamily(fontFamily, style.fontWeight),
+  });
+  return {
+    fontFamily,
+    pageHeading: token(base.pageHeading),
+    sectionHeading: token(base.sectionHeading),
+    subHeading: token(base.subHeading),
+    cardHeading: token(base.cardHeading),
+    cardTitle: token(base.cardTitle),
+    cardSubTitle: token(base.cardSubTitle),
+    cardCaption: token(base.cardCaption),
+    body: token(base.body),
+    button: token(base.button),
+    buttonCaption: token(base.buttonCaption),
+  };
+}
+
+/** Spacing scale (extraSmall → extraLarge) used throughout the SDK UI. */
+export type UseSmileIDSpacing = {
+  extraSmall: number;
+  small: number;
+  medium: number;
+  large: number;
+  extraLarge: number;
+};
+
+/**
+ * Shape tokens. Partners can customize button/card corner radii via the theme
+ * builder; capture-specific shapes (oval, overlay geometry) are locked.
+ */
+export type UseSmileIDShapes = {
+  /** Pill button radius (32). */
+  buttonRadius: number;
+  /** Card corner radius (16). */
+  cardRadius: number;
+};
+
+export type UseSmileIDTheme = {
+  colors: UseSmileIDColors;
+  typography: UseSmileIDTypography;
+  spacing: UseSmileIDSpacing;
+  shapes: UseSmileIDShapes;
+};
+
+const dmSans = (weight: UseSmileIDFontWeight): string =>
+  DM_SANS_FONT_NAMES[weight];
+
+const sharedTypography: UseSmileIDTypography = {
+  fontFamily: DEFAULT_FONT_FAMILY,
+  pageHeading: {
+    fontFamily: dmSans("800"),
+    fontSize: 24,
+    lineHeight: 32,
+    fontWeight: "800",
+    letterSpacing: -0.4,
+  },
+  sectionHeading: {
+    fontFamily: dmSans("600"),
+    fontSize: 18,
+    lineHeight: 24,
+    fontWeight: "600",
+  },
+  subHeading: {
+    fontFamily: dmSans("500"),
+    fontSize: 14,
+    lineHeight: 20,
+    fontWeight: "500",
+  },
+  cardHeading: {
+    fontFamily: dmSans("800"),
+    fontSize: 20,
+    lineHeight: 26,
+    fontWeight: "800",
+    letterSpacing: -0.425,
+  },
+  cardTitle: {
+    fontFamily: dmSans("700"),
+    fontSize: 14,
+    lineHeight: 20,
+    fontWeight: "700",
+  },
+  cardSubTitle: {
+    fontFamily: dmSans("400"),
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "400",
+  },
+  cardCaption: {
+    fontFamily: dmSans("500"),
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "500",
+  },
+  body: {
+    fontFamily: dmSans("400"),
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "400",
+  },
+  button: {
+    fontFamily: dmSans("700"),
+    fontSize: 16,
+    lineHeight: 24,
+    fontWeight: "700",
+  },
+  buttonCaption: {
+    fontFamily: dmSans("700"),
+    fontSize: 10,
+    lineHeight: 16,
+    fontWeight: "700",
+  },
+};
+
+const sharedSpacing: UseSmileIDSpacing = {
+  extraSmall: 8,
+  small: 12,
+  medium: 16,
+  large: 24,
+  extraLarge: 40,
+};
+
+const sharedShapes: UseSmileIDShapes = {
+  buttonRadius: 32,
+  cardRadius: 16,
+};
+
+/** Default light theme. */
+export const defaultLightTheme: UseSmileIDTheme = {
+  colors: {
+    primary: "#151F72",
+    primaryForeground: "#FFFFFF",
+    secondary: "#5E646E",
+    accent: "#4D88FF",
+
+    background: "#F9FAFB",
+    cardBackground: "#FFFFFF",
+    instructionCardBackground: "#F9F0E766",
+
+    titleText: "#21232C",
+    cardText: "#5E646E",
+
+    disabledBackground: "#E4E7EC",
+    disabledForeground: "#98A2B3",
+
+    stroke: "#EAECF0",
+
+    warningFill: "#FEF3C7",
+    warningIcon: "#FF5805",
+    warningStroke: "#FFEDD5",
+    successFill: "#DCFCE7",
+    successIcon: "#2CC05C",
+
+    captureOverlayBackground: "#FFFFFFE5",
+    documentOverlayScrim: "#00000066", // black @40% — surround dim outside the frame
+    captureOverlayStroke: "#151F72",
+    captureFeedbackBackground: "#000000BF",
+    captureFeedbackText: "#FFFFFF",
+    captureProgressIndicator: "#4D88FF",
+
+    ovalDefault: "#C4C4C4",
+    ovalActive: "#2CC05C",
+    ovalWarning: "#EF4343",
+    ovalDirectionalIndicator: "#EF4343",
+
+    // Preview/accept/submitting tokens are theme-static (same in dark) so the
+    // capture review surface reads identically across themes.
+    previewAcceptBackground: "#04B04A1A", // 10% green
+    previewAcceptIcon: "#12B76A",
+    previewAcceptBorder: "#04B04A4D", // 30% green
+    previewRejectBackground: "#F8FAFC",
+    previewRejectIcon: "#90A1B9",
+    previewRejectBorder: "#E2E8F0",
+    captureReviewBackground: "#F8FAFC",
+
+    submittingIndicator: "#2CC05C",
+    cardShadow: "#0000001A", // black @10%
+    backButtonBorder: "#FFFFFF1A", // white @10% rim on the dark fill
+
+    smileIdYellow: "#F2BD51",
+    offBlack: "#2D2B2A",
+    offWhite: "#F9F0E7",
+  },
+  typography: sharedTypography,
+  spacing: sharedSpacing,
+  shapes: sharedShapes,
+};
+
+/** Default dark theme — surface tokens swap, brand tokens shift cooler. */
+export const defaultDarkTheme: UseSmileIDTheme = {
+  colors: {
+    primary: "#4D88FF",
+    primaryForeground: "#FFFFFF",
+    secondary: "#C2C5CB",
+    accent: "#7BA3FF",
+
+    background: "#1A1C23",
+    cardBackground: "#272A35",
+    instructionCardBackground: "#2D3748",
+
+    titleText: "#F2F2F2",
+    cardText: "#C2C5CB",
+
+    disabledBackground: "#3A3D47",
+    disabledForeground: "#667085",
+
+    // 15% alpha — divider stroke on dark surfaces.
+    stroke: "#EAECF026",
+
+    warningFill: "#3B2F12",
+    warningIcon: "#FF5805",
+    warningStroke: "#5C3A1A",
+    successFill: "#163B27",
+    successIcon: "#2CC05C",
+
+    captureOverlayBackground: "#FFFFFFE5",
+    documentOverlayScrim: "#00000066", // black @40% — surround dim outside the frame (identical in dark)
+    captureOverlayStroke: "#4D88FF",
+    captureFeedbackBackground: "#000000BF",
+    captureFeedbackText: "#FFFFFF",
+    captureProgressIndicator: "#4D88FF",
+
+    ovalDefault: "#C4C4C4",
+    ovalActive: "#2CC05C",
+    ovalWarning: "#EF4343",
+    ovalDirectionalIndicator: "#EF4343",
+
+    // Theme-static (match light) — the capture review surface stays consistent.
+    previewAcceptBackground: "#04B04A1A", // 10% green
+    previewAcceptIcon: "#12B76A",
+    previewAcceptBorder: "#04B04A4D", // 30% green
+    previewRejectBackground: "#F8FAFC",
+    previewRejectIcon: "#90A1B9",
+    previewRejectBorder: "#E2E8F0",
+    captureReviewBackground: "#F8FAFC",
+
+    submittingIndicator: "#2CC05C",
+    cardShadow: "#0000001A", // black @10%
+    backButtonBorder: "#0000001A", // black @10% rim on the light fill
+
+    smileIdYellow: "#F2BD51",
+    offBlack: "#F9F0E7",
+    offWhite: "#2D2B2A",
+  },
+  typography: sharedTypography,
+  spacing: sharedSpacing,
+  shapes: sharedShapes,
+};

package/src/presentation/theme/theme_context.tsx

@@ -0,0 +1,45 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { defaultLightTheme, type UseSmileIDTheme } from "./theme";
+
+/**
+ * React Context for the SDK's visual design tokens.
+ *
+ * The active theme cascades through the UI tree via context, not
+ * props. `<UseSmileIDBuilder>` mounts this provider with the
+ * partner-built theme; every screen + component reads via
+ * `useUseSmileIDTheme()`.
+ *
+ * **Default value** is `defaultLightTheme` so:
+ *   - Components imported by partners outside `<UseSmileIDBuilder>`
+ *     still render with canonical tokens (don't crash on a missing
+ *     provider).
+ *   - Custom partner widgets rendered inside `<UseSmileIDBuilder>`
+ *     inherit the active theme without prop-drilling.
+ */
+const UseSmileIDThemeContext =
+  createContext<UseSmileIDTheme>(defaultLightTheme);
+
+export type UseSmileIDThemeProviderProps = {
+  readonly value: UseSmileIDTheme;
+  readonly children: ReactNode;
+};
+
+export function UseSmileIDThemeProvider({
+  value,
+  children,
+}: UseSmileIDThemeProviderProps) {
+  return (
+    <UseSmileIDThemeContext.Provider value={value}>
+      {children}
+    </UseSmileIDThemeContext.Provider>
+  );
+}
+
+/**
+ * Read the active `UseSmileIDTheme` from context. Returns
+ * `defaultLightTheme` when no `<UseSmileIDThemeProvider>` wraps
+ * the caller.
+ */
+export function useUseSmileIDTheme(): UseSmileIDTheme {
+  return useContext(UseSmileIDThemeContext);
+}

package/src/presentation/theme/use_smile_id_motion.ts

@@ -0,0 +1,12 @@
+/**
+ * Capture/oval animation timings (ms) — a cross-platform contract;
+ * change only in lockstep with the sibling SDKs.
+ */
+export const UseSmileIDMotion = {
+  /** Border-color tween and directional-arc alpha fade. */
+  stateTransition: 300,
+  /** Oval capture-progress fill animation (linear). */
+  progressFill: 350,
+  /** Settle window for the guidance copy + coaching-animation key. */
+  feedbackDebounce: 300,
+} as const;

package/src/presentation/theme/use_use_smile_id_fonts.ts

@@ -0,0 +1,71 @@
+import { useEffect, useState } from "react";
+import { DM_SANS_FONT_NAMES } from "./theme";
+
+/**
+ * Bundled DM Sans faces, keyed by the registered face name each
+ * typography token references (see `DM_SANS_FONT_NAMES`).
+ *
+ * The `require` calls live inside a function (not at module scope) so
+ * importing this module never touches the font assets — they are only
+ * resolved when a flow actually mounts and loads fonts.
+ */
+function bundledFontMap(): Record<string, number> {
+  return {
+    [DM_SANS_FONT_NAMES["400"]]:
+      require("../assets/fonts/DMSans-Regular.ttf") as number,
+    [DM_SANS_FONT_NAMES["500"]]:
+      require("../assets/fonts/DMSans-Medium.ttf") as number,
+    [DM_SANS_FONT_NAMES["600"]]:
+      require("../assets/fonts/DMSans-SemiBold.ttf") as number,
+    [DM_SANS_FONT_NAMES["700"]]:
+      require("../assets/fonts/DMSans-Bold.ttf") as number,
+    [DM_SANS_FONT_NAMES["800"]]:
+      require("../assets/fonts/DMSans-ExtraBold.ttf") as number,
+  };
+}
+
+/** Module-level so concurrent flows trigger a single load. */
+let loadPromise: Promise<void> | undefined;
+
+/**
+ * Load the bundled DM Sans faces via `expo-font`. Idempotent — repeat
+ * calls share one in-flight promise. Exported so partners who render
+ * SDK components outside `<UseSmileIDFlow>` can preload the faces.
+ */
+export function loadUseSmileIDFonts(): Promise<void> {
+  loadPromise ??= (async () => {
+    // Dynamic import keeps expo-font out of the static module graph for
+    // consumers (and tests) that never mount a flow.
+    const font = await import("expo-font");
+    await font.loadAsync(bundledFontMap());
+  })();
+  return loadPromise;
+}
+
+/**
+ * Mounts the bundled DM Sans faces for the current app session.
+ * Returns `true` once the faces are registered. Rendering does not
+ * wait for the load — until registration completes the system font
+ * renders at the same metrics, then text re-renders in DM Sans.
+ */
+export function useUseSmileIDFonts(): boolean {
+  const [loaded, setLoaded] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    loadUseSmileIDFonts()
+      .then(() => {
+        if (!cancelled) setLoaded(true);
+      })
+      .catch((error: unknown) => {
+        // Font registration must never block a verification flow — the
+        // UI falls back to the system font. Surface the cause for the
+        // integrator instead of failing silently.
+        const reason = error instanceof Error ? error.message : String(error);
+        console.warn(`UseSmileID: bundled fonts failed to load — ${reason}`);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+  return loaded;
+}