@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/content/componentPreview.tsx

@@ -0,0 +1,249 @@
+// The block HOVER PREVIEW: a bubble beside a block row (the palette, the canvas's insert
+// popover), showing what a block looks like.
+//
+// DECLARED AS DATA. A preview exists where the module's editor facet says so — `preview: 'self'`
+// for a block that stands on its own, or a tree for anything richer. Nothing to declare, nothing
+// shown: a block rendered alone out of any composition is a guess, and a guess presented as "this
+// is what you are about to place" is worse than no answer.
+//
+// MOUNTED, NOT RENDERED (ADR-0034). The editor does not render the specimen with its own react —
+// the hosting itself is `useMountedTree`, the same one the settings panel's form goes through.
+// What this file owns is the PLAN: reading the declaration and turning it into a tree for a ROOT —
+// in order, the one the preview tree names, the one the block's own library ships, and failing
+// both the editor's.
+//
+// ONE MOUNT, MANY PREVIEWS. The application lives as long as the panel; a new row hands it a new
+// tree (IMountHandle.render → the page manager). No mounting on hover, no empty box while a
+// module loads.
+//
+// SIZED BY WHAT IT SHOWS, up to a ceiling, never shrinking while one preview is open.
+import { createPortal } from 'react-dom';
+import { useEffect, useState } from 'react';
+import { TILES_HOLDER_TOKEN } from '@mosetta/runtime/client';
+import type { IMountPreview } from '@mosetta/runtime/client';
+import type { IBlueprintNode } from '@mosetta/core';
+import { PALETTE_PREVIEW, useComponent } from '@mosetta/react';
+import { useDi } from '@mosetta/react';
+import { tileScopeClass } from '@mosetta/react';
+import type { IEditorSide, IPreviewTree, TPreviewSpec } from '@mosetta/react';
+import { hostedPage, hostFallbackOf, loadModule } from './mountedTree';
+import type { IMountSpec } from './mountedTree';
+import { useMountedTree } from './useMountedTree';
+import { atOwnVersion } from './blockVariants';
+import './componentPreview.css';
+
+/** the bubble grows with its content, between these */
+const MIN_WIDTH = 160;
+const MIN_HEIGHT = 80;
+const MAX_WIDTH = 420;
+const MAX_HEIGHT = 320;
+/** distance from the row, and the margin the bubble keeps from the window's edges */
+const GAP = 12;
+const EDGE = 8;
+/** the frame between the border and the specimen, so they never touch */
+const PAD = 12;
+/** what the frame adds to the measured content: the padding and the 1px borders */
+const FRAME = PAD * 2 + 2;
+
+export interface IPreviewTarget {
+  readonly reference: string;
+  /** from the catalog: no editor facet, no declaration — nothing to load and nothing to ask */
+  readonly hasEditor: boolean;
+  /** a root module of the block's OWN library, when it ships one (catalog `isRoot`) */
+  readonly libraryRoot?: string;
+  /** the hovered row, in window coordinates */
+  readonly anchor: { readonly top: number; readonly left: number; readonly right: number };
+  /** a PREFAB's own tree — shown as it is, under its own root, no declaration asked for */
+  readonly tree?: { readonly rootReference: string; readonly children: readonly IBlueprintNode[] };
+}
+
+export const editorReferenceOf = (reference: string) => reference.replace('_t_component_', '_t_editor_');
+
+/** the mount option every specimen gets: "you are a palette preview" (IMountOptions.preview) */
+const PALETTE_MOUNT: IMountPreview = { type: PALETTE_PREVIEW };
+
+/**
+ * ONE declaration object per facet: its identity is what keeps the specimen application alive
+ * across rows (MountedTree remounts when the declaration changes) — facets with the same (empty)
+ * environment share one application, a facet with services of its own gets one arranged for it.
+ */
+const previewByFacet = new WeakMap<object, IMountPreview>();
+
+export function previewMountFor(facet: object | undefined, services: IEditorSide['previewServices']): IMountPreview {
+  if (!facet || !services?.length) return PALETTE_MOUNT;
+  let declared = previewByFacet.get(facet);
+  if (!declared) {
+    declared = { type: PALETTE_PREVIEW, services };
+    previewByFacet.set(facet, declared);
+  }
+  return declared;
+}
+
+/** the editor's own root — every root can host, so this is simply ours (ADR-0034 §5) */
+export const previewRootOf = ({ namespace, version }: { namespace: string; version: string }) => `_ns_${namespace}_t_component_n_page_v_${version}`;
+
+export interface IComponentFacet {
+  defaultSettings?: () => Record<string, unknown>;
+}
+
+export interface IEditorFacet {
+  preview?: TPreviewSpec;
+  previewServices?: IEditorSide['previewServices'];
+  variants?: IEditorSide['variants'];
+}
+
+type TPlan
+  = | { readonly status: 'looking' }
+  /** the module says nothing about how it looks alone — then the palette says nothing either */
+  | { readonly status: 'none' }
+  | { readonly status: 'failed' }
+  | { readonly status: 'ready'; readonly spec: IMountSpec };
+
+/**
+ * Reads the declaration and turns it into a mount spec — what to show, and whose root shows it.
+ * Everything here is data and module loading — no rendering of anyone else's UI, no mounting:
+ * the spec goes to `useMountedTree`, which owns the application.
+ */
+export function usePreviewPlan(target: IPreviewTarget | null, self: { namespace: string; version: string }): TPlan {
+  const holder = useDi(TILES_HOLDER_TOKEN);
+  const [plan, setPlan] = useState<TPlan>({ status: 'looking' });
+
+  useEffect(() => {
+    let alive = true;
+    if (!target) return undefined;
+    if (target.tree) {
+      setPlan({ status: 'ready', spec: { rootReference: target.tree.rootReference, tree: hostedPage(target.tree.rootReference, target.tree.children, hostFallbackOf(self)), preview: PALETTE_MOUNT } });
+      return undefined;
+    }
+    if (!target.hasEditor) {
+      setPlan({ status: 'none' });
+      return undefined;
+    }
+    setPlan({ status: 'looking' });
+    void (async () => {
+      try {
+        const [editor, component] = await Promise.all([
+          loadModule(holder, editorReferenceOf(target.reference)),
+          loadModule(holder, target.reference),
+        ]);
+        const loaded = editor?.module as IEditorFacet | undefined;
+        // the facet's own blocks at the facet's own version — the preview was written at some earlier one
+        const facet = loaded ? atOwnVersion(loaded, target.reference) : undefined;
+        const spec = facet?.preview;
+        if (!spec) {
+          if (alive) setPlan({ status: 'none' });
+          return;
+        }
+        const declared: IPreviewTree = spec === 'self'
+          ? {
+            children: [{
+              id: '__preview-node',
+              reference: target.reference,
+              settings: (component?.module as IComponentFacet | undefined)?.defaultSettings?.() ?? {},
+              children: [],
+            }],
+          }
+          : spec;
+        // whose root: the one the declaration names, the block's own library, or ours
+        const rootReference = declared.reference ?? target.libraryRoot ?? previewRootOf(self);
+        if (alive) {
+          setPlan({
+            status: 'ready',
+            spec: {
+              rootReference,
+              tree: hostedPage(rootReference, declared.children, hostFallbackOf(self)),
+              // keyed by the LOADED facet: its identity is what keeps one application across rows
+              preview: previewMountFor(loaded, loaded?.previewServices),
+            },
+          });
+        }
+      } catch {
+        if (alive) setPlan({ status: 'failed' });
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+  }, [holder, target, self.namespace, self.version]);
+
+  return plan;
+}
+
+/** where the bubble goes: beside the row, clamped into the window, beak on the row's own line */
+function place(anchor: IPreviewTarget['anchor'], size: { width: number; height: number }) {
+  const view = { width: window.innerWidth, height: window.innerHeight };
+  const flipped = anchor.right + GAP + size.width > view.width - EDGE;
+  const left = flipped
+    ? Math.max(EDGE, anchor.left - GAP - size.width)
+    : Math.min(anchor.right + GAP, view.width - EDGE - size.width);
+  // grows DOWN from the row — until there is no down left, and then it slides up while the beak
+  // stays on the row it belongs to
+  const top = Math.max(EDGE, Math.min(anchor.top - GAP, view.height - EDGE - size.height));
+  return { top, left, beak: Math.max(6, Math.min(anchor.top - top, size.height - 16)), flipped };
+}
+
+/**
+ * The bubble — in a PORTAL, because the panel it is anchored to scrolls and clips its own content.
+ * Wrapped in a scope host of the palette's module: css is built with that class as a prefix, and
+ * markup portalled onto the body would otherwise arrive with no styles at all. Pointer-transparent:
+ * something to look at, never to reach, so it can never steal the hover that opened it.
+ */
+export function ComponentPreview({ target }: { target: IPreviewTarget | null }) {
+  const self = useComponent().reference;
+  const plan = usePreviewPlan(target, self);
+  // a null spec leaves the application as it is — the bubble outlives the hover on purpose
+  const { ref: stage, failed } = useMountedTree(plan.status === 'ready' ? plan.spec : null);
+  const [size, setSize] = useState({ width: MIN_WIDTH, height: MIN_HEIGHT });
+
+  // measured again for each new specimen
+  useEffect(() => {
+    if (plan.status === 'ready') setSize({ width: MIN_WIDTH, height: MIN_HEIGHT });
+  }, [plan]);
+
+  // measured after the specimen renders, and never allowed to shrink while it is shown: a box
+  // that followed its content downwards would twitch as data arrived
+  useEffect(() => {
+    const element = stage.current;
+    if (!element || typeof ResizeObserver === 'undefined') return undefined;
+    const grow = () => setSize((seen) => ({
+      width: Math.min(MAX_WIDTH, Math.max(seen.width, element.scrollWidth)),
+      height: Math.min(MAX_HEIGHT, Math.max(seen.height, element.scrollHeight)),
+    }));
+    const observer = new ResizeObserver(grow);
+    observer.observe(element);
+    grow();
+    return () => observer.disconnect();
+  }, [plan.status]);
+
+  // `failed` counts only against the plan that asked for the mount — not the one being replaced
+  const broken = plan.status === 'failed' || (plan.status === 'ready' && failed);
+  const shown = target !== null && (plan.status === 'ready' || broken);
+  // the window sees the FULL box — the frame included — while the styles carry the content's size
+  const outer = { width: size.width + FRAME, height: size.height + FRAME };
+  const at = place(target?.anchor ?? { top: 0, left: 0, right: 0 }, outer);
+  return createPortal(
+    <div className={tileScopeClass(self)}
+         style={{ display: 'contents' }}>
+      {/* the application outlives the hover, so the bubble is always in the document and merely
+          hidden — unmounting it on every pointer-out would defeat the point of mounting once */}
+      <div className={`palette-preview${at.flipped ? ' palette-preview--flipped' : ''}`}
+           data-component-preview={shown ? target.reference : undefined}
+           hidden={!shown}
+           style={{ top: `${at.top}px`, left: `${at.left}px`, width: `${size.width}px`, height: `${size.height}px`, padding: `${PAD}px` }}>
+        <span className="palette-preview__beak"
+              style={{ top: `${at.beak}px` }} />
+        {broken && (
+          <div className="palette-preview__failed"
+               data-preview-failed>Could not render this preview</div>
+        )}
+        <div className="palette-preview__viewport">
+          {/* capped at the box ceiling so long text WRAPS there instead of leaving as one line */}
+          <div className="palette-preview__content"
+               style={{ maxWidth: `${MAX_WIDTH}px` }}
+               ref={stage} />
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}