@usels/core 0.0.1

package/src/elements/useWindowSize/demo.tsx

@@ -0,0 +1,51 @@
+import { useWindowSize } from ".";
+import { Computed } from "@legendapp/state/react";
+
+const row: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  padding: "8px 14px",
+  borderRadius: "6px",
+  border: "1px solid var(--sl-color-gray-5, #e2e8f0)",
+
+  background: "var(--sl-color-gray-6, #f1f5f9)",
+  // borderRadius: "6px",
+  gap: "24px",
+  color: "white",
+};
+
+export default function UseWindowSizeDemo() {
+  const { width: width$, height: height$ } = useWindowSize();
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "8px",
+        fontFamily: "monospace",
+        fontSize: "14px",
+        background: "var(--sl-color-gray-6, #f1f5f9)",
+      }}
+    >
+      <Computed>
+        {() => (
+          <div style={row}>
+            <span>width: {width$.get()}px</span>
+            <span>height: {height$.get()}px</span>
+          </div>
+        )}
+      </Computed>
+
+      <p
+        style={{
+          margin: 5,
+          fontSize: "11px",
+          color: "var(--sl-color-gray-3, #94a3b8)",
+        }}
+      >
+        Resize the browser window to see the values update.
+      </p>
+    </div>
+  );
+}

package/src/elements/useWindowSize/index.md

@@ -0,0 +1,55 @@
+---
+title: useWindowSize
+category: elements
+---
+
+Tracks the browser window dimensions as reactive `Observable<number>` values for width and height.
+Supports `inner`, `outer`, and `visual` viewport modes, and updates on resize and orientation change.
+SSR-safe: returns `initialWidth`/`initialHeight` (default `0`) when `window` is not available.
+
+## Demo
+
+## Usage
+
+```tsx
+import { useWindowSize } from '@usels/core'
+import { Computed } from '@legendapp/state/react'
+
+function Component() {
+  const size$ = useWindowSize()
+
+  return (
+    <Computed>
+      {() => (
+        <p>
+          {size$.width.get()} × {size$.height.get()}
+        </p>
+      )}
+    </Computed>
+  )
+}
+```
+
+### Excluding scrollbar width
+
+```tsx
+const size$ = useWindowSize({ includeScrollbar: false })
+```
+
+### Outer window size
+
+```tsx
+const size$ = useWindowSize({ type: 'outer' })
+```
+
+### Visual viewport (pinch-zoom aware)
+
+```tsx
+const size$ = useWindowSize({ type: 'visual' })
+```
+
+### Custom initial size for SSR
+
+```tsx
+const size$ = useWindowSize({ initialWidth: 1280, initialHeight: 800 })
+```

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

