@multiplatform.one/frappe 7.6.3 → 7.7.1

package/src/devtools/plugin.stories.tsx

@@ -0,0 +1,77 @@
+import { useState } from "react";
+import { isWeb, Text, YStack } from "tamagui";
+import {
+  type ToDo,
+  toDoFixtureData,
+  useSeededJournal,
+  useStoryConfig,
+} from "../../tests/storyFixtures";
+import { useFrappeCollection } from "../frappeReact";
+import { useLiveQuery } from "../useLiveQuery";
+import { frappeDevtoolsPlugin } from "./plugin";
+
+export default {
+  title: "Frappe/frappeDevtoolsPlugin",
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "The plugin factory core hands to the TanStack Devtools shell (MPO-8): frappeDevtoolsPlugin(syncModule) returns { id: 'frappe', name: 'Frappe', render }. The shell lists id/name in its tab strip and calls render(hostElement, { theme }) when the tab opens; render returns the FrappeDevtoolsPanel element bound to that SyncModule. The story calls render the same way, with a real host element and the shell's theme prop. Network-hermetic (G-15/D-05): the SyncModule runs over an InMemoryFixtureProvider with one ToDo subscription and a seeded journal; nothing is fetched. On native there is no shell, so the story shows what the shell would list.",
+      },
+    },
+  },
+};
+
+function PluginHost({ theme }: { theme: "light" | "dark" }) {
+  const config = useStoryConfig(toDoFixtureData());
+  const collection = useFrappeCollection<ToDo>(config, "ToDo");
+  const { isReady } = useLiveQuery(
+    (q) => (collection ? q.from({ todo: collection }) : null),
+    [collection],
+  );
+  const syncModule = useSeededJournal(config, Boolean(isReady));
+  const [host, setHost] = useState<HTMLDivElement | null>(null);
+  if (!syncModule) {
+    return (
+      <Text fontSize="$2">
+        No SyncModule: getFrappeSyncModule() returns undefined during server rendering.
+      </Text>
+    );
+  }
+  const plugin = frappeDevtoolsPlugin(syncModule);
+  return (
+    <YStack gap="$2">
+      <Text fontSize="$2" data-testid="plugin-identity">
+        plugin.id = {plugin.id} · plugin.name = {plugin.name} · theme = {theme}
+      </Text>
+      {isWeb ? (
+        <div
+          ref={setHost}
+          data-testid="devtools-plugin-host"
+          style={{
+            height: 440,
+            borderRadius: 6,
+            overflow: "hidden",
+            border: "1px solid rgba(128, 128, 128, 0.35)",
+          }}
+        >
+          {host ? plugin.render(host, { theme }) : null}
+        </div>
+      ) : (
+        <Text fontSize="$2" color="$color10">
+          render() returns the DOM panel for the TanStack Devtools shell, which only exists on web.
+          The id and name above are what the shell lists.
+        </Text>
+      )}
+    </YStack>
+  );
+}
+
+/** render(host, { theme: "light" }), the way the shell opens the tab. */
+export const Main = () => <PluginHost theme="light" />;
+Main.storyName = "Main";
+
+/** The same plugin rendered with the shell's dark theme prop. */
+export const Dark = () => <PluginHost theme="dark" />;

package/src/fixtureDb.spec.ts

