@multiplatform.one/backoffice 6.4.3 → 6.6.0

package/src/views/ReportView.tsx

@@ -0,0 +1,434 @@
+// Desk "report" view parity. FrappeReportBuilder stays the grid engine
+// (meta-driven columns, live rows, group rendering with aggregation +
+// chart, save/load, Export button); the desk chrome it lacks is composed
+// around it from report-controls.tsx:
+//   - column add/remove picker across all meta fields (+ synthetic ID
+//     column). The generic ReportBuilder's own column/group-by toggle
+//     handlers are dead code and its enabled-column state is mount-only,
+//     so selection is driven through `initialColumns`/`initialGroupBy`
+//     plus a remount key.
+//   - `?f=` URL param (urlencoded JSON FrappeFilters) → base filters
+//     (chips + clear); FrappeReportBuilder accepts filter tuples directly.
+//   - page-size selector (20/100/500) + pagination: a parallel name-window
+//     query (name + sort + numeric fields) orders the full filtered result
+//     client-side, and the current page is handed to the grid as a
+//     `["name","in",names]` filter — the builder reacts to filter-prop
+//     changes without remounting. Small results (≤ page size) skip the
+//     window entirely and keep the pure live path.
+//   - totals strip over the full filtered result (ReportBuilder has no
+//     totals row) and an "Open" record jump in the footer.
+//   - grid rows click through to the form via onRowPress (threaded
+//     through FrappeReportBuilder → ReportBuilder).
+//   - CSV export via onExport: current page rows / enabled columns,
+//     web-guarded (Blob + anchor download); native shows an honest toast.
+// Known gaps vs desk (component limitations, documented for integrator):
+//   - the component's own Save/Load applies loaded configs to its internal
+//     state only — this screen's pickers stay the source of truth
+//   - CSV exports the loaded page, not a server-side full export
+import { isWeb, notify, YStack } from "@multiplatform.one/components";
+import {
+  Order,
+  useFrappeCollection,
+  useLiveQuery,
+  type UseFrappeCollectionConfig,
+} from "@multiplatform.one/frappe";
+import {
+  FrappeReportBuilder,
+  type GroupByConfig,
+  type ReportColumn,
+} from "@multiplatform.one/frappe-ui";
+import { downloadBlob } from "@multiplatform.one/platform";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useBackofficeNavigator, useBackofficePaths } from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import type { FrappeFilters } from "../shared/types";
+import { useViewConnection } from "./connection";
+import {
+  REPORT_NUMERIC_FIELDTYPES,
+  ReportFooter,
+  ReportToolbar,
+  type ReportRecordRef,
+  type ReportTotal,
+} from "./report-controls";
+import { useViewMeta } from "./viewMeta";
+import { ViewError, ViewLoading } from "./ViewStates";
+
+export interface ReportViewProps {
+  /** 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) — the screen itself stays
+   * search-param free so it mounts outside a One navigation container
+   * (stories/tests).
+   */
+  filtersParam?: string;
+  /** Base filters when no `?f=` URL param is present (stories/tests). */
+  initialFilters?: FrappeFilters;
+}
+
+const LAYOUT_FIELDTYPES = new Set(["Section Break", "Column Break", "Tab Break"]);
+const EMPTY_FILTERS: FrappeFilters = [];
+const DEFAULT_PAGE_SIZE = 20;
+
+type StatsRow = { name: string; doctype: string } & Record<string, unknown>;
+
+/**
+ * Parse the `?f=` search param: urlencoded JSON FrappeFilters
+ * (e.g. `?f=%5B%5B%22status%22%2C%22%3D%22%2C%22Open%22%5D%5D`).
+ * The router usually decodes the param already, so the raw value is tried
+ * first. Malformed input degrades to "no filters" (honest default).
+ */
+export function parseReportFiltersParam(raw: unknown): FrappeFilters | undefined {
+  if (typeof raw !== "string" || !raw) return undefined;
+  const candidates = [raw];
+  try {
+    const decoded = decodeURIComponent(raw);
+    if (decoded !== raw) candidates.push(decoded);
+  } catch {
+    // raw is not percent-encoded — the direct candidate covers it
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (!Array.isArray(parsed)) continue;
+      const filters: FrappeFilters = [];
+      for (const tuple of parsed) {
+        if (
+          Array.isArray(tuple) &&
+          tuple.length === 3 &&
+          typeof tuple[0] === "string" &&
+          typeof tuple[1] === "string"
+        ) {
+          filters.push([tuple[0], tuple[1], tuple[2]]);
+        }
+      }
+      if (filters.length > 0) return filters;
+    } catch {
+      // not JSON — try the next candidate
+    }
+  }
+  return undefined;
+}
+
+function isNullish(value: unknown): value is null | undefined {
+  return value === null || value === undefined;
+}
+
+function compareValues(a: unknown, b: unknown): number {
+  if (isNullish(a) && isNullish(b)) return 0;
+  if (isNullish(a)) return 1;
+  if (isNullish(b)) return -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  const left = String(a);
+  const right = String(b);
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export function ReportView({ doctype, filtersParam, initialFilters }: ReportViewProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const { knobProps } = useResolvedKnobs();
+  const connection = useViewConnection();
+  const { meta, isLoading: isMetaLoading, error: metaError } = useViewMeta(doctype);
+
+  // ---------------------------------------------------------------------
+  // Base filters: ?f= URL param wins, then the initialFilters prop.
+  // ---------------------------------------------------------------------
+  const urlFilters = useMemo(() => parseReportFiltersParam(filtersParam), [filtersParam]);
+  const [filtersCleared, setFiltersCleared] = useState(false);
+  useEffect(() => setFiltersCleared(false), [filtersParam, doctype]);
+  const baseFilters = filtersCleared
+    ? EMPTY_FILTERS
+    : (urlFilters ?? initialFilters ?? EMPTY_FILTERS);
+  const handleClearFilters = useCallback(() => {
+    setFiltersCleared(true);
+    // Drop the ?f= param from the URL so the cleared state survives reloads.
+    if (urlFilters) navigator.replace(paths.view(doctype, "report"));
+  }, [urlFilters, navigator, paths, doctype]);
+
+  // ---------------------------------------------------------------------
+  // Columns: all non-layout meta fields, plus a synthetic ID column.
+  // Initial selection = in_list_view fields (+ name), desk parity.
+  // ---------------------------------------------------------------------
+  const allColumns = useMemo<ReportColumn[]>(() => {
+    if (!meta) return [];
+    const idColumn: ReportColumn = {
+      fieldname: "name",
+      label: t("report.idColumn", "ID"),
+      fieldtype: "Data",
+      enabled: true,
+    };
+    return [
+      idColumn,
+      ...meta.fields
+        .filter((field) => field.fieldname && !LAYOUT_FIELDTYPES.has(field.fieldtype))
+        .map((field) => ({
+          fieldname: field.fieldname,
+          label: field.label || field.fieldname,
+          fieldtype: field.fieldtype as string,
+          enabled: Boolean(field.in_list_view),
+        })),
+    ];
+  }, [meta, t]);
+
+  const defaultSelected = useMemo(
+    () => allColumns.filter((column) => column.enabled).map((column) => column.fieldname),
+    [allColumns],
+  );
+  const [selectedOverride, setSelectedOverride] = useState<string[] | null>(null);
+  const selected = selectedOverride ?? defaultSelected;
+
+  const handleToggleColumn = useCallback(
+    (fieldname: string) => {
+      setSelectedOverride((previous) => {
+        const current = previous ?? defaultSelected;
+        if (current.includes(fieldname)) {
+          // Keep at least one column visible (the toolbar disables the last
+          // enabled row too — this guard covers races).
+          if (current.length === 1) return current;
+          return current.filter((entry) => entry !== fieldname);
+        }
+        return [...current, fieldname];
+      });
+    },
+    [defaultSelected],
+  );
+
+  const builderColumns = useMemo<ReportColumn[]>(
+    () => allColumns.map((column) => ({ ...column, enabled: selected.includes(column.fieldname) })),
+    [allColumns, selected],
+  );
+
+  // ---------------------------------------------------------------------
+  // Group-by + paging state. Reset per doctype; page resets on any change
+  // that alters result membership.
+  // ---------------------------------------------------------------------
+  const [groupBy, setGroupBy] = useState<GroupByConfig | null>(null);
+  const [pageSize, setPageSize] = useState<number>(DEFAULT_PAGE_SIZE);
+  const [page, setPage] = useState(0);
+
+  useEffect(() => {
+    setSelectedOverride(null);
+    setGroupBy(null);
+    setPage(0);
+  }, [doctype]);
+
+  const filtersKey = useMemo(() => JSON.stringify(baseFilters), [baseFilters]);
+  useEffect(() => {
+    setPage(0);
+  }, [filtersKey, pageSize]);
+
+  // ---------------------------------------------------------------------
+  // Parallel stats query: names (ordered by the doctype sort field) drive
+  // pagination windows; numeric fields drive the totals strip; the title
+  // field feeds the open-record jump. Kept independent of the column
+  // selection so toggles never resubscribe it.
+  // ---------------------------------------------------------------------
+  const numericColumns = useMemo(
+    () => allColumns.filter((column) => REPORT_NUMERIC_FIELDTYPES.has(column.fieldtype)),
+    [allColumns],
+  );
+  const titleField = meta?.title_field;
+  const sortField = (meta?.sort_field || "modified").split(" ")[0];
+  const sortAscending = (meta?.sort_order || "DESC").toLowerCase() === "asc";
+
+  const statsFields = useMemo(() => {
+    const fields = new Set<string>(["name", sortField]);
+    if (titleField) fields.add(titleField);
+    for (const column of numericColumns) fields.add(column.fieldname);
+    return [...fields];
+  }, [sortField, titleField, numericColumns]);
+
+  const [statsError, setStatsError] = useState<Error | null>(null);
+  const handleStatsError = useCallback((error: unknown) => {
+    setStatsError(error instanceof Error ? error : new Error(String(error)));
+  }, []);
+
+  // ViewConnection carries syncOptions as `unknown`; the shapes match the
+  // collection config (same FrappeProvider source) — assert once here.
+  const statsConfig = useMemo(
+    () => (connection && meta ? (connection as unknown as UseFrappeCollectionConfig) : undefined),
+    [connection, meta],
+  );
+  const statsCollection = useFrappeCollection<StatsRow>(statsConfig, doctype, {
+    fields: statsFields,
+    filters: baseFilters,
+    orderBy: { field: sortField, order: sortAscending ? Order.Asc : Order.Desc },
+    onSyncError: handleStatsError,
+  });
+  useEffect(() => setStatsError(null), [statsCollection]);
+  const { data: statsData, isLoading: statsLoading } = useLiveQuery(
+    (q) => (statsCollection ? q.from({ _stats: statsCollection }) : null),
+    [statsCollection],
+  );
+
+  // Live-query row order is not guaranteed — order deterministically by the
+  // doctype sort field (name tiebreak) so page windows are stable.
+  const statsRows = useMemo(() => {
+    const rows = [...((statsData as StatsRow[] | undefined) ?? [])];
+    const direction = sortAscending ? 1 : -1;
+    rows.sort((a, b) => {
+      const left = a[sortField];
+      const right = b[sortField];
+      const ordered =
+        isNullish(left) || isNullish(right)
+          ? compareValues(left, right)
+          : direction * compareValues(left, right);
+      return ordered || compareValues(a.name, b.name);
+    });
+    return rows;
+  }, [statsData, sortField, sortAscending]);
+
+  const statsReady = Boolean(statsError) || !statsLoading;
+  const total = statsRows.length;
+  const pageCount = Math.max(1, Math.ceil(total / pageSize));
+  const effectivePage = Math.min(page, pageCount - 1);
+  // Small results (or a failed stats query) skip the window: the grid keeps
+  // the pure live path and refreshes rows in place on realtime events.
+  const needsWindow = !statsError && total > pageSize;
+  const pageRows = useMemo(
+    () =>
+      needsWindow
+        ? statsRows.slice(effectivePage * pageSize, (effectivePage + 1) * pageSize)
+        : statsRows,
+    [needsWindow, statsRows, effectivePage, pageSize],
+  );
+
+  const builderFilters = useMemo<FrappeFilters>(() => {
+    if (!needsWindow) return baseFilters;
+    return [...baseFilters, ["name", "in", pageRows.map((row) => row.name)]];
+  }, [needsWindow, baseFilters, pageRows]);
+
+  // ---------------------------------------------------------------------
+  // Footer inputs: open-record jump + totals over the FULL filtered result
+  // (not just the page) — desk totals-row parity.
+  // ---------------------------------------------------------------------
+  const records = useMemo<ReportRecordRef[]>(
+    () =>
+      pageRows.map((row) => ({
+        name: row.name,
+        title:
+          titleField && !isNullish(row[titleField]) && row[titleField] !== ""
+            ? String(row[titleField])
+            : row.name,
+      })),
+    [pageRows, titleField],
+  );
+
+  const totals = useMemo<ReportTotal[]>(() => {
+    if (total === 0) return [];
+    return builderColumns
+      .filter((column) => column.enabled && REPORT_NUMERIC_FIELDTYPES.has(column.fieldtype))
+      .map((column) => ({
+        label: column.label,
+        fieldtype: column.fieldtype,
+        value: statsRows.reduce((sum, row) => sum + (Number(row[column.fieldname]) || 0), 0),
+      }));
+  }, [builderColumns, statsRows, total]);
+
+  const handleOpenRecord = useCallback(
+    (name: string) => {
+      navigator.navigate(paths.form(doctype, name));
+    },
+    [navigator, paths, doctype],
+  );
+
+  // ---------------------------------------------------------------------
+  // CSV export: enabled columns of the rows the grid currently holds.
+  // Web-only (Blob + anchor download); native gets an honest toast.
+  // ---------------------------------------------------------------------
+  const handleExport = useCallback(
+    (exportData: Record<string, unknown>[]) => {
+      if (!isWeb) {
+        notify({
+          severity: "warning",
+          scope: "page",
+          body: t(
+            "report.exportUnsupported",
+            "CSV export needs a browser download — not available on this platform yet",
+          ),
+        });
+        return;
+      }
+      const enabledColumns = builderColumns.filter((column) => column.enabled);
+      const escapeCell = (value: unknown): string => {
+        if (value === null || value === undefined) return "";
+        const text = String(value);
+        return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+      };
+      const lines = [
+        enabledColumns.map((column) => escapeCell(column.label)).join(","),
+        ...exportData.map((row) =>
+          enabledColumns.map((column) => escapeCell(row[column.fieldname])).join(","),
+        ),
+      ];
+      downloadBlob(
+        new Blob([lines.join("\n")], { type: "text/csv;charset=utf-8;" }),
+        `${doctype}_report.csv`,
+      );
+    },
+    [builderColumns, doctype, t],
+  );
+
+  // ---------------------------------------------------------------------
+  // Render
+  // ---------------------------------------------------------------------
+  if (isMetaLoading) return <ViewLoading />;
+  if (metaError && !meta) return <ViewError doctype={doctype} error={metaError} />;
+
+  // ReportBuilder initializes its enabled-column set (and FrappeReportBuilder
+  // its group-by state) at mount only — remount on selection/group changes.
+  const builderKey = `${doctype}::${[...selected].sort().join("|")}::${
+    groupBy ? `${groupBy.field}:${groupBy.aggregation}:${groupBy.aggregationField ?? ""}` : "none"
+  }`;
+
+  return (
+    <YStack flex={1} {...knobProps.gap}>
+      <ReportToolbar
+        columns={builderColumns}
+        onToggleColumn={handleToggleColumn}
+        groupBy={groupBy}
+        onGroupByChange={setGroupBy}
+        pageSize={pageSize}
+        onPageSizeChange={setPageSize}
+        filters={baseFilters}
+        onClearFilters={baseFilters.length > 0 ? handleClearFilters : undefined}
+      />
+      {statsReady ? (
+        <FrappeReportBuilder
+          key={builderKey}
+          doctype={doctype}
+          initialColumns={builderColumns}
+          initialGroupBy={groupBy ?? undefined}
+          filters={builderFilters}
+          showChart
+          onExport={handleExport}
+          onRowPress={(row) => {
+            if (typeof row.name === "string" && row.name) {
+              navigator.navigate(paths.form(doctype, row.name));
+            }
+          }}
+          flex={1}
+        />
+      ) : (
+        <ViewLoading />
+      )}
+      {!statsError && statsReady && (
+        <ReportFooter
+          page={effectivePage}
+          pageCount={pageCount}
+          pageSize={pageSize}
+          totalItems={total}
+          onPageChange={setPage}
+          records={records}
+          onOpenRecord={handleOpenRecord}
+          totals={totals}
+        />
+      )}
+    </YStack>
+  );
+}

package/src/views/TreeView.tsx

@@ -0,0 +1,58 @@
+// Desk "tree" view parity: only meaningful when the doctype is a tree
+// (nested set: lft/rgt + parent_<doctype> fields — surfaced by meta.is_tree).
+// FrappeTreeView fetches the full list itself (realtime-backed) and builds
+// the forest from the parent field; node click opens the form.
+import { YStack } from "@multiplatform.one/components";
+import { FrappeTreeView, type FrappeTreeViewProps } from "@multiplatform.one/frappe-ui";
+import type { ReactElement } from "react";
+import { useTranslation } from "react-i18next";
+import { useBackofficeNavigator, useBackofficePaths } from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { useViewMeta, type AnyDoc } from "./viewMeta";
+import { ViewError, ViewLoading, ViewUnsupported } from "./ViewStates";
+
+// The `one` compiler breaks explicit JSX generics — instantiate once.
+const TreeOfDoc = FrappeTreeView as (props: FrappeTreeViewProps<AnyDoc>) => ReactElement;
+
+export interface TreeViewProps {
+  /** Proper-cased doctype name (e.g. "ToDo", "Sales Order") */
+  doctype: string;
+}
+
+export function TreeView({ doctype }: TreeViewProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const { meta, isLoading: isMetaLoading, error: metaError } = useViewMeta(doctype);
+
+  if (isMetaLoading) return <ViewLoading />;
+  if (metaError && !meta) return <ViewError doctype={doctype} error={metaError} />;
+
+  if (meta && !meta.is_tree) {
+    return (
+      <ViewUnsupported
+        doctype={doctype}
+        title={t("views.treeUnsupported", "Tree not available")}
+        description={t(
+          "views.treeUnsupportedDetail",
+          "{{doctype}} is not a tree doctype — try the list view instead.",
+          { doctype },
+        )}
+      />
+    );
+  }
+
+  return (
+    <YStack flex={1}>
+      <TreeOfDoc
+        doctype={doctype}
+        titleField={meta?.title_field}
+        onNodeClick={(doc) => {
+          if (doc.name) navigator.navigate(paths.form(doctype, doc.name));
+        }}
+        error={(err) => <ViewError doctype={doctype} error={err} />}
+        flex={1}
+      />
+    </YStack>
+  );
+}

package/src/views/ViewHeader.tsx

@@ -0,0 +1,136 @@
+// Shared header for the alternate doctype views: title, a view-switcher
+// menu covering every backoffice view (including back to list), and the
+// New button (desk list-header parity). Desk parity: views the doctype
+// cannot render are hidden from the switcher — tree needs meta.is_tree,
+// image needs an image field — and the current view is check-marked.
+import {
+  Button,
+  DropdownMenu,
+  H4,
+  Text,
+  XStack,
+  type DropdownMenuEntry,
+} from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { CaretDownIcon, PlusIcon } from "@phosphor-icons/react";
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  useBackofficeCapabilities,
+  useBackofficeNavigator,
+  useBackofficePaths,
+} from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { BACKOFFICE_VIEWS, type BackofficeView } from "../navigation/paths";
+import { detectImageField, useViewMeta } from "./viewMeta";
+
+export function useViewLabels(): Record<BackofficeView, string> {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  return {
+    list: t("views.list", "List"),
+    report: t("views.report", "Report"),
+    kanban: t("views.kanban", "Kanban"),
+    calendar: t("views.calendar", "Calendar"),
+    tree: t("views.tree", "Tree"),
+    image: t("views.image", "Image"),
+    dashboard: t("views.dashboard", "Dashboard"),
+  };
+}
+
+/**
+ * Views this doctype can actually render (desk parity): tree only for tree
+ * doctypes, image only when an image field exists (meta.image_field or an
+ * Attach Image field). The provider's `capabilities.views.allow` gates the
+ * offer list too. Conditional views stay hidden until meta confirms them;
+ * `current` is always included so the switcher stays honest about where you
+ * are (e.g. a deep link to /view/tree on a flat doctype, which renders its
+ * own unsupported state).
+ */
+export function useAvailableViews(doctype: string, current?: BackofficeView): BackofficeView[] {
+  const { meta } = useViewMeta(doctype);
+  const { views } = useBackofficeCapabilities();
+  return BACKOFFICE_VIEWS.filter((candidate) => {
+    if (candidate === current) return true;
+    if (!views.enabled || !views.allow.includes(candidate)) return false;
+    if (candidate === "tree") return !!meta?.is_tree;
+    if (candidate === "image") return !!meta && !!detectImageField(meta);
+    return true;
+  });
+}
+
+export interface ViewHeaderProps {
+  /** Proper-cased doctype name (e.g. "ToDo", "Sales Order") */
+  doctype: string;
+  view: BackofficeView;
+}
+
+export function ViewHeader({ doctype, view }: ViewHeaderProps) {
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const { newDoc } = useBackofficeCapabilities();
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const labels = useViewLabels();
+  const availableViews = useAvailableViews(doctype, view);
+  // Controlled so a selection closes the menu (checkbox items keep the
+  // menu open by default — wrong for navigation).
+  const [switcherOpen, setSwitcherOpen] = useState(false);
+
+  // Every entry is a checkbox item (single-select radio semantics): the
+  // shared 18px check gutter keeps labels aligned and the current view
+  // carries the check mark.
+  const switcherItems: DropdownMenuEntry[] = availableViews.map((candidate) => ({
+    key: candidate,
+    label: labels[candidate],
+    checked: candidate === view,
+    onCheckedChange: () => {
+      setSwitcherOpen(false);
+      if (candidate !== view) navigator.navigate(paths.view(doctype, candidate));
+    },
+  }));
+
+  return (
+    <XStack
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      alignItems="center"
+      justifyContent="space-between"
+      borderBottomWidth={1}
+      borderBottomColor="$borderColor"
+      flexWrap="wrap"
+    >
+      <XStack {...knobProps.gap} alignItems="center" flexShrink={1}>
+        <H4 numberOfLines={1}>{doctype}</H4>
+        <Text color="$color10" fontSize="$3">
+          {labels[view]}
+        </Text>
+      </XStack>
+      <XStack {...knobProps.gap} alignItems="center">
+        <DropdownMenu
+          items={switcherItems}
+          open={switcherOpen}
+          onOpenChange={setSwitcherOpen}
+          placement="bottom-end"
+        >
+          <Button
+            size="$3"
+            iconAfter={CaretDownIcon}
+            aria-label={t("views.switchView", "Switch view")}
+          >
+            {labels[view]}
+          </Button>
+        </DropdownMenu>
+        {newDoc.enabled && (
+          <Button
+            size="$3"
+            theme="accent"
+            icon={PlusIcon}
+            onPress={() => navigator.navigate(paths.newDoc(doctype))}
+          >
+            {t("views.new", "New")}
+          </Button>
+        )}
+      </XStack>
+    </XStack>
+  );
+}

