From 2bf9081c1bd8385b45210ead8524eda5512b3ca1 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 11:06:43 +0100 Subject: [PATCH] feat(postcard): mail branding and the logo URL - Brand, DefaultBrand and CompileBrandCSS: thirteen colours, each checked as a six-digit hex colour, compiled into CSS for plain elements and the built-in layouts and partials - once the branding row exists its compiled CSS replaces mail.brandCss; mail.css still follows, and the file version sent after a failing override keeps the Branding - layouts get logoUrl, built per send from storage.uploads.public_url or app.url through attach.AbsolutePublicURL; a logo that cannot be shown is left out with a rate-limited warning - Editor previews and validates a Branding draft (rule colour) Plan 35-01, task 5. --- docs/services/mail.md | 16 +- modules/postcard/README.md | 61 +++- modules/postcard/assets/brand.css.tmpl | 201 ++++++++++++ modules/postcard/brand.go | 128 ++++++++ modules/postcard/brand_smoke_test.go | 400 ++++++++++++++++++++++++ modules/postcard/editor.go | 40 ++- modules/postcard/mailer.go | 27 +- modules/postcard/override_smoke_test.go | 44 ++- modules/postcard/store.go | 80 ++++- modules/postcard/templates.go | 4 + 10 files changed, 974 insertions(+), 27 deletions(-) create mode 100644 modules/postcard/assets/brand.css.tmpl create mode 100644 modules/postcard/brand.go create mode 100644 modules/postcard/brand_smoke_test.go diff --git a/docs/services/mail.md b/docs/services/mail.md index a42774a6..a18d8856 100644 --- a/docs/services/mail.md +++ b/docs/services/mail.md @@ -14,7 +14,7 @@ A plugin implements `pact.HasMailTemplates`: it returns its embedded `views/mail The file format is WinterCMS's: an INI header with the `subject`, the `layout` alias and a `description`, a `==` line, then a Markdown body with Go template variables such as `{{ .name }}`. A layout has a header, a text wrapper and an HTML wrapper, separated by `==` lines, each with `{{ .Content }}` where the message goes. A template without a `layout` uses the built-in `default` layout; see [Built-in layouts](#built-in-layouts). -Each message gets an HTML part, rendered from the Markdown, and a plain-text part. `mail.css` and `mail.brandCss` are inlined into the layout's style block. +Each message gets an HTML part, rendered from the Markdown, and a plain-text part. `mail.css` and the brand CSS go into the layout's style block; see [Branding](#branding). ## Partials @@ -61,6 +61,20 @@ Three layouts are available to every plugin's templates without declaring an ali A plugin's own alias wins over `system` and `minimal`; `default` cannot be redefined. +## Branding + +A layout's style block has a brand slot, `{{ .brandCss }}`, before `{{ .css }}`. Until the branding settings are saved for the first time, the brand slot holds `mail.brandCss` from the configuration. From the first save on, it holds CSS that postcard compiles from the saved colours, and `mail.brandCss` is no longer used. `mail.css` is applied either way. + +The settings are thirteen colours: the page and content backgrounds, the header, footer, heading, text and link colours, the button text and the primary, positive and negative button backgrounds, the panel background and the table border. Each is a six-digit hexadecimal colour such as `#2da7c7`, and one left empty takes WinterCMS's default. The compiled CSS styles plain elements (the page, links, headings, paragraphs, tables) as well as the built-in layouts and partials, so it shows in any layout that has the style block. + +The settings also hold a logo. A layout shows it where it uses `{{ .logoUrl }}`: + +```text +{{ if .logoUrl }}{{ end }} +``` + +A mail client needs an absolute address, so the logo's URL is built at send time from the configuration: `storage.uploads.public_url` when it is set, otherwise `app.url` with `storage.uploads.public_path_prefix`; see [Absolute URLs for mail](storage.md#absolute-urls-for-mail). Set one of them, or the logo is left out and a warning is logged. + ## Sample values for previews A preview of a template has no caller to pass its variables. A template can therefore give sample values in its header, one key per variable: `sample.` followed by the variable's path, in the variable's own case. diff --git a/modules/postcard/README.md b/modules/postcard/README.md index 64202862..a81e25a4 100644 --- a/modules/postcard/README.md +++ b/modules/postcard/README.md @@ -12,7 +12,7 @@ postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTem ## Role in the framework -A service module on `backpack`, `compass` and `pact`; `party` registers the templates plugins contribute, and `lagoon` runs `postcard.Migrations` with the framework's other migrations. postcard does not import `lagoon`: it finds the database through `backpack`. It is separate so mail rendering and delivery can be tested and swapped (memory, log, SMTP) without touching the code that sends. +A service module on `backpack`, `compass` and `pact`; `party` registers the templates plugins contribute, and `lagoon` runs `postcard.Migrations` with the framework's other migrations. postcard does not import `lagoon`: it finds the database through `backpack`, and uses only lagoon's `attach` package, for the logo's URL. It is separate so mail rendering and delivery can be tested and swapped (memory, log, SMTP) without touching the code that sends. Use cases: @@ -26,10 +26,11 @@ Use cases: - WinterCMS file format: an INI header (`subject`, `layout`, `description`), a `==` separator, then a Markdown body rendered with Go `html/template` variables such as `{{ .name }}`. - Layouts with a header, a text wrapper and an HTML wrapper, referenced from templates by a short alias (`pact.HasMailTemplates` maps aliases to full names). Three layouts are built in and usable from any plugin's templates: `default`, `system` and `minimal`. - Partials: reusable blocks named `::mail.partials.`, loaded from `views/mail/partials/.htm` and declared through `pact.HasMailPartials`. Bodies and layouts call them with `{{ partial "" "key" value }}`. The partials `button`, `panel`, `table` and `subcopy` are built in. -- Every message gets an HTML part (Markdown converted with goldmark) and a plain-text part. `mail.css` and `mail.brandCss` are inlined into the layout's style block. +- Every message gets an HTML part (Markdown converted with goldmark) and a plain-text part. The brand CSS (`mail.brandCss`, or the saved Branding) and `mail.css` go into the layout's style block. - Safety checks: rendered HTML with script, iframe, object or embed tags, inline event handlers or `javascript:`/`vbscript:`/`data:` URLs is rejected; CR/LF in the subject or address headers is rejected; addresses are parsed with `net/mail`. - Drivers behind the `postcard.Driver` interface: `postcard.MemoryDriver` (keeps messages for tests), `postcard.LogDriver` (logs headers and the text part through `log/slog`, never the HTML or credentials), `postcard.SMTPDriver` (go-mail with an explicit TLS policy) and `postcard.FailDriver` (a deterministic failure for tests). - Database overrides: a customized row of `system_mail_templates` replaces a template's subject, body and layout, a customized row of `system_mail_layouts` or `system_mail_partials` replaces a layout or a partial, and `system_mail_layouts` also holds layouts that exist only in the database. The mailer reads them on every send, with no cache, in every process that publishes a `*gorm.DB`. A missing database, tables that are not migrated yet, or an override that does not render or fails the safety checks sends the file version. +- Branding: once the branding settings have been saved, the brand CSS is compiled from their colours (`postcard.CompileBrandCSS`) and replaces `mail.brandCss`, and layouts get the logo's absolute URL as `{{ .logoUrl }}`. - Sample values: a template's header may give its variables sample values with `sample.` keys. Previews and save checks use them, and show every other variable as a visible `[path]` placeholder. - An editor API for admin code (`postcard.Editor`): validate, preview and test-send an unsaved draft of a template, layout or partial through the same render path as a real send; one index row per file (`postcard.SyncIndex`) with a hash of the file for detecting that it changed under an override, and reset to the file version (`postcard.ResetOverride`). - No locale selection: callers pass the full template name, including any locale suffix. @@ -229,6 +230,41 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile } ``` +### Branding + +Layouts have two CSS slots, `{{ .brandCss }}` and `{{ .css }}`, and a logo slot, `{{ .logoUrl }}`. What fills the brand slot depends on the row with `id` 1 of `system_mail_brand_settings`: + +- While the row does not exist, the slot holds `mail.brandCss` from the configuration and `{{ .logoUrl }}` is empty, so an application that never saves Branding is unchanged. +- Once the row exists, the slot holds `postcard.CompileBrandCSS` of the row's colours, and `mail.brandCss` is no longer used. An empty colour column is that colour's default (`postcard.DefaultBrand`). + +`mail.css` fills `{{ .css }}` in both cases, after the brand CSS, with a layout's own CSS before it. + +The compiled CSS styles the page, links, headings, paragraphs and tables, and the classes of the built-in layouts and partials (`button button-primary`, `panel`, `table`, `subcopy`, `layout-system` and others), so the colours also apply in a plugin's layout that has the style block and no brand classes of its own. A colour must be a six-digit hexadecimal colour such as `#2da7c7`; `postcard.CompileBrandCSS` refuses anything else with an error naming the column. If a stored colour is invalid at send time, a warning is logged and `mail.brandCss` is used. + +| Column | `postcard.Brand` field | Default | +|--------|------------------------|---------| +| `body_bg` | `BodyBg` | `#f5f8fa` | +| `content_bg` | `ContentBg` | `#ffffff` | +| `header_color` | `HeaderColor` | `#bbbfc3` | +| `footer_color` | `FooterColor` | `#aeaeae` | +| `heading_color` | `HeadingColor` | `#2f3133` | +| `text_color` | `TextColor` | `#74787e` | +| `link_color` | `LinkColor` | `#2da7c7` | +| `button_text_color` | `ButtonTextColor` | `#ffffff` | +| `button_primary_bg` | `ButtonPrimaryBg` | `#d66829` | +| `button_positive_bg` | `ButtonPositiveBg` | `#52a838` | +| `button_negative_bg` | `ButtonNegativeBg` | `#e01346` | +| `panel_bg` | `PanelBg` | `#edeff2` | +| `table_border_color` | `TableBorderColor` | `#edeff2` | + +The row's `logo_file_id` names a public `system_files` row. Its URL is not stored: on every send it is built from the configuration with `attach.AbsolutePublicURL`, from `storage.uploads.public_url`, or from `app.url` and `storage.uploads.public_path_prefix`, so a worker process and `serve` produce the same absolute URL and a changed CDN address applies at once. When the file is missing or not public, or neither base is configured, `{{ .logoUrl }}` is empty, a warning is logged at most once a minute, and the mail is sent. A layout that shows the logo guards it: + +```text +{{ if .logoUrl }}{{ end }} +``` + +A mail that falls back to its file version because an override failed still gets the Branding. + ### Sample values A preview has no caller to supply variables, so a template can carry sample values in its header. A key is `sample.` followed by the variable's path, and the path keeps its case, because template variables are case-sensitive: @@ -289,8 +325,9 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t | `postcard.KindTemplate` | The template's full name | `Subject`, `Body`, `Layout` (a layout code; empty keeps the file's layout) | The template with its sample values and placeholders. | | `postcard.KindLayout` | The layout's code | `HTML`, `Text`, `CSS` | The layout around postcard's sample message. | | `postcard.KindPartial` | The partial's full name | `HTML`, `Text` | A message that is one call of the partial, with a placeholder for every argument it reads. | +| `postcard.KindBrand` | Not used | `Brand` (nil is the default brand) | The sample message in the default layout, with the draft's colours and logo in place of the saved Branding. | -`postcard.Editor.Validate` returns nil or a `postcard.DraftError`. `postcard.DraftError.Field` is the form field at fault: `subject`, `layout` or `body` for a template, `content_html`, `content_text` or `content_css` for a layout or a partial. `postcard.DraftError.Rule` is one of: +`postcard.Editor.Validate` returns nil or a `postcard.DraftError`. `postcard.DraftError.Field` is the form field at fault: `subject`, `layout` or `body` for a template, `content_html`, `content_text` or `content_css` for a layout or a partial, the colour's column for Branding. `postcard.DraftError.Rule` is one of: | Rule | Meaning | |------|---------| @@ -301,6 +338,7 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t | `layout` | The template's layout code names no layout. | | `partial` | A call names a partial that does not exist; `postcard.DraftError.Name` holds the name. | | `no_content` | A layout wrapper does not use `{{ .Content }}`. | +| `colour` | A Branding colour is not a six-digit hexadecimal colour; the field is its column, such as `button_primary_bg`. | `postcard.DraftError.Message` carries the template parser's, the renderer's or the safety check's own text and nothing else. The safety checks are the ones a send runs, so text such as `metadata:` is refused at save as it would be at send, and the message shows where. A template body is also refused when its source contains one of the unsafe tags, which Markdown would otherwise drop without notice. @@ -338,16 +376,19 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t | `postcard.SMTPConfig` | Host, port, credentials, TLS policy and timeout for the SMTP driver. | | `postcard.FailDriver` | Driver whose `postcard.FailDriver.Send` always returns `postcard.FailDriver.Err`. | | `postcard.OverrideSource` | Supplies the database overrides of one render. `postcard.OverrideSource.MailOverrides` takes the template name; an empty name asks for everything except a template override. | -| `postcard.Overrides` | What a source returns: the template override in `postcard.Overrides.Template` (nil when there is none), layout content by code in `postcard.Overrides.Layouts` and partial content by name in `postcard.Overrides.Partials`. | +| `postcard.Overrides` | What a source returns: the template override in `postcard.Overrides.Template` (nil when there is none), layout content by code in `postcard.Overrides.Layouts`, partial content by name in `postcard.Overrides.Partials` and the saved Branding in `postcard.Overrides.Brand` (nil while it has never been saved). | | `postcard.TemplateOverride` | A template's customized subject, body and layout code. An empty `postcard.TemplateOverride.Layout` keeps the file's layout. | | `postcard.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS from the database. In `postcard.Overrides.Layouts` under a file layout's full name it replaces that layout; under another code it is a database-only layout. | | `postcard.PartialOverride` | A partial's HTML and text sections from the database, in `postcard.Overrides.Partials` under the partial's full name. | -| `postcard.NewDBSource` | The source over postcard's tables. It looks the `*gorm.DB` up on the app at every call and returns no overrides when none is published. | +| `postcard.NewDBSource` | The source over postcard's tables. It looks the `*gorm.DB` up on the app at every call and returns no overrides when none is published. It builds the Branding logo's URL from the app's configuration. | +| `postcard.Brand` | The Branding: thirteen colours and `postcard.Brand.LogoURL`, the logo's absolute URL. | +| `postcard.DefaultBrand` | WinterCMS's default mail colours. | +| `postcard.CompileBrandCSS` | Checks a brand's colours and returns the brand CSS compiled from them. | | `postcard.Migrations` | The gormigrate set that creates the mail tables; lagoon runs it under the `summercms.postcard` history. | | `postcard.TemplatesTable`, `postcard.LayoutsTable`, `postcard.PartialsTable`, `postcard.BrandTable`, `postcard.ImageLibraryTable` | The names of the mail tables, for code that defines models over them. | | `postcard.SyncIndex` | Upserts one index row per file template, layout and partial of a catalog; mirrors the file into rows that are not customized and refreshes `file_hash` on all. | | `postcard.ResetOverride` | Returns one file-backed row to its file version. Takes the row's `postcard.Kind` and code. | -| `postcard.Kind` | What a draft or a row is: `postcard.KindTemplate`, `postcard.KindLayout`, `postcard.KindPartial` or `postcard.KindBrand` (reserved for the branding settings; the editor does not render it yet). | +| `postcard.Kind` | What a draft or a row is: `postcard.KindTemplate`, `postcard.KindLayout`, `postcard.KindPartial` or `postcard.KindBrand` (a Branding draft; it has no index row). | | `postcard.Editor` | Validates, previews and test-sends drafts with the mailer's catalog, configuration, override source and driver. | | `postcard.EditorFrom` | Returns the editor of the mailer published on an app. | | `postcard.Editor.Catalog` | The mailer's catalog. | @@ -364,14 +405,14 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t ## Configuration -`postcard.Activate` reads these keys from the app's [compass](../compass/README.md) config: +`postcard.Activate` reads these keys from the app's [compass](../compass/README.md) config. The Branding logo's URL also reads `storage.uploads.public_url`, `storage.uploads.public_path_prefix` and `app.url`, which belong to [lagoon](../lagoon/README.md)'s `attach` and to the application. | Key | Default | Controls | |-----|---------|----------| | `mail.driver` | `memory` | Delivery driver: `memory`, `log` or `smtp`. Any other value fails at boot. | | `mail.from` | empty | Sender address. Required by the SMTP driver. | -| `mail.css` | empty | CSS inlined into the layout. | -| `mail.brandCss` | empty | Brand CSS inlined before `mail.css`. | +| `mail.css` | empty | CSS placed in the layout's style block, after the brand CSS. Always applied. | +| `mail.brandCss` | empty | Brand CSS placed before `mail.css`. Used only until the branding settings are saved; from then on the CSS compiled from their colours replaces it (see [Branding](#branding)). | | `mail.smtp.host` | none | SMTP host. Required when `mail.driver` is `smtp`. | | `mail.smtp.port` | `587` | SMTP port. | | `mail.smtp.username` | empty | SMTP user. When set, PLAIN authentication is used. | @@ -393,7 +434,7 @@ mail: ## Dependencies -- SummerCMS modules: [backpack](../backpack/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component logger `postcard` when the app publishes no logger), [pact](../pact/README.md). +- SummerCMS modules: [backpack](../backpack/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component logger `postcard` when the app publishes no logger), [pact](../pact/README.md), and the `attach` package of [lagoon](../lagoon/README.md) (`attach.AbsolutePublicURL` and `attach.BlobKey` for the logo's URL; lagoon itself is not imported). - Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown, and its table extension inside partials), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations). - Standard library: `bytes`, `context`, `crypto/rand`, `crypto/sha256`, `database/sql`, `embed`, `encoding/hex`, `errors`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `sort`, `strconv`, `strings`, `sync`, `text/template` (and `text/template/parse`), `time`. - Tests additionally use `github.com/testcontainers/testcontainers-go` (Mailpit and Postgres containers), `gorm.io/driver/postgres` and `github.com/jackc/pgx/v5`. diff --git a/modules/postcard/assets/brand.css.tmpl b/modules/postcard/assets/brand.css.tmpl new file mode 100644 index 00000000..18c67a0b --- /dev/null +++ b/modules/postcard/assets/brand.css.tmpl @@ -0,0 +1,201 @@ +/* Base */ +body, body *:not(html):not(style):not(br):not(tr):not(code) { + font-family: Avenir, Helvetica, sans-serif; + box-sizing: border-box; +} +body { + background-color: {{ .BodyBg }}; + color: {{ .TextColor }}; + height: 100%; + line-height: 1.4; + margin: 0; + width: 100% !important; + word-break: break-word; + -webkit-text-size-adjust: none; +} +p, ul, ol, blockquote { + line-height: 1.4; + text-align: left; +} +a { + color: {{ .LinkColor }}; +} +a img { + border: none; +} +/* Typography */ +h1 { + color: {{ .HeadingColor }}; + font-size: 19px; + font-weight: bold; + margin-top: 0; + text-align: left; +} +h2 { + color: {{ .HeadingColor }}; + font-size: 16px; + font-weight: bold; + margin-top: 0; + text-align: left; +} +h3 { + color: {{ .HeadingColor }}; + font-size: 14px; + font-weight: bold; + margin-top: 0; + text-align: left; +} +p { + color: {{ .TextColor }}; + font-size: 16px; + line-height: 1.5em; + margin-top: 0; + text-align: left; +} +code { + color: {{ .TextColor }}; + font-size: 16px; + line-height: 1.5em; + word-break: break-all; +} +p.sub { + font-size: 12px; +} +img { + max-width: 100%; +} +.break-all, .break-all * { + word-break: break-all; +} +/* Layout */ +.wrapper { + background-color: {{ .BodyBg }}; + margin: 0; + padding: 0; + width: 100%; +} +.content { + margin: 0; + padding: 0; + width: 100%; +} +/* Header */ +.header { + padding: 25px 0; + text-align: center; +} +.header a, .header span { + color: {{ .HeaderColor }}; + font-size: 19px; + font-weight: bold; + text-decoration: none; +} +/* Body */ +.body { + background-color: {{ .ContentBg }}; + border-bottom: 1px solid {{ .TableBorderColor }}; + border-top: 1px solid {{ .TableBorderColor }}; + margin: 0; + padding: 0; + width: 100%; +} +.inner-body { + background-color: {{ .ContentBg }}; + margin: 0 auto; + padding: 0; + width: 570px; +} +.content-cell { + padding: 35px; +} +.wrapper.layout-system .content-cell { + padding: 35px 0; +} +/* Subcopy */ +.subcopy { + border-top: 1px solid {{ .TableBorderColor }}; + margin-top: 25px; + padding-top: 25px; +} +.subcopy p { + font-size: 12px; +} +/* Footer */ +.footer { + margin: 0 auto; + padding: 0; + text-align: center; + width: 570px; +} +.footer p { + color: {{ .FooterColor }}; + font-size: 12px; + text-align: center; +} +/* Tables */ +.table table { + border-collapse: collapse; + margin: 30px auto; + width: 100%; +} +.table th { + border-bottom: 1px solid {{ .TableBorderColor }}; + padding-bottom: 8px; +} +.table td { + color: {{ .TextColor }}; + font-size: 15px; + line-height: 18px; + padding: 10px 0; +} +/* Buttons */ +.action { + margin: 30px auto; + padding: 0; + text-align: center; + width: 100%; +} +.button { + border-radius: 3px; + box-shadow: 0 2px 3px rgba(0, 0, 0, 0.16); + color: {{ .ButtonTextColor }}; + display: inline-block; + text-decoration: none; + -webkit-text-size-adjust: none; +} +.button-primary { + background-color: {{ .ButtonPrimaryBg }}; + border-top: 10px solid {{ .ButtonPrimaryBg }}; + border-right: 18px solid {{ .ButtonPrimaryBg }}; + border-bottom: 10px solid {{ .ButtonPrimaryBg }}; + border-left: 18px solid {{ .ButtonPrimaryBg }}; +} +.button-positive { + background-color: {{ .ButtonPositiveBg }}; + border-top: 10px solid {{ .ButtonPositiveBg }}; + border-right: 18px solid {{ .ButtonPositiveBg }}; + border-bottom: 10px solid {{ .ButtonPositiveBg }}; + border-left: 18px solid {{ .ButtonPositiveBg }}; +} +.button-negative { + background-color: {{ .ButtonNegativeBg }}; + border-top: 10px solid {{ .ButtonNegativeBg }}; + border-right: 18px solid {{ .ButtonNegativeBg }}; + border-bottom: 10px solid {{ .ButtonNegativeBg }}; + border-left: 18px solid {{ .ButtonNegativeBg }}; +} +/* Panels */ +.panel { + margin: 0 0 21px; +} +.panel-content { + background-color: {{ .PanelBg }}; + padding: 16px; +} +.panel-item { + padding: 0; +} +.panel-item p:last-of-type { + margin-bottom: 0; + padding-bottom: 0; +} diff --git a/modules/postcard/brand.go b/modules/postcard/brand.go new file mode 100644 index 00000000..a4f08004 --- /dev/null +++ b/modules/postcard/brand.go @@ -0,0 +1,128 @@ +package postcard + +import ( + "bytes" + _ "embed" + "regexp" + "strings" + "sync" + texttemplate "text/template" +) + +// Brand is the mail branding: the colours the brand CSS is compiled from +// and the logo layouts show. A colour is a six-digit hexadecimal colour such +// as #2da7c7; an empty colour is that field's default. +type Brand struct { + BodyBg string + ContentBg string + HeaderColor string + FooterColor string + HeadingColor string + TextColor string + LinkColor string + ButtonTextColor string + ButtonPrimaryBg string + ButtonPositiveBg string + ButtonNegativeBg string + PanelBg string + TableBorderColor string + // LogoURL is the absolute URL of the logo, given to layouts as + // {{ .logoUrl }}. It is not part of the CSS. + LogoURL string +} + +// DefaultBrand returns WinterCMS's default mail colours. +func DefaultBrand() Brand { + return Brand{ + BodyBg: "#f5f8fa", + ContentBg: "#ffffff", + HeaderColor: "#bbbfc3", + FooterColor: "#aeaeae", + HeadingColor: "#2f3133", + TextColor: "#74787e", + LinkColor: "#2da7c7", + ButtonTextColor: "#ffffff", + ButtonPrimaryBg: "#d66829", + ButtonPositiveBg: "#52a838", + ButtonNegativeBg: "#e01346", + PanelBg: "#edeff2", + TableBorderColor: "#edeff2", + } +} + +// brandColours lists a brand's colours in the order they are checked, each +// under the name of its column in the branding table. +func brandColours(b *Brand) []brandColour { + return []brandColour{ + {"body_bg", &b.BodyBg}, + {"content_bg", &b.ContentBg}, + {"header_color", &b.HeaderColor}, + {"footer_color", &b.FooterColor}, + {"heading_color", &b.HeadingColor}, + {"text_color", &b.TextColor}, + {"link_color", &b.LinkColor}, + {"button_text_color", &b.ButtonTextColor}, + {"button_primary_bg", &b.ButtonPrimaryBg}, + {"button_positive_bg", &b.ButtonPositiveBg}, + {"button_negative_bg", &b.ButtonNegativeBg}, + {"panel_bg", &b.PanelBg}, + {"table_border_color", &b.TableBorderColor}, + } +} + +type brandColour struct { + column string + value *string +} + +// brandColourError is a brand colour that is not a six-digit hexadecimal +// colour. The value is left out: it may be anything. +type brandColourError struct { + column string +} + +func (e *brandColourError) Error() string { + return "postcard: brand colour " + e.column + " must be a six-digit hexadecimal colour such as #2da7c7" +} + +var hexColour = regexp.MustCompile(`^#[0-9a-f]{6}$`) + +//go:embed assets/brand.css.tmpl +var brandCSSSource string + +var ( + brandCSSOnce sync.Once + brandCSSTemplate *texttemplate.Template +) + +// CompileBrandCSS returns the brand CSS for b: styles for the page, links, +// headings, paragraphs and tables and for the classes of the built-in +// layouts and partials (button, panel, table, subcopy), so that the colours +// also show in a plugin's layout that carries no class of its own. Every +// colour must be a six-digit hexadecimal colour; upper-case digits are +// accepted and written lower-case, and an empty colour is that field's +// default. The error of an invalid colour names its column, such as +// button_primary_bg. +func CompileBrandCSS(b Brand) (string, error) { + def := DefaultBrand() + defaults := brandColours(&def) + for i, c := range brandColours(&b) { + colour := strings.ToLower(*c.value) + if colour == "" { + colour = *defaults[i].value + } + // Nothing but a checked colour reaches the style block. + if !hexColour.MatchString(colour) { + return "", &brandColourError{column: c.column} + } + *c.value = colour + } + brandCSSOnce.Do(func() { + brandCSSTemplate = texttemplate.Must(texttemplate.New("brand.css").Parse(brandCSSSource)) + }) + var buf bytes.Buffer + if err := brandCSSTemplate.Execute(&buf, b); err != nil { + return "", err + } + return buf.String(), nil +} diff --git a/modules/postcard/brand_smoke_test.go b/modules/postcard/brand_smoke_test.go new file mode 100644 index 00000000..b68e58b7 --- /dev/null +++ b/modules/postcard/brand_smoke_test.go @@ -0,0 +1,400 @@ +package postcard + +import ( + "context" + "errors" + "path/filepath" + "reflect" + "strings" + "testing" + + "git.golem15.com/golem15/summercms/modules/compass" + "git.golem15.com/golem15/summercms/modules/lagoon/attach" + "github.com/go-gormigrate/gormigrate/v2" +) + +// brandCfg writes config files and opens them: files maps a config file +// name such as mail.yaml to its content. +func brandCfg(t *testing.T, files map[string]string) *compass.Config { + t.Helper() + dir := t.TempDir() + for name, body := range files { + writeFile(t, filepath.Join(dir, name), body) + } + return loadMailCfg(t, dir, nil) +} + +// styleBlock returns the content of the first style element of html. +func styleBlock(t *testing.T, html string) string { + t.Helper() + _, rest, ok := strings.Cut(html, "") + css, _, _ := strings.Cut(rest, "") + return css +} + +// TestMailBrandSmoke covers Branding: the compiled brand CSS and its colour +// checks, the precedence over mail.brandCss once the settings row exists, +// the logo URL built at send time from configuration, and the editor's +// preview of unsaved colours. +func TestMailBrandSmoke(t *testing.T) { + ctx := context.Background() + + t.Run("absolute_url", func(t *testing.T) { + const key = "abc/def/123/abcdef123456.png" + cases := []struct { + name string + files map[string]string + want string + }{ + {"public_url", map[string]string{"storage.yaml": "uploads:\n public_url: https://cdn.example.com/u\n", "app.yaml": "url: https://acme.test\n"}, "https://cdn.example.com/u/" + key}, + {"public_url trailing slash", map[string]string{"storage.yaml": "uploads:\n public_url: https://cdn.example.com/u/\n"}, "https://cdn.example.com/u/" + key}, + {"app.url and the default prefix", map[string]string{"app.yaml": "url: https://acme.test\n"}, "https://acme.test/storage/uploads/" + key}, + {"app.url with a path and a prefix", map[string]string{"app.yaml": "url: https://acme.test/shop/\n", "storage.yaml": "uploads:\n public_path_prefix: /files/\n"}, "https://acme.test/shop/files/" + key}, + } + for _, tc := range cases { + got, err := attach.AbsolutePublicURL(brandCfg(t, tc.files), "/"+key) + if err != nil || got != tc.want { + t.Errorf("%s: %q, %v; want %q", tc.name, got, err, tc.want) + } + } + for name, files := range map[string]map[string]string{ + "neither": {"mail.yaml": "driver: memory\n"}, + "relative app.url": {"app.yaml": "url: /shop\n"}, + "app.url no scheme": {"app.yaml": "url: acme.test\n"}, + "app.url ftp": {"app.yaml": "url: ftp://acme.test\n"}, + } { + if got, err := attach.AbsolutePublicURL(brandCfg(t, files), key); !errors.Is(err, attach.ErrNoAbsoluteURL) || got != "" { + t.Errorf("%s: %q, %v; want ErrNoAbsoluteURL", name, got, err) + } + } + if _, err := attach.AbsolutePublicURL(nil, key); !errors.Is(err, attach.ErrNoAbsoluteURL) { + t.Errorf("nil config: %v", err) + } + if _, err := attach.AbsolutePublicURL(brandCfg(t, map[string]string{"storage.yaml": "uploads:\n public_url: cdn.example.com\n", "app.yaml": "url: https://acme.test\n"}), key); err == nil || errors.Is(err, attach.ErrNoAbsoluteURL) { + t.Errorf("a malformed public_url = %v, want its own error", err) + } + }) + + t.Run("defaults", func(t *testing.T) { + want := Brand{ + BodyBg: "#f5f8fa", ContentBg: "#ffffff", HeaderColor: "#bbbfc3", FooterColor: "#aeaeae", + HeadingColor: "#2f3133", TextColor: "#74787e", LinkColor: "#2da7c7", ButtonTextColor: "#ffffff", + ButtonPrimaryBg: "#d66829", ButtonPositiveBg: "#52a838", ButtonNegativeBg: "#e01346", + PanelBg: "#edeff2", TableBorderColor: "#edeff2", + } + if got := DefaultBrand(); got != want { + t.Errorf("DefaultBrand() = %+v, want %+v", got, want) + } + }) + + t.Run("compile", func(t *testing.T) { + // Thirteen distinct colours, so each one can be found in the output. + b := Brand{ + BodyBg: "#010101", ContentBg: "#020202", HeaderColor: "#030303", FooterColor: "#040404", + HeadingColor: "#050505", TextColor: "#060606", LinkColor: "#070707", ButtonTextColor: "#080808", + ButtonPrimaryBg: "#090909", ButtonPositiveBg: "#0a0a0a", ButtonNegativeBg: "#0b0b0b", + PanelBg: "#0c0c0c", TableBorderColor: "#0d0d0d", + } + css, err := CompileBrandCSS(b) + if err != nil { + t.Fatalf("CompileBrandCSS: %v", err) + } + v := reflect.ValueOf(b) + for i := range v.NumField() { + if colour := v.Field(i).String(); colour != "" && !strings.Contains(css, colour) { + t.Errorf("compiled CSS lacks %s (%s)", v.Type().Field(i).Name, colour) + } + } + for _, want := range []string{ + "body {", "background-color: #010101", "a {\n\tcolor: #070707", "h1 {\n\tcolor: #050505", + ".button-primary {\n\tbackground-color: #090909", ".button-positive {\n\tbackground-color: #0a0a0a", + ".button-negative {\n\tbackground-color: #0b0b0b", ".panel-content {\n\tbackground-color: #0c0c0c", + ".table th {\n\tborder-bottom: 1px solid #0d0d0d", ".subcopy {", ".footer p {\n\tcolor: #040404", + ".header a, .header span {\n\tcolor: #030303", ".body {\n\tbackground-color: #020202", + } { + if !strings.Contains(css, want) { + t.Errorf("compiled CSS lacks %q", want) + } + } + if err := validateHTML(""); err != nil { + t.Errorf("the compiled CSS fails the mail safety checks: %v", err) + } + if strings.Contains(css, "<") || strings.Contains(css, "{{") { + t.Errorf("compiled CSS holds markup or an unexecuted action:\n%s", css) + } + + def, err := CompileBrandCSS(DefaultBrand()) + if err != nil { + t.Fatal(err) + } + for _, colour := range []string{"#f5f8fa", "#ffffff", "#bbbfc3", "#aeaeae", "#2f3133", "#74787e", "#2da7c7", "#d66829", "#52a838", "#e01346", "#edeff2"} { + if !strings.Contains(def, colour) { + t.Errorf("default CSS lacks %s", colour) + } + } + // An empty colour is that field's default; the zero Brand is the default brand. + if zero, err := CompileBrandCSS(Brand{}); err != nil || zero != def { + t.Errorf("CompileBrandCSS(Brand{}) differs from the default brand: %v", err) + } + // Upper-case hex is accepted and emitted lower-case. + upper, err := CompileBrandCSS(Brand{ButtonPrimaryBg: "#AB12CD"}) + if err != nil || !strings.Contains(upper, "#ab12cd") || strings.Contains(upper, "#AB12CD") { + t.Errorf("upper-case hex: %v", err) + } + // The logo URL is not a colour and does not reach the CSS. + if with, err := CompileBrandCSS(Brand{LogoURL: "https://cdn.example.com/logo.png"}); err != nil || with != def { + t.Errorf("LogoURL changed the CSS: %v", err) + } + + bad := map[string]string{ + "short hex": "#ABC", + "name": "red", + "style end": "#fff