@peers-app/peers-ui 0.26.6 → 0.27.0

package/dist/utils.js

@@ -7,18 +7,15 @@ exports.AsyncFunction = void 0;
 exports.htmlToText = htmlToText;
 exports.stripMentions = stripMentions;
 exports.trimAndSanitizeHtml = trimAndSanitizeHtml;
-exports.isObject = isObject;
-exports.js = js;
 exports.jsAsync = jsAsync;
-exports.toJSON = toJSON;
-exports.fromJSON = fromJSON;
 const dompurify_1 = __importDefault(require("dompurify"));
 const lodash_1 = __importDefault(require("lodash"));
+/** Plain text content of an HTML string (parsed with `DOMParser`, so browser-only). */
 function htmlToText(html) {
     const doc = new DOMParser().parseFromString(html, "text/html");
     return doc.body.textContent || "";
 }
-// Strip mention formatting and clean text for display
+/** Replaces `<@type:name:id>` / `<$type:name:id>` mentions with the readable name, underscores as spaces. */
 function stripMentions(text) {
     // Replace <type:name:id> with just the readable name part
     // Convert underscores to spaces for better readability
@@ -26,6 +23,7 @@ function stripMentions(text) {
         return name.replace(/_/g, " ");
     });
 }
+/** Sanitizes HTML with DOMPurify, collapses repeated blank paragraphs, and drops a trailing one. */
 function trimAndSanitizeHtml(value) {
     let sanitizedValue = dompurify_1.default.sanitize(value);
     // removes empty paragraphs
@@ -42,31 +40,15 @@ function trimAndSanitizeHtml(value) {
     }
     return sanitizedValue;
 }
-function isObject(x) {
-    return lodash_1.default.isObject(x) && !lodash_1.default.isArray(x) && !lodash_1.default.isDate(x) && x !== null;
-}
-function js(jsCode, externalReferences) {
-    const hideGlobals = [
-        "process",
-        "global", //,'setTimeout','setInterval','setImmediate','clearImmediate','clearInterval','clearTimeout'
-    ];
-    const common = module.exports;
-    const refNames = ["console", "common"];
-    const refValues = [console, common];
-    lodash_1.default.keys(externalReferences).forEach((key) => {
-        refNames.push(key);
-        refValues.push(externalReferences[key]);
-    });
-    const compiledJs = Function.apply(null, [
-        ...refNames,
-        ...hideGlobals,
-        `"use strict";  ${jsCode.trim()}`,
-    ]);
-    return compiledJs.apply(null, refValues);
-}
 // must be done this way so TypeScript doesn't rewrite async keyword
 // export const AsyncFunction = eval('Object.getPrototypeOf(async function () { }).constructor');
+/** The `AsyncFunction` constructor, for compiling async code from a string. */
 exports.AsyncFunction = Object.getPrototypeOf(async () => { }).constructor;
+/**
+ * Compiles and runs `jsCode` as the body of a strict async function. `utils`, `Promise`,
+ * `console` and each key of `externalReferences` are in scope; `process` and `global` are hidden.
+ * Runs arbitrary code: never pass it untrusted input.
+ */
 function jsAsync(jsCode, externalReferences = {}) {
     jsCode = String(jsCode).trim();
     const hideGlobals = [
@@ -87,153 +69,6 @@ function jsAsync(jsCode, externalReferences = {}) {
     ]);
     return compiledJs.apply(null, refValues);
 }
