@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/editor/extensions.d.ts

@@ -0,0 +1,34 @@
+import { Mark, type AnyExtension, type Editor } from "@tiptap/react";
+import { PluginKey } from "@tiptap/pm/state";
+import type { LabelFn } from "../lib/labels.js";
+import type { BlockEditorLabels } from "./labels.js";
+import type { BlockEditorVariant, ImageUploader, SlashStore } from "./context.js";
+export declare const HighlightMark: Mark<any, any>;
+export declare const SubscriptMark: Mark<any, any>;
+export declare const SuperscriptMark: Mark<any, any>;
+export interface EditorBridge {
+    t: LabelFn<BlockEditorLabels>;
+    announce: (m: string) => void;
+    title: (node: {
+        type: {
+            name: string;
+        };
+        attrs: Record<string, unknown>;
+    }) => string;
+    focusToolbar: () => boolean;
+    uploader?: ImageUploader;
+}
+export declare const slashPluginKey: PluginKey<any>;
+export interface BuildExtensionsOptions {
+    variant: BlockEditorVariant;
+    t: LabelFn<BlockEditorLabels>;
+    placeholder?: string;
+    slash: SlashStore | null;
+    bridge: {
+        current: EditorBridge;
+    };
+    getEditor: () => Editor;
+    /** Allow component blocks, tables and images (false in rich-text mode). */
+    blocks: boolean;
+}
+export declare function buildExtensions(o: BuildExtensionsOptions): AnyExtension[];

package/dist/editor/extensions.js

