# Section Component — LLM Reference

`Section` is the **top-level structural wrapper** for an email. It renders as a full-width `<table>` 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 `<td>` 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 `<table>` 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',
};

<Section config={config}>
  <Container config={containerConfig}>
    <Text config={textConfig} />
  </Container>
</Section>
```

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 `<td>` 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 `<table>`.** 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.