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