@voila.dev/ui-email-block-editor 1.1.9

package/README.md

@@ -0,0 +1,23 @@
+# @voila.dev/ui-email-block-editor
+
+WYSIWYG block editor for marketing emails. The canvas mirrors the transactional
+email chrome (600px card, email theme) so what the admin composes looks like the
+email that will be sent — the server-rendered preview stays the source of truth.
+
+- `document/types.ts` — the editor document model (`EmailEditorDocument`,
+  blocks: heading, paragraph, button, image, divider). Pure TypeScript; the
+  domain's `MarketingEmailDocument` schema validates exactly this shape.
+- `document/reducer.ts` — pure reducer (add/update/remove/move/duplicate/
+  select/replace) with an injected block-id factory.
+- `blocks/*` — one WYSIWYG component per block, edited in place.
+- `sections/*` — canvas chrome, block toolbar, add-block menu, settings sidebar.
+- `dnd/sortable-block-list.tsx` — keyboard-accessible dnd-kit reordering.
+- `email-block-editor.tsx` — the composed `<EmailBlockEditor />`.
+
+Image uploads are delegated: the host passes `onUploadImage(file) → Promise<url>`.
+
+Consumers must add this package to their Tailwind sources:
+
+```css
+@source "../../../../packages/ui-email-block-editor/src";
+```

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@voila.dev/ui-email-block-editor",
+	"version": "1.1.9",
+	"type": "module",
+	"description": "The email template editor that lives in your app, not someone else's SaaS.",
+	"license": "MIT",
+	"homepage": "https://ui.voila.dev/components/email-block-editor",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/voila-voila-dev/ui.git",
+		"directory": "packages/ui-email-block-editor"
+	},
+	"keywords": [
+		"react",
+		"email",
+		"editor",
+		"block-editor",
+		"dnd-kit"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
+		"!src/**/*.stories.ts",
+		"!src/**/*.stories.tsx"
+	],
+	"exports": {
+		"./styles.css": "./src/styles.css",
+		"./email-block-editor": "./src/email-block-editor.tsx",
+		"./theme": "./src/theme.ts",
+		"./document/*": "./src/document/*.ts",
+		"./blocks/*": "./src/blocks/*.tsx",
+		"./sections/*": "./src/sections/*.tsx",
+		"./dnd/*": "./src/dnd/*.tsx"
+	},
+	"imports": {
+		"#/*": "./src/*"
+	},
+	"scripts": {
+		"check": "biome check",
+		"check-types": "tsc --noEmit",
+		"format": "biome format",
+		"lint": "biome lint",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@dnd-kit/core": "^6.3.1",
+		"@dnd-kit/sortable": "^10.0.0",
+		"@dnd-kit/utilities": "^3.2.2",
+		"@phosphor-icons/react": "2.1.10",
+		"@voila.dev/ui": "0.0.0"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"tailwindcss": "^4.0.0"
+	},
+	"sideEffects": [
+		"**/*.css"
+	]
+}

package/src/blocks/article-block.tsx

