@dxos/react-client 0.6.11-staging.e6894a4 → 0.6.12-main.5cc132e

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/useSpaceInvitations.ts

@@ -6,7 +6,7 @@ import { useMemo } from 'react';
 
 import { MulticastObservable } from '@dxos/async';
 import { type PublicKey } from '@dxos/client';
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useSpace } from './useSpaces';
 import { type CancellableInvitationObservable, useInvitationStatus } from '../invitations';

package/src/echo/useSpaces.test.tsx

@@ -3,38 +3,22 @@
 //
 
 import { act, renderHook } from '@testing-library/react';
-import { expect } from 'chai';
-import React from 'react';
-
-import { Client, fromHost } from '@dxos/client';
-import { describe, test } from '@dxos/test';
+import { describe, expect, test } from 'vitest';
 
 import { useSpace, useSpaces } from './useSpaces';
-import { ClientContext } from '../client';
+import { createClient, createClientContextProvider } from '../testing/util';
 
 describe('useSpaces', () => {
   test('lists existing spaces', async () => {
-    const client = new Client({ services: fromHost() });
-    await client.initialize();
-    await client.halo.createIdentity();
-    await client.spaces.isReady.wait();
-    // TODO(wittjosiah): Factor out.
-    const wrapper = ({ children }: any) => (
-      <ClientContext.Provider value={{ client }}>{children}</ClientContext.Provider>
-    );
+    const { client } = await createClient({ createIdentity: true });
+    const wrapper = await createClientContextProvider(client);
     const { result } = renderHook(() => useSpaces(), { wrapper });
     expect(result.current.length).to.eq(1);
   });
 
   test('updates when new spaces are created', async () => {
-    const client = new Client({ services: fromHost() });
-    await client.initialize();
-    await client.halo.createIdentity();
-    await client.spaces.isReady.wait();
-    // TODO(wittjosiah): Factor out.
-    const wrapper = ({ children }: any) => (
-      <ClientContext.Provider value={{ client }}>{children}</ClientContext.Provider>
-    );
+    const { client } = await createClient({ createIdentity: true });
+    const wrapper = await createClientContextProvider(client);
     const { result, rerender } = renderHook(() => useSpaces(), { wrapper });
     expect(result.current.length).to.eq(1);
     await act(async () => {
@@ -47,12 +31,8 @@ describe('useSpaces', () => {
 
 describe('useSpace', () => {
   test('gets default space', async () => {
-    const client = new Client({ services: fromHost() });
-    await client.initialize();
-    // TODO(wittjosiah): Factor out.
-    const wrapper = ({ children }: any) => (
-      <ClientContext.Provider value={{ client }}>{children}</ClientContext.Provider>
-    );
+    const { client } = await createClient();
+    const wrapper = await createClientContextProvider(client);
     const { result, rerender } = renderHook(() => useSpace(), { wrapper });
     expect(result.current).to.be.undefined;
     await act(async () => {
@@ -64,15 +44,9 @@ describe('useSpace', () => {
   });
 
   test('gets space by key', async () => {
-    const client = new Client({ services: fromHost() });
-    await client.initialize();
-    await client.halo.createIdentity();
-    const space = await client.spaces.create();
-    // TODO(wittjosiah): Factor out.
-    const wrapper = ({ children }: any) => (
-      <ClientContext.Provider value={{ client }}>{children}</ClientContext.Provider>
-    );
-    const { result } = renderHook(() => useSpace(space.key), { wrapper });
+    const { client, space } = await createClient({ createIdentity: true, createSpace: true });
+    const wrapper = await createClientContextProvider(client);
+    const { result } = renderHook(() => useSpace(space!.key), { wrapper });
     expect(result.current).to.not.be.undefined;
   });
 });

package/src/echo/useSpaces.ts

@@ -6,7 +6,7 @@ import { useEffect, useState } from 'react';
 
 import { type PublicKeyLike } from '@dxos/client';
 import { type Space, SpaceState } from '@dxos/client/echo';
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useClient } from '../client';
 

package/src/halo/useContacts.ts

@@ -3,7 +3,7 @@
 //
 
 import type { Contact } from '@dxos/client/halo';
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useClient } from '../client';
 

package/src/halo/useDevices.test.tsx

@@ -3,24 +3,15 @@
 //
 
 import { renderHook } from '@testing-library/react';
-import { expect } from 'chai';
-import React from 'react';
-
-import { Client, fromHost } from '@dxos/client';
-import { describe, test } from '@dxos/test';
+import { describe, expect, test } from 'vitest';
 
 import { useDevices } from './useDevices';
-import { ClientContext } from '../client';
+import { createClient, createClientContextProvider } from '../testing/util';
 
 describe('useDevices', () => {
   test('lists existing devices', async () => {
-    const client = new Client({ services: fromHost() });
-    await client.initialize();
-    await client.halo.createIdentity();
-    // TODO(wittjosiah): Factor out.
-    const wrapper = ({ children }: any) => (
-      <ClientContext.Provider value={{ client }}>{children}</ClientContext.Provider>
-    );
+    const { client } = await createClient({ createIdentity: true });
+    const wrapper = await createClientContextProvider(client);
     const { result } = renderHook(() => useDevices(), { wrapper });
     expect(result.current?.length).to.eq(1);
   });

package/src/halo/useDevices.ts

@@ -3,7 +3,7 @@
 //
 
 import type { Device } from '@dxos/client/halo';
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useClient } from '../client';
 

package/src/halo/useHaloInvitations.ts

@@ -4,7 +4,7 @@
 
 import { useMemo } from 'react';
 
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useClient } from '../client';
 import { useInvitationStatus, type CancellableInvitationObservable } from '../invitations';

package/src/halo/useIdentity.ts

@@ -3,7 +3,7 @@
 //
 
 import { type Identity } from '@dxos/client/halo';
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useClient } from '../client';
 

package/src/index.ts

@@ -3,6 +3,6 @@
 //
 
 export * from '@dxos/client';
-export { useMulticastObservable } from '@dxos/react-async';
+export { useMulticastObservable } from '@dxos/react-hooks';
 
 export * from './client';

package/src/mesh/useNetworkStatus.ts

@@ -3,7 +3,7 @@
 //
 
 import { type NetworkStatus } from '@dxos/client/mesh';
-import { useMulticastObservable } from '@dxos/react-async';
+import { useMulticastObservable } from '@dxos/react-hooks';
 
 import { useClient } from '../client';
 

package/src/playwright/playwright.config.ts

@@ -2,6 +2,17 @@
 // Copyright 2023 DXOS.org
 //
 
-import { defaultPlaywrightConfig } from '@dxos/test/playwright';
+import { nxE2EPreset } from '@nx/playwright/preset';
+import { defineConfig } from '@playwright/test';
 
-export default defaultPlaywrightConfig;
+import { e2ePreset } from '@dxos/test-utils/playwright';
+
+export default defineConfig({
+  ...nxE2EPreset(__filename, { testDir: __dirname }),
+  ...e2ePreset(__dirname),
+  webServer: {
+    command: 'pnpm -w nx storybook-e2e stories',
+    port: 9009,
+    reuseExistingServer: !process.env.CI,
+  },
+});