@atom-forge/brickee 0.0.0-stage → 0.0.1

package/docs/en/writing-plugins.md

@@ -0,0 +1,305 @@
+# 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, clamp numbers, and look images up in the media list instead of using stored URLs. 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`, `image` or `images`. |
+| `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. |
+| `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. |
+| `image` | The picked media item's `id`; picking it again removes it. |
+| `images` | An array of ids, in picking order; picking a picked one takes it out. |
+
+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. Media, messages and the view are available through the contexts (`useMedia`, `useText`, `useView`; see [Host contexts](host-contexts.md)).
+
+## 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, media })` returns the block as markdown, used when blocks are copied in the editor and by `toMarkdown`:
+
+- `inner` — the nested blocks already as markdown (`''` without any);
+- `media` — the document's media, to turn an image id into its URL with `findMedia(media, id)?.url`.
+
+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. |
+
+## 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). |
+| `useMedia`, `findMedia` | functions | The document's images (see [Host contexts](host-contexts.md)). |
+| `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` | — (helyben szerkesztve) | GFM-táblázat | Inline formázott cellák sorai és oszlopai; 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,115 @@
+# 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, media })` | `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 MediaItem, 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[], media: MediaItem[]) =>
+	toMarkdown(doc.map(fromStored), { plugins: PLUGINS, media });
+
+// 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, media })` 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.

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

