@atom-forge/brickee 0.0.0-stage → 0.0.2

package/dist/plugins/YouTubePreview.svelte

@@ -0,0 +1,76 @@
+<svelte:options css="injected" />
+
+<script lang="ts">
+	import { useText } from '../i18n';
+	import type { PluginPreviewProps } from '../types';
+	import type { YouTubeProps } from './YouTube.svelte';
+
+	let { props }: PluginPreviewProps<YouTubeProps> = $props();
+	const tr = useText();
+	const id = $derived(/^[\w-]{11}$/.test(props.id ?? '') ? props.id : '');
+	// The player loads only on click (no YouTube request before that but the thumbnail).
+	let playing = $state(false);
+</script>
+
+{#if id}
+	<figure class="yt">
+		{#if playing}
+			<iframe
+				src="https://www.youtube-nocookie.com/embed/{id}?autoplay=1"
+				title={props.title || tr('YouTube video')}
+				allow="autoplay; encrypted-media; picture-in-picture"
+				allowfullscreen
+			></iframe>
+		{:else}
+			<button type="button" onclick={() => (playing = true)} aria-label={tr('Play {title}', { title: props.title || tr('video') })}>
+				<img src="https://i.ytimg.com/vi/{id}/hqdefault.jpg" alt="" />
+				<span class="play" aria-hidden="true">▶</span>
+			</button>
+		{/if}
+		{#if props.title}<figcaption>{props.title}</figcaption>{/if}
+	</figure>
+{/if}
+
+<style>
+	.yt {
+		margin: 0 0 1em;
+	}
+	iframe,
+	button {
+		display: block;
+		width: 100%;
+		aspect-ratio: 16 / 9;
+		border: 0;
+		border-radius: 8px;
+	}
+	button {
+		position: relative;
+		padding: 0;
+		overflow: hidden;
+		background: #000;
+		cursor: pointer;
+	}
+	img {
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+	}
+	.play {
+		position: absolute;
+		inset: 0;
+		margin: auto;
+		width: 64px;
+		height: 44px;
+		display: grid;
+		place-items: center;
+		border-radius: 12px;
+		background: #dc2626;
+		color: #fff;
+		font-size: 20px;
+	}
+	figcaption {
+		margin-top: 0.4em;
+		color: color-mix(in srgb, currentColor 65%, transparent);
+		font: 13px/1.4 system-ui, sans-serif;
+	}
+</style>

package/dist/plugins/YouTubePreview.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { PluginPreviewProps } from '../types';
+import type { YouTubeProps } from './YouTube.svelte';
+declare const YouTubePreview: import("svelte").Component<PluginPreviewProps<YouTubeProps>, {}, "">;
+type YouTubePreview = ReturnType<typeof YouTubePreview>;
+export default YouTubePreview;

package/dist/plugins/index.d.ts

@@ -0,0 +1,20 @@
+import type { BlockPlugin } from '../types';
+import { type GapProps } from './Gap.svelte';
+import { type MapProps } from './Map.svelte';
+import { type TableProps } from './Table.svelte';
+import { type YouTubeProps } from './YouTube.svelte';
+/** A YouTube video, loaded on click. */
+export declare const youtube: BlockPlugin<YouTubeProps>;
+/** Rows and columns of inline-formatted cells (price lists, fines…); edited in place, rows and columns dragged by their
+ * grips. The first row can be a header, the last a footer (sums). */
+export declare const table: BlockPlugin<TableProps>;
+/** A Google Maps embed of a place or an address. */
+export declare const map: BlockPlugin<MapProps>;
+/** Empty space between blocks, some lines of text high; only its height can be set. */
+export declare const gap: BlockPlugin<GapProps>;
+export declare const PLUGINS: BlockPlugin[];
+export { youtubeId } from './util';
+export type { GapProps, MapProps, TableProps, YouTubeProps };
+export { square, tableHeads, rowHead, HEADS, type Head } from './Table.svelte';
+export { GAP_LINES, GAP_MAX, gapLines } from './Gap.svelte';
+export { mapSrc } from './Map.svelte';

package/dist/plugins/index.js

@@ -0,0 +1,105 @@
+// The bundled plugins: plugins like any other (written with the kit), an app picks the ones it wants. Only general
+// blocks live here (video, map, table, gap); anything an app gives its own meaning to belongs in the app.
+import { MapPin, PanelBottom, PanelTop, SquarePlay, Table, UnfoldVertical } from '@lucide/svelte';
+import { mdText } from '../kit/util';
+import { youtubeId } from './util';
+import Gap, { GAP_LINES } from './Gap.svelte';
+import GapPreview from './GapPreview.svelte';
+import MapView, {} from './Map.svelte';
+import MapPreview from './MapPreview.svelte';
+import TableView, { tableHeads } from './Table.svelte';
+import TablePreview from './TablePreview.svelte';
+import YouTube, {} from './YouTube.svelte';
+import YouTubePreview from './YouTubePreview.svelte';
+// Markdown forms (BlockPlugin.markdown).
+const mdLink = (text, url) => `[${mdText(text) || url}](${url})`;
+/** One table row in GFM; the cells are inline markdown already, only the pipes are escaped. */
+const mdRow = (cells) => `| ${cells.map((c) => (c ?? '').replace(/\|/g, '\\|').replace(/\n/g, '<br>')).join(' | ')} |`;
+/** A YouTube video, loaded on click. */
+export const youtube = {
+    type: 'youtube',
+    label: 'YouTube',
+    hint: 'Video from a link',
+    keys: 'youtube video embed',
+    icon: SquarePlay,
+    props: () => ({ id: '', title: '' }),
+    fields: [
+        { key: 'id', label: 'Video link or id', kind: 'text', placeholder: 'https://youtu.be/…', parse: youtubeId },
+        { key: 'title', label: 'Title', kind: 'text' }
+    ],
+    tag: () => 'youtube',
+    content: 'none',
+    markdown: (p) => (p.id ? mdLink(p.title, `https://www.youtube.com/watch?v=${p.id}`) : ''),
+    view: YouTube,
+    preview: YouTubePreview
+};
+/** Rows and columns of inline-formatted cells (price lists, fines…); edited in place, rows and columns dragged by their
+ * grips. The first row can be a header, the last a footer (sums). */
+export const table = {
+    type: 'table',
+    label: 'Table',
+    hint: 'Rows and columns',
+    keys: 'table grid rows columns price list',
+    icon: Table,
+    props: () => ({ rows: [['', ''], ['', '']], heads: ['top'] }),
+    fields: [
+        {
+            key: 'heads',
+            label: 'Header and footer',
+            kind: 'toggles',
+            options: [
+                { value: 'top', label: 'Header row', icon: PanelTop },
+                { value: 'bottom', label: 'Footer row (e.g. sums)', icon: PanelBottom }
+            ]
+        }
+    ],
+    tag: (p) => `table · ${p.rows?.length ?? 0}×${p.rows?.[0]?.length ?? 0}`,
+    content: 'none',
+    markdown: (p) => {
+        const rows = p.rows ?? [];
+        if (!rows.length)
+            return '';
+        const body = tableHeads(p).has('top') ? rows.slice(1) : rows;
+        const head = tableHeads(p).has('top') ? rows[0] : rows[0].map(() => '');
+        return [mdRow(head), mdRow(head.map(() => '---')), ...body.map(mdRow)].join('\n');
+    },
+    view: TableView,
+    preview: TablePreview
+};
+/** A Google Maps embed of a place or an address. */
+export const map = {
+    type: 'map',
+    label: 'Map',
+    hint: 'Google Maps for a place',
+    keys: 'map google location address place',
+    icon: MapPin,
+    props: () => ({ q: '', zoom: '15' }),
+    fields: [
+        { key: 'q', label: 'Place or address', kind: 'text', placeholder: 'e.g. Pécs, Széchenyi tér' },
+        { key: 'zoom', label: 'Zoom', kind: 'slider', options: Array.from({ length: 20 }, (_, i) => ({ value: String(i + 1), label: String(i + 1) })) }
+    ],
+    tag: (p) => (p.q ? `map · ${p.q}` : 'map'),
+    content: 'none',
+    markdown: (p) => (p.q ? mdLink(p.q, `https://www.google.com/maps/search/?api=1&query=${encodeURIComponent(String(p.q))}`) : ''),
+    view: MapView,
+    preview: MapPreview
+};
+/** Empty space between blocks, some lines of text high; only its height can be set. */
+export const gap = {
+    type: 'gap',
+    label: 'Gap',
+    hint: 'Empty space',
+    keys: 'gap space spacer whitespace',
+    icon: UnfoldVertical,
+    props: () => ({ lines: '1' }),
+    fields: [{ key: 'lines', label: 'Height', kind: 'slider', options: GAP_LINES }],
+    tag: (p) => `gap · ${p.lines ?? '1'}`,
+    content: 'none',
+    view: Gap,
+    preview: GapPreview
+};
+export const PLUGINS = [table, youtube, map, gap];
+export { youtubeId } from './util';
+export { square, tableHeads, rowHead, HEADS } from './Table.svelte';
+export { GAP_LINES, GAP_MAX, gapLines } from './Gap.svelte';
+export { mapSrc } from './Map.svelte';

package/dist/plugins/util.d.ts

@@ -0,0 +1,3 @@
+export { lines, safeColor } from '../kit/util';
+/** A YouTube video id from an id or any YouTube link. */
+export declare function youtubeId(s: string): string;

package/dist/plugins/util.js

@@ -0,0 +1,8 @@
+// Helpers of the bundled plugins (the general ones are in kit/util.ts).
+export { lines, safeColor } from '../kit/util';
+/** A YouTube video id from an id or any YouTube link. */
+export function youtubeId(s) {
+    const t = s.trim();
+    const m = /(?:v=|youtu\.be\/|embed\/|shorts\/)([\w-]{11})/.exec(t);
+    return m ? m[1] : t.replace(/[^\w-]/g, '').slice(0, 11);
+}

package/dist/schema.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { type StoredBlock } from './model';
+export declare const blocksSchema: z.ZodArray<z.ZodType<StoredBlock, unknown, z.core.$ZodTypeInternals<StoredBlock, unknown>>>;
+/**
+ * The stored blocks, also checked against the containers' `accepts` (pass the editor's plugins, or just their
+ * `type` and `accepts`): a container may hold only the blocks it takes.
+ */
+export declare const blocksSchemaFor: (plugins: readonly {
+    type: string;
+    accepts?: readonly string[];
+}[]) => z.ZodArray<z.ZodType<StoredBlock, unknown, z.core.$ZodTypeInternals<StoredBlock, unknown>>>;

package/dist/schema.js

@@ -0,0 +1,25 @@
+// Server-side validation of a stored document (zod). Only the shape is checked: the renderers escape every text,
+// keep links to http(s)/mailto/tel/site paths, take colours only as #hex.
+import { z } from 'zod';
+import { acceptsId, MAX_DEPTH, MAX_INDENT } from './model';
+const block = z.lazy(() => z.strictObject({
+    type: z.string().regex(/^[a-z][a-z0-9:-]{0,39}$/),
+    indent: z.number().int().min(0).max(MAX_INDENT),
+    text: z.string().max(100_000).optional(),
+    props: z.record(z.string().max(60), z.json()).optional(),
+    blocks: z.array(block).max(500).optional()
+}));
+const depth = (blocks) => Math.max(0, ...blocks.map((b) => (b.blocks ? 1 + depth(b.blocks) : 0)));
+export const blocksSchema = z
+    .array(block)
+    .max(2000)
+    .refine((blocks) => depth(blocks) <= MAX_DEPTH - 1, 'Blocks may hold blocks one level deep only.')
+    .refine((blocks) => JSON.stringify(blocks).length <= 1_000_000, 'The content is too large.');
+/**
+ * The stored blocks, also checked against the containers' `accepts` (pass the editor's plugins, or just their
+ * `type` and `accepts`): a container may hold only the blocks it takes.
+ */
+export const blocksSchemaFor = (plugins) => {
+    const accepts = new Map(plugins.map((p) => [p.type, p.accepts]));
+    return blocksSchema.refine((blocks) => blocks.every((b) => !b.blocks || b.blocks.every((inner) => acceptsId(accepts.get(b.type), inner.type))), 'A block holds a block it does not take.');
+};

package/dist/scroll.d.ts

@@ -0,0 +1,18 @@
+import type { Action } from 'svelte/action';
+/** How far a box is scrolled, 0…1 (0 when it does not scroll). */
+export declare const scrollFraction: (box: HTMLElement) => number;
+/** Scrolls a box to a fraction (0…1) of its scroll range. */
+export declare const setScrollFraction: (box: HTMLElement, f: number) => void;
+export interface ScrollSync {
+    /** The box the reader scrolls (e.g. the editor's). */
+    source: Action<HTMLElement>;
+    /**
+     * The box that follows it (e.g. the preview's); its content changing size keeps it in step too. Its parameter turns
+     * it on and off (default on), for a host that switches between two boxes.
+     */
+    target: Action<HTMLElement, boolean | undefined>;
+    /** Puts the target in step now (e.g. after its width changed). */
+    align(): void;
+}
+/** Keeps a target box scrolled to the same fraction as the source box. One way: scrolling the target moves nothing else. */
+export declare function scrollSync(): ScrollSync;

package/dist/scroll.js

@@ -0,0 +1,57 @@
+/** How far a box is scrolled, 0…1 (0 when it does not scroll). */
+export const scrollFraction = (box) => {
+    const max = box.scrollHeight - box.clientHeight;
+    return max > 0 ? box.scrollTop / max : 0;
+};
+/** Scrolls a box to a fraction (0…1) of its scroll range. */
+export const setScrollFraction = (box, f) => {
+    box.scrollTop = Math.min(1, Math.max(0, f)) * (box.scrollHeight - box.clientHeight);
+};
+/** Keeps a target box scrolled to the same fraction as the source box. One way: scrolling the target moves nothing else. */
+export function scrollSync() {
+    let source = null;
+    let target = null;
+    let frame = 0;
+    const align = () => {
+        frame = 0;
+        if (source && target)
+            setScrollFraction(target, scrollFraction(source));
+    };
+    const later = () => (frame ||= requestAnimationFrame(align));
+    return {
+        source(node) {
+            source = node;
+            node.addEventListener('scroll', later, { passive: true });
+            return {
+                destroy() {
+                    node.removeEventListener('scroll', later);
+                    if (source === node)
+                        source = null;
+                }
+            };
+        },
+        target(node, on = true) {
+            const watch = new ResizeObserver(later);
+            const use = (yes = true) => {
+                watch.disconnect();
+                if (!yes)
+                    return void (target === node && (target = null));
+                target = node;
+                for (const child of node.children)
+                    watch.observe(child);
+                watch.observe(node);
+                later();
+            };
+            use(on);
+            return {
+                update: use,
+                destroy() {
+                    watch.disconnect();
+                    if (target === node)
+                        target = null;
+                }
+            };
+        },
+        align
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+import type { Component } from 'svelte';
+import type { StoredBlock } from './model';
+import type { Icon } from './palette';
+export type BlockType = 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'ul' | 'ol' | 'todo' | 'quote' | 'code' | 'hr' | 'plugin';
+export type Props = Record<string, unknown>;
+export interface Block {
+    /** Editor-only identity (rendering, focus, selection, drag); never stored. */
+    id: string;
+    type: BlockType;
+    /** Inline HTML (b, i, u, strike, code, a, br). Always sanitized by construction, never raw paste. */
+    html: string;
+    indent: number;
+    checked?: boolean;
+    /** Properties edited in the block's fields: a code block's `lang`, or a plugin's own. */
+    props?: Props;
+    /** Plugin blocks only: the plugin's stored type and its nested document. */
+    plugin?: string;
+    blocks?: StoredBlock[];
+}
+export { isMd, MD, type StoredBlock } from './model';
+/**
+ * What a block holds: nothing (divider), inline-formatted text (paragraph, heading, list item…), plain text
+ * without formatting (code), or a nested list of blocks (box).
+ */
+export type Content = 'none' | 'text' | 'plain' | 'blocks';
+/** Content of the built-in block types. */
+export declare const BUILT_IN_CONTENT: Record<Exclude<BlockType, 'plugin'>, Content>;
+/** One editable property, a field on the top of the block. */
+export interface PropField {
+    key: string;
+    label: string;
+    /**
+     * 'toggles' is a row of icon buttons, each switching one of `options` on or off; stored as the list of the ones on
+     * (in `options` order).
+     * 'slider' steps through `options` in their order (e.g. heights), or, with `min` and `max`, sets a number freely.
+     */
+    kind: 'text' | 'textarea' | 'color' | 'select' | 'slider' | 'toggles';
+    placeholder?: string;
+    /** A number slider: its range, step (default 1) and unit shown after the value. */
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+    /**
+     * The label of the unset state, where the key is removed: a number slider's position left of `min` (e.g. 'Original'),
+     * or an optional colour ('None'; `placeholder` is the colour a click on it starts from).
+     */
+    none?: string;
+    /**
+     * A slider with a value per view (e.g. the page's widths); the host sets the current view with `provideView`, a badge
+     * shows which one is edited. The first view is
+     * the base; each other view, while it has no value of its own, takes the one before it. Stored as the base value
+     * alone, or, with own values for other views, as an object by view key.
+     */
+    views?: {
+        key: string;
+        label: string;
+    }[];
+    /** For 'select', 'slider' and 'toggles' (where `icon` is the button and `label` its tooltip). */
+    options?: {
+        value: string;
+        label: string;
+        icon?: Icon;
+    }[];
+    /** The field's text from the stored value; default: the value as a string. */
+    format?: (value: unknown) => string;
+    /** The stored value from the field's text (e.g. a list from lines, an id from a URL); default: the text. '' removes the key. */
+    parse?: (text: string) => unknown;
+}
+/** What a plugin component receives. `props` and `blocks` are bindable. */
+export interface PluginViewProps<P extends Props = Props> {
+    props: P;
+    blocks: StoredBlock[];
+    readonly: boolean;
+    /** The host editor's palette and plugins, for a nested editor. */
+    palette: string[];
+    plugins: BlockPlugin[];
+}
+/** What a plugin's preview receives: the block as stored, and the plugins to render its nested blocks with. */
+export interface PluginPreviewProps<P extends Props = Props> {
+    props: P;
+    blocks: StoredBlock[];
+    plugins: BlockPlugin[];
+}
+/** A custom block for the slash menu. */
+/** What a plugin's `markdown` gets beside its props. */
+export interface MarkdownContext {
+    /** The nested blocks as markdown ('' when it has none). */
+    inner: string;
+}
+export interface BlockPlugin<P extends Props = Props> {
+    /** Stored `type`; must not start with 'md:'. */
+    type: string;
+    label: string;
+    hint: string;
+    keys: string;
+    icon: Icon;
+    /** Properties of a new block. */
+    props: () => P;
+    /** Its fields, on the top of the block. */
+    fields?: PropField[];
+    /** The mini label on the top of the block (before its fields). */
+    tag(props: P): string;
+    /** What the block holds; decides what "Turn into" can offer. 'blocks' gets a nested document. */
+    content: Content;
+    /** In the editor. */
+    view: Component<PluginViewProps<any>, {}, 'props' | 'blocks'>;
+    /**
+     * On the site: the block as it will be rendered by `<Preview>`. Optional: an app with its own renderer leaves it out,
+     * and `<Preview>` then skips the block.
+     */
+    preview?: Component<PluginPreviewProps<any>>;
+    /**
+     * For a plugin with nested blocks: the blocks it takes, as palette ids ('md:p', 'youtube'…); 'md:*' stands for every
+     * built-in block. Its nested editor offers the host's palette narrowed to these. Default: everything the host has.
+     */
+    accepts?: string[];
+    /**
+     * Its markdown form (copying as text, export); `inner` holds its nested blocks already as markdown. Without it, or
+     * when it gives '', the block is left out of the markdown.
+     */
+    markdown?(props: P, ctx: MarkdownContext): string;
+    /** At most one per document, and only at the top level (e.g. the supporters-only divider). */
+    unique?: boolean;
+    /** The blocks after it are gated (e.g. for supporters only): the preview marks them. Implies nothing about `unique`. */
+    gate?: boolean;
+}
+export { MAX_INDENT } from './model';
+export declare const uid: () => string;
+export declare const newBlock: (type?: BlockType, html?: string, extra?: Partial<Block>) => Block;
+/** Ordinal for every `ol` block, restarting after interruptions and per indent level. */
+export declare function numbering(blocks: Block[]): Record<string, number>;

package/dist/types.js

@@ -0,0 +1,43 @@
+// The stored form is shared with the server (validation, search text, the HTML converter).
+export { isMd, MD } from './model';
+/** Content of the built-in block types. */
+export const BUILT_IN_CONTENT = {
+    p: 'text',
+    h1: 'text',
+    h2: 'text',
+    h3: 'text',
+    h4: 'text',
+    h5: 'text',
+    h6: 'text',
+    ul: 'text',
+    ol: 'text',
+    todo: 'text',
+    quote: 'text',
+    code: 'plain',
+    hr: 'none'
+};
+export { MAX_INDENT } from './model';
+export const uid = () => Math.random().toString(36).slice(2, 10);
+export const newBlock = (type = 'p', html = '', extra = {}) => ({
+    id: uid(),
+    type,
+    html,
+    indent: 0,
+    ...extra
+});
+/** Ordinal for every `ol` block, restarting after interruptions and per indent level. */
+export function numbering(blocks) {
+    const out = {};
+    const counters = [];
+    for (const b of blocks) {
+        if (b.type === 'ol') {
+            counters.length = b.indent + 1;
+            counters[b.indent] = (counters[b.indent] ?? 0) + 1;
+            out[b.id] = counters[b.indent];
+        }
+        else {
+            counters.length = Math.min(counters.length, b.indent);
+        }
+    }
+    return out;
+}

package/dist/view.d.ts

@@ -0,0 +1,6 @@
+type Get = () => string | undefined;
+/** Call in a component's init (around the editor); the function returns the current view's key. */
+export declare function provideView(get: Get): void;
+/** Call in a component's init; the returned function reads the current view's key (undefined: none given). */
+export declare const useView: () => Get;
+export {};

package/dist/view.js

@@ -0,0 +1,11 @@
+// The view the per-view fields edit (see PropField.views). Which views there are and which one is shown is the
+// host's business (e.g. the width its preview shows): it gives the current one through the context. Without it, a
+// per-view field simply edits its base value.
+import { getContext, setContext } from 'svelte';
+const KEY = 'block-editor:view';
+/** Call in a component's init (around the editor); the function returns the current view's key. */
+export function provideView(get) {
+    setContext(KEY, get);
+}
+/** Call in a component's init; the returned function reads the current view's key (undefined: none given). */
+export const useView = () => getContext(KEY) ?? (() => undefined);

package/docs/en/bundled-plugins.md

@@ -0,0 +1,99 @@
+# Bundled plugins
+
+[← Previous](documents-and-markdown.md) · [Contents](index.md) · [Next →](writing-plugins.md)
+
+`@atom-forge/brickee/plugins` holds four general-purpose plugins. They are written only with what the core exports to any plugin author, so they double as examples, and you take only the ones you need.
+
+```ts
+import { PLUGINS } from '@atom-forge/brickee/plugins'; // all four
+import { table, youtube } from '@atom-forge/brickee/plugins'; // or some
+```
+
+## The plugins
+
+| Export | `type` | Fields | Markdown form | What it is |
+|---|---|---|---|---|
+| `table` | `table` | header and footer (the cells are edited in place) | a GFM table | Rows and columns of inline-formatted cells; click a cell for its row and column tools (insert, delete, align), drag rows and columns by their grips. The first row can be a header, the last a footer. |
+| `youtube` | `youtube` | video link or id, title | a link | A YouTube video, loaded on click; any YouTube link is reduced to the video id. |
+| `map` | `map` | place or address, zoom slider | a link | A Google Maps embed of a place or an address. |
+| `gap` | `gap` | height slider | none | Empty space between blocks, 1–8 lines high. |
+
+None of them holds nested blocks. Image blocks, boxes and other containers are application-specific in look and behaviour, so the package leaves them to you: [Writing plugins](writing-plugins.md) shows a container, and [Host contexts](host-contexts.md) an image block.
+
+Besides the plugins, the entry point exports their props types (`TableProps`, `YouTubeProps`, `MapProps`, `GapProps`) and the helpers their previews use, which are useful when you write your own previews: `youtubeId` (a video id from any YouTube link), `mapSrc` (the embed address of a place), `gapLines`, `GAP_LINES` and `GAP_MAX`, and `tableHeads`, `rowHead`, `HEADS` and `square` for tables.
+
+## Overriding a preview
+
+A plugin is a plain object, so adapting one is a spread. The most common change is the preview: the editor view stays the package's, and the site renders the block with your own component — so the editor's preview and the published page are exactly the same.
+
+```ts
+// blocks.ts
+import type { BlockPlugin } from '@atom-forge/brickee';
+import { gap, table, youtube } from '@atom-forge/brickee/plugins';
+import SiteYouTube from './SiteYouTube.svelte';
+
+const withPreview = (plugin: BlockPlugin, preview: BlockPlugin['preview']): BlockPlugin => ({ ...plugin, preview });
+
+export const plugins: BlockPlugin[] = [withPreview(youtube, SiteYouTube), table, gap];
+```
+
+A replacement preview receives the same props as the original (`PluginPreviewProps`: `props`, `blocks`, `plugins`). This one shows a thumbnail that links to the video instead of embedding a player:
+
+```svelte
+<!-- SiteYouTube.svelte -->
+<script lang="ts">
+	import type { PluginPreviewProps } from '@atom-forge/brickee';
+	import { youtubeId, type YouTubeProps } from '@atom-forge/brickee/plugins';
+
+	let { props }: PluginPreviewProps<YouTubeProps> = $props();
+	// props are user input: keep only a well-formed video id
+	const id = $derived(youtubeId(String(props.id ?? '')));
+</script>
+
+{#if id.length === 11}
+	<a class="video" href="https://www.youtube.com/watch?v={id}" target="_blank" rel="noopener noreferrer">
+		<img src="https://img.youtube.com/vi/{id}/hqdefault.jpg" alt={props.title || 'YouTube video'} />
+	</a>
+{/if}
+```
+
+## Adding fields
+
+New settings are new fields and new initial props. The plugin's view does not need to change: the editor draws every field on the top of the block, and your preview reads the new props.
+
+```ts
+import type { BlockPlugin } from '@atom-forge/brickee';
+import { map } from '@atom-forge/brickee/plugins';
+import SiteMap from './SiteMap.svelte';
+
+export const siteMap: BlockPlugin = {
+	...map,
+	props: () => ({ ...map.props(), caption: '' }),
+	fields: [...(map.fields ?? []), { key: 'caption', label: 'Caption', kind: 'text' }],
+	preview: SiteMap
+};
+```
+
+```svelte
+<!-- SiteMap.svelte -->
+<script lang="ts">
+	import type { PluginPreviewProps } from '@atom-forge/brickee';
+	import { mapSrc, type MapProps } from '@atom-forge/brickee/plugins';
+
+	let { props }: PluginPreviewProps<MapProps> = $props();
+	const src = $derived(mapSrc(props));
+</script>
+
+{#if src}
+	<figure>
+		<iframe title={props.q} {src} loading="lazy"></iframe>
+		{#if props.caption}<figcaption>{props.caption}</figcaption>{/if}
+	</figure>
+{/if}
+```
+
+Add the new field labels to your `messages` if the editor is not in English (see [UI text](host-contexts.md#ui-text)). To make an existing slider per-view, map over `fields` and add `views` to it (see [Per-view values](host-contexts.md#per-view-values)).
+
+> **Keep the type**
+>
+> Keep the plugin's `type` when you override it: stored documents refer to blocks by type. A new `type` makes a new block, and existing documents will not find their blocks.