@usels/core 0.0.1-beta.3

package/src/browser/useMediaQuery/index.ts

@@ -0,0 +1,96 @@
+"use client";
+import { ObservableHint, type Observable } from "@legendapp/state";
+import { useObservable, useObserve } from "@legendapp/state/react";
+import { get } from "../../function/get";
+import { useSupported } from "../../function/useSupported";
+import type { MaybeObservable } from "../../types";
+import { useWhenMounted } from "../../function/useWhenMounted";
+import { useEventListener } from "../useEventListener";
+
+// ---------------------------------------------------------------------------
+// Local helpers
+// ---------------------------------------------------------------------------
+
+function pxValue(value: string): number {
+  const num = parseFloat(value);
+  const unit = value
+    .trim()
+    .replace(/^-?\d+(?:\.\d+)?/, "")
+    .trim();
+  if (unit === "px" || unit === "") return num;
+  if (unit === "em" || unit === "rem") return num * 16;
+  return num;
+}
+
+export function evaluateSSRQuery(query: string, ssrWidth: number): boolean {
+  const queryStrings = query.split(",");
+  return queryStrings.some((queryString) => {
+    const not = queryString.includes("not all");
+    const minWidth = queryString.match(
+      /\(\s*min-width:\s*(-?\d+(?:\.\d*)?[a-z]+\s*)\)/,
+    );
+    const maxWidth = queryString.match(
+      /\(\s*max-width:\s*(-?\d+(?:\.\d*)?[a-z]+\s*)\)/,
+    );
+    let res = Boolean(minWidth || maxWidth);
+    if (minWidth && res) res = ssrWidth >= pxValue(minWidth[1]);
+    if (maxWidth && res) res = ssrWidth <= pxValue(maxWidth[1]);
+    return not ? !res : res;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface UseMediaQueryOptions {
+  ssrWidth?: number;
+}
+
+export type UseMediaQueryReturn = Observable<boolean>;
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/*@__NO_SIDE_EFFECTS__*/
+export function useMediaQuery(
+  query: MaybeObservable<string>,
+  options: UseMediaQueryOptions = {},
+): UseMediaQueryReturn {
+  const { ssrWidth } = options;
+
+  const isSupported = useSupported(
+    () => "matchMedia" in window && typeof window.matchMedia === "function",
+  );
+
+  const matches$ = useObservable(() =>
+    typeof ssrWidth === "number"
+      ? evaluateSSRQuery(get(query), ssrWidth)
+      : false,
+  );
+
+  const mql$ = useWhenMounted(() =>
+    isSupported.get()
+      ? ObservableHint.opaque(window.matchMedia(get(query)))
+      : null,
+  );
+  useObserve(() => {
+    const mql = mql$.get();
+    if (!mql) {
+      return;
+    }
+    matches$.set(mql.matches.valueOf());
+  });
+
+  useEventListener(
+    mql$,
+    "change",
+    (e: Event) => {
+      matches$.set((e as MediaQueryListEvent).matches);
+    },
+    { passive: true },
+  );
+
+  return matches$;
+}

package/src/components/Auto/index.tsx

@@ -0,0 +1,65 @@
+"use client";
+import React, {
+  createElement,
+  type FC,
+  type ReactNode,
+  type ReactElement,
+} from "react";
+import { Computed, Show } from "@legendapp/state/react";
+import type { Selector } from "@legendapp/state";
+
+type AutoPropsIf<T> = {
+  if: Selector<T>;
+  ifReady?: never;
+  withState?: boolean; // Show is already reactive to parent state; withState is accepted but has no effect
+  children: () => ReactNode;
+  else?: ReactNode | (() => ReactNode);
+  wrap?: FC<{ children: ReactNode }>;
+};
+
+type AutoPropsIfReady<T> = {
+  if?: never;
+  ifReady: Selector<T>;
+  withState?: boolean; // Same as above
+  children: () => ReactNode;
+  else?: ReactNode | (() => ReactNode);
+  wrap?: FC<{ children: ReactNode }>;
+};
+
+type AutoPropsReactive = {
+  if?: never;
+  ifReady?: never;
+  withState?: boolean;
+  children: () => ReactNode;
+};
+
+export type AutoProps<T = unknown> =
+  | AutoPropsIf<T>
+  | AutoPropsIfReady<T>
+  | AutoPropsReactive;
+
+export function Auto<T>({
+  if: ifProp,
+  ifReady,
+  withState,
+  children,
+  ...rest
+}: AutoProps<T>): ReactElement | null {
+  if (ifProp !== undefined) {
+    const { else: elseProp, wrap } = rest as AutoPropsIf<T>;
+    return createElement(Show<T>, {
+      if: ifProp,
+      else: elseProp,
+      wrap,
+      children,
+    });
+  }
+  if (ifReady !== undefined) {
+    const { else: elseProp, wrap } = rest as AutoPropsIfReady<T>;
+    return createElement(Show<T>, { ifReady, else: elseProp, wrap, children });
+  }
+  return createElement(
+    withState ? Computed : React.memo(Computed, () => true),
+    { children },
+  );
+}

package/src/elements/useDocumentVisibility/demo.tsx

@@ -0,0 +1,111 @@
+import { useRef } from "react";
+import { useDocumentVisibility } from ".";
+import {
+  Computed,
+  useObservable,
+  useObserveEffect,
+} from "@legendapp/state/react";
+
+const dot: React.CSSProperties = {
+  display: "inline-block",
+  width: "8px",
+  height: "8px",
+  borderRadius: "50%",
+  marginRight: "6px",
+  verticalAlign: "middle",
+};
+
+function StateRow({
+  label,
+  value,
+}: {
+  label: string;
+  value: DocumentVisibilityState;
+}) {
+  const visible = value === "visible";
+  return (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        padding: "10px 14px",
+        borderRadius: "6px",
+        border: `1px solid ${visible ? "var(--sl-color-green, #22c55e)" : "var(--sl-color-orange, #f97316)"}`,
+        background: visible
+          ? "var(--sl-color-green-low, #f0fdf4)"
+          : "var(--sl-color-orange-low, #fff7ed)",
+        transition: "border-color 0.3s, background 0.3s",
+        gap: "10px",
+      }}
+    >
+      <span
+        style={{
+          ...dot,
+          background: visible
+            ? "var(--sl-color-green, #22c55e)"
+            : "var(--sl-color-orange, #f97316)",
+        }}
+      />
+      <span style={{ color: "var(--sl-color-gray-2, #64748b)", minWidth: "80px" }}>
+        {label}
+      </span>
+      <strong
+        style={{
+          color: visible
+            ? "var(--sl-color-green, #22c55e)"
+            : "var(--sl-color-orange, #f97316)",
+        }}
+      >
+        &quot;{value}&quot;
+      </strong>
+    </div>
+  );
+}
+
+export default function UseDocumentVisibilityDemo() {
+  const visibility$ = useDocumentVisibility();
+  // Delayed display: stays on 'hidden' for 2s after returning to visible
+  const delayed$ = useObservable<DocumentVisibilityState>("visible");
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useObserveEffect(() => {
+    const state = visibility$.get();
+    if (timerRef.current !== null) clearTimeout(timerRef.current);
+    if (state === "hidden") {
+      delayed$.set("hidden");
+    } else {
+      timerRef.current = setTimeout(() => {
+        delayed$.set("visible");
+      }, 2000);
+    }
+  });
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "8px",
+        fontFamily: "monospace",
+        fontSize: "13px",
+      }}
+    >
+      <Computed>
+        {() => <StateRow label="Instant" value={visibility$.get()} />}
+      </Computed>
+      <Computed>
+        {() => <StateRow label="2s delay" value={delayed$.get()} />}
+      </Computed>
+      <p
+        style={{
+          margin: 0,
+          fontSize: "11px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+        }}
+      >
+        Switch to another tab and come back — the 2s delay row stays{" "}
+        <strong>&quot;hidden&quot;</strong> long enough to confirm the transition.
+      </p>
+    </div>
+  );
+}

