@globalpayments-private/gpds-pattern-web 0.0.0-stage → 0.1.0-pr.7.gdcb74cd

package/dist/collection/components/uds-pattern-login-card/view-model/login-step.view-model.js

@@ -0,0 +1,138 @@
+import { formatLabel } from "../../../utils/labels";
+/**
+ * The data a renderer needs to draw one step of the login workflow.
+ *
+ * ## Why this is a class with a factory, and not an inline object
+ *
+ * Deriving "what the user should see" from "what the workflow currently holds"
+ * is real logic: which affordances are available, what the heading says, which
+ * description variant applies, whether a countdown is running. Assembled inline
+ * inside `render()` that derivation is untestable and re-read on every change;
+ * named here it has one home, one test surface and one place to review.
+ *
+ * ## Why it carries no callbacks
+ *
+ * A view model is *data*. Handlers are supplied alongside it
+ * (`LoginCardHandlers`) rather than folded in, because a model that carries
+ * behaviour cannot be compared, snapshotted or reasoned about independently of
+ * the component that produced it. Keeping the two apart is what lets the
+ * renderers be checked as pure functions of their inputs.
+ *
+ * ## Pattern-library standard
+ *
+ * Every pattern component should follow this shape:
+ *
+ * - `view-model/<pattern>.view-model.ts` exporting a plain data class;
+ * - construction through a single `static from(state)` factory;
+ * - no inheritance, and no logic beyond derivation from the state passed in;
+ * - consumed by renderer slimmers, never mutated by them.
+ *
+ * Note this is a *view model*, not a DTO: it never crosses a process or
+ * serialisation boundary, only the boundary between the stateful layer
+ * (slimmers) and the rendering layer. DTO semantics — validation, wire format —
+ * belong at the provider seam, where data genuinely enters from outside.
+ */
+export class LoginStepViewModel {
+    constructor(
+    /** The step being rendered. */
+    step, 
+    /** Resolved copy, after merging any consumer overrides. */
+    copy, 
+    /** Heading for this step. */
+    heading, 
+    /** Supporting description, when this step has one. */
+    description, 
+    /** Error copy to surface, already mapped to approved wording. */
+    errorText, 
+    /** Whether a provider call is in flight. */
+    busy, 
+    /** Which affordances the provider can service. */
+    can, 
+    /** MFA methods offered by the provider. */
+    methods, 
+    /** Values collected on the current step. */
+    values, 
+    /** How many characters the passcode entry expects. */
+    otpLength, 
+    /** Seconds left on the resend throttle; zero when resending is allowed. */
+    resendSeconds) {
+        this.step = step;
+        this.copy = copy;
+        this.heading = heading;
+        this.description = description;
+        this.errorText = errorText;
+        this.busy = busy;
+        this.can = can;
+        this.methods = methods;
+        this.values = values;
+        this.otpLength = otpLength;
+        this.resendSeconds = resendSeconds;
+    }
+    static from(state) {
+        const { step, copy } = state;
+        return new LoginStepViewModel(step, copy, headingFor(step, copy), descriptionFor(step, copy, state), state.errorText, state.busy, state.can, state.methods, state.values, state.otpLength, state.resendSeconds);
+    }
+    /** Steps that render no form: terminal outcomes and confirmations. */
+    get isTerminal() {
+        return this.step === 'success' || this.step === 'locked' || this.step === 'check-email';
+    }
+    /** Whether a resend is currently throttled. */
+    get isResendThrottled() {
+        return this.resendSeconds > 0;
+    }
+    /** Copy for the throttle countdown, with the remaining seconds applied. */
+    get resendCountdownText() {
+        return formatLabel(this.copy.resendCodeIn, { seconds: this.resendSeconds });
+    }
+    /** The current value of a collected field, as a string. */
+    valueOf(name) {
+        const value = this.values[name];
+        return typeof value === 'string' ? value : '';
+    }
+    /** Whether a boolean field is set. */
+    isChecked(name) {
+        return this.values[name] === true;
+    }
+}
+function headingFor(step, copy) {
+    const headings = {
+        identifier: copy.identifierHeading,
+        password: copy.passwordHeading,
+        'mfa-method': copy.mfaMethodHeading,
+        otp: copy.otpHeading,
+        'forgot-password': copy.forgotPasswordHeading,
+        'forgot-username': copy.forgotUsernameHeading,
+        'reset-password': copy.resetPasswordHeading,
+        'sign-up': copy.signUpHeading,
+        'check-email': copy.checkEmailHeading,
+        locked: copy.lockedHeading,
+        success: copy.successHeading,
+    };
+    return headings[step];
+}
+function descriptionFor(step, copy, ctx) {
+    switch (step) {
+        case 'mfa-method':
+            return copy.mfaMethodDescription;
+        case 'otp':
+            return ctx.otpMethodLabel
+                ? formatLabel(copy.otpDescriptionForMethod, { method: ctx.otpMethodLabel })
+                : copy.otpDescription;
+        case 'forgot-password':
+            return copy.forgotPasswordDescription;
+        case 'forgot-username':
+            return copy.forgotUsernameDescription;
+        case 'sign-up':
+            return copy.signUpDescription;
+        case 'check-email':
+            return ctx.destination
+                ? formatLabel(copy.checkEmailDescriptionWithDestination, { destination: ctx.destination })
+                : copy.checkEmailDescription;
+        case 'locked':
+            return ctx.unlockMinutes
+                ? formatLabel(copy.lockedDescriptionWithTime, { minutes: ctx.unlockMinutes })
+                : copy.lockedDescription;
+        default:
+            return undefined;
+    }
+}

