Skip to content
Brickee
Language:en Author:AtomForge

Writing plugins

A plugin is a BlockPlugin object plus two Svelte components: a view for the editor and a preview for the site. Everything a plugin needs is exported from @atom-forge/brickee — the bundled plugins use nothing else.

Anatomy

Member Type Meaning
type string The stored type. Must not start with md:; to pass the schema it must match ^[a-z][a-z0-9:-]{0,39}$.
label, hint string Name and short description in the slash and Turn-into menus.
keys string Extra search words for the slash menu.
icon Icon A @lucide/svelte icon component.
props () => P The props of a new block.
fields PropField[] The settings on the top of the block (optional).
form Component<PluginFormProps> The plugin's own form in the fields bar, below the fields (optional; see Custom fields form).
tag (props: P) => string The small label on the top of the block, before its fields. Parts separated by · are translated one by one.
content 'none' | 'text' | 'plain' | 'blocks' What the block holds. Plugins use 'none' (props only) or 'blocks' (a nested document); it decides what Turn-into offers.
view Component<PluginViewProps> The block in the editor.
preview Component<PluginPreviewProps> The block on the site (optional). Without it, Preview renders nothing for the block — for apps that render stored blocks with their own renderer.
accepts string[] A container's allowed nested blocks, as palette ids; 'md:*' is every built-in block. Default: everything the host offers.
markdown (props: P, ctx: MarkdownContext) => string Its markdown form (optional).
unique boolean At most one per document, top level only.

P is the props type of the plugin; declare it as an interface extending Record<string, unknown>.

A plugin without content

A link button: a label, a link, a size and a colour — all set in fields, nothing typed into the block itself.

// safe-url.ts — only links the site should render
export const safeUrl = (u: unknown) => {
	const s = String(u ?? '').trim();
	return /^(https?:|mailto:|\/(?!\/))/.test(s) ? s : '';
};
<!-- ButtonView.svelte: the block in the editor -->
<script lang="ts" module>
	export interface ButtonProps extends Record<string, unknown> {
		label: string;
		url: string;
		size: 'normal' | 'large';
		color: string;
	}
</script>

<script lang="ts">
	import { MousePointerClick } from '@lucide/svelte';
	import { Empty, safeColor, type PluginViewProps } from '@atom-forge/brickee';

	// Both bindable, even when the view does not use them: the editor binds them on every plugin view.
	let { props = $bindable(), blocks = $bindable() }: PluginViewProps<ButtonProps> = $props();
</script>

