@nxgt/mail-presets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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

@@ -0,0 +1,222 @@
+# @nxgt/mail-presets
+
+Nine ready transactional e-mails for a [Maizzle](https://maizzle.com) 6
+project: `verify-email`, `reset-password`, `password-changed`,
+`email-changed`, `sign-in-code`, `magic-link`, `new-sign-in`, `welcome` and
+`invitation`, written with `@nxgt/mail-ui`'s components and translated in
+`en` and `fr`. Your project builds them with its own brand and theme, next to
+its own templates, and replaces any of them — a whole template, or one
+message.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { i18n } from '@nxgt/mail-i18n';
+import { presets } from '@nxgt/mail-presets';
+import { ui, uiCatalogues } from '@nxgt/mail-ui';
+
+const mails = presets();
+
+export default defineMailConfig({
+	plugins: [
+		ui({ brand: { name: 'Acme', url: 'https://acme.example' } }),
+		i18n({
+			locales: ['en', 'fr'],
+			catalogues: [uiCatalogues, mails.catalogues],
+			templates: [mails.templates],
+		}),
+	],
+});
+```
+
+`maizzle build` then writes `dist/en/verify-email.html`,
+`dist/fr/verify-email.html`… each with its `.txt`, and every e-mail's
+placeholders and subjects in `dist/mail-manifest.json`. See what they look
+like in the [built samples](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-presets/samples/README.md).
+
+Each preset as it arrives, with the brand `Acme`, the default theme and example
+values in its placeholders. Click one for full size; `fr` is the French build.
+
+<table>
+<tr><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/verify-email.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/verify-email.png" width="260" alt="The verify-email e-mail, in English"></a><br><code>verify-email</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/verify-email.png">fr</a></td><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/reset-password.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/reset-password.png" width="260" alt="The reset-password e-mail, in English"></a><br><code>reset-password</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/reset-password.png">fr</a></td><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/password-changed.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/password-changed.png" width="260" alt="The password-changed e-mail, in English"></a><br><code>password-changed</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/password-changed.png">fr</a></td></tr>
+<tr><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/email-changed.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/email-changed.png" width="260" alt="The email-changed e-mail, in English"></a><br><code>email-changed</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/email-changed.png">fr</a></td><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/sign-in-code.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/sign-in-code.png" width="260" alt="The sign-in-code e-mail, in English"></a><br><code>sign-in-code</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/sign-in-code.png">fr</a></td><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/magic-link.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/magic-link.png" width="260" alt="The magic-link e-mail, in English"></a><br><code>magic-link</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/magic-link.png">fr</a></td></tr>
+<tr><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/new-sign-in.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/new-sign-in.png" width="260" alt="The new-sign-in e-mail, in English"></a><br><code>new-sign-in</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/new-sign-in.png">fr</a></td><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/welcome.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/welcome.png" width="260" alt="The welcome e-mail, in English"></a><br><code>welcome</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/welcome.png">fr</a></td><td valign="top"><a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/invitation.png"><img src="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/en/invitation.png" width="260" alt="The invitation e-mail, in English"></a><br><code>invitation</code> · <a href="https://raw.githubusercontent.com/softistx/nxgt-mail/refs/tags/@nxgt/mail-presets@0.1.0/packages/mail-presets/previews/fr/invitation.png">fr</a></td></tr>
+</table>
+
+> **0.x.** A minor version may still change the surface; the changelog says how.
+
+## Install
+
+```sh
+bun add @nxgt/mail-presets @nxgt/mail-i18n @nxgt/mail-ui @nxgt/mail-config @maizzle/framework @maizzle/tailwindcss vue
+```
+
+Peers, all required:
+
+- `@nxgt/mail-i18n` — builds the templates once per locale, from the folder
+  `presets()` names, with the messages it gives.
+- `@nxgt/mail-ui` — the templates are written with its `Nx*` components, and
+  use its shared `common.*` messages.
+- `@maizzle/framework` (`^6.1.7`) — Maizzle itself. `@nxgt/mail-config` and
+  `@maizzle/tailwindcss` (`^1.5.6`) are what `@nxgt/mail-ui` needs, the
+  latter as a direct dependency of your project (see its
+  [Setup](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-ui/README.md#setup)).
+- `vue` (`^3.5`) — the templates are Vue single-file components.
+- `typescript` (6). Bundler resolution (`"moduleResolution": "bundler"`) is
+  what is supported and tested; `nodenext` is out of contract.
+
+Your project still has a `locales/<locale>.json` per locale, `{}` if it
+overrides nothing: `@nxgt/mail-i18n` requires it.
+
+## Exports
+
+| Export | What it is |
+| --- | --- |
+| `presets(options?)` | `{ templates, catalogues }` for `i18n({ templates, catalogues })`: every preset, or the ones in `only` |
+| `PRESETS` | The nine names, `['verify-email', 'reset-password', …]`, as a readonly tuple |
+| `PresetName` | One of them, as a type |
+| `presetCatalogues` | Every preset's messages, `{ en, fr }`, before `presets()` keeps the ones asked for; frozen, every group in it |
+| `TEMPLATES_DIR` | The absolute path of the package's `emails/` folder |
+| `Presets`, `PresetsOptions` | What `presets()` answers, and its options |
+
+## Usage
+
+### A few of them — `only`
+
+```ts
+import { presets } from '@nxgt/mail-presets';
+
+const mails = presets({ only: ['verify-email', 'reset-password', 'magic-link'] });
+// mails.templates  → { dir: '/…/@nxgt/mail-presets/emails', emails: ['verify-email', 'reset-password', 'magic-link'] }
+// mails.catalogues → { en, fr }, with presets.*, verifyEmail.*, resetPassword.*, magicLink.* only
+```
+
+Pass both to `i18n()` as above: only those three are built, beside your own
+templates. A wrong `only` is a bare `TypeError` when the config loads:
+`presets: only holds something that is not a preset — name one of
+verify-email, reset-password, …`. See [Wiring the presets](docs/guide/presets.md).
+
+### The e-mails
+
+Each one takes its values at send time as placeholders, listed in the
+manifest:
+
+| E-mail | Placeholders | Subject (`en`) |
+| --- | --- | --- |
+| `verify-email` | `link`, `name` | Confirm your e-mail address |
+| `reset-password` | `link`, `name` | Reset your password |
+| `password-changed` | `link`, `name` | Your password was changed |
+| `email-changed` | `link`, `name`, `newEmail` | Your e-mail address was changed |
+| `sign-in-code` | `code` | Your sign-in code: `{{ code }}` |
+| `magic-link` | `link` | Your sign-in link |
+| `new-sign-in` | `device`, `link`, `location`, `name`, `time` | New sign-in to your account |
+| `welcome` | `link`, `name` | Welcome, `{{ name }}` |
+| `invitation` | `inviter`, `link`, `organization` | `{{ inviter }}` invited you to join `{{ organization }}` |
+
+`link` is a URL in each of them: the sender fills it with an `http:` or `https:` URL.
+See [The e-mails](docs/guide/emails.md) for what each one says, in both
+locales, and every message key.
+
+### Replacing a template
+
+```vue
+<!-- emails/welcome.vue — built instead of the package's welcome -->
+<template>
+  <NxLayout :preheader="t('welcome.preheader')">
+    <NxTypography variant="headline-small">{{ t('welcome.title', { brand: brand.name }) }}</NxTypography>
+    <NxTypography>{{ t('common.greeting', { name: placeholder('name') }) }}</NxTypography>
+    <NxButton :href="placeholder('link')">{{ t('welcome.action') }}</NxButton>
+    <NxTypography variant="caption">{{ t('welcome.help') }}</NxTypography>
+  </NxLayout>
+</template>
+```
+
+A template in your `emails/` with the name of a preset replaces it. It keeps
+the preset's messages, so it only writes the keys it adds (`welcome.help`
+here) in your `locales/<locale>.json`. To start from the package's, copy it
+from `TEMPLATES_DIR`.
+
+### Overriding a message
+
+```json
+// locales/en.json — every other message stays the package's
+{ "verifyEmail": { "action": "Yes, this is my address" } }
+```
+
+Your catalogues go over the package's, key by key, in each locale. The
+`fr` button stays `Confirmer mon adresse`. See
+[Wiring the presets](docs/guide/presets.md#overriding-a-message).
+
+## Traps
+
+**Give `i18n()` both catalogues.** The templates use `@nxgt/mail-ui`'s
+`common.*` messages: without `uiCatalogues` the build fails with
+`calls t('common.footer.why'), which is not a key of the catalogues`, and
+without `mails.catalogues`, with `calls t('verifyEmail.preheader'), …`.
+
+```ts
+catalogues: [uiCatalogues, mails.catalogues],
+```
+
+**List `ui()` in `plugins`.** The templates are made of its `Nx*` components,
+installed under `node_modules`, where Maizzle resolves no tag: `ui()` resolves
+them, and without it the build fails with `i18n: en/verify-email.html is
+empty — a tag of its template resolved to no component; list the plugin that
+brings it, as ui()`.
+
+**Another locale writes the keys itself.** The presets have `en` and `fr`
+only: a project in `de` writes `common.*`, `presets.*` and the group of each
+preset it builds in `locales/de.json`, or the build fails with
+`i18n: de: presets.linkFallback is missing — en, the fallback locale, has it`.
+See [Another locale](docs/guide/presets.md#another-locale).
+
+**An `en` override keeps the template's arguments.** `en` is the fallback
+locale, and the template still passes `{brand}` to `verifyEmail.body`: an
+override without it fails with `passes {brand} to verifyEmail.body, which
+does not use it`. Replace the template to change what it passes.
+
+**`only` keeps only those presets' messages.** A template of yours named
+like a preset left out of `only` writes all of its messages itself.
+
+**Three subjects hold placeholders.** `welcome`, `sign-in-code` and
+`invitation` put `{{ name }}`, `{{ code }}`, `{{ inviter }}` and
+`{{ organization }}` in the subject: take the subject from the manifest and
+fill it like the body.
+
+**The samples are not in the tarball.** They are on GitHub, in
+[`samples/`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-presets/samples/README.md).
+
+## Type safety, counted
+
+**5 plausible mistakes, 5 refused** at compile time, each measured by a
+`@ts-expect-error` in
+[`test/types/refusals.ts`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-presets/test/types/refusals.ts)
+that fails the typecheck the moment it stops holding:
+
+1. A name in `only` that is not a preset (`'sign-in'`).
+2. `only` given one name rather than a list.
+3. `only` given an empty list, rather than left out for every preset.
+4. The list given as the options (`presets(['welcome'])`) rather than in
+   `only`.
+5. `i18n({ templates })` given the folder alone (`mails.templates.dir`)
+   rather than the whole `mails.templates`.
+
+The same file holds the calls that must keep compiling: a refusal that refuses
+the correct call is a bug.
+
+## Documentation
+
+- [The guides](docs/README.md) — one page per area, with every option,
+  e-mail, message and error.
+- [Troubleshooting](docs/troubleshooting.md) — an error message, its cause and
+  its fix.
+- [Roadmap](docs/roadmap.md) — what is next, and what is deliberately not
+  planned.
+- [Samples](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-presets/samples/README.md)
+  — every preset built in `en` and `fr`, with the brand `Acme`.
+- [Vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md)
+  — the words these pages use, defined once.
+
+## Licence
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@nxgt/mail-presets` — ready transactional e-mails for a Maizzle project
+ * built with `@nxgt/mail-ui` and `@nxgt/mail-i18n`: verify-email,
+ * reset-password, password-changed, email-changed, sign-in-code, magic-link,
+ * new-sign-in, welcome and invitation, in `en` and `fr`.
+ *
+ * ```ts
+ * // maizzle.config.ts
+ * import { defineMailConfig } from '@nxgt/mail-config';
+ * import { i18n } from '@nxgt/mail-i18n';
+ * import { presets } from '@nxgt/mail-presets';
+ * import { ui, uiCatalogues } from '@nxgt/mail-ui';
+ *
+ * const mails = presets();
+ *
+ * export default defineMailConfig({
+ *   plugins: [
+ *     ui({ brand: { name: 'Acme', url: 'https://acme.example' } }),
+ *     i18n({
+ *       locales: ['en', 'fr'],
+ *       catalogues: [uiCatalogues, mails.catalogues],
+ *       templates: [mails.templates],
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * The built samples are in the package's `samples/` folder, on GitHub.
+ */
+export { PRESETS, type PresetName, type Presets, type PresetsOptions, presetCatalogues, presets, TEMPLATES_DIR, } from './presets';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EACN,OAAO,EACP,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,gBAAgB,EAChB,OAAO,EACP,aAAa,GACb,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,221 @@
+// src/presets.ts
+import { fileURLToPath } from "node:url";
+import {
+  emailKey
+} from "@nxgt/mail-i18n";
+// src/locales/en.json
+var en_default = {
+  presets: {
+    linkFallback: "If the button does not work, open this link:",
+    notYou: "If this was not you, secure your account now."
+  },
+  verifyEmail: {
+    subject: "Confirm your e-mail address",
+    preheader: "One click to confirm your address.",
+    title: "Confirm your e-mail address",
+    body: "Confirm that this address is yours to finish setting up your {brand} account.",
+    action: "Confirm my address"
+  },
+  resetPassword: {
+    subject: "Reset your password",
+    preheader: "Choose a new password for your account.",
+    title: "Reset your password",
+    body: "Someone asked to reset the password of your {brand} account. Choose a new one with the button below.",
+    action: "Choose a new password"
+  },
+  passwordChanged: {
+    subject: "Your password was changed",
+    preheader: "The password of your account was just changed.",
+    title: "Your password was changed",
+    body: "The password of your {brand} account was just changed.",
+    action: "Secure my account"
+  },
+  emailChanged: {
+    subject: "Your e-mail address was changed",
+    preheader: "Your account now signs in with a new address.",
+    title: "Your e-mail address was changed",
+    body: "Your {brand} account now uses {newEmail}. We send this notice to your former address.",
+    action: "Undo this change"
+  },
+  signInCode: {
+    subject: "Your sign-in code: {code}",
+    preheader: "Enter this code to sign in.",
+    title: "Your sign-in code",
+    body: "Enter this code to sign in to {brand}. It works once.",
+    ignore: "If you did not try to sign in, you can ignore this e-mail: no one can sign in without the code."
+  },
+  magicLink: {
+    subject: "Your sign-in link",
+    preheader: "One click to sign in.",
+    title: "Sign in to {brand}",
+    body: "Click the button below to sign in. The link works once.",
+    action: "Sign in"
+  },
+  newSignIn: {
+    subject: "New sign-in to your account",
+    preheader: "Your account was signed in from a new device.",
+    title: "New sign-in to your account",
+    banner: "Your account was signed in from a device we had not seen.",
+    device: "Device",
+    location: "Location",
+    time: "Time",
+    body: "If this was you, there is nothing to do.",
+    action: "Secure my account"
+  },
+  welcome: {
+    subject: "Welcome, {name}",
+    preheader: "Your account is ready.",
+    title: "Welcome to {brand}",
+    body: "Your account is ready. Everything you need is one click away.",
+    action: "Get started"
+  },
+  invitation: {
+    subject: "{inviter} invited you to join {organization}",
+    preheader: "Join {organization} on {brand}.",
+    title: "Join {organization}",
+    body: "{inviter} invited you to join {organization} on {brand}.",
+    action: "Accept the invitation"
+  }
+};
+// src/locales/fr.json
+var fr_default = {
+  presets: {
+    linkFallback: "Si le bouton ne fonctionne pas, ouvrez ce lien :",
+    notYou: "Si ce n'était pas vous, sécurisez votre compte dès maintenant."
+  },
+  verifyEmail: {
+    subject: "Confirmez votre adresse e-mail",
+    preheader: "Un clic pour confirmer votre adresse.",
+    title: "Confirmez votre adresse e-mail",
+    body: "Confirmez que cette adresse est bien la vôtre pour terminer la création de votre compte {brand}.",
+    action: "Confirmer mon adresse"
+  },
+  resetPassword: {
+    subject: "Réinitialisez votre mot de passe",
+    preheader: "Choisissez un nouveau mot de passe pour votre compte.",
+    title: "Réinitialisez votre mot de passe",
+    body: "Quelqu'un a demandé à réinitialiser le mot de passe de votre compte {brand}. Choisissez-en un nouveau avec le bouton ci-dessous.",
+    action: "Choisir un nouveau mot de passe"
+  },
+  passwordChanged: {
+    subject: "Votre mot de passe a été modifié",
+    preheader: "Le mot de passe de votre compte vient d'être modifié.",
+    title: "Votre mot de passe a été modifié",
+    body: "Le mot de passe de votre compte {brand} vient d'être modifié.",
+    action: "Sécuriser mon compte"
+  },
+  emailChanged: {
+    subject: "Votre adresse e-mail a été modifiée",
+    preheader: "Votre compte utilise désormais une nouvelle adresse.",
+    title: "Votre adresse e-mail a été modifiée",
+    body: "Votre compte {brand} utilise désormais {newEmail}. Nous envoyons cet avis à votre ancienne adresse.",
+    action: "Annuler ce changement"
+  },
+  signInCode: {
+    subject: "Votre code de connexion : {code}",
+    preheader: "Saisissez ce code pour vous connecter.",
+    title: "Votre code de connexion",
+    body: "Saisissez ce code pour vous connecter à {brand}. Il ne fonctionne qu'une fois.",
+    ignore: "Si vous n'avez pas essayé de vous connecter, vous pouvez ignorer cet e-mail : personne ne peut se connecter sans ce code."
+  },
+  magicLink: {
+    subject: "Votre lien de connexion",
+    preheader: "Un clic pour vous connecter.",
+    title: "Connectez-vous à {brand}",
+    body: "Cliquez sur le bouton ci-dessous pour vous connecter. Le lien ne fonctionne qu'une fois.",
+    action: "Me connecter"
+  },
+  newSignIn: {
+    subject: "Nouvelle connexion à votre compte",
+    preheader: "Votre compte a été utilisé depuis un nouvel appareil.",
+    title: "Nouvelle connexion à votre compte",
+    banner: "Votre compte a été utilisé depuis un appareil que nous ne connaissions pas.",
+    device: "Appareil",
+    location: "Lieu",
+    time: "Heure",
+    body: "Si c'était vous, vous n'avez rien à faire.",
+    action: "Sécuriser mon compte"
+  },
+  welcome: {
+    subject: "Bienvenue, {name}",
+    preheader: "Votre compte est prêt.",
+    title: "Bienvenue chez {brand}",
+    body: "Votre compte est prêt. Tout ce dont vous avez besoin est à portée de clic.",
+    action: "Commencer"
+  },
+  invitation: {
+    subject: "{inviter} vous invite à rejoindre {organization}",
+    preheader: "Rejoignez {organization} sur {brand}.",
+    title: "Rejoignez {organization}",
+    body: "{inviter} vous invite à rejoindre {organization} sur {brand}.",
+    action: "Accepter l'invitation"
+  }
+};
+
+// src/presets.ts
+var PRESETS = [
+  "verify-email",
+  "reset-password",
+  "password-changed",
+  "email-changed",
+  "sign-in-code",
+  "magic-link",
+  "new-sign-in",
+  "welcome",
+  "invitation"
+];
+var TEMPLATES_DIR = fileURLToPath(new URL("../emails", import.meta.url));
+function freeze(catalogue) {
+  for (const value of Object.values(catalogue)) {
+    if (typeof value === "object" && value !== null)
+      freeze(value);
+  }
+  return Object.freeze(catalogue);
+}
+var presetCatalogues = Object.freeze({
+  en: freeze(en_default),
+  fr: freeze(fr_default)
+});
+function checkOnly(only) {
+  if (!Array.isArray(only) || only.length === 0) {
+    throw new TypeError("presets: only must list at least one preset, as ['verify-email']");
+  }
+  for (const name of only) {
+    if (!PRESETS.includes(name)) {
+      throw new TypeError(`presets: only holds something that is not a preset — name one of ${PRESETS.join(", ")}`);
+    }
+  }
+  if (new Set(only).size !== only.length) {
+    throw new TypeError("presets: only holds the same preset twice");
+  }
+}
+function pick(catalogue, keys) {
+  return Object.fromEntries(Object.entries(catalogue).filter(([key]) => keys.has(key)));
+}
+function presets(options = {}) {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new TypeError("presets: options must be an object, as { only: ['verify-email'] }");
+  }
+  if (options.only === undefined) {
+    return { templates: { dir: TEMPLATES_DIR }, catalogues: presetCatalogues };
+  }
+  checkOnly(options.only);
+  const [first, ...rest] = options.only;
+  const keys = new Set(["presets", ...options.only.map(emailKey)]);
+  return {
+    templates: { dir: TEMPLATES_DIR, emails: [first, ...rest] },
+    catalogues: Object.fromEntries(Object.entries(presetCatalogues).map(([locale, catalogue]) => [
+      locale,
+      pick(catalogue, keys)
+    ]))
+  };
+}
+export {
+  PRESETS,
+  TEMPLATES_DIR,
+  presetCatalogues,
+  presets
+};
+
+//# debugId=ECFD552A0FD494CB64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/presets.ts"],
+  "sourcesContent": [
+    "import { fileURLToPath } from 'node:url';\nimport {\n\ttype Catalogue,\n\ttype Catalogues,\n\temailKey,\n\ttype TemplateSource,\n} from '@nxgt/mail-i18n';\nimport en from './locales/en.json';\nimport fr from './locales/fr.json';\n\n/** Every preset, by the name of its template and of its built file. */\nexport const PRESETS = [\n\t'verify-email',\n\t'reset-password',\n\t'password-changed',\n\t'email-changed',\n\t'sign-in-code',\n\t'magic-link',\n\t'new-sign-in',\n\t'welcome',\n\t'invitation',\n] as const;\n\nexport type PresetName = (typeof PRESETS)[number];\n\n/** The templates, beside `src/` and `dist/` in the package. */\nexport const TEMPLATES_DIR = fileURLToPath(\n\tnew URL('../emails', import.meta.url),\n);\n\n/** `catalogue` and every group in it, frozen: a project reads them, never changes them. */\nfunction freeze(catalogue: Catalogue): Catalogue {\n\tfor (const value of Object.values(catalogue)) {\n\t\tif (typeof value === 'object' && value !== null) freeze(value as Catalogue);\n\t}\n\treturn Object.freeze(catalogue);\n}\n\n/** The messages of every preset, in `en` and `fr`, before {@link presets} keeps the ones asked for. */\nexport const presetCatalogues: Catalogues = Object.freeze({\n\ten: freeze(en),\n\tfr: freeze(fr),\n});\n\nexport interface PresetsOptions {\n\t/** The presets to build, as `['verify-email', 'reset-password']`. Default every one. */\n\treadonly only?: readonly [PresetName, ...PresetName[]];\n}\n\n/** What {@link presets} answers, for `@nxgt/mail-i18n`. */\nexport interface Presets {\n\t/** For `i18n({ templates })`. */\n\treadonly templates: TemplateSource;\n\t/** For `i18n({ catalogues })`: the messages of the presets kept, and the shared `presets.*`. */\n\treadonly catalogues: Catalogues;\n}\n\nfunction checkOnly(\n\tonly: unknown,\n): asserts only is readonly [PresetName, ...PresetName[]] {\n\tif (!Array.isArray(only) || only.length === 0) {\n\t\tthrow new TypeError(\n\t\t\t\"presets: only must list at least one preset, as ['verify-email']\",\n\t\t);\n\t}\n\tfor (const name of only) {\n\t\tif (!(PRESETS as readonly unknown[]).includes(name)) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`presets: only holds something that is not a preset — name one of ${PRESETS.join(', ')}`,\n\t\t\t);\n\t\t}\n\t}\n\tif (new Set(only).size !== only.length) {\n\t\tthrow new TypeError('presets: only holds the same preset twice');\n\t}\n}\n\n/** `catalogue` with only the groups named in `keys`. */\nfunction pick(catalogue: Catalogue, keys: ReadonlySet<string>): Catalogue {\n\treturn Object.fromEntries(\n\t\tObject.entries(catalogue).filter(([key]) => keys.has(key)),\n\t);\n}\n\n/**\n * The preset e-mails of `@nxgt/mail-presets`, for `@nxgt/mail-i18n`:\n *\n * ```ts\n * const mails = presets({ only: ['verify-email', 'reset-password'] });\n * i18n({\n *   locales: ['en', 'fr'],\n *   catalogues: [uiCatalogues, mails.catalogues],\n *   templates: [mails.templates],\n * });\n * ```\n *\n * The project builds them with its own `ui({ brand, theme })`. A template of\n * the same name in its `emails/` replaces a preset, and its catalogue\n * overrides any message key by key.\n */\nexport function presets(options: PresetsOptions = {}): Presets {\n\tif (\n\t\ttypeof options !== 'object' ||\n\t\toptions === null ||\n\t\tArray.isArray(options)\n\t) {\n\t\tthrow new TypeError(\n\t\t\t\"presets: options must be an object, as { only: ['verify-email'] }\",\n\t\t);\n\t}\n\tif (options.only === undefined) {\n\t\treturn { templates: { dir: TEMPLATES_DIR }, catalogues: presetCatalogues };\n\t}\n\tcheckOnly(options.only);\n\tconst [first, ...rest] = options.only;\n\tconst keys = new Set(['presets', ...options.only.map(emailKey)]);\n\treturn {\n\t\ttemplates: { dir: TEMPLATES_DIR, emails: [first, ...rest] },\n\t\tcatalogues: Object.fromEntries(\n\t\t\tObject.entries(presetCatalogues).map(([locale, catalogue]) => [\n\t\t\t\tlocale,\n\t\t\t\tpick(catalogue, keys),\n\t\t\t]),\n\t\t),\n\t};\n}\n"
+  ],
+  "mappings": ";AAAA;AACA;AAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUO,IAAM,UAAU;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD;AAKO,IAAM,gBAAgB,cAC5B,IAAI,IAAI,aAAa,YAAY,GAAG,CACrC;AAGA,SAAS,MAAM,CAAC,WAAiC;AAAA,EAChD,WAAW,SAAS,OAAO,OAAO,SAAS,GAAG;AAAA,IAC7C,IAAI,OAAO,UAAU,YAAY,UAAU;AAAA,MAAM,OAAO,KAAkB;AAAA,EAC3E;AAAA,EACA,OAAO,OAAO,OAAO,SAAS;AAAA;AAIxB,IAAM,mBAA+B,OAAO,OAAO;AAAA,EACzD,IAAI,OAAO,UAAE;AAAA,EACb,IAAI,OAAO,UAAE;AACd,CAAC;AAeD,SAAS,SAAS,CACjB,MACyD;AAAA,EACzD,IAAI,CAAC,MAAM,QAAQ,IAAI,KAAK,KAAK,WAAW,GAAG;AAAA,IAC9C,MAAM,IAAI,UACT,kEACD;AAAA,EACD;AAAA,EACA,WAAW,QAAQ,MAAM;AAAA,IACxB,IAAI,CAAE,QAA+B,SAAS,IAAI,GAAG;AAAA,MACpD,MAAM,IAAI,UACT,oEAAoE,QAAQ,KAAK,IAAI,GACtF;AAAA,IACD;AAAA,EACD;AAAA,EACA,IAAI,IAAI,IAAI,IAAI,EAAE,SAAS,KAAK,QAAQ;AAAA,IACvC,MAAM,IAAI,UAAU,2CAA2C;AAAA,EAChE;AAAA;AAID,SAAS,IAAI,CAAC,WAAsB,MAAsC;AAAA,EACzE,OAAO,OAAO,YACb,OAAO,QAAQ,SAAS,EAAE,OAAO,EAAE,SAAS,KAAK,IAAI,GAAG,CAAC,CAC1D;AAAA;AAmBM,SAAS,OAAO,CAAC,UAA0B,CAAC,GAAY;AAAA,EAC9D,IACC,OAAO,YAAY,YACnB,YAAY,QACZ,MAAM,QAAQ,OAAO,GACpB;AAAA,IACD,MAAM,IAAI,UACT,mEACD;AAAA,EACD;AAAA,EACA,IAAI,QAAQ,SAAS,WAAW;AAAA,IAC/B,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,GAAG,YAAY,iBAAiB;AAAA,EAC1E;AAAA,EACA,UAAU,QAAQ,IAAI;AAAA,EACtB,OAAO,UAAU,QAAQ,QAAQ;AAAA,EACjC,MAAM,OAAO,IAAI,IAAI,CAAC,WAAW,GAAG,QAAQ,KAAK,IAAI,QAAQ,CAAC,CAAC;AAAA,EAC/D,OAAO;AAAA,IACN,WAAW,EAAE,KAAK,eAAe,QAAQ,CAAC,OAAO,GAAG,IAAI,EAAE;AAAA,IAC1D,YAAY,OAAO,YAClB,OAAO,QAAQ,gBAAgB,EAAE,IAAI,EAAE,QAAQ,eAAe;AAAA,MAC7D;AAAA,MACA,KAAK,WAAW,IAAI;AAAA,IACrB,CAAC,CACF;AAAA,EACD;AAAA;",
+  "debugId": "ECFD552A0FD494CB64756E2164756E21",
+  "names": []
+}

package/dist/presets.d.ts

@@ -0,0 +1,37 @@
+import { type Catalogues, type TemplateSource } from '@nxgt/mail-i18n';
+/** Every preset, by the name of its template and of its built file. */
+export declare const PRESETS: readonly ["verify-email", "reset-password", "password-changed", "email-changed", "sign-in-code", "magic-link", "new-sign-in", "welcome", "invitation"];
+export type PresetName = (typeof PRESETS)[number];
+/** The templates, beside `src/` and `dist/` in the package. */
+export declare const TEMPLATES_DIR: string;
+/** The messages of every preset, in `en` and `fr`, before {@link presets} keeps the ones asked for. */
+export declare const presetCatalogues: Catalogues;
+export interface PresetsOptions {
+    /** The presets to build, as `['verify-email', 'reset-password']`. Default every one. */
+    readonly only?: readonly [PresetName, ...PresetName[]];
+}
+/** What {@link presets} answers, for `@nxgt/mail-i18n`. */
+export interface Presets {
+    /** For `i18n({ templates })`. */
+    readonly templates: TemplateSource;
+    /** For `i18n({ catalogues })`: the messages of the presets kept, and the shared `presets.*`. */
+    readonly catalogues: Catalogues;
+}
+/**
+ * The preset e-mails of `@nxgt/mail-presets`, for `@nxgt/mail-i18n`:
+ *
+ * ```ts
+ * const mails = presets({ only: ['verify-email', 'reset-password'] });
+ * i18n({
+ *   locales: ['en', 'fr'],
+ *   catalogues: [uiCatalogues, mails.catalogues],
+ *   templates: [mails.templates],
+ * });
+ * ```
+ *
+ * The project builds them with its own `ui({ brand, theme })`. A template of
+ * the same name in its `emails/` replaces a preset, and its catalogue
+ * overrides any message key by key.
+ */
+export declare function presets(options?: PresetsOptions): Presets;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../src/presets.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,UAAU,EAEf,KAAK,cAAc,EACnB,MAAM,iBAAiB,CAAC;AAIzB,uEAAuE;AACvE,eAAO,MAAM,OAAO,wJAUV,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,+DAA+D;AAC/D,eAAO,MAAM,aAAa,QAEzB,CAAC;AAUF,uGAAuG;AACvG,eAAO,MAAM,gBAAgB,EAAE,UAG7B,CAAC;AAEH,MAAM,WAAW,cAAc;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,UAAU,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC;CACvD;AAED,2DAA2D;AAC3D,MAAM,WAAW,OAAO;IACvB,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,gGAAgG;IAChG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CAChC;AA6BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAyB7D"}

package/docs/README.md

@@ -0,0 +1,21 @@
+# @nxgt/mail-presets — documentation
+
+The [README](../README.md) shows that it works. These pages show how, one area
+at a time, with an example for every rule. A *preset* is one of the package's
+nine e-mails: its template and its messages. The other words they use
+(project, template, catalogue, message, placeholder, variable, subject) are
+defined once, in the
+[vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md).
+
+| Page | Read it when |
+| --- | --- |
+| [Wiring the presets](guide/presets.md) | You are adding `presets()` to `maizzle.config.ts`: its `only` option, what it answers and how `i18n()` builds it, replacing a template, overriding a message, a locale other than `en` and `fr`, and every `TypeError` it throws |
+| [The e-mails](guide/emails.md) | You are sending one of the nine: what it is for, what it shows, its placeholders and which of them is a URL, its subject, and each of its messages in `en` and `fr` |
+| [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
+| [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |
+
+The built HTML of every preset, in both locales, is in
+[`samples/`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-presets/samples/README.md),
+on GitHub. The package's specs check it against a build made the way a
+project makes it: `@nxgt/mail-ui` and `@nxgt/mail-presets` installed in a
+`node_modules`, with the configuration of [The e-mails](guide/emails.md).