docs(35-03): complete mail templates SPA editor plan

This commit is contained in:
2026-11-13 13:43:33 +01:00
parent f232076531
commit 95eed7ad98
3 changed files with 246 additions and 10 deletions

View File

@@ -1936,7 +1936,7 @@ Plans:
**Requirements**: TBD
**Depends on:** Phase 34
**Context:** postcard already loads plugin templates and layouts from `views/mail/` (`pact.HasMailTemplates`, `postcard.BootPlugin`); this phase adds the editable database layer, admin screens and image handling on top. To confirm in discussion: partials (WinterCMS mail partials), preview and test send, per-locale variants, and whether the screens live in cabana or in a plugin.
**Plans:** 2/4 plans executed
**Plans:** 3/4 plans executed
Plans:
**Wave 1**
@@ -1946,7 +1946,7 @@ Plans:
- [x] 35-02-PLAN.md — cabana Settings → Mail screens, two permission codes, reset/delete rules, drift notice and diff, server field types, preview and own-address test send, OpenAPI, en/pl copy
**Wave 3** *(blocked on Wave 2 completion)*
- [ ] 35-03-PLAN.md — admin SPA: CodeMirror decision note and checkpoint, codeeditor/colour/image fields, image picker, mail preview and test send, rebuilt dist
- [x] 35-03-PLAN.md — admin SPA: CodeMirror decision note and checkpoint, codeeditor/colour/image fields, image picker, mail preview and test send, rebuilt dist
**Wave 4** *(blocked on Wave 3 completion)*
- [ ] 35-04-PLAN.md — unit tests for the D-21 list and `scripts/check-phase35.sh` (incl. user and paymentgateway mail tests)

View File

@@ -4,16 +4,16 @@ milestone: v1.0
current_phase: 31
current_phase_name: Chat polish against WavePath clients
status: executing
stopped_at: Phase 31.2 context gathered
last_updated: "2026-11-13T12:41:26.779Z"
stopped_at: Completed 35-03-PLAN.md
last_updated: "2026-11-13T12:43:13.511Z"
last_activity: 2026-11-13
last_activity_desc: Phase 35 execution resumed (wave continue)
state_head: b8638aac667e73f83db5772f8c132412fc40a498
state_head: f23207653116e529ffdb10fdc7defb8d3212031b
progress:
total_phases: 52
completed_phases: 37
total_plans: 299
completed_plans: 286
completed_plans: 287
gsd_state_version: "1.0"
milestone_name: milestone
---
@@ -30,7 +30,7 @@ See: .planning/PROJECT.md (updated 2026-10-22)
## Current Position
Phase: 31 (Chat polish against WavePath clients) — READY TO EXECUTE
Plan: 3 of 4
Plan: 4 of 4
Status: Ready to execute
Last activity: 2026-11-13 — Phase 35 execution resumed (wave continue)
@@ -315,6 +315,7 @@ Progress: [████████░░] 82%
| Phase 33 P15 | 2h15m | 6 tasks | 70 files |
| Phase 35 P01 | 55 min | 5 tasks | 30 files |
| Phase 35 P02 | 77 | 4 tasks | 66 files |
| Phase 35 P03 | 22min | 6 tasks | 47 files |
## Accumulated Context
@@ -1107,6 +1108,8 @@ Recent decisions affecting current work:
- [Phase 35]: Image list/pick allows either mail permission; upload and Mail images singleton need system.manage_mail_layouts — Planner call for picker split (D-03 / UI-SPEC C4)
- [Phase 35]: Test-send is interactive-only; recipient is always the signed-in administrator email; limit 5/10min via cooler.Attempter — D-16/D-17 and research Pattern 7
- [Phase 35]: GET /mail/images documents AdminMailImagesResponse so meta.canUpload validates under OpenAPI conformance — SuccessMeta cannot carry canUpload; MarketplaceResponse pattern
- [Phase 35]: Task 3 approved all seven CodeMirror pins including @codemirror/view@6.43.15
- [Phase 35]: CodeMirror loads only from codeeditor/editor.ts; meta package and indentWithTab unused
### Pending Todos
@@ -1254,6 +1257,6 @@ Items acknowledged and carried forward from previous milestone close:
## Session Continuity
Last session: 2026-11-13T12:41:25.815Z
Stopped at: Phase 31.2 context gathered
Resume file: .planning/phases/31.2-wavepath-satellites-parity-and-close-out/31.2-CONTEXT.md
Last session: 2026-11-13T12:43:12.596Z
Stopped at: Completed 35-03-PLAN.md
Resume file: None

