@incodetech/prizma-core-screens 0.1.0

package/src/EkybOwnersScreen.tsx

@@ -0,0 +1,230 @@
+import React, { forwardRef } from 'react';
+import { PrizmaTextField } from '@incodetech/prizma-core-web/text-field';
+import { PrizmaTitle } from '@incodetech/prizma-core-web/title';
+import { PrizmaButton } from '@incodetech/prizma-core-web/button';
+import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaFormScreen, type PrizmaFormScreenProps } from './FormScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { EkybOwnersState, EkybOwnersValues, EkybStrings } from './EkybStrings';
+import './ScreenLayout.css';
+
+export interface EkybOwnersScreenProps
+  extends Omit<
+    PrizmaFormScreenProps,
+    | 'title'
+    | 'subtitle'
+    | 'ctaLabel'
+    | 'ctaLoading'
+    | 'ctaLoadingLabel'
+    | 'verifiedLabel'
+    | 'children'
+    | 'navLabel'
+    | 'linkLabel'
+    | 'linkContent'
+    | 'progress'
+    | 'scrollFields'
+  > {
+  /** Module copy — this screen reads the `owners` slice. */
+  strings: EkybStrings;
+  /** Which purple `eKYB.UBO.*` / `eKYB.director.*` section to render.
+   *  Default `uboEmpty`. */
+  state?: EkybOwnersState;
+  /** The four field values. Empty renders the resting empty field. */
+  values?: EkybOwnersValues;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * eKYB — step 3 of the wizard, the people behind the company, built on the Form
+ * archetype (GUIDELINES.md §6-E, `PrizmaFormScreen`).
+ *
+ * ONE screen for BOTH purple parents — `eKYB.UBO` (5707:90967) and
+ * `eKYB.director` (5707:99490) — because measured against the 390 frames the
+ * director frames ARE the UBO frames with a second block revealed: same stepper
+ * position, same H2 "Beneficial Owner", same H5, same first two fields, same
+ * "Add another UBO (Optional)" link, same CTA band. Building them as two files
+ * would have duplicated the UBO block and given it two places to drift.
+ *
+ * Five sections, five distinct renderings:
+ * - `uboEmpty`       2115:20619 — UBO block only, both fields blank
+ * - `uboFilled`      5707:49608 — UBO block only, both fields carrying a value
+ * - `directorEmpty`  5655:56032 — UBO block + Director block, all four blank
+ * - `directorFilled` 5707:49782 — UBO block + Director block, all four filled
+ * - `loading`        5663:94390 — `directorFilled` with the submission in
+ *   flight: every field, both "Add another" links and "Back" go inert, and the
+ *   spinner rides the CTA, never a field (the Phone Input lesson, #PI-5)
+ *
+ * Four things are deliberate:
+ *
+ * 1. The stack SCROLLS inside the content column — now through the archetype's
+ *    own `scrollFields` prop, not a module stylesheet. The director frames are
+ *    1201–1245 tall against a 844 screen that never reflows (#17); without the
+ *    release the surplus paints over the CTA, and the second "Add another…"
+ *    link — the element `directorEmpty` exists to draw — never reaches the
+ *    screen at all. The module used to hand-roll `overflow-y: auto` in
+ *    `EkybLayout.css`; the archetype absorbed it (DEVIATIONS #DSC-2) and that
+ *    file is now deleted.
+ * 2. The Director block's heading is Core's OWN `PrizmaTitle` (H2 + H5, left
+ *    variant) composed into the archetype's `children` slot — the same
+ *    component the archetype uses for the screen title, so the typography is
+ *    the design system's and nothing is hand-rolled. It does mean the screen
+ *    carries TWO H2s, which GUIDELINES §4 does not anticipate; reported as a
+ *    deviation rather than resolved silently.
+ * 3. Both "Add another…" links are Core's `PrizmaButton variant="tertiary-link"`
+ *    and sit INSIDE the field stack, which is where Figma draws them — attached
+ *    to the block they extend, above the CTA band — not in the CTA column.
+ *    They are two SEPARATELY actionable flows (#PI-10), but
+ *    `PrizmaScreenAction` offers only one non-primary/non-secondary type, so
+ *    they are told apart by an action-qualified `screenId` until the contract
+ *    gains a discriminator — reported in `archetypeGaps`.
+ * 4. Only `loading` passes `disabled`. Core's `readOnly` would grey the other
+ *    four sections too, which Figma draws white (#PI-6).
+ *
+ * The three-segment journey bar sits above the title on every one of the five
+ * sections, in the archetype's `progress` slot. This is step 3 of 3, so the bar
+ * runs at `currentState={3}` (5919:71500 / 6340:63438 — segments 1–2 pale,
+ * segment 3 solid) and `loading` flips it to `'Completed'`, which is what turns
+ * all three segments GREEN in 5919:73354. That green beat is the treatment that
+ * distinguishes `loading` from `directorFilled` above the fold, so it is not
+ * optional chrome.
+ */
+export const EkybOwnersScreen = forwardRef<HTMLDivElement, EkybOwnersScreenProps>(
+  (
+    {
+      strings,
+      state = 'uboEmpty',
+      values,
+      screenId = `ekyb-owners-${state}`,
+      className,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    const copy = strings.owners;
+    const busy = state === 'loading';
+    const showDirector =
+      state === 'directorEmpty' || state === 'directorFilled' || busy;
+
+    return (
+      <PrizmaFormScreen
+        ref={ref}
+        className={['ekyb-owners', className].filter(Boolean).join(' ')}
+        /* The archetype's own scrolling field stack — two titled blocks, four
+           fields and two links do not fit a 844 frame. No module CSS. */
+        scrollFields
+        /* Step 3 of 3, and GREEN across all three once the submission runs. */
+        progress={
+          <PrizmaStepper
+            steps={3}
+            currentState={busy ? 'Completed' : 3}
+            showIcons={false}
+            aria-label={strings.stepperLabel}
+            completedValueText={strings.stepperCompletedLabel}
+          />
+        }
+        title={copy.title}
+        subtitle={copy.subtitle}
+        ctaLabel={copy.ctaLabel}
+        /* `loading` swaps the CTA label for Core's designed spinner. */
+        ctaLoading={busy}
+        ctaLoadingLabel={copy.ctaLoadingLabel}
+        linkContent={
+          <PrizmaButton
+            variant="secondary"
+            size="L"
+            /* 5663:94390 greys "Back" while the submission runs. */
+            disabled={busy}
+            onClick={() => onAction?.({ type: 'secondary', screenId })}
+          >
+            {strings.backLabel}
+          </PrizmaButton>
+        }
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        overrides={{ align: overrides?.align ?? 'left', logo: overrides?.logo }}
+        onAction={onAction}
+        {...shell}
+      >
+        <PrizmaTextField
+          label={copy.uboName.label}
+          placeholder={copy.uboName.placeholder}
+          required
+          requiredHint={strings.requiredHint}
+          autoComplete="off"
+          defaultValue={values?.uboName ?? ''}
+          disabled={busy}
+        />
+        {/* Figma draws no asterisk on the surname — it is optional. */}
+        <PrizmaTextField
+          label={copy.uboSurname.label}
+          placeholder={copy.uboSurname.placeholder}
+          autoComplete="off"
+          defaultValue={values?.uboSurname ?? ''}
+          disabled={busy}
+        />
+        <PrizmaButton
+          variant="tertiary-link"
+          size="L"
+          disabled={busy}
+          /* Action-qualified id: the two "Add another…" links are different
+             flows and must stay distinguishable (#PI-10), but the action
+             contract has no per-action discriminator yet. */
+          onClick={() =>
+            onAction?.({ type: 'tertiary', screenId: `${screenId}-add-ubo` })
+          }
+        >
+          {copy.addUboLabel}
+        </PrizmaButton>
+
+        {showDirector ? (
+          <>
+            {/* Core's own Title component — the same H2 + H5 pair the archetype
+                renders at the top of the screen, so the Director block's
+                typography is the design system's, not a copy. */}
+            <PrizmaTitle
+              variant="left"
+              title={copy.directorTitle}
+              showSubtitle={Boolean(copy.directorSubtitle)}
+              subtitle={copy.directorSubtitle}
+            />
+            <PrizmaTextField
+              label={copy.directorName.label}
+              placeholder={copy.directorName.placeholder}
+              autoComplete="off"
+              defaultValue={values?.directorName ?? ''}
+              disabled={busy}
+            />
+            <PrizmaTextField
+              label={copy.directorSurname.label}
+              placeholder={copy.directorSurname.placeholder}
+              autoComplete="off"
+              defaultValue={values?.directorSurname ?? ''}
+              disabled={busy}
+            />
+            <PrizmaButton
+              variant="tertiary-link"
+              size="L"
+              disabled={busy}
+              onClick={() =>
+                onAction?.({
+                  type: 'tertiary',
+                  screenId: `${screenId}-add-director`,
+                })
+              }
+            >
+              {copy.addDirectorLabel}
+            </PrizmaButton>
+          </>
+        ) : null}
+      </PrizmaFormScreen>
+    );
+  },
+);
+EkybOwnersScreen.displayName = 'EkybOwnersScreen';
+
+export default EkybOwnersScreen;

package/src/EkybProcessingScreen.tsx

@@ -0,0 +1,57 @@
+import React, { forwardRef } from 'react';
+import {
+  PrizmaProcessingScreen,
+  type PrizmaProcessingScreenProps,
+} from './ProcessingScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { EkybStrings } from './EkybStrings';
+import './ScreenLayout.css';
+
+export interface EkybProcessingScreenProps
+  extends Omit<
+    PrizmaProcessingScreenProps,
+    'status' | 'title' | 'subtitle' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `processing` slice. */
+  strings: EkybStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * eKYB — the in-flight screen (`eKYB.processing`, 2116:34749), built on the
+ * Processing archetype (GUIDELINES.md §6-C, `PrizmaProcessingScreen`).
+ *
+ * The pure spinner + H2 case with no button, which is exactly what §6-F reserves
+ * for C rather than the Result archetype: the frame centres Core's spinner over
+ * the status line in the middle of the column, keeps the logo header and the
+ * verified tag, and offers the operator nothing to press while the submission is
+ * checked.
+ *
+ * The title block is CENTRED here — unlike every eKYB form page, which
+ * left-aligns — because the archetype centres the whole column and Figma draws
+ * it that way; no alignment override is passed.
+ */
+export const EkybProcessingScreen = forwardRef<HTMLDivElement, EkybProcessingScreenProps>(
+  (
+    { strings, screenId = 'ekyb-processing', overrides, onAction, ...shell },
+    ref,
+  ) => (
+    <PrizmaProcessingScreen
+      ref={ref}
+      status="loading"
+      title={strings.processing.title}
+      subtitle={strings.processing.subtitle}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+EkybProcessingScreen.displayName = 'EkybProcessingScreen';
+
+export default EkybProcessingScreen;

package/src/EkybStrings.ts

@@ -0,0 +1,239 @@
+// eKYB — copy contract.
+//
+// Figma: `💼 eKYB - Screens specs + Localization` (TWgYZVhurQCizfC4tfLEut,
+// page 2003:12082, purple parent section 2116:23785). The file is SHARED with
+// eKYC (sections 2098:20865 and 2101:7869) — none of those frames belong to this
+// module and none is rebuilt here.
+//
+// SIX purple parent sections, fifteen master frames:
+//   eKYB.country   (5707:78603) — empty 2115:20444 · filled 5655:42140 ·
+//                                 dropdown 5707:54174
+//   eKYB.Bdetails  (5707:87449) — empty 2115:21864 · filled 5663:83132
+//   eKYB.Bdetails  (6340:32594) — the SECOND section of that name, the address
+//                                 page: empty 6340:50731 · filled 6340:38197
+//   eKYB.UBO       (5707:90967) — empty 2115:20619 · filled 5707:49608
+//   eKYB.director  (5707:99490) — empty 5655:56032 · filled 5707:49782 ·
+//                                 loading 5663:94390
+//   (unnamed)      (5707:99491) — processing 2116:34749 · error 2116:34743 ·
+//                                 success 2116:34709
+//
+// The module is business onboarding: the operator picks the country of
+// registration, files the company's identity and address, names the beneficial
+// owner(s) and director(s), and the submission is checked.
+//
+// No hardcoded English anywhere in a screen: every visible string arrives here,
+// so the host's locale pack drives the module (the Figma file ships ES + PT
+// columns beside the EN one).
+
+/**
+ * The `eKYB.country.*` sections. All three share the archetype-E skeleton —
+ * nav → Title (H2 + H5) → Spacing/32 → one labelled dropdown → "Continue" →
+ * tag — and differ ONLY in what the dropdown carries:
+ * - `empty`    — the placeholder ("Select country"), nothing chosen
+ * - `filled`   — a country selected, drawn as flag + name in the closed field
+ * - `dropdown` — the same selection with the MENU OPEN over the form: search
+ *   bar plus the country rows (Core's documentation-only `forceOpen`, since a
+ *   screen is one static spec state and never a live interaction)
+ */
+export type EkybCountryState = 'empty' | 'filled' | 'dropdown';
+
+/** The two `eKYB.Bdetails` (business identity) sections: every field on its
+ *  resting empty surface, or every field carrying a value. */
+export type EkybBusinessState = 'empty' | 'filled';
+
+/** The two address sections (the SECOND `eKYB.Bdetails` parent). Same axis. */
+export type EkybAddressState = 'empty' | 'filled';
+
+/**
+ * The `eKYB.UBO.*` and `eKYB.director.*` sections — one screen family, because
+ * measured against the 390 frames the director frames ARE the UBO frames with
+ * the Director block revealed below the "Add another UBO" link: same stepper
+ * position, same H2, same subtitle, same first two fields, same CTA band.
+ *
+ * - `uboEmpty`      — `eKYB.UBO.empty` (2115:20619): the two UBO fields blank
+ * - `uboFilled`     — `eKYB.UBO.filled` (5707:49608): both carrying a value
+ * - `directorEmpty` — `eKYB.director.empty` (5655:56032): UBO block plus the
+ *   Director block, every field blank
+ * - `directorFilled`— `eKYB.directorFilled` (5707:49782): all four filled
+ * - `loading`       — `eKYB.directorloading` (5663:94390): the submission is in
+ *   flight, so EVERY field, both "Add another" links and "Back" go inert and
+ *   the spinner rides the CTA, never a field (the Phone Input lesson,
+ *   DEVIATIONS #PI-5)
+ */
+export type EkybOwnersState =
+  | 'uboEmpty'
+  | 'uboFilled'
+  | 'directorEmpty'
+  | 'directorFilled'
+  | 'loading';
+
+/**
+ * One selectable row in the country / state menus. Runtime data, not copy — the
+ * host owns the catalogue (an ISO country list is ~250 entries and a state list
+ * is jurisdiction-specific), exactly as Phone Input takes its dial codes as data
+ * rather than strings.
+ */
+export interface EkybOption {
+  /** Stable value, e.g. `US` / `TX`. */
+  value: string;
+  /** The row label as drawn in the open menu. */
+  label: string;
+  /** Compact face for the CLOSED field when it differs from the menu row —
+   *  Core's own `PrizmaDropdownOption.fieldLabel`. `eKYB.country.dropdown`
+   *  draws "🇺🇸 +1 United States" in the row and "🇺🇸 United States" in the
+   *  field. */
+  fieldLabel?: string;
+}
+
+/** The values the business-identity page carries. Runtime data, never copy. */
+export interface EkybBusinessValues {
+  businessName?: string;
+  taxId?: string;
+}
+
+/** The values the address page carries. Runtime data, never copy. */
+export interface EkybAddressValues {
+  street?: string;
+  houseNumber?: string;
+  addressLine2?: string;
+  city?: string;
+  /** An `EkybOption.value` from the `states` catalogue. */
+  state?: string;
+  postalCode?: string;
+}
+
+/** The values the owners page carries. Runtime data, never copy. */
+export interface EkybOwnersValues {
+  uboName?: string;
+  uboSurname?: string;
+  directorName?: string;
+  directorSurname?: string;
+}
+
+/** Copy for one labelled field. The required `*` is appended by Core from
+ *  `EkybStrings.requiredHint`, never baked into `label`. */
+export interface EkybFieldStrings {
+  /** Visible label ("Business name"). */
+  label: string;
+  /** Placeholder inside the field. The eKYB frames draw none on the text
+   *  fields — only the two dropdowns carry one — so this is optional. */
+  placeholder?: string;
+}
+
+export interface EkybStrings {
+  /** "verified by" attribution in the footer tag. */
+  verifiedLabel: string;
+  /** Accessible name for the logo nav row. */
+  navLabel?: string;
+  /**
+   * Suffix Core appends to a required field's label — the `*` every eKYB form
+   * label carries. Passed to Core's own `requiredHint` prop so the marker is
+   * localizable and never hardcoded in a screen.
+   */
+  requiredHint?: string;
+  /** Shared "Back" secondary action drawn under "Continue" on every page except
+   *  `country`. Emits `secondary`. */
+  backLabel: string;
+
+  /**
+   * Accessible name for the three-segment journey bar every WIZARD frame draws
+   * between the logo nav and the title block (Core's `PrizmaStepper`,
+   * `role="progressbar"`). Nine of the module's fifteen sections carry it —
+   * business ×2 (segment 1), address ×2 (segment 2), owners ×5 (segment 3, or
+   * all three green while the submission runs) — and it is the only chrome that
+   * tells the three wizard pages apart, so it carries a real name rather than
+   * none. Copy, therefore it lives here.
+   *
+   * The `eKYB.country.*` sections draw NO bar (2115:20444 has no Stepper
+   * instance): the country choice sits before the wizard.
+   */
+  stepperLabel: string;
+  /**
+   * `aria-valuetext` the same bar announces once all three segments are green —
+   * the `eKYB.directorloading` section (5663:94390). Same contract as eKYC's
+   * and Video Selfie's `stepperCompletedLabel`.
+   */
+  stepperCompletedLabel: string;
+
+  /** eKYB.country.{empty,filled,dropdown} */
+  country: {
+    /** H2 ("Select your country"). */
+    title: string;
+    /** H5 ("Select the country where your business is registered"). */
+    subtitle?: string;
+    /** The one labelled dropdown ("Country" / "Select country"). */
+    field: EkybFieldStrings;
+    /** Search-bar placeholder inside the open menu ("Search for country"). */
+    searchPlaceholder?: string;
+    /** Accessible name for the menu's search-clear button. */
+    clearSearchLabel?: string;
+    /** Primary CTA ("Continue"). */
+    ctaLabel: string;
+  };
+
+  /** eKYB.Bdetails.{empty,filled} — the business-identity page. */
+  business: {
+    /** H2 ("Business Information"). */
+    title: string;
+    /** H5 ("All fields marked with * are required."). */
+    subtitle?: string;
+    businessName: EkybFieldStrings;
+    taxId: EkybFieldStrings;
+    /** Primary CTA ("Continue"). */
+    ctaLabel: string;
+  };
+
+  /** The second eKYB.Bdetails parent — the address page. */
+  address: {
+    /** H2 ("Address Details"). */
+    title: string;
+    /** H5 ("All fields marked with * are required."). */
+    subtitle?: string;
+    street: EkybFieldStrings;
+    houseNumber: EkybFieldStrings;
+    /** The one OPTIONAL field of the page — Figma draws no `*`. */
+    addressLine2: EkybFieldStrings;
+    city: EkybFieldStrings;
+    /** The State dropdown ("State" / "Select state"). No search copy: neither
+     *  address section draws this menu open, so the screen ships no
+     *  `searchable` and a search placeholder would be dead copy. */
+    state: EkybFieldStrings;
+    postalCode: EkybFieldStrings;
+    /** Primary CTA ("Continue"). */
+    ctaLabel: string;
+  };
+
+  /** eKYB.UBO.* and eKYB.director.* — one screen, two blocks. */
+  owners: {
+    /** The screen's single H2 ("Beneficial Owner") and its H5. */
+    title: string;
+    subtitle?: string;
+    uboName: EkybFieldStrings;
+    /** Figma draws NO `*` on the surname — it is optional. */
+    uboSurname: EkybFieldStrings;
+    /** The tertiary link under the UBO block ("Add another UBO (Optional)"). */
+    addUboLabel: string;
+    /** The Director block's own heading + description. Rendered by Core's
+     *  `PrizmaTitle` inside the field stack; see the screen's docstring and the
+     *  module's reported deviation about the second heading. */
+    directorTitle: string;
+    directorSubtitle?: string;
+    directorName: EkybFieldStrings;
+    directorSurname: EkybFieldStrings;
+    /** The tertiary link under the Director block. */
+    addDirectorLabel: string;
+    /** Primary CTA ("Continue"). */
+    ctaLabel: string;
+    /** Accessible busy label while the submission runs (`loading`). */
+    ctaLoadingLabel?: string;
+  };
+
+  /** eKYB.processing (2116:34749) — the pure spinner screen, no button. */
+  processing: { title: string; subtitle?: string };
+
+  /** eKYB.success (2116:34709) — positive mark, no button. */
+  success: { title: string; subtitle?: string };
+
+  /** eKYB.error (2116:34743) — negative mark + "Try again". */
+  error: { title: string; subtitle?: string; ctaLabel: string };
+}

package/src/EkybSuccessScreen.tsx

@@ -0,0 +1,54 @@
+import React, { forwardRef } from 'react';
+import {
+  PrizmaProcessingScreen,
+  type PrizmaProcessingScreenProps,
+} from './ProcessingScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { EkybStrings } from './EkybStrings';
+import './ScreenLayout.css';
+
+export interface EkybSuccessScreenProps
+  extends Omit<
+    PrizmaProcessingScreenProps,
+    'status' | 'title' | 'subtitle' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `success` slice. */
+  strings: EkybStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * eKYB — the positive verdict (`eKYB.success`, 2116:34709), built on the
+ * Processing archetype (GUIDELINES.md §6-C, `PrizmaProcessingScreen`).
+ *
+ * Figma draws NO button here: the flow advances on its own once the submission
+ * is accepted, so this is the pure status-mark case §6-F reserves for C rather
+ * than for the Result archetype — the same deliberate split Email Input records
+ * against its Phone Input sibling (DEVIATIONS #EI-4). Its sibling
+ * `EkybErrorScreen` needs a button and therefore sits on F.
+ *
+ * Core's outline status mark is used, not Figma's two-tone filled disc — the
+ * icon-outline sweep of 2026-07-28 settled that for every module (#15, #DC-34)
+ * and this file's frames are one sweep behind.
+ */
+export const EkybSuccessScreen = forwardRef<HTMLDivElement, EkybSuccessScreenProps>(
+  ({ strings, screenId = 'ekyb-success', overrides, onAction, ...shell }, ref) => (
+    <PrizmaProcessingScreen
+      ref={ref}
+      status="success"
+      title={strings.success.title}
+      subtitle={strings.success.subtitle}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+EkybSuccessScreen.displayName = 'EkybSuccessScreen';
+
+export default EkybSuccessScreen;