@atom-forge/brickee 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,123 @@
+# Recipes and pitfalls
+
+[← Previous](server-side.md) · [Contents](index.md) · [Next →](upgrading.md)
+
+## One place for the block setup
+
+Keep the plugins, palettes and messages of an application in one module, and wrap the editor in a component of your own. Pages then use the wrapper and never repeat the setup.
+
+```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
+];
+
+/** The full palette, for editors of the site's own pages. */
+export const PAGE_PALETTE = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)];
+
+/** A smaller one, for user comments. */
+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} />
+```
+
+Render the published page with `<Preview blocks={doc} {plugins} {messages} />` and the same `plugins`, so a block looks the same in the editor's preview and on the site.
+
+## Copying the whole document as markdown
+
+Copying selected blocks already puts markdown on the clipboard. For a "Copy as markdown" button for the whole document:
+
+```svelte
+<script lang="ts">
+	import { fromStored, toMarkdown, type StoredBlock } from '@atom-forge/brickee';
+	import { plugins } from './blocks';
+
+	let { doc }: { doc: StoredBlock[] } = $props();
+
+	// Runs in a click handler, so the browser-only toMarkdown is safe here.
+	const copy = () => navigator.clipboard.writeText(toMarkdown(doc.map(fromStored), { plugins }));
+</script>
+
+<button type="button" onclick={copy}>Copy as markdown</button>
+```
+
+## Starting a document from markdown
+
+```ts
+import { fromMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
+
+// In the browser: toStored reads the inline HTML through the DOM.
+export const fromText = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
+```
+
+Remember that every non-empty line becomes its own block.
+
+## Developing against a local copy
+
+When you link a local checkout of the package into an application (`bun link`), the linked folder brings its own `node_modules`. Make Vite use the application's single copy of the shared packages, otherwise Svelte contexts — the popup manager, the theme — are not found across the two copies:
+
+```ts
+// vite.config.ts of the application
+export default defineConfig({
+	plugins: [sveltekit()],
+	resolve: {
+		dedupe: ['svelte', '@atom-forge/ui', '@lucide/svelte', 'zod']
+	}
+});
+```
+
+The application reads the package's built `dist/`, so rebuild the package after each change.
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Block fields and popups look unstyled | The `@atom-forge/ui` theme CSS or its Tailwind `@source` is missing | Set up `@atom-forge/ui` as its documentation describes and render the app beneath its `Root`. |
+| Block handles stick out on the left | The handles are drawn left of the editor's box | Give the element around the editor about 22 px of left padding. |
+| Popups do not open, or "context not found" errors with a linked package | Two copies of `svelte` or `@atom-forge/ui` | Add them to Vite's `resolve.dedupe`. |
+| A plugin block shows "Unknown block" | Its plugin is missing from `plugins` | Pass the same plugins to every editor and preview of a document type. |
+| A block is missing from `Preview` | Its plugin has no `preview` | Give the plugin a `preview` (the bundled ones have a default), or render the block with your own renderer. |
+| A plugin block is missing from the site | The preview got other `plugins` | Use the same plugin list for the editor and the preview. |
+| An image block renders nothing | Its preview rejects the stored address, or the app's own lookup does not know the stored id | Store addresses the preview accepts (`http(s)` or site-relative); resolve ids from the same data in the editor and on the site. |
+| A box cannot be put inside another box | Nested editors go one level deep | Design containers to hold content blocks, not other containers. |
+| A block is not offered inside a container | Its `accepts` or the host `palette` leaves it out | Add the palette id to `accepts` (or use `'md:*'` for every built-in). |
+| A unique block appears twice | The schema does not enforce `unique` | Check it on the server if your application relies on it. |
+| Gated content visible to everyone | `gate` only marks the blocks | Cut the document on the server before rendering. |
+| `document is not defined` | `toMarkdown` or `toStored` ran during SSR | Call them in the browser only. |
+| A colour or link from props breaks the page | Props are user input | Use `safeColor`, check links, never use `{@html}` with props. |
+| Overridden plugin loses its blocks | Its `type` was changed | Keep `type` when spreading a plugin. |
+| `bind:blocks` error in a custom view | `props` or `blocks` not declared bindable | Declare both with `$bindable()`. |
+| The value is never an empty array | The editor shows (and writes) one empty paragraph for an empty document | Treat a document with only empty paragraphs as empty, for example with `blocksToPlainText(doc).trim() === ''`. |
+| The preview does not follow the editor's scrolling | The actions are not on the boxes that scroll | Put `use:sync.source` / `use:sync.target` on the `overflow` boxes themselves. |

