sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ copy-editor/ markdown.ts

/**
 * Markdown prose as an editable source.
 *
 * {@link markdownRuns} splits one block of inline markdown (a paragraph,
 * heading, or list item) into the runs its rendered text nodes come from:
 * text between emphasis delimiters, code spans, link text, and so on. The
 * markdown can live inside another file (a JSDoc comment, a string) — the
 * `linePrefix` option describes text that starts each continuation line.
 */
import { CopyEditError, decodeEntities, type Dialect, type Run, type TextToken } from "./text.ts";

/** A syntax whose rendered text isn't literal source text (e.g. `{@link X}`). */
export interface Atomic {
  /** Matched at the current position (compiled with the sticky flag). */
  pattern: RegExp;
  /** The rendered text for a match (continuation-line prefixes removed). */
  text: (match: RegExpExecArray) => string;
}

export interface MarkdownOptions {
  /**
   * Source of a regex matching what follows `\n` on continuation lines and
   * isn't content, e.g. `"[ \\t]*\\*(?!/)[ \\t]?"` for JSDoc's ` * `.
   */
  linePrefix?: string;
  /** Extra inline syntaxes rendered as generated, non-editable text. */
  atomics?: Atomic[];
}

const PUNCT = /[!-/:-@[-`{-~\p{P}\p{S}]/u;
const isWs = (ch: string | undefined) => ch === undefined || /\s/.test(ch);
const isPunct = (ch: string | undefined) => ch !== undefined && PUNCT.test(ch);

/** Straight quotes, dashes, and dots: how smart punctuation renders them. */
const canon = (text: string) =>
  text
    .replace(/[“”„]/g, '"')
    .replace(/[‘’‚]/g, "'")
    .replace(/—/g, "---")
    .replace(/–/g, "--")
    .replace(/…/g, "...")
    .replace(/\u00a0/g, " ");

const decodeMarkdown = (raw: string) => decodeEntities(raw.replace(/\\([!-/:-@[-`{-~])/g, "$1"));

