@usels/core 0.0.1

package/src/browser/useEventListener/index.ts

@@ -0,0 +1,242 @@
+"use client";
+import { isObservable, type Observable } from "@legendapp/state";
+import { useObservable, useObserve } from "@legendapp/state/react";
+import { useEffect, useRef } from "react";
+import { isRef$, type MaybeElement } from "../../elements/useRef$";
+import { normalizeTargets } from "../../shared/normalizeTargets";
+import { get } from "../../function/get";
+import type { Arrayable, MaybeObservable } from "../../types";
+import { toArray } from "../../shared/utils";
+
+/**
+ * Returns true if the value looks like an event name argument (string or
+ * array of strings), meaning no explicit target was provided.
+ */
+function isEventNameArg(v: unknown): boolean {
+  if (typeof v === "string") return true;
+  if (Array.isArray(v)) {
+    const nonNull = v.filter((item) => item != null);
+    return (
+      nonNull.length > 0 && nonNull.every((item) => typeof item === "string")
+    );
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GeneralEventListener<E = Event> {
+  (evt: E): void;
+}
+
+// ---------------------------------------------------------------------------
+// Overloads
+// ---------------------------------------------------------------------------
+
+/**
+ * Register using addEventListener on mounted, and removeEventListener
+ * automatically on unmounted.
+ *
+ * Overload 1: Omitted target — defaults to `window`.
+ */
+export function useEventListener<E extends keyof WindowEventMap>(
+  event: Arrayable<E>,
+  listener: Arrayable<(ev: WindowEventMap[E]) => any>,
+  options?: MaybeObservable<boolean | AddEventListenerOptions>,
+): () => void;
+
+/**
+ * Register using addEventListener on mounted, and removeEventListener
+ * automatically on unmounted.
+ *
+ * Overload 2: Explicit `Window` target.
+ */
+export function useEventListener<E extends keyof WindowEventMap>(
+  target: Window,
+  event: Arrayable<E>,
+  listener: Arrayable<(ev: WindowEventMap[E]) => any>,
+  options?: MaybeObservable<boolean | AddEventListenerOptions>,
+): () => void;
+
+/**
+ * Register using addEventListener on mounted, and removeEventListener
+ * automatically on unmounted.
+ *
+ * Overload 3: Explicit `Document` target.
+ */
+export function useEventListener<E extends keyof DocumentEventMap>(
+  target: Document,
+  event: Arrayable<E>,
+  listener: Arrayable<(ev: DocumentEventMap[E]) => any>,
+  options?: MaybeObservable<boolean | AddEventListenerOptions>,
+): () => void;
+
+/**
+ * Register using addEventListener on mounted, and removeEventListener
+ * automatically on unmounted.
+ *
+ * Overload 4: `MaybeElement` target — supports Ref$, Observable<OpaqueObject<Element>>,
+ * Document, Window, or an array of those (Legend-State reactive).
+ * Raw HTMLElement is excluded — use Ref$ or Observable<OpaqueObject<Element>> instead.
+ */
+export function useEventListener<E extends keyof HTMLElementEventMap>(
+  target: MaybeElement | MaybeElement[] | null | undefined,
+  event: Arrayable<E>,
+  listener: Arrayable<(ev: HTMLElementEventMap[E]) => any>,
+  options?: MaybeObservable<boolean | AddEventListenerOptions>,
+): () => void;
+
+/**
+ * Register using addEventListener on mounted, and removeEventListener
+ * automatically on unmounted.
+ *
+ * Overload 5: Observable<EventTarget> — reactive target (e.g.
+ * Observable<MediaQueryList>, Ref$<HTMLElement>, etc.).
+ * The observer re-fires whenever the observable value changes.
+ */
+export function useEventListener<EventType = Event>(
+  target: Observable<any>,
+  event: Arrayable<string>,
+  listener: Arrayable<GeneralEventListener<EventType>>,
+  options?: MaybeObservable<boolean | AddEventListenerOptions>,
+): () => void;
+
+/**
+ * Register using addEventListener on mounted, and removeEventListener
+ * automatically on unmounted.
+ *
+ * Overload 6: Generic `EventTarget` fallback.
+ */
+export function useEventListener<EventType = Event>(
+  target: EventTarget | null | undefined,
+  event: Arrayable<string>,
+  listener: Arrayable<GeneralEventListener<EventType>>,
+  options?: MaybeObservable<boolean | AddEventListenerOptions>,
+): () => void;
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export function useEventListener(...args: any[]): () => void {
+  // Detect whether first arg is an event name (no target) or a target.
+  // Mirrors VueUse's firstParamTargets check.
+  const hasTarget = !isEventNameArg(args[0]);
+
+  const rawTarget: unknown = hasTarget ? args[0] : undefined;
+  const rawEvent: Arrayable<string> = hasTarget ? args[1] : args[0];
+  const rawListener: Arrayable<(...a: any[]) => any> = hasTarget
+    ? args[2]
+    : args[1];
+  const rawOptions: MaybeObservable<boolean | AddEventListenerOptions> | undefined = hasTarget
+    ? args[3]
+    : args[2];
+
+  // Always keep the latest listeners in a ref so that the forwarder always
+  // calls the current listeners, even after re-renders change the functions.
+  const listenersRef = useRef(toArray(rawListener));
+  listenersRef.current = toArray(rawListener);
+
+  // Stable forwarder — one function reference per hook instance, created once.
+  const forwarder = useRef((ev: Event) => {
+    listenersRef.current.forEach((l) => l(ev));
+  });
+
+  // Options ref prevents recreating listeners when only options change.
+  const optionsRef = useRef(rawOptions);
+  optionsRef.current = rawOptions;
+
+  // Observable mount flag — lets useObserve react when component mounts.
+  const mounted$ = useObservable(false);
+
+  // Array of removeEventListener thunks for the currently active registrations.
+  const cleanupsRef = useRef<Array<() => void>>([]);
+
+  // Single reactive observer: re-runs whenever mounted$ changes OR any
+  // observable target changes. Reading .get() inside this callback registers
+  // reactive dependencies, so listener setup/teardown is always in sync.
+  useObserve(() => {
+    // Teardown previous registrations before re-registering.
+    cleanupsRef.current.forEach((fn) => fn());
+    cleanupsRef.current = [];
+
+    // Only register listeners while the component is mounted.
+    if (!mounted$.get()) return;
+
+    // Resolve targets inline — reading .get() on observable targets registers
+    // them as reactive dependencies for this observer.
+    const targets: EventTarget[] = (() => {
+      if (!hasTarget) {
+        return typeof window !== "undefined" ? [window] : [];
+      }
+      if (rawTarget == null) return [];
+
+      const items: unknown[] = Array.isArray(rawTarget)
+        ? rawTarget
+        : [rawTarget];
+      return items.flatMap((item): EventTarget[] => {
+        if (item == null) return [];
+        // Ref$ references — normalizeTargets handles OpaqueObject.valueOf() unwrapping.
+        if (isRef$(item)) {
+          return normalizeTargets([item as MaybeElement]) as EventTarget[];
+        }
+        // Observable targets — .get() unwraps and registers reactive dependency.
+        // Supports Element, Document, MediaQueryList, or any EventTarget.
+        if (isObservable(item)) {
+          const val = (item as { get: () => unknown }).get();
+          if (val == null) return [];
+          // Unwrap OpaqueObject created by ObservableHint.opaque (has custom valueOf).
+          const target =
+            typeof (val as any).valueOf === "function"
+              ? ((val as any).valueOf() as unknown) ?? val
+              : val;
+          // Duck-type check: works with real EventTargets and test mocks alike.
+          if (typeof (target as any).addEventListener === "function") {
+            return [target as EventTarget];
+          }
+          return [];
+        }
+        // Raw EventTarget (Window, Document — stable singletons)
+        return [item as EventTarget];
+      });
+    })();
+
+    if (!targets.length) return;
+
+    const events = toArray(rawEvent);
+    if (!events.length || !listenersRef.current.length) return;
+
+    const resolvedOpts = get(optionsRef.current);
+    const opts =
+      typeof resolvedOpts === "object" && resolvedOpts !== null
+        ? { ...resolvedOpts }
+        : resolvedOpts;
+
+    const fn = forwarder.current;
+    cleanupsRef.current = targets.flatMap((el) =>
+      events.map((event) => {
+        el.addEventListener(event, fn, opts);
+        return () => el.removeEventListener(event, fn, opts);
+      }),
+    );
+  });
+
+  // useEffect manages mount state only — no setup logic here.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    mounted$.set(true);
+    return () => {
+      mounted$.set(false);
+      cleanupsRef.current.forEach((fn) => fn());
+      cleanupsRef.current = [];
+    };
+  }, []);
+
+  // Return a manual cleanup function for imperative removal.
+  return () => {
+    cleanupsRef.current.forEach((fn) => fn());
+    cleanupsRef.current = [];
+  };
+}

