# Frontend Components - Unit 1: Start migration and script step All paths are under `web/`. Interfaces for new files follow [component-methods.md](../../../inception/application-design/component-methods.md); this document fixes the details and records the additions (marked **new**). Rules: [business-rules.md](business-rules.md). Logic: [business-logic-model.md](business-logic-model.md). First-render values: [domain-entities.md § 3](domain-entities.md). ## 1. Component hierarchy ```mermaid 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 ``, `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 `` 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 `NavLink`s 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 `` 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 <address>" 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](business-logic-model.md). 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 |