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

package/src/document/types.ts

@@ -0,0 +1,388 @@
+/**
+ * The editor document model, owned by this package. The domain's
+ * `MarketingEmailDocument` Effect Schema mirrors this shape exactly (a
+ * type-assertion test in `packages/domain` guards against drift), so a document
+ * produced here can be persisted and rendered server-side as-is.
+ *
+ * Text fields may carry `{{firstName}}` / `{{lastName}}` / `{{email}}`
+ * placeholders; substitution happens at render time, not in the editor.
+ */
+export const EMAIL_EDITOR_DOCUMENT_VERSION = 1;
+
+/**
+ * Which rendering of the email the canvas is showing. Not part of the
+ * document — it is a view of it — but every block gets it, because what a
+ * reader sees depends on it (a grid's column count, the card's width).
+ */
+export type EmailEditorPreview = "desktop" | "mobile";
+
+/** The card width each preview mirrors: the full 600px email card, or a
+ * common phone viewport. */
+export const EMAIL_PREVIEW_WIDTH: {
+	readonly [P in EmailEditorPreview]: number;
+} = { desktop: 600, mobile: 390 };
+
+/**
+ * The shared option vocabulary. Declared once here and mirrored once in the
+ * domain schema; a new option reuses one of these rather than inventing a
+ * per-block string union (§3.2 of the editor plan).
+ */
+export type EmailEditorAlignment = "left" | "center" | "right";
+export type EmailEditorButtonVariant = "primary" | "secondary";
+export type EmailEditorHeadingLevel = 1 | 2;
+export type EmailEditorImageWidth = "full" | "contained";
+/** No embedded video survives an email client, so a video is a thumbnail with
+ * a play badge composited over it. */
+export type EmailEditorImageOverlay = "none" | "play";
+
+export interface EmailEditorHeadingBlock {
+	readonly id: string;
+	readonly type: "heading";
+	readonly text: string;
+	/** H1 for the email's title, H2 for a section — a long email needs the
+	 * hierarchy, and every heading was the same size before. */
+	readonly level: EmailEditorHeadingLevel;
+}
+
+/**
+ * A run of paragraph text sharing the same inline formatting. Rich text is a
+ * flat list of these spans — no nesting, trivially safe to render (escape the
+ * text, wrap the marks) and to extend with a new mark.
+ */
+export interface EmailEditorTextSpan {
+	readonly text: string;
+	readonly bold?: boolean;
+	readonly italic?: boolean;
+	readonly underline?: boolean;
+	/** Present when the run is a link. */
+	readonly href?: string;
+}
+
+export interface EmailEditorParagraphBlock {
+	readonly id: string;
+	readonly type: "paragraph";
+	readonly spans: ReadonlyArray<EmailEditorTextSpan>;
+}
+
+export interface EmailEditorButtonBlock {
+	readonly id: string;
+	readonly type: "button";
+	readonly label: string;
+	readonly href: string;
+	readonly align: EmailEditorAlignment;
+	/** `primary` is the filled brand button, `secondary` the outlined one. */
+	readonly variant: EmailEditorButtonVariant;
+}
+
+export interface EmailEditorImageBlock {
+	readonly id: string;
+	readonly type: "image";
+	readonly src: string;
+	readonly alt: string;
+	/** Wraps the image in a link when non-empty. */
+	readonly href: string;
+	readonly width: EmailEditorImageWidth;
+	readonly overlay: EmailEditorImageOverlay;
+	/** Rounded corners, on by default. Outlook's Word engine squares them off
+	 * regardless — the toggle says so next to it. */
+	readonly rounded: boolean;
+}
+
+export interface EmailEditorDividerBlock {
+	readonly id: string;
+	readonly type: "divider";
+}
+
+export type EmailEditorListMarker = "bullet" | "number" | "badge";
+
+/** One list entry: an optional bold lead-in, then the same span model the
+ * paragraph uses — so bold/italic/underline/links work inside items for free. */
+export interface EmailEditorListItem {
+	readonly title?: string;
+	readonly spans: ReadonlyArray<EmailEditorTextSpan>;
+}
+
+export interface EmailEditorListBlock {
+	readonly id: string;
+	readonly type: "list";
+	readonly marker: EmailEditorListMarker;
+	readonly items: ReadonlyArray<EmailEditorListItem>;
+}
+
+/**
+ * A single figure. One stat per block on purpose: a row of three is a
+ * three-column grid of stat blocks, not a block that invents its own layout
+ * (§1.5 of the editor plan).
+ */
+export interface EmailEditorStatBlock {
+	readonly id: string;
+	readonly type: "stat";
+	readonly value: string;
+	readonly label: string;
+	readonly description: string;
+	readonly align: EmailEditorAlignment;
+}
+
+export type EmailEditorRatingStyle = "filled" | "outline";
+
+/**
+ * A one-to-five satisfaction question. Each step is its own link to `href`
+ * with `?rating=N` appended, so the five variants are five separately
+ * countable tracked links — the distribution falls out of the click stats.
+ */
+export interface EmailEditorRatingBlock {
+	readonly id: string;
+	readonly type: "rating";
+	readonly question: ReadonlyArray<EmailEditorTextSpan>;
+	readonly style: EmailEditorRatingStyle;
+	readonly lowLabel: string;
+	readonly highLabel: string;
+	readonly href: string;
+}
+
+export interface EmailEditorTableColumn {
+	readonly label: string;
+	readonly align: "left" | "right";
+}
+
+/** The currencies the platform transacts in, mirroring the domain's
+ * `SupportedCurrency`. */
+export type EmailEditorCurrency = "EUR";
+
+/**
+ * A price, stored the way the platform stores money everywhere: an integer
+ * amount in the currency's minor unit plus its currency, never a
+ * pre-formatted string — one campaign can go out in several locales, so the
+ * formatting happens at render.
+ */
+export interface EmailEditorMoney {
+	readonly amountInMinorUnits: number;
+	readonly currency: EmailEditorCurrency;
+}
+
+/** The visual of a card block. An empty `src` means the card has none. */
+export interface EmailEditorCardImage {
+	readonly src: string;
+	readonly alt: string;
+}
+
+/**
+ * A blog post or an external resource. The field names follow the real blog
+ * model (`your blog content model`), so composing a digest from published
+ * posts is a straight mapping. Empty strings stand for the absent optionals.
+ */
+export interface EmailEditorArticleBlock {
+	readonly id: string;
+	readonly type: "article";
+	readonly title: string;
+	readonly description: string;
+	readonly image: EmailEditorCardImage;
+	readonly author: string;
+	/** ISO date (`YYYY-MM-DD`), formatted for the recipient at render. */
+	readonly publishDate: string;
+	readonly href: string;
+}
+
+export interface EmailEditorProductBlock {
+	readonly id: string;
+	readonly type: "product";
+	readonly name: string;
+	readonly description: string;
+	readonly image: EmailEditorCardImage;
+	readonly price: EmailEditorMoney;
+	/** The struck-through « tarif de base », mirroring the shop catalogue's
+	 * `publicPriceHtCents`. Null when the product is not discounted. */
+	readonly compareAtPrice: EmailEditorMoney | null;
+	readonly href: string;
+	readonly buttonLabel: string;
+}
+
+export interface EmailEditorOfferBlock {
+	readonly id: string;
+	readonly type: "offer";
+	readonly eyebrow: string;
+	readonly name: string;
+	readonly description: string;
+	readonly image: EmailEditorCardImage;
+	readonly price: EmailEditorMoney;
+	/** « par mois », « par an »; empty for a one-off price. */
+	readonly period: string;
+	readonly features: ReadonlyArray<string>;
+	readonly buttonLabel: string;
+	readonly buttonHref: string;
+	/** Draws the card in the brand colour — the recommended plan of a row. */
+	readonly highlighted: boolean;
+}
+
+export interface EmailEditorTableBlock {
+	readonly id: string;
+	readonly type: "table";
+	readonly columns: ReadonlyArray<EmailEditorTableColumn>;
+	/** Row-major plain-text cells; a short row renders blank trailing cells. */
+	readonly rows: ReadonlyArray<ReadonlyArray<string>>;
+	readonly headerRow: boolean;
+}
+
+/** Everything that can sit inside a grid cell — that is, every block but the
+ * grid itself. */
+export type EmailEditorLeafBlock =
+	| EmailEditorHeadingBlock
+	| EmailEditorParagraphBlock
+	| EmailEditorButtonBlock
+	| EmailEditorImageBlock
+	| EmailEditorDividerBlock
+	| EmailEditorListBlock
+	| EmailEditorStatBlock
+	| EmailEditorTableBlock
+	| EmailEditorArticleBlock
+	| EmailEditorProductBlock
+	| EmailEditorOfferBlock
+	| EmailEditorRatingBlock;
+
+export type EmailEditorGridColumns = 1 | 2 | 3 | 4;
+export type EmailEditorGridMobileColumns = 1 | 2;
+
+/**
+ * A multi-column row. `children` is a flat list that *flows* into the columns
+ * rather than explicit per-column buckets — that covers every layout we need
+ * (a gallery, two article cards, three offers) at a fraction of the
+ * complexity, and an asymmetric layout is simply two sibling blocks.
+ *
+ * A grid cannot contain a grid: the type forbids it, which is what keeps the
+ * reducer, the drag-and-drop layer and the renderer tractable.
+ */
+export interface EmailEditorGridBlock {
+	readonly id: string;
+	readonly type: "grid";
+	readonly desktopColumns: EmailEditorGridColumns;
+	/** Defaults to 1 so the layout is readable in the clients that ignore the
+	 * media query pinning this count (see the renderer). */
+	readonly mobileColumns: EmailEditorGridMobileColumns;
+	readonly children: ReadonlyArray<EmailEditorLeafBlock>;
+}
+
+export type EmailEditorBlock = EmailEditorLeafBlock | EmailEditorGridBlock;
+
+export type EmailEditorBlockType = EmailEditorBlock["type"];
+export type EmailEditorLeafBlockType = EmailEditorLeafBlock["type"];
+
+export const isEmailEditorGridBlock = (
+	block: EmailEditorBlock,
+): block is EmailEditorGridBlock => block.type === "grid";
+
+export interface EmailEditorDocument {
+	readonly version: typeof EMAIL_EDITOR_DOCUMENT_VERSION;
+	readonly blocks: ReadonlyArray<EmailEditorBlock>;
+}
+
+export const emptyEmailEditorDocument = (): EmailEditorDocument => ({
+	version: EMAIL_EDITOR_DOCUMENT_VERSION,
+	blocks: [],
+});
+
+/** A freshly added block of the given type, with empty content fields. */
+export const createEmailEditorBlock = (
+	type: EmailEditorBlockType,
+	id: string,
+): EmailEditorBlock => {
+	switch (type) {
+		case "heading":
+			return { id, type, text: "", level: 1 };
+		case "paragraph":
+			return { id, type, spans: [] };
+		case "button":
+			return {
+				id,
+				type,
+				label: "",
+				href: "",
+				align: "center",
+				variant: "primary",
+			};
+		case "image":
+			return {
+				id,
+				type,
+				src: "",
+				alt: "",
+				href: "",
+				width: "full",
+				overlay: "none",
+				rounded: true,
+			};
+		case "divider":
+			return { id, type };
+		case "list":
+			return { id, type, marker: "bullet", items: [{ spans: [] }] };
+		case "stat":
+			return {
+				id,
+				type,
+				value: "",
+				label: "",
+				description: "",
+				align: "center",
+			};
+		case "table":
+			return {
+				id,
+				type,
+				columns: [
+					{ label: "", align: "left" },
+					{ label: "", align: "right" },
+				],
+				rows: [["", ""]],
+				headerRow: true,
+			};
+		case "article":
+			return {
+				id,
+				type,
+				title: "",
+				description: "",
+				image: { src: "", alt: "" },
+				author: "",
+				publishDate: "",
+				href: "",
+			};
+		case "product":
+			return {
+				id,
+				type,
+				name: "",
+				description: "",
+				image: { src: "", alt: "" },
+				price: { amountInMinorUnits: 0, currency: "EUR" },
+				compareAtPrice: null,
+				href: "",
+				buttonLabel: "",
+			};
+		case "offer":
+			return {
+				id,
+				type,
+				eyebrow: "",
+				name: "",
+				description: "",
+				image: { src: "", alt: "" },
+				price: { amountInMinorUnits: 0, currency: "EUR" },
+				period: "",
+				features: [],
+				buttonLabel: "",
+				buttonHref: "",
+				highlighted: false,
+			};
+		case "rating":
+			return {
+				id,
+				type,
+				question: [],
+				style: "filled",
+				lowLabel: "",
+				highLabel: "",
+				href: "",
+			};
+		case "grid":
+			return { id, type, desktopColumns: 2, mobileColumns: 1, children: [] };
+	}
+};

