@praxisjs/composables 1.0.0 → 1.0.2

package/src/__tests__/dom.test.ts

@@ -189,6 +189,82 @@ describe("Intersection", () => {
   });
 });
 
+// ── ElementSize (additional) ──────────────────────────────────────────────────
+
+describe("ElementSize (additional)", () => {
+  it("ref.current changes to a new element: old observer is disconnected and new one started", () => {
+    const disconnectFn = vi.fn();
+    const observeFn = vi.fn();
+
+    vi.stubGlobal("ResizeObserver", class {
+      observe = observeFn;
+      disconnect = disconnectFn;
+    });
+
+    const el1 = document.createElement("div");
+    const ref = { current: el1 as HTMLElement | null };
+    const es = new ElementSize(ref);
+    es.setup();
+
+    // Disconnect old observer and create new one for el2
+    es.onUnmount();
+    expect(disconnectFn).toHaveBeenCalled();
+
+    const el2 = document.createElement("div");
+    ref.current = el2;
+    const es2 = new ElementSize(ref);
+    es2.setup();
+    expect(observeFn).toHaveBeenCalledWith(el2);
+  });
+});
+
+// ── Intersection (additional) ─────────────────────────────────────────────────
+
+describe("Intersection (additional)", () => {
+  let observerCallback: IntersectionObserverCallback;
+
+  beforeEach(() => {
+    vi.stubGlobal("IntersectionObserver", class {
+      constructor(cb: IntersectionObserverCallback) { observerCallback = cb; }
+      observe = vi.fn();
+      disconnect = vi.fn();
+    });
+  });
+
+  it("visibility toggles false after being true", () => {
+    const el = document.createElement("div");
+    const ref = { current: el };
+    const int = new Intersection(ref);
+    const { visible } = int.setup() as { visible: () => boolean };
+
+    observerCallback(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    );
+    expect(visible()).toBe(true);
+
+    observerCallback(
+      [{ isIntersecting: false } as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    );
+    expect(visible()).toBe(false);
+  });
+});
+
+// ── ScrollPosition (additional) ───────────────────────────────────────────────
+
+describe("ScrollPosition (additional)", () => {
+  it("setup() called twice registers only one scroll listener", () => {
+    const el = document.createElement("div");
+    const add = vi.spyOn(el, "addEventListener");
+    const sp = new ScrollPosition(el);
+    sp.setup();
+    sp.setup();
+    const scrollCalls = add.mock.calls.filter((c) => c[0] === "scroll").length;
+    expect(scrollCalls).toBe(1);
+  });
+});
+
 // ── Focus ─────────────────────────────────────────────────────────────────────
 
 describe("Focus", () => {
@@ -258,4 +334,72 @@ describe("Focus", () => {
     document.body.removeChild(el1);
     document.body.removeChild(el2);
   });
+
+  it("setup() called twice registers only one listener pair", () => {
+    const el = document.createElement("input");
+    document.body.appendChild(el);
+    const add = vi.spyOn(el, "addEventListener");
+    const ref = { current: el };
+    const focus = new Focus(ref);
+    focus.setup();
+    focus.setup();
+    const focusCalls = add.mock.calls.filter((c) => c[0] === "focus").length;
+    expect(focusCalls).toBe(1);
+    document.body.removeChild(el);
+  });
+});
+
+// ── WindowSize (additional) ───────────────────────────────────────────────────
+
+describe("WindowSize (additional)", () => {
+  it("setup() called twice returns the same view object", () => {
+    const ws = new WindowSize();
+    const view1 = ws.setup();
+    const view2 = ws.setup();
+    expect(view1).toBe(view2);
+    ws.onUnmount();
+  });
+
+  it("setup() called twice registers only one resize listener", () => {
+    const add = vi.spyOn(window, "addEventListener");
+    const ws = new WindowSize();
+    ws.setup();
+    ws.setup();
+    const resizeCalls = add.mock.calls.filter((c) => c[0] === "resize").length;
+    expect(resizeCalls).toBe(1);
+    ws.onUnmount();
+    vi.restoreAllMocks();
+  });
+});
+
+// ── ElementSize (cache) ───────────────────────────────────────────────────────
+
+describe("ElementSize (cache)", () => {
+  it("setup() called twice returns the same view object", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const ref = { current: el };
+    const es = new ElementSize(ref);
+    const view1 = es.setup();
+    const view2 = es.setup();
+    expect(view1).toBe(view2);
+    es.onUnmount();
+    document.body.removeChild(el);
+  });
+});
+
+// ── Intersection (cache) ──────────────────────────────────────────────────────
+
+describe("Intersection (cache)", () => {
+  it("setup() called twice returns the same view object", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const ref = { current: el };
+    const inter = new Intersection(ref);
+    const view1 = inter.setup();
+    const view2 = inter.setup();
+    expect(view1).toBe(view2);
+    inter.onUnmount();
+    document.body.removeChild(el);
+  });
 });