@@ -0,0 +1,239 @@
+// The Tiptap extension set behind BlockEditor. MIT extensions only (no Pro / Cloud).
+import { Extension, Mark, mergeAttributes } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import { Placeholder } from "@tiptap/extensions";
+import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table";
+import UniqueID from "@tiptap/extension-unique-id";
+import { Suggestion, exitSuggestion } from "@tiptap/suggestion";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { sanitizeHref } from "../blocks/schema/safety.js";
+import { COMPONENT_BLOCK, createBlockId, toProseMirror } from "./convert.js";
+import { cleanPastedHtml, looksLikeMarkdown, markdownToBlocks } from "./markdown.js";
+import { ComponentBlockNode, ImageNode, uploadImageFile } from "./nodes.js";
+import { deleteBlock, duplicateBlock, editBlock, getTopBlock, isBlockSelection, moveBlock, selectBlock, selectSibling } from "./commands.js";
+// ---------------------------------------------------------------- marks missing from StarterKit
+const simpleMark = (name, tag, shortcut) => Mark.create({
+    name,
+    excludes: name === "subscript" ? "superscript" : name === "superscript" ? "subscript" : undefined,
+    parseHTML: () => [{ tag }],
+    renderHTML: ({ HTMLAttributes }) => [tag, mergeAttributes(HTMLAttributes), 0],
+    addKeyboardShortcuts() {
+        return shortcut ? { [shortcut]: () => this.editor.commands.toggleMark(name) } : {};
+    },
+});
+export const HighlightMark = simpleMark("highlight", "mark", "Mod-Shift-h");
+export const SubscriptMark = simpleMark("subscript", "sub", "Mod-,");
+export const SuperscriptMark = simpleMark("superscript", "sup", "Mod-.");
+// ---------------------------------------------------------------- BlockNode fields with no PM home
+const EXTRA_TYPES = ["paragraph", "heading", "bulletList", "orderedList", "blockquote", "codeBlock", "horizontalRule", "image", "table"];
+const VamosAttributes = Extension.create({
+    name: "vamosAttributes",
+    addGlobalAttributes() {
+        return [
+            { types: EXTRA_TYPES, attributes: { extra: { default: null, rendered: false, keepOnSplit: false } } },
+            { types: ["heading"], attributes: { anchor: { default: null, rendered: false, keepOnSplit: false } } },
+            { types: ["blockquote"], attributes: { cite: { default: null, parseHTML: (el) => el.getAttribute("data-cite"), renderHTML: (a) => (a.cite ? { "data-cite": a.cite } : {}) } } },
+            // Content language direction per block (mixed-script docs).
+            { types: ["paragraph", "heading", "blockquote", "listItem", "tableCell", "tableHeader"], attributes: { dir: { default: "auto", renderHTML: () => ({ dir: "auto" }), parseHTML: () => "auto" } } },
+        ];
+    },
+});
+const BlockKeymap = Extension.create({
+    name: "vamosBlockKeymap",
+    priority: 150,
+    addOptions() {
+        return { bridge: { current: null } };
+    },
+    addKeyboardShortcuts() {
+        const b = () => this.options.bridge.current;
+        const say = (key, node) => node && b().announce(b().t(key, { title: b().title(node) }));
+        return {
+            Escape: ({ editor }) => {
+                if (isBlockSelection(editor))
+                    return false;
+                const top = getTopBlock(editor);
+                if (!top)
+                    return false;
+                selectBlock(editor, top.pos);
+                say("announceSelected", top.node);
+                return true;
+            },
+            ArrowUp: ({ editor }) => {
+                if (!isBlockSelection(editor))
+                    return false;
+                const s = selectSibling(editor, -1);
+                if (s)
+                    say("announceSelected", s.node);
+                return true;
+            },
+            ArrowDown: ({ editor }) => {
+                if (!isBlockSelection(editor))
+                    return false;
+                const s = selectSibling(editor, 1);
+                if (s)
+                    say("announceSelected", s.node);
+                return true;
+            },
+            Enter: ({ editor }) => (isBlockSelection(editor) ? editBlock(editor) : false),
+            "Alt-Shift-ArrowUp": ({ editor }) => {
+                const m = moveBlock(editor, -1);
+                if (m)
+                    say("announceMovedUp", m.node);
+                return true;
+            },
+            "Alt-Shift-ArrowDown": ({ editor }) => {
+                const m = moveBlock(editor, 1);
+                if (m)
+                    say("announceMovedDown", m.node);
+                return true;
+            },
+            "Mod-Shift-d": ({ editor }) => {
+                const d = duplicateBlock(editor);
+                if (d)
+                    say("announceDuplicated", d.node);
+                return true;
+            },
+            "Alt-Shift-z": ({ editor }) => {
+                const d = deleteBlock(editor);
+                if (d)
+                    say("announceDeleted", d.node);
+                return true;
+            },
+            "Alt-F10": () => b().focusToolbar(),
+        };
+    },
+});
+// ---------------------------------------------------------------- paste / drop
+const imageFiles = (dt) => Array.from(dt?.files ?? []).filter((f) => f.type.startsWith("image/"));
+function PasteHandler(opts) {
+    return new Plugin({
+        key: new PluginKey("vamosPaste"),
+        props: {
+            transformPastedHTML: (html) => cleanPastedHtml(html),
+            handlePaste(view, event) {
+                const editor = opts.editor();
+                const uploader = opts.bridge.current.uploader;
+                const files = imageFiles(event.clipboardData);
+                if (files.length && uploader && opts.images) {
+                    files.forEach((f) => uploadImageFile(editor, f, uploader, { onError: () => opts.bridge.current.announce(opts.bridge.current.t("imageFailed")) }));
+                    return true;
+                }
+                const html = event.clipboardData?.getData("text/html");
+                const text = event.clipboardData?.getData("text/plain");
+                if (html || !text || view.state.selection.$from.parent.type.spec.code)
+                    return false;
+                if (!looksLikeMarkdown(text))
+                    return false;
+                let blocks = markdownToBlocks(text);
+                if (!opts.tables)
+                    blocks = blocks.filter((bl) => bl.type !== "table");
+                if (!blocks.length)
+                    return false;
+                const content = toProseMirror({ version: 1, blocks }).content ?? [];
+                editor.chain().focus().insertContent(content).run();
+                return true;
+            },
+            handleDrop(view, event, _slice, moved) {
+                if (moved)
+                    return false;
+                const uploader = opts.bridge.current.uploader;
+                const files = imageFiles(event.dataTransfer);
+                if (!files.length || !uploader || !opts.images)
+                    return false;
+                const coords = view.posAtCoords({ left: event.clientX, top: event.clientY });
+                event.preventDefault();
+                files.forEach((f) => uploadImageFile(opts.editor(), f, uploader, { pos: coords?.pos }));
+                return true;
+            },
+        },
+    });
+}
+// ---------------------------------------------------------------- slash command
+export const slashPluginKey = new PluginKey("vamosSlash");
+const SlashCommand = Extension.create({
+    name: "vamosSlash",
+    priority: 200,
+    addOptions() {
+        return { store: null };
+    },
+    addProseMirrorPlugins() {
+        const store = this.options.store;
+        if (!store)
+            return [];
+        const editor = this.editor;
+        store.close.current = () => {
+            exitSuggestion(editor.view, slashPluginKey);
+            store.set(null);
+        };
+        return [
+            Suggestion({
+                editor,
+                pluginKey: slashPluginKey,
+                char: "/",
+                allowSpaces: false,
+                items: () => [],
+                allow: ({ state, range }) => {
+                    const $from = state.doc.resolve(range.from);
+                    return $from.parent.type.name === "paragraph" && !state.selection.$from.parent.type.spec.code;
+                },
+                render: () => ({
+                    onStart: (p) => store.set({ query: p.query, range: p.range, rect: p.clientRect?.() ?? null }),
+                    onUpdate: (p) => store.set({ query: p.query, range: p.range, rect: p.clientRect?.() ?? null }),
+                    onExit: () => store.set(null),
+                    onKeyDown: ({ event }) => {
+                        if (event.key === "Escape") {
+                            store.close.current?.();
+                            return true;
+                        }
+                        return store.keydown.current?.(event) ?? false;
+                    },
+                }),
+            }),
+        ];
+    },
+});
+const ID_TYPES = ["paragraph", "heading", "bulletList", "orderedList", "listItem", "blockquote", "codeBlock", "horizontalRule", "image", "table", "tableRow", "tableCell", "tableHeader", COMPONENT_BLOCK];
+export function buildExtensions(o) {
+    const richText = o.variant === "rich-text";
+    const exts = [
+        StarterKit.configure({
+            heading: { levels: richText ? [2, 3, 4] : [1, 2, 3, 4] },
+            link: {
+                openOnClick: false,
+                autolink: true,
+                linkOnPaste: true,
+                defaultProtocol: "https",
+                HTMLAttributes: { rel: "noopener noreferrer", target: null },
+                isAllowedUri: (url) => sanitizeHref(url) !== null,
+            },
+            dropcursor: { color: "var(--accent)", width: 2, class: "vui-dropcursor" },
+            trailingNode: richText ? false : { node: "paragraph", notAfter: ["paragraph"] },
+        }),
+        HighlightMark,
+        SubscriptMark,
+        SuperscriptMark,
+        VamosAttributes,
+        Placeholder.configure({
+            includeChildren: true,
+            placeholder: ({ node, editor }) => {
+                if (node.type.name === "heading")
+                    return o.t("placeholderHeading");
+                if (node.type.name === "codeBlock")
+                    return o.t("placeholderCode");
+                if (editor.isEmpty)
+                    return o.placeholder ?? (richText ? o.t("placeholderRichText") : o.t("placeholder"));
+                return richText ? "" : o.t("placeholder");
+            },
+        }),
+        UniqueID.configure({ types: ID_TYPES.filter((n) => o.blocks || !["image", "table", "tableRow", "tableCell", "tableHeader", COMPONENT_BLOCK].includes(n)), attributeName: "id", generateID: () => createBlockId() }),
+        BlockKeymap.configure({ bridge: o.bridge }),
+        SlashCommand.configure({ store: o.slash }),
+        Extension.create({
+            name: "vamosPaste",
+            addProseMirrorPlugins: () => [PasteHandler({ editor: o.getEditor, bridge: o.bridge, tables: o.blocks, images: o.blocks })],
+        }),
+    ];
+    if (o.blocks)
+        exts.push(Table.configure({ resizable: false, HTMLAttributes: { class: "vui-table" } }), TableRow, TableHeader, TableCell, ImageNode, ComponentBlockNode);
+    return exts;
+}