package/src/views/ViewStates.tsx

@@ -0,0 +1,65 @@
+// Shared honest-state chrome for the alternate views: loading, error, and
+// "this view is not supported for this doctype" — each with a way back to
+// the list view (desk parity: unsupported views bounce you to list).
+import { Button, EmptyState, Spinner, YStack } from "@multiplatform.one/components";
+import { ListBulletsIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
+import { useBackofficeNavigator, useBackofficePaths } from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+
+export function ViewLoading() {
+  return (
+    <YStack flex={1} alignItems="center" justifyContent="center">
+      <Spinner size="large" />
+    </YStack>
+  );
+}
+
+export function BackToListButton({ doctype }: { doctype: string }) {
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  return (
+    <Button
+      size="$3"
+      icon={ListBulletsIcon}
+      onPress={() => navigator.navigate(paths.list(doctype))}
+    >
+      {t("views.backToList", "Back to list")}
+    </Button>
+  );
+}
+
+export interface ViewUnsupportedProps {
+  doctype: string;
+  title: string;
+  description?: string;
+}
+
+/** Graceful "view not supported for this doctype" empty state. */
+export function ViewUnsupported({ doctype, title, description }: ViewUnsupportedProps) {
+  return (
+    <EmptyState
+      title={title}
+      description={description}
+      action={<BackToListButton doctype={doctype} />}
+    />
+  );
+}
+
+export interface ViewErrorProps {
+  doctype: string;
+  error: Error;
+}
+
+export function ViewError({ doctype, error }: ViewErrorProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  return (
+    <EmptyState
+      intent="error"
+      title={t("views.loadFailed", "Couldn't load this view")}
+      description={error.message}
+      action={<BackToListButton doctype={doctype} />}
+    />
+  );
+}