jazz-tools 0.19.8 → 0.19.11

package/src/inspector/ui/modal.tsx

@@ -15,14 +15,15 @@ interface ModalProps {
   onCancel?: () => void;
   showButtons?: boolean;
   className?: string;
+  wide?: boolean;
 }
 
-const ModalContent = styled("dialog")`
+const ModalContent = styled("dialog")<{ wide?: boolean }>`
   background-color: var(--j-background);
   border-radius: var(--j-radius-lg);
   box-shadow: 0 10px 25px rgba(0, 0, 0, 0.2);
   border: 1px solid var(--j-border-color);
-  max-width: 32rem;
+  ${(props) => (props.wide ? "max-width: 60vw;" : "max-width: 32rem;")}
   margin-block: auto;
   margin-inline: auto;
   &::backdrop {
@@ -90,6 +91,7 @@ export const Modal = forwardRef<HTMLDialogElement, ModalProps>(
       onCancel,
       showButtons = true,
       className,
+      wide = false,
     },
     ref,
   ) => {
@@ -123,6 +125,7 @@ export const Modal = forwardRef<HTMLDialogElement, ModalProps>(
         role="dialog"
         aria-labelledby="modal-heading"
         onClose={onClose}
+        wide={wide}
       >
         <ModalHeader>
           <Heading id="modal-heading">{heading}</Heading>

package/src/inspector/viewer/breadcrumbs.tsx

@@ -1,7 +1,7 @@
 import { styled } from "goober";
 import React from "react";
 import { Button } from "../ui/button.js";
-import { PageInfo } from "./types.js";
+import { useRouter } from "../router/context.js";
 
 const BreadcrumbsContainer = styled("div")`
   position: relative;
@@ -15,21 +15,15 @@ const Separator = styled("span")`
   padding: 0 0.125rem;
 `;
 
-interface BreadcrumbsProps {
-  path: PageInfo[];
-  onBreadcrumbClick: (index: number) => void;
-}
+export const Breadcrumbs: React.FC<{}> = () => {
+  const { path, goToIndex } = useRouter();
 
-export const Breadcrumbs: React.FC<BreadcrumbsProps> = ({
-  path,
-  onBreadcrumbClick,
-}) => {
   return (
     <BreadcrumbsContainer>
       <Button
         variant="link"
         style={{ padding: "0 0.25rem" }}
-        onClick={() => onBreadcrumbClick(-1)}
+        onClick={() => goToIndex(-1)}
       >
         Home
       </Button>
@@ -40,7 +34,7 @@ export const Breadcrumbs: React.FC<BreadcrumbsProps> = ({
             <Button
               variant="link"
               style={{ padding: "0 0.25rem" }}
-              onClick={() => onBreadcrumbClick(index)}
+              onClick={() => goToIndex(index)}
             >
               {index === 0 ? page.name || "Root" : page.name}
             </Button>

package/src/inspector/viewer/header.tsx

@@ -0,0 +1,67 @@
+import { CoID, RawCoValue } from "cojson";
+import { styled } from "goober";
+import React, { type PropsWithChildren, useState } from "react";
+import { Button } from "../ui/button.js";
+import { Input } from "../ui/input.js";
+import { Breadcrumbs } from "./breadcrumbs.js";
+import { DeleteLocalData } from "./delete-local-data.js";
+import { useRouter } from "../router/context.js";
+
+export function Header({
+  showDeleteLocalData = false,
+  showClose = false,
+  onClose,
+  children,
+}: PropsWithChildren<{
+  showDeleteLocalData?: boolean;
+  showClose?: boolean;
+  onClose?: () => void;
+}>) {
+  const [coValueId, setCoValueId] = useState<CoID<RawCoValue> | "">("");
+  const { path, setPage } = useRouter();
+
+  const handleCoValueIdSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (coValueId) {
+      setPage(coValueId);
+    }
+    setCoValueId("");
+  };
+
+  return (
+    <HeaderContainer>
+      <Breadcrumbs />
+      {path.length !== 0 && (
+        <Form onSubmit={handleCoValueIdSubmit}>
+          <Input
+            label="CoValue ID"
+            style={{ fontFamily: "monospace" }}
+            hideLabel
+            placeholder="co_z1234567890abcdef123456789"
+            value={coValueId}
+            onChange={(e) => setCoValueId(e.target.value as CoID<RawCoValue>)}
+          />
+        </Form>
+      )}
+      {children}
+      {showDeleteLocalData && <DeleteLocalData />}
+      {showClose && (
+        <Button variant="plain" type="button" onClick={onClose}>
+          Close
+        </Button>
+      )}
+    </HeaderContainer>
+  );
+}
+
+const HeaderContainer = styled("div")`
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0 0.75rem;
+  margin: 0.75rem 0;
+`;
+
+const Form = styled("form")`
+  width: 24rem;
+`;

package/src/inspector/viewer/page-stack.tsx

@@ -2,23 +2,11 @@ import { CoID, LocalNode, RawCoValue } from "cojson";
 import { styled } from "goober";
 import { Page } from "./page.js";
 import { ErrorBoundary } from "../ui/error-boundary.js";
+import { useRouter } from "../router/context.js";
+import { useNode } from "../contexts/node.js";
+import { HomePage } from "../pages/home.js";
 
-// Define the structure of a page in the path
-interface PageInfo {
-  coId: CoID<RawCoValue>;
-  name?: string;
-}
-
-// Props for the PageStack component
-interface PageStackProps {
-  path: PageInfo[];
-  node?: LocalNode | null;
-  goBack: () => void;
-  addPages: (pages: PageInfo[]) => void;
-  children?: React.ReactNode;
-}
-
-const PageStackContainer = styled("div")`
+const PageStackContainer = styled("article")`
   position: relative;
   padding: 0 0.75rem;
   overflow-y: auto;
@@ -27,25 +15,29 @@ const PageStackContainer = styled("div")`
   font-size: 16px;
 `;
 
-export function PageStack({
-  path,
-  node,
-  goBack,
-  addPages,
-  children,
-}: PageStackProps) {
+type PageStackProps = {
+  homePage?: React.ReactNode;
+};
+
+export function PageStack({ homePage }: PageStackProps) {
+  const { path, addPages, goBack } = useRouter();
+  const { localNode } = useNode();
+
   const page = path[path.length - 1];
   const index = path.length - 1;
 
+  if (path.length <= 0) {
+    return <PageStackContainer>{homePage ?? <HomePage />}</PageStackContainer>;
+  }
+
   return (
     <>
       <PageStackContainer>
-        {children}
-        {node && page && (
+        {localNode && page && (
           <ErrorBoundary title="An error occurred while rendering this CoValue">
             <Page
               coId={page.coId}
-              node={node}
+              node={localNode}
               name={page.name || page.coId}
               onHeaderClick={goBack}
               onNavigate={addPages}

package/src/inspector/viewer/page.tsx

@@ -6,7 +6,6 @@ import {
   RawCoPlainText,
   RawCoStream,
   RawCoValue,
-  RawGroup,
 } from "cojson";
 import { styled } from "goober";
 import React from "react";

package/src/react/hooks.tsx

@@ -56,4 +56,6 @@ export {
   useCoValueSubscription,
   useAccountSubscription,
   useSubscriptionSelector,
+  useSuspenseAccount,
+  useSuspenseCoState,
 } from "jazz-tools/react-core";

package/src/react/index.ts

@@ -1,19 +1,6 @@
 export { JazzReactProvider } from "./provider.js";
 export type { JazzProviderProps } from "./provider.js";
-export {
-  useAccount,
-  useCoState,
-  useAcceptInvite,
-  experimental_useInboxSender,
-  useJazzContext,
-  useAuthSecretStorage,
-  useAgent,
-  useLogOut,
-  useSyncConnectionStatus,
-  useCoValueSubscription,
-  useAccountSubscription,
-  useSubscriptionSelector,
-} from "./hooks.js";
+export * from "./hooks.js";
 
 export {
   createCoValueSubscriptionContext,

package/src/react-core/hooks.ts

@@ -23,11 +23,11 @@ import {
   Loaded,
   MaybeLoaded,
   NotLoaded,
+  RefsToResolve,
   ResolveQuery,
   ResolveQueryStrict,
   SchemaResolveQuery,
   SubscriptionScope,
-  coValueClassFromCoValueClassOrSchema,
   importContentPieces,
   captureStack,
   getUnloadedCoValueWithoutId,
@@ -36,6 +36,7 @@ import {
 import { JazzContext, JazzContextManagerContext } from "./provider.js";
 import { getCurrentAccountFromContextManager } from "./utils.js";
 import { CoValueSubscription } from "./types.js";
+import { use } from "./use.js";
 
 export function useJazzContext<Acc extends Account>() {
   const value = useContext(JazzContext) as JazzContextType<Acc>;
@@ -134,20 +135,22 @@ export function useCoValueSubscription<
     const resolve = getResolveQuery(Schema, options?.resolve);
 
     const node = contextManager.getCurrentValue()!.node;
-    const subscription = new SubscriptionScope<any>(
+    const cache = contextManager.getSubscriptionScopeCache();
+    const subscription = cache.getOrCreate(
       node,
-      resolve,
+      Schema,
       id,
-      {
-        ref: coValueClassFromCoValueClassOrSchema(Schema),
-        optional: true,
-      },
+      resolve,
       false,
       false,
       options?.unstable_branch,
-      callerStack.current,
     );
 
+    // Set callerStack on returned subscription after retrieval
+    if (callerStack.current) {
+      subscription.callerStack = callerStack.current;
+    }
+
     return {
       value: subscription,
       contextManager,
@@ -182,7 +185,6 @@ export function useCoValueSubscription<
     subscription.branchOwnerId !== branchOwnerId ||
     subscription.agent !== agent
   ) {
-    subscription.value?.destroy();
     subscriptionRef.current = createSubscription();
     subscription = subscriptionRef.current;
   }
@@ -442,6 +444,79 @@ export function useCoState<
   return value;
 }
 
+export function useSuspenseCoState<
+  S extends CoValueClassOrSchema,
+  // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+  const R extends ResolveQuery<S> = SchemaResolveQuery<S>,
+  TSelectorReturn = Loaded<S, R>,
+>(
+  /** The CoValue schema or class constructor */
+  Schema: S,
+  /** The ID of the CoValue to subscribe to */
+  id: string,
+  /** Optional configuration for the subscription */
+  options?: {
+    /** Resolve query to specify which nested CoValues to load */
+    resolve?: ResolveQueryStrict<S, R>;
+    /** Select which value to return */
+    select?: (value: Loaded<S, R>) => TSelectorReturn;
+    /** Equality function to determine if the selected value has changed, defaults to `Object.is` */
+    equalityFn?: (a: TSelectorReturn, b: TSelectorReturn) => boolean;
+    /**
+     * Create or load a branch for isolated editing.
+     *
+     * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+     * It's a fork of your data graph: the same schema, but with diverging values.
+     *
+     * The checkout of the branch is applied on all the resolved values.
+     *
+     * @param name - A unique name for the branch. This identifies the branch
+     *   and can be used to switch between different branches of the same CoValue.
+     * @param owner - The owner of the branch. Determines who can access and modify
+     *   the branch. If not provided, the branch is owned by the current user.
+     *
+     * For more info see the [branching](https://jazz.tools/docs/react/using-covalues/version-control) documentation.
+     */
+    unstable_branch?: BranchDefinition;
+    preloaded?: ExportedCoValue<Loaded<S, R>>;
+  },
+): TSelectorReturn {
+  useImportCoValueContent(id, options?.preloaded);
+
+  const subscription = useCoValueSubscription(Schema, id, options);
+
+  if (!subscription) {
+    throw new Error("Subscription not found");
+  }
+
+  use(subscription.getPromise());
+
+  const getCurrentValue = () => {
+    const value = subscription.getCurrentValue();
+
+    if (!value.$isLoaded) {
+      throw new Error("CoValue must be loaded in a suspense context");
+    }
+
+    return value;
+  };
+
+  const value = useSyncExternalStoreWithSelector<Loaded<S, R>, TSelectorReturn>(
+    React.useCallback(
+      (callback) => {
+        return subscription.subscribe(callback);
+      },
+      [subscription],
+    ),
+    getCurrentValue,
+    getCurrentValue,
+    options?.select ?? ((value) => value as TSelectorReturn),
+    options?.equalityFn ?? Object.is,
+  );
+
+  return value;
+}
+
 export function useSubscriptionSelector<
   S extends CoValueClassOrSchema,
   // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
@@ -510,20 +585,22 @@ export function useAccountSubscription<
     const resolve = getResolveQuery(Schema, options?.resolve);
 
     const node = contextManager.getCurrentValue()!.node;
-    const subscription = new SubscriptionScope<any>(
+    const cache = contextManager.getSubscriptionScopeCache();
+    const subscription = cache.getOrCreate(
       node,
-      resolve,
+      Schema,
       agent.$jazz.id,
-      {
-        ref: coValueClassFromCoValueClassOrSchema(Schema),
-        optional: true,
-      },
+      resolve,
       false,
       false,
       options?.unstable_branch,
-      callerStack.current,
     );
 
+    // Set callerStack on returned subscription after retrieval
+    if (callerStack.current) {
+      subscription.callerStack = callerStack.current;
+    }
+
     return {
       subscription,
       contextManager,
@@ -545,12 +622,12 @@ export function useAccountSubscription<
       subscription.branchName !== options?.unstable_branch?.name ||
       subscription.branchOwnerId !== options?.unstable_branch?.owner?.$jazz.id
     ) {
-      subscription.subscription?.destroy();
+      // No need to manually destroy - cache handles cleanup via SubscriptionScope lifecycle
       setSubscription(createSubscription());
     }
 
     return contextManager.subscribe(() => {
-      subscription.subscription?.destroy();
+      // No need to manually destroy - cache handles cleanup via SubscriptionScope lifecycle
       setSubscription(createSubscription());
     });
   }, [Schema, contextManager, branchName, branchOwnerId]);
@@ -705,6 +782,78 @@ export function useAccount<
   );
 }
 
+export function useSuspenseAccount<
+  A extends AccountClass<Account> | AnyAccountSchema,
+  // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+  const R extends ResolveQuery<A> = SchemaResolveQuery<A>,
+  TSelectorReturn = Loaded<A, R>,
+>(
+  /** The account schema to use. Defaults to the base Account schema */
+  AccountSchema: A = Account as unknown as A,
+  /** Optional configuration for the subscription */
+  options?: {
+    /** Resolve query to specify which nested CoValues to load from the account */
+    resolve?: ResolveQueryStrict<A, R>;
+    /** Select which value to return from the account data */
+    select?: (account: Loaded<A, R>) => TSelectorReturn;
+    /** Equality function to determine if the selected value has changed, defaults to `Object.is` */
+    equalityFn?: (a: TSelectorReturn, b: TSelectorReturn) => boolean;
+    /**
+     * Create or load a branch for isolated editing.
+     *
+     * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+     * It's a fork of your data graph: the same schema, but with diverging values.
+     *
+     * The checkout of the branch is applied on all the resolved values.
+     *
+     * @param name - A unique name for the branch. This identifies the branch
+     *   and can be used to switch between different branches of the same CoValue.
+     * @param owner - The owner of the branch. Determines who can access and modify
+     *   the branch. If not provided, the branch is owned by the current user.
+     *
+     * For more info see the [branching](https://jazz.tools/docs/react/using-covalues/version-control) documentation.
+     */
+    unstable_branch?: BranchDefinition;
+  },
+): TSelectorReturn {
+  const subscription = useAccountSubscription(AccountSchema, options);
+
+  if (!subscription) {
+    throw new Error(
+      "Subscription not found, are you using useSuspenseAccount in guest mode?",
+    );
+  }
+
+  use(subscription.getPromise());
+
+  const getCurrentValue = () => {
+    const value = subscription.getCurrentValue();
+
+    if (!value.$isLoaded) {
+      throw new Error("Account must be loaded in a suspense context");
+    }
+
+    return value;
+  };
+
+  return useSyncExternalStoreWithSelector<Loaded<A, R>, TSelectorReturn>(
+    React.useCallback(
+      (callback) => {
+        if (!subscription) {
+          return () => {};
+        }
+
+        return subscription.subscribe(callback);
+      },
+      [subscription],
+    ),
+    getCurrentValue,
+    getCurrentValue,
+    options?.select ?? ((value) => value as TSelectorReturn),
+    options?.equalityFn ?? Object.is,
+  );
+}
+
 /**
  * Returns a function for logging out of the current account.
  */

package/src/react-core/tests/createCoValueSubscriptionContext.test.tsx

@@ -164,15 +164,31 @@ describe("createCoValueSubscriptionContext", () => {
   });
 
   it("the provider shows a loading fallback when loading the coValue", async () => {
+    await setupJazzTestSync({
+      asyncPeers: true,
+    });
+
     const TestMap = co.map({
       value: z.string(),
     });
 
+    const map = TestMap.create({
+      value: "123",
+    });
+
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
     const { Provider } = createCoValueSubscriptionContext(TestMap);
 
     const { container } = render(
       <JazzTestProvider>
-        <Provider id="co_test123" loadingFallback={<div>Loading...</div>}>
+        <Provider
+          id={map.$jazz.id}
+          loadingFallback={<div>Loading...</div>}
+          unavailableFallback={<div>Unavailable</div>}
+        >
           <div>Children should not render</div>
         </Provider>
       </JazzTestProvider>,
@@ -203,13 +219,7 @@ describe("createCoValueSubscriptionContext", () => {
       </JazzTestProvider>,
     );
 
-    // Initially shows loading fallback
-    expect(container.textContent).toContain("Loading...");
-
-    // Should show unavailable fallback after CoValue load timeout
-    await waitFor(() => {
-      expect(container.textContent).toContain("Unavailable");
-    });
+    expect(container.textContent).toContain("Unavailable");
 
     // Children should never be rendered
     expect(container.textContent).not.toContain("Children should not render");

package/src/react-core/tests/testUtils.tsx

@@ -4,9 +4,12 @@ import {
   render,
   renderHook,
 } from "@testing-library/react";
-import { Account, AnonymousJazzAgent, AuthSecretStorage } from "jazz-tools";
+import { Account, AnonymousJazzAgent } from "jazz-tools";
 import React from "react";
 import { JazzTestProvider } from "../testing.js";
+import { getSqliteStorageAsync, SQLiteDatabaseDriverAsync } from "cojson";
+import Database, { type Database as DatabaseT } from "libsql";
+import { onTestFinished } from "vitest";
 
 type JazzExtendedOptions = {
   account?: Account | { guest: AnonymousJazzAgent };
@@ -23,12 +26,16 @@ const customRender = (
         account={options.account}
         isAuthenticated={options.isAuthenticated}
       >
-        {children}
+        {options.wrapper ? (
+          <options.wrapper>{children}</options.wrapper>
+        ) : (
+          children
+        )}
       </JazzTestProvider>
     );
   };
 
-  return render(ui, { wrapper: AllTheProviders, ...options });
+  return render(ui, { ...options, wrapper: AllTheProviders });
 };
 
 const customRenderHook = <TProps, TResult>(
@@ -41,12 +48,16 @@ const customRenderHook = <TProps, TResult>(
         account={options.account}
         isAuthenticated={options.isAuthenticated}
       >
-        {children}
+        {options.wrapper ? (
+          <options.wrapper>{children}</options.wrapper>
+        ) : (
+          children
+        )}
       </JazzTestProvider>
     );
   };
 
-  return renderHook(callback, { wrapper: AllTheProviders, ...options });
+  return renderHook(callback, { ...options, wrapper: AllTheProviders });
 };
 
 // re-export everything
@@ -55,3 +66,54 @@ export * from "@testing-library/react";
 // override render method
 export { customRender as render };
 export { customRenderHook as renderHook };
+
+class LibSQLSqliteAsyncDriver implements SQLiteDatabaseDriverAsync {
+  private readonly db: DatabaseT;
+
+  constructor(filename: string) {
+    this.db = new Database(filename, {});
+  }
+
+  async initialize() {
+    await this.db.pragma("journal_mode = WAL");
+  }
+
+  async run(sql: string, params: unknown[]) {
+    this.db.prepare(sql).run(params);
+  }
+
+  async query<T>(sql: string, params: unknown[]): Promise<T[]> {
+    return this.db.prepare(sql).all(params) as T[];
+  }
+
+  async get<T>(sql: string, params: unknown[]): Promise<T | undefined> {
+    return this.db.prepare(sql).get(params) as T | undefined;
+  }
+
+  async transaction(callback: () => unknown) {
+    await this.run("BEGIN TRANSACTION", []);
+
+    try {
+      await callback();
+      await this.run("COMMIT", []);
+    } catch (error) {
+      await this.run("ROLLBACK", []);
+    }
+  }
+
+  async closeDb() {
+    this.db.close();
+  }
+}
+
+export async function createAsyncStorage() {
+  const storage = await getSqliteStorageAsync(
+    new LibSQLSqliteAsyncDriver(":memory:"),
+  );
+
+  onTestFinished(() => {
+    storage.close();
+  });
+
+  return storage;
+}

package/src/react-core/tests/useCoState.test.ts

@@ -64,13 +64,9 @@ describe("useCoState", () => {
       account,
     });
 
-    expect(result.current.$jazz.loadingState).toBe(CoValueLoadingState.LOADING);
-
-    await waitFor(() => {
-      expect(result.current.$jazz.loadingState).toBe(
-        CoValueLoadingState.UNAVAILABLE,
-      );
-    });
+    expect(result.current.$jazz.loadingState).toBe(
+      CoValueLoadingState.UNAVAILABLE,
+    );
   });
 
   it("should update the value when the coValue changes", async () => {