Files
SluijsensandClaude Sonnet 5.5 7a5e713b69
Continuous Integration / check (pull_request) Successful in 1m45s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 8m44s
Continuous Integration / deploy-production (pull_request) Skipped
Adds the AI-DLC documents of the testimonials redesign
Requirements, execution plan, functional design, code summaries, build and test results and the audit log; the reverse-engineering notes and the feature registry are updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-06 01:24:15 +01:00

109 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API Documentation
## REST APIs
None. There is no back-end yet (`api/` is empty). The static design README anticipates these endpoints on a .NET API:
- `POST /api/contact` — contact form; the design README names the payload `{ naam, email, onderwerp, bericht }`, the code sends `{ naam, email, shoot, bericht }` (homepage-sections turned `onderwerp` into the shoot choice); maps to a C# `ContactRequest` record
- `/api/pages`, `/api/portfolio`, `/api/packages` — CMS content
## Internal APIs
### Routes (TanStack Router, file-based)
| Path | File | Head | Component | Indexed |
|------|------|------|-----------|---------|
| (root) | `routes/__root.tsx` | `siteHead(siteContent)` | `AppShell` | — |
| `/` | `routes/index.tsx` | `pageHead('/')` | `Hero` + six home sections; search `?pakket=` | yes |
| `/over-mij` | `routes/over-mij.tsx` | `pageHead('/over-mij')` + `AboutPage` JSON-LD | `PageIntro`, `AboutIntro`, `StorySection` ×2, `PhotoDuo`, `LinkButton` | yes |
| `/portfolio` | `routes/portfolio.tsx` | `pageHead('/portfolio')` + `ImageGallery` JSON-LD; search `?shoot=` (`ShootTypeId`) | `PageIntro`, `PortfolioGallery`, `InstagramGrid` | yes |
| `/soorten-fotoshoots` | `routes/soorten-fotoshoots/index.tsx` | `pageHead('/soorten-fotoshoots')` + `WebPage` JSON-LD via `StructuredData` (`webPage()` + `shootServices()`; Service `@id` `…/soorten-fotoshoots/<id>#service` per D2) | `PageIntro`, `shoots/ShootList` (5× `ShootBlock`), `CallToAction`, `RichParagraph`, `LinkButton` | yes |
| `/soorten-fotoshoots/<id>` (newborn, zwangerschap, gezin, loveshoot, portret) | `routes/soorten-fotoshoots/<id>.tsx` | `pageHead('/soorten-fotoshoots/<id>')` with its own `ogImage` (`/og-<id>.jpg`, 1200 × 630, unit 2); JSON-LD via `StructuredData` (`shootPageGraph`: `WebPage` with the shoot's Service, `FAQPage` when there are questions) | `shoots/ShootPage` (intro, story blocks, process timeline, photo mosaic when there are at least two photos, FAQ when there are questions, package block, closing call to action), `NotFound` when `shootPageView` returns `undefined` | yes |
| `/contact` | `routes/contact.tsx` | `pageHead(...)` | `PageIntro` placeholder | no |
| `/privacyverklaring` | `routes/privacyverklaring.tsx` | `pageHead(...)` | `PageIntro` placeholder | no |
| (not found) | — | — | `NotFound` | — |
### seo.ts / sitePages.ts / sitemap.ts
- `pageHead(path: RoutePath)` → `{ meta, links }` (title, description, robots noindex if not indexed, OG tags, canonical)
- `siteHead(content: SiteContent)` → `{ meta, scripts }` (OG basics, JSON-LD ProfessionalService)
- `preloadImage(image, { media? })` → `HeadLink` (high-priority image preload link; prerendering display fallbacks)
- `canonicalUrl(path, base?)`, `jsonLdScript(data)`, `structuredDataScript(data)`, `professionalService(content)` (with `@id` `businessId` and `founder` → `personId`), `person(content, site, image)`, `aboutPage(path, content, site)`
- `sitePages: Record<RoutePath, PageMeta>`, `pageList(pages)`
- `sitemapXml(...)` — used by `config/sitemapPlugin.ts`
- Shoot pages (unit 1): `shootServiceId(id)` (`…/soorten-fotoshoots/<id>#service`), `shootService(shoot, site, pkg?)` (Service, `offers` only with `pkg`), `breadcrumbList(items)`, `faqPage(path, items)` (`undefined` without items), `shootPageGraph(view, site)` (WebPage + optional FAQPage); `shootServices` builds the overview list with `shootService`
### Components (props)
- `AppShell()`, `NavigationBar()`, `BackToTop()`, `NotFound()` — no props
- `MobileNav({ id, open, groupOpen, pathname, dispatch })`, `NavLink(RouterLink props & { sectionCurrent? })`, `NavSubmenu({ item, id, open, pathname, transparent, toggleRef, dispatch })` (desktop panel), `MobileNavGroup({ item, id, open, pathname, dispatch })`, `ChevronIcon()`
- `Footer({ content: SiteContent })`, `FooterColumn({ title, children })`, `FooterLink(LinkProps)`
- `Hero({ content: HeroContent, socials: SocialLink[] })`, `HeroArrows({ onPrev, onNext })`, `HeroPauseButton({ stopped, onToggle })`, `HeroSocials({ socials })`
- `PageIntro({ title, eyebrow?, children? })` — renders the page's only h1
- `PageSection({ labelledBy, id?, tone?: 'paper' | 'alt', width?: 'default' | 'narrow' | 'full', spacing?: 'default' | 'tight' | 'flushTop', 'data-testid'?, children })` (was `HomeSection`)
- `MediaText({ image, aspectRatio, priority?, reverse?, frameColor?, 'data-testid'?, children })` — framed photo next to a text column; `reverse` puts the photo right from `lg`, `frameColor` colours the block behind it (default `sand`)
- `CallToAction({ title, titleId, lead?, 'data-testid'?, children })` — closing block of a page: h2, lead, action, on `paper.alt`
- `RichParagraph({ paragraph: RichText })` — paragraph with inline links (moved from `about/`)
- `Eyebrow(TextProps & { as?: 'p' | 'span' | 'h2' | 'h3' | 'h4' })` — accent label, optionally a heading
- `SectionHeading({ id, title, eyebrow?, lead?, align?: 'center' | 'start', spacing?: 'default' | 'compact', focusable? })` — renders an h2
- `FramedImage({ image: ContentImage, aspectRatio })`, `DeferredImage(ImageProps & { image, near? })` (also renders a `<noscript>` twin; prerendering display fallbacks), `Reveal(BoxProps & { delay? })` (visible in the HTML; hidden after hydration only when wholly below the viewport)
- `IntroGallery({ content })`, `AboutBlock({ content })`, `Pricing({ content, packages })`, `PriceCard(...)`, `Testimonials({ content, testimonials })`, `ContactSection({ content, packages, enabled, email, pakket? })`, `InstagramGrid({ content: InstagramContent, profileUrl })` (shared, `components/InstagramGrid/`)
- `ContactForm(...)`, `ContactFormGate({ enabled, email, ... })`
- `PhotoDuo({ photos: [ContentImage, ContentImage], label, 'data-testid'? })`
- `PortfolioGrid({ items: GalleryItem[], eagerFirstRow = true, onOpen(index), onIntent?(), 'data-testid'? })`, `Lightbox({ items, index: number | null, onIndexChange, onClose, label?, finalFocusEl? })` (default export, lazy-loadable), `FilterBar({ options: FilterOption[], value, onChange, label })`
- `about/AboutIntro({ content })`, `about/StorySection({ content, titleId, tone?, spacing?, children? })`, `shoots/ShootList({ shoots, packages, portfolioShoots })` (types that link to the portfolio), `shoots/ShootBlock({ shoot, packages, reverse, priority, portfolioLink })`, `portfolio/PortfolioGallery({ photos, shootTypes, shoot, onShootChange })`
- `StatusPage({ title, children, actions? })`, `ErrorPage({ error, reset })`
- `LinkButton(RouterLink props & { variant?: 'outline' | 'accent' | 'light' })`
- `UmamiAnalytics({ hostname? })`
### Hooks
- `useHeroSlider(count)` → slider state, controls, handlers, `HeroAnnouncement` (swipe via `useSwipe`, wrap via `wrapIndex`)
- `useSwipe({ onPrev, onNext, enabled? })` → `{ onTouchStart, onTouchEnd }` (threshold and direction from `lib/swipeDirection`)
- `useScrolledPast(getThreshold)` → boolean (stable `getThreshold` required)
- `useRouteFocus()` — focuses `<main>` after navigation
- `useDismiss(ref, active, onDismiss(reason: 'escape' | 'outside'))` — document-level Escape and outside pointer down, listeners only while `active` (unit 3)
- `useInView({ rootMargin, skip })` → `{ ref, inView }`; `usePageLoaded()` → boolean; `useReveal()` → `{ ref, visible, animated }` (layout effect, visible by default); `lib/revealPhase.ts` (`startsHidden`, `nextRevealPhase`); `lib/firstRow.ts` (`GRID_COLUMNS`, `firstRow`, `firstRowPreloads`)
### Pure helpers (`lib/`)
- `emailAddress({ user, domain }): string | null`
- `visibleSocials(socials): SocialLink[]` — only valid https links
- `copyrightLine(year): string`
- `slidesToLoad(active, count): number[]`
- `backToTopThreshold(viewportHeight): number`
- `slideLabel`, `formatPrice`, `bookLabel`, `visiblePackages`, `visibleTestimonials`, `packageFromSearch`, `shootOptions`, `mailSubject`/`mailtoLink`, `validateField`/`validateContact`, `isLikelySpam`, `toContactPayload`, `contactFormReducer`
- Portfolio (`lib/portfolioFilters.ts`): `isShootTypeId`, `shootTypesWithPhotos(shootTypes, photos)`, `shootFromSearch(value, available)`, `filterPhotos(photos, shoot)`, `filterOptions(shootTypes, allLabel)`, `toGalleryItems(photos, shootTypes)`, `photoCountLabel(n)`; `seo.ts`: `galleryImages(photos)`
- 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
- `monitoringFor(hostname): Monitoring | null`, `startSentry(hostname?)`, `reportError(error)`
## Data Models
### SiteContent (`content/types.ts`)
- **Fields**: `footerIntro: string`, `socials: SocialLink[]`, `email: EmailAddress`, `contactForm: { enabled: boolean }`
### ContentImage
- **Fields**: `src`, `alt`, `width`, `height` (intrinsic size, reserves space)
### HomeContent
- **Fields**: `intro`, `about` (`eyebrow`, `title`, `paragraphs[]`, `image`, `link: { label, to: RoutePath }`), `pricing`, `testimonials`, `contact`
### InstagramContent
- **Fields**: `title`, `handle`, `photos: ContentImage[]` (the intro photos followed by the review photos, `instagramContent.ts`)
### LinkTarget / InlineLink / RichText
- **Fields**: `{ to: RoutePath; hash? }`; `InlineLink` adds `text`; `RichText = (string | InlineLink)[]`
### PortfolioContent / PortfolioPhoto
- **Fields**: `intro` (eyebrow, title, text), `photos: PortfolioPhoto[]` — `{ id, shootType: ShootTypeId, thumb: ContentImage (800 px wide), full: ImageSource (1600 px long side) }`
### GalleryItem / FilterOption
- **Fields**: `{ id, thumb, full, caption? }` / `{ id, label }` (generic, for the gallery blocks)
### 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`, `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
### EmailAddress
- **Fields**: `user`, `domain` — assembled only in the browser; invalid parts → hidden
### HeroContent
- **Fields**: `title`, `tagline`, `cta: { label, to }`, `slides: { id, src, alt }[]`
### NavItem (`navigation.ts`)
- **Fields**: `to: RoutePath`, `label: string`, `children?: readonly NavItem[]` (one level; `hasChildren(item)` is true only for a non-empty list; the shoot pages are the children of `/soorten-fotoshoots`)
### PageMeta (`sitePages.ts`)
- **Fields**: `title`, `description`, `indexed`, `ogImage?`