@visns-studio/visns-components 6.6.3 → 6.15.0

package/src/components/auth/ClientAuth.jsx

@@ -0,0 +1,161 @@
+import React, { useState } from 'react';
+
+import ClientLogin from './ClientLogin';
+import ClientOTPVerify from './ClientOTPVerify';
+
+/**
+ * Both client sign-in steps on one page.
+ *
+ * ClientLogin and ClientOTPVerify were written as two routes with a router
+ * navigation between them. That is one shape a sign-in can take; the other is
+ * a single page that swaps its own contents, which is what the Next.js portal
+ * does and what an App Router page can actually host. This composes the two
+ * screens into that shape by holding the challenge in state instead of in
+ * router state.
+ *
+ * It needs no router, so it mounts cleanly under Next.js, and it is the whole
+ * of the "zero adapter code" story: a consumer supplies endpoints, a protocol
+ * name and an `onAuthenticated`, and writes nothing that knows a request body
+ * from a response field.
+ *
+ *   <ClientAuth
+ *       layout="split"
+ *       loginBg="/images/office.jpg"
+ *       branding={{ name: 'Client Portal', tagline: '…' }}
+ *       protocol="contact"
+ *       urls={{ login: '/api/auth/request-otp', verify: '/api/auth/login-otp' }}
+ *       usernameDomain="virtualportal.com.au"
+ *       showContactHint
+ *       showDevOtp
+ *       showMaskedContact
+ *       showContactField
+ *       resendCooldown={0}
+ *       onAuthenticated={(user, token) => {
+ *           setCookie('portal_token', token, { maxAge: 28800 });
+ *           setUserData(user);
+ *           router.push('/portal/dashboard');
+ *       }}
+ *   />
+ *
+ * Props are forwarded to whichever step owns them; `loginProps` and
+ * `verifyProps` are escape hatches for anything that has to differ between the
+ * two. The shared ones (logo, urls, protocol, …) are passed to both.
+ */
+
+const ClientAuth = ({
+    /** Shared. */
+    logo,
+    /**
+     * 'card' (default) renders exactly what every consumer rendered before
+     * 6.8.3: a box centred in the space the host page gives it. 'split' is the
+     * staff sign-in's two-pane language — brand on one side, task on the other
+     * — sized to fill its PARENT rather than the viewport, so the consumer
+     * keeps its own header and footer and hands this the space between.
+     */
+    layout = 'card',
+    /** Split layout: the brand panel's photograph. Ignored by 'card'. */
+    loginBg,
+    /**
+     * Split layout: {eyebrow, name, tagline, footer}, rendered in the same
+     * type hierarchy as the staff Login's brand panel. Ignored by 'card'.
+     */
+    branding,
+    urls,
+    paths,
+    protocol,
+    contactField,
+    usernameDomain = null,
+    showDevOtp = false,
+    onError,
+
+    /** Step one. */
+    showContactHint = false,
+    contactHints,
+    loginCopy,
+    loginLabels,
+
+    /** Step two. */
+    resendCooldown = 60,
+    showMaskedContact = false,
+    showContactField = false,
+    minimalResponse = true,
+    verifyCopy,
+    verifyLabels,
+
+    /** Called with `(user, token, rawResponse)` on a successful verification. */
+    onAuthenticated,
+
+    /** Notified with the challenge each time a code is sent. */
+    onCodeSent,
+
+    /** Extra props for either step, merged last. */
+    loginProps = {},
+    verifyProps = {},
+}) => {
+    const [challenge, setChallenge] = useState(null);
+    // What the user typed, kept across the back link so returning to step one
+    // does not blank the field.
+    const [contact, setContact] = useState('');
+
+    if (challenge) {
+        return (
+            <ClientOTPVerify
+                logo={logo}
+                layout={layout}
+                loginBg={loginBg}
+                branding={branding}
+                urls={urls}
+                paths={paths}
+                protocol={protocol}
+                contactField={contactField}
+                challenge={challenge}
+                copy={verifyCopy}
+                labels={verifyLabels}
+                resendCooldown={resendCooldown}
+                showMaskedContact={showMaskedContact}
+                showContactField={showContactField}
+                showDevOtp={showDevOtp}
+                minimalResponse={minimalResponse}
+                onAuthenticated={onAuthenticated}
+                onError={onError}
+                // The back link clears the challenge rather than navigating.
+                // Passing it is also what stops the verify screen redirecting
+                // when it decides it has nothing to answer.
+                onBack={() => setChallenge(null)}
+                {...verifyProps}
+            />
+        );
+    }
+
+    return (
+        <ClientLogin
+            logo={logo}
+            layout={layout}
+            loginBg={loginBg}
+            branding={branding}
+            urls={urls}
+            paths={paths}
+            protocol={protocol}
+            contactField={contactField}
+            usernameDomain={usernameDomain}
+            showContactHint={showContactHint}
+            contactHints={contactHints}
+            showDevOtp={showDevOtp}
+            copy={loginCopy}
+            labels={loginLabels}
+            initialContact={contact}
+            onError={onError}
+            onChallengeIssued={(issued) => {
+                setContact(issued.rawContact || '');
+                setChallenge(issued);
+
+                if (typeof onCodeSent === 'function') {
+                    onCodeSent(issued);
+                }
+            }}
+            {...loginProps}
+        />
+    );
+};
+
+export default ClientAuth;

