term-md 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# term-md
+
+Render Markdown strings for terminal output.
+
+## Install
+
+```sh
+npm install term-md
+```
+
+## Usage
+
+```js
+import termMd from 'term-md';
+
+const output = termMd('# Title\n\nHello **terminal** `markdown`.');
+console.log(output);
+```
+
+### Override styles
+
+```js
+import chalk from 'chalk';
+import termMd from 'term-md';
+
+const output = termMd('Read [docs](https://example.com).', {
+  heading: chalk.cyan.bold,
+  link: chalk.green,
+  href: chalk.gray.underline,
+  codespan: chalk.yellow,
+});
+```
+
+### Reflow text
+
+```js
+import termMd from 'term-md';
+
+console.log(
+  termMd('A long paragraph that should wrap for narrow terminals.', {
+    reflowText: true,
+    width: 40,
+  }),
+);
+```
+
+### Custom list wrapper
+
+```js
+import termMd from 'term-md';
+
+console.log(
+  termMd('- first\n- second', {
+    list(body, ordered) {
+      return ordered ? `ordered:\n${body}` : `unordered:\n${body}`;
+    },
+  }),
+);
+```
+
+### Options
+
+```js
+import chalk from 'chalk';
+
+const options = {
+  code: chalk.yellow,
+  blockquote: chalk.gray.italic,
+  html: chalk.gray,
+  heading: chalk.green.bold,
+  firstHeading: chalk.magenta.underline.bold,
+  hr: chalk.reset,
+  listitem: chalk.reset,
+  table: chalk.reset,
+  paragraph: chalk.reset,
+  strong: chalk.bold,
+  em: chalk.italic,
+  codespan: chalk.yellow,
+  del: chalk.dim.gray.strikethrough,
+  link: chalk.blue,
+  href: chalk.blue.underline,
+
+  list(body, ordered) {
+    return body;
+  },
+
+  width: 80,
+  reflowText: false,
+  showSectionPrefix: true,
+  unescape: true,
+  emoji: true,
+  tableOptions: {
+    paddingLeft: 0,
+    paddingRight: 0,
+    colWidths: [],
+  },
+  tab: 3,
+};
+```
+
+### Import defaults
+
+```js
+import termMd, { defaultOptions } from 'term-md';
+
+const output = termMd('~~old~~ **new**', {
+  ...defaultOptions,
+  del: (value) => value,
+});
+```
+
+## Related
+
+- [marked-terminal](https://github.com/mikaelbr/marked-terminal)

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "term-md",
+  "version": "1.0.0",
+  "description": "Render Markdown strings for terminal output.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "markdown",
+    "terminal",
+    "cli"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "marked": "^18.0.3"
+  }
+}

package/src/index.js

