@usels/core 0.0.1-beta.3

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

@@ -0,0 +1,208 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { observable, ObservableHint } from "@legendapp/state";
+import type { OpaqueObject } from "@legendapp/state";
+import { describe, it, expect, afterEach } from "vitest";
+import { useRef$ } from "../useRef$";
+import { useParentElement } from ".";
+
+const wrapEl = (el: Element) => observable<OpaqueObject<Element> | null>(ObservableHint.opaque(el));
+
+// ---------------------------------------------------------------------------
+// DOM helpers
+// ---------------------------------------------------------------------------
+
+const attached: Element[] = [];
+
+/** Attach a child inside a parent div to the document and track for cleanup. */
+function attachToBody<T extends Element>(child: T): { child: T; parent: HTMLDivElement } {
+  const parent = document.createElement("div");
+  parent.appendChild(child);
+  document.body.appendChild(parent);
+  attached.push(parent);
+  return { child, parent };
+}
+
+afterEach(() => {
+  attached.forEach((el) => el.parentNode?.removeChild(el));
+  attached.length = 0;
+});
+
+// ---------------------------------------------------------------------------
+// useParentElement()
+// ---------------------------------------------------------------------------
+
+describe("useParentElement()", () => {
+  it("returns parentElement of a plain element attached to DOM", () => {
+    const child = document.createElement("span");
+    const { parent } = attachToBody(child);
+
+    const { result } = renderHook(() => useParentElement(wrapEl(child)));
+
+    expect(result.current.get()).toBe(parent);
+  });
+
+  it("returns null when element is not attached to DOM", () => {
+    const el = document.createElement("div");
+    // not appended anywhere
+
+    const { result } = renderHook(() => useParentElement(wrapEl(el)));
+
+    expect(result.current.get()).toBeNull();
+  });
+
+  it("returns null when element param is undefined", () => {
+    const { result } = renderHook(() => useParentElement());
+
+    expect(result.current.get()).toBeNull();
+  });
+
+  it("reacts to Ref$ — returns parent after element is assigned", () => {
+    const child = document.createElement("span");
+    const { parent } = attachToBody(child);
+
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLSpanElement>();
+      return { el$, parent$: useParentElement(el$) };
+    });
+
+    // Before el$ is assigned — no element to resolve
+    expect(result.current.parent$.get()).toBeNull();
+
+    act(() => result.current.el$(child));
+
+    expect(result.current.parent$.get()).toBe(parent);
+  });
+
+  it("reacts to Observable<Element|null> — updates when value is set", () => {
+    const child = document.createElement("p");
+    const { parent } = attachToBody(child);
+
+    const target$ = observable<HTMLElement | null>(null);
+
+    const { result } = renderHook(() => useParentElement(target$ as any));
+
+    expect(result.current.get()).toBeNull();
+
+    act(() => {
+      target$.set(child);
+    });
+
+    expect(result.current.get()).toBe(parent);
+  });
+
+  it("updates when Ref$ is reassigned to a different element", () => {
+    const childA = document.createElement("span");
+    const { parent: parentA } = attachToBody(childA);
+
+    const childB = document.createElement("em");
+    const { parent: parentB } = attachToBody(childB);
+
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLElement>();
+      return { el$, parent$: useParentElement(el$) };
+    });
+
+    act(() => result.current.el$(childA));
+    expect(result.current.parent$.get()).toBe(parentA);
+
+    act(() => result.current.el$(childB));
+    expect(result.current.parent$.get()).toBe(parentB);
+  });
+
+  it("returns null when Observable is set to null", () => {
+    const child = document.createElement("span");
+    attachToBody(child);
+
+    const target$ = observable<HTMLElement | null>(child);
+
+    const { result } = renderHook(() => useParentElement(target$ as any));
+
+    act(() => {
+      target$.set(null);
+    });
+
+    expect(result.current.get()).toBeNull();
+  });
+
+  it("observable value persists after unmount", () => {
+    const child = document.createElement("span");
+    attachToBody(child);
+
+    const { result, unmount } = renderHook(() => useParentElement(wrapEl(child)));
+
+    expect(result.current.get()).not.toBeNull();
+    unmount();
+    // Observable value remains readable after unmount
+    expect(result.current.get()).not.toBeNull();
+  });
+
+  it("returns null when Document is passed", () => {
+    const { result } = renderHook(() => useParentElement(document as any));
+    expect(result.current.get()).toBeNull();
+  });
+
+  it("handles null → value → null cycle for Observable", () => {
+    const child = document.createElement("span");
+    const { parent } = attachToBody(child);
+
+    const target$ = observable<HTMLElement | null>(null);
+    const { result } = renderHook(() => useParentElement(target$ as any));
+
+    expect(result.current.get()).toBeNull();
+
+    act(() => { target$.set(child); });
+    expect(result.current.get()).toBe(parent);
+
+    act(() => { target$.set(null); });
+    expect(result.current.get()).toBeNull();
+  });
+
+  it("reads parent of Ref$ that already holds an element at mount time", () => {
+    const child = document.createElement("span");
+    const { parent } = attachToBody(child);
+
+    // Phase 1: create el$ and assign the element
+    let sharedRef$: ReturnType<typeof useRef$<HTMLSpanElement>>;
+    const { result: elResult } = renderHook(() => {
+      const el$ = useRef$<HTMLSpanElement>();
+      sharedRef$ = el$;
+      return el$;
+    });
+
+    act(() => { elResult.current(child); });
+
+    // Phase 2: pass the pre-assigned el$ to useParentElement
+    // useMount should pick up the existing element value immediately
+    const { result } = renderHook(() => useParentElement(sharedRef$!));
+
+    expect(result.current.get()).toBe(parent);
+  });
+
+  it("does NOT update when element's Observable value is unchanged (only DOM moved)", () => {
+    const child = document.createElement("span");
+    const { parent: parentA } = attachToBody(child);
+
+    const { result } = renderHook(() => useParentElement(wrapEl(child)));
+    expect(result.current.get()).toBe(parentA);
+
+    const parentB = document.createElement("div");
+    document.body.appendChild(parentB);
+    attached.push(parentB);
+    parentB.appendChild(child);
+
+    // plain element는 Observable이 아니므로 갱신되지 않음
+    expect(result.current.get()).toBe(parentA);
+  });
+
+  it("returns parent of an SVGElement", () => {
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    const circle = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+    svg.appendChild(circle);
+    document.body.appendChild(svg);
+    attached.push(svg);
+
+    const { result } = renderHook(() => useParentElement(circle as any));
+    expect(result.current.get()).toBe(svg);
+  });
+});

