@atom-forge/brickee 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,139 @@
+# 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). |
+| `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. |
+| `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 `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);
+}
+```

package/docs/hu/getting-started.md

@@ -0,0 +1,85 @@
+# Első lépések
+
+[Tartalom](index.md) · [Következő →](editor-and-preview.md)
+
+## Mi a Brickee
+
+A Brickee blokkszerkesztő: a dokumentum blokkok listája, mindegyik a saját sorában szerkeszthető, húzással átrendezhető, és a fogantyújáról más típusúvá alakítható. A magban lévő blokkok markdown blokkok — bekezdések, hat címsorszint, felsorolás, számozott lista és teendőlista, idézetek, kód és elválasztók —, így egy pluginok nélküli dokumentum sima markdownként olvasható és másolható.
+
+Minden más plugin. A plugin egy egyszerű objektum (`BlockPlugin`), amely megnevez egy blokktípust, és a következőket adja hozzá:
+
+- egy **nézetet** — a szerkesztőben megjelenő Svelte-komponenst;
+- egy **előnézetet** — a blokkot az oldalon megjelenítő Svelte-komponenst;
+- **mezőket** — a blokk tetején megjelenő beállításokat (szöveg, szín, választó, csúszka…);
+- opcionálisan egy **markdown alakot**, amelyet a dokumentum markdownként való másolásakor vagy exportálásakor használ.
+
+A csomag négy általános plugint is tartalmaz — táblázat, YouTube-videó, térkép és térköz —, de ezek is ugyanolyan pluginok, mint bármelyik más: a magban semmi sem függ tőlük, és csak azokat adod át, amelyeket szeretnél. A képblokkokat, dobozokat és más, az oldalra jellemző blokkokat te írod meg pluginként.
+
+## Telepítés
+
+```sh
+bun add @atom-forge/brickee @atom-forge/ui @lucide/svelte
+```
+
+| Peer dependency | Miért |
+|---|---|
+| `svelte` `^5.0.0` | A szerkesztő, az előnézet és a pluginok Svelte 5 komponensek. |
+| `@atom-forge/ui` `>=0.0.37` | A felugró ablakok (linkbekérő) és a blokkmezők űrlapvezérlői. |
+| `@lucide/svelte` `>=1.0.0` | A blokkok ikonjai. |
+| `zod` `^4.0.0` (opcionális) | Csak az `@atom-forge/brickee/schema` szerveroldali sémájához. |
+
+## A befogadó alkalmazás beállítása
+
+A blokkmezők és a felugró ablakok `@atom-forge/ui` komponensek, ezért az alkalmazást úgy kell beállítani, ahogy az `@atom-forge/ui` megköveteli:
+
+- Tailwind CSS 4, importált `@atom-forge/ui` téma-CSS-sel, a `dist` mappáját pedig add hozzá Tailwind `@source`-ként;
+- az alkalmazás az `@atom-forge/ui` `Root` komponense alatt renderelődjön, amely a témát és az overlay-kontextusokat biztosítja.
+
+A legfelső szintű `Editor` saját felugróablak-kezelőt hoz létre, és saját felugróablak-tárolót renderel; a pluginblokkokba ágyazott szerkesztők ezt használják közösen.
+
+A szerkesztő a színeit az `@atom-forge/ui` téma tokenjeiből veszi (`--color-surface`, `--color-frame`, `--color-muted-contrast`…), így követi a befogadó alkalmazás világos és sötét módját. Az előnézet keretei és képaláírásai az oldal szövegszínéből számolódnak.
+
+A blokkok fogantyúi a **szerkesztő dobozától balra**, egy kb. 22 px széles sávban jelennek meg: a szerkesztőt körülvevő elemnek legyen ennyi bal oldali paddingje, különben a fogantyúk kilógnak belőle.
+
+> **Hiányzó téma**
+>
+> Az `@atom-forge/ui` téma-CSS nélkül a szerkesztő továbbra is működik, de a blokkmezők, a színválasztó, a csúszka és a felugró ablakok stílus nélkül jelennek meg.
+
+Az előnézet csak azt a kevés stílust adja hozzá, amelyre saját magának szüksége van (teendő-jelölőnégyzetek, képszélességek, körbefuttatás). A címsorok, bekezdések és listák tipográfiája az előnézetet megjelenítő oldalról jön.
+
+## Egy első szerkesztő
+
+```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>
+```
+
+- A `value` a dokumentum JSON-ként (`StoredBlock[]`). A szerkesztő minden változáskor visszaírja; mentsd el úgy, ahogy van.
+- A `plugins` felsorolja azokat a pluginblokkokat, amelyeket a szerkesztő megjeleníthet és felkínálhat. Ha elhagyod, egyszerű markdown-szerkesztőt kapsz.
+- A `Preview` ugyanazt a dokumentumot ugyanazokkal a pluginokkal rendereli, úgy, ahogy az oldal megjeleníti.
+
+Üres sorban gépelj `/` jelet a blokkmenü megnyitásához.
+
+## Belépési pontok
+
+| Import | Tartalom |
+|---|---|
+| `@atom-forge/brickee` | `Editor`, `Preview`, a kit (`Frame`, `Empty`, segédfüggvények), a tárolt alak, a markdown-átalakítások, a kontextusok, a paletta, a típusok. |
+| `@atom-forge/brickee/plugins` | A mellékelt pluginok (`table`, `youtube`, `map`, `gap`), a mind a négyet tartalmazó `PLUGINS` és a segédfüggvényeik. |
+| `@atom-forge/brickee/schema` | `blocksSchema` és `blocksSchemaFor` (zod), szerveroldali validáláshoz. |
+| `@atom-forge/brickee/model` | A tárolt alak Svelte nélkül: `StoredBlock`, `MD`, `isMd`, `acceptsId`, `blocksToPlainText`… |
+| `@atom-forge/brickee/locales/hu` | `hu`: a magyar felületi szövegek. |
+
+> **Csak az kerül a bundle-be, amit importálsz**
+>
+> A mellékelt pluginok saját belépési ponton érhetők el. Az az alkalmazás, amely csak az `@atom-forge/brickee`-t importálja, a markdown-szerkesztőt kapja, pluginkód nélkül.

