jazz-tools 0.18.6 → 0.18.7

package/src/inspector/ui/heading.tsx

@@ -10,6 +10,11 @@ const StyledHeading = styled("h1")<{ className?: string }>`
 export function Heading({
   children,
   className,
-}: React.PropsWithChildren<{ className?: string }>) {
-  return <StyledHeading className={className}>{children}</StyledHeading>;
+  id,
+}: React.PropsWithChildren<{ className?: string; id?: string }>) {
+  return (
+    <StyledHeading className={className} id={id}>
+      {children}
+    </StyledHeading>
+  );
 }

package/src/inspector/ui/input.tsx

@@ -27,7 +27,7 @@ const StyledInput = styled("input")`
   box-shadow: var(--j-shadow-sm);
   font-weight: 500;
   background-color: white;
-  color: var(--text-color-strong);
+  color: var(--j-text-color-strong);
 
   @media (prefers-color-scheme: dark) {
     background-color: var(--j-foreground);
@@ -41,7 +41,11 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(
 
     return (
       <Container className={className}>
-        <label htmlFor={id} className={hideLabel ? "j-sr-only" : ""}>
+        <label
+          htmlFor={id}
+          className={hideLabel ? "j-sr-only" : ""}
+          style={{ color: "var(--j-text-color)" }}
+        >
           {label}
         </label>
         <StyledInput ref={ref} {...inputProps} id={id} />

package/src/inspector/ui/modal.tsx

@@ -0,0 +1,158 @@
+import { styled } from "goober";
+import { forwardRef, useEffect, useRef } from "react";
+import { Button } from "./button.js";
+import { Heading } from "./heading.js";
+
+interface ModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  heading: string;
+  text?: string;
+  children?: React.ReactNode;
+  confirmText?: string;
+  cancelText?: string;
+  onConfirm?: () => void;
+  onCancel?: () => void;
+  showButtons?: boolean;
+  className?: string;
+}
+
+const ModalContent = styled("dialog")`
+  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;
+  margin-block: auto;
+  margin-inline: auto;
+  &::backdrop {
+    background-color: rgba(0, 0, 0, 0.7);
+  }
+  
+`;
+
+const ModalHeader = styled("div")`
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  padding: 1.5rem 1.5rem 0 1.5rem;
+  gap: 1rem;
+`;
+
+const ModalBody = styled("div")`
+  padding: 1rem 1.5rem;
+  flex: 1;
+`;
+
+const ModalFooter = styled("div")`
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.75rem;
+  padding: 0 1.5rem 1.5rem 1.5rem;
+`;
+
+const CloseButton = styled("button")`
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: 0.25rem;
+  border-radius: var(--j-radius-sm);
+  color: var(--j-text-color);
+  font-size: 1.25rem;
+  line-height: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2rem;
+  min-height: 2rem;
+  
+  &:hover {
+    background-color: var(--j-foreground);
+  }
+  
+  &:focus-visible {
+    outline: 2px solid var(--j-border-focus);
+    outline-offset: 2px;
+  }
+`;
+
+export const Modal = forwardRef<HTMLDialogElement, ModalProps>(
+  (
+    {
+      isOpen,
+      onClose,
+      heading,
+      text,
+      children,
+      confirmText = "Confirm",
+      cancelText = "Cancel",
+      onConfirm,
+      onCancel,
+      showButtons = true,
+      className,
+    },
+    ref,
+  ) => {
+    const modalRef = useRef<HTMLDialogElement>(null);
+
+    useEffect(() => {
+      if (isOpen) {
+        modalRef.current?.showModal();
+      } else {
+        onClose();
+        modalRef.current?.close();
+      }
+    }, [isOpen, onClose]);
+
+    const handleConfirm = () => {
+      onConfirm?.();
+      onClose();
+    };
+
+    const handleCancel = () => {
+      onCancel?.();
+      onClose();
+    };
+
+    if (!isOpen) return null;
+
+    return (
+      <ModalContent
+        ref={ref || modalRef}
+        className={className}
+        role="dialog"
+        aria-labelledby="modal-heading"
+        onClose={onClose}
+      >
+        <ModalHeader>
+          <Heading id="modal-heading">{heading}</Heading>
+          <CloseButton onClick={onClose} aria-label="Close modal" type="button">
+            ×
+          </CloseButton>
+        </ModalHeader>
+
+        <ModalBody>
+          {text && (
+            <p style={{ margin: "0 0 1rem 0", color: "var(--j-text-color)" }}>
+              {text}
+            </p>
+          )}
+          {children}
+        </ModalBody>
+
+        {showButtons && (
+          <ModalFooter>
+            <Button variant="secondary" onClick={handleCancel}>
+              {cancelText}
+            </Button>
+            <Button variant="primary" onClick={handleConfirm}>
+              {confirmText}
+            </Button>
+          </ModalFooter>
+        )}
+      </ModalContent>
+    );
+  },
+);
+
+Modal.displayName = "Modal";

package/src/inspector/viewer/delete-local-data.tsx

@@ -0,0 +1,101 @@
+import { Button } from "../ui/button.js";
+import { Modal } from "../ui/modal.js";
+import { Input } from "../ui/input.js";
+import { useState } from "react";
+
+const DELETE_LOCAL_DATA_STRING = "delete my local data";
+
+export function DeleteLocalData() {
+  const [showDeleteModal, setShowDeleteModal] = useState(false);
+  const [confirmDeleteString, setConfirmDeleteString] = useState("");
+
+  return (
+    <>
+      <Button variant="destructive" onClick={() => setShowDeleteModal(true)}>
+        Delete my local data
+      </Button>
+      <Modal
+        isOpen={showDeleteModal}
+        onClose={() => setShowDeleteModal(false)}
+        heading="Delete Local Data"
+        showButtons={false}
+      >
+        <div
+          style={{
+            margin: "0 0 1rem 0",
+            color: "var(--j-text-color)",
+            display: "flex",
+            flexDirection: "column",
+            gap: "0.5rem",
+          }}
+        >
+          <p>
+            This action <strong>cannot</strong> be undone.
+          </p>
+          <p>
+            Be aware that the following data will be{" "}
+            <strong>permanently</strong> deleted:
+          </p>
+          <ul style={{ listStyleType: "disc", paddingLeft: "1rem" }}>
+            <li>
+              Unsynced data for <strong>all apps</strong> on{" "}
+              <code>{window.location.origin}</code>
+            </li>
+            <li>Accounts</li>
+            <li>Logged in sessions</li>
+          </ul>
+          <p></p>
+        </div>
+        <Input
+          label={`Type "${DELETE_LOCAL_DATA_STRING}" to confirm`}
+          placeholder={DELETE_LOCAL_DATA_STRING}
+          value={confirmDeleteString}
+          onChange={(e) => {
+            setConfirmDeleteString(e.target.value);
+          }}
+        />
+        <p
+          style={{
+            margin: "0 0 1rem 0",
+            color: "var(--j-text-color)",
+            display: "flex",
+            flexDirection: "column",
+            gap: "0.5rem",
+          }}
+        >
+          <small>
+            Data synced to a sync server will <strong>not</strong> be deleted,
+            and will be synced when you log in again.
+          </small>
+        </p>
+        <div
+          style={{
+            display: "flex",
+            marginTop: "0.5rem",
+            justifyContent: "flex-end",
+            gap: "0.5rem",
+          }}
+        >
+          <Button variant="secondary" onClick={() => setShowDeleteModal(false)}>
+            Cancel
+          </Button>
+          <Button
+            variant="destructive"
+            disabled={confirmDeleteString !== DELETE_LOCAL_DATA_STRING}
+            onClick={() => {
+              const jazzKeys = Object.keys(localStorage).filter(
+                (key) => key.startsWith("jazz-") || key.startsWith("co_z"),
+              );
+              jazzKeys.forEach((key) => localStorage.removeItem(key));
+              indexedDB.deleteDatabase("jazz-storage");
+              window.location.reload();
+              setShowDeleteModal(false);
+            }}
+          >
+            I'm sure, delete my local data
+          </Button>
+        </div>
+      </Modal>
+    </>
+  );
+}

package/src/inspector/viewer/new-app.tsx

@@ -9,8 +9,9 @@ import { usePagePath } from "./use-page-path.js";
 
 import { GlobalStyles } from "../ui/global-styles.js";
 import { Heading } from "../ui/heading.js";
-import { InspectorButton, type Position } from "./inpsector-button.js";
+import { InspectorButton, type Position } from "./inspector-button.js";
 import { useOpenInspector } from "./use-open-inspector.js";
+import { DeleteLocalData } from "./delete-local-data.js";
 
 const InspectorContainer = styled("div")`
   position: fixed;
@@ -102,6 +103,7 @@ export function JazzInspectorInternal({
             />
           )}
         </Form>
+        <DeleteLocalData />
         <Button variant="plain" type="button" onClick={() => setOpen(false)}>
           Close
         </Button>

package/src/react/hooks.tsx

@@ -50,4 +50,5 @@ export {
   experimental_useInboxSender,
   useJazzContext,
   useAccount,
+  useCoStateWithSelector,
 } from "jazz-tools/react-core";

package/src/react/index.ts

@@ -7,6 +7,7 @@ export {
   experimental_useInboxSender,
   useJazzContext,
   useAuthSecretStorage,
+  useCoStateWithSelector,
 } from "./hooks.js";
 
 export { createInviteLink, parseInviteLink } from "jazz-tools/browser";

package/src/react-core/hooks.ts

@@ -1,3 +1,4 @@
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
 import React, {
   useCallback,
   useContext,
@@ -261,6 +262,167 @@ export function useCoState<
   return value;
 }
 
+/**
+ * React hook for subscribing to CoValues with selective data extraction and custom equality checking.
+ *
+ * This hook extends `useCoState` by allowing you to select only specific parts of the CoValue data
+ * through a selector function, which helps reduce unnecessary re-renders by narrowing down the
+ * returned data. Additionally, you can provide a custom equality function to further optimize
+ * performance by controlling when the component should re-render based on the selected data.
+ *
+ * The hook automatically handles the subscription lifecycle and supports deep loading of nested
+ * CoValues through resolve queries, just like `useCoState`.
+ *
+ * @returns The result of the selector function applied to the loaded CoValue data
+ *
+ * @example
+ * ```tsx
+ * // Select only specific fields to reduce re-renders
+ * const Project = co.map({
+ *   name: z.string(),
+ *   description: z.string(),
+ *   tasks: co.list(Task),
+ *   lastModified: z.date(),
+ * });
+ *
+ * function ProjectTitle({ projectId }: { projectId: string }) {
+ *   // Only re-render when the project name changes, not other fields
+ *   const projectName = useCoStateWithSelector(
+ *     Project,
+ *     projectId,
+ *     {
+ *       select: (project) => project?.name ?? "Loading...",
+ *     }
+ *   );
+ *
+ *   return <h1>{projectName}</h1>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Use custom equality function for complex data structures
+ * const TaskList = co.list(Task);
+ *
+ * function TaskCount({ listId }: { listId: string }) {
+ *   const taskStats = useCoStateWithSelector(
+ *     TaskList,
+ *     listId,
+ *     {
+ *       resolve: { $each: true },
+ *       select: (tasks) => {
+ *         if (!tasks) return { total: 0, completed: 0 };
+ *         return {
+ *           total: tasks.length,
+ *           completed: tasks.filter(task => task.completed).length,
+ *         };
+ *       },
+ *       // Custom equality to prevent re-renders when stats haven't changed
+ *       equalityFn: (a, b) => a.total === b.total && a.completed === b.completed,
+ *     }
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       {taskStats.completed} of {taskStats.total} tasks completed
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Combine with deep loading and complex selectors
+ * const Team = co.map({
+ *   name: z.string(),
+ *   members: co.list(TeamMember),
+ *   projects: co.list(Project),
+ * });
+ *
+ * function TeamSummary({ teamId }: { teamId: string }) {
+ *   const summary = useCoStateWithSelector(
+ *     Team,
+ *     teamId,
+ *     {
+ *       resolve: {
+ *         members: { $each: true },
+ *         projects: { $each: { tasks: { $each: true } } },
+ *       },
+ *       select: (team) => {
+ *         if (!team) return null;
+ *
+ *         const totalTasks = team.projects.reduce(
+ *           (sum, project) => sum + project.tasks.length,
+ *           0
+ *         );
+ *
+ *         return {
+ *           teamName: team.name,
+ *           memberCount: team.members.length,
+ *           projectCount: team.projects.length,
+ *           totalTasks,
+ *         };
+ *       },
+ *     }
+ *   );
+ *
+ *   if (!summary) return <div>Loading team summary...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <h2>{summary.teamName}</h2>
+ *       <p>{summary.memberCount} members</p>
+ *       <p>{summary.projectCount} projects</p>
+ *       <p>{summary.totalTasks} total tasks</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * For more examples, see the [subscription and deep loading](https://jazz.tools/docs/react/using-covalues/subscription-and-loading) documentation.
+ */
+export function useCoStateWithSelector<
+  S extends CoValueClassOrSchema,
+  TSelectorReturn,
+  const R extends ResolveQuery<S> = true,
+>(
+  /** The CoValue schema or class constructor */
+  Schema: S,
+  /** The ID of the CoValue to subscribe to. If `undefined`, returns the result of selector called with `null` */
+  id: string | undefined,
+  /** 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> | undefined | null) => TSelectorReturn;
+    /** Equality function to determine if the selected value has changed, defaults to `Object.is` */
+    equalityFn?: (a: TSelectorReturn, b: TSelectorReturn) => boolean;
+  },
+): TSelectorReturn {
+  const subscription = useCoValueSubscription(Schema, id, options);
+
+  return useSyncExternalStoreWithSelector<
+    Loaded<S, R> | undefined | null,
+    TSelectorReturn
+  >(
+    React.useCallback(
+      (callback) => {
+        if (!subscription) {
+          return () => {};
+        }
+
+        return subscription.subscribe(callback);
+      },
+      [subscription],
+    ),
+    () => (subscription ? subscription.getCurrentValue() : null),
+    () => (subscription ? subscription.getCurrentValue() : null),
+    options.select,
+    options.equalityFn ?? Object.is,
+  );
+}
+
 function useAccountSubscription<
   S extends AccountClass<Account> | AnyAccountSchema,
   const R extends ResolveQuery<S>,

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

@@ -0,0 +1,149 @@
+// @vitest-environment happy-dom
+
+import { cojsonInternals } from "cojson";
+import { Account, co, Loaded, z } from "jazz-tools";
+import { beforeEach, describe, expect, expectTypeOf, it } from "vitest";
+import { useCoStateWithSelector } from "../index.js";
+import { createJazzTestAccount, setupJazzTestSync } from "../testing.js";
+import { renderHook, waitFor } from "./testUtils.js";
+import { useRef } from "react";
+
+beforeEach(async () => {
+  await setupJazzTestSync();
+
+  await createJazzTestAccount({
+    isCurrentActiveAccount: true,
+  });
+});
+
+cojsonInternals.setCoValueLoadingRetryDelay(300);
+
+const useRenderCount = <T>(hook: () => T) => {
+  const renderCountRef = useRef(0);
+  const result = hook();
+  renderCountRef.current = renderCountRef.current + 1;
+  return {
+    renderCount: renderCountRef.current,
+    result,
+  };
+};
+
+describe("useCoStateWithSelector", () => {
+  it("should not re-render when a nested coValue is updated and not selected", async () => {
+    const TestMap = co.map({
+      value: z.string(),
+      get nested() {
+        return TestMap.optional();
+      },
+    });
+
+    const map = TestMap.create({
+      value: "1",
+      nested: TestMap.create({
+        value: "1",
+      }),
+    });
+
+    const { result } = renderHook(() =>
+      useRenderCount(() =>
+        useCoStateWithSelector(TestMap, map.$jazz.id, {
+          resolve: {
+            nested: true,
+          },
+          select: (v) => v?.value,
+        }),
+      ),
+    );
+
+    await waitFor(() => {
+      expect(result.current.result).not.toBeUndefined();
+    });
+
+    for (let i = 0; i < 100; i++) {
+      map.nested!.$jazz.set("value", `${i}`);
+      await Account.getMe().$jazz.waitForAllCoValuesSync();
+    }
+
+    expect(result.current.result).toEqual("1");
+    expect(result.current.renderCount).toEqual(1);
+  });
+
+  it("should re-render when a nested coValue is updated and selected", async () => {
+    const TestMap = co.map({
+      value: z.string(),
+      get nested() {
+        return TestMap.optional();
+      },
+    });
+
+    const map = TestMap.create({
+      value: "1",
+      nested: TestMap.create({
+        value: "1",
+      }),
+    });
+
+    const { result } = renderHook(() =>
+      useRenderCount(() =>
+        useCoStateWithSelector(TestMap, map.$jazz.id, {
+          resolve: {
+            nested: true,
+          },
+          select: (v) => v?.nested?.value,
+        }),
+      ),
+    );
+
+    await waitFor(() => {
+      expect(result.current.result).not.toBeUndefined();
+    });
+
+    for (let i = 1; i <= 100; i++) {
+      map.nested!.$jazz.set("value", `${i}`);
+      await Account.getMe().$jazz.waitForAllCoValuesSync();
+    }
+
+    expect(result.current.result).toEqual("100");
+
+    // skips re-render on i = 1, only re-renders on i = [2,100], so initial render + 99 renders = 100
+    expect(result.current.renderCount).toEqual(100);
+
+    expectTypeOf(result.current.result).toEqualTypeOf<string | undefined>();
+  });
+
+  it("should not re-render when equalityFn always returns true", async () => {
+    const TestMap = co.map({
+      value: z.string(),
+      get nested() {
+        return TestMap.optional();
+      },
+    });
+
+    const map = TestMap.create({
+      value: "1",
+      nested: TestMap.create({
+        value: "1",
+      }),
+    });
+
+    const { result } = renderHook(() =>
+      useRenderCount(() =>
+        useCoStateWithSelector(TestMap, map.$jazz.id, {
+          resolve: {
+            nested: true,
+          },
+          select: (v) => v?.nested?.value,
+          equalityFn: () => true,
+        }),
+      ),
+    );
+
+    for (let i = 1; i <= 100; i++) {
+      map.nested!.$jazz.set("value", `${i}`);
+      await Account.getMe().$jazz.waitForAllCoValuesSync();
+    }
+
+    expect(result.current.result).toEqual("1");
+    expect(result.current.renderCount).toEqual(1);
+  });
+});

package/src/react-native-core/hooks.tsx

@@ -13,6 +13,7 @@ export {
   useAuthSecretStorage,
   useIsAuthenticated,
   useAccount,
+  useCoStateWithSelector,
 } from "jazz-tools/react-core";
 
 export function useAcceptInviteNative<S extends CoValueClassOrSchema>({

package/src/tools/coValues/CoValueBase.ts

@@ -77,4 +77,36 @@ export abstract class CoValueJazzApi<V extends CoValue> {
 
     return new AnonymousJazzAgent(this.localNode);
   }
+
+  /**
+   * The timestamp of the creation time of the CoValue
+   *
+   * @category Content
+   */
+  get createdAt(): number {
+    const createdAt = this.raw.core.verified.header.meta?.createdAt;
+
+    if (typeof createdAt === "string") {
+      return new Date(createdAt).getTime();
+    }
+
+    return this.raw.core.earliestTxMadeAt;
+  }
+
+  /**
+   * The timestamp of the last updated time of the CoValue
+   *
+   * Returns the creation time if there are no updates.
+   *
+   * @category Content
+   */
+  get lastUpdatedAt(): number {
+    const value = this.raw.core.latestTxMadeAt;
+
+    if (value === 0) {
+      return this.createdAt;
+    }
+
+    return value;
+  }
 }