package/src/__tests__/utilities.test.ts

@@ -56,6 +56,17 @@ describe("Clipboard", () => {
     expect(warn).toHaveBeenCalled();
     warn.mockRestore();
   });
+
+  it("setTimeout is cleared on onUnmount", async () => {
+    vi.useFakeTimers();
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+    const cb = new Clipboard(1000);
+    const { copy } = cb.setup() as { copy: (t: string) => Promise<void> };
+    await copy("hello");
+    cb.onUnmount();
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+    vi.useRealTimers();
+  });
 });
 
 // ── Geolocation ───────────────────────────────────────────────────────────────
@@ -111,6 +122,42 @@ describe("Geolocation", () => {
     expect(loading()).toBe(false);
     expect(error()).toBe(mockError);
   });
+
+  it("success callback after unmount does not update state", () => {
+    let capturedSuccess: PositionCallback | undefined;
+    mockGeolocation((success) => { capturedSuccess = success; });
+
+    const geo = new Geolocation();
+    const { lat, lng, loading } = geo.setup() as {
+      lat: () => number | null;
+      lng: () => number | null;
+      loading: () => boolean;
+    };
+
+    geo.onUnmount();
+    capturedSuccess!({ coords: { latitude: 99, longitude: 99 } } as GeolocationPosition);
+
+    expect(lat()).toBeNull();
+    expect(lng()).toBeNull();
+    expect(loading()).toBe(true);
+  });
+
+  it("error callback after unmount does not update state", () => {
+    let capturedError: PositionErrorCallback | undefined;
+    mockGeolocation((_success, error) => { capturedError = error ?? undefined; });
+
+    const geo = new Geolocation();
+    const { error, loading } = geo.setup() as {
+      error: () => GeolocationPositionError | null;
+      loading: () => boolean;
+    };
+
+    geo.onUnmount();
+    capturedError!({ code: 1, message: "denied" } as GeolocationPositionError);
+
+    expect(error()).toBeNull();
+    expect(loading()).toBe(true);
+  });
 });
 
 // ── TimeAgo ───────────────────────────────────────────────────────────────────
@@ -165,6 +212,13 @@ describe("TimeAgo", () => {
     ta.onUnmount();
     expect(clearInterval).toHaveBeenCalled();
   });
+
+  it("future date produces a positive relative time string (e.g. 'in 30 seconds')", () => {
+    // A future timestamp produces a positive diff; Intl.RelativeTimeFormat formats it as "in X"
+    const ta = new TimeAgo(() => now + 30_000, "en");
+    const { value } = ta.setup() as { value: () => string };
+    expect(value()).toContain("in 30 seconds");
+  });
 });
 
 // ── Pagination ────────────────────────────────────────────────────────────────
@@ -251,4 +305,12 @@ describe("Pagination", () => {
     const { totalPages } = p.setup() as { totalPages: () => number };
     expect(totalPages()).toBe(3);
   });
+
+  it("throws when pageSize is 0", () => {
+    expect(() => new Pagination({ total: 10, pageSize: 0 })).toThrow("pageSize must be greater than 0");
+  });
+
+  it("throws when pageSize is negative", () => {
+    expect(() => new Pagination({ total: 10, pageSize: -1 })).toThrow("pageSize must be greater than 0");
+  });
 });

package/src/browser.ts

