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/aidlc-state.md
+5 -1
View File
@@ -5,7 +5,7 @@
- **Feature Slug**: master-cms-module
- **Project Type**: Brownfield
- **Start Date**: 2026-06-26T00:00:00Z
- **Current Stage**: CONSTRUCTION - Unit 2 (slave-availability-extension) Code Generation
- **Current Stage**: CONSTRUCTION - Unit 3 (frontend-cms-page) Code Generation Complete
- **Branch**: unknown
## Workspace State
@@ -51,6 +51,10 @@
- [x] NFR Requirements — Complete (Unit 2)
- [x] NFR Design — Complete (Unit 2)
- [x] Code Generation — Complete (Unit 2)
- [x] Functional Design — Complete (Unit 3)
- [x] NFR Requirements — Complete (Unit 3)
- [x] NFR Design — Complete (Unit 3)
- [x] Code Generation — Complete (Unit 3)
- [ ] Infrastructure Design — Skipped
- [ ] Code Generation — Execute (per unit)
- [ ] Build and Test — Execute
aidlc-docs/features/master-cms-module/construction/frontend-cms-page/nfr-design/logical-components.md
+116
View File
@@ -0,0 +1,116 @@
# Logical Components — Unit 3: frontend-cms-page
## Overview
```
src/lib/schemas/
├── auth.ts (existing — unchanged)
├── users.ts (NEW — migrated from InviteUserDialog inline)
└── cms.ts (NEW — addCmsInstanceSchema, setStatusSchema)
src/api/
├── types.ts (extended — CmsInstance, CmsInstanceStatus, CreateCmsInstanceRequest,
│ UpdateCmsInstanceStatusRequest, UpdateStatusResult)
├── useCmsInstances.ts (NEW)
├── useAddCmsInstance.ts (NEW)
└── useUpdateCmsInstanceStatus.ts (NEW)
src/components/cms/
├── CmsInstanceList.tsx (NEW)
├── AddCmsInstanceDialog.tsx (NEW)
└── SetStatusDialog.tsx (NEW)
src/components/users/
└── InviteUserDialog.tsx (MODIFIED — schema import + serverError migration)
src/pages/
└── CmsPage.tsx (MODIFIED — replace placeholder with full page)
src/i18n/locales/
├── en/translation.json (MODIFIED — cms.* keys added)
└── nl/translation.json (MODIFIED — cms.* keys added)
src/mocks/
├── cms/handlers.ts (NEW — GET, POST, PUT MSW handlers)
├── browser.ts (MODIFIED — register cms handlers)
└── server.ts (MODIFIED — register cms handlers)
Test files:
├── src/lib/schemas/cms.test.ts (NEW)
├── src/lib/schemas/users.test.ts (NEW)
├── src/api/useCmsInstances.test.ts (NEW)
├── src/api/useAddCmsInstance.test.ts (NEW)
├── src/api/useUpdateCmsInstanceStatus.test.ts (NEW)
├── src/components/cms/AddCmsInstanceDialog.test.tsx (NEW)
├── src/components/cms/SetStatusDialog.test.tsx (NEW)
└── src/pages/CmsPage.test.tsx (MODIFIED — replace placeholder assertions)
```
---
## Component Responsibilities
### `src/lib/schemas/cms.ts` — Validation Logic
| Export | Validates |
|--------|-----------|
| `addCmsInstanceSchema` | name (required, max 255), url (z.string().url()), apiKey (required) |
| `AddCmsInstanceFormData` | Inferred type |
| `setStatusSchema` | status (enum), disableMessage (required when NotAvailable via `.refine()`) |
| `SetStatusFormData` | Inferred type |
### `src/lib/schemas/users.ts` — Migrated Schema
| Export | Source |
|--------|--------|
| `inviteUserSchema` | Migrated from `InviteUserDialog.tsx` inline — no behaviour change |
| `InviteUserFormData` | Inferred type |
### `src/api/useCmsInstances.ts` — Query Hook
| Concern | Implementation |
|---------|---------------|
| Endpoint | `GET /api/v1/CmsInstances` |
| Query key | `['cmsInstances']` |
| Stale time | 30 000 ms |
| Return type | `UseQueryResult<CmsInstance[], Error>` |
### `src/api/useAddCmsInstance.ts` — Mutation Hook
| Concern | Implementation |
|---------|---------------|
| Endpoint | `POST /api/v1/CmsInstances` |
| Body | `CreateCmsInstanceRequest` |
| On success | `invalidateQueries(['cmsInstances'])` |
| Accepts | Optional `onError` callback (caller sets `serverError` state) |
### `src/api/useUpdateCmsInstanceStatus.ts` — Mutation Hook
| Concern | Implementation |
|---------|---------------|
| Endpoint | `PUT /api/v1/CmsInstances/{id}/status` |
| Variables | `{ id: string } & UpdateCmsInstanceStatusRequest` |
| Return | `UpdateStatusResult` |
| On success | `invalidateQueries(['cmsInstances'])` |
| Accepts | Optional `onSuccess` / `onError` callbacks |
### `src/mocks/cms/handlers.ts` — MSW Handlers
| Handler | Behaviour |
|---------|-----------|
| `GET /api/v1/CmsInstances` | Returns in-memory `cmsInstances[]` array |
| `POST /api/v1/CmsInstances` | Pushes new instance to array; returns 201 + created instance |
| `PUT /api/v1/CmsInstances/:id/status` | Updates instance in array; returns `UpdateStatusResult` |
In-memory state initialised with 1-2 seed instances to support development and test scenarios.
---
## Migration Summary
| File | Change | Reason |
|------|--------|--------|
| `InviteUserDialog.tsx` | Import schema from `@/lib/schemas/users` instead of inline | Pattern 1 (centralised schemas) |
| `InviteUserDialog.tsx` | Replace `inviteUser.error` with `useState<string \| null>` | Pattern 2 (consistent error handling) |
| `src/lib/schemas/users.ts` | New file — migrated `inviteSchema` | Pattern 1 |
| `src/lib/schemas/users.test.ts` | New file — tests for `inviteUserSchema` | NFR-FE-04 |
aidlc-docs/features/master-cms-module/construction/frontend-cms-page/nfr-design/nfr-design-patterns.md
+156
View File
@@ -0,0 +1,156 @@
# NFR Design Patterns — Unit 3: frontend-cms-page
## Pattern 1 — Validation: Centralised Zod Schema Module
**NFR**: NFR-FE-01, NFR-FE-13, NFR-FE-14
**Decision**: Q1 Other — all Zod form schemas live in `src/lib/schemas/`
### Rule
Every form schema in the project is defined in `src/lib/schemas/{domain}.ts` and exported from that module. No schema is defined inline inside a component file.
### New files (this unit)
**`src/lib/schemas/cms.ts`**
```typescript
import { z } from 'zod';
export const addCmsInstanceSchema = z.object({
name: z.string().min(1, 'Name is required').max(255),
url: z.string().url('Must be a valid URL (include http:// or https://)'),
apiKey: z.string().min(1, 'API key is required'),
});
export type AddCmsInstanceFormData = z.infer<typeof addCmsInstanceSchema>;
export const setStatusSchema = z.object({
status: z.enum(['Available', 'NotAvailable', 'Inactive']),
disableMessage: z.string().optional(),
}).refine(
(data) => data.status !== 'NotAvailable' || (data.disableMessage?.trim().length ?? 0) > 0,
{ message: 'Disable message is required when status is Not Available', path: ['disableMessage'] }
);
export type SetStatusFormData = z.infer<typeof setStatusSchema>;
```
### Migration (existing inline schema)
`InviteUserDialog.tsx` currently defines `inviteSchema` inline. As part of this unit, migrate it to **`src/lib/schemas/users.ts`**:
```typescript
import { z } from 'zod';
export const inviteUserSchema = z.object({
email: z.string().email(),
role: z.enum(['Administrator', 'User']),
});
export type InviteUserFormData = z.infer<typeof inviteUserSchema>;
```
`InviteUserDialog.tsx` then imports from `@/lib/schemas/users` and removes the inline definition.
### Test files
- `src/lib/schemas/cms.test.ts` — tests for `addCmsInstanceSchema` (URL strictness, DisableMessage refinement) and `setStatusSchema`
- `src/lib/schemas/users.test.ts` — tests for `inviteUserSchema` (migrated from inline, no behaviour change)
---
## Pattern 2 — Error Handling: Local Server Error State
**NFR**: NFR-FE-15 (field errors via `FieldError`), BR-FE-15/16 (FormErrorBanner for server errors)
**Decision**: Q2 B — all forms use `useState<string | null>(null)` for server-side error messages
### Rule
Every form component that calls a mutation owns a `const [serverError, setServerError] = useState<string | null>(null)` local state. The mutation's `onError` callback translates the error type to an i18n string and sets `serverError`. The `<FormErrorBanner>` receives `serverError`.
This pattern is adopted **project-wide**, including the migration of `InviteUserDialog` (currently using `mutation.error` directly).
### Standard implementation
```typescript
const [serverError, setServerError] = useState<string | null>(null);
const addInstance = useAddCmsInstance({
onError: (err) => {
if (err instanceof ProblemDetailsError && err.status === 409) {
setServerError(t('cms.add.errors.conflict'));
} else if (err instanceof NetworkError) {
setServerError(t('errors.network'));
} else {
setServerError(t('errors.generic'));
}
},
});
// Reset on dialog close
useEffect(() => {
if (!open) {
setServerError(null);
addInstance.reset();
reset();
}
}, [open]);
```
### FormErrorBanner usage
```tsx
<FormErrorBanner
error={serverError !== null ? { message: serverError } : null}
onDismiss={() => setServerError(null)}
/>
```
### Migration (existing InviteUserDialog)
`InviteUserDialog` currently passes `inviteUser.error` directly to `FormErrorBanner`. Migrate to local `useState<string | null>` + `onError` callback. Error message stays generic (`t('errors.generic')`) since invite errors are not status-code-specific.
---
## Pattern 3 — Form Lifecycle: Reset on Close
**NFR**: NFR-FE-01 (consistent patterns)
All dialog forms reset their full state (form values, server error, mutation state) when the dialog closes. Implemented via `useEffect` watching the `open` prop:
```typescript
useEffect(() => {
if (!open) {
setServerError(null);
mutation.reset();
reset(); // react-hook-form reset
}
}, [open]);
```
This pattern is already present in `InviteUserDialog` and is carried forward to `AddCmsInstanceDialog` and `SetStatusDialog`.
---
## Pattern 4 — Security: PasswordField for Credentials
**NFR**: NFR-FE-07, NFR-FE-08
**Decision**: TSD-03
The `apiKey` field in `AddCmsInstanceDialog` uses the existing `PasswordField` component:
```tsx
import { PasswordField } from '@/components/ui/PasswordField';
<PasswordField
id="add-cms-apikey"
label={t('cms.add.apiKeyLabel')}
data-testid="add-cms-apikey"
aria-invalid={errors.apiKey !== undefined}
{...register('apiKey')}
/>
```
`PasswordField` already renders `type="password"` with a show/hide toggle button. No new component needed.
---
## Pattern 5 — Cache Invalidation: Pessimistic Refetch
**NFR**: NFR-FE-12
All mutations invalidate `['cmsInstances']` in `onSuccess` after the server confirms the operation. No optimistic updates. Consistent with `useUsers` / `useChangeRole` patterns in this project.
```typescript
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['cmsInstances'] }),
```
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`.
aidlc-docs/features/master-cms-module/construction/plans/frontend-cms-page-code-generation-plan.md
+242
View File
@@ -0,0 +1,242 @@
# Code Generation Plan — Unit 3: frontend-cms-page
## Unit Context
**Workspace root**: `K:\Development\Projects\SlpModularCms`
**Frontend root**: `frontend/src/`
**Project type**: Brownfield
**FD artifacts**: `aidlc-docs/features/master-cms-module/construction/frontend-cms-page/functional-design/`
**NFR artifacts**: `aidlc-docs/features/master-cms-module/construction/frontend-cms-page/nfr-requirements/` + `nfr-design/`
## Dependencies
- Backend API (`CmsInstanceController`) implemented in Unit 1 (master-backend) ✅
- Existing frontend: `src/api/types.ts`, `src/lib/schemas/auth.ts`, `src/mocks/index.ts`, `src/pages/CmsPage.tsx` (placeholder)
- MSW: existing `mocks/index.ts` pattern with feature folders
## Cross-cutting migrations (part of this unit)
- `InviteUserDialog.tsx`: schema → `@/lib/schemas/users`, error state → `useState<string | null>`
- New schema files: `src/lib/schemas/users.ts`, `src/lib/schemas/cms.ts`
---
## Steps
### Step 1 — `src/api/types.ts` (MODIFY)
Add CMS domain types after existing types:
- `CmsInstanceStatus` union type (`'Available' | 'NotAvailable' | 'Inactive'`)
- `CmsInstance` interface (id, name, url, status, disableMessage, lastContactedAt, lastStatusPushedAt, lastIntegrityCheckFailedAt)
- `CreateCmsInstanceRequest` interface (name, url, apiKey)
- `UpdateCmsInstanceStatusRequest` interface (status, disableMessage)
- `UpdateStatusResult` interface (success, slaveContactSuccess)
### Step 2 — `src/lib/schemas/users.ts` (CREATE)
Migrate `inviteSchema` from `InviteUserDialog.tsx` to `src/lib/schemas/users.ts`:
- Export `inviteUserSchema` (z.object: email z.string().email(), role z.enum(['Administrator','User']))
- Export `InviteUserFormData` inferred type
### Step 3 — `src/lib/schemas/cms.ts` (CREATE)
- `addCmsInstanceSchema`: name (min 1, max 255), url (z.string().url()), apiKey (min 1)
- `AddCmsInstanceFormData` inferred type
- `setStatusSchema`: status enum + `.refine()` requiring disableMessage when NotAvailable
- `SetStatusFormData` inferred type
### Step 4 — `src/lib/schemas/users.test.ts` (CREATE)
Tests for migrated `inviteUserSchema`:
- Valid email + role → passes
- Invalid email → fails
- Missing role → fails
### Step 5 — `src/lib/schemas/cms.test.ts` (CREATE)
Tests for both schemas:
- `addCmsInstanceSchema`: valid data passes; missing name/apiKey fails; `z.string().url()` — `http://valid.url` passes, `no-protocol` fails
- `setStatusSchema`: Available without disableMessage passes; NotAvailable without disableMessage fails; NotAvailable with disableMessage passes
### Step 6 — `src/components/users/InviteUserDialog.tsx` (MODIFY)
Two changes (pattern migration):
1. Replace inline `inviteSchema` + `InviteFormData` with import from `@/lib/schemas/users`
2. Replace `inviteUser.error` passed to `<FormErrorBanner>` with local `useState<string | null>(null)` + `onError` callback setting generic error message
### Step 7 — `src/mocks/cms/handlers.ts` (CREATE)
In-memory MSW handlers:
- `let mockCmsInstances: CmsInstance[]` with 2 seed entries (one Available, one Inactive)
- `resetMockCmsInstances()` export
- `GET /api/v1/CmsInstances` → return array
- `POST /api/v1/CmsInstances` → create instance (status=Available), push to array, return 201 + instance
- `PUT /api/v1/CmsInstances/:id/status` → update instance in array, return `UpdateStatusResult { success: true, slaveContactSuccess: true }`
### Step 8 — `src/mocks/index.ts` (MODIFY)
- Import `cmsHandlers` from `./cms/handlers`
- Add `...cmsHandlers` to `handlers` array
- Re-export `cmsHandlers` and `resetMockCmsInstances`
### Step 9 — `src/api/useCmsInstances.ts` (CREATE)
```typescript
export function useCmsInstances() {
return useQuery<CmsInstance[], Error>({
queryKey: ['cmsInstances'],
queryFn: () => api.get<CmsInstance[]>('/api/v1/CmsInstances'),
staleTime: 30_000,
});
}
```
### Step 10 — `src/api/useAddCmsInstance.ts` (CREATE)
```typescript
export function useAddCmsInstance(options?: MutationOptions) {
const queryClient = useQueryClient();
return useMutation<CmsInstance, Error, CreateCmsInstanceRequest>({
mutationFn: (data) => api.post<CmsInstance>('/api/v1/CmsInstances', data),
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['cmsInstances'] }),
...options,
});
}
```
### Step 11 — `src/api/useUpdateCmsInstanceStatus.ts` (CREATE)
```typescript
export function useUpdateCmsInstanceStatus(options?: MutationOptions) {
const queryClient = useQueryClient();
return useMutation<UpdateStatusResult, Error, { id: string } & UpdateCmsInstanceStatusRequest>({
mutationFn: ({ id, ...body }) =>
api.put<UpdateStatusResult>(`/api/v1/CmsInstances/${id}/status`, body),
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['cmsInstances'] }),
...options,
});
}
```
### Step 12 — `src/i18n/locales/en/translation.json` (MODIFY)
Replace existing `"cms": { "title": ..., "description": ... }` with full `cms.*` key tree (from frontend-components.md i18n section).
### Step 13 — `src/i18n/locales/nl/translation.json` (MODIFY)
Replace existing `"cms": { "title": ..., "description": ... }` with full `cms.*` key tree in Dutch.
### Step 14 — `src/components/cms/CmsInstanceList.tsx` (CREATE)
Table component:
- Props: `instances: CmsInstance[]`, `onSetStatus: (instance: CmsInstance) => void`
- Shadcn `Table` with 6 columns (Name, URL, Status, Last Contact, Disable Message, Actions)
- Status badge: green/red/muted per BR-FE-05..07
- Inactive row: `className={instance.status === 'Inactive' ? 'opacity-50' : ''}`
- Actions: `DropdownMenu` with "Set Status" item
- `data-testid` on row (`cms-instance-row`), badge, and actions trigger
### Step 15 — `src/components/cms/AddCmsInstanceDialog.tsx` (CREATE)
Dialog with react-hook-form + `addCmsInstanceSchema`:
- Fields: name (text), url (text), apiKey (`PasswordField`)
- `useState<string | null>(null)` for serverError
- `onError` callback: ProblemDetailsError 409 → specific message, NetworkError → `errors.network`, else → `errors.generic`
- `useEffect` on `open` → reset form + serverError + mutation
- `FormErrorBanner`, `FieldError`, `data-testid` on all fields and submit button
### Step 16 — `src/components/cms/SetStatusDialog.tsx` (CREATE)
Dialog with react-hook-form + `setStatusSchema`:
- Fields: status (Shadcn `Select`), disableMessage (conditional text, only when NotAvailable)
- `useState<string | null>(null)` for serverError
- `onSuccess`: close dialog, toast message based on `result.slaveContactSuccess` (BR-FE-12/13)
- `onError`: set serverError from toast (generic)
- `useEffect` on `open` or `instance` change → reset
- `data-testid` on select, disableMessage input, submit button
### Step 17 — `src/pages/CmsPage.tsx` (MODIFY)
Replace placeholder with full page:
- State: `addDialogOpen`, `statusTarget`
- `useCmsInstances()` hook
- Header row: title + "Add CMS" button (data-testid="cms-add-button")
- Loading/error text per NFR-FE-10/11
- Empty state (BR-FE-18) vs `CmsInstanceList`
- `AddCmsInstanceDialog` + `SetStatusDialog`
- Remove old `data-testid="cms-placeholder"` (test file updated in step 18)
### Step 18 — `src/pages/CmsPage.test.tsx` (MODIFY)
Replace existing placeholder-only tests with:
- `renders list of CMS instances` (happy path with seed data)
- `renders empty state when no instances` (MSW returns [])
- `opens AddCmsInstanceDialog on button click`
- `adds a CMS instance successfully`
- `redirects unauthenticated users to login` (existing — keep)
### Step 19 — `src/api/useCmsInstances.test.ts` (CREATE)
- Returns list on success
- Handles network error
### Step 20 — `src/api/useAddCmsInstance.test.ts` (CREATE)
- Creates instance + invalidates cache on success (HTTP 201)
- Calls onError on HTTP 400
### Step 21 — `src/api/useUpdateCmsInstanceStatus.test.ts` (CREATE)
- Updates status + invalidates cache on success
- Returns UpdateStatusResult with slaveContactSuccess flag
### Step 22 — `src/components/cms/AddCmsInstanceDialog.test.tsx` (CREATE)
- Renders fields and submit button
- Shows FieldError for missing name
- Shows FieldError for invalid URL (non-URL format)
- Shows FormErrorBanner on HTTP 400
- Resets form on dialog close
### Step 23 — `src/components/cms/SetStatusDialog.test.tsx` (CREATE)
- DisableMessage field hidden when status ≠ NotAvailable
- DisableMessage field shown and required when status = NotAvailable
- Form blocks submit when DisableMessage empty + NotAvailable
---
## File Summary
| # | File | Action |
|---|------|--------|
| 1 | `frontend/src/api/types.ts` | MODIFY — add 5 CMS types |
| 2 | `frontend/src/lib/schemas/users.ts` | CREATE — migrated inviteUserSchema |
| 3 | `frontend/src/lib/schemas/cms.ts` | CREATE — addCmsInstanceSchema, setStatusSchema |
| 4 | `frontend/src/lib/schemas/users.test.ts` | CREATE |
| 5 | `frontend/src/lib/schemas/cms.test.ts` | CREATE |
| 6 | `frontend/src/components/users/InviteUserDialog.tsx` | MODIFY — schema import + serverError migration |
| 7 | `frontend/src/mocks/cms/handlers.ts` | CREATE — MSW handlers |
| 8 | `frontend/src/mocks/index.ts` | MODIFY — register cmsHandlers |
| 9 | `frontend/src/api/useCmsInstances.ts` | CREATE |
| 10 | `frontend/src/api/useAddCmsInstance.ts` | CREATE |
| 11 | `frontend/src/api/useUpdateCmsInstanceStatus.ts` | CREATE |
| 12 | `frontend/src/i18n/locales/en/translation.json` | MODIFY — cms.* keys |
| 13 | `frontend/src/i18n/locales/nl/translation.json` | MODIFY — cms.* keys |
| 14 | `frontend/src/components/cms/CmsInstanceList.tsx` | CREATE |
| 15 | `frontend/src/components/cms/AddCmsInstanceDialog.tsx` | CREATE |
| 16 | `frontend/src/components/cms/SetStatusDialog.tsx` | CREATE |
| 17 | `frontend/src/pages/CmsPage.tsx` | MODIFY — replace placeholder |
| 18 | `frontend/src/pages/CmsPage.test.tsx` | MODIFY — full test suite |
| 19 | `frontend/src/api/useCmsInstances.test.ts` | CREATE |
| 20 | `frontend/src/api/useAddCmsInstance.test.ts` | CREATE |
| 21 | `frontend/src/api/useUpdateCmsInstanceStatus.test.ts` | CREATE |
| 22 | `frontend/src/components/cms/AddCmsInstanceDialog.test.tsx` | CREATE |
| 23 | `frontend/src/components/cms/SetStatusDialog.test.tsx` | CREATE |
**Total**: 16 new files, 7 modified files
---
## Step Completion Tracking
- [x] Step 1 — types.ts
- [x] Step 2 — schemas/users.ts
- [x] Step 3 — schemas/cms.ts
- [x] Step 4 — schemas/users.test.ts
- [x] Step 5 — schemas/cms.test.ts
- [x] Step 6 — InviteUserDialog.tsx migration
- [x] Step 7 — mocks/cms/handlers.ts
- [x] Step 8 — mocks/index.ts
- [x] Step 9 — useCmsInstances.ts
- [x] Step 10 — useAddCmsInstance.ts
- [x] Step 11 — useUpdateCmsInstanceStatus.ts
- [x] Step 12 — en/translation.json
- [x] Step 13 — nl/translation.json
- [x] Step 14 — CmsInstanceList.tsx
- [x] Step 15 — AddCmsInstanceDialog.tsx
- [x] Step 16 — SetStatusDialog.tsx
- [x] Step 17 — CmsPage.tsx
- [x] Step 18 — CmsPage.test.tsx
- [x] Step 19 — useCmsInstances.test.ts
- [x] Step 20 — useAddCmsInstance.test.ts
- [x] Step 21 — useUpdateCmsInstanceStatus.test.ts
- [x] Step 22 — AddCmsInstanceDialog.test.tsx
- [x] Step 23 — SetStatusDialog.test.tsx
aidlc-docs/features/master-cms-module/construction/plans/frontend-cms-page-nfr-design-plan.md
+22
View File
@@ -0,0 +1,22 @@
# NFR Design Plan — Unit 3: frontend-cms-page
## Unit Context
**Unit**: `frontend-cms-page`
**Inputs**: nfr-requirements.md, tech-stack-decisions.md
**Key NFR design concerns**: Zod schema organisation, error-handling pattern for hooks
---
## Execution Steps
- [x] **Step 1** — Analyze answers; flag ambiguities
- [x] **Step 2** — Generate `nfr-design-patterns.md`
- [x] **Step 3** — Generate `logical-components.md`
- [x] **Step 4** — Update `aidlc-state.md`
- [ ] **Step 5** — Present completion message for approval
---
*Questions file*: `frontend-cms-page-nfr-design-questions.md`
*Artifact path*: `aidlc-docs/features/master-cms-module/construction/plans/frontend-cms-page-nfr-design-plan.md`
aidlc-docs/features/master-cms-module/construction/plans/frontend-cms-page-nfr-design-questions.md
+34
View File
@@ -0,0 +1,34 @@
# NFR Design Questions — Unit 3: frontend-cms-page
Please answer each question by filling in the letter after the `[Answer]:` tag.
If none of the options match, choose the last option (Other) and describe your preference.
---
## Question 1
Where should the Zod form schemas for `AddCmsInstanceDialog` and `SetStatusDialog` live?
Context: `src/lib/schemas/auth.ts` holds shared auth schemas (used by LoginPage, SetupPage, InviteCompletePage, and tested in `auth.test.ts`). `InviteUserDialog` defines its schema inline.
A) **Inline in each component file** — `addInstanceSchema` defined inside `AddCmsInstanceDialog.tsx`, `setStatusSchema` inside `SetStatusDialog.tsx`. Pragmatic: each schema is single-use and lives next to the form that uses it. Consistent with `InviteUserDialog.tsx` pattern.
B) **Centralised in `src/lib/schemas/cms.ts`** — Both schemas exported from a single module, tested separately in `src/lib/schemas/cms.test.ts`. Consistent with the `auth.ts` pattern; schemas are independently testable.
C) Other (please describe after [Answer]: tag below)
[Answer]: C, I want all schemas to live in the src/lib/schemas folder. Do it also for schemas that are inlin or otherwise not in that directory to make it consistent and easy to find.
---
## Question 2
How should hook-level API errors be surfaced to the component?
Context: TanStack Query exposes `mutation.error` on the mutation object. Two approaches are used in this project:
A) **`mutation.error` prop** — component reads `mutation.error` directly and passes `{ message: mutation.error.message }` to `FormErrorBanner`. Pattern used by `InviteUserDialog` (`inviteUser.error`). No extra state.
B) **Local `useState<string | null>(null)`** — component owns a `serverError` string, set in the mutation `onError` callback. Pattern used by `LoginPage`. Allows custom i18n error messages per status code (e.g. 409 Conflict → "Name already in use").
C) Other (please describe after [Answer]: tag below)
[Answer]: B, also make it consistent accross the projects if possible.
aidlc-docs/features/master-cms-module/construction/plans/frontend-cms-page-nfr-questions.md
+3 -3
View File
@@ -18,7 +18,7 @@ C) **Custom** — Must start with `http://` or `https://`, but the rest is not v
D) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A
---
@@ -33,7 +33,7 @@ C) **Hooks + page + component tests** — In addition to B, dedicated tests for
D) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: C
---
@@ -48,4 +48,4 @@ B) **`type="text"`** — Visible. Easier to verify the pasted value is correct.
C) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A
aidlc-docs/features/master-cms-module/construction/plans/frontend-cms-page-nfr-requirements-plan.md
+4 -4
View File
@@ -10,10 +10,10 @@
## Execution Steps
- [ ] **Step 1** — Analyze answers; flag ambiguities
- [ ] **Step 2** — Generate `nfr-requirements.md`
- [ ] **Step 3** — Generate `tech-stack-decisions.md`
- [ ] **Step 4** — Update `aidlc-state.md`
- [x] **Step 1** — Analyze answers; flag ambiguities
- [x] **Step 2** — Generate `nfr-requirements.md`
- [x] **Step 3** — Generate `tech-stack-decisions.md`
- [x] **Step 4** — Update `aidlc-state.md`
- [ ] **Step 5** — Present completion message for approval
---