package/dist/collection/components/uds-pattern-login-page/uds-pattern-login-page.css

@@ -0,0 +1,37 @@
+:host {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+  box-sizing: border-box;
+  font-family: var(--uds-pattern-font-family);
+  color: var(--uds-pattern-color-text);
+  background: var(--uds-pattern-color-background);
+}
+
+.masthead {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  padding: var(--uds-pattern-space-md) var(--uds-pattern-space-lg);
+  background: var(--uds-pattern-color-surface);
+}
+
+.masthead__logo {
+  display: block;
+  max-height: 2rem;
+}
+
+.content {
+  display: flex;
+  flex: 1;
+  justify-content: center;
+  align-items: center;
+  padding: var(--uds-pattern-space-xl) var(--uds-pattern-space-md);
+}
+
+.page-footer:not(:empty) {
+  padding: var(--uds-pattern-space-md) var(--uds-pattern-space-lg);
+  text-align: center;
+  font-size: var(--uds-pattern-font-size-sm);
+  color: var(--uds-pattern-color-text-subtle);
+}

package/dist/collection/components/uds-pattern-login-page/uds-pattern-login-page.js

@@ -0,0 +1,97 @@
+import { h, Host } from "@stencil/core";
+/**
+ * Full-page layout shell for authentication screens: branded masthead, a
+ * centred content column sized for `uds-pattern-login-card`, and an optional legal
+ * footer.
+ *
+ * It exists so consuming portals do not re-implement the same centred,
+ * responsive, brandable login layout for every product.
+ *
+ * @slot brand - Replaces the default masthead logo (e.g. a partner lockup).
+ * @slot - The authentication card, typically a `uds-pattern-login-card`.
+ * @slot footer - Legal / utility links rendered beneath the content column.
+ */
+export class UdsPatternLoginPage {
+    constructor() {
+        /** Accessible name for the masthead logo. */
+        this.logoAlt = '';
+    }
+    render() {
+        const logo = this.logoSrc ? h("img", { class: "masthead__logo", src: this.logoSrc, alt: this.logoAlt }) : null;
+        return (h(Host, { key: '7c2d0d6ae80dc7e52c0780c457de982738ef8faa' }, h("header", { key: '7eac231827e53a5e4018591506f7632aff8ddda5', class: "masthead" }, h("slot", { key: 'e80b31f6301079a15f45066189c646ed4c444e24', name: "brand" }, this.logoHref && logo ? h("a", { href: this.logoHref }, logo) : logo)), h("main", { key: '3081bf6ec017cff44900f6cd0d9c98b38baf5126', class: "content" }, h("slot", { key: '3c84048fae834578b00254e6bdbad4eecc74b5e2' })), h("footer", { key: 'dfb064a71e3f39c8e99212b523d043f9f9f20538', class: "page-footer" }, h("slot", { key: '5ea9ef897c20a96f3c42b2b4f54496155516a423', name: "footer" }))));
+    }
+    static get is() { return "uds-pattern-login-page"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["uds-pattern-login-page.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["uds-pattern-login-page.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "logoSrc": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "URL of the masthead logo. Ignored when the `brand` slot is used."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "logo-src"
+            },
+            "logoAlt": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Accessible name for the masthead logo."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "logo-alt",
+                "defaultValue": "''"
+            },
+            "logoHref": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Destination for the masthead logo link. When unset the logo is not a link."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "logo-href"
+            }
+        };
+    }
+}

