@aws-amplify/ui 3.0.15 → 3.2.1

package/dist/index.d.ts

@@ -1,9 +1,89 @@
 import * as amazon_cognito_identity_js from 'amazon-cognito-identity-js';
 import { CognitoUser, CodeDeliveryDetails } from 'amazon-cognito-identity-js';
 import * as xstate from 'xstate';
-import { State, Interpreter, Sender } from 'xstate';
+import { Interpreter, State, Sender } from 'xstate';
 import { PartialDeep } from 'type-fest';
 
+/**
+ * Map of each input name to its value
+ */
+declare type AuthFormData = Record<string, string>;
+/**
+ * List of routes that support custom formFields
+ */
+declare type FormFieldComponents = 'signIn' | 'signUp' | 'forceNewPassword' | 'confirmResetPassword' | 'confirmSignIn' | 'confirmSignUp' | 'confirmVerifyUser' | 'resetPassword' | 'setupTOTP';
+/**
+ * Used to customize form field attributes for each authenticator screen.
+ */
+declare type FormFields = {
+    [key in FormFieldComponents]?: FormField;
+};
+/**
+ * Override option for each screen. Maps each input to override options.
+ */
+interface FormField {
+    [key: string]: FormFieldOptions;
+}
+/**
+ * Override options for each field
+ */
+interface FormFieldOptions {
+    /** Will hide the label above the input if set to true */
+    labelHidden?: boolean;
+    /** Label text */
+    label?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /**
+     * @deprecated For internal use only, please use `isRequired` instead.
+     */
+    required?: boolean;
+    /** Whether this field is required for submission */
+    isRequired?: boolean;
+    /** Default dial code value */
+    dialCode?: string;
+    /** TOTP issuer to be used in the QR setup */
+    totpIssuer?: string;
+    /** TOTP username to be used in the QR */
+    totpUsername?: string;
+    /** List of dial codes you want to show in phone number field */
+    dialCodeList?: Array<string>;
+    /** Integer that denotes where this field should be positioned in. */
+    order?: number;
+}
+
+/** Enum of known challenge names */
+declare enum AuthChallengeNames {
+    SMS_MFA = "SMS_MFA",
+    SOFTWARE_TOKEN_MFA = "SOFTWARE_TOKEN_MFA",
+    NEW_PASSWORD_REQUIRED = "NEW_PASSWORD_REQUIRED",
+    RESET_REQUIRED = "RESET_REQUIRED",
+    MFA_SETUP = "MFA_SETUP"
+}
+/** Contact destinations that we can send user confirmation code to */
+declare type ContactMethod = 'Email' | 'Phone Number';
+/** Federated IDPs that Authenticator supports */
+declare enum FederatedIdentityProviders {
+    Apple = "SignInWithApple",
+    Amazon = "LoginWithAmazon",
+    Facebook = "Facebook",
+    Google = "Google"
+}
+/** Known cognito user attributes */
+interface CognitoAttributes {
+    email: string;
+    phone_number: string;
+    [key: string]: string;
+}
+/** Cognito User Interface */
+interface CognitoUserAmplify extends CognitoUser {
+    username?: string;
+    attributes?: CognitoAttributes;
+}
+
+/**
+ * Maps each input to its validation error, if any
+ */
 declare type ValidationError = Record<string, string>;
 /**
  * Return type of validator. This is `null` if there are no error, and `ValidationError` otherwise.
@@ -16,6 +96,36 @@ declare type SignInResult = string;
 declare type Validator = (formData: AuthFormData, touchData?: AuthFormData) => ValidatorResult | Promise<ValidatorResult>;
 declare type SignInTypes = (user: string, code: string, mfaType: AuthChallengeNames.SMS_MFA | AuthChallengeNames.SOFTWARE_TOKEN_MFA) => SignInResult | Promise<SignInResult>;
 
+/** Array of auth fields that we supply defaults with */
+declare const signUpFieldsWithDefault: readonly ["birthdate", "email", "family_name", "given_name", "middle_name", "name", "nickname", "phone_number", "preferred_username", "profile", "website"];
+/** Auth fields that we supply defaults with */
+declare type SignUpFieldsWithDefaults = typeof signUpFieldsWithDefault[number];
+/** Array of auth fields that we do not supply defaults with */
+declare const signUpFieldsWithoutDefault: readonly ["address", "gender", "locale", "picture", "updated_at", "zoneinfo"];
+/** Auth fields that we do not supply defaults with */
+declare type SignUpFieldsWithoutDefaults = typeof signUpFieldsWithoutDefault[number];
+/** All known auth fields */
+declare type SignUpAttribute = SignUpFieldsWithDefaults | SignUpFieldsWithoutDefaults;
+/** Fields that are common in all routes */
+declare type CommonFields = 'username' | 'password' | 'confirm_password';
+/** Array of known login mechanisms */
+declare const LoginMechanismArray: readonly ["username", "email", "phone_number"];
+/** Login mechanisms that can be used to sign in */
+declare type LoginMechanism = typeof LoginMechanismArray[number];
+/** List of social provider Authenticator supports */
+declare type SocialProvider = 'amazon' | 'apple' | 'facebook' | 'google';
+/** Input fields that we provide default fields with */
+declare type AuthFieldsWithDefaults = LoginMechanism | SignUpFieldsWithDefaults | 'confirmation_code' | 'password';
+/** Maps default attributes values for an input */
+interface InputAttributeDefaults {
+    label: string;
+    type: string;
+    placeholder: string;
+    autocomplete?: string;
+}
+/** Maps default attribute values for each Auth Field */
+declare type AuthInputAttributes = Record<AuthFieldsWithDefaults, InputAttributeDefaults>;
+
 declare const defaultServices: {
     getAmplifyConfig(): Promise<{}>;
     getCurrentUser(): Promise<any>;
@@ -44,18 +154,28 @@ declare const defaultServices: {
     validatePreferredUsername(formData: any, touchData: any): Promise<ValidatorResult>;
 };
 
-declare type AuthFormData = Record<string, string>;
+/**
+ * Data that actor returns when they are done and reach the final state
+ */
 interface ActorDoneData {
+    /** Any auth form values that needs to be persisted between the actors */
     authAttributes?: AuthFormData;
+    /** String that indicates where authMachine should next transition to */
     intent?: string;
+    /** User returned by the actor it's done */
     user?: CognitoUserAmplify;
 }
+/**
+ * Context interface for the top-level machine
+ */
 interface AuthContext {
+    /** Reference to the spawned actor */
     actorRef?: any;
     config?: {
         loginMechanisms?: LoginMechanism[];
         signUpAttributes?: SignUpAttribute[];
         socialProviders?: SocialProvider[];
+        formFields?: FormFields;
         initialState?: 'signIn' | 'signUp' | 'resetPassword';
     };
     services?: Partial<typeof defaultServices>;
@@ -66,107 +186,122 @@ interface AuthContext {
     mfaType?: AuthChallengeNames.SMS_MFA | AuthChallengeNames.SOFTWARE_TOKEN_MFA;
     actorDoneData?: Omit<ActorDoneData, 'user'>;
 }
-interface ServicesContext {
-    username?: string;
-    password?: string;
-    user?: string;
-    code?: string;
-    mfaType: AuthChallengeNames.SMS_MFA | AuthChallengeNames.SOFTWARE_TOKEN_MFA;
-}
+/**
+ * Base context for all actors that have auth forms associated
+ */
 interface BaseFormContext {
+    /** Any user attributes set that needs to persist between states */
     authAttributes?: Record<string, any>;
+    /** Current challengeName issued by Cognnito */
     challengeName?: string;
+    /** Required attributes for form submission */
     requiredAttributes?: Array<string>;
+    /** Maps each input name to tis value */
     formValues?: AuthFormData;
+    /** Input (names) that has been blurred at least ones */
     touched?: AuthFormData;
+    /** String that indicates where authMachine should next transition to */
     intent?: string;
+    /** Error returned from remote service / API */
     remoteError?: string;
+    /** Current user inteface the actor is working with */
     user?: CognitoUserAmplify;
+    /** Maps each input to its validation error, if any */
     validationError?: ValidationError;
+    /** Denotes where a confirmation code has been sent to */
     codeDeliveryDetails?: CodeDeliveryDetails;
+    /** Default country code for all phone number fields. */
     country_code?: string;
 }
 interface SignInContext extends BaseFormContext {
     loginMechanisms: Required<AuthContext>['config']['loginMechanisms'];
     socialProviders: Required<AuthContext>['config']['socialProviders'];
+    formFields?: FormFields;
     attributeToVerify?: string;
     redirectIntent?: string;
     unverifiedAttributes?: Record<string, string>;
 }
-declare const signUpFieldsWithDefault: readonly ["birthdate", "email", "family_name", "given_name", "middle_name", "name", "nickname", "phone_number", "preferred_username", "profile", "website"];
-declare const signUpFieldsWithoutDefault: readonly ["address", "gender", "locale", "picture", "updated_at", "zoneinfo"];
-declare type SignUpFieldsWithDefaults = typeof signUpFieldsWithDefault[number];
-declare type SignUpFieldsWithoutDefaults = typeof signUpFieldsWithoutDefault[number];
-declare type SignUpAttribute = SignUpFieldsWithDefaults | SignUpFieldsWithoutDefaults;
 interface SignUpContext extends BaseFormContext {
     loginMechanisms: Required<AuthContext>['config']['loginMechanisms'];
     socialProviders: Required<AuthContext>['config']['socialProviders'];
+    formFields: FormFields;
     unverifiedAttributes?: Record<string, string>;
 }
 interface ResetPasswordContext extends BaseFormContext {
     username?: string;
     unverifiedAttributes?: Record<string, string>;
+    formFields?: FormFields;
 }
 interface SignOutContext {
     authAttributes?: Record<string, any>;
     challengeName?: string;
     unverifiedAttributes?: Record<string, string>;
     user?: CognitoUserAmplify;
+    formFields?: FormFields;
 }
+/**
+ * Context for actors that have forms
+ */
 declare type ActorContextWithForms = SignInContext | SignUpContext | ResetPasswordContext;
-declare type SignInState = State<SignInContext, AuthEvent>;
-declare type SignUpState = State<SignUpContext, AuthEvent>;
-declare type SignOutState = State<SignOutContext, AuthEvent>;
-declare type ResetPasswordState = State<ResetPasswordContext, AuthEvent>;
 declare type AuthActorContext = ActorContextWithForms | SignOutContext;
-declare type AuthActorState = State<AuthActorContext, AuthEvent>;
-interface CognitoUserAmplify extends CognitoUser {
-    username?: string;
-    attributes?: CognitoAttributes;
-}
-interface CognitoAttributes {
-    email: string;
-    phone_number: string;
-    [key: string]: string;
-}
+
+/**
+ * Events that occur when actors are done
+ */
 declare type InvokeActorEventTypes = 'done.invoke.signInActor' | 'done.invoke.signUpActor' | 'done.invoke.signOutActor' | 'done.invoke.resetPasswordActor';
+/**
+ * All known explicit events for xstate
+ */
 declare type AuthEventTypes = 'CHANGE' | 'BLUR' | 'FEDERATED_SIGN_IN' | 'RESEND' | 'RESET_PASSWORD' | 'SIGN_IN' | 'SIGN_OUT' | 'SIGN_UP' | 'SKIP' | 'SUBMIT' | 'INIT' | InvokeActorEventTypes;
-declare enum AuthChallengeNames {
-    SMS_MFA = "SMS_MFA",
-    SOFTWARE_TOKEN_MFA = "SOFTWARE_TOKEN_MFA",
-    NEW_PASSWORD_REQUIRED = "NEW_PASSWORD_REQUIRED",
-    RESET_REQUIRED = "RESET_REQUIRED",
-    MFA_SETUP = "MFA_SETUP"
-}
-interface InputAttributes {
-    label: string;
-    type: string;
-    placeholder: string;
-    autocomplete?: string;
-}
-declare const LoginMechanismArray: readonly ["username", "email", "phone_number"];
-declare type LoginMechanism = typeof LoginMechanismArray[number];
-declare type SocialProvider = 'amazon' | 'apple' | 'facebook' | 'google';
-declare type AuthFieldsWithDefaults = LoginMechanism | SignUpFieldsWithDefaults | 'confirmation_code' | 'password';
-declare type AuthInputAttributes = Record<AuthFieldsWithDefaults, InputAttributes>;
+/**
+ * Data payload for auth events
+ */
 declare type AuthEventData = Record<PropertyKey, any>;
+/** Top-level auth machine event interface */
 interface AuthEvent {
     type: AuthEventTypes;
     data?: AuthEventData;
 }
-declare type AuthMachineState = State<AuthContext, AuthEvent>;
+
+/**
+ * This files provides types that describe general shape of
+ * authenticator machine and its intepreter.
+ */
+
+/**
+ * Intefrace for `authMachine` machine interpreter
+ */
 declare type AuthInterpreter = Interpreter<AuthContext, any, AuthEvent>;
+/**
+ * Function type for `send` in `authMachine`
+ */
 declare type AuthMachineSend = AuthInterpreter['send'];
 
+declare type SignInState = State<SignInContext, AuthEvent>;
+declare type SignUpState = State<SignUpContext, AuthEvent>;
+declare type SignOutState = State<SignOutContext, AuthEvent>;
+declare type ResetPasswordState = State<ResetPasswordContext, AuthEvent>;
+declare type AuthActorState = State<AuthActorContext, AuthEvent>;
+declare type AuthMachineState = State<AuthContext, AuthEvent>;
+
 declare type NoInfer<T> = [T][T extends any ? 0 : never];
 
-declare const authInputAttributes: AuthInputAttributes;
-declare enum FederatedIdentityProviders {
-    Apple = "SignInWithApple",
-    Amazon = "LoginWithAmazon",
-    Facebook = "Facebook",
-    Google = "Google"
-}
+/**
+ * This file contains helpers that lets you easily access current actor's state
+ * and context.
+ */
+
+/**
+ * Get the state of current actor. This is useful for checking which screen
+ * to render: e.g. `getActorState(state).matches('confirmSignUp.edit').
+ */
+declare const getActorState: (state: AuthMachineState) => AuthActorState;
+/**
+ * Get the context of current actor. Useful for getting any nested context
+ * like remoteError.
+ */
+declare const getActorContext: (state: AuthMachineState) => AuthActorContext;
+
 /**
  * Given xstate context from AuthMachine, this returns the input label, type,
  * and error attributes of the configured login_mechanisms. An optional "alias"
@@ -182,19 +317,10 @@ declare const getAliasInfoFromContext: (context: AuthContext, alias?: LoginMecha
  * secondaryAliases.
  */
 declare const getConfiguredAliases: (context: AuthContext) => {
-    primaryAlias: "username" | "email" | "phone_number";
-    secondaryAliases: ("username" | "email" | "phone_number")[];
+    primaryAlias: "email" | "phone_number" | "username";
+    secondaryAliases: ("email" | "phone_number" | "username")[];
 };
-/**
- * Get the state of current actor. This is useful for checking which screen
- * to render: e.g. `getActorState(state).matches('confirmSignUp.edit').
- */
-declare const getActorState: (state: AuthMachineState) => AuthActorState;
-/**
- * Get the context of current actor. Useful for getting any nested context
- * like remoteError.
- */
-declare const getActorContext: (state: AuthMachineState) => AuthActorContext;
+
 /**
  * Creates public facing auth helpers that abstracts out xstate implementation
  * detail. Each framework implementation can export these helpers so that
@@ -253,6 +379,24 @@ declare const getServiceFacade: ({ send, state }: {
     toSignUp: (data?: AuthEventData) => void;
     skipVerification: (data?: AuthEventData) => void;
 };
+
+/**
+ * This file contains helpers related to forms and input attributes.
+ */
+
+declare const authInputAttributes: AuthInputAttributes;
+declare const getFormDataFromEvent: (event: Event) => {
+    [k: string]: FormDataEntryValue;
+};
+declare const setFormOrder: (formOverrides: FormField, fieldNames: Array<SignUpAttribute | CommonFields>) => Array<string | number>;
+
+/**
+ * This file contains general helpers that state machine or authenticator
+ * implementations can use.
+ */
+
+declare const censorAllButFirstAndLast: (value: string) => string;
+declare const censorPhoneNumber: (val: string) => string;
 /**
  * Listens to external auth Hub events and sends corresponding event to
  * the `authService` of interest
@@ -263,13 +407,6 @@ declare const getServiceFacade: ({ send, state }: {
  */
 declare const listenToAuthHub: (send: AuthMachineSend) => () => void;
 
-declare type ContactMethod = 'Email' | 'Phone Number';
-declare const censorAllButFirstAndLast: (value: string) => string;
-declare const censorPhoneNumber: (val: string) => string;
-declare const getFormDataFromEvent: (event: Event) => {
-    [k: string]: FormDataEntryValue;
-};
-
 declare const countryDialCodes: string[];
 
 /**
@@ -642,7 +779,7 @@ declare type WebShadows = {
     [Property in keyof Shadows]: WebDesignToken<ShadowValue>;
 };
 
-declare type Space = {
+declare type SpaceSizes = {
     xxxs: DesignToken<SpaceValue>;
     xxs: DesignToken<SpaceValue>;
     xs: DesignToken<SpaceValue>;
@@ -652,16 +789,11 @@ declare type Space = {
     xl: DesignToken<SpaceValue>;
     xxl: DesignToken<SpaceValue>;
     xxxl: DesignToken<SpaceValue>;
-    relative: {
-        xxxs: DesignToken<SpaceValue>;
-        xxs: DesignToken<SpaceValue>;
-        xs: DesignToken<SpaceValue>;
-        small: DesignToken<SpaceValue>;
-        medium: DesignToken<SpaceValue>;
-        large: DesignToken<SpaceValue>;
-        xl: DesignToken<SpaceValue>;
-        xxl: DesignToken<SpaceValue>;
-        xxxl: DesignToken<SpaceValue>;
+};
+declare type Space = SpaceSizes & {
+    zero: DesignToken<SpaceValue>;
+    relative: SpaceSizes & {
+        full: DesignToken<SpaceValue>;
     };
 };
 declare type WebSpace = {
@@ -862,4 +994,4 @@ declare function createTheme(theme?: Theme, baseTheme?: BaseTheme): WebTheme;
 
 declare const defaultTheme: WebTheme;
 
-export { ActorContextWithForms, ActorDoneData, AuthActorContext, AuthActorState, AuthChallengeNames, AuthContext, AuthEvent, AuthEventData, AuthEventTypes, AuthFieldsWithDefaults, AuthFormData, AuthInputAttributes, AuthInterpreter, AuthMachineSend, AuthMachineState, AuthenticatorMachineOptions, BaseTheme, BorderWidthValue, CognitoAttributes, CognitoUserAmplify, ColorModeOverride, ColorValue, ContactMethod, DefaultTexts, DesignToken, Dict, FederatedIdentityProviders, FontSizeValue, FontValue, FontWeightValue, InputAttributes, InvokeActorEventTypes, LineHeightValue, LoginMechanism, LoginMechanismArray, MediaQueryOverride, NoInfer, OpacityValue, OutlineOffsetValue, OutlineWidthValue, Override, Phrase, RadiusValue, ResetPasswordContext, ResetPasswordState, SelectorOverride, ServicesContext, ShadowValue, SignInContext, SignInResult, SignInState, SignInTypes, SignOutContext, SignOutState, SignUpAttribute, SignUpContext, SignUpFieldsWithDefaults, SignUpFieldsWithoutDefaults, SignUpState, SocialProvider, SpaceValue, Theme, TimeValue, TransformValue, ValidationError, Validator, ValidatorResult, WebDesignToken, WebTheme, authInputAttributes, censorAllButFirstAndLast, censorPhoneNumber, countryDialCodes, createAuthenticatorMachine, createTheme, defaultTheme, getActorContext, getActorState, getAliasInfoFromContext, getConfiguredAliases, getFormDataFromEvent, getSendEventAliases, getServiceContextFacade, getServiceFacade, hasTranslation, isDesignToken, listenToAuthHub, signUpFieldsWithDefault, signUpFieldsWithoutDefault, translate, translations };
+export { ActorContextWithForms, ActorDoneData, AuthActorContext, AuthActorState, AuthChallengeNames, AuthContext, AuthEvent, AuthEventData, AuthEventTypes, AuthFieldsWithDefaults, AuthFormData, AuthInputAttributes, AuthInterpreter, AuthMachineSend, AuthMachineState, AuthenticatorMachineOptions, BaseTheme, BorderWidthValue, CognitoAttributes, CognitoUserAmplify, ColorModeOverride, ColorValue, CommonFields, ContactMethod, DefaultTexts, DesignToken, Dict, FederatedIdentityProviders, FontSizeValue, FontValue, FontWeightValue, FormField, FormFieldComponents, FormFieldOptions, FormFields, InputAttributeDefaults, InvokeActorEventTypes, LineHeightValue, LoginMechanism, LoginMechanismArray, MediaQueryOverride, NoInfer, OpacityValue, OutlineOffsetValue, OutlineWidthValue, Override, Phrase, RadiusValue, ResetPasswordContext, ResetPasswordState, SelectorOverride, ShadowValue, SignInContext, SignInResult, SignInState, SignInTypes, SignOutContext, SignOutState, SignUpAttribute, SignUpContext, SignUpFieldsWithDefaults, SignUpFieldsWithoutDefaults, SignUpState, SocialProvider, SpaceValue, Theme, TimeValue, TransformValue, ValidationError, Validator, ValidatorResult, WebDesignToken, WebTheme, authInputAttributes, censorAllButFirstAndLast, censorPhoneNumber, countryDialCodes, createAuthenticatorMachine, createTheme, defaultTheme, getActorContext, getActorState, getAliasInfoFromContext, getConfiguredAliases, getFormDataFromEvent, getSendEventAliases, getServiceContextFacade, getServiceFacade, hasTranslation, isDesignToken, listenToAuthHub, setFormOrder, signUpFieldsWithDefault, signUpFieldsWithoutDefault, translate, translations };