@boxcustodia/library 2.0.0-alpha.19 → 2.0.0-alpha.20

package/src/hooks/use-media-query/use-media-query.stories.tsx

@@ -1,39 +1,99 @@
-import { Meta } from "@storybook/react-vite";
+import type { Meta } from "@storybook/react-vite";
 import { useMediaQuery } from "../use-media-query";
 
+/**
+ * Subscribes to a CSS media query and returns whether it currently
+ * matches. Powered by `useSyncExternalStore` so multiple subscribers
+ * stay in sync and updates fire from the native `change` event. SSR-safe:
+ * pass `defaultValue` to control what is returned during server render
+ * and on the first client render, which avoids hydration mismatches.
+ */
 const meta: Meta = {
   title: "hooks/useMediaQuery",
+  tags: ["beta"],
 };
 
 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)");
+/**
+ * Resize the preview to cross each breakpoint and watch the active row
+ * light up. Each row is an independent `useMediaQuery` subscription.
+ */
+export const Default = {
+  render: () => {
+    const breakpoints = [
+      { label: "Small", emoji: "📱", query: "(max-width: 768px)" },
+      {
+        label: "Medium",
+        emoji: "💻",
+        query: "(min-width: 769px) and (max-width: 992px)",
+      },
+      {
+        label: "Large",
+        emoji: "🖥️",
+        query: "(min-width: 993px) and (max-width: 1200px)",
+      },
+      { label: "Extra large", emoji: "🖥️", query: "(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)"}
+    return (
+      <div className="flex w-full max-w-sm flex-col gap-2">
+        {breakpoints.map((bp) => (
+          <BreakpointRow key={bp.query} {...bp} />
+        ))}
       </div>
+    );
+  },
+};
+
+function BreakpointRow({
+  label,
+  emoji,
+  query,
+}: {
+  label: string;
+  emoji: string;
+  query: string;
+}) {
+  const matches = useMediaQuery(query);
+
+  return (
+    <div
+      className={`flex items-center justify-between rounded-md border px-3 py-2 text-sm transition-colors ${
+        matches
+          ? "border-primary bg-primary/10 font-medium text-foreground"
+          : "border-input text-muted-foreground"
+      }`}
+    >
+      <span>
+        {emoji} {label}
+      </span>
+      <code className="text-xs">{query}</code>
     </div>
   );
+}
+
+/**
+ * Pass `defaultValue` to align the first render with whatever the
+ * server rendered. Common pattern for responsive layouts under SSR
+ * where the breakpoint is known from the request user-agent or a cookie.
+ *
+ * ```tsx
+ * const isMobile = useMediaQuery("(max-width: 768px)", {
+ *   defaultValue: serverIsMobile,
+ * });
+ * ```
+ */
+export const WithDefaultValue = {
+  render: () => {
+    const isMobile = useMediaQuery("(max-width: 768px)", {
+      defaultValue: true,
+    });
+
+    return (
+      <p className="text-sm">
+        Layout: <strong>{isMobile ? "mobile" : "desktop"}</strong>
+      </p>
+    );
+  },
 };

package/src/hooks/use-media-query/use-media-query.test.ts

@@ -0,0 +1,132 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useMediaQuery } from "./use-media-query";
+
+type Listener = (event: { matches: boolean }) => void;
+
+interface MockMediaQueryList {
+  matches: boolean;
+  addEventListener: ReturnType<typeof vi.fn>;
+  removeEventListener: ReturnType<typeof vi.fn>;
+  setMatches: (next: boolean) => void;
+}
+
+function createMockMatchMedia() {
+  const listeners = new Map<string, Set<Listener>>();
+  const states = new Map<string, MockMediaQueryList>();
+
+  const matchMedia = vi.fn((query: string): MockMediaQueryList => {
+    let state = states.get(query);
+    if (state) return state;
+
+    const queryListeners = new Set<Listener>();
+    listeners.set(query, queryListeners);
+
+    state = {
+      matches: false,
+      addEventListener: vi.fn((_type: string, listener: Listener) => {
+        queryListeners.add(listener);
+      }),
+      removeEventListener: vi.fn((_type: string, listener: Listener) => {
+        queryListeners.delete(listener);
+      }),
+      setMatches(next: boolean) {
+        if (this.matches === next) return;
+        this.matches = next;
+        for (const listener of queryListeners) {
+          listener({ matches: next });
+        }
+      },
+    };
+    states.set(query, state);
+    return state;
+  });
+
+  return {
+    matchMedia,
+    getState: (query: string) => states.get(query),
+  };
+}
+
+describe("useMediaQuery hook", () => {
+  let mock: ReturnType<typeof createMockMatchMedia>;
+
+  beforeEach(() => {
+    mock = createMockMatchMedia();
+    vi.stubGlobal("matchMedia", mock.matchMedia);
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      value: mock.matchMedia,
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns the initial `matches` value from matchMedia", () => {
+    const query = "(max-width: 768px)";
+    const { result } = renderHook(() => useMediaQuery(query));
+
+    expect(result.current).toBe(false);
+    expect(mock.matchMedia).toHaveBeenCalledWith(query);
+  });
+
+  it("reflects later changes to the match state", () => {
+    const query = "(max-width: 768px)";
+    const { result } = renderHook(() => useMediaQuery(query));
+
+    act(() => {
+      mock.getState(query)?.setMatches(true);
+    });
+
+    expect(result.current).toBe(true);
+
+    act(() => {
+      mock.getState(query)?.setMatches(false);
+    });
+
+    expect(result.current).toBe(false);
+  });
+
+  it("subscribes on mount and unsubscribes on unmount", () => {
+    const query = "(max-width: 768px)";
+    const { unmount } = renderHook(() => useMediaQuery(query));
+
+    const state = mock.getState(query);
+    expect(state?.addEventListener).toHaveBeenCalledTimes(1);
+
+    unmount();
+
+    expect(state?.removeEventListener).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-subscribes when the query changes", () => {
+    const { rerender } = renderHook(({ query }) => useMediaQuery(query), {
+      initialProps: { query: "(max-width: 768px)" },
+    });
+
+    rerender({ query: "(min-width: 1024px)" });
+
+    expect(
+      mock.getState("(max-width: 768px)")?.removeEventListener,
+    ).toHaveBeenCalled();
+    expect(
+      mock.getState("(min-width: 1024px)")?.addEventListener,
+    ).toHaveBeenCalled();
+  });
+
+  it("returns defaultValue when window.matchMedia is unavailable", () => {
+    vi.unstubAllGlobals();
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      value: undefined,
+    });
+
+    const { result } = renderHook(() =>
+      useMediaQuery("(max-width: 768px)", { defaultValue: true }),
+    );
+
+    expect(result.current).toBe(true);
+  });
+});

