@hyper-elements/react 0.0.0-stage → 0.3.0

package/GUIDE.md

@@ -0,0 +1,176 @@
+# Writing templates with the new components (`@hyper-elements/react`)
+
+<!-- Written from the component definitions by src/primitives/reference.ts: don't edit by hand. Regenerate with UPDATE_REFERENCE=1 pnpm --filter @hyper-elements/react test reference -->
+
+Everything needed to write a template, in short. Every prop's and style's details: [REFERENCE.md](./REFERENCE.md).
+
+## How a template is written
+
+- Import from `@hyper-elements/react`. A template has one root: `Email`, `Page`, `Document` or `Canvas`.
+- Styles go in `style={{ … }}`, never as props: `<Heading style={{ fontSize: 24, color: "#111827" }}>`. A number is px; `padding` takes `16`, `[12, 24]` or `"12px 24px"`. A box's text styles are inherited by what it holds.
+- There are no margins: space between blocks is their parent's `gap` (`<Column style={{ gap: 16 }}>`), space inside a box its `padding`.
+- A root, a `Section` and a `Column` stack their children. A `Row` puts its children side by side (each `Column` at its `style.width`, or an equal share) and stacks them on phones. `Grid columns={3}` makes rows of three. A `Section` is a band whose background spans the window; a `Column` with a background is a card.
+- Text is components, not HTML: `Heading level={1}` and `Text` hold text; inside them `Span` styles a run, `Link href` links one, `LineBreak` breaks the line and `MergeTag name` writes a merge tag. No raw HTML (`<b>`, `<br>`, `<div>`) and no `html` prop.
+- `Image src={{ src, width, height }}` (the file's size in px) with `alt`; `style.width` sets the size shown.
+- Lists: `<List type="number">` of `ListItem`s. Tables: a `Table` of `TableRow`s (`header` on the first) of `TableCell`s, with `cellPadding` and `rowBorder` in the Table's `style`.
+- Phones: `mobile={{ fontSize: 20 }}` (the styles listed under "Phones"), `hidden={{ mobile: true }}`. Hover: `hover={{ backgroundColor: "#374151" }}` (those under "Hover").
+- `await render(element)` gives `{ html, text, diagnostics }`; a template with errors throws an `ElementsError` whose `diagnostics` give each problem's `code`, `message` and `path`. `validate(element)` runs the same checks without rendering. `outline(element)` prints the laid-out template (each block, its width, its text), to check the layout without reading the HTML.
+
+## Common mistakes
+
+Each of these made an agent's first try fail:
+
+- `<Email backgroundColor="#fff">` → `<Email style={{ backgroundColor: "#fff" }}>`. Styles never go as props.
+- `<Email style={{ width: 600, padding: 24 }}>` → `<Email width={600}>`, with the padding on a `Column` (a card) or a `Section` (a band) inside it. A root's width is a prop, and a root has no padding.
+- `items={[{ text: "Home", link: "/" }]}` → `items={[{ text: "Home", href: "/" }]}`. A `Menu`'s items are `{ text, href }`, a `Social`'s icons `{ name, href }`.
+- `style={{ marginBottom: 16 }}` → `gap: 16` on the parent. There are no margins.
+- `ColumnLayouts`, `layout`, `headingType`, `altText`, `html` are Unlayer Elements' props, not these: a `Row` of `Column`s, `level`, `alt`, and text as children.
+- `<Image src="https://example.com/logo.png">` → `src={{ src: "https://example.com/logo.png", width: 240, height: 80 }}`, the file's size. Without it Outlook shows the image at its file's size, and Hyper Elements warns.
+
+## A whole template
+
+```tsx
+import { Button, Column, Email, Heading, Image, Link, List, ListItem, MergeTag, Text, Row, Span, Table, TableCell, TableRow } from "@hyper-elements/react";
+
+export default function Receipt() {
+  return (
+    <Email previewText="Your Acme receipt" style={{ backgroundColor: "#f4f4f5", fontFamily: "Inter, Arial, sans-serif", gap: 16 }}>
+      <Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
+      <Column style={{ backgroundColor: "#ffffff", padding: 32, gap: 16, borderRadius: 8 }}>
+        <Heading level={1} style={{ fontSize: 24 }} mobile={{ fontSize: 20 }}>
+          Thanks for your order, <MergeTag name="first_name" />
+        </Heading>
+        <Text>
+          Order <Span style={{ fontWeight: 700 }}>#10482</Span> ships tomorrow. <Link href="https://example.com/orders/10482">Track it</Link>.
+        </Text>
+        <Table style={{ cellPadding: [8, 0], rowBorder: "1px solid #e4e4e7" }}>
+          <TableRow header>
+            <TableCell>Item</TableCell>
+            <TableCell style={{ textAlign: "right" }}>Price</TableCell>
+          </TableRow>
+          <TableRow>
+            <TableCell>Linen shirt</TableCell>
+            <TableCell style={{ textAlign: "right" }}>$48.00</TableCell>
+          </TableRow>
+        </Table>
+        <Row style={{ gap: 16 }}>
+          <Column>
+            <Text style={{ fontWeight: 700 }}>Shipping to</Text>
+            <Text>Ada Lovelace, London</Text>
+          </Column>
+          <Column>
+            <Text style={{ fontWeight: 700 }}>Next steps</Text>
+            <List type="number">
+              <ListItem>We pack it</ListItem>
+              <ListItem>You track it</ListItem>
+            </List>
+          </Column>
+        </Row>
+        <Button href="https://example.com/orders/10482" style={{ backgroundColor: "#111827", borderRadius: 6 }} hover={{ backgroundColor: "#374151" }}>
+          View your order
+        </Button>
+      </Column>
+      <Text style={{ fontSize: 12, color: "#71717a", textAlign: "center" }}>Acme Inc., 1 Market St, San Francisco</Text>
+    </Email>
+  );
+}
+```
+
+## A Canvas as an image
+
+`renderImage(element, options)` (`@hyper-elements/react/image`) writes a `Canvas` as a PNG (`format: "svg"` an SVG, `scale: 2` twice the pixels). Nothing is fetched: `fonts` gives each font file by the family the template names (TTF, OTF or WOFF, not WOFF2; one per weight and style used), `images` each image file by the `src` the template gives. It gives `{ image, width, height, diagnostics }` (what it drew otherwise than written: a weight not given, a hover); errors throw an `ElementsError`.
+
+```tsx
+import { readFile } from "node:fs/promises";
+import { Canvas, Heading, Image } from "@hyper-elements/react";
+import { renderImage } from "@hyper-elements/react/image";
+
+const { image, diagnostics } = await renderImage(
+  <Canvas width={1200} height={630} style={{ padding: 64, gap: 24, fontFamily: "Inter", textAlign: "center", justifyContent: "center" }}>
+    <Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
+    <Heading level={1} style={{ fontSize: 64 }}>Launch week</Heading>
+  </Canvas>,
+  {
+    fonts: [{ family: "Inter", src: await readFile("Inter-Bold.ttf"), weight: 700 }],
+    images: { "https://example.com/logo.png": await readFile("logo.png") },
+  }
+);
+```
+
+## Components
+
+\* required. *text* styles: color, fontFamily, fontSize, fontWeight, fontStyle, lineHeight, letterSpacing, textAlign, textTransform. *box* styles: width, maxWidth, padding, backgroundColor, border, borderRadius.
+
+### Roots
+
+- **Email**: An email. Its children are stacked down the content width, centered in the window. Holds sections, layout, blocks. Props: width (a length (a number of px)), previewText (text), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch). Phones: fontSize, lineHeight, letterSpacing, textAlign, gap.
+- **Page**: A web page. Its children are stacked down the content width, centered in the window. Holds sections, layout, blocks. Props: width (a length (a number of px)), description (text), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch). Phones: fontSize, lineHeight, letterSpacing, textAlign, gap.
+- **Document**: A printed document: its children on pages of its size (Document.Page, or split by PageBreaks), a PageHeader and a PageFooter on each. Renders to print HTML, and to PDF with @hyper-elements/react/pdf. Holds sections, layout, blocks, Document.Page, PageBreak, PageHeader, PageFooter. Props: size (A3|A4|A5|Letter|Legal|Tabloid), orientation (portrait|landscape), margin (insets), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch). Phones: fontSize, lineHeight, letterSpacing, textAlign, gap.
+- **Canvas**: An image of a fixed size (a social card, a banner): its children laid out in it as on a page. Written as PNG or SVG with @hyper-elements/react/image. Holds sections, layout, blocks. Props: width (a length (a number of px)), height (a length (a number of px)), title (text), lang (text), dir (ltr|rtl|auto), fonts (fontFaces). Style: text, backgroundColor, gap, alignItems (start|center|end|stretch), padding, justifyContent (start|center|end|space-between). Phones: fontSize, lineHeight, letterSpacing, textAlign, gap, padding.
+
+### Sections and layout
+
+- **Section**: A band across the whole window, directly in an Email or Page: its background spans the window, its children are stacked at the content width. Holds layout, blocks. Style: text, backgroundColor, padding, border, gap, alignItems (start|center|end|stretch). Phones: fontSize, lineHeight, letterSpacing, textAlign, padding, border, gap.
+- **Row**: Lays its children out side by side. A child takes its width, or a share of what's left (its flex, 1 by default). Holds layout, blocks. Props: stackOnMobile (true or false), dir (ltr|rtl|auto). Style: text, box, minWidth, height, overflow (visible|hidden), gap, alignItems (start|center|end|stretch), justifyContent (start|center|end|space-between), flexWrap (nowrap|wrap|words), flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, padding, border, gap.
+- **Column**: Stacks its children vertically, with its own spacing and box. Holds layout, blocks. Style: text, box, minWidth, height, overflow (visible|hidden), gap, alignItems (start|center|end|stretch), justifyContent (start|center|end|space-between), flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, padding, border, gap.
+- **Grid**: Its children in columns of equal width, row after row; on phones, one under another. Holds layout, blocks. Props: columns (an integer from 1 to 12), stackOnMobile (true or false). Style: text, box, minWidth, height, overflow (visible|hidden), gap, rowGap, alignItems (start|center|end|stretch), flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, padding, border, gap, rowGap.
+- **Layer**: Its children over each other, in one box as tall as the tallest: an image with words on it. In an email, an Image with one child over it. Holds layout, blocks. Style: text, width, minWidth, maxWidth, backgroundColor, border, borderRadius, height, alignItems (start|center|end|stretch), justifyItems (start|center|end|stretch), flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, border.
+
+### Blocks
+
+- **Svg**: Shapes (Rect, Circle, Ellipse, Line, Polygon, Path) drawn in a box of its own: its width and height, and the coordinates its viewBox gives them. Holds shapes. Props: width* (a number from 0), height* (a number from 0), viewBox (text), title (text). Style: padding, backgroundColor, border, borderRadius, flex. Phones: padding, border.
+- **Text**: A paragraph of text. Holds text, inline, Image. Props: dir (ltr|rtl|auto). Style: text, box, textDecoration (none|underline|line-through), flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, padding, border.
+- **Heading**: A heading, from level 1 (the page's title) to 6. Holds text, inline. Props: level (1|2|3|4|5|6), dir (ltr|rtl|auto). Style: text, box, textDecoration (none|underline|line-through), flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, padding, border.
+- **Button**: A link drawn as a button. Holds text, Span, MergeTag, LineBreak. Props: href* (link), title (text), aria-label (text), attrs (attributes). Style: text, box, textDecoration (none|underline|line-through), boxSizing (border-box|content-box), alignSelf (start|center|end), flex. Hover: color, backgroundColor. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, padding, border, alignSelf.
+- **Image**: An image in the content. Without a width it takes its own size, no wider than its parent. Props: src* (asset), alt (text), title (text). Style: width, maxWidth, height, border, borderRadius, flex, alignSelf (start|center|end), verticalAlign (top|middle). Phones: width, maxWidth, border, alignSelf.
+- **Divider**: A horizontal line. Style: borderTop, width, padding. Phones: width, padding.
+- **List**: A bulleted or numbered list of ListItems. Its markers sit in a column of their own (indent) before the items. Holds ListItem. Props: type (bullet|number), start (an integer from 0). Style: text, width, maxWidth, padding, backgroundColor, border, gap, indent, flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, padding, border, gap.
+- **Table**: A table of data: TableRows of TableCells. Columns take their cells' widths; the rest share what's left. Holds TableRow. Style: text, width, maxWidth, backgroundColor, border, cellPadding, rowBorder, borderCollapse (separate|collapse), flex. Phones: fontSize, lineHeight, letterSpacing, textAlign, width, maxWidth, border.
+- **Video**: A YouTube or Vimeo video: its player on a page; in an email (which can't play one), its thumbnail, linked to it. Props: src* (video), thumbnail (asset), title (text). Style: width, maxWidth, flex. Phones: width, maxWidth.
+- **Social**: Links to social profiles: a line of the networks' icons, each linked to its profile. Props: icons* (a list of icons, each { name, href }), iconType (circle|rounded|squared), size (an integer from 1). Style: gap, justifyContent (start|center|end), flex. Phones: gap.
+- **Menu**: A line of links (a site's sections, a footer's), onto more lines where they don't fit, with a separator between them on desktop; or links down a column. Props: items* (a list of items, each { text, href }), separator (text), layout (horizontal|vertical). Style: color, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textTransform (none|uppercase|lowercase|capitalize), separatorColor, padding, justifyContent (start|center|end), flex. Phones: fontSize, lineHeight, letterSpacing.
+- **Html**: Markup written as it is, for what no component says (the builder's HTML block): in an email and on a page as given, nothing in it checked or escaped. A Document's PDF and a Canvas's image draw its plain text. Props: html* (text), text (text).
+
+### Inline
+
+- **PageNumber**: In a Document's text: the number of the page it's on, or (total) how many pages there are. Props: total (true or false).
+- **Span**: Styled text inside text; raised or lowered (superscript, subscript) with verticalAlign. Holds text, inline. Style: color, fontFamily, fontSize, fontWeight, fontStyle (normal|italic), letterSpacing, textTransform (none|uppercase|lowercase|capitalize), textDecoration (none|underline|line-through), backgroundColor, verticalAlign (baseline|super|sub). Phones: fontSize, letterSpacing.
+- **Link**: A link: text inside text, or around an Image. Holds text, inline, Image. Props: href* (link), title (text), aria-label (text), attrs (attributes). Style: color, fontFamily, fontSize, fontWeight, fontStyle (normal|italic), letterSpacing, textTransform (none|uppercase|lowercase|capitalize), textDecoration (none|underline|line-through), backgroundColor, flex. Hover: color, textDecoration, backgroundColor. Phones: fontSize, letterSpacing.
+- **LineBreak**: Starts a new line inside text.
+- **MergeTag**: A value the sending service fills in (a name, a link), written in the service's own syntax. Props: name* (text).
+
+### Parts
+
+- **Document.Page**: One page of a Document (Document.Page in JSX): its children stacked down it, inside the Document's margins. Holds sections, layout, blocks. Style: text, backgroundColor, gap, alignItems (start|center|end|stretch). Phones: fontSize, lineHeight, letterSpacing, textAlign, gap.
+- **PageBreak**: In a Document, where a page ends: what follows starts the next page.
+- **PageHeader**: In a Document: drawn at the top of every page, inside its margins. Holds layout, blocks. Style: text, padding, backgroundColor, border, gap, alignItems (start|center|end|stretch). Phones: fontSize, lineHeight, letterSpacing, textAlign, padding, border, gap.
+- **PageFooter**: In a Document: drawn at the bottom of every page, inside its margins. Holds layout, blocks. Style: text, padding, backgroundColor, border, gap, alignItems (start|center|end|stretch). Phones: fontSize, lineHeight, letterSpacing, textAlign, padding, border, gap.
+- **ListItem**: An item of a List: text, and a List of its own to nest one. Holds text, inline, List. Props: dir (ltr|rtl|auto). Style: text, textDecoration (none|underline|line-through). Phones: fontSize, lineHeight, letterSpacing, textAlign.
+- **TableRow**: A row of a Table. A header row's cells are header cells, in bold. Holds TableCell. Props: header (true or false), footer (true or false). Style: text, backgroundColor, height. Phones: fontSize, lineHeight, letterSpacing, textAlign.
+- **TableCell**: A cell of a TableRow: text, and images. Its width sets its column's. Holds text, inline, Image. Props: colSpan (an integer from 1), dir (ltr|rtl|auto). Style: text, textDecoration (none|underline|line-through), padding, backgroundColor, border, width, verticalAlign (top|middle|bottom). Phones: fontSize, lineHeight, letterSpacing, textAlign, padding, border.
+
+### Shapes
+
+- **Rect**: A rectangle at x, y in its Svg, rounded by rx. Props: x (a number), y (a number), width* (a number from 0), height* (a number from 0), rx (a number from 0). Style: fill, stroke, strokeWidth, opacity.
+- **Circle**: A circle centered at cx, cy in its Svg. Props: cx (a number), cy (a number), r* (a number from 0). Style: fill, stroke, strokeWidth, opacity.
+- **Ellipse**: An ellipse centered at cx, cy in its Svg. Props: cx (a number), cy (a number), rx* (a number from 0), ry* (a number from 0). Style: fill, stroke, strokeWidth, opacity.
+- **Line**: A straight line from x1, y1 to x2, y2 in its Svg (drawn by its stroke). Props: x1 (a number), y1 (a number), x2 (a number), y2 (a number). Style: fill, stroke, strokeWidth, opacity.
+- **Polygon**: A closed shape through its points ("0,0 40,0 20,30"), in its Svg. Props: points* (text). Style: fill, stroke, strokeWidth, opacity.
+- **Path**: A shape drawn by an SVG path (d), in its Svg. Props: d* (text). Style: fill, stroke, strokeWidth, opacity.
+
+## Values
+
+- *fontFaces*: a list of { family, src, format, weight, style }
+- *color*: a color ("#0879a1", "rgb(…)", "rgba(…)" or a CSS name)
+- *fontFamily*: a font stack, as CSS writes it ("Inter, Arial, sans-serif")
+- *fontWeight*: 100 to 900 in hundreds, "normal" or "bold"
+- *lineHeight*: a multiple of the font size (1.5), a percentage ("150%"), px ("24px") or "normal" (the font's own)
+- *insets*: px for all sides, "8px 16px" (1 to 4 values), [v, h] or [t, r, b, l], or { top, right, bottom, left }
+- *border*: "1px solid #ccc", { width, style, color } for all sides, or { top, right, bottom, left } with one of those each
+- *radius*: px for every corner, [topLeft, topRight, bottomRight, bottomLeft], or { topLeft, topRight, bottomRight, bottomLeft }
+- *flex*: a share of the free width (0 or more), or "none"
+- *link*: a URL (http, https, mailto, tel, a path, or a merge tag) or { href, target }
+- *attributes*: attributes by name, each a text value (no on… handlers, href or style)
+- *asset*: an image URL (http, https or a data:image URI), or { src, width, height }
+- *line*: "1px solid #ccc" or { width, style, color }
+- *video*: a YouTube or Vimeo video's https link

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Unlayer, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,372 @@
-# Temporary Holding Version
+# @hyper-elements/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components for transactional emails, email templates, landing pages, invoices, reports and documents. One template renders to email-safe HTML, a responsive web page, print-ready HTML, a PDF or an image, on your own server, with no network calls.
+
+## Installation
+
+```bash
+npm install @hyper-elements/react
+# or
+pnpm add @hyper-elements/react
+```
+
+## Quick start
+
+Import from `@hyper-elements/react`. A template has one root, its styles go in `style={{ }}`, and the space between blocks is their parent's `gap`.
+
+```tsx
+import { Button, Column, Email, Heading, Image, Link, List, ListItem, MergeTag, Text, Row, Span, Table, TableCell, TableRow } from "@hyper-elements/react";
+
+export default function Receipt() {
+  return (
+    <Email previewText="Your Acme receipt" style={{ backgroundColor: "#f4f4f5", fontFamily: "Inter, Arial, sans-serif", gap: 16 }}>
+      <Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Acme" style={{ width: 120 }} />
+      <Column style={{ backgroundColor: "#ffffff", padding: 32, gap: 16, borderRadius: 8 }}>
+        <Heading level={1} style={{ fontSize: 24 }} mobile={{ fontSize: 20 }}>
+          Thanks for your order, <MergeTag name="first_name" />
+        </Heading>
+        <Text>
+          Order <Span style={{ fontWeight: 700 }}>#10482</Span> ships tomorrow. <Link href="https://example.com/orders/10482">Track it</Link>.
+        </Text>
+        <Table style={{ cellPadding: [8, 0], rowBorder: "1px solid #e4e4e7" }}>
+          <TableRow header>
+            <TableCell>Item</TableCell>
+            <TableCell style={{ textAlign: "right" }}>Price</TableCell>
+          </TableRow>
+          <TableRow>
+            <TableCell>Linen shirt</TableCell>
+            <TableCell style={{ textAlign: "right" }}>$48.00</TableCell>
+          </TableRow>
+        </Table>
+        <Row style={{ gap: 16 }}>
+          <Column>
+            <Text style={{ fontWeight: 700 }}>Shipping to</Text>
+            <Text>Ada Lovelace, London</Text>
+          </Column>
+          <Column>
+            <Text style={{ fontWeight: 700 }}>Next steps</Text>
+            <List type="number">
+              <ListItem>We pack it</ListItem>
+              <ListItem>You track it</ListItem>
+            </List>
+          </Column>
+        </Row>
+        <Button href="https://example.com/orders/10482" style={{ backgroundColor: "#111827", borderRadius: 6 }} hover={{ backgroundColor: "#374151" }}>
+          View your order
+        </Button>
+      </Column>
+      <Text style={{ fontSize: 12, color: "#71717a", textAlign: "center" }}>Acme Inc., 1 Market St, San Francisco</Text>
+    </Email>
+  );
+}
+```
+
+```tsx
+import { outline, render, validate } from "@hyper-elements/react";
+
+const { html, text, diagnostics } = await render(<Receipt />); // warnings in diagnostics; errors throw an ElementsError
+const { valid } = validate(<Receipt />); // the same checks, without rendering
+console.log(outline(<Receipt />)); // the laid-out template as text: each block, its width, its words
+```
+
+To write a template, read [GUIDE.md](./GUIDE.md): how a template is written, and every component on a line. [REFERENCE.md](./REFERENCE.md) has every prop and style in full. Both are written from the components' definitions.
+
+Upgrading from Unlayer Elements? See [Moving from Unlayer Elements](#moving-from-unlayer-elements).
+
+## Using with an AI agent
+
+**With an AI agent:** in Claude Code, add this line to your project's `CLAUDE.md`, and every session starts out knowing these components:
+
+```
+@node_modules/@hyper-elements/react/GUIDE.md
+```
+
+For Codex, Cursor and other agents, add to `AGENTS.md` (or a rule): "Before writing a Hyper Elements template, read node_modules/@hyper-elements/react/GUIDE.md."
+
+Or install the same guide as an agent skill: `npx skills add hyper-elements/hyper-elements`.
+
+## Structure
+
+```
+<Email>            ← the root: Email, Page, Document or Canvas
+  <Section>        ← a band whose background spans the window (optional)
+    <Row>          ← its children side by side, stacked on phones
+      <Column>     ← its children stacked
+        <Heading />
+        <Text />
+        <Button />
+      </Column>
+    </Row>
+  </Section>
+</Email>
+```
+
+A root, a `Section` and a `Column` stack what they hold, so a block doesn't need a `Row` around it. There are no margins: space between blocks is their parent's `gap`, and space inside a box is its `padding`.
+
+## Components
+
+### Roots
+
+| Component | Renders to |
+|-----------|-------------|
+| `<Email>` | Email-safe HTML: tables, with Outlook's markup in conditional comments |
+| `<Page>` | A responsive web page |
+| `<Document>` | Print-ready HTML on pages of its size, and a PDF with `@hyper-elements/react/pdf` |
+| `<Canvas>` | An image of a fixed size, with `@hyper-elements/react/image` |
+
+### Layout
+
+| Component | Description |
+|-----------|-------------|
+| `<Section>` | A band across the whole window, directly in an Email or Page |
+| `<Row>` | Its children side by side; stacked on phones |
+| `<Column>` | Its children stacked, with its own spacing and box; with a background, a card |
+| `<Grid>` | Its children in columns of equal width, row after row |
+| `<Layer>` | Its children over each other: an image with words on it |
+
+### Content
+
+| Component | Description |
+|-----------|-------------|
+| `<Heading>` | A heading, `level` 1 to 6 |
+| `<Text>` | A block of text |
+| `<Span>`, `<Link>`, `<LineBreak>`, `<MergeTag>` | Inside text: a styled run, a link, a new line, a value the sending service fills in |
+| `<Button>` | A link drawn as a button, with its colors on hover |
+| `<Image>` | An image; `src` has the file's size, `style.width` the size shown |
+| `<Divider>` | A horizontal line |
+| `<List>`, `<ListItem>` | A bulleted or numbered list |
+| `<Table>`, `<TableRow>`, `<TableCell>` | A table of data |
+| `<Video>` | A YouTube or Vimeo video: its player on a page, its linked thumbnail in an email |
+| `<Social>` | A line of social network icons, each a link |
+| `<Menu>` | A line or column of links |
+| `<Svg>` and its shapes | Shapes drawn in a box of their own |
+| `<Html>` | Markup written as it is, for what no component says |
+| `<PageBreak>`, `<PageHeader>`, `<PageFooter>`, `<PageNumber>` | In a Document: where a page ends, what's on every page, and page numbers |
+
+## Columns
+
+A `Column` in a `Row` takes its `width`, or a share of what's left.
+
+```tsx
+import { Column, Grid, Row } from "@hyper-elements/react";
+
+// Equal shares.
+<Row style={{ gap: 16 }}>
+  <Column>{/* content */}</Column>
+  <Column>{/* content */}</Column>
+</Row>
+
+// A set width, and what's left.
+<Row style={{ gap: 16 }}>
+  <Column style={{ width: 180 }}>{/* content */}</Column>
+  <Column>{/* content */}</Column>
+</Row>
+
+// Shares of two to one.
+<Row style={{ gap: 16 }}>
+  <Column style={{ flex: 2 }}>{/* content */}</Column>
+  <Column>{/* content */}</Column>
+</Row>
+
+// Side by side on phones too.
+<Row stackOnMobile={false}>
+  <Column>{/* content */}</Column>
+  <Column>{/* content */}</Column>
+</Row>
+
+// Rows of three, one under another on phones.
+<Grid columns={3} style={{ gap: 16 }}>
+  <Column>{/* content */}</Column>
+  <Column>{/* content */}</Column>
+  <Column>{/* content */}</Column>
+</Grid>
+```
+
+## Rendering
+
+```tsx
+const { html, text, head, body, bodyStyle, diagnostics } = await render(<Receipt />);
+```
+
+- `html` is the whole document, from `<!DOCTYPE html>`, with no React hydration markers and no client-side JavaScript.
+- `text` is the plain-text version.
+- `head`, `body` and `bodyStyle` are for embedding the output in a page of your own.
+- `diagnostics` holds warnings and notes. A template with errors throws an `ElementsError`, whose `diagnostics` give each problem's `code`, `message` and `path`.
+
+The options are `pretty` (the HTML indented, for reading it), `mergeTag` (how a merge tag is written, by default `{{name}}`) and `classPrefix` (what every class name starts with, for HTML embedded where other CSS is).
+
+`validate()` runs the same checks without rendering, and `outline()` prints the laid-out template, to check the layout without reading the HTML.
+
+## One template, every output
+
+Share the content, and give each output its root:
+
+```tsx
+import { Button, Column, Document, Email, Heading, Page, Text, render } from "@hyper-elements/react";
+
+const Invoice = () => (
+  <Column style={{ gap: 12 }}>
+    <Heading level={1} style={{ fontSize: 24 }}>Invoice 2705</Heading>
+    <Text>Thank you for your order.</Text>
+    <Button href="https://example.com/invoices/2705" style={{ backgroundColor: "#111827" }}>View it online</Button>
+  </Column>
+);
+
+const email = await render(<Email><Invoice /></Email>);
+const page = await render(<Page><Invoice /></Page>);
+const printed = await render(<Document size="A4" margin={48}><Invoice /></Document>);
+```
+
+`printed.html` is print-ready HTML. For PDF files, [`@hyper-elements/react/pdf`](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/render-pdf.md) writes a `Document` with no browser, and [`@hyper-elements/react/image`](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/render-image.md) writes a `Canvas` as PNG or SVG.
+
+## Phones and hover
+
+`mobile` holds a component's styles on phones, `hidden` shows it on one size only, and `hover` holds its styles under the pointer. Each component's list is in [GUIDE.md](./GUIDE.md).
+
+```tsx
+<Heading style={{ fontSize: 32 }} mobile={{ fontSize: 24, textAlign: "center" }}>Welcome</Heading>
+<Text hidden={{ mobile: true }}>Desktop detail</Text>
+<Text hidden={{ desktop: true }}>Phone detail</Text>
+<Button href="https://example.com" style={{ backgroundColor: "#111827" }} hover={{ backgroundColor: "#374151" }}>Buy</Button>
+```
+
+## Common design patterns
+
+### Header with a logo
+
+```tsx
+<Section style={{ backgroundColor: "#ffffff", padding: [24, 40] }}>
+  <Image src={{ src: "https://example.com/logo.png", width: 240, height: 80 }} alt="Logo" style={{ width: 120 }} />
+</Section>
+```
+
+### Accent bar
+
+```tsx
+<Divider style={{ borderTop: "3px solid #4f46e5" }} />
+```
+
+### Feature grid
+
+```tsx
+<Grid columns={2} style={{ backgroundColor: "#ffffff", padding: [24, 40], gap: 24 }}>
+  <Column style={{ gap: 4 }}>
+    <Heading level={3} style={{ fontSize: 16, fontWeight: 600 }}>Feature 1</Heading>
+    <Text style={{ fontSize: 13, color: "#71717a" }}>Description of the feature.</Text>
+  </Column>
+  <Column style={{ gap: 4 }}>
+    <Heading level={3} style={{ fontSize: 16, fontWeight: 600 }}>Feature 2</Heading>
+    <Text style={{ fontSize: 13, color: "#71717a" }}>Description of the feature.</Text>
+  </Column>
+</Grid>
+```
+
+### Metric cards
+
+```tsx
+<Row style={{ gap: 16 }}>
+  <Column style={{ backgroundColor: "#ffffff", padding: 16, borderRadius: 8, textAlign: "center" }}>
+    <Heading level={2} style={{ fontSize: 28, fontWeight: 700, color: "#0f172a" }}>1.2M</Heading>
+    <Text style={{ fontSize: 12, color: "#94a3b8" }}>API calls</Text>
+  </Column>
+  {/* One Column for each metric */}
+</Row>
+```
+
+### Product card
+
+```tsx
+<Row style={{ backgroundColor: "#ffffff", padding: [20, 40], gap: 16 }}>
+  <Column style={{ width: 160 }}>
+    <Image src={{ src: "https://example.com/product.jpg", width: 320, height: 320 }} alt="Product" style={{ width: "100%" }} />
+  </Column>
+  <Column style={{ gap: 4 }}>
+    <Heading level={3} style={{ fontSize: 16, fontWeight: 600 }}>Product name</Heading>
+    <Text style={{ fontSize: 13, color: "#a1a1aa" }}>Matte white, medium</Text>
+    <Text style={{ fontSize: 16, fontWeight: 700 }}>$89.00</Text>
+  </Column>
+</Row>
+```
+
+### Footer
+
+```tsx
+<Section style={{ padding: [20, 40, 40, 40] }}>
+  <Text style={{ fontSize: 12, color: "#a1a1aa", textAlign: "center" }}>Company name, City, State</Text>
+</Section>
+```
+
+## Your own components
+
+A function that returns components is a component of your own, as in [One template, every output](#one-template-every-output). For a named block with typed props and its own editors, use `component()`:
+
+```tsx
+import { Button, Column, Heading, Image, component, prop } from "@hyper-elements/react";
+
+const ProductCard = component({
+  type: "acme.ProductCard",
+  label: "Product card",
+  props: {
+    name: prop.text({ label: "Name", required: true }),
+    photo: prop.image({ label: "Photo", required: true }),
+    href: prop.link({ label: "Link", required: true }),
+    accent: prop.color({ label: "Accent", default: "#0879a1" }),
+  },
+  render: ({ name, photo, href, accent }) => (
+    <Column style={{ gap: 8 }}>
+      <Image src={photo} alt={name} />
+      <Heading level={3}>{name}</Heading>
+      <Button href={href} style={{ backgroundColor: accent }}>Buy</Button>
+    </Column>
+  ),
+});
+```
+
+For markup no component says, `<Html html="…" />` writes it as it is, in an email and on a page, with nothing in it checked or escaped. Put only markup you wrote there.
+
+## To the Unlayer builder and back
+
+`@hyper-elements/react/builder`: `toDesign()` writes a template as the builder's design JSON, for `loadDesign()`; `fromDesign()` reads a design (made by `toDesign()`, edited in the builder or made there) back as a template, as an element to render and as JSX source.
+
+```tsx
+import { fromDesign, toDesign } from "@hyper-elements/react/builder";
+
+const { design, report } = toDesign(<Receipt />); // report: what the builder can't hold as it is, one line each
+// …the design is edited in the builder, and saved…
+const { element, code, report: read } = fromDesign(saved, { displayMode: "email" }); // "web" a Page, "document" a Document
+```
+
+The design holds no Hyper Elements data. A style or prop a builder tool has no field for is a hidden property of that tool, kept in the design under its own name and drawn by Hyper Elements, with no editor in the builder yet. What the builder can't arrange comes back with the same look, flatter: a Section around several Rows as a Section each, a box's padding on its blocks, a Grid as Rows of Columns. What no tool shows (a Layer, an Svg, a Table, a box nested in a column, your own `component()`) goes as an HTML block of the new engine's markup, and comes back as an `Html` block, as the builder's own HTML blocks do. A design's markup comes back as it is: where designs can hold untrusted content, pass your sanitizer, `fromDesign(saved, { toSafeHtml })`. A line height goes in the builder's field as a whole percentage, as browsers draw it, so `24px` at 13px is `185%`, a twentieth of a pixel taller there. The builder has no page numbers yet: a `PageNumber` goes as its token, which the editor's PDF prints as it is, and `report` says so.
+
+## Task guides and runnable examples
+
+- [Transactional email in React](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/transactional-email.md): render HTML and plain text, then send a receipt.
+- [Resend, AWS SES, Postmark, SendGrid, and Nodemailer](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/email-providers.md): complete provider integrations.
+- [One React template to email, web, and PDF](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/one-template-email-web-pdf.md): shared invoice content with output-specific roots.
+- [React invoice PDF with Playwright](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/react-to-pdf.md): generate actual PDF bytes from document HTML.
+- [React to Unlayer visual editing](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/visual-editing.md): `toDesign()`, editor loading, export, and what the builder can hold.
+
+See [when to choose Hyper Elements](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/README.md) and the [runnable example](https://github.com/hyper-elements/hyper-elements/tree/main/examples/content-workflows).
+
+## Moving from Unlayer Elements
+
+Unlayer Elements (`@unlayer/react-elements`) is the old package. Its components (`Body`, `ColumnLayouts`, `renderToHtml()` and the rest) aren't in this one. The codemod moves templates written with them:
+
+```bash
+npx @hyper-elements/migrate src/emails --from unlayer-elements   # templates written with Unlayer Elements
+npx @hyper-elements/migrate src/emails                           # React Email templates
+```
+
+It lists what it would change, and `--write` replaces the files (only those git can restore). Then install `@hyper-elements/react`, and remove `@unlayer/react-elements` once nothing imports it. What it can't move is listed, and that file is left as it was to rewrite by hand. See the [migration guide](https://github.com/hyper-elements/hyper-elements/blob/main/packages/react/docs/migrating-from-unlayer-elements.md) and [`@hyper-elements/migrate`](https://github.com/hyper-elements/hyper-elements/tree/main/packages/migrate).
+
+## Development
+
+```bash
+pnpm build          # Build the package
+pnpm test           # Run tests
+pnpm storybook      # Launch Storybook
+```
+
+## License
+
+MIT