@dxos/react-client 0.6.12 → 0.6.13-main.09887cd

package/src/client/ClientProvider.tsx

@@ -2,12 +2,18 @@
 // Copyright 2020 DXOS.org
 //
 
-import React, { type FunctionComponent, type ReactNode, useEffect, useMemo, useState } from 'react';
+import React, {
+  type FunctionComponent,
+  type PropsWithChildren,
+  forwardRef,
+  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 { registerSignalFactory } from '@dxos/echo-signals/react';
+import { registerSignalsRuntime } 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';
@@ -18,47 +24,47 @@ import { printBanner } from '../banner';
 /**
  * Properties for the ClientProvider.
  */
-export type ClientProviderProps = Pick<ClientContextProps, 'status'> &
-  Omit<ClientOptions, 'config' | 'services'> & {
-    children?: ReactNode;
-
+export type ClientProviderProps = Omit<ClientOptions, 'config' | 'services'> &
+  Pick<ClientContextProps, 'status'> &
+  PropsWithChildren<{
     /**
-     * Config object or async provider.
+     * Client object or async provider to enable to caller to do custom initialization.
+     *
+     * NOTE: For advanced use cases only.
      */
-    config?: Config | Provider<Promise<Config>>;
+    client?: Client | Provider<Promise<Client>>;
 
     /**
-     * Client object or async provider to enable to caller to do custom initialization.
+     * Config object or async provider.
      *
-     * Most apps won't need this.
+     * NOTE: If a `client` is provided then `config` is ignored.
      */
-    // TODO(wittjosiah): Remove async and just use to keep reference to client?
-    //   (Preferring `onInitialized` for custom initialization.)
-    // TODO(burdon): Use useImperativeHandle to expose client.
-    client?: Client | Provider<Promise<Client>>;
+    // TODO(burdon): Reconcile with ClientOptions.
+    config?: Config | Provider<Promise<Config>>;
 
     /**
      * Callback to enable the caller to create a custom ClientServicesProvider.
      *
-     * Most apps won't need this.
+     * NOTE: If a `client` is provided then `services` is ignored.
      */
+    // TODO(burdon): Reconcile with ClientOptions.
     services?: ClientServicesProvider | ((config?: Config) => MaybePromise<ClientServicesProvider>);
 
     /**
-     * List of schema to register.
+     * ReactNode to display until the client is available.
      */
-    types?: S.Schema<any>[];
+    fallback?: FunctionComponent<Partial<ClientContextProps>>;
 
     /**
-     * ReactNode to display until the client is available.
+     * Enable (by default) registration of Preact signals runtime for reactive ECHO objects.
+     * @see https://www.npmjs.com/package/@preact/signals-react
      */
-    fallback?: FunctionComponent<Partial<ClientContextProps>>;
+    signalsRuntime?: boolean;
 
     /**
-     * Set to false to stop default signal factory from being registered.
+     * Skip the DXOS banner.
      */
-    // TODO(burdon): Move to options.
-    registerSignalFactory?: boolean;
+    noBanner?: boolean;
 
     /**
      * Post initialization hook to enable to caller to do custom initialization.
@@ -66,91 +72,111 @@ export type ClientProviderProps = Pick<ClientContextProps, 'status'> &
      * @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 = ({
-  children,
-  config: configProvider,
-  client: clientProvider,
-  services: servicesProvider,
-  types,
-  status: controlledStatus,
-  fallback: Fallback = () => null,
-  registerSignalFactory: _registerSignalFactory = true,
-  onInitialized,
-  ...options
-}: ClientProviderProps) => {
-  useMemo(() => {
-    // TODO(wittjosiah): Ideally this should be imported asynchronously because it is optional.
-    //   Unfortunately, async import seemed to break signals React instrumentation.
-    _registerSignalFactory && registerSignalFactory();
-  }, []);
-
-  const [client, setClient] = useState(clientProvider instanceof Client ? clientProvider : undefined);
-
-  const [error, setError] = useState();
-  if (error) {
-    throw error;
-  }
-
-  // Status subscription.
-  const [status, setStatus] = useControlledValue(controlledStatus);
-  useEffect(() => {
-    if (!client) {
-      return;
+export const ClientProvider = forwardRef<Client | undefined, ClientProviderProps>(
+  (
+    {
+      children,
+      config: configProvider,
+      client: clientProvider,
+      services: servicesProvider,
+      status: controlledStatus,
+      fallback: Fallback = () => null,
+      signalsRuntime = true,
+      noBanner,
+      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.
+      signalsRuntime && registerSignalsRuntime();
+    }, []);
+
+    // 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 subscription = client.status.subscribe((status) => setStatus(status));
-    return () => subscription.unsubscribe();
-  }, [client, setStatus]);
-
-  // Initialize client.
-  useEffect(() => {
-    const done = async (client: Client) => {
-      await client.initialize().catch(setError);
-      log('client ready');
-      await onInitialized?.(client);
-      log('initialization complete');
-      if (types) {
-        client.addTypes(types);
-      }
+    const [client, setClient] = useState(clientProvider instanceof Client ? clientProvider : undefined);
 
-      setClient(client);
-      setStatus(client.status.get() ?? SystemStatus.ACTIVE);
-      printBanner(client);
-    };
-
-    const t = setTimeout(async () => {
-      if (clientProvider) {
-        // Asynchronously request client.
-        const client = await getAsyncProviderValue(clientProvider);
-        await done(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 });
-        const client = new Client({ config, services, ...options });
-        log('created client');
-        await done(client);
-      }
-    });
+    // Provide external access.
+    useImperativeHandle(forwardedRef, () => client, [client]);
 
-    return () => {
-      log('clean up');
-      clearTimeout(t);
-      void client?.destroy().catch((err) => log.catch(err));
-    };
-  }, [clientProvider, configProvider, servicesProvider]);
+    // Client status subscription.
+    const [status, setStatus] = useControlledValue(controlledStatus);
+    useEffect(() => {
+      if (!client) {
+        return;
+      }
 
-  if (!client || status !== SystemStatus.ACTIVE) {
-    return <Fallback client={client} status={status} />;
-  }
+      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');
+          await onInitialized?.(client);
+          log('initialization complete');
+        }
+
+        setClient(client);
+
+        if (!noBanner) {
+          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, noBanner]);
+
+    if (!client?.initialized || status !== SystemStatus.ACTIVE) {
+      return <Fallback client={client} status={status} />;
+    }
 
-  return <ClientContext.Provider value={{ client, status }}>{children}</ClientContext.Provider>;
-};
+    return <ClientContext.Provider value={{ client, status }}>{children}</ClientContext.Provider>;
+  },
+);

package/src/client/context.ts

@@ -4,17 +4,16 @@
 
 import { type Context, createContext } from 'react';
 
-import { type Client, type ClientServices, type SystemStatus } from '@dxos/client';
+import { type Client, type SystemStatus } from '@dxos/client';
 
 export type ClientContextProps = {
   client: Client;
-
-  // Optionally expose services (e.g., for devtools).
-  services?: ClientServices;
-
   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

@@ -4,12 +4,9 @@
 
 export * from './AgentHostingProvider';
 export * from './ClientProvider';
-
-// TODO(burdon): Remove.
 export * from './context';
 
 export * from './useClient';
-export * from './useClientServices';
 export * from './useClientStatus';
 export * from './useConfig';
 export * from './useShell';

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 './ClientProvider';
 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/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 = () => {};
 

package/src/echo/useSpaces.test.tsx

@@ -3,24 +3,22 @@
 //
 
 import { act, renderHook } from '@testing-library/react';
-import { expect } from 'chai';
-
-import { describe, test } from '@dxos/test';
+import { describe, expect, test } from 'vitest';
 
 import { useSpace, useSpaces } from './useSpaces';
-import { createClient, createContextProvider } from '../testing/util';
+import { createClient, createClientContextProvider } from '../testing/util';
 
 describe('useSpaces', () => {
   test('lists existing spaces', async () => {
     const { client } = await createClient({ createIdentity: true });
-    const wrapper = await createContextProvider(client);
+    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 } = await createClient({ createIdentity: true });
-    const wrapper = await createContextProvider(client);
+    const wrapper = await createClientContextProvider(client);
     const { result, rerender } = renderHook(() => useSpaces(), { wrapper });
     expect(result.current.length).to.eq(1);
     await act(async () => {
@@ -34,7 +32,7 @@ describe('useSpaces', () => {
 describe('useSpace', () => {
   test('gets default space', async () => {
     const { client } = await createClient();
-    const wrapper = await createContextProvider(client);
+    const wrapper = await createClientContextProvider(client);
     const { result, rerender } = renderHook(() => useSpace(), { wrapper });
     expect(result.current).to.be.undefined;
     await act(async () => {
@@ -47,7 +45,7 @@ describe('useSpace', () => {
 
   test('gets space by key', async () => {
     const { client, space } = await createClient({ createIdentity: true, createSpace: true });
-    const wrapper = await createContextProvider(client);
+    const wrapper = await createClientContextProvider(client);
     const { result } = renderHook(() => useSpace(space!.key), { wrapper });
     expect(result.current).to.not.be.undefined;
   });

package/src/halo/useDevices.test.tsx

@@ -3,17 +3,15 @@
 //
 
 import { renderHook } from '@testing-library/react';
-import { expect } from 'chai';
-
-import { describe, test } from '@dxos/test';
+import { describe, expect, test } from 'vitest';
 
 import { useDevices } from './useDevices';
-import { createClient, createContextProvider } from '../testing/util';
+import { createClient, createClientContextProvider } from '../testing/util';
 
 describe('useDevices', () => {
   test('lists existing devices', async () => {
     const { client } = await createClient({ createIdentity: true });
-    const wrapper = await createContextProvider(client);
+    const wrapper = await createClientContextProvider(client);
     const { result } = renderHook(() => useDevices(), { wrapper });
     expect(result.current?.length).to.eq(1);
   });

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,
+  },
+});

package/src/playwright/smoke.spec.ts

@@ -2,10 +2,9 @@
 // Copyright 2021 DXOS.org
 //
 
-import { type Page, test } from '@playwright/test';
-import { expect } from 'chai';
+import { type Page, expect, test } from '@playwright/test';
 
-import { setupPage } from '@dxos/test/playwright';
+import { setupPage } from '@dxos/test-utils/playwright';
 
 // TODO(wittjosiah): Factor out.
 // TODO(burdon): No hard-coding of ports; reconcile all DXOS tools ports.
@@ -15,17 +14,13 @@ test.describe('Smoke test', () => {
   let page: Page;
 
   test.beforeAll(async ({ browser }) => {
-    const result = await setupPage(browser, {
-      url: storybookUrl('react-client-withclientprovider--default'),
-      waitFor: (page) => page.isVisible(':has-text("initialized")'),
-    });
-
+    const result = await setupPage(browser, { url: storybookUrl('react-client-withclientprovider--default') });
     page = result.page;
+    await page.locator(':text("initialized")').waitFor({ state: 'visible' });
   });
 
   // NOTE: This test depends on connecting to the default production deployed HALO vault.
   test('Renders remote client info', async () => {
-    const isVisible = await page.isVisible(':has-text("initialized")');
-    expect(isVisible).to.be.true;
+    await expect(page.locator(':text("initialized")')).toBeVisible();
   });
 });

package/src/testing/ClientRepeater.tsx

@@ -2,37 +2,36 @@
 // Copyright 2022 DXOS.org
 //
 
+import { type Schema as S } from '@effect/schema';
 import React, { useState, type FC, useEffect, useRef } from 'react';
 
 import { Client, type PublicKey } from '@dxos/client';
-import { type Space } from '@dxos/client/echo';
 import { TestBuilder, performInvitation } from '@dxos/client/testing';
-import { type S } from '@dxos/echo-schema';
-import { registerSignalFactory } from '@dxos/echo-signals/react';
+import { registerSignalsRuntime } from '@dxos/echo-signals/react';
 import { faker } from '@dxos/random';
-import { type MaybePromise } from '@dxos/util';
 
+import { type WithClientProviderProps } from './withClientProvider';
 import { ClientProvider } from '../client';
 
 export type ClientRepeatedComponentProps = { id: number; count: number; spaceKey?: PublicKey };
 
+export type ClientRepeaterControlsProps = { clients: Client[] };
+
+// TODO(burdon): Reconcile with ClientProviderProps.
 export type ClientRepeaterProps<P extends ClientRepeatedComponentProps> = {
   className?: string;
   component: FC<ClientRepeatedComponentProps>;
-  controls?: FC<{ clients: Client[] }>;
-  clients?: Client[];
+  controls?: FC<ClientRepeaterControlsProps>;
   count?: number;
-  registerSignalFactory?: boolean;
+  clients?: Client[];
   types?: S.Schema<any>[];
-  createIdentity?: boolean;
-  createSpace?: boolean;
-  onCreateSpace?: (space: Space) => MaybePromise<void>;
   args?: Omit<P, 'id' | 'count'>;
-};
+} & Pick<WithClientProviderProps, 'createIdentity' | 'createSpace' | 'onSpaceCreated'>;
 
 /**
  * Utility component for Storybook stories which sets up clients for n peers.
  * The `Component` property is rendered n times, once for each peer.
+ * @deprecated use `withClientProvider`.
  */
 // TODO(burdon): To discuss: evolve ClientRepeater with optional decorator that uses it.
 // NOTE: This is specifically not a storybook decorator because it broke stories as a decorator.
@@ -47,11 +46,11 @@ export const ClientRepeater = <P extends ClientRepeatedComponentProps>(props: Cl
     types,
     createIdentity,
     createSpace,
-    onCreateSpace,
+    onSpaceCreated,
   } = props;
-  if (props.registerSignalFactory ?? true) {
-    registerSignalFactory();
-  }
+  useEffect(() => {
+    registerSignalsRuntime();
+  }, []);
 
   const [clients, setClients] = useState(props.clients ?? []);
   const [spaceKey, setSpaceKey] = useState<PublicKey>();
@@ -60,19 +59,19 @@ export const ClientRepeater = <P extends ClientRepeatedComponentProps>(props: Cl
   useEffect(() => {
     const timeout = setTimeout(async () => {
       const clients = [...Array(count)].map(
-        (_) => new Client({ services: testBuilder.current.createLocalClientServices() }),
+        (_) => new Client({ services: testBuilder.current.createLocalClientServices(), types }),
       );
-      await Promise.all(clients.map((client) => client.initialize()));
-      types && clients.map((client) => client.addTypes(types));
 
+      await Promise.all(clients.map((client) => client.initialize()));
       if (createIdentity || createSpace) {
         await Promise.all(clients.map((client) => client.halo.createIdentity()));
       }
 
       if (createSpace) {
-        const space = await clients[0].spaces.create({ name: faker.commerce.productName() });
+        const client = clients[0];
+        const space = await client.spaces.create({ name: faker.commerce.productName() });
         setSpaceKey(space.key);
-        await onCreateSpace?.(space);
+        await onSpaceCreated?.({ client, space });
         await Promise.all(
           clients.slice(1).flatMap((client) => performInvitation({ host: space, guest: client.spaces })),
         );

package/src/testing/util.tsx

@@ -4,16 +4,18 @@
 
 import React from 'react';
 
-import { Client, fromHost } from '@dxos/client';
+import { Client, type Config, fromHost } from '@dxos/client';
 import { type Space } from '@dxos/client/echo';
 
-import { ClientContext } from '../client';
+import { ClientContext, ClientProvider } from '../client';
 
+// TODO(burdon): Reconcile with initializeClient.
 export const createClient = async ({
+  config,
   createIdentity,
   createSpace,
-}: { createIdentity?: boolean; createSpace?: boolean } = {}) => {
-  const client = new Client({ services: fromHost() });
+}: { config?: Config; createIdentity?: boolean; createSpace?: boolean } = {}) => {
+  const client = new Client({ config, services: fromHost(config) });
   await client.initialize();
   if (createIdentity) {
     await client.halo.createIdentity();
@@ -28,7 +30,10 @@ export const createClient = async ({
   return { client, space };
 };
 
-// TODO(burdon): Change to ClientProvider.
-export const createContextProvider = async (client: Client) => {
+export const createClientContextProvider = async (client: Client) => {
   return ({ children }: any) => <ClientContext.Provider value={{ client }}>{children}</ClientContext.Provider>;
 };
+
+export const createClientProvider = async (client: Client) => {
+  return ({ children }: any) => <ClientProvider client={client}>{children}</ClientProvider>;
+};