@atom-forge/brickee 0.0.0-stage → 0.0.2

package/docs/en/writing-plugins.md

@@ -0,0 +1,405 @@
+# Writing plugins
+
+[← Previous](bundled-plugins.md) · [Contents](index.md) · [Next →](host-contexts.md)
+
+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). |
+| `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. |
+| `gate` | `boolean` | The blocks after it are gated; the preview marks them. |
+
+`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.
+
+```ts
+// 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 : '';
+};
+```
+
+```svelte
+<!-- 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>
+```
+
+```svelte
+<!-- 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}
+```
+
+```ts
+// 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:
+
+```svelte
+<Editor bind:value plugins={[...PLUGINS, button]} />
+<Preview blocks={value} plugins={[...PLUGINS, button]} />
+```
+
+> **Props come from users**
+>
+> A plugin's props are whatever was stored — typed by an editor, pasted, or sent to your API by anyone who can save a document. The schema only checks the shape. Every preview must treat props as untrusted: take colours through `safeColor`, check links and image addresses, and clamp numbers. Svelte escapes text in `{...}`; never put a prop into `{@html}`.
+
+## 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. |
+| `views` | Per-view values for a `slider` (see [Per-view values](host-contexts.md#per-view-values)). |
+| `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.
+
+## 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. Messages and the view are available through the contexts (`useText`, `useView`; see [Host contexts](host-contexts.md)); images are the plugin's own business (see [Images](#images)).
+
+## 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`.
+
+```svelte
+<!-- 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…')} />
+```
+
+```svelte
+<!-- 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>
+```
+
+```ts
+// 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](server-side.md)).
+
+## Unique and gate blocks
+
+- **`unique: true`** — at most one per document, at the top level. Once the document has one, the plugin leaves the slash and Turn-into menus; nested editors never offer it.
+- **`gate: true`** — the blocks after the first top-level gate block are gated. The `Preview` renders them inside a section marked "For supporters only" with a dashed line; `markGated={false}` turns the marking off. Nested previews never split.
+
+A supporters-only divider is a typical example of both: one per document, with the gated content behind it.
+
+> **Gating only marks**
+>
+> `gate` does not hide anything: the preview still renders every block, and the stored document still holds them. Deciding who may read the gated part — and leaving it out of the page for everyone else — is the host's job, on the server (see [Gated content](server-side.md#gated-content)). `unique` is not enforced by the schema either.
+
+## 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. |
+
+## Images
+
+The editor has no notion of images: no image field, no picker, no list of media. Whether a block stores an image's URL or the id of an image in the app's own media library, how the user picks it, and how the stored value becomes an address are the application's decisions, so an image block is an ordinary plugin of the app.
+
+A minimal `photo` plugin stores the image's address, typed into a text field, with alt text and a height slider:
+
+```svelte
+<!-- PhotoView.svelte -->
+<script lang="ts" module>
+	export interface PhotoProps extends Record<string, unknown> {
+		/** The image's address. */
+		url: string;
+		alt: string;
+		/** The height in % of the width (20–150), or unset for the image's own shape. */
+		ratio?: unknown;
+	}
+
+	/** The stored address if it is http(s) or site-relative, else ''. */
+	export const imageSrc = (u: unknown) => {
+		const s = String(u ?? '').trim();
+		return /^(https?:|\/(?!\/))/.test(s) ? s : '';
+	};
+
+	/** A CSS aspect-ratio from a stored height, or undefined. */
+	export const aspect = (v: unknown) => {
+		const n = Number(v);
+		return n >= 20 && n <= 150 ? `100 / ${n}` : undefined;
+	};
+</script>
+
+<script lang="ts">
+	import { ImageIcon } from '@lucide/svelte';
+	import { Empty, type PluginViewProps } from '@atom-forge/brickee';
+
+	let { props = $bindable(), blocks = $bindable() }: PluginViewProps<PhotoProps> = $props();
+	const src = $derived(imageSrc(props.url));
+</script>
+
+{#if src}
+	<img {src} alt={props.alt} style="max-width: 100%" />
+{:else}
+	<Empty icon={ImageIcon} text="Set the image's address above" />
+{/if}
+```
+
+```svelte
+<!-- PhotoPreview.svelte -->
+<script lang="ts">
+	import { baseValue, type PluginPreviewProps } from '@atom-forge/brickee';
+	import { aspect, imageSrc, type PhotoProps } from './PhotoView.svelte';
+
+	let { props }: PluginPreviewProps<PhotoProps> = $props();
+	const src = $derived(imageSrc(props.url));
+</script>
+
+{#if src}
+	<img {src} alt={props.alt ?? ''} style:aspect-ratio={aspect(baseValue(props.ratio))} />
+{/if}
+
+<style>
+	img {
+		width: 100%;
+		object-fit: cover;
+	}
+</style>
+```
+
+```ts
+// photo.ts
+import { ImageIcon } from '@lucide/svelte';
+import { mdText, type BlockPlugin } from '@atom-forge/brickee';
+import PhotoView, { type PhotoProps } from './PhotoView.svelte';
+import PhotoPreview from './PhotoPreview.svelte';
+
+export const photo: BlockPlugin<PhotoProps> = {
+	type: 'photo',
+	label: 'Photo',
+	hint: 'One image',
+	keys: 'photo image picture',
+	icon: ImageIcon,
+	props: () => ({ url: '', alt: '' }),
+	fields: [
+		{ key: 'url', label: 'Image', kind: 'text', placeholder: 'https://…', parse: (s) => s.trim() },
+		{ key: 'alt', label: 'Alt text', kind: 'text', placeholder: 'What the image shows' },
+		{ key: 'ratio', label: 'Height', kind: 'slider', min: 20, max: 150, unit: '%', none: 'Original' }
+	],
+	tag: () => 'photo',
+	content: 'none',
+	markdown: (p) => {
+		const src = imageSrc(p.url);
+		return src ? `![${mdText(p.alt)}](${src})` : '';
+	},
+	view: PhotoView,
+	preview: PhotoPreview
+};
+```
+
+The address is a prop like any other, so it is untrusted: the view and the preview render it only when it is an `http(s)` or site-relative address, as the button checks its link.
+
+Other apps choose differently, all within the plugin:
+
+- **A media library.** The block stores the id of an image in the app's library instead of a URL. The view, the preview and `markdown` turn the id into an address with the app's own lookup: a module of the app, or the app's own Svelte context provided above the editor and the preview (plugin components are rendered beneath them). `markdown` runs outside components, when blocks are copied and in `toMarkdown`, so it can only use module data.
+- **Picking.** Instead of a text field, the view can show its own picker — a button that opens the app's media dialog or an upload — and write the result into `props`, which is bindable.
+- **Several images.** A gallery stores a list (of URLs or ids) in one prop and edits it in its view the same way.
+
+## 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. |
+| `baseValue(value)` | function | The base value of a per-view prop. |
+| `viewValues(value, keys)` | function | A per-view prop's value for each view. |
+| `mdText`, `mdJoin`, `mdQuote` | functions | Markdown forms (above). |
+| `useText` | function | Translates the plugin's own UI text. |
+| `useView` | function | The view the host is showing. |
+| `Preview` | component | Renders a container's nested blocks (with `nested`). |

package/docs/hu/bundled-plugins.md

@@ -0,0 +1,99 @@
+# Mellékelt pluginok
+
+[← Előző](documents-and-markdown.md) · [Tartalom](index.md) · [Következő →](writing-plugins.md)
+
+Az `@atom-forge/brickee/plugins` négy általános célú plugint tartalmaz. Kizárólag azzal készültek, amit a mag bármely plugin-szerzőnek exportál, így példaként is szolgálnak, és csak azokat veszed át, amelyekre szükséged van.
+
+```ts
+import { PLUGINS } from '@atom-forge/brickee/plugins'; // mind a négy
+import { table, youtube } from '@atom-forge/brickee/plugins'; // vagy néhány
+```
+
+## A pluginok
+
+| Export | `type` | Mezők | Markdown alak | Mi ez |
+|---|---|---|---|---|
+| `table` | `table` | fejléc és lábléc (a cellák helyben szerkeszthetők) | GFM-táblázat | Inline formázott cellák sorai és oszlopai; egy cellába kattintva megjelennek a sora és oszlopa eszközei (beszúrás, törlés, igazítás), a sorokat és az oszlopokat a fogantyújuknál fogva húzhatod. Az első sor lehet fejléc, az utolsó lábléc. |
+| `youtube` | `youtube` | videóhivatkozás vagy -azonosító, cím | hivatkozás | YouTube-videó, kattintásra betöltve; bármely YouTube-hivatkozásból csak a videó azonosítója marad meg. |
+| `map` | `map` | hely vagy cím, nagyításcsúszka | hivatkozás | Egy hely vagy cím beágyazott Google Maps-térképe. |
+| `gap` | `gap` | magasságcsúszka | nincs | Üres hely a blokkok között, 1–8 sor magas. |
+
+Egyikük sem tartalmaz beágyazott blokkokat. A képblokkok, a dobozok és a többi tároló megjelenése és viselkedése alkalmazásonként más, ezért a csomag ezeket rád hagyja: a [Pluginok írása](writing-plugins.md) egy tárolót mutat be, [Az alkalmazás kontextusai](host-contexts.md) pedig egy képblokkot.
+
+A pluginok mellett a belépési pont exportálja a props-típusaikat (`TableProps`, `YouTubeProps`, `MapProps`, `GapProps`) és az előnézeteik által használt segédfüggvényeket, amelyek saját előnézetek írásakor jól jönnek: `youtubeId` (videóazonosító bármely YouTube-hivatkozásból), `mapSrc` (egy hely beágyazási címe), `gapLines`, `GAP_LINES` és `GAP_MAX`, valamint a táblázatokhoz `tableHeads`, `rowHead`, `HEADS` és `square`.
+
+## Előnézet felülírása
+
+A plugin egyszerű objektum, így az átalakítása egy spread. A leggyakoribb változtatás az előnézet: a szerkesztőnézet a csomagé marad, az oldal pedig a saját komponenseddel rendereli a blokkot – így a szerkesztő előnézete és a közzétett oldal pontosan ugyanaz.
+
+```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 helyettesítő előnézet ugyanazokat a propsokat kapja, mint az eredeti (`PluginPreviewProps`: `props`, `blocks`, `plugins`). Ez lejátszó beágyazása helyett egy bélyegképet mutat, amely a videóra hivatkozik:
+
+```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();
+	// a props felhasználói bemenet: csak a jól formált videóazonosítót tartsd meg
+	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}
+```
+
+## Mezők hozzáadása
+
+Az új beállítások új mezőket és új kezdő propsokat jelentenek. A plugin nézetén nem kell változtatni: a szerkesztő minden mezőt kirajzol a blokk tetején, az előnézeted pedig beolvassa az új propsokat.
+
+```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}
+```
+
+Ha a szerkesztő nem angol nyelvű, add hozzá az új mezőcímkéket a `messages`-hez (lásd [Felületi szövegek](host-contexts.md#felületi-szövegek)). Ha egy meglévő csúszkát nézetenkéntivé akarsz tenni, képezd le a `fields` tömböt, és adj hozzá `views`-t (lásd [Nézetenkénti értékek](host-contexts.md#nézetenkénti-értékek)).
+
+> **Tartsd meg a típust**
+>
+> Felülíráskor tartsd meg a plugin `type` értékét: a tárolt dokumentumok típus szerint hivatkoznak a blokkokra. Egy új `type` új blokkot jelent, és a meglévő dokumentumok nem fogják megtalálni a blokkjaikat.

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

@@ -0,0 +1,114 @@
+# Dokumentumok és markdown
+
+[← Előző](editor-and-preview.md) · [Tartalom](index.md) · [Következő →](bundled-plugins.md)
+
+## A tárolt alak
+
+A dokumentum `StoredBlock` objektumok tömbje: egyszerű JSON, amelyet úgy, ahogy van, elmenthetsz egy adatbázis-oszlopba:
+
+```ts
+interface StoredBlock {
+	type: string; // beépített blokkoknál 'md:p', 'md:h2'…; plugin-blokkoknál a plugin típusa
+	indent: number; // 0–6
+	text?: string; // beépített blokkok: inline markdown (md:code esetén nyers szöveg)
+	props?: Record<string, unknown>; // plugin-beállítások; md:todo { checked }, md:code { lang }
+	blocks?: StoredBlock[]; // beágyazott blokkokat tartalmazó pluginok: a belső dokumentumuk
+}
+```
+
+Egy rövid dokumentum egy bekezdéssel, egy listával, egy videóval és egy dobozzal (a [Pluginok írása](writing-plugins.md#tárolók) `note` tárolójával):
+
+```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." }]
+	}
+]
+```
+
+- A beépített típusok `md:` előtagot kapnak (`MD` konstans, `isMd(block)` vizsgálat); minden más plugin-típus.
+- A plugin-blokkok csak a `type`, az `indent`, a `props` és – tárolóknál – a `blocks` mezőt őrzik meg. Hogy a props mit jelent, az a pluginon múlik.
+- A beágyazás egy szint mély: egy dobozon belüli blokk maga már nem tartalmazhat blokkokat (a `MAX_DEPTH` értéke 2).
+- A szerkesztő saját munkaalakja (`Block`, `id`-vel és inline HTML-lel) soha nem kerül tárolásra; a kettő között a `toStored` és a `fromStored` alakít át.
+
+## Beépített blokkok
+
+| Típus | Tárolt szöveg | Props | Markdown |
+|---|---|---|---|
+| `md:p` | inline markdown | — | maga a szöveg |
+| `md:h1` … `md:h6` | inline markdown | — | `#` … `######` |
+| `md:ul` | inline markdown | — | `- item` |
+| `md:ol` | inline markdown | — | `1. item` (sorozatonként és behúzási szintenként számozva) |
+| `md:todo` | inline markdown | `{ checked: boolean }` | `- [x] item` |
+| `md:quote` | inline markdown | — | `> quote` |
+| `md:code` | nyers szöveg | `{ lang?: string }` | kerített blokk a nyelvvel |
+| `md:hr` | — | — | `---` |
+
+Az `indent` egymásba ágyazza a listaelemeket (az egymást követő lista-blokkokból az előnézetben helyesen egymásba ágyazott `ul`/`ol` elemek lesznek), a bekezdéseket és az idézeteket pedig behúzza. A címsorok, a kódblokkok és az elválasztók figyelmen kívül hagyják.
+
+### Inline markdown
+
+A beépített blokkok szövege a markdown egy kicsi, biztonságos részhalmaza:
+
+| Jelölés | Tárolt alak |
+|---|---|
+| félkövér | `**text**` |
+| dőlt | `*text*` |
+| aláhúzott, alsó index, felső index | `<u>text</u>`, `<sub>text</sub>`, `<sup>text</sup>` |
+| áthúzott | `~~text~~` |
+| kód | `` `text` `` |
+| hivatkozás | `[text](url)` – csak a `http:`, `https:`, `mailto:`, `tel:` és a webhelyen belüli `/…` célok lesznek hivatkozások |
+| sortörés | egy újsor karakter |
+
+Az egyszerű szövegben a speciális karakterek visszaperjeles escape-elést kapnak, így soha nem válnak jelöléssé. Az `inline(md)` az inline markdownt HTML-lé alakítja: előbb escape-eli a szöveget, és csak utána teszi hozzá a fenti tageket, így a kimenete biztonságosan megjeleníthető `{@html}`-lel – az előnézet is így tesz.
+
+## Markdown be és ki
+
+A markdown teljes értékű formátum: a vágólap ezt hordozza, és a befogadó alkalmazás importálhatja és exportálhatja.
+
+| Függvény | Miből → mibe | Hol fut |
+|---|---|---|
+| `fromStored(block)` | `StoredBlock` → `Block` | bárhol |
+| `toStored(block)` | `Block` → `StoredBlock` | csak böngészőben |
+| `fromMarkdown(text)` | markdown → `Block[]` | bárhol |
+| `toMarkdown(blocks, { plugins })` | `Block[]` → markdown | csak böngészőben |
+| `inline(md)` | inline markdown → inline HTML | bárhol |
+
+A markdown-függvények a szerkesztő alakján (`Block[]`) dolgoznak, ezért a tárolt dokumentumok a `fromStored` és a `toStored` függvényen mennek át:
+
+```ts
+import { fromMarkdown, fromStored, toMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
+import { PLUGINS } from '@atom-forge/brickee/plugins';
+
+// Tárolt dokumentum -> markdown (csak böngészőben).
+export const exportMarkdown = (doc: StoredBlock[]) => toMarkdown(doc.map(fromStored), { plugins: PLUGINS });
+
+// Markdown -> tárolt dokumentum (csak böngészőben).
+export const importMarkdown = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
+```
+
+> **Csak böngészőben**
+>
+> A `toMarkdown` és a `toStored` a DOM-on keresztül olvassa a szerkesztő inline HTML-jét, ezért szüksége van a `document`-re. A böngészőben hívd őket (eseménykezelőben, effectben), ne szerveroldali renderelés közben. Szerveroldali szöveghez a `blocksToPlainText`-et használd (lásd [A szerveren](server-side.md)).
+
+Amit a `fromMarkdown` beolvas:
+
+- címsorok, felsorolás-, számozott és teendő-elemek, idézetek, kerített kódblokkok a nyelvükkel, elválasztók és a fenti inline jelölések;
+- a sor eleji szóközök behúzásként (szintenként két szóköz vagy egy tabulátor);
+- minden nem üres sor külön blokként – a tördelt sorokat nem vonja össze egy bekezdéssé, és csak beépített blokkokat hoz létre (táblázatot, képet vagy plugin-blokkot nem).
+
+Amit a `toMarkdown` kiír:
+
+- az egymást követő listaelemeket egymást követő sorokba, minden más blokkot üres sorral elválasztva;
+- a listaelemeket és a bekezdéseket szintenként két szóközzel behúzva;
+- a plugin-blokkot a pluginja `markdown(props, { inner })` függvényével, ahol az `inner` a már átalakított beágyazott blokkjai; a markdown alak nélküli plugin, illetve az, amelyik `''`-t ad vissza, kimarad.
+
+Saját pluginod markdown alakjának megírásáról a [Pluginok írása](writing-plugins.md#markdown-alak) fejezet szól.