Adds frontend for cms page
This commit is contained in:
+242
@@ -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
|
||||
+22
@@ -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`
|
||||
+34
@@ -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.
|
||||
+3
-3
@@ -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
|
||||
|
||||
+4
-4
@@ -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
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user