@usels/core 0.0.1-beta.3

package/src/elements/useElementBounding/index.ts

@@ -0,0 +1,159 @@
+import type { Observable } from "@legendapp/state";
+import { useObservable } from "@legendapp/state/react";
+import { useCallback, useEffect, useRef } from "react";
+import { type MaybeElement, peekElement } from "../useRef$";
+import { useResizeObserver } from "../useResizeObserver";
+import { useMutationObserver } from "../useMutationObserver";
+import { useEventListener } from "../../browser/useEventListener";
+import { isWindow } from "../../shared";
+import { useMayObservableOptions } from "../../function/useMayObservableOptions";
+import type { DeepMaybeObservable } from "../../types";
+
+export interface UseElementBoundingOptions {
+  /** Reset all values to 0 when element unmounts. Default: true */
+  reset?: boolean;
+  /** Re-calculate on window resize. Default: true */
+  windowResize?: boolean;
+  /** Re-calculate on window scroll. Default: true */
+  windowScroll?: boolean;
+  /** Calculate immediately on mount. Default: true */
+  immediate?: boolean;
+  /** Use requestAnimationFrame to read rect after CSS transforms settle. Default: true */
+  useCssTransforms?: boolean;
+}
+
+export interface UseElementBoundingReturn {
+  x$: Observable<number>;
+  y$: Observable<number>;
+  top$: Observable<number>;
+  right$: Observable<number>;
+  bottom$: Observable<number>;
+  left$: Observable<number>;
+  width$: Observable<number>;
+  height$: Observable<number>;
+  update: () => void;
+}
+
+const ZERO = {
+  x: 0,
+  y: 0,
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+  width: 0,
+  height: 0,
+};
+
+// isWindow(window) returns false in SSR (typeof window === "undefined"), true in browser.
+const win = typeof window !== "undefined" ? window : null;
+
+/**
+ * Tracks the bounding rect of a DOM element (x, y, top, right, bottom, left, width, height).
+ * Observes 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 bounding rect values plus a manual `update()` function
+ *
+ * @example
+ * ```tsx
+ * const el$ = useRef$<HTMLDivElement>();
+ * const { top$, left$, width$, height$ } = useElementBounding(el$);
+ * return <div ref={el$} />;
+ * ```
+ */
+export function useElementBounding(
+  target: MaybeElement,
+  options?: DeepMaybeObservable<UseElementBoundingOptions>,
+): UseElementBoundingReturn {
+  const opts$ = useMayObservableOptions<UseElementBoundingOptions>(options, {
+    immediate: "peek",
+  });
+
+  const bounding$ = useObservable({ ...ZERO });
+
+  // Guards rAF callbacks from updating state after unmount.
+  const unmountedRef = useRef(false);
+  const rafRef = useRef<number | null>(null);
+
+  const recalculate = useCallback(() => {
+    const el = peekElement(target) as Element | null;
+    if (!el || !(el instanceof Element)) {
+      if (opts$.reset.peek() !== false) bounding$.assign({ ...ZERO });
+      return;
+    }
+    const rect = el.getBoundingClientRect();
+    bounding$.assign({
+      x: rect.x,
+      y: rect.y,
+      top: rect.top,
+      right: rect.right,
+      bottom: rect.bottom,
+      left: rect.left,
+      width: rect.width,
+      height: rect.height,
+    });
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const update = useCallback(() => {
+    if (opts$.useCssTransforms.peek() !== false) {
+      rafRef.current = requestAnimationFrame(() => {
+        if (!unmountedRef.current) recalculate();
+      });
+    } else {
+      recalculate();
+    }
+  }, [recalculate]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Observe size changes
+  useResizeObserver(target, update);
+
+  // Observe style/class attribute changes (e.g. CSS transitions, class toggles)
+  useMutationObserver(target, update, {
+    attributes: true,
+    attributeFilter: ["style", "class"],
+  });
+
+  // Observe window scroll / resize (always call hooks unconditionally — Rules of Hooks)
+  // isWindow(win) is false in SSR, so target becomes null outside the browser.
+  // peek() — evaluated once at render time, no reactive subscription needed.
+  useEventListener(
+    isWindow(win) && opts$.windowScroll.peek() !== false ? win : null,
+    "scroll",
+    update,
+    { passive: true },
+  );
+  useEventListener(
+    isWindow(win) && opts$.windowResize.peek() !== false ? win : null,
+    "resize",
+    update,
+    { passive: true },
+  );
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    unmountedRef.current = false;
+    if (opts$.immediate.peek() !== false) update();
+    return () => {
+      unmountedRef.current = true;
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+      if (opts$.reset.peek() !== false) bounding$.assign({ ...ZERO });
+    };
+  }, []);
+
+  return {
+    x$: bounding$.x,
+    y$: bounding$.y,
+    top$: bounding$.top,
+    right$: bounding$.right,
+    bottom$: bounding$.bottom,
+    left$: bounding$.left,
+    width$: bounding$.width,
+    height$: bounding$.height,
+    update,
+  };
+}

package/src/elements/useElementSize/demo.tsx

@@ -0,0 +1,48 @@
+import { useRef$ } from "../useRef$";
+import { useElementSize } from ".";
+
+export default function UseElementSizeDemo() {
+  const el$ = useRef$<HTMLTextAreaElement>();
+  const { width$, height$ } = useElementSize(el$);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "12px" }}>
+      <div
+        style={{
+          display: "flex",
+          gap: "24px",
+          fontFamily: "monospace",
+          fontSize: "14px",
+          padding: "8px 12px",
+          background: "var(--sl-color-gray-6, #f1f5f9)",
+          borderRadius: "6px",
+        }}
+      >
+        <>
+          <span>
+            width: <strong>{Math.round(width$.get())}px</strong>
+          </span>
+          <span>
+            height: <strong>{Math.round(height$.get())}px</strong>
+          </span>
+        </>
+      </div>
+      <textarea
+        ref={el$}
+        defaultValue="Resize this textarea to see width & height update"
+        style={{
+          resize: "both",
+          overflow: "auto",
+          width: "300px",
+          height: "120px",
+          padding: "10px",
+          border: "1px solid var(--sl-color-gray-5, #cbd5e1)",
+          borderRadius: "6px",
+          fontFamily: "inherit",
+          fontSize: "14px",
+          lineHeight: "1.5",
+        }}
+      />
+    </div>
+  );
+}

