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

package/src/components/FormCore/types.ts

@@ -0,0 +1,277 @@
+import React from 'react';
+import { DefaultValues } from 'react-hook-form';
+
+export interface FormValues {
+  [k: string]: string;
+}
+
+export type FocusHandler = (event?: any) => void;
+export type ChangeHandler = (event?: any) => void;
+
+export type SubmitHandler<Values extends FormValues = FormValues> = (
+  values: Values,
+  event?: React.BaseSyntheticEvent
+) => void;
+
+type RefCallback = (node: any) => void;
+
+export interface SetFormValueParams<Name extends string = string> {
+  /**
+   * `Form` value `name`
+   */
+  name: Name;
+
+  /**
+   * `value` to be applied
+   */
+  value: string;
+
+  /**
+   * Whether validation should be ran
+   */
+  shouldValidate?: boolean;
+}
+
+type SetFormValue<Name extends string = string> = (
+  params: SetFormValueParams<Name>
+) => void;
+
+/**
+ * `Field` validator callback
+ *
+ * @param value current `Field` value`
+ * @param values current `Form` values
+ * @returns `string` message on invalid `Field`, `undefined` on valid
+ */
+export type Validator<Values extends FormValues = FormValues> = (
+  value: string,
+  values: Values
+) => string | undefined;
+
+export type Validate<Values extends FormValues = FormValues> =
+  | Validator<Values>
+  | Record<string, Validator<Values>>;
+
+export interface RegisterFieldParams<Values extends FormValues = FormValues> {
+  disabled?: boolean;
+  name: string;
+  onBlur?: FocusHandler;
+  onChange?: ChangeHandler;
+  validate?: Validate<Values>;
+  value?: string;
+}
+
+export interface UseFormParams<
+  Values extends FormValues = FormValues,
+  OnSubmit extends SubmitHandler<Values> = SubmitHandler<Values>
+> {
+  /**
+   * Custom error message provided to `Error` on call to `useForm` outside `FormProvider`
+   */
+  errorMessage?: string;
+
+  /**
+   * Submit event handler
+   */
+  onSubmit?: OnSubmit;
+}
+
+/**
+ * `Form` aware `Field` props to be provided to UI components
+ */
+interface RegisterProps<Name extends string = string> {
+  disabled?: boolean;
+  name: Name;
+  onBlur: FocusHandler;
+  onChange: ChangeHandler;
+  ref: RefCallback;
+}
+
+interface FieldState {
+  errorMessage: string | undefined;
+  hasError: boolean;
+  invalid: boolean;
+  isDirty: boolean;
+  isTouched: boolean;
+}
+
+export type UseForm<Values extends FormValues = FormValues> = {
+  /**
+   * Get `Field` state of `name`
+   */
+  getFieldState: (name: string) => FieldState;
+
+  /**
+   * Get current `Form` values
+   */
+  getValues: () => FormValues;
+
+  /**
+   * `Form` validity state
+   */
+  isValid: boolean;
+
+  /**
+   * Registers `name` to `Form` values, returns `Form` aware `Field` handlers and `ref`
+   */
+  registerField: (params: RegisterFieldParams) => RegisterProps;
+
+  /**
+   * Reset `Form` values
+   */
+  reset: (values: Values) => void;
+
+  /**
+   * Sets `Form` value of `name` param to provided `value`
+   */
+  setFormValue: SetFormValue;
+
+  /**
+   * `Form` submit callback prop
+   *
+   * @usage
+   * ```tsx
+   * const { onSubmit } = useForm();
+   *
+   * <form onSubmit={onSubmit} />
+   * ```
+   */
+  onSubmit: (e?: React.BaseSyntheticEvent) => void;
+};
+
+export type FormHandle<Values extends FormValues = FormValues> = {
+  /**
+   * Get current `Form` values
+   */
+  getValues: () => Values;
+
+  /**
+   * Reset `Form` values to default values
+   */
+  reset: () => void;
+};
+
+type ValidationMode = 'onBlur' | 'onChange' | 'onSubmit' | 'onTouched' | 'all';
+
+export interface FormProviderProps<Values extends FormValues = FormValues> {
+  /**
+   * `Form` children
+   */
+  children?: React.ReactNode;
+
+  /**
+   * `Form` default values
+   */
+  defaultValues?: DefaultValues<Values>;
+
+  /**
+   * Validation mode applied to `Field` components:
+   *
+   * - `onTouched`: Validate on first blur event and every subsequent change event
+   * - `onBlur`: validate on blur events only
+   * - `onChange`: validate on change events, non-performant
+   * - `all`: validate on blur and change events
+   *
+   * @default
+   * "onTouched"
+   */
+  mode?: ValidationMode;
+}
+
+/**
+ * For use with React only.
+ */
+export interface UseField<Name extends string = string>
+  extends FieldState,
+    RegisterProps {
+  name: Name;
+}
+
+/**
+ * For use with React only.
+ */
+export interface UseFieldParams<
+  OnBlur extends FocusHandler | undefined,
+  OnChange extends ChangeHandler | undefined,
+  Values extends FormValues = FormValues
+> {
+  /**
+   * Controlled `disabled` state
+   */
+  disabled?: boolean;
+
+  /**
+   * Controlled blur event handler
+   */
+  onBlur?: OnBlur;
+
+  /**
+   * Controlled change event handler
+   */
+  onChange?: OnChange;
+
+  /**
+   * `Field` name, must be unique
+   */
+  name: string;
+
+  /**
+   * `Field` validation handler. Accepts a callback function or an
+   * object of callback functions to validate against
+   *
+   * @usage
+   * ```tsx
+   *
+   * // validate `password` and `confim_pasword` values match
+   * const validate = (value: string, values: Values) =>
+   *   value === values['confirm_password']
+   *     ? undefined
+   *     : 'Passwords must match!';
+   *
+   *
+   * const passwordProps = useField({ name: 'password' });
+   *
+   * const confirmPasswordProps = useField({
+   *   name: 'confirm_password',
+   *   validate
+   * });
+   *
+   * return (
+   *   <>
+   *     <TextField {...passwordProps} />
+   *     <TextField {...confirmPasswordProps} />
+   *   </>
+   * )
+   * ```
+   */
+  validate?: Validate<Values>;
+}
+
+/**
+ * For use with React Native only.
+ */
+export interface UseControlledFieldParams<
+  OnBlur extends FocusHandler | undefined,
+  Values extends FormValues = FormValues
+> extends Omit<UseFieldParams<OnBlur, undefined, Values>, 'onChange'> {
+  /**
+   * Controlled text change event handler
+   */
+  onChangeText?: (value: string) => void;
+}
+
+/**
+ * For use with React Native only.
+ */
+export interface UseControlledField<Name extends string = string>
+  extends Omit<UseField<Name>, 'onChange'> {
+  name: Name;
+
+  /**
+   * React Native only.
+   * Controlled text change event handler
+   */
+  onChangeText: (value: string) => void;
+
+  value: string;
+}

