chore(docs): add headless auth usage page

docs/src/pages/[platform]/connected-components/authenticator/headless/advanced/current-route.react-native.mdx

@@ -0,0 +1,27 @@
+You can use `useAuthenticator` hook to access `route` string that represents the current `authState`. They can be one of:
+
+- `idle`
+- `setup`
+- `signIn`
+- `signUp`
+- `confirmSignIn`
+- `confirmSignUp`
+- `setupTOTP`
+- `forceNewPassword`
+- `resetPassword`
+- `confirmResetPassword`
+- `verifyUser`
+- `confirmVerifyUser`
+- `signOut`
+- `authenticated`
+
+```jsx
+import { useAuthenticator } from '@aws-amplify/ui-react-native';
+
+const App = () => {
+  const { route } = useAuthenticator(context => [context.route]);
+
+  // Use the value of route to decide which page to render
+  return route === 'authenticated' ? <Home /> : <Authenticator />;
+};
+```

docs/src/pages/[platform]/connected-components/authenticator/headless/advanced/current-user.react-native.mdx

@@ -0,0 +1,17 @@
+You can use `useAuthenticator` hook to access current signed in `user`. If no user is authenticated, it'll return `undefined`.
+
+```jsx
+import { View, Text, Button } from 'react-native';
+import { useAuthenticator } from '@aws-amplify/ui-react-native';
+
+const Home = () => {
+  const { user, signOut } = useAuthenticator((context) => [context.user]);
+
+  return (
+    <View>
+      <Text>{`Welcome, ${user.username}!`}</Text>
+      <Button onPress={signOut} title="Sign Out" />
+    </View>
+  );
+};
+```

docs/src/pages/[platform]/connected-components/authenticator/headless/advanced/example.react-native.mdx

@@ -0,0 +1,28 @@
+```jsx
+import { View, Button, Text } from 'react-native';
+import { Amplify } from 'aws-amplify';
+import { Authenticator, useAuthenticator } from '@aws-amplify/ui-react-native';
+
+import awsExports from './aws-exports';
+Amplify.configure(awsExports);
+
+function Footer() {
+  const { toResetPassword } = useAuthenticator();
+  return (
+    <Button onPress={toResetPassword} title="Custom Reset Password" />
+  );
+},
+
+export default function App() {
+  return (
+    <Authenticator components={{
+      SignIn: (props) => <Authenticator.SignIn {...props} Footer={Footer} />
+    }}>
+      <View>
+        <Text>Hello {user.username}</Text>
+        <Button onPress={signOut} title="Sign out" />
+      </View>
+    </Authenticator>
+  );
+}
+```

docs/src/pages/[platform]/connected-components/authenticator/headless/advanced/full-api.react-native.mdx

@@ -0,0 +1 @@
+Below is the full list of context that `useAuthenticator` composable returns.

docs/src/pages/[platform]/connected-components/authenticator/headless/advanced/trigger-transitions.react-native.mdx

@@ -0,0 +1,12 @@
+You can use `useAuthenticator` hook to access functions that lets you trigger transitions to the authenticator. Please see [Full API](#full-api) to see all supported transition functions. Any invalid transitions (e.g. `signUp` directly to `authenticated`) will be ignored.
+
+```jsx
+import { Button } from 'react-native';
+import { useAuthenticator } from '@aws-amplify/ui-react-native';
+
+const Home = () => {
+  const { user, signOut } = useAuthenticator((context) => [context.user]);
+
+  return <Button onPress={signOut} title={`Welcome, ${user.username}!`} />;
+};
+```

docs/src/pages/[platform]/connected-components/authenticator/headless/advanced/useAuthenticator.react-native.mdx

@@ -0,0 +1,60 @@
+import { Tabs, TabItem } from '@aws-amplify/ui-react';
+
+## useAuthenticator Hook
+
+`@aws-amplify/ui-react-native` ships with `useAuthenticator` React hook that can be used to access, modify, and update Authenticator's auth state. To use them, first wrap your application with [`<Authenticator.Provider>`](#authenticator-provider):
+
+```jsx
+import { Authenticator } from '@aws-amplify/ui-react-native';
+
+export default () => (
+  <Authenticator.Provider>
+    <App />
+  </Authenticator.Provider>
+);
+```
+
+Then, you can use `useAuthenticator` on your App:
+
+```jsx
+import { useAuthenticator } from '@aws-amplify/ui-react-native';
+
+const App = () => {
+  const { user, signOut } = useAuthenticator((context) => [context.user]);
+  // ...
+};
+```
+
+## Authenticator Provider
+
+In advanced use cases where usage of the [`useAuthenticator` hook](headless#useauthenticator-hook) outside the scope of the [`Authenticator`](../authenticator) is needed, wrap your application inside an `Authenticator.Provider`. The `Authenticator.Provider` guarantees that the [useAuthenticator hook](headless#useauthenticator-hook) is available throughout your application. You can see an example of this pattern in the [Protected Routes Guide.](../../guides/auth-protected)
+
+```jsx
+import { View, Text } from 'react-native';
+import { Authenticator } from '@aws-amplify/ui-react-native';
+
+export default function App() {
+  return (
+    <Authenticator.Provider>
+      <View>
+        <Text>Your app here<Text/>
+      </View>
+    </Authenticator.Provider>
+  );
+};
+```
+
+## Prevent Re-renders
+
+Using `useAuthenticator` hook at your `App` level is risky, because it'll trigger a re-render down its tree whenever any of its context changes value.
+
+To prevent undesired re-renders, you can pass a function to `useAuthenticator` that takes in Authenticator context and returns an array of desired context values. The hook will only trigger re-render if any of the array values change.
+
+For example, you can ensure `useAuthenticator` to only reevaluate when its `user` context changes:
+
+```jsx
+import { useAuthenticator } from '@aws-amplify/ui-react-native';
+
+// hook below is only reevaluated when `user` changes
+const { user, signOut } = useAuthenticator((context) => [context.user]);
+```