📧 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>
2023-06-12 13:30:20 +02:00 · 2023-06-12 13:30:20 +02:00 · e106ab9ff4
commit e106ab9ff4
parent cce2fbc3d5
16 changed files with 125 additions and 90 deletions
--- a/.changeset/polite-badgers-relate.md
+++ b/.changeset/polite-badgers-relate.md
@ -0,0 +1,5 @@
+---
+"saleor-app-emails-and-messages": patch
+---
+
+Added improved descriptions in the Sendgrid configuration views.
--- a/.changeset/popular-comics-sniff.md
+++ b/.changeset/popular-comics-sniff.md
@ -0,0 +1,5 @@
+---
+"saleor-app-emails-and-messages": patch
+---
+
+Added improved descriptions in the Sendgrid configuration views.
--- a/apps/emails-and-messages/src/modules/app-configuration/ui/configuration-active-description-text.tsx
+++ b/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>
+);
--- a/apps/emails-and-messages/src/modules/app-configuration/ui/configuration-name-description-text.tsx
+++ b/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>
+);
--- a/apps/emails-and-messages/src/modules/sendgrid/ui/api-connection-section.tsx
+++ b/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) => {
--- a/apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-api-key-description-text.tsx
+++ b/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>
+);
--- a/apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-basic-information-section.tsx
+++ b/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>
-          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>
+        <Box display="flex" flexDirection="column" gap={2}>
+          <ConfigurationNameDescriptionText />
+          <ConfigurationActiveDescriptionText />
+        </Box>
      }
    >
      <BoxWithBorder>
--- a/apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-events-section.tsx
+++ b/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 -
-            production and development.
-          </Text>
-          <Text as="p">Then, pass your API Key. Obtain it here.</Text>
-        </>
+        <Text as="p">
+          Choose which Saleor events should send emails via Sendgrid. You can create and modify your templates in the
+          <TextLink href="https://mc.sendgrid.com/dynamic-templates" newTab={true}>
+            Sendgrid dashboard
+          </TextLink>
+          .
+        </Text>
      }
    >
      <Box display="flex" flexDirection="column" gap={defaultPadding}>
--- a/apps/emails-and-messages/src/modules/sendgrid/ui/sendgrid-sender-section.tsx
+++ b/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) => {
--- a/apps/emails-and-messages/src/modules/smtp/ui/smtp-basic-information-section.tsx
+++ b/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>
-          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>
+        <Box display="flex" flexDirection="column" gap={2}>
+          <ConfigurationNameDescriptionText />
+          <ConfigurationActiveDescriptionText />
+        </Box>
      }
    >
      <BoxWithBorder>
--- a/apps/emails-and-messages/src/modules/smtp/ui/smtp-events-section.tsx
+++ b/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 -
-            production and development.
+            You can modify the email templates using{" "}
+            <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}>
--- a/apps/emails-and-messages/src/modules/smtp/ui/smtp-section.tsx
+++ b/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}>
--- a/apps/emails-and-messages/src/modules/smtp/ui/smtp-sender-section.tsx
+++ b/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) => {
--- a/apps/emails-and-messages/src/pages/configuration/index.tsx
+++ b/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
-            providers
+            Configure Emails & Messages app to deliver Saleor Event webhooks to configured messaging
+            providers.
          </Text>
        </Box>
      </Box>
      <SectionWithDescription
        title="Messaging providers"
        description={
-          <Text>
-            Manage providers configuration to connect Saleor events with 3rd party services.
-          </Text>
+          <Text>Manage provider configurations and modify it&apos;s message templates.</Text>
        }
      >
        <MessagingProvidersBox configurations={data || []} isLoading={isLoading} />
--- a/apps/emails-and-messages/src/pages/configuration/sendgrid/new.tsx
+++ b/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>
-            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>
+          <Box display="flex" flexDirection="column" gap={2}>
+            <ConfigurationNameDescriptionText />
+            <SendgridApiKeyDescriptionText />
+          </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}
-                    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"
-                    }
-                  />
-                )}
+                label="Configuration name"
+                helperText={"Name of the configuration, for example 'Production' or 'Test'"}
              />
+              {/* TODO: add key validation */}
+              <Input name="apiKey" control={control} label="API key" helperText={"Your API key"} />
            </Box>
            <BoxFooter>
              <Button type="submit">Save provider</Button>
--- a/apps/emails-and-messages/src/pages/configuration/smtp/new.tsx
+++ b/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={
-          <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>
-        }
+        description={<ConfigurationNameDescriptionText />}
      >
        <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}>