@multiplatform.one/frappe-ui 7.7.4 → 7.8.0

package/src/FrappeTable.tsx

@@ -3,9 +3,7 @@ import {
   Order,
   matchesFilters,
   useDocTypeMeta,
-  useFrappeCollection,
   useFrappeDoctypeEvents,
-  useLiveQuery,
 } from "@multiplatform.one/frappe";
 import {
   DataTable,
@@ -25,12 +23,31 @@ import { FilterManager, SavedFilterDropdown, useSavedFilters } from "@multiplatf
 import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeReconnectIndicator } from "./FrappeReconnectIndicator";
 import { docFieldsToFilterFields } from "./filterFields";
-import { toLiveLoadError } from "./liveErrors";
+import { useFrappeRows } from "./useFrappeRows";
 
 /**
  * Props for the FrappeTable component.
  *
- * @typeParam TDoc - The document type with at least name and doctype fields
+ * `data` is omitted because FrappeTable fetches its own rows. Everything else
+ * on `DataTableProps` passes straight through — including `rowAccumulator`
+ * (MPO-250), so a Frappe-bound table CAN carry a folded column (a running
+ * balance, a per-row cumulative count) without the caller re-fetching the
+ * doctype and hand-assembling a DataTable. Declare the derived field on
+ * `TDoc` so a column can name it in `accessorKey`:
+ *
+ * ```tsx
+ * const balance: RowAccumulator<Partial<Posting>, string> = {
+ *   initial: "0",
+ *   reduce: (carried, row) => addMoney(carried, row.amount ?? "0"),
+ *   derive: (carried) => ({ running: carried }),
+ *   order: (a, b) => compareByDateThenName(a, b),
+ * };
+ * <FrappeTable<Posting & { running?: string }> doctype="Posting" rowAccumulator={balance} … />
+ * ```
+ *
+ * The fold runs over the rows the table HOLDS, before pagination. In
+ * `serverSide` mode that is one page, so a running balance there needs the
+ * server to send the figure — the fold cannot invent rows it never got.
  */
 export interface FrappeTableProps<TDoc extends { name: string; doctype: string }> extends Omit<
   DataTableProps<Partial<TDoc>>,
@@ -310,8 +327,10 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   const finalAuth = auth ?? config?.auth;
   const finalSyncOptions = syncOptions ?? config?.syncOptions;
 
