Initial commit: React frontend (SLP Software) + AIDLC workflow docs

Co-authored-by: Junie <junie@jetbrains.com>
2026-07-20 00:19:44 +02:00
commit e299f1c745
73 changed files with 7275 additions and 0 deletions
@@ -0,0 +1,47 @@
+# Build and Test Summary
+
+## Build Status
+- **Build Tool**: Vite 5 + TypeScript (`tsc -b`)
+- **Build Status**: Success
+- **Build Artifacts**: `dist/` (static HTML/JS/CSS/font bundle)
+- **Build Time**: Not formally measured; completes in a few seconds on a typical dev machine
+
+## Test Execution Summary
+
+### Unit Tests
+- **Total Tests**: 9
+- **Passed**: 9
+- **Failed**: 0
+- **Coverage**: No formal coverage gate configured
+- **Status**: Pass
+
+### Static Analysis (ESLint)
+- **Errors**: 0
+- **Warnings**: 2 (non-blocking `react-refresh/only-export-components` in `src/routes/index.tsx` and `src/theme/ThemeProvider.tsx`)
+- **Status**: Pass
+
+### Integration Tests (Manual Smoke Test)
+- **Test Scenarios**: 2 (navigation/scroll repeatability, theme toggle consistency)
+- **Passed**: 2 (manually verified during this session — the previously reported "click again and it jumps back to top" navigation bug is fixed)
+- **Failed**: 0
+- **Status**: Pass
+
+### Performance Tests
+- **Response Time / LCP**: Not yet formally measured with Lighthouse this session (instructions provided; recommended before first production deployment)
+- **Throughput**: N/A (static site, no application server)
+- **Error Rate**: 0% observed during manual testing (no console errors)
+- **Status**: Not yet run — see `performance-test-instructions.md`
+
+### Additional Tests
+- **Contract Tests**: N/A (no service boundaries)
+- **Security Tests**: N/A (no backend/auth surface for this static unit)
+- **E2E Tests**: Covered by the manual smoke test in `integration-test-instructions.md`
+
+## Overall Status
+- **Build**: Success
+- **All Automated Tests**: Pass (9/9 unit tests, 0 lint errors)
+- **Manual Navigation Regression Check**: Pass (fixed and verified)
+- **Ready for Operations**: Yes
+
+## Next Steps
+Ready to proceed to the Operations phase for deployment planning (Deployment Setup), as configured (`Include Operations Phase: Yes`, decided during Requirements Analysis).
@@ -0,0 +1,43 @@
+# Build Instructions
+
+## Prerequisites
+- **Build Tool**: Vite 5 + TypeScript (project references / `tsc -b`)
+- **Package Manager**: pnpm
+- **Runtime**: Node.js (LTS compatible with Vite 5 / TypeScript 5.6)
+- **Dependencies**: All packages listed in `package.json` (React 18, TanStack Router/Query, Tailwind CSS, Vitest, ESLint, Prettier)
+- **Environment Variables**: None required — the site is fully static, no backend/API keys
+- **System Requirements**: Any OS supported by Node.js; no special memory/disk requirements (small static bundle)
+
+## Build Steps
+
+### 1. Install Dependencies
+```bash
+pnpm install
+```
+
+### 2. Configure Environment
+No environment configuration is required. The app has no runtime environment variables or external service credentials.
+
+### 3. Build the Unit (react-frontend-app)
+```bash
+pnpm run build
+```
+This runs `tsc -b` (type-check via project references) followed by `vite build` (production bundle).
+
+### 4. Verify Build Success
+- **Expected Output**: `tsc -b` completes with no type errors; `vite build` reports the generated chunks and finishes with `✓ built in <time>`
+- **Build Artifacts**: Static assets emitted to `dist/` (HTML, JS, CSS, fonts) — ready to be uploaded as-is to any static/FTP web host
+- **Common Warnings**: None expected under normal conditions
+
+## Troubleshooting
+
+### Build Fails with Dependency Errors
+- **Cause**: `node_modules` missing/corrupted, or `pnpm-lock.yaml` out of sync with `package.json`
+- **Solution**: Delete `node_modules`, re-run `pnpm install`; if the lockfile is out of date, run `pnpm install` again to regenerate it, then rebuild
+
+### Build Fails with Compilation Errors
+- **Cause**: TypeScript type errors introduced by recent changes (e.g. incorrect props, missing imports)
+- **Solution**: Read the `tsc -b` error output (file + line), fix the reported type issue, and re-run `pnpm run build`
+
+## Verified Result (this session)
+- `pnpm run build` executed successfully: `tsc -b && vite build` completed without errors, `dist/` was generated correctly.
@@ -0,0 +1,52 @@
+# Integration Test Instructions
+
+## Purpose
+This feature consists of a single unit (`react-frontend-app`, a static marketing site with no backend service and no other units to integrate with). There is no cross-service integration to test. Instead, this stage covers **manual end-to-end smoke testing** of the built bundle in a browser, focusing on the areas where components/routing interact (navigation, routing, theming).
+
+## Test Scenarios
+
+### Scenario 1: Full Page Render & Navigation Flow
+- **Description**: Verify that the whole single-page site renders and that in-page navigation (Nav links, Hero CTAs, package CTA) scrolls to the correct sections repeatedly, without ever reverting to the top.
+- **Setup**: Run `pnpm run build && pnpm run preview` (serves the production `dist/` bundle), open the printed local URL in a browser
+- **Test Steps**:
+  1. Click each Nav link (`Pakketten`, `Werkwijze`, `Over`, `Start project`) in sequence, multiple times each, including repeated clicks on the same link
+  2. Click the Hero CTAs (`Bekijk pakketten`, `Plan een gesprek`)
+  3. Click a package card's CTA (`Kies ...` / `Vraag offerte aan`)
+  4. Click the logo (`SLP.Software`) to return to `#top`
+- **Expected Results**: Every click smoothly scrolls to the correct section every time; the page never snaps back to the top on a repeated/second click (this was the regression fixed via `handleAnchorClick`/`scrollToHash`); the URL hash is not required to change for scrolling to work
+- **Cleanup**: Stop the `pnpm run preview` process
+
+### Scenario 2: Theme Toggle Integration
+- **Description**: Verify the theme toggle correctly switches and persists across the whole page (all sections read from the same theme context)
+- **Setup**: Same as Scenario 1
+- **Test Steps**: Toggle the theme control in the Nav; observe all sections (Hero, Packages, Process, About, Contact)
+- **Expected Results**: All sections switch theme consistently; no section is left in the previous theme
+- **Cleanup**: None
+
+## Setup Integration Test Environment
+
+### 1. Build and Serve the Production Bundle
+```bash
+pnpm run build
+pnpm run preview
+```
+
+### 2. Configure Service Endpoints
+Not applicable — no external services or APIs are called by this unit.
+
+## Run Integration Tests
+
+### 1. Execute Manual Smoke Test Suite
+Follow Scenario 1 and Scenario 2 above in a browser against the `pnpm run preview` URL.
+
+### 2. Verify Behaviors
+- **Test Scenarios**: Navigation/scroll repeatability (Scenario 1), theme consistency (Scenario 2)
+- **Expected Results**: See per-scenario expectations above
+- **Logs Location**: Browser DevTools console (should show no errors/warnings during navigation)
+
+### 3. Cleanup
+Stop the preview server (`Ctrl+C` or terminate the process).
+
+## Status
+- **Automated integration/contract tests**: N/A — single static unit, no service boundaries to test
+- **Manual smoke test**: Recommended before each deployment; the navigation-scroll regression (Scenario 1) was manually verified as fixed during this session
@@ -0,0 +1,51 @@
+# Performance Test Instructions
+
+## Purpose
+Validate that the static marketing site loads fast on a typical FTP/static web host, since page-load speed and SEO basics are explicit requirements (see `aidlc-docs/features/react-frontend/inception/requirements/`).
+
+## Performance Requirements
+- **Initial Load (Largest Contentful Paint)**: < 2.5s on a simulated "Fast 3G"/typical mobile connection
+- **Bundle Size**: JS + CSS payload kept small (single-page static site, no heavy client-side data fetching)
+- **Concurrent Users**: Not applicable — static assets served by the host/CDN, no application server to load-test
+- **Error Rate**: 0% (no runtime errors in the browser console)
+
+## Setup Performance Test Environment
+
+### 1. Prepare Test Environment
+```bash
+pnpm run build
+pnpm run preview
+```
+Serves the actual production bundle (`dist/`) locally, which is representative of what a static host would serve.
+
+### 2. Configure Test Parameters
+- **Tooling**: Browser DevTools "Lighthouse" panel (or `npx lighthouse <preview-url> --view`)
+- **Throttling**: Simulated mobile / Fast 3G, as offered by Lighthouse's default mobile preset
+
+## Run Performance Tests
+
+### 1. Execute Load Test (Lighthouse)
+```bash
+npx lighthouse http://localhost:4173 --view
+```
+(Adjust the port to whatever `pnpm run preview` prints.)
+
+### 2. Execute Stress Tests
+Not applicable — there is no backend/API to stress-test; the site is purely static assets.
+
+### 3. Analyze Performance Results
+- **Response Time / LCP**: Read from the Lighthouse report; target < 2.5s
+- **Bundle Size**: Inspect `dist/assets/*.js` and `*.css` sizes after `pnpm run build`
+- **Error Rate**: Confirm no console errors during the Lighthouse run
+- **Bottlenecks**: Typically font loading (`@fontsource/*`) or unused CSS; check the Lighthouse "Opportunities" section
+- **Results Location**: Lighthouse HTML report opened via `--view`, or exported JSON if needed
+
+## Performance Optimization
+If performance doesn't meet requirements:
+1. Identify bottlenecks from the Lighthouse report (e.g. render-blocking fonts, unused Tailwind classes)
+2. Optimize (e.g. font-display swap, purge unused Tailwind utilities via the existing Tailwind config, code-split rarely used components)
+3. Rerun `pnpm run build` + Lighthouse to validate improvements
+
+## Status
+- **Automated performance gate**: Not part of the current CI; this is a manual pre-deployment check
+- **Recommendation**: Run this check once before the first production deployment (Deployment Setup stage) and after any significant asset/dependency change
@@ -0,0 +1,31 @@
+# Unit Test Execution
+
+## Run Unit Tests
+
+### 1. Execute All Unit Tests
+```bash
+pnpm run test
+```
+Runs Vitest (`vitest run`) with `jsdom` + `@testing-library/react` for component-level tests.
+
+### 2. Review Test Results
+- **Expected**: 9 tests pass across 3 test files, 0 failures
+- **Test Coverage**: No formal coverage threshold configured; tests cover key rendering/interaction behavior of `Hero`, `Nav`, and the anchor-scroll utility
+- **Test Report Location**: Console output from `vitest run` (no HTML report is generated by default)
+
+### 3. Static Analysis (complementary check)
+```bash
+pnpm run lint
+```
+- **Expected**: 0 errors. 2 non-blocking warnings are known and accepted (`react-refresh/only-export-components` in `src/routes/index.tsx` and `src/theme/ThemeProvider.tsx`) — cosmetic Fast Refresh warnings, not correctness issues.
+
+### 4. Fix Failing Tests
+If tests fail:
+1. Review the Vitest console output for the failing test file/assertion
+2. Reproduce locally with `pnpm run test:watch` for fast iteration
+3. Fix the component/utility code or update the test if the expected behavior changed intentionally
+4. Rerun `pnpm run test` until all pass
+
+## Verified Result (this session)
+- `pnpm run test`: 3 test files, 9 tests, all passed.
+- `pnpm run lint`: 0 errors, 2 known non-blocking warnings.