@usels/core 0.0.1

package/src/function/useMayObservableOptions/index.ts

@@ -0,0 +1,173 @@
+import {
+  isObservable,
+  ObservableHint,
+  type Observable,
+} from "@legendapp/state";
+import { useObservable } from "@legendapp/state/react";
+import { useMemo, useRef } from "react";
+import { get } from "../get";
+import { peek } from "../peek";
+import type { DeepMaybeObservable, MaybeObservable } from "../../types";
+import { getElement, peekElement } from "../../elements/useRef$";
+import type { MaybeElement } from "../../elements/useRef$";
+
+/**
+ * Per-field resolution hint for the object-form transform.
+ *
+ * Resolution axis (`get` / `peek`):
+ * - `'get'`          — no-op; Legend-State auto-derefs the field Observable and registers the dep at the call site. **Default.**
+ * - `'peek'`         — `peek(fieldValue)` — no dep, mount-time-only snapshot.
+ *
+ * Legend-State wrapping axis (dot-notation):
+ * - `'get.opaque'`   — `get()` then `ObservableHint.opaque()`. Null-safe.
+ * - `'get.plain'`    — `get()` then `ObservableHint.plain()`. Prevents nested auto-deref. Null-safe.
+ * - `'get.function'` — `get()` then `ObservableHint.function()`. For callbacks. Null-safe.
+ * - `'get.element'`  — `getElement(fieldValue)` (reactive) then `ObservableHint.opaque()`. For MaybeElement.
+ * - `'peek.element'` — `peekElement(fieldValue)` (non-reactive) then `ObservableHint.opaque()`. For MaybeElement.
+ *
+ * Escape hatch:
+ * - `(value) => R`   — custom transform function.
+ */
+export type FieldHint<V = any, R = any> =
+  | "get"
+  | "peek"
+  | "get.opaque"
+  | "get.plain"
+  | "get.function"
+  | "get.element"
+  | "peek.element"
+  | ((value: MaybeObservable<V>) => R);
+
+/**
+ * Maps each field of `T` to a `FieldHint`.
+ * Fields not specified default to `'get'` (reactive resolution via Legend-State auto-deref).
+ */
+export type FieldTransformMap<T> = {
+  [K in keyof T]?: FieldHint<T[K], any>;
+};
+
+/**
+ * The `transform` parameter for `useMayObservableOptions`.
+ * - **Object form:** declarative per-field hints — `FieldTransformMap<T>`.
+ * - **Function form:** full custom compute — `(current) => T | undefined`.
+ */
+export type Transform<T> =
+  | FieldTransformMap<T>
+  | ((current: DeepMaybeObservable<T> | undefined) => T | undefined);
+
+function applyObjectTransform<T>(
+  raw: T | undefined,
+  map: FieldTransformMap<T>,
+): T | undefined {
+  if (raw == null) return undefined;
+  const result = { ...raw } as Record<string, unknown>;
+  for (const key of Object.keys(result)) {
+    const hint = (map as Record<string, FieldHint>)[key];
+    const fieldValue = result[key] as MaybeObservable<unknown>;
+    switch (hint) {
+      case "peek":
+        result[key] = peek(fieldValue);
+        break;
+      case "get.opaque": {
+        const v = get(fieldValue);
+        if (v != null) result[key] = ObservableHint.opaque(v);
+        break;
+      }
+      case "get.plain": {
+        const v = get(fieldValue);
+        if (v != null) result[key] = ObservableHint.plain(v as object);
+        break;
+      }
+      case "get.function": {
+        const v = get(fieldValue);
+        if (v != null)
+          result[key] = ObservableHint.function(
+            v as (...args: unknown[]) => unknown,
+          );
+        break;
+      }
+      case "get.element": {
+        if (fieldValue !== undefined) {
+          // Observable resolving to undefined means "not set" — propagate undefined
+          if (isObservable(fieldValue) && (fieldValue as Observable<unknown>).get() === undefined) {
+            result[key] = undefined;
+            break;
+          }
+          const el = getElement(fieldValue as MaybeElement);
+          result[key] = el != null ? ObservableHint.opaque(el) : null;
+        }
+        break;
+      }
+      case "peek.element": {
+        if (fieldValue !== undefined) {
+          // Observable resolving to undefined means "not set" — propagate undefined
+          if (isObservable(fieldValue) && (fieldValue as Observable<unknown>).peek() === undefined) {
+            result[key] = undefined;
+            break;
+          }
+          const el = peekElement(fieldValue as MaybeElement);
+          result[key] = el != null ? ObservableHint.opaque(el) : null;
+        }
+        break;
+      }
+      default:
+        if (typeof hint === "function") {
+          result[key] = hint(fieldValue);
+        }
+        // 'get' or undefined → no action; Legend-State auto-derefs per-field Observables
+    }
+  }
+  return result as T;
+}
+
+/**
+ * Normalizes `DeepMaybeObservable<T>` into a stable computed `Observable<T | undefined>`.
+ *
+ * Handles three cases without interference:
+ * - **Outer `Observable<T>`** — tracked via `.get()` dep inside the compute fn
+ * - **Per-field `{ field: Observable<T[K]> }`** — tracked via explicit `get()` per field
+ * - **Plain value changing between renders** — tracked via Symbol depKey (React-level)
+ *
+ * The Symbol depKey prevents Legend-State from auto-deref'ing inner Observables
+ * inside `depsObs$`, which would break per-field dep tracking if the raw `options`
+ * object were passed directly as the dep array item.
+ *
+ * @param options - DeepMaybeObservable options to normalize
+ * @param transform - Optional transform. Two forms:
+ *   - **Object form:** `FieldTransformMap<T>` — per-field hints (`'peek'`, `'get.opaque'`, etc.).
+ *     Defaults to `'get'` for unspecified fields.
+ *     **Note:** has no effect when `options` is an outer `Observable<T>` — in that case the
+ *     proxy is returned as-is (same as no transform), preserving Legend-State's
+ *     reference-equality tracking behavior. Use per-field Observables or plain objects
+ *     when field-level hints are needed.
+ *   - **Function form:** `(current) => T | undefined` — full custom compute for complex cases.
+ */
+export function useMayObservableOptions<T>(
+  options: DeepMaybeObservable<T> | undefined,
+  transform?: Transform<T>,
+): Observable<T | undefined> {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const depKey = useMemo(() => Symbol(), [options]);
+  const compute = (): T | undefined => {
+    if (typeof transform === "function") {
+      return transform(optionsRef.current);
+    }
+    const raw = optionsRef.current;
+    const resolved = get(raw as MaybeObservable<T> | undefined);
+    if (transform != null && !isObservable(raw)) {
+      // Object form — only applies when options is NOT an outer Observable.
+      // For outer Observable, returning the proxy as-is preserves the
+      // "reference-equality tracking" behavior: child-field mutations do not
+      // trigger opts$ recomputation (documented known Legend-State limitation).
+      // For per-field Observable or plain object, apply field hints.
+      return applyObjectTransform(resolved, transform);
+    }
+    return resolved;
+  };
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useObservable(compute, [depKey]) as unknown as Observable<
+    T | undefined
+  >;
+}

