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

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/ClientProvider.test.tsx

@@ -2,14 +2,13 @@
 // 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 } from './ClientProvider';
 import { useClient } from './useClient';
@@ -97,6 +96,10 @@ describe('ClientProvider', () => {
     await client.halo.createIdentity({ displayName: 'test-user' });
   });
 
+  afterEach(() => {
+    cleanup();
+  });
+
   test('Renders with children', async () => {
     render(
       <ClientProvider client={client}>
@@ -148,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

@@ -2,12 +2,19 @@
 // Copyright 2020 DXOS.org
 //
 
-import React, { type FunctionComponent, type ReactNode, useEffect, useMemo, useState } from 'react';
+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 { registerSignalFactory } from '@dxos/echo-signals/react';
+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';
@@ -23,29 +30,30 @@ export type ClientProviderProps = Pick<ClientContextProps, 'status'> &
     children?: ReactNode;
 
     /**
-     * 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>>;
+    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.
      */
     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>[];
 
@@ -55,10 +63,16 @@ export type ClientProviderProps = Pick<ClientContextProps, 'status'> &
     fallback?: FunctionComponent<Partial<ClientContextProps>>;
 
     /**
-     * Set to false to stop default signal factory from being registered.
+     * 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.
      */
-    // TODO(burdon): Move to options.
-    registerSignalFactory?: boolean;
+    disableBanner?: boolean;
 
     /**
      * Post initialization hook to enable to caller to do custom initialization.
@@ -72,85 +86,111 @@ export type ClientProviderProps = Pick<ClientContextProps, 'status'> &
  * 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,
+      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 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');
+          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>;
-};
+    return <ClientContext.Provider value={{ client, status }}>{children}</ClientContext.Provider>;
+  },
+);

package/src/client/context.ts

@@ -4,17 +4,17 @@
 
 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/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>;
+};

package/src/testing/withClientProvider.stories.tsx

@@ -6,10 +6,11 @@ import '@dxos-theme';
 
 import React from 'react';
 
+import { log } from '@dxos/log';
 import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
 import { withLayout, withTheme } from '@dxos/storybook-utils';
 
-import { withClientProvider, withMultiClientProvider } from './withClientProvider';
+import { withClientProvider, type WithClientProviderProps, withMultiClientProvider } from './withClientProvider';
 import { useClient } from '../client';
 import { type Space, useSpaces } from '../echo';
 
@@ -37,20 +38,28 @@ const Test = () => {
 
 export default {
   title: 'react-client/withClientProvider',
-  component: Test,
-  decorators: [withTheme, withClientProvider({ createIdentity: true })],
+  render: Test,
 };
 
-export const Default = {};
+const clientProps: WithClientProviderProps = {
+  createIdentity: true,
+  createSpace: true,
+  onInitialized: async (client) => {
+    log.info('onInitialized', { client });
+  },
+  onSpaceCreated: async ({ client, space }) => {
+    log.info('onSpaceCreated', { client, space });
+  },
+};
+
+export const Default = {
+  decorators: [withClientProvider(clientProps), withTheme, withLayout({ classNames: ['flex gap-2'] })],
+};
 
 export const Multiple = {
   decorators: [
-    withMultiClientProvider({
-      numClients: 3,
-      createIdentity: true,
-      createSpace: true,
-    }),
-    withLayout({ classNames: ['flex gap-2'] }),
+    withMultiClientProvider({ ...clientProps, numClients: 3 }),
     withTheme,
+    withLayout({ classNames: ['flex gap-2'] }),
   ],
 };