@dxos/echo-react 0.9.1-main.c7dcc2e112 → 0.9.1-staging.ee54ba693a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo-react",
-  "version": "0.9.1-main.c7dcc2e112",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "React integration for ECHO.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -27,18 +27,18 @@
   "dependencies": {
     "@effect-atom/atom": "^0.5.3",
     "@effect-atom/atom-react": "^0.5.0",
-    "@dxos/echo": "0.9.1-main.c7dcc2e112"
+    "@dxos/echo": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
-    "@testing-library/react": "^16.3.0",
-    "@types/react": "~19.2.7",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
-    "@dxos/echo-client": "0.9.1-main.c7dcc2e112"
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/echo-client": "0.9.1-staging.ee54ba693a"
   },
   "peerDependencies": {
-    "react": "~19.2.3"
+    "react": "~19.2.7"
   },
   "publishConfig": {
     "access": "public"

package/src/useObject.ts

@@ -24,9 +24,16 @@ export const useObject: {
    * Hook to subscribe to a Ref's target object.
    * Automatically dereferences the ref and handles async loading.
    * Returns a snapshot (undefined if the ref hasn't loaded yet).
+   * Re-renders the component when the ref resolves or the target object changes.
    *
    * @param ref - The Ref to dereference and subscribe to
    * @returns The current target snapshot (or undefined if not loaded) and update callback
+   *
+   * @idiom org.dxos.echo-react.useObjectReactive
+   *   applies: Reading a ref's target (or a specific property) inside a React component — establishes a reactive subscription so the component re-renders when the ref resolves or the value changes
+   *   instead-of: `ref.target` — synchronous and not reactive; returns `undefined` when the target isn't loaded yet and never triggers a re-render when it becomes available
+   *   uses: {@link useObject}
+   *   related: org.dxos.echo.objAtomReactive, org.dxos.echo.refLoad
    */
   <T extends Obj.Unknown>(ref: Ref.Ref<T>): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
 
@@ -65,7 +72,7 @@ export const useObject: {
    * @param objOrRef - The Echo object or Ref to subscribe to
    * @returns The current object snapshot (or undefined) and update callback
    */
-  <T extends Obj.Unknown>(objOrRef: T | Ref.Ref<T>): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
+  <T extends Obj.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
 
   /**
    * Hook to subscribe to a specific property of an Echo object.
@@ -208,6 +215,10 @@ const useObjectProperty = <T extends Obj.Unknown, K extends keyof T>(
  * This hook is useful for aggregate computations like counts or filtering
  * across multiple refs without using .target directly.
  *
+ * @deprecated Subscribes the component to the whole list, re-rendering on any element's change. Prefer pushing
+ * the subscription down — derive the aggregate in an atom (reading each `Obj.atom(ref)`) and read it where it is
+ * needed, or subscribe to the individual ref/property closest to the consumer — to keep subscriptions granular.
+ *
  * @param refs - Array of Refs to dereference and subscribe to
  * @returns Array of loaded target snapshots (excludes unloaded refs)
  */

package/src/useType.ts

@@ -4,7 +4,7 @@
 
 import { useMemo, useSyncExternalStore } from 'react';
 
-import { DXN, EID, URI, type Database, Filter, Query, Scope, Type } from '@dxos/echo';
+import { type Database, DXN, EID, Filter, Query, Scope, Type, URI } from '@dxos/echo';
 
 /**
  * Subscribe to and retrieve a type by its URI from a space: a static schema's typename DXN, or a