@usels/core 0.0.1-beta.3

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

@@ -0,0 +1,312 @@
+// @vitest-environment jsdom
+import { renderHook, act } 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";
+import { useRef$ } from "../useRef$";
+import { useResizeObserver } from ".";
+
+const wrapEl = (el: Element) => observable<OpaqueObject<Element> | null>(ObservableHint.opaque(el));
+
+// ---------------------------------------------------------------------------
+// ResizeObserver mock
+// ---------------------------------------------------------------------------
+
+type ResizeObserverMockEntry = {
+  target: Element;
+  contentRect: DOMRectReadOnly;
+};
+
+class ResizeObserverMock {
+  static instances: ResizeObserverMock[] = [];
+
+  callback: ResizeObserverCallback;
+  observed: Element[] = [];
+  disconnected = false;
+
+  constructor(cb: ResizeObserverCallback) {
+    this.callback = cb;
+    ResizeObserverMock.instances.push(this);
+  }
+
+  observe(el: Element) {
+    this.observed.push(el);
+  }
+
+  unobserve(el: Element) {
+    this.observed = this.observed.filter((e) => e !== el);
+  }
+
+  disconnect() {
+    this.disconnected = true;
+    this.observed = [];
+  }
+
+  /** Helper: trigger the callback with a fake entry for the given element */
+  trigger(el: Element, rect: Partial<DOMRectReadOnly> = {}) {
+    if (this.disconnected) return;
+    const entry = {
+      target: el,
+      contentRect: { width: 100, height: 100, ...rect } as DOMRectReadOnly,
+      borderBoxSize: [],
+      contentBoxSize: [],
+      devicePixelContentBoxSize: [],
+    } as unknown as ResizeObserverEntry;
+    this.callback([entry], this);
+  }
+}
+
+beforeEach(() => {
+  ResizeObserverMock.instances = [];
+  vi.stubGlobal("ResizeObserver", ResizeObserverMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// ---------------------------------------------------------------------------
+// useResizeObserver
+// ---------------------------------------------------------------------------
+
+describe("useResizeObserver()", () => {
+  it("calls callback when element resizes", () => {
+    const div = document.createElement("div");
+    const cb = vi.fn();
+
+    renderHook(() => useResizeObserver(wrapEl(div), cb));
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() => instance.trigger(div));
+
+    expect(cb).toHaveBeenCalledOnce();
+  });
+
+  it("observes multiple elements from an array", () => {
+    const a = document.createElement("div");
+    const b = document.createElement("span");
+    const cb = vi.fn();
+
+    renderHook(() => useResizeObserver([wrapEl(a), wrapEl(b)], cb));
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    expect(instance.observed).toContain(a);
+    expect(instance.observed).toContain(b);
+  });
+
+  it("stop() disconnects the observer and suppresses further callbacks", () => {
+    const div = document.createElement("div");
+    const cb = vi.fn();
+
+    const { result } = renderHook(() => useResizeObserver(wrapEl(div), cb));
+
+    act(() => result.current.stop());
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    expect(instance.disconnected).toBe(true);
+    act(() => instance.trigger(div));
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  it("passes box option to observe()", () => {
+    const div = document.createElement("div");
+    const observeSpy = vi.spyOn(ResizeObserverMock.prototype, "observe");
+
+    renderHook(() =>
+      useResizeObserver(wrapEl(div), vi.fn(), { box: "border-box" })
+    );
+
+    expect(observeSpy).toHaveBeenCalledWith(div, { box: "border-box" });
+  });
+
+  it("returns isSupported: true when ResizeObserver is available", () => {
+    const div = document.createElement("div");
+    const { result } = renderHook(() => useResizeObserver(wrapEl(div), vi.fn()));
+    expect(result.current.isSupported$.get()).toBe(true);
+  });
+
+  it("returns isSupported: false and skips setup when ResizeObserver is unavailable", () => {
+    vi.stubGlobal("ResizeObserver", undefined);
+
+    const div = document.createElement("div");
+    const cb = vi.fn();
+    const { result } = renderHook(() => useResizeObserver(wrapEl(div), cb));
+
+    expect(result.current.isSupported$.get()).toBe(false);
+    expect(ResizeObserverMock.instances).toHaveLength(0);
+  });
+
+  it("reacts to Ref$ target — starts observing after element is assigned", () => {
+    const cb = vi.fn();
+
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLDivElement>();
+      const ro = useResizeObserver(el$, cb);
+      return { el$, ro };
+    });
+
+    // Before element assigned — no active observer yet
+    const instancesBefore = ResizeObserverMock.instances.filter(
+      (i) => !i.disconnected && i.observed.length > 0
+    );
+    expect(instancesBefore).toHaveLength(0);
+
+    const div = document.createElement("div");
+    act(() => result.current.el$(div));
+
+    // After element assigned — observer should be active
+    const activeInstance = ResizeObserverMock.instances.find(
+      (i) => i.observed.includes(div)
+    );
+    expect(activeInstance).toBeDefined();
+  });
+
+  it("reacts to Observable<Element|null> target — starts observing after value is set", () => {
+    const target$ = observable<Element | null>(null);
+    const cb = vi.fn();
+
+    renderHook(() => useResizeObserver(target$ as any, cb));
+
+    // Initially null — no active observer with observed elements
+    const instancesWithObserved = ResizeObserverMock.instances.filter(
+      (i) => i.observed.length > 0
+    );
+    expect(instancesWithObserved).toHaveLength(0);
+
+    const div = document.createElement("div");
+    act(() => {
+      target$.set(div);
+    });
+
+    // After setting element, observer should be active
+    const activeInstance = ResizeObserverMock.instances.find(
+      (i) => i.observed.includes(div)
+    );
+    expect(activeInstance).toBeDefined();
+  });
+
+  it("handles mixed array of Ref$, Observable, and plain Element", () => {
+    const plainEl = document.createElement("section");
+    const obsEl = document.createElement("span");
+    const el$El = document.createElement("p");
+    const target$ = observable<Element | null>(obsEl);
+
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLParagraphElement>();
+      const ro = useResizeObserver([el$ as any, target$ as any, plainEl], vi.fn());
+      return { el$, ro };
+    });
+
+    // After mount: plainEl and obsEl observed, el$ not yet assigned
+    let instance = ResizeObserverMock.instances.at(-1)!;
+    expect(instance.observed).toContain(plainEl);
+    expect(instance.observed).toContain(obsEl);
+    expect(instance.observed).not.toContain(el$El);
+
+    // Assign Ref$ element
+    act(() => result.current.el$(el$El));
+
+    // After Ref$ assigned, all three observed
+    instance = ResizeObserverMock.instances.at(-1)!;
+    expect(instance.observed).toContain(el$El);
+    expect(instance.observed).toContain(obsEl);
+    expect(instance.observed).toContain(plainEl);
+  });
+
+  it("disconnects the active observer on unmount", () => {
+    const div = document.createElement("div");
+    const { unmount } = renderHook(() => useResizeObserver(wrapEl(div), vi.fn()));
+
+    const activeInstance = ResizeObserverMock.instances.at(-1)!;
+    expect(activeInstance.disconnected).toBe(false);
+
+    unmount();
+
+    expect(activeInstance.disconnected).toBe(true);
+  });
+
+  it("does not create an observer when target is an empty array", () => {
+    renderHook(() => useResizeObserver([], vi.fn()));
+
+    const activeInstances = ResizeObserverMock.instances.filter(
+      (i) => i.observed.length > 0,
+    );
+    expect(activeInstances).toHaveLength(0);
+  });
+
+  it("does not create an observer when target is null", () => {
+    renderHook(() => useResizeObserver(null as any, vi.fn()));
+
+    const activeInstances = ResizeObserverMock.instances.filter(
+      (i) => i.observed.length > 0,
+    );
+    expect(activeInstances).toHaveLength(0);
+  });
+
+  it("stops observing old element and observes new element when Ref$ target changes", () => {
+    const elA = document.createElement("div");
+    const elB = document.createElement("div");
+    const cb = vi.fn();
+
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLDivElement>();
+      return { el$, ro: useResizeObserver(el$ as any, cb) };
+    });
+
+    // Assign elA first
+    act(() => result.current.el$(elA));
+
+    expect(
+      ResizeObserverMock.instances.find((i) => !i.disconnected && i.observed.includes(elA)),
+    ).toBeDefined();
+
+    // Switch to elB
+    act(() => result.current.el$(elB));
+
+    // elB should now be observed
+    expect(
+      ResizeObserverMock.instances.find((i) => !i.disconnected && i.observed.includes(elB)),
+    ).toBeDefined();
+
+    // elA should no longer be observed by any active instance
+    expect(
+      ResizeObserverMock.instances.find((i) => !i.disconnected && i.observed.includes(elA)),
+    ).toBeUndefined();
+  });
+
+  it("uses the latest callback without recreating the observer on re-render", () => {
+    const div = document.createElement("div");
+    const cb1 = vi.fn();
+    const cb2 = vi.fn();
+
+    const { rerender } = renderHook(
+      ({ cb }) => useResizeObserver(wrapEl(div), cb),
+      { initialProps: { cb: cb1 } },
+    );
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+
+    rerender({ cb: cb2 });
+
+    // Observer must NOT be recreated — same instance as before
+    expect(ResizeObserverMock.instances.at(-1)).toBe(instance);
+
+    // Triggering should invoke the latest callback (cb2), not the stale one (cb1)
+    act(() => instance.trigger(div));
+    expect(cb1).not.toHaveBeenCalled();
+    expect(cb2).toHaveBeenCalledOnce();
+  });
+
+  it("passes device-pixel-content-box box option to observe()", () => {
+    const div = document.createElement("div");
+    const observeSpy = vi.spyOn(ResizeObserverMock.prototype, "observe");
+
+    renderHook(() =>
+      useResizeObserver(wrapEl(div), vi.fn(), { box: "device-pixel-content-box" }),
+    );
+
+    expect(observeSpy).toHaveBeenCalledWith(div, {
+      box: "device-pixel-content-box",
+    });
+  });
+});