package/src/browser/useMediaQuery/demo.tsx

@@ -0,0 +1,63 @@
+import { useMediaQuery } from ".";
+import { Computed } from "@legendapp/state/react";
+
+const row: React.CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "start",
+  gap: "10px",
+  padding: "8px 14px",
+  borderRadius: "6px",
+  border: "1px solid var(--sl-color-gray-5, #e2e8f0)",
+  background: "var(--sl-color-gray-6, #f8fafc)",
+  margin: 0,
+};
+
+const label: React.CSSProperties = {
+  color: "var(--sl-color-gray-3, #64748b)",
+  fontSize: "12px",
+};
+
+const value: React.CSSProperties = {
+  fontFamily: "monospace",
+  fontSize: "13px",
+  fontWeight: "bold",
+  color: "var(--sl-color-text, #0f172a)",
+};
+
+export default function UseMediaQueryDemo() {
+  const isLargeScreen$ = useMediaQuery("(min-width: 1024px)");
+  const prefersDark$ = useMediaQuery("(prefers-color-scheme: dark)");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "8px",
+        fontFamily: "monospace",
+        fontSize: "13px",
+      }}
+    >
+      <Computed>
+        {() => (
+          <div
+            style={{
+              display: "flex",
+              gap: "10px",
+            }}
+          >
+            <div style={row}>
+              <span style={label}>isLargeScreen</span>
+              <span style={value}>{String(isLargeScreen$.get())}</span>
+            </div>
+            <div style={row}>
+              <span style={label}>prefersDark</span>
+              <span style={value}>{String(prefersDark$.get())}</span>
+            </div>
+          </div>
+        )}
+      </Computed>
+    </div>
+  );
+}

