@jobber/components-native 0.38.0 → 0.40.0

package/src/Form/Form.tsx

@@ -0,0 +1,296 @@
+import React, { useState } from "react";
+import { FieldValues, FormProvider } from "react-hook-form";
+import { KeyboardAwareScrollView } from "react-native-keyboard-aware-scroll-view";
+import {
+  Keyboard,
+  LayoutChangeEvent,
+  Platform,
+  View,
+  findNodeHandle,
+} from "react-native";
+import { styles } from "./Form.style";
+import { FormErrorBanner } from "./components/FormErrorBanner";
+import { KEYBOARD_SAVE_BUTTON_DISTANCE } from "./constants";
+import { FormMessageBanner } from "./components/FormMessageBanner";
+import {
+  FormErrors,
+  FormProps,
+  FormSubmitErrorType,
+  FormValues,
+  InternalFormProps,
+} from "./types";
+import { FormMask } from "./components/FormMask";
+import { useInternalForm } from "./hooks/useInternalForm";
+import { useFormViewRefs } from "./hooks/useFormViewRefs";
+import { useScreenInformation } from "./hooks/useScreenInformation";
+import { FormMessage } from "./components/FormMessage";
+import { FormBody, useBottomPadding } from "./components/FormBody";
+import { useOfflineHandler } from "./hooks/useOfflineHandler";
+import { useScrollToError } from "./hooks/useScrollToError";
+import { FormSaveButton } from "./components/FormSaveButton";
+import { useSaveButtonPosition } from "./hooks/useSaveButtonPosition";
+import { FormCache } from "./components/FormCache/FormCache";
+import { InputAccessoriesProvider } from "../InputText";
+import { tokens } from "../utils/design";
+import { ErrorMessageProvider } from "../ErrorMessageWrapper";
+
+export function Form<T extends FieldValues, S>({
+  initialLoading,
+  ...rest
+}: FormProps<T, S>): JSX.Element {
+  const child = initialLoading ? <FormMask /> : <InternalForm {...rest} />;
+  return (
+    <InputAccessoriesProvider>
+      <ErrorMessageProvider>{child}</ErrorMessageProvider>
+    </InputAccessoriesProvider>
+  );
+}
+
+// eslint-disable-next-line max-statements
+function InternalForm<T extends FieldValues, S>({
+  children,
+  onBeforeSubmit,
+  onSubmit,
+  onSubmitError,
+  onSubmitSuccess,
+  bannerErrors,
+  bannerMessages,
+  initialValues,
+  mode = "onTouched",
+  reValidateMode = "onChange",
+  formRef,
+  saveButtonLabel,
+  renderStickySection,
+  localCacheKey,
+  localCacheExclude,
+  localCacheId,
+  secondaryActions,
+  saveButtonOffset,
+  showStickySaveButton = false,
+  renderFooter,
+}: InternalFormProps<T, S>) {
+  const { scrollViewRef, bottomViewRef, scrollToTop } = useFormViewRefs();
+  const [saveButtonHeight, setSaveButtonHeight] = useState(0);
+  const [messageBannerHeight, setMessageBannerHeight] = useState(0);
+  const {
+    formMethods,
+    handleSubmit,
+    isSubmitting,
+    removeListenerRef,
+    setLocalCache,
+  } = useInternalForm<T, S>({
+    mode,
+    reValidateMode,
+    initialValues,
+    formRef,
+    localCacheKey,
+    localCacheExclude,
+    localCacheId,
+    scrollViewRef,
+    saveButtonHeight,
+    messageBannerHeight,
+  });
+  const { windowHeight, headerHeight } = useScreenInformation();
+  const [keyboardHeight, setKeyboardHeight] = useState(0);
+  const [keyboardScreenY, setKeyboardScreenY] = useState(0);
+  const [formContentHeight, setFormContentHeight] = useState(0);
+  const [isBottomSheetOpen, setIsBottomSheetOpen] = useState(false);
+  const paddingBottom = useBottomPadding();
+
+  const { saveButtonPosition } = useSaveButtonPosition({
+    formContentHeight,
+    isBottomSheetOpen,
+    showStickySaveButton,
+    keyboardHeight,
+    keyboardScreenY,
+  });
+
+  const [isSecondaryActionLoading, setIsSecondaryActionLoading] =
+    useState<boolean>(false);
+
+  const extraViewHeight = paddingBottom + KEYBOARD_SAVE_BUTTON_DISTANCE;
+  const calculatedKeyboardHeight = keyboardHeight - extraViewHeight;
+
+  useScrollToError({
+    formState: formMethods.formState,
+    refNode: findNodeHandle(scrollViewRef.current),
+    setFocus: formMethods.setFocus,
+    scrollToPosition: scrollViewRef.current?.scrollToPosition,
+  });
+
+  const handleOfflineSubmit = useOfflineHandler();
+
+  const keyboardProps = Platform.select({
+    ios: {
+      onKeyboardWillHide: handleKeyboardHide,
+      onKeyboardWillShow: handleKeyboardShow,
+    },
+    android: {
+      onKeyboardDidHide: handleKeyboardHide,
+      onKeyboardDidShow: handleKeyboardShow,
+    },
+  });
+
+  const onLayout = (event: LayoutChangeEvent) => {
+    setMessageBannerHeight(event.nativeEvent.layout.height);
+  };
+
+  return (
+    <FormProvider {...formMethods}>
+      <>
+        {(isSubmitting || isSecondaryActionLoading) && <FormMask />}
+
+        {/* FormCache isolates watching entire form value changes to only this component */}
+        <FormCache
+          localCacheKey={localCacheKey}
+          localCacheExclude={localCacheExclude}
+          setLocalCache={setLocalCache}
+        />
+
+        <FormBody
+          keyboardHeight={calculateSaveButtonOffset()}
+          submit={handleSubmit(internalSubmit)}
+          isFormSubmitting={isSubmitting}
+          saveButtonLabel={saveButtonLabel}
+          shouldRenderActionBar={saveButtonPosition === "sticky"}
+          renderStickySection={renderStickySection}
+          secondaryActions={secondaryActions}
+          setSecondaryActionLoading={setIsSecondaryActionLoading}
+          setSaveButtonHeight={setSaveButtonHeight}
+          saveButtonOffset={saveButtonOffset}
+        >
+          <KeyboardAwareScrollView
+            enableResetScrollToCoords={false}
+            enableAutomaticScroll={true}
+            keyboardOpeningTime={
+              Platform.OS === "ios" ? tokens["timing-slowest"] : 0
+            }
+            keyboardShouldPersistTaps={"handled"}
+            ref={scrollViewRef}
+            {...keyboardProps}
+            extraHeight={headerHeight}
+            contentContainerStyle={
+              !keyboardHeight && styles.scrollContentContainer
+            }
+          >
+            <View
+              onLayout={({ nativeEvent }) => {
+                setFormContentHeight(nativeEvent.layout.height);
+              }}
+            >
+              <View onLayout={onLayout}>
+                <FormMessageBanner bannerMessages={bannerMessages} />
+                <FormErrorBanner
+                  networkError={bannerErrors?.networkError}
+                  bannerError={bannerErrors?.bannerError}
+                />
+              </View>
+              <View style={styles.formChildContainer}>
+                <>
+                  <View style={styles.formContent}>{children}</View>
+                  {saveButtonPosition === "inline" && (
+                    <View style={styles.fixedSaveButton}>
+                      {renderStickySection ? (
+                        renderStickySection(
+                          handleSubmit(internalSubmit),
+                          saveButtonLabel,
+                          isSubmitting,
+                        )
+                      ) : (
+                        <FormSaveButton
+                          primaryAction={handleSubmit(internalSubmit)}
+                          label={saveButtonLabel}
+                          loading={isSubmitting}
+                          secondaryActions={secondaryActions}
+                          setSecondaryActionLoading={
+                            setIsSecondaryActionLoading
+                          }
+                          onOpenBottomSheet={() => setIsBottomSheetOpen(true)}
+                          onCloseBottomSheet={() => setIsBottomSheetOpen(false)}
+                        />
+                      )}
+                    </View>
+                  )}
+                  {renderFooter}
+                </>
+              </View>
+            </View>
+            <View style={styles.safeArea} ref={bottomViewRef} />
+          </KeyboardAwareScrollView>
+        </FormBody>
+      </>
+      <FormMessage />
+    </FormProvider>
+  );
+
+  function handleKeyboardShow(frames: Record<string, any>) {
+    setKeyboardScreenY(frames.endCoordinates.screenY);
+    setKeyboardHeight(frames.endCoordinates.height);
+  }
+
+  function handleKeyboardHide() {
+    bottomViewRef?.current?.measureInWindow(
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      (_x: number, y: number, _width: number, _height: number) => {
+        // This fixes extra whitespace below the form if it was scrolled down while the keyboard was open
+        // i.e. a View below the form is higher than the bottom of the window
+        if (y < windowHeight) {
+          scrollViewRef?.current?.scrollToEnd();
+        }
+      },
+    );
+    setKeyboardHeight(0);
+    setKeyboardScreenY(0);
+  }
+
+  async function internalSubmit(data: FormValues<T>) {
+    let performSubmit = true;
+    if (onBeforeSubmit) {
+      performSubmit = await onBeforeSubmit(data);
+    }
+
+    if (performSubmit) {
+      Keyboard.dismiss();
+
+      return onSubmit(data)
+        .then((result: S) => {
+          removeListenerRef.current?.();
+          onSubmitSuccess(result);
+        })
+        .catch(handleSubmitCatch);
+    }
+  }
+
+  function handleSubmitCatch(error: FormErrors) {
+    // Scroll to top of form to see error
+    scrollToTop();
+    onSubmitError(error);
+
+    if (error?.errorType === FormSubmitErrorType.NetworkError) {
+      // @ts-expect-error We are making the form submission fail so that we can
+      // prevent the isSubmitSuccess to be true
+      formMethods.setError("offline", "Error saving form.");
+
+      handleOfflineSubmit(handleRetry, clearFormErrors)();
+    }
+  }
+
+  function clearFormErrors() {
+    // @ts-expect-error  We are clearing the error that we previously set
+    // when the form had no internet connection
+    formMethods.clearErrors("offline");
+  }
+  function handleRetry() {
+    clearFormErrors();
+    return handleSubmit(internalSubmit)();
+  }
+
+  function calculateSaveButtonOffset() {
+    if (saveButtonOffset) {
+      // Included the space-base because it's the padding of the FormActionBar
+      return calculatedKeyboardHeight - saveButtonOffset + tokens["space-base"];
+    }
+
+    return calculatedKeyboardHeight;
+  }
+}