package/src/elements/useResizeObserver/index.ts

@@ -0,0 +1,106 @@
+import type { Observable } from "@legendapp/state";
+import { useObservable, useObserve } from "@legendapp/state/react";
+import { useEffect, useRef } from "react";
+import { normalizeTargets } from "../../shared/normalizeTargets";
+import { MaybeElement } from "../useRef$";
+
+export { normalizeTargets } from "../../shared/normalizeTargets";
+
+export interface UseResizeObserverOptions {
+  box?: "content-box" | "border-box" | "device-pixel-content-box";
+}
+
+export interface UseResizeObserverReturn {
+  isSupported$: Observable<boolean>;
+  stop: () => void;
+}
+
+/**
+ * Observes one or more elements for size changes using the ResizeObserver API.
+ *
+ * @param target - Element(s) to observe: Ref$, Observable<Element|null>, plain Element, or an array
+ * @param callback - ResizeObserver callback. Wrap in `useCallback` to avoid stale closures —
+ *   the observer is only recreated when targets change, not on every render.
+ * @param options - Optional box model option. Note: dynamic `box` changes are not reactively
+ *   tracked; remount the hook or change a tracked target to pick up a new box value.
+ * @returns `{ isSupported$, stop }` — reactive support flag and manual stop function
+ *
+ * @example
+ * ```tsx
+ * const el$ = useRef$<HTMLDivElement>();
+ * const handleResize = useCallback<ResizeObserverCallback>((entries) => {
+ *   const { width, height } = entries[0].contentRect;
+ *   width$.set(width);
+ * }, []);
+ * useResizeObserver(el$, handleResize);
+ * return <div ref={el$} />;
+ * ```
+ */
+export function useResizeObserver(
+  target: MaybeElement | MaybeElement[],
+  callback: ResizeObserverCallback,
+  options?: UseResizeObserverOptions,
+): UseResizeObserverReturn {
+  const isSupported$ = useObservable<boolean>(
+    typeof ResizeObserver !== "undefined",
+  );
+  const observerRef = useRef<ResizeObserver | null>(null);
+
+  // Always use the latest callback without recreating the observer on every render.
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  // Always use the latest options in setup() without reactive tracking.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  // Guards useObserve's initial synchronous run (before DOM is committed) from
+  // calling setup(). Only useMount triggers the first setup, ensuring elements
+  // are available in the DOM before observation begins.
+  const mountedRef = useRef(false);
+
+  const cleanup = () => {
+    observerRef.current?.disconnect();
+    observerRef.current = null;
+  };
+
+  const setup = () => {
+    if (!isSupported$.peek()) return;
+    cleanup();
+
+    const targets = normalizeTargets(target);
+    if (!targets.length) return;
+
+    observerRef.current = new ResizeObserver((...args) =>
+      callbackRef.current(...args),
+    );
+    targets.forEach((el) => {
+      observerRef.current!.observe(el, { box: optionsRef.current?.box });
+    });
+  };
+
+  // Initial setup after DOM is committed; cleanup on unmount.
+  // useEffect is used directly (instead of useMount/useUnmount) because
+  // Legend-State's useEffectOnce delays cleanup via queueMicrotask in test
+  // environments, making synchronous post-unmount assertions unreliable.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    mountedRef.current = true;
+    setup();
+    return () => {
+      mountedRef.current = false;
+      cleanup();
+    };
+  }, []);
+
+  // Re-run setup whenever observable targets (Ref$ or Observable<Element>) change.
+  // Reading normalizeTargets(target) here registers observable dependencies so
+  // useObserve re-fires when a tracked target value changes.
+  // mountedRef guard prevents a redundant setup on the initial synchronous run.
+  useObserve(() => {
+    normalizeTargets(target);
+    if (mountedRef.current) setup();
+  });
+
+  return { isSupported$, stop: cleanup };
+}