@@ -0,0 +1,122 @@
+import { NewspaperIcon } from "@phosphor-icons/react";
+import type {
+	EmailBlockComponentProps,
+	EmailBlockDefinition,
+} from "#/blocks/block-definitions.tsx";
+import { BlockTextInput } from "#/blocks/block-text-input.tsx";
+import { EmailCardMeta, EmailCardShell } from "#/blocks/email-card-shell.tsx";
+import type { EmailEditorArticleBlock } from "#/document/types.ts";
+import { BlockOptionSection } from "#/sections/block-options/block-option-row.tsx";
+import {
+	LinkOption,
+	TextAreaOption,
+	TextOption,
+} from "#/sections/block-options/text-option.tsx";
+import { EMAIL_COLOR } from "#/theme.ts";
+
+/** The author/date line, with a separator only when both are present. */
+const metaLine = (block: EmailEditorArticleBlock): string =>
+	[block.author, block.publishDate].filter((part) => part !== "").join(" · ");
+
+/**
+ * A blog post or an external resource, on the shared card shell. Field names
+ * follow the real blog model, so a digest built from published posts maps
+ * straight across. The title and description are edited in place; the image,
+ * the byline and the link live in the settings.
+ */
+function ArticleBlockView({
+	block,
+	onChange,
+}: EmailBlockComponentProps<EmailEditorArticleBlock>) {
+	const meta = metaLine(block);
+	return (
+		<EmailCardShell image={block.image}>
+			<BlockTextInput
+				ariaLabel="Titre de l'article"
+				value={block.title}
+				placeholder="Titre de l'article"
+				onChange={(title) => onChange({ ...block, title })}
+				className="font-bold text-[17px] leading-[1.3]"
+				style={{ color: EMAIL_COLOR.brand }}
+			/>
+			{meta === "" ? null : <EmailCardMeta>{meta}</EmailCardMeta>}
+			<textarea
+				aria-label="Résumé de l'article"
+				value={block.description}
+				placeholder="Le résumé de l'article."
+				rows={2}
+				onChange={(event) =>
+					onChange({ ...block, description: event.target.value })
+				}
+				className="w-full resize-none border-none bg-transparent p-0 text-[15px] leading-[1.5] outline-none [field-sizing:content] placeholder:opacity-40"
+				style={{ color: EMAIL_COLOR.ink }}
+			/>
+		</EmailCardShell>
+	);
+}
+
+function ArticleBlockSettings({
+	block,
+	onChange,
+}: EmailBlockComponentProps<EmailEditorArticleBlock>) {
+	return (
+		<>
+			<BlockOptionSection title="Contenu">
+				<TextOption
+					label="Titre"
+					value={block.title}
+					onChange={(title) => onChange({ ...block, title })}
+				/>
+				<TextAreaOption
+					label="Résumé"
+					value={block.description}
+					onChange={(description) => onChange({ ...block, description })}
+				/>
+				<TextOption
+					label="Auteur"
+					value={block.author}
+					onChange={(author) => onChange({ ...block, author })}
+				/>
+				<TextOption
+					label="Date de publication"
+					value={block.publishDate}
+					onChange={(publishDate) => onChange({ ...block, publishDate })}
+					placeholder="2026-07-20"
+					description="Format AAAA-MM-JJ ; la date est écrite dans la langue du destinataire à l'envoi."
+				/>
+			</BlockOptionSection>
+			<BlockOptionSection title="Apparence">
+				<TextOption
+					label="Adresse de l'image"
+					value={block.image.src}
+					onChange={(src) =>
+						onChange({ ...block, image: { ...block.image, src } })
+					}
+					placeholder="https://"
+				/>
+				<TextOption
+					label="Texte alternatif"
+					value={block.image.alt}
+					onChange={(alt) =>
+						onChange({ ...block, image: { ...block.image, alt } })
+					}
+				/>
+			</BlockOptionSection>
+			<BlockOptionSection title="Lien">
+				<LinkOption
+					value={block.href}
+					onChange={(href) => onChange({ ...block, href })}
+					description="La carte entière renvoie vers cette adresse."
+				/>
+			</BlockOptionSection>
+		</>
+	);
+}
+
+export const articleBlockDefinition: EmailBlockDefinition<EmailEditorArticleBlock> =
+	{
+		label: "Article",
+		icon: NewspaperIcon,
+		View: ArticleBlockView,
+		Settings: ArticleBlockSettings,
+	};

package/src/blocks/block-definitions.tsx

