Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/inception/application-design/services.md
T
SluijsensandClaude Opus 5.5 b5b7f3b3db Adds application design for the front-end shell feature
Component boundaries, interfaces, services and dependencies for the
shell: footer, back-to-top, skip link, status pages, page intro,
shared RouterLink, content folder and navigation module. Includes the
answered design questions and the revised site content requirement.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 23:20:41 +02:00

35 lines
2.6 KiB
Markdown

# Services — frontend-shell
There is no back-end or service layer in this SPA. The cross-cutting "services" the shell relies on are configuration-level and listed here with how they are orchestrated.
## Routing service (TanStack Router)
- **Configured in**: `main.tsx` (`createRouter`) and `routes/__root.tsx` (`createRootRoute`)
- **Responsibilities**:
- File-based route tree, including the four new placeholder routes.
- **Scroll restoration** (`scrollRestoration: true`): a new navigation starts at the top, and back/forward restores the previous position (FR-08).
- **Not found**: the root route's `notFoundComponent: NotFound`. For an unknown URL, the root component (`AppShell`) keeps rendering and `NotFound` appears in its `<Outlet>`, so the shell stays visible. Verified in `@tanstack/react-router` `Match.js`: a global not-found renders through the root match's `Outlet`.
- **Errors**: `defaultErrorComponent: ErrorPage` on the router, plus `errorComponent: ErrorPage` on the root.
- An error in a page route is caught at that page's match, inside the shell.
- An error in the shell itself falls back to the root's boundary and renders `ErrorPage` without the shell. This is a deliberate fail-safe (SECURITY-15).
## Head management service
- **Configured in**: `seo.ts` and each route's `head`; rendered by `HeadContent` in the root layout
- **Responsibilities**:
- Per-page title and description via `pageHead`; site-wide Open Graph tags via `siteHead`.
- The 404 page sets its own title plus `robots: noindex`. A global not-found has no route of its own whose `head` could do this, so the mechanism is settled in Functional Design.
## Content provisioning
- **Today**: static modules in `content/` (`siteContent`, `heroContent`)
- **Orchestration** (application design Q3 = A):
- `AppShell` imports `siteContent` and passes it to `Footer`.
- The home route passes `heroContent` and `siteContent.socials` to `Hero`.
- Components never import content themselves.
- **Later**: the import points (`AppShell`, the home route) are replaced by route loaders or API calls. The components and types stay the same.
## Scroll state
- `useScrolledPast` is the one scroll-listening primitive (passive listener). It is used by `NavigationBar` (150px threshold) and `BackToTop` (60% of the viewport).
## Theme service (Chakra system)
- `theme.ts` with `createSystem(defaultConfig, config)`
- New and overridden recipes are merged into Chakra's default config. Components consume them through `Link variant="subtle"`, `SkipNavLink`, `useRecipe({ key: 'iconControl' })` and `LinkButton`.