@multiplatform.one/frappe-ui 7.7.6 → 7.8.0

package/src/frappeViews.designLaw.spec.ts

@@ -55,14 +55,15 @@ describe("Frappe view adapters — design-law 100%", () => {
     expect(source).toMatch(/from "@multiplatform.one\/components"/);
   });
 
-  it("FrappeGantt action banners use form ramps and do not steal Desk assembly", () => {
+  it("FrappeGantt action errors use Alert and keep the adapter boundary", () => {
     const source = read("FrappeGantt.tsx");
-    expect(source).toContain("formCommonColors");
+    expect(source).toMatch(/import \{[^}]*Alert[^}]*\} from "@multiplatform.one\/components"/);
+    expect(source).toMatch(/<Alert\b[^>]*intent="error"/);
     expect(source).toContain("containerRadius");
+    expect(source).not.toContain("knobProps.borderRadius");
     expect(source).not.toMatch(/fontSize=\{knobProps\.sizeToken\}/);
-    expect(source).not.toContain('color="$red11"');
-    expect(source).toContain("BACKOFFICE_VIEWS");
-    expect(source).toContain("MPO-14");
+    expect(source).not.toMatch(/\$red\d+/);
+    expect(source).not.toMatch(/from ["'](?:@multiplatform\.one\/backoffice|\.\/desk\/)/);
   });
 
   it("FrappeReportView uses the house Button and label fragments (LC-54)", () => {
@@ -81,12 +82,15 @@ describe("Frappe view adapters — design-law 100%", () => {
     expect(source).toContain("formCommonColors");
     expect(source).not.toMatch(/fontWeight="600"|fontWeight="500"/);
     expect(source).toContain('fontWeight="400"');
-    expect(source).toContain("outlined");
+    expect(source).not.toMatch(/<Button\b[^>]*\b(?:controlFill|backgroundColor|borderColor)=/);
   });
 
   it("FrappeTreeView empty chrome is EmptyState and labels use the label fragment", () => {
     const source = read("FrappeTreeView.tsx");
-    expect(source).toContain("EmptyState");
+    expect(source).toMatch(/import \{[^}]*EmptyState[^}]*\} from "@multiplatform.one\/components"/);
+    expect(source).toContain("<EmptyState");
+    expect(source).toContain("useGlyphColor(formCommonColors.muted)");
+    expect(source).not.toMatch(/<TreeStructureIcon\b[^>]*color=\{formCommonColors\./);
     expect(source).not.toMatch(/size=\{48\}/);
     expect(source).toContain("knobProps.label");
     expect(source).not.toMatch(/fontSize=\{display === "compressed" \? 12 : 14\}/);

package/src/index.ts

@@ -120,6 +120,19 @@ export {
   type FrappeChartDataSource,
 } from "./FrappeChartCard";
 
+// The composed doctype read (MPO-251) — the supported way to get rows out of
+// a doctype when the panel shape has no shipped component. FrappeTable and
+// the other live views read through it, so there is one implementation.
+export {
+  useFrappeRows,
+  useFrappeConnection,
+  DEFAULT_FRAPPE_ROWS_LIMIT,
+  type FrappeRowsConnection,
+  type FrappeRowsMessages,
+  type UseFrappeRowsOptions,
+  type UseFrappeRowsResult,
+} from "./useFrappeRows";
+
 export {
   useFrappeAggregate,
   type FrappeAggregateConnection,

package/src/schemaForm/index.tsx

@@ -17,9 +17,10 @@ import {
   type RequiredMarkStrategy,
 } from "@multiplatform.one/forms";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Card } from "@multiplatform.one/components";
 import React, { useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import { Card, Text, XStack, YStack } from "tamagui";
+import { Text, XStack, YStack } from "tamagui";
 
 import { compileDependsOn } from "../dependsOn";
 import { Heading, type HeadingLevel } from "../fields/Heading";
@@ -353,13 +354,12 @@ function SchemaFormSectionCard({ section, headingLevel, renderField }: SchemaFor
 
   return (
     <Card
-      borderWidth={hideBorder ? 0 : 1}
-      borderColor="$borderColor"
-      size={knobProps.sizeToken}
-      backgroundColor={hideBorder ? "transparent" : undefined}
+      data-mpo-schema-form-card=""
+      data-mpo-schema-form-borderless={hideBorder ? "" : undefined}
+      {...(hideBorder ? { borderWidth: 0, backgroundColor: "transparent" } : {})}
     >
       {(section.label || section.description) && (
-        <Card.Header {...knobProps.panelPadding}>
+        <Card.Header>
           {section.label ? (
             <Heading
               label={section.label}
@@ -380,7 +380,6 @@ function SchemaFormSectionCard({ section, headingLevel, renderField }: SchemaFor
       {/* Kept mounted while collapsed (display none) so field state and the
           collapse target survive toggles — matches desk's CSS hide. */}
       <Card.Footer
-        {...knobProps.panelPadding}
         display={effectiveCollapsed ? "none" : undefined}
         aria-hidden={effectiveCollapsed || undefined}
       >

package/src/shared/devWarn.ts

@@ -0,0 +1,42 @@
+/**
+ * Package-local DEV guardrails for frappe-ui, warned under a `[frappe-ui]`
+ * prefix.
+ *
+ * The canonical catalog is `devWarn` in `@multiplatform.one/theme`, whose
+ * `DevWarnCode` union is closed over design-guardrail codes. Live-data
+ * misconfiguration is a frappe-ui concern rather than a design-law one, so
+ * it warns from here, the same way AsyncBoundary keeps its own.
+ *
+ * No-ops when `NODE_ENV === "production"`, and each key warns once per
+ * process so a re-render never repeats a line.
+ */
+
+export type FrappeDevWarnCode = "kpi-datasource-without-baseurl";
+
+export type FrappeDevWarnDetail = {
+  component?: string;
+  id?: string;
+  doctype?: string;
+  suggest?: string;
+};
+
+const seen = new Set<string>();
+
+export function frappeDevWarn(code: FrappeDevWarnCode, detail: FrappeDevWarnDetail = {}): void {
+  if (process.env.NODE_ENV === "production") return;
+  const key = [code, detail.component ?? "", detail.id ?? "", detail.doctype ?? ""].join(":");
+  if (seen.has(key)) return;
+  seen.add(key);
+  const bits = [
+    detail.component ? `component=${detail.component}` : undefined,
+    detail.id ? `id=${detail.id}` : undefined,
+    detail.doctype ? `doctype=${detail.doctype}` : undefined,
+    detail.suggest ? `suggest=${detail.suggest}` : undefined,
+  ].filter(Boolean);
+  console.warn(`[frappe-ui] ${code}${bits.length ? ` (${bits.join(", ")})` : ""}`);
+}
+
+/** @internal test helper */
+export function __resetFrappeDevWarnSeen(): void {
+  seen.clear();
+}

package/src/useFrappeAggregate.ts

@@ -41,7 +41,8 @@ export type FrappeAggregateOperation = "count" | "sum" | "avg" | "min" | "max";
 
 /** Connection shape shared with the other frappe-ui widgets. */
 export interface FrappeAggregateConnection {
-  baseURL: string;
+  /** Required unless `fixtures` is set (see FrappeConfig.baseURL). */
+  baseURL?: string;
   /** False keeps HTTP reads without realtime subscriptions. */
   realtime?: boolean;
   socketPort?: number;
@@ -97,18 +98,18 @@ const DEFAULT_DEBOUNCE_MS = 300;
 // One REST client per connection — widgets sharing a bench share it.
 const dbCache = new Map<string, DbModule>();
 
-function getDb(connection: FrappeAggregateConnection): DbModule {
-  const key = `${connection.baseURL}:${connection.auth?.token ?? ""}:${connection.auth?.type ?? ""}`;
+function getDb(baseURL: string, auth: FrappeAggregateConnection["auth"]): DbModule {
+  const key = `${baseURL}:${auth?.token ?? ""}:${auth?.type ?? ""}`;
   let db = dbCache.get(key);
   if (!db) {
-    const authConfig: AuthConfig | undefined = connection.auth
+    const authConfig: AuthConfig | undefined = auth
       ? {
-          useToken: connection.auth.useToken,
-          token: connection.auth.token,
-          type: connection.auth.type as AuthConfig["type"],
+          useToken: auth.useToken,
+          token: auth.token,
+          type: auth.type as AuthConfig["type"],
         }
       : undefined;
-    db = new DbModule(new HttpClient(connection.baseURL, authConfig));
+    db = new DbModule(new HttpClient(baseURL, authConfig));
     dbCache.set(key, db);
   }
   return db;
@@ -271,9 +272,14 @@ export function useFrappeAggregate(
     if (!conn || !currentSpec.doctype) return;
     const seq = ++fetchSeq.current;
     try {
-      const result = conn.fixtures
-        ? await fetchFixtureAggregate(conn.fixtures, currentSpec)
-        : await fetchLiveAggregate(getDb(conn), currentSpec);
+      let result: AggregateData;
+      if (conn.fixtures) {
+        result = await fetchFixtureAggregate(conn.fixtures, currentSpec);
+      } else if (conn.baseURL) {
+        result = await fetchLiveAggregate(getDb(conn.baseURL, conn.auth), currentSpec);
+      } else {
+        throw new Error("useFrappeAggregate requires a connection with baseURL or fixtures");
+      }
       if (seq !== fetchSeq.current) return; // stale response — a newer fetch won
       setData(result);
       setError(undefined);

package/src/useFrappeFacets.ts

@@ -78,7 +78,8 @@ export interface FrappeFacetState {
 
 /** Connection shape shared with the other frappe-ui widgets. */
 export interface FrappeFacetsConnection {
-  baseURL: string;
+  /** Required unless `fixtures` is set (see FrappeConfig.baseURL). */
+  baseURL?: string;
   auth?: { useToken?: boolean; token?: string | (() => string | Promise<string>); type?: string };
   fixtures?: FixtureProvider;
 }
@@ -169,18 +170,18 @@ export function scrubUserFacetRows(
 // One RPC client per connection — facets sharing a bench share it.
 const callCache = new Map<string, CallModule>();
 
-function getCall(connection: FrappeFacetsConnection): CallModule {
-  const key = `${connection.baseURL}:${connection.auth?.token ?? ""}:${connection.auth?.type ?? ""}`;
+function getCall(baseURL: string, auth: FrappeFacetsConnection["auth"]): CallModule {
+  const key = `${baseURL}:${auth?.token ?? ""}:${auth?.type ?? ""}`;
   let call = callCache.get(key);
   if (!call) {
-    const authConfig: AuthConfig | undefined = connection.auth
+    const authConfig: AuthConfig | undefined = auth
       ? {
-          useToken: connection.auth.useToken,
-          token: connection.auth.token,
-          type: connection.auth.type as AuthConfig["type"],
+          useToken: auth.useToken,
+          token: auth.token,
+          type: auth.type as AuthConfig["type"],
         }
       : undefined;
-    call = new CallModule(new HttpClient(connection.baseURL, authConfig));
+    call = new CallModule(new HttpClient(baseURL, authConfig));
     callCache.set(key, call);
   }
   return call;
@@ -439,7 +440,9 @@ export function useFrappeFacets(
   useEffect(() => {
     if (!enabled) return;
     const conn = connectionRef.current;
-    if (!conn) return;
+    // Neither a corpus nor a bench can answer, so stay idle instead of
+    // entering a loading state nothing will ever resolve.
+    if (!conn || (!conn.fixtures && !conn.baseURL)) return;
     const seq = ++fetchSeq.current;
     const activeFilters = JSON.parse(filtersKey) as FrappeFacetFilters;
 
@@ -525,7 +528,11 @@ export function useFrappeFacets(
       return;
     }
 
-    const call = getCall(conn);
+    // Narrowing only: the guard at the top of the effect already returned
+    // when neither a corpus nor a baseURL is configured.
+    if (!conn.baseURL) return;
+
+    const call = getCall(conn.baseURL, conn.auth);
     fetchGroupByCount(call, doctype, filtersExcludingField(activeFilters, "_assign"), "assigned_to")
       .then((rows) => done("assigned", rows))
       .catch((error) => fail("assigned", error));

package/src/useFrappeRows.spec.tsx

@@ -0,0 +1,176 @@
+/**
+ * useFrappeRows — the composed doctype read (MPO-251).
+ *
+ * What this locks:
+ *  1. rows / isLoading / error come back from one hook, so a panel with no
+ *     shipped component does not re-derive the read.
+ *  2. A 403 or an unreachable server surfaces as an ERROR, not as an empty
+ *     result — the trap the copies each had to remember.
+ *  3. `limit` is defaulted by the hook (DEFAULT_FRAPPE_ROWS_LIMIT), with
+ *     `limit: null` as the explicit bench-default opt-out FrappeTable takes.
+ *  4. Collection sharing is keyed on the options JSON: the same field list
+ *     shares one collection, a different one does not.
+ *
+ * Fixture-hermetic: documents ride InMemoryFixtureProvider, so nothing
+ * dials a baseURL.
+ */
+
+import { InMemoryFixtureProvider, useFrappeCollection } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { FrappeProvider } from "./FrappeProvider";
+import { DEFAULT_FRAPPE_ROWS_LIMIT, useFrappeConnection, useFrappeRows } from "./useFrappeRows";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+interface Account {
+  name: string;
+  doctype: string;
+  account: string;
+  balance: string;
+}
+
+const accounts: Account[] = [
+  { name: "ACC-001", doctype: "Account", account: "Assets:Cash", balance: "10.00" },
+  { name: "ACC-002", doctype: "Account", account: "Assets:Bank", balance: "9.00" },
+];
+
+const accountFields = ["name", "account", "balance"] as const;
+
+function Harness({
+  onResult,
+  ...options
+}: {
+  onResult: (result: ReturnType<typeof useFrappeRows<Account>>) => void;
+} & Parameters<typeof useFrappeRows<Account>>[2]) {
+  const connection = useFrappeConnection();
+  const result = useFrappeRows<Account>(connection, "Account", options);
+  onResult(result);
+  return null;
+}
+
+function renderHarness(
+  options: Parameters<typeof useFrappeRows<Account>>[2] = {},
+  fixtures = new InMemoryFixtureProvider({ Account: accounts }),
+) {
+  const results: Array<ReturnType<typeof useFrappeRows<Account>>> = [];
+  const utils = renderWithProviders(
+    <FrappeProvider baseURL="https://userows.spec.test" fixtures={fixtures}>
+      <Harness onResult={(r) => results.push(r)} {...options} />
+    </FrappeProvider>,
+  );
+  return { results, last: () => results[results.length - 1]!, ...utils };
+}
+
+describe("useFrappeRows", () => {
+  it("reads a doctype into rows", async () => {
+    const { last } = renderHarness({ fields: accountFields });
+    await waitFor(() => expect(last().rows).toHaveLength(2));
+    expect(last().rows.map((r) => r.name)).toEqual(["ACC-001", "ACC-002"]);
+    expect(last().isLoading).toBe(false);
+    expect(last().error).toBeNull();
+  });
+
+  it("parks on enabled: false — no rows, not loading", () => {
+    const { last } = renderHarness({ fields: accountFields, enabled: false });
+    expect(last().rows).toEqual([]);
+    expect(last().isLoading).toBe(false);
+    expect(last().collection).toBeUndefined();
+  });
+
+  it("surfaces a permission rejection as an error rather than an empty result", async () => {
+    const fixtures = new InMemoryFixtureProvider({ Account: accounts });
+    vi.spyOn(fixtures, "getList").mockRejectedValue(
+      Object.assign(new Error("PermissionError"), { status: 403 }),
+    );
+    const { last } = renderHarness(
+      {
+        fields: accountFields,
+        messages: { permission: "No permission for Account", generic: "Error loading Account" },
+      },
+      fixtures,
+    );
+    await waitFor(() => expect(last().error).toBeInstanceOf(Error));
+    expect(last().error?.message).toContain("No permission for Account");
+    expect(last().rows).toEqual([]);
+  });
+
+  it("surfaces an unreachable server as an error rather than an empty result", async () => {
+    const fixtures = new InMemoryFixtureProvider({ Account: accounts });
+    vi.spyOn(fixtures, "getList").mockRejectedValue(new Error("Failed to fetch"));
+    const { last } = renderHarness(
+      {
+        fields: accountFields,
+        messages: { permission: "No permission for Account", generic: "Error loading Account" },
+      },
+      fixtures,
+    );
+    await waitFor(() => expect(last().error).toBeInstanceOf(Error));
+    expect(last().error?.message).toContain("Error loading Account");
+  });
+
+  it("defaults the limit rather than leaving it to the caller", () => {
+    // Two readers of the same doctype: one taking the default limit, one
+    // passing null (the bench-default opt-out). The options JSON is the
+    // collection cache key and `limit` is part of it, so a differing limit
+    // must produce a DIFFERENT collection.
+    const fixtures = new InMemoryFixtureProvider({ Account: accounts });
+    const seen: Array<unknown> = [];
+    function TwoReaders() {
+      const connection = useFrappeConnection();
+      const defaulted = useFrappeRows<Account>(connection, "Account", { fields: accountFields });
+      const benchDefault = useFrappeRows<Account>(connection, "Account", {
+        fields: accountFields,
+        limit: null,
+      });
+      const explicit = useFrappeRows<Account>(connection, "Account", {
+        fields: accountFields,
+        limit: DEFAULT_FRAPPE_ROWS_LIMIT,
+      });
+      seen.push([defaulted.collection, benchDefault.collection, explicit.collection]);
+      return null;
+    }
+    renderWithProviders(
+      <FrappeProvider baseURL="https://userows.spec.test" fixtures={fixtures}>
+        <TwoReaders />
+      </FrappeProvider>,
+    );
+    const [defaulted, benchDefault, explicit] = seen[seen.length - 1] as unknown[];
+    expect(defaulted).toBeDefined();
+    expect(defaulted, "omitting limit is the same query as passing the default").toBe(explicit);
+    expect(benchDefault, "limit: null is a different query — no limit at all").not.toBe(defaulted);
+  });
+
+  it("shares one collection with an identical field list and splits on a different one", () => {
+    const fixtures = new InMemoryFixtureProvider({ Account: accounts });
+    const seen: Array<unknown[]> = [];
+    function ThreeReaders() {
+      const connection = useFrappeConnection();
+      const a = useFrappeRows<Account>(connection, "Account", { fields: accountFields });
+      const b = useFrappeRows<Account>(connection, "Account", {
+        fields: ["name", "account", "balance"],
+      });
+      const c = useFrappeRows<Account>(connection, "Account", { fields: ["name", "account"] });
+      seen.push([a.collection, b.collection, c.collection]);
+      return null;
+    }
+    renderWithProviders(
+      <FrappeProvider baseURL="https://userows.spec.test" fixtures={fixtures}>
+        <ThreeReaders />
+      </FrappeProvider>,
+    );
+    const [a, b, c] = seen[seen.length - 1]!;
+    expect(a, "same field list shares one collection").toBe(b);
+    expect(c, "a field list short by one entry does NOT share").not.toBe(a);
+  });
+
+  it("is the same primitive FrappeTable's read was built on", () => {
+    // Guardrail against the hook drifting away from useFrappeCollection —
+    // the point of MPO-251 is ONE implementation, not a second one.
+    expect(typeof useFrappeCollection).toBe("function");
+  });
+});