Files
SlpSoftware/docs/hero-integration.md
T

4.4 KiB

Hero from the CMS (SLP Software site)

The title, lead and buttons of the hero come from the CMS. The baked hero stays as the fallback. Contract and CMS side: the CMS repository, aidlc-docs/features/hero-module/inception/requirements/site-contract-agreed-with-asf.md and docs/hero-module.md.

What is CMS content and what is fixed

Part Source
Title (one field, a new line is a line break) CMS, key hero.title
Lead CMS, hero.lead (no lead: no paragraph)
Two buttons (label + target) CMS, hero.buttons (none: no buttons)
Tagline, slides, display Not used by this site (ignored)
Small line "Web & .NET development", code line, prompt Fixed text, src/i18n/nl.json, block home.hero
Screen-reader and search-engine h1 Derived: home.hero.headingPrefix ("SLP Software:") + a space + the title lines joined with single spaces
Baked fallback (title lines, lead, buttons, heading) src/i18n/nl.json, home.hero.fallback, via heroContent in src/features/landing/data/content.ts

Seed (hero-sls.json): title "Websites,\napps\n& meer." gives the heading "SLP Software: Websites, apps & meer." The baked heading stays "SLP software: websites, apps & meer" (unchanged, so the prerender is unchanged); the two differ only in capitals and the final full stop.

How it works

  1. index.html has <!--CMS:HERO-PRELOAD--><!--/CMS:HERO-PRELOAD--> and <!--CMS:DATA--> followed by a baked <script type="application/json" id="cms-data">{}</script>. The build (scripts/prerender.mjs) writes <!--CMS:HERO-HTML--> ... <!--/CMS:HERO-HTML--> around the baked title, lead and buttons in the prerendered #root (the code strip is outside the region). The host replaces the regions and the data block per request (60 s cache); nothing else about the page changes. Without a host, or when the host answers 204, the markers are plain comments.
  2. At start-up the app reads #cms-data once (src/cms-client/hero, useCmsHero), synchronously in the first render, so there is no flash of baked text. parseHero checks everything: no usable title, invalid JSON or no hero key gives the baked hero. Buttons with an empty label or a target that is not #anchor, /path or https://... are skipped (isSafeTarget), at most two are used.
  3. Hero.tsx (design B) and Era2026.tsx (time travel 2026) render the same content: the first button solid, the second outline.
  4. A change in the CMS is visible on the next page load (host cache 60 s, direct invalidation in the host).

Without a CMS hero (fallback)

No data block, hero: null (204: no hero, not live, outside the schedule), or invalid data: the baked hero. The prerender always uses the baked hero.

Baseline

The only change in the prerendered text compared with the build before this feature is the extra marker comments and the empty data block (pnpm baseline:check keeps CMS: comments and JSON blocks, so the saved baseline has to be saved again once: pnpm baseline:save; checked line by line that only those lines differ).

Open points for the CMS host

See the report of this feature: the host renders the hero region only when the hero has a usable slide, and it writes picture/h1 HTML without the lead. For this text-only site the region therefore stays the baked hero and the visitor gets the CMS text from the data block after the app has loaded. The site already styles the host's cms-hero-* classes (src/index.css) for the day the host can write a text-only region.

Layout shift (CLS) at start-up

Measured on the test site (mobile, 4x CPU, slow 4G): CLS 0.35-0.40, one shift on #root. Cause: not the hero swap (that is about 1 px, CLS 0.0007) but the static packages list #packages-static that the host injects above #root (about 288 px high, visible) and that main.tsx removes at start-up, which moves the whole page up. A second, smaller shift (0.045, platform dependent) came from the code line of the hero re-wrapping when JetBrains Mono replaced the generic monospace fallback.

Fixes: index.html takes #packages-static out of the layout (visually hidden, still in the HTML for crawlers); src/index.css defines JetBrains Mono Fallback (Courier New / Liberation Mono / Cousine, same 0.6em advance) in front of monospace. After the fix CLS is 0.000 locally (390, 412 and 1350 px wide). No change to the host markup is needed: the cms-hero-* region and the React hero take practically the same space.