diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md new file mode 100644 index 00000000..3dae203b --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-06-SUMMARY.md @@ -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=/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 `© ` (or `© `). 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 `` holding `img.logo` (alt = body), or `body` when there is no logo. Its text is the name. `footer` (`postcard::mail.partials.footer`) takes `body` (Markdown). Its HTML is a `` 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 `
{{ .Content }}
`, 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 `` 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*