# `Mailglass.Components`
[🔗](https://github.com/szTheory/mailglass/blob/v0.1.0/lib/mailglass/components.ex#L1)

HEEx function components for transactional email composition.

## Components

  * Layout: `container/1`, `section/1`, `row/1`, `column/1`
  * Content: `heading/1`, `text/1`, `button/1`, `link/1`
  * Atomic:  `img/1`, `hr/1`, `preheader/1`

## 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).

# `button`
*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`
*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`
*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`
*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`
*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`
*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`
*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`
*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`
*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`
*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`
*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)

---

*Consult [api-reference.md](api-reference.md) for complete listing*