package/src/elements/useDocumentVisibility/index.md

@@ -0,0 +1,51 @@
+---
+title: useDocumentVisibility
+category: elements
+---
+
+Tracks the browser tab's visibility state (`'visible'` or `'hidden'`) as a reactive `Observable<DocumentVisibilityState>`.
+Updates automatically when the user switches tabs or minimizes the window.
+SSR-safe: returns `'visible'` when `document` is not available.
+
+## Demo
+
+## Usage
+
+```tsx
+import { useDocumentVisibility } from '@usels/core'
+
+function Component() {
+  const visibility$ = useDocumentVisibility()
+
+  return (
+    <p>Tab is {visibility$.get()}</p>
+  )
+}
+```
+
+### Pausing work when the tab is hidden
+
+```tsx
+const visibility$ = useDocumentVisibility()
+
+useObserve(() => {
+  if (visibility$.get() === 'hidden') pausePolling()
+  else resumePolling()
+})
+```
+
+### Tracking page view time
+
+```tsx
+const visibility$ = useDocumentVisibility()
+const visibleSince = useObservable(Date.now())
+
+useObserve(() => {
+  if (visibility$.get() === 'visible') {
+    visibleSince.set(Date.now())
+  } else {
+    const elapsed = Date.now() - visibleSince.get()
+    trackVisibleTime(elapsed)
+  }
+})
+```

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