package/src/components/auth/ClientAuthFrame.jsx

@@ -0,0 +1,59 @@
+import React from 'react';
+
+import AuthBrandPanel from './AuthBrandPanel';
+
+/**
+ * The frame around a client sign-in step.
+ *
+ * Both steps render the same children — logo, title, subtitle, form — and the
+ * only thing `layout` changes is what sits around them. Keeping that choice
+ * here means neither ClientLogin nor ClientOTPVerify has to know there are two
+ * layouts, and the form markup stays untouched by the design work.
+ *
+ *   `card`  (default) — the original: a box centred in whatever vertical space
+ *                       the host page happens to give it. Byte-identical to
+ *                       what every consumer rendered before 6.8.3.
+ *   `split` — the staff sign-in's language: the brand on one side, the task on
+ *             the other. A SECTION rather than a screen, sized by its parent —
+ *             the consumer keeps its own header and footer and hands this the
+ *             space between, which is why there is no `100vh` in its styles.
+ */
+const ClientAuthFrame = ({
+    layout = 'card',
+    styles,
+    loginBg,
+    branding = {},
+    children,
+}) => {
+    if (layout === 'split') {
+        return (
+            <section className={styles.split}>
+                <AuthBrandPanel
+                    styles={styles}
+                    loginBg={loginBg}
+                    branding={branding}
+                />
+
+                <div className={styles.splitPane}>
+                    <div className={styles.splitCard}>
+                        {children}
+
+                        {branding.footer ? (
+                            <p className={styles.splitFoot}>
+                                {branding.footer}
+                            </p>
+                        ) : null}
+                    </div>
+                </div>
+            </section>
+        );
+    }
+
+    return (
+        <div className={styles.container}>
+            <div className={styles.loginBox}>{children}</div>
+        </div>
+    );
+};
+
+export default ClientAuthFrame;

package/src/components/auth/ClientLogin.jsx

@@ -1,19 +1,146 @@
 import '../styles/global.css';
 
 import React, { useState } from 'react';
-import { useLocation, useNavigate } from 'react-router-dom';
 import { toast } from 'react-toastify';
 import { User } from 'lucide-react';
 
 import CustomFetch from '../Fetch';
+import useOptionalRouter from './useOptionalRouter';
+import ClientAuthFrame from './ClientAuthFrame';
+import { resolveClientPaths } from './authEndpoints';
+import {
+    applyUsernameDomain,
+    contactHint,
+    normaliseAuthError,
+} from './authHelpers';
+import { resolveClientProtocol } from './clientAuthProtocols';
 
 import styles from '../styles/ClientAuth.module.scss';
 