package/docs/en/server-side.md

@@ -0,0 +1,95 @@
+# On the server
+
+[← Previous](host-contexts.md) · [Contents](index.md) · [Next →](recipes-and-pitfalls.md)
+
+A stored document is JSON sent by the browser, so the server must check it before saving. Two entry points have no Svelte dependency and are meant for server code:
+
+- `@atom-forge/brickee/model` — `StoredBlock`, `MD`, `MAX_INDENT`, `MAX_DEPTH`, `isMd`, `acceptsId`, `inlineToPlainText`, `blocksToPlainText`;
+- `@atom-forge/brickee/schema` — `blocksSchema` and `blocksSchemaFor`, built with `zod` (an optional peer dependency: install it to use this entry point).
+
+## Validating a document
+
+```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[]
+}
+```
+
+`blocksSchema` checks the shape of any document; `blocksSchemaFor(plugins)` adds the containers' `accepts` lists. It needs only `type` and `accepts` of each plugin, so a server that does not want to import the plugin components can pass those alone:
+
+```ts
+const contentSchema = blocksSchemaFor([
+	{ type: 'note', accepts: ['md:*', 'youtube'] },
+	{ type: 'youtube' }
+]);
+```
+
+What the schema checks:
+
+| Rule | Limit |
+|---|---|
+| Block keys | `type`, `indent`, `text`, `props`, `blocks` only (strict objects). |
+| `type` | `^[a-z][a-z0-9:-]{0,39}$` |
+| `indent` | An integer, 0–6. |
+| `text` | At most 100 000 characters. |
+| `props` | Keys up to 60 characters, JSON values. |
+| `blocks` | At most 500 nested blocks per container, one level deep only. |
+| Document | At most 2000 top-level blocks and 1 000 000 characters as JSON. |
+| `accepts` (`blocksSchemaFor`) | Every nested block is one its container takes. |
+
+What it does **not** check: whether a type is known, whether a unique block appears once, and what the props contain. Add your own refinements for the rules your application relies on — for example, to reject unknown block types:
+
+```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.');
+```
+
+> **Shape, not safety**
+>
+> The schema keeps documents well-formed and bounded; it does not make props safe to render. The renderers escape every text and keep links to safe schemes, and each plugin preview must sanitize its own props (see [Writing plugins](writing-plugins.md)).
+
+## Plain text
+
+`blocksToPlainText(blocks)` collects every text of a document in order, separated by blank lines: block texts with their marks and link targets removed, string props that contain whitespace (titles, captions — not ids or colours), table rows, and nested blocks. Use it for search indexes, leads and meta descriptions. `inlineToPlainText(md)` does the same for a single inline markdown string.
+
+```ts
+import { blocksToPlainText, type StoredBlock } from '@atom-forge/brickee/model';
+
+export const description = (doc: StoredBlock[]) => blocksToPlainText(doc).slice(0, 160);
+```
+
+## Rendering
+
+`Preview` is an ordinary Svelte component and can be server-rendered; the core renderer and the bundled previews use no browser APIs. Only the markdown export path (`toMarkdown`, `toStored`) needs the browser.
+
+## Gated content
+
+A gate block (a plugin with `gate: true`, such as a supporters-only divider) only makes the preview mark the blocks after it. To keep the gated part from readers who may not see it, cut the document on the server before it reaches the page:
+
+```ts
+import type { StoredBlock } from '@atom-forge/brickee/model';
+
+/** The document up to and including the first gate block, for readers without access. */
+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);
+}
+```
+
+Call it with your gate plugin types (for example `['paywall']`) and the reader's access. Readers without access see the content up to the gate block and its teaser; readers with access get the whole document, and the preview marks the gated part for them.

package/docs/en/upgrading.md

