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

package/src/useIsMounted/useIsMounted.test.tsx

@@ -0,0 +1,18 @@
+import { renderHook } from "@testing-library/react-hooks";
+import { useIsMounted } from "./useIsMounted";
+
+it("should return true when the component is currently mounted", () => {
+  const { result } = renderHook(() => useIsMounted());
+  const isMounted = result.current;
+
+  expect(isMounted.current).toBe(true);
+});
+
+it("should return false when the component is unmounted", () => {
+  const { result, unmount } = renderHook(() => useIsMounted());
+  const isMounted = result.current;
+
+  unmount();
+
+  expect(isMounted.current).toBe(false);
+});

package/src/useIsMounted/useIsMounted.ts

@@ -0,0 +1,30 @@
+import { useLayoutEffect, useRef } from "react";
+
+/**
+ * Why does this work?
+ *
+ * The following is from the react docs:
+ *    [The return function from `useLayoutEffect`] is the optional cleanup mechanism for effects.
+ *    Every effect may return a function that cleans up after it.
+ *
+ *    When exactly does React clean up an effect? React performs the cleanup when the component unmounts.
+ *    The cleanup for useLayoutEffect is called after component unmounts and before before browser painting
+ *    the screen
+ *
+ * What does that mean for us? When this hook is initially loaded, we then trigger a `useLayoutEffect` that
+ * sets the isMounted to true right after the component is mounted.
+ * When the component unmounts, it calls the cleanup function that sets `isMounted` to false.
+ * This `useLayoutEffect` hook will only be run once.
+ */
+export function useIsMounted(): { current: boolean } {
+  const isMounted = useRef(false);
+
+  useLayoutEffect(() => {
+    isMounted.current = true;
+    return () => {
+      isMounted.current = false;
+    };
+  }, []);
+
+  return isMounted;
+}

package/src/useLiveAnnounce/index.ts

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

package/src/useLiveAnnounce/useLiveAnnounce.stories.mdx

@@ -0,0 +1,38 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import { Button } from "@jobber/components/Button";
+import * as hooks from ".";
+
+<Meta title="Hooks/useLiveAnnounce" />
+
+# useLiveAnnounce
+
+Announce a message through the screen reader whenever a user does an action like
+deletion or addition.
+
+```ts
+import { useLiveAnnounce } from "@jobber/hooks";
+```
+
+Before you try this example, turn on Voice Over (Mac), or a Windows equivalent.
+You can turn on Voice Over by holding `Command ⌘` and press the fingerprint key
+3 times (fast).
+
+<Canvas>
+  <Story name="useLiveAnnounce">
+    {() => {
+      const { liveAnnounce } = hooks.useLiveAnnounce();
+      return (
+        <>
+          <Button
+            label="Delete"
+            onClick={() => liveAnnounce("You have clicked the Delete button")}
+          />{" "}
+          <Button
+            label="Add"
+            onClick={() => liveAnnounce("You have clicked the Add button")}
+          />
+        </>
+      );
+    }}
+  </Story>
+</Canvas>

package/src/useLiveAnnounce/useLiveAnnounce.test.tsx

