@markup-carve/carve-grammars 0.1.2

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

@@ -0,0 +1,270 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+/**
+ * Carve Definition List extension for Tiptap
+ *
+ * Provides full definition list support with keyboard navigation.
+ *
+ * Carve syntax:
+ * ```
+ * : term
+ *
+ *   Definition paragraph (indented)
+ * ```
+ *
+ * Multiple terms sharing definition:
+ * ```
+ * : color
+ * : colour
+ *
+ *   The visual property...
+ * ```
+ *
+ * Multiple definitions (: + continuation):
+ * ```
+ * : term
+ *
+ *   First definition.
+ *
+ * : +
+ *
+ *   Second definition.
+ * ```
+ *
+ * Keyboard shortcuts:
+ * - Enter in term: go to definition
+ * - Shift+Enter in term: add another term (for synonyms)
+ * - Enter in empty definition: create new term+definition pair
+ * - Shift+Enter in definition: add another definition (: + syntax)
+ */
+
+/**
+ * Definition List container node (<dl>)
+ */
+export const CarveDefinitionList = Node.create({
+    name: 'definitionList',
+
+    group: 'block',
+
+    // Allow multiple terms followed by multiple descriptions, repeating
+    content: '(definitionTerm+ definitionDescription+)+',
+
+    parseHTML() {
+        return [{ tag: 'dl', priority: 51 }];
+    },
+
+    renderHTML({ HTMLAttributes }) {
+        return ['dl', mergeAttributes(HTMLAttributes, { class: 'carve-definition-list' }), 0];
+    },
+
+    addCommands() {
+        return {
+            insertDefinitionList: () => ({ chain, state }) => {
+                const { $from } = state.selection;
+                const insertPos = $from.end();
+
+                return chain()
+                    .insertContentAt(insertPos, {
+                        type: 'definitionList',
+                        content: [
+                            { type: 'definitionTerm' },
+                            { type: 'definitionDescription', content: [{ type: 'paragraph' }] },
+                        ],
+                    })
+                    // Focus at the start of the term
+                    .focus(insertPos + 2)
+                    .run();
+            },
+        };
+    },
+});
+
+/**
+ * Definition Term node (<dt>)
+ * Note: No group - can only appear inside definitionList
+ */
+export const CarveDefinitionTerm = Node.create({
+    name: 'definitionTerm',
+
+    content: 'inline*',
+
+    defining: true,
+
+    parseHTML() {
+        return [{ tag: 'dt', priority: 51 }];
+    },
+
+    renderHTML({ HTMLAttributes }) {
+        return ['dt', mergeAttributes(HTMLAttributes), 0];
+    },
+
+    addKeyboardShortcuts() {
+        return {
+            // Enter in term: go to description or create one
+            'Enter': () => {
+                const { state } = this.editor;
+                const { $from } = state.selection;
+
+                if ($from.parent.type.name !== 'definitionTerm') {
+                    return false;
+                }
+
+                const termEnd = $from.end();
+
+                // Empty term - let default behavior handle it
+                if ($from.parent.content.size === 0) {
+                    return false;
+                }
+
+                // Check what comes next
+                const $afterTerm = state.doc.resolve(termEnd + 1);
+                const nextNode = $afterTerm.nodeAfter;
+
+                if (nextNode && nextNode.type.name === 'definitionDescription') {
+                    // Move cursor to the description
+                    return this.editor.chain()
+                        .focus(termEnd + 2)
+                        .run();
+                } else {
+                    // Insert a description after this term
+                    return this.editor.chain()
+                        .insertContentAt(termEnd + 1, {
+                            type: 'definitionDescription',
+                            content: [{ type: 'paragraph' }],
+                        })
+                        .focus(termEnd + 3)
+                        .run();
+                }
+            },
+            // Shift+Enter: add another term (for multiple terms sharing a definition)
+            'Shift-Enter': () => {
+                const { state } = this.editor;
+                const { $from } = state.selection;
+
+                if ($from.parent.type.name !== 'definitionTerm') {
+                    return false;
+                }
+
+                const termEnd = $from.end();
+
+                return this.editor.chain()
+                    .insertContentAt(termEnd + 1, {
+                        type: 'definitionTerm',
+                    })
+                    .focus(termEnd + 2)
+                    .run();
+            },
+        };
+    },
+});
+
+/**
+ * Definition Description node (<dd>)
+ * Note: No group - can only appear inside definitionList
+ */
+export const CarveDefinitionDescription = Node.create({
+    name: 'definitionDescription',
+
+    content: 'block+',
+
+    defining: true,
+
+    parseHTML() {
+        return [{ tag: 'dd', priority: 51 }];
+    },
+
+    renderHTML({ HTMLAttributes }) {
+        return ['dd', mergeAttributes(HTMLAttributes), 0];
+    },
+
+    addKeyboardShortcuts() {
+        return {
+            // Enter in empty paragraph inside description: create new term+description pair
+            'Enter': () => {
+                const { state } = this.editor;
+                const { $from } = state.selection;
+
+                // Check if we're in a paragraph inside a description
+                let inDescription = false;
+                let descriptionDepth = 0;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'definitionDescription') {
+                        inDescription = true;
+                        descriptionDepth = d;
+                        break;
+                    }
+                }
+
+                if (!inDescription) {
+                    return false;
+                }
+
+                // Check if current paragraph is empty
+                const paragraph = $from.parent;
+                if (paragraph.type.name !== 'paragraph' || paragraph.content.size !== 0) {
+                    return false;
+                }
+
+                // Find the definition list
+                let listDepth = 0;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'definitionList') {
+                        listDepth = d;
+                        break;
+                    }
+                }
+
+                if (listDepth === 0) {
+                    return false;
+                }
+
+                const descNode = $from.node(descriptionDepth);
+
+                // If description only has one empty paragraph, add new term + description
+                if (descNode.childCount === 1) {
+                    const descEnd = $from.end(descriptionDepth);
+
+                    return this.editor.chain()
+                        .insertContentAt(descEnd + 1, [
+                            { type: 'definitionTerm' },
+                            { type: 'definitionDescription', content: [{ type: 'paragraph' }] },
+                        ])
+                        .focus(descEnd + 2)
+                        .run();
+                }
+
+                return false;
+            },
+            // Shift+Enter: add another description (for : + continuation)
+            'Shift-Enter': () => {
+                const { state } = this.editor;
+                const { $from } = state.selection;
+
+                // Check if we're in a description
+                let descriptionDepth = 0;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'definitionDescription') {
+                        descriptionDepth = d;
+                        break;
+                    }
+                }
+
+                if (descriptionDepth === 0) {
+                    return false;
+                }
+
+                const descEnd = $from.end(descriptionDepth);
+
+                return this.editor.chain()
+                    .insertContentAt(descEnd + 1, {
+                        type: 'definitionDescription',
+                        content: [{ type: 'paragraph' }],
+                    })
+                    .focus(descEnd + 3)
+                    .run();
+            },
+        };
+    },
+});
+
+export default { CarveDefinitionList, CarveDefinitionTerm, CarveDefinitionDescription };

