@one-million-lines/email-builder 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+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.
+
+## [Unreleased]
+
+### Added
+- npm library build (`dist/email-builder.js` ESM, `dist/email-builder.cjs` CommonJS).
+- Generated TypeScript declarations (`dist/index.d.ts` + per-module `.d.ts`).
+- Compiled stylesheet at `dist/styles.css`, imported via `openpostcards-builder/styles.css`.
+- `exports` map, `files` allowlist, and publishing metadata in `package.json`.
+- Library-only stylesheet (`src/lib.css`) that omits app `html/body/#root` globals.
+
+### Changed
+- `react` and `react-dom` are now **peer dependencies** (no longer bundled).
+- Runtime dependencies (`@dnd-kit/*`, `lucide-react`, `zod`, `zustand`) are
+  externalized from the bundle and declared as `dependencies`.
+
+## [0.1.0]
+
+### Added
+- Initial visual email builder: JSON document model, modules, templates, themes,
+  table-based HTML renderer, plugin hooks, React component, and vanilla factory.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Rada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# OpenPostcards AI Builder
+
+OpenPostcards AI Builder is a visual email builder for composing modular marketing emails from a JSON document model and exporting table-based HTML. It can run as a standalone app or be embedded into other products through a React component or a vanilla JavaScript wrapper.
+
+## What it does
+
+It gives users a drag-and-drop editor with reusable modules, themes, HTML export, and plugin hooks for extending the builder.
+
+## Why it exists
+
+Marketing teams often need a reusable editor that produces email-safe HTML without tying the editor to a specific CMS or backend. This project separates the editing experience, the JSON document model, and the final HTML renderer so it can be embedded elsewhere.
+
+## Features
+
+- Visual editor with top bar, left sidebar, canvas, and right sidebar
+- JSON-first email document model
+- Built-in modules, templates, and themes
+- Table-based HTML rendering for email output
+- Local autosave via Zustand store
+- React component API and vanilla JS factory
+- Plugin registration for modules and integrations
+- AI action pipeline that validates structured output with Zod before applying changes
+
+## How it works
+
+1. The app registers default modules and starter templates at load time.
+2. The email document lives in a Zustand store with import, export, and autosave support.
+3. The canvas and sidebars edit that shared document model.
+4. `renderEmailHtml()` converts the JSON document into table-based email HTML.
+5. Embedders can mount the editor with `EmailBuilder` or `createEmailBuilder()` and subscribe to document or HTML changes.
+
+## Tech stack
+
+- React
+- TypeScript
+- Vite
+- Zustand
+- Zod
+- dnd-kit
+
+## Project structure
+
+```text
+src/
+  core/             document types, renderer, validation, AI actions, plugins
+  editor/           top bar, sidebars, canvas
+  modules/          module registry and built-in modules
+  recommendations/  recommendation and fallback logic
+  store/            editor state and persistence
+  templates/        built-in email templates
+  themes/           theme definitions
+  plugins/          extension points, including image uploader helpers
+  index.ts          public API for embedding
+```
+
+## Install
+
+```bash
+npm install openpostcards-builder react react-dom
+```
+
+`react` and `react-dom` (v18 or v19) are **peer dependencies** — install them in
+your app; they are never bundled into the package.
+
+> **MANUAL ACTION REQUIRED:** `openpostcards-builder` is a placeholder package
+> name. Check availability and choose/reserve your own npm name before publishing,
+> then update `package.json` `name`, `repository`, `homepage`, and `bugs`.
+
+## Getting started
+
+```bash
+git clone <repo-url>
+cd email-builder
+npm install
+npm run dev
+```
+
+Open `http://localhost:5315`.
+
+## Configuration
+
+This project does not require environment variables for local development.
+
+The production build uses `/demo/email-builder/` as the Vite base path.
+
+## Usage
+
+React:
+
+```tsx
+import { EmailBuilder } from "openpostcards-builder";
+import "openpostcards-builder/styles.css";
+
+<EmailBuilder
+  initialDocument={emailJson}
+  onChange={(doc) => console.log(doc)}
+  onExportHtml={(html) => console.log(html)}
+/>;
+```
+
+Vanilla JS:
+
+```ts
+import { createEmailBuilder } from "openpostcards-builder";
+import "openpostcards-builder/styles.css";
+
+const instance = createEmailBuilder({
+  container: document.getElementById("builder")!,
+  initialDocument,
+  onChange(doc) {
+    console.log(doc);
+  },
+});
+
+// instance.getDocument(); instance.exportHtml(); instance.exportJson(); instance.destroy();
+```
+
+Always import the stylesheet once per app: `import "openpostcards-builder/styles.css";`
+
+### Framework integration
+
+Thin wrappers for each framework live in [`examples/`](./examples):
+
+- **React** — `examples/react/App.jsx`
+- **Vue 3** — `examples/vue/EmailBuilder.vue`
+- **Angular** — `examples/angular/email-builder.component.ts`
+- **Plain JS** — `examples/plain/index.html`
+
+Vue and Angular mount the React-based editor through the framework-neutral
+`createEmailBuilder()` factory (`getDocument` / `exportHtml` / `exportJson` /
+`destroy`). React and ReactDOM remain peer dependencies in all cases.
+
+### Styling & isolation
+
+The stylesheet at `openpostcards-builder/styles.css` includes Tailwind
+**Preflight**, a global CSS reset that normalizes `margin`, `box-sizing`,
+headings, lists, etc. When embedding into an existing design system this can
+affect host styles. Mitigations:
+
+- Load the editor in a dedicated route/page where the reset is acceptable, or
+- Scope/encapsulate it (e.g., render inside an iframe or a Shadow DOM host), or
+- Build your own Tailwind stylesheet without Preflight if your app already
+  provides resets.
+
+The editor root uses `h-screen w-screen`; place it in a full-size container.
+
+### Server-side rendering
+
+The package does not access `window`/`document` at import time, so it is safe to
+import in SSR frameworks. The editor itself is client-only — render it in an
+effect, or dynamically import it with SSR disabled in Next.js:
+
+```tsx
+import dynamic from "next/dynamic";
+
+const EmailBuilder = dynamic(
+  () => import("openpostcards-builder").then((m) => m.EmailBuilder),
+  { ssr: false }
+);
+```
+
+## Development
+
+```bash
+npm run dev           # standalone app
+npm run build         # build the library into dist/ (ESM + CJS + CSS + d.ts)
+npm test              # package-consumption tests (jsdom + React)
+npm run lint          # eslint
+npm run validate:pack # build + npm pack --dry-run
+npm run build:demo    # build the standalone demo app
+```
+
+## Building & publishing
+
+```bash
+npm run build              # produces dist/
+npm pack --dry-run         # inspect the tarball contents
+npm pack                   # create the .tgz to test in a consumer app
+```
+
+To publish (run manually):
+
+```bash
+# MANUAL ACTION REQUIRED — choose a real package name first, then:
+npm login
+npm publish --access public
+```
+
+`prepublishOnly` rebuilds the library automatically before publish.
+
+## Roadmap
+
+- Add persistence adapters beyond local storage
+- Add more production-ready media upload integrations
+- Add automated tests for document validation and HTML export
+- Add richer framework wrappers and packaging docs
+
+## Contributing
+
+This project is public and open for collaboration. If you’re interested in contributing, improving the project, or discussing ideas, feel free to reach out.
+
+LinkedIn: https://linkedin.com/in/alexrada
+
+1. Fork the repository
+2. Create a new branch
+3. Make your changes
+4. Open a pull request
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](./LICENSE).

