@godxjp/block-editor
A Notion / note.com style block editor for GoDX apps, on Tiptap v3 (MIT parts only). It reads and
writes Markdown: the document is @godxjp/markdown/codec's, so what onValueChange returns is
byte-for-byte normalize(body) — the same canonical form a server computes with the same codec.
import { BlockEditor } from "@godxjp/block-editor";
<BlockEditor
aria-label="本文"
value={body}
onValueChange={setBody}
upload={async (file, { signal }) => ({ url: await media.put(file, { signal }), name: file.name })}
pickMedia={() => media.pick()}
suggestWikilinks={(query) => pages.search(query)}
renderEmbed={(target) => <PageEmbed target={target} />}
resolveUrl={(url) => (url.startsWith("asset:") ? media.url(url) : undefined)}
/>;
What it does
/block menu at the caret (also/from a Japanese keyboard): text, headings, lists, to-do, quote, callout, code, divider, image, table, toggle, columns — filtered as you type (h2,h2,見出し), ↑↓ Enter Esc. Host rows throughactions.- ⋮⋮ handle and + beside the block under the pointer (the caret's block on touch): drag to move, click for turn into / duplicate / move / delete. From the keyboard: Alt+Shift+↑/↓ moves a block, Mod+/ opens its menu.
- Format toolbar on a selection: bold, italic, strikethrough, code, link (only marks Markdown can store — there is no underline).
- Markdown shortcuts (
#,-,1.,>,```,---,[[x]]), and plain-text paste is read as Markdown. - Uploads: paste / drop / pick a file → an inline placeholder with progress; failure offers
Retry / Remove; deleting the placeholder aborts the host's
signal. - Directive blocks: a container directive the kit does not model (
:::poll[…]{…},::::form) is ONE atomic block — dragged, deleted and inserted whole — showing the host's preview for its name (directives), or its source; "Edit source" edits its Markdown. A host/row inserts one withapi.insertMarkdown(skeleton). - Lossless: anything else the editor does not model (raw HTML, footnotes, a malformed toggle or column row) is a raw block showing its source, editable as source.
- IME-safe (menus read the committed document), ja / en / vi, a named
textboxwith the WAI-ARIA popup wiring on the/and[[lists, the kit's Prose as the editing surface.
Contract
| prop | |
|---|---|
value / defaultValue / onValueChange | Markdown in, canonical Markdown out |
upload(file, { signal }) | → { url, name? } — the same shape as MarkdownEditor |
pickMedia() | → { url, name? } | null — the host's library |
suggestWikilinks(query) | → { target, label?, heading?, description? }[] |
renderEmbed(target) | a block embed ![[target]] |
resolveUrl(url) | display URL for a stored one (asset:<id>) |
directives | { [name]: (block, controls) => ReactNode | undefined } previews |
actions, labels, disabled, readOnly, autoFocus, aria-*, id |
// A poll is a block: the host previews it and inserts its skeleton from the `/` menu.
<BlockEditor
value={body}
onValueChange={setBody}
directives={{
// block: { name, label, attributes, source, body } — the codec's canonical Markdown
poll: (block) => <PollPreview question={block.label} options={block.body} />,
}}
actions={[
{
key: "poll",
label: "Poll",
icon: <ListChecks />,
run: (api) => api.insertMarkdown(":::poll[Question]{id=poll-1}\n- Option A\n- Option B\n:::"),
},
]}
/>
A preview can change its own block (gh#1479): controls.update(markdown) replaces the block's
source exactly like "Edit source" → Done (still one directive: the same block, one undo step;
anything else takes its place), controls.remove() deletes it, and controls.editable is false in a
read-only or disabled editor. A host's picker or config form writes its result back this way:
directives={{
card: (block, { update, editable }) => (
<CardPreview id={block.attributes.card} onPick={editable ? (id) => update(`:::card{card=${id}}\n:::`) : undefined} />
),
}}
The grammar it reads and writes is specified in @godxjp/markdown's README ("Grammar v1 and the
codec"). The editor's schema is tested to round-trip every fixture exactly:
serialize(editor.getJSON()) === normalize(markdown).
RichTextEditor and TranslatableRichText — HTML fields
For columns that already hold HTML (a product description a storefront renders), the package also ships a form field with a fixed toolbar — bold, italic, strike, inline code · H1–H3, bulleted / numbered list, quote · undo, redo — and its per-locale form (gh#1365).
import { RichTextEditor, TranslatableRichText } from "@godxjp/block-editor";
import { FormField } from "@godxjp/ui/data-entry";
<FormField label="説明" required>
<TranslatableRichText value={description} onValueChange={setDescription} errors={errors} />
</FormField>;
- The schema is the sanitiser:
value(and a paste) is parsed into, andonValueChangeemits, onlyp br h1 h2 h3 ul ol li blockquote strong em s code(RICH_TEXT_ALLOWED_TAGS) with no attributes except an integerstarton<ol>. Anything else — script, links, images, styles, h4–h6, tables — is kept as its text. An empty body is"". - A
valuefrom outside (a reset, a locale tab) replaces the document without callingonValueChange, and never while an IME composition is open. - It takes FormField's
id/aria-*on the editable;status/aria-invalidpaint the frame. TranslatableRichTextis the kit'sTranslatableFieldengine around it — the same contract asTranslatableInput: locales and first tab from AppProvidercontentLocales, per-locale error marks, the active error in FormField, and the fallback locale's text as an empty locale's placeholder.