-function toJSON(obj) {
-    //console.log('toJSON');
-    const knownObjs = [];
-    const objRefs = [];
-    const newObjs = [];
-    let refCount = 0;
-    function recurse(obj) {
-        // stringify values
-        if (Number.isNaN(obj))
-            return "NaN";
-        if (obj === undefined)
-            return "undefined";
-        if (obj === Infinity)
-            return "Infinity";
-        if (obj instanceof RegExp)
-            return `__REGEXP ${obj.toString()}`;
-        //   if(isDate(obj))
-        //       return "__DATE " + obj.toISOString();
-        if (lodash_1.default.isDate(obj))
-            return obj.toISOString();
-        if (lodash_1.default.isFunction(obj))
-            return `__FUNCTION ${obj.toString()}`;
-        if (lodash_1.default.isElement(obj)) {
-            return `__HTML ${obj.outerHTML}`;
-        }
-        if (typeof window !== "undefined" && window && obj === window) {
-            return "__WINDOW";
-        }
-        if (lodash_1.default.isError(obj)) {
-            return `__ERROR ${obj.stack}`;
-        }
-        // non-objects can just be returned at this point
-        if (!(isObject(obj) || lodash_1.default.isArray(obj))) {
-            return obj;
-        }
-        // if we've found a duplicate reference, deal with it
-        var iObj = knownObjs.indexOf(obj);
-        if (iObj >= 0) {
-            var ref = objRefs[iObj];
-            var nObj = newObjs[iObj];
-            if (lodash_1.default.isArray(nObj) && (!lodash_1.default.isString(nObj[0]) || !nObj[0].match(/^__this_ref:/)))
-                nObj.unshift(`__this_ref:${ref}`);
-            else if (isObject(nObj) && !nObj.__this_ref)
-                nObj.__this_ref = ref;
-            return ref;
-        }
-        // capture references in case we need them later
-        refCount++;
-        var newRef = `__duplicate_ref_${lodash_1.default.isArray(obj) ? "ary_" : "obj_"}${refCount}`;
-        var outObj = lodash_1.default.isArray(obj) ? [] : {};
-        knownObjs.push(obj);
-        objRefs.push(newRef);
-        newObjs.push(outObj);
-        // recurse on properties
-        if (lodash_1.default.isArray(obj))
-            for (var i = 0; i < obj.length; i++)
-                outObj.push(recurse(obj[i])); // use push so offset from reference capture doesn't mess things up
-        else
-            for (var key in obj) {
-                if (!Object.hasOwn(obj, key))
-                    continue;
-                var value = recurse(obj[key]);
-                if (key[0] === "$")
-                    // escape leading dollar signs
-                    key = `__DOLLAR_${key.substr(1)}`;
-                outObj[key] = value;
-            }
-        return outObj;
-    }
-    obj = recurse(obj);
-    return obj;
-}
-function fromJSON(obj, externalReferences) {
-    //console.log('fromJSON');
-    var dup_refs = {};
-    function recurse(obj) {
-        if (lodash_1.default.isString(obj)) {
-            // restore values
-            if (obj === "undefined")
-                return undefined;
-            if (obj === "NaN")
-                return NaN;
-            if (obj === "Infinity")
-                return Infinity;
-            if (obj.match(/^__REGEXP /)) {
-                var m = obj.split("__REGEXP ")[1].match(/\/(.*)\/(.*)?/);
-                return new RegExp(m[1], m[2] || "");
-            }
-            if (obj.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/)) {
-                return new Date(obj);
-            }
-            if (obj.match(/^__FUNCTION /)) {
-                return js(obj.substring(11), externalReferences);
-            }
-            if (obj.match(/^__HTML /)) {
-                //@ts-expect-error
-                if (typeof $ !== "undefined")
-                    return $(obj.substring(7))[0];
-                else
-                    return obj;
-            }
-            if (obj.startsWith("__ERROR ")) {
-                const error = new Error();
-                error.stack = obj.substring(8);
-                return error;
-            }
-            if (obj === "__WINDOW") {
-                return window;
-            }
-            // deal with duplicate refs
-            if (obj.match(/^__duplicate_ref_/)) {
-                if (!dup_refs[obj])
-                    dup_refs[obj] = obj.match(/_obj_/) ? {} : [];
-                return dup_refs[obj];
-            }
-        }
-        if (!(isObject(obj) || lodash_1.default.isArray(obj)))
-            return obj;
-        // deal with objects that have duplicate refs
-        var dup_ref = null;
-        obj = lodash_1.default.clone(obj); // don't mess up the original JSON object
-        if (lodash_1.default.isArray(obj) && lodash_1.default.isString(obj[0]) && obj[0].match(/^__this_ref:/))
-            dup_ref = obj.shift().split(":")[1];
-        else if (obj.__this_ref) {
-            dup_ref = obj.__this_ref;
-            delete obj.__this_ref;
-        }
-        var mObj = lodash_1.default.isArray(obj) ? [] : {};
-        if (dup_ref)
-            if (!dup_refs[dup_ref])
-                dup_refs[dup_ref] = mObj;
-            else
-                mObj = dup_refs[dup_ref];
-        // restore keys and recurse on objects
-        for (var key in obj) {
-            if (!Object.hasOwn(obj, key))
-                continue;
-            var value = recurse(obj[key]);
-            if (key.match(/^__DOLLAR_/))
-                key = `$${key.substr(9)}`;
-            mObj[key] = value;
-        }
-        return mObj;
-    }
-    obj = recurse(obj);
-    return obj;
-}
 // export type IObjectMatch<T> = {
 //   [key in keyof T]?: RegExp | string | number | boolean
 // }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-ui",