package/src/components/FormCore/useControlledField.ts

@@ -0,0 +1,73 @@
+import { useController } from 'react-hook-form';
+
+import {
+  FormValues,
+  FocusHandler,
+  UseControlledField,
+  UseControlledFieldParams,
+} from './types';
+import { isTypedFunction } from '@aws-amplify/ui';
+
+export const DEFAULT_ERROR_MESSAGE =
+  '`useControlledField` must be used within a `FormProvider`';
+
+/**
+ * `Field` integration hook for usage with React Native `Field` components
+ *
+ * @param params Requires `name`, all additional params optional
+ * @returns `Form` aware `Field` handlers and state values
+ */
+export default function useControlledField<OnBlur extends FocusHandler>({
+  onBlur: _onBlur,
+  onChangeText: _onChangeText,
+  ...rest
+}: UseControlledFieldParams<OnBlur>): UseControlledField {
+  // If called outside a `FormProvider`, `useController` throws a `TypeError` instead
+  // of failing gracefully (for example returning `undefined` or `null`).
+  // Wrap call to `useController` in a `try`/`catch` for graceful failure
+  let controller;
+  try {
+    controller = useController<FormValues>(rest);
+  } catch {
+    throw new Error(DEFAULT_ERROR_MESSAGE);
+  }
+
+  const {
+    // `useController.onChange` handles `string` values passed directly to `onChange`
+    // for RN support, map to `onChangeText`
+    field: { name, onBlur, onChange: onChangeText, ref, value },
+    fieldState: { error, isDirty, isTouched },
+    formState: { isValid: invalid },
+  } = controller;
+
+  const errorMessage = error?.message;
+  const hasError = !!errorMessage;
+
+  const handleBlur = (event: Parameters<OnBlur>[0]) => {
+    if (isTypedFunction(_onBlur)) {
+      _onBlur(event);
+    }
+    // `useController.onBlur` does not receive params
+    onBlur();
+  };
+
+  const handleChangeText = (event: string) => {
+    if (isTypedFunction(_onChangeText)) {
+      _onChangeText(event);
+    }
+    onChangeText(event);
+  };
+
+  return {
+    errorMessage,
+    hasError,
+    invalid,
+    isDirty,
+    isTouched,
+    name,
+    onBlur: handleBlur,
+    onChangeText: handleChangeText,
+    ref,
+    value,
+  };
+}