@@ -0,0 +1,55 @@
+import React from "react";
+import { act, render, screen, waitFor } from "@testing-library/react";
+import { useLiveAnnounce } from ".";
+
+function setupHook() {
+  const returnVal: ReturnType<typeof useLiveAnnounce> = {
+    liveAnnounce: jest.fn,
+  };
+
+  function TestComponent() {
+    Object.assign(returnVal, useLiveAnnounce());
+    return <></>;
+  }
+
+  const { rerender } = render(<TestComponent />);
+  return { ...returnVal, rerenderComponent: () => rerender(<TestComponent />) };
+}
+
+it("should render a div to announce", async () => {
+  const { liveAnnounce } = setupHook();
+  const message = "Huzzah";
+  act(() => liveAnnounce(message));
+
+  await waitFor(() => {
+    const expectedElement = screen.queryByRole("status");
+    expect(expectedElement).toBeInTheDocument();
+    expect(expectedElement?.textContent).toBe(message);
+    expect(expectedElement).toHaveAttribute("role", "status");
+    expect(expectedElement).toHaveAttribute("aria-atomic", "true");
+    expect(expectedElement).toHaveAttribute("aria-live", "assertive");
+  });
+});
+
+it("should not render the announced div", async () => {
+  setupHook();
+  expect(screen.queryByRole("status")).not.toBeInTheDocument();
+});
+
+it("should only have 1 div to announce a message on a single instance of the hook", async () => {
+  const { liveAnnounce } = setupHook();
+  const firstMessage = "I am first";
+  const secondMessage = "I am second";
+
+  act(() => liveAnnounce(firstMessage));
+  await waitFor(() => {
+    expect(screen.queryAllByRole("status")).toHaveLength(1);
+    expect(screen.getByRole("status").textContent).toBe(firstMessage);
+  });
+
+  act(() => liveAnnounce(secondMessage));
+  await waitFor(() => {
+    expect(screen.queryAllByRole("status")).toHaveLength(1);
+    expect(screen.getByRole("status").textContent).toBe(secondMessage);
+  });
+});

package/src/useLiveAnnounce/useLiveAnnounce.tsx

@@ -0,0 +1,47 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Announce a message on voice over whenever you do an action. This is
+ * especially helpful when you have an action that adds or deletes an element
+ * from the screen.
+ */
+export function useLiveAnnounce() {
+  const [announcedMessage, setAnnouncedMessage] = useState("");
+
+  useEffect(() => {
+    let target: HTMLElement;
+
+    if (announcedMessage) {
+      target = createAnnouncedElement();
+      setTimeout(() => target.append(announcedMessage), 100);
+    }
+
+    return () => target?.remove();
+  }, [announcedMessage]);
+
+  return {
+    liveAnnounce: (message: string) => {
+      setAnnouncedMessage(message);
+    },
+  };
+}
+
+// eslint-disable-next-line max-statements
+function createAnnouncedElement() {
+  const el = document.createElement("div");
+
+  el.style.position = "absolute";
+  el.style.width = "1px";
+  el.style.height = "1px";
+  el.style.overflow = "hidden";
+  el.style.clipPath = " inset(100%)";
+  el.style.whiteSpace = " nowrap";
+  el.style.top = "0";
+  el.setAttribute("role", "status");
+  el.setAttribute("aria-atomic", "true");
+  el.setAttribute("aria-live", "assertive");
+
+  document.body.appendChild(el);
+
+  return el;
+}

package/src/useOnKeyDown/index.ts

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

package/src/useOnKeyDown/useOnKeyDown.stories.mdx

@@ -0,0 +1,67 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import { useState } from "react";
+import { Text } from "@jobber/components/Text";
+import { Card } from "@jobber/components/Card";
+import { Content } from "@jobber/components/Content";
+import * as hooks from ".";
+
+<Meta title="Hooks/useOnKeyDown" />
+
+# useOnKeyDown
+
+`useOnKeyDown` is a simple hook that adds the `keydown` event handler when the
+component is mounted and removed when unmounted.
+
+`useOnKeyDown` should **only** be used when building keyboard shortcuts in a
+component.
+
+```tsx
+import { useOnKeyDown } from "@jobber/hooks";
+```
+
+You can specify a list of keys to watch including a key modifier with the event
+handler.
+
+<Canvas>
+  <Story name="useOnKeyDown">
+    {() => {
+      const initialListText = "";
+      const [listText, setListText] = useState(initialListText);
+      const initialModifierText = "Press escape to clear this text";
+      const [modifierText, setModifierText] = useState(initialModifierText);
+      hooks.useOnKeyDown(
+        e => {
+          setListText("You pressed '" + e.key + "'");
+        },
+        ["Shift", "Enter"]
+      );
+      hooks.useOnKeyDown(
+        () => setModifierText("Removed. Press Control + z to undo."),
+        "Escape"
+      );
+      hooks.useOnKeyDown(() => setModifierText(initialModifierText), {
+        key: "z",
+        ctrlKey: true,
+      });
+      return (
+        <Content>
+          <Card title="Shift or Enter Example">
+            <Content>
+              Press shift or enter.
+              <pre>{listText}</pre>
+            </Content>
+          </Card>
+          <Card title="With a Key modifier">
+            <Content>
+              <Text>
+                A key can have a modifier. In this case, we show how to
+                implement a ctrl+z workflow.
+              </Text>
+              <pre>{modifierText}</pre>
+            </Content>
+          </Card>
+        </Content>
+      );
+    }}
+  </Story>
+</Canvas>

