@godxjp/block-editor 33.20.0 → 33.22.1

package/README.md

@@ -33,22 +33,47 @@ import { BlockEditor } from "@godxjp/block-editor";
   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.
+- **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 with `api.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 `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` |                                                         |
+| 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) => ReactNode \| undefined }` previews |
+| `actions`, `labels`, `disabled`, `readOnly`, `autoFocus`, `aria-*`, `id` |                                                          |
+
+```tsx
+// 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:::"),
+    },
+  ]}
+/>
+```
 
 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:

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { Editor, Node, Extensions } from '@tiptap/core';
+import { DirectiveBlock } from '@godxjp/markdown/codec';
 import { FieldA11yProps, TranslatableLocaleProp } from '@godxjp/ui/data-entry';
 
 /**
@@ -55,6 +56,7 @@ declare const BLOCK_EDITOR_MESSAGES: {
         readonly editSource: "Markdown を編集";
         readonly done: "完了";
         readonly embed: "埋め込み: {target}";
+        readonly directive: "ブロック: {name}";
         readonly calloutNote: "メモ";
         readonly calloutTip: "ヒント";
         readonly calloutImportant: "重要";
@@ -132,6 +134,7 @@ declare const BLOCK_EDITOR_MESSAGES: {
         readonly editSource: "Edit Markdown";
         readonly done: "Done";
         readonly embed: "Embed: {target}";
+        readonly directive: "Block: {name}";
         readonly calloutNote: "Note";
         readonly calloutTip: "Tip";
         readonly calloutImportant: "Important";
@@ -209,6 +212,7 @@ declare const BLOCK_EDITOR_MESSAGES: {
         readonly editSource: "Sửa Markdown";
         readonly done: "Xong";
         readonly embed: "Nhúng: {target}";
+        readonly directive: "Khối: {name}";
         readonly calloutNote: "Ghi chú";
         readonly calloutTip: "Mẹo";
         readonly calloutImportant: "Quan trọng";
@@ -244,6 +248,9 @@ type BlockEditorLabels = {
     [K in keyof (typeof BLOCK_EDITOR_MESSAGES)["en"]]: string;
 };
 
+/** Draws a directive block's preview in the editor; `undefined` shows its source instead. */
+type BlockEditorDirectiveRenderer = (block: DirectiveBlock) => React.ReactNode | undefined;
+
 /** What the host's storage returns for one file — the same shape as MarkdownEditor's. */
 type BlockEditorUploadResult = {
     url: string;
@@ -293,8 +300,20 @@ type BlockEditorProps = {
     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. */
+    /**
+     * Extra `/` rows after the built-in blocks — the extension point for host block types. A row
+     * that inserts a directive skeleton (`api.insertMarkdown(":::poll[…]{…}\n- A\n- B\n:::")`)
+     * inserts a directive BLOCK.
+     */
     actions?: readonly BlockEditorAction[];
+    /**
+     * Previews for directive blocks, by name: `{ poll: (block) => <PollPreview … /> }`. A container
+     * directive the kit does not model (`:::poll[…]{…}`) is one block — dragged, deleted, inserted
+     * whole, its source edited behind "Edit source"; the renderer receives its parts
+     * (`DirectiveBlock`: name, label, attributes, canonical source, body). Without one — or when it
+     * returns `undefined` — the block shows its source.
+     */
+    directives?: Readonly<Record<string, BlockEditorDirectiveRenderer>>;
     /** Override any string the editor renders (defaults: the kit's ja / en / vi catalogue). */
     labels?: Partial<BlockEditorLabels>;
     /**
@@ -349,6 +368,7 @@ declare function schemaExtensions(options: {
     /** Node views the component owns (React); omitted, the nodes render as plain HTML. */
     embed?: Node;
     rawBlock?: Node;
+    directive?: Node;
     /** Resolves a stored image URL (`asset:<id>`) to one the browser can load; the doc keeps the original. */
     resolveUrl?: (url: string) => string | undefined;
     callout?: Node;
@@ -440,9 +460,9 @@ type TranslatableRichTextProps = Omit<RichTextEditorProps, "value" | "defaultVal
  * `contentLocales`, fallback placeholder, per-locale error marks, FormField error report). An empty
  * locale shows the fallback locale's TEXT as its placeholder. `ref` is the editor's handle.
  */
-declare const TranslatableRichText: React.ForwardRefExoticComponent<Omit<RichTextEditorProps, "value" | "lang" | "defaultValue" | "onValueChange"> & TranslatableLocaleProp & {
+declare const TranslatableRichText: React.ForwardRefExoticComponent<Omit<RichTextEditorProps, "value" | "defaultValue" | "lang" | "onValueChange"> & TranslatableLocaleProp & {
     /** The tab strip's tier, as on TranslatableTextarea (`sm` tabs; `md` for `lg`). */
     size?: "sm" | "md" | "lg";
 } & React.RefAttributes<RichTextEditorHandle>>;
 
-export { BLOCK_EDITOR_MESSAGES, BlockEditor, type BlockEditorAction, type BlockEditorApi, type BlockEditorHandle, type BlockEditorLabels, type BlockEditorProps, type BlockEditorUploadResult, type CalloutTitles, RICH_TEXT_ALLOWED_TAGS, RichTextEditor, type RichTextEditorHandle, type RichTextEditorLabels, type RichTextEditorProps, TranslatableRichText, type TranslatableRichTextProps, type WikilinkSuggestion, schemaExtensions };
+export { BLOCK_EDITOR_MESSAGES, BlockEditor, type BlockEditorAction, type BlockEditorApi, type BlockEditorDirectiveRenderer, type BlockEditorHandle, type BlockEditorLabels, type BlockEditorProps, type BlockEditorUploadResult, type CalloutTitles, RICH_TEXT_ALLOWED_TAGS, RichTextEditor, type RichTextEditorHandle, type RichTextEditorLabels, type RichTextEditorProps, TranslatableRichText, type TranslatableRichTextProps, type WikilinkSuggestion, schemaExtensions };

package/dist/index.js

@@ -616,6 +616,36 @@ var Frontmatter = Node.create({
     ];
   }
 });