export const markdownDialect = (options: MarkdownOptions = {}): Dialect => {
  const ws = new RegExp(
    `(?:[ \\t\\r\\f]|\\n${options.linePrefix ? `(?:${options.linePrefix})?` : ""})+`,
    "y",
  );
  return {
    tokenize(raw, kind) {
      const tokens: TextToken[] = [];
      let i = 0;
      while (i < raw.length) {
        ws.lastIndex = i;
        const m = ws.exec(raw);
        if (m && m[0].length > 0) {
          tokens.push({ raw: m[0], ws: true, text: " " });
          i += m[0].length;
          continue;
        }
        let j = i;
        while (j < raw.length && !/[ \t\r\f\n]/.test(raw[j])) j++;
        const word = raw.slice(i, j);
        tokens.push({
          raw: word,
          ws: false,
          text: kind === "code" ? word : decodeMarkdown(word),
        });
        i = j;
      }
      return tokens;
    },
    compare: canon,
    escape(word, { kind, lineStart }) {
      if (kind === "code") {
        if (word.includes("`") || word.includes("*/")) {
          throw new CopyEditError("Code spans can't contain ` or */.");
        }
        return word;
      }
      let out = word
        .replace(/[“”]/g, '"')
        .replace(/[‘’]/g, "'")
        .replace(/…/g, "...")
        .replace(/[\\`*[\]<]/g, "\\

Loading Sailfork

amp;") .replace(/^_|_$/g, "\\_") .replace(/~~/g, "\\~\\~") .replace(/\{@/g, "{\\@"); if (lineStart) { out = out.replace(/^[#>+\-=|:@]/, "\\

Loading Sailfork

amp;").replace(/^(\d+)([.)])/, "$1\\$2"); } // Never let prose close a surrounding block comment. return out.replace(/\*\//g, "*\\/"); }, }; }; /** * Splits the inline markdown in `code[start, end)` into runs matching its * rendered text nodes. The first run starts a line. */ export const markdownRuns = ( code: string, start: number, end: number, options: MarkdownOptions = {}, ): Run[] => { const prefix = options.linePrefix ? new RegExp(`\\n(?:${options.linePrefix})`, "g") : undefined; const clean = (raw: string) => (prefix ? raw.replace(prefix, "\n") : raw); const atomics = (options.atomics ?? []).map(({ pattern, text }) => ({ pattern: new RegExp(pattern.source, `${pattern.flags.replace(/[gy]/g, "")}y`), text, })); const runs: Run[] = []; let runStart = start; const boundary = (at: number, resume: number) => { runs.push({ start: runStart, end: at, lineStart: runs.length === 0 }); runStart = resume; }; const locked = (at: number, resume: number, expected: string) => { boundary(at, at); runs.push({ start: at, end: resume, kind: "locked", expected }); runStart = resume; }; // Positions of `]` that close link text, mapped to the end of `](...)`. const linkEnds = new Map<number, number>(); let i = start; while (i < end) { const ch = code[i]; if (ch === "\\" && i + 1 < end && /[!-/:-@[-`{-~]/.test(code[i + 1])) { i += 2; continue; } const atomic = atomics.find((a) => { a.pattern.lastIndex = i; return a.pattern.test(code) && a.pattern.lastIndex <= end; }); if (atomic) { atomic.pattern.lastIndex = i; const m = atomic.pattern.exec(code)!; const cleaned = Object.assign(m.map(clean), { index: m.index, input: m.input, }); locked(i, i + m[0].length, atomic.text(cleaned as RegExpExecArray)); i += m[0].length; continue; } if (ch === "`") { let n = 1; while (code[i + n] === "`") n++; const fence = "`".repeat(n); let close = code.indexOf(fence, i + n); while (close !== -1 && close < end && code[close + n] === "`") { close = code.indexOf(fence, close + n + 1); } if (close !== -1 && close + n <= end) { boundary(i, i + n); runs.push({ start: i + n, end: close, kind: "code" }); runStart = close + n; i = close + n; continue; } i += n; continue; } if (ch === "<") { const autolink = /^<(https?:\/\/[^\s<>]+)>/.exec(code.slice(i, end)); if (autolink) { locked(i, i + autolink[0].length, autolink[1]); i += autolink[0].length; continue; } const tag = /^<\/?[A-Za-z][^<>]*>|^<!--[\s\S]*?-->/.exec(code.slice(i, end)); if (tag) { boundary(i, i + tag[0].length); i += tag[0].length; continue; } } if ( ((ch === "h" || ch === "w") && isWs(code[i - 1])) || (i === start && (ch === "h" || ch === "w")) ) { const url = /^(?:https?:\/\/|www\.)[^\s<]*[^\s<.,:;"')\]!?*_~]/.exec(code.slice(i, end)); if (url) { locked(i, i + url[0].length, url[0]); i += url[0].length; continue; } } if (ch === "!" && code[i + 1] === "[") { const img = /^!\[[^\]]*\]\([^)]*\)/.exec(code.slice(i, end)); if (img) { boundary(i, i + img[0].length); i += img[0].length; continue; } } if (ch === "[") { const close = matchLink(code, i, end); if (close) { linkEnds.set(close.bracket, close.end); boundary(i, i + 1); i += 1; continue; } } if (ch === "]" && linkEnds.has(i)) { const after = linkEnds.get(i)!; boundary(i, after); i = after; continue; } if (ch === "*" || ch === "_" || ch === "~") { let n = 1; while (code[i + n] === ch) n++; const prev = code[i - 1]; const next = code[i + n]; const left = !isWs(next) && (!isPunct(next) || isWs(prev) || isPunct(prev)); const right = !isWs(prev) && (!isPunct(prev) || isWs(next) || isPunct(next)); const delimiter = ch === "~" ? n === 2 && (left || right) : ch === "*" ? left || right : (left && (!right || isPunct(prev))) || (right && (!left || isPunct(next))); if (delimiter) { boundary(i, i + n); i += n; continue; } i += n; continue; } i++; } boundary(end, end); return runs; }; /** Finds the `]` closing `[` at `open` when followed by `(destination)`. */ const matchLink = (code: string, open: number, end: number) => { let depth = 0; for (let i = open; i < end; i++) { const ch = code[i]; if (ch === "\\") { i++; continue; } if (ch === "`") { const close = code.indexOf("`", i + 1); if (close === -1 || close >= end) return undefined; i = close; continue; } if (ch === "[") depth++; else if (ch === "]" && --depth === 0) { if (code[i + 1] !== "(") return undefined; let parens = 0; for (let j = i + 1; j < end; j++) { if (code[j] === "(") parens++; else if (code[j] === ")" && --parens === 0) { return { bracket: i, end: j + 1 }; } } return undefined; } } return undefined; };