@ecsplico/editor 2.1.2 → 3.1.0

package/dist/features/composites/reference-text.js

@@ -0,0 +1,89 @@
+import { blockIdOf } from "../../core/schema/block-ids.js";
+import { REFERENCE_TOKEN_SOURCE } from "./reference.js";
+//#region src/features/composites/reference-text.ts
+/** `[@<block id>]` or `[@<block id>, <locator>]`; a `]` inside the locator is written `\]`. */
+const TOKEN = new RegExp(REFERENCE_TOKEN_SOURCE, "g");
+/** Block IDs of every composite in a TipTap JSON tree, added to `into`. */
+function collectCompositeIds(content, into) {
+	if (!content) return into;
+	if (content.type === "composite" && typeof content.attrs?.id === "string" && content.attrs.id) into.add(content.attrs.id);
+	for (const child of content.content ?? []) collectCompositeIds(child, into);
+	return into;
+}
+/**
+* Turns `[@<id>]` / `[@<id>, <locator>]` tokens in text nodes into `reference` nodes (attrs target, locator, empty
+* `label`: the node view resolves the live label) — for imported and AI-generated Markdown, whose parser keeps the
+* token as text. Only ids in `ids` (the Bausteine of the document) match; unknown ids and text in code blocks, inline
+* code or links stay plain. Returns the input unchanged when nothing matched.
+*/
+function referencesFromText(json, ids) {
+	if (!ids.size) return json;
+	const splitText = (node) => {
+		const text = node.text ?? "";
+		if (!text.includes("[@") || node.marks?.some((m) => m.type === "code" || m.type === "link")) return [node];
+		const out = [];
+		let last = 0;
+		for (const match of text.matchAll(TOKEN)) {
+			const target = match[1];
+			if (!ids.has(target)) continue;
+			const at = match.index ?? 0;
+			if (at > last) out.push({
+				...node,
+				text: text.slice(last, at)
+			});
+			out.push({
+				type: "reference",
+				attrs: {
+					target,
+					documentId: null,
+					locator: match[2]?.replace(/\\\]/g, "]").trim() || null,
+					label: ""
+				},
+				...node.marks?.length ? { marks: node.marks } : {}
+			});
+			last = at + match[0].length;
+		}
+		if (!out.length) return [node];
+		if (last < text.length) out.push({
+			...node,
+			text: text.slice(last)
+		});
+		return out;
+	};
+	const walk = (node) => {
+		if (!node.content || node.type === "codeBlock") return node;
+		let changed = false;
+		const content = node.content.flatMap((child) => {
+			const next = child.type === "text" ? splitText(child) : [walk(child)];
+			if (next.length !== 1 || next[0] !== child) changed = true;
+			return next;
+		});
+		return changed ? {
+			...node,
+			content
+		} : node;
+	};
+	return walk(json);
+}
+/** Block IDs of the composites of `doc`: the Bausteine a `[@id]` text may point at. */
+function compositeIdsOf(doc) {
+	const ids = /* @__PURE__ */ new Set();
+	doc.descendants((node) => {
+		if (node.type.name !== "composite") return;
+		const id = blockIdOf(node);
+		if (id) ids.add(id);
+	});
+	return ids;
+}
+/** The `normalize` stage: the composites of the document (`current`) and of `blocks` themselves may be referenced by text. */
+function normalizeReferences(blocks, current) {
+	const doc = {
+		type: "doc",
+		content: blocks
+	};
+	return referencesFromText(doc, collectCompositeIds(doc, new Set(current))).content ?? [];
+}
+//#endregion
+export { collectCompositeIds, compositeIdsOf, normalizeReferences, referencesFromText };
+
+//# sourceMappingURL=reference-text.js.map