package/dist/editor/index.d.ts

@@ -0,0 +1,14 @@
+export { BlockEditor, BlockEditorContent, RichTextEditor, type BlockEditorProps, type BlockEditorContentProps, type BlockEditorHandle, type BlockEditorChangeInfo, type RichTextEditorProps, } from "./block-editor.js";
+export { BlockEditorBubbleMenu, BlockEditorToolbar, type BlockEditorBubbleMenuProps, type BlockEditorToolbarProps } from "./menus.js";
+export { BlockEditorSlashMenu, type BlockEditorSlashMenuProps } from "./slash-menu.js";
+export { BlockEditorDragHandle, type BlockEditorDragHandleProps } from "./drag-handle.js";
+export { BlockInserter, type BlockInserterProps } from "./inserter.js";
+export { BlockInspector, type BlockInspectorProps } from "./inspector.js";
+export { BlockEditorOutline, type BlockEditorOutlineProps } from "./outline.js";
+export { SchemaForm, type SchemaFormProps, type SchemaFieldHint, type SchemaFieldHints, type SchemaFormIssue, type WidgetComponent, type WidgetProps } from "./schema-form.js";
+export { useBlockEditor, type BlockEditorContextValue, type BlockEditorVariant, type BlockPattern, type LinkSuggestion, type ImageUploader } from "./context.js";
+export { blockEditorLabels, type BlockEditorLabels } from "./labels.js";
+export { toProseMirror, fromProseMirror, richDocToProseMirror, proseMirrorToRichDoc, inlineToPM, inlineFromPM, computeDocMeta, changedBlockIds, stableStringify, docToPlainText, countWords, createBlockId, isValidBlockId, isRichDocEmpty, COMPONENT_BLOCK, EDITOR_TEXT_TYPES, isEditorTextType, type EditorTextType, type ImageBlockProps, type TableCellProps, type FromProseMirrorOptions, } from "./convert.js";
+export { markdownToBlocks, parseInlineMarkdown, looksLikeMarkdown, cleanPastedHtml } from "./markdown.js";
+export { getTopBlock, selectBlock, moveBlock, duplicateBlock, deleteBlock, setNodeAttrs, type TopBlock } from "./commands.js";
+export { buildExtensions, HighlightMark, SubscriptMark, SuperscriptMark, type BuildExtensionsOptions } from "./extensions.js";

