@decocms/blocks 7.38.0 → 7.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.38.0",
+  "version": "7.40.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/applySectionConventions.ts

@@ -6,7 +6,8 @@
  * registerSectionsSync, setAsyncRenderingConfig, registerCacheableSections,
  * registerLayoutSections, registerSeoSections, and registerSection.
  */
-import { registerSection, registerSectionsSync } from "./registry";
+import { registerSection, registerSectionsSync, setSectionRenderJson } from "./registry";
+import type { RenderJson } from "./renderJson";
 import {
   type AsyncRenderingConfig,
   getAsyncRenderingConfig,
@@ -32,6 +33,10 @@ export interface SectionMetaEntry {
   clientOnly?: boolean;
   seo?: boolean;
   hasLoadingFallback?: boolean;
+  /** `export const renderJson = false` — drop the section from ?renderJson. */
+  renderJson?: false;
+  /** `export const renderJson = (props) => ...` — a projection fn (in `renderJsons`). */
+  hasRenderJson?: boolean;
 }
 
 export interface ApplySectionConventionsInput {
@@ -41,12 +46,14 @@ export interface ApplySectionConventionsInput {
   syncComponents?: Record<string, any>;
   /** LoadingFallback components from sections.gen.ts */
   loadingFallbacks?: Record<string, React.ComponentType<any>>;
+  /** renderJson projection functions from sections.gen.ts (?renderJson mobile path) */
+  renderJsons?: Record<string, RenderJson>;
   /** Lazy section loaders from import.meta.glob (used for clientOnly/loadingFallback registration) */
   sectionGlob?: Record<string, () => Promise<any>>;
 }
 
 export function applySectionConventions(input: ApplySectionConventionsInput): void {
-  const { meta, syncComponents, loadingFallbacks, sectionGlob } = input;
+  const { meta, syncComponents, loadingFallbacks, renderJsons, sectionGlob } = input;
 
   const eagerSections: string[] = [];
   const neverDeferSections: string[] = [];
@@ -78,6 +85,15 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
         });
       }
     }
