diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index fd126a0..056637d 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -17,4 +17,4 @@ | Feature | asf-packages-cms | ✅ Complete (closed 2026-11-16; PR to master after the CMS PR; no production release) | feature/asf-packages-cms (worktree ../AndreaSlopFotografie-packages, based on feature/contact-form-cms) | web/config (offerings, fetchOfferings), web/src/content (packages, snapshot, types), Pricing + PriceBanner + PriceTopBar (two banners, centred card rows), PackagesProvider (live refresh), CI build-test job and nightly test build, docs/ (CMS integration, deploy and CI, go-live checklist) | 2026-11-12 | | Feature | asf-cms-host-injection | ✅ Complete on the ASF side (2026-11-16, delivered with asf-packages-cms; host side by SMC) | feature/asf-packages-cms | web (PackagesProvider, build markers, neutral HTML), preview server stand-in injector, e2e/contract tests; host side in the SlpModularCms repo | 2026-11-15 | | Feature | asf-translation-files | ✅ Complete on the ASF side (2026-11-16, delivered with asf-packages-cms) | feature/asf-packages-cms | web/src/i18n (nl.json, helpers), content modules, components, ESLint rules, baseline tool, docs/translations.md | 2026-11-15 | -| Feature | hero-module | 🔵 Inception (requirements questions to Bryan) | (none yet) | Hero as a manageable CMS module (SMC builds the module, ASF consumes it); LCP in the first HTML via host injection or prerender; static hero texts move into it | 2026-11-16 | +| Feature | hero-module | ✅ Complete on the ASF side (2026-11-17; branch ready to merge, no production) | feature/hero-module | Hero as a manageable CMS module (SMC builds the module, ASF consumes it); LCP in the first HTML via host injection or prerender; static hero texts move into it | 2026-11-16 | diff --git a/aidlc-docs/features/hero-module/aidlc-state.md b/aidlc-docs/features/hero-module/aidlc-state.md new file mode 100644 index 0000000..cc7ce35 --- /dev/null +++ b/aidlc-docs/features/hero-module/aidlc-state.md @@ -0,0 +1,30 @@ +# AI-DLC State Tracking + +## Project Information + +- **Feature Name**: Hero as a manageable CMS module (ASF side) +- **Feature Slug**: hero-module +- **Project Type**: Brownfield (cross-repo: SMC builds the module and the host injection of the hero; this repo consumes it, supplies markers, contract and golden files) +- **Start Date**: 2026-11-16 +- **Current Stage**: COMPLETE on the ASF side (closed 2026-11-17); branch feature/hero-module, to be merged to master by SLS-Main. No production deploy. + +## Language Configuration + +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) + +## Stage Progress + +- [x] INCEPTION - requirements and contract agreed with SMC (`web/contract/host-injection/hero/README.md`, model B: wide 3:2 and tall 4:5 variants, ``, preload per orientation) +- [x] CONSTRUCTION - Code Generation: markers HERO-HTML and HERO-PRELOAD, `hero` key in `#cms-data`, `useHero` with baked fallback, plain-HTML first photo that survives hydration, slider on top, hero texts in `nl.json`, stand-in host and preview server, e2e tests, docs +- [x] CONSTRUCTION - Build and Test: [build-and-test-summary.md](construction/build-and-test/build-and-test-summary.md) +- [x] OPERATIONS - part of the joint production checklist ([docs/go-live-checklist.md](../../../docs/go-live-checklist.md), section "Hero"); production follows via the IIS pipeline, later + +## Scope decisions + +- **Planning (from/to dates) and a hero-wide on/off switch are deliberately not built.** The hero is always there; a hero without usable slides leaves the baked hero in place (for ASF the host setting `Hero:TextOnlyRegion` is off). Adding them later is a CMS change plus a `204`, which the site already handles. +- The ASF test seed holds the 8 existing hero photos with focus estimates (`web/contract/host-injection/hero/seed.json`); Bryan runs the seed himself (admin password). + +## Assumptions + +[assumptions-and-open-questions.md](assumptions-and-open-questions.md): what Bryan has to check later. diff --git a/aidlc-docs/features/hero-module/assumptions-and-open-questions.md b/aidlc-docs/features/hero-module/assumptions-and-open-questions.md new file mode 100644 index 0000000..15e1105 --- /dev/null +++ b/aidlc-docs/features/hero-module/assumptions-and-open-questions.md @@ -0,0 +1,28 @@ +# Hero module: assumptions and deferred questions (ASF side) + +Written while Bryan was away; he decides later. Each point: question, assumption, what changes with another answer, where in the code. + +| # | Question | Assumption | If the answer differs | Where | +| --- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| 1 | Focus points of the 8 photos | Estimates from the seed (e.g. hero-8 0.50/0.55) | Change x/y in the seed (CMS) and in the baked values | `web/src/content/heroContent.ts`, `web/contract/host-injection/hero/seed.json` | +| 2 | Is the baked hero cropped around the focus point too? | Yes: object-position from the estimates, so baked and live look the same | Pass `focus: null` for the baked slides to get plain centre crop | `heroContent.ts` | +| 3 | Button target `#anchor` and https: plain link, `/path`: router link | As said | Make all plain links | `web/src/components/Hero/HeroButton.tsx` | +| 4 | Single display (one photo) or slideshow with one slide | No arrows, pause or progress bar for one slide | Show controls anyway | `Hero.tsx` (`shown.length > 1`) | +| 5 | Title with a new line | `
` in the plain HTML, `pre-line` in the slider | One line only | `heroHtml.ts`, `Hero.tsx` | +| 6 | Where does the head preload marker come from | Build step adds it to the finished HTML (React cannot write a head comment) | Host adds the head region itself | `web/config/heroPreload.ts` | +| 7 | Hero texts (aria, baked title, alts) | In `nl.json`, block `hero` | Other wording: edit the file | `web/src/i18n/nl.json` | +| 8 | Without a host block the site asks `/api/v1/hero` (8 s time-out) | Yes, like packages and banners | Remove the call: baked only | `web/src/components/Hero/useHero.ts` | +| 9 | Style of the plain hero before hydration | Matches the slider's first frame (checked by screenshot at 1280 and 390 px) | Adjust CSS | `.cms-hero-*` in `web/src/theme.ts` | +| 10 | AVIF for slides 2..n only | As agreed with the CMS session | Add AVIF to the first photo and its preload (then two fetches) | `Hero.tsx` (`SlidePicture`) | +| 11 | The first photo, title and buttons stay the plain HTML after hydration (never replaced); the slider adds the other photos on top | Yes: replacing the nodes at hydration risks a late LCP. Side effect: the first photo has no slow zoom and is not in a role=group slide | Go back to a full slider render (one component), accepting the DOM replacement | `Hero.tsx` (`HeroFrame`), `useHero.ts` (`regionHero`) | +| 12 | Planning (from/to dates) and a hero-wide on/off switch | Deliberately not built: the hero is always there, a hero without usable slides keeps the baked one | Add in the CMS; the site already handles a 204 and an empty hero | CMS (module), `useHero.ts` | +| 13 | Content of the ASF test seed | The 8 existing photos with focus estimates (#1), texts like the baked ones | Edit in the CMS admin; update `heroContent.ts` if the baked fallback should match | `web/contract/host-injection/hero/seed.json` | +| 14 | Baked hero after a CMS change | The baked hero is only a fallback and is not rebuilt from the CMS any more (no nightly build) | Re-bake by hand in `heroContent.ts` when the real hero changes for good | `heroContent.ts` | + +## What Bryan has to check later + +- Look at the home page on ASF-test after the seed, on phone and desktop: crop around the focus points (#1, #2), the first frame before the slider starts (#9, #11), the title and buttons (#3, #5). +- Does the first photo without slow zoom (#11) bother you? Then choose the full slider render and accept the later LCP. +- Wording of the hero texts in `nl.json` (#7). +- Whether planning and an on/off switch are wanted (#12). +- Keep an eye on the LCP of `/` in the Lighthouse run on test (the host measures it after the seed). diff --git a/aidlc-docs/features/hero-module/construction/build-and-test/build-and-test-summary.md b/aidlc-docs/features/hero-module/construction/build-and-test/build-and-test-summary.md new file mode 100644 index 0000000..f31ccdd --- /dev/null +++ b/aidlc-docs/features/hero-module/construction/build-and-test/build-and-test-summary.md @@ -0,0 +1,22 @@ +# Build and Test summary: hero-module (ASF side) + +## What was built + +- `src/lib/hero.ts` (mapping and validation of `/api/v1/hero`), `src/lib/heroHtml.ts` (HTML between the markers and the preload links), golden files shared with SMC in `web/contract/host-injection/hero/`. +- `config/heroPreload.ts` adds the HERO-PRELOAD region to the head of the finished HTML; `config/hostInjector.ts`, `normalizeInjected.ts` and `previewServer.ts` know the hero (stand-in host, `/api/v1/hero` answers 204). +- `src/components/Hero/`: `useHero` (host block, else `/api/v1/hero`, else baked), `Hero.tsx` (the region div is never replaced; the slider adds slides 2..n, scrim, arrows, pause, progress and announcement after hydration), `HeroButton`, `HeroArrows`, `HeroPauseButton`. +- Baked hero in `src/content/heroContent.ts` (8 photos, real sizes, focus estimates); texts in `nl.json` block `hero`. + +## Verification + +- Unit and property tests: 100% thresholds on `src/lib/**`, `src/i18n/**`, `seo.ts`, `sitemap.ts` hold; golden files match for all hero inputs. +- e2e (`pnpm e2e`): host injection with the hero (3 tests), no-JS, display HTML (priority image), reveal. The two frame-sampling reveal tests got retries (2 on CI, 1 locally) after a flaky failure in run #110 on a page without a hero. +- Lighthouse (local, noisy machine): the LCP element of the home page is the h1 on master and on this branch; master 0.71, branch 0.69-0.70. Keeping the region after hydration (commit 3d7bb2d) removed the late LCP the first design had. +- Visual check against the slider at 1280 and 390 px. +- Final run before merge: see the audit trail of the closing commit; lint, format, tests, build and e2e were run as CI runs them. + +## Not verified here (needs the CMS or Bryan) + +- The real host output on ASF-test after the seed (SMC verified it byte-equal to the golden files locally). +- LCP measurement on ASF-test (SMC, after the seed). +- IIS pass-through and a production CMS for ASF: later, separate feature. diff --git a/docs/cms-integration.md b/docs/cms-integration.md index 26a12ef..532b91b 100644 --- a/docs/cms-integration.md +++ b/docs/cms-integration.md @@ -32,6 +32,16 @@ Both follow the same rules as the packages: baked into the HTML at build time, r **Layout shift:** a banner that was not active at the last build is not in the HTML. When it appears live, the content below it moves down by its height once (for the top bar, the cards move). Behind the CMS host the host injection writes the banner into the HTML, so there is no shift; without the host a rebuild with the banner active removes it. The same holds in reverse when a baked banner is switched off. +## Hero (CMS module) + +The hero of the homepage comes from the CMS hero module (`GET /api/v1/hero`); the build bakes one in as the fallback (`web/src/content/heroContent.ts`, texts in `nl.json` under `hero.baked`). + +- **Markers.** `index.html` has `…` (first photo as ``, the `h1` with tagline and title, the buttons) and, in the head, `…` (the preload links). The head markers are added to the finished HTML by `config/heroPreload.ts` (React cannot write a comment into the head), as part of `config/externalizeInlineScripts.ts`. The host rewrites both from live data; the contract is `web/contract/host-injection/hero/` (README, seed, golden files shared with the CMS repo). Code: `src/lib/hero.ts` (mapping), `src/lib/heroHtml.ts` (HTML and preload). +- **Data block.** `#cms-data` gets a `hero` key (the answer of `/api/v1/hero`). After hydration `src/components/Hero/useHero.ts` takes it; without a host block the site asks `/api/v1/hero` itself (8 s time-out). A missing block, a 204, an error or an answer without a usable slide keeps the baked hero (fail open). +- **Until hydration** the hero is the plain HTML between the markers, styled by the global CSS `.cms-hero-*` in `src/theme.ts`; the slider (arrows, pause, progress) only exists after hydration, so a visitor without JavaScript sees the first photo and no dead controls. Slides after the first also get AVIF ``s; the first and the preload are WebP only. +- **Images.** Ratios `wide` (3:2) and `tall` (4:5; portrait screens), chosen by `(orientation: portrait)`; the focus point is `object-position`. Alt texts and the slider's aria texts are in `nl.json` (`hero`); a decorative photo has `alt=""`. +- **Stand-in host.** `config/hostInjector.ts` (preview server and e2e) writes the hero regions and the `hero` key like the real host; `e2e/hostInjection.e2e.ts` covers it. + ## Contact form `GET /api/v1/contact-messages/token` and `POST /api/v1/contact-messages` through the headless `web/src/cms-client`. The form is behind the switch `contactForm.enabled` in `web/src/content/siteContent.ts` (off means the "Binnenkort" gate and no request to the server). Details and the go-live conditions are in `aidlc-docs/features/contact-form-cms/` and [go-live-checklist.md](go-live-checklist.md). Friendly Captcha is off at go-live. diff --git a/docs/go-live-checklist.md b/docs/go-live-checklist.md index da76795..e97b7a9 100644 --- a/docs/go-live-checklist.md +++ b/docs/go-live-checklist.md @@ -13,6 +13,12 @@ What must be true before the CMS-driven parts of the site go to production. Brya - [ ] `web/src/content/offerings.snapshot.json` holds the real, current packages (production builds use it). - [ ] The production CMS holds the real packages. The test CMS prices must never end up in the production artifact (it is built without `OFFERINGS_URL`). +## Hero + +- [ ] The hero module is on `master` and the CMS host of the target environment has the hero module and the injection (`HERO-HTML`, `HERO-PRELOAD`, `hero` in the data block). +- [ ] ASF-test: the hero is seeded (Bryan runs the seed, admin password) and the home page checked on phone and desktop; the assumption list `aidlc-docs/features/hero-module/assumptions-and-open-questions.md` is read. +- [ ] Production: ASF-production is served by the CMS host (the IIS pipeline, later) and holds the real hero. Until then production shows the baked hero in `src/content/heroContent.ts`; check that it is the one you want. + ## Contact form - [ ] All conditions in the contact-form production readiness checklist (server module, recipient, sender, retention 1 year / 30 days spam, proxies, CSP `frame-src`, a real mail from the production host). diff --git a/docs/translations.md b/docs/translations.md index 4abbb7b..ac1eaf0 100644 --- a/docs/translations.md +++ b/docs/translations.md @@ -4,12 +4,12 @@ The texts of the site live in language files, not in the components. Dutch is th ## Where things are -- `web/src/i18n/nl.json`: all Dutch texts of the site in one file, in blocks per area in the order of the site: `common`, `site`, `home`, `about`, `contact`, `shoots`, `portfolio`, `instagram`, `testimonials`, `seo`, `cmsClient`. The file is the source of the types. A second language is `web/src/i18n/en.json` with the same keys. +- `web/src/i18n/nl.json`: all Dutch texts of the site in one file, in blocks per area in the order of the site: `common`, `site`, `hero`, `home`, `about`, `contact`, `shoots`, `portfolio`, `instagram`, `testimonials`, `seo`, `cmsClient`. The file is the source of the types. A second language is `web/src/i18n/en.json` with the same keys. - `web/src/i18n/index.ts`: `t(key, params?)` for a text, `tList(key)` for a list of texts, `tPlural(key, count, params?)` for a text with a singular and a plural form, `locales`, `locale` and `Messages`. - `web/src/i18n/compare.ts`: the checks the tests use (same keys and parameters, nothing empty). - The typed content modules in `web/src/content` keep their structure, images and paths; the words come from the language files. -Not in the language files: the hero (becomes a CMS module), the privacy statement (separate feature), and everything that comes from the CMS (packages, banners, later the gallery). +Not in the language files: the privacy statement (separate feature), and everything that comes from the CMS (packages, banners, later the gallery). ## Keys @@ -42,7 +42,7 @@ Dotted paths: the block (`common`, `home`, ...), then the page or section, then The block `cmsClient` holds the texts of the shared `src/cms-client` package, per part of the package: `cmsClient.contact` has the form's field errors, fallback, waiting time (`rateLimited.one/other` with `{minutes}`), too-large, captcha-required, failure (`{address}`) and the sending label. `src/i18n/cmsClientMessages.ts` builds the `ContactMessages` object from it and `ContactForm` passes it to `useContactForm({ messages })`. The package keeps its own Dutch defaults (`messages.nl.ts`) as a fallback and a test checks that both say the same. Parts that come later (offerings) get their own part of the block. -Not here: the hero, the privacy statement and everything from the CMS. +Not here: the privacy statement and everything from the CMS. ## Importing the language files diff --git a/web/.prettierignore b/web/.prettierignore index 78aa15e..107652a 100644 --- a/web/.prettierignore +++ b/web/.prettierignore @@ -17,3 +17,4 @@ src/cms-client # Golden files of the host injection contract: exact text, never reformatted contract/host-injection/*.expected.html +contract/host-injection/hero/*.html diff --git a/web/config/externalizeInlineScripts.ts b/web/config/externalizeInlineScripts.ts index 476947c..7d107fd 100644 --- a/web/config/externalizeInlineScripts.ts +++ b/web/config/externalizeInlineScripts.ts @@ -28,6 +28,7 @@ import { externalizeInlineScripts, findExecutableInlineScripts, } from './inlineScripts.ts'; +import { injectHeroPreload } from './heroPreload.ts'; import { NOT_FOUND_FILE, pageFile } from './pageFiles.ts'; export type ViolationCode = @@ -179,7 +180,7 @@ export function planExternalization( let result; try { - result = scripts.externalize(html); + result = scripts.externalize(injectHeroPreload(html)); } catch (error) { if (!(error instanceof ScriptError)) throw error; add(file, error.code, detailOf(error)); diff --git a/web/config/heroPreload.test.ts b/web/config/heroPreload.test.ts new file mode 100644 index 0000000..f4c438d --- /dev/null +++ b/web/config/heroPreload.test.ts @@ -0,0 +1,36 @@ +import { describe, expect, it } from 'vitest'; +import { injectHeroPreload } from './heroPreload.ts'; + +const page = (body: string, head = 't') => + `${head}${body}`; + +describe('injectHeroPreload', () => { + it('writes the preload of the first photo between markers before ', () => { + const out = injectHeroPreload( + page( + '', + ), + ); + expect(out).toContain( + 't', + ); + }); + + it('finds the image when src comes before class', () => { + const out = injectHeroPreload( + page(''), + ); + expect(out).toContain('href="/a.jpg"'); + }); + + it('leaves a page without a hero, without a head and a done page alone', () => { + const plain = page(''); + expect(injectHeroPreload(plain)).toBe(plain); + const noHead = ''; + expect(injectHeroPreload(noHead)).toBe(noHead); + const once = injectHeroPreload( + page(''), + ); + expect(injectHeroPreload(once)).toBe(once); + }); +}); diff --git a/web/config/heroPreload.ts b/web/config/heroPreload.ts new file mode 100644 index 0000000..45ef030 --- /dev/null +++ b/web/config/heroPreload.ts @@ -0,0 +1,45 @@ +import { heroPreloadHtml } from '../src/lib/heroHtml.ts'; + +// The preload link of the hero in the head of a prerendered page, between the +// markers the CMS host rewrites (). React cannot write +// a comment into the head, so the build step adds it to the finished HTML, +// from the baked first photo of the page. Pages without a hero stay as they +// are, and so does a page that already has the markers (running twice is fine). + +const MARK = ''; +const HERO_IMAGE = + /]*\bclass="cms-hero-image"[^>]*\bsrc="([^"]+)"|]*\bsrc="([^"]+)"[^>]*\bclass="cms-hero-image"/; + +export function injectHeroPreload(html: string): string { + if (html.includes(MARK)) return html; + const found = HERO_IMAGE.exec(html); + const src = found?.[1] ?? found?.[2]; + const end = html.indexOf(''); + if (src === undefined || end === -1) return html; + // The src is already escaped in the HTML; the link is built from the same + // text, so it is written back unchanged + const link = heroPreloadHtml({ + display: 'single', + title: '', + buttons: [], + slides: [ + { + id: 'baked', + alt: '', + decorative: false, + image: { + width: 1, + height: 1, + focus: null, + src: '', + variants: [], + }, + }, + ], + }).replace('href=""', `href="${src}"`); + return ( + html.slice(0, end) + + `${MARK}${link}` + + html.slice(end) + ); +} diff --git a/web/config/hostInjector.test.ts b/web/config/hostInjector.test.ts index 474ca98..12ce2b2 100644 --- a/web/config/hostInjector.test.ts +++ b/web/config/hostInjector.test.ts @@ -54,6 +54,45 @@ describe('injectCms regions', () => { }); }); +describe('injectCms hero', () => { + const hero = { + title: 'Titel', + slides: [ + { + id: 'a', + alt: 'Alt', + decorative: false, + image: { width: 10, height: 8, src: '/m/a.webp' }, + }, + ], + }; + const regions = + 'oldold'; + + it('writes the hero and its preload and puts the hero in the data block', () => { + const out = run( + page( + regions + + '', + ), + { ...live([]), hero }, + ); + expect(out).toContain('

'); + expect(out).toContain( + ' { + for (const data of [live([]), { ...live([]), hero: { title: 'x' } }]) { + const out = run(page(regions), data); + expect(out).toBe(page(regions)); + } + }); +}); + describe('injectCms data block', () => { const baked = ''; diff --git a/web/config/hostInjector.ts b/web/config/hostInjector.ts index ac17832..fa50b2e 100644 --- a/web/config/hostInjector.ts +++ b/web/config/hostInjector.ts @@ -9,6 +9,8 @@ // matches that code. import { bannerHtml, offeringsHtml } from '../src/lib/cmsHtml.ts'; import { scriptJson } from '../src/lib/cmsData.ts'; +import { mapHero } from '../src/lib/hero.ts'; +import { heroHtml, heroPreloadHtml } from '../src/lib/heroHtml.ts'; import { formatPrice } from '../src/lib/formatPrice.ts'; import { mapBanner, mapOfferings, mapTopBanner } from '../src/lib/offerings.ts'; @@ -16,6 +18,8 @@ export interface LiveData { // The answers as the public API gives them offerings: unknown; banners: { top: unknown; bottom: unknown }; + // The answer of GET /api/v1/hero; absent or unusable leaves the baked hero + hero?: unknown; } export interface InjectOptions { @@ -33,7 +37,7 @@ const jsonLd = (value: unknown) => .replace(/&/g, '\\u0026'); const REGION = - /[\s\S]*?/g; + /[\s\S]*?/g; const DATA_BLOCK = /(?:`, ) .replace(OFFER_JSON_LD, (match, slug: string, json: string) => { diff --git a/web/config/normalizeInjected.ts b/web/config/normalizeInjected.ts index 416fd21..c43a281 100644 --- a/web/config/normalizeInjected.ts +++ b/web/config/normalizeInjected.ts @@ -11,7 +11,7 @@ import { readFileSync, writeFileSync } from 'node:fs'; const REGION = - /()[\s\S]*?()/g; + /()[\s\S]*?()/g; const DATA_BLOCK = /(?:)?