package/docs/hu/host-contexts.md

@@ -0,0 +1,169 @@
+# Az alkalmazás kontextusai
+
+[← Előző](writing-plugins.md) · [Tartalom](index.md) · [Következő →](server-side.md)
+
+A szerkesztőnek nincsenek propjai az alkalmazás fogalmaihoz. Amit a befogadó alkalmazás tud — az éppen mutatott oldalszélességet, a kiemelhető kódnyelveket, a nyelvét —, az három Svelte-kontextuson keresztül jut el a pluginokhoz. Mindegyikhez tartozik egy `provide…` függvény, amelyet a szerkesztő vagy az előnézet fölötti komponens inicializálásakor hívsz meg, és egy `use…` függvény a plugin-komponensek számára.
+
+| Kontextus | Megadás | Olvasás | Mit hordoz |
+|---|---|---|---|
+| Nézet | `provideView(() => key)` | `useView()` | A nézet, amelyet a nézetenkénti mezők szerkesztenek. |
+| Kódnyelvek | `provideCodeLanguages(() => list)` | `useCodeLanguages()` | A nyelvek, amelyeket a kódblokk felkínál. |
+| Szöveg | `messages` prop, vagy `provideText(() => messages)` | `useText()` | Felületi szövegek az alkalmazás nyelvén. |
+
+A beágyazott szerkesztők és előnézetek mindhármat a szülőjüktől öröklik.
+
+A képek nem kontextuson keresztül érkeznek: hogy egy képblokk mit tárol, és honnan veszi a képeit, azt az alkalmazás saját pluginja dönti el (lásd [Képek](writing-plugins.md#képek)).
+
+## Nézetenkénti értékek
+
+Egyes beállítások attól függnek, hogyan jelenik meg az oldal: egy képnek telefonon más képarány kellhet, mint széles képernyőn. A `views` beállítással rendelkező `slider` mező nézetenként tárol értéket. Itt ez a [Pluginok írása](writing-plugins.md#képek) fejezet `photo` pluginjának magassága és a mellékelt `gap`:
+
+```ts
+import type { BlockPlugin } from '@atom-forge/brickee';
+import { gap } from '@atom-forge/brickee/plugins';
+import { photo } from './photo';
+
+export const VIEWS = [
+	{ key: 'desktop', label: 'Desktop' },
+	{ key: 'tablet', label: 'Tablet' },
+	{ key: 'phone', label: 'Phone' }
+];
+
+/** Ugyanaz a plugin, az egyik mezője nézetenként állítva. */
+const perView = (plugin: BlockPlugin, key: string): BlockPlugin => ({
+	...plugin,
+	fields: plugin.fields?.map((f) => (f.key === key ? { ...f, views: VIEWS } : f))
+});
+
+export const plugins = [perView(photo, 'ratio'), perView(gap, 'lines')];
+```
+
+Hogy milyen nézetek léteznek, és melyik látszik éppen, az az alkalmazás dolga. Az alkalmazás a `provideView`-val közli a szerkesztővel az aktuális nézetet, jellemzően egy szerkesztő melletti szélességváltóból:
+
+```svelte
+<script lang="ts">
+	import { Editor, provideView, type StoredBlock } from '@atom-forge/brickee';
+	import { plugins } from './blocks';
+
+	let { value = $bindable(), view }: { value: StoredBlock[]; view: string } = $props();
+	provideView(() => view);
+</script>
+
+<Editor bind:value {plugins} />
+```
+
+Hogyan viselkednek az értékek:
+
+- Az első nézet az **alap**. Minden további nézet, amíg nincs saját értéke, az előtte lévő nézet értékét veszi át; a mező ilyenkor örököltként jelölve mutatja az értéket.
+- A mező az aktuális nézet értékét szerkeszti, és a saját címkéje mellett a nézet címkéjét is mutatja. `provideView` nélkül, vagy ha a kulcs nem szerepel a `views`-ban, az alapértéket szerkeszti.
+- Tárolás: ha csak alapérték van → önmagában, egyszerű értékként tárolódik (`"ratio": "56"`); ha más nézeteknek saját értékük van → nézet szerint kulcsolt objektumként (`"ratio": { "desktop": "56", "phone": "100" }`). Azok a dokumentumok, amelyek még azelőtt íródtak, hogy egy mező nézetenkéntivé vált, érvényesek maradnak.
+
+Az előnézet a `viewValues(value, keys)`-szel olvassa ki őket — minden nézet értékét, az öröklést alkalmazva —, vagy csak az alapértéket a `baseValue(value)`-val. A photo előnézetének ez a változata CSS-változókon keresztül szélességenként egy-egy képarányt ad a böngészőnek:
+
+```svelte
+<script lang="ts">
+	import { viewValues, 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));
+	// desktop, tablet, phone: mindegyikhez egy CSS aspect-ratio ('auto': a kép saját alakja)
+	const r = $derived(viewValues(props.ratio, ['desktop', 'tablet', 'phone']).map((v) => aspect(v) ?? 'auto'));
+</script>
+
+{#if src}
+	<img {src} alt={props.alt ?? ''} style:--r-desktop={r[0]} style:--r-tablet={r[1]} style:--r-phone={r[2]} />
+{/if}
+
+<style>
+	img {
+		width: 100%;
+		object-fit: cover;
+		aspect-ratio: var(--r-phone);
+	}
+	@media (min-width: 640px) {
+		img {
+			aspect-ratio: var(--r-tablet);
+		}
+	}
+	@media (min-width: 1024px) {
+		img {
+			aspect-ratio: var(--r-desktop);
+		}
+	}
+</style>
+```
+
+> **Csak csúszkák**
+>
+> A `views` a `slider` mezőkön támogatott. A többi mezőfajta figyelmen kívül hagyja.
+
+## Kódnyelvek
+
+A kódblokk nyelve (`props.lang`, a markdown-kerítés info-szövege) alapból szabad szöveg. Ha az alkalmazás tudja, mely nyelveket tud kiemelni az oldala, megadja a listát, és a kódblokk mezősávjában a mező legördülő lista lesz, elején a *Nincs* opcióval:
+
+```svelte
+<script lang="ts">
+	import { Editor, provideCodeLanguages, type StoredBlock } from '@atom-forge/brickee';
+
+	let { value = $bindable() }: { value: StoredBlock[] } = $props();
+	provideCodeLanguages(() => [{ value: 'ts', label: 'TypeScript' }, { value: 'svelte', label: 'Svelte' }, 'css', 'bash']);
+</script>
+
+<Editor bind:value />
+```
+
+Egy elem string vagy `{ value, label? }`; a `value` kerül tárolásra. A beágyazott szerkesztők öröklik a listát. Egy tárolt nyelv, amely nincs a listában, opció marad, így egy régebbi dokumentum megnyitásakor semmi sem vész el.
+
+## Felületi szövegek
+
+A szerkesztő és a pluginok angolul íródtak, és az angol szöveg a fordításának kulcsa. Add át a `messages`-t — egy objektumot, amely az angol szövegeket a te nyelvedre képezi le — a legfelső szintű szerkesztőnek és előnézetnek:
+
+```svelte
+<script lang="ts">
+	import { Editor, type StoredBlock } from '@atom-forge/brickee';
+	import { PLUGINS } from '@atom-forge/brickee/plugins';
+	import { hu } from '@atom-forge/brickee/locales/hu';
+
+	let value = $state<StoredBlock[]>([]);
+</script>
+
+<Editor bind:value plugins={PLUGINS} messages={hu} />
+```
+
+Az `@atom-forge/brickee/locales/hu` a `hu`-t exportálja: a szerkesztő és az összes mellékelt plugin magyar szövegeit. Bővítsd ki a saját pluginjaid és mezőid szövegeivel:
+
+```ts
+import type { Messages } from '@atom-forge/brickee';
+import { hu } from '@atom-forge/brickee/locales/hu';
+
+export const messages: Messages = {
+	...hu,
+	Button: 'Gomb',
+	'A link as a button': 'Egy link gombként',
+	Desktop: 'Asztali',
+	Phone: 'Telefon'
+};
+```
+
+Amit a szerkesztő magától lefordít:
+
+- a beépített blokkok és a pluginok `label`, `hint` és `keys` értékeit (a perjeles menü az angol és a lefordított szavak között is keres);
+- egy plugin `tag`-jének részeit, ` · `-nál darabolva;
+- a mezők címkéit, helyőrzőit, az opciók címkéit, a `none` címkéket és a nézetcímkéket;
+- az `Empty` szövegét és a szerkesztő saját felületét.
+
+Azt a szöveget, amelyet egy plugin maga renderel — a nézetében vagy az előnézetében —, a `useText()`-en keresztül add ki:
+
+```svelte
+<script lang="ts">
+	import { useText, type PluginPreviewProps } from '@atom-forge/brickee';
+
+	let { props }: PluginPreviewProps = $props();
+	const tr = useText();
+</script>
+
+<p>{tr('Map: {place}', { place: String(props.q ?? '') })}</p>
+```
+
+A `{name}` helyőrzőket a második argumentum tölti ki. Komponenseken kívül a `translator(messages)` ugyanilyen függvényt ad vissza. A `messages`-ből hiányzó szöveg angol marad.

package/docs/hu/index.md

@@ -0,0 +1,38 @@
+# Brickee
+
+Az `@atom-forge/brickee` blokkszerkesztő Svelte 5-höz. A magja egy markdown blokkszerkesztő — bekezdések, címsorok, listák, teendők, idézetek, kód, elválasztók —, minden más blokk pedig **plugin**: egy blokk, amelynek van szerkesztőnézete, oldali előnézete, vannak mezői, és opcionálisan markdown alakja. A dokumentumok JSON-ként tárolódnak.
+
+Ezek az oldalak a [Brickee könyv](https://books.atom-forge.eu) alapján készültek, és angol nyelvű változatuk, a [`../en/index.md`](../en/index.md) fordításai; eltérés esetén az angol változat a mérvadó. Kódoló ágenseknek tömör referencia a [`README-AI.md`](../../README-AI.md).
+
+A csomag három rétegből épül fel:
+
+```mermaid
+flowchart TB
+  core["Mag: markdown blokkok, Editor, Preview, tárolt alak, kit"]
+  bundled["Mellékelt pluginok: táblázat, YouTube, térkép, térköz"]
+  own["Saját pluginok: ugyanaz a BlockPlugin alak"]
+  core --> bundled
+  core --> own
+```
+
+- **Mag** (`@atom-forge/brickee`) — a markdown blokkok, az `Editor` és a `Preview`, a tárolt alak és annak markdown-átalakításai, valamint a **kit**, amellyel a pluginok készülnek. Pluginok nélkül egyszerű markdown blokkszerkesztő.
+- **Mellékelt pluginok** (`@atom-forge/brickee/plugins`) — ugyanolyan pluginok, mint bármelyik más, és csak abból készültek, amit a mag exportál. Csak azokat kapcsolod be, amelyekre szükséged van.
+- **A saját pluginjaid** — ugyanaz a `BlockPlugin` alak, az alkalmazásodban.
+
+Maga a szerkesztő semmit sem tud az alkalmazásodról. Amire egy alkalmazásnak szüksége van — az oldalszélességei, a kódnyelvei, a nyelve —, az **kontextusokon** (nézet, kódnyelvek, szöveg) vagy a pluginok **mezőin** keresztül jut el a pluginokhoz, soha nem külön szerkesztő-propokon át. A képek sem kivételek: a képblokk a saját pluginod, amely úgy tárolja, választja ki és oldja fel a képeit, ahogy az alkalmazásod teszi.
+
+## Tartalom
+
+1. [Első lépések](getting-started.md) — a három réteg, telepítés, a befogadó alkalmazás beállítása, és egy első szerkesztő az előnézetével.
+2. [A szerkesztő és az előnézet](editor-and-preview.md) — az `Editor` és a `Preview` propjai, a paletta, a szerkesztési funkciók és a görgetés-szinkron.
+3. [Dokumentumok és markdown](documents-and-markdown.md) — a tárolt alak (`StoredBlock`), a beépített blokkok, valamint az átalakítás markdownból és markdownba.
+4. [Mellékelt pluginok](bundled-plugins.md) — mit tartalmaz az `@atom-forge/brickee/plugins`, és hogyan írhatsz felül egy előnézetet vagy adhatsz hozzá mezőket.
+5. [Pluginok írása](writing-plugins.md) — a `BlockPlugin` felépítése, mezők, nézetek és előnézetek, tárolók, markdown alakok, képblokkok és a kit.
+6. [Az alkalmazás kontextusai](host-contexts.md) — nézetenkénti értékek, kódnyelvek és felületi szövegek.
+7. [A szerveren](server-side.md) — sémavalidálás, sima szöveg és védett tartalom.
+8. [Receptek és buktatók](recipes-and-pitfalls.md) — teljes minták és az elkerülendő hibák.
+9. [Frissítés](upgrading.md) — mit kell módosítanod a kódodban, amikor újabb verzióra váltasz.
+
+A könyvben van egy AI Notes fejezet is: utasítások, amelyeket a csomagot használó projekt ágens-utasításfájljába másolhatsz.
+
+A Svelte-példák teljes komponensek, hacsak másként nem jelzik. Az alkalmazásbeli értékek, például az aktuális oldalszélesség, azt jelölik, amit az alkalmazásod biztosít.

package/docs/hu/recipes-and-pitfalls.md

@@ -0,0 +1,123 @@
+# Receptek és buktatók
+
+[← Előző](server-side.md) · [Tartalom](index.md) · [Következő →](upgrading.md)
+
+## Egy hely a blokkbeállításoknak
+
+Egy alkalmazás pluginjait, palettáit és szövegeit tartsd egyetlen modulban, a szerkesztőt pedig csomagold be egy saját komponensbe. Az oldalak ezután a csomagolót használják, és soha nem ismétlik meg a beállítást.
+
+```ts
+// lib/blocks.ts
+import type { BlockPlugin, Messages } from '@atom-forge/brickee';
+import * as base from '@atom-forge/brickee/plugins';
+import { hu } from '@atom-forge/brickee/locales/hu';
+import SiteYouTube from './SiteYouTube.svelte';
+import { photo } from './photo';
+import { button } from './button';
+
+const withPreview = (plugin: BlockPlugin, preview: BlockPlugin['preview']): BlockPlugin => ({ ...plugin, preview });
+
+export const plugins: BlockPlugin[] = [
+	withPreview(base.youtube, SiteYouTube),
+	base.table,
+	base.map,
+	base.gap,
+	photo,
+	button
+];
+
+/** A teljes paletta, az oldal saját lapjainak szerkesztőihez. */
+export const PAGE_PALETTE = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)];
+
+/** Egy kisebb, a felhasználói hozzászólásokhoz. */
+export const COMMENT_PALETTE = ['md:p', 'md:ul', 'md:ol', 'md:quote', 'photo'];
+
+export const messages: Messages = { ...hu, Button: 'Gomb', 'A link as a button': 'Egy link gombként' };
+```
+
+```svelte
+<!-- lib/BlockEditor.svelte -->
+<script lang="ts">
+	import { Editor, provideView, type StoredBlock } from '@atom-forge/brickee';
+	import { messages, PAGE_PALETTE, plugins } from './blocks';
+
+	let {
+		value = $bindable(),
+		palette = PAGE_PALETTE,
+		view
+	}: { value: StoredBlock[]; palette?: string[]; view?: string } = $props();
+
+	provideView(() => view);
+</script>
+
+<Editor bind:value {plugins} {palette} {messages} />
+```
+
+A közzétett oldalt a `<Preview blocks={doc} {plugins} {messages} />`-val és ugyanazokkal a `plugins`-szal rendereld, így egy blokk ugyanúgy néz ki a szerkesztő előnézetében és az oldalon.
+
+## A teljes dokumentum másolása markdownként
+
+A kijelölt blokkok másolása már most is markdownt tesz a vágólapra. Egy, a teljes dokumentumot másoló „Copy as markdown” gombhoz:
+
+```svelte
+<script lang="ts">
+	import { fromStored, toMarkdown, type StoredBlock } from '@atom-forge/brickee';
+	import { plugins } from './blocks';
+
+	let { doc }: { doc: StoredBlock[] } = $props();
+
+	// Kattintáskezelőben fut, így a csak böngészőben működő toMarkdown itt biztonságos.
+	const copy = () => navigator.clipboard.writeText(toMarkdown(doc.map(fromStored), { plugins }));
+</script>
+
+<button type="button" onclick={copy}>Copy as markdown</button>
+```
+
+## Dokumentum indítása markdownból
+
+```ts
+import { fromMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
+
+// Böngészőben: a toStored a DOM-on keresztül olvassa be a soron belüli HTML-t.
+export const fromText = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
+```
+
+Ne feledd, hogy minden nem üres sorból külön blokk lesz.
+
+## Fejlesztés helyi másolattal
+
+Ha a csomag egy helyi checkoutját linkeled be egy alkalmazásba (`bun link`), a linkelt mappa a saját `node_modules`-át hozza magával. Vedd rá a Vite-ot, hogy a közös csomagokból az alkalmazás egyetlen példányát használja, különben a Svelte-kontextusok — a popupkezelő, a téma — nem találhatók meg a két példány között:
+
+```ts
+// az alkalmazás vite.config.ts-e
+export default defineConfig({
+	plugins: [sveltekit()],
+	resolve: {
+		dedupe: ['svelte', '@atom-forge/ui', '@lucide/svelte', 'zod']
+	}
+});
+```
+
+Az alkalmazás a csomag lefordított `dist/` mappáját olvassa, ezért minden változtatás után buildeld újra a csomagot.
+
+## Buktatók
+
+| Tünet | Ok | Megoldás |
+|---|---|---|
+| A blokkmezők és a popupok stílus nélkülinek tűnnek | Hiányzik az `@atom-forge/ui` téma CSS-e vagy a Tailwind `@source`-a | Állítsd be az `@atom-forge/ui`-t a dokumentációja szerint, és az alkalmazást a `Root`-ja alatt rendereld. |
+| A blokkfogantyúk balra kilógnak | A fogantyúk a szerkesztő dobozától balra jelennek meg | Adj a szerkesztőt körülvevő elemnek kb. 22 px bal oldali paddinget. |
+| A popupok nem nyílnak meg, vagy „context not found” hibák linkelt csomaggal | A `svelte` vagy az `@atom-forge/ui` két példányban van jelen | Vedd fel őket a Vite `resolve.dedupe` listájába. |
+| Egy plugin blokkja „Unknown block” feliratot mutat | A pluginja hiányzik a `plugins`-ból | Egy dokumentumtípus minden szerkesztőjének és előnézetének ugyanazokat a pluginokat add át. |
+| Egy blokk hiányzik a `Preview`-ból | A pluginjának nincs `preview`-ja | Adj a pluginnak `preview`-t (a mellékelt pluginoknak van alapértelmezett), vagy rendereld a blokkot a saját megjelenítőddel. |
+| Egy plugin blokkja hiányzik az oldalról | Az előnézet más `plugins`-t kapott | Ugyanazt a pluginlistát használd a szerkesztőhöz és az előnézethez. |
+| Egy képblokk semmit sem renderel | Az előnézete elutasítja a tárolt címet, vagy az alkalmazás saját keresése nem ismeri a tárolt azonosítót | Olyan címet tárolj, amelyet az előnézet elfogad (`http(s)` vagy az oldalon belüli); az azonosítókat a szerkesztőben és az oldalon ugyanabból az adatból oldd fel. |
+| Egy doboz nem tehető egy másik dobozba | A beágyazott szerkesztők egy szint mélyek | A tárolókat tartalomblokkok befogadására tervezd, ne más tárolókéra. |
+| Egy blokk nem érhető el egy tárolón belül | Az `accepts` vagy az alkalmazás `palette`-je kihagyja | Vedd fel a palettaazonosítót az `accepts`-be (vagy használd az `'md:*'`-ot az összes beépítetthez). |
+| Egy egyedi blokk kétszer jelenik meg | A séma nem kényszeríti ki a `unique`-ot | Ellenőrizd a szerveren, ha az alkalmazásod számít rá. |
+| A védett tartalom mindenkinek látszik | A `gate` csak megjelöli a blokkokat | Renderelés előtt vágd meg a dokumentumot a szerveren. |
+| `document is not defined` | A `toMarkdown` vagy a `toStored` SSR közben futott | Csak a böngészőben hívd őket. |
+| Egy propsból jövő szín vagy link elrontja az oldalt | A props felhasználói bemenet | Használd a `safeColor`-t, ellenőrizd a linkeket, és propsszal soha ne használj `{@html}`-t. |
+| Egy felülírt plugin elveszíti a blokkjait | Megváltozott a `type`-ja | Egy plugin szétterítésekor tartsd meg a `type`-ot. |
+| `bind:blocks` hiba egy saját nézetben | A `props` vagy a `blocks` nincs bindable-ként deklarálva | Deklaráld mindkettőt `$bindable()`-lel. |
+| Az érték soha nem üres tömb | A szerkesztő üres dokumentumnál egy üres bekezdést mutat (és ír) | Az olyan dokumentumot, amelyben csak üres bekezdések vannak, kezeld üresként, például a `blocksToPlainText(doc).trim() === ''` segítségével. |
+| Az előnézet nem követi a szerkesztő görgetését | Az actionök nem a görgethető dobozokon vannak | A `use:sync.source` / `use:sync.target` közvetlenül az `overflow` dobozokra kerüljön. |

package/docs/hu/server-side.md

@@ -0,0 +1,95 @@
+# A szerveren
+
+[← Előző](host-contexts.md) · [Tartalom](index.md) · [Következő →](recipes-and-pitfalls.md)
+
+A tárolt dokumentum a böngésző által küldött JSON, ezért a szervernek mentés előtt ellenőriznie kell. Két belépési pontnak nincs Svelte-függősége, ezek szerveroldali kódhoz készültek:
+
+- `@atom-forge/brickee/model` — `StoredBlock`, `MD`, `MAX_INDENT`, `MAX_DEPTH`, `isMd`, `acceptsId`, `inlineToPlainText`, `blocksToPlainText`;
+- `@atom-forge/brickee/schema` — `blocksSchema` és `blocksSchemaFor`, `zod`-dal építve (opcionális peer dependency: telepítsd, ha ezt a belépési pontot használod).
+
+## Dokumentum validálása
+
+```ts
+// content.server.ts
+import { blocksSchemaFor } from '@atom-forge/brickee/schema';
+import { plugins } from '$lib/blocks';
+
+const contentSchema = blocksSchemaFor(plugins);
+
+export function parseContent(input: unknown) {
+	const result = contentSchema.safeParse(input);
+	if (!result.success) throw new Error('Invalid content');
+	return result.data; // StoredBlock[]
+}
+```
+
+A `blocksSchema` bármely dokumentum alakját ellenőrzi; a `blocksSchemaFor(plugins)` ehhez hozzáveszi a tárolók `accepts` listáit. Minden pluginból csak a `type` és az `accepts` kell neki, így az a szerver, amely nem akarja importálni a plugin-komponenseket, csak ezeket is átadhatja:
+
+```ts
+const contentSchema = blocksSchemaFor([
+	{ type: 'note', accepts: ['md:*', 'youtube'] },
+	{ type: 'youtube' }
+]);
+```
+
+Amit a séma ellenőriz:
+
+| Szabály | Korlát |
+|---|---|
+| Blokkkulcsok | Csak `type`, `indent`, `text`, `props`, `blocks` (szigorú objektumok). |
+| `type` | `^[a-z][a-z0-9:-]{0,39}$` |
+| `indent` | Egész szám, 0–6. |
+| `text` | Legfeljebb 100 000 karakter. |
+| `props` | Legfeljebb 60 karakteres kulcsok, JSON-értékek. |
+| `blocks` | Tárolónként legfeljebb 500 beágyazott blokk, csak egy szint mélyen. |
+| Dokumentum | Legfeljebb 2000 legfelső szintű blokk és JSON-ként 1 000 000 karakter. |
+| `accepts` (`blocksSchemaFor`) | Minden beágyazott blokkot befogad a tárolója. |
+
+Amit **nem** ellenőriz: hogy egy típus ismert-e, hogy egy egyedi blokk csak egyszer fordul-e elő, és hogy mit tartalmaz a props. Az alkalmazásod által megkövetelt szabályokhoz adj hozzá saját finomításokat – például az ismeretlen blokktípusok elutasításához:
+
+```ts
+import type { StoredBlock } from '@atom-forge/brickee/model';
+import { blocksSchemaFor } from '@atom-forge/brickee/schema';
+import { plugins } from '$lib/blocks';
+
+const BUILT_IN = ['md:p', 'md:h1', 'md:h2', 'md:h3', 'md:h4', 'md:h5', 'md:h6', 'md:ul', 'md:ol', 'md:todo', 'md:quote', 'md:code', 'md:hr'];
+const known = new Set([...BUILT_IN, ...plugins.map((p) => p.type)]);
+const allKnown = (list: StoredBlock[]): boolean => list.every((b) => known.has(b.type) && allKnown(b.blocks ?? []));
+
+export const contentSchema = blocksSchemaFor(plugins).refine(allKnown, 'Unknown block type.');
+```
+
+> **Alak, nem biztonság**
+>
+> A séma szabályos és korlátos méretű dokumentumokat biztosít; a propsokat viszont nem teszi biztonságosan renderelhetővé. A renderelők minden szöveget escape-elnek, és a hivatkozásokat biztonságos sémákra korlátozzák, a saját propsait pedig minden plugin-előnézetnek magának kell megtisztítania (lásd [Pluginok írása](writing-plugins.md)).
+
+## Egyszerű szöveg
+
+A `blocksToPlainText(blocks)` sorrendben összegyűjti egy dokumentum minden szövegét, üres sorokkal elválasztva: a blokkszövegeket jelölések és hivatkozáscélok nélkül, a szóközt tartalmazó szöveges propsokat (címek, képaláírások – azonosítók és színek nem), a táblázatsorokat és a beágyazott blokkokat. Keresőindexekhez, leadekhez és meta descriptionökhöz használd. Az `inlineToPlainText(md)` ugyanezt teszi egyetlen inline markdown szöveggel.
+
+```ts
+import { blocksToPlainText, type StoredBlock } from '@atom-forge/brickee/model';
+
+export const description = (doc: StoredBlock[]) => blocksToPlainText(doc).slice(0, 160);
+```
+
+## Renderelés
+
+A `Preview` hagyományos Svelte-komponens, és szerveren is renderelhető; a mag renderelője és a mellékelt előnézetek nem használnak böngésző-API-kat. Csak a markdown-export útvonalnak (`toMarkdown`, `toStored`) kell a böngésző.
+
+## Védett tartalom
+
+Egy kapus blokk (egy `gate: true` beállítású plugin, például egy csak támogatóknak szóló elválasztó) csak annyit tesz, hogy az előnézet megjelöli az utána következő blokkokat. Hogy a védett részt elzárd azoktól az olvasóktól, akik nem láthatják, vágd el a dokumentumot a szerveren, mielőtt az oldalhoz érne:
+
+```ts
+import type { StoredBlock } from '@atom-forge/brickee/model';
+
+/** A dokumentum az első kapus blokkig, azt is beleértve, hozzáférés nélküli olvasóknak. */
+export function publicPart(doc: StoredBlock[], gateTypes: string[], canRead: boolean): StoredBlock[] {
+	if (canRead) return doc;
+	const at = doc.findIndex((b) => gateTypes.includes(b.type));
+	return at < 0 ? doc : doc.slice(0, at + 1);
+}
+```
+
+Hívd meg a kapus pluginjaid típusaival (például `['paywall']`) és az olvasó hozzáférésével. A hozzáférés nélküli olvasók a kapus blokkig látják a tartalmat, az előzetesével együtt; a hozzáféréssel rendelkezők a teljes dokumentumot kapják, és az előnézet megjelöli számukra a védett részt.