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

package/src/sections/editor-canvas.tsx

@@ -0,0 +1,403 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import { type ReactElement, type ReactNode, useState } from "react";
+import { createPortal } from "react-dom";
+import {
+	EMAIL_LEAF_BLOCK_TYPES,
+	type EmailBlockComponentProps,
+	emailBlockDefinition,
+} from "#/blocks/block-definitions.tsx";
+import { EMAIL_GRID_GAP_PX } from "#/blocks/grid-block.tsx";
+import {
+	EmailEditorDndContext,
+	SortableBlockContainer,
+	type SortableBlockHandle,
+	SortableBlockItem,
+} from "#/dnd/sortable-block-list.tsx";
+import type {
+	EmailEditorAction,
+	EmailEditorContainerId,
+	EmailEditorState,
+} from "#/document/reducer.ts";
+import {
+	EMAIL_PREVIEW_WIDTH,
+	type EmailEditorBlock,
+	type EmailEditorGridBlock,
+	type EmailEditorPreview,
+	isEmailEditorGridBlock,
+} from "#/document/types.ts";
+import { useCoarsePointer } from "#/lib/use-media-query.ts";
+import { AddBlockMenu } from "#/sections/add-block-menu.tsx";
+import { BlockToolbar } from "#/sections/block-toolbar.tsx";
+import { EMAIL_COLOR, EMAIL_FONT } from "#/theme.ts";
+
+/** Render `node` into `slot`, or in place when there is no slot. */
+const renderIn = (slot: HTMLElement | null, node: ReactElement): ReactNode =>
+	slot === null ? node : createPortal(node, slot);
+
+/** Blocks whose content is edited through the span model, and therefore want
+ * the toolbar's bold/italic/underline/link group. */
+const RICH_TEXT_BLOCK_TYPES: ReadonlySet<string> = new Set([
+	"paragraph",
+	"list",
+	"rating",
+]);
+
+/** Everything the block rows need from the editor, threaded down one level of
+ * nesting without turning each row into a ten-prop component. */
+interface CanvasContext {
+	readonly state: EmailEditorState;
+	readonly dispatch: (action: EmailEditorAction) => void;
+	readonly coarsePointer: boolean;
+	readonly preview: EmailEditorPreview;
+	readonly onUploadImage?: (file: File) => Promise<string>;
+	readonly onOpenSettings?: () => void;
+}
+
+/** The dashed « ajouter » slot of a grid cell. */
+function GridAddCell({
+	gridId,
+	context,
+}: {
+	gridId: string;
+	context: CanvasContext;
+}) {
+	return (
+		<div className="flex items-center justify-center rounded-lg border border-dashed px-2 py-6">
+			<AddBlockMenu
+				types={EMAIL_LEAF_BLOCK_TYPES}
+				onAdd={(type) =>
+					context.dispatch({
+						type: "add",
+						blockType: type,
+						containerId: gridId,
+					})
+				}
+			/>
+		</div>
+	);
+}
+
+function GridBlockCells({
+	block,
+	context,
+}: {
+	block: EmailEditorGridBlock;
+	context: CanvasContext;
+}) {
+	const definition = emailBlockDefinition(block);
+	const selected = context.state.selectedBlockId === block.id;
+	const showAddCell = selected || block.children.length === 0;
+	// Under a touch pointer a cell is far too narrow for a row of 44px targets,
+	// so a selected child's toolbar is portalled up here and gets the whole
+	// grid's width. Under a mouse the toolbar floats and needs no help.
+	const [toolbarSlot, setToolbarSlot] = useState<HTMLDivElement | null>(null);
+	return (
+		<SortableBlockContainer
+			containerId={block.id}
+			blockIds={block.children.map((child) => child.id)}
+			layout="grid"
+		>
+			<div ref={setToolbarSlot} className="mb-2 empty:mb-0" />
+			<definition.View
+				block={block}
+				selected={selected}
+				preview={context.preview}
+				onChange={(updated) =>
+					context.dispatch({ type: "update", block: updated })
+				}
+				onUploadImage={context.onUploadImage}
+			>
+				{block.children.map((child, index) => (
+					<CanvasBlockRow
+						key={child.id}
+						block={child}
+						index={index}
+						containerId={block.id}
+						context={context}
+						toolbarSlot={context.coarsePointer ? toolbarSlot : null}
+					/>
+				))}
+				{showAddCell ? (
+					<GridAddCell gridId={block.id} context={context} />
+				) : null}
+			</definition.View>
+		</SortableBlockContainer>
+	);
+}
+
+/**
+ * The controls of the selected row. It stays mounted while dragging — dnd-kit
+ * holds a reference to the drag handle it contains — but is hidden, so it
+ * stops floating over the neighbouring blocks' text.
+ *
+ * Under a touch pointer the 44px bar is too tall to float without covering the
+ * previous block, so it sits in the flow above its own block; a row inside a
+ * grid cell hands it to the grid instead, which has the width for it. The
+ * portal keeps it in this row's React tree, so dnd-kit and the selection
+ * handlers are unaffected.
+ */
+// fallow-ignore-next-line complexity -- prop wiring: one dispatch per toolbar action, plus the nested/root split.
+function CanvasBlockRowToolbar({
+	block,
+	index,
+	containerId,
+	context,
+	handle,
+	toolbarSlot,
+}: {
+	block: EmailEditorBlock;
+	index: number;
+	containerId: EmailEditorContainerId;
+	context: CanvasContext;
+	handle: SortableBlockHandle;
+	toolbarSlot: HTMLElement | null;
+}) {
+	const { dispatch, coarsePointer } = context;
+	const nested = containerId !== null;
+	return renderIn(
+		toolbarSlot,
+		<div
+			className={cn(
+				toolbarSlot !== null || coarsePointer
+					? "mb-2"
+					: "-top-9 absolute right-0 z-10",
+				handle.isDragging && "pointer-events-none opacity-0",
+			)}
+		>
+			<BlockToolbar
+				handle={handle}
+				richText={RICH_TEXT_BLOCK_TYPES.has(block.type)}
+				coarsePointer={coarsePointer}
+				addableTypes={nested ? EMAIL_LEAF_BLOCK_TYPES : undefined}
+				onAddBelow={(type) =>
+					dispatch({
+						type: "add",
+						blockType: type,
+						containerId,
+						index: index + 1,
+					})
+				}
+				onDuplicate={() => dispatch({ type: "duplicate", blockId: block.id })}
+				onRemove={() => dispatch({ type: "remove", blockId: block.id })}
+				onOpenSettings={context.onOpenSettings}
+				onSelectContainer={
+					nested
+						? () => dispatch({ type: "select", blockId: containerId })
+						: undefined
+				}
+			/>
+		</div>,
+	);
+}
+
+function CanvasBlockRow({
+	block,
+	index,
+	containerId,
+	context,
+	toolbarSlot = null,
+}: {
+	block: EmailEditorBlock;
+	index: number;
+	containerId: EmailEditorContainerId;
+	context: CanvasContext;
+	/** Where to render the toolbar when the row's own column is too narrow for
+	 * it; see {@link GridBlockCells}. */
+	toolbarSlot?: HTMLElement | null;
+}) {
+	const { dispatch } = context;
+	const selected = context.state.selectedBlockId === block.id;
+	const definition = emailBlockDefinition(block);
+	const grid = isEmailEditorGridBlock(block) ? block : null;
+	const viewProps: EmailBlockComponentProps = {
+		block,
+		selected,
+		preview: context.preview,
+		onChange: (updated) => dispatch({ type: "update", block: updated }),
+		onUploadImage: context.onUploadImage,
+	};
+	// Selecting the innermost block: the child's handler runs first and stops
+	// the event, so clicking inside a grid cell never selects the grid.
+	const select = (event: { stopPropagation: () => void }) => {
+		event.stopPropagation();
+		dispatch({ type: "select", blockId: block.id });
+	};
+
+	return (
+		<SortableBlockItem
+			blockId={block.id}
+			className={cn(
+				"group relative rounded-lg py-3",
+				// Every row's *content* starts at its container's edge, root or
+				// cell — that alignment is what makes the canvas read as one email.
+				// The padding that gives the selection ring its breathing room is
+				// cancelled by an equal negative margin, so it never shifts content.
+				// A cell gets half the 16px gutter on each side, so two neighbouring
+				// rings meet exactly rather than overlapping.
+				containerId === null ? "-mx-3 px-3" : "-mx-2 px-2",
+				selected && "ring-2 ring-ring/50",
+			)}
+		>
+			{(handle) => (
+				<>
+					{selected ? (
+						<CanvasBlockRowToolbar
+							block={block}
+							index={index}
+							containerId={containerId}
+							context={context}
+							handle={handle}
+							toolbarSlot={toolbarSlot}
+						/>
+					) : null}
+					{/* Selection follows focus (most blocks host a focusable control)
+					    plus plain clicks for non-editable blocks like the divider. */}
+					{/* biome-ignore lint/a11y/noStaticElementInteractions: selection sugar; the real controls inside stay keyboard-accessible. */}
+					{/* biome-ignore lint/a11y/useKeyWithClickEvents: same as above. */}
+					<div onClick={select} onFocus={select}>
+						{grid === null ? (
+							<definition.View {...viewProps} />
+						) : (
+							<GridBlockCells block={grid} context={context} />
+						)}
+					</div>
+				</>
+			)}
+		</SortableBlockItem>
+	);
+}
+
+/**
+ * Neutral stand-in for the branded header the server prepends. Pass
+ * `headerSlot` to render your own logo instead.
+ */
+function CardHeaderPlaceholder() {
+	return (
+		<div
+			className="flex justify-center pt-8 pb-2 text-[13px]"
+			style={{ color: EMAIL_COLOR.muted, fontFamily: EMAIL_FONT }}
+		>
+			<div className="rounded-md border border-dashed px-4 py-3">
+				Your header
+			</div>
+		</div>
+	);
+}
+
+/**
+ * Neutral stand-in for the branded footer the server appends. Pass
+ * `footerSlot` to render your own.
+ */
+function CardFooterPlaceholder() {
+	return (
+		<div
+			className="px-8 pt-6 pb-2 text-center text-[13px] leading-[1.6]"
+			style={{ color: EMAIL_COLOR.muted, fontFamily: EMAIL_FONT }}
+		>
+			<div>
+				The full footer (contact details, social links, unsubscribe) is added
+				when the email is sent.
+			</div>
+		</div>
+	);
+}
+
+/**
+ * The editing surface, dressed as the email it produces: the grey canvas, the
+ * 600px white card, the blocks, and header/footer placeholders.
+ * The real chrome is rendered server-side — the canvas only mirrors it.
+ * Blocks are added from the selected block's toolbar (+); an empty document
+ * shows a single centered add button instead.
+ */
+export function EditorCanvas({
+	state,
+	dispatch,
+	preview,
+	onUploadImage,
+	onOpenSettings,
+	headerSlot,
+	footerSlot,
+}: {
+	state: EmailEditorState;
+	dispatch: (action: EmailEditorAction) => void;
+	/** Which rendering to mirror: the 600px card, or a phone-width one where
+	 * grids collapse to their mobile column count. */
+	preview: EmailEditorPreview;
+	onUploadImage?: (file: File) => Promise<string>;
+	/** Present when the settings live in a sheet rather than in the sidebar;
+	 * each selected block's toolbar then offers a « Réglages » button. */
+	onOpenSettings?: () => void;
+	headerSlot?: ReactNode;
+	footerSlot?: ReactNode;
+}) {
+	const coarsePointer = useCoarsePointer();
+	const blocks = state.document.blocks;
+	const context: CanvasContext = {
+		state,
+		dispatch,
+		coarsePointer,
+		preview,
+		onUploadImage,
+		onOpenSettings,
+	};
+	return (
+		<div
+			className="flex justify-center rounded-lg px-4 py-8"
+			style={{ backgroundColor: EMAIL_COLOR.canvas }}
+		>
+			<div
+				className="w-full"
+				style={{ maxWidth: `${EMAIL_PREVIEW_WIDTH[preview]}px` }}
+			>
+				<div
+					className="rounded-[14px] border"
+					style={{
+						backgroundColor: EMAIL_COLOR.card,
+						borderColor: EMAIL_COLOR.border,
+					}}
+				>
+					{headerSlot ?? <CardHeaderPlaceholder />}
+					<div className="px-8 pt-2 pb-8">
+						<EmailEditorDndContext
+							blocks={blocks}
+							onMove={(blockId, toContainerId, toIndex) =>
+								dispatch({ type: "move", blockId, toContainerId, toIndex })
+							}
+						>
+							<SortableBlockContainer
+								containerId={null}
+								blockIds={blocks.map((block) => block.id)}
+								layout="list"
+								style={{ minHeight: `${EMAIL_GRID_GAP_PX}px` }}
+							>
+								{blocks.map((block, index) => (
+									<CanvasBlockRow
+										key={block.id}
+										block={block}
+										index={index}
+										containerId={null}
+										context={context}
+									/>
+								))}
+							</SortableBlockContainer>
+						</EmailEditorDndContext>
+						{blocks.length === 0 ? (
+							<div className="flex flex-col items-center gap-3 rounded-lg border border-dashed px-4 py-10">
+								<p
+									className="text-[14px]"
+									style={{ color: EMAIL_COLOR.muted, fontFamily: EMAIL_FONT }}
+								>
+									Votre email est vide.
+								</p>
+								<AddBlockMenu
+									onAdd={(type) => dispatch({ type: "add", blockType: type })}
+								/>
+							</div>
+						) : null}
+					</div>
+				</div>
+				{footerSlot ?? <CardFooterPlaceholder />}
+			</div>
+		</div>
+	);
+}