-  "version": "0.26.6",
+  "version": "0.27.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-ui.git"
@@ -30,7 +30,7 @@
     "lint:fix": "biome check --write ."
   },
   "peerDependencies": {
-    "@peers-app/peers-sdk": "^0.26.6",
+    "@peers-app/peers-sdk": "^0.27.0",
     "bootstrap": "^5.3.3",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
@@ -41,7 +41,7 @@
     "@babel/preset-react": "^7.24.1",
     "@babel/preset-typescript": "^7.27.1",
     "@biomejs/biome": "2.3.11",
-    "@peers-app/peers-sdk": "0.26.6",
+    "@peers-app/peers-sdk": "0.27.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+// `use-host-contract` stays internal: its screens import it by path.
+export * from "./use-observable";
+export * from "./use-observable-state";
+export * from "./use-on-screen";
+export * from "./use-promise";
+export * from "./use-rows";
+export * from "./use-subscription";
+export * from "./use-tool";

package/src/hooks/use-observable-state.test.tsx

@@ -0,0 +1,101 @@
+import type { Observable } from "@peers-app/peers-sdk";
+import { act, render, screen, waitFor } from "@testing-library/react";
+import { useObservable } from "./use-observable";
+import { useObservableState } from "./use-observable-state";
+
+// Helper component to test useObservableState
+function ObservableStateTestComponent({ initialValue }: { initialValue: number }) {
+  const obs = useObservableState(initialValue);
+  const [value] = useObservable(obs);
+  return (
+    <div>
+      <span data-testid="state-value">{value}</span>
+      <button type="button" data-testid="increment" onClick={() => obs(obs() + 1)}>
+        Increment
+      </button>
+    </div>
+  );
+}
+
+describe("useObservableState", () => {
+  it("should create an observable with the initial value", () => {
+    render(<ObservableStateTestComponent initialValue={42} />);
+    expect(screen.getByTestId("state-value")).toHaveTextContent("42");
+  });
+
+  it("should re-render when the observable is updated", async () => {
+    render(<ObservableStateTestComponent initialValue={0} />);
+
+    expect(screen.getByTestId("state-value")).toHaveTextContent("0");
+
+    act(() => {
+      screen.getByTestId("increment").click();
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("state-value")).toHaveTextContent("1");
+    });
+  });
+
+  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) {
+        capturedObs = obs;
+      }
+      const [value] = useObservable(obs);
+      return (
+        <div>
+          <span data-testid="value">{value}</span>
+          <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");
+
+    // Trigger a re-render by updating the observable
+    act(() => {
+      screen.getByTestId("update").click();
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("value")).toHaveTextContent("1");
+      expect(screen.getByTestId("same-obs")).toHaveTextContent("same");
+    });
+  });
+
+  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 type="button" data-testid="update" onClick={() => obs(obs() + 1)}>
+            Update
+          </button>
+        </div>
+      );
+    }
+
+    render(<NoSubscribeComponent />);
+
+    expect(screen.getByTestId("value")).toHaveTextContent("0");
+
+    // Update won't cause re-render since we're not subscribed
+    act(() => {
+      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");
+  });
+});

