Adds the functional design of the second unit
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+319
@@ -0,0 +1,319 @@
|
||||
# Business Logic Model - Unit 2: Display fallbacks
|
||||
|
||||
Unit 2 of the feature "prerendering": fade-in, no JavaScript, first photo (FR-PR-09 to 13, FR-PR-21; D6 to D9). It builds on unit 1 (hydration rule BR-HYD-01: the first browser render equals the HTML). Rules: [business-rules.md](business-rules.md). Data: [domain-entities.md](domain-entities.md). Components: [frontend-components.md](frontend-components.md).
|
||||
|
||||
Everything here was checked against `web/src`, the built `web/dist/client`, the Lighthouse reports of the measurement at the gate (`after` and `revealvisible`, mobile and desktop) and a real Chrome driven by Playwright against the local preview server, on 2026-10-31. No application code was changed.
|
||||
|
||||
## 1. Reveal
|
||||
|
||||
### 1.1 Lifetime of one `Reveal`
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Server["Prerender: settled, visible"] --> Html["HTML on screen, content visible"]
|
||||
Html --> Hydrate["Hydrating render: settled, same markup"]
|
||||
Hydrate --> Layout["Layout effect before paint: measure top edge"]
|
||||
Layout --> Test{"Top at or below innerHeight"}
|
||||
Test -->|"no"| Stay["Stays settled: no change at all"]
|
||||
Test -->|"yes"| Hide["Set hidden: opacity 0, no transition"]
|
||||
Hide --> Watch["Observer: threshold 0.12, margin 60 px"]
|
||||
Watch --> Fire["Intersected once"]
|
||||
Fire --> Fade["Revealed: fade 0.8 s after delay"]
|
||||
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef state fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class Server,Html,Hydrate build;
|
||||
class Layout,Watch,Fire,Hide state;
|
||||
class Stay,Fade state;
|
||||
class Test choice;
|
||||
```
|
||||
|
||||
Text alternative: the HTML and hydrating render are visible; a layout effect hides only elements wholly below the viewport before the next paint, and an observer reveals each once.
|
||||
|
||||
### 1.2 Why the layout effect and why `top >= innerHeight`
|
||||
|
||||
- **Layout effect, not a passive effect.** A passive effect runs after the browser painted. An element in the 60 px band at the bottom of the screen would be painted visible from the HTML, then hidden, which is the flash FR-PR-09 forbids. A layout effect runs after React committed the hydrated tree and before the next paint, and a state change inside it is applied synchronously before that paint. No `useLayoutEffect` exists in `src` today; React 19.3 does not warn for it while prerendering.
|
||||
- **Reads before writes.** Every `Reveal` in the commit reads its rectangle in its own layout effect; the state updates are applied after all effects ran. The browser lays out once, not once per `Reveal`.
|
||||
- **The test is the viewport edge, not the 60 px line.** The trigger line (`rootMargin` bottom -60 px) is how late the fade starts while scrolling. At load the question is "was this painted on screen". Only an element that starts at or below the bottom edge was not.
|
||||
- **No transition for the hide.** The hidden style sets `transition: none`. A transition is taken from the style after the change, so the step from settled to hidden does not animate. The transition properties exist only in the revealed style.
|
||||
- **Reduced motion is read directly.** Chakra's `useMediaQuery` (BR-HYD-07) still returns its server-safe `false` in that same layout effect, because its own effect has not run. Reading `matchMedia` in the effect avoids a hide followed by an animated reveal.
|
||||
|
||||
### 1.3 Anything that breaks
|
||||
|
||||
All 21 call sites keep their props. What each does under the new rule at 412 x 823 and 1350 x 940 (probe of `data-reveal` and tops, dist build):
|
||||
|
||||
| Call site (file, count) | Wraps | Effect |
|
||||
|---|---|---|
|
||||
| `home/IntroGallery` (2), `home/Pricing` (2), `home/Testimonials` (2), `home/ContactSection` (2), `InstagramGrid` (2) | Headings, photo lists, cards | First `Reveal` of `/` is at top 919 px at 412 x 823: all hidden at load, fade on scroll, as now. At 1350 x 940 the first ones are in view and stay. `Pricing` stagger (`delay`) only shows on scroll (BR-RVL-06). |
|
||||
| `MediaText` (2: photo and text) | Photo column and text column of `/over-mij`, `/soorten-fotoshoots`, shoot pages | In view at the top of these pages: visible at once. Before: 1.0 s after the first paint (observed LCP 977 to 1047 ms at 412 x 823). |
|
||||
| `PhotoMosaic` (1, `as="li"` with `delay`), `PhotoDuo` (1), `PortfolioGrid` (1), `ProcessTimeline` (1), `StoryBlocks` (1), `CallToAction` (1), `StorySection` (1), `routes/contact` (2) | Lists, grids, blocks | Same rule. `PortfolioGrid` is the tall one: see BR-RVL-13 and 1.4. `routes/contact` has one `Reveal` around `display: none` content from `lg` (zero rectangle, so it counts as in view and is settled). |
|
||||
| `data-reveal` consumers | `MediaText.test`, `ShootList.test`, `Reveal.test` use `closest('[data-reveal]')` only | Unchanged: the attribute stays, values `visible` and `hidden`. |
|
||||
| `IntersectionObserver` absent (jsdom, old browsers) | Whole site | Settled and visible (BR-RVL-08); the existing `Reveal.test` case stays. |
|
||||
| Tests with a fake observer (`useReveal.test`) | The hook | Five cases change (BR-DTS-01). No other test asserts hidden content. |
|
||||
|
||||
### 1.4 The `/portfolio` grid and an existing defect
|
||||
|
||||
Measured in Chrome at 412 x 823 on the built page, 2 s after load: the grid wrapper of `/portfolio` (`top` 377, height 4537) was still `data-reveal="hidden"`. Its top part is on screen but 12 % of its height (544 px) never fits between the top of the grid and the 60 px line (386 px visible), so the observer never fires. The final screenshots of the Lighthouse reports (master and unit 1) show the same empty area under the filter row at 3 s. This is the behaviour on master too. The new rule makes the grid settled at load (BR-RVL-03), which fixes it for elements that start in view, and is also why `/portfolio` changes in the measurement (section 6).
|
||||
|
||||
### 1.5 Client navigation
|
||||
|
||||
Option specified (provisional, O1): the same rule as on a first load; no `useHydrated` branch.
|
||||
|
||||
- Why: FR-PR-09's reason is that visible content must never wait for an animation. One rule on both paths has no divergence to test, and the hydration rule (BR-HYD-01) is untouched.
|
||||
- What changes: today a page reached by client navigation fades in its first screen; after this unit its first screen is visible at once and only content below the fold fades on scroll.
|
||||
- Alternative: hide in the first render when `useHydrated()` is already `true` and let the observer reveal what is in view. It keeps the entrance fade, costs a second code path and a second set of tests, and holds back content in view for the length of the fade.
|
||||
|
||||
## 2. Images
|
||||
|
||||
### 2.1 What `DeferredImage` renders
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Props["DeferredImage props: image, near, style props"] --> First["img: no src until loaded, loading lazy, data-deferred"]
|
||||
Props --> Twin["noscript: img with src, alt, width, height, same style props"]
|
||||
First --> Phase{"Page loaded and near the viewport"}
|
||||
Phase -->|"yes"| SetSrc["Effect sets src, photo loads"]
|
||||
Phase -->|"no"| Empty["Stays empty, as in unit 1"]
|
||||
Twin --> NoJs{"Parser scripting enabled"}
|
||||
NoJs -->|"yes"| Text["Content is text: nothing fetched"]
|
||||
NoJs -->|"no"| Shown["Twin is an img: photo loads"]
|
||||
classDef comp fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef markup fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class Props comp;
|
||||
class First,Twin,SetSrc,Empty,Text,Shown markup;
|
||||
class Phase,NoJs choice;
|
||||
```
|
||||
|
||||
Text alternative: DeferredImage renders its deferred image and a noscript twin; without scripting the twin shows the photo and the CSS hides the empty image.
|
||||
|
||||
### 2.2 Facts behind the design
|
||||
|
||||
| Question | Answer | Evidence |
|
||||
|---|---|---|
|
||||
| What does the empty `<img>` look like without JavaScript | A sized box (its CSS size) with Chrome's broken-image icon and the alt text inside; `complete` is `true`, `naturalWidth` 0 | Screenshot of `/soorten-fotoshoots` with JavaScript off and `Reveal` forced visible |
|
||||
| Is the twin double-displayed | Not when the empty image is `display: none` (BR-IMG-02); both have the same class so the twin has the same box | Class equality by construction; V-D2 |
|
||||
| Does the twin download with JavaScript on | No. `noscript` content is text; React 19.3 client does not render `noscript` children (`shouldSetTextContent` in `react-dom-client.production.js`) | Source |
|
||||
| Does the twin add a preload | No. `react-dom-server` skips the image preload when `tagScope & 1` (inside `noscript`) | Source, line 2135 ff. of `react-dom-server.node.production.js` |
|
||||
| Does the twin cause a hydration mismatch | No: children of `noscript` are not compared | Source; V-D1, V-D3 |
|
||||
| Lazy loading without JavaScript | Not honoured by Chrome; all twins load at once | BR-IMG-05 |
|
||||
|
||||
### 2.3 Every image path that depends on JavaScript
|
||||
|
||||
`DeferredImage` (deferred `src`) is the only mechanism that withholds a photo from the HTML, besides the hero's later slides. All image-rendering components in `src` (grep of `DeferredImage` and `<Image`):
|
||||
|
||||
| Path | Photo in the HTML | Without JavaScript |
|
||||
|---|---|---|
|
||||
| `Hero` slide 1 | `src` present, `fetchPriority="high"` | Shown. Slides 2 and up are JavaScript only (BR-IMG-07). |
|
||||
| `IntroGallery` (4, `near` from its own observer) | No `src` | Twin shown. The phone row is a CSS scroll-snap list and keeps working. |
|
||||
| `PortfolioGrid` (`eagerCount={0}`, so all deferred) | No `src` | Twins shown, all load at once. Tiles link to the large photo. |
|
||||
| `InstagramGrid` | No `src` | Twins shown; tiles link to Instagram. |
|
||||
| `PhotoMosaic`, `PhotoDuo` | No `src` | Twins shown. |
|
||||
| `FramedImage` without `priority` (shoot pages, testimonials, `MediaText`) | No `src` | Twin shown. |
|
||||
| `FramedImage` / `MediaText` with `priority` | `src` present | Shown. |
|
||||
| `MediaText` detail photo, `Pricing` decorations | No `src` | Twin shown; the decorations keep `aria-hidden`. |
|
||||
| `TestimonialSlide` in the hidden review copies | No `src` | Twins load, nobody sees them (BR-IMG-09). |
|
||||
| `ContactAside` | `<source srcSet>` in `<picture>`; the `<img>` has a `data:` GIF | Photo shown from `lg`; no change needed. |
|
||||
| `ContactDetails` portrait, `NavigationBar` logos, `Footer` logo | `src` present | Shown. |
|
||||
| `Lightbox` | Not in the HTML | JavaScript only (BR-IMG-08). |
|
||||
| `TestimonialCarousel` slides | Not in the HTML | JavaScript only; the placeholder shows the longest review. |
|
||||
|
||||
## 3. The menu without JavaScript
|
||||
|
||||
### 3.1 What the visitor does
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Closed["Page loaded: panel hidden, open link in the header"] --> Open["Visitor activates open link: address gets #mobile-nav"]
|
||||
Open --> Target["Panel is the target: clip-path inset 0, visibility visible"]
|
||||
Target --> Choose["Visitor picks a link: normal page load"]
|
||||
Target --> Close["Visitor activates close link: address gets #site-header"]
|
||||
Close --> Closed
|
||||
classDef state fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef act fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
class Closed,Target state;
|
||||
class Open,Choose,Close act;
|
||||
```
|
||||
|
||||
Text alternative: the open link makes the panel the URL fragment target and visible, a menu link loads a page, and the close link moves the target to the fixed header so the panel hides again.
|
||||
|
||||
### 3.2 The CSS, rule by rule (selectors; declarations in BR-NAV and BR-NJS)
|
||||
|
||||
| Group | Selector | Why it wins over Emotion |
|
||||
|---|---|---|
|
||||
| Wrapper | `noscript` | Element selector, nothing competes |
|
||||
| Hidden controls | `[data-requires-js]`, `[data-email-pending]` | `!important` (equal weight, Emotion later) |
|
||||
| Empty photo | `img[data-deferred]:not([src])` | `!important` |
|
||||
| Open link | `.ns-menu-open` and its three bars, hidden from `64rem` | Own class, nothing competes |
|
||||
| Close link | `.ns-menu-close` | Own class |
|
||||
| Panel open | `#mobile-nav:target` | Id: weight 1,1,0 against 0,1,0 (verified computed values) |
|
||||
| Group expanded | `#mobile-nav [id^="mobile-group-"]` | Weight 1,1,0 |
|
||||
| Desktop submenu | `[data-submenu]:focus-within > [data-submenu-panel]` | Weight 0,3,0 against 0,1,0, with `transition: none` |
|
||||
| Focus ring | `.ns-menu-open:focus-visible`, `.ns-menu-close:focus-visible` | Own classes |
|
||||
|
||||
Emotion's own rules were seen in the built HTML: they are unlayered `.css-xxxx` single-class rules, written next to the element in the body, so they follow the head CSS in document order. That is why the group rules use ids and why the bare marker rules use `!important`.
|
||||
|
||||
### 3.3 Verified behaviour (Chrome, JavaScript off, 390 x 800 and 1280 x 800, `over-mij` with the CSS and links injected through a request route)
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| Panel while closed | `visibility: hidden`, links not in the Tab order |
|
||||
| After clicking the open link | `location.hash` `#mobile-nav`, `:target` is the panel, `clip-path` `inset(0px)`, `visibility` `visible` |
|
||||
| Scroll jump | Page at `scrollY` 300 stayed at 300 after opening and after closing through `#site-header` |
|
||||
| Tab order after opening | close link, Home, Over mij, Portfolio, Soorten fotoshoots, Newborn, Zwangerschap, Gezin, Loveshoot, Portretten, Contact |
|
||||
| Group | `[id^="mobile-group-"]` computed `grid-template-rows` `1fr`, `visibility` `visible` |
|
||||
| Hamburger | Hidden by the marker rule |
|
||||
| At 1280 px, Tab with 150 ms pauses | Soorten fotoshoots link, then Newborn, Zwangerschap, Gezin ... in the panel; without the pause the first Tab skipped the panel while its `visibility` transition began, hence `transition: none` |
|
||||
|
||||
### 3.4 Placement of the CSS (settled)
|
||||
|
||||
The `<style>` goes in `<head>` inside `<noscript>`, rendered by the root shell (`__root.tsx`) after `HeadContent`. That is the only place the HTML specification allows a `style` inside `noscript`; in `body` it would be invalid although browsers apply it. React 19.3 writes the children of `noscript` into the HTML in place (it does not hoist inside `noscript`). The script step does not touch it (raw-text element, no `<script>`), the CSP allows it (`style-src 'unsafe-inline'`), and with JavaScript the browser never parses it. An external stylesheet link in `noscript` was rejected: one extra blocking request for the visitors who need the fallback, plus asset plumbing, for about 1.5 KB.
|
||||
|
||||
## 4. What a visitor without JavaScript sees
|
||||
|
||||
Common to all pages: skip link; header with the logo and, below `lg`, the menu link instead of the hamburger, from `lg` the five links (the shoot submenu opens on keyboard focus); all text; all photos (twins load at once); footer with the Socials column, the footer menu and the copyright with the build year, but no Contact column; no e-mail address or mailto link anywhere (FR-PR-22); no hidden control that does nothing.
|
||||
|
||||
| Page | Also sees | Missing or different |
|
||||
|---|---|---|
|
||||
| `/` | Hero slide 1 with h1 and call to action; intro gallery (phones swipe the CSS row); about block; price cards with "Boek" links; one review; contact section heading with the coming-soon notice; Instagram tiles | Other hero slides, arrows, pause, progress bar; other reviews (BR-NJS-04); form and mail button; "Boek" does not apply a package (BR-NJS-07) |
|
||||
| `/over-mij` | All text and photos | Nothing |
|
||||
| `/portfolio` | Intro, all photos (links to the large photo), Instagram tiles | Filter buttons, lightbox; `?shoot=` has no effect |
|
||||
| `/soorten-fotoshoots` | Five shoot bands with their links | Nothing |
|
||||
| Five shoot pages | Story blocks, mosaic or duo photos, call to action | Nothing |
|
||||
| `/contact` | Intro, contact card with the social channels, notice, aside photo from `lg` | Form (hidden streamed segment), e-mail address, mail button |
|
||||
| `/privacyverklaring` | Text | Nothing |
|
||||
| 404 page | Text and "Terug naar home" | The two extra buttons under `/soorten-fotoshoots/` (unit 1, BR-404-04) |
|
||||
|
||||
Imperfect and accepted: BR-IMG-05 (everything loads at once), BR-NAV-11 (history), BR-NAV-12 (JavaScript on but not loading), BR-NJS-03 (a carousel with one slide for screen readers), BR-NJS-04, BR-NJS-05 (no way to send a message once the form is enabled), BR-NJS-07, and the missing address.
|
||||
|
||||
## 5. The first photo
|
||||
|
||||
### 5.1 Largest paint per page and screen size
|
||||
|
||||
Chrome 2026-10-31, `PerformanceObserver` `largest-contentful-paint`, last entry after 2.5 s, unthrottled, `Reveal` forced visible to stand for this unit (the current build gives the same elements at 1 s, except `/portfolio` at 412 px, where the grid is hidden today):
|
||||
|
||||
| Page | 412 x 823 | 768 x 1024 | 1350 x 940 | Preload today |
|
||||
|---|---|---|---|---|
|
||||
| `/` | h1 text | h1 text | h1 text | Hero photo (React), logos |
|
||||
| `/over-mij` | `andrea-portret` | same | same | `andrea-portret` (React) |
|
||||
| `/portfolio` | `f41a1916` (first tile) | `f41a1922` | `f41a7883` | None |
|
||||
| `/soorten-fotoshoots` | `newborn` | same | same | `newborn` (React) |
|
||||
| `newborn`, `zwangerschap`, `gezin`, `loveshoot`, `portret` | own photo | same | same | Own photo (React) |
|
||||
| `/contact` | intro text | intro text | `contact` (aside photo) | None for the aside; the 72 px portrait is preloaded at every width |
|
||||
| `/privacyverklaring` | footer logo | h1 | h1 | Logos only |
|
||||
|
||||
The Lighthouse reports name the same elements (mobile: `/` the h1 span; over-mij, soorten and shoot pages their photo; portfolio the intro `p` in the current build and the first grid photo in the "Reveal visible" run; contact the intro `p`; desktop contact the aside photo, desktop portfolio a grid photo).
|
||||
|
||||
### 5.2 Decision flow
|
||||
|
||||
See flowchart 1.3 in the business rules. Result: nothing to add for seven of the eleven pages (React already preloads), one explicit link for `/contact` from `lg`, nothing for `/portfolio` (deferred by decision, different tile per width), nothing for `/privacyverklaring`. Two preloads are avoided by making their images lazy (the light logo off `/`, the contact portrait), because they are `display: none` where they are not used.
|
||||
|
||||
## 6. Largest paint: what the reports show
|
||||
|
||||
### 6.1 Two numbers per URL
|
||||
|
||||
Lighthouse here is in simulate mode (mobile: 150 ms RTT, 1.6 Mbps, CPU x4). The page is loaded once without throttling, and the simulator computes the LCP from that trace's dependency graph. Each report therefore holds the real, unthrottled LCP (`observedLargestContentfulPaint`) and the simulated one.
|
||||
|
||||
| Mobile URL | Master LCP | After (A) | Reveal visible (B) | Real LCP A / B, ms | LCP element in A / B |
|
||||
|---|---|---|---|---|---|
|
||||
| `/` | 4293 | 4280 | 4281 | 109 / 111 | h1 text span, both |
|
||||
| `/over-mij` | 3535 | 3608 | 3306 | 977 / 51 | portrait photo, both |
|
||||
| `/portfolio` | 2926 | 3007 | 3607 | 55 / 197 | intro text in A, first grid photo in B |
|
||||
| `/soorten-fotoshoots` | 3750 | 3683 | 3383 | 990 / 56 | newborn photo |
|
||||
| newborn | 3525 | 3610 | 3457 | 1047 / 62 | own photo |
|
||||
| zwangerschap | 3676 | 3834 | 3682 | 1034 / 65 | own photo |
|
||||
| gezin | 3678 | 3908 | 3758 | 1027 / 65 | own photo |
|
||||
| loveshoot | 3768 | 4133 | 3907 | 1016 / 65 | own photo |
|
||||
| portret | 3673 | 3759 | 3682 | 1007 / 63 | own photo |
|
||||
| `/contact` | 3345 | 3007 | 3006 | 50 / 64 | intro text |
|
||||
|
||||
### 6.2 Shoot pages are worse than master (up to +365 ms on loveshoot)
|
||||
|
||||
Two causes, one of which this unit removes.
|
||||
|
||||
1. **The photo waits for hydration.** In A the photo is in the HTML but inside a hidden `Reveal`; Chrome ignores `opacity: 0` elements, so the photo only becomes the largest paint after hydration, the observer and the 0.8 s fade: real LCP 1007 to 1047 ms against 62 to 65 ms when `Reveal` is visible (B). The simulator, which waits for that late paint, includes everything requested before it. Master had the same wait (the SPA rendered the photo hidden too: real LCP 1008 to 1046 ms), so this cause is not new; A did not remove it.
|
||||
2. **The photo is now requested first and competes for the link.** In A the photo is requested at about 11 ms with the 215 KB of scripts; in master it was requested after React rendered, behind the scripts. The simulator shares the 1.6 Mbps link between the concurrent requests, so the hydration that the paint waits for finishes later by about the photo's transfer time. Evidence: the regression against master grows with the photo's size: newborn 74 KB +85 ms, portret 97 KB +86, zwangerschap 104 KB +158, gezin 117 KB +230, loveshoot 153 KB +365. The scripts grew by 7 KB (208 to 215 KB), worth about 40 ms, not 365.
|
||||
|
||||
B shows what this unit achieves: it removes cause 1 (77 to 226 ms better than A, and 65 ms real LCP), but cause 2 stays: zwangerschap +6, portret +9, gezin +80, loveshoot +139 ms against master. newborn is 72 ms better than master.
|
||||
|
||||
### 6.3 `/portfolio` 3007 to 3607 ms with `Reveal` visible
|
||||
|
||||
In A the grid is hidden (BR-RVL-13 defect, section 1.4), so the largest paint is the intro paragraph at 55 ms, and the photos requested later (two requests at 194 ms, `DeferredImage` after the `load` event) are never candidates. In B the grid is visible, the first photo is the largest paint, and its real LCP is 197 ms. The simulator now includes everything requested up to 197 ms, among it those two photos (54 KB and 144 KB): +600 ms for +198 KB (3.0 ms per KB). The element changed from text to a photo; nothing got slower for the visitor, but the lab number did. This unit's design makes the grid visible (BR-RVL-03), so `/portfolio` is expected near B (score 0.90 against 0.94 in A). See O2.
|
||||
|
||||
### 6.4 `/` stays at 4280 ms in both
|
||||
|
||||
The largest paint on `/` is the h1 text span at the first paint (real 109 and 111 ms), and all 14 `Reveal`s of the page are below the fold at 412 x 823 (the first top is at 919 px), so `Reveal` plays no part. The simulated number is the cost of what was requested before 109 ms: the 19 scripts (216 KB), both logos (48 KB) and the hero photo (224 KB, requested at 14 ms with `fetchPriority="high"`). Compare `/contact`: same scripts, 54 KB of images, 3007 ms. The difference, 1273 ms, is what the hero's 224 KB costs at the simulated 184 KB/s (5.4 ms per KB): 1216 ms. The same slope appears in B on the shoot pages: from newborn (122 KB of images before the cut) to loveshoot (201 KB), +450 ms for +79 KB is 5.7 ms per KB. Master gave 4293 ms for the same reason (the same hero photo).
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Real["Real trace: LCP at 50 to 200 ms"] --> Cut["Simulator: take every request started before that moment"]
|
||||
Cut --> Bytes["Scripts 200 to 220 KB, logos 48 KB, first photo 75 to 225 KB"]
|
||||
Bytes --> Link["Share a 1.6 Mbps link, about 5.4 ms per KB"]
|
||||
Link --> Sim["Simulated LCP 3.0 to 4.3 s"]
|
||||
Hide["Reveal hides the photo"] --> Late["Real LCP moves to about 1.0 s"]
|
||||
Late --> Cut
|
||||
classDef real fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef model fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef cause fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
class Real,Late real;
|
||||
class Cut,Bytes,Link,Sim model;
|
||||
class Hide cause;
|
||||
```
|
||||
|
||||
Text alternative: the simulated LCP follows the bytes requested before the real LCP moment, and a hidden Reveal pushes that moment from about 60 ms to about 1 s.
|
||||
|
||||
### 6.5 What was not determined
|
||||
|
||||
- The reports contain no trace, so the simulator's inner workings (which requests it includes, how it shares the link) are inferred from the correlation above, not read from a trace. The fit is close (hero: 1216 predicted against 1273 observed; slope 5.4 against 5.7 ms per KB), but it is a fit. BR-DMS-02 keeps a trace to confirm it.
|
||||
- Why Chrome never reports the hero photo as the largest paint on `/` (one entry only, the text). A viewport-filling image being treated as background is likely; not confirmed (V-D10).
|
||||
- Whether the residual increase on four shoot pages (cause 2) is the whole of it: it fits the photo sizes, no other candidate was found.
|
||||
|
||||
What this unit's design does about it: removes cause 1 (fade-in gate), fixes the empty mobile portfolio, removes 25 KB of never-shown logo on ten pages (BR-PRE-05, an estimated 140 ms), and leaves the bytes of photos, scripts and the 500 x 500 logos to the responsive-photos feature, unit 3 and the owner's per-page decision (BR-DMS-04).
|
||||
|
||||
## 7. Testable Properties (PBT-01)
|
||||
|
||||
Properties extend the numbering of unit 1 (P1 to P17). fast-check runs in Vitest with the existing seed handling. `src/lib/**` and `src/seo.ts` have 100 % coverage thresholds, so each property file also carries example tests.
|
||||
|
||||
| Id | Function | Category | Property |
|
||||
|---|---|---|---|
|
||||
| P18 | `startsHidden(top, viewportHeight)` | Invariant | For any finite numbers: an element whose top is below the viewport height is hidden; one whose top is smaller is never hidden (BR-RVL-03). Equal gives hidden. |
|
||||
| P19 | `startsHidden` | Metamorphic (monotonic) | If an element with top `t` is hidden then every element with top `t' >= t` (same viewport) is hidden; shifting top and viewport height by the same amount does not change the result. |
|
||||
| P20 | `nextRevealPhase(phase, event)` | Invariant (state machine) | For any phase and any sequence of events the phase never returns from `revealed` to `hidden` or `settled`, and never goes from `settled` to `revealed` (BR-RVL-09). |
|
||||
| P21 | `nextRevealPhase` | Idempotence | Applying the same event twice gives the same result as once (StrictMode runs effects twice). |
|
||||
| P22 | `preloadImage(image, options)` | Invariant | For any image and options, `href` equals `image.src`, `rel` is `preload`, `as` is `image`, `fetchPriority` is `high`, `media` is present exactly when given and equals it, and no other key exists. |
|
||||
|
||||
The check that the CSS constant has no `</`, `url(` or `@import` and balanced braces (BR-NAV-02) is an example test on one constant, not a property.
|
||||
|
||||
Components with no properties:
|
||||
|
||||
| Component | Result |
|
||||
|---|---|
|
||||
| `Reveal`, `useReveal` | No PBT properties identified beyond P18 to P21: the hook reads the DOM and renders; the decisions are in `revealPhase`. Example tests with a stubbed rectangle and the fake observer. |
|
||||
| `DeferredImage` | No PBT properties identified: fixed markup from one image; example tests with `renderToString` and `hydrate()`. |
|
||||
| `NoScriptStyles`, `NoScriptNav` | No PBT properties identified: constant markup; example tests and the browser tests of BR-DTS-03. |
|
||||
| `NavigationBar`, `MobileNav`, `MobileNavGroup`, `NavSubmenu`, `Hero*`, `FilterBar`, `Footer`, `FooterColumn`, `Testimonials` | No PBT properties identified: attribute additions on components with small fixed inputs. |
|
||||
| Route `head()` of `/contact` | No PBT properties identified: it calls `preloadImage` (P22) with fixed content. |
|
||||
|
||||
## 8. Requirement coverage
|
||||
|
||||
| Requirement | Where |
|
||||
|---|---|
|
||||
| FR-PR-09 | BR-RVL-01 to 06, 09 to 14; section 1 |
|
||||
| FR-PR-10 | BR-RVL-07 |
|
||||
| FR-PR-11 | BR-IMG-01 to 10; BR-RVL-01; section 2 |
|
||||
| FR-PR-12 | BR-NAV-01 to 12; section 3 |
|
||||
| FR-PR-13 | BR-NJS-01 to 11; BR-IMG-07, 08; section 4 |
|
||||
| FR-PR-21 | BR-PRE-01 to 09; section 5 |
|
||||
| FR-PR-22 | BR-NJS-02 (placeholders hidden, address stays absent) |
|
||||
| NFR-PR-P-01, P-03 | BR-DMS-01 to 04; section 6 |
|
||||
| NFR-PR-Q-01, Q-03 | BR-DTS-01 to 04 |
|
||||
| NFR-PR-SEC-01 | BR-NAV-02 |
|
||||
|
||||
## 9. Security Baseline and PBT compliance (unit 2)
|
||||
|
||||
| Rule | Status | Note |
|
||||
|---|---|---|
|
||||
| SECURITY-04 | Compliant | CSP unchanged: the new CSS needs `style-src 'unsafe-inline'`, already present and documented; no new script, no inline handler |
|
||||
| SECURITY-13 | Compliant | No external resource added; `preloadImage` links are same-origin hashed assets |
|
||||
| SECURITY-09, 10, 11, 15 | Compliant / unchanged | No server output, dependency, endpoint or error path changes |
|
||||
| PBT-01 | Compliant | Section 7 |
|
||||
+211
@@ -0,0 +1,211 @@
|
||||
# Business Rules - Unit 2: Display fallbacks
|
||||
|
||||
Rule ids are scoped to this feature and this unit. "Source" points at a requirement (FR/NFR), a design decision (D1 to D13 in [application-design.md](../../../inception/application-design/application-design.md)) or a unit 1 rule ([business-rules.md](../../start-migration/functional-design/business-rules.md)). Flows and evidence: [business-logic-model.md](business-logic-model.md). Components: [frontend-components.md](frontend-components.md). Data: [domain-entities.md](domain-entities.md).
|
||||
|
||||
Groups: BR-RVL reveal, BR-IMG images, BR-NAV menu without JavaScript, BR-NJS other fallbacks, BR-PRE first-photo preload, BR-DMS measurement, BR-DTS tests.
|
||||
|
||||
**Provisional** marks a choice that belongs to the owner. The recommendation is written down; the alternatives are in section 5.
|
||||
|
||||
All statements marked "verified" were checked on 2026-10-31 against `web/src`, the built `web/dist/client` and a real Chrome (Playwright, local preview server) without changing any code.
|
||||
|
||||
## 1. Decision flowcharts
|
||||
|
||||
### 1.1 What `Reveal` does after hydration
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start["Reveal mounted in the browser"] --> Support{"IntersectionObserver available and no reduced motion"}
|
||||
Support -->|"no"| Settled["Settled: visible, nothing to animate"]
|
||||
Support -->|"yes"| Measure["Layout effect: read top edge of the element"]
|
||||
Measure --> Below{"Top edge at or below the viewport bottom"}
|
||||
Below -->|"no"| Settled
|
||||
Below -->|"yes"| Hidden["Hidden: opacity 0, no transition"]
|
||||
Hidden --> Seen{"12 percent visible above the 60 px line"}
|
||||
Seen -->|"yes, once"| Revealed["Revealed: fades in with the delay"]
|
||||
classDef state fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class Settled,Hidden,Revealed state;
|
||||
class Start,Measure step;
|
||||
class Support,Below,Seen choice;
|
||||
```
|
||||
|
||||
Text alternative: after hydration an element that is wholly below the viewport is hidden without a transition and fades in once on scroll; every other element stays visible.
|
||||
|
||||
### 1.2 Which markup a deferred photo gets
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Img["DeferredImage renders"] --> Pair["Image without src plus a noscript twin with src"]
|
||||
Pair --> Js{"JavaScript on"}
|
||||
Js -->|"yes"| Today["Twin is plain text to the parser: no request, no preload"]
|
||||
Today --> Load["After load and in view the effect sets src"]
|
||||
Js -->|"no"| Hide["CSS hides the empty image, the twin shows the photo"]
|
||||
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef result fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class Img,Pair step;
|
||||
class Js choice;
|
||||
class Today,Load,Hide result;
|
||||
```
|
||||
|
||||
Text alternative: a deferred photo is rendered as an empty image plus a noscript twin; with JavaScript the twin is ignored, without it the CSS hides the empty image and shows the twin.
|
||||
|
||||
### 1.3 How a page gets its first-photo preload
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Photo["First photo of a page"] --> Plain{"A plain img with src and high priority"}
|
||||
Plain -->|"yes"| React["React hoists a preload link into the head"]
|
||||
Plain -->|"no, inside picture"| Explicit["Route head adds preloadImage with media"]
|
||||
Photo --> Hidden{"Hidden at some breakpoint"}
|
||||
Hidden -->|"yes"| Lazy["Image is lazy: no fetch, no preload there"]
|
||||
Photo --> Deferred{"Deliberately deferred"}
|
||||
Deferred -->|"yes"| None["No preload, see BR-PRE-08"]
|
||||
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef result fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class Photo step;
|
||||
class Plain,Hidden,Deferred choice;
|
||||
class React,Explicit,Lazy,None result;
|
||||
```
|
||||
|
||||
Text alternative: a plain high-priority photo is preloaded by React itself, a photo in a picture element needs an explicit media-bound link, hidden photos are lazy and deferred photos get no preload.
|
||||
|
||||
## 2. Rules
|
||||
|
||||
### BR-RVL: Reveal and `useReveal`
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-RVL-01 | The first render of `Reveal`, on the server and in the browser, is visible: `data-reveal="visible"`, `opacity` 1, no transform, no transition. The prerendered HTML therefore shows all `Reveal` content, with and without JavaScript. | FR-PR-09, FR-PR-11; D7; BR-HYD-01 |
|
||||
| BR-RVL-02 | After hydration each `Reveal` decides in a `useLayoutEffect` whether to hide itself. The effect reads `element.getBoundingClientRect().top` and `window.innerHeight` and hides the element only when `top >= innerHeight`. A layout effect runs after the DOM commit and before the next paint, so hiding a below-the-fold element is never painted as a flash. All `Reveal`s of a commit read before any of them writes (state is set after the effects), so the reads cost one layout. React 19 does not warn for `useLayoutEffect` during prerendering (no such message in `react-dom-server.*.development.js`). | FR-PR-09; D6, D7 |
|
||||
| BR-RVL-03 | "In view at load" means: not wholly below the bottom edge of the viewport. This includes an element that is partly visible, one taller than the screen, and one above the viewport (scroll restoration, `#anchor` jump). The 60 px trigger margin is not part of this test: an element whose top sits in that band was painted from the HTML, and hiding it would make it disappear. | FR-PR-09 |
|
||||
| BR-RVL-04 | The hidden state is `opacity` 0 and `translateY(24px)` with `transition: none`. The change from settled to hidden therefore never animates. | FR-PR-09 |
|
||||
| BR-RVL-05 | The reveal trigger is unchanged: one `IntersectionObserver`, `threshold` 0.12, `rootMargin` `0px 0px -60px 0px`, disconnected after the first intersection. When it fires, the element becomes revealed: `opacity` 1, no transform, `transitionProperty` `opacity, transform`, duration token `reveal` (0.8 s), `smooth`, `transitionDelay` `${delay}s`. | FR-PR-09 ("as it does now") |
|
||||
| BR-RVL-06 | `delay` only matters for an element that was hidden and is revealed. Elements in view at load show at once, so a staggered row (`Pricing` cards, `PhotoMosaic` tiles) that is in view at load appears together. Rows revealed on scroll keep their stagger. | FR-PR-09 |
|
||||
| BR-RVL-07 | With `prefers-reduced-motion: reduce` nothing is hidden and no observer is created. The layout effect reads `window.matchMedia('(prefers-reduced-motion: reduce)').matches` itself: Chakra's `useMediaQuery` still holds its server-safe `false` while the layout effect runs (BR-HYD-07), and a late `true` would first hide and then animate. `useReveal` no longer calls `useMediaQuery`. In addition `Reveal` carries `_motionReduce` `{ opacity: 1, transform: 'none', transition: 'none' }`, so a preference that changes while elements are hidden shows them at once. | FR-PR-10 |
|
||||
| BR-RVL-08 | Without `IntersectionObserver` (old browsers, jsdom) the element stays settled and visible. | FR-PR-09; BR-HYD-05 |
|
||||
| BR-RVL-09 | The transitions are one-way: settled stays settled, hidden becomes revealed, revealed stays revealed. An element never goes back to hidden, also not when it scrolls out of view. The observer is disconnected on unmount. | FR-PR-09 |
|
||||
| BR-RVL-10 | **Provisional.** A `Reveal` that mounts after hydration (client navigation, the lazy testimonial and contact content) follows the same rules; there is no `useHydrated` branch. Content in view when the new page mounts appears at once, content below the viewport fades in on scroll. Reason: FR-PR-09 asks that content in view never waits for an animation, and the same rule on both paths is simpler to test and cannot diverge from the first load. Consequence: the entrance fade of the first screen on client navigation, which exists today, is dropped. Edge: the router scrolls to the top after the new page mounts, so on a navigation from a scrolled page, elements that end up below the fold after that scroll may already be settled and not fade. | FR-PR-09 |
|
||||
| BR-RVL-11 | `Reveal` keeps its props (`BoxProps` plus `delay`) and all 21 call sites stay as they are (list in [frontend-components.md § 4](frontend-components.md)). `useReveal<T>()` returns `{ ref, visible, animated }`: `visible` is `false` only while hidden; `animated` is `true` only once revealed. `data-reveal` keeps the values `visible` and `hidden` that tests select on. | FR-PR-09 |
|
||||
| BR-RVL-12 | The decision is pure logic in `src/lib/revealPhase.ts`: `startsHidden(top, viewportHeight)` and `nextRevealPhase(phase, event)`. The hook only reads the DOM and calls them. `src/lib` has a 100 % coverage threshold. | NFR-PR-Q-01, Q-02 |
|
||||
| BR-RVL-13 | The existing trigger cannot reveal an element taller than `(innerHeight - 60) / 0.12` (6358 px at 823 px, 4833 px at 640 px, 4233 px at 568 px): the 12 % threshold is then never reached. Observed 2026-10-31: on `/portfolio` at 412 x 823 the grid wrapper (4537 px high, top at 377 px) stayed `hidden` for good until scrolled, although it was in view; the grid showed as an empty area under the filters. BR-RVL-03 removes this for elements that start in view. For an element that starts below the fold the limit stays. Code generation checks the tallest `Reveal` on every page at 320, 360 and 412 px wide (V-D6). | FR-PR-09 |
|
||||
| BR-RVL-14 | Anchors and scroll restoration are decided at hydration time, as today. `/?pakket=...#contact` and `/#prijzen` jump before hydration (the element exists in the HTML), so the target is in view and settled. Smooth scrolling to `#contact` after hydration passes hidden sections; they fade as they intersect, as now. A scroll position restored after hydration reveals content by scrolling, as now. | FR-PR-07, FR-PR-09 |
|
||||
|
||||
### BR-IMG: Images and `DeferredImage`
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-IMG-01 | `DeferredImage` renders two siblings: the deferred `<img>` exactly as today, and `<noscript>` with a twin `<img>`. The twin has `src` (`image.src`), `alt`, `width` and `height` from the image, `decoding="async"`, no `loading` attribute, and the same style props as the first image, so it has the same class and the same box. It leaves out `id`, `data-testid` and `ref`. The props of `DeferredImage` do not change. | FR-PR-11; D8 |
|
||||
| BR-IMG-02 | The deferred `<img>` carries `data-deferred`. The no-JavaScript CSS hides `img[data-deferred]:not([src])` with `display: none !important`. Without it Chrome draws the empty image as a sized box with a broken-image icon and the alt text inside it (verified on `/soorten-fotoshoots` without JavaScript: `complete` is `true`, `naturalWidth` 0, the box keeps its size). Hidden with `display: none`, the empty image is not announced either, so a screen reader without JavaScript meets the photo once, in the twin. | FR-PR-11 |
|
||||
| BR-IMG-03 | With JavaScript nothing changes. The HTML parser reads `noscript` content as text when scripting is on, so the twin is not fetched. React renders no `noscript` children in the browser (`shouldSetTextContent` is true for `noscript` in `react-dom-client`) and ignores them when hydrating, so there is no mismatch. Prerendering skips the preload for an `img` inside `noscript` (`tagScope & 1` in `react-dom-server`), so no `<link rel="preload">` is added. Code generation proves "no extra request" with a request log (V-D2). | FR-PR-11; D6, D8 |
|
||||
| BR-IMG-04 | The no-JavaScript CSS gives `noscript` `display: contents`, so the wrapper element takes no part in flex, grid or positioning of the twin (absolute photos in `PhotoMosaic`, `MediaText` and the `Pricing` decorations keep their containing block either way). | FR-PR-11 |
|
||||
| BR-IMG-05 | Without JavaScript browsers do not honour `loading="lazy"` (Chrome disables it when scripting is off), so every twin on a page loads at once; on `/portfolio` that is all photos of the grid. The twin carries no `loading` attribute for that reason. Accepted: the visitors are rare and the alternative (load nothing) leaves empty frames. | FR-PR-11 |
|
||||
| BR-IMG-06 | Photos that are already in the HTML with a `src` need nothing: `Image` with `priority` in `FramedImage`, the hero's first slide, `ContactAside` (`<source srcSet>` in `<picture>` works without JavaScript), the `ContactDetails` portrait, the logos. Inventory of every image path: [business-logic-model.md § 2.3](business-logic-model.md). | FR-PR-11 |
|
||||
| BR-IMG-07 | Hero slides other than the first need JavaScript to appear and stay out of the HTML (the first render loads only the active slide). Without JavaScript the visitor sees slide 1, its text and the call to action. | FR-PR-13 |
|
||||
| BR-IMG-08 | The `Lightbox` needs JavaScript. Every tile of `PortfolioGrid` is a plain link to the large photo (`href` is `item.full.src`), so without JavaScript a tile opens the photo file itself. | FR-PR-13 |
|
||||
| BR-IMG-09 | The testimonial placeholder's visually hidden review copies contain deferred photos too, so their twins also load without JavaScript although nobody sees them. Accepted (review photos only); see BR-NJS-05. | FR-PR-11 |
|
||||
| BR-IMG-10 | The twin never changes what a page looks like with JavaScript, so hydration needs no new rule: the first render still has no `src` on either side (BR-HYD-01 and unit 1 section 3). | FR-PR-05 |
|
||||
|
||||
### BR-NAV: The menu without JavaScript
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-NAV-01 | The CSS for all no-JavaScript fallbacks (menu, deferred photos, hidden controls) lives in one `<noscript><style>` in the `<head>`, rendered by the root shell after `HeadContent`. That position is valid HTML: `style` is only allowed in `noscript` inside `head`, not in `body`. The two menu links are `<noscript>` elements in the body. This replaces the application design's single `NoScriptNav` that held the CSS as well. | FR-PR-12; D9 |
|
||||
| BR-NAV-02 | The CSS is allowed by `style-src 'self' 'unsafe-inline'` (unchanged, `securityHeaders.ts`). The script step leaves it alone: `inlineScripts.ts` treats `noscript` as a raw-text element and only looks for `<script>`; the CSS contains none. The CSS has no `</`, no `url(` and no `@import` (a test checks this), so it cannot end the `noscript` early or fetch anything. It holds no e-mail address, so the address scan stays clean. | NFR-PR-SEC-01; BR-SCR-02, BR-MAIL-10 |
|
||||
| BR-NAV-03 | Open link: `<a class="ns-menu-open" href="#mobile-nav" aria-label="Menu openen">` with three bars, inside the header's right-hand `div` before the hamburger. It is 44 x 44 px like the button. It is hidden from `64rem` up (`lg`), where the header shows the links. `aria-label` reuses the existing string. | FR-PR-12 |
|
||||
| BR-NAV-04 | The hamburger `button` gets `data-requires-js` and is hidden without JavaScript (BR-NJS-01). | FR-PR-12, FR-PR-13 |
|
||||
| BR-NAV-05 | `#mobile-nav:target { clip-path: inset(0); visibility: visible }`. No `!important`: an id selector outranks the single-class selectors Emotion generates, also those inside media queries (verified: with the rule the computed values were `inset(0px)` and `visible`). `display` is not touched, so the panel stays `none` from `lg` up even when the address ends in `#mobile-nav`. The existing `clip-path` and `visibility` transition animates the opening, and `_motionReduce` on the panel still switches it off. | FR-PR-12 |
|
||||
| BR-NAV-06 | The shoot submenu is expanded without JavaScript: `#mobile-nav [id^="mobile-group-"] { grid-template-rows: 1fr; visibility: visible; transition: none }` always, not only on `:target` (selector weight 1,1,0 beats Emotion's single class). The chevron button of the group carries `data-requires-js` and is hidden. | FR-PR-12 |
|
||||
| BR-NAV-07 | Close link: `<a class="ns-menu-close" href="#site-header">` with the existing text "Menu sluiten", as the first child of the panel's content, so it is the first Tab stop after opening. `#site-header` is the fixed `header`, which gets an `id` for this. A fragment navigation to a fixed element does not scroll: verified in Chrome with the page at `scrollY` 300, opening via `#mobile-nav` and closing via `#site-header` both left it at 300 (Firefox and Safari: V-D4). Rejected: `href="#"` (scrolls to the top of the page) and `href="#main"` (scrolls to the content). | FR-PR-12 |
|
||||
| BR-NAV-08 | Focus order without JavaScript: skip link, logo, open link; closed, the panel is `visibility: hidden`, so none of its links is focusable. After activating the open link the browser's sequential focus starting point is `#mobile-nav`, so the next Tab goes to the close link, then Home, Over mij, Portfolio, Soorten fotoshoots, Newborn, Zwangerschap, Gezin, Loveshoot, Portretten, Contact (verified, in that order). Both links get a visible focus ring (`:focus-visible` outline in the CSS). | FR-PR-12; WCAG 2.4.3, 2.4.7 |
|
||||
| BR-NAV-09 | Desktop (from `lg`): all top-level links are in the header and work. The panel with the five shoot links is `visibility: hidden`, so by keyboard those links are unreachable, and the chevron button does nothing. **Provisional:** `[data-submenu]:focus-within > [data-submenu-panel] { visibility: visible; opacity: 1; transform: none; pointer-events: auto; transition: none }` opens it while focus is on the "Soorten fotoshoots" link or inside the panel, and the chevron is hidden (`data-requires-js`). `transition: none` is needed: the panel's `visibility` transition starts hidden, and a Tab pressed in the same frame skipped the panel (observed); with a 150 ms pause, Tab reached Newborn to Gezin in order. Mouse users click "Soorten fotoshoots", which opens the overview where each shoot has its "Lees meer" link; hover opening is not offered (the 0.75rem gap between link and panel would close it). | FR-PR-12; BR-NAV-21, 27 (earlier feature: no hover opening) |
|
||||
| BR-NAV-10 | The JavaScript menu stays as it is. The additions are `id="site-header"`, `data-requires-js` on the hamburger and the two chevron buttons, `data-submenu` on the submenu wrapper and `data-submenu-panel` on its panel, and the close link. With JavaScript these attributes do nothing (`noscript` content is not rendered). `useReducer`, ARIA and focus handling are not touched. | FR-PR-12; D9 |
|
||||
| BR-NAV-11 | Opening and closing add history entries (`#mobile-nav`, `#site-header`). Back from a page reached through the menu can return to the home page with the menu open. Accepted. | FR-PR-12 |
|
||||
| BR-NAV-12 | A visitor with JavaScript switched on whose script fails to load gets no `noscript` content, so the hamburger stays inert. That case is not covered by FR-PR-12 ("without JavaScript") and not by this design; the desktop links still work. | FR-PR-12 |
|
||||
|
||||
### BR-NJS: Other fallbacks without JavaScript
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-NJS-01 | One marker, `data-requires-js`, means "no function without JavaScript". The no-JavaScript CSS hides it: `[data-requires-js] { display: none !important }`. `!important` is needed because style props set `display` on several of these elements, and Emotion's rules are unlayered single-class rules that come later in the document than the `head` CSS. Marked: the hamburger button, the two chevron buttons, `HeroArrows` buttons, `HeroPauseButton`, the hero progress bar, the `FilterBar` root, the testimonial controls spacer, the footer Contact column. | FR-PR-13 |
|
||||
| BR-NJS-02 | `[data-email-pending] { display: none !important }`: the e-mail placeholders (footer, contact card, gate sentence and gate button) stay in the HTML for layout during hydration, and are removed from layout without JavaScript, where the address never comes (FR-PR-22). The footer Contact column gets `data-requires-js` as well, so its title "Contact" does not stand alone (BR-MAIL-09). `FooterColumn` takes an optional prop to put the marker on its root. | FR-PR-22; BR-MAIL-09 |
|
||||
| BR-NJS-03 | Hero: slide 1 with its photo, h1, call to action and social links. The arrows, the pause button and the progress bar are hidden. The progress bar would otherwise run once and stop. The section keeps `aria-roledescription="carousel"`; a screen reader without JavaScript hears a carousel with one slide. Accepted. | FR-PR-13 |
|
||||
| BR-NJS-04 | Testimonials: the placeholder shows the longest review (not necessarily the first) and keeps the other copies visually hidden, `aria-hidden` and `inert`, as unit 1 decided (BR-LZY-02) and as the browser test V9 asserts. The empty 48 px spacer for the carousel controls is hidden. **Provisional:** a visitor without JavaScript reads one review, not all. | FR-PR-13; BR-LZY-02 |
|
||||
| BR-NJS-05 | Contact form: on `/contact` the form is a hidden streamed segment (`<div hidden id="S:0">`) that stays hidden without JavaScript, and the gate shows its notice over a blank, blurred area. On `/` the notice sits over the placeholder box. The notice text "Het contactformulier komt binnenkort." is readable; the address and the mail button do not exist without JavaScript (FR-PR-22). The form is disabled today (`contactForm.enabled` is `false`), so nothing usable is lost. When it is enabled, a visitor without JavaScript gets an empty area and no way to send a message; that must be designed then. | FR-PR-13, FR-PR-22; BR-LZY-01 |
|
||||
| BR-NJS-06 | Portfolio: the filter buttons are hidden and all photos show, also for `/portfolio?shoot=...` (the search only applies after hydration, BR-HYD-10). Tiles are links to the large photos. | FR-PR-13 |
|
||||
| BR-NJS-07 | The "Boek" links of the price cards go to `/?pakket=...`. Without JavaScript the page loads at the top and the package is not applied. Accepted. | FR-PR-06, FR-PR-13 |
|
||||
| BR-NJS-08 | `BackToTop` is already `inert` and `visibility: hidden` until a scroll listener shows it, so it needs no marker. The 404 page already shows one button, "Terug naar home", a link. | FR-PR-13 |
|
||||
| BR-NJS-09 | Specificity policy for the CSS: id selectors and attribute selectors with a pseudo-class beat Emotion's single-class rules by weight; a bare attribute selector has equal weight and loses to the later Emotion rule, so it needs `!important` (BR-NJS-01) or an id. | FR-PR-12, FR-PR-13 |
|
||||
| BR-NJS-10 | No Dutch copy is written or changed. The only visible texts the unit uses are existing strings: "Menu openen", "Menu sluiten". | FR-PR-12 |
|
||||
| BR-NJS-11 | What a visitor without JavaScript sees, per page, is in [business-logic-model.md § 4](business-logic-model.md). Remaining imperfections: BR-IMG-05, BR-NAV-11, BR-NAV-12, BR-NJS-03, BR-NJS-04, BR-NJS-05, BR-NJS-07, and the missing e-mail address (FR-PR-22). | FR-PR-11, FR-PR-13 |
|
||||
|
||||
### BR-PRE: First-photo preload
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-PRE-01 | Fact, verified in `dist/client`: React 19.3 already writes `<link rel="preload" as="image">` into the `<head>` for every `<img>` with a string `src` that is not `loading="lazy"`, not `fetchPriority="low"`, not a `data:` URL, and not inside `<picture>` or `<noscript>`. Photos with `fetchPriority="high"` get `fetchPriority="high"` on the link. So `/` (hero 8), `/over-mij`, `/soorten-fotoshoots` and the five shoot pages already preload their first photo, with the hashed URL, from the same `src` the `<img>` uses (so the browser can never fetch it twice). The declaration of "this is the first photo" is `priority` on `FramedImage` / `fetchPriority="high"` on the `<img>`, which unit 1 left in place. | FR-PR-21; D8 |
|
||||
| BR-PRE-02 | Explicit links are only for images React cannot hoist. That is `/contact` from `lg`: the photo is a `<source media="(min-width: 64em)" srcSet>` in a `<picture>` and the `<img>` has a `data:` placeholder, so nothing is preloaded today and it is the largest paint at 1350 x 940. The contact route's `head()` adds `preloadImage(image, { media: ASIDE_MEDIA })`: `rel="preload"`, `as="image"`, `href` the hashed URL, `fetchPriority="high"`, `media="(min-width: 64em)"`. Below `lg` the media query keeps it from downloading. | FR-PR-21 |
|
||||
| BR-PRE-03 | `preloadImage(image: ContentImage, options?: { media?: string }): HeadLink` is added to `seo.ts` (component-methods.md named it `preloadImage(src)`). It returns a plain object with `rel`, `as`, `href` (= `image.src`), `fetchPriority` and, only when given, `media`. `seo.ts` has a 100 % coverage threshold: examples and property P22 cover it. `pageHead` is not changed: passing every page's first photo to it would write the same preload twice (BR-PRE-04). The application design said pages pass their first photo to `pageHead`; the investigation shows React already does it. | FR-PR-21; D8 |
|
||||
| BR-PRE-04 | A photo is declared once. A build test over all 12 HTML files asserts: every `preload as="image"` `href` occurs once; every page that has a `priority` photo has its preload; `/contact` has the `media` link and no other link for that file. This also catches a React upgrade that changes the hoisting. | FR-PR-21; NFR-PR-Q-01 |
|
||||
| BR-PRE-05 | Nothing is preloaded that is not shown. Measured on `dist/client`: every page preloads both logos, `/contact` preloads the 72 px portrait (5 KB) that is `display: none` from `lg`. Fixes, both by `loading="lazy"` (a lazy image is neither fetched while `display: none` nor hoisted by React): the contact page's narrow portrait; the light logo on every page except `/` (on those pages the header is never transparent, so the light logo is never shown). `NavigationBar` knows `isHome` from the pathname in its first render, which is the same on the server and in the browser (the prerendered 404 has `/404`, never `/`). On `/` both logos stay eager, because both are shown in some state (dark below `lg` and after scrolling 150 px, light over the hero from `lg`). The light logo is 25 KB, about 140 ms of simulated LCP at the Lighthouse throttle on ten pages (estimate from the 5.4 ms per KB slope in the business logic model, to be measured). Verified in Chrome on the built `/over-mij`: with `loading="lazy"` on the light logo and its preload link removed, only the dark logo is requested. **Provisional.** | FR-PR-21; NFR-PR-P-01 |
|
||||
| BR-PRE-06 | Largest paint per page and screen size, measured in Chrome 2026-10-31 at 412 x 823, 768 x 1024 and 1350 x 940 (unthrottled, Reveal forced visible to simulate this unit) and checked against the Lighthouse reports: `/`: the h1 text at every size (the hero photo is never reported, probably because it covers the whole viewport; not confirmed); `/over-mij`, `/soorten-fotoshoots` and the five shoot pages: their `priority` photo at every size; `/contact`: the intro text below `lg`, the aside photo from `lg`; `/portfolio`: a grid photo at every size once the grid is visible (a different tile per width); `/privacyverklaring` and the 404 page: text or the footer logo. Table with names: [domain-entities.md § 6](domain-entities.md). | FR-PR-21 |
|
||||
| BR-PRE-07 | The hero photo on `/` keeps its React-written preload with `fetchPriority="high"` although the largest paint there is text: it is the first thing a visitor sees. No explicit link is added. | FR-PR-21 |
|
||||
| BR-PRE-08 | **Provisional, and a deviation from FR-PR-21:** `/portfolio` gets no preload. Its largest paint after this unit is a grid photo (`DeferredImage`, loaded after the `load` event), a different tile at each width. `PortfolioGallery` keeps `eagerCount={0}` (decision 2026-10-27: eager photos measured 0.80 against 0.91 on mobile, because they slowed fonts and the intro text). A preload would repeat that and could not name one photo. The comment in `PortfolioGallery` ("the grid fades in, so its photos are never the largest paint") stops being true for a grid in view and is rewritten. Measuring "first row eager plus preload" is V-D5. | FR-PR-21; decision 2026-10-27 |
|
||||
| BR-PRE-09 | A route never preloads an image that is lazy or deferred, and never more than one explicit link per page. No `imagesrcset` or `imagesizes` is used (responsive photos are out of scope). | FR-PR-21 |
|
||||
|
||||
### BR-DMS: Measurement and the largest-paint mechanism
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-DMS-01 | Explanation, with evidence in [business-logic-model.md § 6](business-logic-model.md): the mobile Lighthouse LCP is a throttled simulation whose result follows the bytes requested before the real (unthrottled) LCP moment, at about 5.4 ms per KB; and in the "after" run the shoot pages' LCP waits for hydration because `Reveal` hides the photo. This unit removes the second cause. It does not change the bytes. | NFR-PR-P-03 |
|
||||
| BR-DMS-02 | After code generation the gate measurement is repeated with the unit 1 method (`lhci collect`, 3 runs per URL, mobile and desktop, median, same machine) against `measurement-gate.md`. At least one run per URL keeps its trace (Lighthouse gather mode) so the claim in BR-DMS-01 can be checked against the trace and not only inferred. | NFR-PR-P-03 |
|
||||
| BR-DMS-03 | Expected result, from the "Reveal visible" run (B) and the changes above: score and LCP better than A on `/over-mij`, `/soorten-fotoshoots`, the five shoot pages (by 77 to 226 ms), `/contact`; `/portfolio` on mobile worse than A (3007 to about 3600 ms, score 0.94 to about 0.90) because a photo becomes the largest paint; `/` unchanged at about 4280 ms. B is only an indication (BR-MEA-05); the real figures come from the measurement. | NFR-PR-P-01 |
|
||||
| BR-DMS-04 | Not solved by this unit and reported as such: `/` stays at about 0.85 (the 224 KB hero photo is requested before the text paint); zwangerschap, gezin, loveshoot and portret stay below 0.9 on mobile in B (0.88 to 0.89), and zwangerschap (+6), portret (+9), gezin (+80) and loveshoot (+139 ms) stay above master. The levers are bytes (photo size, 48 KB of 500 x 500 logos shown at 46 px, script size), which belong to the responsive-photos feature, unit 3 or the owner's per-page decision (NFR-PR-P-01). | NFR-PR-P-01 |
|
||||
|
||||
### BR-DTS: Tests
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-DTS-01 | `useReveal.test.tsx` changes where behaviour changed: jsdom has no layout (`getBoundingClientRect` returns zeros, so every element counts as in view), so tests that need a below-the-fold element stub `getBoundingClientRect` to return `top` larger than `innerHeight`. The cases "server render is visible", "in view at hydration stays visible, no observer", "below the fold is hidden and then visible after the observer fires", "reduced motion hides nothing and creates no observer", "no IntersectionObserver stays visible", "disconnects on unmount" replace the old ones. `Reveal.test.tsx` stays. No other test selects on hidden content (`grep` of `src`, 2026-10-31). | BR-TST-02 |
|
||||
| BR-DTS-02 | New example tests: `DeferredImage` through `renderToString` (twin once, `data-deferred` on the first image, no `<link rel="preload">` for the twin) and through `hydrate()` (no hydration error); `NoScriptNav` and `NoScriptStyles` through `renderToString`; `preloadImage`; the CSS-content test of BR-NAV-02; a check that every id the CSS names exists in the components (`mobile-nav`, `site-header`, `mobile-group-`, `data-submenu`). | NFR-PR-Q-01 |
|
||||
| BR-DTS-03 | Browser tests (`e2e/`, JavaScript off, 11 pages and the 404 page at 390 and 1280 px): no visible `button`; no visible `img` without a loaded photo (`complete` and `naturalWidth` > 0), none with `display` other than `none` among `img[data-deferred]`; every `img` has its alt text in the accessibility tree once; at 390 px the open link opens the menu, all links are focusable in the order of BR-NAV-08, the close link closes it, `scrollY` is unchanged; at 1280 px the submenu links are reached by Tab. With JavaScript, at 390 and 1280 px: the opacity of every `Reveal` that is in view at load is 1 on every animation frame from the first paint to hydration and after; below-the-fold ones are 0 and then fade in on scroll; no request for a deferred photo before it is near; every `preload as="image"` URL is used by a visible `img` at that width and requested exactly once; at 1280 px `/contact` requests the aside photo once and at 390 px not at all. | NFR-PR-Q-03; FR-PR-09, 11, 12, 21 |
|
||||
| BR-DTS-04 | The unit-1 browser tests keep passing: V9 (one review, the rest 1 px, `aria-hidden`, `inert`), V15 (the h1 and `main` stay in place between JavaScript off and on), BR-HYD-20 (no console error on any page). The raw-HTML tests that count `img` or links parse with `DOMParser`, which treats `noscript` as markup, so they must not count the twins or the menu links twice (V-D8). | BR-TST-05, 06 |
|
||||
|
||||
## 3. What this unit leaves for unit 3
|
||||
|
||||
| Belongs to | Left as it is |
|
||||
|---|---|
|
||||
| Servers and upload | Nothing changes: the new CSS and links are inside the HTML files. |
|
||||
| Lighthouse targets | `lighthouserc.cjs` exceptions are decided after BR-DMS-02; `/portfolio` may need an owner decision (section 5, O2). |
|
||||
| Responsive photos | Out of scope. The logos and photos stay as they are. |
|
||||
|
||||
## 4. To verify in code generation
|
||||
|
||||
Neither the code nor the probes of this design settle these.
|
||||
|
||||
| # | Point | Where it matters |
|
||||
|---|---|---|
|
||||
| V-D1 | `useLayoutEffect` in `Reveal` during `renderToString`, `hydrateRoot` and StrictMode (double effect): no warning, no mismatch, the hide step runs once visibly. | BR-RVL-02 |
|
||||
| V-D2 | With JavaScript on, the twin image is never requested (request log on `/soorten-fotoshoots` and `/portfolio` before any scroll), and the preload scanner does not read inside `noscript`. Also that Emotion writes the shared class once (one `<style>` for the two images). | BR-IMG-03 |
|
||||
| V-D3 | `<noscript>` inside `<head>` and inside the header and the panel hydrate without a mismatch in `hydrateRoot(document)` (the shell hydrates `<html>`), and the head hoisting of `HeadContent` keeps the CSS in the head. | BR-NAV-01 |
|
||||
| V-D4 | Fragment navigation to a fixed element does not scroll in Firefox and Safari, and Chrome on Android (only desktop Chrome was probed). If one scrolls, the fixed `header` target moves to a zero-size fixed element. | BR-NAV-07 |
|
||||
| V-D5 | Measure `/portfolio` with the first row eager and preloaded against deferred (mobile and desktop) before any change to `eagerCount`. | BR-PRE-08 |
|
||||
| V-D6 | Height of every `Reveal` at 320, 360, 412, 768, 1350 px wide against the limit of BR-RVL-13. | BR-RVL-13 |
|
||||
| V-D7 | After the gate measurement: whether `loading="lazy"` on the light logo and the contact portrait changes score and LCP as estimated; that the logo does not flash on `/` or on a client navigation from `/` to another page and back. | BR-PRE-05 |
|
||||
| V-D8 | The raw-HTML e2e tests that count `img` or links (`rawHtml.e2e.ts`) with `noscript` content present. | BR-DTS-04 |
|
||||
| V-D9 | The visible focus ring of the two menu links in Chakra's reset (a bare `a` outside Chakra components). | BR-NAV-08 |
|
||||
| V-D10 | Whether Chrome really excludes the viewport-filling hero photo from LCP (so text is the candidate on `/`), by a trace. Only explains `/`; changes no rule. | BR-PRE-06 |
|
||||
| V-D11 | The first React 19 upgrade: the hoisting facts of BR-PRE-01 (tested by BR-PRE-04). | BR-PRE-01 |
|
||||
| V-D12 | Visual check without JavaScript on every page at 390 and 1280 px (screenshots through `E2E_SCREENSHOT_DIR`, looked at, not compared): header, hero, nav, footer, empty areas left by hidden controls (`mb` of the filter bar, the gate's margin). | BR-NJS-01 to 06 |
|
||||
|
||||
## 5. Decisions for the owner (all provisional)
|
||||
|
||||
| # | Decision | Recommendation (written down) | Alternatives |
|
||||
|---|---|---|---|
|
||||
| O1 | First screen on client navigation (BR-RVL-10) | Same rule as the first load: in view appears at once, below the fold fades in on scroll | Keep today's entrance fade for the first screen on client navigation (needs a `useHydrated` branch and a second path to test) |
|
||||
| O2 | `/portfolio`: grid in view is visible, no preload, deferred photos stay (BR-RVL-03, BR-PRE-08) | Follow FR-PR-09 literally; expect mobile 0.94 to about 0.90 in the lab, real visitors see the photos earlier | (a) Keep the grid hidden until 12 % visible, i.e. leave the mobile portfolio grid empty under the filters at load as today (keeps 3007 ms, contradicts "content in view stays visible"); (b) first row eager plus preload (FR-PR-21 literal, measure first, V-D5) |
|
||||
| O3 | Desktop shoot submenu without JavaScript (BR-NAV-09) | Open on keyboard focus (`:focus-within`) | Leave unreachable (the overview page lists all five); or also open on hover with a bridge for the gap |
|
||||
| O4 | `loading="lazy"` on the light logo (not on `/`) and the contact portrait (BR-PRE-05) | Do it, about 140 ms of lab LCP on ten pages | Leave as is and resize the two 500 x 500 PNG logos (48 KB shown at 46 px) in the responsive-photos feature, which saves more |
|
||||
| O5 | Testimonials without JavaScript (BR-NJS-04) | One review (longest), as unit 1 | Show all reviews stacked: needs the hidden copies to lose `aria-hidden`, and V9 changes |
|
||||
+106
@@ -0,0 +1,106 @@
|
||||
# Domain Entities - Unit 2: Display fallbacks
|
||||
|
||||
The site has no runtime data model and unit 2 adds none. The entities are the reveal phase of an element, the markers and ids the no-JavaScript CSS depends on, the preload link, and the per-page inventory of the largest paint. Existing entities (`ContentImage`, `SitePage`, `NavItem`) are unchanged. Rules: [business-rules.md](business-rules.md). Flows: [business-logic-model.md](business-logic-model.md).
|
||||
|
||||
## 1. Relationships
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Rect["ViewportMeasure: top edge and viewport height"]
|
||||
Phase["RevealPhase: settled, hidden, revealed"]
|
||||
Elem["Reveal element"]
|
||||
Img["ContentImage: src, alt, width, height"]
|
||||
Pair["DeferredImagePair: empty img plus noscript twin"]
|
||||
Mark["JsOnlyMarker: data-requires-js, data-email-pending, data-deferred"]
|
||||
Css["NoScriptStyleSheet in the head"]
|
||||
Frag["FragmentTarget: mobile-nav, site-header"]
|
||||
Link["PreloadLink: rel preload, as image"]
|
||||
Prof["PageImageProfile: largest paint per page and width"]
|
||||
Rect -->|"decides first phase of"| Phase
|
||||
Phase -->|"styles"| Elem
|
||||
Img -->|"yields"| Pair
|
||||
Pair -->|"first image carries"| Mark
|
||||
Mark -->|"is hidden by"| Css
|
||||
Frag -->|"is shown by"| Css
|
||||
Img -->|"yields, only for picture"| Link
|
||||
Prof -->|"says which page needs a"| Link
|
||||
classDef value fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef entity fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef build fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class Rect,Phase,Img value;
|
||||
class Elem,Pair,Link,Prof entity;
|
||||
class Mark,Css,Frag build;
|
||||
```
|
||||
|
||||
Text alternative: a measured rectangle sets the reveal phase, a content image yields the deferred pair or a preload link, and the no-JavaScript stylesheet acts on markers and fragment targets.
|
||||
|
||||
## 2. Reveal phase
|
||||
|
||||
| Phase | When | `data-reveal` | opacity | transform | transition |
|
||||
|---|---|---|---|---|---|
|
||||
| `settled` | Prerender, hydrating render, in view at hydration, reduced motion, no observer | `visible` | 1 | none | none |
|
||||
| `hidden` | After hydration, wholly below the viewport | `hidden` | 0 | `translateY(24px)` | none |
|
||||
| `revealed` | Hidden element intersected (threshold 0.12, bottom margin 60 px) | `visible` | 1 | none | `opacity, transform`, 0.8 s, `smooth`, delay `delay` s |
|
||||
|
||||
Transitions: `settled` stays; `hidden` becomes `revealed`; `revealed` stays (P20, P21). `useReveal` returns `visible` (phase is not `hidden`) and `animated` (phase is `revealed`).
|
||||
|
||||
| Input of `startsHidden` | Type | Note |
|
||||
|---|---|---|
|
||||
| `top` | number | `getBoundingClientRect().top`; zero for `display: none` and in jsdom |
|
||||
| `viewportHeight` | number | `window.innerHeight` |
|
||||
|
||||
Constants kept from `useReveal`: `threshold` 0.12, `rootMargin` `0px 0px -60px 0px`; `translateY(24px)` and the `reveal` duration token from `Reveal`.
|
||||
|
||||
## 3. Markers the no-JavaScript CSS acts on
|
||||
|
||||
| Marker | Meaning | Rule | Put on |
|
||||
|---|---|---|---|
|
||||
| `data-requires-js` | No function without JavaScript; hidden | BR-NJS-01 | Hamburger button (`NavigationBar`); chevron buttons (`NavSubmenu`, `MobileNavGroup`); `HeroArrows` buttons; `HeroPauseButton`; hero progress bar; `FilterBar` root; testimonial controls spacer (`CarouselPlaceholder`); footer Contact column (through `FooterColumn`) |
|
||||
| `data-email-pending` | Placeholder for the address that never comes without JavaScript; hidden | BR-NJS-02 | Already there (unit 1): footer `li`, contact card `li` (two), gate sentence span, gate button placeholder |
|
||||
| `data-deferred` | Photo that is empty until JavaScript sets its `src`; hidden while it has no `src` | BR-IMG-02 | The first `<img>` of `DeferredImage` |
|
||||
| `data-submenu` and `data-submenu-panel` | Desktop submenu wrapper and its panel; panel opens on `:focus-within` | BR-NAV-09 | `NavSubmenu` wrapper `Box` and panel `Box` |
|
||||
|
||||
## 4. Fragment targets and ids
|
||||
|
||||
| Id | Element | Used by | Notes |
|
||||
|---|---|---|---|
|
||||
| `mobile-nav` | `MobileNav` panel (exists) | Open link `href`; `:target` rule | `position: fixed`; no scroll on navigation |
|
||||
| `site-header` | `NavigationBar`'s `chakra.header` (new `id`) | Close link `href` | `position: fixed`; no scroll on navigation |
|
||||
| `mobile-group-<slug>` | `MobileNavGroup` list (exists) | Selector prefix `[id^="mobile-group-"]` | Expanded without JavaScript |
|
||||
| `submenu-<slug>` | `NavSubmenu` panel (exists) | `aria-controls` | Not styled by id; the rule uses `data-submenu-panel` |
|
||||
| `main` | `SkipNavContent` (exists) | Skip link | Unchanged |
|
||||
|
||||
Classes written by hand in the CSS (no Emotion): `ns-menu-open`, `ns-menu-close`.
|
||||
|
||||
## 5. PreloadLink
|
||||
|
||||
| Field | Type | Value |
|
||||
|---|---|---|
|
||||
| `rel` | `'preload'` | constant |
|
||||
| `as` | `'image'` | constant |
|
||||
| `href` | string | `image.src`, the hashed asset URL Vite produced |
|
||||
| `fetchPriority` | `'high'` | constant |
|
||||
| `media` | string, optional | Only for a photo shown from one breakpoint (`ASIDE_MEDIA`, `(min-width: 64em)`) |
|
||||
|
||||
Written by React (not by this entity): one link per non-lazy `img` with `src`, inside the head (BR-PRE-01).
|
||||
|
||||
## 6. PageImageProfile (largest paint, preload source)
|
||||
|
||||
Sizes are transfer sizes from the Lighthouse reports. "React" means the hoisted link of BR-PRE-01.
|
||||
|
||||
| Page | Largest paint, below `lg` | Largest paint, from `lg` | Photo (KB) | Preload |
|
||||
|---|---|---|---|---|
|
||||
| `/` | h1 text | h1 text | Hero `hero-8` 224 | React, `fetchPriority="high"` (BR-PRE-07) |
|
||||
| `/over-mij` | `andrea-portret` | same | 84 | React |
|
||||
| `/portfolio` | grid tile 1 (`f41a1916`) at 412; tile 2 (`f41a1922`) at 768 | tile (`f41a7883`) | 54 to 144 each | None (BR-PRE-08) |
|
||||
| `/soorten-fotoshoots` | `newborn` | same | 74 | React |
|
||||
| `/soorten-fotoshoots/newborn` | `newborn` | same | 74 | React |
|
||||
| `/soorten-fotoshoots/zwangerschap` | `zwangerschap` | same | 103 | React |
|
||||
| `/soorten-fotoshoots/gezin` | `gezin` | same | 117 | React |
|
||||
| `/soorten-fotoshoots/loveshoot` | `loveshoot` | same | 153 | React |
|
||||
| `/soorten-fotoshoots/portret` | `portret` | same | 97 | React |
|
||||
| `/contact` | intro text | `contact-D949P5Az` (aside photo) | 80 | Explicit `media` link (BR-PRE-02) |
|
||||
| `/privacyverklaring` | footer logo | h1 text | none | None |
|
||||
| 404 page | footer logo | footer logo | none | None |
|
||||
|
||||
Logos, preloaded by React on every page today: `logo-dark` 23 KB and `logo-light` 25 KB, 500 x 500 px, shown at 46 px. The light logo is used only on `/` from `lg` (BR-PRE-05). The 72 px contact portrait is 5 KB.
|
||||
+130
@@ -0,0 +1,130 @@
|
||||
# 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](../../../inception/application-design/components.md) ("Display (unit 2)"); this document fixes the details and records the differences. Rules: [business-rules.md](business-rules.md). Logic: [business-logic-model.md](business-logic-model.md). Data: [domain-entities.md](domain-entities.md).
|
||||
|
||||
## 1. Component hierarchy
|
||||
|
||||
```mermaid
|
||||
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 `skip`ped 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](domain-entities.md); 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](business-logic-model.md). 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.
|
||||
Reference in New Issue
Block a user