@usels/core 0.0.1

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,
+  };
+}

package/src/elements/useMutationObserver/demo.tsx

@@ -0,0 +1,270 @@
+import { useRef$ } from "../useRef$";
+import { useMutationObserver } from ".";
+import { Computed, useObservable } from "@legendapp/state/react";
+import { batch, beginBatch, endBatch } from "@legendapp/state";
+
+const MAX_LOG = 6;
+
+const btn: React.CSSProperties = {
+  height: "26px",
+  padding: "0 10px",
+  fontSize: "12px",
+  cursor: "pointer",
+  borderRadius: "4px",
+  border: "1px solid var(--sl-color-gray-4, #94a3b8)",
+  background: "transparent",
+  fontFamily: "monospace",
+  display: "inline-flex",
+  alignItems: "center",
+  margin: 0,
+};
+
+const rowLabel: React.CSSProperties = {
+  fontSize: "11px",
+  color: "var(--sl-color-gray-3, #94a3b8)",
+  alignSelf: "center",
+  userSelect: "none",
+  minWidth: "52px",
+};
+
+export default function UseMutationObserverDemo() {
+  const el$ = useRef$<HTMLDivElement>();
+  const log$ = useObservable<string[]>([]);
+  const active$ = useObservable(false);
+  const childCount$ = useObservable(0);
+  const stopped$ = useObservable(false);
+
+  const { stop, resume } = useMutationObserver(
+    el$,
+    (records) => {
+      const lines = records.map((r): string => {
+        if (r.type === "attributes") {
+          return `[attributes]  ${r.attributeName}  ← was: ${
+            r.oldValue ?? "—"
+          }`;
+        }
+        const a = r.addedNodes.length;
+        const rm = r.removedNodes.length;
+        return `[childList]   ${[a && `+${a} added`, rm && `-${rm} removed`]
+          .filter(Boolean)
+          .join(", ")}`;
+      });
+      batch(() => {
+        log$.unshift(...lines);
+        if (MAX_LOG < log$.peek().length) {
+          log$.splice(-1, 1);
+        }
+      });
+    },
+    { attributes: true, attributeOldValue: true, childList: true },
+  );
+
+  const toggleAttr = () => {
+    batch(() => {
+      const el = el$.peek();
+      if (!el) return;
+
+      const next = !active$.peek();
+      active$.set(next);
+      if (next) el.setAttribute("data-active", "true");
+      else el.removeAttribute("data-active");
+    });
+  };
+
+  const addChild = () => {
+    const el = el$.peek();
+    if (!el) return;
+    beginBatch();
+    childCount$.set((n) => n + 1);
+    const span = document.createElement("span");
+    span.textContent = `child-${childCount$.peek()}`;
+    span.style.cssText =
+      "display:block;font-size:12px;font-family:monospace;" +
+      "color:var(--sl-color-gray-2,#475569);padding:1px 0";
+    el.appendChild(span);
+    endBatch();
+  };
+
+  const removeChild = () => {
+    const el = el$.peek();
+    if (!el) return;
+    const last = el.querySelector("span:last-of-type");
+    if (!last) return;
+    el.removeChild(last);
+    childCount$.set((n) => Math.max(0, n - 1));
+  };
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "8px",
+        fontFamily: "monospace",
+        fontSize: "13px",
+      }}
+    >
+      {/* Status bar */}
+      <div
+        style={{
+          display: "flex",
+          gap: "16px",
+          alignItems: "center",
+          padding: "6px 12px",
+          background: "var(--sl-color-gray-6, #f1f5f9)",
+          borderRadius: "6px",
+        }}
+      >
+        <Computed>
+          {() => (
+            <span>
+              status:{" "}
+              <strong
+                style={{
+                  color: stopped$.get()
+                    ? "var(--sl-color-red, #ef4444)"
+                    : "var(--sl-color-green, #22c55e)",
+                }}
+              >
+                {stopped$.get() ? "stopped" : "observing"}
+              </strong>
+            </span>
+          )}
+        </Computed>
+        <Computed>
+          {() => (
+            <span style={{ color: "var(--sl-color-gray-3, #94a3b8)" }}>
+              data-active: <strong>{active$.get() ? '"true"' : "—"}</strong>
+            </span>
+          )}
+        </Computed>
+        <Computed>
+          {() => (
+            <span style={{ color: "var(--sl-color-gray-3, #94a3b8)" }}>
+              children: <strong>{childCount$.get()}</strong>
+            </span>
+          )}
+        </Computed>
+      </div>
+
+      {/* DOM mutation actions */}
+      <div style={{ display: "flex", gap: "6px", alignItems: "center" }}>
+        <span style={rowLabel}>DOM</span>
+        <button onClick={toggleAttr} style={btn}>
+          toggle data-active
+        </button>
+        <button onClick={addChild} style={btn}>
+          add child
+        </button>
+        <button onClick={removeChild} style={btn}>
+          remove child
+        </button>
+        <button onClick={() => log$.set([])} style={btn}>
+          clear log
+        </button>
+      </div>
+
+      {/* Observer control */}
+      <div style={{ display: "flex", gap: "6px", alignItems: "center" }}>
+        <span style={rowLabel}>Observer</span>
+        <Computed>
+          {() =>
+            stopped$.get() ? (
+              <button
+                onClick={() => {
+                  resume();
+                  stopped$.set(false);
+                }}
+                style={{
+                  ...btn,
+                  borderColor: "var(--sl-color-green, #22c55e)",
+                  color: "var(--sl-color-green, #22c55e)",
+                }}
+              >
+                resume observe()
+              </button>
+            ) : (
+              <button
+                onClick={() => {
+                  stop();
+                  stopped$.set(true);
+                }}
+                style={{
+                  ...btn,
+                  borderColor: "var(--sl-color-red, #ef4444)",
+                  color: "var(--sl-color-red, #ef4444)",
+                }}
+              >
+                stop observe()
+              </button>
+            )
+          }
+        </Computed>
+      </div>
+
+      {/* Observed target element — children appended/removed by buttons above */}
+      <Computed>
+        {() => (
+          <div
+            ref={el$}
+            style={{
+              minHeight: "52px",
+              padding: "8px 12px",
+              borderRadius: "6px",
+              border: `1px dashed ${
+                active$.get()
+                  ? "var(--sl-color-green, #22c55e)"
+                  : "var(--sl-color-gray-4, #94a3b8)"
+              }`,
+              background: active$.get()
+                ? "var(--sl-color-green-low, #f0fdf4)"
+                : "transparent",
+              transition: "border-color 0.2s, background 0.2s",
+            }}
+          />
+        )}
+      </Computed>
+
+      {/* Mutation log */}
+      <div
+        style={{
+          minHeight: "80px",
+          maxHeight: "168px",
+          overflowY: "auto",
+          padding: "8px 12px",
+          background: "var(--sl-color-gray-6, #f1f5f9)",
+          borderRadius: "6px",
+          fontSize: "12px",
+        }}
+      >
+        <Computed>
+          {() => {
+            const entries = log$.get();
+            if (!entries.length) {
+              return (
+                <span style={{ opacity: 0.4 }}>
+                  — no mutations recorded yet
+                </span>
+              );
+            }
+            return (
+              <>
+                {entries.map((line, i) => (
+                  <div
+                    key={i}
+                    style={{
+                      padding: "1px 0",
+                      opacity: Math.max(0.2, 1 - i * 0.15),
+                    }}
+                  >
+                    {line}
+                  </div>
+                ))}
+              </>
+            );
+          }}
+        </Computed>
+      </div>
+    </div>
+  );
+}

