@cherry-markdown/cherry-markdown-dev 0.8.58-dev

package/src/core/HookCenter.js

@@ -0,0 +1,297 @@
+/**
+ * Copyright (C) 2021 THL A29 Limited, a Tencent company.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import SyntaxBase from './SyntaxBase';
+import ParagraphBase from './ParagraphBase';
+import { $expectTarget } from '@/utils/error';
+import Logger from '@/Logger';
+
+/**
+ * @typedef {import('~types/cherry').CherryOptions} CherryOptions
+ * @typedef {import('~types/cherry').CherryEngineOptions} CherryEngineOptions
+ * @typedef {import('~types/cherry').CustomSyntaxRegConfig} CustomSyntaxRegConfig
+ * @typedef { (SyntaxBase | ParagraphBase) & { Cherry$$CUSTOM: true } } CustomSyntax
+ * @typedef { (typeof SyntaxBase | typeof ParagraphBase) & { Cherry$$CUSTOM: true } } CustomSyntaxClass
+ */
+
+const WARN_DUPLICATED = -1;
+const WARN_NOT_A_VALID_HOOK = -2;
+
+/**
+ * 处理报错信息，在dev模式下才会输出报错信息
+ * @param {number} type
+ * @param {any} objClass
+ * @param {number} index
+ */
+function processWarning(type, objClass, index) {
+  if (type === WARN_DUPLICATED) {
+    Logger.warn(
+      `Duplicate hook name [${objClass.HOOK_NAME}] found, hook [${objClass.toString()}] ${
+        isNaN(index) ? '' : `at index [${index}] `
+      }will not take effect.`,
+    );
+  } else if (type === WARN_NOT_A_VALID_HOOK) {
+    Logger.warn(
+      `Hook [${objClass.toString()}] ${
+        isNaN(index) ? '' : `at index [${index}] `
+      }is not a valid hook, and will not take effect.`,
+    );
+  }
+}
+
+/**
+ * 是否一个合法的 HookClass
+ * @param {any} HookClass
+ * @returns { HookClass is (typeof SyntaxBase | typeof ParagraphBase) }
+ */
+function isHookValid(HookClass) {
+  return isProtoOfSyntaxBase(HookClass) || isProtoOfParagraphBase(HookClass);
+}
+
+/**
+ * 传入的类是否 SyntaxBase 的子类
+ * @param {any} value
+ * @returns { value is typeof SyntaxBase }
+ */
+function isProtoOfSyntaxBase(value) {
+  return Object.prototype.isPrototypeOf.call(SyntaxBase, value);
+}
+
+/**
+ * 传入的类是否 ParagraphBase 的子类
+ * @param {any} value
+ * @returns { value is typeof ParagraphBase }
+ */
+function isProtoOfParagraphBase(value) {
+  return Object.prototype.isPrototypeOf.call(ParagraphBase, value);
+}
+
+/**
+ * 是否一个配置型的自定义语法
+ * @param {any} value
+ * @returns { value is CustomSyntaxRegConfig }
+ */
+function isCustomSyntaxConfig(value) {
+  const syntaxClass = /** @type {any} */ (/** @type {CustomSyntaxRegConfig} */ (value)?.syntaxClass);
+  return isProtoOfSyntaxBase(syntaxClass) || isProtoOfParagraphBase(syntaxClass);
+}
+
+/**
+ * 是否一个已注册的自定义语法hook类
+ * @param {any} value
+ * @returns { value is CustomSyntaxClass }
+ */
+function isRegisteredCustomSyntaxClass(value) {
+  return isHookValid(value) && /** @type {CustomSyntaxClass} */ (value)?.Cherry$$CUSTOM === true;
+}
+
+/**
+ * 语法注册中心
+ */
+export default class HookCenter {
+  /**
+   *
+   * @param {(typeof SyntaxBase)[]} hooksConfig
+   * @param {CherryOptions} editorConfig
+   */
+  constructor(hooksConfig, editorConfig, cherry) {
+    this.$locale = cherry.locale;
+    this.$cherry = cherry;
+    /**
+     * @property
+     * @type {Record<import('./SyntaxBase').HookType, SyntaxBase[]>} hookList hook 名称 -> hook 类型的映射
+     */
+    this.hookList = /** @type {any} */ ({});
+
+    /**
+     * @property
+     * @type {Record<string, { type: import('./SyntaxBase').HookType }>} hookNameList hook 名称 -> hook 类型的映射
+     */
+    this.hookNameList = {};
+
+    $expectTarget(hooksConfig, Array);
+    this.registerInternalHooks(hooksConfig, editorConfig);
+    this.registerCustomHooks(editorConfig.engine.customSyntax, editorConfig);
+  }
+
+  /**
+   * 注册系统默认的语法hook
+   * @param {any[]} hooksConfig 在hookconfig.js里定义的配置
+   * @param {CherryOptions} editorConfig 编辑器配置
+   */
+  registerInternalHooks(hooksConfig, editorConfig) {
+    hooksConfig.forEach(
+      /**
+       *
+       * @param {typeof SyntaxBase} HookClass
+       * @param {number} index
+       */
+      (HookClass, index) => {
+        const result = this.register(HookClass, editorConfig);
+        processWarning(result, HookClass, index);
+      },
+    );
+  }
+
+  /**
+   * 注册第三方的语法hook
+   * @param {CherryEngineOptions['customSyntax']} customHooks 用户传入的配置
+   * @param {CherryOptions} editorConfig 编辑器配置
+   */
+  registerCustomHooks(customHooks, editorConfig) {
+    if (!customHooks) {
+      return;
+    }
+    const hookNames = Object.keys(customHooks);
+    hookNames.forEach((hookName) => {
+      /** @type {number} */
+      let result;
+      /** @type {typeof SyntaxBase} */
+      let HookClass;
+      const customHookConfig = {};
+      const hookClassOrConfig = customHooks[hookName];
+      if (isProtoOfSyntaxBase(hookClassOrConfig)) {
+        HookClass = hookClassOrConfig;
+      } else if (isCustomSyntaxConfig(hookClassOrConfig)) {
+        HookClass = hookClassOrConfig.syntaxClass;
+        customHookConfig.force = Boolean(hookClassOrConfig.force);
+        if (hookClassOrConfig.before) {
+          customHookConfig.before = hookClassOrConfig.before;
+        } else if (hookClassOrConfig.after) {
+          customHookConfig.after = hookClassOrConfig.after;
+        }
+      } else {
+        return;
+      }
+      if (isHookValid(HookClass)) {
+        // 自定义Hook标识
+        Object.defineProperty(HookClass, 'Cherry$$CUSTOM', {
+          enumerable: false,
+          configurable: false,
+          writable: false,
+          value: true,
+        });
+        result = this.register(HookClass, editorConfig, customHookConfig);
+      } else {
+        result = WARN_NOT_A_VALID_HOOK;
+      }
+      processWarning(result, HookClass, undefined);
+    });
+  }
+
+  getHookList() {
+    return this.hookList;
+  }
+
+  getHookNameList() {
+    return this.hookNameList;
+  }
+
+  /**
+   *
+   * @param {((...args: any[]) => any) | typeof SyntaxBase} HookClass
+   * @param {CherryOptions} editorConfig
+   * @param {Omit<CustomSyntaxRegConfig, 'syntaxClass'>} [customHookConfig]
+   * @returns
+   */
+  register(HookClass, editorConfig, customHookConfig) {
+    // filter Configs Here
+    const { externals, engine } = editorConfig;
+    const { syntax } = engine;
+    const { $cherry } = this;
+
+    /** @type {SyntaxBase | CustomSyntax} */
+    let instance;
+
+    /** @type {string} */
+    let hookName;
+
+    // 首先校验Hook是否合法
+    if (!isHookValid(HookClass)) {
+      // 可能是一个function hook
+      if (typeof HookClass === 'function') {
+        const funcHook = HookClass;
+        instance = funcHook(editorConfig);
+        if (!instance || !isHookValid(instance.constructor)) {
+          return WARN_NOT_A_VALID_HOOK;
+        }
+        hookName = instance.getName();
+      } else {
+        return WARN_NOT_A_VALID_HOOK;
+      }
+    } else {
+      hookName = HookClass.HOOK_NAME;
+      // TODO: 需要考虑自定义 hook 配置的传入方式
+      const config = syntax?.[hookName] || {};
+      instance = new HookClass({ externals, config, globalConfig: engine.global, cherry: $cherry });
+      instance.afterInit(() => {
+        instance.setLocale(this.$locale);
+      });
+    }
+    // TODO: 待校验是否需要跳过禁用的自定义 hook
+    // Skip Disabled Internal Hooks
+    if (syntax[hookName] === false && !isRegisteredCustomSyntaxClass(HookClass)) {
+      return;
+    }
+    // 下面处理的都是 CustomSyntax
+    const hookType = instance.getType();
+    if (this.hookNameList[hookName]) {
+      // 内置 hook 重名
+      if (!isRegisteredCustomSyntaxClass(HookClass)) {
+        return WARN_DUPLICATED;
+      }
+      // 自定义 hook 重名且没有开启覆盖的选项
+      if (!customHookConfig.force) {
+        return WARN_DUPLICATED;
+      }
+      // 强制覆盖以前的Hook，所以需要移除
+      const duplicateHookType = this.hookNameList[hookName].type;
+      this.hookList[duplicateHookType] = this.hookList[duplicateHookType].filter((hook) => hook.getName() !== hookName);
+    }
+    this.hookNameList[hookName] = { type: hookType };
+    this.hookList[hookType] = this.hookList[hookType] || [];
+    // 内置Hook直接push到结尾
+    if (!isRegisteredCustomSyntaxClass(HookClass)) {
+      this.hookList[hookType].push(instance);
+      return;
+    }
+    // 插入自定义Hook
+    let insertIndex = -1;
+    if (customHookConfig.before) {
+      insertIndex = this.hookList[hookType].findIndex((hook) => hook.getName() === customHookConfig.before);
+      if (insertIndex === -1) {
+        Logger.warn(
+          `Cannot find hook named [${customHookConfig.before}],
+            custom hook [${hookName}] will append to the end of the hooks.`,
+        );
+      }
+    } else if (customHookConfig.after) {
+      insertIndex = this.hookList[hookType].findIndex((hook) => hook.getName() === customHookConfig.after);
+      insertIndex === -1
+        ? Logger.warn(
+            `Cannot find hook named [${customHookConfig.after}],
+              custom hook [${hookName}] will append to the end of the hooks.`,
+          )
+        : (insertIndex += 1); // 统一处理往前插入的逻辑，所以要插入某Hook之后，索引需要加一
+    }
+    // 无需插入或目标索引为数组结尾
+    if (insertIndex < 0 || insertIndex >= this.hookList[hookType].length) {
+      this.hookList[hookType].push(instance);
+    } else {
+      this.hookList[hookType].splice(insertIndex, 0, instance);
+    }
+    // console.log(this.hookList[hookType]);
+  }
+}