@@ -0,0 +1,94 @@
+import type { Icon } from "@phosphor-icons/react";
+import type { ComponentType, ReactNode } from "react";
+import { articleBlockDefinition } from "#/blocks/article-block.tsx";
+import { buttonBlockDefinition } from "#/blocks/button-block.tsx";
+import { dividerBlockDefinition } from "#/blocks/divider-block.tsx";
+import { gridBlockDefinition } from "#/blocks/grid-block.tsx";
+import { headingBlockDefinition } from "#/blocks/heading-block.tsx";
+import { imageBlockDefinition } from "#/blocks/image-block.tsx";
+import { listBlockDefinition } from "#/blocks/list-block.tsx";
+import { offerBlockDefinition } from "#/blocks/offer-block.tsx";
+import { paragraphBlockDefinition } from "#/blocks/paragraph-block.tsx";
+import { productBlockDefinition } from "#/blocks/product-block.tsx";
+import { ratingBlockDefinition } from "#/blocks/rating-block.tsx";
+import { statBlockDefinition } from "#/blocks/stat-block.tsx";
+import { tableBlockDefinition } from "#/blocks/table-block.tsx";
+import type {
+	EmailEditorBlock,
+	EmailEditorBlockType,
+	EmailEditorLeafBlockType,
+	EmailEditorPreview,
+} from "#/document/types.ts";
+
+/** What every block component receives, in the canvas and in the sidebar. */
+export interface EmailBlockComponentProps<
+	B extends EmailEditorBlock = EmailEditorBlock,
+> {
+	block: B;
+	selected: boolean;
+	onChange: (block: B) => void;
+	onUploadImage?: (file: File) => Promise<string>;
+	/** Which rendering the canvas is showing; a block whose layout differs
+	 * between a phone and a desktop client reads it. Defaults to `desktop` in
+	 * the settings panel, where it is irrelevant. */
+	preview?: EmailEditorPreview;
+	/** Container blocks only (the grid): the child rows the canvas has already
+	 * wired for selection, drag-and-drop and their own toolbars. */
+	children?: ReactNode;
+}
+
+/**
+ * Everything the editor needs to know about one block type. Adding a block =
+ * add its interface to `document/types.ts` (type union + `createEmailEditorBlock`
+ * case), write one `blocks/<type>-block.tsx` exporting a definition, and
+ * register it below — the mapped type makes a missing entry a compile error,
+ * and the menu, canvas and sidebar all pick it up from here.
+ */
+export interface EmailBlockDefinition<
+	B extends EmailEditorBlock = EmailEditorBlock,
+> {
+	/** French label shown in the add-block menu. */
+	readonly label: string;
+	readonly icon: Icon;
+	/** The WYSIWYG rendering, edited in place on the canvas. */
+	readonly View: ComponentType<EmailBlockComponentProps<B>>;
+	/** The per-block settings panel; null when the block has none. */
+	readonly Settings: ComponentType<EmailBlockComponentProps<B>> | null;
+}
+
+export const EMAIL_BLOCK_DEFINITIONS: {
+	readonly [T in EmailEditorBlockType]: EmailBlockDefinition<
+		Extract<EmailEditorBlock, { type: T }>
+	>;
+} = {
+	heading: headingBlockDefinition,
+	paragraph: paragraphBlockDefinition,
+	button: buttonBlockDefinition,
+	image: imageBlockDefinition,
+	divider: dividerBlockDefinition,
+	list: listBlockDefinition,
+	stat: statBlockDefinition,
+	table: tableBlockDefinition,
+	article: articleBlockDefinition,
+	product: productBlockDefinition,
+	offer: offerBlockDefinition,
+	rating: ratingBlockDefinition,
+	grid: gridBlockDefinition,
+};
+
+export const EMAIL_BLOCK_TYPES = Object.keys(
+	EMAIL_BLOCK_DEFINITIONS,
+) as ReadonlyArray<EmailEditorBlockType>;
+
+/** The types offered inside a grid cell: everything but the grid, which cannot
+ * nest. Derived from the registry so a new leaf block appears automatically. */
+export const EMAIL_LEAF_BLOCK_TYPES = EMAIL_BLOCK_TYPES.filter(
+	(type): type is EmailEditorLeafBlockType => type !== "grid",
+);
+
+/** Look up a block's definition with the union narrowed away — the registry
+ * guarantees the definition matches the block's own type. */
+export const emailBlockDefinition = (
+	block: EmailEditorBlock,
+): EmailBlockDefinition =>
+	EMAIL_BLOCK_DEFINITIONS[block.type] as EmailBlockDefinition;

package/src/blocks/block-text-input.tsx

