components/markdown-editor/markdown-editor-edits.ts

Functions

Imports

It imports no other module of this repo. Imported by components/markdown-editor/markdown-editor.ts.

Source

1// The markdown editor's types and pure helpers: the edits each command makes, counted and checked without a page (markdown-editor.ts).
2
3// ---- types ---------------------------------------------------------------------------------
4
5// One edit to the document, in the document's own positions (every change refers to the text
6// as it was before any of them), and where the cursor goes after.
7export interface Edit {
8  changes: Array<{ from: number; to?: number; insert: string }>;
9  anchor: number;
10  head?: number;
11}
12
13// A page the link palette can offer: the app decides the address and the words. `note` is
14// said in words beside the title ("not live yet (draft)"), never colour alone.
15export interface LinkTarget {
16  href: string;
17  title: string;
18  hint?: string;
19  note?: string;
20}
21
22// A block the slash menu and the toolbar insert. The app supplies them; the editor knows no
23// block syntax of its own. `cursor` is where the cursor lands, as an offset into `text`;
24// `cursorAfter` finds that offset from the first place the given text occurs. `icon` is the
25// `d` of one 24 by 24 SVG path for the toolbar button; without it the button shows the
26// label's first letter.
27export interface Scaffold {
28  id: string;
29  label: string;
30  hint: string;
31  text: string;
32  cursor?: number;
33  cursorAfter?: string;
34  icon?: string;
35}
36
37export interface UploadResult {
38  url: string;
39}
40
41export interface MarkdownEditorOptions {
42  // The name of the editable surface; defaults to the label's text plus ", markdown".
43  label?: string;
44  // Each of these defaults to the textarea's own attribute (placeholder, readonly, disabled,
45  // maxlength), which is also watched, so an app can change either.
46  placeholder?: string;
47  readOnly?: boolean;
48  disabled?: boolean;
49  maxLength?: number;
50  lineNumbers?: boolean;
51  scaffolds?: Scaffold[];
52  // Pages to offer, or a function that searches them (it may be async; the newest answer wins).
53  linkTargets?: LinkTarget[] | ((query: string) => LinkTarget[] | Promise<LinkTarget[]>);
54  // Uploads a pasted, dropped or chosen image and says where it went. Without it, the image
55  // button, the drop hint and the alt prompt are absent.
56  onUpload?: (file: File) => Promise<UploadResult>;
57  // The markdown that goes into the text once the image has its alt text.
58  imageMarkdown?: (image: { url: string; alt: string; name: string }) => string;
59  // The file chooser's accept list.
60  accept?: string;
61  onChange?: (value: string) => void;
62  // Ctrl or Cmd + S. The key is always claimed (the browser's save-page is no use here); the
63  // page's own handler on window still sees it.
64  onSave?: (value: string) => void;
65  // The CSP nonce for the styles CodeMirror injects. Defaults to the nonce on the page's first
66  // script that has one.
67  nonce?: string;
68  wordsPerMinute?: number;
69}
70
71export interface MarkdownEditorHandle {
72  readonly root: HTMLElement;
73  getValue(): string;
74  // Replaces the text. It does not call onChange: the app is the one setting it.
75  setValue(value: string): void;
76  // Focuses the surface; "end" also puts the cursor after the last character.
77  focus(at?: "start" | "end"): void;
78  update(patch: Partial<MarkdownEditorOptions>): void;
79  destroy(): void;
80}
81
82// ---- pure helpers --------------------------------------------------------------------------
83
84export const LINK_RESULT_LIMIT = 8;
85const DEFAULT_WORDS_PER_MINUTE = 200;
86
87// Markdown syntax counts as words on purpose: it is the count the site's published reading
88// times were built with.
89export function countWords(text: string): number {
90  return text.trim().split(/\s+/).filter(Boolean).length;
91}
92
93export function minutesForWords(words: number, wordsPerMinute = DEFAULT_WORDS_PER_MINUTE): number {
94  return Math.max(1, Math.round(words / wordsPerMinute));
95}
96
97export function looksLikeUrl(text: string): boolean {
98  return /^(https?:\/\/|mailto:|\/|#)/i.test(text.trim());
99}
100
101// The targets whose title, address or hint holds the query; all of them for an empty query.
102// A typed address matches nothing: it is committed as itself.
103export function filterLinkTargets(targets: LinkTarget[], query: string, limit = LINK_RESULT_LIMIT): LinkTarget[] {
104  const needle = query.trim().toLowerCase();
105  if (looksLikeUrl(needle)) return [];
106  const pool = needle
107    ? targets.filter((t) => [t.title, t.href, t.hint ?? ""].some((s) => s.toLowerCase().includes(needle)))
108    : targets;
109  return pool.slice(0, limit);
110}
111
112// Which item an arrow, Home or End moves to in a roving group (APG toolbar and menu). It wraps.
113export function rovingIndex(key: string, at: number, count: number, axis: "horizontal" | "vertical" = "horizontal"): number | null {
114  if (count <= 0) return null;
115  const next = axis === "horizontal" ? "ArrowRight" : "ArrowDown";
116  const prev = axis === "horizontal" ? "ArrowLeft" : "ArrowUp";
117  if (key === next) return (at + 1) % count;
118  if (key === prev) return (at - 1 + count) % count;
119  if (key === "Home") return 0;
120  if (key === "End") return count - 1;
121  return null;
122}
123
124// The start and end of the line holding `pos`.
125export function lineBounds(doc: string, pos: number): { from: number; to: number } {
126  const from = doc.lastIndexOf("\n", pos - 1) + 1;
127  const nl = doc.indexOf("\n", pos);
128  return { from, to: nl === -1 ? doc.length : nl };
129}
130
131// Marks around the selection; with none selected, the cursor lands between the marks.
132export function wrapEdit(doc: string, from: number, to: number, before: string, after = before): Edit {
133  const selected = doc.slice(from, to);
134  return {
135    changes: [{ from, to, insert: `${before}${selected}${after}` }],
136    anchor: from + before.length,
137    head: selected ? from + before.length + selected.length : undefined,
138  };
139}
140
141// Cycles the line's heading: none, h2, h3, h4, none.
142export function headingEdit(doc: string, head: number): Edit {
143  const { from, to } = lineBounds(doc, head);
144  const line = doc.slice(from, to);
145  const match = /^(#{1,6})\s+/.exec(line);
146  const n = match?.[1]?.length ?? 0;
147  const next = n === 0 ? "## " : n === 1 ? "## " : n >= 4 ? "" : `${"#".repeat(n + 1)} `;
148  const stripped = match ? match[0].length : 0;
149  return {
150    changes: [{ from, to: from + stripped, insert: next }],
151    anchor: Math.max(from + next.length, head - stripped + next.length),
152  };
153}
154
155// A numbered reference at the selection and its definition at the end, with the cursor in the
156// definition, the part still to write. The number is one past the highest in the text (the
157// site counted every match, so its second footnote was numbered 3).
158export function footnoteEdit(doc: string, from: number, to: number): Edit {
159  const used = [...doc.matchAll(/\[\^(\d+)\]/g)].map((m) => Number(m[1]));
160  const n = (used.length ? Math.max(...used) : 0) + 1;
161  const ref = `[^${n}]`;
162  const def = `\n\n${ref}: `;
163  return {
164    changes: [
165      { from, to, insert: ref },
166      { from: doc.length, insert: def },
167    ],
168    // After both changes: the reference lengthens the text before the definition.
169    anchor: doc.length - (to - from) + ref.length + def.length,
170  };
171}
172
173// A block of text at the cursor, set apart by a blank line before it unless the cursor is on
174// one, and after it when text follows on the same line.
175export function blockEdit(doc: string, from: number, to: number, text: string, cursor?: number): Edit {
176  const line = lineBounds(doc, from);
177  const onBlank = line.from === from && doc.slice(line.from, line.to).trim() === "";
178  const prefix = onBlank ? "" : "\n\n";
179  const next = doc.charAt(to);
180  const suffix = next !== "" && next !== "\n" ? "\n\n" : "";
181  return {
182    changes: [{ from, to, insert: `${prefix}${text}${suffix}` }],
183    anchor: from + prefix.length + (cursor ?? text.length),
184  };
185}
186
187// The slash line becomes the block, in its place.
188export function slashBlockEdit(lineFrom: number, lineTo: number, text: string, cursor?: number): Edit {
189  return { changes: [{ from: lineFrom, to: lineTo, insert: text }], anchor: lineFrom + (cursor ?? text.length) };
190}
191
192export function scaffoldCursor(s: Scaffold): number | undefined {
193  if (s.cursorAfter) {
194    const at = s.text.indexOf(s.cursorAfter);
195    if (at >= 0) return at + s.cursorAfter.length;
196  }
197  return s.cursor;
198}
199
200// A link at the selection, the cursor after it: the next keystroke is almost always the
201// sentence going on.
202export function linkEdit(from: number, to: number, selected: string, href: string, fallbackLabel: string): Edit {
203  const markdown = `[${selected || fallbackLabel || href}](${href})`;
204  return { changes: [{ from, to, insert: markdown }], anchor: from + markdown.length };
205}
206
207// The markdown for an image when the app does not say: alt text with its brackets made safe.
208export function defaultImageMarkdown({ url, alt }: { url: string; alt: string }): string {
209  return `![${alt.replace(/[[\]\n]/g, " ").replace(/\s+/g, " ").trim()}](${url})`;
210}