package/src/browser/useMediaQuery/index.md

@@ -0,0 +1,43 @@
+---
+title: useMediaQuery
+category: browser
+---
+
+Tracks a CSS media query string as a reactive `Observable<boolean>`.
+Subscribes to `MediaQueryList` change events and updates automatically.
+SSR-safe: accepts an optional `ssrWidth` to statically evaluate `min-width`/`max-width` queries on the server.
+
+## Demo
+
+## Usage
+
+```tsx
+import { useMediaQuery } from '@usels/core'
+import { Computed } from '@legendapp/state/react'
+
+function Component() {
+  const isLarge$ = useMediaQuery('(min-width: 1024px)')
+
+  return (
+    <Computed>
+      {() => <p>{isLarge$.get() ? 'Large screen' : 'Small screen'}</p>}
+    </Computed>
+  )
+}
+```
+
+### Multiple queries
+
+```tsx
+const isLarge$ = useMediaQuery('(min-width: 1024px)')
+const prefersDark$ = useMediaQuery('(prefers-color-scheme: dark)')
+```
+
+### SSR with ssrWidth
+
+```tsx
+const isLarge$ = useMediaQuery('(min-width: 1024px)', { ssrWidth: 1280 })
+```
+
+`ssrWidth` is used to statically evaluate the query when `window` is unavailable,
+preventing a layout shift between the server-rendered markup and the first client render.

package/src/browser/useMediaQuery/index.spec.ts