package/src/Form/components/FormActionBar/FormActionBar.style.ts

@@ -0,0 +1,11 @@
+import { StyleSheet } from "react-native";
+import { tokens } from "../../../utils/design";
+
+export const styles = StyleSheet.create({
+  saveButton: {
+    padding: tokens["space-base"],
+    backgroundColor: tokens["color-surface"],
+    width: "100%",
+    ...tokens["shadow-high"],
+  },
+});

package/src/Form/components/FormActionBar/FormActionBar.tsx

@@ -0,0 +1,63 @@
+import React from "react";
+import { LayoutChangeEvent, StyleSheet, View } from "react-native";
+import Reanimated from "react-native-reanimated";
+import { styles } from "./FormActionBar.style";
+import { SecondaryActionProp } from "../../types";
+import { FormSaveButton } from "../FormSaveButton";
+
+const ReanimatedView = Reanimated.createAnimatedComponent(View);
+
+export interface FormActionBarProps {
+  readonly keyboardHeight: number;
+  readonly isFormSubmitting: boolean;
+  readonly saveButtonLabel?: string;
+  readonly submit: () => Promise<void> | void;
+  readonly setSaveButtonHeight?: (height: number) => void;
+  readonly renderStickySection?: (
+    onSubmit: () => void,
+    label: string | undefined,
+    isSubmitting: boolean,
+  ) => JSX.Element;
+  readonly secondaryActions?: SecondaryActionProp[];
+  readonly setSecondaryActionLoading?: (bool: boolean) => void;
+}
+
+export function FormActionBar({
+  keyboardHeight,
+  submit,
+  isFormSubmitting,
+  saveButtonLabel,
+  renderStickySection,
+  setSaveButtonHeight,
+  secondaryActions,
+  setSecondaryActionLoading,
+}: FormActionBarProps): JSX.Element {
+  const buttonStyle = StyleSheet.flatten([
+    styles.saveButton,
+    {
+      position: keyboardHeight > 0 ? "absolute" : "relative",
+      bottom: 0,
+    },
+  ]);
+
+  const onLayout = (event: LayoutChangeEvent) => {
+    setSaveButtonHeight && setSaveButtonHeight(event.nativeEvent.layout.height);
+  };
+
+  return (
+    //@ts-expect-error tsc-ci
+    <ReanimatedView style={buttonStyle} onLayout={onLayout}>
+      {renderStickySection ? (
+        renderStickySection(submit, saveButtonLabel, isFormSubmitting)
+      ) : (
+        <FormSaveButton
+          setSecondaryActionLoading={setSecondaryActionLoading}
+          primaryAction={submit}
+          loading={isFormSubmitting}
+          label={saveButtonLabel}
+          secondaryActions={secondaryActions}
+        />
+      )}
+    </ReanimatedView>
+  );
+}