package/src/email-block-editor.tsx

@@ -0,0 +1,163 @@
+import {
+	Drawer,
+	DrawerContent,
+	DrawerDescription,
+	DrawerHeader,
+	DrawerTitle,
+} from "@voila.dev/ui/components/drawer";
+import { type ReactNode, useCallback, useMemo, useState } from "react";
+import {
+	createEmailEditorReducer,
+	type EmailEditorAction,
+	type EmailEditorState,
+} from "#/document/reducer.ts";
+import type {
+	EmailEditorDocument,
+	EmailEditorPreview,
+} from "#/document/types.ts";
+import { useCompactEditorLayout } from "#/lib/use-media-query.ts";
+import { EditorCanvas } from "#/sections/editor-canvas.tsx";
+import {
+	BlockSettingsPanel,
+	EditorSidebar,
+} from "#/sections/editor-sidebar.tsx";
+import { PreviewToggle } from "#/sections/preview-toggle.tsx";
+
+/** « Réglages du bloc » as a bottom sheet, for the viewports where a 280px
+ * column would put the options a screenful away from their block. */
+function BlockSettingsSheet({
+	open,
+	onOpenChange,
+	state,
+	dispatch,
+	onUploadImage,
+}: {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	state: EmailEditorState;
+	dispatch: (action: EmailEditorAction) => void;
+	onUploadImage?: (file: File) => Promise<string>;
+}) {
+	return (
+		<Drawer open={open} onOpenChange={onOpenChange}>
+			<DrawerContent>
+				<DrawerHeader>
+					<DrawerTitle>Réglages du bloc</DrawerTitle>
+					<DrawerDescription className="sr-only">
+						Options du bloc sélectionné.
+					</DrawerDescription>
+				</DrawerHeader>
+				<div className="flex flex-col gap-4 overflow-y-auto px-4 pb-8">
+					<BlockSettingsPanel
+						state={state}
+						dispatch={dispatch}
+						onUploadImage={onUploadImage}
+					/>
+				</div>
+			</DrawerContent>
+		</Drawer>
+	);
+}
+
+/**
+ * The composed WYSIWYG email editor. On a wide viewport it is the canvas plus
+ * a per-block settings column; below `lg` the column would push the options a
+ * screenful away from the block they configure, so the settings move into a
+ * bottom sheet opened from the selected block's toolbar.
+ *
+ * The document is controlled (`document`/`onChange`); the block selection is
+ * internal UI state. Every building part (blocks, sections, dnd list, reducer)
+ * is also exported individually for custom compositions.
+ */
+// fallow-ignore-next-line complexity -- composition, not logic: the compact/wide split picks a layout and the rest is prop wiring.
+export function EmailBlockEditor({
+	document,
+	onChange,
+	onUploadImage,
+	generateBlockId = () => crypto.randomUUID(),
+	headerSlot,
+	footerSlot,
+}: {
+	document: EmailEditorDocument;
+	onChange: (document: EmailEditorDocument) => void;
+	/** Delegated image upload: receives the picked file, resolves with its
+	 * public URL. Omit to disable image uploads. */
+	onUploadImage?: (file: File) => Promise<string>;
+	/** Block-id factory, injectable for deterministic tests. */
+	generateBlockId?: () => string;
+	headerSlot?: ReactNode;
+	footerSlot?: ReactNode;
+}) {
+	const [selectedBlockId, setSelectedBlockId] = useState<string | null>(null);
+	const [settingsSheetOpen, setSettingsSheetOpen] = useState(false);
+	const compact = useCompactEditorLayout();
+	// Editing on a phone starts on the phone rendering; the author can still
+	// switch to the desktop one to check a multi-column row.
+	const [preview, setPreview] = useState<EmailEditorPreview>(
+		compact ? "mobile" : "desktop",
+	);
+	const reduce = useMemo(
+		() => createEmailEditorReducer(generateBlockId),
+		[generateBlockId],
+	);
+
+	const dispatch = useCallback(
+		(action: EmailEditorAction) => {
+			const state = reduce({ document, selectedBlockId }, action);
+			if (state.document !== document) {
+				onChange(state.document);
+			}
+			setSelectedBlockId(state.selectedBlockId);
+		},
+		[reduce, document, selectedBlockId, onChange],
+	);
+
+	const state = { document, selectedBlockId };
+	// Only the sheet layout needs an opener; the sidebar layout is always there.
+	const openSettingsSheet = compact
+		? () => setSettingsSheetOpen(true)
+		: undefined;
+
+	return (
+		<>
+			<div
+				className={
+					compact
+						? "grid grid-cols-1 items-start gap-6"
+						: "grid grid-cols-[minmax(0,1fr)_280px] items-start gap-6"
+				}
+			>
+				<div className="flex flex-col gap-3">
+					<div className="flex items-center justify-end">
+						<PreviewToggle value={preview} onChange={setPreview} />
+					</div>
+					<EditorCanvas
+						state={state}
+						dispatch={dispatch}
+						preview={preview}
+						onUploadImage={onUploadImage}
+						onOpenSettings={openSettingsSheet}
+						headerSlot={headerSlot}
+						footerSlot={footerSlot}
+					/>
+				</div>
+				{compact ? null : (
+					<EditorSidebar
+						state={state}
+						dispatch={dispatch}
+						onUploadImage={onUploadImage}
+					/>
+				)}
+			</div>
+			{compact ? (
+				<BlockSettingsSheet
+					open={settingsSheetOpen}
+					onOpenChange={setSettingsSheetOpen}
+					state={state}
+					dispatch={dispatch}
+					onUploadImage={onUploadImage}
+				/>
+			) : null}
+		</>
+	);
+}