@@ -0,0 +1,126 @@
+/**
+ * FixtureDbModule cursor paging.
+ *
+ * Fixture mode is what makes the frappe stories network-hermetic (G-15/D-05),
+ * so it has to page the same way the HTTP path does. It did not: `getDocList`
+ * forwarded fields / filters / orderBy / limitStart / limit and dropped
+ * `cursor` on the floor, so every cursor-paged fetch returned page ONE again.
+ * VirtualPageManager appends what it gets, so a fixture-backed
+ * useFrappeInfiniteList grew [1..10, 1..10] and React logged a duplicate-key
+ * error for every row of the first page (MPO-197).
+ */
+import { describe, expect, it } from "vitest";
+import { FixtureDbModule } from "./fixtureDb";
+import { InMemoryFixtureProvider } from "./fixtures";
+import { Order } from "./sync/types";
+
+function pad(n: number): string {
+  return String(n).padStart(4, "0");
+}
+
+function todos(count: number) {
+  return Array.from({ length: count }, (_, i) => ({
+    name: `TODO-${pad(i + 1)}`,
+    doctype: "ToDo",
+    description: `row ${i + 1}`,
+    status: i % 2 === 0 ? "Open" : "Working",
+  }));
+}
+
+function db(count = 25) {
+  return new FixtureDbModule(new InMemoryFixtureProvider({ ToDo: todos(count) }));
+}
+
+const byName = { field: "name", order: Order.Asc };
+
+describe("FixtureDbModule.getDocList cursor paging", () => {
+  it("with no cursor it returns the first page", async () => {
+    const rows = await db().getDocList("ToDo", { orderBy: byName, limit: 10 });
+    expect(rows.map((r) => r.name)).toEqual(todos(10).map((r) => r.name));
+  });
+
+  it("a cursor starts the page AFTER that document", async () => {
+    const rows = await db().getDocList("ToDo", {
+      orderBy: byName,
+      limit: 10,
+      cursor: "TODO-0010",
+    });
+    expect(rows[0]?.name).toBe("TODO-0011");
+    expect(rows).toHaveLength(10);
+    expect(rows.at(-1)?.name).toBe("TODO-0020");
+  });
+
+  it("paging the whole list by cursor yields every row exactly once", async () => {
+    const module = db(25);
+    const seen: string[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < 5; page++) {
+      const rows = await module.getDocList("ToDo", { orderBy: byName, limit: 10, cursor });
+      if (rows.length === 0) break;
+      seen.push(...rows.map((r) => String(r.name)));
+      cursor = String(rows[rows.length - 1].name);
+    }
+    expect(seen).toHaveLength(25);
+    expect(new Set(seen).size).toBe(25);
+    expect(seen[0]).toBe("TODO-0001");
+    expect(seen.at(-1)).toBe("TODO-0025");
+  });
+
+  it("the last page is short and the one after it is empty", async () => {
+    const module = db(25);
+    const tail = await module.getDocList("ToDo", {
+      orderBy: byName,
+      limit: 10,
+      cursor: "TODO-0020",
+    });
+    expect(tail).toHaveLength(5);
+    const past = await module.getDocList("ToDo", {
+      orderBy: byName,
+      limit: 10,
+      cursor: "TODO-0025",
+    });
+    expect(past).toHaveLength(0);
+  });
+
+  it("a cursor naming a document that is not there falls back to the first page", async () => {
+    const rows = await db().getDocList("ToDo", { orderBy: byName, limit: 5, cursor: "NOPE" });
+    expect(rows[0]?.name).toBe("TODO-0001");
+  });
+
+  it("the cursor is resolved against the FILTERED order, not the whole doctype", async () => {
+    const rows = await db(10).getDocList("ToDo", {
+      orderBy: byName,
+      filters: { status: "Open" },
+      limit: 2,
+      cursor: "TODO-0003",
+    });
+    // Open rows are the odd names; after TODO-0003 come TODO-0005 and TODO-0007.
+    expect(rows.map((r) => r.name)).toEqual(["TODO-0005", "TODO-0007"]);
+  });
+
+  it("an explicit limitStart wins over the cursor (that caller pages by offset)", async () => {
+    const rows = await db().getDocList("ToDo", {
+      orderBy: byName,
+      limit: 3,
+      limitStart: 0,
+      cursor: "TODO-0010",
+    });
+    expect(rows[0]?.name).toBe("TODO-0001");
+  });
+
+  it("getListWithCursor and getDocList agree on where a cursor lands", async () => {
+    const module = db();
+    const viaList = await module.getDocList("ToDo", {
+      orderBy: byName,
+      limit: 5,
+      cursor: "TODO-0005",
+    });
+    const viaCursor = await module.getListWithCursor({
+      doctype: "ToDo",
+      orderBy: byName,
+      limit: 5,
+      cursor: "TODO-0005",
+    });
+    expect(viaList.map((r) => r.name)).toEqual(viaCursor.data.map((r) => r.name));
+  });
+});

