` elements for line breaks | | `` | Images are not permitted inside `text`; use a dedicated image component | | Any `

`, ``, structural tags | Not permitted inside `text` | ### Permitted inline tag: `` for links The `` tag is permitted for hyperlinks. See **Link Style Injection** below for detailed behavior. ### Allowed inline styles on `` and `` When using `` or ``, only the following CSS properties are permitted. These correspond to the properties the parent `TextConfig` already manages — using them inline overrides those values for the spanned content only. | CSS property | Example value | |---|---| | `font-weight` | `"700"`, `"400"`, `"bold"` | | `font-style` | `"italic"`, `"normal"` | | `font-size` | `"14px"`, `"1.2em"` | | `color` | `"#6366f1"` | | `background-color` | `"#fef9c3"` | | `text-decoration` | `"underline"`, `"line-through"`, `"none"` | | `letter-spacing` | `"1px"` | | `text-transform` | `"uppercase"`, `"capitalize"` | | `vertical-align` | `"super"`, `"sub"` | | `font-family` | `"Georgia, serif"` | **Do not use** layout-related properties (`margin`, `padding`, `display`, `width`, `float`, etc.) on inline elements inside `text`. These are not meaningful in this context and will produce unpredictable results in email clients. ### Correct and incorrect examples **✅ Correct — use `` with `font-weight` for bold text:** ```json "text": "

Your order is confirmed.

