@usels/core 0.0.1-beta.3

package/src/elements/useMouseInElement/index.md

@@ -0,0 +1,71 @@
+---
+title: useMouseInElement
+category: elements
+---
+
+Tracks the mouse cursor position relative to a DOM element and reports whether the cursor is inside or outside it.
+Observes `mousemove`, `document` `mouseleave`, [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver), [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) (`style`/`class` attribute changes), and `window` `scroll`/`resize` events to keep values accurate as the element moves or resizes.
+All return values are reactive `Observable<number | boolean>`.
+
+## Demo
+
+## Usage
+
+```tsx twoslash
+// @noErrors
+import { useRef$, useMouseInElement } from '@usels/core'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+  const { elementX$, elementY$, isOutside$ } = useMouseInElement(el$)
+
+  return (
+    <div ref={el$}>
+      {isOutside$.get() ? 'outside' : `${elementX$.get()}, ${elementY$.get()}`}
+    </div>
+  )
+}
+```
+
+### Disable outside tracking
+
+By default `elementX$`/`elementY$` continue to update even when the cursor leaves the element.
+Pass `handleOutside: false` to freeze the last in-element position once the cursor exits.
+
+```typescript
+const { elementX$, elementY$ } = useMouseInElement(el$, { handleOutside: false })
+```
+
+### Disable scroll / resize recalculation
+
+```typescript
+const { elementX$, elementY$ } = useMouseInElement(el$, {
+  windowScroll: false,
+  windowResize: false,
+})
+```
+
+### Stop all observers manually
+
+```tsx twoslash
+// @noErrors
+import { useRef$, Ref$, useMouseInElement } from '@usels/core'
+declare const el$: Ref$<HTMLDivElement>
+// ---cut---
+const { elementX$, elementY$, stop } = useMouseInElement(el$)
+
+// Tear down all event listeners and observers
+stop()
+```
+
+### Global mouse coordinates
+
+The raw `clientX` / `clientY` values are also exposed as `x$` and `y$`.
+
+```tsx twoslash
+// @noErrors
+import { useRef$, Ref$, useMouseInElement } from '@usels/core'
+declare const el$: Ref$<HTMLDivElement>
+// ---cut---
+const { x$, y$, elementX$, elementY$ } = useMouseInElement(el$)
+```

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

