@atom-forge/brickee 0.0.0-stage → 0.0.1

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` | — (edited in place) | a GFM table | Rows and columns of inline-formatted cells; rows and columns are dragged 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.

package/docs/en/documents-and-markdown.md

@@ -0,0 +1,115 @@
+# Documents and markdown
+
+[← Previous](editor-and-preview.md) · [Contents](index.md) · [Next →](bundled-plugins.md)
+
+## The stored form
+
+A document is an array of `StoredBlock` objects — plain JSON you can save in a database column as it is:
+
+```ts
+interface StoredBlock {
+	type: string; // 'md:p', 'md:h2'… for built-in blocks; the plugin's type for plugin blocks
+	indent: number; // 0–6
+	text?: string; // built-in blocks: inline markdown (raw text for md:code)
+	props?: Record<string, unknown>; // plugin settings; md:todo { checked }, md:code { lang }
+	blocks?: StoredBlock[]; // plugins with nested blocks: their inner document
+}
+```
+
+A short document with a paragraph, a list, a video and a box (the `note` container from [Writing plugins](writing-plugins.md#containers)):
+
+```json
+[
+	{ "type": "md:h2", "indent": 0, "text": "Getting there" },
+	{ "type": "md:p", "indent": 0, "text": "Take the **night train** or see the [timetable](https://example.com/trains)." },
+	{ "type": "md:ul", "indent": 0, "text": "Tickets online" },
+	{ "type": "md:ul", "indent": 1, "text": "Students get *20%* off" },
+	{ "type": "youtube", "indent": 0, "props": { "id": "aqz-KE-bpKQ", "title": "The route by night" } },
+	{
+		"type": "note",
+		"indent": 0,
+		"props": { "title": "Good to know" },
+		"blocks": [{ "type": "md:p", "indent": 0, "text": "Trains are cancelled on public holidays." }]
+	}
+]
+```
+
+- Built-in types carry the `md:` prefix (`MD` constant, `isMd(block)` test); everything else is a plugin type.
+- Plugin blocks keep only `type`, `indent`, `props` and, for containers, `blocks`. What the props mean is up to the plugin.
+- Nested blocks go one level deep: a block inside a box cannot hold blocks itself (`MAX_DEPTH` is 2).
+- The editor's own working form (`Block`, with an `id` and inline HTML) is never stored; `toStored` and `fromStored` convert between the two.
+
+## Built-in blocks
+
+| Type | Stored text | Props | Markdown |
+|---|---|---|---|
+| `md:p` | inline markdown | — | the text |
+| `md:h1` … `md:h6` | inline markdown | — | `#` … `######` |
+| `md:ul` | inline markdown | — | `- item` |
+| `md:ol` | inline markdown | — | `1. item` (numbered per run and indent level) |
+| `md:todo` | inline markdown | `{ checked: boolean }` | `- [x] item` |
+| `md:quote` | inline markdown | — | `> quote` |
+| `md:code` | raw text | `{ lang?: string }` | fenced block with the language |
+| `md:hr` | — | — | `---` |
+
+`indent` nests list items (consecutive list blocks become properly nested `ul`/`ol` elements in the preview) and indents paragraphs and quotes. Headings, code and dividers ignore it.
+
+### Inline markdown
+
+The text of a built-in block is a small, safe subset of markdown:
+
+| Mark | Stored as |
+|---|---|
+| bold | `**text**` |
+| italic | `*text*` |
+| underline, subscript, superscript | `<u>text</u>`, `<sub>text</sub>`, `<sup>text</sup>` |
+| strikethrough | `~~text~~` |
+| code | `` `text` `` |
+| link | `[text](url)` — only `http:`, `https:`, `mailto:`, `tel:` and site-relative `/…` targets become links |
+| line break | a newline |
+
+Special characters in plain text are backslash-escaped, so they never turn into markup. `inline(md)` turns inline markdown into HTML: it escapes the text first and only then adds the tags above, so its output is safe to render with `{@html}` — this is what the preview does.
+
+## Markdown in and out
+
+Markdown is a first-class format: the clipboard carries it, and a host can import and export it.
+
+| Function | From → to | Runs |
+|---|---|---|
+| `fromStored(block)` | `StoredBlock` → `Block` | anywhere |
+| `toStored(block)` | `Block` → `StoredBlock` | browser only |
+| `fromMarkdown(text)` | markdown → `Block[]` | anywhere |
+| `toMarkdown(blocks, { plugins, media })` | `Block[]` → markdown | browser only |
+| `inline(md)` | inline markdown → inline HTML | anywhere |
+
+The markdown functions work on the editor form (`Block[]`), so stored documents go through `fromStored` and `toStored`:
+
+```ts
+import { fromMarkdown, fromStored, toMarkdown, toStored, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+import { PLUGINS } from '@atom-forge/brickee/plugins';
+
+// Stored document -> markdown (browser only).
+export const exportMarkdown = (doc: StoredBlock[], media: MediaItem[]) =>
+	toMarkdown(doc.map(fromStored), { plugins: PLUGINS, media });
+
+// Markdown -> stored document (browser only).
+export const importMarkdown = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
+```
+
+> **Browser only**
+>
+> `toMarkdown` and `toStored` read the editor's inline HTML through the DOM, so they need `document`. Call them in the browser (an event handler, an effect), not during server-side rendering. For server-side text, use `blocksToPlainText` (see [On the server](server-side.md)).
+
+What `fromMarkdown` reads:
+
+- headings, bulleted, numbered and to-do items, quotes, fenced code blocks with their language, dividers, and the inline marks above;
+- leading spaces as indentation (two spaces or one tab per level);
+- every non-empty line as its own block — it does not join wrapped lines into one paragraph, and it creates built-in blocks only (no tables, images or plugin blocks).
+
+What `toMarkdown` writes:
+
+- consecutive list items on consecutive lines, every other block separated by a blank line;
+- list items and paragraphs indented by two spaces per level;
+- a plugin block through its plugin's `markdown(props, { inner, media })`, where `inner` is its nested blocks already converted; a plugin without a markdown form, or one returning `''`, is left out.
+
+Writing a markdown form for your own plugin is covered in [Writing plugins](writing-plugins.md#markdown-form).

package/docs/en/editor-and-preview.md

@@ -0,0 +1,141 @@
+# The editor and the preview
+
+[← Previous](getting-started.md) · [Contents](index.md) · [Next →](documents-and-markdown.md)
+
+## Editor props
+
+| Prop | Type | Default | Meaning |
+|---|---|---|---|
+| `value` | `StoredBlock[]` (bindable) | `[]` | The document. Written back on every change; a document replaced from outside is loaded again. |
+| `plugins` | `BlockPlugin[]` | `[]` | The plugin blocks this editor can show and offer. |
+| `palette` | `string[]` | every built-in block, then every plugin | The block types the slash menu offers, in this order (see below). |
+| `media` | `MediaItem[]` | — | The images blocks can pick from (see [Host contexts](host-contexts.md)). |
+| `messages` | `Messages` | — | UI text in the host's language: English text → translation. |
+| `readonly` | `boolean` | `false` | Shows the document without editing; plugin fields are hidden. |
+| `placeholder` | `string` | `Write something, or press '/' for blocks…` | The hint of an empty block. |
+| `nested` | `boolean` | `false` | Set by plugins with nested blocks for their inner editor; a host never sets it. |
+
+An empty document is shown as one empty paragraph, so the value the editor writes back is never an empty array once it has been mounted: it is at least `[{ type: 'md:p', indent: 0, text: '' }]`. The preview skips empty paragraphs.
+
+## Preview props
+
+| Prop | Type | Default | Meaning |
+|---|---|---|---|
+| `blocks` | `StoredBlock[]` | — | The document to render. |
+| `plugins` | `BlockPlugin[]` | — | The plugins whose previews render the plugin blocks. |
+| `media` | `MediaItem[]` | — | The images the blocks refer to by id. |
+| `messages` | `Messages` | — | UI text in the host's language. |
+| `markGated` | `boolean` | `true` | Marks the blocks after a gate block (see [Unique and gate blocks](writing-plugins.md#unique-and-gate-blocks)). |
+| `nested` | `boolean` | `false` | Set by plugin previews that render their nested blocks. |
+
+The preview renders built-in blocks as plain HTML (`p`, `h1`…`h6`, `ul`/`ol` with nested items, `blockquote`, `pre > code` with a `language-<lang>` class, `hr`) and each plugin block with its plugin's `preview`. A block whose type has no plugin in `plugins`, or whose plugin has no `preview`, is not rendered.
+
+Using `Preview` at all is your choice: the editor does not depend on it. An application with its own renderer can render the stored blocks itself, and its plugins can leave `preview` out.
+
+`media` and `messages` given to the top-level editor or preview are inherited by every nested editor, nested preview and plugin component below it.
+
+## The palette
+
+The `palette` is a list of **palette ids**: `md:p`, `md:h1`…`md:h6`, `md:ul`, `md:ol`, `md:todo`, `md:quote`, `md:code`, `md:hr` for the built-in blocks, and a plugin's `type` for a plugin. It decides:
+
+- which blocks the slash menu and the Turn-into menu offer, and in which order;
+- which markdown shortcuts work (typing `## ` turns a paragraph into a heading only if `md:h2` is in the palette);
+- what pasted markdown may become: a pasted block of a type outside the palette becomes a paragraph, and a divider is dropped.
+
+A plain paragraph (`md:p`) is always allowed as the fallback.
+
+```svelte
+<script lang="ts">
+	import { Editor, type StoredBlock } from '@atom-forge/brickee';
+	import { map, table, youtube } from '@atom-forge/brickee/plugins';
+
+	const plugins = [table, youtube, map];
+	// No h1 (the page title is one) and no code blocks.
+	const palette = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)];
+
+	let value = $state<StoredBlock[]>([]);
+</script>
+
+<Editor bind:value {plugins} {palette} />
+```
+
+`PALETTE_ITEMS` lists the built-in blocks with their labels, hints and icons; `BUILT_IN_IDS` is just their ids in the default order.
+
+> **The palette limits offering, not loading**
+>
+> A document that already holds a block outside the palette still shows it. A plugin block whose plugin is missing from `plugins` is kept as it is and shown as an unknown block that can only be deleted. To reject such documents, validate them on the server (see [On the server](server-side.md)).
+
+## Editing
+
+| Action | How |
+|---|---|
+| Insert a block | `/` opens the slash menu (searchable by label, hint, keywords and their translations); the `+` button adds a block below. |
+| Markdown shortcuts | At the start of a paragraph: `# `…`###### `, `- ` / `* ` / `+ `, `1. `, `[] `, `> `. |
+| Inline formatting | Select text for the toolbar, or `Ctrl/Cmd` + `B` bold, `I` italic, `U` underline, `Shift+X` strikethrough, `E` code, `K` link, `\` remove formatting. Subscript and superscript are on the toolbar. |
+| Indent | `Tab` / `Shift+Tab` (at most 6 levels). |
+| Line break | `Shift+Enter`; in a code block `Enter` breaks the line and `Shift+Enter` or `Ctrl/Cmd+Enter` starts a new block. |
+| Select blocks | Click a block's handle, `Esc` in a block, `Shift+↑/↓` past the edge of a block, or drag a text selection across blocks. `Ctrl/Cmd+A` in an empty block selects every block. |
+| Move blocks | Drag the handle (also into and out of nested editors), or `Ctrl/Cmd+Shift+↑/↓`. |
+| Turn into | Click the handle of a block or a selection for the Turn-into menu. |
+| Copy, cut | Copying selected blocks puts their markdown on the clipboard (plugin blocks through their markdown form). |
+| Paste | Multi-line text is read as markdown and becomes blocks. |
+| Undo, redo | `Ctrl/Cmd+Z`, `Ctrl/Cmd+Shift+Z` or `Ctrl/Cmd+Y`. |
+
+What a block can turn into depends on what it holds (its `content`):
+
+- text blocks turn into each other and keep their formatting; turning text into code keeps only the letters;
+- a block without content (divider, video, map) only replaces empty blocks or other blocks without content;
+- a block with nested blocks (a box) can wrap the selected blocks, if it accepts all of them; **Unwrap** moves a box's blocks out; a box can turn into another box-like type, and the props with the same names carry over.
+
+## Scroll sync
+
+A host that shows the editor and the preview side by side can make the preview follow the editor's scrolling. `scrollSync()` returns two Svelte actions and a function:
+
+```svelte
+<script lang="ts">
+	import { Editor, Preview, scrollSync, type StoredBlock } from '@atom-forge/brickee';
+	import { PLUGINS } from '@atom-forge/brickee/plugins';
+
+	let value = $state<StoredBlock[]>([]);
+	const sync = scrollSync();
+</script>
+
+<div class="split">
+	<div class="pane" use:sync.source>
+		<Editor bind:value plugins={PLUGINS} />
+	</div>
+	<div class="pane" use:sync.target>
+		<Preview blocks={value} plugins={PLUGINS} />
+	</div>
+</div>
+
+<style>
+	.split {
+		display: grid;
+		grid-template-columns: 1fr 1fr;
+		height: 100vh;
+	}
+	.pane {
+		overflow-y: auto;
+	}
+</style>
+```
+
+- `use:sync.source` goes on the editor's scrolling box, `use:sync.target` on the preview's. The target is scrolled to the same fraction (0…1) of its scroll range as the source. The sync is one way: scrolling the preview moves nothing else.
+- It re-syncs once per animation frame when the source scrolls, and when the target box or its children change size. `sync.align()` re-syncs on demand, for example after the preview's width changed.
+- `use:sync.target={on}` takes a boolean (default `true`), for a host that switches the target between two boxes, such as a desktop pane and a phone frame: turn on the visible one.
+- The sync is proportional only: both boxes show roughly the same place, not exactly the same block. This is deliberate — it needs no markup and works with any preview.
+
+`scrollFraction(box)` reads how far a box is scrolled (0…1; 0 when it does not scroll), and `setScrollFraction(box, f)` scrolls it there — for example to keep the place when the preview changes width while it is shown alone:
+
+```ts
+import { scrollFraction, setScrollFraction } from '@atom-forge/brickee';
+import { tick } from 'svelte';
+
+export async function keepPlace(box: HTMLElement, change: () => void) {
+	const f = scrollFraction(box);
+	change(); // e.g. switch the preview width
+	await tick();
+	setScrollFraction(box, f);
+}
+```

package/docs/en/getting-started.md

@@ -0,0 +1,81 @@
+# Getting started
+
+[Contents](index.md) · [Next →](editor-and-preview.md)
+
+## What Brickee is
+
+Brickee is a block editor: a document is a list of blocks, each edited on its own row, reordered by dragging, and turned into another type from its handle. The core blocks are markdown — paragraphs, six heading levels, bulleted, numbered and to-do lists, quotes, code and dividers — so a document without plugins reads and copies as plain markdown.
+
+Everything else is a plugin. A plugin is a plain object (`BlockPlugin`) that names a block type and gives it:
+
+- a **view** — a Svelte component shown in the editor;
+- a **preview** — a Svelte component that renders the block on the site;
+- **fields** — the settings shown on the top of the block (text, colour, select, slider, image…);
+- optionally a **markdown form**, used when the document is copied or exported as markdown.
+
+The package ships four general-purpose plugins — table, YouTube video, map and gap — but they are plugins like any other: nothing in the core depends on them, and you pass only the ones you want. Image blocks, boxes and other site-specific blocks are plugins you write yourself.
+
+## Installation
+
+```sh
+bun add @atom-forge/brickee @atom-forge/ui @lucide/svelte
+```
+
+| Peer dependency | Why |
+|---|---|
+| `svelte` `^5.0.0` | The editor, the preview and the plugins are Svelte 5 components. |
+| `@atom-forge/ui` `>=0.0.37` | The popups (link prompt, image picker) and the form controls of the block fields. |
+| `@lucide/svelte` `>=1.0.0` | The block icons. |
+| `zod` `^4.0.0` (optional) | Only for the server-side schema in `@atom-forge/brickee/schema`. |
+
+## Host setup
+
+The block fields and popups are `@atom-forge/ui` components, so the application must be set up the way `@atom-forge/ui` requires:
+
+- Tailwind CSS 4 with the `@atom-forge/ui` theme CSS imported and its `dist` folder added as a Tailwind `@source`;
+- the application rendered beneath the `@atom-forge/ui` `Root` component, which provides the theme and the overlay contexts.
+
+The top-level `Editor` creates its own popup manager and renders its own popup container; editors nested in plugin blocks share it.
+
+> **Missing theme**
+>
+> Without the `@atom-forge/ui` theme CSS the editor still works, but the block fields, the colour picker, the slider and the popups appear unstyled.
+
+The preview adds only the little styling it needs itself (to-do checkboxes, image widths, floats). The typography of headings, paragraphs and lists comes from the page that shows the preview.
+
+## A first editor
+
+```svelte
+<script lang="ts">
+	import { Editor, Preview, type StoredBlock } from '@atom-forge/brickee';
+	import { PLUGINS } from '@atom-forge/brickee/plugins';
+
+	let value = $state<StoredBlock[]>([]);
+</script>
+
+<Editor bind:value plugins={PLUGINS} />
+
+<article>
+	<Preview blocks={value} plugins={PLUGINS} />
+</article>
+```
+
+- `value` is the document as JSON (`StoredBlock[]`). The editor writes it back on every change; save it as it is.
+- `plugins` lists the plugin blocks the editor can show and offer. Leave it out and you have a plain markdown editor.
+- `Preview` renders the same document with the same plugins, the way the site shows it.
+
+Type `/` in an empty line to open the block menu.
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `@atom-forge/brickee` | `Editor`, `Preview`, the kit (`Frame`, `Empty`, helpers), the stored form, the markdown conversions, the contexts, the palette, the types. |
+| `@atom-forge/brickee/plugins` | The bundled plugins (`table`, `youtube`, `map`, `gap`), `PLUGINS` with all four, and their helpers. |
+| `@atom-forge/brickee/schema` | `blocksSchema` and `blocksSchemaFor` (zod), for server-side validation. |
+| `@atom-forge/brickee/model` | The stored form without Svelte: `StoredBlock`, `MD`, `isMd`, `acceptsId`, `blocksToPlainText`… |
+| `@atom-forge/brickee/locales/hu` | `hu`: the Hungarian UI text. |
+
+> **Only what you import is bundled**
+>
+> The bundled plugins live in their own entry point. An application that imports only `@atom-forge/brickee` gets the markdown editor without any plugin code.