@@ -0,0 +1,44 @@
+import type { CSSProperties } from "react";
+
+/**
+ * A single-line field that *wraps* instead of clipping. An `<input>` scrolls
+ * its overflow out of sight, which is wrong on a canvas that has to mirror the
+ * email: inside a 178px grid cell a heading or a stat label has to run onto a
+ * second line exactly as the reader will see it.
+ *
+ * So it is a one-row `<textarea>` sized to its content, with Enter suppressed
+ * — the block model holds a plain string, and a line break in it would mean
+ * nothing to the renderer.
+ */
+export function BlockTextInput({
+	value,
+	onChange,
+	ariaLabel,
+	placeholder,
+	className,
+	style,
+}: {
+	value: string;
+	onChange: (value: string) => void;
+	ariaLabel: string;
+	placeholder?: string;
+	className?: string;
+	style?: CSSProperties;
+}) {
+	return (
+		<textarea
+			aria-label={ariaLabel}
+			rows={1}
+			value={value}
+			placeholder={placeholder}
+			onChange={(event) => onChange(event.target.value)}
+			onKeyDown={(event) => {
+				if (event.key === "Enter") {
+					event.preventDefault();
+				}
+			}}
+			className={`w-full resize-none overflow-hidden border-none bg-transparent p-0 outline-none [field-sizing:content] placeholder:opacity-40 ${className ?? ""}`}
+			style={style}
+		/>
+	);
+}

package/src/blocks/button-block.tsx

@@ -0,0 +1,119 @@
+import { CursorClickIcon } from "@phosphor-icons/react";
+import type {
+	EmailBlockComponentProps,
+	EmailBlockDefinition,
+} from "#/blocks/block-definitions.tsx";
+import type {
+	EmailEditorAlignment,
+	EmailEditorButtonBlock,
+	EmailEditorButtonVariant,
+} from "#/document/types.ts";
+import { AlignmentOption } from "#/sections/block-options/alignment-option.tsx";
+import { BlockOptionSection } from "#/sections/block-options/block-option-row.tsx";
+import { SelectOption } from "#/sections/block-options/select-option.tsx";
+import {
+	LinkOption,
+	TextOption,
+} from "#/sections/block-options/text-option.tsx";
+import { EMAIL_COLOR, EMAIL_FONT } from "#/theme.ts";
+
+const VARIANT_OPTIONS: ReadonlyArray<{
+	readonly value: EmailEditorButtonVariant;
+	readonly label: string;
+}> = [
+	{ value: "primary", label: "Plein (couleur de marque)" },
+	{ value: "secondary", label: "Contour" },
+];
+
+/** Flexbox equivalents of the email's `align` attribute. */
+const JUSTIFY: { readonly [A in EmailEditorAlignment]: string } = {
+	left: "flex-start",
+	center: "center",
+	right: "flex-end",
+};
+
+/**
+ * The call-to-action button. The label is edited in place; the target URL, the
+ * alignment and the variant live in the settings sidebar (no inline chip — the
+ * button carries one link for the whole block, unlike a paragraph's
+ * per-selection links). Mirrors the domain `emailButton` component.
+ */
+function ButtonBlockView({
+	block,
+	onChange,
+}: EmailBlockComponentProps<EmailEditorButtonBlock>) {
+	const filled = block.variant === "primary";
+	return (
+		<div className="flex" style={{ justifyContent: JUSTIFY[block.align] }}>
+			<span
+				className="inline-block rounded-lg px-[30px] py-[13px]"
+				style={{
+					backgroundColor: filled ? EMAIL_COLOR.brand : "transparent",
+					border: `1px solid ${EMAIL_COLOR.brand}`,
+				}}
+			>
+				<input
+					aria-label="Libellé du bouton"
+					value={block.label}
+					onChange={(event) =>
+						onChange({ ...block, label: event.target.value })
+					}
+					placeholder="Votre bouton"
+					className="min-w-16 max-w-full border-none bg-transparent p-0 text-center font-semibold text-[15px] leading-none outline-none [field-sizing:content] placeholder:opacity-50"
+					style={{
+						fontFamily: EMAIL_FONT,
+						color: filled ? "#ffffff" : EMAIL_COLOR.brand,
+					}}
+				/>
+			</span>
+		</div>
+	);
+}
+
+function ButtonBlockSettings({
+	block,
+	onChange,
+}: EmailBlockComponentProps<EmailEditorButtonBlock>) {
+	return (
+		<>
+			<BlockOptionSection title="Contenu">
+				<TextOption
+					label="Libellé"
+					value={block.label}
+					onChange={(label) => onChange({ ...block, label })}
+				/>
+			</BlockOptionSection>
+			<BlockOptionSection title="Apparence">
+				<AlignmentOption
+					value={block.align}
+					onChange={(align) => onChange({ ...block, align })}
+				/>
+				<SelectOption
+					label="Style"
+					value={block.variant}
+					options={VARIANT_OPTIONS}
+					onChange={(variant) => onChange({ ...block, variant })}
+					description={
+						block.variant === "secondary"
+							? "Outlook (moteur Word) ignore les coins arrondis : le contour y sera à angles droits."
+							: undefined
+					}
+				/>
+			</BlockOptionSection>
+			<BlockOptionSection title="Lien">
+				<LinkOption
+					value={block.href}
+					onChange={(href) => onChange({ ...block, href })}
+				/>
+			</BlockOptionSection>
+		</>
+	);
+}
+
+export const buttonBlockDefinition: EmailBlockDefinition<EmailEditorButtonBlock> =
+	{
+		label: "Bouton",
+		icon: CursorClickIcon,
+		View: ButtonBlockView,
+		Settings: ButtonBlockSettings,
+	};

