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>
62 lines
8.7 KiB
Markdown
62 lines
8.7 KiB
Markdown
# 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.
|