package/src/function/useSupported/index.md

@@ -0,0 +1,43 @@
+---
+title: useSupported
+description: SSR-safe browser feature detection as a reactive Observable
+category: Browser Utilities
+---
+
+Check whether a browser API or feature is supported, returning a reactive `Observable<boolean>` that re-evaluates after the component mounts. Safe to use during SSR — the value is always `false` on the server and updates on the client after hydration.
+
+## Usage
+
+```typescript
+import { useSupported } from '@usels/core'
+
+const isMatchMediaSupported = useSupported(() => 'matchMedia' in window)
+
+// Use the observable value
+if (isMatchMediaSupported.get()) {
+  // matchMedia is available
+}
+```
+
+### With Legend-State reactive bindings
+
+```typescript
+import { useSupported } from '@usels/core'
+import { Memo } from '@legendapp/state/react'
+
+const isIntersectionObserverSupported = useSupported(
+  () => 'IntersectionObserver' in window
+)
+
+function MyComponent() {
+  return (
+    <Memo>
+      {() =>
+        isIntersectionObserverSupported.get()
+          ? <FeatureComponent />
+          : <Fallback />
+      }
+    </Memo>
+  )
+}
+```

package/src/function/useSupported/index.spec.ts

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+import { renderHook, act } from "@testing-library/react";
+import { observable } from "@legendapp/state";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { useSupported } from ".";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// useSupported — return value
+// ---------------------------------------------------------------------------
+
+describe("useSupported() — return value", () => {
+  it("returns an Observable", () => {
+    const { result } = renderHook(() => useSupported(() => true));
+    expect(typeof result.current.get).toBe("function");
+  });
+
+  it("returns true when callback returns a truthy value", () => {
+    const { result } = renderHook(() => useSupported(() => true));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("returns false when callback returns a falsy value", () => {
+    const { result } = renderHook(() => useSupported(() => false));
+    expect(result.current.get()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useSupported — Boolean coercion
+// ---------------------------------------------------------------------------
+
+describe("useSupported() — Boolean coercion", () => {
+  it("coerces a non-empty string to true", () => {
+    const { result } = renderHook(() => useSupported(() => "supported"));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("coerces an object to true", () => {
+    const { result } = renderHook(() => useSupported(() => ({})));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("coerces 1 to true", () => {
+    const { result } = renderHook(() => useSupported(() => 1));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("coerces 0 to false", () => {
+    const { result } = renderHook(() => useSupported(() => 0));
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("coerces null to false", () => {
+    const { result } = renderHook(() => useSupported(() => null));
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("coerces undefined to false", () => {
+    const { result } = renderHook(() => useSupported(() => undefined));
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("coerces empty string to false", () => {
+    const { result } = renderHook(() => useSupported(() => ""));
+    expect(result.current.get()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useSupported — mount re-evaluation
+// ---------------------------------------------------------------------------
+
+describe("useSupported() — mount re-evaluation", () => {
+  it("invokes the callback when the observable value is accessed", () => {
+    // useObservable with a selector is lazy — callback runs on .get(), not at creation
+    const callback = vi.fn(() => true);
+    const { result } = renderHook(() => useSupported(callback));
+    result.current.get();
+    expect(callback).toHaveBeenCalled();
+  });
+
+  it("re-evaluates when a reactive dependency inside the callback changes", () => {
+    // callback reads an observable — Legend State tracks it as a dependency
+    const flag$ = observable(false);
+    const { result } = renderHook(() => useSupported(() => flag$.get()));
+
+    expect(result.current.get()).toBe(false);
+
+    act(() => flag$.set(true));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("reflects a browser API check after mount", () => {
+    const { result } = renderHook(() =>
+      useSupported(() => "matchMedia" in window),
+    );
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("returns false for an unavailable browser API after mount", () => {
+    const win = globalThis.window as any;
+    const original = win.matchMedia;
+    delete win.matchMedia;
+
+    const { result } = renderHook(() =>
+      useSupported(() => "matchMedia" in window),
+    );
+    expect(result.current.get()).toBe(false);
+
+    win.matchMedia = original;
+  });
+});

package/src/function/useSupported/index.ts

@@ -0,0 +1,14 @@
+import { Observable } from "@legendapp/state";
+import { useIsMounted, useObservable } from "@legendapp/state/react";
+
+export type UseSupportedReturn = Observable<boolean>;
+
+/* @__NO_SIDE_EFFECTS__ */
+export function useSupported(callback: () => unknown): UseSupportedReturn {
+  const isMounted = useIsMounted();
+
+  return useObservable(() => {
+    if (!isMounted.get()) return false;
+    return Boolean(callback());
+  });
+}

package/src/function/useWhenMounted/index.md

@@ -0,0 +1,25 @@
+---
+title: useWhenMounted
+category: Browser Utilities
+---
+
+Execute a callback and expose its return value as a reactive `Observable<T | undefined>` — only after the component has mounted. Returns `undefined` during SSR and before hydration, then re-evaluates with the actual callback value once mounted. Unlike `useSupported`, the return value is not coerced to boolean — the full type `T` is preserved.
+
+## Usage
+
+```typescript
+import { useWhenMounted } from '@usels/core'
+
+const windowWidth = useWhenMounted(() => window.innerWidth)
+
+// undefined on the server, actual width after mount
+console.log(windowWidth.get())
+```
+
+### Deferred browser API access
+
+```typescript
+import { useWhenMounted } from '@usels/core'
+
+const scrollY = useWhenMounted(() => window.scrollY)
+```

package/src/function/useWhenMounted/index.spec.ts

@@ -0,0 +1,120 @@
+// @vitest-environment jsdom
+import { renderHook, act } from "@testing-library/react";
+import { observable } from "@legendapp/state";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { useWhenMounted } from ".";
+
+// Shared observable that controls the mocked isMounted state.
+// Initialized in beforeEach so each test starts with a fresh observable.
+let isMounted$: ReturnType<typeof observable<boolean>>;
+
+vi.mock("@legendapp/state/react", async () => {
+  const actual = await import("@legendapp/state/react");
+  return {
+    ...actual,
+    // Return the shared observable lazily — evaluated at call time, not setup time
+    useIsMounted: () => isMounted$,
+  };
+});
+
+beforeEach(() => {
+  isMounted$ = observable(true); // default: mounted
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// useWhenMounted — return value
+// ---------------------------------------------------------------------------
+
+describe("useWhenMounted() — return value", () => {
+  it("returns an Observable", () => {
+    const { result } = renderHook(() => useWhenMounted(() => "hello"));
+    expect(typeof result.current.get).toBe("function");
+  });
+
+  it("returns the callback value when mounted", () => {
+    const { result } = renderHook(() => useWhenMounted(() => "hello"));
+    expect(result.current.get()).toBe("hello");
+  });
+
+  it("returns undefined when not mounted", () => {
+    isMounted$.set(false);
+    const { result } = renderHook(() => useWhenMounted(() => "hello"));
+    expect(result.current.get()).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useWhenMounted — type preservation (no boolean coercion)
+// ---------------------------------------------------------------------------
+
+describe("useWhenMounted() — type preservation", () => {
+  it("returns false as-is (no boolean coercion)", () => {
+    const { result } = renderHook(() => useWhenMounted(() => false));
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("returns 0 as-is", () => {
+    const { result } = renderHook(() => useWhenMounted(() => 0));
+    expect(result.current.get()).toBe(0);
+  });
+
+  it("returns a string as-is", () => {
+    const { result } = renderHook(() => useWhenMounted(() => "value"));
+    expect(result.current.get()).toBe("value");
+  });
+
+  it("returns a number as-is", () => {
+    const { result } = renderHook(() => useWhenMounted(() => 42));
+    expect(result.current.get()).toBe(42);
+  });
+
+  it("returns an object reference", () => {
+    const obj = { foo: "bar" };
+    const { result } = renderHook(() => useWhenMounted(() => obj));
+    expect(result.current.get()).toEqual({ foo: "bar" });
+  });
+
+  // Legend State observables treat null as an empty/deleted value and normalize it to undefined
+  it("normalizes null to undefined (Legend State behavior)", () => {
+    const { result } = renderHook(() => useWhenMounted(() => null));
+    expect(result.current.get()).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useWhenMounted — reactive re-evaluation
+// ---------------------------------------------------------------------------
+
+describe("useWhenMounted() — reactive re-evaluation", () => {
+  it("invokes the callback when the observable value is accessed", () => {
+    const callback = vi.fn(() => "value");
+    const { result } = renderHook(() => useWhenMounted(callback));
+    result.current.get();
+    expect(callback).toHaveBeenCalled();
+  });
+
+  it("re-evaluates when a reactive dependency inside the callback changes", () => {
+    const count$ = observable(1);
+    const { result } = renderHook(() =>
+      useWhenMounted(() => count$.get() * 2),
+    );
+
+    expect(result.current.get()).toBe(2);
+
+    act(() => count$.set(5));
+    expect(result.current.get()).toBe(10);
+  });
+
+  it("transitions from undefined to callback value when isMounted becomes true", () => {
+    isMounted$.set(false);
+    const { result } = renderHook(() => useWhenMounted(() => "ready"));
+    expect(result.current.get()).toBeUndefined();
+
+    act(() => isMounted$.set(true));
+    expect(result.current.get()).toBe("ready");
+  });
+});

package/src/function/useWhenMounted/index.ts

@@ -0,0 +1,16 @@
+import type { Observable } from "@legendapp/state";
+import { useIsMounted, useObservable } from "@legendapp/state/react";
+
+export type UseWhenMountedReturn<T> = Observable<T | undefined>;
+
+/* @__NO_SIDE_EFFECTS__ */
+export function useWhenMounted<T>(
+  callback: () => T,
+): UseWhenMountedReturn<T> {
+  const isMounted = useIsMounted();
+
+  return useObservable(() => {
+    if (!isMounted.get()) return undefined;
+    return callback();
+  }) as unknown as Observable<T | undefined>;
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from "./types";
+
+export * from "./function/get";
+export * from "./function/peek";
+export * from "./function/useSupported";
+export * from "./function/useWhenMounted";
+
+export * from "./elements/useRef$";
+export * from "./elements/useResizeObserver";
+export * from "./elements/useElementSize";
+export * from "./elements/useElementBounding";
+export * from "./elements/useMutationObserver";
+export * from "./elements/useIntersectionObserver";
+export * from "./elements/useElementVisibility";
+export * from "./elements/useDocumentVisibility";
+export * from "./elements/useWindowFocus";
+export * from "./elements/useWindowSize";
+export * from "./elements/useParentElement";
+export * from "./elements/useMouseInElement";
+
+export * from "./sensors/useScroll";
+export * from "./sensors/useWindowScroll";
+
+export * from "./browser/useEventListener";
+export * from "./browser/useMediaQuery";

package/src/sensors/useScroll/demo.tsx

@@ -0,0 +1,103 @@
+import { Computed } from "@legendapp/state/react";
+import { useRef$ } from "../../elements/useRef$";
+import { useScroll } from ".";
+
+const badge = (active: boolean): React.CSSProperties => ({
+  display: "inline-flex",
+  alignItems: "center",
+  padding: "2px 8px",
+  borderRadius: "4px",
+  fontSize: "12px",
+  fontFamily: "monospace",
+  background: active
+    ? "var(--sl-color-green-low, #f0fdf4)"
+    : "var(--sl-color-gray-5, #f1f5f9)",
+  color: active
+    ? "var(--sl-color-green, #16a34a)"
+    : "var(--sl-color-gray-3, #64748b)",
+  border: `1px solid ${active ? "var(--sl-color-green, #22c55e)" : "var(--sl-color-gray-4, #e2e8f0)"}`,
+  transition: "all 0.15s",
+});
+
+export default function UseScrollDemo() {
+  const el$ = useRef$<HTMLDivElement>();
+  const { x, y, isScrolling, arrivedState, directions } = useScroll(el$);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "10px" }}>
+      {/* Stats */}
+      <Computed>
+        {() => (
+          <div
+            style={{
+              display: "flex",
+              flexWrap: "wrap",
+              gap: "8px",
+              padding: "8px 12px",
+              borderRadius: "6px",
+              border: "1px solid var(--sl-color-gray-5, #e2e8f0)",
+              background: "var(--sl-color-gray-6, #f8fafc)",
+              fontFamily: "monospace",
+              fontSize: "13px",
+            }}
+          >
+            <span>
+              x: <strong>{x.get()}</strong>
+            </span>
+            <span>
+              y: <strong>{y.get()}</strong>
+            </span>
+            <span style={badge(isScrolling.get())}>
+              {isScrolling.get() ? "scrolling" : "idle"}
+            </span>
+            <span style={badge(arrivedState.top.get())}>top</span>
+            <span style={badge(arrivedState.bottom.get())}>bottom</span>
+            <span style={{ color: "var(--sl-color-gray-3, #94a3b8)" }}>
+              {directions.top.get() && "↑"}
+              {directions.bottom.get() && "↓"}
+              {directions.left.get() && "←"}
+              {directions.right.get() && "→"}
+            </span>
+          </div>
+        )}
+      </Computed>
+
+      {/* Scrollable container */}
+      <div
+        ref={el$}
+        style={{
+          height: "200px",
+          overflowY: "auto",
+          borderRadius: "6px",
+          border: "1px solid var(--sl-color-gray-5, #e2e8f0)",
+          background: "var(--sl-color-gray-7, #fff)",
+        }}
+      >
+        {Array.from({ length: 20 }, (_, i) => (
+          <div
+            key={i}
+            style={{
+              padding: "8px 14px",
+              borderBottom: "1px solid var(--sl-color-gray-6, #f1f5f9)",
+              fontSize: "13px",
+              color: "var(--sl-color-gray-2, #475569)",
+              fontFamily: "monospace",
+            }}
+          >
+            Item {i + 1}
+          </div>
+        ))}
+      </div>
+
+      <p
+        style={{
+          margin: 0,
+          fontSize: "11px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+        }}
+      >
+        Scroll inside the box to see x, y, arrivedState, and directions update.
+      </p>
+    </div>
+  );
+}