+var Directive = Node.create({
+  name: "directive",
+  group: "block",
+  atom: true,
+  draggable: true,
+  addAttributes() {
+    return { name: { default: "" }, source: { default: "" } };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "pre[data-directive]",
+        getAttrs: (element) => ({
+          name: element.getAttribute("data-directive") ?? "",
+          source: element.textContent ?? ""
+        })
+      }
+    ];
+  },
+  renderHTML({ node, HTMLAttributes }) {
+    return [
+      "pre",
+      mergeAttributes(HTMLAttributes, {
+        "data-directive": node.attrs.name,
+        class: "ui-block-editor-raw-block"
+      }),
+      node.attrs.source
+    ];
+  }
+});
 var RawBlock = Node.create({
   name: "rawBlock",
   group: "block",
@@ -685,6 +715,7 @@ function schemaExtensions(options) {
     RawInline,
     options.embed ?? Embed,
     options.rawBlock ?? RawBlock,
+    options.directive ?? Directive,
     options.frontmatter ?? Frontmatter,
     Placeholder.configure({
       includeChildren: true,
@@ -718,6 +749,7 @@ import {
 import * as React from "react";
 var LabelsContext = React.createContext((key) => key);
 var useLabel = () => React.useContext(LabelsContext);
+var DirectivesContext = React.createContext(void 0);
 
 // src/handle.tsx
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
@@ -916,6 +948,7 @@ var BLOCK_EDITOR_MESSAGES = {
     editSource: "Markdown \u3092\u7DE8\u96C6",
     done: "\u5B8C\u4E86",
     embed: "\u57CB\u3081\u8FBC\u307F: {target}",
+    directive: "\u30D6\u30ED\u30C3\u30AF: {name}",
     calloutNote: "\u30E1\u30E2",
     calloutTip: "\u30D2\u30F3\u30C8",
     calloutImportant: "\u91CD\u8981",
@@ -993,6 +1026,7 @@ var BLOCK_EDITOR_MESSAGES = {
     editSource: "Edit Markdown",
     done: "Done",
     embed: "Embed: {target}",
+    directive: "Block: {name}",
     calloutNote: "Note",
     calloutTip: "Tip",
     calloutImportant: "Important",
@@ -1070,6 +1104,7 @@ var BLOCK_EDITOR_MESSAGES = {
     editSource: "S\u1EEDa Markdown",
     done: "Xong",
     embed: "Nh\xFAng: {target}",
+    directive: "Kh\u1ED1i: {name}",
     calloutNote: "Ghi ch\xFA",
     calloutTip: "M\u1EB9o",
     calloutImportant: "Quan tr\u1ECDng",
@@ -1439,7 +1474,7 @@ import {
   ReactNodeViewRenderer
 } from "@tiptap/react";
 import { ChevronDown, LoaderCircle, TriangleAlert } from "lucide-react";
-import { parse } from "@godxjp/markdown/codec";
+import { parse, readDirective } from "@godxjp/markdown/codec";
 import { Input as Input2, Select, Textarea } from "@godxjp/ui/data-entry";
 import {
   DropdownMenu as DropdownMenu2,
@@ -1504,6 +1539,68 @@ function RawBlockView({ node, editor, getPos, updateAttributes, selected }) {
 function rawBlockNode() {
   return RawBlock.extend({ addNodeView: () => ReactNodeViewRenderer(RawBlockView) });
 }
+function DirectiveView({ node, editor, getPos, updateAttributes, selected }) {
+  const tr = useLabel();
+  const previews = React5.useContext(DirectivesContext);
+  const name = node.attrs.name;
+  const source = node.attrs.source;
+  const [editing, setEditing] = React5.useState(false);
+  const [draft, setDraft] = React5.useState(source);
+  const render = previews && Object.hasOwn(previews, name) ? previews[name] : void 0;
+  const block = React5.useMemo(() => render ? readDirective(source) : null, [render, source]);
+  const preview = render && block ? render(block) : void 0;
+  const commit = () => {
+    setEditing(false);
+    const doc = parse(draft);
+    const pos = getPos();
+    const [only] = doc.content;
+    if (doc.content.length === 1 && only.type === "directive") {
+      updateAttributes(only.attrs);
+      return;
+    }
+    if (typeof pos !== "number") return;
+    editor.chain().focus().insertContentAt({ from: pos, to: pos + node.nodeSize }, doc.content).run();
+  };
+  return /* @__PURE__ */ jsxs5(
+    NodeViewWrapper,
+    {
+      className: "ui-block-editor-raw-block",
+      "data-directive": name,
+      "data-selected": selected ? "" : void 0,
+      children: [
+        /* @__PURE__ */ jsxs5("div", { className: "ui-block-editor-raw-block-head", contentEditable: false, children: [
+          /* @__PURE__ */ jsx6(Text, { size: "xs", tone: "muted", children: tr("directive", { name }) }),
+          editor.isEditable ? /* @__PURE__ */ jsx6(
+            Button4,
+            {
+              size: "xs",
+              variant: "ghost",
+              onClick: () => editing ? commit() : (setDraft(source), setEditing(true)),
+              children: editing ? tr("done") : tr("editSource")
+            }
+          ) : null
+        ] }),
+        editing ? /* @__PURE__ */ jsx6(
+          Textarea,
+          {
+            "aria-label": tr("directive", { name }),
+            value: draft,
+            rows: Math.min(12, Math.max(3, draft.split("\n").length)),
+            onValueChange: setDraft,
+            onKeyDown: (event) => {
+              event.stopPropagation();
+              if (event.key === "Escape") commit();
+            },
+            autoFocus: true
+          }
+        ) : preview !== void 0 ? /* @__PURE__ */ jsx6("div", { "data-directive-preview": "", contentEditable: false, children: preview }) : /* @__PURE__ */ jsx6("pre", { className: "ui-block-editor-raw-block-source", contentEditable: false, children: source })
+      ]
+    }
+  );
+}
+function directiveNode() {
+  return Directive.extend({ addNodeView: () => ReactNodeViewRenderer(DirectiveView) });
+}
 function FrontmatterView({ node, updateAttributes, editor, selected }) {
   const label = useLabel();
   const [editing, setEditing] = React5.useState(false);
@@ -1810,6 +1907,7 @@ var BlockEditor = React6.forwardRef(
     renderEmbed,
     resolveUrl,
     actions = [],
+    directives,
     labels,
     appearance = "framed",
     disabled = false,
@@ -2090,6 +2188,7 @@ var BlockEditor = React6.forwardRef(
           },
           embed: embedNode(renderEmbed),
           rawBlock: rawBlockNode(),
+          directive: directiveNode(),
           frontmatter: frontmatterNode(),
           callout: calloutNode(Callout),
           columns: columnsNode(Columns),
@@ -2261,7 +2360,7 @@ var BlockEditor = React6.forwardRef(
               }
             )
           ] }) : null,
-          /* @__PURE__ */ jsx7(EditorContent, { editor }),
+          /* @__PURE__ */ jsx7(DirectivesContext.Provider, { value: directives, children: /* @__PURE__ */ jsx7(EditorContent, { editor }) }),
           /* @__PURE__ */ jsx7(
             SuggestionMenu,
             {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godxjp/block-editor",
-  "version": "33.20.0",
+  "version": "33.22.1",
   "description": "Block editor for GoDX apps (Notion / note.com style) on Tiptap: slash menu, block handles, floating format toolbar; reads and writes Markdown through @godxjp/markdown/codec, IME-safe, ja / en / vi.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,8 +45,8 @@
     "lucide-react": "^1.37.0"
   },
   "peerDependencies": {
-    "@godxjp/markdown": "~33.20.0",
-    "@godxjp/ui": "~33.20.0",
+    "@godxjp/markdown": "~33.22.1",
+    "@godxjp/ui": "~33.22.1",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },