@dxos/react-client 0.6.11-staging.e6894a4 → 0.6.12-main.15a606f

package/package.json

@@ -1,65 +1,73 @@
 {
   "name": "@dxos/react-client",
-  "version": "0.6.11-staging.e6894a4",
+  "version": "0.6.12-main.15a606f",
   "description": "React client API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
   "author": "DXOS.org",
   "exports": {
-    ".": {
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": {
-        "default": "./dist/lib/node/index.cjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
-    },
     "./devtools": {
       "browser": "./dist/lib/browser/devtools/index.mjs",
       "node": {
-        "default": "./dist/lib/node/devtools/index.cjs"
+        "require": "./dist/lib/node/devtools/index.cjs",
+        "default": "./dist/lib/node-esm/devtools/index.mjs"
       },
       "types": "./dist/types/src/devtools/index.d.ts"
     },
     "./echo": {
       "browser": "./dist/lib/browser/echo/index.mjs",
       "node": {
-        "default": "./dist/lib/node/echo/index.cjs"
+        "require": "./dist/lib/node/echo/index.cjs",
+        "default": "./dist/lib/node-esm/echo/index.mjs"
       },
       "types": "./dist/types/src/echo/index.d.ts"
     },
     "./halo": {
       "browser": "./dist/lib/browser/halo/index.mjs",
       "node": {
-        "default": "./dist/lib/node/halo/index.cjs"
+        "require": "./dist/lib/node/halo/index.cjs",
+        "default": "./dist/lib/node-esm/halo/index.mjs"
       },
       "types": "./dist/types/src/halo/index.d.ts"
     },
+    ".": {
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": {
+        "require": "./dist/lib/node/index.cjs",
+        "default": "./dist/lib/node-esm/index.mjs"
+      },
+      "types": "./dist/types/src/index.d.ts"
+    },
     "./invitations": {
       "browser": "./dist/lib/browser/invitations/index.mjs",
       "node": {
-        "default": "./dist/lib/node/invitations/index.cjs"
+        "require": "./dist/lib/node/invitations/index.cjs",
+        "default": "./dist/lib/node-esm/invitations/index.mjs"
       },
       "types": "./dist/types/src/invitations/index.d.ts"
     },
     "./mesh": {
       "browser": "./dist/lib/browser/mesh/index.mjs",
       "node": {
-        "default": "./dist/lib/node/mesh/index.cjs"
+        "require": "./dist/lib/node/mesh/index.cjs",
+        "default": "./dist/lib/node-esm/mesh/index.mjs"
       },
       "types": "./dist/types/src/mesh/index.d.ts"
     },
     "./testing": {
       "browser": "./dist/lib/browser/testing/index.mjs",
       "node": {
-        "default": "./dist/lib/node/testing/index.cjs"
+        "require": "./dist/lib/node/testing/index.cjs",
+        "default": "./dist/lib/node-esm/testing/index.mjs"
       },
       "types": "./dist/types/src/testing/index.d.ts"
     },
     "./worker": {
       "browser": "./dist/lib/browser/worker.mjs",
       "node": {
-        "default": "./dist/lib/node/worker.cjs"
+        "require": "./dist/lib/node/worker.cjs",
+        "default": "./dist/lib/node-esm/worker.mjs"
       },
       "types": "./dist/types/src/worker.d.ts"
     }
@@ -91,18 +99,20 @@
     }
   },
   "dependencies": {
-    "@dxos/async": "0.6.11-staging.e6894a4",
-    "@dxos/codec-protobuf": "0.6.11-staging.e6894a4",
-    "@dxos/client": "0.6.11-staging.e6894a4",
-    "@dxos/config": "0.6.11-staging.e6894a4",
-    "@dxos/debug": "0.6.11-staging.e6894a4",
-    "@dxos/echo-signals": "0.6.11-staging.e6894a4",
-    "@dxos/invariant": "0.6.11-staging.e6894a4",
-    "@dxos/node-std": "0.6.11-staging.e6894a4",
-    "@dxos/echo-schema": "0.6.11-staging.e6894a4",
-    "@dxos/log": "0.6.11-staging.e6894a4",
-    "@dxos/react-async": "0.6.11-staging.e6894a4",
-    "@dxos/util": "0.6.11-staging.e6894a4"
+    "react-error-boundary": "^4.0.13",
+    "@dxos/client": "0.6.12-main.15a606f",
+    "@dxos/async": "0.6.12-main.15a606f",
+    "@dxos/config": "0.6.12-main.15a606f",
+    "@dxos/echo-signals": "0.6.12-main.15a606f",
+    "@dxos/debug": "0.6.12-main.15a606f",
+    "@dxos/echo-schema": "0.6.12-main.15a606f",
+    "@dxos/codec-protobuf": "0.6.12-main.15a606f",
+    "@dxos/log": "0.6.12-main.15a606f",
+    "@dxos/invariant": "0.6.12-main.15a606f",
+    "@dxos/protocols": "0.6.12-main.15a606f",
+    "@dxos/node-std": "0.6.12-main.15a606f",
+    "@dxos/react-hooks": "0.6.12-main.15a606f",
+    "@dxos/util": "0.6.12-main.15a606f"
   },
   "devDependencies": {
     "@testing-library/dom": "^8.17.1",
@@ -112,19 +122,21 @@
     "@types/react-dom": "~18.2.0",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "@dxos/random": "0.6.11-staging.e6894a4",
-    "@dxos/react-ui": "0.6.11-staging.e6894a4",
-    "@dxos/react-ui-theme": "0.6.11-staging.e6894a4",
-    "@dxos/storybook-utils": "0.6.11-staging.e6894a4"
+    "@dxos/react-ui": "0.6.12-main.15a606f",
+    "@dxos/random": "0.6.12-main.15a606f",
+    "@dxos/react-ui-syntax-highlighter": "0.6.12-main.15a606f",
+    "@dxos/react-ui-theme": "0.6.12-main.15a606f",
+    "@dxos/storybook-utils": "0.6.12-main.15a606f",
+    "@dxos/test-utils": "0.6.12-main.15a606f"
   },
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
-    "@dxos/react-ui": "0.6.11-staging.e6894a4",
-    "@dxos/react-ui-theme": "0.6.11-staging.e6894a4"
+    "react": "~18.2.0",
+    "react-dom": "~18.2.0",
+    "@dxos/react-ui": "0.6.12-main.15a606f",
+    "@dxos/react-ui-theme": "0.6.12-main.15a606f"
   },
   "optionalDependencies": {
-    "@dxos/random": "0.6.11-staging.e6894a4"
+    "@dxos/random": "0.6.12-main.15a606f"
   },
   "publishConfig": {
     "access": "public"

package/project.json

@@ -26,32 +26,12 @@
       "dependsOn": [
         "^compile",
         "stories:mkdist"
-      ],
-      "options": {
-        "playwrightConfigPath": "{projectRoot}/src/playwright/playwright.config.ts",
-        "serve": "stories:storybook-e2e",
-        "testPatterns": [
-          "{projectRoot}/src/playwright/**/*.spec.{ts,js}"
-        ],
-        "timeout": 60000,
-        "watchPatterns": [
-          "{projectRoot}/src/**/*"
-        ]
-      }
+      ]
     },
     "lint": {},
