@multiplatform.one/frappe-ui 7.20.0 → 7.21.0

package/src/FrappeTable.tsx

@@ -24,6 +24,8 @@ import { FilterManager, SavedFilterDropdown, useSavedFilters } from "@multiplatf
 import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeReconnectIndicator } from "./FrappeReconnectIndicator";
 import { docFieldsToFilterFields } from "./filterFields";
+import type { DocRights } from "./formEngine/docPermissions";
+import { useDocRights } from "./formEngine/useDocRights";
 import { useFrappeRows } from "./useFrappeRows";
 
 /**
@@ -136,9 +138,17 @@ export interface FrappeTableProps<TDoc extends { name: string; doctype: string }
    * meta-derived menu offers the doctype's fields, including ones the
    * server refuses to filter on, so a live app should pass the honoured
    * set by hand. Passing it skips the meta read entirely, which also drops
-   * title-field row labels back to the document name.
+   * title-field row labels back to the document name, unless the table
+   * still reads meta for `rights`.
    */
   filterableFields?: FilterableField[];
+  /**
+   * The session's rights on the doctype. Without write the cells render
+   * read-only, without create there is no add row, without delete no row
+   * delete. Omitted, the table resolves them from the doctype's meta and the
+   * session's roles; a fixtures connection withholds nothing.
+   */
+  rights?: Pick<DocRights, "create" | "write" | "delete">;
 }
 
 /**
@@ -326,6 +336,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   paginationMode = "pages",
   loadPage: loadPageProp,
   filterableFields: filterableFieldsProp,
+  rights: rightsProp,
   layout,
   ...dataTableProps
 }: FrappeTableProps<TDoc>) {
@@ -424,13 +435,18 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   // 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;
+  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],
@@ -867,6 +883,9 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
         {...(filterableFields ? { filterableFields } : {})}
         isFetching={isFetching}
         {...dataTableProps}
+        readOnly={dataTableProps.readOnly || !rights.write}
+        showAddRow={dataTableProps.showAddRow && rights.create}
+        showDeleteRow={dataTableProps.showDeleteRow && rights.delete}
         {...(layout ? { layout } : {})}
       />
     </YStack>

package/src/formEngine/docPermissions.spec.ts

@@ -0,0 +1,145 @@
+// The session's doc-level rights from getdoctype's DocPerm rows and the
+// session roles (MPO-390), against frappe/permissions.py
+// get_role_permissions: permlevel 0 only, OR across the user's roles,
+// if_owner rows scoped to the user's own records except create.
+import { describe, expect, it } from "vitest";
+import { allDocRights, resolveDocRights, sessionDocRights, type DocRights } from "./docPermissions";
+import type { DocPermissionRule } from "./doctypeMeta";
+
+const pokeMove: DocPermissionRule[] = [
+  { role: "System Manager", read: 1, write: 1, create: 1, delete: 1, export: 1 },
+  { role: "Pokemon Editor", read: 1, write: 1, create: 1, delete: 1 },
+  { role: "Guest", read: 1 },
+  { role: "Move Author", read: 1, write: 1, create: 1, delete: 1, if_owner: 1 },
+  { role: "Move Curator", permlevel: 1, read: 1, write: 1 },
+];
+
+function granted(rights: DocRights): string[] {
+  return Object.entries(rights)
+    .filter(([, value]) => value)
+    .map(([right]) => right)
+    .sort();
+}
+
+describe("resolveDocRights", () => {
+  it("grants a reader only what the Guest row grants", () => {
+    const rights = resolveDocRights({ permissions: pokeMove, roles: ["Guest", "All"] });
+    expect(granted(rights)).toEqual(["read"]);
+  });
+
+  it("grants create, write and delete through Pokemon Editor", () => {
+    const rights = resolveDocRights({
+      permissions: pokeMove,
+      roles: ["Pokemon Editor", "Guest", "All"],
+      user: "editor@pokemon.test",
+      owner: "Administrator",
+    });
+    expect(rights.create).toBe(true);
+    expect(rights.write).toBe(true);
+    expect(rights.delete).toBe(true);
+    expect(rights.export).toBe(false);
+  });
+
+  it("ORs the rights of every role the user holds", () => {
+    const rights = resolveDocRights({
+      permissions: pokeMove,
+      roles: ["Pokemon Editor", "System Manager"],
+    });
+    expect(rights.export).toBe(true);
+    expect(rights.delete).toBe(true);
+  });
+
+  it("ignores rows above permlevel 0", () => {
+    const rights = resolveDocRights({ permissions: pokeMove, roles: ["Move Curator"] });
+    expect(granted(rights)).toEqual([]);
+  });
+
+  it("scopes if_owner write and delete to the user's own records but keeps create", () => {
+    const base = { permissions: pokeMove, roles: ["Move Author"], user: "author@pokemon.test" };
+    const own = resolveDocRights({ ...base, owner: "author@pokemon.test" });
+    expect([own.create, own.read, own.write, own.delete]).toEqual([true, true, true, true]);
+
+    const others = resolveDocRights({ ...base, owner: "Administrator" });
+    expect([others.create, others.read, others.write, others.delete]).toEqual([
+      true,
+      false,
+      false,
+      false,
+    ]);
+
+    const doctype = resolveDocRights(base);
+    expect([doctype.create, doctype.read, doctype.write, doctype.delete]).toEqual([
+      true,
+      true,
+      false,
+      false,
+    ]);
+  });
+
+  it("lets a plain row lift the if_owner scope for the same right", () => {
+    const rights = resolveDocRights({
+      permissions: pokeMove,
+      roles: ["Move Author", "Pokemon Editor"],
+      user: "author@pokemon.test",
+      owner: "Administrator",
+    });
+    expect(rights.write).toBe(true);
+    expect(rights.delete).toBe(true);
+  });
+
+  it("gives Administrator every right, rows or not", () => {
+    expect(resolveDocRights({ permissions: [], roles: [], user: "Administrator" })).toEqual(
+      allDocRights(true),
+    );
+  });
+
+  it("adds read and write from a share for the user or for everyone, never delete", () => {
+    const reader = {
+      permissions: pokeMove,
+      roles: ["Guest"],
+      user: "reader@pokemon.test",
+      owner: "Administrator",
+    };
+    const shared = resolveDocRights({
+      ...reader,
+      shares: [{ user: "reader@pokemon.test", read: 1, write: 1 }],
+    });
+    expect([shared.write, shared.delete]).toEqual([true, false]);
+
+    const everyone = resolveDocRights({ ...reader, shares: [{ everyone: 1, write: 1 }] });
+    expect(everyone.write).toBe(true);
+
+    const someoneElse = resolveDocRights({
+      ...reader,
+      shares: [{ user: "other@pokemon.test", write: 1 }],
+    });
+    expect(someoneElse.write).toBe(false);
+  });
+});
+
+describe("sessionDocRights", () => {
+  const meta = { permissions: pokeMove };
+
+  it("withholds nothing on a fixtures connection", () => {
+    expect(sessionDocRights({ fixtures: true, meta: undefined, roles: undefined })).toEqual(
+      allDocRights(true),
+    );
+  });
+
+  it("grants nothing on a live connection without meta (Guest's getdoctype 403)", () => {
+    expect(sessionDocRights({ fixtures: false, meta: undefined, roles: ["Guest"] })).toEqual(
+      allDocRights(false),
+    );
+  });
+
+  it("grants nothing on a live connection whose roles are loading or unreadable", () => {
+    expect(sessionDocRights({ fixtures: false, meta, roles: undefined })).toEqual(
+      allDocRights(false),
+    );
+  });
+
+  it("resolves the session's roles once both are known", () => {
+    const rights = sessionDocRights({ fixtures: false, meta, roles: ["Pokemon Editor"] });
+    expect([rights.create, rights.write, rights.delete]).toEqual([true, true, true]);
+  });
+});

package/src/formEngine/docPermissions.ts

@@ -0,0 +1,128 @@
+/**
+ * Doc-level rights for the session, the permlevel-0 half of desk's
+ * permission model (fieldPermissions.ts is the field-level half).
+ *
+ * Server parity with frappe/permissions.py `get_role_permissions`: a right is
+ * granted when a permlevel-0 DocPerm row of one of the session's roles grants
+ * it. When every granting row is `if_owner`, the right holds only on records
+ * the session user owns, except `create`, which an `if_owner` row still
+ * grants, and `read` / `select` at doctype level, which stay open so the list
+ * can be read (the server narrows it to the user's own rows). Administrator
+ * holds every right, as the server's `allow_everything()` does. A record's
+ * DocShare rows for the user or for everyone add read, write and share, as
+ * desk perm.js applies `docinfo.shared`.
+ */
+
+import type { DocPermissionRule, DoctypeMeta } from "./doctypeMeta";
+
+export const docRightNames = [
+  "select",
+  "read",
+  "write",
+  "create",
+  "delete",
+  "submit",
+  "cancel",
+  "amend",
+  "print",
+  "email",
+  "report",
+  "import",
+  "export",
+  "share",
+] as const;
+
+export type DocRight = (typeof docRightNames)[number];
+
+export type DocRights = Record<DocRight, boolean>;
+
+/** A DocShare row as the live collection or docinfo carries it. */
+export interface DocShareGrant {
+  user?: string | null;
+  everyone?: number | boolean | null;
+  read?: number | boolean | null;
+  write?: number | boolean | null;
+  share?: number | boolean | null;
+}
+
+export interface ResolveDocRightsInput {
+  permissions: readonly DocPermissionRule[] | undefined;
+  roles: readonly string[];
+  user?: string;
+  /** The record's owner. Omitted, the rights are the doctype's (a list, a new record). */
+  owner?: string;
+  shares?: readonly DocShareGrant[];
+}
+
+export function allDocRights(granted: boolean): DocRights {
+  const rights = {} as DocRights;
+  for (const right of docRightNames) rights[right] = granted;
+  return rights;
+}
+
+const openAtDoctypeLevel = new Set<DocRight>(["read", "select"]);
+
+export function resolveDocRights({
+  permissions,
+  roles,
+  user,
+  owner,
+  shares,
+}: ResolveDocRightsInput): DocRights {
+  if (user === "Administrator") return allDocRights(true);
+  const roleSet = new Set(roles);
+  const rows = (permissions ?? []).filter(
+    (row) => !!row.role && roleSet.has(row.role) && !(Number(row.permlevel ?? 0) || 0),
+  );
+  const isOwner = owner !== undefined && user !== undefined && owner === user;
+  const rights = allDocRights(false);
+  for (const right of docRightNames) {
+    const granting = rows.filter((row) => !!row[right]);
+    if (granting.length === 0) continue;
+    const ownerOnly = granting.every((row) => !!row.if_owner);
+    rights[right] =
+      !ownerOnly ||
+      right === "create" ||
+      isOwner ||
+      (owner === undefined && openAtDoctypeLevel.has(right));
+  }
+  if (user && owner !== undefined) {
+    for (const share of shares ?? []) {
+      if (share.user !== user && !share.everyone) continue;
+      if (share.read) rights.read = true;
+      if (share.write) rights.write = true;
+      if (share.share) rights.share = true;
+    }
+  }
+  return rights;
+}
+
+export interface SessionDocRightsInput {
+  /** A fixtures-only connection: no session exists, so nothing is withheld. */
+  fixtures: boolean;
+  meta: Pick<DoctypeMeta, "permissions"> | undefined;
+  /** The session's roles; undefined while they load or when they can't be read. */
+  roles: readonly string[] | undefined;
+  user?: string;
+  owner?: string;
+  shares?: readonly DocShareGrant[];
+}
+
+/**
+ * The rights a surface offers. A fixtures connection keeps every action; a
+ * live one grants nothing until both the doctype's meta and the session's
+ * roles are known, so a reader who can't load meta (Guest) or whose roles
+ * can't be read is shown a read-only surface.
+ */
+export function sessionDocRights({
+  fixtures,
+  meta,
+  roles,
+  user,
+  owner,
+  shares,
+}: SessionDocRightsInput): DocRights {
+  if (fixtures) return allDocRights(true);
+  if (!meta || !roles) return allDocRights(false);
+  return resolveDocRights({ permissions: meta.permissions, roles, user, owner, shares });
+}