+
+    // renderJson (?renderJson mobile path): a `= false` opt-out drops the
+    // section; a projection function trims its props. Set as a section option so
+    // the serializer reads it via getSectionOptions without loading the module.
+    if (entry.renderJson === false) {
+      setSectionRenderJson(key, false);
+    } else if (entry.hasRenderJson && renderJsons?.[key]) {
+      setSectionRenderJson(key, renderJsons[key]);
+    }
   }
 
   if (syncComponents && Object.keys(syncComponents).length > 0) {

package/src/cms/index.ts

@@ -67,7 +67,17 @@ export {
   registerSections,
   registerSectionsSync,
   setResolvedComponent,
+  setSectionRenderJson,
 } from "./registry";
+export type {
+  DeferredRef,
+  RenderJson,
+  RenderJsonModule,
+  SerializableSection,
+  SerializedSection,
+  SerializeOptions,
+} from "./renderJson";
+export { serializeRenderJson } from "./renderJson";
 export type {
   AsyncRenderingConfig,
   CommerceLoader,

package/src/cms/registry.ts

@@ -1,4 +1,5 @@
 import type { ComponentType } from "react";
+import type { RenderJson } from "./renderJson";
 
 export type OnBeforeResolveProps = (props: Record<string, unknown>) => Record<string, unknown>;
 
@@ -8,6 +9,8 @@ export type SectionModule = {
   onBeforeResolveProps?: OnBeforeResolveProps;
   LoadingFallback?: ComponentType<any>;
   ErrorFallback?: ComponentType<{ error: Error }>;
+  /** How this section renders to JSON for the mobile app (?renderJson). */
+  renderJson?: RenderJson;
 };
 
 type RegistryEntry = () => Promise<SectionModule>;
@@ -17,6 +20,12 @@ export interface SectionOptions {
   loadingFallback?: ComponentType<any>;
   /** Custom error fallback component for this section. */
   errorFallback?: ComponentType<{ error: Error }>;
+  /**
+   * The section's `renderJson` export (?renderJson mobile path): `false` drops
+   * the section from the JSON, a function projects its props. Populated by the
+   * generated section conventions and, as a fallback, on module preload.
+   */
+  renderJson?: RenderJson;
   /**
    * When true, the section is wrapped in `<ClientOnly>` from TanStack Router.
    * It renders only on the client — no SSR, no hydration mismatch.
@@ -72,6 +81,15 @@ export function registerSections(
   }
 }
 
+/**
+ * Set a section's `renderJson` option (?renderJson mobile path) without touching
+ * its loader/component registration. Called from the generated section
+ * conventions for `export const renderJson = false | (props) => ...`.
+ */
+export function setSectionRenderJson(key: string, renderJson: RenderJson): void {
+  sectionOptions[key] = { ...sectionOptions[key], renderJson };
+}
+
 export function getSection(resolveType: string): RegistryEntry | undefined {
   return registry[resolveType];
 }
@@ -99,6 +117,7 @@ export async function preloadSectionModule(
     const opts: SectionOptions = { ...existing };
     if (mod.LoadingFallback) opts.loadingFallback = mod.LoadingFallback;
     if (mod.ErrorFallback) opts.errorFallback = mod.ErrorFallback;
+    if (mod.renderJson !== undefined) opts.renderJson = mod.renderJson;
     sectionOptions[resolveType] = opts;
     return opts;
   } catch (e) {
@@ -146,6 +165,7 @@ export async function preloadSectionComponents(keys: string[]): Promise<void> {
         const opts: SectionOptions = { ...sectionOptions[key] };
         if (mod.LoadingFallback) opts.loadingFallback = mod.LoadingFallback;
         if (mod.ErrorFallback) opts.errorFallback = mod.ErrorFallback;
+        if (mod.renderJson !== undefined) opts.renderJson = mod.renderJson;
         sectionOptions[key] = opts;
       } catch (e) {
         console.warn(`[Registry] Failed to preload component "${key}":`, e);
@@ -167,6 +187,7 @@ export type SyncSectionEntry =
       default: ComponentType<any>;
       LoadingFallback?: ComponentType<any>;
       ErrorFallback?: ComponentType<{ error: Error }>;
+      renderJson?: RenderJson;
     };
 
 /**
@@ -205,6 +226,7 @@ export function registerSectionsSync(sections: Record<string, SyncSectionEntry>)
       const opts: SectionOptions = { ...sectionOptions[key] };
       if (entry.LoadingFallback) opts.loadingFallback = entry.LoadingFallback;
       if (entry.ErrorFallback) opts.errorFallback = entry.ErrorFallback;
+      if (entry.renderJson !== undefined) opts.renderJson = entry.renderJson;
       sectionOptions[key] = opts;
     }
   }

package/src/cms/renderJson.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { type RenderJsonModule, serializeRenderJson } from "./renderJson";
+
+const modules: Record<string, RenderJsonModule> = {
+  "site/sections/Product/ProductDetails.tsx": {
+    renderJson: ({ storeConfig: _s, ...rest }) => rest,
+  },
+  "site/sections/Theme/Theme.tsx": { renderJson: false },
+  "site/sections/Footer/Footer.tsx": {}, // no renderJson → full props
+};
+const getSectionModule = (c: string) => modules[c];
+
+describe("serializeRenderJson", () => {
+  it("applies a projection function to the props", () => {
+    const out = serializeRenderJson(
+      [{ component: "site/sections/Product/ProductDetails.tsx", props: { storeConfig: {}, page: 1 } }],
+      { getSectionModule },
+    );
+    expect(out).toEqual([
+      { component: "site/sections/Product/ProductDetails.tsx", props: { page: 1 } },
+    ]);
+  });
+
+  it("drops sections whose module exports renderJson === false", () => {
+    const out = serializeRenderJson(
+      [
+        { component: "site/sections/Theme/Theme.tsx", props: { x: 1 } },
+        { component: "site/sections/Footer/Footer.tsx", props: { y: 2 } },
+      ],
+      { getSectionModule },
+    );
+    expect(out).toEqual([{ component: "site/sections/Footer/Footer.tsx", props: { y: 2 } }]);
+  });
+
+  it("passes full props through when there is no renderJson export", () => {
+    const out = serializeRenderJson([{ component: "site/sections/Footer/Footer.tsx", props: { y: 2 } }], {
+      getSectionModule,
+    });
+    expect(out).toEqual([{ component: "site/sections/Footer/Footer.tsx", props: { y: 2 } }]);
+  });
+
+  it("drops sections by sectionsToIgnore suffix match on resolveType", () => {
+    const out = serializeRenderJson(
+      [
+        { component: "website/sections/Seo/SeoV2.tsx", props: { title: "x" } },
+        { component: "site/sections/Footer/Footer.tsx", props: { y: 2 } },
+      ],
+      { getSectionModule, sectionsToIgnore: ["SeoV2.tsx"] },
+    );
+    expect(out).toEqual([{ component: "site/sections/Footer/Footer.tsx", props: { y: 2 } }]);
+  });
+
+  it("ignores blank sectionsToIgnore entries (a '' suffix must not drop everything)", () => {
+    const out = serializeRenderJson(
+      [{ component: "site/sections/Footer/Footer.tsx", props: { y: 2 } }],
+      { getSectionModule, sectionsToIgnore: ["", "  "] },
+    );
+    expect(out).toHaveLength(1);
+  });
+
+  it("keeps full props when no getSectionModule is provided", () => {
+    const out = serializeRenderJson([{ component: "a", props: { z: 1 } }]);
+    expect(out).toEqual([{ component: "a", props: { z: 1 } }]);
+  });
+
+  it("defaults missing props to an empty object", () => {
+    const out = serializeRenderJson([{ component: "a" }]);
+    expect(out).toEqual([{ component: "a", props: {} }]);
+  });
+
+  it("interleaves deferred sections as { component, lazyUrl } by index", () => {
+    const out = serializeRenderJson(
+      [
+        { component: "site/sections/Footer/Footer.tsx", props: { y: 2 }, index: 2 },
+        { component: "site/sections/Header.tsx", props: { h: 1 }, index: 0 },
+      ],
+      {
+        getSectionModule,
+        deferred: [{ component: "site/sections/Shelf.tsx", index: 1 }],
+        lazyUrlFor: (ref) => `/p?renderJson&__lazy=${ref.index}`,
+      },
+    );
+    expect(out).toEqual([
+      { component: "site/sections/Header.tsx", props: { h: 1 } },
+      { component: "site/sections/Shelf.tsx", lazyUrl: "/p?renderJson&__lazy=1" },
+      { component: "site/sections/Footer/Footer.tsx", props: { y: 2 } },
+    ]);
+  });
+
+  it("does not emit a lazyUrl for a dropped deferred section", () => {
+    const out = serializeRenderJson([{ component: "site/sections/Header.tsx", props: {}, index: 0 }], {
+      getSectionModule,
+      sectionsToIgnore: ["SeoV2.tsx"],
+      deferred: [
+        { component: "website/sections/Seo/SeoV2.tsx", index: 1 }, // suffix-dropped
+        { component: "site/sections/Theme/Theme.tsx", index: 2 }, // renderJson === false
+      ],
+      lazyUrlFor: (ref) => `/p?renderJson&__lazy=${ref.index}`,
+    });
+    expect(out).toEqual([{ component: "site/sections/Header.tsx", props: {} }]);
+  });
+});

package/src/cms/renderJson.ts

@@ -0,0 +1,126 @@
+/**
+ * renderJson — structured JSON projection of a resolved page for the mobile app.
+ *
+ * A section controls how it renders to JSON through a recognized named export
+ * `renderJson` (same convention family as `loader`/`action`/`LoadingFallback`):
+ *
+ * - `export const renderJson = false` — drop the section from the JSON entirely
+ *   (web-only: theme/analytics/SEO/scripts). It also short-circuits the loader
+ *   in {@link runSectionLoaders} (no data fetch for a dropped section).
+ * - `export const renderJson = (props) => projected` — a pure projection applied
+ *   to the resolved props before serialization (typically {@link deepOmit} of
+ *   internal/SEO/store-config fields).
+ * - no export — the section serializes with its full resolved props.
+ *
+ * The whole-page envelope (`?renderJson`) is `{ name, path, sections }`, where
+ * each section is `{ component, props }`. This is the lean shape — no admin
+ * `resolveChain`/metadata (unlike the legacy `?asJson`).
+ *
+ * Ported from the deco-runtime fork's `serialize-section.ts`, adapted for the
+ * TanStack pipeline: sections are resolved EAGERLY before serialization, so this
+ * serializer has no lazy-placeholder (`{ component, lazyUrl }`) branch — the
+ * mobile app receives the whole page in one request.
+ *
+ * ponytail: no nested section-in-section recursion (composite/layout sections).
+ * deepOmit handles trimming within a single section's data; add a recursive walk
+ * here if a composite section must project its child sections.
+ */
+
+// deno-lint-ignore-style any: a projection accepts the section's own resolved props.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type RenderJson = ((props: any) => Record<string, unknown>) | false;
+
+export interface RenderJsonModule {
+  renderJson?: RenderJson;
+}
+
+/** A resolved section after its loader ran: component id + enriched props. */
+export interface SerializableSection {
+  component: string;
+  props?: Record<string, unknown>;
+  /** Position in the page's flat section list (used to interleave with lazy ones). */
+  index?: number;
+}
+
+/** A deferred section that isn't resolved eagerly — emitted as a lazy placeholder. */
+export interface DeferredRef {
+  component: string;
+  index: number;
+}
+
+/** An eager section carries `props`; a lazy one carries a `lazyUrl` to fetch it. */
+export type SerializedSection =
+  | { component: string; props: Record<string, unknown> }
+  | { component: string; lazyUrl: string };
+
+export interface SerializeOptions {
+  /**
+   * Resolves a section module by resolveType so the serializer can honor its
+   * `renderJson` export. When omitted, every section keeps its full props.
+   */
+  getSectionModule?: (component: string) => RenderJsonModule | undefined;
+  /**
+   * App-owned sections excluded from the response, matched by resolveType
+   * suffix (e.g. "SeoV2.tsx"). Blank entries are ignored — a "" suffix would
+   * endsWith-match every section.
+   */
+  sectionsToIgnore?: string[];
+  /**
+   * Deferred sections to emit as `{ component, lazyUrl }` placeholders,
+   * interleaved with the eager ones by `index`. Dropped sections
+   * (`renderJson === false` / `sectionsToIgnore`) are omitted here too. When
+   * set, the output is ordered by `index`.
+   */
+  deferred?: DeferredRef[];
+  /** Builds the lazy-fetch URL for a deferred section. Required when `deferred` is set. */
+  lazyUrlFor?: (ref: DeferredRef) => string;
+}
+
+/**
+ * Projects a page's sections into the lean renderJson shape. Eager sections
+ * become `{ component, props }` (a `renderJson` function projects the props;
+ * otherwise props pass through). Deferred sections become
+ * `{ component, lazyUrl }`, interleaved by `index`. A section is dropped when
+ * its resolveType matches a `sectionsToIgnore` suffix OR its module exports
+ * `renderJson === false` (for a deferred section, dropping avoids emitting a
+ * lazyUrl the app would fetch for nothing).
+ */
+export function serializeRenderJson(
+  sections: SerializableSection[],
+  opts: SerializeOptions = {},
+): SerializedSection[] {
+  const ignore = (opts.sectionsToIgnore ?? [])
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  const renderJsonOf = (component: string): RenderJson | undefined =>
+    opts.getSectionModule?.(component)?.renderJson;
+
+  const isDropped = (component: string): boolean =>
+    ignore.some((suffix) => component.endsWith(suffix)) ||
+    renderJsonOf(component) === false;
+
+  const eager = sections
+    .filter((s) => !isDropped(s.component))
+    .map((section) => {
+      const rj = renderJsonOf(section.component);
+      const props = typeof rj === "function" ? rj(section.props ?? {}) : section.props ?? {};
+      return { index: section.index, out: { component: section.component, props } as SerializedSection };
+    });
+
+  // No deferred sections → preserve input order (backward compatible).
+  if (!opts.deferred || opts.deferred.length === 0) {
+    return eager.map((e) => e.out);
+  }
+
+  const lazyUrlFor = opts.lazyUrlFor;
+  const lazy = opts.deferred
+    .filter((ref) => !isDropped(ref.component) && !!lazyUrlFor)
+    .map((ref) => ({
+      index: ref.index,
+      out: { component: ref.component, lazyUrl: lazyUrlFor!(ref) } as SerializedSection,
+    }));
+
+  // Interleave eager + lazy by their position in the page's flat section list.
+  return [...eager, ...lazy].sort((a, b) => (a.index ?? 0) - (b.index ?? 0)).map((e) => e.out);
+}

package/src/sdk/deepOmit.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { deepOmit } from "./deepOmit";
+
+describe("deepOmit", () => {
+  it("removes a top-level key immutably", () => {
+    const input = { a: 1, b: 2 };
+    const out = deepOmit(input, "b");
+    expect(out).toEqual({ a: 1 });
+    expect(input).toEqual({ a: 1, b: 2 }); // input untouched
+  });
+
+  it("removes a nested dotted path", () => {
+    const out = deepOmit({ page: { seo: { title: "x" }, id: 1 } }, "page.seo");
+    expect(out).toEqual({ page: { id: 1 } });
+  });
+
+  it("fans a wildcard over record values", () => {
+    const out = deepOmit(
+      { page: { productsMap: { a: { keep: 1, drop: 2 }, b: { keep: 3, drop: 4 } } } },
+      "page.productsMap.*.drop",
+    );
+    expect(out).toEqual({ page: { productsMap: { a: { keep: 1 }, b: { keep: 3 } } } });
+  });
+
+  it("fans a wildcard over array elements", () => {
+    const out = deepOmit({ items: [{ keep: 1, drop: 2 }, { keep: 3, drop: 4 }] }, "items.*.drop");
+    expect(out).toEqual({ items: [{ keep: 1 }, { keep: 3 }] });
+  });
+
+  it("auto-applies a path to each array element (no explicit *)", () => {
+    const out = deepOmit({ items: [{ a: 1, b: 2 }, { a: 3, b: 4 }] }, "items.b");
+    expect(out).toEqual({ items: [{ a: 1 }, { a: 3 }] });
+  });
+
+  it("is a no-op for a missing key (never fabricates undefined)", () => {
+    const out = deepOmit({ a: 1 }, "b.c.d");
+    expect(out).toEqual({ a: 1 });
+    expect("b" in out).toBe(false);
+  });
+
+  it("applies multiple paths", () => {
+    const out = deepOmit({ a: 1, b: 2, c: { d: 3, e: 4 } }, "a", "c.d");
+    expect(out).toEqual({ b: 2, c: { e: 4 } });
+  });
+});

package/src/sdk/deepOmit.ts

@@ -0,0 +1,52 @@
+/**
+ * deepOmit — immutably remove dotted paths from an object tree.
+ *
+ * Used by section `renderJson` projections to trim a section's props before it
+ * is serialized for the mobile app (the ?renderJson page-as-JSON path):
+ *
+ * ```ts
+ * export const renderJson = (props: SectionProps<typeof loader>) =>
+ *   deepOmit(props, "storeConfig", "page.seo", "page.productsMap.*.hasFetchedSimilars");
+ * ```
+ *
+ * Semantics:
+ * - Top-level key: `deepOmit(o, "seoProps")`.
+ * - Nested path (dot-separated): `deepOmit(o, "page.seo")`.
+ * - Wildcard `*`: fans the remaining path over every array element OR record
+ *   value — `"page.productsMap.*.hasFetchedSimilars"` strips `hasFetchedSimilars`
+ *   from every value of `productsMap`.
+ * - Arrays without an explicit `*`: the path auto-applies to each element and the
+ *   array shape is preserved.
+ * - Missing key: a no-op — never fabricates an `undefined` branch.
+ *
+ * Pure: spreads/copies at each level, never mutates the input.
+ */
+const omitAtPath = (obj: unknown, parts: string[]): unknown => {
+  if (!obj || typeof obj !== "object" || parts.length === 0) return obj;
+  const [key, ...rest] = parts;
+
+  // `*` fans the remaining path out over every array element / record value.
+  if (key === "*") {
+    if (Array.isArray(obj)) return obj.map((v) => omitAtPath(v, rest));
+    return Object.fromEntries(
+      Object.entries(obj as Record<string, unknown>).map(([k, v]) => [k, omitAtPath(v, rest)]),
+    );
+  }
+  // Preserve array shape: apply the same path to each element.
+  if (Array.isArray(obj)) return obj.map((v) => omitAtPath(v, parts));
+
+  const current = obj as Record<string, unknown>;
+  if (rest.length === 0) {
+    const copy = { ...current };
+    delete copy[key];
+    return copy;
+  }
+  if (!(key in current)) return current; // absent path = no-op, never creates undefined branches
+  return { ...current, [key]: omitAtPath(current[key], rest) };
+};
+
+export const deepOmit = <T extends object>(obj: T, ...paths: string[]): T => {
+  let result: unknown = obj;
+  for (const path of paths) result = omitAtPath(result, path.split("."));
+  return result as T;
+};

package/src/sdk/index.ts

@@ -18,6 +18,7 @@ export {
 export { clx } from "./clx";
 export { decodeCookie, deleteCookie, getCookie, getServerSideCookie, setCookie } from "./cookie";
 export { buildCSPHeaderValue, type CSPOptions, setCSPHeaders } from "./csp";
+export { deepOmit } from "./deepOmit";
 export { djb2, djb2Hex } from "./djb2";
 export { isDevMode } from "./env";
 export {