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

package/src/hooks/use-is-visible/use-is-visible.stories.tsx

@@ -1,60 +1,207 @@
-import { Meta, StoryObj } from "@storybook/react-vite";
-import { ArrowDown } from "lucide-react";
-import { ReactNode } from "react";
-import { createToastManager, ToastProvider } from "../../components/toast";
-import { useIsVisible } from "../use-is-visible";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useIsVisible } from "./use-is-visible";
 
-const toastManager = createToastManager();
+// ─── Demo component ────────────────────────────────────────────────────────────
+
+type IsVisibleDemoProps = {
+  onVisible?: () => void;
+  triggerOnce?: boolean;
+  freezeOnceVisible?: boolean;
+  threshold?: number;
+  rootMargin?: string;
+};
+
+const IsVisibleDemo = ({
+  onVisible,
+  triggerOnce = false,
+  freezeOnceVisible = false,
+  threshold = 0,
+  rootMargin = "0px",
+}: IsVisibleDemoProps) => {
+  const { ref, isVisible, entry } = useIsVisible<HTMLDivElement>({
+    onVisible,
+    triggerOnce,
+    freezeOnceVisible,
+    threshold,
+    rootMargin,
+  });
+
+  return (
+    <div className="flex flex-col gap-3 max-w-xs">
+      <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed">
+        {JSON.stringify(
+          {
+            isVisible,
+            "entry.isIntersecting": entry?.isIntersecting ?? null,
+            "entry.intersectionRatio": entry
+              ? +entry.intersectionRatio.toFixed(2)
+              : null,
+          },
+          null,
+          2,
+        )}
+      </pre>
+
+      <div className="h-48 overflow-y-auto border rounded-md">
+        <div className="flex flex-col" style={{ height: 480 }}>
+          <div className="flex-1 flex items-start pt-4 justify-center text-xs text-muted-foreground">
+            ↓ scroll down
+          </div>
+          <div
+            ref={ref}
+            className={`mx-2 mb-2 p-4 rounded text-center text-sm font-medium text-white transition-colors duration-500 ${
+              isVisible ? "bg-primary" : "bg-muted-foreground/60"
+            }`}
+          >
+            {isVisible ? "Visible" : "Not visible"}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
 
 /**
- * Hook que permite detectar si un elemento es visible para el usuario
+ * `useIsVisible` observes a DOM element with `IntersectionObserver` and reports
+ * whether it is intersecting the viewport (or a custom root).
+ *
+ * **API summary**
  *
- * Extiende la API de `IntersectionObserver`
+ * ```ts
+ * const { ref, isVisible, entry } = useIsVisible<T>({
+ *   onVisible?,         // () => void — stable, safe to pass inline
+ *   triggerOnce?,       // boolean — disconnect after first intersection (default false)
+ *   freezeOnceVisible?, // boolean — never reset isVisible to false (default false)
+ *   // IntersectionObserverInit options:
+ *   threshold?,         // number | number[] (default 0)
+ *   rootMargin?,        // string (default "0px")
+ *   root?,              // Element | Document | null (default null = viewport)
+ * });
+ * ```
+ *
+ * **Return**
+ *
+ * | Field | Type | Description |
+ * |-------|------|-------------|
+ * | `ref` | `RefObject<T \| null>` | Attach to the element you want to observe |
+ * | `isVisible` | `boolean` | `true` when the element intersects the root |
+ * | `entry` | `IntersectionObserverEntry \| null` | Latest raw entry, `null` until first event |
+ *
+ * **Key behaviors**
+ * - `onVisible` is stabilized via `useLatestRef` — inline callbacks never re-attach the observer.
+ * - `triggerOnce: true` — observer disconnects after the first positive intersection; `isVisible` latches permanently.
+ * - `freezeOnceVisible: true` — `isVisible` never resets; observer stays connected so `entry` keeps updating.
+ * - SSR-safe: the effect short-circuits when `IntersectionObserver` is unavailable.
  */
-const meta: Meta = {
+const meta: Meta<typeof IsVisibleDemo> = {
   title: "hooks/useIsVisible",
-  decorators: [
-    (Story) => (
-      <ToastProvider toastManager={toastManager}>
-        <Story />
-      </ToastProvider>
-    ),
-  ],
+  component: IsVisibleDemo,
+  argTypes: {
+    onVisible: {
+      action: "onVisible",
+      description:
+        "Called once when the observed element first becomes visible. Stable — safe to pass an inline function without causing observer re-attachment.",
+      table: {
+        category: "Hook options",
+        type: { summary: "() => void" },
+      },
+    },
+    triggerOnce: {
+      control: "boolean",
+      description:
+        "When true, the observer disconnects after the first positive intersection. `isVisible` latches to `true` permanently and never flips back.",
+      table: {
+        category: "Hook options",
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    freezeOnceVisible: {
+      control: "boolean",
+      description:
+        "When true, `isVisible` never resets to `false` once set. Unlike `triggerOnce`, the observer stays connected and `entry` continues updating on subsequent intersections.",
+      table: {
+        category: "Hook options",
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    threshold: {
+      control: { type: "range", min: 0, max: 1, step: 0.05 },
+      description:
+        "Fraction of the element that must be visible before an intersection fires. `0` = any pixel, `1` = fully visible.",
+      table: {
+        category: "Hook options",
+        type: { summary: "number | number[]" },
+        defaultValue: { summary: "0" },
+      },
+    },
+    rootMargin: {
+      control: "text",
+      description:
+        'Margin around the root (viewport by default). Expands or shrinks the detection area. CSS shorthand syntax, e.g. `"50px 0px"`.',
+      table: {
+        category: "Hook options",
+        type: { summary: "string" },
+        defaultValue: { summary: '"0px"' },
+      },
+    },
+  },
+  args: {
+    triggerOnce: false,
+    freezeOnceVisible: false,
+    threshold: 0,
+    rootMargin: "0px",
+  },
+  render: (args) => <IsVisibleDemo {...args} />,
 };
 
 export default meta;
+type Story = StoryObj<typeof IsVisibleDemo>;
 
-const Wrapper = ({ children }: { children: ReactNode }) => {
-  return (
-    <div className="h-[200px] border rounded overflow-y-scroll">{children}</div>
-  );
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+/**
+ * Scroll down inside the box to reveal the observed element. `isVisible`
+ * toggles as the element enters and leaves the viewport. `entry` updates on
+ * every intersection event. `onVisible` fires each time the element becomes
+ * visible (visible in the Actions tab).
+ */
+export const Default: Story = {};
+
+/**
+ * With `triggerOnce: true`, the observer disconnects after the first positive
+ * intersection. `isVisible` latches permanently to `true` — scrolling back up
+ * does not reset it and `onVisible` never fires a second time.
+ */
+export const TriggerOnce: Story = {
+  args: {
+    triggerOnce: true,
+  },
 };
-export const Default: StoryObj = {
-  render: () => {
-    const { ref, isVisible } = useIsVisible<HTMLDivElement>({
-      onVisible: () =>
-        toastManager.add({
-          variant: "success",
-          description: "El elemento es visible",
-        }),
-    });
-
-    return (
-      <>
-        <div className="flex items-center gap-x-2">
-          <span>Scroll</span>
-          <ArrowDown className="animate-bounce" />
-        </div>
 
-        <Wrapper>
-          <div
-            ref={ref}
-            className={`transition-colors p-2 rounded text-primary-foreground duration-1000 mt-[400px] ${isVisible ? "bg-primary" : "bg-error"}`}
-          >
-            {isVisible ? "El elemento es visible" : "El elemento no es visible"}
-          </div>
-        </Wrapper>
-      </>
-    );
+/**
+ * With `freezeOnceVisible: true`, `isVisible` never returns to `false` once
+ * set. The observer stays connected — scroll up and down after the first
+ * intersection to see `entry.intersectionRatio` still updating while
+ * `isVisible` remains `true`.
+ */
+export const FreezeOnceVisible: Story = {
+  args: {
+    freezeOnceVisible: true,
+  },
+};
+
+/**
+ * `threshold: 0.5` requires 50% of the element to be visible before
+ * `isVisible` becomes `true`. Adjust the **threshold** slider in controls to
+ * shift the intersection boundary. Watch `entry.intersectionRatio` update in
+ * real time as you scroll.
+ */
+export const WithThreshold: Story = {
+  args: {
+    threshold: 0.5,
   },
 };

package/src/hooks/use-is-visible/use-is-visible.test.tsx

@@ -7,14 +7,19 @@ type ObserverCallback = IntersectionObserverCallback;
 
 let observerCallback: ObserverCallback | null = null;
 let observedEl: Element | null = null;
+let observerInit: IntersectionObserverInit | undefined = undefined;
+let constructorCallCount = 0;
 
 class IntersectionObserverMock implements IntersectionObserver {
   readonly root = null;
   readonly rootMargin = "0px";
   readonly thresholds = [0];
 
-  constructor(cb: ObserverCallback) {
+  constructor(cb: ObserverCallback, init?: IntersectionObserverInit) {
     observerCallback = cb;
+    observerInit = init;
+    constructorCallCount++;
+    observedEl = null;
   }
 
   observe(el: Element) {
@@ -37,10 +42,30 @@ function makeEntry(isIntersecting: boolean): IntersectionObserverEntry {
 
 function Fixture({
   onVisible,
+  triggerOnce,
+  freezeOnceVisible,
+  rootMargin,
+  threshold,
+  onRender,
 }: {
   onVisible?: () => void;
+  triggerOnce?: boolean;
+  freezeOnceVisible?: boolean;
+  rootMargin?: string;
+  threshold?: number;
+  onRender?: (result: {
+    isVisible: boolean;
+    entry: IntersectionObserverEntry | null;
+  }) => void;
 }) {
-  const { ref, isVisible } = useIsVisible<HTMLDivElement>({ onVisible });
+  const { ref, isVisible, entry } = useIsVisible<HTMLDivElement>({
+    onVisible,
+    triggerOnce,
+    freezeOnceVisible,
+    rootMargin,
+    threshold,
+  });
+  onRender?.({ isVisible, entry });
   return (
     <div ref={ref} data-testid="target">
       {isVisible ? "visible" : "hidden"}
@@ -49,6 +74,13 @@ function Fixture({
 }
 
 describe("useIsVisible", () => {
+  beforeEach(() => {
+    constructorCallCount = 0;
+    observerInit = undefined;
+    observerCallback = null;
+    observedEl = null;
+  });
+
   it("starts as hidden", () => {
     render(<Fixture />);
     expect(screen.getByTestId("target")).toHaveTextContent("hidden");
@@ -109,10 +141,11 @@ describe("useIsVisible", () => {
     expect(observedEl).not.toBeNull();
   });
 
-  it("calls unobserve when observer options change (cleanup while mounted)", () => {
-    const unobserveSpy = vi.spyOn(
+  // T-02: updated to assert disconnect instead of unobserve
+  it("calls disconnect when observer options change (cleanup while mounted)", () => {
+    const disconnectSpy = vi.spyOn(
       IntersectionObserverMock.prototype,
-      "unobserve",
+      "disconnect",
     );
 
     function Resettable({ margin }: { margin: string }) {
@@ -129,7 +162,202 @@ describe("useIsVisible", () => {
     const { rerender } = render(<Resettable margin="0px" />);
     rerender(<Resettable margin="10px" />);
 
-    expect(unobserveSpy).toHaveBeenCalled();
-    unobserveSpy.mockRestore();
+    expect(disconnectSpy).toHaveBeenCalled();
+    disconnectSpy.mockRestore();
+  });
+
+  // T-03: entry exposed and matches received entry
+  describe("entry", () => {
+    it("starts as null", () => {
+      let capturedEntry: IntersectionObserverEntry | null | undefined =
+        undefined;
+      render(
+        <Fixture
+          onRender={({ entry }) => {
+            capturedEntry = entry;
+          }}
+        />,
+      );
+      expect(capturedEntry).toBeNull();
+    });
+
+    it("reflects the received IntersectionObserverEntry after intersection fires", () => {
+      let capturedEntry: IntersectionObserverEntry | null | undefined =
+        undefined;
+      render(
+        <Fixture
+          onRender={({ entry }) => {
+            capturedEntry = entry;
+          }}
+        />,
+      );
+
+      const entry = makeEntry(true);
+      act(() => {
+        observerCallback?.([entry], {} as IntersectionObserver);
+      });
+
+      expect(capturedEntry).toBe(entry);
+    });
+
+    it("updates entry on negative intersection", () => {
+      let capturedEntry: IntersectionObserverEntry | null | undefined =
+        undefined;
+      render(
+        <Fixture
+          onRender={({ entry }) => {
+            capturedEntry = entry;
+          }}
+        />,
+      );
+
+      act(() => {
+        observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+      });
+
+      const negEntry = makeEntry(false);
+      act(() => {
+        observerCallback?.([negEntry], {} as IntersectionObserver);
+      });
+
+      expect(capturedEntry).toBe(negEntry);
+    });
+  });
+
+  // T-04: triggerOnce behavior
+  describe("triggerOnce", () => {
+    it("isVisible stays true after element leaves viewport", () => {
+      render(<Fixture triggerOnce={true} />);
+
+      act(() => {
+        observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+      });
+      expect(screen.getByTestId("target")).toHaveTextContent("visible");
+
+      act(() => {
+        observerCallback?.([makeEntry(false)], {} as IntersectionObserver);
+      });
+      expect(screen.getByTestId("target")).toHaveTextContent("visible");
+    });
+
+    it("observer is disconnected after first positive intersection", () => {
+      const disconnectSpy = vi.spyOn(
+        IntersectionObserverMock.prototype,
+        "disconnect",
+      );
+
+      render(<Fixture triggerOnce={true} />);
+
+      act(() => {
+        observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+      });
+
+      expect(disconnectSpy).toHaveBeenCalledTimes(1);
+      disconnectSpy.mockRestore();
+    });
+  });
+
+  // T-05: freezeOnceVisible behavior
+  describe("freezeOnceVisible", () => {
+    it("isVisible stays true after element leaves viewport", () => {
+      render(<Fixture freezeOnceVisible={true} />);
+
+      act(() => {
+        observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+      });
+      expect(screen.getByTestId("target")).toHaveTextContent("visible");
+
+      act(() => {
+        observerCallback?.([makeEntry(false)], {} as IntersectionObserver);
+      });
+      expect(screen.getByTestId("target")).toHaveTextContent("visible");
+    });
+  });
+
+  // T-06: stable onVisible — no re-attach on re-render
+  it("does not re-attach observer when onVisible changes reference", () => {
+    constructorCallCount = 0;
+
+    function StableFixture({ onVisible }: { onVisible: () => void }) {
+      const { ref } = useIsVisible<HTMLDivElement>({ onVisible });
+      return <div ref={ref} data-testid="stable-target" />;
+    }
+
+    const { rerender } = render(<StableFixture onVisible={() => {}} />);
+    rerender(<StableFixture onVisible={() => {}} />);
+    rerender(<StableFixture onVisible={() => {}} />);
+
+    expect(constructorCallCount).toBe(1);
+  });
+
+  // T-07: onVisible not called on negative intersection (stable-ref test)
+  it("does not call a newly-referenced onVisible on negative intersection", () => {
+    const firstMock = vi.fn();
+
+    function DynamicFixture({ onVisible }: { onVisible: () => void }) {
+      const { ref } = useIsVisible<HTMLDivElement>({ onVisible });
+      return <div ref={ref} data-testid="dynamic-target" />;
+    }
+
+    const { rerender } = render(<DynamicFixture onVisible={firstMock} />);
+
+    act(() => {
+      observerCallback?.([makeEntry(true)], {} as IntersectionObserver);
+    });
+    firstMock.mockClear();
+
+    const secondMock = vi.fn();
+    rerender(<DynamicFixture onVisible={secondMock} />);
+
+    act(() => {
+      observerCallback?.([makeEntry(false)], {} as IntersectionObserver);
+    });
+
+    expect(secondMock).not.toHaveBeenCalled();
+  });
+
+  // T-08: SSR safety
+  describe("SSR safety", () => {
+    afterEach(() => {
+      vi.stubGlobal("IntersectionObserver", IntersectionObserverMock);
+    });
+
+    it("does not throw when IntersectionObserver is undefined (SSR)", () => {
+      vi.stubGlobal("IntersectionObserver", undefined);
+
+      function SSRFixture() {
+        const { ref, isVisible } = useIsVisible<HTMLDivElement>();
+        return (
+          <div ref={ref} data-testid="ssr-target">
+            {isVisible ? "visible" : "hidden"}
+          </div>
+        );
+      }
+
+      expect(() => render(<SSRFixture />)).not.toThrow();
+      expect(screen.getByTestId("ssr-target")).toHaveTextContent("hidden");
+    });
+  });
+
+  // T-09: IntersectionObserver options forwarded to constructor
+  it("forwards root, rootMargin, and threshold to IntersectionObserver constructor", () => {
+    render(<Fixture rootMargin="50px" threshold={0.5} />);
+
+    expect(observerInit?.rootMargin).toBe("50px");
+    expect(observerInit?.threshold).toBe(0.5);
+  });
+
+  // T-10: cleanup on unmount is distinct from options-change cleanup
+  it("calls disconnect on unmount (no prior options change)", () => {
+    const disconnectSpy = vi.spyOn(
+      IntersectionObserverMock.prototype,
+      "disconnect",
+    );
+
+    const { unmount } = render(<Fixture />);
+    unmount();
+
+    expect(disconnectSpy).toHaveBeenCalledTimes(1);
+    disconnectSpy.mockRestore();
   });
 });

package/src/hooks/use-is-visible/use-is-visible.ts

@@ -0,0 +1,114 @@
+import type { RefObject } from "react";
+import { useEffect, useRef, useState } from "react";
+import { isBrowser } from "../internal/is-browser";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+export interface UseIsVisibleOptions extends IntersectionObserverInit {
+  /**
+   * Called once when the element first becomes visible.
+   * Stable — safe to pass an inline arrow function without causing observer re-attachment.
+   */
+  onVisible?: () => void;
+  /**
+   * When true, the IntersectionObserver disconnects after the first positive intersection.
+   * `isVisible` latches to `true` and never flips back to `false`.
+   * The observer lifecycle is torn down early; no further intersection callbacks fire.
+   */
+  triggerOnce?: boolean;
+  /**
+   * When true, once `isVisible` becomes `true` it is never reset to `false`.
+   * The observer stays connected (unlike `triggerOnce`), so `entry` may continue updating.
+   */
+  freezeOnceVisible?: boolean;
+}
+
+export interface UseIsVisibleReturn<T extends HTMLElement> {
+  /** Attach to the DOM element you want to observe. */
+  ref: RefObject<T | null>;
+  /**
+   * True when the observed element is intersecting the viewport (or root).
+   * Stays true permanently when `triggerOnce` or `freezeOnceVisible` has triggered.
+   */
+  isVisible: boolean;
+  /**
+   * The latest IntersectionObserverEntry received.
+   * `null` until the first intersection event fires.
+   */
+  entry: IntersectionObserverEntry | null;
+}
+
+export function useIsVisible<T extends HTMLElement>(
+  options: UseIsVisibleOptions = {},
+): UseIsVisibleReturn<T> {
+  const {
+    onVisible,
+    triggerOnce = false,
+    freezeOnceVisible = false,
+    root = null,
+    rootMargin = "0px",
+    threshold = 0,
+  } = options;
+
+  const ref = useRef<T | null>(null);
+  const [isVisible, setIsVisible] = useState(false);
+  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
+
+  // AD-2: stable callback ref — inline onVisible never re-attaches the observer
+  const onVisibleRef = useLatestRef(onVisible);
+
+  // AD-3: guards triggerOnce against double-disconnect / late callbacks
+  const hasTriggeredRef = useRef(false);
+
+  useEffect(() => {
+    // AD-4: SSR guard at the top of the effect body
+    // Also guard against environments where IntersectionObserver may be undefined
+    // even when window is available (e.g. jsdom tests that stub it to undefined).
+    if (!isBrowser || typeof IntersectionObserver === "undefined") return;
+
+    const el = ref.current;
+    if (el == null) return;
+
+    // fresh observer per effect run → reset the trigger latch
+    hasTriggeredRef.current = false;
+
+    const observer = new IntersectionObserver(
+      ([nextEntry]) => {
+        // AD-3: ignore any callback that lands after triggerOnce teardown
+        if (hasTriggeredRef.current) return;
+        if (!nextEntry) return;
+
+        const intersecting = nextEntry.isIntersecting;
+
+        // entry always tracks the latest observed entry
+        setEntry(nextEntry);
+
+        // AD-3 freezeOnceVisible: once visible, never write false again
+        setIsVisible((prev) =>
+          freezeOnceVisible && prev ? true : intersecting,
+        );
+
+        if (intersecting) {
+          // AD-1/AD-2: fire the stable callback synchronously
+          onVisibleRef.current?.();
+
+          // AD-3 triggerOnce: tear down early, latch the guard
+          if (triggerOnce) {
+            hasTriggeredRef.current = true;
+            observer.disconnect();
+          }
+        }
+      },
+      { root, rootMargin, threshold },
+    );
+
+    observer.observe(el);
+
+    return () => {
+      // AD-3: skip redundant teardown if triggerOnce already disconnected
+      if (hasTriggeredRef.current) return;
+      observer.disconnect();
+    };
+  }, [root, rootMargin, threshold, triggerOnce, freezeOnceVisible]);
+
+  return { ref, isVisible, entry };
+}