package/dist/editor/index.js

@@ -0,0 +1,17 @@
+// Public API of @vamos-ui/react/editor — the block / rich-text editor (Tiptap v3, admin only).
+// Websites render content with @vamos-ui/react/render and never load this entry.
+export { BlockEditor, BlockEditorContent, RichTextEditor, } from "./block-editor.js";
+export { BlockEditorBubbleMenu, BlockEditorToolbar } from "./menus.js";
+export { BlockEditorSlashMenu } from "./slash-menu.js";
+export { BlockEditorDragHandle } from "./drag-handle.js";
+export { BlockInserter } from "./inserter.js";
+export { BlockInspector } from "./inspector.js";
+export { BlockEditorOutline } from "./outline.js";
+export { SchemaForm } from "./schema-form.js";
+export { useBlockEditor } from "./context.js";
+export { blockEditorLabels } from "./labels.js";
+// Converters + doc helpers (pure, no Tiptap runtime)
+export { toProseMirror, fromProseMirror, richDocToProseMirror, proseMirrorToRichDoc, inlineToPM, inlineFromPM, computeDocMeta, changedBlockIds, stableStringify, docToPlainText, countWords, createBlockId, isValidBlockId, isRichDocEmpty, COMPONENT_BLOCK, EDITOR_TEXT_TYPES, isEditorTextType, } from "./convert.js";
+export { markdownToBlocks, parseInlineMarkdown, looksLikeMarkdown, cleanPastedHtml } from "./markdown.js";
+export { getTopBlock, selectBlock, moveBlock, duplicateBlock, deleteBlock, setNodeAttrs } from "./commands.js";
+export { buildExtensions, HighlightMark, SubscriptMark, SuperscriptMark } from "./extensions.js";

package/dist/editor/inserter.d.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+export interface BlockInserterProps {
+    /** Custom trigger. Default: an "Add block" row at the end of the canvas. `null` hides it (open via the drag handle "+"). */
+    trigger?: React.ReactNode | null;
+    className?: string;
+}
+/**
+ * The "+" inserter: a searchable popover of text blocks, page blocks and patterns, grouped by
+ * category, with a live mini preview of the highlighted block. Opens from its trigger or from
+ * the drag handle "+" (then it inserts below that block).
+ */
+export declare function BlockInserter({ trigger, className }: BlockInserterProps): React.JSX.Element | null;

package/dist/editor/inserter.js

