@godxjp/block-editor 31.27.0

package/README.md

@@ -0,0 +1,55 @@
+# @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.
+
+```tsx
+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`, `ｈ２`, `見出し`), ↑↓ Enter Esc. Host rows through `actions`.
+- **⋮⋮ 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`.
+- **Lossless**: anything the editor does not model (raw HTML, footnotes, an unknown directive) is a
+  raw block showing its source, editable as source.
+- **IME-safe** (menus read the committed document), **ja / en / vi**, a named `textbox` with 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>`)             |
+| `actions`, `labels`, `disabled`, `readOnly`, `autoFocus`, `aria-*`, `id` |                                                         |
+
+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)`.

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+import * as React from 'react';
+import { Editor, Node, Extensions } from '@tiptap/core';
+
+/**
+ * The block editor's strings, under its own namespace (`blockEditor`), registered with the kit's
+ * catalogue the first time an editor renders — from the component, not a top-level side effect,
+ * because `sideEffects: false` lets a bundler drop an import that binds nothing.
+ */
+declare const BLOCK_EDITOR_MESSAGES: {
+    readonly ja: {
+        readonly editor: "エディター";
+        readonly placeholder: "「/」でブロックを挿入";
+        readonly placeholderHeading: "見出し{level}";
+        readonly placeholderToggle: "トグル";
+        readonly blocks: "ブロック";
+        readonly noResults: "該当するブロックがありません";
+        readonly text: "テキスト";
+        readonly heading1: "見出し1";
+        readonly heading2: "見出し2";
+        readonly heading3: "見出し3";
+        readonly bulletList: "箇条書き";
+        readonly numberedList: "番号付きリスト";
+        readonly taskList: "ToDoリスト";
+        readonly quote: "引用";
+        readonly callout: "コールアウト";
+        readonly code: "コード";
+        readonly divider: "区切り線";
+        readonly table: "表";
+        readonly image: "画像";
+        readonly toggle: "トグル";
+        readonly columns: "2列";
+        readonly addBlock: "下にブロックを追加";
+        readonly dragHandle: "ドラッグで移動、クリックでブロックの操作";
+        readonly blockActions: "ブロックの操作";
+        readonly turnInto: "ブロックの種類を変更";
+        readonly duplicate: "複製";
+        readonly delete: "削除";
+        readonly moveUp: "上へ移動";
+        readonly moveDown: "下へ移動";
+        readonly formatting: "書式";
+        readonly bold: "太字";
+        readonly italic: "斜体";
+        readonly strike: "取り消し線";
+        readonly inlineCode: "コード";
+        readonly link: "リンク";
+        readonly linkUrl: "リンク先のURL";
+        readonly applyLink: "適用";
+        readonly removeLink: "リンクを解除";
+        readonly uploading: "{name} をアップロード中…";
+        readonly uploadFailed: "{name} をアップロードできませんでした。";
+        readonly retry: "再試行";
+        readonly remove: "削除";
+        readonly rawBlock: "Markdown のソース";
+        readonly editSource: "Markdown を編集";
+        readonly done: "完了";
+        readonly embed: "埋め込み: {target}";
+        readonly calloutNote: "メモ";
+        readonly calloutTip: "ヒント";
+        readonly calloutImportant: "重要";
+        readonly calloutWarning: "警告";
+        readonly calloutCaution: "注意";
+    };
+    readonly en: {
+        readonly editor: "Editor";
+        readonly placeholder: "Type / for blocks";
+        readonly placeholderHeading: "Heading {level}";
+        readonly placeholderToggle: "Toggle";
+        readonly blocks: "Blocks";
+        readonly noResults: "No matching blocks";
+        readonly text: "Text";
+        readonly heading1: "Heading 1";
+        readonly heading2: "Heading 2";
+        readonly heading3: "Heading 3";
+        readonly bulletList: "Bulleted list";
+        readonly numberedList: "Numbered list";
+        readonly taskList: "To-do list";
+        readonly quote: "Quote";
+        readonly callout: "Callout";
+        readonly code: "Code";
+        readonly divider: "Divider";
+        readonly table: "Table";
+        readonly image: "Image";
+        readonly toggle: "Toggle";
+        readonly columns: "2 columns";
+        readonly addBlock: "Add a block below";
+        readonly dragHandle: "Drag to move, click for block actions";
+        readonly blockActions: "Block actions";
+        readonly turnInto: "Turn into";
+        readonly duplicate: "Duplicate";
+        readonly delete: "Delete";
+        readonly moveUp: "Move up";
+        readonly moveDown: "Move down";
+        readonly formatting: "Formatting";
+        readonly bold: "Bold";
+        readonly italic: "Italic";
+        readonly strike: "Strikethrough";
+        readonly inlineCode: "Code";
+        readonly link: "Link";
+        readonly linkUrl: "Link URL";
+        readonly applyLink: "Apply";
+        readonly removeLink: "Remove link";
+        readonly uploading: "Uploading {name}…";
+        readonly uploadFailed: "Could not upload {name}.";
+        readonly retry: "Retry";
+        readonly remove: "Remove";
+        readonly rawBlock: "Markdown source";
+        readonly editSource: "Edit Markdown";
+        readonly done: "Done";
+        readonly embed: "Embed: {target}";
+        readonly calloutNote: "Note";
+        readonly calloutTip: "Tip";
+        readonly calloutImportant: "Important";
+        readonly calloutWarning: "Warning";
+        readonly calloutCaution: "Caution";
+    };
+    readonly vi: {
+        readonly editor: "Trình soạn thảo";
+        readonly placeholder: "Gõ / để chèn khối";
+        readonly placeholderHeading: "Tiêu đề {level}";
+        readonly placeholderToggle: "Mục thu gọn";
+        readonly blocks: "Khối";
+        readonly noResults: "Không có khối phù hợp";
+        readonly text: "Văn bản";
+        readonly heading1: "Tiêu đề 1";
+        readonly heading2: "Tiêu đề 2";
+        readonly heading3: "Tiêu đề 3";
+        readonly bulletList: "Danh sách gạch đầu dòng";
+        readonly numberedList: "Danh sách đánh số";
+        readonly taskList: "Danh sách việc cần làm";
+        readonly quote: "Trích dẫn";
+        readonly callout: "Chú thích nổi bật";
+        readonly code: "Mã";
+        readonly divider: "Đường phân cách";
+        readonly table: "Bảng";
+        readonly image: "Hình ảnh";
+        readonly toggle: "Mục thu gọn";
+        readonly columns: "2 cột";
+        readonly addBlock: "Thêm khối bên dưới";
+        readonly dragHandle: "Kéo để di chuyển, bấm để thao tác với khối";
+        readonly blockActions: "Thao tác với khối";
+        readonly turnInto: "Chuyển thành";
+        readonly duplicate: "Nhân bản";
+        readonly delete: "Xoá";
+        readonly moveUp: "Chuyển lên";
+        readonly moveDown: "Chuyển xuống";
+        readonly formatting: "Định dạng";
+        readonly bold: "In đậm";
+        readonly italic: "In nghiêng";
+        readonly strike: "Gạch ngang";
+        readonly inlineCode: "Mã";
+        readonly link: "Liên kết";
+        readonly linkUrl: "URL liên kết";
+        readonly applyLink: "Áp dụng";
+        readonly removeLink: "Bỏ liên kết";
+        readonly uploading: "Đang tải {name} lên…";
+        readonly uploadFailed: "Không tải được {name} lên.";
+        readonly retry: "Thử lại";
+        readonly remove: "Gỡ bỏ";
+        readonly rawBlock: "Mã nguồn Markdown";
+        readonly editSource: "Sửa Markdown";
+        readonly done: "Xong";
+        readonly embed: "Nhúng: {target}";
+        readonly calloutNote: "Ghi chú";
+        readonly calloutTip: "Mẹo";
+        readonly calloutImportant: "Quan trọng";
+        readonly calloutWarning: "Cảnh báo";
+        readonly calloutCaution: "Thận trọng";
+    };
+};
+type BlockEditorLabels = {
+    [K in keyof (typeof BLOCK_EDITOR_MESSAGES)["en"]]: string;
+};
+
+/** What the host's storage returns for one file — the same shape as MarkdownEditor's. */
+type BlockEditorUploadResult = {
+    url: string;
+    name?: string;
+};
+/** A row the host's `[[` source returns. `label` is what the link shows instead of the target. */
+type WikilinkSuggestion = {
+    target: string;
+    label?: string;
+    heading?: string;
+    description?: string;
+};
+/** What a host command (an extra `/` row) is handed. */
+type BlockEditorApi = {
+    editor: Editor;
+    /** Insert Markdown at the caret, parsed through the codec. */
+    insertMarkdown: (markdown: string) => void;
+    markdown: () => string;
+};
+type BlockEditorAction = {
+    key: string;
+    label: string;
+    icon: React.ReactNode;
+    keywords?: readonly string[];
+    run: (api: BlockEditorApi) => void;
+};
+type BlockEditorProps = {
+    /** The body, as Markdown. Controlled with `onValueChange`; uncontrolled with `defaultValue`. */
+    value?: string;
+    defaultValue?: string;
+    /** Called with the canonical Markdown (`@godxjp/markdown/codec` `serialize`) after each edit. */
+    onValueChange?: (markdown: string) => void;
+    /**
+     * Stores a pasted, dropped or chosen file and returns its URL (`asset:<id>` is fine). Aborted
+     * with `signal` when the placeholder block is removed. Omit it and files are not accepted.
+     */
+    upload?: (file: File, options: {
+        signal: AbortSignal;
+    }) => Promise<BlockEditorUploadResult>;
+    /** The host's media library. When set, the `/` Image row opens it instead of a file picker. */
+    pickMedia?: () => Promise<BlockEditorUploadResult | null>;
+    /** When set, files are refused with this message (a quota, a read-only space). */
+    uploadBlockedReason?: string | null;
+    /** `[[` suggestions — the host's page index. Omit it and `[[…]]` is still typed as text. */
+    suggestWikilinks?: (query: string) => WikilinkSuggestion[] | Promise<WikilinkSuggestion[]>;
+    /** Renders a block embed (`![[target]]`). Default: a labelled placeholder. */
+    renderEmbed?: (target: string) => React.ReactNode;
+    /** Resolves a stored image URL (`asset:<id>`) for display. The body keeps the original. */
+    resolveUrl?: (url: string) => string | undefined;
+    /** Extra `/` rows after the built-in blocks — the extension point for host block types. */
+    actions?: readonly BlockEditorAction[];
+    /** Override any string the editor renders (defaults: the kit's ja / en / vi catalogue). */
+    labels?: Partial<BlockEditorLabels>;
+    disabled?: boolean;
+    readOnly?: boolean;
+    autoFocus?: boolean;
+    id?: string;
+    className?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+};
+type BlockEditorHandle = {
+    focus: () => void;
+    /** The current body, serialized. */
+    markdown: () => string;
+    /** The Tiptap editor, for host integrations. */
+    editor: Editor | null;
+};
+/**
+ * BlockEditor (gh#1156) — a Notion / note.com style block editor that reads and writes MARKDOWN.
+ *
+ * Its document is `@godxjp/markdown/codec`'s: `value` is parsed by the codec, every edit is
+ * serialized by it, so what `onValueChange` hands back is byte-for-byte `normalize(body)` — the
+ * same canonical form a server computes. The surface is the kit's `Prose`, so the body looks the
+ * way the published page draws it. `/` opens the block menu at the caret; ⋮⋮ beside a block drags
+ * it and opens its menu (turn into, duplicate, move, delete); selecting text raises the format
+ * toolbar. Japanese IME composition is never interrupted: menus read the committed document.
+ */
+declare const BlockEditor: React.ForwardRefExoticComponent<BlockEditorProps & React.RefAttributes<BlockEditorHandle>>;
+
+/**
+ * THE EDITOR SCHEMA IS THE CODEC'S DOCUMENT (gh#1156). Every node `@godxjp/markdown/codec` emits
+ * has a node type here with the same name and attributes, so `setContent(parse(md))` loses nothing
+ * and `serialize(getJSON())` writes it back. A node the codec does not know never enters the
+ * schema — underline is switched off because Markdown has no underline.
+ */
+type CalloutTitles = Record<"note" | "tip" | "important" | "warning" | "caution", string>;
+/**
+ * The editor's extensions. Block atoms that need React — the host's embed renderer, the raw
+ * Markdown block, an upload in flight — are added by the component, which owns their node views.
+ */
+declare function schemaExtensions(options: {
+    placeholder: string;
+    headingPlaceholder: (level: number) => string;
+    togglePlaceholder: string;
+    calloutTitles: CalloutTitles;
+    /** Node views the component owns (React); omitted, the nodes render as plain HTML. */
+    embed?: Node;
+    rawBlock?: Node;
+    /** Resolves a stored image URL (`asset:<id>`) to one the browser can load; the doc keeps the original. */
+    resolveUrl?: (url: string) => string | undefined;
+}): Extensions;
+
+export { BLOCK_EDITOR_MESSAGES, BlockEditor, type BlockEditorAction, type BlockEditorApi, type BlockEditorHandle, type BlockEditorLabels, type BlockEditorProps, type BlockEditorUploadResult, type CalloutTitles, type WikilinkSuggestion, schemaExtensions };