" ``` **❌ Incorrect — do not use ``:** ```json "text": "
Your order is confirmed.
" ``` **✅ Correct — use `` with `font-style` for italic text:** ```json "text": "
Terms apply. See terms and conditions.
" ``` **❌ Incorrect — do not use `` or ``:** ```json "text": "
Terms apply. See terms and conditions.
" ``` **✅ Correct — use `` with `color` for inline color changes:** ```json "text": "
Price: $0.00
" ``` **✅ Correct — use multiple `
` tags instead of `
`:** ```json "text": "
Line one
Line two
" ``` **❌ Incorrect — do not use `
`:** ```json "text": "
Line one
Line two
" ``` **✅ Correct — link with manual color override:** ```json "text": "Visit our site
" ``` --- ## `text` vs `children` `Text` accepts content in two ways: **`config.text` (string)** — an HTML string rendered via `dangerouslySetInnerHTML`. Link styles are automatically injected into `` tags inside the HTML via `injectLinkStyles`. This is the standard mode used by the builder. ```json "text": "
Visit our website for details.
" ``` **`children` (React nodes)** — rendered directly inside the styled `
`. Used when composing `Text` programmatically in React. `injectLinkStyles` is not applied in this mode. If both `config.text` and `children` are provided, `config.text` takes precedence. --- ## `maxWidth` Behavior `maxWidth` uses the same Outlook Classic compatibility pattern as `Column.maxWidth`: - The outer `` stays at `width: 100%` — it always fills its parent cell - Inside it, `` handles horizontal centering in Outlook Classic (Word engine) - Inside ``, an inner table with `width={maxWidth}` as an HTML attribute — Outlook Classic respects this as a hard pixel cap - Modern clients receive `max-width: {maxWidth}` as CSS on the same table > **Important:** `maxWidth` is **not** applied to the inner `
` — CSS `max-width` on a `
` is ignored by Outlook Classic. The constraint is enforced at the table level only. **When to use:** When a Text block sits in a wide column but you want to limit the line length for readability. For example, a 600px Section containing a single text column where lines should cap at 480px. ```json "config": { "maxWidth": "480px", "textAlign": "center" } ``` --- ## Link Style Injection (`injectLinkStyles`) The `Text` component uses `injectLinkStyles` to automatically manage link styles. Understanding how it works is critical for correct AI-generated content. ### What `injectLinkStyles` Does When `config.text` is a string, the component runs the HTML through `injectLinkStyles`, which: 1. Parses the HTML and finds all `` tags 2. For each `` tag, examines its existing inline `style` attributes 3. **Conditionally injects** missing styles for `color` and `text-decoration` only when: - The property is **not already defined** on the `` tag's inline style, AND - The property is **not inheriting** a valid value from parent elements ### The Algorithm (Simplified) For each `` tag, `injectLinkStyles` checks two properties: `color` and `text-decoration`. **For each property:** - If the `` tag already has this property defined in its inline `style` attribute → **DO NOTHING** (keep the manual value) - If the `` tag does NOT have this property defined: - Try to inherit from parent elements (like a surrounding ``) - If no inherited value exists, use the `fallback` from the text component's config (e.g., `color`, `textDecoration`) - If no fallback exists for `text-decoration`, default to `"none"` **Key takeaway:** Manual inline styles on `` tags are **never overwritten**. They always take precedence. ### Link Style Resolution Examples **Example 1: No manual styles on ``** ```html Click here ``` Result: Receives `color` and `text-decoration` from text config (fallback). If config has `color: "#3b82f6"` and `textDecoration: "underline"`, the link gets those. **Example 2: Manual `color` only** ```html Click here ``` Result: - `color: #ff0000` → **preserved** (manual wins) - `text-decoration` → injected from text config (or defaults to `"none"`) **Example 3: Manual `text-decoration` only** ```html Click here ``` Result: - `text-decoration: none` → **preserved** (manual wins) - `color` → injected from text config **Example 4: Both properties manually defined** ```html Click here ``` Result: Both properties preserved. Nothing is injected. Your manual styles win completely. **Example 5: Inherited from parent ``** ```html Click here ``` Result: - No manual styles on `` - `color` is inherited from the parent `` → `#00ff00` is used - `text-decoration` injected from text config (or defaults to `"none"`) ### Summary: What `injectLinkStyles` Does NOT Do - ❌ It does **NOT** remove or override any existing inline styles on `` tags - ❌ It does **NOT** prevent you from adding any supported style property to `` tags - ❌ It does **NOT** restrict what colors, decorations, or weights you can apply to links - ❌ It does **NOT** inject styles for properties already defined on the `` tag ### Best Practices for AI-Generated Content **✅ You can safely add any supported inline style to `` tags** — they will never be stripped or overridden: ```html Custom styled link ``` **✅ You can rely on automatic injection** — if you don't specify styles, the component ensures links look consistent with your text config: ```html Link that inherits text styles ``` **✅ You can mix both approaches** — let the component handle some properties while manually controlling others: ```html Bold link that inherits color from text config ``` --- ## `wordBreak` Default Unlike all other properties, `wordBreak` has a **non-`undefined` default**: it defaults to `"break-all"` when not specified. This prevents long URLs or unbroken strings from overflowing narrow email columns in most clients. Set `wordBreak: "normal"` explicitly if you need standard word-break behavior (e.g., for CJK text or controlled layouts where overflow is handled elsewhere). --- ## React Usage ```tsx import Text, { TextConfig } from './Text'; // String HTML content (standard) const config: TextConfig = { text: '
Hello world
', fontSize: '16px', color: '#111827', lineHeight: '1.6', padding: '16px 24px', }; // React node children (programmatic) Custom content ``` The component is memoized via `arePropsEqual`. Pass stable `config` objects to avoid re-renders. --- ## Common Patterns & Examples ### 1. Body paragraph ```json { "id": "body-text", "type": "TextComponent", "config": { "text": "
Your order has been confirmed and will ship within 2 business days.
", "fontSize": "16px", "fontFamily": "Arial, sans-serif", "color": "#374151", "lineHeight": "1.6", "padding": "0 0 16px 0" } } ``` ### 2. Section heading within Text component ```json { "id": "text-section-heading", "type": "TextComponent", "config": { "text": "
Welcome back, Alex
", "fontSize": "28px", "fontWeight": "700", "color": "#111827", "lineHeight": "1.2", "textAlign": "center", "padding": "0 0 8px 0" } } ``` ### 3. Link with automatic style injection (no manual styles) ```json { "id": "footer-legal", "type": "TextComponent", "config": { "text": "
You received this email because you signed up at example.com. Unsubscribe
", "fontSize": "12px", "color": "#9ca3af", "textAlign": "center", "lineHeight": "1.5", "padding": "16px 24px" } } ``` The unsubscribe link automatically receives `color: #9ca3af` via `injectLinkStyles`. ### 4. Link with manual style override ```json { "id": "promo-link", "type": "TextComponent", "config": { "text": "
Special offer ends soon
", "fontSize": "16px", "color": "#3b82f6", "textDecoration": "none" } } ``` The link keeps `color: #ff0000` and `font-weight: 800` (manual wins). `text-decoration` is NOT injected because the text config has `textDecoration: "none"` which becomes the fallback. ### 5. Link inheriting from parent span ```json { "id": "inherited-link", "type": "TextComponent", "config": { "text": "
Check this deal
", "fontSize": "16px", "color": "#3b82f6", "textDecoration": "underline" } } ``` The link inherits `color: #00aa00` from the parent ``. `text-decoration: underline` is injected from the text config since the link has no manual decoration. ### 6. Mixed inline styles (bold + colored span) ```json { "id": "mixed-inline", "type": "TextComponent", "config": { "text": "
Save 30% on your next order.
", "fontSize": "16px", "color": "#111827", "lineHeight": "1.5" } } ``` ### 7. Constrained reading-width text ```json { "id": "article-body", "type": "TextComponent", "config": { "text": "
Long-form article content goes here...
", "maxWidth": "480px", "textAlign": "left", "fontSize": "16px", "color": "#374151", "lineHeight": "1.7", "padding": "0" } } ``` ### 8. RTL text block ```json { "id": "rtl-text", "type": "TextComponent", "config": { "text": "
مرحباً بك في متجرنا
", "direction": "rtl", "textAlign": "right", "fontFamily": "Arial, sans-serif", "fontSize": "16px", "color": "#111827", "lineHeight": "1.8" } } ``` ### 9. Highlighted callout text with background ```json { "id": "highlight-text", "type": "TextComponent", "config": { "text": "
Limited time offer: Free shipping on all orders over $50.
", "fontSize": "15px", "color": "#713f12", "backgroundColor": "#fef9c3", "padding": "12px 16px", "lineHeight": "1.5", "wordBreak": "break-word" } } ``` --- ## Data Bindings `Text` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Leaf components do not support `dataList` or `itemAlias` — use those on a parent `Container`, `Column`, or `Row` to repeat the component. `visible` and `propertyMap` are fully supported. ```json { "id": "promo-text", "type": "TextComponent", "bindings": { "visible": "user.isPremium === true", "propertyMap": { "config.text": "promo.body", "config.color": "promo.textColor" } }, "config": { "text": "
Fallback text
", "fontSize": "16px", "color": "#111827" } } ``` | Property | Description | |---|---| | `visible` | JS expression evaluated against the Data Layer. Hides this component when falsy. | | `propertyMap` | Maps component property paths (prefixed with `config.`) to Data Layer paths. | > Bindable properties include `config.text`, `config.color`, `config.backgroundColor`, `config.fontSize`, `config.fontFamily`, `config.padding`, and any other scalar `TextConfig` field. --- ## Rules & Constraints - **`config.text` must only contain permitted HTML.** Block elements (`
`, `
`–`
`, `
`, `
`, `
`, `
`) and `` and `` are the only allowed tags. All semantic inline tags (``, ``, ``, ``, ``, `
`, etc.) are forbidden. - **Use `` for bold, never `` or ``.** Semantic weight tags are not supported. - **Use `` for italic, never `` or ``.** Semantic emphasis tags are not supported. - **Manual inline styles on `` tags are never removed or overridden** — `injectLinkStyles` only adds missing `color` and `text-decoration` properties. - **You can add any supported style property to `` tags** (`color`, `text-decoration`, `font-weight`, `font-style`). - **`` and `` may only carry allowed inline CSS properties.** Layout properties (`margin`, `padding`, `display`, `width`, etc.) are not permitted. - **`wordBreak` defaults to `"break-all"`** unless explicitly set. This is the only property with a non-`undefined` default. Set `"normal"` to opt out. - **`maxWidth` is enforced at the table level, not on the `
`.** Do not attempt to replicate this behavior using CSS on inner elements — Outlook Classic will ignore it. - **`padding` is the only spacing mechanism.** There is no `margin` on `Text`. Use `padding` on this component or `gap` on the parent `Column` for spacing between text blocks. - **`backgroundColor` applies to the outer ``, not the `
`.** It covers the full padded area including the padding space. - **`text` takes precedence over `children`** when both are supplied. - **Link styles are only injected when `text` is a string.** React node `children` receive no automatic link styling — style links manually in that case. - **`listStyle` is informational.** It is stored in config and consumed by the builder UI, but is not applied as CSS by this component's renderer. - **`opacity` applies to the inner `
`**, not the ``. This means `backgroundColor` (on the ``) is not affected by `opacity` — the background remains fully opaque even when `opacity < 1`. - **`textAlign` is applied both as CSS and as the HTML `align` attribute** on the `` for Outlook Classic compatibility. No special handling needed — set `textAlign` normally. --- ## Quick Reference Card | Do ✅ | Don't ❌ | |------|---------| | `text` | `text` | | `text` | `text` | | `text` | `text` | | `text` | `text` | | `link` (manual color) | Worrying that manual styles will be stripped | | `link` (relies on injection) | Adding unsupported CSS properties | | Use separate `
` tags for line breaks | `
` tags | | Combine spans: `` | Nest spans unnecessarily | | Let `injectLinkStyles` fill missing `color` and `text-decoration` | Assuming injection overrides your manual styles | --- ## Technical Reference: `injectLinkStyles` Behavior For implementers and advanced users, here is the exact behavior of `injectLinkStyles`: ```typescript // Properties that injectLinkStyles manages const BROWSER_LINK_DEFAULTS = ["color", "text-decoration"]; // Resolution logic for each anchor: // 1. If property exists in anchor's inline style → preserve it (skip injection) // 2. Else if property can be inherited from parent elements → use inherited value // 3. Else if fallback exists from text config → use fallback // 4. Else if property === "text-decoration" → default to "none" // 5. Else → leave undefined (property not added) ``` **This means:** - Your manual `color` and `text-decoration` are **sacred** — never touched - Only links missing these properties receive automatic values - Inheritance from parent `` elements is respected - The text config's `color` and `textDecoration` act as fallbacks, not overrides --- SECTION: TABLE --- # Table Pattern — LLM Reference This document teaches how to build table-like layouts using `Row` and `Column` components. Since no dedicated `Table` component exists, you compose tables by nesting `Row` (horizontal arrangement) inside `Column` (vertical arrangement), all within a `Container`. --- ## Core Concept — Correct Nesting ``` ContainerComponent ← email width container (fixed width only) └── ColumnComponent ← vertical stacking container (required) ├── RowComponent ← table row (horizontal) │ ├── ColumnComponent ← table cell │ └── ColumnComponent ← table cell ├── RowComponent ← table row (horizontal) │ ├── ColumnComponent ← table cell │ └── ColumnComponent ← table cell └── RowComponent ← table row (horizontal) └── ... ``` **Critical:** - `Row` must always be a child of `Column`, never directly inside `Container` - `Container` uses `widthType: "fixed"` only (no `"full"` value) — tables require a fixed pixel width | Component | Role | |---|---| | `ContainerComponent` | Fixed-width email container (e.g., `600px`) | | `ColumnComponent` (parent) | Vertical stacking container — holds all table rows | | `RowComponent` | Represents a **table row** — arranges cells horizontally | | `ColumnComponent` (child of Row) | Represents a **table cell** — contains content | --- ## Row Height Consistency To ensure all rows in a table have the same height, apply the `height` property on `Row` components whenever necessary. This prevents uneven row heights caused by varying content lengths across cells. ```json { "id": "consistent-height-row", "type": "RowComponent", "config": { "layoutColumns": ["33%", "34%", "33%"], "gap": "0px", "fillWidth": true, "height": "60px" }, "children": [...] } ``` **When to use `height`:** - Cells contain content of different lengths (e.g., short text vs. multi-line text) - Images or media of varying sizes appear in the same row - Ensuring visual alignment across complex table layouts **Best practice:** Set the same `height` value on all `Row` components within a table to guarantee uniform row dimensions. --- ## Border Application on Entire Row When there is a high possibility that row heights are not even, borders must be applied on the **entire row** (using `Row` configuration) rather than on individual cells. This prevents broken or misaligned border lines that occur when cells have different heights. ### Incorrect — Border on Cells (Height Mismatch Risk) ```json { "id": "bad-row", "type": "RowComponent", "config": { "layoutColumns": ["50%", "50%"], "gap": "0px", "fillWidth": true }, "children": [ { "id": "cell-1", "type": "ColumnComponent", "config": { "padding": "12px", "border": { "bottom": { "width": "1px", "style": "solid", "color": "#cbd5e1" } } }, "children": [...] }, { "id": "cell-2", "type": "ColumnComponent", "config": { "padding": "12px", "border": { "bottom": { "width": "1px", "style": "solid", "color": "#cbd5e1" } } }, "children": [...] } ] } ``` ### Correct — Border on Entire Row ```json { "id": "good-row", "type": "RowComponent", "config": { "layoutColumns": ["50%", "50%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#cbd5e1" } } }, "children": [ { "id": "cell-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "id": "cell-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] } ] } ``` **Why row-level borders are safer:** - The border spans the full width of the row regardless of individual cell heights - No gaps or breaks appear when cell content heights differ - Maintains visual integrity across all email clients **When to use row borders vs. cell borders:** | Scenario | Recommendation | |---|---| | Uneven row heights possible | Apply border on `Row` component | | All cells have identical content height | Cell borders acceptable | | Table has complex responsive behavior | Row borders preferred | | Borders required on all four sides of table | Use row borders for horizontal lines, container border for outer frame | --- ## Basic Table Structure ```json { "id": "table-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" } }, "children": [ { "id": "table-column-wrapper", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "header-row", "type": "RowComponent", "config": { "layoutColumns": "equal", "gap": "0px", "fillWidth": true, "backgroundColor": "#1e293b", "height": "50px" }, "children": [ { "id": "header-cell-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [ { "id": "header-text-1", "type": "TextComponent", "config": { "text": "Column A", "color": "#ffffff", "fontWeight": "bold" } } ] }, { "id": "header-cell-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [ { "id": "header-text-2", "type": "TextComponent", "config": { "text": "Column B", "color": "#ffffff", "fontWeight": "bold" } } ] } ] }, { "id": "data-row-1", "type": "RowComponent", "config": { "layoutColumns": "equal", "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e2e8f0" } } }, "children": [ { "id": "cell-1-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [ { "id": "text-1-1", "type": "TextComponent", "config": { "text": "Row 1, Cell A" } } ] }, { "id": "cell-1-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [ { "id": "text-1-2", "type": "TextComponent", "config": { "text": "Row 1, Cell B — additional content that might wrap to multiple lines" } } ] } ] }, { "id": "data-row-2", "type": "RowComponent", "config": { "layoutColumns": "equal", "gap": "0px", "fillWidth": true }, "children": [ { "id": "cell-2-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [ { "id": "text-2-1", "type": "TextComponent", "config": { "text": "Row 2, Cell A" } } ] }, { "id": "cell-2-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [ { "id": "text-2-2", "type": "TextComponent", "config": { "text": "Row 2, Cell B" } } ] } ] } ] } ] } ``` --- ## Controlling Column Widths with `layoutColumns` `layoutColumns` on `Row` determines how child `Column` components share space. **Use the same `layoutColumns` value for every row** to maintain column alignment. ### Equal Columns (2, 3, or more) ```json { "id": "row-3-columns", "type": "RowComponent", "config": { "layoutColumns": "equal", "gap": "0px", "fillWidth": true, "height": "60px" }, "children": [ { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] } ] } ``` Each cell gets `33.33%` width. ### Proportional Columns (Manual Percentages) ```json { "id": "row-asymmetric", "type": "RowComponent", "config": { "layoutColumns": ["25%", "50%", "25%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e2e8f0" } } }, "children": [ { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] } ] } ``` ### Fixed Width Columns ```json { "id": "row-fixed", "type": "RowComponent", "config": { "layoutColumns": ["100px", "auto", "150px"], "gap": "0px", "fillWidth": true, "height": "50px" }, "children": [ { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] } ] } ``` - First cell: fixed `100px` - Second cell: fills remaining space (`auto`) - Third cell: fixed `150px` --- ## Complete Table Example — 3×3 with Row Borders ```json { "id": "complete-table-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" } }, "children": [ { "id": "table-vertical-wrapper", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "header-row", "type": "RowComponent", "config": { "layoutColumns": ["30%", "40%", "30%"], "gap": "0px", "fillWidth": true, "backgroundColor": "#1e293b", "height": "55px" }, "children": [ { "id": "header-cell-1", "type": "ColumnComponent", "config": { "padding": "16px" }, "children": [{ "id": "header-text-1", "type": "TextComponent", "config": { "text": "Product", "color": "#ffffff", "fontWeight": "bold" } }] }, { "id": "header-cell-2", "type": "ColumnComponent", "config": { "padding": "16px" }, "children": [{ "id": "header-text-2", "type": "TextComponent", "config": { "text": "Description", "color": "#ffffff", "fontWeight": "bold" } }] }, { "id": "header-cell-3", "type": "ColumnComponent", "config": { "padding": "16px" }, "children": [{ "id": "header-text-3", "type": "TextComponent", "config": { "text": "Price", "color": "#ffffff", "fontWeight": "bold", "textAlign": "right" } }] } ] }, { "id": "row-1", "type": "RowComponent", "config": { "layoutColumns": ["30%", "40%", "30%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e2e8f0" } } }, "children": [ { "id": "cell-1-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-1-1", "type": "TextComponent", "config": { "text": "Basic Tee" } }] }, { "id": "cell-1-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-1-2", "type": "TextComponent", "config": { "text": "Cotton t-shirt, regular fit" } }] }, { "id": "cell-1-3", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-1-3", "type": "TextComponent", "config": { "text": "$29.00", "textAlign": "right" } }] } ] }, { "id": "row-2", "type": "RowComponent", "config": { "layoutColumns": ["30%", "40%", "30%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e2e8f0" } } }, "children": [ { "id": "cell-2-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-2-1", "type": "TextComponent", "config": { "text": "Premium Hoodie" } }] }, { "id": "cell-2-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-2-2", "type": "TextComponent", "config": { "text": "Fleece-lined, zip-up hoodie with extra warm lining for cold weather" } }] }, { "id": "cell-2-3", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-2-3", "type": "TextComponent", "config": { "text": "$89.00", "textAlign": "right" } }] } ] }, { "id": "footer-row", "type": "RowComponent", "config": { "layoutColumns": ["30%", "40%", "30%"], "gap": "0px", "fillWidth": true, "backgroundColor": "#f8fafc", "height": "50px" }, "children": [ { "id": "footer-cell-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "footer-text-1", "type": "TextComponent", "config": { "text": "Total" } }] }, { "id": "footer-cell-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "footer-text-2", "type": "TextComponent", "config": { "text": "2 items" } }] }, { "id": "footer-cell-3", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "footer-text-3", "type": "TextComponent", "config": { "text": "$118.00", "textAlign": "right", "fontWeight": "bold" } }] } ] } ] } ] } ``` --- ## Full Grid Borders (All Sides) — Row-Level Approach When borders are needed on all sides of a table with potential height mismatches, apply horizontal borders on `Row` components and use a container border for the outer frame. ```json { "id": "bordered-table-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" }, "border": { "all": { "width": "1px", "style": "solid", "color": "#cbd5e1" } } }, "children": [ { "id": "bordered-table-wrapper", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "row-1", "type": "RowComponent", "config": { "layoutColumns": ["33%", "34%", "33%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#cbd5e1" } } }, "children": [ { "id": "cell-1", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-1", "type": "TextComponent", "config": { "text": "Cell 1" } }] }, { "id": "cell-2", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-2", "type": "TextComponent", "config": { "text": "Cell 2 with longer content that might wrap" } }] }, { "id": "cell-3", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-3", "type": "TextComponent", "config": { "text": "Cell 3" } }] } ] }, { "id": "row-2", "type": "RowComponent", "config": { "layoutColumns": ["33%", "34%", "33%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#cbd5e1" } } }, "children": [ { "id": "cell-4", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-4", "type": "TextComponent", "config": { "text": "Cell 4" } }] }, { "id": "cell-5", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-5", "type": "TextComponent", "config": { "text": "Cell 5" } }] }, { "id": "cell-6", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-6", "type": "TextComponent", "config": { "text": "Cell 6 — even more text that causes this cell to be taller than others in the same row" } }] } ] } ] } ] } ``` **Note:** The container border wraps the entire table, while row borders provide horizontal lines that span the full width regardless of individual cell heights. --- ## Simulating Rowspan Since `Row` does not support `rowspan` natively, nest multiple `Row` components inside a `Column` on one side. ```json { "id": "rowspan-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" } }, "children": [ { "id": "rowspan-wrapper", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "rowspan-row", "type": "RowComponent", "config": { "layoutColumns": ["30%", "70%"], "gap": "0px", "fillWidth": true }, "children": [ { "id": "left-span-cell", "type": "ColumnComponent", "config": { "padding": "16px", "backgroundColor": "#fef3c7" }, "children": [ { "id": "span-content", "type": "TextComponent", "config": { "text": "This spans both rows vertically" } } ] }, { "id": "right-group-cell", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "sub-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "100%", "childrenConstraints": { "widthDistributionType": "equals" } }, "children": [ { "id": "sub-wrapper", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "sub-row-1", "type": "RowComponent", "config": { "layoutColumns": ["100%"], "gap": "0px", "fillWidth": true }, "children": [ { "id": "top-right-cell", "type": "ColumnComponent", "config": { "padding": "12px", "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e5e7eb" } } }, "children": [{ "id": "text-right-1", "type": "TextComponent", "config": { "text": "Top right row" } }] } ] }, { "id": "sub-row-2", "type": "RowComponent", "config": { "layoutColumns": ["100%"], "gap": "0px", "fillWidth": true }, "children": [ { "id": "bottom-right-cell", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-right-2", "type": "TextComponent", "config": { "text": "Bottom right row" } }] } ] } ] } ] } ] } ] } ] } ] } ``` --- ## Shopping Cart Table Example ```json { "id": "cart-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" } }, "children": [ { "id": "cart-wrapper", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "cart-header", "type": "RowComponent", "config": { "layoutColumns": ["40%", "15%", "20%", "25%"], "gap": "0px", "fillWidth": true, "backgroundColor": "#111827", "height": "50px" }, "children": [ { "id": "header-product", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-product", "type": "TextComponent", "config": { "text": "Product", "color": "#ffffff", "fontWeight": "bold" } }] }, { "id": "header-qty", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-qty", "type": "TextComponent", "config": { "text": "Qty", "color": "#ffffff", "fontWeight": "bold", "textAlign": "center" } }] }, { "id": "header-price", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-price", "type": "TextComponent", "config": { "text": "Price", "color": "#ffffff", "fontWeight": "bold", "textAlign": "right" } }] }, { "id": "header-total", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "text-total", "type": "TextComponent", "config": { "text": "Total", "color": "#ffffff", "fontWeight": "bold", "textAlign": "right" } }] } ] }, { "id": "cart-item-1", "type": "RowComponent", "config": { "layoutColumns": ["40%", "15%", "20%", "25%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e5e7eb" } } }, "children": [ { "id": "item1-product", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item1-name", "type": "TextComponent", "config": { "text": "Wireless Mouse" } }] }, { "id": "item1-qty", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item1-qty-num", "type": "TextComponent", "config": { "text": "2", "textAlign": "center" } }] }, { "id": "item1-price", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item1-price-val", "type": "TextComponent", "config": { "text": "$25.00", "textAlign": "right" } }] }, { "id": "item1-total", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item1-total-val", "type": "TextComponent", "config": { "text": "$50.00", "textAlign": "right", "fontWeight": "bold" } }] } ] }, { "id": "cart-item-2", "type": "RowComponent", "config": { "layoutColumns": ["40%", "15%", "20%", "25%"], "gap": "0px", "fillWidth": true, "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e5e7eb" } } }, "children": [ { "id": "item2-product", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item2-name", "type": "TextComponent", "config": { "text": "Mechanical Keyboard with RGB lighting and extra keycaps" } }] }, { "id": "item2-qty", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item2-qty-num", "type": "TextComponent", "config": { "text": "1", "textAlign": "center" } }] }, { "id": "item2-price", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item2-price-val", "type": "TextComponent", "config": { "text": "$129.00", "textAlign": "right" } }] }, { "id": "item2-total", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "item2-total-val", "type": "TextComponent", "config": { "text": "$129.00", "textAlign": "right", "fontWeight": "bold" } }] } ] }, { "id": "cart-footer", "type": "RowComponent", "config": { "layoutColumns": ["40%", "15%", "20%", "25%"], "gap": "0px", "fillWidth": true, "backgroundColor": "#f8fafc", "height": "50px" }, "children": [ { "id": "footer-empty", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [] }, { "id": "footer-label", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "footer-label-text", "type": "TextComponent", "config": { "text": "Subtotal:", "fontWeight": "bold", "textAlign": "right" } }] }, { "id": "footer-price", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [] }, { "id": "footer-total", "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [{ "id": "footer-total-text", "type": "TextComponent", "config": { "text": "$179.00", "textAlign": "right", "fontWeight": "bold" } }] } ] } ] } ] } ``` --- ## Quick Reference: Table Template ```json { "id": "table-template", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" } }, "children": [ { "id": "table-rows-wrapper", "type": "ColumnComponent", "config": { "padding": "0px" }, "children": [ { "id": "row-1", "type": "RowComponent", "config": { "layoutColumns": ["25%", "50%", "25%"], "gap": "0px", "fillWidth": true, "height": "60px", "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e2e8f0" } } }, "children": [ { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] } ] }, { "id": "row-2", "type": "RowComponent", "config": { "layoutColumns": ["25%", "50%", "25%"], "gap": "0px", "fillWidth": true, "height": "60px" }, "children": [ { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] }, { "type": "ColumnComponent", "config": { "padding": "12px" }, "children": [...] } ] } ] } ] } ``` --- ## Key Rules for Table Construction | Rule | Explanation | |---|---| | **Container → Column → Row** | Never put `Row` directly inside `Container`. Always wrap with a `Column`. | | **Container uses `widthType: "fixed"` only** | Tables require a fixed pixel width (e.g., `600px`). No `"full"` value. | | **Every table row is a `Row`** | `Row` provides horizontal arrangement of cells. | | **Every cell is a `Column`** | `Column` stacks content vertically within a cell. | | **Use `layoutColumns` on every row** | Ensures column widths stay consistent across all rows. | | **Same `layoutColumns` array for all rows** | Copy the exact same `layoutColumns` value across every row in the table. | | **Set `gap: "0px"` for tables** | Table cells should have no gap; use `Column.padding` for internal spacing. | | **Set `fillWidth: true` on table rows** | Ensures the row fills the container width for proper column distribution. | | **`Container.width` sets email width** | Use `width` on `Container` (with `widthType: "fixed"`) to control the overall table width. | | **Use `height` on rows for consistency** | Apply `height` property on `Row` components when uneven row heights are possible. | | **Apply borders on rows when heights may vary** | When there is a high possibility of uneven row heights, use `Row` borders instead of cell borders. | --- SECTION: SPACER --- # Spacer Component — LLM Reference `Spacer` is a **vertical whitespace primitive**. It renders a fixed-height transparent block that creates consistent vertical spacing between components in an email. It has no visual output beyond the space it occupies — no background, no border, no text. It is the correct tool for adding vertical rhythm between layout elements. --- ## Position in the Document Tree ``` DocumentTree └── Section └── Container └── Column └── Heading (Text) └── Spacer ← vertical gap between elements └── Text └── Spacer ← vertical gap before button └── Button ``` `Spacer` is a leaf node. It can be placed anywhere a child component is accepted: inside `Column`, `Row`, directly in a `Container` cell, or between any sibling components. --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "SpacerComponent", "config": { "height": "24px", "hideOnMobile": false } } ``` --- ## `SpacerConfig` — Full Property Reference | Property | Type | Required | Default | Description | |---|---|---|---|---| | `height` | `string` | ✓ Yes | — | Height of the vertical space. Must be a px value (e.g. `"16px"`, `"48px"`). | | `hideOnMobile` | `boolean` | No | `false` | When `true`, adds the `hide-on-mobile` CSS class to the outer table. The builder's global stylesheet collapses the spacer on mobile viewports. | --- ## How It Works `Spacer` creates vertical space using three reinforcing techniques for cross-client reliability: 1. **CSS `height`** on the `` — respected by modern email clients 2. **HTML `height` attribute** on both the `` and the `
` — required for Outlook Classic (Word rendering engine), which ignores CSS height on table cells 3. **`fontSize: "0"` and `lineHeight: "0"`** on the ` ` — suppresses any phantom vertical space that font metrics would otherwise add, even with no visible text content 4. **` `** inside the ` ` — ensures the cell renders in clients that collapse empty cells The outer table uses `width: 100%` so the spacer spans the full width of its parent column, maintaining layout integrity. --- ## `height` Format `height` must be a **pixel string** (e.g. `"24px"`). The numeric value is parsed and applied as both the CSS `height` and the HTML `height` attribute. Non-px values (e.g. `"1.5rem"`, `"10%"`) will have their integer portion extracted via `parseInt` — the `rem`/`%` unit will be silently dropped and the raw integer used as pixels. Always use `px` units for predictable behavior. ```json // Correct "height": "32px" // Avoid — unit stripped, only "10" used "height": "10%" ``` --- ## `hideOnMobile` When `hideOnMobile: true`, the outer table receives the `hide-on-mobile` CSS class. The builder's global `` stylesheet sets `display: none` on this class for mobile viewports. This allows a large desktop spacer to be hidden on mobile without a second Spacer component. ```json // Large desktop spacer, hidden on mobile { "id": "desktop-spacer", "type": "SpacerComponent", "config": { "height": "48px", "hideOnMobile": true } } // Paired small mobile spacer (always visible) { "id": "mobile-spacer", "type": "SpacerComponent", "config": { "height": "16px" } } ``` --- ## React Usage ```tsx import Spacer, { SpacerConfig } from './Spacer'; const config: SpacerConfig = { height: '24px', }; ``` The component is memoized via `arePropsEqual`. Pass a stable `config` reference to avoid re-renders. --- ## Spacer vs `gap` on Parent Components Both `Spacer` and parent `gap` properties create vertical space, but they serve different purposes: | | `Spacer` | `gap` on `Column` | |---|---|---| | **Mechanism** | Explicit child node in the tree | Config property on the parent | | **Granularity** | Per-gap, any size | Uniform between all children | | **Mobile control** | `hideOnMobile` per spacer | Single value for all gaps | | **Outlook support** | ✓ Full (HTML attribute + CSS) | ✓ Full (spacer ` ` row) | | **When to use** | Different spacing between specific pairs of children, or mobile-responsive spacing | Uniform spacing between all children in a column | Use `gap` on `Column` when all children should be evenly spaced. Use `Spacer` when you need variable spacing between specific elements, or when you need mobile-specific control over individual gaps. --- ## Common Patterns & Examples ### 1. Standard content gap ```json { "id": "spacer-16", "type": "SpacerComponent", "config": { "height": "16px" } } ``` --- ### 2. Section breathing room (top/bottom of a column) ```json { "id": "spacer-top", "type": "SpacerComponent", "config": { "height": "40px" } } ``` --- ### 3. Large desktop spacer, hidden on mobile ```json { "id": "spacer-hero-gap", "type": "SpacerComponent", "config": { "height": "64px", "hideOnMobile": true } } ``` --- ### 4. Spacer between heading and body text ```json [ { "id": "spacer-ex-heading", "type": "TextComponent", "config": { "text": "
Our latest products
", "fontSize": "24px", "fontWeight": "700" } }, { "id": "spacer-heading-body", "type": "SpacerComponent", "config": { "height": "12px" } }, { "id": "body", "type": "TextComponent", "config": { "text": "
Discover our new arrivals this season.
", "fontSize": "16px" } } ] ``` --- ## Data Bindings `Spacer` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Leaf components do not support `dataList` or `itemAlias` — use those on a parent `Container`, `Column`, or `Row` to repeat the component. `visible` and `propertyMap` are fully supported. ```json { "id": "dynamic-spacer", "type": "SpacerComponent", "bindings": { "visible": "layout.showSpacing === true" }, "config": { "height": "32px" } } ``` | Property | Description | |---|---| | `visible` | JS expression evaluated against the Data Layer. Hides this component when falsy. | | `propertyMap` | Maps component property paths (prefixed with `config.`) to Data Layer paths. | > `Spacer` has no meaningful `propertyMap` targets beyond `config.height`. Conditional rendering via `visible` is the primary binding use case. --- ## Rules & Constraints - **`height` is required.** There is no default — omitting it will cause a broken render. Always provide a `px` string value. - **Use `px` units only.** Non-px values are silently truncated to their integer portion and treated as pixels. `"1.5rem"` becomes `1`, `"10%"` becomes `10` — both likely unintended. - **`Spacer` has no visual properties.** It cannot have a background color, border, or content. It is transparent by design. To create a visible divider, use a `Container` or `Row` with a `border` instead. - **Do not use `Spacer` for horizontal spacing.** It always renders at `width: 100%`. Horizontal gaps between siblings are handled by the `gap` property on `Container`, `Column`, or `Row`. - **`hideOnMobile` requires the global stylesheet.** The `hide-on-mobile` class has no effect without the builder's `` CSS. In isolated rendering contexts, the spacer will always be visible regardless of this flag. - **Minimum effective height is `1px`.** `parseInt` falls back to `1` if the height string produces `0` or `NaN`. A `"0px"` spacer renders with `height: 1` in Outlook — use the `Column` or `Row` `gap` property instead if you need truly zero space. --- SECTION: SECTION --- # Section Component — LLM Reference `Section` is the **top-level structural wrapper** for an email. It renders as a full-width `` that spans the entire email width and acts as the outermost shell for a band of content. A template contains **exactly three Sections** — `header`, `content`, and `footer` — in fixed positions. They cannot be added, removed, reordered, or nested. Sections are **not** layout containers — they don't distribute children side-by-side. That is the job of `Container`. A Section holds one or more `Container` components stacked vertically as children, and those Containers handle column logic. --- ## Position in the Document Tree ``` Body (ComponentNode) └── children (Array) └── Section ← Full-width band └── Container ← Layout & width control └── Column ← Vertical stacking ``` A `Section` is always a **root-level node** in the `DocumentTree`. There are exactly three — `header`, `content`, `footer` — and their positions are fixed. They are never nested inside each other or inside a `Container`. --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "SectionComponent", "config": { "sectionType": "content", "backgroundColor": "#f3f4f6", "padding": "24px 0", "gap": "16px", "border": { "bottom": { "width": "1px", "style": "solid", "color": "#e5e7eb" } }, "backgroundImage": { "src": "https://example.com/bg.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" } }, "children": [] } ``` --- ## `SectionConfig` — Full Property Reference ### Required | Property | Type | Options | Description | |---|---|---|---| | `sectionType` | `string` | `"header"`, `"footer"`, `"content"` | Semantic role of the section. Used for labeling and dev tooling — does not affect visual rendering. | ### Layout | Property | Type | Example | Description | |---|---|---|---| | `padding` | `string` | `"48px 0"` | Inner padding applied to the single `
` that wraps all children. CSS shorthand. | | `gap` | `string` | `"16px"` | Vertical space between children (informational — consumed by the builder's layout engine, not directly rendered by this component). | ### Visual | Property | Type | Example | Description | |---|---|---|---| | `backgroundColor` | `string` | `"#1e1b4b"` | Background fill color for the full-width band | | `border` | `BorderConfig` | See below | Border applied to the outer `` element | | `backgroundImage` | `object` | See below | Background image for the section band | ### `BorderConfig` Specify either a **full border** (all sides) or **individual sides**. Do not mix both in the same object. ```json // Full border — all sides "border": { "width": "1px", "style": "solid", "color": "#e5e7eb" } // Per-side border "border": { "top": { "width": "3px", "style": "solid", "color": "#6366f1" } } ``` Supported side keys: `"top"`, `"right"`, `"bottom"`, `"left"`. Each side object requires all three of: `width`, `style`, `color`. When individual sides are specified, all other sides are explicitly set to `"none"` to prevent Outlook from rendering phantom black borders. ### `backgroundImage` ```json "backgroundImage": { "src": "https://example.com/texture.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" } ``` | Property | Type | Description | |---|---|---| | `src` | `string` | Absolute URL of the image | | `repeat` | `string` | Any CSS `background-repeat` value: `"no-repeat"`, `"repeat"`, `"repeat-x"`, `"repeat-y"` | | `size` | `string` | Any CSS `background-size` value: `"cover"`, `"contain"`, `"auto"` | | `position` | `string` | Any CSS `background-position` value: `"center center"`, `"top left"`, etc. | --- ## Section vs Container — Key Differences | | `Section` | `Container` | |---|---|---| | **Purpose** | Full-width email band | Multi-column layout | | **Width** | Always 100% | `"full"` or `"fixed"` (e.g. `"600px"`) | | **Column layout** | ✗ No | ✓ Yes (`childrenConstraints`) | | **Position in tree** | Root level only | Inside a Section | | **Stacking direction** | Vertical (Sections stack top-to-bottom) | Horizontal (children placed left-to-right) | | **Background image** | ✓ Yes | ✓ Yes | | **Border** | ✓ Yes | ✓ Yes | | **Border radius** | ✗ No | ✓ Yes | | **`alignItems`** | ✗ No | ✓ Yes | | **`justifyContent`** | ✗ No | ✓ Yes | --- ## React Usage ```tsx import Section, { SectionConfig } from './Section'; const config: SectionConfig = { sectionType: 'content', backgroundColor: '#f9fafb', padding: '32px 0', };