{#if props.label}
	<span class="button" style:background={safeColor(props.color, '#2563eb')}>{props.label}</span>
{:else}
	<Empty icon={MousePointerClick} text="Set the label and the link above" />
{/if}

<style>
	.button {
		display: inline-block;
		padding: 0.5em 1.2em;
		border-radius: 8px;
		color: #fff;
	}
</style>
<!-- ButtonPreview.svelte: the block on the site -->
<script lang="ts">
	import { safeColor, type PluginPreviewProps } from '@atom-forge/brickee';
	import type { ButtonProps } from './ButtonView.svelte';
	import { safeUrl } from './safe-url';

	let { props }: PluginPreviewProps<ButtonProps> = $props();
	const href = $derived(safeUrl(props.url));
</script>

{#if href && props.label}
	<p>
		<a class="button" class:large={props.size === 'large'} {href} style:background={safeColor(props.color, '#2563eb')}>
			{props.label}
		</a>
	</p>
{/if}
// button.ts: the plugin
import { MousePointerClick } from '@lucide/svelte';
import { mdText, type BlockPlugin } from '@atom-forge/brickee';
import ButtonView, { type ButtonProps } from './ButtonView.svelte';
import ButtonPreview from './ButtonPreview.svelte';
import { safeUrl } from './safe-url';

export const button: BlockPlugin<ButtonProps> = {
	type: 'button',
	label: 'Button',
	hint: 'A link as a button',
	keys: 'button link cta',
	icon: MousePointerClick,
	props: () => ({ label: '', url: '', size: 'normal', color: '#2563eb' }),
	fields: [
		{ key: 'label', label: 'Label', kind: 'text' },
		{ key: 'url', label: 'Link', kind: 'text', placeholder: 'https://…', parse: (s) => s.trim() },
		{
			key: 'size',
			label: 'Size',
			kind: 'select',
			options: [
				{ value: 'normal', label: 'Normal' },
				{ value: 'large', label: 'Large' }
			]
		},
		{ key: 'color', label: 'Colour', kind: 'color' }
	],
	tag: (p) => (p.size === 'large' ? 'button · large' : 'button'),
	content: 'none',
	markdown: (p) => {
		const href = safeUrl(p.url);
		return href ? `[${mdText(p.label) || href}](${href})` : '';
	},
	view: ButtonView,
	preview: ButtonPreview
};

Register it beside the others:

<Editor bind:value plugins={[...PLUGINS, button]} />
<Preview blocks={value} plugins={[...PLUGINS, button]} />

Fields

Each PropField is one setting on the top of the block. The editor draws them and stores their values in props.

Member Meaning
key The prop it edits.
label Its label (translated through messages).
kind text, textarea, color, select, slider or toggles.
placeholder Hint of an empty text field; for an optional colour, the colour a click on "none" starts from.
options { value, label }[] for select, and for a slider that steps through values. An option label may use {n}, filled with its value. For toggles, { value, label, icon }[]: icon is the button, label its tooltip.
min, max, step, unit A number slider: its range, step (default 1) and the unit shown after the value.
none The label of the unset state: a number slider's notch left of min, or an optional colour's "none" button.
format The field's text from the stored value (default: the value as a string).
parse The stored value from the field's text (default: the text).

How each kind stores its value:

Kind Stored value
text, textarea The text, or what parse returns (parse: lines stores a list of lines).
select The chosen option's value.
slider with options The value of the option at the slider's position.
slider with min and max The number as a string (for example '56'); the none notch removes the key.
color A #rrggbb string; with none, clearing it removes the key.
toggles The list of the options switched on, in options order ([] when none); the bundled table's header and footer are one.

An empty value ('', null or undefined, also when returned by parse) removes the key from props, so a preview must always handle a missing prop. A field's parse is also a good place to normalize input: the bundled YouTube field accepts any YouTube link and stores only the video id.

Custom fields form

The generated fields cover simple settings. For anything else — a picker of the app's own, values from the app's own data or context, a script — a plugin gives its own form: any Svelte component, shown in the block's fields bar below the fields (or alone, when the plugin has no fields).

The form receives PluginFormProps:

Prop Meaning
props The block's props (bindable). Assign a new object (props = { ...props, image: id }): that is one edit of the block, with its own undo step.
readonly The editor is read-only. The fields bar, and with it the form, is not shown then.

The form is the app's code, so it takes its data wherever the app keeps it — its own modules, stores, or a Svelte context the app provides above the editor (plugin components are rendered beneath it). The editor knows nothing about it. A photo block, for example, stores the id of an image of the app's library and offers the images of the album the app names in a context of its own:

// images.ts — the app's own data and context
import { getContext, setContext } from 'svelte';

export const IMAGES = [
	{ id: 'ocean', album: 'cool', url: '/img/ocean.jpg' },
	{ id: 'sunrise', album: 'warm', url: '/img/sunrise.jpg' }
];
export const findImage = (id: unknown) => IMAGES.find((i) => i.id === id);

export const provideAlbum = (get: () => string) => setContext('app:album', get);
export const useAlbum = (): (() => string) => getContext<() => string>('app:album') ?? (() => 'cool');
<!-- PhotoForm.svelte -->
<script lang="ts">
	import type { PluginFormProps } from '@atom-forge/brickee';
	import { IMAGES, useAlbum } from './images';
	import type { PhotoProps } from './PhotoView.svelte';

	let { props = $bindable() }: PluginFormProps<PhotoProps> = $props();
	const album = useAlbum();
</script>

{#each IMAGES.filter((m) => m.album === album()) as m (m.id)}
	<button type="button" onclick={() => (props = { ...props, image: m.id })}>
		<img src={m.url} alt={m.id} width="64" />
	</button>
{/each}
// photo.ts
export const photo: BlockPlugin<PhotoProps> = {
	type: 'photo',
	// …
	props: () => ({ image: '', alt: '' }),
	fields: [{ key: 'alt', label: 'Alt text', kind: 'text', placeholder: 'What the image shows' }],
	form: PhotoForm,
	view: PhotoView, // shows findImage(props.image)
	preview: PhotoPreview, // the same, for the site
	markdown: (p) => {
		const url = findImage(p.image)?.url;
		return url ? `![${mdText(p.alt)}](${url})` : '';
	}
};

The host sets the album around the editor with provideAlbum(() => album). markdown runs outside components (copying blocks, toMarkdown), so it can use module data only, not a context. The stored id is a prop like any other, so it is untrusted: the view and the preview resolve it with the app's own lookup and render nothing for an unknown one.

The view

The view receives PluginViewProps:

Prop Meaning
props The block's props (bindable): a view may also edit them in place, as the table does.
blocks The nested document (bindable); always [] for a plugin without content.
readonly The editor is read-only.
palette, plugins The host's palette (already narrowed to accepts) and plugins, for a nested editor.

Declare props and blocks with $bindable() even when the view does not use them. The fields are drawn above the view automatically; a view only has to show the block. Empty (props icon and text) is the dashed placeholder the bundled plugins show until their props are set; its text is translated.

The preview

The preview receives PluginPreviewProps: props, blocks and plugins. It is a plain Svelte component that renders the block for the site. UI text is available through useText (see Host contexts); anything else the app knows reaches it through the app's own modules and contexts.

Containers

A plugin with content: 'blocks' holds a nested document in blocks. Its view uses Frame, a thin box that draws the block's fields on its top and a nested editor below; its preview renders the inner blocks with a nested Preview.

<!-- NoteView.svelte -->
<script lang="ts" module>
	export interface NoteProps extends Record<string, unknown> {
		title: string;
	}
</script>

<script lang="ts">
	import { Frame, useText, type PluginViewProps } from '@atom-forge/brickee';

	let { props = $bindable(), blocks = $bindable(), readonly, palette, plugins }: PluginViewProps<NoteProps> = $props();
	const tr = useText();
</script>

<Frame bind:blocks {readonly} {palette} {plugins} heading={props.title} empty={tr('Note')} placeholder={tr('Write the note…')} />
<!-- NotePreview.svelte -->
<script lang="ts">
	import { Preview, type PluginPreviewProps } from '@atom-forge/brickee';
	import type { NoteProps } from './NoteView.svelte';

	let { props, blocks, plugins }: PluginPreviewProps<NoteProps> = $props();
</script>

<aside class="note">
	{#if props.title}<p class="note-title">{props.title}</p>{/if}
	<Preview {blocks} {plugins} nested />
</aside>
// note.ts
import { StickyNote } from '@lucide/svelte';
import { mdJoin, mdQuote, mdText, type BlockPlugin } from '@atom-forge/brickee';
import NoteView, { type NoteProps } from './NoteView.svelte';
import NotePreview from './NotePreview.svelte';

export const note: BlockPlugin<NoteProps> = {
	type: 'note',
	label: 'Note',
	hint: 'Boxed text with a title',
	keys: 'note aside box',
	icon: StickyNote,
	props: () => ({ title: '' }),
	fields: [{ key: 'title', label: 'Title', kind: 'text' }],
	tag: () => 'note',
	content: 'blocks',
	accepts: ['md:p', 'md:ul', 'md:ol', 'youtube'],
	markdown: (p, { inner }) => mdQuote(mdJoin(p.title && `**${mdText(p.title)}**`, inner)),
	view: NoteView,
	preview: NotePreview
};

Frame props: blocks (bindable), readonly, palette, plugins, and optionally placeholder for the nested editor. heading, empty and image (a URL) make a heading line, which is shown only when the fields are not (read-only mode or no fields).

How nesting works:

  • One level. A nested editor never offers blocks that hold blocks themselves, nor unique blocks. The schema rejects deeper documents.
  • accepts narrows what the nested editor offers to the listed palette ids, in the host's order. 'md:*' stands for every built-in block, so ['md:*', 'youtube'] is "text and videos". Without accepts, the nested editor offers everything the host does (minus containers and unique blocks).
  • The host's palette still applies: accepts can only narrow it, never add to it.
  • Wrapping blocks into a container from the Turn-into menu, and turning a container into another, is offered only when the container accepts every block going in.
  • blocksSchemaFor(plugins) checks accepts on the server (see On the server).

Unique blocks

unique: true — at most one per document, at the top level (a table of contents, for example). Once the document has one, the plugin leaves the slash and Turn-into menus, a second one pasted in falls back to its markdown form, and nested editors never offer it. The schema does not enforce it.

Markdown form

markdown(props, { inner }) returns the block as markdown, used when blocks are copied in the editor and by toMarkdown. inner is the nested blocks already as markdown ('' without any).

Return '' to leave the block out. Plugins whose output has no meaning as text (an ad slot, the bundled gap) simply have no markdown form. Three helpers keep the output well-formed:

Helper Does
mdText(value) Plain text made safe inside markdown: escapes inline marks and #, joins lines.
mdJoin(...parts) Joins parts as separate blocks (blank line between), leaving out empty and falsy ones.
mdQuote(md) Prefixes every line with > , for a box rendered as a blockquote.

Taking pasted tables

When markdown with a GFM table is pasted into the editor, or imported with fromMarkdown(text, { plugins }), the table goes to the first plugin that has fromTable. It gets the table and returns the new block's props:

interface MarkdownTable {
	rows: string[][]; // the cells as inline markdown, row by row; the first row is the header
	align: ('left' | 'center' | 'right')[]; // per column, from the delimiter row (:--, :-:, --:)
}

fromTable?(table: MarkdownTable): P;

The bundled table has it (fromTable: ({ rows, align }) => ({ rows, heads: ['top'], align })), so a table pasted into an editor that offers it becomes a table block. Without such a plugin the table stays text.

Inline plugins

An inline plugin is an element inside a block's text — a formula, a mention, a variable — that moves and deletes as one, while the stored text stays inline markdown. Give the same list to the editor and the preview (inlinePlugins); nested editors and plugin views (a table's cells) get it through a context (useInlinePlugins()).

interface InlinePlugin<D extends Record<string, string>> {
	type: string; label: string; icon: Icon;
	pattern: RegExp;                 // its markdown form in the text (global, bounded)
	parse(match: string[]): D;       // a match → the data
	markdown(data: D): string;       // the data → its markdown form (parse of it gives the same data)
	render(data: D): string;         // the data → safe HTML (escape what comes from the data)
	fields: PropField[];             // edited in a popup when the element is clicked
	create(text: string): D;         // a new one from the selected or typed text
	typing?: { open: string; close: string }; // typing open…close and a space makes one
}

How it works: inline() looks for the patterns outside code spans and escaped characters, and puts render's HTML in a span that carries the markdown form (data-md); the editor's span is not editable text. Converting back to markdown takes the data-md, so a document saves the same even where the plugin is missing (its markdown form then shows as text). The toolbar gets a button per inline plugin, a click on an element opens its fields, and typing works like **bold**. inlineMath in @atom-forge/brickee/math is the bundled example.

Taking files

When files are pasted into the editor (a copied image, a screenshot) or dropped on it from outside the page, the first plugin the editor offers that has fromFiles and returns props gets one block of its own:

fromFiles?(files: File[]): P | null | Promise<P | null>;

Return null to leave the files to the next plugin. Uploading and storing them is the plugin's business, so it may return a promise — upload, then return the props with the stored URL or id. A pasted file goes after the block with the caret (or in place of an empty one); a dropped one where the drop line shows.

fromFiles: async (files) => {
	const file = files.find((f) => f.type.startsWith('image/'));
	if (!file) return null;
	const url = await uploadToMyStorage(file); // your app's upload
	return { url, alt: file.name };
},

The kit

Export Kind Use
Frame component The editor look of a container: fields on top, nested editor below.
Empty component The placeholder of a block whose props are not set yet.
safeColor(value, fallback) function A #hex colour (3–8 digits), or the fallback.
lines(text) function Trimmed, non-empty lines: a field's parse for "one per line" lists.
mdText, mdJoin, mdQuote functions Markdown forms (above).
useText function Translates the plugin's own UI text.
Preview component Renders a container's nested blocks (with nested).

Prerequisites (2)

  • stored-block
  • palette

Teaches (1)

  • block-plugin