@one-million-lines/email-builder 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to this package are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/) and the
 [Keep a Changelog](https://keepachangelog.com/) format.
 
+## [0.4.0] — 2026-09-03
+
+### Added
+
+- **Special link types** — links can now be tagged with a semantic `linkType`
+  (`"unsubscribe"`, `"view_in_browser"`, `"manage_preferences"`, `"user_profile"`).
+  The rendered HTML carries both a `data-link-type` attribute on the anchor element
+  **and** a placeholder href value (e.g. `{{unsubscribe_url}}`), giving backend
+  processors two independent ways to locate and replace per-recipient URLs.
+  - New `SpecialLinkType` union type and `SPECIAL_LINK_PLACEHOLDERS` map exported
+    from `core/types`.
+  - `linkType` field added to `ButtonElement` and `ImageElement` (top-level), and
+    to `TextElement.style` (alongside the existing `link`).
+  - `text()`, `button()`, and `muted()` helpers accept a `linkType` option.
+  - New `footerLinks(links, opts?)` helper creates a text element with multiple
+    inline `<a>` tags, each carrying `data-link-type` — ideal for footer lines
+    that combine "Unsubscribe · View in browser".
+  - All built-in footer modules updated to use `footerLinks()` and proper
+    `linkType` values instead of plain text.
+  - Right sidebar: **Link role** dropdown added below the Link URL field for
+    Text, Image, and Button elements. Selecting a role auto-fills the placeholder
+    URL.
+  - `safeUrl()` updated to pass through `{{...}}` placeholder URLs without
+    stripping them.
+  - Validation schema updated to accept `linkType` on image and button elements.
+
+- **Merge tags / personalisation tokens** — dynamic content placeholders can
+  now be configured and inserted directly from the editor sidebar.
+  - New `MergeTag` interface: `{ attribute: string; title: string }`.
+  - New `mergeTags` prop on `<EmailBuilder>` (React) and `createEmailBuilder`
+    (vanilla) accepts an array of merge tag definitions.
+  - New `builder.registerMergeTags(tags)` method on `BuilderHandle` for plugin
+    authors.
+  - New `useMergeTagsStore` reactive store (`src/plugins/mergeTags/state.ts`).
+  - Right sidebar: **Insert merge tag** dropdown appears in the Text element
+    panel when merge tags are configured. Selecting one appends
+    `{attribute}` to the text content.
+  - `MergeTag` exported from the public API.
+
+- **Template & block authoring guide** (`src/templates/TEMPLATE_GUIDE.md`) —
+  comprehensive, AI-agent-ready reference documenting:
+  - The full `EmailDocument` JSON schema
+  - All element types and their style options
+  - Module structure, categories, and naming conventions
+  - Theme tokens and how to reference them
+  - All helper functions with options tables
+  - Special link types and merge tags
+  - Step-by-step instructions for creating new templates and module definitions
+  - A complete template code example
+  - A commit checklist and AI agent prompt template
+
 ## [Unreleased]
 
 ### Added

package/dist/core/plugins.d.ts

@@ -1,5 +1,5 @@
 import { ModuleDefinition } from '../modules/registry';
-import { Theme } from './types';
+import { Theme, MergeTag } from './types';
 import { AIProvider } from './aiActions';
 export interface AssetProvider {
     upload: (file: File) => Promise<{
@@ -49,6 +49,8 @@ export interface BuilderHandle {
     registerProductProvider: (provider: ProductProvider) => void;
     registerVoucherProvider: (provider: VoucherProvider) => void;
     setAIProvider: (provider: AIProvider) => void;
+    /** Configure the list of merge tags available in the text element sidebar. */
+    registerMergeTags: (tags: MergeTag[]) => void;
 }
 export type PluginType = "modules" | "themes" | "asset-provider" | "product-provider" | "voucher-provider" | "ai-provider";
 export interface Plugin {

package/dist/core/types.d.ts

@@ -1,4 +1,24 @@
 export type ElementType = "text" | "image" | "button" | "spacer" | "divider" | "productGrid";
+/**
+ * Marks a link as a well-known system link. Backend processors replace the
+ * placeholder href (e.g. `{{unsubscribe_url}}`) with a real per-recipient URL.
+ * The rendered HTML also carries a `data-link-type` attribute so backends that
+ * parse HTML can find and replace these links without inspecting the JSON.
+ */
+export type SpecialLinkType = "unsubscribe" | "view_in_browser" | "manage_preferences" | "user_profile";
+/** Placeholder href values automatically set when a SpecialLinkType is chosen. */
+export declare const SPECIAL_LINK_PLACEHOLDERS: Record<SpecialLinkType, string>;
+/**
+ * A merge tag / personalisation token. Configured via the `mergeTags` prop on
+ * `<EmailBuilder>` or via `builder.registerMergeTags(tags)`.
+ * When the user picks a tag, `{attribute}` is inserted into the text content.
+ */
+export interface MergeTag {
+    /** Dot-notation path used as the placeholder, e.g. `"user.firstname"`. */
+    attribute: string;
+    /** Human-readable label shown in the sidebar dropdown, e.g. `"First name"`. */
+    title: string;
+}
 export interface BaseStyle {
     paddingTop?: number;
     paddingBottom?: number;
@@ -28,6 +48,8 @@ export interface TextElement {
         fontWeight?: number | string;
         color?: string;
         link?: string;
+        /** Marks the element link as a well-known system link (e.g. unsubscribe). */
+        linkType?: SpecialLinkType;
     };
 }
 export interface ImageElement {
@@ -36,6 +58,8 @@ export interface ImageElement {
     src: string;
     alt?: string;
     link?: string;
+    /** Marks the image link as a well-known system link. */
+    linkType?: SpecialLinkType;
     style?: BaseStyle & {
         width?: number;
         height?: number;
@@ -46,6 +70,8 @@ export interface ButtonElement {
     type: "button";
     label: string;
     link: string;
+    /** Marks the button link as a well-known system link. */
+    linkType?: SpecialLinkType;
     style?: BaseStyle & {
         backgroundColor?: string;
         color?: string;

package/dist/core/validation.d.ts

@@ -16,12 +16,14 @@ export declare const moduleSchema: z.ZodObject<{
         src: z.ZodString;
         alt: z.ZodOptional<z.ZodString>;
         link: z.ZodOptional<z.ZodString>;
+        linkType: z.ZodOptional<z.ZodString>;
         style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodAny>]>>>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
         type: z.ZodLiteral<"button">;
         label: z.ZodString;
         link: z.ZodString;
+        linkType: z.ZodOptional<z.ZodString>;
         style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodAny>]>>>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;
@@ -104,12 +106,14 @@ export declare const documentSchema: z.ZodObject<{
             src: z.ZodString;
             alt: z.ZodOptional<z.ZodString>;
             link: z.ZodOptional<z.ZodString>;
+            linkType: z.ZodOptional<z.ZodString>;
             style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodAny>]>>>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
             type: z.ZodLiteral<"button">;
             label: z.ZodString;
             link: z.ZodString;
+            linkType: z.ZodOptional<z.ZodString>;
             style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodAny>]>>>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;