package/src/formEngine/index.ts

@@ -32,4 +32,17 @@ export type { BuildTabsOptions, FormTab } from "./formLayout";
 export { useFormEngine } from "./useFormEngine";
 export type { FormEngine } from "./useFormEngine";
 
-export { useSessionRoles } from "./useSessionRoles";
+export { useFrappeSession, useSessionRoles } from "./useSessionRoles";
+export type { FrappeSession } from "./useSessionRoles";
+
+export { allDocRights, docRightNames, resolveDocRights, sessionDocRights } from "./docPermissions";
+export type {
+  DocRight,
+  DocRights,
+  DocShareGrant,
+  ResolveDocRightsInput,
+  SessionDocRightsInput,
+} from "./docPermissions";
+
+export { useDocRights } from "./useDocRights";
+export type { DocRightsOptions, DocRightsResult } from "./useDocRights";

package/src/formEngine/useDocRights.ts

@@ -0,0 +1,41 @@
+import { useMemo } from "react";
+import { sessionDocRights, type DocRights, type DocShareGrant } from "./docPermissions";
+import type { DoctypeMeta } from "./doctypeMeta";
+import { useFrappeSession, type SessionConnection } from "./useSessionRoles";
+
+export interface DocRightsOptions {
+  /** Roles to resolve against instead of the session's. */
+  roles?: string[];
+  /** The record's owner; omitted for the doctype's rights. */
+  owner?: string;
+  shares?: readonly DocShareGrant[];
+}
+
+export interface DocRightsResult {
+  rights: DocRights;
+  /** The session's roles are still loading, so `rights` withholds what they may grant. */
+  pending: boolean;
+  user?: string;
+  roles?: string[];
+}
+
+/**
+ * The session's rights on a doctype, or on one record of it, from the
+ * doctype's DocPerm rows (`meta.permissions`) and the session's roles.
+ * See `sessionDocRights` for the fixtures and unknown-session rules.
+ */
+export function useDocRights(
+  connection: SessionConnection | undefined,
+  meta: DoctypeMeta | undefined,
+  { roles: rolesOverride, owner, shares }: DocRightsOptions = {},
+): DocRightsResult {
+  const fixtures = Boolean(connection?.fixtures);
+  const session = useFrappeSession(meta && !fixtures ? connection : undefined);
+  const roles = rolesOverride ?? session.roles;
+  const rights = useMemo(
+    () => sessionDocRights({ fixtures, meta, roles, user: session.user, owner, shares }),
+    [fixtures, meta, roles, session.user, owner, shares],
+  );
+  const pending = !fixtures && Boolean(meta) && !rolesOverride && session.state === "loading";
+  return { rights, pending, user: session.user, roles };
+}

