@decocms/blocks 7.34.1 → 7.34.3

package/package.json

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

package/src/cms/applySectionConventions.ts

@@ -10,6 +10,7 @@ import { registerSection, registerSectionsSync } from "./registry";
 import {
   type AsyncRenderingConfig,
   getAsyncRenderingConfig,
+  registerAlwaysDeferSections,
   registerEagerSections,
   registerNeverDeferSections,
   registerSeoSections,
@@ -24,6 +25,7 @@ import {
 export interface SectionMetaEntry {
   eager?: boolean;
   neverDefer?: boolean;
+  deferred?: boolean;
   cache?: string;
   layout?: boolean;
   sync?: boolean;
@@ -48,6 +50,7 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
 
   const eagerSections: string[] = [];
   const neverDeferSections: string[] = [];
+  const alwaysDeferSections: string[] = [];
   const layoutSections: string[] = [];
   const seoSections: string[] = [];
   const cacheableSections: Record<string, CacheableSectionInput> = {};
@@ -55,6 +58,7 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
   for (const [key, entry] of Object.entries(meta)) {
     if (entry.eager) eagerSections.push(key);
     if (entry.neverDefer) neverDeferSections.push(key);
+    if (entry.deferred) alwaysDeferSections.push(key);
     if (entry.layout) layoutSections.push(key);
     if (entry.seo) seoSections.push(key);
     if (entry.cache) cacheableSections[key] = entry.cache as CacheableSectionInput;
@@ -88,6 +92,10 @@ export function applySectionConventions(input: ApplySectionConventionsInput): vo
     registerNeverDeferSections(neverDeferSections);
   }
 
+  if (alwaysDeferSections.length > 0) {
+    registerAlwaysDeferSections(alwaysDeferSections);
+  }
+
   // Always initialize asyncConfig so CMS Lazy deferral (`respectCmsLazy`) is
   // active — this is what makes the admin ⚡ toggle the source of truth. Without
   // it, asyncConfig stays null, `useAsync` is false in resolveDecoPage, and

package/src/cms/loader.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { findPageByPath, matchPath, setBlocks } from "./loader";
+import { setDraftOverrideGetter } from "./draftSource";
+import { findPageByPath, loadBlocks, matchPath, setBlocks } from "./loader";
 
 // Mirrors the behavior of the original deco-cx/deco Fresh framework
 // (runtime/features/render.tsx), which uses native `URLPattern` directly
@@ -198,3 +199,85 @@ describe("findPageByPath specificity", () => {
     expect(findPageByPath("/nope")).toBeNull();
   });
 });
+
+describe("loadBlocks draft override — key percent-encoding", () => {
+  // The published decofile encodes special characters in block keys
+  // (`pages-Home%20(principal)-1`); the Studio draft-preview sandbox emits them
+  // raw (`pages-Home (principal)-1`). A naive key-merge ADDS the raw-keyed
+  // draft block instead of REPLACING the encoded published one, leaving two
+  // `pages-` blocks with path "/" — and findPageByPath returns the first
+  // (published) one, so the draft edit silently never renders. This shipped and
+  // made ~73% of casaevideo's pages (home + afiliados included) ignore drafts.
+
+  afterEach(() => {
+    setBlocks({});
+    setDraftOverrideGetter(() => undefined);
+  });
+
+  it("replaces an encoded base key with its raw-encoded draft twin (home)", () => {
+    setBlocks({
+      "pages-Home%20(principal)-1": {
+        name: "Home",
+        path: "/",
+        sections: [{ __resolveType: "published" }],
+      },
+    });
+    setDraftOverrideGetter(() => ({
+      "pages-Home (principal)-1": {
+        name: "Home",
+        path: "/",
+        sections: [{ __resolveType: "draft" }],
+      },
+    }));
+
+    // Exactly one page for "/" survives the merge — no encoded/raw duplicate.
+    const pageBlocks = Object.keys(loadBlocks()).filter((k) =>
+      k.startsWith("pages-"),
+    );
+    expect(pageBlocks).toHaveLength(1);
+
+    const match = findPageByPath("/");
+    const sections = match?.page.sections as Array<{ __resolveType: string }>;
+    expect(sections[0].__resolveType).toBe("draft");
+  });
+
+  it("still replaces a plain (unescaped) base key", () => {
+    setBlocks({
+      "pages-disney-1": {
+        name: "Disney",
+        path: "/disney",
+        sections: [{ __resolveType: "published" }],
+      },
+    });
+    setDraftOverrideGetter(() => ({
+      "pages-disney-1": {
+        name: "Disney",
+        path: "/disney",
+        sections: [{ __resolveType: "draft" }],
+      },
+    }));
+
+    const match = findPageByPath("/disney");
+    const sections = match?.page.sections as Array<{ __resolveType: string }>;
+    expect(sections[0].__resolveType).toBe("draft");
+  });
+
+  it("a null draft value removes the encoded base twin too", () => {
+    setBlocks({
+      "pages-Home%20(principal)-1": {
+        name: "Home",
+        path: "/",
+        sections: [{ __resolveType: "published" }],
+      },
+    });
+    setDraftOverrideGetter(() => ({
+      "pages-Home (principal)-1": null,
+    }));
+
+    expect(findPageByPath("/")).toBeNull();
+    const pageBlocks = Object.keys(loadBlocks()).filter((k) =>
+      k.startsWith("pages-"),
+    );
+    expect(pageBlocks).toHaveLength(0);
+  });
+});

package/src/cms/loader.ts

@@ -85,6 +85,59 @@ export function setBlocks(blocks: Record<string, unknown>) {
   }
 }
 
