@smileid/usesmileid 12.0.0-beta01

package/src/presentation/flow/dsl/builder/screens_builder.ts

@@ -0,0 +1,180 @@
+import type { ReactNode } from "react";
+import { CaptureType } from "../../../../core/models/ml_config";
+import type { DocumentType } from "../../../../core/models/document_type";
+import { DocumentCaptureMode } from "../../../../core/models/document_capture_mode";
+import type { ConsentInformation } from "../../../../core/models/params";
+import type { InstructionGuideline } from "../../model/instruction_guideline";
+import type { HeroAnimationSource } from "../../model/instructions_defaults";
+
+export { CaptureType };
+
+/**
+ * Screens DSL:
+ *
+ *   screens → consent((c) => …)
+ *           → instructions((i) => …)
+ *           → capture({ captureType }, (cap) => cap.selfie(…) | cap.document(…))
+ *           → preview((p) => …)
+ *           → processing((p) => …)
+ *
+ * Each screen-builder call appends a step to the orchestrator's
+ * `flowSteps` list in the order declared. The partner can omit
+ * screens entirely (no `screens.consent(…)` call → no consent screen).
+ */
+
+export type ButtonSlot = (props: {
+  onClick: () => void;
+  enabled: boolean;
+}) => ReactNode;
+
+// --- Per-screen builders ---------------------------------------------------
+
+export class ConsentConfigBuilder {
+  partnerName = "";
+  /** Partner brand mark rendered next to the Smile ID icon at the top of the consent screen. */
+  partnerIcon?: ReactNode;
+  partnerPrivacyPolicyUrl?: string;
+  showAttribution = true;
+  onConsentGranted?: (info: ConsentInformation) => void;
+  allowButton?: ButtonSlot;
+  denyButton?: ButtonSlot;
+}
+
+export class InstructionsConfigBuilder {
+  /** Leading title text (title-text colour). Defaults to the localized prefix. */
+  titlePrefix?: string;
+  /** Emphasized word (primary colour, own line). Defaults to the localized "selfie". */
+  titleEmphasis?: string;
+  /** Lottie hero. Unset uses the selfie hero (or the ESS hero when enhanced liveness is on). */
+  heroAnimation?: HeroAnimationSource;
+  /** Capture-guidelines section title (rendered uppercase). */
+  guidelinesSectionTitle?: string;
+  /** Capture-guideline tiles; push to customize. Empty uses the defaults. */
+  guidelines: InstructionGuideline[] = [];
+  showAttribution = true;
+  /** Draw the face-oval ring around the hero animation. */
+  showHeroOval = true;
+  continueButton?: ButtonSlot;
+}
+
+export class SelfieCaptureConfigBuilder {
+  allowAgentMode = false;
+  enableEnhancedLiveness = false;
+}
+
+export class DocumentCaptureConfigBuilder {
+  /** The document being captured. **Required** — missing it fails validation. */
+  documentType?: DocumentType;
+  /** When the photo is taken. Defaults to auto-capture with a 10s manual fallback. */
+  captureMode: DocumentCaptureMode =
+    DocumentCaptureMode.AutoCaptureWithManualFallback();
+  allowGalleryUpload = false;
+  captureBothSides = true;
+  allowSkipBack = false;
+  /** Optional aspect ratio hint — e.g. CR-80 ID card = 1.586. */
+  knownIdAspectRatio?: number;
+
+  /** The `documentType`'s aspect ratio when present, otherwise `knownIdAspectRatio`. */
+  get resolvedAspectRatio(): number | undefined {
+    return this.documentType?.knownAspectRatio ?? this.knownIdAspectRatio;
+  }
+}
+
+export class CaptureConfigBuilder {
+  captureType?: CaptureType;
+  startButton?: ButtonSlot;
+
+  private _selfie?: SelfieCaptureConfigBuilder;
+  private _document?: DocumentCaptureConfigBuilder;
+
+  selfie(block: (s: SelfieCaptureConfigBuilder) => void): void {
+    if (!this._selfie) this._selfie = new SelfieCaptureConfigBuilder();
+    block(this._selfie);
+  }
+
+  document(block: (d: DocumentCaptureConfigBuilder) => void): void {
+    if (!this._document) this._document = new DocumentCaptureConfigBuilder();
+    block(this._document);
+  }
+
+  /** @internal Snapshot used by the orchestrator. */
+  get selfieConfig(): SelfieCaptureConfigBuilder | undefined {
+    return this._selfie;
+  }
+
+  /** @internal Snapshot used by the orchestrator. */
+  get documentConfig(): DocumentCaptureConfigBuilder | undefined {
+    return this._document;
+  }
+}
+
+export class PreviewConfigBuilder {
+  allowRetake = true;
+  showAttribution = true;
+  continueButton?: ButtonSlot;
+  cancelButton?: ButtonSlot;
+}
+
+export class ProcessingConfigBuilder {
+  showProgressPercentage = true;
+  showAttribution = true;
+  continueButton?: ButtonSlot;
+  retryButton?: ButtonSlot;
+  exitButton?: ButtonSlot;
+}
+
+// --- Discriminated union the orchestrator consumes -------------------------
+
+export type ScreenSpec =
+  | { readonly kind: "consent"; readonly config: ConsentConfigBuilder }
+  | {
+      readonly kind: "instructions";
+      readonly config: InstructionsConfigBuilder;
+    }
+  | { readonly kind: "capture"; readonly config: CaptureConfigBuilder }
+  | { readonly kind: "preview"; readonly config: PreviewConfigBuilder }
+  | { readonly kind: "processing"; readonly config: ProcessingConfigBuilder };
+
+export type ScreensConfig = {
+  readonly steps: readonly ScreenSpec[];
+};
+
+// --- Top-level screens builder ---------------------------------------------
+
+export class ScreensBuilder {
+  private _steps: ScreenSpec[] = [];
+
+  consent(block?: (c: ConsentConfigBuilder) => void): void {
+    const config = new ConsentConfigBuilder();
+    block?.(config);
+    this._steps.push({ kind: "consent", config });
+  }
+
+  instructions(block?: (i: InstructionsConfigBuilder) => void): void {
+    const config = new InstructionsConfigBuilder();
+    block?.(config);
+    this._steps.push({ kind: "instructions", config });
+  }
+
+  capture(block: (c: CaptureConfigBuilder) => void): void {
+    const config = new CaptureConfigBuilder();
+    block(config);
+    this._steps.push({ kind: "capture", config });
+  }
+
+  preview(block?: (p: PreviewConfigBuilder) => void): void {
+    const config = new PreviewConfigBuilder();
+    block?.(config);
+    this._steps.push({ kind: "preview", config });
+  }
+
+  processing(block?: (p: ProcessingConfigBuilder) => void): void {
+    const config = new ProcessingConfigBuilder();
+    block?.(config);
+    this._steps.push({ kind: "processing", config });
+  }
+
+  build(): ScreensConfig {
+    return Object.freeze({ steps: Object.freeze([...this._steps]) });
+  }
+}