package/src/lib/use-media-query.ts

@@ -0,0 +1,38 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Subscribe to a CSS media query. The initial value is read synchronously so
+ * the first paint already uses the right layout (no desktop-then-mobile flash);
+ * it falls back to `false` where `window` is absent.
+ */
+const useMediaQuery = (query: string): boolean => {
+	const [matches, setMatches] = useState(() =>
+		typeof window === "undefined" ? false : window.matchMedia(query).matches,
+	);
+
+	useEffect(() => {
+		const list = window.matchMedia(query);
+		const update = () => setMatches(list.matches);
+		update();
+		list.addEventListener("change", update);
+		return () => list.removeEventListener("change", update);
+	}, [query]);
+
+	return matches;
+};
+
+/**
+ * Touch-driven pointers. Drives the 44px tap-target floor on the block
+ * toolbar, and moves that toolbar into the flow above its block instead of
+ * floating it (a 44px bar has nowhere to float on a 390px viewport).
+ */
+export const useCoarsePointer = (): boolean =>
+	useMediaQuery("(pointer: coarse)");
+
+/**
+ * Below Tailwind's `lg`, the 280px settings column no longer fits beside the
+ * canvas, so « Réglages du bloc » moves into a bottom sheet reachable from the
+ * selected block's toolbar.
+ */
+export const useCompactEditorLayout = (): boolean =>
+	useMediaQuery("(max-width: 1023px)");