@@ -0,0 +1,398 @@
+// @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 { useMouseInElement } from ".";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const wrapEl = (el: Element) =>
+  observable<OpaqueObject<Element> | null>(ObservableHint.opaque(el));
+
+/**
+ * Create a div whose getClientRects() returns a single rect at the given position.
+ * Defaults: left=0, top=0, right=200, bottom=100, width=200, height=100
+ */
+function createDiv(rect: Partial<DOMRect> = {}) {
+  const div = document.createElement("div");
+  const full: DOMRect = {
+    left: 0,
+    top: 0,
+    right: 200,
+    bottom: 100,
+    width: 200,
+    height: 100,
+    x: 0,
+    y: 0,
+    toJSON: () => ({}),
+    ...rect,
+  };
+  vi.spyOn(div, "getClientRects").mockReturnValue(
+    [full] as unknown as DOMRectList,
+  );
+  return div;
+}
+
+function fireMouseMove(x: number, y: number) {
+  act(() => {
+    window.dispatchEvent(
+      new MouseEvent("mousemove", { clientX: x, clientY: y, bubbles: true }),
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Mocks: ResizeObserver, MutationObserver
+// ---------------------------------------------------------------------------
+
+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 = [];
+  }
+}
+
+class MutationObserverMock {
+  static instances: MutationObserverMock[] = [];
+  callback: MutationCallback;
+  disconnected = false;
+
+  constructor(cb: MutationCallback) {
+    this.callback = cb;
+    MutationObserverMock.instances.push(this);
+  }
+  observe(_el: Element, _opts?: MutationObserverInit) {}
+  disconnect() {
+    this.disconnected = true;
+  }
+  takeRecords(): MutationRecord[] {
+    return [];
+  }
+}
+
+beforeEach(() => {
+  ResizeObserverMock.instances = [];
+  MutationObserverMock.instances = [];
+  vi.stubGlobal("ResizeObserver", ResizeObserverMock);
+  vi.stubGlobal("MutationObserver", MutationObserverMock);
+  Object.defineProperty(window, "scrollX", { value: 0, configurable: true });
+  Object.defineProperty(window, "scrollY", { value: 0, configurable: true });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// ---------------------------------------------------------------------------
+// useMouseInElement tests
+// ---------------------------------------------------------------------------
+
+describe("useMouseInElement()", () => {
+  it("initial state: all zeros and isOutside = true", () => {
+    const div = createDiv();
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    expect(result.current.elementX$.get()).toBe(0);
+    expect(result.current.elementY$.get()).toBe(0);
+    expect(result.current.elementPositionX$.get()).toBe(0);
+    expect(result.current.elementPositionY$.get()).toBe(0);
+    expect(result.current.elementWidth$.get()).toBe(0);
+    expect(result.current.elementHeight$.get()).toBe(0);
+    expect(result.current.isOutside$.get()).toBe(true);
+    expect(result.current.x$.get()).toBe(0);
+    expect(result.current.y$.get()).toBe(0);
+  });
+
+  it("mousemove inside rect → updates elementX/Y and sets isOutside = false", () => {
+    // Rect: left=10, top=20, right=210, bottom=120
+    const div = createDiv({
+      left: 10,
+      top: 20,
+      right: 210,
+      bottom: 120,
+      width: 200,
+      height: 100,
+    });
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(60, 70); // inside: 60-10=50, 70-20=50
+
+    expect(result.current.isOutside$.get()).toBe(false);
+    expect(result.current.elementX$.get()).toBe(50);
+    expect(result.current.elementY$.get()).toBe(50);
+  });
+
+  it("exposes raw clientX/clientY as x and y", () => {
+    const div = createDiv();
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(350, 420);
+
+    expect(result.current.x$.get()).toBe(350);
+    expect(result.current.y$.get()).toBe(420);
+  });
+
+  it("elementPositionX/Y includes window.scrollX/scrollY", () => {
+    Object.defineProperty(window, "scrollX", { value: 100, configurable: true });
+    Object.defineProperty(window, "scrollY", { value: 200, configurable: true });
+
+    const div = createDiv({
+      left: 10,
+      top: 20,
+      right: 210,
+      bottom: 120,
+      width: 200,
+      height: 100,
+    });
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(60, 70); // inside
+
+    // elementPositionX = rect.left + scrollX = 10 + 100 = 110
+    expect(result.current.elementPositionX$.get()).toBe(110);
+    // elementPositionY = rect.top + scrollY = 20 + 200 = 220
+    expect(result.current.elementPositionY$.get()).toBe(220);
+  });
+
+  it("exposes elementWidth and elementHeight from matched rect", () => {
+    const div = createDiv({
+      left: 0,
+      top: 0,
+      right: 300,
+      bottom: 150,
+      width: 300,
+      height: 150,
+    });
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(50, 50); // inside
+
+    expect(result.current.elementWidth$.get()).toBe(300);
+    expect(result.current.elementHeight$.get()).toBe(150);
+  });
+
+  it("mousemove outside rect → isOutside = true", () => {
+    const div = createDiv({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 100,
+      width: 200,
+      height: 100,
+    });
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(50, 50); // inside first
+    expect(result.current.isOutside$.get()).toBe(false);
+
+    fireMouseMove(500, 500); // outside
+    expect(result.current.isOutside$.get()).toBe(true);
+  });
+
+  it("handleOutside: true (default) — still updates elementX/Y when outside", () => {
+    const div = createDiv({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 100,
+      width: 200,
+      height: 100,
+    });
+    const { result } = renderHook(() =>
+      useMouseInElement(wrapEl(div) as any, { handleOutside: true }),
+    );
+
+    fireMouseMove(300, 400); // outside: elementX = 300-0, elementY = 400-0
+
+    expect(result.current.isOutside$.get()).toBe(true);
+    expect(result.current.elementX$.get()).toBe(300);
+    expect(result.current.elementY$.get()).toBe(400);
+  });
+
+  it("handleOutside: false — elementX/Y frozen at last inside position after leaving", () => {
+    const div = createDiv({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 100,
+      width: 200,
+      height: 100,
+    });
+    const { result } = renderHook(() =>
+      useMouseInElement(wrapEl(div) as any, { handleOutside: false }),
+    );
+
+    fireMouseMove(80, 60); // inside
+    expect(result.current.elementX$.get()).toBe(80);
+    expect(result.current.elementY$.get()).toBe(60);
+
+    fireMouseMove(500, 500); // outside — should NOT update elementX/Y
+    expect(result.current.isOutside$.get()).toBe(true);
+    expect(result.current.elementX$.get()).toBe(80);
+    expect(result.current.elementY$.get()).toBe(60);
+  });
+
+  it("document mouseleave → sets isOutside = true regardless of cursor position", () => {
+    const div = createDiv({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 100,
+      width: 200,
+      height: 100,
+    });
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(50, 50); // inside
+    expect(result.current.isOutside$.get()).toBe(false);
+
+    act(() => {
+      document.dispatchEvent(new MouseEvent("mouseleave", { bubbles: false }));
+    });
+
+    expect(result.current.isOutside$.get()).toBe(true);
+  });
+
+  it("scroll event triggers recalculation (windowScroll: true by default)", () => {
+    const div = createDiv();
+    const spy = vi.spyOn(div, "getClientRects");
+    renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    const before = spy.mock.calls.length;
+
+    act(() => {
+      window.dispatchEvent(new Event("scroll"));
+    });
+
+    expect(spy.mock.calls.length).toBeGreaterThan(before);
+  });
+
+  it("windowScroll: false — scroll event does not trigger recalculation", () => {
+    const div = createDiv();
+    const spy = vi.spyOn(div, "getClientRects");
+    renderHook(() =>
+      useMouseInElement(wrapEl(div) as any, { windowScroll: false }),
+    );
+
+    const before = spy.mock.calls.length;
+
+    act(() => {
+      window.dispatchEvent(new Event("scroll"));
+    });
+
+    expect(spy.mock.calls.length).toBe(before);
+  });
+
+  it("resize event triggers recalculation (windowResize: true by default)", () => {
+    const div = createDiv();
+    const spy = vi.spyOn(div, "getClientRects");
+    renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    const before = spy.mock.calls.length;
+
+    act(() => {
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    expect(spy.mock.calls.length).toBeGreaterThan(before);
+  });
+
+  it("windowResize: false — resize event does not trigger recalculation", () => {
+    const div = createDiv();
+    const spy = vi.spyOn(div, "getClientRects");
+    renderHook(() =>
+      useMouseInElement(wrapEl(div) as any, { windowResize: false }),
+    );
+
+    const before = spy.mock.calls.length;
+
+    act(() => {
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    expect(spy.mock.calls.length).toBe(before);
+  });
+
+  it("stop() disconnects ResizeObserver and MutationObserver", () => {
+    const div = createDiv();
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    act(() => result.current.stop());
+
+    expect(ResizeObserverMock.instances.some((i) => i.disconnected)).toBe(true);
+    expect(MutationObserverMock.instances.some((i) => i.disconnected)).toBe(
+      true,
+    );
+  });
+
+  it("stop() removes mousemove listener — state does not update afterwards", () => {
+    const div = createDiv({
+      left: 0,
+      top: 0,
+      right: 200,
+      bottom: 100,
+      width: 200,
+      height: 100,
+    });
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(80, 60); // inside
+    expect(result.current.elementX$.get()).toBe(80);
+
+    act(() => result.current.stop());
+
+    // Dispatch mousemove after stop — listener should be removed
+    act(() => {
+      window.dispatchEvent(
+        new MouseEvent("mousemove", {
+          clientX: 10,
+          clientY: 10,
+          bubbles: true,
+        }),
+      );
+    });
+
+    // x/y raw values should not have updated
+    expect(result.current.x$.get()).toBe(80);
+    expect(result.current.y$.get()).toBe(60);
+  });
+
+  it("does not throw when target is null", () => {
+    expect(() => {
+      renderHook(() => useMouseInElement(null as any));
+    }).not.toThrow();
+  });
+
+  it("skips update when getClientRects returns empty (no layout)", () => {
+    const div = document.createElement("div");
+    vi.spyOn(div, "getClientRects").mockReturnValue(
+      [] as unknown as DOMRectList,
+    );
+    const { result } = renderHook(() => useMouseInElement(wrapEl(div) as any));
+
+    fireMouseMove(50, 50);
+
+    // No rect → state stays at initial values
+    expect(result.current.isOutside$.get()).toBe(true);
+    expect(result.current.elementX$.get()).toBe(0);
+    expect(result.current.elementY$.get()).toBe(0);
+  });
+});

package/src/elements/useMouseInElement/index.ts

@@ -0,0 +1,209 @@
+import type { Observable } from "@legendapp/state";
+import { useObservable } from "@legendapp/state/react";
+import { useCallback } from "react";
+import { isWindow } from "../../shared";
+import { useMayObservableOptions } from "../../function/useMayObservableOptions";
+import type { DeepMaybeObservable } from "../../types";
+import { type MaybeElement, peekElement } from "../useRef$";
+import { useResizeObserver } from "../useResizeObserver";
+import { useMutationObserver } from "../useMutationObserver";
+import { useEventListener } from "../../browser/useEventListener";
+
+export interface UseMouseInElementOptions {
+  /** Also update elementX/Y when mouse is outside the element. Default: true */
+  handleOutside?: boolean;
+  /** Re-calculate on window scroll. Default: true */
+  windowScroll?: boolean;
+  /** Re-calculate on window resize. Default: true */
+  windowResize?: boolean;
+}
+
+export interface UseMouseInElementReturn {
+  /** Mouse X position relative to the element */
+  elementX$: Observable<number>;
+  /** Mouse Y position relative to the element */
+  elementY$: Observable<number>;
+  /** Element's absolute X position on the page */
+  elementPositionX$: Observable<number>;
+  /** Element's absolute Y position on the page */
+  elementPositionY$: Observable<number>;
+  /** Element width */
+  elementWidth$: Observable<number>;
+  /** Element height */
+  elementHeight$: Observable<number>;
+  /** Whether the mouse is outside the element */
+  isOutside$: Observable<boolean>;
+  /** Global mouse X (clientX) */
+  x$: Observable<number>;
+  /** Global mouse Y (clientY) */
+  y$: Observable<number>;
+  /** Stop all observers and event listeners */
+  stop: () => void;
+}
+
+// isWindow(window) returns false in SSR (typeof window === "undefined"), true in browser.
+const win = typeof window !== "undefined" ? window : null;
+
+/**
+ * Tracks whether the mouse cursor is inside a DOM element and calculates
+ * the cursor position relative to that element.
+ *
+ * Observes mousemove, document mouseleave, ResizeObserver, MutationObserver
+ * (style/class changes), window scroll, and resize.
+ *
+ * @param target - Element to observe: Ref$, Observable<OpaqueObject<Element>|null>, Document, Window, or null
+ * @param options - Configuration options
+ * @returns Reactive mouse position values relative to the element, plus a manual `stop()` function
+ *
+ * @example
+ * ```tsx
+ * const el$ = useRef$<HTMLDivElement>();
+ * const { elementX$, elementY$, isOutside$ } = useMouseInElement(el$);
+ * return <div ref={el$} />;
+ * ```
+ */
+export function useMouseInElement(
+  target: MaybeElement,
+  options?: DeepMaybeObservable<UseMouseInElementOptions>,
+): UseMouseInElementReturn {
+  // Rule 2: normalize with useMayObservableOptions
+  // Rule 3: handleOutside/windowScroll/windowResize are mount-time-only → 'peek'
+  const opts$ = useMayObservableOptions<UseMouseInElementOptions>(options, {
+    handleOutside: "peek",
+    windowScroll: "peek",
+    windowResize: "peek",
+  });
+
+  // Global mouse coordinates (exposed in return)
+  const mouse$ = useObservable({ x: 0, y: 0 });
+
+  // Element-relative state
+  const state$ = useObservable({
+    elementX: 0,
+    elementY: 0,
+    elementPositionX: 0,
+    elementPositionY: 0,
+    elementWidth: 0,
+    elementHeight: 0,
+    isOutside: true,
+  });
+
+  // Recalculate element-relative position from current mouse coords
+  const update = useCallback(() => {
+    const el = peekElement(target) as HTMLElement | null;
+    if (!el || !(el instanceof Element)) return;
+
+    const rects = Array.from(el.getClientRects());
+    if (!rects.length) return;
+
+    const mx = mouse$.x.peek();
+    const my = mouse$.y.peek();
+    let found = false;
+
+    for (const rect of rects) {
+      if (
+        mx >= rect.left &&
+        mx <= rect.right &&
+        my >= rect.top &&
+        my <= rect.bottom
+      ) {
+        state$.assign({
+          elementX: mx - rect.left,
+          elementY: my - rect.top,
+          elementPositionX: rect.left + window.scrollX,
+          elementPositionY: rect.top + window.scrollY,
+          elementWidth: rect.width,
+          elementHeight: rect.height,
+          isOutside: false,
+        });
+        found = true;
+        break;
+      }
+    }
+
+    if (!found) {
+      state$.isOutside.set(true);
+      if (opts$.handleOutside.peek() !== false) {
+        const rect = rects[0];
+        state$.assign({
+          elementX: mx - rect.left,
+          elementY: my - rect.top,
+          elementPositionX: rect.left + window.scrollX,
+          elementPositionY: rect.top + window.scrollY,
+          elementWidth: rect.width,
+          elementHeight: rect.height,
+        });
+      }
+    }
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Update global mouse coords then recalculate
+  const onMouseMove = useCallback(
+    (e: MouseEvent) => {
+      mouse$.assign({ x: e.clientX, y: e.clientY });
+      update();
+    },
+    [update], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  // Always call hooks unconditionally — Rules of Hooks.
+  // null target → useEventListener registers no listener (no-op).
+  // peek() — evaluated once at render time, no reactive subscription needed.
+  const stopMouse = useEventListener(
+    isWindow(win) ? win : null,
+    "mousemove",
+    onMouseMove,
+    { passive: true },
+  );
+
+  // document mouseleave → force isOutside = true
+  const stopLeave = useEventListener(
+    typeof document !== "undefined" ? document : null,
+    "mouseleave",
+    () => state$.isOutside.set(true),
+  );
+
+  const stopScroll = useEventListener(
+    isWindow(win) && opts$.windowScroll.peek() !== false ? win : null,
+    "scroll",
+    update,
+    { passive: true },
+  );
+  const stopResize = useEventListener(
+    isWindow(win) && opts$.windowResize.peek() !== false ? win : null,
+    "resize",
+    update,
+    { passive: true },
+  );
+
+  // Observe element size changes
+  const { stop: stopRO } = useResizeObserver(target, update);
+
+  // Observe style/class attribute changes (e.g. CSS transitions, class toggles)
+  const { stop: stopMO } = useMutationObserver(target, update, {
+    attributes: true,
+    attributeFilter: ["style", "class"],
+  });
+
+  const stop = useCallback(() => {
+    stopMouse();
+    stopLeave();
+    stopScroll();
+    stopResize();
+    stopRO();
+    stopMO();
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return {
+    elementX$: state$.elementX,
+    elementY$: state$.elementY,
+    elementPositionX$: state$.elementPositionX,
+    elementPositionY$: state$.elementPositionY,
+    elementWidth$: state$.elementWidth,
+    elementHeight$: state$.elementHeight,
+    isOutside$: state$.isOutside,
+    x$: mouse$.x,
+    y$: mouse$.y,
+    stop,
+  };
+}