Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/start-migration/functional-design/frontend-components.md
T
SluijsensandClaude Opus 5.5 65c850e949 Adds the prerendering requirements, design and baseline
Records the requirements, execution plan, application design, the first unit's
functional design and code generation plan, and the baseline on master.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 17:41:12 +01:00

12 KiB

Frontend Components - Unit 1: Start migration and script step

All paths are under web/. Interfaces for new files follow component-methods.md; this document fixes the details and records the additions (marked new). Rules: business-rules.md. Logic: business-logic-model.md. First-render values: domain-entities.md § 3.

1. Component hierarchy

graph TD
    Vite["vite.config.ts with Start plugin"] --> Router["src/router.tsx getRouter"]
    Client["src/client.tsx: Sentry, then hydrate"] --> Router
    Router --> Root["routes/__root.tsx shellComponent"]
    Root --> Html["html, HeadContent, ChakraProvider, Scripts"]
    Html --> App["AppShell"]
    App --> Nav["NavigationBar and MobileNav"]
    App --> Out["Outlet: page routes and catch-all"]
    App --> Foot["Footer"]
    App --> Top["BackToTop"]
    App --> Umami["UmamiAnalytics"]
    Out --> Pages["index, contact, portfolio, other pages"]
    Out --> NF["routes/$.tsx NotFound"]
    Pages --> Panel["ContactPanel and ContactFormGate"]
    Pages --> Details["ContactDetails"]
    Pages --> Tests["Testimonials"]
    Nav --> Hyd["useHydrated"]
    Foot --> Mail["useEmailAddress"]
    Details --> Mail
    Panel --> Mail
    NF --> Hyd
    Pages --> Hyd
    Mail --> Hyd
    Cfg["config: pageFiles, inlineScripts, externalizeInlineScripts, previewServer"] -.-> Vite
    classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef app fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef hook fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef infra fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
    class Vite,Router,Client,Root,Html build;
    class App,Nav,Out,Foot,Top,Umami,Pages,NF,Panel,Details,Tests app;
    class Hyd,Mail hook;
    class Cfg infra;

Text alternative: the Start build and the browser entry both use getRouter; the root shell renders the document around AppShell, whose navigation, pages, footer and monitoring components use the hydration hooks (green = app components, yellow = hooks, blue = build and entry, orange = config tools).

2. Changed components

"Contract" is what the component renders in the first render, on the server and in the browser (BR-HYD-01).

Build, entry and document

Component Status Contract and behaviour
vite.config.ts Changed tanstackStart with prerender: pages from sitePages plus /404 to /404.html, autoSubfolderIndex: false, no extra crawling. Start plugin only outside Vitest. define of VITE_BUILD_YEAR. sitemapPlugin emits in the client environment only. CSP headers for server and preview stay from securityHeaders.
src/router.tsx new getRouter() and a shared options function (routeTree, scrollRestoration: true, defaultErrorComponent: ErrorPage).
src/routes/__root.tsx Changed shellComponent renders <html lang="nl">, HeadContent, ChakraProvider value={system} around children, Scripts last. head() adds charset, viewport, favicon.png icon and apple-touch-icon besides siteHead. Fonts imported here. component stays RootLayout (without HeadContent, which moves to the shell). notFoundComponent and errorComponent stay.
src/client.tsx new startSentry(), then hydrate inside StrictMode. Replaces main.tsx; index.html is removed.
src/routes/$.tsx new Catch-all route, component NotFound. No head().
config/inlineScripts.ts new externalizeInlineScripts, findExecutableInlineScripts (signatures as in component-methods.md).
config/externalizeInlineScripts.ts new externalizeOutput(clientDir), plus exported planExternalization(files, context) (new, pure core). Runs as a script with Node type stripping like writeServerConfig.ts.
config/pageFiles.ts new pageFile, pagePath, NOT_FOUND_FILE, NOT_FOUND_PATH.
config/previewServer.ts new resolveRequest, startPreviewServer. package.json preview runs it.
config/sitemapPlugin.ts Changed Emits sitemap.xml only when this.environment.name is the client environment (to verify V7).
src/test/renderApp.tsx Changed Router from the shared options with memory history; no <html> shell (V2).
e2e/ new Playwright tests of BR-TST-05 and BR-TST-06.

Hooks

Hook Status Interface and contract
hooks/useHydrated.ts new useHydrated(): boolean. useSyncExternalStore(subscribeNoop, () => true, () => false). Same behaviour as the useHydrated that @tanstack/react-router exports (marked internal there), so the project owns its copy.
hooks/useEmailAddress.ts new useEmailAddress(email: EmailAddress): { available: boolean; address: string | null } (BR-MAIL-01).
hooks/usePageLoaded.ts Changed Store-based (BR-HYD-04). Returns false while hydrating.
hooks/useInView.ts Changed Same options and return { ref, inView }. inView = skip || intersected || unsupported (BR-HYD-05). The "no observer counts as in view" contract is applied after the first render.
hooks/useReveal.ts Changed useMediaQuery without ssr: false; first render reducedMotion is false. Returns { ref, visible } as before; the visible-by-default rule is unit 2.
hooks/useScrolledPast.tsx Unchanged Verified safe (BR-HYD-06). The application design lists it as changed; it needs no change.
Hero/useHeroSlider.ts Changed hidden from a store, useMediaQuery without ssr: false; first render autoplay is count > 1.

Pages and components

