Merge pull request #13 from etecture/feature/hooks

Feature/hooks

Author: btmnk

core/src/hooks/index.ts

@@ -3,3 +3,6 @@ export * from "./useBreakpoint/useBreakpoint";
 export * from "./useSwiper/useSwiper";
 export * from "./useHotkeys/useHotkeys";
 export * from "./useToggle/useToggle";
+export * from "./useIsIdle/useIsIdle";
+export * from "./useOnChange/useOnChange";
+export * from "./usePrevious/usePrevious";

core/src/hooks/useIsIdle/stories/useIsIdle.stories.tsx

@@ -0,0 +1,19 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { type UseIsIdleOptions, useIsIdle } from "../useIsIdle";
+
+export default {
+  title: "Hooks/useIsIdle",
+  parameters: {
+    layout: "centered",
+  },
+  args: {
+    idleAfterMs: 1000,
+  } satisfies UseIsIdleOptions,
+} satisfies Meta;
+
+export const Default: StoryObj = {
+  render: (args: UseIsIdleOptions) => {
+    const isIdle = useIsIdle(args);
+    return <div>isIdle: {isIdle.toString()}</div>;
+  },
+};

core/src/hooks/useIsIdle/useIsIdle.test.tsx

@@ -0,0 +1,32 @@
+import { renderHook } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useIsIdle } from "./useIsIdle";
+
+const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+
+describe("useIsIdle", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+  });
+
+  it("should return idle by default", async () => {
+    const { result } = renderHook(() => useIsIdle({ idleAfterMs: 1000 }));
+    expect(result.current).toBe(true);
+  });
+
+  it("should return idle after the set amount of ms", async () => {
+    const { result } = renderHook(() => useIsIdle({ idleAfterMs: 1000 }));
+    expect(result.current).toBe(true);
+    await user.click(document.body);
+    expect(result.current).toBe(false);
+    await act(async () => await vi.advanceTimersByTimeAsync(1000));
+    expect(result.current).toBe(true);
+  });
+});

core/src/hooks/useIsIdle/useIsIdle.ts

@@ -0,0 +1,45 @@
+import { useEffect, useRef, useState } from "react";
+
+export interface UseIsIdleOptions {
+  /**
+   * The amount of time after the last interaction that marks the user as idle.
+   * @default 10000
+   */
+  idleAfterMs?: number;
+}
+
+/**
+ * Checks for user interaction and returns idle after a set time.
+ * The default user interactions are mousemove, mousedown, touchstart and keydown.
+ */
+export const useIsIdle = (options?: UseIsIdleOptions) => {
+  const { idleAfterMs = 10000 } = options ?? {};
+
+  const [isIdle, setIsIdle] = useState(true);
+
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>();
+
+  useEffect(() => {
+    const handleAction = (event: Event) => {
+      event.preventDefault();
+
+      setIsIdle(false);
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => {
+        setIsIdle(true);
+      }, idleAfterMs);
+    };
+
+    document.addEventListener("mousemove", handleAction);
+    document.addEventListener("touchstart mousedown", handleAction);
+    document.addEventListener("keydown", handleAction);
+
+    return () => {
+      document.removeEventListener("mousemove", handleAction);
+      document.removeEventListener("touchstart mousedown", handleAction);
+      document.removeEventListener("keydown", handleAction);
+    };
+  }, [idleAfterMs]);
+
+  return isIdle;
+};

core/src/hooks/useOnChange/useOnChange.test.tsx

@@ -0,0 +1,37 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useOnChange } from "./useOnChange";
+
+describe("useOnChange", () => {
+  it("should not trigger when nothing changed", async () => {
+    const onChange = vi.fn();
+
+    const { rerender } = renderHook((value: unknown) =>
+      useOnChange({ value: value ?? "first", onChange }),
+    );
+
+    expect(onChange).toHaveBeenCalledTimes(0);
+    rerender("first");
+    expect(onChange).toHaveBeenCalledTimes(0);
+  });
+
+  it("should trigger when value changed", async () => {
+    const onChange = vi.fn();
+
+    const { rerender } = renderHook((value: unknown) =>
+      useOnChange({ value: value ?? "first", onChange }),
+    );
+
+    rerender("first");
+    expect(onChange).toHaveBeenCalledTimes(0);
+    rerender("second");
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith("second");
+    rerender("third");
+    expect(onChange).toHaveBeenCalledTimes(2);
+    expect(onChange).toHaveBeenCalledWith("third");
+    rerender("fourth");
+    expect(onChange).toHaveBeenCalledTimes(3);
+    expect(onChange).toHaveBeenCalledWith("fourth");
+  });
+});

core/src/hooks/useOnChange/useOnChange.ts