@@ -0,0 +1,141 @@
+# A szerkesztő és az előnézet
+
+[← Előző](getting-started.md) · [Tartalom](index.md) · [Következő →](documents-and-markdown.md)
+
+## Az Editor propjai
+
+| Prop | Típus | Alapérték | Jelentés |
+|---|---|---|---|
+| `value` | `StoredBlock[]` (bindable) | `[]` | A dokumentum. Minden változáskor visszaíródik; a kívülről lecserélt dokumentum újra betöltődik. |
+| `plugins` | `BlockPlugin[]` | `[]` | A pluginblokkok, amelyeket ez a szerkesztő megjeleníthet és felkínálhat. |
+| `palette` | `string[]` | minden beépített blokk, utána minden plugin | A perjeles menü által felkínált blokktípusok, ebben a sorrendben (lásd lent). |
+| `media` | `MediaItem[]` | — | A képek, amelyek közül a blokkok választhatnak (lásd [Az alkalmazás kontextusai](host-contexts.md)). |
+| `messages` | `Messages` | — | Felületi szövegek az alkalmazás nyelvén: angol szöveg → fordítás. |
+| `readonly` | `boolean` | `false` | Szerkesztés nélkül mutatja a dokumentumot; a pluginmezők rejtve vannak. |
+| `placeholder` | `string` | `Write something, or press '/' for blocks…` | Az üres blokk tippszövege. |
+| `nested` | `boolean` | `false` | A beágyazott blokkokat tartalmazó pluginok állítják be a belső szerkesztőjükön; a befogadó alkalmazás soha nem állítja be. |
+
+Az üres dokumentum egyetlen üres bekezdésként jelenik meg, így a szerkesztő által visszaírt érték a csatolás után soha nem üres tömb: legalább `[{ type: 'md:p', indent: 0, text: '' }]`. Az előnézet kihagyja az üres bekezdéseket.
+
+## A Preview propjai
+
+| Prop | Típus | Alapérték | Jelentés |
+|---|---|---|---|
+| `blocks` | `StoredBlock[]` | — | A megjelenítendő dokumentum. |
+| `plugins` | `BlockPlugin[]` | — | A pluginok, amelyek előnézetei a pluginblokkokat renderelik. |
+| `media` | `MediaItem[]` | — | A képek, amelyekre a blokkok azonosítóval hivatkoznak. |
+| `messages` | `Messages` | — | Felületi szövegek az alkalmazás nyelvén. |
+| `markGated` | `boolean` | `true` | Megjelöli a kapus blokk utáni blokkokat (lásd [Egyedi és kapus blokkok](writing-plugins.md#egyedi-és-kapus-blokkok)). |
+| `nested` | `boolean` | `false` | A beágyazott blokkjaikat renderelő plugin-előnézetek állítják be. |
+
+Az előnézet a beépített blokkokat sima HTML-ként rendereli (`p`, `h1`…`h6`, `ul`/`ol` beágyazott elemekkel, `blockquote`, `pre > code` `language-<lang>` osztállyal, `hr`), a pluginblokkokat pedig a pluginjuk `preview` komponensével. Az a blokk, amelynek típusához nincs plugin a `plugins` listában, vagy amelynek pluginjának nincs `preview`-ja, nem renderelődik.
+
+Hogy használod-e egyáltalán a `Preview`-t, rajtad múlik: a szerkesztő nem függ tőle. Egy saját megjelenítővel dolgozó alkalmazás maga is renderelheti a tárolt blokkokat, és a pluginjai elhagyhatják a `preview`-t.
+
+A legfelső szintű szerkesztőnek vagy előnézetnek átadott `media` és `messages` öröklődik minden alatta lévő beágyazott szerkesztőre, beágyazott előnézetre és pluginkomponensre.
+
+## A paletta
+
+A `palette` **palettaazonosítók** listája: `md:p`, `md:h1`…`md:h6`, `md:ul`, `md:ol`, `md:todo`, `md:quote`, `md:code`, `md:hr` a beépített blokkokhoz, pluginoknál pedig a plugin `type` értéke. Ez dönti el:
+
+- mely blokkokat kínálja fel a perjeles menü és az „Átalakítás” menü, és milyen sorrendben;
+- mely markdown-gyorsbillentyűk működnek (a `## ` begépelése csak akkor alakít egy bekezdést címsorrá, ha az `md:h2` szerepel a palettán);
+- mivé válhat a beillesztett markdown: a palettán kívüli típusú beillesztett blokk bekezdés lesz, az elválasztó pedig elvész.
+
+A sima bekezdés (`md:p`) tartalékként mindig engedélyezett.
+
+```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];
+	// Nincs h1 (az oldal címe az), és nincs kódblokk.
+	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} />
+```
+
+A `PALETTE_ITEMS` a beépített blokkokat sorolja fel a címkéikkel, tippjeikkel és ikonjaikkal; a `BUILT_IN_IDS` csak az azonosítóik az alapértelmezett sorrendben.
+
+> **A paletta a felkínálást korlátozza, nem a betöltést**
+>
+> Ha egy dokumentumban már van palettán kívüli blokk, az továbbra is megjelenik. Az a pluginblokk, amelynek pluginja hiányzik a `plugins` listából, változatlanul megmarad, és ismeretlen blokkként jelenik meg, amelyet csak törölni lehet. Ha az ilyen dokumentumokat el akarod utasítani, validáld őket a szerveren (lásd [A szerveren](server-side.md)).
+
+## Szerkesztés
+
+| Művelet | Hogyan |
+|---|---|
+| Blokk beszúrása | A `/` megnyitja a perjeles menüt (címke, tipp, kulcsszavak és ezek fordításai alapján kereshető); a `+` gomb egy blokkot ad hozzá alul. |
+| Markdown-gyorsbillentyűk | Bekezdés elején: `# `…`###### `, `- ` / `* ` / `+ `, `1. `, `[] `, `> `. |
+| Szövegformázás | Jelölj ki szöveget az eszköztárhoz, vagy `Ctrl/Cmd` + `B` félkövér, `I` dőlt, `U` aláhúzott, `Shift+X` áthúzott, `E` kód, `K` link, `\` formázás eltávolítása. Az alsó és a felső index az eszköztáron érhető el. |
+| Behúzás | `Tab` / `Shift+Tab` (legfeljebb 6 szint). |
+| Sortörés | `Shift+Enter`; kódblokkban az `Enter` töri a sort, a `Shift+Enter` vagy a `Ctrl/Cmd+Enter` pedig új blokkot kezd. |
+| Blokkok kijelölése | Kattints egy blokk fogantyújára, nyomj `Esc`-et egy blokkban, `Shift+↑/↓` a blokk szélén túl, vagy húzz szövegkijelölést több blokkon át. Üres blokkban a `Ctrl/Cmd+A` minden blokkot kijelöl. |
+| Blokkok mozgatása | Húzd a fogantyút (beágyazott szerkesztőkbe be és onnan ki is), vagy `Ctrl/Cmd+Shift+↑/↓`. |
+| Átalakítás | Kattints egy blokk vagy egy kijelölés fogantyújára az „Átalakítás” menühöz. |
+| Másolás, kivágás | A kijelölt blokkok másolásakor a markdownjuk kerül a vágólapra (a pluginblokkok a markdown alakjukon keresztül). |
+| Beillesztés | A többsoros szöveg markdownként értelmeződik, és blokkokká válik. |
+| Visszavonás, újra | `Ctrl/Cmd+Z`, `Ctrl/Cmd+Shift+Z` vagy `Ctrl/Cmd+Y`. |
+
+Hogy egy blokk mivé alakítható, az attól függ, mit tartalmaz (a `content` értékétől):
+
+- a szöveges blokkok egymásba alakíthatók, és megtartják a formázásukat; ha szöveget kóddá alakítasz, csak a betűk maradnak meg;
+- a tartalom nélküli blokk (elválasztó, videó, térkép) csak üres blokkokat vagy más tartalom nélküli blokkokat válthat fel;
+- a beágyazott blokkokat tartalmazó blokk (egy doboz) körbefoghatja a kijelölt blokkokat, ha mindegyiket elfogadja; a **„Kicsomagolás”** kimozgatja a doboz blokkjait; egy doboz átalakítható másik dobozszerű típussá, és az azonos nevű props értékek átkerülnek.
+
+## Görgetés-szinkron
+
+Ha az alkalmazás egymás mellett mutatja a szerkesztőt és az előnézetet, az előnézet követheti a szerkesztő görgetését. A `scrollSync()` két Svelte actiont és egy függvényt ad vissza:
+
+```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>
+```
+
+- A `use:sync.source` a szerkesztő görgethető dobozára kerül, a `use:sync.target` az előnézetére. A cél a görgetési tartományának ugyanakkora hányadáig (0…1) görög, mint a forrás. A szinkron egyirányú: az előnézet görgetése semmi mást nem mozgat.
+- Animációs képkockánként egyszer igazodik, amikor a forrás görög, és akkor is, amikor a céldoboz vagy a gyerekei mérete megváltozik. A `sync.align()` kérésre is igazít, például miután megváltozott az előnézet szélessége.
+- A `use:sync.target={on}` egy logikai értéket kap (alapértéke `true`), ha az alkalmazás két doboz között váltogatja a célt, például egy asztali panel és egy telefonkeret között: a láthatót kapcsold be.
+- A szinkron csak arányos: a két doboz nagyjából ugyanazt a helyet mutatja, nem pontosan ugyanazt a blokkot. Ez szándékos — nem kell hozzá semmilyen jelölés, és bármilyen előnézettel működik.
+
+A `scrollFraction(box)` megmondja, mennyire van legörgetve egy doboz (0…1; 0, ha nem görgethető), a `setScrollFraction(box, f)` pedig odagörgeti — például hogy megmaradjon a hely, amikor az önmagában látható előnézet szélessége változik:
+
+```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(); // pl. az előnézet szélességének váltása
+	await tick();
+	setScrollFraction(box, f);
+}
+```