@multiplatform.one/backoffice 6.4.2 → 6.6.0

package/src/report/DoctypeReportView.tsx

@@ -0,0 +1,600 @@
+// Desk "report" view parity (audit punch #1). Replaces the old
+// FrappeReportBuilder composition (triple-stacked toolbars, 2-column
+// defaults, no filter row, no saved reports) with:
+//   - desk default columns: name + title field + in_list_view /
+//     in_standard_filter fields + modified (reportViewModel, desk
+//     set_default_fields parity)
+//   - a column add/remove picker; the choice persists per doctype on this
+//     device (@multiplatform.one/store) while no saved report is selected
+//   - a per-column FILTER ROW driving the standard frappe filter pipeline
+//     (kind→operator mapping shared with the list filter vocabulary)
+//   - ONE toolbar row (picker / group-by / saved reports / chips / export);
+//     page size rides the footer pager like the list screen
+//   - saved reports on the `Report` doctype (desk round-trip) selected via
+//     the ?report= search param; fixture mode keeps them in memory
+//   - live rows through the house collection channel: the FULL filtered
+//     result stays client-side (totals + export need it), ordered
+//     deterministically and windowed into pages client-side
+import { EmptyState, ScrollView, YStack, isWeb, notify } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import {
+  Order,
+  useFrappeCollection,
+  useLiveQuery,
+  type UseFrappeCollectionConfig,
+} from "@multiplatform.one/frappe";
+import { downloadBlob } from "@multiplatform.one/platform";
+import { storage } from "@multiplatform.one/store";
+import { DataTablePagination } from "@multiplatform.one/table";
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  useBackofficeLocation,
+  useBackofficeNavigator,
+  useBackofficePaths,
+} from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import type { FrappeFilters } from "../shared/types";
+import { useDoctypeMeta } from "../shared/useDoctypeMeta";
+import { useViewConnection } from "../views/connection";
+import { ViewError, ViewLoading } from "../views/ViewStates";
+import { ReportGrid } from "./report-grid";
+import { ReportToolbar } from "./report-toolbar";
+import { useSavedReports } from "./savedReports";
+import {
+  DEFAULT_REPORT_PAGE_SIZE,
+  REPORT_PAGE_SIZES,
+  buildGridRows,
+  buildReportCsv,
+  columnFilterTuples,
+  computeTotals,
+  defaultReportFieldnames,
+  orderReportRows,
+  parseReportFiltersParam,
+  reportColumnsFromMeta,
+  resolveSelectedColumns,
+  type ReportRow,
+  type ReportSortState,
+} from "./reportViewModel";
+
+export interface DoctypeReportViewProps {
+  /** Proper-cased doctype name (e.g. "ToDo", "Sales Order") */
+  doctype: string;
+  /**
+   * Raw `?f=` search-param value (urlencoded JSON FrappeFilters), read by
+   * the route wrapper (DoctypeViewScreen) — kept as a prop so the screen
+   * mounts outside a One navigation container (stories/tests).
+   */
+  filtersParam?: string;
+  /** Base filters when no `?f=` URL param is present (stories/tests). */
+  initialFilters?: FrappeFilters;
+}
+
+const EMPTY_FILTERS: FrappeFilters = [];
+const COLUMN_FILTER_DEBOUNCE_MS = 350;
+
+function columnsStorageKey(doctype: string): string {
+  return `backoffice.report.columns.${doctype}`;
+}
+
+async function readStoredColumns(doctype: string): Promise<string[] | undefined> {
+  try {
+    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 unavailable or corrupted — defaults win
+  }
+  return undefined;
+}
+
+function persistStoredColumns(doctype: string, fieldnames: readonly string[]): void {
+  try {
+    void Promise.resolve(storage.setItem(columnsStorageKey(doctype), JSON.stringify(fieldnames)));
+  } catch {
+    // storage unavailable — selection stays session-only
+  }
+}
+
+export function DoctypeReportView({
+  doctype,
+  filtersParam,
+  initialFilters,
+}: DoctypeReportViewProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const { params } = useBackofficeLocation();
+  const connection = useViewConnection();
+  const fixtureMode = Boolean(connection?.fixtures);
+  const { meta, loading: metaLoading, error: metaError } = useDoctypeMeta(doctype);
+  const savedReports = useSavedReports(doctype);
+
+  // ── Saved-report selection (?report= search param) ──────────
+  // The router may hand the param through raw — decode defensively (same
+  // contract as the `?f=` parser: percent-decoding a decoded value is a
+  // no-op for names without a literal %).
+  const rawReportParam = typeof params.report === "string" ? params.report : params.report?.[0];
+  const currentReport = useMemo(() => {
+    if (!rawReportParam) return null;
+    try {
+      return decodeURIComponent(rawReportParam);
+    } catch {
+      return rawReportParam;
+    }
+  }, [rawReportParam]);
+
+  // ── Columns: defaults → device-stored → explicit override ───
+  const allColumns = useMemo(() => reportColumnsFromMeta(meta), [meta]);
+  const defaultFieldnames = useMemo(() => defaultReportFieldnames(meta), [meta]);
+  const [storedColumns, setStoredColumns] = useState<string[] | undefined>(undefined);
+  const [selectedOverride, setSelectedOverride] = useState<string[] | null>(null);
+
+  useEffect(() => {
+    if (fixtureMode) return;
+    let cancelled = false;
+    void readStoredColumns(doctype).then((stored) => {
+      if (!cancelled) setStoredColumns(stored);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [doctype, fixtureMode]);
+
+  const selectedFieldnames = selectedOverride ?? storedColumns ?? defaultFieldnames;
+  const selectedColumns = useMemo(
+    () => resolveSelectedColumns(allColumns, selectedFieldnames),
+    [allColumns, selectedFieldnames],
+  );
+
+  // ── Filters: ?f= base channel + the per-column filter row ───
+  const urlFilters = useMemo(() => parseReportFiltersParam(filtersParam), [filtersParam]);
+  const [filtersCleared, setFiltersCleared] = useState(false);
+  const [reportFilters, setReportFilters] = useState<FrappeFilters | null>(null);
+  const baseFilters = filtersCleared
+    ? EMPTY_FILTERS
+    : (reportFilters ?? urlFilters ?? initialFilters ?? 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 effectiveFilters = useMemo(
+    () => [...baseFilters, ...columnTuples],
+    [baseFilters, columnTuples],
+  );
+
+  // ── 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 [groupBy, setGroupBy] = useState<string | null>(null);
+  const [pageSize, setPageSize] = useState<number>(DEFAULT_REPORT_PAGE_SIZE);
+  const [page, setPage] = useState(0);
+
+  // Doctype swap resets every view state (route component is reused).
+  useEffect(() => {
+    setSelectedOverride(null);
+    setStoredColumns(undefined);
+    setSortOverride(null);
+    setGroupBy(null);
+    setPage(0);
+    setPageSize(DEFAULT_REPORT_PAGE_SIZE);
+    setFilterDrafts({});
+    setCommittedFilters({});
+    setFiltersCleared(false);
+    setReportFilters(null);
+  }, [doctype]);
+
+  useEffect(() => setFiltersCleared(false), [filtersParam]);
+
+  const filtersKey = useMemo(() => JSON.stringify(effectiveFilters), [effectiveFilters]);
+  useEffect(() => {
+    setPage(0);
+  }, [filtersKey, pageSize, groupBy]);
+
+  // ── Apply a saved report's config when ?report= changes ─────
+  useEffect(() => {
+    if (!currentReport) {
+      setReportFilters(null);
+      return;
+    }
+    let cancelled = false;
+    void savedReports.load(currentReport).then((config) => {
+      if (cancelled || !config) return;
+      setSelectedOverride(config.fieldnames.length > 0 ? config.fieldnames : null);
+      setReportFilters(config.filters);
+      setFilterDrafts({});
+      setCommittedFilters({});
+      setFiltersCleared(false);
+      if (config.sort) setSortOverride(config.sort);
+      if (config.pageSize && REPORT_PAGE_SIZES.some((size) => size === config.pageSize)) {
+        setPageSize(config.pageSize);
+      }
+      setGroupBy(config.groupBy ?? null);
+    });
+    return () => {
+      cancelled = true;
+    };
+    // 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 ?? 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;
+      });
+    },
+    [storedColumns, defaultFieldnames, fixtureMode, currentReport, doctype],
+  );
+
+  const handleResetColumns = useCallback(() => {
+    setSelectedOverride(defaultFieldnames);
+    setStoredColumns(undefined);
+    if (!fixtureMode) persistStoredColumns(doctype, defaultFieldnames);
+  }, [defaultFieldnames, fixtureMode, doctype]);
+
+  // ── 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);
+    return [...fields];
+  }, [selectedColumns, sort.field, groupBy]);
+
+  const [syncError, setSyncError] = useState<Error | null>(null);
+  const handleSyncError = useCallback((error: unknown) => {
+    setSyncError(error instanceof Error ? error : new Error(String(error)));
+  }, []);
+  const [retryGen, setRetryGen] = useState(0);
+
+  // ViewConnection carries syncOptions as `unknown`; the shapes match the
+  // collection config (same FrappeProvider source) — assert once here.
+  const collectionConfig = useMemo(
+    () =>
+      connection && meta && retryGen >= 0
+        ? (connection as unknown as UseFrappeCollectionConfig)
+        : undefined,
+    [connection, meta, retryGen],
+  );
+  const collection = useFrappeCollection<ReportRow & { doctype: string }>(
+    collectionConfig,
+    doctype,
+    {
+      fields: fetchFields,
+      filters: effectiveFilters,
+      orderBy: { field: sort.field, order: sort.order === "asc" ? Order.Asc : Order.Desc },
+      onSyncError: handleSyncError,
+    },
+  );
+  useEffect(() => setSyncError(null), [collection]);
+  const { data: rowsData, isLoading: rowsLoading } = useLiveQuery(
+    (q) => (collection ? q.from({ _report: collection }) : null),
+    [collection],
+  );
+
+  const orderedRows = useMemo(
+    () => orderReportRows((rowsData as ReportRow[] | undefined) ?? [], 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;
+
+  // ── Navigation ──────────────────────────────────────────────
+  const handleOpenRow = useCallback(
+    (name: string) => navigator.navigate(paths.form(doctype, name)),
+    [navigator, paths, doctype],
+  );
+  const handleOpenLink = useCallback(
+    (targetDoctype: string, name: string) => navigator.navigate(paths.form(targetDoctype, name)),
+    [navigator, paths],
+  );
+
+  const handleSelectReport = useCallback(
+    (name: string | null) => {
+      const base = paths.view(doctype, "report");
+      navigator.replace(name ? `${base}?report=${encodeURIComponent(name)}` : base);
+      if (!name) {
+        setReportFilters(null);
+        setSelectedOverride(null);
+        setSortOverride(null);
+        setGroupBy(null);
+      }
+    },
+    [navigator, paths, doctype],
+  );
+
+  const handleClearBaseFilters = useCallback(() => {
+    setFiltersCleared(true);
+    if (urlFilters && !reportFilters) navigator.replace(paths.view(doctype, "report"));
+  }, [urlFilters, reportFilters, navigator, paths, doctype]);
+
+  // ── 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"),
+          });
+        });
+    },
+    [
+      savedReports,
+      selectedFieldnames,
+      effectiveFilters,
+      sort,
+      pageSize,
+      groupBy,
+      totals.length,
+      currentReport,
+      handleSelectReport,
+      t,
+    ],
+  );
+
+  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"),
+          });
+        });
+    },
+    [savedReports, currentReport, handleSelectReport, t],
+  );
+
+  // ── Export: full filtered + ordered result as CSV ───────────
+  const handleExport = useCallback(() => {
+    if (!isWeb) {
+      notify({
+        severity: "warning",
+        scope: "page",
+        body: t(
+          "report.exportUnsupported",
+          "CSV export needs a browser download — not available on this platform yet",
+        ),
+      });
+      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",
+      }),
+    });
+  }, [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 };
+    });
+  }, []);
+
+  const handleClearColumnFilters = useCallback(() => {
+    setFilterDrafts({});
+    setCommittedFilters({});
+  }, []);
+
+  const activeColumnFilterCount = columnTuples.length;
+
+  // ── Render ──────────────────────────────────────────────────
+  if (metaLoading && !meta) return <ViewLoading />;
+  if (metaError && !meta) return <ViewError doctype={doctype} error={metaError} />;
+
+  let body: React.ReactNode;
+  if (syncError) {
+    body = (
+      <EmptyState
+        intent="error"
+        title={t("report.loadFailed", "Couldn't load report rows")}
+        description={syncError.message}
+        action={
+          <Button
+            size="$3"
+            onPress={() => {
+              setSyncError(null);
+              setRetryGen((generation) => generation + 1);
+            }}
+          >
+            {t("report.retry", "Retry")}
+          </Button>
+        }
+      />
+    );
+  } else if (rowsLoading && total === 0) {
+    body = <ViewLoading />;
+  } 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>
+          ) : undefined
+        }
+      />
+    );
+  } else {
+    body = (
+      <ReportGrid
+        columns={selectedColumns}
+        rows={gridRows}
+        sort={sort}
+        onSortChange={setSortOverride}
+        columnFilters={filterDrafts}
+        onColumnFilterChange={handleColumnFilterChange}
+        onOpenRow={handleOpenRow}
+        onOpenLink={handleOpenLink}
+        totals={totals}
+        groupByColumn={groupByColumn}
+      />
+    );
+  }
+
+  const content = (
+    <YStack flex={1} minWidth={0}>
+      <ReportToolbar
+        columns={allColumns}
+        selected={selectedFieldnames}
+        onToggleColumn={handleToggleColumn}
+        onResetColumns={handleResetColumns}
+        groupBy={groupBy}
+        onGroupByChange={setGroupBy}
+        baseFilters={baseFilters}
+        onClearBaseFilters={baseFilters.length > 0 ? handleClearBaseFilters : undefined}
+        columnFilterCount={activeColumnFilterCount}
+        onClearColumnFilters={handleClearColumnFilters}
+        savedReports={savedReports.reports}
+        currentReport={currentReport}
+        onSelectReport={handleSelectReport}
+        onSaveReport={handleSaveReport}
+        onDeleteReport={handleDeleteReport}
+        onExport={handleExport}
+        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 (DoctypeListScreen precedent) — wrap so
+  // rows below the fold stay reachable. Web keeps the flex layout.
+  return isWeb ? content : <ScrollView flex={1}>{content}</ScrollView>;
+}