package/dist/collection/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_LOGIN_LABELS, formatLabel } from './utils/labels';
+export { createAuthProvider } from './providers/auth-provider';
+export { createMemoryAuthProvider } from './providers/memory-auth-provider';
+export { createControlStrategy, fail, goTo, stay } from './providers/control-strategy';
+export { createLoginConfig } from './providers/login-config';

package/dist/collection/providers/auth-provider.js

@@ -0,0 +1,28 @@
+/**
+ * Provider contracts for the GP pattern library.
+ *
+ * A pattern owns the *workflow* — which step comes next, what is in flight,
+ * what the user is told when something fails. It owns no SDK code and knows no
+ * identity platform. The seam between the two is a Provider contract: the
+ * consumer brings their own backend SDK (Okta, Auth0, Cognito, Ping, GCP API
+ * Gateway, Azure APIM, …) and writes a thin adapter against the interface
+ * below.
+ *
+ * See `docs/adr/0002-provider-driven-patterns.md` for why the workflow lives
+ * inside the pattern rather than in the host application.
+ */
+/**
+ * Identity helper that gives adapter authors type inference and a single place
+ * to add shared behaviour later (telemetry, retry, logging) without changing
+ * every call site.
+ *
+ * ```ts
+ * const auth = createAuthProvider({
+ *   signIn: ({ identifier, password }) => oktaSdk.authn(identifier, password),
+ *   verifyOtp: ({ code }) => oktaSdk.verifyFactor(code),
+ * });
+ * ```
+ */
+export function createAuthProvider(provider) {
+    return provider;
+}

package/dist/collection/providers/control-strategy.js

@@ -0,0 +1,21 @@
+/** Moves the workflow to `step`. */
+export const goTo = (step) => ({ type: 'goto', step });
+/** Leaves the workflow where it is. */
+export const stay = () => ({ type: 'stay' });
+/** Surfaces a failure without moving. */
+export const fail = (code, message) => ({
+    type: 'fail',
+    code,
+    message,
+});
+/**
+ * Runs a checkpoint through the strategy, falling back to the pattern's own
+ * behaviour when the strategy does not intercept it.
+ */
+export function intercept(interceptor, context, fallback) {
+    return interceptor ? interceptor(context, fallback) : fallback();
+}
+/** Identity helper giving a strategy literal its types without a type annotation. */
+export function createControlStrategy(strategy) {
+    return strategy;
+}

package/dist/collection/providers/login-config.js

@@ -0,0 +1,4 @@
+/** Identity helper giving a config literal its types without an annotation. */
+export function createLoginConfig(config) {
+    return config;
+}

