@simple-mark/codemirror 0.2.0 → 0.3.1

package/README.md

@@ -11,6 +11,7 @@ const view = createEditor(document.getElementById('editor')!, {
   doc: '# Hello **world**\n\n| a | b |\n|---|---|\n| 1 | 2 |\n',
   onChange: (text) => save(text),        // in the document's own line endings
   resolveImage: (src) => new URL(src, base).href,
+  openLink: (target) => open(target),     // { kind: 'web' | 'file' | 'image', url }
 });
 ```
 
@@ -19,6 +20,10 @@ const view = createEditor(document.getElementById('editor')!, {
   them with an IME is safe.
 - **Images** and `$$` math preview below their source; `$inline$` math in a tooltip. Math
   (`@simple-mark/math`) loads only when a document has math.
+- **Links**: Ctrl+Click (⌘+Click on macOS) follows a link — a plain click keeps placing the
+  cursor, since links are editable text. `#heading` links jump within the document; other
+  schemes than http(s)/mailto are refused; web pages and paths go to `openLink` (default: a
+  new browser tab). A click on an image preview opens the image.
 - **Line endings** are kept (`\r\n`, `\r`), so an unedited file saves back byte for byte.
 - Accurate scroll heights for documents with many images and formulas.
 - `simpleMark(theme)` gives the extensions for your own `EditorState`.

package/index.d.ts

@@ -1,11 +1,34 @@
 import { EditorState, Extension, Facet, StateCommand } from "@codemirror/state";
 import { DecorationSet, EditorView, ViewPlugin, ViewUpdate } from "@codemirror/view";
 import { LineLook, Theme } from "@simple-mark/model";
-//#region packages/codemirror/src/previews.d.ts
-/** Turns an image path as written in the document into a URL to load, or null if it can't. */
-type ImageResolver = (src: string) => string | null;
-/** How image paths are resolved; by default they are used as written. */
+//#region packages/codemirror/src/links.d.ts
+/** What to open: a web address, or a path as written (an image, another document, …). */
+interface LinkTarget {
+  kind: 'web' | 'file' | 'image';
+  url: string;
+}
+/** Opens a link target; hosts replace this with their own (see `createEditor`'s `openLink`). */
+type LinkOpener = (target: LinkTarget, view: EditorView) => void;
+/** How links are opened. */
+export declare const linkOpener: Facet<LinkOpener, LinkOpener>;
+/**
+ * Follows a link target as written (`isImage`: from `![alt](src)`). Returns false when there
+ * is nothing to open: no target, an unsafe scheme, or an anchor no heading has.
+ */
+export declare function followLink(view: EditorView, target: string | null, isImage?: boolean): boolean;
+/** Ctrl/Cmd+Click follows links; `#anchors` jump to headings. */
+export declare function links(): Extension;
+//#endregion
+//#region packages/codemirror/src/image-resolver.d.ts
+/**
+ * Turns a path as written in the document into a URL to load, or several to try in order
+ * (the first that loads is shown), or null if it can't be loaded.
+ */
+type ImageResolver = (src: string) => string | readonly string[] | null;
+/** How image (and file) paths are resolved; by default they are used as written. */
 export declare const imageResolver: Facet<ImageResolver, ImageResolver>;
+//#endregion
+//#region packages/codemirror/src/previews.d.ts
 /** Image and math previews; the source text always stays visible. */
 export declare function previews(): Extension;
 //#endregion