package/src/elements/useMutationObserver/index.md

@@ -0,0 +1,99 @@
+---
+title: useMutationObserver
+category: elements
+---
+
+Reactive wrapper around the [MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
+Observes one or more DOM nodes for mutations — attribute changes, child additions/removals, and text content changes.
+Targets can be `Ref$`, `Observable<Element|null>`, or a plain `Element`.
+
+## Demo
+
+## Usage
+
+```tsx twoslash
+// @noErrors
+import { useRef$, useMutationObserver } from '@usels/core'
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+
+  useMutationObserver(
+    el$,
+    (records) => {
+      records.forEach((r) => { /* handle r.type, r.target */ })
+    },
+    { attributes: true, childList: true },
+  )
+
+  return <div ref={el$} />
+}
+```
+
+### Watching attributes only
+
+```tsx
+useMutationObserver(el$, callback, { attributes: true })
+```
+
+### Filtering specific attributes
+
+Only fire when `aria-expanded` or `data-active` change:
+
+```tsx
+useMutationObserver(el$, callback, {
+  attributes: true,
+  attributeFilter: ['aria-expanded', 'data-active'],
+})
+```
+
+### Recording the previous attribute value
+
+```tsx
+useMutationObserver(
+  el$,
+  (records) => {
+    records.forEach((r) => {
+      const next = (r.target as Element).getAttribute(r.attributeName!)
+      console.log('old:', r.oldValue, '→ new:', next)
+    })
+  },
+  { attributes: true, attributeOldValue: true },
+)
+```
+
+### Watching descendant nodes with `subtree`
+
+```tsx
+useMutationObserver(el$, callback, { childList: true, subtree: true })
+```
+
+### Multiple targets
+
+```tsx
+useMutationObserver([el$, anotherEl], callback, { attributes: true })
+```
+
+### Stop and resume
+
+```tsx
+const { stop, resume } = useMutationObserver(el$, callback, { childList: true })
+
+stop()   // disconnects the observer
+resume() // reconnects with the same target and options
+```
+
+### Flushing pending records
+
+```tsx
+const { takeRecords } = useMutationObserver(el$, callback, { attributes: true })
+
+const pending = takeRecords()
+```
+
+### Checking browser support
+
+```tsx
+const { isSupported } = useMutationObserver(el$, callback, { attributes: true })
+
+console.log(isSupported.get()) // Observable<boolean>
+```