@multiplatform.one/components 7.7.4 → 7.8.0

package/src/layouts/PaneScaffold.tsx

@@ -1,6 +1,11 @@
 /**
  * PaneScaffold + canonical layouts (DG-LAY-02) — W11.
  *
+ * PaneScaffold is a TWO-pane scaffold: `primary` and `secondary`, no more.
+ * Three regions come from NESTING one scaffold inside a pane of another. The
+ * resolved size class rides a context down, so an inner scaffold reflows with
+ * the outer one instead of splitting inside a stacked column.
+ *
  * Devs declare pane roles; the scaffold picks 1 vs 2 columns from the
  * canonical layout size class (`expanded` @ 860 = two-pane budget).
  *
@@ -13,7 +18,10 @@
  * - **Supporting-pane**: secondary is meaningful only relative to primary.
  * - **Feed**: equal-weight cards in a responsive grid.
  *
- * Compact/medium show one pane; pass `activePane` to choose which.
+ * Below the two-pane budget the panes STACK (primary above secondary) and the
+ * sash goes away — a drag handle is a pointer affordance and there is nothing
+ * to drag with a thumb. Hiding a pane is the list-detail navigation idiom, not
+ * the responsive default: pass `activePane` (or `narrowLayout="swap"`) for it.
  */
 
 import {
@@ -31,7 +39,17 @@ import {
   type LayoutSizeClass,
   READING_WIDTH_CH,
 } from "@multiplatform.one/theme";
-import { Children, useCallback, useEffect, useId, useRef, useState, type ReactNode } from "react";
+import {
+  Children,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import type { XStackProps, YStackProps } from "tamagui";
 import { isWeb, XStack, YStack } from "tamagui";
 import { useDirection } from "../hooks/useDirection";
@@ -51,10 +69,17 @@ export interface PaneScaffoldProps extends Omit<XStackProps, "children"> {
   primary: ReactNode;
   secondary?: ReactNode;
   /**
-   * Which pane to show when only one column fits. Default: `primary`.
-   * List-detail on compact typically flips to `secondary` once an item is selected.
+   * Which pane to show when `narrowLayout` is `swap`. Default: `primary`.
+   * List-detail on compact typically flips to `secondary` once an item is
+   * selected. Passing this prop opts the scaffold into `swap`.
    */
   activePane?: PaneRole;
+  /**
+   * What happens below the two-pane budget. `stack` (the default) puts
+   * secondary under primary so no content is unreachable; `swap` renders
+   * `activePane` alone, which is the list-detail navigation idiom.
+   */
+  narrowLayout?: "stack" | "swap";
   /** Override the default pane budget (compact/medium → 1, expanded+ → 2). */
   maxPanes?: 1 | 2;
   /**
@@ -82,6 +107,14 @@ export interface PaneScaffoldProps extends Omit<XStackProps, "children"> {
   sizeClass?: LayoutSizeClass;
 }
 
+/**
+ * Resolved size class handed down to nested scaffolds. Without it an inner
+ * scaffold reads the WINDOW while the outer one was overridden (Storybook
+ * viewport, template test), so a stacked outer could still hold a split
+ * inner and the narrow reflow would only go one level deep.
+ */
+const PaneSizeClassContext = createContext<LayoutSizeClass | null>(null);
+
 /**
  * Adaptive one-/two-pane shell. Geometry only — surface colors stay stable
  * across breakpoints (Material M-L5).
@@ -89,7 +122,8 @@ export interface PaneScaffoldProps extends Omit<XStackProps, "children"> {
 export function PaneScaffold({
   primary,
   secondary,
-  activePane = "primary",
+  activePane: activePaneProp,
+  narrowLayout: narrowLayoutProp,
   maxPanes: maxPanesProp,
   paneFlex = [1, 1],
   paneGap,
@@ -102,23 +136,73 @@ export function PaneScaffold({
   ...rest
 }: PaneScaffoldProps) {
   const liveClass = useLayoutSizeClass();
-  const sizeClass = sizeClassProp ?? liveClass;
+  const inheritedClass = useContext(PaneSizeClassContext);
+  const sizeClass = sizeClassProp ?? inheritedClass ?? liveClass;
   // Explicit `maxPanes` is the eject hatch (force 1 or 2 regardless of class).
   const budget = maxPanesProp ?? defaultMaxPanes(sizeClass);
   const hasSecondary = secondary !== null && secondary !== undefined;
-  const multi = budget >= 2 && hasSecondary;
+  const split = budget >= 2 && hasSecondary;
   const gapped = paneGap !== undefined;
   const gap = gapped ? paneGap : undefined;
-  const resizable = (resizableProp ?? !gapped) && multi && !gapped;
+  const resizable = (resizableProp ?? !gapped) && split && !gapped;
+  // `activePane` only decides anything when a pane is dropped, so passing it
+  // IS the swap opt-in. Everything else stacks: a scaffold that hides its
+  // secondary by default leaves that content unreachable on a phone.
+  const narrowLayout = narrowLayoutProp ?? (activePaneProp === undefined ? "stack" : "swap");
+  const stacked = !split && hasSecondary && narrowLayout === "stack";
+  const [primaryFlex, secondaryFlex] = paneFlex;
 
   // flexBasis auto, not the flex:1 shorthand's 0%: react-native-web resets
   // min-height to 0, so a 0% basis contributes zero intrinsic height inside
   // auto-height scroll flows (Screen scroll pages) and the scaffold collapses,
   // painting pane content over whatever follows. Bounded parents still fill
   // (grow 1) exactly as before.
-  if (!multi) {
+  let content: ReactNode;
+  if (stacked) {
+    content = (
+      <YStack
+        flexGrow={1}
+        flexShrink={1}
+        flexBasis="auto"
+        minWidth={0}
+        width="100%"
+        gap={gap ?? 0}
+        data-testid="pane-scaffold"
+        data-panes="2"
+        data-pane-layout="stack"
+        data-size-class={sizeClass}
+        data-sash="false"
+        {...rest}
+      >
+        <YStack
+          flexGrow={1}
+          flexShrink={1}
+          flexBasis="auto"
+          minWidth={0}
+          minHeight={0}
+          width="100%"
+          {...(gapped ? undefined : paneHairlineBottom)}
+          data-testid="pane-primary"
+        >
+          {primary}
+        </YStack>
+        <YStack
+          flexGrow={1}
+          flexShrink={1}
+          flexBasis="auto"
+          minWidth={0}
+          minHeight={0}
+          width="100%"
+          data-testid="pane-secondary"
+        >
+          {secondary}
+        </YStack>
+      </YStack>
+    );
+  } else if (!split) {
+    const activePane = activePaneProp ?? "primary";
     const shown = activePane === "secondary" && hasSecondary ? secondary : primary;
-    return (
+    content = (
       <YStack
         flexGrow={1}
         flexShrink={1}
@@ -127,62 +211,64 @@ export function PaneScaffold({
         width="100%"
         data-testid="pane-scaffold"
         data-panes="1"
+        data-pane-layout="single"
         data-size-class={sizeClass}
         {...rest}
       >
         {shown}
       </YStack>
     );
+  } else {
+    content = (
+      <XStack
+        flexGrow={1}
+        flexShrink={1}
+        flexBasis="auto"
+        minWidth={0}
+        minHeight={0}
+        width="100%"
+        alignItems="stretch"
+        gap={gap ?? 0}
+        position="relative"
+        data-testid="pane-scaffold"
+        data-panes="2"
+        data-pane-layout="split"
+        data-size-class={sizeClass}
+        data-sash={resizable ? "true" : "false"}
+        {...rest}
+      >
+        {resizable ? (
+          <ResizablePanes
+            primary={primary}
+            secondary={secondary}
+            primaryFlex={primaryFlex}
+            secondaryFlex={secondaryFlex}
+            minFraction={minPaneFraction}
+            maxFraction={maxPaneFraction}
+            fraction={primaryFractionProp}
+            onFractionChange={onPrimaryFractionChange}
+          />
+        ) : (
+          <>
+            <YStack
+              flex={primaryFlex}
+              minWidth={0}
+              minHeight={0}
+              {...(gapped ? undefined : paneHairlineEnd)}
+              data-testid="pane-primary"
+            >
+              {primary}
+            </YStack>
+            <YStack flex={secondaryFlex} minWidth={0} minHeight={0} data-testid="pane-secondary">
+              {secondary}
+            </YStack>
+          </>
+        )}
+      </XStack>
+    );
   }
 
-  const [primaryFlex, secondaryFlex] = paneFlex;
-
-  return (
-    <XStack
-      flexGrow={1}
-      flexShrink={1}
-      flexBasis="auto"
-      minWidth={0}
-      minHeight={0}
-      width="100%"
-      alignItems="stretch"
-      gap={gap ?? 0}
-      position="relative"
-      data-testid="pane-scaffold"
-      data-panes="2"
-      data-size-class={sizeClass}
-      data-sash={resizable ? "true" : "false"}
-      {...rest}
-    >
-      {resizable ? (
-        <ResizablePanes
-          primary={primary}
-          secondary={secondary}
-          primaryFlex={primaryFlex}
-          secondaryFlex={secondaryFlex}
-          minFraction={minPaneFraction}
-          maxFraction={maxPaneFraction}
-          fraction={primaryFractionProp}
-          onFractionChange={onPrimaryFractionChange}
-        />
-      ) : (
-        <>
-          <YStack
-            flex={primaryFlex}
-            minWidth={0}
-            minHeight={0}
-            {...(gapped ? undefined : paneHairlineEnd)}
-            data-testid="pane-primary"
-          >
-            {primary}
-          </YStack>
-          <YStack flex={secondaryFlex} minWidth={0} minHeight={0} data-testid="pane-secondary">
-            {secondary}
-          </YStack>
-        </>
-      )}
-    </XStack>
-  );
+  return <PaneSizeClassContext.Provider value={sizeClass}>{content}</PaneSizeClassContext.Provider>;
 }
 
 const paneHairlineEnd = isWeb
@@ -194,6 +280,9 @@ const paneHairlineEnd = isWeb
     }
   : { borderEndWidth: hairlineWidth, borderColor: "$borderColor" };
 
+/** Stacked seam: the horizontal twin of `paneHairlineEnd`. */
+const paneHairlineBottom = { ...hairline.bottom, borderColor: "$borderColor" };
+
 function clampFraction(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, value));
 }
@@ -458,12 +547,17 @@ export interface ListDetailLayoutProps extends Omit<
  * Canonical list-detail: explorative list + item detail. Detail remains
  * meaningful without the list (Material M-L4). List is the narrower pane
  * (Linear issue view / VS Code explorer), not a 50/50 split.
+ *
+ * Below the two-pane budget this SWAPS rather than stacks — list and detail
+ * are two steps of one navigation, so `selected` decides which is on screen.
+ * Pass `narrowLayout="stack"` to show both instead.
  */
 export function ListDetailLayout({
   list,
   detail,
   selected = false,
   activePane,
+  narrowLayout,
   ...rest
 }: ListDetailLayoutProps) {
   return (
@@ -472,6 +566,7 @@ export function ListDetailLayout({
       secondary={detail}
       paneFlex={[1, 2]}
       activePane={activePane ?? (selected ? "secondary" : "primary")}
+      narrowLayout={narrowLayout ?? "swap"}
       data-canonical="list-detail"
       {...rest}
     />
@@ -493,6 +588,9 @@ export interface SupportingPaneLayoutProps extends Omit<
  * Canonical supporting-pane: primary content + contextual support (~⅔ / ⅓).
  * Supporting content is only meaningful relative to primary (Material M-L4).
  * Seam is a hairline (Polaris Frame navigation / Linear properties column).
+ *
+ * Below the two-pane budget the supporting content stacks under the primary.
+ * It is never dropped: it has no screen of its own to be reached from.
  */
 export function SupportingPaneLayout({ children, supporting, ...rest }: SupportingPaneLayoutProps) {
   return (

package/src/layouts/ScreenToolbar.stories.tsx

@@ -26,16 +26,10 @@ export const Default: Story = {
   name: "Main",
   render: () => (
     <ScreenToolbar
-      leading={
-        <Button compact variant="outlined">
-          Back
-        </Button>
-      }
+      leading={<Button compact>Back</Button>}
       trailing={
         <>
-          <Button compact variant="outlined">
-            Cancel
-          </Button>
+          <Button compact>Cancel</Button>
           <Button compact>Save</Button>
         </>
       }
@@ -59,7 +53,6 @@ export const DisabledAndLoading: Story = {
         // the toolbar row's shared control height.
         <Button
           compact
-          variant="outlined"
           disabled
           disabledReason="No screen to go back to"
           disabledReasonPlacement="inline"
@@ -82,22 +75,12 @@ export const ManyActionsNarrow: Story = {
   render: () => (
     <YStack maxWidth={320} borderWidth={1} borderColor="$color6" borderStyle="dashed">
       <ScreenToolbar
-        leading={
-          <Button compact variant="outlined">
-            Back to the previous screen
-          </Button>
-        }
+        leading={<Button compact>Back to the previous screen</Button>}
         trailing={
           <>
-            <Button compact variant="outlined">
-              Duplicate
-            </Button>
-            <Button compact variant="outlined">
-              Archive
-            </Button>
-            <Button compact variant="outlined">
-              Delete permanently
-            </Button>
+            <Button compact>Duplicate</Button>
+            <Button compact>Archive</Button>
+            <Button compact>Delete permanently</Button>
             <Button compact>Save changes</Button>
           </>
         }

package/src/layouts/index.tsx

@@ -12,6 +12,17 @@ export * from "./page";
 export * from "./pageHeadingScope";
 export * from "./PageTemplates";
 export * from "./PaneScaffold";
+// EmptyState is NAMED here rather than left to reach the barrel through
+// `export * from "./page"` (page.tsx re-exports it, so it has always been
+// importable from @multiplatform.one/components — MPO-223's "not exported"
+// premise was wrong, measured against published 7.7.1). Naming it is still
+// worth doing: reachability that rides a transitive star through an unrelated
+// module is the fragility that dropped ProgressCard twice (MPO-53, 5c7af7134),
+// and it reads as absent to anyone grepping this file, which is how a consumer
+// talked itself into a deep `src/layouts/EmptyState` import. `layouts.spec.tsx`
+// asserts every module in this directory is reachable from here, so the next
+// omission fails a test.
+export { EmptyState, type EmptyStateProps } from "./EmptyState";
 export {
   AsyncBoundary,
   AsyncSkeleton,

package/src/layouts/layouts.spec.tsx

@@ -13,6 +13,7 @@ import * as React from "react";
 import { TamaguiProvider, createTamagui } from "tamagui";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import * as Debug from "./Debug";
+import * as EmptyStateModule from "./EmptyState";
 import * as Layouts from "./index";
 import { Sidebar, type SidebarSection } from "./sidebar";
 import { Toolbar, type ToolbarAction } from "./toolbar";
@@ -72,6 +73,56 @@ describe("Layouts Index", () => {
   it("should export Timeline", () => {
     expect(Layouts).toHaveProperty("Timeline");
   });
+
+  // MPO-223. The per-component `it`s above are a hand-kept list, and a hand-kept
+  // list is how ProgressCard fell off the catalog twice (MPO-53, then 5c7af7134):
+  // nobody adds a line for the module they forgot. This walks the directory
+  // instead, so a new module in src/layouts that nothing re-exports fails here
+  // rather than in a consumer's app.
+  //
+  // Scope is this directory's own modules: the top-level files, plus each
+  // subdirectory's index. A subdirectory's internals stay internal on purpose
+  // (SafeAreaWrapper/insets, KeyboardAvoidingWrapper/behavior), and `.native`
+  // variants are the same module on a platform this runner is not.
+  //
+  // Runtime names only — `import * as` cannot see type-only exports, so the
+  // interfaces ride the typecheck. That is enough for the failure this guards:
+  // a missing VALUE is what breaks a build.
+  it("reaches every module under src/layouts from the barrel", () => {
+    // Negations live in the GLOB, not in a filter below it: `eager: true`
+    // imports every match up front, so a `.stories.tsx` skipped afterwards has
+    // already been loaded — and loading one drags the storybook runtime into a
+    // vitest environment that has no preview API (measured: "does not provide
+    // an export named 'definePreview'", whole suite fails to collect).
+    const modules = import.meta.glob<Record<string, unknown>>(
+      [
+        "./*.tsx",
+        "./*/index.tsx",
+        "!./index.tsx",
+        "!./*.spec.tsx",
+        "!./*.stories.tsx",
+        "!./**/*.spec.tsx",
+        "!./**/*.stories.tsx",
+      ],
+      { eager: true },
+    );
+    const unreachable: string[] = [];
+    for (const [file, mod] of Object.entries(modules)) {
+      for (const name of Object.keys(mod)) {
+        if (name === "default") continue;
+        if (!(name in Layouts)) unreachable.push(`${file} -> ${name}`);
+      }
+    }
+    expect(unreachable).toEqual([]);
+  });
+
+  // The import a consumer actually writes. It passed before EmptyState was
+  // named in index.tsx too — page.tsx re-exported it — and this locks the
+  // identity, not just the presence, so a future shadow cannot quietly swap it.
+  it("exports the same EmptyState from the barrel and from its module", () => {
+    expect(Layouts).toHaveProperty("EmptyState");
+    expect(Layouts.EmptyState).toBe(EmptyStateModule.EmptyState);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/layouts/page.designLaw.spec.tsx

@@ -135,4 +135,29 @@ describe("density unpinned (LC-76)", () => {
     const frame = container.querySelector('[data-testid="page-section"]') as HTMLElement;
     expect(frame.getAttribute("data-density")).toBe("compact");
   });
+
+  it("Screen's explicit density override reaches nested page primitives", () => {
+    renderWithProviders(
+      <Preset overrides={{ density: "comfortable" }}>
+        <Screen compact scroll={false}>
+          <PageHeader title="Compact screen" />
+          <PageSection title="Inherited section" />
+        </Screen>
+      </Preset>,
+    );
+    expect(screen.getByTestId("page-header").getAttribute("data-density")).toBe("compact");
+    expect(screen.getByTestId("page-section").getAttribute("data-density")).toBe("compact");
+  });
+
+  it("a painted section steps its interior density without shrinking its heading", () => {
+    renderWithProviders(
+      <Preset overrides={{ density: "comfortable" }}>
+        <PageSection surface title="Outer" data-testid="outer-section">
+          <PageSection title="Inner" data-testid="inner-section" />
+        </PageSection>
+      </Preset>,
+    );
+    expect(screen.getByTestId("outer-section").getAttribute("data-density")).toBe("comfortable");
+    expect(screen.getByTestId("inner-section").getAttribute("data-density")).toBe("compact");
+  });
 });

package/src/layouts/page.tsx

@@ -17,6 +17,8 @@
 
 import {
   MIN_PRESS_TARGET,
+  Preset,
+  Surface,
   hairline,
   layoutBreakpoints,
   resolvePageTitleScale,
@@ -55,6 +57,17 @@ function negateSpaceToken(token: string): `$-${string}` {
   return `$-${token.startsWith("$") ? token.slice(1) : token}`;
 }
 
+function knobsFor(component: string, compact: boolean | undefined) {
+  // LC-76: an omitted override must leave density under the preset's control.
+  return compact === undefined ? { component } : { component, compact };
+}
+
+/** Nested surfaces step density only; hue remains inherited (LC-73 / R12). */
+function NestedScale({ density, children }: { density: string; children: ReactNode }) {
+  if (density === "compact") return children;
+  return <Preset overrides={{ density: "compact" }}>{children}</Preset>;
+}
+
 // ---------------------------------------------------------------------------
 // Screen — page outer shell (scroll, max-width, padding, theme background)
 // ---------------------------------------------------------------------------
@@ -76,6 +89,8 @@ export interface ScreenProps extends YStackProps {
   noPadding?: boolean;
   /** Props forwarded to the inner ScrollView when scroll=true. */
   scrollViewProps?: TamaguiScrollViewProps;
+  /** Density override inherited by the subtree. Omitted follows the preset. */
+  compact?: boolean;
 }
 
 /**
@@ -83,8 +98,7 @@ export interface ScreenProps extends YStackProps {
  * compose-only screens.
  *
  * SF-TRANSPARENT + SP-PAD/SP-GAP: panelPadding and gapLg restyle with the
- * density/space knobs (LC-76). Do not wrap in `<Surface density="comfortable">`
- * — that ceiling pinned page inset and made the density knob a no-op.
+ * density/space knobs (LC-76). Only an explicit compact prop overrides density.
  *
  * @example
  * <Screen>
@@ -92,16 +106,26 @@ export interface ScreenProps extends YStackProps {
  *   <FrappeImageView doctype="Pokemon" />
  * </Screen>
  */
-export function Screen({
+export function Screen({ compact, ...props }: ScreenProps) {
+  const density = compact === undefined ? undefined : compact ? "compact" : "comfortable";
+  return (
+    <Surface density={density}>
+      <ScreenInner compact={compact} {...props} />
+    </Surface>
+  );
+}
+
+function ScreenInner({
   children,
   scroll = true,
   maxWidth = CONTENT_MAX_WIDTH,
   bleed = false,
   noPadding = false,
   scrollViewProps,
+  compact,
   ...rest
 }: ScreenProps) {
-  const { knobProps } = useResolvedKnobs({ component: "Screen" });
+  const { knobProps } = useResolvedKnobs(knobsFor("Screen", compact));
 
   const inner = (
     <YStack
@@ -180,6 +204,8 @@ export interface PageHeaderProps extends YStackProps {
    * surface. Semantics (headingLevel) are unchanged either way.
    */
   titleScale?: PageTitleScale;
+  /** Density override. Omitted follows the preset or parent Surface. */
+  compact?: boolean;
 }
 
 /**
@@ -200,10 +226,11 @@ export function PageHeader({
   divider = true,
   headingLevel = 1,
   titleScale,
+  compact,
   children,
   ...rest
 }: PageHeaderProps) {
-  const { knobProps } = useResolvedKnobs();
+  const { knobProps } = useResolvedKnobs(knobsFor("PageHeader", compact));
   const insetToken = usePageChromeInset();
   // DG-A11Y-02: count the built-in title toward the Screen's h1 budget.
   // Custom `heading` nodes have an unknown level and are not registered.
@@ -230,9 +257,10 @@ export function PageHeader({
     (title ? (
       <TitleTag
         margin={0}
-        fontWeight={knobProps.heading.fontWeight}
         {...titleSize}
+        fontWeight={knobProps.heading.fontWeight}
         {...headingFamily}
+        data-font-weight-knob={knobProps.heading.fontWeight === "700" ? "bold" : "regular"}
       >
         {title}
       </TitleTag>
@@ -247,6 +275,7 @@ export function PageHeader({
   return (
     <YStack
       data-testid="page-header"
+      data-density={knobProps.density}
       overflow="visible"
       {...bleed}
       {...(showHairline ? { ...hairline.bottom, borderColor: componentColors.divider } : null)}
@@ -327,6 +356,8 @@ export interface PageSectionProps extends YStackProps {
    * without skips. Visuals are pinned by the shared sectionHeading scale.
    */
   headingLevel?: Exclude<PageHeadingLevel, 1>;
+  /** Density override. Omitted follows the preset or parent Surface. */
+  compact?: boolean;
 }
 
 /**
@@ -340,10 +371,11 @@ export function PageSection({
   divider = true,
   surface = false,
   headingLevel = 2,
+  compact,
   children,
   ...rest
 }: PageSectionProps) {
-  const { knobProps } = useResolvedKnobs();
+  const { knobProps } = useResolvedKnobs(knobsFor("PageSection", compact));
   // See PageHeader: native-only heading family from the headingFont knob.
   const headingFamily = isWeb ? null : { fontFamily: knobProps.heading.fontFamily };
   // The sectionHeading spread pins the visual scale, so stepped levels only
@@ -387,11 +419,16 @@ export function PageSection({
   // a sibling flips `surface` — only the section CONTENT earns the card's
   // panelPadding inset (the painted surface owns it, per LC-39's converse).
   return (
-    <YStack {...knobProps.gap} {...rest}>
+    <YStack
+      data-testid="page-section"
+      data-density={knobProps.density}
+      {...knobProps.gap}
+      {...rest}
+    >
       {headerBlock}
       {surface ? (
         <YStack {...knobProps.gap} {...surfaceProps}>
-          {children}
+          <NestedScale density={knobProps.density}>{children}</NestedScale>
         </YStack>
       ) : (
         children