docs: Authenticator migration guide

docs/__tests__/__snapshots__/sitemap.test.ts.snap

@@ -48,6 +48,7 @@ exports[`Sitemap Snapshot 1`] = `
 /react-native/connected-components/in-app-messaging, 
 /react-native/getting-started/installation, 
 /react-native/getting-started/introduction, 
+/react-native/getting-started/migration, 
 /react-native/getting-started/usage, 
 /react-native/theming, 
 /react-native/theming/dark-mode, 

docs/src/pages/[platform]/getting-started/migration/index.page.mdx

@@ -2,7 +2,7 @@
 title: Migration
 metaTitle: Migration
 metaDescription: Migration Guide - How to migrate from an older version of Amplify UI to a newer version.
-supportedFrameworks: react|angular|vue
+supportedFrameworks: react|angular|vue|react-native
 ---
 
 import { Fragment } from '@/components/Fragment';

docs/src/pages/[platform]/getting-started/migration/migration.angular.mdx

@@ -1,7 +1,132 @@
-import { Alert, Tabs } from '@aws-amplify/ui-react';
+import { Alert, Message, Tabs } from '@aws-amplify/ui-react';
 import { TerminalCommand } from '@/components/InstallScripts';
 
-## 3.x to 4.x
+## `@aws-amplify/ui-angular`
+
+### Migrate from 4.x to 5.x
+#### Installation
+Install the 5.x version of `@aws-amplify/ui-angular` and 6.x version of `aws-amplify`.
+
+<Message colorTheme="warning" title="Upgrade both @aws-amplify/ui-angular and aws-amplify">
+The 5.x version of `@aws-amplify/ui-angular` has a minimum dependency of 6.x on `aws-amplify`. `aws-amplify@6` introduced breaking API changes.
+</Message>
+
+<Tabs.Container defaultValue='npm'>
+  <Tabs.List>
+    <Tabs.Item value="npm">npm</Tabs.Item>
+    <Tabs.Item value="yarn">yarn</Tabs.Item>
+  </Tabs.List>
+  <Tabs.Panel value="npm">
+    <TerminalCommand command="npm install @aws-amplify/[email protected] [email protected]" />
+  </Tabs.Panel>
+  <Tabs.Panel value="yarn">
+    <TerminalCommand command="yarn add @aws-amplify/[email protected] [email protected]" />
+  </Tabs.Panel>
+</Tabs.Container>
+
+#### 1. Updates to the Authenticator
+
+The Authenticator has the following breaking changes:
+
+The `initialState` property now accepts `forgotPassword` in place of `resetPassword`:
+
+```diff
+- <amplify-authenticator initialState="resetPassword">
+- </amplify-authenticator>
++ <amplify-authenticator initialState="forgotPassword">
++ </amplify-authenticator>
+```
+
+The corresponding component slot has been updated to reflect the change as well:
+
+```diff
+- <ng-template amplifySlot="reset-password-header">
+-   <h3
+-     class="amplify-heading"
+-     style="padding: var(--amplify-space-xl) 0 0 var(--amplify-space-xl)"
+-   >
+-     Did you forget something?
+-   </h3>
+- </ng-template>
++ <ng-template amplifySlot="forgot-password-header">
++   <h3
++     class="amplify-heading"
++     style="padding: var(--amplify-space-xl) 0 0 var(--amplify-space-xl)"
++   >
++     Did you forget something?
++   </h3>
++ </ng-template>
+```
+
+---
+
+The `user` object provided after an end user has been authenticated has been updated to reflect the `AuthUser` interface available from `aws-amplify/auth`:
+
+```diff
+- interface AmplifyUser {
+-   challengeName?: ChallengeName;
+-   attributes?: CognitpAttributes;
+-   username: string;  
+- }
++ interface AuthUser  {
++   username: string;
++   userId: string;
++   signInDetails?: CognitoAuthSignInDetails;
++ }
+```
+
+`AuthUser` can be imported from `aws-amplify/auth`:
+
+```ts
+import { AuthUser } from 'aws-amplify/auth';
+```
+
+User attributes are now available by directly calling `fetchUserAttribues`:
+
+```ts
+import { fetchUserAttributes } from 'aws-amplify/auth';
+
+const userAttributes = await fetchUserAttributes();
+```
+
+---
+
+The function signatures of the `services` interface have been updated to align with the shape of the underlying `aws-amplify/auth` APIs used by the `Authenticator` and provide improved typescript support:
+
+```diff
+interface AuthenticatorServices {
+  services?: {
+-    getCurrentUser?: () => Promise<any>,
++    getCurrentUser?: () => Promise<AuthUser>,
+
+-    handleSignIn?: ({ username, password, }: { username: string;password: string; }) => Promise<any>,
++    handleSignIn?: (input: SignInInput) => Promise<SignInOutput>,
+
+-    handleSignUp?: (formData: any) => Promise<ISignUpResult>,
++    handleSignUp?: (input: SignUpInput) => Promise<SignUpOutput>,
+
+-    handleConfirmSignIn?: ({ user, code, mfaType, }: { user: any; code: string; mfaType: ChallengeName; }) =>Promise<any>),
++    handleConfirmSignIn?: (input: ConfirmSignInInput) => Promise<ConfirmSignInOutput>,
+
+-    handleConfirmSignUp?: ({ username, code, }: { username: string; code: string; }) => Promise<any>,
++    handleConfirmSignUp?: (input: ConfirmSignUpInput) => Promise<ConfirmSignUpOutput>,
+
+-    handleForgotPasswordSubmit?: ({ username, code, password, }: { username: string; code: string; password:string; }) => Promise<string>),
++    handleForgotPasswordSubmit?: (input: ConfirmResetPasswordInput) => Promise<void>,
+
+-    handleForgotPassword?: (formData: any) => Promise<any>,
++    handleForgotPassword?: (input: ResetPasswordInput) => Promise<ResetPasswordOutput>,
+  }
+}
+```
+
+The input and return type interfaces are available as imports from `aws-amplify/auth`:
+
+```ts
+import { ConfirmSignInInput } from 'aws-amplify';
+```
+
+##$ 3.x to 4.x
 ### Installation
 Install the 4.x version of the `@aws-amplify/ui-angular` library.
 

docs/src/pages/[platform]/getting-started/migration/migration.react-native.mdx

@@ -0,0 +1,114 @@
+import { Tabs, Message } from '@aws-amplify/ui-react';
+import { TerminalCommand } from '@/components/InstallScripts';
+
+## `@aws-amplify/ui-react-native`
+
+### Migrate from 1.x to 2.x
+#### Installation
+Install the 2.x version of `@aws-amplify/ui-react-native`, 6.x version of `aws-amplify` and 1.x version of `@aws-amplify/react-native`.
+
+<Message colorTheme="warning" title="Upgrade both @aws-amplify/ui-react-native and aws-amplify">
+The 2.x version of `@aws-amplify/ui-react-native` has a minimum dependency of 6.x on `aws-amplify` and 1.x on `@aws-amplify/react-native`. `aws-amplify@6` introduced breaking API changes and requires `@aws-amplify/react-native`.
+</Message>
+
+<Tabs.Container defaultValue='npm'>
+  <Tabs.List>
+    <Tabs.Item value="npm">npm</Tabs.Item>
+    <Tabs.Item value="yarn">yarn</Tabs.Item>
+  </Tabs.List>
+  <Tabs.Panel value="npm">
+    <TerminalCommand command="npm install @aws-amplify/[email protected] [email protected] @aws-amplify/[email protected]" />
+  </Tabs.Panel>
+  <Tabs.Panel value="yarn">
+    <TerminalCommand command="yarn add @aws-amplify/[email protected] [email protected] @aws-amplify/[email protected]" />
+  </Tabs.Panel>
+</Tabs.Container>
+
+#### Update and usage
+
+`@aws-amplify/[email protected]` introduces the following breaking changes:
+
+#### 1. Updates to the Authenticator
+
+The `initialState` property now accepts `forgotPassword` in place of `resetPassword`:
+
+**React/React Native**
+```diff
+- <Authenticator initialState="resetPassword" />
++ <Authenticator initialState="forgotPassword" />
+```
+
+The corresponding key of the `components` prop has been updated to reflect the change as well:
+
+```diff
+- <Authenticator components={{ ResetPassword: MyResetPassword }} />
++ <Authenticator components={{ ForgotPassword: MyForgotPassword }} />
+```
+
+---
+
+The `user` object provided after an end user has been authenticated has been updated to reflect the `AuthUser` interface available from `aws-amplify/auth`:
+
+```diff
+- interface AmplifyUser {
+-   challengeName?: ChallengeName;
+-   attributes?: CognitpAttributes;
+-   username: string;  
+- }
++ interface AuthUser  {
++   username: string;
++   userId: string;
++   signInDetails?: CognitoAuthSignInDetails;
++ }
+```
+
+`AuthUser` can be imported from `aws-amplify/auth`:
+
+```ts
+import { AuthUser } from 'aws-amplify/auth';
+```
+
+User attributes are now available by directly calling `fetchUserAttribues`:
+
+```ts
+import { fetchUserAttributes } from 'aws-amplify/auth';
+
+const userAttributes = await fetchUserAttributes();
+```
+
+---
+
+The function signatures of the `services` interface have been updated to align with the shape of the underlying `aws-amplify/auth` APIs used by the `Authenticator` and provide improved typescript support:
+
+```diff
+interface AuthenticatorProps {
+  services?: {
+-    getCurrentUser?: () => Promise<any>,
++    getCurrentUser?: () => Promise<AuthUser>,
+
+-    handleSignIn?: ({ username, password, }: { username: string;password: string; }) => Promise<any>,
++    handleSignIn?: (input: SignInInput) => Promise<SignInOutput>,
+
+-    handleSignUp?: (formData: any) => Promise<ISignUpResult>,
++    handleSignUp?: (input: SignUpInput) => Promise<SignUpOutput>,
+
+-    handleConfirmSignIn?: ({ user, code, mfaType, }: { user: any; code: string; mfaType: ChallengeName; }) =>Promise<any>),
++    handleConfirmSignIn?: (input: ConfirmSignInInput) => Promise<ConfirmSignInOutput>,
+
+-    handleConfirmSignUp?: ({ username, code, }: { username: string; code: string; }) => Promise<any>,
++    handleConfirmSignUp?: (input: ConfirmSignUpInput) => Promise<ConfirmSignUpOutput>,
+
+-    handleForgotPasswordSubmit?: ({ username, code, password, }: { username: string; code: string; password:string; }) => Promise<string>),
++    handleForgotPasswordSubmit?: (input: ConfirmResetPasswordInput) => Promise<void>,
+
+-    handleForgotPassword?: (formData: any) => Promise<any>,
++    handleForgotPassword?: (input: ResetPasswordInput) => Promise<ResetPasswordOutput>,
+  }
+}
+```
+
+The input and return type interfaces are available as imports from `aws-amplify/auth`:
+
+```ts
+import { ConfirmSignInInput } from 'aws-amplify';
+```

docs/src/pages/[platform]/getting-started/migration/migration.react.mdx

@@ -28,15 +28,88 @@ The 6.x version of `@aws-amplify/ui-react` has a minimum dependency of 6.x on `a
 
 `@aws-amplify/[email protected]` introduces the following breaking changes:
 