package/src/fixtureDb.ts

@@ -68,6 +68,22 @@ export class FixtureDbModule {
     if (typeof options.limitStart === "number") fixtureOptions.limitStart = options.limitStart;
     if (options.limit != null) fixtureOptions.limit = options.limit;
 
+    // Honour `cursor` the way getListWithCursor does. Dropping it silently
+    // made every cursor-paged fetch return page ONE again, and
+    // VirtualPageManager.fetchMorePages appends what it gets without
+    // de-duplicating — so a fixture-backed useFrappeInfiniteList grew
+    // [1..10, 1..10] and React logged a duplicate-key error per row
+    // (Frappe/useFrappeInfiniteList "Sentinel Auto Load", MPO-197).
+    // An explicit limitStart wins: that caller is paging by offset already.
+    if (options.cursor && typeof options.limitStart !== "number") {
+      const ordered = await this.fixtures.getList(doctype, {
+        filters: options.filters as any,
+        orderBy: options.orderBy ? normalizeOrderBy(options.orderBy) : undefined,
+      } as any);
+      const cursorIdx = ordered.findIndex((d: any) => d.name === options.cursor);
+      if (cursorIdx >= 0) fixtureOptions.limitStart = cursorIdx + 1;
+    }
+
     const docs = await this.fixtures.getList<Data>(doctype, fixtureOptions as any);
     return docs.map((d) => ({ ...d, doctype, name: (d as any).name }) as FrappeDoc<Data>);
   }

package/src/sync/virtualPageManager.spec.ts

@@ -822,4 +822,66 @@ describe("VirtualPageManager", () => {
       expect((virtualPageManager as any).shouldLimitCacheSize(subscription)).toBe(true);
     });
   });
+
+  /**
+   * docIds is a list of document NAMES, so a name can appear at most once.
+   * fetchMorePages used to append whatever came back without checking, which
+   * two racing loadMore() calls (the useFrappeInfiniteList sentinel fires
+   * twice before isLoadingMore settles) turned into the same page twice —
+   * React then logs a duplicate-key error per row (MPO-197).
+   */
+  describe("progressive cache stays a set of unique names", () => {
+    async function subscribeTen(id: string) {
+      await virtualPageManager.initializeSubscription(id, {
+        doctype: "TestDoc",
+        limit: 10,
+        orderBy: { field: "value", order: Order.Asc },
+      });
+      return virtualPageManager.getSubscription(id)!;
+    }
+
+    it("re-fetching from the same cursor does not duplicate a page", async () => {
+      const subscription = await subscribeTen("sub-dedupe-1");
+      // Rewind to one page, as a fresh subscribe leaves it, and point the
+      // cursor at the last row of that page.
+      setCache(subscription, {
+        docIds: mockDocs.slice(0, 10).map((d) => d.name),
+        nextCursor: "doc-9",
+        hasMore: true,
+      });
+      await virtualPageManager.getNextBatch("sub-dedupe-1", "doc-9", 10);
+      const first = [...getCache(subscription).docIds];
+      expect(new Set(first).size).toBe(first.length);
+
+      // A second call from the SAME cursor: the engine must not append the
+      // rows it already holds.
+      setCache(subscription, { nextCursor: "doc-9", hasMore: true });
+      await virtualPageManager.getNextBatch("sub-dedupe-1", "doc-9", 10);
+      const after = getCache(subscription).docIds;
+      expect(new Set(after).size).toBe(after.length);
+    });
+
+    it("two concurrent getNextBatch calls leave no duplicate ids", async () => {
+      const subscription = await subscribeTen("sub-dedupe-2");
+      setCache(subscription, {
+        docIds: mockDocs.slice(0, 10).map((d) => d.name),
+        nextCursor: "doc-9",
+        hasMore: true,
+      });
+      await Promise.all([
+        virtualPageManager.getNextBatch("sub-dedupe-2", "doc-9", 10),
+        virtualPageManager.getNextBatch("sub-dedupe-2", "doc-9", 10),
+      ]);
+      const ids = getCache(subscription).docIds;
+      expect(new Set(ids).size).toBe(ids.length);
+    });
+
+    it("de-duplicating never reorders or drops the rows already held", async () => {
+      const subscription = await subscribeTen("sub-dedupe-3");
+      const head = mockDocs.slice(0, 10).map((d) => d.name);
+      setCache(subscription, { docIds: [...head], nextCursor: "doc-9", hasMore: true });
+      await virtualPageManager.getNextBatch("sub-dedupe-3", "doc-9", 10);
+      expect(getCache(subscription).docIds.slice(0, 10)).toEqual(head);
+    });
+  });
 });

