Improved welcome email user flow for editing and activating (#26035)

closes
https://linear.app/ghost/issue/NY-842/editing-viewing-email-before-setting-to-active

- previously a user needed to toggle a welcome email to active before
they could edit it because the button was hidden. this meant there was a
scenario where a new member could sign up before the admin was done
editing, and get the default welcome email text
- this PR updates the UI so that the welcome email can be edited
separately from activating it
- also some improvements for accessibility, markup semantics, and
keyboard interactivity

Author: peterzimon

apps/admin-x-settings/src/components/settings/membership/member-emails.tsx

@@ -3,7 +3,7 @@ import NiceModal from '@ebay/nice-modal-react';
 import React from 'react';
 import TopLevelGroup from '../../top-level-group';
 import WelcomeEmailModal from './member-emails/welcome-email-modal';
-import {Button, Separator, SettingGroupContent, Toggle, withErrorBoundary} from '@tryghost/admin-x-design-system';
+import {Separator, SettingGroupContent, Toggle, showToast, withErrorBoundary} from '@tryghost/admin-x-design-system';
 import {checkStripeEnabled, getSettingValues} from '@tryghost/admin-x-framework/api/settings';
 import {useAddAutomatedEmail, useBrowseAutomatedEmails, useEditAutomatedEmail} from '@tryghost/admin-x-framework/api/automated-emails';
 import {useGlobalData} from '../../providers/global-data-provider';
@@ -18,10 +18,18 @@ const DEFAULT_PAID_LEXICAL_CONTENT = '{"root":{"children":[{"children":[{"detail
 
 const EmailPreview: React.FC<{
     automatedEmail: AutomatedEmail,
-    emailType: 'free' | 'paid'
+    emailType: 'free' | 'paid',
+    enabled: boolean,
+    isInitialLoading: boolean,
+    onEdit: () => void,
+    onToggle: () => void
 }> = ({
     automatedEmail,
-    emailType
+    emailType,
+    enabled,
+    isInitialLoading,
+    onEdit,
+    onToggle
 }) => {
     const {settings} = useGlobalData();
     const [accentColor, icon, siteTitle] = getSettingValues<string>(settings, ['accent_color', 'icon', 'title']);
@@ -30,34 +38,60 @@ const EmailPreview: React.FC<{
     const senderName = automatedEmail.sender_name || siteTitle || 'Your Site';
 
     return (
-        <div className='mb-5 flex items-center justify-between gap-3 rounded-lg border border-grey-100 bg-grey-50 p-5 dark:border-grey-925 dark:bg-grey-975'>
-            <div className='flex items-start gap-3'>
-                {icon ?
-                    <div className='size-10 min-h-10 min-w-10 rounded-sm bg-cover bg-center' style={{
-                        backgroundImage: `url(${icon})`
-                    }} />
-                    :
-                    <div className='flex aspect-square size-10 items-center justify-center overflow-hidden rounded-full p-1 text-white' style={{
-                        backgroundColor: color
-                    }}>
-                        <img className='h-auto w-8' src={FakeLogo} />
+        <div
+            className='relative flex w-full items-center justify-between gap-6 rounded-lg border border-grey-100 bg-grey-50 p-5 text-left transition-all hover:border-grey-200 hover:shadow-sm dark:border-grey-925 dark:bg-grey-975 dark:hover:border-grey-800'
+            data-testid={`${emailType}-welcome-email-preview`}
+        >
+            <button
+                className='flex w-full cursor-pointer items-center justify-between before:absolute before:inset-0 before:rounded-lg before:content-[""] focus-visible:outline-none focus-visible:before:ring-2 focus-visible:before:ring-green'
+                type='button'
+                onClick={onEdit}
+            >
+                <div className='flex items-start gap-3'>
+                    {icon ?
+                        <div className='size-10 min-h-10 min-w-10 rounded-sm bg-cover bg-center' style={{
+                            backgroundImage: `url(${icon})`
+                        }} />
+                        :
+                        <div className='flex aspect-square size-10 items-center justify-center overflow-hidden rounded-full p-1 text-white' style={{
+                            backgroundColor: color
+                        }}>
+                            <img alt="" className='h-auto w-8' src={FakeLogo} />
+                        </div>
+                    }
+                    <div className='text-left'>
+                        <div className='font-semibold'>{senderName}</div>
+                        <div className='text-sm'>{automatedEmail.subject}</div>
                     </div>
-                }
-                <div>
-                    <div className='font-semibold'>{senderName}</div>
-                    <div className='text-sm'>{automatedEmail.subject}</div>
                 </div>
+                <div className='text-sm font-semibold opacity-100 transition-all hover:opacity-80'>
+                    Edit
+                </div>
+            </button>
+            <div className='relative z-10 rounded-full has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-green'>
+                {isInitialLoading ? (
+                    <div className="h-4 w-7 rounded-full bg-grey-300 dark:bg-grey-800" />
+                ) : (
+                    <Toggle
+                        checked={enabled}
+                        onChange={onToggle}
+                    />
+                )}
+            </div>
+        </div>
+    );
+};
+
+const EmailSettingRow: React.FC<{
+    title: string,
+    description: string
+}> = ({title, description}) => {
+    return (
+        <div className='flex items-center justify-between py-4'>
+            <div>
+                <div className='font-medium'>{title}</div>
+                <div className='text-sm text-grey-700 dark:text-grey-600'>{description}</div>
             </div>
-            <Button
-                className='border border-grey-200 font-semibold hover:border-grey-300 dark:border-grey-900 dark:hover:border-grey-800 dark:hover:bg-grey-950'
-                color='white'
-                data-testid={`${emailType}-welcome-email-edit-button`}
-                icon='pen'
-                label='Edit'
-                onClick={() => {
-                    NiceModal.show(WelcomeEmailModal, {emailType, automatedEmail});
-                }}
-            />
         </div>
     );
 };
@@ -67,51 +101,101 @@ const MemberEmails: React.FC<{ keywords: string[] }> = ({keywords}) => {
     const [siteTitle] = getSettingValues<string>(settings, ['title']);
 
     const {data: automatedEmailsData, isLoading} = useBrowseAutomatedEmails();
-    const {mutateAsync: addAutomatedEmail} = useAddAutomatedEmail();
-    const {mutateAsync: editAutomatedEmail} = useEditAutomatedEmail();
+    const {mutateAsync: addAutomatedEmail, isLoading: isAddingAutomatedEmail} = useAddAutomatedEmail();
+    const {mutateAsync: editAutomatedEmail, isLoading: isEditingAutomatedEmail} = useEditAutomatedEmail();
     const handleError = useHandleError();
 
     const automatedEmails = automatedEmailsData?.automated_emails || [];
+    const isMutating = isAddingAutomatedEmail || isEditingAutomatedEmail;
+    const isBusy = isLoading || isMutating;
 
     const freeWelcomeEmail = automatedEmails.find(email => email.slug === 'member-welcome-email-free');
     const paidWelcomeEmail = automatedEmails.find(email => email.slug === 'member-welcome-email-paid');
 
     const freeWelcomeEmailEnabled = freeWelcomeEmail?.status === 'active';
     const paidWelcomeEmailEnabled = paidWelcomeEmail?.status === 'active';
 
+    // Helper to get default values for an email type
+    const getDefaultEmailValues = (emailType: 'free' | 'paid') => ({
+        name: emailType === 'free' ? 'Welcome Email (Free)' : 'Welcome Email (Paid)',
+        slug: `member-welcome-email-${emailType}`,
+        subject: emailType === 'free'
+            ? `Welcome to ${siteTitle || 'our site'}`
+            : 'Welcome to your paid subscription',
+        lexical: emailType === 'free' ? DEFAULT_FREE_LEXICAL_CONTENT : DEFAULT_PAID_LEXICAL_CONTENT
+    });
+
+    // Create default email objects for display when no DB row exists
+    const getDefaultEmail = (emailType: 'free' | 'paid'): AutomatedEmail => ({
+        id: '',
+        status: 'inactive',
+        ...getDefaultEmailValues(emailType),
+        sender_name: null,
+        sender_email: null,
+        sender_reply_to: null,
+        created_at: '',
+        updated_at: null
+    });
+
+    // Create a new automated email row with the given status
+    const createAutomatedEmail = async (emailType: 'free' | 'paid', status: 'active' | 'inactive') => {
+        const defaults = getDefaultEmailValues(emailType);
+        return addAutomatedEmail({...defaults, status});
+    };
+
     const handleToggle = async (emailType: 'free' | 'paid') => {
         const slug = `member-welcome-email-${emailType}`;
         const existing = automatedEmails.find(email => email.slug === slug);
+        const label = emailType === 'free' ? 'Free members' : 'Paid members';
 
-        const defaultSubject = emailType === 'free'
-            ? `Welcome to ${siteTitle || 'our site'}`
-            : 'Welcome to your paid subscription';
+        if (isBusy) {
+            return;
+        }
 
         try {
             if (!existing) {
-                // First toggle ON - create with defaults
-                const defaultContent = emailType === 'free'
-                    ? DEFAULT_FREE_LEXICAL_CONTENT
-                    : DEFAULT_PAID_LEXICAL_CONTENT;
-                await addAutomatedEmail({
-                    name: emailType === 'free' ? 'Welcome Email (Free)' : 'Welcome Email (Paid)',
-                    slug: slug,
-                    subject: defaultSubject,
-                    status: 'active',
-                    lexical: defaultContent
-                });
+                await createAutomatedEmail(emailType, 'active');
+                showToast({type: 'success', title: `${label} welcome email enabled`});
             } else if (existing.status === 'active') {
-                // Toggle OFF
                 await editAutomatedEmail({...existing, status: 'inactive'});
+                showToast({type: 'success', title: `${label} welcome email disabled`});
             } else {
-                // Toggle ON (re-enable)
                 await editAutomatedEmail({...existing, status: 'active'});
+                showToast({type: 'success', title: `${label} welcome email enabled`});
             }
         } catch (e) {
             handleError(e);
         }
     };
 
+    // Handle Edit button click - creates inactive row if needed, then opens modal
+    const handleEditClick = async (emailType: 'free' | 'paid') => {
+        const slug = `member-welcome-email-${emailType}`;
+        const existing = automatedEmails.find(email => email.slug === slug);
+
+        if (isBusy) {
+            return;
+        }
+
+        if (!existing) {
+            try {
+                const result = await createAutomatedEmail(emailType, 'inactive');
+                const newEmail = result?.automated_emails?.[0];
+                if (newEmail) {
+                    NiceModal.show(WelcomeEmailModal, {emailType, automatedEmail: newEmail});
+                }
+            } catch (e) {
+                handleError(e);
+            }
+        } else {
+            NiceModal.show(WelcomeEmailModal, {emailType, automatedEmail: existing});
+        }
+    };
+
+    // Get email to display (existing or default for preview)
+    const freeEmailForDisplay = freeWelcomeEmail || getDefaultEmail('free');
+    const paidEmailForDisplay = paidWelcomeEmail || getDefaultEmail('paid');
+
     return (
         <TopLevelGroup
             description="Create and manage automated emails for your members"
@@ -122,46 +206,33 @@ const MemberEmails: React.FC<{ keywords: string[] }> = ({keywords}) => {
         >
             <SettingGroupContent className="!gap-y-0" columns={1}>
                 <Separator />
-                <Toggle
-                    key={`free-${isLoading ? 'loading' : freeWelcomeEmail?.status ?? 'none'}`}
-                    checked={Boolean(freeWelcomeEmailEnabled)}
-                    containerClasses='items-center'
-                    direction='rtl'
-                    disabled={isLoading}
-                    gap='gap-0'
-                    hint='Sent to new free members right after they join your site.'
-                    label='Free members'
-                    labelClasses='py-4 w-full'
-                    onChange={() => handleToggle('free')}
+                <EmailSettingRow
+                    description='Email new free members receive when they join your site.'
+                    title='Free members welcome email'
+                />
+                <EmailPreview
+                    automatedEmail={freeEmailForDisplay}
+                    emailType='free'
+                    enabled={freeWelcomeEmailEnabled}
+                    isInitialLoading={isLoading}
+                    onEdit={() => handleEditClick('free')}
+                    onToggle={() => handleToggle('free')}
                 />
-                {freeWelcomeEmail && freeWelcomeEmailEnabled &&
-                    <EmailPreview
-                        automatedEmail={freeWelcomeEmail}
-                        emailType='free'
-                    />
-                }
                 {checkStripeEnabled(settings, config) && (
-                    <>
-                        <Separator />
-                        <Toggle
-                            key={`paid-${isLoading ? 'loading' : paidWelcomeEmail?.status ?? 'none'}`}
-                            checked={Boolean(paidWelcomeEmailEnabled)}
-                            containerClasses='items-center'
-                            direction='rtl'
-                            disabled={isLoading}
-                            gap='gap-0'
-                            hint='Sent to new paid members right after they start their subscription.'
-                            label='Paid members'
-                            labelClasses='py-4 w-full'
-                            onChange={() => handleToggle('paid')}
+                    <div className='mt-4'>
+                        <EmailSettingRow
+                            description='Sent to new paid members as soon as they start their subscription.'
+                            title='Paid members welcome email'
                         />
-                        {paidWelcomeEmail && paidWelcomeEmailEnabled &&
-                            <EmailPreview
-                                automatedEmail={paidWelcomeEmail}
-                                emailType='paid'
-                            />
-                        }
-                    </>
+                        <EmailPreview
+                            automatedEmail={paidEmailForDisplay}
+                            emailType='paid'
+                            enabled={paidWelcomeEmailEnabled}
+                            isInitialLoading={isLoading}
+                            onEdit={() => handleEditClick('paid')}
+                            onToggle={() => handleToggle('paid')}
+                        />
+                    </div>
                 )}
             </SettingGroupContent>
         </TopLevelGroup>