@markup-carve/carve-grammars 0.1.7 → 0.1.8

package/README.md

@@ -259,6 +259,16 @@ available as the `editor` CSS part (`carve-editor::part(editor)`). Tiptap stays
 an implementation detail of the element, although its peer packages must be
 installed with `carve-grammars`.
 
+Document front matter appears as a collapsed **Document metadata** card. Expand
+it to edit the common `title`, `lang`, `author`, and `description` fields, or use
+the raw YAML/TOML field for custom metadata. Both paths update the document
+through the editor, so they participate in undo/redo and preserve unknown keys.
+Unsupported-source atoms use the same compact/editable pattern for their exact
+Carve payload. Inline footnotes, cross-references, and citations open target
+pickers, while abbreviation and link-reference definitions use collapsible
+forms. Import `@markup-carve/carve-grammars/tiptap/editor.css` when mounting
+`CarveKit` directly to receive the associated editor chrome and table styling.
+
 ## Syntax highlighting
 
 Render Carve source as highlighted HTML on the web. Both grammars cover the full

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markup-carve/carve-grammars",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Grammars for the Carve markup language: Tiptap editor kit + serializer, plus Prism, highlight.js and TextMate syntax-highlighting grammars",
   "type": "module",
   "main": "tiptap/index.js",

package/tiptap/carve-editor.js

