@usels/core 0.0.1-beta.3

package/src/sensors/useScroll/index.ts

@@ -0,0 +1,201 @@
+"use client";
+import type { Observable } from "@legendapp/state";
+import { useMount, useObservable } from "@legendapp/state/react";
+import { useMemo, useRef } from "react";
+import { throttle } from "es-toolkit";
+import { type MaybeElement, peekElement } from "../../elements/useRef$";
+import { isWindow } from "../../shared";
+import type { MaybeObservable } from "../../types";
+import { useEventListener } from "../../browser/useEventListener";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface UseScrollOptions {
+  throttle?: number;
+  idle?: number;
+  onStop?: () => void;
+  onError?: (error: unknown) => void;
+  offset?: {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+  };
+  behavior?: ScrollBehavior;
+  eventListenerOptions?: MaybeObservable<AddEventListenerOptions>;
+}
+
+export interface ArrivedState {
+  left: boolean;
+  right: boolean;
+  top: boolean;
+  bottom: boolean;
+}
+
+export interface ScrollDirections {
+  left: boolean;
+  right: boolean;
+  top: boolean;
+  bottom: boolean;
+}
+
+export interface UseScrollReturn {
+  x$: Observable<number>;
+  y$: Observable<number>;
+  isScrolling$: Observable<boolean>;
+  arrivedState$: Observable<ArrivedState>;
+  directions$: Observable<ScrollDirections>;
+  measure: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getScrollValues(el: HTMLElement | Document | Window | null): {
+  x: number;
+  y: number;
+} {
+  if (!el) return { x: 0, y: 0 };
+  if (isWindow(el)) return { x: el.scrollX, y: el.scrollY };
+  if (el instanceof Document)
+    return {
+      x: el.documentElement.scrollLeft,
+      y: el.documentElement.scrollTop,
+    };
+  return { x: el.scrollLeft, y: el.scrollTop };
+}
+
+function getScrollDimensions(el: HTMLElement | Document | Window | null): {
+  scrollW: number;
+  scrollH: number;
+  clientW: number;
+  clientH: number;
+} {
+  if (!el || isWindow(el)) {
+    return {
+      scrollW: document.documentElement.scrollWidth,
+      scrollH: document.documentElement.scrollHeight,
+      clientW: window.innerWidth,
+      clientH: window.innerHeight,
+    };
+  }
+  if (el instanceof Document) {
+    const root = el.documentElement;
+    return {
+      scrollW: root.scrollWidth,
+      scrollH: root.scrollHeight,
+      clientW: root.clientWidth,
+      clientH: root.clientHeight,
+    };
+  }
+  return {
+    scrollW: el.scrollWidth,
+    scrollH: el.scrollHeight,
+    clientW: el.clientWidth,
+    clientH: el.clientHeight,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function useScroll(
+  element: MaybeElement,
+  options?: UseScrollOptions,
+): UseScrollReturn {
+  const initial = getScrollValues(peekElement(element));
+
+  const x$ = useObservable<number>(initial.x);
+  const y$ = useObservable<number>(initial.y);
+  const isScrolling$ = useObservable<boolean>(false);
+  const arrivedState$ = useObservable<ArrivedState>({
+    left: true,
+    right: false,
+    top: true,
+    bottom: false,
+  });
+  const directions$ = useObservable<ScrollDirections>({
+    left: false,
+    right: false,
+    top: false,
+    bottom: false,
+  });
+
+  const idleTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const resetIdle = () => {
+    if (idleTimer.current) clearTimeout(idleTimer.current);
+    isScrolling$.set(true);
+    idleTimer.current = setTimeout(() => {
+      isScrolling$.set(false);
+      options?.onStop?.();
+    }, options?.idle ?? 200);
+  };
+
+  const measure = () => {
+    const el = peekElement(element);
+    if (!el) return;
+
+    const prevX = x$.peek();
+    const prevY = y$.peek();
+    const { x: newX, y: newY } = getScrollValues(el);
+
+    directions$.assign({
+      left: newX < prevX,
+      right: newX > prevX,
+      top: newY < prevY,
+      bottom: newY > prevY,
+    });
+
+    x$.set(newX);
+    y$.set(newY);
+
+    const { scrollW, scrollH, clientW, clientH } = getScrollDimensions(el);
+    const maxX = scrollW - clientW;
+    const maxY = scrollH - clientH;
+    const offset = options?.offset ?? {};
+
+    arrivedState$.assign({
+      left: newX <= (offset.left ?? 0),
+      right: newX >= maxX - (offset.right ?? 0),
+      top: newY <= (offset.top ?? 0),
+      bottom: newY >= maxY - (offset.bottom ?? 0),
+    });
+
+    resetIdle();
+  };
+
+  const measureRef = useRef(measure);
+  measureRef.current = measure;
+
+  const handler = useMemo(() => {
+    const ms = options?.throttle ?? 0;
+    return ms > 0
+      ? throttle(() => measureRef.current(), ms)
+      : () => measureRef.current();
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEventListener(element as any, "scroll", handler,
+    options?.eventListenerOptions ?? { capture: false, passive: true },
+  );
+
+  useMount(() => {
+    measure();
+    return () => {
+      if (idleTimer.current) clearTimeout(idleTimer.current);
+    };
+  });
+
+  return {
+    x$,
+    y$,
+    isScrolling$,
+    arrivedState$,
+    directions$,
+    measure,
+  };
+}

package/src/sensors/useWindowScroll/demo.tsx

@@ -0,0 +1,69 @@
+import { useWindowScroll } from ".";
+
+const card: React.CSSProperties = {
+  display: "flex",
+  flexWrap: "wrap",
+  gap: "16px",
+  padding: "10px 14px",
+  borderRadius: "6px",
+  border: "1px solid var(--sl-color-gray-5, #e2e8f0)",
+  background: "var(--sl-color-gray-6, #f8fafc)",
+  fontFamily: "monospace",
+  fontSize: "13px",
+};
+
+const chip = (active: boolean): React.CSSProperties => ({
+  padding: "2px 8px",
+  borderRadius: "4px",
+  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-5, #e2e8f0)"}`,
+  transition: "all 0.15s",
+});
+
+export default function UseWindowScrollDemo() {
+  const { x$, y$, isScrolling$, arrivedState$, directions$ } = useWindowScroll();
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "8px" }}>
+      <div style={card}>
+        <span>
+          x: <strong>{x$.get()}</strong>
+        </span>
+        <span>
+          y: <strong>{y$.get()}</strong>
+        </span>
+        <span style={chip(isScrolling$.get())}>
+          {isScrolling$.get() ? "scrolling" : "idle"}
+        </span>
+      </div>
+
+      <div style={card}>
+        <span style={chip(arrivedState$.top.get())}>top</span>
+        <span style={chip(arrivedState$.bottom.get())}>bottom</span>
+        <span style={chip(arrivedState$.left.get())}>left</span>
+        <span style={chip(arrivedState$.right.get())}>right</span>
+        <span style={{ color: "var(--sl-color-gray-3, #94a3b8)" }}>
+          {directions$.top.get() && "↑ "}
+          {directions$.bottom.get() && "↓ "}
+          {directions$.left.get() && "← "}
+          {directions$.right.get() && "→ "}
+        </span>
+      </div>
+
+      <p
+        style={{
+          margin: 0,
+          fontSize: "11px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+        }}
+      >
+        Scroll the page to see the values update in real time.
+      </p>
+    </div>
+  );
+}

package/src/sensors/useWindowScroll/index.md

@@ -0,0 +1,88 @@
+---
+title: useWindowScroll
+category: sensors
+---
+
+Tracks the window scroll position, direction, arrived state, and scrolling status as reactive `Observable` values. A convenience wrapper around `useScroll(window)`.
+
+## Demo
+
+## Usage
+
+### Basic
+
+```tsx twoslash
+// @noErrors
+import { useWindowScroll } from '@usels/core'
+
+function Component() {
+  const { x, y, arrivedState } = useWindowScroll()
+
+  return (
+    <p>
+      scrollX: {x.get()}, scrollY: {y.get()}
+      {arrivedState.bottom.get() && ' — reached bottom'}
+    </p>
+  )
+}
+```
+
+### Back-to-top button
+
+```tsx twoslash
+// @noErrors
+import { useWindowScroll } from '@usels/core'
+
+function BackToTop() {
+  const { arrivedState } = useWindowScroll()
+
+  return (
+    !arrivedState.top.get() ? (
+      <button onClick={() => window.scrollTo({ top: 0, behavior: 'smooth' })}>
+        ↑ Back to top
+      </button>
+    ) : null
+  )
+}
+```
+
+### Scroll direction indicator
+
+```tsx
+const { directions } = useWindowScroll()
+// directions.bottom.get() → true while scrolling down
+// directions.top.get()    → true while scrolling up
+```
+
+### Infinite scroll trigger
+
+```typescript
+import { useObserveEffect } from '@legendapp/state/react'
+
+const { arrivedState } = useWindowScroll({ offset: { bottom: 200 } })
+
+useObserveEffect(arrivedState.bottom, (e) => {
+  if (e.value) fetchNextPage()
+})
+```
+
+### isScrolling + onStop
+
+```typescript
+const { isScrolling } = useWindowScroll({
+  idle: 300,
+  onStop: () => saveScrollPosition(),
+})
+```
+
+### Throttled updates
+
+```typescript
+const { y } = useWindowScroll({ throttle: 100 })
+```
+
+## Notes
+
+**SSR-safe.** When `window` is not available (SSR), `useWindowScroll` passes `null` to `useScroll`, so all observables hold initial values (`x: 0`, `y: 0`, `isScrolling: false`) and no event listener is registered.
+
+See [`useScroll`](/sensors/use-scroll) for the full API reference including all options.

package/src/sensors/useWindowScroll/index.spec.ts

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+import { renderHook } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { useWindowScroll } from ".";
+import * as useScrollModule from "../useScroll";
+
+describe("useWindowScroll()", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    Object.defineProperty(window, "scrollX", {
+      writable: true,
+      configurable: true,
+      value: 0,
+    });
+    Object.defineProperty(window, "scrollY", {
+      writable: true,
+      configurable: true,
+      value: 0,
+    });
+    Object.defineProperty(window, "innerWidth", {
+      writable: true,
+      configurable: true,
+      value: 1024,
+    });
+    Object.defineProperty(window, "innerHeight", {
+      writable: true,
+      configurable: true,
+      value: 768,
+    });
+    Object.defineProperty(document.documentElement, "scrollWidth", {
+      writable: true,
+      configurable: true,
+      value: 1024,
+    });
+    Object.defineProperty(document.documentElement, "scrollHeight", {
+      writable: true,
+      configurable: true,
+      value: 2000,
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("calls useScroll internally with window as target", () => {
+    const spy = vi.spyOn(useScrollModule, "useScroll");
+    renderHook(() => useWindowScroll());
+    expect(spy).toHaveBeenCalledWith(window, undefined);
+  });
+
+  it("options are forwarded to useScroll as-is", () => {
+    const spy = vi.spyOn(useScrollModule, "useScroll");
+    const options = { idle: 500, throttle: 100 };
+    renderHook(() => useWindowScroll(options));
+    expect(spy).toHaveBeenCalledWith(window, options);
+  });
+
+  it("returns an object matching UseScrollReturn shape", () => {
+    const { result } = renderHook(() => useWindowScroll());
+    expect(typeof result.current.x$.get).toBe("function");
+    expect(typeof result.current.y$.get).toBe("function");
+    expect(typeof result.current.isScrolling$.get).toBe("function");
+    expect(typeof result.current.arrivedState$.get).toBe("function");
+    expect(typeof result.current.directions$.get).toBe("function");
+    expect(typeof result.current.measure).toBe("function");
+  });
+});

package/src/sensors/useWindowScroll/index.ts

@@ -0,0 +1,11 @@
+"use client";
+import { type UseScrollOptions, type UseScrollReturn, useScroll } from "../useScroll";
+
+export type { UseScrollOptions, UseScrollReturn };
+
+export function useWindowScroll(options?: UseScrollOptions): UseScrollReturn {
+  return useScroll(
+    typeof window !== "undefined" ? window : null,
+    options,
+  );
+}

package/src/shared/configurable.ts

@@ -0,0 +1,35 @@
+import { isClient } from "./utils";
+
+export interface ConfigurableWindow {
+  window?: Window;
+}
+
+export interface ConfigurableDocument {
+  document?: Document;
+}
+
+export interface ConfigurableDocumentOrShadowRoot {
+  document?: DocumentOrShadowRoot;
+}
+
+export interface ConfigurableNavigator {
+  navigator?: Navigator;
+}
+
+export interface ConfigurableLocation {
+  location?: Location;
+}
+
+export const defaultWindow = /* #__PURE__ */ isClient ? window : undefined;
+
+export const defaultDocument = /* #__PURE__ */ isClient
+  ? window.document
+  : undefined;
+
+export const defaultNavigator = /* #__PURE__ */ isClient
+  ? window.navigator
+  : undefined;
+
+export const defaultLocation = /* #__PURE__ */ isClient
+  ? window.location
+  : undefined;

package/src/shared/index.ts

@@ -0,0 +1,4 @@
+/** typeof window 우선 검사 — instanceof Window는 jsdom 환경에서 실패할 수 있음 */
+export function isWindow(el: unknown): el is Window {
+  return typeof window !== "undefined" && el === window;
+}

package/src/shared/normalizeTargets/index.spec.ts

@@ -0,0 +1,76 @@
+// @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 } from "vitest";
+import { useRef$ } from "../../elements/useRef$";
+import type { Ref$ } from "../../elements/useRef$";
+import { normalizeTargets } from ".";
+
+const wrapEl = (el: Element) => observable<OpaqueObject<Element> | null>(ObservableHint.opaque(el));
+
+describe("normalizeTargets()", () => {
+  it("returns empty array for null plain value", () => {
+    expect(normalizeTargets(null)).toEqual([]);
+  });
+
+  it("returns empty array for undefined", () => {
+    expect(normalizeTargets(undefined)).toEqual([]);
+  });
+
+  it("returns empty array for empty array input", () => {
+    expect(normalizeTargets([])).toEqual([]);
+  });
+
+  it("returns element for Observable<OpaqueObject<Element>> input", () => {
+    const div = document.createElement("div");
+    expect(normalizeTargets(wrapEl(div))).toEqual([div]);
+  });
+
+  it("returns elements for array of Observable<OpaqueObject<Element>>", () => {
+    const a = document.createElement("div");
+    const b = document.createElement("span");
+    expect(normalizeTargets([wrapEl(a), wrapEl(b)])).toEqual([a, b]);
+  });
+
+  it("unwraps Observable<OpaqueObject<Element>>", () => {
+    const div = document.createElement("div");
+    expect(normalizeTargets(wrapEl(div))).toEqual([div]);
+  });
+
+  it("filters out Observable<null>", () => {
+    const obs = observable<ReturnType<typeof ObservableHint.opaque<Element>> | null>(null);
+    expect(normalizeTargets(obs)).toEqual([]);
+  });
+
+  it("unwraps Ref$ target and returns the raw DOM element", () => {
+    const div = document.createElement("div");
+    const { result } = renderHook(() => useRef$<HTMLDivElement>());
+
+    act(() => result.current(div));
+
+    const elements = normalizeTargets(result.current as Ref$<Element>);
+    expect(elements).toEqual([div]);
+  });
+
+  it("returns empty array when Ref$ has no element assigned", () => {
+    const { result } = renderHook(() => useRef$<HTMLDivElement>());
+
+    const elements = normalizeTargets(result.current as Ref$<Element>);
+    expect(elements).toEqual([]);
+  });
+
+  it("handles mixed array of Ref$, Observable, and wrapped Element", () => {
+    const div = document.createElement("div");
+    const span = document.createElement("span");
+    const p = document.createElement("p");
+
+    const { result } = renderHook(() => useRef$<HTMLDivElement>());
+    act(() => result.current(div));
+
+    const obs = wrapEl(span);
+
+    const elements = normalizeTargets([result.current as Ref$<Element>, obs, wrapEl(p)]);
+    expect(elements).toEqual([div, span, p]);
+  });
+});

package/src/shared/normalizeTargets/index.ts

@@ -0,0 +1,27 @@
+import { getElement, type MaybeElement } from "../../elements/useRef$";
+
+/**
+ * Normalizes one or more observable-element targets into a plain Element[].
+ *
+ * - `Ref$<T>` — calls `.get()` and unwraps the OpaqueObject via `.valueOf()`
+ * - `Observable<OpaqueObject<Element> | null>` — calls `.get()` and unwraps via `.valueOf()`
+ * - `Document` / `Window` — filtered out (not an Element, handled by callers)
+ * - `null` — filtered out
+ *
+ * When called inside `useObserve`, reading `.get()` registers observable
+ * dependencies so the observer re-fires when a tracked target changes.
+ *
+ * Currently shared by useResizeObserver.
+ * useIntersectionObserver, useMutationObserver will use this once implemented.
+ */
+export function normalizeTargets(
+  target?: MaybeElement | MaybeElement[],
+): Element[] {
+  if (target == null) return [];
+  const arr = Array.isArray(target) ? target : [target];
+  return arr
+    .map((t) => {
+      return getElement(t) as any;
+    })
+    .filter((el): el is Element => el != null);
+}

package/src/shared/utils.ts

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// TIER 0-B: Shared pure utility functions (VueUse equivalents, no dependencies)
+// ---------------------------------------------------------------------------
+
+export const isClient =
+  typeof window !== "undefined" && typeof document !== "undefined";
+
+export const noop = () => {};
+
+export const clamp = (n: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, n));
+
+export const isDef = <T>(val?: T): val is T => typeof val !== "undefined";
+
+export const notNullish = <T>(val?: T | null): val is T => val != null;
+
+export const isObject = (val: unknown): val is object =>
+  Object.prototype.toString.call(val) === "[object Object]";
+
+export const isIOS =
+  /* #__PURE__ */ isClient &&
+  /iPad|iPhone|iPod/.test(navigator.userAgent) &&
+  !(window as any).MSStream;
+
+export function toArray<T>(v: T | T[]): T[] {
+  return Array.isArray(v) ? v : [v];
+}
+
+export function objectPick<O extends object, T extends keyof O>(
+  obj: O,
+  keys: T[],
+): Pick<O, T> {
+  return keys.reduce(
+    (n, k) => {
+      if (k in obj) n[k] = obj[k];
+      return n;
+    },
+    {} as Pick<O, T>,
+  );
+}
+
+export function objectOmit<O extends object, T extends keyof O>(
+  obj: O,
+  keys: T[],
+): Omit<O, T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([k]) => !keys.includes(k as T)),
+  ) as Omit<O, T>;
+}
+
+export function promiseTimeout(ms: number, throwOnTimeout = false): Promise<void> {
+  return new Promise((resolve, reject) =>
+    throwOnTimeout
+      ? setTimeout(() => reject(new Error(`Timeout ${ms}ms`)), ms)
+      : setTimeout(resolve, ms),
+  );
+}
+
+export function increaseWithUnit(target: number, delta: number): number;
+export function increaseWithUnit(target: string, delta: number): string;
+export function increaseWithUnit(target: number | string, delta: number): number | string {
+  if (typeof target === "number") return target + delta;
+  const match = target.match(/^(-?\d*\.?\d+)([a-z%]*)$/i);
+  if (!match) return target;
+  const [, num, unit] = match;
+  return `${Number(num) + delta}${unit}`;
+}