docs(35-06): complete finished mail layouts and CSS inlining plan
This commit is contained in:
@@ -0,0 +1,289 @@
|
||||
---
|
||||
phase: 35-mail-templates-and-layouts-editor
|
||||
plan: 06
|
||||
subsystem: mail
|
||||
tags: [postcard, cabana, mail-layouts, branding, css-inlining, go-premailer, gap-closure]
|
||||
status: complete
|
||||
|
||||
requires:
|
||||
- phase: 35-05
|
||||
provides: TemplateBase / Catalog.TemplateFor / EnsureLocaleRows and migration 202611130001_mail_template_base_code (built on, not changed)
|
||||
provides:
|
||||
- WinterCMS default layout port (header with logo or site name, white card, copyright footer) in postcard's default.htm
|
||||
- built-in header and footer partials
|
||||
- layout keys siteName and year
|
||||
- Brand.SiteName (Branding Site name, mail.from display-name fallback) and the site_name column
|
||||
- CSS inlining at render through github.com/vanng822/go-premailer v1.38.0, with the per-layout disable_auto_inline_css opt-out
|
||||
- finished system layout (header, footer, side padding) and minimal layout (logo)
|
||||
affects: [35-07, sm-user-plugin follow-up, sm-paymentgateway-plugin follow-up, consumers with a replace to this checkout]
|
||||
|
||||
actuals:
|
||||
tokens: 38920
|
||||
tasks: 3
|
||||
commits: 5
|
||||
plan_head_before: fdc2094ffc01ea21eea80c944820d3357ffed589
|
||||
plan_head_after: f1cebf1d70f3ba70da6c08c6f90ad86992242d78
|
||||
|
||||
tech-stack:
|
||||
added:
|
||||
- "github.com/vanng822/go-premailer v1.38.0 (direct)"
|
||||
patterns:
|
||||
- "Inline after render: validateHTML, then go-premailer, then validateHTML again; HTML without a style element is left as it is; an inliner error keeps the style block and warns (rate-limited)"
|
||||
- "Per-layout opt-out mirrored in three places: file header key, layouts column, Draft field"
|
||||
- "Tests that check what fills the CSS slots use a no-op inliner seam (mailer.inline) or the opt-out flag"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- modules/postcard/inline.go
|
||||
- modules/postcard/assets/partials/header.htm
|
||||
- modules/postcard/assets/partials/footer.htm
|
||||
- .planning/notes/2026-11-13-mail-layouts-css-inlining.md
|
||||
modified:
|
||||
- modules/postcard/assets/default.htm
|
||||
- modules/postcard/assets/system.htm
|
||||
- modules/postcard/assets/minimal.htm
|
||||
- modules/postcard/assets/brand.css.tmpl
|
||||
- modules/postcard/templates.go
|
||||
- modules/postcard/mailer.go
|
||||
- modules/postcard/brand.go
|
||||
- modules/postcard/store.go
|
||||
- modules/postcard/editor.go
|
||||
- modules/cabana/mail_admin.go
|
||||
- modules/cabana/mail_routes.go
|
||||
- modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
|
||||
- modules/cabana/backendscreens/models/maillayout/fields.yaml
|
||||
- modules/phrasebook/backend/lang/en/lang.yaml
|
||||
- modules/phrasebook/backend/lang/pl/lang.yaml
|
||||
- go.mod
|
||||
- go.sum
|
||||
- .planning/research/STACK.md
|
||||
- .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md
|
||||
|
||||
key-decisions:
|
||||
- "CSS inlining runs inside postcard's render path with go-premailer v1.38.0 default options, so preview, test send and sends match; supersedes D-10's inlining claim"
|
||||
- "Layouts opt out of inlining with disable_auto_inline_css (file header key, layouts column, layout form switch), WinterCMS's option name; built-in layouts all inline"
|
||||
- "Branding gains Site name; empty falls back to the display name of mail.from; the default and system layouts show logo or name in the header and a language-neutral footer (© year name)"
|
||||
- "HTML without a style element is not passed through the inliner: x/net/html would re-serialise it (attribute order, html/head/body wrappers) with nothing to inline"
|
||||
- "35-01's default.htm-unchanged gate is lifted; the default layout is WinterCMS's default layout built on the new header and footer partials"
|
||||
|
||||
patterns-established:
|
||||
- "Mail layout keys: Content, Subject, css, brandCss, logoUrl, siteName, year"
|
||||
- "Header partial arguments: logo, body, url (optional); footer partial argument: body (Markdown)"
|
||||
|
||||
requirements-completed: [G-35-8, D-10, D-11, D-12, D-14]
|
||||
|
||||
coverage:
|
||||
- id: D1
|
||||
description: "Default layout ports WinterCMS's default layout: header with the Branding logo (alt = site name) or the site name, inner-body card, styled button, footer with © year and site name; mail.from fallback; no header row without name and logo"
|
||||
requirement: G-35-8
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke/default_layout"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D2
|
||||
description: "Branding Site name: site_name column (migration 202611130002), Brand.SiteName read by the DB source, cabana form field (trimmed, max 255), Branding preview shows it"
|
||||
requirement: D-10
|
||||
verification:
|
||||
- kind: integration
|
||||
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/branding"
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: "modules/postcard/brand_smoke_test.go#TestMailBrandSmoke/precedence"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D3
|
||||
description: "CSS inlined at render (button carries the brand colour inline, DOCTYPE and classes kept, media query stays in a style element), per-layout opt-out from file header, DB column and draft, inliner error falls back with one warning, text part unchanged"
|
||||
requirement: D-14
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "modules/postcard/partials_smoke_test.go#TestMailPartialsSmoke/inline"
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: "modules/postcard/editor_smoke_test.go#TestMailEditorSmoke/inline_flag"
|
||||
status: pass
|
||||
- kind: integration
|
||||
ref: "modules/cabana/mail_screens_smoke_test.go#TestMailScreensSmoke/layouts"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D4
|
||||
description: "System layout has the header, footer and 35px side padding; minimal layout shows the logo above the message; all three built-in layouts render the button with the inlined brand colour"
|
||||
requirement: D-12
|
||||
verification:
|
||||
- kind: unit
|
||||
ref: "modules/postcard/partials_smoke_test.go#TestMailPartialsSmoke/built_in_layouts"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D5
|
||||
description: "sm-user-plugin and sm-paymentgateway-plugin mail tests pass against this checkout through scratch modfiles, their trees unchanged"
|
||||
requirement: D-11
|
||||
verification:
|
||||
- kind: other
|
||||
ref: "go test -mod=mod -modfile=<scratch>/go.mod (sm-user-plugin: TestMail, TestPolishMailSubjects -short; sm-paymentgateway-plugin with GOWORK=off: TestMailCatalog, TestMailTracer, TestMailersMatrixSmoke without -short); git status --porcelain empty in both"
|
||||
status: pass
|
||||
human_judgment: false
|
||||
- id: D6
|
||||
description: "Mail in the built-in layouts looks finished in real mail clients and the admin preview (UAT test 8 re-run for the built-in layouts)"
|
||||
requirement: G-35-8
|
||||
verification: []
|
||||
human_judgment: true
|
||||
rationale: "Visual rendering across mail clients (webmail, Outlook) and the admin preview needs a human; automated tests assert markup and inlined styles only"
|
||||
|
||||
duration: 33min
|
||||
completed: 2026-11-13
|
||||
---
|
||||
|
||||
# Phase 35 Plan 06: Finished built-in mail layouts and CSS inlining Summary
|
||||
|
||||
**WinterCMS's default layout (logo or site-name header, white card, © year footer) in postcard's default, system and minimal layouts, a Branding Site name with the mail.from fallback, and CSS inlined onto elements at render through go-premailer v1.38.0, with a per-layout disable_auto_inline_css opt-out (G-35-8)**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 33 min
|
||||
- **Started:** 2026-11-13T19:44:45Z
|
||||
- **Completed:** 2026-11-13T20:17:36Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 34
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- `default.htm` is WinterCMS's default layout: `table.wrapper.layout-default`, the `header` partial with `img.logo` (alt = site name) or the name in a span, the `inner-body` card, and the `footer` partial with `© <year> <site name>` (or `© <year>`). Its text wrapper ends with the footer's text section.
|
||||
- `system.htm` has the same header and footer, and its content cell keeps WinterCMS's 35px side padding. `minimal.htm` shows the logo above the message.
|
||||
- Branding has a Site name (`site_name`, `Brand.SiteName`). When it is empty, the display name of `mail.from` is used. The cabana form field, the en/pl copy and the Branding preview all carry it.
|
||||
- postcard inlines the rendered HTML with go-premailer in preview, test send and sends. The DOCTYPE and classes are kept, and media queries stay in a style element. Each layout can opt out through a file header key, a database column (with a CSS-tab switch in the layout form) or `Draft.DisableAutoInlineCSS`. An inliner error sends the style block only and logs a rate-limited warning.
|
||||
- The decision note and the STACK.md row went in before go.mod changed. The core consumer plugins pass against this checkout without any change to their trees.
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: default layout with header, footer and site name (tracer)** - `093529d4` (feat)
|
||||
2. **Task 2: decision note and STACK row** - `dcd0ae53` (docs); **CSS inlining with the per-layout opt-out** - `d3207335` (feat)
|
||||
3. **Task 3: system and minimal layouts** - `09a5338d` (feat); **UI-SPEC copy** - `f1cebf1d` (docs)
|
||||
|
||||
**Plan metadata:** recorded in the SUMMARY commit (docs)
|
||||
|
||||
## Interfaces for 35-07
|
||||
|
||||
- **Migrations:** `202611130002_mail_brand_site_name` (`system_mail_brand_settings.site_name TEXT NOT NULL DEFAULT ''`), `202611130003_mail_layout_disable_auto_inline_css` (`system_mail_layouts.disable_auto_inline_css BOOLEAN NOT NULL DEFAULT FALSE`). Both roll back by dropping the column.
|
||||
- **Layout keys (both wrappers):** `Content`, `Subject`, `css`, `brandCss`, `logoUrl`, plus the new `siteName` (Branding site name trimmed, else the `net/mail` display name of `mail.from`, else empty) and `year` (int, the current year).
|
||||
- **Partials:** `header` (`postcard::mail.partials.header`), with arguments `logo` (URL), `body` (name) and `url` (optional link). Its HTML is `<tr><td class="header">` holding `img.logo` (alt = body), or `<span>body</span>` when there is no logo. Its text is the name. `footer` (`postcard::mail.partials.footer`) takes `body` (Markdown). Its HTML is a `<tr>` with `table.footer` and `td.content-cell`; its text is a line of 19 dashes followed by the body. `builtinPartials` now has 6 entries, so SyncIndex writes 2 more partial rows.
|
||||
- **Exported fields:** `Brand.SiteName`, `LayoutFile.DisableAutoInlineCSS`, `LayoutOverride.DisableAutoInlineCSS`, `Draft.DisableAutoInlineCSS`, `cabana.MailBrandSetting.SiteName`, `cabana.MailLayout.DisableAutoInlineCSS`.
|
||||
- **Header key / column:** `disable_auto_inline_css` (`true`, `1` or `yes`, any case). SyncIndex mirrors it into rows that are not customized, and ResetOverride writes the file's value back.
|
||||
- **go.mod:** direct `github.com/vanng822/go-premailer v1.38.0`. Raised: `golang.org/x/net` v0.58.0→v0.62.0, `golang.org/x/crypto` v0.57.0→v0.58.0, `golang.org/x/text` v0.42.0→v0.43.0, `golang.org/x/term` v0.46.0→v0.47.0. Indirect, raised: `golang.org/x/sys` v0.48.0→v0.49.0, `golang.org/x/sync` v0.23.0→v0.24.0. Indirect, added: `github.com/PuerkitoBio/goquery` v1.13.0, `github.com/andybalholm/cascadia` v1.3.4, `github.com/inbucket/html2text` v1.0.0, `github.com/vanng822/css` v1.0.1, `github.com/olekukonko/tablewriter` v1.0.7, `github.com/olekukonko/errors` v1.1.0, `github.com/olekukonko/ll` v0.0.9, `github.com/fatih/color` v1.18.0, `github.com/mattn/go-colorable` v0.1.14, `github.com/mattn/go-isatty` v0.0.20, `github.com/ssor/bom` v0.0.0-20170718123548-6386211fdfcf. examples/hello/go.mod and go.sum are unchanged.
|
||||
- **Copy keys (en/pl):** new `mail.brand.site_name`, `mail.brand.site_name_comment`, `mail.layout.disable_inline_css`, `mail.layout.disable_inline_css_comment`; changed `mail.brand.logo_comment`.
|
||||
- **Tests:** `TestMailBrandSmoke/default_layout` (new), `TestMailPartialsSmoke/inline` (new), `TestMailPartialsSmoke/built_in_layouts` (rewritten), `TestMailEditorSmoke/inline_flag` (new, Docker), `TestMailScreensSmoke/branding` and `/layouts` (extended), `TestMailBrandSmoke/precedence` (now checks site_name too). Test seams are `mailer.inline` (unexported; nil means `inlineCSS`), `noInline`, `unstyled`, `buttonStyle` and `copyright` in the postcard tests.
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `modules/postcard/inline.go` wraps go-premailer and turns a panic into an error.
|
||||
- `modules/postcard/assets/{default,system,minimal}.htm` are the finished built-in layouts. `assets/partials/{header,footer}.htm` are the new partials. `brand.css.tmpl` gains the `img.logo` rule and loses the `.wrapper.layout-system .content-cell` override.
|
||||
- `modules/postcard/templates.go` holds the siteName/year keys, the opt-out parse (`headerBool`, `disableInlineKey`) and the `inlineHTML` step in `renderParts`.
|
||||
- `modules/postcard/mailer.go` holds the `siteName` fallback. `options` now passes `inline` and `warn` to the file version as well.
|
||||
- `modules/postcard/store.go` has the two migrations, the site_name read, the opt-out read, SyncIndex mirroring and the reset.
|
||||
- `modules/postcard/editor.go` handles the brand draft site name and the layout draft opt-out.
|
||||
- `modules/cabana/*`: `MailBrandSetting.SiteName`, `MailLayout.DisableAutoInlineCSS`, the draft mapping (`boolValue`), the form fields and the save validation with the opt-out.
|
||||
- The docs are the postcard and cabana READMEs and `docs/services/mail.md` (CSS inlining section, built-in layouts, partials, Branding). The planning docs are the decision note, STACK.md and 35-UI-SPEC.md (C5, C12).
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- Inlining uses go-premailer's default options: classes are kept and widths and heights are mirrored to attributes. Leftover rules go back into one style element in the head, marked `!important`, so after inlining the style block holds only those rules.
|
||||
- HTML with no style element skips the inliner. There is nothing to inline, and x/net/html v0.62 would otherwise re-serialise the fragment (attribute order, html/head/body wrappers).
|
||||
- Inliner warnings are now logged on the file-version path too: `mailer.options` sets `warn`, which used to be set only on the override path.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 2 - Missing critical] A panic in the inliner becomes an error**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** goquery or the CSS parser could panic on unusual HTML, and a panic would stop the send (T-35-36).
|
||||
- **Fix:** `inlineCSS` recovers the panic and returns an error, which takes the style-block fallback and logs a warning.
|
||||
- **Files modified:** modules/postcard/inline.go
|
||||
- **Committed in:** d3207335
|
||||
|
||||
**2. [Rule 1 - Bug] HTML without a style element is no longer re-serialised**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** Fragments with no CSS, such as `<main>{{ .Content }}</main>`, came back wrapped in html/head/body with their attributes reordered, although nothing had been inlined.
|
||||
- **Fix:** `inlineHTML` returns the HTML as it is when it has no `<style` element.
|
||||
- **Files modified:** modules/postcard/templates.go
|
||||
- **Committed in:** d3207335
|
||||
|
||||
**3. [Rule 2 - Missing critical] The inliner warning is logged for the file version**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** `opts.warn` was nil on the file-version path, so an inliner failure in ordinary mail went unlogged.
|
||||
- **Fix:** `mailer.options` sets `warn: m.warn` and `inline: m.inline`.
|
||||
- **Files modified:** modules/postcard/mailer.go
|
||||
- **Committed in:** d3207335
|
||||
|
||||
**4. [Rule 2 - Correctness] Layout save validation renders with the opt-out**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** cabana's save validation built the layout draft without the switch, so the result it checked could differ from what is sent.
|
||||
- **Fix:** The `mailLayoutsAdmin.validate` draft carries `DisableAutoInlineCSS`. The `boolValue` helper reads the switch from preview payloads.
|
||||
- **Files modified:** modules/cabana/mail_admin.go, modules/cabana/mail_routes.go
|
||||
- **Committed in:** d3207335
|
||||
|
||||
**5. [Rule 3 - Blocking] The consumer check needed GOWORK=off for sm-paymentgateway-plugin**
|
||||
- **Found during:** Task 2 verify
|
||||
- **Issue:** That repository has a go.work, and `-modfile` is refused in workspace mode.
|
||||
- **Fix:** Ran its check with `GOWORK=off`. Its go.mod also replaces the framework with `../summercms.go` (Replace.Dir confirmed). Its TestMailTracer and TestMailersMatrixSmoke skip under `-short`, so they were also run without `-short` (Docker), and they pass. `git status --porcelain` stayed empty in both repositories.
|
||||
|
||||
**6. [Test seam] The no-op inliner is a mailer field, not a package variable**
|
||||
- **Found during:** Task 2
|
||||
- **Issue:** Swapping a package variable would race with parallel tests (TestBrand uses t.Parallel).
|
||||
- **Fix:** Added the unexported field `mailer.inline`. Tests that check what fills the CSS slots (style block contents and order) use `noInline` or the opt-out flag. Tests of the delivered markup compare HTML with its `style` attributes stripped.
|
||||
|
||||
**7. [CLAUDE.md] The TDD RED phase was verified but not committed on its own**
|
||||
- **Found during:** Tasks 2 and 3
|
||||
- **Issue:** CLAUDE.md requires `go test ./...` to be green at every commit, so a separate failing `test(...)` commit is not allowed.
|
||||
- **Fix:** RED was run and checked with `msd_run check tdd-red-evidence`; both runs returned `RED_EVIDENCE_OK`. The records are `35-06-task2-red-evidence.json` and `35-06-task3-red-evidence.json` in the session scratchpad, built from go test JSON converted to JUnit. Each test landed with its implementation in the plan's listed feat commit. Before that, Task 2's struct fields were added with no behaviour so the RED test compiled.
|
||||
|
||||
**8. [Acceptance wording] Two grep criteria print more lines than "one"**
|
||||
- `grep -n "site_name" .../mailbrandsetting/fields.yaml` prints 3 lines: the field key, plus the label and comment keys `mail.brand.site_name[_comment]` the plan prescribes.
|
||||
- `grep -n 'partial "footer"' modules/postcard/assets/system.htm` prints 2 lines, one per wrapper. The plan's action requires both: the text wrapper "ends with the footer's text form".
|
||||
- Both criteria are met in substance; the counts follow from the plan's own copy keys and text wrapper.
|
||||
|
||||
**9. [Scope] examples/hello go.mod and go.sum are unchanged**
|
||||
- `go mod tidy` there would have rewritten about 90 unrelated lines of an already stale go.mod. The module builds and tests through go.work as it is (`go test ./...` passes), so it needed no go.sum lines.
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 9 (3 Rule 2, 1 Rule 1, 1 Rule 3, 1 test-seam choice, 1 CLAUDE.md-driven TDD commit shape, 2 notes on acceptance wording and scope).
|
||||
**Impact on plan:** The fixes make inlining safer and keep it from changing mail that has no CSS. The scope is unchanged, and nothing in a sibling repository was touched.
|
||||
|
||||
## TDD Gate Compliance
|
||||
|
||||
There is no separate `test(35-06)` RED commit. CLAUDE.md requires `go vet ./...` and `go test ./...` to be green at every commit. RED was verified before GREEN for both TDD tasks, with `RED_EVIDENCE_OK` from `check tdd-red-evidence`; the target tests were `TestMailPartialsSmoke/inline` and `TestMailPartialsSmoke/built_in_layouts`. The tests are committed in the feat commits d3207335 and 09a5338d.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- x/net/html v0.62 (raised by MVS) re-serialises the inlined HTML. Attribute order can change (for example `class` before `href` on the button), `<tbody>` is inserted, and void elements end with `/>`. Assertions on exact markup were moved to style-stripped comparisons. The consumer plugins' mail tests pass unchanged.
|
||||
- gofmt already reported `modules/cabana/mail_routes.go` and `modules/postcard/store_postgres_test.go` before this plan; this plan added no new gofmt diffs. They were not logged to deferred-items.md, because another session holds uncommitted edits in that file.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
| Flag | File | Description |
|
||||
|------|------|-------------|
|
||||
| threat_flag: availability | modules/postcard/templates.go (validateHTML) | validateHTML scans all rendered HTML, text included, for `javascript:`, `vbscript:` and `data:`. A Branding site name (or a `mail.from` display name) containing such text would make every message in the default and system layouts fail to render. Nothing checks the name for this at save time; cabana only trims it and caps it at 255 characters. An administrator would have to type it. Worth a save-time check in 35-07 or later. |
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None. No external service configuration is required. Follow-up outside this phase: consumers that build with a `replace` to this checkout need `go mod tidy` to pick up go-premailer's go.sum lines (see the decision note).
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- 35-07 can record G-35-8 as closed in the framework and bake the scratch-modfile consumer check into `check-phase35.sh --consumers`. Until then, `--consumers` fails on the siblings' missing go.sum lines, as the plan expected.
|
||||
- The plugin follow-up (user and paymentgateway layouts and templates, go.mod bumps) waits for the framework tag.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- Created files exist: modules/postcard/inline.go, modules/postcard/assets/partials/header.htm, modules/postcard/assets/partials/footer.htm, .planning/notes/2026-11-13-mail-layouts-css-inlining.md.
|
||||
- Commits exist: 093529d4, dcd0ae53, d3207335, 09a5338d, f1cebf1d.
|
||||
- The decision note commit (dcd0ae53) is older than the go.mod commit (d3207335, the feat subject).
|
||||
- `go vet ./...`, `go test -short ./...`, `go test ./modules/postcard ./modules/cabana` (Docker), `cd examples/hello && go test ./...`, `docs:build --check`, `TestCommandsDocumented|TestDocsTree`, `check-phase35.sh --additive` and `check-admin-openapi.sh --check` all pass.
|
||||
|
||||
---
|
||||
*Phase: 35-mail-templates-and-layouts-editor*
|
||||
*Completed: 2026-11-13*
|
||||
Reference in New Issue
Block a user