@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/editor/block-editor.js

@@ -0,0 +1,280 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { EditorContent, useEditor } from "@tiptap/react";
+import { NodeSelection, TextSelection } from "@tiptap/pm/state";
+import { cn } from "../lib/cn.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { useMediaAdapter } from "../lib/provider.js";
+import { useFieldContext, useFieldControl } from "../lib/field-context.js";
+import { useLatest } from "../lib/use-controllable-state.js";
+import { createRegistry } from "../blocks/schema/define-block.js";
+import { blockEditorLabels } from "./labels.js";
+import { BlockEditorContext, createSlashStore, useBlockEditor, } from "./context.js";
+import { buildExtensions } from "./extensions.js";
+import { changedBlockIds, stableStringify, fromProseMirror, proseMirrorToRichDoc, richDocToProseMirror, toProseMirror } from "./convert.js";
+import { blockTitle, registryItems, runInsert, textItems, filterAllowed } from "./items.js";
+import { BlockEditorBubbleMenu, BlockEditorToolbar } from "./menus.js";
+import { BlockEditorSlashMenu } from "./slash-menu.js";
+import { BlockEditorDragHandle } from "./drag-handle.js";
+import { BlockInserter } from "./inserter.js";
+const EMPTY_REGISTRY = createRegistry([]);
+/**
+ * The block editor: text blocks edited inline, page blocks rendered by the very component the
+ * site uses (via the registry), a "/" inserter, a bubble menu on selection, a drag handle with a
+ * keyboard-equivalent block menu, and a schema-generated inspector. Reads and writes `VamosDoc`.
+ *
+ * ```tsx
+ * <BlockEditor value={doc} onChange={setDoc} registry={siteBlocks} variant="document" />
+ *
+ * <BlockEditor value={doc} onChange={setDoc} registry={siteBlocks}>
+ *   <BlockEditorContent />
+ *   <BlockEditorBubbleMenu />
+ *   <BlockEditorSlashMenu />
+ *   <BlockEditorDragHandle />
+ *   <aside><BlockInspector /></aside>
+ * </BlockEditor>
+ * ```
+ */
+export function BlockEditor(props) {
+    const { value, defaultValue, onChange, registry = EMPTY_REGISTRY, variant = "document", size = "md", allowedBlocks, patterns = [], placeholder, readOnly = false, media: mediaProp, uploadImage: uploadProp, linkSearch, lang: langProp, editorRef, autoFocus, labels, format = "doc", richValue, defaultRichValue, onRichChange, a11y, children, } = props;
+    const t = useLabels("blockEditor", blockEditorLabels, labels);
+    const { locale } = useLocale();
+    const providerMedia = useMediaAdapter();
+    const media = mediaProp ?? providerMedia ?? undefined;
+    const initialDoc = value ?? defaultValue;
+    const lang = langProp ?? initialDoc?.lang ?? locale.split("-")[0] ?? "en";
+    const richText = variant === "rich-text";
+    const uploadImage = React.useMemo(() => {
+        if (uploadProp)
+            return uploadProp;
+        if (!media?.upload)
+            return undefined;
+        return async (file, opts) => {
+            const asset = await media.upload(file, { signal: opts.signal, onProgress: opts.onProgress ?? (() => { }) });
+            return { src: asset.url, alt: asset.alt, width: asset.width, height: asset.height, assetId: asset.id };
+        };
+    }, [uploadProp, media]);
+    // ---------------------------------------------------------------- announcements
+    const [message, setMessage] = React.useState("");
+    const announce = React.useCallback((m) => {
+        setMessage("");
+        requestAnimationFrame?.(() => setMessage(m));
+    }, []);
+    const slash = React.useMemo(() => createSlashStore(), []);
+    const toolbarRef = React.useRef(null);
+    const editorHolder = React.useRef(null);
+    const bridge = React.useRef(null);
+    bridge.current = {
+        t,
+        announce,
+        title: (node) => blockTitle(node, registry, t),
+        focusToolbar: () => {
+            const el = toolbarRef.current?.querySelector("button:not([disabled])");
+            if (!el)
+                return false;
+            el.focus();
+            return true;
+        },
+        uploader: readOnly ? undefined : uploadImage,
+    };
+    const baseDoc = React.useRef(initialDoc);
+    const lastDoc = React.useRef(initialDoc);
+    const lastRich = React.useRef(richValue ?? defaultRichValue);
+    const onChangeRef = useLatest(onChange);
+    const onRichRef = useLatest(onRichChange);
+    const timer = React.useRef(null);
+    const emit = React.useCallback(() => {
+        timer.current = null;
+        const ed = editorHolder.current;
+        if (!ed || ed.isDestroyed)
+            return;
+        const json = ed.getJSON();
+        if (format === "rich") {
+            const rich = proseMirrorToRichDoc(json);
+            if (stableStringify(rich) === stableStringify(lastRich.current ?? { type: "doc", content: [] }))
+                return;
+            lastRich.current = rich;
+            onRichRef.current?.(rich);
+            return;
+        }
+        const doc = fromProseMirror(json, { base: baseDoc.current, lang });
+        if (lastDoc.current && stableStringify(doc.blocks) === stableStringify(lastDoc.current.blocks))
+            return;
+        const changed = changedBlockIds(lastDoc.current, doc);
+        lastDoc.current = doc;
+        onChangeRef.current?.(doc, { wordCount: doc.meta?.wordCount ?? 0, changedBlockIds: changed });
+    }, [format, lang, onChangeRef, onRichRef]);
+    const initialContent = React.useMemo(() => (format === "rich" ? richDocToProseMirror(richValue ?? defaultRichValue) : toProseMirror(initialDoc ?? { version: 1, blocks: [] }, registry)), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    const editor = useEditor({
+        extensions: buildExtensions({ variant, t, placeholder, slash: readOnly ? null : slash, bridge, getEditor: () => editorHolder.current, blocks: !richText }),
+        content: initialContent,
+        editable: !readOnly,
+        immediatelyRender: false,
+        shouldRerenderOnTransaction: false,
+        autofocus: autoFocus ? "end" : false,
+        editorProps: {
+            attributes: {
+                role: "textbox",
+                "aria-multiline": "true",
+                spellcheck: "true",
+                class: cn("vui-editor-prose prose-ui vb-prose", richText && size === "sm" && "prose-ui-sm"),
+            },
+        },
+        onCreate: ({ editor: ed }) => {
+            editorHolder.current = ed;
+            // Start with a caret in the first text block, not a selected page block.
+            if (ed.state.selection instanceof NodeSelection) {
+                const sel = TextSelection.findFrom(ed.state.doc.resolve(0), 1, true);
+                if (sel)
+                    ed.view.dispatch(ed.state.tr.setSelection(sel).setMeta("addToHistory", false));
+            }
+        },
+        onUpdate: () => {
+            if (timer.current)
+                clearTimeout(timer.current);
+            timer.current = setTimeout(emit, 300);
+        },
+        onBlur: () => {
+            if (timer.current) {
+                clearTimeout(timer.current);
+                emit();
+            }
+        },
+    }, [variant, richText]);
+    editorHolder.current = editor;
+    // Flush pending changes on unmount.
+    React.useEffect(() => () => {
+        if (timer.current) {
+            clearTimeout(timer.current);
+            emit();
+        }
+    }, [emit]);
+    React.useEffect(() => {
+        editor?.setEditable(!readOnly);
+    }, [editor, readOnly]);
+    // Controlled value: replace content only when the value differs from what we last emitted.
+    React.useEffect(() => {
+        if (!editor || format !== "doc" || !value || value === lastDoc.current)
+            return;
+        if (lastDoc.current && stableStringify(value.blocks) === stableStringify(lastDoc.current.blocks)) {
+            lastDoc.current = value;
+            baseDoc.current = value;
+            return;
+        }
+        baseDoc.current = value;
+        lastDoc.current = value;
+        editor.commands.setContent(toProseMirror(value, registry), { emitUpdate: false });
+    }, [editor, value, registry, format]);
+    React.useEffect(() => {
+        if (!editor || format !== "rich" || !richValue || richValue === lastRich.current)
+            return;
+        if (stableStringify(richValue) === stableStringify(lastRich.current))
+            return;
+        lastRich.current = richValue;
+        editor.commands.setContent(richDocToProseMirror(richValue), { emitUpdate: false });
+    }, [editor, richValue, format]);
+    // ---------------------------------------------------------------- allowed blocks, inserter
+    const allowedRef = useLatest(allowedBlocks);
+    const allowedTypes = React.useCallback((parentType) => {
+        const a = allowedRef.current;
+        if (!a)
+            return null;
+        return typeof a === "function" ? a({ parentType }) : a;
+    }, [allowedRef]);
+    const [inserter, setInserter] = React.useState({ open: false });
+    const openInserter = React.useCallback((req) => setInserter({ open: true, at: req?.at, anchor: req?.anchor }), []);
+    React.useImperativeHandle(editorRef, () => ({
+        focus: () => editor?.commands.focus(),
+        insertBlock: (type, props) => {
+            if (!editor)
+                return;
+            const items = filterAllowed([...textItems(t, { richText }), ...registryItems(registry)], null);
+            const item = items.find((i) => i.id === type || i.id === `block:${type}` || i.blockType === type);
+            if (!item)
+                return;
+            const patched = props && item.def ? { ...item, build: (l) => {
+                    const c = item.build(l);
+                    return { ...c, attrs: { ...c.attrs, props: { ...c.attrs?.props, ...props } } };
+                } } : item;
+            runInsert(editor, patched, { lang });
+        },
+        getDoc: () => (editor ? fromProseMirror(editor.getJSON(), { base: baseDoc.current, lang }) : (lastDoc.current ?? { version: 1, blocks: [] })),
+        undo: () => editor?.commands.undo(),
+        redo: () => editor?.commands.redo(),
+        editor,
+    }), [editor, registry, t, lang, richText]);
+    const ctx = {
+        editor,
+        registry,
+        variant,
+        size,
+        readOnly,
+        lang,
+        t,
+        allowedTypes,
+        patterns,
+        media,
+        uploadImage: readOnly ? undefined : uploadImage,
+        linkSearch,
+        slash,
+        announce,
+        openInserter,
+        inserter: { open: inserter.open, at: inserter.at, anchor: inserter.anchor, setOpen: (open) => setInserter((s) => ({ ...s, open })) },
+        toolbarRef,
+        editorLabel: props["aria-label"] ?? t("editorLabel"),
+        canvasTheme: props.canvasTheme,
+        placeholder,
+        a11y: { ...a11y, labelledBy: props["aria-labelledby"] ?? a11y?.labelledBy },
+    };
+    const content = children ??
+        (richText ? (_jsxs(_Fragment, { children: [props.toolbar === false || readOnly ? null : _jsx(BlockEditorToolbar, {}), _jsx(BlockEditorContent, {}), readOnly ? null : _jsx(BlockEditorBubbleMenu, {}), readOnly ? null : _jsx(BlockEditorSlashMenu, {})] })) : (_jsxs(_Fragment, { children: [_jsx(BlockEditorContent, {}), readOnly ? null : (_jsxs(_Fragment, { children: [_jsx(BlockEditorBubbleMenu, {}), _jsx(BlockEditorSlashMenu, {}), _jsx(BlockEditorDragHandle, {}), _jsx(BlockInserter, {})] }))] })));
+    return (_jsx(BlockEditorContext.Provider, { value: ctx, children: _jsxs("div", { "data-slot": "block-editor", "data-variant": variant, "data-size": richText ? size : undefined, "data-readonly": readOnly ? "" : undefined, "data-invalid": a11y?.invalid ? "" : undefined, className: cn("vui-editor", props.className), style: richText ? { "--editor-min-h": props.minHeight, "--editor-max-h": props.maxHeight } : undefined, children: [content, _jsx("div", { role: "status", "aria-live": "polite", "aria-atomic": "true", className: "sr-only", children: message })] }) }));
+}
+/**
+ * The editable canvas. Wears the site theme (`canvasTheme`) and is always `solid`, even inside a
+ * glass admin, for long-text readability and scroll performance.
+ */
+export const BlockEditorContent = React.forwardRef(function BlockEditorContent({ className, ...props }, ref) {
+    const { editor, variant, lang, editorLabel, a11y, readOnly, size, canvasTheme = {} } = useBlockEditor();
+    // ARIA on the contenteditable element (Tiptap owns the node).
+    React.useEffect(() => {
+        const dom = editor?.view.dom;
+        if (!dom)
+            return;
+        const set = (k, v) => (v ? dom.setAttribute(k, v) : dom.removeAttribute(k));
+        set("aria-label", a11y?.labelledBy ? null : editorLabel);
+        set("aria-labelledby", a11y?.labelledBy);
+        set("aria-describedby", a11y?.describedBy);
+        set("aria-invalid", a11y?.invalid ? "true" : null);
+        set("aria-required", a11y?.required ? "true" : null);
+        set("aria-readonly", readOnly ? "true" : null);
+        set("id", a11y?.id);
+        set("lang", lang);
+    }, [editor, editorLabel, a11y?.labelledBy, a11y?.describedBy, a11y?.invalid, a11y?.required, a11y?.id, readOnly, lang]);
+    return (_jsx("div", { ref: ref, "data-slot": "block-editor-content", "data-material": variant === "rich-text" ? undefined : "solid", "data-accent": canvasTheme.accent, "data-font": canvasTheme.font, "data-density": canvasTheme.density, className: cn("vui-editor-canvas", variant !== "rich-text" && canvasTheme.theme, className), lang: lang, ...props, children: editor ? (_jsx(EditorContent, { editor: editor, className: "vui-editor-root" })) : (_jsx("div", { className: "vui-editor-root", "aria-hidden": true, children: _jsx("div", { className: cn("vui-editor-prose prose-ui vb-prose", variant === "rich-text" && size === "sm" && "prose-ui-sm") }) })) }));
+});
+/**
+ * Compact rich-text field for notes, comments, CRM activities and HR announcements. Same engine
+ * as BlockEditor (`variant="rich-text"`), RichDoc in and out, Field-aware like Textarea.
+ *
+ * ```tsx
+ * <Field label="Note" hint="Visible to your team only.">
+ *   <RichTextEditor value={note} onChange={setNote} size="sm" minHeight="6rem" />
+ * </Field>
+ * ```
+ */
+export function RichTextEditor({ value, defaultValue, onChange, id, invalid, required, "aria-describedby": describedBy, "aria-labelledby": labelledBy, ...rest }) {
+    const field = useFieldContext();
+    const control = useFieldControl({ id, "aria-describedby": describedBy, "aria-invalid": invalid || undefined, required });
+    return (_jsx(BlockEditor, { ...rest, variant: "rich-text", format: "rich", richValue: value, defaultRichValue: defaultValue, onRichChange: onChange, a11y: {
+            id: control.id,
+            describedBy: control["aria-describedby"],
+            invalid: !!control["aria-invalid"],
+            required: !!control.required,
+            labelledBy: labelledBy ?? field?.labelId,
+        } }));
+}

package/dist/editor/commands.d.ts

@@ -0,0 +1,31 @@
+import type { Editor, JSONContent } from "@tiptap/react";
+import type { Node as PMNode } from "@tiptap/pm/model";
+export interface TopBlock {
+    /** Position before the node. */
+    pos: number;
+    node: PMNode;
+    index: number;
+}
+/** The top-level block containing the selection (or the selected top-level node). */
+export declare function getTopBlock(editor: Editor): TopBlock | null;
+/** The top-level block at a document position. */
+export declare function topBlockAt(editor: Editor, pos: number): TopBlock | null;
+export declare const isBlockSelection: (editor: Editor) => boolean;
+/** Selects a whole top-level block (block-selection mode). */
+export declare function selectBlock(editor: Editor, pos: number): boolean;
+/** Moves the block selection to the previous / next top-level block. */
+export declare function selectSibling(editor: Editor, dir: -1 | 1): TopBlock | null;
+/** Leaves block-selection mode: cursor at the end of a text block. */
+export declare function editBlock(editor: Editor): boolean;
+/** Moves the current top-level block one step up or down. Keeps it selected. */
+export declare function moveBlock(editor: Editor, dir: -1 | 1, at?: number): TopBlock | null;
+/** JSON of a node with every `id` attribute cleared (the unique-id plugin assigns new ones). */
+export declare function withoutIds(json: JSONContent): JSONContent;
+/** Duplicates the current top-level block below itself and selects the copy. */
+export declare function duplicateBlock(editor: Editor, at?: number): TopBlock | null;
+/** Deletes the current top-level block. Selection lands on the neighbour. */
+export declare function deleteBlock(editor: Editor, at?: number): TopBlock | null;
+/** Sets attributes of the node at `pos` without losing a node selection on it. */
+export declare function setNodeAttrs(editor: Editor, pos: number, patch: Record<string, unknown>): boolean;
+/** Inserts content after the top-level block at `pos` (or after the current one). */
+export declare function insertAfterBlock(editor: Editor, content: JSONContent | JSONContent[], at?: number): number;

package/dist/editor/commands.js

@@ -0,0 +1,150 @@
+// Block-level commands on the Tiptap editor: find / select / move / duplicate / delete the
+// top-level block around the selection. Every drag action has a keyboard + menu twin here (WCAG 2.5.7).
+import { NodeSelection, TextSelection } from "@tiptap/pm/state";
+import { COMPONENT_BLOCK } from "./convert.js";
+/** The top-level block containing the selection (or the selected top-level node). */
+export function getTopBlock(editor) {
+    const { state } = editor;
+    const sel = state.selection;
+    if (sel instanceof NodeSelection && sel.$from.depth === 0) {
+        return { pos: sel.from, node: sel.node, index: sel.$from.index(0) };
+    }
+    const $from = sel.$from;
+    if ($from.depth < 1) {
+        const node = state.doc.nodeAt(sel.from);
+        return node ? { pos: sel.from, node, index: $from.index(0) } : null;
+    }
+    const index = $from.index(0);
+    const pos = $from.before(1);
+    return { pos, node: state.doc.child(index), index };
+}
+/** The top-level block at a document position. */
+export function topBlockAt(editor, pos) {
+    const doc = editor.state.doc;
+    if (pos < 0 || pos > doc.content.size)
+        return null;
+    const $pos = doc.resolve(pos);
+    if ($pos.depth === 0) {
+        const node = doc.nodeAt(pos);
+        return node ? { pos, node, index: $pos.index(0) } : null;
+    }
+    return { pos: $pos.before(1), node: doc.child($pos.index(0)), index: $pos.index(0) };
+}
+export const isBlockSelection = (editor) => editor.state.selection instanceof NodeSelection && editor.state.selection.$from.depth === 0;
+/** Selects a whole top-level block (block-selection mode). */
+export function selectBlock(editor, pos) {
+    const node = editor.state.doc.nodeAt(pos);
+    if (!node)
+        return false;
+    const tr = editor.state.tr.setSelection(NodeSelection.create(editor.state.doc, pos)).scrollIntoView();
+    editor.view.dispatch(tr);
+    return true;
+}
+/** Moves the block selection to the previous / next top-level block. */
+export function selectSibling(editor, dir) {
+    const cur = getTopBlock(editor);
+    if (!cur)
+        return null;
+    const doc = editor.state.doc;
+    const index = cur.index + dir;
+    if (index < 0 || index >= doc.childCount)
+        return null;
+    let pos = 0;
+    for (let i = 0; i < index; i++)
+        pos += doc.child(i).nodeSize;
+    selectBlock(editor, pos);
+    return { pos, node: doc.child(index), index };
+}
+/** Leaves block-selection mode: cursor at the end of a text block. */
+export function editBlock(editor) {
+    const sel = editor.state.selection;
+    if (!(sel instanceof NodeSelection) || sel.node.isAtom || sel.node.isLeaf || sel.node.type.name === COMPONENT_BLOCK)
+        return false;
+    const end = sel.from + sel.node.nodeSize - 1;
+    const tr = editor.state.tr.setSelection(TextSelection.near(editor.state.doc.resolve(end), -1));
+    editor.view.dispatch(tr);
+    return true;
+}
+/** Moves the current top-level block one step up or down. Keeps it selected. */
+export function moveBlock(editor, dir, at) {
+    const cur = at === undefined ? getTopBlock(editor) : topBlockAt(editor, at);
+    if (!cur)
+        return null;
+    const doc = editor.state.doc;
+    const targetIndex = cur.index + dir;
+    if (targetIndex < 0 || targetIndex >= doc.childCount)
+        return null;
+    const sibling = doc.child(targetIndex);
+    const wasBlockSel = isBlockSelection(editor) || at !== undefined;
+    const sel = editor.state.selection;
+    const offset = sel.from - cur.pos;
+    const tr = editor.state.tr;
+    tr.delete(cur.pos, cur.pos + cur.node.nodeSize);
+    const insertAt = dir === -1 ? cur.pos - sibling.nodeSize : cur.pos + sibling.nodeSize;
+    tr.insert(insertAt, cur.node);
+    if (wasBlockSel)
+        tr.setSelection(NodeSelection.create(tr.doc, insertAt));
+    else
+        tr.setSelection(TextSelection.near(tr.doc.resolve(Math.min(insertAt + offset, tr.doc.content.size))));
+    editor.view.dispatch(tr.scrollIntoView());
+    return { pos: insertAt, node: cur.node, index: targetIndex };
+}
+/** JSON of a node with every `id` attribute cleared (the unique-id plugin assigns new ones). */
+export function withoutIds(json) {
+    const out = { ...json };
+    if (out.attrs && "id" in out.attrs)
+        out.attrs = { ...out.attrs, id: null };
+    if (out.content)
+        out.content = out.content.map(withoutIds);
+    return out;
+}
+/** Duplicates the current top-level block below itself and selects the copy. */
+export function duplicateBlock(editor, at) {
+    const cur = at === undefined ? getTopBlock(editor) : topBlockAt(editor, at);
+    if (!cur)
+        return null;
+    const copy = editor.schema.nodeFromJSON(withoutIds(cur.node.toJSON()));
+    const insertAt = cur.pos + cur.node.nodeSize;
+    const tr = editor.state.tr.insert(insertAt, copy);
+    tr.setSelection(NodeSelection.create(tr.doc, insertAt));
+    editor.view.dispatch(tr.scrollIntoView());
+    return { pos: insertAt, node: copy, index: cur.index + 1 };
+}
+/** Deletes the current top-level block. Selection lands on the neighbour. */
+export function deleteBlock(editor, at) {
+    const cur = at === undefined ? getTopBlock(editor) : topBlockAt(editor, at);
+    if (!cur)
+        return null;
+    const tr = editor.state.tr.delete(cur.pos, cur.pos + cur.node.nodeSize);
+    if (tr.doc.childCount === 0)
+        tr.insert(0, editor.schema.nodes.paragraph.create());
+    const pos = Math.min(cur.pos, tr.doc.content.size);
+    tr.setSelection(TextSelection.near(tr.doc.resolve(pos)));
+    editor.view.dispatch(tr.scrollIntoView());
+    return cur;
+}
+/** Sets attributes of the node at `pos` without losing a node selection on it. */
+export function setNodeAttrs(editor, pos, patch) {
+    const node = editor.state.doc.nodeAt(pos);
+    if (!node)
+        return false;
+    const keepSelection = editor.state.selection instanceof NodeSelection && editor.state.selection.from === pos;
+    const tr = editor.state.tr.setNodeMarkup(pos, undefined, { ...node.attrs, ...patch });
+    if (keepSelection)
+        tr.setSelection(NodeSelection.create(tr.doc, pos));
+    editor.view.dispatch(tr);
+    return true;
+}
+/** Inserts content after the top-level block at `pos` (or after the current one). */
+export function insertAfterBlock(editor, content, at) {
+    const cur = at === undefined ? getTopBlock(editor) : topBlockAt(editor, at);
+    const doc = editor.state.doc;
+    // Replace an empty paragraph instead of leaving it behind.
+    if (cur && cur.node.type.name === "paragraph" && cur.node.content.size === 0) {
+        editor.chain().insertContentAt({ from: cur.pos, to: cur.pos + cur.node.nodeSize }, content).run();
+        return cur.pos;
+    }
+    const pos = cur ? cur.pos + cur.node.nodeSize : doc.content.size;
+    editor.chain().insertContentAt(pos, content).run();
+    return pos;
+}

package/dist/editor/context.d.ts

@@ -0,0 +1,108 @@
+import * as React from "react";
+import type { Editor } from "@tiptap/react";
+import type { BlockRegistry } from "../blocks/schema/define-block.js";
+import type { VamosDoc } from "../blocks/schema/types.js";
+import type { MediaAdapter } from "../media/types.js";
+import type { LabelFn } from "../lib/labels.js";
+import type { BlockEditorLabels } from "./labels.js";
+export type BlockEditorVariant = "document" | "canvas" | "rich-text";
+export interface BlockPattern {
+    id: string;
+    title: string;
+    category: string;
+    description?: string;
+    doc: VamosDoc;
+}
+export interface LinkSuggestion {
+    title: string;
+    href: string;
+    type: string;
+}
+/** Uploads a dropped / pasted image and returns what the image node stores. */
+export type ImageUploader = (file: File, opts: {
+    signal: AbortSignal;
+    onProgress?: (p: {
+        loaded: number;
+        total: number;
+    }) => void;
+}) => Promise<{
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    assetId?: string;
+}>;
+/** State of the "/" menu, written by the suggestion plugin and read by `BlockEditorSlashMenu`. */
+export interface SlashState {
+    query: string;
+    range: {
+        from: number;
+        to: number;
+    };
+    rect: DOMRect | null;
+}
+export interface SlashStore {
+    get(): SlashState | null;
+    set(s: SlashState | null): void;
+    subscribe(cb: () => void): () => void;
+    /** Keydown forwarded from the editor while the menu is open. Returns true when handled. */
+    keydown: {
+        current: ((e: KeyboardEvent) => boolean) | null;
+    };
+    close: {
+        current: (() => void) | null;
+    };
+}
+export declare function createSlashStore(): SlashStore;
+export interface InserterRequest {
+    /** Insert after the top-level block at this position. Default: after the current block. */
+    at?: number;
+    /** Element the popover anchors to (the "+" that opened it). Default: the block at `at`. */
+    anchor?: HTMLElement | null;
+}
+export interface BlockEditorContextValue {
+    editor: Editor | null;
+    registry: BlockRegistry;
+    variant: BlockEditorVariant;
+    size: "sm" | "md";
+    readOnly: boolean;
+    lang: string;
+    t: LabelFn<BlockEditorLabels>;
+    allowedTypes: (parentType?: string) => string[] | null;
+    patterns: BlockPattern[];
+    media?: MediaAdapter;
+    uploadImage?: ImageUploader;
+    linkSearch?: (q: string) => Promise<LinkSuggestion[]>;
+    slash: SlashStore;
+    announce: (message: string) => void;
+    /** Opens the inserter (drag handle "+", empty-state hint). */
+    openInserter: (req?: InserterRequest) => void;
+    inserter: {
+        open: boolean;
+        at?: number;
+        anchor?: HTMLElement | null;
+        setOpen: (open: boolean) => void;
+    };
+    /** Bubble/fixed toolbar registers itself so Alt+F10 can focus it. */
+    toolbarRef: React.MutableRefObject<HTMLElement | null>;
+    editorLabel: string;
+    canvasTheme?: {
+        accent?: string;
+        font?: string;
+        density?: string;
+        theme?: "light" | "dark";
+    };
+    placeholder?: string;
+    /** Field wiring for the rich-text variant (id, aria-describedby, invalid). */
+    a11y?: {
+        id?: string;
+        describedBy?: string;
+        invalid?: boolean;
+        required?: boolean;
+        labelledBy?: string;
+    };
+}
+export declare const BlockEditorContext: React.Context<BlockEditorContextValue | null>;
+/** The surrounding `BlockEditor` (editor instance, registry, labels…). */
+export declare function useBlockEditor(): BlockEditorContextValue;
+export declare function useSlashState(store: SlashStore): SlashState | null;

package/dist/editor/context.js

@@ -0,0 +1,30 @@
+"use client";
+import * as React from "react";
+export function createSlashStore() {
+    let state = null;
+    const subs = new Set();
+    return {
+        get: () => state,
+        set(s) {
+            state = s;
+            subs.forEach((cb) => cb());
+        },
+        subscribe(cb) {
+            subs.add(cb);
+            return () => subs.delete(cb);
+        },
+        keydown: { current: null },
+        close: { current: null },
+    };
+}
+export const BlockEditorContext = React.createContext(null);
+/** The surrounding `BlockEditor` (editor instance, registry, labels…). */
+export function useBlockEditor() {
+    const ctx = React.useContext(BlockEditorContext);
+    if (!ctx)
+        throw new Error("Block editor parts must be rendered inside <BlockEditor>.");
+    return ctx;
+}
+export function useSlashState(store) {
+    return React.useSyncExternalStore(store.subscribe, store.get, () => null);
+}

package/dist/editor/convert.d.ts

@@ -0,0 +1,66 @@
+import type { JSONContent } from "@tiptap/react";
+import type { RichDoc, RichInline } from "../blocks/schema/rich-doc.js";
+import type { BlockRegistry } from "../blocks/schema/define-block.js";
+import type { DocMeta, ImageRef, VamosDoc } from "../blocks/schema/types.js";
+/** ProseMirror node name of component blocks (hero, pricing, FAQ…). */
+export declare const COMPONENT_BLOCK = "vamosBlock";
+/** Block types the editor edits as native text (everything else is a component block). */
+export declare const EDITOR_TEXT_TYPES: readonly ["paragraph", "heading", "list", "list-item", "quote", "code", "divider", "image", "table", "table-row", "table-cell"];
+export type EditorTextType = (typeof EDITOR_TEXT_TYPES)[number];
+export declare const isEditorTextType: (t: string) => t is EditorTextType;
+/** Props of an `image` node (flat, see BLOCK-FORMAT §2 "Media in content"). */
+export interface ImageBlockProps {
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    caption?: string;
+    focal?: ImageRef["focal"];
+    assetId?: string;
+    decorative?: boolean;
+}
+/** Props of a `table-cell` node. */
+export interface TableCellProps {
+    header?: boolean;
+    colspan?: number;
+    rowspan?: number;
+}
+/** A new stable block id (`b_` + 8 random characters). */
+export declare function createBlockId(): string;
+export declare const isValidBlockId: (id: unknown) => id is string;
+/** Inline runs → ProseMirror inline nodes (`br` → hardBreak, stray `\n` tolerated). */
+export declare function inlineToPM(content: readonly RichInline[] | undefined): JSONContent[];
+/** ProseMirror inline nodes → inline runs (adjacent runs with equal marks merged). */
+export declare function inlineFromPM(nodes: readonly JSONContent[] | undefined): RichInline[];
+/**
+ * A VamosDoc as a ProseMirror document. With a `registry`, the doc and every component block are
+ * first migrated to their current version, so the editor always works on current props.
+ * Unknown block types become component blocks too: their data is carried untouched.
+ */
+export declare function toProseMirror(doc: VamosDoc | unknown, registry?: BlockRegistry): JSONContent;
+export interface FromProseMirrorOptions {
+    /** Doc-level fields (lang, seo, layout, locales…) to keep. `blocks` and `meta` are replaced. */
+    base?: Partial<VamosDoc>;
+    /** Content language for word counts. Default `base.lang ?? "en"`. */
+    lang?: string;
+    /** Write `meta` (word count, reading time, toc). Default true. */
+    meta?: boolean;
+}
+/** A ProseMirror document (JSON) as a VamosDoc. Missing or duplicate ids are replaced. */
+export declare function fromProseMirror(json: JSONContent, opts?: FromProseMirrorOptions): VamosDoc;
+/** Word count with `Intl.Segmenter(lang, { granularity: "word" })` (regex fallback). */
+export declare function countWords(text: string, lang?: string): number;
+/** Plain text of the editable text in a doc (component block props are not included). */
+export declare function docToPlainText(doc: VamosDoc): string;
+/** Derived doc meta: word count, reading time (230 wpm, min 1) and the heading outline. */
+export declare function computeDocMeta(doc: VamosDoc, lang?: string): DocMeta;
+/** JSON with sorted object keys: equal content compares equal regardless of key order. */
+export declare function stableStringify(v: unknown): string;
+/** Ids of top-level blocks that were added, removed or changed between two docs. */
+export declare function changedBlockIds(prev: VamosDoc | undefined, next: VamosDoc): string[];
+/** A RichDoc (the value of an `f.rich()` field) as a ProseMirror document. */
+export declare function richDocToProseMirror(doc: RichDoc | undefined | null): JSONContent;
+/** A ProseMirror document as a RichDoc. Headings are clamped to h2–h4 (rich fields never hold h1). */
+export declare function proseMirrorToRichDoc(json: JSONContent): RichDoc;
+/** True when a RichDoc has no text at all. */
+export declare function isRichDocEmpty(doc: RichDoc | undefined | null): boolean;