@react-native-ama/forms 1.0.0

package/src/hooks/useFormField.test.tsx

@@ -0,0 +1,183 @@
+import * as AMAProvider from '@react-native-ama/core';
+import { renderHook } from '@testing-library/react-native';
+import { waitFor } from '@testing-library/react-native';
+import * as React from 'react';
+
+import * as Form from '../components/Form';
+import { useFormField } from './useFormField';
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+let submitForm: jest.Mock = jest.fn();
+
+describe('useFormField', () => {
+  let localRef: any[] = [];
+
+  beforeEach(() => {
+    jest.spyOn(AMAProvider, 'useAMAContext').mockReturnValue({
+      isScreenReaderEnabled: true,
+    } as any);
+
+    jest.spyOn(Form, 'useForm').mockImplementation(() => {
+      return { refs: localRef, submitForm };
+    });
+  });
+
+  afterEach(function () {
+    localRef.splice(-1);
+  });
+
+  it('register itself as ref when is mounted', async () => {
+    renderHook(
+      () => {
+        return useFormField({
+          ref: { current: 'hello' },
+          hasFocusCallback: false,
+          id: 'my-id',
+          nextFieldId: 'next-field-id',
+          nextFormFieldRef: { current: 'nextFormFieldRef' },
+          hasValidation: false,
+        });
+      },
+      { wrapper: renderHookWrapper },
+    );
+
+    await waitFor(() => {
+      expect(localRef).toHaveLength(1);
+      expect(localRef[0]).toEqual({
+        hasFocusCallback: false,
+        ref: { current: { current: 'hello' } },
+        id: 'my-id',
+        hasError: undefined,
+        hasValidation: false,
+        isEditable: true,
+      });
+    });
+  });
+
+  it('unregister itself from the refs when is mounted', () => {
+    const { unmount } = renderHook(
+      () => {
+        return useFormField({
+          ref: { current: 'hello' },
+          hasFocusCallback: false,
+          hasValidation: false,
+        });
+      },
+      { wrapper: renderHookWrapper },
+    );
+
+    unmount();
+
+    expect(localRef.length).toBe(0);
+  });
+
+  describe('focusNextFormField', () => {
+    describe('Given the form field is not the last of the refs', () => {
+      describe('checks for focus when calling focusNextFormField', function () {
+        it('checks only against the current field if next one does not have the focus callback', async () => {
+          const focus = jest.fn();
+          const ref = { current: { focus, isFocused: jest.fn() } };
+
+          const { result } = renderHook(
+            () => {
+              const first = useFormField({
+                ref: { current: 'random ref' },
+                hasFocusCallback: true,
+                hasValidation: false,
+              });
+
+              // next field
+              useFormField({
+                ref,
+                hasFocusCallback: false,
+                hasValidation: false,
+              });
+
+              return first;
+            },
+            { wrapper: renderHookWrapper },
+          );
+
+          result.current.focusNextFormField();
+
+          await waitFor(() =>
+            expect(checkFocusTrap).toHaveBeenCalledWith({
+              ref: { current: 'random ref' },
+              shouldHaveFocus: false,
+            }),
+          );
+
+          expect(checkFocusTrap).toHaveBeenCalledTimes(1);
+        });
+      });
+    });
+
+    it('triggers submitForm when the element is the last one of the ref', async () => {
+      jest.spyOn(AMAProvider, 'useAMAContext').mockReturnValue({
+        isScreenReaderEnabled: true,
+      } as any);
+
+      const ref = { current: 'whatever' };
+
+      const { result } = renderHook(
+        () => {
+          useFormField({
+            ref: { current: 'random ref' },
+            hasFocusCallback: false,
+            hasValidation: false,
+          });
+
+          // next field
+          return useFormField({
+            ref,
+            hasFocusCallback: false,
+            hasValidation: false,
+          });
+        },
+        { wrapper: renderHookWrapper },
+      );
+
+      await waitFor(() => {
+        result.current.focusNextFormField();
+
+        expect(submitForm).toHaveBeenCalledWith();
+      });
+    });
+  });
+});
+
+let setFocus: jest.Mock;
+let checkFocusTrap: jest.Mock;
+
+function mockAMACore() {
+  const original = jest.requireActual('@react-native-ama/core');
+
+  setFocus = jest.fn();
+
+  return {
+    ...original,
+    useFocus: () => {
+      return {
+        setFocus,
+      };
+    },
+  };
+}
+
+function mockAMAInternal() {
+  const original = jest.requireActual('@react-native-ama/internal');
+
+  checkFocusTrap = jest.fn().mockResolvedValue(null);
+
+  return { ...original, checkFocusTrap };
+}
+
+const renderHookWrapper = ({ children }) => (
+  <AMAProvider.AMAProvider>{children}</AMAProvider.AMAProvider>
+);
+
+jest.mock('@react-native-ama/core', () => mockAMACore());
+jest.mock('@react-native-ama/internal', () => mockAMAInternal());

