@jobber/hooks 2.0.3-dar.45 → 2.0.3-dar.47

package/src/useCollectionQuery/useCollectionQuery.ts

@@ -0,0 +1,359 @@
+import {
+  ApolloError,
+  DocumentNode,
+  QueryHookOptions,
+  SubscribeToMoreOptions,
+  useQuery,
+} from "@apollo/client";
+import { cloneDeep } from "lodash";
+import { useCallback, useEffect, useState } from "react";
+import { config } from "@jobber/formatters";
+import { Node, uniqueNodes } from "./uniqueNodes";
+import { Edge, createEdge, uniqueEdges } from "./uniqueEdges";
+import { useIsMounted } from "../useIsMounted";
+
+interface UseCollectionQueryArguments<TQuery, TSubscription> {
+  /**
+   * The graphQL query that fetches the collection
+   */
+  query: DocumentNode;
+
+  /**
+   * A list of options for us to pass into the apollo `useQuery` hook
+   */
+  queryOptions?: QueryHookOptions<TQuery>;
+
+  /**
+   * A function that returns the location where the {@link Collection} is located.
+   *
+   * The collection is the part of the result that needs to be paginated.
+   */
+  getCollectionByPath: GetCollectionByPathFunction<TQuery>;
+
+  /**
+   *  A list of subscription options if you want to create a GraphQL
+   *  subscription to listen for more content.
+   */
+  subscription?: ListSubscription<TSubscription>;
+}
+
+interface ListSubscription<TSubscription> {
+  /**
+   * The graphQL subscription that listens for more data. This query should
+   * return a single Node that matches the data structure in
+   * `getCollectionByPath<TQuery>(...).edges.node` and
+   * `getCollectionByPath<TQuery>(...).nodes
+   */
+  document: DocumentNode;
+
+  /**
+   * A list of variables to pass into the apollo `subscribeToMore` function.
+   */
+  options?: Pick<SubscribeToMoreOptions<TSubscription>, "variables">;
+
+  /**
+   * A function that returns the location where the `Node` is located on the
+   * `TSubscription` object.
+   *
+   * It should return a single Node that matches the data structure in
+   * `getCollectionByPath<TQuery>(...).edges.node` and
+   * `getCollectionByPath<TQuery>(...).nodes
+   */
+  getNodeByPath: GetNodeByPath<TSubscription>;
+}
+
+interface Collection {
+  edges?: Edge[];
+  nodes?: Node[];
+  pageInfo: {
+    endCursor?: string | undefined;
+    hasNextPage: boolean;
+    [otherProperties: string]: unknown;
+  };
+  totalCount?: number;
+  [otherProperties: string]: unknown;
+}
+
+interface CollectionQueryResult<TQuery> {
+  data: TQuery | undefined;
+  error: ApolloError | undefined;
+  loadingRefresh: boolean;
+  loadingNextPage: boolean;
+  loadingInitialContent: boolean;
+  refresh(): void;
+  nextPage(): void;
+}
+
+type GetCollectionByPathFunction<TQuery> = (
+  data: TQuery | undefined,
+) => Collection | undefined;
+
+type GetNodeByPath<TSubscription> = (
+  data: TSubscription | undefined,
+) => Node | undefined;
+
+export function useCollectionQuery<TQuery, TSubscription = undefined>({
+  query,
+  queryOptions,
+  getCollectionByPath,
+  subscription,
+}: UseCollectionQueryArguments<
+  TQuery,
+  TSubscription
+>): CollectionQueryResult<TQuery> {
+  const { data, loading, refetch, error, fetchMore, subscribeToMore } =
+    useQuery<TQuery>(query, queryOptions);
+
+  const isMounted = useIsMounted();
+  const [loadingRefresh, setLoadingRefresh] = useState<boolean>(false);
+  const [loadingNextPage, setLoadingNextPage] = useState<boolean>(false);
+  const loadingInitialContent = loading && !loadingRefresh && !loadingNextPage;
+  const isSearching = !!queryOptions?.variables?.searchTerm;
+
+  const refresh = useCallback(() => {
+    if (loadingInitialContent || loadingRefresh) {
+      return;
+    }
+
+    setLoadingRefresh(true);
+
+    fetchMore({
+      // a workaround fix for the error described in this post
+      // https://github.com/apollographql/apollo-client/issues/7491#issuecomment-767985363
+      // These changes can be reverted once we can update to version 3.4
+      // (the current release candidate)
+      variables: {},
+      updateQuery: (prev, { fetchMoreResult }) => fetchMoreResult || prev,
+    })
+      .catch(err => config.errorNotifier("Refetch Error", err))
+      .finally(() => {
+        if (isMounted.current) {
+          setLoadingRefresh(false);
+        }
+      });
+  }, [
+    loadingInitialContent,
+    loadingRefresh,
+    setLoadingRefresh,
+    refetch,
+    isMounted,
+  ]);
+
+  const nextPage = useCallback(() => {
+    if (loadingInitialContent || loadingRefresh || loadingNextPage) {
+      return;
+    }
+
+    const pageInfo = getCollectionByPath(data)?.pageInfo;
+
+    if (!pageInfo || !pageInfo.hasNextPage) {
+      return;
+    }
+
+    setLoadingNextPage(true);
+
+    fetchMore({
+      variables: {
+        cursor: pageInfo.endCursor,
+      },
+      updateQuery: (prev, { fetchMoreResult }) =>
+        fetchMoreUpdateQueryHandler(prev, fetchMoreResult, getCollectionByPath),
+    })
+      .catch(err => config.errorNotifier("FetchMore Error", err))
+      .finally(() => {
+        if (isMounted.current) {
+          setLoadingNextPage(false);
+        }
+      });
+  }, [
+    data,
+    loadingInitialContent,
+    loadingRefresh,
+    fetchMore,
+    loadingNextPage,
+    setLoadingNextPage,
+    getCollectionByPath,
+    isMounted,
+  ]);
+
+  useEffect(
+    () => {
+      if (subscription == undefined) return;
+
+      const subscriptionOptions = subscription.options || {};
+
+      return subscribeToMore<TSubscription>({
+        ...subscriptionOptions,
+        document: subscription.document,
+        updateQuery: (prev, { subscriptionData }) =>
+          subscribeToMoreHandler(
+            isSearching,
+            prev,
+            getCollectionByPath,
+            subscriptionData?.data,
+            subscription.getNodeByPath,
+          ),
+        onError: err => config.errorNotifier("Subscribe to More Error", err),
+      });
+    },
+    // Disabling this linter so we can force this only run once. If we didn't
+    // do this we would need to ensure subscription, subscribeToMore, and getNodeByPath
+    // all use useCallback.
+    [queryOptions?.variables?.searchTerm],
+  );
+
+  return {
+    data,
+    error,
+    refresh,
+    loadingRefresh,
+    nextPage,
+    loadingNextPage,
+    loadingInitialContent,
+  };
+}
+
+/**
+ * The following method uses an `output` variable, and indirectly modifies it through the `outputCollection` variable.
+ * This type of indirect modification is prone to bugs, but I couldn't think of a better way to write this code.
+ *
+ * Here's what I was balancing:
+ * 1. We need to copy the structure of prev to ensure that when we're combining two objects, we're not losing properties
+ * 2. We need to extract a key from an unknown path that's given to us by getCollectionByPath and then we need to modify
+ *    that, and ensure that it's properly set on the cloned output object.
+ * 3. We want to keep the interface to this hook as simple and easy to use as possible
+ *
+ * The alternative approaches that were rejected:
+ * 1. We replace the getCollectionByPath with a keyPath string. (Eg. "data.conversation.message") and then we use lodash
+ *    `get` and `set` which should remove all the object manipulation. But, this approach loses us the type safety that
+ *    getCollectionByPath gives us
+ * 2. We could add a setCollection function to the list of arguments for this hook. This leaves us with type safety but
+ *    makes the `useCollectionQuery` interface more complicated by adding arguments
+ */
+function fetchMoreUpdateQueryHandler<TQuery>(
+  prev: TQuery,
+  fetchMoreResult: TQuery | undefined,
+  getCollectionByPath: GetCollectionByPathFunction<TQuery>,
+): TQuery {
+  const nextCollection = getCollectionByPath(fetchMoreResult);
+  const output = cloneDeep(prev);
+  const outputCollection = getCollectionByPath(output);
+
+  if (outputCollection === undefined || nextCollection === undefined) {
+    return output;
+  }
+
+  if (outputCollection.nodes && nextCollection.nodes) {
+    outputCollection.nodes = getUpdatedNodes(
+      outputCollection.nodes,
+      nextCollection.nodes,
+    );
+  }
+  if (outputCollection.edges && nextCollection.edges) {
+    outputCollection.edges = getUpdatedEdges(
+      outputCollection.edges,
+      nextCollection.edges,
+    );
+  }
+
+  Object.assign(outputCollection, {
+    pageInfo: cloneDeep(nextCollection.pageInfo),
+    ...getTotalCount(nextCollection.totalCount),
+  });
+
+  return output;
+}
+
+function subscribeToMoreHandler<TQuery, TSubscription>(
+  isSearching: boolean,
+  prev: TQuery,
+  getCollectionByPath: GetCollectionByPathFunction<TQuery>,
+  subscriptionData: TSubscription | undefined,
+  getNodeByPath: GetNodeByPath<TSubscription>,
+): TQuery {
+  const node = getNodeByPath(subscriptionData);
+  const output = cloneDeep(prev);
+  const outputCollection = getCollectionByPath(output);
+
+  if (outputCollection == undefined || node == undefined) return output;
+
+  if (isAlreadyUpdated(outputCollection, node) || isSearching) {
+    return prev;
+  }
+
+  if (outputCollection.nodes) {
+    outputCollection.nodes = getUpdatedNodes(
+      outputCollection.nodes,
+      [node],
+      false,
+    );
+  }
+  if (outputCollection.edges) {
+    outputCollection.edges = getUpdatedEdges(
+      outputCollection.edges,
+      [createEdge(node)],
+      false,
+    );
+  }
+
+  Object.assign(outputCollection, {
+    pageInfo: cloneDeep(outputCollection.pageInfo),
+    ...getTotalCount(outputCollection.totalCount, 1),
+  });
+
+  return output;
+}
+
+interface TotalCountReturn {
+  totalCount?: number;
+}
+
+function getTotalCount(
+  totalCount: number | undefined,
+  additionalCount = 0,
+): TotalCountReturn {
+  return totalCount !== undefined
+    ? { totalCount: totalCount + additionalCount }
+    : {};
+}
+
+export function isAlreadyUpdated(outputCollection: Collection, newNode: Node) {
+  let edgesAlreadyUpdated = true;
+  let nodesAlreadyUpdated = true;
+
+  if (outputCollection.edges) {
+    edgesAlreadyUpdated = outputCollection.edges.some(edge => {
+      return edge.node.id === newNode.id;
+    });
+  }
+
+  if (outputCollection.nodes) {
+    nodesAlreadyUpdated = outputCollection.nodes.some(node => {
+      return node.id === newNode.id;
+    });
+  }
+
+  return edgesAlreadyUpdated && nodesAlreadyUpdated;
+}
+
+function getUpdatedEdges(
+  prevEdges: Edge[],
+  nextEdges: Edge[],
+  appendToEnd = true,
+) {
+  const newEdges = appendToEnd
+    ? [...prevEdges, ...nextEdges]
+    : [...nextEdges, ...prevEdges];
+  return uniqueEdges(newEdges);
+}
+
+function getUpdatedNodes(
+  prevNodes: Node[],
+  nextNodes: Node[],
+  appendToEnd = true,
+) {
+  const newNodes = appendToEnd
+    ? [...prevNodes, ...nextNodes]
+    : [...nextNodes, ...prevNodes];
+  return uniqueNodes(newNodes);
+}