-  if (!finalBaseURL) {
-    throw new Error("FrappeTable requires baseURL prop or FrappeProvider with baseURL");
+  // A fixture corpus is a complete data source, so it satisfies the same
+  // requirement a baseURL does: fixture mode never dials a server.
+  if (!finalBaseURL && !config?.fixtures) {
+    throw new Error("FrappeTable requires baseURL prop or FrappeProvider with baseURL or fixtures");
   }
 
   // One connection config for the live subscription (client mode), the
@@ -324,6 +343,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
       socketBaseURL: config?.socketBaseURL,
       auth: finalAuth,
       syncOptions: finalSyncOptions,
+      realtime: config?.realtime,
       fixtures: config?.fixtures,
     }),
     [
@@ -331,6 +351,7 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
       config?.socketPort,
       config?.siteName,
       config?.socketBaseURL,
+      config?.realtime,
       finalAuth,
       finalSyncOptions,
       config?.fixtures,
@@ -592,32 +613,31 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   // Always call the hook — toggling `savedFilters` must not change hook order (SB-M-012).
   const savedFiltersHook = useSavedFilters({ userId });
 
-  // Honest error surface: the collection swallows initial-sync failures
-  // (renders as empty otherwise); onSyncError turns 403/PermissionError and
-  // network failures into a visible error state.
-  const handleSyncError = useCallback(
-    (err: unknown) => {
-      setErrorState(
-        toLiveLoadError(err, {
-          permissionMessage: t("You do not have permission to view {{doctype}}", { doctype }),
-          genericMessage: t("Error loading {{doctype}}", { doctype }),
-        }),
-      );
-    },
+  // The client/live-collection read is the SHARED one (MPO-251): collection
+  // + live query + the honest error surface a bare collection swallows
+  // (without onSyncError a 403 or a dead server renders as an empty table).
+  // `limit: null` keeps the bench's own page length rather than the hook's
+  // default — FrappeTable paginates on the rows it is handed, and moving its
+  // row ceiling here would move it for every existing consumer.
+  const rowsMessages = useMemo(
+    () => ({
+      permission: t("You do not have permission to view {{doctype}}", { doctype }),
+      generic: t("Error loading {{doctype}}", { doctype }),
+      queryFailed: t("Failed to load {{doctype}}", { doctype }),
+    }),
     [doctype, t],
   );
-
-  const collection = useFrappeCollection<TDoc>(
-    serverSide ? undefined : connectionConfig,
-    serverSide ? "" : doctype,
-    serverSide ? undefined : { fields, filters: activeFilters, onSyncError: handleSyncError },
-  );
   const {
-    data: rawData,
-    isLoading: isRowsLoading,
-    isError: isLiveError,
-  } = useLiveQuery((q) => (collection ? q.from({ _list: collection }) : null), [collection]);
-  const clientRows = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
+    rows: clientRows,
+    isQueryLoading: isRowsLoading,
+    error: liveError,
+  } = useFrappeRows<TDoc>(serverSide ? undefined : connectionConfig, doctype, {
+    fields,
+    filters: activeFilters,
+    limit: null,
+    enabled: !serverSide,
+    messages: rowsMessages,
+  });
 
   // Keep-rows-and-reconcile for client/live-collection mode: a filter change
   // swaps the collection (new subscription), which reports loading from
@@ -659,19 +679,6 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
     ? !infiniteServerMode && serverLoading && hasLoadedOnce
     : isRowsLoading && lastGoodClientRows.current !== null;
 
-  // Reset stale errors when the underlying collection changes (new doctype
-  // or filters) so a recovered query doesn't keep showing the old failure.
-  useEffect(() => {
-    if (!serverSide) setErrorState(null);
-  }, [collection, serverSide]);
-
-  // Fallback surface for live-query failures the collection itself reports
-  // (onSyncError above carries the specific message when available).
-  useEffect(() => {
-    if (serverSide || !isLiveError) return;
-    setErrorState((prev) => prev ?? new Error(t("Failed to load {{doctype}}", { doctype })));
-  }, [serverSide, isLiveError, doctype, t]);
-
   const handleSelectFilter = (filter: any) => {
     if (filter) {
       setActiveFilters(filter.filters);
@@ -695,8 +702,12 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
     await savedFiltersHook.deleteFilter(name);
   };
 
-  if (errorState && error) {
-    return <>{error(errorState)}</>;
+  // serverSide failures come from the fetch above; client/live failures come
+  // from useFrappeRows. Only one path is ever live at a time.
+  const resolvedError = serverSide ? errorState : liveError;
+
+  if (resolvedError && error) {
+    return <>{error(resolvedError)}</>;
   }
 
   const rowData = rows ?? [];
@@ -704,8 +715,8 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   // Infinite serverSide delegates loading/empty chrome to DataTable.
   // After the first load, NEVER replace DataTable with empty/loading chrome
   // while a refetch is in flight — that was the named blank-the-list defect.
-  const boundaryState = errorState
-    ? { error: errorState }
+  const boundaryState = resolvedError
+    ? { error: resolvedError }
     : isRowsLoadingResolved
       ? { loading: loading ?? true }
       : rowData.length === 0 && !infiniteServerMode && !isFetching
@@ -713,7 +724,16 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
         : null;
   if (boundaryState) {
     return (
-      <YStack {...knobProps.gap} flex={1}>
+      <YStack
+        {...knobProps.gap}
+        // flexBasis auto, not flex={1}: a basis-0 chain resolves to 0 in an
+        // auto-height parent and collapses the table to a sliver. Same
+        // geometry as DataTableRoot's own root.
+        flexGrow={1}
+        flexShrink={1}
+        flexBasis="auto"
+        minHeight={0}
+      >
         <FrappeReconnectIndicator config={connectionConfig} />
         <AsyncBoundary
           layout={layout === "list" || layout === "cards" ? "list" : "table"}
@@ -726,7 +746,16 @@ export function FrappeTable<TDoc extends { name: string; doctype: string }>({
   }
 
   return (
-    <YStack {...knobProps.gap} flex={1}>
+    <YStack
+      {...knobProps.gap}
+      // flexBasis auto, not flex={1}: a basis-0 chain resolves to 0 in an
+      // auto-height parent and collapses the table to a sliver. Same
+      // geometry as DataTableRoot's own root.
+      flexGrow={1}
+      flexShrink={1}
+      flexBasis="auto"
+      minHeight={0}
+    >
       <FrappeReconnectIndicator config={connectionConfig} />
       {savedFilters && savedFiltersHook && (
         <XStack {...knobProps.gap} padding="$2">

package/src/FrappeTreeView.stories.tsx

@@ -75,10 +75,23 @@ function regionMeta(name: string, isTree: boolean) {
   };
 }
 
+/** A chart of accounts: no parent field, no is_tree, the name is the path. */
+function accountMeta(name: string) {
+  return {
+    name,
+    module: "QA",
+    title_field: "name",
+    is_tree: 0,
+    fields: [{ fieldname: "balance", fieldtype: "Currency", label: "Balance", in_list_view: 1 }],
+    permissions: [{ role: "All", read: 1 }],
+  };
+}
+
 function handleMetaRequest(url: URL): Response | null {
   const metaMatch = url.pathname.match(/^\/api\/resource\/DocType\/(.+)$/);
   if (!metaMatch) return null;
   const name = decodeURIComponent(metaMatch[1]);
+  if (name === "QaAccount") return jsonResponse({ data: accountMeta(name) });
   return jsonResponse({ data: regionMeta(name, name !== "QaFlatDoc") });
 }
 
@@ -143,6 +156,52 @@ export const NotATree = () => (
   </FrappeProvider>
 );
 
+interface Account {
+  name: string;
+  doctype: string;
+  balance: string;
+}
+
+/**
+ * Seven rows, and every one of them is a leaf. "Assets", "Assets:Personal"
+ * and "Assets:Personal:Bank" are not documents at all.
+ */
+const accountDocs: Account[] = [
+  { name: "Assets:Personal:Bank:Checking", doctype: "QaAccount", balance: "4,120.55" },
+  { name: "Assets:Personal:Bank:Savings", doctype: "QaAccount", balance: "18,300.00" },
+  { name: "Assets:Personal:Cash", doctype: "QaAccount", balance: "260.00" },
+  { name: "Expenses:Groceries", doctype: "QaAccount", balance: "612.40" },
+  { name: "Expenses:Utilities:Power", doctype: "QaAccount", balance: "148.90" },
+  { name: "Income:Salary", doctype: "QaAccount", balance: "9,000.00" },
+  { name: "Liabilities:Credit Card", doctype: "QaAccount", balance: "-732.10" },
+];
+
+/** Colon-path doctype: is_tree is 0, there is no parent field, tree renders. */
+export const ColonPath = () => (
+  <FrappeProvider
+    baseURL={MOCK_HOST}
+    fixtures={new InMemoryFixtureProvider({ QaAccount: accountDocs })}
+  >
+    <FrappeTreeView
+      doctype="QaAccount"
+      pathSeparator=":"
+      pathField="name"
+      valueField="balance"
+      expandByDefault
+      onNodeClick={action("onNodeClick")}
+      onPathSelect={action("onPathSelect")}
+    />
+  </FrappeProvider>
+);
+ColonPath.parameters = {
+  docs: {
+    description: {
+      story:
+        "The account IS its path (Assets:Personal:Bank:Checking). Meta reports is_tree 0 and the doctype has no parent field, so the parent-field path would paint the unsupported state instead. pathSeparator synthesises the branches client-side from each row's own key. A synthesised branch carries no document: clicking it fires onPathSelect with the path and no doc, and onNodeClick stays silent. The balances hang off the leaves, which are the only real rows.",
+    },
+  },
+};
+
 /** Tree doctype with zero root nodes: empty message. */
 export const EmptyTree = () => (
   <FrappeProvider baseURL={MOCK_HOST} fixtures={new InMemoryFixtureProvider({ QaRegionEmpty: [] })}>

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(
@@ -135,6 +233,7 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
       socketBaseURL: config?.socketBaseURL,
       auth: finalAuth,
       syncOptions: finalSyncOptions,
+      realtime: config?.realtime,
       fixtures: config?.fixtures,
     }),
     [
@@ -142,6 +241,7 @@ export function FrappeTreeView<TDoc extends { name: string; doctype: string }>({
       config?.socketPort,
       config?.siteName,
       config?.socketBaseURL,
+      config?.realtime,
       finalAuth,
       finalSyncOptions,
       config?.fixtures,
@@ -150,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, "_")}`;
@@ -158,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) {
@@ -226,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
@@ -241,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/attachments.tsx

@@ -81,6 +81,7 @@ function AttachmentsBody({
             socketBaseURL: config.socketBaseURL,
             auth: config.auth,
             syncOptions: config.syncOptions,
+            realtime: config.realtime,
             fixtures: config.fixtures,
           }
         : undefined,

package/src/components/tags.tsx

@@ -41,6 +41,7 @@ export function Tags({ doctype, docname, onAdd, onRemove, enableAdd, ...props }:
         auth: config.auth,
         syncOptions: config.syncOptions,
         socketOptions: config.socketOptions,
+        realtime: config.realtime,
         fixtures: config.fixtures,
       }
     : undefined;

package/src/components/timeline.tsx

@@ -130,6 +130,7 @@ export function Timeline({
         auth: config.auth,
         syncOptions: config.syncOptions,
         socketOptions: config.socketOptions,
+        realtime: config.realtime,
         fixtures: config.fixtures,
       }
     : undefined;
@@ -207,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 {