Mailglass.Components (Mailglass v0.1.0)

Copy Markdown View Source

HEEx function components for transactional email composition.

Components

Theme

All brand-token attributes (:tone, :variant, :bg) resolve via Mailglass.Components.Theme.color/1 and .font/1 at render time. The theme is cached in :persistent_term by Mailglass.Config.validate_at_boot!/0 (D-19); reads are O(1).

MSO / Outlook VML

Per D-11, VML is used surgically:

  • button/1 — <v:roundrect> bulletproof button with mso-hide:all HTML fallback
  • row/1 / column/1 — ghost-table <!--[if mso]> conditionals
  • all other components — pure HTML + inline CSS

Plaintext extraction

Each content component emits data-mg-plaintext="<strategy>" on its root node. Mailglass.Renderer.to_plaintext/1 (Plan 06) walks the tree keyed off these markers. A terminal Floki pass strips all data-mg-* attributes from the final HTML wire (D-22).

Summary

Functions

button(assigns)

Renders a bulletproof button with a <v:roundrect> VML wrapper for classic Outlook and an <a> HTML fallback carrying mso-hide:all so Outlook hides it in favour of the VML version (D-10).

column(assigns)

Renders a column inside a row/1. Emits a <!--[if mso]><td> ghost-td conditional wrapper so classic Outlook respects the column layout.

container(assigns)

Renders a 600px-wide centered email container table (D-11).

heading(assigns)

Renders an <h1>..<h4> heading with brand-tone color and email-safe mso-line-height-rule:exactly.

hr(assigns)

Renders an email-safe horizontal rule: a zero-height <table> with a 1px border-top on the inner <td> (D-11).

img(assigns)

Renders an <img> tag. The :alt attribute is required at compile time (D-18) — authors must pass alt="" for decorative images.

link(assigns)

Renders an inline text link. Sets the tone color both on the <a> and the wrapping <span> so email clients that strip one still render the other (D-11).

preheader(assigns)

Renders an email preheader — the hidden snippet that email clients show in inbox previews.

row(assigns)

Renders a row that holds column/1 children.

section(assigns)

Renders a full-width email section with padded inner cell.

text(assigns)

Renders a paragraph with brand-tone color and size variant.

Functions

button(assigns)

(since 0.1.0)

Renders a bulletproof button with a <v:roundrect> VML wrapper for classic Outlook and an <a> HTML fallback carrying mso-hide:all so Outlook hides it in favour of the VML version (D-10).

Content components exclude :style from :global per D-17.

Attributes

  • variant (:string) - Defaults to "primary". Must be one of "primary", "secondary", or "ghost".
  • tone (:string) - Defaults to "glass". Must be one of "glass", "ink", or "slate".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden", "href", "target"].

Slots

  • inner_block (required)

column(assigns)

(since 0.1.0)

Renders a column inside a row/1. Emits a <!--[if mso]><td> ghost-td conditional wrapper so classic Outlook respects the column layout.

Attributes

  • width (:any) - Defaults to :auto.
  • valign (:string) - Defaults to "top". Must be one of "top", "middle", or "bottom".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden"].

Slots

  • inner_block (required)

container(assigns)

(since 0.1.0)

Renders a 600px-wide centered email container table (D-11).

Attributes

  • bg (:string) - Defaults to "paper". Must be one of "paper", "mist", "ink", or "custom".
  • bg_hex (:string) - Defaults to nil.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden"].

Slots

  • inner_block (required)

heading(assigns)

(since 0.1.0)

Renders an <h1>..<h4> heading with brand-tone color and email-safe mso-line-height-rule:exactly.

Attributes

  • level (:integer) - Defaults to 1. Must be one of 1, 2, 3, or 4.
  • align (:string) - Defaults to "left". Must be one of "left", "center", or "right".
  • tone (:string) - Defaults to "ink". Must be one of "ink", "glass", or "slate".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden"].

Slots

  • inner_block (required)

hr(assigns)

(since 0.1.0)

Renders an email-safe horizontal rule: a zero-height <table> with a 1px border-top on the inner <td> (D-11).

Attributes

  • tone (:string) - Defaults to "mist". Must be one of "mist", or "slate".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden"].

img(assigns)

(since 0.1.0)

Renders an <img> tag. The :alt attribute is required at compile time (D-18) — authors must pass alt="" for decorative images.

Attributes

  • src (:string) (required)
  • alt (:string) (required)
  • width (:integer) - Defaults to nil.
  • height (:integer) - Defaults to nil.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid"].

link(assigns)

(since 0.1.0)

Renders an inline text link. Sets the tone color both on the <a> and the wrapping <span> so email clients that strip one still render the other (D-11).

Attributes

  • tone (:string) - Defaults to "glass". Must be one of "glass", or "ink".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden", "href", "target"].

Slots

  • inner_block (required)

preheader(assigns)

(since 0.1.0)

Renders an email preheader — the hidden snippet that email clients show in inbox previews.

Styled to be invisible (display:none, mso-hide:all) and padded with zero-width chars to push additional content out of Gmail's preview pull (D-15). Carries data-mg-plaintext="skip" so the plaintext walker excludes it from the text body.

Attributes

  • text (:string) (required)
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id"].

row(assigns)

(since 0.1.0)

Renders a row that holds column/1 children.

Emits a <!--[if mso]><table role="presentation"> ghost table so classic Outlook aligns columns side-by-side instead of stacking them (D-11).

Attributes

  • gap (:integer) - Defaults to 0.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden"].

Slots

  • inner_block (required)

section(assigns)

(since 0.1.0)

Renders a full-width email section with padded inner cell.

Attributes

  • bg (:string) - Defaults to "paper". Must be one of "paper", "mist", "ink", or "custom".
  • bg_hex (:string) - Defaults to nil.
  • padding (:string) - Defaults to "20px".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden"].

Slots

  • inner_block (required)

text(assigns)

(since 0.1.0)

Renders a paragraph with brand-tone color and size variant.

Attributes

  • size (:string) - Defaults to "base". Must be one of "sm", "base", or "lg".
  • tone (:string) - Defaults to "ink". Must be one of "ink", or "slate".
  • align (:string) - Defaults to "left". Must be one of "left", "center", or "right".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Supports all globals plus: ["id", "data-testid", "aria-label", "aria-hidden"].

Slots

  • inner_block (required)