@menapo/email 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @menapo/email
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Transactional mail as HTML and text, from standard HTML and your own styles.
+
+```ts
+import { email, html, render } from "@menapo/email";
+
+export const verify = email(({ name, url }: { name: string; url: string }) => ({
+  subject: t("Verify your email"),
+  preheader: t("One click to confirm your address"),
+  body: html`<div class=${card}>
+    <p class=${text}>${t("Hi {name},", { name })}</p>
+    <a href=${url} class=${cta({ intent: "primary" })}>${t("Verify email")}</a>
+  </div>`,
+}));
+
+const { subject, html, text } = await render(verify, { name, url }, { locale: "de" });
+```
+
+```ts
+// vite.config.ts: no options
+import { email } from "@menapo/email/vite";
+export default { plugins: [vicss(), vi18n(), email()] };
+```
+
+- **Your styles, made safe for mail:** vicss tokens and recipes become literal inline styles; buttons, boxes and flex rows become Outlook-safe tables; dark mode and breakpoints go in one `<style>`.
+- **Warnings, not guesses:** what a client would drop warns in dev and tests, naming the clients and the fix.
+- **Per recipient:** `t()` runs in the recipient's locale; `lang` and `dir` follow.
+- **Small and fast:** no framework; one mail renders in about 0.14 ms and ships in about 7 KB gzip, against React Email's 4 ms and 49 KB ([bench](../../bench/README.md#menapoemail)).
+- **Preview and snapshots:** `/__email` in the dev server; `renderSamples()` in tests.
+
+Status: built, private until 1.0. [Guide](docs/guide/README.md) · [Plan](docs/PLAN.md).

package/dist/index-CSAt1cGc.d.ts

@@ -0,0 +1,82 @@
+//#region ../markup/src/index.d.ts
+/** A style object of literal CSS values; numbers are px where CSS takes a length. */
+type Style = {
+  readonly [property: string]: string | number | undefined;
+};
+/** What `class` takes: what vicss produces (a `css()` style, a recipe's result), class names, or a list of them. */
+type ClassValue = string | {
+  readonly [id: string]: string;
+} | {
+  readonly $c: {
+    readonly [id: string]: string;
+  };
+  readonly $s?: {
+    readonly [name: string]: string;
+  };
+} | false | null | undefined | 0 | readonly ClassValue[];
+type Props = {
+  readonly [name: string]: unknown;
+};
+/** An element. `class` is merged to one string and `style` to one object. */
+interface Node {
+  readonly type: string;
+  readonly props: Props & {
+    readonly class?: string;
+    readonly style?: Style;
+  };
+  readonly children: readonly Child[];
+}
+type Child = Node | string;
+/** What a template returns: one element, text, or several (several roots). */
+type Markup = Child | readonly Child[];
+/** A component: a function from its attributes and children to markup. */
+type Component<P = Props> = (props: P & {
+  children: readonly Child[];
+}) => Markup;
+/**
+ * A template: `` html`<p class=${card} ...${attrs}>${text}</p>` `` → a node
+ * tree. Several roots give an array.
+ */
+declare const html: (strings: TemplateStringsArray, ...values: readonly unknown[]) => Markup;
+//#endregion
+//#region src/email.d.ts
+/** What a template returns. */
+interface Message {
+  readonly subject: string;
+  /** The line inbox lists show after the subject; hidden in the mail itself. */
+  readonly preheader?: string;
+  readonly body: Markup;
+}
+interface EmailOptions<P> {
+  /** Named props for the dev preview and `renderSamples()`: `{ default: { name: "Ada" } }`. */
+  readonly samples?: Readonly<Record<string, P>>;
+}
+declare const KIND: unique symbol;
+/** A defined email: pass it to `render()`. */
+declare class Email<P> {
+  readonly [KIND] = true;
+  readonly template: (props: P) => Message | Promise<Message>;
+  readonly samples: Readonly<Record<string, P>>;
+  constructor(template: (props: P) => Message | Promise<Message>, samples?: Readonly<Record<string, P>>);
+}
+/** Defines an email. The props type is the parameter's. */
+declare function email<P>(template: (props: P) => Message | Promise<Message>, options?: EmailOptions<P>): Email<P>;
+//#endregion
+//#region src/index.d.ts
+interface RenderOptions {
+  /** The recipient's locale: `t()` runs in it, and `<html lang dir>` follow it. */
+  readonly locale?: string;
+  /** The recipient's IANA zone for dates, with vi18n. */
+  readonly timeZone?: string;
+  /** For warnings: the export's name. The preview and `renderSamples()` pass it. */
+  readonly name?: string;
+}
+interface Rendered {
+  readonly subject: string;
+  readonly html: string;
+  readonly text: string;
+}
+/** Renders an email for one recipient: its subject, HTML and plain text. */
+declare function render<P>(mail: Email<P>, props: P, options?: RenderOptions): Promise<Rendered>;
+//#endregion
+export { EmailOptions as a, Child as c, Markup as d, Node as f, Email as i, ClassValue as l, html as m, Rendered as n, Message as o, Style as p, render as r, email as s, RenderOptions as t, Component as u };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { a as EmailOptions, c as Child, d as Markup, f as Node, i as Email, l as ClassValue, m as html, n as Rendered, o as Message, p as Style, r as render, s as email, t as RenderOptions, u as Component } from "./index-CSAt1cGc.js";
+export { type Child, type ClassValue, type Component, type Email, type EmailOptions, type Markup, type Message, type Node, RenderOptions, Rendered, type Style, email, html, render };

package/dist/index.js

@@ -0,0 +1 @@
+export { n as email, i as html, t as render } from "./src-nwP-sVbY.js";