@multiplatform.one/frappe-ui 6.7.0 → 7.0.0

package/src/commentActions.ts

@@ -0,0 +1,157 @@
+/**
+ * Optimistic comment writes for timeline surfaces (frappe-ui Timeline and
+ * the backoffice FormTimeline).
+ *
+ * Server-side parity ruling: the desk RPCs are KEPT as the transport,
+ * wrapped in engine mutations via `mutation.execute`. A plain live
+ * `create_doc` on Comment is NOT equivalent to
+ * `frappe.desk.form.utils.add_comment` — upstream, add_comment inserts
+ * with ignore_permissions (any user who can read the reference doc may
+ * comment, without Comment-create permission) and extracts inline images
+ * into Files. Losing either silently would be a regression, so the RPC
+ * stays; the engine supplies optimism, journaling, temp→real remap, and
+ * rollback around it. In fixture mode there is no desk endpoint, so the
+ * engine's default REST-shape path (FixtureDbModule) is used instead.
+ */
+import {
+  FrappeApp,
+  Operation,
+  getFrappeSyncModule,
+  type FrappeDoc,
+  type FrappeDocData,
+  type UseFrappeCollectionConfig,
+} from "@multiplatform.one/frappe";
+import { useMemo } from "react";
+
+type CommentDoc = FrappeDoc<FrappeDocData>;
+
+export interface AddCommentInput {
+  content: string;
+  /** Session user's email (`comment_email` on the Comment). */
+  email: string;
+  /** Display name (`comment_by`); falls back to the email. */
+  fullname?: string;
+}
+
+export interface FrappeCommentActions {
+  /**
+   * Inserts a comment optimistically: the row paints from the in-memory
+   * store immediately under a `local:` identity, the desk RPC runs in the
+   * background, and the ack remaps to the server-assigned name (the
+   * realtime echo then reconciles idempotently). On rejection the row is
+   * rolled back and the failure lands in the mutation ledger
+   * (`useFrappePendingMutations` + `SyncErrorNotice`).
+   */
+  addComment: (input: AddCommentInput) => Promise<void>;
+  /** Optimistic content edit via `frappe.desk.form.utils.update_comment`. */
+  updateComment: (commentName: string, content: string) => Promise<void>;
+  /** Optimistic delete via `frappe.client.delete`. */
+  deleteComment: (commentName: string) => Promise<void>;
+}
+
+function nowFrappeTimestamp(): string {
+  // Frappe timestamps are "YYYY-MM-DD HH:mm:ss.SSSSSS" naive datetimes.
+  return new Date().toISOString().replace("T", " ").replace("Z", "");
+}
+
+/**
+ * Builds the optimistic comment actions for one referenced document. The
+ * mutations run through the shared sync engine, so any mounted Comment
+ * collection (frappe-ui Timeline, backoffice FormTimeline) repaints
+ * optimistically without extra wiring.
+ */
+export function useFrappeCommentActions(
+  config: UseFrappeCollectionConfig | undefined,
+  doctype: string,
+  docname: string,
+): FrappeCommentActions {
+  return useMemo(() => {
+    const app =
+      config && !config.fixtures
+        ? new FrappeApp(config.baseURL, (config.auth ?? {}) as Record<string, unknown>)
+        : undefined;
+
+    const requireSync = () => {
+      const sync = getFrappeSyncModule(config);
+      if (!sync) throw new Error("Frappe connection is not available");
+      return sync;
+    };
+
+    const addComment = async ({ content, email, fullname }: AddCommentInput) => {
+      const sync = requireSync();
+      const doc: CommentDoc = {
+        doctype: "Comment",
+        name: `local:${crypto.randomUUID()}`,
+        comment_type: "Comment",
+        reference_doctype: doctype,
+        reference_name: docname,
+        content,
+        comment_email: email,
+        comment_by: fullname || email,
+        owner: email,
+        creation: nowFrappeTimestamp(),
+        modified: nowFrappeTimestamp(),
+      };
+      await sync.mutate({
+        mutationId: crypto.randomUUID(),
+        operation: Operation.Create,
+        doc,
+        execute: app
+          ? async () => {
+              const response = await app
+                .call()
+                .post<{ message?: CommentDoc }>("frappe.desk.form.utils.add_comment", {
+                  reference_doctype: doctype,
+                  reference_name: docname,
+                  content,
+                  comment_email: email,
+                  comment_by: fullname || email,
+                });
+              const payload = response?.payload;
+              const created = (payload?.message ?? payload) as CommentDoc | undefined;
+              if (!created?.name) throw new Error("add_comment returned no document");
+              return created;
+            }
+          : undefined,
+      });
+    };
+
+    const updateComment = async (commentName: string, content: string) => {
+      const sync = requireSync();
+      await sync.mutate({
+        mutationId: crypto.randomUUID(),
+        operation: Operation.Update,
+        doc: { doctype: "Comment", name: commentName, content } as CommentDoc,
+        execute: app
+          ? async () => {
+              await app.call().post("frappe.desk.form.utils.update_comment", {
+                name: commentName,
+                content,
+              });
+              // update_comment returns no document — the optimistic value
+              // stands until the realtime echo reconciles.
+            }
+          : undefined,
+      });
+    };
+
+    const deleteComment = async (commentName: string) => {
+      const sync = requireSync();
+      await sync.mutate({
+        mutationId: crypto.randomUUID(),
+        operation: Operation.Delete,
+        doc: { doctype: "Comment", name: commentName } as CommentDoc,
+        execute: app
+          ? async () => {
+              await app.call().post("frappe.client.delete", {
+                doctype: "Comment",
+                name: commentName,
+              });
+            }
+          : undefined,
+      });
+    };
+
+    return { addComment, updateComment, deleteComment };
+  }, [config?.baseURL, config?.fixtures, doctype, docname]);
+}

