bootstrap-email-wysiwyg 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,483 @@
+import { DecoratorNode } from 'lexical';
+import { DOMConversionMap } from 'lexical';
+import { DOMExportOutput } from 'lexical';
+import { EditorConfig } from 'lexical';
+import { EditorThemeClasses } from 'lexical';
+import { ElementFormatType } from 'lexical';
+import { ElementNode } from 'lexical';
+import { ForwardRefExoticComponent } from 'react';
+import { JSX as JSX_2 } from 'react';
+import { LexicalEditor } from 'lexical';
+import { LexicalNode } from 'lexical';
+import { NodeKey } from 'lexical';
+import { ParagraphNode } from 'lexical';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+import { SerializedElementNode } from 'lexical';
+import { SerializedLexicalNode } from 'lexical';
+import { SerializedParagraphNode } from 'lexical';
+import { Spread } from 'lexical';
+
+/**
+ * Step the font size up or down one notch. Replaces any existing size (never
+ * stacks) and treats "no size" as base. Targets, in order:
+ *  - cursor inside a button   → the button (inline font-size),
+ *  - collapsed selection      → the enclosing block (text-* class),
+ *  - non-empty text selection → the selected text (span, text-* class).
+ * Must run inside an `editor.update()`.
+ */
+export declare function $adjustFontSize(direction: FontSizeDirection): void;
+
+/**
+ * Apply a color following the target rules. Must be called inside an
+ * `editor.update()` (hence the `$` prefix):
+ *  - cursor inside a button   → the button node,
+ *  - collapsed selection      → the enclosing block (parent element),
+ *  - non-empty text selection → the selected text (inline span).
+ */
+export declare function $applyColor(kind: ColorKind, token: string | null): void;
+
+export declare function $createButtonNode(payload?: ButtonPayload): ButtonNode;
+
+/** Create a button already populated with a text label. */
+export declare function $createButtonWithLabel(label: string, payload?: ButtonPayload): ButtonNode;
+
+export declare function $createHrNode(payload?: HrPayload): HrNode;
+
+export declare function $createImageNode(payload: ImagePayload): ImageNode;
+
+export declare function $isButtonNode(node: LexicalNode | null | undefined): node is ButtonNode;
+
+export declare function $isHrNode(node: LexicalNode | null | undefined): node is HrNode;
+
+export declare function $isImageNode(node: LexicalNode | null | undefined): node is ImageNode;
+
+export declare function addCustomColor(hex: string): void;
+
+/** Convenience wrapper that runs {@link $adjustFontSize} in an editor update. */
+export declare function adjustFontSize(editor: LexicalEditor, direction: FontSizeDirection): void;
+
+export declare type Align = "left" | "center" | "right" | "justify";
+
+/** Convenience wrapper that runs {@link $applyColor} in an editor update. */
+export declare function applyColor(editor: LexicalEditor, kind: ColorKind, token: string | null): void;
+
+/**
+ * Bootstrap Email horizontal-alignment class for block content (buttons,
+ * images). `justify` is meaningless here, so it yields no class.
+ */
+export declare function axAlignClass(format: ElementFormatType): string | null;
+
+/** Contextual + absolute colors shown as the top row of the picker. */
+export declare const BASE_COLORS: Swatch[];
+
+/**
+ * The root WYSIWYG editor component: a rich-text surface with a Quill-style
+ * toolbar (inline formatting, font sizing, colors, image / button / separator
+ * insertion) and undo/redo history. Every block is a Bootstrap Email `<div>`.
+ *
+ * Get content out via `onChange` or the imperative `ref`; seed it with
+ * `initialContent`.
+ */
+export declare const BootstrapEmailEditor: ForwardRefExoticComponent<BootstrapEmailEditorProps & RefAttributes<BootstrapEmailEditorHandle>>;
+
+/** Imperative handle exposed via `ref`. */
+export declare interface BootstrapEmailEditorHandle {
+    /** Export Bootstrap Email HTML (fragment by default; pass `{ document: true }`). */
+    getHtml: (options?: BootstrapEmailHtmlOptions) => string;
+    /** Serialized editor state JSON, suitable for `initialContent`. */
+    getJson: () => string;
+    focus: () => void;
+    /** Remove all content. */
+    clear: () => void;
+    /** The underlying Lexical editor, for advanced use. */
+    getEditor: () => LexicalEditor | null;
+}
+
+export declare interface BootstrapEmailEditorProps {
+    /** Placeholder text shown when the editor is empty. */
+    placeholder?: string;
+    /** Show the built-in formatting toolbar. Defaults to true. */
+    toolbar?: boolean;
+    /** Seed the editor from a serialized state (as produced by `getJson`). */
+    initialContent?: string;
+    /** Called on every edit with the current HTML + serialized state. */
+    onChange?: (change: EditorChange) => void;
+    /** Called when Lexical throws during an update. */
+    onError?: (error: Error) => void;
+    /**
+     * Extra Lexical plugins/components rendered inside the composer, so they
+     * have access to the editor context.
+     */
+    children?: ReactNode;
+}
+
+export declare interface BootstrapEmailHtmlOptions {
+    /** Wrap the content in a full HTML email document. Default: false (fragment). */
+    document?: boolean;
+    /** Pretty-print with indentation. Default: true. */
+    pretty?: boolean;
+}
+
+/**
+ * Maps Lexical node types to CSS class names. These classes are styled in
+ * `editor.css`. Keeping the theme separate lets consumers override styling
+ * without touching editor logic.
+ */
+export declare const bootstrapEmailTheme: EditorThemeClasses;
+
+/**
+ * A paragraph that exports as a Bootstrap Email `<div>` line rather than a
+ * `<p>`. Alignment becomes a `text-*` class (or `ax-*` when the block's content
+ * is a button), and block-level text/background colors become `text-*` / `bg-*`
+ * classes (or inline styles for custom colors).
+ */
+export declare class BootstrapParagraphNode extends ParagraphNode {
+    __textColor: string | null;
+    __bgColor: string | null;
+    __fontSize: string | null;
+    constructor(textColor?: string | null, bgColor?: string | null, fontSize?: string | null, key?: string);
+    static getType(): string;
+    static clone(node: BootstrapParagraphNode): BootstrapParagraphNode;
+    static importJSON(serializedNode: SerializedBootstrapParagraphNode): BootstrapParagraphNode;
+    exportJSON(): SerializedBootstrapParagraphNode;
+    getFontSize(): string | null;
+    setFontSize(key: string | null): this;
+    getTextColor(): string | null;
+    setTextColor(token: string | null): this;
+    getBgColor(): string | null;
+    setBgColor(token: string | null): this;
+    private applyInlineStyles;
+    createDOM(config: EditorConfig): HTMLElement;
+    updateDOM(prevNode: BootstrapParagraphNode, dom: HTMLElement, config: EditorConfig): boolean;
+    private hasButtonChild;
+    exportDOM(): DOMExportOutput;
+}
+
+/**
+ * A Bootstrap Email button, authored in source as
+ * `<a href="…" class="btn btn-primary">Label</a>`. Modeled as an inline
+ * element so the label text is edited natively, while href / color variant /
+ * outline are node properties.
+ */
+export declare class ButtonNode extends ElementNode {
+    __href: string;
+    __variant: ButtonVariant;
+    __outline: boolean;
+    __textColor: string | null;
+    __bgColor: string | null;
+    __borderColor: string | null;
+    __fontSize: string | null;
+    static getType(): string;
+    static clone(node: ButtonNode): ButtonNode;
+    constructor(href?: string, variant?: ButtonVariant, outline?: boolean, textColor?: string | null, bgColor?: string | null, borderColor?: string | null, fontSize?: string | null, key?: string);
+    private variantClass;
+    private buildClassName;
+    private applyInlineStyles;
+    createDOM(_config: EditorConfig): HTMLElement;
+    updateDOM(prevNode: ButtonNode, dom: HTMLElement): boolean;
+    static importDOM(): DOMConversionMap | null;
+    exportDOM(): DOMExportOutput;
+    static importJSON(serializedNode: SerializedButtonNode): ButtonNode;
+    exportJSON(): SerializedButtonNode;
+    getHref(): string;
+    setHref(href: string): this;
+    getVariant(): ButtonVariant;
+    setVariant(variant: ButtonVariant): this;
+    getOutline(): boolean;
+    setOutline(outline: boolean): this;
+    getTextColor(): string | null;
+    setTextColor(token: string | null): this;
+    getBgColor(): string | null;
+    setBgColor(token: string | null): this;
+    getBorderColor(): string | null;
+    setBorderColor(token: string | null): this;
+    getFontSize(): string | null;
+    setFontSize(key: string | null): this;
+    isInline(): boolean;
+    canBeEmpty(): boolean;
+    canInsertTextBefore(): boolean;
+    canInsertTextAfter(): boolean;
+}
+
+export declare interface ButtonPayload {
+    href?: string;
+    variant?: ButtonVariant;
+    outline?: boolean;
+    textColor?: string | null;
+    bgColor?: string | null;
+    borderColor?: string | null;
+    fontSize?: string | null;
+}
+
+/** The full visual styling of a button, minus href/label. */
+export declare interface ButtonStyle {
+    variant: ButtonVariant;
+    outline: boolean;
+    textColor: string | null;
+    bgColor: string | null;
+    borderColor: string | null;
+    fontSize: string | null;
+}
+
+/** Bootstrap contextual color variants supported by Bootstrap Email buttons. */
+export declare type ButtonVariant = "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark";
+
+/**
+ * Clean Lexical's raw HTML export into Bootstrap Email source (class-based,
+ * span-free). Browser-only (uses the DOM).
+ */
+export declare function cleanBootstrapHtml(rawHtml: string, pretty?: boolean): string;
+
+export declare const COLOR_FAMILIES: ColorFamily[];
+
+/**
+ * Resolve a text/bg color token into the classes and inline styles needed on
+ * an exported element (palette → class, custom → inline style).
+ */
+export declare function colorAttributes(textToken?: string | null, bgToken?: string | null, borderToken?: string | null): {
+    classes: string[];
+    style: string;
+};
+
+export declare interface ColorFamily {
+    name: string;
+    /** Shades ordered light → dark (100 → 900). */
+    shades: {
+        shade: number;
+        token: string;
+        hex: string;
+    }[];
+}
+
+export declare type ColorKind = "text" | "bg" | "border";
+
+export declare function ColorPicker({ onSelect }: ColorPickerProps): JSX_2.Element;
+
+declare interface ColorPickerProps {
+    /** Called with a palette token, a custom "#hex", or null to clear color. */
+    onSelect: (token: string | null) => void;
+}
+
+/** A plain `<hr>` has 20px top/bottom spacing; mt-5 / mb-5 = 20px. */
+export declare const DEFAULT_HR_MARGIN = "5";
+
+/** Payload passed to `onChange` on every edit. */
+export declare interface EditorChange {
+    /** Bootstrap Email source HTML (content fragment). */
+    html: string;
+    /** Serialized editor state, for persistence / `initialContent`. */
+    json: string;
+}
+
+export declare const FONT_SIZE_KEYS: readonly ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl", "7xl"];
+
+/** Class for a size key, or null for the default ("base"). */
+export declare function fontSizeClass(key: string | null | undefined): string | null;
+
+export declare type FontSizeDirection = "increase" | "decrease";
+
+export declare type FontSizeKey = (typeof FONT_SIZE_KEYS)[number];
+
+export declare function fontSizePx(key: FontSizeKey): number;
+
+export declare function getCustomColors(): string[];
+
+export declare function getLastButtonStyle(): ButtonStyle;
+
+/** Reverse a rendered hex back to a palette token, or null if not in palette. */
+export declare function hexToToken(hex: string): string | null;
+
+/** Classes for an HR's spacing — separate `mt-` / `mb-` rather than `my-`. */
+export declare function hrClasses(top: string, bottom: string): string[];
+
+/**
+ * A Bootstrap Email horizontal rule (`<hr>`) with configurable top/bottom
+ * spacing (`mt-*` / `mb-*`). Rendered as a decorator for the settings overlay.
+ */
+export declare class HrNode extends DecoratorNode<ReactNode> {
+    __top: string;
+    __bottom: string;
+    static getType(): string;
+    static clone(node: HrNode): HrNode;
+    constructor(top?: string, bottom?: string, key?: NodeKey);
+    static importJSON(serializedNode: SerializedHrNode): HrNode;
+    exportJSON(): SerializedHrNode;
+    static importDOM(): DOMConversionMap | null;
+    exportDOM(): DOMExportOutput;
+    getTop(): string;
+    setTop(top: string): this;
+    getBottom(): string;
+    setBottom(bottom: string): this;
+    createDOM(): HTMLElement;
+    updateDOM(): boolean;
+    isInline(): boolean;
+    decorate(): ReactNode;
+}
+
+export declare interface HrPayload {
+    top?: string;
+    bottom?: string;
+    key?: NodeKey;
+}
+
+/** Bootstrap Email classes for an image's sizing. */
+export declare function imageClasses(mode: ImageMode, width: string | null, height: string | null): string[];
+
+export declare type ImageMode = "fluid" | "fixed" | "max";
+
+/**
+ * A Bootstrap Email image (`<img>` from a URL). Sizing is one of three modes:
+ * fluid (`img-fluid`), fixed (`w-*`/`h-*`), or max-width (`max-w-* w-full`).
+ * Rendered as a decorator so the editor can show a settings (gear) overlay.
+ */
+export declare class ImageNode extends DecoratorNode<ReactNode> {
+    __src: string;
+    __alt: string;
+    __mode: ImageMode;
+    __width: string | null;
+    __height: string | null;
+    static getType(): string;
+    static clone(node: ImageNode): ImageNode;
+    constructor(src: string, alt?: string, mode?: ImageMode, width?: string | null, height?: string | null, key?: NodeKey);
+    static importJSON(serializedNode: SerializedImageNode): ImageNode;
+    exportJSON(): SerializedImageNode;
+    static importDOM(): DOMConversionMap | null;
+    exportDOM(): DOMExportOutput;
+    getSrc(): string;
+    setSrc(src: string): this;
+    getAlt(): string;
+    setAlt(alt: string): this;
+    getMode(): ImageMode;
+    setMode(mode: ImageMode): this;
+    getWidth(): string | null;
+    setWidth(width: string | null): this;
+    getHeight(): string | null;
+    setHeight(height: string | null): this;
+    createDOM(): HTMLElement;
+    updateDOM(): boolean;
+    isInline(): boolean;
+    decorate(): ReactNode;
+}
+
+export declare interface ImagePayload {
+    src: string;
+    alt?: string;
+    mode?: ImageMode;
+    width?: string | null;
+    height?: string | null;
+    key?: NodeKey;
+}
+
+/** Inline styles mirroring {@link imageClasses}, for live editor preview. */
+export declare function imagePreviewStyle(mode: ImageMode, width: string | null, height: string | null): Record<string, string>;
+
+/**
+ * Insert a Bootstrap Email button at the current selection. No-op when there
+ * is no range selection (e.g. the editor isn't focused).
+ */
+export declare function insertButton(editor: LexicalEditor, options?: InsertButtonOptions): void;
+
+export declare interface InsertButtonOptions extends ButtonPayload {
+    /** Text label for the button. Defaults to "Button". */
+    label?: string;
+}
+
+/** Insert a horizontal rule (separator) as a block at the current selection. */
+export declare function insertHr(editor: LexicalEditor, payload?: HrPayload): void;
+
+/** Insert an image (from a URL) as a block at the current selection. */
+export declare function insertImage(editor: LexicalEditor, payload: ImagePayload): void;
+
+export declare const MARGIN_STEPS: MarginStep[];
+
+export declare function marginKeyToPx(key: string | null): number;
+
+export declare interface MarginStep {
+    key: string;
+    px: number;
+}
+
+/** Collapse Lexical's element format into a Bootstrap Email alignment, or null. */
+export declare function normalizeAlign(format: ElementFormatType): Align | null;
+
+/** Match a pixel size back to a scale key, or null if off-scale. */
+export declare function pxToFontSizeKey(px: number): FontSizeKey | null;
+
+export declare function rememberButtonStyle(style: ButtonStyle): void;
+
+export declare function removeCustomColor(hex: string): void;
+
+declare type SerializedBootstrapParagraphNode = Spread<{
+    textColor: string | null;
+    bgColor: string | null;
+    fontSize: string | null;
+}, SerializedParagraphNode>;
+
+export declare type SerializedButtonNode = Spread<{
+    href: string;
+    variant: ButtonVariant;
+    outline: boolean;
+    textColor: string | null;
+    bgColor: string | null;
+    borderColor: string | null;
+    fontSize: string | null;
+}, SerializedElementNode>;
+
+export declare type SerializedHrNode = Spread<{
+    top: string;
+    bottom: string;
+}, SerializedLexicalNode>;
+
+export declare type SerializedImageNode = Spread<{
+    src: string;
+    alt: string;
+    mode: ImageMode;
+    width: string | null;
+    height: string | null;
+}, SerializedLexicalNode>;
+
+/** The discrete Bootstrap Email sizing scale (w-0 … w-150). */
+export declare const SIZE_STEPS: SizeStep[];
+
+export declare function sizeKeyToPx(key: string | null): number | null;
+
+export declare interface SizeStep {
+    key: string;
+    px: number;
+}
+
+/**
+ * Step a size one notch up (+1) or down (-1) the scale, clamped at the ends.
+ * A null/unknown current size is treated as "base".
+ */
+export declare function stepFontSize(current: string | null | undefined, direction: 1 | -1): FontSizeKey;
+
+export declare interface Swatch {
+    /** Token stored on nodes, e.g. "blue-500", "primary", or a custom "#a1b2c3". */
+    token: string;
+    hex: string;
+}
+
+/** Bootstrap Email text-alignment class for a block of inline text. */
+export declare function textAlignClass(format: ElementFormatType): string | null;
+
+/**
+ * Export the editor's content as Bootstrap Email source HTML — a content
+ * fragment by default, or a full email document with `{ document: true }`.
+ * Browser-only (uses the DOM). Feed the result to the bootstrap-email compiler.
+ */
+export declare function toBootstrapEmailHtml(editor: LexicalEditor, options?: BootstrapEmailHtmlOptions): string;
+
+/** Bootstrap Email class for a palette token, or null for custom hex colors. */
+export declare function tokenToClass(token: string, kind: ColorKind): string | null;
+
+/** CSS color for live rendering. */
+export declare function tokenToHex(token: string): string;
+
+export declare function Toolbar(): JSX_2.Element;
+
+/** React hook returning the live list of custom colors. */
+export declare function useCustomColors(): string[];
+
+export { }

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "bootstrap-email-wysiwyg",
+  "version": "0.1.0",
+  "description": "A Lexical-based WYSIWYG editor for building Bootstrap Email templates.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Süleyman Kenar <suleyman@kenar.net>",
+  "homepage": "https://github.com/kenarsuleyman/bootstrap-email-wysiwyg#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kenarsuleyman/bootstrap-email-wysiwyg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kenarsuleyman/bootstrap-email-wysiwyg/issues"
+  },
+  "keywords": [
+    "lexical",
+    "wysiwyg",
+    "editor",
+    "bootstrap",
+    "email",
+    "react"
+  ],
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/bootstrap-email-wysiwyg.cjs",
+  "module": "./dist/bootstrap-email-wysiwyg.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/bootstrap-email-wysiwyg.js",
+      "require": "./dist/bootstrap-email-wysiwyg.cjs"
+    },
+    "./styles.css": "./dist/bootstrap-email-wysiwyg.css"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@lexical/react": "^0.36.2",
+    "@lexical/rich-text": "^0.36.2",
+    "@lexical/selection": "^0.36.2",
+    "@lexical/utils": "^0.36.2",
+    "lexical": "^0.36.2"
+  },
+  "devDependencies": {
+    "@lexical/headless": "^0.36.2",
+    "@lexical/html": "^0.36.2",
+    "@types/node": "^22.20.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.5",
+    "vite-plugin-dts": "^4.4.0"
+  }
+}