package/src/elements/useParentElement/index.ts

@@ -0,0 +1,35 @@
+import type { Observable, OpaqueObject } from "@legendapp/state";
+import { ObservableHint } from "@legendapp/state";
+import { useMount, useObservable, useObserve } from "@legendapp/state/react";
+import { getElement } from "../useRef$";
+import type { MaybeElement } from "../useRef$";
+
+export function useParentElement(
+  element?: MaybeElement,
+): Observable<OpaqueObject<HTMLElement | SVGElement> | null> {
+  const parent$ = useObservable<OpaqueObject<HTMLElement | SVGElement> | null>(
+    null,
+  );
+
+  /**
+   * NOTE: plain element (non-Observable, non-Ref$)을 전달한 경우,
+   * 해당 요소가 DOM 내에서 다른 부모로 이동하더라도 자동으로 갱신되지 않습니다.
+   * 동적 감지가 필요하면 Ref$ 또는 Observable<Element>를 사용하세요.
+   */
+  const update = () => {
+    if (!element) return;
+    const el = getElement(element as MaybeElement);
+    // Document / Window 는 parentElement 프로퍼티가 없으므로 null → SSR-safe
+    const parent = (el as HTMLElement | null)?.parentElement ?? null;
+    parent$.set(
+      parent
+        ? ObservableHint.opaque(parent as unknown as HTMLElement | SVGElement)
+        : null,
+    );
+  };
+
+  useMount(update);
+  useObserve(update, { immediate: false });
+
+  return parent$;
+}

package/src/elements/useRef$/index.md