-const ClientLogin = ({ logo, setSystemAuth, urls = {} }) => {
-    const location = useLocation();
-    const navigate = useNavigate();
+/**
+ * Client portal sign-in, step one: identify yourself, receive a code.
+ *
+ * Three things about this screen are configurable rather than assumed, because
+ * each was a blocker for the Next.js portal in 6.7.0:
+ *
+ *   - the WIRE PROTOCOL (`protocol`), because the two backends in the wild
+ *     disagree about the request body and about how success is signalled. See
+ *     clientAuthProtocols.js.
+ *   - the HAND-OFF to step two (`onChallengeIssued`), because a router
+ *     navigation carrying router state is one way to get there, not the only
+ *     one. An app rendering both steps on a single page just holds the
+ *     challenge in its own state.
+ *   - NAVIGATION (`onNavigate`), because react-router is not a given. The
+ *     router hooks are consulted only when nothing else was supplied, and only
+ *     when a Router actually exists.
+ *
+ * With none of those passed, this renders and behaves exactly as 6.6.3 did.
+ */
+
+const DEFAULT_COPY = {
+    title: 'Client Login',
+    subtitle:
+        'Enter your email address or mobile number to receive a verification code',
+    fieldLabel: 'Email or Mobile',
+    placeholder: 'Enter your email address or mobile number',
+    /** Client-side validation. */
+    required: 'Please enter your email address or mobile number',
+    /** Fallback when the server declines without saying why. */
+    notFound:
+        'Could not find an account with this email address or mobile number.',
+    sending: 'Sending verification code...',
+    sent: 'Verification code sent',
+};
+
+/**
+ * Button labels. These are the 6.6.3 strings, NOT the portal's — the
+ * backward-compatibility rule outranks matching the portal's wording, so an app
+ * that wants "Send Code" / "Please wait..." asks for them:
+ *   labels={{ submit: 'Send Code', submitting: 'Please wait...' }}
+ */
+const DEFAULT_LABELS = {
+    submit: 'Continue',
+    submitting: 'Sending...',
+};
+
+const ClientLogin = ({
+    logo,
+    setSystemAuth,
+    /** Endpoint map — `urls.login` is the request this screen makes. */
+    urls = {},
+    /** Route paths; `/client/*` unless overridden. See authEndpoints.js. */
+    paths,
+    /**
+     * Wire protocol: `'uuid'` (default, unchanged) or `'contact'` for
+     * ThroughLife's `/api/auth/*`. An object of overrides is accepted too.
+     */
+    protocol,
+    /** Merged over DEFAULT_COPY. */
+    copy: copyOverrides,
+    /** Merged over DEFAULT_LABELS. */
+    labels: labelOverrides,
+    /** Show the live "Email address detected" hint under the field. */
+    showContactHint = false,
+    /** Merged over DEFAULT_CONTACT_HINTS in authHelpers.js. */
+    contactHints,
+    /**
+     * Complete a bare username to `name@domain` before sending, the way the
+     * portal does (`virtualportal.com.au`). Null leaves the input untouched.
+     */
+    usernameDomain = null,
+    /**
+     * Overrides the protocol's own request-body key for the identifier. Left
+     * unset, `uuid` sends `email` and `contact` sends `contact`.
+     */
+    contactField,
+    /**
+     * Carry the server's dev OTP through to the verify screen so it can offer
+     * an auto-fill. Only ever honoured outside production.
+     */
+    showDevOtp = false,
+    /** Initial field value — used by the "keep what I typed" back link. */
+    initialContact,
+    /**
+     * 'card' (default, unchanged) or 'split' — the two-pane brand layout. See
+     * ClientAuthFrame; the form itself is identical either way.
+     */
+    layout = 'card',
+    /** Split layout: the brand panel's photograph. */
+    loginBg,
+    /** Split layout: {eyebrow, name, tagline, footer}. */
+    branding,
+    /**
+     * Called with the whole challenge once a code has been sent. When present,
+     * this screen does NOT navigate: the consumer owns what happens next.
+     *
+     * The challenge is `{contact, rawContact, challengeId, maskedContact,
+     * contactMethod, devOtp, message, previousUrl}` — everything
+     * ClientOTPVerify needs, in the shape its `challenge` prop takes.
+     */
+    onChallengeIssued,
+    /**
+     * Navigation, when this screen still owns it. `(path, options) => void`.
+     * Falls back to react-router's navigate, then to a plain page load.
+     */
+    onNavigate,
+    /** Notified with the normalised message when the request is declined. */
+    onError,
+}) => {
+    const { navigate, location } = useOptionalRouter();
+
+    const routes = resolveClientPaths(paths);
+    const wire = resolveClientProtocol(protocol);
+    const copy = { ...DEFAULT_COPY, ...(copyOverrides || {}) };
+    const labels = { ...DEFAULT_LABELS, ...(labelOverrides || {}) };
+    const field = contactField || wire.contactField;
+    const previousUrl = location?.state?.previousUrl || '';
+
     const [isLoading, setIsLoading] = useState(false);
-    const [email, setEmail] = useState('');
+    // Prefilled when the verify screen sent the user back with its "keep what I
+    // typed" back link. Nothing sets it otherwise, so this is '' as before.
+    const [email, setEmail] = useState(
+        initialContact ?? location?.state?.email ?? ''
+    );
     const [inputError, setInputError] = useState(false);
 
     const handleChange = (e) => {
@@ -21,77 +148,156 @@ const ClientLogin = ({ logo, setSystemAuth, urls = {} }) => {
         setInputError(false);
     };
 
+    /** Move, by whichever mechanism this app actually has. */
+    const go = (path, options) => {
+        if (typeof onNavigate === 'function') {
+            onNavigate(path, options);
+
+            return;
+        }
+
+        if (navigate) {
+            navigate(path, options);
+
+            return;
+        }
+
+        if (typeof window !== 'undefined') {
+            window.location.href = path;
+        }
+    };
+
+    const fail = (error) => {
+        const message = normaliseAuthError(error, copy.notFound);
+
+        setInputError(true);
+        toast.error(message);
+
+        if (typeof onError === 'function') {
+            onError(message);
+        }
+    };
+
     const handleSubmit = async (e) => {
         e.preventDefault();
 
+        // The button is disabled too; this is the belt to that pair of braces,
+        // since a form can also be submitted by Enter in the field.
+        if (isLoading) {
+            return;
+        }
+
         if (!email.trim()) {
             setInputError(true);
-            toast.error('Please enter your email address or mobile number');
+            toast.error(copy.required);
             return;
         }
 
         setIsLoading(true);
-        toast.info('Sending verification code...', { autoClose: 2000 });
+        toast.info(copy.sending, { autoClose: 2000 });
+
+        const rawContact = email.trim();
+        // A no-op unless `usernameDomain` is set.
+        const contact = applyUsernameDomain(rawContact, usernameDomain);
 
         try {
-            const loginUrl = urls.login;
-            const result = await CustomFetch(loginUrl, 'POST', {
-                email: email,
-                location:
-                    location.state && location.state.previousUrl
-                        ? location.state.previousUrl
-                        : '',
-            });
+            const result = await CustomFetch(
+                urls.login,
+                'POST',
+                wire.requestBody({
+                    contact,
+                    contactField: field,
+                    previousUrl,
+                    resend: false,
+                })
+            );
 
-            setIsLoading(false);
+            const body = result.data;
+
+            // Cleared per-branch: on success this screen hands over to step
+            // two, and dropping the button back to "Continue" first left a gap
+            // where a second code could be requested.
+            if (!wire.isSuccess(body)) {
+                setIsLoading(false);
+
+                if (typeof setSystemAuth === 'function') {
+                    setSystemAuth(false);
+                }
 
-            if (result.data && result.data.success) {
-                // Redirect to OTP verification page with email and uuid
-                const verifyUrl = '/client/verify';
-                navigate(verifyUrl, {
-                    state: {
-                        email: email,
-                        uuid: result.data.uuid,
-                        previousUrl: location.state?.previousUrl || '',
-                        // In development, we can pass the OTP for testing
-                        ...(process.env.NODE_ENV === 'development' && {
-                            otp: result.data.otp,
-                        }),
-                    },
-                });
-                toast.success(
-                    result.data.message ||
-                        'Verification code sent'
-                );
-            } else {
-                setSystemAuth(false);
-                setInputError(true);
-                toast.error(
-                    (result.data && result.data.message) ||
-                        'Could not find an account with this email address or mobile number.'
-                );
+                // `{error: '…'}` bodies are as common here as `{message}` ones,
+                // and only one of them used to reach the user.
+                fail(body);
+
+                return;
+            }
+
+            const read = wire.readChallenge(body);
+
+            // Everything step two needs, in one object. Both forms of the
+            // identifier travel: which one the verify call sends is the
+            // protocol's decision, not this screen's.
+            const challenge = {
+                contact,
+                rawContact,
+                challengeId: read.challengeId,
+                maskedContact: read.maskedContact,
+                contactMethod: read.contactMethod,
+                message: read.message,
+                previousUrl,
+                // Never in a production build, and never without the opt-in —
+                // the panel that renders it is gated a second time.
+                devOtp:
+                    process.env.NODE_ENV !== 'production' &&
+                    (showDevOtp || process.env.NODE_ENV === 'development')
+                        ? read.devOtp
+                        : null,
+            };
+
+            toast.success(read.message || copy.sent);
+
+            if (typeof onChallengeIssued === 'function') {
+                onChallengeIssued(challenge);
+
+                return;
             }
+
+            // Router state is the 6.6.3 hand-off. Both the old key spellings
+            // and the whole challenge are written, so an app already reading
+            // `state.uuid` keeps working.
+            go(routes.verify, {
+                state: {
+                    email: rawContact,
+                    contact: challenge.contact,
+                    uuid: challenge.challengeId,
+                    challenge,
+                    maskedContact: challenge.maskedContact,
+                    contactMethod: challenge.contactMethod,
+                    previousUrl,
+                    ...(challenge.devOtp ? { otp: challenge.devOtp } : {}),
+                },
+            });
         } catch (error) {
             setIsLoading(false);
-            setInputError(true);
-            toast.error(String(error));
+            fail(error);
         }
     };
 
     return (
-        <div className={styles.container}>
-            <div className={styles.loginBox}>
-                <img src={logo} alt="Client Portal" className={styles.logo} />
+        <ClientAuthFrame
+            layout={layout}
+            styles={styles}
+            loginBg={loginBg}
+            branding={branding}
+        >
+            <img src={logo} alt="Client Portal" className={styles.logo} />
 
-                <h1 className={styles.title}>Client Login</h1>
-                <p className={styles.subtitle}>
-                    Enter your email address or mobile number to receive a verification code
-                </p>
+                <h1 className={styles.title}>{copy.title}</h1>
+                <p className={styles.subtitle}>{copy.subtitle}</p>
 
                 <form onSubmit={handleSubmit}>
                     <div className={styles.formGroup}>
                         <label htmlFor="email" className={styles.inputLabel}>
-                            Email or Mobile
+                            {copy.fieldLabel}
                         </label>
                         <input
                             id="email"
@@ -102,12 +308,18 @@ const ClientLogin = ({ logo, setSystemAuth, urls = {} }) => {
                             className={`${styles.input} ${
                                 inputError ? styles.error : ''
                             }`}
-                            placeholder="Enter your email address or mobile number"
+                            placeholder={copy.placeholder}
                             autoComplete="username"
+                            disabled={isLoading}
                         />
                         <span className={styles.inputIcon}>
                             <User strokeWidth={2} size={18} />
                         </span>
+                        {showContactHint ? (
+                            <p className={styles.inputHint}>
+                                {contactHint(email, contactHints)}
+                            </p>
+                        ) : null}
                     </div>
 
                     <button
@@ -115,11 +327,10 @@ const ClientLogin = ({ logo, setSystemAuth, urls = {} }) => {
                         type="submit"
                         disabled={isLoading}
                     >
-                        {isLoading ? 'Sending...' : 'Continue'}
+                        {isLoading ? labels.submitting : labels.submit}
                     </button>
                 </form>
-            </div>
-        </div>
+        </ClientAuthFrame>
     );
 };