package/src/useFocusTrap/index.ts

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

package/src/useFocusTrap/useFocusTrap.stories.mdx

@@ -0,0 +1,49 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import { useState } from "react";
+import { Button } from "@jobber/components/Button";
+import { Content } from "@jobber/components/Content";
+import { Checkbox } from "@jobber/components/Checkbox";
+import { InputText } from "@jobber/components/InputText";
+import { Text } from "@jobber/components/Text";
+import * as hooks from ".";
+
+<Meta title="Hooks/useFocusTrap" />
+
+# UseFocusTrap
+
+Trap focus within a DOM node.
+
+Useful for building Modals, lightboxes, menus, bottom sheets, etc. The user will
+be able to navigate the component using `Tab` and `Shift+Tab`.
+
+```ts
+import { useFocusTrap } from "@jobber/hooks";
+```
+
+<Canvas>
+  <Story name="useFocusTrap">
+    {() => {
+      const [checked, setChecked] = useState(false);
+      const trapRef = hooks.useFocusTrap(checked);
+      return (
+        <>
+          <Checkbox
+            checked={checked}
+            onChange={setChecked}
+            label="Trap focus"
+          />
+          <div ref={trapRef} tabIndex={0}>
+            <Content>
+              {checked}
+              <InputText placeholder="First Name" name="firstName" />
+              <InputText placeholder="Last Name" name="lastName" />
+              <Button label="Submit Form" submit={true} />
+            </Content>
+          </div>
+        </>
+      );
+    }}
+  </Story>
+</Canvas>
+
+<ArgsTable of={hooks.useFocusTrap} />