package/src/Form/components/FormActionBar/index.ts

@@ -0,0 +1,2 @@
+export { FormActionBar } from "./FormActionBar";
+export type { FormActionBarProps } from "./FormActionBar";

package/src/Form/components/FormBody/FormBody.style.ts

@@ -0,0 +1,27 @@
+import { StyleSheet } from "react-native";
+import { tokens } from "../../../utils/design";
+
+export const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    flexGrow: 1,
+    width: "100%",
+  },
+  safeArea: {
+    backgroundColor: tokens["color-surface"],
+  },
+  scrollContentContainer: {
+    flexGrow: 1,
+  },
+  scrollView: {
+    flexGrow: 1,
+  },
+  formChildContainer: {
+    flexGrow: 1,
+    justifyContent: "flex-start",
+  },
+  activityIndicator: {
+    marginVertical: tokens["space-base"],
+    flex: 1,
+  },
+});

package/src/Form/components/FormBody/FormBody.tsx

@@ -0,0 +1,62 @@
+import React, { useMemo } from "react";
+import { View } from "react-native";
+import { styles } from "./FormBody.style";
+import { useScreenInformation } from "../../hooks/useScreenInformation";
+import { FormActionBar, FormActionBarProps } from "../FormActionBar";
+import { tokens } from "../../../utils/design";
+
+interface FormBodyProps extends FormActionBarProps {
+  children: JSX.Element;
+  shouldRenderActionBar?: boolean;
+  saveButtonOffset?: number;
+}
+
+export function FormBody({
+  isFormSubmitting,
+  submit,
+  keyboardHeight,
+  children,
+  saveButtonLabel,
+  renderStickySection,
+  shouldRenderActionBar = true,
+  secondaryActions,
+  setSecondaryActionLoading,
+  setSaveButtonHeight,
+  saveButtonOffset,
+}: FormBodyProps): JSX.Element {
+  const paddingBottom = useBottomPadding();
+  const fullViewPadding = useMemo(() => ({ paddingBottom }), [paddingBottom]);
+
+  return (
+    <>
+      <View style={[styles.container]}>
+        {children}
+        {shouldRenderActionBar && (
+          <FormActionBar
+            setSecondaryActionLoading={setSecondaryActionLoading}
+            keyboardHeight={keyboardHeight}
+            submit={submit}
+            isFormSubmitting={isFormSubmitting}
+            saveButtonLabel={saveButtonLabel}
+            renderStickySection={renderStickySection}
+            secondaryActions={secondaryActions}
+            setSaveButtonHeight={setSaveButtonHeight}
+          />
+        )}
+      </View>
+
+      {shouldRenderActionBar && !saveButtonOffset && (
+        <View
+          style={[fullViewPadding, styles.safeArea]}
+          testID="ATL-FormSafeArea"
+        />
+      )}
+    </>
+  );
+}
+
+export function useBottomPadding(): number {
+  const { insets } = useScreenInformation();
+  const extraBottomSpace = insets.bottom - tokens["space-base"];
+  return extraBottomSpace >= 0 ? extraBottomSpace : 0;
+}