package/src/elements/useElementSize/index.md

@@ -0,0 +1,60 @@
+---
+title: useElementSize
+category: elements
+---
+
+Tracks the width and height of a DOM element using the [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
+Returns reactive `Observable<number>` values that update whenever the element resizes.
+SVG elements use `getBoundingClientRect()` as a fallback. Supports all three box models.
+
+## Demo
+
+## Usage
+
+```tsx twoslash
+// @noErrors
+import { useRef$, useElementSize } from '@usels/core'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+  const { width$, height$ } = useElementSize(el$)
+
+  return (
+    <div ref={el$}>
+      {width$.get()} × {height$.get()}
+    </div>
+  )
+}
+```
+
+### Custom initial size
+
+```tsx twoslash
+// @noErrors
+import { useRef$, Ref$, useElementSize } from '@usels/core'
+declare const el$: Ref$<HTMLDivElement>
+// ---cut---
+const { width$, height$ } = useElementSize(el$, { width: 320, height: 240 })
+```
+
+### With `border-box`
+
+```tsx twoslash
+// @noErrors
+import { useRef$, Ref$, useElementSize } from '@usels/core'
+declare const el$: Ref$<HTMLDivElement>
+// ---cut---
+const { width$, height$ } = useElementSize(el$, undefined, { box: 'border-box' })
+```
+
+### Stopping observation manually
+
+```tsx twoslash
+// @noErrors
+import { useRef$, Ref$, useElementSize } from '@usels/core'
+declare const el$: Ref$<HTMLDivElement>
+// ---cut---
+const { width$, height$, stop } = useElementSize(el$)
+
+stop()
+```

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

@@ -0,0 +1,295 @@
+// @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 { useElementSize } from ".";
+
+const wrapEl = (el: Element) =>
+  observable<OpaqueObject<Element> | null>(ObservableHint.opaque(el));
+
+// ---------------------------------------------------------------------------
+// ResizeObserver mock (extended with box size support)
+// ---------------------------------------------------------------------------
+
+type BoxSize = { inlineSize: number; blockSize: number };
+
+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 = [];
+  }
+
+  /**
+   * Trigger the callback with a configurable fake entry.
+   * All box size arrays default to empty (falling back to contentRect).
+   */
+  trigger(
+    el: Element,
+    options: {
+      contentRect?: Partial<DOMRectReadOnly>;
+      contentBoxSize?: BoxSize[];
+      borderBoxSize?: BoxSize[];
+      devicePixelContentBoxSize?: BoxSize[];
+    } = {},
+  ) {
+    if (this.disconnected) return;
+    const entry = {
+      target: el,
+      contentRect: {
+        width: 100,
+        height: 200,
+        ...options.contentRect,
+      } as DOMRectReadOnly,
+      contentBoxSize: options.contentBoxSize ?? [],
+      borderBoxSize: options.borderBoxSize ?? [],
+      devicePixelContentBoxSize: options.devicePixelContentBoxSize ?? [],
+    } as unknown as ResizeObserverEntry;
+    this.callback([entry], this);
+  }
+}
+
+beforeEach(() => {
+  ResizeObserverMock.instances = [];
+  vi.stubGlobal("ResizeObserver", ResizeObserverMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// ---------------------------------------------------------------------------
+// useElementSize
+// ---------------------------------------------------------------------------
+
+describe("useElementSize()", () => {
+  it("updates width and height on resize event (contentRect fallback)", () => {
+    const div = document.createElement("div");
+
+    const { result } = renderHook(() => useElementSize(wrapEl(div) as any));
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() =>
+      instance.trigger(div, { contentRect: { width: 320, height: 240 } }),
+    );
+
+    expect(result.current.width$.get()).toBe(320);
+    expect(result.current.height$.get()).toBe(240);
+  });
+
+  it("uses getBoundingClientRect() for SVG elements", () => {
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    vi.spyOn(svg, "getBoundingClientRect").mockReturnValue({
+      width: 150,
+      height: 75,
+      top: 0,
+      left: 0,
+      bottom: 75,
+      right: 150,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    });
+
+    const { result } = renderHook(() => useElementSize(wrapEl(svg) as any));
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() => instance.trigger(svg));
+
+    expect(svg.getBoundingClientRect).toHaveBeenCalled();
+    expect(result.current.width$.get()).toBe(150);
+    expect(result.current.height$.get()).toBe(75);
+  });
+
+  it("reads borderBoxSize when box option is 'border-box'", () => {
+    const div = document.createElement("div");
+
+    const { result } = renderHook(() =>
+      useElementSize(wrapEl(div) as any, undefined, { box: "border-box" }),
+    );
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() =>
+      instance.trigger(div, {
+        borderBoxSize: [{ inlineSize: 400, blockSize: 300 }],
+      }),
+    );
+
+    expect(result.current.width$.get()).toBe(400);
+    expect(result.current.height$.get()).toBe(300);
+  });
+
+  it("reads devicePixelContentBoxSize when box option is 'device-pixel-content-box'", () => {
+    const div = document.createElement("div");
+
+    const { result } = renderHook(() =>
+      useElementSize(wrapEl(div) as any, undefined, {
+        box: "device-pixel-content-box",
+      }),
+    );
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() =>
+      instance.trigger(div, {
+        devicePixelContentBoxSize: [{ inlineSize: 800, blockSize: 600 }],
+      }),
+    );
+
+    expect(result.current.width$.get()).toBe(800);
+    expect(result.current.height$.get()).toBe(600);
+  });
+
+  it("falls back to contentBoxSize when present and no specific box matched", () => {
+    const div = document.createElement("div");
+
+    // default box is "content-box" — reads contentBoxSize
+    const { result } = renderHook(() => useElementSize(wrapEl(div) as any));
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() =>
+      instance.trigger(div, {
+        contentBoxSize: [{ inlineSize: 500, blockSize: 250 }],
+      }),
+    );
+
+    expect(result.current.width$.get()).toBe(500);
+    expect(result.current.height$.get()).toBe(250);
+  });
+
+  it("falls back to contentRect when no boxSize arrays are present", () => {
+    const div = document.createElement("div");
+
+    const { result } = renderHook(() => useElementSize(wrapEl(div) as any));
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() =>
+      instance.trigger(div, { contentRect: { width: 123, height: 456 } }),
+    );
+
+    expect(result.current.width$.get()).toBe(123);
+    expect(result.current.height$.get()).toBe(456);
+  });
+
+  it("returns initialSize when target is null", () => {
+    const { result } = renderHook(() =>
+      useElementSize(null as any, { width: 10, height: 20 }),
+    );
+
+    expect(result.current.width$.get()).toBe(10);
+    expect(result.current.height$.get()).toBe(20);
+  });
+
+  it("returns default initialSize { width: 0, height: 0 } when no initialSize provided and target is null", () => {
+    const { result } = renderHook(() => useElementSize(null as any));
+
+    expect(result.current.width$.get()).toBe(0);
+    expect(result.current.height$.get()).toBe(0);
+  });
+
+  it("stop() suppresses further size updates", () => {
+    const div = document.createElement("div");
+
+    const { result } = renderHook(() => useElementSize(wrapEl(div) as any));
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+
+    // Trigger first resize — should update
+    act(() =>
+      instance.trigger(div, { contentRect: { width: 100, height: 100 } }),
+    );
+    expect(result.current.width$.get()).toBe(100);
+
+    // Stop observing
+    act(() => result.current.stop());
+
+    // Trigger again — instance is disconnected, trigger() is a no-op
+    act(() =>
+      instance.trigger(div, { contentRect: { width: 999, height: 999 } }),
+    );
+    expect(result.current.width$.get()).toBe(100);
+    expect(result.current.height$.get()).toBe(100);
+  });
+
+  it("Ref$ target: sets offsetWidth/offsetHeight as initial size after element is assigned", () => {
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLDivElement>();
+      const size = useElementSize(el$);
+      return { el$, size };
+    });
+
+    // Before assignment — initial values
+    expect(result.current.size.width$.get()).toBe(0);
+    expect(result.current.size.height$.get()).toBe(0);
+
+    const div = document.createElement("div");
+    // jsdom returns 0 for offsetWidth/Height by default, but we can override
+    Object.defineProperty(div, "offsetWidth", { value: 640, configurable: true });
+    Object.defineProperty(div, "offsetHeight", { value: 480, configurable: true });
+
+    act(() => result.current.el$(div));
+
+    expect(result.current.size.width$.get()).toBe(640);
+    expect(result.current.size.height$.get()).toBe(480);
+  });
+
+  it("resets to initialSize when target Ref$ becomes null", () => {
+    const div = document.createElement("div");
+
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLDivElement>();
+      const size = useElementSize(el$, { width: 5, height: 10 });
+      return { el$, size };
+    });
+
+    // Assign element first
+    act(() => result.current.el$(div));
+
+    // Then set element to null (passing null simulates unmounting)
+    act(() => result.current.el$(null));
+
+    expect(result.current.size.width$.get()).toBe(5);
+    expect(result.current.size.height$.get()).toBe(10);
+  });
+
+  it("accumulates multiple borderBoxSize entries", () => {
+    const div = document.createElement("div");
+
+    const { result } = renderHook(() =>
+      useElementSize(wrapEl(div) as any, undefined, { box: "border-box" }),
+    );
+
+    const instance = ResizeObserverMock.instances.at(-1)!;
+    act(() =>
+      instance.trigger(div, {
+        borderBoxSize: [
+          { inlineSize: 100, blockSize: 50 },
+          { inlineSize: 200, blockSize: 100 },
+        ],
+      }),
+    );
+
+    // Accumulated: 100+200=300, 50+100=150
+    expect(result.current.width$.get()).toBe(300);
+    expect(result.current.height$.get()).toBe(150);
+  });
+});

