jazz-tools 0.14.27 → 0.15.0

package/src/prosemirror/lib/plugin.ts

@@ -0,0 +1,120 @@
+import { CoRichText } from "jazz-tools";
+import { Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+import { htmlToProseMirror } from "./converter.js";
+import { createSyncHandlers } from "./sync.js";
+
+/**
+ * Configuration options for the Jazz plugin
+ */
+export interface JazzPluginConfig {
+  /** Whether to show caret and selection decorations */
+  showDecorations?: boolean;
+}
+
+/**
+ * Unique key for the Jazz plugin to identify it in the ProseMirror state.
+ * This key is used to access the plugin's state and view from the editor.
+ */
+export const jazzPluginKey = new PluginKey("jazz");
+
+/**
+ * Creates a ProseMirror plugin that synchronizes a CoRichText instance with a ProseMirror editor.
+ *
+ * This plugin enables bidirectional synchronization between a CoRichText instance
+ * and a ProseMirror editor. It handles:
+ * - Initializing the editor with CoRichText content
+ * - Updating the editor when CoRichText changes
+ * - Updating CoRichText when the editor changes
+ * - Managing the editor view lifecycle
+ *
+ * @param coRichText - The CoRichText instance to synchronize with the editor.
+ *                     If undefined, the plugin will still work but won't sync with CoRichText.
+ * @param config - Optional configuration for the plugin
+ * @returns A ProseMirror plugin instance that can be added to an editor
+ *
+ * @example
+ * ```typescript
+ * const coRichText = new CoRichText({ text: "<p>Hello</p>", owner: account });
+ * const plugin = createJazzPlugin(coRichText, { showDecorations: true });
+ * const state = EditorState.create({
+ *   schema,
+ *   plugins: [plugin],
+ * });
+ * ```
+ */
+export function createJazzPlugin(
+  coRichText: CoRichText | undefined,
+  config: JazzPluginConfig = {},
+) {
+  const { setView, handleCoRichTextChange, handleProseMirrorChange } =
+    createSyncHandlers(coRichText);
+
+  return new Plugin({
+    key: jazzPluginKey,
+
+    view(editorView) {
+      setView(editorView);
+
+      if (coRichText) {
+        coRichText.subscribe(handleCoRichTextChange);
+      }
+
+      return {
+        destroy() {
+          setView(undefined);
+        },
+      };
+    },
+
+    state: {
+      init(_config, state) {
+        if (coRichText) {
+          const pmDoc = htmlToProseMirror(coRichText.toString(), state.schema);
+          state.doc = pmDoc;
+        }
+        return { coRichText };
+      },
+
+      apply(tr, value) {
+        handleProseMirrorChange(tr);
+        return value;
+      },
+    },
+
+    props: {
+      decorations(state) {
+        if (!config.showDecorations) {
+          return null;
+        }
+
+        const selection = state.selection;
+
+        if (selection.empty) {
+          const caret = Decoration.widget(selection.from, () => {
+            const div = document.createElement("span");
+            div.className = "jazz-caret";
+            div.style.borderLeft = "2px solid red";
+            div.style.marginLeft = "-2px";
+            div.style.backgroundColor = "rgba(255,0,0,0.1)";
+            return div;
+          });
+
+          return DecorationSet.create(state.doc, [caret]);
+        }
+
+        const selectionDecoration = Decoration.inline(
+          selection.from,
+          selection.to,
+          {
+            class: "jazz-caret-selection",
+            style:
+              "border-left: 2px solid red; margin-left: -2px; background: rgba(255,0,0,0.1);",
+          },
+        );
+
+        return DecorationSet.create(state.doc, [selectionDecoration]);
+      },
+    },
+  });
+}

package/src/prosemirror/lib/sync.ts

@@ -0,0 +1,96 @@
+import { recreateTransform } from "@manuscripts/prosemirror-recreate-steps";
+import { CoRichText } from "jazz-tools";
+import { Transaction } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+import { htmlToProseMirror, proseMirrorToHtml } from "./converter.js";
+
+/**
+ * Metadata key used to identify changes originating from Jazz.
+ * This is used to prevent infinite update loops between CoRichText and ProseMirror.
+ */
+export const META_KEY = "fromJazz";
+
+/**
+ * Creates handlers for bidirectional synchronization between CoRichText and ProseMirror.
+ *
+ * This function returns a set of handlers that manage the synchronization between
+ * a CoRichText instance and a ProseMirror editor. It handles:
+ * - Updating the ProseMirror editor when CoRichText changes
+ * - Updating CoRichText when the ProseMirror editor changes
+ * - Preventing infinite update loops
+ *
+ * @param coRichText - The CoRichText instance to synchronize with
+ * @returns An object containing the synchronization handlers:
+ *   - setView: Function to set the current ProseMirror view
+ *   - handleCoRichTextChange: Handler for CoRichText changes
+ *   - handleProseMirrorChange: Handler for ProseMirror changes
+ *
+ * @example
+ * ```typescript
+ * const handlers = createSyncHandlers(coRichText);
+ * handlers.setView(editorView);
+ * ```
+ */
+export function createSyncHandlers(coRichText: CoRichText | undefined) {
+  // Store the editor view in a closure
+  let view: EditorView | undefined;
+
+  /**
+   * Handles changes from CoRichText by updating the ProseMirror editor.
+   *
+   * When CoRichText content changes, this function:
+   * 1. Converts the new content to a ProseMirror document
+   * 2. Creates a transaction to replace the editor's content
+   * 3. Marks the transaction as coming from Jazz to prevent loops
+   * 4. Dispatches the transaction to update the editor
+   *
+   * @param newText - The updated CoRichText instance
+   */
+  function handleCoRichTextChange(newText: CoRichText) {
+    if (!view || !newText) return;
+
+    const pmDoc = htmlToProseMirror(
+      newText.toString(),
+      view.state.doc.type.schema,
+    );
+    const transform = recreateTransform(view.state.doc, pmDoc);
+
+    // Create a new transaction
+    const tr = view.state.tr;
+
+    // Apply all steps from the transform to the transaction
+    transform.steps.forEach((step) => {
+      tr.step(step);
+    });
+
+    tr.setMeta(META_KEY, true);
+    view.dispatch(tr);
+  }
+
+  /**
+   * Handles changes from ProseMirror by updating the CoRichText.
+   *
+   * When the ProseMirror editor content changes, this function:
+   * 1. Checks if the change originated from Jazz (to prevent loops)
+   * 2. Converts the new content to HTML
+   * 3. Updates the CoRichText with the new content
+   *
+   * @param tr - The ProseMirror transaction representing the change
+   */
+  function handleProseMirrorChange(tr: Transaction) {
+    if (!coRichText || tr.getMeta(META_KEY)) return;
+
+    if (tr.docChanged) {
+      const str = proseMirrorToHtml(tr.doc);
+      coRichText.applyDiff(str);
+    }
+  }
+
+  return {
+    setView: (newView?: EditorView) => {
+      view = newView;
+    },
+    handleCoRichTextChange,
+    handleProseMirrorChange,
+  };
+}

package/src/prosemirror/tests/plugin.test.ts

@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+
+import { Account, CoRichText } from "jazz-tools";
+import { createJazzTestAccount, setupJazzTestSync } from "jazz-tools/testing";
+import { schema } from "prosemirror-schema-basic";
+import { EditorState, TextSelection } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createJazzPlugin } from "../lib/plugin";
+
+let account: Account;
+let coRichText: CoRichText;
+let plugin: Plugin;
+let state: EditorState;
+let view: EditorView;
+
+beforeEach(async () => {
+  await setupJazzTestSync();
+  account = await createJazzTestAccount({ isCurrentActiveAccount: true });
+
+  // Create a real CoRichText with the test account as owner
+  coRichText = CoRichText.create("<p>Hello</p>", account);
+
+  plugin = createJazzPlugin(coRichText);
+  state = EditorState.create({
+    schema,
+    plugins: [plugin],
+  });
+
+  // Create a DOM element for the editor
+  const editorElement = document.createElement("div");
+  document.body.appendChild(editorElement);
+
+  // Initialize the editor view
+  view = new EditorView(editorElement, {
+    state,
+  });
+});
+
+afterEach(() => {
+  // Clean up the editor view
+  if (view) {
+    view.destroy();
+    view.dom.remove();
+  }
+});
+
+describe("createJazzPlugin", () => {
+  it("initializes editor with CoRichText content", () => {
+    expect(state.doc.textContent).toContain("Hello");
+  });
+
+  it("updates editor when CoRichText changes", async () => {
+    // Update CoRichText content
+    coRichText.applyDiff("<p>Updated content</p>");
+
+    // Wait for the next tick to allow the update to propagate
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(view.state.doc.textContent).toContain("Updated content");
+  });
+
+  it("updates CoRichText when editor content changes", () => {
+    // Create a transaction to update the editor content
+    const tr = view.state.tr.insertText(" World", 6);
+    view.dispatch(tr);
+
+    // Verify CoRichText was updated
+    expect(coRichText.toString()).toContain("Hello World");
+  });
+
+  it("handles empty CoRichText initialization", () => {
+    const emptyCoRichText = CoRichText.create("", account);
+    const emptyPlugin = createJazzPlugin(emptyCoRichText);
+    const emptyState = EditorState.create({
+      schema,
+      plugins: [emptyPlugin],
+    });
+
+    expect(emptyState.doc.textContent).toBe("");
+  });
+
+  it("handles undefined CoRichText", () => {
+    const undefinedPlugin = createJazzPlugin(undefined);
+    const undefinedState = EditorState.create({
+      schema,
+      plugins: [undefinedPlugin],
+    });
+
+    expect(undefinedState.doc.textContent).toBe("");
+  });
+
+  it("prevents infinite update loops", () => {
+    // Create a transaction that would normally trigger a CoRichText update
+    const tr = view.state.tr.insertText(" Loop", 6);
+
+    // Mark the transaction as coming from Jazz
+    tr.setMeta("fromJazz", true);
+    view.dispatch(tr);
+
+    // Verify the content was updated in the editor
+    expect(view.state.doc.textContent).toContain("Hello Loop");
+
+    // Verify CoRichText was NOT updated (to prevent infinite loop)
+    expect(coRichText.toString()).not.toContain("Loop");
+  });
+
+  it.skip("preserves selection when CoRichText changes", () => {
+    // Set a selection in the editor
+    const tr = view.state.tr.setSelection(
+      TextSelection.create(view.state.doc, 2, 5),
+    );
+    view.dispatch(tr);
+
+    // Verify initial selection is set
+    expect(view.state.selection.from).toBe(2);
+    expect(view.state.selection.to).toBe(5);
+
+    // Update CoRichText content
+    coRichText.applyDiff("<p>Updated content</p>");
+
+    // Verify selection is preserved after content update
+    expect(view.state.selection.from).toBe(2);
+    expect(view.state.selection.to).toBe(5);
+  });
+});

