caracms 0.0.0-stage → 0.2.0

package/src/editor/client/fields/rich-text-doc.ts

@@ -0,0 +1,156 @@
+/**
+ * Rich text's value (rich-text.ts: blocks of runs) and the editor's ProseMirror
+ * document (JSON), both ways. Pure, so it's tested in node.
+ *
+ *   p          ↔ paragraph
+ *   h2, h3     ↔ heading { level }
+ *   ul, ol     ↔ bulletList / orderedList of listItem, each a textblock (its text
+ *                directly, as `<li>` holds it); `fromDoc` also reads an item holding
+ *                paragraphs, the shape before on-page rich text
+ *   a run      ↔ text with marks bold, italic, link { href }
+ *   "\n"       ↔ hardBreak (Shift+Enter: a break inside the paragraph, heading or item)
+ *
+ * A heading field (M9 Decision 11, `options.heading`) has no blocks: its document's
+ * content is inline, as its heading tag holds it, each paragraph a line, the lines
+ * joined by hardBreaks. Read back, every break starts a paragraph.
+ *
+ * `fromDoc` reads back through Phase 1's `parseRichText`, so what the store holds
+ * is always the field's own value: empty paragraphs, items and lists dropped,
+ * breaks at a unit's start or end trimmed, kinds the field doesn't allow as `p`,
+ * links dropped where the field has them off (Decision 3).
+ */
+import { parseRichText, type RichTextOptions, type RichTextValue, type TextRun } from '../../../rich-text.ts';
+
+export interface PMMark {
+	type: 'bold' | 'italic' | 'link';
+	attrs?: { href: string };
+}
+
+export interface PMNode {
+	type: string;
+	attrs?: Record<string, unknown>;
+	content?: PMNode[];
+	text?: string;
+	marks?: PMMark[];
+}
+
+function marksOf(run: TextRun): PMMark[] | undefined {
+	const marks: PMMark[] = [];
+	if (run.bold) marks.push({ type: 'bold' });
+	if (run.italic) marks.push({ type: 'italic' });
+	if (run.href !== undefined) marks.push({ type: 'link', attrs: { href: run.href } });
+	return marks.length ? marks : undefined;
+}
+
+/** A unit's runs as inline nodes: text with marks, and a hardBreak for each `\n`. */
+export function inlineNodes(runs: readonly TextRun[]): PMNode[] {
+	const out: PMNode[] = [];
+	for (const run of runs) {
+		const marks = marksOf(run);
+		run.text.split('\n').forEach((part, i) => {
+			if (i > 0) out.push({ type: 'hardBreak' });
+			if (part !== '') out.push(marks ? { type: 'text', text: part, marks } : { type: 'text', text: part });
+		});
+	}
+	return out;
+}
+
+const textblock = (type: string, runs: readonly TextRun[], attrs?: Record<string, unknown>): PMNode => {
+	const content = inlineNodes(runs);
+	return { type, ...(attrs ? { attrs } : {}), ...(content.length ? { content } : {}) };
+};
+
+/** A value as the editor's document. Never empty: an empty value is one empty paragraph (a heading's: no content). */
+export function toDoc(value: RichTextValue, options?: Pick<RichTextOptions, 'heading'>): PMNode {
+	if (options?.heading) {
+		const lines = value.flatMap((block) => ('items' in block ? block.items : [block.runs]));
+		const content = lines.flatMap((runs, i) => [...(i > 0 ? [{ type: 'hardBreak' }] : []), ...inlineNodes(runs)]);
+		return { type: 'doc', ...(content.length ? { content } : {}) };
+	}
+	const content: PMNode[] = value.map((block) => {
+		if ('items' in block) {
+			return {
+				type: block.kind === 'ol' ? 'orderedList' : 'bulletList',
+				content: block.items.map((runs) => textblock('listItem', runs)),
+			};
+		}
+		if (block.kind === 'h2' || block.kind === 'h3') return textblock('heading', block.runs, { level: block.kind === 'h2' ? 2 : 3 });
+		return textblock('paragraph', block.runs);
+	});
+	return { type: 'doc', content: content.length ? content : [{ type: 'paragraph' }] };
+}
+
+/** Inline nodes as runs: a hardBreak is a `\n` (with no marks). */
+export function runsOf(content: readonly PMNode[] | undefined): TextRun[] {
+	const runs: TextRun[] = [];
+	for (const node of content ?? []) {
+		if (node.type === 'hardBreak') {
+			runs.push({ text: '\n' });
+			continue;
+		}
+		if (node.type !== 'text' || !node.text) continue;
+		const run: TextRun = { text: node.text };
+		for (const mark of node.marks ?? []) {
+			if (mark.type === 'bold') run.bold = true;
+			else if (mark.type === 'italic') run.italic = true;
+			else if (mark.type === 'link' && typeof mark.attrs?.href === 'string') run.href = mark.attrs.href;
+		}
+		runs.push(run);
+	}
+	return runs;
+}
+
+/** Runs split at each `\n`: a heading field's lines (M9 Decision 11). */
+export function splitLines(runs: readonly TextRun[]): TextRun[][] {
+	const lines: TextRun[][] = [[]];
+	for (const run of runs) {
+		run.text.split('\n').forEach((part, i) => {
+			if (i > 0) lines.push([]);
+			if (part !== '') lines.at(-1)!.push({ ...run, text: part });
+		});
+	}
+	return lines;
+}
+
+const isBlock = (node: PMNode) => node.type === 'paragraph' || node.type === 'heading';
+
+/**
+ * A list item's runs: its inline content (a textblock item), or, in the older shape,
+ * its paragraphs joined by breaks should it hold more than one.
+ */
+const itemRuns = (item: PMNode): TextRun[] => {
+	const content = item.content ?? [];
+	if (!content.some(isBlock)) return runsOf(content);
+	return content.filter(isBlock).flatMap((child, i) => [...(i > 0 ? [{ text: '\n' }] : []), ...runsOf(child.content)]);
+};
+
+/** The editor's document as the field's value (normalised by the field's rules). */
+export function fromDoc(doc: PMNode, options: RichTextOptions): RichTextValue {
+	if (options.heading) {
+		// A heading's document is inline (or, from older content, paragraphs): each line a paragraph.
+		const content = (doc.content ?? []).some(isBlock) ? (doc.content ?? []).filter(isBlock).flatMap((child, i) => [...(i > 0 ? [{ type: 'hardBreak' }] : []), ...(child.content ?? [])]) : doc.content;
+		return parseRichText(splitLines(runsOf(content)).map((runs) => ({ kind: 'p', runs })), options);
+	}
+	const blocks: unknown[] = [];
+	for (const node of doc.content ?? []) {
+		if (node.type === 'paragraph') blocks.push({ kind: 'p', runs: runsOf(node.content) });
+		else if (node.type === 'heading') blocks.push({ kind: node.attrs?.level === 3 ? 'h3' : 'h2', runs: runsOf(node.content) });
+		else if (node.type === 'bulletList' || node.type === 'orderedList') {
+			blocks.push({ kind: node.type === 'orderedList' ? 'ol' : 'ul', items: (node.content ?? []).map(itemRuns) });
+		}
+	}
+	return parseRichText(blocks, options);
+}
+
+/**
+ * Pasted plain text (Spec → Text): a blank line starts a new paragraph, a single
+ * newline is a break. The paragraphs' inline content, one array per paragraph.
+ */
+export function pastedParagraphs(text: string): PMNode[][] {
+	return text
+		.replace(/\r\n?/g, '\n')
+		.split(/\n[ \t]*\n/)
+		.map((chunk) => chunk.replace(/^\n+|\n+$/g, ''))
+		.filter((chunk) => chunk.trim() !== '')
+		.map((chunk) => inlineNodes([{ text: chunk }]));
+}

