@multiplatform.one/frappe-ui 7.23.2 → 7.24.0

package/src/FrappeListView.tsx

@@ -1,6 +1,15 @@
 import { HttpClient, useDocTypeMeta } from "@multiplatform.one/frappe";
 import type { DataTableColumn } from "@multiplatform.one/table";
-import { ArrowsClockwiseIcon, PlusIcon } from "@phosphor-icons/react";
+import {
+  ArrowsClockwiseIcon,
+  HeartIcon,
+  ImageIcon,
+  ListIcon,
+  MagnifyingGlassIcon,
+  PlusIcon,
+  SparkleIcon,
+  TableIcon,
+} from "@phosphor-icons/react";
 import React, { useState, useMemo, useCallback, useEffect } from "react";
 import { useTranslation } from "react-i18next";
 import { Button, SearchInput, Spinner } from "@multiplatform.one/forms";
@@ -9,10 +18,14 @@ import { SavedFilterDropdown, useSavedFilters, type ParsedFilter } from "@multip
 import {
   AsyncBoundary,
   Avatar,
+  EmptyState,
   ListPageLayout,
   PageHeader,
+  SkipLink,
+  Tooltip,
   ViewSwitcher,
   componentColors,
+  showToast,
   type ImageGridProps,
 } from "@multiplatform.one/components";
 import { pressTargetStyle, useResolvedKnobs } from "@multiplatform.one/theme";
@@ -20,11 +33,29 @@ import { storage } from "@multiplatform.one/store";
 import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeList, type FrappeListProps } from "./FrappeList";
 import { FrappeNotConfigured } from "./FrappeNotConfigured";
+import { FrappeRowsReader, type FrappeRowsSnapshot } from "./FrappeRowsReader";
 import { FrappeTable } from "./FrappeTable";
 import { useDocRights } from "./formEngine/useDocRights";
-import { frappeRouteHref, useFrappeRouter } from "./frappeNavigation";
+import { frappeRouteHref, useFrappeRouter, useRouteLoaderData } from "./frappeNavigation";
 import { connectionsFromMeta, type FrappeConnection } from "./frappeConnections";
 import { isPermissionError } from "./liveErrors";
