@lit-pigeon/core 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,752 @@
+export declare function addColumn(rowId: string): Command;
+
+/**
+ * Either a built-in {@link ContentBlock} or a registry-defined
+ * {@link CustomBlock}. Use this where code must accept plugin blocks as well as
+ * the built-ins (e.g. `createBlock`, canvas/MJML registry dispatch).
+ */
+export declare type AnyBlock = ContentBlock | CustomBlock;
+
+/**
+ * A managed image / file asset. Lives in an `AssetStorage` so editors and
+ * AI tools can search, tag, and reuse it without re-uploading.
+ */
+export declare interface Asset {
+    /** Stable, URL-safe slug — used as the storage key. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Public URL of the underlying file. */
+    src: string;
+    /** Accessibility alt text. Recommended for every image. */
+    alt?: string;
+    /** MIME type (e.g. `image/png`). */
+    mimeType?: string;
+    /** Total bytes. Useful for {@link AssetStorage.list} filtering. */
+    sizeBytes?: number;
+    /** Pixel width when known. */
+    width?: number;
+    /** Pixel height when known. */
+    height?: number;
+    /** Folder path (`/marketing/Q3`). Defaults to `/` (root). */
+    folder?: string;
+    /** Free-form tags for search + filtering. */
+    tags?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** Filters accepted by {@link AssetStorage.list}. */
+export declare interface AssetListFilter {
+    /** Restrict to a folder path. Pass `/` for the root or omit for all folders. */
+    folder?: string;
+    /** Free-text search over `name`, `alt`, and `tags`. Case-insensitive. */
+    search?: string;
+    /** Restrict to assets that match every tag in this list. */
+    tags?: string[];
+    /** Pagination: max items to return. Default unlimited. */
+    limit?: number;
+    /** Pagination: skip this many items. Default 0. */
+    offset?: number;
+}
+
+export declare interface AssetManagerConfig {
+    enabled?: boolean;
+    uploadUrl?: string;
+    uploadHeaders?: Record<string, string>;
+    acceptedTypes?: string[];
+    maxFileSize?: number;
+    uploadHandler?: (file: File) => Promise<string>;
+    presignedUpload?: {
+        getUploadParams: (file: File) => Promise<PresignedUploadParams>;
+    };
+}
+
+/**
+ * Pluggable persistence for image / file assets. Mirrors `TemplateStorage`
+ * and `BrandKitStorage`. Listing returns assets newest-first so picker UIs
+ * surface recent uploads at the top.
+ */
+export declare interface AssetStorage {
+    list(filter?: AssetListFilter): Promise<Asset[]>;
+    get(id: string): Promise<Asset | null>;
+    save(asset: Asset): Promise<void>;
+    delete(id: string): Promise<void>;
+    /** Distinct folder paths in use across the store. */
+    listFolders(): Promise<string[]>;
+}
+
+export declare interface BlockDefinition {
+    type: string;
+    label: string;
+    icon: string;
+    defaultValues: Record<string, unknown>;
+    /**
+     * Declarative property form for a custom block. When set, selecting the
+     * block in the editor renders these fields (instead of just its label) and
+     * writes edits back to the block's `values`. Pairs with `renderCanvas` /
+     * `renderMjml` to make a registry block fully editable without forking.
+     */
+    propertySchema?: PropertyField[];
+    /**
+     * Optional canvas renderer for a custom block. Returns an HTML string shown
+     * in the editor canvas. Without it, a custom block renders as a labelled
+     * placeholder chip instead of failing. Built-in blocks ignore this — they
+     * have dedicated canvas components.
+     */
+    renderCanvas?: (block: RegisteredBlock) => string;
+    /**
+     * Optional MJML renderer for a custom block, used on export. Returns an MJML
+     * fragment (e.g. `<mj-text>…</mj-text>`). Without it, the block is emitted as
+     * an MJML comment and effectively skipped.
+     */
+    renderMjml?: (block: RegisteredBlock) => string;
+}
+
+export declare type BlockType = ContentBlock['type'];
+
+/**
+ * A single saved color in a brand kit. Hex (`#rrggbb`/`#rgb`) recommended;
+ * any CSS color string is accepted at storage time.
+ */
+export declare interface BrandColor {
+    /** Stable, URL-safe slug used as the storage key. */
+    id: string;
+    name: string;
+    value: string;
+}
+
+/**
+ * A saved font family with the weights the brand uses. `family` is the
+ * value that will appear in CSS `font-family`, including fallbacks.
+ */
+export declare interface BrandFont {
+    id: string;
+    name: string;
+    family: string;
+    weights?: number[];
+    /** Where to load the webfont from, e.g. a Google Fonts URL. */
+    url?: string;
+}
+
+/**
+ * The full saved brand kit. Multiple kits can coexist (different sub-brands,
+ * regions, or seasonal palettes) so the storage layer is keyed by id.
+ */
+export declare interface BrandKit {
+    id: string;
+    name: string;
+    description?: string;
+    colors: BrandColor[];
+    fonts: BrandFont[];
+    logos: BrandLogo[];
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Pluggable persistence for brand kits. Mirrors {@link TemplateStorage}.
+ */
+export declare interface BrandKitStorage {
+    list(): Promise<BrandKit[]>;
+    get(id: string): Promise<BrandKit | null>;
+    save(kit: BrandKit): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/** A saved logo asset — typically a transparent-background image. */
+export declare interface BrandLogo {
+    id: string;
+    name: string;
+    /** Public URL of the logo asset. */
+    src: string;
+    /** Width hint in px used when pre-populating logo-bearing blocks. */
+    width?: number;
+}
+
+export declare interface ButtonBlock {
+    id: string;
+    type: 'button';
+    values: {
+        content: string;
+        href: string;
+        backgroundColor: string;
+        textColor: string;
+        borderRadius: number;
+        padding: Spacing;
+        innerPadding: Spacing;
+        fontSize: number;
+        fontWeight: string;
+        alignment: 'left' | 'center' | 'right';
+        fullWidth: boolean;
+    };
+}
+
+export declare function canRedo(history: HistoryState): boolean;
+
+export declare function canUndo(history: HistoryState): boolean;
+
+export declare interface ColumnNode {
+    id: string;
+    type: 'column';
+    attributes: {
+        backgroundColor?: string;
+        padding: Spacing;
+        borderRadius?: number;
+        verticalAlign: 'top' | 'middle' | 'bottom';
+    };
+    blocks: ContentBlock[];
+}
+
+export declare type Command = (state: EditorStateSnapshot, dispatch?: (tr: TransactionSnapshot) => void) => boolean;
+
+export declare type ContentBlock = TextBlock | ImageBlock | ButtonBlock | DividerBlock | SpacerBlock | SocialBlock | HtmlBlock | HeroBlock | NavBarBlock;
+
+export declare function createBlock(type: BlockType, overrides?: Partial<ContentBlock['values']>): ContentBlock;
+
+export declare function createBlock(type: string, overrides?: Record<string, unknown>): AnyBlock;
+
+export declare function createBlockSelection(rowId: string, columnId: string, blockId: string): Selection_2;
+
+export declare function createBodySelection(): Selection_2;
+
+export declare function createColumn(blocks?: ContentBlock[]): ColumnNode;
+
+export declare function createColumnSelection(rowId: string, columnId: string): Selection_2;
+
+export declare function createDefaultDocument(name?: string): PigeonDocument;
+
+export declare function createDocStep(type: string, path: string, recipe: (doc: PigeonDocument) => void, invertRecipe: (doc: PigeonDocument) => void): Step;
+
+export declare function createHistoryPlugin(): PigeonPlugin;
+
+export declare function createRow(columns?: ColumnNode[], columnRatios?: number[]): RowNode;
+
+export declare function createRowSelection(rowId: string): Selection_2;
+
+/**
+ * A block whose `type` was contributed at runtime via the block registry
+ * (`registerBlock`) rather than being one of the built-in {@link ContentBlock}
+ * kinds. Its `values` are an open record because the editor core can't know a
+ * plugin block's shape ahead of time.
+ */
+export declare interface CustomBlock {
+    id: string;
+    type: string;
+    values: Record<string, unknown>;
+}
+
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+
+export declare function defaultSpacing(all?: number): Spacing;
+
+export declare function deleteBlock(rowId: string, columnId: string, blockId: string): Command;
+
+export declare function deleteRow(rowId: string): Command;
+
+export declare interface DividerBlock {
+    id: string;
+    type: 'divider';
+    values: {
+        borderColor: string;
+        borderWidth: number;
+        borderStyle: 'solid' | 'dashed' | 'dotted';
+        padding: Spacing;
+        width: string;
+    };
+}
+
+export declare function duplicateBlock(rowId: string, columnId: string, blockId: string): Command;
+
+export declare function duplicateRow(rowId: string): Command;
+
+export declare interface EditorConfig {
+    doc?: PigeonDocument;
+    plugins?: PigeonPlugin[];
+    assetManager?: AssetManagerConfig;
+    mergeTags?: MergeTagConfig;
+    /**
+     * Optional persistent asset library. When supplied, the asset modal shows
+     * a "Library" tab next to "Upload" so users can pick from previously saved
+     * assets without re-uploading. The data layer lives in `@lit-pigeon/core`
+     * (`AssetStorage`) and a filesystem-backed implementation ships in
+     * `@lit-pigeon/mcp-server` (`FsAssetStorage`).
+     */
+    assetStorage?: AssetStorage;
+    /**
+     * Optional brand kit (or storage for multiple kits) — saved colors and
+     * fonts can be surfaced as palette swatches in the property panels' color
+     * pickers and font-family pickers. When a `BrandKit` is passed it is used
+     * directly; a `BrandKitStorage` is resolved lazily on demand.
+     */
+    brandKit?: BrandKit | BrandKitStorage;
+}
+
+export declare class EditorState {
+    readonly doc: PigeonDocument;
+    readonly selection: Selection_2 | null;
+    readonly plugins: Map<string, unknown>;
+    private readonly _pluginList;
+    private constructor();
+    static create(config?: EditorConfig): EditorState;
+    createTransaction(): Transaction;
+    apply(tr: TransactionSnapshot): EditorState;
+    getPluginState<T>(pluginName: string): T | undefined;
+}
+
+export declare interface EditorStateSnapshot {
+    readonly doc: PigeonDocument;
+    readonly selection: Selection_2 | null;
+    readonly plugins: Map<string, unknown>;
+    createTransaction(): TransactionSnapshot;
+}
+
+export declare function generateId(): string;
+
+export declare function getAllBlockDefinitions(): BlockDefinition[];
+
+export declare function getBlockDefinition(type: string): BlockDefinition | undefined;
+
+export declare function getDefaultValues(type: BlockType): ContentBlock['values'];
+
+export declare function getStarterTemplate(id: string): Template | null;
+
+export declare function getStarterTemplates(): Template[];
+
+export declare interface HeroBlock {
+    id: string;
+    type: 'hero';
+    values: {
+        backgroundUrl: string;
+        backgroundPosition: 'center center' | 'top center' | 'bottom center' | 'left center' | 'right center';
+        mode: 'fixed-height' | 'fluid-height';
+        width: number;
+        height: number;
+        verticalAlign: 'top' | 'middle' | 'bottom';
+        padding: Spacing;
+        innerPadding: Spacing;
+        backgroundColor: string;
+        content: string;
+    };
+}
+
+export declare const HISTORY_PLUGIN_NAME = "history";
+
+declare interface HistoryEntry {
+    steps: Step[];
+    doc: PigeonDocument;
+    timestamp: number;
+}
+
+export declare interface HistoryState {
+    undoStack: HistoryEntry[];
+    redoStack: HistoryEntry[];
+}
+
+export declare interface HtmlBlock {
+    id: string;
+    type: 'html';
+    values: {
+        content: string;
+        padding: Spacing;
+    };
+}
+
+export declare interface ImageBlock {
+    id: string;
+    type: 'image';
+    values: {
+        src: string;
+        alt: string;
+        width: number | 'auto';
+        href?: string;
+        padding: Spacing;
+        alignment: 'left' | 'center' | 'right';
+        borderRadius?: number;
+    };
+}
+
+/**
+ * Default `AssetStorage` — Map-backed, per-process. Search, folder filter,
+ * and tag filter are all client-side; for very large libraries, back this
+ * with an indexed storage (S3 + DynamoDB / Postgres / etc.).
+ */
+export declare class InMemoryAssetStorage implements AssetStorage {
+    private readonly _byId;
+    constructor(opts?: InMemoryAssetStorageOptions);
+    list(filter?: AssetListFilter): Promise<Asset[]>;
+    get(id: string): Promise<Asset | null>;
+    save(asset: Asset): Promise<void>;
+    delete(id: string): Promise<void>;
+    listFolders(): Promise<string[]>;
+}
+
+export declare interface InMemoryAssetStorageOptions {
+    seed?: Asset[];
+}
+
+/**
+ * Default `BrandKitStorage` — `Map`-backed, per-process. Mirrors
+ * `InMemoryTemplateStorage`: deep-clones on read so callers can't poison
+ * the store by mutating returned objects.
+ */
+export declare class InMemoryBrandKitStorage implements BrandKitStorage {
+    private readonly _byId;
+    constructor(opts?: InMemoryBrandKitStorageOptions);
+    list(): Promise<BrandKit[]>;
+    get(id: string): Promise<BrandKit | null>;
+    save(kit: BrandKit): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+export declare interface InMemoryBrandKitStorageOptions {
+    /** Brand kits to seed the store with on construction. */
+    seed?: BrandKit[];
+}
+
+/**
+ * Default `TemplateStorage` implementation — backs templates in a `Map`
+ * inside a single process. Suitable for the editor's default config, the
+ * MCP server's per-session lifetime, and unit tests.
+ *
+ * Consumers that need persistence should implement `TemplateStorage` directly
+ * (e.g. wrapping localStorage, a REST endpoint, or the filesystem).
+ */
+export declare class InMemoryTemplateStorage implements TemplateStorage {
+    private readonly _byId;
+    constructor(opts?: InMemoryTemplateStorageOptions);
+    list(): Promise<Template[]>;
+    get(id: string): Promise<Template | null>;
+    save(template: Template): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+export declare interface InMemoryTemplateStorageOptions {
+    /** When true (default), the storage is seeded with the built-in starter templates. */
+    includeStarters?: boolean;
+    /** Additional templates to seed alongside the starters. */
+    seed?: Template[];
+}
+
+export declare function insertBlock(rowId: string, columnId: string, block: ContentBlock, index?: number): Command;
+
+export declare function insertRow(row: RowNode, index?: number): Command;
+
+export declare function isKnownBlockType(type: string): type is BlockType;
+
+export declare function isValidDocument(doc: unknown): doc is PigeonDocument;
+
+export declare interface MergeTag {
+    name: string;
+    label: string;
+    category?: string;
+    sample?: string;
+}
+
+export declare interface MergeTagConfig {
+    trigger?: string;
+    tags?: MergeTag[];
+}
+
+export declare function moveBlock(fromRowId: string, fromColumnId: string, blockId: string, toRowId: string, toColumnId: string, toIndex: number): Command;
+
+export declare function moveRow(rowId: string, toIndex: number): Command;
+
+export declare interface NavBarBlock {
+    id: string;
+    type: 'navbar';
+    values: {
+        links: NavLink[];
+        hamburger: 'hamburger' | 'none';
+        alignment: 'left' | 'center' | 'right';
+        padding: Spacing;
+        linkColor: string;
+        linkFontSize: number;
+        linkPadding: string;
+    };
+}
+
+export declare interface NavLink {
+    href: string;
+    text: string;
+    color?: string;
+    fontWeight?: string;
+    textDecoration?: string;
+    padding?: string;
+}
+
+export declare interface PigeonDocument {
+    version: '1.0';
+    metadata: {
+        name: string;
+        previewText?: string;
+        createdAt: string;
+        updatedAt: string;
+    };
+    body: {
+        attributes: {
+            width: number;
+            backgroundColor: string;
+            fontFamily: string;
+            contentAlignment: 'center' | 'left';
+        };
+        rows: RowNode[];
+    };
+}
+
+export declare interface PigeonPlugin {
+    name: string;
+    init?(state: EditorStateSnapshot): unknown;
+    apply?(tr: TransactionSnapshot, pluginState: unknown): unknown;
+    onStateChange?(newState: EditorStateSnapshot, oldState: EditorStateSnapshot): void;
+    blocks?: BlockDefinition[];
+    commands?: Record<string, Command>;
+}
+
+export declare class PluginRegistry {
+    private _plugins;
+    register(plugin: PigeonPlugin): void;
+    unregister(name: string): void;
+    get(name: string): PigeonPlugin | undefined;
+    getAll(): PigeonPlugin[];
+    getCommands(): Record<string, Command>;
+    has(name: string): boolean;
+}
+
+export declare interface PresignedUploadParams {
+    uploadUrl: string;
+    publicUrl: string;
+    method?: 'PUT' | 'POST';
+    headers?: Record<string, string>;
+    fields?: Record<string, string>;
+}
+
+/**
+ * A single editable field in a custom block's property panel. The editor
+ * renders the matching control and writes changes back to `block.values[key]`.
+ */
+export declare interface PropertyField {
+    /** Key within the block's `values` this field reads and writes. */
+    key: string;
+    label: string;
+    type: 'text' | 'textarea' | 'number' | 'color' | 'checkbox' | 'select';
+    placeholder?: string;
+    /** For `number` fields. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** For `select` fields. */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+
+export declare function redo(state: EditorStateSnapshot, dispatch?: (tr: TransactionSnapshot) => void): boolean;
+
+export declare function registerBlock(definition: BlockDefinition): void;
+
+/**
+ * The minimal block shape passed to a {@link BlockDefinition}'s render hooks.
+ * Structurally compatible with both built-in `ContentBlock`s and registry
+ * `CustomBlock`s.
+ */
+export declare interface RegisteredBlock {
+    id: string;
+    type: string;
+    values: Record<string, unknown>;
+}
+
+export declare function removeColumn(rowId: string, columnId: string): Command;
+
+export declare interface Renderer {
+    render(doc: PigeonDocument, options?: RenderOptions): Promise<RenderResult>;
+}
+
+export declare interface RenderError {
+    message: string;
+    line?: number;
+    tagName?: string;
+}
+
+export declare interface RenderOptions {
+    minify?: boolean;
+    inlineCss?: boolean;
+    beautify?: boolean;
+    /**
+     * When true (default), the MJML renderer injects Outlook (mso) and
+     * dark-mode rendering workarounds: a heading-margin reset `<mj-style>`,
+     * dark-mode color-scheme `<meta>` tags, and an `[if mso]` conditional
+     * block with Arial fallback and blockquote margin reset.
+     * Set to false to opt out (useful for testing the bare renderer output).
+     */
+    outlookWorkarounds?: boolean;
+}
+
+export declare interface RenderResult {
+    html: string;
+    errors: RenderError[];
+}
+
+export declare function resizeColumns(rowId: string, ratios: number[]): Command;
+
+export declare interface RowNode {
+    id: string;
+    type: 'row';
+    attributes: {
+        backgroundColor?: string;
+        backgroundImage?: string;
+        padding: Spacing;
+        fullWidth: boolean;
+        /**
+         * Optional display condition. When set, the row only renders when the
+         * expression is truthy in the sending platform's template engine. The
+         * renderer wraps the section in `{{#if <condition>}} … {{/if}}` (Handlebars
+         * / Liquid-style, passed through verbatim), e.g. `condition: "user.premium"`.
+         */
+        condition?: string;
+    };
+    columns: ColumnNode[];
+    columnRatios: number[];
+    locked: boolean;
+}
+
+declare interface Selection_2 {
+    type: 'block' | 'row' | 'column' | 'body';
+    rowId?: string;
+    columnId?: string;
+    blockId?: string;
+}
+export { Selection_2 as Selection }
+
+export declare function selectionsEqual(a: Selection_2 | null, b: Selection_2 | null): boolean;
+
+export declare interface SocialBlock {
+    id: string;
+    type: 'social';
+    values: {
+        icons: SocialIcon[];
+        iconSize: number;
+        spacing: number;
+        alignment: 'left' | 'center' | 'right';
+        padding: Spacing;
+    };
+}
+
+export declare interface SocialIcon {
+    type: 'facebook' | 'twitter' | 'instagram' | 'linkedin' | 'youtube' | 'tiktok' | 'custom';
+    href: string;
+    label?: string;
+    iconUrl?: string;
+}
+
+export declare interface SpacerBlock {
+    id: string;
+    type: 'spacer';
+    values: {
+        height: number;
+    };
+}
+
+export declare interface Spacing {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+
+export declare interface Step {
+    type: string;
+    path: string;
+    apply(doc: PigeonDocument): PigeonDocument;
+    invert(doc: PigeonDocument): Step;
+}
+
+export declare interface Template {
+    /** Stable, URL-safe slug. Doubles as filename when persisted. */
+    id: string;
+    /** Display name shown in pickers. */
+    name: string;
+    /** One-line summary used in template galleries. */
+    description?: string;
+    /** Optional category for grouping in UI. */
+    category?: TemplateCategory;
+    /** Optional preview image — base64 data URL or absolute URL. */
+    thumbnail?: string;
+    /** The full PigeonDocument the template materialises. */
+    document: PigeonDocument;
+    /** ISO-8601 timestamps. */
+    createdAt: string;
+    updatedAt: string;
+}
+
+export declare type TemplateCategory = 'welcome' | 'newsletter' | 'transactional' | 'promo' | 'announcement' | 'other';
+
+/**
+ * Pluggable persistence layer for templates. The editor ships with an
+ * in-memory implementation that includes the starter templates; consumers
+ * implement this interface to back templates with localStorage, a REST
+ * endpoint, IndexedDB, or the filesystem.
+ */
+export declare interface TemplateStorage {
+    list(): Promise<Template[]>;
+    get(id: string): Promise<Template | null>;
+    save(template: Template): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+export declare interface TextBlock {
+    id: string;
+    type: 'text';
+    values: {
+        content: string;
+        padding: Spacing;
+        lineHeight: string;
+        textAlign: 'left' | 'center' | 'right';
+    };
+}
+
+export declare class Transaction {
+    private _steps;
+    private _selection;
+    private _selectionSet;
+    private _meta;
+    private _doc;
+    constructor(doc: PigeonDocument);
+    get steps(): ReadonlyArray<Step>;
+    get selection(): Selection_2 | null;
+    get selectionSet(): boolean;
+    get meta(): ReadonlyMap<string, unknown>;
+    get doc(): PigeonDocument;
+    addStep(step: Step): this;
+    setSelection(sel: Selection_2 | null): this;
+    setMeta(key: string, value: unknown): this;
+    getMeta(key: string): unknown;
+}
+
+export declare interface TransactionSnapshot {
+    readonly doc: PigeonDocument;
+    readonly steps: readonly Step[];
+    readonly selection: Selection_2 | null;
+    readonly selectionSet: boolean;
+    readonly meta: ReadonlyMap<string, unknown>;
+    addStep(step: Step): TransactionSnapshot;
+    setSelection(sel: Selection_2 | null): TransactionSnapshot;
+    setMeta(key: string, value: unknown): TransactionSnapshot;
+    getMeta(key: string): unknown;
+}
+
+export declare function undo(state: EditorStateSnapshot, dispatch?: (tr: TransactionSnapshot) => void): boolean;
+
+export declare function updateBlock(rowId: string, columnId: string, blockId: string, values: Record<string, unknown>): Command;
+
+export declare function updateRowAttributes(rowId: string, attributes: Partial<RowNode['attributes']>): Command;
+
+export declare function validateDocument(doc: unknown): ValidationError[];
+
+export declare interface ValidationError {
+    path: string;
+    message: string;
+}
+
+export { }