@simple-mark/codemirror 0.2.0 → 0.3.0

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 });
@@ -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);
 		}
@@ -497,8 +608,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) => {
@@ -557,15 +666,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,9 +737,17 @@ 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();
 			};
@@ -965,6 +1084,7 @@ function simpleMark(theme = defaultTheme) {
 		markdownTheme.of(theme),
 		markdownDecorations,
 		previews(),
+		links(),
 		EditorView.theme({
 			"&": { color: theme.color },
 			".cm-scroller": {
@@ -976,7 +1096,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 +1109,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 +1119,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.0",
   "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.0",
+    "@simple-mark/model": "^0.3.0"
   }
 }