@@ -6,17 +6,20 @@ export class MediaQuery extends Composable {
 
   private _mql?: MediaQueryList;
   private _handler?: (e: MediaQueryListEvent) => void;
+  private _view?: Record<string, unknown>;
 
   constructor(private readonly query: string) {
     super();
   }
 
   setup() {
+    if (this._view) return this._view;
     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 };
+    this._view = { matches };
+    return this._view;
   }
 
   onUnmount() {
@@ -32,14 +35,17 @@ export class ColorScheme extends Composable {
 
   private _mql?: MediaQueryList;
   private _handler?: (e: MediaQueryListEvent) => void;
+  private _view?: Record<string, unknown>;
 
   setup() {
+    if (this._view) return this._view;
     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 };
+    this._view = { isDark, isLight };
+    return this._view;
   }
 
   onUnmount() {
@@ -55,13 +61,16 @@ export class Mouse extends Composable {
 
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   private _handler = (_e: MouseEvent) => {};
+  private _view?: Record<string, unknown>;
 
   setup() {
+    if (this._view) return this._view;
     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 };
+    this._view = { x, y };
+    return this._view;
   }
 
   onUnmount() {
@@ -76,21 +85,35 @@ export class KeyCombo extends Composable {
   private _keydownHandler = (_e: KeyboardEvent) => {};
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   private _keyupHandler = () => {};
+  private _view?: Record<string, unknown>;
 
   constructor(private readonly combo: string) {
     super();
   }
 
   setup() {
-    const parts = this.combo.toLowerCase().split("+");
+    if (this._view) return this._view;
+    const parts = this.combo.toLowerCase().split("+").map((p) => p.trim());
     const pressed = signal(false);
 
+    const modifiers = ["ctrl", "shift", "alt", "meta"];
+    const key = parts.find((p) => !modifiers.includes(p));
+
+    // A combo with no non-modifier key is invalid and should never fire
+    if (!key) {
+      this._keyupHandler = () => { pressed.set(false); };
+      window.addEventListener("keydown", this._keydownHandler);
+      window.addEventListener("keyup", this._keyupHandler);
+      this._view = { pressed };
+      return this._view;
+    }
+
     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)) {
+      const meta = parts.includes("meta") ? e.metaKey : true;
+      if (ctrl && shift && alt && meta && e.key.toLowerCase() === key) {
         pressed.set(true);
       }
     };
@@ -98,7 +121,8 @@ export class KeyCombo extends Composable {
 
     window.addEventListener("keydown", this._keydownHandler);
     window.addEventListener("keyup", this._keyupHandler);
-    return { pressed };
+    this._view = { pressed };
+    return this._view;
   }
 
   onUnmount() {
@@ -112,12 +136,14 @@ export class Idle extends Composable {
 
   private _listeners: Array<[string, () => void]> = [];
   private _timer?: ReturnType<typeof setTimeout>;
+  private _view?: Record<string, unknown>;
 
   constructor(private readonly timeout = 60_000) {
     super();
   }
 
   setup() {
+    if (this._view) return this._view;
     const idle = signal(false);
     const reset = () => {
       idle.set(false);
@@ -131,7 +157,8 @@ export class Idle extends Composable {
     });
 
     reset();
-    return { idle };
+    this._view = { idle };
+    return this._view;
   }
 
   onUnmount() {

package/src/dom.ts

@@ -7,8 +7,10 @@ export class WindowSize extends Composable {
 
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   private _handler = () => {};
+  private _view?: Record<string, unknown>;
 
   setup() {
+    if (this._view) return this._view;
     const width = signal(window.innerWidth);
     const height = signal(window.innerHeight);
     this._handler = () => {
@@ -16,7 +18,8 @@ export class WindowSize extends Composable {
       height.set(window.innerHeight);
     };
     window.addEventListener("resize", this._handler);
-    return { width, height };
+    this._view = { width, height };
+    return this._view;
   }
 
   onUnmount() {
@@ -31,6 +34,7 @@ export class ScrollPosition extends Composable {
   private readonly _target: HTMLElement | Window;
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   private _handler = () => {};
+  private _view?: Record<string, unknown>;
 
   constructor(target: HTMLElement | Window = window) {
     super();
@@ -38,6 +42,7 @@ export class ScrollPosition extends Composable {
   }
 
   setup() {
+    if (this._view) return this._view;
     const x = signal(0);
     const y = signal(0);
     const t = this._target;
@@ -46,7 +51,8 @@ export class ScrollPosition extends Composable {
       y.set(t === window ? window.scrollY : (t as HTMLElement).scrollTop);
     };
     t.addEventListener("scroll", this._handler);
-    return { x, y };
+    this._view = { x, y };
+    return this._view;
   }
 
   onUnmount() {
@@ -59,12 +65,14 @@ export class ElementSize extends Composable {
   declare height: number;
 
   private _observer?: ResizeObserver;
+  private _view?: Record<string, unknown>;
 
   constructor(private readonly ref: { current: HTMLElement | null }) {
     super();
   }
 
   setup() {
+    if (this._view) return this._view;
     const width = signal(0);
     const height = signal(0);
     this._observer = new ResizeObserver(([entry]) => {
@@ -78,7 +86,8 @@ export class ElementSize extends Composable {
         height.set(this.ref.current.offsetHeight);
       }
     });
-    return { width, height };
+    this._view = { width, height };
+    return this._view;
   }
 
   onUnmount() {
@@ -90,6 +99,7 @@ export class Intersection extends Composable {
   declare visible: boolean;
 
   private _observer?: IntersectionObserver;
+  private _view?: Record<string, unknown>;
 
   constructor(
     private readonly ref: { current: HTMLElement | null },
@@ -99,6 +109,7 @@ export class Intersection extends Composable {
   }
 
   setup() {
+    if (this._view) return this._view;
     const visible = signal(false);
     this._observer = new IntersectionObserver(([entry]) => {
       visible.set(entry.isIntersecting);
@@ -106,7 +117,8 @@ export class Intersection extends Composable {
     effect(() => {
       if (this.ref.current) this._observer?.observe(this.ref.current);
     });
-    return { visible };
+    this._view = { visible };
+    return this._view;
   }
 
   onUnmount() {
@@ -117,11 +129,14 @@ export class Intersection extends Composable {
 export class Focus extends Composable {
   declare focused: boolean;
 
+  private _view?: Record<string, unknown>;
+
   constructor(private readonly ref: { current: HTMLElement | null }) {
     super();
   }
 
   setup() {
+    if (this._view) return this._view;
     const focused = signal(false);
     effect(() => {
       const el = this.ref.current;
@@ -135,6 +150,7 @@ export class Focus extends Composable {
         el.removeEventListener("blur", onBlur);
       };
     });
-    return { focused };
+    this._view = { focused };
+    return this._view;
   }
 }

package/src/utilities.ts

@@ -13,6 +13,8 @@ export class Clipboard extends Composable {
   declare content: string;
   declare copy: (text: string) => Promise<void>;
 
+  private _resetTimer?: ReturnType<typeof setTimeout>;
+
   constructor(private readonly resetDelay = 2000) {
     super();
   }
@@ -27,7 +29,8 @@ export class Clipboard extends Composable {
         await navigator.clipboard.writeText(text);
         content.set(text);
         copied.set(true);
-        setTimeout(() => { copied.set(false); }, resetDelay);
+        clearTimeout(this._resetTimer);
+        this._resetTimer = setTimeout(() => { copied.set(false); }, resetDelay);
       } catch {
         console.warn("[Clipboard] Falha ao copiar");
       }
@@ -35,6 +38,10 @@ export class Clipboard extends Composable {
 
     return { copied, content, copy };
   }
+
+  onUnmount() {
+    clearTimeout(this._resetTimer);
+  }
 }
 
 export class Geolocation extends Composable {
@@ -43,6 +50,8 @@ export class Geolocation extends Composable {
   declare error: GeolocationPositionError | null;
   declare loading: boolean;
 
+  private _active = true;
+
   constructor(private readonly options?: PositionOptions) {
     super();
   }
@@ -55,11 +64,13 @@ export class Geolocation extends Composable {
 
     navigator.geolocation.getCurrentPosition(
       (pos) => {
+        if (!this._active) return;
         lat.set(pos.coords.latitude);
         lng.set(pos.coords.longitude);
         loading.set(false);
       },
       (err) => {
+        if (!this._active) return;
         error.set(err);
         loading.set(false);
       },
@@ -68,6 +79,10 @@ export class Geolocation extends Composable {
 
     return { lat, lng, error, loading };
   }
+
+  onUnmount() {
+    this._active = false;
+  }
 }
 
 export class TimeAgo extends Composable {
@@ -127,6 +142,9 @@ export class Pagination extends Composable {
 
   constructor(private readonly options: PaginationOptions) {
     super();
+    if (options.pageSize <= 0) {
+      throw new Error("pageSize must be greater than 0");
+    }
   }
 
   setup() {