@peers-app/peers-ui 0.14.0 → 0.15.0

package/src/hooks.test.tsx

@@ -1,15 +1,16 @@
-import React from 'react';
-import { render, screen, act, waitFor } from '@testing-library/react';
-import { observable, Observable } from '@peers-app/peers-sdk';
-import { useObservable, useObservableState } from './hooks';
+import { type Observable, observable } from "@peers-app/peers-sdk";
+import { act, render, screen, waitFor } from "@testing-library/react";
+import { useObservable, useObservableState } from "./hooks";
 
 // Helper component to test useObservable
-function TestComponent<T>({ obs, testId = 'value' }: { obs: Observable<T> | T, testId?: string }) {
+function TestComponent<T>({ obs, testId = "value" }: { obs: Observable<T> | T; testId?: string }) {
   const [value, setValue] = useObservable(obs);
   return (
     <div>
       <span data-testid={testId}>{JSON.stringify(value)}</span>
-      <button data-testid="setter" onClick={() => setValue('new-value' as any)}>Set</button>
+      <button type="button" data-testid="setter" onClick={() => setValue("new-value" as T)}>
+        Set
+      </button>
     </div>
   );
 }
@@ -32,108 +33,110 @@ function ObservableStateTestComponent({ initialValue }: { initialValue: number }
   return (
     <div>
       <span data-testid="state-value">{value}</span>
-      <button data-testid="increment" onClick={() => obs(obs() + 1)}>Increment</button>
+      <button type="button" data-testid="increment" onClick={() => obs(obs() + 1)}>
+        Increment
+      </button>
     </div>
   );
 }
 
-describe('useObservable', () => {
-  describe('basic functionality', () => {
-    it('should return the current value of an observable', () => {
-      const obs = observable('hello');
+describe("useObservable", () => {
+  describe("basic functionality", () => {
+    it("should return the current value of an observable", () => {
+      const obs = observable("hello");
       render(<TestComponent obs={obs} />);
-      expect(screen.getByTestId('value')).toHaveTextContent('"hello"');
+      expect(screen.getByTestId("value")).toHaveTextContent('"hello"');
     });
 
-    it('should return the value when passed a plain value (non-observable)', () => {
+    it("should return the value when passed a plain value (non-observable)", () => {
       render(<TestComponent obs="plain-value" />);
-      expect(screen.getByTestId('value')).toHaveTextContent('"plain-value"');
+      expect(screen.getByTestId("value")).toHaveTextContent('"plain-value"');
     });
 
-    it('should re-render when observable value changes', async () => {
-      const obs = observable('initial');
+    it("should re-render when observable value changes", async () => {
+      const obs = observable("initial");
       render(<TestComponent obs={obs} />);
-      
-      expect(screen.getByTestId('value')).toHaveTextContent('"initial"');
-      
+
+      expect(screen.getByTestId("value")).toHaveTextContent('"initial"');
+
       act(() => {
-        obs('updated');
+        obs("updated");
       });
-      
+
       await waitFor(() => {
-        expect(screen.getByTestId('value')).toHaveTextContent('"updated"');
+        expect(screen.getByTestId("value")).toHaveTextContent('"updated"');
       });
     });
 
-    it('should update the observable when setter is called', async () => {
-      const obs = observable('initial');
+    it("should update the observable when setter is called", async () => {
+      const obs = observable("initial");
       render(<TestComponent obs={obs} />);
-      
+
       act(() => {
-        screen.getByTestId('setter').click();
+        screen.getByTestId("setter").click();
       });
-      
+
       await waitFor(() => {
-        expect(obs()).toBe('new-value');
-        expect(screen.getByTestId('value')).toHaveTextContent('"new-value"');
+        expect(obs()).toBe("new-value");
+        expect(screen.getByTestId("value")).toHaveTextContent('"new-value"');
       });
     });
 
-    it('should handle undefined values', () => {
+    it("should handle undefined values", () => {
       const obs = observable<string | undefined>(undefined);
       render(<TestComponent obs={obs} />);
       // undefined serializes to empty string in JSON.stringify, but actually shows as nothing
-      expect(screen.getByTestId('value')).toHaveTextContent('');
+      expect(screen.getByTestId("value")).toHaveTextContent("");
     });
 
-    it('should handle object values', async () => {
-      const obs = observable({ name: 'test', count: 5 });
+    it("should handle object values", async () => {
+      const obs = observable({ name: "test", count: 5 });
       render(<TestComponent obs={obs} />);
-      
-      expect(screen.getByTestId('value')).toHaveTextContent('{"name":"test","count":5}');
-      
+
+      expect(screen.getByTestId("value")).toHaveTextContent('{"name":"test","count":5}');
+
       act(() => {
-        obs({ name: 'updated', count: 10 });
+        obs({ name: "updated", count: 10 });
       });
-      
+
       await waitFor(() => {
-        expect(screen.getByTestId('value')).toHaveTextContent('{"name":"updated","count":10}');
+        expect(screen.getByTestId("value")).toHaveTextContent('{"name":"updated","count":10}');
       });
     });
   });
 
-  describe('array handling', () => {
-    it('should handle array values', () => {
-      const obs = observable(['a', 'b', 'c']);
+  describe("array handling", () => {
+    it("should handle array values", () => {
+      const obs = observable(["a", "b", "c"]);
       render(<ArrayTestComponent obs={obs} />);
-      
-      expect(screen.getByTestId('array-value')).toHaveTextContent('["a","b","c"]');
-      expect(screen.getByTestId('array-length')).toHaveTextContent('3');
+
+      expect(screen.getByTestId("array-value")).toHaveTextContent('["a","b","c"]');
+      expect(screen.getByTestId("array-length")).toHaveTextContent("3");
     });
 
-    it('should re-render when array is replaced with new reference', async () => {
-      const obs = observable(['a', 'b']);
+    it("should re-render when array is replaced with new reference", async () => {
+      const obs = observable(["a", "b"]);
       render(<ArrayTestComponent obs={obs} />);
-      
-      expect(screen.getByTestId('array-length')).toHaveTextContent('2');
-      
+
+      expect(screen.getByTestId("array-length")).toHaveTextContent("2");
+
       act(() => {
-        obs(['a', 'b', 'c']); // New array reference
+        obs(["a", "b", "c"]); // New array reference
       });
-      
+
       await waitFor(() => {
-        expect(screen.getByTestId('array-length')).toHaveTextContent('3');
+        expect(screen.getByTestId("array-length")).toHaveTextContent("3");
       });
     });
 
-    it('should NOT re-render when array is mutated in place (requires immutable updates)', async () => {
+    it("should NOT re-render when array is mutated in place (requires immutable updates)", async () => {
       // This tests the case where an array is mutated in place and notifySubscribers is called.
-      // 
+      //
       // IMPORTANT BEHAVIORAL NOTE:
-      // The OLD implementation (useState + useEffect) had special handling that would 
-      // spread the array when it detected same-reference mutation: 
+      // The OLD implementation (useState + useEffect) had special handling that would
+      // spread the array when it detected same-reference mutation:
       //   if (isArray(newData) && newData === data) setData([...newData])
-      // 
+      //
       // The NEW implementation (useSyncExternalStore) does NOT do this.
       // useSyncExternalStore uses Object.is() comparison on getSnapshot results.
       // If the reference is the same, React won't re-render.
@@ -141,132 +144,132 @@ describe('useObservable', () => {
       // This is actually the CORRECT behavior - it encourages immutable data patterns
       // which are required for React 18 concurrent rendering to work correctly.
       // Mutating data in place can cause tearing in concurrent mode.
-      
-      const obs = observable(['a', 'b']);
+
+      const obs = observable(["a", "b"]);
       render(<ArrayTestComponent obs={obs} />);
-      
-      expect(screen.getByTestId('array-length')).toHaveTextContent('2');
-      
+
+      expect(screen.getByTestId("array-length")).toHaveTextContent("2");
+
       act(() => {
         // Mutate the array in place (BAD PRACTICE - don't do this!)
         const arr = obs();
-        arr.push('c');
+        arr.push("c");
         obs.notifySubscribers();
       });
-      
+
       // The observable itself has the mutated value
-      expect(obs()).toEqual(['a', 'b', 'c']);
-      
+      expect(obs()).toEqual(["a", "b", "c"]);
+
       // But the component did NOT re-render because the reference didn't change
       // This is expected with useSyncExternalStore - it requires immutable updates
-      expect(screen.getByTestId('array-length')).toHaveTextContent('2');
+      expect(screen.getByTestId("array-length")).toHaveTextContent("2");
     });
 
-    it('should re-render when array is properly updated with spread', async () => {
+    it("should re-render when array is properly updated with spread", async () => {
       // This is the recommended pattern for updating arrays
-      const obs = observable(['a', 'b']);
+      const obs = observable(["a", "b"]);
       render(<ArrayTestComponent obs={obs} />);
-      
-      expect(screen.getByTestId('array-length')).toHaveTextContent('2');
-      
+
+      expect(screen.getByTestId("array-length")).toHaveTextContent("2");
+
       act(() => {
-        obs([...obs(), 'c']); // Proper immutable update
+        obs([...obs(), "c"]); // Proper immutable update
       });
-      
+
       await waitFor(() => {
-        expect(screen.getByTestId('array-length')).toHaveTextContent('3');
-        expect(screen.getByTestId('array-value')).toHaveTextContent('["a","b","c"]');
+        expect(screen.getByTestId("array-length")).toHaveTextContent("3");
+        expect(screen.getByTestId("array-value")).toHaveTextContent('["a","b","c"]');
       });
     });
   });
 
-  describe('subscription management', () => {
-    it('should unsubscribe when component unmounts', () => {
-      const obs = observable('test');
+  describe("subscription management", () => {
+    it("should unsubscribe when component unmounts", () => {
+      const obs = observable("test");
       const initialSubscriberCount = obs.subscriberCount();
-      
+
       const { unmount } = render(<TestComponent obs={obs} />);
-      
+
       // Should have subscribed
       expect(obs.subscriberCount()).toBeGreaterThan(initialSubscriberCount);
-      
+
       unmount();
-      
+
       // Should have unsubscribed
       expect(obs.subscriberCount()).toBe(initialSubscriberCount);
     });
 
-    it('should handle multiple components subscribing to same observable', async () => {
-      const obs = observable('shared');
-      
+    it("should handle multiple components subscribing to same observable", async () => {
+      const obs = observable("shared");
+
       render(
         <div>
           <TestComponent obs={obs} testId="value1" />
           <TestComponent obs={obs} testId="value2" />
-        </div>
+        </div>,
       );
-      
-      expect(screen.getByTestId('value1')).toHaveTextContent('"shared"');
-      expect(screen.getByTestId('value2')).toHaveTextContent('"shared"');
-      
+
+      expect(screen.getByTestId("value1")).toHaveTextContent('"shared"');
+      expect(screen.getByTestId("value2")).toHaveTextContent('"shared"');
+
       act(() => {
-        obs('updated');
+        obs("updated");
       });
-      
+
       await waitFor(() => {
-        expect(screen.getByTestId('value1')).toHaveTextContent('"updated"');
-        expect(screen.getByTestId('value2')).toHaveTextContent('"updated"');
+        expect(screen.getByTestId("value1")).toHaveTextContent('"updated"');
+        expect(screen.getByTestId("value2")).toHaveTextContent('"updated"');
       });
     });
   });
 
-  describe('rapid updates', () => {
-    it('should handle rapid sequential updates correctly', async () => {
+  describe("rapid updates", () => {
+    it("should handle rapid sequential updates correctly", async () => {
       const obs = observable(0);
-      
+
       function CounterComponent() {
         const [value] = useObservable(obs);
         return <span data-testid="counter">{value}</span>;
       }
-      
+
       render(<CounterComponent />);
-      
+
       act(() => {
         for (let i = 1; i <= 10; i++) {
           obs(i);
         }
       });
-      
+
       await waitFor(() => {
-        expect(screen.getByTestId('counter')).toHaveTextContent('10');
+        expect(screen.getByTestId("counter")).toHaveTextContent("10");
       });
     });
   });
 });
 
-describe('useObservableState', () => {
-  it('should create an observable with the initial value', () => {
+describe("useObservableState", () => {
+  it("should create an observable with the initial value", () => {
     render(<ObservableStateTestComponent initialValue={42} />);
-    expect(screen.getByTestId('state-value')).toHaveTextContent('42');
+    expect(screen.getByTestId("state-value")).toHaveTextContent("42");
   });
 
-  it('should re-render when the observable is updated', async () => {
+  it("should re-render when the observable is updated", async () => {
     render(<ObservableStateTestComponent initialValue={0} />);
-    
-    expect(screen.getByTestId('state-value')).toHaveTextContent('0');
-    
+
+    expect(screen.getByTestId("state-value")).toHaveTextContent("0");
+
     act(() => {
-      screen.getByTestId('increment').click();
+      screen.getByTestId("increment").click();
     });
-    
+
     await waitFor(() => {
-      expect(screen.getByTestId('state-value')).toHaveTextContent('1');
+      expect(screen.getByTestId("state-value")).toHaveTextContent("1");
     });
   });
 
-  it('should maintain the same observable instance across re-renders', async () => {
+  it("should maintain the same observable instance across re-renders", async () => {
     let capturedObs: Observable<number> | null = null;
-    
+
     function CaptureObsComponent() {
       const obs = useObservableState(0);
       if (!capturedObs) {
@@ -276,49 +279,53 @@ describe('useObservableState', () => {
       return (
         <div>
           <span data-testid="value">{value}</span>
-          <span data-testid="same-obs">{obs === capturedObs ? 'same' : 'different'}</span>
-          <button data-testid="update" onClick={() => obs(obs() + 1)}>Update</button>
+          <span data-testid="same-obs">{obs === capturedObs ? "same" : "different"}</span>
+          <button type="button" data-testid="update" onClick={() => obs(obs() + 1)}>
+            Update
+          </button>
         </div>
       );
     }
-    
+
     render(<CaptureObsComponent />);
-    
-    expect(screen.getByTestId('same-obs')).toHaveTextContent('same');
-    
+
+    expect(screen.getByTestId("same-obs")).toHaveTextContent("same");
+
     // Trigger a re-render by updating the observable
     act(() => {
-      screen.getByTestId('update').click();
+      screen.getByTestId("update").click();
     });
-    
+
     await waitFor(() => {
-      expect(screen.getByTestId('value')).toHaveTextContent('1');
-      expect(screen.getByTestId('same-obs')).toHaveTextContent('same');
+      expect(screen.getByTestId("value")).toHaveTextContent("1");
+      expect(screen.getByTestId("same-obs")).toHaveTextContent("same");
     });
   });
 
-  it('should not subscribe when doNotSubscribe is true', () => {
+  it("should not subscribe when doNotSubscribe is true", () => {
     function NoSubscribeComponent() {
       const obs = useObservableState(0, true); // doNotSubscribe = true
       return (
         <div>
           <span data-testid="value">{obs()}</span>
-          <button data-testid="update" onClick={() => obs(obs() + 1)}>Update</button>
+          <button type="button" data-testid="update" onClick={() => obs(obs() + 1)}>
+            Update
+          </button>
         </div>
       );
     }
-    
+
     render(<NoSubscribeComponent />);
-    
-    expect(screen.getByTestId('value')).toHaveTextContent('0');
-    
+
+    expect(screen.getByTestId("value")).toHaveTextContent("0");
+
     // Update won't cause re-render since we're not subscribed
     act(() => {
-      screen.getByTestId('update').click();
+      screen.getByTestId("update").click();
     });
-    
+
     // Value in DOM should still show 0 since component didn't re-render
     // But the observable itself has been updated
-    expect(screen.getByTestId('value')).toHaveTextContent('0');
+    expect(screen.getByTestId("value")).toHaveTextContent("0");
   });
 });

package/src/hooks.ts

@@ -1,8 +1,11 @@
-
-import { isSubscribable, observable, Observable, unwrapObservable } from "@peers-app/peers-sdk";
-import React, { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
-
-
+import {
+  isSubscribable,
+  type Observable,
+  observable,
+  unwrapObservable,
+} from "@peers-app/peers-sdk";
+import type React from "react";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
 
 /**
  * Use this to subscribe to an observable or computed in a functional component.
@@ -11,16 +14,22 @@ import React, { useCallback, useEffect, useState, useSyncExternalStore } from 'r
  * @param deps an array of dependencies that will cause re-subscription when changed
  * @returns the current value of the observable or computed and a function to set the value
  */
-export function useObservable<T>(sub: Observable<T> | T, deps: React.DependencyList = []): [T, (value: T) => void] {
+export function useObservable<T>(
+  sub: Observable<T> | T,
+  deps: React.DependencyList = [],
+): [T, (value: T) => void] {
   // Create memoized subscribe function that adapts Observable's subscribe API to useSyncExternalStore's expected signature
-  const subscribe = useCallback((onStoreChange: () => void) => {
-    if (!isSubscribable(sub)) {
-      // If not subscribable, return a no-op unsubscribe
-      return () => {};
-    }
-    const subscription = sub.subscribe(onStoreChange);
-    return () => subscription.dispose();
-  }, [sub, ...deps]);
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!isSubscribable(sub)) {
+        // If not subscribable, return a no-op unsubscribe
+        return () => {};
+      }
+      const subscription = sub.subscribe(onStoreChange);
+      return () => subscription.dispose();
+    },
+    [sub, ...deps],
+  );
 
   // getSnapshot returns the current value from the observable
   const getSnapshot = useCallback(() => {
@@ -31,11 +40,14 @@ export function useObservable<T>(sub: Observable<T> | T, deps: React.DependencyL
   const data = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 
   // Create setter that updates both local understanding and the observable
-  const setter = useCallback((newData: T) => {
-    if (isSubscribable(sub)) {
-      sub(newData);
-    }
-  }, [sub]);
+  const setter = useCallback(
+    (newData: T) => {
+      if (isSubscribable(sub)) {
+        sub(newData);
+      }
+    },
+    [sub],
+  );
 
   return [data, setter];
 }
@@ -47,23 +59,28 @@ export function useObservable<T>(sub: Observable<T> | T, deps: React.DependencyL
  * @param deps the dependencies to pass to useEffect which will trigger a re-render when any of the dependencies change
  * @returns the initial value and the resolved value of the promise
  */
-export function usePromise<T>(p: Promise<T> | (() => Promise<T>), initialValue?: T, deps: React.DependencyList = []): T | undefined {
+export function usePromise<T>(
+  p: Promise<T> | (() => Promise<T>),
+  initialValue?: T,
+  deps: React.DependencyList = [],
+): T | undefined {
   const [data, setData] = useState(initialValue);
+  // `deps` drives when the effect re-runs; callers include `p` when it changes. Omitting `p` avoids duplicate tracking with `[...deps]`.
   useEffect(() => {
     let disposed = false;
-    if (typeof p === 'function') {
+    if (typeof p === "function") {
       p = p();
     }
-    p.then(newData => {
+    p.then((newData) => {
       // if (!_.isEqual(newData, data) && !disposed) {
       if (!disposed) {
-        setData(newData)
+        setData(newData);
       }
-    })
-    return () => { 
-      disposed = true; 
-    }
-  }, deps);
+    });
+    return () => {
+      disposed = true;
+    };
+  }, [...deps]);
   return data;
 }
 
@@ -76,10 +93,16 @@ export function usePromise<T>(p: Promise<T> | (() => Promise<T>), initialValue?:
  * @returns
  */
 export function useObservableState<T>(initialValue: T, doNotSubscribe?: boolean): Observable<T>;
-export function useObservableState<T = undefined>(initialValue?: T, doNotSubscribe?: boolean): Observable<T | undefined>;
+export function useObservableState<T = undefined>(
+  initialValue?: T,
+  doNotSubscribe?: boolean,
+): Observable<T | undefined>;
 export function useObservableState<T>(initialValue?: T, doNotSubscribe?: boolean) {
-  const [obs] = useState(() => initialValue !== undefined ? observable<T>(initialValue) : observable<T | undefined>());
+  const [obs] = useState(() =>
+    initialValue !== undefined ? observable<T>(initialValue) : observable<T | undefined>(),
+  );
   if (!doNotSubscribe) {
+    // biome-ignore lint/correctness/useHookAtTopLevel: when doNotSubscribe, caller keeps a stable observable without React-driven subscription (see docstring).
     useObservable(obs);
   }
   return obs;
@@ -87,32 +110,41 @@ export function useObservableState<T>(initialValue?: T, doNotSubscribe?: boolean
 
 /**
  * Use this to register a handler for a knockout subscribable in a functional component.
- * The handler will be called immediately and whenever the subscribable changes. 
+ * The handler will be called immediately and whenever the subscribable changes.
  * @param subscribable The observable to subscribe to
  * @param onChange The function to call with the new value when the observable changes
-  */
-export function useSubscription<T>(subscribable: Observable<T>, onChange: (value: T) => any, doNotCallOnChangeDuringSetup?: boolean): void {
-  if (!doNotCallOnChangeDuringSetup) {
-    useEffect(() => onChange(subscribable()), []);
-  }
+ */
+export function useSubscription<T>(
+  subscribable: Observable<T>,
+  onChange: (value: T) => void,
+  doNotCallOnChangeDuringSetup?: boolean,
+): void {
   useEffect(() => {
+    if (!doNotCallOnChangeDuringSetup) {
+      onChange(subscribable());
+    }
     const subscription = subscribable.subscribe(() => onChange(subscribable()));
     return () => subscription.dispose();
-  }, [subscribable, onChange]);
+  }, [subscribable, onChange, doNotCallOnChangeDuringSetup]);
 }
 
-export function useOnScreen(ref: React.RefObject<any>) {
-  const [isIntersecting, setIntersecting] = useState(false)
-
-  const observer = new IntersectionObserver(
-    ([entry]) => setIntersecting(entry.isIntersecting)
-  )
+export function useOnScreen(ref: React.RefObject<Element | null>) {
+  const [isIntersecting, setIntersecting] = useState(false);
 
+  // Read ref.current once on mount (ref object identity is stable).
   useEffect(() => {
-    observer.observe(ref.current)
-    // Remove the observer as soon as the component is unmounted
-    return () => { observer.disconnect() }
-  }, [])
+    const element = ref.current;
+    if (!element) {
+      return;
+    }
+    const observer = new IntersectionObserver(([entry]) => {
+      setIntersecting(entry.isIntersecting);
+    });
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+    };
+  }, []);
 
-  return isIntersecting
+  return isIntersecting;
 }