package/tiptap/extensions/carve-delete.js

@@ -0,0 +1,54 @@
+import { Mark, mergeAttributes } from '@tiptap/core';
+
+/**
+ * Carve Delete mark extension for Tiptap
+ *
+ * Renders as {-text-} in Carve markup
+ *
+ * @example
+ * ```js
+ * import { CarveDelete } from 'carve-grammars/tiptap'
+ *
+ * const editor = new Editor({
+ *   extensions: [CarveDelete],
+ * })
+ *
+ * // Toggle delete mark
+ * editor.chain().focus().toggleCarveDelete().run()
+ * ```
+ */
+export const CarveDelete = Mark.create({
+    name: 'carveDelete',
+
+    // 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: 'del' },
+            { tag: 'span.carve-delete' },
+        ];
+    },
+
+    renderHTML({ HTMLAttributes }) {
+        return ['span', mergeAttributes(HTMLAttributes, { class: 'carve-delete' }), 0];
+    },
+
+    addCommands() {
+        return {
+            toggleCarveDelete: () => ({ commands }) => commands.toggleMark(this.name),
+            setCarveDelete: () => ({ commands }) => commands.setMark(this.name),
+            unsetCarveDelete: () => ({ commands }) => commands.unsetMark(this.name),
+        };
+    },
+
+    addKeyboardShortcuts() {
+        return {
+            'Mod-Shift-d': () => this.editor.commands.toggleCarveDelete(),
+        };
+    },
+});
+
+export default CarveDelete;

package/tiptap/extensions/carve-div.js