package/dist/features/composites/reference-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-text.js","names":[],"sources":["../../../src/features/composites/reference-text.ts"],"sourcesContent":["import type { JSONContent } from '@tiptap/core'\nimport type { Node as PMNode } from '@tiptap/pm/model'\nimport { blockIdOf } from '../../core/schema'\nimport { REFERENCE_TOKEN_SOURCE } from './reference'\n\n/** `[@<block id>]` or `[@<block id>, <locator>]`; a `]` inside the locator is written `\\]`. */\nconst TOKEN = new RegExp(REFERENCE_TOKEN_SOURCE, 'g')\n\n/** Block IDs of every composite in a TipTap JSON tree, added to `into`. */\nexport function collectCompositeIds(content: JSONContent | null | undefined, into: Set<string>): Set<string> {\n  if (!content) return into\n  if (content.type === 'composite' && typeof content.attrs?.id === 'string' && content.attrs.id) into.add(content.attrs.id)\n  for (const child of content.content ?? []) collectCompositeIds(child, into)\n  return into\n}\n\n/**\n * Turns `[@<id>]` / `[@<id>, <locator>]` tokens in text nodes into `reference` nodes (attrs target, locator, empty\n * `label`: the node view resolves the live label) — for imported and AI-generated Markdown, whose parser keeps the\n * token as text. Only ids in `ids` (the Bausteine of the document) match; unknown ids and text in code blocks, inline\n * code or links stay plain. Returns the input unchanged when nothing matched.\n */\nexport function referencesFromText(json: JSONContent, ids: ReadonlySet<string>): JSONContent {\n  if (!ids.size) return json\n\n  const splitText = (node: JSONContent): JSONContent[] => {\n    const text = node.text ?? ''\n    if (!text.includes('[@') || node.marks?.some(m => m.type === 'code' || m.type === 'link')) return [node]\n    const out: JSONContent[] = []\n    let last = 0\n    for (const match of text.matchAll(TOKEN)) {\n      const target = match[1]!\n      if (!ids.has(target)) continue\n      const at = match.index ?? 0\n      if (at > last) out.push({ ...node, text: text.slice(last, at) })\n      out.push({\n        type: 'reference',\n        attrs: { target, documentId: null, locator: match[2]?.replace(/\\\\\\]/g, ']').trim() || null, label: '' },\n        ...(node.marks?.length ? { marks: node.marks } : {}),\n      })\n      last = at + match[0].length\n    }\n    if (!out.length) return [node]\n    if (last < text.length) out.push({ ...node, text: text.slice(last) })\n    return out\n  }\n\n  const walk = (node: JSONContent): JSONContent => {\n    if (!node.content || node.type === 'codeBlock') return node\n    let changed = false\n    const content = node.content.flatMap((child) => {\n      const next = child.type === 'text' ? splitText(child) : [walk(child)]\n      if (next.length !== 1 || next[0] !== child) changed = true\n      return next\n    })\n    return changed ? { ...node, content } : node\n  }\n  return walk(json)\n}\n\n/** Block IDs of the composites of `doc`: the Bausteine a `[@id]` text may point at. */\nexport function compositeIdsOf(doc: PMNode): Set<string> {\n  const ids = new Set<string>()\n  doc.descendants((node) => {\n    if (node.type.name !== 'composite') return\n    const id = blockIdOf(node)\n    if (id) ids.add(id)\n  })\n  return ids\n}\n\n/** The `normalize` stage: the composites of the document (`current`) and of `blocks` themselves may be referenced by text. */\nexport function normalizeReferences(blocks: JSONContent[], current: ReadonlySet<string>): JSONContent[] {\n  const doc: JSONContent = { type: 'doc', content: blocks }\n  return referencesFromText(doc, collectCompositeIds(doc, new Set(current))).content ?? []\n}\n"],"mappings":";;;;AAMA,MAAM,QAAQ,IAAI,OAAO,wBAAwB,GAAG;;AAGpD,SAAgB,oBAAoB,SAAyC,MAAgC;CAC3G,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,SAAS,eAAe,OAAO,QAAQ,OAAO,OAAO,YAAY,QAAQ,MAAM,IAAI,KAAK,IAAI,QAAQ,MAAM,EAAE;CACxH,KAAK,MAAM,SAAS,QAAQ,WAAW,CAAC,GAAG,oBAAoB,OAAO,IAAI;CAC1E,OAAO;AACT;;;;;;;AAQA,SAAgB,mBAAmB,MAAmB,KAAuC;CAC3F,IAAI,CAAC,IAAI,MAAM,OAAO;CAEtB,MAAM,aAAa,SAAqC;EACtD,MAAM,OAAO,KAAK,QAAQ;EAC1B,IAAI,CAAC,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO,MAAK,MAAK,EAAE,SAAS,UAAU,EAAE,SAAS,MAAM,GAAG,OAAO,CAAC,IAAI;EACvG,MAAM,MAAqB,CAAC;EAC5B,IAAI,OAAO;EACX,KAAK,MAAM,SAAS,KAAK,SAAS,KAAK,GAAG;GACxC,MAAM,SAAS,MAAM;GACrB,IAAI,CAAC,IAAI,IAAI,MAAM,GAAG;GACtB,MAAM,KAAK,MAAM,SAAS;GAC1B,IAAI,KAAK,MAAM,IAAI,KAAK;IAAE,GAAG;IAAM,MAAM,KAAK,MAAM,MAAM,EAAE;GAAE,CAAC;GAC/D,IAAI,KAAK;IACP,MAAM;IACN,OAAO;KAAE;KAAQ,YAAY;KAAM,SAAS,MAAM,EAAE,EAAE,QAAQ,SAAS,GAAG,CAAC,CAAC,KAAK,KAAK;KAAM,OAAO;IAAG;IACtG,GAAI,KAAK,OAAO,SAAS,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;GACpD,CAAC;GACD,OAAO,KAAK,MAAM,EAAE,CAAC;EACvB;EACA,IAAI,CAAC,IAAI,QAAQ,OAAO,CAAC,IAAI;EAC7B,IAAI,OAAO,KAAK,QAAQ,IAAI,KAAK;GAAE,GAAG;GAAM,MAAM,KAAK,MAAM,IAAI;EAAE,CAAC;EACpE,OAAO;CACT;CAEA,MAAM,QAAQ,SAAmC;EAC/C,IAAI,CAAC,KAAK,WAAW,KAAK,SAAS,aAAa,OAAO;EACvD,IAAI,UAAU;EACd,MAAM,UAAU,KAAK,QAAQ,SAAS,UAAU;GAC9C,MAAM,OAAO,MAAM,SAAS,SAAS,UAAU,KAAK,IAAI,CAAC,KAAK,KAAK,CAAC;GACpE,IAAI,KAAK,WAAW,KAAK,KAAK,OAAO,OAAO,UAAU;GACtD,OAAO;EACT,CAAC;EACD,OAAO,UAAU;GAAE,GAAG;GAAM;EAAQ,IAAI;CAC1C;CACA,OAAO,KAAK,IAAI;AAClB;;AAGA,SAAgB,eAAe,KAA0B;CACvD,MAAM,sBAAM,IAAI,IAAY;CAC5B,IAAI,aAAa,SAAS;EACxB,IAAI,KAAK,KAAK,SAAS,aAAa;EACpC,MAAM,KAAK,UAAU,IAAI;EACzB,IAAI,IAAI,IAAI,IAAI,EAAE;CACpB,CAAC;CACD,OAAO;AACT;;AAGA,SAAgB,oBAAoB,QAAuB,SAA6C;CACtG,MAAM,MAAmB;EAAE,MAAM;EAAO,SAAS;CAAO;CACxD,OAAO,mBAAmB,KAAK,oBAAoB,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;AACzF"}

package/dist/features/composites/reference.d.ts

