@multiplatform.one/components 7.11.0 → 7.16.0

package/src/layouts/PaneScaffold.tsx

@@ -6,6 +6,12 @@
  * resolved size class rides a context down, so an inner scaffold reflows with
  * the outer one instead of splitting inside a stacked column.
  *
+ * The seam runs on one axis. `orientation="horizontal"` (the default) puts the
+ * panes side by side; `orientation="vertical"` puts `secondary` under
+ * `primary` (a console under a source pane, an editor under a page). The sash,
+ * its clamps, keyboard handling and the controlled-fraction contract are the
+ * same code with the axis swapped; only the dimension it reads changes.
+ *
  * Devs declare pane roles; the scaffold picks 1 vs 2 columns from the
  * canonical layout size class (`expanded` @ 860 = two-pane budget).
  *
@@ -64,10 +70,17 @@ const DEFAULT_MAX_FRACTION = 0.8;
 // ── PaneScaffold ──────────────────────────────────────────────────────────
 
 export type PaneRole = "primary" | "secondary";
+export type PaneOrientation = "horizontal" | "vertical";
 
 export interface PaneScaffoldProps extends Omit<XStackProps, "children"> {
   primary: ReactNode;
   secondary?: ReactNode;
+  /**
+   * Axis of the seam. `horizontal` (default) sets the panes side by side;
+   * `vertical` docks `secondary` under `primary`. A vertical scaffold splits
+   * the height its parent gives it, so the parent must be bounded.
+   */
+  orientation?: PaneOrientation;
   /**
    * Which pane to show when `narrowLayout` is `swap`. Default: `primary`.
    * List-detail on compact typically flips to `secondary` once an item is
@@ -122,6 +135,7 @@ const PaneSizeClassContext = createContext<LayoutSizeClass | null>(null);
 export function PaneScaffold({
   primary,
   secondary,
+  orientation = "horizontal",
   activePane: activePaneProp,
   narrowLayout: narrowLayoutProp,
   maxPanes: maxPanesProp,
@@ -150,6 +164,7 @@ export function PaneScaffold({
   // secondary by default leaves that content unreachable on a phone.
   const narrowLayout = narrowLayoutProp ?? (activePaneProp === undefined ? "stack" : "swap");
   const stacked = !split && hasSecondary && narrowLayout === "stack";
+  const vertical = orientation === "vertical";
   const [primaryFlex, secondaryFlex] = paneFlex;
 
   // flexBasis auto, not the flex:1 shorthand's 0%: react-native-web resets
@@ -170,6 +185,7 @@ export function PaneScaffold({
         data-testid="pane-scaffold"
         data-panes="2"
         data-pane-layout="stack"
+        data-orientation={orientation}
         data-size-class={sizeClass}
         data-sash="false"
         {...rest}
@@ -212,6 +228,7 @@ export function PaneScaffold({
         data-testid="pane-scaffold"
         data-panes="1"
         data-pane-layout="single"
+        data-orientation={orientation}
         data-size-class={sizeClass}
         {...rest}
       >
@@ -221,6 +238,7 @@ export function PaneScaffold({
   } else {
     content = (
       <XStack
+        flexDirection={vertical ? "column" : "row"}
         flexGrow={1}
         flexShrink={1}
         flexBasis="auto"
@@ -233,12 +251,14 @@ export function PaneScaffold({
         data-testid="pane-scaffold"
         data-panes="2"
         data-pane-layout="split"
+        data-orientation={orientation}
         data-size-class={sizeClass}
         data-sash={resizable ? "true" : "false"}
         {...rest}
       >
         {resizable ? (
           <ResizablePanes
+            vertical={vertical}
             primary={primary}
             secondary={secondary}
             primaryFlex={primaryFlex}
@@ -254,7 +274,7 @@ export function PaneScaffold({
               flex={primaryFlex}
               minWidth={0}
               minHeight={0}
-              {...(gapped ? undefined : paneHairlineEnd)}
+              {...(gapped ? undefined : vertical ? paneHairlineBottom : paneHairlineEnd)}
               data-testid="pane-primary"
             >
               {primary}
@@ -287,7 +307,21 @@ function clampFraction(value: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, value));
 }
 
+function axisSize(
+  vertical: boolean,
+  rect: { width?: number; height?: number } | null | undefined,
+): number {
+  return (vertical ? rect?.height : rect?.width) ?? 0;
+}
+
+function pointerPos(vertical: boolean, e: any): number {
+  return vertical
+    ? (e.clientY ?? e.nativeEvent?.pageY ?? 0)
+    : (e.clientX ?? e.nativeEvent?.pageX ?? 0);
+}
+
 function ResizablePanes({
+  vertical,
   primary,
   secondary,
   primaryFlex,
@@ -297,6 +331,7 @@ function ResizablePanes({
   fraction: fractionProp,
   onFractionChange,
 }: {
+  vertical: boolean;
   primary: ReactNode;
   secondary: ReactNode;
   primaryFlex: number;
@@ -308,23 +343,24 @@ function ResizablePanes({
 }) {
   const sashId = useId();
   const rtl = useDirection() === "rtl";
-  const dirSign = rtl ? -1 : 1;
+  // RTL mirrors the inline axis only; a vertical seam has no mirror.
+  const dirSign = !vertical && rtl ? -1 : 1;
   const defaultFraction = primaryFlex / Math.max(primaryFlex + secondaryFlex, 1);
   const [uncontrolled, setUncontrolled] = useState(defaultFraction);
   const fraction = clampFraction(fractionProp ?? uncontrolled, minFraction, maxFraction);
   const [hot, setHot] = useState(false);
   const [kbFocus, setKbFocus] = useState(false);
   const [dragging, setDragging] = useState(false);
-  const widthRef = useRef(0);
+  const sizeRef = useRef(0);
   const rowRef = useRef<any>(null);
-  const dragRef = useRef<{ startX: number; startFraction: number; moved: boolean } | null>(null);
+  const dragRef = useRef<{ start: number; startFraction: number; moved: boolean } | null>(null);
   const lastTapRef = useRef(0);
+  const resizeCursor = vertical ? "row-resize" : "col-resize";
 
-  const measureWidth = () => {
-    const node = rowRef.current;
-    const rect = node?.getBoundingClientRect?.();
-    if (rect?.width) widthRef.current = rect.width;
-  };
+  const measureSize = useCallback(() => {
+    const size = axisSize(vertical, rowRef.current?.getBoundingClientRect?.());
+    if (size) sizeRef.current = size;
+  }, [vertical]);
 
   ensureKeyboardModalityTracking();
 
@@ -356,22 +392,16 @@ function ResizablePanes({
     const prevUserSelect = document.body.style.userSelect;
     const prevCursor = document.documentElement.style.cursor;
     document.body.style.userSelect = "none";
-    document.documentElement.style.cursor = "col-resize";
+    document.documentElement.style.cursor = resizeCursor;
 
     const onMove = (e: PointerEvent) => {
       const session = dragRef.current;
-      let width = widthRef.current;
-      if (width <= 0) {
-        const rect = rowRef.current?.getBoundingClientRect?.();
-        if (rect?.width) {
-          width = rect.width;
-          widthRef.current = width;
-        }
-      }
-      if (!session || width <= 0) return;
-      const dx = (e.clientX - session.startX) * dirSign;
-      if (Math.abs(dx) > 2) session.moved = true;
-      commit(session.startFraction + dx / width);
+      if (sizeRef.current <= 0) measureSize();
+      const size = sizeRef.current;
+      if (!session || size <= 0) return;
+      const delta = (pointerPos(vertical, e) - session.start) * dirSign;
+      if (Math.abs(delta) > 2) session.moved = true;
+      commit(session.startFraction + delta / size);
     };
     window.addEventListener("pointermove", onMove);
     window.addEventListener("pointerup", finishDrag);
@@ -383,7 +413,7 @@ function ResizablePanes({
       window.removeEventListener("pointerup", finishDrag);
       window.removeEventListener("pointercancel", finishDrag);
     };
-  }, [commit, dirSign, dragging, finishDrag]);
+  }, [commit, dirSign, dragging, finishDrag, measureSize, resizeCursor, vertical]);
 
   const onSashPointerDown = (e: any) => {
     if (e.button != null && e.button !== 0) return;
@@ -394,9 +424,9 @@ function ResizablePanes({
     } catch {
       /* native / no capture */
     }