package/src/Form/components/FormBody/index.ts

@@ -0,0 +1 @@
+export { FormBody, useBottomPadding } from "./FormBody";

package/src/Form/components/FormCache/FormCache.tsx

@@ -0,0 +1,50 @@
+import React, { useEffect, useMemo } from "react";
+import { FieldValues, useFormContext, useWatch } from "react-hook-form";
+import omit from "lodash/omit";
+
+interface FormCacheProps<T extends FieldValues> {
+  localCacheId?: string | string[];
+  localCacheKey?: string;
+  localCacheExclude?: string[];
+  setLocalCache: (data: T) => void;
+}
+export function FormCache<T extends FieldValues>({
+  localCacheExclude,
+  localCacheKey,
+  setLocalCache,
+}: FormCacheProps<T>): JSX.Element {
+  const { control, formState } = useFormContext<T>();
+  const { isDirty } = formState;
+
+  const formData = useWatch<T>({ control });
+  const shouldExclude = useMemo(() => {
+    return Array.isArray(localCacheExclude) && localCacheExclude.length > 0;
+  }, [localCacheExclude]);
+
+  useEffect(() => {
+    !localCacheKey &&
+      console.log(
+        "No `localCacheKey` specified on Form. Local copy of form data is now disabled.",
+      );
+  }, [localCacheKey]);
+
+  /**
+   * Automatically save form data locally
+   */
+  useEffect(() => {
+    if (!isDirty) return;
+
+    if (shouldExclude) {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore The type below is not working. It seems to be an issue with react-hook-form
+      // https://github.com/react-hook-form/react-hook-form/issues/2978
+      setLocalCache(omit(formData, localCacheExclude));
+    } else {
+      // @ts-expect-error Typescript thinks that the FieldValues defined in useWatch is different
+      // from the one in useFormContext
+      setLocalCache(formData);
+    }
+  }, [formData, isDirty, localCacheExclude, setLocalCache, shouldExclude]);
+
+  return <></>;
+}