package/src/components/FormCore/useField.ts

@@ -0,0 +1,25 @@
+import useForm from './useForm';
+import { ChangeHandler, FocusHandler, UseField, UseFieldParams } from './types';
+
+export const DEFAULT_ERROR_MESSAGE =
+  '`useField` must be used within a `FormProvider`';
+
+/**
+ * `Field` integration hook for usage with React `Field` components.
+ *
+ * @param params Requires `name`, all additional params optional
+ * @returns `Form` aware `Field` event handlers and state values
+ */
+export default function useField<
+  OnBlur extends FocusHandler,
+  OnChange extends ChangeHandler
+>(params: UseFieldParams<OnBlur, OnChange>): UseField {
+  const { getFieldState, registerField } = useForm({
+    errorMessage: DEFAULT_ERROR_MESSAGE,
+  });
+
+  return {
+    ...registerField(params),
+    ...getFieldState(params.name),
+  };
+}

package/src/components/FormCore/useForm.ts

@@ -0,0 +1,84 @@
+import React from 'react';
+import { useFormContext } from 'react-hook-form';
+import { noop } from '@aws-amplify/ui';
+
+import {
+  FormValues,
+  RegisterFieldParams,
+  SetFormValueParams,
+  SubmitHandler,
+  UseForm,
+  UseFormParams,
+} from './types';
+
+export const DEFAULT_ERROR_MESSAGE =
+  '`useForm` must be called inside a `FormProvider`';
+
+/**
+ * Utility hook corresponding to `FormProvider`, must be used within a `FormProvider`
+ *
+ * @internal Extend for public export. `useForm` and `UseForm` are an abstraction layer
+ * on top of `useFormContext` and `UseFormReturn`, imported from `react-hook-form`
+ *
+ * @param options optional parameters
+ * @returns `Form` utilities
+ */
+export default function useForm<
+  Values extends FormValues = FormValues,
+  OnSubmit extends SubmitHandler = SubmitHandler
+>(options: UseFormParams<Values, OnSubmit> = {}): UseForm<Values> {
+  const formContext = useFormContext();
+  const { errorMessage, onSubmit: _onSubmit } = options;
+
+  if (!formContext) {
+    throw new Error(errorMessage ?? DEFAULT_ERROR_MESSAGE);
+  }
+
+  const {
+    formState,
+    getFieldState: _getFieldState,
+    getValues,
+    handleSubmit,
+    register,
+    reset,
+    setValue,
+  } = formContext;
+
+  // Do not memoize, `formState` updates on all events
+  const getFieldState = (name: string) => {
+    const { error, ...fieldState } = _getFieldState(name, formState);
+
+    const { message: errorMessage } = error ?? {};
+    return { ...fieldState, errorMessage, hasError: !!errorMessage };
+  };
+
+  // memoize `registerField` and `setFormValue` together,
+  // `register` and `setValue` maintain stable references
+  const { registerField, setFormValue } = React.useMemo(() => {
+    return {
+      registerField: ({ name, ...options }: RegisterFieldParams) =>
+        register(name, options),
+      setFormValue: ({ name, value, ...options }: SetFormValueParams) =>
+        setValue(name, value, options),
+    };
+  }, [register, setValue]);
+
+  const onSubmit = React.useCallback(
+    (event?: React.BaseSyntheticEvent) => {
+      const handler = _onSubmit ? handleSubmit(_onSubmit) : noop;
+
+      handler(event);
+    },
+    [_onSubmit, handleSubmit]
+  );
+
+  return {
+    getFieldState,
+    getValues,
+    isValid: formState.isValid,
+    onSubmit,
+    registerField,
+    reset,
+    setFormValue,
+  };
+}

