@decocms/start 0.19.0

package/src/hooks/DecoPageRenderer.tsx

@@ -0,0 +1,444 @@
+import {
+  type ComponentType,
+  createElement,
+  lazy,
+  type ReactNode,
+  Suspense,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import type { SectionOptions } from "../cms/registry";
+import {
+  getResolvedComponent,
+  getSectionOptions,
+  getSectionRegistry,
+  getSyncComponent,
+  preloadSectionModule,
+  setResolvedComponent,
+} from "../cms/registry";
+import type { DeferredSection, ResolvedSection } from "../cms/resolve";
+import { SectionErrorBoundary } from "./SectionErrorFallback";
+
+type LazyComponent = ReturnType<typeof lazy>;
+
+const lazyCache = new Map<string, LazyComponent>();
+
+/**
+ * Create a React.lazy-compatible thenable that is already fulfilled.
+ * React internally checks `thenable.status === "fulfilled"` and reads
+ * `thenable.value` synchronously — no Suspense activation, no microtask.
+ */
+function syncThenable(mod: {
+  default: ComponentType<any>;
+}): Promise<{ default: ComponentType<any> }> {
+  const t = Promise.resolve(mod);
+  // React uses these internal properties to detect sync-resolved thenables
+  (t as any).status = "fulfilled";
+  (t as any).value = mod;
+  return t;
+}
+
+function getLazyComponent(key: string) {
+  if (!lazyCache.has(key)) {
+    const registry = getSectionRegistry();
+    const loader = registry[key];
+    if (!loader) return null;
+    lazyCache.set(
+      key,
+      lazy(() => {
+        // If already resolved (from preloadSectionComponents on server,
+        // or from route loader on client SPA), return a sync thenable.
+        // React reads thenable.status/value synchronously — no Suspense.
+        const resolved = getResolvedComponent(key);
+        if (resolved) {
+          return syncThenable({ default: resolved });
+        }
+
+        return (loader as () => Promise<{ default: ComponentType<any> }>)().then((mod) => {
+          if (!mod?.default) {
+            console.error(`[DecoSection] "${key}" has no default export`, Object.keys(mod ?? {}));
+            return { default: () => null } as { default: ComponentType<any> };
+          }
+          setResolvedComponent(key, mod.default);
+          return mod as { default: ComponentType<any> };
+        });
+      }),
+    );
+  }
+  return lazyCache.get(key)!;
+}
+
+function DefaultSectionFallback() {
+  return <div className="w-full h-48 bg-base-200 animate-pulse rounded" />;
+}
+
+function NestedSectionFallback() {
+  return <div className="w-full h-24 bg-base-200 animate-pulse rounded" />;
+}
+
+import { isDevMode } from "../sdk/env";
+
+const isDev = isDevMode();
+
+const DEFERRED_FADE_CSS = `@keyframes decoFadeIn{from{opacity:0}to{opacity:1}}`;
+
+function FadeInStyle() {
+  return <style dangerouslySetInnerHTML={{ __html: DEFERRED_FADE_CSS }} />;
+}
+
+function DevMissingFallbackWarning({ component }: { component: string }) {
+  if (!isDev) return null;
+  return (
+    <div
+      style={{
+        position: "relative",
+        border: "2px dashed #e53e3e",
+        borderRadius: 8,
+        padding: 8,
+        margin: "4px 0",
+      }}
+    >
+      <div
+        style={{
+          fontSize: 11,
+          color: "#e53e3e",
+          fontFamily: "monospace",
+          marginBottom: 4,
+        }}
+      >
+        [AsyncRender] Missing LoadingFallback for &quot;{component}&quot;.
+        <br />
+        Export a LoadingFallback from your section for better UX.
+        <br />
+        See: https://deco.cx/docs/async-rendering
+      </div>
+      <DefaultSectionFallback />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Section type — same shape as deco-cx/deco (Fresh): { Component, props }
+// ---------------------------------------------------------------------------
+
+interface Section {
+  Component: string | ComponentType<any>;
+  props: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// SectionRenderer — renders a single nested section
+// ---------------------------------------------------------------------------
+
+export function SectionRenderer({ section }: { section: Section | null | undefined }) {
+  if (!section?.Component) return null;
+
+  if (typeof section.Component === "function") {
+    const Comp = section.Component;
+    return <Comp {...(section.props ?? {})} />;
+  }
+
+  const Lazy = getLazyComponent(section.Component);
+  if (!Lazy) {
+    console.warn(`[SectionRenderer] No component registered for: ${section.Component}`);
+    return null;
+  }
+
+  return (
+    <Suspense fallback={<NestedSectionFallback />}>
+      <Lazy {...(section.props ?? {})} />
+    </Suspense>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// SectionList — renders an array of nested sections
+// ---------------------------------------------------------------------------
+
+export function SectionList({ sections }: { sections: Section[] | null | undefined }) {
+  if (!sections?.length) return null;
+  return (
+    <>
+      {sections.map((section, i) => {
+        const key = typeof section.Component === "string" ? section.Component : `nested-${i}`;
+        return <SectionRenderer key={key} section={section} />;
+      })}
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// DeferredSectionWrapper — loads a section when it scrolls into view
+// ---------------------------------------------------------------------------
+
+interface DeferredSectionWrapperProps {
+  deferred: DeferredSection;
+  pagePath: string;
+  loadingFallback?: ReactNode;
+  errorFallback?: ReactNode;
+  loadFn: (data: {
+    component: string;
+    rawProps: Record<string, unknown>;
+    pagePath: string;
+  }) => Promise<ResolvedSection | null>;
+}
+
+function DeferredSectionWrapper({
+  deferred,
+  pagePath,
+  loadingFallback,
+  errorFallback,
+  loadFn,
+}: DeferredSectionWrapperProps) {
+  const stableKey = `${pagePath}::${deferred.component}::${deferred.index}`;
+  const [section, setSection] = useState<ResolvedSection | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [loadedOptions, setLoadedOptions] = useState<SectionOptions | undefined>(() =>
+    getSectionOptions(deferred.component),
+  );
+  const isSSR = typeof document === "undefined";
+  const [optionsReady, setOptionsReady] = useState(() =>
+    isSSR ? false : !!getSectionOptions(deferred.component),
+  );
+  const ref = useRef<HTMLDivElement>(null);
+  const triggered = useRef(false);
+  const prevKeyRef = useRef(stableKey);
+
+  if (prevKeyRef.current !== stableKey) {
+    prevKeyRef.current = stableKey;
+    triggered.current = false;
+    if (section) setSection(null);
+    if (error) setError(null);
+  }
+
+  useEffect(() => {
+    if (optionsReady) return;
+    preloadSectionModule(deferred.component).then((opts) => {
+      if (opts) setLoadedOptions(opts);
+      setOptionsReady(true);
+    });
+  }, [deferred.component, optionsReady]);
+
+  const hasCustomFallback = !!loadedOptions?.loadingFallback;
+  const skeleton = !optionsReady
+    ? null
+    : hasCustomFallback
+      ? createElement(loadedOptions!.loadingFallback!)
+      : (loadingFallback ??
+        (isDev ? (
+          <DevMissingFallbackWarning component={deferred.component} />
+        ) : (
+          <DefaultSectionFallback />
+        )));
+
+  useEffect(() => {
+    if (triggered.current || section) return;
+
+    const el = ref.current;
+    if (!el) return;
+
+    if (typeof IntersectionObserver === "undefined") {
+      triggered.current = true;
+      loadFn({
+        component: deferred.component,
+        rawProps: deferred.rawProps,
+        pagePath,
+      })
+        .then(setSection)
+        .catch((e) => setError(e));
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry?.isIntersecting && !triggered.current) {
+          triggered.current = true;
+          observer.disconnect();
+          loadFn({
+            component: deferred.component,
+            rawProps: deferred.rawProps,
+            pagePath,
+          })
+            .then(setSection)
+            .catch((e) => setError(e));
+        }
+      },
+      { rootMargin: "300px" },
+    );
+
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [deferred.component, deferred.rawProps, pagePath, section, loadFn]);
+
+  if (error) {
+    const errFallback = loadedOptions?.errorFallback
+      ? createElement(loadedOptions.errorFallback, { error })
+      : errorFallback;
+    return <>{errFallback ?? null}</>;
+  }
+
+  if (section) {
+    const sectionId = section.key
+      .replace(/\//g, "-")
+      .replace(/\.tsx$/, "")
+      .replace(/^site-sections-/, "");
+
+    const LazyComponent = getLazyComponent(section.component);
+    if (!LazyComponent) return null;
+
+    return (
+      <section
+        id={sectionId}
+        data-manifest-key={section.key}
+        style={{ animation: "decoFadeIn 0.3s ease-out" }}
+      >
+        <SectionErrorBoundary sectionKey={section.key} fallback={errorFallback}>
+          <Suspense fallback={skeleton}>
+            <LazyComponent {...section.props} />
+          </Suspense>
+        </SectionErrorBoundary>
+      </section>
+    );
+  }
+
+  const sectionId = deferred.key
+    .replace(/\//g, "-")
+    .replace(/\.tsx$/, "")
+    .replace(/^site-sections-/, "");
+
+  return (
+    <section ref={ref} id={sectionId} data-manifest-key={deferred.key} data-deferred="true">
+      {skeleton}
+    </section>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Merge helper — combines eager and deferred sections in original order
+// ---------------------------------------------------------------------------
+
+type PageItem =
+  | { type: "eager"; section: ResolvedSection; originalIndex: number }
+  | { type: "deferred"; deferred: DeferredSection };
+
+function mergeSections(resolved: ResolvedSection[], deferred: DeferredSection[]): PageItem[] {
+  if (!resolved?.length && !deferred?.length) return [];
+  const safeResolved = resolved ?? [];
+  const safeDeferred = deferred ?? [];
+
+  if (!safeDeferred.length) {
+    return safeResolved.map((s, i) => ({ type: "eager", section: s, originalIndex: i }));
+  }
+
+  // Use the `index` property stamped by resolveDecoPage to sort all
+  // sections (eager + deferred) back into their original CMS order.
+  const items: (PageItem & { _sort: number })[] = [];
+
+  for (let i = 0; i < safeResolved.length; i++) {
+    const s = safeResolved[i];
+    items.push({ type: "eager", section: s, originalIndex: i, _sort: s.index ?? i });
+  }
+
+  for (const d of safeDeferred) {
+    items.push({ type: "deferred", deferred: d, _sort: d.index } as PageItem & { _sort: number });
+  }
+
+  items.sort((a, b) => a._sort - b._sort);
+
+  return items;
+}
+
+// ---------------------------------------------------------------------------
+// DecoPageRenderer — renders top-level resolved sections from a CMS page
+// ---------------------------------------------------------------------------
+
+interface Props {
+  sections: ResolvedSection[];
+  deferredSections?: DeferredSection[];
+  pagePath?: string;
+  loadingFallback?: ReactNode;
+  errorFallback?: ReactNode;
+  loadDeferredSectionFn?: (data: {
+    component: string;
+    rawProps: Record<string, unknown>;
+    pagePath: string;
+  }) => Promise<ResolvedSection | null>;
+}
+
+export function DecoPageRenderer({
+  sections,
+  deferredSections,
+  pagePath = "/",
+  loadingFallback,
+  errorFallback,
+  loadDeferredSectionFn,
+}: Props) {
+  const items = mergeSections(sections ?? [], deferredSections ?? []);
+  const hasDeferred = deferredSections && deferredSections.length > 0;
+
+  return (
+    <>
+      {hasDeferred && <FadeInStyle />}
+      {items.map((item, index) => {
+        if (item.type === "deferred") {
+          if (!loadDeferredSectionFn) {
+            return null;
+          }
+          return (
+            <DeferredSectionWrapper
+              key={`deferred-${pagePath}-${item.deferred.key}-${item.deferred.index}`}
+              deferred={item.deferred}
+              pagePath={pagePath}
+              loadingFallback={loadingFallback}
+              errorFallback={errorFallback}
+              loadFn={loadDeferredSectionFn}
+            />
+          );
+        }
+
+        const { section } = item;
+
+        const options = getSectionOptions(section.component);
+        const errFallback = options?.errorFallback
+          ? createElement(options.errorFallback, { error: new Error("") })
+          : errorFallback;
+
+        const sectionId = section.key
+          .replace(/\//g, "-")
+          .replace(/\.tsx$/, "")
+          .replace(/^site-sections-/, "");
+
+        // Only use sync path for sections explicitly registered via registerSectionsSync.
+        // DO NOT fallback to getResolvedComponent: that is populated server-side by
+        // preloadSectionComponents but NOT on the client, causing hydration mismatches
+        // (server renders <ul>, client renders <Suspense> for the same component).
+        const SyncComp = getSyncComponent(section.component);
+        if (SyncComp) {
+          return (
+            <section key={`${section.key}-${index}`} id={sectionId} data-manifest-key={section.key}>
+              <SectionErrorBoundary sectionKey={section.key} fallback={errFallback}>
+                <SyncComp {...section.props} />
+              </SectionErrorBoundary>
+            </section>
+          );
+        }
+
+        // Fallback: React.lazy with syncThenable for pre-loaded modules.
+        // fallback={null} preserves server HTML during hydration.
+        const LazyComponent = getLazyComponent(section.component);
+        if (!LazyComponent) return null;
+
+        return (
+          <section key={`${section.key}-${index}`} id={sectionId} data-manifest-key={section.key}>
+            <SectionErrorBoundary sectionKey={section.key} fallback={errFallback}>
+              <Suspense fallback={null}>
+                <LazyComponent {...section.props} />
+              </Suspense>
+            </SectionErrorBoundary>
+          </section>
+        );
+      })}
+    </>
+  );
+}

package/src/hooks/LazySection.tsx

@@ -0,0 +1,109 @@
+/**
+ * LazySection -- Intersection Observer-based deferred rendering.
+ *
+ * Wraps section content and defers rendering until the element scrolls
+ * into view. Uses IntersectionObserver for zero-JS-cost detection and
+ * renders a lightweight placeholder until the content is needed.
+ *
+ * For SSR: the placeholder is rendered server-side. On hydration,
+ * the observer is set up and content loads when visible.
+ *
+ * @example
+ * ```tsx
+ * <LazySection fallback={<div style={{ height: 400 }} />}>
+ *   <HeavyProductCarousel products={products} />
+ * </LazySection>
+ * ```
+ */
+
+import { type ReactNode, useEffect, useRef, useState } from "react";
+
+export interface LazySectionProps {
+  children: ReactNode;
+  /**
+   * Content shown before the section scrolls into view.
+   * Should have a fixed height to prevent layout shifts.
+   */
+  fallback?: ReactNode;
+  /**
+   * IntersectionObserver rootMargin.
+   * Positive values trigger loading before the element is visible.
+   * @default "200px"
+   */
+  rootMargin?: string;
+  /**
+   * Minimum height for the wrapper div (prevents CLS).
+   * Applied as CSS min-height.
+   */
+  minHeight?: string | number;
+  /**
+   * CSS class for the wrapper div.
+   */
+  className?: string;
+  /**
+   * If true, render the content immediately (bypass lazy loading).
+   * Useful for sections above the fold.
+   * @default false
+   */
+  eager?: boolean;
+}
+
+export function LazySection({
+  children,
+  fallback,
+  rootMargin = "200px",
+  minHeight,
+  className,
+  eager = false,
+}: LazySectionProps) {
+  const [isVisible, setVisible] = useState(eager);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (eager || isVisible) return;
+
+    const element = ref.current;
+    if (!element) return;
+
+    if (typeof IntersectionObserver === "undefined") {
+      setVisible(true);
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry?.isIntersecting) {
+          setVisible(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin },
+    );
+
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [eager, isVisible, rootMargin]);
+
+  const style: React.CSSProperties | undefined = minHeight
+    ? { minHeight: typeof minHeight === "number" ? `${minHeight}px` : minHeight }
+    : undefined;
+
+  return (
+    <div ref={ref} className={className} style={style}>
+      {isVisible ? children : (fallback ?? null)}
+    </div>
+  );
+}
+
+/**
+ * Determine if a section index is "below the fold" and should be lazy-loaded.
+ *
+ * Used by DecoPageRenderer to auto-wrap distant sections.
+ *
+ * @param index - Zero-based section index on the page
+ * @param foldThreshold - Sections at or above this index render eagerly
+ * @default foldThreshold = 3
+ */
+export function isBelowFold(index: number, foldThreshold = 3): boolean {
+  return index >= foldThreshold;
+}

package/src/hooks/LiveControls.tsx

@@ -0,0 +1,108 @@
+import React from "react";
+
+interface LiveControlsProps {
+  site?: string;
+  page?: { id?: string; pathTemplate?: string };
+  flags?: any[];
+}
+
+/**
+ * LiveControls bridges the deco admin (parent window) with the storefront (iframe).
+ *
+ * Mirrors production behavior (apps/website/components/_Controls.tsx):
+ * 1. Injects __DECO_STATE for the admin to read
+ * 2. Listens for postMessage events from the admin (inject scripts, scroll, rerender)
+ * 3. "." opens admin in same tab, Ctrl/Cmd+"." opens in new tab, Ctrl+Shift+E also works
+ */
+export function LiveControls({ site, page, flags }: LiveControlsProps) {
+  return (
+    <>
+      <script
+        id="__DECO_STATE"
+        type="application/json"
+        dangerouslySetInnerHTML={{
+          __html: JSON.stringify({
+            page: page || {},
+            site: { name: site || "storefront" },
+            flags: flags || [],
+          }),
+        }}
+      />
+      <LiveControlsScript />
+    </>
+  );
+}
+
+function LiveControlsScript() {
+  const script = `
+    (function() {
+      if (window.__DECO_LIVE_CONTROLS__) return;
+      window.__DECO_LIVE_CONTROLS__ = true;
+
+      var LIVE = JSON.parse(document.getElementById("__DECO_STATE")?.textContent || "{}");
+      window.LIVE = { ...window.LIVE, ...LIVE };
+
+      window.addEventListener("message", function(event) {
+        var data = event.data;
+        if (!data || typeof data !== "object") return;
+
+        switch (data.type) {
+          case "editor::inject":
+            if (data.args && data.args.script) {
+              try { eval(data.args.script); } catch(e) { console.error("[deco] inject error:", e); }
+            }
+            break;
+
+          case "scrollToComponent":
+            var el = document.querySelector('[data-manifest-key="' + data.args?.id + '"]');
+            if (!el) el = document.getElementById(data.args?.id);
+            if (el) el.scrollIntoView({ behavior: "smooth", block: "center" });
+            break;
+
+          case "DOMInspector":
+            break;
+
+          case "editor::rerender":
+            if (data.args?.url) {
+              window.location.href = data.args.url;
+            }
+            break;
+        }
+      });
+
+      if (window.self === window.top) {
+        document.body.addEventListener("keydown", function(e) {
+          if (e.target !== document.body) return;
+          if (e.defaultPrevented) return;
+
+          if (
+            (e.ctrlKey && e.shiftKey && e.key === "E") ||
+            e.key === "."
+          ) {
+            e.preventDefault();
+            e.stopPropagation();
+
+            var siteName = (window.LIVE.site && window.LIVE.site.name) || window.LIVE.site || "storefront";
+            var pageId = (window.LIVE.page && window.LIVE.page.id) || "";
+            var pathTemplate = (window.LIVE.page && window.LIVE.page.pathTemplate) || "/*";
+
+            var href = new URL("/choose-editor", "https://admin.deco.cx");
+            href.searchParams.set("site", siteName);
+            href.searchParams.set("domain", window.location.origin);
+            if (pageId) href.searchParams.set("pageId", pageId);
+            href.searchParams.set("path", encodeURIComponent(window.location.pathname + window.location.search));
+            href.searchParams.set("pathTemplate", encodeURIComponent(pathTemplate));
+
+            if ((e.ctrlKey || e.metaKey) && e.key === ".") {
+              window.open(href.toString(), "_blank");
+              return;
+            }
+            window.location.href = href.toString();
+          }
+        });
+      }
+    })();
+  `;
+
+  return <script type="module" dangerouslySetInnerHTML={{ __html: script }} />;
+}