SLP_Software/slp-modular-cms
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Wiki Activity

Adds frontend for cms page

Browse Source
This commit is contained in:
Sluijsens
2026-06-30 23:23:50 +02:00
parent c156107cb1
commit 488ab821a7
38 changed files with 2047 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
aidlc-docs/features/master-cms-module/construction/frontend-cms-page/nfr-requirements/nfr-requirements.md
+41
View File
@@ -0,0 +1,41 @@
# NFR Requirements — Unit 3: frontend-cms-page
## Maintainability
| ID | Requirement | Rationale |
|----|-------------|-----------|
| NFR-FE-01 | All new components use `react-hook-form` + `zodResolver` + Zod schemas, consistent with `InviteUserDialog` and `LoginPage` patterns in this project. | Single validation strategy across the entire frontend. |
| NFR-FE-02 | All user-visible strings are externalised in `src/i18n/locales/{lang}/translation.json` under the `cms.*` namespace. No hardcoded UI text in components. | Enables future language additions without code changes. |
| NFR-FE-03 | Components follow the existing Shadcn/UI composition pattern: `Dialog`, `Table`, `Select`, `Badge`, `DropdownMenu` from `@/components/ui/*`. No third-party UI additions. | Keeps the component surface consistent and avoids dependency sprawl. |
## Testability
| ID | Requirement | Rationale |
|----|-------------|-----------|
| NFR-FE-04 | Test scope: **hooks + page integration + individual component tests** (Q2: C). Required test files: `useCmsInstances.test.ts`, `useAddCmsInstance.test.ts`, `useUpdateCmsInstanceStatus.test.ts`, `CmsPage.test.tsx`, `AddCmsInstanceDialog.test.tsx`, `SetStatusDialog.test.tsx`. | Matches precedent set by `InviteUserDialog.test.tsx`. Isolated component tests cover error states and conditional logic (DisableMessage) without needing a full page mount. |
| NFR-FE-05 | MSW handlers cover all three API operations (GET list, POST create, PUT status) with at least one happy-path and one error variant per endpoint. | Handlers must be registered in both `src/mocks/browser.ts` (dev) and `src/mocks/server.ts` (tests). |
| NFR-FE-06 | All interactive elements receive `data-testid` attributes following the existing naming convention (`cms-*`, e.g. `cms-add-button`, `cms-instance-row`, `cms-set-status-submit`). | Required for RTL `getByTestId` selectors in tests. |
## Security
| ID | Requirement | Rationale |
|----|-------------|-----------|
| NFR-FE-07 | The `apiKey` field in `AddCmsInstanceDialog` is rendered as `type="password"` using the existing `PasswordField` component (which includes a show/hide toggle). | Prevents shoulder-surfing of infrastructure credentials during the add flow (Q3: A). Reuses existing `PasswordField.tsx` component. |
| NFR-FE-08 | The `apiKey` value is sent once to the backend on form submit. It is not stored in React state beyond the form lifecycle and is not logged to the console. | Credentials must not leak into browser DevTools' React state inspector or console logs. |
| NFR-FE-09 | `CmsPage` relies on `RoleGuard allowedRoles={['Owner']}` at the route level. No additional role check is implemented inside the page or its components. | Single point of access control; avoids partial/inconsistent guards. See BR-FE-20. |
## Reliability
| ID | Requirement | Rationale |
|----|-------------|-----------|
| NFR-FE-10 | Loading state for `useCmsInstances` is rendered as `<p className="text-sm text-muted-foreground">{t('common.loading')}</p>`, consistent with `UsersPage`. No skeleton component is introduced. | Uniform loading UX without additional dependencies. |
| NFR-FE-11 | Error state for `useCmsInstances` is rendered as `<p className="text-sm text-destructive">{t('errors.generic')}</p>`, consistent with `UsersPage`. | No custom error component needed. |
| NFR-FE-12 | TanStack Query stale time for `useCmsInstances` is 30 000 ms. Cache is invalidated on every successful mutation (add or status update). | Balances freshness with network efficiency; avoids redundant refetches while dialogs are open. |
## Validation
| ID | Requirement | Rationale |
|----|-------------|-----------|
| NFR-FE-13 | URL field in `AddCmsInstanceDialog` uses `z.string().url()` (strict Zod URL validation). The user must supply a fully-qualified URL including protocol (e.g. `http://192.168.1.5:8080`). | Q1: A. Backend validates anyway; client-side strict validation prevents protocol-less entries from ever reaching the API. |
| NFR-FE-14 | `react-hook-form` mode is set to `onTouched` for all new dialogs, consistent with `LoginPage`. Validation messages appear after a field is touched, not on initial render. | Avoids red errors appearing before the user has interacted with the form. |
| NFR-FE-15 | Field-level validation errors are rendered using the existing `<FieldError>` component (`src/components/ui/FieldError.tsx`). | Consistent error presentation across all forms. |
aidlc-docs/features/master-cms-module/construction/frontend-cms-page/nfr-requirements/tech-stack-decisions.md
+50
View File
@@ -0,0 +1,50 @@
# Tech Stack Decisions — Unit 3: frontend-cms-page
## Existing stack — no changes
| Layer | Technology | Notes |
|-------|-----------|-------|
| UI components | Shadcn/UI | `Dialog`, `Table`, `Select`, `Badge`, `DropdownMenu` — all already present |
| Styling | Tailwind CSS | `opacity-50` for Inactive rows (BR-FE-04) |
| Data fetching | TanStack Query v5 | `useQuery` + `useMutation` pattern already used by `useUsers` |
| Form state | react-hook-form + zodResolver | Used in `InviteUserDialog`, `LoginPage`, `SetupPage` |
| Schema validation | Zod | `z.string().url()` for URL field (NFR-FE-13) |
| Routing | TanStack Router | `/cms` route already exists; `RoleGuard` already wired |
| i18n | react-i18next | New `cms.*` keys added to EN + NL locales |
| Toasts | Sonner | `toast.success()` / `toast.error()` — already used throughout |
| Testing | Vitest + React Testing Library + MSW | All already configured |
| HTTP client | Custom `api-client` (`NetworkError`, `ProblemDetailsError`) | Same error types used across all existing hooks |
## Decisions made in this unit
### TSD-01 — URL validation: `z.string().url()` (strict)
**Decision**: Use Zod's built-in `z.string().url()` for the URL field.
**Rationale**: Q1: A. Users must enter a fully-qualified URL with protocol. The backend validates anyway, but client-side strict validation stops obviously malformed input early and improves error feedback.
**Implication**: Users entering `192.168.1.5:8080` will see a validation error. They must enter `http://192.168.1.5:8080`.
### TSD-02 — Test scope: hooks + page + component tests
**Decision**: Three test layers:
1. Hook unit tests (`useCmsInstances.test.ts`, `useAddCmsInstance.test.ts`, `useUpdateCmsInstanceStatus.test.ts`) using `renderHook` + MSW server
2. Page integration test (`CmsPage.test.tsx`) covering load, empty state, add flow, status flow
3. Component tests (`AddCmsInstanceDialog.test.tsx`, `SetStatusDialog.test.tsx`) for error states and conditional logic
**Rationale**: Q2: C. Matches `InviteUserDialog.test.tsx` precedent. Dialog component tests are necessary to cover `FormErrorBanner` on HTTP 400 and the `DisableMessage` conditional show/hide (BR-FE-08) without a full page mount.
### TSD-03 — ApiKey field: `PasswordField` with show/hide toggle
**Decision**: Reuse the existing `PasswordField` component (`src/components/ui/PasswordField.tsx`) for the `apiKey` input.
**Rationale**: Q3: A. Hides the credential from shoulder-surfing while allowing the user to reveal it for verification. No new component needed — `PasswordField` already implements the show/hide pattern.
### TSD-04 — Toast content: differentiated on `slaveContactSuccess`
**Decision**: Two distinct toast messages for `PUT /api/v1/CmsInstances/{id}/status`:
- `slaveContactSuccess === true` → `t('cms.setStatus.successContactedToast')` = "Status updated — cliënt confirmed"
- `slaveContactSuccess === false` → `t('cms.setStatus.successUnreachableToast')` = "Status saved — cliënt unreachable"
**Rationale**: Q3 FD: B + user terminology preference (no "slave" in UI). Both cases are HTTP 200; the distinction is surfaced via the `UpdateStatusResult.slaveContactSuccess` field from the backend.
### TSD-05 — `FormErrorBanner` component name
The project has both `FormBannerError` (`src/components/ui/FormBannerError.tsx`) and `FormErrorBanner` (`src/components/ui/FormErrorBanner.tsx`). The dialogs use `FormErrorBanner` (as used in `InviteUserDialog`). The `AddCmsInstanceDialog` and `SetStatusDialog` will import from `@/components/ui/FormErrorBanner`.