@multiplatform.one/frappe-ui 7.28.0 → 7.29.0

package/src/FrappeReportBuilder.tsx

@@ -1,64 +1,246 @@
-import { useDocTypeMeta, useFrappeDoctypeEvents } from "@multiplatform.one/frappe";
-import { downloadBlob } from "@multiplatform.one/platform";
+/**
+ * FrappeReportBuilder — a doctype's report view, the desk's
+ * /app/<doctype>/view/report (MPO-15, GL-28). The desk's view=report renders
+ * this component, so an app that reaches for it gets the same report the desk
+ * shows:
+ *   - desk default columns (name, status, title/image fields, in_list_view
+ *     and in_standard_filter fields, currency sources, modified), a column
+ *     picker whose choice persists per doctype on this device while no saved
+ *     report is selected
+ *   - a per-column filter row on the standard frappe filter pipeline
+ *   - one toolbar row: columns, group-by, saved reports, filter chips, export
+ *   - saved reports on the `Report` doctype, the records desk's "Select
+ *     Report" lists (in memory on a fixture corpus)
+ *   - live rows through the collection channel: the full filtered result
+ *     stays client-side (totals and export need it), ordered
+ *     deterministically and paged client-side, with a totals row
+ *   - a reader refused DocType meta (Guest) still gets the rows, laid out
+ *     from `initialColumns` or one record's own fields, with nothing to save
+ *     (LC-96); rows refused too is a permission state, never a retry
+ * The model is `./report/reportViewModel`; navigation, scope and the selected
+ * saved report come in as props, so the desk and a plain app mount the same
+ * component.
+ */
 import {
-  ReportBuilder,
-  PopoverContent,
-  Separator,
-  type ReportColumn,
+  BarChart,
+  EmptyState,
+  ScrollView,
+  Spinner,
+  YStack,
+  isWeb,
+  notify,
   type GroupByConfig,
+  type ReportColumn,
 } from "@multiplatform.one/components";
-import { Button, Input, Spinner, formCommonColors } from "@multiplatform.one/forms";
+import {
+  Order,
+  frappeFieldTypes,
+  useDocTypeMeta,
+  type DocTypeField,
+  type FrappeFieldType,
+} from "@multiplatform.one/frappe";
+import { Button } from "@multiplatform.one/forms";
+import { downloadBlob } from "@multiplatform.one/platform";
 import { storage } from "@multiplatform.one/store";
