nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/MarkdownEditing.js

@@ -0,0 +1,250 @@
+/*
+ * Editing commands for Markdown text: the toolbar buttons and shortcuts of MarkdownEditor, list continuation on Enter,
+ * ticking a task, and turning a pasted URL into a link. Each takes the text and the selection and returns a single
+ * replacement, with no DOM, so a custom editor or a test can use them as well.
+ */
+/** A starter table: three columns, a header, and one row. */
+export const MARKDOWN_TABLE = "| Column | Column | Column |\n| --- | --- | --- |\n| Text | Text | Text |";
+/**
+ * The edit for a toolbar button. Inline marks (bold, italic, strikethrough, code) wrap the selection or the word at the
+ * caret, or remove the marks when they are already there. Line marks (quote, lists) apply to every selected line and
+ * come off when every line has them. Blocks (table, horizontal line) go on their own lines after the selection.
+ */
+export function applyMarkdownTool(value, selectionStart, selectionEnd, tool) {
+    const start = Math.min(selectionStart, selectionEnd);
+    const end = Math.max(selectionStart, selectionEnd);
+    switch (tool) {
+        case "bold":
+            return toggleWrap(value, start, end, "**", "bold text");
+        case "italic":
+            return toggleWrap(value, start, end, "_", "italic text");
+        case "strikethrough":
+            return toggleWrap(value, start, end, "~~", "text");
+        case "code":
+            return value.slice(start, end).includes("\n") ? toggleCodeBlock(value, start, end) : toggleWrap(value, start, end, "`", "code");
+        case "link":
+        case "image":
+            return insertLink(value, start, end, tool === "image");
+        case "heading":
+            return cycleHeading(value, start, end);
+        case "quote":
+        case "bulletList":
+        case "numberedList":
+        case "taskList":
+            return toggleLinePrefix(value, start, end, tool);
+        case "codeBlock":
+            return toggleCodeBlock(value, start, end);
+        case "table":
+            // Selects the first header, ready to type over.
+            return insertBlock(value, start, end, MARKDOWN_TABLE, [2, 8]);
+        case "rule":
+            return insertBlock(value, start, end, "---");
+    }
+}
+/**
+ * The edit for Enter at the end of a list item: a new item with the same indent and marker, the next number, and an
+ * empty box for a task. Enter on an empty item ends the list instead. `null` when Enter should just break the line.
+ */
+export function continueMarkdownList(value, selectionStart, selectionEnd) {
+    if (selectionStart !== selectionEnd)
+        return null;
+    const from = lineStartAt(value, selectionStart);
+    const to = lineEndAt(value, selectionStart);
+    const line = value.slice(from, to);
+    const match = /^([ \t]*)(?:([-+*])|(\d{1,9})([.)]))([ \t]+)(\[[ xX]\](?:[ \t]+|$))?/.exec(line);
+    if (!match || RULE.test(line) || selectionStart - from < match[0].length)
+        return null;
+    if (!line.slice(match[0].length).trim()) {
+        return { start: from, end: to, text: "", selectionStart: from, selectionEnd: from };
+    }
+    const [, indent = "", bullet, number, delimiter = ".", space = " ", task] = match;
+    const text = `\n${indent}${bullet ?? `${Number(number) + 1}${delimiter}`}${space}${task ? "[ ] " : ""}`;
+    return { start: selectionStart, end: selectionStart, text, selectionStart: selectionStart + text.length, selectionEnd: selectionStart + text.length };
+}
+/** The edit that ticks or clears the task whose marker is on `line` (from 0), as `MarkdownListItem.line` gives it. */
+export function toggleMarkdownTask(value, line, checked) {
+    let from = 0;
+    for (let n = 0; n < line; n++) {
+        const next = value.indexOf("\n", from);
+        if (next < 0)
+            return null;
+        from = next + 1;
+    }
+    const match = /^((?:[ \t]*>)*[ \t]*(?:[-+*]|\d{1,9}[.)])[ \t]+\[)[ xX]\]/.exec(value.slice(from, lineEndAt(value, from)));
+    if (!match)
+        return null;
+    const at = from + match[1].length;
+    return { start: at, end: at + 1, text: checked ? "x" : " " };
+}
+/** The edit that turns selected text into a link when a URL is pasted over it. `null` for any other paste. */
+export function linkPastedUrl(value, selectionStart, selectionEnd, pasted) {
+    const url = pasted.trim();
+    const selected = value.slice(selectionStart, selectionEnd);
+    if (!selected.trim() || selected.includes("\n") || !/^https?:\/\/\S+$/.test(url) || /^\s*(?:https?:\/\/|www\.)/.test(selected))
+        return null;
+    const text = `[${selected}](${url})`;
+    return { start: selectionStart, end: selectionEnd, text, selectionStart: selectionStart + text.length, selectionEnd: selectionStart + text.length };
+}
+const RULE = /^ {0,3}(?:(?:\*[ \t]*){3,}|(?:-[ \t]*){3,}|(?:_[ \t]*){3,})$/;
+const WORD = /[\p{L}\p{N}\p{M}]/u;
+const LINE_PREFIX = {
+    quote: /^([ \t]*)> ?/,
+    bulletList: /^([ \t]*)[-+*][ \t]+(?!\[[ xX]\](?:[ \t]|$))/,
+    numberedList: /^([ \t]*)\d{1,9}[.)][ \t]+/,
+    taskList: /^([ \t]*)[-+*][ \t]+\[[ xX]\](?:[ \t]+|$)/,
+};
+const ANY_LIST_PREFIX = /^([ \t]*)(?:[-+*]|\d{1,9}[.)])[ \t]+(?:\[[ xX]\](?:[ \t]+|$))?/;
+function toggleWrap(value, start, end, marker, placeholder) {
+    const size = marker.length;
+    const selected = value.slice(start, end);
+    // The marks sit just outside the selection, or the selection includes them: take them off.
+    if (start >= size && value.slice(start - size, start) === marker && value.slice(end, end + size) === marker) {
+        return { start: start - size, end: end + size, text: selected, selectionStart: start - size, selectionEnd: end - size };
+    }
+    if (selected.length >= 2 * size && selected.startsWith(marker) && selected.endsWith(marker)) {
+        const inner = selected.slice(size, -size);
+        return { start, end, text: inner, selectionStart: start, selectionEnd: start + inner.length };
+    }
+    if (!selected.trim()) {
+        // A caret inside a word marks the word; anywhere else, a placeholder to type over.
+        const word = start === end ? wordAround(value, start) : null;
+        if (word) {
+            const text = marker + value.slice(word.start, word.end) + marker;
+            return { start: word.start, end: word.end, text, selectionStart: start + size, selectionEnd: start + size };
+        }
+        return { start: end, end, text: marker + placeholder + marker, selectionStart: end + size, selectionEnd: end + size + placeholder.length };
+    }
+    // Marks cannot span lines, so each line gets its own. Spaces at the edges stay outside them.
+    const text = selected
+        .split("\n")
+        .map(line => {
+        const core = line.trim();
+        if (!core)
+            return line;
+        const lead = line.indexOf(core);
+        return line.slice(0, lead) + marker + core + marker + line.slice(lead + core.length);
+    })
+        .join("\n");
+    if (selected.includes("\n"))
+        return { start, end, text, selectionStart: start, selectionEnd: start + text.length };
+    const lead = selected.indexOf(selected.trim());
+    return { start, end, text, selectionStart: start + lead + size, selectionEnd: start + lead + size + selected.trim().length };
+}
+function toggleLinePrefix(value, start, end, tool) {
+    const { from, to, lines } = selectedLines(value, start, end);
+    const pattern = LINE_PREFIX[tool];
+    const filled = lines.filter(line => line.trim());
+    const remove = filled.length > 0 && filled.every(line => pattern.test(line));
+    let number = 0;
+    const prefixLengths = [];
+    const next = lines.map(line => {
+        if (!line.trim() && lines.length > 1) {
+            prefixLengths.push(0);
+            return line;
+        }
+        // A list replaces any other list marker on the line, so a bulleted list becomes a numbered one in one click.
+        const current = remove ? pattern.exec(line) : tool === "quote" ? null : ANY_LIST_PREFIX.exec(line);
+        const indent = current?.[1] ?? (tool === "quote" ? "" : /^[ \t]*/.exec(line)[0]);
+        number++;
+        const marker = remove ? "" : tool === "quote" ? "> " : tool === "numberedList" ? `${number}. ` : tool === "taskList" ? "- [ ] " : "- ";
+        prefixLengths.push(current?.[0].length ?? indent.length);
+        return indent + marker + line.slice(current?.[0].length ?? indent.length);
+    });
+    const text = next.join("\n");
+    if (start === end && lines.length === 1) {
+        // The caret keeps its place in the line's text.
+        const oldPrefix = prefixLengths[0];
+        const newPrefix = text.length - (lines[0].length - oldPrefix);
+        const caret = from + newPrefix + Math.max(0, start - from - oldPrefix);
+        return { start: from, end: to, text, selectionStart: caret, selectionEnd: caret };
+    }
+    return { start: from, end: to, text, selectionStart: from, selectionEnd: from + text.length };
+}
+/** No heading, then #, ##, ###, and back to none: one button for the three sizes a page usually needs. */
+function cycleHeading(value, start, end) {
+    const from = lineStartAt(value, start);
+    const to = lineEndAt(value, start);
+    const line = value.slice(from, to);
+    const match = /^ {0,3}(#{1,6})(?:[ \t]+|$)/.exec(line);
+    const level = match ? match[1].length : 0;
+    const prefix = level >= 3 ? "" : `${"#".repeat(level + 1)} `;
+    const text = prefix + line.slice(match ? match[0].length : 0);
+    const shift = text.length - line.length;
+    const selectionStart = Math.max(from + prefix.length, start + shift);
+    return { start: from, end: to, text, selectionStart, selectionEnd: Math.max(selectionStart, end + shift) };
+}
+function toggleCodeBlock(value, start, end) {
+    const { from, to, lines } = selectedLines(value, start, end);
+    // Fences right above and below the lines: take them off.
+    if (from > 0 && to < value.length) {
+        const aboveFrom = lineStartAt(value, from - 1);
+        const belowTo = lineEndAt(value, to + 1);
+        if (/^ {0,3}(?:```|~~~)/.test(value.slice(aboveFrom, from - 1)) && /^ {0,3}(?:```|~~~)[ \t]*$/.test(value.slice(to + 1, belowTo))) {
+            const inner = value.slice(from, to);
+            return { start: aboveFrom, end: belowTo, text: inner, selectionStart: aboveFrom, selectionEnd: aboveFrom + inner.length };
+        }
+    }
+    const inner = lines.join("\n");
+    const text = `\`\`\`\n${inner}\n\`\`\``;
+    return { start: from, end: to, text, selectionStart: from + 4, selectionEnd: from + 4 + (inner.trim() ? inner.length : 0) };
+}
+function insertLink(value, start, end, image) {
+    const open = image ? "![" : "[";
+    const placeholder = image ? "description" : "link text";
+    const selected = value.slice(start, end);
+    // A selected URL becomes the address; select the text to type over.
+    if (/^(?:https?:\/\/|www\.)\S+$/.test(selected.trim())) {
+        const text = `${open}${placeholder}](${selected.trim()})`;
+        return { start, end, text, selectionStart: start + open.length, selectionEnd: start + open.length + placeholder.length };
+    }
+    // Selected text becomes the link's text; select the address to paste over.
+    if (selected.trim() && !selected.includes("\n")) {
+        const text = `${open}${selected}](https://)`;
+        const address = start + open.length + selected.length + 2;
+        return { start, end, text, selectionStart: address, selectionEnd: address + "https://".length };
+    }
+    const text = `${open}${placeholder}](https://)`;
+    return { start: end, end, text, selectionStart: end + open.length, selectionEnd: end + open.length + placeholder.length };
+}
+/**
+ * Puts a block on its own lines: in place of an empty line, or after the selected lines. Blank lines keep it apart
+ * from the text around it; without one, a line of dashes under text would make that text a heading.
+ */
+function insertBlock(value, start, end, block, select) {
+    const from = lineStartAt(value, start);
+    const to = lineEndAt(value, Math.max(start, end));
+    const onEmptyLine = !value.slice(from, to).trim();
+    const at = onEmptyLine ? from : to;
+    const textBefore = value.slice(0, at);
+    const textAfter = value.slice(to);
+    const before = at === 0 || textBefore.endsWith("\n\n") ? "" : textBefore.endsWith("\n") ? "\n" : "\n\n";
+    const after = textAfter.startsWith("\n\n") ? "" : "\n";
+    const blockStart = at + before.length;
+    // Without a selection inside the block, the caret goes to the line after it.
+    const [selectFrom, selectTo] = select ?? [block.length + 1, block.length + 1];
+    return { start: at, end: to, text: before + block + after, selectionStart: blockStart + selectFrom, selectionEnd: blockStart + selectTo };
+}
+/** The full lines a selection touches. A selection that ends at the start of a line does not touch that line. */
+function selectedLines(value, start, end) {
+    const from = lineStartAt(value, start);
+    const to = lineEndAt(value, end > start && value[end - 1] === "\n" ? end - 1 : end);
+    return { from, to, lines: value.slice(from, to).split("\n") };
+}
+function lineStartAt(value, at) {
+    return at <= 0 ? 0 : value.lastIndexOf("\n", at - 1) + 1;
+}
+function lineEndAt(value, at) {
+    const end = value.indexOf("\n", at);
+    return end < 0 ? value.length : end;
+}
+function wordAround(value, at) {
+    if (!WORD.test(value[at - 1] ?? "") || !WORD.test(value[at] ?? ""))
+        return null;
+    let start = at;
+    let end = at;
+    while (start > 0 && WORD.test(value[start - 1]))
+        start--;
+    while (end < value.length && WORD.test(value[end]))
+        end++;
+    return { start, end };
+}

package/dist/Helpers/MarkdownHelpers.d.ts

@@ -0,0 +1,82 @@
+export type MarkdownInline = {
+    type: "text";
+    text: string;
+} | {
+    type: "strong" | "emphasis" | "strike";
+    children: MarkdownInline[];
+} | {
+    type: "code";
+    text: string;
+}
+/** `href` is `null` when the address is not safe to open, such as `javascript:`. */
+ | {
+    type: "link";
+    href: string | null;
+    title?: string;
+    children: MarkdownInline[];
+} | {
+    type: "image";
+    src: string | null;
+    alt: string;
+    title?: string;
+} | {
+    type: "break";
+};
+export type MarkdownAlign = "left" | "center" | "right" | null;
+export interface MarkdownTableCell {
+    children: MarkdownInline[];
+}
+export interface MarkdownListItem {
+    /** `true` or `false` for a task (`- [x]`, `- [ ]`), `null` for any other item. */
+    checked: boolean | null;
+    /** Line of the item's marker in the source, counted from 0, so a preview can tick a task in the text. */
+    line: number;
+    children: MarkdownBlock[];
+}
+export type MarkdownHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export type MarkdownBlock = {
+    type: "heading";
+    level: MarkdownHeadingLevel;
+    children: MarkdownInline[];
+} | {
+    type: "paragraph";
+    children: MarkdownInline[];
+} | {
+    type: "code";
+    language: string;
+    text: string;
+} | {
+    type: "quote";
+    children: MarkdownBlock[];
+}
+/** `tight` lists have no blank lines between their items, and show their text without paragraph spacing. */
+ | {
+    type: "list";
+    ordered: boolean;
+    start: number;
+    tight: boolean;
+    items: MarkdownListItem[];
+} | {
+    type: "table";
+    align: MarkdownAlign[];
+    head: MarkdownTableCell[];
+    rows: MarkdownTableCell[][];
+} | {
+    type: "rule";
+};
+export interface MarkdownOptions {
+    /**
+     * Every line break inside a paragraph shows as a line break, as in GitHub comments. Default true.
+     * Off: lines join into one paragraph, and only a line ending in two spaces or a backslash breaks.
+     */
+    breaks?: boolean;
+}
+/** Parses Markdown into blocks for rendering. Never throws, whatever the text. */
+export declare function parseMarkdown(markdown: string, options?: MarkdownOptions): MarkdownBlock[];
+/** The text of Markdown without its marks, for excerpts, search, and counts. Blocks are separated by a line break. */
+export declare function markdownToPlainText(markdown: string): string;
+/**
+ * The address when a link or image may use it, otherwise `null`. Links allow http, https, mailto, tel, and addresses
+ * without a scheme (relative paths and #anchors); images allow http, https, relative paths, and raster data URLs.
+ */
+export declare function safeUrl(url: string, kind?: "link" | "image"): string | null;