10 KiB
Frontend Components - Unit 2: Display fallbacks
All paths are under web/. "New" and "changed" refer to the state at the end of unit 1 (worktree HEAD). Component list and responsibilities follow components.md ("Display (unit 2)"); this document fixes the details and records the differences. Rules: business-rules.md. Logic: business-logic-model.md. Data: domain-entities.md.
1. Component hierarchy
graph TD
Root["routes/__root.tsx shell"] --> Head["head: HeadContent and NoScriptStyles"]
Root --> Body["body: ChakraProvider, AppShell, Scripts"]
Body --> Nav["NavigationBar"]
Nav --> Open["NoScriptMenuOpen in noscript"]
Nav --> Mob["MobileNav"]
Mob --> Close["NoScriptMenuClose in noscript"]
Nav --> Sub["NavSubmenu and MobileNavGroup"]
Body --> Pages["Pages"]
Pages --> Rev["Reveal"]
Rev --> Hook["useReveal"]
Hook --> Pure["lib/revealPhase"]
Pages --> Def["DeferredImage"]
Def --> Twin["noscript twin image"]
Pages --> Hero["Hero, FilterBar, Testimonials, Footer"]
Seo["seo.ts preloadImage"] --> Contact["routes/contact head"]
classDef shell fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef app fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef newc fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
class Root,Head,Body shell;
class Nav,Mob,Sub,Pages,Rev,Def,Hero,Contact app;
class Open,Close,Hook,Pure,Twin,Seo newc;
Text alternative: the shell holds the noscript CSS, navigation the noscript menu links, Reveal a hook over a pure module, DeferredImage a twin, and the contact head uses preloadImage (yellow new, green changed).
2. Components
"Contract" is what the component renders in the first render on the server and in the browser (BR-HYD-01), so each change keeps the hydration rule.
New
| File | Exports and contract |
|---|---|
src/lib/revealPhase.ts |
type RevealPhase = 'settled' | 'hidden' | 'revealed'; startsHidden(top: number, viewportHeight: number): boolean (top >= viewportHeight); nextRevealPhase(phase, event: 'belowViewport' | 'inView' | 'intersected'): RevealPhase (BR-RVL-09, 12). Pure, no DOM. |
src/components/NoScript/noScriptCss.ts |
NO_SCRIPT_CSS: string, the whole sheet of BR-NAV, BR-NJS and BR-IMG-02, 04. No </, url( or @import (BR-NAV-02). The ids and attributes it names are exported as constants next to it (MOBILE_NAV_ID, HEADER_ID) and used by the components, so a rename breaks a test and not the fallback. |
src/components/NoScript/NoScriptStyles.tsx |
NoScriptStyles() renders <noscript><style>{NO_SCRIPT_CSS}</style></noscript>. Rendered by the root shell after HeadContent. Renders the same on both sides; the browser ignores the children (BR-IMG-03). |
src/components/NavigationBar/NoScriptNav.tsx |
NoScriptMenuOpen(): <noscript><a className="ns-menu-open" href="#mobile-nav" aria-label="Menu openen"> three <span aria-hidden>. NoScriptMenuClose(): <noscript><a className="ns-menu-close" href="#site-header">Menu sluiten</a></noscript>. One module, two exports; this replaces the single NoScriptNav of components.md because the CSS moved to the head (BR-NAV-01). |
Changed
| Component | Contract and behaviour |
|---|---|
hooks/useReveal.ts |
useReveal<T>() returns { ref, visible, animated }. First render: settled. useLayoutEffect once after mount: if IntersectionObserver exists, the visitor does not prefer reduced motion (matchMedia read directly) and startsHidden(rect.top, innerHeight), the phase becomes hidden. While hidden, useInView({ threshold: 0.12, rootMargin: '0px 0px -60px 0px' }) observes (it is skipped otherwise); when it reports in view the phase is revealed. No useMediaQuery. |
components/Reveal/Reveal.tsx |
Props unchanged. data-reveal visible or hidden. Style per phase as in domain-entities.md § 2; the transition props only when animated; _motionReduce { opacity: 1, transform: 'none', transition: 'none' }. |
components/DeferredImage/DeferredImage.tsx |
Props unchanged. Returns a fragment: the existing Image plus data-deferred, and <noscript><Image src={image.src} alt width height decoding="async" {...rest minus id, data-testid} /></noscript> (BR-IMG-01). ref, loading="lazy" and the src logic stay on the first image only. |
routes/__root.tsx |
RootDocument adds <NoScriptStyles /> after <HeadContent /> in <head>. |
NavigationBar |
chakra.header gets id={HEADER_ID}; the hamburger gets data-requires-js; NoScriptMenuOpen renders before the button in the right-hand div; the light logo gets loading="lazy" when !isHome (BR-PRE-05). No change to the reducer, ARIA or focus code. |
MobileNav |
NoScriptMenuClose as the first child of the content Box, before the nav. |
MobileNavGroup |
Chevron button gets data-requires-js. |
NavSubmenu |
Wrapper Box gets data-submenu, the panel Box data-submenu-panel, the chevron data-requires-js. |
Hero, HeroArrows, HeroPauseButton |
data-requires-js on each arrow button, the pause button and the progress bar. The slide loaded logic is unchanged. |
FilterBar |
Root div gets data-requires-js. |
Testimonials (CarouselPlaceholder) |
The 48 px controls spacer gets data-requires-js. The review copies stay as unit 1 made them. |
Footer, FooterColumn |
FooterColumn takes an optional requiresJs prop that puts data-requires-js on its root; the Contact column passes it. |
ContactDetails |
The narrow-variant portrait gets loading="lazy" (BR-PRE-05). |
routes/contact.tsx |
head() returns links: [...pageHead('/contact').links, preloadImage(image, { media: ASIDE_MEDIA })]; ASIDE_MEDIA is imported from ContactAside. |
seo.ts |
Adds preloadImage(image, options?) and the HeadLink type (BR-PRE-03). pageHead unchanged. |
PortfolioGallery |
Comment on eagerCount={0} rewritten (BR-PRE-08); behaviour unchanged. |
Unchanged (verified)
ContactAside (picture and source already work without JavaScript), FramedImage, MediaText, IntroGallery, PhotoDuo, PhotoMosaic, PortfolioGrid, InstagramGrid, Pricing (they only render DeferredImage or Image), useInView (still used by DeferredImage, IntroGallery, Testimonials, ContactPanel), usePageLoaded, BackToTop, Lightbox, ContactFormGate, ContactPanel, NotFound.
3. First-render contract
| Component | Server and hydrating render | After hydration |
|---|---|---|
Reveal |
Settled, visible | Hidden below the viewport (layout effect), revealed on scroll |
DeferredImage |
Image without src, data-deferred, plus noscript twin (not rendered in the browser) |
src set after load and in view, as unit 1 |
NoScriptStyles, NoScriptMenuOpen, NoScriptMenuClose |
noscript with children |
Browser ignores the children |
NavigationBar light logo |
loading="lazy" unless pathname is / (same on both sides) |
Unchanged |
| Hero, FilterBar, chevrons, hamburger | As unit 1, plus the marker attribute | Unchanged |
4. The 21 Reveal call sites
Props unchanged; nothing to edit. Verified by grep of <Reveal in src (21 non-test lines).
| File | Count | Notes |
|---|---|---|
components/about/StorySection/StorySection.tsx |
1 | |
components/CallToAction/CallToAction.tsx |
1 | textAlign prop |
components/home/ContactSection/ContactSection.tsx |
2 | Heading and panel |
components/home/IntroGallery/IntroGallery.tsx |
2 | Heading, photo list |
components/home/Pricing/Pricing.tsx |
2 | Heading; one per card with delay |
components/home/Testimonials/Testimonials.tsx |
2 | Heading, carousel |
components/InstagramGrid/InstagramGrid.tsx |
2 | Heading, grid |
components/MediaText/MediaText.tsx |
2 | Photo column, text column; order, maxW props |
components/PhotoDuo/PhotoDuo.tsx |
1 | |
components/PhotoMosaic/PhotoMosaic.tsx |
1 | as="li", delay, grid props |
components/PortfolioGrid/PortfolioGrid.tsx |
1 | Tall; BR-RVL-13 |
components/ProcessTimeline/ProcessTimeline.tsx |
1 | data-testid, as="ol" inside |
components/shoots/StoryBlocks/StoryBlocks.tsx |
1 | |
routes/contact.tsx |
2 | One around display: none content from lg |
5. Test list (code generation input)
| Area | Test |
|---|---|
revealPhase |
P18 to P21 and examples for each transition |
useReveal, Reveal |
BR-DTS-01; also hydrate() of a page with a stubbed rectangle above and below the fold: no hydration error, the in-view Reveal never leaves visible |
DeferredImage |
renderToString markup; hydrate() clean; existing tests unchanged (client render shows no noscript content) |
NoScriptStyles, NoScriptNav |
renderToString; CSS constant checks; id constants exist in NavigationBar and MobileNav |
seo.ts |
preloadImage with and without media (P22) |
| Prerender | BR-PRE-04 over the 12 HTML files |
Browser (e2e/) |
BR-DTS-03, BR-DTS-04 |
6. Testable properties
Component-level properties: none, see "No PBT properties identified" in business-logic-model.md § 7. The pure functions startsHidden, nextRevealPhase and preloadImage have properties P18 to P22 there.
| Component | Result |
|---|---|
| All components in section 2 | No PBT properties identified: markup and wiring with fixed small inputs; example tests, axe and the browser tests cover them. The only decisions with a large input space were moved into lib/revealPhase.ts and seo.ts. |
7. Accessibility notes
- The empty deferred image is
display: nonewithout JavaScript, so a screen reader meets each photo once, in the twin (BR-IMG-02). - The open link has the existing accessible name "Menu openen"; the close link shows "Menu sluiten". Neither can announce expanded or collapsed state, since there is no script to update it. The panel becomes visible, so its
navlandmark "Mobiel menu" appears in the accessibility tree at that moment. - Both links need a visible focus ring (BR-NAV-08, V-D9).
Revealcontent is in the accessibility tree in every phase, as now ("always in the DOM and readable"); only opacity and position change.- Hiding controls with
display: noneremoves them from the accessibility tree and Tab order, which is the intent for controls that do nothing. - Lighthouse accessibility, best practices and SEO targets stay 1.0 (NFR-PR-S-01);
noscriptcontent is not parsed with JavaScript on, so audits see no extra links.