package/src/sync/virtualPageManager.ts

@@ -848,9 +848,15 @@ export class VirtualPageManager<Data extends FrappeDocData = FrappeDocData> {
       hasMore = response.length === fetchSize && fetchedDocs.length < neededCount;
     }
 
-    // Append to progressive cache
-    const newDocIds = fetchedDocs.map((doc) => doc.name);
+    // Append to progressive cache. docIds is a list of document NAMES and a
+    // name can only appear once, so filter out any already present: two
+    // loadMore() calls that race past the isLoadingMore guard (the sentinel
+    // path fires twice before the state settles) both fetch from the same
+    // cursor, and a blind append put the same page in twice — which React
+    // reports as a duplicate-key error per row (MPO-197).
     const currentDocIds = subscription.getProgressiveCache().docIds;
+    const seen = new Set(currentDocIds);
+    const newDocIds = fetchedDocs.map((doc) => doc.name).filter((name) => !seen.has(name));
     const updatedDocIds = [...currentDocIds, ...newDocIds];
     subscription.updateProgressiveCache({
       docIds: updatedDocIds,

package/src/useFrappeCollection.stories.tsx

@@ -0,0 +1,166 @@
+import { useState } from "react";
+import { Button, Text, XStack, YStack } from "tamagui";
+import {
+  type ToDo,
+  type ToDoStatus,
+  toDoFixtureData,
+  useStoryConfig,
+} from "../tests/storyFixtures";
+import type { FrappeCollectionOptionsConfig } from "./collection";
+import { type UseFrappeCollectionConfig, useFrappeCollection } from "./frappeReact";
+import { Order } from "./sync/types";
+import { useLiveQuery } from "./useLiveQuery";
+
+export default {
+  title: "Frappe/useFrappeCollection",
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "The SDK's main React entry point: useFrappeCollection(config, doctype, options) returns a TanStack DB collection kept in sync by the SyncModule, and useLiveQuery reads it. Writes go through collection.insert / update / delete, apply optimistically, and are journaled by the engine. The probe prints the collection status, the live-query state and the rows, with buttons that write through the collection. Network-hermetic (G-15/D-05): config.fixtures is an InMemoryFixtureProvider, so the same SyncModule pipeline runs over in-memory documents and nothing is fetched.",
+      },
+    },
+  },
+};
+
+type ProbeOptions = Omit<FrappeCollectionOptionsConfig<ToDo>, "sync">;
+
+interface ProbeProps {
+  config: UseFrappeCollectionConfig | undefined;
+  doctype?: string;
+  options?: ProbeOptions;
+}
+
+const nextStatus: Record<ToDoStatus, ToDoStatus> = {
+  Open: "Working",
+  Working: "Completed",
+  Completed: "Open",
+  Cancelled: "Open",
+};
+
+function swallow(tx: { isPersisted: { promise: Promise<unknown> } }) {
+  tx.isPersisted.promise.catch(() => {});
+}
+
+function CollectionProbe({ config, doctype = "ToDo", options }: ProbeProps) {
+  const collection = useFrappeCollection<ToDo>(config, doctype, options);
+  const { data, isReady, isLoading } = useLiveQuery(
+    (q) => (collection ? q.from({ todo: collection }) : null),
+    [collection],
+  );
+  const [inserted, setInserted] = useState(0);
+  const rows = (data as ToDo[] | undefined) ?? [];
+
+  const insert = () => {
+    if (!collection) return;
+    const n = inserted + 1;
+    setInserted(n);
+    swallow(
+      collection.insert({
+        name: `TODO-NEW-${String(n).padStart(3, "0")}`,
+        doctype,
+        description: `Added from the story (#${n})`,
+        status: "Open",
+        priority: "Medium",
+        date: "2026-09-05",
+        modified: "2026-09-05 12:00:00",
+      }),
+    );
+  };
+  const advanceFirst = () => {
+    const first = rows[0];
+    if (!collection || !first) return;
+    swallow(
+      collection.update(first.name, (draft) => {
+        draft.status = nextStatus[first.status];
+      }),
+    );
+  };
+  const removeLast = () => {
+    const last = rows[rows.length - 1];
+    if (!collection || !last) return;
+    swallow(collection.delete(last.name));
+  };
+
+  return (
+    <YStack gap="$3" data-testid="collection-probe">
+      <Text fontWeight="600">
+        useFrappeCollection(config, "{doctype}"{options ? ", options" : ""}) + useLiveQuery
+      </Text>
+      <Text fontSize="$2" data-testid="collection-status">
+        collection: {collection ? collection.status : "(undefined, no config)"} · live query:{" "}
+        {isLoading ? "loading" : isReady ? "ready" : "idle"} · rows: {rows.length}
+      </Text>
+      <XStack gap="$2" flexWrap="wrap">
+        <Button size="$2" onPress={insert} disabled={!collection}>
+          Insert
+        </Button>
+        <Button size="$2" onPress={advanceFirst} disabled={!rows.length}>
+          Advance first row's status
+        </Button>
+        <Button size="$2" onPress={removeLast} disabled={!rows.length}>
+          Delete last row
+        </Button>
+      </XStack>
+      <YStack gap="$1">
+        {rows.map((row) => (
+          <XStack key={row.name} gap="$3" alignItems="center" data-testid={`row-${row.name}`}>
+            <Text fontSize="$2" width={120}>
+              {row.name}
+            </Text>
+            <Text fontSize="$2" flex={1}>
+              {row.description}
+            </Text>
+            <Text fontSize="$2" width={90}>
+              {row.status}
+            </Text>
+            <Text fontSize="$2" width={70}>
+              {row.priority}
+            </Text>
+            <Text fontSize="$2" width={90}>
+              {row.date}
+            </Text>
+          </XStack>
+        ))}
+        {collection && isReady && rows.length === 0 ? (
+          <Text fontSize="$2" color="$color10">
+            No documents match.
+          </Text>
+        ) : null}
+      </YStack>
+    </YStack>
+  );
+}
+
+/** Eight ToDos from fixtures; insert, update and delete through the collection. */
+export const Main = () => {
+  const config = useStoryConfig(toDoFixtureData(8, { scripted: false }));
+  return <CollectionProbe config={config} />;
+};
+Main.storyName = "Main";
+
+/** filters, orderBy and limit are passed to the subscription: only Open rows, by date, at most four. */
+export const Filtered = () => {
+  const config = useStoryConfig(toDoFixtureData(12, { scripted: false }));
+  return (
+    <CollectionProbe
+      config={config}
+      options={{
+        filters: [["status", "=", "Open"]],
+        orderBy: { field: "date", order: Order.Asc },
+        limit: 4,
+      }}
+    />
+  );
+};
+
+/** A doctype with no fixture rows: the collection still reaches ready, with zero rows. */
+export const EmptyDoctype = () => {
+  const config = useStoryConfig(toDoFixtureData(8, { scripted: false }));
+  return <CollectionProbe config={config} doctype="Note" />;
+};
+
+/** No config (no provider above the consumer): the hook returns undefined and nothing syncs. */
+export const WithoutConfig = () => <CollectionProbe config={undefined} />;