@@ -0,0 +1,44 @@
+import { Extension, Node } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import { SuggestionOptions } from "@tiptap/suggestion";
+//#region src/features/composites/reference.d.ts
+/**
+ * Attributes of a reference chip. `target` is the block ID of the referenced Baustein; `label` caches its display text
+ * for the cases the target cannot be resolved (the node view shows the live label and only falls back to this one).
+ */
+export interface ReferenceAttrs {
+  target: string;
+  /** Document of the target; `null` = this document (cross-document references are not resolved yet). */
+  documentId: string | null;
+  /** Position inside the target's source: `S. 12` (PDF page), `03:14` (recording time); `null` = the whole Baustein. */
+  locator: string | null;
+  label: string;
+}
+export declare const REFERENCE_NODE = "reference";
+/** `[@<target>]` / `[@<target>, <locator>]`, the chip's Markdown form; `]` in a locator is escaped as `\]`. */
+export declare function referenceMarkdown(attrs: Pick<ReferenceAttrs, 'target' | 'locator'>): string;
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    reference: {
+      /** Inserts a reference chip (followed by a space) at the selection. */
+      insertReference: (attrs: Partial<ReferenceAttrs> & Pick<ReferenceAttrs, 'target'>) => ReturnType;
+      /** Sets the locator of the reference chip at `pos`; an empty text clears it. */
+      setReferenceLocator: (pos: number, locator: string) => ReturnType;
+    };
+  }
+}
+export interface ReferenceOptions {
+  HTMLAttributes: Record<string, unknown>;
+  /** `[@` popup (client only, see reference-suggestion.ts); `null` = schema only (server, Markdown). */
+  suggestion: Omit<SuggestionOptions<ReferenceAttrs, ReferenceAttrs>, 'editor'> | null;
+}
+/** Own key, so the `[@` popup runs next to the `@` mention and `#` tag popups. */
+export declare const ReferenceSuggestionPluginKey: PluginKey<any>;
+/**
+ * Inline chip pointing at a Baustein of the document (a paper, a recording, a note): shared by the client editor and
+ * the server (collab schema, Markdown). Markdown form `[@<block id>, <locator>]`; text of that form becomes chips again
+ * through `referencesFromText` (the composites feature's `normalize` stage). The client adds the node view and the popup.
+ */
+export declare const ReferenceNode: Node<ReferenceOptions, any>;
+//#endregion
+//# sourceMappingURL=reference.d.ts.map

package/dist/features/composites/reference.js