package/src/components/FormCore/withFormProvider.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+
+import { AnyComponent, MergeProps } from '../../types';
+
+import FormProvider from './FormProvider';
+import { FormHandle, FormProviderProps } from './types';
+
+/**
+ * @param Child `Form` base component wrapped inside `FormProvider`
+ * @returns Composed `Form` component exposing `FormContext` values to descendents
+ */
+export default function withFormProvider<
+  ChildComp extends AnyComponent,
+  ChildProps extends React.ComponentPropsWithRef<ChildComp>,
+  Props extends MergeProps<FormProviderProps, ChildProps>
+>(
+  Child: ChildComp
+): React.ForwardRefExoticComponent<
+  React.PropsWithoutRef<Props> & React.RefAttributes<FormHandle>
+> {
+  return React.forwardRef<FormHandle, Props>(function Form(
+    { defaultValues, mode, ...props },
+    ref
+  ) {
+    return (
+      <FormProvider defaultValues={defaultValues} mode={mode} ref={ref}>
+        <Child {...(props as ChildProps)} />
+      </FormProvider>
+    );
+  });
+}

package/src/components/RenderNothing/RenderNothing.tsx

@@ -0,0 +1,6 @@
+/**
+ * Utility component for rendering nothing.
+ */
+export default function RenderNothing<Props>(_: Props): JSX.Element | null {
+  return null;
+}

package/src/components/RenderNothing/index.ts

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

package/src/components/index.ts

@@ -0,0 +1,15 @@
+export {
+  FormProvider,
+  FormProviderProps,
+  FormValues,
+  FormHandle,
+  SubmitHandler,
+  useField,
+  useForm,
+  UseForm,
+  Validate,
+  Validator,
+  withFormProvider,
+} from './FormCore';
+
+export { RenderNothing } from './RenderNothing';

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export {
+  default as useDeprecationWarning,
+  UseDeprecationWarning,
+} from './useDeprecationWarning';
+export { default as useHasValueUpdated } from './useHasValueUpdated';
+export { default as usePreviousValue } from './usePreviousValue';
+export { default as useSetUserAgent } from './useSetUserAgent';
+export { default as useTimeout } from './useTimeout';

package/src/hooks/useDeprecationWarning.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+
+export type UseDeprecationWarning = (params: {
+  shouldWarn: boolean;
+  message: string;
+}) => void;
+
+/**
+ * Logs a deprecation warning message.
+ *
+ * @important Please use the React/React Native specific platform implementations.
+ * This version of the hook is a base implementation that the others extend from due
+ * to env differences between running in RN or the browser
+ */
+const useDeprecationWarning: UseDeprecationWarning = ({
+  shouldWarn,
+  message,
+}) => {
+  React.useEffect(() => {
+    if (shouldWarn) {
+      // eslint-disable-next-line no-console
+      console.warn(message);
+    }
+  }, [shouldWarn, message]);
+};
+
+export default useDeprecationWarning;

package/src/hooks/useHasValueUpdated.ts