package/src/sections/add-block-menu.tsx

@@ -0,0 +1,56 @@
+import { PlusIcon } from "@phosphor-icons/react";
+import { Button } from "@voila.dev/ui/components/button";
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from "@voila.dev/ui/components/dropdown-menu";
+import type { ReactElement } from "react";
+import {
+	EMAIL_BLOCK_DEFINITIONS,
+	EMAIL_BLOCK_TYPES,
+} from "#/blocks/block-definitions.tsx";
+import type { EmailEditorBlockType } from "#/document/types.ts";
+
+/**
+ * The « Ajouter un bloc » menu, fed by the block registry. The default trigger
+ * is the outlined empty-state button; the block toolbar passes its own icon
+ * trigger instead.
+ */
+export function AddBlockMenu({
+	onAdd,
+	trigger,
+	types = EMAIL_BLOCK_TYPES,
+}: {
+	onAdd: (type: EmailEditorBlockType) => void;
+	trigger?: ReactElement;
+	/** The offerable types; a grid cell passes the leaf types only. */
+	types?: ReadonlyArray<EmailEditorBlockType>;
+}) {
+	return (
+		<DropdownMenu>
+			<DropdownMenuTrigger
+				render={
+					trigger ?? (
+						<Button variant="outline" size="sm">
+							<PlusIcon aria-hidden />
+							Ajouter un bloc
+						</Button>
+					)
+				}
+			/>
+			<DropdownMenuContent align="start">
+				{types.map((type) => {
+					const definition = EMAIL_BLOCK_DEFINITIONS[type];
+					return (
+						<DropdownMenuItem key={type} onClick={() => onAdd(type)}>
+							<definition.icon aria-hidden />
+							{definition.label}
+						</DropdownMenuItem>
+					);
+				})}
+			</DropdownMenuContent>
+		</DropdownMenu>
+	);
+}