-    measureWidth();
+    measureSize();
     dragRef.current = {
-      startX: e.clientX ?? e.nativeEvent?.pageX ?? 0,
+      start: pointerPos(vertical, e),
       startFraction: fraction,
       moved: false,
     };
@@ -406,21 +436,23 @@ function ResizablePanes({
 
   const onSashPointerMove = (e: any) => {
     if (!dragRef.current || isWeb) return;
-    const width = widthRef.current;
-    if (width <= 0) return;
-    const x = e.clientX ?? e.nativeEvent?.pageX ?? 0;
-    const dx = (x - dragRef.current.startX) * dirSign;
-    if (Math.abs(dx) > 2) dragRef.current.moved = true;
-    commit(dragRef.current.startFraction + dx / width);
+    const size = sizeRef.current;
+    if (size <= 0) return;
+    const delta = (pointerPos(vertical, e) - dragRef.current.start) * dirSign;
+    if (Math.abs(delta) > 2) dragRef.current.moved = true;
+    commit(dragRef.current.startFraction + delta / size);
   };
 
+  const keyBack = vertical ? "ArrowUp" : "ArrowLeft";
+  const keyForward = vertical ? "ArrowDown" : "ArrowRight";
+
   const onSashKeyDown = (e: any) => {
     const key = e.key as string;
     const step = e.shiftKey ? FRACTION_STEP_LARGE : FRACTION_STEP;
-    if (key === "ArrowLeft") {
+    if (key === keyBack) {
       e.preventDefault?.();
       commit(fraction - step * dirSign);
-    } else if (key === "ArrowRight") {
+    } else if (key === keyForward) {
       e.preventDefault?.();
       commit(fraction + step * dirSign);
     } else if (key === "Home") {
@@ -437,10 +469,12 @@ function ResizablePanes({
 
   const percent = Math.round(fraction * 100);
   const lineHot = hot || dragging || kbFocus;
+  const sashOverhang = -(SASH_VISUAL - hairlineWidth) / 2;
 
   return (
     <XStack
       ref={rowRef}
+      flexDirection={vertical ? "column" : "row"}
       flexGrow={1}
       flexShrink={1}
       flexBasis="auto"
@@ -449,7 +483,7 @@ function ResizablePanes({
       width="100%"
       alignItems="stretch"
       onLayout={(e) => {
-        widthRef.current = e.nativeEvent.layout.width;
+        sizeRef.current = axisSize(vertical, e.nativeEvent.layout);
       }}
     >
       <YStack
@@ -463,7 +497,7 @@ function ResizablePanes({
         {primary}
       </YStack>
       <YStack
-        width={hairlineWidth}
+        {...(vertical ? { height: hairlineWidth } : { width: hairlineWidth })}
         flexGrow={0}
         flexShrink={0}
         alignSelf="stretch"
@@ -472,16 +506,26 @@ function ResizablePanes({
       >
         <YStack
           position="absolute"
-          top={0}
-          bottom={0}
-          width={SASH_VISUAL}
-          left={-(SASH_VISUAL - hairlineWidth) / 2}
-          alignItems="center"
-          cursor="col-resize"
+          {...(vertical
+            ? {
+                left: 0,
+                right: 0,
+                height: SASH_VISUAL,
+                top: sashOverhang,
+                justifyContent: "center" as const,
+              }
+            : {
+                top: 0,
+                bottom: 0,
+                width: SASH_VISUAL,
+                left: sashOverhang,
+                alignItems: "center" as const,
+              })}
+          cursor={resizeCursor}
           userSelect="none"
           tabIndex={0}
           role="separator"
-          aria-orientation="vertical"
+          aria-orientation={vertical ? "horizontal" : "vertical"}
           aria-controls={sashId}
           aria-valuemin={Math.round(minFraction * 100)}
           aria-valuemax={Math.round(maxFraction * 100)}
@@ -508,12 +552,21 @@ function ResizablePanes({
           onBlur={() => setKbFocus(false)}
           onKeyDown={onSashKeyDown}
         >
-          <YStack
-            flex={1}
-            width={lineHot ? 2 : hairlineWidth}
-            backgroundColor={lineHot ? "$accentBackground" : "$borderColor"}
-            {...(lineHot ? undefined : hairline.vline)}
-          />
+          {vertical ? (
+            <YStack
+              alignSelf="stretch"
+              height={lineHot ? 2 : hairlineWidth}
+              backgroundColor={lineHot ? "$accentBackground" : "$borderColor"}
+              {...(lineHot ? undefined : hairline.line)}
+            />
+          ) : (
+            <YStack
+              flex={1}
+              width={lineHot ? 2 : hairlineWidth}
+              backgroundColor={lineHot ? "$accentBackground" : "$borderColor"}
+              {...(lineHot ? undefined : hairline.vline)}
+            />
+          )}
         </YStack>
       </YStack>
       <YStack

package/src/layouts/attachments.radius.spec.tsx

@@ -0,0 +1,74 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { cleanup, screen } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset, type Knobs } from "@multiplatform.one/theme";
+import { afterEach, describe, expect, it } from "vitest";
+import { Attachments, type AttachmentItem } from "./attachments";
+
+afterEach(cleanup);
+
+const items: AttachmentItem[] = [
+  { id: "a", fileName: "restore-log.txt", fileUrl: "/a.txt", fileSize: 12_000 },
+  { id: "b", fileName: "topology.txt", fileUrl: "/b.txt", fileSize: 812_000 },
+];
+
+function rowAtoms(overrides: Partial<Knobs>) {
+  renderWithProviders(
+    <Preset overrides={overrides}>
+      <Attachments items={items} />
+    </Preset>,
+  );
+  return screen
+    .getAllByRole("listitem")
+    .map((row) => (row.getAttribute("class") ?? "").split(/\s+/));
+}
+
+describe("Attachments rows are a CONTAINER-CAP stack (DG-RAD-04, MPO-56)", () => {
+  it("caps the outer corners at the row padding at full", () => {
+    const [first, last] = rowAtoms({ borderRadius: "full", space: "medium" });
+    expect(first).toEqual(
+      expect.arrayContaining(["_borderStartStartRadius-18px", "_borderStartEndRadius-18px"]),
+    );
+    expect(last).toEqual(
+      expect.arrayContaining(["_borderEndStartRadius-18px", "_borderEndEndRadius-18px"]),
+    );
+  });
+
+  it("caps large at 13 under space small, where 16 would exceed the padding", () => {
+    const [first] = rowAtoms({ borderRadius: "large", space: "small" });
+    expect(first).toEqual(
+      expect.arrayContaining(["_borderStartStartRadius-13px", "_borderStartEndRadius-13px"]),
+    );
+  });
+
+  it("declares each row a StackedRow cap with the stops it resolved", () => {
+    renderWithProviders(
+      <Preset overrides={{ borderRadius: "large", space: "small" }}>
+        <Attachments items={items} />
+      </Preset>,
+    );
+    const declared = screen.getAllByRole("listitem").map((row) => ({
+      container: row.getAttribute("data-constraint-container"),
+      position: row.getAttribute("data-stack-position"),
+      radius: row.getAttribute("data-radius-knob"),
+      space: row.getAttribute("data-space-knob"),
+    }));
+    expect(declared).toEqual([
+      { container: "StackedRow", position: "first", radius: "large", space: "small" },
+      { container: "StackedRow", position: "last", radius: "large", space: "small" },
+    ]);
+  });
+
+  it("squares every corner at none", () => {
+    for (const row of rowAtoms({ borderRadius: "none" })) {
+      const corners = row.filter((a) =>
+        /^_border(Start|End)(Start|End)Radius-(\d+px|t-radius-\d+)$/.test(a),
+      );
+      expect(corners).toHaveLength(4);
+      expect(corners.filter((a) => !/-(0px|t-radius-0)$/.test(a))).toEqual([]);
+    }
+  });
+});

package/src/layouts/attachments.tsx

@@ -11,6 +11,7 @@ import {
 } from "@phosphor-icons/react";
 import { downloadFile } from "@multiplatform.one/platform";
 import {
+  containerCapProps,
   ensureFocusVisibleRing,
   ensureKeyboardModalityTracking,
   getGroupPosition,
@@ -335,7 +336,7 @@ function AttachmentRow({
   const ext = getFileExtension(attachment);
   const iconSize = compact ? 14 : 16;
   const position = getGroupPosition(index, count);
-  const corners = stackRadiusProps(position, knobProps.borderRadius.borderRadius);
+  const corners = stackRadiusProps(position, knobProps.containerRadius.borderRadius);
 
   const actions = {
     onPreview: () => onPreview(attachment),
@@ -419,6 +420,7 @@ function AttachmentRow({
       <XStack
         role="listitem"
         data-stack-position={position}
+        {...containerCapProps("StackedRow", knobProps.borderRadius.borderRadius, knobProps.space)}
         alignItems="center"
         paddingVertical="$2"
         paddingHorizontal={rowPad}

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

@@ -161,3 +161,23 @@ describe("density unpinned (LC-76)", () => {
     expect(screen.getByTestId("inner-section").getAttribute("data-density")).toBe("compact");
   });
 });
+
+describe("PageSection surface declares its container cap (DG-RAD-04)", () => {
+  it("the painted surface carries the knob stops its radius resolved from", () => {
+    renderWithProviders(
+      <Preset overrides={{ borderRadius: "full", space: "small" }}>
+        <PageSection surface title="Details" data-testid="details">
+          <></>
+        </PageSection>
+      </Preset>,
+    );
+    const surface = document.querySelector('[data-constraint-container="PageSection"]');
+    expect(surface?.getAttribute("data-radius-knob")).toBe("full");
+    expect(surface?.getAttribute("data-space-knob")).toBe("small");
+  });
+
+  it("a section without a surface makes no claim", () => {
+    renderWithProviders(<PageSection title="Plain" />);
+    expect(document.querySelector("[data-constraint-container]")).toBeNull();
+  });
+});

package/src/layouts/page.tsx

@@ -19,6 +19,7 @@ import {
   MIN_PRESS_TARGET,
   Preset,
   Surface,
+  containerCapProps,
   hairline,
   layoutBreakpoints,
   resolvePageTitleScale,
@@ -396,6 +397,7 @@ export function PageSection({
         ...knobProps.surface,
         ...knobProps.containerRadius,
         ...knobProps.panelPadding,
+        ...containerCapProps("PageSection", knobProps.borderRadius.borderRadius, knobProps.space),
       } as Partial<YStackProps>)
     : {};
 

package/src/layouts/sidebar.tsx

@@ -8,6 +8,7 @@ import {
   useReadableTextOn,
   useResolvedKnobs,
   wasKeyboardFocus,
+  transitionProps,
 } from "@multiplatform.one/theme";
 import type React from "react";
 import { Fragment, useId, useState } from "react";
@@ -168,9 +169,7 @@ export function Sidebar({
                           cursor={pressable ? "pointer" : "default"}
                           userSelect="none"
                           onPress={item.onPress}
-                          {...(knobProps.transition
-                            ? { transition: knobProps.transition }
-                            : undefined)}
+                          {...transitionProps(knobProps.transition)}
                           {...(pressable
                             ? {
                                 role: "button" as const,

package/src/layouts/timeline-radius.spec.tsx

@@ -76,3 +76,41 @@ describe("Timeline entry radius knob (SB-M-301)", () => {
     expect(fullRadiusClass).not.toBe(noneRadiusClass);
   });
 });
+
+describe("Timeline comment card is CONTAINER-CAP on its own padding (DG-RAD-04, MPO-56)", () => {
+  const cardRadius = (borderRadius: "none" | "medium" | "large" | "full", compact = false) => {
+    renderWithProviders(
+      <Preset overrides={{ borderRadius }}>
+        <Timeline entries={entries} compact={compact} />
+      </Preset>,
+    );
+    const found = entryRowRadiusClass();
+    cleanup();
+    return found;
+  };
+
+  it("takes the token while it fits the $3 padding", () => {
+    expect(cardRadius("none")).toBe("_btlr-0px");
+    expect(cardRadius("medium")).toBe("_btlr-9px");
+  });
+
+  it("caps large and full at the 13px padding", () => {
+    expect(cardRadius("large")).toBe("_btlr-13px");
+    expect(cardRadius("full")).toBe("_btlr-13px");
+  });
+
+  it("caps at the compact $2 padding when compact", () => {
+    expect(cardRadius("medium", true)).toBe("_btlr-7px");
+  });
+
+  it("declares an OwnInset cap for the constraint audit", () => {
+    renderWithProviders(
+      <Preset overrides={{ borderRadius: "full" }}>
+        <Timeline entries={entries} />
+      </Preset>,
+    );
+    const card = screen.getByText("Looks good!").closest("[data-constraint-container]");
+    expect(card?.getAttribute("data-constraint-container")).toBe("OwnInset");
+    expect(card?.getAttribute("data-radius-knob")).toBe("full");
+  });
+});

package/src/layouts/timeline.tsx

@@ -13,12 +13,15 @@ import {
 import { useDirection } from "../hooks/useDirection";
 import {
   MIN_PRESS_TARGET,
+  containerCapProps,
   ensureFocusVisibleRing,
   formatAbsoluteDateTime,
   formatRelativeTimestamp,
   getGroupPosition,
   pressTargetHitSlop,
   pressTargetStyle,
+  radiusStopFromToken,
+  resolveRadiusClass,
   stackRadiusProps,
   useResolvedKnobs,
 } from "@multiplatform.one/theme";
@@ -37,6 +40,7 @@ import {
   XStack,
   YStack,
   type YStackProps,
+  getTokenValue,
   isWeb,
 } from "tamagui";
 import { Avatar } from "../Avatar";
@@ -556,6 +560,15 @@ export function Timeline({
   // Twin of the live avatar/badge column — spine centers on this well.
   const columnPx = compact ? 20 : sz === "$5" ? 34 : 24;
   const rowPad = compact ? 8 : sz === "$5" ? 16 : 12;
+  // DG-RAD-04: the comment card is a padded content container, so it caps
+  // at its own padding, not at the panelPadding knob it does not use.
+  const commentPad = compact ? "$2" : "$3";
+  const commentPadPx = getTokenValue(commentPad as Parameters<typeof getTokenValue>[0], "space");
+  const commentStop = radiusStopFromToken(radiusToken);
+  const commentRadius =
+    commentStop && typeof commentPadPx === "number"
+      ? resolveRadiusClass("CONTAINER-CAP", commentStop, { paddingPx: commentPadPx })
+      : radiusToken;
 
   const emptyIconSize = compact
     ? sz === "$3"
@@ -818,7 +831,9 @@ export function Timeline({
           gap="$1"
           backgroundColor={componentColors.surface.background}
           {...knobProps.borderRadius}
-          padding={compact ? "$2" : "$3"}
+          borderRadius={commentRadius}
+          {...containerCapProps("OwnInset", radiusToken, knobProps.space)}
+          padding={commentPad}
         >
           <XStack gap="$2" alignItems="center" flexWrap="wrap">
             <Text fontSize={nameFontSize} fontWeight="400" color={componentColors.text.primary}>