package/src/useFocusTrap/useFocusTrap.test.tsx

@@ -0,0 +1,66 @@
+import React from "react";
+import { render } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useFocusTrap } from "./useFocusTrap";
+
+const targetId = "target";
+const firstFocusableChild = "first-element";
+const lastFocusableChild = "last-element";
+
+it("should focus on the ref target on mount", () => {
+  const { getByTestId } = render(<TestComponent />);
+  expect(getByTestId(targetId)).toHaveFocus();
+});
+
+it("should focus on the ref target when tabbing out of the last focusable element and ignore the tabindex'=-1'", () => {
+  const { getByTestId } = render(<TestComponent />);
+  getByTestId(lastFocusableChild).focus();
+  userEvent.tab();
+  expect(getByTestId(targetId)).toHaveFocus();
+});
+
+it("should focus on the first focusable element", () => {
+  const { getByTestId } = render(<TestComponent />);
+  userEvent.tab();
+  expect(getByTestId(firstFocusableChild)).toHaveFocus();
+});
+
+it("should focus on the last focusable element", () => {
+  const { getByTestId } = render(<TestComponent />);
+  userEvent.tab({ shift: true });
+  expect(getByTestId(lastFocusableChild)).toHaveFocus();
+});
+
+it("should not trap the tabbing and focus on the first child node", () => {
+  const { getByTestId } = render(<TestComponent trap={false} />);
+  userEvent.tab();
+  expect(getByTestId(targetId).previousElementSibling).toHaveFocus();
+});
+
+interface TestComponentProps {
+  readonly trap?: boolean;
+}
+
+function TestComponent({ trap = true }: TestComponentProps) {
+  const testRef = useFocusTrap<HTMLDivElement>(trap);
+
+  return (
+    <>
+      <input type="number" />
+
+      <div ref={testRef} data-testid={targetId} tabIndex={0}>
+        <button data-testid={firstFocusableChild}>Click me</button>
+        <a href="#"></a>
+        <input type="text" />
+        <select>
+          <option value="A"></option>
+        </select>
+        <textarea></textarea>
+        <span tabIndex={0} data-testId={lastFocusableChild}></span>
+        <span tabIndex={-1}></span>
+      </div>
+
+      <input type="calendar" />
+    </>
+  );
+}