@@ -32,6 +32,73 @@ export class CarveEditorElement extends HTMLElementBase {
                 [part="editor"] { min-height: 8rem; }
                 .ProseMirror { min-height: inherit; outline: none; }
                 .ProseMirror:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
+                .carve-frontmatter-card { border: 1px solid #d5d9df; border-radius: 4px; margin-block-end: 1rem; }
+                .carve-frontmatter-summary { width: 100%; border: 0; background: #f4f5f7; color: inherit; cursor: pointer; font: inherit; font-weight: 600; padding: .65rem .8rem; text-align: start; }
+                .carve-frontmatter-summary::before { content: '▸'; display: inline-block; margin-inline-end: .5rem; }
+                .carve-frontmatter-summary[aria-expanded="true"]::before { transform: rotate(90deg); }
+                .carve-frontmatter-body { padding: .8rem; }
+                .carve-frontmatter-fields { display: grid; grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr)); gap: .75rem; }
+                .carve-frontmatter-card label { display: grid; gap: .25rem; font-size: .875rem; font-weight: 600; }
+                .carve-frontmatter-card input, .carve-frontmatter-card textarea { box-sizing: border-box; width: 100%; border: 1px solid #b9c0ca; border-radius: 3px; font: inherit; padding: .5rem; }
+                .carve-frontmatter-raw { margin-block-start: .75rem; }
+                .carve-frontmatter-raw textarea { min-height: 7rem; font-family: monospace; font-weight: 400; }
+                .ProseMirror table { width: 100%; border-collapse: collapse; outline: 1px solid #d5d9df; }
+                .ProseMirror th, .ProseMirror td { border: 1px solid #d5d9df; padding: .5rem; vertical-align: top; }
+                .ProseMirror th { background: #f4f5f7; font-weight: 700; }
+                .ProseMirror a { color: #1769c2; text-underline-offset: .14em; }
+                .ProseMirror blockquote { margin: 0 0 1rem; padding-inline-start: 1rem; border-inline-start: 3px solid #c8ced7; color: #5a626d; }
+                .ProseMirror blockquote:focus-within { border-inline-start-color: #1769c2; }
+                .ProseMirror blockquote > :first-child { margin-block-start: 0; }
+                .ProseMirror blockquote > :last-child { margin-block-end: 0; }
+                .ProseMirror ul[data-type="taskList"] { list-style: none; padding-inline-start: 0; }
+                .ProseMirror ul[data-type="taskList"] ul[data-type="taskList"] { padding-inline-start: 1.5rem; }
+                .ProseMirror ul[data-type="taskList"] > li[data-checked] { display: grid; grid-template-columns: auto minmax(0, 1fr); align-items: start; column-gap: .5rem; }
+                .ProseMirror ul[data-type="taskList"] > li[data-checked] > label { margin-block-start: .2em; line-height: inherit; }
+                .ProseMirror ul[data-type="taskList"] > li[data-checked] > div > :first-child { margin-block-start: 0; }
+                .ProseMirror ul[data-type="taskList"] > li[data-checked] > div > :last-child { margin-block-end: 0; }
+                .ProseMirror pre[data-carve-comment] { margin-block: .75rem; border: 1px dashed #7a828c; border-radius: 4px; background: #f4f5f7; color: #5a626d; padding: .55rem .75rem .65rem; white-space: pre-wrap; }
+                .ProseMirror pre[data-carve-comment]::before { content: "Comment"; display: block; margin-block-end: .35rem; color: #0e4459; font: 700 .7rem/1.2 system-ui, sans-serif; letter-spacing: .08em; text-transform: uppercase; }
+                .ProseMirror span[data-carve-comment-inline] { border: 1px dashed #7a828c; border-radius: 4px; background: #e6f0f4; color: #5a626d; padding: .05em .3em; }
+                .ProseMirror span[data-carve-comment-inline]::before { content: "Comment: "; color: #0e4459; font-size: .78em; font-weight: 700; }
+                .ProseMirror [data-carve-extension], .ProseMirror [data-carve-empty-mark-node] { border-radius: 3px; background: #f4f5f7; padding: .05em .3em; }
+                .ProseMirror [data-carve-extension]::before { content: ':' attr(data-carve-extension) '['; color: #0e4459; font: 600 .78em/1 monospace; margin-inline-end: .2em; }
+                .ProseMirror [data-carve-extension]::after { content: ']'; color: #0e4459; font: 600 .78em/1 monospace; margin-inline-start: .2em; }
+                .ProseMirror [data-carve-empty-mark-node]::before { content: 'Empty ' attr(data-carve-empty-mark); color: #5a626d; font: 600 .78em/1 system-ui, sans-serif; }
+                .ProseMirror [data-carve-citation-definition], .ProseMirror .carve-footnote-definition, .ProseMirror figcaption[data-carve-caption] { border-inline-start: 3px solid #c8ced7; padding-inline-start: .75rem; }
+                .ProseMirror [data-carve-citation-definition]::before, .ProseMirror .carve-footnote-definition::before, .ProseMirror figcaption[data-carve-caption]::before { display: block; color: #5a626d; font: 700 .68rem/1.3 system-ui, sans-serif; letter-spacing: .06em; text-transform: uppercase; }
+                .ProseMirror [data-carve-citation-definition]::before { content: 'Citation · ' attr(key); }
+                .ProseMirror .carve-footnote-definition::before { content: 'Footnote · ' attr(data-footnote-label); }
+                .ProseMirror figcaption[data-carve-caption]::before { content: 'Caption'; }
+                .ProseMirror .critic-comment { background: #fff6dc; text-decoration: underline dotted #9a6700; text-underline-offset: .2em; }
+                .carve-code-block { position: relative; margin-block: .75rem; border: 1px solid #d5d9df; border-radius: 4px; overflow: hidden; }
+                .carve-code-block-chrome { display: flex; align-items: center; justify-content: flex-end; padding: .375rem .5rem; border-block-start: 1px solid #d5d9df; background: white; }
+                .carve-code-block-chrome > span { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+                .carve-code-lang { max-width: 12rem; border: 1px solid #1769c2; border-radius: 3px; background: #1769c2; color: white; font: inherit; font-weight: 600; padding: .3rem .55rem; }
+                .carve-code-block > pre { margin: 0; border: 0; border-radius: 0; padding: var(--carve-code-padding, .75rem); }
+                .carve-inline-control, .carve-raw-atom-inline { position: relative; display: inline-flex; }
+                .carve-inline-control-trigger, .carve-raw-atom-summary { border: 1px solid #c8ced7; border-radius: 999px; background: #f4f5f7; color: inherit; cursor: pointer; font: inherit; padding: .1em .45em; }
+                .carve-inline-control-editor, .carve-raw-atom-inline .carve-raw-atom-editor { position: absolute; z-index: 20; inset-block-start: 100%; inset-inline-start: 0; display: grid; grid-template-columns: 1fr auto; gap: .4rem; min-width: min(22rem, 80vw); padding: .5rem; border: 1px solid #c8ced7; background: white; }
+                .carve-inline-control-editor[hidden], .carve-raw-atom-editor[hidden] { display: none; }
+                .carve-inline-control-editor > input, .carve-inline-choices { grid-column: 1 / -1; }
+                .carve-inline-control-editor > .carve-control-primary { justify-self: end; }
+                .carve-inline-fields-editor > label { grid-column: 1 / -1; display: grid; gap: .2rem; color: #5a626d; font-size: .8rem; }
+                .carve-inline-fields-editor textarea { min-height: 4.5rem; resize: vertical; }
+                .carve-inline-fields-editor input, .carve-inline-fields-editor textarea { width: 100%; min-width: 0; font: inherit; }
+                .carve-inline-fields-editor input[type="checkbox"] { width: auto; justify-self: start; }
+                .carve-inline-field-actions { grid-column: 1 / -1; display: flex; justify-content: flex-end; gap: .4rem; }
+                .carve-embed-editor { display: grid; grid-template-columns: 1fr auto auto; gap: .4rem; padding: .6rem; border-block-start: 1px solid #c8ced7; background: white; }
+                .carve-embed-editor[hidden] { display: none; }
+                .carve-embed-editor label { grid-column: 1 / -1; display: grid; gap: .25rem; }
+                .carve-embed-editor input { width: 100%; min-width: 0; font: inherit; }
+                .carve-inline-choices { display: grid; max-height: 11rem; overflow-y: auto; border: 1px solid #d5d9df; border-radius: 3px; padding: .2rem; }
+                .carve-inline-choices[hidden] { display: none; }
+                .carve-inline-choice { width: 100%; border: 0; background: transparent; color: inherit; padding: .4rem .5rem; text-align: start; }
+                .carve-inline-choice:hover, .carve-inline-choice:focus-visible, .carve-inline-choice[aria-selected="true"] { background: #e6f0f4; color: #0e4459; }
+                .carve-definition-card, .carve-raw-atom:not(.carve-raw-atom-inline) { border: 1px solid #d5d9df; border-radius: 4px; margin-block: .75rem; }
+                .carve-definition-summary, .carve-raw-atom:not(.carve-raw-atom-inline) > .carve-raw-atom-summary { display: block; width: 100%; border: 0; border-radius: 0; text-align: start; font-weight: 600; padding: .6rem .75rem; }
+                .carve-definition-body, .carve-raw-atom:not(.carve-raw-atom-inline) > .carve-raw-atom-editor { padding: .75rem; }
+                .carve-definition-body label { display: grid; gap: .25rem; margin-block-end: .6rem; }
+                .carve-definition-body input, .carve-definition-body textarea, .carve-raw-atom-editor textarea { box-sizing: border-box; width: 100%; padding: .5rem; }
             </style>
             <div part="editor"></div>
         `;
@@ -62,6 +129,9 @@ export class CarveEditorElement extends HTMLElementBase {
     attributeChangedCallback(name) {
         if (name === 'readonly' && this._editor) {
             this._editor.setEditable(!this.hasAttribute('readonly'));
+            for (const control of this.shadowRoot.querySelectorAll('.carve-frontmatter-card input, .carve-frontmatter-card textarea, [data-carve-edit-control]')) {
+                control.disabled = this.hasAttribute('readonly');
+            }
         }
     }
 

package/tiptap/carve-kit.js

@@ -1,4 +1,5 @@
 import { Extension } from '@tiptap/core';
+import { Plugin } from '@tiptap/pm/state';
 import StarterKit from '@tiptap/starter-kit';
 import CodeBlock from '@tiptap/extension-code-block';
 import Highlight from '@tiptap/extension-highlight';
@@ -67,6 +68,7 @@ import { CarveMention, CarveTag } from './extensions/carve-mention.js';
 // shown even if it is not in this list.
 const CODE_LANGS = [
     { value: '', label: 'Plain text' },
+    { value: 'carve', label: 'Carve' },
     { value: 'php', label: 'PHP' },
     { value: 'javascript', label: 'JavaScript' },
     { value: 'typescript', label: 'TypeScript' },
@@ -147,12 +149,68 @@ function authoredClasses(element) {
     return kept.length ? kept.join(' ') : null;
 }
 
+const LEGACY_INLINE_CONTENT_NODES = new Set([
+    'carveCommentInline',
+    'carveLiteral',
+    'carveRawInline',
+]);
+
+// These nodes used to store their editable payload in attrs.content. Keep old
+// persisted ProseMirror JSON usable by promoting that attribute to child text
+// as soon as it enters an editor. Applying replacements from right to left
+// keeps every collected position valid as leaf nodes grow children.
+function legacyInlineContentTransaction(state) {
+    const replacements = [];
+    state.doc.descendants((node, pos) => {
+        const legacyContent = node.attrs?.content;
+        if (LEGACY_INLINE_CONTENT_NODES.has(node.type.name)
+            && node.childCount === 0
+            && typeof legacyContent === 'string'
+            && legacyContent.length > 0) {
+            replacements.push({ node, pos, legacyContent });
+        }
+    });
+    if (replacements.length === 0) return null;
+
+    const transaction = state.tr;
+    for (const { node, pos, legacyContent } of replacements.reverse()) {
+        transaction.replaceWith(
+            pos,
+            pos + node.nodeSize,
+            node.type.create(
+                { ...node.attrs, content: null },
+                state.schema.text(legacyContent),
+                node.marks,
+            ),
+        );
+    }
+    transaction.setMeta('addToHistory', false);
+    transaction.setMeta('carveLegacyInlineContentMigration', true);
+    return transaction;
+}
+
 export const CarveKit = Extension.create({
     name: 'carveKit',
 
     addExtensions() {
         const extensions = [];
 
+        extensions.push(Extension.create({
+            name: 'carveLegacyInlineContentMigration',
+            onCreate() {
+                const transaction = legacyInlineContentTransaction(this.editor.state);
+                if (transaction) this.editor.view.dispatch(transaction);
+            },
+            addProseMirrorPlugins() {
+                return [new Plugin({
+                    appendTransaction(transactions, _oldState, newState) {
+                        if (transactions.some(transaction => transaction.getMeta('carveLegacyInlineContentMigration'))) return null;
+                        return legacyInlineContentTransaction(newState);
+                    },
+                })];
+            },
+        }));
+
         // Attributes on ordinary block nodes are part of the Carve document,
         // but the stock Tiptap schema does not declare them. ProseMirror drops
         // undeclared fields while mounting JSON, so retain the common Carve
@@ -262,9 +320,11 @@ export const CarveKit = Extension.create({
                     };
                 },
 
-                // Floating language picker: a <select> in the corner of every
-                // code block that shows the current language and edits it in
-                // place (the toolbar can't show a per-block value). Disable with
+                // Language toolbar below every code block. Keeping the control
+                // outside <pre>/<code> means it never consumes the first line's
+                // horizontal space or becomes part of the editable content,
+                // while placing it after the source keeps metadata secondary.
+                // Disable with
                 // CarveKit.configure({ codeBlock: { languagePicker: false } }).
                 addNodeView() {
                     if (this.options.languagePicker === false) {
@@ -272,6 +332,8 @@ export const CarveKit = Extension.create({
                     }
                     return ({ node, editor, getPos }) => {
                         let current = node;
+                        const dom = document.createElement('div');
+                        dom.className = 'carve-code-block';
                         const pre = document.createElement('pre');
                         if (node.attrs.carveLanguageRaw) {
                             pre.setAttribute('data-language-raw', node.attrs.carveLanguageRaw);
@@ -281,6 +343,11 @@ export const CarveKit = Extension.create({
                         select.className = 'carve-code-lang';
                         select.contentEditable = 'false';
                         select.setAttribute('aria-label', 'Code language');
+                        const chrome = document.createElement('div');
+                        chrome.className = 'carve-code-block-chrome';
+                        chrome.contentEditable = 'false';
+                        const label = document.createElement('span');
+                        label.textContent = 'Language';
                         const fill = (lang) => {
                             select.innerHTML = '';
                             const opts = CODE_LANGS.slice();
@@ -318,11 +385,12 @@ export const CarveKit = Extension.create({
                             code.className = lang ? `language-${lang}` : '';
                         };
                         applyLangClass(node.attrs.language || '');
-                        pre.appendChild(select);
                         pre.appendChild(code);
+                        chrome.append(label, select);
+                        dom.append(pre, chrome);
 
                         return {
-                            dom: pre,
+                            dom,
                             contentDOM: code,
                             update: (updated) => {
                                 if (updated.type !== current.type) {
@@ -336,8 +404,8 @@ export const CarveKit = Extension.create({
                                 return true;
                             },
                             // The <select> is chrome, not editable content.
-                            ignoreMutation: (m) => select.contains(m.target),
-                            stopEvent: (e) => select.contains(e.target),
+                            ignoreMutation: (m) => chrome.contains(m.target),
+                            stopEvent: (e) => chrome.contains(e.target),
                         };
                     };
                 },
@@ -396,6 +464,25 @@ export const CarveKit = Extension.create({
                         carveBareMarker: { default: null },
                     };
                 },
+                addCommands() {
+                    return {
+                        ...this.parent?.(),
+                        // A list CREATED in Tiptap has no authored marker to
+                        // preserve. Prefer Carve's constant-width automatic
+                        // marker without changing the schema default: keeping
+                        // that nullable preserves older persisted PM JSON.
+                        toggleOrderedList: () => ({ chain, editor }) => {
+                            const wasActive = editor.isActive(this.name);
+                            const command = chain().toggleList(
+                                this.name, this.options.itemTypeName, this.options.keepMarks,
+                            );
+                            if (wasActive) return command.run();
+                            return command.updateAttributes(this.name, {
+                                carveBareMarker: true, carveDelim: '.',
+                            }).run();
+                        },
+                    };
+                },
             });
             extensions.push(CustomOrderedList.configure(this.options.orderedList ?? {}));
         }
@@ -532,9 +619,26 @@ export const CarveKit = Extension.create({
                 resizable: true,
                 ...this.options.table,
             }));
+            const tableAlign = {
+                default: null,
+                parseHTML: element => !element.hasAttribute('data-carve-inherited-align')
+                    && ['left', 'center', 'right'].includes(element.style.textAlign)
+                    ? element.style.textAlign : null,
+                renderHTML: attrs => ['left', 'center', 'right'].includes(attrs.textAlign)
+                    ? { style: `text-align: ${attrs.textAlign}` } : {},
+            };
+            const inheritedTableAlign = {
+                default: null,
+                parseHTML: () => null,
+                renderHTML: attrs => !attrs.textAlign && ['left', 'center', 'right'].includes(attrs.carveInheritedTextAlign)
+                    ? {
+                        style: `text-align: ${attrs.carveInheritedTextAlign}`,
+                        'data-carve-inherited-align': attrs.carveInheritedTextAlign,
+                    } : {},
+            };
             const tableAttrs = {
                 id: { default: null }, class: { default: null }, carveKeyValues: { default: null },
-                ...attributeOrderSlot(), textAlign: { default: null },
+                ...attributeOrderSlot(), textAlign: tableAlign, carveInheritedTextAlign: inheritedTableAlign,
             };
             const CustomTableRow = TableRow.extend({ addAttributes() { return { ...this.parent?.(), ...tableAttrs }; } });
             const CustomTableCell = TableCell.extend({ addAttributes() { return { ...this.parent?.(), ...tableAttrs }; } });

package/tiptap/carve-to-pm.js

@@ -282,7 +282,7 @@ function unsupported(type, node, ctx) {
     if (ctx?.unsupported === 'preserve') {
         const carveSource = sourceFor(node, ctx);
         if (carveSource) {
-            record(ctx, 'preserved', type, 'kept as exact source in a carveUnsupported atom; not editable');
+            record(ctx, 'preserved', type, 'kept as exact source in an editable carveUnsupported atom');
 
             // The TYPE the atom stands in for, not only its source. Without it
             // a caller can see that something was preserved and never learn
@@ -493,7 +493,10 @@ function convertBlock(node, ctx) {
                 // Dropping it rewrote every alpha and roman list as `1.`.
                 if (node.olType) listNode.attrs.carveOlType = node.olType;
                 if (node.delim) listNode.attrs.carveDelim = node.delim;
-                if (node.bareMarker) listNode.attrs.carveBareMarker = true;
+                // Spell this out in both directions. The schema default is
+                // `true` for newly authored Tiptap lists, while an imported
+                // explicit `1.` list must override that default with `false`.
+                listNode.attrs.carveBareMarker = node.bareMarker === true;
             }
             return listNode;
         }
@@ -774,6 +777,11 @@ function convertTable(node, ctx) {
 
 function convertTableCore(node, ctx) {
     let previousGrid = [];
+    const inheritedColumnAligns = (node.columns || []).map(column => column?.align || null);
+    const headingRow = (node.rows || []).find(row => (row.cells || []).some(cell => cell.header));
+    (headingRow?.cells || []).forEach((cell, col) => {
+        if (cell.header && cell.align) inheritedColumnAligns[col] = cell.align;
+    });
     const rows = (node.rows || []).map((row) => {
         const cells = [];
         const grid = [];
@@ -805,6 +813,7 @@ function convertTableCore(node, ctx) {
             }
             const attrs = { ...(convertAttrs(cell.attrs) || {}) };
             if (cell.align) attrs.textAlign = cell.align;
+            else if (inheritedColumnAligns[col]) attrs.carveInheritedTextAlign = inheritedColumnAligns[col];
             const converted = {
                 type: cell.header ? 'tableHeader' : 'tableCell',
                 attrs,
@@ -840,7 +849,7 @@ function convertInline(nodes, ctx) {
                 const carveSource = sourceFor(node, ctx);
                 if (carveSource) {
                     record(ctx, 'preserved', error.nodeType || node.type,
-                        'kept as exact source in a carveUnsupportedInline atom; not editable');
+                        'kept as exact source in an editable carveUnsupportedInline atom');
                     out.push(unsupportedInlineSource(carveSource, error.nodeType || node.type));
                     continue;
                 }
@@ -1097,7 +1106,8 @@ function convertInlineNode(node, marks, ctx) {
         case 'literal_inline':
             return [{
                 type: 'carveLiteral',
-                attrs: { content: node.content || '', ...(convertAttrs(node.attrs) || {}) },
+                ...(convertAttrs(node.attrs) ? { attrs: convertAttrs(node.attrs) } : {}),
+                content: node.content ? [{ type: 'text', text: node.content }] : [],
                 ...(marks.length ? { marks } : {}),
             }];
 
@@ -1117,9 +1127,9 @@ function convertInlineNode(node, marks, ctx) {
                 type: 'carveRawInline',
                 attrs: {
                     format: node.format || '',
-                    content: node.content || '',
                     ...(convertAttrs(node.attrs) || {}),
                 },
+                content: node.content ? [{ type: 'text', text: node.content }] : [],
                 ...(marks.length ? { marks } : {}),
             }];
 
@@ -1165,7 +1175,8 @@ function convertInlineNode(node, marks, ctx) {
         case 'comment':
             return [{
                 type: 'carveCommentInline',
-                attrs: { content: node.content || '', delimited: Boolean(node.delimited) },
+                attrs: { delimited: Boolean(node.delimited) },
+                content: node.content ? [{ type: 'text', text: node.content }] : [],
             }];
 
         case 'abbreviation':