@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+import { renderHook, act } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { useDocumentVisibility } from ".";
+
+const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve));
+
+function mockVisibilityState(value: DocumentVisibilityState) {
+  return vi.spyOn(document, "visibilityState", "get").mockReturnValue(value);
+}
+
+describe("useDocumentVisibility()", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns an Observable", () => {
+    const { result } = renderHook(() => useDocumentVisibility());
+    expect(typeof result.current.get).toBe("function");
+    expect(typeof result.current.set).toBe("function");
+  });
+
+  it("initial value is 'visible' before mount syncs", () => {
+    mockVisibilityState("hidden");
+    // renderHook runs the hook — the observable initializes to 'visible' first,
+    // then useMount sets it to the actual state. We just assert the final value.
+    const { result } = renderHook(() => useDocumentVisibility());
+    expect(result.current.get()).toBe("hidden");
+  });
+
+  it("reflects 'visible' when document.visibilityState is 'visible'", () => {
+    mockVisibilityState("visible");
+    const { result } = renderHook(() => useDocumentVisibility());
+    expect(result.current.get()).toBe("visible");
+  });
+
+  it("sets to 'hidden' when visibilitychange fires with hidden state", () => {
+    mockVisibilityState("visible");
+    const { result } = renderHook(() => useDocumentVisibility());
+
+    act(() => {
+      mockVisibilityState("hidden");
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+
+    expect(result.current.get()).toBe("hidden");
+  });
+
+  it("sets to 'visible' when visibilitychange fires with visible state", () => {
+    mockVisibilityState("hidden");
+    const { result } = renderHook(() => useDocumentVisibility());
+
+    act(() => {
+      mockVisibilityState("visible");
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+
+    expect(result.current.get()).toBe("visible");
+  });
+
+  it("toggles correctly across multiple visibility changes", () => {
+    mockVisibilityState("visible");
+    const { result } = renderHook(() => useDocumentVisibility());
+
+    act(() => {
+      mockVisibilityState("hidden");
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(result.current.get()).toBe("hidden");
+
+    act(() => {
+      mockVisibilityState("visible");
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(result.current.get()).toBe("visible");
+
+    act(() => {
+      mockVisibilityState("hidden");
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(result.current.get()).toBe("hidden");
+  });
+
+  it("removes event listener on unmount", async () => {
+    const addSpy = vi.spyOn(document, "addEventListener");
+    const removeSpy = vi.spyOn(document, "removeEventListener");
+
+    const { unmount } = renderHook(() => useDocumentVisibility());
+    unmount();
+    await flush(); // useMount defers cleanup via queueMicrotask in test env
+
+    const added = addSpy.mock.calls.some(([type]) => type === "visibilitychange");
+    const removed = removeSpy.mock.calls.some(([type]) => type === "visibilitychange");
+
+    expect(added).toBe(true);
+    expect(removed).toBe(true);
+  });
+
+  it("does not respond to events after unmount", async () => {
+    mockVisibilityState("visible");
+    const { result, unmount } = renderHook(() => useDocumentVisibility());
+
+    unmount();
+    await flush(); // wait for cleanup
+
+    act(() => {
+      mockVisibilityState("hidden");
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+
+    // Value stays at 'visible' — no listener active after cleanup
+    expect(result.current.get()).toBe("visible");
+  });
+});

package/src/elements/useDocumentVisibility/index.ts

@@ -0,0 +1,26 @@
+"use client";
+import type { Observable } from "@legendapp/state";
+import { useObservable, useMount } from "@legendapp/state/react";
+
+/*@__NO_SIDE_EFFECTS__*/
+export function useDocumentVisibility(): Observable<DocumentVisibilityState> {
+  // Always initialize with 'visible' to match SSR output and avoid hydration mismatch.
+  // The actual value is synced after mount.
+  const visibility$ = useObservable<DocumentVisibilityState>("visible");
+
+  useMount(() => {
+    visibility$.set(document.visibilityState);
+
+    const handler = () => {
+      visibility$.set(document.visibilityState);
+    };
+
+    document.addEventListener("visibilitychange", handler, { passive: true });
+
+    return () => {
+      document.removeEventListener("visibilitychange", handler);
+    };
+  });
+
+  return visibility$;
+}

package/src/elements/useElementBounding/demo.tsx

@@ -0,0 +1,63 @@
+import { useRef$ } from "../useRef$";
+import { useElementBounding } from ".";
+
+export default function UseElementBoundingDemo() {
+  const el$ = useRef$<HTMLDivElement>();
+  const { x$, y$, top$, left$, width$, height$ } = useElementBounding(el$);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "12px" }}>
+      {/* Bounding values readout */}
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(3, 1fr)",
+          gap: "6px",
+          fontFamily: "monospace",
+          fontSize: "13px",
+          padding: "10px 14px",
+          background: "var(--sl-color-gray-6, #f1f5f9)",
+          borderRadius: "6px",
+        }}
+      >
+        {(
+          [
+            ["x", x$.get()],
+            ["y", y$.get()],
+            ["top", top$.get()],
+            ["left", left$.get()],
+            ["width", width$.get()],
+            ["height", height$.get()],
+          ] as [string, number][]
+        ).map(([label, val]) => (
+          <span key={label}>
+            {label}: <strong>{Math.round(val)}px</strong>
+          </span>
+        ))}
+      </div>
+
+      {/* Resizable target element */}
+      <div
+        ref={el$}
+        style={{
+          resize: "both",
+          overflow: "auto",
+          width: "240px",
+          height: "100px",
+          padding: "12px",
+          border: "1px solid var(--sl-color-gray-5, #cbd5e1)",
+          borderRadius: "6px",
+          fontFamily: "monospace",
+          fontSize: "13px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+          userSelect: "none",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+        }}
+      >
+        resize me ↘
+      </div>
+    </div>
+  );
+}

package/src/elements/useElementBounding/index.md

@@ -0,0 +1,59 @@
+---
+title: useElementBounding
+category: elements
+---
+
+Tracks the bounding rect of a DOM element — `x`, `y`, `top`, `right`, `bottom`, `left`, `width`, `height` — as reactive `Observable<number>` values.
+Uses [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) for size changes, [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) for `style`/`class` attribute changes, and `scroll`/`resize` window events for position changes.
+`requestAnimationFrame` is used by default so CSS transform animations are captured accurately.
+
+## Demo
+
+## Usage
+
+```tsx twoslash
+// @noErrors
+import { useRef$, useElementBounding } from '@usels/core'
+
+function Component() {
+  const el$ = useRef$<HTMLDivElement>()
+  const { top$, left$, width$, height$ } = useElementBounding(el$)
+
+  return (
+    <div ref={el$}>
+      {width$.get()} × {height$.get()} at ({left$.get()}, {top$.get()})
+    </div>
+  )
+}
+```
+
+### Manual update
+
+```tsx twoslash
+// @noErrors
+import { useRef$, Ref$, useElementBounding } from '@usels/core'
+declare const el$: Ref$<HTMLDivElement>
+// ---cut---
+const { top$, left$, update } = useElementBounding(el$)
+
+// Force-recalculate bounding rect imperatively
+update()
+```
+
+### Disable window scroll tracking
+
+```typescript
+const { top$, left$ } = useElementBounding(el$, { windowScroll: false })
+```
+
+### Skip requestAnimationFrame (synchronous reads)
+
+```typescript
+const { width$, height$ } = useElementBounding(el$, { useCssTransforms: false })
+```
+
+### Keep values on unmount (no reset)
+
+```typescript
+const { top$ } = useElementBounding(el$, { reset: false })
+```