activemail 1.2.3 → 2.1.0

data/UPGRADING.md

@@ -0,0 +1,185 @@
+# Upgrading to ActiveMail 2.1
+
+## Gemfile
+
+```ruby
+gem 'activemail', '~> 2.1'
+```
+
+## Outer gutter
+
+Rows now keep content off the screen edge: the first and last column of a row
+get a 16px (`container_gutter`) border-box padding on their outer side, inlined
+like every other framework rule. Columns still sum to `container_width`; the
+text area is 16px narrower on each side.
+
+- To keep edge-to-edge columns: `config.tokens.spacing :container_gutter, '0px'`
+  (or `$am-container-gutter: 0`).
+- Content you padded by hand to avoid the edge now has the padding twice:
+  remove it.
+- A nested row does not repeat the outer gutter. The `.columns.first.last` SCSS
+  rule is gone; ejected `_grid.scss` copies (`activemail:styles`) must be
+  re-ejected.
+
+## Outlook markup
+
+- Conditional comments are `<!--[if mso]>` (`mso` alone targets Outlook
+  for Windows). Tests matching `[if mso | IE]` must change.
+- Each column ghost cell wraps its column in a `<table><tr>`. A nested column
+  is sized against the content box of its enclosing column: `large="6"` in a
+  lone `large="6"` is 134px (300px minus two 16px gutters, halved), not 300px.
+
+## Buttons
+
+- The fill and the radius are on the cell, not on the `<a>`. The `<a>` carries
+  `display:inline-block`, `font-family` (the `body` font token) and
+  `line-height:1.25`; the cell gets `mso-padding-alt`.
+- A dark-mode override of the button fill must target `table td`, not `a`.
+
+## Center
+
+`<center>` no longer adds `align="center"` and `.float-center` to its children
+(nor to nested menu items): it renders one `<center align="center">` and leaves
+its content as written. Put `class="float-center"` or `align="center"` on the
+children that need it.
+
+## Layouts
+
+The `<head>` of the default layout moved to `layouts/activemail/_document_head`,
+with `<title><%= message.subject %></title>`. The generated layouts
+(`activemail:install`, `--haml`, `--slim`) render that partial and the `_head`
+and `_footer` partials: regenerate yours or add the `<title>`. The partial reads
+`message`, so it only renders inside a mailer view.
+
+## Quality
+
+New built-in rules flag emails that passed before: `title`, `anchor_href`,
+`placeholder`, `unsupported_color`, `text_entities`. Disable any with
+`Guard.new(disable: [...])`.
+
+A `NullMail` (a mailer that returned without sending) is now a `declined`
+violation, in `Guard`, `render_all`, `assert_email_quality`,
+`assert_quality_for_all_previews` and `be_a_valid_email`. List the previews that
+decline on purpose:
+
+```ruby
+ActiveMail::Quality.configure { |c| c.allow_declined = %w[reminder_mailer#maybe_skipped] }
+```
+
+or pass `allow_declined: true` to `Guard#violations`, `Guard#valid?`,
+`assert_email_quality` and `be_a_valid_email`.
+
+---
+
+# Upgrading to ActiveMail 2.0
+
+## Gemfile
+
+```ruby
+gem 'activemail', '~> 2.0'
+```
+
+## Inlining
+
+The delivery interceptor is gone: each email is transpiled and inlined once,
+when the mailer renders an inky HTML template.
+
+- Remove `config.register_inline_interceptor` from your initializer.
+- If you ran another inliner (premailer-rails) next to ActiveMail with
+  `config.inliner = :null`, drop that inliner and the `:null` setting: ActiveMail
+  now inlines the whole body, layout included.
+- Inliner failures still raise `ActiveMail::Inliner::Error` (now a subclass of
+  `ActiveMail::Error`).
+
+## Layouts
+
+Ejected or hand-written layouts must embed the stylesheets with the helper and
+drop `stylesheet_link_tag` (Premailer strips it, so it never styled anything):
+
+```erb
+<%# before %>
+<%= stylesheet_link_tag "emails/emails" %>
+<%= activemail_inline_styles %>
+
+<%# after %>
+<%= activemail_inline_styles "emails/emails" %>
+```
+
+A missing or empty asset now raises `ActiveMail::StylesheetNotFound` instead of
+logging a warning; inside a view it surfaces as the `#cause` of
+`ActionView::Template::Error`.
+
+## SCSS
+
+The framework uses the Sass module system. Replace `@import` and variables
+declared before it with `@use … with (…)`; a variable declared before the
+`@use` is no longer read.
+
+```scss
+// before
+$am-button-secondary-color: #264653;
+@import "activemail/activemail";
+
+// after
+@use "activemail/activemail" with (
+  $am-button-secondary-color: #264653
+);
+```
+
+- Renamed: `$am-button-color` → `$am-button-primary-color`,
+  `$am-info-box-bg` → `$am-info-box-background`.
+- Prefer Ruby tokens (`secondary_text`, `secondary_border`, `info_box_*`, …):
+  they now reach both the inline styles and the stylesheet, so SCSS overrides of
+  the button/info-box variables are rarely needed.
+- `$am-breakpoint` defaults to the container width (600px) instead of 596px.
+
+## Buttons
+
+`<button>` and `<cta>` share one rendering, styled inline from the tokens.
+
+- CSS targeting the old markup (`<center>`, `.expander` cell inside
+  `.button.expand`) no longer matches; style buttons through tokens.
+- A dark-mode override must use `!important` to beat the inline styles.
+- A `<button>` without `href` renders its label in a `<span>`.
+
+## Components
+
+- The `<inky>` tag is removed.
+- `inner` is an opaque slot: interpolate it exactly once and never parse or
+  alter it.
+- `IGNORED_ON_PASSTHROUGH`, `combine_attributes`, `pass_through_attributes`,
+  `bulletproof_button_table` and `BUTTON_PADDING` are removed. Use
+  `root_attributes(node, classes:, layout_style:)` and override the private
+  `consumed_attributes` to list the attributes your component reads; a
+  component whose root is a `TABLE_RESET` table inherits from
+  `ActiveMail::Components::TableComponent`.
+- A component must output `inner` exactly once (or have no children):
+  otherwise `ActiveMail::Error` is raised instead of silently dropping content.
+  Self-closing `<h-line/>`/`<spacer/>` are not valid HTML4 and swallow their
+  following siblings; write `<h-line></h-line>`.
+- `id`, `aria-*`, `data-*` and other attributes now pass through on every
+  built-in component. On tables carrying `TABLE_RESET`, the component's
+  `role="presentation"` wins over the author's `role`.
+- `ActiveMail::Core.new` only takes keywords (`config:`, `components:`,
+  `column_count:`, `container_width:`). For plain transpilation prefer the
+  memoized `ActiveMail.configuration.core`.
+- Integer settings (`column_count`, `container_width`) raise `TypeError` for a
+  non-Integer and `ArgumentError` for a non-positive value. Numeric attributes
+  are parsed in strict base 10.
+
+## Quality
+
+- `output_dir` must be relative, inside `Rails.root` (symlinks resolved), and
+  neither `.` nor contain `..`. `render_all` marks it with an
+  `.activemail_previews` file and refuses to clean an existing, non-empty
+  directory without that marker: empty your previous output directory once.
+- `PreviewRenderer.render` is removed.
+- `RenderAll.new(root:, config:)` replaces `output_root:`.
+- Rendered files and failures carry the locale when it differs from the
+  default (`welcome.fr.html`, `preview#email [fr]`).
+- `Guard#violations` and `assert_email_quality` accept a `Mail::Message` (HTML
+  plus message rules) or an HTML string. New built-in rules may flag existing
+  emails: `translation_missing`, `translation_missing_text`, `single_root`,
+  `html_part_present`, `text_part_present`, `text_part_plain`. Disable any with
+  `Guard.new(disable: [...])`.
+- Host-specific checks move to `Guard.new(rules: [Quality::Rule.html(...)])`.