package/src/sections/block-options/alignment-option.tsx

@@ -0,0 +1,53 @@
+import {
+	TextAlignCenterIcon,
+	TextAlignLeftIcon,
+	TextAlignRightIcon,
+} from "@phosphor-icons/react";
+import type { EmailEditorAlignment } from "#/document/types.ts";
+import { SegmentedOption } from "#/sections/block-options/segmented-option.tsx";
+
+const ALIGNMENTS: ReadonlyArray<{
+	readonly value: EmailEditorAlignment;
+	readonly label: string;
+	readonly icon: React.ReactNode;
+}> = [
+	{
+		value: "left",
+		label: "Aligner à gauche",
+		icon: <TextAlignLeftIcon aria-hidden />,
+	},
+	{
+		value: "center",
+		label: "Centrer",
+		icon: <TextAlignCenterIcon aria-hidden />,
+	},
+	{
+		value: "right",
+		label: "Aligner à droite",
+		icon: <TextAlignRightIcon aria-hidden />,
+	},
+];
+
+/**
+ * The one alignment control. Every block that can be aligned uses this exact
+ * segmented control, so « Alignement » means the same thing and looks the same
+ * everywhere (§1.2 of the editor plan).
+ */
+export function AlignmentOption({
+	label = "Alignement",
+	value,
+	onChange,
+}: {
+	label?: string;
+	value: EmailEditorAlignment;
+	onChange: (alignment: EmailEditorAlignment) => void;
+}) {
+	return (
+		<SegmentedOption
+			label={label}
+			value={value}
+			options={ALIGNMENTS}
+			onChange={onChange}
+		/>
+	);
+}