@@ -0,0 +1,28 @@
+import { isUndefined } from '@aws-amplify/ui';
+
+import usePreviousValue from './usePreviousValue';
+
+/**
+ * @param value `value` to track for updates
+ * @param ignoreFirstRender whether to ignore initial render. defaults to `false`
+ * @returns a boolean representing whether the tracked `value` has updated between renders
+ *
+ * Returns `false`:
+ * - on initial render when ignoring first render
+ * - current and previous `value` are equal
+ *
+ * Returns `true`:
+ * - on initial render when not ignoring first render (default behavior)
+ * - current and previous `value` are not equal
+ */
+export default function useHasValueUpdated<Value>(
+  value: Value,
+  ignoreFirstRender = false
+): boolean {
+  const previous = usePreviousValue<Value>(value);
+  const shouldIgnoreChange = isUndefined(previous) && ignoreFirstRender;
+  if (shouldIgnoreChange) {
+    return false;
+  }
+  return previous !== value;
+}

package/src/hooks/usePreviousValue.ts

@@ -0,0 +1,15 @@
+import { useEffect, useRef } from 'react';
+
+export default function usePreviousValue<Value>(
+  value: Value
+): Value | undefined {
+  const previous = useRef<Value>();
+
+  // update ref post render
+  useEffect(() => {
+    previous.current = value;
+  }, [value]);
+
+  // return previous ref
+  return previous.current;
+}

package/src/hooks/useSetUserAgent.ts

@@ -0,0 +1,18 @@
+import { useEffect } from 'react';
+import { setUserAgent, SetUserAgentOptions } from '@aws-amplify/ui';
+
+export default function useSetUserAgent({
+  componentName,
+  packageName,
+  version,
+}: SetUserAgentOptions): void {
+  useEffect(() => {
+    const clearUserAgent = setUserAgent({
+      componentName,
+      packageName,
+      version,
+    });
+
+    return clearUserAgent;
+  }, [componentName, packageName, version]);
+}

package/src/hooks/useTimeout.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+import { isTypedFunction } from '@aws-amplify/ui';
+
+export default function useTimeout({
+  callback,
+  delay,
+}: {
+  callback?: () => void;
+  delay?: number;
+}): void {
+  const storedCallback = React.useRef(callback);
+
+  React.useLayoutEffect(() => {
+    storedCallback.current = callback;
+  }, [callback]);
+
+  React.useEffect(() => {
+    if (!isTypedFunction(storedCallback.current) || !delay) {
+      return;
+    }
+
+    const timeoutId = setTimeout(() => {
+      storedCallback.current?.();
+    }, delay);
+
+    return () => {
+      clearTimeout(timeoutId);
+    };
+  }, [delay]);
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// features
+export {
+  AuthenticatorComponentDefaults,
+  AuthenticatorComponentDefaultProps,
+  AuthenticatorComponentOverrides,
+  AuthenticatorFooterComponent,
+  AuthenticatorFormFieldsComponent,
+  AuthenticatorHeaderComponent,
+  AuthenticatorLegacyField,
+  AuthenticatorMachineContext,
+  AuthenticatorProvider,
+  AuthenticatorRouteComponentKey,
+  AuthenticatorRouteComponentName,
+  isAuthenticatorComponentRouteKey,
+  resolveAuthenticatorComponents,
+  useAuthenticator,
+  useAuthenticatorRoute,
+  UseAuthenticator,
+  useAuthenticatorInitMachine,
+  UseAuthenticatorRoute,
+} from './Authenticator';
+
+export {
+  FormProvider,
+  FormProviderProps,
+  RenderNothing,
+  FormValues,
+  FormHandle,
+  useField,
+  useForm,
+  UseForm,
+  Validate,
+  Validator,
+  withFormProvider,
+} from './components';
+
+export {
+  useDeprecationWarning,
+  UseDeprecationWarning,
+  useHasValueUpdated,
+  usePreviousValue,
+  useSetUserAgent,
+  useTimeout,
+} from './hooks';
+
+export { MergeProps } from './types';
+
+export { createContextUtilities } from './utils';

package/src/types/index.ts

@@ -0,0 +1 @@
+export { AnyComponent, MergeProps } from './types';