@praxisjs/composables 0.1.5 → 1.0.0

package/src/__tests__/utilities.test.ts

@@ -1,282 +1,254 @@
 // @vitest-environment jsdom
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-
 import { signal } from "@praxisjs/core/internal";
 
-import { usePagination, useClipboard, useGeolocation, useTimeAgo } from "../utilities";
-
-describe("usePagination", () => {
-  it("starts on page 1 by default", () => {
-    const p = usePagination({ total: 100, pageSize: 10 });
-    expect(p.page()).toBe(1);
-  });
-
-  it("respects initial page option", () => {
-    const p = usePagination({ total: 100, pageSize: 10, initial: 3 });
-    expect(p.page()).toBe(3);
-  });
-
-  it("computes total pages correctly", () => {
-    expect(usePagination({ total: 100, pageSize: 10 }).totalPages()).toBe(10);
-    expect(usePagination({ total: 101, pageSize: 10 }).totalPages()).toBe(11);
-    expect(usePagination({ total: 5, pageSize: 10 }).totalPages()).toBe(1);
-  });
-
-  it("computes offset", () => {
-    const p = usePagination({ total: 100, pageSize: 10 });
-    expect(p.offset()).toBe(0);
-    p.goTo(3);
-    expect(p.offset()).toBe(20);
-  });
-
-  it("next() advances the page", () => {
-    const p = usePagination({ total: 30, pageSize: 10 });
-    p.next();
-    expect(p.page()).toBe(2);
-  });
+import { Clipboard, Geolocation, TimeAgo, Pagination } from "../utilities";
 
-  it("next() does nothing on last page", () => {
-    const p = usePagination({ total: 10, pageSize: 10 });
-    p.next();
-    expect(p.page()).toBe(1);
-  });
-
-  it("prev() goes back", () => {
-    const p = usePagination({ total: 30, pageSize: 10, initial: 3 });
-    p.prev();
-    expect(p.page()).toBe(2);
-  });
-
-  it("prev() does nothing on first page", () => {
-    const p = usePagination({ total: 30, pageSize: 10 });
-    p.prev();
-    expect(p.page()).toBe(1);
-  });
-
-  it("goTo() clamps to valid range", () => {
-    const p = usePagination({ total: 30, pageSize: 10 });
-    p.goTo(0);
-    expect(p.page()).toBe(1);
-    p.goTo(99);
-    expect(p.page()).toBe(3);
-  });
-
-  it("first() jumps to page 1", () => {
-    const p = usePagination({ total: 50, pageSize: 10, initial: 5 });
-    p.first();
-    expect(p.page()).toBe(1);
-  });
+// ── Clipboard ─────────────────────────────────────────────────────────────────
 
-  it("last() jumps to last page", () => {
-    const p = usePagination({ total: 50, pageSize: 10 });
-    p.last();
-    expect(p.page()).toBe(5);
-  });
-
-  it("hasNext is false on last page", () => {
-    const p = usePagination({ total: 10, pageSize: 10 });
-    expect(p.hasNext()).toBe(false);
-  });
-
-  it("hasPrev is false on first page", () => {
-    const p = usePagination({ total: 30, pageSize: 10 });
-    expect(p.hasPrev()).toBe(false);
-  });
-
-  it("pages() returns array of page numbers", () => {
-    const p = usePagination({ total: 30, pageSize: 10 });
-    expect(p.pages()).toEqual([1, 2, 3]);
-  });
-
-  it("pageSize() reflects the configured size", () => {
-    const p = usePagination({ total: 100, pageSize: 25 });
-    expect(p.pageSize()).toBe(25);
-  });
-
-  it("accepts a factory function for options", () => {
-    const p = usePagination(() => ({ total: 50, pageSize: 5 }));
-    expect(p.totalPages()).toBe(10);
-  });
-});
-
-// ── useClipboard ──────────────────────────────────────────────────────────────
-
-describe("useClipboard", () => {
+describe("Clipboard", () => {
   beforeEach(() => {
-    vi.useFakeTimers();
     Object.defineProperty(navigator, "clipboard", {
       value: { writeText: vi.fn().mockResolvedValue(undefined) },
       configurable: true,
-      writable: true,
     });
   });
 
-  afterEach(() => {
-    vi.clearAllTimers();
-    vi.useRealTimers();
-  });
-
-  it("copied starts as false", () => {
-    const { copied } = useClipboard();
+  it("starts with copied=false and empty content", () => {
+    const cb = new Clipboard();
+    const { copied, content } = cb.setup() as { copied: () => boolean; content: () => string };
     expect(copied()).toBe(false);
-  });
-
-  it("content starts as empty string", () => {
-    const { content } = useClipboard();
     expect(content()).toBe("");
   });
 
-  it("sets copied to true and content to the text after copy()", async () => {
-    const { copy, copied, content } = useClipboard();
+  it("sets copied=true and content after copy", async () => {
+    const cb = new Clipboard();
+    const { copy, copied, content } = cb.setup() as {
+      copy: (t: string) => Promise<void>;
+      copied: () => boolean;
+      content: () => string;
+    };
     await copy("hello");
     expect(copied()).toBe(true);
     expect(content()).toBe("hello");
   });
 
-  it("resets copied to false after resetDelay", async () => {
-    const { copy, copied } = useClipboard(1000);
+  it("resets copied after resetDelay", async () => {
+    vi.useFakeTimers();
+    const cb = new Clipboard(1000);
+    const { copy, copied } = cb.setup() as {
+      copy: (t: string) => Promise<void>;
+      copied: () => boolean;
+    };
     await copy("test");
     expect(copied()).toBe(true);
     vi.advanceTimersByTime(1000);
     expect(copied()).toBe(false);
+    vi.useRealTimers();
   });
 
-  it("warns and does not update state on clipboard failure", async () => {
-    (navigator.clipboard as unknown as { writeText: ReturnType<typeof vi.fn> }).writeText =
-      vi.fn().mockRejectedValue(new Error("denied"));
+  it("warns on clipboard failure", async () => {
+    (navigator.clipboard.writeText as ReturnType<typeof vi.fn>).mockRejectedValue(new Error("denied"));
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const { copy, copied } = useClipboard();
+    const cb = new Clipboard();
+    const { copy } = cb.setup() as { copy: (t: string) => Promise<void> };
     await copy("fail");
-    expect(copied()).toBe(false);
     expect(warn).toHaveBeenCalled();
     warn.mockRestore();
   });
 });
 
-// ── useGeolocation ────────────────────────────────────────────────────────────
-
-describe("useGeolocation", () => {
-  it("starts with loading=true and lat/lng null", () => {
-    const successCb: PositionCallback[] = [];
-    Object.defineProperty(navigator, "geolocation", {
-      value: {
-        getCurrentPosition: (success: PositionCallback) => {
-          successCb.push(success);
-        },
-      },
-      configurable: true,
-    });
+// ── Geolocation ───────────────────────────────────────────────────────────────
 
-    const geo = useGeolocation();
-    expect(geo.loading()).toBe(true);
-    expect(geo.lat()).toBeNull();
-    expect(geo.lng()).toBeNull();
+describe("Geolocation", () => {
+  function mockGeolocation(impl: (success: PositionCallback, error?: PositionErrorCallback | null) => void) {
+    vi.stubGlobal("navigator", {
+      ...navigator,
+      geolocation: { getCurrentPosition: impl },
+    });
+  }
+
+  afterEach(() => { vi.unstubAllGlobals(); });
+
+  it("starts in loading state", () => {
+    mockGeolocation(() => {});
+    const geo = new Geolocation();
+    const { loading, lat, lng, error } = geo.setup() as {
+      loading: () => boolean;
+      lat: () => number | null;
+      lng: () => number | null;
+      error: () => GeolocationPositionError | null;
+    };
+    expect(loading()).toBe(true);
+    expect(lat()).toBeNull();
+    expect(lng()).toBeNull();
+    expect(error()).toBeNull();
+  });
+
+  it("sets coordinates on success", () => {
+    mockGeolocation((success) => {
+      success({ coords: { latitude: 51.5, longitude: -0.1 } } as GeolocationPosition);
+    });
+    const geo = new Geolocation();
+    const { loading, lat, lng } = geo.setup() as {
+      loading: () => boolean;
+      lat: () => number | null;
+      lng: () => number | null;
+    };
+    expect(loading()).toBe(false);
+    expect(lat()).toBe(51.5);
+    expect(lng()).toBe(-0.1);
+  });
+
+  it("sets error on failure", () => {
+    const mockError = { code: 1, message: "denied" } as GeolocationPositionError;
+    mockGeolocation((_s, error) => { error!(mockError); });
+    const geo = new Geolocation();
+    const { loading, error } = geo.setup() as {
+      loading: () => boolean;
+      error: () => GeolocationPositionError | null;
+    };
+    expect(loading()).toBe(false);
+    expect(error()).toBe(mockError);
   });
+});
 
-  it("updates lat/lng/loading on success", () => {
-    let successCb: PositionCallback | null = null;
-    Object.defineProperty(navigator, "geolocation", {
-      value: {
-        getCurrentPosition: (success: PositionCallback) => {
-          successCb = success;
-        },
-      },
-      configurable: true,
-    });
+// ── TimeAgo ───────────────────────────────────────────────────────────────────
 
-    const geo = useGeolocation();
+describe("TimeAgo", () => {
+  beforeEach(() => { vi.useFakeTimers(); });
+  afterEach(() => { vi.useRealTimers(); });
 
-    successCb!({
-      coords: { latitude: 10.5, longitude: 20.5 } as GeolocationCoordinates,
-    } as GeolocationPosition);
+  const now = Date.now();
 
-    expect(geo.lat()).toBe(10.5);
-    expect(geo.lng()).toBe(20.5);
-    expect(geo.loading()).toBe(false);
+  it("formats seconds ago", () => {
+    const ta = new TimeAgo(() => now - 30_000, "en");
+    const { value } = ta.setup() as { value: () => string };
+    expect(value()).toContain("30 seconds ago");
   });
 
-  it("sets error and loading=false on failure", () => {
-    let errorCb: PositionErrorCallback | null = null;
-    Object.defineProperty(navigator, "geolocation", {
-      value: {
-        getCurrentPosition: (_s: PositionCallback, error: PositionErrorCallback) => {
-          errorCb = error;
-        },
-      },
-      configurable: true,
-    });
+  it("formats minutes ago", () => {
+    const ta = new TimeAgo(() => now - 5 * 60_000, "en");
+    const { value } = ta.setup() as { value: () => string };
+    expect(value()).toContain("5 minutes ago");
+  });
+
+  it("formats hours ago", () => {
+    const ta = new TimeAgo(() => now - 2 * 3_600_000, "en");
+    const { value } = ta.setup() as { value: () => string };
+    expect(value()).toContain("2 hours ago");
+  });
 
-    const geo = useGeolocation();
-    const fakeError = { code: 1, message: "denied" } as GeolocationPositionError;
-    errorCb!(fakeError);
+  it("formats days ago", () => {
+    const ta = new TimeAgo(() => now - 3 * 86_400_000, "en");
+    const { value } = ta.setup() as { value: () => string };
+    expect(value()).toContain("3 days ago");
+  });
+
+  it("formats months ago", () => {
+    const ta = new TimeAgo(() => now - 60 * 86_400_000, "en");
+    const { value } = ta.setup() as { value: () => string };
+    expect(value()).toContain("2 months ago");
+  });
 
-    expect(geo.error()).toBe(fakeError);
-    expect(geo.loading()).toBe(false);
+  it("accepts a signal as source", () => {
+    const src = signal(now - 30_000);
+    const ta = new TimeAgo(src, "en");
+    const { value } = ta.setup() as { value: () => string };
+    expect(value()).toContain("30 seconds ago");
+  });
+
+  it("clears interval on unmount", () => {
+    const clearInterval = vi.spyOn(globalThis, "clearInterval");
+    const ta = new TimeAgo(() => now, "en");
+    ta.setup();
+    ta.onUnmount();
+    expect(clearInterval).toHaveBeenCalled();
   });
 });
 
-// ── useTimeAgo ────────────────────────────────────────────────────────────────
+// ── Pagination ────────────────────────────────────────────────────────────────
 
-describe("useTimeAgo", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
+describe("Pagination", () => {
+  it("initialises with defaults", () => {
+    const p = new Pagination({ total: 100, pageSize: 10 });
+    const s = p.setup() as {
+      page: () => number; totalPages: () => number; offset: () => number;
+      hasNext: () => boolean; hasPrev: () => boolean; pageSize: () => number;
+    };
+    expect(s.page()).toBe(1);
+    expect(s.totalPages()).toBe(10);
+    expect(s.offset()).toBe(0);
+    expect(s.hasNext()).toBe(true);
+    expect(s.hasPrev()).toBe(false);
+    expect(s.pageSize()).toBe(10);
   });
 
-  afterEach(() => {
-    vi.clearAllTimers();
-    vi.useRealTimers();
+  it("respects initial page", () => {
+    const p = new Pagination({ total: 100, pageSize: 10, initial: 3 });
+    const { page, offset } = p.setup() as { page: () => number; offset: () => number };
+    expect(page()).toBe(3);
+    expect(offset()).toBe(20);
   });
 
-  it("returns a computed string", () => {
-    const now = Date.now();
-    const t = useTimeAgo(() => now);
-    expect(typeof t()).toBe("string");
+  it("next() advances page", () => {
+    const p = new Pagination({ total: 30, pageSize: 10 });
+    const { page, next } = p.setup() as { page: () => number; next: () => void };
+    (next as () => void)();
+    expect(page()).toBe(2);
   });
 
-  it("formats seconds ago", () => {
-    const now = Date.now();
-    const t = useTimeAgo(() => now - 30_000);
-    expect(t()).toMatch(/segundo|second/i);
+  it("prev() goes back a page", () => {
+    const p = new Pagination({ total: 30, pageSize: 10, initial: 3 });
+    const { page, prev } = p.setup() as { page: () => number; prev: () => void };
+    (prev as () => void)();
+    expect(page()).toBe(2);
   });
 
-  it("formats minutes ago", () => {
-    const now = Date.now();
-    const t = useTimeAgo(() => now - 5 * 60_000);
-    expect(t()).toMatch(/minuto|minute/i);
+  it("next() does not go past last page", () => {
+    const p = new Pagination({ total: 10, pageSize: 10 });
+    const { page, next } = p.setup() as { page: () => number; next: () => void };
+    (next as () => void)();
+    expect(page()).toBe(1);
   });
 
-  it("formats hours ago", () => {
-    const now = Date.now();
-    const t = useTimeAgo(() => now - 2 * 3_600_000);
-    expect(t()).toMatch(/hora|hour/i);
+  it("prev() does not go before first page", () => {
+    const p = new Pagination({ total: 30, pageSize: 10 });
+    const { page, prev } = p.setup() as { page: () => number; prev: () => void };
+    (prev as () => void)();
+    expect(page()).toBe(1);
   });
 
-  it("formats days ago", () => {
-    const now = Date.now();
-    const t = useTimeAgo(() => now - 3 * 86_400_000);
-    expect(t()).toMatch(/dia|day/i);
+  it("goTo() jumps to a page", () => {
+    const p = new Pagination({ total: 50, pageSize: 10 });
+    const { page, goTo } = p.setup() as { page: () => number; goTo: (n: number) => void };
+    (goTo as (n: number) => void)(4);
+    expect(page()).toBe(4);
   });
 
-  it("formats months ago", () => {
-    const now = Date.now();
-    const t = useTimeAgo(() => now - 60 * 86_400_000);
-    expect(t()).toMatch(/mes|month/i);
+  it("first() jumps to page 1", () => {
+    const p = new Pagination({ total: 50, pageSize: 10, initial: 5 });
+    const { page, first } = p.setup() as { page: () => number; first: () => void };
+    (first as () => void)();
+    expect(page()).toBe(1);
   });
 
-  it("accepts a signal source", () => {
-    const src = signal(Date.now() - 90_000);
-    const t = useTimeAgo(src);
-    expect(typeof t()).toBe("string");
+  it("last() jumps to last page", () => {
+    const p = new Pagination({ total: 50, pageSize: 10 });
+    const { page, last } = p.setup() as { page: () => number; last: () => void };
+    (last as () => void)();
+    expect(page()).toBe(5);
+  });
+
+  it("pages() returns array of page numbers", () => {
+    const p = new Pagination({ total: 30, pageSize: 10 });
+    const { pages } = p.setup() as { pages: () => number[] };
+    expect((pages as () => number[])()).toEqual([1, 2, 3]);
   });
 
-  it("ticks after 60 seconds via setInterval", () => {
-    const now = Date.now();
-    const t = useTimeAgo(() => now - 30_000);
-    const before = t();
-    vi.advanceTimersByTime(60_000);
-    // After ticking, the computed re-evaluates (may or may not change the string)
-    expect(typeof t()).toBe("string");
-    // The interval ran — just verify no errors
-    expect(before).toBeTruthy();
+  it("clamps totalPages for fractional divisions", () => {
+    const p = new Pagination({ total: 25, pageSize: 10 });
+    const { totalPages } = p.setup() as { totalPages: () => number };
+    expect(totalPages()).toBe(3);
   });
 });

package/src/browser.ts

@@ -1,63 +1,144 @@
+import { Composable } from "@praxisjs/core";
 import { signal, computed } from "@praxisjs/core/internal";
-import type { Computed } from "@praxisjs/shared";
-
-export function useMediaQuery(query: string): Computed<boolean> {
-  const mql = window.matchMedia(query);
-  const matches = signal(mql.matches);
-  mql.addEventListener("change", (e: MediaQueryListEvent) => {
-    matches.set(e.matches);
-  });
-  return computed(() => matches());
+
+export class MediaQuery extends Composable {
+  declare matches: boolean;
+
+  private _mql?: MediaQueryList;
+  private _handler?: (e: MediaQueryListEvent) => void;
+
+  constructor(private readonly query: string) {
+    super();
+  }
+
+  setup() {
+    this._mql = window.matchMedia(this.query);
+    const matches = signal(this._mql.matches);
+    this._handler = (e) => { matches.set(e.matches); };
+    this._mql.addEventListener("change", this._handler);
+    return { matches };
+  }
+
+  onUnmount() {
+    if (this._mql && this._handler) {
+      this._mql.removeEventListener("change", this._handler);
+    }
+  }
 }
 
-export function useColorScheme() {
-  const isDark = useMediaQuery("(prefers-color-scheme: dark)");
-  const isLight = computed(() => !isDark());
-  return { isDark, isLight };
+export class ColorScheme extends Composable {
+  declare isDark: boolean;
+  declare isLight: boolean;
+
+  private _mql?: MediaQueryList;
+  private _handler?: (e: MediaQueryListEvent) => void;
+
+  setup() {
+    this._mql = window.matchMedia("(prefers-color-scheme: dark)");
+    const isDark = signal(this._mql.matches);
+    const isLight = computed(() => !isDark());
+    this._handler = (e) => { isDark.set(e.matches); };
+    this._mql.addEventListener("change", this._handler);
+    return { isDark, isLight };
+  }
+
+  onUnmount() {
+    if (this._mql && this._handler) {
+      this._mql.removeEventListener("change", this._handler);
+    }
+  }
 }
 
-export function useMouse() {
-  const x = signal(0);
-  const y = signal(0);
-  window.addEventListener("mousemove", (e) => {
-    x.set(e.clientX);
-    y.set(e.clientY);
-  });
-  return { x: computed(() => x()), y: computed(() => y()) };
+export class Mouse extends Composable {
+  declare x: number;
+  declare y: number;
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private _handler = (_e: MouseEvent) => {};
+
+  setup() {
+    const x = signal(0);
+    const y = signal(0);
+    this._handler = (e) => { x.set(e.clientX); y.set(e.clientY); };
+    window.addEventListener("mousemove", this._handler);
+    return { x, y };
+  }
+
+  onUnmount() {
+    window.removeEventListener("mousemove", this._handler);
+  }
 }
 
-export function useKeyCombo(combo: string): Computed<boolean> {
-  const parts = combo.toLowerCase().split("+");
-  const pressed = signal(false);
-  window.addEventListener("keydown", (e: KeyboardEvent) => {
-    const ctrl = parts.includes("ctrl") ? e.ctrlKey : true;
-    const shift = parts.includes("shift") ? e.shiftKey : true;
-    const alt = parts.includes("alt") ? e.altKey : true;
-    const key = parts.find(
-      (p) => !["ctrl", "shift", "alt", "meta"].includes(p),
-    );
-    if (ctrl && shift && alt && (!key || e.key.toLowerCase() === key))
-      pressed.set(true);
-  });
-  window.addEventListener("keyup", () => {
-    pressed.set(false);
-  });
-  return computed(() => pressed());
+export class KeyCombo extends Composable {
+  declare pressed: boolean;
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private _keydownHandler = (_e: KeyboardEvent) => {};
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private _keyupHandler = () => {};
+
+  constructor(private readonly combo: string) {
+    super();
+  }
+
+  setup() {
+    const parts = this.combo.toLowerCase().split("+");
+    const pressed = signal(false);
+
+    this._keydownHandler = (e) => {
+      const ctrl = parts.includes("ctrl") ? e.ctrlKey : true;
+      const shift = parts.includes("shift") ? e.shiftKey : true;
+      const alt = parts.includes("alt") ? e.altKey : true;
+      const key = parts.find((p) => !["ctrl", "shift", "alt", "meta"].includes(p));
+      if (ctrl && shift && alt && (!key || e.key.toLowerCase() === key)) {
+        pressed.set(true);
+      }
+    };
+    this._keyupHandler = () => { pressed.set(false); };
+
+    window.addEventListener("keydown", this._keydownHandler);
+    window.addEventListener("keyup", this._keyupHandler);
+    return { pressed };
+  }
+
+  onUnmount() {
+    window.removeEventListener("keydown", this._keydownHandler);
+    window.removeEventListener("keyup", this._keyupHandler);
+  }
 }
 
-export function useIdle(timeout = 60_000): Computed<boolean> {
-  const idle = signal(false);
-  let timer: ReturnType<typeof setTimeout>;
-  const reset = () => {
-    idle.set(false);
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      idle.set(true);
-    }, timeout);
-  };
-  ["mousemove", "keydown", "click", "scroll", "touchstart"].forEach((e) => {
-    window.addEventListener(e, reset, { passive: true });
-  });
-  reset();
-  return computed(() => idle());
+export class Idle extends Composable {
+  declare idle: boolean;
+
+  private _listeners: Array<[string, () => void]> = [];
+  private _timer?: ReturnType<typeof setTimeout>;
+
+  constructor(private readonly timeout = 60_000) {
+    super();
+  }
+
+  setup() {
+    const idle = signal(false);
+    const reset = () => {
+      idle.set(false);
+      clearTimeout(this._timer);
+      this._timer = setTimeout(() => { idle.set(true); }, this.timeout);
+    };
+
+    ["mousemove", "keydown", "click", "scroll", "touchstart"].forEach((event) => {
+      window.addEventListener(event, reset, { passive: true });
+      this._listeners.push([event, reset]);
+    });
+
+    reset();
+    return { idle };
+  }
+
+  onUnmount() {
+    clearTimeout(this._timer);
+    this._listeners.forEach(([event, handler]) => {
+      window.removeEventListener(event, handler);
+    });
+    this._listeners = [];
+  }
 }