package/src/useFocusTrap/useFocusTrap.ts

@@ -0,0 +1,64 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Traps the focus within the children of the ref element.
+ *
+ * @param active - Turns the focus trapping on or off. Also adds aria-hidden on the
+ * body but not the dialog.
+ *
+ * @returns ref
+ */
+export function useFocusTrap<T extends HTMLElement>(active: boolean) {
+  // There's an ongoing issue with useRef return type clashing with an element's
+  // ref prop type. TLDR: Use null because useRef doesn't expect undefined.
+  // https://github.com/DefinitelyTyped/DefinitelyTyped/issues/35572
+  const ref = useRef<T>(null);
+
+  function handleKeyDown(event: KeyboardEvent) {
+    if (!(active && ref.current) || event.key !== "Tab") {
+      return;
+    }
+
+    const { firstElement, lastElement } = getElements(ref.current);
+
+    if (event.shiftKey) {
+      if (document.activeElement === firstElement) {
+        lastElement.focus();
+        event.preventDefault();
+      }
+    } else {
+      if (document.activeElement === lastElement) {
+        firstElement.focus();
+        event.preventDefault();
+      }
+    }
+  }
+
+  useEffect(() => {
+    if (active) {
+      ref.current?.focus();
+      ref.current?.addEventListener("keydown", handleKeyDown);
+    }
+
+    return () => {
+      ref.current?.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [active]);
+
+  return ref;
+}
+
+function getElements<T extends HTMLElement>(ref: T) {
+  const focusables = [
+    "button",
+    "[href]",
+    "input",
+    "select",
+    "textarea",
+    '[tabindex]:not([tabindex="-1"])',
+  ];
+  const elements = ref.querySelectorAll<HTMLElement>(focusables.join(", "));
+  const firstElement = ref;
+  const lastElement = elements[elements.length - 1];
+  return { firstElement, lastElement };
+}

package/src/useFormState/index.ts

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

package/src/useFormState/useFormState.stories.mdx

@@ -0,0 +1,70 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import { Form } from "@jobber/components/Form";
+import { InputText } from "@jobber/components/InputText";
+import { Content } from "@jobber/components/Content";
+import { Button } from "@jobber/components/Button";
+import * as hooks from ".";
+
+<Meta title="Hooks/useFormState" />
+
+# UseFormState
+
+`useFormState` is an extremely simple hook that wraps the
+[useState()](https://reactjs.org/docs/hooks-state.html) hook and supplies some
+default values.
+
+`useFormState` should **only** only by used when using a
+[`<Form />`](../?path=/docs/components-form--form) component.
+
+```tsx
+import { useFormState } from "@jobber/hooks";
+```
+
+<Canvas>
+  <Story name="useFormState">
+    {() => {
+      const [formState, setFormState] = hooks.useFormState();
+      return (
+        <>
+          <Form
+            onSubmit={() => alert("submitted")}
+            onStateChange={setFormState}
+          >
+            <Content>
+              <InputText
+                placeholder="First Name"
+                name="firstName"
+                validations={{
+                  required: {
+                    value: true,
+                    message: "Tell us your name",
+                  },
+                  minLength: {
+                    value: 3,
+                    message: "Your name is too short.",
+                  },
+                }}
+              />
+              <InputText
+                placeholder="Last Name"
+                name="lastName"
+                validations={{
+                  required: {
+                    value: true,
+                    message: "Tell us your last name.",
+                  },
+                }}
+              />
+              <Button
+                label="Submit Form"
+                submit={true}
+                disabled={!formState.isDirty || !formState.isValid}
+              />
+            </Content>
+          </Form>
+          <pre>{JSON.stringify(formState, null, 2)}</pre>
+        </>
+      );
+    }}
+  </Story>
+</Canvas>

package/src/useFormState/useFormState.ts

@@ -0,0 +1,10 @@
+import { useState } from "react";
+
+export function useFormState() {
+  const [formState, setFormState] = useState({
+    isDirty: false,
+    isValid: true,
+  });
+
+  return [formState, setFormState] as const;
+}

package/src/useIsMounted/index.ts

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

package/src/useIsMounted/useIsMounted.stories.mdx

@@ -0,0 +1,59 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import { useEffect, useState } from "react";
+import { Button } from "@jobber/components/Button";
+import * as hooks from ".";
+
+<Meta title="Hooks/useIsMounted" />
+
+# UseIsMounted
+
+`useIsMounted` should be used on asynchronous calls to ensure the component is
+mounted before manipulating the state of that component. Manipulating the state
+of unmounted components can cause errors and memory leaks.
+
+```tsx
+import { useIsMounted } from "@jobber/hooks";
+```
+
+<Canvas>
+  <Story name="useIsMounted">
+    {() => {
+      function AlertMountedComponent() {
+        const isMounted = hooks.useIsMounted();
+        useEffect(() => {
+          setTimeout(() => {
+            if (isMounted.current) {
+              // only set state if the component is still mounted
+              console.log("The component is mounted");
+            } else {
+              console.log("The component is not mounted");
+            }
+          }, 10000);
+        }, []);
+        return <h4>I am the AlertMountedComponent</h4>;
+      }
+      const [shouldMount, setShouldMount] = useState(false);
+      let component = <></>;
+      if (shouldMount) {
+        component = <AlertMountedComponent />;
+      }
+      return (
+        <>
+          {component}
+          <Button
+            label={"Mount Component"}
+            onClick={() => {
+              setShouldMount(true);
+            }}
+          />
+          <Button
+            label={"Unmount Component"}
+            onClick={() => {
+              setShouldMount(false);
+            }}
+          />
+        </>
+      );
+    }}
+  </Story>
+</Canvas>