@@ -0,0 +1,71 @@
+# Upgrading
+
+[← Previous](recipes-and-pitfalls.md) · [Contents](index.md)
+
+This chapter lists the changes that may require action when you move to a newer version of `@atom-forge/brickee`. Each section covers one version step, newest first, and each change ends with a **What to do:** paragraph.
+
+Changes that need no action from you — new exports, fixes, documentation updates — are listed only in the changelog (`CHANGELOG.md`, shipped with the package).
+
+## From 0.0.1 to 0.0.2
+
+### Images and media are no longer part of the package
+
+The package has no notion of images any more. Whether a block stores an image's URL or an id, how the user picks the image, and how the stored value becomes an address are decided by the application's own image plugin (see [Images](writing-plugins.md#images)).
+
+| Removed | Was |
+|---|---|
+| `kind: 'image'`, `kind: 'images'` | Field kinds that stored the id (or ids) of a picked media item, with the built-in image picker popup |
+| `media` prop of `Editor` and `Preview` | The images blocks could pick from and refer to |
+| `provideMedia`, `useMedia`, `findMedia`, `MediaItem` | The media context, its lookup and its type |
+| `media` option of `toMarkdown` | `toMarkdown(blocks, { plugins, media })` is now `toMarkdown(blocks, { plugins })` |
+| `ctx.media` in a plugin's `markdown(props, ctx)` | `MarkdownContext` is now `{ inner }` |
+
+`PropField['kind']` is now `'text' | 'textarea' | 'color' | 'select' | 'slider'`. Stored documents are unaffected: a block's props keep whatever they stored, ids included.
+
+**What to do:** in your image plugins, replace each `image` or `images` field with your own picking — a button in the plugin's view that opens your media dialog or an upload and writes the result into `props`, or a plain `text` field for a URL — and keep the prop keys, so stored documents still load. Remove the `media` prop from your editors and previews, and the `media` option from your `toMarkdown` calls. Where a view, a preview or a `markdown` form turned an id into an address with `useMedia`, `findMedia` or `ctx.media`, look it up in your application's own data instead: a module of your app, or a Svelte context of your own provided above the editor and the preview (`markdown` runs outside components, so it needs module data). Define a `MediaItem`-like type in your app if you still need one.
+
+## From the `block-editor` workspace package to 0.0.1
+
+This section is only for applications that used the editor before it became this package.
+
+The editor started as `block-editor`, a workspace package inside an application. It moved here as `@atom-forge/brickee` with the same stored form, so saved documents need no conversion. The import specifiers changed, the plugin kit moved from the plugins entry point into the core, and the site-specific plugins stayed with the application.
+
+### Package name and entry points
+
+| Before | After |
+|---|---|
+| `block-editor` | `@atom-forge/brickee` |
+| `block-editor/plugins` | `@atom-forge/brickee/plugins` |
+| `block-editor/locales/hu` | `@atom-forge/brickee/locales/hu` |
+
+**What to do:** replace the dependency (`"block-editor": "workspace:*"` → `"@atom-forge/brickee"`) and rename the imports. Install `@atom-forge/ui` and `@lucide/svelte` as dependencies of the application if they are not already, and `zod` if you use the schema.
+
+### The kit lives in the core
+
+`Frame`, `Empty` and the plugin helpers are exported from the core entry point. `safeColor`, `viewValues`, `baseValue` and `lines` are no longer exported from the plugins entry point.
+
+```ts
+// Before
+import { safeColor, viewValues } from 'block-editor/plugins';
+
+// After
+import { safeColor, viewValues } from '@atom-forge/brickee';
+```
+
+**What to do:** import `Frame`, `Empty`, `safeColor`, `viewValues`, `baseValue`, `lines`, `mdText`, `mdJoin` and `mdQuote` from `@atom-forge/brickee`. The helpers of the bundled plugins that remain (`youtubeId`, `mapSrc`, `gapLines`, `tableHeads`…) stay in `@atom-forge/brickee/plugins`.
+
+### Site-specific plugins are no longer in the package
+
+The package now bundles only four general-purpose plugins: `table`, `youtube`, `map` and `gap` (`PLUGINS` holds these four). The other plugins of `block-editor/plugins` and their helpers were application-specific and are not part of `@atom-forge/brickee`:
+
+| Removed | Kind |
+|---|---|
+| `richBox`, `feature`, `sideBox`, `callout`, `spoiler`, `faq`, `imageText` | container plugins |
+| `image`, `gallery`, `tweet`, `form`, `banner`, `locked` | plugins |
+| `CALLOUTS`, `calloutTone`, `CalloutTone`, `questions`, `formEmbed`, `formHeight` | their helpers |
+| `postId`, `userName`, `RATIO_MIN`, `RATIO_MAX`, `ratioPercent`, `ratio` | helpers of the former `plugins/util` |
+| `ImageProps`, `GalleryProps`, `CalloutProps` and the other props types of these plugins | types |
+
+The stored form is unchanged: documents that contain these block types stay valid, as long as the application still passes plugins with the same `type` values to the editor and the preview.
+
+**What to do:** if the application uses any of these plugins, keep its own copy of them (their views, previews and helpers) in the application, written against the core kit, and add them to its plugin list with the same `type`. Import the four remaining plugins and their helpers from `@atom-forge/brickee/plugins` as before. Add the UI text of the copied plugins to your `messages`: `@atom-forge/brickee/locales/hu` no longer contains it.