@@ -0,0 +1,62 @@
+---
+title: useRef$
+category: elements
+---
+
+An observable element ref hook that serves as a drop-in replacement for `useRef`. Works with callback ref composition and `forwardRef` patterns. The element is wrapped with `opaqueObject` to prevent legendapp/state from deeply observing DOM properties.
+
+## Usage
+
+### Standalone (useRef replacement)
+
+```tsx
+import { useRef$ } from '@usels/core'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+
+  return <div ref={el$} />
+}
+```
+
+### Reactive access with useObserve
+
+Calling `el$.get()` inside `useObserve` automatically re-runs the observer when the element is mounted or unmounted.
+
+```tsx
+import { useObserve } from '@legendapp/state/react'
+import { useRef$ } from '@usels/core'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+
+  useObserve(() => {
+    const el = el$.get()
+    if (el) {
+      el.focus()
+    }
+  })
+
+  return <div ref={el$} />
+}
+```
+
+### forwardRef pattern
+
+```tsx
+import { forwardRef } from 'react'
+import { useRef$ } from '@usels/core'
+
+const Component = forwardRef<HTMLDivElement>((props, ref) => {
+  const el$ = useRef$(ref)
+
+  useObserve(() => {
+    const el = el$.get()
+    if (el) {
+      console.log('element mounted:', el)
+    }
+  })
+
+  return <div ref={el$} />
+})
+```

package/src/elements/useRef$/index.spec.ts

