@email-kit/cli 1.0.1 → 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.
@@ -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.