@markup-carve/carve-grammars 0.1.2

package/tiptap/extensions/carve-embed.js

@@ -0,0 +1,248 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+import { carveMediaDirective } from '../serializer.js';
+
+/**
+ * A preview iframe URL for the node view. Prefer an explicit embed src captured
+ * from the render; otherwise derive one from the Carve source directive so the
+ * player still shows after an inline edit.
+ *
+ * @param {object} attrs - carveEmbed node attrs.
+ * @returns {string} An https URL to embed, or '' if none can be derived.
+ */
+function embedPreviewSrc(attrs) {
+    if (attrs.src) {
+        return attrs.src.startsWith('//') ? `https:${attrs.src}` : attrs.src;
+    }
+    const source = attrs.carveSource || '';
+    let m = source.match(/^:youtube\[([\w-]+)\]/i);
+    if (m) return `https://www.youtube.com/embed/${m[1]}`;
+    m = source.match(/^:vimeo\[(\d+)\]/i);
+    if (m) return `https://player.vimeo.com/video/${m[1]}`;
+    m = source.match(/^:media\[([^\]]+)\]/i);
+    if (m) return m[1].startsWith('//') ? `https:${m[1]}` : m[1];
+    return '';
+}
+
+/**
+ * Carve Embed node extension for Tiptap
+ *
+ * Preserves video embeds, iframes, and oEmbed content during round-trips.
+ * Stores the original Carve source (e.g., YouTube URL) in data-carve-src.
+ *
+ * @example
+ * ```js
+ * import { CarveEmbed } from 'carve-grammars/tiptap'
+ *
+ * const editor = new Editor({
+ *   extensions: [CarveEmbed],
+ * })
+ *
+ * // Insert an embed
+ * editor.chain().focus().setCarveEmbed({
+ *   src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+ *   html: '<iframe...></iframe>',
+ * }).run()
+ * ```
+ */
+export const CarveEmbed = Node.create({
+    name: 'carveEmbed',
+
+    group: 'block',
+
+    atom: true,
+
+    addAttributes() {
+        return {
+            // The exact Carve source stamped by the renderer (data-carve-source),
+            // e.g. ":youtube[id]" or ":media[url]". When present it is emitted
+            // verbatim on serialize - lossless for every provider, no guessing.
+            carveSource: {
+                default: null,
+                parseHTML: element => element.getAttribute('data-carve-source')
+                    || element.querySelector('[data-carve-source]')?.getAttribute('data-carve-source')
+                    || null,
+                renderHTML: attributes => {
+                    if (!attributes.carveSource) return {};
+                    return { 'data-carve-source': attributes.carveSource };
+                },
+            },
+            src: {
+                default: null,
+                parseHTML: element => {
+                    // Check for data-carve-src first
+                    const carveSrc = element.getAttribute('data-carve-src');
+                    if (carveSrc) return carveSrc;
+                    // The element may BE the iframe (matched by the tag rule) or
+                    // wrap one.
+                    if (element.tagName === 'IFRAME') return element.getAttribute('src');
+                    const iframe = element.querySelector('iframe');
+                    if (iframe) return iframe.getAttribute('src');
+                    // Check for video source
+                    const video = element.querySelector('video source');
+                    if (video) return video.getAttribute('src');
+                    return null;
+                },
+                renderHTML: attributes => {
+                    if (!attributes.src) return {};
+                    return { 'data-carve-src': attributes.src };
+                },
+            },
+            html: {
+                default: null,
+                // Keep the full original embed markup so the editor previews the
+                // real player (all iframe attributes: allow, referrerpolicy, ...),
+                // not a stripped-down reconstruction.
+                parseHTML: element => {
+                    if (element.tagName === 'IFRAME') return element.outerHTML;
+                    const iframe = element.querySelector('iframe');
+                    if (iframe) return iframe.outerHTML;
+                    return element.innerHTML || null;
+                },
+                renderHTML: () => ({}),
+            },
+        };
+    },
+
+    parseHTML() {
+        return [
+            // Match WordPress embed wrappers
+            { tag: 'figure.wp-block-embed' },
+            { tag: 'div.wp-block-embed' },
+            // Match wpcarve-embed class
+            { tag: 'figure.wpcarve-embed' },
+            { tag: 'div.wpcarve-embed' },
+            // A source-stamped element round-trips exactly - match it first.
+            { tag: '[data-carve-source]', priority: 60 },
+            // Match elements with data-carve-src
+            { tag: '[data-carve-src]' },
+            // Match iframes that look like video embeds
+            {
+                tag: 'iframe',
+                getAttrs: element => {
+                    const src = element.getAttribute('src') || '';
+                    // Only match video embed iframes
+                    if (src.includes('youtube') || src.includes('vimeo') ||
+                        src.includes('dailymotion') || src.includes('wistia')) {
+                        return {};
+                    }
+                    return false;
+                },
+            },
+        ];
+    },
+
+    renderHTML({ HTMLAttributes, node }) {
+        const wrapper = document.createElement('div');
+        wrapper.innerHTML = node.attrs.html || '';
+
+        return ['figure', mergeAttributes(HTMLAttributes, {
+            class: 'wpcarve-embed',
+            'data-carve-src': node.attrs.src,
+        }), node.attrs.html ? ['div', { innerHTML: node.attrs.html }] : ['p', 'Embedded content']];
+    },
+
+    addNodeView() {
+        return ({ node, editor, getPos }) => {
+            let current = node;
+            const dom = document.createElement('figure');
+            dom.classList.add('wpcarve-embed');
+            dom.contentEditable = 'false';
+
+            const media = document.createElement('div');
+            media.className = 'wpcarve-embed-media';
+
+            // Inline edit affordance: change the media URL / video id in place.
+            const editBtn = document.createElement('button');
+            editBtn.type = 'button';
+            editBtn.className = 'carve-embed-edit';
+            editBtn.textContent = 'Edit';
+            editBtn.contentEditable = 'false';
+            editBtn.setAttribute('aria-label', 'Edit media URL');
+            editBtn.addEventListener('mousedown', e => e.stopPropagation());
+            editBtn.addEventListener('click', () => {
+                if (typeof getPos !== 'function') return;
+                const shown = current.attrs.carveSource || current.attrs.src || '';
+                const val = window.prompt('Media URL or video id', shown);
+                if (val === null) return;
+                const input = val.trim();
+                if (!input) return;
+                // A `:name[...]` directive is kept as-is; a URL/id becomes one
+                // (a bare id is assumed to be YouTube).
+                const directive = input.startsWith(':')
+                    ? input
+                    : carveMediaDirective(/^https?:|^\/\//.test(input) ? input : `https://www.youtube.com/watch?v=${input}`);
+                editor.chain().focus().command(({ tr }) => {
+                    tr.setNodeMarkup(getPos(), undefined, {
+                        ...current.attrs,
+                        carveSource: directive,
+                        src: null,
+                        html: null,
+                    });
+                    return true;
+                }).run();
+            });
+
+            const paint = (n) => {
+                media.innerHTML = '';
+                const src = embedPreviewSrc(n.attrs);
+                if (n.attrs.html) {
+                    media.innerHTML = n.attrs.html;
+                } else if (src) {
+                    const iframe = document.createElement('iframe');
+                    iframe.src = src;
+                    iframe.setAttribute('loading', 'lazy');
+                    iframe.setAttribute('allowfullscreen', '');
+                    iframe.setAttribute('frameborder', '0');
+                    iframe.width = '480';
+                    iframe.height = '270';
+                    media.appendChild(iframe);
+                } else {
+                    const p = document.createElement('p');
+                    p.textContent = `Embedded: ${n.attrs.carveSource || 'unknown'}`;
+                    media.appendChild(p);
+                }
+                if (n.attrs.src) {
+                    dom.setAttribute('data-carve-src', n.attrs.src);
+                } else {
+                    dom.removeAttribute('data-carve-src');
+                }
+                if (n.attrs.carveSource) {
+                    dom.setAttribute('data-carve-source', n.attrs.carveSource);
+                } else {
+                    dom.removeAttribute('data-carve-source');
+                }
+            };
+
+            dom.appendChild(media);
+            dom.appendChild(editBtn);
+            paint(node);
+
+            return {
+                dom,
+                update: (updated) => {
+                    if (updated.type !== current.type) {
+                        return false;
+                    }
+                    current = updated;
+                    paint(updated);
+                    return true;
+                },
+                // Atom chrome: never let ProseMirror re-read our internal DOM.
+                ignoreMutation: () => true,
+            };
+        };
+    },
+
+    addCommands() {
+        return {
+            setCarveEmbed: (attributes) => ({ commands }) => {
+                return commands.insertContent({
+                    type: this.name,
+                    attrs: attributes,
+                });
+            },
+        };
+    },
+});
+
+export default CarveEmbed;

package/tiptap/extensions/carve-footnote-definition.js

@@ -0,0 +1,81 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+/**
+ * Carve Footnote Definition node for Tiptap.
+ *
+ * A block that holds a footnote's body, paired with an inline `[^label]`
+ * reference (see CarveFootnote). Serializes to Carve as:
+ *
+ * ```
+ * [^label]: the footnote body
+ * ```
+ *
+ * Hosts typically collect these at the end of the document. The body is regular
+ * block content (`paragraph+`).
+ *
+ * @example
+ * ```js
+ * import { CarveFootnoteDefinition } from 'carve-grammars/tiptap'
+ *
+ * editor.chain().focus().insertCarveFootnoteDefinition({ label: '1' }).run()
+ * ```
+ */
+export const CarveFootnoteDefinition = Node.create({
+    name: 'carveFootnoteDefinition',
+
+    group: 'block',
+
+    content: 'paragraph+',
+
+    defining: true,
+
+    addAttributes() {
+        return {
+            label: {
+                default: 'note',
+                parseHTML: element => element.getAttribute('data-footnote-label')
+                    // carve-php / carve-js reference: id="fnN".
+                    || element.id.replace(/^fn/, '')
+                    || 'note',
+                renderHTML: attributes => ({ 'data-footnote-label': attributes.label }),
+            },
+        };
+    },
+
+    parseHTML() {
+        return [
+            { tag: 'li[data-footnote-label]' },
+            { tag: 'section.carve-footnotes > ol > li' },
+            // carve-php / carve-js render the footnote section as
+            // <section role="doc-endnotes"><hr><ol><li id="fnN"><p>body
+            // <a role="doc-backlink">↩</a></p></li></ol></section>. Take each li
+            // as a definition; unwrap the <ol>, drop the <hr> and the back-link
+            // so only the body survives.
+            { tag: 'section[role="doc-endnotes"] li', priority: 60 },
+            { tag: 'section[role="doc-endnotes"] ol', skip: true, priority: 60 },
+            { tag: 'section[role="doc-endnotes"] hr', ignore: true, priority: 60 },
+            { tag: 'a[role="doc-backlink"]', ignore: true, priority: 60 },
+        ];
+    },
+
+    renderHTML({ HTMLAttributes, node }) {
+        return ['li', mergeAttributes(HTMLAttributes, {
+            class: 'carve-footnote-definition',
+            'data-footnote-label': node.attrs.label,
+        }), 0];
+    },
+
+    addCommands() {
+        return {
+            insertCarveFootnoteDefinition: attributes => ({ commands }) => {
+                return commands.insertContent({
+                    type: this.name,
+                    attrs: attributes,
+                    content: [{ type: 'paragraph' }],
+                });
+            },
+        };
+    },
+});
+
+export default CarveFootnoteDefinition;

package/tiptap/extensions/carve-footnote.js

@@ -0,0 +1,76 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+/**
+ * Carve Footnote node extension for Tiptap
+ *
+ * Renders as [^label] in Carve markup
+ *
+ * @example
+ * ```js
+ * import { CarveFootnote } from 'carve-grammars/tiptap'
+ *
+ * const editor = new Editor({
+ *   extensions: [CarveFootnote],
+ * })
+ *
+ * // Insert a footnote reference
+ * editor.chain().focus().insertCarveFootnote({ label: 'note1' }).run()
+ * ```
+ */
+export const CarveFootnote = Node.create({
+    name: 'carveFootnote',
+
+    group: 'inline',
+
+    inline: true,
+
+    atom: true,
+
+    addAttributes() {
+        return {
+            label: {
+                default: 'note',
+                parseHTML: element => element.getAttribute('data-footnote-label')
+                    || element.textContent?.replace(/[[\]^]/g, '').trim()
+                    // carve-php / carve-js reference: id="fnrefN".
+                    || element.id.replace(/^fnref/, '')
+                    || 'note',
+                renderHTML: attributes => {
+                    return { 'data-footnote-label': attributes.label };
+                },
+            },
+        };
+    },
+
+    parseHTML() {
+        return [
+            { tag: 'sup.carve-footnote' },
+            { tag: 'span.carve-footnote-ref' },
+            // carve-php / carve-js render the reference as
+            // <a id="fnrefN" role="doc-noteref"><sup>N</sup></a>. Beat Link to it.
+            { tag: 'a[role="doc-noteref"]', priority: 60 },
+        ];
+    },
+
+    renderHTML({ HTMLAttributes }) {
+        const label = HTMLAttributes['data-footnote-label'] || 'note';
+        return ['sup', mergeAttributes(HTMLAttributes, {
+            class: 'carve-footnote',
+            'data-footnote-label': label,
+            contenteditable: 'false',
+        }), `[^${label}]`];
+    },
+
+    addCommands() {
+        return {
+            insertCarveFootnote: (attributes) => ({ commands }) => {
+                return commands.insertContent({
+                    type: this.name,
+                    attrs: attributes,
+                });
+            },
+        };
+    },
+});
+
+export default CarveFootnote;

package/tiptap/extensions/carve-insert.js

@@ -0,0 +1,54 @@
+import { Mark, mergeAttributes } from '@tiptap/core';
+
+/**
+ * Carve Insert mark extension for Tiptap
+ *
+ * Renders as {+text+} in Carve markup
+ *
+ * @example
+ * ```js
+ * import { CarveInsert } from 'carve-grammars/tiptap'
+ *
+ * const editor = new Editor({
+ *   extensions: [CarveInsert],
+ * })
+ *
+ * // Toggle insert mark
+ * editor.chain().focus().toggleCarveInsert().run()
+ * ```
+ */
+export const CarveInsert = Mark.create({
+    name: 'carveInsert',
+
+    // Outrank StarterKit's Strike, whose parseHTML also claims <del> - at
+    // default priority the strike mark wins and {-...-} degrades to ~...~
+    // after an HTML round-trip.
+    priority: 101,
+
+    parseHTML() {
+        return [
+            { tag: 'ins' },
+            { tag: 'span.carve-insert' },
+        ];
+    },
+
+    renderHTML({ HTMLAttributes }) {
+        return ['span', mergeAttributes(HTMLAttributes, { class: 'carve-insert' }), 0];
+    },
+
+    addCommands() {
+        return {
+            toggleCarveInsert: () => ({ commands }) => commands.toggleMark(this.name),
+            setCarveInsert: () => ({ commands }) => commands.setMark(this.name),
+            unsetCarveInsert: () => ({ commands }) => commands.unsetMark(this.name),
+        };
+    },
+
+    addKeyboardShortcuts() {
+        return {
+            'Mod-Shift-i': () => this.editor.commands.toggleCarveInsert(),
+        };
+    },
+});
+
+export default CarveInsert;

package/tiptap/extensions/carve-keymap.js

@@ -0,0 +1,71 @@
+import { Extension } from '@tiptap/core';
+
+/**
+ * Carve keyboard shortcuts.
+ *
+ * Tiptap only binds Mod-Alt-1..6 for headings, so plain Ctrl/Cmd+1..6 fall
+ * through to the browser (switching tabs). These bindings cover the common
+ * Carve constructs, all return true so the browser default is prevented, and
+ * use toggle* commands so pressing a heading level on an existing heading
+ * REPLACES it (or toggles back to a paragraph) rather than stacking.
+ *
+ * Included in CarveKit by default; import standalone to add to a custom set.
+ */
+export const CarveKeymap = Extension.create({
+    name: 'carveKeymap',
+
+    addKeyboardShortcuts() {
+        const editor = this.editor;
+        const heading = (level) => () => editor.chain().focus().toggleHeading({ level }).run();
+
+        return {
+            'Mod-1': heading(1),
+            'Mod-2': heading(2),
+            'Mod-3': heading(3),
+            'Mod-4': heading(4),
+            'Mod-5': heading(5),
+            'Mod-6': heading(6),
+            'Mod-e': () => editor.chain().focus().toggleCode().run(),
+            'Mod-.': () => editor.chain().focus().toggleSuperscript().run(),
+            'Mod-,': () => editor.chain().focus().toggleSubscript().run(),
+            'Mod-Shift-x': () => editor.chain().focus().toggleStrike().run(),
+            'Mod-Shift-h': () => editor.chain().focus().toggleHighlight().run(),
+            'Mod-Shift-e': () => editor.chain().focus().toggleCodeBlock().run(),
+            'Mod-Shift-.': () => editor.chain().focus().toggleBlockquote().run(),
+            'Mod-Shift-8': () => editor.chain().focus().toggleBulletList().run(),
+            'Mod-Shift-7': () => editor.chain().focus().toggleOrderedList().run(),
+            // Clear formatting: node type back to paragraph + drop all marks.
+            'Mod-\\': () => editor.chain().focus().clearNodes().unsetAllMarks().run(),
+            // Enter at the END of a top-level textblock starts a fresh, mark-free
+            // paragraph - so heading/bold/italic reset on a new line instead of
+            // carrying over. Mid-block splits, lists, blockquotes and containers
+            // keep the default behavior.
+            Enter: () => {
+                const { $from, empty } = editor.state.selection;
+                if (!empty) {
+                    return false;
+                }
+                const parent = $from.parent;
+                const atEnd = $from.parentOffset === parent.content.size;
+                const isPlainTextblock = parent.isTextblock && parent.type.name !== 'codeBlock';
+                const topLevel = $from.depth === 1;
+                if (!atEnd || !isPlainTextblock || !topLevel) {
+                    return false;
+                }
+                return editor
+                    .chain()
+                    .insertContentAt($from.after(), { type: 'paragraph' })
+                    .setTextSelection($from.after() + 1)
+                    .command(({ tr, dispatch }) => {
+                        if (dispatch) {
+                            dispatch(tr.setStoredMarks([]));
+                        }
+                        return true;
+                    })
+                    .run();
+            },
+        };
+    },
+});
+
+export default CarveKeymap;

package/tiptap/extensions/carve-math.js

@@ -0,0 +1,82 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+/**
+ * Carve Math node extension for Tiptap.
+ *
+ * Inline atom holding raw math source. Serializes to Carve as:
+ * - inline:  `` $`x`$ ``
+ * - display: `` $$`x`$$ `` (when `display` is true)
+ *
+ * The source is stored verbatim in `data-carve-math`; rendering of the math
+ * itself (KaTeX/MathML/etc.) is left to the host application's node view.
+ *
+ * @example
+ * ```js
+ * import { CarveMath } from 'carve-grammars/tiptap'
+ *
+ * editor.chain().focus().insertCarveMath({ src: 'E = mc^2' }).run()
+ * ```
+ */
+export const CarveMath = Node.create({
+    name: 'carveMath',
+
+    group: 'inline',
+
+    inline: true,
+
+    atom: true,
+
+    addAttributes() {
+        return {
+            src: {
+                default: '',
+                parseHTML: element => {
+                    const explicit = element.getAttribute('data-carve-math');
+                    if (explicit) return explicit;
+                    // carve-php renders <span class="math ...">\(TEX\)</span> or
+                    // \[TEX\] for display; recover the raw TeX by stripping the
+                    // \( \) / \[ \] delimiters.
+                    return (element.textContent || '')
+                        .trim()
+                        .replace(/^\\[([]/, '')
+                        .replace(/\\[)\]]$/, '')
+                        .trim();
+                },
+                renderHTML: attributes => ({ 'data-carve-math': attributes.src }),
+            },
+            display: {
+                default: false,
+                parseHTML: element => element.getAttribute('data-display') === 'true' || element.classList.contains('display'),
+                renderHTML: attributes => (attributes.display ? { 'data-display': 'true' } : {}),
+            },
+        };
+    },
+
+    parseHTML() {
+        return [
+            { tag: 'span[data-carve-math]' },
+            // carve-php rendered output.
+            { tag: 'span.math' },
+        ];
+    },
+
+    renderHTML({ HTMLAttributes, node }) {
+        return ['span', mergeAttributes(HTMLAttributes, {
+            class: 'carve-math',
+            'data-carve-math': node.attrs.src,
+        }), node.attrs.src];
+    },
+
+    addCommands() {
+        return {
+            insertCarveMath: attributes => ({ commands }) => {
+                return commands.insertContent({
+                    type: this.name,
+                    attrs: attributes,
+                });
+            },
+        };
+    },
+});
+
+export default CarveMath;

package/tiptap/extensions/carve-mention.js

@@ -0,0 +1,44 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+/**
+ * Carve mention / tag inline nodes.
+ *
+ * carve-php / carve-js render `@name` as
+ * `<span class="mention"><strong>@name</strong></span>` and `#tag` as
+ * `<span class="tag"><strong>#tag</strong></span>`. Citations use a mention:
+ * `[@key]` is literal brackets around a mention. These are inline atoms so they
+ * round-trip verbatim (the bare `@`/`#` is escaped in ordinary prose, so only a
+ * real mention/tag node emits an unescaped one).
+ */
+function mentionNode(name, cssClass, sigil) {
+    return Node.create({
+        name,
+        group: 'inline',
+        inline: true,
+        atom: true,
+
+        addAttributes() {
+            return {
+                id: {
+                    default: '',
+                    parseHTML: element => (element.textContent || '').replace(/^[@#]/, '').trim(),
+                    renderHTML: attributes => ({ 'data-id': attributes.id }),
+                },
+            };
+        },
+
+        parseHTML() {
+            // Beat CarveSpan (which also matches span[class]).
+            return [{ tag: `span.${cssClass}`, priority: 60 }];
+        },
+
+        renderHTML({ HTMLAttributes, node }) {
+            return ['span', mergeAttributes(HTMLAttributes, { class: cssClass }), sigil + node.attrs.id];
+        },
+    });
+}
+
+export const CarveMention = mentionNode('carveMention', 'mention', '@');
+export const CarveTag = mentionNode('carveTag', 'tag', '#');
+
+export default CarveMention;