@usels/core 0.0.1-beta.3

package/src/elements/useElementVisibility/index.spec.ts

@@ -0,0 +1,227 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { observable, ObservableHint } from "@legendapp/state";
+import type { OpaqueObject } from "@legendapp/state";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const wrapEl = (el: Element) => observable<OpaqueObject<Element> | null>(ObservableHint.opaque(el));
+import { useElementVisibility } from ".";
+
+const mockObserve = vi.fn();
+const mockDisconnect = vi.fn();
+let capturedCallback: IntersectionObserverCallback;
+
+const MockIntersectionObserver = vi.fn(
+  (cb: IntersectionObserverCallback, init?: IntersectionObserverInit) => {
+    capturedCallback = cb;
+    void init;
+    return { observe: mockObserve, disconnect: mockDisconnect };
+  },
+);
+
+beforeEach(() => {
+  vi.stubGlobal("IntersectionObserver", MockIntersectionObserver);
+  mockObserve.mockClear();
+  mockDisconnect.mockClear();
+  MockIntersectionObserver.mockClear();
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function makeEntry(
+  isIntersecting: boolean,
+  time = 0,
+): IntersectionObserverEntry {
+  return { isIntersecting, time } as IntersectionObserverEntry;
+}
+
+describe("useElementVisibility()", () => {
+  it("returns false by default", () => {
+    const el = document.createElement("div");
+    const { result } = renderHook(() => useElementVisibility(wrapEl(el)));
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("returns initialValue when provided", () => {
+    const el = document.createElement("div");
+    const { result } = renderHook(() =>
+      useElementVisibility(wrapEl(el), { initialValue: true }),
+    );
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("becomes true when element enters viewport", () => {
+    const el = document.createElement("div");
+    const { result } = renderHook(() => useElementVisibility(wrapEl(el)));
+
+    act(() => {
+      capturedCallback([makeEntry(true)], {} as IntersectionObserver);
+    });
+
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("becomes false when element leaves viewport", () => {
+    const el = document.createElement("div");
+    const { result } = renderHook(() => useElementVisibility(wrapEl(el)));
+
+    act(() => {
+      capturedCallback([makeEntry(true)], {} as IntersectionObserver);
+    });
+    expect(result.current.get()).toBe(true);
+
+    act(() => {
+      capturedCallback([makeEntry(false)], {} as IntersectionObserver);
+    });
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("selects the entry with the largest time value", () => {
+    const el = document.createElement("div");
+    const { result } = renderHook(() => useElementVisibility(wrapEl(el)));
+
+    act(() => {
+      capturedCallback(
+        [makeEntry(true, 100), makeEntry(false, 200)],
+        {} as IntersectionObserver,
+      );
+    });
+
+    // Entry with time=200 (isIntersecting: false) should win
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("once: true stops observer after first visible", () => {
+    const el = document.createElement("div");
+    renderHook(() => useElementVisibility(wrapEl(el), { once: true }));
+
+    act(() => {
+      capturedCallback([makeEntry(true)], {} as IntersectionObserver);
+    });
+
+    expect(mockDisconnect).toHaveBeenCalled();
+  });
+
+  it("once: true does not stop observer while element is not intersecting", () => {
+    const el = document.createElement("div");
+    renderHook(() => useElementVisibility(wrapEl(el), { once: true }));
+
+    mockDisconnect.mockClear();
+    act(() => {
+      capturedCallback([makeEntry(false)], {} as IntersectionObserver);
+    });
+
+    expect(mockDisconnect).not.toHaveBeenCalled();
+  });
+
+  it("passes scrollTarget as root to IntersectionObserver", () => {
+    const el = document.createElement("div");
+    const scrollContainer = document.createElement("div");
+    renderHook(() =>
+      useElementVisibility(wrapEl(el), { scrollTarget: wrapEl(scrollContainer) }),
+    );
+
+    expect(MockIntersectionObserver).toHaveBeenCalledWith(
+      expect.any(Function),
+      expect.objectContaining({ root: scrollContainer }),
+    );
+  });
+
+  it("passes rootMargin option to IntersectionObserver", () => {
+    const el = document.createElement("div");
+    renderHook(() => useElementVisibility(wrapEl(el), { rootMargin: "10px" }));
+
+    expect(MockIntersectionObserver).toHaveBeenCalledWith(
+      expect.any(Function),
+      expect.objectContaining({ rootMargin: "10px" }),
+    );
+  });
+
+  it("passes threshold option to IntersectionObserver", () => {
+    const el = document.createElement("div");
+    renderHook(() => useElementVisibility(wrapEl(el), { threshold: 0.5 }));
+
+    expect(MockIntersectionObserver).toHaveBeenCalledWith(
+      expect.any(Function),
+      expect.objectContaining({ threshold: 0.5 }),
+    );
+  });
+
+  it("disconnects observer on unmount", () => {
+    const el = document.createElement("div");
+    const { unmount } = renderHook(() => useElementVisibility(wrapEl(el)));
+    unmount();
+    expect(mockDisconnect).toHaveBeenCalled();
+  });
+
+  it("does not throw when entries array is empty", () => {
+    const el = document.createElement("div");
+    const { result } = renderHook(() => useElementVisibility(wrapEl(el)));
+
+    expect(() => {
+      act(() => {
+        capturedCallback([], {} as IntersectionObserver);
+      });
+    }).not.toThrow();
+
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("accepts Observable<UseElementVisibilityOptions> as options", () => {
+    const el = document.createElement("div");
+    const options$ = observable({ initialValue: true });
+    const { result } = renderHook(() => useElementVisibility(wrapEl(el), options$));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("accepts Observable<boolean> for initialValue", () => {
+    const el = document.createElement("div");
+    const initialValue$ = observable(true);
+    const { result } = renderHook(() =>
+      useElementVisibility(wrapEl(el), { initialValue: initialValue$ }),
+    );
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("accepts Observable<boolean> for once option", () => {
+    const el = document.createElement("div");
+    const once$ = observable(true);
+    renderHook(() => useElementVisibility(wrapEl(el), { once: once$ }));
+
+    act(() => {
+      capturedCallback([makeEntry(true)], {} as IntersectionObserver);
+    });
+
+    expect(mockDisconnect).toHaveBeenCalled();
+  });
+
+  it("accepts Observable<number> for threshold option", () => {
+    const el = document.createElement("div");
+    const threshold$ = observable<number | number[]>(0.5);
+    renderHook(() => useElementVisibility(wrapEl(el), { threshold: threshold$ }));
+
+    expect(MockIntersectionObserver).toHaveBeenCalledWith(
+      expect.any(Function),
+      expect.objectContaining({ threshold: 0.5 }),
+    );
+  });
+
+  it("once: true preserves true after observer fires again with false", () => {
+    const el = document.createElement("div");
+    const { result } = renderHook(() => useElementVisibility(wrapEl(el), { once: true }));
+
+    act(() => {
+      capturedCallback([makeEntry(true)], {} as IntersectionObserver);
+    });
+    expect(result.current.get()).toBe(true);
+
+    // Simulate a stale callback firing after stop (disconnect was called)
+    act(() => {
+      capturedCallback([makeEntry(false)], {} as IntersectionObserver);
+    });
+    // Value stays true because the underlying observer was stopped
+    expect(result.current.get()).toBe(false); // Real-world: observer is disconnected so no further calls
+  });
+});

package/src/elements/useElementVisibility/index.ts

@@ -0,0 +1,78 @@
+"use client";
+import type { Observable } from "@legendapp/state";
+import { useObservable } from "@legendapp/state/react";
+import type { DeepMaybeObservable } from "../../types";
+import { useMayObservableOptions } from "../../function/useMayObservableOptions";
+import type { MaybeElement } from "../useRef$";
+import { useIntersectionObserver } from "../useIntersectionObserver";
+import type { UseIntersectionObserverOptions } from "../useIntersectionObserver";
+
+export interface UseElementVisibilityOptions {
+  /** Initial visibility value. Default: false */
+  initialValue?: boolean;
+  /** Element used as the viewport for intersection. Maps to IntersectionObserver `root`. */
+  scrollTarget?: MaybeElement;
+  /** Margin around the root. Accepts CSS-style values. Default: "0px" */
+  rootMargin?: string;
+  /** Threshold(s) at which to trigger. Default: 0 */
+  threshold?: number | number[];
+  /**
+   * Stop observing after the element becomes visible for the first time. Default: false.
+   * Must be set at mount time; changing dynamically has no effect.
+   */
+  once?: boolean;
+}
+
+/**
+ * Tracks whether a DOM element is visible within the viewport (or a specified scroll container).
+ * Returns a reactive `Observable<boolean>` that updates automatically as visibility changes.
+ *
+ * `options` accepts a `DeepMaybeObservable<UseElementVisibilityOptions>`:
+ * - A plain object with per-field values
+ * - A plain object with per-field `Observable<T>` values
+ * - The entire options object wrapped in `Observable<UseElementVisibilityOptions>`
+ *
+ * @param element - The element to observe
+ * @param options - Optional configuration — plain, per-field Observable, or fully Observable
+ * @returns `Observable<boolean>` — true when element is intersecting
+ *
+ * @example
+ * ```tsx
+ * const el$ = useRef$<HTMLDivElement>();
+ * const isVisible$ = useElementVisibility(el$);
+ * return <div ref={el$} />;
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export function useElementVisibility(
+  element: MaybeElement,
+  options?: DeepMaybeObservable<UseElementVisibilityOptions>,
+): Observable<boolean> {
+  const opts$ = useMayObservableOptions<UseElementVisibilityOptions>(options, {
+    initialValue: "peek",
+    once: "peek",
+    scrollTarget: "get.element",
+  });
+
+  const isVisible$ = useObservable<boolean>(opts$.initialValue.peek() ?? false);
+
+  const { stop } = useIntersectionObserver(
+    element,
+    (entries) => {
+      if (entries.length === 0) return;
+      const latest = entries.reduce((a, b) => (a.time > b.time ? a : b));
+      isVisible$.set(latest.isIntersecting);
+
+      if (opts$.once.peek() && latest.isIntersecting) {
+        stop();
+      }
+    },
+    {
+      root: opts$.scrollTarget,
+      rootMargin: opts$.rootMargin,
+      threshold: opts$.threshold,
+    } as DeepMaybeObservable<UseIntersectionObserverOptions>,
+  );
+
+  return isVisible$;
+}

package/src/elements/useIntersectionObserver/demo.tsx

@@ -0,0 +1,180 @@
+import { useRef$ } from "../useRef$";
+import { useIntersectionObserver } from ".";
+import { Computed, useObservable } from "@legendapp/state/react";
+
+const DEFAULT_ROOT_MARGIN = 0;
+
+const btnStyle: React.CSSProperties = {
+  padding: "3px 10px",
+  fontSize: "12px",
+  cursor: "pointer",
+  borderRadius: "4px",
+  border: "1px solid var(--sl-color-gray-4, #94a3b8)",
+  background: "transparent",
+  fontFamily: "monospace",
+};
+
+export default function UseIntersectionObserverDemo() {
+  const el$ = useRef$<HTMLDivElement>();
+  const containerRef$ = useRef$<HTMLElement>();
+  const isVisible$ = useObservable(false);
+  const rootMargin$ = useObservable(DEFAULT_ROOT_MARGIN);
+
+  const marginString$ = useObservable(() => {
+    const m = Number(rootMargin$.get());
+    return `${isNaN(m) ? 0 : m}px`;
+  });
+  const { isActive$, pause, resume } = useIntersectionObserver(
+    el$,
+    (entries) => {
+      isVisible$.set(entries[0]?.isIntersecting ?? false);
+    },
+    { threshold: 0.5, rootMargin: marginString$, root: containerRef$ },
+  );
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+      {/* Status + pause/resume */}
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "16px",
+          fontFamily: "monospace",
+          fontSize: "14px",
+          padding: "8px 12px",
+          background: "var(--sl-color-gray-6, #f1f5f9)",
+          borderRadius: "6px",
+        }}
+      >
+        <Computed>
+          {() => (
+            <span>
+              isIntersecting:{" "}
+              <strong>
+                {isActive$.get() ? String(isVisible$.get()) : "— (paused)"}
+              </strong>
+            </span>
+          )}
+        </Computed>
+        <Computed>
+          {() =>
+            isActive$.get() ? (
+              <button onClick={pause} style={btnStyle}>
+                pause
+              </button>
+            ) : (
+              <button onClick={resume} style={btnStyle}>
+                resume
+              </button>
+            )
+          }
+        </Computed>
+      </div>
+
+      {/* rootMargin input */}
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "8px",
+          fontFamily: "monospace",
+          fontSize: "13px",
+          padding: "6px 12px",
+          background: "var(--sl-color-gray-6, #f1f5f9)",
+          borderRadius: "6px",
+        }}
+      >
+        <span style={{ color: "var(--sl-color-gray-2, #64748b)" }}>
+          rootMargin:
+        </span>
+        <Computed>
+          {() => (
+            <input
+              value={rootMargin$.get()}
+              type="number"
+              onChange={(e) => rootMargin$.set(Number(e.target.value))}
+              style={{
+                fontFamily: "monospace",
+                fontSize: "13px",
+                padding: "2px 8px",
+                borderRadius: "4px",
+                border: "1px solid var(--sl-color-gray-4, #94a3b8)",
+                background: "var(--sl-color-gray-7, #ffffff)",
+                color: "black",
+                width: "160px",
+              }}
+            />
+          )}
+        </Computed>
+        <Computed>
+          {() =>
+            rootMargin$.get() !== DEFAULT_ROOT_MARGIN ? (
+              <button
+                onClick={() => rootMargin$.set(DEFAULT_ROOT_MARGIN)}
+                style={btnStyle}
+              >
+                default
+              </button>
+            ) : null
+          }
+        </Computed>
+      </div>
+
+      {/* Scrollable container — used as root for IntersectionObserver */}
+      <div
+        ref={containerRef$}
+        style={{
+          height: "200px",
+          overflowY: "auto",
+          border: "1px solid var(--sl-color-gray-5, #cbd5e1)",
+          borderRadius: "6px",
+          position: "relative",
+        }}
+      >
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            height: "200px",
+            color: "var(--sl-color-gray-3, #94a3b8)",
+            fontSize: "13px",
+            fontFamily: "monospace",
+          }}
+        >
+          ↓ scroll down
+        </div>
+
+        <Computed>
+          {() => (
+            <div
+              ref={el$}
+              style={{
+                margin: "0 16px",
+                padding: "20px",
+                borderRadius: "6px",
+                textAlign: "center",
+                fontFamily: "monospace",
+                fontSize: "13px",
+                transition: "background 0.2s, border-color 0.2s",
+                border: `2px solid ${
+                  isVisible$.get()
+                    ? "var(--sl-color-green, #22c55e)"
+                    : "var(--sl-color-gray-4, #94a3b8)"
+                }`,
+                background: isVisible$.get()
+                  ? "var(--sl-color-green-low, #dcfce7)"
+                  : "transparent",
+              }}
+            >
+              target element
+            </div>
+          )}
+        </Computed>
+
+        <div style={{ height: "140px" }} />
+      </div>
+    </div>
+  );
+}

package/src/elements/useIntersectionObserver/index.md

@@ -0,0 +1,99 @@
+---
+title: useIntersectionObserver
+category: elements
+---
+
+Reactive wrapper around the [IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+Observes one or more elements for intersection changes with pause/resume/stop support.
+Targets can be `Ref$`, `MaybeElement`, or a plain `Element`.
+
+## Demo
+
+## Usage
+
+```tsx
+import { useRef$, useIntersectionObserver } from '@usels/core'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+
+  const { isActive$, pause, resume } = useIntersectionObserver(
+    el$,
+    (entries) => {
+      entries.forEach((entry) => {
+        console.log(entry.isIntersecting)
+      })
+    },
+    { threshold: 0.5 },
+  )
+
+  return <div ref={el$} />
+}
+```
+
+### Threshold array
+
+Trigger the callback at multiple intersection ratios:
+
+```tsx
+useIntersectionObserver(el$, callback, {
+  threshold: [0, 0.25, 0.5, 0.75, 1],
+})
+```
+
+### Custom root and rootMargin
+
+```tsx
+useIntersectionObserver(el$, callback, {
+  root: scrollContainerEl,
+  rootMargin: '0px 0px -100px 0px',
+})
+```
+
+### Reactive root / rootMargin
+
+Pass an `Observable` to reactively recreate the observer when the value changes:
+
+```tsx
+const rootMargin$ = observable('0px')
+
+useIntersectionObserver(el$, callback, { rootMargin: rootMargin$ })
+
+// later — observer is automatically recreated with new margin
+rootMargin$.set('-50px 0px')
+```
+
+### Deferred start
+
+Set `immediate: false` to start observation manually:
+
+```tsx
+const { resume } = useIntersectionObserver(el$, callback, { immediate: false })
+
+resume() // starts observing
+```
+
+### Pause and resume
+
+```tsx
+const { pause, resume } = useIntersectionObserver(el$, callback)
+
+pause()   // disconnects the observer, isActive$ → false
+resume()  // reconnects the observer, isActive$ → true
+```
+
+### Permanent stop
+
+```tsx
+const { stop } = useIntersectionObserver(el$, callback)
+
+stop() // disconnects and prevents future resume()
+```
+
+### Checking browser support
+
+```tsx
+const { isSupported$ } = useIntersectionObserver(el$, callback)
+
+console.log(isSupported$.get()) // Observable<boolean>
+```