data/app/assets/stylesheets/activemail/_components.scss

@@ -1,62 +1,53 @@
-// Background on both cell and link so the whole bulletproof button is filled and
-// clickable. Radius by default — progressive enhancement, clients that don't support it ignore it.
-.button table td,
-.button a {
-  background: $am-button-primary-bg;
-  border-radius: $am-button-radius;
-}
+@use "sass:math";
+@use "settings" as *;
 
-.button a {
-  color: $am-button-color;
-  font-family: $am-font-family;
-  font-weight: bold;
+.expander {
+  padding: 0 !important;
+  visibility: hidden;
+  width: 0;
 }
 
-.button.secondary table td,
-.button.secondary a {
-  background: $am-button-secondary-bg;
-  color: $am-button-secondary-color;
+.info-box td {
+  background-color: $am-info-box-background;
+  border-left: 5px solid $am-info-box-border;
+  border-radius: $am-box-radius;
+  color: $am-info-box-text;
+  padding: $am-spacing-md;
 }
 
-// Border on the cell only — a repeated <a> border would double the line.
-.button.secondary table td {
-  border: 1px solid $am-button-secondary-border;
+.callout-inner {
+  background-color: $am-background;
+  color: $am-text;
+  padding: $am-spacing-md;
 }
 
-.cta table td,
-.cta a {
-  background: $am-button-primary-bg;
-  border-radius: $am-button-radius;
+.h-line,
+.h-line th {
+  font-size: 1px;
+  line-height: 1px;
 }
 
-.cta a {
-  color: $am-button-color;
-  font-family: $am-font-family;
-  font-weight: bold;
+.h-line {
+  border-top: 1px solid $am-border;
 }
 
-.cta.secondary table td,
-.cta.secondary a {
-  background: $am-button-secondary-bg;
-  color: $am-button-secondary-color;
+.menu {
+  width: auto !important;
 }
 
-.cta.secondary table td {
-  border: 1px solid $am-button-secondary-border;
+.menu-item {
+  padding: $am-spacing-sm $am-spacing-md;
 }
 
-.info-box td {
-  background-color: $am-info-box-bg;
-  border-left: 5px solid $am-info-box-border;
-  border-radius: $am-box-radius;
-  color: $am-info-box-text;
-  padding: $am-spacing-md;
+.menu-item a {
+  text-decoration: none;
 }
 
-.callout-inner {
-  background-color: $am-background;
-  color: $am-text;
-  padding: $am-spacing-md;
+@for $n from 1 through $am-column-count {
+  .block-grid.up-#{$n} > tbody > tr > th,
+  .block-grid.up-#{$n} > tbody > tr > td {
+    width: math.div(100%, $n);
+  }
 }
 
 // Height is set inline per instance; this rule is just a styling anchor.

data/app/assets/stylesheets/activemail/_dark.scss

@@ -1,12 +1,7 @@
 // Dark mode: prefers-color-scheme (Apple Mail/iOS) + [data-ogsc] (Outlook
 // Android). Colors derived from tokens — pure black/white crush contrast.
 
-$am-dark-bg: mix($am-color-text, $am-color-background, 96%) !default;
-$am-dark-surface: mix($am-color-text, $am-color-background, 92%) !default;
-$am-dark-panel: mix($am-color-text, $am-color-background, 82%) !default;
-$am-dark-text: mix($am-color-background, $am-color-text, 88%) !default;
-$am-dark-muted: $am-color-muted !default;
-$am-dark-link: $am-color-primary !default;
+@use "settings" as *;
 
 @mixin am-dark-rules {
   .body,
@@ -37,27 +32,40 @@ $am-dark-link: $am-color-primary !default;
     color: $am-dark-link !important;
   }
 
+  // The fill lives on the cell alone: a filled link would square off its rounded corners.
   .button table td,
+  .cta table td {
+    background: $am-button-primary-bg !important;
+  }
+
   .button a,
-  .cta table td,
-  .cta a {
-    background: $am-color-primary !important;
-    color: $am-color-button-text !important;
+  .button span,
+  .cta a,
+  .cta span {
+    color: $am-button-primary-color !important;
   }
 
-  // Restore the secondary fill AND text — the primary rule above forces button-text,
-  // which would be unreadable on an outline (light) secondary fill.
+  // Restore the secondary fill AND text — the primary rule above would be unreadable
+  // on a light secondary fill.
   .button.secondary table td,
+  .cta.secondary table td {
+    background: $am-button-secondary-bg !important;
+  }
+
   .button.secondary a,
-  .cta.secondary table td,
-  .cta.secondary a {
-    background: $am-color-secondary !important;
+  .button.secondary span,
+  .cta.secondary a,
+  .cta.secondary span {
     color: $am-button-secondary-color !important;
   }
 
   // Panels keep their inline background unless overridden here, which would
   // otherwise leave dark text on a dark background.
-  .callout-inner,
+  .callout-inner {
+    background-color: $am-dark-panel !important;
+    color: $am-dark-text !important;
+  }
+
   .info-box,
   .info-box td {
     background-color: $am-dark-panel !important;
@@ -101,22 +109,34 @@ $am-dark-link: $am-color-primary !default;
   }
 
   [data-ogsc] .button table td,
+  [data-ogsc] .cta table td {
+    background: $am-button-primary-bg !important;
+  }
+
   [data-ogsc] .button a,
-  [data-ogsc] .cta table td,
-  [data-ogsc] .cta a {
-    background: $am-color-primary !important;
-    color: $am-color-button-text !important;
+  [data-ogsc] .button span,
+  [data-ogsc] .cta a,
+  [data-ogsc] .cta span {
+    color: $am-button-primary-color !important;
   }
 
   [data-ogsc] .button.secondary table td,
+  [data-ogsc] .cta.secondary table td {
+    background: $am-button-secondary-bg !important;
+  }
+
   [data-ogsc] .button.secondary a,
-  [data-ogsc] .cta.secondary table td,
-  [data-ogsc] .cta.secondary a {
-    background: $am-color-secondary !important;
+  [data-ogsc] .button.secondary span,
+  [data-ogsc] .cta.secondary a,
+  [data-ogsc] .cta.secondary span {
     color: $am-button-secondary-color !important;
   }
 
-  [data-ogsc] .callout-inner,
+  [data-ogsc] .callout-inner {
+    background-color: $am-dark-panel !important;
+    color: $am-dark-text !important;
+  }
+
   [data-ogsc] .info-box,
   [data-ogsc] .info-box td {
     background-color: $am-dark-panel !important;

data/app/assets/stylesheets/activemail/_grid.scss

@@ -1,5 +1,6 @@
-// Gutters are unconditional padding (inlined by the CSS inliner): the gem emits
-// none, and they must not depend on media queries (stripped by Gmail mobile).
+@use "settings" as *;
+
+// Gutters are plain padding, inlined: Gmail mobile strips media queries.
 
 .container {
   width: 100%;
@@ -15,11 +16,8 @@
   width: 100%;
 }
 
-// Gutters: half on each side, outer edges collapsed via first/last so content
-// stays flush with the container.
-// box-sizing keeps the gutter inside the inline max-width — without it a 300px
-// 2-col cell + 8px padding becomes 316px and the row overflows ~616px, wrapping
-// in clients that honor inline padding.
+// border-box keeps each gutter inside the inline max-width, else the row overflows and wraps;
+// the container takes no padding for the same reason.
 .columns {
   box-sizing: border-box;
   padding-left: $am-gutter;
@@ -27,23 +25,51 @@
 }
 
 .columns.first {
-  padding-left: 0;
+  padding-left: $am-container-gutter;
 }
 
 .columns.last {
-  padding-right: 0;
+  padding-right: $am-container-gutter;
 }
 
-// A single full-width column carries no side gutter.
-.columns.first.last {
+// A nested row already sits inside its parent column's padding.
+.columns .columns.first {
   padding-left: 0;
+}
+
+.columns .columns.last {
   padding-right: 0;
 }
 
-// Collapse removes gutters on demand (e.g. edge-to-edge images). Columns are not
-// direct children of .row — the real markup nests them as <th class="columns">
-// under tbody > tr — so this must be a descendant selector, not a child one.
+// Descendant selector: columns render as <th> under tbody > tr, not as children of .row.
 .row.collapse .columns {
   padding-left: 0;
   padding-right: 0;
 }
+
+// Below the container width every full row stacks, so each top-level column edge is an outer one.
+// Nested columns may still sit side by side and keep the regular gutters. Gmail strips this query.
+@media only screen and (max-width: $am-breakpoint - 1px) {
+  .columns {
+    padding-left: $am-container-gutter !important;
+    padding-right: $am-container-gutter !important;
+  }
+
+  .columns .columns {
+    padding-left: $am-gutter !important;
+    padding-right: $am-gutter !important;
+  }
+
+  .columns .columns.first {
+    padding-left: 0 !important;
+  }
+
+  .columns .columns.last {
+    padding-right: 0 !important;
+  }
+
+  .row.collapse .columns {
+    padding-left: 0 !important;
+    padding-right: 0 !important;
+  }
+}

data/app/assets/stylesheets/activemail/_settings.scss

@@ -1,5 +1,8 @@
-// All !default so a host app can pre-declare any value before importing the framework.
-@import "activemail/activemail_tokens";
+// Sass only lets `with (...)` configure !default variables of forwarded modules:
+// every configurable variable must live here or in the forwarded token bridge.
+@forward "activemail_tokens";
+@use "sass:color";
+@use "activemail_tokens" as *;
 
 // Typography
 $am-font-family: $am-font-body !default;
@@ -11,19 +14,19 @@ $am-background: $am-color-background !default;
 $am-muted: $am-color-muted !default;
 $am-border: $am-color-border !default;
 
-// Buttons
+// Buttons — a null border means no border at all.
 $am-button-primary-bg: $am-color-primary !default;
+$am-button-primary-color: $am-color-primary-text !default;
+$am-button-primary-border: $am-color-primary-border !default;
 $am-button-secondary-bg: $am-color-secondary !default;
-$am-button-color: $am-color-button-text !default;
-// Secondary falls back to filled-button defaults; override *-secondary-* for an outline variant.
-$am-button-secondary-color: $am-color-button-text !default;
-$am-button-secondary-border: transparent !default;
+$am-button-secondary-color: $am-color-secondary-text !default;
+$am-button-secondary-border: $am-color-secondary-border !default;
 $am-button-radius: $am-radius-button !default;
 
 // Info box
-$am-info-box-bg: $am-background !default;
-$am-info-box-border: $am-border !default;
-$am-info-box-text: $am-text !default;
+$am-info-box-background: $am-color-info-box-background !default;
+$am-info-box-border: $am-color-info-box-border !default;
+$am-info-box-text: $am-color-info-box-text !default;
 $am-box-radius: $am-radius-box !default;
 
 // Grid — the gem emits no gutters; we provide them via column padding. Width
@@ -31,3 +34,13 @@ $am-box-radius: $am-radius-box !default;
 // aligned with the transpiled markup (ghost tables, column max-width).
 $am-container-width: $am-grid-container-width !default;
 $am-gutter: $am-spacing-sm !default;
+$am-container-gutter: $am-spacing-container-gutter !default;
+$am-breakpoint: $am-container-width !default;
+
+// Dark mode
+$am-dark-bg: color.mix($am-color-text, $am-color-background, 96%) !default;
+$am-dark-surface: color.mix($am-color-text, $am-color-background, 92%) !default;
+$am-dark-panel: color.mix($am-color-text, $am-color-background, 82%) !default;
+$am-dark-text: color.mix($am-color-background, $am-color-text, 88%) !default;
+$am-dark-muted: $am-color-muted !default;
+$am-dark-link: $am-button-primary-bg !default;

data/app/assets/stylesheets/activemail/_utilities.scss

@@ -1,3 +1,5 @@
+@use "settings" as *;
+
 // Alignment and visibility utilities.
 
 .text-center {
@@ -32,7 +34,7 @@
   overflow: hidden;
 }
 
-@media only screen and (min-width: 596px) {
+@media only screen and (min-width: $am-breakpoint) {
   .show-for-large {
     display: block !important;
     font-size: inherit;

data/app/assets/stylesheets/activemail/activemail.scss

@@ -1,11 +1,12 @@
 // ActiveMail email framework entry point. Critical styles are inlined by the
 // configured CSS inliner (Gmail mobile strips <style>); only media-query and
 // dark-mode enhancements stay in the <head>.
-@import "activemail/settings";
-@import "activemail/grid";
-@import "activemail/components";
-@import "activemail/utilities";
-@import "activemail/dark";
+@forward "settings";
+@use "settings" as *;
+@use "grid";
+@use "components";
+@use "utilities";
+@use "dark";
 
 body,
 table,

data/app/helpers/active_mail/styles_helper.rb

@@ -1,29 +1,28 @@
 # typed: false
 # frozen_string_literal: true
 
+require 'activemail/asset_pipeline'
+
 module ActiveMail
-  # Embeds the compiled framework CSS as a <style> block so the Premailer adapter
-  # (string-only) inlines it — it can't fetch the stylesheet_link_tag's asset URL.
+  # Embeds the compiled CSS as a <style> block: the inliners take an HTML string
+  # and cannot fetch the digest URL a stylesheet_link_tag would emit.
   module StylesHelper
-    FRAMEWORK_STYLESHEET = 'activemail/activemail.css'
-
-    # '' (not raise) when the asset can't be read — degrades to the link fallback,
-    # but warns, since the email then ships unstyled.
-    def activemail_inline_styles
-      css = activemail_compiled_css
-      if css.blank?
-        ActiveMail.log_warning('[activemail] framework stylesheet could not be read from the asset pipeline; ' \
-                               'email ships without inlined framework CSS')
-        return ''.html_safe
-      end
+    FRAMEWORK_STYLESHEET = 'activemail/activemail'
 
+    def activemail_inline_styles(*logical_paths)
+      paths = logical_paths.empty? ? [FRAMEWORK_STYLESHEET] : logical_paths
+      css = paths.map { |path| activemail_compiled_css(path.to_s) }.join("\n")
       content_tag(:style, css.html_safe, type: 'text/css')
     end
 
     private
 
-    def activemail_compiled_css
-      ActiveMail::CompiledStylesheet.read(FRAMEWORK_STYLESHEET)
+    def activemail_compiled_css(logical_path)
+      asset = logical_path.end_with?('.css') ? logical_path : "#{logical_path}.css"
+      css = ActiveMail::AssetPipeline.current.read(asset)
+      return css if css.present?
+
+      raise ActiveMail::StylesheetNotFound, "stylesheet #{asset.inspect} is missing or empty in the asset pipeline"
     end
   end
 end

data/app/views/layouts/activemail/_document_head.html.erb

@@ -0,0 +1,18 @@
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="x-apple-disable-message-reformatting">
+  <meta name="color-scheme" content="light dark">
+  <meta name="supported-color-schemes" content="light dark">
+  <title><%= message.subject %></title>
+  <!--[if mso]>
+  <noscript>
+    <xml>
+      <o:OfficeDocumentSettings>
+        <o:PixelsPerInch>96</o:PixelsPerInch>
+      </o:OfficeDocumentSettings>
+    </xml>
+  </noscript>
+  <![endif]-->
+  <%= activemail_inline_styles %>
+</head>

data/app/views/layouts/activemail/mailer.html.inky-erb

@@ -1,27 +1,6 @@
 <!DOCTYPE html>
 <html lang="<%= I18n.locale %>" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="x-apple-disable-message-reformatting">
-    <meta name="color-scheme" content="light dark">
-    <meta name="supported-color-schemes" content="light dark">
-    <!--[if mso]>
-    <noscript>
-      <xml>
-        <o:OfficeDocumentSettings>
-          <o:PixelsPerInch>96</o:PixelsPerInch>
-        </o:OfficeDocumentSettings>
-      </xml>
-    </noscript>
-    <![endif]-->
-    <%# Embedded so the Premailer adapter (HTML-string only) can inline the framework CSS. %>
-    <%= activemail_inline_styles %>
-    <%# Fallback for when activemail_inline_styles cannot read the compiled asset %>
-    <%# (CDN-only host, compile=false without precompile); redundant otherwise, as the %>
-    <%# embed's rules are idempotent once inlined. %>
-    <%= stylesheet_link_tag "activemail/activemail", media: "all" %>
-  </head>
+  <%= render "layouts/activemail/document_head" %>
 
   <body style="margin:0;padding:0;word-spacing:normal;">
     <div role="article" aria-roledescription="email" lang="<%= I18n.locale %>" style="width:100%;">