package/src/Form/components/FormErrorBanner/FormErrorBanner.test.tsx

@@ -0,0 +1,124 @@
+import React from "react";
+import { cleanup, render } from "@testing-library/react-native";
+import { useIntl } from "react-intl";
+import { FormErrorBanner } from "./FormErrorBanner";
+import { messages as formErrorBannerMessages } from "./messages";
+import { defaultValues as contextDefaultValue } from "../../../AtlantisContext";
+import * as atlantisContext from "../../../AtlantisContext/AtlantisContext";
+
+describe("FormErrorBanner", () => {
+  const atlantisContextSpy = jest.spyOn(atlantisContext, "useAtlantisContext");
+
+  beforeEach(() => {
+    atlantisContextSpy.mockReturnValue({
+      ...contextDefaultValue,
+      isOnline: true,
+    });
+  });
+
+  const { formatMessage } = useIntl();
+  const networkError = new Error();
+  const userError = {
+    title: "My error",
+    messages: ["userError1", "userError2"],
+  };
+  const validationErrors = [
+    "This is the first validation error",
+    "This is the second validation error",
+  ];
+
+  it("should render Offline banner when offline", () => {
+    atlantisContextSpy.mockReturnValue({
+      ...contextDefaultValue,
+      isOnline: false,
+    });
+    const { getByText, queryByText } = render(
+      <FormErrorBanner
+        // @ts-expect-error tsc-ci
+        networkError={networkError}
+        bannerError={userError}
+        validationErrors={validationErrors}
+        actionLabel="Action"
+      />,
+    );
+
+    // Show: Offline Message
+    expect(
+      getByText(formatMessage(formErrorBannerMessages.offlineError)),
+    ).toBeDefined();
+
+    // Hide: Network Error, User Error, Validation Error
+    expect(
+      queryByText(formatMessage(formErrorBannerMessages.networkError)),
+    ).toBeNull();
+
+    expect(queryByText(userError.title)).toBeNull();
+  });
+
+  it("should render network error banner when online and network errors exist", () => {
+    const { getByText, queryByText } = render(
+      <FormErrorBanner
+        // @ts-expect-error tsc-ci
+        networkError={networkError}
+        bannerError={userError}
+        actionLabel="action"
+      />,
+    );
+
+    // Show: Network Error
+    expect(
+      getByText(formatMessage(formErrorBannerMessages.networkError)),
+    ).toBeDefined();
+
+    // Hide: Offline Message, User Error, Validation Error
+    expect(
+      queryByText(formatMessage(formErrorBannerMessages.offlineError)),
+    ).toBeNull();
+
+    expect(queryByText(userError.title)).toBeNull();
+  });
+
+  it("should render user error banner when online and user errors exist", () => {
+    const { getByText, queryByText } = render(
+      <FormErrorBanner bannerError={userError} />,
+    );
+
+    // Show: User Error
+    expect(getByText(userError.title)).toBeDefined();
+    expect(getByText(userError.messages[0])).toBeDefined();
+    expect(getByText(userError.messages[1])).toBeDefined();
+
+    // Hide: Offline Message, Network Error, Validation Error
+    expect(
+      queryByText(formatMessage(formErrorBannerMessages.offlineError)),
+    ).toBeNull();
+
+    expect(
+      queryByText(formatMessage(formErrorBannerMessages.networkError)),
+    ).toBeNull();
+  });
+
+  it("should render user error banner with just title when online", () => {
+    const userErrorJustTitle = {
+      title: "My error",
+    };
+    const { getByText, queryByText } = render(
+      <FormErrorBanner bannerError={userErrorJustTitle} />,
+    );
+
+    // Show: User Error
+    expect(getByText(userErrorJustTitle.title)).toBeDefined();
+
+    // Hide: Offline Message, Network Error, Validation Error
+    expect(
+      queryByText(formatMessage(formErrorBannerMessages.offlineError)),
+    ).toBeNull();
+
+    expect(
+      queryByText(formatMessage(formErrorBannerMessages.networkError)),
+    ).toBeNull();
+  });
+});
+
+afterEach(jest.clearAllMocks);
+afterEach(cleanup);