package/src/presentation/flow/dsl/builder/theme_builder.ts

@@ -0,0 +1,102 @@
+import {
+  DEFAULT_FONT_FAMILY,
+  defaultDarkTheme,
+  defaultLightTheme,
+  typographyWithFontFamily,
+  type UseSmileIDColors,
+  type UseSmileIDTheme,
+} from "../../../theme/theme";
+
+/** A color that adapts to the active light/dark color scheme. */
+export type AdaptiveColor = {
+  readonly light: string;
+  readonly dark: string;
+};
+
+/** Pair of resolved themes — renderer picks one based on system scheme. */
+export type ThemeConfiguration = {
+  readonly light: UseSmileIDTheme;
+  readonly dark: UseSmileIDTheme;
+};
+
+/**
+ * `b.theme((t) => { t.primaryColor = color('#1A73E8', '#4DA3FF'); })`
+ *
+ * Each color slot accepts an [AdaptiveColor] pair. Build produces a
+ * [ThemeConfiguration] carrying both resolved themes; the renderer
+ * picks light or dark at mount time based on the active color scheme.
+ */
+export class ThemeConfigBuilder {
+  primaryColor?: AdaptiveColor;
+  primaryForeground?: AdaptiveColor;
+  secondaryColor?: AdaptiveColor;
+  accentColor?: AdaptiveColor;
+
+  fontFamily?: string;
+
+  buttonShape?: number;
+  cardShape?: number;
+
+  /** Helper to create an `AdaptiveColor` with explicit light/dark values. */
+  color(light: string, dark: string): AdaptiveColor {
+    return Object.freeze({ light, dark });
+  }
+
+  /**
+   * Helper to create a button/card shape value. Returns the input
+   * radius unchanged — React Native resolves shape at render time via
+   * `borderRadius`, so the `buttonShape` / `cardShape` properties are
+   * plain numbers.
+   */
+  shape(radius: number): number {
+    return radius;
+  }
+
+  /**
+   * Build a [ThemeConfiguration] that pairs a fully-resolved light
+   * theme with its dark counterpart. Each `AdaptiveColor` override maps
+   * to its canonical key on the matching variant.
+   */
+  build(): ThemeConfiguration {
+    return Object.freeze({
+      light: this._resolve("light", defaultLightTheme),
+      dark: this._resolve("dark", defaultDarkTheme),
+    });
+  }
+
+  private _resolve(
+    variant: "light" | "dark",
+    base: UseSmileIDTheme,
+  ): UseSmileIDTheme {
+    const pick = (c: AdaptiveColor | undefined): string | undefined =>
+      c === undefined ? undefined : c[variant];
+    // Capture each picked colour once so the `!== undefined` guard narrows
+    // it to `string` — re-invoking `pick` inside the spread value would
+    // leave it `string | undefined` and trip `exactOptionalPropertyTypes`.
+    const primary = pick(this.primaryColor);
+    const primaryForeground = pick(this.primaryForeground);
+    const secondary = pick(this.secondaryColor);
+    const accent = pick(this.accentColor);
+    const colorOverrides: Partial<UseSmileIDColors> = {
+      ...(primary !== undefined ? { primary } : {}),
+      ...(primaryForeground !== undefined ? { primaryForeground } : {}),
+      ...(secondary !== undefined ? { secondary } : {}),
+      ...(accent !== undefined ? { accent } : {}),
+    };
+    return Object.freeze({
+      ...base,
+      colors: { ...base.colors, ...colorOverrides },
+      typography: typographyWithFontFamily(
+        base.typography,
+        this.fontFamily ?? DEFAULT_FONT_FAMILY,
+      ),
+      shapes: {
+        ...base.shapes,
+        ...(this.buttonShape !== undefined
+          ? { buttonRadius: this.buttonShape }
+          : {}),
+        ...(this.cardShape !== undefined ? { cardRadius: this.cardShape } : {}),
+      },
+    });
+  }
+}