@@ -0,0 +1,586 @@
+import chalk from 'chalk';
+import { lexer } from 'marked';
+
+const ANSI_PATTERN = /\x1B\[[0-?]*[ -/]*[@-~]/g;
+const EMOJI_PATTERN = /\p{Extended_Pictographic}/u;
+const REGIONAL_INDICATOR_PATTERN = /[\u{1F1E6}-\u{1F1FF}]/u;
+const KEYCAP_PATTERN = /[0-9#*]\uFE0F?\u20E3/u;
+const EMOJI_SEQUENCE_PATTERN =
+  /[\u{1F1E6}-\u{1F1FF}]{2}|[0-9#*]\uFE0F?\u20E3|\p{Extended_Pictographic}(?:[\uFE0E\uFE0F]|\u200D\p{Extended_Pictographic}(?:[\uFE0E\uFE0F])?)*/gu;
+const DEFAULT_BULLET = '-';
+const NAMED_ENTITIES = new Map([
+  ['Aacute', '\u00C1'],
+  ['Acirc', '\u00C2'],
+  ['Agrave', '\u00C0'],
+  ['Aring', '\u00C5'],
+  ['Atilde', '\u00C3'],
+  ['Auml', '\u00C4'],
+  ['Ccedil', '\u00C7'],
+  ['Eacute', '\u00C9'],
+  ['Ecirc', '\u00CA'],
+  ['Egrave', '\u00C8'],
+  ['Euml', '\u00CB'],
+  ['Iacute', '\u00CD'],
+  ['Icirc', '\u00CE'],
+  ['Igrave', '\u00CC'],
+  ['Iuml', '\u00CF'],
+  ['Ntilde', '\u00D1'],
+  ['Oacute', '\u00D3'],
+  ['Ocirc', '\u00D4'],
+  ['Ograve', '\u00D2'],
+  ['Oslash', '\u00D8'],
+  ['Otilde', '\u00D5'],
+  ['Ouml', '\u00D6'],
+  ['Uacute', '\u00DA'],
+  ['Ucirc', '\u00DB'],
+  ['Ugrave', '\u00D9'],
+  ['Uuml', '\u00DC'],
+  ['Yacute', '\u00DD'],
+  ['aacute', '\u00E1'],
+  ['acirc', '\u00E2'],
+  ['acute', '\u00B4'],
+  ['aelig', '\u00E6'],
+  ['agrave', '\u00E0'],
+  ['amp', '&'],
+  ['aring', '\u00E5'],
+  ['apos', "'"],
+  ['atilde', '\u00E3'],
+  ['auml', '\u00E4'],
+  ['brvbar', '\u00A6'],
+  ['bull', '\u2022'],
+  ['ccedil', '\u00E7'],
+  ['cedil', '\u00B8'],
+  ['cent', '\u00A2'],
+  ['circ', '\u02C6'],
+  ['clubs', '\u2663'],
+  ['copy', '\u00A9'],
+  ['curren', '\u00A4'],
+  ['dagger', '\u2020'],
+  ['Dagger', '\u2021'],
+  ['deg', '\u00B0'],
+  ['diams', '\u2666'],
+  ['divide', '\u00F7'],
+  ['eacute', '\u00E9'],
+  ['ecirc', '\u00EA'],
+  ['egrave', '\u00E8'],
+  ['emsp', '\u2003'],
+  ['ensp', '\u2002'],
+  ['eth', '\u00F0'],
+  ['euml', '\u00EB'],
+  ['euro', '\u20AC'],
+  ['frac12', '\u00BD'],
+  ['frac14', '\u00BC'],
+  ['frac34', '\u00BE'],
+  ['ge', '\u2265'],
+  ['gt', '>'],
+  ['harr', '\u2194'],
+  ['hearts', '\u2665'],
+  ['hellip', '\u2026'],
+  ['iacute', '\u00ED'],
+  ['icirc', '\u00EE'],
+  ['iexcl', '\u00A1'],
+  ['igrave', '\u00EC'],
+  ['iquest', '\u00BF'],
+  ['iuml', '\u00EF'],
+  ['laquo', '\u00AB'],
+  ['larr', '\u2190'],
+  ['ldquo', '\u201C'],
+  ['le', '\u2264'],
+  ['lsaquo', '\u2039'],
+  ['lsquo', '\u2018'],
+  ['lt', '<'],
+  ['mdash', '\u2014'],
+  ['micro', '\u00B5'],
+  ['middot', '\u00B7'],
+  ['minus', '\u2212'],
+  ['mu', '\u03BC'],
+  ['nabla', '\u2207'],
+  ['ndash', '\u2013'],
+  ['nbsp', '\u00A0'],
+  ['not', '\u00AC'],
+  ['ntilde', '\u00F1'],
+  ['oacute', '\u00F3'],
+  ['ocirc', '\u00F4'],
+  ['ograve', '\u00F2'],
+  ['ordf', '\u00AA'],
+  ['ordm', '\u00BA'],
+  ['oslash', '\u00F8'],
+  ['otilde', '\u00F5'],
+  ['ouml', '\u00F6'],
+  ['para', '\u00B6'],
+  ['permil', '\u2030'],
+  ['plusmn', '\u00B1'],
+  ['pound', '\u00A3'],
+  ['quot', '"'],
+  ['raquo', '\u00BB'],
+  ['rarr', '\u2192'],
+  ['reg', '\u00AE'],
+  ['rdquo', '\u201D'],
+  ['rsaquo', '\u203A'],
+  ['rsquo', '\u2019'],
+  ['sbquo', '\u201A'],
+  ['sect', '\u00A7'],
+  ['shy', '\u00AD'],
+  ['spades', '\u2660'],
+  ['sup1', '\u00B9'],
+  ['sup2', '\u00B2'],
+  ['sup3', '\u00B3'],
+  ['szlig', '\u00DF'],
+  ['thinsp', '\u2009'],
+  ['thorn', '\u00FE'],
+  ['tilde', '\u02DC'],
+  ['times', '\u00D7'],
+  ['trade', '\u2122'],
+  ['uacute', '\u00FA'],
+  ['ucirc', '\u00FB'],
+  ['ugrave', '\u00F9'],
+  ['uml', '\u00A8'],
+  ['uuml', '\u00FC'],
+  ['yacute', '\u00FD'],
+  ['yen', '\u00A5'],
+  ['yuml', '\u00FF'],
+]);
+
+export const defaultOptions = {
+  // Colors
+  code: chalk.yellow,
+  blockquote: chalk.gray.italic,
+  html: chalk.gray,
+  heading: chalk.green.bold,
+  firstHeading: chalk.magenta.underline.bold,
+  hr: chalk.reset,
+  listitem: chalk.reset,
+  table: chalk.reset,
+  paragraph: chalk.reset,
+  strong: chalk.bold,
+  em: chalk.italic,
+  codespan: chalk.yellow,
+  del: chalk.dim.gray.strikethrough,
+  link: chalk.blue,
+  href: chalk.blue.underline,
+
+  // Formats the bulletpoints and numbers for lists
+  list(body) {
+    return body;
+  },
+
+  // Reflow and print-out width
+  width: 80,
+  reflowText: false,
+
+  // Should it prefix headers?
+  showSectionPrefix: true,
+
+  // Whether or not to undo marked escaping of entities (" -> &quot; etc)
+  unescape: true,
+
+  // Whether or not to show emojis
+  emoji: true,
+
+  // Options passed to table rendering
+  tableOptions: {},
+
+  // The size of tabs in number of spaces or as tab characters
+  tab: 3,
+};
+
+export default function termMd(markdown = '', options = {}) {
+  const opts = normalizeOptions(options);
+  const tokens = lexer(String(markdown));
+  const state = { hasRenderedHeading: false };
+
+  return renderTokens(tokens, opts, state)
+    .filter((block) => block.length > 0)
+    .join('\n\n');
+}
+
+function normalizeOptions(options) {
+  return {
+    ...defaultOptions,
+    ...options,
+    tableOptions: {
+      ...defaultOptions.tableOptions,
+      ...options.tableOptions,
+    },
+  };
+}
+
+function renderTokens(tokens, opts, state) {
+  return tokens.map((token) => renderBlock(token, opts, state)).filter((block) => block !== null);
+}
+
+function renderBlock(token, opts, state) {
+  switch (token.type) {
+    case 'space':
+    case 'def':
+      return null;
+    case 'heading':
+      return renderHeading(token, opts, state);
+    case 'paragraph':
+      return opts.paragraph(renderParagraph(token, opts));
+    case 'blockquote':
+      return opts.blockquote(renderTokens(token.tokens, opts, state).join('\n\n'));
+    case 'list':
+      return renderList(token, opts, state);
+    case 'code':
+      return opts.code(formatText(token.text, opts));
+    case 'html':
+      return opts.html(formatText(token.raw, opts));
+    case 'hr':
+      return opts.hr('---');
+    case 'table':
+      return opts.table(renderTable(token, opts));
+    case 'text':
+      if (token.tokens) {
+        return renderInlineTokens(token.tokens, opts);
+      }
+      return formatText(token.text, opts);
+    default:
+      if (token.tokens) {
+        return renderTokens(token.tokens, opts, state).join('\n\n');
+      }
+      return token.raw ? formatText(token.raw, opts) : '';
+  }
+}
+
+function renderHeading(token, opts, state) {
+  const content = renderInlineTokens(token.tokens ?? [], opts);
+  const prefix = opts.showSectionPrefix ? `${'#'.repeat(token.depth)} ` : '';
+  const body = `${prefix}${content}`;
+  const formatter = state.hasRenderedHeading ? opts.heading : opts.firstHeading;
+
+  state.hasRenderedHeading = true;
+  return formatter(body);
+}
+
+function renderParagraph(token, opts) {
+  const body = renderInlineTokens(token.tokens ?? [], opts);
+  return opts.reflowText ? reflow(body, opts.width) : body;
+}
+
+function renderList(token, opts, state) {
+  const start = Number.isInteger(token.start) ? token.start : 1;
+  const body = token.items
+    .map((item, index) => {
+      const marker = token.ordered ? `${start + index}. ` : `${DEFAULT_BULLET} `;
+      const taskMarker = item.task ? `[${item.checked ? 'x' : ' '}] ` : '';
+      const content = renderListItem(item, opts, state);
+      const lines = `${taskMarker}${content}`.split('\n');
+      const firstLine = `${marker}${lines[0] ?? ''}`;
+      const continuationPrefix = ' '.repeat(visibleLength(marker));
+      const continuationLines = lines.slice(1).map((line) => `${continuationPrefix}${line}`);
+
+      return opts.listitem([firstLine, ...continuationLines].join('\n'));
+    })
+    .join('\n');
+
+  return opts.list(body, token.ordered);
+}
+
+function renderListItem(item, opts, state) {
+  return item.tokens
+    .map((token) => {
+      if (token.type === 'checkbox') {
+        return null;
+      }
+      if (token.type === 'text' && token.tokens) {
+        return renderInlineTokens(token.tokens, opts);
+      }
+      return renderBlock(token, opts, state);
+    })
+    .filter((block) => block !== null && block.length > 0)
+    .join('\n');
+}
+
+function renderTable(token, opts) {
+  const paddingLeft = readTablePadding(opts.tableOptions.paddingLeft);
+  const paddingRight = readTablePadding(opts.tableOptions.paddingRight);
+  const header = token.header.map((cell) => renderInlineTokens(cell.tokens ?? [], opts));
+  const rows = token.rows.map((row) => row.map((cell) => renderInlineTokens(cell.tokens ?? [], opts)));
+  const naturalWidths = header.map((cell, column) =>
+    Math.max(visibleLength(cell), ...rows.map((row) => visibleLength(row[column] ?? ''))),
+  );
+  const widths = naturalWidths.map((width, column) => {
+    const configuredWidth = readConfiguredColumnWidth(opts.tableOptions.colWidths?.[column]);
+    return Math.max(width + paddingLeft + paddingRight, configuredWidth);
+  });
+  const aligns = token.align ?? [];
+  const separator = widths.map((width) => '-'.repeat(width + 1)).join('|');
+  const renderedRows = [
+    renderTableRow(header, widths, aligns, paddingLeft, paddingRight),
+    separator,
+    ...rows.map((row) => renderTableRow(row, widths, aligns, paddingLeft, paddingRight)),
+  ];
+
+  return renderedRows.join('\n');
+}
+
+function renderTableRow(row, widths, aligns, paddingLeft, paddingRight) {
+  return row
+    .map((cell, column) => padCell(cell, widths[column], aligns[column], paddingLeft, paddingRight))
+    .join(' | ');
+}
+
+function padCell(cell, width, align, paddingLeft, paddingRight) {
+  const contentWidth = Math.max(width - paddingLeft - paddingRight, visibleLength(cell));
+  const padding = Math.max(contentWidth - visibleLength(cell), 0);
+  let content;
+
+  if (align === 'right') {
+    content = `${' '.repeat(padding)}${cell}`;
+  } else if (align === 'center') {
+    const left = Math.floor(padding / 2);
+    const right = padding - left;
+    content = `${' '.repeat(left)}${cell}${' '.repeat(right)}`;
+  } else {
+    content = `${cell}${' '.repeat(padding)}`;
+  }
+
+  return `${' '.repeat(paddingLeft)}${content}${' '.repeat(paddingRight)}`;
+}
+
+function readTablePadding(value) {
+  const padding = Number(value ?? 0);
+  return Number.isFinite(padding) && padding > 0 ? Math.floor(padding) : 0;
+}
+
+function readConfiguredColumnWidth(value) {
+  const width = Number(value ?? 0);
+  return Number.isFinite(width) && width > 0 ? Math.floor(width) : 0;
+}
+
+function renderInlineTokens(tokens, opts) {
+  return tokens.map((token) => renderInlineToken(token, opts)).join('');
+}
+
+function renderInlineToken(token, opts) {
+  switch (token.type) {
+    case 'text':
+      if (token.tokens) {
+        return renderInlineTokens(token.tokens, opts);
+      }
+      return formatText(token.text, opts);
+    case 'escape':
+      return formatText(token.text, opts);
+    case 'strong':
+      return opts.strong(renderInlineTokens(token.tokens ?? [], opts));
+    case 'em':
+      return opts.em(renderInlineTokens(token.tokens ?? [], opts));
+    case 'codespan':
+      return opts.codespan(formatText(token.text, opts));
+    case 'del':
+      return opts.del(renderInlineTokens(token.tokens ?? [], opts));
+    case 'link':
+      return renderLink(token, opts);
+    case 'image':
+      return renderImage(token, opts);
+    case 'br':
+      return '\n';
+    case 'html':
+      return opts.html(formatText(token.raw, opts));
+    default:
+      if (token.tokens) {
+        return renderInlineTokens(token.tokens, opts);
+      }
+      return token.raw ? formatText(token.raw, opts) : '';
+  }
+}
+
+function renderLink(token, opts) {
+  const text = opts.link(renderInlineTokens(token.tokens ?? [], opts));
+  const href = formatText(token.href ?? '', opts);
+
+  return href ? `${text} ${opts.href(href)}` : text;
+}
+
+function renderImage(token, opts) {
+  const alt = token.text ? opts.link(formatText(token.text, opts)) : '';
+  const href = token.href ? opts.href(formatText(token.href, opts)) : '';
+
+  return [alt, href].filter(Boolean).join(' ');
+}
+
+function formatText(value, opts) {
+  let text = expandTabs(String(value), opts.tab);
+
+  if (opts.unescape) {
+    text = unescapeEntities(text);
+  }
+  if (!opts.emoji) {
+    text = stripEmoji(text);
+  }
+
+  return text;
+}
+
+function expandTabs(value, tab) {
+  const replacement = typeof tab === 'number' ? ' '.repeat(Math.max(Math.floor(tab), 0)) : String(tab);
+  return value.replaceAll('\t', replacement);
+}
+
+function unescapeEntities(value) {
+  return value.replace(/&(#x[\da-f]+|#\d+|[a-z][\da-z]+);/gi, (entity, body) => {
+    if (body.startsWith('#x') || body.startsWith('#X')) {
+      return decodeCodePoint(entity, Number.parseInt(body.slice(2), 16));
+    }
+    if (body.startsWith('#')) {
+      return decodeCodePoint(entity, Number.parseInt(body.slice(1), 10));
+    }
+
+    return NAMED_ENTITIES.get(body) ?? NAMED_ENTITIES.get(body.toLowerCase()) ?? entity;
+  });
+}
+
+function decodeCodePoint(entity, codePoint) {
+  if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff) {
+    return entity;
+  }
+
+  return String.fromCodePoint(codePoint);
+}
+
+function stripEmoji(value) {
+  if (typeof globalThis.Intl?.Segmenter === 'function') {
+    const segmenter = new globalThis.Intl.Segmenter(undefined, { granularity: 'grapheme' });
+    return Array.from(segmenter.segment(value), ({ segment }) =>
+      isEmojiSegment(segment) ? '' : segment,
+    ).join('');
+  }
+
+  return value.replace(EMOJI_SEQUENCE_PATTERN, '').replace(/[\u200D\uFE0E\uFE0F]/g, '');
+}
+
+function isEmojiSegment(segment) {
+  return EMOJI_PATTERN.test(segment) || REGIONAL_INDICATOR_PATTERN.test(segment) || KEYCAP_PATTERN.test(segment);
+}
+
+function reflow(value, width) {
+  const maxWidth = Math.max(Number(width) || defaultOptions.width, 1);
+  const words = value.trim().split(/\s+/);
+  const lines = [];
+  let line = '';
+
+  for (const word of words) {
+    if (!line) {
+      line = word;
+      continue;
+    }
+
+    if (visibleLength(`${line} ${word}`) > maxWidth) {
+      lines.push(line);
+      line = word;
+      continue;
+    }
+
+    line = `${line} ${word}`;
+  }
+
+  if (line) {
+    lines.push(line);
+  }
+
+  return lines.join('\n');
+}
+
+function visibleLength(value) {
+  return stringWidth(String(value).replace(ANSI_PATTERN, ''));
+}
+
+function stringWidth(value) {
+  let width = 0;
+
+  for (let index = 0; index < value.length; ) {
+    const codePoint = value.codePointAt(index);
+    const character = String.fromCodePoint(codePoint);
+
+    index += character.length;
+
+    if (isZeroWidth(codePoint)) {
+      continue;
+    }
+
+    if (EMOJI_PATTERN.test(character)) {
+      width += 2;
+      index = skipEmojiSequence(value, index);
+      continue;
+    }
+
+    width += isFullWidth(codePoint) ? 2 : 1;
+  }
+
+  return width;
+}
+
+function skipEmojiSequence(value, index) {
+  let nextIndex = index;
+
+  while (nextIndex < value.length) {
+    const codePoint = value.codePointAt(nextIndex);
+    const character = String.fromCodePoint(codePoint);
+
+    if (isVariationSelector(codePoint)) {
+      nextIndex += character.length;
+      continue;
+    }
+
+    if (character !== '\u200D') {
+      break;
+    }
+
+    nextIndex += character.length;
+    const joinedCodePoint = value.codePointAt(nextIndex);
+    if (joinedCodePoint === undefined) {
+      break;
+    }
+    const joinedCharacter = String.fromCodePoint(joinedCodePoint);
+
+    if (!EMOJI_PATTERN.test(joinedCharacter)) {
+      break;
+    }
+
+    nextIndex += joinedCharacter.length;
+  }
+
+  return nextIndex;
+}
+
+function isZeroWidth(codePoint) {
+  return (
+    codePoint === 0 ||
+    codePoint < 32 ||
+    (codePoint >= 0x7f && codePoint < 0xa0) ||
+    isCombiningMark(codePoint) ||
+    isVariationSelector(codePoint)
+  );
+}
+
+function isCombiningMark(codePoint) {
+  return (
+    (codePoint >= 0x0300 && codePoint <= 0x036f) ||
+    (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+    (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+    (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+    (codePoint >= 0xfe20 && codePoint <= 0xfe2f)
+  );
+}
+
+function isVariationSelector(codePoint) {
+  return (codePoint >= 0xfe00 && codePoint <= 0xfe0f) || (codePoint >= 0xe0100 && codePoint <= 0xe01ef);
+}
+
+function isFullWidth(codePoint) {
+  return (
+    codePoint >= 0x1100 &&
+    (codePoint <= 0x115f ||
+      codePoint === 0x2329 ||
+      codePoint === 0x232a ||
+      (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+      (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+      (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+      (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+      (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+      (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+      (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+      (codePoint >= 0x20000 && codePoint <= 0x3fffd))
+  );
+}