@atom-forge/brickee 0.0.0-stage → 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +24 -0
- package/LICENSE +21 -0
- package/README-AI.md +283 -0
- package/README.md +41 -2
- package/dist/Editor.svelte +1968 -0
- package/dist/Editor.svelte.d.ts +22 -0
- package/dist/ImagePicker.svelte +131 -0
- package/dist/ImagePicker.svelte.d.ts +13 -0
- package/dist/LinkPrompt.svelte +42 -0
- package/dist/LinkPrompt.svelte.d.ts +8 -0
- package/dist/PluginHost.svelte +41 -0
- package/dist/PluginHost.svelte.d.ts +13 -0
- package/dist/Preview.svelte +186 -0
- package/dist/Preview.svelte.d.ts +35 -0
- package/dist/PropsBar.svelte +395 -0
- package/dist/PropsBar.svelte.d.ts +20 -0
- package/dist/dom.d.ts +29 -0
- package/dist/dom.js +224 -0
- package/dist/i18n.d.ts +7 -0
- package/dist/i18n.js +18 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +16 -0
- package/dist/kit/Empty.svelte +24 -0
- package/dist/kit/Empty.svelte.d.ts +8 -0
- package/dist/kit/Frame.svelte +76 -0
- package/dist/kit/Frame.svelte.d.ts +15 -0
- package/dist/kit/util.d.ts +13 -0
- package/dist/kit/util.js +28 -0
- package/dist/locales/hu.d.ts +2 -0
- package/dist/locales/hu.js +147 -0
- package/dist/markdown.d.ts +25 -0
- package/dist/markdown.js +219 -0
- package/dist/media.d.ts +17 -0
- package/dist/media.js +12 -0
- package/dist/model.d.ts +21 -0
- package/dist/model.js +45 -0
- package/dist/palette.d.ts +19 -0
- package/dist/palette.js +23 -0
- package/dist/plugins/Gap.svelte +28 -0
- package/dist/plugins/Gap.svelte.d.ts +15 -0
- package/dist/plugins/GapPreview.svelte +17 -0
- package/dist/plugins/GapPreview.svelte.d.ts +5 -0
- package/dist/plugins/Map.svelte +47 -0
- package/dist/plugins/Map.svelte.d.ts +12 -0
- package/dist/plugins/MapPreview.svelte +26 -0
- package/dist/plugins/MapPreview.svelte.d.ts +5 -0
- package/dist/plugins/Table.svelte +563 -0
- package/dist/plugins/Table.svelte.d.ts +28 -0
- package/dist/plugins/TablePreview.svelte +62 -0
- package/dist/plugins/TablePreview.svelte.d.ts +5 -0
- package/dist/plugins/YouTube.svelte +52 -0
- package/dist/plugins/YouTube.svelte.d.ts +8 -0
- package/dist/plugins/YouTubePreview.svelte +76 -0
- package/dist/plugins/YouTubePreview.svelte.d.ts +5 -0
- package/dist/plugins/index.d.ts +20 -0
- package/dist/plugins/index.js +94 -0
- package/dist/plugins/util.d.ts +3 -0
- package/dist/plugins/util.js +8 -0
- package/dist/schema.d.ts +11 -0
- package/dist/schema.js +25 -0
- package/dist/scroll.d.ts +18 -0
- package/dist/scroll.js +57 -0
- package/dist/types.d.ts +133 -0
- package/dist/types.js +43 -0
- package/dist/view.d.ts +6 -0
- package/dist/view.js +11 -0
- package/docs/en/bundled-plugins.md +99 -0
- package/docs/en/documents-and-markdown.md +115 -0
- package/docs/en/editor-and-preview.md +141 -0
- package/docs/en/getting-started.md +81 -0
- package/docs/en/host-contexts.md +275 -0
- package/docs/en/index.md +38 -0
- package/docs/en/recipes-and-pitfalls.md +122 -0
- package/docs/en/server-side.md +95 -0
- package/docs/en/upgrading.md +55 -0
- package/docs/en/writing-plugins.md +305 -0
- package/docs/hu/bundled-plugins.md +99 -0
- package/docs/hu/documents-and-markdown.md +115 -0
- package/docs/hu/editor-and-preview.md +141 -0
- package/docs/hu/getting-started.md +81 -0
- package/docs/hu/host-contexts.md +275 -0
- package/docs/hu/index.md +38 -0
- package/docs/hu/recipes-and-pitfalls.md +122 -0
- package/docs/hu/server-side.md +95 -0
- package/docs/hu/upgrading.md +55 -0
- package/docs/hu/writing-plugins.md +305 -0
- package/package.json +110 -5
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Frissítés
|
|
2
|
+
|
|
3
|
+
[← Előző](recipes-and-pitfalls.md) · [Tartalom](index.md)
|
|
4
|
+
|
|
5
|
+
Ez a fejezet azokat a változásokat sorolja fel, amelyek teendőt igényelhetnek, amikor az `@atom-forge/brickee` újabb verziójára váltasz. Minden szakasz egy verziólépést tárgyal, a legújabbal kezdve, és minden változás egy **Teendő:** bekezdéssel zárul.
|
|
6
|
+
|
|
7
|
+
A tőled semmit nem igénylő változások – új exportok, javítások, dokumentációfrissítések – csak a változásnaplóban (`CHANGELOG.md`, a csomaggal együtt szállítva) szerepelnek.
|
|
8
|
+
|
|
9
|
+
> **Egyelőre nincs szükség migrációra**
|
|
10
|
+
>
|
|
11
|
+
> Az `@atom-forge/brickee`-nek még nem volt olyan kiadása, amely változtatást igényelt volna az azt használó kódban. Az alábbi szakasz csak azoknak az alkalmazásoknak szól, amelyek már azelőtt használták a szerkesztőt, hogy ebből a csomagból lett volna.
|
|
12
|
+
|
|
13
|
+
## A `block-editor` munkaterület-csomagról az Unreleased változatra
|
|
14
|
+
|
|
15
|
+
A szerkesztő `block-editor` néven, egy alkalmazáson belüli munkaterület-csomagként indult. Ugyanazzal a tárolt alakkal költözött ide `@atom-forge/brickee` néven, így az elmentett dokumentumokat nem kell átalakítani. Az import-azonosítók megváltoztak, a plugin-kit a pluginok belépési pontjából átkerült a magba, az oldalspecifikus pluginok pedig az alkalmazásnál maradtak.
|
|
16
|
+
|
|
17
|
+
### Csomagnév és belépési pontok
|
|
18
|
+
|
|
19
|
+
| Előtte | Utána |
|
|
20
|
+
|---|---|
|
|
21
|
+
| `block-editor` | `@atom-forge/brickee` |
|
|
22
|
+
| `block-editor/plugins` | `@atom-forge/brickee/plugins` |
|
|
23
|
+
| `block-editor/locales/hu` | `@atom-forge/brickee/locales/hu` |
|
|
24
|
+
|
|
25
|
+
**Teendő:** cseréld le a függőséget (`"block-editor": "workspace:*"` → `"@atom-forge/brickee"`), és nevezd át az importokat. Telepítsd az alkalmazás függőségeként az `@atom-forge/ui`-t és a `@lucide/svelte`-et, ha még nincsenek meg, valamint a `zod`-ot, ha a sémát használod.
|
|
26
|
+
|
|
27
|
+
### A kit a magban van
|
|
28
|
+
|
|
29
|
+
A `Frame`, az `Empty` és a plugin-segédfüggvények a mag belépési pontjából exportálódnak. A `safeColor`, a `viewValues`, a `baseValue` és a `lines` már nem exportálódik a pluginok belépési pontjából.
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
// Előtte
|
|
33
|
+
import { safeColor, viewValues } from 'block-editor/plugins';
|
|
34
|
+
|
|
35
|
+
// Utána
|
|
36
|
+
import { safeColor, viewValues } from '@atom-forge/brickee';
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
**Teendő:** a `Frame`, `Empty`, `safeColor`, `viewValues`, `baseValue`, `lines`, `mdText`, `mdJoin` és `mdQuote` elemeket az `@atom-forge/brickee`-ből importáld. A megmaradt mellékelt pluginok segédfüggvényei (`youtubeId`, `mapSrc`, `gapLines`, `tableHeads`…) az `@atom-forge/brickee/plugins`-ban maradnak.
|
|
40
|
+
|
|
41
|
+
### Az oldalspecifikus pluginok kikerültek a csomagból
|
|
42
|
+
|
|
43
|
+
A csomag mostantól csak négy általános célú plugint tartalmaz: `table`, `youtube`, `map` és `gap` (a `PLUGINS` ezt a négyet tartalmazza). A `block-editor/plugins` többi pluginja és a segédfüggvényeik alkalmazásspecifikusak voltak, és nem részei az `@atom-forge/brickee`-nek:
|
|
44
|
+
|
|
45
|
+
| Eltávolítva | Fajta |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `richBox`, `feature`, `sideBox`, `callout`, `spoiler`, `faq`, `imageText` | tároló pluginok |
|
|
48
|
+
| `image`, `gallery`, `tweet`, `form`, `banner`, `locked` | pluginok |
|
|
49
|
+
| `CALLOUTS`, `calloutTone`, `CalloutTone`, `questions`, `formEmbed`, `formHeight` | a segédfüggvényeik |
|
|
50
|
+
| `postId`, `userName`, `RATIO_MIN`, `RATIO_MAX`, `ratioPercent`, `ratio` | a korábbi `plugins/util` segédfüggvényei |
|
|
51
|
+
| `ImageProps`, `GalleryProps`, `CalloutProps` és e pluginok többi props-típusa | típusok |
|
|
52
|
+
|
|
53
|
+
A tárolt alak nem változott: az ilyen blokktípusokat tartalmazó dokumentumok érvényesek maradnak, amíg az alkalmazás ugyanazokkal a `type` értékekkel ad át pluginokat a szerkesztőnek és az előnézetnek.
|
|
54
|
+
|
|
55
|
+
**Teendő:** ha az alkalmazás ezek közül bármelyik plugint használja, tartsd meg belőlük a saját másolatodat (a nézeteiket, előnézeteiket és segédfüggvényeiket) az alkalmazásban, a mag kitjére építve, és vedd fel őket az alkalmazás pluginlistájába ugyanazzal a `type`-pal. A megmaradt négy plugint és a segédfüggvényeiket a korábbiakhoz hasonlóan az `@atom-forge/brickee/plugins`-ból importáld. A lemásolt pluginok felületi szövegeit add hozzá a `messages`-hez: az `@atom-forge/brickee/locales/hu` már nem tartalmazza őket.
|
|
@@ -0,0 +1,305 @@
|
|
|
1
|
+
# Pluginok írása
|
|
2
|
+
|
|
3
|
+
[← Előző](bundled-plugins.md) · [Tartalom](index.md) · [Következő →](host-contexts.md)
|
|
4
|
+
|
|
5
|
+
Egy plugin egy `BlockPlugin` objektum és két Svelte-komponens: egy **nézet** a szerkesztőhöz és egy **előnézet** az oldalhoz. Mindent, amire egy pluginnak szüksége van, az `@atom-forge/brickee` exportál — a mellékelt pluginok sem használnak mást.
|
|
6
|
+
|
|
7
|
+
## Felépítés
|
|
8
|
+
|
|
9
|
+
| Tag | Típus | Jelentés |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `type` | `string` | A tárolt `type`. Nem kezdődhet `md:`-vel; hogy átmenjen a sémán, illeszkednie kell a `^[a-z][a-z0-9:-]{0,39}$` mintára. |
|
|
12
|
+
| `label`, `hint` | `string` | Név és rövid leírás a perjeles és az „Átalakítás” menüben. |
|
|
13
|
+
| `keys` | `string` | További keresőszavak a perjeles menühöz. |
|
|
14
|
+
| `icon` | `Icon` | Egy `@lucide/svelte` ikonkomponens. |
|
|
15
|
+
| `props` | `() => P` | Egy új blokk propsai. |
|
|
16
|
+
| `fields` | `PropField[]` | A blokk tetején lévő beállítások (opcionális). |
|
|
17
|
+
| `tag` | `(props: P) => string` | A blokk tetején, a mezői előtt álló kis címke. A ` · `-tal elválasztott részeit egyenként fordítja le. |
|
|
18
|
+
| `content` | `'none' \| 'text' \| 'plain' \| 'blocks'` | Mit tartalmaz a blokk. A pluginok `'none'`-t (csak props) vagy `'blocks'`-ot (beágyazott dokumentum) használnak; ez dönti el, mit kínál az „Átalakítás” menü. |
|
|
19
|
+
| `view` | `Component<PluginViewProps>` | A blokk a szerkesztőben. |
|
|
20
|
+
| `preview` | `Component<PluginPreviewProps>` | A blokk az oldalon (opcionális). Nélküle a `Preview` semmit sem renderel a blokkhoz — saját megjelenítővel dolgozó alkalmazásoknak. |
|
|
21
|
+
| `accepts` | `string[]` | Egy tároló blokk megengedett beágyazott blokkjai, palettaazonosítókként; az `'md:*'` az összes beépített blokk. Alapértelmezés: minden, amit az alkalmazás kínál. |
|
|
22
|
+
| `markdown` | `(props: P, ctx: MarkdownContext) => string` | A markdown alakja (opcionális). |
|
|
23
|
+
| `unique` | `boolean` | Dokumentumonként legfeljebb egy, csak a legfelső szinten. |
|
|
24
|
+
| `gate` | `boolean` | Az utána következő blokkok védettek; az előnézet megjelöli őket. |
|
|
25
|
+
|
|
26
|
+
A `P` a plugin props-típusa; `Record<string, unknown>`-t kiterjesztő interfészként deklaráld.
|
|
27
|
+
|
|
28
|
+
## Plugin tartalom nélkül
|
|
29
|
+
|
|
30
|
+
Egy linkgomb: felirat, link, méret és szín — mind mezőkben állítható, magába a blokkba semmit sem kell gépelni.
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
// safe-url.ts — csak azok a linkek, amelyeket az oldal megjeleníthet
|
|
34
|
+
export const safeUrl = (u: unknown) => {
|
|
35
|
+
const s = String(u ?? '').trim();
|
|
36
|
+
return /^(https?:|mailto:|\/(?!\/))/.test(s) ? s : '';
|
|
37
|
+
};
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```svelte
|
|
41
|
+
<!-- ButtonView.svelte: a blokk a szerkesztőben -->
|
|
42
|
+
<script lang="ts" module>
|
|
43
|
+
export interface ButtonProps extends Record<string, unknown> {
|
|
44
|
+
label: string;
|
|
45
|
+
url: string;
|
|
46
|
+
size: 'normal' | 'large';
|
|
47
|
+
color: string;
|
|
48
|
+
}
|
|
49
|
+
</script>
|
|
50
|
+
|
|
51
|
+
<script lang="ts">
|
|
52
|
+
import { MousePointerClick } from '@lucide/svelte';
|
|
53
|
+
import { Empty, safeColor, type PluginViewProps } from '@atom-forge/brickee';
|
|
54
|
+
|
|
55
|
+
// Mindkettő bindable, akkor is, ha a nézet nem használja őket: a szerkesztő minden plugin-nézeten bindolja őket.
|
|
56
|
+
let { props = $bindable(), blocks = $bindable() }: PluginViewProps<ButtonProps> = $props();
|
|
57
|
+
</script>
|
|
58
|
+
|
|
59
|
+
{#if props.label}
|
|
60
|
+
<span class="button" style:background={safeColor(props.color, '#2563eb')}>{props.label}</span>
|
|
61
|
+
{:else}
|
|
62
|
+
<Empty icon={MousePointerClick} text="Set the label and the link above" />
|
|
63
|
+
{/if}
|
|
64
|
+
|
|
65
|
+
<style>
|
|
66
|
+
.button {
|
|
67
|
+
display: inline-block;
|
|
68
|
+
padding: 0.5em 1.2em;
|
|
69
|
+
border-radius: 8px;
|
|
70
|
+
color: #fff;
|
|
71
|
+
}
|
|
72
|
+
</style>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
```svelte
|
|
76
|
+
<!-- ButtonPreview.svelte: a blokk az oldalon -->
|
|
77
|
+
<script lang="ts">
|
|
78
|
+
import { safeColor, type PluginPreviewProps } from '@atom-forge/brickee';
|
|
79
|
+
import type { ButtonProps } from './ButtonView.svelte';
|
|
80
|
+
import { safeUrl } from './safe-url';
|
|
81
|
+
|
|
82
|
+
let { props }: PluginPreviewProps<ButtonProps> = $props();
|
|
83
|
+
const href = $derived(safeUrl(props.url));
|
|
84
|
+
</script>
|
|
85
|
+
|
|
86
|
+
{#if href && props.label}
|
|
87
|
+
<p>
|
|
88
|
+
<a class="button" class:large={props.size === 'large'} {href} style:background={safeColor(props.color, '#2563eb')}>
|
|
89
|
+
{props.label}
|
|
90
|
+
</a>
|
|
91
|
+
</p>
|
|
92
|
+
{/if}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
// button.ts: a plugin
|
|
97
|
+
import { MousePointerClick } from '@lucide/svelte';
|
|
98
|
+
import { mdText, type BlockPlugin } from '@atom-forge/brickee';
|
|
99
|
+
import ButtonView, { type ButtonProps } from './ButtonView.svelte';
|
|
100
|
+
import ButtonPreview from './ButtonPreview.svelte';
|
|
101
|
+
import { safeUrl } from './safe-url';
|
|
102
|
+
|
|
103
|
+
export const button: BlockPlugin<ButtonProps> = {
|
|
104
|
+
type: 'button',
|
|
105
|
+
label: 'Button',
|
|
106
|
+
hint: 'A link as a button',
|
|
107
|
+
keys: 'button link cta',
|
|
108
|
+
icon: MousePointerClick,
|
|
109
|
+
props: () => ({ label: '', url: '', size: 'normal', color: '#2563eb' }),
|
|
110
|
+
fields: [
|
|
111
|
+
{ key: 'label', label: 'Label', kind: 'text' },
|
|
112
|
+
{ key: 'url', label: 'Link', kind: 'text', placeholder: 'https://…', parse: (s) => s.trim() },
|
|
113
|
+
{
|
|
114
|
+
key: 'size',
|
|
115
|
+
label: 'Size',
|
|
116
|
+
kind: 'select',
|
|
117
|
+
options: [
|
|
118
|
+
{ value: 'normal', label: 'Normal' },
|
|
119
|
+
{ value: 'large', label: 'Large' }
|
|
120
|
+
]
|
|
121
|
+
},
|
|
122
|
+
{ key: 'color', label: 'Colour', kind: 'color' }
|
|
123
|
+
],
|
|
124
|
+
tag: (p) => (p.size === 'large' ? 'button · large' : 'button'),
|
|
125
|
+
content: 'none',
|
|
126
|
+
markdown: (p) => {
|
|
127
|
+
const href = safeUrl(p.url);
|
|
128
|
+
return href ? `[${mdText(p.label) || href}](${href})` : '';
|
|
129
|
+
},
|
|
130
|
+
view: ButtonView,
|
|
131
|
+
preview: ButtonPreview
|
|
132
|
+
};
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Regisztráld a többi mellé:
|
|
136
|
+
|
|
137
|
+
```svelte
|
|
138
|
+
<Editor bind:value plugins={[...PLUGINS, button]} />
|
|
139
|
+
<Preview blocks={value} plugins={[...PLUGINS, button]} />
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
> **A props a felhasználóktól jön**
|
|
143
|
+
>
|
|
144
|
+
> Egy plugin propsa az, ami el lett tárolva — amit egy szerkesztő begépelt, beillesztett, vagy amit bárki, aki dokumentumot menthet, elküldött az API-dnak. A séma csak az alakot ellenőrzi. Minden előnézetnek megbízhatatlanként kell kezelnie a propsot: a színeket a `safeColor`-on keresztül vedd át, ellenőrizd a linkeket, korlátozd a számokat, a képeket pedig a médialistában keresd ki, ne a tárolt URL-eket használd. A Svelte escape-eli a `{...}`-ban lévő szöveget; propot soha ne tegyél `{@html}`-be.
|
|
145
|
+
|
|
146
|
+
## Mezők
|
|
147
|
+
|
|
148
|
+
Minden `PropField` egy beállítás a blokk tetején. A szerkesztő rajzolja ki őket, és az értéküket a `props`-ban tárolja.
|
|
149
|
+
|
|
150
|
+
| Tag | Jelentés |
|
|
151
|
+
|---|---|
|
|
152
|
+
| `key` | A prop, amelyet szerkeszt. |
|
|
153
|
+
| `label` | A címkéje (a `messages`-en keresztül fordítva). |
|
|
154
|
+
| `kind` | `text`, `textarea`, `color`, `select`, `slider`, `image` vagy `images`. |
|
|
155
|
+
| `placeholder` | Üres szövegmező tippje; opcionális színnél az a szín, amelyről a „none” gombra kattintás indul. |
|
|
156
|
+
| `options` | `{ value, label }[]` a `select`-hez, valamint az értékeken lépkedő `slider`-hez. Egy opció címkéje tartalmazhat `{n}`-t, amelyet az értéke tölt ki. |
|
|
157
|
+
| `min`, `max`, `step`, `unit` | Számcsúszka (`slider`): a tartománya, a lépésköze (alapértelmezés 1) és az érték után mutatott mértékegység. |
|
|
158
|
+
| `none` | A beállítatlan állapot címkéje: számcsúszkánál a `min`-től balra lévő rovátka, opcionális színnél a „none” gomb. |
|
|
159
|
+
| `views` | Nézetenkénti értékek egy `slider`-hez (lásd [Nézetenkénti értékek](host-contexts.md#nézetenkénti-értékek)). |
|
|
160
|
+
| `format` | A mező szövege a tárolt értékből (alapértelmezés: az érték szövegként). |
|
|
161
|
+
| `parse` | A tárolt érték a mező szövegéből (alapértelmezés: maga a szöveg). |
|
|
162
|
+
|
|
163
|
+
Az egyes fajták így tárolják az értéküket:
|
|
164
|
+
|
|
165
|
+
| Fajta | Tárolt érték |
|
|
166
|
+
|---|---|
|
|
167
|
+
| `text`, `textarea` | A szöveg, vagy amit a `parse` visszaad (a `parse: lines` sorok listáját tárolja). |
|
|
168
|
+
| `select` | A kiválasztott opció `value`-ja. |
|
|
169
|
+
| `slider` `options`-szel | A csúszka pozíciójában lévő opció értéke. |
|
|
170
|
+
| `slider` `min`-nel és `max`-szal | A szám szövegként (például `'56'`); a `none` rovátka eltávolítja a kulcsot. |
|
|
171
|
+
| `color` | Egy `#rrggbb` szöveg; `none` esetén a törlése eltávolítja a kulcsot. |
|
|
172
|
+
| `image` | A kiválasztott médiaelem `id`-ja; újbóli kiválasztása eltávolítja. |
|
|
173
|
+
| `images` | Azonosítók tömbje, kiválasztási sorrendben; egy már kiválasztott elem újbóli kiválasztása kiveszi. |
|
|
174
|
+
|
|
175
|
+
Az üres érték (`''`, `null` vagy `undefined`, akkor is, ha a `parse` adja vissza) eltávolítja a kulcsot a `props`-ból, ezért az előnézetnek mindig kezelnie kell a hiányzó propot. A mező `parse`-a jó hely a bemenet normalizálására is: a mellékelt YouTube-mező bármilyen YouTube-linket elfogad, de csak a videó azonosítóját tárolja.
|
|
176
|
+
|
|
177
|
+
## A nézet
|
|
178
|
+
|
|
179
|
+
A nézet `PluginViewProps`-ot kap:
|
|
180
|
+
|
|
181
|
+
| Prop | Jelentés |
|
|
182
|
+
|---|---|
|
|
183
|
+
| `props` | A blokk propsa (bindable): a nézet helyben is szerkesztheti, ahogy a táblázat teszi. |
|
|
184
|
+
| `blocks` | A beágyazott dokumentum (bindable); tartalom nélküli pluginnál mindig `[]`. |
|
|
185
|
+
| `readonly` | A szerkesztő csak olvasható. |
|
|
186
|
+
| `palette`, `plugins` | Az alkalmazás palettája (már az `accepts`-re szűkítve) és pluginjai, egy beágyazott szerkesztőhöz. |
|
|
187
|
+
|
|
188
|
+
A `props`-ot és a `blocks`-ot akkor is `$bindable()`-lel deklaráld, ha a nézet nem használja őket. A mezők automatikusan a nézet fölé kerülnek; a nézetnek csak a blokkot kell megjelenítenie. Az `Empty` (`icon` és `text` propokkal) az a szaggatott helyőrző, amelyet a mellékelt pluginok mutatnak, amíg a propsuk nincs beállítva; a szövegét lefordítja.
|
|
189
|
+
|
|
190
|
+
## Az előnézet
|
|
191
|
+
|
|
192
|
+
Az előnézet `PluginPreviewProps`-ot kap: `props`, `blocks` és `plugins`. Ez egy egyszerű Svelte-komponens, amely az oldal számára rendereli a blokkot. A média, a szövegek és a nézet a kontextusokon keresztül érhető el (`useMedia`, `useText`, `useView`; lásd [Az alkalmazás kontextusai](host-contexts.md)).
|
|
193
|
+
|
|
194
|
+
## Tárolók
|
|
195
|
+
|
|
196
|
+
A `content: 'blocks'` beállítású plugin beágyazott dokumentumot tart a `blocks`-ban. A nézete a `Frame`-et használja, egy vékony dobozt, amely a tetején a blokk mezőit, alatta egy beágyazott szerkesztőt rajzol; az előnézete egy beágyazott `Preview`-val rendereli a belső blokkokat.
|
|
197
|
+
|
|
198
|
+
```svelte
|
|
199
|
+
<!-- NoteView.svelte -->
|
|
200
|
+
<script lang="ts" module>
|
|
201
|
+
export interface NoteProps extends Record<string, unknown> {
|
|
202
|
+
title: string;
|
|
203
|
+
}
|
|
204
|
+
</script>
|
|
205
|
+
|
|
206
|
+
<script lang="ts">
|
|
207
|
+
import { Frame, useText, type PluginViewProps } from '@atom-forge/brickee';
|
|
208
|
+
|
|
209
|
+
let { props = $bindable(), blocks = $bindable(), readonly, palette, plugins }: PluginViewProps<NoteProps> = $props();
|
|
210
|
+
const tr = useText();
|
|
211
|
+
</script>
|
|
212
|
+
|
|
213
|
+
<Frame bind:blocks {readonly} {palette} {plugins} heading={props.title} empty={tr('Note')} placeholder={tr('Write the note…')} />
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
```svelte
|
|
217
|
+
<!-- NotePreview.svelte -->
|
|
218
|
+
<script lang="ts">
|
|
219
|
+
import { Preview, type PluginPreviewProps } from '@atom-forge/brickee';
|
|
220
|
+
import type { NoteProps } from './NoteView.svelte';
|
|
221
|
+
|
|
222
|
+
let { props, blocks, plugins }: PluginPreviewProps<NoteProps> = $props();
|
|
223
|
+
</script>
|
|
224
|
+
|
|
225
|
+
<aside class="note">
|
|
226
|
+
{#if props.title}<p class="note-title">{props.title}</p>{/if}
|
|
227
|
+
<Preview {blocks} {plugins} nested />
|
|
228
|
+
</aside>
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
```ts
|
|
232
|
+
// note.ts
|
|
233
|
+
import { StickyNote } from '@lucide/svelte';
|
|
234
|
+
import { mdJoin, mdQuote, mdText, type BlockPlugin } from '@atom-forge/brickee';
|
|
235
|
+
import NoteView, { type NoteProps } from './NoteView.svelte';
|
|
236
|
+
import NotePreview from './NotePreview.svelte';
|
|
237
|
+
|
|
238
|
+
export const note: BlockPlugin<NoteProps> = {
|
|
239
|
+
type: 'note',
|
|
240
|
+
label: 'Note',
|
|
241
|
+
hint: 'Boxed text with a title',
|
|
242
|
+
keys: 'note aside box',
|
|
243
|
+
icon: StickyNote,
|
|
244
|
+
props: () => ({ title: '' }),
|
|
245
|
+
fields: [{ key: 'title', label: 'Title', kind: 'text' }],
|
|
246
|
+
tag: () => 'note',
|
|
247
|
+
content: 'blocks',
|
|
248
|
+
accepts: ['md:p', 'md:ul', 'md:ol', 'youtube'],
|
|
249
|
+
markdown: (p, { inner }) => mdQuote(mdJoin(p.title && `**${mdText(p.title)}**`, inner)),
|
|
250
|
+
view: NoteView,
|
|
251
|
+
preview: NotePreview
|
|
252
|
+
};
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
A `Frame` propsai: `blocks` (bindable), `readonly`, `palette`, `plugins`, és opcionálisan `placeholder` a beágyazott szerkesztőhöz. A `heading`, az `empty` és az `image` (egy URL) címsort hoz létre, amely csak akkor látszik, ha a mezők nem (csak olvasható módban, vagy ha nincsenek mezők).
|
|
256
|
+
|
|
257
|
+
Hogyan működik a beágyazás:
|
|
258
|
+
|
|
259
|
+
- **Egy szint.** A beágyazott szerkesztő soha nem kínál olyan blokkot, amely maga is blokkokat tartalmaz, sem egyedi blokkot. A séma elutasítja a mélyebb dokumentumokat.
|
|
260
|
+
- Az **`accepts`** a felsorolt palettaazonosítókra szűkíti azt, amit a beágyazott szerkesztő kínál, az alkalmazás sorrendjében. Az `'md:*'` az összes beépített blokkot jelenti, így a `['md:*', 'youtube']` jelentése „szöveg és videók”. `accepts` nélkül a beágyazott szerkesztő mindent kínál, amit az alkalmazás (a tárolók és az egyedi blokkok kivételével).
|
|
261
|
+
- Az alkalmazás `palette`-je továbbra is érvényes: az `accepts` csak szűkítheti, soha nem bővítheti.
|
|
262
|
+
- Blokkok tárolóba csomagolását az „Átalakítás” menüből, illetve egy tároló másikká alakítását csak akkor kínálja fel, ha a tároló minden bekerülő blokkot elfogad.
|
|
263
|
+
- A `blocksSchemaFor(plugins)` a szerveren ellenőrzi az `accepts`-et (lásd [A szerveren](server-side.md)).
|
|
264
|
+
|
|
265
|
+
## Egyedi és kapus blokkok
|
|
266
|
+
|
|
267
|
+
- **`unique: true`** — dokumentumonként legfeljebb egy, a legfelső szinten. Amint a dokumentumban van egy, a plugin eltűnik a perjeles és az „Átalakítás” menüből; beágyazott szerkesztő soha nem kínálja.
|
|
268
|
+
- **`gate: true`** — az első legfelső szintű kapus blokk utáni blokkok védettek. A `Preview` egy „For supporters only” jelölésű, szaggatott vonallal elválasztott szakaszban rendereli őket; a `markGated={false}` kikapcsolja a jelölést. A beágyazott előnézetek soha nem osztódnak ketté.
|
|
269
|
+
|
|
270
|
+
Mindkettőre tipikus példa egy csak támogatóknak szóló elválasztó: dokumentumonként egy, mögötte a védett tartalommal.
|
|
271
|
+
|
|
272
|
+
> **A kapu csak jelöl**
|
|
273
|
+
>
|
|
274
|
+
> A `gate` semmit sem rejt el: az előnézet továbbra is minden blokkot renderel, és a tárolt dokumentum is mindet tartalmazza. Annak eldöntése, hogy ki olvashatja a védett részt — és hogy mindenki más elől kimaradjon az oldalról —, az alkalmazás feladata, a szerveren (lásd [Védett tartalom](server-side.md#védett-tartalom)). A `unique`-ot a séma sem kényszeríti ki.
|
|
275
|
+
|
|
276
|
+
## Markdown alak
|
|
277
|
+
|
|
278
|
+
A `markdown(props, { inner, media })` markdownként adja vissza a blokkot; ezt használja a szerkesztő blokkok másolásakor, és a `toMarkdown`:
|
|
279
|
+
|
|
280
|
+
- `inner` — a beágyazott blokkok, már markdownként (`''`, ha nincsenek);
|
|
281
|
+
- `media` — a dokumentum médiája, hogy egy kép azonosítóját a `findMedia(media, id)?.url`-lel URL-lé alakíthasd.
|
|
282
|
+
|
|
283
|
+
`''` visszaadásával kihagyod a blokkot. Azoknak a pluginoknak, amelyek kimenetének szövegként nincs értelme (hirdetéshely, a mellékelt `gap`), egyszerűen nincs markdown alakjuk. Három segédfüggvény gondoskodik a jól formált kimenetről:
|
|
284
|
+
|
|
285
|
+
| Segédfüggvény | Mit csinál |
|
|
286
|
+
|---|---|
|
|
287
|
+
| `mdText(value)` | Markdownban biztonságos egyszerű szöveg: escape-eli a soron belüli jelöléseket és a `#`-et, összevonja a sorokat. |
|
|
288
|
+
| `mdJoin(...parts)` | Különálló blokkokként fűzi össze a részeket (köztük üres sorral), kihagyva az üreseket és a hamis értékűeket. |
|
|
289
|
+
| `mdQuote(md)` | Minden sor elé `> `-t tesz, idézetblokként renderelt dobozhoz. |
|
|
290
|
+
|
|
291
|
+
## A kit
|
|
292
|
+
|
|
293
|
+
| Export | Fajta | Használat |
|
|
294
|
+
|---|---|---|
|
|
295
|
+
| `Frame` | komponens | Egy tároló szerkesztőbeli kinézete: felül a mezők, alatta a beágyazott szerkesztő. |
|
|
296
|
+
| `Empty` | komponens | Olyan blokk helyőrzője, amelynek a propsa még nincs beállítva. |
|
|
297
|
+
| `safeColor(value, fallback)` | függvény | Egy `#hex` szín (3–8 számjegy), vagy a tartalék érték. |
|
|
298
|
+
| `lines(text)` | függvény | Levágott, nem üres sorok: a mező `parse`-a „soronként egy” listákhoz. |
|
|
299
|
+
| `baseValue(value)` | függvény | Egy nézetenkénti prop alapértéke. |
|
|
300
|
+
| `viewValues(value, keys)` | függvény | Egy nézetenkénti prop értéke minden nézetre. |
|
|
301
|
+
| `mdText`, `mdJoin`, `mdQuote` | függvények | Markdown alakok (fent). |
|
|
302
|
+
| `useMedia`, `findMedia` | függvények | A dokumentum képei (lásd [Az alkalmazás kontextusai](host-contexts.md)). |
|
|
303
|
+
| `useText` | függvény | Lefordítja a plugin saját felületi szövegeit. |
|
|
304
|
+
| `useView` | függvény | Az alkalmazás által éppen mutatott nézet. |
|
|
305
|
+
| `Preview` | komponens | Egy tároló beágyazott blokkjait rendereli (`nested`-del). |
|
package/package.json
CHANGED
|
@@ -1,6 +1,111 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@atom-forge/brickee",
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"author": {
|
|
5
|
+
"name": "Gergely Laborci",
|
|
6
|
+
"url": "https://github.com/laborci"
|
|
7
|
+
},
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/atom-forge/brickee.git"
|
|
11
|
+
},
|
|
12
|
+
"description": "A Svelte 5 block editor: markdown blocks plus plugins, stored as JSON",
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"scripts": {
|
|
15
|
+
"dev": "vite dev",
|
|
16
|
+
"build": "vite build && bun run prepack",
|
|
17
|
+
"preview": "vite preview",
|
|
18
|
+
"prepare": "svelte-kit sync || echo ''",
|
|
19
|
+
"prepack": "(svelte-kit sync || true) && svelte-package && publint",
|
|
20
|
+
"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
|
|
21
|
+
"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
|
|
22
|
+
"package": "svelte-package",
|
|
23
|
+
"prepublishOnly": "bun run prepack",
|
|
24
|
+
"pub-check": "ship-it check",
|
|
25
|
+
"pub": "ship-it",
|
|
26
|
+
"pub-validate": "ship-it validate"
|
|
27
|
+
},
|
|
28
|
+
"ship": {
|
|
29
|
+
"verify": [
|
|
30
|
+
"bun run check",
|
|
31
|
+
"bun run prepack",
|
|
32
|
+
"npm pack --dry-run --ignore-scripts"
|
|
33
|
+
]
|
|
34
|
+
},
|
|
35
|
+
"files": [
|
|
36
|
+
"dist",
|
|
37
|
+
"!dist/**/*.test.*",
|
|
38
|
+
"!dist/**/*.spec.*",
|
|
39
|
+
"README.md",
|
|
40
|
+
"README-AI.md",
|
|
41
|
+
"docs",
|
|
42
|
+
"LICENSE",
|
|
43
|
+
"CHANGELOG.md"
|
|
44
|
+
],
|
|
45
|
+
"svelte": "./dist/index.js",
|
|
46
|
+
"types": "./dist/index.d.ts",
|
|
47
|
+
"type": "module",
|
|
48
|
+
"sideEffects": [
|
|
49
|
+
"**/*.css"
|
|
50
|
+
],
|
|
51
|
+
"exports": {
|
|
52
|
+
".": {
|
|
53
|
+
"types": "./dist/index.d.ts",
|
|
54
|
+
"svelte": "./dist/index.js",
|
|
55
|
+
"default": "./dist/index.js"
|
|
56
|
+
},
|
|
57
|
+
"./plugins": {
|
|
58
|
+
"types": "./dist/plugins/index.d.ts",
|
|
59
|
+
"svelte": "./dist/plugins/index.js",
|
|
60
|
+
"default": "./dist/plugins/index.js"
|
|
61
|
+
},
|
|
62
|
+
"./schema": {
|
|
63
|
+
"types": "./dist/schema.d.ts",
|
|
64
|
+
"default": "./dist/schema.js"
|
|
65
|
+
},
|
|
66
|
+
"./model": {
|
|
67
|
+
"types": "./dist/model.d.ts",
|
|
68
|
+
"default": "./dist/model.js"
|
|
69
|
+
},
|
|
70
|
+
"./locales/*": {
|
|
71
|
+
"types": "./dist/locales/*.d.ts",
|
|
72
|
+
"default": "./dist/locales/*.js"
|
|
73
|
+
}
|
|
74
|
+
},
|
|
75
|
+
"peerDependencies": {
|
|
76
|
+
"@atom-forge/ui": ">=0.0.37",
|
|
77
|
+
"@lucide/svelte": ">=1.0.0",
|
|
78
|
+
"svelte": "^5.0.0",
|
|
79
|
+
"zod": "^4.0.0"
|
|
80
|
+
},
|
|
81
|
+
"peerDependenciesMeta": {
|
|
82
|
+
"zod": {
|
|
83
|
+
"optional": true
|
|
84
|
+
}
|
|
85
|
+
},
|
|
86
|
+
"devDependencies": {
|
|
87
|
+
"@atom-forge/ship": "0.2.0",
|
|
88
|
+
"@atom-forge/ui": "^0.0.37",
|
|
89
|
+
"@lucide/svelte": "^1.59.0",
|
|
90
|
+
"@sveltejs/adapter-auto": "^7.0.0",
|
|
91
|
+
"@sveltejs/kit": "^2.50.2",
|
|
92
|
+
"@sveltejs/package": "^2.5.7",
|
|
93
|
+
"@sveltejs/vite-plugin-svelte": "^6.2.4",
|
|
94
|
+
"publint": "^0.3.15",
|
|
95
|
+
"svelte": "^5.57.1",
|
|
96
|
+
"svelte-check": "^4.4.2",
|
|
97
|
+
"typescript": "^5.9.3",
|
|
98
|
+
"vite": "^7.3.1",
|
|
99
|
+
"zod": "^4.6.7"
|
|
100
|
+
},
|
|
101
|
+
"keywords": [
|
|
102
|
+
"svelte",
|
|
103
|
+
"block-editor",
|
|
104
|
+
"markdown",
|
|
105
|
+
"editor"
|
|
106
|
+
],
|
|
107
|
+
"publishConfig": {
|
|
108
|
+
"access": "public",
|
|
109
|
+
"registry": "https://registry.npmjs.org"
|
|
110
|
+
}
|
|
111
|
+
}
|