@email-kit/cli 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +124 -17
- package/dist/cli.js +654 -40
- package/dist/docs/guide/checks-and-ci.md +158 -0
- package/dist/docs/guide/components.md +426 -0
- package/dist/docs/guide/formatting.md +77 -0
- package/dist/docs/guide/messages.md +147 -0
- package/dist/docs/guide/sending.md +242 -0
- package/dist/docs/guide/templates.md +269 -0
- package/dist/docs/guide/theme.md +212 -0
- package/dist/docs/reference/checks.md +876 -0
- package/dist/docs/reference/cli.md +214 -0
- package/dist/docs/reference/configuration.md +115 -0
- package/dist/docs/reference/errors.md +264 -0
- package/dist/docs/reference/mustache-core.md +340 -0
- package/dist/skill/email-kit/SKILL.md +326 -0
- package/package.json +6 -6
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
<!-- Generated from docs/guide/checks-and-ci.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
|
|
2
|
+
|
|
3
|
+
# Checks and CI
|
|
4
|
+
|
|
5
|
+
`email-kit check` looks for problems that make an email render badly, read badly or break rules:
|
|
6
|
+
accessibility, dark mode, size limits, links, copy, translations, the theme and the project setup.
|
|
7
|
+
The [checks reference](../reference/checks.md) lists every check with its default level and fix.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npx email-kit check
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## What it checks
|
|
14
|
+
|
|
15
|
+
`check` compiles in memory (it writes nothing), then runs the checks over:
|
|
16
|
+
|
|
17
|
+
- **the compiled emails**, every template in every locale, including the two
|
|
18
|
+
[pseudo-locales](messages.md#pseudo-locales);
|
|
19
|
+
- **renders of every fixture**, and of three variants it generates from the schema: an empty one
|
|
20
|
+
(optional fields left out, strings at their minimum length), a long one (long strings, 25 items
|
|
21
|
+
per list unless `maxItems` says fewer) and a hostile one (markup, quotes and braces);
|
|
22
|
+
- **the template sources**, for literal colours, fonts and sizes that should come from the theme;
|
|
23
|
+
- **the theme**, for contrast and dark mode;
|
|
24
|
+
- **the project**, for an out-of-date `_generated` folder and a missing runtime dependency.
|
|
25
|
+
|
|
26
|
+
So the schema's limits matter: a required name without `.min(1)` can render as "Thanks, !" in the
|
|
27
|
+
empty variant, and a list without a maximum can push the long variant past Gmail's clipping size.
|
|
28
|
+
|
|
29
|
+
## Reading the output
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
order-shipped (en)
|
|
33
|
+
! a11y.link-text src/email-kit/order-shipped/template.tsx
|
|
34
|
+
Generic link text "Click here"
|
|
35
|
+
Fix: Say where the link goes ("View your order"): screen reader users list links out of context.
|
|
36
|
+
Docs: https://github.com/email-kit/email-kit/blob/main/docs/reference/checks.md#a11ylink-text
|
|
37
|
+
|
|
38
|
+
0 errors, 1 warning, 2 notes
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Findings are grouped by template and locale, with a group each for the theme and the project.
|
|
42
|
+
Each has a level:
|
|
43
|
+
|
|
44
|
+
| Mark | Level | Fails `check`? |
|
|
45
|
+
|---|---|---|
|
|
46
|
+
| `✗` | error | Yes: exit code 1 |
|
|
47
|
+
| `!` | warning | No |
|
|
48
|
+
| `i` | note (info) | No |
|
|
49
|
+
|
|
50
|
+
| Flag | Does |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `--reporter <name>` | `human` (the default), `json` or `github`, which writes annotations for GitHub Actions |
|
|
53
|
+
| `--json` | The same as `--reporter json`: the findings in a versioned JSON schema |
|
|
54
|
+
| `--config <path>` | Use this config file instead of `./email-kit.config.ts` |
|
|
55
|
+
|
|
56
|
+
## In CI
|
|
57
|
+
|
|
58
|
+
Run `check` on every pull request. With GitHub Actions, the `github` reporter puts each finding on
|
|
59
|
+
the line it's about:
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
- run: npm ci
|
|
63
|
+
- run: npx email-kit check --reporter github
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`check` needs the devDependencies, so run it after a full install.
|
|
67
|
+
|
|
68
|
+
## Commit the output, or compile in the build
|
|
69
|
+
|
|
70
|
+
By default `check` expects the `_generated` folder to be committed, so deploys need no compile
|
|
71
|
+
step: `output.drift` fails when it's out of date (run `email-kit compile` and commit), and
|
|
72
|
+
`output.gitignored` warns when it's ignored.
|
|
73
|
+
|
|
74
|
+
To compile in your build instead, run the compile before the app's build
|
|
75
|
+
(`"build": "email-kit compile && next build"`), gitignore the folder, and turn both checks off
|
|
76
|
+
with your reason:
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
checks: {
|
|
80
|
+
"output.drift": { level: "off", reason: "The build compiles the emails" },
|
|
81
|
+
"output.gitignored": { level: "off", reason: "The build compiles the emails" },
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Either way, `@email-kit/runtime` must be a dependency, not a devDependency, since the app imports
|
|
86
|
+
it when it runs (`output.runtime-dependency`).
|
|
87
|
+
|
|
88
|
+
## Change a check's level
|
|
89
|
+
|
|
90
|
+
Each check has a default level. Change it per project in `email-kit.config.ts`, with the reason a
|
|
91
|
+
reviewer will read:
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
checks: {
|
|
95
|
+
"img.fluid-width": { level: "off", reason: "Hero images are fixed width by design" },
|
|
96
|
+
"i18n.unused-keys": { level: "error", reason: "We keep message files tidy" },
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
| Field | Type | |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| `level` | `"off"`, `"info"`, `"warn"` or `"error"` | `error` fails `check` (exit 1); `warn` and `info` are reported only |
|
|
103
|
+
| `reason` | `string` | Required, and not empty |
|
|
104
|
+
|
|
105
|
+
An unknown check id fails the config, with a suggestion if it's close to a real one. [Team checks](#team-checks) take levels the same way. Checks that the compiler enforces, such as `source.fixture-valid`, fail
|
|
106
|
+
the compile whatever their level.
|
|
107
|
+
|
|
108
|
+
## Team checks
|
|
109
|
+
|
|
110
|
+
Add your own rules with `defineCheck()` in `customChecks`. They run alongside the catalogue, take
|
|
111
|
+
levels from `checks`, and show in every reporter.
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { defineCheck, defineConfig } from "@email-kit/core"
|
|
115
|
+
|
|
116
|
+
const helpLink = defineCheck({
|
|
117
|
+
id: "acme.help-link",
|
|
118
|
+
level: "warn",
|
|
119
|
+
rule: "Every email links to the help centre.",
|
|
120
|
+
fix: "Add the footer's help link.",
|
|
121
|
+
run({ emails }, report) {
|
|
122
|
+
for (const email of emails) {
|
|
123
|
+
const hrefs = email.elements("a").map((a) => a.attributes.href ?? "")
|
|
124
|
+
if (!hrefs.some((href) => href.startsWith("https://help.acme.example"))) {
|
|
125
|
+
report({ email, message: "No link to the help centre" })
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
},
|
|
129
|
+
})
|
|
130
|
+
|
|
131
|
+
export default defineConfig({
|
|
132
|
+
customChecks: [helpLink],
|
|
133
|
+
})
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
| Field | Type | |
|
|
137
|
+
|---|---|---|
|
|
138
|
+
| `id` | `string` | `family.name` in lowercase, with a family of your own (`acme.help-link`); email-kit's families, such as `html.` or `text.`, are refused |
|
|
139
|
+
| `level` | `"error"`, `"warn"` or `"info"` | The default level |
|
|
140
|
+
| `rule` | `string` | The rule, in one sentence |
|
|
141
|
+
| `fix` | `string` | The usual fix |
|
|
142
|
+
| `docs` | `string` | Where your docs for it live |
|
|
143
|
+
| `on` | `"template"`, `"render"` or `"both"` | `template` (the default) checks the compiled templates, with `{{placeholders}}` where data goes; `render` checks the renders of every fixture and generated variant |
|
|
144
|
+
| `run` | `(context, report) => void` | The check |
|
|
145
|
+
|
|
146
|
+
`context.emails` holds one entry per template and locale (and, for renders, per fixture):
|
|
147
|
+
|
|
148
|
+
| Field | |
|
|
149
|
+
|---|---|
|
|
150
|
+
| `template`, `locale` | Which email |
|
|
151
|
+
| `fixture` | For renders: the fixture's name, or a generated variant such as `"generated empty"` |
|
|
152
|
+
| `subject`, `preheader`, `html`, `text` | The parts |
|
|
153
|
+
| `elements(name?)` | Every element, or those with a tag name: `{ name, attributes, text, offset, mso }`, where `mso` is true inside a classic-Outlook-only block |
|
|
154
|
+
|
|
155
|
+
`report({ message, email?, at?, fix? })` records a problem: leave out `email` for a project-wide
|
|
156
|
+
one, give `at` (an element's `offset`) to point at a place in the HTML, and `fix` to replace the
|
|
157
|
+
check's usual fix. A check that throws is reported as
|
|
158
|
+
[`check-failed`](../reference/errors.md#check-failed).
|
|
@@ -0,0 +1,426 @@
|
|
|
1
|
+
<!-- Generated from docs/guide/components.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
|
|
2
|
+
|
|
3
|
+
# Components
|
|
4
|
+
|
|
5
|
+
`@email-kit/components` has the building blocks of an email body. Every value they draw with
|
|
6
|
+
(colours, type, spacing, radius) comes from the [theme](theme.md), and each colour
|
|
7
|
+
gets its dark-mode rule from it. They are built from tables and cell padding rather than margins,
|
|
8
|
+
following what email clients are known to support; they haven't been tested in real email
|
|
9
|
+
clients yet.
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
import { Button, Heading, Text } from "@email-kit/components"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Every email is centred in a container of the theme's `layout.container` width (600px by default),
|
|
16
|
+
fluid below that width. The compiler adds it, so templates start straight with content. There's no
|
|
17
|
+
`Layout`, `Row` or `Column` component yet: content stacks in one column.
|
|
18
|
+
|
|
19
|
+
In the tables below, `Child` is anything a template can render: text, numbers, data fields,
|
|
20
|
+
messages from `t()`, elements, or arrays of them. A URL prop (`href`, `src`) takes a literal
|
|
21
|
+
string, a `url` field from `data`, or a sender value.
|
|
22
|
+
|
|
23
|
+
Most components leave space below themselves (16px unless stated), so a template is a plain list
|
|
24
|
+
of components.
|
|
25
|
+
|
|
26
|
+
| Component | For |
|
|
27
|
+
|---|---|
|
|
28
|
+
| [`Text`](#text) | A paragraph |
|
|
29
|
+
| [`Heading`](#heading) | A heading, h1 to h3 |
|
|
30
|
+
| [`Link`](#link) | A text link |
|
|
31
|
+
| [`Button`](#button) | A call to action |
|
|
32
|
+
| [`Image`](#image) | A content image |
|
|
33
|
+
| [`Divider`](#divider) | A horizontal rule |
|
|
34
|
+
| [`Spacer`](#spacer) | Vertical space |
|
|
35
|
+
| [`Section`](#section) | A padded block, optionally on a surface colour |
|
|
36
|
+
| [`List`, `ListItem`](#list-and-listitem) | A bulleted or numbered list |
|
|
37
|
+
| [`KeyValue`](#keyvalue) | Labelled facts, such as an order number and a date |
|
|
38
|
+
| [`Callout`](#callout) | A notice with a status colour |
|
|
39
|
+
| [`OtpCode`](#otpcode) | A one-time code |
|
|
40
|
+
| [`DataTable`](#datatable) | Tabular data with headers |
|
|
41
|
+
| [`LineItems`](#lineitems) | Itemised lines and totals for receipts and invoices |
|
|
42
|
+
| [`Footer`](#footer) | The footer of a transactional email |
|
|
43
|
+
|
|
44
|
+
## Text
|
|
45
|
+
|
|
46
|
+
A paragraph, in the body colour by default.
|
|
47
|
+
|
|
48
|
+
| Prop | Type | Default | |
|
|
49
|
+
|---|---|---|---|
|
|
50
|
+
| `children` | `Child` | | The text |
|
|
51
|
+
| `size` | `"lead"`, `"body"`, `"bodySm"` or `"caption"` | `"body"` | A step of the type scale: 18/28, 16/24, 14/22 or 14/20 px by default |
|
|
52
|
+
| `tone` | `"default"`, `"muted"` or `"subtle"` | `"default"` | The `ink`, `mutedInk` or `subtleInk` colour role |
|
|
53
|
+
| `align` | `"left"`, `"center"` or `"right"` | start of the line | Body copy reads best start-aligned |
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
<Text>{t("intro")}</Text>
|
|
57
|
+
<Text size="caption" tone="muted">{t("legal")}</Text>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Heading
|
|
61
|
+
|
|
62
|
+
A heading from the h1–h3 steps of the type scale.
|
|
63
|
+
|
|
64
|
+
| Prop | Type | Default | |
|
|
65
|
+
|---|---|---|---|
|
|
66
|
+
| `children` | `Child` | | The text |
|
|
67
|
+
| `level` | `1`, `2` or `3` | `1` | Use one h1 per email, then h2 and h3 without skipping a level (`a11y.one-h1`) |
|
|
68
|
+
| `align` | `"left"`, `"center"` or `"right"` | start of the line | |
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
<Heading>{t("heading", { name: data.name })}</Heading>
|
|
72
|
+
<Heading level={2}>{t("details")}</Heading>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Link
|
|
76
|
+
|
|
77
|
+
A text link in the theme's `link` colour, underlined so it isn't told apart by colour alone.
|
|
78
|
+
|
|
79
|
+
| Prop | Type | Default | |
|
|
80
|
+
|---|---|---|---|
|
|
81
|
+
| `href` | URL | | |
|
|
82
|
+
| `children` | `Child` | | The link text: it should make sense on its own (`a11y.link-text`) |
|
|
83
|
+
| `title` | `Child` | | A tooltip; never the only description of the link |
|
|
84
|
+
|
|
85
|
+
```tsx
|
|
86
|
+
<Text>
|
|
87
|
+
{t("help")} <Link href={sender.helpUrl}>{t("helpLink")}</Link>
|
|
88
|
+
</Text>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
In the plain-text part a link becomes `text: URL`.
|
|
92
|
+
|
|
93
|
+
## Button
|
|
94
|
+
|
|
95
|
+
A link styled as a button. Classic Outlook draws it with square corners.
|
|
96
|
+
|
|
97
|
+
| Prop | Type | Default | |
|
|
98
|
+
|---|---|---|---|
|
|
99
|
+
| `href` | URL | | |
|
|
100
|
+
| `children` | `Child` | | A short, verb-first label, such as "Track your parcel" |
|
|
101
|
+
| `variant` | `"primary"`, `"secondary"` or `"destructive"` | `"primary"` | The theme's action colours. Keep to one primary action per email |
|
|
102
|
+
| `size` | `"sm"`, `"md"` or `"lg"` | `"md"` | At least 36, 44 or 52 px tall. `sm` is under 44 px: use it for secondary actions only |
|
|
103
|
+
| `fullWidth` | `boolean` | `false` | Fill the container's width |
|
|
104
|
+
| `title` | `Child` | | A tooltip; never the only description of the action |
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
<Button href={data.trackingUrl}>{t("track")}</Button>
|
|
108
|
+
<Button href={data.reviewUrl} variant="destructive">{t("review")}</Button>
|
|
109
|
+
<Button href={sender.helpUrl} variant="secondary" size="sm">{t("contact")}</Button>
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Image
|
|
113
|
+
|
|
114
|
+
A content image. `kind` says what the image is for, and decides which props it needs.
|
|
115
|
+
|
|
116
|
+
| Prop | Type | Default | |
|
|
117
|
+
|---|---|---|---|
|
|
118
|
+
| `kind` | `"decorative"`, `"informative"` or `"functional"` | | `decorative` adds nothing a reader needs (empty alt, skipped by screen readers); `informative` carries content; `functional` is a link |
|
|
119
|
+
| `src` | URL | | An absolute `https:` URL to a PNG, JPEG or GIF |
|
|
120
|
+
| `width` | `number` | | The display width in whole px. Serve about twice as many pixels for sharp high-density screens |
|
|
121
|
+
| `height` | `number` | | The display height in whole px |
|
|
122
|
+
| `alt` | `Child` | | `informative` and `functional` only, and required for them. What the image shows, or for a link, where it goes |
|
|
123
|
+
| `href` | URL | | `functional` only, and required for it |
|
|
124
|
+
| `fluid` | `boolean` | `false` | Scale down to the container's width on narrow screens |
|
|
125
|
+
| `rounded` | `boolean` | `false` | The theme's image radius. Classic Outlook draws square corners |
|
|
126
|
+
| `align` | `"left"` or `"center"` | start of the line | |
|
|
127
|
+
|
|
128
|
+
```tsx
|
|
129
|
+
<Image
|
|
130
|
+
kind="functional"
|
|
131
|
+
src="https://cdn.acme.example/logo@2x.png"
|
|
132
|
+
alt={t("logoAlt", { product: sender.productName })}
|
|
133
|
+
href="https://acme.example"
|
|
134
|
+
width={120}
|
|
135
|
+
height={30}
|
|
136
|
+
/>
|
|
137
|
+
<Image
|
|
138
|
+
kind="informative"
|
|
139
|
+
src="https://cdn.acme.example/hero@2x.png"
|
|
140
|
+
alt={t("heroAlt")}
|
|
141
|
+
width={536}
|
|
142
|
+
height={200}
|
|
143
|
+
fluid
|
|
144
|
+
rounded
|
|
145
|
+
align="center"
|
|
146
|
+
/>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
A literal `src` is checked when the template compiles: SVG, WebP, AVIF, `http:` URLs, relative
|
|
150
|
+
paths and widths or heights that aren't whole numbers fail with
|
|
151
|
+
[`invalid-image`](../reference/errors.md#invalid-image), as does an empty `alt` on an informative or
|
|
152
|
+
functional image.
|
|
153
|
+
|
|
154
|
+
## Divider
|
|
155
|
+
|
|
156
|
+
A 1px horizontal rule in the theme's `divider` colour, with 16px of space above and below. It
|
|
157
|
+
takes no props.
|
|
158
|
+
|
|
159
|
+
```tsx
|
|
160
|
+
<Divider />
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Spacer
|
|
164
|
+
|
|
165
|
+
Vertical space of a fixed height.
|
|
166
|
+
|
|
167
|
+
| Prop | Type | Default | |
|
|
168
|
+
|---|---|---|---|
|
|
169
|
+
| `size` | `"sm"`, `"md"`, `"lg"` or `"section"` | `"md"` | 8, 16, 24 or 32 px |
|
|
170
|
+
|
|
171
|
+
```tsx
|
|
172
|
+
<Spacer size="lg" />
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Section
|
|
176
|
+
|
|
177
|
+
A block of content with padding, optionally on a surface colour.
|
|
178
|
+
|
|
179
|
+
| Prop | Type | Default | |
|
|
180
|
+
|---|---|---|---|
|
|
181
|
+
| `children` | `Child` | | |
|
|
182
|
+
| `padding` | `"none"`, `"sm"` or `"md"` | `"md"` | `md` is 32px on every side; `sm` is 16px |
|
|
183
|
+
| `surface` | `"canvas"`, `"card"` or `"muted"` | none | A background from the theme's surface roles. Without it the canvas shows through |
|
|
184
|
+
|
|
185
|
+
```tsx
|
|
186
|
+
<Section surface="muted" padding="sm">
|
|
187
|
+
<Heading level={2}>{t("codeHeading")}</Heading>
|
|
188
|
+
<OtpCode label={t("codeLabel")} code={data.code} />
|
|
189
|
+
</Section>
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## List and ListItem
|
|
193
|
+
|
|
194
|
+
A real bulleted or numbered list. `List` holds `ListItem`s, or an `Each` of them.
|
|
195
|
+
|
|
196
|
+
| Prop | Type | Default | |
|
|
197
|
+
|---|---|---|---|
|
|
198
|
+
| `children` | `Child` | | `ListItem`s |
|
|
199
|
+
| `ordered` | `boolean` | `false` | A numbered list |
|
|
200
|
+
|
|
201
|
+
`ListItem` takes `children` only.
|
|
202
|
+
|
|
203
|
+
```tsx
|
|
204
|
+
<List ordered>
|
|
205
|
+
<Each of={data.steps}>{(step) => <ListItem>{step}</ListItem>}</Each>
|
|
206
|
+
</List>
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## KeyValue
|
|
210
|
+
|
|
211
|
+
Facts as labelled rows, such as an order number and a date. Neither layout uses columns, so both
|
|
212
|
+
read well on a phone. The plain-text part has a `Label: value` line for each.
|
|
213
|
+
|
|
214
|
+
| Prop | Type | Default | |
|
|
215
|
+
|---|---|---|---|
|
|
216
|
+
| `items` | `KeyValueItem[]` | | The rows |
|
|
217
|
+
| `layout` | `"inline"` or `"stacked"` | `"inline"` | `inline` is "Label: value" on one line; `stacked` puts the label above the value |
|
|
218
|
+
|
|
219
|
+
`KeyValueItem`:
|
|
220
|
+
|
|
221
|
+
| Field | Type | |
|
|
222
|
+
|---|---|---|
|
|
223
|
+
| `label` | `Child` | |
|
|
224
|
+
| `value` | `Child` | |
|
|
225
|
+
| `copyable` | `boolean` | Lets a click select the whole value, in clients that support it |
|
|
226
|
+
|
|
227
|
+
```tsx
|
|
228
|
+
<KeyValue
|
|
229
|
+
items={[
|
|
230
|
+
{ label: t("order"), value: data.orderNumber, copyable: true },
|
|
231
|
+
{ label: t("date"), value: data.date },
|
|
232
|
+
]}
|
|
233
|
+
/>
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## Callout
|
|
237
|
+
|
|
238
|
+
A notice on a status surface, with a bold title. The title carries the meaning in words, so the
|
|
239
|
+
colour is never the only signal.
|
|
240
|
+
|
|
241
|
+
| Prop | Type | Default | |
|
|
242
|
+
|---|---|---|---|
|
|
243
|
+
| `tone` | `"info"`, `"success"`, `"warning"` or `"error"` | | The theme's status colours |
|
|
244
|
+
| `title` | `Child` | | Required |
|
|
245
|
+
| `children` | `Child` | | The body: text and links |
|
|
246
|
+
|
|
247
|
+
```tsx
|
|
248
|
+
<Callout tone="warning" title={t("notYouTitle")}>
|
|
249
|
+
{t("notYou")}
|
|
250
|
+
</Callout>
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
## OtpCode
|
|
254
|
+
|
|
255
|
+
A one-time code: a label, then the code once, large and monospaced on the theme's code surface.
|
|
256
|
+
The code stays one run of characters, spaced with letter-spacing rather than split up, so copying
|
|
257
|
+
it gives the whole code.
|
|
258
|
+
|
|
259
|
+
| Prop | Type | Default | |
|
|
260
|
+
|---|---|---|---|
|
|
261
|
+
| `code` | `Child` | | Contiguous digits or letters, with no spaces or hyphens inside |
|
|
262
|
+
| `label` | `Child` | | Words that name it as a code and say what it's for, such as "Your code to sign in to Acme" |
|
|
263
|
+
|
|
264
|
+
```tsx
|
|
265
|
+
<OtpCode label={t("label", { product: sender.productName })} code={data.code} />
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Mark the field with [`secret`](templates.md#field-markers) so `check` keeps it out of the subject
|
|
269
|
+
and preheader.
|
|
270
|
+
|
|
271
|
+
## DataTable
|
|
272
|
+
|
|
273
|
+
A real data table with a caption and header cells, for rows from a list field. Amounts align to
|
|
274
|
+
the end of the line. The plain-text part lists each row as `Header: value` lines.
|
|
275
|
+
|
|
276
|
+
| Prop | Type | Default | |
|
|
277
|
+
|---|---|---|---|
|
|
278
|
+
| `caption` | `Child` | | Names the table |
|
|
279
|
+
| `rows` | a list field | | Such as `data.logins` |
|
|
280
|
+
| `columns` | `DataTableColumn[]` | | At least two ([`invalid-table`](../reference/errors.md#invalid-table)); use `KeyValue` or `List` for one |
|
|
281
|
+
| `rowHeaders` | `boolean` | `true` | The first column heads its row |
|
|
282
|
+
| `summary` | `(SummaryRow \| OptionalRow)[]` | | Rows under the data, such as totals |
|
|
283
|
+
|
|
284
|
+
`DataTableColumn`:
|
|
285
|
+
|
|
286
|
+
| Field | Type | |
|
|
287
|
+
|---|---|---|
|
|
288
|
+
| `header` | `Child` | |
|
|
289
|
+
| `cell` | `(row) => Child` | The cell for one row, such as `(row) => row.time` |
|
|
290
|
+
| `align` | `"start"` or `"end"` | `end` for numbers and amounts. Default: `start` |
|
|
291
|
+
| `width` | `number` | In px |
|
|
292
|
+
|
|
293
|
+
`SummaryRow` is `{ label, amount, emphasis? }`: the label spans the leading columns and the amount
|
|
294
|
+
sits in the last; `emphasis` makes it bold with a strong rule above, for a grand total.
|
|
295
|
+
`optionalRow(field, (value) => row)` makes a summary row that shows only when an optional field is
|
|
296
|
+
present.
|
|
297
|
+
|
|
298
|
+
```tsx
|
|
299
|
+
<DataTable
|
|
300
|
+
caption={t("recentCaption")}
|
|
301
|
+
rows={data.recent}
|
|
302
|
+
columns={[
|
|
303
|
+
{ header: t("time"), cell: (row) => row.time },
|
|
304
|
+
{ header: t("device"), cell: (row) => row.device },
|
|
305
|
+
]}
|
|
306
|
+
/>
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
## LineItems
|
|
310
|
+
|
|
311
|
+
Itemised lines and totals for receipts and invoices: a `DataTable` of the items, then the
|
|
312
|
+
subtotal, discounts, shipping, taxes and the total, in that order. Amounts are strings your backend
|
|
313
|
+
formats (see [Formatting dates, money and numbers](formatting.md)).
|
|
314
|
+
|
|
315
|
+
| Prop | Type | Default | |
|
|
316
|
+
|---|---|---|---|
|
|
317
|
+
| `caption` | `Child` | | Such as "Order A-1042" |
|
|
318
|
+
| `items` | a list field | | |
|
|
319
|
+
| `headers` | `{ item, qty, unitPrice?, lineTotal }` | | Column headers. The unit price column appears when both its header and its cell are given |
|
|
320
|
+
| `cells` | `{ name, meta?, qty, unitPrice?, lineTotal }` | | Functions from an item to its cells. `meta` is a second line under the name, such as a size |
|
|
321
|
+
| `subtotal` | `SummaryRow` | | |
|
|
322
|
+
| `discounts` | `(SummaryRow \| OptionalRow)[]` | | Shown as given, so write them as negative amounts |
|
|
323
|
+
| `shipping` | `SummaryRow \| OptionalRow` | | |
|
|
324
|
+
| `taxes` | `(SummaryRow \| OptionalRow)[]` | | Each label names the rate and whether it's included, such as "VAT 20% (included)" |
|
|
325
|
+
| `total` | `SummaryRow` | | Required; always emphasised |
|
|
326
|
+
|
|
327
|
+
```tsx
|
|
328
|
+
<LineItems
|
|
329
|
+
caption={t("caption", { order: data.orderNumber })}
|
|
330
|
+
items={data.items}
|
|
331
|
+
headers={{ item: t("item"), qty: t("qty"), lineTotal: t("lineTotal") }}
|
|
332
|
+
cells={{
|
|
333
|
+
name: (item) => item.name,
|
|
334
|
+
meta: (item) => <If when={item.variant}>{(variant) => variant}</If>,
|
|
335
|
+
qty: (item) => item.qty,
|
|
336
|
+
lineTotal: (item) => item.total,
|
|
337
|
+
}}
|
|
338
|
+
subtotal={{ label: t("subtotal"), amount: data.subtotal }}
|
|
339
|
+
discounts={[optionalRow(data.discount, (discount) => ({ label: t("discount"), amount: discount }))]}
|
|
340
|
+
shipping={{ label: t("shipping"), amount: data.shipping }}
|
|
341
|
+
taxes={[{ label: t("vat"), amount: data.vat }]}
|
|
342
|
+
total={{ label: t("total"), amount: data.total }}
|
|
343
|
+
/>
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
email-kit doesn't check that the amounts add up: your backend computes them.
|
|
347
|
+
|
|
348
|
+
## Footer
|
|
349
|
+
|
|
350
|
+
The footer of a transactional email: why the reader got it, who sent it and from where, and the
|
|
351
|
+
help and privacy links, in small muted type under a hairline. Unsubscribe links and the other
|
|
352
|
+
marketing parts don't exist yet.
|
|
353
|
+
|
|
354
|
+
`check` requires a reason line and a sender in every email (`legal.reason`,
|
|
355
|
+
`legal.sender-identity`), and a postal address in `marketing` and `consent-request` emails
|
|
356
|
+
(`legal.postal-address`). It finds them by the classes `Footer` puts on its parts:
|
|
357
|
+
`ek-footer-reason`, `ek-footer-sender` and `ek-footer-address`. A footer you build yourself
|
|
358
|
+
passes the same checks if it carries those classes.
|
|
359
|
+
|
|
360
|
+
| Prop | Type | Default | |
|
|
361
|
+
|---|---|---|---|
|
|
362
|
+
| `reason` | `Child` | | Why the reader got the email, naming the account or relationship. Required |
|
|
363
|
+
| `sender` | `Child` | | Who sends it: the legal name or brand, such as `sender.legalName`. Required |
|
|
364
|
+
| `address` | `Child` | | The postal address, such as `sender.postalAddress` |
|
|
365
|
+
| `links` | `FooterLink[]` | | `{ href, label }` each: help or contact first, then privacy. Shown on one line, separated by a middle dot |
|
|
366
|
+
|
|
367
|
+
```tsx
|
|
368
|
+
<Footer
|
|
369
|
+
reason={t("footer", { product: sender.productName })}
|
|
370
|
+
sender={sender.legalName}
|
|
371
|
+
address={sender.postalAddress}
|
|
372
|
+
links={[
|
|
373
|
+
{ href: sender.helpUrl, label: t("help") },
|
|
374
|
+
{ href: sender.privacyUrl, label: t("privacy") },
|
|
375
|
+
]}
|
|
376
|
+
/>
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
## Your own components
|
|
380
|
+
|
|
381
|
+
A component is a function that takes props and returns JSX. Start the file with
|
|
382
|
+
`/** @jsxImportSource @email-kit/core */` (unless your tsconfig sets
|
|
383
|
+
[`jsxImportSource`](templates.md) to email-kit), keep it in a folder whose name starts with `_`, such as `_shared/`, and import it
|
|
384
|
+
with a relative path. Build on the components above where you can: `check` expects text to have a px
|
|
385
|
+
line height and an explicit direction, which `Text` and `Heading` give you.
|
|
386
|
+
|
|
387
|
+
Colour things with theme roles rather than literal colours: `role("muted")` writes the light value
|
|
388
|
+
inline and tags the element so the dark value applies in dark mode. `check` fails on literal
|
|
389
|
+
colours, font families and font sizes in templates and your components
|
|
390
|
+
(`source.no-literal-colour`, `source.no-font-family`, `source.no-font-size`). `useTheme()` gives
|
|
391
|
+
the resolved theme (spacing, radius and the type scale in px, the light colours as hex), and
|
|
392
|
+
`useDirection()` the writing direction of the locale being compiled. For text in an element of your
|
|
393
|
+
own, `font(step)` from `@email-kit/components` gives a type step's family stack, px size and line
|
|
394
|
+
height, and the line-height rule classic Outlook needs:
|
|
395
|
+
`<p style={{ margin: "0", ...font("bodySm"), color: role("mutedInk") }}>`.
|
|
396
|
+
|
|
397
|
+
```tsx
|
|
398
|
+
/** @jsxImportSource @email-kit/core */
|
|
399
|
+
import { Text } from "@email-kit/components"
|
|
400
|
+
import { type Child, role, useTheme } from "@email-kit/core"
|
|
401
|
+
|
|
402
|
+
/** A muted note on its own surface. */
|
|
403
|
+
export function Note(props: { readonly children?: Child }) {
|
|
404
|
+
const { space } = useTheme()
|
|
405
|
+
return (
|
|
406
|
+
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
|
|
407
|
+
<tbody>
|
|
408
|
+
<tr>
|
|
409
|
+
<td
|
|
410
|
+
style={{
|
|
411
|
+
padding: `${space.stack.md}px ${space.stack.md}px 0`,
|
|
412
|
+
backgroundColor: role("muted"),
|
|
413
|
+
}}
|
|
414
|
+
>
|
|
415
|
+
<Text size="bodySm" tone="muted">
|
|
416
|
+
{props.children}
|
|
417
|
+
</Text>
|
|
418
|
+
</td>
|
|
419
|
+
</tr>
|
|
420
|
+
</tbody>
|
|
421
|
+
</table>
|
|
422
|
+
)
|
|
423
|
+
}
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
The colour roles are listed under [roles](theme.md#roles).
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
<!-- Generated from docs/guide/formatting.md for AI coding agents: run `pnpm --filter @email-kit/cli test -u` after changing the docs. -->
|
|
2
|
+
|
|
3
|
+
# Formatting dates, money and numbers
|
|
4
|
+
|
|
5
|
+
email-kit templates don't format values at send time ([ADR 0008](https://github.com/email-kit/email-kit/blob/main/docs/adr/0008-backend-formats-values.md)). Your backend formats them for the
|
|
6
|
+
recipient and passes strings; the template prints them as they are. That keeps the output
|
|
7
|
+
identical whichever language renders it, and puts the recipient's locale and time zone where
|
|
8
|
+
they're known: in your backend.
|
|
9
|
+
|
|
10
|
+
Mark such fields in the schema, so the generated types tell whoever calls `render()`:
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
import { formatted } from "@email-kit/core"
|
|
14
|
+
|
|
15
|
+
schema: z.object({
|
|
16
|
+
orderDate: z.string().meta(formatted("date")),
|
|
17
|
+
deliveryWindow: z.string().meta(formatted("date-time")),
|
|
18
|
+
total: z.string().meta(formatted("money")),
|
|
19
|
+
savings: z.string().meta(formatted("percent")),
|
|
20
|
+
})
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Kinds: `date`, `time`, `date-time`, `money`, `number`, `percent`. They appear in `schema.json`
|
|
24
|
+
(`"x-email-kit": { "formatted": "money" }`) and as a comment on the generated data type.
|
|
25
|
+
|
|
26
|
+
Use the same locale you pass to `render(data, { locale })`. `email-kit check` flags currency
|
|
27
|
+
symbols written next to an argument (`${total}`) and dates assembled from parts
|
|
28
|
+
(`{day}/{month}/{year}`) as `i18n.intl-format`.
|
|
29
|
+
|
|
30
|
+
## JavaScript and TypeScript
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
const locale = "de-DE"
|
|
34
|
+
const timeZone = "Europe/Berlin" // the recipient's, not the server's
|
|
35
|
+
|
|
36
|
+
const orderDate = new Intl.DateTimeFormat(locale, { dateStyle: "long", timeZone }).format(order.createdAt)
|
|
37
|
+
// "30. Oktober 2026"
|
|
38
|
+
|
|
39
|
+
const total = new Intl.NumberFormat(locale, { style: "currency", currency: "EUR" }).format(43.6)
|
|
40
|
+
// "43,60 €" (Intl uses each currency's minor units: JPY has none)
|
|
41
|
+
|
|
42
|
+
const savings = new Intl.NumberFormat(locale, { style: "percent" }).format(0.1)
|
|
43
|
+
// "10 %"
|
|
44
|
+
|
|
45
|
+
emails.receipt.render({ orderDate, total, savings, … }, { locale })
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Amounts stored in minor units (cents) need dividing first; for exact decimal arithmetic, format
|
|
49
|
+
from a string or a decimal library rather than a float you computed.
|
|
50
|
+
|
|
51
|
+
## Python
|
|
52
|
+
|
|
53
|
+
[Babel](https://babel.pocoo.org/) formats with CLDR data. It expects `de_DE`, so convert BCP 47 tags:
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
from zoneinfo import ZoneInfo
|
|
57
|
+
from babel.dates import format_date
|
|
58
|
+
from babel.numbers import format_currency, format_percent
|
|
59
|
+
|
|
60
|
+
locale = "de-DE".replace("-", "_")
|
|
61
|
+
order_date = format_date(created_at.astimezone(ZoneInfo("Europe/Berlin")), format="long", locale=locale)
|
|
62
|
+
total = format_currency(43.60, "EUR", locale=locale)
|
|
63
|
+
savings = format_percent(0.1, locale=locale)
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Go
|
|
67
|
+
|
|
68
|
+
`golang.org/x/text` formats numbers for a locale (`message.NewPrinter(language.German)` with
|
|
69
|
+
`number.Decimal`, and `currency` for amounts). Neither it nor the standard library formats dates
|
|
70
|
+
by locale: use a CLDR-based package, or format dates in a service that has CLDR data. Check its
|
|
71
|
+
output against the JavaScript or Python result for your locales, since email-kit can't.
|
|
72
|
+
|
|
73
|
+
## Time zones
|
|
74
|
+
|
|
75
|
+
A date-time without the recipient's time zone is wrong for most of them. Store the zone with the
|
|
76
|
+
account, format in it, and name it when it matters ("14:05 CET"). Security alerts must say when
|
|
77
|
+
something happened in a zone the reader recognises.
|