Files
AndreaSlopFotografie/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 7a5e713b69
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
Adds the AI-DLC documents of the testimonials redesign
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>
2026-11-06 01:24:15 +01:00

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 (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

  • 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.
  • 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.
  • 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).
  • 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).
  • 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).
  • 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.
  • 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.
  • 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.
  • 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.
  • 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).
  • 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.
  • 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 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.
  • 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.