package/src/sections/editor-sidebar.tsx

@@ -0,0 +1,95 @@
+import {
+	type EmailBlockComponentProps,
+	emailBlockDefinition,
+} from "#/blocks/block-definitions.tsx";
+import {
+	allEmailEditorBlocks,
+	type EmailEditorAction,
+	type EmailEditorState,
+} from "#/document/reducer.ts";
+import type { EmailEditorBlock } from "#/document/types.ts";
+
+function SelectedBlockSettings({
+	block,
+	dispatch,
+	onUploadImage,
+}: {
+	block: EmailEditorBlock;
+	dispatch: (action: EmailEditorAction) => void;
+	onUploadImage?: (file: File) => Promise<string>;
+}) {
+	const definition = emailBlockDefinition(block);
+	if (definition.Settings === null) {
+		return (
+			<p className="text-muted-foreground text-sm">
+				Aucun réglage pour ce bloc.
+			</p>
+		);
+	}
+	const settingsProps: EmailBlockComponentProps = {
+		block,
+		selected: true,
+		onChange: (updated) => dispatch({ type: "update", block: updated }),
+		onUploadImage,
+	};
+	return <definition.Settings key={block.id} {...settingsProps} />;
+}
+
+/**
+ * The settings of the selected block, driven by the block registry. Rendered
+ * bare so it can live either in the desktop sidebar card or in the mobile
+ * bottom sheet without either owning the other's chrome.
+ */
+export function BlockSettingsPanel({
+	state,
+	dispatch,
+	onUploadImage,
+}: {
+	state: EmailEditorState;
+	dispatch: (action: EmailEditorAction) => void;
+	onUploadImage?: (file: File) => Promise<string>;
+}) {
+	// Grid children are selectable too, so the lookup walks the whole tree.
+	const selectedBlock =
+		allEmailEditorBlocks(state.document.blocks).find(
+			(block) => block.id === state.selectedBlockId,
+		) ?? null;
+
+	if (selectedBlock === null) {
+		return (
+			<p className="text-muted-foreground text-sm">
+				Sélectionnez un bloc pour modifier ses réglages.
+			</p>
+		);
+	}
+
+	return (
+		<SelectedBlockSettings
+			block={selectedBlock}
+			dispatch={dispatch}
+			onUploadImage={onUploadImage}
+		/>
+	);
+}
+
+/** The desktop settings column: the panel above, in its own titled card. */
+export function EditorSidebar({
+	state,
+	dispatch,
+	onUploadImage,
+}: {
+	state: EmailEditorState;
+	dispatch: (action: EmailEditorAction) => void;
+	onUploadImage?: (file: File) => Promise<string>;
+}) {
+	return (
+		<div className="flex flex-col gap-4 rounded-lg border bg-background p-4">
+			<h3 className="font-medium text-sm">Réglages du bloc</h3>
+			<BlockSettingsPanel
+				state={state}
+				dispatch={dispatch}
+				onUploadImage={onUploadImage}
+			/>
+		</div>
+	);
+}

