@one-million-lines/email-builder 0.2.2 → 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/README.md

@@ -155,6 +155,49 @@ response is validated with Zod before it is applied. See
 [`src/ai/README.md`](./src/ai/README.md) and
 [`backend/README.md`](./backend/README.md).
 
+### Product search
+
+Connect product cards to your catalog. When a product provider is configured, a
+**Find** button appears on any product grid (and a search icon on each card).
+Searching opens a modal, previews the returned product, and — on **Save** —
+populates the card's fields (which stay fully editable afterwards).
+
+```tsx
+<EmailBuilder productEndpoint="http://localhost:3001/products/search" />
+```
+
+```ts
+import { registerPlugin, productSearchPlugin } from "@one-million-lines/email-builder";
+registerPlugin(productSearchPlugin({ endpoint: "http://localhost:3001/products/search" }));
+```
+
+The demo backend in [`backend/`](./backend) ships a `/products/search` endpoint
+over a small in-memory catalog. Product fields are `title`, `final_price`,
+`old_price` (optional), `description`, `link`, `image` and `stars` (optional).
+See [`src/plugins/productSearch/README.md`](./src/plugins/productSearch/README.md)
+for the wire protocol and response mapping.
+
+### Voucher select
+
+Let users pick a discount code from your backend instead of typing it. When a
+voucher provider is configured, selecting a **voucher block** (the built-in
+**Voucher Code** module, or any module with a `voucherCode` text element) shows a
+**Select voucher** dropdown that fills the code. The list is fetched once and
+cached (lazily, or eagerly with `preload`).
+
+```tsx
+<EmailBuilder voucherEndpoint="http://localhost:3001/vouchers" />
+```
+
+```ts
+import { registerPlugin, voucherPlugin } from "@one-million-lines/email-builder";
+registerPlugin(voucherPlugin({ endpoint: "http://localhost:3001/vouchers", preload: true }));
+```
+
+The demo backend ships a `GET /vouchers` endpoint. See
+[`src/plugins/voucherSelect/README.md`](./src/plugins/voucherSelect/README.md)
+for the wire protocol and response mapping.
+
 ### Styling & isolation
 
 The stylesheet at `@one-million-lines/email-builder/styles.css` is designed to

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<{
@@ -7,13 +7,52 @@ export interface AssetProvider {
         alt?: string;
     }>;
 }
+/**
+ * A single product returned by a {@link ProductProvider} search. Field names
+ * match the builder's `Product` model so results drop straight into a card.
+ */
+export interface ProductSearchResult {
+    name: string;
+    finalPrice: string;
+    oldPrice?: string;
+    description?: string;
+    link?: string;
+    image?: string;
+    imageAlt?: string;
+    stars?: number;
+    /** Optional external identifier echoed back from the backend. */
+    sku?: string;
+}
+export interface ProductProvider {
+    /** Look up a single product for a free-text query. Resolves null if none. */
+    search: (query: string) => Promise<ProductSearchResult | null>;
+}
+/** A discount/voucher entry returned by a {@link VoucherProvider}. */
+export interface Voucher {
+    /** Stable identifier (used to remember the selection). */
+    id: string;
+    /** Human label shown in the select dropdown. */
+    title: string;
+    /** The code (or merge tag) inserted into the voucher block. */
+    code: string;
+    /** Optional longer description. */
+    description?: string;
+}
+export interface VoucherProvider {
+    /** Load the list of vouchers to choose from. */
+    list: () => Promise<Voucher[]>;
+}
 export interface BuilderHandle {
     registerModule: (def: ModuleDefinition) => void;
     registerTheme: (theme: Theme) => void;
     registerAssetProvider: (provider: AssetProvider) => void;
+    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" | "ai-provider";
+export type PluginType = "modules" | "themes" | "asset-provider" | "product-provider" | "voucher-provider" | "ai-provider";
 export interface Plugin {
     name: string;
     type: PluginType;
@@ -23,4 +62,6 @@ export declare const builder: BuilderHandle;
 export declare function registerPlugin(plugin: Plugin): void;
 export declare function getRegisteredThemes(): Theme[];
 export declare function getAssetProvider(): AssetProvider | null;
+export declare function getProductProvider(): ProductProvider | null;
+export declare function getVoucherProvider(): VoucherProvider | null;
 export declare function getAIProvider(): AIProvider | null;

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;
@@ -18,7 +38,7 @@ export interface BaseStyle {
 export interface TextElement {
     id: string;
     type: "text";
-    role?: "headline" | "subheadline" | "body" | "caption";
+    role?: "headline" | "subheadline" | "body" | "caption" | "voucherCode";
     content: string;
     style?: BaseStyle & {
         fontFamily?: string;
@@ -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;
@@ -79,6 +105,8 @@ export interface Product {
     description?: string;
     link?: string;
     buttonLabel?: string;
+    /** Optional 0–5 rating. Rendered as star glyphs when the grid shows stars. */
+    stars?: number;
 }
 export interface ProductGridElement {
     id: string;
@@ -88,6 +116,8 @@ export interface ProductGridElement {
     showOldPrice: boolean;
     showButton: boolean;
     showDescription: boolean;
+    /** Show the star rating on each product card. Optional for back-compat. */
+    showStars?: boolean;
     buttonLabel?: string;
     style?: BaseStyle & {
         nameColor?: string;

package/dist/core/utils.d.ts

@@ -1,3 +1,10 @@
 export declare function uid(prefix?: string): string;
 export declare function escapeHtml(s: string): string;
 export declare function safeUrl(url: string | undefined): string;
+/** Default gold used for product star ratings. */
+export declare const STAR_COLOR = "#F5A623";
+/**
+ * Build a 5-glyph star string for a 0–5 rating (rounded to the nearest whole
+ * star). Uses ★ (full) and ☆ (empty) so it renders in any email client.
+ */
+export declare function starGlyphs(rating: number): 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;
@@ -44,11 +46,13 @@ export declare const moduleSchema: z.ZodObject<{
             description: z.ZodOptional<z.ZodString>;
             link: z.ZodOptional<z.ZodString>;
             buttonLabel: z.ZodOptional<z.ZodString>;
+            stars: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
         columns: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
         showOldPrice: z.ZodBoolean;
         showButton: z.ZodBoolean;
         showDescription: z.ZodBoolean;
+        showStars: z.ZodOptional<z.ZodBoolean>;
         buttonLabel: 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>], "type">>;
@@ -102,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;
@@ -130,11 +136,13 @@ export declare const documentSchema: z.ZodObject<{
                 description: z.ZodOptional<z.ZodString>;
                 link: z.ZodOptional<z.ZodString>;
                 buttonLabel: z.ZodOptional<z.ZodString>;
+                stars: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
             columns: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
             showOldPrice: z.ZodBoolean;
             showButton: z.ZodBoolean;
             showDescription: z.ZodBoolean;
+            showStars: z.ZodOptional<z.ZodBoolean>;
             buttonLabel: 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>], "type">>;