@mdit-vue/shared 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.3.0](https://github.com/mdit-vue/mdit-vue/compare/v0.2.0...v0.3.0) (2022-06-25)
+
+### Features
+
+- **plugin-toc:** add toc plugin ([e64cc2c](https://github.com/mdit-vue/mdit-vue/commit/e64cc2ce3bbc89999d373f8a00fb3a049d6af58f))
+- **shared:** add html escape and unescape utils ([e1103c2](https://github.com/mdit-vue/mdit-vue/commit/e1103c21998aec77c67cdefd3cbb4994c127124c))
+
 # [0.2.0](https://github.com/mdit-vue/mdit-vue/compare/v0.1.1...v0.2.0) (2022-06-23)
 
 ### Features

package/README.md

@@ -12,6 +12,16 @@ npm i @mdit-vue/shared
 
 ## Usage
 
+Add more properties to `env` via [TypeScript module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation):
+
+```ts
+declare module '@mdit-vue/shared' {
+  interface MarkdownItEnv {
+    foo?: string[];
+  }
+}
+```
+
 ```ts
 import MarkdownIt from 'markdown-it';
 import type { MarkdownItEnv } from '@mdit-vue/shared';

package/dist/index.cjs

@@ -1,2 +1,108 @@
 'use strict';
 
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const htmlEscapeMap = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  "'": "&#39;",
+  '"': "&quot;"
+};
+const htmlEscapeRegexp = /[&<>'"]/g;
+const htmlEscape = (str) => str.replace(htmlEscapeRegexp, (char) => htmlEscapeMap[char]);
+
+const htmlUnescapeMap = {
+  "&amp;": "&",
+  "&#38;": "&",
+  "&lt;": "<",
+  "&#60;": "<",
+  "&gt;": ">",
+  "&#62;": ">",
+  "&apos;": "'",
+  "&#39;": "'",
+  "&quot;": '"',
+  "&#34;": '"'
+};
+const htmlUnescapeRegexp = /&(amp|#38|lt|#60|gt|#62|apos|#39|quot|#34);/g;
+const htmlUnescape = (str) => str.replace(htmlUnescapeRegexp, (char) => htmlUnescapeMap[char]);
+
+const resolveTitleFromToken = (token, {
+  shouldAllowHtml,
+  shouldEscapeText
+}) => {
+  const children = token.children ?? [];
+  const titleTokenTypes = ["text", "emoji", "code_inline"];
+  if (shouldAllowHtml) {
+    titleTokenTypes.push("html_inline");
+  }
+  const titleTokens = children.filter((item) => titleTokenTypes.includes(item.type) && !item.meta?.isPermalinkSymbol);
+  return titleTokens.reduce((result, item) => {
+    if (shouldEscapeText) {
+      if (item.type === "code_inline" || item.type === "text") {
+        return `${result}${htmlEscape(item.content)}`;
+      }
+    }
+    return `${result}${item.content}`;
+  }, "").trim();
+};
+
+const resolveHeadersFromTokens = (tokens, {
+  level,
+  shouldAllowHtml,
+  shouldEscapeText,
+  slugify,
+  format
+}) => {
+  const headers = [];
+  const stack = [];
+  const push = (header) => {
+    while (stack.length !== 0 && header.level <= stack[0].level) {
+      stack.shift();
+    }
+    if (stack.length === 0) {
+      headers.push(header);
+      stack.push(header);
+    } else {
+      stack[0].children.push(header);
+      stack.unshift(header);
+    }
+  };
+  tokens.forEach((_, idx) => {
+    const token = tokens[idx];
+    if (token?.type !== "heading_open") {
+      return;
+    }
+    const headerLevel = Number.parseInt(token.tag.slice(1), 10);
+    if (!level.includes(headerLevel)) {
+      return;
+    }
+    const nextToken = tokens[idx + 1];
+    if (!nextToken) {
+      return;
+    }
+    const title = resolveTitleFromToken(nextToken, {
+      shouldAllowHtml,
+      shouldEscapeText
+    });
+    const slug = token.attrGet("id") ?? slugify(title);
+    push({
+      level: headerLevel,
+      title: format?.(title) ?? title,
+      slug,
+      children: []
+    });
+  });
+  return headers;
+};
+
+const rControl = /[\u0000-\u001f]/g;
+const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
+const rCombining = /[\u0300-\u036F]/g;
+const slugify = (str) => str.normalize("NFKD").replace(rCombining, "").replace(rControl, "").replace(rSpecial, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "").replace(/^(\d)/, "_$1").toLowerCase();
+
+exports.htmlEscape = htmlEscape;
+exports.htmlUnescape = htmlUnescape;
+exports.resolveHeadersFromTokens = resolveHeadersFromTokens;
+exports.resolveTitleFromToken = resolveTitleFromToken;
+exports.slugify = slugify;

package/dist/index.d.ts

@@ -1,4 +1,48 @@
+import Token from 'markdown-it/lib/token';
+
+/**
+ * Escape html chars
+ */
+declare const htmlEscape: (str: string) => string;
+
+/**
+ * Unescape html chars
+ */
+declare const htmlUnescape: (str: string) => string;
+
 interface MarkdownItEnv {
 }
+interface MarkdownItHeader {
+    level: number;
+    title: string;
+    slug: string;
+    children: MarkdownItHeader[];
+}
+
+/**
+ * Resolve headers from markdown-it tokens
+ */
+declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldEscapeText, slugify, format, }: {
+    level: number[];
+    shouldAllowHtml: boolean;
+    shouldEscapeText: boolean;
+    slugify: (str: string) => string;
+    format?: ((str: string) => string) | undefined;
+}) => MarkdownItHeader[];
+
+/**
+ * Resolve header title from markdown-it token
+ *
+ * Typically using the next token of `heading_open` token
+ */
+declare const resolveTitleFromToken: (token: Token, { shouldAllowHtml, shouldEscapeText, }: {
+    shouldAllowHtml: boolean;
+    shouldEscapeText: boolean;
+}) => string;
+
+/**
+ * Default slugification function
+ */
+declare const slugify: (str: string) => string;
 
-export { MarkdownItEnv };
+export { MarkdownItEnv, MarkdownItHeader, htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolveTitleFromToken, slugify };

package/dist/index.mjs

@@ -1 +1,100 @@
+const htmlEscapeMap = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  "'": "&#39;",
+  '"': "&quot;"
+};
+const htmlEscapeRegexp = /[&<>'"]/g;
+const htmlEscape = (str) => str.replace(htmlEscapeRegexp, (char) => htmlEscapeMap[char]);
 
+const htmlUnescapeMap = {
+  "&amp;": "&",
+  "&#38;": "&",
+  "&lt;": "<",
+  "&#60;": "<",
+  "&gt;": ">",
+  "&#62;": ">",
+  "&apos;": "'",
+  "&#39;": "'",
+  "&quot;": '"',
+  "&#34;": '"'
+};
+const htmlUnescapeRegexp = /&(amp|#38|lt|#60|gt|#62|apos|#39|quot|#34);/g;
+const htmlUnescape = (str) => str.replace(htmlUnescapeRegexp, (char) => htmlUnescapeMap[char]);
+
+const resolveTitleFromToken = (token, {
+  shouldAllowHtml,
+  shouldEscapeText
+}) => {
+  const children = token.children ?? [];
+  const titleTokenTypes = ["text", "emoji", "code_inline"];
+  if (shouldAllowHtml) {
+    titleTokenTypes.push("html_inline");
+  }
+  const titleTokens = children.filter((item) => titleTokenTypes.includes(item.type) && !item.meta?.isPermalinkSymbol);
+  return titleTokens.reduce((result, item) => {
+    if (shouldEscapeText) {
+      if (item.type === "code_inline" || item.type === "text") {
+        return `${result}${htmlEscape(item.content)}`;
+      }
+    }
+    return `${result}${item.content}`;
+  }, "").trim();
+};
+
+const resolveHeadersFromTokens = (tokens, {
+  level,
+  shouldAllowHtml,
+  shouldEscapeText,
+  slugify,
+  format
+}) => {
+  const headers = [];
+  const stack = [];
+  const push = (header) => {
+    while (stack.length !== 0 && header.level <= stack[0].level) {
+      stack.shift();
+    }
+    if (stack.length === 0) {
+      headers.push(header);
+      stack.push(header);
+    } else {
+      stack[0].children.push(header);
+      stack.unshift(header);
+    }
+  };
+  tokens.forEach((_, idx) => {
+    const token = tokens[idx];
+    if (token?.type !== "heading_open") {
+      return;
+    }
+    const headerLevel = Number.parseInt(token.tag.slice(1), 10);
+    if (!level.includes(headerLevel)) {
+      return;
+    }
+    const nextToken = tokens[idx + 1];
+    if (!nextToken) {
+      return;
+    }
+    const title = resolveTitleFromToken(nextToken, {
+      shouldAllowHtml,
+      shouldEscapeText
+    });
+    const slug = token.attrGet("id") ?? slugify(title);
+    push({
+      level: headerLevel,
+      title: format?.(title) ?? title,
+      slug,
+      children: []
+    });
+  });
+  return headers;
+};
+
+const rControl = /[\u0000-\u001f]/g;
+const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
+const rCombining = /[\u0300-\u036F]/g;
+const slugify = (str) => str.normalize("NFKD").replace(rCombining, "").replace(rControl, "").replace(rSpecial, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "").replace(/^(\d)/, "_$1").toLowerCase();
+
+export { htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolveTitleFromToken, slugify };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdit-vue/shared",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared utils and types of mdit-vue",
   "keywords": [
     "markdown-it",
@@ -30,11 +30,17 @@
     "build": "unbuild",
     "test": "vitest"
   },
+  "dependencies": {
+    "@types/markdown-it": "^12.2.3",
+    "markdown-it": "^13.0.1"
+  },
   "devDependencies": {
-    "unbuild": "^0.7.4"
+    "c8": "^7.11.3",
+    "unbuild": "^0.7.4",
+    "vitest": "^0.15.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "4b796710a93d6126e0c59e9ccc8cd742d5f121ea"
+  "gitHead": "bcbfd4705d747ee71d6c7c32f8be6155261e9c90"
 }

package/src/html-escape.ts

@@ -0,0 +1,18 @@
+const htmlEscapeMap = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  "'": '&#39;',
+  '"': '&quot;',
+};
+
+const htmlEscapeRegexp = /[&<>'"]/g;
+
+/**
+ * Escape html chars
+ */
+export const htmlEscape = (str: string): string =>
+  str.replace(
+    htmlEscapeRegexp,
+    (char) => htmlEscapeMap[char as keyof typeof htmlEscapeMap],
+  );

package/src/html-unescape.ts

@@ -0,0 +1,23 @@
+const htmlUnescapeMap = {
+  '&': '&',
+  '&': '&',
+  '&lt;': '<',
+  '&#60;': '<',
+  '&gt;': '>',
+  '&#62;': '>',
+  '&apos;': "'",
+  '&#39;': "'",
+  '&quot;': '"',
+  '&#34;': '"',
+};
+
+const htmlUnescapeRegexp = /&(amp|#38|lt|#60|gt|#62|apos|#39|quot|#34);/g;
+
+/**
+ * Unescape html chars
+ */
+export const htmlUnescape = (str: string): string =>
+  str.replace(
+    htmlUnescapeRegexp,
+    (char) => htmlUnescapeMap[char as keyof typeof htmlUnescapeMap],
+  );

package/src/index.ts

@@ -1 +1,6 @@
+export * from './html-escape';
+export * from './html-unescape';
+export * from './resolve-headers-from-tokens';
+export * from './resolve-title-from-token';
+export * from './slugify';
 export * from './types';

package/src/resolve-headers-from-tokens.ts

@@ -0,0 +1,88 @@
+import type Token from 'markdown-it/lib/token';
+import { resolveTitleFromToken } from './resolve-title-from-token';
+import type { MarkdownItHeader } from './types';
+
+/**
+ * Resolve headers from markdown-it tokens
+ */
+export const resolveHeadersFromTokens = (
+  tokens: Token[],
+  {
+    level,
+    shouldAllowHtml,
+    shouldEscapeText,
+    slugify,
+    format,
+  }: {
+    level: number[];
+    shouldAllowHtml: boolean;
+    shouldEscapeText: boolean;
+    slugify: (str: string) => string;
+    format?: (str: string) => string;
+  },
+): MarkdownItHeader[] => {
+  // store the result of headers
+  const headers: MarkdownItHeader[] = [];
+
+  // a temp headers stack for generating the headers tree
+  const stack: MarkdownItHeader[] = [];
+
+  // push a header to the headers tree
+  const push = (header: MarkdownItHeader): void => {
+    while (stack.length !== 0 && header.level <= stack[0].level) {
+      stack.shift();
+    }
+
+    if (stack.length === 0) {
+      headers.push(header);
+      stack.push(header);
+    } else {
+      stack[0].children.push(header);
+      stack.unshift(header);
+    }
+  };
+
+  tokens.forEach((_, idx) => {
+    const token = tokens[idx];
+
+    // if the token type does not match, skip
+    if (token?.type !== 'heading_open') {
+      return;
+    }
+
+    // get the level from the tag, h1 -> 1
+    const headerLevel = Number.parseInt(token.tag.slice(1), 10);
+
+    // if the level should not be extracted, skip
+    if (!level.includes(headerLevel)) {
+      return;
+    }
+
+    // the next token of 'heading_open' contains the heading content
+    const nextToken = tokens[idx + 1];
+
+    // if the next token does not exist, skip
+    if (!nextToken) {
+      return;
+    }
+
+    const title = resolveTitleFromToken(nextToken, {
+      shouldAllowHtml,
+      shouldEscapeText,
+    });
+
+    // the id of the heading anchor is the slugify result of markdown-it-anchor
+    // if the id does not exist, slugify the title ourselves
+    const slug = token.attrGet('id') ?? slugify(title);
+
+    // push the header to tree
+    push({
+      level: headerLevel,
+      title: format?.(title) ?? title,
+      slug,
+      children: [],
+    });
+  });
+
+  return headers;
+};

package/src/resolve-title-from-token.ts

@@ -0,0 +1,52 @@
+import type Token from 'markdown-it/lib/token';
+import { htmlEscape } from './html-escape';
+
+/**
+ * Resolve header title from markdown-it token
+ *
+ * Typically using the next token of `heading_open` token
+ */
+export const resolveTitleFromToken = (
+  token: Token,
+  {
+    shouldAllowHtml,
+    shouldEscapeText,
+  }: {
+    shouldAllowHtml: boolean;
+    shouldEscapeText: boolean;
+  },
+): string => {
+  // children of the token contains the parsed result of the heading title
+  const children = token.children ?? [];
+
+  // type of tokens to be included in the heading title
+  const titleTokenTypes = ['text', 'emoji', 'code_inline'];
+
+  // include 'html_inline' or not
+  if (shouldAllowHtml) {
+    titleTokenTypes.push('html_inline');
+  }
+
+  // filter the token type to be included in the title
+  const titleTokens = children.filter(
+    (item) =>
+      titleTokenTypes.includes(item.type) &&
+      // filter permalink symbol that generated by markdown-it-anchor
+      !item.meta?.isPermalinkSymbol,
+  );
+
+  // get title from tokens
+  return titleTokens
+    .reduce((result, item) => {
+      if (shouldEscapeText) {
+        // escape the content of 'code_inline' and 'text'
+        if (item.type === 'code_inline' || item.type === 'text') {
+          return `${result}${htmlEscape(item.content)}`;
+        }
+      }
+
+      // keep the content of 'emoji' and 'html_inline'
+      return `${result}${item.content}`;
+    }, '')
+    .trim();
+};

package/src/slugify.ts

@@ -0,0 +1,25 @@
+// eslint-disable-next-line no-control-regex
+const rControl = /[\u0000-\u001f]/g;
+const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
+const rCombining = /[\u0300-\u036F]/g;
+
+/**
+ * Default slugification function
+ */
+export const slugify = (str: string): string =>
+  str
+    .normalize('NFKD')
+    // Remove accents
+    .replace(rCombining, '')
+    // Remove control characters
+    .replace(rControl, '')
+    // Replace special characters
+    .replace(rSpecial, '-')
+    // Remove continuos separators
+    .replace(/-{2,}/g, '-')
+    // Remove prefixing and trailing separators
+    .replace(/^-+|-+$/g, '')
+    // ensure it doesn't start with a number (#121)
+    .replace(/^(\d)/, '_$1')
+    // lowercase
+    .toLowerCase();

package/src/types.ts

@@ -2,3 +2,10 @@
 export interface MarkdownItEnv {
   // to be extended with module augmentation
 }
+
+export interface MarkdownItHeader {
+  level: number;
+  title: string;
+  slug: string;
+  children: MarkdownItHeader[];
+}

package/tests/html-escape.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { htmlEscape } from '../src';
+
+const testCases = [['&<>\'"', '&amp;&lt;&gt;&#39;&quot;']];
+
+describe('shared > html-escape', () => {
+  describe('should escape special chars', () => {
+    testCases.forEach(([source, expected]) => {
+      it(source, () => {
+        expect(htmlEscape(source)).toBe(expected);
+      });
+    });
+  });
+});

package/tests/html-unescape.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { htmlUnescape } from '../src';
+
+const testCases = [
+  ['&amp;&#38;&lt;&#60;&gt;&#62;&apos;&#39;&quot;&#34;', '&&<<>>\'\'""'],
+  ['&amp;lt;', '&lt;'],
+  [
+    '&amp;lt;script&amp;gt;&amp;lt;/script&amp;gt;',
+    '&lt;script&gt;&lt;/script&gt;',
+  ],
+];
+
+describe('shared > html-unescape', () => {
+  describe('should unescape special chars', () => {
+    testCases.forEach(([source, expected]) => {
+      it(source, () => {
+        expect(htmlUnescape(source)).toBe(expected);
+      });
+    });
+  });
+});

package/tests/slugify.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { slugify } from '../src';
+
+const testCases: [string, string][] = [
+  ['Привет', 'привет'],
+  ['Лед üäöß', 'лед-uaoß'],
+  ['hangul 가', 'hangul-가'],
+  ['ع', 'ع'],
+  ['džℍΩ', 'dzhω'],
+  ['ｶi⁹', 'カi9'],
+  // ㌀ -> アパート'
+  ['㌀', decodeURIComponent('%E3%82%A2%E3%83%8F%E3%82%9A%E3%83%BC%E3%83%88')],
+  ['¼', '_1⁄4'],
+  ['džℍΩｶi⁹¼', 'dzhωカi91⁄4'],
+  ['Iлｔèｒｎåｔïｏｎɑｌíƶａｔï߀ԉ', 'iлternationɑliƶati߀ԉ'],
+  [
+    'Båｃòл íｐѕùｍ ðｏɭ߀ｒ ѕïｔ ａϻèｔ âùþê ａԉᏧ߀üïｌɭê ƃëéｆ ｃｕｌρá ｆïｌèｔ ϻｉǥｎòｎ ｃｕρｉᏧａｔａｔ ｕｔ êлｉｍ ｔòлɢùê.',
+    'bacoл-ipѕum-ðoɭ߀r-ѕit-aϻet-auþe-aԉꮷ߀uilɭe-ƃeef-culρa-filet-ϻiǥnon-cuρiꮷatat-ut-eлim-toлɢue',
+  ],
+  ['ᴎᴑᴅᴇȷʂ', 'ᴎᴑᴅᴇȷʂ'],
+  ['hambúrguer', 'hamburguer'],
+  ['hŒllœ', 'hœllœ'],
+  ['Fußball', 'fußball'],
+  ['ABCDEFGHIJKLMNOPQRSTUVWXYZé', 'abcdefghijklmnopqrstuvwxyze'],
+];
+
+describe('shared > slugify', () => {
+  describe('should slugify string correctly', () => {
+    testCases.forEach(([source, expected]) => {
+      it(`${source} => ${expected}`, () => {
+        expect(slugify(source)).toBe(expected);
+      });
+    });
+  });
+});