@@ -0,0 +1,188 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+
+/**
+ * First direct child that carries the admonition-title class (carve-php and
+ * carve-js render a quoted container title as such a paragraph).
+ */
+function findTitleChild(element) {
+    for (const child of element.children || []) {
+        if (child.classList && child.classList.contains('admonition-title')) {
+            return child;
+        }
+    }
+    return null;
+}
+
+/** First direct child carrying the carve-div-body class (own editor DOM). */
+function findBodyChild(element) {
+    for (const child of element.children || []) {
+        if (child.classList && child.classList.contains('carve-div-body')) {
+            return child;
+        }
+    }
+    return null;
+}
+
+/**
+ * Content for the node: everything except the title paragraph, which is
+ * captured as the `title` attribute instead (else it would duplicate into the
+ * body and the quoted summary would be lost on serialization). The editor's
+ * own DOM wraps content in .carve-div-body next to the rendered title.
+ */
+function contentWithoutTitle(element) {
+    const body = findBodyChild(element);
+    if (body) {
+        return body;
+    }
+    const clone = element.cloneNode(true);
+    const title = findTitleChild(clone);
+    if (!title) {
+        return element;
+    }
+    title.remove();
+    return clone;
+}
+
+/**
+ * Carve Div container node extension for Tiptap
+ *
+ * Renders as ::: class in Carve markup, with an optional quoted title
+ * (::: note "Custom title") kept in the `title` attribute
+ *
+ * @example
+ * ```js
+ * import { CarveDiv } from 'carve-grammars/tiptap'
+ *
+ * const editor = new Editor({
+ *   extensions: [CarveDiv],
+ * })
+ *
+ * // Wrap selection in a div container
+ * editor.chain().focus().setCarveDiv({ class: 'warning' }).run()
+ * ```
+ */
+export const CarveDiv = Node.create({
+    name: 'carveDiv',
+
+    group: 'block',
+
+    content: 'block+',
+
+    defining: true,
+
+    addAttributes() {
+        return {
+            class: {
+                default: null,
+                parseHTML: element => element.getAttribute('data-carve-class')
+                    // Drop the framing classes so an <aside class="admonition note">
+                    // (carve-php / carve-js output) yields just "note".
+                    || element.className.replace(/\b(carve-div|admonition)\b/g, '').replace(/\s+/g, ' ').trim()
+                    || null,
+                renderHTML: attributes => {
+                    if (!attributes.class) return {};
+                    return { 'data-carve-class': attributes.class };
+                },
+            },
+            title: {
+                default: null,
+                // An empty string is meaningful (::: note "" suppresses the
+                // default title), so only a missing title maps to null.
+                parseHTML: element => {
+                    const attr = element.getAttribute('data-carve-title');
+                    if (attr !== null) return attr;
+                    const child = findTitleChild(element);
+                    if (child) return child.textContent.trim();
+                    // carve-js renders an authored {title="..."} block attribute
+                    // as a literal title attribute on the container (carve-php
+                    // promotes it to an admonition-title paragraph instead);
+                    // capture it so the title survives that engine's seed too.
+                    return element.getAttribute('title');
+                },
+                renderHTML: attributes => {
+                    if (attributes.title == null) return {};
+                    return { 'data-carve-title': attributes.title };
+                },
+            },
+        };
+    },
+
+    parseHTML() {
+        return [
+            { tag: 'div.carve-div', contentElement: contentWithoutTitle },
+            // Admonitions render as <aside class="admonition TYPE"> (carve-php,
+            // carve-js). Match highest so it wins over the generic rules.
+            { tag: 'aside.admonition', priority: 60, contentElement: contentWithoutTitle },
+            // Also match common container classes rendered by carve-php
+            { tag: 'div.note', contentElement: contentWithoutTitle },
+            { tag: 'div.tip', contentElement: contentWithoutTitle },
+            { tag: 'div.warning', contentElement: contentWithoutTitle },
+            { tag: 'div.danger', contentElement: contentWithoutTitle },
+            { tag: 'div.info', contentElement: contentWithoutTitle },
+            // Match any div with a single class (likely a ::: container)
+            {
+                tag: 'div[class]',
+                contentElement: contentWithoutTitle,
+                getAttrs: element => {
+                    // Only match divs with a simple class (not complex component divs)
+                    const className = element.className;
+                    // Skip if it looks like a WordPress/editor component
+                    if (className.includes('wp-') || className.includes('block-') ||
+                        className.includes('editor-') || className.includes('is-')) {
+                        return false;
+                    }
+                    // Skip Torchlight code block line divs
+                    if (className === 'line' || className.includes('line-')) {
+                        return false;
+                    }
+                    // Skip if inside a pre or code element (syntax highlighting)
+                    if (element.closest('pre') || element.closest('code')) {
+                        return false;
+                    }
+                    // Accept single-word classes or carve-div
+                    if (/^[a-z-]+$/i.test(className) || className.includes('carve-div')) {
+                        return {};
+                    }
+                    return false;
+                },
+            },
+        ];
+    },
+
+    renderHTML({ HTMLAttributes }) {
+        const classes = ['carve-div'];
+        if (HTMLAttributes['data-carve-class']) {
+            classes.push(HTMLAttributes['data-carve-class']);
+        }
+        const attrs = mergeAttributes(HTMLAttributes, { class: classes.join(' ') });
+        const title = HTMLAttributes['data-carve-title'];
+        if (title === undefined) {
+            return ['div', attrs, 0];
+        }
+        // Keep the captured title VISIBLE in the editor: a non-editable title
+        // element plus a body wrapper carrying the content hole (ProseMirror
+        // requires the hole to be its parent's only child). The title itself
+        // is edited in source mode; contentWithoutTitle() reads content from
+        // .carve-div-body so this shape re-parses without duplication.
+        return ['div', attrs,
+            ['p', { class: 'admonition-title', contenteditable: 'false' }, title],
+            ['div', { class: 'carve-div-body' }, 0],
+        ];
+    },
+
+    addCommands() {
+        return {
+            setCarveDiv: (attributes) => ({ commands }) => {
+                return commands.wrapIn(this.name, attributes);
+            },
+            toggleCarveDiv: (attributes) => ({ commands }) => {
+                return commands.toggleWrap(this.name, attributes);
+            },
+            unsetCarveDiv: () => ({ commands }) => {
+                return commands.lift(this.name);
+            },
+        };
+    },
+});
+
+export default CarveDiv;