4e14152758
- Persistent ShellComponent hosts the router-outlet so header/footer mount once (no re-mount flash); pages nest under a shell route. page-shell is now content-only; page-layout removed. - Native withViewTransitions() cross-fades only the routed content (chrome gets stable view-transition-names); respects prefers-reduced-motion. - package.json overrides pin patched transitive dev/build deps: npm audit 16 (3 high/9 mod/4 low) -> 5 low; shipped app stays at 0 (npm audit --omit=dev). No Angular downgrade, no breaking Babel 8 bump. jsdom 28 -> 29. - README: page-transitions section + honest dependency-security note. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# BIG-register Self-Service Portal — Atomic Design POC
|
|
|
|
A small Angular app that shows how **atomic design** makes a frontend cheap to build,
|
|
reuse and extend. The domain is the **BIG-register** self-service portal (the Dutch
|
|
register of healthcare professionals, run by CIBG). It looks like an NL Design System
|
|
app, branded **Rijkshuisstijl**, and demonstrates a robust **async-state pattern** where
|
|
the UI can never reach an inconsistent state.
|
|
|
|
> Demo / POC — no real data, no real login. Free **Fira Sans** stands in for the
|
|
> licensed Rijksoverheid font and a text wordmark for the logo.
|
|
|
|
---
|
|
|
|
## Run it
|
|
|
|
```bash
|
|
npm install
|
|
npm start # app → http://localhost:4200
|
|
npm run storybook # component library, organized by atomic layer
|
|
```
|
|
|
|
Flow: **Login → Dashboard → Mijn gegevens (wijziging) → Herregistratie**.
|
|
|
|
### See every data state (scenario toggle)
|
|
|
|
Append `?scenario=` to any data page (e.g. `/dashboard`) to force an async state:
|
|
|
|
| URL | What you see |
|
|
|-----|--------------|
|
|
| `/dashboard` | real data (fast) |
|
|
| `/dashboard?scenario=slow` | skeletons for ~2.5s, then data |
|
|
| `/dashboard?scenario=loading` | the loading state, held open |
|
|
| `/dashboard?scenario=empty` | "geen gegevens" empty state |
|
|
| `/dashboard?scenario=error` | error message + **Opnieuw proberen** (retry) |
|
|
|
|
---
|
|
|
|
## How atomic design works here (folder = layer)
|
|
|
|
Atomic design organizes UI into five layers, each built from the one below. In this repo
|
|
the folder structure *is* the hierarchy (`src/app/`):
|
|
|
|
| Layer | What it is | Examples here |
|
|
|-------|-----------|---------------|
|
|
| **atoms/** | smallest building blocks; wrap one design-system element | `button`, `text-input`, `heading`, `link`, `alert`, `status-badge`, `spinner`, `skeleton` |
|
|
| **molecules/** | a few atoms combined into a unit | `form-field` (label + input + error), `data-row`, `async` (state wrapper) |
|
|
| **organisms/** | larger, self-contained sections | `site-header`, `site-footer`, `login-form`, `registration-summary`, `registration-table`, `change-request-form` |
|
|
| **templates/** | page skeletons that define layout; content is projected in | `page-layout` (header/content/footer chrome), `page-shell` (back-link + heading + intro + content) |
|
|
| **pages/** | a template filled with real data | `login`, `dashboard`, `registration-detail`, `herregistratie` |
|
|
|
|
Each atom is a thin Angular standalone component that applies the Utrecht/Rijkshuisstijl
|
|
CSS classes — so the design system does the visual work and we only own a small, typed
|
|
component API.
|
|
|
|
---
|
|
|
|
## Where you actually notice the benefit
|
|
|
|
**1. Reuse — the same blocks appear everywhere.**
|
|
|
|
| Component | Appears in |
|
|
|-----------|-----------|
|
|
| `button` | login, change-request, herregistratie, async retry, Storybook |
|
|
| `form-field` + `text-input` | login form *and* change-request *and* herregistratie |
|
|
| `status-badge` | dashboard summary, detail summary |
|
|
| `page-shell` / `page-layout` | all four pages |
|
|
| `site-header` / `site-footer` | every page |
|
|
| `async` + `skeleton` | dashboard, detail |
|
|
|
|
Change a component once and every screen that uses it updates.
|
|
|
|
**2. A whole new page = composition, no new components.**
|
|
`pages/herregistratie/herregistratie.page.ts` is a complete new flow assembled entirely
|
|
from existing atoms/molecules/templates — zero new building blocks. That's the payoff:
|
|
new screens cost almost nothing.
|
|
|
|
**3. Templates remove per-page boilerplate.**
|
|
Every page used to repeat its own back-link + heading + intro markup. `page-shell`
|
|
captures that once; pages now read like `<app-page-shell heading="…" backLink="…">…`.
|
|
|
|
**4. Theming is one import.**
|
|
The look comes from `@rijkshuisstijl-community/design-tokens`. `src/styles.scss` imports
|
|
the `lintblauw` palette and applies `rhc-theme lintblauw` on `<body>`. Swap the palette
|
|
import to re-theme the whole app — no component changes.
|
|
|
|
---
|
|
|
|
## State management (no impossible states)
|
|
|
|
Data fetching uses Angular's native, signal-based **`httpResource`** (no NgRx,
|
|
no extra dependency). `core/registration.service.ts` exposes resources that carry
|
|
`status()`, `value()`, `error()`, `hasValue()` and `reload()` as signals.
|
|
|
|
The molecule **`<app-async>`** turns those signals into UI. It renders **exactly one** of
|
|
four slots, chosen by a single `computed` — so loading, empty, error and loaded are
|
|
mutually exclusive *by construction*. You cannot render data and an error at the same
|
|
time, or show stale content during a hard failure: those states are unrepresentable.
|
|
|
|
```html
|
|
<app-async [resource]="reg" [isEmpty]="regEmpty">
|
|
<ng-template appAsyncLoaded let-r> <app-registration-summary [reg]="r" /> </ng-template>
|
|
<ng-template appAsyncLoading> <app-skeleton [count]="6" /> </ng-template>
|
|
<!-- appAsyncEmpty / appAsyncError are optional → sensible defaults -->
|
|
</app-async>
|
|
```
|
|
|
|
- **Loaded** — your content, with the value.
|
|
- **Loading** — your skeleton, or a default **delayed spinner** (only appears after
|
|
~250ms, so fast connections never flash a spinner; slow ones get feedback). Skeletons
|
|
are also delay-gated. → *handles slow vs fast connections.*
|
|
- **Empty** — your message, or a default "Geen gegevens gevonden" (driven by an
|
|
`isEmpty` predicate).
|
|
- **Error** — your template, or a default alert + a **retry** button that calls
|
|
`resource.reload()`.
|
|
|
|
Because each data-fetching page wraps its content in `<app-async>`, correct
|
|
loading/empty/error handling is automatic and consistent across the app.
|
|
|
|
---
|
|
|
|
## Page transitions
|
|
|
|
The chrome (`templates/shell` — header + footer) is **persistent**: it mounts once and
|
|
hosts the `<router-outlet>`, so navigating doesn't re-create it (no white flash). Only
|
|
the routed content cross-fades, via Angular's native **`withViewTransitions()`** — the
|
|
header/footer get a stable `view-transition-name` in `styles.scss` so they're excluded
|
|
from the fade. `prefers-reduced-motion` disables the animation; non-Chromium browsers
|
|
degrade to an instant navigation.
|
|
|
|
## Tech notes
|
|
|
|
- Angular 22 (standalone components, signals, `httpResource`, view transitions,
|
|
control flow `@if/@for`).
|
|
- Styling: `@rijkshuisstijl-community/{design-tokens,components-css}` (Utrecht + RHC CSS,
|
|
pre-themed Rijkshuisstijl) — imported in `src/styles.scss`, no hand-written theme.
|
|
- Mock data: JSON in `public/mock/`, timing/outcome shaped by `core/scenario.interceptor.ts`.
|
|
- `.npmrc` sets `legacy-peer-deps=true` because `@storybook/angular`'s peer range lags
|
|
Angular 22; the builder runs fine (build verified).
|
|
|
|
### Dependency security
|
|
|
|
The **shipped app has 0 known vulnerabilities** (`npm audit --omit=dev`). All advisories
|
|
live in dev/build tooling (Storybook + the Angular build chain) and never reach the
|
|
bundle. `package.json` `overrides` pin patched transitive versions, taking the full
|
|
audit from 16 (incl. 3 high) down to **5 low** — the remainder all cascade from
|
|
`@babel/core`'s low-severity sourceMappingURL issue, which only "fixes" by jumping to
|
|
Babel 8 (a breaking change across the Storybook/Babel chain) and is deliberately left.
|
|
We do **not** run `npm audit fix --force`: its proposed fix downgrades Angular 22 → 21.
|
|
|
|
### Deliberately out of scope (POC)
|
|
Real auth/DigiD, real backend, i18n, NgRx, licensed Rijkshuisstijl fonts/logo.
|