package/src/formEngine/useSessionRoles.ts

@@ -13,61 +13,87 @@
 import { useEffect, useRef, useState } from "react";
 import { createHttpClient, type FrappeConnection } from "./formActions";
 
-const rolesCache = new Map<string, Promise<string[]>>();
+interface SessionIdentity {
+  user: string;
+  roles: string[];
+}
+
+const sessionCache = new Map<string, Promise<SessionIdentity>>();
 
-function fetchSessionRoles(connection: FrappeConnection): Promise<string[]> {
+function fetchSession(connection: FrappeConnection): Promise<SessionIdentity> {
   const http = createHttpClient(connection);
-  return http
-    .get<{ message?: string }>("/api/method/frappe.auth.get_logged_user")
-    .then((res) => {
-      const user = res.payload?.message;
-      if (!user) throw new Error("No session user");
-      return http.get<{ message?: string[] }>(
-        "/api/method/frappe.core.doctype.user.user.get_roles",
-        { uid: user },
-      );
-    })
-    .then((res) => {
-      const list = res.payload?.message;
-      if (!Array.isArray(list)) throw new Error("No roles returned");
-      return list;
-    });
+  return http.get<{ message?: string }>("/api/method/frappe.auth.get_logged_user").then((res) => {
+    const user = res.payload?.message;
+    if (!user || typeof user !== "string") throw new Error("No session user");
+    return http
+      .get<{ message?: string[] }>("/api/method/frappe.core.doctype.user.user.get_roles", {
+        uid: user,
+      })
+      .then((rolesRes) => {
+        const roles = rolesRes.payload?.message;
+        if (!Array.isArray(roles)) throw new Error("No roles returned");
+        return { user, roles };
+      });
+  });
 }
 
 /** A connection that may not name a bench yet (a provider's config before it resolves). */
-type SessionConnection = Omit<FrappeConnection, "baseURL"> & { baseURL?: string };
+export type SessionConnection = Omit<FrappeConnection, "baseURL"> & { baseURL?: string };
 
-export function useSessionRoles(connection: SessionConnection | undefined): string[] | undefined {
+export interface FrappeSession {
+  user?: string;
+  roles?: string[];
+  /**
+   * `idle`: no bench to ask (no connection, a fixtures-only one, or none
+   * given). `loading`: asked, not answered. `ready`: user and roles known.
+   * `failed`: the bench answered without a session (Guest) or refused.
+   */
+  state: "idle" | "loading" | "ready" | "failed";
+}
+
+const idleSession: FrappeSession = { state: "idle" };
+const loadingSession: FrappeSession = { state: "loading" };
+
+export function useFrappeSession(connection: SessionConnection | undefined): FrappeSession {
   const baseURL = connection?.baseURL;
   const fixtures = connection?.fixtures;
-  const [roles, setRoles] = useState<string[] | undefined>(undefined);
+  const active = Boolean(connection) && !fixtures && Boolean(baseURL);
+  const [session, setSession] = useState<FrappeSession>(() =>
+    active ? { state: "loading" } : idleSession,
+  );
   const connectionRef = useRef(connection);
   connectionRef.current = connection;
 
   useEffect(() => {
     const current = connectionRef.current;
     if (!current || fixtures || !baseURL) {
-      setRoles(undefined);
+      setSession(idleSession);
       return;
     }
     let cancelled = false;
-    let promise = rolesCache.get(baseURL);
+    setSession((prev) => (prev.state === "loading" ? prev : { state: "loading" }));
+    let promise = sessionCache.get(baseURL);
     if (!promise) {
-      promise = fetchSessionRoles({ ...current, baseURL });
-      rolesCache.set(baseURL, promise);
-      promise.catch(() => rolesCache.delete(baseURL));
+      promise = fetchSession({ ...current, baseURL });
+      sessionCache.set(baseURL, promise);
+      promise.catch(() => sessionCache.delete(baseURL));
     }
     promise
-      .then((list) => {
-        if (!cancelled) setRoles(list);
+      .then(({ user, roles }) => {
+        if (!cancelled) setSession({ user, roles, state: "ready" });
       })
       .catch(() => {
-        if (!cancelled) setRoles(undefined);
+        if (!cancelled) setSession({ state: "failed" });
       });
     return () => {
       cancelled = true;
     };
   }, [baseURL, fixtures]);
 
-  return roles;
+  if (!active) return idleSession;
+  return session.state === "idle" ? loadingSession : session;
+}
+
+export function useSessionRoles(connection: SessionConnection | undefined): string[] | undefined {
+  return useFrappeSession(connection).roles;
 }