+/**
+ * Canonicalise a block key so an override block matches its base twin even when
+ * the two decofiles disagree on percent-encoding of the key.
+ *
+ * The site's published decofile encodes special characters in block keys
+ * (`pages-Home%20(principal)-287364`); the Studio draft-preview sandbox emits
+ * them raw (`pages-Home (principal)-287364`). Decoding collapses both spellings
+ * to the same canonical form. Defensive: a malformed `%` sequence makes
+ * `decodeURIComponent` throw, so fall back to the raw key rather than 500 the
+ * merge.
+ */
+function canonicalBlockKey(key: string): string {
+  try {
+    return decodeURIComponent(key);
+  } catch {
+    return key;
+  }
+}
+
+/**
+ * Merge an override decofile on top of the base blocks.
+ *
+ * An override entry REPLACES the base block of the same logical key — including
+ * a base twin spelled with different percent-encoding. A naive key-merge would
+ * instead ADD the differently-encoded override block, leaving two `pages-`
+ * blocks with the same `.path`; `findPageByPath` returns the first (base) one,
+ * so a draft-preview edit would silently never render. Canonicalising the base
+ * keys lets the override find and displace its twin.
+ *
+ * A `null`/`undefined` override value deletes the block (its twin too), so a
+ * draft that removes a block is honoured.
+ */
+function mergeOverride(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged = { ...base };
+  const baseByCanonical = new Map<string, string>();
+  for (const baseKey of Object.keys(merged)) {
+    baseByCanonical.set(canonicalBlockKey(baseKey), baseKey);
+  }
+  for (const [key, value] of Object.entries(override)) {
+    const twin = baseByCanonical.get(canonicalBlockKey(key));
+    if (twin !== undefined && twin !== key) delete merged[twin];
+    if (value === null || value === undefined) {
+      delete merged[key];
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
 /**
  * Load the current blocks. If running inside a `withBlocksOverride` scope
  * (admin preview) or a request carrying a draft-preview override, that
@@ -101,17 +154,7 @@ export function loadBlocks(): Record<string, unknown> {
   // over an ambient draft: the caller named the exact blocks to render, so a
   // draft pointer on the same request must not silently replace them.
   const override = blocksOverrideStorage.getStore() ?? getRequestDraftOverride();
-  if (override) {
-    const merged = { ...blockData };
-    for (const [key, value] of Object.entries(override)) {
-      if (value === null || value === undefined) {
-        delete merged[key];
-      } else {
-        merged[key] = value;
-      }
-    }
-    return merged;
-  }
+  if (override) return mergeOverride(blockData, override);
   return blockData;
 }
 

package/src/cms/resolve.test.ts

@@ -32,6 +32,7 @@ import {
   isEagerRequest,
   registerCommerceLoader,
   registerEagerSections,
+  registerAlwaysDeferSections,
   registerNeverDeferSections,
   resolveDecoPage,
   resolveDeferredSectionFull,
@@ -468,6 +469,22 @@ describe("shouldDeferSection — admin is the source of truth", () => {
     expect(shouldDeferSection(section, 5, mkCfg({ foldThreshold: 3 }), false)).toBe(true);
     expect(shouldDeferSection(section, 1, mkCfg({ foldThreshold: 3 }), false)).toBe(false);
   });
+
+  it("`export const deferred = true` defers one section even with respectCmsLazy off", () => {
+    const key = "site/sections/HeavyPLP.tsx";
+    registerAlwaysDeferSections([key]);
+    const section = { __resolveType: key };
+    // Not ⚡-wrapped and respectCmsLazy disabled — the per-section flag is the
+    // only thing forcing deferral here.
+    expect(shouldDeferSection(section, 0, mkCfg({ respectCmsLazy: false }), false)).toBe(true);
+  });
+
+  it("`export const deferred = true` still stays eager for bots (SEO)", () => {
+    const key = "site/sections/HeavyPLPBot.tsx";
+    registerAlwaysDeferSections([key]);
+    const section = { __resolveType: key };
+    expect(shouldDeferSection(section, 0, mkCfg({ respectCmsLazy: false }), true)).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/cms/resolve.ts

@@ -243,6 +243,28 @@ function isNeverDeferSection(key: string): boolean {
   return (G.__deco.neverDeferSectionKeys as Set<string> | undefined)?.has(key) ?? false;
 }
 
+// ---------------------------------------------------------------------------
+// Permanent alwaysDefer section registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Register sections that declared `export const deferred = true`.
+ * These sections are ALWAYS deferred (rendered client-side on scroll),
+ * independent of the global `respectCmsLazy` config — the per-section opt-in
+ * for async-rendering a single heavy section (e.g. a PLP grid) without
+ * turning on deferral site-wide. Bots stay eager via the `isBotReq`
+ * short-circuit in {@link shouldDeferSection}.
+ */
+export function registerAlwaysDeferSections(keys: string[]): void {
+  G.__deco.alwaysDeferSectionKeys ??= new Set();
+  const set: Set<string> = G.__deco.alwaysDeferSectionKeys;
+  for (const k of keys) set.add(k);
+}
+
+function isAlwaysDeferSection(key: string): boolean {
+  return (G.__deco.alwaysDeferSectionKeys as Set<string> | undefined)?.has(key) ?? false;
+}
+
 // ---------------------------------------------------------------------------
 // Deferred rawProps cache — keeps rawProps server-side to trim HTML payload
 // ---------------------------------------------------------------------------
@@ -1497,6 +1519,12 @@ export function shouldDeferSection(
   const finalKey = resolveFinalSectionKey(section, matcherCtx);
   if (!finalKey) return false;
 
+  // ── PER-SECTION FORCE-DEFER (`export const deferred = true`) ───────────────
+  // Explicit code-level opt-in to defer one section regardless of the global
+  // `respectCmsLazy` config — lets a site async-render a single heavy section
+  // without a site-wide skeleton sweep. Bots already returned eager above.
+  if (isAlwaysDeferSection(finalKey)) return true;
+
   // ── ADMIN IS THE SOURCE OF TRUTH ──────────────────────────────────────────
   // If the editor marked the section ⚡ (wrapped in CMS Lazy/Deferred at any
   // nesting level, including multivariate flags), it is deferred —