@jobber/components-native 0.38.0 → 0.40.0

package/src/Form/context/types.ts

@@ -0,0 +1,34 @@
+import { MutableRefObject } from "react";
+import { FieldValues, UseFormReturn } from "react-hook-form";
+
+export interface UseConfirmBeforeBackProps {
+  alwaysPreventBack: boolean;
+  onAcceptEvent?: () => void;
+  shouldShowAlert: boolean;
+  showLostProgressMessage?: boolean;
+}
+
+interface LocalCacheOptions {
+  /**
+   * Allows the ability to specify that the cached data contains pre-filled data.
+   * By setting this the cached data will only be applied if the same id is based
+   * for the same key. If the id doesn't match the data will be deleted from the
+   * cache.
+   */
+  readonly id?: string | string[];
+}
+
+export interface AtlantisFormContextProps {
+  useConfirmBeforeBack: (
+    props: UseConfirmBeforeBackProps,
+  ) => MutableRefObject<() => void>;
+  useInternalFormLocalCache: <TData extends FieldValues>(
+    formMethods: UseFormReturn<TData>,
+    cacheKey?: string,
+    options?: LocalCacheOptions,
+  ) => {
+    setLocalCache: (data: TData) => void;
+    removeLocalCache: () => void;
+  };
+  headerHeight: number;
+}

package/src/Form/hooks/useFormViewRefs.ts

@@ -0,0 +1,23 @@
+import { RefObject, useCallback, useRef } from "react";
+import { View } from "react-native";
+import { KeyboardAwareScrollView } from "react-native-keyboard-aware-scroll-view";
+
+interface UseFormViewRefsReturn {
+  readonly scrollViewRef: RefObject<KeyboardAwareScrollView>;
+  readonly bottomViewRef: RefObject<View>;
+  readonly scrollToTop: () => void;
+}
+
+export function useFormViewRefs(): UseFormViewRefsReturn {
+  const scrollViewRef: RefObject<KeyboardAwareScrollView> =
+    useRef<KeyboardAwareScrollView>(null);
+  const bottomViewRef: RefObject<View> = useRef<View>(null);
+  const scrollToTop = useCallback(() => {
+    scrollViewRef.current?.scrollToPosition(0, 0);
+  }, [scrollViewRef]);
+  return {
+    scrollViewRef: scrollViewRef,
+    bottomViewRef,
+    scrollToTop,
+  };
+}

package/src/Form/hooks/useInternalForm.ts

@@ -0,0 +1,99 @@
+import {
+  FieldValues,
+  UseFormHandleSubmit,
+  UseFormReturn,
+  useForm,
+} from "react-hook-form";
+import { MutableRefObject, RefObject } from "react";
+import { KeyboardAwareScrollView } from "react-native-keyboard-aware-scroll-view";
+import { useAtlantisContext } from "../../AtlantisContext";
+import { useAtlantisFormContext } from "../context/AtlantisFormContext";
+import { InternalFormProps } from "../types";
+
+type UseInternalFormProps<T extends FieldValues, SubmitResponseType> = Pick<
+  InternalFormProps<T, SubmitResponseType>,
+  | "mode"
+  | "reValidateMode"
+  | "initialValues"
+  | "formRef"
+  | "localCacheKey"
+  | "localCacheExclude"
+  | "localCacheId"
+> & {
+  scrollViewRef?: RefObject<KeyboardAwareScrollView>;
+  readonly saveButtonHeight: number;
+  readonly messageBannerHeight: number;
+};
+
+interface UseInternalForm<T extends FieldValues> {
+  readonly formMethods: UseFormReturn<T>;
+  readonly handleSubmit: UseFormHandleSubmit<T>;
+  readonly isSubmitting: boolean;
+  readonly isDirty: boolean;
+  readonly removeListenerRef: MutableRefObject<() => void>;
+  readonly setLocalCache: (data: T) => void;
+}
+
+export function useInternalForm<T extends FieldValues, SubmitResponseType>({
+  mode,
+  reValidateMode,
+  initialValues,
+  formRef,
+  localCacheKey,
+  localCacheId,
+  scrollViewRef,
+  saveButtonHeight,
+  messageBannerHeight,
+}: UseInternalFormProps<T, SubmitResponseType>): UseInternalForm<T> {
+  const { useConfirmBeforeBack, useInternalFormLocalCache } =
+    useAtlantisFormContext();
+
+  const { isOnline } = useAtlantisContext();
+
+  const formMethods = useForm<T>({
+    mode,
+    reValidateMode,
+    defaultValues: initialValues,
+    shouldFocusError: false,
+  });
+
+  const clientSideSaveOn = localCacheKey && localCacheKey !== "INVALID";
+
+  const { setLocalCache, removeLocalCache } = useInternalFormLocalCache(
+    formMethods,
+    localCacheKey,
+    {
+      id: localCacheId,
+    },
+  );
+
+  const {
+    handleSubmit,
+    formState: { isSubmitting, isDirty },
+  } = formMethods;
+
+  if (formRef) {
+    formRef.current = {
+      ...formMethods,
+      saveButtonHeight,
+      messageBannerHeight,
+      scrollViewRef,
+    };
+  }
+
+  const removeListenerRef = useConfirmBeforeBack({
+    alwaysPreventBack: isSubmitting,
+    shouldShowAlert: isDirty,
+    onAcceptEvent: isOnline ? removeLocalCache : undefined,
+    showLostProgressMessage: isOnline || !clientSideSaveOn ? true : false,
+  });
+
+  return {
+    setLocalCache,
+    formMethods,
+    handleSubmit,
+    isSubmitting,
+    isDirty,
+    removeListenerRef,
+  };
+}

