Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/display-fallbacks/functional-design/frontend-components.md
T
2026-10-31 22:17:56 +01:00

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: none without 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 nav landmark "Mobiel menu" appears in the accessibility tree at that moment.
  • Both links need a visible focus ring (BR-NAV-08, V-D9).
  • Reveal content 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: none removes 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); noscript content is not parsed with JavaScript on, so audits see no extra links.