@zalify/storefront-kit 0.3.2 → 0.5.0

package/src/react/server-preview.tsx

@@ -0,0 +1,333 @@
+"use client";
+/**
+ * Editor preview for storefronts that render templates on the server (React
+ * Server Components) instead of through the client theme engine.
+ *
+ * The app supplies two server functions — one returning its bootstrap, one
+ * rendering a draft template to React nodes — and wraps each editable region.
+ * Everything else (trust, bridge, design mode, selection, responsive-copy
+ * paths, error surface) is here, so a storefront repo never writes it again.
+ *
+ *   <EditorPreviewProvider getBootstrap={…} renderTemplate={…}>
+ *     <EditorGroupRegion name="header-group">…</EditorGroupRegion>
+ *     <EditorTemplateRegion name="page.about">…</EditorTemplateRegion>
+ *   </EditorPreviewProvider>
+ */
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { flushSync } from "react-dom";
+import type { FrameBridgeController } from "../editor/frame";
+import type { EditorBootstrap } from "../schemas/bridge";
+import type {
+  SectionGroupData,
+  SettingsData,
+  TemplateData,
+} from "../schemas/data";
+import { enterDesignMode } from "./design-mode";
+import { resolveEditorOrigin, ZALIFY_EDITOR_ORIGINS } from "./editor-origin";
+
+export interface RenderTemplateInput {
+  templateName: string;
+  template: TemplateData;
+  groups?: Record<string, SectionGroupData>;
+  /** Path + query of the page being previewed, without the editor param. */
+  pathname: string;
+}
+
+/** Keys are `template:<name>` and `group:<name>`. */
+export type RenderedRegions = Record<string, ReactNode>;
+
+export interface EditorPreviewProviderProps {
+  children: ReactNode;
+  /** Server function: the app's bootstrap (see `createEditorBootstrap`). */
+  getBootstrap: () => Promise<EditorBootstrap>;
+  /** Server function: render a draft. Must be read-only. */
+  renderTemplate: (input: RenderTemplateInput) => Promise<RenderedRegions>;
+  /** Map draft theme settings onto the page (CSS variables, usually). */
+  applySettings?: (settings: SettingsData, root: HTMLElement) => void;
+  /** Defaults to {@link ZALIFY_EDITOR_ORIGINS}. */
+  origins?: readonly string[];
+  /** A render slower than this fails the edit instead of hanging it. */
+  renderTimeoutMs?: number;
+}
+
+type PreviewContextValue = {
+  enabled: boolean;
+  selectedPath: string | null;
+  regions: RenderedRegions;
+  register: (name: string) => () => void;
+};
+const PreviewContext = createContext<PreviewContextValue | null>(null);
+
+const CONNECT_TIMEOUT_MS = 30_000;
+const GUARDED_EVENTS = ["click", "auxclick", "dblclick", "submit"];
+
+async function withDeadline<T>(request: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      request,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("Preview update timed out. Retry the edit.")),
+          ms,
+        );
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** No bootstrap payload or bridge code is downloaded by ordinary visitors. */
+export function EditorPreviewProvider({
+  children,
+  getBootstrap,
+  renderTemplate,
+  applySettings,
+  origins = ZALIFY_EDITOR_ORIGINS,
+  renderTimeoutMs = 20_000,
+}: EditorPreviewProviderProps) {
+  const [editorOrigin, setEditorOrigin] = useState<string | null>(null);
+  const [selectedPath, setSelectedPath] = useState<string | null>(null);
+  const [templateName, setTemplateName] = useState<string | null>(null);
+  const [regions, setRegions] = useState<RenderedRegions>({});
+  const [error, setError] = useState<string | null>(null);
+  const [retry, setRetry] = useState(0);
+  const controllerRef = useRef<FrameBridgeController | null>(null);
+  const sequenceRef = useRef(0);
+  // Server functions and callbacks may be new identities on every render;
+  // they must not reconnect the bridge.
+  const handlers = useRef({ getBootstrap, renderTemplate, applySettings });
+  handlers.current = { getBootstrap, renderTemplate, applySettings };
+  const enabled = editorOrigin !== null;
+
+  useEffect(() => {
+    setEditorOrigin(resolveEditorOrigin(origins));
+  }, [origins]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const guard = (event: Event) => {
+      if (
+        event.type === "click" &&
+        event.target instanceof Element &&
+        event.target.closest("[data-z-editor-retry]")
+      ) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        setRetry((value) => value + 1);
+        return;
+      }
+      // The bridge owns clicks once connected. Until then nothing in the shop
+      // may run; and a preview never submits a real lead, order or login.
+      if (event.type === "submit" || !controllerRef.current) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+      }
+    };
+    for (const type of GUARDED_EVENTS)
+      document.addEventListener(type, guard, true);
+    return () => {
+      for (const type of GUARDED_EVENTS)
+        document.removeEventListener(type, guard, true);
+    };
+  }, [enabled]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: retry intentionally tears down and reconnects the bridge.
+  useEffect(() => {
+    if (!editorOrigin || !templateName) return;
+    let disposed = false;
+    let unmountObservers = () => {};
+    const leaveDesignMode = enterDesignMode();
+    setError(null);
+    const timeout = window.setTimeout(
+      () =>
+        setError("Editor connection timed out. Retry the preview connection."),
+      CONNECT_TIMEOUT_MS,
+    );
+    void (async () => {
+      const [{ mountFrameBridge }, selection, visiblePaths, bootstrap] =
+        await Promise.all([
+          import("../editor/frame"),
+          import("../editor/selection"),
+          import("../editor/visible-paths"),
+          handlers.current.getBootstrap(),
+        ]);
+      if (disposed) return;
+      // Both must listen before the bridge does: selection so a component can
+      // reveal the selected tab before it is measured, visible paths so a
+      // hidden responsive copy never shadows the visible one.
+      const unmountSelection = selection.mountEditorSelection(window, (path) =>
+        flushSync(() => setSelectedPath(path)),
+      );
+      const unmountVisiblePaths = visiblePaths.mountVisiblePaths(window, () =>
+        controllerRef.current?.reportRects(),
+      );
+      unmountObservers = () => {
+        unmountVisiblePaths();
+        unmountSelection();
+      };
+      window.clearTimeout(timeout);
+      setError(null);
+      controllerRef.current = mountFrameBridge({
+        editorOrigin,
+        templateName,
+        hash: bootstrap.manifest.hash,
+        capabilities: [
+          "editor-bootstrap-v1",
+          "apply-template-v1",
+          "apply-groups-v1",
+          "apply-settings-v1",
+          "preview-navigation-v1",
+        ],
+        getManifest: () => bootstrap.manifest,
+        getBootstrap: () => bootstrap,
+        applyTemplate: async (payload) => {
+          if (payload.templateName !== templateName) return false;
+          const sequence = ++sequenceRef.current;
+          try {
+            const content = await withDeadline(
+              handlers.current.renderTemplate({
+                templateName,
+                template: payload.template,
+                groups: payload.groups,
+                pathname: window.location.pathname + window.location.search,
+              }),
+              renderTimeoutMs,
+            );
+            // A newer edit is already rendering: this result is stale.
+            if (disposed || sequence !== sequenceRef.current) return true;
+            setRegions((current) => ({ ...current, ...content }));
+            if (payload.settingsData)
+              handlers.current.applySettings?.(
+                payload.settingsData,
+                document.documentElement,
+              );
+            setError(null);
+            return true;
+          } catch (cause) {
+            if (!disposed && sequence === sequenceRef.current)
+              setError(
+                cause instanceof Error
+                  ? cause.message
+                  : "Preview could not update",
+              );
+            throw cause;
+          }
+        },
+      });
+    })().catch((cause: unknown) => {
+      window.clearTimeout(timeout);
+      if (!disposed)
+        setError(
+          cause instanceof Error ? cause.message : "Editor connection failed",
+        );
+    });
+    return () => {
+      disposed = true;
+      sequenceRef.current++;
+      window.clearTimeout(timeout);
+      controllerRef.current?.unmount();
+      controllerRef.current = null;
+      unmountObservers();
+      leaveDesignMode();
+    };
+  }, [editorOrigin, templateName, retry, renderTimeoutMs]);
+
+  // Measure after each committed region replacement.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: regions is the trigger.
+  useEffect(() => {
+    controllerRef.current?.reportRects();
+  }, [regions]);
+
+  const register = (name: string) => {
+    setTemplateName(name);
+    return () =>
+      setTemplateName((current) => (current === name ? null : current));
+  };
+
+  return (
+    <PreviewContext.Provider
+      value={{ enabled, selectedPath, regions, register }}
+    >
+      {children}
+      {enabled && error ? (
+        <div
+          role="alert"
+          style={{
+            position: "fixed",
+            left: 16,
+            right: 16,
+            bottom: 16,
+            zIndex: 2147483647,
+            padding: 16,
+            background: "#fff1f0",
+            color: "#8b1b16",
+            border: "1px solid #c63225",
+          }}
+        >
+          {error}{" "}
+          <button
+            type="button"
+            data-z-editor-retry
+            onClick={() => setRetry((value) => value + 1)}
+          >
+            Retry
+          </button>
+        </div>
+      ) : null}
+    </PreviewContext.Provider>
+  );
+}
+
+function useRegion(key: string, children: ReactNode): ReactNode {
+  const context = useContext(PreviewContext);
+  return context?.enabled && Object.hasOwn(context.regions, key)
+    ? context.regions[key]
+    : children;
+}
+
+/** The page's template. Also tells the provider which template this route is. */
+export function EditorTemplateRegion({
+  name,
+  children,
+}: {
+  name: string;
+  children: ReactNode;
+}) {
+  const context = useContext(PreviewContext);
+  // Registration follows route identity, not every update of preview state.
+  const registerRef = useRef(context?.register);
+  registerRef.current = context?.register;
+  useEffect(() => registerRef.current?.(name), [name]);
+  return useRegion(`template:${name}`, children);
+}
+
+/** A section group (header-group, footer-group). */
+export function EditorGroupRegion({
+  name,
+  children,
+}: {
+  name: string;
+  children: ReactNode;
+}) {
+  return useRegion(`group:${name}`, children);
+}
+
+/** True inside a trusted editor frame, after hydration. */
+export function useEditorPreview(): boolean {
+  return useContext(PreviewContext)?.enabled ?? false;
+}
+
+/** The editor's selected `data-z-path`, so a component can reveal it. */
+export function useEditorSelection(): string | null {
+  const context = useContext(PreviewContext);
+  return context?.enabled ? context.selectedPath : null;
+}