package/src/Form/hooks/useOfflineHandler.ts

@@ -0,0 +1,36 @@
+import { useCallback } from "react";
+import { useIntl } from "react-intl";
+import { Alert } from "react-native";
+import { messages } from "../messages";
+
+export function useOfflineHandler(): (
+  callback: () => void,
+  dismiss: () => void,
+) => () => void {
+  const { formatMessage } = useIntl();
+
+  const handleOfflineSubmit = useCallback(
+    (callback: () => void, dismiss: () => void) => {
+      return () => {
+        Alert.alert(
+          formatMessage(messages.unavailableNetworkTitle),
+          formatMessage(messages.unavailableNetworkMessage),
+          [
+            {
+              text: formatMessage(messages.dismissAlertButton),
+              style: "cancel",
+              onPress: dismiss,
+            },
+            {
+              text: formatMessage(messages.retryAlertButton),
+              style: "default",
+              onPress: callback,
+            },
+          ],
+        );
+      };
+    },
+    [formatMessage],
+  );
+  return handleOfflineSubmit;
+}

package/src/Form/hooks/useSaveButtonPosition.ts

@@ -0,0 +1,52 @@
+import { Platform } from "react-native";
+import { useScreenInformation } from "./useScreenInformation";
+import { tokens } from "../../utils/design";
+
+interface UseSaveButtonPositionReturn {
+  saveButtonPosition: "sticky" | "inline";
+}
+
+interface UseSaveButtonPositionParams {
+  formContentHeight: number;
+  isBottomSheetOpen: boolean;
+  showStickySaveButton: boolean;
+  keyboardHeight: number;
+  keyboardScreenY: number;
+}
+
+export function useSaveButtonPosition({
+  formContentHeight,
+  isBottomSheetOpen,
+  showStickySaveButton,
+  keyboardHeight,
+  keyboardScreenY,
+}: UseSaveButtonPositionParams): UseSaveButtonPositionReturn {
+  const { headerHeight } = useScreenInformation();
+
+  if (showStickySaveButton) {
+    return {
+      saveButtonPosition: "sticky",
+    };
+  }
+
+  if (Platform.OS === "android" || isBottomSheetOpen) {
+    return {
+      saveButtonPosition: "inline",
+    };
+  }
+
+  const isKeyboardOpen = Boolean(keyboardHeight);
+
+  // tokens["space-large"] acts like a safe space below the form to avoid
+  // rendering the sticky button above the form elements.
+  const calculatedFormContentHeight =
+    formContentHeight + headerHeight + tokens["space-large"];
+
+  const isKeyboardOverForm = calculatedFormContentHeight > keyboardScreenY;
+
+  const showInlineSaveButton = isKeyboardOpen && isKeyboardOverForm;
+
+  return {
+    saveButtonPosition: showInlineSaveButton ? "inline" : "sticky",
+  };
+}

package/src/Form/hooks/useScreenInformation.ts

@@ -0,0 +1,25 @@
+import { useWindowDimensions } from "react-native";
+import { EdgeInsets, useSafeAreaInsets } from "react-native-safe-area-context";
+import { KEYBOARD_TOP_PADDING_AUTO_SCROLL } from "../constants";
+import { useAtlantisFormContext } from "../context";
+
+interface UseScreenInformation {
+  readonly windowHeight: number;
+  readonly headerHeight: number;
+  readonly insets: EdgeInsets;
+}
+
+export function useScreenInformation(): UseScreenInformation {
+  const { headerHeight } = useAtlantisFormContext();
+  const windowHeight = useWindowDimensions().height;
+  const headerHeightWithPadding =
+    headerHeight + KEYBOARD_TOP_PADDING_AUTO_SCROLL;
+
+  const insets = useSafeAreaInsets();
+
+  return {
+    windowHeight,
+    headerHeight: headerHeightWithPadding,
+    insets,
+  } as const;
+}

