Adds the AI-DLC documents of the testimonials redesign
Continuous Integration / check (pull_request) Successful in 1m45s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 8m44s
Continuous Integration / deploy-production (pull_request) Skipped

Requirements, execution plan, functional design, code summaries, build and test results and the audit log; the reverse-engineering notes and the feature registry are updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-06 01:24:15 +01:00
co-authored by Claude Sonnet 5.5
parent b03b18f58e
commit 7a5e713b69
26 changed files with 1593 additions and 5 deletions
@@ -0,0 +1,48 @@
# Build and Test Summary
Run on 2026-11-06 in the worktree `AndreaSlopFotografie-testimonials-redesign` (branch `feature/testimonials-redesign` from master `c8ca5eb`), on the owner's PC.
## Build Status
- **Build tool**: pnpm 12.11, `tsc`, Vite with prerender
- **Build status**: Success (24 s)
- **Build artifacts**: `web/dist/client`; 12 pages prerendered; 16 inline scripts moved into 28 files
## Test Execution Summary
### Unit tests
- **Total**: 1414 in 134 files, 0 failed
- **Coverage**: thresholds met, including 100% for `src/lib`
- **Status**: Pass
### Integration (browser checks on the built site)
- **Heading style on six pages at 390, 768 and 1440 px**: capitals everywhere; no page scrolls sideways (`scrollWidth` equals the width on every page, on the branch and on master); the longest title takes 4 lines at 390 px and 3 lines from 768 px, as estimated (A2)
- **Testimonials geometry** (1440 / 1024 / 768 / 390 px): photo 638 x 426 and card 627 x 400 at 1440 px (overlap as in the canvas); the control bar sits under the card inside the slide; below 1024 px the layout is stacked with the photo at most 640 px wide; card colour `rgb(232, 224, 213)`; crop `50% 42%`; the second slide starts at the group's right edge, no glimpse
- **Behaviour**: next, previous, the loop, ArrowRight in the bar, dragging with the mouse and swiping on a touch device all change the review; after the scroll settles the counter and the announcement follow ("1 / 2" to "2 / 2", "Review 2 van 2"); the second photo is already loaded when it slides in; nothing changes by itself over 7 seconds
- **Status**: Pass
### Performance (Lighthouse)
- **Desktop** (`lighthouserc.desktop.cjs`): all 12 URLs pass
- **Mobile** (`pnpm lighthouse`): all assertions pass except one, **`/` performance 0.83 against a floor of 0.85** (blocking locally only; CI warns)
- **Root cause check**: five runs of `/` on the branch and five on a build of master, same machine, one after the other: branch 0.84 0.85 0.84 0.84 0.84, master 0.84 0.84 0.84 0.85 0.85 (median 0.84 for both); LCP about 4.36 s on both, TBT 60 to 80 ms on both; the LCP element is the hero (`span`), not the testimonials. So the change does not lower the score; the homepage is recorded at exactly 0.85 (`mobileExceptions`, owner decision 2026-11-01, `numberOfRuns: 1`) and fails by chance on this machine today, on master as well
- **Status**: No regression; the single-run local floor of `/` is borderline (known follow-up: responsive photos)
### Additional tests
- **E2E suite** (`pnpm e2e`): 12 files, 268 passed, 205 skipped; the same numbers on master
- **Security**: `pnpm audit:deps` clean (no known vulnerabilities in production packages); `pnpm audit:dev` reports 23 advisories in development tools (2 low, 10 moderate, 11 high), which do not block (NFR-SEC-05) and are unrelated to this change
- **Contract tests**: N/A (no API)
## Extension compliance (Build and Test)
| Extension | Rule | Status | Note |
|---|---|---|---|
| Security Baseline | SECURITY-04, 10, 15 | Compliant | See security-test-instructions.md; other rules N/A |
| Property-Based Testing | PBT-08 | Compliant | Seed printed on every run, shrinking on, part of `pnpm test` in CI |
| Property-Based Testing | PBT-02..07, 09, 10 | Compliant | Unchanged since Code Generation; PBT-06 N/A |
## Overall Status
- **Build**: Success
- **All tests**: Pass, with one local Lighthouse floor (`/` mobile performance) that is borderline and equal on master
- **Ready for Operations**: Not applicable (Operations phase declined at Requirements Analysis)
## Next Steps
Commit, push, open the pull request and handle it (authorised by the owner for this task), then update and clean up the branches.
@@ -0,0 +1,21 @@
# Build Instructions
## Prerequisites
- **Build tool**: pnpm 12.11 (`packageManager` in `web/package.json`), Vite, TypeScript; Node as in the CI image.
- **Dependencies**: the lock file `web/pnpm-lock.yaml`; no dependency was added or changed in this feature. In a new worktree run `pnpm install --frozen-lockfile` first.
- **Environment variables**: none needed locally. `LIGHTHOUSE_PERFORMANCE=warn` is set by CI (see performance-test-instructions.md).
- **System requirements**: Chrome for Lighthouse and the browser checks (`C:\Program Files\Google\Chrome\Application\chrome.exe` on this PC); free port 4173 for `pnpm preview` and Lighthouse.
## Build steps
1. Install dependencies: `cd web && pnpm install --frozen-lockfile`.
2. Build everything: `pnpm build` (runs `tsc`, `vite build` with prerender, and the script that moves inline scripts into files).
3. Verify: the output lists the 12 prerendered pages (`/`, `/404`, `/over-mij`, `/portfolio`, `/contact`, `/privacyverklaring`, `/soorten-fotoshoots` and its five shoot pages) and ends with "Inline scripts verplaatst: 12 pagina's gecontroleerd, 16 scripts verplaatst, 28 bestanden geschreven".
**Build artifacts**: `web/dist/client` (static HTML per page, assets, moved scripts). **Common warnings**: none expected.
## Troubleshooting
- **Type errors in `tsc`**: run `pnpm exec tsc --noEmit` to see them without building; the Chakra types come from `pnpm typegen` (also run by `postinstall`).
- **`vite build` fails during prerender**: a page throws while rendering on the server; run the failing route's test (`pnpm exec vitest run src/<test>`) to find it.
- **Port 4173 in use**: another session may be running Lighthouse; ask before starting `pnpm preview` (see the parallel-sessions agreement).
@@ -0,0 +1,28 @@
# End-to-End Test Instructions
## Automated
```bash
cd web
pnpm build
pnpm e2e # vitest run --config vitest.e2e.config.ts, against the built site
```
- **Expected**: 12 files; 268 passed and 205 skipped (the skips come from the suite itself and are the same on master).
- Nothing in the e2e suite names the old dots; the tests that touch the section look for `testimonial-{id}`, which still exists.
## Manual or scripted browser checks (a real browser, because jsdom has no layout)
Start `pnpm preview` and open `/`, scroll to "Lieve woorden".
| Check | Expected |
|---|---|
| Click next and previous | The slide moves horizontally in about a second; the counter reads "2 / 2" then "1 / 2"; the live region says "Review 2 van 2" |
| Loop | Next on the last review goes to the first; previous on the first goes to the last |
| Arrow keys | With focus on a button in the bar, ArrowRight and ArrowLeft move the review |
| Drag with the mouse, swipe on a phone | The slide follows and snaps; after about a second the counter and the announcement follow. Drag at least about half the width, a short drag snaps back |
| Nothing by itself | After 7 seconds the counter is unchanged |
| Reduced motion | With `prefers-reduced-motion: reduce` the change is immediate |
| The second photo | Loaded before it slides in (the carousel sets `near`) |
Results of the run of 2026-11-06 are in build-and-test-summary.md.
@@ -0,0 +1,30 @@
# Integration Test Instructions
## Purpose
The two units meet in the testimonials section: the new heading style (unit 1) sits above the new slides (unit 2), and the heading style also reaches every other page that uses `SectionHeading`. These scenarios check that they work together on the built site.
## Scenarios
### 1. Heading style on every page that uses `SectionHeading`
- **Setup**: `pnpm build`, then `pnpm preview` (port 4173).
- **Steps**: open `/`, `/over-mij`, `/contact`, `/portfolio`, `/soorten-fotoshoots/newborn` and `/soorten-fotoshoots/gezin` at 390, 768 and 1440 px; read the line count of each uppercase `h2` and the page's `scrollWidth`.
- **Expected**: every title shows in capitals; no page scrolls sideways; the longest title ("Lifestyle fotograaf met een passie voor storytelling") takes 4 lines at 390 px and 3 lines from 768 px.
### 2. Testimonials section on the built, prerendered page
- **Steps**: open `/`, scroll to "Lieve woorden", wait for the carousel; read the geometry of the slide, photo, card and control bar at 1440, 1024, 768 and 390 px.
- **Expected**: from 1024 px the photo overlaps the card and the control bar sits under the card inside the slide's height; below 1024 px the layout is stacked with the photo at most 640 px wide; the card is `rgb(232, 224, 213)`; the second slide starts at the group's right edge (no glimpse); the crop is `50% 42%` on the rings photo.
### 3. Prerender to hydration to carousel
- **Covered by**: the existing prerender, hydration and placeholder tests (`Testimonials in the prerendered HTML`, `displayHydration`, `hydration`) and the e2e suites `rawHtml`, `noJs` and `interaction`.
- **Expected**: the HTML holds every review's text; without JavaScript the longest review and the hidden copies are present; after hydration the carousel replaces the placeholder without a layout jump.
## Run
```bash
cd web
pnpm build && pnpm e2e # scenario 3 and the page-level checks
pnpm preview # then the browser checks of scenarios 1 and 2
```
The browser checks of scenarios 1 and 2 were run with `playwright-core` (already a dev dependency) against Chrome; the scripts are scratch files, not part of the repository.
@@ -0,0 +1,30 @@
# Performance Test Instructions
## Purpose
NFR-TR-02: the Lighthouse targets in `web/lighthouserc.cjs` (mobile) and `lighthouserc.desktop.cjs` do not go down because of this feature. The carousel stays lazy-loaded away from the hero, and the photos are the same files.
## Run
```bash
cd web
pnpm build
pnpm lighthouse # lhci autorun for mobile, then for desktop (&&)
```
- Needs port 4173 free and no heavy work in parallel: it skews the score. In the parallel-sessions agreement, ask the other sessions first.
- **Locally the performance assertion blocks; in CI it only warns** (`LIGHTHOUSE_PERFORMANCE=warn`), because the Raspberry Pi runner scores 30 to 40 points lower. `numberOfRuns` is 1 on purpose, so a page that sits exactly on its floor can fail by chance.
- Accessibility, best practices and SEO must be 1 on every page; those block everywhere.
## A/B check against master (when one page sits on its floor)
```bash
cd web
pnpm exec lhci collect --collect.url=http://localhost:4173/ --collect.numberOfRuns=5
```
Run it once with the branch's `dist` and once with master's `dist` (build master in the main checkout), then compare the scores in `.lighthouseci/lhr-*.json`. Do not run the two at the same time.
## Result of 2026-11-06
See build-and-test-summary.md: the homepage is on its floor of 0.85 and scores 0.84 on both the branch and master on this machine.
@@ -0,0 +1,23 @@
# Security Test Instructions
The change is front-end only: no new inputs, endpoints, storage or dependencies.
## Dependency audit
```bash
cd web
pnpm audit:deps # production packages, blocking: pnpm audit --prod --audit-level high
pnpm audit:dev # development tools, report only
```
- **Expected**: `audit:deps` reports "No known vulnerabilities found". `audit:dev` lists the known advisories in development tools (2026-11-06: 23, none in production); they do not block (NFR-SEC-05) and are not changed by this feature.
## Rules from the Security Baseline extension
| Rule | How it is checked |
|---|---|
| SECURITY-04 (headers and CSP) | No header or CSP change; the new styles are generated CSS classes, no inline `style` attribute; the e2e `serverRules` suite checks the headers; Lighthouse best-practices stays 1 |
| SECURITY-05 (in spirit) | `normalizeImagePosition` takes `unknown` and gives a safe string; its property tests include arbitrary values and `fc.anything()` |
| SECURITY-10 | Lock file unchanged; no dependency added |
| SECURITY-15 | `normalizeImagePosition` and `slideCounter` never throw (property tests) |
| Others | Not applicable: no data store, API, identity, logging or network configuration in this change |
@@ -0,0 +1,28 @@
# Unit Test Execution
## Run the unit tests
```bash
cd web
pnpm test # vitest run --coverage
```
- **Expected**: 134 files and 1414 tests pass; the coverage thresholds hold (including 100% for `src/lib`, which the two new helpers meet).
- **Seed**: fast-check prints `fast-check seed: <n>` at the top of every run. To replay a failure: `FC_SEED=<n> pnpm test` (PBT-08).
- **Reports**: coverage in `web/coverage`.
## Tests of this feature
| Area | Files |
|---|---|
| Section heading | `src/components/SectionHeading/SectionHeading.test.tsx` (uppercase and letter-spacing in CSS only; plain `sectionTitle` headings untouched) |
| Helpers | `src/lib/normalizeImagePosition.test.ts` and `slideCounter.test.ts` (examples plus properties), `visibleTestimonials.test.ts` (new property) |
| Components | `Testimonials.test.tsx` (no dots, counter, no timer, wiring of arrows, keys and reduced motion, prerendered HTML), `TestimonialSlide.test.tsx` (card, crop, no quotation mark) |
Property tests and example tests sit side by side (PBT-10). jsdom has no layout, so swiping, sliding and the geometry are checked in a real browser (see e2e-test-instructions.md).
## If a test fails
1. Read the output; for a property failure the shrunk counterexample and the seed are printed.
2. Replay with `FC_SEED=<n> pnpm exec vitest run <file>`.
3. Fix the code (or, if the property was wrong, the property) and add the shrunk case as a permanent example test.
@@ -0,0 +1,45 @@
# Code Generation Plan: section-heading (unit 1)
This plan is the single source of truth for Code Generation of this unit. Application code goes in `web/` of the worktree `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-testimonials-redesign`; only the summary (Step 6) goes under `aidlc-docs/`.
## Unit context
- **Goal**: `SectionHeading` shows its title in uppercase with wide letter-spacing, as in the approved canvas (FR-TR-05). It applies to all eight places that use `SectionHeading` (`AboutBlock`, `ContactSection`, `IntroGallery`, `Pricing`, `Testimonials`, `InstagramGrid`, `AboutIntro`, `ShootPage`) without changing those callers.
- **Dependencies**: none. Unit 2 (testimonials) comes after it and uses the same heading.
- **Stories**: none (User Stories skipped). Traceability is to requirements: FR-TR-05, assumptions A1 and A2, NFR-TR-01.
- **Functional Design**: skipped for this unit (a style change without logic). PBT-01 is N/A: there is no logic to give properties.
- **Existing files to modify** (brownfield, in place, no copies): `web/src/theme.ts`, `web/src/components/SectionHeading/SectionHeading.tsx`, `web/src/components/SectionHeading/SectionHeading.test.tsx`.
- **New files**: the code summary under `aidlc-docs/features/testimonials-redesign/construction/section-heading/code/`.
## Design of the change
| Item | Decision |
|---|---|
| New text style | `sectionHeading` in `theme.ts`: heading font, `textTransform: uppercase`, `letterSpacing: caps` (the existing token, 0.22em), line-height 1.15, size 26 px on phones (`base`) and 30 px from `md`. |
| Old text style | `sectionTitle` stays as it is: five other h2 elements use it directly (`CallToAction`, `PackageBlock`, `ShootBlock`, `ShootPage` twice, `StoryBlocks`), and they keep their style (assumption A1). Its comment is corrected, because it no longer belongs to `SectionHeading`. |
| `SectionHeading` | The `Heading` uses `textStyle="sectionHeading"`. No new props, no change to alignment, spacing, eyebrow or lead. The text in the DOM does not change (the case is only CSS), so accessible names and every existing test that looks for the title text keep working. |
| Size on phones | The canvas used 26 px on the phone artboard and 30 px on desktop; FR-TR-05 only says 30 px. This plan follows the canvas: 26 px below `md`. Requirements are updated to say so (Step 5). |
| Wrapping | Uppercase and letter-spacing make titles wider. The longest title is "Lifestyle fotograaf met een passie voor storytelling" (52 characters, `AboutBlock`, maximum width 620 px). By my estimate it takes about three lines on desktop and four on a phone. That is checked in Build and Test (assumption A2); this unit does not shorten any text. |
## Steps
- [x] **Step 1: Theme.** In `web/src/theme.ts` add the text style `sectionHeading` next to `sectionTitle` and correct the comment of `sectionTitle` (no longer used by `SectionHeading`; still used by the five direct h2 elements).
- [x] **Step 2: Component.** In `web/src/components/SectionHeading/SectionHeading.tsx` switch the `Heading` to `textStyle="sectionHeading"` and update the component comment (design reference: uppercase, letter-spaced title).
- [x] **Step 3: Unit tests.** In `SectionHeading.test.tsx` add example tests (PBT-10: not a property case, there is no logic):
- the h2 keeps its text exactly as given (the accessible name is not uppercased in the DOM), also for a long title;
- the generated CSS rules for the h2 contain `text-transform: uppercase` and the wide letter-spacing (using `cssRulesFor`, since jsdom does not compute responsive styles);
- the five direct `sectionTitle` headings do not get the new style (a render of `CallToAction` or `PackageBlock` checks that its h2 has no `text-transform: uppercase`).
- [x] **Step 4: Callers.** Search the other tests and the e2e tests for assumptions about the old heading style (`sectionTitle`, letter-spacing, text case); adjust only if one fails.
- [x] **Step 5: Requirements note.** In `requirements.md` change FR-TR-05 to "30 px from `md`, 26 px below" and mark A2 with the estimate of the longest title.
- [x] **Step 6: Code summary.** Write `aidlc-docs/features/testimonials-redesign/construction/section-heading/code/code-summary.md` (files changed, the decision, extension compliance).
- [x] **Step 7: Build and test this unit (Step 13.5).** In `web/`: `pnpm exec tsc --noEmit` (or the project's type check), lint, and the unit tests of `SectionHeading` and of every component that uses it; then the whole unit-test run (`pnpm test`) once. Fix failures inside this stage. The prerender build, the e2e tests and Lighthouse are part of the phase-level Build and Test.
- [x] **Step 8: Progress.** Update `aidlc-state.md`, check the plan checkboxes and set `active-features.md` to `🟢 Construction`.
## Extension compliance for this unit
- **Security Baseline**: SECURITY-04 (CSP) compliant by design: a theme text style produces a CSS class, no inline style, no new header. SECURITY-10 N/A: no dependency changes. All other rules N/A (front-end style change).
- **Property-Based Testing**: PBT-01..09 N/A (no logic, no pure function added). PBT-10: example tests only, because there are no properties to check; the existing property tests of other units are not touched.
## Scope and size
One theme entry, one component line, three small test cases, one summary and one requirements line. No new dependencies.
@@ -0,0 +1,61 @@
# Code Generation Plan: testimonials (unit 2)
This plan is the single source of truth for Code Generation of this unit. Application code goes in `web/` of the worktree `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-testimonials-redesign`; only summaries go under `aidlc-docs/`.
## Unit context
- **Goal**: the "Lieve woorden" section matches the approved canvas: card over a landscape photo, counter "X / Y" with arrows, no autoplay and no dots, a horizontal slide on change, a crop position per review (FR-TR-01..04, 06..14).
- **Design**: `construction/testimonials/functional-design/` (domain-entities, business-rules BR-TR-01..09, business-logic-model with the testable properties, frontend-components).
- **Dependencies**: unit 1 (`SectionHeading` style) is done. No new packages; `fast-check` is already there.
- **Brownfield rules**: files are changed in place; no copies. New files are only the two helpers and their tests.
- **Stories**: none (User Stories skipped); traceability is to FR-TR / NFR-TR and BR-TR / BR-REV.
## Files
| File | Action |
|---|---|
| `web/src/content/types.ts` | Modify: optional `imagePosition` on `Testimonial` |
| `web/src/content/testimonials.ts` | Modify: `imagePosition: '50% 42%'` on the trouwshoot review |
| `web/src/lib/normalizeImagePosition.ts` and `.test.ts` | Create |
| `web/src/lib/slideCounter.ts` and `.test.ts` | Create |
| `web/src/test/arbitraries.ts` | Modify: `imagePositionValid`, `imagePositionAny`; optional `imagePosition` on `testimonial` and `anyTestimonial` |
| `web/src/lib/visibleTestimonials.test.ts` | Modify: new property (an `imagePosition` never changes what is shown) |
| `web/src/recipes/carouselControl.ts` | Modify: drop `dot`; arrow without border, 44 px, opacity on hover |
| `web/src/components/home/Testimonials/TestimonialSlide.tsx` | Rebuild: card over photo, two layouts, crop |
| `web/src/components/home/Testimonials/TestimonialCarousel.tsx` | Modify: spacing 0, no item padding, counter, new bar placement, no dots |
| `web/src/components/home/Testimonials/Testimonials.tsx` | Modify: placeholder without padding wrappers, spacer below `lg` only |
| `web/src/components/home/Testimonials/TestimonialSlide.test.tsx`, `Testimonials.test.tsx` | Modify |
| `web/src/app.test.tsx` and other tests that name the dots or the old slide | Modify only if they fail |
| `aidlc-docs/_shared/reverse-engineering/` (`api-documentation.md`, `architecture.md`, `business-overview.md`) | Modify the lines about the testimonials (FR-TR-14) |
| `LAYOUT.md` | Check: the home diagram holds only the block name "Testimonials", which does not change; edit only if the diagram needs it |
| `aidlc-docs/features/testimonials-redesign/construction/testimonials/code/code-summary.md` | Create |
## Steps
- [x] **Step 1: Content model.** Add `imagePosition?: string` to `Testimonial` with a comment (raw `object-position`, normalised before use); set `'50% 42%'` on the trouwshoot review in `testimonials.ts`.
- [x] **Step 2: `normalizeImagePosition`.** Create `web/src/lib/normalizeImagePosition.ts` per the decision flow: `(value: unknown) => string`; two numbers with `%`, whitespace between and around, digits with optional decimals, each 0 to 100 inclusive; output `"X% Y%"` in shortest form; everything else `"50% 50%"`; never throws.
- [x] **Step 3: `slideCounter`.** Create `web/src/lib/slideCounter.ts`: `(index: number, count: number) => string` giving `"X / Y"`; odd input is made safe (count below 1 or not finite counts as 1; index is cut to a whole number and moved into range; non-finite index is 0).
- [x] **Step 4: Generators.** In `web/src/test/arbitraries.ts` add `imagePositionValid` (two numbers 0..100, whole or with one or two decimals, random whitespace) and `imagePositionAny` (`fc.oneof` of valid, out-of-range, other strings and non-string values); give `testimonial` and `anyTestimonial` an optional `imagePosition` (PBT-07: shared, reusable).
- [x] **Step 5: Property tests and example tests for the helpers (PBT-02..04, 07, 08, 10).**
- `normalizeImagePosition.test.ts`: invariant (any value gives the form with numbers 0..100), idempotence, round-trip with whitespace variants, easy verification (invalid gives exactly the centre); examples: `"50% 42%"`, `"050.0% 42%"` to `"50% 42%"`, `"120% 40%"`, `"50 42"`, `undefined`, `""`.
- `slideCounter.test.ts`: invariant over any numbers (including NaN and negatives) with 1 <= X <= Y, round-trip on valid positions, oracle against the plain template; examples `(0, 2)` is `"1 / 2"`, `(1, 2)` is `"2 / 2"`, `(5, 2)` is `"2 / 2"`, `(0, 0)` is `"1 / 1"`.
- `visibleTestimonials.test.ts`: any `imagePosition` (valid, garbled, missing) does not change which reviews are shown or their order.
- fast-check keeps shrinking on and prints its seed (already configured in the test setup; checked in Step 12).
- [x] **Step 6: Control recipe.** In `carouselControl.ts` remove the `dot` kind, make `arrow` a 44 px square without border or background with an `opacity` transition (0.55 on hover and focus-visible), and update the comment.
- [x] **Step 7: `TestimonialSlide`.** Rebuild per `frontend-components.md`: one grid cell with the photo layer and the card layer from `lg`; stacked in a wrapper of at most 640 px below `lg`, card overlapping the photo by 36 px; `DeferredImage` with `objectPosition` from `normalizeImagePosition`; no `FramedImage`; card `paper.deep`; shoot type, quote (`blockquote`) and names (`figcaption`, `accent.deeper`), no quotation mark; card minimum height 400 px with the 66 px control room at the bottom from `lg`. `data-testid="testimonial-{id}"` stays.
- [x] **Step 8: `TestimonialCarousel`.** `spacing` 0 (check that the next slide does not show at the edge), remove the items' `ps` and `pb`, remove the dots, add the counter (`aria-hidden`, `data-testid="testimonials-counter"`, text from `slideCounter(carousel.page, count)`), place the bar at the bottom right from `lg` (aligned with the card column) and centred below the slides under `lg`; keep the arrow keys, the instant flag for reduced motion, the live region and all other test ids.
- [x] **Step 9: `Testimonials` placeholder.** Remove the padding wrappers; show the longest review as a plain slide; keep the other reviews visually hidden, `aria-hidden` and `inert`; the spacer for the control bar only below `lg`, still with `data-requires-js`. Update the comments of the section and the placeholder.
- [x] **Step 10: Component tests.** Update `Testimonials.test.tsx` (no dots; counter "1 / 2" and "2 / 2" after next; arrows and arrow keys still call the API with `instant` under reduced motion; announcement unchanged; single review without controls and counter; prerendered HTML still holds every review) and `TestimonialSlide.test.tsx` (crop position from `imagePosition`, centre when missing, card contains shoot type, quote and names, no decorative quotation mark). Example tests pin the key scenarios; fix other tests that name the dots or the old slide only if they fail (`app.test.tsx` and the hydration and prerender tests).
- [x] **Step 11: Documentation.** Update the testimonials lines in `_shared/reverse-engineering/` (`api-documentation.md`: `Testimonial` field and the two new helpers; `architecture.md` and `business-overview.md`: the section's behaviour); check `LAYOUT.md` against `.ai/layout-conventions.md` and change it only if needed.
- [x] **Step 12: Code summary.** Write `construction/testimonials/code/code-summary.md` (files, decisions, verification, extension compliance, and what needs a real browser).
- [x] **Step 13: Build and test this unit (Step 13.5).** In `web/`: `tsc --noEmit`, `eslint .`, `prettier --check .`, the tests of the touched folders, then the whole `vitest run` once. Fix failures inside this stage. The prerender build, e2e, Lighthouse, swipe and visual checks are the phase-level Build and Test.
- [x] **Step 14: Progress.** Update `aidlc-state.md` and tick the checkboxes.
## Extension compliance for this unit
- **Security Baseline**: SECURITY-04: styles come from Chakra classes, no inline style attribute, no header change; the crop value is normalised before it reaches a style. SECURITY-05 (in spirit): content is validated, not trusted. SECURITY-10: no dependency change. SECURITY-15: the helpers never throw and fall back safely. Other rules N/A.
- **Property-Based Testing**: PBT-01 done in Functional Design; PBT-02 round-trips, PBT-03 invariants, PBT-04 idempotence (`normalizeImagePosition`) in Step 5; PBT-05 oracle for `slideCounter`; PBT-06 N/A (state is Chakra's); PBT-07 shared domain generators in Step 4; PBT-08 shrinking on, seed logged, runs in CI with the rest of `pnpm test`; PBT-09 `fast-check`; PBT-10 example tests next to every property.
## Scope and size
Two new helpers with tests, one content field, three components and one recipe changed, and test and documentation updates. No new dependencies.
@@ -0,0 +1,50 @@
# Vragen bij het functioneel ontwerp: testimonials
Vul achter elke `[Answer]:` de letter van je keuze in. Past geen enkele optie, kies dan de laatste (Anders) en licht je keuze toe. Bij elke vraag staat welke optie ik aanbeveel en waarom.
**Vaste uitgangspunten, hierover hoef je niets te beslissen:**
- Het canvas is de visuele referentie: desktop (1440 px) en telefoon (390 px). Voor het gebied daartussen is niets getekend.
- De carousel blijft gebouwd op Chakra's carousel; de loop, gelijke hoogte, de aankondiging "Review n van m" en het gedrag zonder JavaScript blijven zoals in de huidige spec.
- Tussen twee slides is geen ruimte (zoals in het canvas): de slide komt direct tegen de vorige aan schuiven.
- De teller "X / Y" is zichtbare tekst die schermlezers overslaan; de aankondiging bij een wissel doet de live region.
## Vraag 1
Vanaf welke breedte krijgt de testimonial de liggende opstelling met de kaart over de foto (zoals op desktop)? Het canvas tekent alleen 1440 px en 390 px. Nu staat de huidige opstelling gestapeld onder 1024 px (`lg`).
- A) Vanaf `lg` (1024 px), zoals nu; daaronder gestapeld met de foto op ten hoogste 640 px breed en gecentreerd, zodat hij op een tablet niet het hele scherm vult (aanbevolen: sluit aan bij de breekpunten van de rest van de site, en een kaart over een foto is op 768 px nog erg krap)
- B) Vanaf `md` (768 px): ook een tablet in de liggende opstelling, met een smallere kaart en kleinere tekst
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
## Vraag 2
In het canvas is de kaart 400 px hoog. De langste review (213 tekens) past daar op 1440 px ruim in, maar op 1024 px is de tekstkolom veel smaller en wordt de tekst hoger. Hoe bepalen we de hoogte van de kaart?
- A) Minimaal 400 px (of in verhouding tot de breedte), en hoger als de tekst dat nodig heeft; alle slides krijgen de hoogte van de hoogste, zodat de pagina eronder niet verspringt (aanbevolen: de tekst wordt nooit afgeknipt, en de gelijke hoogte van BR-REV-07 blijft kloppen)
- B) Vast 400 px; bij een lange review op een smal scherm wordt de tekst kleiner (risico: onleesbaar klein bij een lange review)
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
## Vraag 3
De huidige foto heeft een zandkleurig blok dat links en onderaan achter de foto uitsteekt (`FramedImage`). In het goedgekeurde canvas staat dat blok niet meer: de kaart zelf is het vlak achter de foto. Wat doen we?
- A) Geen zandblok meer; de foto is een gewone afbeelding met de bijsnijpositie (aanbevolen: zo staat het in het canvas, en de kaart vervult die rol al)
- B) Het zandblok blijft achter de foto, naast de kaart
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
## Vraag 4
Het veld `imagePosition` bevat twee percentages (bijvoorbeeld `"50% 42%"`). Wat gebeurt er met een waarde die buiten het bereik valt, bijvoorbeeld `"120% 40%"`, of een typefout als `"50 42"`?
- A) Elke waarde die niet precies uit twee percentages van 0 tot en met 100 bestaat telt als ongeldig en valt terug op het midden (`"50% 50%"`) (aanbevolen: voorspelbaar, en het is wat de requirements al zeggen: "ongeldige waarden vallen terug op het midden")
- B) Waarden buiten het bereik worden begrensd (`"120% 40%"` wordt `"100% 40%"`); alleen een onleesbare tekst valt terug op het midden
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A (gegeven in de chat)
@@ -0,0 +1,13 @@
# Functional Design Plan: testimonials (unit 2)
Only the checklist. The questions are in `testimonials-fd-questions.md`.
- [x] **Step 1: Analyse unit context.** Requirements FR-TR-01..04 and 06..14, NFR-TR-01..06, the approved canvas, and the existing design of the section (`homepage-sections/construction/lieve-woorden/functional-design`, BR-REV-01..11, BR-LZY-02).
- [x] **Step 2: Questions.** Four layout and behaviour questions the canvas does not settle (tablet layout, card height, sand block, out-of-range crop values).
- [x] **Step 3: Collect and check the answers.**
- [x] **Step 4: Domain entities.** `Testimonial` with the optional `imagePosition`; the normalised position; the counter text; invariants. File: `domain-entities.md`.
- [x] **Step 5: Business rules.** Updated rule table (what replaces BR-REV-04, 06, 09, 11; new rules for the counter, the crop and the card) and decision flowcharts. File: `business-rules.md`.
- [x] **Step 6: Business logic model.** Navigation (button, key, swipe, loop), announcement, placeholder swap, and the two pure helpers with their **testable properties (PBT-01)**. File: `business-logic-model.md`.
- [x] **Step 7: Frontend components.** Component hierarchy, layout geometry for desktop, tablet and phone, props, equal height, slide animation on Chakra's carousel, placeholder height, accessibility, test ids. File: `frontend-components.md`.
- [x] **Step 8: Extension compliance** for this stage (Security Baseline, PBT-01).
- [ ] **Step 9: Completion message and approval.** (message presented; awaiting approval)
@@ -0,0 +1,38 @@
# Code summary: section-heading (unit 1)
## What changed
| File | Change |
|---|---|
| `web/src/theme.ts` | New text style `sectionHeading`: heading font, `text-transform: uppercase`, `letter-spacing` from the shared `caps` token (0.22em), line-height 1.15, 26 px on phones and 30 px from `md`. The comment of `sectionTitle` now says it is the plain h2 for blocks that do not use `SectionHeading`. |
| `web/src/components/SectionHeading/SectionHeading.tsx` | The `Heading` uses `textStyle="sectionHeading"`. No new props; alignment, spacing, eyebrow and lead are untouched. The component comment says the case is only CSS. |
| `web/src/components/SectionHeading/SectionHeading.test.tsx` | Two new example tests: the title keeps its text and accessible name while the CSS rules hold uppercase and the `caps` letter-spacing; the plain h2 of `CallToAction` does not get the new style. |
| `aidlc-docs/features/testimonials-redesign/inception/requirements/requirements.md` | FR-TR-05 states 30 px from `md` and 26 px below; A2 holds the estimate for the longest title. |
No callers changed: the eight users of `SectionHeading` (`AboutBlock`, `ContactSection`, `IntroGallery`, `Pricing`, `Testimonials`, `InstagramGrid`, `AboutIntro`, `ShootPage`) get the new style through the component. The five h2 elements that use `sectionTitle` directly (`CallToAction`, `PackageBlock`, `ShootBlock`, `ShootPage` twice, `StoryBlocks`) keep their style (assumption A1).
No file was created or duplicated in `web/`; nothing else in the tests or e2e files referred to the old style.
## Verification of this unit (Step 13.5)
| Check | Result |
|---|---|
| Type check (`tsc --noEmit`) | passed |
| Lint on the changed files | passed |
| Format check (`prettier --check .`) | passed |
| `SectionHeading` tests | 5 passed |
| Whole unit-test run (`vitest run`) | 132 files, 1392 tests passed |
One test assertion was corrected during the run: the rule holds the token as a CSS variable (`var(--slp-letter-spacings-caps)`), not the literal `0.22em`. The code was right; the assertion was changed to check the variable.
Not part of this unit (phase-level Build and Test): prerender build, e2e tests, Lighthouse, and a visual check of every page that shows a `SectionHeading`, including the wrapping of the longest title (A2).
## Extension compliance
| Extension | Rule | Status | Note |
|---|---|---|---|
| Security Baseline | SECURITY-04 | Compliant | The new style is a generated CSS class; no inline style, no header change |
| Security Baseline | SECURITY-10 | N/A | No dependency change (`pnpm install --frozen-lockfile` only restored the worktree) |
| Security Baseline | other rules | N/A | Front-end style change; no inputs, storage, API or identity |
| Property-Based Testing | PBT-01..09 | N/A | No logic and no pure function added |
| Property-Based Testing | PBT-10 | Compliant | Example tests only, because there are no properties to check; existing property tests still pass |
@@ -0,0 +1,76 @@
# Code summary: testimonials (unit 2)
## What changed
| File | Change |
|---|---|
| `web/src/content/types.ts` | `Testimonial` gets the optional `imagePosition` (comment: not trusted, goes through `normalizeImagePosition`, has no say in whether a review is shown) |
| `web/src/content/testimonials.ts` | `imagePosition: '50% 42%'` on the trouwshoot review |
| `web/src/lib/normalizeImagePosition.ts` (new) | `(value: unknown) => string`: `"X% Y%"` or the centre `"50% 50%"`; never throws |
| `web/src/lib/slideCounter.ts` (new) | `(index, count) => string`: `"X / Y"`, safe for odd input |
| `web/src/lib/normalizeImagePosition.test.ts`, `slideCounter.test.ts` (new) | Example tests plus property tests (see below) |
| `web/src/lib/visibleTestimonials.test.ts` | New property: any `imagePosition` (valid, garbled, missing) changes neither which reviews are shown nor their order |
| `web/src/test/arbitraries.ts` | `imagePositionValid`, `imagePositionInvalid`, `imagePositionAny`; `testimonial` and `anyTestimonial` get an optional `imagePosition` |
| `web/src/recipes/carouselControl.ts` | `dot` removed; `arrow` is a 44 px target without border or background, lighter on hover |
| `web/src/components/home/Testimonials/TestimonialSlide.tsx` | Rebuilt: landscape photo over a `paper.deep` card; from `lg` one grid cell with both layers (photo 57%, card 56%, card at least 400 px, 66 px reserved under it when `withControls`); below `lg` stacked in at most 640 px with the card overlapping the photo by 36 px; photo through `DeferredImage` with `objectPosition`; no `FramedImage`, no quotation mark, no dash before the names |
| `web/src/components/home/Testimonials/TestimonialCarousel.tsx` | `spacing: '0px'`, no item padding, no dots, a counter (`aria-hidden`, `testimonials-counter`), the bar at the bottom right from `lg` and centred below the slides under `lg`; arrow keys, the `instant` flag, the live region and the other test ids unchanged |
| `web/src/components/home/Testimonials/Testimonials.tsx` | Placeholder without the padding wrappers; the control spacer only below `lg` (still one `data-requires-js` element) |
| `Testimonials.test.tsx`, `TestimonialSlide.test.tsx` | Updated and extended (no dots, counter, no timer, crop, card, no quotation mark) |
| `aidlc-docs/_shared/reverse-engineering/` (`api-documentation.md`, `architecture.md`, `business-overview.md`) | Testimonial field, the two helpers, the section's behaviour and the heading style |
| Functional design (`domain-entities.md`, `frontend-components.md`) | Aligned with what was built (see deviations) |
`LAYOUT.md` is unchanged on purpose: its home diagram only holds the block name "Testimonials", which stays.
## Deviations from the functional design (small, recorded here)
- **Rounding**: `normalizeImagePosition` rounds to at most two decimals instead of "the shortest form". A value like `0.0000001%` would otherwise print in exponent form, which cannot be read back (it would break idempotence). Design documents are updated.
- **Hover only**: the arrows lighten on hover but not on keyboard focus: opacity would also fade the focus ring. Focus keeps the theme's ring.
- **Photo loads early in the carousel**: `TestimonialSlide` gets a `near` prop that the carousel sets, so the next photo is not still loading while it slides in (the clipped off-screen slides never come into view on their own). The placeholder and the single review keep the lazy behaviour.
- **Control room only with a carousel**: the 66 px under the card is added only when `withControls` is set (carousel and its placeholder), not for a single review.
- **Text padding**: the left padding of the card text is 25% of the slide width (a percentage on a grid item refers to the grid area), as on the canvas; the design text said "of the card" and was corrected.
## Testable properties (PBT-02..08, 10)
| Function | Property | Category |
|---|---|---|
| `normalizeImagePosition` | Always two numbers from 0 to 100 with at most two decimals, for any value | Invariant |
| `normalizeImagePosition` | Normalising twice equals normalising once | Idempotence |
| `normalizeImagePosition` | Any whitespace layout of a valid value gives `"X% Y%"` with the same numbers | Round-trip |
| `normalizeImagePosition` | Every unacceptable value gives exactly `"50% 50%"` | Easy verification |
| `normalizeImagePosition` | Never throws, for `fc.anything()` | Invariant |
| `slideCounter` | Reads `X / Y` with 1 <= X <= Y for any numbers (NaN, infinite, negative, fractional) | Invariant |
| `slideCounter` | Gives back index + 1 and count for a valid position | Round-trip |
| `slideCounter` | Equals the plain template for a valid position | Oracle |
| `visibleTestimonials` | `imagePosition` never changes what is shown or in which order | Invariant |
Example tests pin the key scenarios next to each property (`"50% 42%"`, `"120% 40%"`, `(0, 2)` is `"1 / 2"`, ...). fast-check keeps shrinking on and the seed is printed in every run (`fast-check seed: ...`), CI runs it with `pnpm test`.
## Verification of this unit (Step 13.5)
| Check | Result |
|---|---|
| Type check (`tsc --noEmit`) | passed |
| `pnpm lint` | passed (one unused variable in my own test was fixed) |
| `pnpm format:check` | passed |
| Whole unit-test run with coverage (`pnpm test`) | 134 files, 1414 tests passed; coverage thresholds met (including the 100% for `lib/`) |
Not done here (phase-level Build and Test): prerender build, e2e tests, Lighthouse, a real-browser check of the swipe, the slide, the gap between slides (that the next slide never shows at the edge) and the geometry at 1024, 1440 and phone widths, plus the wrapping of every `SectionHeading` title.
## Extension compliance
| Extension | Rule | Status | Note |
|---|---|---|---|
| Security Baseline | SECURITY-04 | Compliant | Styles are Chakra classes; no inline style attribute; no header change; the crop value is normalised before it reaches a style |
| Security Baseline | SECURITY-05 (in spirit) | Compliant | Content is validated, not trusted (`unknown` in, safe string out) |
| Security Baseline | SECURITY-10 | N/A | No dependency change |
| Security Baseline | SECURITY-15 | Compliant | Both helpers never throw and fall back safely |
| Security Baseline | other rules | N/A | Front-end only; no store, API or identity |
| Property-Based Testing | PBT-02 | Compliant | Round-trips for both helpers |
| Property-Based Testing | PBT-03 | Compliant | Invariants for both helpers and for `visibleTestimonials` |
| Property-Based Testing | PBT-04 | Compliant | Idempotence of `normalizeImagePosition` |
| Property-Based Testing | PBT-05 | Compliant | Oracle for `slideCounter` |
| Property-Based Testing | PBT-06 | N/A | The carousel state belongs to Chakra |
| Property-Based Testing | PBT-07 | Compliant | Shared domain generators in `arbitraries.ts` |
| Property-Based Testing | PBT-08 | Compliant | Shrinking on, seed printed, part of CI |
| Property-Based Testing | PBT-09 | Compliant | `fast-check`, already a dependency |
| Property-Based Testing | PBT-10 | Compliant | Example tests beside every property |
@@ -0,0 +1,84 @@
# Business Logic Model: testimonials (unit 2)
## Navigation flow
All state lives in Chakra's carousel. Buttons, keys and swipes all end in the same place, so the counter and the announcement can not disagree with what is on screen.
```mermaid
graph TD
Button["Previous or next button"]
Key["Arrow key in the control bar"]
Swipe["Swipe or mouse drag on the slides"]
Api["Carousel scrollPrev, scrollNext, snap"]
Motion{"Prefers reduced motion?"}
Instant["Jump to the page"]
Slide["Slide horizontally to the page"]
Page["Carousel page changes"]
Counter["Counter text from slideCounter"]
Announce["Live region text from slideLabel"]
Button --> Api
Key --> Api
Swipe --> Api
Api --> Motion
Motion -->|"yes"| Instant
Motion -->|"no"| Slide
Instant --> Page
Slide --> Page
Page --> Counter
Page --> Announce
classDef input fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
classDef logic fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
classDef decision fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
classDef result fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
class Button,Key,Swipe input;
class Api,Page logic;
class Motion decision;
class Instant,Slide,Counter,Announce result;
```
Text alternative: buttons, arrow keys and swipes all call the carousel, which jumps or slides to the page depending on the reduced-motion preference; the new page then updates the counter text and the live-region announcement.
Notes:
- The carousel loops: next on the last review goes to the first, previous on the first to the last. With two reviews both buttons give the other review, only the direction of the slide differs.
- Swipes and drags are handled by the carousel (`allowMouseDrag`), which follows the finger and snaps; under reduced motion the snap is instant.
- Nothing runs on a timer.
- The announcement is empty on load and filled only by a change (BR-REV-08).
## Pure helpers
| Function | Signature | Behaviour |
|---|---|---|
| `slideCounter` (new, `web/src/lib/slideCounter.ts`) | `(index: number, count: number) => string` | `"X / Y"`; see domain-entities.md for the total behaviour on odd input |
| `normalizeImagePosition` (new, `web/src/lib/normalizeImagePosition.ts`) | `(value: unknown) => string` | `"X% Y%"` or `"50% 50%"`; see the decision flow in business-rules.md |
| `slideLabel` (unchanged) | `(index, count) => string` | `"Review n van m"` |
| `visibleTestimonials`, `isValidTestimonial` (unchanged) | | BR-REV-01 |
`normalizeImagePosition` takes `unknown` on purpose: the value comes from content that a CMS may deliver later, so it is checked, not trusted (SECURITY-05 in spirit, SECURITY-15 fail safe: never throws).
## Testable properties (PBT-01)
Framework: `fast-check` (already a dependency, with shared arbitraries in `web/src/test`; PBT-09 is met). Properties are in addition to example tests (PBT-10).
| Component | Category | Property |
|---|---|---|
| `slideCounter` | Invariant | For any numbers at all (also negative, fractional, NaN, infinite) the result matches `^\d+ / \d+$` and reads X <= Y with X >= 1 |
| `slideCounter` | Round-trip | For a valid position, parsing the result gives back `index + 1` and `count` |
| `slideCounter` | Oracle | For a valid position it equals the plain template `${index + 1} / ${count}` (the simplest possible reference) |
| `normalizeImagePosition` | Invariant | For any value (strings of every shape, numbers, `undefined`, `null`, objects) the result is two numbers from 0 to 100 with percent signs, separated by one space |
| `normalizeImagePosition` | Idempotence | `normalize(normalize(v)) === normalize(v)` for any value |
| `normalizeImagePosition` | Round-trip | For X and Y in 0..100 with at most two decimals, any layout of whitespace around the parts gives the same result as the plain `"X% Y%"` form, and that result keeps the numbers |
| `normalizeImagePosition` | Easy verification | A value outside the accepted form (generated as out-of-range, one part, no `%`, a sign, an exponent, extra text) always gives exactly `"50% 50%"` |
| `visibleTestimonials` | Invariant (new case) | Giving a review any `imagePosition` (valid, garbled or missing) does not change whether it is shown or in which order |
| `slideLabel`, `visibleTestimonials` (existing) | Invariant, Round-trip | Existing properties keep passing |
| Carousel navigation (next and previous around the loop) | Stateful (PBT-06) | **N/A**: the state belongs to Chakra's carousel, not to this code; a stateful model test would test the library. The loop is pinned by example tests |
| Layout, animation, placeholder | None | **No PBT properties identified**: presentation only; covered by example tests, the prerender and hydration tests, and the manual swipe check |
Generators (PBT-07), added to `web/src/test/arbitraries.ts` and reused by the tests:
- `imagePositionValid`: two numbers from 0 to 100 (whole and with one or two decimals) written with a percent sign and random whitespace between and around.
- `imagePositionAny`: `fc.oneof` of the valid form, out-of-range numbers, strings of other shapes, and non-string values.
- the existing `testimonial` arbitrary gets an optional `imagePosition` (valid, garbled or absent), so existing review properties also run with the new field.
@@ -0,0 +1,91 @@
# Business Rules: testimonials (unit 2)
Rule numbers `BR-REV-nn` are the ones of `homepage-sections/construction/lieve-woorden`; `BR-TR-nn` are new in this feature. Requirement references are to `requirements.md`.
## Rule table
| ID | Rule | Status | Source |
|---|---|---|---|
| BR-REV-01 | Only valid reviews are shown; broken ones are skipped, and of two with the same id the first wins; the order stays | Kept | FR-TR-09 |
| BR-REV-02 | No valid review: the section is left out; one review: shown without controls and without counter | Kept (counter added to the "without controls" part) | FR-TR-09 |
| BR-REV-03 | The carousel is shown from two reviews on, one review per page | Kept | FR-TR-09 |
| BR-REV-04 | Navigation | **Replaced** by BR-TR-01 (no dots) | FR-TR-07 |
| BR-REV-05 | The carousel loops; the buttons are never disabled | Kept | FR-TR-09 |
| BR-REV-06 | A change slides horizontally; instant under `prefers-reduced-motion` | Kept, now also for swipes and keys (all through the carousel's `instant` flag) | FR-TR-08 |
| BR-REV-07 | Every slide has the height of the tallest one | Kept | FR-TR-09 |
| BR-REV-08 | Every manual change is announced once, politely, as "Review n van m"; nothing on load | Kept | FR-TR-09 |
| BR-REV-09 | Slides are named "Review n van m"; buttons "Vorige review" and "Volgende review" | Kept without the dot labels | FR-TR-06 |
| BR-REV-10 | Hidden slides are not readable or focusable | Kept | FR-TR-09 |
| BR-REV-11 | The quote is a `blockquote` with the names as its `figcaption` | Kept, **without** the decorative quotation mark | FR-TR-04 |
| BR-LZY-02 | The prerendered HTML holds the text of every shown review | Kept | FR-TR-13 |
| BR-TR-01 | The review changes only through the previous and next buttons, the left and right arrow keys while focus is in the control bar, a swipe, or a drag with the mouse. No timer, no pause control, no dots | New | FR-TR-07 |
| BR-TR-02 | The counter reads "X / Y" (current of total, from 1). It is visible text that screen readers skip (`aria-hidden`); the live region carries the announcement | New | FR-TR-06, NFR-TR-01 |
| BR-TR-03 | The crop of a photo comes from `normalizeImagePosition(testimonial.imagePosition)`; a missing or invalid value gives the centre | New | FR-TR-11 |
| BR-TR-04 | Layout switches at `lg` (1024 px). From `lg`: the photo (3:2) on the left overlaps the card on the right. Below `lg`: stacked, with the photo (4:3) at most 640 px wide and centred, and the card overlapping its bottom by 36 px | New (question 1 = A) | FR-TR-01, FR-TR-02 |
| BR-TR-05 | The card is at least 400 px high and grows with its text; all slides take the height of the tallest (BR-REV-07). Text is never cut off or shrunk to fit | New (question 2 = A) | FR-TR-01 |
| BR-TR-06 | There is no coloured block behind the photo; the card is the surface behind it | New (question 3 = A) | FR-TR-01 |
| BR-TR-07 | The card is always `paper.deep`; quote text `ink.soft`; shoot type `ink`; names `accent.deeper`; all at least 4.5:1 on the card | New | FR-TR-03, NFR-TR-01 |
| BR-TR-08 | Until the carousel has loaded the placeholder shows the longest review as a slide, and below `lg` also the height of the control bar, so nothing below moves | Changed (no sand-block padding) | FR-TR-13 |
| BR-TR-09 | The heading of the section uses the heading style of unit 1 (`SectionHeading`) | Kept from unit 1 | FR-TR-05 |
## Decision flow: what is rendered
```mermaid
graph TD
Start["Reviews from the content"]
Filter["visibleTestimonials"]
Count{"How many shown?"}
None["Render nothing"]
One["One TestimonialSlide, no controls"]
Many{"Section near the screen?"}
Placeholder["Placeholder: longest slide, others hidden"]
Carousel["Carousel with controls and counter"]
Start --> Filter
Filter --> Count
Count -->|"none"| None
Count -->|"one"| One
Count -->|"two or more"| Many
Many -->|"no, or still loading"| Placeholder
Many -->|"yes, and loaded"| Carousel
classDef step fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef decision fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
classDef result fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
class Start,Filter step;
class Count,Many decision;
class None,One,Placeholder,Carousel result;
```
Text alternative: the reviews are filtered; none renders nothing, one renders a single slide without controls, and two or more render the placeholder until the section is near the screen and the carousel has loaded.
## Decision flow: normalising the crop position
```mermaid
graph TD
Raw["Raw imagePosition"]
Present{"Is it a string?"}
Parse{"Two numbers with percent signs, separated by whitespace?"}
Range{"Both from 0 to 100?"}
Format["Write as X% Y% in shortest form"]
Centre["Use 50% 50%"]
Raw --> Present
Present -->|"no"| Centre
Present -->|"yes"| Parse
Parse -->|"no"| Centre
Parse -->|"yes"| Range
Range -->|"no"| Centre
Range -->|"yes"| Format
classDef step fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef decision fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
classDef result fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
class Raw step;
class Present,Parse,Range decision;
class Format,Centre result;
```
Text alternative: a raw value that is a string of two percentages from 0 to 100 is written in its shortest form; every other value gives the centre.
@@ -0,0 +1,77 @@
# Domain Entities: testimonials (unit 2)
## Entity relationships
```mermaid
graph TD
Testimonial["Testimonial"]
ContentImage["ContentImage"]
ImagePosition["ImagePosition, normalised"]
ShownList["Shown reviews"]
Counter["Counter text"]
SlideLabel["Slide label"]
CarouselState["Carousel state, owned by Chakra"]
Testimonial -->|"has one"| ContentImage
Testimonial -->|"may carry raw value for"| ImagePosition
Testimonial -->|"filtered into"| ShownList
ShownList -->|"sets the count of"| CarouselState
CarouselState -->|"index and count give"| Counter
CarouselState -->|"index and count give"| SlideLabel
classDef entity fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef value fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000;
classDef external fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000;
class Testimonial,ContentImage,ShownList entity;
class ImagePosition,Counter,SlideLabel value;
class CarouselState external;
```
Text alternative: a Testimonial has one ContentImage and may carry a raw crop value that is normalised into an ImagePosition; the valid reviews form the shown list, which sets the count of Chakra's carousel state, and from that state's index and count come the counter text and the slide label (blue = entities, orange = derived values, purple = state owned by the library).
## Testimonial (changed: one optional field)
| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | Unique among shown reviews (first wins, BR-REV-01) |
| `shoot` | string | yes | Shoot type shown above the quote |
| `quote` | string | yes | Plain text without quotation marks; the design adds none |
| `author` | string | yes | Names under the quote |
| `image` | `ContentImage` | yes | `src`, `width` > 0, `height` > 0, `alt` |
| `imagePosition` | string | **no (new)** | Raw CSS `object-position` as two percentages, e.g. `"50% 42%"`. Never trusted as given: it is passed through `normalizeImagePosition` before it reaches a style |
**Invariants** (`isValidTestimonial`, unchanged): `id`, `shoot`, `quote`, `author` and `image.src` are not blank; `image.width` and `image.height` are above zero. `imagePosition` is **not** part of validity: a missing, empty or garbled value never hides a review, it only falls back to the centre.
Content values: trouwshoot `"50% 42%"`, newbornshoot not set (centre).
## ImagePosition (derived value)
The normalised crop position, always of the form `"X% Y%"`.
| Property | Rule |
|---|---|
| Accepted input | Two numbers, each followed by `%`, separated by whitespace; optional surrounding whitespace; digits with an optional decimal part; no sign, no exponent |
| Range | Each number from 0 up to and including 100 |
| Output | `"X% Y%"` where X and Y are the numbers rounded to at most two decimals and written without trailing zeros (`"050.0% 42%"` becomes `"50% 42%"`; `"0.0000001%"` becomes `"0%"`, so no exponent form can appear), one space between. The range check is on the number as given (`"100.001%"` is out of range) |
| Fallback | Anything else (missing, empty, one number, no `%`, out of range, negative, extra parts, text): the centre, `"50% 50%"` (owner's answer A, question 4) |
| Idempotence | Normalising a normalised value gives the same value |
## Counter text (derived value)
`"X / Y"` with X the current review (counted from 1) and Y the number of reviews.
| Property | Rule |
|---|---|
| Input | `index` (zero-based) and `count` (number of shown reviews) |
| Valid input | `count` is a whole number of at least 1 and `index` is a whole number from 0 up to `count - 1` |
| Output | `` `${index + 1} / ${count}` `` |
| Invalid input | Never throws and never reads wrong: a count below 1 or not a finite number counts as 1; an index outside the range, or not a finite number, is moved to the nearest end (0 or `count - 1`); fractions are cut off. The result always has 1 <= X <= Y |
## Slide label (unchanged)
`slideLabel(index, count)` gives `"Review n van m"` and names each slide and the announcement (BR-REV-08, BR-REV-09). The old dot labels `"Review n"` are removed together with the dots.
## Carousel state
Owned by Chakra's carousel (`page`, `pageSnapPoints`, loop, scroll position). The unit does not keep its own copy of the current review: the counter and the announcement read the carousel's `page` and the shown count.
@@ -0,0 +1,132 @@
# Frontend Components: testimonials (unit 2)
Visual reference: the design canvas <https://claude.ai/artifact/BEDx5KkBVMKXs6bjzoNoew> (desktop 1440 px, phone 390 px). Decisions of the owner after the canvas: tablet and phone share the stacked layout (question 1 = A), the card grows with its text (question 2 = A), no sand block (question 3 = A).
## Component hierarchy
```mermaid
graph TD
Route["routes/index.tsx"]
T["Testimonials"]
Section["PageSection tone alt"]
Heading["SectionHeading"]
Holder["Box with view observer"]
Placeholder["CarouselPlaceholder"]
Carousel["TestimonialCarousel, lazy"]
Slide["TestimonialSlide"]
Photo["DeferredImage with crop"]
Card["Card: shoot, quote, names"]
Controls["Control bar: prev, counter, next"]
Live["Live region"]
Lib["lib: visibleTestimonials, slideLabel, slideCounter, normalizeImagePosition"]
Recipe["carouselControl recipe"]
Route --> T
T --> Section
Section --> Heading
Section --> Holder
Holder --> Placeholder
Holder --> Carousel
Placeholder --> Slide
Carousel --> Slide
Carousel --> Controls
Carousel --> Live
Slide --> Photo
Slide --> Card
Controls --> Recipe
Lib -.-> T
Lib -.-> Carousel
Lib -.-> Slide
classDef root fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000;
classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000;
classDef logic fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000;
class Route root;
class T,Section,Heading,Holder,Placeholder,Carousel,Slide,Photo,Card,Controls,Live,Recipe ui;
class Lib logic;
```
Text alternative: the home route renders Testimonials in a PageSection with SectionHeading; a view-observing box shows either the placeholder or the lazy carousel, both made of TestimonialSlide (a cropped photo and a card), and the carousel adds the control bar and the live region; pure helpers feed all of them.
## Testimonials (changed a little)
- **Props**: unchanged, `{ content: HomeContent['testimonials']; testimonials: Testimonial[] }`.
- **Behaviour**: unchanged: `visibleTestimonials`; none gives `null`; one gives a single `TestimonialSlide`; two or more give the box with the view observer, the placeholder first and the lazy carousel once near the screen.
- **Section**: `PageSection` with `tone="alt"` (decision FR-TR-10), `data-testid="testimonials"`, centred `SectionHeading` with the unit 1 style.
## TestimonialSlide (rebuilt)
- **Props**: `{ testimonial: Testimonial }`.
- **Wrapper**: `data-testid="testimonial-{id}"`.
### From `lg` (1024 px)
One grid cell holds two stacked layers, so the row is as high as the higher one:
| Part | Placement |
|---|---|
| Photo | Left, 57% of the width, 3:2, starts 40 px below the top of the cell, above the card |
| Card | Right, 56% of the width, at least 400 px high (`minH`), `paper.deep`, with a bottom margin of 66 px that reserves the room for the control bar (22 px gap plus 44 px bar) |
| Card content | Centred in the card; left padding of 25% of the slide width (a percentage padding on a grid item refers to the grid area, as in the canvas; it clears the 13% overlap with the photo) and 44 px on the right |
The cell is therefore as high as the larger of "photo bottom" and "card plus the control room". The two overlap by about 13% of the width, as in the canvas.
### Below `lg`
A wrapper at most 640 px wide, centred. The photo is full width of the wrapper, 4:3; the card follows with a negative top margin of 36 px so it overlaps the bottom of the photo, with 72 px top padding so the text starts below the overlap and 28 px at the sides. Text centred. The control bar is below the card (see Controls).
### Photo
- `DeferredImage` (keeps the lazy loading, the width and height that reserve space, and the `noscript` twin) with `objectFit: cover`, `bg: paper.deep` until it loads, and `objectPosition` from `normalizeImagePosition(testimonial.imagePosition)`.
- No `FramedImage` and no coloured block (BR-TR-06). The source files stay 880 x 1100.
### Card text
| Element | Style |
|---|---|
| Shoot type | Heading font, uppercase, letter-spacing 0.2em, 21 px (19 px below `lg`), colour `ink` |
| Quote | `chakra.blockquote`, body font, weight 300, 17 px (16.5 px below `lg`), line-height 1.75, colour `ink.soft`, balanced wrapping (`text-wrap: pretty`) |
| Names | `chakra.figcaption`, small caps style (`textStyle="eyebrow"`), colour `accent.deeper`; the old "— " prefix is dropped |
`figure` > `blockquote` + `figcaption` stays (BR-REV-11). No decorative quotation mark. Plain elements are used instead of Chakra's `Blockquote` for the same bundle-size reason as before.
## TestimonialCarousel (changed)
- Chakra `useCarousel` with `slideCount`, `loop`, `allowMouseDrag`, `translations.item = slideLabel`, `onPageChange` for the announcement, and `spacing` set to 0 (slides come directly after each other, as on the canvas). The old 4 rem spacing existed so the sand block of one photo never peeked into the next slide; without that block it is not needed. Code Generation checks that the next slide never shows at the edge.
- `Carousel.ItemGroup` keeps `aria-live="off"`; items stretch to equal height (BR-REV-07); no more `ps` and `pb` of 1.5 rem on the items.
- Touch and mouse: the carousel follows the finger and snaps. Under reduced motion the buttons, keys and indicators call the API with `instant`; the swipe snap is made instant by the existing reduced-motion CSS.
- **Control bar** (own markup, as before): previous button, counter, next button.
- From `lg`: placed at the bottom right of the carousel, aligned with the card column (width 56%, left padding 25%, right 44 px), content centred; it sits in the room reserved under the card.
- Below `lg`: below the slides, centred, 28 px under the card.
- Buttons: icon only (the existing Ant Design arrows, offline), no circle and no border, 44 px target, lighter on hover (opacity), the theme focus ring on keyboard focus. Names "Vorige review" and "Volgende review". Arrow keys on the bar work as before.
- Counter: `Text` with the heading font, 16 px, letter-spacing 0.08em, `ink.soft`, `aria-hidden`, content `slideCounter(carousel.page, count)`.
- The dots are removed.
- **Live region**: unchanged: empty on load, `slideLabel(page, count)` after a change.
- **Test ids**: `testimonials-prev`, `testimonials-next`, `testimonials-status`, new `testimonials-counter`; `testimonials-dot-{n}` is removed.
## carouselControl recipe (changed)
The `dot` variant is removed. The `arrow` variant loses its 48 px box with border: it becomes a 44 px square target without border or background, with `opacity` transition (hover lowers the opacity to 0.55, which lightens it; keyboard focus gets the theme's focus ring and is not dimmed, because opacity would also fade the ring). The recipe comment names the buttons under the testimonials only.
## CarouselPlaceholder (changed)
- Shows the longest review as a normal `TestimonialSlide` (no padding wrappers any more), the other reviews visually hidden, `aria-hidden` and `inert` (BR-LZY-02).
- Below `lg` it adds a spacer of the control bar's height plus its margin, with `data-requires-js` as before; from `lg` no spacer is needed, because the bar sits inside the room the slide already reserves.
## Accessibility (NFR-TR-01)
- The region is named by the h2; the carousel keeps its `aria-roledescription` and label; slides are named "Review n van m".
- Contrast on `paper.deep`: names `accent.deeper` (about 6.4:1), quote `ink.soft` (about 6.1:1), shoot type `ink` (higher).
- Targets of at least 44 px; the focus ring comes from the theme.
- Hidden slides stay inert (BR-REV-10); the counter is hidden from assistive technology and never read twice.
- Axe clean for the placeholder, the carousel and the single review.
## Interaction flows
- Visitor presses next, presses the right arrow key in the bar, or swipes left: the carousel moves one review forward, slides (or jumps under reduced motion), the counter changes to "2 / 2", the live region announces "Review 2 van 2".
- On the last review, next goes to the first (loop); on the first, previous goes to the last.
- No form, no API call and no persisted state in this unit.
## Not in this unit
Autoplay and pause (removed), dots (removed), changes outside the Testimonials folder other than the theme-free helpers, content, test helpers and `LAYOUT.md`.