@@ -0,0 +1,205 @@
+// @vitest-environment jsdom
+import { render, renderHook, act } from "@testing-library/react";
+import { useObserve } from "@legendapp/state/react";
+import { createElement, createRef, forwardRef, useRef } from "react";
+import { describe, it, expect, vi } from "vitest";
+import { useRef$ } from ".";
+
+const noop = () => {};
+
+describe("useRef$()", () => {
+  it("initial value is null", () => {
+    const { result } = renderHook(() => useRef$<HTMLDivElement>(noop));
+    expect(result.current.get()).toBe(null);
+  });
+
+  it("registers element in observable when called with an element", () => {
+    const { result } = renderHook(() => useRef$<HTMLDivElement>(noop));
+    const div = document.createElement("div");
+
+    act(() => {
+      result.current(div);
+    });
+
+    expect(result.current.get()).toBe(div);
+  });
+
+  it("resets observable to null when called with null", () => {
+    const { result } = renderHook(() => useRef$<HTMLDivElement>(noop));
+    const div = document.createElement("div");
+
+    act(() => result.current(div));
+    act(() => result.current(null));
+
+    expect(result.current.get()).toBe(null);
+  });
+
+  it("el$ maintains stable reference across re-renders", () => {
+    const { result, rerender } = renderHook(() => useRef$<HTMLDivElement>(noop));
+    const el$1 = result.current;
+
+    rerender();
+
+    expect(result.current).toBe(el$1);
+  });
+
+  it("el$ is callable and exposes get/peek as functions", () => {
+    const { result } = renderHook(() => useRef$(noop));
+    expect(typeof result.current).toBe("function");
+    expect(typeof result.current.get).toBe("function");
+    expect(typeof result.current.peek).toBe("function");
+  });
+
+  it("calls externalRef first then updates observable", () => {
+    const callOrder: string[] = [];
+    const externalRef = vi.fn((_node: HTMLDivElement | null) => {
+      callOrder.push("externalRef");
+    });
+
+    const { result } = renderHook(() => useRef$<HTMLDivElement>(externalRef));
+    const div = document.createElement("div");
+
+    act(() => {
+      result.current(div);
+    });
+
+    expect(externalRef).toHaveBeenCalledWith(div);
+    expect(result.current.get()).toBe(div);
+    expect(callOrder[0]).toBe("externalRef"); // external runs first
+  });
+
+  it("uses latest externalRef after re-render", () => {
+    let currentRef = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ ref }) => useRef$<HTMLDivElement>(ref),
+      { initialProps: { ref: currentRef } }
+    );
+
+    const newRef = vi.fn();
+    rerender({ ref: newRef });
+
+    const div = document.createElement("div");
+    act(() => {
+      result.current(div);
+    });
+
+    expect(currentRef).not.toHaveBeenCalled();
+    expect(newRef).toHaveBeenCalledWith(div);
+  });
+
+  it("works without any argument (standalone useRef replacement)", () => {
+    const { result } = renderHook(() => useRef$<HTMLDivElement>());
+    const div = document.createElement("div");
+
+    act(() => result.current(div));
+
+    expect(result.current.get()).toBe(div);
+  });
+
+  it("syncs RefObject.current when RefObject is provided", () => {
+    const refObject = createRef<HTMLDivElement>();
+
+    const { result } = renderHook(() => useRef$<HTMLDivElement>(refObject));
+    const div = document.createElement("div");
+
+    act(() => result.current(div));
+
+    expect(refObject.current).toBe(div);
+    expect(result.current.get()).toBe(div);
+  });
+
+  it("clears RefObject.current to null on unmount", () => {
+    const refObject = createRef<HTMLDivElement>();
+
+    const { result } = renderHook(() => useRef$<HTMLDivElement>(refObject));
+    const div = document.createElement("div");
+
+    act(() => result.current(div));
+    act(() => result.current(null));
+
+    expect(refObject.current).toBe(null);
+    expect(result.current.get()).toBe(null);
+  });
+
+  it("handles null externalRef gracefully (forwardRef passing null)", () => {
+    const { result } = renderHook(() => useRef$<HTMLDivElement>(null));
+    const div = document.createElement("div");
+
+    act(() => result.current(div));
+
+    expect(result.current.get()).toBe(div);
+  });
+
+  it("updates latest RefObject when externalRef changes between renders", () => {
+    const { result, rerender } = renderHook(
+      ({ ref }) => useRef$<HTMLDivElement>(ref),
+      { initialProps: { ref: createRef<HTMLDivElement>() } }
+    );
+
+    const newRef = createRef<HTMLDivElement>();
+    rerender({ ref: newRef });
+
+    const div = document.createElement("div");
+    act(() => result.current(div));
+
+    expect(newRef.current).toBe(div);
+  });
+
+  it("can be used with useRef inside forwardRef pattern", () => {
+    const { result } = renderHook(() => {
+      const localRef = useRef<HTMLDivElement>(null);
+      return { el$: useRef$<HTMLDivElement>(localRef), localRef };
+    });
+
+    const div = document.createElement("div");
+    act(() => result.current.el$(div));
+
+    expect(result.current.localRef.current).toBe(div);
+    expect(result.current.el$.get()).toBe(div);
+  });
+
+  it("reactivity works inside forwardRef component", () => {
+    const observeSpy = vi.fn();
+
+    const Component = forwardRef<HTMLDivElement, object>((_, ref) => {
+      const el$ = useRef$(ref);
+      useObserve(() => {
+        el$.get();
+        observeSpy();
+      });
+      return createElement("div", { ref: el$ });
+    });
+
+    const parentRef = createRef<HTMLDivElement>();
+    render(createElement(Component, { ref: parentRef }));
+
+    // 1st: initial useObserve (el = null), 2nd: element assigned
+    expect(observeSpy).toHaveBeenCalledTimes(2);
+    expect(parentRef.current).not.toBe(null);
+  });
+
+  it("triggers useObserve when element is assigned", () => {
+    const observeSpy = vi.fn();
+
+    const { result } = renderHook(() => {
+      const el$ = useRef$<HTMLDivElement>(noop);
+      useObserve(() => {
+        el$.get(); // register as selector
+        observeSpy();
+      });
+      return el$;
+    });
+
+    // called once on mount
+    expect(observeSpy).toHaveBeenCalledTimes(1);
+
+    const div = document.createElement("div");
+    act(() => {
+      result.current(div);
+    });
+
+    // called again when element changes
+    expect(observeSpy).toHaveBeenCalledTimes(2);
+  });
+});

package/src/elements/useRef$/index.ts