package/src/hooks/useFormField.ts

@@ -0,0 +1,133 @@
+import { useChecks } from '@react-native-ama/core';
+import { applyStyle } from '@react-native-ama/internal';
+import React from 'react';
+import { Keyboard, ViewStyle } from 'react-native';
+
+import { useForm } from '../components/Form';
+
+export type UseFormField = {
+  ref?: React.RefObject<any> | React.ForwardedRef<any> | null;
+  hasFocusCallback: boolean;
+  id?: string;
+  nextFieldId?: string;
+  nextFormFieldRef?: React.RefObject<any>;
+  accessibilityHint?: string;
+  style?: ViewStyle;
+  editable?: boolean;
+  hasValidation: boolean;
+  hasError?: boolean;
+  errorMessage?: string;
+};
+
+export const useFormField = ({
+  ref,
+  hasFocusCallback,
+  id,
+  nextFieldId,
+  nextFormFieldRef,
+  hasValidation,
+  hasError,
+  accessibilityHint,
+  errorMessage,
+  editable = true,
+  style = {},
+}: UseFormField) => {
+  const { refs, submitForm, focusField } = useForm();
+  const fieldRef = React.useRef(ref);
+
+  const checks = __DEV__ ? useChecks?.() : undefined;
+
+  const getMyIndex = () => {
+    const allRefs = refs!;
+    const item = allRefs.find(r => r.ref === fieldRef);
+
+    return item ? allRefs.indexOf(item) : -1;
+  };
+
+  const focusNextFormField = () => {
+    const isLastItem = isLastField();
+
+    if (isLastItem) {
+      Keyboard.dismiss();
+
+      submitForm();
+
+      return;
+    }
+
+    const currentField = refs![getMyIndex()];
+
+    focusField?.(getNextFieldRef());
+
+    __DEV__ &&
+      currentField?.hasFocusCallback &&
+      checks?.checkFocusTrap({
+        ref: currentField?.ref?.current,
+        shouldHaveFocus: false,
+      });
+  };
+
+  const getNextFieldRef = () => {
+    const allRefs = refs || [];
+
+    if (nextFormFieldRef) {
+      return {
+        ref: nextFormFieldRef,
+      };
+    } else if (nextFieldId) {
+      return allRefs.find(item => item.id === nextFieldId);
+    }
+
+    return allRefs[getMyIndex() + 1];
+  };
+
+  const isLastField = () => {
+    const myIndex = getMyIndex();
+
+    return myIndex === refs!.length - 1;
+  };
+
+  React.useEffect(() => {
+    refs?.push({
+      ref: fieldRef,
+      hasFocusCallback,
+      id,
+      hasValidation,
+      hasError,
+      isEditable: editable,
+    });
+
+    return () => {
+      const myIndex = getMyIndex();
+
+      refs?.splice(myIndex, 1);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  React.useEffect(() => {
+    const myRefIndex = refs?.findIndex(item => item.ref === fieldRef);
+
+    // @ts-ignore
+    refs[myRefIndex].hasError = hasError;
+    // @ts-ignore
+    refs[myRefIndex].isEditable = editable;
+  }, [editable, hasError, refs]);
+
+  const fullAccessibilityHint = [accessibilityHint, errorMessage]
+    .filter(Boolean)
+    .join(',');
+
+  return __DEV__
+    ? {
+        focusNextFormField,
+        isLastField,
+        style: applyStyle?.({ style, debugStyle: checks?.debugStyle }),
+        accessibilityHint: fullAccessibilityHint,
+      }
+    : {
+        focusNextFormField,
+        accessibilityHint: fullAccessibilityHint,
+        isLastField,
+      };
+};

package/src/hooks/useTextInput.ts

@@ -0,0 +1,128 @@
+import { useChecks } from '@react-native-ama/core';
+import { applyStyle } from '@react-native-ama/internal';
+import * as React from 'react';
+import type {
+  LayoutChangeEvent,
+  NativeSyntheticEvent,
+  ReturnKeyTypeOptions,
+  StyleProp,
+  TextInputSubmitEditingEventData,
+  TextStyle,
+  ViewStyle,
+} from 'react-native';
+
+import { TextInputProps } from '../components/TextInput';
+import { UseFormField, useFormField } from './useFormField';
+
+type UseTextInput = Omit<UseFormField, 'hasFocusCallback'> & {
+  onLayout?: (event: LayoutChangeEvent) => void;
+  returnKeyType?: ReturnKeyTypeOptions;
+  onSubmitEditing?: (
+    event: NativeSyntheticEvent<TextInputSubmitEditingEventData>,
+  ) => void;
+  accessibilityLabel: string;
+  editable?: boolean;
+  style?: ViewStyle | StyleProp<TextStyle> | null;
+  required: boolean;
+  requiredMessage?: string;
+  hasValidation: boolean;
+  hasError?: boolean;
+  errorMessage?: string;
+};
+
+export const useTextInput = ({
+  onLayout,
+  returnKeyType,
+  onSubmitEditing,
+  accessibilityLabel,
+  requiredMessage,
+  required,
+  ...rest
+}: UseTextInput) => {
+  const [theReturnKeyType, setTheReturnKeyType] = React.useState(
+    returnKeyType || 'next',
+  );
+  const { style: formFieldStyle, ...formField } = useFormField({
+    hasFocusCallback: true,
+    ...rest,
+  });
+
+  const handleOnSubmitEditing = (
+    event: NativeSyntheticEvent<TextInputSubmitEditingEventData>,
+  ) => {
+    onSubmitEditing?.(event);
+
+    formField.focusNextFormField();
+  };
+
+  const checkReturnKeyType = (event: LayoutChangeEvent) => {
+    const setReturnKeyTypeAsDone =
+      formField.isLastField() && returnKeyType == null;
+
+    if (setReturnKeyTypeAsDone) {
+      setTheReturnKeyType('done');
+    }
+
+    onLayout?.(event);
+  };
+
+  const checks = __DEV__ ? useChecks?.() : undefined;
+
+  __DEV__ &&
+    checks?.noUndefinedProperty({
+      properties: { accessibilityLabel },
+      property: 'accessibilityLabel',
+      rule: 'NO_FORM_LABEL',
+    });
+  __DEV__ &&
+    checks?.noUppercaseStringChecker({
+      text: accessibilityLabel,
+    });
+  __DEV__ &&
+    checks?.noUppercaseStringChecker({
+      text: rest.accessibilityHint,
+    });
+  __DEV__ &&
+    accessibilityLabel?.trim().slice(-1) === '*' &&
+    checks?.logResult('NO_FORM_LABEL_ENDING_WITH_ASTERISK', {
+      rule: 'NO_FORM_LABEL_ENDING_WITH_ASTERISK',
+      message:
+        'Form labels should not end with an asterisk. Please remove it and provide a required message instead.',
+    });
+  __DEV__ &&
+    required &&
+    checks?.noUndefinedProperty({
+      properties: { requiredMessage },
+      property: 'requiredMessage',
+      rule: 'NO_FORM_LABEL_ENDING_WITH_ASTERISK',
+    });
+
+  const fullAccessibilityLabel = required
+    ? `${accessibilityLabel}, ${requiredMessage}`
+    : accessibilityLabel;
+
+  const advancedProps: Partial<TextInputProps> = {
+    accessibilityLabel: fullAccessibilityLabel,
+    returnKeyType: theReturnKeyType,
+    onSubmitEditing: handleOnSubmitEditing,
+    onLayout: checkReturnKeyType,
+    blurOnSubmit: theReturnKeyType === 'done',
+  };
+
+  return __DEV__
+    ? {
+        ...rest,
+        ...formField,
+        ...advancedProps,
+        style: applyStyle?.({
+          // @ts-ignore
+          style: formFieldStyle,
+          debugStyle: checks?.debugStyle,
+        }) as any,
+      }
+    : {
+        ...rest,
+        ...formField,
+        ...advancedProps,
+      };
+};

package/src/index.ts

@@ -0,0 +1,39 @@
+// Components
+import {
+  FormActions,
+  FormProps,
+  Form as FormProvider,
+} from './components/Form';
+import { FormField, FormFieldProps } from './components/FormField';
+import { FormSubmit, FormSubmitProps } from './components/FormSubmit';
+import { FormSwitch, FormSwitchProps } from './components/FormSwitch';
+
+type FormComponent = React.FunctionComponent<FormProps> & {
+  Submit: (props: FormSubmitProps) => JSX.Element;
+  Field: React.FunctionComponent<FormFieldProps>;
+  Switch: (props: FormSwitchProps) => JSX.Element;
+};
+
+// @ts-ignore
+const Form: FormComponent = FormProvider;
+Form.Submit = FormSubmit;
+Form.Field = FormField;
+Form.Switch = FormSwitch;
+
+export { Form, FormField, FormSubmit };
+
+// Components
+export { TextInput } from './components/TextInput';
+
+// Hooks
+export { useFormField } from './hooks/useFormField';
+export { useTextInput } from './hooks/useTextInput';
+
+// Types
+export {
+  type FormProps,
+  type FormActions,
+  type FormFieldProps,
+  type FormSubmitProps,
+  type FormSwitchProps,
+};