@@ -0,0 +1,88 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Plus } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { renderDoc } from "../render/block-renderer.js";
+import { Popover, PopoverAnchor, PopoverContent } from "../components/popover.js";
+import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from "../components/command.js";
+import { useBlockEditor } from "./context.js";
+import { filterAllowed, patternItems, runInsert } from "./items.js";
+import { useInsertItems } from "./slash-menu.js";
+const GROUPS = ["text", "media", "layout", "blocks"];
+const GROUP_LABEL = { text: "groupText", media: "groupMedia", layout: "groupLayout", blocks: "groupBlocks", patterns: "groupPatterns" };
+/** A scaled, non-interactive render of a block or pattern (inserter preview). */
+function InsertPreview({ item }) {
+    const { registry, lang, t } = useBlockEditor();
+    const blocks = React.useMemo(() => {
+        if (!item)
+            return null;
+        if (item.pattern)
+            return item.pattern.doc.blocks;
+        if (item.def) {
+            const variant = item.def.defaultVariant ?? item.def.variants?.[0];
+            return [{ id: "b_preview", type: item.def.type, v: item.def.version, variant, props: item.def.sample(variant, lang) }];
+        }
+        return null;
+    }, [item, lang]);
+    if (!item)
+        return null;
+    return (_jsxs("div", { className: "vui-inserter-preview", "aria-hidden": true, children: [_jsx("p", { className: "vui-eyebrow", children: t("preview") }), blocks ? (_jsx("div", { className: "vui-inserter-stage", "data-material": "solid", children: _jsx("div", { className: "vui-inserter-scale", children: renderDoc({ version: 1, lang, blocks }, { registry, locale: lang, jsonLd: false, dev: false }) }) })) : (_jsxs("div", { className: "vui-inserter-stage vui-inserter-text", children: [_jsx(item.icon, { className: "size-5 text-fg-subtle" }), _jsx("p", { className: "text-sm font-medium text-fg", children: item.title }), item.hint ? _jsx("p", { className: "text-xs text-fg-muted", children: item.hint }) : null] })), item.hint && (blocks || item.pattern) ? _jsx("p", { className: "mt-2 text-xs text-fg-muted", children: item.hint }) : null] }));
+}
+/**
+ * The "+" inserter: a searchable popover of text blocks, page blocks and patterns, grouped by
+ * category, with a live mini preview of the highlighted block. Opens from its trigger or from
+ * the drag handle "+" (then it inserts below that block).
+ */
+export function BlockInserter({ trigger, className }) {
+    const { editor, t, inserter, openInserter, patterns, registry, lang, allowedTypes, readOnly } = useBlockEditor();
+    const items = useInsertItems();
+    const pItems = React.useMemo(() => filterAllowed(patternItems(patterns, registry), allowedTypes()), [patterns, registry, allowedTypes]);
+    const [tab, setTab] = React.useState("blocks");
+    const [highlight, setHighlight] = React.useState("");
+    const list = tab === "patterns" ? pItems : items;
+    const current = list.find((i) => i.id === highlight) ?? list[0];
+    const anchorRef = React.useRef({ getBoundingClientRect: () => new DOMRect() });
+    const triggerRef = React.useRef(null);
+    anchorRef.current = {
+        getBoundingClientRect: () => {
+            if (inserter.anchor?.isConnected)
+                return inserter.anchor.getBoundingClientRect();
+            if (editor && inserter.at !== undefined) {
+                const dom = editor.view.nodeDOM(inserter.at);
+                if (dom?.getBoundingClientRect) {
+                    const r = dom.getBoundingClientRect();
+                    return new DOMRect(r.left, r.bottom, Math.min(r.width, 1), 0);
+                }
+            }
+            return triggerRef.current?.getBoundingClientRect() ?? new DOMRect();
+        },
+    };
+    if (readOnly)
+        return null;
+    const choose = (item) => {
+        if (!editor)
+            return;
+        inserter.setOpen(false);
+        runInsert(editor, item, { lang, at: inserter.at });
+    };
+    return (_jsxs(Popover, { open: inserter.open, onOpenChange: (o) => (o ? undefined : inserter.setOpen(false)), children: [_jsx(PopoverAnchor, { virtualRef: anchorRef }), trigger === null ? null : (_jsx("div", { className: cn("vui-inserter-row", className), children: trigger ?? (_jsxs("button", { ref: triggerRef, type: "button", className: "vui-inserter-trigger focus-ring", "aria-haspopup": "dialog", "aria-expanded": inserter.open, onClick: (e) => {
+                        if (!editor)
+                            return;
+                        const anchor = e.currentTarget;
+                        // Insert at the end of the document.
+                        const doc = editor.state.doc;
+                        openInserter({ at: doc.childCount ? doc.content.size - doc.lastChild.nodeSize : 0, anchor });
+                    }, children: [_jsx(Plus, { "aria-hidden": true, className: "size-4" }), t("insert")] })) })), _jsx(PopoverContent, { size: "auto", padded: false, align: "start", side: "bottom", "aria-label": t("insert"), className: "vui-inserter w-[min(40rem,calc(100vw-1.5rem))] overflow-hidden", onCloseAutoFocus: (e) => {
+                    e.preventDefault();
+                    editor?.commands.focus();
+                }, children: _jsxs(Command, { label: t("searchBlocks"), value: current?.id ?? "", onValueChange: setHighlight, loop: true, children: [_jsx(CommandInput, { placeholder: t("searchBlocks") }), pItems.length ? (_jsx("div", { role: "tablist", "aria-label": t("insert"), className: "vui-inserter-tabs", children: ["blocks", "patterns"].map((k) => (_jsx("button", { type: "button", role: "tab", "aria-selected": tab === k, "data-active": tab === k ? "" : undefined, className: "focus-ring", onClick: () => {
+                                    setTab(k);
+                                    setHighlight("");
+                                }, children: t(k) }, k))) })) : null, _jsxs("div", { className: "grid min-h-0 sm:grid-cols-[minmax(0,1fr)_15rem]", children: [_jsxs(CommandList, { className: "max-h-[min(24rem,60dvh)] sm:border-e sm:border-line", children: [_jsx(CommandEmpty, { children: t("noBlocksPlain") }), tab === "patterns" ? (_jsx(CommandGroup, { heading: t("groupPatterns"), children: pItems.map((it) => (_jsx(CommandItem, { value: it.id, keywords: [it.title, ...it.keywords], icon: _jsx(it.icon, { className: "size-4" }), description: it.hint, onSelect: () => choose(it), children: it.title }, it.id))) })) : (GROUPS.map((g) => {
+                                            const inGroup = items.filter((i) => i.group === g);
+                                            if (!inGroup.length)
+                                                return null;
+                                            return (_jsx(CommandGroup, { heading: t(GROUP_LABEL[g]), children: inGroup.map((it) => (_jsx(CommandItem, { value: it.id, keywords: [it.title, ...it.keywords], icon: _jsx(it.icon, { className: "size-4" }), description: it.hint, onSelect: () => choose(it), children: it.title }, it.id))) }, g));
+                                        }))] }), _jsx("div", { className: "max-sm:hidden", children: _jsx(InsertPreview, { item: current }) })] })] }) })] }));
+}