package/src/Form/components/FormErrorBanner/FormErrorBanner.tsx

@@ -0,0 +1,34 @@
+import React from "react";
+import { useIntl } from "react-intl";
+import { messages } from "./messages";
+import { FormBannerErrors } from "../../types";
+import { useAtlantisContext } from "../../../AtlantisContext";
+import { Banner } from "../../../Banner";
+
+export function FormErrorBanner({
+  networkError,
+  bannerError,
+}: FormBannerErrors): JSX.Element {
+  const { formatMessage } = useIntl();
+  const { isOnline } = useAtlantisContext();
+
+  if (!isOnline) {
+    return (
+      <Banner text={formatMessage(messages.offlineError)} type={"error"} />
+    );
+  } else if (networkError) {
+    return (
+      <Banner text={formatMessage(messages.networkError)} type={"error"} />
+    );
+  } else if (bannerError) {
+    return (
+      <Banner
+        text={bannerError.title}
+        details={bannerError.messages}
+        type={"error"}
+      />
+    );
+  } else {
+    return <></>;
+  }
+}

package/src/Form/components/FormErrorBanner/index.ts

@@ -0,0 +1 @@
+export { FormErrorBanner } from "./FormErrorBanner";

package/src/Form/components/FormErrorBanner/messages.ts

@@ -0,0 +1,14 @@
+import { defineMessages } from "react-intl";
+
+export const messages = defineMessages({
+  networkError: {
+    id: "networkError",
+    defaultMessage: "Could not save changes",
+    description: "Displayed when a general server error occurs during save",
+  },
+  offlineError: {
+    id: "offlineError",
+    defaultMessage: "Currently offline. Check your internet connection.",
+    description: "Error message to be shown when the app is offline",
+  },
+});