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