package/src/react/auth/Clerk.tsx

@@ -0,0 +1,82 @@
+import { JazzClerkAuth, type MinimalClerkClient } from "jazz-tools";
+import {
+  Account,
+  AccountClass,
+  AnyAccountSchema,
+  CoValueFromRaw,
+  InMemoryKVStore,
+  KvStoreContext,
+} from "jazz-tools";
+import { LocalStorageKVStore } from "jazz-tools/browser";
+import { useAuthSecretStorage, useJazzContext } from "jazz-tools/react-core";
+import { useEffect, useMemo, useState } from "react";
+import { JazzProviderProps, JazzReactProvider } from "../provider.js";
+
+function useJazzClerkAuth(clerk: MinimalClerkClient) {
+  const context = useJazzContext();
+  const authSecretStorage = useAuthSecretStorage();
+
+  if ("guest" in context) {
+    throw new Error("Clerk auth is not supported in guest mode");
+  }
+
+  const authMethod = useMemo(() => {
+    return new JazzClerkAuth(context.authenticate, authSecretStorage);
+  }, []);
+
+  useEffect(() => {
+    return authMethod.registerListener(clerk);
+  }, []);
+}
+
+function RegisterClerkAuth(props: {
+  clerk: MinimalClerkClient;
+  children: React.ReactNode;
+}) {
+  useJazzClerkAuth(props.clerk);
+
+  return props.children;
+}
+
+export const JazzReactProviderWithClerk = <
+  S extends
+    | (AccountClass<Account> & CoValueFromRaw<Account>)
+    | AnyAccountSchema,
+>(
+  props: { clerk: MinimalClerkClient } & JazzProviderProps<S>,
+) => {
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  /**
+   * This effect ensures that a logged-in Clerk user is authenticated before the JazzReactProvider is mounted.
+   *
+   * This is done to optimize the initial load.
+   */
+  useEffect(() => {
+    setupKvStore();
+
+    JazzClerkAuth.initializeAuth(props.clerk).then(() => {
+      setIsLoaded(true);
+    });
+  }, []);
+
+  if (!isLoaded) {
+    return null;
+  }
+
+  return (
+    <JazzReactProvider {...props} logOutReplacement={props.clerk.signOut}>
+      <RegisterClerkAuth clerk={props.clerk}>
+        {props.children}
+      </RegisterClerkAuth>
+    </JazzReactProvider>
+  );
+};
+
+function setupKvStore() {
+  KvStoreContext.getInstance().initialize(
+    typeof window === "undefined"
+      ? new InMemoryKVStore()
+      : new LocalStorageKVStore(),
+  );
+}

