@incodetech/prizma-core-screens 0.1.0

package/src/PhoneInputLayout.css

@@ -0,0 +1,61 @@
+/* Phone Input — module layout additions.
+ *
+ * ONLY what the foundation archetypes and Prizma Core do not already own.
+ * Every value is a token. Nothing here re-declares an archetype spacing rule:
+ * the content column, the 24px gutters, the title → fields offset and the
+ * anchored footer all stay the foundation's (`ScreenLayout.css`,
+ * `FormScreen.css`).
+ */
+
+/* ── Combined country + phone row ────────────────────────────────────────────
+ * Figma `Input / Combined` (3939:41889): "a combined form element that allows
+ * users to input phone number" — a dropdown + text field pair at Spacing/8,
+ * the dropdown hugging its content, the field filling the rest.
+ *
+ * Core ships both primitives; what it has no component for is the PAIRING, so
+ * the row lives here. `align-items: start` keeps the two fields top-aligned
+ * when the text field grows an error/helper row that the dropdown does not.
+ */
+.phone-input-combined {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--prizma-spacing-8);
+  width: 100%;
+}
+
+/* The dial-code dropdown hugs its content ("🇷🇸 +381"), as Figma draws it.
+ *
+ * Core's `.prizma-dropdown` is `width: 100%` (Dropdown.css) — it is built to
+ * FILL its container and ships no hug/auto-width variant, so inside this row it
+ * consumed the whole column and pushed the number field out. Constrained here
+ * from the module layer (no Core file touched, no !important): `width: auto`
+ * releases the fill and `flex: 0 0 auto` keeps the row from stretching it back.
+ * The inner `__anchor` inherits the same rule for the same reason.
+ * A `width`/`fit` prop on `PrizmaDropdown` would remove this — DEVIATIONS #PI-1.
+ */
+.phone-input-combined__country,
+.phone-input-combined__country .prizma-dropdown__anchor,
+.phone-input-combined__country .prizma-dropdown__label-container {
+  flex: 0 0 auto;
+  width: auto;
+}
+
+/* …and the number field takes the remaining width. `min-width: 0` is what lets
+ * it actually shrink inside the flex row instead of overflowing the column. */
+.phone-input-combined__number {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/* The open menu must NOT inherit the hugged anchor's width: Core anchors the
+ * menu to the trigger, so once the trigger hugs "🇷🇸 +381" the option rows
+ * truncate ("+…"). The menu keeps its own readable width — it lists country
+ * names and dial codes, which the closed field never shows. Sized to the
+ * content and capped at the 342 column so it never escapes the screen.
+ * DEVIATIONS #PI-1 (same root cause as the hug).
+ */
+.phone-input-combined__country .prizma-dropdown__menu {
+  width: max-content;
+  min-width: 100%;
+  max-width: 342px;
+}

package/src/PhoneInputOtpScreen.tsx

@@ -0,0 +1,126 @@
+import React, { forwardRef } from 'react';
+import { PrizmaOtp } from '@incodetech/prizma-core-web/otp';
+import { PrizmaFormScreen, type PrizmaFormScreenProps } from './FormScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { PhoneInputOtpState, PhoneInputStrings } from './PhoneInputStrings';
+import './ScreenLayout.css';
+import './PhoneInputLayout.css';
+
+export interface PhoneInputOtpScreenProps
+  extends Omit<
+    PrizmaFormScreenProps,
+    'title' | 'subtitle' | 'ctaLabel' | 'verifiedLabel' | 'children' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `otp` slice. */
+  strings: PhoneInputStrings;
+  /** Which purple `phoneNumber.OTP.*` section to render. Default `typing`. */
+  state?: PhoneInputOtpState;
+  /** The code as typed. `typing` draws a partial value, `filled` a complete one. */
+  value?: string;
+  /** How many digits the code carries. Default 6. */
+  length?: number;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Phone Input — the one-time-code screen, built on the Form archetype
+ * (GUIDELINES.md §6-E, `PrizmaFormScreen`).
+ *
+ * ONE screen for all four purple `phoneNumber.OTP.*` sections
+ * (`typing` / `filled` / `processing` / `error`) — identical layout, differing
+ * only in the state of the code field and the CTA.
+ *
+ * `processing` deliberately does NOT use Core's `PrizmaOtp.loading`. That prop
+ * centres the spinner INSIDE the code field (owner definition 2026-07-12), but
+ * the purple `OTP.processing` section draws the field simply DISABLED with the
+ * code still legible and puts the spinner in the CTA — the same treatment as
+ * `verify.loading`, which is what makes the module read consistently. Figma
+ * wins; `PrizmaOtp.loading` stays correct for hosts that want the in-field
+ * spinner. DEVIATIONS #PI-5.
+ */
+export const PhoneInputOtpScreen = forwardRef<HTMLDivElement, PhoneInputOtpScreenProps>(
+  (
+    {
+      strings,
+      state = 'typing',
+      value,
+      length = 6,
+      screenId = `phone-input-otp-${state}`,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaFormScreen
+      ref={ref}
+      title={strings.otp.title}
+      subtitle={strings.otp.subtitle}
+      ctaLabel={strings.otp.ctaLabel}
+      /* Figma greys the CTA until the code is complete. */
+      ctaDisabled={state === 'typing'}
+      /* The spinner rides the CTA, not the field (see the note above). */
+      ctaLoading={state === 'processing'}
+      ctaLoadingLabel={strings.otp.ctaLoadingLabel}
+      /* "Didn't receive the code? Resend code or Change phone number" — drawn
+         under the CTA on every OTP section. ONE sentence, TWO independently
+         actionable links, so it uses the archetype's composed-line slot rather
+         than `linkLabel` (a full-width 56px button cannot sit inside a line of
+         body text, and one button could not tell the two actions apart —
+         DEVIATIONS #PI-10). */
+      linkContent={
+        strings.otp.resendPrompt ? (
+          <p className="prizma-screen-layout__inline-prompt">
+            {strings.otp.resendPrompt}{' '}
+            {strings.otp.resendLabel ? (
+              <button
+                type="button"
+                className="prizma-screen-layout__inline-link"
+                onClick={() => onAction?.({ type: 'secondary', screenId })}
+              >
+                {strings.otp.resendLabel}
+              </button>
+            ) : null}
+            {strings.otp.changeNumberLabel ? (
+              <>
+                {' '}
+                {strings.otp.resendSeparator}{' '}
+                <button
+                  type="button"
+                  className="prizma-screen-layout__inline-link"
+                  onClick={() => onAction?.({ type: 'tertiary', screenId })}
+                >
+                  {strings.otp.changeNumberLabel}
+                </button>
+              </>
+            ) : null}
+          </p>
+        ) : undefined
+      }
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    >
+      <PrizmaOtp
+        length={length}
+        /* Uncontrolled, for the same reason as the phone field: `readOnly`
+           would paint Core's DISABLED surface on the resting states, which is
+           grey Figma does not draw there (DEVIATIONS #PI-6). */
+        defaultValue={value ?? ''}
+        /* `processing` is the one section Figma greys — the code stays legible
+           while the check runs. */
+        disabled={state === 'processing'}
+        error={state === 'error'}
+        errorText={state === 'error' ? strings.otp.errorText : undefined}
+      />
+    </PrizmaFormScreen>
+  ),
+);
+PhoneInputOtpScreen.displayName = 'PhoneInputOtpScreen';
+
+export default PhoneInputOtpScreen;

package/src/PhoneInputSnaLoadingScreen.tsx

@@ -0,0 +1,61 @@
+import React, { forwardRef } from 'react';
+import {
+  PrizmaProcessingScreen,
+  type PrizmaProcessingScreenProps,
+} from './ProcessingScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { PhoneInputStrings } from './PhoneInputStrings';
+import './ScreenLayout.css';
+
+export interface PhoneInputSnaLoadingScreenProps
+  extends Omit<
+    PrizmaProcessingScreenProps,
+    'status' | 'title' | 'subtitle' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `sna` slice. */
+  strings: PhoneInputStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Phone Input — Silent Network Auth in flight, built on the Processing
+ * archetype (GUIDELINES.md §6-C, `PrizmaProcessingScreen`).
+ *
+ * Figma: the purple `phoneNumber.loading` section (`phoneNumber.SNA.loading`).
+ * A pure spinner + H2 screen with no button, which is exactly the case §6-F
+ * reserves for C rather than the Result archetype — nothing here needs a CTA
+ * band, so the centred column stays.
+ */
+export const PhoneInputSnaLoadingScreen = forwardRef<
+  HTMLDivElement,
+  PhoneInputSnaLoadingScreenProps
+>(
+  (
+    {
+      strings,
+      screenId = 'phone-input-sna-loading',
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaProcessingScreen
+      ref={ref}
+      status="loading"
+      title={strings.sna.title}
+      subtitle={strings.sna.subtitle}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+PhoneInputSnaLoadingScreen.displayName = 'PhoneInputSnaLoadingScreen';
+
+export default PhoneInputSnaLoadingScreen;

package/src/PhoneInputStrings.ts

@@ -0,0 +1,136 @@
+// Phone Input — copy contract.
+//
+// Figma: `📞 Phone - Screens specs + Localization` (nIj8kklozEOMs2e5sLzGFi,
+// page 5:13191). Five purple parent sections:
+//   phoneNumber.verify   — default / countryCode / phonetyping / phoneFilled / loading
+//   phoneNumber.OTP      — typing / filled / processing / error
+//   phoneNumber.loading  — SNA.loading (Silent Network Auth)
+//   phoneNumber.success  — success
+//   phoneNumber.error    — tryAgain / unknown / noNetwork
+//
+// No hardcoded English anywhere in a screen: every visible string arrives here,
+// so the host's locale pack drives the module (the file ships ES + PT columns).
+
+/**
+ * The `phoneNumber.verify.*` sections. All five draw the SAME layout — the
+ * country dropdown + phone field pair — and differ only in field content and
+ * CTA state, so they are states of one screen rather than five screens:
+ * - `default`     — placeholder phone, CTA enabled (Figma draws it enabled)
+ * - `countryCode` — the country dropdown open over the form
+ * - `typing`      — partial value, focused field
+ * - `filled`      — complete value
+ * - `loading`     — CTA in its loading treatment while the code is requested
+ */
+export type PhoneInputVerifyState =
+  | 'default'
+  | 'countryCode'
+  | 'typing'
+  | 'filled'
+  | 'loading';
+
+/**
+ * The `phoneNumber.OTP.*` sections — same layout, different field state:
+ * - `typing`     — partial code
+ * - `filled`     — complete code
+ * - `processing` — code submitted, `PrizmaOtp` in its loading treatment
+ * - `error`      — wrong code, negative field + error row
+ */
+export type PhoneInputOtpState = 'typing' | 'filled' | 'processing' | 'error';
+
+/**
+ * The `phoneNumber.error.*` sections. `tryAgain` and `unknown` keep the module
+ * chrome; `noNetwork` is the connectivity family every module carries — no nav,
+ * no tag, a Wi-Fi glyph above the title (DEVIATIONS #9, #10).
+ */
+export type PhoneInputErrorVariant = 'tryAgain' | 'unknown' | 'noNetwork';
+
+/** One selectable country in the dial-code dropdown. Runtime data, not copy —
+ *  the host supplies its own list; `flag` is the emoji Figma draws (Core has no
+ *  country-flag primitive — DEVIATIONS #PI-3). */
+export interface PhoneInputCountry {
+  /** Stable value, e.g. an ISO 3166-1 alpha-2 code. */
+  value: string;
+  /** Dial code as drawn, e.g. `+381`. */
+  dialCode: string;
+  /** Country name for the open menu row. */
+  label: string;
+  /** Emoji flag, e.g. `🇷🇸`. */
+  flag?: string;
+}
+
+export interface PhoneInputStrings {
+  /** "verified by" attribution in the footer tag. */
+  verifiedLabel: string;
+  /** Accessible name for the logo nav row. */
+  navLabel?: string;
+
+  /** phoneNumber.verify.* */
+  verify: {
+    /** H2 ("Verify your phone number"). */
+    title: string;
+    /** H5 ("We'll send you a code to ensure it's yours"). */
+    subtitle: string;
+    /** Phone field placeholder ("(123) 123-45-67"). */
+    placeholder: string;
+    /** Accessible label for the phone field. */
+    fieldLabel?: string;
+    /** Accessible label for the country dial-code dropdown. */
+    countryLabel?: string;
+    /** Search placeholder inside the open country menu. */
+    countrySearchPlaceholder?: string;
+    /** Primary CTA ("Continue"). */
+    ctaLabel: string;
+    /** Accessible busy label while the code is requested (`loading`). */
+    ctaLoadingLabel?: string;
+  };
+
+  /** phoneNumber.OTP.* */
+  otp: {
+    /** H2 ("Enter the code we've sent via SMS"). */
+    title: string;
+    /** H5 — carries the masked destination number, when the section shows one. */
+    subtitle?: string;
+    /** Error row on the `error` state ("Incorrect code, try again"). */
+    errorText: string;
+    /**
+     * The line under the CTA is ONE sentence carrying TWO separate links:
+     * "Didn't receive the code? [Resend code] or [Change phone number]".
+     * It is split into four strings because the links are independently
+     * actionable — the host must be able to tell a re-send from a return to
+     * phone entry — and because a locale needs to order the fragments itself.
+     * Omit `resendPrompt` to render no line at all.
+     */
+    resendPrompt?: string;
+    /** First link — re-sends the code. Emits `secondary`. */
+    resendLabel?: string;
+    /** The conjunction between the two links ("or"). */
+    resendSeparator?: string;
+    /** Second link — returns to phone entry. Emits `tertiary`. */
+    changeNumberLabel?: string;
+    /** Primary CTA. */
+    ctaLabel: string;
+    /** Accessible / visible busy copy while the code is checked (`processing`). */
+    ctaLoadingLabel?: string;
+  };
+
+  /** phoneNumber.loading — Silent Network Auth, a pure processing screen. */
+  sna: {
+    /** H2 shown under the spinner. */
+    title: string;
+    subtitle?: string;
+  };
+
+  /** phoneNumber.success */
+  success: {
+    title: string;
+    subtitle?: string;
+    ctaLabel?: string;
+  };
+
+  /** phoneNumber.error.* — one slice per variant. */
+  error: {
+    tryAgain: { title: string; subtitle?: string; ctaLabel: string };
+    unknown: { title: string; subtitle?: string; ctaLabel: string };
+    noConnection: { title: string; subtitle?: string; ctaLabel: string };
+  };
+}

package/src/PhoneInputSuccessScreen.tsx

@@ -0,0 +1,56 @@
+import React, { forwardRef } from 'react';
+import { PrizmaResultScreen, type PrizmaResultScreenProps } from './ResultScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { PhoneInputStrings } from './PhoneInputStrings';
+import './ScreenLayout.css';
+
+export interface PhoneInputSuccessScreenProps
+  extends Omit<
+    PrizmaResultScreenProps,
+    'status' | 'title' | 'subtitle' | 'ctaLabel' | 'verifiedLabel' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `success` slice. */
+  strings: PhoneInputStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Phone Input — the verified verdict, built on the Result archetype
+ * (GUIDELINES.md §6-F, `PrizmaResultScreen`).
+ *
+ * Figma: the purple `phoneNumber.success` section. Centred status mark + title
+ * over the CTA band. The mark is Core's outline status icon via
+ * `PrizmaTitle`'s icon slot — the module Figma still draws the two-tone filled
+ * disc, one icon sweep behind (DEVIATIONS #15, unchanged here).
+ */
+export const PhoneInputSuccessScreen = forwardRef<HTMLDivElement, PhoneInputSuccessScreenProps>(
+  (
+    {
+      strings,
+      screenId = 'phone-input-success',
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaResultScreen
+      ref={ref}
+      status="success"
+      title={strings.success.title}
+      subtitle={strings.success.subtitle}
+      ctaLabel={strings.success.ctaLabel}
+      verifiedLabel={strings.verifiedLabel}
+      navLabel={strings.navLabel}
+      screenId={screenId}
+      overrides={overrides}
+      onAction={onAction}
+      {...shell}
+    />
+  ),
+);
+PhoneInputSuccessScreen.displayName = 'PhoneInputSuccessScreen';
+
+export default PhoneInputSuccessScreen;

package/src/PhoneInputVerifyScreen.tsx

@@ -0,0 +1,153 @@
+import React, { forwardRef } from 'react';
+import { PrizmaTextField } from '@incodetech/prizma-core-web/text-field';
+import { PrizmaDropdown } from '@incodetech/prizma-core-web/dropdown';
+import { PrizmaFormScreen, type PrizmaFormScreenProps } from './FormScreen';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type {
+  PhoneInputCountry,
+  PhoneInputStrings,
+  PhoneInputVerifyState,
+} from './PhoneInputStrings';
+import './ScreenLayout.css';
+import './PhoneInputLayout.css';
+
+export interface PhoneInputVerifyScreenProps
+  extends Omit<
+    PrizmaFormScreenProps,
+    'title' | 'subtitle' | 'ctaLabel' | 'verifiedLabel' | 'children' | 'navLabel'
+  > {
+  /** Module copy — this screen reads the `verify` slice. */
+  strings: PhoneInputStrings;
+  /** Which purple `phoneNumber.verify.*` section to render. Default `default`. */
+  state?: PhoneInputVerifyState;
+  /** The selectable dial codes. Runtime data, not copy. */
+  countries?: PhoneInputCountry[];
+  /** Selected country `value`. Defaults to the first entry. */
+  country?: string;
+  /** The phone number as typed. Empty renders the placeholder (`default`). */
+  value?: string;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/** Figma's `countryCode` section draws the dropdown menu open over the form;
+ *  Core exposes that as the documentation-only `forceOpen` (a screen is one
+ *  static spec state, never a live interaction). */
+const DEFAULT_COUNTRIES: PhoneInputCountry[] = [
+  { value: 'RS', dialCode: '+381', label: 'Serbia', flag: '🇷🇸' },
+];
+
+/**
+ * Phone Input — the phone-entry screen, built on the Form archetype
+ * (GUIDELINES.md §6-E, `PrizmaFormScreen`).
+ *
+ * ONE screen for all five purple `phoneNumber.verify.*` sections
+ * (`default` / `countryCode` / `phonetyping` / `phoneFilled` / `loading`):
+ * measured against the 390 frames, they share an identical layout — nav → Title
+ * (H2 + H5) → Spacing/32 → the combined country-dropdown + phone-field row →
+ * CTA → tag — and differ ONLY in field content and CTA state, which is exactly
+ * what GUIDELINES §6-E means by "states are separate screens sharing the
+ * identical layout".
+ *
+ * Figma's `Input / Combined` is a dropdown + text field pair at Spacing/8, the
+ * dropdown hugging its content and the field filling the rest. Core ships both
+ * primitives (`PrizmaDropdown`, `PrizmaTextField`) at the designed 56px min
+ * height and `Border/Radius/small`, so the module layer contributes only the
+ * row that pairs them (`PhoneInputLayout.css`) — no primitive is re-implemented.
+ */
+export const PhoneInputVerifyScreen = forwardRef<HTMLDivElement, PhoneInputVerifyScreenProps>(
+  (
+    {
+      strings,
+      state = 'default',
+      countries = DEFAULT_COUNTRIES,
+      country,
+      value,
+      screenId = `phone-input-verify-${state}`,
+      overrides,
+      onAction,
+      ...shell
+    },
+    ref,
+  ) => {
+    const selected = country ?? countries[0]?.value;
+    const options = countries.map((c) => ({
+      value: c.value,
+      // The closed field shows flag + dial code exactly as Figma draws it
+      // ("🇷🇸 +381"); the open menu row adds the country name.
+      label: [c.flag, c.dialCode].filter(Boolean).join(' '),
+    }));
+
+    // Figma treats the states as three distinct field treatments, not one:
+    // `loading` greys BOTH fields (the request is in flight and the form is
+    // inert) and puts the spinner in the CTA; `typing` draws the focused blue
+    // border with the caret and the clear affordance; everything else is a
+    // plain editable field on the default white surface. Core's read-only
+    // paints the DISABLED surface (owner definition 2026-07-12), so it is used
+    // for none of them — it would grey the resting states too (DEVIATIONS #PI-6).
+    const busy = state === 'loading';
+    const focused = state === 'typing';
+
+    return (
+      <PrizmaFormScreen
+        ref={ref}
+        title={strings.verify.title}
+        subtitle={strings.verify.subtitle}
+        ctaLabel={strings.verify.ctaLabel}
+        /* Figma's `loading` section swaps the CTA label for Core's spinner. */
+        ctaLoading={busy}
+        ctaLoadingLabel={strings.verify.ctaLoadingLabel}
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        overrides={overrides}
+        onAction={onAction}
+        {...shell}
+      >
+        <div className="phone-input-combined">
+          <PrizmaDropdown
+            className="phone-input-combined__country"
+            /* Figma's combined row draws NO visible labels — the flag + dial
+               code and the placeholder carry the meaning — so the module copy
+               rides `aria-label` instead of Core's visible `label` slot, which
+               would add a row the design does not have. */
+            aria-label={strings.verify.countryLabel}
+            options={options}
+            value={selected}
+            searchable
+            searchPlaceholder={strings.verify.countrySearchPlaceholder}
+            /* The `countryCode` section IS the open-menu spec state. */
+            forceOpen={state === 'countryCode'}
+            disabled={busy}
+          />
+          <PrizmaTextField
+            className={[
+              'phone-input-combined__number',
+              /* Core's own static-focus modifier — the same mechanism the
+                 Dropdown exposes as `forceState`, which `PrizmaTextField` has
+                 no prop for yet (DEVIATIONS #PI-7). No styling is redeclared. */
+              focused ? 'prizma-input-textfield--focused' : '',
+            ]
+              .filter(Boolean)
+              .join(' ')}
+            type="tel"
+            inputMode="tel"
+            aria-label={strings.verify.fieldLabel}
+            placeholder={strings.verify.placeholder}
+            /* Uncontrolled: a screen is one static spec state, and `value`
+               without `onChange` would either warn or force `readOnly`, whose
+               disabled surface is exactly the grey Figma does NOT draw here. */
+            defaultValue={value ?? ''}
+            disabled={busy}
+            /* Figma draws the clear ✕ only while the field is focused. */
+            clearable={focused}
+          />
+        </div>
+      </PrizmaFormScreen>
+    );
+  },
+);
+PhoneInputVerifyScreen.displayName = 'PhoneInputVerifyScreen';
+
+export default PhoneInputVerifyScreen;