@multiplatform.one/frappe-ui 7.7.6 → 7.10.0

package/src/FrappeTreeView.tsx

@@ -1,14 +1,14 @@
-import { useDocTypeMeta, useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
-import { AsyncBoundary, TreeView, type TreeNode } from "@multiplatform.one/components";
+import { useDocTypeMeta } from "@multiplatform.one/frappe";
+import { AsyncBoundary, EmptyState, TreeView, type TreeNode } from "@multiplatform.one/components";
 import { TreeStructureIcon } from "@phosphor-icons/react";
-import React, { useCallback, useEffect, useMemo, useState } from "react";
+import React, { useCallback, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Text, YStack, type YStackProps } from "tamagui";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useGlyphColor, useResolvedKnobs } from "@multiplatform.one/theme";
 import { formCommonColors } from "@multiplatform.one/forms";
 import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeReconnectIndicator } from "./FrappeReconnectIndicator";
-import { toLiveLoadError } from "./liveErrors";
+import { useFrappeRows } from "./useFrappeRows";
 
 export interface FrappeTreeViewProps<TDoc extends { name: string; doctype: string }> extends Omit<
   YStackProps,
@@ -16,11 +16,32 @@ export interface FrappeTreeViewProps<TDoc extends { name: string; doctype: strin
 > {
   doctype: string;
   parentField?: string;
+  /**
+   * Separator that splits {@link FrappeTreeViewProps.pathField} into levels,
+   * e.g. ":" for an account named `Assets:Personal:Bank:Checking`. Setting it
+   * switches the tree to path mode: the branches between root and leaf are
+   * synthesised from the segments, `parentField` is neither read nor fetched,
+   * and the `is_tree` gate is skipped. A doctype whose hierarchy lives in the
+   * row's own key has no parent field and the server will never report
+   * `is_tree`.
+   */
+  pathSeparator?: string;
+  /**
+   * Row field holding the path. Path mode only; defaults to `name`. Path mode
+   * fetches `name`, this field, `valueField` and whatever `fields` adds, so a
+   * caller who needs more on the `onNodeClick` document asks for it there.
+   */
+  pathField?: string;
   titleField?: string;
   valueField?: string;
   fields?: readonly (keyof TDoc & string)[];
   filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, any]>;
   onNodeClick?: (doc: Partial<TDoc>) => void;
+  /**
+   * Path-mode selection, fired for synthesised branches as well as documents.
+   * `doc` is present only when a document actually sits at that path.
+   */
+  onPathSelect?: (path: string, doc?: Partial<TDoc>) => void;
   /** Reserved for future DnD reparenting; not wired yet. */
   enableDragDrop?: boolean;
   /** Expand every branch on first paint (passed through to TreeView). */
@@ -88,20 +109,94 @@ export function buildTreeNodes<TDoc extends { name: string }>(
   return sortDocs(roots).map(buildNode);
 }
 
+/** One level of the path forest, before it becomes TreeNodes. */
+interface PathBucket<TDoc> {
+  path: string;
+  segment: string;
+  doc?: TDoc;
+  children: Map<string, PathBucket<TDoc>>;
+}
+
+/**
+ * Build a TreeNode forest from paths held on the rows themselves, e.g.
+ * `Assets:Personal:Bank:Checking` split on ":".
+ *
+ * The branches between root and leaf are not rows, so they are synthesised:
+ * a synthesised node carries no `data` and its `id` is the path prefix it
+ * stands for. A row whose path value is empty falls back to a single segment
+ * of its own name, so nothing is silently dropped.
+ */
+export function buildPathTreeNodes<TDoc extends { name: string }>(
+  docs: TDoc[],
+  pathField: string,
+  separator: string,
+): TreeNode<Record<string, unknown>>[] {
+  const roots = new Map<string, PathBucket<TDoc>>();
+
+  const splitPath = (doc: TDoc): string[] => {
+    const raw = (doc as Record<string, unknown>)[pathField];
+    const value = raw == null ? "" : String(raw);
+    // An empty separator would split the value into single characters.
+    const segments = separator ? value.split(separator) : [value];
+    const cleaned = segments.map((segment) => segment.trim()).filter((segment) => segment !== "");
+    return cleaned.length > 0 ? cleaned : [doc.name];
+  };
+
+  for (const doc of docs) {
+    let level = roots;
+    let prefix = "";
+    let bucket: PathBucket<TDoc> | undefined;
+    for (const segment of splitPath(doc)) {
+      prefix = prefix ? `${prefix}${separator}${segment}` : segment;
+      bucket = level.get(segment);
+      if (!bucket) {
+        bucket = { path: prefix, segment, children: new Map() };
+        level.set(segment, bucket);
+      }
+      level = bucket.children;
+    }
+    // Two rows on one path: the first keeps the node rather than the last
+    // row the live query happened to deliver.
+    if (bucket && !bucket.doc) bucket.doc = doc;
+  }
+
+  const toNodes = (level: Map<string, PathBucket<TDoc>>): TreeNode<Record<string, unknown>>[] =>
+    Array.from(level.values())
+      .sort((a, b) => a.segment.localeCompare(b.segment))
+      .map((bucket) => {
+        const children = toNodes(bucket.children);
+        return {
+          id: bucket.path,
+          label: bucket.segment,
+          data: bucket.doc as unknown as Record<string, unknown> | undefined,
+          children: children.length > 0 ? children : undefined,
+        };
+      });
+
+  return toNodes(roots);
+}
+
 /**
  * Thin Frappe wrapper around the generic TreeView component.
  *
  * Fetches the full DocType list via `useFrappeCollection` / `useLiveQuery`
  * (realtime-backed), then builds a `TreeNode` forest from the parent field.
+ *
+ * Pass `pathSeparator` instead when the hierarchy lives in the row's own key
+ * (`Assets:Personal:Bank:Checking`). The branches are synthesised client-side,
+ * so no parent field and no `is_tree` are needed.
  */
 export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
   doctype,
   parentField: parentFieldProp,
+  pathSeparator,
+  pathField,
   titleField: titleFieldProp,
   valueField,
   fields,
   filters,
   onNodeClick,
+  onPathSelect,
   enableDragDrop: _enableDragDrop = false,
   expandByDefault = false,
   display = "default",
@@ -116,6 +211,7 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
 
   const config = useFrappeConfig();
   const { knobProps } = useResolvedKnobs();
+  const emptyIconColor = useGlyphColor(formCommonColors.muted);
   const { t } = useTranslation();
   const [selectedId, setSelectedId] = useState<string | undefined>();
 
@@ -123,8 +219,10 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
   const finalAuth = auth ?? config?.auth;
   const finalSyncOptions = syncOptions ?? config?.syncOptions;
 
-  if (!finalBaseURL) {
-    throw new Error("FrappeTreeView requires baseURL prop or FrappeProvider with baseURL");
+  if (!finalBaseURL && !config?.fixtures) {
+    throw new Error(
+      "FrappeTreeView requires baseURL prop or FrappeProvider with baseURL or fixtures",
+    );
   }
 
   const appConfig = useMemo(
@@ -152,6 +250,8 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
 
   const { meta, isLoading: isMetaLoading, error: metaError } = useDocTypeMeta(appConfig, doctype);
 
+  const isPathMode = !!pathSeparator;
+  const effectivePathField = pathField ?? "name";
   const effectiveTitleField = titleFieldProp ?? meta?.title_field ?? "name";
   const effectiveParentField =
     parentFieldProp ?? `parent_${doctype.toLowerCase().replace(/ /g, "_")}`;
@@ -160,67 +260,75 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
   // lets callers continue (Guest peek / offline). Successful meta always
   // wins for the is_tree gate — including rejecting flat DocTypes that
   // happened to pass parentField.
-  const isKnownNotTree = !!meta && !meta.is_tree;
-  const canProceed = !!meta?.is_tree || (!!metaError && !meta && !!parentFieldProp);
+  //
+  // Path mode is the exception: the hierarchy comes from the row's own key,
+  // so there is nothing for is_tree to be right about.
+  const isKnownNotTree = !isPathMode && !!meta && !meta.is_tree;
+  const canProceed = isPathMode || !!meta?.is_tree || (!!metaError && !meta && !!parentFieldProp);
 
   const effectiveFields = useMemo(() => {
     const fieldSet = new Set<string>(fields as string[] | undefined);
     fieldSet.add("name");
-    fieldSet.add(effectiveTitleField);
-    fieldSet.add(effectiveParentField);
+    if (isPathMode) {
+      // The parent field does not exist on a path-shaped doctype; asking for
+      // it would fail the read on a live bench.
+      fieldSet.add(effectivePathField);
+    } else {
+      fieldSet.add(effectiveTitleField);
+      fieldSet.add(effectiveParentField);
+    }
     if (valueField) fieldSet.add(valueField);
     return Array.from(fieldSet) as (keyof TDoc & string)[];
-  }, [fields, effectiveTitleField, effectiveParentField, valueField]);
-
-  // Honest error surface: without onSyncError a 403/network failure renders
-  // as an empty tree.
-  const [syncError, setSyncError] = useState<Error | null>(null);
-  const handleSyncError = useCallback(
-    (err: unknown) => {
-      setSyncError(
-        toLiveLoadError(err, {
-          permissionMessage: t("You do not have permission to view {{doctype}}", { doctype }),
-          genericMessage: t("Failed to load {{doctype}} tree", { doctype }),
-        }),
-      );
-    },
-    [doctype, t],
-  );
+  }, [
+    fields,
+    isPathMode,
+    effectivePathField,
+    effectiveTitleField,
+    effectiveParentField,
+    valueField,
+  ]);
 
-  const collection = useFrappeCollection<TDoc>(
-    canProceed && !isKnownNotTree ? appConfig : undefined,
-    doctype,
-    { fields: effectiveFields, filters, onSyncError: handleSyncError },
+  // The shared doctype read (MPO-251): collection + live query + the honest
+  // error surface a bare collection swallows — without it a 403 or a network
+  // failure renders as an empty tree. `limit: null` keeps the tree on the
+  // bench's own page length, as it was before the hook existed.
+  const rowsMessages = useMemo(
+    () => ({
+      permission: t("You do not have permission to view {{doctype}}", { doctype }),
+      generic: t("Failed to load {{doctype}} tree", { doctype }),
+    }),
+    [doctype, t],
   );
-
-  // A new collection (doctype/filter change) starts with a clean slate.
-  useEffect(() => {
-    setSyncError(null);
-  }, [collection]);
-
   const {
-    data: rawData,
-    isLoading: isDataLoading,
-    isError,
-  } = useLiveQuery((q) => (collection ? q.from({ _list: collection }) : null), [collection]);
-
-  const docs = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
+    rows: docs,
+    isQueryLoading: isDataLoading,
+    error: queryError,
+  } = useFrappeRows<TDoc>(appConfig, doctype, {
+    fields: effectiveFields,
+    filters,
+    limit: null,
+    enabled: canProceed && !isKnownNotTree,
+    messages: rowsMessages,
+  });
 
   const treeNodes = useMemo(
-    () => buildTreeNodes(docs, effectiveParentField, effectiveTitleField),
-    [docs, effectiveParentField, effectiveTitleField],
+    () =>
+      pathSeparator
+        ? buildPathTreeNodes(docs, effectivePathField, pathSeparator)
+        : buildTreeNodes(docs, effectiveParentField, effectiveTitleField),
+    [docs, pathSeparator, effectivePathField, effectiveParentField, effectiveTitleField],
   );
 
-  const queryError =
-    syncError ?? (isError ? new Error(t("Failed to load {{doctype}} tree", { doctype })) : null);
-
   const handleNodeSelect = useCallback(
     (node: TreeNode<Record<string, unknown>>) => {
       setSelectedId(node.id);
+      if (isPathMode) onPathSelect?.(node.id, node.data as Partial<TDoc> | undefined);
+      // A synthesised branch is not a document, so onNodeClick stays silent
+      // rather than handing a caller a name that would 404 on open.
       if (!node.data) return;
       onNodeClick?.(node.data as Partial<TDoc>);
     },
-    [onNodeClick],
+    [isPathMode, onNodeClick, onPathSelect],
   );
 
   if (isMetaLoading) {
@@ -228,7 +336,7 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
     return <AsyncBoundary layout="list" loading {...stackProps} />;
   }
 
-  if (metaError && !meta && !parentFieldProp) {
+  if (metaError && !meta && !parentFieldProp && !isPathMode) {
     if (error) return <>{error(metaError)}</>;
     return (
       <AsyncBoundary
@@ -243,12 +351,14 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
   if (isKnownNotTree) {
     const iconSize = Number(knobProps.controlIcon?.width) || 16;
     return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap} {...stackProps}>
-        <TreeStructureIcon size={iconSize * 2} color={formCommonColors.muted} />
-        <Text color={formCommonColors.muted} {...knobProps.body}>
-          {t("This DocType does not support tree view")}
-        </Text>
-      </YStack>
+      <EmptyState
+        title={t("This DocType does not support tree view")}
+        description={t(
+          "Pass pathSeparator and pathField to build the hierarchy from a path-shaped value on each row. parentField alone does not, because a flat DocType has no parent field.",
+        )}
+        icon={<TreeStructureIcon size={iconSize * 2} color={emptyIconColor} />}
+        {...stackProps}
+      />
     );
   }
 

package/src/commentActions.ts

@@ -67,7 +67,7 @@ export function useFrappeCommentActions(
 ): FrappeCommentActions {
   return useMemo(() => {
     const app =
-      config && !config.fixtures
+      config?.baseURL && !config.fixtures
         ? new FrappeApp(config.baseURL, (config.auth ?? {}) as Record<string, unknown>)
         : undefined;
 

package/src/components/timeline.tsx

@@ -208,7 +208,7 @@ export function Timeline({
 
   const resolveSessionUser = useCallback(async (): Promise<string> => {
     if (sessionUserRef.current) return sessionUserRef.current;
-    if (config && !config.fixtures) {
+    if (config?.baseURL && !config.fixtures) {
       const app = new FrappeApp(config.baseURL, (config.auth ?? {}) as Record<string, unknown>);
       sessionUserRef.current = await app.auth().getLoggedInUser();
     } else {

package/src/desk/DeskShell.tsx

@@ -209,6 +209,7 @@ export function DeskShell({
         {showSidebar && !isNarrow && (
           <YStack
             role="navigation"
+            aria-label={t("Desk navigation")}
             id="desk-sidebar"
             flexShrink={0}
             data-testid="desk-sidebar-rail"
@@ -234,6 +235,7 @@ export function DeskShell({
             />
             <YStack
               role="navigation"
+              aria-label={t("Desk navigation")}
               id="desk-sidebar"
               position="absolute"
               top={0}

package/src/desk/awesomebar.tsx

@@ -101,7 +101,10 @@ async function addRecentSearch(query: string): Promise<void> {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function createHttpClientFromConfig(config: FrappeConnectionConfig): HttpClient {
+function createHttpClientFromConfig(config: {
+  baseURL: string;
+  auth?: FrappeConnectionConfig["auth"];
+}): HttpClient {
   return new HttpClient(
     config.baseURL,
     config.auth as Parameters<typeof HttpClient.prototype.updateAuth>[0],
@@ -168,7 +171,7 @@ export function Awesomebar({ onNavigate, basePath = "/desk", ...stackProps }: Aw
   // HttpClient ref for document search
   const httpRef = useRef<HttpClient | undefined>(undefined);
   const configKeyRef = useRef("");
-  if (config) {
+  if (config?.baseURL) {
     const key = `${config.baseURL}:${config.auth?.token ?? ""}`;
     if (key !== configKeyRef.current) {
       httpRef.current = createHttpClientFromConfig({

package/src/fields/CodeEditor/CodeEditor.spec.tsx

@@ -29,12 +29,10 @@ function readCodeEditorSource() {
   return readFileSync(join(codeEditorDir(), "index.tsx"), "utf8");
 }
 
-function readCodeEditorStories() {
-  return readFileSync(join(codeEditorDir(), "CodeEditor.stories.tsx"), "utf8");
-}
-
 afterEach(cleanup);
 
+vi.mock("@multiplatform.one/storybook", () => ({ action: () => vi.fn() }));
+
 describe("frappeCodeLanguage (stock ControlCode language_map)", () => {
   it("maps stock Frappe options case-insensitively", () => {
     expect(frappeCodeLanguage("Python")).toBe("python");
@@ -102,11 +100,14 @@ describe("CodeEditorField (standalone)", () => {
     expect(result.getTextArea()).toBeNull();
   });
 
-  it("ships CSF3 story objects so native gallery keeps args (KS blank-pane)", () => {
-    const stories = readCodeEditorStories();
-    expect(stories).toMatch(/export const Main = \{/);
-    expect(stories).not.toMatch(/Main\.args\s*=/);
-    expect(stories).toContain("value: PYTHON_FIXTURE");
+  it("ships CSF3 story objects so native gallery keeps args (KS blank-pane)", async () => {
+    const { Main, Json, ReadOnly } = await import("./CodeEditor.stories");
+    for (const story of [Main, Json, ReadOnly]) {
+      expect(typeof story).toBe("object");
+      expect(story.render).toBeTypeOf("function");
+      expect(story.args.value?.trim().length).toBeGreaterThan(0);
+    }
+    expect(ReadOnly.args.readOnly).toBe(true);
   });
 
   it("forwards knob containerRadius onto the source textarea (F14)", () => {

package/src/fields/Date/Date.spec.tsx

@@ -10,7 +10,7 @@
  * a seeded value is not a user edit).
  */
 
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeAll } from "vitest";
 
 // The first field-module import in a cold fork transforms the whole fields
 // graph (same budget as tests/fieldRenderers.spec.tsx).
@@ -79,6 +79,13 @@ function getDayButton(root: ParentNode, day: number): HTMLButtonElement | undefi
   });
 }
 
+// Warm the graph here, not inside the first `it`: the transform is setup cost
+// (110-155s quiet, past 240s under load), and charging it to an assertion made
+// whichever case ran first time out.
+beforeAll(async () => {
+  await loadDateField();
+}, 900_000);
+
 describe("Date wrapper — late-arriving value display", () => {
   it("a value arriving after mount displays, without onChange", async () => {
     const DateField = await loadDateField();

package/src/fields/Date/nativePresentation.spec.tsx

@@ -18,7 +18,7 @@
  * than rendered) and the platform flags.
  */
 
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeAll, beforeEach } from "vitest";
 
 // Same cold-fork budget as the sibling Date.spec.tsx: the first field-module
 // import transforms the whole fields graph.
@@ -132,6 +132,13 @@ async function press(root: ParentNode, text: string) {
 const lastPick = () => mockState.picks[mockState.picks.length - 1];
 const waitForPick = (predicate: () => void) => waitFor(predicate, { timeout: 30_000 });
 
+// Warm the graph here, not inside the first `it`: the transform is setup cost
+// (110-155s quiet, past 240s under load), and charging it to an assertion made
+// whichever case ran first time out.
+beforeAll(async () => {
+  await loadNativeDateField();
+}, 900_000);
+
 beforeEach(() => {
   // The iOS sheet is a portal, so a previous case's chrome would otherwise
   // still be in the document when the next one asserts on it.

package/src/fields/Date/typeParity.spec.tsx

@@ -17,7 +17,7 @@
  * rather than rendered) and the platform flags. The web half imports neither.
  */
 
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeAll, beforeEach } from "vitest";
 
 // Same cold-fork budget as the sibling Date specs: the first field-module
 // import transforms the whole fields graph.
@@ -168,6 +168,21 @@ async function pressText(root: ParentNode, text: string) {
   });
 }
 
+async function selectPeriod(period: "AM" | "PM") {
+  const wheel = document.querySelector('[role="slider"][aria-label="AM/PM"]');
+  expect(wheel).toBeTruthy();
+  await act(async () => {
+    fireEvent.keyDown(wheel!, { key: period === "AM" ? "Home" : "End" });
+  });
+}
+
+// Warm the graph here, not inside the first `it`: the transform is setup cost
+// (110-155s quiet, past 240s under load), and charging it to an assertion made
+// whichever case ran first time out.
+beforeAll(async () => {
+  await Promise.all([loadWebDateField(), loadNativeDateField()]);
+}, 900_000);
+
 beforeEach(() => {
   // Both halves portal their surfaces, so a previous case's chrome would
   // otherwise still be in the document when the next one queries it.
@@ -194,7 +209,7 @@ describe("web Date field — type=date keeps the calendar", () => {
     await openPanel(triggerInput(result.container)!);
     expect(panelText()).toContain("Su");
     // A date-only control offers no clock.
-    expect(panelText()).not.toMatch(/\bHour\b/);
+    expect(document.querySelector('[role="slider"][aria-label="Hour"]')).toBeNull();
 
     await waitFor(() => expect(dayCell(15)).toBeTruthy(), { timeout: 30_000 });
     await act(async () => {
@@ -226,8 +241,8 @@ describe("web Date field — type=time renders a time control", () => {
     );
     await openPanel(triggerInput(result.container)!);
     const text = panelText();
-    expect(text).toContain("Hour");
-    expect(text).toContain("Min");
+    expect(document.querySelector('[role="slider"][aria-label="Hour"]')).toBeTruthy();
+    expect(document.querySelector('[role="slider"][aria-label="Min"]')).toBeTruthy();
     expect(text).not.toContain("Su");
   });
 
@@ -239,11 +254,11 @@ describe("web Date field — type=time renders a time control", () => {
     );
     await openPanel(triggerInput(result.container)!);
     // 9:00 AM → PM is a deterministic edit with no wheel animation in it.
-    await pressText(document.body, "PM");
+    await selectPeriod("PM");
 
     // The control speaks `HH:mm`; the field re-serializes through the shared
     // wire body, so what persists carries seconds like every other writer.
-    expect(onChange).toHaveBeenCalledWith("21:00:00");
+    await waitFor(() => expect(onChange).toHaveBeenCalledWith("21:00:00"));
   });
 
   it("adopts a seconds-less HH:mm value too (what Frappe hands a fresh field)", async () => {
@@ -292,7 +307,9 @@ describe("web Date field — type=datetime renders date AND time", () => {
     await openPanel(triggerInput(result.container)!);
     expect(panelText()).toContain("Su");
     await pressText(document.body, "Time");
-    await waitFor(() => expect(panelText()).toContain("Hour"), { timeout: 30_000 });
+    await waitFor(() =>
+      expect(document.querySelector('[role="slider"][aria-label="Hour"]')).toBeTruthy(),
+    );
   });
 
   it("a day change keeps the existing time — and the picker, not the serializer, keeps it", async () => {
@@ -330,8 +347,8 @@ describe("web Date field — type=datetime renders date AND time", () => {
     await pressText(document.body, "Time");
     // 2:30 PM → AM. Carrying `previousValue` here would have pinned the old
     // 14:30 back over the edit the user just made.
-    await pressText(document.body, "AM");
-    expect(onChange).toHaveBeenLastCalledWith("2026-03-05 02:30:00");
+    await selectPeriod("AM");
+    await waitFor(() => expect(onChange).toHaveBeenLastCalledWith("2026-03-05 02:30:00"));
   });
 });
 
@@ -412,7 +429,7 @@ describe("web and native persist byte-identical wire strings", () => {
 
   it("time — moving 9:00 AM to 9:00 PM writes the same string on both halves", async () => {
     const web = await webPick("time", "09:00:00", async () => {
-      await pressText(document.body, "PM");
+      await selectPeriod("PM");
     });
     cleanup();
     mockState.picks.length = 0;