package/src/react/auth/DemoAuth.tsx

@@ -0,0 +1,121 @@
+import { useDemoAuth } from "jazz-tools/react-core";
+import { useState } from "react";
+
+export const DemoAuthBasicUI = (props: {
+  appName: string;
+  children?: React.ReactNode;
+}) => {
+  const auth = useDemoAuth();
+
+  const [username, setUsername] = useState<string>("");
+
+  const darkMode =
+    typeof window !== "undefined"
+      ? window.matchMedia("(prefers-color-scheme: dark)").matches
+      : false;
+
+  if (auth.state === "signedIn") return props.children ?? null;
+
+  const { signUp, logIn, existingUsers } = auth;
+
+  return (
+    <div
+      style={{
+        minHeight: "100%",
+        display: "flex",
+        flexDirection: "column",
+        justifyContent: "center",
+        width: "18rem",
+        maxWidth: "calc(100vw - 2rem)",
+        gap: "2rem",
+        margin: "0 auto",
+      }}
+    >
+      <h1
+        style={{
+          color: darkMode ? "#fff" : "#000",
+          textAlign: "center",
+          fontSize: "1.5rem",
+          fontWeight: "bold",
+        }}
+      >
+        {props.appName}
+      </h1>
+      <form
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "0.5rem",
+        }}
+        onSubmit={(e) => {
+          e.preventDefault();
+          signUp(username);
+        }}
+      >
+        <input
+          placeholder="Display name"
+          value={username}
+          onChange={(e) => setUsername(e.target.value)}
+          autoComplete="webauthn"
+          style={{
+            border: darkMode ? "1px solid #444" : "1px solid #ddd",
+            padding: "11px 8px",
+            borderRadius: "6px",
+            background: darkMode ? "#000" : "#fff",
+            color: darkMode ? "#fff" : "#000",
+          }}
+        />
+        <input
+          type="submit"
+          value="Sign up"
+          style={{
+            padding: "13px 5px",
+            border: "none",
+            borderRadius: "6px",
+            cursor: "pointer",
+            background: darkMode ? "#444" : "#ddd",
+            color: darkMode ? "#fff" : "#000",
+          }}
+        />
+      </form>
+      {existingUsers.length > 0 && (
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            gap: "0.5rem",
+          }}
+        >
+          <p
+            style={{
+              color: darkMode ? "#e2e2e2" : "#000",
+              textAlign: "center",
+              paddingTop: "0.5rem",
+              borderTop: "1px solid",
+              borderColor: darkMode ? "#111" : "#e2e2e2",
+            }}
+          >
+            Log in as
+          </p>
+          {existingUsers.map((user) => (
+            <button
+              key={user}
+              onClick={() => logIn(user)}
+              type="button"
+              aria-label={`Log in as ${user}`}
+              style={{
+                background: darkMode ? "#0d0d0d" : "#eee",
+                color: darkMode ? "#fff" : "#000",
+                padding: "0.5rem",
+                border: "none",
+                borderRadius: "6px",
+              }}
+            >
+              {user}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};