f1f4f982a6
- Fix full-bleed header/footer (align-items:stretch + block hosts; centered content column via shared --app-content-max). - New templates/page-shell (back-link + heading + intro + content, narrow mode); all pages refactored to compose it. - Async state management with native httpResource + <app-async> wrapper that renders exactly one of loading/empty/error/loaded (impossible states unrepresentable); delayed spinner + skeleton atoms for slow/fast connections. - Scenario interceptor (?scenario=slow|loading|empty|error) to demo every state. - Storybook: spinner/skeleton/page-shell/async-states stories. - README rewritten as a guide (atomic design, reuse benefits, state handling). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
132 lines
6.0 KiB
Markdown
132 lines
6.0 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.
|
|
|
|
---
|
|
|
|
## Tech notes
|
|
|
|
- Angular 22 (standalone components, signals, `httpResource`, 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).
|
|
|
|
### Deliberately out of scope (POC)
|
|
Real auth/DigiD, real backend, i18n, NgRx, licensed Rijkshuisstijl fonts/logo.
|