@usels/core 0.0.1

package/src/elements/useMouseInElement/demo.tsx

@@ -0,0 +1,88 @@
+import { Computed } from "@legendapp/state/react";
+import { useRef$ } from "../useRef$";
+import { useMouseInElement } from ".";
+
+export default function UseMouseInElementDemo() {
+  const el$ = useRef$<HTMLDivElement>();
+  const { elementX, elementY, isOutside, elementWidth, elementHeight, x, y: _y } =
+    useMouseInElement(el$);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "12px" }}>
+      {/* Stats readout */}
+      <Computed>
+        {() => (
+          <div
+            style={{
+              display: "grid",
+              gridTemplateColumns: "repeat(3, 1fr)",
+              gap: "6px",
+              fontFamily: "monospace",
+              fontSize: "13px",
+              padding: "10px 14px",
+              background: "var(--sl-color-gray-6, #f1f5f9)",
+              borderRadius: "6px",
+            }}
+          >
+            {(
+              [
+                ["elementX", `${Math.round(elementX.get())}px`],
+                ["elementY", `${Math.round(elementY.get())}px`],
+                ["isOutside", String(isOutside.get())],
+                ["width", `${Math.round(elementWidth.get())}px`],
+                ["height", `${Math.round(elementHeight.get())}px`],
+                ["x (global)", `${Math.round(x.get())}px`],
+              ] as [string, string][]
+            ).map(([label, val]) => (
+              <span key={label}>
+                {label}: <strong>{val}</strong>
+              </span>
+            ))}
+          </div>
+        )}
+      </Computed>
+
+      {/* Hover target with tracking dot */}
+      <div
+        ref={el$}
+        style={{
+          position: "relative",
+          width: "100%",
+          height: "160px",
+          border: "1px solid var(--sl-color-gray-5, #cbd5e1)",
+          borderRadius: "6px",
+          overflow: "hidden",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          userSelect: "none",
+          fontFamily: "monospace",
+          fontSize: "13px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+          cursor: "crosshair",
+        }}
+      >
+        move your mouse here
+        <Computed>
+          {() => (
+            <div
+              style={{
+                position: "absolute",
+                left: elementX.get(),
+                top: elementY.get(),
+                width: "10px",
+                height: "10px",
+                borderRadius: "50%",
+                background: "var(--sl-color-accent, #818cf8)",
+                transform: "translate(-50%, -50%)",
+                pointerEvents: "none",
+                opacity: isOutside.get() ? 0 : 1,
+                transition: "opacity 0.15s",
+              }}
+            />
+          )}
+        </Computed>
+      </div>
+    </div>
+  );
+}

package/src/elements/useMouseInElement/index.md

@@ -0,0 +1,76 @@
+---
+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'
+import { Computed } from '@legendapp/state/react'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+  const { elementX, elementY, isOutside } = useMouseInElement(el$)
+
+  return (
+    <Computed>
+      {() => (
+        <div ref={el$}>
+          {isOutside.get() ? 'outside' : `${elementX.get()}, ${elementY.get()}`}
+        </div>
+      )}
+    </Computed>
+  )
+}
+```
+
+### 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);
+  });
+});