@xemahq/ui-kernel 0.6.0 → 0.6.1

package/src/ui/primitives/preview-device-frame.tsx

@@ -0,0 +1,205 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── PreviewDeviceFrame — CSS-transform-scaled device bezel ──
+//
+// Wraps a child (typically an iframe, but any node works) in a scale-to-fit
+// bezel for Tablet (768×1024) and Mobile (390×844). Desktop renders children
+// at 100% width/height. Presentation renders a responsive 16:9 viewport;
+// A4 renders a 794×1123 portrait sheet — both grow/shrink to fit the panel.
+//
+// IMPORTANT: We scale the *wrapper* via `transform: scale(...)` — the child is
+// always rendered at the bezel's native resolution. This avoids ResizeObserver
+// churn inside an embedded app (width/height stay constant; only the parent's
+// visual size changes). Devices report the bezel's intended CSS pixel
+// dimensions to the child regardless of the visual scale.
+//
+// Owned by the UI kernel so both the host session-preview surface AND biome
+// canvases (e.g. App Forge's builder) reuse ONE bezel — there is no second
+// device-frame implementation.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { useLayoutEffect, useRef, useState, type ReactNode } from 'react';
+
+import { cn } from '../cn';
+
+/**
+ * Closed set of preview viewports. `desktop`/`tablet`/`mobile` are the
+ * device widths an app builder offers; `presentation`/`a4` are
+ * document-preview viewports used by the session preview surface only.
+ */
+export type PreviewDevice =
+  | 'desktop'
+  | 'tablet'
+  | 'mobile'
+  | 'presentation'
+  | 'a4';
+
+interface PreviewDeviceFrameProps {
+  readonly device: PreviewDevice;
+  readonly children: ReactNode;
+}
+
+interface Bezel {
+  width: number;
+  height: number;
+  radius: number;
+}
+
+const BEZELS: Record<
+  Exclude<PreviewDevice, 'desktop' | 'presentation' | 'a4'>,
+  Bezel
+> = {
+  tablet: { width: 768, height: 1024, radius: 18 },
+  mobile: { width: 390, height: 844, radius: 36 },
+};
+
+const PRESENTATION_VIEWPORT: Bezel = { width: 1280, height: 720, radius: 20 };
+// A4 at 96 dpi: 210mm × 297mm → 794×1123 px
+const A4_VIEWPORT: Bezel = { width: 794, height: 1123, radius: 4 };
+
+export function PreviewDeviceFrame({
+  device,
+  children,
+}: PreviewDeviceFrameProps) {
+  if (device === 'desktop') {
+    return <div className="h-full w-full">{children}</div>;
+  }
+  if (device === 'presentation') {
+    return (
+      <ResponsiveViewport bezel={PRESENTATION_VIEWPORT} aspectRatio={16 / 9}>
+        {children}
+      </ResponsiveViewport>
+    );
+  }
+  if (device === 'a4') {
+    return (
+      <ResponsiveViewport bezel={A4_VIEWPORT} aspectRatio={794 / 1123}>
+        {children}
+      </ResponsiveViewport>
+    );
+  }
+  return <ScaledBezel bezel={BEZELS[device]}>{children}</ScaledBezel>;
+}
+
+interface ScaledBezelProps {
+  readonly bezel: Bezel;
+  readonly children: ReactNode;
+}
+
+/**
+ * Render a fixed-size bezel at (bezel.width × bezel.height) CSS px, then
+ * scale the whole wrapper down to fit its container. The child inside stays
+ * at the bezel's native resolution.
+ */
+function ScaledBezel({ bezel, children }: ScaledBezelProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [scale, setScale] = useState(1);
+
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const compute = (): void => {
+      const { clientWidth, clientHeight } = el;
+      if (clientWidth === 0 || clientHeight === 0) return;
+      // Leave a tiny margin so the shadow is not clipped.
+      const margin = 24;
+      const availW = Math.max(0, clientWidth - margin);
+      const availH = Math.max(0, clientHeight - margin);
+      const next = Math.min(1, availW / bezel.width, availH / bezel.height);
+      setScale(next);
+    };
+    compute();
+    const observer = new ResizeObserver(compute);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [bezel.width, bezel.height]);
+
+  return (
+    <div
+      ref={containerRef}
+      className="flex h-full w-full items-center justify-center overflow-hidden bg-paper-elev/60 p-2"
+    >
+      <div
+        className={cn(
+          'relative shrink-0 overflow-hidden bg-paper shadow-2xl ring-1 ring-border/75',
+        )}
+        style={{
+          width: bezel.width,
+          height: bezel.height,
+          borderRadius: bezel.radius,
+          // Scale the WRAPPER — NOT the child element. The child's own
+          // width/height in CSS pixels remain bezel.width × bezel.height, so
+          // an embedded app sees a stable viewport and no ResizeObserver churn
+          // when the outer panel resizes.
+          transform: `scale(${scale})`,
+          transformOrigin: 'center center',
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
+interface ResponsiveViewportProps extends ScaledBezelProps {
+  /** Width-to-height ratio used to letterbox/pillarbox the frame. */
+  readonly aspectRatio: number;
+}
+
+/**
+ * Fit an arbitrary-aspect-ratio viewport inside the available space and let
+ * the child resize to that real size. Content sees the actual viewport
+ * dimensions instead of a transform-scaled shell, so it can adapt responsively.
+ */
+function ResponsiveViewport({
+  bezel,
+  aspectRatio,
+  children,
+}: ResponsiveViewportProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [size, setSize] = useState(() => ({
+    width: bezel.width,
+    height: bezel.height,
+  }));
+
+  useLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const compute = (): void => {
+      const { clientWidth, clientHeight } = el;
+      if (clientWidth === 0 || clientHeight === 0) return;
+      const margin = 24;
+      const availW = Math.max(0, clientWidth - margin);
+      const availH = Math.max(0, clientHeight - margin);
+      const nextWidth = Math.min(availW, availH * aspectRatio);
+      const nextHeight = nextWidth / aspectRatio;
+      setSize({
+        width: Math.max(1, Math.round(nextWidth)),
+        height: Math.max(1, Math.round(nextHeight)),
+      });
+    };
+    compute();
+    const observer = new ResizeObserver(compute);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [bezel.width, bezel.height]);
+
+  return (
+    <div
+      ref={containerRef}
+      className="flex h-full w-full items-center justify-center overflow-hidden bg-paper-elev/60 p-2"
+    >
+      <div
+        className={cn(
+          'relative shrink-0 overflow-hidden bg-paper shadow-2xl ring-1 ring-border/75',
+        )}
+        style={{
+          width: size.width,
+          height: size.height,
+          borderRadius: bezel.radius,
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}