package/src/useFrappeInfiniteList.stories.tsx

@@ -0,0 +1,104 @@
+import { Button, isWeb, Text, XStack, YStack } from "tamagui";
+import { type ToDo, toDoFixtureData, useStoryConfig } from "../tests/storyFixtures";
+import { type UseFrappeCollectionConfig, useFrappeInfiniteList } from "./frappeReact";
+import { Order } from "./sync/types";
+
+export default {
+  title: "Frappe/useFrappeInfiniteList",
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "Cursor-paged list over a progressive SyncModule subscription: items, hasMore, isLoading / isLoadingMore, loadMore(), refresh(), and a sentinelRef that loads the next page when its element scrolls into view (IntersectionObserver, web only). The probe pages 57 fixture ToDos ten at a time. Network-hermetic (G-15/D-05): config.fixtures is an InMemoryFixtureProvider and the cursor path runs through FixtureDbModule.getListWithCursor, so nothing is fetched.",
+      },
+    },
+  },
+};
+
+interface ProbeProps {
+  config: UseFrappeCollectionConfig | undefined;
+  pageSize: number;
+  /** Attach sentinelRef to a trailing element so pages load as you scroll (web only). */
+  sentinel?: boolean;
+}
+
+function InfiniteProbe({ config, pageSize, sentinel = false }: ProbeProps) {
+  const list = useFrappeInfiniteList<ToDo>({
+    config,
+    doctype: "ToDo",
+    pageSize,
+    orderBy: { field: "name", order: Order.Asc },
+  });
+  return (
+    <YStack gap="$3" data-testid="infinite-probe">
+      <Text fontWeight="600">
+        useFrappeInfiniteList({`{ doctype: "ToDo", pageSize: ${pageSize} }`})
+      </Text>
+      <Text fontSize="$2" data-testid="infinite-status">
+        loaded {list.totalLoaded} · hasMore {String(list.hasMore)} · isLoading{" "}
+        {String(list.isLoading)} · isLoadingMore {String(list.isLoadingMore)}
+        {list.error ? ` · error: ${list.error.message}` : ""}
+        {!config ? " · no config, so nothing subscribes" : ""}
+      </Text>
+      <XStack gap="$2" flexWrap="wrap">
+        <Button
+          size="$2"
+          onPress={() => void list.loadMore()}
+          disabled={!list.hasMore || list.isLoadingMore || !config}
+        >
+          Load more
+        </Button>
+        <Button size="$2" onPress={() => void list.refresh()} disabled={!config}>
+          Refresh
+        </Button>
+      </XStack>
+      <YStack gap="$1">
+        {list.items.map((row) => (
+          <XStack key={row.name} gap="$3" alignItems="center" data-testid={`row-${row.name}`}>
+            <Text fontSize="$2" width={120}>
+              {row.name}
+            </Text>
+            <Text fontSize="$2" flex={1}>
+              {row.description}
+            </Text>
+            <Text fontSize="$2" width={90}>
+              {row.status}
+            </Text>
+          </XStack>
+        ))}
+        {sentinel && isWeb ? (
+          <div ref={list.sentinelRef} data-testid="infinite-sentinel" style={{ height: 1 }} />
+        ) : null}
+        {!list.hasMore && list.items.length > 0 ? (
+          <Text fontSize="$2" color="$color10">
+            End of list.
+          </Text>
+        ) : null}
+      </YStack>
+    </YStack>
+  );
+}
+
+/** 57 rows, ten per page; Load more walks the cursor until hasMore is false. */
+export const Main = () => {
+  const config = useStoryConfig(toDoFixtureData(57, { scripted: false }));
+  return <InfiniteProbe config={config} pageSize={10} />;
+};
+Main.storyName = "Main";
+
+/** Same list with sentinelRef attached: scroll to the bottom and the next page loads by itself (web). */
+export const SentinelAutoLoad = () => {
+  const config = useStoryConfig(toDoFixtureData(57, { scripted: false }));
+  return <InfiniteProbe config={config} pageSize={10} sentinel />;
+};
+
+/** Fewer rows than one page: hasMore is false after the first load. */
+export const SinglePage = () => {
+  const config = useStoryConfig(toDoFixtureData(8, { scripted: false }));
+  return <InfiniteProbe config={config} pageSize={20} />;
+};
+
+/** No config: the hook stays in its initial loading state and never subscribes. */
+export const WithoutConfig = () => <InfiniteProbe config={undefined} pageSize={10} />;