@@ -0,0 +1,267 @@
+// @vitest-environment jsdom
+import { renderHook, act } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { observable } from "@legendapp/state";
+import { useMediaQuery, evaluateSSRQuery } from ".";
+
+const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve));
+// TODO: change to e2e
+function createMockMatchMedia(initialMatches = false) {
+  const listeners = new Map<string, EventListener[]>();
+  let currentMatches = initialMatches;
+
+  const mql = {
+    get matches() {
+      return currentMatches;
+    },
+    media: "",
+    addEventListener: vi.fn((type: string, listener: EventListener) => {
+      if (!listeners.has(type)) listeners.set(type, []);
+      listeners.get(type)!.push(listener);
+    }),
+    removeEventListener: vi.fn((type: string, listener: EventListener) => {
+      const list = listeners.get(type) ?? [];
+      const idx = list.indexOf(listener);
+      if (idx !== -1) list.splice(idx, 1);
+    }),
+    dispatchEvent: vi.fn((event: Event) => {
+      listeners.get(event.type)?.forEach((l) => l(event));
+      return true;
+    }),
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+  } as unknown as MediaQueryList;
+
+  const triggerChange = (matches: boolean) => {
+    currentMatches = matches;
+    const event = {
+      type: "change",
+      matches,
+    } as unknown as MediaQueryListEvent;
+    listeners.get("change")?.forEach((l) => l(event));
+  };
+
+  return {
+    mockFn: (_query: string) => mql,
+    mql,
+    triggerChange,
+  };
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// useMediaQuery — return value
+// ---------------------------------------------------------------------------
+
+describe("useMediaQuery() — return value", () => {
+  it("returns an Observable", () => {
+    vi.stubGlobal("matchMedia", createMockMatchMedia().mockFn);
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    expect(typeof result.current.get).toBe("function");
+  });
+
+  it("returns false when matchMedia is not supported", () => {
+    const win = globalThis.window as any;
+    const original = win.matchMedia;
+    delete win.matchMedia;
+
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    expect(result.current.get()).toBe(false);
+
+    win.matchMedia = original;
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useMediaQuery — client initial value
+// ---------------------------------------------------------------------------
+
+describe("useMediaQuery() — client initial value", () => {
+  it("initial value is true when matchMedia matches", () => {
+    vi.stubGlobal("matchMedia", createMockMatchMedia(true).mockFn);
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("initial value is false when matchMedia does not match", () => {
+    vi.stubGlobal("matchMedia", createMockMatchMedia(false).mockFn);
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    expect(result.current.get()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useMediaQuery — change event
+// ---------------------------------------------------------------------------
+
+describe("useMediaQuery() — change event", () => {
+  it("updates to true on change event", () => {
+    const { mockFn, triggerChange } = createMockMatchMedia(false);
+    vi.stubGlobal("matchMedia", mockFn);
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    expect(result.current.get()).toBe(false);
+
+    act(() => triggerChange(true));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("updates to false on change event", () => {
+    const { mockFn, triggerChange } = createMockMatchMedia(true);
+    vi.stubGlobal("matchMedia", mockFn);
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    expect(result.current.get()).toBe(true);
+
+    act(() => triggerChange(false));
+    expect(result.current.get()).toBe(false);
+  });
+
+  it("toggles correctly across multiple change events", () => {
+    const { mockFn, triggerChange } = createMockMatchMedia(false);
+    vi.stubGlobal("matchMedia", mockFn);
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+
+    act(() => triggerChange(true));
+    expect(result.current.get()).toBe(true);
+
+    act(() => triggerChange(false));
+    expect(result.current.get()).toBe(false);
+
+    act(() => triggerChange(true));
+    expect(result.current.get()).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useMediaQuery — SSR (evaluateSSRQuery)
+// ---------------------------------------------------------------------------
+
+describe("useMediaQuery() — SSR (evaluateSSRQuery)", () => {
+  it("min-width satisfied", () => {
+    expect(evaluateSSRQuery("(min-width: 768px)", 1024)).toBe(true);
+  });
+
+  it("min-width not satisfied", () => {
+    expect(evaluateSSRQuery("(min-width: 768px)", 500)).toBe(false);
+  });
+
+  it("max-width satisfied", () => {
+    expect(evaluateSSRQuery("(max-width: 768px)", 500)).toBe(true);
+  });
+
+  it("max-width not satisfied", () => {
+    expect(evaluateSSRQuery("(max-width: 768px)", 1024)).toBe(false);
+  });
+
+  it("not all negation", () => {
+    expect(evaluateSSRQuery("not all and (min-width: 768px)", 500)).toBe(true);
+  });
+
+  it("comma-separated queries match when one condition is met", () => {
+    expect(
+      evaluateSSRQuery("(max-width: 500px), (min-width: 768px)", 1024),
+    ).toBe(true);
+  });
+
+  it("defaults to false when no ssrWidth is provided", () => {
+    const win = globalThis.window as any;
+    const original = win.matchMedia;
+    delete win.matchMedia;
+
+    const { result } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    expect(result.current.get()).toBe(false);
+
+    win.matchMedia = original;
+  });
+
+  it("query without min/max-width resolves to false", () => {
+    expect(evaluateSSRQuery("(prefers-color-scheme: dark)", 1024)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useMediaQuery — cleanup
+// ---------------------------------------------------------------------------
+
+describe("useMediaQuery() — cleanup", () => {
+  it("removes change listener on unmount", async () => {
+    const { mockFn, mql } = createMockMatchMedia(false);
+    vi.stubGlobal("matchMedia", mockFn);
+
+    const { unmount } = renderHook(() => useMediaQuery("(min-width: 768px)"));
+    unmount();
+    await flush();
+
+    expect(mql.removeEventListener).toHaveBeenCalledWith(
+      "change",
+      expect.any(Function),
+      expect.objectContaining({ passive: true }),
+    );
+  });
+
+  it("does not update after unmount", async () => {
+    const { mockFn, triggerChange } = createMockMatchMedia(false);
+    vi.stubGlobal("matchMedia", mockFn);
+
+    const { result, unmount } = renderHook(() =>
+      useMediaQuery("(min-width: 768px)"),
+    );
+    unmount();
+    await flush();
+
+    act(() => triggerChange(true));
+    expect(result.current.get()).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useMediaQuery — reactive query (MaybeObservable<string>)
+// ---------------------------------------------------------------------------
+
+describe("useMediaQuery() — reactive query (MaybeObservable<string>)", () => {
+  it("accepts Observable<string> and reads initial value", () => {
+    vi.stubGlobal("matchMedia", createMockMatchMedia(true).mockFn);
+    const query$ = observable("(min-width: 768px)");
+
+    const { result } = renderHook(() => useMediaQuery(query$));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("updates matches when query Observable changes", () => {
+    const mqlMap = new Map<string, ReturnType<typeof createMockMatchMedia>>();
+    vi.stubGlobal("matchMedia", (q: string) => {
+      if (!mqlMap.has(q))
+        mqlMap.set(q, createMockMatchMedia(q === "(max-width: 480px)"));
+      return mqlMap.get(q)!.mql;
+    });
+
+    const query$ = observable("(min-width: 1024px)");
+    const { result } = renderHook(() => useMediaQuery(query$));
+    expect(result.current.get()).toBe(false);
+
+    act(() => query$.set("(max-width: 480px)"));
+    expect(result.current.get()).toBe(true);
+  });
+
+  it("removes old change listener and adds new one when query changes", () => {
+    const mqlMap = new Map<string, ReturnType<typeof createMockMatchMedia>>();
+    vi.stubGlobal("matchMedia", (q: string) => {
+      if (!mqlMap.has(q)) mqlMap.set(q, createMockMatchMedia(false));
+      return mqlMap.get(q)!.mql;
+    });
+
+    const query$ = observable("(min-width: 1024px)");
+    renderHook(() => useMediaQuery(query$));
+
+    act(() => query$.set("(max-width: 480px)"));
+
+    expect(mqlMap.get("(min-width: 1024px)")!.mql.removeEventListener)
+      .toHaveBeenCalledWith("change", expect.any(Function), expect.objectContaining({ passive: true }));
+    expect(mqlMap.get("(max-width: 480px)")!.mql.addEventListener)
+      .toHaveBeenCalledWith("change", expect.any(Function), { passive: true });
+  });
+});