@multiplatform.one/frappe-ui 7.34.3 → 7.35.0

package/src/FrappeListView.sidebar.spec.tsx

@@ -0,0 +1,225 @@
+// A routed list whose filters live in the page's one sidebar: type facets
+// with counts, a generation band, a base-XP stock slider and favorites
+// beside the results from md up; below md a Filters button wearing the
+// active-filter count opens the same filters (sort included) in a bottom
+// sheet, and the header's secondary actions move to a ⋯ menu.
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, fireEvent, screen, waitFor, within } from "@testing-library/react";
+import i18next from "i18next";
+import { Order } from "@multiplatform.one/frappe";
+import { ChartBarIcon } from "@phosphor-icons/react";
+import { initReactI18next } from "react-i18next";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  createRosterFixtures,
+  rosterPokemonFields,
+  rosterPokemonMeta,
+  type RosterPokemon,
+} from "../tests/fixtures/pokemonRoster";
+import type { FrappeNavigation } from "./frappeNavigation";
+import { FrappeListView } from "./FrappeListView";
+import { FrappeProvider } from "./FrappeProvider";
+import { favoritesStore } from "./list/favorites";
+
+const host = "https://listview-sidebar.spec.test";
+const realFetch = globalThis.fetch;
+const favoritesKey = "sidebar-spec-favorites";
+
+beforeAll(async () => {
+  await i18next.use(initReactI18next).init({
+    lng: "en",
+    interpolation: { escapeValue: false },
+    resources: { en: { translation: {} } },
+  });
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (url.startsWith(host)) {
+      const body = /\/api\/resource\/DocType\//.test(url)
+        ? { data: rosterPokemonMeta }
+        : { data: [] };
+      return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    return realFetch(input as RequestInfo, init);
+  }) as typeof fetch;
+});
+
+afterAll(() => {
+  globalThis.fetch = realFetch;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  favoritesStore(favoritesKey).setState(() => ({ names: [] }));
+});
+
+function renderList(navigate = vi.fn()) {
+  const navigation: FrappeNavigation = {
+    usePathname: () => "/pokemon",
+    useNavigate: () => navigate,
+  };
+  return renderWithProviders(
+    <FrappeProvider baseURL={host} fixtures={createRosterFixtures()} navigation={navigation}>
+      <FrappeListView<RosterPokemon>
+        doctype="Pokemon"
+        route="/pokemon"
+        title="Pokemon"
+        subtitle={(count) => `${count} Pokémon`}
+        fields={rosterPokemonFields}
+        defaultViewMode="grid"
+        showToolbar={false}
+        surface={false}
+        filterPlacement="sidebar"
+        look={{
+          title: (doc) => doc.pokemon_name ?? "",
+          code: (doc) => `#${String(doc.poke_id ?? 0).padStart(3, "0")}`,
+          images: (doc) => [`https://art.spec.test/${doc.poke_id}.png`],
+        }}
+        favorites={favoritesKey}
+        sorts={[
+          { value: "pokedex", label: "Pokédex", orderBy: [{ field: "poke_id", order: Order.Asc }] },
+          {
+            value: "name",
+            label: "Name",
+            orderBy: [{ field: "pokemon_name", order: Order.Asc }],
+          },
+        ]}
+        facets={[
+          {
+            param: "type",
+            doctype: "Pokemon Poke Type",
+            field: "poke_type",
+            orderBy: "slot",
+            label: "Type",
+            options: ["grass", "poison", "fire", "water", "electric", "ghost", "normal"],
+            tint: (value) => (value === "grass" ? "grass" : "purple"),
+          },
+        ]}
+        bands={[
+          {
+            param: "gen",
+            field: "poke_id",
+            label: "Generation",
+            options: [
+              { value: "1", label: "Generation I", min: 1, max: 151 },
+              { value: "2", label: "Generation II", min: 152, max: 251 },
+            ],
+          },
+        ]}
+        ranges={[{ param: "xp", field: "base_experience", label: "Base XP" }]}
+        actions={[{ label: "Insights", icon: ChartBarIcon, href: "/pokemon/insights" }]}
+      />
+    </FrappeProvider>,
+  );
+}
+
+async function sidebar() {
+  return screen.findByTestId("list-page-sidebar", {}, { timeout: 5000 });
+}
+
+describe("FrappeListView sidebar filters", () => {
+  it("puts every filter in the page's one sidebar", async () => {
+    renderList();
+    const aside = await sidebar();
+    expect(screen.getAllByTestId("list-page-sidebar")).toHaveLength(1);
+    expect(within(aside).getByRole("radiogroup", { name: "Type" })).toBeTruthy();
+    expect(within(aside).getByRole("radiogroup", { name: "Generation" })).toBeTruthy();
+    expect(aside.querySelector("[data-range-slider]")).not.toBeNull();
+    expect(within(aside).getByTestId("pokemon-sidebar-favorites-filter")).toBeTruthy();
+  });
+
+  it("labels each type and generation with its record count", async () => {
+    renderList();
+    const aside = await sidebar();
+    await waitFor(() => {
+      const poison = within(aside).getByTestId("pokemon-sidebar-type-poison");
+      expect(poison.querySelector("[data-facet-count]")?.textContent).toBe("2");
+    });
+    await waitFor(() => {
+      const gen1 = within(aside).getByTestId("pokemon-sidebar-gen-1");
+      expect(gen1.querySelector("[data-facet-count]")?.textContent).toBe("6");
+      const gen2 = within(aside).getByTestId("pokemon-sidebar-gen-2");
+      expect(gen2.querySelector("[data-facet-count]")?.textContent).toBe("0");
+    });
+  });
+
+  it("keeps the header's title and count beside the sidebar, not in it", async () => {
+    renderList();
+    const aside = await sidebar();
+    const main = screen.getByTestId("list-page-main");
+    await waitFor(() => expect(main.textContent).toContain("6 Pokémon"));
+    expect(aside.textContent).not.toContain("6 Pokémon");
+  });
+
+  it("narrows to a generation band", async () => {
+    renderList();
+    const aside = await sidebar();
+    await screen.findByTestId("pokemon-card-bulbasaur", {}, { timeout: 5000 });
+    fireEvent.click(within(aside).getByTestId("pokemon-sidebar-gen-2"));
+    await waitFor(() => expect(screen.queryByTestId("pokemon-card-bulbasaur")).toBeNull());
+  });
+});
+
+describe("FrappeListView phone filters", () => {
+  it("offers a Filters button wearing the active-filter count", async () => {
+    renderList();
+    const aside = await sidebar();
+    await screen.findByTestId("pokemon-card-bulbasaur", {}, { timeout: 5000 });
+    const button = screen.getByTestId("pokemon-filters-button");
+    expect(button.getAttribute("aria-label")).toBe("Filters");
+    fireEvent.click(within(aside).getByTestId("pokemon-sidebar-type-fire"));
+    await waitFor(() =>
+      expect(screen.getByTestId("pokemon-filters-button").getAttribute("aria-label")).toBe(
+        "Filters (1)",
+      ),
+    );
+    fireEvent.click(within(aside).getByTestId("pokemon-sidebar-gen-1"));
+    await waitFor(() =>
+      expect(screen.getByTestId("pokemon-filters-button").getAttribute("aria-label")).toBe(
+        "Filters (2)",
+      ),
+    );
+  });
+
+  it("opens the same filters, sort included, in a bottom sheet", async () => {
+    renderList();
+    await sidebar();
+    expect(screen.queryByTestId("pokemon-filters-sheet")).toBeNull();
+    fireEvent.click(screen.getByTestId("pokemon-filters-button"));
+    const sheet = await screen.findByTestId("pokemon-filters-sheet");
+    expect(within(sheet).getByRole("radiogroup", { name: "Type" })).toBeTruthy();
+    expect(within(sheet).getByRole("radiogroup", { name: "Generation" })).toBeTruthy();
+    expect(sheet.querySelector("[data-range-slider]")).not.toBeNull();
+    expect(within(sheet).getByTestId("pokemon-sheet-favorites-filter")).toBeTruthy();
+    expect(within(sheet).getByRole("group", { name: "Sort by" })).toBeTruthy();
+  });
+
+  it("a pick in the sheet narrows the list and counts on the button", async () => {
+    renderList();
+    await screen.findByTestId("pokemon-card-pikachu", {}, { timeout: 5000 });
+    fireEvent.click(screen.getByTestId("pokemon-filters-button"));
+    const sheet = await screen.findByTestId("pokemon-filters-sheet");
+    fireEvent.click(within(sheet).getByTestId("pokemon-sheet-type-fire"));
+    await waitFor(() => expect(screen.queryByTestId("pokemon-card-pikachu")).toBeNull());
+    expect(screen.getByTestId("pokemon-card-charmander")).toBeTruthy();
+    expect(screen.getByTestId("pokemon-filters-button").getAttribute("aria-label")).toBe(
+      "Filters (1)",
+    );
+  });
+
+  it("holds the secondary actions in a ⋯ menu beside the Filters button", async () => {
+    renderList();
+    await sidebar();
+    const tools = screen.getByTestId("pokemon-phone-tools");
+    const more = within(tools).getByTestId("pokemon-more");
+    expect(more.getAttribute("aria-label")).toBe("More actions");
+    fireEvent.click(more);
+    const menu = await screen.findByRole("menu");
+    expect(within(menu).getByText("Insights")).toBeTruthy();
+    expect(within(menu).getByText("Cards")).toBeTruthy();
+    expect(within(menu).getByText("Table")).toBeTruthy();
+  });
+});

