@bearmenu/ui 0.8.37 → 0.8.38

package/dist/components/badge.d.ts

@@ -4,7 +4,7 @@ import * as React from 'react';
 import { VariantProps } from 'class-variance-authority';
 
 declare const badgeVariants: (props?: ({
-    variant?: "secondary" | "default" | "success" | "warning" | "destructive" | "outline" | "glass" | "overlay" | "brown" | "code" | "onPrimary" | "confirmed" | "pending" | "completed" | "assignee" | "softSuccess" | "softWarning" | "softDestructive" | "softNeutral" | null | undefined;
+    variant?: "default" | "secondary" | "success" | "warning" | "destructive" | "outline" | "glass" | "overlay" | "brown" | "code" | "onPrimary" | "confirmed" | "pending" | "completed" | "assignee" | "softSuccess" | "softWarning" | "softDestructive" | "softNeutral" | null | undefined;
     size?: "status" | "chip" | null | undefined;
     live?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;

package/dist/components/button.d.ts

@@ -3,8 +3,8 @@ import * as React from 'react';
 import { VariantProps } from 'class-variance-authority';
 
 declare const buttonVariants: (props?: ({
-    variant?: "secondary" | "default" | "link" | "warning" | "destructive" | "outline" | "ghost" | "glass" | "overlay" | "ink" | "brown" | "cta" | null | undefined;
-    size?: "default" | "icon" | "cta" | "xs" | "sm" | "lg" | "pill" | "cta-sm" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+    variant?: "default" | "link" | "secondary" | "warning" | "destructive" | "outline" | "ghost" | "glass" | "overlay" | "ink" | "brown" | "cta" | null | undefined;
+    size?: "icon" | "default" | "cta" | "xs" | "sm" | "lg" | "pill" | "cta-sm" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
     fullWidth?: boolean | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {

package/dist/components/command.d.ts

@@ -28,7 +28,7 @@ declare const CommandInput: React.ForwardRefExoticComponent<Omit<Omit<Pick<Pick<
     ref?: React.Ref<HTMLInputElement>;
 } & {
     asChild?: boolean;
-}, "asChild" | "key" | keyof React.InputHTMLAttributes<HTMLInputElement>>, "onChange" | "value" | "type"> & {
+}, "asChild" | "key" | keyof React.InputHTMLAttributes<HTMLInputElement>>, "value" | "onChange" | "type"> & {
     value?: string;
     onValueChange?: (search: string) => void;
 } & React.RefAttributes<HTMLInputElement>, "ref"> & React.RefAttributes<HTMLInputElement>>;
@@ -64,7 +64,7 @@ declare const CommandGroup: React.ForwardRefExoticComponent<Omit<{
     ref?: React.Ref<HTMLDivElement>;
 } & {
     asChild?: boolean;
-}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key">, "heading" | "value"> & {
+}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key">, "value" | "heading"> & {
     heading?: React.ReactNode;
     value?: string;
     forceMount?: boolean;
@@ -82,7 +82,7 @@ declare const CommandItem: React.ForwardRefExoticComponent<Omit<{
     ref?: React.Ref<HTMLDivElement>;
 } & {
     asChild?: boolean;
-}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key">, "onSelect" | "value" | "disabled"> & {
+}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key">, "value" | "onSelect" | "disabled"> & {
     disabled?: boolean;
     onSelect?: (value: string) => void;
     value?: string;

package/dist/components/pan-zoom-viewport.d.ts

@@ -23,7 +23,9 @@ import * as React from 'react';
  * - Keyboard, with the viewport focused: arrows pan (Shift for four times the
  *   step); `+` / `-` zoom and `0` fits, from anywhere inside it. Tabbing onto
  *   a table that sits off screen pans it into view.
- * - The + / − / Fit controls, bottom right.
+ * - The + / − / Fit controls: a raised card 12px in from the bottom-right
+ *   corner, 44 × 44 per button. Fit and the pan bounds keep the content clear
+ *   of them.
  *
  * The min-scale floor: `Fit` never shrinks below `minScale`. On a phone the
  * plan would otherwise fit at a size no finger can hit, so below the floor it
@@ -96,8 +98,18 @@ type PanZoomViewportProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children
     zoomStep?: number;
     /** One arrow press, in viewport px. Default 48. */
     panStep?: number;
-    /** The air Fit leaves around the content, and how far past it a pan may go. Default 24. */
+    /**
+     * The air Fit leaves around the content, and how far past it a pan may go.
+     * Default 24. With `controls` on, the side the control stack would cover
+     * (right or bottom, whichever costs the fit less) is widened to clear it.
+     */
     fitPadding?: number;
+    /**
+     * Where fitted content sits vertically when it is shorter than the
+     * viewport: `center` (default), or `top` — pinned under the top padding,
+     * as a phone shows a plan.
+     */
+    fitAlign?: "center" | "top";
     /** Render the + / − / Fit controls. Default true. */
     controls?: boolean;
     /** Called with every transform — gestures included, so keep it cheap. */
@@ -122,8 +134,18 @@ declare const PanZoomViewport: React.ForwardRefExoticComponent<Omit<React.HTMLAt
     zoomStep?: number;
     /** One arrow press, in viewport px. Default 48. */
     panStep?: number;
-    /** The air Fit leaves around the content, and how far past it a pan may go. Default 24. */
+    /**
+     * The air Fit leaves around the content, and how far past it a pan may go.
+     * Default 24. With `controls` on, the side the control stack would cover
+     * (right or bottom, whichever costs the fit less) is widened to clear it.
+     */
     fitPadding?: number;
+    /**
+     * Where fitted content sits vertically when it is shorter than the
+     * viewport: `center` (default), or `top` — pinned under the top padding,
+     * as a phone shows a plan.
+     */
+    fitAlign?: "center" | "top";
     /** Render the + / − / Fit controls. Default true. */
     controls?: boolean;
     /** Called with every transform — gestures included, so keep it cheap. */

package/dist/components/pan-zoom-viewport.js

@@ -12,12 +12,21 @@ var DRAG_THRESHOLD = 4;
 var MAX_WHEEL_ZOOM_DELTA = 25;
 var WHEEL_ZOOM_SPEED = 0.01;
 var EPSILON = 1e-3;
+var CONTROLS_RESERVE_X = 12 + 44 + 8;
+var CONTROLS_RESERVE_Y = 12 + 130 + 8;
 function clamp(value, min, max) {
   return Math.min(max, Math.max(min, value));
 }
-function clampAxis(offset, content, viewport, pad) {
-  if (content + pad * 2 <= viewport) return (viewport - content) / 2;
-  return clamp(offset, viewport - content - pad, pad);
+function clampAxis(offset, content, viewport, start, end, align) {
+  const room = viewport - start - end;
+  if (content <= room) return align === "start" ? start : start + (room - content) / 2;
+  return clamp(offset, viewport - content - end, start);
+}
+function fitScale(viewport, insets, contentWidth, contentHeight) {
+  return Math.min(
+    (viewport.width - insets.left - insets.right) / contentWidth,
+    (viewport.height - insets.top - insets.bottom) / contentHeight
+  );
 }
 function distance(a, b) {
   return Math.hypot(a.x - b.x, a.y - b.y);
@@ -40,6 +49,7 @@ var PanZoomViewport = React.forwardRef(
       zoomStep = 1.25,
       panStep = 48,
       fitPadding = 24,
+      fitAlign = "center",
       controls = true,
       onTransformChange,
       apiRef,
@@ -55,6 +65,7 @@ var PanZoomViewport = React.forwardRef(
       "zoomStep",
       "panStep",
       "fitPadding",
+      "fitAlign",
       "controls",
       "onTransformChange",
       "apiRef",
@@ -79,26 +90,37 @@ var PanZoomViewport = React.forwardRef(
       onTransformChangeRef.current = onTransformChange;
       zoomLevelRef.current = labels.zoomLevel;
     });
+    const insets = React.useMemo(() => {
+      const base = { top: fitPadding, right: fitPadding, bottom: fitPadding, left: fitPadding };
+      if (!controls || !viewport) return base;
+      const right = __spreadProps(__spreadValues({}, base), { right: Math.max(fitPadding, CONTROLS_RESERVE_X) });
+      const bottom = __spreadProps(__spreadValues({}, base), { bottom: Math.max(fitPadding, CONTROLS_RESERVE_Y) });
+      return fitScale(viewport, bottom, contentWidth, contentHeight) > fitScale(viewport, right, contentWidth, contentHeight) ? bottom : right;
+    }, [controls, viewport, fitPadding, contentWidth, contentHeight]);
     const clampTransform = React.useCallback(
       (next) => {
         if (!viewport || viewport.width <= 0 || viewport.height <= 0) return next;
         const scale = clamp(next.scale, minScale, maxScale);
         return {
           scale,
-          x: clampAxis(next.x, contentWidth * scale, viewport.width, fitPadding),
-          y: clampAxis(next.y, contentHeight * scale, viewport.height, fitPadding)
+          x: clampAxis(next.x, contentWidth * scale, viewport.width, insets.left, insets.right, "center"),
+          y: clampAxis(
+            next.y,
+            contentHeight * scale,
+            viewport.height,
+            insets.top,
+            insets.bottom,
+            fitAlign === "top" ? "start" : "center"
+          )
         };
       },
-      [viewport, minScale, maxScale, contentWidth, contentHeight, fitPadding]
+      [viewport, minScale, maxScale, contentWidth, contentHeight, insets, fitAlign]
     );
     const fitted = React.useCallback(() => {
       if (!viewport || viewport.width <= 0 || viewport.height <= 0) return null;
-      const scale = Math.min(
-        (viewport.width - fitPadding * 2) / contentWidth,
-        (viewport.height - fitPadding * 2) / contentHeight
-      );
-      return clampTransform({ scale, x: fitPadding, y: fitPadding });
-    }, [viewport, fitPadding, contentWidth, contentHeight, clampTransform]);
+      const scale = fitScale(viewport, insets, contentWidth, contentHeight);
+      return clampTransform({ scale, x: insets.left, y: insets.top });
+    }, [viewport, insets, contentWidth, contentHeight, clampTransform]);
     const commit = React.useCallback(
       (next, options) => {
         var _a2;
@@ -382,13 +404,13 @@ var PanZoomViewport = React.forwardRef(
       if (pressing.current || event.target === event.currentTarget) return;
       const bounds = event.currentTarget.getBoundingClientRect();
       const rect = event.target.getBoundingClientRect();
-      const margin = fitPadding;
       let dx = 0;
       let dy = 0;
-      if (rect.left < bounds.left + margin) dx = bounds.left + margin - rect.left;
-      else if (rect.right > bounds.right - margin) dx = bounds.right - margin - rect.right;
-      if (rect.top < bounds.top + margin) dy = bounds.top + margin - rect.top;
-      else if (rect.bottom > bounds.bottom - margin) dy = bounds.bottom - margin - rect.bottom;
+      if (rect.left < bounds.left + insets.left) dx = bounds.left + insets.left - rect.left;
+      else if (rect.right > bounds.right - insets.right) dx = bounds.right - insets.right - rect.right;
+      if (rect.top < bounds.top + insets.top) dy = bounds.top + insets.top - rect.top;
+      else if (rect.bottom > bounds.bottom - insets.bottom)
+        dy = bounds.bottom - insets.bottom - rect.bottom;
       if (dx !== 0 || dy !== 0) panBy(dx, dy);
     };
     const scaledWidth = contentWidth * transform.scale;
@@ -479,14 +501,14 @@ var PanZoomViewport = React.forwardRef(
               orientation: "vertical",
               "aria-label": labels.controls,
               "data-slot": "pan-zoom-viewport-controls",
-              className: "absolute bottom-3 right-3 rounded-xl bg-card shadow-sm",
+              className: "absolute bottom-3 right-3 rounded-xl bg-card shadow-[var(--shadow-card)]",
               children: [
                 /* @__PURE__ */ jsx(
                   Button,
                   {
                     type: "button",
                     variant: "outline",
-                    size: "icon-sm",
+                    size: "icon",
                     "aria-label": labels.zoomIn,
                     disabled: atMax,
                     onClick: zoomIn,
@@ -498,7 +520,7 @@ var PanZoomViewport = React.forwardRef(
                   {
                     type: "button",
                     variant: "outline",
-                    size: "icon-sm",
+                    size: "icon",
                     "aria-label": labels.zoomOut,
                     disabled: atMin,
                     onClick: zoomOut,
@@ -510,7 +532,7 @@ var PanZoomViewport = React.forwardRef(
                   {
                     type: "button",
                     variant: "outline",
-                    size: "icon-sm",
+                    size: "icon",
                     className: "text-xs font-semibold",
                     onClick: fit,
                     children: labels.fit

package/dist/components/spinner.d.ts

@@ -4,11 +4,11 @@ import { VariantProps } from 'class-variance-authority';
 
 declare const spinnerVariants: (props?: ({
     size?: "default" | "xs" | "sm" | "lg" | "xl" | null | undefined;
-    tone?: "primary" | "default" | "inherit" | "destructive" | null | undefined;
+    tone?: "default" | "inherit" | "primary" | "destructive" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare const Spinner: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & VariantProps<(props?: ({
     size?: "default" | "xs" | "sm" | "lg" | "xl" | null | undefined;
-    tone?: "primary" | "default" | "inherit" | "destructive" | null | undefined;
+    tone?: "default" | "inherit" | "primary" | "destructive" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & {
     /** Visually-hidden label for screen readers. Defaults to "Loading". */
     label?: string;

package/dist/components/tag.d.ts

@@ -3,11 +3,11 @@ import * as React from 'react';
 import { VariantProps } from 'class-variance-authority';
 
 declare const tagVariants: (props?: ({
-    variant?: "primary" | "default" | "success" | "warning" | "destructive" | "outline" | "quiet" | null | undefined;
+    variant?: "default" | "primary" | "success" | "warning" | "destructive" | "outline" | "quiet" | null | undefined;
     size?: "default" | "sm" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare const Tag: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & VariantProps<(props?: ({
-    variant?: "primary" | "default" | "success" | "warning" | "destructive" | "outline" | "quiet" | null | undefined;
+    variant?: "default" | "primary" | "success" | "warning" | "destructive" | "outline" | "quiet" | null | undefined;
     size?: "default" | "sm" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string> & {
     onRemove?: () => void;

package/dist/components/text.d.ts

@@ -22,8 +22,8 @@ import { VariantProps } from 'class-variance-authority';
  * Weights are 400 / 600 / 700. 500 is not in the system.
  */
 declare const textVariants: (props?: ({
-    variant?: "small" | "body" | "display" | "h2" | "h3" | "label" | "caption" | "h1" | "h4" | "body-lg" | "body-sm" | "overline" | null | undefined;
-    color?: "primary" | "default" | "inherit" | "destructive" | "muted" | "primary-foreground" | null | undefined;
+    variant?: "body" | "small" | "display" | "h2" | "h3" | "label" | "caption" | "h1" | "h4" | "body-lg" | "body-sm" | "overline" | null | undefined;
+    color?: "default" | "inherit" | "primary" | "destructive" | "muted" | "primary-foreground" | null | undefined;
     weight?: "bold" | "medium" | "normal" | "semibold" | null | undefined;
     leading?: "none" | "normal" | "tight" | "snug" | "relaxed" | "loose" | null | undefined;
     tracking?: "normal" | "tight" | "wide" | "wider" | null | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bearmenu/ui",
-  "version": "0.8.37",
+  "version": "0.8.38",
   "description": "BearMenu design system — shared UI tokens, primitives, and components",
   "license": "UNLICENSED",
   "repository": {

package/src/components/pan-zoom-viewport.stories.tsx

@@ -60,7 +60,7 @@ const meta: Meta<typeof PanZoomViewport> = {
     docs: {
       description: {
         component:
-          "A window onto a plan that pans and zooms: drag, pinch, trackpad pinch or ctrl-wheel, arrows / + / − / 0 on the focused viewport, and the + / − / Fit controls. Fit never goes below `minScale`; past the floor the plan anchors top-left and the edges it runs past are shaded. Every string is injected through `labels`.",
+          "A window onto a plan that pans and zooms: drag, pinch, trackpad pinch or ctrl-wheel, arrows / + / − / 0 on the focused viewport, and the + / − / Fit controls (44px each, on a raised card inset 12px; Fit keeps the plan clear of them). `fitAlign=\"top\"` pins a short plan to the top. Fit never goes below `minScale`; past the floor the plan anchors top-left and the edges it runs past are shaded. Every string is injected through `labels`.",
       },
     },
   },
@@ -104,6 +104,26 @@ export const PhoneAtTheFloor: Story = {
   ),
 };
 
+/**
+ * floor/07-f0 phone, pinned to the top: `fitAlign="top"` holds a plan shorter
+ * than the viewport under the top padding instead of centring it. The controls
+ * float 12px in on a raised card, 44px per button, and the fit keeps clear of them.
+ */
+export const PhonePinnedTop: Story = {
+  render: () => (
+    <PanZoomViewport
+      contentWidth={1200}
+      contentHeight={800}
+      minScale={0.25}
+      fitAlign="top"
+      labels={labels}
+      className="h-[640px] w-[390px] border-y border-border bg-background"
+    >
+      <DemoPlan />
+    </PanZoomViewport>
+  ),
+};
+
 /** Driving it from outside: a "Show T12" link, a reset. */
 export const Imperative: Story = {
   render: () => {

package/src/components/pan-zoom-viewport.test.tsx

@@ -85,14 +85,34 @@ function renderOnAPhone(props: Partial<PanZoomViewportProps> = {}) {
 describe("PanZoomViewport", () => {
   describe("fit", () => {
     it("fits the content inside its padding and centres it", () => {
-      renderViewport();
+      renderViewport({ controls: false });
       // min((800 - 48) / 400, (600 - 48) / 300) = 1.84 → 736 × 552.
       expect(transformOf()).toEqual({ x: 32, y: 24, scale: 1.84 });
       expect(content()).not.toHaveClass("invisible");
     });
 
+    it("keeps the fitted content clear of the controls, on the side that costs least", () => {
+      renderViewport();
+      // Right side widened to 64: min((800 - 88) / 400, (600 - 48) / 300) = 1.78
+      // → 712 × 534. Widening the bottom to 150 would cost more: 426 / 300 = 1.42.
+      // Its right edge lands at 736, 64 in: past the 12px inset and the 44px stack.
+      expect(transformOf()).toEqual({ x: 24, y: 33, scale: 1.78 });
+    });
+
+    it("widens the bottom instead when that leaves the bigger fit", () => {
+      viewportSize = { width: 400, height: 800 };
+      renderViewport({ contentWidth: 400, contentHeight: 300 });
+      // Bottom: min(352 / 400, 626 / 300) = 0.88. Right: 312 / 400 = 0.78.
+      expect(transformOf()).toEqual({ x: 24, y: 24 + (626 - 264) / 2, scale: 0.88 });
+    });
+
+    it("pins fitted content to the top with fitAlign top", () => {
+      renderViewport({ fitAlign: "top" });
+      expect(transformOf()).toEqual({ x: 24, y: 24, scale: 1.78 });
+    });
+
     it("stops at the floor, anchors top-left and shades the edge that runs on", () => {
-      renderOnAPhone();
+      renderOnAPhone({ controls: false });
       // The fit would be 0.285; the floor holds it at 0.5 → 600 × 400.
       // Too wide: anchored at the padding. Short enough: centred.
       expect(transformOf()).toEqual({ x: 24, y: 50, scale: 0.5 });
@@ -102,6 +122,17 @@ describe("PanZoomViewport", () => {
       expect(edgeVisible("bottom")).toBe(false);
     });
 
+    it("lets a plan under the controls pan clear of them", () => {
+      renderOnAPhone();
+      // Bottom widened to 150 (the smaller loss here): 400 tall no longer fits
+      // the 326 left, so it anchors at the top and may pan up by 74.
+      expect(transformOf()).toEqual({ x: 24, y: 24, scale: 0.5 });
+      expect(edgeVisible("bottom")).toBe(false);
+      surface().focus();
+      fireEvent.keyDown(surface(), { key: "ArrowDown", shiftKey: true });
+      expect(transformOf().y).toBe(500 - 400 - 150);
+    });
+
     it("never fits above the ceiling", () => {
       renderViewport({ contentWidth: 100, contentHeight: 100, maxScale: 2 });
       expect(transformOf().scale).toBe(2);
@@ -112,10 +143,22 @@ describe("PanZoomViewport", () => {
     it("zooms in and out by one step about the centre", async () => {
       renderViewport();
       await userEvent.click(screen.getByRole("button", { name: "Zoom out" }));
-      // 1.84 / 1.25 = 1.472 → 588.8 × 441.6, centred.
-      expect(transformOf()).toEqual({ x: 105.6, y: 79.2, scale: 1.472 });
+      // 1.78 / 1.25 = 1.424 → 569.6 × 427.2, centred between the paddings.
+      expect(transformOf()).toEqual({ x: 95.2, y: 86.4, scale: 1.424 });
       await userEvent.click(screen.getByRole("button", { name: "Zoom in" }));
-      expect(transformOf().scale).toBe(1.84);
+      expect(transformOf().scale).toBe(1.78);
+    });
+
+    it("gives every control a 44px hit area on a raised card", () => {
+      renderViewport();
+      for (const name of ["Zoom in", "Zoom out", "Fit"]) {
+        expect(screen.getByRole("button", { name })).toHaveClass("h-11", "w-11");
+      }
+      expect(screen.getByRole("group", { name: "Zoom" })).toHaveClass(
+        "bottom-3",
+        "right-3",
+        "shadow-[var(--shadow-card)]"
+      );
     });
 
     it("disables zoom out at the floor and zoom in at the ceiling", async () => {
@@ -175,7 +218,7 @@ describe("PanZoomViewport", () => {
     });
 
     it("zooms with + and -, and fits with 0", async () => {
-      renderViewport();
+      renderViewport({ controls: false });
       surface().focus();
       await userEvent.keyboard("+");
       expect(transformOf().scale).toBe(2.3);
@@ -195,7 +238,7 @@ describe("PanZoomViewport", () => {
     });
 
     it("announces the zoom level through the injected formatter", async () => {
-      renderViewport();
+      renderViewport({ controls: false });
       surface().focus();
       await userEvent.keyboard("+");
       expect(screen.getByText("230%")).toBeInTheDocument();
@@ -281,7 +324,7 @@ describe("PanZoomViewport", () => {
     });
 
     it("zooms with a two-finger pinch about the fingers", () => {
-      renderViewport();
+      renderViewport({ controls: false });
       const touch = (id: number, x: number, y: number) => ({
         pointerId: id,
         pointerType: "touch",
@@ -316,7 +359,7 @@ describe("PanZoomViewport", () => {
     });
 
     it("caps one ctrl-wheel notch so a mouse wheel does not jump", () => {
-      renderViewport({ maxScale: 10 });
+      renderViewport({ maxScale: 10, controls: false });
       wheel({ deltaY: -100, ctrlKey: true, clientX: 400, clientY: 300 });
       expect(transformOf().scale).toBeCloseTo(1.84 * Math.exp(0.25), 2);
     });
@@ -339,7 +382,7 @@ describe("PanZoomViewport", () => {
     it("drives the view from outside and reports every transform", () => {
       const api = React.createRef<PanZoomViewportHandle>();
       const onTransformChange = vi.fn();
-      renderOnAPhone({ apiRef: api, onTransformChange });
+      renderOnAPhone({ apiRef: api, onTransformChange, controls: false });
       expect(onTransformChange).toHaveBeenLastCalledWith({ scale: 0.5, x: 24, y: 50 });
 
       act(() => api.current?.centerOn(1000, 400));
@@ -355,9 +398,9 @@ describe("PanZoomViewport", () => {
     });
 
     it("refits when the plan changes size", () => {
-      const view = renderViewport();
+      const view = renderViewport({ controls: false });
       view.rerender(
-        <PanZoomViewport contentWidth={800} contentHeight={600} labels={labels}>
+        <PanZoomViewport contentWidth={800} contentHeight={600} labels={labels} controls={false}>
           <button type="button">T1</button>
         </PanZoomViewport>
       );
@@ -366,11 +409,17 @@ describe("PanZoomViewport", () => {
     });
 
     it("keeps a panned view, pulled inside the bounds, when the plan changes", async () => {
-      const view = renderOnAPhone();
+      const view = renderOnAPhone({ controls: false });
       surface().focus();
       await userEvent.keyboard("{Shift>}{ArrowRight}{/Shift}");
       view.rerender(
-        <PanZoomViewport contentWidth={700} contentHeight={800} minScale={0.5} labels={labels}>
+        <PanZoomViewport
+          contentWidth={700}
+          contentHeight={800}
+          minScale={0.5}
+          labels={labels}
+          controls={false}
+        >
           <button type="button">T1</button>
         </PanZoomViewport>
       );

package/src/components/pan-zoom-viewport.tsx

@@ -29,7 +29,9 @@ import { ButtonGroup } from "./button-group";
  * - Keyboard, with the viewport focused: arrows pan (Shift for four times the
  *   step); `+` / `-` zoom and `0` fits, from anywhere inside it. Tabbing onto
  *   a table that sits off screen pans it into view.
- * - The + / − / Fit controls, bottom right.
+ * - The + / − / Fit controls: a raised card 12px in from the bottom-right
+ *   corner, 44 × 44 per button. Fit and the pan bounds keep the content clear
+ *   of them.
  *
  * The min-scale floor: `Fit` never shrinks below `minScale`. On a phone the
  * plan would otherwise fit at a size no finger can hit, so below the floor it
@@ -106,8 +108,18 @@ export type PanZoomViewportProps = Omit<React.HTMLAttributes<HTMLDivElement>, "c
   zoomStep?: number;
   /** One arrow press, in viewport px. Default 48. */
   panStep?: number;
-  /** The air Fit leaves around the content, and how far past it a pan may go. Default 24. */
+  /**
+   * The air Fit leaves around the content, and how far past it a pan may go.
+   * Default 24. With `controls` on, the side the control stack would cover
+   * (right or bottom, whichever costs the fit less) is widened to clear it.
+   */
   fitPadding?: number;
+  /**
+   * Where fitted content sits vertically when it is shorter than the
+   * viewport: `center` (default), or `top` — pinned under the top padding,
+   * as a phone shows a plan.
+   */
+  fitAlign?: "center" | "top";
   /** Render the + / − / Fit controls. Default true. */
   controls?: boolean;
   /** Called with every transform — gestures included, so keep it cheap. */
@@ -120,6 +132,7 @@ export type PanZoomViewportProps = Omit<React.HTMLAttributes<HTMLDivElement>, "c
 
 type Size = { width: number; height: number };
 type Point = { x: number; y: number };
+type Insets = { top: number; right: number; bottom: number; left: number };
 
 type Gesture =
   | { kind: "idle" }
@@ -136,19 +149,40 @@ const DRAG_THRESHOLD = 4;
 const MAX_WHEEL_ZOOM_DELTA = 25;
 const WHEEL_ZOOM_SPEED = 0.01;
 const EPSILON = 0.001;
+/**
+ * The control stack's footprint plus air: `bottom-3 right-3` (12px), three
+ * 44px buttons sharing borders (44 × 130), and 8px before the content.
+ */
+const CONTROLS_RESERVE_X = 12 + 44 + 8;
+const CONTROLS_RESERVE_Y = 12 + 130 + 8;
 
 function clamp(value: number, min: number, max: number) {
   return Math.min(max, Math.max(min, value));
 }
 
 /**
- * One axis. Content that fits (with its padding) is centred and cannot move;
- * content that does not may pan until its far edge is `pad` inside the
- * viewport's, and no further.
+ * One axis. Content that fits between its paddings is centred between them
+ * (or held at the start one) and cannot move; content that does not may pan
+ * until its far edge is `end` inside the viewport's, and no further.
  */
-function clampAxis(offset: number, content: number, viewport: number, pad: number) {
-  if (content + pad * 2 <= viewport) return (viewport - content) / 2;
-  return clamp(offset, viewport - content - pad, pad);
+function clampAxis(
+  offset: number,
+  content: number,
+  viewport: number,
+  start: number,
+  end: number,
+  align: "center" | "start"
+) {
+  const room = viewport - start - end;
+  if (content <= room) return align === "start" ? start : start + (room - content) / 2;
+  return clamp(offset, viewport - content - end, start);
+}
+
+function fitScale(viewport: Size, insets: Insets, contentWidth: number, contentHeight: number) {
+  return Math.min(
+    (viewport.width - insets.left - insets.right) / contentWidth,
+    (viewport.height - insets.top - insets.bottom) / contentHeight
+  );
 }
 
 function distance(a: Point, b: Point) {
@@ -178,6 +212,7 @@ const PanZoomViewport = React.forwardRef<HTMLDivElement, PanZoomViewportProps>(
       zoomStep = 1.25,
       panStep = 48,
       fitPadding = 24,
+      fitAlign = "center",
       controls = true,
       onTransformChange,
       apiRef,
@@ -211,29 +246,47 @@ const PanZoomViewport = React.forwardRef<HTMLDivElement, PanZoomViewportProps>(
       zoomLevelRef.current = labels.zoomLevel;
     });
 
+    // The padding on each side. The control stack covers the bottom-right
+    // corner: keep the content clear of it by widening the right side or the
+    // bottom one — whichever leaves the bigger fit.
+    const insets = React.useMemo((): Insets => {
+      const base = { top: fitPadding, right: fitPadding, bottom: fitPadding, left: fitPadding };
+      if (!controls || !viewport) return base;
+      const right = { ...base, right: Math.max(fitPadding, CONTROLS_RESERVE_X) };
+      const bottom = { ...base, bottom: Math.max(fitPadding, CONTROLS_RESERVE_Y) };
+      return fitScale(viewport, bottom, contentWidth, contentHeight) >
+        fitScale(viewport, right, contentWidth, contentHeight)
+        ? bottom
+        : right;
+    }, [controls, viewport, fitPadding, contentWidth, contentHeight]);
+
     const clampTransform = React.useCallback(
       (next: PanZoomTransform): PanZoomTransform => {
         if (!viewport || viewport.width <= 0 || viewport.height <= 0) return next;
         const scale = clamp(next.scale, minScale, maxScale);
         return {
           scale,
-          x: clampAxis(next.x, contentWidth * scale, viewport.width, fitPadding),
-          y: clampAxis(next.y, contentHeight * scale, viewport.height, fitPadding),
+          x: clampAxis(next.x, contentWidth * scale, viewport.width, insets.left, insets.right, "center"),
+          y: clampAxis(
+            next.y,
+            contentHeight * scale,
+            viewport.height,
+            insets.top,
+            insets.bottom,
+            fitAlign === "top" ? "start" : "center"
+          ),
         };
       },
-      [viewport, minScale, maxScale, contentWidth, contentHeight, fitPadding]
+      [viewport, minScale, maxScale, contentWidth, contentHeight, insets, fitAlign]
     );
 
     const fitted = React.useCallback((): PanZoomTransform | null => {
       if (!viewport || viewport.width <= 0 || viewport.height <= 0) return null;
-      const scale = Math.min(
-        (viewport.width - fitPadding * 2) / contentWidth,
-        (viewport.height - fitPadding * 2) / contentHeight
-      );
+      const scale = fitScale(viewport, insets, contentWidth, contentHeight);
       // Start from the padded top-left: content under the floor overflows and
-      // stays anchored there; content that fits is centred by the clamp.
-      return clampTransform({ scale, x: fitPadding, y: fitPadding });
-    }, [viewport, fitPadding, contentWidth, contentHeight, clampTransform]);
+      // stays anchored there; content that fits is placed by the clamp.
+      return clampTransform({ scale, x: insets.left, y: insets.top });
+    }, [viewport, insets, contentWidth, contentHeight, clampTransform]);
 
     const commit = React.useCallback(
       (
@@ -574,13 +627,13 @@ const PanZoomViewport = React.forwardRef<HTMLDivElement, PanZoomViewportProps>(
       if (pressing.current || event.target === event.currentTarget) return;
       const bounds = event.currentTarget.getBoundingClientRect();
       const rect = event.target.getBoundingClientRect();
-      const margin = fitPadding;
       let dx = 0;
       let dy = 0;
-      if (rect.left < bounds.left + margin) dx = bounds.left + margin - rect.left;
-      else if (rect.right > bounds.right - margin) dx = bounds.right - margin - rect.right;
-      if (rect.top < bounds.top + margin) dy = bounds.top + margin - rect.top;
-      else if (rect.bottom > bounds.bottom - margin) dy = bounds.bottom - margin - rect.bottom;
+      if (rect.left < bounds.left + insets.left) dx = bounds.left + insets.left - rect.left;
+      else if (rect.right > bounds.right - insets.right) dx = bounds.right - insets.right - rect.right;
+      if (rect.top < bounds.top + insets.top) dy = bounds.top + insets.top - rect.top;
+      else if (rect.bottom > bounds.bottom - insets.bottom)
+        dy = bounds.bottom - insets.bottom - rect.bottom;
       if (dx !== 0 || dy !== 0) panBy(dx, dy);
     };
 
@@ -674,12 +727,14 @@ const PanZoomViewport = React.forwardRef<HTMLDivElement, PanZoomViewportProps>(
             orientation="vertical"
             aria-label={labels.controls}
             data-slot="pan-zoom-viewport-controls"
-            className="absolute bottom-3 right-3 rounded-xl bg-card shadow-sm"
+            // A raised card floating 12px in. The DS's default icon size, so
+            // every hit area is 44 × 44 at any width.
+            className="absolute bottom-3 right-3 rounded-xl bg-card shadow-[var(--shadow-card)]"
           >
             <Button
               type="button"
               variant="outline"
-              size="icon-sm"
+              size="icon"
               aria-label={labels.zoomIn}
               disabled={atMax}
               onClick={zoomIn}
@@ -689,7 +744,7 @@ const PanZoomViewport = React.forwardRef<HTMLDivElement, PanZoomViewportProps>(
             <Button
               type="button"
               variant="outline"
-              size="icon-sm"
+              size="icon"
               aria-label={labels.zoomOut}
               disabled={atMin}
               onClick={zoomOut}
@@ -699,7 +754,7 @@ const PanZoomViewport = React.forwardRef<HTMLDivElement, PanZoomViewportProps>(
             <Button
               type="button"
               variant="outline"
-              size="icon-sm"
+              size="icon"
               className="text-xs font-semibold"
               onClick={fit}
             >