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>
8.7 KiB
8.7 KiB
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 (
SectionHeadingstyle) is done. No new packages;fast-checkis 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
- Step 1: Content model. Add
imagePosition?: stringtoTestimonialwith a comment (rawobject-position, normalised before use); set'50% 42%'on the trouwshoot review intestimonials.ts. - Step 2:
normalizeImagePosition. Createweb/src/lib/normalizeImagePosition.tsper 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. - Step 3:
slideCounter. Createweb/src/lib/slideCounter.ts:(index: number, count: number) => stringgiving"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). - Step 4: Generators. In
web/src/test/arbitraries.tsaddimagePositionValid(two numbers 0..100, whole or with one or two decimals, random whitespace) andimagePositionAny(fc.oneofof valid, out-of-range, other strings and non-string values); givetestimonialandanyTestimonialan optionalimagePosition(PBT-07: shared, reusable). - 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: anyimagePosition(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).
- Step 6: Control recipe. In
carouselControl.tsremove thedotkind, makearrowa 44 px square without border or background with anopacitytransition (0.55 on hover and focus-visible), and update the comment. - Step 7:
TestimonialSlide. Rebuild perfrontend-components.md: one grid cell with the photo layer and the card layer fromlg; stacked in a wrapper of at most 640 px belowlg, card overlapping the photo by 36 px;DeferredImagewithobjectPositionfromnormalizeImagePosition; noFramedImage; cardpaper.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 fromlg.data-testid="testimonial-{id}"stays. - Step 8:
TestimonialCarousel.spacing0 (check that the next slide does not show at the edge), remove the items'psandpb, remove the dots, add the counter (aria-hidden,data-testid="testimonials-counter", text fromslideCounter(carousel.page, count)), place the bar at the bottom right fromlg(aligned with the card column) and centred below the slides underlg; keep the arrow keys, the instant flag for reduced motion, the live region and all other test ids. - Step 9:
Testimonialsplaceholder. Remove the padding wrappers; show the longest review as a plain slide; keep the other reviews visually hidden,aria-hiddenandinert; the spacer for the control bar only belowlg, still withdata-requires-js. Update the comments of the section and the placeholder. - 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 withinstantunder reduced motion; announcement unchanged; single review without controls and counter; prerendered HTML still holds every review) andTestimonialSlide.test.tsx(crop position fromimagePosition, 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.tsxand the hydration and prerender tests). - Step 11: Documentation. Update the testimonials lines in
_shared/reverse-engineering/(api-documentation.md:Testimonialfield and the two new helpers;architecture.mdandbusiness-overview.md: the section's behaviour); checkLAYOUT.mdagainst.ai/layout-conventions.mdand change it only if needed. - Step 12: Code summary. Write
construction/testimonials/code/code-summary.md(files, decisions, verification, extension compliance, and what needs a real browser). - 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 wholevitest runonce. Fix failures inside this stage. The prerender build, e2e, Lighthouse, swipe and visual checks are the phase-level Build and Test. - Step 14: Progress. Update
aidlc-state.mdand 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 forslideCounter; 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 ofpnpm test; PBT-09fast-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.