package/src/blocks/divider-block.tsx

@@ -0,0 +1,19 @@
+import { MinusIcon } from "@phosphor-icons/react";
+import type { EmailBlockDefinition } from "#/blocks/block-definitions.tsx";
+import type { EmailEditorDividerBlock } from "#/document/types.ts";
+import { EMAIL_COLOR } from "#/theme.ts";
+
+/** A horizontal rule. Mirrors the domain `emailDivider` component. */
+function DividerBlockView() {
+	return (
+		<hr className="my-2 border-t" style={{ borderColor: EMAIL_COLOR.border }} />
+	);
+}
+
+export const dividerBlockDefinition: EmailBlockDefinition<EmailEditorDividerBlock> =
+	{
+		label: "Séparateur",
+		icon: MinusIcon,
+		View: DividerBlockView,
+		Settings: null,
+	};

package/src/blocks/email-card-shell.tsx

@@ -0,0 +1,80 @@
+import { ImageIcon } from "@phosphor-icons/react";
+import type { ReactNode } from "react";
+import type { EmailEditorCardImage } from "#/document/types.ts";
+import { EMAIL_COLOR, EMAIL_FONT } from "#/theme.ts";
+
+/**
+ * The one card shape. The article, product and offer blocks are all
+ * card-shaped, so they share this shell (and its `emailCard` counterpart in
+ * the renderer) rather than each growing its own border, radius and padding —
+ * which is exactly how three cards drift into three looks.
+ */
+export function EmailCardShell({
+	image,
+	highlighted = false,
+	children,
+}: {
+	/** Omit for a card with no visual; an empty `src` renders the placeholder. */
+	image?: EmailEditorCardImage;
+	highlighted?: boolean;
+	children: ReactNode;
+}) {
+	return (
+		<div
+			className="overflow-hidden rounded-[14px]"
+			style={{
+				border: `${highlighted ? 2 : 1}px solid ${highlighted ? EMAIL_COLOR.brand : EMAIL_COLOR.border}`,
+				backgroundColor: EMAIL_COLOR.card,
+				fontFamily: EMAIL_FONT,
+			}}
+		>
+			{image === undefined ? null : <EmailCardImage image={image} />}
+			<div className="flex flex-col gap-2 px-[18px] py-4">{children}</div>
+		</div>
+	);
+}
+
+function EmailCardImage({ image }: { image: EmailEditorCardImage }) {
+	if (image.src === "") {
+		return (
+			<div
+				className="flex h-28 items-center justify-center"
+				style={{
+					backgroundColor: EMAIL_COLOR.canvas,
+					color: EMAIL_COLOR.muted,
+				}}
+			>
+				<ImageIcon size={24} aria-hidden />
+			</div>
+		);
+	}
+	return <img src={image.src} alt={image.alt} className="block w-full" />;
+}
+
+/** The muted meta line a card puts under its title (author, date, period). */
+export function EmailCardMeta({ children }: { children: ReactNode }) {
+	return (
+		<div
+			className="text-[13px] leading-[1.4]"
+			style={{ color: EMAIL_COLOR.muted }}
+		>
+			{children}
+		</div>
+	);
+}
+
+/** A card's call to action. The target lives in the settings, so the canvas
+ * only shows the pill; an empty label means the card has no button. */
+export function EmailCardButton({ label }: { label: string }) {
+	if (label === "") {
+		return null;
+	}
+	return (
+		<span
+			className="mt-1 inline-block self-start rounded-lg px-[18px] py-[10px] font-semibold text-[14px] text-white"
+			style={{ backgroundColor: EMAIL_COLOR.brand }}
+		>
+			{label}
+		</span>
+	);
+}

