@multiplatform.one/backoffice 6.4.3 → 6.6.0

package/src/list/DoctypeListScreen.tsx

@@ -0,0 +1,1121 @@
+// Contract: the primary list view for a doctype (desk list parity —
+// filters, sort, pagination, bulk actions, tags, view switcher, New).
+//
+// Composition: FrappeTable (serverSide — Frappe REST pagination/sort/filter
+// with realtime invalidation) fed by meta-derived columns, wrapped in desk
+// chrome (header + live count, refresh, view switcher, New → QuickEntry,
+// facet sidebar, sort selector). Fixture mode (Storybook / tests) degrades
+// to the client-mode live collection and hides bench-only surfaces.
+import React from "react";
+import {
+  EmptyState,
+  H1,
+  PageHeader,
+  Paragraph,
+  ScrollView,
+  Spinner,
+  ViewSwitcher,
+  XStack,
+  YStack,
+  isWeb,
+  notify,
+} from "@multiplatform.one/components";
+import { useLayoutSizeClass } from "@multiplatform.one/theme";
+// Catalog action Button — `accent` renders the active accent intent, the
+// house expression of the one page primary (LC-05 ONE-EMPHASIS; quick entry
+// "Create" precedent). The components Button above stays for neutral chrome.
+import { Button as ActionButton } from "@multiplatform.one/forms";
+import { ArrowsClockwiseIcon, PlusIcon, SidebarSimpleIcon } from "@phosphor-icons/react";
+import {
+  FrappeTable,
+  docFieldsToFilterFields,
+  useFrappeAggregate,
+  useFrappeConfig,
+} from "@multiplatform.one/frappe-ui";
+import type { DocTypeField } from "@multiplatform.one/frappe";
+import { DataTablePagination } from "@multiplatform.one/table";
+import type {
+  BulkAction,
+  DataTableColumn,
+  DataTableState,
+  FilterableField,
+  TableFilter,
+} from "@multiplatform.one/table";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  actionsForDoctype,
+  useBackofficeCapabilities,
+  useBackofficeConfig,
+  useBackofficeNavigator,
+  useBackofficePaths,
+  useBackofficeSlots,
+  type BackofficeAction,
+} from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { BACKOFFICE_VIEWS, type BackofficeView } from "../navigation/paths";
+import { QuickEntryDialog } from "../quickEntry/QuickEntryDialog";
+import { useRecentVisit } from "../shared/useRecentVisit";
+// Permlevel role matrix (desk perm.js parity) — shared with the form surface
+// via the UI-free fieldPermissions module; drives list column pruning.
+import { buildPermLevelMatrix } from "../form/fieldPermissions";
+import type { FrappeFilters } from "../shared/types";
+import { type DoctypeMeta, useDoctypeMeta } from "../shared/useDoctypeMeta";
+import { useFrappeApp } from "../shared/useFrappeApp";
+import { useUserRoles } from "../shared/useUserRoles";
+import { AddTagsDialog } from "./AddTagsDialog";
+import { AssignToDialog } from "./AssignToDialog";
+import { bulkDelete, toggleLike } from "./bulkActions";
+import { BulkEditDialog } from "./bulk-edit-dialog";
+import { bulkExportCsv } from "./bulk-export";
+import { bulkSubmitCancel, type BulkDocstatusAction } from "./bulk-submit-cancel";
+import { FilterChips } from "./filter-chips";
+import {
+  frappeFiltersToTableFilters,
+  sameFilterTuple,
+  tableStateToFrappeFilters,
+} from "./filterConversion";
+import { ListFilterBar } from "./ListFilterBar";
+import { ListSidebar } from "./ListSidebar";
+import { type ListDoc, type ListRow, buildListColumns } from "./listColumns";
+import { listFieldsToFetch } from "./listFields";
+import {
+  parseFiltersParam,
+  parseSortParam,
+  serializeFiltersParam,
+  serializeSortParam,
+  type ListSortState,
+} from "./listUrlState";
+import { useSessionUserId as useSessionUser } from "../shared/useSessionUserId";
+
+export interface DoctypeListScreenProps {
+  /** Proper-cased doctype name (e.g. "ToDo", "Sales Order") */
+  doctype: string;
+  /**
+   * Raw `?f=` deep-link query value (urlencoded JSON FrappeFilters) —
+   * connections panels / dashboards link into filtered lists with it. Read
+   * by the route wrapper (SlugScreen); the screen itself stays search-param
+   * free so it mounts outside a One navigation container (stories/tests).
+   * Bidirectional: the screen writes filter changes back through
+   * `navigator.setParams` (listUrlState.ts documents the schema).
+   */
+  filtersParam?: string;
+  /**
+   * Raw `?sort=` query value (`<fieldname>.<asc|desc>`, see listUrlState.ts)
+   * — same route-wrapper contract and write-back channel as `filtersParam`.
+   */
+  sortParam?: string;
+  /**
+   * Meta override for fixture-backed stories/tests (fixtures expose no
+   * `getdoctype` RPC). Live surfaces leave this unset.
+   */
+  metaOverride?: DoctypeMeta;
+  /**
+   * View-switcher allowlist — intersected with the provider's
+   * `capabilities.views.allow`. Unset offers every capability-allowed view.
+   */
+  views?: readonly BackofficeView[];
+  /**
+   * Filters seeded into the user-editable filter channel on mount (chips /
+   * editor can change or remove them). `filtersParam` wins when both are set.
+   */
+  initialFilters?: FrappeFilters;
+  /**
+   * Filters ALWAYS ANDed into the query, invisible to the filter chrome and
+   * not removable by the user — scope a list to a subset (e.g. one owner).
+   */
+  fixedFilters?: FrappeFilters;
+  /** Transform the meta-derived columns before render (reorder/hide/extend). */
+  columnOverrides?: (columns: DataTableColumn<ListRow>[]) => DataTableColumn<ListRow>[];
+  /** Initial page size (user page-size picks still win afterwards). */
+  pageSize?: number;
+  /**
+   * Row-open override. Default: navigate to the document form and emit a
+   * `doc-opened` event on the provider bus.
+   */
+  onRowOpen?: (doctype: string, name: string) => void;
+  /**
+   * Hide the "New" affordances (header button + create-first empty state).
+   * The `newDoc` capability gates them too.
+   */
+  hideNewButton?: boolean;
+  /** Extra toolbar actions on selection (merged with provider `actions.list`). */
+  toolbarActions?: readonly BackofficeAction[];
+}
+
+type PendingDialog = {
+  type: "assign" | "tag" | "edit";
+  names: string[];
+  clear: () => void;
+} | null;
+
+const PAGE_SIZES = [20, 100, 500];
+
+// Generic JSX (`<FrappeTable<ListDoc> …/>`) breaks one-dev's source
+// annotation transform; instantiate the type argument outside JSX instead.
+const ListTable = FrappeTable<ListDoc>;
+
+function sameFilters(a: FrappeFilters, b: FrappeFilters): boolean {
+  return a.length === b.length && a.every((tuple, index) => sameFilterTuple(tuple, b[index]));
+}
+
+function sameSort(a: ListSortState | null, b: ListSortState | null): boolean {
+  return (a?.field ?? null) === (b?.field ?? null) && (a?.order ?? null) === (b?.order ?? null);
+}
+
+export function DoctypeListScreen({
+  doctype,
+  filtersParam,
+  sortParam,
+  metaOverride,
+  views: viewsAllowlist,
+  initialFilters,
+  fixedFilters,
+  columnOverrides,
+  pageSize,
+  onRowOpen,
+  hideNewButton,
+  toolbarActions,
+}: DoctypeListScreenProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const capabilities = useBackofficeCapabilities();
+  const { actions, emitEvent } = useBackofficeConfig();
+  const slots = useBackofficeSlots();
+  const config = useFrappeConfig();
+  const app = useFrappeApp();
+  const fixtureMode = Boolean(config?.fixtures);
+  const sessionUser = useSessionUser();
+  // Compact list chrome below 640 (theme `compact` size class — matchMedia
+  // on web, window dimensions on native; BackofficeShell drawer precedent):
+  // one title row + one scrollable switcher row, filters/sort behind a sheet.
+  const compactChrome = useLayoutSizeClass() === "compact";
+
+  // Write-on-visit for the shared recents store (workspace "Continue where
+  // you left off" strip). Fixture mode (stories/tests) stays storage-free.
+  useRecentVisit(fixtureMode ? undefined : { label: doctype, path: paths.list(doctype) });
+
+  const {
+    meta: loadedMeta,
+    loading: metaLoading,
+    error: metaError,
+  } = useDoctypeMeta(metaOverride ? undefined : doctype);
+  const meta = metaOverride ?? loadedMeta;
+
+  // Operational errors reach the host bus (never replaces the inline state).
+  useEffect(() => {
+    if (metaError && !meta) emitEvent({ type: "error", error: metaError, context: "list-meta" });
+  }, [metaError, meta, emitEvent]);
+
+  // "New" affordances: host prop + the newDoc capability.
+  const showNew = !hideNewButton && capabilities.newDoc.enabled;
+
+  // ONE FILTER SYSTEM (MOD-04): `baseFilters` is the single writable filter
+  // state for this screen. Every filter surface — quick standard filters,
+  // the tuple editor, saved filters, the chips row, the facet sidebar, the
+  // compact tools sheet, and the `?f=` deep link — reads and writes THIS
+  // state via handleBaseFiltersChange; changing it bumps `filtersGen`,
+  // remounting the table with the tuples injected as initialState.filters.
+  // The table's own filter chrome is suppressed (enableFiltering={false}
+  // below), so no second live filter state exists.
+  const [baseFilters, setBaseFilters] = useState<FrappeFilters>(() => {
+    const fromParam = parseFiltersParam(filtersParam);
+    if (fromParam.length > 0) return fromParam;
+    return initialFilters ? [...initialFilters] : fromParam;
+  });
+  const [filtersGen, setFiltersGen] = useState(0);
+  // Read-only mirror of the table's effective query (injected base tuples +
+  // the table-owned search box), synced from onStateChange — feeds the live
+  // count and facet stats. Not a second filter authority: with the table's
+  // filter chrome suppressed, search is the only table-side contribution.
+  const [effectiveFilters, setEffectiveFilters] = useState<FrappeFilters | null>(null);
+  // null = ride the doctype's meta default; `?sort=` deep links seed it.
+  const [sort, setSort] = useState<ListSortState | null>(() => parseSortParam(sortParam) ?? null);
+  const [sortGen, setSortGen] = useState(0);
+  const [refreshGen, setRefreshGen] = useState(0);
+  const [sidebarVisible, setSidebarVisible] = useState(true);
+  const [quickEntryOpen, setQuickEntryOpen] = useState(false);
+  const [pendingDialog, setPendingDialog] = useState<PendingDialog>(null);
+  const [likeOverrides, setLikeOverrides] = useState<Record<string, boolean>>({});
+  // Last page size the user picked — survives the filter/sort remounts.
+  const pageSizeRef = useRef(pageSize ?? PAGE_SIZES[0]);
+
+  // Always-ANDed host filters: joined into every query (table injection,
+  // live count, facet stats) but invisible to the user filter chrome —
+  // value-keyed so unstable array literals from the host don't churn.
+  const fixedFiltersKey = JSON.stringify(fixedFilters ?? []);
+  const fixedTuples = useMemo(
+    () => JSON.parse(fixedFiltersKey) as FrappeFilters,
+    [fixedFiltersKey],
+  );
+  const withFixed = useCallback(
+    (filters: FrappeFilters): FrappeFilters =>
+      fixedTuples.length > 0 ? [...fixedTuples, ...filters] : filters,
+    [fixedTuples],
+  );
+
+  // Seeds on doctype/param swaps (refs — prop identity must not retrigger).
+  const initialFiltersRef = useRef(initialFilters);
+  initialFiltersRef.current = initialFilters;
+  // Render-synced mirrors so imperative handlers (URL writes, the table's
+  // onStateChange) read current state without re-subscribing.
+  const baseFiltersRef = useRef(baseFilters);
+  baseFiltersRef.current = baseFilters;
+  const sortRef = useRef(sort);
+  sortRef.current = sort;
+
+  // URL round-trip, outbound half (desk parity: list_view.js
+  // update_url_with_filters → history.replaceState). Every USER state
+  // change mirrors into `?f=`/`?sort=` through the navigator's optional
+  // setParams — no history entry, no remount; hosts without the primitive
+  // (noop navigator in bare stories) skip silently and state stays local.
+  // Inbound param changes never call this (the sync effect below adopts
+  // them), so the echo cannot loop.
+  const writeUrlState = useCallback(
+    (filters: FrappeFilters, sortState: ListSortState | null) => {
+      navigator.setParams?.({
+        f: serializeFiltersParam(filters),
+        sort: sortState ? serializeSortParam(sortState) : undefined,
+      });
+    },
+    [navigator],
+  );
+
+  // The route component is reused across /backoffice/[slug] navigations, so
+  // a doctype swap or a new `?f=`/`?sort=` deep link (incl. browser
+  // back/forward — the URL is the single source) resets the list state in
+  // place. Echoes of our own writeUrlState calls arrive here too and are
+  // adopted without state churn (sameFilters/sameSort guards).
+  const lastDoctype = useRef(doctype);
+  const lastFiltersParam = useRef(filtersParam);
+  const lastSortParam = useRef(sortParam);
+  useEffect(() => {
+    const doctypeChanged = lastDoctype.current !== doctype;
+    const filtersParamChanged = lastFiltersParam.current !== filtersParam;
+    const sortParamChanged = lastSortParam.current !== sortParam;
+    if (!doctypeChanged && !filtersParamChanged && !sortParamChanged) return;
+    lastDoctype.current = doctype;
+    lastFiltersParam.current = filtersParam;
+    lastSortParam.current = sortParam;
+    if (doctypeChanged || filtersParamChanged) {
+      const fromParam = parseFiltersParam(filtersParam);
+      const next =
+        fromParam.length > 0
+          ? fromParam
+          : doctypeChanged && initialFiltersRef.current
+            ? [...initialFiltersRef.current]
+            : fromParam;
+      if (doctypeChanged || !sameFilters(next, baseFiltersRef.current)) {
+        setBaseFilters(next);
+        setEffectiveFilters(withFixed(next));
+        setFiltersGen((generation) => generation + 1);
+      }
+    }
+    if (doctypeChanged) {
+      setSort(parseSortParam(sortParam) ?? null);
+      setLikeOverrides({});
+      return;
+    }
+    if (sortParamChanged) {
+      const parsed = parseSortParam(sortParam) ?? null;
+      if (!sameSort(parsed, sortRef.current)) {
+        setSort(parsed);
+        setSortGen((generation) => generation + 1);
+      }
+    }
+  }, [doctype, filtersParam, sortParam, withFixed]);
+
+  const sortField = sort?.field ?? meta?.sort_field ?? "modified";
+  const sortOrder = sort?.order ?? (meta?.sort_order?.toUpperCase() === "ASC" ? "asc" : "desc");
+  // Effective sort as the table sees it (state ?? meta default) — the
+  // onStateChange mirror compares against THIS so the seeded initial sort
+  // never echoes a redundant `?sort=` into the URL on mount.
+  const effectiveSortRef = useRef<ListSortState>({ field: sortField, order: sortOrder });
+  effectiveSortRef.current = { field: sortField, order: sortOrder };
+  const currentFilters = effectiveFilters ?? withFixed(baseFilters);
+
+  const connection = useMemo(
+    () =>
+      config
+        ? {
+            baseURL: config.baseURL,
+            socketPort: config.socketPort,
+            auth: config.auth
+              ? {
+                  useToken: config.auth.useToken,
+                  token: typeof config.auth.token === "string" ? config.auth.token : undefined,
+                  type: config.auth.type,
+                }
+              : undefined,
+            // Forward the provider's engine options: the SyncModule is
+            // shared per baseURL and the FIRST consumer's config wins — a
+            // connection built without syncOptions here would silently
+            // strip persistKey/cdcInterval for every other screen when the
+            // list's aggregate watcher happens to construct the engine
+            // first (observed on GNOME, where this screen is the first
+            // engine touch).
+            syncOptions: config.syncOptions,
+            socketOptions: config.socketOptions,
+            fixtures: config.fixtures,
+          }
+        : undefined,
+    [config],
+  );
+
+  // Live result count — realtime refetch on doctype events.
+  const count = useFrappeAggregate(connection, {
+    doctype,
+    filters: currentFilters.length > 0 ? currentFilters : undefined,
+  });
+
+  const handleToggleLike = useCallback(
+    (name: string, nextLiked: boolean) => {
+      setLikeOverrides((previous) => ({ ...previous, [name]: nextLiked }));
+      if (!app || fixtureMode) return;
+      toggleLike(app, doctype, name, nextLiked).catch(() => {
+        setLikeOverrides((previous) => ({ ...previous, [name]: !nextLiked }));
+        notify({
+          severity: "error",
+          scope: "page",
+          body: t("list.likeFailed", "Could not update liked state"),
+        });
+      });
+    },
+    [app, fixtureMode, doctype, t],
+  );
+
+  // Session roles × meta.permissions → permlevel read matrix. Columns for
+  // fields above the roles' read level are pruned (desk hides them; the
+  // server strips their values anyway). Undefined (fixtures / roles RPC
+  // unavailable) prunes nothing — never hides more than desk would.
+  const { roles } = useUserRoles();
+  const permMatrix = useMemo(
+    () => buildPermLevelMatrix(meta?.permissions, roles),
+    [meta?.permissions, roles],
+  );
+
+  const columns = useMemo(() => {
+    const built = buildListColumns({
+      meta,
+      t: (key, fallback) => t(key, fallback),
+      sessionUser,
+      onToggleLike: handleToggleLike,
+      likeOverrides,
+      permMatrix,
+    });
+    return columnOverrides ? columnOverrides(built) : built;
+  }, [meta, t, sessionUser, handleToggleLike, likeOverrides, permMatrix, columnOverrides]);
+
+  const fields = useMemo(() => listFieldsToFetch(meta, permMatrix), [meta, permMatrix]);
+
+  // Filterable-field declarations (meta fields + the desk `_` facet
+  // columns). With the table's filter chrome suppressed these render no
+  // toolbar surface — they resolve filter TYPES for the injected tuples and
+  // keep FrappeTable from refetching meta to derive its own list.
+  const filterableFields = useMemo<FilterableField[] | undefined>(() => {
+    if (!meta?.fields) return undefined;
+    return [
+      ...docFieldsToFilterFields(meta.fields as unknown as DocTypeField[]),
+      {
+        id: "_assign",
+        label: t("list.assignedTo", "Assigned To"),
+        type: "text",
+      },
+      { id: "_user_tags", label: t("list.tags", "Tags"), type: "text" },
+      { id: "_liked_by", label: t("list.likedBy", "Liked By"), type: "text" },
+    ];
+  }, [meta, t]);
+
+  const initialTableFilters = useMemo<TableFilter[]>(
+    () => frappeFiltersToTableFilters(withFixed(baseFilters)),
+    [baseFilters, withFixed],
+  );
+
+  const handleBaseFiltersChange = useCallback(
+    (next: FrappeFilters) => {
+      setBaseFilters(next);
+      setEffectiveFilters(withFixed(next));
+      setFiltersGen((generation) => generation + 1);
+      writeUrlState(next, sortRef.current);
+    },
+    [withFixed, writeUrlState],
+  );
+
+  const handleSortChange = useCallback(
+    (field: string, order: "asc" | "desc") => {
+      setSort({ field, order });
+      setSortGen((generation) => generation + 1);
+      writeUrlState(baseFiltersRef.current, { field, order });
+    },
+    [writeUrlState],
+  );
+
+  // DataTable's onStateChange fires on every table render (its state object
+  // is rebuilt each pass), so every mirror below MUST bail to the previous
+  // state identity when nothing changed — fresh objects would loop
+  // render → onStateChange → setState → render forever.
+  const handleStateChange = useCallback(
+    (state: DataTableState) => {
+      if (state.pagination?.pageSize) pageSizeRef.current = state.pagination.pageSize;
+      const nextFilters = tableStateToFrappeFilters(state);
+      setEffectiveFilters((previous) =>
+        previous && sameFilters(previous, nextFilters) ? previous : nextFilters,
+      );
+      // Header-sort clicks stay internal to the table; mirror them into the
+      // sort selector without bumping sortGen (no remount needed). Compared
+      // against the EFFECTIVE sort so the seeded initial sorting is a no-op;
+      // a real header sort also mirrors into the URL (write-once — the
+      // effective ref updates on the next render).
+      const sorting = state.sorting?.[0];
+      if (sorting) {
+        const order = sorting.desc ? ("desc" as const) : ("asc" as const);
+        const effective = effectiveSortRef.current;
+        if (effective.field !== sorting.id || effective.order !== order) {
+          const nextSort: ListSortState = { field: sorting.id, order };
+          setSort(nextSort);
+          writeUrlState(baseFiltersRef.current, nextSort);
+        }
+      }
+    },
+    [writeUrlState],
+  );
+
+  const handleRefresh = useCallback(() => {
+    setRefreshGen((generation) => generation + 1);
+    count.refresh();
+  }, [count]);
+
+  const handleRowClick = useCallback(
+    (row: ListRow) => {
+      if (!row.name) return;
+      if (onRowOpen) {
+        onRowOpen(doctype, row.name);
+        return;
+      }
+      emitEvent({ type: "doc-opened", doctype, name: row.name });
+      navigator.navigate(paths.form(doctype, row.name));
+    },
+    [navigator, paths, doctype, onRowOpen, emitEvent],
+  );
+
+  const handleBulkExport = useCallback(
+    async (names: string[]) => {
+      if (!app) return;
+      try {
+        const result = await bulkExportCsv(app, doctype, names, meta);
+        if (!result.downloaded) {
+          notify({
+            severity: "warning",
+            scope: "page",
+            body: t(
+              "list.exportUnsupported",
+              "CSV export needs a browser download — not available on this platform yet",
+            ),
+          });
+        } else {
+          notify({
+            severity: "success",
+            scope: "page",
+            body: t("list.exportDone", {
+              count: result.rowCount,
+              defaultValue_one: "Exported {{count}} row to CSV",
+              defaultValue_other: "Exported {{count}} rows to CSV",
+            }),
+          });
+        }
+      } catch (error) {
+        notify({
+          severity: "error",
+          scope: "page",
+          body:
+            error instanceof Error ? error.message : t("list.exportFailed", "CSV export failed"),
+        });
+      }
+    },
+    [app, doctype, meta, t],
+  );
+
+  const handleBulkDocstatus = useCallback(
+    async (names: string[], action: BulkDocstatusAction) => {
+      if (!app) return;
+      try {
+        const result = await bulkSubmitCancel(app, doctype, names, action);
+        if (result.queued) {
+          notify({
+            severity: "info",
+            scope: "page",
+            body: t("list.docstatusQueued", {
+              action: action === "submit" ? t("list.submit", "Submit") : t("list.cancel", "Cancel"),
+              count: result.attempted,
+              defaultValue_one: "{{action}} of {{count}} document queued in the background",
+              defaultValue_other: "{{action}} of {{count}} documents queued in the background",
+            }),
+          });
+        } else if (result.failed.length > 0) {
+          notify({
+            severity: "warning",
+            scope: "page",
+            // Two independent counts in one sentence — phrased "X of Y" so
+            // no noun needs a second plural slot.
+            body: t("list.docstatusPartial", {
+              count: result.attempted - result.failed.length,
+              total: result.attempted,
+              names: result.failed.join(", "),
+              defaultValue: "Processed {{count}} of {{total}} documents; failed: {{names}}",
+            }),
+          });
+        } else {
+          notify({
+            severity: "success",
+            scope: "page",
+            body:
+              action === "submit"
+                ? t("list.submitDone", {
+                    count: result.attempted,
+                    defaultValue_one: "Submitted {{count}} document",
+                    defaultValue_other: "Submitted {{count}} documents",
+                  })
+                : t("list.cancelDone", {
+                    count: result.attempted,
+                    defaultValue_one: "Cancelled {{count}} document",
+                    defaultValue_other: "Cancelled {{count}} documents",
+                  }),
+          });
+        }
+        count.refresh();
+      } catch (error) {
+        notify({
+          severity: "error",
+          scope: "page",
+          body:
+            error instanceof Error
+              ? error.message
+              : t("list.docstatusFailed", "Bulk action failed"),
+        });
+      }
+    },
+    [app, doctype, t, count],
+  );
+
+  const isSubmittable = meta?.is_submittable === 1;
+
+  // Host-injected selection actions: provider `actions.list` (doctype-scoped
+  // registry) + the `toolbarActions` prop, appended to the built-in bulk
+  // actions.
+  const hostListActions = useMemo<BulkAction<ListRow>[]>(() => {
+    const injected: BackofficeAction[] = [
+      ...actionsForDoctype(actions.list, doctype),
+      ...actionsForDoctype(toolbarActions, doctype),
+    ];
+    return injected.map((action) => ({
+      id: action.id,
+      label: action.label,
+      onExecute: (items: ListRow[]) => {
+        const names = items.map((item) => item.name).filter(Boolean) as string[];
+        action.onPress({ doctype, selection: names });
+      },
+    }));
+  }, [actions.list, toolbarActions, doctype]);
+
+  const bulkActions = useMemo<BulkAction<ListRow>[]>(
+    () => [
+      // Assignment/tag actions ride their capability flags.
+      ...(capabilities.assignments.enabled
+        ? ([
+            {
+              id: "assign",
+              label: t("list.assignTitle", "Assign To"),
+              onExecute: (items, clearSelection) => {
+                const names = items.map((item) => item.name).filter(Boolean) as string[];
+                if (names.length > 0)
+                  setPendingDialog({ type: "assign", names, clear: clearSelection });
+              },
+            },
+          ] as BulkAction<ListRow>[])
+        : []),
+      ...(capabilities.tags.enabled
+        ? ([
+            {
+              id: "tag",
+              label: t("list.tagTitle", "Add Tags"),
+              onExecute: (items, clearSelection) => {
+                const names = items.map((item) => item.name).filter(Boolean) as string[];
+                if (names.length > 0)
+                  setPendingDialog({ type: "tag", names, clear: clearSelection });
+              },
+            },
+          ] as BulkAction<ListRow>[])
+        : []),
+      {
+        id: "edit",
+        label: t("list.editTitle", "Bulk Edit"),
+        onExecute: (items, clearSelection) => {
+          const names = items.map((item) => item.name).filter(Boolean) as string[];
+          if (names.length > 0) setPendingDialog({ type: "edit", names, clear: clearSelection });
+        },
+      },
+      {
+        id: "export",
+        label: t("list.export", "Export CSV"),
+        onExecute: async (items) => {
+          const names = items.map((item) => item.name).filter(Boolean) as string[];
+          if (names.length > 0) await handleBulkExport(names);
+        },
+      },
+      ...(isSubmittable
+        ? ([
+            {
+              id: "submit",
+              label: t("list.submit", "Submit"),
+              requiresConfirmation: true,
+              confirmTitle: t("list.submitTitle", "Submit documents"),
+              confirmMessage: t("list.submitConfirm", {
+                defaultValue: "Submit the selected {{doctype}} documents?",
+                doctype,
+              }),
+              onExecute: async (items, clearSelection) => {
+                const names = items.map((item) => item.name).filter(Boolean) as string[];
+                if (names.length === 0) return;
+                await handleBulkDocstatus(names, "submit");
+                clearSelection();
+              },
+            },
+            {
+              id: "cancel",
+              label: t("list.cancel", "Cancel"),
+              requiresConfirmation: true,
+              confirmTitle: t("list.cancelTitle", "Cancel documents"),
+              confirmMessage: t("list.cancelBody", {
+                defaultValue: "Cancel the selected submitted {{doctype}} documents?",
+                doctype,
+              }),
+              onExecute: async (items, clearSelection) => {
+                const names = items.map((item) => item.name).filter(Boolean) as string[];
+                if (names.length === 0) return;
+                await handleBulkDocstatus(names, "cancel");
+                clearSelection();
+              },
+            },
+          ] as BulkAction<ListRow>[])
+        : []),
+      {
+        id: "delete",
+        label: t("list.delete", "Delete"),
+        variant: "destructive",
+        requiresConfirmation: true,
+        confirmTitle: t("list.deleteTitle", "Delete documents"),
+        confirmMessage: t("list.deleteConfirm", {
+          defaultValue: "Permanently delete the selected {{doctype}} documents?",
+          doctype,
+        }),
+        onExecute: async (items, clearSelection) => {
+          if (!app) return;
+          const names = items.map((item) => item.name).filter(Boolean) as string[];
+          if (names.length === 0) return;
+          const result = await bulkDelete(app, doctype, names);
+          if (result.failed.length > 0) {
+            notify({
+              severity: "warning",
+              scope: "page",
+              body: t("list.deletePartial", {
+                count: result.succeeded.length,
+                total: names.length,
+                names: result.failed.map((failure) => failure.name).join(", "),
+                defaultValue: "Deleted {{count}} of {{total}} documents; failed: {{names}}",
+              }),
+            });
+          } else {
+            notify({
+              severity: "success",
+              scope: "page",
+              body: t("list.deleteDone", {
+                count: result.succeeded.length,
+                defaultValue_one: "Deleted {{count}} document",
+                defaultValue_other: "Deleted {{count}} documents",
+              }),
+            });
+          }
+          clearSelection();
+          count.refresh();
+        },
+      },
+      ...hostListActions,
+    ],
+    [
+      t,
+      app,
+      doctype,
+      count,
+      isSubmittable,
+      handleBulkExport,
+      handleBulkDocstatus,
+      capabilities.assignments.enabled,
+      capabilities.tags.enabled,
+      hostListActions,
+    ],
+  );
+
+  // Selection + the bulk bar ride the bulkActions capability as one unit.
+  const bulkActionsEnabled = capabilities.bulkActions.enabled;
+
+  // View switcher options: capability allowlist ∩ the `views` prop.
+  const views = useMemo(() => {
+    if (!capabilities.views.enabled) return [];
+    return BACKOFFICE_VIEWS.filter(
+      (view) =>
+        capabilities.views.allow.includes(view) &&
+        (!viewsAllowlist || viewsAllowlist.includes(view)),
+    ).map((view) => ({
+      type: view,
+      label: t(`views.${view}`, view.charAt(0).toUpperCase() + view.slice(1)),
+    }));
+  }, [t, capabilities.views.enabled, capabilities.views.allow, viewsAllowlist]);
+
+  const tableKey = `${doctype}|${refreshGen}|${sortGen}|${filtersGen}`;
+
+  if (metaError && !meta) {
+    return (
+      <YStack flex={1}>
+        <EmptyState
+          intent="error"
+          title={t("list.metaError", {
+            defaultValue: "Could not load {{doctype}}",
+            doctype,
+          })}
+          description={metaError.message}
+        />
+      </YStack>
+    );
+  }
+
+  if (!meta && metaLoading) {
+    return (
+      <YStack flex={1} alignItems="center" justifyContent="center" padding="$6">
+        <Spinner size="large" />
+      </YStack>
+    );
+  }
+
+  const showCreateFirst = !count.isLoading && count.value === 0 && currentFilters.length === 0;
+
+  // i18next plural forms — never the lazy "(s)" suffix (the count picks the
+  // form; other locales pluralize correctly through the same key).
+  const countText = count.isLoading
+    ? undefined
+    : t("list.resultCount", {
+        count: count.value ?? 0,
+        defaultValue_one: "{{count}} result",
+        defaultValue_other: "{{count}} results",
+      });
+  const handleViewChange = (view: string) => {
+    if (view !== "list") navigator.navigate(paths.view(doctype, view as BackofficeView));
+  };
+  // Nothing to switch to (capability/allowlist narrowed to list or off).
+  const showViewSwitcher = views.length > 1;
+
+  return (
+    <YStack flex={1} gap={compactChrome ? "$2" : "$3"} padding={compactChrome ? "$3" : "$4"}>
+      {compactChrome ? (
+        // Compact chrome (< 640): one title row (title + live count inline,
+        // icon refresh, compact New), then one row with the view switcher
+        // (horizontally scrollable — all views stay reachable) and the
+        // single Filter affordance (filters/sort collapse into its sheet).
+        <PageHeader
+          heading={
+            <XStack gap="$2" alignItems="baseline" flexWrap="wrap">
+              <H1 size="$7" margin={0} flexShrink={1} minWidth={0}>
+                {doctype}
+              </H1>
+              {countText ? (
+                <Paragraph size="$2" color="$color10" margin={0}>
+                  {countText}
+                </Paragraph>
+              ) : null}
+            </XStack>
+          }
+          actions={
+            <XStack gap="$2" alignItems="center">
+              {/* House Button: icon slot (LC-53) + the sub-44 circular size
+                  resolves the press floor through the house channel (LC-54). */}
+              <ActionButton
+                size="$3"
+                circular
+                chromeless
+                icon={ArrowsClockwiseIcon}
+                onPress={handleRefresh}
+                aria-label={t("list.refresh", "Refresh")}
+              />
+              {showNew && (
+                <ActionButton
+                  size="$3"
+                  accent
+                  icon={PlusIcon}
+                  onPress={() => setQuickEntryOpen(true)}
+                  aria-label={t("list.new", {
+                    defaultValue: "New {{doctype}}",
+                    doctype,
+                  })}
+                >
+                  {t("list.newShort", "New")}
+                </ActionButton>
+              )}
+            </XStack>
+          }
+        >
+          <XStack gap="$2" alignItems="center">
+            <ScrollView
+              horizontal
+              flexGrow={1}
+              flexShrink={1}
+              minWidth={0}
+              showsHorizontalScrollIndicator={false}
+            >
+              {showViewSwitcher ? (
+                <ViewSwitcher views={views} currentView="list" onViewChange={handleViewChange} />
+              ) : null}
+            </ScrollView>
+            <ListFilterBar
+              compact
+              doctype={doctype}
+              meta={meta}
+              filters={baseFilters}
+              onFiltersChange={handleBaseFiltersChange}
+              sortField={sortField}
+              sortOrder={sortOrder}
+              onSortChange={handleSortChange}
+            />
+          </XStack>
+          {/* Shared chips readout (MOD-04 honest state): the table's own
+              chips row is suppressed with the rest of its filter chrome, so
+              compact renders the list-chrome chips here (wide gets them
+              inside ListFilterBar). Renders nothing while no filters apply. */}
+          <FilterChips
+            meta={meta}
+            filters={baseFilters}
+            onFiltersChange={handleBaseFiltersChange}
+          />
+        </PageHeader>
+      ) : (
+        <>
+          <PageHeader
+            title={doctype}
+            // D-11 page-title dial: moderate (32px) — list titles are
+            // wayfinding, not display copy (matches WorkspaceScreen).
+            titleScale="moderate"
+            subtitle={countText}
+            actions={
+              <XStack gap="$2" alignItems="center" flexWrap="wrap">
+                {/* Icon-only refresh (desk parity): a text "Refresh" at the
+                    switcher's left read as one of its segments — an action
+                    mixed into a view picker (LC-26). House Button: icon slot
+                    (LC-53), circular sub-44 press floor via the house
+                    channel (LC-54). */}
+                <ActionButton
+                  size="$3"
+                  circular
+                  chromeless
+                  icon={ArrowsClockwiseIcon}
+                  onPress={handleRefresh}
+                  aria-label={t("list.refresh", "Refresh")}
+                />
+                {showViewSwitcher ? (
+                  <ViewSwitcher views={views} currentView="list" onViewChange={handleViewChange} />
+                ) : null}
+                {showNew && (
+                  <ActionButton size="$2" accent onPress={() => setQuickEntryOpen(true)}>
+                    {t("list.new", { defaultValue: "New {{doctype}}", doctype })}
+                  </ActionButton>
+                )}
+              </XStack>
+            }
+          />
+
+          {/* flex-start: the toggle rides the filter bar's FIRST control row
+              (both 44px) — centering floated it between rows when the bar
+              wraps (Axiom 16 row line). */}
+          <XStack gap="$2" alignItems="flex-start">
+            {!fixtureMode && (
+              // Icon-only sidebar toggle: the bare "Hide sidebar" text read
+              // as a floating label, not a control, and its 28px box missed
+              // the press floor. House Button icon slot (LC-53) + circular
+              // sub-44 floor via the house channel (LC-54); aria-expanded
+              // carries the region state.
+              <ActionButton
+                size="$3"
+                circular
+                chromeless
+                icon={SidebarSimpleIcon}
+                display="none"
+                $sm={{ display: "flex" }}
+                onPress={() => setSidebarVisible((visible) => !visible)}
+                aria-expanded={sidebarVisible}
+                aria-label={
+                  sidebarVisible
+                    ? t("list.hideSidebar", "Hide sidebar")
+                    : t("list.showSidebar", "Show sidebar")
+                }
+              />
+            )}
+            <YStack flex={1}>
+              <ListFilterBar
+                doctype={doctype}
+                meta={meta}
+                filters={baseFilters}
+                onFiltersChange={handleBaseFiltersChange}
+                sortField={sortField}
+                sortOrder={sortOrder}
+                onSortChange={handleSortChange}
+              />
+            </YStack>
+          </XStack>
+        </>
+      )}
+
+      {(() => {
+        const listBody = (
+          <XStack flex={1} gap="$2" alignItems="stretch">
+            {/* Facet sidebar needs bench RPCs (fixture mode hides it) and is
+                hidden on narrow viewports (< $sm) like desk. MOD-04 keeps it:
+                facet clicks toggle tuples through the same baseFilters
+                channel (handleBaseFiltersChange) — counts are informative,
+                the chips row is the shared readout. */}
+            {sidebarVisible && !fixtureMode && (
+              <YStack display="none" $sm={{ display: "flex" }}>
+                <ListSidebar
+                  doctype={doctype}
+                  meta={meta}
+                  filters={currentFilters}
+                  onFiltersChange={handleBaseFiltersChange}
+                />
+              </YStack>
+            )}
+            <YStack flex={1} minWidth={0}>
+              {showCreateFirst ? (
+                (slots.renderListEmpty?.({ doctype }) ?? (
+                  <EmptyState
+                    title={t("list.emptyTitle", {
+                      defaultValue: "No {{doctype}} yet",
+                      doctype,
+                    })}
+                    description={t("list.emptyDescription", {
+                      defaultValue: "Create your first {{doctype}} to get started",
+                      doctype,
+                    })}
+                    action={
+                      showNew ? (
+                        <ActionButton accent onPress={() => setQuickEntryOpen(true)}>
+                          {t("list.new", {
+                            defaultValue: "New {{doctype}}",
+                            doctype,
+                          })}
+                        </ActionButton>
+                      ) : undefined
+                    }
+                  />
+                ))
+              ) : (
+                <ListTable
+                  key={tableKey}
+                  doctype={doctype}
+                  columns={columns}
+                  fields={fields}
+                  serverSide={!fixtureMode}
+                  {...(fixtureMode && withFixed(baseFilters).length > 0
+                    ? { filters: withFixed(baseFilters) }
+                    : {})}
+                  filterableFields={filterableFields}
+                  initialState={{
+                    sorting: [{ id: sortField, desc: sortOrder === "desc" }],
+                    filters: initialTableFilters,
+                    pagination: { pageIndex: 0, pageSize: pageSizeRef.current },
+                  }}
+                  enablePagination
+                  renderPagination={(paginationProps) => (
+                    <DataTablePagination
+                      {...paginationProps}
+                      pageSizeOptions={[...PAGE_SIZES]}
+                      compact
+                    />
+                  )}
+                  // ONE FILTER SYSTEM (MOD-04 / LC-16): the list chrome is
+                  // the single filtering authority; tuples reach the table
+                  // only through initialState.filters (remount via tableKey).
+                  // enableFiltering={false} suppresses every in-table filter
+                  // entry point (toolbar Filter button, column funnels, chips
+                  // row, card Add Filter) and detaches the search clear-X
+                  // from the injected filters — the table contributes search
+                  // + header sort only, mirrored back via onStateChange.
+                  enableFiltering={false}
+                  enableSorting
+                  enableRowSelection={bulkActionsEnabled}
+                  {...(bulkActionsEnabled ? { bulkActions } : {})}
+                  onRowClick={handleRowClick}
+                  onStateChange={handleStateChange}
+                />
+              )}
+            </YStack>
+          </XStack>
+        );
+        // Native has no page-level scroll and the table body ships none —
+        // wrap in a vertical ScrollView (DocFormScreen precedent) so rows
+        // below the fold stay reachable. Compact web is in the same boat:
+        // the card list renders in flow inside the shell's overflow-hidden
+        // frame, so it needs the same scroll wrapper (the compact header
+        // stays pinned above it). Wide web keeps the flex layout as-is —
+        // the grid body scrolls internally.
+        return isWeb && !compactChrome ? listBody : <ScrollView flex={1}>{listBody}</ScrollView>;
+      })()}
+
+      {showNew && (
+        <QuickEntryDialog
+          doctype={doctype}
+          open={quickEntryOpen}
+          onOpenChange={setQuickEntryOpen}
+          onCreated={(name) => {
+            emitEvent({ type: "doc-opened", doctype, name });
+            navigator.navigate(paths.form(doctype, name));
+          }}
+          onEditFullForm={() => navigator.navigate(paths.newDoc(doctype))}
+        />
+      )}
+      <AssignToDialog
+        doctype={doctype}
+        names={pendingDialog?.type === "assign" ? pendingDialog.names : []}
+        open={pendingDialog?.type === "assign"}
+        onOpenChange={(open) => {
+          if (!open) setPendingDialog(null);
+        }}
+        onDone={() => {
+          pendingDialog?.clear();
+          count.refresh();
+        }}
+      />
+      <AddTagsDialog
+        doctype={doctype}
+        names={pendingDialog?.type === "tag" ? pendingDialog.names : []}
+        open={pendingDialog?.type === "tag"}
+        onOpenChange={(open) => {
+          if (!open) setPendingDialog(null);
+        }}
+        onDone={() => {
+          pendingDialog?.clear();
+          count.refresh();
+        }}
+      />
+      <BulkEditDialog
+        doctype={doctype}
+        meta={meta}
+        names={pendingDialog?.type === "edit" ? pendingDialog.names : []}
+        open={pendingDialog?.type === "edit"}
+        onOpenChange={(open) => {
+          if (!open) setPendingDialog(null);
+        }}
+        onDone={() => {
+          pendingDialog?.clear();
+          count.refresh();
+        }}
+      />
+    </YStack>
+  );
+}