@boxcustodia/library 2.0.0-alpha.10 → 2.0.0-alpha.12

package/src/hooks/useLocalStorage/__doc__/useLocalStorage.stories.tsx

@@ -0,0 +1,86 @@
+import { Meta } from "@storybook/react-vite";
+import { Trash } from "lucide-react";
+import { Button, Input } from "../../../components";
+import useLocalStorage from "../useLocalStorage";
+
+/**
+ * Hook que proporciona una interfaz sencilla para interactuar con el localStorage de manera tipada.
+ *
+ * Este hook permite almacenar, recuperar y eliminar valores en el localStorage de manera segura,
+ * utilizando una API genérica que asegura la consistencia de tipos en TypeScript. Es compatible con cualquier
+ * tipo de dato, desde strings hasta objetos complejos.
+ *
+ * @param key - La clave del localStorage donde se almacenará el valor.
+ * @param initialValue - El valor inicial que se utilizará si no hay datos almacenados bajo la clave proporcionada.
+ * @returns Una tupla con el valor almacenado, una función para actualizarlo y otra para eliminarlo.
+ *
+ * @example
+ * const [name, setName, removeName] = useLocalStorage<string>("name", "John Doe");
+ *
+ * @example
+ * const [count, setCount, removeCount] = useLocalStorage<number>("count", 0);
+ *
+ * @example
+ * const [items, setItems, removeItems] = useLocalStorage<string[]>("items", ["apple", "banana"]);
+ */
+const meta: Meta = {
+  title: "hooks/useLocalStorage",
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const [value, setValue, removeValue] = useLocalStorage<string>("myKey", "");
+
+    return (
+      <div className="space-y-2">
+        <Input value={value} onChange={setValue} />
+        <Button onClick={removeValue}>Clear</Button>
+      </div>
+    );
+  },
+};
+
+export const WithNumber = {
+  render: () => {
+    const [count, setCount, removeCount] = useLocalStorage<number>("count", 0);
+
+    return (
+      <div className="space-y-2">
+        <p>Count: {count}</p>
+        <div className="flex gap-2">
+          <Button onClick={() => setCount(count + 1)}>Increment</Button>
+          <Button onClick={removeCount}>Reset</Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const WithArray = {
+  render: () => {
+    const [items, setItems, removeItems] = useLocalStorage<string[]>(
+      "oranges",
+      ["🍊"],
+    );
+
+    return (
+      <div className="space-y-2">
+        <ul>
+          {items.map((item, index) => (
+            <li key={index}>{item}</li>
+          ))}
+        </ul>
+        <div className="flex gap-2">
+          <Button onClick={() => setItems([...items, "🍊"])}>
+            🍊 Add Orange
+          </Button>
+          <Button onClick={removeItems}>
+            <Trash /> Clear List
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};

package/src/hooks/useLocalStorage/__test__/useLocalStorage.test.ts

@@ -0,0 +1,85 @@
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import useLocalStorage from "../useLocalStorage";
+
+describe("useLocalStorage hook", () => {
+  const key = "testKey";
+
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("should be defined", () => {
+    expect(useLocalStorage).toBeDefined();
+  });
+
+  it("should initialize with default value if localStorage is empty", () => {
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("initialValue");
+  });
+
+  it("should retrieve stored value from localStorage", () => {
+    localStorage.setItem(key, JSON.stringify("storedValue"));
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("storedValue");
+  });
+
+  it("should update localStorage when value changes", () => {
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    const [, setValue] = result.current;
+
+    act(() => {
+      setValue("newValue");
+    });
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("newValue");
+    expect(localStorage.getItem(key)).toBe(JSON.stringify("newValue"));
+  });
+
+  it("should remove the value from localStorage when remove is called", () => {
+    localStorage.setItem(key, JSON.stringify("storedValue"));
+
+    const { result } = renderHook(() => useLocalStorage<string>(key, ""));
+
+    const [, , remove] = result.current;
+
+    act(() => {
+      remove();
+    });
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("");
+  });
+
+  it("should handle non-JSON serializable values gracefully", () => {
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {
+        console.log("error");
+      });
+    localStorage.setItem(key, "non-JSON-string");
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("initialValue");
+    expect(consoleErrorSpy).toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+  });
+});

package/src/hooks/useLocalStorage/index.ts

@@ -0,0 +1 @@
+export { default as useLocalStorage } from "./useLocalStorage";

package/src/hooks/useLocalStorage/useLocalStorage.ts

@@ -0,0 +1,57 @@
+import { useEffect, useState } from "react";
+
+function useLocalStorage<T>(
+  key: string,
+): [T | undefined, (value: T) => void, () => void];
+function useLocalStorage<T>(
+  key: string,
+  initialValue: T,
+): [T, (value: T) => void, () => void];
+function useLocalStorage<T>(
+  key: string,
+  initialValue?: T,
+): [T | undefined, (value: T) => void, () => void] {
+  const getStoredValue = (): T | undefined => {
+    try {
+      const item = localStorage.getItem(key);
+      if (item) {
+        return JSON.parse(item) as T;
+      }
+      return initialValue !== undefined ? initialValue : undefined;
+    } catch (error) {
+      console.error(`Error parsing localStorage key "${key}":`, error);
+      return initialValue !== undefined ? initialValue : undefined;
+    }
+  };
+
+  const [storedValue, setStoredValue] = useState<T | undefined>(getStoredValue);
+
+  useEffect(() => {
+    try {
+      if (storedValue !== undefined) {
+        localStorage.setItem(key, JSON.stringify(storedValue));
+      } else {
+        localStorage.removeItem(key);
+      }
+    } catch (error) {
+      console.error(`Error setting localStorage key "${key}":`, error);
+    }
+  }, [key, storedValue]);
+
+  const setValue = (value: T) => {
+    setStoredValue(value);
+  };
+
+  const remove = () => {
+    try {
+      localStorage.removeItem(key);
+      setStoredValue(initialValue !== undefined ? initialValue : undefined);
+    } catch (error) {
+      console.error(`Error removing localStorage key "${key}":`, error);
+    }
+  };
+
+  return [storedValue, setValue, remove];
+}
+
+export default useLocalStorage;

package/src/hooks/useMediaQuery/__doc__/useMediaQuery.stories.tsx

@@ -0,0 +1,39 @@
+import { Meta } from "@storybook/react-vite";
+import useMediaQuery from "../useMediaQuery";
+
+const meta: Meta = {
+  title: "hooks/useMediaQuery",
+};
+
+export default meta;
+
+export const Default = () => {
+  const isSmallDevice = useMediaQuery("(max-width: 768px)");
+  const isMediumDevice = useMediaQuery(
+    "(min-width: 769px) and (max-width: 992px)",
+  );
+  const isLargeDevice = useMediaQuery(
+    "(min-width: 993px) and (max-width: 1200px)",
+  );
+  const isExtraLargeDevice = useMediaQuery("(min-width: 1201px)");
+
+  return (
+    <div className="flex items-center justify-center h-screen">
+      <div
+        className={`
+        p-8 rounded-lg text-white text-center transition-all duration-500
+        ${isSmallDevice ? "bg-blue-500" : ""}
+        ${isMediumDevice ? "bg-green-500" : ""}
+        ${isLargeDevice ? "bg-yellow-500" : ""}
+        ${isExtraLargeDevice ? "bg-red-500" : ""}
+      `}
+      >
+        {isSmallDevice && "📱 You are using a Small Device (max-width: 768px)"}
+        {isMediumDevice && "💻 You are using a Medium Device (769px - 992px)"}
+        {isLargeDevice && "🖥️ You are using a Large Device (993px - 1200px)"}
+        {isExtraLargeDevice &&
+          "🖥️ You are using an Extra Large Device (min-width: 1201px)"}
+      </div>
+    </div>
+  );
+};

package/src/hooks/useMediaQuery/index.ts

@@ -0,0 +1 @@
+export { default as useMediaQuery } from "./useMediaQuery";

package/src/hooks/useMediaQuery/useMediaQuery.ts

@@ -0,0 +1,22 @@
+import { useEffect, useState } from "react";
+
+const useMediaQuery = (query: string): boolean => {
+  const [matches, setMatches] = useState<boolean>(false);
+
+  useEffect(() => {
+    const mediaQueryList = window.matchMedia(query);
+    const documentChangeHandler = () => setMatches(mediaQueryList.matches);
+
+    documentChangeHandler();
+
+    mediaQueryList.addEventListener("change", documentChangeHandler);
+
+    return () => {
+      mediaQueryList.removeEventListener("change", documentChangeHandler);
+    };
+  }, [query]);
+
+  return matches;
+};
+
+export default useMediaQuery;

package/src/hooks/useMemoizedFn/index.ts

@@ -0,0 +1 @@
+export { default as useMemoizedFn } from "./useMemoizedFn";

package/src/hooks/useMemoizedFn/useMemoizedFn.ts

@@ -0,0 +1,32 @@
+import { isFunction } from "lodash";
+import { useMemo, useRef } from "react";
+
+type noop = (this: any, ...args: any[]) => any;
+
+type PickFunction<T extends noop> = (
+  this: ThisParameterType<T>,
+  ...args: Parameters<T>
+) => ReturnType<T>;
+
+function useMemoizedFn<T extends noop>(fn: T) {
+  if (!isFunction(fn)) {
+    console.error(
+      `useMemoizedFn expected parameter is a function, got ${typeof fn}`,
+    );
+  }
+
+  const fnRef = useRef<T>(fn);
+
+  fnRef.current = useMemo<T>(() => fn, [fn]);
+
+  const memoizedFn = useRef<PickFunction<T>>(null);
+  if (!memoizedFn.current) {
+    memoizedFn.current = function (this, ...args) {
+      return fnRef.current.apply(this, args);
+    };
+  }
+
+  return memoizedFn.current as T;
+}
+
+export default useMemoizedFn;

package/src/hooks/useMutation/__doc__/useMutation.stories.tsx

@@ -0,0 +1,111 @@
+import { Meta } from "@storybook/react-vite";
+import { FormEvent } from "react";
+import { Button, Input } from "../../../components";
+import { getFormData } from "../../../utils";
+import useAsync from "../../useAsync/useAsync";
+import useMutation from "../useMutation";
+
+/**
+ * El hook `useMutation` permite manejar operaciones de mutación asincrónicas, proporcionando estados de carga, error y éxito.
+ *
+ * Opciones de configuración:
+ * - `fn`: La función de mutación que se ejecutará.
+ * - `onError`: Callback opcional que se llama cuando ocurre un error.
+ * - `onSuccess`: Callback opcional que se llama cuando la mutación es exitosa.
+ * - `onFinish`: Callback opcional que se llama cuando la mutación termina, sin importar si tuvo éxito o error. Es útil para hacer un `refetch` (de `useAsync`)
+ *
+ * Devuelve un objeto con las siguientes propiedades:
+ * - `mutate`: Función para ejecutar la mutación.
+ * - `loading`: Indica si la mutación está en progreso.
+ * - `error`: Contiene el error si la mutación falla.
+ * - `data`: Contiene los datos si la mutación es exitosa.
+ */
+
+const meta: Meta = {
+  title: "hooks/useMutation",
+  parameters: {
+    docs: {
+      source: { type: "code" },
+    },
+  },
+};
+
+export default meta;
+
+interface FakeTodo {
+  userId: number;
+  id: number;
+  title: string;
+  completed: boolean;
+}
+
+const fetchTodos = async (): Promise<FakeTodo> => {
+  const response = fetch("https://jsonplaceholder.typicode.com/todos/1").then(
+    (response) => response.json(),
+  );
+  if (!response) throw new Error("Todo not found");
+  return response;
+};
+
+const createTodo = async (title: string): Promise<FakeTodo> => {
+  if (!title) throw new Error("Title is required");
+  return await fetch("https://jsonplaceholder.typicode.com/posts", {
+    method: "POST",
+    body: JSON.stringify({
+      title: title,
+      body: "bar",
+      userId: 1,
+    }),
+    headers: {
+      "Content-type": "application/json; charset=UTF-8",
+    },
+  })
+    .then((response) => response.json())
+    .then((json) => json);
+};
+
+const Result = ({ loading = false, data = null, error = null }: any) => (
+  <pre className="rounded-md bg-slate-950 p-4 text-white mt-2">
+    {JSON.stringify(
+      {
+        loading,
+        error,
+        data,
+      },
+      undefined,
+      2,
+    )}
+  </pre>
+);
+
+export const Form = {
+  render: () => {
+    const { refetch } = useAsync<FakeTodo>({
+      fn: fetchTodos,
+    });
+
+    const { mutate, loading, data, error } = useMutation({
+      fn: createTodo,
+      onFinish: () => refetch(),
+    });
+
+    const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      const data = getFormData(event);
+      if ("title" in data) mutate(data.title);
+    };
+
+    return (
+      <div>
+        <form className="space-y-2" onSubmit={handleSubmit}>
+          <Input placeholder="title" name="title" autoComplete="0" />
+          <Button type="submit" loading={loading}>
+            Enviar
+          </Button>
+        </form>
+
+        <Result loading={loading} data={data} error={error?.message} />
+      </div>
+    );
+  },
+};

package/src/hooks/useMutation/__test__/useMutation.test.tsx

@@ -0,0 +1,83 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import useMutation from "../useMutation";
+
+const mockMutationSuccess = async (data: any) => {
+  return new Promise((resolve) => setTimeout(() => resolve(data), 100));
+};
+
+const mockMutationError = async () => {
+  return new Promise((_, reject) =>
+    setTimeout(() => reject(new Error("Mutation error")), 100),
+  );
+};
+
+describe("useMutation hook", () => {
+  it("should initialize with default state", () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => Promise.resolve("test") }),
+    );
+
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.data).toBeNull();
+  });
+
+  it("should handle success", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => mockMutationSuccess("success") }),
+    );
+
+    result.current.mutate();
+    await waitFor(() => expect(result.current.data).toBe("success"));
+  });
+
+  it("should handle error", async () => {
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => mockMutationError() }),
+    );
+
+    try {
+      await result.current.mutate();
+    } catch (e) {
+      console.log(e);
+      await waitFor(() => expect(result.current.error).not.toBeNull());
+    }
+  });
+
+  it("should call onSuccess callback", async () => {
+    const onSuccess = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => mockMutationSuccess("success"), onSuccess }),
+    );
+
+    result.current.mutate();
+    await waitFor(() => expect(onSuccess).toHaveBeenCalledWith("success"));
+  });
+
+  it("should call onError callback", async () => {
+    const onError = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => mockMutationError(), onError }),
+    );
+
+    try {
+      await result.current.mutate();
+    } catch (e) {
+      console.log(e);
+      await waitFor(() =>
+        expect(onError).toHaveBeenCalledWith(expect.any(Error)),
+      );
+    }
+  });
+
+  it("should call onFinish callback", async () => {
+    const onFinish = vi.fn();
+    const { result } = renderHook(() =>
+      useMutation({ fn: () => mockMutationSuccess("success"), onFinish }),
+    );
+
+    result.current.mutate();
+    await waitFor(() => expect(onFinish).toHaveBeenCalled());
+  });
+});