package/src/useOnKeyDown/useOnKeyDown.test.tsx

@@ -0,0 +1,31 @@
+import React from "react";
+import { fireEvent, render } from "@testing-library/react";
+import { useOnKeyDown } from ".";
+
+test("fires the method when the key is pressed", () => {
+  const keypressCallback = jest.fn();
+  const { container } = render(<TestComponent callback={keypressCallback} />);
+
+  expect(keypressCallback).toHaveBeenCalledTimes(0);
+
+  fireEvent(
+    container,
+    new KeyboardEvent("keydown", {
+      key: "Enter",
+      bubbles: true,
+      cancelable: false,
+    }),
+  );
+
+  expect(keypressCallback).toHaveBeenCalledTimes(1);
+});
+
+interface TestComponentProps {
+  callback(): void;
+}
+
+function TestComponent({ callback }: TestComponentProps) {
+  useOnKeyDown(callback, "Enter");
+
+  return <>Look at me!</>;
+}

package/src/useOnKeyDown/useOnKeyDown.ts

@@ -0,0 +1,52 @@
+import useEventListener from "@use-it/event-listener";
+import { XOR } from "ts-xor";
+
+type SimpleKeyComparator = KeyboardEvent["key"];
+
+interface VerboseKeyComparator {
+  readonly key: SimpleKeyComparator;
+  readonly shiftKey?: boolean;
+  readonly ctrlKey?: boolean;
+  readonly altKey?: boolean;
+  readonly metaKey?: boolean;
+  readonly [index: string]: boolean | string | undefined;
+}
+
+type KeyComparator = XOR<VerboseKeyComparator, SimpleKeyComparator>;
+
+export function useOnKeyDown(
+  callback: (event: KeyboardEvent) => void,
+  keys: KeyComparator[] | KeyComparator,
+) {
+  useEventListener("keydown", handler);
+
+  function handler(event: KeyboardEvent) {
+    const keyboardEvent = event as unknown as VerboseKeyComparator;
+    if (typeof keys === "string" && keyboardEvent.key === keys) {
+      callback(event);
+      return;
+    }
+
+    if (
+      Array.isArray(keys) &&
+      keys.some(item => {
+        if (typeof item === "string") return keyboardEvent.key === item;
+        return Object.keys(item).every(
+          index => keyboardEvent[index] === item[index],
+        );
+      })
+    ) {
+      callback(event);
+      return;
+    }
+
+    if (
+      !Array.isArray(keys) &&
+      typeof keys !== "string" &&
+      Object.keys(keys).every(index => keyboardEvent[index] === keys[index])
+    ) {
+      callback(event);
+      return;
+    }
+  }
+}

package/src/usePasswordStrength/index.ts

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

package/src/usePasswordStrength/usePasswordStrength.stories.mdx