package/src/sections/link-popover.tsx

@@ -0,0 +1,89 @@
+import { Button } from "@voila.dev/ui/components/button";
+import { Input } from "@voila.dev/ui/components/input";
+import {
+	Popover,
+	PopoverContent,
+	PopoverTrigger,
+} from "@voila.dev/ui/components/popover";
+import { type ReactElement, useState } from "react";
+
+/**
+ * The shared « lien » editing surface: a small popover with a URL field,
+ * apply, and an optional remove action. The paragraph toolbar drives it with
+ * text-selection callbacks; the button block edits its target through it.
+ */
+export function LinkPopover({
+	trigger,
+	initialHref,
+	onOpen,
+	onApply,
+	onRemove,
+}: {
+	trigger: ReactElement;
+	/** Resolved each time the popover opens (e.g. the link under the caret). */
+	initialHref: () => string;
+	/** Runs as the popover opens (the toolbar saves the text selection here). */
+	onOpen?: () => void;
+	onApply: (href: string) => void;
+	/** « Retirer le lien » — omitted when removing makes no sense (a button). */
+	onRemove?: () => void;
+}) {
+	const [open, setOpen] = useState(false);
+	const [href, setHref] = useState("");
+
+	return (
+		<Popover
+			open={open}
+			onOpenChange={(next) => {
+				if (next) {
+					onOpen?.();
+					setHref(initialHref());
+				}
+				setOpen(next);
+			}}
+		>
+			<PopoverTrigger render={trigger} />
+			<PopoverContent
+				side="bottom"
+				align="start"
+				className="w-[min(18rem,calc(100vw-2rem))] p-3"
+			>
+				<form
+					className="flex flex-col gap-2"
+					onSubmit={(event) => {
+						event.preventDefault();
+						onApply(href.trim());
+						setOpen(false);
+					}}
+				>
+					<Input
+						aria-label="Adresse du lien"
+						type="url"
+						placeholder="https://"
+						value={href}
+						onChange={(event) => setHref(event.target.value)}
+						autoFocus
+					/>
+					<div className="flex items-center justify-between gap-2">
+						<Button type="submit" size="sm" disabled={href.trim() === ""}>
+							Appliquer
+						</Button>
+						{onRemove ? (
+							<Button
+								type="button"
+								variant="ghost"
+								size="sm"
+								onClick={() => {
+									onRemove();
+									setOpen(false);
+								}}
+							>
+								Retirer le lien
+							</Button>
+						) : null}
+					</div>
+				</form>
+			</PopoverContent>
+		</Popover>
+	);
+}

