@multiplatform.one/components 7.11.0 → 7.16.0

package/src/charts/series.tsx

@@ -1,7 +1,7 @@
 import { MIN_PRESS_TARGET } from "@multiplatform.one/theme";
 import type { ScaleBand, ScaleLinear } from "d3-scale";
 import { useId } from "react";
-import { areaPath, arcPath, linePath, pieSlices, canMaskPieSlices } from "./math";
+import { areaPath, arcPath, barPath, linePath, pieSlices, canMaskPieSlices } from "./math";
 import {
   Circle,
   Defs,
@@ -10,6 +10,7 @@ import {
   Path,
   Rect,
   datumTargetProps,
+  chartBarProps,
   chartMarkProps,
   chartWebProps,
   luminanceMaskProps,
@@ -69,7 +70,8 @@ export interface BarSeriesProps extends DatumTargetCallbacks {
 
 /**
  * Vertical bars from the zero baseline (negative values hang below it).
- * Corner radius follows the borderRadius knob, clamped to bar anatomy.
+ * Only the value end rounds, with the borderRadius knob clamped to bar
+ * anatomy; the baseline corners stay square (R-SCALE-DATA).
  * Hit target = the full column, floored at 44px width.
  */
 export function BarSeries({ data, xScale, yScale, plot, fills, ...callbacks }: BarSeriesProps) {
@@ -90,15 +92,18 @@ export function BarSeries({ data, xScale, yScale, plot, fills, ...callbacks }: B
         const targetWidth = Math.max(bandwidth, MIN_PRESS_TARGET);
         return (
           <G key={`${datum.label}-${index}`}>
-            <Rect
+            <Path
               {...chartMarkProps(datum.label)}
-              x={x}
-              y={y}
-              width={bandwidth}
-              height={height}
+              {...chartBarProps({ x, y, width: bandwidth, height, radius })}
+              d={barPath({
+                x,
+                y,
+                width: bandwidth,
+                height,
+                radius,
+                valueEnd: valueY <= baseline ? "top" : "bottom",
+              })}
               fill={fills[index]}
-              rx={radius}
-              ry={radius}
             />
             {interactive ? (
               <Rect

package/src/charts/svg.ts

@@ -88,6 +88,19 @@ export function chartMarkProps(label: string): Record<string, unknown> {
   return isWeb ? { "data-mpo-chart-mark": label } : {};
 }
 
+/** A bar mark's box and value-end radius, for audits that cannot read a path. */
+export function chartBarProps(box: {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  radius: number;
+}): Record<string, unknown> {
+  return isWeb
+    ? { "data-mpo-chart-bar": [box.x, box.y, box.width, box.height, box.radius].join(",") }
+    : {};
+}
+
 export function chartChromeProps(kind: "axis" | "grid"): Record<string, unknown> {
   return isWeb ? { "data-mpo-chart-chrome": kind } : {};
 }

package/src/charts/useChartTheme.ts

@@ -16,11 +16,18 @@
  *   from the Tamagui font config — KNOB-TOTALITY for text inside SVG);
  * - `transition` carries the animation knob (undefined at `none`/PRM via
  *   `useResolvedKnobs`) so draw-in motion stops per A-CONTINUOUS;
- * - `barCornerRadius` steps with the borderRadius knob and clamps at the
- *   mark's own anatomy (R-CLAMP: never past half the bar).
+ * - `barCornerRadius` resolves the borderRadius knob through the DEFAULT
+ *   class (Part 2b: 0/5/9/16/50) and caps at the mark's own anatomy
+ *   (R-SCALE-DATA: half the band, and the bar's own value extent).
  */
 
-import { useChartPalette, useResolvedKnobs, type ChartPalette } from "@multiplatform.one/theme";
+import {
+  radiusStopFromToken,
+  resolveRadiusClass,
+  useChartPalette,
+  useResolvedKnobs,
+  type ChartPalette,
+} from "@multiplatform.one/theme";
 import * as Colors from "@tamagui/colors";
 import { useMemo } from "react";
 import {
@@ -49,7 +56,7 @@ export interface ChartTheme {
   transition?: TransitionProp;
   /** True when draw-in / continuous motion may play (A-CONTINUOUS). */
   animationEnabled: boolean;
-  /** Bar corner radius from the borderRadius knob, clamped to anatomy. */
+  /** Value-end bar corner radius from the borderRadius knob, clamped to anatomy. */
   barCornerRadius: (bandWidth: number, barHeight: number) => number;
 }
 
@@ -59,15 +66,6 @@ const labelFontSizeBySizeToken: Record<string, number> = {
   $5: 13,
 };
 
-/** borderRadius knob → bar corner radius px (pre-clamp). */
-const barRadiusByKnob: Record<string, number> = {
-  $0: 0,
-  $2: 2,
-  $4: 3,
-  $6: 5,
-  $12: Number.POSITIVE_INFINITY,
-};
-
 function resolveFontFamily(fontToken: unknown): string | undefined {
   if (typeof fontToken !== "string") return undefined;
   try {
@@ -102,7 +100,8 @@ export function useChartTheme(): ChartTheme {
   const transition = knobProps.transition;
 
   return useMemo(() => {
-    const barRadiusBase = barRadiusByKnob[radiusToken] ?? 3;
+    const radiusStop = radiusStopFromToken(radiusToken);
+    const barRadiusBase = radiusStop ? resolveRadiusClass("DEFAULT", radiusStop) : 0;
     return {
       scheme,
       palette,
@@ -114,7 +113,7 @@ export function useChartTheme(): ChartTheme {
       transition,
       animationEnabled: transition !== null && transition !== undefined,
       barCornerRadius: (bandWidth: number, barHeight: number) =>
-        Math.max(0, Math.min(barRadiusBase, bandWidth / 2, barHeight / 2)),
+        Math.max(0, Math.min(barRadiusBase, bandWidth / 2, barHeight)),
     };
   }, [
     scheme,

package/src/code/Code/code.spec.tsx

@@ -1,5 +1,5 @@
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import { Code, CodeInline } from "./index";
 
 describe("Code", () => {
@@ -27,7 +27,7 @@ describe("Code", () => {
     const codeElement = container.querySelector("code");
     expect(codeElement).toBeTruthy();
     expect(codeElement!.getAttribute("data-code-font")).toBe("mono");
-    // React lowercases an unknown dataSet prop to dataset="[object Object]".
+    // An RN prop map on this host would land as dataset="[object Object]".
     expect(codeElement!.hasAttribute("dataset")).toBe(false);
   });
 });
@@ -51,21 +51,4 @@ describe("CodeInline", () => {
     const codeElement = container.querySelector("code");
     expect(codeElement).toBeDefined();
   });
-
-  it("emits data-code-font on web without a dataSet host-prop leak", () => {
-    const leak = /does not recognize the `dataSet` prop on a DOM element/;
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    try {
-      const { container } = renderWithProviders(<CodeInline>npm install</CodeInline>);
-      const codeElement = container.querySelector("code");
-      expect(codeElement).toBeDefined();
-      expect(codeElement?.getAttribute("data-code-font")).toBe("mono");
-      const leaks = errorSpy.mock.calls
-        .map((args) => args.map(String).join(" "))
-        .filter((message) => leak.test(message));
-      expect(leaks).toEqual([]);
-    } finally {
-      errorSpy.mockRestore();
-    }
-  });
 });

package/src/code/Code/index.tsx

@@ -81,12 +81,6 @@ export const CodeInline = CodeInlineFrame.styleable((props, ref) => {
       fontFamily="$mono"
       letterSpacing={0}
       data-code-font="mono"
-      // react-native-web reads dataSet; React-DOM warns on the camel host
-      // prop. Keep the kebab attribute on every target; spread dataSet
-      // only when TAMAGUI_TARGET is native.
-      {...(process.env.TAMAGUI_TARGET === "native"
-        ? ({ dataSet: { codeFont: "mono" } } as object)
-        : {})}
     />
   );
 });

package/src/code/CodeBlock/index.tsx

@@ -10,10 +10,11 @@ import { LinearGradient } from "@tamagui/linear-gradient";
 import { ClipboardIcon } from "@phosphor-icons/react";
 import {
   MIN_PRESS_TARGET,
-  isTouchSurface,
+  useTouchSurface,
   pressTargetHitSlop,
   sizeRecipeForToken,
   useResolvedKnobs,
+  transitionProps,
 } from "@multiplatform.one/theme";
 import { useEffect, useRef, useState } from "react";
 import { useTranslation } from "../../shared/i18n";
@@ -75,6 +76,7 @@ export function CodeBlock({
   const { region, copy } = useCopyFeedback();
   const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
+  const touch = useTouchSurface();
   // Content type scale follows the size knob (T-VALUE via sizeToken, LC-18);
   // an explicit size prop ejects.
   const codeSize = (size ?? knobProps.sizeToken) as any;
@@ -126,7 +128,7 @@ export function CodeBlock({
   const activateCopy = () => {
     void copy(codeText);
   };
-  const capSquare = sizeRecipeForToken(String(codeSize), { touch: isTouchSurface() }).height;
+  const capSquare = sizeRecipeForToken(String(codeSize), { touch }).height;
 
   return (
     <YStack position="relative" marginBottom="$4">
@@ -134,11 +136,11 @@ export function CodeBlock({
         <YStack
           ref={clampRef}
           position="relative"
+          {...transitionProps(transition)}
           {...(clamped && {
             maxHeight: expandTarget ?? clampHeight,
             overflow: "hidden" as const,
             ...knobProps.borderRadius,
-            ...(transition ? { transition } : {}),
           })}
         >
           {isCutoff && expandTarget == null && (

package/src/code/highlightedCode.spec.tsx

@@ -125,8 +125,8 @@ describe("HighlightedCode", () => {
     // The actual LC-07 pin: bodyFont serif / fontWeight bold must not reach
     // code text, so the line keeps the mono family class.
     expect(line!.className).toContain("font_mono");
-    // React does not recognise `dataSet`; leaving it on the line logged an
-    // unknown-prop error and wrote dataset="[object Object]" on every node.
+    // React does not recognise the RN prop map; leaving it on the line logged
+    // an unknown-prop error and wrote dataset="[object Object]" on every node.
     expect(container.querySelectorAll("[dataset]")).toHaveLength(0);
   });
 });

package/src/code/hostProps.spec.tsx

@@ -0,0 +1,55 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import type { ReactElement } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Code, CodeInline } from "./Code";
+import type { HighlightLine } from "./Highlighter";
+import { HighlightedCode } from "./HighlightedCode";
+
+const tokens: HighlightLine[] = [[{ content: "const x = 1;" }]];
+
+const cases: [string, ReactElement][] = [
+  ["Code", <Code>const x = 1;</Code>],
+  ["CodeInline", <CodeInline>npm install</CodeInline>],
+  ["HighlightedCode", <HighlightedCode tokens={tokens} />],
+];
+
+function hostProps(el: Element): Record<string, unknown> {
+  const key = Object.keys(el).find((k) => k.startsWith("__reactProps$"));
+  return key ? ((el as unknown as Record<string, Record<string, unknown>>)[key] ?? {}) : {};
+}
+
+function formatConsoleCall(args: unknown[]): string {
+  const [format = "", ...substitutions] = args.map(String);
+  let next = 0;
+  return format.replace(/%s/g, () => substitutions[next++] ?? "");
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe.each(["web", "native"])("code family host props, TAMAGUI_TARGET=%s", (target) => {
+  it.each(cases)("%s hands the code-font node no dataset prop map", (_name, node) => {
+    vi.stubEnv("TAMAGUI_TARGET", target);
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const { container } = renderWithProviders(node);
+      const hosts = Array.from(container.querySelectorAll("[data-code-font]"));
+      expect(hosts.length).toBeGreaterThan(0);
+      for (const host of hosts) {
+        const props = hostProps(host);
+        expect(props["data-code-font"]).toBe("mono");
+        expect(Object.keys(props).filter((key) => key.toLowerCase() === "dataset")).toEqual([]);
+        expect(host.hasAttribute("dataset")).toBe(false);
+      }
+      // React warns once per prop name per process, so the console alone
+      // cannot prove a later case clean; the props check above can.
+      const unknownProps = errorSpy.mock.calls
+        .map(formatConsoleCall)
+        .filter((message) => /does not recognize the `\w+` prop on a DOM element/.test(message));
+      expect(unknownProps).toEqual([]);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});

package/src/icons/themed.hydration.spec.tsx

@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { renderToString } from "react-dom/server";
+import { hydrateRoot } from "react-dom/client";
+import { TestProviders } from "@multiplatform.one/test-utils";
+import { sizeRecipeForToken } from "@multiplatform.one/theme";
+import { describe, expect, it, vi } from "vitest";
+import { themed } from "./themed";
+
+const host = vi.hoisted(() => ({ touch: false }));
+vi.mock("@multiplatform.one/platform", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@multiplatform.one/platform")>()),
+  isWeb: true,
+  isTouchable: false,
+  get isWebTouchable() {
+    return host.touch;
+  },
+}));
+
+const Icon = themed(({ size }: { size?: string | number }) => <svg width={size} height={size} />);
+function Fixture() {
+  return (
+    <TestProviders>
+      <Icon size="$4" />
+    </TestProviders>
+  );
+}
+
+describe("token icon hydration", () => {
+  it("preserves the server SVG before adopting touch sizing", async () => {
+    host.touch = false;
+    const container = document.createElement("div");
+    container.innerHTML = renderToString(<Fixture />);
+    document.body.append(container);
+    const icon = container.querySelector("svg");
+    const errors: unknown[] = [];
+    const spy = vi.spyOn(console, "error").mockImplementation((...args) => errors.push(args));
+    host.touch = true;
+    let root: ReturnType<typeof hydrateRoot> | undefined;
+    try {
+      await act(async () => {
+        root = hydrateRoot(container, <Fixture />, {
+          onRecoverableError: (error) => errors.push(error),
+        });
+      });
+      expect(container.querySelector("svg")).toBe(icon);
+      expect(icon?.getAttribute("width")).toBe(
+        String(sizeRecipeForToken("$4", { touch: true }).iconSize),
+      );
+      expect(
+        errors.filter((error) => /hydration|hydrated|didn't match/i.test(String(error))),
+      ).toEqual([]);
+    } finally {
+      await act(async () => root?.unmount());
+      spy.mockRestore();
+      container.remove();
+      host.touch = false;
+    }
+  });
+});

package/src/icons/themed.tsx

@@ -1,4 +1,4 @@
-import { isTouchSurface, sizeRecipeForToken } from "@multiplatform.one/theme";
+import { useTouchSurface, sizeRecipeForToken } from "@multiplatform.one/theme";
 import type { FC } from "react";
 import { getVariable, useProps, useTheme } from "tamagui";
 
@@ -9,6 +9,7 @@ import { getVariable, useProps, useTheme } from "tamagui";
  */
 export function themed<A extends FC>(Component: A) {
   return ((props: any) => {
+    const touch = useTouchSurface();
     const { color, disableTheme, size } = useProps(props);
     const theme = useTheme();
     const fromTheme =
@@ -19,11 +20,7 @@ export function themed<A extends FC>(Component: A) {
       <Component
         {...props}
         color={colorValue}
-        size={
-          typeof size === "string"
-            ? sizeRecipeForToken(size, { touch: isTouchSurface() }).iconSize
-            : size
-        }
+        size={typeof size === "string" ? sizeRecipeForToken(size, { touch }).iconSize : size}
       />
     );
   }) as A;

package/src/knobImmuneExports.ts

@@ -35,9 +35,9 @@ export const knobImmuneExports: Readonly<Record<string, string>> = {
   ScrollView: "scroll container lego; no opinionated chrome, fragments ride the content",
   // Separator left the registry 2026-08-28 (MPO-47): bare `Separator` is now
   // a house implementation (./Separator — painted 1px line), so it no longer
-  // qualifies for a row (house implementations ARE the knob story). The
-  // weight-knob question stays an ADJUDICATION-CANDIDATE on the component
-  // header (MPO-21 G10 / G0-clay R9).
+  // qualifies for a row (house implementations ARE the knob story). Its
+  // weight has no knob by ruling (MPO-21 G10-A, 2026-09-26), and Circle and
+  // Square stay knob-immune lego with no per-role radius (MPO-21 R-B).
   // MPO-21 G1 — Fold's substrate. Logic shell only; Accordion (and Fold)
   // own the painted chrome. Restored with the three below after MPO-21 R9 G8
   // (the Adapt drop) rewrote this file from a pre-MPO-21 copy and took them

package/src/layouts/PaneScaffold.spec.tsx

@@ -1,6 +1,6 @@
-import { cleanup, screen } from "@testing-library/react";
+import { cleanup, fireEvent, screen } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { Paragraph, YStack } from "tamagui";
 import {
   FeedLayout,
@@ -8,6 +8,7 @@ import {
   PaneScaffold,
   ReadingWidth,
   SupportingPaneLayout,
+  type PaneScaffoldProps,
 } from "./PaneScaffold";
 import * as Layouts from "./index";
 
@@ -277,3 +278,148 @@ describe("ReadingWidth", () => {
     expect(el).toHaveStyle({ maxWidth: "70ch" });
   });
 });
+
+// MPO-253: the seam runs on one axis. A vertical scaffold docks secondary
+// under primary with the sash, clamps and fraction contract the side-by-side
+// split already has, turned on its side.
+describe("PaneScaffold orientation (MPO-253)", () => {
+  function renderSplit(props: Partial<PaneScaffoldProps> = {}) {
+    renderWithProviders(
+      <PaneScaffold
+        sizeClass="expanded"
+        primary={<Paragraph>Body</Paragraph>}
+        secondary={<Paragraph>Editor</Paragraph>}
+        {...props}
+      />,
+    );
+    return screen.getByTestId("pane-sash");
+  }
+
+  function boundRow(width: number, height: number) {
+    const row = screen.getByTestId("pane-primary").parentElement as HTMLElement;
+    row.getBoundingClientRect = () =>
+      ({
+        x: 0,
+        y: 0,
+        top: 0,
+        left: 0,
+        right: width,
+        bottom: height,
+        width,
+        height,
+        toJSON: () => ({}),
+      }) as DOMRect;
+  }
+
+  it("docks secondary under primary behind a horizontal sash", () => {
+    const sash = renderSplit({ orientation: "vertical" });
+    const root = screen.getByTestId("pane-scaffold");
+    expect(root).toHaveAttribute("data-orientation", "vertical");
+    expect(root).toHaveAttribute("data-pane-layout", "split");
+    expect(root).toHaveAttribute("data-sash", "true");
+    expect(sash).toHaveAttribute("aria-orientation", "horizontal");
+    const primary = screen.getByTestId("pane-primary");
+    const secondary = screen.getByTestId("pane-secondary");
+    expect(
+      primary.compareDocumentPosition(secondary) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("keeps the side-by-side sash vertical by default", () => {
+    const sash = renderSplit();
+    expect(screen.getByTestId("pane-scaffold")).toHaveAttribute("data-orientation", "horizontal");
+    expect(sash).toHaveAttribute("aria-orientation", "vertical");
+  });
+
+  it.each([
+    ["horizontal", "ArrowRight", "ArrowLeft"],
+    ["vertical", "ArrowDown", "ArrowUp"],
+  ] as const)("%s: arrows step the fraction along its own axis", (orientation, forward, back) => {
+    const sash = renderSplit({ orientation });
+    expect(sash).toHaveAttribute("aria-valuenow", "50");
+    fireEvent.keyDown(sash, { key: forward });
+    expect(sash).toHaveAttribute("aria-valuenow", "52");
+    fireEvent.keyDown(sash, { key: forward, shiftKey: true });
+    expect(sash).toHaveAttribute("aria-valuenow", "62");
+    fireEvent.keyDown(sash, { key: back });
+    expect(sash).toHaveAttribute("aria-valuenow", "60");
+    fireEvent.keyDown(sash, { key: "Enter" });
+    expect(sash).toHaveAttribute("aria-valuenow", "50");
+  });
+
+  it("vertical ignores the horizontal arrows", () => {
+    const sash = renderSplit({ orientation: "vertical" });
+    fireEvent.keyDown(sash, { key: "ArrowRight" });
+    fireEvent.keyDown(sash, { key: "ArrowLeft" });
+    expect(sash).toHaveAttribute("aria-valuenow", "50");
+  });
+
+  it("vertical honours the clamps: the default is clamped, Home / End land on min / max", () => {
+    const sash = renderSplit({
+      orientation: "vertical",
+      paneFlex: [9, 1],
+      minPaneFraction: 0.3,
+      maxPaneFraction: 0.7,
+    });
+    expect(sash).toHaveAttribute("aria-valuemin", "30");
+    expect(sash).toHaveAttribute("aria-valuemax", "70");
+    expect(sash).toHaveAttribute("aria-valuenow", "70");
+    fireEvent.keyDown(sash, { key: "Home" });
+    expect(sash).toHaveAttribute("aria-valuenow", "30");
+    fireEvent.keyDown(sash, { key: "End" });
+    expect(sash).toHaveAttribute("aria-valuenow", "70");
+  });
+
+  it("vertical is controlled through primaryFraction / onPrimaryFractionChange", () => {
+    const onChange = vi.fn();
+    const sash = renderSplit({
+      orientation: "vertical",
+      primaryFraction: 0.4,
+      onPrimaryFractionChange: onChange,
+    });
+    expect(sash).toHaveAttribute("aria-valuenow", "40");
+    fireEvent.keyDown(sash, { key: "ArrowDown" });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange.mock.calls[0][0]).toBeCloseTo(0.42);
+    expect(sash).toHaveAttribute("aria-valuenow", "40");
+  });
+
+  it.each([
+    ["horizontal", { clientX: 200, clientY: 0 }, { clientX: 280, clientY: 0 }],
+    ["vertical", { clientX: 0, clientY: 100 }, { clientX: 0, clientY: 140 }],
+  ] as const)(
+    "%s: dragging the seam moves the fraction by the distance over the row",
+    (orientation, down, move) => {
+      const sash = renderSplit({ orientation });
+      boundRow(800, 400);
+      fireEvent.pointerDown(sash, { button: 0, ...down });
+      fireEvent.pointerMove(window, move);
+      expect(sash).toHaveAttribute("aria-valuenow", "60");
+      fireEvent.pointerUp(window, move);
+      fireEvent.pointerMove(window, { clientX: 0, clientY: 0 });
+      expect(sash).toHaveAttribute("aria-valuenow", "60");
+    },
+  );
+
+  it("vertical stacks like horizontal below the two-pane budget", () => {
+    renderWithProviders(
+      <PaneScaffold
+        sizeClass="compact"
+        orientation="vertical"
+        primary={<Paragraph>Body</Paragraph>}
+        secondary={<Paragraph>Editor</Paragraph>}
+      />,
+    );
+    const root = screen.getByTestId("pane-scaffold");
+    expect(root).toHaveAttribute("data-pane-layout", "stack");
+    expect(root).toHaveAttribute("data-orientation", "vertical");
+    expect(screen.queryByTestId("pane-sash")).not.toBeInTheDocument();
+    expect(screen.getByText("Editor")).toBeInTheDocument();
+  });
+
+  it("vertical keeps the seam on a narrow window when maxPanes ejects", () => {
+    const sash = renderSplit({ orientation: "vertical", sizeClass: "compact", maxPanes: 2 });
+    expect(screen.getByTestId("pane-scaffold")).toHaveAttribute("data-pane-layout", "split");
+    expect(sash).toHaveAttribute("aria-orientation", "horizontal");
+  });
+});

package/src/layouts/PaneScaffold.stories.tsx

@@ -110,7 +110,7 @@ const meta: Meta<typeof PaneScaffold> = {
     docs: {
       description: {
         component:
-          'Adaptive TWO-pane shell (DG-LAY-01/02) — `primary` and `secondary`, no more. Size classes: compact <640, medium ≥640, expanded ≥860 (FloatingPanel), large ≥1024, xl ≥1280. Two panes from expanded up unless `maxPanes` ejects. Side-by-side uses a hairline sash (Linear / VS Code / Polaris Frame); pass `paneGap` to eject to spaced columns. Below expanded the panes stack and the sash goes away, so nothing is hidden on a phone; `narrowLayout="swap"` (what `activePane` opts into) is the list-detail exception. Three regions come from nesting a scaffold inside a pane — see the Nested three-region story; the size class rides down, so the inner scaffold stacks with the outer.',
+          'Adaptive TWO-pane shell (DG-LAY-01/02) — `primary` and `secondary`, no more. Size classes: compact <640, medium ≥640, expanded ≥860 (FloatingPanel), large ≥1024, xl ≥1280. Two panes from expanded up unless `maxPanes` ejects. Side-by-side uses a hairline sash (Linear / VS Code / Polaris Frame); pass `paneGap` to eject to spaced columns. Below expanded the panes stack and the sash goes away, so nothing is hidden on a phone; `narrowLayout="swap"` (what `activePane` opts into) is the list-detail exception. Three regions come from nesting a scaffold inside a pane — see the Nested three-region story; the size class rides down, so the inner scaffold stacks with the outer. `orientation="vertical"` docks `secondary` under `primary` with the same sash turned on its side (↑/↓, Home/End, double-press resets) — see the Docked editor story.',
       },
     },
   },
@@ -119,6 +119,7 @@ const meta: Meta<typeof PaneScaffold> = {
       control: "select",
       options: ["compact", "medium", "expanded", "large", "xl"],
     },
+    orientation: { control: "radio", options: ["horizontal", "vertical"] },
     activePane: { control: "radio", options: ["primary", "secondary"] },
     narrowLayout: { control: "radio", options: ["stack", "swap"] },
     maxPanes: { control: "radio", options: [1, 2, undefined] },
@@ -202,6 +203,37 @@ export const NestedThreeRegion: Story = {
   ),
 };
 
+export const DockedEditor: Story = {
+  name: "Docked editor (vertical)",
+  args: { sizeClass: "xl", orientation: "vertical" },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`orientation="vertical"` runs the seam across the page: the body above, an editor docked below, resized by dragging the seam (↑/↓ from the keyboard, Home/End for the clamps, double-press resets). The body here is itself a horizontal scaffold, which is how a strip editor sits under a multi-pane page. A vertical scaffold splits the height its parent gives it, so the frame is bounded.',
+      },
+    },
+  },
+  render: (args) => (
+    <YStack height={520} padding="$4">
+      <SplitFrame height={480}>
+        <PaneScaffold
+          {...args}
+          paneFlex={[3, 1]}
+          primary={
+            <PaneScaffold
+              paneFlex={[2, 1]}
+              primary={<PaneFill label="Page body" hint="Drag the seam below · ↑/↓ resize" />}
+              secondary={<PaneFill label="Inspector" muted />}
+            />
+          }
+          secondary={<PaneFill label="Editor" hint="Docked under the page" muted />}
+        />
+      </SplitFrame>
+    </YStack>
+  ),
+};
+
 export const CompactActiveSecondary: Story = {
   name: "Compact (swap)",
   args: { sizeClass: "compact", activePane: "secondary" },