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>
35 lines
2.6 KiB
Markdown
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`.
|