package/src/editor/client/fields/rich-text-schema.ts

@@ -0,0 +1,224 @@
+/**
+ * The rich-text editor's schema (M5a Decision 3): Tiptap (ProseMirror) with
+ * exactly the nodes and marks the field allows, and nothing else. Browser only.
+ *
+ * - Nodes: paragraph, heading (only when the field allows `h2` or `h2`/`h3`, and
+ *   only those levels), bulletList / orderedList of listItem, hardBreak. **A list
+ *   item is a textblock** (on-page rich text, Decision 3): `<li>` holds its text
+ *   directly, as `richTextHtml` renders it, so the editor's DOM is the render's on
+ *   the page too. No lists inside lists. Its commands: rich-text-commands.ts.
+ *   Marks: bold, italic, link (only when the field allows links; it never spans
+ *   into new text typed at its end).
+ * - **No input rules, no paste rules, no autolink, no link-on-paste, no slash
+ *   menu:** typing `**` gives two asterisks. Formatting is the toolbar, ⌘B, ⌘I and ⌘K.
+ * - **The keys follow Spec → Text:** Enter is a new paragraph (in a heading, a new
+ *   paragraph after it; in a list, a new item); Shift+Enter is a line break in the
+ *   paragraph, heading or item. Where the table is silent, Google Docs: Enter in an
+ *   empty item leaves the list; Backspace at the start of an item takes it out of
+ *   the list; Backspace at the start of a heading joins it to the block above (and
+ *   an empty heading at the very start becomes a paragraph).
+ * - **Paste keeps only what the field allows:** HTML is read through this schema
+ *   (anything else is dropped or becomes text); plain text has a blank line start a
+ *   paragraph and a single newline make a break.
+ * - **A heading field** (M9 Decision 11): the document is inline content (no paragraph,
+ *   list or heading nodes), with bold and hardBreak only; Enter is a line break too.
+ * - Undo inside the field is its own (⌘Z / ⇧⌘Z), as every text field's is (Decision 14).
+ */
+import { Extension, Mark, Node } from '@tiptap/core';
+import { history, redo, undo } from '@tiptap/pm/history';
+import { Fragment, Slice } from '@tiptap/pm/model';
+import type { EditorView } from '@tiptap/pm/view';
+import { isLinkHref } from '../../../links.ts';
+import type { HeadingKind } from '../../../rich-text.ts';
+import { liftListItem, splitListItem } from './rich-text-commands.ts';
+import { pastedParagraphs, type PMNode } from './rich-text-doc.ts';
+
+const Doc = Node.create({ name: 'doc', topNode: true, content: 'block+' });
+const Text = Node.create({ name: 'text', group: 'inline' });
+
+const Paragraph = Node.create({
+	name: 'paragraph',
+	group: 'block',
+	content: 'inline*',
+	priority: 1000,
+	parseHTML: () => [{ tag: 'p' }],
+	renderHTML: () => ['p', 0],
+});
+
+const heading = (levels: readonly number[]) =>
+	Node.create({
+		name: 'heading',
+		group: 'block',
+		content: 'inline*',
+		defining: true,
+		addAttributes: () => ({ level: { default: levels[0] ?? 2, rendered: false } }),
+		parseHTML: () => levels.map((level) => ({ tag: `h${level}`, attrs: { level } })),
+		renderHTML: ({ node }) => [`h${node.attrs.level as number}`, 0],
+	});
+
+const list = (name: string, tag: string) =>
+	Node.create({
+		name,
+		group: 'block',
+		content: 'listItem+',
+		parseHTML: () => [{ tag }],
+		renderHTML: () => [tag, 0],
+	});
+
+const ListItem = Node.create({
+	name: 'listItem',
+	content: 'inline*',
+	defining: true,
+	parseHTML: () => [
+		{ tag: 'li' },
+		// A pasted item holding a paragraph (Google Docs, most web pages: <li><p>…</p></li>): its text is the item's.
+		// Above the paragraph's own rule (rules without a priority are 50).
+		{ tag: 'li > p', skip: true, priority: 60 },
+	],
+	renderHTML: () => ['li', 0],
+});
+
+const HardBreak = Node.create({
+	name: 'hardBreak',
+	group: 'inline',
+	inline: true,
+	selectable: false,
+	linebreakReplacement: true,
+	parseHTML: () => [{ tag: 'br' }],
+	renderHTML: () => ['br'],
+	renderText: () => '\n',
+});
+
+const Bold = Mark.create({
+	name: 'bold',
+	parseHTML: () => [
+		{ tag: 'strong' },
+		// Google Docs wraps a paste in <b style="font-weight:normal">.
+		{ tag: 'b', getAttrs: (node) => (node as HTMLElement).style.fontWeight !== 'normal' && null },
+		{ style: 'font-weight=400', clearMark: (mark) => mark.type.name === 'bold' },
+		{ style: 'font-weight', getAttrs: (value) => /^(bold(er)?|[5-9]\d{2,})$/.test(value as string) && null },
+	],
+	renderHTML: () => ['strong', 0],
+});
+
+const Italic = Mark.create({
+	name: 'italic',
+	parseHTML: () => [
+		{ tag: 'em' },
+		{ tag: 'i', getAttrs: (node) => (node as HTMLElement).style.fontStyle !== 'normal' && null },
+		{ style: 'font-style=normal', clearMark: (mark) => mark.type.name === 'italic' },
+		{ style: 'font-style=italic' },
+	],
+	renderHTML: () => ['em', 0],
+});
+
+const Link = Mark.create({
+	name: 'link',
+	// Typing at a link's end doesn't extend it; a link can't hold a link (a mark excludes its own type).
+	inclusive: false,
+	addAttributes: () => ({ href: { default: '' } }),
+	parseHTML: () => [{ tag: 'a[href]', getAttrs: (dom) => ({ href: (dom as HTMLElement).getAttribute('href') ?? '' }) }],
+	// The editor shows a link as a link; an href that fails the rule isn't put in the DOM (it's kept in the value).
+	renderHTML: ({ mark }) => ['a', { href: isLinkHref(mark.attrs.href) ? (mark.attrs.href as string) : null, 'data-href': mark.attrs.href as string }, 0],
+});
+
+/** The keys (Spec → Text) and the field's own undo. ⌘K is the component's (it must not reach the switcher). */
+const Keys = () =>
+	Extension.create({
+		name: 'caracmsKeys',
+		priority: 1000,
+		addProseMirrorPlugins: () => [history()],
+		addKeyboardShortcuts() {
+			const editor = this.editor;
+			const inItem = () => editor.state.selection.$from.parent.type.name === 'listItem';
+			return {
+				'Shift-Enter': () =>
+					editor.commands.command(({ tr, state, dispatch }) => {
+						const br = state.schema.nodes.hardBreak!;
+						if (dispatch) tr.replaceSelectionWith(br.create(), false).scrollIntoView();
+						return true;
+					}),
+				Enter: () => (inItem() ? splitListItem(editor.state, editor.view.dispatch) : false),
+				Backspace: () => {
+					const { empty, $from } = editor.state.selection;
+					if (!empty || $from.parentOffset !== 0 || !inItem()) return false;
+					return liftListItem(editor.state, editor.view.dispatch);
+				},
+				'Mod-b': () => editor.commands.toggleMark('bold'),
+				'Mod-i': () => editor.commands.toggleMark('italic'),
+				'Mod-z': () => undo(editor.state, editor.view.dispatch),
+				'Shift-Mod-z': () => redo(editor.state, editor.view.dispatch),
+				'Mod-y': () => redo(editor.state, editor.view.dispatch),
+				// No sinking an item into a nested list, and no tab characters: Tab moves focus on.
+				Tab: () => false,
+			};
+		},
+	});
+
+/**
+ * A heading field's document (M9 Decision 11): inline content straight inside the
+ * heading tag, as RichText.astro draws it, so there's no paragraph to put a `<p>` in.
+ */
+const InlineDoc = Node.create({ name: 'doc', topNode: true, content: 'inline*' });
+
+/** A heading field's keys: Enter and Shift+Enter both start a new line; bold only. */
+const HeadingKeys = () =>
+	Extension.create({
+		name: 'caracmsHeadingKeys',
+		priority: 1000,
+		addProseMirrorPlugins: () => [history()],
+		addKeyboardShortcuts() {
+			const editor = this.editor;
+			const lineBreak = () =>
+				editor.commands.command(({ tr, state, dispatch }) => {
+					if (dispatch) tr.replaceSelectionWith(state.schema.nodes.hardBreak!.create(), false).scrollIntoView();
+					return true;
+				});
+			return {
+				'Shift-Enter': lineBreak,
+				Enter: lineBreak,
+				'Mod-b': () => editor.commands.toggleMark('bold'),
+				'Mod-i': () => true,
+				'Mod-z': () => undo(editor.state, editor.view.dispatch),
+				'Shift-Mod-z': () => redo(editor.state, editor.view.dispatch),
+				'Mod-y': () => redo(editor.state, editor.view.dispatch),
+				Tab: () => false,
+			};
+		},
+	});
+
+/** Every extension the field's editor runs with. */
+export function richTextExtensions(options: { headings: readonly HeadingKind[]; links: boolean; heading?: boolean }) {
+	if (options.heading) return [InlineDoc, Text, HardBreak, Bold, HeadingKeys()];
+	const levels = options.headings.map((h) => (h === 'h2' ? 2 : 3));
+	return [
+		Doc,
+		Text,
+		Paragraph,
+		...(levels.length ? [heading(levels)] : []),
+		list('bulletList', 'ul'),
+		list('orderedList', 'ol'),
+		ListItem,
+		HardBreak,
+		Bold,
+		Italic,
+		...(options.links ? [Link] : []),
+		Keys(),
+	];
+}
+
+/** Plain text pasted (Spec → Text): a blank line starts a new paragraph, a single newline is a break. In a heading (no paragraphs): each a line. */
+export function clipboardTextParser(text: string, _context: unknown, _plain: boolean, view: EditorView): Slice {
+	const schema = view.state.schema;
+	if (!schema.nodes.paragraph) {
+		const inline = pastedParagraphs(text).flatMap((nodes, i) => [...(i > 0 ? [{ type: 'hardBreak' } as PMNode] : []), ...nodes]);
+		return new Slice(Fragment.fromArray(inline.map((n) => (n.type === 'hardBreak' ? schema.nodes.hardBreak!.create() : schema.text(n.text!)))), 0, 0);
+	}
+	const paragraphs = pastedParagraphs(text).map((inline) =>
+		schema.nodes.paragraph!.create(
+			null,
+			inline.map((n: PMNode) => (n.type === 'hardBreak' ? schema.nodes.hardBreak!.create() : schema.text(n.text!))),
+		),
+	);
+	return Slice.maxOpen(Fragment.fromArray(paragraphs));
+}

