email-builder-online 4.1.4 → 4.1.5

package/README.md

@@ -775,6 +775,122 @@ interface AIFeatureRequest {
 }
 ```
 
+## Block Schemas & Validation (`@eb/document-core`)
+
+All block schemas, the document-level schema, and the validation logic are exported from the `@eb/document-core` package. This package has **zero browser dependencies** (only `zod`) and is safe to use in Node.js processes — designed for MCP servers, backend scripts, and CLI tools.
+
+### Installation
+
+```bash
+# Within the monorepo (workspace protocol)
+pnpm add @eb/document-core
+```
+
+### Schemas
+
+```ts
+import {
+  // Composite schemas
+  EditorBlockSchema,          // z.discriminatedUnion of all 9 block types
+  EditorConfigurationSchema,  // z.record(string, EditorBlockSchema) — full document
+  BLOCK_TYPES,                // ['EmailLayout', 'Container', ...] as const
+
+  // Individual block schemas
+  ButtonPropsSchema,
+  ColumnsContainerPropsSchema,
+  ContainerPropsSchema,
+  DividerPropsSchema,
+  EmailLayoutPropsSchema,
+  ImagePropsSchema,
+  NotionTextPropsSchema,
+  SocialMediaPropsSchema,
+  SpacerPropsSchema,
+
+  // Primitives (shared across blocks)
+  COLOR_SCHEMA,
+  PADDING_SCHEMA,
+  FONT_FAMILY_SCHEMA,
+  FONT_FAMILY_NAMES,
+  SHAPE_SCHEMA,
+
+  // Types
+  type TEditorBlock,
+  type TEditorConfiguration,
+  type BlockType,
+} from '@eb/document-core';
+```
+
+### Validation
+
+```ts
+import { validateDocument, type ValidationResult } from '@eb/document-core';
+
+const result: ValidationResult = validateDocument(jsonDocument);
+
+if (result.ok) {
+  // result.data is a valid TEditorConfiguration
+  console.log('Valid document with', Object.keys(result.data).length, 'blocks');
+} else {
+  // result.issues is string[] of human-readable errors
+  console.error('Validation failed:', result.issues);
+}
+```
+
+`validateDocument()` runs **3 layers** that mirror the editor's own validation:
+
+1. **Zod schema parse** — every block conforms to its type-specific schema (props, enums, ranges).
+2. **Root invariant** — a `root` key must exist with `type: "EmailLayout"`.
+3. **Structural integrity** — every `childrenIds` reference points to an existing block.
+
+A document that passes `validateDocument()` is guaranteed to load in the editor via `resetDocument()`.
+
+### Document Format
+
+The document is a flat `Record<blockId, TEditorBlock>`:
+
+```json
+{
+  "root": {
+    "type": "EmailLayout",
+    "data": {
+      "backdropColor": "#F5F5F5",
+      "canvasColor": "#FFFFFF",
+      "textColor": "#262626",
+      "fontFamily": "MODERN_SANS",
+      "childrenIds": ["block-1"]
+    }
+  },
+  "block-1": {
+    "type": "Container",
+    "data": {
+      "style": { "backgroundColor": "#FFFFFF", "padding": { "top": 16, "bottom": 16, "left": 24, "right": 24 } },
+      "props": { "childrenIds": ["block-2"] }
+    }
+  },
+  "block-2": {
+    "type": "NotionText",
+    "data": {
+      "style": { "fontSize": 16, "padding": { "top": 16, "bottom": 16, "left": 24, "right": 24 } },
+      "props": { "html": "<p>Hello world</p>" }
+    }
+  }
+}
+```
+
+### Valid Block Types
+
+| Type | Description |
+|------|-------------|
+| `EmailLayout` | Root block (exactly one, keyed as `root`) |
+| `Container` | Section wrapper with `childrenIds` |
+| `ColumnsContainer` | 2–3 column layout with `columns[].childrenIds` |
+| `NotionText` | Rich text (HTML string in `props.html`) |
+| `Button` | CTA button with text, URL, colors |
+| `Image` | Image with URL, alt, alignment |
+| `Divider` | Horizontal rule |
+| `Spacer` | Vertical spacing |
+| `SocialMedia` | Social media icon links |
+
 ## License
 
 Free to use. © Laravel42. All rights reserved.