diff --git a/aidlc-docs/_shared/reverse-engineering/api-documentation.md b/aidlc-docs/_shared/reverse-engineering/api-documentation.md index d2f0916..a301db2 100644 --- a/aidlc-docs/_shared/reverse-engineering/api-documentation.md +++ b/aidlc-docs/_shared/reverse-engineering/api-documentation.md @@ -70,6 +70,7 @@ None. There is no back-end yet (`api/` is empty). The static design README antic - Gallery (portfolio-page): `wrapIndex(index, count)`, `swipeDirection(start, end, threshold = 50)`, `masonryRowSpan({ width, height }, K = 40, gapRows = 2)`, `neighbourIndexes(index, count, radius = 2)`, `lightboxReducer(state, event)` (+ `LightboxState`, `LightboxEvent`) - Shoot pages (unit 1): `shootPagePath(id)`, `shootIdFromSlug(slug)`, `shootIdFromPath(pathname)` (`lib/shootPages.ts`); `shootPackage(shoot, packages)` (`lib/shootPackage.ts`); `fillPlaceholders(text, values)`, `fillRichText(rich, values)` (`lib/fillPlaceholders.ts`); `richTextToPlain(text)` (`lib/richTextToPlain.ts`); `shootPageView(id, page, sources)` (`lib/shootPageView.ts`) - Shoot pages (unit 2): `headingId(prefix, id)` (`lib/headingId.ts`), `readMoreLabel(shoot)` (`lib/readMoreLabel.ts`), `mosaicLayout(count): MosaicTile[]` (`lib/mosaicLayout.ts`), `storyLayout(stories): StoryLayout[]` (`lib/storyLayout.ts`), `shootPageBands(view): SectionBand[]` (`lib/shootPageBands.ts`; the section order of `ShootPage`), `isShootSectionPath(pathname)` (`lib/isShootSectionPath.ts`, FR-ST-14, used by `NotFound`) +- Testimonials (testimonials-redesign): `slideCounter(index, count): string` (`lib/slideCounter.ts`; the visible "X / Y", safe for odd input), `normalizeImagePosition(value: unknown): string` (`lib/normalizeImagePosition.ts`; `"X% Y%"` or the centre `"50% 50%"`, never throws) - Navigation (unit 3): `shootNavItems(shoots): NavItem[]` (`lib/shootNavItems.ts`); `isItemCurrent(item, pathname)`, `isSectionCurrent(item, pathname)` (`lib/navCurrent.ts`); `navMenuReducer(state, event)` with `NavMenuState`, `NavMenuEvent`, `initialNavMenuState`, `FocusRequest` (`lib/navMenuState.ts`) ### Monitoring @@ -93,7 +94,7 @@ None. There is no back-end yet (`api/` is empty). The static design README antic ### AboutPageContent - **Fields**: `head`, `intro` (eyebrow, title, `paragraphs: RichText[]`, image), `background`, `photos`, `personal`, `booking` (label + LinkTarget), `person` (name, jobTitle, knowsAbout) ### PricingPackage / Testimonial -- **Fields**: `id`, `name`, `price`, `features[]` / `id`, `shoot`, `quote`, `author`, `image` +- **Fields**: `id`, `name`, `price`, `features[]` / `id`, `shoot`, `quote`, `author`, `image`, `imagePosition?` (optional crop position of the landscape photo, two percentages such as `'50% 42%'`; normalised by `normalizeImagePosition`, never decides whether the review is shown; testimonials-redesign) ### SocialLink - **Fields**: `platform: SocialPlatform` (`facebook` | `instagram`), `href: string` - **Validation**: shown only if `href` is a valid https URL diff --git a/aidlc-docs/_shared/reverse-engineering/architecture.md b/aidlc-docs/_shared/reverse-engineering/architecture.md index 62dae12..4e7d17c 100644 --- a/aidlc-docs/_shared/reverse-engineering/architecture.md +++ b/aidlc-docs/_shared/reverse-engineering/architecture.md @@ -77,12 +77,12 @@ Text alternative: client.tsx starts Sentry and hydrates the prerendered page (pr ### components/home/ (homepage sections) - **Purpose**: The six homepage blocks below the hero, in LAYOUT.md order -- **Responsibilities**: `IntroGallery` (four photos, swipeable row on phones), `AboutBlock` (framed photo of Andrea + intro + link to `/over-mij`), `Pricing` + `PriceCard` (packages with "Boek" links → `/?pakket=…#contact`), `Testimonials` (+ `TestimonialCarousel`, `TestimonialSlide`), `ContactSection` (lazy `ContactForm` behind `ContactFormGate`, mailto fallback); the Instagram block is the shared `components/InstagramGrid` (fixed tiles linking to the profile, content from `instagramContent.ts`), also used on the portfolio +- **Responsibilities**: `IntroGallery` (four photos, swipeable row on phones), `AboutBlock` (framed photo of Andrea + intro + link to `/over-mij`), `Pricing` + `PriceCard` (packages with "Boek" links → `/?pakket=…#contact`), `Testimonials` (+ `TestimonialCarousel`, `TestimonialSlide`: a landscape photo over a card with a "X / Y" counter and arrows, no dots and no autoplay, slides on change and on swipe), `ContactSection` (lazy `ContactForm` behind `ContactFormGate`, mailto fallback); the Instagram block is the shared `components/InstagramGrid` (fixed tiles linking to the profile, content from `instagramContent.ts`), also used on the portfolio - **Type**: Application ### Shared section building blocks - **Purpose**: Reusable pieces extracted during homepage-sections; `HomeSection` was renamed to `PageSection` and `MediaText`/`Eyebrow` were extracted in over-mij-page -- **Responsibilities**: `PageSection` (section frame: `aria-labelledby`, tone `paper`/`alt`, width `default`/`narrow`/`full`, spacing `default`/`tight`/`flushTop`, anchor offset), `MediaText` (framed photo next to a text column, design `.about`), `Eyebrow` (accent label, optionally a heading), `SectionHeading` (eyebrow + h2 + lead, align start/center, compact spacing), `FramedImage` (photo with a coloured offset block, sand by default, design `.about__media`), `CallToAction` (closing block: h2, lead, action; added in soorten-fotoshoots-page), `RichParagraph` (paragraph with inline links), `DeferredImage` (loads after page load and near the viewport, reserves space), `Reveal` (fade-in on scroll, content always in the DOM, reduced motion respected); gallery blocks from portfolio-page: `PortfolioGrid` (CSS-only masonry in reading order, first 3 photos eager), `Lightbox` (Chakra `Dialog`, wrap-around browsing, keys, swipe, preloading, load-error note), `FilterBar` (toggle buttons, `filterControl` recipe) +- **Responsibilities**: `PageSection` (section frame: `aria-labelledby`, tone `paper`/`alt`, width `default`/`narrow`/`full`, spacing `default`/`tight`/`flushTop`, anchor offset), `MediaText` (framed photo next to a text column, design `.about`), `Eyebrow` (accent label, optionally a heading), `SectionHeading` (eyebrow + h2 + lead, align start/center, compact spacing; the h2 in letter-spaced capitals via the `sectionHeading` text style, testimonials-redesign), `FramedImage` (photo with a coloured offset block, sand by default, design `.about__media`), `CallToAction` (closing block: h2, lead, action; added in soorten-fotoshoots-page), `RichParagraph` (paragraph with inline links), `DeferredImage` (loads after page load and near the viewport, reserves space), `Reveal` (fade-in on scroll, content always in the DOM, reduced motion respected); gallery blocks from portfolio-page: `PortfolioGrid` (CSS-only masonry in reading order, first 3 photos eager), `Lightbox` (Chakra `Dialog`, wrap-around browsing, keys, swipe, preloading, load-error note), `FilterBar` (toggle buttons, `filterControl` recipe) - **Type**: Application (shared UI) ### components/PageIntro/, StatusPage/ @@ -103,7 +103,7 @@ Text alternative: client.tsx starts Sentry and hydrates the prerendered page (pr ### lib/ - **Purpose**: Pure, fully tested helpers -- **Responsibilities**: `emailAddress`, `visibleSocials`, `copyrightLine`, `slidesToLoad`, `backToTopThreshold`, `slideLabel`, `formatPrice`, `bookLabel`, `visiblePackages`, `visibleTestimonials`, `packageFromSearch`, `shootOptions`, `mailLink`, `validateContact`, `isLikelySpam`, `toContactPayload`, `contactFormReducer` +- **Responsibilities**: `emailAddress`, `visibleSocials`, `copyrightLine`, `slidesToLoad`, `backToTopThreshold`, `slideLabel`, `slideCounter`, `normalizeImagePosition`, `formatPrice`, `bookLabel`, `visiblePackages`, `visibleTestimonials`, `packageFromSearch`, `shootOptions`, `mailLink`, `validateContact`, `isLikelySpam`, `toContactPayload`, `contactFormReducer` - **Type**: Application (utility, 100% coverage threshold) ### hooks/ diff --git a/aidlc-docs/_shared/reverse-engineering/business-overview.md b/aidlc-docs/_shared/reverse-engineering/business-overview.md index 936c4d4..58f54aa 100644 --- a/aidlc-docs/_shared/reverse-engineering/business-overview.md +++ b/aidlc-docs/_shared/reverse-engineering/business-overview.md @@ -27,7 +27,7 @@ Text alternative: visitors and crawlers use the website, which links out to soci ## Business Description - **Business Description**: Portfolio and marketing website for Andrea Slop Fotografie, a lifestyle photographer in Huizen (NL). It presents her work (loveshoots, family, pregnancy and newborn shoots), tells who she is, lists shoot types and prices, and gets prospective clients to make contact. It will replace the existing WordPress (Solene theme) site at andreaslop.nl; a test build runs at test.andreaslop.nl. - **Business Transactions** (current state — front-end only, no back-end): - - **Browse the homepage** — hero slider with featured photos (autoplay, arrows, swipe, pause button, screen reader announcements), call-to-action to "Over mij"; below it Lifestyle fotografie (photo gallery), Over mij (intro + "Lees mijn verhaal" → `/over-mij`), Prijzen (packages), Lieve woorden (testimonials carousel), Contact and Instagram + - **Browse the homepage** — hero slider with featured photos (autoplay, arrows, swipe, pause button, screen reader announcements), call-to-action to "Over mij"; below it Lifestyle fotografie (photo gallery), Over mij (intro + "Lees mijn verhaal" → `/over-mij`), Prijzen (packages), Lieve woorden (testimonials carousel: arrows, a "X / Y" counter and swipe, no autoplay), Contact and Instagram - **Choose a package** — "Boek" on a price card scrolls to Contact with that shoot preselected (`?pakket=`) - **Contact the photographer** — contact form (validation, anti-spam) shown dimmed under a "coming soon" notice until the API exists; mailto fallback with a subject - **Navigate between pages** — header navigation (desktop), full-screen menu (mobile), footer menu, skip link, back-to-top button diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index 4b0ecb4..ef87365 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -11,3 +11,4 @@ | Feature | portfolio-page | ✅ Complete | feature/portfolio-page (based on master after over-mij merge; worktree ../AndreaSlopFotografie-portfolio) | web/src/routes/portfolio.tsx, web/src/content, new PortfolioGrid + Lightbox, InstagramGrid (moved to shared), own entries in sitePages.ts / lighthouserc.cjs, ImageGallery JSON-LD via the shared webPage() helper | 2026-10-24 | | Feature | shoot-type-pages | ✅ Complete (content follow-up: [content-pending.md](features/shoot-type-pages/content-pending.md)) | feature/shoot-type-pages (worktree ../AndreaSlopFotografie-shoot-type-pages) | new route(s) per shoot type under web/src/routes, web/src/content (shootTypes.ts extension, timeline content), shared Timeline component, links from soorten-fotoshoots, seo.ts (webPage helper), sitePages.ts / sitemap, lighthouserc.cjs | 2026-10-29 | | Feature | prerendering | ✅ Complete (merge pending) | feature/prerendering (worktree ../AndreaSlopFotografie-prerendering) | web/vite.config.ts, web/src/main.tsx, web/index.html, web/config/serverConfig.ts + web/deploy, CI workflow, web/lighthouserc.cjs, possibly Reveal/useReveal and hooks using media queries | 2026-10-31 | +| Feature | testimonials-redesign | ✅ Complete (pull request next) | feature/testimonials-redesign (worktree ../AndreaSlopFotografie-testimonials-redesign) | web/src/components/home/Testimonials (Testimonials, TestimonialSlide, TestimonialCarousel), web/src/recipes/carouselControl.ts, web/src/content (Testimonial type, testimonials.ts), possibly SectionHeading, LAYOUT.md, unit/e2e tests that reference the dots | 2026-11-05 | diff --git a/aidlc-docs/features/testimonials-redesign/aidlc-state.md b/aidlc-docs/features/testimonials-redesign/aidlc-state.md new file mode 100644 index 0000000..d260417 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/aidlc-state.md @@ -0,0 +1,69 @@ +# AI-DLC State Tracking + +## Project Information +- **Feature Name**: Testimonials redesign ("Lieve woorden" section: more elegant, closer to the live site's style, counter instead of dots, no autoplay) +- **Feature Slug**: testimonials-redesign +- **Project Type**: Brownfield +- **Start Date**: 2026-11-05T00:00:00Z +- **Current Stage**: Complete (Build and Test passed 2026-11-06; pull request next, owner authorised commit, push, PR and merge for this task) +- **Branch**: feature/testimonials-redesign (from master c8ca5eb). Commits and pushes only when the owner asks (task-scoped permission) +- **Worktree**: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-testimonials-redesign +- **Design source**: Design canvas https://claude.ai/artifact/BEDx5KkBVMKXs6bjzoNoew (private; Main.dc.html desktop, Mobiel.dc.html mobile). Decisions made on the canvas are recorded in the audit. + +## Workspace State +- **Existing Code**: Yes +- **Programming Languages**: TypeScript (React/TSX) +- **Build System**: pnpm + Vite, Gitea Actions CI +- **Project Structure**: Single front-end SPA in `web/`; static design reference in `design/andreaslop-static/`; `api/` (.NET back-end) +- **Reverse Engineering Needed**: No (team agreement: no full RE refresh per feature; only this feature's own lines are updated in `_shared/reverse-engineering/`) +- **Workspace Root**: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-testimonials-redesign + +## Code Location Rules +- **Application Code**: Workspace root (NEVER in aidlc-docs/) - front-end lives in `web/` +- **Feature Documentation**: aidlc-docs/features/testimonials-redesign/ only +- **Shared Artifacts**: aidlc-docs/_shared/ +- **Structure patterns**: See code-generation.md Critical Rules + +## Language Configuration +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) +- **Source**: inherited from aidlc-docs/language-preference.md (answer A); user may override + +## Extension Configuration +| Extension | Enabled | Decided At | +|---|---|---| +| Security Baseline | Yes | Requirements Analysis | +| Property-Based Testing | Yes (full enforcement) | Requirements Analysis | + +## Operations Configuration +- **Include Operations Phase**: No +- **Decided At**: Requirements Analysis + +## Stage Progress + +### 🔵 INCEPTION PHASE +- [x] Workspace Detection +- [x] Reverse Engineering - SKIP (shared artifacts used; delta lines only) +- [x] Requirements Analysis (approved 2026-11-06) +- [x] User Stories - SKIP +- [x] Workflow Planning (approved 2026-11-06) +- [ ] Application Design - SKIP +- [ ] Units Generation - SKIP (two units fixed in the plan) + +### 🟢 CONSTRUCTION PHASE +- [x] Functional Design - unit 1 SKIP, unit 2 EXECUTE (approved 2026-11-06) +- [ ] NFR Requirements - SKIP +- [ ] NFR Design - SKIP +- [ ] Infrastructure Design - SKIP +- [x] Code Generation - unit 1 (section-heading): approved 2026-11-06 +- [x] Code Generation - unit 2 (testimonials): approved 2026-11-06 +- [x] Build and Test - passed 2026-11-06 (summary in construction/build-and-test/); one local Lighthouse floor (`/` mobile 0.83 against 0.85) is borderline and equal on master +- [ ] Build and Test - EXECUTE + +### 🟡 OPERATIONS PHASE +- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP (Operations Configuration = No) + +## Execution Plan Summary +- **Units**: 1. section-heading, 2. testimonials (unit 1 first) +- **Stages to execute**: Functional Design (unit 2), Code Generation (both units), Build and Test +- **Stages to skip**: Reverse Engineering, User Stories, Application Design, Units Generation, NFR Requirements, NFR Design, Infrastructure Design, Operations (reasons in execution-plan.md) diff --git a/aidlc-docs/features/testimonials-redesign/audit.md b/aidlc-docs/features/testimonials-redesign/audit.md new file mode 100644 index 0000000..5c4b8e5 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/audit.md @@ -0,0 +1,293 @@ +# Audit log: testimonials-redesign + +## Workspace Detection + +**Timestamp**: 2026-11-05T00:00:00Z + +**User Input**: "ja ga verder met de code. doe dat met de aidlc workflow" + +**AI Response**: "Classified as Feature (brownfield): new look and new behaviour of an existing component. Created worktree ../AndreaSlopFotografie-testimonials-redesign on branch feature/testimonials-redesign from master c8ca5eb. Reverse Engineering skipped: shared artifacts exist and the team agreement is no full refresh per feature. Language inherited from aidlc-docs/language-preference.md (English documentation, Dutch conversation)." + +**Context**: Workspace Detection. All other items in active-features.md are complete, so no registry conflicts. The owner's earlier design brief and decisions on the canvas (listed in the next entries) are the input for Requirements Analysis. + +--- + +## Design Input: brief (before the workflow started) + +**Timestamp**: 2026-11-04T00:00:00Z + +**User Input**: "De testimonials zijn nu wat lomp. Dat mag wat eleganter. Meer richting de stijl van de live site. Niet hetzelfde, maar in die richting" + +**AI Response**: "Created a design canvas (desktop and mobile) based on the theme tokens." + +**Context**: Design phase, brief. + +--- + +## Design Input: live site reference + +**Timestamp**: 2026-11-04T00:00:00Z + +**User Input**: "Dit is het design op de live site. Geen controls, je moet swipen. Dat is niet ideaal, ik wil wel die controls behouden. Hij animeert de afbeelding die van links naar rechts een soort van binnen \"rolt\". De testimonials rouleren ook automatisch als een soort diavoorstelling" (screenshot attached: wide photo on the left, light grey card overlapping its right side with centred shoot type, quote and names, counter 01 / 02 below) + +**AI Response**: "Redesigned with an overlapping card, centred text, controls kept, roll-in photo and autoplay." + +**Context**: Design phase. + +--- + +## Design Input: slide animation and block background + +**Timestamp**: 2026-11-04T00:00:00Z + +**User Input**: "Ziet er goed uit. het roteren mag met een slide animatie en de achtergrondkleur hangt ook af van het block waarin de testimonials staan. Op de nieuwe site gaan die om en om dus dat wil ik wel aanhouden om dta patroon niet te breken." + +**AI Response**: "Rotation became a horizontal slide; the section background follows a `tone` setting." + +**Context**: Design phase. Later clarifications by the owner: "ho wacht, ik ha dhet over de achtergrondkleur van het blok, niet van het tekstvak. die was al goed namelijk"; then "als de achtergrond alt is dan valt de achtergrond van de tekstbox weg. misschien een donkerdere tint doen zodat je altijd het tekstvlak ziet?"; then "kan hij niet altijd de wat donkerdere tint krijgen? ik zi egeen noodzaak om een wisselende kleur te geven". Decision: the text card is always paper.deep (#e8e0d5); only the block background alternates (paper / paper.alt). + +--- + +## Design Input: controls and autoplay + +**Timestamp**: 2026-11-05T00:00:00Z + +**User Input**: "Kan je de cirkels om de pijltjes weghalen. Het balkje tussen de teksten mag weg en de tekst mag worden 01/02 dus X / Y waar X de huidige testimonial is en Y het aantal testimonials. De auto play mag er ook uit. Hij wisselt alleen bij klikken op de pijlen of bij swipen." + +**AI Response**: "Removed the circles, the progress bar, the pause button and autoplay; the counter reads \"1 / 2\"; swipe added to the prototype." + +**Context**: Design phase. Final design decisions. + +--- + +## Requirements Analysis - Verification Questions + +**Timestamp**: 2026-11-05T00:00:00Z + +**User Input**: "(none: questions generated by the AI)" + +**AI Response**: "Created inception/requirements/requirement-verification-questions.md with 6 questions (3 content, 3 process-level: Security Baseline, Property-Based Testing, Operations phase), based on the existing homepage-sections spec (BR-REV-01..11), Testimonials.tsx, TestimonialSlide.tsx, TestimonialCarousel.tsx, carouselControl.ts and the design canvas." + +**Context**: Requirements Analysis, Step 6. Awaiting the user's answers. + +--- + +## Requirements Analysis - Answers (given in chat) + +**Timestamp**: 2026-11-05T00:00:00Z + +**User Input**: "kan je de vragen hier sturen?" (the owner asked for the questions in chat instead of in the file; they were presented as clickable options and the answers recorded in the question file). Answers: Q1 (heading) = "Alle homepage-secties"; Q2 (tone) = "Vast op alt (Recommended)"; Q3 (crop) = "Veld imagePosition (Recommended)"; Q4 (Security Baseline) = "Ja (Recommended)"; Q5 (PBT) = "Ja, alle regels (Recommended)"; Q6 (Operations) = "Nee (Recommended)". Follow-up question on Q1 (SectionHeading is also used in AboutIntro and ShootPage): "Overal waar SectionHeading staat". + +**AI Response**: "Recorded the answers in requirement-verification-questions.md and in aidlc-state.md (Extension Configuration: Security Baseline = Yes, Property-Based Testing = Yes full; Operations Configuration: No). Loaded the full rules of both enabled extensions. Found that five more headings use textStyle sectionTitle without SectionHeading (CallToAction, PackageBlock, ShootBlock, ShootPage x2, StoryBlocks); recorded as assumption A1 in requirements.md for review." + +**Context**: Requirements Analysis, answers to Step 6. The deviation (questions answered in chat instead of the file) was the owner's explicit request. + +--- + +## Requirements Analysis - Approval Prompt + +**Timestamp**: 2026-11-05T00:00:00Z + +**User Input**: "(none: approval prompt shown)" + +**AI Response**: "Created inception/requirements/requirements.md (14 functional requirements FR-TR-01..14, 6 non-functional NFR-TR-01..06, extension applicability for Security Baseline and PBT, assumptions A1..A4). Offered: Request Changes, Add User Stories, Continue to Workflow Planning." + +**Context**: Requirements Analysis, Step 9. Awaiting the owner's decision. + +--- + +## Requirements Analysis - Approval + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Request Changes, Add User Stories or Continue to Next Stage (Workflow Planning)?" + +**User Input**: "ga verder" + +**Status**: Approved. User Stories stays skipped; assumptions A1..A4 accepted as written. + +**Context**: Requirements Analysis complete. + +--- + +## Workflow Planning - Approval Prompt + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Ready to proceed with this plan?" + +**User Input**: "(none: approval prompt shown)" + +**AI Response**: "Created inception/plans/execution-plan.md: two fixed units (1 section-heading, 2 testimonials); execute Functional Design (unit 2 only), Code Generation (both units) and Build and Test; skip Reverse Engineering, User Stories, Application Design, Units Generation, NFR Requirements, NFR Design, Infrastructure Design and Operations. Corrected the caller count of SectionHeading to eight in the plan and in requirements.md (earlier text said seven or '8 usages in 7 components')." + +**Context**: Workflow Planning, Step 9. Awaiting the owner's decision. + +--- + +## Workflow Planning - Approval + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Request Changes, Add Skipped Stages or Continue to Next Stage (Code Generation, unit 1)?" + +**User Input**: "ga verder" + +**Status**: Approved. + +**Context**: Workflow Planning complete. Next: Code Generation, unit 1 (section-heading), Part 1 (Planning). + +--- + +## Code Generation, unit 1 (section-heading) - Plan Approval Prompt + +**Timestamp**: 2026-11-06T00:00:00Z + +**User Input**: "(none: approval prompt shown)" + +**AI Response**: "Created construction/plans/section-heading-code-generation-plan.md (8 steps). Notes for the owner: new text style sectionHeading (sectionTitle stays for the five direct h2 elements), 26 px below md following the canvas (requirements said 30 px), and the longest title ('Lifestyle fotograaf met een passie voor storytelling', 52 characters) is estimated at three lines on desktop and four on a phone." + +**Context**: Code Generation Part 1, Step 7. Awaiting approval. + +--- + +## Code Generation, unit 1 (section-heading) - Plan Approval + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Request Changes or Approve Plan?" + +**User Input**: "approve plan" + +**Status**: Approved, including the 26 px size below md and the estimate for long titles (checked in Build and Test). + +**Context**: Code Generation Part 1 complete; starting Part 2 (Generation) for unit 1. + +--- + +## Code Generation, unit 1 (section-heading) - Generation Complete + +**Timestamp**: 2026-11-06T00:00:00Z + +**User Input**: "(none: approval prompt shown)" + +**AI Response**: "Modified theme.ts (text style sectionHeading), SectionHeading.tsx (uses it) and SectionHeading.test.tsx (two example tests); updated FR-TR-05 and A2 in requirements.md; wrote construction/section-heading/code/code-summary.md. Step 13.5: tsc, eslint and prettier clean; SectionHeading tests 5 passed; whole run 132 files, 1392 tests passed. One assertion was corrected (CSS variable instead of the literal 0.22em). Security Baseline: SECURITY-04 compliant, others N/A. PBT: N/A except PBT-10 (compliant). active-features.md set to Construction." + +**Context**: Code Generation Part 2, Step 14. Awaiting approval of the generated code. + +--- + +## Code Generation, unit 1 (section-heading) - Approval + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Request Changes or Continue to Next Stage (Functional Design, unit 2)?" + +**User Input**: "ga verder" + +**Status**: Approved. + +**Context**: Code Generation complete for unit 1. Next: Functional Design, unit 2 (testimonials). + +--- + +## Functional Design, unit 2 (testimonials) - Questions and Answers + +**Timestamp**: 2026-11-06T00:00:00Z + +**User Input**: "(answers given as clickable options in the chat, as the owner asked earlier for questions in chat)": Q1 (tablet layout) = "Vanaf lg, 1024 px (Recommended)"; Q2 (card height) = "Minimaal 400 px, groeit mee (Recommended)"; Q3 (sand block) = "Geen zandblok meer (Recommended)"; Q4 (crop value out of range) = "Ongeldig, dan midden (Recommended)". + +**AI Response**: "Created construction/plans/testimonials-functional-design-plan.md and testimonials-fd-questions.md (answers recorded in the file). No ambiguity in the answers, so no follow-up file." + +**Context**: Functional Design steps 2 and 3. + +--- + +## Functional Design, unit 2 (testimonials) - Artifacts and Approval Prompt + +**Timestamp**: 2026-11-06T00:00:00Z + +**User Input**: "(none: approval prompt shown)" + +**AI Response**: "Created construction/testimonials/functional-design/: domain-entities.md, business-rules.md (BR-REV carried over or replaced, BR-TR-01..09, two decision flowcharts), business-logic-model.md (navigation flow, two new pure helpers, testable properties PBT-01, generators), frontend-components.md (hierarchy, geometry from lg and below lg, controls, recipe, placeholder, accessibility). Security Baseline: SECURITY-04 and SECURITY-15 compliant by design, others N/A. PBT-01 compliant: properties listed per component, PBT-06 N/A with rationale." + +**Context**: Functional Design, Step 8. Awaiting the owner's decision. + +--- + +## Functional Design, unit 2 (testimonials) - Approval + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Request Changes or Continue to Next Stage (Code Generation, unit 2)?" + +**User Input**: "Ga verder" + +**Status**: Approved. + +**Context**: Functional Design complete for unit 2. Next: Code Generation, unit 2, Part 1 (Planning). + +--- + +## Code Generation, unit 2 (testimonials) - Plan Approval Prompt + +**Timestamp**: 2026-11-06T00:00:00Z + +**User Input**: "(none: approval prompt shown)" + +**AI Response**: "Created construction/plans/testimonials-code-generation-plan.md (14 steps): content field, two helpers with property tests, generators, recipe, three components, tests, RE documentation, summary, build and test." + +**Context**: Code Generation Part 1, Step 7. Awaiting approval. + +--- + +## Code Generation, unit 2 (testimonials) - Plan Approval + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Request Changes or Approve Plan?" + +**User Input**: "Approve plan" + +**Status**: Approved. + +**Context**: Code Generation Part 1 complete for unit 2; starting Part 2 (Generation). + +--- + +## Code Generation, unit 2 (testimonials) - Generation Complete + +**Timestamp**: 2026-11-06T00:00:00Z + +**User Input**: "(none: approval prompt shown)" + +**AI Response**: "Generated all 14 plan steps: imagePosition in the content model, helpers normalizeImagePosition and slideCounter with example and property tests, shared generators, carouselControl recipe without dots, rebuilt TestimonialSlide, changed TestimonialCarousel (counter, bar placement, spacing 0) and Testimonials placeholder, updated tests, RE documentation, code summary. Step 13.5: tsc, lint and prettier clean; whole run 134 files, 1414 tests passed with coverage thresholds met. Deviations recorded in the code summary: rounding to two decimals, hover-only dimming, near prop for the carousel photos, control room only with a carousel, text padding relative to the slide width. Security Baseline compliant or N/A; PBT-02..10 compliant, PBT-06 N/A." + +**Context**: Code Generation Part 2, Step 14. Awaiting approval of the generated code. + +--- + +## Code Generation, unit 2 (testimonials) - Approval, and authorisation for this task + +**Timestamp**: 2026-11-06T00:00:00Z + +**AI Prompt**: "Request Changes or Continue to Next Stage (Build and Test)?" + +**User Input**: "Ga door naar build en test. Als alles goed is mag je committen, pushen en PR maken. Die PR mag je zelf afhandelen en achteraf de branches updaten en opruimen" + +**Status**: Approved. The owner also authorised, for this task only (the Build and Test of this feature and its pull request): commit, push, create the pull request, handle (merge) it, then update and clean up the branches, on condition that everything is good. The authorisation ends when that task ends. + +**Context**: Code Generation complete for unit 2. Next: Build and Test. + +--- + +## Build and Test - Results + +**Timestamp**: 2026-11-06T00:00:00Z + +**User Input**: "(none: results of the run)" + +**AI Response**: "Build success (12 pages prerendered). Unit tests 134 files / 1414 tests passed with coverage thresholds met. E2E 268 passed, 205 skipped (identical on master). Audit: production clean, 23 advisories in development tools (do not block). Lighthouse desktop passes on 12 URLs; mobile passes except `/` performance 0.83 against 0.85 (blocks locally only; CI warns). A/B of five runs each: branch 0.84 0.85 0.84 0.84 0.84 and master 0.84 0.84 0.84 0.85 0.85, same LCP about 4.36 s, so no regression: the homepage floor is borderline with numberOfRuns 1 (known). Browser checks at 1440, 1024, 768 and 390 px: geometry as designed, no sideways scroll (same on master), next, previous, loop, arrow keys, drag and touch swipe work, counter and announcement follow, nothing moves by itself; longest title takes 4 lines at 390 px and 3 from 768 px. Wrote construction/build-and-test/ (7 files). Operations Configuration = No, so the feature is marked Complete." + +**Context**: Build and Test, Steps 7 to 9. The owner's earlier instruction covers the next step: commit, push, open the pull request and handle it, 'if everything is good'. I judged it good: the only failing assertion is a borderline floor that master misses just the same, and CI only warns on performance. + +--- diff --git a/aidlc-docs/features/testimonials-redesign/construction/build-and-test/build-and-test-summary.md b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/build-and-test-summary.md new file mode 100644 index 0000000..ad25007 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/build-and-test-summary.md @@ -0,0 +1,48 @@ +# Build and Test Summary + +Run on 2026-11-06 in the worktree `AndreaSlopFotografie-testimonials-redesign` (branch `feature/testimonials-redesign` from master `c8ca5eb`), on the owner's PC. + +## Build Status +- **Build tool**: pnpm 12.11, `tsc`, Vite with prerender +- **Build status**: Success (24 s) +- **Build artifacts**: `web/dist/client`; 12 pages prerendered; 16 inline scripts moved into 28 files + +## Test Execution Summary + +### Unit tests +- **Total**: 1414 in 134 files, 0 failed +- **Coverage**: thresholds met, including 100% for `src/lib` +- **Status**: Pass + +### Integration (browser checks on the built site) +- **Heading style on six pages at 390, 768 and 1440 px**: capitals everywhere; no page scrolls sideways (`scrollWidth` equals the width on every page, on the branch and on master); the longest title takes 4 lines at 390 px and 3 lines from 768 px, as estimated (A2) +- **Testimonials geometry** (1440 / 1024 / 768 / 390 px): photo 638 x 426 and card 627 x 400 at 1440 px (overlap as in the canvas); the control bar sits under the card inside the slide; below 1024 px the layout is stacked with the photo at most 640 px wide; card colour `rgb(232, 224, 213)`; crop `50% 42%`; the second slide starts at the group's right edge, no glimpse +- **Behaviour**: next, previous, the loop, ArrowRight in the bar, dragging with the mouse and swiping on a touch device all change the review; after the scroll settles the counter and the announcement follow ("1 / 2" to "2 / 2", "Review 2 van 2"); the second photo is already loaded when it slides in; nothing changes by itself over 7 seconds +- **Status**: Pass + +### Performance (Lighthouse) +- **Desktop** (`lighthouserc.desktop.cjs`): all 12 URLs pass +- **Mobile** (`pnpm lighthouse`): all assertions pass except one, **`/` performance 0.83 against a floor of 0.85** (blocking locally only; CI warns) +- **Root cause check**: five runs of `/` on the branch and five on a build of master, same machine, one after the other: branch 0.84 0.85 0.84 0.84 0.84, master 0.84 0.84 0.84 0.85 0.85 (median 0.84 for both); LCP about 4.36 s on both, TBT 60 to 80 ms on both; the LCP element is the hero (`span`), not the testimonials. So the change does not lower the score; the homepage is recorded at exactly 0.85 (`mobileExceptions`, owner decision 2026-11-01, `numberOfRuns: 1`) and fails by chance on this machine today, on master as well +- **Status**: No regression; the single-run local floor of `/` is borderline (known follow-up: responsive photos) + +### Additional tests +- **E2E suite** (`pnpm e2e`): 12 files, 268 passed, 205 skipped; the same numbers on master +- **Security**: `pnpm audit:deps` clean (no known vulnerabilities in production packages); `pnpm audit:dev` reports 23 advisories in development tools (2 low, 10 moderate, 11 high), which do not block (NFR-SEC-05) and are unrelated to this change +- **Contract tests**: N/A (no API) + +## Extension compliance (Build and Test) + +| Extension | Rule | Status | Note | +|---|---|---|---| +| Security Baseline | SECURITY-04, 10, 15 | Compliant | See security-test-instructions.md; other rules N/A | +| Property-Based Testing | PBT-08 | Compliant | Seed printed on every run, shrinking on, part of `pnpm test` in CI | +| Property-Based Testing | PBT-02..07, 09, 10 | Compliant | Unchanged since Code Generation; PBT-06 N/A | + +## Overall Status +- **Build**: Success +- **All tests**: Pass, with one local Lighthouse floor (`/` mobile performance) that is borderline and equal on master +- **Ready for Operations**: Not applicable (Operations phase declined at Requirements Analysis) + +## Next Steps +Commit, push, open the pull request and handle it (authorised by the owner for this task), then update and clean up the branches. diff --git a/aidlc-docs/features/testimonials-redesign/construction/build-and-test/build-instructions.md b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/build-instructions.md new file mode 100644 index 0000000..155ae8f --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/build-instructions.md @@ -0,0 +1,21 @@ +# Build Instructions + +## Prerequisites +- **Build tool**: pnpm 12.11 (`packageManager` in `web/package.json`), Vite, TypeScript; Node as in the CI image. +- **Dependencies**: the lock file `web/pnpm-lock.yaml`; no dependency was added or changed in this feature. In a new worktree run `pnpm install --frozen-lockfile` first. +- **Environment variables**: none needed locally. `LIGHTHOUSE_PERFORMANCE=warn` is set by CI (see performance-test-instructions.md). +- **System requirements**: Chrome for Lighthouse and the browser checks (`C:\Program Files\Google\Chrome\Application\chrome.exe` on this PC); free port 4173 for `pnpm preview` and Lighthouse. + +## Build steps + +1. Install dependencies: `cd web && pnpm install --frozen-lockfile`. +2. Build everything: `pnpm build` (runs `tsc`, `vite build` with prerender, and the script that moves inline scripts into files). +3. Verify: the output lists the 12 prerendered pages (`/`, `/404`, `/over-mij`, `/portfolio`, `/contact`, `/privacyverklaring`, `/soorten-fotoshoots` and its five shoot pages) and ends with "Inline scripts verplaatst: 12 pagina's gecontroleerd, 16 scripts verplaatst, 28 bestanden geschreven". + +**Build artifacts**: `web/dist/client` (static HTML per page, assets, moved scripts). **Common warnings**: none expected. + +## Troubleshooting + +- **Type errors in `tsc`**: run `pnpm exec tsc --noEmit` to see them without building; the Chakra types come from `pnpm typegen` (also run by `postinstall`). +- **`vite build` fails during prerender**: a page throws while rendering on the server; run the failing route's test (`pnpm exec vitest run src/`) to find it. +- **Port 4173 in use**: another session may be running Lighthouse; ask before starting `pnpm preview` (see the parallel-sessions agreement). diff --git a/aidlc-docs/features/testimonials-redesign/construction/build-and-test/e2e-test-instructions.md b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/e2e-test-instructions.md new file mode 100644 index 0000000..cdad764 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/e2e-test-instructions.md @@ -0,0 +1,28 @@ +# End-to-End Test Instructions + +## Automated + +```bash +cd web +pnpm build +pnpm e2e # vitest run --config vitest.e2e.config.ts, against the built site +``` + +- **Expected**: 12 files; 268 passed and 205 skipped (the skips come from the suite itself and are the same on master). +- Nothing in the e2e suite names the old dots; the tests that touch the section look for `testimonial-{id}`, which still exists. + +## Manual or scripted browser checks (a real browser, because jsdom has no layout) + +Start `pnpm preview` and open `/`, scroll to "Lieve woorden". + +| Check | Expected | +|---|---| +| Click next and previous | The slide moves horizontally in about a second; the counter reads "2 / 2" then "1 / 2"; the live region says "Review 2 van 2" | +| Loop | Next on the last review goes to the first; previous on the first goes to the last | +| Arrow keys | With focus on a button in the bar, ArrowRight and ArrowLeft move the review | +| Drag with the mouse, swipe on a phone | The slide follows and snaps; after about a second the counter and the announcement follow. Drag at least about half the width, a short drag snaps back | +| Nothing by itself | After 7 seconds the counter is unchanged | +| Reduced motion | With `prefers-reduced-motion: reduce` the change is immediate | +| The second photo | Loaded before it slides in (the carousel sets `near`) | + +Results of the run of 2026-11-06 are in build-and-test-summary.md. diff --git a/aidlc-docs/features/testimonials-redesign/construction/build-and-test/integration-test-instructions.md b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/integration-test-instructions.md new file mode 100644 index 0000000..8f1540d --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/integration-test-instructions.md @@ -0,0 +1,30 @@ +# Integration Test Instructions + +## Purpose + +The two units meet in the testimonials section: the new heading style (unit 1) sits above the new slides (unit 2), and the heading style also reaches every other page that uses `SectionHeading`. These scenarios check that they work together on the built site. + +## Scenarios + +### 1. Heading style on every page that uses `SectionHeading` +- **Setup**: `pnpm build`, then `pnpm preview` (port 4173). +- **Steps**: open `/`, `/over-mij`, `/contact`, `/portfolio`, `/soorten-fotoshoots/newborn` and `/soorten-fotoshoots/gezin` at 390, 768 and 1440 px; read the line count of each uppercase `h2` and the page's `scrollWidth`. +- **Expected**: every title shows in capitals; no page scrolls sideways; the longest title ("Lifestyle fotograaf met een passie voor storytelling") takes 4 lines at 390 px and 3 lines from 768 px. + +### 2. Testimonials section on the built, prerendered page +- **Steps**: open `/`, scroll to "Lieve woorden", wait for the carousel; read the geometry of the slide, photo, card and control bar at 1440, 1024, 768 and 390 px. +- **Expected**: from 1024 px the photo overlaps the card and the control bar sits under the card inside the slide's height; below 1024 px the layout is stacked with the photo at most 640 px wide; the card is `rgb(232, 224, 213)`; the second slide starts at the group's right edge (no glimpse); the crop is `50% 42%` on the rings photo. + +### 3. Prerender to hydration to carousel +- **Covered by**: the existing prerender, hydration and placeholder tests (`Testimonials in the prerendered HTML`, `displayHydration`, `hydration`) and the e2e suites `rawHtml`, `noJs` and `interaction`. +- **Expected**: the HTML holds every review's text; without JavaScript the longest review and the hidden copies are present; after hydration the carousel replaces the placeholder without a layout jump. + +## Run + +```bash +cd web +pnpm build && pnpm e2e # scenario 3 and the page-level checks +pnpm preview # then the browser checks of scenarios 1 and 2 +``` + +The browser checks of scenarios 1 and 2 were run with `playwright-core` (already a dev dependency) against Chrome; the scripts are scratch files, not part of the repository. diff --git a/aidlc-docs/features/testimonials-redesign/construction/build-and-test/performance-test-instructions.md b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/performance-test-instructions.md new file mode 100644 index 0000000..c1d4b8e --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/performance-test-instructions.md @@ -0,0 +1,30 @@ +# Performance Test Instructions + +## Purpose + +NFR-TR-02: the Lighthouse targets in `web/lighthouserc.cjs` (mobile) and `lighthouserc.desktop.cjs` do not go down because of this feature. The carousel stays lazy-loaded away from the hero, and the photos are the same files. + +## Run + +```bash +cd web +pnpm build +pnpm lighthouse # lhci autorun for mobile, then for desktop (&&) +``` + +- Needs port 4173 free and no heavy work in parallel: it skews the score. In the parallel-sessions agreement, ask the other sessions first. +- **Locally the performance assertion blocks; in CI it only warns** (`LIGHTHOUSE_PERFORMANCE=warn`), because the Raspberry Pi runner scores 30 to 40 points lower. `numberOfRuns` is 1 on purpose, so a page that sits exactly on its floor can fail by chance. +- Accessibility, best practices and SEO must be 1 on every page; those block everywhere. + +## A/B check against master (when one page sits on its floor) + +```bash +cd web +pnpm exec lhci collect --collect.url=http://localhost:4173/ --collect.numberOfRuns=5 +``` + +Run it once with the branch's `dist` and once with master's `dist` (build master in the main checkout), then compare the scores in `.lighthouseci/lhr-*.json`. Do not run the two at the same time. + +## Result of 2026-11-06 + +See build-and-test-summary.md: the homepage is on its floor of 0.85 and scores 0.84 on both the branch and master on this machine. diff --git a/aidlc-docs/features/testimonials-redesign/construction/build-and-test/security-test-instructions.md b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/security-test-instructions.md new file mode 100644 index 0000000..cd0bb81 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/security-test-instructions.md @@ -0,0 +1,23 @@ +# Security Test Instructions + +The change is front-end only: no new inputs, endpoints, storage or dependencies. + +## Dependency audit + +```bash +cd web +pnpm audit:deps # production packages, blocking: pnpm audit --prod --audit-level high +pnpm audit:dev # development tools, report only +``` + +- **Expected**: `audit:deps` reports "No known vulnerabilities found". `audit:dev` lists the known advisories in development tools (2026-11-06: 23, none in production); they do not block (NFR-SEC-05) and are not changed by this feature. + +## Rules from the Security Baseline extension + +| Rule | How it is checked | +|---|---| +| SECURITY-04 (headers and CSP) | No header or CSP change; the new styles are generated CSS classes, no inline `style` attribute; the e2e `serverRules` suite checks the headers; Lighthouse best-practices stays 1 | +| SECURITY-05 (in spirit) | `normalizeImagePosition` takes `unknown` and gives a safe string; its property tests include arbitrary values and `fc.anything()` | +| SECURITY-10 | Lock file unchanged; no dependency added | +| SECURITY-15 | `normalizeImagePosition` and `slideCounter` never throw (property tests) | +| Others | Not applicable: no data store, API, identity, logging or network configuration in this change | diff --git a/aidlc-docs/features/testimonials-redesign/construction/build-and-test/unit-test-instructions.md b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/unit-test-instructions.md new file mode 100644 index 0000000..e6cdac1 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/build-and-test/unit-test-instructions.md @@ -0,0 +1,28 @@ +# Unit Test Execution + +## Run the unit tests + +```bash +cd web +pnpm test # vitest run --coverage +``` + +- **Expected**: 134 files and 1414 tests pass; the coverage thresholds hold (including 100% for `src/lib`, which the two new helpers meet). +- **Seed**: fast-check prints `fast-check seed: ` at the top of every run. To replay a failure: `FC_SEED= pnpm test` (PBT-08). +- **Reports**: coverage in `web/coverage`. + +## Tests of this feature + +| Area | Files | +|---|---| +| Section heading | `src/components/SectionHeading/SectionHeading.test.tsx` (uppercase and letter-spacing in CSS only; plain `sectionTitle` headings untouched) | +| Helpers | `src/lib/normalizeImagePosition.test.ts` and `slideCounter.test.ts` (examples plus properties), `visibleTestimonials.test.ts` (new property) | +| Components | `Testimonials.test.tsx` (no dots, counter, no timer, wiring of arrows, keys and reduced motion, prerendered HTML), `TestimonialSlide.test.tsx` (card, crop, no quotation mark) | + +Property tests and example tests sit side by side (PBT-10). jsdom has no layout, so swiping, sliding and the geometry are checked in a real browser (see e2e-test-instructions.md). + +## If a test fails + +1. Read the output; for a property failure the shrunk counterexample and the seed are printed. +2. Replay with `FC_SEED= pnpm exec vitest run `. +3. Fix the code (or, if the property was wrong, the property) and add the shrunk case as a permanent example test. diff --git a/aidlc-docs/features/testimonials-redesign/construction/plans/section-heading-code-generation-plan.md b/aidlc-docs/features/testimonials-redesign/construction/plans/section-heading-code-generation-plan.md new file mode 100644 index 0000000..29601a8 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/plans/section-heading-code-generation-plan.md @@ -0,0 +1,45 @@ +# Code Generation Plan: section-heading (unit 1) + +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 the summary (Step 6) goes under `aidlc-docs/`. + +## Unit context + +- **Goal**: `SectionHeading` shows its title in uppercase with wide letter-spacing, as in the approved canvas (FR-TR-05). It applies to all eight places that use `SectionHeading` (`AboutBlock`, `ContactSection`, `IntroGallery`, `Pricing`, `Testimonials`, `InstagramGrid`, `AboutIntro`, `ShootPage`) without changing those callers. +- **Dependencies**: none. Unit 2 (testimonials) comes after it and uses the same heading. +- **Stories**: none (User Stories skipped). Traceability is to requirements: FR-TR-05, assumptions A1 and A2, NFR-TR-01. +- **Functional Design**: skipped for this unit (a style change without logic). PBT-01 is N/A: there is no logic to give properties. +- **Existing files to modify** (brownfield, in place, no copies): `web/src/theme.ts`, `web/src/components/SectionHeading/SectionHeading.tsx`, `web/src/components/SectionHeading/SectionHeading.test.tsx`. +- **New files**: the code summary under `aidlc-docs/features/testimonials-redesign/construction/section-heading/code/`. + +## Design of the change + +| Item | Decision | +|---|---| +| New text style | `sectionHeading` in `theme.ts`: heading font, `textTransform: uppercase`, `letterSpacing: caps` (the existing token, 0.22em), line-height 1.15, size 26 px on phones (`base`) and 30 px from `md`. | +| Old text style | `sectionTitle` stays as it is: five other h2 elements use it directly (`CallToAction`, `PackageBlock`, `ShootBlock`, `ShootPage` twice, `StoryBlocks`), and they keep their style (assumption A1). Its comment is corrected, because it no longer belongs to `SectionHeading`. | +| `SectionHeading` | The `Heading` uses `textStyle="sectionHeading"`. No new props, no change to alignment, spacing, eyebrow or lead. The text in the DOM does not change (the case is only CSS), so accessible names and every existing test that looks for the title text keep working. | +| Size on phones | The canvas used 26 px on the phone artboard and 30 px on desktop; FR-TR-05 only says 30 px. This plan follows the canvas: 26 px below `md`. Requirements are updated to say so (Step 5). | +| Wrapping | Uppercase and letter-spacing make titles wider. The longest title is "Lifestyle fotograaf met een passie voor storytelling" (52 characters, `AboutBlock`, maximum width 620 px). By my estimate it takes about three lines on desktop and four on a phone. That is checked in Build and Test (assumption A2); this unit does not shorten any text. | + +## Steps + +- [x] **Step 1: Theme.** In `web/src/theme.ts` add the text style `sectionHeading` next to `sectionTitle` and correct the comment of `sectionTitle` (no longer used by `SectionHeading`; still used by the five direct h2 elements). +- [x] **Step 2: Component.** In `web/src/components/SectionHeading/SectionHeading.tsx` switch the `Heading` to `textStyle="sectionHeading"` and update the component comment (design reference: uppercase, letter-spaced title). +- [x] **Step 3: Unit tests.** In `SectionHeading.test.tsx` add example tests (PBT-10: not a property case, there is no logic): + - the h2 keeps its text exactly as given (the accessible name is not uppercased in the DOM), also for a long title; + - the generated CSS rules for the h2 contain `text-transform: uppercase` and the wide letter-spacing (using `cssRulesFor`, since jsdom does not compute responsive styles); + - the five direct `sectionTitle` headings do not get the new style (a render of `CallToAction` or `PackageBlock` checks that its h2 has no `text-transform: uppercase`). +- [x] **Step 4: Callers.** Search the other tests and the e2e tests for assumptions about the old heading style (`sectionTitle`, letter-spacing, text case); adjust only if one fails. +- [x] **Step 5: Requirements note.** In `requirements.md` change FR-TR-05 to "30 px from `md`, 26 px below" and mark A2 with the estimate of the longest title. +- [x] **Step 6: Code summary.** Write `aidlc-docs/features/testimonials-redesign/construction/section-heading/code/code-summary.md` (files changed, the decision, extension compliance). +- [x] **Step 7: Build and test this unit (Step 13.5).** In `web/`: `pnpm exec tsc --noEmit` (or the project's type check), lint, and the unit tests of `SectionHeading` and of every component that uses it; then the whole unit-test run (`pnpm test`) once. Fix failures inside this stage. The prerender build, the e2e tests and Lighthouse are part of the phase-level Build and Test. +- [x] **Step 8: Progress.** Update `aidlc-state.md`, check the plan checkboxes and set `active-features.md` to `🟢 Construction`. + +## Extension compliance for this unit + +- **Security Baseline**: SECURITY-04 (CSP) compliant by design: a theme text style produces a CSS class, no inline style, no new header. SECURITY-10 N/A: no dependency changes. All other rules N/A (front-end style change). +- **Property-Based Testing**: PBT-01..09 N/A (no logic, no pure function added). PBT-10: example tests only, because there are no properties to check; the existing property tests of other units are not touched. + +## Scope and size + +One theme entry, one component line, three small test cases, one summary and one requirements line. No new dependencies. diff --git a/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-code-generation-plan.md b/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-code-generation-plan.md new file mode 100644 index 0000000..1fe8f76 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-code-generation-plan.md @@ -0,0 +1,61 @@ +# 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. diff --git a/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-fd-questions.md b/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-fd-questions.md new file mode 100644 index 0000000..9451041 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-fd-questions.md @@ -0,0 +1,50 @@ +# Vragen bij het functioneel ontwerp: testimonials + +Vul achter elke `[Answer]:` de letter van je keuze in. Past geen enkele optie, kies dan de laatste (Anders) en licht je keuze toe. Bij elke vraag staat welke optie ik aanbeveel en waarom. + +**Vaste uitgangspunten, hierover hoef je niets te beslissen:** + +- Het canvas is de visuele referentie: desktop (1440 px) en telefoon (390 px). Voor het gebied daartussen is niets getekend. +- De carousel blijft gebouwd op Chakra's carousel; de loop, gelijke hoogte, de aankondiging "Review n van m" en het gedrag zonder JavaScript blijven zoals in de huidige spec. +- Tussen twee slides is geen ruimte (zoals in het canvas): de slide komt direct tegen de vorige aan schuiven. +- De teller "X / Y" is zichtbare tekst die schermlezers overslaan; de aankondiging bij een wissel doet de live region. + +## Vraag 1 + +Vanaf welke breedte krijgt de testimonial de liggende opstelling met de kaart over de foto (zoals op desktop)? Het canvas tekent alleen 1440 px en 390 px. Nu staat de huidige opstelling gestapeld onder 1024 px (`lg`). + +- A) Vanaf `lg` (1024 px), zoals nu; daaronder gestapeld met de foto op ten hoogste 640 px breed en gecentreerd, zodat hij op een tablet niet het hele scherm vult (aanbevolen: sluit aan bij de breekpunten van de rest van de site, en een kaart over een foto is op 768 px nog erg krap) +- B) Vanaf `md` (768 px): ook een tablet in de liggende opstelling, met een smallere kaart en kleinere tekst +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A (gegeven in de chat) + +## Vraag 2 + +In het canvas is de kaart 400 px hoog. De langste review (213 tekens) past daar op 1440 px ruim in, maar op 1024 px is de tekstkolom veel smaller en wordt de tekst hoger. Hoe bepalen we de hoogte van de kaart? + +- A) Minimaal 400 px (of in verhouding tot de breedte), en hoger als de tekst dat nodig heeft; alle slides krijgen de hoogte van de hoogste, zodat de pagina eronder niet verspringt (aanbevolen: de tekst wordt nooit afgeknipt, en de gelijke hoogte van BR-REV-07 blijft kloppen) +- B) Vast 400 px; bij een lange review op een smal scherm wordt de tekst kleiner (risico: onleesbaar klein bij een lange review) +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A (gegeven in de chat) + +## Vraag 3 + +De huidige foto heeft een zandkleurig blok dat links en onderaan achter de foto uitsteekt (`FramedImage`). In het goedgekeurde canvas staat dat blok niet meer: de kaart zelf is het vlak achter de foto. Wat doen we? + +- A) Geen zandblok meer; de foto is een gewone afbeelding met de bijsnijpositie (aanbevolen: zo staat het in het canvas, en de kaart vervult die rol al) +- B) Het zandblok blijft achter de foto, naast de kaart +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A (gegeven in de chat) + +## Vraag 4 + +Het veld `imagePosition` bevat twee percentages (bijvoorbeeld `"50% 42%"`). Wat gebeurt er met een waarde die buiten het bereik valt, bijvoorbeeld `"120% 40%"`, of een typefout als `"50 42"`? + +- A) Elke waarde die niet precies uit twee percentages van 0 tot en met 100 bestaat telt als ongeldig en valt terug op het midden (`"50% 50%"`) (aanbevolen: voorspelbaar, en het is wat de requirements al zeggen: "ongeldige waarden vallen terug op het midden") +- B) Waarden buiten het bereik worden begrensd (`"120% 40%"` wordt `"100% 40%"`); alleen een onleesbare tekst valt terug op het midden +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A (gegeven in de chat) diff --git a/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-functional-design-plan.md b/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-functional-design-plan.md new file mode 100644 index 0000000..6eaefef --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/plans/testimonials-functional-design-plan.md @@ -0,0 +1,13 @@ +# Functional Design Plan: testimonials (unit 2) + +Only the checklist. The questions are in `testimonials-fd-questions.md`. + +- [x] **Step 1: Analyse unit context.** Requirements FR-TR-01..04 and 06..14, NFR-TR-01..06, the approved canvas, and the existing design of the section (`homepage-sections/construction/lieve-woorden/functional-design`, BR-REV-01..11, BR-LZY-02). +- [x] **Step 2: Questions.** Four layout and behaviour questions the canvas does not settle (tablet layout, card height, sand block, out-of-range crop values). +- [x] **Step 3: Collect and check the answers.** +- [x] **Step 4: Domain entities.** `Testimonial` with the optional `imagePosition`; the normalised position; the counter text; invariants. File: `domain-entities.md`. +- [x] **Step 5: Business rules.** Updated rule table (what replaces BR-REV-04, 06, 09, 11; new rules for the counter, the crop and the card) and decision flowcharts. File: `business-rules.md`. +- [x] **Step 6: Business logic model.** Navigation (button, key, swipe, loop), announcement, placeholder swap, and the two pure helpers with their **testable properties (PBT-01)**. File: `business-logic-model.md`. +- [x] **Step 7: Frontend components.** Component hierarchy, layout geometry for desktop, tablet and phone, props, equal height, slide animation on Chakra's carousel, placeholder height, accessibility, test ids. File: `frontend-components.md`. +- [x] **Step 8: Extension compliance** for this stage (Security Baseline, PBT-01). +- [ ] **Step 9: Completion message and approval.** (message presented; awaiting approval) diff --git a/aidlc-docs/features/testimonials-redesign/construction/section-heading/code/code-summary.md b/aidlc-docs/features/testimonials-redesign/construction/section-heading/code/code-summary.md new file mode 100644 index 0000000..4f4b348 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/section-heading/code/code-summary.md @@ -0,0 +1,38 @@ +# Code summary: section-heading (unit 1) + +## What changed + +| File | Change | +|---|---| +| `web/src/theme.ts` | New text style `sectionHeading`: heading font, `text-transform: uppercase`, `letter-spacing` from the shared `caps` token (0.22em), line-height 1.15, 26 px on phones and 30 px from `md`. The comment of `sectionTitle` now says it is the plain h2 for blocks that do not use `SectionHeading`. | +| `web/src/components/SectionHeading/SectionHeading.tsx` | The `Heading` uses `textStyle="sectionHeading"`. No new props; alignment, spacing, eyebrow and lead are untouched. The component comment says the case is only CSS. | +| `web/src/components/SectionHeading/SectionHeading.test.tsx` | Two new example tests: the title keeps its text and accessible name while the CSS rules hold uppercase and the `caps` letter-spacing; the plain h2 of `CallToAction` does not get the new style. | +| `aidlc-docs/features/testimonials-redesign/inception/requirements/requirements.md` | FR-TR-05 states 30 px from `md` and 26 px below; A2 holds the estimate for the longest title. | + +No callers changed: the eight users of `SectionHeading` (`AboutBlock`, `ContactSection`, `IntroGallery`, `Pricing`, `Testimonials`, `InstagramGrid`, `AboutIntro`, `ShootPage`) get the new style through the component. The five h2 elements that use `sectionTitle` directly (`CallToAction`, `PackageBlock`, `ShootBlock`, `ShootPage` twice, `StoryBlocks`) keep their style (assumption A1). + +No file was created or duplicated in `web/`; nothing else in the tests or e2e files referred to the old style. + +## Verification of this unit (Step 13.5) + +| Check | Result | +|---|---| +| Type check (`tsc --noEmit`) | passed | +| Lint on the changed files | passed | +| Format check (`prettier --check .`) | passed | +| `SectionHeading` tests | 5 passed | +| Whole unit-test run (`vitest run`) | 132 files, 1392 tests passed | + +One test assertion was corrected during the run: the rule holds the token as a CSS variable (`var(--slp-letter-spacings-caps)`), not the literal `0.22em`. The code was right; the assertion was changed to check the variable. + +Not part of this unit (phase-level Build and Test): prerender build, e2e tests, Lighthouse, and a visual check of every page that shows a `SectionHeading`, including the wrapping of the longest title (A2). + +## Extension compliance + +| Extension | Rule | Status | Note | +|---|---|---|---| +| Security Baseline | SECURITY-04 | Compliant | The new style is a generated CSS class; no inline style, no header change | +| Security Baseline | SECURITY-10 | N/A | No dependency change (`pnpm install --frozen-lockfile` only restored the worktree) | +| Security Baseline | other rules | N/A | Front-end style change; no inputs, storage, API or identity | +| Property-Based Testing | PBT-01..09 | N/A | No logic and no pure function added | +| Property-Based Testing | PBT-10 | Compliant | Example tests only, because there are no properties to check; existing property tests still pass | diff --git a/aidlc-docs/features/testimonials-redesign/construction/testimonials/code/code-summary.md b/aidlc-docs/features/testimonials-redesign/construction/testimonials/code/code-summary.md new file mode 100644 index 0000000..6d3f339 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/testimonials/code/code-summary.md @@ -0,0 +1,76 @@ +# 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 | diff --git a/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/business-logic-model.md b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/business-logic-model.md new file mode 100644 index 0000000..e5ade23 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/business-logic-model.md @@ -0,0 +1,84 @@ +# 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. diff --git a/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/business-rules.md b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/business-rules.md new file mode 100644 index 0000000..9511174 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/business-rules.md @@ -0,0 +1,91 @@ +# Business Rules: testimonials (unit 2) + +Rule numbers `BR-REV-nn` are the ones of `homepage-sections/construction/lieve-woorden`; `BR-TR-nn` are new in this feature. Requirement references are to `requirements.md`. + +## Rule table + +| ID | Rule | Status | Source | +|---|---|---|---| +| BR-REV-01 | Only valid reviews are shown; broken ones are skipped, and of two with the same id the first wins; the order stays | Kept | FR-TR-09 | +| BR-REV-02 | No valid review: the section is left out; one review: shown without controls and without counter | Kept (counter added to the "without controls" part) | FR-TR-09 | +| BR-REV-03 | The carousel is shown from two reviews on, one review per page | Kept | FR-TR-09 | +| BR-REV-04 | Navigation | **Replaced** by BR-TR-01 (no dots) | FR-TR-07 | +| BR-REV-05 | The carousel loops; the buttons are never disabled | Kept | FR-TR-09 | +| BR-REV-06 | A change slides horizontally; instant under `prefers-reduced-motion` | Kept, now also for swipes and keys (all through the carousel's `instant` flag) | FR-TR-08 | +| BR-REV-07 | Every slide has the height of the tallest one | Kept | FR-TR-09 | +| BR-REV-08 | Every manual change is announced once, politely, as "Review n van m"; nothing on load | Kept | FR-TR-09 | +| BR-REV-09 | Slides are named "Review n van m"; buttons "Vorige review" and "Volgende review" | Kept without the dot labels | FR-TR-06 | +| BR-REV-10 | Hidden slides are not readable or focusable | Kept | FR-TR-09 | +| BR-REV-11 | The quote is a `blockquote` with the names as its `figcaption` | Kept, **without** the decorative quotation mark | FR-TR-04 | +| BR-LZY-02 | The prerendered HTML holds the text of every shown review | Kept | FR-TR-13 | +| BR-TR-01 | The review changes only through the previous and next buttons, the left and right arrow keys while focus is in the control bar, a swipe, or a drag with the mouse. No timer, no pause control, no dots | New | FR-TR-07 | +| BR-TR-02 | The counter reads "X / Y" (current of total, from 1). It is visible text that screen readers skip (`aria-hidden`); the live region carries the announcement | New | FR-TR-06, NFR-TR-01 | +| BR-TR-03 | The crop of a photo comes from `normalizeImagePosition(testimonial.imagePosition)`; a missing or invalid value gives the centre | New | FR-TR-11 | +| BR-TR-04 | Layout switches at `lg` (1024 px). From `lg`: the photo (3:2) on the left overlaps the card on the right. Below `lg`: stacked, with the photo (4:3) at most 640 px wide and centred, and the card overlapping its bottom by 36 px | New (question 1 = A) | FR-TR-01, FR-TR-02 | +| BR-TR-05 | The card is at least 400 px high and grows with its text; all slides take the height of the tallest (BR-REV-07). Text is never cut off or shrunk to fit | New (question 2 = A) | FR-TR-01 | +| BR-TR-06 | There is no coloured block behind the photo; the card is the surface behind it | New (question 3 = A) | FR-TR-01 | +| BR-TR-07 | The card is always `paper.deep`; quote text `ink.soft`; shoot type `ink`; names `accent.deeper`; all at least 4.5:1 on the card | New | FR-TR-03, NFR-TR-01 | +| BR-TR-08 | Until the carousel has loaded the placeholder shows the longest review as a slide, and below `lg` also the height of the control bar, so nothing below moves | Changed (no sand-block padding) | FR-TR-13 | +| BR-TR-09 | The heading of the section uses the heading style of unit 1 (`SectionHeading`) | Kept from unit 1 | FR-TR-05 | + +## Decision flow: what is rendered + +```mermaid +graph TD + Start["Reviews from the content"] + Filter["visibleTestimonials"] + Count{"How many shown?"} + None["Render nothing"] + One["One TestimonialSlide, no controls"] + Many{"Section near the screen?"} + Placeholder["Placeholder: longest slide, others hidden"] + Carousel["Carousel with controls and counter"] + + Start --> Filter + Filter --> Count + Count -->|"none"| None + Count -->|"one"| One + Count -->|"two or more"| Many + Many -->|"no, or still loading"| Placeholder + Many -->|"yes, and loaded"| Carousel + + classDef step fill:#2196F3,stroke:#0d47a1,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 Start,Filter step; + class Count,Many decision; + class None,One,Placeholder,Carousel result; +``` + +Text alternative: the reviews are filtered; none renders nothing, one renders a single slide without controls, and two or more render the placeholder until the section is near the screen and the carousel has loaded. + +## Decision flow: normalising the crop position + +```mermaid +graph TD + Raw["Raw imagePosition"] + Present{"Is it a string?"} + Parse{"Two numbers with percent signs, separated by whitespace?"} + Range{"Both from 0 to 100?"} + Format["Write as X% Y% in shortest form"] + Centre["Use 50% 50%"] + + Raw --> Present + Present -->|"no"| Centre + Present -->|"yes"| Parse + Parse -->|"no"| Centre + Parse -->|"yes"| Range + Range -->|"no"| Centre + Range -->|"yes"| Format + + classDef step fill:#2196F3,stroke:#0d47a1,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 Raw step; + class Present,Parse,Range decision; + class Format,Centre result; +``` + +Text alternative: a raw value that is a string of two percentages from 0 to 100 is written in its shortest form; every other value gives the centre. diff --git a/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/domain-entities.md b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/domain-entities.md new file mode 100644 index 0000000..fd702be --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/domain-entities.md @@ -0,0 +1,77 @@ +# Domain Entities: testimonials (unit 2) + +## Entity relationships + +```mermaid +graph TD + Testimonial["Testimonial"] + ContentImage["ContentImage"] + ImagePosition["ImagePosition, normalised"] + ShownList["Shown reviews"] + Counter["Counter text"] + SlideLabel["Slide label"] + CarouselState["Carousel state, owned by Chakra"] + + Testimonial -->|"has one"| ContentImage + Testimonial -->|"may carry raw value for"| ImagePosition + Testimonial -->|"filtered into"| ShownList + ShownList -->|"sets the count of"| CarouselState + CarouselState -->|"index and count give"| Counter + CarouselState -->|"index and count give"| SlideLabel + + classDef entity fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000; + classDef value fill:#FF9800,stroke:#e65100,stroke-width:1px,color:#000; + classDef external fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000; + + class Testimonial,ContentImage,ShownList entity; + class ImagePosition,Counter,SlideLabel value; + class CarouselState external; +``` + +Text alternative: a Testimonial has one ContentImage and may carry a raw crop value that is normalised into an ImagePosition; the valid reviews form the shown list, which sets the count of Chakra's carousel state, and from that state's index and count come the counter text and the slide label (blue = entities, orange = derived values, purple = state owned by the library). + +## Testimonial (changed: one optional field) + +| Field | Type | Required | Notes | +|---|---|---|---| +| `id` | string | yes | Unique among shown reviews (first wins, BR-REV-01) | +| `shoot` | string | yes | Shoot type shown above the quote | +| `quote` | string | yes | Plain text without quotation marks; the design adds none | +| `author` | string | yes | Names under the quote | +| `image` | `ContentImage` | yes | `src`, `width` > 0, `height` > 0, `alt` | +| `imagePosition` | string | **no (new)** | Raw CSS `object-position` as two percentages, e.g. `"50% 42%"`. Never trusted as given: it is passed through `normalizeImagePosition` before it reaches a style | + +**Invariants** (`isValidTestimonial`, unchanged): `id`, `shoot`, `quote`, `author` and `image.src` are not blank; `image.width` and `image.height` are above zero. `imagePosition` is **not** part of validity: a missing, empty or garbled value never hides a review, it only falls back to the centre. + +Content values: trouwshoot `"50% 42%"`, newbornshoot not set (centre). + +## ImagePosition (derived value) + +The normalised crop position, always of the form `"X% Y%"`. + +| Property | Rule | +|---|---| +| Accepted input | Two numbers, each followed by `%`, separated by whitespace; optional surrounding whitespace; digits with an optional decimal part; no sign, no exponent | +| Range | Each number from 0 up to and including 100 | +| Output | `"X% Y%"` where X and Y are the numbers rounded to at most two decimals and written without trailing zeros (`"050.0% 42%"` becomes `"50% 42%"`; `"0.0000001%"` becomes `"0%"`, so no exponent form can appear), one space between. The range check is on the number as given (`"100.001%"` is out of range) | +| Fallback | Anything else (missing, empty, one number, no `%`, out of range, negative, extra parts, text): the centre, `"50% 50%"` (owner's answer A, question 4) | +| Idempotence | Normalising a normalised value gives the same value | + +## Counter text (derived value) + +`"X / Y"` with X the current review (counted from 1) and Y the number of reviews. + +| Property | Rule | +|---|---| +| Input | `index` (zero-based) and `count` (number of shown reviews) | +| Valid input | `count` is a whole number of at least 1 and `index` is a whole number from 0 up to `count - 1` | +| Output | `` `${index + 1} / ${count}` `` | +| Invalid input | Never throws and never reads wrong: a count below 1 or not a finite number counts as 1; an index outside the range, or not a finite number, is moved to the nearest end (0 or `count - 1`); fractions are cut off. The result always has 1 <= X <= Y | + +## Slide label (unchanged) + +`slideLabel(index, count)` gives `"Review n van m"` and names each slide and the announcement (BR-REV-08, BR-REV-09). The old dot labels `"Review n"` are removed together with the dots. + +## Carousel state + +Owned by Chakra's carousel (`page`, `pageSnapPoints`, loop, scroll position). The unit does not keep its own copy of the current review: the counter and the announcement read the carousel's `page` and the shown count. diff --git a/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/frontend-components.md b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/frontend-components.md new file mode 100644 index 0000000..3a29273 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/construction/testimonials/functional-design/frontend-components.md @@ -0,0 +1,132 @@ +# Frontend Components: testimonials (unit 2) + +Visual reference: the design canvas (desktop 1440 px, phone 390 px). Decisions of the owner after the canvas: tablet and phone share the stacked layout (question 1 = A), the card grows with its text (question 2 = A), no sand block (question 3 = A). + +## Component hierarchy + +```mermaid +graph TD + Route["routes/index.tsx"] + T["Testimonials"] + Section["PageSection tone alt"] + Heading["SectionHeading"] + Holder["Box with view observer"] + Placeholder["CarouselPlaceholder"] + Carousel["TestimonialCarousel, lazy"] + Slide["TestimonialSlide"] + Photo["DeferredImage with crop"] + Card["Card: shoot, quote, names"] + Controls["Control bar: prev, counter, next"] + Live["Live region"] + Lib["lib: visibleTestimonials, slideLabel, slideCounter, normalizeImagePosition"] + Recipe["carouselControl recipe"] + + Route --> T + T --> Section + Section --> Heading + Section --> Holder + Holder --> Placeholder + Holder --> Carousel + Placeholder --> Slide + Carousel --> Slide + Carousel --> Controls + Carousel --> Live + Slide --> Photo + Slide --> Card + Controls --> Recipe + Lib -.-> T + Lib -.-> Carousel + Lib -.-> Slide + + classDef root fill:#4CAF50,stroke:#2e7d32,stroke-width:1px,color:#000; + classDef ui fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000; + classDef logic fill:#9C27B0,stroke:#4a148c,stroke-width:1px,color:#000; + class Route root; + class T,Section,Heading,Holder,Placeholder,Carousel,Slide,Photo,Card,Controls,Live,Recipe ui; + class Lib logic; +``` + +Text alternative: the home route renders Testimonials in a PageSection with SectionHeading; a view-observing box shows either the placeholder or the lazy carousel, both made of TestimonialSlide (a cropped photo and a card), and the carousel adds the control bar and the live region; pure helpers feed all of them. + +## Testimonials (changed a little) + +- **Props**: unchanged, `{ content: HomeContent['testimonials']; testimonials: Testimonial[] }`. +- **Behaviour**: unchanged: `visibleTestimonials`; none gives `null`; one gives a single `TestimonialSlide`; two or more give the box with the view observer, the placeholder first and the lazy carousel once near the screen. +- **Section**: `PageSection` with `tone="alt"` (decision FR-TR-10), `data-testid="testimonials"`, centred `SectionHeading` with the unit 1 style. + +## TestimonialSlide (rebuilt) + +- **Props**: `{ testimonial: Testimonial }`. +- **Wrapper**: `data-testid="testimonial-{id}"`. + +### From `lg` (1024 px) + +One grid cell holds two stacked layers, so the row is as high as the higher one: + +| Part | Placement | +|---|---| +| Photo | Left, 57% of the width, 3:2, starts 40 px below the top of the cell, above the card | +| Card | Right, 56% of the width, at least 400 px high (`minH`), `paper.deep`, with a bottom margin of 66 px that reserves the room for the control bar (22 px gap plus 44 px bar) | +| Card content | Centred in the card; left padding of 25% of the slide width (a percentage padding on a grid item refers to the grid area, as in the canvas; it clears the 13% overlap with the photo) and 44 px on the right | + +The cell is therefore as high as the larger of "photo bottom" and "card plus the control room". The two overlap by about 13% of the width, as in the canvas. + +### Below `lg` + +A wrapper at most 640 px wide, centred. The photo is full width of the wrapper, 4:3; the card follows with a negative top margin of 36 px so it overlaps the bottom of the photo, with 72 px top padding so the text starts below the overlap and 28 px at the sides. Text centred. The control bar is below the card (see Controls). + +### Photo + +- `DeferredImage` (keeps the lazy loading, the width and height that reserve space, and the `noscript` twin) with `objectFit: cover`, `bg: paper.deep` until it loads, and `objectPosition` from `normalizeImagePosition(testimonial.imagePosition)`. +- No `FramedImage` and no coloured block (BR-TR-06). The source files stay 880 x 1100. + +### Card text + +| Element | Style | +|---|---| +| Shoot type | Heading font, uppercase, letter-spacing 0.2em, 21 px (19 px below `lg`), colour `ink` | +| Quote | `chakra.blockquote`, body font, weight 300, 17 px (16.5 px below `lg`), line-height 1.75, colour `ink.soft`, balanced wrapping (`text-wrap: pretty`) | +| Names | `chakra.figcaption`, small caps style (`textStyle="eyebrow"`), colour `accent.deeper`; the old "— " prefix is dropped | + +`figure` > `blockquote` + `figcaption` stays (BR-REV-11). No decorative quotation mark. Plain elements are used instead of Chakra's `Blockquote` for the same bundle-size reason as before. + +## TestimonialCarousel (changed) + +- Chakra `useCarousel` with `slideCount`, `loop`, `allowMouseDrag`, `translations.item = slideLabel`, `onPageChange` for the announcement, and `spacing` set to 0 (slides come directly after each other, as on the canvas). The old 4 rem spacing existed so the sand block of one photo never peeked into the next slide; without that block it is not needed. Code Generation checks that the next slide never shows at the edge. +- `Carousel.ItemGroup` keeps `aria-live="off"`; items stretch to equal height (BR-REV-07); no more `ps` and `pb` of 1.5 rem on the items. +- Touch and mouse: the carousel follows the finger and snaps. Under reduced motion the buttons, keys and indicators call the API with `instant`; the swipe snap is made instant by the existing reduced-motion CSS. +- **Control bar** (own markup, as before): previous button, counter, next button. + - From `lg`: placed at the bottom right of the carousel, aligned with the card column (width 56%, left padding 25%, right 44 px), content centred; it sits in the room reserved under the card. + - Below `lg`: below the slides, centred, 28 px under the card. + - Buttons: icon only (the existing Ant Design arrows, offline), no circle and no border, 44 px target, lighter on hover (opacity), the theme focus ring on keyboard focus. Names "Vorige review" and "Volgende review". Arrow keys on the bar work as before. + - Counter: `Text` with the heading font, 16 px, letter-spacing 0.08em, `ink.soft`, `aria-hidden`, content `slideCounter(carousel.page, count)`. + - The dots are removed. +- **Live region**: unchanged: empty on load, `slideLabel(page, count)` after a change. +- **Test ids**: `testimonials-prev`, `testimonials-next`, `testimonials-status`, new `testimonials-counter`; `testimonials-dot-{n}` is removed. + +## carouselControl recipe (changed) + +The `dot` variant is removed. The `arrow` variant loses its 48 px box with border: it becomes a 44 px square target without border or background, with `opacity` transition (hover lowers the opacity to 0.55, which lightens it; keyboard focus gets the theme's focus ring and is not dimmed, because opacity would also fade the ring). The recipe comment names the buttons under the testimonials only. + +## CarouselPlaceholder (changed) + +- Shows the longest review as a normal `TestimonialSlide` (no padding wrappers any more), the other reviews visually hidden, `aria-hidden` and `inert` (BR-LZY-02). +- Below `lg` it adds a spacer of the control bar's height plus its margin, with `data-requires-js` as before; from `lg` no spacer is needed, because the bar sits inside the room the slide already reserves. + +## Accessibility (NFR-TR-01) + +- The region is named by the h2; the carousel keeps its `aria-roledescription` and label; slides are named "Review n van m". +- Contrast on `paper.deep`: names `accent.deeper` (about 6.4:1), quote `ink.soft` (about 6.1:1), shoot type `ink` (higher). +- Targets of at least 44 px; the focus ring comes from the theme. +- Hidden slides stay inert (BR-REV-10); the counter is hidden from assistive technology and never read twice. +- Axe clean for the placeholder, the carousel and the single review. + +## Interaction flows + +- Visitor presses next, presses the right arrow key in the bar, or swipes left: the carousel moves one review forward, slides (or jumps under reduced motion), the counter changes to "2 / 2", the live region announces "Review 2 van 2". +- On the last review, next goes to the first (loop); on the first, previous goes to the last. +- No form, no API call and no persisted state in this unit. + +## Not in this unit + +Autoplay and pause (removed), dots (removed), changes outside the Testimonials folder other than the theme-free helpers, content, test helpers and `LAYOUT.md`. diff --git a/aidlc-docs/features/testimonials-redesign/inception/plans/execution-plan.md b/aidlc-docs/features/testimonials-redesign/inception/plans/execution-plan.md new file mode 100644 index 0000000..8229969 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/inception/plans/execution-plan.md @@ -0,0 +1,176 @@ +# Execution Plan + +## Detailed Analysis Summary + +### Transformation Scope +- **Transformation Type**: Single component area in one package (`web/`), plus one shared component that fans out to several pages +- **Primary Changes**: a new look and new behaviour for the "Lieve woorden" section (card over a landscape photo, counter instead of dots, no autoplay, horizontal slide), a new heading style in `SectionHeading`, and an optional `imagePosition` field in the content model +- **Related Components**: `Testimonials`, `TestimonialSlide`, `TestimonialCarousel`, `carouselControl` recipe, `SectionHeading` and its eight callers (`AboutBlock`, `ContactSection`, `IntroGallery`, `Pricing`, `Testimonials`, `InstagramGrid`, `AboutIntro`, `ShootPage`), `theme.ts` (text styles), `content/types.ts`, `content/testimonials.ts`, two new helpers in `web/src/lib`, `LAYOUT.md` + +### Change Impact Assessment +- **User-facing changes**: Yes. The testimonials look and behave differently; every `SectionHeading` on the site gets uppercase, letter-spaced titles +- **Structural changes**: No. Same components, same route, same lazy-loading pattern +- **Data model changes**: Yes, small: one optional field `imagePosition` on `Testimonial` +- **API changes**: No +- **NFR impact**: Yes, checks only: accessibility (contrast, axe), no hydration mismatch, Lighthouse targets must hold, titles must not break on phones + +### Component Relationships + +```mermaid +graph TD + Theme["theme.ts text styles"] + SH["SectionHeading"] + Callers["Seven other callers: home sections, about intro, shoot page"] + Test["Testimonials, slide and carousel"] + Content["Testimonial content and type"] + Helpers["lib helpers: slideCounter, normalizeImagePosition"] + Recipe["carouselControl recipe"] + Theme --> SH + SH --> Callers + SH --> Test + Content --> Test + Helpers --> Test + Recipe --> Test + classDef style1 fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef comp fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef data fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000; + class Theme,Recipe style1; + class SH,Callers,Test comp; + class Content,Helpers data; +``` + +Text alternative: the theme text styles feed SectionHeading, which is used by its callers and by Testimonials; Testimonials also uses the content, two new helpers and the carousel control recipe. + +| Component | Change type | Reason | Priority | +|---|---|---|---| +| `theme.ts` (new heading text style) | Minor | FR-TR-05 | Critical | +| `SectionHeading` and its eight callers | Minor | New style on every page that uses it; callers themselves do not change | Critical | +| `Testimonials`, `TestimonialSlide`, `TestimonialCarousel` | Major | New layout, controls, animation, placeholder | Critical | +| `carouselControl` recipe | Minor | Dots removed, arrows without circle | Important | +| `content/types.ts`, `content/testimonials.ts` | Minor | `imagePosition` | Important | +| `lib/slideCounter`, `lib/normalizeImagePosition` (new) | Minor | FR-TR-12, property tests | Important | +| `LAYOUT.md`, RE lines | Minor | FR-TR-14 | Optional | + +### Risk Assessment +- **Risk Level**: Medium. The carousel is the heaviest code on the page and sits behind a lazy-load placeholder whose height must match; the heading change reaches several pages and may wrap titles on phones +- **Rollback Complexity**: Easy. One branch, no deployment or data change +- **Testing Complexity**: Moderate. The existing tests (including prerender, hydration and axe tests) must be adjusted; swiping can not be tested in jsdom, so it needs a manual check in a real browser + +## Workflow Visualization + +```mermaid +flowchart TD + Start(["User Request"]) + + subgraph INCEPTION["🔵 INCEPTION PHASE"] + WD["Workspace Detection
COMPLETED"] + RE["Reverse Engineering
SKIP"] + RA["Requirements Analysis
COMPLETED"] + US["User Stories
SKIP"] + WP["Workflow Planning
IN PROGRESS"] + AD["Application Design
SKIP"] + UG["Units Generation
SKIP"] + end + + subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"] + FD1["Functional Design, unit 1
SKIP"] + CG1["Code Generation, unit 1
section heading
EXECUTE"] + FD2["Functional Design, unit 2
EXECUTE"] + CG2["Code Generation, unit 2
testimonials
EXECUTE"] + NFR["NFR Requirements, NFR Design,
Infrastructure Design
SKIP"] + BT["Build and Test
EXECUTE"] + end + + Start --> WD + WD --> RA + RA --> WP + WP --> CG1 + CG1 --> FD2 + FD2 --> CG2 + CG2 --> BT + BT --> End(["Complete"]) + + style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style CG1 fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style CG2 fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style FD2 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style AD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style FD1 fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style NFR fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000 + style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000 + style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + + linkStyle default stroke:#333,stroke-width:2px +``` + +Text alternative: after Workflow Planning, unit 1 (section heading) goes straight to Code Generation; unit 2 (testimonials) has Functional Design and then Code Generation; Build and Test closes the feature. Reverse Engineering, User Stories, Application Design, Units Generation, the NFR stages and Infrastructure Design are skipped; there is no Operations phase. + +## Units + +The two units are fixed here, so Units Generation is skipped. They do not depend on each other for logic, only for looks, so unit 1 goes first (small, and the testimonials heading then already has its final style). + +| Unit | Content | Requirements | +|---|---|---| +| 1. section-heading | New text style in `theme.ts`, used by `SectionHeading`; check the eight callers and every page that shows a `SectionHeading` (titles that wrap on a phone, tests and snapshots that name the old style) | FR-TR-05, A1, A2 | +| 2. testimonials | `imagePosition` in the content model, helpers `slideCounter` and `normalizeImagePosition` with property tests, new `TestimonialSlide` and `Testimonials` layout, controls and counter in `TestimonialCarousel` and the recipe, slide animation, placeholder height, tests, `LAYOUT.md` and RE lines | FR-TR-01..04, 06..14, NFR-TR-01..06 | + +## Phases to Execute + +### 🔵 INCEPTION PHASE +- [x] Workspace Detection (COMPLETED) +- [x] Reverse Engineering (SKIPPED) + - **Rationale**: shared artifacts exist; team agreement is no full refresh per feature. Only the lines about the testimonials and the heading are updated (FR-TR-14) +- [x] Requirements Analysis (COMPLETED) +- [x] User Stories (SKIPPED) + - **Rationale**: one type of visitor and concrete requirements from a reviewed design +- [x] Workflow Planning (IN PROGRESS) +- [ ] Application Design - SKIP + - **Rationale**: no new components or services; the two helpers are fully specified in FR-TR-12 and the layout decisions belong in Functional Design of unit 2 +- [ ] Units Generation - SKIP + - **Rationale**: the two units are fixed in this plan + +### 🟢 CONSTRUCTION PHASE +- [ ] Functional Design, unit 1 - SKIP + - **Rationale**: a style change with no logic; PBT-01 is N/A +- [ ] Functional Design, unit 2 - EXECUTE + - **Rationale**: layout geometry and overlap, how Chakra's carousel carries the slide animation, the placeholder height, the helpers and the testable properties (PBT-01) +- [ ] NFR Requirements - SKIP + - **Rationale**: the NFRs are in requirements.md; the PBT framework (`fast-check`) is already selected (PBT-09) +- [ ] NFR Design - SKIP + - **Rationale**: no new NFR patterns +- [ ] Infrastructure Design - SKIP + - **Rationale**: no infrastructure change +- [ ] Code Generation, unit 1 - EXECUTE (ALWAYS) +- [ ] Code Generation, unit 2 - EXECUTE (ALWAYS) +- [ ] Build and Test - EXECUTE (ALWAYS) + - **Rationale**: `pnpm check` (lint, types, tests, build, Lighthouse), a manual swipe check on a phone or in device mode, and a check of every page that shows a `SectionHeading` + +### 🟡 OPERATIONS PHASE +- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP + - **Rationale**: Operations Configuration = No (decided at Requirements Analysis) + +## Package Change Sequence + +Single package (`web/`). Order: unit 1 (heading), then unit 2 (testimonials), each with its own build and tests; Build and Test covers both together. + +## Estimated Timeline +- **Total Phases**: 5 stages still to run (Functional Design for unit 2, two Code Generation stages, Build and Test, plus this plan) +- **Estimated Duration**: about the size of the shoot-type pages feature; the carousel and the placeholder are the long part + +## Success Criteria +- **Primary Goal**: the testimonials match the approved canvas on desktop and phone, with no autoplay and no dots +- **Key Deliverables**: new `Testimonials` section, `SectionHeading` style, `imagePosition` field, two helpers with property tests, updated tests and `LAYOUT.md` +- **Quality Gates**: + - `pnpm check` green, Lighthouse targets not lowered + - No axe violations; contrast at least 4.5:1 + - Hydrated page equals prerendered HTML + - Security Baseline and PBT compliance summaries at each applicable stage + - Manual swipe check and a look at every page with a `SectionHeading` diff --git a/aidlc-docs/features/testimonials-redesign/inception/requirements/requirement-verification-questions.md b/aidlc-docs/features/testimonials-redesign/inception/requirements/requirement-verification-questions.md new file mode 100644 index 0000000..bf951d2 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/inception/requirements/requirement-verification-questions.md @@ -0,0 +1,76 @@ +# Vragen bij de requirements: testimonials-redesign + +Vul achter elke `[Answer]:` de letter van je keuze in. Past geen enkele optie, kies dan de laatste (Anders) en licht je keuze toe. Bij elke vraag staat welke optie ik aanbeveel en waarom. + +**Vaste uitgangspunten uit het ontwerp, hierover hoef je niets te beslissen:** + +- Foto links (landschap, 3:2) overlapt een kaart rechts; de tekst in de kaart is gecentreerd (shoot-naam in hoofdletters, citaat, naam). +- De kaart is altijd `paper.deep` (`#e8e0d5`); alleen de achtergrond van het blok eromheen wisselt (paper / paper.alt). +- Controls: pijlen zonder cirkel en een teller "X / Y". De bolletjes, het balkje, de pauzeknop en autoplay vervallen. +- De review wisselt alleen met de pijlen, de pijltjestoetsen of swipen (en slepen met de muis). Een wissel is een horizontale slide; bij `prefers-reduced-motion` direct, zonder animatie. +- Wat uit de homepage-sections-spec blijft gelden: de loop (BR-REV-05), gelijke hoogte (BR-REV-07), één nette aankondiging "Review n van m" (BR-REV-08), verborgen slides niet focusbaar (BR-REV-10), en de volledige tekst van elke review in de prerendered HTML (BR-LZY-02). +- Vervalt of verandert: BR-REV-04 (de bolletjes), BR-REV-09 (de labels "Review n" van de bolletjes) en de tests en testids van de bolletjes. + +## Vraag 1 + +De kop "LIEVE WOORDEN" staat in het ontwerp in gespatieerde hoofdletters (30 px, letter-spacing 0,22em, gecentreerd, zonder hairline). `SectionHeading` is nu gedeeld door alle homepage-secties. Waar moet de nieuwe kop gelden? + +- A) Alleen bij de testimonials, via een variant of prop op `SectionHeading`; de andere secties blijven zoals ze zijn (aanbevolen: het ontwerp is alleen voor deze sectie bekeken, en de andere koppen zijn niet getoetst) +- B) Bij alle homepage-secties: dan krijgt de hele homepage dezelfde kop (een grotere wijziging die ik apart zou moeten ontwerpen) +- C) De bestaande kop blijft; alleen de rest van de sectie verandert +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: B, daarna in de chat verfijnd met een vervolgvraag (`SectionHeading` staat ook in over-mij en de shoot-pagina's): overal waar `SectionHeading` staat. + +## Vraag 2 + +De achtergrond van het blok wisselt "om en om" met de blokken op de pagina. Nu staat de sectie vast op `tone="alt"` in `Testimonials.tsx`. Hoe bepalen we de tone? + +- A) Vast op `alt`, zoals nu; verandert de volgorde van de blokken, dan pas je de tone aan in één regel (aanbevolen: eenvoudig, en de tone is al een prop van `PageSection`) +- B) Een prop `tone` op `Testimonials`, die de homepage-route doorgeeft op basis van de plek van het blok, zodat het patroon vanzelf klopt als de volgorde verandert +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 3 + +De foto's in `testimonials.ts` zijn staand (880 × 1100, 4:5). Het ontwerp toont ze liggend (3:2), dus er wordt flink bijgesneden: bij de trouwring blijft de hand zichtbaar met de focus op 42% van de hoogte, bij de newborn-foto op het midden. Hoe regelen we welk deel zichtbaar blijft? + +- A) Een optioneel veld `imagePosition` (bijvoorbeeld `'50% 42%'`) per review in het contentmodel, dat de bijsnijdpositie bepaalt; zonder veld is het midden (aanbevolen: past bij de CMS die later komt, en de eigenaar kan het per foto bijstellen) +- B) Altijd het midden, zonder extra veld (eenvoudiger, maar de ring-foto verliest dan een deel van de hand) +- C) Liggende foto's aanleveren, zodat er niet bijgesneden hoeft te worden (nu geen nieuwe foto's beschikbaar: dat zou een vervolgtaak worden) +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 4: Beveiligingsextensies + +Moeten de beveiligingsregels als harde vereisten worden afgedwongen voor deze feature? (Bij de vorige features stond dit aan.) + +- A) Ja: dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten (aanbevolen voor productietoepassingen) +- B) Nee: sla alle BEVEILIGINGSREGELS over +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 5: Property-Based Testing + +Moeten de property-based testing (PBT) regels worden afgedwongen? De feature is vooral UI, maar er zijn pure functies die erbij horen (`visibleTestimonials`, `slideLabel`, en straks de teller "X / Y"). Bij de vorige features stond dit aan. + +- A) Ja: dwing alle PBT-regels af als blokkerende vereisten (aanbevolen voor projecten met bedrijfslogica of datatransformaties; hier vooral voor de pure helpers) +- B) Gedeeltelijk: dwing PBT-regels alleen af voor pure functies en serialisatie round-trips (past bij een feature die vooral UI is) +- C) Nee: sla alle PBT-regels over +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A + +## Vraag 6: Operations-fase + +Moet deze feature na de Construction-fase door de Operations-fase (deployment en monitoring opzetten)? Bij de vorige features was het antwoord nee, omdat de pipeline en de testomgeving al bestaan. + +- A) Ja: voer de Operations-fase uit na Construction (deployment + monitoring) +- B) Nee: stop na Build and Test (deployment en monitoring vallen buiten deze feature) (aanbevolen: er verandert niets aan de pipeline of de hosting) +- C) Nog niet zeker: vraag het opnieuw na de Construction-fase +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: B diff --git a/aidlc-docs/features/testimonials-redesign/inception/requirements/requirements.md b/aidlc-docs/features/testimonials-redesign/inception/requirements/requirements.md new file mode 100644 index 0000000..a86d469 --- /dev/null +++ b/aidlc-docs/features/testimonials-redesign/inception/requirements/requirements.md @@ -0,0 +1,97 @@ +# Requirements: testimonials-redesign + +## Intent analysis + +| Item | Value | +|---|---| +| User request | Make the "Lieve woorden" testimonials more elegant and closer to the style of the live site, keep the controls, no autoplay. Built on a design canvas (desktop and mobile) that the owner reviewed in several rounds. | +| Request type | Enhancement (new look and new behaviour of an existing component) | +| Scope | Multiple components: the Testimonials section, the shared `SectionHeading`, the content model and the theme | +| Complexity | Moderate: the carousel logic and a lazy-load placeholder exist and must keep working; the heading change reaches every page that uses `SectionHeading` | +| Depth | Standard | +| Design source | Design canvas (private). It is the visual reference; the numbers below are taken from it. | +| Questions | `requirement-verification-questions.md` (6 questions, all answered) | + +## Decisions from the questions + +| Q | Decision | +|---|---| +| 1 | The new heading style applies everywhere `SectionHeading` is used (homepage sections, over-mij intro, shoot pages, Instagram section): 8 usages in 8 components | +| 2 | The Testimonials section stays on `tone="alt"`; the card colour is constant | +| 3 | Optional `imagePosition` field per review sets the crop of the landscape photo | +| 4 | Security Baseline extension: enforced | +| 5 | Property-Based Testing extension: enforced (full) | +| 6 | No Operations phase | + +## Functional requirements + +Replaces and extends the homepage-sections spec for the testimonials (BR-REV-01..11). Rules that are not mentioned stay as they are. + +| ID | Requirement | +|---|---| +| FR-TR-01 | **Desktop layout (from `lg`)**: a landscape photo (3:2) on the left, about 57% of the content width, overlaps a card on the right (about 56% of the width, 400 px high). The photo starts 40 px below the top of the card. The card runs to the right edge of the content area. | +| FR-TR-02 | **Phone and tablet layout (below `lg`)**: heading, then the photo at full width (4:3), then the card overlapping the bottom of the photo by 36 px, with the controls centred below it. | +| FR-TR-03 | **Card**: always `paper.deep` (`#e8e0d5`), on both `paper` and `paper.alt` sections. The text in it is centred: shoot type, quote, names. | +| FR-TR-04 | **Typography**: shoot type in the heading font, uppercase, letter-spacing 0.2em, 21 px (19 px on phones); quote in the body font, weight 300, 17 px (16.5 px on phones), line-height 1.75, colour `ink.soft`; names uppercase, small, letter-spaced, colour `accent.deeper`. The large decorative quotation mark is removed (BR-REV-11 changes: the quote stays a `blockquote` with the names as its `figcaption`, without a decorative mark). | +| FR-TR-05 | **Section heading**: a new text style used by `SectionHeading`: heading font, uppercase, letter-spacing 0.22em, 30 px from `md` and 26 px below (as on the canvas), centred. The hairline of the canvas is not part of it. The eyebrow and lead of `SectionHeading` keep their style. The accessible text of the heading does not change (the case is only CSS). | +| FR-TR-06 | **Controls**: previous and next as icon-only buttons without a circle or border, each with a 44 px target, with the visible counter "X / Y" between them (X is the current review, Y the number of reviews, both counted from 1). Hover lightens the icon. The buttons keep their names "Vorige review" and "Volgende review". The arrow keys still work while focus is in the control bar (BR-REV-04). | +| FR-TR-07 | **Navigation**: only the buttons, the arrow keys, swiping and dragging with the mouse change the review. No autoplay, no pause control and no dots. BR-REV-04 and BR-REV-09 (the dots and their labels) no longer apply. | +| FR-TR-08 | **Animation**: a change slides the whole slide (card, photo and text) horizontally; a swipe follows the finger. Under `prefers-reduced-motion` the change is immediate (BR-REV-06 stays). | +| FR-TR-09 | **Kept**: the loop at both ends (BR-REV-05), equal height of all slides (BR-REV-07), one polite announcement "Review n van m" for each manual change and nothing on load (BR-REV-08), hidden slides not focusable or readable (BR-REV-10), a single review without controls, and the section left out when no review is valid (BR-REV-01/02). | +| FR-TR-10 | **Section tone**: `Testimonials` stays on `tone="alt"`. Only the block background alternates; the card does not change with it. | +| FR-TR-11 | **Crop**: `Testimonial` gets an optional `imagePosition` (a CSS `object-position` of two percentages, e.g. `"50% 42%"`). Missing or invalid values fall back to the centre (`"50% 50%"`). The content sets `"50% 42%"` for the trouwshoot photo and the centre for the newborn photo. A review without the field stays valid (`isValidTestimonial` does not change). | +| FR-TR-12 | **Counter and position helpers**: two small pure functions in `web/src/lib`: one returns the text "X / Y" for an index and a count, one normalises an `imagePosition` value to a safe `"N% N%"` string. | +| FR-TR-13 | **Lazy-load placeholder**: until the carousel has loaded (and in the prerendered HTML) the placeholder shows the longest review laid out exactly like a slide plus the height of the controls, so nothing below moves when the carousel takes its place. The other reviews stay in the page, visually hidden, aria-hidden and inert (BR-LZY-02). | +| FR-TR-14 | **Documentation**: `LAYOUT.md` (the Testimonials block) is updated following `.ai/layout-conventions.md`, and the lines of the reverse-engineering artifacts about the testimonials and the heading are updated. | + +## Non-functional requirements + +| ID | Requirement | +|---|---| +| NFR-TR-01 | **Accessibility**: no axe violations in the prerendered HTML and in the hydrated page. Text contrast at least 4.5:1: names `accent.deeper` on `paper.deep`, quote `ink.soft` on `paper.deep`. Targets at least 44 px. The counter is not read out twice (it is visible text; the live region carries the announcement). | +| NFR-TR-02 | **Performance**: the carousel code stays lazy-loaded, away from the hero. The Lighthouse targets in `web/lighthouserc.cjs` (for example `/` at 0.85) do not go down. Photos are not made larger: the existing 880 x 1100 files are used. | +| NFR-TR-03 | **Motion**: no animation under `prefers-reduced-motion`; no motion that starts by itself (no autoplay). | +| NFR-TR-04 | **Compatibility**: the hydrated page must match the prerendered HTML (no hydration mismatch) and must work without a visible jump in the placeholder swap. | +| NFR-TR-05 | **Dependencies**: no new runtime dependencies. | +| NFR-TR-06 | **Quality**: `pnpm check` (lint, types, tests, build, Lighthouse) is green. Tests: the tests and test ids of the dots are replaced; new example tests for the counter, the crop position and the controls; property tests for the pure helpers (see below). | + +## Extension rules: applicability + +**Security Baseline (enforced).** The change is front-end only: no new inputs, endpoints, storage or dependencies. + +| Rule | Status | Note | +|---|---|---| +| SECURITY-01, 02, 03, 05, 06, 07, 08, 11, 12, 14 | N/A | No data store, network intermediary, API, identity or authentication in this change | +| SECURITY-04 | Compliant (to verify) | Headers and CSP are untouched; the new styles must not need `unsafe-inline`; `imagePosition` is normalised before it reaches a style (FR-TR-12) | +| SECURITY-09 | N/A | No deployment change | +| SECURITY-10 | Compliant (to verify) | No new dependencies; the lock file stays committed | +| SECURITY-13 | N/A | No external scripts or deserialisation | +| SECURITY-15 | Compliant (to verify) | Invalid `imagePosition` and invalid reviews fail safe (fallback or skipped), never thrown | + +**Property-Based Testing (enforced, full).** Framework: `fast-check` (already a dependency, with shared arbitraries in `web/src/test`). Candidate properties, to be detailed in Functional Design (PBT-01): + +| Function | Category | Property | +|---|---|---| +| `slideCounter(index, count)` | Invariant | Always reads "X / Y" with 1 <= X <= Y | +| `normalizeImagePosition(value)` | Invariant, idempotence | The result is always two percentages between 0 and 100; normalising twice gives the same result as once; any invalid input gives the centre | +| `visibleTestimonials` (unchanged) | Invariant | Existing properties keep passing | +| `slideLabel` (unchanged) | Invariant | Existing properties keep passing | + +Example tests keep pinning the key scenarios (PBT-10): "1 / 2", "2 / 2", the ring photo at `50% 42%`. + +## Assumptions to check at review + +| ID | Assumption | +|---|---| +| A1 | `SectionHeading` has 8 usages; five more h2 elements use the `sectionTitle` text style directly (`CallToAction`, `PackageBlock`, `ShootBlock`, `ShootPage` x2, `StoryBlocks`). The new heading style is a separate text style used by `SectionHeading` only, so these five keep the current style. If you want them to match, say so and the style is applied there too. | +| A2 | Uppercase and letter-spacing are applied in CSS, so long titles may wrap. The longest is "Lifestyle fotograaf met een passie voor storytelling" (52 characters, `AboutBlock`, maximum width 620 px): estimated at about three lines on desktop and four on a phone. This is checked during Build and Test on every page that uses `SectionHeading`; no text is shortened in unit 1. | +| A3 | The pixel values from the canvas become relative units in the theme (the card's 56% and the photo's 57% of the content width). The overlap and offsets stay as in the canvas. | +| A4 | Chakra's carousel stays the base (paging, snapping, looping, swiping, hidden slides); only the slide content, the controls and the animation change. | + +## Out of scope + +- Autoplay, a pause control and the dots (removed on purpose). +- New or landscape photos, and any change to the review texts. +- The CMS that will deliver the reviews later (the new field is optional so it fits). +- Other text styles that are not `SectionHeading` (see A1). +- Deployment and monitoring (no Operations phase). diff --git a/web/src/components/SectionHeading/SectionHeading.test.tsx b/web/src/components/SectionHeading/SectionHeading.test.tsx index 0b456d9..4faacc6 100644 --- a/web/src/components/SectionHeading/SectionHeading.test.tsx +++ b/web/src/components/SectionHeading/SectionHeading.test.tsx @@ -1,6 +1,8 @@ import { screen } from '@testing-library/react'; import { describe, expect, it } from 'vitest'; +import CallToAction from '@/components/CallToAction/CallToAction'; import { axeResults } from '@/test/axe'; +import { cssRulesFor } from '@/test/cssRules'; import { renderWithProviders } from '@/test/renderWithProviders'; import SectionHeading from './SectionHeading'; @@ -50,4 +52,34 @@ describe('SectionHeading', () => { ).toHaveAttribute('id', 'about-title'); expect(screen.getByText('Over mij')).toBeInTheDocument(); }); + + it('shows the title in letter-spaced capitals without changing its text', async () => { + const title = 'Lifestyle fotograaf met een passie voor storytelling'; + await renderWithProviders(); + + const heading = screen.getByRole('heading', { level: 2 }); + // The case is CSS only: the text and the accessible name stay as given + expect(heading).toHaveTextContent(title); + expect(heading).toHaveAccessibleName(title); + + const rules = cssRulesFor(heading).join(); + expect(rules).toContain('text-transform: uppercase'); + // The wide spacing is the shared "caps" token (0.22em) + expect(rules).toContain( + 'letter-spacing: var(--slp-letter-spacings-caps)', + ); + }); + + it('does not give the plain section titles of other blocks the new style', async () => { + await renderWithProviders( + + Actie + , + ); + + const rules = cssRulesFor( + screen.getByRole('heading', { level: 2 }), + ).join(); + expect(rules).not.toContain('text-transform: uppercase'); + }); }); diff --git a/web/src/components/SectionHeading/SectionHeading.tsx b/web/src/components/SectionHeading/SectionHeading.tsx index 28d4ed8..0a019bd 100644 --- a/web/src/components/SectionHeading/SectionHeading.tsx +++ b/web/src/components/SectionHeading/SectionHeading.tsx @@ -16,8 +16,9 @@ type SectionHeadingProps = { focusable?: boolean; }; -// Heading block of a homepage section (design .section__head): optional -// small label, the h2 and an optional intro sentence. +// Heading block of a section (design .section__head): optional small label, +// the h2 in letter-spaced capitals (the case is only CSS, the text stays as +// given) and an optional intro sentence. export default function SectionHeading({ id, title, @@ -40,7 +41,7 @@ export default function SectionHeading({ {title} diff --git a/web/src/components/home/Testimonials/TestimonialCarousel.tsx b/web/src/components/home/Testimonials/TestimonialCarousel.tsx index b145499..0ddf4db 100644 --- a/web/src/components/home/Testimonials/TestimonialCarousel.tsx +++ b/web/src/components/home/Testimonials/TestimonialCarousel.tsx @@ -4,6 +4,7 @@ import { Carousel, chakra, Flex, + Text, useCarousel, useMediaQuery, useRecipe, @@ -13,14 +14,16 @@ import { Icon } from '@iconify/react/offline'; import leftOutlined from '@iconify-icons/ant-design/left-outlined'; import rightOutlined from '@iconify-icons/ant-design/right-outlined'; import type { Testimonial } from '@/content/types'; +import { slideCounter } from '@/lib/slideCounter'; import { slideLabel } from '@/lib/slideLabel'; import TestimonialSlide from './TestimonialSlide'; // The carousel itself. Chakra's carousel (Zag) handles paging, snapping, -// looping, swiping and hiding off-screen slides. The buttons, dots and arrow -// keys are our own: the built-in ones always scroll smoothly from -// JavaScript, which CSS cannot switch off for visitors who prefer reduced -// motion; ours pass the API's `instant` flag instead (BR-REV-06). +// looping, swiping and hiding off-screen slides. The buttons and arrow keys +// are our own: the built-in ones always scroll smoothly from JavaScript, +// which CSS cannot switch off for visitors who prefer reduced motion; ours +// pass the API's `instant` flag instead (BR-REV-06). The review only changes +// by those buttons and keys or by swiping: nothing moves by itself. export default function TestimonialCarousel({ testimonials, }: { @@ -34,8 +37,8 @@ export default function TestimonialCarousel({ slideCount: count, loop: true, allowMouseDrag: true, - // Room between slides, so the next one never peeks in - spacing: '4rem', + // The slides follow each other directly, as in the design + spacing: '0px', translations: { item: slideLabel }, onPageChange: ({ page }) => setAnnouncement(slideLabel(page, count)), }); @@ -50,30 +53,39 @@ export default function TestimonialCarousel({ aria-label="Reviews" aria-roledescription="carrousel" gap={0} + // The control bar lies over the bottom right of the slides + position="relative" + maxW={{ lg: '1120px' }} + mx="auto" > {/* Our own live region announces changes, so the item group's built-in one is switched off to avoid hearing it twice */} {testimonials.map((testimonial, index) => ( - // The photo's sand block sticks out 1.5rem to the left - // and below (FramedImage); the item group clips - // everything outside a slide, so each slide makes room - - + + ))} + {/* From lg the bar sits in the room under the card, in line with + the card's text; below lg it follows the slides, centred. + The 25% and 44px match the card's padding. */} { if (event.key === 'ArrowLeft') previous(); else if (event.key === 'ArrowRight') next(); @@ -90,23 +102,19 @@ export default function TestimonialCarousel({ > - - {testimonials.map((testimonial, index) => ( - - carousel.scrollTo(index, reducedMotion) - } - /> - ))} - + {/* Visible text only: the live region below says it aloud */} + cssRulesFor(screen.getByRole('img')).join(); + describe('TestimonialSlide', () => { it('shows the photo, shoot, quote and names', async () => { const { container } = await renderWithProviders( @@ -23,13 +28,58 @@ describe('TestimonialSlide', () => { expect(await axeResults(container)).toHaveNoViolations(); }); - it('keeps the decorative quotation mark away from assistive technology', async () => { + it('shows the names as they are, without a leading dash', async () => { const { container } = await renderWithProviders( , ); - const mark = [ - ...container.querySelectorAll('[aria-hidden="true"]'), - ].find((element) => element.textContent === '“'); - expect(mark).toBeDefined(); + const caption = container.querySelector('figcaption'); + expect(caption).toHaveTextContent(review.author); + expect(cssRulesFor(caption!).join()).not.toContain('content'); + }); + + it('has no decorative quotation mark', async () => { + const { container } = await renderWithProviders( + , + ); + expect(container.textContent).not.toMatch(/[“”]/); + expect( + [...container.querySelectorAll('[aria-hidden="true"]')].filter( + (element) => element.textContent?.trim(), + ), + ).toEqual([]); + }); + + it('crops the photo at the position of the review', async () => { + await renderWithProviders(); + expect(cropOf()).toContain('object-position: 50% 42%'); + }); + + it('crops at the centre when the review has no position or a bad one', async () => { + const { unmount } = await renderWithProviders( + , + ); + expect(cropOf()).toContain('object-position: 50% 50%'); + unmount(); + + await renderWithProviders( + , + ); + expect(cropOf()).toContain('object-position: 50% 50%'); + }); + + it('lays the card on paper.deep with no coloured block behind the photo', async () => { + const { container } = await renderWithProviders( + , + ); + const card = container.querySelector('figure')!.parentElement!; + expect(cssRulesFor(card).join()).toContain( + 'background: var(--slp-colors-paper-deep)', + ); + // No leftover sand block: the old frame drew it with a ::before + expect( + cssRulesFor(screen.getByRole('img').parentElement!).join(), + ).not.toContain('::before'); }); }); diff --git a/web/src/components/home/Testimonials/TestimonialSlide.tsx b/web/src/components/home/Testimonials/TestimonialSlide.tsx index bd30a50..6d46368 100644 --- a/web/src/components/home/Testimonials/TestimonialSlide.tsx +++ b/web/src/components/home/Testimonials/TestimonialSlide.tsx @@ -1,73 +1,123 @@ -import { Box, chakra, Grid, Text } from '@chakra-ui/react'; -import Eyebrow from '@/components/Eyebrow/Eyebrow'; -import FramedImage from '@/components/FramedImage/FramedImage'; +import { Box, chakra, Text } from '@chakra-ui/react'; +import DeferredImage from '@/components/DeferredImage/DeferredImage'; import type { Testimonial } from '@/content/types'; +import { normalizeImagePosition } from '@/lib/normalizeImagePosition'; type TestimonialSlideProps = { testimonial: Testimonial; + // The slide sits in a carousel whose control bar needs room under the + // card (from `lg` the bar lies inside the slide's own height) + withControls?: boolean; + // Load the photo straight away: for a slide in the carousel, whose + // off-screen slides are clipped and would never come into view on their + // own, so the next photo would still be loading while it slides in + near?: boolean; }; -// One review (design .testimonial): framed photo next to a large quotation -// mark, the shoot type, the quote and the names. Stacked below `lg`, with -// the photo centred. +// Room under the card for the control bar: a 22px gap and the 44px buttons +const CONTROL_ROOM = '66px'; + +// One review (design .testimonial): a landscape photo that overlaps a card +// with the shoot type, the quote and the names, centred. From `lg` the photo +// lies over the left of the card; below `lg` it is stacked, at most 640px +// wide and centred, with the card overlapping the bottom of the photo. export default function TestimonialSlide({ testimonial, + withControls = false, + near, }: TestimonialSlideProps) { return ( - - {/* Kept small and centred on phones and tablets, so the photo - does not fill the screen above the quote */} - + - - - {testimonial.shoot} + {/* Plain elements, not Chakra's Blockquote: its slot recipe would pull shared code into the chunk the hero waits for */} - - {/* Smaller than the design's clamp(1.35rem, 2.2vw, - 1.75rem) at the owner's request: 18.4px to 22px */} - + + {testimonial.shoot} + + {testimonial.quote} {testimonial.author} - + ); } diff --git a/web/src/components/home/Testimonials/Testimonials.test.tsx b/web/src/components/home/Testimonials/Testimonials.test.tsx index 797ff64..9a9f28f 100644 --- a/web/src/components/home/Testimonials/Testimonials.test.tsx +++ b/web/src/components/home/Testimonials/Testimonials.test.tsx @@ -17,6 +17,8 @@ import Testimonials from './Testimonials'; const carousel = vi.hoisted(() => ({ props: undefined as UseCarouselProps | undefined, calls: [] as Array<[string, ...unknown[]]>, + // Zag can not move in jsdom: a test sets the page the counter should show + page: undefined as number | undefined, })); vi.mock('@chakra-ui/react', async (importOriginal) => { @@ -34,6 +36,7 @@ vi.mock('@chakra-ui/react', async (importOriginal) => { }; return { ...api, + page: carousel.page ?? api.page, scrollNext: record('scrollNext', api.scrollNext), scrollPrev: record('scrollPrev', api.scrollPrev), scrollTo: record('scrollTo', api.scrollTo), @@ -44,6 +47,7 @@ vi.mock('@chakra-ui/react', async (importOriginal) => { beforeEach(() => { carousel.calls = []; + carousel.page = undefined; vi.stubGlobal('IntersectionObserver', FakeIntersectionObserver); Element.prototype.scrollTo = () => {}; }); @@ -79,6 +83,7 @@ async function renderTestimonials(items = testimonials) { } const status = () => screen.getByTestId('testimonials-status'); +const counter = () => screen.getByTestId('testimonials-counter'); const button = (name: string) => screen.getByRole('button', { name }); const preferReducedMotion = () => @@ -130,8 +135,6 @@ describe('Testimonials', () => { }); expect(button('Vorige review')).toBeInTheDocument(); expect(button('Volgende review')).toBeInTheDocument(); - expect(button('Review 1')).toHaveAttribute('aria-current', 'true'); - expect(button('Review 2')).not.toHaveAttribute('aria-current'); const slides = container.querySelectorAll( '[aria-roledescription="slide"]', ); @@ -157,42 +160,73 @@ describe('Testimonials', () => { expect(status()).toHaveTextContent('Review 2 van 2'); }); - it('moves with the arrows, the dots and the arrow keys', async () => { + it('moves with the arrows and the arrow keys', async () => { await renderTestimonials(); fireEvent.click(button('Volgende review')); fireEvent.click(button('Vorige review')); - fireEvent.click(button('Review 2')); - fireEvent.keyDown(button('Review 2'), { key: 'ArrowRight' }); - fireEvent.keyDown(button('Review 2'), { key: 'ArrowLeft' }); - fireEvent.keyDown(button('Review 2'), { key: 'Enter' }); + fireEvent.keyDown(button('Vorige review'), { key: 'ArrowRight' }); + fireEvent.keyDown(button('Volgende review'), { key: 'ArrowLeft' }); + fireEvent.keyDown(button('Volgende review'), { key: 'Enter' }); expect(carousel.calls).toEqual([ ['scrollNext', false], ['scrollPrev', false], - ['scrollTo', 1, false], ['scrollNext', false], ['scrollPrev', false], ]); }); + it('has no dots: only the two arrows and the counter', async () => { + await renderTestimonials(); + expect(screen.getAllByRole('button').map((b) => b.ariaLabel)).toEqual([ + 'Vorige review', + 'Volgende review', + ]); + expect(screen.queryByTestId('testimonials-dot-1')).toBeNull(); + }); + + it('shows the counter as "X / Y" and keeps it away from assistive technology', async () => { + await renderTestimonials(); + expect(counter()).toHaveTextContent('1 / 2'); + expect(counter()).toHaveAttribute('aria-hidden', 'true'); + + carousel.page = 1; + act(() => { + carousel.props?.onPageChange?.({ page: 1, pageSnapPoint: 0 }); + }); + expect(counter()).toHaveTextContent('2 / 2'); + // The announcement says the same thing aloud + expect(status()).toHaveTextContent('Review 2 van 2'); + }); + + it('does not move by itself', async () => { + await renderTestimonials(); + expect(carousel.props).not.toHaveProperty('autoplay'); + await new Promise((resolve) => setTimeout(resolve, 100)); + expect(carousel.calls).toEqual([]); + expect(status()).toHaveTextContent(''); + expect( + screen.queryByRole('button', { name: /paus|afspel/i }), + ).toBeNull(); + }); + it('scrolls instantly for visitors who prefer reduced motion', async () => { preferReducedMotion(); await renderTestimonials(); fireEvent.click(button('Volgende review')); - fireEvent.click(button('Review 1')); - fireEvent.keyDown(button('Review 1'), { key: 'ArrowLeft' }); + fireEvent.keyDown(button('Vorige review'), { key: 'ArrowLeft' }); expect(carousel.calls).toEqual([ ['scrollNext', true], - ['scrollTo', 0, true], ['scrollPrev', true], ]); }); - it('shows a single review without carousel controls', async () => { + it('shows a single review without carousel controls or counter', async () => { await renderTestimonials([testimonials[0]]); expect( screen.getByTestId(`testimonial-${testimonials[0].id}`), ).toBeInTheDocument(); expect(screen.queryByRole('button')).toBeNull(); + expect(screen.queryByTestId('testimonials-counter')).toBeNull(); }); it('leaves the section out when no review is valid', async () => { diff --git a/web/src/components/home/Testimonials/Testimonials.tsx b/web/src/components/home/Testimonials/Testimonials.tsx index 4d318fc..730b8ad 100644 --- a/web/src/components/home/Testimonials/Testimonials.tsx +++ b/web/src/components/home/Testimonials/Testimonials.tsx @@ -68,13 +68,15 @@ export default function Testimonials({ } // Stands in for the carousel until it has loaded: the longest review laid -// out exactly like a slide (same padding), plus the controls' height. That -// makes it as tall as the carousel at every screen width, so nothing below -// moves when the carousel takes its place, not even during a scroll to -// #contact that passes this section while it loads. The other reviews are in -// the page too, visually hidden, so the prerendered HTML holds every review -// text for search engines (BR-LZY-02). They are aria-hidden and inert, so -// assistive technology reads each review once, in the carousel. +// out exactly like a slide, plus the room for the controls. From `lg` that +// room is part of the slide; below `lg` the control bar follows the slides, so +// a spacer of its height is added. That makes it as tall as the carousel at +// every screen width, so nothing below moves when the carousel takes its +// place, not even during a scroll to #contact that passes this section while +// it loads. The other reviews are in the page too, visually hidden, so the +// prerendered HTML holds every review text for search engines (BR-LZY-02). +// They are aria-hidden and inert, so assistive technology reads each review +// once, in the carousel. function CarouselPlaceholder({ testimonials, }: { @@ -84,10 +86,8 @@ function CarouselPlaceholder({ b.quote.length > a.quote.length ? b : a, ); return ( - - - - + + {testimonials .filter((testimonial) => testimonial !== longest) .map((testimonial) => ( @@ -97,8 +97,13 @@ function CarouselPlaceholder({ ))} - {/* The control bar: 48px buttons below the same margin */} - + {/* Below lg the control bar: 44px buttons under a 28px margin */} + ); } diff --git a/web/src/content/testimonials.ts b/web/src/content/testimonials.ts index e805613..1602a09 100644 --- a/web/src/content/testimonials.ts +++ b/web/src/content/testimonials.ts @@ -18,6 +18,8 @@ const testimonials: Testimonial[] = [ width: 880, height: 1100, }, + // The rings sit a little above the middle of the photo + imagePosition: '50% 42%', }, { id: 'demi-kevin', diff --git a/web/src/content/types.ts b/web/src/content/types.ts index 1c836f3..0c19ab7 100644 --- a/web/src/content/types.ts +++ b/web/src/content/types.ts @@ -130,13 +130,18 @@ export interface ShootType { } // A review from a client ("Lieve woorden"). quote is plain text without -// quotation marks; the design adds a decorative one. +// quotation marks; the design shows none either. export interface Testimonial { id: string; shoot: string; quote: string; author: string; image: ContentImage; + // Which part of the photo stays visible in the landscape crop, as a CSS + // object-position of two percentages, e.g. '50% 42%'. Optional and not + // trusted: it goes through normalizeImagePosition, which falls back to + // the centre, and it has no say in whether the review is shown. + imagePosition?: string; } // Content of the homepage sections below the hero diff --git a/web/src/lib/normalizeImagePosition.test.ts b/web/src/lib/normalizeImagePosition.test.ts new file mode 100644 index 0000000..376d7e9 --- /dev/null +++ b/web/src/lib/normalizeImagePosition.test.ts @@ -0,0 +1,95 @@ +import fc from 'fast-check'; +import { describe, expect, it } from 'vitest'; +import { + imagePositionAny, + imagePositionInvalid, + imagePositionValid, +} from '../test/arbitraries'; +import { normalizeImagePosition } from './normalizeImagePosition'; + +const CENTRE = '50% 50%'; + +// The shape every result has: two numbers with at most two decimals +const SHAPE = /^(\d+(?:\.\d{1,2})?)% (\d+(?:\.\d{1,2})?)%$/; + +describe('normalizeImagePosition (examples)', () => { + it('keeps a good value', () => { + expect(normalizeImagePosition('50% 42%')).toBe('50% 42%'); + expect(normalizeImagePosition('0% 100%')).toBe('0% 100%'); + }); + + it('writes the numbers tidily and ignores extra whitespace', () => { + expect(normalizeImagePosition('050.0% 42%')).toBe('50% 42%'); + expect(normalizeImagePosition(' 12.50% 7.25% ')).toBe( + '12.5% 7.25%', + ); + expect(normalizeImagePosition('50%\t42%')).toBe('50% 42%'); + }); + + it('rounds tiny values instead of writing an exponent', () => { + expect(normalizeImagePosition('0.0000001% 50%')).toBe('0% 50%'); + }); + + it('falls back to the centre for anything else', () => { + for (const bad of [ + '120% 40%', + '50 42', + '50%', + '-5% 10%', + '1e1% 5%', + '', + 'center', + ]) { + expect(normalizeImagePosition(bad)).toBe(CENTRE); + } + expect(normalizeImagePosition(undefined)).toBe(CENTRE); + expect(normalizeImagePosition(null)).toBe(CENTRE); + expect(normalizeImagePosition(42)).toBe(CENTRE); + }); +}); + +describe('normalizeImagePosition (properties)', () => { + it('always gives two numbers from 0 to 100 (invariant)', () => { + fc.assert( + fc.property(imagePositionAny, (value) => { + const match = SHAPE.exec(normalizeImagePosition(value)); + expect(match).not.toBeNull(); + const [x, y] = [Number(match?.[1]), Number(match?.[2])]; + expect(x >= 0 && x <= 100 && y >= 0 && y <= 100).toBe(true); + }), + ); + }); + + it('does not change a value that is already normalised (idempotence)', () => { + fc.assert( + fc.property(imagePositionAny, (value) => { + const once = normalizeImagePosition(value); + expect(normalizeImagePosition(once)).toBe(once); + }), + ); + }); + + it('reads any layout of whitespace as the plain form (round-trip)', () => { + fc.assert( + fc.property(imagePositionValid, ({ x, y, text }) => { + expect(normalizeImagePosition(text)).toBe(`${x}% ${y}%`); + }), + ); + }); + + it('gives exactly the centre for a value that is not acceptable (easy verification)', () => { + fc.assert( + fc.property(imagePositionInvalid, (value) => { + expect(normalizeImagePosition(value)).toBe(CENTRE); + }), + ); + }); + + it('never throws, whatever it is given', () => { + fc.assert( + fc.property(fc.anything(), (value) => { + expect(typeof normalizeImagePosition(value)).toBe('string'); + }), + ); + }); +}); diff --git a/web/src/lib/normalizeImagePosition.ts b/web/src/lib/normalizeImagePosition.ts new file mode 100644 index 0000000..38dce73 --- /dev/null +++ b/web/src/lib/normalizeImagePosition.ts @@ -0,0 +1,23 @@ +// The centre of a photo, used whenever a crop position can not be trusted +const CENTRE = '50% 50%'; + +// Two numbers with a percent sign, separated by whitespace. Digits and an +// optional decimal part only: no sign, no exponent. +const NUMBER = '(\\d{1,3}(?:\\.\\d+)?)'; +const POSITION = new RegExp(`^${NUMBER}%\\s+${NUMBER}%$`); + +// Rounded to two decimals: enough for a crop, and it keeps tiny values from +// being written in exponent form, which would not read back +const tidy = (n: number) => Math.round(n * 100) / 100; + +// The crop position of a photo (CSS object-position) from content that a CMS +// may deliver later: "X% Y%" with X and Y from 0 to 100, or the centre when +// the value is missing or not exactly that. Never throws (FR-TR-11/12). +export function normalizeImagePosition(value: unknown): string { + if (typeof value !== 'string') return CENTRE; + const match = POSITION.exec(value.trim()); + if (!match) return CENTRE; + const [x, y] = [Number(match[1]), Number(match[2])]; + if (x > 100 || y > 100) return CENTRE; + return `${tidy(x)}% ${tidy(y)}%`; +} diff --git a/web/src/lib/slideCounter.test.ts b/web/src/lib/slideCounter.test.ts new file mode 100644 index 0000000..b089165 --- /dev/null +++ b/web/src/lib/slideCounter.test.ts @@ -0,0 +1,80 @@ +import fc from 'fast-check'; +import { describe, expect, it } from 'vitest'; +import { slideCounter } from './slideCounter'; + +// A position within a carousel: 1 to 20 slides, index within range +const position = fc + .integer({ min: 1, max: 20 }) + .chain((count) => + fc + .integer({ min: 0, max: count - 1 }) + .map((index) => ({ index, count })), + ); + +// Any number at all, including the odd ones +const anyNumber = fc.oneof( + fc.integer(), + fc.double(), + fc.constantFrom( + Number.NaN, + Infinity, + -Infinity, + 0, + -0, + 1.5, + Number.MAX_VALUE, + ), +); + +describe('slideCounter (examples)', () => { + it('counts from one', () => { + expect(slideCounter(0, 2)).toBe('1 / 2'); + expect(slideCounter(1, 2)).toBe('2 / 2'); + expect(slideCounter(4, 12)).toBe('5 / 12'); + }); + + it('stays within the range for odd input', () => { + expect(slideCounter(5, 2)).toBe('2 / 2'); + expect(slideCounter(-3, 2)).toBe('1 / 2'); + expect(slideCounter(0, 0)).toBe('1 / 1'); + expect(slideCounter(Number.NaN, 3)).toBe('1 / 3'); + expect(slideCounter(1, Number.NaN)).toBe('1 / 1'); + expect(slideCounter(1.9, 3)).toBe('2 / 3'); + }); +}); + +describe('slideCounter (properties)', () => { + it('always reads "X / Y" with 1 <= X <= Y, for any numbers (invariant)', () => { + fc.assert( + fc.property(anyNumber, anyNumber, (index, count) => { + const match = /^(\d+) \/ (\d+)$/.exec( + slideCounter(index, count), + ); + expect(match).not.toBeNull(); + const [x, y] = [Number(match?.[1]), Number(match?.[2])]; + expect(x >= 1 && x <= y).toBe(true); + }), + ); + }); + + it('gives back its numbers for a valid position (round-trip)', () => { + fc.assert( + fc.property(position, ({ index, count }) => { + const [, x, y] = + /^(\d+) \/ (\d+)$/.exec(slideCounter(index, count)) ?? []; + expect(Number(x)).toBe(index + 1); + expect(Number(y)).toBe(count); + }), + ); + }); + + it('equals the plain template for a valid position (oracle)', () => { + fc.assert( + fc.property(position, ({ index, count }) => { + expect(slideCounter(index, count)).toBe( + `${index + 1} / ${count}`, + ); + }), + ); + }); +}); diff --git a/web/src/lib/slideCounter.ts b/web/src/lib/slideCounter.ts new file mode 100644 index 0000000..a1ff8c9 --- /dev/null +++ b/web/src/lib/slideCounter.ts @@ -0,0 +1,13 @@ +// The visible counter under the testimonials, e.g. "2 / 3": the current +// review (counted from 1) out of the total. index is zero-based. Odd input +// is made safe instead of thrown at: a total below 1 or not a finite number +// counts as 1, and an index outside the range moves to the nearest end, so +// the result always reads X / Y with 1 <= X <= Y (FR-TR-12). +export function slideCounter(index: number, count: number): string { + const total = Number.isFinite(count) + ? Math.min(Math.max(1, Math.trunc(count)), Number.MAX_SAFE_INTEGER) + : 1; + const current = Number.isFinite(index) ? Math.trunc(index) : 0; + const position = Math.min(Math.max(current, 0), total - 1); + return `${position + 1} / ${total}`; +} diff --git a/web/src/lib/visibleTestimonials.test.ts b/web/src/lib/visibleTestimonials.test.ts index eb59508..e52206f 100644 --- a/web/src/lib/visibleTestimonials.test.ts +++ b/web/src/lib/visibleTestimonials.test.ts @@ -1,7 +1,12 @@ import fc from 'fast-check'; import { describe, expect, it } from 'vitest'; import testimonials from '../content/testimonials'; -import { anyTestimonial, uniqueTestimonials } from '../test/arbitraries'; +import type { Testimonial } from '../content/types'; +import { + anyTestimonial, + imagePositionAny, + uniqueTestimonials, +} from '../test/arbitraries'; import { isValidTestimonial, visibleTestimonials } from './visibleTestimonials'; const valid = testimonials[0]; @@ -63,6 +68,31 @@ describe('visibleTestimonials', () => { ); }); + it('does not let the crop position decide what is shown (invariant)', () => { + const ids = (items: Testimonial[]) => + visibleTestimonials(items).map((item) => item.id); + fc.assert( + fc.property( + fc.array(anyTestimonial), + fc.array(imagePositionAny, { minLength: 1, maxLength: 5 }), + (input, positions) => { + const withOther = input.map((item, index) => ({ + ...item, + imagePosition: positions[index % positions.length] as + string | undefined, + })); + const withNone = input.map((item) => { + const copy = { ...item }; + delete copy.imagePosition; + return copy; + }); + expect(ids(withOther)).toEqual(ids(input)); + expect(ids(withNone)).toEqual(ids(input)); + }, + ), + ); + }); + it('returns valid, unique reviews unchanged (oracle)', () => { fc.assert( fc.property(uniqueTestimonials, (input) => { diff --git a/web/src/recipes/carouselControl.ts b/web/src/recipes/carouselControl.ts index c65ac7f..d59e100 100644 --- a/web/src/recipes/carouselControl.ts +++ b/web/src/recipes/carouselControl.ts @@ -1,8 +1,8 @@ import { defineRecipe } from '@chakra-ui/react'; -// Buttons under a carousel on a light background (design .testimonials__arrow -// and .testimonials__dot): square arrows with a hairline, and dots with a -// 44px hit area around a small visible circle. +// The previous and next buttons under the testimonials (design +// .testimonials__arrow): just the arrow, with no circle or border, in a 44px +// target. Hovering lightens it; keyboard focus gets the theme's focus ring. const carouselControlRecipe = defineRecipe({ className: 'carousel-control', base: { @@ -18,34 +18,11 @@ const carouselControlRecipe = defineRecipe({ variants: { kind: { arrow: { - w: '48px', - h: '48px', - borderWidth: '1px', - borderColor: 'line', - fontSize: '1.1rem', - transitionProperty: 'border-color, background', - _hover: { borderColor: 'ink', bg: 'paper' }, - _focusVisible: { borderColor: 'ink', bg: 'paper' }, - }, - dot: { - position: 'relative', w: '44px', h: '44px', - _after: { - content: '""', - position: 'absolute', - top: '50%', - left: '50%', - w: '8px', - h: '8px', - borderWidth: '1px', - borderColor: 'accent.deep', - rounded: 'full', - transform: 'translate(-50%, -50%)', - transitionProperty: 'background', - transitionDuration: 'interaction', - }, - '&[aria-current="true"]::after': { bg: 'accent.deep' }, + fontSize: '1.15rem', + transitionProperty: 'opacity', + _hover: { opacity: 0.55 }, }, }, }, diff --git a/web/src/test/arbitraries.ts b/web/src/test/arbitraries.ts index 0bf6e6c..bd22e07 100644 --- a/web/src/test/arbitraries.ts +++ b/web/src/test/arbitraries.ts @@ -228,17 +228,89 @@ export const uniqueShootTypes = fc.uniqueArray(shootType, { maxLength: 5, }); -// A review that meets every invariant -export const testimonial: fc.Arbitrary = fc.record({ - id: fc.oneof( - fc.constantFrom('majella-mark', 'demi-kevin'), - fc.stringMatching(/^[a-z0-9-]{1,16}$/), +// A crop position the way content may write it: two percentages from 0 to +// 100 (whole or with up to two decimals) with any whitespace around and +// between. x and y are the numbers, text is how they are written. +export const imagePositionValid = fc + .tuple( + fc.integer({ min: 0, max: 10000 }), + fc.integer({ min: 0, max: 10000 }), + fc.constantFrom('', ' ', '\t', '\n '), + fc.constantFrom(' ', ' ', '\t', ' \n '), + fc.constantFrom('', ' ', '\t'), + ) + .map(([hundredthsX, hundredthsY, before, between, after]) => { + const [x, y] = [hundredthsX / 100, hundredthsY / 100]; + return { + x, + y, + text: `${before}${x}%${between}${y}%${after}`, + }; + }); + +// Crop positions that are not acceptable: out of range, one part, no percent +// sign, a sign or exponent, extra parts, other text and non-strings +export const imagePositionInvalid: fc.Arbitrary = fc.oneof( + fc + .tuple( + fc.integer({ min: 10001, max: 99999 }), + fc.integer({ min: 0, max: 10000 }), + ) + .map(([big, small]) => `${big / 100}% ${small / 100}%`), + fc + .tuple( + fc.integer({ min: 0, max: 10000 }), + fc.integer({ min: 10001, max: 99999 }), + ) + .map(([small, big]) => `${small / 100}% ${big / 100}%`), + fc.constantFrom( + '', + ' ', + '50%', + '50 42', + '50% 42', + '50 42%', + '-5% 10%', + '+5% 10%', + '1e1% 5%', + '50% 42% 10%', + '50%42%', + 'center', + 'top left', + '50.% 42%', + '.5% 42%', ), - shoot: nonBlank, - quote: nonBlank, - author: nonBlank, - image, -}); + fc.constantFrom(undefined, null, 50, true, {}, ['50% 42%']), +); + +// Anything content might hold in imagePosition: good and bad +export const imagePositionAny: fc.Arbitrary = fc.oneof( + imagePositionValid.map(({ text }) => text), + imagePositionInvalid, + fc.string(), +); + +// The raw text of a crop position as a review field: valid, garbled or odd +const imagePositionText = fc.oneof( + imagePositionValid.map(({ text }) => text), + fc.string(), +); + +// A review that meets every invariant, with or without a crop position +export const testimonial: fc.Arbitrary = fc.record( + { + id: fc.oneof( + fc.constantFrom('majella-mark', 'demi-kevin'), + fc.stringMatching(/^[a-z0-9-]{1,16}$/), + ), + shoot: nonBlank, + quote: nonBlank, + author: nonBlank, + image, + imagePosition: imagePositionText, + }, + { requiredKeys: ['id', 'shoot', 'quote', 'author', 'image'] }, +); // Valid reviews with unique ids export const uniqueTestimonials = fc.uniqueArray(testimonial, { @@ -249,18 +321,22 @@ export const uniqueTestimonials = fc.uniqueArray(testimonial, { // Valid and broken reviews mixed, as a CMS might deliver them export const anyTestimonial: fc.Arbitrary = fc.oneof( testimonial, - fc.record({ - id: fc.oneof(fc.constantFrom('majella-mark', '', ' '), fc.string()), - shoot: fc.oneof(nonBlank, fc.constantFrom('', ' ')), - quote: fc.oneof(nonBlank, fc.constantFrom('', ' ')), - author: fc.oneof(nonBlank, fc.constantFrom('', ' ')), - image: fc.record({ - src: fc.oneof(fc.constant(''), fc.constant('/a.jpg')), - alt: fc.string({ maxLength: 10 }), - width: fc.integer({ min: -1, max: 10 }), - height: fc.integer({ min: -1, max: 10 }), - }), - }), + fc.record( + { + id: fc.oneof(fc.constantFrom('majella-mark', '', ' '), fc.string()), + shoot: fc.oneof(nonBlank, fc.constantFrom('', ' ')), + quote: fc.oneof(nonBlank, fc.constantFrom('', ' ')), + author: fc.oneof(nonBlank, fc.constantFrom('', ' ')), + image: fc.record({ + src: fc.oneof(fc.constant(''), fc.constant('/a.jpg')), + alt: fc.string({ maxLength: 10 }), + width: fc.integer({ min: -1, max: 10 }), + height: fc.integer({ min: -1, max: 10 }), + }), + imagePosition: imagePositionText, + }, + { requiredKeys: ['id', 'shoot', 'quote', 'author', 'image'] }, + ), ); // Shoot values as the form offers them for the live packages diff --git a/web/src/theme.ts b/web/src/theme.ts index 6b02b10..2542842 100644 --- a/web/src/theme.ts +++ b/web/src/theme.ts @@ -197,7 +197,19 @@ const config = defineConfig({ lineHeight: '1', }, }, - // The h2 of a homepage section (SectionHeading); smaller than the + // The h2 of a section block (SectionHeading): letter-spaced + // capitals, as on the live site. 26px on phones, 30px from md. + sectionHeading: { + value: { + fontFamily: 'heading', + fontSize: { base: '1.625rem', md: '1.875rem' }, + lineHeight: '1.15', + letterSpacing: 'caps', + textTransform: 'uppercase', + }, + }, + // Plain h2 in blocks that do not use SectionHeading (call to + // action, packages, shoot and story blocks); smaller than the // design's 2.5rem at the owner's request, 30px at every width sectionTitle: { value: {