@marlinjai/email-editor-blocks 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,456 @@
+import * as _marlinjai_email_editor_core from '@marlinjai/email-editor-core';
+import { BlockDefinition, TextBlock, ImageBlock, ButtonBlock, DividerBlock, SpacerBlock, SocialBlock, HeroBlock, AccordionBlock, RawBlock, NavbarBlock, CarouselBlock, TableBlock, FooterBlock, HeaderBlock, PrebuiltTemplate } from '@marlinjai/email-editor-core';
+
+/**
+ * How a host tells this package where its own placeholder images live.
+ *
+ * Every section and every block default ships with a `data:` URI placeholder,
+ * which renders in the editor's canvas and needs nothing behind it. A host that
+ * sends real mail wants something better, because Gmail and Outlook.com do not
+ * render `data:` images and because a workspace may refuse every address but
+ * its service's own. Giving the base here swaps them all for
+ * `<base>/p/<width>x<height>.png`.
+ */
+type PlaceholderOptions = {
+    /** An origin with no trailing slash, e.g. `https://mail.example.com`. Absent keeps the `data:` URIs. */
+    placeholderBase?: string;
+};
+/**
+ * A deep copy of `value` with every placeholder address swapped for one on
+ * `base`. Anything that is not a placeholder is left exactly as it was, so this
+ * is safe to run over a whole section tree or a block's default props.
+ *
+ * Copied rather than edited in place because the built-in sections are module
+ * level constants shared by every editor on the page: two editors with
+ * different hosts must not fight over them.
+ */
+declare function withHostedPlaceholders<T>(value: T, base: string | undefined): T;
+
+/**
+ * Create a registry with all standard blocks pre-registered
+ */
+declare function createStandardBlockRegistry(options?: PlaceholderOptions): _marlinjai_email_editor_core.BlockRegistryImpl;
+
+/**
+ * Text block definition
+ * Uses TipTap for rich text editing
+ */
+declare const textBlockDefinition: BlockDefinition<TextBlock>;
+
+/**
+ * Image block definition
+ */
+declare const imageBlockDefinition: BlockDefinition<ImageBlock>;
+
+/**
+ * Button block definition
+ */
+declare const buttonBlockDefinition: BlockDefinition<ButtonBlock>;
+
+/**
+ * Divider block definition
+ */
+declare const dividerBlockDefinition: BlockDefinition<DividerBlock>;
+
+/**
+ * Spacer block definition
+ */
+declare const spacerBlockDefinition: BlockDefinition<SpacerBlock>;
+
+/**
+ * Platform brand colors for social icons (exported for UI use)
+ */
+declare const SOCIAL_COLORS: Record<string, string>;
+/**
+ * Social icons block definition
+ * Renders as buttons with icon images instead of mj-social for reliable sizing
+ */
+declare const socialBlockDefinition: BlockDefinition<SocialBlock>;
+
+/**
+ * Hero block definition
+ */
+declare const heroBlockDefinition: BlockDefinition<HeroBlock>;
+
+/**
+ * Accordion block definition
+ * Maps to MJML's <mj-accordion> component
+ */
+declare const accordionBlockDefinition: BlockDefinition<AccordionBlock>;
+
+/**
+ * Raw HTML block definition
+ * Maps to MJML's <mj-raw> component
+ */
+declare const rawBlockDefinition: BlockDefinition<RawBlock>;
+
+/**
+ * Navbar block definition
+ * Creates a responsive navigation menu with optional hamburger mode
+ */
+declare const navbarBlockDefinition: BlockDefinition<NavbarBlock>;
+
+/**
+ * Carousel block definition
+ * Creates an interactive image gallery with optional thumbnails
+ */
+declare const carouselBlockDefinition: BlockDefinition<CarouselBlock>;
+
+/**
+ * Table block definition
+ * Creates a data table for displaying structured information
+ */
+declare const tableBlockDefinition: BlockDefinition<TableBlock>;
+
+/**
+ * Locked header block
+ */
+declare const headerBlockDefinition: BlockDefinition<HeaderBlock>;
+/**
+ * Locked footer block
+ *
+ * The unsubscribe link and nothing else: a locked block cannot be corrected by
+ * whoever sends the mail, so it must not claim a copyright holder or a company
+ * name that is not theirs.
+ */
+declare const footerBlockDefinition: BlockDefinition<FooterBlock>;
+
+/**
+ * A neutral grey palette. It carries no brand: it is a starting point a host
+ * overrides with its own colours.
+ */
+declare const PALETTE: {
+    readonly primary: "#374151";
+    readonly primaryDark: "#111827";
+    readonly primaryLight: "#9ca3af";
+    readonly bgMuted: "#f5f5f5";
+    readonly bgWhite: "#ffffff";
+    readonly bgLight: "#fafafa";
+    readonly textDark: "#111827";
+    readonly textBody: "#4b5563";
+    readonly textLight: "#9ca3af";
+    readonly textWhite: "#ffffff";
+    readonly border: "#e5e7eb";
+    readonly divider: "#d1d5db";
+};
+/**
+ * Typography styles built from fonts every mail client already has, so a
+ * section renders as intended without loading a webfont (which `service_only`
+ * would refuse anyway).
+ */
+declare const TYPOGRAPHY: {
+    readonly h1: "font-family: Helvetica, Arial, sans-serif; font-weight: 700; font-size: 32px; line-height: 1.2;";
+    readonly h2: "font-family: Helvetica, Arial, sans-serif; font-weight: 700; font-size: 26px; line-height: 1.3;";
+    readonly h3: "font-family: Helvetica, Arial, sans-serif; font-weight: 600; font-size: 21px; line-height: 1.4;";
+    readonly h4: "font-family: Helvetica, Arial, sans-serif; font-weight: 600; font-size: 18px; line-height: 1.4;";
+    readonly body: "font-family: Helvetica, Arial, sans-serif; font-size: 16px; line-height: 1.6;";
+    readonly bodySmall: "font-family: Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.5;";
+    readonly caption: "font-family: Helvetica, Arial, sans-serif; font-size: 12px; line-height: 1.4;";
+    readonly signature: "font-family: Georgia, \"Times New Roman\", serif; font-style: italic; font-size: 22px;";
+    readonly label: "font-family: Helvetica, Arial, sans-serif; font-size: 11px; letter-spacing: 1.5px; text-transform: uppercase;";
+    readonly price: "font-family: Georgia, \"Times New Roman\", serif; font-weight: 600;";
+};
+/**
+ * A grey rectangle of the given size as a `data:` URI, used wherever a section
+ * needs an image the host has not chosen yet.
+ *
+ * It is a `data:` URI rather than an address on an image host for two reasons:
+ * a workspace whose `asset_policy` is `service_only` refuses every remote
+ * address at compile, so a section built on one could be inserted but never
+ * sent; and a placeholder should not make a reader's mail client call a third
+ * party. The `viewBox` carries the intended aspect ratio, so a block that sets
+ * only a width still lays out as designed.
+ *
+ * Gmail and Outlook.com do not render `data:` URIs, so a placeholder left in a
+ * sent mail shows as an empty frame there rather than a grey box. That is the
+ * point: the alt text says it must be replaced.
+ */
+declare function placeholderImage(width: number, height: number): string;
+/**
+ * The size a placeholder from {@link placeholderImage} was made at, or null for
+ * anything else.
+ *
+ * The encoder and this decoder are a pair and live together on purpose: this is
+ * the one place that knows the format, so a host can swap every placeholder for
+ * one served from its own address without the 35 built-in sections having to be
+ * rebuilt as functions of that address. See {@link hostedPlaceholder}.
+ */
+declare function placeholderSize(src: string): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * The same placeholder as an address on `base`, the host's own origin, or the
+ * value unchanged when it is not a placeholder.
+ *
+ * Why a host would want this, and why the `data:` URI is still the default:
+ *
+ *  - **Gmail and Outlook.com do not render `data:` images.** A placeholder that
+ *    survived into a sent mail would be invisible there rather than obviously
+ *    wrong, which is the worse of the two failures.
+ *  - **A workspace may refuse every address but its service's own.** That is
+ *    what Lumitra Mail's `service_only` asset policy does, and it is why the
+ *    placeholder cannot simply point at an image host: the section would insert
+ *    and the mail would never send.
+ *
+ * So the address has to come from the host, which is the only thing that knows
+ * it. A consumer of this package with no service behind it passes nothing and
+ * keeps the `data:` URI, which renders in the editor's own canvas, where it is
+ * the only thing that has to work.
+ *
+ * `base` is an origin with no trailing slash, e.g. `https://mail.example.com`.
+ */
+declare function hostedPlaceholder(src: string, base: string | undefined): string;
+/** The alt text every placeholder image carries, so a reader knows why it is empty. */
+declare const PLACEHOLDER_ALT = "Placeholder image, replace with your own";
+/**
+ * Placeholder copy for the built-in sections. Every line reads as something to
+ * replace rather than as finished text, and no line names anybody: there is no
+ * company, no person and no email address here.
+ */
+declare const PLACEHOLDER: {
+    readonly companyName: "Your company";
+    readonly tagline: "Your tagline goes here";
+    readonly ownerName: "Your name";
+    readonly ownerTitle: "Your title";
+    readonly ownerContact: "Your email address";
+    readonly ctaBookSession: "Book now";
+    readonly ctaLearnMore: "Learn more";
+    readonly ctaReadMore: "Read more";
+    readonly ctaGetStarted: "Get started";
+    readonly ctaExplore: "Explore more";
+    readonly headlines: readonly ["Your headline here", "A second headline", "A third headline", "One, two, three.", "Your subject in a few words"];
+    readonly bodyText: {
+        readonly intro: "A short paragraph introducing this section. Replace it with your own text, and keep it to a couple of sentences so it stays readable on a phone.";
+        readonly destination: "A closing line that says what the reader gets out of it.";
+        readonly welcome: "Thank you for subscribing. Replace this paragraph with a welcome in your own words.";
+    };
+    readonly closing: {
+        readonly gratitude: "With kind regards,";
+        readonly signature: "Your name";
+    };
+    readonly footer: {
+        readonly unsubscribe: "If you no longer wish to receive these emails, you can";
+        readonly unsubscribeLink: "unsubscribe here";
+        readonly received: "You received this email because you subscribed to this newsletter.";
+    };
+    readonly logoUrl: string;
+    readonly website: "https://example.com";
+};
+/**
+ * Helper function to create styled heading HTML
+ */
+declare function styledHeading(text: string, level?: 1 | 2 | 3 | 4): string;
+/**
+ * Helper function to create styled body text HTML
+ */
+declare function styledBody(text: string, centered?: boolean): string;
+/**
+ * Helper function to create styled label HTML
+ */
+declare function styledLabel(text: string): string;
+
+/**
+ * Hero Main - Full-width with background image
+ * A full-width hero: a heading, one line of copy and a button.
+ */
+declare const heroMainTemplate: PrebuiltTemplate;
+/**
+ * Hero Newsletter Header - Centered logo + welcome
+ * Based on the newsletter header screenshot provided
+ */
+declare const heroNewsletterTemplate: PrebuiltTemplate;
+/**
+ * Hero Minimal - Clean with divider
+ */
+declare const heroMinimalTemplate: PrebuiltTemplate;
+/**
+ * Hero Split - Image and text side by side
+ */
+declare const heroSplitTemplate: PrebuiltTemplate;
+declare const heroTemplates: PrebuiltTemplate[];
+
+/**
+ * Text + Image Right - Image on the right side
+ * Like "Hiking Sequoia" example in Mailjet
+ */
+declare const textImageRightTemplate: PrebuiltTemplate;
+/**
+ * Text + Image Left - Image on the left side
+ * Like "Trail to Machu Picchu" example in Mailjet
+ */
+declare const textImageLeftTemplate: PrebuiltTemplate;
+/**
+ * Section Title 1 - Simple centered headline with body
+ * Like "The Scottish Highlands" example
+ */
+declare const sectionTitle1Template: PrebuiltTemplate;
+/**
+ * Section Title 2 - With button
+ * Like "Scottish Highlands with Buy now" example
+ */
+declare const sectionTitle2Template: PrebuiltTemplate;
+/**
+ * Section Title 3 - Colored background
+ * Like red "Other Adventure Styles" example
+ */
+declare const sectionTitle3Template: PrebuiltTemplate;
+/**
+ * Quote Block - Testimonial or inspirational quote
+ */
+declare const quoteBlockTemplate: PrebuiltTemplate;
+/**
+ * Simple Divider Section
+ */
+declare const dividerSectionTemplate: PrebuiltTemplate;
+/**
+ * Spacer Section
+ */
+declare const spacerSectionTemplate: PrebuiltTemplate;
+declare const contentTemplates: PrebuiltTemplate[];
+
+/**
+ * Features 2-Column - Two feature boxes side by side
+ * Like "A breath of fresh air / Unplug and unwind" example
+ */
+declare const features2ColTemplate: PrebuiltTemplate;
+/**
+ * Features 3-Column - Three feature boxes
+ * Like "Wild beauty / Fresh adventure / Natural wonder" example
+ */
+declare const features3ColTemplate: PrebuiltTemplate;
+/**
+ * Features 4-Column (2x2 Grid) - Four features in a grid
+ * Like "Open horizon / Rugged terrain / Coastal charm / Outdoor escape" example
+ */
+declare const features4ColTemplate: PrebuiltTemplate;
+/**
+ * Features 4-Column Row 2 (continuation of grid)
+ */
+declare const features4ColRow2Template: PrebuiltTemplate;
+/**
+ * Take Action / CTA Section
+ * Like "Organized Adventures: What are they?" example
+ */
+declare const takeActionTemplate: PrebuiltTemplate;
+declare const featureTemplates: PrebuiltTemplate[];
+
+/**
+ * Event Simple - Basic event details
+ */
+declare const eventSimpleTemplate: PrebuiltTemplate;
+/**
+ * Event with Image - Event card with visual
+ * Like "Travel Talks Lecture" example
+ */
+declare const eventImageTemplate: PrebuiltTemplate;
+/**
+ * Coupon Discount - Discount offer with code
+ * Like "-50% THANKYOU50" example
+ */
+declare const couponDiscountTemplate: PrebuiltTemplate;
+/**
+ * Coupon Gift Card - Gift card style
+ * Like the "Gift card HBD2U" example
+ */
+declare const couponGiftCardTemplate: PrebuiltTemplate;
+/**
+ * Coupon Banner - Simple banner with code
+ * Like the "FIRESIDE40" red banner example
+ */
+declare const couponBannerTemplate: PrebuiltTemplate;
+/**
+ * Product Right - Service with image on right
+ * Like "Nitro Weekender Backpack" example
+ */
+declare const productRightTemplate: PrebuiltTemplate;
+/**
+ * Product Left - Service with image on left
+ */
+declare const productLeftTemplate: PrebuiltTemplate;
+/**
+ * Products 2-Column - Two services side by side
+ */
+declare const products2ColTemplate: PrebuiltTemplate;
+/**
+ * Products 3-Column - Three services in a row
+ */
+declare const products3ColTemplate: PrebuiltTemplate;
+declare const marketingTemplates: PrebuiltTemplate[];
+
+/**
+ * Signature 1 - Simple name + title
+ * Like "John Doe, CEO of Falcon" example
+ */
+declare const signature1Template: PrebuiltTemplate;
+/**
+ * Signature 2 - Centered with signature image
+ * Like centered "John Doe" with cursive signature
+ */
+declare const signature2Template: PrebuiltTemplate;
+/**
+ * Signature 3 - With email and phone
+ * Like "Mary Johnson" with contact info
+ */
+declare const signature3Template: PrebuiltTemplate;
+/**
+ * Signature 4 - Full signature with closing
+ * A signature with a name, a title and a line of contact details
+ */
+declare const signature4Template: PrebuiltTemplate;
+/**
+ * Dual Buttons - Two side-by-side CTAs
+ * Like "Book tour right now / Save tour for later" example
+ */
+declare const buttonsDualTemplate: PrebuiltTemplate;
+/**
+ * App Download - App store badges
+ * Like the Apple/Google Play example
+ */
+declare const appDownloadTemplate: PrebuiltTemplate;
+/**
+ * Footer Standard - Newsletter footer with unsubscribe
+ * A footer with the sender's name, a divider and the unsubscribe line
+ */
+declare const footerStandardTemplate: PrebuiltTemplate;
+/**
+ * Footer with Social - Footer including social icons
+ */
+declare const footerSocialTemplate: PrebuiltTemplate;
+/**
+ * Footer Links - Footer with navigation links
+ */
+declare const footerLinksTemplate: PrebuiltTemplate;
+declare const utilityTemplates: PrebuiltTemplate[];
+
+/**
+ * All pre-built templates organized by category
+ *
+ * Categories:
+ * - hero (4): Main, Newsletter, Minimal, Split
+ * - content (8): Text+Image Right/Left, Section Titles 1-3, Quote, Divider, Spacer
+ * - features (5): 2-col, 3-col, 4-col, 4-col row 2, Take Action
+ * - marketing (9): Events (2), Coupons (3), Products/Services (4)
+ * - utility (9): Signatures (4), Buttons, App Download, Footers (3)
+ *
+ * Total: 35 templates
+ */
+declare const allPrebuiltTemplates: _marlinjai_email_editor_core.PrebuiltTemplate[];
+/**
+ * Get templates by category
+ */
+declare function getTemplatesByCategory(category: string): _marlinjai_email_editor_core.PrebuiltTemplate[];
+/**
+ * Template categories with display names
+ */
+declare const templateCategories: {
+    id: string;
+    name: string;
+    count: number;
+}[];
+/**
+ * Create a pre-built template registry with all built-in, brand-neutral sections
+ */
+declare function createStandardPrebuiltRegistry(options?: PlaceholderOptions): _marlinjai_email_editor_core.PrebuiltTemplateRegistry;
+
+export { PALETTE, PLACEHOLDER, PLACEHOLDER_ALT, type PlaceholderOptions, SOCIAL_COLORS, TYPOGRAPHY, accordionBlockDefinition, allPrebuiltTemplates, appDownloadTemplate, buttonBlockDefinition, buttonsDualTemplate, carouselBlockDefinition, contentTemplates, couponBannerTemplate, couponDiscountTemplate, couponGiftCardTemplate, createStandardPrebuiltRegistry as createPrebuiltRegistry, createStandardBlockRegistry, createStandardPrebuiltRegistry, dividerBlockDefinition, dividerSectionTemplate, eventImageTemplate, eventSimpleTemplate, featureTemplates, features2ColTemplate, features3ColTemplate, features4ColRow2Template, features4ColTemplate, footerBlockDefinition, footerLinksTemplate, footerSocialTemplate, footerStandardTemplate, getTemplatesByCategory, headerBlockDefinition, heroBlockDefinition, heroMainTemplate, heroMinimalTemplate, heroNewsletterTemplate, heroSplitTemplate, heroTemplates, hostedPlaceholder, imageBlockDefinition, marketingTemplates, navbarBlockDefinition, placeholderImage, placeholderSize, productLeftTemplate, productRightTemplate, products2ColTemplate, products3ColTemplate, quoteBlockTemplate, rawBlockDefinition, sectionTitle1Template, sectionTitle2Template, sectionTitle3Template, signature1Template, signature2Template, signature3Template, signature4Template, socialBlockDefinition, spacerBlockDefinition, spacerSectionTemplate, styledBody, styledHeading, styledLabel, tableBlockDefinition, takeActionTemplate, templateCategories, textBlockDefinition, textImageLeftTemplate, textImageRightTemplate, utilityTemplates, withHostedPlaceholders };