package/src/core/HooksConfig.js

@@ -0,0 +1,100 @@
+/**
+ * Copyright (C) 2021 THL A29 Limited, a Tencent company.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// import Bold from './hooks/Bold';
+// import Italic from './hooks/Italic';
+// import Underline from './hooks/Underline';
+import Color from './hooks/Color';
+import BackgroundColor from './hooks/BackgroundColor';
+import Size from './hooks/Size';
+import Strikethrough from './hooks/Strikethrough';
+import Sup from './hooks/Sup';
+import Sub from './hooks/Sub';
+import InlineCode from './hooks/InlineCode';
+import CodeBlock from './hooks/CodeBlock';
+import Link from './hooks/Link';
+import Emphasis from './hooks/Emphasis';
+import Paragraph from './hooks/Paragraph';
+import Header from './hooks/Header';
+import Transfer from './hooks/Transfer';
+import Table from './hooks/Table';
+import Br from './hooks/Br';
+import Hr from './hooks/Hr';
+import Image from './hooks/Image';
+import List from './hooks/List';
+import Blockquote from './hooks/Blockquote';
+import AutoLink from './hooks/AutoLink';
+import MathBlock from './hooks/MathBlock';
+import InlineMath from './hooks/InlineMath';
+import Toc from './hooks/Toc';
+import Footnote from './hooks/Footnote';
+import CommentReference from './hooks/CommentReference';
+import HtmlBlock from './hooks/HtmlBlock';
+import Emoji from './hooks/Emoji';
+import Underline from './hooks/Underline';
+import HighLight from './hooks/HighLight';
+import Suggester from './hooks/Suggester';
+import Ruby from './hooks/Ruby';
+import Panel from './hooks/Panel';
+import Detail from './hooks/Detail';
+import FrontMatter from './hooks/FrontMatter';
+/**
+ * 引擎各语法的配置
+ * 主要决定支持哪些语法，以及各语法的执行顺序
+ */
+const hooksConfig = [
+  // 段落级 Hook
+  // 引擎会按当前排序顺序执行beforeMake、makeHtml方法
+  // 引擎会按当前排序逆序执行afterMake方法
+  FrontMatter,
+  CodeBlock,
+  InlineCode,
+  MathBlock,
+  InlineMath,
+  HtmlBlock,
+  Footnote,
+  CommentReference,
+  Transfer,
+  Br,
+  Table,
+  Blockquote,
+  Toc,
+  Header, // 处理标题, 传入strict属性严格要求ATX风格标题#后带空格
+  Hr,
+  List,
+  Detail,
+  Panel,
+  Paragraph, // 普通段落
+
+  // 行内Hook
+  // 引擎会按当前顺序执行makeHtml方法
+  Emoji,
+  Image,
+  Link,
+  AutoLink,
+  Emphasis,
+  BackgroundColor,
+  Color,
+  Size,
+  Sub,
+  Sup,
+  Ruby,
+  Strikethrough,
+  Underline,
+  HighLight,
+  Suggester,
+];
+
+export default hooksConfig;