package/src/hooks/use-media-query/use-media-query.ts

@@ -1,20 +1,45 @@
-import { useEffect, useState } from "react";
+import { useCallback, useSyncExternalStore } from "react";
+import { isBrowser } from "../internal";
 
-export const useMediaQuery = (query: string): boolean => {
-  const [matches, setMatches] = useState<boolean>(false);
+export interface UseMediaQueryOptions {
+  /**
+   * Value returned during server render and on the first client render
+   * before `matchMedia` has been read. Use this to avoid hydration
+   * mismatches in SSR consumers that already know the breakpoint.
+   * @default false
+   */
+  defaultValue?: boolean;
+}
 
-  useEffect(() => {
-    const mediaQueryList = window.matchMedia(query);
-    const documentChangeHandler = () => setMatches(mediaQueryList.matches);
+function canMatch(): boolean {
+  return isBrowser && typeof window.matchMedia === "function";
+}
 
-    documentChangeHandler();
+export function useMediaQuery(
+  query: string,
+  options: UseMediaQueryOptions = {},
+): boolean {
+  const { defaultValue = false } = options;
 
-    mediaQueryList.addEventListener("change", documentChangeHandler);
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      if (!canMatch()) return () => {};
+      const mql = window.matchMedia(query);
+      mql.addEventListener("change", listener);
+      return () => mql.removeEventListener("change", listener);
+    },
+    [query],
+  );
 
-    return () => {
-      mediaQueryList.removeEventListener("change", documentChangeHandler);
-    };
-  }, [query]);
+  const getSnapshot = useCallback((): boolean => {
+    if (!canMatch()) return defaultValue;
+    return window.matchMedia(query).matches;
+  }, [query, defaultValue]);
 
-  return matches;
-};
+  const getServerSnapshot = useCallback(
+    (): boolean => defaultValue,
+    [defaultValue],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/hooks/use-memoized-fn/use-memoized-fn.ts

@@ -27,4 +27,3 @@ export function useMemoizedFn<T extends noop>(fn: T) {
 
   return memoizedFn.current as T;
 }
-