feat(cms): dedicated page hero field — one H1, sections are H2

apps/cms/src/app/(frontend)/[locale]/[...slug]/page.tsx

@@ -4,6 +4,7 @@ import { draftMode } from "next/headers";
 import React from "react";
 
 import { RenderBlocks } from "@/blocks/RenderBlocks";
+import { RenderHero } from "@/blocks/RenderHero";
 import { SYNTHETIC_REFS } from "@/lib/plugins/analytics/SYNTHETIC_REFS";
 import { generateMeta } from "@/lib/utils/generateMeta";
 import { generateNotFoundMeta } from "@/lib/utils/generateNotFoundMeta";
@@ -55,6 +56,7 @@ export default async function Page({ params }: Args) {
 
           <PayloadRedirects disableNotFound url={url} locale={locale} />
 
+          <RenderHero hero={page.hero} />
           <RenderBlocks blocks={page.blocks} />
         </div>
       </main>

apps/cms/src/blocks/RenderHero.tsx

@@ -0,0 +1,15 @@
+import type { Page } from "@/payload-types";
+
+import { filterHiddenBlocks } from "@/lib/fields/section/filterHiddenBlocks";
+
+import { HeroBlockComponent } from "./Hero/Component";
+
+export function RenderHero({ hero }: { hero: Page["hero"] }) {
+  const [visibleHero] = filterHiddenBlocks(hero);
+
+  if (!visibleHero) {
+    return null;
+  }
+
+  return <HeroBlockComponent {...visibleHero} />;
+}

apps/cms/src/blocks/contentBlockComponents.tsx

@@ -6,7 +6,6 @@ import { ChartBlockComponent } from "./Chart/Component";
 import { ContentBlockComponent } from "./Content/Component";
 import { CtaBandBlockComponent } from "./CtaBand/Component";
 import { FaqBlockComponent } from "./Faq/Component";
-import { HeroBlockComponent } from "./Hero/Component";
 import { LogosBlockComponent } from "./Logos/Component";
 import { NewsletterBlockComponent } from "./Newsletter/Component";
 import { RawHtmlBlockComponent } from "./RawHtml/Component";
@@ -22,7 +21,6 @@ export const contentBlockComponents = {
   newsletter: NewsletterBlockComponent,
   stats: StatsBlockComponent,
   faq: FaqBlockComponent,
-  hero: HeroBlockComponent,
   logos: LogosBlockComponent,
   rawHtml: RawHtmlBlockComponent,
   testimonialsList: TestimonialsListBlockComponent,

apps/cms/src/blocks/contentBlocks.ts

@@ -6,15 +6,13 @@ import { ChartBlock } from "./Chart/config";
 import { ContentBlock } from "./Content/config";
 import { CtaBandBlock } from "./CtaBand/config";
 import { FaqBlock } from "./Faq/config";
-import { HeroBlock } from "./Hero/config";
 import { LogosBlock } from "./Logos/config";
 import { NewsletterBlock } from "./Newsletter/config";
 import { RawHtmlBlock } from "./RawHtml/config";
 import { StatsBlock } from "./Stats/config";
 import { TestimonialsListBlock } from "./TestimonialsList/config";
 
 export const contentBlocks: Block[] = [
-  HeroBlock,
   ContentBlock,
   FaqBlock,
   TestimonialsListBlock,

apps/cms/src/blocks/heroBlocks.ts

@@ -0,0 +1,5 @@
+import type { Block } from "payload";
+
+import { HeroBlock } from "./Hero/config";
+
+export const heroBlocks: Block[] = [HeroBlock];

apps/cms/src/collections/Page/basePageFields.ts

@@ -2,6 +2,7 @@ import type { Field } from "payload";
 
 import { contentBlocks } from "@/blocks/contentBlocks";
 import { GlobalSectionSlotBlock } from "@/blocks/GlobalSectionSlot/config";
+import { heroBlocks } from "@/blocks/heroBlocks";
 import { getSoleRelationId } from "@/dal/getSoleRelationId";
 import { generateSeoFields } from "@/lib/utils/seoFields";
 
@@ -25,16 +26,41 @@ export function createBasePageFields({ withBlocksDefaultValue = false } = {}): F
             },
             {
               admin: {
+                description: {
+                  en: "The page's main heading (H1). Every page has exactly one hero.",
+                  es: "El encabezado principal de la página (H1). Cada página tiene exactamente un hero.",
+                },
+                initCollapsed: true,
+              },
+              blocks: heroBlocks,
+              label: { en: "Hero", es: "Hero" },
+              localized: true,
+              maxRows: 1,
+              minRows: 1,
+              name: "hero",
+              required: true,
+              type: "blocks",
+              ...(withBlocksDefaultValue && {
+                defaultValue: () => [{ blockType: "hero" }],
+              }),
+            },
+            {
+              admin: {
+                description: {
+                  en: "Page sections below the hero. Section titles render as H2.",
+                  es: "Secciones de la página debajo del hero. Los títulos de sección se muestran como H2.",
+                },
                 initCollapsed: true,
               },
               blocks: [...contentBlocks, GlobalSectionSlotBlock],
+              label: { en: "Sections", es: "Secciones" },
               localized: true,
               name: "blocks",
               required: true,
               type: "blocks",
               ...(withBlocksDefaultValue && {
                 defaultValue: () =>
-                  ["hero", "content", "testimonialsList", "faq"].map((blockType) => ({
+                  ["content", "testimonialsList", "faq"].map((blockType) => ({
                     blockType,
                   })),
               }),

apps/cms/src/collections/Page/extractPageContent.ts

@@ -19,11 +19,26 @@ import {
   uploadImage,
 } from "@/lib/contentExtraction";
 import type { ImageGroup, LinkResolveCtx, LinkValue, Upload } from "@/lib/contentExtraction";
-import type { GlobalBlock, Page, SectionHeadingFields } from "@/payload-types";
+import type { GlobalBlock, HeroBlock, Page, SectionHeadingFields } from "@/payload-types";
 
 type Block = Page["blocks"][number];
 type GlobalBlockContent = NonNullable<GlobalBlock["block"]>[number];
 
+function extractHeroContent(
+  hero: HeroBlock,
+  ctx: LinkResolveCtx,
+  docs: DocStore,
+  helpers: { compact: (n: (ContentNode | null | undefined)[]) => ContentNode[] }
+): ContentNode[] {
+  return [
+    ...helpers.compact([
+      ...sectionHeadingContent(hero.heading, 1),
+      groupImage(hero.image as ImageGroup, docs),
+    ]),
+    ...actionLinks(hero.actions as LinkValue[], ctx),
+  ];
+}
+
 export function extractPageBlockContent(
   block: Block,
   ctx: LinkResolveCtx,
@@ -32,14 +47,6 @@ export function extractPageBlockContent(
 ): ContentNode[] {
   const b = block as Record<string, unknown> & Block;
   switch (block.blockType) {
-    case "hero":
-      return [
-        ...helpers.compact([
-          ...sectionHeadingContent(b.heading as SectionHeadingFields, 1),
-          groupImage(b.image as ImageGroup, docs),
-        ]),
-        ...actionLinks(b.actions as LinkValue[], ctx),
-      ];
     case "content":
       return [
         ...helpers.compact([
@@ -172,6 +179,7 @@ function mergeStores(...stores: (DocStore | null)[]): DocStore {
 }
 
 const extractPageContent: ContentExtractor = async (values, ctx, { resolveDocs, helpers }) => {
+  const hero = asArray<HeroBlock>((values as { hero?: unknown }).hero);
   const blocks = asArray<Block>((values as { blocks?: unknown }).blocks);
   const locale = ctx.locale ?? I18N_CONFIG.defaultLocale;
 
@@ -197,7 +205,10 @@ const extractPageContent: ContentExtractor = async (values, ctx, { resolveDocs,
   const docs = mergeStores(docs1, docs2);
   const linkCtx: LinkResolveCtx = { docs, locale };
 
-  return blocks.flatMap((block) => extractPageBlockContent(block, linkCtx, docs, helpers));
+  return [
+    ...hero.flatMap((heroBlock) => extractHeroContent(heroBlock, linkCtx, docs, helpers)),
+    ...blocks.flatMap((block) => extractPageBlockContent(block, linkCtx, docs, helpers)),
+  ];
 };
 
 export default extractPageContent;

apps/cms/src/collections/Page/extractPageText.ts

@@ -13,9 +13,6 @@ import type { Page } from "@/payload-types";
 
 export function extractPageBlockText(block: Page["blocks"][number]): string {
   switch (block.blockType) {
-    case "hero": {
-      return extractHeroText(block);
-    }
     case "content": {
       return joinText([...sectionHeadingText(block.heading), extractLexicalText(block.content)]);
     }
@@ -52,6 +49,10 @@ export function extractPageBlockText(block: Page["blocks"][number]): string {
   }
 }
 
-export function extractPageText(page: Pick<Page, "title" | "blocks">): string {
-  return joinText([page.title, ...(page.blocks ?? []).map(extractPageBlockText)]);
+export function extractPageText(page: Pick<Page, "title" | "hero" | "blocks">): string {
+  return joinText([
+    page.title,
+    ...(page.hero ?? []).map(extractHeroText),
+    ...(page.blocks ?? []).map(extractPageBlockText),
+  ]);
 }