package/dist/editor/inspector.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import { type WidgetComponent } from "./schema-form.js";
+export interface BlockInspectorProps {
+    className?: string;
+    /** Custom SchemaForm widgets. */
+    widgets?: Record<string, WidgetComponent>;
+    /** Shown with no selection: a button that switches the side panel to document settings. */
+    onShowDocument?: () => void;
+    /** Label of that button. Default "Document settings". */
+    documentLabel?: string;
+}
+/**
+ * Settings of the selected block, generated from its zod schema (SchemaForm): variant, every
+ * prop with its `f.*` widget, anchor and visibility. Images get alt text, caption and
+ * "decorative". Field errors come straight from validation. Put it in an `EditorPanel` tab.
+ */
+export declare function BlockInspector({ className, widgets, onShowDocument, documentLabel }: BlockInspectorProps): React.JSX.Element;

package/dist/editor/inspector.js

@@ -0,0 +1,65 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEditorState } from "@tiptap/react";
+import { NodeSelection } from "@tiptap/pm/state";
+import { MousePointerClick, PackageX, Settings2 } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { slugify } from "../lib/text.js";
+import { Field, Input, Textarea } from "../components/input.js";
+import { Switch } from "../components/switch.js";
+import { NativeSelect } from "../components/native-select.js";
+import { Button } from "../components/button.js";
+import { ToggleGroup, ToggleGroupItem } from "../components/toggle.js";
+import { useBlockEditor } from "./context.js";
+import { COMPONENT_BLOCK } from "./convert.js";
+import { setNodeAttrs } from "./commands.js";
+import { iconForBlock } from "./items.js";
+import { SchemaForm } from "./schema-form.js";
+/**
+ * Settings of the selected block, generated from its zod schema (SchemaForm): variant, every
+ * prop with its `f.*` widget, anchor and visibility. Images get alt text, caption and
+ * "decorative". Field errors come straight from validation. Put it in an `EditorPanel` tab.
+ */
+export function BlockInspector({ className, widgets, onShowDocument, documentLabel = "Document settings" }) {
+    const { editor, registry, t, lang, readOnly } = useBlockEditor();
+    const sel = useEditorState({
+        editor,
+        selector: ({ editor: e }) => {
+            if (!e)
+                return null;
+            const s = e.state.selection;
+            if (!(s instanceof NodeSelection))
+                return null;
+            const name = s.node.type.name;
+            if (name !== COMPONENT_BLOCK && name !== "image")
+                return null;
+            return { pos: s.from, name, attrs: s.node.attrs };
+        },
+        equalityFn: (a, b) => a?.pos === b?.pos && a?.attrs === b?.attrs,
+    });
+    const update = (patch) => {
+        if (editor && sel)
+            setNodeAttrs(editor, sel.pos, patch);
+    };
+    if (!sel) {
+        return (_jsxs("div", { "data-slot": "block-inspector", className: cn("vui-inspector vui-inspector-empty", className), children: [_jsx(MousePointerClick, { "aria-hidden": true, className: "size-5 text-fg-subtle" }), _jsx("p", { className: "text-sm font-medium text-fg", children: t("noSelection") }), _jsx("p", { className: "text-xs text-fg-muted", children: t("noSelectionHint") }), onShowDocument ? (_jsxs(Button, { size: "xs", variant: "ghost", onClick: onShowDocument, className: "mt-1", children: [_jsx(Settings2, { "aria-hidden": true }), documentLabel] })) : null] }));
+    }
+    if (sel.name === "image") {
+        const a = sel.attrs;
+        return (_jsxs("div", { "data-slot": "block-inspector", className: cn("vui-inspector", className), children: [_jsx(InspectorHeader, { title: t("image"), meta: "image" }), _jsxs("div", { className: "flex flex-col gap-3.5", children: [_jsx(Field, { label: t("altText"), hint: t("altTextHint"), error: !a.decorative && !String(a.alt ?? "").trim() && a.src ? t("missingAlt") : undefined, children: _jsx(Textarea, { rows: 2, value: a.alt ?? "", disabled: readOnly || !!a.decorative, onChange: (e) => update({ alt: e.target.value }) }) }), _jsx(Field, { orientation: "horizontal", label: t("decorative"), children: _jsx(Switch, { size: "sm", checked: !!a.decorative, disabled: readOnly, onCheckedChange: (c) => update({ decorative: c || null }) }) }), _jsx(Field, { label: t("caption"), children: _jsx(Input, { size: "sm", value: a.caption ?? "", disabled: readOnly, onChange: (e) => update({ caption: e.target.value || null }) }) }), _jsx(Field, { label: t("imageUrl"), children: _jsx(Input, { size: "sm", value: a.src ?? "", disabled: readOnly, onChange: (e) => update({ src: e.target.value || null }) }) })] })] }));
+    }
+    const type = String(sel.attrs.blockType ?? "");
+    const def = registry.get(type);
+    if (!def) {
+        return (_jsxs("div", { "data-slot": "block-inspector", className: cn("vui-inspector", className), children: [_jsx(InspectorHeader, { title: t("unknownBlock", { type }), meta: type, icon: _jsx(PackageX, { className: "size-4" }) }), _jsx("p", { className: "text-xs text-fg-muted", children: t("unknownBlockHint") }), _jsx("pre", { className: "vui-inspector-json", children: JSON.stringify(sel.attrs.props ?? {}, null, 2) })] }));
+    }
+    const props = (sel.attrs.props ?? {});
+    const variant = sel.attrs.variant ?? def.defaultVariant ?? def.variants?.[0];
+    const parsed = def.schema.safeParse(props);
+    const Icon = iconForBlock(def.icon);
+    const variants = def.variants ?? [];
+    return (_jsxs("div", { "data-slot": "block-inspector", className: cn("vui-inspector", className), children: [_jsx(InspectorHeader, { title: def.title, meta: `${def.type} · v${def.version}`, icon: _jsx(Icon, { className: "size-4" }), description: def.description }), variants.length > 1 ? (_jsx(Field, { label: t("variant"), children: variants.length <= 3 ? (_jsx(ToggleGroup, { "aria-label": t("variant"), size: "sm", block: true, value: variant, onValueChange: (v) => v && update({ variant: v }), disabled: readOnly, children: variants.map((v) => (_jsx(ToggleGroupItem, { value: v, children: def.variantMeta?.[v]?.label ?? v }, v))) })) : (_jsx(NativeSelect, { size: "sm", value: variant, disabled: readOnly, items: variants.map((v) => ({ value: v, label: def.variantMeta?.[v]?.label ?? v })), onChange: (e) => update({ variant: e.target.value }) })) })) : null, _jsx(SchemaForm, { schema: def.schema, value: props, onChange: (next) => update({ props: next }), fields: def.fields, widgets: widgets, errors: parsed.success ? null : parsed.error.issues, variant: variant, locale: lang, disabled: readOnly }), def.supports.anchor !== false ? (_jsxs("section", { className: "vui-sf-section", "aria-label": t("advanced"), children: [_jsx("h3", { className: "vui-eyebrow", children: t("advanced") }), _jsx(Field, { label: t("anchor"), hint: sel.attrs.anchor ? t("anchorHint", { anchor: String(sel.attrs.anchor) }) : undefined, children: _jsx(Input, { size: "sm", addonStart: "#", value: sel.attrs.anchor ?? "", disabled: readOnly, onChange: (e) => update({ anchor: slugify(e.target.value, { locale: lang }) || null }) }) }), _jsx(Field, { orientation: "horizontal", label: t("hide"), children: _jsx(Switch, { size: "sm", checked: !!sel.attrs.hidden, disabled: readOnly, onCheckedChange: (c) => update({ hidden: c || null }) }) })] })) : null] }));
+}
+function InspectorHeader({ title, meta, icon, description }) {
+    return (_jsxs("header", { className: "vui-inspector-head", children: [icon ? (_jsx("span", { "aria-hidden": true, className: "vui-inspector-icon", children: icon })) : null, _jsxs("div", { className: "min-w-0", children: [_jsx("h3", { className: "truncate text-sm font-semibold text-fg", children: title }), _jsx("p", { className: "truncate font-mono text-[10.5px] uppercase tracking-[0.08em] text-fg-subtle", children: meta }), description ? _jsx("p", { className: "mt-1 text-xs text-fg-muted", children: description }) : null] })] }));
+}

