@aws-amplify/ui-react-core 2.1.33 → 3.0.0

package/src/Authenticator/hooks/types.ts

@@ -0,0 +1,218 @@
+import React from 'react';
+
+import {
+  ChallengeName,
+  AuthenticatorServiceFacade,
+  LegacyFormFieldOptions,
+} from '@aws-amplify/ui';
+
+import { UseAuthenticator } from './useAuthenticator';
+
+export type AuthenticatorRouteComponentKey =
+  | 'confirmResetPassword'
+  | 'confirmSignIn'
+  | 'confirmSignUp'
+  | 'confirmVerifyUser'
+  | 'forceNewPassword'
+  | 'forgotPassword'
+  | 'setupTotp'
+  | 'signIn'
+  | 'signUp'
+  | 'verifyUser';
+
+export type AuthenticatorLegacyField = LegacyFormFieldOptions;
+export type AuthenticatorLegacyFields = AuthenticatorLegacyField[];
+
+/**
+ * These are the "facades" that we provide, which contains contexts respective
+ * to current authenticator state.
+ */
+export type AuthenticatorMachineContext = AuthenticatorServiceFacade;
+export type AuthenticatorMachineContextKey = keyof AuthenticatorMachineContext;
+
+export type AuthenticatorRouteComponentName =
+  Capitalize<AuthenticatorRouteComponentKey>;
+
+interface HeaderProps {
+  children?: React.ReactNode;
+}
+
+interface FooterProps {
+  children?: React.ReactNode;
+}
+
+type FormFieldsProps = {
+  isPending: UseAuthenticator['isPending'];
+  validationErrors?: UseAuthenticator['validationErrors'];
+};
+
+export type FooterComponent<Props = {}> = React.ComponentType<
+  FooterProps & Props
+>;
+
+export type FormFieldsComponent<FieldType, Props = {}> = React.ComponentType<
+  FormFieldsProps & { fields: FieldType[] } & Props
+>;
+
+export type HeaderComponent<Props = {}> = React.ComponentType<
+  HeaderProps & Props
+>;
+
+export interface ComponentSlots<FieldType = {}> {
+  Footer: FooterComponent;
+  Header: HeaderComponent;
+
+  // `FormFieldsComponent` requires `FieldType`
+  FormFields: FormFieldsComponent<FieldType>;
+}
+
+/**
+ * Common component prop types used for both RWA and RNA implementations
+ */
+export type CommonRouteProps = {
+  error?: UseAuthenticator['error'];
+  isPending: UseAuthenticator['isPending'];
+  handleBlur: UseAuthenticator['updateBlur'];
+  handleChange: UseAuthenticator['updateForm'];
+  handleSubmit: UseAuthenticator['submitForm'];
+};
+
+export interface ValidationProps {
+  hasValidationErrors: UseAuthenticator['hasValidationErrors'];
+  validationErrors?: UseAuthenticator['validationErrors'];
+}
+
+/**
+ * Base Route component props
+ */
+export type ConfirmResetPasswordBaseProps<FieldType = {}> = {
+  resendCode: UseAuthenticator['resendCode'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type ConfirmSignInBaseProps<FieldType = {}> = {
+  challengeName: ChallengeName | undefined;
+  toSignIn: UseAuthenticator['toSignIn'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type ConfirmSignUpBaseProps<FieldType = {}> = {
+  codeDeliveryDetails: UseAuthenticator['codeDeliveryDetails'];
+  resendCode: UseAuthenticator['resendCode'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type ConfirmVerifyUserProps<FieldType = {}> = {
+  skipVerification: UseAuthenticator['skipVerification'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type ForceResetPasswordBaseProps<FieldType = {}> = {
+  toSignIn: UseAuthenticator['toSignIn'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type ResetPasswordBaseProps<FieldType = {}> = {
+  toSignIn: UseAuthenticator['toSignIn'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type SetupTotpBaseProps<FieldType = {}> = {
+  toSignIn: UseAuthenticator['toSignIn'];
+  totpSecretCode: UseAuthenticator['totpSecretCode'];
+  username: UseAuthenticator['username'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type SignInBaseProps<FieldType = {}> = {
+  hideSignUp?: boolean;
+  socialProviders?: UseAuthenticator['socialProviders'];
+  toFederatedSignIn: UseAuthenticator['toFederatedSignIn'];
+  toForgotPassword: UseAuthenticator['toForgotPassword'];
+  toSignUp: UseAuthenticator['toSignUp'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type SignUpBaseProps<FieldType = {}> = {
+  hideSignIn?: boolean;
+  socialProviders?: UseAuthenticator['socialProviders'];
+  toFederatedSignIn: UseAuthenticator['toFederatedSignIn'];
+  toSignIn: UseAuthenticator['toSignIn'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export type VerifyUserProps<FieldType = {}> = {
+  skipVerification: UseAuthenticator['skipVerification'];
+} & CommonRouteProps &
+  ComponentSlots<FieldType> &
+  ValidationProps;
+
+export interface DefaultProps<FieldType = {}> {
+  ConfirmSignIn: ConfirmSignInBaseProps<FieldType>;
+  ConfirmSignUp: ConfirmSignUpBaseProps<FieldType>;
+  ConfirmResetPassword: ConfirmResetPasswordBaseProps<FieldType>;
+  ConfirmVerifyUser: ConfirmVerifyUserProps<FieldType>;
+  ForceNewPassword: ForceResetPasswordBaseProps<FieldType>;
+  ForgotPassword: ResetPasswordBaseProps<FieldType>;
+  SetupTotp: SetupTotpBaseProps<FieldType>;
+  SignIn: SignInBaseProps<FieldType>;
+  SignUp: SignUpBaseProps<FieldType>;
+  VerifyUser: VerifyUserProps<FieldType>;
+}
+
+/**
+ * common types extended for default component types/implementations and override component types
+ */
+type BaseComponent<
+  // Route specifc props
+  ComponentRouteProps = {},
+  // Route specific `FieldType`
+  FieldType = {},
+  // additional props assigned in the UI layer
+  Props = {},
+> = React.ComponentType<
+  ComponentSlots<FieldType> &
+    ComponentRouteProps & { fields: FieldType[] } & Props
+>;
+
+/**
+ * Authenticator Route Component Default types
+ */
+export type Defaults<FieldType = {}, PlatformProps = {}> = {
+  [Key in AuthenticatorRouteComponentName]: BaseComponent<
+    DefaultProps<FieldType>[Key],
+    FieldType,
+    PlatformProps
+  > &
+    // add component slots for Defaults
+    ComponentSlots<FieldType>;
+};
+
+export type Overrides<FieldType = {}, PlatformProps = {}> = {
+  [Key in AuthenticatorRouteComponentName]?: BaseComponent<
+    DefaultProps<FieldType>[Key],
+    FieldType,
+    PlatformProps
+  >;
+};
+
+/**
+ * Default Route Component union type
+ */
+export type DefaultComponentType<FieldType = {}> =
+  Defaults<FieldType>[keyof Defaults<FieldType>];
+
+/**
+ * Default Route Component union type
+ */
+export type DefaultPropsType<FieldType = {}> =
+  DefaultProps<FieldType>[keyof DefaultProps<FieldType>];

package/src/Authenticator/hooks/useAuthenticator/__mock__/useAuthenticator.ts

@@ -0,0 +1,66 @@
+import {
+  AuthenticatorLegacyFields,
+  AuthenticatorMachineContext,
+} from '../../types';
+import { UseAuthenticator } from '../types';
+
+const authStatus = 'unauthenticated';
+const challengeName = 'CUSTOM_CHALLENGE';
+const codeDeliveryDetails =
+  {} as AuthenticatorMachineContext['codeDeliveryDetails'];
+const error = 'error';
+const fields = [] as AuthenticatorLegacyFields;
+const hasValidationErrors = false;
+const initializeMachine = jest.fn();
+const isPending = false;
+const QRFields = null;
+const resendCode = jest.fn();
+const route = 'idle';
+const skipVerification = jest.fn();
+const signOut = jest.fn();
+const socialProviders = [] as AuthenticatorMachineContext['socialProviders'];
+const submitForm = jest.fn();
+const toFederatedSignIn = jest.fn();
+const toForgotPassword = jest.fn();
+const toSignIn = jest.fn();
+const toSignUp = jest.fn();
+const totpSecretCode = null;
+const unverifiedUserAttributes = {};
+const updateBlur = jest.fn();
+const updateForm = jest.fn();
+const user = { username: 'username', userId: 'userId' };
+const validationErrors = {};
+
+export const mockMachineContext: AuthenticatorMachineContext = {
+  authStatus,
+  challengeName,
+  codeDeliveryDetails,
+  error,
+  hasValidationErrors,
+  initializeMachine,
+  isPending,
+  resendCode,
+  route,
+  signOut,
+  submitForm,
+  updateForm,
+  toSignIn,
+  toSignUp,
+  updateBlur,
+  user,
+  skipVerification,
+  socialProviders,
+  toFederatedSignIn,
+  toForgotPassword,
+  totpSecretCode,
+
+  unverifiedUserAttributes,
+  username: 'george',
+  validationErrors,
+};
+
+export const mockUseAuthenticatorOutput: UseAuthenticator = {
+  ...mockMachineContext,
+  fields,
+  QRFields,
+};

package/src/Authenticator/hooks/useAuthenticator/constants.ts

@@ -0,0 +1,2 @@
+export const USE_AUTHENTICATOR_ERROR =
+  '`useAuthenticator` must be used inside an `Authenticator.Provider`.';

package/src/Authenticator/hooks/useAuthenticator/index.ts

@@ -0,0 +1,2 @@
+export { default as useAuthenticator } from './useAuthenticator';
+export { UseAuthenticator, UseAuthenticatorSelector } from './types';

package/src/Authenticator/hooks/useAuthenticator/types.ts

@@ -0,0 +1,48 @@
+import {
+  AuthenticatorServiceFacade,
+  LegacyFormFieldOptions,
+} from '@aws-amplify/ui';
+
+/**
+ * These are the "facades" that we provide, which contains contexts respective
+ * to current authenticator state.
+ */
+type AuthenticatorMachineContext = AuthenticatorServiceFacade;
+type AuthenticatorMachineContextKey = keyof AuthenticatorMachineContext;
+
+export type AuthenticatorRouteComponentKey =
+  | 'signIn'
+  | 'signUp'
+  | 'forceNewPassword'
+  | 'confirmResetPassword'
+  | 'confirmSignIn'
+  | 'confirmSignUp'
+  | 'confirmVerifyUser'
+  | 'forgotPassword'
+  | 'setupTotp'
+  | 'verifyUser';
+
+export type AuthenticatorLegacyFields = LegacyFormFieldOptions[];
+
+/**
+ * Inspired from https://xstate.js.org/docs/packages/xstate-react/#useselector-actor-selector-compare-getsnapshot.
+ *
+ * Selector accepts current facade values and returns an array of
+ * desired value(s) that should trigger re-render.
+ */
+export type UseAuthenticatorSelector = (
+  context: AuthenticatorMachineContext
+) => AuthenticatorMachineContext[AuthenticatorMachineContextKey][];
+
+export interface UseAuthenticator extends AuthenticatorServiceFacade {
+  /** @deprecated For internal use only */
+  fields: AuthenticatorLegacyFields;
+
+  /** @deprecated For internal use only */
+  QRFields: { totpIssuer?: string; totpUsername?: string } | null;
+}
+
+export type Comparator = (
+  currentMachineContext: AuthenticatorMachineContext,
+  nextMachineContext: AuthenticatorMachineContext
+) => boolean;

package/src/Authenticator/hooks/useAuthenticator/useAuthenticator.ts

@@ -0,0 +1,72 @@
+import React, { useCallback } from 'react';
+import { useSelector } from '@xstate/react';
+import { AuthMachineState, getServiceFacade } from '@aws-amplify/ui';
+
+import { AuthenticatorContext } from '../../context';
+
+import { USE_AUTHENTICATOR_ERROR } from './constants';
+import { UseAuthenticatorSelector, UseAuthenticator } from './types';
+import {
+  defaultComparator,
+  getComparator,
+  getMachineFields,
+  // getTotpSecretCodeCallback,
+  getQRFields,
+} from './utils';
+
+/**
+ * [📖 Docs](https://ui.docs.amplify.aws/react/connected-components/authenticator/headless#useauthenticator-hook)
+ */
+export default function useAuthenticator(
+  selector?: UseAuthenticatorSelector
+): UseAuthenticator {
+  const context = React.useContext(AuthenticatorContext);
+
+  if (!context) {
+    throw new Error(USE_AUTHENTICATOR_ERROR);
+  }
+
+  const { service } = context;
+  const { send } = service;
+
+  const xstateSelector = useCallback(
+    (state: AuthMachineState) => ({ ...getServiceFacade({ send, state }) }),
+    [send]
+  );
+
+  const comparator = selector ? getComparator(selector) : defaultComparator;
+
+  // the purpose of `context.authStatus`is to intentionally override `facade.authStatus`. `facade.authStatus` does
+  // not update on external sign in events (for example when a user is not using the `Authenticator`).
+  const { authStatus } = context;
+  const facade = useSelector(service, xstateSelector, comparator);
+
+  const { route, totpSecretCode, unverifiedUserAttributes, user, ...rest } =
+    facade;
+
+  // do not memoize output. `service.getSnapshot` reference remains stable preventing
+  // `fields` from updating with current form state on value changes
+  const serviceSnapshot = service.getSnapshot() as AuthMachineState;
+
+  // legacy `QRFields` values only used for SetupTotp page to retrieve issuer information, will be removed in future
+  const QRFields = route === 'setupTotp' ? getQRFields(serviceSnapshot) : null;
+
+  // legacy `formFields` values required until form state is removed from state machine
+  const fields = getMachineFields(
+    route,
+    serviceSnapshot,
+    unverifiedUserAttributes
+  );
+
+  return {
+    ...rest,
+    authStatus,
+    route,
+    totpSecretCode,
+    unverifiedUserAttributes,
+    user,
+    /** @deprecated For internal use only */
+    fields,
+    QRFields,
+  };
+}

package/src/Authenticator/hooks/useAuthenticator/utils.ts

@@ -0,0 +1,97 @@
+import {
+  areEmptyArrays,
+  areEmptyObjects,
+  AuthenticatorRoute,
+  AuthMachineState,
+  FormFieldsArray,
+  getSortedFormFields,
+  UnverifiedUserAttributes,
+  getActorContext,
+  isString,
+} from '@aws-amplify/ui';
+
+import { AuthenticatorLegacyField, AuthenticatorLegacyFields } from '../types';
+import { isComponentRouteKey } from '../utils';
+
+import { Comparator, UseAuthenticatorSelector } from './types';
+
+export const defaultComparator = (): false => false;
+
+/**
+ * Does an ordering and shallow comparison of each array value,
+ * plus a value equality check for empty objects and arrays.
+ */
+export function areSelectorDepsEqual<T>(
+  currentDeps: T[],
+  nextDeps: T[]
+): boolean {
+  if (currentDeps.length !== nextDeps.length) {
+    return false;
+  }
+  return currentDeps.every((currentDep, index) => {
+    const nextDep = nextDeps[index];
+
+    if (
+      areEmptyArrays(currentDep, nextDep) ||
+      areEmptyObjects(currentDep, nextDep)
+    ) {
+      return true;
+    }
+
+    return currentDep === nextDep;
+  });
+}
+
+export const getComparator =
+  (selector: UseAuthenticatorSelector): Comparator =>
+  (currentFacade, nextFacade) => {
+    const currentSelectorDeps = selector(currentFacade);
+    const nextSelectorDeps = selector(nextFacade);
+
+    // Shallow compare the array values
+    return areSelectorDepsEqual(currentSelectorDeps, nextSelectorDeps);
+  };
+
+export const getQRFields = (
+  state: AuthMachineState
+): { totpIssuer?: string; totpUsername?: string } => ({
+  ...getActorContext(state)?.formFields?.setupTotp?.QR,
+});
+
+const flattenFormFields = (
+  fields: FormFieldsArray
+): AuthenticatorLegacyFields =>
+  fields.flatMap(([name, options]) => ({ name, ...options }));
+
+const convertContactMethodsToFields = (
+  unverifiedUserAttributes: UnverifiedUserAttributes
+): AuthenticatorLegacyFields => {
+  return (
+    unverifiedUserAttributes &&
+    Object.entries(unverifiedUserAttributes).map(([name, value]) => {
+      const valueIsString = isString(value);
+      if (!valueIsString || !name) {
+        return {} as AuthenticatorLegacyField;
+      }
+      return { name, label: value, type: 'radio', value };
+    })
+  );
+};
+
+/**
+ * Retrieves default and custom (RWA only, to be updated) form field values from state machine
+ * for subcomponent routes that render fields
+ */
+export const getMachineFields = (
+  route: AuthenticatorRoute,
+  state: AuthMachineState,
+  unverifiedUserAttributes: UnverifiedUserAttributes
+): AuthenticatorLegacyFields => {
+  if (isComponentRouteKey(route)) {
+    return route === 'verifyUser'
+      ? convertContactMethodsToFields(unverifiedUserAttributes)
+      : flattenFormFields(getSortedFormFields(route, state));
+  }
+
+  return [];
+};

package/src/Authenticator/hooks/useAuthenticatorInitMachine/index.ts

@@ -0,0 +1 @@
+export { default as useAuthenticatorInitMachine } from './useAuthenticatorInitMachine';

package/src/Authenticator/hooks/useAuthenticatorInitMachine/useAuthenticatorInitMachine.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { AuthenticatorMachineOptions } from '@aws-amplify/ui';
+
+import {
+  useAuthenticator,
+  UseAuthenticatorSelector,
+} from '../useAuthenticator';
+
+// only select `route` from machine context
+export const routeSelector: UseAuthenticatorSelector = ({ route }) => [route];
+
+export default function useAuthenticatorInitMachine(
+  data: AuthenticatorMachineOptions
+): void {
+  const { route, initializeMachine } = useAuthenticator(routeSelector);
+
+  const hasInitialized = React.useRef(false);
+  React.useEffect(() => {
+    if (!hasInitialized.current && route === 'setup') {
+      initializeMachine(data);
+
+      hasInitialized.current = true;
+    }
+  }, [initializeMachine, route, data]);
+}

package/src/Authenticator/hooks/useAuthenticatorRoute/constants.ts

@@ -0,0 +1,107 @@
+import {
+  AuthenticatorMachineContextKey,
+  AuthenticatorRouteComponentKey,
+} from '../types';
+import {
+  CommonRouteMachineKey,
+  ConfirmResetPasswordMachineKey,
+  ConfirmSignInMachineKey,
+  ConfirmSignUpMachineKey,
+  ConfirmVerifyUserMachineKey,
+  ForceNewPasswordMachineKey,
+  FormEventHandlerMachineKey,
+  FormEventHandlerPropKey,
+  ResetPasswordMachineKey,
+  SignInMachineKey,
+  SignUpMachineKey,
+  SetupTotpMachineKey,
+  VerifyUserMachineKey,
+} from './types';
+
+export const EVENT_HANDLER_KEY_MAP: Record<
+  FormEventHandlerMachineKey,
+  FormEventHandlerPropKey
+> = {
+  updateBlur: 'handleBlur',
+  updateForm: 'handleChange',
+  submitForm: 'handleSubmit',
+};
+
+const COMMON_ROUTE_MACHINE_KEYS: CommonRouteMachineKey[] = [
+  'error',
+  'isPending',
+  'submitForm',
+  'updateBlur',
+  'updateForm',
+];
+
+const CONFIRM_RESET_PASSWORD_MACHINE_KEYS: ConfirmResetPasswordMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'hasValidationErrors',
+  'resendCode',
+  'validationErrors',
+];
+const CONFIRM_SIGN_IN_MACHINE_KEYS: ConfirmSignInMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'challengeName',
+  'toSignIn',
+];
+const CONFIRM_SIGN_UP_MACHINE_KEYS: ConfirmSignUpMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'codeDeliveryDetails',
+  'resendCode',
+];
+const CONFIRM_VERIFY_USER_MACHINE_KEYS: ConfirmVerifyUserMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'skipVerification',
+];
+const FORCE_NEW_PASSWORD_MACHINE_KEYS: ForceNewPasswordMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'hasValidationErrors',
+  'toSignIn',
+  'validationErrors',
+];
+const RESET_PASSWORD_MACHINE_KEYS: ResetPasswordMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'toSignIn',
+];
+const SIGN_IN_MACHINE_KEYS: SignInMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'socialProviders',
+  'toFederatedSignIn',
+  'toForgotPassword',
+  'toSignUp',
+];
+const SIGN_UP_MACHINE_KEYS: SignUpMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'hasValidationErrors',
+  'socialProviders',
+  'toSignIn',
+  'validationErrors',
+];
+const SETUP_TOTP_MACHINE_KEYS: SetupTotpMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'toSignIn',
+  'totpSecretCode',
+  'username',
+];
+const VERIFY_USER_MACHINE_KEYS: VerifyUserMachineKey[] = [
+  ...COMMON_ROUTE_MACHINE_KEYS,
+  'skipVerification',
+];
+
+export const MACHINE_PROP_KEYS: Record<
+  AuthenticatorRouteComponentKey,
+  AuthenticatorMachineContextKey[]
+> = {
+  confirmResetPassword: CONFIRM_RESET_PASSWORD_MACHINE_KEYS,
+  confirmSignIn: CONFIRM_SIGN_IN_MACHINE_KEYS,
+  confirmSignUp: CONFIRM_SIGN_UP_MACHINE_KEYS,
+  confirmVerifyUser: CONFIRM_VERIFY_USER_MACHINE_KEYS,
+  forceNewPassword: FORCE_NEW_PASSWORD_MACHINE_KEYS,
+  signIn: SIGN_IN_MACHINE_KEYS,
+  signUp: SIGN_UP_MACHINE_KEYS,
+  forgotPassword: RESET_PASSWORD_MACHINE_KEYS,
+  setupTotp: SETUP_TOTP_MACHINE_KEYS,
+  verifyUser: VERIFY_USER_MACHINE_KEYS,
+};

package/src/Authenticator/hooks/useAuthenticatorRoute/index.ts

@@ -0,0 +1,2 @@
+export { default as useAuthenticatorRoute } from './useAuthenticatorRoute';
+export * from './types';