package/src/Form/hooks/useScrollToError/index.ts

@@ -0,0 +1 @@
+export * from "./useScrollToError";

package/src/Form/hooks/useScrollToError/useScrollToError.test.tsx

@@ -0,0 +1,103 @@
+import { renderHook } from "@testing-library/react-hooks";
+import { useScrollToError } from "./useScrollToError";
+
+const mockFormState = {
+  isDirty: true,
+  dirtyFields: {},
+  isSubmitted: false,
+  isSubmitSuccessful: false,
+  submitCount: 0,
+  touchedFields: {},
+  isSubmitting: false,
+  isValidating: false,
+  isValid: true,
+  errors: {},
+};
+
+const mockScreenReaderEnabled = jest.fn().mockReturnValue(false);
+jest.mock("../../../hooks/useIsScreenReaderEnabled", () => ({
+  useIsScreenReaderEnabled: () => mockScreenReaderEnabled(),
+}));
+
+jest.mock("../../../ErrorMessageWrapper", () => ({
+  useErrorMessageContext: () => ({
+    elements: {
+      el: {
+        measure: jest.fn((_, callback) => callback()),
+        hasErrorMessage: true,
+      },
+    },
+    register: jest.fn(),
+    unregister: jest.fn(),
+  }),
+}));
+
+const handleScrollToPosition = jest.fn();
+const handleSetFocus = jest.fn();
+
+const initialProps = {
+  formState: mockFormState,
+  refNode: 1,
+  scrollToPosition: handleScrollToPosition,
+  setFocus: handleSetFocus,
+};
+
+afterEach(() => {
+  handleScrollToPosition.mockClear();
+  handleSetFocus.mockClear();
+});
+
+describe("useScrollToError", () => {
+  it("should do nothing if everything is valid", () => {
+    renderHook(useScrollToError, { initialProps });
+
+    expect(handleSetFocus).not.toHaveBeenCalled();
+    expect(handleScrollToPosition).not.toHaveBeenCalled();
+  });
+
+  it("should focus with RHF if it can", () => {
+    const { rerender } = renderHook(useScrollToError, { initialProps });
+    rerender({
+      ...initialProps,
+      formState: { ...mockFormState, isValid: false, submitCount: 1 },
+    });
+
+    expect(handleSetFocus).toHaveBeenCalled();
+    expect(handleScrollToPosition).not.toHaveBeenCalled();
+  });
+
+  it("should manually scroll", () => {
+    // @ts-expect-error - making this fail when it gets called since you can't
+    // call undefined as a function. This mimic's RHF not being able to focus on
+    // non-input fields
+    const failedSetFocus = jest.fn(() => failingFn());
+    const manualScrollProps = { ...initialProps, setFocus: failedSetFocus };
+
+    const { rerender } = renderHook(useScrollToError, {
+      initialProps: manualScrollProps,
+    });
+    rerender({
+      ...manualScrollProps,
+      formState: { ...mockFormState, isValid: false, submitCount: 1 },
+    });
+
+    expect(failedSetFocus).toHaveBeenCalled();
+    expect(failedSetFocus).toThrow();
+    expect(handleScrollToPosition).toHaveBeenCalled();
+  });
+
+  describe("With screen readers", () => {
+    it("should not fire the setFocus", () => {
+      mockScreenReaderEnabled.mockReturnValue(true);
+
+      const { rerender } = renderHook(useScrollToError, { initialProps });
+      rerender({
+        ...initialProps,
+        formState: { ...mockFormState, isValid: false, submitCount: 1 },
+      });
+
+      expect(handleSetFocus).not.toHaveBeenCalled();
+      expect(handleScrollToPosition).toHaveBeenCalled();
+    });
+  });
+});

package/src/Form/hooks/useScrollToError/useScrollToError.ts