package/src/components/attachments.tsx

@@ -77,6 +77,8 @@ function AttachmentsBody({
         ? {
             baseURL: config.baseURL,
             socketPort: config.socketPort,
+            siteName: config.siteName,
+            socketBaseURL: config.socketBaseURL,
             auth: config.auth,
             syncOptions: config.syncOptions,
             fixtures: config.fixtures,

package/src/components/tags.tsx

@@ -28,8 +28,21 @@ export interface FrappeTagsProps extends Omit<TagsProps, "tags" | "suggestions">
 export function Tags({ doctype, docname, onAdd, onRemove, enableAdd, ...props }: FrappeTagsProps) {
   const config = useFrappeConfig();
 
+  // Forward the full socket target + engine options: the SyncModule cache
+  // keys on baseURL + socketPort/socketBaseURL/siteName, so dropping them
+  // here would split Tags onto a second SyncModule (own socket, own cache)
+  // whenever the provider sets them.
   const connectionConfig = config
-    ? { baseURL: config.baseURL, auth: config.auth, fixtures: config.fixtures }
+    ? {
+        baseURL: config.baseURL,
+        socketPort: config.socketPort,
+        siteName: config.siteName,
+        socketBaseURL: config.socketBaseURL,
+        auth: config.auth,
+        syncOptions: config.syncOptions,
+        socketOptions: config.socketOptions,
+        fixtures: config.fixtures,
+      }
     : undefined;
 
   const tagLinkFilters = useMemo<Array<[string, string, unknown]>>(

package/src/components/timeline.optimistic.spec.tsx

@@ -0,0 +1,106 @@
+// The comment repro kill, as a deferred-network spec: a comment submitted
+// through the Timeline composer must PAINT before the server ack resolves
+// (the whole point of the live client's in-memory store), then reconcile to
+// the server-assigned name without duplicating when the ack lands.
+import { InMemoryFixtureProvider, type FrappeDocData } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { FrappeProvider } from "../FrappeProvider";
+import { Timeline } from "./timeline";
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+afterEach(cleanup);
+
+/**
+ * Fixture provider whose creates hang until `release()` — the "server" is
+ * slow. Assigns a server-style name (drops the client's `local:` identity)
+ * so the temp→real remap path is exercised too.
+ */
+class DeferredCreateFixtureProvider extends InMemoryFixtureProvider {
+  private pendingCreates: Array<() => void> = [];
+  private serial = 0;
+
+  get pendingCount() {
+    return this.pendingCreates.length;
+  }
+
+  async createDoc<TDoc extends FrappeDocData>(doctype: string, doc: Partial<TDoc>): Promise<TDoc> {
+    await new Promise<void>((resolve) => this.pendingCreates.push(resolve));
+    const { name: _clientName, ...rest } = doc as Record<string, unknown>;
+    return super.createDoc(doctype, {
+      ...rest,
+      name: `CMT-${String(++this.serial).padStart(3, "0")}`,
+    } as Partial<TDoc>);
+  }
+
+  release() {
+    const pending = this.pendingCreates.splice(0);
+    for (const resolve of pending) resolve();
+  }
+}
+
+const makeFixtures = () =>
+  new DeferredCreateFixtureProvider({
+    Comment: [
+      {
+        name: "CMT-EXISTING",
+        doctype: "Comment",
+        comment_type: "Comment",
+        content: "already here",
+        comment_by: "Jane Doe",
+        comment_email: "jane@example.com",
+        reference_doctype: "Task",
+        reference_name: "TASK-001",
+        creation: "2024-01-01 10:00:00",
+        owner: "jane@example.com",
+      },
+    ],
+    Version: [],
+  });
+
+describe("Timeline optimistic comments (deferred network)", () => {
+  it("paints the comment row BEFORE the create ack resolves, then reconciles without duplicating", async () => {
+    const fixtures = makeFixtures();
+    renderWithProviders(
+      <FrappeProvider baseURL="https://bench.example.com" fixtures={fixtures}>
+        <Timeline doctype="Task" docname="TASK-001" />
+      </FrappeProvider>,
+    );
+
+    // Seeded comment arrives from the fixture store.
+    expect(await screen.findByText("already here")).toBeTruthy();
+
+    // Submit through the composer — no onAddComment prop: this is the
+    // default engine write path (previously a silent drop).
+    const input = screen.getByPlaceholderText("Add a comment...");
+    fireEvent.change(input, { target: { value: "optimistic!" } });
+    fireEvent.click(screen.getByRole("button", { name: /Comment/ }));
+
+    // THE REPRO KILL: the row paints while the server ack is still pending.
+    await waitFor(() => {
+      expect(screen.getByText("optimistic!")).toBeTruthy();
+    });
+    expect(fixtures.pendingCount).toBeGreaterThan(0);
+
+    // Ack lands: the local: identity remaps to the server name — the row
+    // stays painted and does not duplicate.
+    fixtures.release();
+    await waitFor(() => {
+      expect(fixtures.getData().Comment?.some((c) => c.content === "optimistic!")).toBe(true);
+    });
+    await waitFor(() => {
+      expect(screen.getAllByText("optimistic!")).toHaveLength(1);
+    });
+    expect(screen.getByText("already here")).toBeTruthy();
+  });
+});

package/src/components/timeline.tsx

@@ -4,8 +4,9 @@ import {
   type TimelineProps,
   type VersionChange,
 } from "@multiplatform.one/components";
-import { useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
-import { useCallback, useMemo } from "react";
+import { FrappeApp, useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import { useCallback, useMemo, useRef } from "react";
+import { useFrappeCommentActions } from "../commentActions";
 import { useFrappeConfig } from "../FrappeProvider";
 
 export interface FrappeComment {
@@ -124,6 +125,8 @@ export function Timeline({
     ? {
         baseURL: config.baseURL,
         socketPort: config.socketPort,
+        siteName: config.siteName,
+        socketBaseURL: config.socketBaseURL,
         auth: config.auth,
         syncOptions: config.syncOptions,
         socketOptions: config.socketOptions,
@@ -195,11 +198,40 @@ export function Timeline({
     );
   }, [commentsData, versionsData, showComments, showVersions, showAttachments, showAssignments]);
 
+  // Default write path: comments insert through the sync engine (optimistic
+  // paint, desk-RPC transport, rollback on rejection). Previously the
+  // composer only forwarded to the onAddComment prop, and consumers that
+  // didn't pass one (FrappeForm) dropped the comment silently.
+  const { addComment } = useFrappeCommentActions(connectionConfig, doctype, docname);
+  const sessionUserRef = useRef<string | undefined>(undefined);
+
+  const resolveSessionUser = useCallback(async (): Promise<string> => {
+    if (sessionUserRef.current) return sessionUserRef.current;
+    if (config && !config.fixtures) {
+      const app = new FrappeApp(config.baseURL, (config.auth ?? {}) as Record<string, unknown>);
+      sessionUserRef.current = await app.auth().getLoggedInUser();
+    } else {
+      // Fixture/story mode has no session endpoint.
+      sessionUserRef.current = "Administrator";
+    }
+    return sessionUserRef.current;
+  }, [config?.baseURL, config?.fixtures]);
+
   const handleAddComment = useCallback(
     (content: string) => {
-      onAddComment?.(content);
+      if (onAddComment) {
+        onAddComment(content);
+        return;
+      }
+      void (async () => {
+        const email = await resolveSessionUser();
+        await addComment({ content, email });
+      })().catch(() => {
+        // Rejection already rolled back and landed in the mutation ledger
+        // (useFrappePendingMutations / SyncErrorNotice at the surface).
+      });
     },
-    [onAddComment],
+    [onAddComment, addComment, resolveSessionUser],
   );
 
   // The base Timeline follows the `timestampStyle` house knob (default

package/src/desk/DeskFormSidebar.tsx

@@ -56,6 +56,8 @@ export function DeskFormSidebar({ doctype, name }: DeskFormSidebarProps) {
         ? {
             baseURL: config.baseURL,
             socketPort: config.socketPort,
+            siteName: config.siteName,
+            socketBaseURL: config.socketBaseURL,
             auth: config.auth,
             syncOptions: config.syncOptions,
             fixtures: config.fixtures,

package/src/fieldRegistry.ts

@@ -1154,6 +1154,8 @@ function TableAdapter(props: FieldRenderProps) {
     ? {
         baseURL: config.baseURL,
         socketPort: config.socketPort,
+        siteName: config.siteName,
+        socketBaseURL: config.socketBaseURL,
         auth: config.auth,
         syncOptions: config.syncOptions,
         fixtures: config.fixtures,