From 95eed7ad9814004c6c894e659b45bb74c65801b4 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 13:43:33 +0100 Subject: [PATCH] docs(35-03): complete mail templates SPA editor plan --- .planning/ROADMAP.md | 4 +- .planning/STATE.md | 19 +- .../35-03-SUMMARY.md | 233 ++++++++++++++++++ 3 files changed, 246 insertions(+), 10 deletions(-) create mode 100644 .planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 2b39e480..972f0267 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -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) diff --git a/.planning/STATE.md b/.planning/STATE.md index 9640a879..90880812 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -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 diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md new file mode 100644 index 00000000..2bef551b --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-03-SUMMARY.md @@ -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*