handoff-app 2.0.0-7 → 2.0.0-9

package/src/app/components/Component/Preview.tsx

@@ -1,6 +1,6 @@
 import { buildArtifactUrl } from '@handoff/artifacts/url';
 import { SlotMetadata } from '@handoff/transformers/preview/component';
-import { PageSlice } from '@handoff/transformers/preview/types';
+import { PageSlice, PreviewWidth } from '@handoff/transformers/preview/types';
 import { PreviewObject } from '@handoff/types/preview';
 import { Types as CoreTypes } from 'handoff-core';
 import type { TypeNode, TypeNodeProperty } from 'handoff-docgen';
@@ -12,6 +12,8 @@ import {
   CircleCheck,
   Component,
   File,
+  Maximize2,
+  Minimize2,
   Monitor,
   MousePointerClick,
   RefreshCcw,
@@ -39,6 +41,23 @@ const getRenderablePreviewKeys = (previews: PreviewObject['previews'] | undefine
     .filter(([, preview]) => preview.url)
     .map(([key]) => key);
 
+/** A frame longer than the card's duration-300 class, so the card rejoins the flow once it lands. */
+const COLLAPSE_MS = 340;
+
+/**
+ * Where the card is between the flow and the floating view.
+ *
+ * `entering` and `leaving` hold it at the rect it occupies in the flow, and only `full` and
+ * `leaving` transition. The geometry must never animate across the change of positioning scheme:
+ * `w-full` and the inline width are both percentages, of the viewport while fixed and of the
+ * column while static. The browser interpolates between the two, and the card jumps to the wrong
+ * width before it grows back.
+ */
+type ExpandPhase = 'collapsed' | 'entering' | 'full' | 'leaving';
+
+/** defaultHeight is hand-authored, and the stage scales it with calc(), which rejects bare numbers. */
+const toCssLength = (value: string): string => (/^\d+(\.\d+)?$/.test(value) ? `${value}px` : value);
+
 /** The inspect artifact sits beside the preview artifact under a fixed suffix. */
 const toArtifactPath = (url: string, inspect: boolean): string => (inspect ? `${url.split('.html')[0]}-inspect.html` : url);
 
@@ -64,21 +83,101 @@ export const getComponentPreviewTitle = (previewableComponent: ComponentPreview)
 export const ComponentDisplay: React.FC<{
   component: PreviewObject | undefined;
   defaultHeight?: string | undefined;
+  defaultWidth?: PreviewWidth | undefined;
   title?: string;
   onPreviewChange?: (previewUrl: string) => void;
-}> = ({ component, defaultHeight, title, onPreviewChange }) => {
+}> = ({ component, defaultHeight, defaultWidth, title, onPreviewChange }) => {
   const context = usePreviewContext();
   const ref = React.useRef<HTMLIFrameElement>(null);
+  const cardRef = React.useRef<HTMLDivElement>(null);
+  const collapseTimer = React.useRef<number | undefined>(undefined);
+  const contentObserver = React.useRef<ResizeObserver | null>(null);
+  const stageObserver = React.useRef<ResizeObserver | null>(null);
   const [height, setHeight] = React.useState('100px');
   const [previewKey, setPreviewKey] = React.useState<string | null>(null);
-  const [width, setWidth] = React.useState('1100px');
+  const [previewWidth, setPreviewWidth] = React.useState<PreviewWidth>(defaultWidth ?? 'fluid');
+  const [stageWidth, setStageWidth] = React.useState(0);
   const [inspect, setInspect] = React.useState(false);
-  const [scale, setScale] = React.useState(0.8);
+  const [phase, setPhase] = React.useState<ExpandPhase>('collapsed');
+  // top/left/width are percentages of the viewport, the same units the expanded card uses. A
+  // transition between a pixel value and a vw has nothing reliable to interpolate.
+  const [originRect, setOriginRect] = React.useState<{ top: number; left: number; width: number; height: number } | null>(null);
+
+  const expanded = phase !== 'collapsed';
+  const animates = phase === 'full' || phase === 'leaving';
 
   const renderablePreviewKeys = getRenderablePreviewKeys(component?.previews);
   const selectedPreview = previewKey ? component?.previews?.[previewKey] : undefined;
   const artifactPath = selectedPreview?.url ? toArtifactPath(selectedPreview.url, inspect) : null;
 
+  // A fluid preview takes the width the stage has, so it renders at 100% and shows the layout the
+  // reader would really get at that width. A fixed width is only scaled when it does not fit, and
+  // never scaled up: a component shown larger than it renders misrepresents the design system.
+  const renderWidth = previewWidth === 'fluid' ? stageWidth : previewWidth;
+  const scale = renderWidth > stageWidth ? stageWidth / renderWidth : 1;
+
+  // Expanding lifts the card out of the flow rather than moving it into a dialog. Moving it would
+  // remount the iframe, and the preview would reload behind the animation instead of growing with
+  // it. The card starts at the rect it already occupies, so the first frame looks identical.
+  const expand = () => {
+    const rect = cardRef.current?.getBoundingClientRect();
+    if (!rect) return;
+    window.clearTimeout(collapseTimer.current);
+    setOriginRect({
+      top: (rect.top / window.innerHeight) * 100,
+      left: (rect.left / window.innerWidth) * 100,
+      width: (rect.width / window.innerWidth) * 100,
+      height: rect.height,
+    });
+    setPhase('entering');
+    requestAnimationFrame(() => setPhase('full'));
+  };
+
+  // A timer, not transitionend: reduced motion removes the transition, and then the event that
+  // would put the card back in the flow never fires.
+  const collapse = () => {
+    setPhase('leaving');
+    window.clearTimeout(collapseTimer.current);
+    collapseTimer.current = window.setTimeout(() => setPhase('collapsed'), COLLAPSE_MS);
+  };
+
+  React.useEffect(() => {
+    if (!expanded) return;
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') collapse();
+    };
+    const pageOverflow = document.body.style.overflow;
+
+    document.addEventListener('keydown', onKeyDown);
+    document.body.style.overflow = 'hidden';
+
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      document.body.style.overflow = pageOverflow;
+    };
+  }, [expanded]);
+
+  // A fluid preview already follows the stage, so animating its width only lags behind a resize.
+  // No easing while the card moves: the target changes every frame, so each frame would restart a
+  // 0.2s ease and the stage would trail the preview inside it. The ease is for discrete changes -
+  // a new device width, a new variant.
+  const boxTransition = animates
+    ? 'none'
+    : previewWidth === 'fluid'
+      ? 'height 0.2s ease-in-out'
+      : 'width 0.2s ease-in-out, height 0.2s ease-in-out';
+
+  // A ref callback, not an effect: the stage only exists once a preview is available. A hidden tab
+  // never delivers a ResizeObserver entry, so the first width is read directly.
+  const observeStage = useCallback((stage: HTMLDivElement | null) => {
+    stageObserver.current?.disconnect();
+    if (!stage) return;
+    setStageWidth(stage.clientWidth);
+    stageObserver.current = new ResizeObserver(([entry]) => setStageWidth(entry.contentRect.width));
+    stageObserver.current.observe(stage);
+  }, []);
+
   // Generate variants from component previews only for Figma atomic components
   const localVariants = React.useMemo(() => {
     if (!component?.figmaComponentId || !component?.previews) return null;
@@ -107,25 +206,42 @@ export const ComponentDisplay: React.FC<{
     return context.variants;
   }, [component?.figmaComponentId, component?.previews, context.preview, context.variants]);
 
+  // The stage reserves the scaled height, so it needs the live content height. That height changes
+  // whenever the preview reflows - a new device width, a late font, an image - not only on load.
   const onLoad = useCallback(() => {
+    contentObserver.current?.disconnect();
+
     if (defaultHeight) {
-      setHeight(defaultHeight);
-    } else if (ref.current) {
-      if (ref.current.contentWindow.document.body) {
-        setHeight(ref.current.contentWindow.document.body.scrollHeight + 'px');
-      }
+      setHeight(toCssLength(defaultHeight));
+      return;
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [defaultHeight, ref]);
+
+    const body = ref.current?.contentWindow?.document?.body;
+    if (!body) return;
+
+    const measure = () => setHeight(body.scrollHeight + 'px');
+    measure();
+    contentObserver.current = new ResizeObserver(measure);
+    contentObserver.current.observe(body);
+  }, [defaultHeight]);
 
   React.useEffect(() => {
     onLoad();
-    window.addEventListener('resize', onLoad);
-    return () => {
-      window.removeEventListener('resize', onLoad);
-    };
   }, [onLoad]);
 
+  React.useEffect(() => {
+    setPreviewWidth(defaultWidth ?? 'fluid');
+  }, [defaultWidth]);
+
+  React.useEffect(
+    () => () => {
+      contentObserver.current?.disconnect();
+      stageObserver.current?.disconnect();
+      window.clearTimeout(collapseTimer.current);
+    },
+    []
+  );
+
   // One effect owns the selection. Split in two, the filter effect clears the selection, then
   // returns early on the next render and never restores it.
   React.useEffect(() => {
@@ -165,186 +281,261 @@ export const ComponentDisplay: React.FC<{
     );
   };
 
-  return (
-    <div className="md:flex" id="preview">
-      <div className="text-medium flex w-full flex-col items-center rounded-lg border border-gray-200 dark:border-gray-900">
-        {component?.previews && (
-          <>
-            <div className="flex w-full items-center justify-between rounded-t-lg bg-gray-50 px-6 py-2 pr-3 align-middle @container dark:bg-gray-800">
-              <div className="flex flex-1 items-start gap-2">
-                {localVariants ? (
-                  <>
-                    {Object.keys(localVariants).length > 0 && (
-                      <>
-                        <div className="flex h-8 shrink-0 items-center gap-2">
-                          <p className="font-monospace text-[11px] text-accent-foreground">{title ?? 'Variant'}</p>
-                          <Separator orientation="vertical" className="h-3" />
-                        </div>
-                        <div className="flex flex-wrap gap-2">
-                          {Object.keys(localVariants)
-                            .filter((variantProperty) => localVariants[variantProperty].length > 1)
-                            .map((variantProperty) => (
-                              <Select
-                                key={variantProperty}
-                                value={context.variantFilter ? context.variantFilter[variantProperty] : undefined}
-                                onValueChange={(value) => context.updateVariantFilter(variantProperty, value)}
-                              >
-                                <SelectTrigger className="h-8 w-[140px] border-none text-xs shadow-none">
-                                  <SelectValue placeholder={variantProperty} />
-                                </SelectTrigger>
-                                <SelectContent>
-                                  {localVariants[variantProperty].map((variantPropertyValue) => {
-                                    if (typeof variantPropertyValue !== 'string' || variantPropertyValue === '') return null;
-                                    return (
-                                      <SelectItem
-                                        key={variantPropertyValue}
-                                        value={variantPropertyValue}
-                                        disabled={!isOptionValid(variantProperty, variantPropertyValue)}
-                                      >
-                                        {variantPropertyValue}
-                                      </SelectItem>
-                                    );
-                                  })}
-                                </SelectContent>
-                              </Select>
-                            ))}
-                        </div>
-                      </>
-                    )}
-                  </>
-                ) : (
-                  <>
-                    <Select value={previewKey ?? ''} onValueChange={setPreviewKey}>
-                      <SelectTrigger className="h-8 w-[180px] border-none border-gray-200 bg-white text-xs shadow-none dark:border-gray-900">
-                        <SelectValue placeholder="Preview" />
-                      </SelectTrigger>
-                      <SelectContent>
-                        {renderablePreviewKeys.map((key) => (
-                          <SelectItem key={key} value={key}>
-                            {component.previews[key].title}
-                          </SelectItem>
-                        ))}
-                      </SelectContent>
-                    </Select>
-                  </>
-                )}
-              </div>
-              <div className=" hidden items-center gap-0 @2xl:flex">
-                <TooltipProvider delayDuration={0}>
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <Button
-                        className="h-7 px-3 font-mono text-[11px] hover:bg-gray-300"
-                        onClick={() => setScale(scale === 1 ? 0.8 : 1)}
-                        variant="ghost"
-                      >
-                        {scale === 1 ? '100%' : '80%'}
-                      </Button>
-                    </TooltipTrigger>
-                    <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">Toggle Scale</TooltipContent>
-                  </Tooltip>
-                </TooltipProvider>
-                <Separator orientation="vertical" className="mx-3 h-6" />
-                <RadioGroup className="flex items-center gap-0" defaultValue="1100" onValueChange={(value) => setWidth(`${value}px`)}>
-                  <label className="relative flex h-7 cursor-pointer flex-col items-center justify-center rounded-md px-3 text-center text-xl ring-inset transition-colors hover:bg-gray-300 has-data-disabled:cursor-not-allowed has-data-[state=checked]:bg-blue-50 has-data-disabled:opacity-50 has-data-[state=checked]:shadow-[inset_0_1px_1px_0_rgba(0,0,0,0.05)] has-focus-visible:outline-solid has-focus-visible:outline-2 has-focus-visible:outline-ring/70 has-data-[state=checked]:ring-1 has-data-[state=checked]:ring-blue-500/20 [&_svg]:size-3">
-                    <RadioGroupItem value="1100" className="sr-only after:absolute after:inset-0" />
-                    <Monitor />
-                  </label>
-                  <label className="relative flex h-7 cursor-pointer flex-col items-center justify-center rounded-md px-3 text-center text-xl transition-colors hover:bg-gray-300 has-data-disabled:cursor-not-allowed has-data-[state=checked]:bg-blue-50 has-data-disabled:opacity-50 has-data-[state=checked]:shadow-[inset_0_1px_1px_0_rgba(0,0,0,0.05)] has-focus-visible:outline-solid has-focus-visible:outline-2 has-focus-visible:outline-ring/70 has-data-[state=checked]:ring-1 has-data-[state=checked]:ring-blue-500/20 [&_svg]:size-3">
-                    <RadioGroupItem value="800" className="sr-only after:absolute after:inset-0" />
-                    <Tablet />
-                  </label>
-                  <label className="relative flex h-7 cursor-pointer flex-col items-center justify-center rounded-md px-3 text-center text-xl transition-colors hover:bg-gray-300 has-data-disabled:cursor-not-allowed has-data-[state=checked]:bg-blue-50 has-data-disabled:opacity-50 has-data-[state=checked]:shadow-[inset_0_1px_1px_0_rgba(0,0,0,0.05)] has-focus-visible:outline-solid has-focus-visible:outline-2 has-focus-visible:outline-ring/70 has-data-[state=checked]:ring-1 has-data-[state=checked]:ring-blue-500/20 [&_svg]:size-2.5">
-                    <RadioGroupItem value="400" className="sr-only after:absolute after:inset-0" />
-                    <Smartphone />
-                  </label>
-                </RadioGroup>
-                <Separator orientation="vertical" className="mx-3 h-6" />
-                <TooltipProvider delayDuration={0}>
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <Button
-                        className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-3"
-                        onClick={() => {
-                          if (ref.current) {
-                            ref.current.contentWindow.location.reload();
-                          }
-                        }}
-                        variant="ghost"
-                      >
-                        <RefreshCcw />
-                      </Button>
-                    </TooltipTrigger>
-                    <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">Refresh Preview</TooltipContent>
-                  </Tooltip>
-                </TooltipProvider>
-                <TooltipProvider delayDuration={0}>
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <Button
-                        className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-4"
-                        onClick={() => {
-                          setInspect(!inspect);
-                        }}
-                        variant={inspect ? 'default' : 'ghost'}
-                      >
-                        <MousePointerClick strokeWidth={1.5} />
-                      </Button>
-                    </TooltipTrigger>
-                    <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">Inspect Component</TooltipContent>
-                  </Tooltip>
-                </TooltipProvider>
-                <TooltipProvider delayDuration={0}>
-                  <Tooltip>
-                    <TooltipTrigger asChild>
-                      <Button
-                        className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-3"
-                        onClick={() => {
-                          // open in new tab
-                          window.open(buildArtifactUrl(`component/${artifactPath}`, process.env.HANDOFF_APP_BASE_PATH ?? ''), '_blank');
-                        }}
-                        variant="ghost"
-                      >
-                        <SquareArrowOutUpRight />
-                      </Button>
-                    </TooltipTrigger>
-                    <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">Open in New Tab</TooltipContent>
-                  </Tooltip>
-                </TooltipProvider>
-              </div>
-            </div>
+  const collapsedStyle: React.CSSProperties = { position: 'fixed', zIndex: 50 };
+  const originStyle: React.CSSProperties = originRect
+    ? { top: `${originRect.top}%`, left: `${originRect.left}%`, width: `${originRect.width}%`, transform: 'translateY(0)' }
+    : {};
+  const fullSizeStyle: React.CSSProperties = {
+    ...collapsedStyle,
+    top: '50%',
+    left: '2%',
+    width: '96%',
+    maxHeight: '92vh',
+    transform: 'translateY(-50%)',
+  };
 
-            <div className="dotted-bg w-full p-8">
-              {artifactPath ? (
-                <div>
-                  <iframe
-                    key={`${artifactPath}-${reloadCounter}`}
-                    onLoad={onLoad}
-                    ref={ref}
-                    height={height}
-                    style={{
-                      minWidth: width,
-                      height: height,
-                      transform: `scale(${scale})`,
-                      transformOrigin: 'left top',
-                      transition: 'all 0.2s ease-in-out',
-                      display: 'block',
-                      margin: '0 auto',
-                    }}
-                    src={buildArtifactUrl(`component/${artifactPath}`, process.env.HANDOFF_APP_BASE_PATH ?? '')}
-                  />
-                </div>
+  const card = (
+    <div
+      ref={cardRef}
+      role={expanded ? 'dialog' : undefined}
+      aria-modal={expanded ? true : undefined}
+      aria-label={expanded ? `${title ?? 'Component'} preview` : undefined}
+      style={expanded ? (phase === 'full' ? fullSizeStyle : { ...collapsedStyle, ...originStyle }) : undefined}
+      className={`text-medium flex w-full flex-col items-center rounded-lg border border-gray-200 dark:border-gray-900 ${
+        expanded ? 'overflow-hidden bg-background shadow-xl' : ''
+      } ${animates ? 'transition-[top,left,width,transform] duration-300 ease-out motion-reduce:transition-none' : ''}`}
+    >
+      {component?.previews && (
+        <>
+          <div
+            className="flex w-full items-center justify-between rounded-t-lg bg-gray-50 px-6 py-2 pr-3 align-middle @container dark:bg-gray-800"
+          >
+            <div className="flex flex-1 items-start gap-2">
+              {localVariants ? (
+                <>
+                  {Object.keys(localVariants).length > 0 && (
+                    <>
+                      <div className="flex h-8 shrink-0 items-center gap-2">
+                        <p className="font-monospace text-[11px] text-accent-foreground">{title ?? 'Variant'}</p>
+                        <Separator orientation="vertical" className="h-3" />
+                      </div>
+                      <div className="flex flex-wrap gap-2">
+                        {Object.keys(localVariants)
+                          .filter((variantProperty) => localVariants[variantProperty].length > 1)
+                          .map((variantProperty) => (
+                            <Select
+                              key={variantProperty}
+                              value={context.variantFilter ? context.variantFilter[variantProperty] : undefined}
+                              onValueChange={(value) => context.updateVariantFilter(variantProperty, value)}
+                            >
+                              <SelectTrigger className="h-8 w-[140px] border-none text-xs shadow-none">
+                                <SelectValue placeholder={variantProperty} />
+                              </SelectTrigger>
+                              <SelectContent>
+                                {localVariants[variantProperty].map((variantPropertyValue) => {
+                                  if (typeof variantPropertyValue !== 'string' || variantPropertyValue === '') return null;
+                                  return (
+                                    <SelectItem
+                                      key={variantPropertyValue}
+                                      value={variantPropertyValue}
+                                      disabled={!isOptionValid(variantProperty, variantPropertyValue)}
+                                    >
+                                      {variantPropertyValue}
+                                    </SelectItem>
+                                  );
+                                })}
+                              </SelectContent>
+                            </Select>
+                          ))}
+                      </div>
+                    </>
+                  )}
+                </>
               ) : (
-                <div className="flex items-center justify-center p-8 text-sm text-gray-500">
-                  No preview available for this selection.
-                </div>
+                <>
+                  <Select value={previewKey ?? ''} onValueChange={setPreviewKey}>
+                    <SelectTrigger className="h-8 w-[180px] border-none border-gray-200 bg-white text-xs shadow-none dark:border-gray-900">
+                      <SelectValue placeholder="Preview" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {renderablePreviewKeys.map((key) => (
+                        <SelectItem key={key} value={key}>
+                          {component.previews[key].title}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </>
               )}
             </div>
-          </>
-        )}
-      </div>
+            <div className="hidden items-center gap-0 @xl:flex">
+              {scale < 1 && (
+                <>
+                  <TooltipProvider delayDuration={0}>
+                    <Tooltip>
+                      <TooltipTrigger asChild>
+                        <span className="px-3 font-mono text-[11px] text-gray-500">{Math.round(scale * 100)}%</span>
+                      </TooltipTrigger>
+                      <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">
+                        Too wide for this column. Expand to see it at full size.
+                      </TooltipContent>
+                    </Tooltip>
+                  </TooltipProvider>
+                  <Separator orientation="vertical" className="mx-3 h-6" />
+                </>
+              )}
+              <RadioGroup
+                className="flex items-center gap-0"
+                value={String(previewWidth)}
+                onValueChange={(value) => setPreviewWidth(value === 'fluid' ? 'fluid' : Number(value))}
+              >
+                <label className="relative flex h-7 cursor-pointer flex-col items-center justify-center rounded-md px-3 text-center text-xl ring-inset transition-colors hover:bg-gray-300 has-data-disabled:cursor-not-allowed has-data-[state=checked]:bg-blue-50 has-data-disabled:opacity-50 has-data-[state=checked]:shadow-[inset_0_1px_1px_0_rgba(0,0,0,0.05)] has-focus-visible:outline-solid has-focus-visible:outline-2 has-focus-visible:outline-ring/70 has-data-[state=checked]:ring-1 has-data-[state=checked]:ring-blue-500/20 [&_svg]:size-3">
+                  <RadioGroupItem value="fluid" aria-label="Fill the available width" className="sr-only after:absolute after:inset-0" />
+                  <Monitor />
+                </label>
+                <label className="relative flex h-7 cursor-pointer flex-col items-center justify-center rounded-md px-3 text-center text-xl transition-colors hover:bg-gray-300 has-data-disabled:cursor-not-allowed has-data-[state=checked]:bg-blue-50 has-data-disabled:opacity-50 has-data-[state=checked]:shadow-[inset_0_1px_1px_0_rgba(0,0,0,0.05)] has-focus-visible:outline-solid has-focus-visible:outline-2 has-focus-visible:outline-ring/70 has-data-[state=checked]:ring-1 has-data-[state=checked]:ring-blue-500/20 [&_svg]:size-3">
+                  <RadioGroupItem value="800" aria-label="Tablet width, 800px" className="sr-only after:absolute after:inset-0" />
+                  <Tablet />
+                </label>
+                <label className="relative flex h-7 cursor-pointer flex-col items-center justify-center rounded-md px-3 text-center text-xl transition-colors hover:bg-gray-300 has-data-disabled:cursor-not-allowed has-data-[state=checked]:bg-blue-50 has-data-disabled:opacity-50 has-data-[state=checked]:shadow-[inset_0_1px_1px_0_rgba(0,0,0,0.05)] has-focus-visible:outline-solid has-focus-visible:outline-2 has-focus-visible:outline-ring/70 has-data-[state=checked]:ring-1 has-data-[state=checked]:ring-blue-500/20 [&_svg]:size-2.5">
+                  <RadioGroupItem value="400" aria-label="Mobile width, 400px" className="sr-only after:absolute after:inset-0" />
+                  <Smartphone />
+                </label>
+              </RadioGroup>
+              <Separator orientation="vertical" className="mx-3 h-6" />
+              <TooltipProvider delayDuration={0}>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button
+                      className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-3"
+                      onClick={() => {
+                        if (ref.current) {
+                          ref.current.contentWindow.location.reload();
+                        }
+                      }}
+                      variant="ghost"
+                    >
+                      <RefreshCcw />
+                    </Button>
+                  </TooltipTrigger>
+                  <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">Refresh Preview</TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+              <TooltipProvider delayDuration={0}>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button
+                      className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-4"
+                      onClick={() => {
+                        setInspect(!inspect);
+                      }}
+                      variant={inspect ? 'default' : 'ghost'}
+                    >
+                      <MousePointerClick strokeWidth={1.5} />
+                    </Button>
+                  </TooltipTrigger>
+                  <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">Inspect Component</TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+              <TooltipProvider delayDuration={0}>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button
+                      aria-label={expanded ? 'Collapse preview' : 'Expand preview'}
+                      className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-3"
+                      onClick={() => (expanded ? collapse() : expand())}
+                      variant="ghost"
+                    >
+                      {expanded ? <Minimize2 /> : <Maximize2 />}
+                    </Button>
+                  </TooltipTrigger>
+                  <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">
+                    {expanded ? 'Collapse Preview' : 'Expand Preview'}
+                  </TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+              <TooltipProvider delayDuration={0}>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button
+                      className="h-7 px-3 hover:bg-gray-300 [&_svg]:size-3"
+                      onClick={() => {
+                        // open in new tab
+                        window.open(buildArtifactUrl(`component/${artifactPath}`, process.env.HANDOFF_APP_BASE_PATH ?? ''), '_blank');
+                      }}
+                      variant="ghost"
+                    >
+                      <SquareArrowOutUpRight />
+                    </Button>
+                  </TooltipTrigger>
+                  <TooltipContent className="rounded-sm px-2 py-1 text-[11px]">Open in New Tab</TooltipContent>
+                </Tooltip>
+              </TooltipProvider>
+            </div>
+          </div>
+
+          <div className={`dotted-bg w-full p-4 ${expanded ? 'min-h-0' : ''}`}>
+            {artifactPath ? (
+              // The outer div measures the width available to the preview. The inner one carries
+              // the scaled size, because a transform does not shrink the layout box: without it
+              // the stage keeps the unscaled box and pads the preview with dead space on the
+              // right and below.
+              <div ref={observeStage}>
+                {renderWidth > 0 && (
+                  <div
+                    style={{
+                      width: renderWidth * scale,
+                      height: `calc(${height} * ${scale})`,
+                      margin: '0 auto',
+                      transition: boxTransition,
+                    }}
+                  >
+                    <iframe
+                      key={`${artifactPath}-${reloadCounter}`}
+                      onLoad={onLoad}
+                      ref={ref}
+                      style={{
+                        width: renderWidth,
+                        height: height,
+                        transform: `scale(${scale})`,
+                        transformOrigin: 'left top',
+                        transition: animates ? 'none' : 'transform 0.2s ease-in-out',
+                        display: 'block',
+                      }}
+                      src={buildArtifactUrl(`component/${artifactPath}`, process.env.HANDOFF_APP_BASE_PATH ?? '')}
+                    />
+                  </div>
+                )}
+              </div>
+            ) : (
+              <div className="flex items-center justify-center p-8 text-sm text-gray-500">
+                No preview available for this selection.
+              </div>
+            )}
+          </div>
+        </>
+      )}
     </div>
   );
+
+  // The docs column is narrower than the widths most components are designed for. Expanding is
+  // how a reader gets the real layout at 100% instead of a scaled copy of it. The placeholder holds
+  // the page height while the card floats, so nothing behind the overlay jumps.
+  return (
+    <>
+      {expanded && (
+        <div
+          className={`backdrop-blur-xs fixed inset-0 z-40 bg-gray-200/50 transition-opacity duration-300 dark:bg-gray-950/60 ${
+            phase === 'full' ? 'opacity-100' : 'opacity-0'
+          }`}
+          onClick={collapse}
+        />
+      )}
+      <div className="md:flex" id="preview" style={expanded && originRect ? { minHeight: originRect.height } : undefined}>
+        {card}
+      </div>
+    </>
+  );
 };
 
 export const ComponentPreview: React.FC<{

package/src/app/components/Component/slices/ComponentDisplaySlice.tsx

@@ -1,3 +1,4 @@
+import { PreviewWidth } from '@handoff/transformers/preview/types';
 import { PreviewObject } from '@handoff/types/preview';
 import { Filter, evaluateFilter } from '@handoff/utils/filter';
 import React from 'react';
@@ -13,6 +14,7 @@ export interface ComponentDisplaySliceProps {
   showPreview?: boolean;
   showCodeHighlight?: boolean;
   defaultHeight?: string;
+  defaultWidth?: PreviewWidth;
   filterBy?: Filter;
   codeHighlight?: boolean;
 }
@@ -38,6 +40,7 @@ const ComponentDisplaySlice: React.FC<ComponentDisplaySliceProps> = ({
   showPreview = true,
   showCodeHighlight,
   defaultHeight,
+  defaultWidth,
   filterBy,
   codeHighlight = true,
 }) => {
@@ -68,6 +71,7 @@ const ComponentDisplaySlice: React.FC<ComponentDisplaySliceProps> = ({
           title={title}
           component={filteredPreview}
           defaultHeight={finalDefaultHeight}
+          defaultWidth={defaultWidth}
           onPreviewChange={onPreviewChange}
         />
       )}