@@ -0,0 +1,137 @@
+import { isObservable, ObservableHint } from "@legendapp/state";
+import type { Observable, OpaqueObject } from "@legendapp/state";
+import { useObservable } from "@legendapp/state/react";
+import { type Ref, type RefObject, useMemo, useRef } from "react";
+import { isWindow } from "../../shared";
+
+export type Ref$<T> = ((node: T | null) => void) & {
+  /** returns element, registers tracking when called inside useObserve */
+  get(): OpaqueObject<T> | null;
+  /** returns element without registering tracking */
+  peek(): OpaqueObject<T> | null;
+};
+
+/**
+ * A value that resolves to an Element, Document, Window, or null.
+ *
+ * - `Ref$<T>` — React-managed element ref (created via `useRef$()`). Primary choice.
+ * - `Document` / `Window` — stable global singletons, always safe to pass raw.
+ * - `Observable<OpaqueObject<Element> | null>` — for imperatively obtained elements.
+ *   Use `ObservableHint.opaque(el)` when storing: `observable(ObservableHint.opaque(el))`.
+ *
+ * Raw `HTMLElement` is intentionally excluded: in React's render model, elements
+ * don't exist at hook call time, making raw element references inherently stale.
+ */
+export type MaybeElement =
+  | Ref$<any>
+  | Document
+  | Window
+  | null
+  | Observable<OpaqueObject<Element> | null>;
+
+/**
+ * Creates an observable element ref. Can be used as a drop-in replacement for
+ * `useRef`, composed with callback refs, or used with `forwardRef`.
+ *
+ * The element is wrapped with `opaqueObject` to prevent legendapp/state
+ * from making DOM properties reactive (deep observation).
+ *
+ * @param externalRef - Optional. Accepts callback ref, RefObject, or null (forwardRef compatible).
+ * @returns A callable ref that is also observable via `get`/`peek`
+ *
+ * @example
+ * ```tsx
+ * // standalone — useRef replacement
+ * const el$ = useRef$<HTMLDivElement>();
+ * return <div ref={el$} />;
+ *
+ * // forwardRef compatible
+ * const Component = forwardRef<HTMLDivElement>((props, ref) => {
+ *   const el$ = useRef$(ref);
+ *   return <div ref={el$} />;
+ * });
+ *
+ * // callback ref composition
+ * const myRef = useCallback((node: HTMLDivElement | null) => {
+ *   node?.focus();
+ * }, []);
+ * const el$ = useRef$(myRef);
+ * return <div ref={el$} />;
+ * ```
+ */
+export function useRef$<T extends Element = Element>(
+  externalRef?: Ref<T> | null,
+): Ref$<T> {
+  const el$ = useObservable<OpaqueObject<T> | null>(null);
+
+  // store externalRef — simple assignment each render, no new closure
+  const extRef = useRef(externalRef);
+  extRef.current = externalRef;
+
+  return useMemo(
+    () =>
+      Object.assign(
+        (node: T | null) => {
+          const ext = extRef.current;
+          if (typeof ext === "function") {
+            ext(node);
+          } else if (ext != null && "current" in ext) {
+            (ext as RefObject<T | null>).current = node;
+          }
+          (el$ as any).set(node ? ObservableHint.opaque(node) : null);
+        },
+        {
+          get: () => el$.get(),
+          peek: () => el$.peek(),
+        },
+      ) as Ref$<T>,
+    [], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+}
+
+/** Type guard for Ref$ — distinguishes it from Observable and raw values */
+export function isRef$(v: unknown): v is Ref$<Element> {
+  return (
+    typeof v === "function" && !isObservable(v) && "get" in v && "peek" in v
+  );
+}
+
+/** Unwraps MaybeElement with tracking (use inside useObserve) */
+export function getElement(
+  v: MaybeElement,
+): HTMLElement | Document | Window | null {
+  if (isRef$(v)) {
+    const raw = v.get();
+    return raw
+      ? ((raw as OpaqueObject<Element>).valueOf() as HTMLElement)
+      : null;
+  }
+  if (isWindow(v)) return v;
+  if (isObservable(v)) {
+    const val = (v as Observable<OpaqueObject<Element> | null>).get();
+    return val
+      ? ((val as OpaqueObject<Element>).valueOf() as HTMLElement)
+      : null;
+  }
+  return v as Document | null;
+}
+
+/** Unwraps MaybeElement without tracking (use inside setup/peek) */
+export function peekElement(
+  v: MaybeElement,
+): HTMLElement | Document | Window | null {
+  if (isRef$(v)) {
+    const raw = v.peek();
+    return raw
+      ? ((raw as OpaqueObject<Element>).valueOf() as HTMLElement)
+      : null;
+  }
+  if (isWindow(v)) return v;
+  if (isObservable(v)) {
+    const val = (v as Observable<OpaqueObject<Element> | null>).peek();
+    return val
+      ? ((val as OpaqueObject<Element>).valueOf() as HTMLElement)
+      : null;
+  }
+  return v as Document | null;
+}