package/dist/App.d.ts

@@ -0,0 +1 @@
+export declare function App(): import("react/jsx-runtime").JSX.Element;

package/dist/core/aiActions.d.ts

@@ -0,0 +1,52 @@
+import { EmailDocument, EmailModule, Theme } from '../core/types';
+export type AIAction = {
+    type: "update_meta";
+    patch: Partial<EmailDocument["meta"]>;
+} | {
+    type: "update_settings";
+    patch: Partial<EmailDocument["settings"]>;
+} | {
+    type: "apply_theme";
+    theme: Theme;
+} | {
+    type: "insert_module";
+    index?: number;
+    module: EmailModule;
+} | {
+    type: "delete_module";
+    moduleId: string;
+} | {
+    type: "update_module";
+    moduleId: string;
+    patch: Partial<EmailModule>;
+} | {
+    type: "update_element";
+    moduleId: string;
+    elementId: string;
+    patch: Record<string, unknown>;
+};
+export interface AIRequest {
+    task: "create_email" | "rewrite_text" | "generate_subject" | "generate_preview" | "translate" | "adapt_tone" | "apply_theme";
+    document?: EmailDocument;
+    instruction?: string;
+    context?: Record<string, unknown>;
+}
+export interface AIResponse {
+    actions?: AIAction[];
+    document?: EmailDocument;
+    text?: string;
+}
+export interface AIProvider {
+    generate(req: AIRequest): Promise<AIResponse>;
+}
+export declare function applyAIActions(doc: EmailDocument, actions: AIAction[]): EmailDocument;
+/** Validate an AI-returned document before applying. */
+export declare function validateAIDocument(doc: unknown): {
+    ok: true;
+    document: EmailDocument;
+} | {
+    ok: false;
+    error: string;
+};
+/** Mock AI provider for demos and tests. Returns deterministic patches. */
+export declare const mockAIProvider: AIProvider;

package/dist/core/plugins.d.ts

@@ -0,0 +1,26 @@
+import { ModuleDefinition } from '../modules/registry';
+import { Theme } from './types';
+import { AIProvider } from './aiActions';
+export interface AssetProvider {
+    upload: (file: File) => Promise<{
+        url: string;
+        alt?: string;
+    }>;
+}
+export interface BuilderHandle {
+    registerModule: (def: ModuleDefinition) => void;
+    registerTheme: (theme: Theme) => void;
+    registerAssetProvider: (provider: AssetProvider) => void;
+    setAIProvider: (provider: AIProvider) => void;
+}
+export type PluginType = "modules" | "themes" | "asset-provider" | "ai-provider";
+export interface Plugin {
+    name: string;
+    type: PluginType;
+    setup: (builder: BuilderHandle) => void;
+}
+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 getAIProvider(): AIProvider | null;