-#### 1. `@aws-amplify/[email protected]` drops `AmplifyProvider`.
+#### 1. Updates to the Authenticator
 
-`AmplifyProvider` was renamed to `ThemeProvider` in version 2.18.3 but kept for compatibility. No API changes other than export name. If still using `AmplifyProvider`, replace directly with `ThemeProvider`:
+The `initialState` property now accepts `forgotPassword` in place of `resetPassword`:
 
 ```diff
-- import { AmplifyProvider } from '@aws-amplify/ui-react';
-+ import { ThemeProvider } from '@aws-amplify/ui-react';
-- const App = ( <AmplifyProvider><App /></AmplifyProvider>);
-+ const App = ( <ThemeProvider><App /></ThemeProvider>);
+- <Authenticator initialState="resetPassword" />
++ <Authenticator initialState="forgotPassword" />
+```
+
+The corresponding key of the `components` prop has been updated to reflect the change as well:
+
+```diff
+- <Authenticator components={{ ResetPassword: MyResetPassword }} />
++ <Authenticator components={{ ForgotPassword: MyForgotPassword }} />
+```
+
+---
+
+The `user` object provided after an end user has been authenticated has been updated to reflect the `AuthUser` interface available from `aws-amplify/auth`:
+
+```diff
+- interface AmplifyUser {
+-   challengeName?: ChallengeName;
+-   attributes?: CognitpAttributes;
+-   username: string;  
+- }
++ interface AuthUser  {
++   username: string;
++   userId: string;
++   signInDetails?: CognitoAuthSignInDetails;
++ }
+```
+
+`AuthUser` can be imported from `aws-amplify/auth`:
+
+```ts
+import { AuthUser } from 'aws-amplify/auth';
+```
+
+User attributes are now available by directly calling `fetchUserAttribues`:
+
+```ts
+import { fetchUserAttributes } from 'aws-amplify/auth';
+
+const userAttributes = await fetchUserAttributes();
+```
+
+---
+
+The function signatures of the `services` interface have been updated to align with the shape of the underlying `aws-amplify/auth` APIs used by the `Authenticator` and provide improved typescript support:
+
+```diff
+interface AuthenticatorProps {
+  services?: {
+-    getCurrentUser?: () => Promise<any>,
++    getCurrentUser?: () => Promise<AuthUser>,
+
+-    handleSignIn?: ({ username, password, }: { username: string;password: string; }) => Promise<any>,
++    handleSignIn?: (input: SignInInput) => Promise<SignInOutput>,
+
+-    handleSignUp?: (formData: any) => Promise<ISignUpResult>,
++    handleSignUp?: (input: SignUpInput) => Promise<SignUpOutput>,
+
+-    handleConfirmSignIn?: ({ user, code, mfaType, }: { user: any; code: string; mfaType: ChallengeName; }) =>Promise<any>),
++    handleConfirmSignIn?: (input: ConfirmSignInInput) => Promise<ConfirmSignInOutput>,
+
+-    handleConfirmSignUp?: ({ username, code, }: { username: string; code: string; }) => Promise<any>,
++    handleConfirmSignUp?: (input: ConfirmSignUpInput) => Promise<ConfirmSignUpOutput>,
+
+-    handleForgotPasswordSubmit?: ({ username, code, password, }: { username: string; code: string; password:string; }) => Promise<string>),
++    handleForgotPasswordSubmit?: (input: ConfirmResetPasswordInput) => Promise<void>,
+
+-    handleForgotPassword?: (formData: any) => Promise<any>,
++    handleForgotPassword?: (input: ResetPasswordInput) => Promise<ResetPasswordOutput>,
+  }
+}
+```
+
+The input and return type interfaces are available as imports from `aws-amplify/auth`:
+
+```ts
+import { ConfirmSignInInput } from 'aws-amplify';
 ```
 
 #### 2. Expander is now Accordion
@@ -171,7 +244,7 @@ There are also more design tokens and better CSS classes for easier customizatio
 
 #### 4. In-App Messaging
 
-Starting with `aws-amplify@6` the Amplify categories like Auth and Notifications are no longer exported from the base `aws-amplify` package. If you are using in-app messaging you will need to change your imports accordingly and run `initializeInAppMessaging` before your application code:
+Starting with `aws-amplify@6`, the Auth and categories like Auth and Notifications are no longer exported from the base `aws-amplify` package. If you are using in-app messaging you will need to change your imports accordingly and run `initializeInAppMessaging` before your application code:
 
 ```diff
 - import { Amplify, Notifications } from 'aws-amplify'