-import React, { useMemo, useState, useCallback, useEffect, useRef } from "react";
-import { useTranslation } from "react-i18next";
-import { Popover, Text, XStack, YStack, type YStackProps } from "tamagui";
-import { FloppyDiskIcon, FolderOpenIcon, TrashIcon } from "@phosphor-icons/react";
+import { DataTablePagination } from "@multiplatform.one/table";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
+import React, { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import type { YStackProps } from "tamagui";
+import { FrappeNotConfigured } from "./FrappeNotConfigured";
 import { useFrappeConfig } from "./FrappeProvider";
+import { isPermissionError, refusalReason } from "./liveErrors";
+import { recordKeyLabel, useRecordShape } from "./recordShape";
+import { ReportGrid } from "./report/ReportGrid";
+import { ReportViewToolbar } from "./report/ReportViewToolbar";
+import {
+  DEFAULT_REPORT_PAGE_SIZE,
+  REPORT_PAGE_SIZES,
+  buildGridRows,
+  buildReportCsv,
+  columnFilterTuples,
+  computeTotals,
+  defaultReportFieldnames,
+  orderReportRows,
+  reportColumnsFromMeta,
+  resolveSelectedColumns,
+  type ReportFilters,
+  type ReportMetaSource,
+  type ReportRow,
+  type ReportSortState,
+} from "./report/reportViewModel";
+import { useSavedReports } from "./report/savedReports";
 import { useFrappeRows } from "./useFrappeRows";
 
-// ============================================================================
-// Saved Report Types (Frappe-specific persisted storage)
-// ============================================================================
+type FilterTuple = [string, string, unknown];
 
-interface SavedReport {
-  name: string;
-  columns: string[];
-  groupBy: GroupByConfig | null;
-  filters: Record<string, unknown> | Array<[string, string, unknown]> | undefined;
+export interface FrappeReportBuilderProps extends Omit<YStackProps, "children"> {
+  /** Proper-cased doctype name (e.g. "ToDo", "Sales Order"). */
+  doctype: string;
+  /**
+   * The report's own filters (a deep link, a host's preset). They show as
+   * chips the user can clear. The object form means `field = value`.
+   */
+  filters?: Record<string, unknown> | FilterTuple[];
+  /**
+   * Filters ANDed into every query: invisible to the chips and not
+   * clearable (a desk or tenant scope).
+   */
+  scopeFilters?: FilterTuple[];
+  /** After the user clears `filters`, so a host can drop them from its address too. */
+  onClearFilters?: () => void;
+  /**
+   * Starting columns by fieldname, or as `ReportColumn` rows (the enabled
+   * ones). Defaults to desk's default columns.
+   */
+  initialColumns?: ReadonlyArray<string | ReportColumn>;
+  /** Starting group-by field; a `GroupByConfig` also sets the chart's aggregation. */
+  initialGroupBy?: string | GroupByConfig;
+  /** A bar chart of the groups above the grid while the rows are grouped. */
+  showChart?: boolean;
+  /** Open a row's document. */
+  onOpenRow?: (name: string) => void;
+  /** A row press with the row and its index in the full ordered result. */
+  onRowPress?: (row: Record<string, unknown>, index: number) => void;
+  /** Open a Link cell's target document. */
+  onOpenLink?: (doctype: string, name: string) => void;
+  /**
+   * The selected saved report (a `Report Builder` Report doc name), or null
+   * for an unsaved report. Given, the selection is controlled.
+   */
+  report?: string | null;
+  onReportChange?: (report: string | null) => void;
+  /** Replaces the CSV download; receives the full filtered, ordered rows. */
+  onExport?: (rows: Record<string, unknown>[]) => void;
+  /** Shown while the doctype's meta loads. */
+  loading?: ReactNode;
+  /** Shown when the doctype's meta cannot be read. */
+  error?: (error: Error) => ReactNode;
+  baseURL?: string;
+  auth?: { useToken?: boolean; token?: string; type?: string };
+  syncOptions?: Record<string, unknown>;
 }
 
-function getSavedReportsKey(doctype: string) {
-  return `frappe-report-${doctype}`;
+const EMPTY_FILTERS: ReportFilters = [];
+const COLUMN_FILTER_DEBOUNCE_MS = 350;
+
+function columnsStorageKey(doctype: string): string {
+  return `backoffice.report.columns.${doctype}`;
 }
 
-async function loadSavedReports(doctype: string): Promise<SavedReport[]> {
+async function readStoredColumns(doctype: string): Promise<string[] | undefined> {
   try {
-    const raw = await Promise.resolve(storage.getItem(getSavedReportsKey(doctype)));
-    if (raw) return JSON.parse(raw) as SavedReport[];
+    const raw = await Promise.resolve(storage.getItem(columnsStorageKey(doctype)));
+    if (!raw) return undefined;
+    const parsed: unknown = JSON.parse(raw);
+    if (Array.isArray(parsed) && parsed.every((entry) => typeof entry === "string")) {
+      return parsed as string[];
+    }
   } catch {
-    // storage not available
+    // storage unavailable or corrupted — defaults win
   }
-  return [];
+  return undefined;
 }
 
-async function persistSavedReports(doctype: string, reports: SavedReport[]): Promise<void> {
+function persistStoredColumns(doctype: string, fieldnames: readonly string[]): void {
   try {
-    await Promise.resolve(storage.setItem(getSavedReportsKey(doctype), JSON.stringify(reports)));
+    void Promise.resolve(storage.setItem(columnsStorageKey(doctype), JSON.stringify(fieldnames)));
   } catch {
-    // storage not available
+    // storage unavailable — selection stays session-only
   }
 }
 
-// ============================================================================
-// Export capability
-// ============================================================================
+/** `{field: value}` → equality tuples; tuple arrays pass through. */
+function toReportFilters(filters: FrappeReportBuilderProps["filters"]): ReportFilters | undefined {
+  if (!filters) return undefined;
+  if (Array.isArray(filters)) return filters.length > 0 ? filters : undefined;
+  const tuples = Object.entries(filters).map(([field, value]): FilterTuple => [field, "=", value]);
+  return tuples.length > 0 ? tuples : undefined;
+}
+
+function initialFieldnames(columns: FrappeReportBuilderProps["initialColumns"]): string[] | null {
+  if (!columns) return null;
+  const fieldnames = columns.flatMap((column) =>
+    typeof column === "string" ? [column] : column.enabled ? [column.fieldname] : [],
+  );
+  return fieldnames.length > 0 ? fieldnames : null;
+}
+
+function asFieldType(fieldtype: string | undefined): FrappeFieldType {
+  return frappeFieldTypes.find((known) => known === fieldtype) ?? "Data";
+}
+
+/**
+ * What a reader refused DocType meta lays the report out from (LC-96): the
+ * host's `initialColumns`, else one record's own fields. Read-only and all in
+ * the default columns.
+ */
+function refusedMetaFields(
+  initialColumns: FrappeReportBuilderProps["initialColumns"],
+  recordFields: readonly DocTypeField[] | undefined,
+): DocTypeField[] {
+  const declared = (initialColumns ?? []).map(
+    (column): DocTypeField =>
+      typeof column === "string"
+        ? { fieldname: column, label: recordKeyLabel(column), fieldtype: "Data" }
+        : {
+            fieldname: column.fieldname,
+            label: column.label,
+            fieldtype: asFieldType(column.fieldtype),
+          },
+  );
+  return (declared.length > 0 ? declared : (recordFields ?? []))
+    .filter((field) => field.fieldname !== "name")
+    .map((field) => ({ ...field, read_only: 1, in_list_view: 1 }));
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function groupField(groupBy: FrappeReportBuilderProps["initialGroupBy"]): string | null {
+  if (!groupBy) return null;
+  return typeof groupBy === "string" ? groupBy : groupBy.field;
+}
+
+/** Group value → aggregate over its rows (count unless the config names one). */
+function aggregateGroups(
+  rows: readonly ReportRow[],
+  field: string,
+  config: GroupByConfig | undefined,
+): Array<{ label: string; value: number }> {
+  const groups = new Map<string, ReportRow[]>();
+  for (const row of rows) {
+    const key = row[field] === null || row[field] === undefined ? "" : String(row[field]);
+    const bucket = groups.get(key);
+    if (bucket) bucket.push(row);
+    else groups.set(key, [row]);
+  }
+  const numbers = (group: ReportRow[]) =>
+    group.map((row) => Number(config?.aggregationField ? row[config.aggregationField] : 0) || 0);
+  return [...groups.entries()].map(([label, group]) => {
+    switch (config?.aggregationField ? config.aggregation : "count") {
+      case "sum":
+        return { label, value: numbers(group).reduce((sum, value) => sum + value, 0) };
+      case "avg":
+        return {
+          label,
+          value: numbers(group).reduce((sum, value) => sum + value, 0) / group.length,
+        };
+      case "min":
+        return { label, value: Math.min(...numbers(group)) };
+      case "max":
+        return { label, value: Math.max(...numbers(group)) };
+      default:
+        return { label, value: group.length };
+    }
+  });
+}
 
 /**
- * Download capability for the built-in CSV export path. `downloadBlob` rides
- * a DOM anchor + object URL, and its native/GTK twins warn + no-op — so the
- * Export button is hidden where no file could actually be delivered (B12).
- * Presence checks, not `typeof window`: Hermes defines `window` without DOM.
+ * The export button needs somewhere to put a file: a DOM anchor and an
+ * object URL. Native and GTK have neither, so the built-in CSV path is left
+ * out there (B12); a host `onExport` owns delivery and shows everywhere.
  */
 function canDownloadCsv(): boolean {
   return (
@@ -70,418 +252,646 @@ function canDownloadCsv(): boolean {
   );
 }
 
-// ============================================================================
-// Props
-// ============================================================================
-
-export interface FrappeReportBuilderProps extends Omit<YStackProps, "children"> {
-  doctype: string;
-  initialColumns?: ReportColumn[];
-  initialGroupBy?: GroupByConfig;
-  filters?: Record<string, unknown> | Array<[string, string, unknown]>;
-  showChart?: boolean;
-  onExport?: (data: Record<string, unknown>[]) => void;
-  /** Row press handler — threaded to the generic ReportBuilder rows */
-  onRowPress?: (row: Record<string, unknown>, index: number) => void;
-  baseURL?: string;
-  auth?: { useToken?: boolean; token?: string; type?: string };
-  syncOptions?: Record<string, unknown>;
+export function FrappeReportBuilder(props: FrappeReportBuilderProps) {
+  const config = useFrappeConfig();
+  if (!(props.baseURL ?? config?.baseURL) && !config?.fixtures) {
+    return <FrappeNotConfigured doctype={props.doctype} />;
+  }
+  return <FrappeReportBuilderBody {...props} />;
 }
 
-// ============================================================================
-// Component
-// ============================================================================
-
-/**
- * Thin Frappe wrapper around the generic ReportBuilder component.
- *
- * Fetches DocType metadata and data via Frappe hooks, then passes
- * column definitions and data to the generic `ReportBuilder` from
- * `@multiplatform.one/components`. Adds Frappe-specific features:
- * save/load reports to shared storage, CSV export.
- */
-export function FrappeReportBuilder({
+function FrappeReportBuilderBody({
   doctype,
+  filters,
+  scopeFilters,
+  onClearFilters,
   initialColumns,
   initialGroupBy,
-  filters,
   showChart = false,
-  onExport,
+  onOpenRow,
   onRowPress,
+  onOpenLink,
+  report: reportProp,
+  onReportChange,
+  onExport,
+  loading: loadingFallback,
+  error: errorFallback,
   baseURL,
   auth,
   syncOptions,
   ...stackProps
 }: FrappeReportBuilderProps) {
-  const config = useFrappeConfig();
-  const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
-
+  const { knobProps } = useResolvedKnobs();
+  const config = useFrappeConfig();
   const finalBaseURL = baseURL ?? config?.baseURL;
   const finalAuth = auth ?? config?.auth;
   const finalSyncOptions = syncOptions ?? config?.syncOptions;
-
-  if (!finalBaseURL && !config?.fixtures) {
-    throw new Error(
-      "FrappeReportBuilder requires baseURL prop or FrappeProvider with baseURL or fixtures",
+  const fixtureMode = Boolean(config?.fixtures);
+
+  const connection = useMemo(
+    () => ({
+      baseURL: finalBaseURL,
+      socketPort: config?.socketPort,
+      siteName: config?.siteName,
+      socketBaseURL: config?.socketBaseURL,
+      auth: finalAuth,
+      syncOptions: finalSyncOptions,
+      realtime: config?.realtime,
+      fixtures: config?.fixtures,
+    }),
+    [
+      finalBaseURL,
+      config?.socketPort,
+      config?.siteName,
+      config?.socketBaseURL,
+      finalAuth,
+      finalSyncOptions,
+      config?.realtime,
+      config?.fixtures,
+    ],
+  );
+  const { meta, isLoading: metaLoading, error: metaError } = useDocTypeMeta(connection, doctype);
+  const metaRefused = !meta && metaError !== undefined && isPermissionError(metaError);
+  const initialColumnsJson = JSON.stringify(initialColumns ?? []);
+  const declaresColumns = initialColumnsJson !== "[]";
+  const recordShape = useRecordShape(connection, doctype, metaRefused && !declaresColumns);
+  const layoutMeta = useMemo((): ReportMetaSource | undefined => {
+    if (meta) return meta;
+    if (!metaRefused) return undefined;
+    const fields = refusedMetaFields(
+      JSON.parse(initialColumnsJson) as FrappeReportBuilderProps["initialColumns"],
+      recordShape.fields,
     );
-  }
+    return fields.length > 0 ? { fields } : undefined;
+  }, [meta, metaRefused, initialColumnsJson, recordShape.fields]);
+  const readsWithoutMeta = !meta && layoutMeta !== undefined;
+  const savedReports = useSavedReports(
+    doctype,
+    useMemo(
+      () => ({
+        baseURL: metaRefused ? "" : (connection.baseURL ?? ""),
+        auth: connection.auth,
+        fixtures: connection.fixtures,
+      }),
+      [metaRefused, connection.baseURL, connection.auth, connection.fixtures],
+    ),
+  );
 
-  const connectionConfig = {
-    baseURL: finalBaseURL,
-    socketPort: config?.socketPort,
-    siteName: config?.siteName,
-    socketBaseURL: config?.socketBaseURL,
-    auth: finalAuth,
-    syncOptions: finalSyncOptions,
-    realtime: config?.realtime,
-    fixtures: config?.fixtures,
-  };
-
-  // Metadata
-  const {
-    meta,
-    isLoading: isMetaLoading,
-    error: metaError,
-  } = useDocTypeMeta(connectionConfig, doctype);
-
-  // Column definitions from meta
-  const allColumns = useMemo((): ReportColumn[] => {
-    if (initialColumns) return initialColumns;
-    if (!meta) return [];
-    return meta.fields
-      .filter(
-        (f) =>
-          f.fieldtype !== "Section Break" &&
-          f.fieldtype !== "Column Break" &&
-          f.fieldtype !== "Tab Break",
-      )
-      .map((f) => ({
-        fieldname: f.fieldname,
-        label: f.label || f.fieldname,
-        fieldtype: f.fieldtype,
-        enabled: !!f.in_list_view,
-      }));
-  }, [initialColumns, meta]);
-
-  // Data fetching
-  const fetchFields = useMemo(() => {
-    const fieldNames = allColumns.map((c) => c.fieldname);
-    if (!fieldNames.includes("name")) {
-      fieldNames.unshift("name");
-    }
-    return fieldNames as readonly string[];
-  }, [allColumns]);
+  // ── Saved-report selection: controlled by `report`, else internal ──
+  const [internalReport, setInternalReport] = useState<string | null>(null);
+  const currentReport = reportProp !== undefined ? reportProp : internalReport;
+
+  // ── Columns: defaults → device-stored → initial → explicit override ──
+  const allColumns = useMemo(() => {
+    const columns = reportColumnsFromMeta(layoutMeta);
+    if (!readsWithoutMeta || !layoutMeta) return columns;
+    const own = new Set(layoutMeta.fields.map((field) => field.fieldname));
+    return columns.filter((column) => column.fieldname === "name" || own.has(column.fieldname));
+  }, [layoutMeta, readsWithoutMeta]);
+  const defaultFieldnames = useMemo(
+    () =>
+      readsWithoutMeta && layoutMeta
+        ? ["name", ...layoutMeta.fields.map((field) => field.fieldname)]
+        : defaultReportFieldnames(layoutMeta),
+    [layoutMeta, readsWithoutMeta],
+  );
+  const initialColumnsKey = JSON.stringify(initialFieldnames(initialColumns));
+  const startFieldnames = useMemo(
+    () => JSON.parse(initialColumnsKey) as string[] | null,
+    [initialColumnsKey],
+  );
+  const [storedColumns, setStoredColumns] = useState<string[] | undefined>(undefined);
+  const [selectedOverride, setSelectedOverride] = useState<string[] | null>(null);
 
-  const {
-    rows,
-    isQueryLoading: isLoading,
-    isError,
-  } = useFrappeRows<{ name: string; doctype: string }>(connectionConfig, doctype, {
-    fields: fetchFields as readonly ("name" | "doctype")[],
-    filters: filters as Partial<{ name: string; doctype: string }>,
-    limit: null,
-  });
-  const data = rows as unknown as Record<string, unknown>[];
-
-  // Live staleness: a realtime change on the doctype marks the current
-  // report result stale until the collection reconciles (data identity
-  // changes) or a settle window passes (the change may fall outside the
-  // report's filters/window). Builder UI state (chosen columns, group-by)
-  // lives in component state and is untouched by refreshes.
-  const [isLiveStale, setIsLiveStale] = useState(false);
-  const staleTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-  const clearStaleTimer = useCallback(() => {
-    if (staleTimerRef.current) {
-      clearTimeout(staleTimerRef.current);
-      staleTimerRef.current = undefined;
-    }
-  }, []);
-  useFrappeDoctypeEvents(connectionConfig as any, doctype, (event) => {
-    if (
-      event.type !== "doc_update" &&
-      event.type !== "list_update" &&
-      event.type !== "doc_deleted" &&
-      event.type !== "doc_changed"
-    ) {
-      return;
-    }
-    setIsLiveStale(true);
-    clearStaleTimer();
-    staleTimerRef.current = setTimeout(() => setIsLiveStale(false), 2500);
-  });
-  const isFirstData = useRef(true);
   useEffect(() => {
-    if (isFirstData.current) {
-      isFirstData.current = false;
-      return;
-    }
-    setIsLiveStale(false);
-    clearStaleTimer();
-  }, [data, clearStaleTimer]);
-  useEffect(() => clearStaleTimer, [clearStaleTimer]);
+    if (fixtureMode) return;
+    let cancelled = false;
+    void readStoredColumns(doctype).then((stored) => {
+      if (!cancelled) setStoredColumns(stored);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [doctype, fixtureMode]);
 
-  // Group by state
-  const [groupBy, setGroupBy] = useState<GroupByConfig | null>(initialGroupBy ?? null);
+  const selectedFieldnames =
+    selectedOverride ?? startFieldnames ?? storedColumns ?? defaultFieldnames;
+  const selectedColumns = useMemo(
+    () => resolveSelectedColumns(allColumns, selectedFieldnames),
+    [allColumns, selectedFieldnames],
+  );
 
-  // Enabled columns state
-  const [enabledColumns, setEnabledColumns] = useState<string[]>([]);
+  // ── Filters: the report's own + the per-column filter row ─────
+  const filtersKey = JSON.stringify(filters ?? null);
+  const propFilters = useMemo(
+    () => toReportFilters(JSON.parse(filtersKey) as FrappeReportBuilderProps["filters"]),
+    [filtersKey],
+  );
+  const [filtersCleared, setFiltersCleared] = useState(false);
+  const [reportFilters, setReportFilters] = useState<ReportFilters | null>(null);
+  const baseFilters = filtersCleared
+    ? EMPTY_FILTERS
+    : (reportFilters ?? propFilters ?? EMPTY_FILTERS);
+
+  const [filterDrafts, setFilterDrafts] = useState<Record<string, string>>({});
+  const [committedFilters, setCommittedFilters] = useState<Record<string, string>>({});
+  useEffect(() => {
+    const handle = setTimeout(() => {
+      setCommittedFilters((previous) =>
+        JSON.stringify(previous) === JSON.stringify(filterDrafts) ? previous : filterDrafts,
+      );
+    }, COLUMN_FILTER_DEBOUNCE_MS);
+    return () => clearTimeout(handle);
+  }, [filterDrafts]);
+
+  const columnTuples = useMemo(
+    () => columnFilterTuples(selectedColumns, committedFilters),
+    [selectedColumns, committedFilters],
+  );
+  const scopeKey = JSON.stringify(scopeFilters ?? []);
+  const scope = useMemo(() => JSON.parse(scopeKey) as ReportFilters, [scopeKey]);
+  const effectiveFilters = useMemo(
+    () => [...scope, ...baseFilters, ...columnTuples],
+    [scope, baseFilters, columnTuples],
+  );
 
-  // Initialize enabled columns
+  // ── Sort / group / paging ───────────────────────────────────
+  const metaSort = useMemo<ReportSortState>(
+    () => ({
+      field: (meta?.sort_field || "modified").split(" ")[0],
+      order: (meta?.sort_order || "DESC").toLowerCase() === "asc" ? "asc" : "desc",
+    }),
+    [meta?.sort_field, meta?.sort_order],
+  );
+  const [sortOverride, setSortOverride] = useState<ReportSortState | null>(null);
+  const sort = sortOverride ?? metaSort;
+  const startGroupBy = groupField(initialGroupBy);
+  const chartConfig = typeof initialGroupBy === "object" ? initialGroupBy : undefined;
+  const [groupBy, setGroupBy] = useState<string | null>(startGroupBy);
+  const [pageSize, setPageSize] = useState<number>(DEFAULT_REPORT_PAGE_SIZE);
+  const [page, setPage] = useState(0);
+
+  // A doctype swap resets every view state (a route reuses the component).
   useEffect(() => {
-    if (allColumns.length > 0 && enabledColumns.length === 0) {
-      const initial = allColumns.filter((c) => c.enabled).map((c) => c.fieldname);
-      if (initial.length === 0) {
-        setEnabledColumns(allColumns.slice(0, 5).map((c) => c.fieldname));
-      } else {
-        setEnabledColumns(initial);
-      }
-    }
-  }, [allColumns, enabledColumns.length]);
+    setSelectedOverride(null);
+    setStoredColumns(undefined);
+    setSortOverride(null);
+    setGroupBy(startGroupBy);
+    setPage(0);
+    setPageSize(DEFAULT_REPORT_PAGE_SIZE);
+    setFilterDrafts({});
+    setCommittedFilters({});
+    setFiltersCleared(false);
+    setReportFilters(null);
+    // startGroupBy is the mount-time seed; only a doctype swap re-seeds.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [doctype]);
 
-  // Saved reports (Frappe-specific persistence layer)
-  const [savedReports, setSavedReports] = useState<SavedReport[]>([]);
-  const [saveDialogOpen, setSaveDialogOpen] = useState(false);
-  const [saveReportName, setSaveReportName] = useState("");
+  useEffect(() => setFiltersCleared(false), [filtersKey]);
 
+  const effectiveFiltersKey = useMemo(() => JSON.stringify(effectiveFilters), [effectiveFilters]);
   useEffect(() => {
+    setPage(0);
+  }, [effectiveFiltersKey, pageSize, groupBy]);
+
+  // ── Apply a saved report's config when the selection changes ─
+  useEffect(() => {
+    if (!currentReport) {
+      setReportFilters(null);
+      return;
+    }
     let cancelled = false;
-    void (async () => {
-      const reports = await loadSavedReports(doctype);
-      if (!cancelled) {
-        setSavedReports(reports);
+    void savedReports.load(currentReport).then((saved) => {
+      if (cancelled || !saved) return;
+      setSelectedOverride(saved.fieldnames.length > 0 ? saved.fieldnames : null);
+      setReportFilters(saved.filters);
+      setFilterDrafts({});
+      setCommittedFilters({});
+      setFiltersCleared(false);
+      if (saved.sort) setSortOverride(saved.sort);
+      if (saved.pageSize && REPORT_PAGE_SIZES.some((size) => size === saved.pageSize)) {
+        setPageSize(saved.pageSize);
       }
-    })();
+      setGroupBy(saved.groupBy ?? null);
+    });
     return () => {
       cancelled = true;
     };
-  }, [doctype]);
+    // savedReports.load changes identity with its report list; reloading the
+    // config on list refreshes would clobber in-progress edits — key on the
+    // selected report (and doctype via load's closure) only.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentReport, doctype]);
+
+  // ── Column selection changes ────────────────────────────────
+  const handleToggleColumn = useCallback(
+    (fieldname: string) => {
+      setSelectedOverride((previous) => {
+        const current = previous ?? startFieldnames ?? storedColumns ?? defaultFieldnames;
+        const next = current.includes(fieldname)
+          ? current.length === 1
+            ? current
+            : current.filter((entry) => entry !== fieldname)
+          : [...current, fieldname];
+        if (!fixtureMode && !currentReport) persistStoredColumns(doctype, next);
+        return next;
+      });
+    },
+    [startFieldnames, storedColumns, defaultFieldnames, fixtureMode, currentReport, doctype],
+  );
 
-  const handleSaveReport = useCallback(() => {
-    if (!saveReportName.trim()) return;
-    const report: SavedReport = {
-      name: saveReportName.trim(),
-      columns: enabledColumns,
-      groupBy,
-      filters,
-    };
-    const updated = [...savedReports.filter((r) => r.name !== report.name), report];
-    setSavedReports(updated);
-    void persistSavedReports(doctype, updated);
-    setSaveDialogOpen(false);
-    setSaveReportName("");
-  }, [saveReportName, enabledColumns, groupBy, filters, savedReports, doctype]);
-
-  const handleLoadReport = useCallback((report: SavedReport) => {
-    setEnabledColumns(report.columns);
-    setGroupBy(report.groupBy);
-  }, []);
+  const handleResetColumns = useCallback(() => {
+    setSelectedOverride(defaultFieldnames);
+    setStoredColumns(undefined);
+    if (!fixtureMode) persistStoredColumns(doctype, defaultFieldnames);
+  }, [defaultFieldnames, fixtureMode, doctype]);
 
-  const handleDeleteReport = useCallback(
+  // ── Data: live collection over the full filtered result ─────
+  const fetchFields = useMemo(() => {
+    const fields = new Set<string>(["name", sort.field]);
+    for (const column of selectedColumns) fields.add(column.fieldname);
+    if (groupBy) fields.add(groupBy);
+    if (chartConfig?.aggregationField) fields.add(chartConfig.aggregationField);
+    return [...fields];
+  }, [selectedColumns, sort.field, groupBy, chartConfig?.aggregationField]);
+
+  const orderBy = useMemo(
+    () => [{ field: sort.field, order: sort.order === "asc" ? Order.Asc : Order.Desc }],
+    [sort.field, sort.order],
+  );
+  const {
+    rows: rowsData,
+    syncError,
+    isLoading: rowsLoading,
+  } = useFrappeRows<ReportRow & { doctype: string }>(connection, doctype, {
+    fields: fetchFields,
+    filters: effectiveFilters,
+    orderBy,
+    limit: null,
+    enabled: layoutMeta !== undefined,
+    mapError: asError,
+  });
+
+  const orderedRows = useMemo(
+    () => orderReportRows(rowsData, sort, groupBy),
+    [rowsData, sort, groupBy],
+  );
+
+  const total = orderedRows.length;
+  const pageCount = Math.max(1, Math.ceil(total / pageSize));
+  const effectivePage = Math.min(page, pageCount - 1);
+  const gridRows = useMemo(
+    () => buildGridRows(orderedRows, effectivePage * pageSize, pageSize, groupBy),
+    [orderedRows, effectivePage, pageSize, groupBy],
+  );
+  const totals = useMemo(
+    () => computeTotals(selectedColumns, orderedRows),
+    [selectedColumns, orderedRows],
+  );
+  const groupByColumn = groupBy
+    ? allColumns.find((column) => column.fieldname === groupBy)
+    : undefined;
+  const chartData = useMemo(
+    () => (showChart && groupBy ? aggregateGroups(orderedRows, groupBy, chartConfig) : []),
+    [showChart, groupBy, orderedRows, chartConfig],
+  );
+
+  // ── Navigation ──────────────────────────────────────────────
+  const rowsPressable = Boolean(onOpenRow || onRowPress);
+  const handleOpenRow = useCallback(
     (name: string) => {
-      const updated = savedReports.filter((r) => r.name !== name);
-      setSavedReports(updated);
-      void persistSavedReports(doctype, updated);
+      onOpenRow?.(name);
+      if (onRowPress) {
+        const index = orderedRows.findIndex((row) => row.name === name);
+        if (index >= 0) onRowPress(orderedRows[index], index);
+      }
     },
-    [savedReports, doctype],
+    [onOpenRow, onRowPress, orderedRows],
   );
 
-  // CSV export handler
-  const handleExport = useCallback(
-    (exportData: Record<string, unknown>[]) => {
-      if (onExport) {
-        onExport(exportData);
-        return;
+  const handleSelectReport = useCallback(
+    (name: string | null) => {
+      if (reportProp === undefined) setInternalReport(name);
+      onReportChange?.(name);
+      if (!name) {
+        setReportFilters(null);
+        setSelectedOverride(null);
+        setSortOverride(null);
+        setGroupBy(null);
       }
+    },
+    [reportProp, onReportChange],
+  );
+
+  const handleClearBaseFilters = useCallback(() => {
+    setFiltersCleared(true);
+    if (propFilters && !reportFilters) onClearFilters?.();
+  }, [propFilters, reportFilters, onClearFilters]);
 
-      // Generate CSV
-      const cols = allColumns.filter((c) => enabledColumns.includes(c.fieldname));
-      const headers = cols.map((c) => c.label);
-      const csvRows = [headers.join(",")];
-
-      for (const row of exportData) {
-        const values = cols.map((col) => {
-          const val = row[col.fieldname];
-          if (val === null || val === undefined) return "";
-          const str = String(val);
-          if (str.includes(",") || str.includes('"') || str.includes("\n")) {
-            return `"${str.replace(/"/g, '""')}"`;
-          }
-          return str;
+  // ── Saved-report actions ────────────────────────────────────
+  const handleSaveReport = useCallback(
+    (name: string) => {
+      void savedReports
+        .save(name, {
+          fieldnames: [...selectedFieldnames],
+          filters: effectiveFilters,
+          sort,
+          pageSize,
+          groupBy,
+          addTotals: totals.length > 0,
+        })
+        .then((savedName) => {
+          notify({
+            severity: "success",
+            scope: "page",
+            body: t("report.saveDone", {
+              defaultValue: "Saved report “{{name}}”",
+              name: savedName,
+            }),
+          });
+          if (savedName !== currentReport) handleSelectReport(savedName);
+        })
+        .catch((error: unknown) => {
+          notify({
+            severity: "error",
+            scope: "page",
+            body:
+              error instanceof Error
+                ? error.message
+                : t("report.saveFailed", "Could not save the report"),
+          });
         });
-        csvRows.push(values.join(","));
-      }
+    },
+    [
+      savedReports,
+      selectedFieldnames,
+      effectiveFilters,
+      sort,
+      pageSize,
+      groupBy,
+      totals.length,
+      currentReport,
+      handleSelectReport,
+      t,
+    ],
+  );
 
-      const csvContent = csvRows.join("\n");
-      const blob = new Blob([csvContent], { type: "text/csv;charset=utf-8;" });
-      downloadBlob(blob, `${doctype}_report.csv`);
+  const handleDeleteReport = useCallback(
+    (name: string) => {
+      void savedReports
+        .remove(name)
+        .then(() => {
+          notify({
+            severity: "success",
+            scope: "page",
+            body: t("report.deleteDone", {
+              defaultValue: "Deleted report “{{name}}”",
+              name,
+            }),
+          });
+          if (name === currentReport) handleSelectReport(null);
+        })
+        .catch((error: unknown) => {
+          notify({
+            severity: "error",
+            scope: "page",
+            body:
+              error instanceof Error
+                ? error.message
+                : t("report.deleteFailed", "Could not delete the report"),
+          });
+        });
     },
-    [allColumns, enabledColumns, onExport, doctype],
+    [savedReports, currentReport, handleSelectReport, t],
   );
 
-  // B12 capability gate: a consumer-provided onExport owns delivery and shows
-  // on every platform; the built-in CSV path only shows where the web download
-  // pipeline exists. `undefined` hides ReportBuilder's Export button entirely,
-  // so native/GTK never render a dead control. Web behavior is unchanged.
+  // ── Export: full filtered + ordered result ──────────────────
   const exportEnabled = Boolean(onExport) || canDownloadCsv();
+  const handleExport = useCallback(() => {
+    if (onExport) {
+      onExport(orderedRows);
+      return;
+    }
+    downloadBlob(
+      new Blob([buildReportCsv(selectedColumns, orderedRows)], {
+        type: "text/csv;charset=utf-8;",
+      }),
+      `${doctype}_report.csv`,
+    );
+    notify({
+      severity: "success",
+      scope: "page",
+      body: t("report.exportDone", {
+        count: orderedRows.length,
+        defaultValue_one: "Exported {{count}} row to CSV",
+        defaultValue_other: "Exported {{count}} rows to CSV",
+      }),
+    });
+  }, [onExport, selectedColumns, orderedRows, doctype, t]);
+
+  const handleColumnFilterChange = useCallback((fieldname: string, value: string) => {
+    setFilterDrafts((previous) => {
+      if (value === "") {
+        if (!(fieldname in previous)) return previous;
+        const { [fieldname]: _dropped, ...rest } = previous;
+        return rest;
+      }
+      return { ...previous, [fieldname]: value };
+    });
+  }, []);
 
-  if (isMetaLoading) {
+  const handleClearColumnFilters = useCallback(() => {
+    setFilterDrafts({});
+    setCommittedFilters({});
+  }, []);
+
+  // ── Render ──────────────────────────────────────────────────
+  if (metaLoading && !meta) {
     return (
-      <YStack
-        {...knobProps.panelPadding}
-        alignItems="center"
-        justifyContent="center"
-        gap="$2"
-        {...stackProps}
-      >
-        <Spinner size="large" />
-        <Text color="$color10">{t("Loading {{doctype}} schema...", { doctype })}</Text>
-      </YStack>
+      <>
+        {loadingFallback ?? (
+          <YStack flex={1} alignItems="center" justifyContent="center" {...stackProps}>
+            <Spinner size="large" />
+          </YStack>
+        )}
+      </>
     );
   }
-
-  if (metaError && !meta) {
+  if (metaError && metaRefused && !layoutMeta) {
+    if (recordShape.status === "pending") {
+      return (
+        <>
+          {loadingFallback ?? (
+            <YStack flex={1} alignItems="center" justifyContent="center" {...stackProps}>
+              <Spinner size="large" />
+            </YStack>
+          )}
+        </>
+      );
+    }
     return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap} {...stackProps}>
-        <Text color="$red11">{t("Failed to load {{doctype}} schema", { doctype })}</Text>
-        <Text color="$color10" fontSize="$2">
-          {metaError.message}
-        </Text>
-      </YStack>
+      <>
+        {errorFallback ? (
+          errorFallback(metaError)
+        ) : (
+          <EmptyState
+            testID="frappe-report-not-permitted"
+            title={t("report.notPermitted", {
+              defaultValue: "You can't open the {{doctype}} report",
+              doctype,
+            })}
+            description={refusalReason(metaError)}
+          />
+        )}
+      </>
     );
   }
-
-  if (isLoading) {
+  if (metaError && !meta && !readsWithoutMeta) {
     return (
-      <YStack {...knobProps.panelPadding} alignItems="center" gap="$1" {...stackProps}>
-        <Spinner size="small" />
-        <Text color="$color10" fontSize="$2">
-          {t("Loading data...")}
-        </Text>
-      </YStack>
+      <>
+        {errorFallback ? (
+          errorFallback(metaError)
+        ) : (
+          <EmptyState
+            intent="error"
+            title={t("report.metaFailed", {
+              defaultValue: "Couldn't load the {{doctype}} report",
+              doctype,
+            })}
+            description={metaError.message}
+          />
+        )}
+      </>
     );
   }
 
-  if (isError) {
-    return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap} {...stackProps}>
-        <Text color="$red11">{t("Failed to load {{doctype}} data", { doctype })}</Text>
-        <Text color="$color10" fontSize="$2">
-          {t("The live query could not load report rows.")}
-        </Text>
+  let body: React.ReactNode;
+  if (syncError && isPermissionError(syncError)) {
+    body = (
+      <EmptyState
+        testID="frappe-report-not-permitted"
+        title={t("report.notPermitted", {
+          defaultValue: "You can't open the {{doctype}} report",
+          doctype,
+        })}
+        description={refusalReason(syncError)}
+      />
+    );
+  } else if (syncError) {
+    body = (
+      <EmptyState
+        intent="error"
+        title={t("report.loadFailed", "Couldn't load report rows")}
+        description={syncError.message}
+      />
+    );
+  } else if (rowsLoading && total === 0) {
+    body = (
+      <YStack flex={1} alignItems="center" justifyContent="center">
+        <Spinner size="large" />
       </YStack>
     );
-  }
-
-  return (
-    <YStack flex={1} {...knobProps.borderRadius} {...stackProps}>
-      {/* Frappe-specific toolbar: Save/Load reports */}
-      <XStack
-        {...knobProps.panelPadding}
-        {...knobProps.surface}
-        {...knobProps.gap}
-        alignItems="center"
-        borderBottomWidth={1}
-        borderBottomColor="$borderColor"
-      >
-        {/* Subtle stale affordance while a post-event refresh reconciles */}
-        {isLiveStale ? (
-          <XStack gap="$2" alignItems="center">
-            <Spinner size="small" aria-label={t("Updating")} />
-            <Text {...knobProps.label} color={formCommonColors.muted}>
-              {t("Updating...")}
-            </Text>
-          </XStack>
-        ) : null}
-        <XStack flex={1} />
-        {/* Save */}
-        <Popover placement="bottom-end" open={saveDialogOpen} onOpenChange={setSaveDialogOpen}>
-          <Popover.Trigger asChild>
-            <Button size="$2" icon={FloppyDiskIcon}>
-              {t("Save")}
+  } else if (total === 0) {
+    const hasFilters = effectiveFilters.length > 0;
+    body = (
+      <EmptyState
+        title={t("report.emptyTitle", "No results")}
+        description={
+          hasFilters
+            ? t("report.emptyFiltered", "No rows match the current filters")
+            : t("report.emptyDescription", {
+                defaultValue: "There are no {{doctype}} records yet",
+                doctype,
+              })
+        }
+        action={
+          hasFilters ? (
+            <Button
+              size="$3"
+              onPress={() => {
+                handleClearColumnFilters();
+                handleClearBaseFilters();
+              }}
+            >
+              {t("report.clearAllFilters", "Clear all filters")}
             </Button>
-          </Popover.Trigger>
-          <PopoverContent>
-            <YStack {...knobProps.gap} minWidth={220}>
-              <Text {...knobProps.label} fontWeight="400">
-                {t("Save Report")}
-              </Text>
-              <Input
-                label={t("Report name")}
-                labelHidden
-                placeholder={t("Report name")}
-                value={saveReportName}
-                onChangeText={setSaveReportName}
-                inputProps={{ onSubmitEditing: handleSaveReport } as any}
-              />
-              <Button size="$2" onPress={handleSaveReport} disabled={!saveReportName.trim()}>
-                {t("Save")}
-              </Button>
-            </YStack>
-          </PopoverContent>
-        </Popover>
-
-        {/* Load */}
-        {savedReports.length > 0 && (
-          <Popover placement="bottom-end">
-            <Popover.Trigger asChild>
-              <Button size="$2" icon={FolderOpenIcon}>
-                {t("Load")}
-              </Button>
-            </Popover.Trigger>
-            <PopoverContent>
-              <YStack {...knobProps.gap} minWidth={180}>
-                <Text {...knobProps.label} fontWeight="400" color={formCommonColors.muted}>
-                  {t("Saved Reports")}
-                </Text>
-                <Separator />
-                {savedReports.map((report) => (
-                  <XStack
-                    key={report.name}
-                    alignItems="center"
-                    justifyContent="space-between"
-                    padding="$2"
-                    {...knobProps.containerRadius}
-                    hoverStyle={{ backgroundColor: "$color2" }}
-                    cursor="pointer"
-                    onPress={() => handleLoadReport(report)}
-                  >
-                    <Text {...knobProps.body} flex={1}>
-                      {report.name}
-                    </Text>
-                    <Button
-                      size="$2"
-                      circular
-                      chromeless
-                      icon={TrashIcon}
-                      onPress={(e) => {
-                        (e as unknown as { stopPropagation: () => void }).stopPropagation();
-                        handleDeleteReport(report.name);
-                      }}
-                      aria-label={t("Delete {{name}}", { name: report.name })}
-                    />
-                  </XStack>
-                ))}
-              </YStack>
-            </PopoverContent>
-          </Popover>
+          ) : undefined
+        }
+      />
+    );
+  } else {
+    body = (
+      <YStack flex={1} minWidth={0} {...knobProps.gap}>
+        {chartData.length > 0 && (
+          <YStack {...knobProps.surface} {...knobProps.containerRadius} {...knobProps.panelPadding}>
+            <BarChart data={chartData} />
+          </YStack>
         )}
-      </XStack>
+        <ReportGrid
+          columns={selectedColumns}
+          rows={gridRows}
+          sort={sort}
+          onSortChange={setSortOverride}
+          columnFilters={filterDrafts}
+          onColumnFilterChange={handleColumnFilterChange}
+          onOpenRow={rowsPressable ? handleOpenRow : undefined}
+          onOpenLink={onOpenLink}
+          totals={totals}
+          groupByColumn={groupByColumn}
+        />
+      </YStack>
+    );
+  }
 
-      {/* Delegate to generic ReportBuilder */}
-      <ReportBuilder
+  const content = (
+    <YStack flex={1} minWidth={0} {...stackProps}>
+      <ReportViewToolbar
         columns={allColumns}
-        data={data}
-        groupBy={groupBy ?? undefined}
+        selected={selectedFieldnames}
+        onToggleColumn={handleToggleColumn}
+        onResetColumns={handleResetColumns}
+        groupBy={groupBy}
         onGroupByChange={setGroupBy}
-        onColumnsChange={setEnabledColumns}
+        baseFilters={baseFilters}
+        onClearBaseFilters={baseFilters.length > 0 ? handleClearBaseFilters : undefined}
+        columnFilterCount={columnTuples.length}
+        onClearColumnFilters={handleClearColumnFilters}
+        savedReports={savedReports.reports}
+        currentReport={currentReport}
+        onSelectReport={handleSelectReport}
+        onSaveReport={readsWithoutMeta ? undefined : handleSaveReport}
+        onDeleteReport={readsWithoutMeta ? undefined : handleDeleteReport}
         onExport={exportEnabled ? handleExport : undefined}
-        onRowPress={onRowPress}
-        showChart={showChart}
-        flex={1}
+        exportDisabled={total === 0}
       />
+      <YStack flex={1} minWidth={0} paddingHorizontal="$3">
+        {body}
+      </YStack>
+      {total > 0 && !syncError && (
+        <YStack paddingHorizontal="$3" paddingVertical="$2">
+          <DataTablePagination
+            pagination={{
+              pageIndex: effectivePage,
+              pageSize,
+              totalCount: total,
+              totalPages: pageCount,
+            }}
+            onPaginationChange={(next) => {
+              setPage(next.pageIndex);
+              setPageSize(next.pageSize);
+            }}
+            pageSizeOptions={[...REPORT_PAGE_SIZES]}
+            compact
+          />
+        </YStack>
+      )}
     </YStack>
   );
+
+  // Native has no page-level scroll (the desk list precedent) — wrap so rows
+  // below the fold stay reachable. Web keeps the flex layout.
+  return isWeb ? content : <ScrollView flex={1}>{content}</ScrollView>;
 }
 
 export type { ReportColumn, GroupByConfig } from "@multiplatform.one/components";