``` The component is memoized via `arePropsEqual`. Pass stable `config` references (e.g. with `useMemo`) to avoid unnecessary re-renders. --- ## `sectionType` Semantics `sectionType` is a semantic label — it has no effect on rendered styles but is used by the builder's dev overlay and accessibility labels. | Value | Intended use | |---|---| | `"header"` | Logo bar, navigation, pre-header text | | `"content"` | Body rows — hero, product blocks, articles, CTAs | | `"footer"` | Unsubscribe links, legal text, social icons, address | Each value maps to exactly one Section in the template. There is one `"header"`, one `"content"`, and one `"footer"` — never more. --- ## Common Patterns & Examples ### 1. Minimal content section ```json { "id": "section-body", "type": "SectionComponent", "config": { "sectionType": "content", "backgroundColor": "#ffffff", "padding": "0" }, "children": [] } ``` --- ### 2. Header section with brand background ```json { "id": "section-header", "type": "SectionComponent", "config": { "sectionType": "header", "backgroundColor": "#1e1b4b", "padding": "16px 0" }, "children": [ { "id": "header-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" }, "justifyContent": "center", "padding": "0 24px" }, "children": [] } ] } ``` --- ### 3. Footer section with top border divider ```json { "id": "section-footer", "type": "SectionComponent", "config": { "sectionType": "footer", "backgroundColor": "#f9fafb", "padding": "24px 0", "border": { "top": { "width": "1px", "style": "solid", "color": "#e5e7eb" } } }, "children": [] } ``` --- ### 4. Hero section with full-bleed background image ```json { "id": "sec-section-hero", "type": "SectionComponent", "config": { "sectionType": "content", "backgroundColor": "#000000", "padding": "0", "backgroundImage": { "src": "https://example.com/hero.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" } }, "children": [ { "id": "hero-container", "type": "ContainerComponent", "config": { "widthType": "fixed", "width": "600px", "childrenConstraints": { "widthDistributionType": "equals" }, "justifyContent": "center", "alignItems": "center", "padding": "80px 40px" }, "children": [] } ] } ``` --- ### 5. Striped layout using multiple Containers Since a template has exactly one `content` Section, alternating background rows are achieved with multiple `Container` children stacked inside it — not multiple Sections. ```json { "id": "section-content", "type": "SectionComponent", "config": { "sectionType": "content", "backgroundColor": "#ffffff", "padding": "0" }, "children": [ { "id": "row-1", "type": "ContainerComponent", "config": { "widthType": "full", "childrenConstraints": { "widthDistributionType": "equals" }, "backgroundColor": "#ffffff", "padding": "32px 24px" }, "children": [] }, { "id": "row-2", "type": "ContainerComponent", "config": { "widthType": "full", "childrenConstraints": { "widthDistributionType": "equals" }, "backgroundColor": "#f3f4f6", "padding": "32px 24px" }, "children": [] }, { "id": "row-3", "type": "ContainerComponent", "config": { "widthType": "full", "childrenConstraints": { "widthDistributionType": "equals" }, "backgroundColor": "#ffffff", "padding": "32px 24px" }, "children": [] } ] } ``` --- ### 6. Section with data binding (conditional visibility) ```json { "id": "sec-promo-visible", "type": "SectionComponent", "bindings": { "visible": "user.hasActivePromo === true" }, "config": { "sectionType": "content", "backgroundColor": "#fef9c3", "padding": "16px 0", "border": { "bottom": { "width": "2px", "style": "solid", "color": "#facc15" } } }, "children": [] } ``` --- ## Data Bindings `Section` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Bindings connect this component to the Data Layer for dynamic rendering. ```json { "id": "sec-promo-bindings", "type": "SectionComponent", "bindings": { "visible": "user.hasActivePromo === true", "propertyMap": { "config.backgroundColor": "promo.bgColor" } }, "config": { "sectionType": "content", "backgroundColor": "#fef9c3", "padding": "16px 0" }, "children": [] } ``` | Property | Description | |---|---| | `dataList` | Not applicable. Sections are fixed structural slots — they cannot be repeated. Use `dataList` on a `Container` child instead. | | `itemAlias` | Not applicable for the same reason — use on `Container`. | | `visible` | JS expression evaluated against the Data Layer. Hides the entire section band when falsy. | | `propertyMap` | Maps `config` property paths to Data Layer paths (e.g. `"config.backgroundColor"` → `"promo.bgColor"`). | --- ## Rules & Constraints - **Exactly three, fixed positions.** A template always has exactly one `header`, one `content`, and one `footer` Section. They cannot be added, removed, reordered, or nested inside any other component. - **One `
` only.** The Section renders a single cell. All width constraint and column logic must live inside a `Container` child. - **`padding` applies to the inner cell**, not the outer table. For full-bleed background colors or images, set `padding: "0"` on the Section and add padding inside the child Container instead. - **`gap` is informational.** The `gap` property on Section is stored in config but is consumed by the builder's drag-and-drop engine for spacing between Sections — it is not applied as CSS by this component. - **`border` renders on the outer ``.** Unlike `Container`, there is no border-radius support on Section — borders will always be square-cornered. - **Background image layering.** `backgroundColor` acts as a fallback when the background image fails to load. Always set a contrasting `backgroundColor` alongside any `backgroundImage`. - **`sectionType` does not affect styles.** It is only a semantic label for dev tooling and accessibility. Any `sectionType` value can use any visual config. --- SECTION: ROW --- # Row Component — LLM Reference `Row` is a **horizontal arrangement primitive** that sits inside a `Container` column. It places its children side-by-side in a single ``, handles gap columns between them, and supports alignment, padding, background styling, borders, links, and mobile stacking. It does **not** control email-level width — that is the job of `Container`. --- ## Position in the Document Tree ``` DocumentTree └── Section ← full-width band └── Container ← column layout & email width └── Row ← horizontal child arrangement └── Image / Text / Button / ... ``` A `Row` lives inside a `Container` (or another component that acts as a column). Unlike `Container`, a `Row` does not manage fixed vs. full width at the email level — it fills whatever space its parent column provides. --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "RowComponent", "config": { "gap": "16px", "justifyContent": "center", "alignItems": "center", "fillWidth": false, "layoutColumns": "equal", "padding": "12px", "backgroundColor": "#ffffff", "borderRadius": "8px", "border": { "width": "1px", "style": "solid", "color": "#e5e7eb" }, "backgroundImage": { "src": "https://example.com/bg.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" }, "width": "100%", "height": "64px", "innerLink": { "type": "url", "url": "https://example.com", "target": "_blank" }, "mobile": { "wrap": true, "justifyContent": "center", "alignItems": "start" } }, "children": [] } ``` --- ## `RowConfig` — Full Property Reference ### Layout | Property | Type | Example | Description | |---|---|---|---| | `gap` | `string` | `"16px"` | Horizontal space between children. Rendered as a gap `
`. Also used as vertical gap between stacked children on mobile. | | `justifyContent` | `"start" \| "center" \| "end"` | `"center"` | Horizontal alignment of children within the row | | `alignItems` | `"start" \| "center" \| "end"` | `"center"` | Vertical alignment of children within the row | | `width` | `string` | `"100%"` | Width of the outer row table. Defaults to `100%`. | | `height` | `string` | `"80px"` | Fixed height applied to all table levels | | `fillWidth` | `boolean` | `true` | See **`fillWidth` vs `layoutColumns`** section below | | `layoutColumns` | `"equal" \| string[]` | `"equal"` | Controls per-child ` ` width distribution. See below. | ### Visual | Property | Type | Example | Description | |---|---|---|---| | `padding` | `string` | `"16px 24px"` | Inner padding applied inside the border wrapper | | `backgroundColor` | `string` | `"#f9fafb"` | Background fill color | | `borderRadius` | `string` | `"8px"` | Rounds all corners (also clips background) | | `border` | `BorderConfig` | See below | Border on the outer wrapper table | | `backgroundImage` | `BackgroundImageType` | See below | Background image for the row | ### Interactivity | Property | Type | Description | |---|---|---| | `innerLink` | `IInnerLink` | Wraps the entire row in an `` tag. See **Link Support** section. | ### Mobile | Property | Type | Description | |---|---|---| | `mobile.wrap` | `boolean` | When `true`, children stack vertically on mobile. Gap is injected as a spacer between stacked children. | | `mobile.justifyContent` | `"start" \| "center" \| "end"` | Overrides `justifyContent` on mobile | | `mobile.alignItems` | `"start" \| "center" \| "end"` | Overrides `alignItems` on mobile | --- ## `fillWidth` vs `layoutColumns` — Critical Distinction These two properties both control how the content table expands, but they serve different purposes and can be combined. ### `fillWidth` Controls whether the inner content table uses `width: 100%` or `width: auto`. | `fillWidth` | Content table width | Use case | |---|---|---| | `false` / `undefined` (default) | `width: auto` | Children shrink-wrap to natural size. Use for icon rows, button rows, social links. | | `true` | `width: 100%` | Children get a constrained box — text can wrap correctly in Outlook. Use for rows mixing text + images. | ### `layoutColumns` Controls how each child ` ` is sized. When set, also forces `table-layout: fixed` and `width: 100%` on the content table (regardless of `fillWidth`). | Value | Behavior | |---|---| | `undefined` (default) | No width is set on child ` `s — original shrink-wrap behavior | | `"equal"` | Each child gets `${100 / numChildren}%`. Works for any number of children. | | `string[]` | Explicit width per child (px, %, or mixed). Array **must** match children count exactly. | ```json // Equal: 3 children each get 33.33% "layoutColumns": "equal" // Manual: explicit per-child widths "layoutColumns": ["200px", "1fr", "80px"] // Mixed units are allowed — author is responsible for not overflowing "layoutColumns": ["60%", "40%"] ``` > **Note:** When using `%` values in `layoutColumns`, ensure they total ≤ 100% after accounting for any `gap`. Overflow behavior is undefined and client-dependent — the same trade-off accepted by MJML and Foundation for Emails. ### Decision Guide | Scenario | `fillWidth` | `layoutColumns` | |---|---|---| | Icon row, button row, social links | `false` | `undefined` | | Text + image side by side | `true` | `undefined` | | Equal-width columns (e.g. 3 product cards) | either | `"equal"` | | Asymmetric columns (e.g. 70/30 split) | either | `["70%", "30%"]` | | Fixed sidebar + fluid content | either | `["200px", "auto"]` | --- ## `BorderConfig` Specify either a **full border** (all sides) or **individual sides**. Do not mix both. ```json // Full border — all sides "border": { "width": "1px", "style": "solid", "color": "#e5e7eb" } // Per-side — other sides are explicitly set to "none" (Outlook-safe) "border": { "left": { "width": "4px", "style": "solid", "color": "#6366f1" } } ``` Supported side keys: `"top"`, `"right"`, `"bottom"`, `"left"`. Each side requires all three of: `width`, `style`, `color`. --- ## `backgroundImage` ```json "backgroundImage": { "src": "https://example.com/texture.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" } ``` | Property | Options | |---|---| | `repeat` | `"no-repeat"`, `"repeat"`, `"repeat-x"`, `"repeat-y"` | | `size` | `"auto"`, `"cover"`, `"contain"` | | `position` | Any valid CSS `background-position` string | Always pair with `backgroundColor` as a fallback for email clients that block images. --- ## Link Support (`innerLink`) When `innerLink` is set (and not `devMode`), the entire row is wrapped in an `` tag with `display: block`. The link is stripped in dev mode. ```json "innerLink": { "type": "url", "url": "https://example.com", "target": "_blank" } ``` | `type` | Required field | Rendered href | |---|---|---| | `"url"` | `url` | The URL as-is | | `"email"` | `email` | `mailto:{email}` | | `"phone"` | `phone` | `tel:{phone}` | | `"anchor"` | `anchor` | `#{anchor}` | | `"page_top"` | — | `#` | | `"page_bottom"` | — | `#bottom` | | `"none"` | — | No link rendered | `target` defaults to `"_blank"` if not specified. --- ## Mobile Stacking When `mobile.wrap: true` and there are 2+ children, the Row uses the same CSS-class-based stacking pattern as `Container` — compatible with Gmail's `@media` stripping. - Each child ` ` gets the `stack-td` class → forces `display: block; width: 100%` on mobile - Gap columns get `desktop-gap-column` → collapsed on mobile - A `mobile-gap-spacer` div is injected inside each child (except the last) → visible only on mobile, provides vertical spacing equal to `gap` ```json "config": { "gap": "16px", "mobile": { "wrap": true } } ``` > **Important:** `mobile.wrap` only activates stacking behavior. The `gap` value controls both horizontal gap (desktop) and vertical gap (mobile stack). If you want different spacing per breakpoint, that is not currently supported — one `gap` value serves both. --- ## React Usage ```tsx import Row, { RowConfig } from './Row'; const config: RowConfig = { gap: '16px', justifyContent: 'center', alignItems: 'center', fillWidth: false, }; ``` The component is memoized via `arePropsEqual`. Pass stable `config` objects to avoid re-renders. --- ## Row vs Container — Key Differences | | `Row` | `Container` | |---|---|---| | **Primary job** | Arrange children horizontally with alignment + gap | Control email column layout and fixed vs. full width | | **Width control** | Fills parent column (`width: 100%` default) | `"fixed"` (e.g. `600px`, centered) or `"full"` | | **Column sizing** | `layoutColumns` (`"equal"` or `string[]`) | `childrenConstraints` (`"equals"`, `"ratio"`, `"manual"`) | | **`fillWidth`** | ✓ Yes — shrink-wrap vs. full-width content table | ✗ No | | **Link wrapping** | ✓ Yes — `innerLink` wraps the whole row in `` | ✗ No | | **Mobile stacking** | ✓ Yes — `mobile.wrap` | ✓ Yes — `shouldWrap` | | **Border radius** | ✓ Yes | ✓ Yes | | **Background image** | ✓ Yes | ✓ Yes | | **`justifyContent`** | ✓ Yes — aligns children within the row | ✓ Yes — aligns the container table within its parent | --- ## Common Patterns & Examples ### 1. Icon/social link row (default shrink-wrap) ```json { "id": "row-social-icons", "type": "RowComponent", "config": { "gap": "12px", "justifyContent": "center", "alignItems": "center" }, "children": [] } ``` No `fillWidth`, no `layoutColumns` — children naturally size to their content. --- ### 2. Text + image side by side (fillWidth for Outlook wrapping) ```json { "id": "text-image-row", "type": "RowComponent", "config": { "gap": "24px", "alignItems": "center", "fillWidth": true, "layoutColumns": ["60%", "40%"], "mobile": { "wrap": true } }, "children": [] } ``` --- ### 3. Equal-width product cards (3-up) ```json { "id": "row-product-cards", "type": "RowComponent", "config": { "gap": "16px", "justifyContent": "center", "layoutColumns": "equal", "mobile": { "wrap": true } }, "children": [] } ``` --- ### 4. Single centered button ```json { "id": "cta-row", "type": "RowComponent", "config": { "justifyContent": "center", "padding": "8px 0" }, "children": [] } ``` No gap needed for a single child. No `layoutColumns` — button sizes to its natural width. --- ### 5. Clickable row (entire row is a link) ```json { "id": "link-row", "type": "RowComponent", "config": { "gap": "12px", "alignItems": "center", "fillWidth": true, "backgroundColor": "#f3f4f6", "padding": "16px", "borderRadius": "8px", "innerLink": { "type": "url", "url": "https://example.com/article", "target": "_blank" } }, "children": [] } ``` --- ### 6. Accent left-border row (callout style) ```json { "id": "callout-row", "type": "RowComponent", "config": { "fillWidth": true, "padding": "16px 20px", "backgroundColor": "#f0f9ff", "border": { "left": { "width": "4px", "style": "solid", "color": "#0ea5e9" } } }, "children": [] } ``` --- ### 7. Fixed-height banner row with background image ```json { "id": "banner-row", "type": "RowComponent", "config": { "height": "200px", "justifyContent": "center", "alignItems": "center", "backgroundColor": "#0f172a", "backgroundImage": { "src": "https://example.com/banner.jpg", "repeat": "no-repeat", "size": "cover", "position": "center center" } }, "children": [] } ``` --- ## Data Bindings `Row` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Bindings connect this component to the Data Layer for dynamic rendering. ```json { "id": "row-social-bindings", "type": "RowComponent", "bindings": { "dataList": "social_links", "itemAlias": "link", "visible": "user.showSocial === true", "propertyMap": { "config.backgroundColor": "link.brandColor" } }, "config": { "gap": "12px", "justifyContent": "center", "alignItems": "center" }, "children": [] } ``` | Property | Description | |---|---| | `dataList` | Dot-path to an array in the Data Layer. Makes `Row` a repeater — one row rendered per item. | | `itemAlias` | Name used by descendant components to reference the current iteration item (e.g. `"link"` → `"link.brandColor"`). | | `visible` | JS expression evaluated against the Data Layer. Hides the entire row when falsy. | | `propertyMap` | Maps `config` property paths to Data Layer paths (e.g. `"config.backgroundColor"` → `"link.brandColor"`). | --- ## Rules & Constraints - **`layoutColumns` array must match children count exactly.** If lengths differ, widths are silently not applied (undefined fallback). - **`layoutColumns` forces `table-layout: fixed` and `width: 100%`** on the content table, overriding `fillWidth`. You cannot have `layoutColumns` without a full-width content table. - **`gap` doubles as mobile spacer height** when `mobile.wrap: true`. A single value serves both orientations. - **`innerLink` is suppressed in `devMode`.** The row renders without the `` wrapper when dev mode is active. - **`borderRadius` clips backgrounds.** Setting `borderRadius` automatically applies `overflow: hidden` to the outer background ` `, clipping background colors and images within rounded corners. - **Per-side borders set all other sides to `"none"`** explicitly to prevent Outlook Classic from rendering phantom black borders. Do not rely on default/inherited border values when using per-side borders. - **`height` is propagated to all nested tables** via both the `height` CSS property and the HTML `height` attribute for Outlook Classic compatibility. - **`mobile.wrap` requires 2+ children** to have any effect. A single-child row is never stacked. --- SECTION: IMAGE --- **Image Component — LLM Reference** `Image` renders a responsive, email-client-compatible image with optional linking. It uses a table wrapper for maximum compatibility across email clients (including Outlook) and supports desktop/mobile overrides, data bindings, and Outlook-specific pixel constraints. --- ## Position in the Document Tree ``` DocumentTree └── Section └── Container └── Column └── Text └── Image ← can be linked or standalone └── Spacer └── Button ``` `Image` is a leaf node. It can be placed anywhere a child component is accepted (inside `Column`, `Row`, `Container`, etc.). --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "ImageComponent", "config": { "src": "https://example.com/image.jpg", "alt": "Alt text description", "width": "100%", "maxWidth": "600px" } } ``` --- ## `ImageConfig` — Full Property Reference | Property | Type | Required | Default | Description | |-----------------------|-------------------------------|----------|-------------|-----------| | `src` | `string` | Yes | — | Image source URL | | `alt` | `string` | Yes | — | Alt text (required for accessibility) | | `width` | `string` | No | "100%" | Desktop width (e.g. "100%", "300px") | | `height` | `string` | No | "auto" | Desktop height | | `maxWidth` | `string` | No | "100%" | Maximum width | | `maxHeight` | `string` | No | — | Maximum height | | `backgroundColor` | `string` | No | — | Background color of wrapper cell | | `padding` | `string` | No | — | Padding around image (CSS string) | | `borderRadius` | `string` | No | "0" | Border radius | | `border` | `BorderConfig` | No | — | Border configuration | | `innerLink` | `IInnerLink` | No | — | Preferred linking object | | `href` | `string` | No | — | Deprecated. Use `innerLink` instead | | `objectFit` | `"contain" \| "cover" \| ...` | No | — | CSS `object-fit` | | `objectPosition` | `string` | No | — | CSS `object-position` | | `outlookWidth` | `string` | No | — | Pixel width for Outlook Classic (no "px") | | `mobile` | `ImageMobileConfig` | No | — | Mobile-specific overrides | --- ## `innerLink` Structure ```json "innerLink": { "type": "url" | "email" | "phone" | "anchor" | "page_top" | "page_bottom" | "none", "url"?: string, "email"?: string, "phone"?: string, "anchor"?: string, "target"?: "_blank" | "_self" } ``` --- ## Mobile Overrides (`mobile`) Only explicitly set properties are overridden on mobile. Unspecified properties inherit desktop values. ```json "mobile": { "width": "100%", "maxWidth": "100%", "borderRadius": "0px", "hidden": false } ``` --- ## How It Works The component renders inside a `` for email compatibility. It includes: - Desktop styles + mobile media query (`@media (max-width: 768px)`) - Outlook Classic support via MSO conditional comments when `outlookWidth` is set - Automatic link wrapping when `innerLink` is provided - `display: block` on the `` to remove unwanted gaps - Unique class names for safe mobile CSS targeting --- ## React Usage ```tsx import Image, { ImageConfig } from './Image'; const config: ImageConfig = { src: "https://example.com/image.jpg", alt: "Product showcase", width: "100%", maxWidth: "600px" }; ``` The component is memoized via `arePropsEqual`. --- ## Common Patterns & Examples ### 1. Basic responsive image ```json { "id": "img_hero", "type": "ImageComponent", "config": { "src": "https://placehold.co/600x200?text=Hero+Banner&font=poppins", "alt": "Hero banner", "width": "100%", "maxWidth": "600px" } } ``` ### 2. Linked image ```json { "id": "cta_image", "type": "ImageComponent", "config": { "src": "https://placehold.co/600x80?text=Shop+Now&font=poppins", "alt": "Shop Now", "innerLink": { "type": "url", "url": "https://example.com/shop", "target": "_blank" }, "outlookWidth": "600" } } ``` ### 3. Mobile-optimized image ```json { "id": "product_img", "type": "ImageComponent", "config": { "src": "https://placehold.co/256x256?text=Product&font=poppins", "alt": "Product", "width": "280px", "mobile": { "width": "100%", "maxWidth": "100%" } } } ``` ### 4. Data-bound image (inside repeater) ```json { "id": "img-dynamic-bound", "type": "ImageComponent", "config": { "src": "https://placehold.co/256x256?text=Product&font=poppins", "alt": "Product name" }, "bindings": { "propertyMap": { "config.src": "item.image_url", "config.alt": "item.name" } } } ``` --- ## Data Bindings `Image` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Leaf components do not support `dataList` or `itemAlias` — use those on a parent `Container`, `Column`, or `Row` to repeat the image. `visible` and `propertyMap` are fully supported. ```json { "id": "dynamic-img", "type": "ImageComponent", "bindings": { "visible": "item.hasImage === true", "propertyMap": { "config.src": "item.imageUrl", "config.alt": "item.name" } }, "config": { "src": "", "alt": "", "width": "100%", "maxWidth": "600px" } } ``` | Property | Description | |---|---| | `visible` | JS expression evaluated against the Data Layer. Hides this component when falsy. | | `propertyMap` | Maps component property paths (prefixed with `config.`) to Data Layer paths. | > Bindable properties include `config.src`, `config.alt`, `config.width`, `config.maxWidth`, `config.backgroundColor`, and any other scalar `ImageConfig` field. `innerLink` itself cannot be bound via `propertyMap` — repeat the image inside a `Container` with `dataList` to vary links per item. --- ## Rules & Constraints - `src` and `alt` are **required**. - Prefer `innerLink` over the deprecated `href`/`target`. - Use `outlookWidth` (numeric string, e.g. `"600"`) when you need reliable fixed-width rendering in Outlook Classic. - `mobile` properties are **overrides only** — they do not reset desktop values unless explicitly set. - Always provide meaningful `alt` text. - For completely hidden images on mobile, use `mobile: { "hidden": true }`. - Non-pixel values in `width`/`height` are handled gracefully but `px` or `%` are recommended for predictability. - For image src in examples, use a real URL when one is available from the context. Otherwise, use a contextual placeholder URL (e.g. https://placehold.co/600x200?text=Hero+Banner&font=poppins) sized and labeled to match the use case. Never invent or guess image URLs. --- SECTION: ICON --- # Icon Component — LLM Reference `Icon` renders a dynamically generated icon using the Iconify API. It supports color, size, rotation, background, borders, and clickable links while maintaining excellent email client compatibility (including Outlook via VML). --- ## Position in the Document Tree ``` DocumentTree └── Section └── Container └── Column └── Text └── Icon ← inline or standalone icon └── Spacer └── Button ``` `Icon` is a leaf node. It can be placed anywhere a child component is accepted. --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "IconComponent", "config": { "iconIdentifier": "mdi:arrow-right", "height": "24", "width": "24", "color": "#000000" } } ``` --- ## `IconConfig` — Full Property Reference | Property | Type | Required | Description | |-----------------------|-------------------------------------------|----------|-------------| | `iconIdentifier` | `string` | Yes | Iconify icon name (e.g. `"mdi:home"`, `"logos:react"`) | | `height` | `string \| number` | Yes | Icon height in pixels | | `width` | `string \| number` | No | Icon width in pixels | | `rotate` | `number` | No | Rotation angle in degrees | | `rotateOrientation` | `"cw" \| "ccw"` | No | Rotation direction | | `color` | `string` | No | Icon color (hex recommended) | | `innerLink` | `IInnerLink` | No | Makes icon clickable | | `backgroundColor` | `string` | No | Background color of container | | `padding` | `string` | No | Padding around icon | | `borderRadius` | `string` | No | Border radius of container | | `border` | `BorderConfig` | No | Border configuration | | `justifyContent` | `"start" \| "center" \| "end"` | No | Horizontal alignment | --- ## `innerLink` Structure ```json "innerLink": { "type": "url" | "email" | "phone" | "anchor" | "page_top" | "page_bottom" | "none", "url"?: string, "email"?: string, "phone"?: string, "anchor"?: string, "target"?: "_blank" | "_self" } ``` --- ## How It Works - Icons are generated at runtime via the Iconify API as PNG images. - Uses a nested table structure for email compatibility. - When `backgroundColor` + `borderRadius` are used, VML (``) is injected for Outlook Classic support. - `display: block`, `fontSize: 0`, and `lineHeight: 0` are used to eliminate unwanted spacing. - Alignment is handled via the `align` attribute on the outer table. --- ## React Usage ```tsx import Icon, { IconConfig } from './Icon'; const config: IconConfig = { iconIdentifier: "mdi:check-circle", height: 32, width: 32, color: "#22c55e", justifyContent: "center" }; ``` The component is memoized via `arePropsEqual`. --- ## Common Patterns & Examples ### 1. Simple icon ```json { "id": "icon_check", "type": "IconComponent", "config": { "iconIdentifier": "mdi:check", "height": 24, "width": 24, "color": "#10b981" } } ``` ### 2. Clickable icon (linked) ```json { "id": "icon_link", "type": "IconComponent", "config": { "iconIdentifier": "mdi:arrow-right", "height": 20, "width": 20, "color": "#3b82f6", "innerLink": { "type": "url", "url": "https://example.com", "target": "_blank" } } } ``` ### 3. Icon with background and border radius ```json { "id": "icon_bg", "type": "IconComponent", "config": { "iconIdentifier": "mdi:star", "height": 28, "width": 28, "color": "#ffffff", "backgroundColor": "#eab308", "padding": "8px", "borderRadius": "9999px" } } ``` ### 4. Rotated icon ```json { "id": "icon_rotate", "type": "IconComponent", "config": { "iconIdentifier": "mdi:refresh", "height": 24, "width": 24, "rotate": 45, "color": "#64748b" } } ``` ### 5. Right-aligned icon ```json { "id": "icon_align", "type": "IconComponent", "config": { "iconIdentifier": "mdi:chevron-right", "height": 18, "width": 18, "color": "#94a3b8", "justifyContent": "end" } } ``` ### 6. Icon with height only (width follows height) ```json { "id": "icon_square", "type": "IconComponent", "config": { "iconIdentifier": "mdi:account", "height": 32, "color": "#ef4444" } } ``` --- ## Data Bindings `Icon` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Leaf components do not support `dataList` or `itemAlias` — use those on a parent `Container`, `Column`, or `Row` to repeat the component. `visible` and `propertyMap` are fully supported. ```json { "id": "dynamic-icon", "type": "IconComponent", "bindings": { "visible": "item.hasIcon === true", "propertyMap": { "config.iconIdentifier": "item.iconName", "config.color": "item.iconColor", "config.height": "item.iconSize" } }, "config": { "iconIdentifier": "mdi:check-circle", "height": 24, "color": "#10b981" } } ``` | Property | Description | |---|---| | `visible` | JS expression evaluated against the Data Layer. Hides this component when falsy. | | `propertyMap` | Maps component property paths (prefixed with `config.`) to Data Layer paths. | > Bindable properties include `config.iconIdentifier`, `config.color`, `config.backgroundColor`, `config.height`, `config.width`, and any other scalar `IconConfig` field. --- ## Rules & Constraints - `iconIdentifier` is **required** — without it the component renders nothing. - `height` is **required** — always specify the icon height explicitly. - Use full Iconify format: `"{collection}:{icon-name}"` (e.g. `mdi:home`, `logos:figma`, `ion:heart`). - Width and height must be numbers or pixel strings (e.g. `24` or `"24px"`). - When `width` is omitted, the icon renders as a square using the `height` value for both dimensions. - Hex colors (`#rrggbb`) are recommended for best compatibility. - `borderRadius` + `backgroundColor` together trigger VML for Outlook rounded backgrounds. - The icon is always rendered with `object-fit: contain`. - `alt` text is intentionally empty (`""`) as icons are decorative in most email use cases. --- SECTION: HTML --- **Html Component — LLM Reference** The `Html` component is the absolute root of the email document. It wraps the entire tree, provides the necessary XML namespaces for legacy Outlook (VML) support, sets the document language, and defines the global background color that fills the email client's viewport. --- ## Position in the Document Tree `Html` is the **root component**. It is the first tag in the generated output and contains exactly two primary children: the `Head` and the `Body`. ```tsx {/* Content */} ``` --- ## ComponentNode JSON Structure ```json { "id": "root_html", "type": "HtmlComponent", "config": { "backgroundColor": "#ffffff", "lang": "en" }, "children": [ { "id": "head_1", "type": "HeadComponent", "config": { ... } }, { "id": "body_1", "type": "BodyComponent", "config": { ... } } ] } ``` --- ## `HtmlConfig` — Full Property Reference | Property | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `backgroundColor` | `string` | No | `"#ffffff"` | The background color of the entire email client canvas (viewport). | | `lang` | `string` | No | `"en"` | Sets the `lang` and `xml:lang` attributes for accessibility. | | `children` | `ComponentNode[]` | Yes | — | Must contain a `Head` and a `Body` component. | --- ## How It Works * **Namespace Injection:** Automatically adds `xmlns:v` and `xmlns:o` to the `` tag. This is critical for rendering vector shapes (VML) and specific office-based fixes in Outlook 2003-2019. * **Legacy Backgrounds:** Uses the `bgcolor` attribute on the `` tag. While modern web dev uses CSS, many email clients (especially older Outlook versions) rely on the `bgcolor` attribute on the root to render the canvas color correctly. * **React Implementation:** Uses `React.createElement` internally to bypass JSX validation rules that occasionally flag colon-namespaced attributes (like `xmlns:v`). --- ## React Usage ```tsx import Html from './Html'; import Head from './Head'; import Body from './Body'; {/* Email Rows */} ``` --- ## Common Patterns & Examples ### 1. Minimal Root Structure The standard entry point for every email generated by the builder. ```json { "id": "email_root", "type": "HtmlComponent", "config": { "backgroundColor": "#ffffff" }, "children": [ { "type": "HeadComponent", "id": "h", "config": {} }, { "type": "BodyComponent", "id": "b", "config": {} } ] } ``` ### 2. Dark Mode Preview Background Setting a dark global background for high-contrast or themed templates. ```json { "id": "email_root_dark", "type": "HtmlComponent", "config": { "backgroundColor": "#1a1a1a", "lang": "en" }, "children": [...] } ``` --- ## Rules & Constraints * **Strict Hierarchy:** An `Html` node must be the top-most node in the JSON `DocumentTree`. * **Required Children:** It should always contain exactly one `Head` and one `Body`. * **Accessibility:** Always ensure the `lang` property matches the primary language of the email content for screen reader compatibility. * **Background Sync:** For the best visual experience, the `backgroundColor` of the `Html` component should either match the `Body` background or be a complementary "outer" color (e.g., a light gray `Html` background with a white `Body` container). --- SECTION: HEADING --- # Heading Component — LLM Reference `Heading` renders a semantic HTML heading (`
` to `
`) with full text styling support. It is optimized for email clients with a table wrapper for reliable padding, background, and alignment. --- ## Position in the Document Tree ``` DocumentTree └── Section └── Container └── Column └── Heading ← semantic heading (h1–h6) └── Spacer └── Text ``` `Heading` is a leaf node. It can be placed anywhere a child component is accepted. --- ## ComponentNode JSON Structure ```json { "id": "unique-string-id", "type": "HeadingComponent", "config": { "text": "Welcome to our newsletter", "level": "h1", "color": "#1f2937", "fontSize": "32px" } } ``` --- ## `HeadingConfig` — Full Property Reference | Property | Type | Required | Default | Description | |--------------------|-----------------------------------|----------|-----------|-------------| | `text` | `string` (HTML) | No | — | Heading content. See HTML restrictions below. | | `level` | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"` | No | `"h1"` | Semantic HTML heading level | | `padding` | `string` | No | — | Padding around the heading (e.g. `"20px 0"`) | | `color` | `string` | No | — | Text color (hex recommended) | | `textAlign` | `"left" \| "center" \| "right" \| "justify"` | No | — | Horizontal alignment | | `fontFamily` | `string` | No | — | Font family stack | | `fontSize` | `string` | No | — | Font size (e.g. `"28px"`) | | `fontWeight` | `string` | No | — | Font weight (`"400"`, `"700"`, `"bold"`, etc.) | | `fontStyle` | `string` | No | — | `"italic"` or `"normal"` | | `lineHeight` | `string` | No | — | Line height (e.g. `"1.3"` or `"34px"`) | | `letterSpacing` | `string` | No | — | Letter spacing (e.g. `"0.5px"`) | | `textTransform` | `string` | No | — | `"uppercase"`, `"capitalize"`, etc. | | `textDecoration` | `string` | No | — | `"underline"`, `"line-through"` | | `backgroundColor` | `string` | No | — | Background color of the block | | `verticalAlign` | `string` | No | `"top"` | Vertical alignment in the cell | | `wordBreak` | `string` | No | — | Word break behavior | | `whiteSpace` | `string` | No | — | White space handling | --- ## HTML Restrictions for `text` Property The `text` property accepts a limited subset of HTML to ensure consistent rendering across email clients and proper inheritance of parent styles. ### Allowed HTML Elements | Element | Restriction | |---------|-------------| | `` | Only allowed inline element. Must use inline `style` attributes for styling. | | `` | For links only. Use `href` attribute. See Link Style Injection below. | ### Forbidden HTML Elements The following elements are **NOT** supported and should be avoided: - ``, `` — use `` instead - ``, `` — use `` instead - `` — use `` instead - `
`-`
` (nesting headings) - `
`, `
`, `
` - Any block-level elements ### Allowed Inline CSS Properties Within `` and `` tags, only these CSS properties are supported: | Property | Example | |----------|---------| | `font-weight` | `font-weight: 700` | | `font-style` | `font-style: italic` | | `text-decoration` | `text-decoration: underline` | | `color` | `color: #ff0000` | ### Correct Examples ```html Important announcement Bold and italic Click here ``` ### Incorrect Examples ```html Text Text Text
Text