@@ -0,0 +1,51 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs";
+import { useState } from "react";
+import { Content } from "@jobber/components/Content";
+import { DataDump } from "@jobber/components/DataDump";
+import { InputText } from "@jobber/components/InputText";
+import * as hooks from ".";
+
+<Meta title="Hooks/usePasswordStrength" />
+
+# usePasswordStrength
+
+`usePasswordStrength` is a hook used to calculate the strength of a password
+using the [zxcvbn](https://github.com/dropbox/zxcvbn) package. You can use it
+as-is or pass a dictionary of common passwords which should be treated as
+insecure.
+
+```tsx
+import { usePasswordStrength } from "@jobber/hooks";
+```
+
+<Canvas>
+  <Story name="usePasswordStrength">
+    {() => {
+      const [password, setPassword] = useState("atlantis_is_a_strong_password");
+      const resultWithoutDict = hooks.usePasswordStrength(password);
+      const resultWithDict = hooks.usePasswordStrength(password, [
+        "atlantis",
+        "atlantis_is_a_strong_password",
+      ]);
+      return (
+        <Content>
+          <InputText
+            placeholder="Password"
+            defaultValue="atlantis_is_a_strong_password"
+            onChange={setPassword}
+          />
+          <DataDump
+            label="Password Strength (with Dictionary)"
+            data={resultWithDict}
+            defaultOpen
+          />
+          <DataDump
+            label="Password Strength (without Dictionary)"
+            data={resultWithoutDict}
+            defaultOpen
+          />
+        </Content>
+      );
+    }}
+  </Story>
+</Canvas>

package/src/usePasswordStrength/usePasswordStrength.ts

@@ -0,0 +1,21 @@
+import { useMemo } from "react";
+import calculateStrength from "zxcvbn";
+
+export function usePasswordStrength(password: string, dictionary?: string[]) {
+  const {
+    guesses,
+    score,
+    feedback: { warning, suggestions },
+    crack_times_display: { offline_fast_hashing_1e10_per_second: timeToCrack },
+  } = useMemo(
+    () => calculateStrength(password, dictionary),
+    [password, dictionary],
+  );
+  return {
+    guesses,
+    score,
+    warning,
+    suggestions,
+    timeToCrack,
+  };
+}

package/src/useRefocusOnActivator/index.ts

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

package/src/useRefocusOnActivator/useRefocusOnActivator.stories.mdx

@@ -0,0 +1,39 @@
+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 { Card } from "@jobber/components/Card";
+import * as hooks from ".";
+
+<Meta title="Hooks/useRefocusOnActivator" />
+
+# useRefocusOnActivator
+
+Improves the keyboard accessibility on modals and/or popovers since the HTML
+element focus returns to the one that opens it.
+
+```tsx
+import { useRefocusOnActivator } from "@jobber/hooks";
+```
+
+<Canvas>
+  <Story name="useRefocusOnActivator">
+    {() => {
+      const [open, setOpen] = useState(false);
+      hooks.useRefocusOnActivator(open);
+      return (
+        <Content>
+          <Button label="Click me" onClick={() => setOpen(true)} />
+          {open && (
+            <Card onClick={() => setOpen(false)}>
+              <Content>
+                Huzzah! Click me to hide me and watch me return the focus on the
+                button
+              </Content>
+            </Card>
+          )}
+        </Content>
+      );
+    }}
+  </Story>
+</Canvas>

package/src/useRefocusOnActivator/useRefocusOnActivator.ts

@@ -0,0 +1,26 @@
+import { useEffect } from "react";
+
+/**
+ * Brings back the focus to the element that opened an overlaid element once
+ * said overlaid element is dismissed.
+ *
+ * @param active - Determines if it should focus or not
+ */
+export function useRefocusOnActivator(active: boolean) {
+  useEffect(() => {
+    let activator: Element | null | undefined;
+
+    if (active && !activator) {
+      activator = document.activeElement;
+    }
+
+    return () => {
+      if (active) {
+        if (activator instanceof HTMLElement) {
+          activator.focus();
+        }
+        activator = undefined;
+      }
+    };
+  }, [active]);
+}

package/src/useResizeObserver/index.ts

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

package/src/useResizeObserver/useResizeObserver.stories.mdx

@@ -0,0 +1,134 @@
+import { isValidElement } from "react";
+import { Canvas, Meta, Source, Story } from "@storybook/addon-docs";
+import { ExampleWithHooks } from "mdxUtils/ExampleWithHooks";
+import { Text } from "@jobber/components/Text";
+import { Card } from "@jobber/components/Card";
+import { Content } from "@jobber/components/Content";
+import * as hooks from ".";
+
+<Meta title="Hooks/useResizeObserver" />
+
+# useResizeObserver
+
+`useResizeObserver` is a hook that will allow for responsive styling of
+components based on their size, instead of the browser size.
+
+```tsx
+import { useResizeObserver } from "@jobber/hooks";
+```
+
+<Canvas withToolbar>
+  <Story name="useResizeObserver">
+    {() => {
+      const { Breakpoints } = hooks;
+      const [ref, { width, exactWidth, exactHeight, height }] =
+        hooks.useResizeObserver();
+      return (
+        <div ref={ref}>
+          <Card title={`Check out my àçƈéñŦ`} accent={getAccent()}>
+            <Content>
+              <Text>Width Step: {width}</Text>
+              <Text>Height Step: {height}</Text>
+              <Text>Exact Width: {exactWidth}</Text>
+              <Text>Exact Height: {exactHeight}</Text>
+            </Content>
+          </Card>
+        </div>
+      );
+      function getAccent() {
+        if (exactWidth < Breakpoints.smaller) return "red";
+        if (width < Breakpoints.small) return "orange";
+        if (width < Breakpoints.base) return "yellow";
+        if (width < Breakpoints.large) return "green";
+        if (width < Breakpoints.larger) return "lightBlue";
+        return "purple";
+      }
+    }}
+  </Story>
+</Canvas>
+
+## Typing
+
+When using `useResizeObserver` in a component, you will need to pass it a type
+to represent the `ref`. In the example below, we pass it the type of
+`HTMLDivElement`.
+
+```tsx
+const [ref, { width, height }] = useResizeObserver<HTMLDivElement>();
+return <div ref={ref}>...</div>;
+```
+
+## Breakpoints
+
+`useResizeObserver` exports an object of `Breakpoints`. This can be used for
+high level components such as `Page`
+
+```tsx
+import { Breakpoints } from "@jobber/hooks";
+```
+
+### The `Breakpoints` object:
+
+<Source language="json" code={JSON.stringify(hooks.Breakpoints)} />
+
+## Custom Sizes
+
+`useResizeObserver` can take a custom `widths` or `heights` object if you do not
+want to use `Breakpoints`.
+
+<Canvas withToolbar>
+  <ExampleWithHooks>
+    {() => {
+      const customWidths = {
+        small: 480,
+        medium: 640,
+        large: 768,
+      };
+      const [ref, { width, exactWidth }] = hooks.useResizeObserver({
+        widths: customWidths,
+      });
+      return (
+        <div ref={ref}>
+          <Card title={`Width: ${getCurrentWidth()}`} accent={getAccent()}>
+            <Content>
+              <Text>Width Step: {width}</Text>
+              <Text>Exact Width: {exactWidth}</Text>
+            </Content>
+          </Card>
+        </div>
+      );
+      function getAccent() {
+        if (width < customWidths.medium) return "red";
+        if (width < customWidths.large) return "green";
+        return "indigo";
+      }
+      function getCurrentWidth() {
+        return Object.keys(customWidths).find(
+          key => customWidths[key] === width
+        );
+      }
+    }}
+  </ExampleWithHooks>
+</Canvas>
+
+## Testing with Jest
+
+Use `jest.mock` to set your desired window attributes.
+
+```tsx
+jest.mock("@jobber/hooks", () => {
+  return {
+    useResizeObserver: () => [
+      { current: undefined },
+      { width: 1000, height: 100 },
+    ],
+    Breakpoints: {
+      base: 640,
+      small: 500,
+      smaller: 265,
+      large: 750,
+      larger: 1024,
+    },
+  };
+});
+```