@incodetech/prizma-core-screens 0.1.0

package/src/DocumentCaptureMethodSelectionScreen.tsx

@@ -0,0 +1,151 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import {
+  IconCamera,
+  IconFolderFileOpen,
+  IconImage,
+  IconPaperUpload,
+} from '@incodetech/prizma-core-icons';
+import {
+  PrizmaBottomSheetContent,
+  type PrizmaActionOptionItem,
+} from '@incodetech/prizma-core-web/bottom-sheet';
+import { PrizmaTutorialScreen, type PrizmaTutorialScreenProps } from './TutorialScreen';
+import { DocumentCaptureIllustration } from './DocumentCaptureIllustration';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type {
+  DocumentCaptureMethodSelectionVariant,
+  DocumentCaptureStrings,
+} from './DocumentCaptureStrings';
+import './ScreenLayout.css';
+import './DocumentCaptureLayout.css';
+
+export interface DocumentCaptureMethodSelectionScreenProps
+  extends Omit<
+    PrizmaTutorialScreenProps,
+    | 'title'
+    | 'subtitle'
+    | 'ctaLabel'
+    | 'linkLabel'
+    | 'overlay'
+    | 'verifiedLabel'
+    | 'navLabel'
+  > {
+  /** Module copy — this screen reads `methodSelection` + `tutorial` (the sheet
+   *  is presented OVER the tutorial, which stays visible behind the scrim). */
+  strings: DocumentCaptureStrings;
+  /** `web` = the 2-row menu · `native` = the 3-row menu · `nativeUpload` = the
+   *  native menu with the camera row dropped (2 rows). */
+  method?: DocumentCaptureMethodSelectionVariant;
+  /** Replace the module's document illustration. */
+  illustration?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Document Capture — capture-method selection: the `PrizmaTutorialScreen`
+ * archetype plus a presented sheet. Figma: purple sections
+ * `documentCapture.tutorial.methodSelectionWeb` (`Bottom sheet` 390 × 172, 2
+ * rows) and `.methodSelectionNative` (390 × 262, 3 rows).
+ *
+ * The screen behind the scrim is the `tutorial.default` composition verbatim —
+ * which is now literally true: it is the same archetype call the tutorial screen
+ * makes, and only the overlay differs. The sheet rides in the archetype's
+ * `overlay` slot, a shell-level layer, because the scrim and panel are positioned
+ * against the shell and cannot live in the content column (#F-32).
+ *
+ * Core's own `PrizmaBottomSheetContent` renders the panel (handle, radius,
+ * padding, Action Option rows); the row icons come from the canonical bank.
+ * The safe presenter (`PrizmaBottomSheet`) is deliberately NOT used: it portals
+ * to `document.body`, which escapes the screen frame and the host's
+ * `transform: scale()`, and a screen is one static spec state with no open/close
+ * clock. bottom-sheet.md §10.3 assigns the scrim to "the consuming surface",
+ * and here the screen IS that surface — DEVIATIONS.md #DC-30.
+ *
+ * `documentCapture.tutorial.nativeMethodSelectionOnWeb` layers the iOS action
+ * sheet ON TOP of this one; that upper layer is OS chrome, not a Prizma
+ * surface, so it is out of scope (DEVIATIONS.md #DC-20).
+ */
+export const DocumentCaptureMethodSelectionScreen = forwardRef<
+  HTMLDivElement,
+  DocumentCaptureMethodSelectionScreenProps
+>(
+  (
+    {
+      strings,
+      method = 'web',
+      illustration,
+      screenId = `document-capture-method-selection-${method}`,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    const { methodSelection } = strings;
+    const takePhoto: PrizmaActionOptionItem = {
+      label: methodSelection.takePhotoLabel,
+      icon: <IconCamera size="m" />,
+      onClick: () => onAction?.({ type: 'cta', screenId }),
+    };
+    const cameraRoll: PrizmaActionOptionItem = {
+      label: methodSelection.cameraRollLabel,
+      icon: <IconImage size="m" />,
+      onClick: () => onAction?.({ type: 'secondary', screenId }),
+    };
+    const chooseFile: PrizmaActionOptionItem = {
+      label: methodSelection.chooseFileLabel,
+      icon: <IconFolderFileOpen size="m" />,
+      onClick: () => onAction?.({ type: 'secondary', screenId }),
+    };
+    // `nativeUpload` is `native` minus the camera row — the upload-only session
+    // cannot offer a photo, so the row is absent rather than disabled.
+    const items: PrizmaActionOptionItem[] =
+      method === 'native'
+        ? [takePhoto, cameraRoll, chooseFile]
+        : method === 'nativeUpload'
+          ? [cameraRoll, chooseFile]
+          : [
+              takePhoto,
+              {
+                label: methodSelection.uploadLabel,
+                icon: <IconPaperUpload size="m" />,
+                onClick: () => onAction?.({ type: 'secondary', screenId }),
+              },
+            ];
+
+    return (
+      <PrizmaTutorialScreen
+        ref={ref}
+        title={strings.tutorial.title}
+        subtitle={strings.tutorial.subtitle.default}
+        ctaLabel={strings.tutorial.ctaLabel.default}
+        linkLabel={strings.tutorial.skipLabel}
+        illustration={illustration ?? <DocumentCaptureIllustration />}
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        overrides={overrides}
+        overlay={
+          /* Scrim + panel own the presentation; Core owns the panel itself. */
+          <>
+            <div className="document-capture-sheet-scrim" aria-hidden="true" />
+            <div className="document-capture-sheet-panel">
+              <PrizmaBottomSheetContent
+                variant={method === 'native' ? 'menu-list-3' : 'menu-list-2'}
+                ariaLabel={methodSelection.sheetLabel}
+                items={items}
+                showBottomBar={false}
+              />
+            </div>
+          </>
+        }
+        {...shell}
+      />
+    );
+  },
+);
+DocumentCaptureMethodSelectionScreen.displayName = 'DocumentCaptureMethodSelectionScreen';
+
+export default DocumentCaptureMethodSelectionScreen;

package/src/DocumentCaptureNextPageScreen.tsx

@@ -0,0 +1,82 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaTutorialScreen, type PrizmaTutorialScreenProps } from './TutorialScreen';
+import { DocumentCaptureIllustration } from './DocumentCaptureIllustration';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { DocumentCaptureStrings } from './DocumentCaptureStrings';
+import './ScreenLayout.css';
+
+export interface DocumentCaptureNextPageScreenProps
+  extends Omit<
+    PrizmaTutorialScreenProps,
+    'title' | 'subtitle' | 'ctaLabel' | 'linkLabel' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `nextPage` slice (+ shared labels). */
+  strings: DocumentCaptureStrings;
+  /**
+   * `documentCapture.nextPage.mandatory` — the next page is required, so the
+   * "All pages captured" escape link is dropped and the subtitle changes.
+   * Default (`false`) is the `.optional` section.
+   */
+  mandatory?: boolean;
+  /** Replace the module's document illustration. */
+  illustration?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Document Capture — next document page, built on the `PrizmaTutorialScreen`
+ * archetype (GUIDELINES.md §6-A). Figma: purple sections
+ * `documentCapture.nextPage.optional` / `.mandatory` — a copy + link-slot pair of
+ * this ONE screen.
+ *
+ * Structurally the tutorial recipe (measured identical on the 390 sections:
+ * nav 8→52, Title 68→145, illustration container flexes, CTAs 472→646), which is
+ * exactly why it now renders the same archetype instead of a second copy of it.
+ * Only `.optional` shows the escape link.
+ */
+export const DocumentCaptureNextPageScreen = forwardRef<
+  HTMLDivElement,
+  DocumentCaptureNextPageScreenProps
+>(
+  (
+    {
+      strings,
+      mandatory = false,
+      illustration,
+      screenId = mandatory
+        ? 'document-capture-next-page-mandatory'
+        : 'document-capture-next-page',
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    // Figma: `.mandatory` has no escape link (every remaining page is required).
+    // Gated here too, so a host that keeps the label in its locale pack still
+    // renders the designed mandatory screen.
+    const doneLabel = mandatory ? undefined : strings.nextPage.doneLabel;
+
+    return (
+      <PrizmaTutorialScreen
+        ref={ref}
+        title={strings.nextPage.title}
+        subtitle={mandatory ? strings.nextPage.mandatorySubtitle : strings.nextPage.subtitle}
+        ctaLabel={strings.nextPage.ctaLabel}
+        linkLabel={doneLabel}
+        illustration={illustration ?? <DocumentCaptureIllustration />}
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        overrides={overrides}
+        onAction={onAction}
+        {...shell}
+      />
+    );
+  },
+);
+DocumentCaptureNextPageScreen.displayName = 'DocumentCaptureNextPageScreen';
+
+export default DocumentCaptureNextPageScreen;

package/src/DocumentCaptureNoConnectionScreen.tsx

@@ -0,0 +1,77 @@
+import React, { forwardRef } from 'react';
+import { IconWifiOff } from '@incodetech/prizma-core-icons';
+import { PrizmaResultScreen, type PrizmaResultScreenProps } from './ResultScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { DocumentCaptureStrings } from './DocumentCaptureStrings';
+import './ScreenLayout.css';
+
+export interface DocumentCaptureNoConnectionScreenProps
+  extends Omit<
+    PrizmaResultScreenProps,
+    'status' | 'title' | 'subtitle' | 'glyph' | 'ctaLabel' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `noConnection` slice. */
+  strings: DocumentCaptureStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Document Capture — no internet connection (purple section
+ * `documentCapture.errors.noConnection`), built on the `PrizmaResultScreen`
+ * archetype (GUIDELINES.md §6-F).
+ *
+ * Byte-for-byte the same spec the Face Capture pilot found in its own
+ * `genericErrors` family, which is exactly what DEVIATIONS.md #9 predicted — and
+ * exactly why all three module copies of it are now one archetype call. Header
+ * and verified tag are on per the owner's non-capture rule (#F-30).
+ *
+ * The glyph is Figma's `Icon / Wi-Fi` in the archetype's `glyph` slot with the
+ * foundation's `__glyph` class, which replaced this module's byte-identical
+ * `.document-capture-glyph` copy (DEVIATIONS #10, #DC-29 — closed).
+ */
+export const DocumentCaptureNoConnectionScreen = forwardRef<
+  HTMLDivElement,
+  DocumentCaptureNoConnectionScreenProps
+>(
+  (
+    {
+      strings,
+      screenId = 'document-capture-no-connection',
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaResultScreen
+      ref={ref}
+      glyph={
+        <span
+          className={[
+            'prizma-screen-layout__glyph',
+            'prizma-screen-layout__glyph--negative',
+            overrides?.align === 'left' ? 'prizma-screen-layout__glyph--left' : '',
+          ]
+            .filter(Boolean)
+            .join(' ')}
+        >
+          <IconWifiOff size="l" />
+        </span>
+      }
+      title={strings.noConnection.title}
+      subtitle={strings.noConnection.description}
+      ctaLabel={strings.noConnection.ctaLabel}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+DocumentCaptureNoConnectionScreen.displayName = 'DocumentCaptureNoConnectionScreen';
+
+export default DocumentCaptureNoConnectionScreen;

package/src/DocumentCaptureStrings.ts

@@ -0,0 +1,192 @@
+// Document Capture module — copy contract.
+//
+// Every Document Capture screen receives the SAME
+// `strings: DocumentCaptureStrings` 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
+// Document Capture Figma file (cbFXiChmJ8cWQDHwVghBqJ, page 4094:15561) —
+// tutorial (4 purple variants + 3 method-selection variants) · commonIssues ·
+// nextPage (optional / mandatory) · capture (default / filled) · confirmImage
+// (reviewPhoto / analyzing / success) · confirmUpload (reviewFile / analyzing /
+// success + 2 native picker specs) · errors (noConnection / genericError /
+// genericErrorExhausted).
+//
+// FOUR purple variants document OS-NATIVE chrome, not Prizma screens, and are
+// therefore NOT part of this contract (DEVIATIONS.md #DC-20):
+// `tutorial.uploadOnlySelector`, `tutorial.nativeMethodSelectionOnWeb`,
+// `upload.selectFromLibrary`, `upload.selectFromFiles`.
+
+/**
+ * Which purple `documentCapture.tutorial.*` intro variant to render. They are
+ * copy variants of ONE screen (DocumentCaptureTutorialScreen) — the layout is
+ * identical; only the subtitle and the CTA label change with the capture
+ * methods the session enables.
+ */
+export type DocumentCaptureTutorialVariant =
+  /** `tutorial.default` — camera AND upload allowed ("Continue"). */
+  | 'default'
+  /** `tutorial.captureOnly` — camera only ("Capture document"). */
+  | 'captureOnly'
+  /** `tutorial.uploadOnly` — upload only ("Upload document"). */
+  | 'uploadOnly';
+
+/**
+ * Which `documentCapture.tutorial.methodSelection*` sheet to render.
+ *
+ *   web          — the 2-row menu: Take photo · Upload document (menu-list-2)
+ *   native       — the 3-row menu: Take photo · Camera roll · Choose file
+ *                  (menu-list-3)
+ *   nativeUpload — the same native menu with the camera row DROPPED, so 2 rows:
+ *                  Camera roll · Choose file (menu-list-2)
+ *
+ * `nativeUpload` has no purple spec section of its own. It comes off the iOS
+ * full flow (`cbFXiChmJ8cWQDHwVghBqJ`, node 4415:38025), where the upload-only
+ * leg presents a `methodSelectionNative` instance whose sheet measures 206 tall
+ * against the spec'd 262 — exactly one row less, with "Take photo" hidden,
+ * because a session that does not allow the camera cannot offer it. The flow is
+ * right and the spec set is one variant short; recorded as such rather than
+ * quietly rendering the 3-row sheet in a flow that forbids the camera.
+ * Flagged for the owner: 2026-09-02, Camila.
+ */
+export type DocumentCaptureMethodSelectionVariant = 'web' | 'native' | 'nativeUpload';
+
+/**
+ * The three purple states shared by `confirmImage.*` and `confirmUpload.*`.
+ * Identical layout, identical stage — only the header block (title vs loading
+ * bar), the stage verdict and the CTA row change.
+ */
+export type DocumentCaptureConfirmStage = 'review' | 'analyzing' | 'success';
+
+/** One `commonIssues` row: an H5 title + a Body/M description. */
+export interface DocumentCaptureIssueStrings {
+  title: string;
+  description?: string;
+}
+
+export interface DocumentCaptureStrings {
+  /** Accessible name for the logo nav region (i18n — no baked-in English). */
+  navLabel?: string;
+  /** "verified by" attribution copy for the footer tag. */
+  verifiedLabel: string;
+  /** "All data is encrypted" reassurance row under every capture / review
+   *  stage. Omit to drop the row (Core's `showEncryptedLabel` boolean). */
+  encryptedLabel?: string;
+
+  /** documentCapture.tutorial.default / .captureOnly / .uploadOnly — the
+   *  subtitle and CTA label are per-variant; everything else is shared. */
+  tutorial: {
+    title: string;
+    /** Per-variant description (H5). */
+    subtitle: Record<DocumentCaptureTutorialVariant, string>;
+    /** Per-variant primary CTA ("Continue" / "Capture document" / …). */
+    ctaLabel: Record<DocumentCaptureTutorialVariant, string>;
+    /** Tertiary link under the CTA ("Skip this step"). Omit to drop it. */
+    skipLabel?: string;
+  };
+
+  /** documentCapture.tutorial.methodSelectionWeb / .methodSelectionNative —
+   *  the action rows of the capture-method sheet. `web` shows the first two,
+   *  `native` all three. */
+  methodSelection: {
+    /** Accessible name of the sheet (Core requires it on the menu variants). */
+    sheetLabel: string;
+    /** "Take photo" */
+    takePhotoLabel: string;
+    /** "Upload document" (web) */
+    uploadLabel: string;
+    /** "Choose from camera roll" (native only) */
+    cameraRollLabel: string;
+    /** "Choose file" (native only) */
+    chooseFileLabel: string;
+  };
+
+  /** documentCapture.commonIssues.default */
+  commonIssues: {
+    title: string;
+    /** The four rows, in Figma order: out of frame · folded · shadows ·
+     *  dirty lens. Icons come from the canonical bank, not from copy
+     *  (DEVIATIONS.md #DC-23). */
+    issues: readonly DocumentCaptureIssueStrings[];
+    /** "Try again" */
+    ctaLabel: string;
+  };
+
+  /** documentCapture.nextPage.optional / .mandatory */
+  nextPage: {
+    title: string;
+    /** `optional` subtitle ("If there's another page…"). */
+    subtitle: string;
+    /** `mandatory` subtitle ("Take a photo of the next page to continue."). */
+    mandatorySubtitle: string;
+    /** "Next page" */
+    ctaLabel: string;
+    /** "All pages captured" — the tertiary link, `optional` only. */
+    doneLabel?: string;
+  };
+
+  /** documentCapture.capture.default / .filled — the dark camera stage. */
+  capture: {
+    /** White H2 above the frame ("Show your full document"). */
+    title: string;
+    /** Muted instruction under it. */
+    subtitle?: string;
+    /** Accessible name of the shutter button. */
+    captureLabel: string;
+    /** Accessible name of the "?" help control. */
+    helpLabel: string;
+  };
+
+  /** documentCapture.confirmImage.reviewPhoto / .analyzing / .success */
+  confirmImage: {
+    /** `review` title ("Review your document"). */
+    title: string;
+    /** `review` description. */
+    subtitle?: string;
+    /** Loading-bar caption on `analyzing` ("Analyzing..."). */
+    analyzingLabel: string;
+    /** H2 on `success` ("Successfully processed!"). */
+    successTitle: string;
+    /** Secondary CTA on `review` ("Replace"). */
+    replaceLabel: string;
+    /** Primary CTA on `review` / `success` ("Continue"). */
+    ctaLabel: string;
+  };
+
+  /** documentCapture.confirmUpload.reviewFile / .analyzing / .success */
+  confirmUpload: {
+    /** `review` title ("Review your document"). */
+    title: string;
+    /** `review` description. */
+    subtitle?: string;
+    /** Loading-bar caption on `analyzing` ("Uploading..."). */
+    analyzingLabel: string;
+    /** H2 on `success` ("Successfully processed!"). */
+    successTitle: string;
+    /** Secondary CTA on `review` ("Replace"). */
+    replaceLabel: string;
+    /** Primary CTA on `review` / `success` ("Continue"). */
+    ctaLabel: string;
+  };
+
+  /** documentCapture.errors.genericError / .genericErrorExhausted — the host
+   *  passes the copy of the CURRENT verdict; the exhausted variant changes
+   *  icon + copy + CTA through the same slice. */
+  error: {
+    title: string;
+    description?: string;
+    /** "2 attempts remaining" — omit on the exhausted variant. */
+    attemptsLabel?: string;
+    /** "Recapture document" / "Continue" */
+    ctaLabel: string;
+  };
+
+  /** documentCapture.errors.noConnection */
+  noConnection: {
+    title: string;
+    description?: string;
+    ctaLabel: string;
+  };
+}

package/src/DocumentCaptureTutorialScreen.tsx

@@ -0,0 +1,79 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaTutorialScreen, type PrizmaTutorialScreenProps } from './TutorialScreen';
+import { DocumentCaptureIllustration } from './DocumentCaptureIllustration';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type {
+  DocumentCaptureStrings,
+  DocumentCaptureTutorialVariant,
+} from './DocumentCaptureStrings';
+import './ScreenLayout.css';
+
+export interface DocumentCaptureTutorialScreenProps
+  extends Omit<
+    PrizmaTutorialScreenProps,
+    'title' | 'subtitle' | 'ctaLabel' | 'linkLabel' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `tutorial` slice (+ shared labels). */
+  strings: DocumentCaptureStrings;
+  /** Which purple `documentCapture.tutorial.*` intro section to render. */
+  variant?: DocumentCaptureTutorialVariant;
+  /** Replace the module's document illustration. */
+  illustration?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Document Capture — tutorial, built on the `PrizmaTutorialScreen` archetype
+ * (GUIDELINES.md §6-A). Figma: purple sections
+ * `documentCapture.tutorial.default` / `.captureOnly` / `.uploadOnly` — copy
+ * variants of this ONE screen (subtitle + CTA label).
+ *
+ * Measured off the 390 sections (CONTENT 654 tall, `px-24 py-8`):
+ * nav 8→52 · Title 68→127 (nav + Spacing/24) · illustration container flexes ·
+ * CTAs 472→646 = primary + the "Skip this step" tertiary link + Tag.
+ *
+ * There is NO disclaimer on any Document Capture tutorial variant — the slot
+ * GUIDELINES §6-A reserves is simply unused.
+ *
+ * It used to hand-build the shell because the archetype hardcoded a single
+ * `PrizmaButton` with no link slot. The archetype now carries `linkLabel` (#F-32);
+ * the link's gap above the tag comes from the band's flat Spacing/16 rather than
+ * `PrizmaButtonGroup`'s Spacing/12, a 4px consolidation logged as #F-32.
+ */
+export const DocumentCaptureTutorialScreen = forwardRef<
+  HTMLDivElement,
+  DocumentCaptureTutorialScreenProps
+>(
+  (
+    {
+      strings,
+      variant = 'default',
+      illustration,
+      screenId = `document-capture-tutorial-${variant}`,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaTutorialScreen
+      ref={ref}
+      title={strings.tutorial.title}
+      subtitle={strings.tutorial.subtitle[variant]}
+      ctaLabel={strings.tutorial.ctaLabel[variant]}
+      linkLabel={strings.tutorial.skipLabel}
+      illustration={illustration ?? <DocumentCaptureIllustration />}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+DocumentCaptureTutorialScreen.displayName = 'DocumentCaptureTutorialScreen';
+
+export default DocumentCaptureTutorialScreen;