package/src/presentation/flow/dsl/flow_build_result.ts

@@ -0,0 +1,37 @@
+import type { ValidationStateInvalid } from "../validation/validation_state";
+import type { FlowConfigurationSnapshot } from "./use_smile_id_flow_builder";
+
+/**
+ * Result of `useSmileIDBuilder(configure)` and the internal
+ * `UseSmileIDFlowBuilder.build()`.
+ *
+ * Discriminated on `kind`. This type is `@internal` — partners interact
+ * with `<UseSmileIDBuilder>` exclusively, which calls `build()` and
+ * dispatches on the result. The `kind: 'invalid'` case is delivered
+ * to partners as a typed `BuilderValidationException` through
+ * `onResult.failure`.
+ */
+export type FlowBuildResult = FlowBuildResultSuccess | FlowBuildResultInvalid;
+
+/**
+ * Builder produced a configuration that passed every validation rule.
+ * `<UseSmileIDBuilder>` renders this case end-to-end.
+ */
+export type FlowBuildResultSuccess = {
+  readonly kind: "success";
+  readonly configuration: FlowConfigurationSnapshot;
+};
+
+/**
+ * Builder produced at least one `error`-severity validation issue.
+ * `validation` carries the invalid branch of [ValidationState] — its
+ * `issues` array is non-empty by construction.
+ *
+ * The wrapper component that renders the failure sources `onResult` /
+ * `enableDebugMode` from the builder reference it already holds rather
+ * than from this result.
+ */
+export type FlowBuildResultInvalid = {
+  readonly kind: "invalid";
+  readonly validation: ValidationStateInvalid;
+};

package/src/presentation/flow/dsl/use_smile_id_builder.tsx

