@multiplatform.one/components 7.11.0 → 7.15.0

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" },