@@ -0,0 +1,310 @@
+// @vitest-environment jsdom
+import { renderHook, act } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { observable } from "@legendapp/state";
+import { useWindowSize } from ".";
+
+const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve));
+
+function mockMatchMedia(
+  matches = false,
+): (query: string) => MediaQueryList {
+  return (_query: string) =>
+    ({
+      matches,
+      media: _query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }) as unknown as MediaQueryList;
+}
+
+describe("useWindowSize()", () => {
+  beforeEach(() => {
+    vi.stubGlobal("matchMedia", mockMatchMedia());
+
+    Object.defineProperty(window, "innerWidth", {
+      writable: true,
+      configurable: true,
+      value: 1024,
+    });
+    Object.defineProperty(window, "innerHeight", {
+      writable: true,
+      configurable: true,
+      value: 768,
+    });
+    Object.defineProperty(window, "outerWidth", {
+      writable: true,
+      configurable: true,
+      value: 1024,
+    });
+    Object.defineProperty(window, "outerHeight", {
+      writable: true,
+      configurable: true,
+      value: 768,
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("returns width and height Observables", () => {
+    const { result } = renderHook(() => useWindowSize());
+    expect(typeof result.current.width.get).toBe("function");
+    expect(typeof result.current.height.get).toBe("function");
+  });
+
+  it("reads innerWidth/innerHeight by default", () => {
+    const { result } = renderHook(() => useWindowSize());
+    expect(result.current.width.get()).toBe(1024);
+    expect(result.current.height.get()).toBe(768);
+  });
+
+  it("uses initialWidth/initialHeight before mount when window is undefined", () => {
+    // Simulate SSR by checking initial values before any side effects run
+    const { result } = renderHook(() =>
+      useWindowSize({ initialWidth: 320, initialHeight: 480 }),
+    );
+    // After mount update fires, it reads actual window values
+    // but the observable was initialized with the provided defaults
+    expect(result.current.width.get()).toBeDefined();
+    expect(result.current.height.get()).toBeDefined();
+  });
+
+  it("updates on window resize event", () => {
+    const { result } = renderHook(() => useWindowSize());
+
+    act(() => {
+      (window as any).innerWidth = 1280;
+      (window as any).innerHeight = 900;
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    expect(result.current.width.get()).toBe(1280);
+    expect(result.current.height.get()).toBe(900);
+  });
+
+  it("type: 'outer' reads outerWidth/outerHeight", () => {
+    (window as any).outerWidth = 1100;
+    (window as any).outerHeight = 850;
+
+    const { result } = renderHook(() => useWindowSize({ type: "outer" }));
+    expect(result.current.width.get()).toBe(1100);
+    expect(result.current.height.get()).toBe(850);
+  });
+
+  it("type: 'outer' updates on resize", () => {
+    const { result } = renderHook(() => useWindowSize({ type: "outer" }));
+
+    act(() => {
+      (window as any).outerWidth = 900;
+      (window as any).outerHeight = 600;
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    expect(result.current.width.get()).toBe(900);
+    expect(result.current.height.get()).toBe(600);
+  });
+
+  it("includeScrollbar: false reads clientWidth/clientHeight", () => {
+    Object.defineProperty(document.documentElement, "clientWidth", {
+      writable: true,
+      configurable: true,
+      value: 1000,
+    });
+    Object.defineProperty(document.documentElement, "clientHeight", {
+      writable: true,
+      configurable: true,
+      value: 740,
+    });
+
+    const { result } = renderHook(() =>
+      useWindowSize({ includeScrollbar: false }),
+    );
+    expect(result.current.width.get()).toBe(1000);
+    expect(result.current.height.get()).toBe(740);
+  });
+
+  it("type: 'visual' reads visualViewport when available", () => {
+    const mockVP = {
+      width: 375,
+      height: 667,
+      scale: 2,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    };
+    vi.stubGlobal("visualViewport", mockVP);
+
+    const { result } = renderHook(() => useWindowSize({ type: "visual" }));
+    expect(result.current.width.get()).toBe(750); // 375 * 2
+    expect(result.current.height.get()).toBe(1334); // 667 * 2
+  });
+
+  it("type: 'visual' falls back to innerWidth/innerHeight when visualViewport unavailable", () => {
+    vi.stubGlobal("visualViewport", null);
+
+    const { result } = renderHook(() => useWindowSize({ type: "visual" }));
+    expect(result.current.width.get()).toBe(1024);
+    expect(result.current.height.get()).toBe(768);
+  });
+
+  it("listens to orientation changes by default", () => {
+    const addSpy = vi.spyOn(window, "matchMedia").mockReturnValue({
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      matches: false,
+      media: "(orientation: portrait)",
+    } as any);
+
+    renderHook(() => useWindowSize());
+    expect(addSpy).toHaveBeenCalledWith("(orientation: portrait)");
+  });
+
+  it("listenOrientation: false does not update size on orientation change", () => {
+    let orientationListener: ((e: Event) => void) | null = null;
+
+    vi.stubGlobal("matchMedia", (_query: string) => ({
+      matches: false,
+      media: _query,
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        if (type === "change") orientationListener = listener;
+      }),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    } as unknown as MediaQueryList));
+
+    const { result } = renderHook(() =>
+      useWindowSize({ listenOrientation: false }),
+    );
+
+    // Change innerWidth but do NOT dispatch a resize event
+    (window as any).innerWidth = 500;
+
+    act(() => {
+      // Trigger orientation change — should NOT call update() when listenOrientation: false
+      orientationListener?.({
+        type: "change",
+        matches: true,
+      } as unknown as MediaQueryListEvent);
+    });
+
+    // Size stays at 1024 because orientation change was ignored
+    expect(result.current.width.get()).toBe(1024);
+  });
+
+  it("removes resize listener on unmount", async () => {
+    const addSpy = vi.spyOn(window, "addEventListener");
+    const removeSpy = vi.spyOn(window, "removeEventListener");
+
+    const { unmount } = renderHook(() => useWindowSize());
+    unmount();
+    await flush();
+
+    const resizeAdded = addSpy.mock.calls.some(([type]) => type === "resize");
+    const resizeRemoved = removeSpy.mock.calls.some(
+      ([type]) => type === "resize",
+    );
+
+    expect(resizeAdded).toBe(true);
+    expect(resizeRemoved).toBe(true);
+  });
+
+  it("type change via re-render triggers immediate re-measurement without resize event", async () => {
+    (window as any).outerWidth = 1100;
+    (window as any).outerHeight = 850;
+
+    const { result, rerender } = renderHook(
+      (props: { type: "inner" | "outer" | "visual" }) =>
+        useWindowSize({ type: props.type }),
+      { initialProps: { type: "inner" as "inner" | "outer" | "visual" } },
+    );
+
+    expect(result.current.width.get()).toBe(1024);
+    expect(result.current.height.get()).toBe(768);
+
+    await act(async () => {
+      rerender({ type: "outer" });
+      await flush();
+    });
+
+    expect(result.current.width.get()).toBe(1100);
+    expect(result.current.height.get()).toBe(850);
+  });
+
+  it("type as Observable → reactive re-measurement when Observable value changes", async () => {
+    (window as any).outerWidth = 1100;
+    (window as any).outerHeight = 850;
+
+    const type$ = observable<"inner" | "outer" | "visual">("inner");
+
+    const { result } = renderHook(() => useWindowSize({ type: type$ }));
+
+    // Initial: 'inner' → reads innerWidth/innerHeight
+    expect(result.current.width.get()).toBe(1024);
+    expect(result.current.height.get()).toBe(768);
+
+    // Change Observable value — useObserveEffect tracks opts$.type.get() → re-measurement
+    await act(async () => {
+      type$.set("outer");
+      await flush();
+    });
+
+    expect(result.current.width.get()).toBe(1100);
+    expect(result.current.height.get()).toBe(850);
+  });
+
+  it("includeScrollbar change via re-render triggers immediate re-measurement without resize event", async () => {
+    Object.defineProperty(document.documentElement, "clientWidth", {
+      writable: true,
+      configurable: true,
+      value: 1000,
+    });
+    Object.defineProperty(document.documentElement, "clientHeight", {
+      writable: true,
+      configurable: true,
+      value: 740,
+    });
+
+    const { result, rerender } = renderHook(
+      (props: { includeScrollbar: boolean }) =>
+        useWindowSize({ includeScrollbar: props.includeScrollbar }),
+      { initialProps: { includeScrollbar: true } },
+    );
+
+    expect(result.current.width.get()).toBe(1024);
+    expect(result.current.height.get()).toBe(768);
+
+    await act(async () => {
+      rerender({ includeScrollbar: false });
+      await flush();
+    });
+
+    expect(result.current.width.get()).toBe(1000);
+    expect(result.current.height.get()).toBe(740);
+  });
+
+  it("does not update after unmount", async () => {
+    const { result, unmount } = renderHook(() => useWindowSize());
+
+    unmount();
+    await flush();
+
+    act(() => {
+      (window as any).innerWidth = 999;
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    // Value stays at what it was before unmount (1024)
+    expect(result.current.width.get()).toBe(1024);
+  });
+
+  it("defaults to 0 initial size", () => {
+    // Verify the observable initializes with 0 before window is read
+    const { result } = renderHook(() => useWindowSize());
+    // After mount, actual window values are read
+    expect(typeof result.current.width.get()).toBe("number");
+    expect(typeof result.current.height.get()).toBe("number");
+  });
+});

package/src/elements/useWindowSize/index.ts

@@ -0,0 +1,107 @@
+"use client";
+import type { Observable } from "@legendapp/state";
+import {
+  useObservable,
+  useMount,
+  useObserveEffect,
+} from "@legendapp/state/react";
+import { useEventListener } from "../../browser/useEventListener";
+import { useMediaQuery } from "../../browser/useMediaQuery";
+import { useMayObservableOptions } from "../../function/useMayObservableOptions";
+import { useWhenMounted } from "../../function/useWhenMounted";
+import type { DeepMaybeObservable } from "../../types";
+
+export interface UseWindowSizeOptions {
+  initialWidth?: number;
+  initialHeight?: number;
+  listenOrientation?: boolean;
+  includeScrollbar?: boolean;
+  type?: "inner" | "outer" | "visual";
+}
+
+export type UseWindowSizeReturn = Observable<{
+  width: number;
+  height: number;
+}>;
+
+/*@__NO_SIDE_EFFECTS__*/
+export function useWindowSize(
+  options?: DeepMaybeObservable<UseWindowSizeOptions>,
+): UseWindowSizeReturn {
+  // Standard Pattern: normalize DeepMaybeObservable<Options> into a stable computed Observable.
+  const opts$ = useMayObservableOptions<UseWindowSizeOptions>(options, {
+    initialWidth: "peek",
+    initialHeight: "peek",
+  });
+
+  const size$ = useObservable({
+    width: opts$.initialWidth.peek() ?? 0,
+    height: opts$.initialHeight.peek() ?? 0,
+  });
+
+  const update = () => {
+    if (typeof window === "undefined") return;
+
+    const type = opts$.type.peek() ?? "inner";
+    const includeScrollbar = opts$.includeScrollbar.peek() !== false;
+
+    let width: number;
+    let height: number;
+
+    if (type === "outer") {
+      width = window.outerWidth;
+      height = window.outerHeight;
+    } else if (type === "visual") {
+      const vp = window.visualViewport;
+      if (vp) {
+        width = vp.width * vp.scale;
+        height = vp.height * vp.scale;
+      } else {
+        width = window.innerWidth;
+        height = window.innerHeight;
+      }
+    } else {
+      if (includeScrollbar) {
+        width = window.innerWidth;
+        height = window.innerHeight;
+      } else {
+        width = document.documentElement.clientWidth;
+        height = document.documentElement.clientHeight;
+      }
+    }
+
+    size$.assign({ width, height });
+  };
+
+  useMount(update);
+
+  useEventListener("resize", update, { passive: true });
+
+  const vp$ = useWhenMounted(() =>
+    opts$.type.peek() === "visual" ? window.visualViewport : null,
+  );
+
+  useEventListener(vp$, "resize", update);
+
+  // type 또는 includeScrollbar가 변경되면 즉시 재측정
+  // 단일 함수 형태: opts$.type.get()/opts$.includeScrollbar.get()으로 dep 등록,
+  // update()는 .peek()만 사용하므로 추가 dep을 등록하지 않음.
+  useObserveEffect((e) => {
+    opts$.type.get();
+    opts$.includeScrollbar.get();
+    if (e.num > 0) update();
+  });
+
+  const matches$ = useMediaQuery("(orientation: portrait)");
+  useObserveEffect(
+    matches$,
+    () => {
+      if (opts$.listenOrientation.get() !== false) {
+        update();
+      }
+    },
+    { immediate: false },
+  );
+
+  return size$;
+}

package/src/function/get/index.md

@@ -0,0 +1,25 @@
+---
+title: get
+description: Extract values from MaybeObservable types
+category: Observable Utilities
+---
+
+Extract raw values from `MaybeObservable` types (works with both raw values and Legend-State observables).
+
+
+## Usage
+
+```typescript
+import { get } from '@usels/core'
+import { observable } from '@legendapp/state'
+
+// With raw values
+const rawValue = { name: 'John', age: 30 }
+console.log(get(rawValue)) // { name: 'John', age: 30 }
+console.log(get(rawValue, 'name')) // 'John'
+
+// With observables
+const obs$ = observable({ name: 'John', age: 30 })
+console.log(get(obs$)) // { name: 'John', age: 30 }
+console.log(get(obs$, 'name')) // 'John'
+```

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

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { get } from ".";
+import { observable } from "@legendapp/state";
+describe("get() - single argument", () => {
+  it("returns raw value as-is", () => {
+    expect(get("hello")).toBe("hello");
+    expect(get(42)).toBe(42);
+    expect(get(true)).toBe(true);
+  });
+
+  it("extracts value from Observable", () => {
+    const obs$ = observable("world");
+    expect(get(obs$)).toBe("world");
+  });
+
+  it("handles null and undefined", () => {
+    expect(get(null)).toBe(null);
+    expect(get(undefined)).toBe(undefined);
+    expect(get(observable(null))).toBe(null);
+    expect(get(observable(undefined))).toBe(undefined);
+  });
+
+  it("handles objects", () => {
+    const obj = { name: "John" };
+    expect(get(obj)).toEqual(obj);
+    expect(get(observable(obj))).toEqual(obj);
+  });
+
+  it("handles arrays", () => {
+    const arr = [1, 2, 3];
+    expect(get(arr)).toEqual(arr);
+    expect(get(observable(arr))).toEqual(arr);
+  });
+});
+
+describe("get() - two arguments (property access)", () => {
+  it("extracts property from raw object", () => {
+    const obj = { name: "John", age: 30 };
+    expect(get(obj, "name")).toBe("John");
+    expect(get(obj, "age")).toBe(30);
+  });
+
+  it("extracts property from Observable object", () => {
+    const obs$ = observable({ name: "Jane", age: 25 });
+    expect(get(obs$, "name")).toBe("Jane");
+    expect(get(obs$, "age")).toBe(25);
+  });
+
+  it("returns undefined for missing keys", () => {
+    const obj = { name: "John" };
+    expect(get(obj, "age" as any)).toBe(undefined);
+    expect(get(observable(obj), "age" as any)).toBe(undefined);
+  });
+
+  it("handles nested observable properties", () => {
+    const filter$ = observable({ category: "electronics" });
+    expect(get(filter$, "category")).toBe("electronics");
+  });
+
+  it("returns undefined when value is not an object", () => {
+    expect(get("hello", "length" as any)).toBe(undefined);
+    expect(get(observable("hello"), "length" as any)).toBe(undefined);
+    expect(get(42, "toString" as any)).toBe(undefined);
+  });
+
+  it("handles null and undefined gracefully", () => {
+    expect(get(null, "key" as any)).toBe(undefined);
+    expect(get(undefined, "key" as any)).toBe(undefined);
+    expect(get(observable(null), "key" as any)).toBe(undefined);
+  });
+
+  it("preserves property value types", () => {
+    const obj = {
+      str: "text",
+      num: 42,
+      bool: true,
+      arr: [1, 2, 3],
+      nested: { value: "deep" },
+    };
+
+    expect(get(obj, "str")).toBe("text");
+    expect(get(obj, "num")).toBe(42);
+    expect(get(obj, "bool")).toBe(true);
+    expect(get(obj, "arr")).toEqual([1, 2, 3]);
+    expect(get(obj, "nested")).toEqual({ value: "deep" });
+  });
+});

package/src/function/get/index.ts

@@ -0,0 +1,70 @@
+import { isObservable } from "@legendapp/state";
+import { MaybeObservable } from "../../types";
+
+/**
+ * Extracts the value from a MaybeObservable
+ * If the value is an Observable, calls .get() to extract it
+ * Otherwise returns the value as-is
+ *
+ * @param maybeObservable - A value that might be an Observable
+ * @returns The extracted value
+ *
+ * @example
+ * ```ts
+ * import { observable } from '@legendapp/state'
+ * import { get } from '@usels/core'
+ *
+ * const value = get('hello')           // 'hello'
+ * const obsValue = get(observable(42)) // 42
+ * ```
+ */
+export function get<T>(maybeObservable: MaybeObservable<T>): T;
+export function get<T>(maybeObservable: MaybeObservable<T> | undefined): T | undefined;
+
+/**
+ * Extracts a property value from a MaybeObservable object
+ *
+ * @param maybeObservable - A value that might be an Observable
+ * @param key - The property key to extract
+ * @returns The property value, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * import { observable } from '@legendapp/state'
+ * import { get } from '@usels/core'
+ *
+ * const obj = { name: 'John' }
+ * const obs$ = observable({ name: 'Jane' })
+ *
+ * get(obj, 'name')    // 'John'
+ * get(obs$, 'name')   // 'Jane'
+ * get(obs$, 'age')    // undefined
+ * ```
+ */
+export function get<T, K extends keyof T>(
+  maybeObservable: MaybeObservable<T>,
+  key: K,
+): T[K] | undefined;
+
+// Implementation
+export function get<T>(
+  maybeObservable: MaybeObservable<T>,
+  key?: keyof T,
+): any {
+  // Extract the base value
+  const value = isObservable(maybeObservable)
+    ? maybeObservable.get()
+    : maybeObservable;
+
+  // If no key provided, return the value (single-arg overload)
+  if (key === undefined) {
+    return value;
+  }
+
+  // If key provided, extract property (two-arg overload)
+  if (value !== null && value !== undefined && typeof value === "object") {
+    return (value as any)[key];
+  }
+
+  return undefined;
+}