@decocms/blocks 7.0.0

package/src/cms/sectionMixins.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Section mixins — focused on `withSectionLoader` since the device/mobile
+ * mixins are exercised by sectionLoaders integration tests already.
+ */
+import { describe, expect, it, vi } from "vitest";
+import {
+  compose,
+  withDevice,
+  withMobile,
+  withSearchParam,
+  withSectionLoader,
+} from "./sectionMixins";
+
+// `__requestDependent` is the runtime tag the framework reads in
+// `registerSectionLoaders` to decide whether to emit the layout-cache
+// contamination warning (#206). Any future mixin that depends on the
+// request must opt in by setting this flag — and `compose` must propagate
+// it whenever any input has it.
+const isRequestDependent = (fn: unknown): boolean =>
+  typeof fn === "function" &&
+  (fn as { __requestDependent?: boolean }).__requestDependent === true;
+
+const makeReq = (url = "https://store.example/foo?q=hello") =>
+  new Request(url, { headers: { "user-agent": "vitest" } });
+
+describe("withSectionLoader", () => {
+  it("invokes the section's exported loader and returns its result", async () => {
+    const loader = vi.fn(async (props: Record<string, unknown>) => ({
+      ...props,
+      url: "https://store.example/foo?q=hello",
+      enriched: true,
+    }));
+
+    const mixin = withSectionLoader(async () => ({ loader }));
+    const result = await mixin({ original: "value" }, makeReq());
+
+    expect(loader).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({
+      original: "value",
+      url: "https://store.example/foo?q=hello",
+      enriched: true,
+    });
+  });
+
+  it("returns props unchanged when module has no loader export", async () => {
+    const mixin = withSectionLoader(async () => ({ default: () => null }));
+    const props = { foo: "bar" };
+    const result = await mixin(props, makeReq());
+    expect(result).toBe(props);
+  });
+
+  it("returns props unchanged when module is undefined / loader is not a function", async () => {
+    const mixin = withSectionLoader(async () => undefined);
+    const props = { foo: "bar" };
+    expect(await mixin(props, makeReq())).toBe(props);
+
+    const mixinWithBadLoader = withSectionLoader(async () => ({
+      loader: "not-a-function",
+    }));
+    expect(await mixinWithBadLoader(props, makeReq())).toBe(props);
+  });
+
+  it("swallows loader errors and returns the original props", async () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mixin = withSectionLoader(async () => ({
+      loader: async () => {
+        throw new Error("boom");
+      },
+    }));
+    const props = { foo: "bar" };
+    const result = await mixin(props, makeReq());
+    expect(result).toBe(props);
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[withSectionLoader] section loader threw:",
+      expect.any(Error),
+    );
+    errorSpy.mockRestore();
+  });
+
+  it("falls back to original props when loader returns undefined", async () => {
+    const mixin = withSectionLoader(async () => ({
+      loader: async () => undefined,
+    }));
+    const props = { foo: "bar" };
+    expect(await mixin(props, makeReq())).toBe(props);
+  });
+
+  it("composes alongside mixins: mixins run first, then the section loader sees the enriched props", async () => {
+    const seen: Array<Record<string, unknown>> = [];
+    const sectionLoader = vi.fn(
+      async (props: Record<string, unknown>) => {
+        seen.push({ ...props });
+        return { ...props, sectionLoaderRan: true };
+      },
+    );
+
+    const composed = compose(
+      withSearchParam(),
+      withSectionLoader(async () => ({ loader: sectionLoader })),
+    );
+
+    const result = await composed({ original: 1 }, makeReq());
+
+    expect(seen).toHaveLength(1);
+    // The section loader sees the enriched props (currentSearchParam injected by withSearchParam)
+    expect(seen[0]).toMatchObject({
+      original: 1,
+      currentSearchParam: "hello",
+    });
+    expect(result).toMatchObject({
+      original: 1,
+      currentSearchParam: "hello",
+      sectionLoaderRan: true,
+    });
+  });
+
+  it("loads the module lazily — modImport is only called on first invocation", async () => {
+    const modImport = vi.fn(async () => ({
+      loader: async (p: Record<string, unknown>) => ({ ...p, ran: true }),
+    }));
+    const mixin = withSectionLoader(modImport);
+    expect(modImport).not.toHaveBeenCalled();
+
+    await mixin({ a: 1 }, makeReq());
+    expect(modImport).toHaveBeenCalledTimes(1);
+
+    // A second invocation calls the import again — caching is the
+    // dynamic import's responsibility (which the runtime memoises).
+    await mixin({ a: 2 }, makeReq());
+    expect(modImport).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("request-dependent tagging (#206)", () => {
+  it("tags withDevice", () => {
+    expect(isRequestDependent(withDevice())).toBe(true);
+  });
+
+  it("tags withMobile", () => {
+    expect(isRequestDependent(withMobile())).toBe(true);
+  });
+
+  it("tags withSearchParam", () => {
+    expect(isRequestDependent(withSearchParam())).toBe(true);
+  });
+
+  it("does NOT tag withSectionLoader (its loader may or may not touch req)", () => {
+    expect(isRequestDependent(withSectionLoader(async () => ({})))).toBe(false);
+  });
+
+  it("compose propagates the flag when any input is request-dependent", () => {
+    expect(isRequestDependent(compose(withDevice(), async (p) => p))).toBe(true);
+    expect(isRequestDependent(compose(async (p) => p, withSearchParam()))).toBe(true);
+  });
+
+  it("compose does NOT set the flag when no input is request-dependent", () => {
+    expect(isRequestDependent(compose(async (p) => p, async (p) => p))).toBe(false);
+  });
+
+  it("empty compose() is not request-dependent", () => {
+    expect(isRequestDependent(compose())).toBe(false);
+  });
+});

package/src/cms/sectionMixins.ts

@@ -0,0 +1,153 @@
+/**
+ * Section Loader Mixins
+ *
+ * Reusable section loader factories for common patterns like device detection,
+ * mobile flag injection, and search param extraction. Eliminates repetitive
+ * `(props, req) => ({ ...props, device: detectDevice(...) })` boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { withDevice, withMobile, compose } from "@decocms/start/cms";
+ *
+ * registerSectionLoaders({
+ *   "site/sections/Product/ProductShelf.tsx": withDevice(),
+ *   "site/sections/Images/Carousel.tsx": withMobile(),
+ *   "site/sections/Header/Header.tsx": compose(withDevice(), withSearchParam()),
+ * });
+ * ```
+ */
+import { detectDevice } from "../sdk/useDevice";
+import type { SectionLoaderFn } from "./sectionLoaders";
+
+/**
+ * Mixins that derive props from the incoming request (UA, search params,
+ * cookies, geo, segment) carry this flag so the framework can warn when a
+ * site accidentally combines them with a layout-cached section — the layout
+ * cache is keyed only by component path, so the first visitor's variant
+ * would be served to all viewers for the cache TTL. See #206.
+ */
+type TaggedSectionLoaderFn = SectionLoaderFn & { __requestDependent?: boolean };
+
+function tagRequestDependent(fn: SectionLoaderFn): SectionLoaderFn {
+  (fn as TaggedSectionLoaderFn).__requestDependent = true;
+  return fn;
+}
+
+/**
+ * Injects `device: "mobile" | "desktop" | "tablet"` from the request User-Agent.
+ */
+export function withDevice(): SectionLoaderFn {
+  return tagRequestDependent((props, req) => ({
+    ...props,
+    device: detectDevice(req.headers.get("user-agent") ?? ""),
+  }));
+}
+
+/**
+ * Injects `isMobile: boolean` (true for mobile and tablet) from the request User-Agent.
+ */
+export function withMobile(): SectionLoaderFn {
+  return tagRequestDependent((props, req) => {
+    const d = detectDevice(req.headers.get("user-agent") ?? "");
+    return { ...props, isMobile: d === "mobile" || d === "tablet" };
+  });
+}
+
+const REGEX_QUERY_VALUE = /[?&]q=([^&]*)/;
+
+/**
+ * Injects `currentSearchParam: string | undefined` extracted from the `?q=` URL parameter.
+ */
+export function withSearchParam(): SectionLoaderFn {
+  return tagRequestDependent((props, req) => {
+    const match = req.url.match(REGEX_QUERY_VALUE);
+    return {
+      ...props,
+      currentSearchParam: match ? decodeURIComponent(match[1]) : undefined,
+    };
+  });
+}
+
+/**
+ * Composes multiple section loader mixins into a single loader.
+ * Each mixin's result is merged left-to-right (later mixins override earlier ones).
+ *
+ * Propagates the `__requestDependent` flag from any input mixin so the
+ * layout-cache contamination warning (#206) fires even when a request-
+ * dependent mixin is hidden inside a compose() chain.
+ *
+ * @example
+ * ```ts
+ * compose(withDevice(), withSearchParam())
+ * // Equivalent to: (props, req) => ({ ...props, device: ..., currentSearchParam: ... })
+ * ```
+ */
+export function compose(...mixins: SectionLoaderFn[]): SectionLoaderFn {
+  const composed: SectionLoaderFn = async (props, req) => {
+    let result = { ...props };
+    for (const mixin of mixins) {
+      const partial = await mixin(result, req);
+      result = { ...result, ...partial };
+    }
+    return result;
+  };
+  if (mixins.some((m) => (m as TaggedSectionLoaderFn).__requestDependent)) {
+    (composed as TaggedSectionLoaderFn).__requestDependent = true;
+  }
+  return composed;
+}
+
+/**
+ * Wraps a section module's exported `loader` so it can be composed alongside
+ * mixins like {@link withDevice}, {@link withMobile}, {@link withSearchParam}.
+ *
+ * The `modImport` argument is a lazy factory (typically `() => import("~/sections/...")`)
+ * — the module is loaded on first call. If the module does not export a
+ * `loader`, the original `props` are returned unchanged (no-op).
+ *
+ * Why this exists: the migrator and many sites lifted from Fresh declare a
+ * `loader` export on the section file (often re-exported from the inner
+ * component). That loader sets things like `url: req.url`, runs platform
+ * invocations, or calls the section's domain logic. If the section is wired
+ * in `registerSectionLoaders` with mixin-only (e.g. `withSearchParam()`),
+ * the section's own loader is silently *replaced* — its work never runs and
+ * its returned props are dropped.
+ *
+ * Compose this helper FIRST in the chain so mixin-injected props
+ * (`device`, `currentSearchParam`, …) are available to the section's loader,
+ * then the section's loader has the final word over what is returned.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   compose,
+ *   withMobile,
+ *   withSearchParam,
+ *   withSectionLoader,
+ * } from "@decocms/start/cms";
+ *
+ * registerSectionLoaders({
+ *   "site/sections/Product/SearchContainerV2.tsx": compose(
+ *     withMobile(),
+ *     withSearchParam(),
+ *     withSectionLoader(() => import("~/sections/Product/SearchContainerV2")),
+ *   ),
+ * });
+ * ```
+ */
+export function withSectionLoader(
+  modImport: () => Promise<unknown>,
+): SectionLoaderFn {
+  return async (props, req) => {
+    const mod = (await modImport()) as { loader?: unknown } | undefined;
+    const loader = mod?.loader;
+    if (typeof loader !== "function") return props;
+    try {
+      const result = await (loader as SectionLoaderFn)(props, req);
+      return result ?? props;
+    } catch (error) {
+      console.error("[withSectionLoader] section loader threw:", error);
+      return props;
+    }
+  };
+}

package/src/hooks/LazySection.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+/**
+ * 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>
+ * ```
+ *
+ * `"use client"` added by Phase 2 Task 9 (@decocms/nextjs's next-smoke
+ * fixture): this file uses `useEffect`/`useRef`/`useState`, which Next's App
+ * Router statically rejects in any file reachable from a Server Component's
+ * module graph unless the file itself declares the client boundary. Neither
+ * `@decocms/tanstack` (Vite, no RSC directive enforcement) nor this
+ * package's Vitest/jsdom unit tests caught this — `@decocms/nextjs` is the
+ * first consumer to go through Next's real RSC-aware webpack build.
+ */
+
+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 are below the fold.
+ *   Defaults to `Infinity` (nothing below the fold), matching the framework
+ *   default where the admin ⚡ toggle — not position — drives deferral.
+ * @default foldThreshold = Infinity
+ */
+export function isBelowFold(index: number, foldThreshold = Infinity): boolean {
+  return index >= foldThreshold;
+}

package/src/hooks/LiveControls.tsx

@@ -0,0 +1,122 @@
+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 TRUSTED_ORIGINS = ["https://deco.cx", "https://admin.deco.cx", "https://play.deco.cx"];
+      function isTrustedOrigin(origin) {
+        return TRUSTED_ORIGINS.indexOf(origin) !== -1 ||
+          (origin.startsWith("https://") && origin.endsWith(".deco.cx")) ||
+          origin === window.location.origin;
+      }
+
+      var LIVE = JSON.parse(document.getElementById("__DECO_STATE")?.textContent || "{}");
+      window.LIVE = { ...window.LIVE, ...LIVE };
+
+      window.addEventListener("message", function(event) {
+        if (!isTrustedOrigin(event.origin)) return;
+
+        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="' + CSS.escape(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) {
+              try {
+                var targetUrl = new URL(data.args.url, window.location.origin);
+                if (targetUrl.origin === window.location.origin) {
+                  window.location.href = targetUrl.href;
+                }
+              } catch(e) {}
+            }
+            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 }} />;
+}

