@aswin.dev/renderer 0.6.3

package/README.md

@@ -0,0 +1,91 @@
+# @aswin.dev/renderer
+
+> JSON → MJML renderer for Templatical email templates. Runs in the browser or on Node.
+
+[![npm version](https://img.shields.io/npm/v/@aswin.dev/renderer?label=npm&color=cb3837)](https://www.npmjs.com/package/@aswin.dev/renderer)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/templatical/sdk/blob/main/LICENSE-MIT)
+
+Converts Templatical's JSON template format into MJML, which you then compile to HTML using any [MJML library](https://mjml.io). Pure functions, zero runtime dependencies aside from `@templatical/types`.
+
+Use this on your backend to render templates server-side before sending email — or in the browser to preview before save.
+
+## Install
+
+```bash
+npm install @aswin.dev/renderer mjml
+```
+
+## Usage
+
+### Browser or Node — JSON → MJML
+
+```ts
+import { renderToMjml } from '@aswin.dev/renderer';
+import type { TemplateContent } from '@templatical/types';
+
+const content: TemplateContent = JSON.parse(stored);
+const mjml = await renderToMjml(content);
+```
+
+`renderToMjml` is async — it returns `Promise<string>`. Custom blocks may need async work to resolve, so the call always returns a promise even when content has none.
+
+### Node — MJML → HTML for sending
+
+```ts
+import { renderToMjml } from '@aswin.dev/renderer';
+import mjml2html from 'mjml';
+
+const mjml = await renderToMjml(content);
+const { html } = mjml2html(mjml);
+
+// Send via Postmark, Resend, SES, Mailgun, anything
+await mailer.send({ to, subject, html });
+```
+
+### With custom fonts
+
+```ts
+const mjml = await renderToMjml(content, {
+  customFonts: [
+    { name: 'Geist', url: 'https://fonts.googleapis.com/...' },
+  ],
+  defaultFallbackFont: 'Arial, sans-serif',
+  allowHtmlBlocks: true,
+});
+```
+
+### With custom blocks
+
+The renderer doesn't know how to render custom blocks on its own — you supply a callback. Editor consumers wire this automatically through `editor.toMjml()`. Headless callers provide their own resolver:
+
+```ts
+const mjml = await renderToMjml(content, {
+  async renderCustomBlock(block) {
+    // e.g. run the same liquid template the editor uses, against block.fieldValues
+    return await myLiquidEngine.render(block.customType, block.fieldValues);
+  },
+});
+```
+
+If you don't pass `renderCustomBlock`, the renderer falls back to the block's `renderedHtml` field (if any) and otherwise omits the block from output.
+
+## API
+
+- `renderToMjml(content, options?): Promise<string>` — render `TemplateContent` to an MJML string. Pair with the [`mjml`](https://www.npmjs.com/package/mjml) package to compile to final HTML.
+
+Options:
+- `customFonts` — `CustomFont[]` declarations rendered into `<mj-attributes>`
+- `defaultFallbackFont` — fallback when a block doesn't specify a font
+- `allowHtmlBlocks` — pass `false` to strip HTML blocks before render (e.g. for untrusted content)
+- `renderCustomBlock` — `(block: CustomBlock) => Promise<string>` — resolves custom blocks to HTML
+
+## Documentation
+
+- [How rendering works](https://docs.templatical.com/getting-started/how-rendering-works)
+- [Renderer API](https://docs.templatical.com/api/renderer-typescript)
+
+Full reference at **[docs.templatical.com](https://docs.templatical.com)**.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import { CustomFont, Block, ColumnLayout, SpacingValue, CustomBlock, TemplateContent } from '@templatical/types';
+
+/**
+ * Immutable context passed through the block rendering chain.
+ */
+declare class RenderContext {
+    readonly containerWidth: number;
+    readonly customFonts: CustomFont[];
+    readonly defaultFallbackFont: string;
+    readonly allowHtmlBlocks: boolean;
+    /**
+     * Map of custom block id → pre-rendered HTML, populated by `renderToMjml`
+     * before the synchronous render pass. Set when the consumer provides a
+     * `renderCustomBlock` option. Empty by default.
+     */
+    readonly customBlockHtml: ReadonlyMap<string, string>;
+    constructor(containerWidth: number, customFonts: CustomFont[], defaultFallbackFont: string, allowHtmlBlocks: boolean, 
+    /**
+     * Map of custom block id → pre-rendered HTML, populated by `renderToMjml`
+     * before the synchronous render pass. Set when the consumer provides a
+     * `renderCustomBlock` option. Empty by default.
+     */
+    customBlockHtml?: ReadonlyMap<string, string>);
+    /**
+     * Create a new context with a different container width.
+     * Used when rendering columns with narrower widths.
+     */
+    withContainerWidth(width: number): RenderContext;
+    /**
+     * Resolve a font family name to include custom font fallbacks.
+     * If the font matches a custom font, returns `'FontName', fallback`.
+     * Otherwise returns the original font family string.
+     */
+    resolveFontFamily(fontFamily: string): string;
+}
+
+/**
+ * Escape HTML special characters (& < > " ').
+ * Equivalent to PHP htmlspecialchars with ENT_QUOTES | ENT_HTML5.
+ */
+declare function escapeHtml(text: string): string;
+/**
+ * Escape a string for use in an HTML attribute value.
+ * Same implementation as escapeHtml for consistency with PHP.
+ */
+declare function escapeAttr(text: string): string;
+/**
+ * Replace merge tag span elements with their data attribute values.
+ * Converts `<span data-merge-tag="{{name}}">Label</span>` to `{{name}}`.
+ * Also handles `data-logic-merge-tag` attributes.
+ */
+declare function convertMergeTagsToValues(html: string): string;
+
+/**
+ * Check if a block is hidden on all viewports.
+ */
+declare function isHiddenOnAll(block: Block): boolean;
+/**
+ * Get the MJML css-class attribute string for visibility hiding.
+ * Returns a string like ` css-class="tpl-hide-desktop tpl-hide-tablet"` or empty string.
+ */
+declare function getCssClassAttr(block: Block): string;
+/**
+ * Get the CSS classes for visibility hiding.
+ */
+declare function getCssClasses(block: Block): string;
+
+/**
+ * Get width percentages for each column in a layout.
+ */
+declare function getWidthPercentages(layout: ColumnLayout): string[];
+/**
+ * Get width in pixels for each column in a layout.
+ */
+declare function getWidthPixels(layout: ColumnLayout, containerWidth: number): number[];
+
+/**
+ * Convert a SpacingValue to a CSS padding string like "10px 10px 10px 10px".
+ */
+declare function toPaddingString(padding: SpacingValue): string;
+
+/**
+ * Social icon SVG path data and brand colors for all supported platforms.
+ */
+declare const SOCIAL_ICONS: Record<string, {
+    path: string;
+    color: string;
+}>;
+/**
+ * Generate a base64-encoded SVG data URI for a social icon.
+ * Ported from SocialIconSvgGenerator.php.
+ */
+declare function generateSocialIconDataUri(platform: string, style: string, size: number): string;
+
+/**
+ * Render a single block to MJML markup.
+ * Dispatches to the appropriate block-type renderer.
+ */
+declare function renderBlock(block: Block, context: RenderContext): string;
+
+/**
+ * A function type that renders a single block to MJML markup.
+ */
+type BlockRenderer = (block: Block, context: RenderContext) => string;
+
+interface RenderOptions {
+    customFonts?: CustomFont[];
+    defaultFallbackFont?: string;
+    allowHtmlBlocks?: boolean;
+    /**
+     * Resolves custom blocks to their HTML representation. Called once per
+     * custom block in the content tree before MJML rendering. The renderer
+     * has no built-in knowledge of how to render custom blocks; consumers
+     * provide this function.
+     *
+     * Editor consumers: pass `editor.renderCustomBlock`.
+     *
+     * Headless consumers (Node.js, server, CLI): provide your own resolver,
+     * typically using the same liquid template + field values pipeline as
+     * the editor uses. If omitted, custom blocks fall back to
+     * `block.renderedHtml` (if present) and otherwise are omitted from the
+     * output.
+     */
+    renderCustomBlock?: (block: CustomBlock) => Promise<string>;
+}
+/**
+ * Render template content to an MJML string.
+ *
+ * The function is async because resolving custom blocks may require
+ * asynchronous work (e.g., the editor's liquid renderer dynamically imports
+ * `liquidjs`). When the content has no custom blocks or `renderCustomBlock`
+ * is omitted, no async work is performed but the function still resolves
+ * synchronously — i.e., it always returns a Promise.
+ */
+declare function renderToMjml(content: TemplateContent, options?: RenderOptions): Promise<string>;
+
+export { type BlockRenderer, RenderContext, type RenderOptions, SOCIAL_ICONS, convertMergeTagsToValues, escapeAttr, escapeHtml, generateSocialIconDataUri, getCssClassAttr, getCssClasses, getWidthPercentages, getWidthPixels, isHiddenOnAll, renderBlock, renderToMjml, toPaddingString };