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
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 |