+import { favoritesKey } from "./list/favorites";
+import { RecordCard } from "./list/RecordCard";
+import { recordTitle, type FrappeRecordLook } from "./list/recordLook";
+import { ListControls } from "./list/ListControls";
+import {
+  isListNarrowed,
+  listStateFilters,
+  listStateOrderBy,
+  type FrappeListControls,
+  type FrappeListFacet,
+  type FrappeListFilter,
+  type FrappeListRange,
+  type FrappeListSort,
+} from "./list/listState";
+import { ListToastHost } from "./list/ListToastHost";
+import { ShufflePanel } from "./list/ShufflePanel";
+import { useListControls } from "./list/useListControls";
 import { useConnectionFilters, type FrappeDoctypeFilter } from "./useConnectionFilters";
 
 interface ListFieldConfig {
@@ -35,6 +66,30 @@ interface ListFieldConfig {
 
 export type ListViewMode = "list" | "table" | "grid";
 
+/** What a card needs from the list beyond its row. */
+export interface FrappeListCard {
+  /** The record's page, when the list is routed. */
+  href?: string;
+  /** Opens the record the way a row press does. */
+  open: () => void;
+  /** Facet param to the record's values (a Pokemon's types, in slot order). */
+  facets: Record<string, string[]>;
+  /** Present when the list offers favorites. */
+  favorite?: { active: boolean; toggle: () => void };
+}
+
+/** A page-header action of a routed list; icon-only under sm. */
+export interface FrappeListAction {
+  label: string;
+  icon?: React.ComponentType<{ size?: number }>;
+  /** Opened through the FrappeProvider's navigation. */
+  href?: string;
+  onPress?: () => void;
+  /** Tooltip. */
+  hint?: string;
+  testID?: string;
+}
+
 export interface FrappeListViewProps<TDoc extends { name: string; doctype: string }> extends Omit<
   YStackProps,
   "children"
@@ -71,14 +126,27 @@ export interface FrappeListViewProps<TDoc extends { name: string; doctype: strin
   orderBy?: FrappeListProps<TDoc>["orderBy"];
   limit?: number;
   initialRows?: readonly Partial<TDoc>[];
+  /**
+   * The route's loader (`frappeListLoader`): the rows it rendered on the
+   * server seed the list, read through the host's navigation.
+   */
+  loader?: (...args: never[]) => Promise<{ rows: readonly Partial<TDoc>[] }>;
   columns?: DataTableColumn<Partial<TDoc>>[];
   displayFields?: ListFieldConfig[];
   /**
    * Per-row card slot. Given, the view gains a card grid (`grid` mode, the
    * catalog ImageGrid) that draws each row with it; loading, empty and error
-   * stay the view's own states.
+   * stay the view's own states. A host that draws the grid itself may leave
+   * `card` out.
    */
-  renderCard?: (doc: Partial<TDoc>, index: number) => React.ReactNode;
+  renderCard?: (doc: Partial<TDoc>, index: number, card?: FrappeListCard) => React.ReactNode;
+  /**
+   * How the doctype's records present. With `images` and no card slot, the
+   * grid draws each record as a RecordCard: the look's title, code,
+   * subtitle and images, the well tinted and badged by the first facet that
+   * declares tints, the favorite heart when the list keeps favorites.
+   */
+  look?: FrappeRecordLook<TDoc>;
   /** Card grid: column count, tile rung and media aspect. */
   gridProps?: Pick<ImageGridProps<Partial<TDoc>>, "columns" | "tileSize" | "mediaAspect">;
   /** Replaces the default empty message in list and card modes. */
@@ -98,6 +166,40 @@ export interface FrappeListViewProps<TDoc extends { name: string; doctype: strin
   showFilterSidebar?: boolean;
   /** @deprecated The toolbar always renders the List/Table switcher now. */
   enableViewSwitcher?: boolean;
+  /** Routed page title; defaults to the doctype. */
+  title?: string;
+  /** Routed page subtitle from the number of records the list reads. */
+  subtitle?: (count: number) => string;
+  /**
+   * Routed page actions. With the toolbar off, the view switcher and Add
+   * join them in the page header.
+   */
+  actions?: readonly FrappeListAction[];
+  /** Header content ahead of the actions. */
+  headerAccessory?: React.ReactNode;
+  /** The field that names a record in toasts; defaults to meta.title_field. */
+  titleField?: string;
+  /** Sort choices, first is the default; given, a Sort select joins the controls. */
+  sorts?: readonly FrappeListSort[];
+  /** The bench filters a search becomes; defaults to a like on the title field. */
+  searchFilter?: (query: string) => readonly FrappeListFilter[];
+  searchPlaceholder?: string;
+  /** One chip rail per facet, with each value's record count. */
+  facets?: readonly FrappeListFacet[];
+  /** One minimum-value slider per numeric field. */
+  ranges?: readonly FrappeListRange[];
+  /**
+   * Star records on this device and filter to them: true keys the stars by
+   * doctype, a string names the storage key.
+   */
+  favorites?: boolean | string;
+  /** A random-record picker; `label` names a record on its wheel. */
+  shuffle?: { label: (doc: Partial<TDoc>) => string };
+  /**
+   * Keep the controls and the view in the route's query params, so a
+   * refresh or a shared link reproduces the list.
+   */
+  urlState?: boolean;
   baseURL?: string;
   auth?: { useToken?: boolean; token?: string; type?: string };
   syncOptions?: Record<string, unknown>;
@@ -105,6 +207,9 @@ export interface FrappeListViewProps<TDoc extends { name: string; doctype: strin
 
 const storageKeyPrefix = "frappe-listview-";
 
+/** Cards whose images load eagerly; the rest wait until they near the viewport. */
+const eagerCards = 6;
+
 // Frappe document bookkeeping keys -- never useful as display columns.
 const internalDocKeys = new Set([
   "name",
@@ -197,10 +302,12 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
   route,
   orderBy,
   limit,
-  initialRows,
+  initialRows: initialRowsProp,
+  loader,
   columns,
   displayFields,
   renderCard,
+  look,
   gridProps,
   emptyState,
   onRetry,
@@ -211,13 +318,27 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
   showFilterSidebar = false,
   // deprecated: switcher always renders; destructured so it stays out of stackProps
   enableViewSwitcher: _enableViewSwitcher,
+  title,
+  subtitle,
+  actions,
+  headerAccessory,
+  titleField,
+  sorts,
+  searchFilter,
+  searchPlaceholder,
+  facets,
+  ranges,
+  favorites,
+  shuffle,
+  urlState = false,
   baseURL,
   auth,
   syncOptions,
   ...stackProps
 }: FrappeListViewProps<TDoc>) {
   const config = useFrappeConfig();
-  const navigate = useFrappeRouter()?.navigate;
+  const router = useFrappeRouter();
+  const navigate = router?.navigate;
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
   const theme = useTheme();
@@ -242,9 +363,6 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
   };
 
   const [storedViewMode, setViewModeState] = useState<ListViewMode>(defaultViewMode);
-  const requestedViewMode = controlledViewMode ?? storedViewMode;
-  const viewMode: ListViewMode =
-    requestedViewMode === "grid" && !renderCard ? "list" : requestedViewMode;
 
   useEffect(() => {
     let cancelled = false;
@@ -260,16 +378,6 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
     };
   }, [doctype, defaultViewMode]);
 
-  const setViewMode = useCallback(
-    (mode: ListViewMode) => {
-      onViewModeChange?.(mode);
-      if (controlledViewMode !== undefined) return;
-      setViewModeState(mode);
-      void setStoredViewMode(doctype, mode);
-    },
-    [doctype, controlledViewMode, onViewModeChange],
-  );
-
   const {
     meta,
     isLoading: isMetaLoading,
@@ -290,15 +398,6 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
       (route !== undefined && navigate
         ? () => navigate(frappeRouteHref(route, { mode: "create" }))
         : undefined));
-  const asPage = (view: React.ReactElement) =>
-    route === undefined ? (
-      view
-    ) : (
-      <ListPageLayout scroll={false} header={<PageHeader title={doctype} divider={false} />}>
-        {view}
-      </ListPageLayout>
-    );
-
   // Guest fallback: DocType meta is permission-gated (Guests get 403) while
   // the documents themselves are often guest-readable. Peek one doc with
   // fields=["*"] and derive display fields from its keys so the views render
@@ -472,10 +571,108 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
     () => connections ?? (isMetaLoading ? undefined : connectionsFromMeta(meta)),
     [connections, isMetaLoading, meta],
   );
+
+  const searchField = useMemo(() => {
+    if (meta?.title_field) return meta.title_field;
+    if (metaListFields.length > 0) return metaListFields[0].fieldname;
+    if (peekedFields && peekedFields.length > 0) return peekedFields[0];
+    return "name";
+  }, [meta, metaListFields, peekedFields]);
+
+  // The list's controls (sorts, facets, ranges, favorites, shuffle) own a
+  // state the filters and order derive from; a list without them keeps the
+  // plain search band below and its own view memory.
+  const hasCards = Boolean(renderCard || look?.images);
+  const listControls: FrappeListControls = {
+    sorts,
+    facets,
+    ranges,
+    views: hasCards ? ["grid", "list", "table"] : ["list", "table"],
+    defaultView: defaultViewMode,
+  };
+  const hasControls = Boolean(
+    sorts?.length || facets?.length || ranges?.length || favorites || shuffle,
+  );
+  const favoritesStorageKey = favorites
+    ? typeof favorites === "string"
+      ? favorites
+      : favoritesKey(doctype)
+    : undefined;
+  const list = useListControls({
+    doctype,
+    controls: listControls,
+    connections: effectiveConnections,
+    connection: connectionConfig,
+    limit,
+    favoritesKey: favoritesStorageKey,
+    router: urlState ? router : undefined,
+    readBase: Boolean(subtitle || facets?.length || ranges?.length),
+  });
+  const updateList = list.update;
+
+  const requestedViewMode =
+    controlledViewMode ?? (urlState ? list.state.view : undefined) ?? storedViewMode;
+  const viewMode: ListViewMode =
+    requestedViewMode === "grid" && !hasCards ? "list" : requestedViewMode;
+
+  const setViewMode = useCallback(
+    (mode: ListViewMode) => {
+      onViewModeChange?.(mode);
+      if (controlledViewMode !== undefined) return;
+      if (urlState) {
+        updateList({ view: mode });
+        return;
+      }
+      setViewModeState(mode);
+      void setStoredViewMode(doctype, mode);
+    },
+    [doctype, controlledViewMode, onViewModeChange, urlState, updateList],
+  );
+
+  const controlsKey = JSON.stringify({
+    facets: facets?.map((facet) => [facet.param, facet.field, facet.doctype]),
+    ranges: ranges?.map((range) => [range.param, range.field]),
+    sorts: sorts?.map((sort) => [sort.value, sort.orderBy]),
+  });
+  const controlFilters = useMemo(() => {
+    if (!hasControls) return activeFilters;
+    const base = !activeFilters
+      ? []
+      : Array.isArray(activeFilters)
+        ? activeFilters
+        : Object.entries(activeFilters).map(([field, value]) => [field, "=", value]);
+    return listStateFilters(list.state, listControls, {
+      base: base as FrappeListFilter[],
+      search: searchFilter ?? ((query) => [[searchField, "like", `%${query}%`]]),
+      favorites: list.favorites.favoriteSet,
+    });
+    // controlsKey stands for the facet and range definitions listControls carries.
+  }, [
+    hasControls,
+    activeFilters,
+    list.state,
+    list.favorites.favoriteSet,
+    searchFilter,
+    searchField,
+    controlsKey,
+  ]);
+  const effectiveOrderBy = hasControls
+    ? (listStateOrderBy(list.state, listControls, orderBy) as typeof orderBy)
+    : orderBy;
+  // The server page is the unfiltered list in its default order; any other
+  // query waits for its own read rather than flash rows it would drop.
+  const loaded = useRouteLoaderData(loader) as { rows?: readonly Partial<TDoc>[] } | undefined;
+  const initialRows = initialRowsProp ?? loaded?.rows;
+  const seedRows =
+    !hasControls ||
+    (!isListNarrowed(list.state) && (!sorts?.length || list.state.sort === sorts[0].value))
+      ? initialRows
+      : undefined;
+
   const linkFilters = useConnectionFilters(
     connectionConfig,
     doctype,
-    activeFilters as Parameters<typeof useConnectionFilters>[2],
+    controlFilters as Parameters<typeof useConnectionFilters>[2],
     effectiveConnections,
   );
   const resolvedFilters = linkFilters.filters as typeof activeFilters;
@@ -487,13 +684,6 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
   const [searchText, setSearchText] = useState("");
   const [debouncedSearch, setDebouncedSearch] = useState("");
 
-  const searchField = useMemo(() => {
-    if (meta?.title_field) return meta.title_field;
-    if (metaListFields.length > 0) return metaListFields[0].fieldname;
-    if (peekedFields && peekedFields.length > 0) return peekedFields[0];
-    return "name";
-  }, [meta, metaListFields, peekedFields]);
-
   const listFilters = useMemo(() => {
     const query = debouncedSearch.trim();
     if (!query) return resolvedFilters;
@@ -551,6 +741,343 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
     [savedFiltersHook],
   );
 
+  const slug = doctype.toLowerCase().replace(/\s+/g, "-");
+  const searchId = `${slug}-list-search`;
+  const resultsId = `${slug}-results`;
+  const nameField = titleField ?? meta?.title_field;
+
+  const [shuffleOpen, setShuffleOpen] = useState(false);
+  const [shuffleRows, setShuffleRows] = useState<Partial<TDoc>[]>([]);
+  const handleShuffleRows = useCallback(
+    (snapshot: FrappeRowsSnapshot<TDoc>) => setShuffleRows(snapshot.rows),
+    [],
+  );
+  const shuffleOrderKey = JSON.stringify(sorts?.[0]?.orderBy ?? orderBy ?? null);
+  const shuffleFiltersKey = JSON.stringify(resolvedFilters ?? null);
+  const shuffleFieldsKey = JSON.stringify(effectiveFields);
+  const shuffleOptions = useMemo(
+    () => ({
+      fields: JSON.parse(shuffleFieldsKey),
+      filters: JSON.parse(shuffleFiltersKey) ?? undefined,
+      orderBy: JSON.parse(shuffleOrderKey) ?? undefined,
+      limit: limit ?? 0,
+    }),
+    [shuffleFieldsKey, shuffleFiltersKey, shuffleOrderKey, limit],
+  );
+
+  const { isFavorite, toggle: toggleStar } = list.favorites;
+  const toggleFavorite = useCallback(
+    (doc: Partial<TDoc>) => {
+      const name = doc.name;
+      if (!name) return;
+      const starred = isFavorite(name);
+      toggleStar(name);
+      const titleValue = nameField ? (doc as Record<string, unknown>)[nameField] : undefined;
+      const label = typeof titleValue === "string" && titleValue ? titleValue : name;
+      showToast(
+        starred
+          ? {
+              id: `${slug}-favorite-${name}`,
+              title: t("{{name}} removed from favorites", { name: label }),
+              intent: "accent",
+              action: { label: t("Undo"), onPress: () => toggleStar(name) },
+            }
+          : {
+              id: `${slug}-favorite-${name}`,
+              title: t("{{name}} added to favorites", { name: label }),
+              intent: "success",
+            },
+      );
+    },
+    [isFavorite, toggleStar, nameField, slug, t],
+  );
+
+  const cardFor = (doc: Partial<TDoc>): FrappeListCard => {
+    const name = doc.name ?? "";
+    const row = doc as Record<string, unknown>;
+    return {
+      href:
+        route !== undefined && name ? frappeRouteHref(route, { mode: "view", name }) : undefined,
+      open: () => onItemClick?.(doc),
+      facets: Object.fromEntries(
+        (facets ?? []).map((facet) => [
+          facet.param,
+          facet.doctype
+            ? (list.facets[facet.param]?.values.get(name) ?? [])
+            : row[facet.field] === undefined || row[facet.field] === null
+              ? []
+              : [String(row[facet.field])],
+        ]),
+      ),
+      favorite:
+        favoritesStorageKey && name
+          ? { active: isFavorite(name), toggle: () => toggleFavorite(doc) }
+          : undefined,
+    };
+  };
+  const tintFacet = facets?.find((facet) => facet.tint);
+  const drawRecordCard = (doc: Partial<TDoc>, index: number) => {
+    const card = cardFor(doc);
+    const name = doc.name ?? "";
+    const values = tintFacet ? (card.facets[tintFacet.param] ?? []) : [];
+    const title = recordTitle(doc, look, nameField);
+    return (
+      <RecordCard
+        title={title}
+        subtitle={look?.subtitle?.(doc)}
+        code={look?.code?.(doc)}
+        images={look?.images?.(doc, finalBaseURL) ?? []}
+        tints={values.slice(0, 2).map((value) => tintFacet?.tint?.(value))}
+        badges={values.map((value) => ({
+          value,
+          label: tintFacet?.optionLabel?.(value) ?? value,
+          tint: tintFacet?.tint?.(value),
+        }))}
+        href={card.href}
+        onPress={card.open}
+        favorite={card.favorite}
+        lazy={index >= eagerCards}
+        testID={`${slug}-card-${name}`}
+        favoriteTestID={`${slug}-favorite-${name}`}
+      />
+    );
+  };
+  const drawCard = renderCard
+    ? (doc: Partial<TDoc>, index: number) => renderCard(doc, index, cardFor(doc))
+    : look?.images
+      ? drawRecordCard
+      : undefined;
+
+  // "/" jumps to the search box on web, the common list-page affordance.
+  // Document scope adds no tab stop (LC-49); it stands down while the reader
+  // types in any editable control or works inside an open overlay.
+  useEffect(() => {
+    if (!isWeb || typeof document === "undefined" || !showSearch) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey) return;
+      if (event.defaultPrevented) return;
+      const target = event.target as HTMLElement | null;
+      if (target) {
+        const tag = target.tagName;
+        if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+        if (target.isContentEditable) return;
+        if (target.closest?.('[role="dialog"], [role="menu"], [role="listbox"]')) return;
+      }
+      const input = document.getElementById(searchId)?.querySelector("input");
+      if (!input) return;
+      event.preventDefault();
+      input.focus();
+      input.select?.();
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [searchId, showSearch]);
+
+  const headerOwnsTools = route !== undefined && !showToolbar;
+  const pressFor = (action: FrappeListAction) =>
+    action.onPress ?? (action.href && navigate ? () => navigate(action.href as string) : undefined);
+  const headerActions =
+    headerOwnsTools || headerAccessory || actions?.length ? (
+      <XStack {...knobProps.gap} alignItems="center" flexWrap="wrap" flexShrink={1} minWidth={0}>
+        {headerOwnsTools ? (
+          <Tooltip content={t("Switch views")}>
+            <XStack>
+              <ViewSwitcher
+                views={[
+                  ...(hasCards ? [{ type: "grid", label: t("Cards"), icon: ImageIcon }] : []),
+                  { type: "list", label: t("List"), icon: ListIcon },
+                  { type: "table", label: t("Table"), icon: TableIcon },
+                ]}
+                currentView={viewMode}
+                onViewChange={(v) => setViewMode(v as ListViewMode)}
+              />
+            </XStack>
+          </Tooltip>
+        ) : null}
+        {headerAccessory}
+        {actions?.map((action) => {
+          const Icon = action.icon;
+          const onPress = pressFor(action);
+          return (
+            <React.Fragment key={action.label}>
+              <Tooltip content={action.hint ?? action.label}>
+                <Button
+                  outlined
+                  onPress={onPress}
+                  icon={Icon ? <Icon size={16} /> : undefined}
+                  $max-sm={{ display: "none" }}
+                  testID={action.testID}
+                >
+                  {action.label}
+                </Button>
+              </Tooltip>
+              <Button
+                outlined
+                circular
+                onPress={onPress}
+                icon={Icon ? <Icon size={16} /> : undefined}
+                display="none"
+                aria-label={action.label}
+                $max-sm={{ display: "flex" }}
+              />
+            </React.Fragment>
+          );
+        })}
+        {headerOwnsTools && onAdd ? (
+          <>
+            <Button
+              theme="accent"
+              onPress={onAdd}
+              icon={<PlusIcon size={16} />}
+              $max-sm={{ display: "none" }}
+            >
+              {t("Add {{doctype}}", { doctype })}
+            </Button>
+            <Button
+              theme="accent"
+              onPress={onAdd}
+              icon={<PlusIcon size={16} />}
+              display="none"
+              $max-sm={{ display: "flex" }}
+            >
+              {t("Add")}
+            </Button>
+          </>
+        ) : null}
+      </XStack>
+    ) : undefined;
+
+  const controlsBand = hasControls ? (
+    <ListControls
+      controls={listControls}
+      list={list}
+      searchId={searchId}
+      searchPlaceholder={searchPlaceholder}
+      showSearch={showSearch}
+      showFavorites={Boolean(favoritesStorageKey)}
+      shuffle={
+        shuffle
+          ? {
+              open: shuffleOpen,
+              toggle: () => setShuffleOpen((open) => !open),
+              panelId: `${slug}-shuffle-panel`,
+            }
+          : undefined
+      }
+      shufflePanel={
+        shuffle && shuffleOpen && shuffleRows.length > 0 && drawCard ? (
+          <ShufflePanel<Partial<TDoc>>
+            id={`${slug}-shuffle-panel`}
+            label={t("Surprise me")}
+            rows={shuffleRows}
+            itemLabel={shuffle.label}
+            renderPick={(doc) => drawCard(doc, 0)}
+            onGo={(doc) => {
+              setShuffleOpen(false);
+              onItemClick?.(doc);
+            }}
+            testID={`${slug}-shuffle-panel`}
+          />
+        ) : null
+      }
+      separator={!surface}
+      testID={slug}
+    />
+  ) : null;
+
+  const asPage = (view: React.ReactElement) => {
+    const extras = (
+      <>
+        {list.readers}
+        {shuffle && shuffleOpen && !linkFilters.pending ? (
+          <FrappeRowsReader<TDoc>
+            connection={connectionConfig}
+            doctype={doctype}
+            options={shuffleOptions as never}
+            onChange={handleShuffleRows}
+          />
+        ) : null}
+        {favoritesStorageKey ? <ListToastHost /> : null}
+      </>
+    );
+    if (route === undefined) {
+      return controlsBand ? (
+        <YStack {...knobProps.gap} flex={viewMode === "grid" ? undefined : 1}>
+          {controlsBand}
+          {view}
+          {extras}
+        </YStack>
+      ) : (
+        <>
+          {view}
+          {extras}
+        </>
+      );
+    }
+    return (
+      <ListPageLayout
+        scroll={!surface}
+        header={
+          <>
+            {controlsBand ? <SkipLink targetId={resultsId}>{t("Skip to results")}</SkipLink> : null}
+            <PageHeader
+              title={title ?? doctype}
+              subtitle={subtitle && list.total !== undefined ? subtitle(list.total) : undefined}
+              actions={headerActions}
+              divider={!surface}
+            />
+          </>
+        }
+        toolbar={controlsBand ?? undefined}
+      >
+        {view}
+        {extras}
+      </ListPageLayout>
+    );
+  };
+
+  const controlsEmptyState = hasControls ? (
+    <EmptyState
+      aria-live="polite"
+      icon={
+        list.state.favoritesOnly ? (
+          <HeartIcon size={28} />
+        ) : isListNarrowed(list.state) ? (
+          <MagnifyingGlassIcon size={28} />
+        ) : (
+          <SparkleIcon size={28} />
+        )
+      }
+      title={
+        list.state.favoritesOnly
+          ? t("No favorites yet")
+          : list.state.search.trim()
+            ? t('No match for "{{query}}"', { query: list.state.search.trim() })
+            : isListNarrowed(list.state)
+              ? t("No {{doctype}} match the active filters", { doctype })
+              : t("No {{doctype}} yet", { doctype })
+      }
+      description={
+        list.state.favoritesOnly
+          ? t("Tap the heart on a record to favorite it.")
+          : isListNarrowed(list.state)
+            ? t("Try a different search or filter.")
+            : undefined
+      }
+      action={
+        isListNarrowed(list.state) ? (
+          <Button outlined onPress={list.clear}>
+            {t("Clear filters")}
+          </Button>
+        ) : onAdd ? (
+          <Button theme="accent" onPress={onAdd}>
+            {t("Add your first {{doctype}}", { doctype })}
+          </Button>
+        ) : undefined
+      }
+    />
+  ) : undefined;
+
   // Named fields need no schema to read or draw: the view renders now (on
   // the server too) and labels settle when meta lands.
   if (isMetaLoading && !fields) {
@@ -559,10 +1086,11 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
         {...knobProps.panelPadding}
         alignItems="center"
         justifyContent="center"
+        gap="$2"
         {...stackProps}
       >
         <Spinner size="large" />
-        <Text {...knobProps.body} color={knobProps.textAccentColor} marginTop="$2">
+        <Text {...knobProps.body} color={knobProps.textAccentColor}>
           {t("Loading {{doctype}} schema...", { doctype })}
         </Text>
       </YStack>,
@@ -586,7 +1114,7 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
         <XStack alignItems="center" {...knobProps.gap}>
           <ViewSwitcher
             views={[
-              ...(renderCard ? [{ type: "grid", label: t("Cards") }] : []),
+              ...(hasCards ? [{ type: "grid", label: t("Cards") }] : []),
               { type: "list", label: t("List") },
               { type: "table", label: t("Table") },
             ]}
@@ -691,7 +1219,7 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
       borderBottomWidth={1}
       borderBottomColor="$borderColor"
     >
-      <View flex={1}>
+      <View flex={1} id={searchId}>
         <SearchInput
           value={searchText}
           onChange={setSearchText}
@@ -711,19 +1239,19 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
       const isGrid = viewMode === "grid";
       return (
         <YStack flex={isGrid ? undefined : 1}>
-          {showSearch ? renderListSearch() : null}
+          {showSearch && !hasControls ? renderListSearch() : null}
           <FrappeList
             key={`${viewMode}-${refreshKey}`}
             layout={isGrid ? "grid" : "list"}
             gridProps={gridProps}
-            emptyState={emptyState}
+            emptyState={emptyState ?? controlsEmptyState}
             pageSize={pageSize}
             onRetry={onRetry ?? handleRefresh}
             doctype={doctype}
             fields={effectiveFields as readonly ("name" | "doctype")[]}
             filters={listFilters as Partial<{ name: string; doctype: string }>}
             renderItem={
-              (isGrid && renderCard ? renderCard : renderListItem) as unknown as (
+              (isGrid && drawCard ? drawCard : renderListItem) as unknown as (
                 item: Partial<{ name: string; doctype: string }>,
                 index: number,
               ) => React.ReactNode
@@ -736,10 +1264,12 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
             baseURL={finalBaseURL}
             auth={finalAuth}
             syncOptions={finalSyncOptions}
-            orderBy={orderBy as FrappeListProps<{ name: string; doctype: string }>["orderBy"]}
+            orderBy={
+              effectiveOrderBy as FrappeListProps<{ name: string; doctype: string }>["orderBy"]
+            }
             limit={limit}
             initialRows={
-              initialRows as FrappeListProps<{ name: string; doctype: string }>["initialRows"]
+              seedRows as FrappeListProps<{ name: string; doctype: string }>["initialRows"]
             }
             // Only override when narrowing is active: FrappeList's own
             // "No {doctype} records found" stays the true-empty message.
@@ -792,6 +1322,7 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
       {...(surface ? knobProps.containerRadius : {})}
       overflow={surface ? "hidden" : undefined}
       testID={`${doctype.toLowerCase()}-list`}
+      {...(hasControls ? { id: resultsId } : {})}
       {...stackProps}
     >
       {renderToolbar()}