package/src/hooks/use-observable-state.ts

@@ -0,0 +1,29 @@
+import { type Observable, observable } from "@peers-app/peers-sdk";
+import { useState } from "react";
+import { useObservable } from "./use-observable";
+
+/**
+ * Use this to create an observable in a functional component.
+ * This automatically subscribes to the observable and triggers a re-render when the value changes.
+ * @param initialValue This will be the initial value of the observable
+ * @param doNotSubscribe If true, the observable will not be subscribed to automatically.
+ * This is useful if you want to create an observable that persists between rerenders but doesn't cause rerenders itself.
+ * @returns The same observable on every render.
+ */
+export function useObservableState<T>(initialValue: T, doNotSubscribe?: boolean): Observable<T>;
+/** Create an observable that may start undefined and subscribe unless `doNotSubscribe` is true. */
+export function useObservableState<T = undefined>(
+  initialValue?: T,
+  doNotSubscribe?: boolean,
+): Observable<T | undefined>;
+/** Create and optionally subscribe to a component-owned observable. */
+export function useObservableState<T>(initialValue?: T, doNotSubscribe?: boolean) {
+  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;
+}

package/src/{hooks.test.tsx → hooks/use-observable.test.tsx}

@@ -1,6 +1,11 @@
-import { type Observable, observable } from "@peers-app/peers-sdk";
-import { act, render, screen, waitFor } from "@testing-library/react";
-import { useObservable, useObservableState } from "./hooks";
+import {
+  isSubscribable,
+  type Observable,
+  observable,
+  type ReadonlyObservable,
+} from "@peers-app/peers-sdk";
+import { act, render, renderHook, screen, waitFor } from "@testing-library/react";
+import { useObservable } from "./use-observable";
 
 // Helper component to test useObservable
 function TestComponent<T>({ obs, testId = "value" }: { obs: Observable<T> | T; testId?: string }) {
@@ -26,21 +31,26 @@ function ArrayTestComponent({ obs }: { obs: Observable<string[]> }) {
   );
 }
 
-// Helper component to test useObservableState
-function ObservableStateTestComponent({ initialValue }: { initialValue: number }) {
-  const obs = useObservableState(initialValue);
-  const [value] = useObservable(obs);
-  return (
-    <div>
-      <span data-testid="state-value">{value}</span>
-      <button type="button" data-testid="increment" onClick={() => obs(obs() + 1)}>
-        Increment
-      </button>
-    </div>
-  );
-}
-
 describe("useObservable", () => {
+  it("reads and follows a read-only observable without allowing typed writes", () => {
+    const source = observable(1);
+    const view: ReadonlyObservable<number> = source;
+    const { result } = renderHook(() => useObservable(view));
+    const checkReadonly = () => {
+      // @ts-expect-error the read-only hook's setter accepts no values
+      result.current[1](2);
+      if (isSubscribable(view)) {
+        // @ts-expect-error testing subscribability must not make a read-only view writable
+        view(2);
+      }
+    };
+    void checkReadonly;
+    const initial: number = result.current[0];
+    expect(initial).toBe(1);
+    act(() => source(3));
+    expect(result.current[0]).toBe(3);
+  });
+
   describe("basic functionality", () => {
     it("should return the current value of an observable", () => {
       const obs = observable("hello");
@@ -246,86 +256,3 @@ describe("useObservable", () => {
     });
   });
 });
-
-describe("useObservableState", () => {
-  it("should create an observable with the initial value", () => {
-    render(<ObservableStateTestComponent initialValue={42} />);
-    expect(screen.getByTestId("state-value")).toHaveTextContent("42");
-  });
-
-  it("should re-render when the observable is updated", async () => {
-    render(<ObservableStateTestComponent initialValue={0} />);
-
-    expect(screen.getByTestId("state-value")).toHaveTextContent("0");
-
-    act(() => {
-      screen.getByTestId("increment").click();
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId("state-value")).toHaveTextContent("1");
-    });
-  });
-
-  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) {
-        capturedObs = obs;
-      }
-      const [value] = useObservable(obs);
-      return (
-        <div>
-          <span data-testid="value">{value}</span>
-          <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");
-
-    // Trigger a re-render by updating the observable
-    act(() => {
-      screen.getByTestId("update").click();
-    });
-
-    await waitFor(() => {
-      expect(screen.getByTestId("value")).toHaveTextContent("1");
-      expect(screen.getByTestId("same-obs")).toHaveTextContent("same");
-    });
-  });
-
-  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 type="button" data-testid="update" onClick={() => obs(obs() + 1)}>
-            Update
-          </button>
-        </div>
-      );
-    }
-
-    render(<NoSubscribeComponent />);
-
-    expect(screen.getByTestId("value")).toHaveTextContent("0");
-
-    // Update won't cause re-render since we're not subscribed
-    act(() => {
-      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");
-  });
-});

