@incodetech/prizma-core-screens 0.1.0

package/src/IdCaptureStageScreen.tsx

@@ -0,0 +1,241 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaNavigation } from '@incodetech/prizma-core-web/navigation';
+import {
+  PrizmaIdCapture,
+  type PrizmaIdCaptureState,
+} from '@incodetech/prizma-core-web/id-capture';
+import { PrizmaCaptureManual } from '@incodetech/prizma-core-web/capture-manual';
+import { PrizmaCaptureFeedback } from '@incodetech/prizma-core-web/capture-feedback';
+import { PrizmaTag } from '@incodetech/prizma-core-web/tag';
+import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type {
+  IdCaptureDocumentType,
+  IdCaptureFeedbackKind,
+  IdCaptureSide,
+  IdCaptureStageState,
+  IdCaptureStrings,
+} from './IdCaptureStrings';
+import './ScreenLayout.css';
+import './ViewfinderScreen.css';
+import './IdCaptureLayout.css';
+
+/**
+ * Purple stage state → Core `PrizmaIdCapture` state. The mapping is 1:1 except
+ * `flash`, which Figma spells "flash" and Core spells `photo-flash`.
+ */
+const CAPTURE_STATE: Record<IdCaptureStageState, PrizmaIdCaptureState> = {
+  empty: 'empty',
+  hint: 'hint',
+  filled: 'filled',
+  focused: 'focused',
+  countdown: 'countdown',
+  flash: 'photo-flash',
+  'error-wrong-side': 'error-wrong-side',
+  'error-not-aligned': 'error-not-aligned',
+  'error-blurry': 'error',
+  'error-glare': 'error-glare',
+  'error-too-dark': 'error-too-dark',
+};
+
+/**
+ * Which feedback pill each error stage carries by default (Figma
+ * `1-5-5 … 1-5-9-id-errors`, left to right). `blurry` has no frame overlay in
+ * Core — the message IS the pill (PrizmaIdCapture's `error` state is the plain
+ * red border precisely for this case, see its `error` doc comment).
+ */
+const STAGE_FEEDBACK: Partial<Record<IdCaptureStageState, IdCaptureFeedbackKind>> = {
+  'error-wrong-side': 'show-front',
+  'error-not-aligned': 'not-aligned',
+  'error-blurry': 'blurry',
+  'error-glare': 'glare',
+  'error-too-dark': 'too-dark',
+};
+
+export interface IdCaptureStageScreenProps
+  extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'> {
+  /** Module copy — this screen reads the `stage` / `feedback` slices. */
+  strings: IdCaptureStrings;
+  /** Which document is being captured — Core `PrizmaIdCapture.type`. */
+  documentType?: IdCaptureDocumentType;
+  /** Which face of a two-sided document (drives the title copy only; the frame
+   *  geometry is identical). Passports are single-sided. */
+  side?: IdCaptureSide;
+  /** Portrait document orientation — Core `PrizmaIdCapture.isVertical`. The
+   *  `ID capture ↕️ vertical` / `Passport capture ↕️ vertical` groups. */
+  vertical?: boolean;
+  /** Which purple stage section to render. */
+  state?: IdCaptureStageState;
+  /** Manual mode (`*-manual`): the shutter + the numbered tooltip appear. */
+  manual?: boolean;
+  /** Show the close control in the stage nav (Figma: present on every stage
+   *  except `*-empty`). */
+  showClose?: boolean;
+  /** Override the feedback pill the state carries by default; `null` suppresses
+   *  it (a host whose pipeline reports an error with no designed pill). */
+  feedback?: IdCaptureFeedbackKind | null;
+  /** Live camera feed (<video>) or sample still (<img>) behind the frame. */
+  camera?: ReactNode;
+  /** The captured document still (<img>) — `filled` / `flash` / error stages. */
+  still?: ReactNode;
+  /** Digit shown by the countdown Timer (`*-countdown` sections 1..3). */
+  countdownValue?: 1 | 2 | 3;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * ID Capture — the camera stage (Archetype D, GUIDELINES.md §6-D; always dark).
+ *
+ * ONE screen for ~45 purple sections: every `*-empty`, `*-hint`, `*-manual`,
+ * `*-filled`, `*-countdown`, `*-flash` and `*-errors` section of all five
+ * capture groups (`ID capture - front side`, `ID capture - back side`,
+ * `Passport capture`, `ID capture ↕️ vertical`, `Passport capture ↕️ vertical`).
+ * They are `type` × `isVertical` × `state` variants of Core's
+ * `PrizmaIdCapture`, which is exactly how the component is axed — so the frame
+ * geometry, the four border treatments, the hand-hint artwork, the Timer, the
+ * flash bloom, the glare/darkener/not-aligned overlays and the "All data is
+ * encrypted" row are ALL Core's, never re-implemented (§7).
+ *
+ * NOT built on the `PrizmaViewfinderScreen` archetype: that archetype hardcodes
+ * `CaptureOverlay` (the face/document vignette) plus its own lock-and-encrypted
+ * row, and ID Capture's stage is `PrizmaIdCapture` — which carries the document
+ * geometry AND the encrypted row itself. Wrapping the archetype would have
+ * double-drawn the reassurance line. Foundation gap reported to the owner (a
+ * `stage` slot on ViewfinderScreen); no foundation file edited. The archetype's
+ * camera-surface and HUD-typography classes ARE reused as-is
+ * (`.prizma-viewfinder__surface` / `__content` / `__title` / `__instruction`),
+ * so nothing about the dark stage is re-declared here.
+ *
+ * Spacing comes from the measured three-band recipe in `IdCaptureLayout.css`
+ * (title block bottom-anchored Spacing/40 above the frame, manual strip flush
+ * to the column's bottom padding) — no offsets are invented here, and
+ * PrizmaIdCapture's own frame→encrypted-row adjacency is left untouched
+ * (DEVIATIONS.md #12's lesson: never stack an offset a Core component carries).
+ */
+export const IdCaptureStageScreen = forwardRef<HTMLDivElement, IdCaptureStageScreenProps>(
+  (
+    {
+      strings,
+      documentType = 'id',
+      side = 'front',
+      vertical = false,
+      state = 'empty',
+      manual = false,
+      showClose = state !== 'empty',
+      feedback,
+      camera,
+      still,
+      countdownValue = 3,
+      screenId = `id-capture-${documentType}-${side}-${state}`,
+      overrides,
+      onAction,
+      className,
+      ...shell
+    },
+    ref,
+  ) => {
+    const slice =
+      documentType === 'passport'
+        ? strings.stage.passport
+        : side === 'back'
+          ? strings.stage.back
+          : strings.stage.front;
+
+    const pillKind = feedback === undefined ? STAGE_FEEDBACK[state] : feedback;
+    const pillCopy = pillKind ? strings.feedback[pillKind] : undefined;
+
+    return (
+      <PrizmaScreenShell
+        ref={ref}
+        dark
+        className={className}
+        {...shell}
+      >
+        <div className="prizma-viewfinder__surface">{camera}</div>
+        <header className="prizma-screen-nav id-capture-stage__nav">
+          <PrizmaNavigation
+            showIncodeLogo={false}
+            showRightIcon={showClose}
+            closeLabel={strings.closeLabel}
+            aria-label={strings.navLabel}
+            onRightIconClick={() => onAction?.({ type: 'secondary', screenId })}
+          />
+        </header>
+        <div
+          className={[
+            'prizma-viewfinder__content',
+            overrides?.align === 'left' ? 'prizma-viewfinder__content--left' : '',
+          ]
+            .filter(Boolean)
+            .join(' ')}
+        >
+          <div className="id-capture-band id-capture-band--top">
+            {pillKind && pillCopy ? (
+              <div className="id-capture-stage__feedback">
+                <PrizmaCaptureFeedback
+                  feedback={pillKind}
+                  title={pillCopy.title}
+                  subtitle={pillCopy.subtitle}
+                />
+              </div>
+            ) : (
+              <>
+                <h2 className="prizma-viewfinder__title">{slice.title}</h2>
+                {/* Manual mode drops the auto-capture instruction — the numbered
+                    tooltip above the shutter says what to do instead. Measured:
+                    `1-5-1-id-empty`'s Title instance is 342×59 (H2 + line) while
+                    `1-5-3-id-manual`'s is 342×28 (H2 only), both still holding
+                    the same Spacing/40 above the frame. */}
+                {slice.instruction && !manual ? (
+                  <p className="prizma-viewfinder__instruction">{slice.instruction}</p>
+                ) : null}
+              </>
+            )}
+          </div>
+          {/* `mode="overlay"` + `scrim` is Core's own recipe for exactly this
+              stage (IdCapture.tsx, integration review 0.5 finding 2): the feed
+              runs full-bleed UNDER the UI on `.prizma-viewfinder__surface` and
+              the frame is drawn on top with a TRANSPARENT window, so the
+              surround is veiled and the window shows the undimmed camera —
+              which is what the purple sections render. The `camera` slot is
+              deliberately not used in this mode. */}
+          <PrizmaIdCapture
+            type={documentType}
+            state={CAPTURE_STATE[state]}
+            isVertical={vertical}
+            mode="overlay"
+            scrim
+            countdownValue={countdownValue}
+            encryptedLabel={strings.encryptedLabel}
+            announcement={strings.stage.stateLabels?.[state]}
+            still={still}
+          />
+          <div className="id-capture-band">
+          </div>
+        </div>
+        <div className="prizma-screen-layout__capture-strip">
+        <PrizmaCaptureManual
+        className="id-capture-stage__manual"
+        variant="id-capture"
+        showButton={manual}
+        showTooltip={manual}
+        showHelpIcon
+        tooltipText={manual ? strings.stage.manualTooltip : undefined}
+        ariaLabel={strings.stage.captureLabel}
+        helpLabel={strings.stage.helpLabel}
+        onCapture={() => onAction?.({ type: 'cta', screenId })}
+        onHelp={() => onAction?.({ type: 'help', screenId })}
+        />
+        </div>
+        <div className="prizma-screen-layout__footer">
+          <PrizmaTag label={strings.verifiedLabel} />
+        </div>
+      </PrizmaScreenShell>
+    );
+  },
+);
+IdCaptureStageScreen.displayName = 'IdCaptureStageScreen';
+
+export default IdCaptureStageScreen;

package/src/IdCaptureStrings.ts

@@ -0,0 +1,228 @@
+// ID Capture module — copy contract.
+//
+// Every ID Capture screen receives the SAME `strings: IdCaptureStrings` object
+// (rule: all copy via props, no hardcoded English — GUIDELINES.md §9). The
+// object is the module's locale pack: one instance drives the whole flow, which
+// is what the FlowPlayer steps through. Sample copy lives only in previews /
+// host apps.
+//
+// Authoritative screen list: the PURPLE "screen specs" sections of the ID
+// Capture Figma file (U1EOfl9RQ1rOlOIuQw3rhL, page 16285:41282) — 13 parent
+// groups, 100 purple sections. They collapse onto 12 screens because the four
+// capture families (ID horizontal / ID vertical / passport horizontal /
+// passport vertical, front and back) are the SAME screens parameterized by
+// `PrizmaIdCapture`'s own `type` × `isVertical` × `state` axes.
+
+/** Which document the flow is capturing — Core `PrizmaIdCapture.type` minus
+ *  `poa` (that belongs to the Document Capture module, not this one). */
+export type IdCaptureDocumentType = 'id' | 'passport';
+
+/** Which face of a two-sided document. Passports are single-sided, so `back`
+ *  is only reachable for `id` (Figma: the `Passport capture` groups have no
+ *  back-side sections). */
+export type IdCaptureSide = 'front' | 'back';
+
+/**
+ * The camera-stage sub-states — one per purple `*-empty` / `*-hint` /
+ * `*-manual` / `*-filled` / `*-countdown` / `*-flash` / `*-errors` spec
+ * section. They are state/copy variants of ONE screen
+ * (IdCaptureStageScreen), not separate screens; each maps to a
+ * `PrizmaIdCaptureState`.
+ */
+export type IdCaptureStageState =
+  | 'empty'         // Figma: *-empty        — live camera, plain frame
+  | 'hint'          // Figma: *-hint         — hand-holding-document ghost
+  | 'filled'        // Figma: 1-6-1-id       — document inside the frame
+  | 'focused'       // Figma: focused frame  — detection locked
+  | 'countdown'     // Figma: *-countdown    — Timer digit inside the frame
+  | 'flash'         // Figma: *-flash        — photo-flash bloom
+  | 'error-wrong-side'
+  | 'error-not-aligned'
+  | 'error-blurry'
+  | 'error-glare'
+  | 'error-too-dark';
+
+/** The on-camera feedback pill variants the error stages carry — Core
+ *  `PrizmaCaptureFeedbackType` (Figma: `Capture feedback / ID`, and the
+ *  `Dynamic feedback messages` copy table in the front-side group). */
+export type IdCaptureFeedbackKind =
+  | 'show-front'
+  | 'show-back'
+  | 'not-aligned'
+  | 'blurry'
+  | 'glare'
+  | 'too-dark';
+
+/** One feedback pill's copy. */
+export interface IdCaptureFeedbackCopy {
+  title: string;
+  subtitle?: string;
+}
+
+/** A single row of an informational list (permission reasons, common issues,
+ *  age-verification steps) — Core `PrizmaCardListCommonIssues` rows. */
+export interface IdCaptureListRow {
+  title: string;
+  description?: string;
+}
+
+export interface IdCaptureStrings {
+  /** Accessible name for the logo nav region (i18n — no baked-in English). */
+  navLabel?: string;
+  /** Accessible name for the close control on the camera stages. */
+  closeLabel?: string;
+  /** "verified by" attribution copy for the footer tag. */
+  verifiedLabel: string;
+  /** "All data is encrypted" reassurance row — rendered by PrizmaIdCapture
+   *  itself on every stage and every screen that shows the captured still. */
+  encryptedLabel?: string;
+
+  /** Document selection — `1-1-1-id` / `1-1-1-Document Chooser V2`. */
+  documentSelection: {
+    title: string;
+    subtitle?: string;
+    /** Row label for the identity-card option. */
+    idLabel: string;
+    /** Row label for the passport option. */
+    passportLabel: string;
+  };
+
+  /** Age verification — `1-1-2-id`. */
+  ageVerification: {
+    title: string;
+    subtitle?: string;
+    /** The three reassurance rows, in order. */
+    rows: IdCaptureListRow[];
+    ctaLabel: string;
+  };
+
+  /** Tutorial — `1-2-1-id` (front) · `4-2-1-back-id` (back) · `3-2-1-id`
+   *  (passport). Copy variants of one screen; the host picks the slice. */
+  tutorial: {
+    front: { title: string; subtitle?: string };
+    back: { title: string; subtitle?: string };
+    passport: { title: string; subtitle?: string };
+    /** "The photo will be taken automatically" */
+    disclaimer?: string;
+    ctaLabel: string;
+    /** Visible/accessible copy while the CTA is loading. */
+    ctaLoadingLabel?: string;
+  };
+
+  /** Camera stage — `*-empty` / `*-hint` / `*-filled` / `*-countdown` /
+   *  `*-flash` / `*-manual` / `*-errors`. The white H2 above the frame plus
+   *  its muted instruction line, per side/document. */
+  stage: {
+    front: { title: string; instruction?: string };
+    back: { title: string; instruction?: string };
+    passport: { title: string; instruction?: string };
+    /** Manual mode — the tooltip bubble above the shutter
+     *  ("1. Fill the frame with your ID / 2. Press the button"). */
+    manualTooltip?: string;
+    /** Accessible name of the shutter button (manual mode). */
+    captureLabel?: string;
+    /** Accessible name of the "?" help control. */
+    helpLabel?: string;
+    /** Visually-hidden state announcements, per stage state — forwarded to
+     *  `PrizmaIdCapture.stateLabels`. */
+    stateLabels?: Partial<Record<IdCaptureStageState, string>>;
+  };
+
+  /** The on-camera feedback pills the error stages carry. */
+  feedback: Partial<Record<IdCaptureFeedbackKind, IdCaptureFeedbackCopy>>;
+
+  /** Analyzing / processing the captured still — `*-analyzing`. */
+  analyzing: { title: string };
+
+  /** Review the captured still — `*-review`. Two actions, no status icon. */
+  review: {
+    title: string;
+    description?: string;
+    /** Secondary action — "Retake". */
+    retakeLabel: string;
+    /** Primary action — "Continue". */
+    ctaLabel: string;
+  };
+
+  /** Capture succeeded — `*-success` / `1-10-2-id-success-capture-only`. */
+  success: {
+    title: string;
+    description?: string;
+    ctaLabel: string;
+  };
+
+  /** Capture failed with retries left / exhausted — `*-attempt`,
+   *  `*-failed-attempt`, `*-no-attempts`. The host passes the copy of the
+   *  CURRENT verdict (wrong side, glare, blur, …). */
+  error: {
+    title: string;
+    description?: string;
+    /** "1 attempt remaining" — omit on the exhausted variant. */
+    attemptsLabel?: string;
+    ctaLabel: string;
+  };
+
+  /** Classification could not decide the document — Classification Errors /
+   *  "Scan the back of your ID". Warning verdict with two actions. */
+  classification: {
+    title: string;
+    description?: string;
+    /** Primary — "Scan back of ID". */
+    ctaLabel: string;
+    /** Secondary — "ID has no back side". */
+    secondaryLabel: string;
+  };
+
+  /** Document not accepted — `1-9-12` / `1-9-13-id-documenterror` and the
+   *  `-empty` variant. */
+  documentError: {
+    title: string;
+    description?: string;
+    /** ISO country code for the bundled flag raster (e.g. "US"). */
+    countryCode?: string;
+    /** Emoji fallback for countries outside the bundled flag bank. */
+    flag?: string;
+    /** Country name shown in the accepted-documents card. */
+    country?: string;
+    /** Accepted document names, in order. */
+    documents?: string[];
+    /** Placeholder copy for the `-empty` variant (no list available). */
+    emptyMessage?: string;
+    attemptsLabel?: string;
+    ctaLabel: string;
+  };
+
+  /** Flip interstitial — `1-11-1-id-flip`. Title only, no CTA. */
+  flip: { title: string };
+
+  /** Common issues help sheet — `1-5-2-id-common-issues`. */
+  commonIssues: {
+    title: string;
+    rows: IdCaptureListRow[];
+    /** Tertiary link — "Take the photo manually". */
+    manualLabel: string;
+    ctaLabel: string;
+  };
+
+  /** Camera permission — `1-3-2-id` and its `allow-camera` /
+   *  `quit-process` copy variants. */
+  permission: {
+    title: string;
+    description?: string;
+    rows: IdCaptureListRow[];
+    /** Tertiary link — "Quit process". */
+    quitLabel: string;
+    ctaLabel: string;
+  };
+
+  /** Server-side verification wait — `1-18-1-id-hold-on`,
+   *  `1-4.1-1-id-hold-on`. */
+  holdOn: { title: string; description?: string };
+
+  /** No internet — `1-9-10-id-no-internet`. */
+  noConnection: {
+    title: string;
+    description?: string;
+    ctaLabel: string;
+  };
+}

package/src/IdCaptureTutorialScreen.tsx

@@ -0,0 +1,99 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaIllustrationIdTutorial } from '@incodetech/prizma-core-web/illustration-id-tutorial';
+import { PrizmaTutorialScreen, type PrizmaTutorialScreenProps } from './TutorialScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { IdCaptureStrings } from './IdCaptureStrings';
+import './ScreenLayout.css';
+
+/** Which purple tutorial section to render. Each is a copy + illustration
+ *  variant of this ONE screen: `1-2-1-id` (front) · `4-2-1-back-id` (back) ·
+ *  `3-2-1-id` (passport). */
+export type IdCaptureTutorialVariant = 'front' | 'back' | 'passport';
+
+/** Tutorial variant → Core `PrizmaIllustrationIdTutorial` type. */
+const ILLUSTRATION_TYPE = {
+  front: 'id-front',
+  back: 'id-back',
+  passport: 'passport',
+} as const;
+
+export interface IdCaptureTutorialScreenProps
+  extends Omit<
+    PrizmaTutorialScreenProps,
+    | 'title'
+    | 'subtitle'
+    | 'disclaimer'
+    | 'ctaLabel'
+    | 'ctaLoadingLabel'
+    | 'verifiedLabel'
+    | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `tutorial` slice (+ shared labels). */
+  strings: IdCaptureStrings;
+  /** Which purple tutorial section to render. Default `front`. */
+  variant?: IdCaptureTutorialVariant;
+  /** CTA shows the designed loading treatment (the tutorial's loading state). */
+  ctaLoading?: boolean;
+  /** Replace the default Core ID-tutorial illustration. */
+  illustration?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * ID Capture — tutorial, built on the `PrizmaTutorialScreen` archetype
+ * (GUIDELINES.md §6-A). Figma: purple sections `1-2-1-id` / `4-2-1-back-id` /
+ * `3-2-1-id` of the `Tutorial` group.
+ *
+ * Composed from the foundation pieces until the archetype grew a CTA-loading
+ * slot (#F-32) — the one thing that had forced this module, like the Face Capture
+ * pilot, to rebuild the tutorial skeleton by hand.
+ *
+ * The three illustrations are Core's `PrizmaIllustrationIdTutorial` variants,
+ * including the composed `id-back` face — never redrawn here (§7, §10).
+ */
+export const IdCaptureTutorialScreen = forwardRef<
+  HTMLDivElement,
+  IdCaptureTutorialScreenProps
+>(
+  (
+    {
+      strings,
+      variant = 'front',
+      ctaLoading = false,
+      illustration,
+      screenId = `id-capture-tutorial-${variant}`,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    const slice = strings.tutorial[variant];
+
+    return (
+      <PrizmaTutorialScreen
+        ref={ref}
+        title={slice.title}
+        subtitle={slice.subtitle}
+        disclaimer={strings.tutorial.disclaimer}
+        ctaLabel={strings.tutorial.ctaLabel}
+        ctaLoading={ctaLoading}
+        ctaLoadingLabel={strings.tutorial.ctaLoadingLabel}
+        illustration={
+          illustration ?? <PrizmaIllustrationIdTutorial type={ILLUSTRATION_TYPE[variant]} />
+        }
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        overrides={overrides}
+        onAction={onAction}
+        {...shell}
+      />
+    );
+  },
+);
+IdCaptureTutorialScreen.displayName = 'IdCaptureTutorialScreen';
+
+export default IdCaptureTutorialScreen;