-    "test": {
-      "options": {
-        "ciEnvironments": [
-          "nodejs"
-        ],
-        "domRequired": true,
-        "forceExit": true
-      }
-    }
+    "test": {}
   },
   "implicitDependencies": [
-    "esbuild",
-    "test"
+    "esbuild"
   ]
 }

package/src/client/AgentHostingProvider.tsx

@@ -11,15 +11,16 @@ import { log } from '@dxos/log';
 
 import { useClient } from '../client';
 
-/*
- * Interface for invoking the agent hosting provider client.
- * @experimental
- */
-
 export type AgentHostingProviderProps = { config: Config; halo: Halo };
 
 export const AgentHostingContext = createContext<AgentHostingProviderClient | null>(null);
 
+/**
+ * Experimental agent hosting provider.
+ * @param props
+ * @constructor
+ * @deprecated
+ */
 export const AgentHostingProvider = (props: PropsWithChildren<{}>) => {
   const client = useClient();
   const [agentHostingProviderClient] = useState(makeClient(client));
@@ -52,7 +53,7 @@ const makeClient = ({ config, halo }: AgentHostingProviderProps) => {
       if (agentHostingProviderClient.init()) {
         return agentHostingProviderClient;
       } else {
-        // Not authorized or error initializing
+        // Not authorized or error initializing.
         return null;
       }
     }

package/src/client/{ClientContext.test.tsx → ClientProvider.test.tsx}

@@ -2,16 +2,16 @@
 // Copyright 2020 DXOS.org
 //
 
-import { renderHook, screen, render, act } from '@testing-library/react';
-import expect from 'expect';
+import { renderHook, screen, render, act, cleanup } from '@testing-library/react';
 import React, { Component, type PropsWithChildren } from 'react';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 
 import { waitForCondition } from '@dxos/async';
 import { Client, Config, SystemStatus, fromHost } from '@dxos/client';
 import { log } from '@dxos/log';
-import { describe, test } from '@dxos/test';
 
-import { ClientProvider, useClient } from './ClientContext';
+import { ClientProvider } from './ClientProvider';
+import { useClient } from './useClient';
 import { useIdentity } from '../halo';
 
 log.config({ filter: 'ClientContext:debug,warn' });
@@ -96,6 +96,10 @@ describe('ClientProvider', () => {
     await client.halo.createIdentity({ displayName: 'test-user' });
   });
 
+  afterEach(() => {
+    cleanup();
+  });
+
   test('Renders with children', async () => {
     render(
       <ClientProvider client={client}>
@@ -147,7 +151,7 @@ describe('ClientProvider', () => {
 
     await act(async () => {
       await waitForCondition({
-        condition: () => newClient.status.get() === SystemStatus.ACTIVE && !client.initialized,
+        condition: () => !client.initialized && newClient.status.get() === SystemStatus.ACTIVE,
       });
     });
     expect(client.initialized).toBe(false);

package/src/client/ClientProvider.tsx

@@ -0,0 +1,196 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import React, {
+  forwardRef,
+  type FunctionComponent,
+  type ReactNode,
+  useEffect,
+  useImperativeHandle,
+  useState,
+} from 'react';
+
+import { Client, type ClientOptions, type ClientServicesProvider, SystemStatus } from '@dxos/client';
+import { type Config } from '@dxos/config';
+import { type S } from '@dxos/echo-schema';
+import { registerSignalRuntime } from '@dxos/echo-signals/react';
+import { log } from '@dxos/log';
+import { useControlledValue } from '@dxos/react-hooks';
+import { getAsyncProviderValue, type MaybePromise, type Provider } from '@dxos/util';
+
+import { ClientContext, type ClientContextProps } from './context';
+import { printBanner } from '../banner';
+
+/**
+ * Properties for the ClientProvider.
+ */
+export type ClientProviderProps = Pick<ClientContextProps, 'status'> &
+  Omit<ClientOptions, 'config' | 'services'> & {
+    children?: ReactNode;
+
+    /**
+     * Client object or async provider to enable to caller to do custom initialization.
+     *
+     * NOTE: For advanced use cases only.
+     */
+    client?: Client | Provider<Promise<Client>>;
+
+    /**
+     * Config object or async provider.
+     *
+     * NOTE: If a `client` is provided then `config` is ignored.
+     */
+    config?: Config | Provider<Promise<Config>>;
+
+    /**
+     * Callback to enable the caller to create a custom ClientServicesProvider.
+     *
+     * NOTE: If a `client` is provided then `services` is ignored.
+     */
+    services?: ClientServicesProvider | ((config?: Config) => MaybePromise<ClientServicesProvider>);
+
+    /**
+     * List of schema to register.
+     *
+     * NOTE: If a `client` is provided then `types` will not be added until after the children are first rendered.
+     */
+    types?: S.Schema<any>[];
+
+    /**
+     * ReactNode to display until the client is available.
+     */
+    fallback?: FunctionComponent<Partial<ClientContextProps>>;
+
+    /**
+     * Set to false to stop default signal runtime from being registered.
+     *
+     * The signals runtime is used to provide reactive updates to ECHO objects.
+     */
+    registerSignalRuntime?: boolean;
+
+    /**
+     * Skip the DXOS banner print.
+     */
+    disableBanner?: boolean;
+
+    /**
+     * Post initialization hook to enable to caller to do custom initialization.
+     *
+     * @param Client
+     */
+    onInitialized?: (client: Client) => MaybePromise<void>;
+  };
+
+/**
+ * Root component that provides the DXOS client instance to child components.
+ * To be used with the `useClient` hook.
+ */
+export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps>(
+  (
+    {
+      children,
+      config: configProvider,
+      client: clientProvider,
+      services: servicesProvider,
+      types,
+      status: controlledStatus,
+      fallback: Fallback = () => null,
+      registerSignalRuntime: _registerSignalRuntime = true,
+      disableBanner,
+      onInitialized,
+      ...options
+    },
+    forwardedRef,
+  ) => {
+    useEffect(() => {
+      // TODO(wittjosiah): Ideally this should be imported asynchronously because it is optional.
+      //   Unfortunately, async import seemed to break signals React instrumentation.
+      _registerSignalRuntime && registerSignalRuntime();
+    }, [_registerSignalRuntime]);
+
+    // The client is initialized asynchronously.
+    // If an error occurs during initialization, it is caught and the state is set.
+    // This allows the error to be thrown in the render method.
+    // The assumption is that a client initialization error is fatal to the app.
+    // This error will be caught by the nearest error boundary.
+    const [error, setError] = useState();
+    if (error) {
+      throw error;
+    }
+
+    const [client, setClient] = useState(clientProvider instanceof Client ? clientProvider : undefined);
+
+    // Provide external access.
+    useImperativeHandle(forwardedRef, () => client, [client]);
+
+    // Client status subscription.
+    const [status, setStatus] = useControlledValue(controlledStatus);
+    useEffect(() => {
+      if (!client) {
+        return;
+      }
+
+      const subscription = client.status.subscribe((status) => setStatus(status));
+      return () => subscription.unsubscribe();
+    }, [client]);
+
+    // Create and/or initialize client.
+    useEffect(() => {
+      const initialize = async (client: Client) => {
+        if (!client.initialized) {
+          await client.initialize().catch(setError);
+          log('client ready');
+          if (types) {
+            client.addTypes(types);
+          }
+          await onInitialized?.(client);
+          log('initialization complete');
+        } else if (types) {
+          client.addTypes(types);
+        }
+
+        setClient(client);
+
+        if (!disableBanner) {
+          printBanner(client);
+        }
+      };
+
+      let client: Client;
+      const t = setTimeout(async () => {
+        if (clientProvider) {
+          // Asynchronously request client.
+          client = await getAsyncProviderValue(clientProvider);
+          await initialize(client);
+        } else {
+          // Asynchronously construct client (config may be undefined).
+          const config = await getAsyncProviderValue(configProvider);
+          log('resolved config', { config });
+          const services = await getAsyncProviderValue(servicesProvider, config);
+          log('created services', { services });
+          client = new Client({ config, services, ...options });
+          log('created client');
+          await initialize(client);
+        }
+      });
+
+      return () => {
+        log('clean up');
+        clearTimeout(t);
+        void client
+          ?.destroy()
+          .then(() => {
+            log('destroyed');
+          })
+          .catch((err) => log.catch(err));
+      };
+    }, [configProvider, clientProvider, servicesProvider, disableBanner]);
+
+    if (!client?.initialized || status !== SystemStatus.ACTIVE) {
+      return <Fallback client={client} status={status} />;
+    }
+
+    return <ClientContext.Provider value={{ client, status }}>{children}</ClientContext.Provider>;
+  },
+);

package/src/client/context.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import { type Context, createContext } from 'react';
+
+import { type Client, type SystemStatus } from '@dxos/client';
+
+export type ClientContextProps = {
+  client: Client;
+
+  status?: SystemStatus | null;
+};
+
+/**
+ * @internal Use ClientProvider to create or initialize the Client.
+ */
+export const ClientContext: Context<ClientContextProps | undefined> = createContext<ClientContextProps | undefined>(
+  undefined,
+);

package/src/client/index.ts

@@ -3,8 +3,11 @@
 //
 
 export * from './AgentHostingProvider';
-export * from './ClientContext';
-export * from './useClientServices';
+export * from './ClientProvider';
+export * from './context';
+
+export * from './useClient';
+export * from './useClientStatus';
 export * from './useConfig';
 export * from './useShell';
 export * from './useStatus';

package/src/client/useClient.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { ClientContext } from '../client/context';
+
+/**
+ * Hook returning instance of DXOS client.
+ * Requires ClientContext to be set via ClientProvider.
+ */
+export const useClient = () => {
+  const { client } = useContext(ClientContext) ?? raise(new Error('Missing ClientContext.'));
+  return client;
+};

package/src/client/useClientStatus.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { type Client, type SystemStatus } from '@dxos/client';
+
+export const useClientStatus = (client: Client) => {
+  const [status, setStatus] = useState<SystemStatus | null>();
+  useEffect(() => {
+    if (!client) {
+      return;
+    }
+
+    const subscription = client.status.subscribe((status) => setStatus(status));
+    return () => subscription.unsubscribe();
+  }, [client, setStatus]);
+
+  return status;
+};

package/src/client/useConfig.test.tsx

@@ -3,15 +3,13 @@
 //
 
 import { act, renderHook } from '@testing-library/react';
-import expect from 'expect';
-import React from 'react';
+import { describe, expect, test } from 'vitest';
 
 import { waitForCondition } from '@dxos/async';
-import { Client, Config, SystemStatus, fromHost } from '@dxos/client';
-import { describe, test } from '@dxos/test';
+import { Config, SystemStatus } from '@dxos/client';
 
-import { ClientProvider } from './ClientContext';
 import { useConfig } from './useConfig';
+import { createClient, createClientContextProvider } from '../testing/util';
 
 describe('Config hook', () => {
   const render = () => useConfig();
@@ -22,9 +20,8 @@ describe('Config hook', () => {
   });
 
   test('should return default client config when no config is passed in a context', async () => {
-    const client = new Client({ services: fromHost() });
-    await client.initialize();
-    const wrapper = ({ children }: any) => <ClientProvider client={client}>{children}</ClientProvider>;
+    const { client } = await createClient();
+    const wrapper = await createClientContextProvider(client);
     const { result } = renderHook(render, { wrapper });
     await act(async () => {
       await waitForCondition({ condition: () => client.status.get() === SystemStatus.ACTIVE });
@@ -43,9 +40,8 @@ describe('Config hook', () => {
         },
       },
     });
-    const client = new Client({ config, services: fromHost(config) });
-    await client.initialize();
-    const wrapper = ({ children }: any) => <ClientProvider client={client}>{children}</ClientProvider>;
+    const { client } = await createClient({ config });
+    const wrapper = await createClientContextProvider(client);
     const { result } = renderHook(render, { wrapper });
     await act(async () => {
       await waitForCondition({ condition: () => client.status.get() === SystemStatus.ACTIVE });

package/src/client/useConfig.ts

@@ -6,7 +6,7 @@ import { useContext } from 'react';
 
 import { raise } from '@dxos/debug';
 
-import { ClientContext } from './ClientContext';
+import { ClientContext } from './context';
 
 /**
  * Hook returning config object used to initialize the DXOS client instance.

package/src/client/useShell.ts

@@ -6,7 +6,7 @@ import { useEffect, useState } from 'react';
 
 import { type Shell, type ShellDisplay } from '@dxos/client';
 
-import { useClient } from './ClientContext';
+import { useClient } from './useClient';
 
 /**
  * Helper hook to access the shell.

package/src/client/useStatus.ts

@@ -7,7 +7,7 @@ import { useContext } from 'react';
 import { type SystemStatus } from '@dxos/client';
 import { raise } from '@dxos/debug';
 
-import { ClientContext } from './ClientContext';
+import { ClientContext } from './context';
 
 export const useStatus = (): SystemStatus | null | undefined => {
   const { status } = useContext(ClientContext) ?? raise(new Error('Missing ClientContext.'));

package/src/devtools/useDevtools.ts

@@ -2,16 +2,12 @@
 // Copyright 2022 DXOS.org
 //
 
-import { useContext } from 'react';
-
 import { type DevtoolsHost } from '@dxos/client/devtools';
 import { raise } from '@dxos/debug';
-import { invariant } from '@dxos/invariant';
 
-import { ClientContext } from '../client';
+import { useClient } from '../client';
 
 export const useDevtools = (): DevtoolsHost => {
-  const { services } = useContext(ClientContext) ?? raise(new Error('Missing ClientContext.'));
-  invariant(services);
-  return services.DevtoolsHost;
+  const client = useClient();
+  return client.services.services.DevtoolsHost ?? raise(new Error('DevtoolsHost not available.'));
 };

package/src/echo/useMembers.ts

@@ -5,7 +5,7 @@
 import { MulticastObservable } from '@dxos/async';
 import { type PublicKey } from '@dxos/client';
 import { HaloSpaceMember, type SpaceMember } from '@dxos/client/echo';
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useSpaces } from './useSpaces';
 

package/src/echo/useQuery.ts

@@ -5,6 +5,7 @@
 import { useMemo, useSyncExternalStore } from 'react';
 
 import {
+  Filter,
   isSpace,
   type Echo,
   type EchoReactiveObject,
@@ -41,18 +42,14 @@ export const useQuery = <T extends EchoReactiveObject<any>>(
       },
       getObjects: () => (subscribed && query ? query.objects : EMPTY_ARRAY),
     };
-  }, [spaceOrEcho, ...(typeof filter === 'function' ? [] : filterToDepsArray(filter)), ...(deps ?? [])]);
+  }, [spaceOrEcho, ...filterToDepsArray(filter), ...(deps ?? [])]);
 
   // https://beta.reactjs.org/reference/react/useSyncExternalStore
   // NOTE: This hook will resubscribe whenever the callback passed to the first argument changes -- make sure it is stable.
   return useSyncExternalStore<T[] | undefined>(subscribe, getObjects) ?? [];
 };
 
-// TODO(dmaretskyi): Serialize the filter here instead.
-const filterToDepsArray = (filter?: FilterSource<any>) =>
-  Object.entries(filter ?? {})
-    .flat(10)
-    .map((x) => (typeof x === 'function' || typeof x === 'object' ? null : x));
+const filterToDepsArray = (filter?: FilterSource<any>) => [JSON.stringify(Filter.from(filter).toProto())];
 
 const noop = () => {};