@@ -0,0 +1,123 @@
+import { useMemo } from "react";
+import {
+  FlowInvalidDispatcher,
+  FlowSuccessRenderer,
+} from "../use_smile_id_flow";
+import {
+  UseSmileIDFlowBuilder,
+  type FlowConfigurationSnapshot,
+} from "./use_smile_id_flow_builder";
+import type { FlowBuildResult } from "./flow_build_result";
+
+/**
+ * Top-level partner entry point. Configures the flow declaratively
+ * via the `builder` closure, then renders the result. The component
+ * owns the build-and-dispatch lifecycle internally — partners never
+ * touch the intermediate [FlowBuildResult].
+ *
+ *     export function VerifyScreen({ onComplete }) {
+ *       return (
+ *         <UseSmileIDBuilder
+ *           builder={(b) => {
+ *             b.network((n) => n.config((c) => {
+ *               c.jobType = JobType.smartSelfieEnrollment;
+ *               c.token = '...';
+ *               c.partnerConfig((p) => { p.partnerId = '...'; });
+ *             }));
+ *             b.ml((m) => m.analyzers((a) => {
+ *               a.forCaptureType(CaptureType.selfie, (face) => face.add(useSmileIDVisionFace));
+ *             }));
+ *             b.screens((screens) => {
+ *               screens.instructions();
+ *               screens.capture((c) => { c.captureType = CaptureType.selfie; });
+ *               screens.preview();
+ *             });
+ *             b.onResult = (result) => { ... onComplete(); };
+ *           }}
+ *         />
+ *       );
+ *     }
+ *
+ * Validation outcomes:
+ *   - Success → renders the configured screen flow.
+ *   - Invalid → fires `b.onResult.failure` with a typed
+ *     `BuilderValidationException`. Additionally renders a
+ *     debug-only `ValidationErrorScreen` when
+ *     `b.config((c) => c.enableDebugMode = true)` is set.
+ *
+ * The `builder` closure runs once when the component mounts. Partners
+ * that need to recompute the flow on prop changes should remount via
+ * a `key` prop on `<UseSmileIDBuilder>` rather than mutate the
+ * closure's captures in place.
+ */
+export type UseSmileIDBuilderProps = {
+  readonly builder: (b: UseSmileIDFlowBuilder) => void;
+};
+
+export function UseSmileIDBuilder({ builder }: UseSmileIDBuilderProps) {
+  // Builder closure intentionally runs once per mount — flow
+  // configuration is captured at first render and not meant to
+  // mutate after.
+  //
+  // `onResult` and `enableDebugMode` are snapshotted off the partial
+  // builder state into `invalidMeta` so the invalid-branch dispatcher
+  // can route the failure through the partner callback and decide
+  // whether to render the debug screen. Neither piece is recoverable
+  // from a malformed configuration alone, but they're not part of
+  // the partner-visible `FlowBuildResult` shape — that matches the
+  // single-field invalid case the other 3 SDKs ship.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const { result, invalidMeta } = useMemo(() => {
+    const flowBuilder = new UseSmileIDFlowBuilder();
+    builder(flowBuilder);
+    const built = flowBuilder.build();
+    return {
+      result: built,
+      invalidMeta: {
+        onResult: flowBuilder.onResult,
+        enableDebugMode:
+          (
+            flowBuilder as unknown as {
+              _config?: { build(): { enableDebugMode: boolean } };
+            }
+          )._config?.build().enableDebugMode === true,
+      },
+    };
+  }, []);
+  if (result.kind === "invalid") {
+    return (
+      <FlowInvalidDispatcher
+        result={result}
+        onResult={invalidMeta.onResult}
+        enableDebugMode={invalidMeta.enableDebugMode}
+      />
+    );
+  }
+  return <FlowSuccessRenderer configuration={result.configuration} />;
+}
+
+/**
+ * Function form of the builder, retained for tests and any partner
+ * code that wants to inspect the [FlowBuildResult] before rendering
+ * (for example, a custom failure UI). Most partners should use the
+ * `<UseSmileIDBuilder>` component instead.
+ *
+ * @internal
+ */
+export function useSmileIDBuilder(
+  configure: (builder: UseSmileIDFlowBuilder) => void,
+): FlowBuildResult {
+  const builder = new UseSmileIDFlowBuilder();
+  configure(builder);
+  return builder.build();
+}
+
+export {
+  UseSmileIDFlowBuilder,
+  type FlowConfigurationSnapshot,
+} from "./use_smile_id_flow_builder";
+export type {
+  FlowBuildResult,
+  FlowBuildResultSuccess,
+  FlowBuildResultInvalid,
+} from "./flow_build_result";