package/src/elements/useElementSize/index.ts

@@ -0,0 +1,100 @@
+import type { Observable } from "@legendapp/state";
+import { useObservable, useObserveEffect } from "@legendapp/state/react";
+import { useCallback } from "react";
+import { getElement, MaybeElement } from "../useRef$";
+import { useResizeObserver } from "../useResizeObserver";
+
+export interface UseElementSizeOptions {
+  box?: "content-box" | "border-box" | "device-pixel-content-box";
+}
+
+export interface UseElementSizeReturn {
+  width$: Observable<number>;
+  height$: Observable<number>;
+  stop: () => void;
+}
+
+/**
+ * Tracks the width and height of a DOM element using ResizeObserver.
+ * SVG elements use getBoundingClientRect() as fallback.
+ *
+ * @param target - Element to observe (Ref$, Observable<Element|null>, Document, Window, or null)
+ * @param initialSize - Initial size values (default: { width: 0, height: 0 })
+ * @param options - Optional box model option
+ * @returns `{ width$, height$, stop }` — reactive size observables and manual stop function
+ *
+ * @example
+ * ```tsx
+ * const el$ = useRef$<HTMLDivElement>();
+ * const { width$, height$ } = useElementSize(el$);
+ * return <div ref={el$}>{width$.get()} x {height$.get()}</div>;
+ * ```
+ */
+export function useElementSize(
+  target: MaybeElement,
+  initialSize?: { width: number; height: number },
+  options?: UseElementSizeOptions,
+): UseElementSizeReturn {
+  const initial = initialSize ?? { width: 0, height: 0 };
+  const size$ = useObservable({ width: initial.width, height: initial.height });
+
+  const onResize = useCallback<ResizeObserverCallback>((entries) => {
+    for (const entry of entries) {
+      const el = entry.target;
+      const isSvg = (el as Element).namespaceURI?.includes("svg");
+
+      if (isSvg) {
+        const rect = el.getBoundingClientRect();
+        size$.assign({ width: rect.width, height: rect.height });
+      } else {
+        const box = options?.box ?? "content-box";
+        let w = 0,
+          h = 0;
+        if (box === "border-box" && entry.borderBoxSize?.length) {
+          for (const b of entry.borderBoxSize) {
+            w += b.inlineSize;
+            h += b.blockSize;
+          }
+        } else if (
+          box === "device-pixel-content-box" &&
+          entry.devicePixelContentBoxSize?.length
+        ) {
+          for (const b of entry.devicePixelContentBoxSize) {
+            w += b.inlineSize;
+            h += b.blockSize;
+          }
+        } else if (entry.contentBoxSize?.length) {
+          for (const b of entry.contentBoxSize) {
+            w += b.inlineSize;
+            h += b.blockSize;
+          }
+        } else {
+          w = entry.contentRect.width;
+          h = entry.contentRect.height;
+        }
+        size$.assign({ width: w, height: h });
+      }
+    }
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const { stop } = useResizeObserver(target, onResize, { box: options?.box });
+
+  // Set initial size from offsetWidth/Height after element mounts.
+  // Uses getElement (tracked) so this re-runs when target Ref$ changes.
+  useObserveEffect(() => {
+    const el = getElement(target) as HTMLElement | null;
+    if (!el) {
+      size$.assign({ width: initial.width, height: initial.height });
+      return;
+    }
+    const isSvg = (el as Element).namespaceURI?.includes("svg");
+    if (!isSvg) {
+      size$.assign({
+        width: (el as HTMLElement).offsetWidth ?? initial.width,
+        height: (el as HTMLElement).offsetHeight ?? initial.height,
+      });
+    }
+  });
+
+  return { width$: size$.width, height$: size$.height, stop };
+}