package/src/hooks/RenderSection.test.tsx

@@ -0,0 +1,81 @@
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { registerSection, registerSectionsSync } from "../cms/registry";
+import RenderSection from "./RenderSection";
+
+// NOTE: each test uses its OWN section key. The registry module captures the
+// `globalThis.__deco.*` objects at module load, so re-assigning them in a
+// beforeEach (the registry.test.ts pattern) does not actually clear the
+// registry this module writes to — and RenderSection additionally keeps a
+// module-level lazy cache keyed by resolveType. Unique keys sidestep both.
+
+function Hero({ label }: { label?: string }) {
+  // Single text node — avoids React's `<!-- -->` separator between
+  // adjacent text/expression children, keeping assertions simple.
+  return <h1>{`hero-${label ?? "none"}`}</h1>;
+}
+
+// A lazy loader that never settles: the lazy path suspends forever, so any
+// content that DOES render must have come from the sync registry.
+const neverResolves = () => new Promise<never>(() => {});
+
+describe("RenderSection sync-first", () => {
+  it("renders a sync-registered section directly (no Suspense fallback)", () => {
+    const KEY = "site/sections/SyncA.tsx";
+    registerSectionsSync({ [KEY]: { default: Hero } });
+
+    const html = renderToString(<RenderSection section={{ __resolveType: KEY, label: "a" }} />);
+    expect(html).toContain("hero-a");
+  });
+
+  it("renders sync for the old { Component: string } shape too", () => {
+    const KEY = "site/sections/SyncB.tsx";
+    registerSectionsSync({ [KEY]: { default: Hero } });
+
+    const html = renderToString(
+      <RenderSection section={{ Component: KEY as any, props: { label: "b" } }} />,
+    );
+    expect(html).toContain("hero-b");
+  });
+
+  it("prefers the sync component over a pending lazy loader", () => {
+    const KEY = "site/sections/SyncC.tsx";
+    // Both registered: lazy loader never settles, sync is available.
+    // Sync-first must render the content without suspending.
+    registerSection(KEY, neverResolves as any);
+    registerSectionsSync({ [KEY]: { default: Hero } });
+
+    const html = renderToString(
+      <RenderSection
+        section={{ __resolveType: KEY, label: "c" }}
+        fallback={<span>loading</span>}
+      />,
+    );
+    expect(html).toContain("hero-c");
+    expect(html).not.toContain("loading");
+  });
+
+  it("falls back to the lazy path when no sync component is registered", () => {
+    const KEY = "site/sections/LazyOnlyD.tsx";
+    registerSection(KEY, neverResolves as any);
+
+    const html = renderToString(
+      <RenderSection
+        section={{ __resolveType: KEY, label: "d" }}
+        fallback={<span>loading</span>}
+      />,
+    );
+    expect(html).toContain("loading");
+    expect(html).not.toContain("hero-d");
+  });
+
+  it("renders the fallback when the section is not registered at all", () => {
+    const html = renderToString(
+      <RenderSection
+        section={{ __resolveType: "site/sections/MissingE.tsx" }}
+        fallback={<span>missing</span>}
+      />,
+    );
+    expect(html).toContain("missing");
+  });
+});