View File

@@ -0,0 +1,233 @@
---
phase: 35-mail-templates-and-layouts-editor
plan: 03
subsystem: ui
tags: [admin, codemirror, mailpreview, mailimage, colorpicker, boardwalk]
requires:
- phase: 35-02
provides: mail preview/test-send/images API routes and OpenAPI types
provides:
- mailpreview field with sandboxed iframe and test send
- codeeditor on CodeMirror 6 (lazy chunk) with approved exact pins
- colorpicker, mailimage, MailImagePicker, insertImage
- FormView footer record actions, meta.deletable, partial reload
- customized/outdated row badges and .summer-diff CSS kit
- rebuilt modules/boardwalk/dist
affects: [35-04, admin SPA mail screens]
actuals:
tokens: 26700
tasks: 6
commits: 15
plan_head_before: 9ea3159ba21668f413b7b2521361a1f6579179d0
plan_head_after: f23207653116e529ffdb10fdc7defb8d3212031b
tech-stack:
added:
- "@codemirror/state@6.7.6"
- "@codemirror/view@6.43.15"
- "@codemirror/language@6.13.1"
- "@codemirror/commands@6.11.1"
- "@codemirror/lang-html@6.4.12"
- "@codemirror/lang-css@6.3.1"
- "@lezer/highlight@1.2.5"
patterns:
- "Lazy CodeMirror chunk via dynamic import('../codeeditor/editor'), TipTap-style"
- "FORM_PARTIAL_RELOAD inject for partial re-fetch after save/action"
key-files:
created:
- admin/src/components/form/fields/MailPreviewField.vue
- admin/src/components/form/fields/CodeEditorField.vue
- admin/src/components/form/codeeditor/editor.ts
- admin/src/components/form/fields/ColorPickerField.vue
- admin/src/components/form/fields/MailImageField.vue
- admin/src/components/mail/MailImagePicker.vue
- admin/src/components/mail/insertImage.ts
- admin/tests/browser/codeeditor-smoke.test.ts
- .planning/notes/2026-11-06-admin-code-editor-codemirror.md
modified:
- admin/package.json
- admin/package-lock.json
- admin/src/components/form/registry.ts
- admin/src/components/form/fields/MarkdownField.vue
- admin/src/views/FormView.vue
- admin/src/views/SettingsFormView.vue
- admin/src/components/list/RowStateBadges.vue
- admin/src/styles/main.css
- modules/boardwalk/dist
- modules/phrasebook/backend/lang/en/lang.yaml
- modules/phrasebook/backend/lang/pl/lang.yaml
- docs/backend/admin-spa.md
- docs/backend/forms.md
key-decisions:
- "Task 3: Jakub approved all seven CodeMirror/lezer pins including @codemirror/view@6.43.15 (latest stable, past 7-day cooldown); no note/STACK rewrite"
- "CodeMirror loads only from codeeditor/editor.ts; meta package and indentWithTab unused"
patterns-established:
- "Package legitimacy: decision note + STACK row + blocking-human checkpoint before npm install"
- "Mail image URLs always come from the server; insertImage only escapes"
requirements-completed: [D-03, D-07, D-08, D-09, D-10, D-11, D-16, D-17, D-18, D-19, D-20, D-21]
coverage:
- id: D1
description: "mailpreview sandboxed srcdoc preview and test-send with 429 disable"
requirement: D-16
verification:
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#MailPreviewField
status: pass
human_judgment: false
- id: D2
description: "codeeditor CodeMirror 6 lazy load, Tab/Mod+S/Esc keyboard contract"
requirement: D-09
verification:
- kind: automated_ui
ref: admin/tests/browser/codeeditor-smoke.test.ts
status: pass
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#CodeEditorField
status: pass
human_judgment: false
- id: D3
description: "CodeMirror packages exactly pinned after human legitimacy gate"
requirement: D-09
verification:
- kind: other
ref: admin/package.json + decision note integrity match
status: pass
human_judgment: true
rationale: "Package legitimacy was a blocking-human checkpoint (Task 3); automation cannot replace that trust step"
- id: D4
description: "colorpicker, mailimage, MailImagePicker, insertImage, markdown mailImages"
requirement: D-18
verification:
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#insertImage|ColorPicker|MailImage
status: pass
human_judgment: false
- id: D5
description: "FormView footer actions, deletable, partial reload, badges, diff kit, boardwalk dist"
requirement: D-21
verification:
- kind: unit
ref: admin/tests/form/mail-smoke.test.ts#RowStateBadges
status: pass
- kind: other
ref: scripts/check-admin-dist.sh
status: pass
human_judgment: false
duration: 22min
completed: 2026-11-13
status: complete
---
# Phase 35 Plan 03: Mail templates SPA editor Summary
**Admin SPA mail editor: sandboxed mailpreview, CodeMirror codeeditor (human-approved pins), colour/image picker, FormView footer actions, badges, and rebuilt boardwalk dist**
## Performance
- **Duration:** 22 min (continuation from Task 3 checkpoint; wall clock from resume)
- **Started:** 2026-11-13T12:19:03Z
- **Completed:** 2026-11-13T12:41:00Z
- **Tasks:** 6/6
- **Files modified:** ~47 across plan window (includes concurrent phase-31 docs commits in the same HEAD range)
## Accomplishments
- `mailpreview` posts drafts to `/mail/preview` and `/mail/test-send`; iframe uses empty `sandbox` and server `srcdoc` only
- CodeMirror 6 installed after Task 3 approval of all seven exact pins (including `@codemirror/view@6.43.15`); lockfile integrity matches the decision note; lazy `editor-*.js` chunk carries `cm-summer-action`
- `colorpicker`, `mailimage`, `MailImagePicker`, and `insertImage` with markdown/codeeditor Insert image; Preview toggle hidden when `mailImages` is set
- FormView footer RecordActions when there is no preview screen; `meta.deletable === false` hides Delete; partials reload via `FORM_PARTIAL_RELOAD`; customized/outdated badges; `.summer-diff` kit
- `modules/boardwalk/dist` rebuilt and `scripts/check-admin-dist.sh` passes
## Task Commits
1. **Task 1: mailpreview field** - `52204e17` (feat)
2. **Task 2: CodeMirror decision note + STACK.md** - `6e0d4bbc` (docs)
3. **Task 3: human pin approval** - none (answer recorded below)
4. **Task 4 RED: failing codeeditor tests** - `7e2c0117` (test)
5. **Task 4 GREEN: CodeMirror install + codeeditor** - `9975cf4b` (feat)
6. **Task 5 RED: failing insertImage/colorpicker tests** - `3e29e604` (test)
7. **Task 5 GREEN: picker, colour, mailimage, insert** - `68e1d36f` (feat)
8. **Task 6 RED: failing row-badge test** - `aba51280` (test)
9. **Task 6 GREEN: FormView/lists/diff/docs** - `d1334067` (feat)
10. **Task 6 dist rebuild** - `36f34108` (build)
11. **Deviation: mail.picker lang keys** - `8969806d` (fix)
**Plan metadata:** (this SUMMARY commit)
## Task 3 answer (verbatim)
> approved — pin the best versions. Orchestrator judgment: keep all seven pins as in the decision note, including @codemirror/view@6.43.15 (latest stable, maintainer marijn, integrity matches note, now ~25 days old / past 7-day cooldown). No note/STACK rewrite needed unless integrity drifts. Proceed to install exactly those pins in Task 4.
**Installed versions:** `@codemirror/state@6.7.6`, `@codemirror/view@6.43.15`, `@codemirror/language@6.13.1`, `@codemirror/commands@6.11.1`, `@codemirror/lang-html@6.4.12`, `@codemirror/lang-css@6.3.1`, `@lezer/highlight@1.2.5` (exact; lockfile integrity matched the decision note).
## Files Created/Modified
- `admin/src/components/form/fields/MailPreviewField.vue` - live preview + test send
- `admin/src/components/form/fields/CodeEditorField.vue` / `codeeditor/editor.ts` - lazy CodeMirror
- `admin/src/components/mail/insertImage.ts` / `MailImagePicker.vue` - library insert/choose
- `admin/src/components/form/fields/ColorPickerField.vue` / `MailImageField.vue`
- `admin/src/views/FormView.vue` - footer actions, deletable, partial reload
- `modules/boardwalk/dist` - embedded admin rebuild
- `.planning/notes/2026-11-06-admin-code-editor-codemirror.md` - dependency decision
## Decisions Made
- Task 3 approved all seven pins including the [SUS] too-new `@codemirror/view@6.43.15`; no pin downgrade
- CodeMirror confined to `codeeditor/editor.ts` dynamic import (T-35-21 / T-35-SC)
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 2 - Missing Critical] mail.picker phrasebook keys**
- **Found during:** Task 6 verification (`go test ./modules/phrasebook`)
- **Issue:** SPA used UI-SPEC picker keys (`insert`, `use`, `uploading`, empty/error copy) not present in backend lang YAML
- **Fix:** Added en/pl keys under `mail.picker` per UI-SPEC copywriting
- **Files modified:** `modules/phrasebook/backend/lang/en/lang.yaml`, `pl/lang.yaml`
- **Verification:** `go test -short ./modules/phrasebook` and `./...` pass
- **Committed in:** `8969806d`
**2. [Rule 1 - Bug] ColorPicker swatch sync without parent v-model**
- **Found during:** Task 5 tests
- **Issue:** Typing a valid hex did not update `lastValid` until props echoed
- **Fix:** Update `lastValid` in `onText` when HEX matches
- **Files modified:** `ColorPickerField.vue`
- **Committed in:** `68e1d36f`
---
**Total deviations:** 2 auto-fixed (1 missing critical, 1 bug)
**Impact on plan:** Required for phrasebook SPA key gate and colorpicker behaviour; no scope creep
## Issues Encountered
- Concurrent phase-31 docs commits interleaved on `master` during this plan window; staged only 35-03 paths
- Task 1 follow-ups (`rowStateCustomized` / mail-smoke TS2349) already clean at resume; DatepickerField timezone failures left deferred per instructions
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- SPA mail editor controls and embedded dist are ready for 35-04 (UAT / remaining phase work)
- Nothing pushed or tagged
## Self-Check: PASSED
- Key files exist: MailPreviewField, CodeEditorField, editor.ts, MailImagePicker, insertImage, decision note, boardwalk dist
- Commits found: 52204e17, 6e0d4bbc, 7e2c0117, 9975cf4b, 3e29e604, 68e1d36f, aba51280, d1334067, 36f34108, 8969806d
- `cm-summer-action` lives in `modules/boardwalk/dist/assets/editor-uDgt9VKj.js` (not an `index-*.js` entry chunk)
---
*Phase: 35-mail-templates-and-layouts-editor*
*Completed: 2026-11-13*