Add example for how to customize Sign Up (aws-amplify#552)

Co-authored-by: Eddie Keller <[email protected]>

.changeset/bump-versions.md

@@ -0,0 +1,46 @@
+---
+'@aws-amplify/ui': patch
+'@aws-amplify/ui-react': patch
+---
+
+`@aws-amplify/ui-react` supports validation & re-use & customization of `Authenticator.SignUp.FormFields` via `components` & `services`:
+
+```js
+<Authenticator
+  components={{
+    SignUp: {
+      FormFields() {
+        const { validationErrors } = useAuthenticator();
+        return (
+          <>
+            <TextField
+              label="Preferred Username"
+              labelHidden={true}
+              name="preferred_username"
+              placeholder="Preferred Username"
+            />
+            <Authenticator.SignUp.FormFields />
+            <CheckboxField
+              errorMessage={validationErrors.acknowledgement}
+              hasError={!!validationErrors.acknowledgement}
+              name="acknowledgement"
+              value="yes"
+            >
+              I agree with the Terms & Conditions
+            </CheckboxField>
+          </>
+        );
+      },
+    },
+  }}
+  services={{
+    async validateCustomSignUp(formData) {
+      if (!formData.acknowledgement) {
+        return {
+          acknowledgement: 'You must agree to the Terms & Conditions',
+        };
+      }
+    },
+  }}
+/>
+```

.gitattributes

@@ -1,2 +1,4 @@
 **/*.d.ts linguist-generated=true
+**/.graphqlconfig.yml linguist-generated=true
+**/amplify/** linguist-generated=true
 yarn.lock linguist-generated=true

docs/src/pages/ui/components/authenticator/index.page.mdx

@@ -2,7 +2,14 @@
 title: Authenticator
 ---
 
-import { Authenticator, Alert } from '@aws-amplify/ui-react';
+import {
+  Alert,
+  Authenticator,
+  CheckboxField,
+  Link,
+  TextField,
+  useAuthenticator,
+} from '@aws-amplify/ui-react';
 import { Example } from '@/components/Example';
 import { Feature } from '@/components/Feature';
 import { Fragment } from '@/components/Fragment';
@@ -146,6 +153,60 @@ For your [configured social providers](https://docs.amplify.aws/lib/auth/social/
 
 ## Customization
 
+### Sign Up Fields
+
+The following example customizes the Sign Up screen with:
+
+- Prepending custom `preferred_username` field
+- Re-using the default form fields
+- Appending a custom "Terms & Conditions" checkbox with custom validation
+
+```tsx{3-11,28-48,51-57} file=../../../../../../examples/next/pages/ui/components/authenticator/custom-sign-up-fields/index.page.tsx
+
+```
+
+<Example>
+  <Authenticator
+    initialState="signUp"
+    loginMechanisms={['email']}
+    components={{
+      SignUp: {
+        FormFields() {
+          const { validationErrors } = useAuthenticator();
+          return (
+            <>
+              <TextField
+                label="Preferred Username"
+                labelHidden={true}
+                name="preferred_username"
+                placeholder="Preferred Username"
+              />
+              <Authenticator.SignUp.FormFields />
+              <CheckboxField
+                errorMessage={validationErrors.acknowledgement}
+                hasError={!!validationErrors.acknowledgement}
+                name="acknowledgement"
+                value="yes"
+              >
+                I agree with the Terms & Conditions
+              </CheckboxField>
+            </>
+          );
+        },
+      },
+    }}
+    services={{
+      async validateCustomSignUp(formData) {
+        if (!formData.acknowledgement) {
+          return {
+            acknowledgement: 'You must agree to the Terms & Conditions',
+          };
+        }
+      },
+    }}
+  />
+</Example>
+
 ### Internationalization (I18n)
 
 The `Authenticator` ships with [translations](https://github.com/aws-amplify/amplify-ui/blob/main/packages/ui/src/i18n/translations.ts) for:

environments/auth-with-email-and-custom-attributes/.gitignore

@@ -0,0 +1,21 @@
+#amplify-do-not-edit-begin
+amplify/\#current-cloud-backend
+amplify/.config/local-*
+amplify/logs
+amplify/mock-data
+amplify/backend/amplify-meta.json
+amplify/backend/awscloudformation
+amplify/backend/.temp
+build/
+dist/
+node_modules/
+aws-exports.js
+awsconfiguration.json
+amplifyconfiguration.json
+amplifyconfiguration.dart
+amplify-build-config.json
+amplify-gradle-config.json
+amplifytools.xcconfig
+.secret-*
+**.sample
+#amplify-do-not-edit-end

environments/auth-with-email-and-custom-attributes/README.md

@@ -0,0 +1,22 @@
+# Auth with Email & Custom Attributes
+
+This backend is configured with Amplify Admin UI & cloned with Amplify CLI v6.3.1:
+
+- Authentication
+
+  - `Email` login mechanism
+  - Preferred Username (`preferred_username`) custom attribute
+
+## Using this Backend
+
+External contributors can re-create this backend by running:
+
+```shell
+amplify pull
+```
+
+Internal (Amplify UI team) contributors can use this backend directly by running:
+
+```shell
+amplify pull --appId di3yvcoio2o2w --envName staging --yes
+```