Files
AndreaSlopFotografie/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/business-logic-model.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

5.3 KiB

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.

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.