Files
AndreaSlopFotografie/aidlc-docs/_shared/reverse-engineering/api-documentation.md
T
SluijsensandClaude Opus 5.5 18bf0311ef Adds the shared gallery building blocks
A masonry photo grid that keeps the reading order (pure CSS, no measuring
in the browser), an accessible lightbox on Chakra's Dialog with wrap-around
browsing, keys, swipe and preloading, and a filter bar of toggle buttons.
They work on generic gallery items, so other pages can use them. The swipe
logic moves out of the hero into a shared hook; the hero behaves as before.
The rules behind them live in pure helpers with property-based tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 23:22:43 +01:00

96 lines
7.8 KiB
Markdown
Raw 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(...)` | `PageIntro` placeholder | no |
| `/soorten-fotoshoots` | `routes/soorten-fotoshoots.tsx` | `pageHead('/soorten-fotoshoots')` + `WebPage` JSON-LD (`webPage()` + `shootServices()`) | `PageIntro`, `shoots/ShootList` (5× `ShootBlock`), `CallToAction`, `RichParagraph`, `LinkButton` | 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)
- `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`
### Components (props)
- `AppShell()`, `NavigationBar()`, `BackToTop()`, `NotFound()` — no props
- `MobileNav({ id, open, onClose })`, `NavLink(RouterLink props)`
- `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? })`, `Reveal(BoxProps & { delay? })`
- `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[], eagerCount = 3, 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, portfolioLive })`, `shoots/ShootBlock({ shoot, packages, reverse, priority, portfolioLive })`
- `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
- `useInView({ rootMargin, skip })` → `{ ref, inView }`; `usePageLoaded()` → boolean; `useReveal()` → `{ ref, visible }`
### 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`
- 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`)
### 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)[]`
### 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`
### 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`
### PageMeta (`sitePages.ts`)
- **Fields**: `title`, `description`, `indexed`, `ogImage?`