@molecule/api-templating-mjml 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,173 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T01:49:38.524Z
+-->
+
+# @molecule/api-templating-mjml
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+MJML email template provider for molecule.dev.
+
+Implements the `TemplateProvider` interface using MJML for responsive email
+template rendering. Variable interpolation uses Handlebars syntax. Templates
+are first interpolated with data, then compiled from MJML to responsive HTML
+that works across all major email clients.
+
+## Quick Start
+
+```typescript
+import { setProvider, render } from '@molecule/api-templating'
+import { provider } from '@molecule/api-templating-mjml'
+
+setProvider(provider)
+
+const html = await render(
+  `
+  <mjml>
+    <mj-body>
+      <mj-section>
+        <mj-column>
+          <mj-text>Hello {{name}}!</mj-text>
+        </mj-column>
+      </mj-section>
+    </mj-body>
+  </mjml>
+`,
+  { name: 'World' },
+)
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-templating-mjml @molecule/api-templating handlebars mjml
+npm install -D @types/mjml
+```
+
+## API
+
+### Interfaces
+
+#### `MjmlTemplateConfig`
+
+Configuration options for the MJML template provider.
+
+```typescript
+interface MjmlTemplateConfig {
+  /**
+   * Validation level for MJML templates.
+   * - `'strict'` — `render()` throws on any MJML validation error
+   * - `'soft'` — renders despite errors (default)
+   * - `'skip'` — no validation at all
+   *
+   * Defaults to `'soft'`. Note: only `render()` enforces `'strict'` —
+   * `renderCompiled()` never throws on MJML validation errors regardless
+   * of this setting.
+   */
+  validationLevel?: MjmlValidationLevel
+
+  /** Whether to minify the HTML output. Defaults to `false`. */
+  minify?: boolean
+
+  /** Whether to beautify the HTML output. Defaults to `false`. */
+  beautify?: boolean
+
+  /** File path for resolving `mj-include` relative paths. */
+  filePath?: string
+
+  /**
+   * Built-in helpers to register on creation.
+   * Keys are helper names, values are helper functions.
+   */
+  helpers?: Record<string, (...args: unknown[]) => string>
+
+  /**
+   * Built-in partials to register on creation.
+   * Keys are partial names, values are partial template strings.
+   */
+  partials?: Record<string, string>
+}
+```
+
+### Types
+
+#### `MjmlValidationLevel`
+
+MJML validation level for template processing.
+
+```typescript
+type MjmlValidationLevel = 'strict' | 'soft' | 'skip'
+```
+
+### Functions
+
+#### `createProvider(config)`
+
+Creates an MJML template provider.
+
+```typescript
+function createProvider(config?: MjmlTemplateConfig): TemplateProvider
+```
+
+- `config` — Provider configuration.
+
+**Returns:** A `TemplateProvider` backed by MJML with Handlebars interpolation.
+
+### Constants
+
+#### `provider`
+
+The provider implementation with default configuration (soft validation).
+
+```typescript
+const provider: TemplateProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-templating` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/api-templating'
+import { provider } from '@molecule/api-templating-mjml'
+
+export function setupTemplatingMjml(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-templating` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-templating`
+- `handlebars`
+- `mjml`
+
+- Validation defaults to `'soft'` (render despite MJML errors). Set
+  `createProvider({ validationLevel: 'strict' })` to make `render()` throw
+  on invalid MJML — but note `renderCompiled()` skips validation entirely.
+- `compile()` pre-compiles only the Handlebars interpolation; the MJML →
+  responsive-HTML conversion still runs on every `renderCompiled()` call.
+- Raw (unescaped) interpolation is per-render only (`options.escape:
+false` on `render()`); compiled templates always escape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-templating-mjml",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MJML responsive email template provider for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -32,21 +33,21 @@
     "mjml": "5.4.0"
   },
   "peerDependencies": {
-    "@molecule/api-templating": "^1.0.0"
+    "@molecule/api-templating": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-templating": "1.0.0",
+    "@molecule/api-templating": "1.0.2",
     "@types/mjml": "5.0.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/molecule-dev/molecule.git",
     "directory": "packages/api/bonds/templating/mjml"
   },
-  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/templating/mjml",
+  "homepage": "https://www.molecule.dev/packages/api-templating-mjml",
   "bugs": "https://github.com/molecule-dev/molecule/issues",
   "publishConfig": {
     "access": "public"