package/dist/collection/providers/memory-auth-provider.js

@@ -0,0 +1,133 @@
+import { createAuthProvider } from "./auth-provider";
+const DEFAULT_USER = {
+    identifier: 'ada@example.com',
+    password: 'correct-horse',
+    mfaMethods: [
+        { id: 'app', label: 'Authenticator app', description: 'Use the code from your authenticator app' },
+        { id: 'sms', label: 'Text message', description: 'Ending in ••3312' },
+    ],
+    otpCode: '555555',
+};
+/**
+ * An in-memory reference implementation of {@link UdsAuthProvider}.
+ *
+ * It exists so the demo harness and the test suite can drive the *real*
+ * workflow — identifier → password → MFA choice → OTP → success, plus the
+ * recovery, lockout and sign-up branches — without a network or an identity
+ * platform. It is also the worked example adapter authors copy from.
+ *
+ * Not intended for production use: it compares passwords in plain text.
+ */
+export function createMemoryAuthProvider(options = {}) {
+    const users = options.users ?? [DEFAULT_USER];
+    const maxAttempts = options.maxAttempts ?? 3;
+    const resendAfterMs = options.resendAfterMs ?? 30000;
+    const caps = {
+        signUp: true,
+        requestPasswordReset: true,
+        requestUsernameReminder: true,
+        resendOtp: true,
+        ...options.capabilities,
+    };
+    // Server-side state of the in-flight attempt.
+    let pending;
+    let failures = 0;
+    let locked = false;
+    const find = (identifier) => users.find(u => u.identifier.toLowerCase() === identifier.trim().toLowerCase());
+    const afterPassword = (user) => {
+        failures = 0;
+        if (user.mustResetPassword) {
+            return { status: 'password_reset_required' };
+        }
+        if (user.mfaMethods?.length) {
+            return { status: 'mfa_required', methods: user.mfaMethods };
+        }
+        return { status: 'success', session: { identifier: user.identifier } };
+    };
+    const provider = {
+        async signIn({ identifier, password }) {
+            if (locked) {
+                return { status: 'locked' };
+            }
+            const user = find(identifier);
+            if (!user) {
+                return { status: 'error', code: 'account_not_found' };
+            }
+            pending = user;
+            // Identifier-first: no password supplied yet.
+            if (password === undefined) {
+                return { status: 'password_required' };
+            }
+            return provider.verifyPassword({ identifier, password });
+        },
+        async verifyPassword({ password }) {
+            if (locked) {
+                return { status: 'locked' };
+            }
+            if (!pending) {
+                return { status: 'error', code: 'unknown' };
+            }
+            if (password !== pending.password) {
+                failures += 1;
+                if (failures >= maxAttempts) {
+                    locked = true;
+                    return { status: 'locked', unlockAfterMs: 15 * 60000 };
+                }
+                return { status: 'error', code: 'invalid_credentials' };
+            }
+            return afterPassword(pending);
+        },
+        async selectMfaMethod({ methodId }) {
+            const method = pending?.mfaMethods?.find(m => m.id === methodId);
+            return { status: 'otp_required', method, codeLength: 6, resendAfterMs };
+        },
+        async verifyOtp({ code }) {
+            if (code !== (pending?.otpCode ?? DEFAULT_USER.otpCode)) {
+                failures += 1;
+                if (failures >= maxAttempts) {
+                    locked = true;
+                    return { status: 'locked' };
+                }
+                return { status: 'error', code: 'invalid_code' };
+            }
+            failures = 0;
+            return { status: 'success', session: { identifier: pending?.identifier } };
+        },
+        async resetPassword({ password }) {
+            if (password.length < 8) {
+                return { status: 'error', code: 'password_policy' };
+            }
+            if (pending) {
+                pending.password = password;
+                pending.mustResetPassword = false;
+            }
+            return { status: 'success', session: { identifier: pending?.identifier } };
+        },
+    };
+    if (caps.resendOtp) {
+        provider.resendOtp = async () => ({ status: 'otp_required', codeLength: 6, resendAfterMs });
+    }
+    if (caps.requestPasswordReset) {
+        provider.requestPasswordReset = async ({ identifier }) => {
+            const user = find(identifier);
+            return user
+                ? { status: 'reset_link_sent', destination: user.identifier }
+                : { status: 'error', code: 'account_not_found' };
+        };
+    }
+    if (caps.requestUsernameReminder) {
+        provider.requestUsernameReminder = async ({ email }) => ({ status: 'username_sent', destination: email });
+    }
+    if (caps.signUp) {
+        provider.signUp = async ({ firstName, lastName, identifier }) => {
+            if (find(identifier)) {
+                return { status: 'error', code: 'account_exists' };
+            }
+            const user = { identifier, password: '', otpCode: DEFAULT_USER.otpCode };
+            users.push(user);
+            pending = user;
+            return { status: 'success', session: { identifier, firstName, lastName } };
+        };
+    }
+    return createAuthProvider(provider);
+}

