📧 Improve section descriptions (#547)

* Improve copy in the descriptions

* Add changeset

* Improve descriptions in the SMTP module

* Improve grammar

Co-authored-by: Adrian Pilarczyk <admin@peelar.dev>

.changeset/polite-badgers-relate.md

@@ -0,0 +1,5 @@
+---
+"saleor-app-emails-and-messages": patch
+---
+
+Added improved descriptions in the Sendgrid configuration views.

.changeset/popular-comics-sniff.md

@@ -0,0 +1,5 @@
+---
+"saleor-app-emails-and-messages": patch
+---
+
+Added improved descriptions in the Sendgrid configuration views.

apps/emails-and-messages/src/modules/app-configuration/ui/configuration-active-description-text.tsx

@@ -0,0 +1,7 @@
+import { Text } from "@saleor/macaw-ui/next";
+
+export const ConfigurationActiveDescriptionText = () => (
+  <Text as="p">
+    Marking the configuration as not active will prevent it from sending any messages.
+  </Text>
+);

apps/emails-and-messages/src/modules/app-configuration/ui/configuration-name-description-text.tsx

@@ -0,0 +1,9 @@
+import { Text } from "@saleor/macaw-ui/next";
+
+export const ConfigurationNameDescriptionText = () => (
+  <Text as="p">
+    The name for your configuration. You can have more than one if you want to use different settings for each channel.
+    <br />
+    For example - <code>production</code> and <code>development</code>.
+  </Text>
+);

apps/emails-and-messages/src/modules/sendgrid/ui/api-connection-section.tsx

@@ -14,6 +14,7 @@ import { SectionWithDescription } from "../../../components/section-with-descrip
 import { zodResolver } from "@hookform/resolvers/zod";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
 import { Input } from "@saleor/react-hook-form-macaw";
+import { SendgridApiKeyDescriptionText } from "./sendgrid-api-key-description-text";
 
 interface ApiConnectionSectionProps {
   configuration: SendgridConfiguration;
@@ -47,7 +48,7 @@ export const ApiConnectionSection = ({ configuration }: ApiConnectionSectionProp
   });
 
   return (
-    <SectionWithDescription title="API Connection">
+    <SectionWithDescription title="API Connection" description={<SendgridApiKeyDescriptionText />}>
       <BoxWithBorder>
         <form
           onSubmit={handleSubmit((data, event) => {

apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-api-key-description-text.tsx

@@ -0,0 +1,13 @@
+import { TextLink } from "@saleor/apps-ui";
+import { Text } from "@saleor/macaw-ui/next";
+
+export const SendgridApiKeyDescriptionText = () => (
+  <Text as="p">
+    The API keys can be found at your Sendgrid dashboard, in the Settings menu. You can find more
+    information in the{" "}
+    <TextLink href="https://docs.sendgrid.com/ui/account-and-settings/api-keys" newTab={true}>
+      documentation
+    </TextLink>
+    .
+  </Text>
+);

apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-basic-information-section.tsx

@@ -14,6 +14,8 @@ import { SectionWithDescription } from "../../../components/section-with-descrip
 import { zodResolver } from "@hookform/resolvers/zod";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
 import { Input } from "@saleor/react-hook-form-macaw";
+import { ConfigurationNameDescriptionText } from "../../app-configuration/ui/configuration-name-description-text";
+import { ConfigurationActiveDescriptionText } from "../../app-configuration/ui/configuration-active-description-text";
 
 interface SendgridBasicInformationSectionProps {
   configuration: SendgridConfiguration;
@@ -49,12 +51,12 @@ export const SendgridBasicInformationSection = ({
 
   return (
     <SectionWithDescription
-      title="Connect Sendgrid"
+      title="Status and name"
       description={
-        <Text>
+        <Box display="flex" flexDirection="column" gap={2}>
-          Provide unique name for your configuration - you can create more than one. For example -
+          <ConfigurationNameDescriptionText />
-          production and development. Then, pass your API Key. Obtain it here.
+          <ConfigurationActiveDescriptionText />
-        </Text>
+        </Box>
       }
     >
       <BoxWithBorder>

apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-events-section.tsx

@@ -19,6 +19,7 @@ import { fetchTemplates } from "../sendgrid-api";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
 import { Combobox } from "@saleor/react-hook-form-macaw";
+import { TextLink } from "@saleor/apps-ui";
 
 interface EventBoxProps {
   configuration: SendgridConfiguration;
@@ -100,13 +101,13 @@ export const SendgridEventsSection = ({ configuration }: SendgridEventsSectionPr
     <SectionWithDescription
       title="Events"
       description={
-        <>
         <Text as="p">
-            Provide unique name for your configuration - you can create more than one. For example -
+          Choose which Saleor events should send emails via Sendgrid. You can create and modify your templates in the
-            production and development.
+          <TextLink href="https://mc.sendgrid.com/dynamic-templates" newTab={true}>
+            Sendgrid dashboard
+          </TextLink>
+          .
         </Text>
-          <Text as="p">Then, pass your API Key. Obtain it here.</Text>
-        </>
       }
     >
       <Box display="flex" flexDirection="column" gap={defaultPadding}>

apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-sender-section.tsx

@@ -1,6 +1,6 @@
 import { SendgridConfiguration } from "../configuration/sendgrid-config-schema";
 import { BoxWithBorder } from "../../../components/box-with-border";
-import { Box, Button } from "@saleor/macaw-ui/next";
+import { Box, Button, Text } from "@saleor/macaw-ui/next";
 import { defaultPadding } from "../../../components/ui-defaults";
 import { useDashboardNotification } from "@saleor/apps-shared";
 import { trpcClient } from "../../trpc/trpc-client";
@@ -16,6 +16,7 @@ import { useQuery } from "@tanstack/react-query";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
 import { Combobox } from "@saleor/react-hook-form-macaw";
+import { TextLink } from "@saleor/apps-ui";
 
 interface SendgridSenderSectionProps {
   configuration: SendgridConfiguration;
@@ -50,7 +51,18 @@ export const SendgridSenderSection = ({ configuration }: SendgridSenderSectionPr
   });
 
   return (
-    <SectionWithDescription title="Sender">
+    <SectionWithDescription
+      title="Sender"
+      description={
+        <Text as="p">
+          Authenticating the sender is required to send emails. Configure your sender in{" "}
+          <TextLink href="https://app.sendgrid.com/settings/sender_auth" newTab={true}>
+            Sendgrid dashboard
+          </TextLink>{" "}
+          and choose it from the list.
+        </Text>
+      }
+    >
       <BoxWithBorder>
         <form
           onSubmit={handleSubmit((data, event) => {

apps/emails-and-messages/src/modules/smtp/ui/smtp-basic-information-section.tsx

@@ -4,7 +4,6 @@ import { Box, Button, Text } from "@saleor/macaw-ui/next";
 import { defaultPadding } from "../../../components/ui-defaults";
 import { useDashboardNotification } from "@saleor/apps-shared";
 import { trpcClient } from "../../trpc/trpc-client";
-import { z } from "zod";
 import { useForm } from "react-hook-form";
 import { BoxFooter } from "../../../components/box-footer";
 import { SectionWithDescription } from "../../../components/section-with-description";
@@ -15,6 +14,8 @@ import {
 import { zodResolver } from "@hookform/resolvers/zod";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
 import { Input } from "@saleor/react-hook-form-macaw";
+import { ConfigurationNameDescriptionText } from "../../app-configuration/ui/configuration-name-description-text";
+import { ConfigurationActiveDescriptionText } from "../../app-configuration/ui/configuration-active-description-text";
 
 interface SmtpBasicInformationSectionProps {
   configuration: SmtpConfiguration;
@@ -50,12 +51,12 @@ export const SmtpBasicInformationSection = ({
 
   return (
     <SectionWithDescription
-      title="Connect SMTP"
+      title="Status and name"
       description={
-        <Text>
+        <Box display="flex" flexDirection="column" gap={2}>
-          Provide unique name for your configuration - you can create more than one. For example -
+          <ConfigurationNameDescriptionText />
-          production and development. Then, pass your API Key. Obtain it here.
+          <ConfigurationActiveDescriptionText />
-        </Text>
+        </Box>
       }
     >
       <BoxWithBorder>

apps/emails-and-messages/src/modules/smtp/ui/smtp-events-section.tsx

@@ -12,6 +12,7 @@ import { useRouter } from "next/router";
 import { zodResolver } from "@hookform/resolvers/zod";
 import { smtpUrls } from "../urls";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
+import { TextLink } from "@saleor/apps-ui";
 
 interface EventBoxProps {
   configuration: SmtpConfiguration;
@@ -87,13 +88,16 @@ export const SmtpEventsSection = ({ configuration }: SmtpEventsSectionProps) =>
     <SectionWithDescription
       title="Events"
       description={
-        <>
+        <Box display="flex" flexDirection="column" gap={2}>
+          <Text as="p">Chose which Saleor events should send emails via SMTP.</Text>
           <Text as="p">
-            Provide unique name for your configuration - you can create more than one. For example -
+            You can modify the email templates using{" "}
-            production and development.
+            <TextLink href="https://mjml.io/" newTab={true}>
+              MJML
+            </TextLink>{" "}
+            syntax.
           </Text>
-          <Text as="p">Then, pass your API Key. Obtain it here.</Text>
+        </Box>
-        </>
       }
     >
       <Box display="flex" flexDirection="column" gap={defaultPadding}>

apps/emails-and-messages/src/modules/smtp/ui/smtp-section.tsx

@@ -48,7 +48,7 @@ export const SmtpSection = ({ configuration }: SmtpSectionProps) => {
   return (
     <SectionWithDescription
       title="Connect SMTP server"
-      description={<Text>Provide SMTP server configuration</Text>}
+      description={<Text>Provide SMTP server credentials.</Text>}
     >
       <BoxWithBorder>
         <form
@@ -61,7 +61,7 @@ export const SmtpSection = ({ configuration }: SmtpSectionProps) => {
           <Box padding={defaultPadding} display="flex" flexDirection="column" gap={7}>
             <Input
               label="Host"
-              helperText="Server host that will be connected."
+              helperText="Address of the SMTP server"
               control={control}
               name="smtpHost"
             />
@@ -69,19 +69,19 @@ export const SmtpSection = ({ configuration }: SmtpSectionProps) => {
               label="Port"
               name="smtpPort"
               control={control}
-              helperText="Port that will be used"
+              helperText="Port that will be used for SMTP connection"
             />
             <Input
               label="User"
               name="smtpUser"
               control={control}
-              helperText="User for the SMTP server connection"
+              helperText="User name for the SMTP server authentication"
             />
             <Input
               label="Password"
               name="smtpPassword"
               control={control}
-              helperText="Password for the SMTP server connection"
+              helperText="Password for the SMTP server authentication"
             />
 
             <Box display="flex" gap={defaultPadding}>

apps/emails-and-messages/src/modules/smtp/ui/smtp-sender-section.tsx

@@ -1,6 +1,6 @@
 import { SmtpConfiguration } from "../configuration/smtp-config-schema";
 import { BoxWithBorder } from "../../../components/box-with-border";
-import { Box, Button } from "@saleor/macaw-ui/next";
+import { Box, Button, Text } from "@saleor/macaw-ui/next";
 import { defaultPadding } from "../../../components/ui-defaults";
 import { useDashboardNotification } from "@saleor/apps-shared";
 import { trpcClient } from "../../trpc/trpc-client";
@@ -46,7 +46,17 @@ export const SmtpSenderSection = ({ configuration }: SmtpSenderSectionProps) =>
   });
 
   return (
-    <SectionWithDescription title="Sender">
+    <SectionWithDescription
+      title="Sender"
+      description={
+        <Box display="flex" flexDirection="column" gap={2}>
+          <Text as="p">
+            Sender&apos;s name and email address will be displayed as the author of an email.
+          </Text>
+          <Text as="p">Setting up the sender is required to send emails.</Text>
+        </Box>
+      }
+    >
       <BoxWithBorder>
         <form
           onSubmit={handleSubmit((data, event) => {

apps/emails-and-messages/src/pages/configuration/index.tsx

@@ -38,17 +38,15 @@ const ConfigurationPage: NextPage = () => {
       <Box display="grid" gridTemplateColumns={{ desktop: 3, mobile: 1 }}>
         <Box>
           <Text>
-            Configure Emails & Messages app to deliver Saleor Events webhooks to various messaging
+            Configure Emails & Messages app to deliver Saleor Event webhooks to configured messaging
-            providers
+            providers.
           </Text>
         </Box>
       </Box>
       <SectionWithDescription
         title="Messaging providers"
         description={
-          <Text>
+          <Text>Manage provider configurations and modify it&apos;s message templates.</Text>
-            Manage providers configuration to connect Saleor events with 3rd party services.
-          </Text>
         }
       >
         <MessagingProvidersBox configurations={data || []} isLoading={isLoading} />

apps/emails-and-messages/src/pages/configuration/sendgrid/new.tsx

@@ -1,4 +1,4 @@
-import { Box, Button, Input, Text } from "@saleor/macaw-ui/next";
+import { Box, Button, Text } from "@saleor/macaw-ui/next";
 import { NextPage } from "next";
 import { SectionWithDescription } from "../../../components/section-with-description";
 import { BoxWithBorder } from "../../../components/box-with-border";
@@ -13,6 +13,9 @@ import { useRouter } from "next/router";
 import { sendgridUrls } from "../../../modules/sendgrid/urls";
 import { appUrls } from "../../../modules/app-configuration/urls";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
+import { Input } from "@saleor/react-hook-form-macaw";
+import { SendgridApiKeyDescriptionText } from "../../../modules/sendgrid/ui/sendgrid-api-key-description-text";
+import { ConfigurationNameDescriptionText } from "../../../modules/app-configuration/ui/configuration-name-description-text";
 
 const NewSendgridConfigurationPage: NextPage = () => {
   const router = useRouter();
@@ -51,10 +54,10 @@ const NewSendgridConfigurationPage: NextPage = () => {
       <SectionWithDescription
         title="Connect Sendgrid"
         description={
-          <Text>
+          <Box display="flex" flexDirection="column" gap={2}>
-            Provide unique name for your configuration - you can create more than one. For example -
+            <ConfigurationNameDescriptionText />
-            production and development. Then, pass your API Key. Obtain it here.
+            <SendgridApiKeyDescriptionText />
-          </Text>
+          </Box>
         }
       >
         <BoxWithBorder>
@@ -66,46 +69,14 @@ const NewSendgridConfigurationPage: NextPage = () => {
             })}
           >
             <Box padding={defaultPadding} display="flex" flexDirection="column" gap={7}>
-              <Controller
+              <Input
                 name="name"
                 control={control}
-                render={({
-                  field: { onChange, value },
-                  fieldState: { error },
-                  formState: { errors },
-                }) => (
-                  <Input
                 label="Configuration name"
-                    value={value}
+                helperText={"Name of the configuration, for example 'Production' or 'Test'"}
-                    onChange={onChange}
-                    error={!!error}
-                    helperText={
-                      error?.message ||
-                      "Name of the configuration, for example 'Production' or 'Test'"
-                    }
-                  />
-                )}
-              />
-              <Controller
-                name="apiKey"
-                control={control}
-                render={({
-                  field: { onChange, value },
-                  fieldState: { error },
-                  formState: { errors },
-                }) => (
-                  // TODO: add validation
-                  <Input
-                    label="API key"
-                    value={value}
-                    onChange={onChange}
-                    error={!!error}
-                    helperText={
-                      error?.message || "Your API key, ensure it has permission XYZ enabled"
-                    }
-                  />
-                )}
               />
+              {/* TODO: add key validation */}
+              <Input name="apiKey" control={control} label="API key" helperText={"Your API key"} />
             </Box>
             <BoxFooter>
               <Button type="submit">Save provider</Button>

apps/emails-and-messages/src/pages/configuration/smtp/new.tsx

@@ -18,6 +18,7 @@ import { appUrls } from "../../../modules/app-configuration/urls";
 import { smtpUrls } from "../../../modules/smtp/urls";
 import { setBackendErrors } from "../../../lib/set-backend-errors";
 import { Input } from "@saleor/react-hook-form-macaw";
+import { ConfigurationNameDescriptionText } from "../../../modules/app-configuration/ui/configuration-name-description-text";
 
 const NewSmtpConfigurationPage: NextPage = () => {
   const router = useRouter();
@@ -57,12 +58,7 @@ const NewSmtpConfigurationPage: NextPage = () => {
       </Box>
       <SectionWithDescription
         title="Connect SMTP"
-        description={
+        description={<ConfigurationNameDescriptionText />}
-          <Text>
-            Provide unique name for your configuration - you can create more than one. For example -
-            production and development. Then, pass your API Key. Obtain it here.
-          </Text>
-        }
       >
         <BoxWithBorder>
           <form
@@ -83,7 +79,7 @@ const NewSmtpConfigurationPage: NextPage = () => {
               <Text variant="heading">SMTP server connection</Text>
               <Input
                 label="Host"
-                helperText="Server host that will be connected."
+                helperText="Address of the SMTP server"
                 control={control}
                 name="smtpHost"
               />
@@ -91,19 +87,19 @@ const NewSmtpConfigurationPage: NextPage = () => {
                 label="Port"
                 name="smtpPort"
                 control={control}
-                helperText="Port that will be used"
+                helperText="Port that will be used for SMTP connection"
               />
               <Input
                 label="User"
                 name="smtpUser"
                 control={control}
-                helperText="User for the SMTP server connection"
+                helperText="User name for the SMTP server authentication"
               />
               <Input
                 label="Password"
                 name="smtpPassword"
                 control={control}
-                helperText="Password for the SMTP server connection"
+                helperText="Password for the SMTP server authentication"
               />
 
               <Box display="flex" gap={defaultPadding}>