package/src/sections/preview-toggle.tsx

@@ -0,0 +1,45 @@
+import { DesktopIcon, DeviceMobileIcon } from "@phosphor-icons/react";
+import {
+	SegmentedControl,
+	SegmentedControlItem,
+} from "@voila.dev/ui/components/segmented-control";
+import type { EmailEditorPreview } from "#/document/types.ts";
+
+const PREVIEWS: ReadonlyArray<{
+	readonly value: EmailEditorPreview;
+	readonly label: string;
+	readonly Icon: typeof DesktopIcon;
+}> = [
+	{ value: "desktop", label: "Ordinateur", Icon: DesktopIcon },
+	{ value: "mobile", label: "Mobile", Icon: DeviceMobileIcon },
+];
+
+/**
+ * Switches the canvas between the two renderings an email actually gets: the
+ * full 600px card, and a phone-width one where grids collapse to their mobile
+ * column count. Editor chrome, so it uses app styling and sits above the
+ * canvas rather than inside the card.
+ */
+export function PreviewToggle({
+	value,
+	onChange,
+}: {
+	value: EmailEditorPreview;
+	onChange: (preview: EmailEditorPreview) => void;
+}) {
+	return (
+		<SegmentedControl
+			size="sm"
+			aria-label="Aperçu"
+			value={value}
+			onValueChange={(next) => onChange(next as EmailEditorPreview)}
+		>
+			{PREVIEWS.map((preview) => (
+				<SegmentedControlItem key={preview.value} value={preview.value}>
+					<preview.Icon aria-hidden />
+					{preview.label}
+				</SegmentedControlItem>
+			))}
+		</SegmentedControl>
+	);
+}