package/src/elements/useWindowFocus/demo.tsx

@@ -0,0 +1,71 @@
+import { useWindowFocus } from ".";
+
+const dot: React.CSSProperties = {
+  display: "inline-block",
+  width: "8px",
+  height: "8px",
+  borderRadius: "50%",
+  marginRight: "6px",
+  verticalAlign: "middle",
+};
+
+export default function UseWindowFocusDemo() {
+  const focused$ = useWindowFocus();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "10px",
+        fontFamily: "monospace",
+        fontSize: "13px",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          padding: "10px 14px",
+          borderRadius: "6px",
+          border: `1px solid ${focused$.get() ? "var(--sl-color-green, #22c55e)" : "var(--sl-color-gray-4, #94a3b8)"}`,
+          background: focused$.get()
+            ? "var(--sl-color-green-low, #f0fdf4)"
+            : "var(--sl-color-gray-6, #f8fafc)",
+          transition: "border-color 0.2s, background 0.2s",
+        }}
+      >
+        <span
+          style={{
+            ...dot,
+            background: focused$.get()
+              ? "var(--sl-color-green, #22c55e)"
+              : "var(--sl-color-gray-4, #94a3b8)",
+          }}
+        />
+        <span>
+          focused$.get() ={" "}
+          <strong
+            style={{
+              color: focused$.get()
+                ? "var(--sl-color-green, #22c55e)"
+                : "var(--sl-color-gray-3, #64748b)",
+            }}
+          >
+            {String(focused$.get())}
+          </strong>
+        </span>
+      </div>
+
+      <p
+        style={{
+          margin: 0,
+          fontSize: "11px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+        }}
+      >
+        Click outside this window or switch tabs to see the value change.
+      </p>
+    </div>
+  );
+}