Component Status Contract
routes/index.tsx Changed pakket passed to ContactSection is hydrated ? search.pakket : undefined.
routes/contact.tsx Changed Same for ContactPanel; the tidy effect depends on the gated value.
routes/portfolio.tsx Changed shoot passed to PortfolioGallery is hydrated ? search.shoot : undefined; navigation callback unchanged.
NavigationBar Changed useBreakpointValue without ssr: false (first render false); all NavLinks get activeOptions={{ exact: true, includeSearch: false }}. Layout stays CSS-driven, so no visible jump.
MobileNav Changed Top-level links get the same activeOptions.
IntroGallery Unchanged useBreakpointValue already uses the default; first render scrollable is true (BR-HYD-08).
ContactSection Changed useMediaQuery without ssr: false; effect unchanged.
TestimonialCarousel Changed useMediaQuery without ssr: false. Only renders after hydration.
Testimonials Changed CarouselPlaceholder renders every visible review (longest in flow, others aria-hidden, visually hidden, inert) so the texts are in the HTML (BR-LZY-02).
NotFound Changed hydrated && isShootSectionPath(pathname) picks the buttons. Renders its own <title> and noindex meta as today.
Footer Changed Year: hydrated ? new Date().getFullYear() : BUILD_YEAR. Contact column per useEmailAddress: absent, placeholder item, or link (BR-MAIL-03).
ContactDetails Changed contactChannels(email, socials, hydrated); renders an empty aria-hidden item with minH 44 px for email-pending (BR-MAIL-04). Returns null only when there is no channel at all.
ContactFormGate Changed Notice per BR-MAIL-05: sentence only plus hidden placeholders before hydration; address text, link and button after. mb depends on available.
ContactForm Changed Reads useEmailAddress; the mail link in the failed state uses its address. shownAt unchanged (BR-HYD-16).
ContactPanel Unchanged Props and behaviour as today; lazy form per BR-LZY-01.
PriceCard Unchanged Accepted attribute difference (BR-HYD-21).
UmamiAnalytics Changed hostname default read in the effect.
AppShell, BackToTop, Hero, PortfolioGallery, Lightbox Unchanged Verified safe (BR-HYD-19). useRouteFocus unchanged (V14).
lib/emailAddress.ts Changed Adds isEmailAddressValid; emailAddress reuses it.
lib/contactChannels.ts Changed Third parameter assemble; new kind email-pending (BR-MAIL-07).

3. Placeholder specification

Place Before hydration (available) After hydration
Footer Contact column Title "Contact" and one empty li, aria-hidden, data-email-pending, minH 44 px below lg li with the FooterLink mailto
Contact card (twice) First li empty, aria-hidden, data-email-pending, minH 44 px li with the mailto link and icon
Gate notice Sentence only. Hidden inline block n characters wide where " Mail me voor nu op " will come; hidden button placeholder with the button's recipe and label Sentence extended, address link, "Stuur een e-mail" button

All placeholders carry no text a reader needs, no href, no address and no mailto. Measured sizes (V10) must give CLS below 0.01 (BR-MEA-04).

4. Interaction flows that must keep working

Flow Behaviour after the change
Direct load of /?pakket=gezin#contact HTML paints; after hydration the panel takes the package, the form loads, the address bar is tidied to /#contact, smooth scroll and focus on the contact heading
Direct load of /contact?pakket=gezin HTML paints; the package is preselected after hydration; the URL becomes /contact without a history entry
Direct load of /portfolio?shoot=gezin All photos first, then the filtered list; filter clicks navigate with replace and keep the scroll position
Click "Boek" on a price card (client navigation) Search applies in the first render of the next state; same as today
Mobile menu Opens, closes with button and Escape, sets body overflow; closes at lg and on route change
Unknown URL 404 page in the shell; extra buttons under /soorten-fotoshoots/ after hydration

5. Accessibility and layout notes

  • Placeholders are aria-hidden and empty; they add no stops for keyboard or screen reader users.
  • Visually hidden testimonial copies are aria-hidden and inert, so each review is read once, in the carousel.
  • The footer "Contact" title stands alone without JavaScript until unit 2 decides (BR-MAIL-09).
  • IntroGallery's list has tabIndex={0} in the HTML at every width until hydration; it is removed from sm up afterwards (BR-HYD-08).
  • Lighthouse accessibility, best practices and SEO targets stay 1.0 (NFR-PR-S-01); the check at the end of unit 1 is informative, the final targets are unit 3.

6. Testable properties

Component-level properties: none, see "No PBT properties identified" in business-logic-model.md § 9. The pure functions (inlineScripts, pageFile, planExternalization, contactChannels, isEmailAddressValid, resolveRequest) have properties P1 to P17 there.

7. Example-based test list (code generation input)

Area Test
Hooks useHydrated, usePageLoaded, useInView, useHeroSlider.hidden: server snapshot value while hydrating (hydrateRoot into server-rendered markup), real value after
Routes Contact, home and portfolio: no search in the first render, search applied after; tidy navigation still fires; filter navigation still works
Footer Year equals build year while hydrating, current year after; Contact column states absent, pending, ready
Contact components ContactDetails, ContactFormGate, ContactForm: no address in renderToString output; address after hydration
NotFound One button while hydrating; two extra under /soorten-fotoshoots/ after
Navigation No link current on an unknown sub-path; current on real pages and with a search
Script step Worked examples of business-logic-model.md § 3.1; each violation code; unsupported forms; unterminated script
Preview server Status, headers, methods, content types for /, /x, /file.ext, unknown, traversal
Build and e2e BR-TST-05 and BR-TST-06