@@ -0,0 +1,25 @@
+import { useEffect, useRef } from "react";
+import { usePrevious } from "../usePrevious/usePrevious";
+
+export interface UseOnChangeProps<ValueType> {
+  value: ValueType;
+  onChange: (value: ValueType) => void;
+}
+
+/**
+ * Triggers the onChange callback whenever the passed value changed since the last render.
+ */
+export const useOnChange = <ValueType>(props: UseOnChangeProps<ValueType>) => {
+  const { value, onChange } = props;
+
+  const lastChangeValue = useRef<ValueType | null>(null);
+  const previousValue = usePrevious(value, { useInitialValueAsPrevious: true });
+
+  useEffect(() => {
+    if (value === lastChangeValue.current) return;
+    if (value !== previousValue) {
+      onChange(value);
+    }
+    lastChangeValue.current = value;
+  }, [value, previousValue, onChange]);
+};

core/src/hooks/usePrevious/usePrevious.test.tsx

@@ -0,0 +1,32 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { usePrevious } from "./usePrevious";
+
+describe("usePrevious", () => {
+  it("should return null for the first render", async () => {
+    const { result } = renderHook(() => usePrevious("first"));
+    expect(result.current).toBeNull();
+  });
+
+  it("should return the previous value after rerender", async () => {
+    const { result, rerender } = renderHook((value: string) => usePrevious(value ?? "first"));
+    expect(result.current).toBeNull();
+    rerender("second");
+    expect(result.current).toBe("first");
+    rerender("third");
+    expect(result.current).toBe("second");
+    rerender("fourth");
+    rerender("fifth");
+    rerender("sixth");
+    expect(result.current).toBe("fifth");
+  });
+
+  it("should return the first value after the first render when useInitialValueAsPrevious is true", async () => {
+    const { result, rerender } = renderHook((value: string) =>
+      usePrevious(value ?? "first", { useInitialValueAsPrevious: true }),
+    );
+    expect(result.current).toBe("first");
+    rerender("second");
+    expect(result.current).toBe("first");
+  });
+});

core/src/hooks/usePrevious/usePrevious.ts

@@ -0,0 +1,35 @@
+import { useEffect, useRef, useState } from "react";
+
+export interface UsePreviousOptions {
+  /**
+   * If true, the first previous value will be the first passed value so you can avoid null checks.
+   */
+  useInitialValueAsPrevious?: boolean;
+}
+
+/**
+ * Keeps track of a states value from the last render. Is initially null.
+ * Set options: { useInitialValueAsPrevious = true } to use the first passed value as the first previous value.
+ */
+export const usePrevious = <ValueType, Options extends UsePreviousOptions>(
+  value: ValueType,
+  options?: Options,
+) => {
+  const { useInitialValueAsPrevious = false } = options ?? {};
+
+  const currentValue = useRef<ValueType | null>(useInitialValueAsPrevious ? value : null);
+  const [previousValue, setPreviousValue] = useState<ValueType | null>(
+    useInitialValueAsPrevious ? value : null,
+  );
+
+  useEffect(() => {
+    setPreviousValue(currentValue.current);
+    currentValue.current = value;
+  }, [value]);
+
+  type ReturnType = Options["useInitialValueAsPrevious"] extends true
+    ? ValueType
+    : ValueType | null;
+
+  return previousValue as ReturnType;
+};

docs/src/app/docs/hooks/use-is-idle/page.mdx

@@ -0,0 +1,17 @@
+import { ComponentLayout } from "../../../../layout/ComponentLayout/ComponentLayout"
+import { Demo } from "@/components/Demo";
+import { Default } from "@/examples/hooks/useIsIdle"
+
+```tsx
+const isIdle = useIsIdle({ idleAfterMs: 10000 })
+```
+
+This hook keeps track of user interactions and returns idle if the user didnt interact with the page for a set amount of time.
+
+## Example
+
+<Demo data={Default} />
+
+export default function MDXPage({ children }) {
+  return <ComponentLayout componentName={"useIsIdle"}>{children}</ComponentLayout>;
+}

docs/src/app/docs/hooks/use-on-change/page.mdx

@@ -0,0 +1,20 @@
+import { ComponentLayout } from "../../../../layout/ComponentLayout/ComponentLayout"
+import { Demo } from "@/components/Demo";
+
+```tsx
+const [value, setValue] = useState("hello world");
+
+const onChange = useCallback((changedValue: string) => {
+  console.log(changedValue)
+}, []);
+
+useOnChange({ value, onChange })
+```
+
+This hook triggers the passed onChange callback whenever the passed value is different to the one from the last render. It uses usePrevious under the hood.
+
+The check uses a shallow compare, if you pass an object you have to make sure that it is immutable.
+
+export default function MDXPage({ children }) {
+  return <ComponentLayout componentName={"useOnChange"}>{children}</ComponentLayout>;
+}