package/src/FrappeListView.spec.tsx

@@ -1,9 +1,11 @@
+import { getSize } from "@tamagui/get-token";
+import { getVariableValue, type SizeTokens } from "tamagui";
 // FrappeListView toolbar refresh — LC-54 PRESS-FLOOR-CHANNEL (amendment
 // 2026-08-13, "the grown box NEVER PAINTS"): the refresh affordance used to
 // be a raw tamagui Button riding a grown transparent press target (negative
 // outsets escaping the toolbar slot) whose default hover fill painted the
 // whole escaped 44px floor. The fix migrates it to the house forms Button
-// with `circular` — the painted box ITSELF is the 44×44 control, so feedback
+// with `circular` — the painted box itself follows the control token, so feedback
 // stays inside its own reserved layout slot (box-is-control mechanism).
 // Same atom-based assertions as FrappeDashboard.spec.tsx (jsdom can't apply
 // :hover; the positive control proving the detectors work lives there).
@@ -121,16 +123,17 @@ const refreshIn = async (container: HTMLElement) => {
 };
 
 describe("FrappeListView refresh press floor (LC-54 amendment)", () => {
-  it("the refresh floor is its own box — no grown-target negative outset", async () => {
+  it("desktop refresh keeps its token box and restores the press floor with slop", async () => {
     const { container } = renderListView();
     const refresh = await refreshIn(container);
     expect(refresh.getAttribute("role")).toBe("button");
-    // House circular Button: the 44px floor is REAL layout (box-is-control);
-    // the escape mechanism (negative margins pulling the grown box over the
-    // adjacent Add button) must be gone.
     expect(refresh.className).not.toMatch(negativeMarginAtom);
-    expect(refresh.className).toMatch(/_mih-44px/);
-    expect(refresh.className).toMatch(/_miw-44px/);
+    const token = refresh.getAttribute("data-size-token") as SizeTokens;
+    const px = Number(getVariableValue(getSize(token)));
+    expect(refresh.className).toContain(`_mih-${px}px`);
+    expect(refresh.className).toContain(`_miw-${px}px`);
+    const slop = Number(refresh.getAttribute("data-mp-press-slop") ?? 0);
+    expect(px + slop * 2).toBeGreaterThanOrEqual(44);
   });
 
   it("hover feedback rides the button's own in-slot box (house channel)", async () => {
@@ -169,7 +172,7 @@ describe("FrappeListView design-law (avatar + type)", () => {
       return node as HTMLElement;
     });
     expect(avatar.getAttribute("data-avatar-nested")).toBe("true");
-    expect(Number(avatar.getAttribute("data-avatar-px"))).toBe(32);
+    expect(Number(avatar.getAttribute("data-avatar-px"))).toBe(29);
     expect(Number(avatar.getAttribute("data-avatar-px"))).not.toBe(40);
   });
 

package/src/FrappeListView.tsx

@@ -2,6 +2,7 @@ import { useDocTypeMeta } from "@multiplatform.one/frappe";
 import type { DataTableColumn } from "@multiplatform.one/table";
 import {
   ArrowsClockwiseIcon,
+  DiceFiveIcon,
   HeartIcon,
   ImageIcon,
   ListIcon,
@@ -26,9 +27,15 @@ import {
   ViewSwitcher,
   componentColors,
   showToast,
+  type DropdownMenuEntry,
   type ImageGridProps,
 } from "@multiplatform.one/components";
-import { pressTargetStyle, useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  containerCapProps,
+  pressTargetStyle,
+  useLayoutSizeClass,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import { storage } from "@multiplatform.one/store";
 import { useFrappeConfig } from "./FrappeProvider";
 import { FrappeList, type FrappeListProps } from "./FrappeList";
@@ -42,17 +49,21 @@ 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 { ListControls, type ListControlsProps } from "./list/ListControls";
+import { ListControlsSheet } from "./list/ListControlsSheet";
 import {
   isListNarrowed,
   listStateFilters,
   listStateOrderBy,
   type FrappeListControls,
+  type FrappeListBand,
   type FrappeListFacet,
   type FrappeListFilter,
   type FrappeListRange,
   type FrappeListSort,
 } from "./list/listState";
+import { ListFilterPanel } from "./list/ListFilterPanel";
+import { ListSidebarToolbar } from "./list/ListSidebarToolbar";
 import { ListToastHost } from "./list/ListToastHost";
 import { ShufflePanel } from "./list/ShufflePanel";
 import { useListControls } from "./list/useListControls";
@@ -189,6 +200,15 @@ export interface FrappeListViewProps<TDoc extends { name: string; doctype: strin
   facets?: readonly FrappeListFacet[];
   /** One minimum-value slider per numeric field. */
   ranges?: readonly FrappeListRange[];
+  /** One choice of named spans per numeric field (a Pokédex generation). */
+  bands?: readonly FrappeListBand[];
+  /**
+   * Where a routed list's filters live. `band` (default): a band above the
+   * results. `sidebar`: the page's one sidebar beside the header and
+   * results from `md` up; below it a Filters button opens the same filters
+   * in a bottom sheet and the header's secondary actions move to a ⋯ menu.
+   */
+  filterPlacement?: "band" | "sidebar";
   /**
    * Star records on this device and filter to them: true keys the stars by
    * doctype, a string names the storage key.
@@ -201,6 +221,14 @@ export interface FrappeListViewProps<TDoc extends { name: string; doctype: strin
    * refresh or a shared link reproduces the list.
    */
   urlState?: boolean;
+  /**
+   * `sheet` folds sort, favorites, facets and ranges into a Filters sheet
+   * behind a counted button, with the view switch beside the active-filter
+   * chips instead of in the page header (the phone layout). A routed list
+   * with `filterPlacement="sidebar"` already opens its filters in a phone
+   * sheet, so the sidebar wins and this layout applies only without it.
+   */
+  controlsLayout?: "band" | "sheet";
   baseURL?: string;
   auth?: { useToken?: boolean; token?: string; type?: string };
   syncOptions?: Record<string, unknown>;
@@ -307,9 +335,12 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
   searchPlaceholder,
   facets,
   ranges,
+  bands,
+  filterPlacement = "band",
   favorites,
   shuffle,
   urlState = false,
+  controlsLayout = "band",
   baseURL,
   auth,
   syncOptions,
@@ -547,11 +578,12 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
     sorts,
     facets,
     ranges,
+    bands,
     views: hasCards ? ["grid", "list", "table"] : ["list", "table"],
     defaultView: defaultViewMode,
   };
   const hasControls = Boolean(
-    sorts?.length || facets?.length || ranges?.length || favorites || shuffle,
+    sorts?.length || facets?.length || ranges?.length || bands?.length || favorites || shuffle,
   );
   const favoritesStorageKey = favorites
     ? typeof favorites === "string"
@@ -566,7 +598,7 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
     limit,
     favoritesKey: favoritesStorageKey,
     router: urlState ? router : undefined,
-    readBase: Boolean(subtitle || facets?.length || ranges?.length),
+    readBase: Boolean(subtitle || facets?.length || ranges?.length || bands?.length),
   });
   const updateList = list.update;
 
@@ -592,6 +624,7 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
   const controlsKey = JSON.stringify({
     facets: facets?.map((facet) => [facet.param, facet.field, facet.doctype]),
     ranges: ranges?.map((range) => [range.param, range.field]),
+    bands: bands?.map((band) => [band.param, band.field, band.options]),
     sorts: sorts?.map((sort) => [sort.value, sort.orderBy]),
   });
   const controlFilters = useMemo(() => {
@@ -834,20 +867,70 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
   }, [searchId, showSearch]);
 
   const headerOwnsTools = route !== undefined && !showToolbar;
+  // responsive-parity: below md these actions move to ListSidebarToolbar's ⋯ menu.
+  const sidebarFilters = filterPlacement === "sidebar" && route !== undefined && hasControls;
+  const secondaryHidden = sidebarFilters ? { "$max-md": { display: "none" as const } } : {};
+  // The sidebar's phone sheet already folds the filters away, so the Filters
+  // sheet layout applies only to a list without one (one sheet per page).
+  const sheetControls = hasControls && controlsLayout === "sheet" && !sidebarFilters;
+  // On the house compact class the view switcher leaves the page header for
+  // the list's one control row, icon-only (§ ListControls rows).
+  const compact = useLayoutSizeClass() === "compact";
+  const switcherOnControls =
+    headerOwnsTools && compact && hasControls && !sidebarFilters && !sheetControls;
+  // The Filters sheet layout draws the view switch beside its chips instead.
+  const headerOwnsViews = headerOwnsTools && !switcherOnControls && !sheetControls;
   const pressFor = (action: FrappeListAction) =>
     action.onPress ?? (action.href && navigate ? () => navigate(action.href as string) : undefined);
+  const viewChoices: Array<{ type: ListViewMode; label: string; icon: typeof ImageIcon }> = [
+    ...(hasCards ? [{ type: "grid" as const, label: t("Cards"), icon: ImageIcon }] : []),
+    { type: "list", label: t("List"), icon: ListIcon },
+    { type: "table", label: t("Table"), icon: TableIcon },
+  ];
+  const menuItems: DropdownMenuEntry[] = sidebarFilters
+    ? [
+        ...(actions ?? []).map((action) => {
+          const Icon = action.icon;
+          return {
+            key: `action-${action.label}`,
+            label: action.label,
+            icon: Icon ? <Icon size={16} /> : undefined,
+            onSelect: pressFor(action),
+          };
+        }),
+        ...(shuffle
+          ? [
+              {
+                key: "shuffle",
+                label: t("Surprise me"),
+                icon: <DiceFiveIcon size={16} />,
+                onSelect: () => setShuffleOpen((open) => !open),
+              },
+            ]
+          : []),
+        ...(headerOwnsTools
+          ? [
+              ...((actions?.length ?? 0) > 0 || shuffle ? [{ separator: true as const }] : []),
+              ...viewChoices.map((view) => ({
+                key: `view-${view.type}`,
+                label: view.label,
+                icon: <view.icon size={16} />,
+                checked: viewMode === view.type,
+                closeOnSelect: true,
+                onSelect: () => setViewMode(view.type),
+              })),
+            ]
+          : []),
+      ]
+    : [];
   const headerActions =
-    headerOwnsTools || headerAccessory || actions?.length ? (
+    headerOwnsViews || (headerOwnsTools && onAdd) || headerAccessory || actions?.length ? (
       <XStack {...knobProps.gap} alignItems="center" flexWrap="wrap" flexShrink={1} minWidth={0}>
-        {headerOwnsTools ? (
+        {headerOwnsViews ? (
           <Tooltip content={t("Switch views")}>
-            <XStack>
+            <XStack {...secondaryHidden}>
               <ViewSwitcher
-                views={[
-                  ...(hasCards ? [{ type: "grid", label: t("Cards"), icon: ImageIcon }] : []),
-                  { type: "list", label: t("List"), icon: ListIcon },
-                  { type: "table", label: t("Table"), icon: TableIcon },
-                ]}
+                views={viewChoices}
                 currentView={viewMode}
                 onViewChange={(v) => setViewMode(v as ListViewMode)}
               />
@@ -858,9 +941,26 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
         {actions?.map((action) => {
           const Icon = action.icon;
           const onPress = pressFor(action);
+          if (sidebarFilters) {
+            return (
+              <XStack key={action.label} {...secondaryHidden}>
+                <Tooltip content={action.hint ?? action.label}>
+                  <Button
+                    outlined
+                    onPress={onPress}
+                    icon={Icon ? <Icon size={16} /> : undefined}
+                    testID={action.testID}
+                  >
+                    {action.label}
+                  </Button>
+                </Tooltip>
+              </XStack>
+            );
+          }
           return (
             <React.Fragment key={action.label}>
               <Tooltip content={action.hint ?? action.label}>
+                {/* responsive-parity: the circular icon twin below carries this action on phones */}
                 <Button
                   outlined
                   onPress={onPress}
@@ -885,6 +985,7 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
         })}
         {headerOwnsTools && onAdd ? (
           <>
+            {/* responsive-parity: the short "Add" twin below carries this action on phones */}
             <Button
               theme="accent"
               onPress={onAdd}
@@ -907,43 +1008,82 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
       </XStack>
     ) : undefined;
 
-  const controlsBand = hasControls ? (
-    <ListControls
+  const 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;
+  const shuffleToggle = shuffle
+    ? {
+        open: shuffleOpen,
+        toggle: () => setShuffleOpen((open) => !open),
+        panelId: `${slug}-shuffle-panel`,
+      }
+    : undefined;
+  const controlsProps: ListControlsProps = {
+    controls: listControls,
+    list,
+    searchId,
+    searchPlaceholder,
+    showSearch,
+    showFavorites: Boolean(favoritesStorageKey),
+    shuffle: shuffleToggle,
+    shufflePanel,
+    separator: !surface,
+    testID: slug,
+  };
+  const filterSidebar = sidebarFilters ? (
+    <ListFilterPanel
+      controls={listControls}
+      list={list}
+      showFavorites={Boolean(favoritesStorageKey)}
+      testID={`${slug}-sidebar`}
+    />
+  ) : undefined;
+  const controlsBand = sidebarFilters ? (
+    <ListSidebarToolbar
       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`}
+      shuffle={shuffleToggle}
+      shufflePanel={shufflePanel}
+      menuItems={menuItems}
+      testID={slug}
+    />
+  ) : !hasControls ? null : sheetControls ? (
+    <ListControlsSheet
+      {...controlsProps}
+      view={{ current: viewMode, onChange: setViewMode }}
+      noun={title ?? doctype}
+    />
+  ) : (
+    <ListControls
+      {...controlsProps}
+      compactAccessory={
+        switcherOnControls ? (
+          <ViewSwitcher
+            views={viewChoices.map((view) => ({ ...view, iconOnly: true }))}
+            currentView={viewMode}
+            onViewChange={(v) => setViewMode(v as ListViewMode)}
+            testID={`${slug}-view-switcher`}
           />
-        ) : null
+        ) : undefined
       }
-      separator={!surface}
-      testID={slug}
     />
-  ) : null;
+  );
 
   const asPage = (view: React.ReactElement) => {
     const extras = (
@@ -974,9 +1114,13 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
         </>
       );
     }
+    // The page owns the scroll in both chromes: once the last page lands the
+    // list hugs every row, so a non-scrolling page would strand the rows below
+    // the fold (§ List scroll owner).
     return (
       <ListPageLayout
-        scroll={!surface}
+        sidebar={filterSidebar}
+        sidebarLabel={t("Filters")}
         header={
           <>
             {controlsBand ? <SkipLink targetId={resultsId}>{t("Skip to results")}</SkipLink> : null}
@@ -1040,7 +1184,7 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
 
   // 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) {
+  if (!fields && (isMetaLoading || recordShape.status === "pending")) {
     return asPage(
       <YStack
         {...knobProps.panelPadding}
@@ -1187,7 +1331,6 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
           debounceMs={300}
           placeholder={t("Search...")}
           aria-label={t("Search {{doctype}}", { doctype })}
-          compact
           size="$3"
         />
       </View>
@@ -1280,7 +1423,10 @@ function FrappeListViewBody<TDoc extends { name: string; doctype: string }>({
       flex={viewMode === "grid" ? undefined : 1}
       {...(surface ? knobProps.surface : {})}
       {...(surface ? knobProps.containerRadius : {})}
-      overflow={surface ? "hidden" : undefined}
+      // No overflow clip on the card: it would cut the rows the page scroll
+      // must reach. The radius is the container cap — rows round only at the
+      // group's outer corners, capped at the row padding (DG-RAD-04).
+      {...(surface ? containerCapProps("PageSection", knobProps.borderRadius.borderRadius) : {})}
       testID={`${doctype.toLowerCase()}-list`}
       {...(hasControls ? { id: resultsId } : {})}
       {...stackProps}

package/src/FrappeReconnectIndicator.stories.tsx

@@ -23,7 +23,7 @@ const config: FrappeReconnectIndicatorProps["config"] = {
 };
 
 export const Default = () => (
-  <YStack gap="$3" width={420}>
+  <YStack gap="$3" width={420} maxWidth="100%">
     <Text fontSize="$2" color="$color10">
       Never-connected (fixtures, SSR): paints nothing.
     </Text>
@@ -43,7 +43,7 @@ export const Reconnecting = () => (
 );
 
 export const Connected = () => (
-  <YStack gap="$3" width={420}>
+  <YStack gap="$3" width={420} maxWidth="100%">
     <Text fontSize="$2" color="$color10">
       Socket up: the chip is gone.
     </Text>