@email-kit/core 0.0.0-stage → 1.0.1
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/LICENSE +21 -0
- package/README.md +124 -2
- package/dist/context-Bzokejt6.d.ts +321 -0
- package/dist/index.d.ts +395 -0
- package/dist/index.js +181 -0
- package/dist/internal.d.ts +44 -0
- package/dist/internal.js +427 -0
- package/dist/jsx-dev-runtime.d.ts +7 -0
- package/dist/jsx-dev-runtime.js +8 -0
- package/dist/jsx-runtime-7xxLVv1A.js +104 -0
- package/dist/jsx-runtime-D7Dhqeps.d.ts +52 -0
- package/dist/jsx-runtime.d.ts +3 -0
- package/dist/jsx-runtime.js +1 -0
- package/dist/nodes-BD_OGvYC.js +270 -0
- package/dist/role-Mpv6ubQ3.d.ts +250 -0
- package/dist/scope-CYu-Vhsw.js +75 -0
- package/package.json +73 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 email-kit contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,125 @@
|
|
|
1
|
-
#
|
|
1
|
+
# email-kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Type-safe email templates for TypeScript backends. Write the emails your app sends in TSX with
|
|
4
|
+
themed, email-safe components. `email-kit compile` turns them into a small typed module your server
|
|
5
|
+
imports, and `email-kit check` checks every one for email clients, dark mode, accessibility and
|
|
6
|
+
copy.
|
|
7
|
+
|
|
8
|
+
**[Documentation](https://email-kit.dev)** · [Getting started](https://email-kit.dev/guide/getting-started/) · [GitHub](https://github.com/email-kit/email-kit)
|
|
9
|
+
|
|
10
|
+
## Get started
|
|
11
|
+
|
|
12
|
+
In the project that sends email (in a monorepo, the app's folder), run:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npm create email-kit
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
It detects your package manager, TypeScript setup and framework, installs the packages below, adds
|
|
19
|
+
a config and a welcome template, and compiles once. It asks before changing any file you already
|
|
20
|
+
have; `npm create email-kit -- --yes` accepts every default, as in CI. `npx @email-kit/cli init`
|
|
21
|
+
does the same.
|
|
22
|
+
|
|
23
|
+
Then render the welcome email from your server, with the import `init` prints for your project:
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { emails } from "./email-kit"
|
|
27
|
+
|
|
28
|
+
const { subject, html, text } = emails.welcome.render({
|
|
29
|
+
name: "Ada",
|
|
30
|
+
plan: "pro",
|
|
31
|
+
startUrl: "https://example.com/start",
|
|
32
|
+
})
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
email-kit doesn't send email: hand `subject`, `html` and `text` to any provider's API.
|
|
36
|
+
|
|
37
|
+
While you work:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
npx email-kit compile # after changing a template or message; --watch keeps it running
|
|
41
|
+
npx email-kit check # the checks; exits 1 on errors, for CI
|
|
42
|
+
npx email-kit new <id> # another template, with messages in every locale
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The [getting started guide](https://email-kit.dev/guide/getting-started/) goes through it step by
|
|
46
|
+
step, and [your first email](https://email-kit.dev/guide/first-email/) builds one from scratch.
|
|
47
|
+
|
|
48
|
+
## A template
|
|
49
|
+
|
|
50
|
+
Each template is a folder with `template.tsx` and a `messages.<locale>.json` per language:
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
import { Button, Heading, Text } from "@email-kit/components"
|
|
54
|
+
import { defineEmail, url } from "@email-kit/core"
|
|
55
|
+
import { z } from "zod"
|
|
56
|
+
|
|
57
|
+
export default defineEmail({
|
|
58
|
+
id: "welcome",
|
|
59
|
+
purpose: "transactional",
|
|
60
|
+
schema: z.object({ name: z.string().min(1), startUrl: z.string().meta(url) }),
|
|
61
|
+
subject: (data, t) => t("subject", { name: data.name }),
|
|
62
|
+
fixtures: { default: { name: "Ada", startUrl: "https://example.com/start" } },
|
|
63
|
+
component: ({ data, t }) => (
|
|
64
|
+
<>
|
|
65
|
+
<Heading>{t("heading", { name: data.name })}</Heading>
|
|
66
|
+
<Text>{t("body")}</Text>
|
|
67
|
+
<Button href={data.startUrl}>{t("cta")}</Button>
|
|
68
|
+
</>
|
|
69
|
+
),
|
|
70
|
+
})
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Templates run when you compile, not when you send: your server imports the generated module, which
|
|
74
|
+
needs only `@email-kit/runtime`.
|
|
75
|
+
|
|
76
|
+
## The packages
|
|
77
|
+
|
|
78
|
+
They work together and are released together: install the same version of each.
|
|
79
|
+
`npm create email-kit` installs them for you.
|
|
80
|
+
|
|
81
|
+
| Package | What it is | Install as |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| [`create-email-kit`](https://www.npmjs.com/package/create-email-kit) | `npm create email-kit`: runs `email-kit init` in the folder you're in | not installed |
|
|
84
|
+
| [`@email-kit/cli`](https://www.npmjs.com/package/@email-kit/cli) | The `email-kit` command: `init`, `new`, `compile`, `check` and `tokens` | devDependency |
|
|
85
|
+
| [`@email-kit/core`](https://www.npmjs.com/package/@email-kit/core) | What templates are written with: `defineEmail`, the JSX runtime, `If`/`Each`/`Unless`, field markers (`url`, `secret`, `formatted`), `defineConfig` and `defineCheck` | devDependency |
|
|
86
|
+
| [`@email-kit/components`](https://www.npmjs.com/package/@email-kit/components) | Email-safe components themed from your shadcn CSS or design tokens: `Text`, `Heading`, `Link`, `Button`, `Image`, `Divider`, `Spacer`, `Section`, `List`, `KeyValue`, `Callout`, `OtpCode`, `DataTable`, `LineItems` and `Footer` | devDependency |
|
|
87
|
+
| [`@email-kit/runtime`](https://www.npmjs.com/package/@email-kit/runtime) | Renders the compiled emails. The only one your app needs when it runs | **dependency** |
|
|
88
|
+
|
|
89
|
+
### The runtime
|
|
90
|
+
|
|
91
|
+
`@email-kit/runtime` has no dependencies and uses only web-standard APIs, so it runs in Node 22+,
|
|
92
|
+
Bun, Deno, Cloudflare Workers, AWS Lambda and Next.js server code. You don't import it yourself:
|
|
93
|
+
the generated module does, and only the entry points your templates use, from about 1.4 KB to 3 KB
|
|
94
|
+
min+gzip:
|
|
95
|
+
|
|
96
|
+
| Entry point | Imported when |
|
|
97
|
+
|---|---|
|
|
98
|
+
| `@email-kit/runtime` | always |
|
|
99
|
+
| `@email-kit/runtime/validate` | `validate` is on (the default) |
|
|
100
|
+
| `@email-kit/runtime/plural` | a message has a plural or a select |
|
|
101
|
+
| `@email-kit/runtime/locale` | the project compiles more than one locale |
|
|
102
|
+
| `@email-kit/runtime/context` | the config has sender values passed at send time |
|
|
103
|
+
|
|
104
|
+
Rendering problems throw an `EmailRenderError` with a `code`; see the
|
|
105
|
+
[error reference](https://email-kit.dev/reference/errors/). A module compiled by another version of
|
|
106
|
+
the CLI fails with `incompatible-module` rather than rendering wrong.
|
|
107
|
+
|
|
108
|
+
## Status
|
|
109
|
+
|
|
110
|
+
**1.0.** Stable for transactional email; breaking changes come only in a major release. Not yet:
|
|
111
|
+
marketing email (unsubscribe links, multi-column layouts), testing in real email clients (classic
|
|
112
|
+
Outlook especially), and the preview studio.
|
|
113
|
+
|
|
114
|
+
## More
|
|
115
|
+
|
|
116
|
+
- [Guide](https://email-kit.dev/guide/): templates, components, messages and locales, theme and dark
|
|
117
|
+
mode, checks and CI, rendering and sending.
|
|
118
|
+
- Reference: [CLI](https://email-kit.dev/reference/cli/),
|
|
119
|
+
[configuration](https://email-kit.dev/reference/configuration/),
|
|
120
|
+
[checks](https://email-kit.dev/reference/checks/), [errors](https://email-kit.dev/reference/errors/).
|
|
121
|
+
- [Issues](https://github.com/email-kit/email-kit/issues) and
|
|
122
|
+
[changelog](https://github.com/email-kit/email-kit/blob/main/packages/cli/CHANGELOG.md).
|
|
123
|
+
|
|
124
|
+
The CLI requires Node.js 22.12 or later. MIT licensed; the CLI's third-party notices are in its
|
|
125
|
+
`THIRD_PARTY_NOTICES.md`.
|
|
@@ -0,0 +1,321 @@
|
|
|
1
|
+
import { A as TypeStyle, D as ThemeRole, T as FontStackName, d as Data, g as TextValue, k as TypeStep, l as Child, m as Placeholder, x as IrNode } from "./role-Mpv6ubQ3.js";
|
|
2
|
+
/**
|
|
3
|
+
* Facts about who sends the email, set under `sender` in email-kit.config.ts. Each one is fixed
|
|
4
|
+
* text, or a placeholder when the config marks it `{ runtime: true }` and your backend passes it
|
|
5
|
+
* to `createEmails()`.
|
|
6
|
+
*/
|
|
7
|
+
interface Sender {
|
|
8
|
+
/** Your product's name, such as `"Acme"`. */
|
|
9
|
+
readonly productName: TextValue;
|
|
10
|
+
/** The name your emails come from, such as `"Acme Support"`. */
|
|
11
|
+
readonly name: TextValue;
|
|
12
|
+
/** Your organisation's registered name, such as `"Acme Inc."`. */
|
|
13
|
+
readonly legalName: TextValue;
|
|
14
|
+
/** Your postal address. Marketing and consent-request emails must show it. */
|
|
15
|
+
readonly postalAddress: TextValue;
|
|
16
|
+
/** The https URL of your privacy policy. */
|
|
17
|
+
readonly privacyUrl: TextValue;
|
|
18
|
+
/** The https URL of your help centre. */
|
|
19
|
+
readonly helpUrl: TextValue;
|
|
20
|
+
/** The email address recipients can write to for help. */
|
|
21
|
+
readonly supportEmail: TextValue;
|
|
22
|
+
/** The https URL of your website. */
|
|
23
|
+
readonly siteUrl: TextValue;
|
|
24
|
+
}
|
|
25
|
+
/** The name of one sender value, such as `"productName"`. */
|
|
26
|
+
type SenderKey = keyof Sender;
|
|
27
|
+
/** Every sender key. */
|
|
28
|
+
declare const SENDER_KEYS: readonly SenderKey[];
|
|
29
|
+
/** The top-level data key for the values `render()` adds, such as runtime sender values. */
|
|
30
|
+
declare const RESERVED_KEY = "_ek";
|
|
31
|
+
/** The sender values from the config. */
|
|
32
|
+
interface SenderValues {
|
|
33
|
+
/** The values set as fixed text. */
|
|
34
|
+
readonly constants: Readonly<Partial<Record<SenderKey, string>>>;
|
|
35
|
+
/** The keys set to `{ runtime: true }`, which the backend passes when it sends. */
|
|
36
|
+
readonly runtime: readonly SenderKey[];
|
|
37
|
+
}
|
|
38
|
+
/** A message resolved for one locale: text with placeholders. */
|
|
39
|
+
type Message = IrNode;
|
|
40
|
+
/**
|
|
41
|
+
* A value for a message parameter: text, a number, a data placeholder, or another message from
|
|
42
|
+
* `t()`. A plural needs a number or a number field. A select needs text or a field with fixed
|
|
43
|
+
* values, such as `z.enum([…])`.
|
|
44
|
+
*/
|
|
45
|
+
type MessageParam = string | number | Placeholder<string> | Placeholder<number> | Message;
|
|
46
|
+
/**
|
|
47
|
+
* Looks up a message for the locale being compiled and fills in its parameters. Throws if the
|
|
48
|
+
* message or a parameter is missing, or if a parameter isn't used.
|
|
49
|
+
*
|
|
50
|
+
* @example
|
|
51
|
+
* ```tsx
|
|
52
|
+
* t("cart.items", { count: data.itemCount })
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
55
|
+
type Translate = (key: string, params?: Readonly<Record<string, MessageParam>>) => Message;
|
|
56
|
+
/** A locale's messages for one template, by key, written as ICU messages. */
|
|
57
|
+
type Messages = Readonly<Record<string, string>>;
|
|
58
|
+
/**
|
|
59
|
+
* Each template's message keys and their parameters, filled in by the `messages.d.ts` that
|
|
60
|
+
* `email-kit compile` writes from the default locale. Until then it's empty and `t()` accepts any
|
|
61
|
+
* key.
|
|
62
|
+
*/
|
|
63
|
+
interface MessageRegistry {}
|
|
64
|
+
/** `t()` for one template: its keys, and each message's parameters with their types. */
|
|
65
|
+
type TypedTranslate<Id extends string> = Id extends keyof MessageRegistry ? <Key extends keyof MessageRegistry[Id] & string>(key: Key, ...params: ParamsArgument<MessageRegistry[Id][Key]>) => Message : Translate;
|
|
66
|
+
type ParamsArgument<P> = [keyof P] extends [never] ? [params?: Record<string, never>] : [params: P];
|
|
67
|
+
/** The locale's CLDR plural rules, from the compiler. */
|
|
68
|
+
interface PluralSupport {
|
|
69
|
+
/** The categories the locale uses, such as ["one", "other"] */
|
|
70
|
+
readonly categories: readonly string[];
|
|
71
|
+
category(n: number): string;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The shared interface that schema libraries such as Zod, Valibot and ArkType implement, so
|
|
75
|
+
* `defineEmail()` accepts a schema from any of them. Standard Schema v1, from
|
|
76
|
+
* https://standardschema.dev (MIT), copied in so that @email-kit/core has no dependencies.
|
|
77
|
+
*/
|
|
78
|
+
interface StandardSchemaV1<Input = unknown, Output = Input> {
|
|
79
|
+
readonly "~standard": StandardSchemaV1.Props<Input, Output>;
|
|
80
|
+
}
|
|
81
|
+
declare namespace StandardSchemaV1 {
|
|
82
|
+
interface Props<Input = unknown, Output = Input> {
|
|
83
|
+
readonly version: 1;
|
|
84
|
+
readonly vendor: string;
|
|
85
|
+
readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
|
|
86
|
+
readonly types?: Types<Input, Output> | undefined;
|
|
87
|
+
}
|
|
88
|
+
type Result<Output> = SuccessResult<Output> | FailureResult;
|
|
89
|
+
interface SuccessResult<Output> {
|
|
90
|
+
readonly value: Output;
|
|
91
|
+
readonly issues?: undefined;
|
|
92
|
+
}
|
|
93
|
+
interface FailureResult {
|
|
94
|
+
readonly issues: readonly Issue[];
|
|
95
|
+
}
|
|
96
|
+
interface Issue {
|
|
97
|
+
readonly message: string;
|
|
98
|
+
readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
|
|
99
|
+
}
|
|
100
|
+
interface PathSegment {
|
|
101
|
+
readonly key: PropertyKey;
|
|
102
|
+
}
|
|
103
|
+
interface Types<Input = unknown, Output = Input> {
|
|
104
|
+
readonly input: Input;
|
|
105
|
+
readonly output: Output;
|
|
106
|
+
}
|
|
107
|
+
type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
|
|
108
|
+
type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Why the email is sent. `email-kit check` uses it to decide what the footer must contain.
|
|
112
|
+
*
|
|
113
|
+
* - `"transactional"`: something the recipient did or needs to know, such as a receipt or a
|
|
114
|
+
* password reset.
|
|
115
|
+
* - `"marketing"`: promotional content of any kind. The footer must show your postal address.
|
|
116
|
+
* - `"consent-request"`: asks the recipient to agree to receive email, such as a newsletter
|
|
117
|
+
* sign-up confirmation. The footer must show your postal address.
|
|
118
|
+
*/
|
|
119
|
+
type Purpose = "transactional" | "marketing" | "consent-request";
|
|
120
|
+
/** What a template's `component` receives. */
|
|
121
|
+
interface EmailProps<T, Id extends string = string> {
|
|
122
|
+
/**
|
|
123
|
+
* The email's data, shaped like `schema`. Its fields are placeholders that are filled in when
|
|
124
|
+
* the email is rendered: put them in your JSX, and use `<Each>` and `<If>` to loop or branch
|
|
125
|
+
* on them.
|
|
126
|
+
*/
|
|
127
|
+
readonly data: Data<T>;
|
|
128
|
+
/**
|
|
129
|
+
* Looks up a message for this template in the locale being compiled:
|
|
130
|
+
* `t("greeting", { name: data.name })`. Keys and parameters are typed after the first
|
|
131
|
+
* `email-kit compile`.
|
|
132
|
+
*/
|
|
133
|
+
readonly t: TypedTranslate<Id>;
|
|
134
|
+
/** The locale being compiled, such as `"en"` or `"pt-BR"`. */
|
|
135
|
+
readonly locale: string;
|
|
136
|
+
/**
|
|
137
|
+
* Facts about who sends the email, from email-kit.config.ts: product name, postal address, site
|
|
138
|
+
* URL…
|
|
139
|
+
*/
|
|
140
|
+
readonly sender: Sender;
|
|
141
|
+
}
|
|
142
|
+
/** An email template made with `defineEmail()`. */
|
|
143
|
+
interface EmailDefinition<T = unknown> {
|
|
144
|
+
readonly id: string;
|
|
145
|
+
/** Why the email is sent: `"transactional"`, `"marketing"` or `"consent-request"`. */
|
|
146
|
+
readonly purpose: Purpose;
|
|
147
|
+
readonly schema: StandardSchemaV1<unknown, T>;
|
|
148
|
+
readonly subject: (data: Data<T>, t: Translate, sender: Sender) => Child;
|
|
149
|
+
readonly preheader?: (data: Data<T>, t: Translate, sender: Sender) => Child;
|
|
150
|
+
/** Named sample data, used for previews and checks. */
|
|
151
|
+
readonly fixtures: Readonly<Record<string, T>>;
|
|
152
|
+
readonly component: (props: EmailProps<T>) => Child;
|
|
153
|
+
}
|
|
154
|
+
/** What `defineEmail()` takes. */
|
|
155
|
+
type EmailDefinitionInput<S extends StandardSchemaV1, Id extends string = string> = Omit<EmailDefinition<StandardSchemaV1.InferOutput<S>>, "id" | "schema" | "subject" | "preheader" | "component"> & {
|
|
156
|
+
/**
|
|
157
|
+
* A unique name in lowercase words joined by hyphens, such as `"order-confirmation"`. It must be
|
|
158
|
+
* the name of the template's folder. Your app sends it as `emails.orderConfirmation`.
|
|
159
|
+
*/
|
|
160
|
+
readonly id: Id;
|
|
161
|
+
/** The shape of the email's data, from Zod, Valibot, ArkType or any Standard Schema library. */
|
|
162
|
+
readonly schema: S;
|
|
163
|
+
/** Returns the subject line. */
|
|
164
|
+
readonly subject: (data: Data<StandardSchemaV1.InferOutput<S>>, t: TypedTranslate<Id>, sender: Sender) => Child;
|
|
165
|
+
/** Returns the short preview text that inboxes show after the subject. */
|
|
166
|
+
readonly preheader?: (data: Data<StandardSchemaV1.InferOutput<S>>, t: TypedTranslate<Id>, sender: Sender) => Child;
|
|
167
|
+
/** Returns the email's content as JSX. */
|
|
168
|
+
readonly component: (props: EmailProps<StandardSchemaV1.InferOutput<S>, Id>) => Child;
|
|
169
|
+
};
|
|
170
|
+
/** Whether a string is a template id: lowercase words joined by hyphens, like `order-shipped`. */
|
|
171
|
+
declare function isTemplateId(id: string): boolean;
|
|
172
|
+
/**
|
|
173
|
+
* Defines an email template. Export it as the default export of `<id>/template.tsx` in the
|
|
174
|
+
* email-kit folder; its messages sit beside it as `messages.<locale>.json`.
|
|
175
|
+
*
|
|
176
|
+
* `schema` (Zod, Valibot, ArkType or any Standard Schema library) describes the data the email
|
|
177
|
+
* needs. It types `data` in the template and the `fixtures`, and the generated `render()`
|
|
178
|
+
* checks data against it.
|
|
179
|
+
*
|
|
180
|
+
* The template runs once, while `email-kit compile` runs, not once per email sent: `data` holds
|
|
181
|
+
* placeholders, not real values.
|
|
182
|
+
*
|
|
183
|
+
* @param definition.id - A unique name in lowercase words joined by hyphens, such as
|
|
184
|
+
* `"order-confirmation"`: the name of the template's folder. Your app sends it as
|
|
185
|
+
* `emails.orderConfirmation`.
|
|
186
|
+
* @param definition.purpose - Why the email is sent: `"transactional"`, `"marketing"` or
|
|
187
|
+
* `"consent-request"`.
|
|
188
|
+
* @param definition.schema - The shape of the email's data.
|
|
189
|
+
* @param definition.subject - Returns the subject line.
|
|
190
|
+
* @param definition.preheader - Returns the short preview text that inboxes show after the
|
|
191
|
+
* subject. Optional.
|
|
192
|
+
* @param definition.fixtures - Named sample data, used for previews and checks.
|
|
193
|
+
* @param definition.component - Returns the email's content as JSX.
|
|
194
|
+
* @throws {EmailKitError} If `id` isn't lowercase words joined by hyphens, or `purpose` is
|
|
195
|
+
* missing or unknown.
|
|
196
|
+
*
|
|
197
|
+
* @example
|
|
198
|
+
* ```tsx
|
|
199
|
+
* export default defineEmail({
|
|
200
|
+
* id: "welcome",
|
|
201
|
+
* purpose: "transactional",
|
|
202
|
+
* schema: z.object({ name: z.string() }),
|
|
203
|
+
* subject: (data, t) => t("subject", { name: data.name }),
|
|
204
|
+
* fixtures: { default: { name: "Ada" } },
|
|
205
|
+
* component: ({ data, t }) => <p>{t("greeting", { name: data.name })}</p>,
|
|
206
|
+
* })
|
|
207
|
+
* ```
|
|
208
|
+
*/
|
|
209
|
+
declare function defineEmail<S extends StandardSchemaV1, const Id extends string = string>(definition: EmailDefinitionInput<S, Id>): EmailDefinition<StandardSchemaV1.InferOutput<S>>;
|
|
210
|
+
/** Whether a value was made with `defineEmail()`, even by another installed copy of email-kit. */
|
|
211
|
+
declare function isEmailDefinition(value: unknown): value is EmailDefinition;
|
|
212
|
+
/**
|
|
213
|
+
* The error email-kit throws for a mistake in a template or config, such as an invalid template
|
|
214
|
+
* id or a list rendered without `<Each>`. `message` says what to fix.
|
|
215
|
+
*/
|
|
216
|
+
declare class EmailKitError extends Error {
|
|
217
|
+
/** A short, stable name for the kind of mistake, such as `"invalid-id"`. */
|
|
218
|
+
readonly code: string;
|
|
219
|
+
constructor(code: string, message: string);
|
|
220
|
+
}
|
|
221
|
+
/** Whether a value is an `EmailKitError`, even one from another installed copy of email-kit. */
|
|
222
|
+
declare function isEmailKitError(value: unknown): value is EmailKitError;
|
|
223
|
+
/**
|
|
224
|
+
* The project's theme with every value filled in: colours, fonts, spacing, corner radius and
|
|
225
|
+
* component settings. Read it with `useTheme()`. All sizes are in pixels.
|
|
226
|
+
*/
|
|
227
|
+
interface ThemeContext {
|
|
228
|
+
/** The light colour of each role, as a CSS colour. To colour a style, use `role()` instead. */
|
|
229
|
+
readonly roles: Readonly<Record<ThemeRole, string>>;
|
|
230
|
+
readonly typography: {
|
|
231
|
+
/**
|
|
232
|
+
* The font families of each stack, and `msoFallback`: its last named family. Classic Outlook
|
|
233
|
+
* can't fall back through a list, so all its text uses the `msoFallback` of the `body` step's
|
|
234
|
+
* stack.
|
|
235
|
+
*/
|
|
236
|
+
readonly stacks: Readonly<Record<FontStackName, {
|
|
237
|
+
readonly families: readonly string[];
|
|
238
|
+
readonly msoFallback: string;
|
|
239
|
+
}>>;
|
|
240
|
+
/** The style of each step of the type scale. */
|
|
241
|
+
readonly scale: Readonly<Record<TypeStep, TypeStyle>>;
|
|
242
|
+
};
|
|
243
|
+
readonly space: {
|
|
244
|
+
/** Side padding on small screens. */
|
|
245
|
+
readonly gutterMobile: number;
|
|
246
|
+
/** Side padding on large screens. */
|
|
247
|
+
readonly gutterDesktop: number;
|
|
248
|
+
/** Gaps between stacked blocks, such as paragraphs and headings. */
|
|
249
|
+
readonly stack: {
|
|
250
|
+
readonly sm: number;
|
|
251
|
+
readonly md: number;
|
|
252
|
+
readonly lg: number;
|
|
253
|
+
};
|
|
254
|
+
/** The gap between sections. */
|
|
255
|
+
readonly section: number;
|
|
256
|
+
};
|
|
257
|
+
/**
|
|
258
|
+
* Corner radii: a scale from `none` to `xl`, `full` for pill shapes, and the radius for each
|
|
259
|
+
* kind of element (`button`, `card`, `badge`, `code`, `image`).
|
|
260
|
+
*/
|
|
261
|
+
readonly radius: Readonly<Record<"none" | "sm" | "md" | "lg" | "xl" | "full" | "button" | "card" | "badge" | "code" | "image", number>>;
|
|
262
|
+
readonly borderWidth: {
|
|
263
|
+
readonly hairline: number;
|
|
264
|
+
readonly strong: number;
|
|
265
|
+
};
|
|
266
|
+
readonly layout: {
|
|
267
|
+
/** The email's content width. */
|
|
268
|
+
readonly container: number;
|
|
269
|
+
};
|
|
270
|
+
readonly components: {
|
|
271
|
+
/**
|
|
272
|
+
* Each button size's minimum height, side padding (`padX`), top and bottom padding (`padY`)
|
|
273
|
+
* and text style.
|
|
274
|
+
*/
|
|
275
|
+
readonly button: Readonly<Record<"sm" | "md" | "lg", {
|
|
276
|
+
readonly minHeight: number;
|
|
277
|
+
readonly padX: number;
|
|
278
|
+
readonly padY: number;
|
|
279
|
+
readonly font: TypeStep;
|
|
280
|
+
}>>;
|
|
281
|
+
/** Whether links are underlined. */
|
|
282
|
+
readonly link: {
|
|
283
|
+
readonly underline: boolean;
|
|
284
|
+
};
|
|
285
|
+
/** The text style and background of one-time codes. */
|
|
286
|
+
readonly otp: {
|
|
287
|
+
readonly font: TypeStep;
|
|
288
|
+
readonly surface: "codeSurface";
|
|
289
|
+
};
|
|
290
|
+
};
|
|
291
|
+
}
|
|
292
|
+
/**
|
|
293
|
+
* Returns the project's theme: colours, fonts, spacing, corner radius and component settings,
|
|
294
|
+
* with defaults for anything email-kit.config.ts leaves out. Use it to build components that
|
|
295
|
+
* match the theme.
|
|
296
|
+
*
|
|
297
|
+
* Works only inside a template or a component, while the template compiles.
|
|
298
|
+
*
|
|
299
|
+
* @throws {EmailKitError} If called outside a template.
|
|
300
|
+
*
|
|
301
|
+
* @example
|
|
302
|
+
* ```tsx
|
|
303
|
+
* function Spacer() {
|
|
304
|
+
* const { space } = useTheme()
|
|
305
|
+
* return <div style={{ height: `${space.section}px` }} />
|
|
306
|
+
* }
|
|
307
|
+
* ```
|
|
308
|
+
*/
|
|
309
|
+
declare function useTheme(): ThemeContext;
|
|
310
|
+
/**
|
|
311
|
+
* Returns the writing direction of the locale being compiled: `"rtl"` for right-to-left
|
|
312
|
+
* languages such as Arabic and Hebrew, otherwise `"ltr"`. Use it to mirror layouts, such as
|
|
313
|
+
* which side an icon or border goes on.
|
|
314
|
+
*
|
|
315
|
+
* @example
|
|
316
|
+
* ```tsx
|
|
317
|
+
* const side = useDirection() === "rtl" ? "right" : "left"
|
|
318
|
+
* ```
|
|
319
|
+
*/
|
|
320
|
+
declare function useDirection(): "ltr" | "rtl";
|
|
321
|
+
export { Sender as C, SENDER_KEYS as S, SenderValues as T, Messages as _, isEmailKitError as a, TypedTranslate as b, EmailProps as c, isEmailDefinition as d, isTemplateId as f, MessageRegistry as g, MessageParam as h, EmailKitError as i, Purpose as l, Message as m, useDirection as n, EmailDefinition as o, StandardSchemaV1 as p, useTheme as r, EmailDefinitionInput as s, ThemeContext as t, defineEmail as u, PluralSupport as v, SenderKey as w, RESERVED_KEY as x, Translate as y };
|