package/src/hooks/use-observable.ts

@@ -0,0 +1,67 @@
+import {
+  isSubscribable,
+  type Observable,
+  type ReadonlyObservable,
+  unwrapObservable,
+} from "@peers-app/peers-sdk";
+import type React from "react";
+import { useCallback, useSyncExternalStore } from "react";
+
+/** Read and subscribe to a writable observable, with a setter for its value. */
+export function useObservable<T>(
+  sub: Observable<T>,
+  deps?: React.DependencyList,
+): [T, (value: T) => void];
+/** Read and subscribe to a read-only observable; its setter accepts no values. */
+export function useObservable<T>(
+  sub: ReadonlyObservable<T>,
+  deps?: React.DependencyList,
+): [T, (value: never) => void];
+/** Read a plain value or a writable observable, retaining the existing optional-observable API. */
+export function useObservable<T>(
+  sub: Observable<T> | T,
+  deps?: React.DependencyList,
+): [T, (value: T) => void];
+/**
+ * Subscribe to an observable or computed in a functional component, using useSyncExternalStore
+ * for React 18 concurrent rendering. Only writable observables have a callable typed setter.
+ * @param sub the observable, computed, or plain value to read
+ * @param deps dependencies that cause re-subscription when changed
+ */
+export function useObservable<T>(
+  sub: ReadonlyObservable<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],
+  );
+
+  // getSnapshot returns the current value from the observable
+  const getSnapshot = useCallback(() => {
+    return unwrapObservable(sub);
+  }, [sub, ...deps]);
+
+  // Use useSyncExternalStore for concurrent-safe subscription
+  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],
+  );
+
+  return [data, setter];
+}

package/src/hooks/use-on-screen.ts

@@ -0,0 +1,24 @@
+import type React from "react";
+import { useEffect, useState } from "react";
+
+/** Track whether the referenced element intersects the viewport. */
+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(() => {
+    const element = ref.current;
+    if (!element) {
+      return;
+    }
+    const observer = new IntersectionObserver(([entry]) => {
+      setIntersecting(entry.isIntersecting);
+    });
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+    };
+  }, []);
+
+  return isIntersecting;
+}

package/src/hooks/use-promise.ts

@@ -0,0 +1,34 @@
+import type React from "react";
+import { useEffect, useState } from "react";
+
+/**
+ * Use this to easily wait for a promise in a functional component.
+ * @param p The promise to wait for
+ * @param initialValue the initial value to return before the promise resolves
+ * @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 {
+  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") {
+      p = p();
+    }
+    p.then((newData) => {
+      // if (!_.isEqual(newData, data) && !disposed) {
+      if (!disposed) {
+        setData(newData);
+      }
+    });
+    return () => {
+      disposed = true;
+    };
+  }, [...deps]);
+  return data;
+}