package/dist/collection/providers/parse-auth-result.js

@@ -0,0 +1,135 @@
+/**
+ * Runtime validation for the one boundary where data genuinely enters the
+ * pattern from outside: a provider's `UdsAuthResult`.
+ *
+ * ## Why validate here and nowhere else
+ *
+ * `UdsAuthResult` is a *DTO* in the strict sense — it crosses a trust boundary.
+ * An adapter is written by a consuming team, usually by mapping a vendor SDK's
+ * response, and TypeScript's guarantees stop at the seam: a compiled adapter
+ * can still hand back `{ status: 'otp_requred' }` from a mistyped mapping, or
+ * `{ status: 'mfa_required' }` with no `methods` because the vendor returned
+ * `null`.
+ *
+ * Unvalidated, those land as *silence*. The workflow's `switch` falls through,
+ * the card stays on its current step, no error is raised, and the user sees a
+ * button that does nothing. Debugging that means reading our source. Validated,
+ * the same mistake names itself at the point it was made.
+ *
+ * The view model deliberately has no equivalent: it never crosses a boundary,
+ * only moves between layers that are compiled together, so checking it at
+ * runtime would buy nothing the compiler has not already proven.
+ *
+ * ## Failure policy
+ *
+ * A malformed result is converted into an `unknown` error — the user always
+ * sees approved copy — and reported on the console with the offending value.
+ * The pattern never throws into a consumer's promise chain for this.
+ */
+const RESULT_STATUSES = [
+    'success',
+    'password_required',
+    'mfa_required',
+    'otp_required',
+    'password_reset_required',
+    'reset_link_sent',
+    'username_sent',
+    'locked',
+    'error',
+];
+const ERROR_CODES = [
+    'invalid_credentials',
+    'invalid_identifier',
+    'invalid_code',
+    'code_expired',
+    'account_locked',
+    'account_not_found',
+    'account_exists',
+    'password_policy',
+    'passwords_do_not_match',
+    'rate_limited',
+    'network',
+    'unknown',
+];
+/** Thrown only internally; never surfaces to a consumer. */
+class InvalidAuthResultError extends Error {
+}
+/**
+ * Validates a provider's response, returning it narrowed to `UdsAuthResult`.
+ *
+ * @param value what the adapter returned
+ * @param source the provider method called, for the diagnostic message
+ */
+export function parseAuthResult(value, source) {
+    try {
+        return assertAuthResult(value, source);
+    }
+    catch (error) {
+        if (!(error instanceof InvalidAuthResultError)) {
+            throw error;
+        }
+        // eslint-disable-next-line no-console
+        console.error(`[uds-pattern-login-card] ${error.message}`, value);
+        return { status: 'error', code: 'unknown' };
+    }
+}
+function assertAuthResult(value, source) {
+    const result = value;
+    if (!result || typeof result !== 'object') {
+        throw new InvalidAuthResultError(`${source} resolved with ${describe(value)}, expected a UdsAuthResult object.`);
+    }
+    const status = result.status;
+    if (!RESULT_STATUSES.includes(status)) {
+        throw new InvalidAuthResultError(`${source} resolved with status ${describe(status)}. Expected one of: ${RESULT_STATUSES.join(', ')}.`);
+    }
+    switch (status) {
+        case 'mfa_required':
+            assertMethods(result.methods, source);
+            break;
+        case 'otp_required':
+            if (result.method !== undefined) {
+                assertMethod(result.method, source, 'method');
+            }
+            assertOptionalNumber(result.codeLength, source, 'codeLength');
+            assertOptionalNumber(result.resendAfterMs, source, 'resendAfterMs');
+            break;
+        case 'locked':
+            assertOptionalNumber(result.unlockAfterMs, source, 'unlockAfterMs');
+            break;
+        case 'error':
+            if (!ERROR_CODES.includes(result.code)) {
+                throw new InvalidAuthResultError(`${source} resolved with error code ${describe(result.code)}. Expected one of: ${ERROR_CODES.join(', ')}.`);
+            }
+            break;
+    }
+    return result;
+}
+function assertMethods(value, source) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new InvalidAuthResultError(`${source} resolved with status 'mfa_required' but methods was ${describe(value)}. ` +
+            'Expected a non-empty array of UdsMfaMethod — the card has nothing to offer the user otherwise.');
+    }
+    value.forEach((method, index) => assertMethod(method, source, `methods[${index}]`));
+}
+function assertMethod(value, source, path) {
+    const method = value;
+    if (!method || typeof method !== 'object' || typeof method.id !== 'string' || typeof method.label !== 'string') {
+        throw new InvalidAuthResultError(`${source} resolved with ${path} = ${describe(value)}. Expected { id: string, label: string }.`);
+    }
+}
+function assertOptionalNumber(value, source, path) {
+    if (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value))) {
+        throw new InvalidAuthResultError(`${source} resolved with ${path} = ${describe(value)}. Expected a finite number or undefined.`);
+    }
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return `'${value}'`;
+    if (Array.isArray(value))
+        return `an array of ${value.length}`;
+    return typeof value === 'object' ? 'an object' : String(value);
+}

