@multiplatform.one/frappe-ui 7.21.0 → 7.23.0

package/src/FrappeTable.defaultColumns.spec.tsx

@@ -0,0 +1,229 @@
+/**
+ * FrappeTable without `columns` (MPO-15 AC4).
+ *
+ * The prop used to be required, so the doctype-aware table could not render
+ * a doctype unless its caller did the meta work. Omitted now, the columns
+ * come from meta through `buildListColumns`, the same derivation the desk
+ * list screen calls: title, the in_list_view fields the session may read,
+ * the activity cluster, and the `modified` sort key kept hidden. A bench read
+ * waits for meta and the roles, then asks once for `listFieldsToFetch`.
+ */
+
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, screen, waitFor } from "@testing-library/react";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { FrappeProvider } from "./FrappeProvider";
+import { FrappeTable } from "./FrappeTable";
+import { buildPermLevelMatrix } from "./formEngine/fieldPermissions";
+import type { DoctypeMeta } from "./formEngine/doctypeMeta";
+import { buildListColumns } from "./list/listColumns";
+import { listFieldsToFetch } from "./list/listFields";
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+interface Customer {
+  name: string;
+  doctype: string;
+  customer_name: string;
+  status: string;
+  territory: string;
+  credit_limit: number;
+  modified: string;
+}
+
+const metaDoc = {
+  name: "Customer",
+  doctype: "DocType",
+  module: "Selling",
+  title_field: "customer_name",
+  fields: [
+    { fieldname: "customer_name", fieldtype: "Data", label: "Customer Name", in_list_view: 1 },
+    {
+      fieldname: "status",
+      fieldtype: "Select",
+      label: "Status",
+      options: "Active\nLead",
+      in_list_view: 1,
+    },
+    {
+      fieldname: "territory",
+      fieldtype: "Link",
+      label: "Territory",
+      options: "Territory",
+      in_list_view: 1,
+    },
+    {
+      fieldname: "credit_limit",
+      fieldtype: "Currency",
+      label: "Credit Limit",
+      in_list_view: 1,
+      permlevel: 1,
+    },
+    { fieldname: "notes", fieldtype: "Text", label: "Notes" },
+  ],
+  permissions: [
+    { role: "Sales User", permlevel: 0, read: 1, write: 1, create: 1 },
+    { role: "Sales Manager", permlevel: 1, read: 1, write: 1 },
+  ],
+};
+const meta = metaDoc as unknown as DoctypeMeta;
+
+const customers: Customer[] = [
+  {
+    name: "CUST-001",
+    doctype: "Customer",
+    customer_name: "Acme Corp",
+    status: "Active",
+    territory: "North",
+    credit_limit: 5000,
+    modified: "2026-09-20 10:00:00",
+  },
+  {
+    name: "CUST-002",
+    doctype: "Customer",
+    customer_name: "Globex",
+    status: "Lead",
+    territory: "South",
+    credit_limit: 900,
+    modified: "2026-09-21 10:00:00",
+  },
+];
+
+function headerText(container: HTMLElement): string {
+  return container.querySelector('[aria-label="Table headers"]')?.textContent ?? "";
+}
+
+describe("FrappeTable without columns, over a fixture corpus", () => {
+  it("renders the desk list columns buildListColumns derives from meta", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockImplementation((input) => {
+      throw new Error(`unexpected network request: ${String(input)}`);
+    });
+    const { container } = renderWithProviders(
+      <FrappeProvider
+        baseURL="https://frappetable-default-columns.spec.test"
+        fixtures={new InMemoryFixtureProvider({ DocType: [metaDoc], Customer: customers })}
+      >
+        <FrappeTable<Customer> doctype="Customer" layout="table" enablePagination={false} />
+      </FrappeProvider>,
+    );
+
+    expect(await screen.findByText("Acme Corp")).toBeTruthy();
+    expect(await screen.findByText("Lead")).toBeTruthy();
+    expect(screen.getByText("North")).toBeTruthy();
+
+    // Fixtures withhold nothing, so every in_list_view field paints.
+    const derived = buildListColumns({ meta, t: (_key, fallback) => fallback });
+    const visibleHeaders = derived
+      .filter((column) => column.id !== "modified")
+      .map((column) => String(column.header));
+    expect(visibleHeaders).toEqual([
+      "Customer Name",
+      "Status",
+      "Territory",
+      "Credit Limit",
+      "Activity",
+    ]);
+    await waitFor(() => {
+      const headers = headerText(container);
+      for (const header of visibleHeaders) expect(headers).toContain(header);
+    });
+    // The modified column is the hidden sort key; its time paints in the
+    // activity cluster, not as a second "Last Updated On" column.
+    expect(headerText(container)).not.toContain("Last Updated On");
+    expect(container.querySelectorAll('[data-testid="list-activity"]').length).toBe(2);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the document name when the corpus has no meta for the doctype", async () => {
+    renderWithProviders(
+      <FrappeProvider
+        baseURL="https://frappetable-default-columns-nometa.spec.test"
+        fixtures={new InMemoryFixtureProvider({ Customer: customers })}
+      >
+        <FrappeTable<Customer> doctype="Customer" layout="table" enablePagination={false} />
+      </FrappeProvider>,
+    );
+
+    expect(await screen.findByText("CUST-001")).toBeTruthy();
+    expect(await screen.findByText("CUST-002")).toBeTruthy();
+    expect(screen.getByText("ID")).toBeTruthy();
+  });
+});
+
+describe("FrappeTable without columns, serverSide against a bench", () => {
+  function json(body: unknown): Response {
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  it("waits for meta and roles, then reads the derived fields once", async () => {
+    const calls: string[] = [];
+    const listRequests: URL[] = [];
+    vi.stubGlobal("fetch", async (input: string | URL | Request) => {
+      const url = new URL(String(input instanceof Request ? input.url : input));
+      const method = url.pathname.replace(/^\/api\/method\//, "");
+      calls.push(method);
+      if (method === "frappe.desk.form.load.getdoctype") return json({ docs: [metaDoc] });
+      if (method === "frappe.auth.get_logged_user") return json({ message: "clerk@sales.test" });
+      if (method === "frappe.core.doctype.user.user.get_roles") {
+        return json({ message: ["Sales User"] });
+      }
+      if (method === "frappe.client.get_count") return json({ message: customers.length });
+      if (url.pathname === "/api/resource/Customer") {
+        listRequests.push(url);
+        return json({ data: customers });
+      }
+      return json({ data: [], message: [] });
+    });
+
+    const { container } = renderWithProviders(
+      <FrappeProvider
+        baseURL="https://frappetable-default-columns-bench.spec.test"
+        realtime={false}
+      >
+        <FrappeTable<Customer>
+          doctype="Customer"
+          serverSide
+          layout="table"
+          initialState={{ pagination: { pageIndex: 0, pageSize: 10 } }}
+        />
+      </FrappeProvider>,
+    );
+
+    expect(await screen.findByText("Acme Corp")).toBeTruthy();
+    // Sales User reads permlevel 0 only: Credit Limit is neither a column
+    // nor asked for, the way desk's list prunes it.
+    const expected = listFieldsToFetch(
+      meta,
+      buildPermLevelMatrix(meta.permissions, ["Sales User"]),
+    );
+    expect(expected).not.toContain("credit_limit");
+    expect(listRequests.length).toBe(1);
+    expect(JSON.parse(listRequests[0].searchParams.get("fields") ?? "[]")).toEqual(expected);
+    expect(calls.indexOf("frappe.desk.form.load.getdoctype")).toBeLessThan(
+      calls.indexOf("/api/resource/Customer"),
+    );
+    await waitFor(() => expect(headerText(container)).toContain("Status"));
+    expect(headerText(container)).not.toContain("Credit Limit");
+
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    expect(listRequests.length).toBe(1);
+  });
+});

package/src/FrappeTable.tsx

@@ -25,7 +25,10 @@ import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeReconnectIndicator } from "./FrappeReconnectIndicator";
 import { docFieldsToFilterFields } from "./filterFields";
 import type { DocRights } from "./formEngine/docPermissions";
+import { buildPermLevelMatrix } from "./formEngine/fieldPermissions";
 import { useDocRights } from "./formEngine/useDocRights";
+import { buildListColumns } from "./list/listColumns";
+import { listFieldsToFetch } from "./list/listFields";
 import { useFrappeRows } from "./useFrappeRows";
 
 /**
@@ -71,13 +74,19 @@ export interface FrappeTableProps<TDoc extends { name: string; doctype: string }
   syncOptions?: any;
   /** The Frappe DocType to display */
   doctype: string;
-  /** Column definitions for the table */
-  columns: DataTableColumn<Partial<TDoc>>[];
+  /**
+   * Column definitions. Omitted, they come from the doctype's meta through
+   * `buildListColumns`, the desk list's own anatomy (title, the
+   * in_list_view fields the session may read, activity), and the table
+   * waits for meta and the session's roles before its first read.
+   */
+  columns?: DataTableColumn<Partial<TDoc>>[];
   /**
    * Fields to fetch. Omitted, a read from the bench (`serverSide`, or client
    * mode under a provider without `fixtures`) requests `name` plus every
-   * column's `accessorKey`, and client mode under a provider carrying
-   * `fixtures` reads whole documents from the corpus. A column keyed on
+   * column's `accessorKey` (with `columns` omitted too, the fields the
+   * derived columns paint: `listFieldsToFetch`), and client mode under a
+   * provider carrying `fixtures` reads whole documents from the corpus. A column keyed on
    * something that is not a doctype field (a rowAccumulator's derived key,
    * say) makes the bench refuse that read, so name the list to leave such a
    * key out. Name it, too, to share one collection with another reader of
@@ -321,7 +330,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   auth,
   syncOptions,
   doctype,
-  columns,
+  columns: columnsProp,
   fields,
   filters: initialFilters,
   onRowClick,
@@ -338,6 +347,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   filterableFields: filterableFieldsProp,
   rights: rightsProp,
   layout,
+  initialState,
   ...dataTableProps
 }: FrappeTableProps<TDoc>) {
   // Infinite + serverSide: DataTable's page cache drives fetching through a
@@ -406,14 +416,69 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
     return new FrappeApp(finalBaseURL, (finalAuth ?? {}) as Record<string, unknown>);
   }, [serverSide, finalBaseURL, finalAuth]);
 
+  // Full doctype field list → table filterableFields: hidden / non-column
+  // fields become filterable through the toolbar Filter surface. An explicit
+  // filterableFields prop overrides the metadata-derived list (fixtures,
+  // stories, custom subsets). A fixture corpus is the whole world for meta
+  // too: the read goes to its "DocType" collection with the baseURL a
+  // fixture host may still carry withheld, so a corpus without the entry
+  // yields no menu instead of dialling getdoctype (MPO-230). Columns left to
+  // meta need it whatever else is given.
+  const deriveColumns = !columnsProp;
+  const skipMeta =
+    !deriveColumns && !!filterableFieldsProp && (!!rightsProp || !!connectionConfig.fixtures);
+  const metaConnection = useMemo(() => {
+    if (skipMeta) return undefined;
+    if (!connectionConfig.fixtures) return connectionConfig;
+    return { ...connectionConfig, baseURL: undefined };
+  }, [skipMeta, connectionConfig]);
+  const { meta, isLoading: isMetaLoading } = useDocTypeMeta(metaConnection, doctype);
+  const readSession = !rightsProp || deriveColumns;
+  const {
+    rights: resolvedRights,
+    pending: rolesPending,
+    user: sessionUser,
+    roles: sessionRoles,
+  } = useDocRights(readSession ? connectionConfig : undefined, readSession ? meta : undefined);
+  const rights = rightsProp ?? resolvedRights;
+
+  const permMatrix = useMemo(
+    () => (deriveColumns ? buildPermLevelMatrix(meta?.permissions, sessionRoles) : undefined),
+    [deriveColumns, meta?.permissions, sessionRoles],
+  );
+  const derivedColumns = useMemo(
+    () =>
+      deriveColumns
+        ? (buildListColumns({
+            meta,
+            t: (_key, fallback) => t(fallback),
+            sessionUser,
+            permMatrix,
+          }) as DataTableColumn<Partial<TDoc>>[])
+        : undefined,
+    [deriveColumns, meta, t, sessionUser, permMatrix],
+  );
+  const columns = columnsProp ?? derivedColumns ?? [];
+  // Derived columns settle once meta and the roles that prune them land;
+  // reading before that would fetch one field list and then another.
+  const columnsPending = deriveColumns && (isMetaLoading || rolesPending);
+  const resolvedInitialState = deriveColumns
+    ? {
+        ...initialState,
+        columnVisibility: { modified: false, ...initialState?.columnVisibility },
+      }
+    : initialState;
+
   // Keyed on content, not on the columns array, so an inline `columns`
   // literal cannot re-key the fetch every render and refetch in a loop.
   const columnFieldsKey = fields
     ? undefined
     : JSON.stringify(
-        columns
-          .map((column): unknown => column.accessorKey)
-          .filter((key): key is string => typeof key === "string"),
+        deriveColumns
+          ? listFieldsToFetch(meta, permMatrix)
+          : columns
+              .map((column): unknown => column.accessorKey)
+              .filter((key): key is string => typeof key === "string"),
       );
   const serverFields = useMemo<string[]>(
     () =>
@@ -428,25 +493,6 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   const clientFields = (fields ??
     (connectionConfig.fixtures ? undefined : serverFields)) as typeof fields;
 
-  // Full doctype field list → table filterableFields: hidden / non-column
-  // fields become filterable through the toolbar Filter surface. An explicit
-  // filterableFields prop overrides the metadata-derived list (fixtures,
-  // stories, custom subsets). A fixture corpus is the whole world for meta
-  // too: the read goes to its "DocType" collection with the baseURL a
-  // fixture host may still carry withheld, so a corpus without the entry
-  // yields no menu instead of dialling getdoctype (MPO-230).
-  const skipMeta = !!filterableFieldsProp && (!!rightsProp || !!connectionConfig.fixtures);
-  const metaConnection = useMemo(() => {
-    if (skipMeta) return undefined;
-    if (!connectionConfig.fixtures) return connectionConfig;
-    return { ...connectionConfig, baseURL: undefined };
-  }, [skipMeta, connectionConfig]);
-  const { meta } = useDocTypeMeta(metaConnection, doctype);
-  const { rights: resolvedRights } = useDocRights(
-    rightsProp ? undefined : connectionConfig,
-    rightsProp ? undefined : meta,
-  );
-  const rights = rightsProp ?? resolvedRights;
   const metaFilterFields = useMemo(
     () => (meta?.fields ? docFieldsToFilterFields(meta.fields) : undefined),
     [meta],
@@ -670,7 +716,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   );
 
   useEffect(() => {
-    if (serverSide && !infiniteServerMode && frappeApp) {
+    if (serverSide && !infiniteServerMode && frappeApp && !columnsPending) {
       lastFetchKey.current = "";
       fetchServerData(
         lastStateRef.current ??
@@ -687,7 +733,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
           } as DataTableState),
       );
     }
-  }, [serverSide, infiniteServerMode, !!frappeApp, fetchServerData]);
+  }, [serverSide, infiniteServerMode, !!frappeApp, columnsPending, fetchServerData]);
 
   // Always call the hook — toggling `savedFilters` must not change hook order (SB-M-012).
   const savedFiltersHook = useSavedFilters({ userId });
@@ -714,7 +760,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
     fields: clientFields,
     filters: activeFilters,
     limit: null,
-    enabled: !serverSide,
+    enabled: !serverSide && !columnsPending,
     messages: rowsMessages,
   });
 
@@ -724,7 +770,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   // (optimistic local apply), until the new collection is ready. Only the
   // very first load may show the skeleton.
   const lastGoodClientRows = useRef<TDoc[] | null>(null);
-  if (!serverSide && !isRowsLoading) lastGoodClientRows.current = clientRows;
+  if (!serverSide && !isRowsLoading && !columnsPending) lastGoodClientRows.current = clientRows;
   const clientRowsResolved = useMemo(() => {
     if (serverSide) return clientRows;
     if (!isRowsLoading || !lastGoodClientRows.current) return clientRows;
@@ -796,7 +842,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   // while a refetch is in flight — that was the named blank-the-list defect.
   const boundaryState = resolvedError
     ? { error: resolvedError }
-    : isRowsLoadingResolved
+    : isRowsLoadingResolved || columnsPending
       ? { loading: loading ?? true }
       : rowData.length === 0 && !infiniteServerMode && !isFetching
         ? { empty: true }
@@ -881,6 +927,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
         paginationMode={paginationMode}
         {...(resolvedLoadPage ? { loadPage: resolvedLoadPage } : {})}
         {...(filterableFields ? { filterableFields } : {})}
+        {...(resolvedInitialState ? { initialState: resolvedInitialState } : {})}
         isFetching={isFetching}
         {...dataTableProps}
         readOnly={dataTableProps.readOnly || !rights.write}

package/src/desk/DeskFormPage.tsx

@@ -156,6 +156,7 @@ export function DeskFormPage({ doctype, name, onNavigate }: DeskFormPageProps) {
           }}
           onCancel={() => handleNavigate(`/desk/${doctype}`)}
           onDelete={() => handleNavigate(`/desk/${doctype}`)}
+          onAmend={() => handleNavigate(`/desk/${doctype}/new`)}
         />
       </DetailPageLayout>
     </DeskShell>

package/src/filterFields.spec.ts

@@ -1,7 +1,13 @@
 import type { DocTypeField } from "@multiplatform.one/frappe";
 import { describe, expect, it } from "vitest";
 import { filterValueToFrappeTuple } from "./FrappeTable";
-import { docFieldsToFilterFields } from "./filterFields";
+import {
+  docFieldsToFilterFields,
+  filterableFieldsFromMeta,
+  standardDocFilterFields,
+  standardFiltersFromMeta,
+} from "./filterFields";
+import type { DoctypeMeta } from "./formEngine/doctypeMeta";
 
 const docFields = [
   { fieldname: "customer_name", fieldtype: "Data", label: "Customer Name" },
@@ -66,11 +72,34 @@ describe("docFieldsToFilterFields", () => {
     expect(byId.photo).toBeUndefined();
   });
 
-  it("appends the standard doc fields (name/owner/creation/modified)", () => {
+  it("appends the standard doc fields, the desk facet columns included", () => {
     expect(byId.name).toMatchObject({ label: "ID", type: "text" });
     expect(byId.owner?.type).toBe("text");
     expect(byId.creation?.type).toBe("date");
     expect(byId.modified?.type).toBe("date");
+    expect(byId.modified_by).toMatchObject({ label: "Last Updated By", type: "text" });
+    expect(byId._assign).toMatchObject({ label: "Assigned To", type: "text" });
+    expect(byId._user_tags).toMatchObject({ label: "Tags", type: "text" });
+    expect(byId._liked_by).toMatchObject({ label: "Liked By", type: "text" });
+    expect(byId._comments).toMatchObject({ label: "Comments", type: "text" });
+  });
+
+  it("offers exactly the fields and labels the desk filter picker offers (one vocabulary)", () => {
+    const desk = filterableFieldsFromMeta({ name: "Customer", fields: docFields } as DoctypeMeta);
+    expect(fields.map((field) => [field.id, field.label])).toEqual(
+      desk.map((field) => [field.fieldname, field.label]),
+    );
+    const standard = standardDocFilterFields().map((field) => field.fieldname);
+    expect(fields.slice(-standard.length).map((field) => field.id)).toEqual(standard);
+  });
+
+  it("does not repeat a standard field the doctype already declares", () => {
+    const out = docFieldsToFilterFields([
+      { fieldname: "owner", fieldtype: "Link", label: "Owner", options: "User" } as DocTypeField,
+    ]);
+    expect(out.filter((field) => field.id === "owner")).toEqual([
+      { id: "owner", label: "Owner", type: "text" },
+    ]);
   });
 
   it("uses the label when present and falls back to fieldname", () => {
@@ -157,3 +186,29 @@ describe("filterValueToFrappeTuple", () => {
     ).toBeNull();
   });
 });
+
+describe("standardFiltersFromMeta", () => {
+  const todoMeta = {
+    name: "ToDo",
+    title_field: "description",
+    fields: [
+      {
+        fieldname: "status",
+        fieldtype: "Select",
+        label: "Status",
+        options: "Open\nClosed",
+        in_standard_filter: 1,
+      },
+      { fieldname: "description", fieldtype: "Small Text", label: "Description" },
+      { fieldname: "priority", fieldtype: "Select", label: "Priority", in_list_view: 1 },
+    ],
+  } as DoctypeMeta;
+
+  it("prepends ID and the title field when they are not already standard filters", () => {
+    const names = standardFiltersFromMeta(todoMeta).map((field) => field.fieldname);
+    expect(names[0]).toBe("name");
+    expect(names).toContain("description");
+    expect(names).toContain("status");
+    expect(names).not.toContain("priority");
+  });
+});