@@ -63,6 +86,11 @@ export interface EditorOptions {
   lineSeparator?: string;
   /** Turns an image path from the document into a URL to load (default: as written). */
   resolveImage?: ImageResolver;
+  /**
+   * Opens a followed link (Ctrl/Cmd+Click) or a clicked image preview. Default: web addresses
+   * and paths (resolved like images) in a new browser tab.
+   */
+  openLink?: LinkOpener;
   /** Off when the host owns undo (VS Code). */
   history?: boolean;
   /** Called after every change with the full text, in the original line endings. */
@@ -72,4 +100,4 @@ export interface EditorOptions {
 /** A Markdown editor in `parent`. The text is kept exactly as given, line endings included. */
 export declare function createEditor(parent: HTMLElement, options?: EditorOptions): EditorView;
 //#endregion
-export type { ImageResolver };
+export type { ImageResolver, LinkOpener, LinkTarget };

package/index.js

@@ -2,8 +2,115 @@ import { defaultKeymap, history, historyKeymap } from "@codemirror/commands";
 import { commonmarkLanguage, markdown } from "@codemirror/lang-markdown";
 import { EditorState, Facet, Prec, StateEffect, StateField } from "@codemirror/state";
 import { Decoration, EditorView, ViewPlugin, WidgetType, hoverTooltip, keymap, showTooltip } from "@codemirror/view";
-import { cellAt, charWidth, defaultTheme, markdownExtensions, markdownStyles, mathSource, parseTable, previewBlocks, renderTable, resolveLineLook, resolveLook, rowLine } from "@simple-mark/model";
+import { cellAt, charWidth, defaultTheme, headingAnchors, linkAt, linkKind, markdownExtensions, markdownStyles, mathSource, parseTable, previewBlocks, renderTable, resolveLineLook, resolveLook, rowLine } from "@simple-mark/model";
 import { ensureSyntaxTree, syntaxTree } from "@codemirror/language";
+//#region packages/codemirror/src/image-resolver.ts
+/** The URLs a resolver gives for `src`, in order. */
+function resolvedUrls(resolve, src) {
+	const result = resolve(src);
+	return result === null ? [] : typeof result === "string" ? [result] : [...result];
+}
+/** How image (and file) paths are resolved; by default they are used as written. */
+const imageResolver = Facet.define({ combine: (values) => values[0] ?? ((src) => src) });
+//#endregion
+//#region packages/codemirror/src/links.ts
+/** In a browser: web addresses and paths (resolved like images) open in a new tab. */
+const openInBrowser = (target, view) => {
+	const url = target.kind === "web" ? target.url : resolvedUrls(view.state.facet(imageResolver), target.url)[0];
+	if (url) window.open(url, "_blank", "noopener,noreferrer");
+};
+/** How links are opened. */
+const linkOpener = Facet.define({ combine: (values) => values[0] ?? openInBrowser });
+const isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
+/** The key held to follow a link: Cmd on macOS, Ctrl elsewhere. */
+const followKeyName = isMac ? "⌘" : "Ctrl";
+const followKey = (event) => isMac ? event.metaKey : event.ctrlKey;
+/**
+* Follows a link target as written (`isImage`: from `![alt](src)`). Returns false when there
+* is nothing to open: no target, an unsafe scheme, or an anchor no heading has.
+*/
+function followLink(view, target, isImage = false) {
+	if (target === null) return false;
+	const { kind, url } = linkKind(target);
+	if (kind === "unsafe") return false;
+	if (kind === "anchor") {
+		const wanted = decodeURIComponent(url.slice(1)).toLowerCase();
+		const heading = headingAnchors(syntaxTree(view.state), view.state.doc.toString()).find((h) => h.anchor === wanted);
+		if (!heading) return false;
+		view.dispatch({
+			selection: { anchor: heading.from },
+			effects: EditorView.scrollIntoView(heading.from, {
+				y: "start",
+				yMargin: 24
+			})
+		});
+		view.focus();
+		return true;
+	}
+	view.state.facet(linkOpener)({
+		kind: kind === "file" && isImage ? "image" : kind,
+		url
+	}, view);
+	return true;
+}
+/** Ctrl/Cmd+Click on a link follows it (instead of adding a cursor there). */
+const clickToFollow = EditorView.domEventHandlers({ mousedown(event, view) {
+	if (event.button !== 0 || !followKey(event) || event.shiftKey || event.altKey) return false;
+	if (!(event.target instanceof Element) || !event.target.closest(".sm-link, .sm-url")) return false;
+	const pos = view.posAtCoords({
+		x: event.clientX,
+		y: event.clientY
+	});
+	if (pos === null) return false;
+	const link = linkAt(syntaxTree(view.state), view.state.doc.toString(), pos);
+	if (!link) return false;
+	event.preventDefault();
+	followLink(view, link.target, link.kind === "image");
+	return true;
+} });
+/** While Ctrl/Cmd is held, links look clickable (pointer, underline). */
+const followKeyHint = ViewPlugin.fromClass(class {
+	view;
+	constructor(view) {
+		this.view = view;
+		for (const type of [
+			"keydown",
+			"keyup",
+			"mousemove"
+		]) window.addEventListener(type, this.track, true);
+		window.addEventListener("blur", this.clear);
+	}
+	destroy() {
+		for (const type of [
+			"keydown",
+			"keyup",
+			"mousemove"
+		]) window.removeEventListener(type, this.track, true);
+		window.removeEventListener("blur", this.clear);
+	}
+	track = (event) => {
+		this.view.dom.classList.toggle("sm-follow-links", followKey(event));
+	};
+	clear = () => {
+		this.view.dom.classList.remove("sm-follow-links");
+	};
+});
+const followTheme = EditorView.theme({
+	"&.sm-follow-links .sm-link, &.sm-follow-links .sm-url": {
+		cursor: "pointer",
+		textDecoration: "underline"
+	},
+	".sm-image-preview img": { cursor: "pointer" }
+});
+/** Ctrl/Cmd+Click follows links; `#anchors` jump to headings. */
+function links() {
+	return [
+		clickToFollow,
+		followKeyHint,
+		followTheme
+	];
+}
+//#endregion
 //#region packages/codemirror/src/decorations.ts
 /** The theme the editor draws with. */
 const markdownTheme = Facet.define({ combine: (values) => values[0] ?? defaultTheme });
@@ -21,7 +128,7 @@ function lookCss(look, theme) {
 		css.push(`text-decoration: ${lines.join(" ") || "none"}`);
 	}
 	if (look.lineBackground !== void 0) css.push(`background-color: ${look.lineBackground}`);
-	if (look.borderLeft !== void 0) css.push(`box-shadow: inset 3px 0 0 ${look.borderLeft}`, "padding-left: 12px");
+	if (look.borderLeft !== void 0) css.push(`box-shadow: inset ${3 / 15}em 0 0 ${look.borderLeft}`, `padding-left: ${12 / 15}em`);
 	return css.join("; ");
 }
 const fontChecks = /* @__PURE__ */ new Map();
@@ -144,9 +251,13 @@ var MarkdownDecorations = class {
 		const key = `mark:${styles.join(" ")}`;
 		let deco = this.cache.get(key);
 		if (!deco) {
+			const linked = styles.includes("link") || styles.includes("url");
 			deco = Decoration.mark({
 				class: styles.map((s) => `sm-${s}`).join(" "),
-				attributes: { style: lookCss(resolveLook([], styles, this.theme), this.theme) }
+				attributes: {
+					style: lookCss(resolveLook([], styles, this.theme), this.theme),
+					...linked ? { title: `${followKeyName}+Click to open` } : {}
+				}
 			});
 			this.cache.set(key, deco);
 		}
@@ -178,8 +289,26 @@ function loadMath() {
 function loadedMath() {
 	return loaded;
 }
-/** Gap between images on one line (CSS gap). */
-const IMAGE_GAP = 8;
+//#endregion
+//#region packages/codemirror/src/preview-heights.ts
+/**
+* Preview sizes in em of the editor's font: at 15px, 4px above and 8px below a preview, images
+* at most 320px tall and 8px apart. The same numbers as @simple-mark/canvas, so a canvas and the
+* editor agree at any font size (a canvas text may be 48 units tall).
+*/
+const PREVIEW_EM = {
+	top: 4 / 15,
+	bottom: 8 / 15,
+	imageMaxHeight: 320 / 15,
+	imageGap: 8 / 15,
+	radius: 4 / 15
+};
+/** Vertical padding of a preview in pixels, at the editor's font size. */
+function previewPadding() {
+	return (PREVIEW_EM.top + PREVIEW_EM.bottom) * layout.fontSize;
+}
+const imageMaxHeight = () => PREVIEW_EM.imageMaxHeight * layout.fontSize;
+const imageGap = () => PREVIEW_EM.imageGap * layout.fontSize;
 /** Editor facts the estimates depend on, measured by `previewLayout`. */
 const layout = {
 	contentWidth: 700,
@@ -264,7 +393,7 @@ function whenImageSized(src, then) {
 /** Gives an <img> its final layout size before its pixels arrive (CSS caps it at the width). */
 function reserveImageBox(img, size) {
 	img.style.aspectRatio = `${size.width} / ${size.height}`;
-	img.style.width = `${Math.min(size.width, 320 * size.width / size.height)}px`;
+	img.style.width = `${Math.min(size.width, imageMaxHeight() * size.width / size.height)}px`;
 }
 function probeImage(src) {
 	if (probing.has(src) || imageSizes.has(src) || typeof Image === "undefined") return;
@@ -273,7 +402,7 @@ function probeImage(src) {
 	watchImage(img, src);
 	img.src = src;
 }
-/** Displayed size of one image: fits the width, at most IMAGE_MAX_HEIGHT tall, never enlarged. */
+/** Displayed size of one image: fits the width, at most `imageMaxHeight` tall, never enlarged. */
 function imageBox(src) {
 	const errorLine = {
 		width: layout.contentWidth,
@@ -285,11 +414,11 @@ function imageBox(src) {
 		probeImage(src);
 		return {
 			width: layout.contentWidth,
-			height: 160
+			height: imageMaxHeight() / 2
 		};
 	}
 	if (size === null) return errorLine;
-	const scale = Math.min(1, layout.contentWidth / size.width, 320 / size.height);
+	const scale = Math.min(1, layout.contentWidth / size.width, imageMaxHeight() / size.height);
 	return {
 		width: size.width * scale,
 		height: size.height * scale
@@ -304,15 +433,15 @@ function imagesEstimate(key, srcs) {
 	let rowHeight = 0;
 	for (const src of srcs) {
 		const box = imageBox(src);
-		if (rowWidth > 0 && rowWidth + IMAGE_GAP + box.width > layout.contentWidth) {
-			total += rowHeight + IMAGE_GAP;
+		if (rowWidth > 0 && rowWidth + imageGap() + box.width > layout.contentWidth) {
+			total += rowHeight + imageGap();
 			rowWidth = 0;
 			rowHeight = 0;
 		}
-		rowWidth += (rowWidth > 0 ? IMAGE_GAP : 0) + box.width;
+		rowWidth += (rowWidth > 0 ? imageGap() : 0) + box.width;
 		rowHeight = Math.max(rowHeight, box.height);
 	}
-	return Math.round(total + rowHeight + 12);
+	return Math.round(total + rowHeight + previewPadding());
 }
 /** Renders queued formulas one at a time, so their heights are known before they are shown. */
 function renderQueuedMath() {
@@ -338,13 +467,13 @@ function mathEstimate(key, tex) {
 	const result = loadedMath()?.cachedMath(tex, true);
 	if (result?.svg !== void 0) {
 		const height = /height="([\d.]+)ex"/.exec(result.svg);
-		if (height) return Math.round(parseFloat(height[1]) * layout.exPx + 12);
-	} else if (result?.error !== void 0) return layout.lineHeight + 12;
+		if (height) return Math.round(parseFloat(height[1]) * layout.exPx + previewPadding());
+	} else if (result?.error !== void 0) return layout.lineHeight + previewPadding();
 	else {
 		mathQueue.add(tex);
 		renderQueuedMath();
 	}
-	return 3 * layout.lineHeight + 12;
+	return 3 * layout.lineHeight + previewPadding();
 }
 /** Measures the editor (content width, x-height, line height) and refreshes previews on news. */
 const previewLayout = ViewPlugin.fromClass(class {
@@ -497,8 +626,6 @@ function lineHeightHints() {
 }
 //#endregion
 //#region packages/codemirror/src/previews.ts
-/** How image paths are resolved; by default they are used as written. */
-const imageResolver = Facet.define({ combine: (values) => values[0] ?? ((src) => src) });
 /** Fills `dom` with rendered math now if known, otherwise when it is ready. */
 function renderInto(dom, tex, display, onDone) {
 	const show = (result) => {
@@ -540,7 +667,7 @@ var MathBlockWidget = class extends WidgetType {
 		const dom = document.createElement("div");
 		dom.className = "sm-math-preview";
 		dom.dataset["key"] = this.key;
-		dom.style.minHeight = `${this.estimate - 12}px`;
+		dom.style.minHeight = `${this.estimate - previewPadding()}px`;
 		renderInto(dom, this.tex, true, () => {
 			dom.style.minHeight = "";
 			view.requestMeasure();
@@ -557,15 +684,17 @@ function imageRef(image, resolve) {
 		alt: image.alt,
 		problem: `No definition for ${image.raw}`
 	};
-	const src = resolve(image.src);
-	return src === null ? {
+	const [src, ...fallbacks] = resolvedUrls(resolve, image.src);
+	if (src === void 0) return {
 		raw: image.raw,
-		src,
+		src: null,
 		alt: image.alt,
 		problem: `Can't load ${image.raw}`
-	} : {
+	};
+	return {
 		raw: image.raw,
 		src,
+		...fallbacks.length ? { fallbacks } : {},
 		alt: image.alt
 	};
 }
@@ -626,14 +755,22 @@ var ImageWidget = class extends WidgetType {
 			img.decoding = "async";
 			img.src = image.src;
 			img.alt = image.alt;
-			img.title = image.raw;
+			img.title = `${image.raw} (click to open)`;
+			img.addEventListener("click", () => followLink(view, image.raw, true));
 			img.onload = settled;
+			const fallbacks = [...image.fallbacks ?? []];
 			img.onerror = () => {
+				const next = fallbacks.shift();
+				if (next !== void 0) {
+					watchImage(img, next);
+					img.src = next;
+					return;
+				}
 				img.replaceWith(problem(`Image not found: ${image.raw}`));
 				settled();
 			};
 		}
-		if (unsized > 0) dom.style.minHeight = `${this.estimate - 12}px`;
+		if (unsized > 0) dom.style.minHeight = `${this.estimate - previewPadding()}px`;
 		if (waiting === 0) rememberHeight(view, this.key, dom);
 		return dom;
 	}
@@ -704,17 +841,20 @@ const hoverMathTooltip = hoverTooltip((view, pos) => {
 	const tooltip = mathTooltip(view.state, pos);
 	return tooltip && cursor?.pos === tooltip.pos ? null : tooltip;
 });
+const em = (value) => `${value}em`;
+const previewSpacing = `${em(PREVIEW_EM.top)} 0 ${em(PREVIEW_EM.bottom)}`;
+/** Sizes in em (see PREVIEW_EM), so previews scale with the text like on a canvas. */
 const previewTheme = EditorView.theme({
 	".sm-image-preview": {
 		display: "flex",
 		flexWrap: "wrap",
-		gap: "8px",
-		padding: "4px 0 8px"
+		gap: em(PREVIEW_EM.imageGap),
+		padding: previewSpacing
 	},
 	".sm-image-preview img": {
 		maxWidth: "100%",
-		maxHeight: "320px",
-		borderRadius: "4px"
+		maxHeight: em(PREVIEW_EM.imageMaxHeight),
+		borderRadius: em(PREVIEW_EM.radius)
 	},
 	".sm-image-error, .sm-math-error": {
 		color: "#cf222e",
@@ -722,7 +862,7 @@ const previewTheme = EditorView.theme({
 	},
 	".sm-math-preview": {
 		textAlign: "center",
-		padding: "4px 0 8px",
+		padding: previewSpacing,
 		overflowX: "auto",
 		overflowY: "hidden"
 	},
@@ -965,6 +1105,7 @@ function simpleMark(theme = defaultTheme) {
 		markdownTheme.of(theme),
 		markdownDecorations,
 		previews(),
+		links(),
 		EditorView.theme({
 			"&": { color: theme.color },
 			".cm-scroller": {
@@ -976,7 +1117,7 @@ function simpleMark(theme = defaultTheme) {
 }
 /** A Markdown editor in `parent`. The text is kept exactly as given, line endings included. */
 function createEditor(parent, options = {}) {
-	const { doc = "", readOnly = false, theme = defaultTheme, resolveImage, onChange, extensions = [] } = options;
+	const { doc = "", readOnly = false, theme = defaultTheme, resolveImage, openLink, onChange, extensions = [] } = options;
 	const useHistory = options.history ?? true;
 	return new EditorView({
 		parent,
@@ -989,6 +1130,7 @@ function createEditor(parent, options = {}) {
 				EditorView.lineWrapping,
 				simpleMark(theme),
 				resolveImage ? imageResolver.of(resolveImage) : [],
+				openLink ? linkOpener.of(openLink) : [],
 				EditorState.readOnly.of(readOnly),
 				EditorView.editable.of(!readOnly),
 				onChange ? EditorView.updateListener.of((update) => update.docChanged && onChange(update.state.sliceDoc(), update)) : [],
@@ -998,4 +1140,4 @@ function createEditor(parent, options = {}) {
 	});
 }
 //#endregion
-export { createEditor, imageResolver, insertRowBelow, keepLineSeparator, lookCss, markdownDecorations, markdownTheme, nextCell, previews, previousCell, simpleMark, tableEditing };
+export { createEditor, followLink, imageResolver, insertRowBelow, keepLineSeparator, linkOpener, links, lookCss, markdownDecorations, markdownTheme, nextCell, previews, previousCell, simpleMark, tableEditing };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simple-mark/codemirror",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "CodeMirror 6 editor that styles Markdown without hiding its syntax.",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,7 @@
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.15",
     "@lezer/common": "^1.5.3",
-    "@simple-mark/math": "^0.2.0",
-    "@simple-mark/model": "^0.2.0"
+    "@simple-mark/math": "^0.3.1",
+    "@simple-mark/model": "^0.3.1"
   }
 }