package/src/elements/useWindowFocus/index.md

@@ -0,0 +1,35 @@
+---
+title: useWindowFocus
+category: elements
+---
+
+Tracks whether the browser window currently has focus as a reactive `Observable<boolean>`.
+Updates automatically when the user switches tabs, clicks away, or returns to the window.
+SSR-safe: returns `false` when `document` is not available.
+
+## Demo
+
+## Usage
+
+```tsx
+import { useWindowFocus } from '@usels/core'
+
+function Component() {
+  const focused$ = useWindowFocus()
+
+  return (
+    <p>Window is {focused$.get() ? 'focused' : 'blurred'}</p>
+  )
+}
+```
+
+### Pausing work when the window loses focus
+
+```tsx
+const focused$ = useWindowFocus()
+
+useObserve(() => {
+  if (!focused$.get()) pausePolling()
+  else resumePolling()
+})
+```

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

@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+import { renderHook, act } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { useWindowFocus } from ".";
+
+const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve));
+
+describe("useWindowFocus()", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns an Observable", () => {
+    const { result } = renderHook(() => useWindowFocus());
+    expect(typeof result.current.get).toBe("function");
+    expect(typeof result.current.set).toBe("function");
+  });
+
+  it("initial value reflects document.hasFocus()", () => {
+    const hasFocusSpy = vi.spyOn(document, "hasFocus").mockReturnValue(true);
+    const { result } = renderHook(() => useWindowFocus());
+    expect(result.current.get()).toBe(true);
+    hasFocusSpy.mockRestore();
+  });
+
+  it("initial value is false when document.hasFocus() returns false", () => {
+    const hasFocusSpy = vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const { result } = renderHook(() => useWindowFocus());
+    expect(result.current.get()).toBe(false);
+    hasFocusSpy.mockRestore();
+  });
+
+  it("sets to true when window focus event fires", () => {
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const { result } = renderHook(() => useWindowFocus());
+
+    act(() => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("sets to false when window blur event fires", () => {
+    vi.spyOn(document, "hasFocus").mockReturnValue(true);
+    const { result } = renderHook(() => useWindowFocus());
+
+    act(() => {
+      window.dispatchEvent(new Event("blur"));
+    });
+
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("toggles correctly across multiple focus/blur events", () => {
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const { result } = renderHook(() => useWindowFocus());
+
+    act(() => { window.dispatchEvent(new Event("focus")); });
+    expect(result.current.get()).toBe(true);
+
+    act(() => { window.dispatchEvent(new Event("blur")); });
+    expect(result.current.get()).toBe(false);
+
+    act(() => { window.dispatchEvent(new Event("focus")); });
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("removes event listeners on unmount", async () => {
+    const addSpy = vi.spyOn(window, "addEventListener");
+    const removeSpy = vi.spyOn(window, "removeEventListener");
+
+    const { unmount } = renderHook(() => useWindowFocus());
+    unmount();
+    await flush(); // useMount defers cleanup via queueMicrotask in test env
+
+    const focusAdded = addSpy.mock.calls.some(([type]) => type === "focus");
+    const blurAdded = addSpy.mock.calls.some(([type]) => type === "blur");
+    const focusRemoved = removeSpy.mock.calls.some(([type]) => type === "focus");
+    const blurRemoved = removeSpy.mock.calls.some(([type]) => type === "blur");
+
+    expect(focusAdded).toBe(true);
+    expect(blurAdded).toBe(true);
+    expect(focusRemoved).toBe(true);
+    expect(blurRemoved).toBe(true);
+
+    addSpy.mockRestore();
+    removeSpy.mockRestore();
+  });
+
+  it("does not respond to events after unmount", async () => {
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const { result, unmount } = renderHook(() => useWindowFocus());
+
+    unmount();
+    await flush(); // wait for cleanup
+
+    act(() => { window.dispatchEvent(new Event("focus")); });
+
+    // Value stays at initial false — no listener active after cleanup
+    expect(result.current.get()).toBe(false);
+  });
+});

package/src/elements/useWindowFocus/index.ts

@@ -0,0 +1,21 @@
+"use client";
+import type { Observable } from "@legendapp/state";
+import { useObservable } from "@legendapp/state/react";
+import { useMount } from "@legendapp/state/react";
+import { useEventListener } from "../../browser/useEventListener";
+
+/*@__NO_SIDE_EFFECTS__*/
+export function useWindowFocus(): Observable<boolean> {
+  // Always initialize with false to match SSR output and avoid hydration mismatch.
+  // The actual value is synced after mount.
+  const focused$ = useObservable<boolean>(false);
+
+  useMount(() => {
+    focused$.set(document.hasFocus());
+  });
+
+  useEventListener("focus", () => focused$.set(true), { passive: true });
+  useEventListener("blur", () => focused$.set(false), { passive: true });
+
+  return focused$;
+}

package/src/elements/useWindowSize/demo.tsx

@@ -0,0 +1,46 @@
+import { useWindowSize } from ".";
+
+const row: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  padding: "8px 14px",
+  borderRadius: "6px",
+  border: "1px solid var(--sl-color-gray-5, #e2e8f0)",
+
+  background: "var(--sl-color-gray-6, #f1f5f9)",
+  // borderRadius: "6px",
+  gap: "24px",
+  color: "white",
+};
+
+export default function UseWindowSizeDemo() {
+  const { width: width$, height: height$ } = useWindowSize();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "8px",
+        fontFamily: "monospace",
+        fontSize: "14px",
+        background: "var(--sl-color-gray-6, #f1f5f9)",
+      }}
+    >
+      <div style={row}>
+        <span>width: {width$.get()}px</span>
+        <span>height: {height$.get()}px</span>
+      </div>
+
+      <p
+        style={{
+          margin: 5,
+          fontSize: "11px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+        }}
+      >
+        Resize the browser window to see the values update.
+      </p>
+    </div>
+  );
+}