package/dist/collection/slimmer/common/log.js

@@ -0,0 +1,14 @@
+/** Console wrapper carrying a GP prefix, so framework diagnostics are traceable. */
+export class LogUtility {
+    static log(...message) {
+        console.log(`%c${this.PREFIX}`, this.PREFIX_STYLE, ...message);
+    }
+    static warn(...message) {
+        console.warn(`%c${this.PREFIX}`, this.PREFIX_STYLE, ...message);
+    }
+    static error(...message) {
+        console.error(`%c${this.PREFIX}`, this.PREFIX_STYLE, ...message);
+    }
+}
+LogUtility.PREFIX = '[GP]';
+LogUtility.PREFIX_STYLE = 'font-weight: bold';

package/dist/collection/slimmer/common/symbols.js

@@ -0,0 +1,10 @@
+/**
+ * Internal markers used to attach slimmer wiring to component and slimmer
+ * instances without colliding with any real field name.
+ */
+/** On a slimmer prototype: the list of component methods it hooks into. */
+export const SlimmerMappedMethod = Symbol('SlimmerMappedMethod');
+/** On a slimmer instance: the component that injected it. */
+export const SlimmerConsumedBy = Symbol('SlimmerConsumedBy');
+/** On a component instance: the slimmers it has injected, keyed by field name. */
+export const ConsumerSlimmers = Symbol('ConsumerSlimmers');

package/dist/collection/slimmer/common/types.js

@@ -0,0 +1,2 @@
+/** Narrows the `Object` a decorator is handed to something indexable. */
+export const asBag = (target) => target;