package/src/editor/client/fields/stale.ts

@@ -0,0 +1,58 @@
+/**
+ * Fields changed since the preview last rendered (the mockup's #preview-failed: the
+ * field says "Not in the preview yet" while the preview is behind). A field is added
+ * when it changes and dropped when a render lands; the field frame shows the chip
+ * only while the latest render failed (previewStatus.failed).
+ *
+ *   staleFields(editor)     Store<ReadonlySet<string>> of `${blockKey} ${field}`
+ *   staleKey(key, field)
+ *
+ * One store per editor (a WeakMap); nothing on the server, where there's no preview.
+ */
+import { isIndexPart, splitPath } from '../../../fields.ts';
+import type { Editor } from '../editor.ts';
+import { createStore, type Store } from '../state/store.ts';
+
+const stores = new WeakMap<Editor, Store<ReadonlySet<string>>>();
+
+export const staleKey = (key: string, field: string) => `${key} ${field}`;
+
+/**
+ * The field frames a change at `path` marks: a list marks itself (`credits.1.name` →
+ * `credits`, M5a Decision 16), and a group is see-through, so its fields mark their own
+ * frames (`left.heading` → `left`, `left.heading`; `left.gallery.0.alt` → `left`,
+ * `left.gallery`). Every key part up to the first row index.
+ */
+export function staleNames(path: string): string[] {
+	const out: string[] = [];
+	let at = '';
+	for (const part of splitPath(path)) {
+		if (isIndexPart(part)) break;
+		at = at ? `${at}.${part}` : part;
+		out.push(at);
+	}
+	return out;
+}
+
+export function staleFields(editor: Editor): Store<ReadonlySet<string>> {
+	let store = stores.get(editor);
+	if (store) return store;
+	store = createStore<ReadonlySet<string>>(new Set());
+	stores.set(editor, store);
+	const driver = editor.preview;
+	if (!driver) return store;
+	const s = store;
+	editor.doc.subscribe((_, change) => {
+		if (change.kind === 'field') {
+			// A change inside a list (`credits.1.name`) marks the list; inside a group, the group's field.
+			const keys = staleNames(change.field).map((name) => staleKey(change.key, name));
+			if (keys.some((k) => !s.get().has(k))) s.set(new Set([...s.get(), ...keys]));
+		} else if (change.kind === 'load') {
+			if (s.get().size) s.set(new Set());
+		}
+	});
+	driver.onMorph(() => {
+		if (s.get().size) s.set(new Set());
+	});
+	return s;
+}