package/dist/core/renderer.d.ts

@@ -0,0 +1,2 @@
+import { EmailDocument } from './types';
+export declare function renderEmailHtml(doc: EmailDocument): string;

package/dist/core/theme.d.ts

@@ -0,0 +1,3 @@
+import { Theme } from './types';
+export declare function resolveToken(value: unknown, theme: Theme): unknown;
+export declare function resolveStyle(style: Record<string, unknown> | undefined | null, theme: Theme): Record<string, unknown>;

package/dist/core/types.d.ts

@@ -0,0 +1,150 @@
+export type ElementType = "text" | "image" | "button" | "spacer" | "divider" | "productGrid";
+export interface BaseStyle {
+    paddingTop?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    paddingRight?: number;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right";
+    borderRadius?: number;
+    border?: string;
+    hideOn?: "mobile" | "desktop";
+    /**
+     * Per-breakpoint overrides applied via @media (max-width:600px).
+     * Any field accepted by the owning element's style can be placed here.
+     */
+    mobile?: Record<string, unknown>;
+}
+export interface TextElement {
+    id: string;
+    type: "text";
+    role?: "headline" | "subheadline" | "body" | "caption";
+    content: string;
+    style?: BaseStyle & {
+        fontFamily?: string;
+        fontSize?: number;
+        lineHeight?: number;
+        letterSpacing?: number;
+        fontWeight?: number | string;
+        color?: string;
+        link?: string;
+    };
+}
+export interface ImageElement {
+    id: string;
+    type: "image";
+    src: string;
+    alt?: string;
+    link?: string;
+    style?: BaseStyle & {
+        width?: number;
+        height?: number;
+    };
+}
+export interface ButtonElement {
+    id: string;
+    type: "button";
+    label: string;
+    link: string;
+    style?: BaseStyle & {
+        backgroundColor?: string;
+        color?: string;
+        fontSize?: number;
+        fontFamily?: string;
+        fontWeight?: number | string;
+    };
+}
+export interface SpacerElement {
+    id: string;
+    type: "spacer";
+    height: number;
+}
+export interface DividerElement {
+    id: string;
+    type: "divider";
+    style?: {
+        color?: string;
+        thickness?: number;
+        paddingTop?: number;
+        paddingBottom?: number;
+    };
+}
+export interface Product {
+    id: string;
+    image: string;
+    imageAlt?: string;
+    name: string;
+    oldPrice?: string;
+    finalPrice: string;
+    description?: string;
+    link?: string;
+    buttonLabel?: string;
+}
+export interface ProductGridElement {
+    id: string;
+    type: "productGrid";
+    products: Product[];
+    columns: 1 | 2 | 3;
+    showOldPrice: boolean;
+    showButton: boolean;
+    showDescription: boolean;
+    buttonLabel?: string;
+    style?: BaseStyle & {
+        nameColor?: string;
+        finalPriceColor?: string;
+        oldPriceColor?: string;
+        buttonBackgroundColor?: string;
+        buttonColor?: string;
+        gap?: number;
+        cardBackgroundColor?: string;
+        borderRadius?: number;
+        align?: "left" | "center" | "right";
+    };
+}
+export type EmailElement = TextElement | ImageElement | ButtonElement | SpacerElement | DividerElement | ProductGridElement;
+export interface EmailModule {
+    id: string;
+    type: string;
+    name: string;
+    style?: BaseStyle;
+    children: EmailElement[];
+    /** Free-form per-module data used by plugins (e.g. `recommendations` logic). */
+    data?: Record<string, unknown>;
+}
+export interface ThemeTokens {
+    colors: Record<string, string>;
+    fonts: Record<string, string>;
+    spacing: Record<string, number>;
+    radius: Record<string, number>;
+}
+export interface Theme {
+    id: string;
+    name: string;
+    tokens: ThemeTokens;
+}
+export interface EmailSettings {
+    width: number;
+    backgroundColor: string;
+    contentBackgroundColor: string;
+}
+export interface EmailMeta {
+    name: string;
+    previewText: string;
+}
+export interface EmailDocument {
+    version: string;
+    meta: EmailMeta;
+    theme: Theme;
+    settings: EmailSettings;
+    modules: EmailModule[];
+}
+export type Selection = {
+    kind: "email";
+} | {
+    kind: "module";
+    moduleId: string;
+} | {
+    kind: "element";
+    moduleId: string;
+    elementId: string;
+} | null;

package/dist/core/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function uid(prefix?: string): string;
+export declare function escapeHtml(s: string): string;
+export declare function safeUrl(url: string | undefined): string;