@@ -0,0 +1,148 @@
+import { Extension, Node, mergeAttributes } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import { Suggestion } from "@tiptap/suggestion";
+//#region src/features/composites/reference.ts
+const REFERENCE_NODE = "reference";
+/** `[@<target>]` / `[@<target>, <locator>]`, the chip's Markdown form; `]` in a locator is escaped as `\]`. */
+function referenceMarkdown(attrs) {
+	const locator = attrs.locator?.trim();
+	return locator ? `[@${attrs.target}, ${locator.replace(/\]/g, "\\]")}]` : `[@${attrs.target}]`;
+}
+/** Pattern of the chip's Markdown form (capture 1: block id, capture 2: locator with `\]` still escaped); compile with `new RegExp(..., 'g')`. */
+const REFERENCE_TOKEN_SOURCE = String.raw`\[@([0-9a-f-]{36})(?:,\s*((?:\\\]|[^\]])+))?\]`;
+/** Own key, so the `[@` popup runs next to the `@` mention and `#` tag popups. */
+const ReferenceSuggestionPluginKey = new PluginKey("referenceSuggestion");
+/**
+* Inline chip pointing at a Baustein of the document (a paper, a recording, a note): shared by the client editor and
+* the server (collab schema, Markdown). Markdown form `[@<block id>, <locator>]`; text of that form becomes chips again
+* through `referencesFromText` (the composites feature's `normalize` stage). The client adds the node view and the popup.
+*/
+const ReferenceNode = Node.create({
+	name: REFERENCE_NODE,
+	group: "inline",
+	inline: true,
+	atom: true,
+	selectable: true,
+	priority: 99,
+	markdownTokenizer: {
+		name: "referenceToken",
+		level: "inline",
+		start: (src) => src.search(/\[@[0-9a-f-]{36}/),
+		tokenize: (src) => {
+			const match = new RegExp(`^${REFERENCE_TOKEN_SOURCE}`).exec(src);
+			return match ? {
+				type: "text",
+				raw: match[0],
+				text: match[0]
+			} : void 0;
+		}
+	},
+	addOptions() {
+		return {
+			HTMLAttributes: { class: "reference" },
+			suggestion: null
+		};
+	},
+	addAttributes() {
+		return {
+			target: {
+				default: "",
+				parseHTML: (el) => el.getAttribute("data-target") ?? "",
+				renderHTML: (attrs) => ({ "data-target": attrs.target })
+			},
+			documentId: {
+				default: null,
+				parseHTML: (el) => el.getAttribute("data-document"),
+				renderHTML: (attrs) => attrs.documentId ? { "data-document": attrs.documentId } : {}
+			},
+			locator: {
+				default: null,
+				parseHTML: (el) => el.getAttribute("data-locator"),
+				renderHTML: (attrs) => attrs.locator ? { "data-locator": attrs.locator } : {}
+			},
+			label: {
+				default: "",
+				parseHTML: (el) => el.getAttribute("data-label") ?? el.textContent ?? "",
+				renderHTML: (attrs) => ({ "data-label": attrs.label })
+			}
+		};
+	},
+	parseHTML() {
+		return [{ tag: `span[data-type="${this.name}"]` }];
+	},
+	renderHTML({ node, HTMLAttributes }) {
+		return [
+			"span",
+			mergeAttributes({ "data-type": this.name }, this.options.HTMLAttributes, HTMLAttributes),
+			String(node.attrs.label ?? "")
+		];
+	},
+	renderText: ({ node }) => referenceMarkdown(node.attrs),
+	renderMarkdown: (node) => referenceMarkdown({
+		target: String(node.attrs?.target ?? ""),
+		locator: typeof node.attrs?.locator === "string" ? node.attrs.locator : null
+	}),
+	addCommands() {
+		return {
+			insertReference: (attrs) => ({ commands }) => commands.insertContent([{
+				type: this.name,
+				attrs
+			}, {
+				type: "text",
+				text: " "
+			}]),
+			setReferenceLocator: (pos, locator) => ({ tr, dispatch }) => {
+				const node = tr.doc.nodeAt(pos);
+				if (node?.type.name !== this.name) return false;
+				if (dispatch) tr.setNodeMarkup(pos, void 0, {
+					...node.attrs,
+					locator: locator.trim() || null
+				});
+				return true;
+			}
+		};
+	},
+	addExtensions() {
+		const { suggestion } = this.options;
+		return suggestion ? [ReferenceSuggestion.configure({ suggestion })] : [];
+	}
+});
+/**
+* The `[@` popup of ReferenceNode. Priority 101 (like TagNode), above core's Keymap (100): extension priority orders
+* the ProseMirror plugins' `handleKeyDown`, and with a lower one Enter would split the paragraph instead of picking.
+*/
+const ReferenceSuggestion = Extension.create({
+	name: "referenceSuggestion",
+	priority: 101,
+	addOptions() {
+		return { suggestion: null };
+	},
+	addProseMirrorPlugins() {
+		const { suggestion } = this.options;
+		if (!suggestion) return [];
+		const { allow, ...rest } = suggestion;
+		return [Suggestion({
+			pluginKey: ReferenceSuggestionPluginKey,
+			char: "[@",
+			allowSpaces: true,
+			allow: (p) => allow?.(p) ?? true,
+			command: ({ editor, range, props }) => {
+				if (editor.view.state.selection.$to.nodeAfter?.text?.startsWith(" ")) range.to += 1;
+				editor.chain().focus().insertContentAt(range, [{
+					type: REFERENCE_NODE,
+					attrs: props
+				}, {
+					type: "text",
+					text: " "
+				}]).run();
+				editor.view.dom.ownerDocument.defaultView?.getSelection()?.collapseToEnd();
+			},
+			...rest,
+			editor: this.editor
+		})];
+	}
+});
+//#endregion
+export { REFERENCE_NODE, REFERENCE_TOKEN_SOURCE, ReferenceNode, ReferenceSuggestion, ReferenceSuggestionPluginKey, referenceMarkdown };
+
+//# sourceMappingURL=reference.js.map

package/dist/features/composites/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","names":[],"sources":["../../../src/features/composites/reference.ts"],"sourcesContent":["import { Extension, mergeAttributes, Node } from '@tiptap/core'\nimport { PluginKey } from '@tiptap/pm/state'\nimport { Suggestion, type SuggestionOptions } from '@tiptap/suggestion'\n\n/**\n * Attributes of a reference chip. `target` is the block ID of the referenced Baustein; `label` caches its display text\n * for the cases the target cannot be resolved (the node view shows the live label and only falls back to this one).\n */\nexport interface ReferenceAttrs {\n  target: string\n  /** Document of the target; `null` = this document (cross-document references are not resolved yet). */\n  documentId: string | null\n  /** Position inside the target's source: `S. 12` (PDF page), `03:14` (recording time); `null` = the whole Baustein. */\n  locator: string | null\n  label: string\n}\n\nexport const REFERENCE_NODE = 'reference'\n\n/** Trigger of the popup. Two characters: `[@` is the Markdown form, so typing it by hand and picking from the list agree. */\nexport const REFERENCE_TRIGGER = '[@'\n\n/** `[@<target>]` / `[@<target>, <locator>]`, the chip's Markdown form; `]` in a locator is escaped as `\\]`. */\nexport function referenceMarkdown(attrs: Pick<ReferenceAttrs, 'target' | 'locator'>): string {\n  const locator = attrs.locator?.trim()\n  return locator ? `[@${attrs.target}, ${locator.replace(/\\]/g, '\\\\]')}]` : `[@${attrs.target}]`\n}\n\n/** Pattern of the chip's Markdown form (capture 1: block id, capture 2: locator with `\\]` still escaped); compile with `new RegExp(..., 'g')`. */\nexport const REFERENCE_TOKEN_SOURCE = String.raw`\\[@([0-9a-f-]{36})(?:,\\s*((?:\\\\\\]|[^\\]])+))?\\]`\n\ndeclare module '@tiptap/core' {\n  interface Commands<ReturnType> {\n    reference: {\n      /** Inserts a reference chip (followed by a space) at the selection. */\n      insertReference: (attrs: Partial<ReferenceAttrs> & Pick<ReferenceAttrs, 'target'>) => ReturnType\n      /** Sets the locator of the reference chip at `pos`; an empty text clears it. */\n      setReferenceLocator: (pos: number, locator: string) => ReturnType\n    }\n  }\n}\n\nexport interface ReferenceOptions {\n  HTMLAttributes: Record<string, unknown>\n  /** `[@` popup (client only, see reference-suggestion.ts); `null` = schema only (server, Markdown). */\n  suggestion: Omit<SuggestionOptions<ReferenceAttrs, ReferenceAttrs>, 'editor'> | null\n}\n\n/** Own key, so the `[@` popup runs next to the `@` mention and `#` tag popups. */\nexport const ReferenceSuggestionPluginKey = new PluginKey('referenceSuggestion')\n\n/**\n * Inline chip pointing at a Baustein of the document (a paper, a recording, a note): shared by the client editor and\n * the server (collab schema, Markdown). Markdown form `[@<block id>, <locator>]`; text of that form becomes chips again\n * through `referencesFromText` (the composites feature's `normalize` stage). The client adds the node view and the popup.\n */\nexport const ReferenceNode = Node.create<ReferenceOptions>({\n  name: REFERENCE_NODE,\n  group: 'inline',\n  inline: true,\n  atom: true,\n  selectable: true,\n  // Just below Mention (100): TipTap's Markdown manager registers the tokenizers in priority order and marked tries the\n  // last registered first, so `markdownTokenizer` below sees `[@<id>]` before Mention's `[@ ...]` shortcode does.\n  priority: 99,\n\n  // Claims `[@<block id>, <locator>]` as plain text, so Mention's tokenizer (which takes every `[@...]`) leaves it alone;\n  // the composites feature's `normalize` stage turns it into a chip when the id belongs to a Baustein of the document.\n  markdownTokenizer: {\n    name: 'referenceToken',\n    level: 'inline',\n    start: src => src.search(/\\[@[0-9a-f-]{36}/),\n    tokenize: (src) => {\n      const match = new RegExp(`^${REFERENCE_TOKEN_SOURCE}`).exec(src)\n      return match ? { type: 'text', raw: match[0], text: match[0] } : undefined\n    },\n  },\n\n  addOptions() {\n    return { HTMLAttributes: { class: 'reference' }, suggestion: null }\n  },\n\n  addAttributes() {\n    return {\n      target: {\n        default: '',\n        parseHTML: el => el.getAttribute('data-target') ?? '',\n        renderHTML: attrs => ({ 'data-target': attrs.target }),\n      },\n      documentId: {\n        default: null,\n        parseHTML: el => el.getAttribute('data-document'),\n        renderHTML: attrs => attrs.documentId ? { 'data-document': attrs.documentId } : {},\n      },\n      locator: {\n        default: null,\n        parseHTML: el => el.getAttribute('data-locator'),\n        renderHTML: attrs => attrs.locator ? { 'data-locator': attrs.locator } : {},\n      },\n      label: {\n        default: '',\n        parseHTML: el => el.getAttribute('data-label') ?? el.textContent ?? '',\n        renderHTML: attrs => ({ 'data-label': attrs.label }),\n      },\n    }\n  },\n\n  parseHTML() {\n    return [{ tag: `span[data-type=\"${this.name}\"]` }]\n  },\n\n  renderHTML({ node, HTMLAttributes }) {\n    return ['span', mergeAttributes({ 'data-type': this.name }, this.options.HTMLAttributes, HTMLAttributes), String(node.attrs.label ?? '')]\n  },\n\n  renderText: ({ node }) => referenceMarkdown(node.attrs as ReferenceAttrs),\n\n  // Markdown export (editor.getMarkdown(), AI context/selection) writes the chip as `[@<id>, <locator>]`.\n  renderMarkdown: node => referenceMarkdown({ target: String(node.attrs?.target ?? ''), locator: typeof node.attrs?.locator === 'string' ? node.attrs.locator : null }),\n\n  addCommands() {\n    return {\n      insertReference: attrs => ({ commands }) =>\n        commands.insertContent([{ type: this.name, attrs }, { type: 'text', text: ' ' }]),\n      setReferenceLocator: (pos, locator) => ({ tr, dispatch }) => {\n        const node = tr.doc.nodeAt(pos)\n        if (node?.type.name !== this.name) return false\n        if (dispatch) tr.setNodeMarkup(pos, undefined, { ...node.attrs, locator: locator.trim() || null })\n        return true\n      },\n    }\n  },\n\n  // The popup lives in a companion extension (see `ReferenceSuggestion`): it must rank above TipTap's core keymap\n  // (100) to see Enter first, which this node cannot (its priority orders the Markdown tokenizer).\n  addExtensions() {\n    const { suggestion } = this.options\n    return suggestion ? [ReferenceSuggestion.configure({ suggestion })] : []\n  },\n})\n\n/**\n * The `[@` popup of ReferenceNode. Priority 101 (like TagNode), above core's Keymap (100): extension priority orders\n * the ProseMirror plugins' `handleKeyDown`, and with a lower one Enter would split the paragraph instead of picking.\n */\nexport const ReferenceSuggestion = Extension.create<{ suggestion: NonNullable<ReferenceOptions['suggestion']> | null }>({\n  name: 'referenceSuggestion',\n  priority: 101,\n\n  addOptions() {\n    return { suggestion: null }\n  },\n\n  addProseMirrorPlugins() {\n    const { suggestion } = this.options\n    if (!suggestion) return []\n    const { allow, ...rest } = suggestion\n    return [Suggestion<ReferenceAttrs, ReferenceAttrs>({\n      pluginKey: ReferenceSuggestionPluginKey,\n      char: REFERENCE_TRIGGER,\n      allowSpaces: true,\n      allow: p => allow?.(p) ?? true,\n      command: ({ editor, range, props }) => {\n        // Reuse a following space instead of doubling it (as Mention does).\n        const nodeAfter = editor.view.state.selection.$to.nodeAfter\n        if (nodeAfter?.text?.startsWith(' ')) range.to += 1\n        editor.chain().focus()\n          .insertContentAt(range, [{ type: REFERENCE_NODE, attrs: props }, { type: 'text', text: ' ' }])\n          .run()\n        editor.view.dom.ownerDocument.defaultView?.getSelection()?.collapseToEnd()\n      },\n      ...rest,\n      editor: this.editor,\n    })]\n  },\n})\n"],"mappings":"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"}

package/dist/features/composites/reveal-source.d.ts

@@ -0,0 +1,32 @@
+import { Editor, Extension } from "@tiptap/core";
+//#region src/features/composites/reveal-source.d.ts
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    sourceReveal: {
+      /** Seek and play the media of the source-holding Baustein enclosing `pos` to `seconds`; silent when there is none. */
+      seekSource: (pos: number, seconds: number) => ReturnType;
+    };
+  }
+}
+/** Where in the source a locator points: a time in seconds (`3:07`) or a PDF page (`S. 12`, `p. 12`, `12`). */
+export type SourceLocator = {
+  seconds: number;
+} | {
+  page: number;
+};
+/** Parses a reference locator; null for anything that is not a time or a page number. */
+export declare function parseLocator(locator: string | null | undefined): SourceLocator | null;
+/**
+ * Seeks and plays the audio/video of the nearest source-holding Baustein around `pos` (a transcript segment inside a
+ * rendition reaches the recording that way). Silent when there is no source or no media element.
+ */
+export declare function seekSource(editor: Editor, pos: number, seconds: number): void;
+/**
+ * Shows the source of Baustein `targetId` at `locator`: a `mm:ss` time seeks the media, a page number opens a PDF source
+ * at that page; then the source block flashes. Silent when the target or its source is gone.
+ */
+export declare function revealSource(editor: Editor, targetId: string, locator: string | null): void;
+/** Registers `seekSource` as an editor command, so features that must not import composites (transcript) can call it. */
+export declare const SourceReveal: Extension<any, any>;
+//#endregion
+//# sourceMappingURL=reveal-source.d.ts.map

package/dist/features/composites/reveal-source.js

@@ -0,0 +1,89 @@
+import { blockIdOf, findBlockById } from "../../core/schema/block-ids.js";
+import { sourceOf } from "./derivation.js";
+import { compositeKindsOf } from "./nodes.js";
+import { Extension } from "@tiptap/core";
+//#region src/features/composites/reveal-source.ts
+/** DOM event the PDF file view listens for; `detail` is the 1-based page to open the viewer at. */
+const REVEAL_PAGE_EVENT = "sk-reveal-page";
+const TIME_LOCATOR = /^(\d+):(\d{2})$/;
+const PAGE_LOCATOR = /^(?:S\.|p\.)?\s*(\d+)$/i;
+/** Parses a reference locator; null for anything that is not a time or a page number. */
+function parseLocator(locator) {
+	const text = locator?.trim();
+	if (!text) return null;
+	const time = TIME_LOCATOR.exec(text);
+	if (time) return { seconds: Number(time[1]) * 60 + Number(time[2]) };
+	const page = PAGE_LOCATOR.exec(text);
+	if (page && Number(page[1]) > 0) return { page: Number(page[1]) };
+	return null;
+}
+/** The source block of the composite `composite` at `pos` with its document position, or null. */
+function sourceAt(editor, composite, pos) {
+	const source = sourceOf(composite, compositeKindsOf(editor));
+	if (!source) return null;
+	let sourcePos = pos + 1;
+	for (let i = 0; i < source.index; i++) sourcePos += composite.child(i).nodeSize;
+	return {
+		node: source.node,
+		pos: sourcePos
+	};
+}
+/** The element of the node view at `pos` that carries the view's own listeners (the framework's wrapper), or null. */
+function viewElement(editor, pos) {
+	const dom = editor.view.nodeDOM(pos);
+	if (!(dom instanceof HTMLElement)) return null;
+	return dom.matches("[data-node-view-wrapper]") ? dom : dom.querySelector("[data-node-view-wrapper]") ?? dom;
+}
+function playAt(editor, sourcePos, seconds) {
+	const dom = editor.view.nodeDOM(sourcePos);
+	if (!(dom instanceof HTMLElement)) return false;
+	const media = dom.matches("audio,video") ? dom : dom.querySelector("audio,video");
+	if (!media) return false;
+	media.currentTime = seconds;
+	media.play().catch(() => {});
+	return true;
+}
+/**
+* Seeks and plays the audio/video of the nearest source-holding Baustein around `pos` (a transcript segment inside a
+* rendition reaches the recording that way). Silent when there is no source or no media element.
+*/
+function seekSource(editor, pos, seconds) {
+	if (!Number.isFinite(seconds) || seconds < 0) return;
+	const $pos = editor.state.doc.resolve(pos);
+	for (let depth = $pos.depth; depth >= 0; depth--) {
+		const composite = $pos.node(depth);
+		if (composite.type.name !== "composite") continue;
+		const source = sourceAt(editor, composite, $pos.before(depth));
+		if (!source) continue;
+		playAt(editor, source.pos, seconds);
+		return;
+	}
+}
+/**
+* Shows the source of Baustein `targetId` at `locator`: a `mm:ss` time seeks the media, a page number opens a PDF source
+* at that page; then the source block flashes. Silent when the target or its source is gone.
+*/
+function revealSource(editor, targetId, locator) {
+	const target = findBlockById(editor.state.doc, targetId);
+	if (!target) return;
+	const source = sourceAt(editor, target.node, target.pos);
+	if (!source) return;
+	const parsed = parseLocator(locator);
+	if (parsed && "seconds" in parsed) playAt(editor, source.pos, parsed.seconds);
+	else if (parsed && source.node.type.name === "file" && source.node.attrs.mimeType === "application/pdf") viewElement(editor, source.pos)?.dispatchEvent(new CustomEvent(REVEAL_PAGE_EVENT, { detail: parsed.page }));
+	editor.commands.revealBlock(blockIdOf(source.node) ?? targetId);
+}
+/** Registers `seekSource` as an editor command, so features that must not import composites (transcript) can call it. */
+const SourceReveal = Extension.create({
+	name: "sourceReveal",
+	addCommands() {
+		return { seekSource: (pos, seconds) => ({ editor }) => {
+			seekSource(editor, pos, seconds);
+			return true;
+		} };
+	}
+});
+//#endregion
+export { REVEAL_PAGE_EVENT, SourceReveal, parseLocator, revealSource, seekSource };
+
+//# sourceMappingURL=reveal-source.js.map

package/dist/features/composites/reveal-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reveal-source.js","names":[],"sources":["../../../src/features/composites/reveal-source.ts"],"sourcesContent":["// Client-only: show a Baustein's source (the media block of a source-holding kind) at a spot. A time seeks and plays the\n// audio/video; a page number reloads the PDF viewer at that page. Composites must not import media or transcript, so\n// `seekSource` is also registered as an editor command (`SourceReveal`) for the transcript node view to call.\nimport { Extension, type Editor } from '@tiptap/core'\nimport type { Node as PMNode } from '@tiptap/pm/model'\nimport { blockIdOf, findBlockById } from '../../core/schema'\nimport { sourceOf } from './derivation'\nimport { compositeKindsOf } from './nodes'\n\ndeclare module '@tiptap/core' {\n  interface Commands<ReturnType> {\n    sourceReveal: {\n      /** Seek and play the media of the source-holding Baustein enclosing `pos` to `seconds`; silent when there is none. */\n      seekSource: (pos: number, seconds: number) => ReturnType\n    }\n  }\n}\n\n/** DOM event the PDF file view listens for; `detail` is the 1-based page to open the viewer at. */\nexport const REVEAL_PAGE_EVENT = 'sk-reveal-page'\n\n/** Where in the source a locator points: a time in seconds (`3:07`) or a PDF page (`S. 12`, `p. 12`, `12`). */\nexport type SourceLocator = { seconds: number } | { page: number }\n\nconst TIME_LOCATOR = /^(\\d+):(\\d{2})$/\nconst PAGE_LOCATOR = /^(?:S\\.|p\\.)?\\s*(\\d+)$/i\n\n/** Parses a reference locator; null for anything that is not a time or a page number. */\nexport function parseLocator(locator: string | null | undefined): SourceLocator | null {\n  const text = locator?.trim()\n  if (!text) return null\n  const time = TIME_LOCATOR.exec(text)\n  if (time) return { seconds: Number(time[1]) * 60 + Number(time[2]) }\n  const page = PAGE_LOCATOR.exec(text)\n  if (page && Number(page[1]) > 0) return { page: Number(page[1]) }\n  return null\n}\n\n/** The source block of the composite `composite` at `pos` with its document position, or null. */\nfunction sourceAt(editor: Editor, composite: PMNode, pos: number): { node: PMNode, pos: number } | null {\n  const source = sourceOf(composite, compositeKindsOf(editor))\n  if (!source) return null\n  let sourcePos = pos + 1\n  for (let i = 0; i < source.index; i++) sourcePos += composite.child(i).nodeSize\n  return { node: source.node, pos: sourcePos }\n}\n\n/** The element of the node view at `pos` that carries the view's own listeners (the framework's wrapper), or null. */\nfunction viewElement(editor: Editor, pos: number): HTMLElement | null {\n  const dom = editor.view.nodeDOM(pos)\n  if (!(dom instanceof HTMLElement)) return null\n  return dom.matches('[data-node-view-wrapper]') ? dom : dom.querySelector<HTMLElement>('[data-node-view-wrapper]') ?? dom\n}\n\nfunction playAt(editor: Editor, sourcePos: number, seconds: number): boolean {\n  const dom = editor.view.nodeDOM(sourcePos)\n  if (!(dom instanceof HTMLElement)) return false\n  const media = dom.matches('audio,video') ? dom as HTMLMediaElement : dom.querySelector<HTMLMediaElement>('audio,video')\n  if (!media) return false\n  media.currentTime = seconds\n  media.play().catch(() => { /* autoplay refused: the seek still happened */ })\n  return true\n}\n\n/**\n * Seeks and plays the audio/video of the nearest source-holding Baustein around `pos` (a transcript segment inside a\n * rendition reaches the recording that way). Silent when there is no source or no media element.\n */\nexport function seekSource(editor: Editor, pos: number, seconds: number): void {\n  if (!Number.isFinite(seconds) || seconds < 0) return\n  const $pos = editor.state.doc.resolve(pos)\n  for (let depth = $pos.depth; depth >= 0; depth--) {\n    const composite = $pos.node(depth)\n    if (composite.type.name !== 'composite') continue\n    const source = sourceAt(editor, composite, $pos.before(depth))\n    if (!source) continue\n    playAt(editor, source.pos, seconds)\n    return\n  }\n}\n\n/**\n * Shows the source of Baustein `targetId` at `locator`: a `mm:ss` time seeks the media, a page number opens a PDF source\n * at that page; then the source block flashes. Silent when the target or its source is gone.\n */\nexport function revealSource(editor: Editor, targetId: string, locator: string | null): void {\n  const target = findBlockById(editor.state.doc, targetId)\n  if (!target) return\n  const source = sourceAt(editor, target.node, target.pos)\n  if (!source) return\n  const parsed = parseLocator(locator)\n  if (parsed && 'seconds' in parsed) {\n    playAt(editor, source.pos, parsed.seconds)\n  } else if (parsed && source.node.type.name === 'file' && source.node.attrs.mimeType === 'application/pdf') {\n    viewElement(editor, source.pos)?.dispatchEvent(new CustomEvent<number>(REVEAL_PAGE_EVENT, { detail: parsed.page }))\n  }\n  editor.commands.revealBlock(blockIdOf(source.node) ?? targetId)\n}\n\n/** Registers `seekSource` as an editor command, so features that must not import composites (transcript) can call it. */\nexport const SourceReveal = Extension.create({\n  name: 'sourceReveal',\n\n  addCommands() {\n    return {\n      // Does not dispatch: a nested dispatch would leave the command's own transaction stale.\n      seekSource: (pos, seconds) => ({ editor }) => {\n        seekSource(editor, pos, seconds)\n        return true\n      },\n    }\n  },\n})\n"],"mappings":";;;;;;AAmBA,MAAa,oBAAoB;AAKjC,MAAM,eAAe;AACrB,MAAM,eAAe;;AAGrB,SAAgB,aAAa,SAA0D;CACrF,MAAM,OAAO,SAAS,KAAK;CAC3B,IAAI,CAAC,MAAM,OAAO;CAClB,MAAM,OAAO,aAAa,KAAK,IAAI;CACnC,IAAI,MAAM,OAAO,EAAE,SAAS,OAAO,KAAK,EAAE,IAAI,KAAK,OAAO,KAAK,EAAE,EAAE;CACnE,MAAM,OAAO,aAAa,KAAK,IAAI;CACnC,IAAI,QAAQ,OAAO,KAAK,EAAE,IAAI,GAAG,OAAO,EAAE,MAAM,OAAO,KAAK,EAAE,EAAE;CAChE,OAAO;AACT;;AAGA,SAAS,SAAS,QAAgB,WAAmB,KAAmD;CACtG,MAAM,SAAS,SAAS,WAAW,iBAAiB,MAAM,CAAC;CAC3D,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI,YAAY,MAAM;CACtB,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,OAAO,KAAK,aAAa,UAAU,MAAM,CAAC,CAAC,CAAC;CACvE,OAAO;EAAE,MAAM,OAAO;EAAM,KAAK;CAAU;AAC7C;;AAGA,SAAS,YAAY,QAAgB,KAAiC;CACpE,MAAM,MAAM,OAAO,KAAK,QAAQ,GAAG;CACnC,IAAI,EAAE,eAAe,cAAc,OAAO;CAC1C,OAAO,IAAI,QAAQ,0BAA0B,IAAI,MAAM,IAAI,cAA2B,0BAA0B,KAAK;AACvH;AAEA,SAAS,OAAO,QAAgB,WAAmB,SAA0B;CAC3E,MAAM,MAAM,OAAO,KAAK,QAAQ,SAAS;CACzC,IAAI,EAAE,eAAe,cAAc,OAAO;CAC1C,MAAM,QAAQ,IAAI,QAAQ,aAAa,IAAI,MAA0B,IAAI,cAAgC,aAAa;CACtH,IAAI,CAAC,OAAO,OAAO;CACnB,MAAM,cAAc;CACpB,MAAM,KAAK,CAAC,CAAC,YAAY,CAAkD,CAAC;CAC5E,OAAO;AACT;;;;;AAMA,SAAgB,WAAW,QAAgB,KAAa,SAAuB;CAC7E,IAAI,CAAC,OAAO,SAAS,OAAO,KAAK,UAAU,GAAG;CAC9C,MAAM,OAAO,OAAO,MAAM,IAAI,QAAQ,GAAG;CACzC,KAAK,IAAI,QAAQ,KAAK,OAAO,SAAS,GAAG,SAAS;EAChD,MAAM,YAAY,KAAK,KAAK,KAAK;EACjC,IAAI,UAAU,KAAK,SAAS,aAAa;EACzC,MAAM,SAAS,SAAS,QAAQ,WAAW,KAAK,OAAO,KAAK,CAAC;EAC7D,IAAI,CAAC,QAAQ;EACb,OAAO,QAAQ,OAAO,KAAK,OAAO;EAClC;CACF;AACF;;;;;AAMA,SAAgB,aAAa,QAAgB,UAAkB,SAA8B;CAC3F,MAAM,SAAS,cAAc,OAAO,MAAM,KAAK,QAAQ;CACvD,IAAI,CAAC,QAAQ;CACb,MAAM,SAAS,SAAS,QAAQ,OAAO,MAAM,OAAO,GAAG;CACvD,IAAI,CAAC,QAAQ;CACb,MAAM,SAAS,aAAa,OAAO;CACnC,IAAI,UAAU,aAAa,QACzB,OAAO,QAAQ,OAAO,KAAK,OAAO,OAAO;MACpC,IAAI,UAAU,OAAO,KAAK,KAAK,SAAS,UAAU,OAAO,KAAK,MAAM,aAAa,mBACtF,YAAY,QAAQ,OAAO,GAAG,CAAC,EAAE,cAAc,IAAI,YAAoB,mBAAmB,EAAE,QAAQ,OAAO,KAAK,CAAC,CAAC;CAEpH,OAAO,SAAS,YAAY,UAAU,OAAO,IAAI,KAAK,QAAQ;AAChE;;AAGA,MAAa,eAAe,UAAU,OAAO;CAC3C,MAAM;CAEN,cAAc;EACZ,OAAO,EAEL,aAAa,KAAK,aAAa,EAAE,aAAa;GAC5C,WAAW,QAAQ,KAAK,OAAO;GAC/B,OAAO;EACT,EACF;CACF;AACF,CAAC"}

package/dist/features/composites/rows.d.ts

@@ -27,6 +27,8 @@ export interface CompositeRow {
   meta: Record<string, unknown>;
   /** The meta fields of the composite's kind. */
   fields: readonly CompositeMetaField[];
+  /** `false` when the composite's kind hides its tag row (`CompositeKind.chrome.tags === false`): chips, the add-tag control and the tags field stay away. */
+  tagsVisible: boolean;
   /** Nesting level among composites, 0 = outermost. */
   depth: number;
 }
@@ -36,14 +38,33 @@ export interface CompositeMention {
   label: string;
   color: string | null;
 }
+/** A reference to a Baustein: a `reference` chip in the text of block `from`, or a `reference` field of the Baustein `from`. */
+export interface CompositeReference {
+  /** Block ID of the referenced Baustein. */
+  target: string;
+  /** Block ID of the nearest block around the chip (the Baustein itself for a field); `null` when that block has no ID yet. */
+  from: string | null;
+  /** The chip's locator (`S. 12`, `03:14`); `null` for a field or a chip without one. */
+  locator: string | null;
+}
 /**
- * Reads every composite of `doc` (also inside quotes and lists) as a row, in document order, and the distinct
- * `@mention` chips anywhere in the document. Unknown kinds get the `section` kind's presentation under their own ID.
+ * Reads every composite of `doc` (also inside quotes and lists) as a row, in document order, the distinct
+ * `@mention` chips anywhere in the document and every reference (`reference` chips and `reference` fields) in document
+ * order. Unknown kinds get the `section` kind's presentation under their own ID.
  */
 export declare function compositeRows(doc: Node$1, kinds: readonly CompositeKind[]): {
   rows: CompositeRow[];
   mentions: CompositeMention[];
+  references: CompositeReference[];
 };
+/** A place that refers to a Baustein: the block holding the chip (or the Baustein with the field) and a short text of it. */
+export interface CompositeBacklink {
+  from: string;
+  locator: string | null;
+  excerpt: string;
+}
+/** Every reference to the Baustein `target` in document order; references whose enclosing block has no ID (or is gone) are left out, as nothing could reveal them. */
+export declare function compositeBacklinks(doc: Node$1, kinds: readonly CompositeKind[], target: string): CompositeBacklink[];
 /** The innermost row around document position `pos`, `null` outside of any composite. */
 export declare function compositeRowAt(rows: readonly CompositeRow[], pos: number): CompositeRow | null;
 /**
@@ -56,7 +77,8 @@ export declare function compositeOfRow(doc: Node$1, row: Pick<CompositeRow, 'id'
 } | null;
 /**
  * `meta` with `value` stored under `field.key`: a number field converts a numeric string, an empty value (`''`,
- * `null`, `undefined`, `NaN`) removes the key. Returns a new object; `meta` is not changed.
+ * `null`, `undefined`, `NaN`) removes the key. A `multiselect` field keeps the string entries of an array value and
+ * removes the key when none is left. Returns a new object; `meta` is not changed.
  */
 export declare function compositeMetaWith(meta: Record<string, unknown>, field: Pick<CompositeMetaField, 'key' | 'type'>, value: unknown): Record<string, unknown>;
 /** Stores `value` under the meta field `key` of the row's composite (see `compositeMetaWith`), in one transaction. */