package/src/styles.css

@@ -0,0 +1,10 @@
+/*
+ * Tailwind must scan this package or none of its classes are generated — the
+ * components ship as .tsx source, not as compiled CSS.
+ *
+ * `@source` resolves relative to the file that declares it, so this works
+ * wherever the package ends up: node_modules in an app, a symlink in a
+ * workspace. Consumers import this file and add nothing of their own.
+ */
+@source "./";
+@source not "./**/*.test.*";

package/src/theme.ts

@@ -0,0 +1,26 @@
+/**
+ * Email look mirrored into the editor canvas, so blocks render on screen the
+ * way the sent email will. Override these to match your own email theme: your
+ * server-side renderer stays the source of truth, and these values only need to
+ * agree with it closely enough that the canvas is an honest preview.
+ */
+export const EMAIL_COLOR = {
+	brand: "#151b77",
+	ink: "#2a2a33",
+	muted: "#9095a3",
+	border: "#ececf1",
+	card: "#ffffff",
+	canvas: "#f4f4f7",
+} as const;
+
+export const EMAIL_FONT =
+	"-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif";
+
+/**
+ * The locale the canvas previews prices and dates in, mirroring
+ * `renderMarketingEmailDocument`'s default. Deliberately not the browser's
+ * locale: the canvas shows what the email will look like, and a French author
+ * on an English-configured machine would otherwise see a price the recipient
+ * never gets. The sent email formats per recipient.
+ */
+export const EMAIL_PREVIEW_LOCALE = "fr-FR";