package/src/hooks/useMutation/index.ts

@@ -0,0 +1 @@
+export { default as useMutation } from "./useMutation";

package/src/hooks/useMutation/useMutation.tsx

@@ -0,0 +1,60 @@
+import { useCallback, useState } from "react";
+
+type Mutation<TArgs extends any[], TReturn> = (
+  ...args: TArgs
+) => Promise<TReturn>;
+
+interface UseMutationOptions<TArgs extends any[], TReturn> {
+  fn: Mutation<TArgs, TReturn>;
+  onError?: (error: Error) => void;
+  onSuccess?: (data: TReturn) => void;
+  onFinish?: () => void;
+}
+
+interface UseMutationReturn<TArgs extends any[], TReturn> {
+  mutate: Mutation<TArgs, TReturn>;
+  loading: boolean;
+  error: Error | null;
+  data: TReturn | null;
+}
+
+export const useMutation = <TArgs extends any[], TReturn>(
+  opts: UseMutationOptions<TArgs, TReturn>,
+): UseMutationReturn<TArgs, TReturn> => {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setdata] = useState<TReturn | null>(null);
+
+  const mutate = useCallback(
+    async (...args: TArgs) => {
+      setLoading(true);
+      setError(null);
+      setdata(null);
+
+      try {
+        const result = await opts.fn(...args);
+        opts.onSuccess?.(result);
+        setdata(result);
+        return result;
+      } catch (err) {
+        const error = err as Error;
+        opts.onError?.(error);
+        setError(error);
+        throw error;
+      } finally {
+        opts.onFinish?.();
+        setLoading(false);
+      }
+    },
+    [opts],
+  );
+
+  return {
+    mutate,
+    loading,
+    error,
+    data,
+  };
+};
+
+export default useMutation;