@incodetech/prizma-core-screens 0.1.0

package/src/QualifiedSignatureUploadScreen.tsx

@@ -0,0 +1,81 @@
+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 { QualifiedSignatureStrings } from './QualifiedSignatureStrings';
+import './ScreenLayout.css';
+
+export interface QualifiedSignatureUploadScreenProps
+  extends Omit<
+    PrizmaTutorialScreenProps,
+    'title' | 'subtitle' | 'disclaimer' | 'ctaLabel' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `upload` slice. */
+  strings: QualifiedSignatureStrings;
+  /** Replace the document illustration (a host may ship its own artwork). */
+  illustration?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Qualified Signature — the intro that asks for the file, built on the Tutorial
+ * archetype (GUIDELINES.md §6-A, `PrizmaTutorialScreen`).
+ *
+ * Figma: purple section `QSign.upload.default` (10196:67095). Measured off the
+ * 390 frame (CONTENT 654, `top container` 342×127): nav 8→52 · Title 68→127
+ * (nav + Spacing/24) · `illustration container` flexes · `Call to Actions`
+ * 536→638 = the primary + the Tag. Exactly the archetype's own rhythm, so this
+ * file declares no layout.
+ *
+ * The illustration is `DocumentCaptureIllustration` — NOT a fourth inline copy
+ * of the same artwork. The Figma `Illustrations` frame here is 310.47 × 325 and
+ * Document Capture's is 342 × 358: the SAME ratio to five decimals (0.90775),
+ * with the same three layers (halo ellipse `bg` · `documents` page · the
+ * `frame-border` outline), i.e. one asset drawn at two scales. Core still ships
+ * no document illustration, so the standing request stands — DEVIATIONS #DC-21
+ * asked to promote it to `PrizmaIllustrationDocument`; a second module now
+ * depends on a Document-Capture-named export, which is the strongest argument
+ * yet for the promotion.
+ *
+ * `QSign.upload.select` (10196:67173), the section between this screen and the
+ * review, is the **iOS Files app** — OS chrome, not a Prizma surface. Not built,
+ * for the reason DEVIATIONS #DC-20 settled: a screen composed only of Core
+ * components cannot render OS chrome, and faking it would ship a fake system UI.
+ * A host that needs the picker calls the platform API.
+ */
+export const QualifiedSignatureUploadScreen = forwardRef<
+  HTMLDivElement,
+  QualifiedSignatureUploadScreenProps
+>(
+  (
+    {
+      strings,
+      illustration,
+      screenId = 'qualified-signature-upload',
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaTutorialScreen
+      ref={ref}
+      title={strings.upload.title}
+      subtitle={strings.upload.subtitle}
+      disclaimer={strings.upload.disclaimer}
+      ctaLabel={strings.upload.ctaLabel}
+      illustration={illustration ?? <DocumentCaptureIllustration />}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+QualifiedSignatureUploadScreen.displayName = 'QualifiedSignatureUploadScreen';
+
+export default QualifiedSignatureUploadScreen;

package/src/ResultScreen.tsx

@@ -0,0 +1,211 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaTitle } from '@incodetech/prizma-core-web/title';
+import { PrizmaButton } from '@incodetech/prizma-core-web/button';
+import { PrizmaDisclaimer } from '@incodetech/prizma-core-web/disclaimer';
+import { PrizmaTag } from '@incodetech/prizma-core-web/tag';
+import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
+import { PrizmaScreenNav } from './ScreenNav';
+import type {
+  PrizmaScreenActionHandler,
+  PrizmaScreenChromeProps,
+  PrizmaScreenOverrides,
+} from './types';
+import './ScreenLayout.css';
+
+/** `loading` renders Core's spinner slot; the verdicts render its status mark. */
+export type PrizmaResultStatus = 'loading' | 'success' | 'error' | 'warning' | 'none';
+
+export interface PrizmaResultScreenProps
+  extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'>,
+    PrizmaScreenChromeProps {
+  /** The status mark above the title. `none` renders the title alone. */
+  status?: PrizmaResultStatus;
+  /**
+   * An optional block between the logo nav and the content — a journey stepper.
+   * Video Selfie draws Core's `PrizmaStepper` on EVERY screen of the flow, not
+   * just its camera stages, and it is the only chrome that tells the steps
+   * apart; the archetypes had a slot on E alone, so the rest of the module shed
+   * it (owner-reported 2026-08-19). Takes a `ReactNode` so the module supplies
+   * Core's own component — no primitive invented, and both offsets live once in
+   * `ScreenLayout.css` (`.prizma-screen-layout__progress`). Omit it and nothing
+   * renders, so every existing consumer is byte-identical. DEVIATIONS #VS-4.
+   */
+  progress?: ReactNode;
+  /** H2 result line ("Verification complete", "Face not aligned"). */
+  title: string;
+  /** Supporting copy below the title. */
+  subtitle?: string;
+  /**
+   * A non-status glyph ABOVE the title — Core's `PrizmaTitle.icon` allowlist is
+   * `status | spinner | none`, so anything else (a Wi-Fi mark on a connectivity
+   * error) is composed here rather than forced into the slot. DEVIATIONS #10.
+   */
+  glyph?: ReactNode;
+  /**
+   * Anything between the title block and the CTA band: a verdict Snackbar
+   * (Face Match), the captured document still (ID Capture), a hint list. Kept as
+   * a slot so one template covers every module's result screen instead of each
+   * hand-building the same skeleton.
+   */
+  children?: ReactNode;
+  /**
+   * Content that belongs INSIDE the CTA band, above the buttons — Face Match's
+   * verdict Snackbar sits there in Figma (Spacing/32 above the CTA, reached as
+   * the band's own 16 plus the slot's 16). Distinct from `children`, which sits
+   * with the centered title block.
+   */
+  bandContent?: ReactNode;
+  /**
+   * How the two CTAs sit. `stacked` (default) puts the secondary above the
+   * primary; `row` pairs them side by side, which is what ID Capture's review
+   * screen draws (Retake | Continue, ~166/163 in a 342 column).
+   */
+  ctaOrientation?: 'stacked' | 'row';
+  /** Legal/hint copy directly above the CTA. Supplies the designed 28px
+   *  text→CTA gap through its own padding (DEVIATIONS #8). */
+  disclaimer?: string;
+  /** Primary CTA. Omit for result screens that only report. */
+  ctaLabel?: string;
+  /** Secondary CTA rendered BELOW the primary (#GEO-1). */
+  secondaryCtaLabel?: string;
+  /**
+   * A tertiary underlined LINK, rendered BELOW the button stack — the position
+   * archetype A uses. Video Selfie's `14.3`/`14.4` draw "Retry" first with
+   * "Quit process" underneath; with no slot here the module had to borrow
+   * `bandContent`, which renders ABOVE the buttons and put the link on the
+   * wrong side (owner QA 2026-08-19). `bandContent` returns to its intended
+   * job (Face Match's verdict Snackbar). DEVIATIONS #VS-17.
+   */
+  linkLabel?: string;
+  /** "verified by" attribution copy for the footer tag. */
+  verifiedLabel: string;
+  navLabel?: string;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Archetype F — Result.
+ *
+ * The "centered status + CTA band + tag" recipe. It exists because three
+ * modules hand-built it independently — `FaceCaptureResultErrorScreen` (100
+ * lines), `FaceMatchResultScreen` (143) and `IdCaptureResultScreen` (198) —
+ * each differing only in what sat between the title and the CTA. Every
+ * hand-build was a fresh chance to get the spacing subtly wrong, which is
+ * exactly how the tag ended up at 0 on some screens and 16 on others.
+ *
+ * Layout: nav (or reserved row) → vertically centered title block → optional
+ * slot → CTA band (secondary, primary, disclaimer at a flat Spacing/16) →
+ * anchored footer tag. Every offset comes from ScreenLayout.css; this file
+ * declares none of its own.
+ *
+ * `ProcessingScreen` stays the pure spinner/no-CTA case; reach for this one as
+ * soon as a result screen needs a button.
+ */
+export const PrizmaResultScreen = forwardRef<HTMLDivElement, PrizmaResultScreenProps>(
+  (
+    {
+      progress,
+      status = 'none',
+      title,
+      subtitle,
+      glyph,
+      children,
+      bandContent,
+      disclaimer,
+      ctaOrientation = 'stacked',
+      ctaLabel,
+      secondaryCtaLabel,
+      linkLabel,
+      verifiedLabel,
+      navLabel,
+      screenId,
+      showHeader = true,
+      showFooter = true,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaScreenShell ref={ref} {...shell}>
+      <PrizmaScreenNav reserved={!showHeader} logo={overrides?.logo} navLabel={navLabel} />
+      {progress ? (
+        <div className="prizma-screen-layout__progress">{progress}</div>
+      ) : null}
+      <div className="prizma-screen-layout__content prizma-screen-layout__content--centered">
+        {glyph}
+        <PrizmaTitle
+          variant={overrides?.align === 'left' ? 'left' : 'centered'}
+          title={title}
+          showSubtitle={Boolean(subtitle)}
+          subtitle={subtitle}
+          icon={
+            status === 'loading'
+              ? { type: 'spinner' }
+              : status === 'none'
+                ? { type: 'none' }
+                : { type: 'status', status }
+          }
+        />
+        {children}
+      </div>
+      {ctaLabel || secondaryCtaLabel || linkLabel || disclaimer || bandContent ? (
+        <div className="prizma-screen-layout__band prizma-screen-layout__band--result">
+          {bandContent ? (
+            <div className="prizma-screen-layout__band__content">{bandContent}</div>
+          ) : null}
+          {disclaimer ? <PrizmaDisclaimer text={disclaimer} /> : null}
+          <div
+            className={
+              ctaOrientation === 'row'
+                ? 'prizma-screen-layout__band__ctas prizma-screen-layout__band__ctas--row'
+                : 'prizma-screen-layout__band__ctas'
+            }
+          >
+            {/* THE PRIMARY ALWAYS SITS ABOVE THE SECONDARY (owner rule
+                2026-08-19, DEVIATIONS #GEO-1). Not a per-screen choice and not
+                a prop — a screen never picks its own button order. `row` pairs
+                them side by side instead, where the rule does not apply. */}
+            {ctaLabel ? (
+              <PrizmaButton
+                variant="primary"
+                size="L"
+                onClick={() => onAction?.({ type: 'cta', screenId })}
+              >
+                {ctaLabel}
+              </PrizmaButton>
+            ) : null}
+            {secondaryCtaLabel ? (
+              <PrizmaButton
+                variant="secondary"
+                size="L"
+                onClick={() => onAction?.({ type: 'secondary', screenId })}
+              >
+                {secondaryCtaLabel}
+              </PrizmaButton>
+            ) : null}
+            {linkLabel ? (
+              <PrizmaButton
+                variant="tertiary-link"
+                size="L"
+                onClick={() => onAction?.({ type: 'tertiary', screenId })}
+              >
+                {linkLabel}
+              </PrizmaButton>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
+      {showFooter ? (
+        <div className="prizma-screen-layout__footer">
+          <PrizmaTag label={verifiedLabel} />
+        </div>
+      ) : null}
+    </PrizmaScreenShell>
+  ),
+);
+PrizmaResultScreen.displayName = 'PrizmaResultScreen';
+
+export default PrizmaResultScreen;

package/src/ReviewScreen.tsx

@@ -0,0 +1,196 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaTitle } from '@incodetech/prizma-core-web/title';
+import { PrizmaButtonGroup } from '@incodetech/prizma-core-web/button-group';
+import { PrizmaLoadingBar } from '@incodetech/prizma-core-web/loading-bar';
+import { PrizmaTag } from '@incodetech/prizma-core-web/tag';
+import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
+import { PrizmaScreenNav } from './ScreenNav';
+import type {
+  PrizmaScreenActionHandler,
+  PrizmaScreenChromeProps,
+  PrizmaScreenOverrides,
+} from './types';
+import './ScreenLayout.css';
+
+/**
+ * The three stages every captured-media review section shares. Identical
+ * skeleton — only the header block (Title vs loading bar), the media's own
+ * state and the presence of the CTA row change. Named to match the modules'
+ * own stage axis (`DocumentCaptureConfirmStage`, Video Selfie's review step).
+ */
+export type PrizmaReviewStage = 'review' | 'analyzing' | 'success';
+
+export interface PrizmaReviewScreenProps
+  extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'>,
+    Pick<PrizmaScreenChromeProps, 'showHeader' | 'showFooter'> {
+  /** Which review stage to render. Default `review`. */
+  stage?: PrizmaReviewStage;
+  /** H2 review/base title ("Review your document"). */
+  title: string;
+  /** Supporting copy under the title — drawn on `review` only (Figma). */
+  subtitle?: string;
+  /** Title shown on `success`; falls back to `title` when omitted. */
+  successTitle?: string;
+  /** Caption inside the loading bar on `analyzing`. */
+  analyzingLabel?: string;
+  /**
+   * Which Core `PrizmaLoadingBar` treatment the `analyzing` stage runs — the
+   * captured-photo review shows the `analyzing` sweep, the uploaded-file review
+   * shows `uploading`. Default `analyzing`.
+   */
+  analyzingState?: 'analyzing' | 'uploading';
+  /** Loading-bar progress on `analyzing`, 0–100. */
+  progress?: number;
+  /**
+   * The flexing captured-media slot: a `PrizmaIdCapture` still, an uploaded-file
+   * preview card, a portrait review. Kept a slot so one template serves every
+   * module's review screen — the module supplies the media in the right state
+   * for the stage; the archetype owns every offset around it.
+   */
+  children: ReactNode;
+  /**
+   * Extra class on the media stage for per-media adapters that Core does not
+   * own (an uploaded-file column inset, the light-surface encrypted re-tint).
+   * These shape CONTENT, never archetype spacing — the header, stage flex, CTA
+   * offset and footer all come from ScreenLayout.css regardless.
+   */
+  stageClassName?: string;
+  /** Primary CTA — the forward action. Drawn on `review` and `success`. */
+  primaryLabel: string;
+  /** Secondary CTA ("Replace" / "Retake") — drawn on `review` only. */
+  secondaryLabel?: string;
+  /** "verified by" attribution copy for the footer tag. */
+  verifiedLabel: string;
+  navLabel?: string;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Archetype H — Review (captured-media confirmation).
+ *
+ * The "header → flexing captured-media stage → CTA band → tag" recipe, with a
+ * `review → analyzing → success` stage axis. It exists because two Document
+ * Capture screens hand-built it independently (`DocumentCaptureConfirmImage`,
+ * `DocumentCaptureConfirmUpload`) with their own three-band arithmetic in
+ * `DocumentCaptureLayout.css`, and Video Selfie's review step needs the same
+ * skeleton — a captured still under a title, confirmed or replaced.
+ *
+ * It is NOT archetype F (Result): F centres a small status + CTA block, while a
+ * review TOP-aligns the header over a large media stage that flexes to fill the
+ * middle, and adds an in-flight `analyzing` state (the Title swaps for Core's
+ * `PrizmaLoadingBar` and the CTA row drops). `IdCaptureResultScreen`'s review
+ * verdict stays on F — its small on-surface still fits F's centred column, and
+ * splitting one file across two archetypes buys nothing (owner call 2026-08-18).
+ *
+ * Layout (measured off the Document Capture 390 sections, DEVIATIONS #DC-22/24):
+ * no logo nav → header block (Title or loading bar) → Spacing/32 → media stage
+ * (flexes, centred) → Spacing/24 → CTA band (`review`/`success`) → anchored
+ * VerifiedTag. `analyzing` drops the band and the stage carries the Spacing/24
+ * to the bottom itself. Every offset lives in ScreenLayout.css; this file
+ * declares none of its own.
+ */
+export const PrizmaReviewScreen = forwardRef<HTMLDivElement, PrizmaReviewScreenProps>(
+  (
+    {
+      stage = 'review',
+      title,
+      subtitle,
+      successTitle,
+      analyzingLabel,
+      analyzingState = 'analyzing',
+      progress = 0,
+      children,
+      stageClassName,
+      primaryLabel,
+      secondaryLabel,
+      verifiedLabel,
+      navLabel,
+      showHeader,
+      showFooter = true,
+      screenId,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    // Review screens are the capture family: no logo unless the client opts in
+    // by supplying one (types.ts chrome contract). `showHeader` still wins when
+    // set explicitly.
+    const withNav = showHeader ?? Boolean(overrides?.logo);
+    const showSecondary = stage === 'review' && Boolean(secondaryLabel);
+    const showBand = stage !== 'analyzing' && Boolean(primaryLabel || secondaryLabel);
+
+    return (
+      <PrizmaScreenShell ref={ref} {...shell}>
+        {withNav ? (
+          <PrizmaScreenNav logo={overrides?.logo} navLabel={navLabel} />
+        ) : null}
+        <div
+          className={[
+            'prizma-screen-layout__content',
+            withNav ? '' : 'prizma-screen-layout__content--no-nav',
+          ]
+            .filter(Boolean)
+            .join(' ')}
+        >
+          <div className="prizma-screen-layout__review-header">
+            {stage === 'analyzing' ? (
+              <div className="prizma-screen-layout__review-loading">
+                <PrizmaLoadingBar
+                  state={analyzingState}
+                  progress={progress}
+                  title={analyzingLabel}
+                />
+              </div>
+            ) : (
+              <PrizmaTitle
+                variant={overrides?.align === 'left' ? 'left' : 'centered'}
+                title={stage === 'success' ? successTitle ?? title : title}
+                showSubtitle={stage === 'review' && Boolean(subtitle)}
+                subtitle={subtitle}
+                icon={stage === 'success' ? { type: 'status', status: 'success' } : undefined}
+              />
+            )}
+          </div>
+
+          <div
+            className={[
+              'prizma-screen-layout__review-stage',
+              stage === 'analyzing' ? 'prizma-screen-layout__review-stage--flush' : '',
+              stageClassName ?? '',
+            ]
+              .filter(Boolean)
+              .join(' ')}
+          >
+            {children}
+          </div>
+
+          {showBand ? (
+            <div className="prizma-screen-layout__band prizma-screen-layout__band--review">
+              <PrizmaButtonGroup
+                orientation="horizontal-v1"
+                showSecondary={showSecondary}
+                primaryLabel={primaryLabel}
+                onPrimaryClick={() => onAction?.({ type: 'cta', screenId })}
+                secondaryLabel={secondaryLabel}
+                onSecondaryClick={() => onAction?.({ type: 'secondary', screenId })}
+              />
+            </div>
+          ) : null}
+
+          {showFooter ? (
+            <div className="prizma-screen-layout__band__tag">
+              <PrizmaTag label={verifiedLabel} />
+            </div>
+          ) : null}
+        </div>
+      </PrizmaScreenShell>
+    );
+  },
+);
+PrizmaReviewScreen.displayName = 'PrizmaReviewScreen';
+
+export default PrizmaReviewScreen;