package/dist/editor/items.d.ts

@@ -0,0 +1,62 @@
+import * as React from "react";
+import type { Editor, JSONContent } from "@tiptap/react";
+import { type LucideIcon } from "lucide-react";
+import type { AnyBlockDefinition, BlockRegistry } from "../blocks/schema/define-block.js";
+import type { LabelFn } from "../lib/labels.js";
+import type { BlockEditorLabels } from "./labels.js";
+import type { BlockPattern } from "./context.js";
+export type InsertGroup = "text" | "media" | "layout" | "blocks" | "patterns";
+export interface InsertItem {
+    id: string;
+    title: string;
+    hint?: string;
+    group: InsertGroup;
+    /** Extra search terms. */
+    keywords: string[];
+    icon: LucideIcon;
+    /** Block type it creates ("heading", "hero"…); used by `allowedBlocks`. */
+    blockType: string;
+    /** Markdown shortcut shown as a hint ("#", "-", ">"). */
+    shortcut?: string;
+    def?: AnyBlockDefinition;
+    pattern?: BlockPattern;
+    /** Content for the node, built lazily. */
+    build: (lang: string) => JSONContent | JSONContent[];
+}
+export declare const iconForBlock: (name?: string) => LucideIcon;
+/** The text block items ("Text", "Heading 2", "Bulleted list"…). */
+export declare function textItems(t: LabelFn<BlockEditorLabels>, opts?: {
+    richText?: boolean;
+}): InsertItem[];
+/** One item per registered component block. */
+export declare function registryItems(registry: BlockRegistry): InsertItem[];
+export declare function patternItems(patterns: readonly BlockPattern[], registry: BlockRegistry): InsertItem[];
+/** Filters items by `allowedBlocks` (block types; patterns pass when every block inside is allowed). */
+export declare function filterAllowed(items: InsertItem[], allowed: string[] | null): InsertItem[];
+/** Inserts an item: replaces `range` (the "/query" text) or goes after the current block. Selects component blocks. */
+export declare function runInsert(editor: Editor, item: InsertItem, opts: {
+    lang: string;
+    range?: {
+        from: number;
+        to: number;
+    };
+    at?: number;
+}): number;
+/** "Turn into" targets for a text block. */
+export declare function turnIntoItems(t: LabelFn<BlockEditorLabels>): {
+    id: string;
+    label: string;
+    icon: LucideIcon;
+    run: (e: Editor) => void;
+    active: (e: Editor) => boolean;
+}[];
+/** Human title of a block node for announcements and menus. */
+export declare function blockTitle(node: {
+    type: {
+        name: string;
+    };
+    attrs: Record<string, unknown>;
+}, registry: BlockRegistry, t: LabelFn<BlockEditorLabels>): string;
+/** The block type of a PM node in VamosDoc terms (for allowedBlocks). */
+export declare function docTypeOf(name: string, attrs: Record<string, unknown>): string;
+export declare const useStableItems: (factory: () => InsertItem[], deps: React.DependencyList) => InsertItem[];