@atom-forge/brickee 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -7,9 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.3] - 2026-11-11
+
+### Added
+
+- Table cells show their text formatted (bold, italic, code, links…) while they are not edited, instead of the raw markdown; while editing, `Ctrl/Cmd` + `B`, `I`, `E`, `Shift+X` and `K` wrap the selected text in the mark (a link with its address selected to type over).
+- Touch and keyboard: *Move up* / *Move down* in the Turn-into menu (moving without dragging); the Turn-into menu opens from the keyboard (`/`, `Ctrl/Cmd+/`, the menu key or `Shift+F10` on selected blocks, `Ctrl/Cmd+/` in a block's text); on a touch screen a tapped block shows its actions beside its handle; the handle is a button (with a label for screen readers) and its actions also show on focus.
+- Files pasted into the editor or dropped on it from outside the page go to a plugin that takes them: the new optional `BlockPlugin.fromFiles(files)` returns the block's props (or a promise of them, after its own upload) or `null` for the next plugin. A drop line shows where a dropped file lands; the step is undoable.
+- Formatted paste: text pasted from a web page, Google Docs or Word keeps its headings, paragraphs, lists (nested, numbered, to-dos), quotes, code, rules, tables (for a plugin that takes them) and inline marks, instead of arriving as plain text. Exported as `fromHtml(html, { plugins })` (browser only); it reads the HTML through markdown, so the result is as safe as any other text.
+- Pasting or importing a GFM table: `fromMarkdown(text, { plugins })` gives it to the first plugin with the new `BlockPlugin.fromTable(table: MarkdownTable)`, which returns the block's props; the bundled `table` takes them, so a table pasted into an editor that offers it becomes a table block.
+- A numbered list keeps its start number (`props.start` on its first `md:ol` item): read from markdown (`5. …`), numbered from it in the editor and the preview (`<ol start>`), and written back.
+- Tests for the markdown conversions (`bun run test`, vitest), run by the release checks, the publish workflow and a new test workflow on every push and pull request (type check, tests, package).
+- Code review findings and a staged fix plan in `notes/` (not shipped), linked from `TODO.md`.
+- Development tools (not shipped): `scripts/shots.mjs` and `scripts/shots-diff.mjs` photograph the editor's looks in light and dark mode from the dev pages (`/dev/states`, `/dev/perf`) and compare two sets pixel by pixel; `<style lang="scss">` is enabled (compiled at build time, so `dist/` holds plain CSS).
+
 ### Changed
-- Configure releases with Ship.
 
+- The undo history shares unchanged blocks between its steps: a step costs only the blocks that changed, not a copy of the whole document (in a 2000-block document about 320 KB a step before, 300 steps kept).
+- The editor's accent (selection, active menu row, checked to-do, links, the focused table cell, the toggles) follows the `@atom-forge/ui` theme's accent colour instead of a fixed blue (blue remains the fallback), and the editor and the table use the page's typeface (the editor keeps its 17px size), so they read like the preview beside them.
+- **Breaking:** the editor is styled with Tailwind classes (with the `@atom-forge/ui` theme's colours) and SCSS instead of scoped CSS, so a host must add the package's `dist` folder as a Tailwind `@source`, like the `@atom-forge/ui` one; otherwise the editor loses its look. The preview is unaffected (its styles still travel with its markup). The slash and turn-into menus and the formatting bar are their own components, and the undo history its own class. See the upgrading chapter.
+- The editor's internal context keys are `brickee:*` (were `block-editor:*`); an "Unknown block" note is translatable (`Unknown block: {type}`, also in the Hungarian locale).
+- `fromMarkdown` reads much more of CommonMark and GFM: fences of any length and `~~~` (closed only by a fence at least as long), indented code, setext headings and closing `#`s, nested quotes, list nesting by the items' markers (also under `1. ` and with four-space indents), reference links, footnotes (as superscripts), and the lines of a paragraph, list item or quote as one block with line breaks instead of one block per line.
+- `inline` reads `_italic_`, `__bold__` and `***both***` (now valid HTML), code spans of any backtick length, link targets with balanced parentheses and titles, `<https://…>` autolinks, images (as links), every ASCII punctuation escape, and inline HTML (marks kept, other tags dropped). A stored text with a word wrapped in single underscores (`_word_`) now shows it in italics.
+- Typing converts only the edited block to its stored form: the other blocks keep their objects in `value`, so the editor and a `<Preview>` beside it do much less work per keystroke (a 2000-block document with a preview: about 50 ms → 33 ms per keystroke). A document from outside is reloaded when `value` is replaced with a new array that differs from the current one; changing the array in place is not picked up.
+- `toMarkdown` writes markdown other readers read the same way: items nested under a numbered item indented to its content, code fenced longer than any backtick run in it, consecutive quotes as one quote, line breaks as a backslash at the line's end, `_` and line starts that would read as markup escaped.
+
+### Removed
+
+- **Breaking:** gate blocks — gating content is the application's concept, not the editor's. Removed: `BlockPlugin.gate`, the `Preview`'s `markGated` prop and its "For supporters only" section (`.supporters`, `.supporters-label`), and that text in the Hungarian locale; the `Preview` renders every block. `unique` stays. See the upgrading chapter.
+
+### Fixed
+
+- The slash menu, the turn-into menu, the formatting bar and the link prompt open where they belong when the editor sits in a transformed parent (an animated drawer or dialog); they live in the body now, placed against the viewport.
+- The table block fills the width of the editor on pages that use Tailwind: its root's class `table` collided with Tailwind's `table` utility (`display: table`), which shrank it to its content.
+- A server-rendered editor shows its blocks' text (it was empty until the page's script ran, so a read-only editor showed nothing without JavaScript). A test renders the editor and the preview on the server, and the test workflow builds the showcase site (which prerenders every page).
+- An editor or a table removed in the middle of a block sweep, a drag or typing leaves no window listener or timer behind.
+- Copying and pasting blocks keeps plugin blocks: the clipboard carries the blocks themselves (`application/x-brickee+json`) beside their markdown, so a copied video, table, gap or box is pasted back as that block instead of a link or nothing; an editor that does not offer the plugin (or already has a unique one) gets its markdown form. An empty block takes pasted plugin blocks in its place, and pasting while blocks are selected inserts after them.
+- Changes made in a plugin's view are undoable: table cells, rows and columns, and the blocks of a nested editor (a box) are undo steps of the editor around them, and Ctrl+Z / Ctrl+Shift+Z in a table cell undo and redo there instead of the cell's own short-lived history. A document loaded from outside starts a fresh history.
+- A read-only editor no longer writes its normalized document back into `value` on mount, so a host does not see a change nobody made.
+- Inline markdown and `fromMarkdown` stay fast on hostile text: many unclosed HTML tags, a long run of `[`, unclosed `**` or `_`, or long runs of spaces could freeze the tab for seconds to minutes; every pattern is now linear (100 000 characters take milliseconds). Limits that come with it: a marked span is at most 2000 characters, a link label has no brackets of its own (at most 1000 characters), a link target at most 2000. Inline HTML marks are now always balanced (an unclosed `<b>` is closed, a stray closing tag dropped).
+
+## [0.0.2] - 2026-11-10
+
+### Added
+
+- Showcase site in `src/routes` (`bun run dev`), styled like the `@atom-forge/ui` site: a playground (editor beside its preview, stored JSON and markdown), the guide (editor and preview, split view, markdown, stored form and schema), a page per bundled plugin, writing, nesting and overriding plugins, image blocks, and the host contexts (per-view values, code languages, localisation), each with live examples and their code. It resolves `@atom-forge/brickee` to the local source and prerenders to `build/` (`@sveltejs/adapter-static`); it is not part of the npm package.
+- A `toggles` field kind (`PropField`): a row of icon buttons, each switching one of `options` on or off (`options[].icon` is the button, `label` its tooltip), stored as the list of the ones on.
+- `provideCodeLanguages(() => list)` (with `useCodeLanguages` and the `CodeLanguage` type): a host context that turns a code block's language field into a dropdown of the given languages, with *None* first; without it the language stays free text. Nested editors inherit the list, and a stored language missing from it stays an option.
+
+### Changed
+
+- The fields bar is more compact: smaller controls and type, text fields show their label as the placeholder (with the field's own placeholder after it), the other fields a short label beside the control.
+- The table's header and footer rows are two icon toggles in its fields bar (a `toggles` field), like any plugin field; the toolbar above the table holds only the row and column tools of the cell being edited, and says to click a cell while none is. The info icon with the keyboard hint is gone.
+- The editor follows the host's light and dark mode: its colours (block fields, popups, frames, the table editor, the block actions) come from the `@atom-forge/ui` theme tokens with the former colours as fallbacks, and the props bar and the link prompt no longer force the light theme. The previews' table borders, video captions and the gap's stripes are drawn from the text colour.
+- A code block's language is edited in the same fields bar as a plugin's (its header shows `code · <language>`), instead of a small input in its corner; read-only, the corner still shows the language.
+- The block handles keep 1px free above and below, so the handles of neighbouring blocks do not touch.
+- The docs note that the block handles are drawn about 22 px left of the editor's box, so the element around it needs that much left padding.
+- Releases are configured with `ship-it init`: the publish workflow comes from Ship's template, `package.json` gains `pub-validate` and `publishConfig`, and npm Trusted Publishing lets CI publish the next versions.
+
+### Removed
+
+- **Breaking:** images and media are no longer the library's concept — whether a block stores a URL or an id, how the user picks an image and how it is resolved is the application's decision. Removed: the `image` and `images` field kinds with their picker, the `media` prop of `Editor` and `Preview`, `provideMedia`, `useMedia`, `findMedia`, the `MediaItem` type, `toMarkdown`'s `media` option and `MarkdownContext.media`. An image block is an app plugin that picks in its own view or dialog and resolves with the app's own data; stored documents are unaffected. See the upgrading chapter.
 
 ## [0.0.1] - 2026-11-10
 

package/README-AI.md

@@ -6,14 +6,16 @@ Brickee is a block editor. Its core is a markdown block editor (`md:p`, `md:h1`
 
 ## Rules
 
-- Peers: `svelte` 5, `@atom-forge/ui` (popups and field controls), `@lucide/svelte`; `zod` only for `@atom-forge/brickee/schema`. The app must set up `@atom-forge/ui` (Tailwind 4, its theme CSS and `@source`, the app beneath its `Root`).
-- Store the editor's `value` (`StoredBlock[]`) as it is. Built-in types start with `md:`; any other `type` is a plugin's. Never rename a plugin's `type`: stored documents refer to it.
+- Peers: `svelte` 5, `@atom-forge/ui` (popups and field controls), `@lucide/svelte`; `zod` only for `@atom-forge/brickee/schema`. The app must set up `@atom-forge/ui` (Tailwind 4, its theme CSS and `@source`, the app beneath its `Root`) and add `@atom-forge/brickee/dist` as a Tailwind `@source` too (the editor is styled with Tailwind classes); the preview needs no Tailwind.
+- Store the editor's `value` (`StoredBlock[]`) as it is. To change it from outside, assign a new array (an in-place change is not picked up); a read-only editor never writes it. Built-in types start with `md:`; any other `type` is a plugin's. Never rename a plugin's `type`: stored documents refer to it.
 - Pass the same `plugins` to the `Editor` and the `Preview` of a document type. Restrict what an editor offers with `palette` (palette ids: `md:*` kinds and plugin types), not by dropping plugins.
-- No app-specific editor props: app data reaches plugins through contexts (`media` / `provideMedia`, `provideView`, `messages` / `provideText`) or plugin fields.
-- Plugin props are untrusted user input. Previews sanitize: `safeColor` for colours, check links, clamp numbers, look images up by id in the media list, never `{@html}` with props.
+- The editor's colours come from the `@atom-forge/ui` theme tokens (light/dark follow the host). Its block handles sit ~22 px left of its box: leave that much left padding around it.
+- No app-specific editor props: app data reaches plugins through contexts (`provideView`, `provideCodeLanguages`, `messages` / `provideText`), plugin fields, or the app's own modules and contexts.
+- No image concept: no image field, picker or media list. An image block is an app plugin that stores what the app chooses (a URL, or an id of its own media library), picks it in its view or the app's own dialog, and resolves ids with the app's own data.
+- Plugin props are untrusted user input. Previews sanitize: `safeColor` for colours, check links and image addresses (`http(s)` or site-relative), clamp numbers, never `{@html}` with props.
 - A plugin view declares both `props` and `blocks` with `$bindable()`, even if unused.
 - Containers (`content: 'blocks'`) nest one level only; nested editors never offer containers or unique plugins. `accepts` narrows their content (`'md:*'` = every built-in).
-- `unique`: one per document, top level; not enforced by the schema. `gate`: the preview only *marks* blocks after it; hide gated content on the server.
+- `unique`: one per document, top level; not enforced by the schema.
 - `toMarkdown` and `toStored` use the DOM: browser only. `fromMarkdown`, `fromStored`, `inline`, the schema and `./model` run anywhere.
 - Validate saved documents on the server with `blocksSchemaFor(plugins)`; it checks shape and `accepts`, not known types, uniqueness or prop contents.
 - Scroll sync is proportional (same scroll fraction), one way, editor → preview; it needs no markup and shows roughly the same place, not the same block.
@@ -24,10 +26,10 @@ Brickee is a block editor. Its core is a markdown block editor (`md:p`, `md:h1`
 
 ```ts
 // @atom-forge/brickee — components
-// <Editor bind:value={StoredBlock[]} plugins?={BlockPlugin[]} palette?={string[]} media?={MediaItem[]}
-//         messages?={Messages} readonly?={boolean} placeholder?={string} />   // `nested` is for Frame only
-// <Preview blocks={StoredBlock[]} plugins={BlockPlugin[]} media?={MediaItem[]} messages?={Messages}
-//          markGated?={boolean /* default true */} nested?={boolean} />
+// <Editor bind:value={StoredBlock[]} plugins?={BlockPlugin[]} palette?={string[]} messages?={Messages}
+//         readonly?={boolean} placeholder?={string} />   // `nested` is for Frame only
+// <Preview blocks={StoredBlock[]} plugins={BlockPlugin[]} messages?={Messages}
+//          nested?={boolean} />
 // <Frame bind:blocks {readonly} {palette} {plugins} heading?={string} empty?={string} image?={string} placeholder?={string} />
 // <Empty icon={Icon} text={string} />
 
@@ -42,16 +44,16 @@ function blocksToPlainText(blocks: StoredBlock[]): string;
 function inline(md: string): string;                 // inline markdown -> safe inline HTML
 function fromStored(s: StoredBlock): Block;
 function toStored(b: Block): StoredBlock;           // browser only
-function fromMarkdown(src: string): Block[];        // one block per non-empty line; built-in blocks only
-function toMarkdown(blocks: Block[], opts?: { plugins?: BlockPlugin[]; media?: MediaItem[] }): string; // browser only
+function fromMarkdown(src: string, opts?: { plugins?: BlockPlugin[] }): Block[]; // CommonMark/GFM blocks; a paragraph's lines stay one block; a GFM table goes to the first plugin with fromTable
+function fromHtml(html: string, opts?: { plugins?: BlockPlugin[] }): Block[]; // browser only; formatted paste (web, Google Docs, Word) via markdown
+function toMarkdown(blocks: Block[], opts?: { plugins?: BlockPlugin[] }): string; // browser only
 
 // contexts (call provide* in component init, above the editor/preview; use* in plugin components)
-interface MediaItem { id: string; name: string; url: string; group?: string }
-function provideMedia(own: () => MediaItem[] | undefined): void;
-function useMedia(): () => MediaItem[];
-function findMedia(list: MediaItem[], id: unknown): MediaItem | undefined;
 function provideView(get: () => string | undefined): void;
 function useView(): () => string | undefined;
+interface CodeLanguage { value: string; label?: string }      // value: stored as the code block's props.lang
+function provideCodeLanguages(own: () => (string | CodeLanguage)[] | undefined): void; // list: the language field is a dropdown
+function useCodeLanguages(): () => CodeLanguage[];             // empty: free text
 type Messages = Record<string, string>;
 type Translate = (text: string, vars?: Record<string, string | number>) => string; // fills {name}
 function provideText(own: () => Messages | undefined): void;
@@ -94,17 +96,19 @@ interface BlockPlugin<P extends Props = Props> {
 	preview?: Component<PluginPreviewProps<any>>; // optional: without it <Preview> renders nothing for the block
 	accepts?: string[];          // container content as palette ids; 'md:*'
 	markdown?(props: P, ctx: MarkdownContext): string; // '' = left out
+	fromTable?(table: MarkdownTable): P; // takes a pasted/imported GFM table (bundled `table` does)
+	fromFiles?(files: File[]): P | null | Promise<P | null>; // takes pasted/dropped files; null = next plugin; upload is yours
 	unique?: boolean;
-	gate?: boolean;
 }
 interface PluginViewProps<P> { props: P; blocks: StoredBlock[]; readonly: boolean; palette: string[]; plugins: BlockPlugin[] }
 interface PluginPreviewProps<P> { props: P; blocks: StoredBlock[]; plugins: BlockPlugin[] }
-interface MarkdownContext { inner: string; media: MediaItem[] }
+interface MarkdownContext { inner: string }
+interface MarkdownTable { rows: string[][] /* inline markdown, first row = header */; align: ('left' | 'center' | 'right')[] }
 interface PropField {
 	key: string; label: string;
-	kind: 'text' | 'textarea' | 'color' | 'select' | 'slider' | 'image' | 'images';
+	kind: 'text' | 'textarea' | 'color' | 'select' | 'slider' | 'toggles'; // toggles: icon buttons, stores the list of the ones on
 	placeholder?: string;
-	options?: { value: string; label: string }[]; // select; stepped slider; label may use {n}
+	options?: { value: string; label: string; icon?: Icon }[]; // select; stepped slider (label may use {n}); toggles (icon + tooltip)
 	min?: number; max?: number; step?: number; unit?: string; // number slider (stored as string)
 	none?: string;                                // unset label (number slider notch, optional colour)
 	views?: { key: string; label: string }[];     // per-view slider values
@@ -113,10 +117,10 @@ interface PropField {
 }
 
 // @atom-forge/brickee/plugins
-// table, youtube, map, gap — the only bundled plugins (none holds nested blocks or uses media); PLUGINS = [table, youtube, map, gap]
+// table, youtube, map, gap — the only bundled plugins (none holds nested blocks or images); PLUGINS = [table, youtube, map, gap]
 // types: TableProps, YouTubeProps, MapProps, GapProps, Head
 // helpers: youtubeId, mapSrc, gapLines, GAP_LINES, GAP_MAX, tableHeads, rowHead, HEADS, square
-// Image blocks, boxes and other containers are app plugins you write yourself (see docs/en/writing-plugins.md, host-contexts.md).
+// Image blocks, boxes and other containers are app plugins you write yourself (see docs/en/writing-plugins.md).
 
 // @atom-forge/brickee/schema (zod)
 const blocksSchema: ZodType<StoredBlock[]>;
@@ -130,16 +134,15 @@ function blocksSchemaFor(plugins: readonly { type: string; accepts?: readonly st
 
 ```svelte
 <script lang="ts">
-	import { Editor, Preview, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+	import { Editor, Preview, type StoredBlock } from '@atom-forge/brickee';
 	import { PLUGINS } from '@atom-forge/brickee/plugins';
 	import { hu } from '@atom-forge/brickee/locales/hu';
 
-	let { media = [] }: { media?: MediaItem[] } = $props();
 	let value = $state<StoredBlock[]>([]);
 </script>
 
-<Editor bind:value plugins={PLUGINS} {media} messages={hu} />
-<Preview blocks={value} plugins={PLUGINS} {media} messages={hu} />
+<Editor bind:value plugins={PLUGINS} messages={hu} />
+<Preview blocks={value} plugins={PLUGINS} messages={hu} />
 ```
 
 ## Common extensions
@@ -214,7 +217,7 @@ export const plugins: BlockPlugin[] = [
 ];
 ```
 
-**Markdown form and conversion** — `markdown(props, { inner, media })` returns markdown or `''`; use `mdText`, `mdJoin`, `mdQuote`, and `findMedia(media, id)?.url` for images. Whole document: `toMarkdown(doc.map(fromStored), { plugins, media })`; import: `fromMarkdown(text).map(toStored)` (both in the browser).
+**Markdown form and conversion** — `markdown(props, { inner })` returns markdown or `''`; use `mdText`, `mdJoin`, `mdQuote`. Whole document: `toMarkdown(doc.map(fromStored), { plugins })`; import: `fromMarkdown(text).map(toStored)` (both in the browser).
 
 **Per-view fields** — add `views` to a slider field and provide the current view:
 
@@ -256,12 +259,15 @@ const result = blocksSchemaFor(plugins).safeParse(input); // or pass [{ type, ac
 | Symptom | Cause | Fix |
 |---|---|---|
 | Fields and popups unstyled | `@atom-forge/ui` theme CSS / `@source` missing | Set up `@atom-forge/ui`; render beneath its `Root`. |
+| Editor rows, menus or table unstyled / shrunk | `@atom-forge/brickee/dist` not a Tailwind `@source` | `@source "../node_modules/@atom-forge/brickee/dist";` |
+| Block handles stick out on the left | Handles are drawn ~22 px left of the editor's box | Give the editor's container ~22 px left padding. |
 | Context errors with a linked local copy | Duplicate `svelte` / `@atom-forge/ui` | Vite `resolve.dedupe: ['svelte', '@atom-forge/ui', '@lucide/svelte', 'zod']`. |
 | A block is missing from `<Preview>` | Its plugin has no `preview` | Add one (bundled plugins have a default) or render it yourself. |
-| "Unknown block" in the editor, block missing on the site | Plugin missing from `plugins`, or image id not in `media` | Same plugins and media for editor and preview. |
+| "Unknown block" in the editor, block missing on the site | Plugin missing from `plugins` | Same plugins for editor and preview. |
+| Image block renders nothing | Preview rejects the stored address, or the app's lookup lacks the id | Store `http(s)` / site-relative addresses; resolve ids from the same app data everywhere. |
+| `media` prop, `useMedia`, `findMedia`, `kind: 'image'` missing | Removed: images are the app's business | Own picking and lookup in the app's image plugin (see `docs/en/upgrading.md`). |
 | Box not offered inside a box | One nesting level | By design. |
 | Block not offered inside a container | `accepts` or host `palette` excludes it | Add its palette id (or `'md:*'`). |
-| Gated content visible to all | `gate` only marks | Cut the document on the server. |
 | `document is not defined` | `toMarkdown` / `toStored` during SSR | Call in the browser. |
 | Injected colour / link | Props rendered unchecked | `safeColor`, link checks, no `{@html}`. |
 | Override loses its blocks | `type` changed | Keep `type`. |