@decocms/start 0.28.3 → 0.29.1

package/src/hooks/DecoPageRenderer.tsx

@@ -8,6 +8,7 @@ import {
   useRef,
   useState,
 } from "react";
+import { Await, ClientOnly } from "@tanstack/react-router";
 import type { SectionOptions } from "../cms/registry";
 import {
   getResolvedComponent,
@@ -375,6 +376,26 @@ function DeferredSectionWrapper({
   );
 }
 
+// ---------------------------------------------------------------------------
+// DeferredSectionSkeleton — resolves the best fallback for a deferred section
+// ---------------------------------------------------------------------------
+
+function DeferredSectionSkeleton({
+  deferred,
+  fallback,
+}: {
+  deferred: DeferredSection;
+  fallback?: ReactNode;
+}) {
+  const options = getSectionOptions(deferred.component);
+  if (options?.loadingFallback) {
+    return createElement(options.loadingFallback, deferred.rawProps);
+  }
+  if (fallback) return <>{fallback}</>;
+  if (isDev) return <DevMissingFallbackWarning component={deferred.component} />;
+  return <DefaultSectionFallback />;
+}
+
 // ---------------------------------------------------------------------------
 // Merge helper — combines eager and deferred sections in original order
 // ---------------------------------------------------------------------------
@@ -418,11 +439,18 @@ function mergeSections(resolved: ResolvedSection[], deferred: DeferredSection[])
 interface Props {
   sections: ResolvedSection[];
   deferredSections?: DeferredSection[];
+  /**
+   * Unawaited promises for deferred sections, keyed by `d_<index>`.
+   * Created by the route loader for TanStack native SSR streaming.
+   * When provided, takes precedence over `loadDeferredSectionFn`.
+   */
+  deferredPromises?: Record<string, Promise<ResolvedSection | null>>;
   pagePath?: string;
   /** Original page URL (with query params) — forwarded to deferred section loaders. */
   pageUrl?: string;
   loadingFallback?: ReactNode;
   errorFallback?: ReactNode;
+  /** @deprecated Use deferredPromises instead (TanStack native streaming). */
   loadDeferredSectionFn?: (data: {
     component: string;
     rawProps: Record<string, unknown>;
@@ -434,6 +462,7 @@ interface Props {
 export function DecoPageRenderer({
   sections,
   deferredSections,
+  deferredPromises,
   pagePath = "/",
   pageUrl,
   loadingFallback,
@@ -448,20 +477,80 @@ export function DecoPageRenderer({
       {hasDeferred && <FadeInStyle />}
       {items.map((item, index) => {
         if (item.type === "deferred") {
-          if (!loadDeferredSectionFn) {
-            return null;
+          const promiseKey = `d_${item.deferred.index}`;
+          const promise = deferredPromises?.[promiseKey];
+
+          // TanStack native streaming path — uses <Await> for SSR-streamed data
+          if (promise) {
+            const deferredSectionId = item.deferred.key
+              .replace(/\//g, "-")
+              .replace(/\.tsx$/, "")
+              .replace(/^site-sections-/, "");
+
+            return (
+              <SectionErrorBoundary
+                key={`deferred-${pagePath}-${item.deferred.key}-${item.deferred.index}`}
+                sectionKey={item.deferred.key}
+                fallback={errorFallback}
+              >
+                <Suspense fallback={
+                  <section id={deferredSectionId} data-manifest-key={item.deferred.key} data-deferred="true">
+                    <DeferredSectionSkeleton deferred={item.deferred} fallback={loadingFallback} />
+                  </section>
+                }>
+                  <Await promise={promise}>
+                    {(resolved) => {
+                      if (!resolved) return null;
+                      const LazyComponent = getLazyComponent(resolved.component);
+                      if (!LazyComponent) return null;
+                      const resolvedOptions = getSectionOptions(resolved.component);
+                      const isClientOnly = resolvedOptions?.clientOnly === true;
+                      const sectionId = resolved.key
+                        .replace(/\//g, "-")
+                        .replace(/\.tsx$/, "")
+                        .replace(/^site-sections-/, "");
+
+                      const inner = (
+                        <Suspense fallback={null}>
+                          <LazyComponent {...resolved.props} />
+                        </Suspense>
+                      );
+
+                      return (
+                        <section
+                          id={sectionId}
+                          data-manifest-key={resolved.key}
+                          style={{ animation: "decoFadeIn 0.3s ease-out" }}
+                        >
+                          {isClientOnly ? (
+                            <ClientOnly fallback={null}>{inner}</ClientOnly>
+                          ) : (
+                            inner
+                          )}
+                        </section>
+                      );
+                    }}
+                  </Await>
+                </Suspense>
+              </SectionErrorBoundary>
+            );
           }
-          return (
-            <DeferredSectionWrapper
-              key={`deferred-${pagePath}-${item.deferred.key}-${item.deferred.index}`}
-              deferred={item.deferred}
-              pagePath={pagePath}
-              pageUrl={pageUrl}
-              loadingFallback={loadingFallback}
-              errorFallback={errorFallback}
-              loadFn={loadDeferredSectionFn}
-            />
-          );
+
+          // Fallback: legacy POST-based IntersectionObserver path
+          if (loadDeferredSectionFn) {
+            return (
+              <DeferredSectionWrapper
+                key={`deferred-${pagePath}-${item.deferred.key}-${item.deferred.index}`}
+                deferred={item.deferred}
+                pagePath={pagePath}
+                pageUrl={pageUrl}
+                loadingFallback={loadingFallback}
+                errorFallback={errorFallback}
+                loadFn={loadDeferredSectionFn}
+              />
+            );
+          }
+          return null;
         }
 
         const { section } = item;
@@ -485,12 +574,34 @@ export function DecoPageRenderer({
         // registerSectionsSync.
         const LazyComponent = getLazyComponent(section.component);
         if (!LazyComponent) return null;
-        const content = (
+
+        // ClientOnly sections: render only on client, no SSR, no hydration mismatch.
+        // Used for analytics scripts, GTM, third-party widgets.
+        const isClientOnly = options?.clientOnly === true;
+        const fallbackEl = options?.loadingFallback
+          ? createElement(options.loadingFallback, section.props)
+          : null;
+
+        const content = isClientOnly ? (
+          <ClientOnly fallback={fallbackEl}>
+            <Suspense fallback={null}>
+              <LazyComponent {...section.props} />
+            </Suspense>
+          </ClientOnly>
+        ) : (
           <Suspense fallback={null}>
             <LazyComponent {...section.props} />
           </Suspense>
         );
 
+        // Dev warning: eager section not sync-registered may blank during hydration
+        if (isDev && !isClientOnly && !getSyncComponent(section.component)) {
+          console.warn(
+            `[DecoPageRenderer] Eager section "${section.component}" is not in registerSectionsSync(). ` +
+              `This may cause blank content during hydration. Add it to registerSectionsSync() in setup.ts.`,
+          );
+        }
+
         return (
           <section key={`${section.key}-${index}`} id={sectionId} data-manifest-key={section.key}>
             <SectionErrorBoundary sectionKey={section.key} fallback={errFallback}>

package/src/middleware/hydrationContext.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { buildHydrationContext } from "./hydrationContext";
+
+function makeRequest(headers: Record<string, string> = {}): Request {
+  return new Request("https://store.com/", { headers });
+}
+
+describe("buildHydrationContext", () => {
+  it("extracts locale and timezone from cookies", () => {
+    const req = makeRequest({ cookie: "locale=pt-BR; tz=America/Sao_Paulo" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("pt-BR");
+    expect(ctx.timeZone).toBe("America/Sao_Paulo");
+  });
+
+  it("falls back to Accept-Language when no locale cookie", () => {
+    const req = makeRequest({ "accept-language": "pt-BR,pt;q=0.9,en;q=0.8" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("pt-BR");
+  });
+
+  it("defaults to en-US and UTC when no headers or cookies", () => {
+    const req = makeRequest();
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("en-US");
+    expect(ctx.timeZone).toBe("UTC");
+  });
+
+  it("extracts country from cf-ipcountry header", () => {
+    const req = makeRequest({ "cf-ipcountry": "BR" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBe("BR");
+  });
+
+  it("extracts country from cookie when no cf header", () => {
+    const req = makeRequest({ cookie: "country=US" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBe("US");
+  });
+
+  it("country is undefined when not available", () => {
+    const req = makeRequest();
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBeUndefined();
+  });
+
+  it("cf-ipcountry takes precedence over cookie", () => {
+    const req = makeRequest({
+      "cf-ipcountry": "BR",
+      cookie: "country=US",
+    });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.country).toBe("BR");
+  });
+
+  it("handles cookies with = in values", () => {
+    const req = makeRequest({ cookie: "locale=en-US; token=abc=def=ghi" });
+    const ctx = buildHydrationContext(req);
+    expect(ctx.locale).toBe("en-US");
+  });
+});

package/src/middleware/hydrationContext.ts

@@ -0,0 +1,79 @@
+/**
+ * Hydration context utilities for consistent SSR/client rendering.
+ *
+ * Provides patterns for extracting locale, timezone, and other
+ * request-specific data that must be consistent between server
+ * and client to avoid hydration mismatches.
+ *
+ * @example
+ * ```tsx
+ * // In your storefront's middleware.ts:
+ * import { createMiddleware } from "@tanstack/react-start";
+ * import { buildHydrationContext } from "@decocms/start/middleware/hydrationContext";
+ *
+ * export const hydrationMiddleware = createMiddleware().server(async ({ request, next }) => {
+ *   const hydrationCtx = buildHydrationContext(request);
+ *   return next({ context: { hydration: hydrationCtx } });
+ * });
+ * ```
+ *
+ * Then in components:
+ * ```tsx
+ * // Use the cookie-based values for deterministic SSR rendering
+ * const locale = hydrationCtx.locale; // same on server and client
+ * ```
+ */
+
+export interface HydrationContext {
+  /** Locale from cookie or Accept-Language header. */
+  locale: string;
+  /** Timezone from cookie. Falls back to "UTC" for deterministic SSR. */
+  timeZone: string;
+  /** Country code from Cloudflare headers or cookie. */
+  country?: string;
+}
+
+/**
+ * Build hydration context from a request.
+ *
+ * Values are extracted from cookies first (set by the client on first visit),
+ * then from headers. Cookie-based values are deterministic because the same
+ * cookie is sent on both SSR and client-side navigations.
+ *
+ * Recommended: set these cookies on first client render:
+ * ```tsx
+ * useEffect(() => {
+ *   const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+ *   document.cookie = `tz=${tz}; path=/; max-age=31536000; SameSite=Lax`;
+ *   document.cookie = `locale=${navigator.language}; path=/; max-age=31536000; SameSite=Lax`;
+ * }, []);
+ * ```
+ */
+export function buildHydrationContext(request: Request): HydrationContext {
+  const cookies = parseCookies(request.headers.get("cookie") ?? "");
+
+  // Locale: cookie → Accept-Language → fallback
+  const locale =
+    cookies.locale ||
+    request.headers.get("accept-language")?.split(",")[0]?.split(";")[0]?.trim() ||
+    "en-US";
+
+  // Timezone: cookie → UTC fallback (never guess — causes hydration mismatch)
+  const timeZone = cookies.tz || "UTC";
+
+  // Country: Cloudflare header → cookie
+  const country =
+    request.headers.get("cf-ipcountry") || cookies.country || undefined;
+
+  return { locale, timeZone, country };
+}
+
+function parseCookies(cookieHeader: string): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  for (const part of cookieHeader.split(";")) {
+    const [key, ...rest] = part.split("=");
+    const k = key?.trim();
+    if (k) cookies[k] = rest.join("=").trim();
+  }
+  return cookies;
+}

package/src/middleware/index.ts

@@ -55,6 +55,13 @@ export {
   withTracing,
 } from "./observability";
 
+export { buildHydrationContext, type HydrationContext } from "./hydrationContext";
+export {
+  createSectionValidator,
+  type DeferredSectionInput,
+  validateDeferredSectionInput,
+} from "./validateSection";
+
 /**
  * Appends Server-Timing header to a response from the accumulated timings.
  */

package/src/middleware/validateSection.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import {
+  createSectionValidator,
+  validateDeferredSectionInput,
+} from "./validateSection";
+
+describe("validateDeferredSectionInput", () => {
+  it("accepts valid input", () => {
+    const result = validateDeferredSectionInput({
+      component: "site/sections/ProductShelf.tsx",
+      rawProps: { title: "Best Sellers" },
+      pagePath: "/",
+    });
+    expect(result.component).toBe("site/sections/ProductShelf.tsx");
+    expect(result.rawProps).toEqual({ title: "Best Sellers" });
+    expect(result.pagePath).toBe("/");
+    expect(result.pageUrl).toBeUndefined();
+  });
+
+  it("accepts input with optional pageUrl", () => {
+    const result = validateDeferredSectionInput({
+      component: "site/sections/Hero.tsx",
+      rawProps: {},
+      pagePath: "/home",
+      pageUrl: "https://store.com/home?ref=nav",
+    });
+    expect(result.pageUrl).toBe("https://store.com/home?ref=nav");
+  });
+
+  it("accepts input with index for SPA navigation ordering", () => {
+    const result = validateDeferredSectionInput({
+      component: "site/sections/Shelf.tsx",
+      rawProps: {},
+      pagePath: "/",
+      index: 5,
+    });
+    expect(result.index).toBe(5);
+  });
+
+  it("index is undefined when not provided", () => {
+    const result = validateDeferredSectionInput({
+      component: "site/sections/Shelf.tsx",
+      rawProps: {},
+      pagePath: "/",
+    });
+    expect(result.index).toBeUndefined();
+  });
+
+  it("throws on null input", () => {
+    expect(() => validateDeferredSectionInput(null)).toThrow("Expected an object");
+  });
+
+  it("throws on undefined input", () => {
+    expect(() => validateDeferredSectionInput(undefined)).toThrow("Expected an object");
+  });
+
+  it("throws on string input", () => {
+    expect(() => validateDeferredSectionInput("nope")).toThrow("Expected an object");
+  });
+
+  it("throws when component is missing", () => {
+    expect(() =>
+      validateDeferredSectionInput({ rawProps: {}, pagePath: "/" }),
+    ).toThrow("component");
+  });
+
+  it("throws when component is not a string", () => {
+    expect(() =>
+      validateDeferredSectionInput({ component: 123, rawProps: {}, pagePath: "/" }),
+    ).toThrow("component");
+  });
+
+  it("throws when rawProps is missing", () => {
+    expect(() =>
+      validateDeferredSectionInput({ component: "X", pagePath: "/" }),
+    ).toThrow("rawProps");
+  });
+
+  it("throws when rawProps is an array", () => {
+    expect(() =>
+      validateDeferredSectionInput({ component: "X", rawProps: [1, 2], pagePath: "/" }),
+    ).toThrow("rawProps");
+  });
+
+  it("throws when rawProps is null", () => {
+    expect(() =>
+      validateDeferredSectionInput({ component: "X", rawProps: null, pagePath: "/" }),
+    ).toThrow("rawProps");
+  });
+
+  it("throws when pagePath is missing", () => {
+    expect(() =>
+      validateDeferredSectionInput({ component: "X", rawProps: {} }),
+    ).toThrow("pagePath");
+  });
+
+  it("throws when pageUrl is not a string", () => {
+    expect(() =>
+      validateDeferredSectionInput({
+        component: "X",
+        rawProps: {},
+        pagePath: "/",
+        pageUrl: 42,
+      }),
+    ).toThrow("pageUrl");
+  });
+
+  it("throws when index is not a number", () => {
+    expect(() =>
+      validateDeferredSectionInput({
+        component: "X",
+        rawProps: {},
+        pagePath: "/",
+        index: "three" as any,
+      }),
+    ).toThrow("index");
+  });
+});
+
+describe("createSectionValidator", () => {
+  it("passes when all required fields present", () => {
+    const validate = createSectionValidator(["title", "maxItems"]);
+    const result = validate({ title: "Shelf", maxItems: 8 });
+    expect(result).toEqual({ title: "Shelf", maxItems: 8 });
+  });
+
+  it("throws when a required field is missing", () => {
+    const validate = createSectionValidator(["title", "maxItems"]);
+    expect(() => validate({ title: "Shelf" })).toThrow("maxItems");
+  });
+
+  it("throws on null input", () => {
+    const validate = createSectionValidator(["title"]);
+    expect(() => validate(null)).toThrow("Expected an object");
+  });
+
+  it("allows extra fields", () => {
+    const validate = createSectionValidator(["title"]);
+    const result = validate({ title: "Hi", extra: true });
+    expect(result).toEqual({ title: "Hi", extra: true });
+  });
+
+  it("empty required fields always passes for objects", () => {
+    const validate = createSectionValidator([]);
+    expect(validate({})).toEqual({});
+  });
+});

package/src/middleware/validateSection.ts

@@ -0,0 +1,100 @@
+/**
+ * Server function input validation for section-related server functions.
+ *
+ * Validates that `loadDeferredSection` and similar server functions receive
+ * well-formed input before reaching section loaders. Prevents malformed
+ * requests from causing obscure runtime errors.
+ *
+ * @example
+ * ```tsx
+ * import { validateDeferredSectionInput } from "@decocms/start/middleware/validateSection";
+ *
+ * // In your storefront's middleware chain:
+ * export const loadSection = createServerFn({ method: "POST" })
+ *   .inputValidator(validateDeferredSectionInput)
+ *   .handler(async (ctx) => { ... });
+ * ```
+ */
+
+export interface DeferredSectionInput {
+  component: string;
+  rawProps: Record<string, unknown>;
+  pagePath: string;
+  pageUrl?: string;
+  /** Original position in the page section list — for correct ordering after resolution. */
+  index?: number;
+}
+
+/**
+ * Validates input for deferred section loading server functions.
+ * Throws descriptive errors for malformed requests.
+ */
+export function validateDeferredSectionInput(data: unknown): DeferredSectionInput {
+  if (!data || typeof data !== "object") {
+    throw new Error("[validateDeferredSectionInput] Expected an object, got " + typeof data);
+  }
+  const obj = data as Record<string, unknown>;
+
+  if (!obj.component || typeof obj.component !== "string") {
+    throw new Error(
+      "[validateDeferredSectionInput] Missing or invalid 'component' field (expected string)",
+    );
+  }
+
+  if (!obj.rawProps || typeof obj.rawProps !== "object" || Array.isArray(obj.rawProps)) {
+    throw new Error(
+      "[validateDeferredSectionInput] Missing or invalid 'rawProps' field (expected object)",
+    );
+  }
+
+  if (!obj.pagePath || typeof obj.pagePath !== "string") {
+    throw new Error(
+      "[validateDeferredSectionInput] Missing or invalid 'pagePath' field (expected string)",
+    );
+  }
+
+  if (obj.pageUrl !== undefined && typeof obj.pageUrl !== "string") {
+    throw new Error(
+      "[validateDeferredSectionInput] Invalid 'pageUrl' field (expected string or undefined)",
+    );
+  }
+
+  if (obj.index !== undefined && typeof obj.index !== "number") {
+    throw new Error(
+      "[validateDeferredSectionInput] Invalid 'index' field (expected number or undefined)",
+    );
+  }
+
+  return {
+    component: obj.component as string,
+    rawProps: obj.rawProps as Record<string, unknown>,
+    pagePath: obj.pagePath as string,
+    pageUrl: obj.pageUrl as string | undefined,
+    index: obj.index as number | undefined,
+  };
+}
+
+/**
+ * Generic section props validator factory.
+ * Creates a validator function that checks required fields exist.
+ *
+ * @example
+ * ```tsx
+ * const validate = createSectionValidator(["title", "maxItems"]);
+ * const props = validate(rawInput); // throws if missing title or maxItems
+ * ```
+ */
+export function createSectionValidator(requiredFields: string[]) {
+  return (data: unknown): Record<string, unknown> => {
+    if (!data || typeof data !== "object") {
+      throw new Error("[SectionValidator] Expected an object");
+    }
+    const obj = data as Record<string, unknown>;
+    for (const field of requiredFields) {
+      if (obj[field] === undefined) {
+        throw new Error(`[SectionValidator] Missing required field: "${field}"`);
+      }
+    }
+    return obj;
+  };
+}