@incodetech/prizma-core-screens 0.2.4 → 0.2.12

package/src/VideoSelfieTutorialScreen.tsx

@@ -1,15 +1,15 @@
 import React, { forwardRef, type ReactNode } from 'react';
 import {
   IconBankCard,
-  IconIdFront,
   IconMessages,
   IconMicrophone,
   IconNumberedList,
-  IconPassport,
+  IconPassportCapture,
   IconUser,
+  IconUserInformation,
   IconWavingHand,
 } from '@incodetech/prizma-core-icons';
-import { PrizmaListItem } from '@incodetech/prizma-core-web/list';
+import { PrizmaList } from '@incodetech/prizma-core-web/list';
 import { PrizmaListScreen, type PrizmaListScreenProps } from './ListScreen';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
 import type {
@@ -18,6 +18,7 @@ import type {
   VideoSelfieTutorialRowKind,
 } from './VideoSelfieStrings';
 import './ScreenLayout.css';
+import './VideoSelfieLayout.css';
 
 /**
  * Journey beat → canonical bank glyph. ONE map, in one place — the same seven
@@ -27,9 +28,13 @@ import './ScreenLayout.css';
  */
 const ROW_ICONS: Record<VideoSelfieTutorialRowKind, ReactNode> = {
   recording: <IconMicrophone size="m" />,
-  idFront: <IconIdFront size="m" />,
+  // `user-information` and `passport-capture`, NOT `id-front` and `passport`:
+  // the tutorial promises the steps the Stepper then counts off, and the
+  // Stepper's own sequence uses these two. Corrected 2026-09-30 — the tutorial
+  // was drawing a different ID glyph from the one the journey shows.
+  idFront: <IconUserInformation size="m" />,
   idBack: <IconBankCard size="m" />,
-  passport: <IconPassport size="m" />,
+  passport: <IconPassportCapture size="m" />,
   frontCamera: <IconUser size="m" />,
   waveHand: <IconWavingHand size="m" />,
   questions: <IconNumberedList size="m" />,
@@ -74,6 +79,14 @@ export interface VideoSelfieTutorialScreenProps
  * NOT archetype A: A centres one illustration in the flexible middle; here the
  * middle is a seven-row list that must span the column and start at the top —
  * the distinction `ScreenLayout.css` draws between `__flex` and `__list`.
+ *
+ * The one class it carries, `video-selfie-tutorial`, exists so the module's
+ * stylesheet can reach this screen on a SHORT panel: seven rows fit the 844
+ * reference to the pixel (measured 497 of 497), and on a 640 or 693 one they
+ * paint straight through the CTA. `VideoSelfieLayout.css` lets them pan there,
+ * the same concession the Android settings walk-through already makes with
+ * `scrollList` — and `scrollList` itself is not used here because its
+ * Spacing/16 margin would take the reference below the 497 the rows need.
  */
 export const VideoSelfieTutorialScreen = forwardRef<
   HTMLDivElement,
@@ -86,12 +99,14 @@ export const VideoSelfieTutorialScreen = forwardRef<
       screenId = `video-selfie-tutorial-${documentType}`,
       overrides,
       onAction,
+      className,
       ...shell
     },
     ref,
   ) => (
     <PrizmaListScreen
       ref={ref}
+      className={['video-selfie-tutorial', className].filter(Boolean).join(' ')}
       title={strings.tutorial.title}
       subtitle={strings.tutorial.subtitle}
       ctaLabel={strings.tutorial.ctaLabel}
@@ -102,25 +117,32 @@ export const VideoSelfieTutorialScreen = forwardRef<
       onAction={onAction}
       {...shell}
     >
-      {/* Core's LIST-WITH-ICON rows. `1.0`/`1.2` draw the steps as plain
-          icon + label rows with NO card surface behind them, so
-          `PrizmaCardListCommonIssues` was wrong — it gave every row a tinted
-          card the design does not have (owner-reported 2026-08-19).
+      {/* Core's `PrizmaList`, `icons-chain` — the stepper-style list: a 40
+          squircle per step with a 2×8 connector running down to the next one,
+          which is exactly what `1.0` and `1.2` draw (`List` → `List item` →
+          `Icon / List item` → `stepIcon` + `bottomConnector`).
 
-          The rows are Core's `PrizmaListItem` (`icon-m`), composed directly
-          rather than through `PrizmaList`: the wrapper's icon variants cap at
-          SIX slots and silently drop the rest, and this tutorial draws SEVEN
-          steps. The <ul> carries only the variant's own Spacing/12 rhythm —
-          no new value. CORE REQUEST: let `PrizmaList`'s icon variants take a
-          seventh row. DEVIATIONS #VS-8.
-       */}
-      <ul className="video-selfie-tutorial-list">
-        {strings.tutorial.rows[documentType].map((row) => (
-          <li key={row.kind}>
-            <PrizmaListItem variant="icon-m" label={row.label} icon={ROW_ICONS[row.kind]} />
-          </li>
-        ))}
-      </ul>
+          It used to be a hand-rolled <ul> of bare `PrizmaListItem`s, for two
+          reasons that are both gone: the icon LIST variants capped at six
+          slots and this tutorial draws seven, and no list variant paired with
+          the `icon-connector` ROW variant at all, so a stepper list could
+          only be numbered. `icons-chain` was added to Core on 2026-09-30 with
+          seven slots, and closes both (#VS-8, #VS-16). The list declares no
+          layout of its own here — the rhythm, the squircle and the connector
+          are the variant's. */}
+      <PrizmaList
+        variant="icons-chain"
+        showItem3
+        showItem4
+        showItem5
+        showItem6
+        showItem7
+        items={strings.tutorial.rows[documentType].map((row) => ({
+          variant: 'icon-connector' as const,
+          label: row.label,
+          icon: ROW_ICONS[row.kind],
+        }))}
+      />
     </PrizmaListScreen>
   ),
 );