package/src/blocks/grid-block.tsx

@@ -0,0 +1,95 @@
+import { ColumnsIcon } from "@phosphor-icons/react";
+import type {
+	EmailBlockComponentProps,
+	EmailBlockDefinition,
+} from "#/blocks/block-definitions.tsx";
+import type {
+	EmailEditorGridBlock,
+	EmailEditorGridColumns,
+	EmailEditorGridMobileColumns,
+} from "#/document/types.ts";
+import { BlockOptionSection } from "#/sections/block-options/block-option-row.tsx";
+import { SegmentedOption } from "#/sections/block-options/segmented-option.tsx";
+
+/** The gutter between two cells, mirrored by the renderer's cell padding. */
+export const EMAIL_GRID_GAP_PX = 16;
+
+const DESKTOP_COLUMN_OPTIONS: ReadonlyArray<{
+	readonly value: EmailEditorGridColumns;
+	readonly label: string;
+}> = [
+	{ value: 1, label: "1" },
+	{ value: 2, label: "2" },
+	{ value: 3, label: "3" },
+	{ value: 4, label: "4" },
+];
+
+const MOBILE_COLUMN_OPTIONS: ReadonlyArray<{
+	readonly value: EmailEditorGridMobileColumns;
+	readonly label: string;
+}> = [
+	{ value: 1, label: "1" },
+	{ value: 2, label: "2" },
+];
+
+/**
+ * The layout shell of a multi-column row. The cells themselves — the child
+ * block rows and the « ajouter » slot — are composed by the canvas and slotted
+ * in as `children`, so the grid owns the layout and nothing else.
+ *
+ * The cells mirror the count the reader will actually get in the previewed
+ * client, which is what makes the desktop/mobile switch meaningful.
+ */
+function GridBlockView({
+	block,
+	preview,
+	children,
+}: EmailBlockComponentProps<EmailEditorGridBlock>) {
+	const columns =
+		preview === "mobile" ? block.mobileColumns : block.desktopColumns;
+	return (
+		<div
+			className="grid items-start"
+			style={{
+				gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+				gap: `${EMAIL_GRID_GAP_PX}px`,
+			}}
+		>
+			{children}
+		</div>
+	);
+}
+
+function GridBlockSettings({
+	block,
+	onChange,
+}: EmailBlockComponentProps<EmailEditorGridBlock>) {
+	return (
+		<BlockOptionSection title="Apparence">
+			<SegmentedOption
+				label="Colonnes (ordinateur)"
+				value={block.desktopColumns}
+				options={DESKTOP_COLUMN_OPTIONS}
+				onChange={(desktopColumns) => onChange({ ...block, desktopColumns })}
+			/>
+			<SegmentedOption
+				label="Colonnes (mobile)"
+				value={block.mobileColumns}
+				options={MOBILE_COLUMN_OPTIONS}
+				onChange={(mobileColumns) => onChange({ ...block, mobileColumns })}
+				description={
+					block.mobileColumns === block.desktopColumns
+						? undefined
+						: "Un nombre de colonnes différent sur mobile repose sur une media query : l'application Gmail sur compte tiers l'ignore et repasse à une colonne."
+				}
+			/>
+		</BlockOptionSection>
+	);
+}
+
+export const gridBlockDefinition: EmailBlockDefinition<EmailEditorGridBlock> = {
+	label: "Colonnes",
+	icon: ColumnsIcon,
+	View: GridBlockView,
+	Settings: GridBlockSettings,
+};