package/src/react/useEditorTemplate.ts

@@ -6,10 +6,14 @@ import type { FrameBridgeController } from "../editor/frame";
 import type { PreviewContext } from "../schemas/bridge";
 import type { EditorDocuments } from "../editor/bootstrap";
 import { getThemeStore, setThemePreview } from "./engine/store";
-import { resolveEditorOrigin } from "./editor-origin";
+import { resolveEditorOrigin, ZALIFY_EDITOR_ORIGINS } from "./editor-origin";
+
+export { ZALIFY_EDITOR_ORIGINS };
+import { enterDesignMode } from "./design-mode";
 
 type Options = {
-  origins: readonly string[];
+  /** Defaults to {@link ZALIFY_EDITOR_ORIGINS}. */
+  origins?: readonly string[];
   loadManifest: () => Promise<ThemeEditorManifest>;
   /** Authoritative, repository-relative merchant data targets. */
   paths: EditorDocuments;
@@ -29,8 +33,11 @@ export function useEditorTemplate(
   const controller = useRef<FrameBridgeController | null>(null);
   useEffect(() => {
     setDraft(null);
-    const parentOrigin = resolveEditorOrigin(options.origins);
+    const parentOrigin = resolveEditorOrigin(
+      options.origins ?? ZALIFY_EDITOR_ORIGINS,
+    );
     if (!parentOrigin) return;
+    const leaveDesignMode = enterDesignMode();
     let disposed = false;
     const owner = getThemeStore();
     void Promise.all([
@@ -114,6 +121,7 @@ export function useEditorTemplate(
       });
     return () => {
       disposed = true;
+      leaveDesignMode();
       controller.current?.unmount();
       controller.current = null;
       setThemePreview(owner, null);