@@ -0,0 +1,102 @@
+import { useCallback, useState } from "react";
+import { FieldValues, FormState, Path, UseFormSetFocus } from "react-hook-form";
+import { KeyboardAwareScrollView } from "react-native-keyboard-aware-scroll-view";
+import {
+  Keyboard,
+  MeasureInWindowOnSuccessCallback,
+  Platform,
+} from "react-native";
+import { useIsScreenReaderEnabled } from "../../../hooks/useIsScreenReaderEnabled";
+import { useErrorMessageContext } from "../../../ErrorMessageWrapper";
+
+interface UseScrollToErrorParams<T extends FieldValues> {
+  readonly formState: FormState<T>;
+  readonly refNode: number | null;
+  readonly setFocus: UseFormSetFocus<T>;
+  readonly scrollToPosition?: KeyboardAwareScrollView["scrollToPosition"];
+}
+
+export function useScrollToError<T extends FieldValues>({
+  formState: { errors, isValid, submitCount },
+  refNode,
+  setFocus,
+  scrollToPosition,
+}: UseScrollToErrorParams<T>): void {
+  const [submitCounter, setSubmitCounter] = useState(submitCount);
+  const isScreenReaderEnabled = useIsScreenReaderEnabled();
+  const manuallyScrollToElement = useManuallyScrollToElement(
+    handleScroll,
+    refNode,
+  );
+
+  // Determine if the form has been submitted by checking if the submit count
+  // went up.
+  const hasBeenSubmitted = submitCounter < submitCount;
+  if (!hasBeenSubmitted) return;
+  if (isScreenReaderEnabled) {
+    manuallyScrollToElement();
+    Keyboard.dismiss();
+  } else {
+    defaultAutoScroll();
+  }
+
+  setSubmitCounter(submitCount);
+
+  function defaultAutoScroll() {
+    if (isValid) return;
+    try {
+      focusInputWithRHF(errors, setFocus);
+    } catch {
+      manuallyScrollToElement();
+    }
+  }
+
+  function handleScroll(
+    ...[x, y]: Parameters<MeasureInWindowOnSuccessCallback>
+  ) {
+    /**
+     * Disable scroll animation on android when screen reader is active since it
+     * can't accessibility-focus on an offscreen component.
+     */
+    const isAndroidWithScreenReader =
+      isScreenReaderEnabled && Platform.OS === "android";
+    const shouldAnimateScroll = !isAndroidWithScreenReader;
+
+    scrollToPosition?.(x, y, shouldAnimateScroll);
+  }
+}
+
+function focusInputWithRHF<T extends FieldValues>(
+  errors: FormState<T>["errors"],
+  setFocus: UseFormSetFocus<T>,
+) {
+  const errorMessages = Object.keys(errors);
+  setFocus(errorMessages[0] as Path<T>);
+}
+
+/**
+ * Manually scroll to the element by checking which elements has an error from
+ * the Error Message Context
+ */
+function useManuallyScrollToElement(
+  callback: MeasureInWindowOnSuccessCallback,
+  refNode: number | null,
+) {
+  const { elements } = useErrorMessageContext();
+
+  return useCallback(() => {
+    const elementWithError = Object.keys(elements).find(
+      el => elements[el].hasErrorMessage,
+    );
+
+    if (elementWithError) {
+      const element = elements[elementWithError];
+      refNode && element.measure(refNode, callback, handleError);
+      element.accessibilityFocus();
+    }
+  }, [callback, elements, refNode]);
+}
+
+function handleError() {
+  return Error("Couldn't scroll to error");
+}

package/src/Form/index.ts

@@ -0,0 +1,13 @@
+export { Form } from "./Form";
+export { FormMessage } from "./components/FormMessage";
+export type {
+  FormBannerErrors,
+  FormBannerMessage,
+  FormErrors,
+  FormRef,
+  FormValues,
+  SecondaryActionProp,
+  ValidationRulesByFieldPath,
+} from "./types";
+export { FormSubmitErrorType, FormBannerMessageType } from "./types";
+export * from "./context";

package/src/Form/messages.ts

@@ -0,0 +1,33 @@
+import { defineMessages } from "react-intl";
+
+export const messages = defineMessages({
+  loadingA11YLabel: {
+    id: "loadingA11yLabel",
+    defaultMessage: "Loading",
+    description: "Accessibility label for the loading indicator",
+  },
+
+  dismissAlertButton: {
+    id: "dismiss",
+    defaultMessage: "Dismiss",
+    description: "The label for the button to dismiss the alert ",
+  },
+
+  retryAlertButton: {
+    id: "retry",
+    defaultMessage: "Try Again",
+    description: "The label for the alert button to try action again",
+  },
+
+  unavailableNetworkTitle: {
+    id: "unavailableNetworkTitle",
+    defaultMessage: "Network unavailable",
+    description: "The title for alert about network unavailable",
+  },
+
+  unavailableNetworkMessage: {
+    id: "unavailableNetworkMessage",
+    defaultMessage: "Check your internet connection and try again later.",
+    description: "The message for alert about network unavailable",
+  },
+});