feat(minimap): preview and wrapper customization; expand Storybook examples

MiniMap: add previewStyle, wrapperClassName, and previewClassName; apply wrapper transforms via explicit style properties; stop spreading outer props onto the inner wrapper div.

Stories: add axis-lock, image-annotations, initial-transform, medical-viewer, stadium, velocity, and keep-scale map examples; refresh existing examples; shared viewer styles and controls utilities; replace miro image asset with inline example; update minimap tests and Storybook preview.
Made-with: Cursor

Author: prc5

.storybook/preview.tsx

@@ -15,6 +15,7 @@ const preview: Preview = {
         order: [
           "Docs",
           "Basic",
+          ["Image", "*"],
           "Advanced",
           "Components",
           "Examples",

__tests__/features/minimap/minimap.rendering.spec.tsx

@@ -62,11 +62,12 @@ describe("MiniMap [Rendering]", () => {
   });
 
   describe("preview styles", () => {
-    it("should have red border by default", () => {
+    it("should use default red border on preview", () => {
       renderMiniMap();
       const preview = document.querySelector(
         ".rzpp-minimap-preview",
       ) as HTMLElement;
+      expect(preview.style.border).toBe("3px solid red");
       expect(preview.style.borderColor).toBe("red");
     });
 
@@ -78,6 +79,17 @@ describe("MiniMap [Rendering]", () => {
       expect(preview.style.borderColor).toBe("blue");
     });
 
+    it("should merge previewStyle after defaults", () => {
+      renderMiniMap({
+        previewStyle: { borderRadius: "8px", border: "1px solid lime" },
+      });
+      const preview = document.querySelector(
+        ".rzpp-minimap-preview",
+      ) as HTMLElement;
+      expect(preview.style.borderRadius).toBe("8px");
+      expect(preview.style.border).toBe("1px solid lime");
+    });
+
     it("should have box-shadow for viewport dimming", () => {
       renderMiniMap();
       const preview = document.querySelector(

src/components/mini-map/mini-map.tsx

@@ -21,6 +21,12 @@ export type MiniMapProps = {
   width?: number;
   height?: number;
   borderColor?: string;
+  /** Merged onto the viewport indicator (`.rzpp-minimap-preview`). */
+  previewStyle?: React.CSSProperties;
+  /** Extra class name(s) appended to `.rzpp-minimap-wrapper`. */
+  wrapperClassName?: string;
+  /** Extra class name(s) appended to `.rzpp-minimap-preview`. */
+  previewClassName?: string;
   panning?: boolean;
 } & React.DetailedHTMLProps<
   React.HTMLAttributes<HTMLDivElement>,
@@ -43,6 +49,9 @@ export const MiniMap: React.FC<MiniMapProps> = ({
   width = 200,
   height = 200,
   borderColor = "red",
+  previewStyle,
+  wrapperClassName,
+  previewClassName,
   children,
   panning = true,
   ...rest
@@ -116,11 +125,14 @@ export const MiniMap: React.FC<MiniMapProps> = ({
       // overflow: "hidden",
     } as const;
 
-    Object.keys(style).forEach((key) => {
-      if (wrapperRef.current) {
-        wrapperRef.current.style[key] = style[key];
-      }
-    });
+    if (wrapperRef.current) {
+      const el = wrapperRef.current.style;
+      el.transform = style.transform;
+      el.transformOrigin = style.transformOrigin;
+      el.position = style.position;
+      el.boxSizing = style.boxSizing;
+      el.zIndex = String(style.zIndex);
+    }
   };
 
   const transformMiniMap = () => {
@@ -261,20 +273,19 @@ export const MiniMap: React.FC<MiniMapProps> = ({
       {...rest}
       ref={mainRef}
       style={wrapperStyle}
-      className={`rzpp-mini-map ${rest.className || ""}`}
+      className={`rzpp-mini-map ${rest.className || ""}`.trim()}
     >
       <div
-        {...rest}
         style={{ pointerEvents: "none" }}
         ref={wrapperRef}
-        className="rzpp-minimap-wrapper"
+        className={`rzpp-minimap-wrapper ${wrapperClassName || ""}`.trim()}
       >
         {children}
       </div>
       <div
-        className="rzpp-minimap-preview"
+        className={`rzpp-minimap-preview ${previewClassName || ""}`.trim()}
         ref={previewRef}
-        style={{ ...previewStyles, borderColor }}
+        style={{ ...previewStyles, borderColor, ...previewStyle }}
       />
     </div>
   );

src/stories/examples/axis-lock/axis-lock.stories.mdx

@@ -0,0 +1,35 @@
+import { Meta, Story, ArgsTable, Canvas } from "@storybook/blocks";
+
+import { TransformWrapper } from "../../../components";
+import { argsTypes } from "../../types/args.types.ts";
+import { Example } from "./example";
+
+export const Template = (args) => <Example {...args} />;
+
+<Meta
+  title="Basic/Axis lock"
+  component={TransformWrapper}
+  argTypes={argsTypes}
+/>
+
+# Axis lock
+
+Use **`panning.lockAxisX`** and **`panning.lockAxisY`** when the viewport should
+only move along one axis — for example a **timeline** (horizontal only) or a
+**tall document strip** (vertical only).
+
+- **`lockAxisX: true`** — horizontal panning is disabled; drag and trackpad pan
+  move the content **vertically** only.
+- **`lockAxisY: true`** — vertical panning is disabled; movement is **horizontal**
+  only.
+
+The buttons above the canvas switch the demo between **free** panning and each
+locked mode. Use the control bar to reset or re-center if you get lost.
+
+<Canvas>
+  <Story name="Axis lock">{(args) => <Template {...args} />}</Story>
+</Canvas>
+
+## Component API
+
+<ArgsTable story="Axis lock" />

src/stories/examples/axis-lock/example.tsx

@@ -0,0 +1,127 @@
+import React, { useMemo, useState } from "react";
+
+import { TransformWrapper, TransformComponent } from "../../../components";
+import {
+  Controls,
+  normalizeArgs,
+  viewerChrome,
+  FreeMovementIcon,
+  LockVerticalIcon,
+  LockHorizontalIcon,
+} from "../../utils";
+
+type AxisMode = "free" | "vertical" | "horizontal";
+
+const viewer: React.CSSProperties = {
+  ...viewerChrome,
+  width: "560px",
+  height: "440px",
+  maxWidth: "90vw",
+  maxHeight: "78vh",
+};
+
+const font = "system-ui, -apple-system, sans-serif";
+
+function GridCanvas() {
+  const cells = useMemo(() => {
+    const out: { key: string; row: number; col: number }[] = [];
+    for (let row = 0; row < 6; row += 1) {
+      for (let col = 0; col < 8; col += 1) {
+        out.push({ key: `${row}-${col}`, row, col });
+      }
+    }
+    return out;
+  }, []);
+
+  return (
+    <div
+      style={{
+        width: 1400,
+        height: 900,
+        display: "grid",
+        gridTemplateColumns: "repeat(8, 1fr)",
+        gridTemplateRows: "repeat(6, 1fr)",
+        gap: 3,
+        padding: 24,
+        boxSizing: "border-box",
+        background:
+          "linear-gradient(145deg, #12122a 0%, #0d1528 40%, #0a1020 100%)",
+      }}
+    >
+      {cells.map(({ key, row, col }) => (
+        <div
+          key={key}
+          style={{
+            borderRadius: 10,
+            background: `rgba(${40 + col * 18}, ${60 + row * 12}, ${120 + (row + col) * 8}, 0.35)`,
+            border: "1px solid rgba(255,255,255,0.06)",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            fontFamily: font,
+            fontSize: 13,
+            fontWeight: 600,
+            color: "rgba(255,255,255,0.45)",
+          }}
+        >
+          {col + 1},{row + 1}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function axisButtons(
+  mode: AxisMode,
+  setMode: (m: AxisMode) => void,
+) {
+  const btn = (
+    id: AxisMode,
+    label: string,
+    Icon: React.FC,
+  ) => ({
+    label,
+    icon: <Icon />,
+    onClick: () => setMode(mode === id ? "free" : id),
+    active: mode === id,
+    "data-tooltip": label,
+  });
+
+  return [
+    btn("free", "Free pan", FreeMovementIcon),
+    btn("vertical", "Vertical only", LockVerticalIcon),
+    btn("horizontal", "Horizontal only", LockHorizontalIcon),
+  ];
+}
+
+export const Example: React.FC<Record<string, unknown>> = (args) => {
+  const normalized = normalizeArgs(args);
+  const [mode, setMode] = useState<AxisMode>("free");
+
+  const panning = {
+    ...normalized.panning,
+    lockAxisX: mode === "vertical",
+    lockAxisY: mode === "horizontal",
+  };
+
+  return (
+    <div style={{ fontFamily: font }}>
+      <TransformWrapper {...normalized} centerOnInit panning={panning}>
+        {(utils) => (
+          <div style={{ position: "relative", display: "inline-block" }}>
+            <Controls
+              {...utils}
+              extraButtons={axisButtons(mode, setMode)}
+            />
+            <TransformComponent
+              wrapperStyle={viewer}
+              contentStyle={{ width: 1400, height: 900 }}
+            >
+              <GridCanvas />
+            </TransformComponent>
+          </div>
+        )}
+      </TransformWrapper>
+    </div>
+  );
+};

src/stories/examples/bounds/bounds.stories.mdx

@@ -2,7 +2,7 @@ import { Meta, Story, ArgsTable, Canvas } from "@storybook/blocks";
 
 import { TransformWrapper, TransformComponent } from "../../../components";
 import { argsTypes } from "../../types/args.types.ts";
-import { normalizeArgs, BoundsOverlay } from "../../utils";
+import { normalizeArgs, BoundsOverlay, viewerChrome } from "../../utils";
 import { BoundsContent, contentSize } from "./bounds.data";
 
 export const minX = -(contentSize - 500);
@@ -22,14 +22,11 @@ export const Template = (args) => (
       <div style={{ position: "relative", display: "inline-block" }}>
         <TransformComponent
           wrapperStyle={{
+            ...viewerChrome,
             width: "500px",
             height: "500px",
             maxWidth: "80vw",
             maxHeight: "80vh",
-            borderRadius: "12px",
-            border: "2px solid #333",
-            boxShadow: "0 8px 32px rgba(0, 0, 0, 0.3)",
-            background: "#0f0f1a",
           }}
         >
           <BoundsContent />

src/stories/examples/cinema/example.tsx

@@ -1,7 +1,7 @@
 import React, { useState, useRef } from "react";
 
 import { TransformWrapper, TransformComponent } from "../../../components";
-import { normalizeArgs, Controls } from "../../utils";
+import { normalizeArgs, Controls, CloseIcon, viewerChrome } from "../../utils";
 import {
   CinemaLayout,
   CATEGORY_STYLES,
@@ -48,16 +48,15 @@ export const Example: React.FC<any> = (args: any) => {
           apiRef.current = api;
           return (
             <>
-              <Controls {...api} extraButtons={selectedSeat ? [{ label: "Deselect", onClick: handleReset }] : []} />
+              <Controls {...api} extraButtons={selectedSeat ? [{ label: "Deselect seat", icon: <CloseIcon />, onClick: handleReset }] : []} />
               <SeatBadge seat={selectedSeat} />
               <TransformComponent
                 wrapperStyle={{
+                  ...viewerChrome,
                   width: "800px",
                   maxWidth: "100%",
                   height: "600px",
                   maxHeight: "70vh",
-                  borderRadius: "12px",
-                  background: "#060612",
                 }}
                 contentStyle={{
                   width: CANVAS_WIDTH,

src/stories/examples/content-rerendering/content-updating.stories.mdx

@@ -15,12 +15,15 @@ export const Template = (args) => <Example {...args} />;
 # Rerendering
 
 Proves that **frequent React re-renders** inside `TransformComponent` do not
-disrupt the current zoom or pan state. Three content blocks update on
-independent timers (1 s, 3 s, 12 s) — zoom in, pan around, and watch the
-blocks toggle without resetting your viewport.
-
-This is important for dashboards, live data feeds, or any UI where child
-components update independently of the user's zoom/pan interaction.
+disrupt the current zoom or pan state. Three regions update on independent
+timers (1 s, 3 s, 12 s). Each toggle is not a text swap — it **restructures the
+layout**: compact card vs three-column grid, sidebar split vs hero + stats +
+two-column dashboard, minimal strip vs tall stack with gallery, list rows, and
+footer. Total content height changes a lot between states.
+
+Zoom in, pan around, and watch the layout reflow without resetting your
+viewport. This matters for dashboards, live data, and any UI where structure and
+size change under the user’s feet.
 
 <Canvas>
   <Story name="Rerendering">{(args) => <Template {...args} />}</Story>