Text
``` --- ## Link Style Injection (`injectLinkStyles`) The `Heading` component uses `injectLinkStyles` to automatically manage link styles. Understanding how it works is critical for correct AI-generated content. ### What `injectLinkStyles` Does When `config.text` contains HTML, the component runs the string through `injectLinkStyles`, which: 1. Parses the HTML and finds all `` tags 2. For each `` tag, examines its existing inline `style` attributes 3. **Conditionally injects** missing styles for `color` and `text-decoration` only when: - The property is **not already defined** on the `` tag's inline style, AND - The property is **not inheriting** a valid value from parent elements ### The Algorithm (Simplified) For each `` tag, `injectLinkStyles` checks two properties: `color` and `text-decoration`. **For each property:** - If the `` tag already has this property defined in its inline `style` attribute → **DO NOTHING** (keep the manual value) - If the `` tag does NOT have this property defined: - Try to inherit from parent elements (like a surrounding ``) - If no inherited value exists, use the `fallback` from the heading's config - If no fallback exists for `text-decoration`, default to `"none"` **Key takeaway:** Manual inline styles on `` tags are **never overwritten**. They always take precedence. ### Link Style Resolution Examples **Example 1: No manual styles on ``** ```html Click here ``` Result: Receives `color` and `text-decoration` from heading config (fallback). If heading has `color: "#3b82f6"` and `textDecoration: "underline"`, the link gets those. **Example 2: Manual `color` only** ```html Click here ``` Result: - `color: #ff0000` → **preserved** (manual wins) - `text-decoration` → injected from heading config (or defaults to `"none"`) **Example 3: Manual `text-decoration` only** ```html Click here ``` Result: - `text-decoration: none` → **preserved** (manual wins) - `color` → injected from heading config **Example 4: Both properties manually defined** ```html Click here ``` Result: Both properties preserved. Nothing is injected. Your manual styles win completely. **Example 5: Inherited from parent ``** ```html Click here ``` Result: - No manual styles on `` - `color` is inherited from the parent `` → `#00ff00` is used - `text-decoration` injected from heading config (or defaults to `"none"`) ### Summary: What `injectLinkStyles` Does NOT Do - ❌ It does **NOT** remove or override any existing inline styles on `` tags - ❌ It does **NOT** prevent you from adding any supported style property to `` tags - ❌ It does **NOT** restrict what colors, decorations, or weights you can apply to links - ❌ It does **NOT** inject styles for properties already defined on the `` tag ### Best Practices for AI-Generated Content **✅ You can safely add any supported inline style to `` tags** — they will never be stripped or overridden: ```html Custom styled link ``` **✅ You can rely on automatic injection** — if you don't specify styles, the component ensures links look consistent with your heading: ```html Link that inherits heading styles ``` **✅ You can mix both approaches** — let the component handle some properties while manually controlling others: ```html Bold link that inherits color from heading ``` --- ## How It Works - Renders inside a `
` → `
` wrapper for consistent padding, background, and width control across email clients. - Default browser margins on heading tags are reset (`margin: 0`). - Only supports `` and `` inline tags within the `text` property. - `injectLinkStyles` processes all `` tags to apply missing `color` and `text-decoration` styles only when not manually defined. - Uses inline styles for maximum email client compatibility. - `msoLineHeightRule: exactly` is applied for better Outlook rendering. --- ## React Usage ```tsx import Heading, { HeadingConfig } from './Heading'; const config: HeadingConfig = { text: 'Our Latest Updates', level: "h2", fontSize: "28px", color: "#111827", textAlign: "center" }; ``` The component is memoized via `arePropsEqual`. --- ## Common Patterns & Examples ### 1. Main hero heading with bold span ```json { "id": "hero_heading", "type": "HeadingComponent", "config": { "text": "Summer Sale is Here!", "level": "h1", "fontSize": "36px", "color": "#1f2937", "textAlign": "center", "padding": "20px 0 12px 0" } } ``` ### 2. Section heading with italic emphasis ```json { "id": "section_title", "type": "HeadingComponent", "config": { "text": "Featured Products", "level": "h2", "fontSize": "24px", "fontWeight": "700", "color": "#374151", "padding": "32px 0 16px 0" } } ``` ### 3. Centered heading with colored span ```json { "id": "bg_heading", "type": "HeadingComponent", "config": { "text": "Special Offer", "level": "h3", "fontSize": "22px", "color": "#ffffff", "backgroundColor": "#3b82f6", "textAlign": "center", "padding": "16px 0", "fontWeight": "600" } } ``` ### 4. Link with automatic style injection (no manual styles) ```json { "id": "auto_link_heading", "type": "HeadingComponent", "config": { "text": "Visit our website for details", "level": "h2", "fontSize": "28px", "color": "#3b82f6", "textDecoration": "underline", "textAlign": "center" } } ``` The link automatically receives `color: #3b82f6` and `text-decoration: underline` because no manual styles were provided. ### 5. Link with manual style override ```json { "id": "manual_link_heading", "type": "HeadingComponent", "config": { "text": "Special offer ends soon", "level": "h2", "fontSize": "28px", "color": "#3b82f6", "textDecoration": "none", "textAlign": "center" } } ``` The link keeps `color: #ff0000` and `font-weight: 800` (manual wins). `text-decoration` is NOT injected because heading has `textDecoration: "none"` which becomes the fallback, but manual styles take precedence for color and weight. ### 6. Link inheriting from parent span ```json { "id": "inherited_link_heading", "type": "HeadingComponent", "config": { "text": "Check this deal", "level": "h3", "fontSize": "20px", "color": "#3b82f6", "textDecoration": "underline" } } ``` The link inherits `color: #00aa00` from the parent ``. `text-decoration: underline` is injected from the heading config since the link has no manual decoration. ### 7. Combined span styles on link ```json { "id": "styled_link_heading", "type": "HeadingComponent", "config": { "text": "Click now", "level": "h2", "fontSize": "28px", "color": "#ffffff", "textDecoration": "none", "backgroundColor": "#000000", "padding": "16px 0", "textAlign": "center" } } ``` The link receives `color: #ffffff` and `text-decoration: none` from injection. The inner `` adds `font-weight: 700` and `font-style: italic` on top. ### 8. Heading with innerLink (whole block clickable) ```json { "id": "clickable_heading", "type": "HeadingComponent", "config": { "text": "Shop the Collection", "level": "h2", "fontSize": "32px", "color": "#ffffff", "backgroundColor": "#000000", "textAlign": "center", "padding": "24px 0", "innerLink": { "type": "url", "url": "https://example.com/shop", "target": "_blank" } } } ``` When `innerLink` is provided, the entire heading block becomes a clickable link. `injectLinkStyles` is not involved here — the link wrapper is applied at the table level. --- ## Data Bindings `Heading` supports the `bindings` property on the `ComponentNode`, alongside `id`, `type`, and `config`. Leaf components do not support `dataList` or `itemAlias` — use those on a parent `Container`, `Column`, or `Row` to repeat the component. `visible` and `propertyMap` are fully supported. ```json { "id": "dynamic-heading", "type": "HeadingComponent", "bindings": { "visible": "section.showTitle === true", "propertyMap": { "config.text": "section.title", "config.color": "section.titleColor" } }, "config": { "text": "Fallback Heading", "level": "h2", "fontSize": "28px", "color": "#1f2937" } } ``` | Property | Description | |---|---| | `visible` | JS expression evaluated against the Data Layer. Hides this component when falsy. | | `propertyMap` | Maps component property paths (prefixed with `config.`) to Data Layer paths. | > Bindable properties include `config.text`, `config.color`, `config.backgroundColor`, `config.fontSize`, `config.fontFamily`, `config.padding`, and any other scalar `HeadingConfig` field. --- ## Rules & Constraints - **Only `` and `` tags are allowed** in the `text` property. - **Use inline styles** (`style="font-weight: 700;"`) instead of semantic HTML tags like ``, ``, ``, ``, ``. - **Manual inline styles on `` tags are never removed or overridden** — `injectLinkStyles` only adds missing `color` and `text-decoration` properties. - **You can add any supported style property to `` tags** (`color`, `text-decoration`, `font-weight`, `font-style`). - Supported inline style properties on `` and ``: `font-weight`, `font-style`, `text-decoration`, `color`. - The `level` should always be specified for semantic correctness. - Always define `fontSize` explicitly — do not rely on default browser sizes for headings in email. - `padding` and `backgroundColor` are applied to the wrapping table cell. - Default top/bottom margins are removed — use `padding` for spacing control. - For complex HTML content requiring multiple block elements, consider using the `Text` component instead. --- ## Quick Reference Card | Do ✅ | Don't ❌ | |------|---------| | `text` | `text` | | `text` | `text` | | `text` | `text` | | `text` | `text` | | `link` (manual color) | Worrying that manual styles will be stripped | | `link` (relies on injection) | Adding unsupported CSS properties | | Combine spans: `` | Nest spans unnecessarily | | Let `injectLinkStyles` fill missing `color` and `text-decoration` | Assuming injection overrides your manual styles | --- ## Technical Reference: `injectLinkStyles` Behavior For implementers and advanced users, here is the exact behavior of `injectLinkStyles`: ```typescript // Properties that injectLinkStyles manages const BROWSER_LINK_DEFAULTS = ["color", "text-decoration"]; // Resolution logic for each anchor: // 1. If property exists in anchor's inline style → preserve it (skip injection) // 2. Else if property can be inherited from parent elements → use inherited value // 3. Else if fallback exists from heading config → use fallback // 4. Else if property === "text-decoration" → default to "none" // 5. Else → leave undefined (property not added) ``` **This means:** - Your manual `color` and `text-decoration` are **sacred** — never touched - Only links missing these properties receive automatic values - Inheritance from parent `` elements is respected - The heading's `color` and `textDecoration` act as fallbacks, not overrides --- SECTION: HEAD --- **Head Component — LLM Reference** `Head` generates the `` section of the email document. It includes essential meta tags, global CSS resets, mobile responsiveness rules, Outlook fixes, and font declarations. --- ## Position in the Document Tree `Head` is a **top-level** component and must be placed directly inside the email root (not in the body). ```tsx {/* Fonts + custom styles */}
{/* Content */}
``` --- ## ComponentNode JSON Structure ```json { "id": "head_root", "type": "HeadComponent", "config": { "title": "Monthly Newsletter", "backgroundColor": "#ffffff", "rowGaps": ["8px", "16px", "32px", "48px"] } } ``` --- ## `HeadConfig` — Full Property Reference | Property | Type | Required | Default | Description | |--------------------|-----------------------|----------|----------------------|-----------| | `title` | `string` | No | `"Email Preview"` | Email subject / browser title | | `backgroundColor` | `string` | No | `"#ffffff"` | Global email background color | | `rowGaps` | `string[]` | No | `[]` | Gap values used for mobile responsive spacing | | `fonts` | `ResolvedFont[]` | No | `[]` | Auto-resolved fonts (from builder pipeline) | | `children` | `ReactNode` | No | — | Additional custom `

` through `

Welcome back, Alex

`–`

Our latest products

` to `

`-`