package/src/VideoSelfieWaveScreen.tsx

@@ -0,0 +1,143 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaModalContent } from '@incodetech/prizma-core-web/modal';
+import { PrizmaSelfieCapture } from '@incodetech/prizma-core-web/selfie-capture';
+import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { VideoSelfieDocumentType, VideoSelfieStrings } from './VideoSelfieStrings';
+import './ScreenLayout.css';
+import './ViewfinderScreen.css';
+import './VideoSelfieLayout.css';
+
+/** The three beats the `👋 Wave` band draws. */
+export type VideoSelfieWaveStage = 'waiting' | 'ready' | 'success';
+
+export interface VideoSelfieWaveScreenProps
+  extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'> {
+  /** Module copy — this screen reads `selfieCapture.wave`. */
+  strings: VideoSelfieStrings;
+  /** Which beat to render. Default `waiting`. */
+  stage?: VideoSelfieWaveStage;
+  /** Which document the journey collects — the Stepper's own `documentType`. */
+  documentType?: VideoSelfieDocumentType;
+  /** Live camera feed (<video>) or sample still (<img>), full-bleed behind
+   *  the ring. */
+  camera?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Video Selfie — the hand-wave beat of the liveness sequence (Archetype D,
+ * GUIDELINES.md §6-D; always dark). NEW 2026-09-30, from the `👋 Wave` band of
+ * the full-flow frames; like the head turns, it had no screen at all.
+ *
+ * The composition is the liveness ring with the spoken steps' card under it:
+ * the feed runs full-bleed, the ring frames the face, and Core's Modal asks
+ * for the gesture with a CTA that only lights up once the stage has seen it
+ * (the frames' "5 second delay" note between the two). The verdict beat is the
+ * ring's own positive treatment plus the module's "Looking good!" — the SAME
+ * copy and the same mark `8.2` uses, because it is the same answer.
+ *
+ * The scrim/panel positioning is the recipe Document Capture's method sheet
+ * established (DEVIATIONS #DC-30): Core's safe presenter portals to
+ * `document.body`, which would escape the 390×844 frame and the host's
+ * `transform: scale()`, so the screen owns the panel and Core owns the card.
+ * The card is pinned back to LIGHT inside the dark shell for the reason
+ * `VideoSelfieSpeakScreen` documents (#VS-10).
+ *
+ * The hand that sweeps across the face is Core's, not this screen's:
+ * `PrizmaSelfieCapture` grew a `hint="wave"` axis on 2026-09-30 (owner: "we
+ * need the hand wave"), the face counterpart of `PrizmaIdCapture`'s animated
+ * hand hint, so the art and the choreography live where every other capture
+ * gesture already lives. The screen only says WHEN: the hand runs while the
+ * stage is waiting and stops the moment the wave has landed, which is the
+ * frames' own "5 second delay · Remove animation (Accessibility)" note.
+ * DEVIATIONS #VS-21.
+ */
+export const VideoSelfieWaveScreen = forwardRef<HTMLDivElement, VideoSelfieWaveScreenProps>(
+  (
+    {
+      strings,
+      stage = 'waiting',
+      documentType = 'id',
+      camera,
+      screenId = `video-selfie-wave-${stage}`,
+      overrides,
+      onAction,
+      className,
+      ...shell
+    },
+    ref,
+  ) => {
+    const slice = strings.selfieCapture.wave;
+    const seen = stage === 'success';
+
+    return (
+      <PrizmaScreenShell
+        ref={ref}
+        dark
+        /* The camera owns the whole window, never a column of it — see the
+           contract note in `VideoSelfieLayout.css`. */
+        data-pcs-overlay="window"
+        className={className}
+        {...shell}
+      >
+        <div className="prizma-viewfinder__surface">{camera}</div>
+        <div className="video-selfie-stepper">
+          <PrizmaStepper
+            steps={7}
+            currentState={5}
+            documentType={documentType}
+            completedValueText={strings.stepperCompletedLabel}
+          />
+        </div>
+        <div
+          className={[
+            'prizma-viewfinder__content',
+            overrides?.align === 'left' ? 'prizma-viewfinder__content--left' : '',
+          ]
+            .filter(Boolean)
+            .join(' ')}
+        >
+          <div className="video-selfie-band video-selfie-band--ring">
+            <PrizmaSelfieCapture
+              mode="overlay"
+              scrim
+              state={seen ? 'success' : 'filled'}
+              /* The hand demonstrates the gesture only while the stage is
+                 still waiting for it. On `ready` the wave has landed and the
+                 CTA lights up instead — the frames drop the animation at
+                 exactly that beat. */
+              hint={stage === 'waiting' ? 'wave' : undefined}
+              showFeedback={false}
+              statusLabels={{ success: strings.selfieCapture.successLabel }}
+            />
+          </div>
+        </div>
+        {/* The card is gone on the verdict beat — the ring and the mark are the
+            whole answer there, exactly as the band's last frame draws it. */}
+        {seen ? null : (
+          <div data-prizma-theme="light" className="video-selfie-sheet-panel">
+            <PrizmaModalContent
+              title={slice.instruction}
+              showCloseIcon={false}
+              buttonGroupProps={{
+                orientation: 'vertical-v1',
+                showPrimary: true,
+                showSecondary: false,
+                primaryLabel: slice.doneLabel,
+                primaryDisabled: stage !== 'ready',
+                onPrimaryClick: () => onAction?.({ type: 'cta', screenId }),
+              }}
+            />
+          </div>
+        )}
+      </PrizmaScreenShell>
+    );
+  },
+);
+VideoSelfieWaveScreen.displayName = 'VideoSelfieWaveScreen';
+
+export default VideoSelfieWaveScreen;

package/src/ViewfinderScreen.css

@@ -13,6 +13,42 @@
   object-fit: cover;
 }
 
+/* ── A feed has an ASPECT, and the plate has to match it ─────────────────────
+ * `object-fit: cover` is right for a live feed and wrong for a still: a phone
+ * plate is 390 x 844, and covering a 1440 x 820 browser window scales it 3.7x,
+ * so the subject fills the window and her face lands nowhere near the capture
+ * ring (Camila, 2026-10-09: "the image is now too zoomed in because full screen
+ * is not good for this image ratio"). A real desktop webcam does not hand the
+ * page a portrait frame; it hands it a landscape one.
+ *
+ * So the HOST may supply two plates and the viewfinder picks the one whose
+ * shape fits the shell it is actually being drawn at:
+ *
+ *   <div className="prizma-viewfinder__surface">
+ *     <img data-pcs-plate="tall" src={portrait} alt="" />
+ *     <img data-pcs-plate="wide" src={landscape} alt="" />
+ *   </div>
+ *
+ * Supply one and nothing changes — an untagged `<img>` or `<video>` is shown at
+ * every shape, which is every existing caller. A CONTAINER query, not a media
+ * one, for the reason `ScreenLayout.css` gives on the capture notice: the
+ * browser viewport is not the screen, and in Core Lab a 390 shell sits inside a
+ * 1400px window. The line is square: anything wider than it is tall takes the
+ * landscape plate. */
+.prizma-viewfinder__surface > [data-pcs-plate='wide'] {
+  display: none;
+}
+
+@container pcs-screen (min-aspect-ratio: 1 / 1) {
+  .prizma-viewfinder__surface > [data-pcs-plate='tall'] {
+    display: none;
+  }
+
+  .prizma-viewfinder__surface > [data-pcs-plate='wide'] {
+    display: block;
+  }
+}
+
 .prizma-viewfinder__content {
   position: relative;
   z-index: 1;

package/src/WatchlistBusinessFormScreen.tsx

@@ -41,8 +41,9 @@ export interface WatchlistBusinessFormScreenProps
  * (GUIDELINES.md §6-E, `PrizmaFormScreen`).
  *
  * ONE screen for both purple form sections (`watchlist.default` and
- * `watchlist.filled`): measured against the 390 frames they share an identical
- * skeleton — nav → Title (H2, no subtitle) → Spacing/32 → Country dropdown,
+ * `watchlist.filled`), plus the `emptyError` state the GUIDELINES §6-E
+ * empty-submit rule adds (Elena 2026-09-30, see note 3): measured against the 390 frames they share an identical
+ * skeleton — nav → Title (H2 + the "fields marked with *" H5) → Spacing/32 → Country dropdown,
  * Business Name and Tax ID at Spacing/16 → primary CTA → tag — and differ ONLY
  * in field content and whether the CTA is live.
  *
@@ -57,11 +58,14 @@ export interface WatchlistBusinessFormScreenProps
  *    and Core's `readOnly`, the other way to make a field inert, paints the
  *    DISABLED grey surface on states Figma draws white (DEVIATIONS #PI-6).
  *    Neither section greys anything, so `disabled` is set nowhere.
- * 3. The CTA state comes from the SECTION, not from the values: Figma greys
- *    "Continue" on `default` and lights it on `filled` — and `filled` leaves Tax
- *    ID empty, which is how we know the tax identifier does not gate the lookup
- *    (DEVIATIONS #WB-2). Deriving `ctaDisabled` from the values would have
- *    disagreed with the design.
+ * 3. The CTA state comes from the SECTION, not from the values. Under the
+ *    GUIDELINES §6-E empty-submit rule (Elena 2026-09-30) "Continue" is live
+ *    on the resting `default` form, so the user can press it, and greys ONLY
+ *    on `emptyError`, the state that press leads to: Country and Business
+ *    Name render empty (no placeholder) in Core's error state with
+ *    `requiredError`. Tax ID never errors — `filled` leaves it empty with the
+ *    CTA live, which is how we know it does not gate the lookup (DEVIATIONS
+ *    #WB-2).
  * 4. The country flag is Core's canonical raster (24×18, radius 2) in the
  *    dropdown's LEADING slot — `PrizmaCountryFlag` composed into
  *    `PrizmaDropdown.renderLeading`, which exists for exactly this case and
@@ -95,9 +99,11 @@ export const WatchlistBusinessFormScreen = forwardRef<
     ref,
   ) => {
     const copy = strings.form;
-    // `default` draws the CTA greyed, `filled` draws it live. The section is the
-    // spec, not the field contents (see note 3 above).
-    const empty = state === 'default';
+    // The CTA greys only after an empty submit; the resting form keeps it live
+    // so that submit can happen. The section is the spec, not the field
+    // contents (see note 3 above).
+    const emptyError = state === 'emptyError';
+    const errorText = emptyError ? strings.requiredError : undefined;
 
     // The label is the country NAME only. The flag is not part of it — it rides
     // the dropdown's leading slot below, where Core paints the raster.
@@ -112,7 +118,7 @@ export const WatchlistBusinessFormScreen = forwardRef<
         title={copy.title}
         subtitle={copy.subtitle}
         ctaLabel={copy.ctaLabel}
-        ctaDisabled={empty}
+        ctaDisabled={emptyError}
         ctaLoadingLabel={copy.ctaLoadingLabel}
         /* Figma draws no verified tag on either form section, but GUIDELINES §1
            and the standing owner rule (#F-30, #PI-8) keep header AND footer on
@@ -127,9 +133,17 @@ export const WatchlistBusinessFormScreen = forwardRef<
       >
         <PrizmaDropdown
           label={copy.country.label}
-          placeholder={copy.country.placeholder}
+          /* Country and Business Name are required and marked (Elena,
+             2026-09-30); the H5 explains the asterisk. */
+          required
+          requiredHint={strings.requiredHint}
+          /* The empty-submit error draws the field with nothing in it, as the
+             `FormsFieldScreen` `emptyError` precedent does. */
+          placeholder={emptyError ? undefined : copy.country.placeholder}
           options={options}
-          defaultValue={values?.country ?? null}
+          defaultValue={emptyError ? null : (values?.country ?? null)}
+          error={emptyError}
+          errorText={errorText}
           /* A country catalogue is long enough that Core's own search bar is
              the right behaviour; no purple section draws the menu open, so
              nothing about its appearance is being invented here. */
@@ -155,9 +169,13 @@ export const WatchlistBusinessFormScreen = forwardRef<
         />
         <PrizmaTextField
           label={copy.businessName.label}
-          placeholder={copy.businessName.placeholder}
+          required
+          requiredHint={strings.requiredHint}
+          placeholder={emptyError ? undefined : copy.businessName.placeholder}
           autoComplete="organization"
-          defaultValue={values?.businessName ?? ''}
+          defaultValue={emptyError ? '' : (values?.businessName ?? '')}
+          error={emptyError}
+          errorText={errorText}
         />
         <PrizmaTextField
           label={copy.taxId.label}
@@ -165,7 +183,8 @@ export const WatchlistBusinessFormScreen = forwardRef<
           autoComplete="off"
           autoCapitalize="characters"
           spellCheck={false}
-          defaultValue={values?.taxId ?? ''}
+          /* Optional (#WB-2): an empty submit leaves it clean. */
+          defaultValue={emptyError ? '' : (values?.taxId ?? '')}
         />
       </PrizmaFormScreen>
     );

package/src/WatchlistBusinessStrings.ts

@@ -23,15 +23,18 @@
  * in field content and whether the CTA is live, which is exactly what
  * GUIDELINES §6-E means by "states are separate screens sharing the identical
  * layout":
- * - `default` — every field empty (the country dropdown on its placeholder),
- *   CTA greyed
- * - `filled`  — country selected and business name typed, CTA live
+ * - `default`    — every field empty (the country dropdown on its placeholder),
+ *   CTA live so the user can press it (GUIDELINES §6-E empty-submit rule)
+ * - `filled`     — country selected and business name typed, CTA live
+ * - `emptyError` — the user pressed the CTA with the form empty: Country and
+ *   Business Name render empty in Core's error state with `requiredError`,
+ *   Tax ID stays clean, CTA greyed (Elena 2026-09-30)
  *
  * Note what `filled` does NOT do: it leaves **Tax ID empty** and still enables
  * the CTA, so the tax identifier is optional and does not gate the lookup
- * (DEVIATIONS #WB-2).
+ * (DEVIATIONS #WB-2). That is also why `emptyError` leaves Tax ID alone.
  */
-export type WatchlistBusinessFormState = 'default' | 'filled';
+export type WatchlistBusinessFormState = 'default' | 'filled' | 'emptyError';
 
 /**
  * One selectable country of registration. Runtime data, never copy — the host
@@ -81,12 +84,23 @@ export interface WatchlistBusinessStrings {
   verifiedLabel: string;
   /** Accessible name for the logo nav row. */
   navLabel?: string;
+  /**
+   * The error row the REQUIRED fields (Country, Business Name) show on the
+   * `emptyError` form state ("This field is required"). Maps to the SDK's
+   * `dynamicForms.fieldRequired` key. GUIDELINES §6-E empty-submit rule.
+   */
+  requiredError: string;
+  /**
+   * Required-field marker ("*"), passed to Core's own `requiredHint` prop on
+   * Country and Business Name (Elena, 2026-09-30).
+   */
+  requiredHint?: string;
 
-  /** watchlist.{default,filled} */
+  /** watchlist.{default,filled,emptyError} */
   form: {
     /** H2 ("Watchlist for business"). */
     title: string;
-    /** H5 — the purple sections draw none, kept for hosts that want one. */
+    /** H5 ("All fields marked with * are required."), explains the asterisk. */
     subtitle?: string;
     country: WatchlistBusinessFieldStrings & {
       /** Search placeholder inside the open menu. */

package/src/flows.ts

@@ -83,6 +83,10 @@ export interface FaceCaptureFlowVariant {
   ctaLoading?: boolean;
   /** FaceCaptureCapturingScreen — which of the 15 `capturing.*` sections. */
   state?: FaceCaptureCapturingState;
+  /** FaceCaptureCapturingScreen — raise the "Need more time?" offer over the
+   *  feed. A modifier of `state`, not one of the fifteen: the fallback timer
+   *  runs underneath whichever guidance is showing. */
+  extendTime?: boolean;
   /** FaceCaptureLoadingScreen — `loading.uploading` vs `loading.processing`. */
   stage?: 'uploading' | 'processing';
   /** FaceCaptureResultErrorScreen — the `*Exhausted` half of the error pairs. */
@@ -140,6 +144,14 @@ export const faceCaptureFlow: readonly FaceCaptureFlowStep[] = [
 /** The off-path screens: manual capture (offered when auto-capture is turned
  *  off or gives up), the two error verdicts, and the connectivity error. */
 export const faceCaptureBranches: readonly FaceCaptureFlowStep[] = [
+  {
+    // A branch, not a step: it only appears when accessibility mode is ON for
+    // the flow AND the fallback timer is 20 s from expiring. It returns to the
+    // capturing states it came from, so it never "follows" anything.
+    screenId: 'face-capture-capturing-extend-time',
+    component: FaceCaptureCapturingScreen,
+    variant: { state: 'alignFace', extendTime: true },
+  },
   {
     screenId: 'face-capture-manual-capture',
     component: FaceCaptureManualCaptureScreen,
@@ -479,6 +491,10 @@ export interface IdCaptureFlowVariant {
   vertical?: boolean;
   /** IdCaptureStageScreen — which stage section. */
   state?: IdCaptureStageState;
+  /** IdCaptureStageScreen — raise the "Need more time?" offer over the feed.
+   *  A modifier of `state`, not one of the eleven: the fallback timer runs
+   *  underneath whichever stage is showing. */
+  extendTime?: boolean;
   /** IdCaptureStageScreen — the `*-manual` sections. */
   manual?: boolean;
   /** IdCaptureResultScreen — which verdict section. */
@@ -633,6 +649,15 @@ export const idCaptureBranches: readonly IdCaptureFlowStep[] = [
     screenId: 'id-capture-age-verification',
     component: IdCaptureAgeVerificationScreen,
   },
+  {
+    // A branch, not a step: it only appears when accessibility mode is ON for
+    // the flow AND the 30 s fallback timer is 20 s from expiring. It returns
+    // to the hint stage it came from, so it never "follows" anything — the
+    // same shape as Face Capture's `capturing-extend-time`.
+    screenId: 'id-capture-front-extend-time',
+    component: IdCaptureStageScreen,
+    variant: { state: 'hint', extendTime: true },
+  },
   {
     screenId: 'id-capture-front-manual',
     component: IdCaptureStageScreen,