@nxgt/mail-config 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,239 @@
+# @nxgt/mail-config
+
+Less boilerplate in a normal [Maizzle](https://maizzle.com) 6 project of
+transactional e-mails: `defineMailConfig` layers **plugins** — partial Maizzle
+configs shipped by packages — under your own `maizzle.config.ts`, and runs every
+plugin's build events one after the other instead of letting the last one
+silently replace the others.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { brand } from './plugins/brand';
+
+export default defineMailConfig({
+	plugins: [brand],
+	// your own Maizzle config, as usual — it wins over every plugin
+	afterTransform: ({ html }) => `${html}<!-- built by the project -->`,
+});
+```
+
+Your project stays a Maizzle project: `emails/`, `components/`, `public/`,
+`maizzle serve`, `maizzle build`. Nothing here replaces a Maizzle command.
+
+> **0.x.** A minor version may still change the surface; the changelog says how.
+
+## Install
+
+```sh
+bun add @nxgt/mail-config @maizzle/framework @maizzle/tailwindcss
+```
+
+Peers, all required:
+
+- `@maizzle/framework` (`^6.1.7`) — Maizzle itself.
+- `@maizzle/tailwindcss` (`^1.5.6`) — **as a direct dependency of your
+  project**, even if another package already brings it: see
+  [Setup](#setup).
+- `typescript` (6). Bundler resolution (`"moduleResolution": "bundler"`) is
+  what is supported and tested; `nodenext` is out of contract.
+
+## Setup
+
+```css
+/* in the <style> your layout imports Tailwind from */
+@import "@maizzle/tailwindcss";
+```
+
+That import is resolved from your project. Under an isolated install — Bun
+workspaces, pnpm — a copy that is only a dependency of another package is not
+reachable from there, and the import fails **silently**: the build succeeds,
+and no Tailwind utility is generated. Listing `@maizzle/tailwindcss` in
+your own `package.json`, as the `bun add` above does, is what makes it
+resolve.
+
+## Exports
+
+| Export | What it is |
+| --- | --- |
+| `defineMailConfig(config?)` | Your `maizzle.config.ts`: base, plugins, then your config |
+| `defineMailPlugin(plugin)` | Checks a plugin and answers it unchanged |
+| `productionConfig(config, overrides?)` | `maizzle.config.production.ts`: minified HTML over your config |
+| `baseConfig` | The lowest layer, `{ plaintext: true }`, frozen |
+| `MailConfig` | The type `defineMailConfig` takes: a `MaizzleConfig` with `plugins` |
+| `MailPlugin` | The type of a plugin: a `MaizzleConfig` with a `name`, and no `plugins` |
+
+## Usage
+
+### A project config — `defineMailConfig`
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { alpha, beta } from './plugins';
+
+export default defineMailConfig({
+	plugins: [alpha, beta],
+	vue: { globalProperties: { greeting: 'from the project' } },
+	afterTransform: ({ html }) => `${html}<!-- project -->`,
+});
+```
+
+The layers, lowest first:
+
+1. **`baseConfig`** — `{ plaintext: true }`: a `.txt` part next to each
+   `.html`. Everything else a project needs (`dist/`, `public/` copied, CSS
+   inlined and purged) is already Maizzle's default.
+2. **Each plugin, in the order listed** — a later plugin wins over an earlier
+   one.
+3. **The rest of your config** — it wins over every plugin.
+
+How two layers merge:
+
+| What | Rule |
+| --- | --- |
+| An object (`output`, `css`, `vue.globalProperties`…) | Merged key by key; the later layer's key wins, a key only an earlier layer sets stays |
+| An array (`content`, `static.source`…) | **Replaced** by the later layer's, as Maizzle's own merge does |
+| `components.source`, `vite.plugins`, `vue.plugins` | **Joined**, in layer order: two plugins that each bring components keep both. A `vue.plugins` factory (`() => Plugin[]`) stays a factory, called once per render |
+| A build event | **Chained** — see below |
+
+The result is a plain Maizzle config: `plugins` and each plugin's `name` are
+not passed to Maizzle. See [The project config](docs/guide/config.md).
+
+### Build events, chained
+
+Every layer's handler for an event runs, in layer order, each awaited before
+the next:
+
+```ts
+import { defineMailConfig, defineMailPlugin } from '@nxgt/mail-config';
+
+const alpha = defineMailPlugin({
+	name: 'alpha',
+	beforeRender: ({ template }) => template.source.replace('[[mark]]', '[[alpha]]'),
+});
+
+const beta = defineMailPlugin({
+	name: 'beta', // listed after alpha, so it sees alpha's source
+	beforeRender: ({ template }) => template.source.replace('[[alpha]]', 'alpha then beta'),
+});
+
+export default defineMailConfig({ plugins: [alpha, beta] }); // [[mark]] → alpha then beta
+```
+
+| Event | What a returned string does |
+| --- | --- |
+| `beforeCreate` | Nothing — every handler runs, in order |
+| `beforeRender` | Replaces `template.source`, which the next handler reads |
+| `afterRender`, `afterTransform` | Replaces the `html` the next handler receives; the last string is the output |
+| `afterBuild` | Nothing — every handler runs, in order |
+
+A handler that returns nothing leaves the source or the HTML as it was. A
+handler that **throws stops the chain**: the handlers after it do not run, and
+the error reaches Maizzle, which fails the build.
+
+### A plugin — `defineMailPlugin`
+
+A plugin is a partial Maizzle config with a `name`. A package exports one,
+checked where it is written — a mistake throws `defineMailPlugin: plugin …`
+when the package loads, not in each project that lists it:
+
+```ts
+// plugins/brand.ts
+import { fileURLToPath } from 'node:url';
+import { defineMailPlugin } from '@nxgt/mail-config';
+
+export const brand = defineMailPlugin({
+	name: 'brand',
+	components: {
+		source: [{ path: fileURLToPath(new URL('./components', import.meta.url)), prefix: 'Brand' }],
+	},
+	vue: { globalProperties: { company: 'Example Inc.' } },
+	afterTransform: ({ html }) => `${html}<!-- brand -->`,
+});
+```
+
+`components/footer.vue` next to that file is `<BrandFooter>` in every template.
+See [Writing a plugin](docs/guide/plugins.md).
+
+### A production build — `productionConfig`
+
+Maizzle has no environments: `maizzle build -c <file>` loads that file and no
+other, so the production config imports the project's.
+
+```ts
+// maizzle.config.production.ts
+import { productionConfig } from '@nxgt/mail-config';
+import config from './maizzle.config';
+
+export default productionConfig(config, { output: { path: 'dist-production' } });
+```
+
+```sh
+maizzle build -c maizzle.config.production.ts
+```
+
+It layers your config, then `{ html: { minify: true } }` — unless your config
+already set minify options, which are kept — then the overrides, merged as a
+plugin is: their `components.source`, `vite.plugins` and `vue.plugins` are
+added to yours, their build events run after yours. See
+[Production](docs/guide/production.md).
+
+## Traps
+
+**A plugin's paths are absolute.** Maizzle resolves a relative
+`components.source` against the directory `maizzle` runs in — your project,
+not the package: write `fileURLToPath(new URL('./components', import.meta.url))`.
+
+**A plugin that sets an array replaces the default under it.** `content:
+['src/**/*.vue']` in a plugin drops Maizzle's `emails/**/*.{vue,md}`, as it
+would in your own config.
+
+**Do not set a build event by spreading configs yourself.** `{ ...a, ...b }`
+keeps `b`'s `beforeRender` and drops `a`'s without a word; list both in
+`plugins`.
+
+**Pass `productionConfig` what `defineMailConfig` answered**, not its argument,
+and list every plugin in the project config: `plugins` in either argument of
+`productionConfig` is a type error, and a `TypeError` at load time.
+
+**A wiring mistake is a bare `TypeError`**, thrown when the config file loads:
+a plugin that was not called, a plugin without a `name`, two plugins with the
+same `name`, a build event that is not a function. Each message names the
+plugin or its index — the list is in [The project config](docs/guide/config.md#errors).
+
+## Type safety, counted
+
+**6 plausible mistakes, 6 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-config/test/types/refusals.ts)
+that fails the typecheck the moment it stops holding:
+
+1. A plugin without a `name`.
+2. `plugins` given one plugin rather than a list.
+3. A build event that is not a function (`beforeRender: 'x'`).
+4. A plugin that brings other plugins.
+5. `productionConfig` given `defineMailConfig`'s argument instead of what it
+   answered.
+6. Plugins added in `productionConfig`'s overrides.
+
+The same file holds the calls that must keep compiling: a refusal that refuses
+the correct call is a bug.
+
+Maizzle's own keys are not refused: its config type takes any key
+(`[key: string]: any`), so a misspelled Maizzle option compiles. What this
+package adds — `name`, `plugins`, the build events' types — is checked.
+
+## Documentation
+
+- [The guides](docs/README.md) — one page per area, with every option 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.
+- [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,72 @@
+/**
+ * `@nxgt/mail-config` — a shareable Maizzle config.
+ *
+ * ```ts
+ * // maizzle.config.ts
+ * import { defineMailConfig } from '@nxgt/mail-config';
+ *
+ * export default defineMailConfig({
+ *   plugins: [ui({ brand }), i18n({ locales: ['en', 'fr'] })],
+ *   // the project's own Maizzle config, which wins over every plugin
+ * });
+ * ```
+ *
+ * A plugin is a partial Maizzle config with a `name`. The layers are the base
+ * config, then each plugin in order, then the project; every build event runs
+ * each layer's handler in that order instead of the last one replacing the
+ * others.
+ */
+import type { MaizzleConfig } from '@maizzle/framework';
+/** A partial Maizzle config a package hands to {@link defineMailConfig}. */
+export interface MailPlugin extends MaizzleConfig {
+    /** Names the plugin in an error; two plugins of a project never share one. */
+    readonly name: string;
+    /** A plugin cannot bring others: the project lists every plugin. */
+    readonly plugins?: never;
+}
+/** A project's Maizzle config, with the plugins layered under it. */
+export interface MailConfig extends MaizzleConfig {
+    /** Layered in order, each over the one before, all under the project. */
+    readonly plugins?: readonly MailPlugin[];
+}
+/**
+ * What a project gets without asking: a plain-text part next to each HTML
+ * file. Everything else — `dist/`, `public/`, CSS inlined and purged — is
+ * already Maizzle's default.
+ */
+export declare const baseConfig: Readonly<MaizzleConfig>;
+/**
+ * Checks a plugin and answers it as it is: for a package that exports one, so
+ * its mistakes surface where it is written, not in the project that uses it.
+ * Typed `MailPlugin`, so a package's declarations can name what it exports.
+ */
+export declare function defineMailPlugin(plugin: MailPlugin): MailPlugin;
+/**
+ * The project's Maizzle config: {@link baseConfig}, then each plugin in
+ * order, then the rest of `config`. Objects merge and arrays replace, as in
+ * Maizzle — except `components.source`, `vite.plugins` and `vue.plugins`,
+ * which every layer adds to. Every build event runs each layer's handler, in
+ * that order.
+ */
+export declare function defineMailConfig(config?: MailConfig): MaizzleConfig;
+/**
+ * The production build's config, for `maizzle.config.production.ts`: the
+ * project's `config`, with the HTML minified — with the project's own
+ * `html.minify` options when it set some — then `overrides`, merged as a
+ * plugin is: its `components.source`, `vite.plugins` and `vue.plugins` are
+ * added to the project's, its build events run after the project's.
+ *
+ * ```ts
+ * // maizzle.config.production.ts — `maizzle build -c maizzle.config.production.ts`
+ * import config from './maizzle.config';
+ * import { productionConfig } from '@nxgt/mail-config';
+ *
+ * export default productionConfig(config, { output: { path: 'dist-production' } });
+ * ```
+ */
+export declare function productionConfig(config: MaizzleConfig & {
+    readonly plugins?: never;
+}, overrides?: MaizzleConfig & {
+    readonly plugins?: never;
+}): MaizzleConfig;
+//# 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;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,4EAA4E;AAC5E,MAAM,WAAW,UAAW,SAAQ,aAAa;IAChD,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAW,SAAQ,aAAa;IAChD,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,aAAa,CAE7C,CAAC;AA0CH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAG/D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,UAAe,GAAG,aAAa,CAwBvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,aAAa,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CAAE,EACpD,SAAS,GAAE,aAAa,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAA;CAAO,GAC1D,aAAa,CAyBf"}

package/dist/index.js

@@ -0,0 +1,173 @@
+// src/layer.ts
+import { createDefu } from "defu";
+var EVENTS = [
+  "beforeCreate",
+  "beforeRender",
+  "afterRender",
+  "afterTransform",
+  "afterBuild"
+];
+var merge = createDefu((target, key, value) => {
+  if (Array.isArray(target[key])) {
+    target[key] = value;
+    return true;
+  }
+});
+var LISTS = [
+  ["components", "source"],
+  ["vite", "plugins"],
+  ["vue", "plugins"]
+];
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function joinVuePlugins(values) {
+  if (values.every(Array.isArray))
+    return values.flat();
+  return () => values.flatMap((value) => typeof value === "function" ? value() : value);
+}
+function takeLists(layers) {
+  const joined = [];
+  for (const [group, key] of LISTS) {
+    const values = [];
+    for (const layer of layers) {
+      const section = layer[group];
+      if (!isObject(section) || section[key] == null)
+        continue;
+      values.push(section[key]);
+      const { [key]: _, ...rest } = section;
+      layer[group] = rest;
+    }
+    if (values.length === 0)
+      continue;
+    const value = group === "vue" ? joinVuePlugins(values) : values.flatMap((entry) => Array.isArray(entry) ? entry : [entry]);
+    joined.push([group, key, value]);
+  }
+  return joined;
+}
+function chain(event, handlers) {
+  if (handlers.length === 1)
+    return handlers[0];
+  if (event === "beforeRender") {
+    return async (params) => {
+      for (const handler of handlers) {
+        const result = await handler(params);
+        if (typeof result === "string")
+          params.template.source = result;
+      }
+      return params.template.source;
+    };
+  }
+  if (event === "afterRender" || event === "afterTransform") {
+    return async ({ config, template, html }) => {
+      let current = html;
+      for (const handler of handlers) {
+        const result = await handler({ config, template, html: current });
+        if (typeof result === "string")
+          current = result;
+      }
+      return current;
+    };
+  }
+  return async (params) => {
+    for (const handler of handlers)
+      await handler(params);
+  };
+}
+function layer(layers) {
+  const copies = layers.map((config) => ({ ...config }));
+  const handlers = new Map;
+  for (const copy of copies) {
+    for (const event of EVENTS) {
+      const handler = copy[event];
+      if (handler === undefined)
+        continue;
+      handlers.set(event, [...handlers.get(event) ?? [], handler]);
+      delete copy[event];
+    }
+  }
+  const lists = takeLists(copies);
+  const merged = merge({}, ...copies.reverse());
+  for (const [group, key, value] of lists) {
+    merged[group] = { ...merged[group], [key]: value };
+  }
+  for (const [event, list] of handlers)
+    merged[event] = chain(event, list);
+  return merged;
+}
+
+// src/index.ts
+var baseConfig = Object.freeze({
+  plaintext: true
+});
+var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function checkHandlers(config, where) {
+  for (const event of EVENTS) {
+    const handler = config[event];
+    if (handler !== undefined && typeof handler !== "function") {
+      throw new TypeError(`${where}: ${event} must be a function`);
+    }
+  }
+}
+function checkPlugin(plugin, call, where) {
+  if (!isObject2(plugin)) {
+    throw new TypeError(`${call}: ${where} must be a plugin object, as { name, ...config } — was it called?`);
+  }
+  const { name } = plugin;
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new TypeError(`${call}: ${where} has no name — a plugin is { name, ...config }`);
+  }
+  if (plugin.plugins !== undefined) {
+    throw new TypeError(`${call}: plugin "${name}" lists plugins — a plugin cannot bring others; list them in the project`);
+  }
+  checkHandlers(plugin, `${call}: plugin "${name}"`);
+}
+function defineMailPlugin(plugin) {
+  checkPlugin(plugin, "defineMailPlugin", "plugin");
+  return plugin;
+}
+function defineMailConfig(config = {}) {
+  if (!isObject2(config)) {
+    throw new TypeError("defineMailConfig: config must be an object, as { plugins, ...maizzleConfig }");
+  }
+  const { plugins = [], ...project } = config;
+  if (!Array.isArray(plugins)) {
+    throw new TypeError("defineMailConfig: plugins must be an array");
+  }
+  const names = new Set;
+  const layers = plugins.map((plugin, index) => {
+    checkPlugin(plugin, "defineMailConfig", `plugins[${index}]`);
+    const { name, ...rest } = plugin;
+    if (names.has(name)) {
+      throw new TypeError(`defineMailConfig: two plugins are named "${name}" — is one listed twice?`);
+    }
+    names.add(name);
+    return rest;
+  });
+  checkHandlers(project, "defineMailConfig");
+  return layer([baseConfig, ...layers, project]);
+}
+function productionConfig(config, overrides = {}) {
+  if (!isObject2(config)) {
+    throw new TypeError("productionConfig: config must be the project config, as productionConfig(config, overrides)");
+  }
+  if (config.plugins !== undefined) {
+    throw new TypeError("productionConfig: config lists plugins — pass what defineMailConfig answered, not its argument");
+  }
+  if (!isObject2(overrides)) {
+    throw new TypeError("productionConfig: overrides must be an object");
+  }
+  if (overrides.plugins !== undefined) {
+    throw new TypeError("productionConfig: overrides list plugins — list every plugin in the project config");
+  }
+  checkHandlers(overrides, "productionConfig");
+  const minify = isObject2(config.html?.minify) ? {} : { html: { minify: true } };
+  return layer([config, minify, overrides]);
+}
+export {
+  baseConfig,
+  defineMailConfig,
+  defineMailPlugin,
+  productionConfig
+};
+
+//# debugId=48E9630C34283E5C64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/layer.ts", "../src/index.ts"],
+  "sourcesContent": [
+    "import type { MaizzleConfig } from '@maizzle/framework';\nimport { createDefu } from 'defu';\n\n/** The build events Maizzle reads from a config, in the order it fires them. */\nexport const EVENTS = [\n\t'beforeCreate',\n\t'beforeRender',\n\t'afterRender',\n\t'afterTransform',\n\t'afterBuild',\n] as const;\n\ntype Event = (typeof EVENTS)[number];\n// biome-ignore lint/suspicious/noExplicitAny: a handler of any of the five events.\ntype Handler = (params: any) => unknown;\n\n/**\n * Maizzle's own merge, copied from `@maizzle/framework`'s config loader:\n * objects merge key by key, an array replaces the array under it.\n */\nconst merge = createDefu((target, key, value) => {\n\tif (Array.isArray(target[key])) {\n\t\ttarget[key] = value;\n\t\treturn true;\n\t}\n});\n\n/**\n * The lists a plugin adds to rather than sets: two plugins that each bring\n * components, or each a Vite or a Vue plugin, keep both. Under Maizzle's rule\n * the last one would silently drop the others.\n */\nconst LISTS = [\n\t['components', 'source'],\n\t['vite', 'plugins'],\n\t['vue', 'plugins'],\n] as const;\n\ntype Layer = Record<string, unknown>;\n\nconst isObject = (value: unknown): value is Layer =>\n\ttypeof value === 'object' && value !== null && !Array.isArray(value);\n\n/** A `vue.plugins` may be a list, or a factory that answers one per render. */\nfunction joinVuePlugins(values: unknown[]): unknown {\n\tif (values.every(Array.isArray)) return values.flat();\n\treturn () =>\n\t\tvalues.flatMap((value) =>\n\t\t\ttypeof value === 'function' ? (value as () => unknown[])() : value,\n\t\t);\n}\n\n/** Takes each list out of the layers, and answers them joined, in layer order. */\nfunction takeLists(layers: Layer[]): [string, string, unknown][] {\n\tconst joined: [string, string, unknown][] = [];\n\tfor (const [group, key] of LISTS) {\n\t\tconst values: unknown[] = [];\n\t\tfor (const layer of layers) {\n\t\t\tconst section = layer[group];\n\t\t\t// Skipped as Maizzle's merge skips it: `null` sets nothing.\n\t\t\tif (!isObject(section) || section[key] == null) continue;\n\t\t\tvalues.push(section[key]);\n\t\t\tconst { [key]: _, ...rest } = section;\n\t\t\tlayer[group] = rest;\n\t\t}\n\t\tif (values.length === 0) continue;\n\t\tconst value =\n\t\t\tgroup === 'vue'\n\t\t\t\t? joinVuePlugins(values)\n\t\t\t\t: values.flatMap((entry) => (Array.isArray(entry) ? entry : [entry]));\n\t\tjoined.push([group, key, value]);\n\t}\n\treturn joined;\n}\n\n/**\n * One handler that runs every layer's, in order, the way Maizzle runs the\n * handlers it collects: for `beforeRender` a string replaces\n * `template.source`; for `afterRender` and `afterTransform` it replaces the\n * `html` the next one receives.\n */\nfunction chain(event: Event, handlers: Handler[]): Handler {\n\tif (handlers.length === 1) return handlers[0] as Handler;\n\tif (event === 'beforeRender') {\n\t\treturn async (params) => {\n\t\t\tfor (const handler of handlers) {\n\t\t\t\tconst result = await handler(params);\n\t\t\t\tif (typeof result === 'string') params.template.source = result;\n\t\t\t}\n\t\t\treturn params.template.source;\n\t\t};\n\t}\n\tif (event === 'afterRender' || event === 'afterTransform') {\n\t\treturn async ({ config, template, html }) => {\n\t\t\tlet current: string = html;\n\t\t\tfor (const handler of handlers) {\n\t\t\t\tconst result = await handler({ config, template, html: current });\n\t\t\t\tif (typeof result === 'string') current = result;\n\t\t\t}\n\t\t\treturn current;\n\t\t};\n\t}\n\treturn async (params) => {\n\t\tfor (const handler of handlers) await handler(params);\n\t};\n}\n\n/**\n * Layers configs, the first lowest: each key of a later one wins, objects\n * merge, arrays replace — except the {@link LISTS}, joined — and every build\n * event runs each layer's handler in order.\n */\nexport function layer(layers: readonly MaizzleConfig[]): MaizzleConfig {\n\tconst copies: Layer[] = layers.map((config) => ({ ...config }));\n\tconst handlers = new Map<Event, Handler[]>();\n\tfor (const copy of copies) {\n\t\tfor (const event of EVENTS) {\n\t\t\tconst handler = copy[event];\n\t\t\tif (handler === undefined) continue;\n\t\t\thandlers.set(event, [...(handlers.get(event) ?? []), handler as Handler]);\n\t\t\tdelete copy[event];\n\t\t}\n\t}\n\tconst lists = takeLists(copies);\n\tconst merged: Layer = merge({}, ...copies.reverse());\n\tfor (const [group, key, value] of lists) {\n\t\tmerged[group] = { ...(merged[group] as Layer | undefined), [key]: value };\n\t}\n\tfor (const [event, list] of handlers) merged[event] = chain(event, list);\n\treturn merged as MaizzleConfig;\n}\n",
+    "/**\n * `@nxgt/mail-config` — a shareable Maizzle config.\n *\n * ```ts\n * // maizzle.config.ts\n * import { defineMailConfig } from '@nxgt/mail-config';\n *\n * export default defineMailConfig({\n *   plugins: [ui({ brand }), i18n({ locales: ['en', 'fr'] })],\n *   // the project's own Maizzle config, which wins over every plugin\n * });\n * ```\n *\n * A plugin is a partial Maizzle config with a `name`. The layers are the base\n * config, then each plugin in order, then the project; every build event runs\n * each layer's handler in that order instead of the last one replacing the\n * others.\n */\n\nimport type { MaizzleConfig } from '@maizzle/framework';\nimport { EVENTS, layer } from './layer';\n\n/** A partial Maizzle config a package hands to {@link defineMailConfig}. */\nexport interface MailPlugin extends MaizzleConfig {\n\t/** Names the plugin in an error; two plugins of a project never share one. */\n\treadonly name: string;\n\t/** A plugin cannot bring others: the project lists every plugin. */\n\treadonly plugins?: never;\n}\n\n/** A project's Maizzle config, with the plugins layered under it. */\nexport interface MailConfig extends MaizzleConfig {\n\t/** Layered in order, each over the one before, all under the project. */\n\treadonly plugins?: readonly MailPlugin[];\n}\n\n/**\n * What a project gets without asking: a plain-text part next to each HTML\n * file. Everything else — `dist/`, `public/`, CSS inlined and purged — is\n * already Maizzle's default.\n */\nexport const baseConfig: Readonly<MaizzleConfig> = Object.freeze({\n\tplaintext: true,\n});\n\nconst isObject = (value: unknown): value is Record<string, unknown> =>\n\ttypeof value === 'object' && value !== null && !Array.isArray(value);\n\nfunction checkHandlers(config: Record<string, unknown>, where: string): void {\n\tfor (const event of EVENTS) {\n\t\tconst handler = config[event];\n\t\tif (handler !== undefined && typeof handler !== 'function') {\n\t\t\tthrow new TypeError(`${where}: ${event} must be a function`);\n\t\t}\n\t}\n}\n\n/**\n * Checks a plugin; `where` names it in an error — `defineMailConfig:\n * plugins[1]`, or `defineMailPlugin: plugin`.\n */\nfunction checkPlugin(\n\tplugin: unknown,\n\tcall: string,\n\twhere: string,\n): asserts plugin is MailPlugin {\n\tif (!isObject(plugin)) {\n\t\tthrow new TypeError(\n\t\t\t`${call}: ${where} must be a plugin object, as { name, ...config } — was it called?`,\n\t\t);\n\t}\n\tconst { name } = plugin;\n\tif (typeof name !== 'string' || name.trim() === '') {\n\t\tthrow new TypeError(\n\t\t\t`${call}: ${where} has no name — a plugin is { name, ...config }`,\n\t\t);\n\t}\n\tif (plugin.plugins !== undefined) {\n\t\tthrow new TypeError(\n\t\t\t`${call}: plugin \"${name}\" lists plugins — a plugin cannot bring others; list them in the project`,\n\t\t);\n\t}\n\tcheckHandlers(plugin, `${call}: plugin \"${name}\"`);\n}\n\n/**\n * Checks a plugin and answers it as it is: for a package that exports one, so\n * its mistakes surface where it is written, not in the project that uses it.\n * Typed `MailPlugin`, so a package's declarations can name what it exports.\n */\nexport function defineMailPlugin(plugin: MailPlugin): MailPlugin {\n\tcheckPlugin(plugin, 'defineMailPlugin', 'plugin');\n\treturn plugin;\n}\n\n/**\n * The project's Maizzle config: {@link baseConfig}, then each plugin in\n * order, then the rest of `config`. Objects merge and arrays replace, as in\n * Maizzle — except `components.source`, `vite.plugins` and `vue.plugins`,\n * which every layer adds to. Every build event runs each layer's handler, in\n * that order.\n */\nexport function defineMailConfig(config: MailConfig = {}): MaizzleConfig {\n\tif (!isObject(config)) {\n\t\tthrow new TypeError(\n\t\t\t'defineMailConfig: config must be an object, as { plugins, ...maizzleConfig }',\n\t\t);\n\t}\n\tconst { plugins = [], ...project } = config;\n\tif (!Array.isArray(plugins)) {\n\t\tthrow new TypeError('defineMailConfig: plugins must be an array');\n\t}\n\tconst names = new Set<string>();\n\tconst layers = plugins.map((plugin: unknown, index) => {\n\t\tcheckPlugin(plugin, 'defineMailConfig', `plugins[${index}]`);\n\t\tconst { name, ...rest } = plugin;\n\t\tif (names.has(name)) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`defineMailConfig: two plugins are named \"${name}\" — is one listed twice?`,\n\t\t\t);\n\t\t}\n\t\tnames.add(name);\n\t\treturn rest;\n\t});\n\tcheckHandlers(project, 'defineMailConfig');\n\treturn layer([baseConfig, ...layers, project]);\n}\n\n/**\n * The production build's config, for `maizzle.config.production.ts`: the\n * project's `config`, with the HTML minified — with the project's own\n * `html.minify` options when it set some — then `overrides`, merged as a\n * plugin is: its `components.source`, `vite.plugins` and `vue.plugins` are\n * added to the project's, its build events run after the project's.\n *\n * ```ts\n * // maizzle.config.production.ts — `maizzle build -c maizzle.config.production.ts`\n * import config from './maizzle.config';\n * import { productionConfig } from '@nxgt/mail-config';\n *\n * export default productionConfig(config, { output: { path: 'dist-production' } });\n * ```\n */\nexport function productionConfig(\n\tconfig: MaizzleConfig & { readonly plugins?: never },\n\toverrides: MaizzleConfig & { readonly plugins?: never } = {},\n): MaizzleConfig {\n\tif (!isObject(config)) {\n\t\tthrow new TypeError(\n\t\t\t'productionConfig: config must be the project config, as productionConfig(config, overrides)',\n\t\t);\n\t}\n\tif (config.plugins !== undefined) {\n\t\tthrow new TypeError(\n\t\t\t'productionConfig: config lists plugins — pass what defineMailConfig answered, not its argument',\n\t\t);\n\t}\n\tif (!isObject(overrides)) {\n\t\tthrow new TypeError('productionConfig: overrides must be an object');\n\t}\n\tif (overrides.plugins !== undefined) {\n\t\tthrow new TypeError(\n\t\t\t'productionConfig: overrides list plugins — list every plugin in the project config',\n\t\t);\n\t}\n\tcheckHandlers(overrides, 'productionConfig');\n\t// Minify options the project already set are kept: `true` would replace them.\n\tconst minify = isObject(config.html?.minify)\n\t\t? {}\n\t\t: { html: { minify: true } };\n\treturn layer([config, minify, overrides]);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "48E9630C34283E5C64756E2164756E21",
+  "names": []
+}

package/dist/layer.d.ts

@@ -0,0 +1,10 @@
+import type { MaizzleConfig } from '@maizzle/framework';
+/** The build events Maizzle reads from a config, in the order it fires them. */
+export declare const EVENTS: readonly ["beforeCreate", "beforeRender", "afterRender", "afterTransform", "afterBuild"];
+/**
+ * Layers configs, the first lowest: each key of a later one wins, objects
+ * merge, arrays replace — except the {@link LISTS}, joined — and every build
+ * event runs each layer's handler in order.
+ */
+export declare function layer(layers: readonly MaizzleConfig[]): MaizzleConfig;
+//# sourceMappingURL=layer.d.ts.map

package/dist/layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer.d.ts","sourceRoot":"","sources":["../src/layer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,gFAAgF;AAChF,eAAO,MAAM,MAAM,0FAMT,CAAC;AAiGX;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,aAAa,CAkBrE"}

package/docs/README.md

@@ -0,0 +1,14 @@
+# @nxgt/mail-config — documentation
+
+The [README](../README.md) shows that it works; these pages show how, one area
+at a time, with an example for every rule. The words they use — project,
+template, plugin, component — are defined once, in the
+[vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md).
+
+| Page | Read it when |
+| --- | --- |
+| [The project config](guide/config.md) | You are writing `maizzle.config.ts` with `defineMailConfig`: the layers, how objects, arrays and the three joined lists merge, how each build event is chained, and every `TypeError` it throws |
+| [Writing a plugin](guide/plugins.md) | You are shipping a partial Maizzle config in a package with `defineMailPlugin`: components under a prefix, hooks, global properties, options checked at wiring time, and why the order of `plugins` matters |
+| [Production](guide/production.md) | You are adding `maizzle.config.production.ts` with `productionConfig`: minified HTML, its own output folder, a hook that only runs there |
+| [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 |