@lark-apaas/coding-template-nestjs-react-fullstack 0.1.0-alpha.1

package/template/client/src/components/business-ui/tiptap-editor/extensions/code-block-shiki.tsx

@@ -0,0 +1,236 @@
+'use client';
+
+import * as React from 'react';
+import { CodeBlock } from '@tiptap/extension-code-block';
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+import {
+  NodeViewContent,
+  NodeViewWrapper,
+  ReactNodeViewRenderer,
+  type NodeViewProps,
+} from '@tiptap/react';
+import { debounce } from 'es-toolkit';
+
+import {
+  bundledLanguages,
+  codeToTokensWithThemes,
+  type BundledLanguage,
+} from '@/lib/shiki';
+import { cn } from '@/lib/utils';
+
+const codeBlockShikiPluginKey = new PluginKey<DecorationSet>(
+  'codeBlockShikiDecorations',
+);
+
+const CodeNodeViewContent = NodeViewContent<'code'>;
+
+type Language = BundledLanguage | 'text';
+
+const themes = {
+  light: 'github-light',
+  dark: 'github-dark',
+} as const;
+
+const fallbackCodeLanguage = 'text';
+
+function resolveLanguage(language: unknown) {
+  if (typeof language !== 'string' || !language.trim()) {
+    return fallbackCodeLanguage;
+  }
+
+  const normalized = language.trim().toLowerCase();
+  if (Object.keys(bundledLanguages).includes(normalized)) {
+    return normalized as BundledLanguage;
+  }
+
+  return fallbackCodeLanguage;
+}
+
+function getTokenInlineStyle(token: {
+  variants?: Record<string, { color?: string }>;
+}) {
+  const lightColor = token.variants?.light?.color;
+  const darkColor = token.variants?.dark?.color;
+
+  if (!lightColor && !darkColor) {
+    return undefined;
+  }
+
+  const styles: string[] = [];
+  if (lightColor) styles.push(`--shiki-light: ${lightColor};`);
+  if (darkColor) styles.push(`--shiki-dark: ${darkColor}`);
+
+  return styles.join();
+}
+
+/**
+ * 使用 Shiki 为单个代码块生成 ProseMirror 装饰器
+ *
+ * @param code - 代码块的文本内容
+ * @param lang - 代码语言
+ * @param pos - 代码块在文档中的绝对起始位置
+ * @returns 解析生成的高亮装饰器数组
+ */
+async function getDecorationsForCodeBlock(
+  code: string,
+  lang: Language,
+  pos: number,
+): Promise<Decoration[]> {
+  const decorations: Decoration[] = [];
+  if (lang === 'text') {
+    return decorations;
+  }
+
+  try {
+    const tokenizedLines = await codeToTokensWithThemes(code, { lang, themes });
+
+    for (const line of tokenizedLines) {
+      for (const token of line) {
+        const content = token.content ?? '';
+        if (!content) continue;
+
+        const style = getTokenInlineStyle(token);
+        if (!style) continue;
+
+        // 计算 token 在 ProseMirror 中的绝对位置
+        const from = pos + 1 + token.offset;
+        const to = from + content.length;
+        decorations.push(Decoration.inline(from, to, { style }));
+      }
+    }
+  } catch {
+    // 如果 Shiki 无法进行 tokenize（未知语言等），则回退到纯文本
+  }
+
+  return decorations;
+}
+
+async function buildDecorationsForDoc(doc: import('@tiptap/pm/model').Node) {
+  // 遍历整个 doc，为所有 codeBlock 生成高亮 Decorations。
+  // 注意：tokenize 是重操作，所以这里采用异步 + 合并 Promise 的方式。
+  const tasks: Array<Promise<Decoration[]>> = [];
+
+  doc.descendants((node, pos) => {
+    if (node.type.name !== 'codeBlock') return;
+
+    const code = node.textContent;
+    const lang = resolveLanguage(node.attrs.language);
+
+    tasks.push(getDecorationsForCodeBlock(code, lang, pos));
+  });
+
+  const results = await Promise.all(tasks);
+  return DecorationSet.create(doc, results.flat());
+}
+
+function CodeBlockShikiNodeView(props: NodeViewProps) {
+  const code = props.node.textContent;
+  const lines = React.useMemo(() => {
+    const split = code.split('\n');
+    return split.length ? split : [''];
+  }, [code]);
+
+  return (
+    <NodeViewWrapper className={cn('not-prose my-3')}>
+      <div
+        className={cn(
+          'flex flex-col gap-2 rounded-md border border-border bg-muted/30 p-3',
+        )}
+      >
+        <div className="text-xs text-muted-foreground select-none">代码块</div>
+
+        <div className="flex items-start gap-2 overflow-x-auto">
+          <div className="shrink-0 select-none">
+            {lines.map((_, index) => (
+              <div
+                key={index}
+                className={cn(
+                  'w-4 text-center font-mono text-xs/5 text-muted-foreground select-none',
+                )}
+              >
+                {index + 1}
+              </div>
+            ))}
+          </div>
+
+          <pre
+            className={cn(
+              'shiki m-0 flex-1 bg-transparent p-0 font-mono text-xs/5 text-foreground',
+              '[&_span]:text-(--shiki-light) dark:[&_span]:text-(--shiki-dark)',
+            )}
+          >
+            <CodeNodeViewContent
+              as="code"
+              className="block min-w-max whitespace-pre"
+              style={{ whiteSpace: 'pre' }}
+            />
+          </pre>
+        </div>
+      </div>
+    </NodeViewWrapper>
+  );
+}
+
+export const CodeBlockShiki = CodeBlock.extend({
+  addNodeView() {
+    return ReactNodeViewRenderer(CodeBlockShikiNodeView);
+  },
+
+  addProseMirrorPlugins() {
+    const basePlugins = this.parent?.() ?? [];
+
+    const highlightPlugin = new Plugin<DecorationSet>({
+      key: codeBlockShikiPluginKey,
+      state: {
+        init: () => DecorationSet.empty,
+        apply: (tr, previous) => {
+          const meta = tr.getMeta(codeBlockShikiPluginKey) as
+            | { decorations?: DecorationSet }
+            | undefined;
+
+          if (meta?.decorations) return meta.decorations;
+          if (tr.docChanged) return previous.map(tr.mapping, tr.doc);
+          return previous;
+        },
+      },
+      props: {
+        decorations(state) {
+          return codeBlockShikiPluginKey.getState(state) ?? undefined;
+        },
+      },
+      view: (view) => {
+        const schedule = debounce(async () => {
+          const snapshotDoc = view.state.doc;
+          try {
+            const decorations = await buildDecorationsForDoc(snapshotDoc);
+            if (!view.state.doc.eq(snapshotDoc)) return;
+            const tr = view.state.tr.setMeta(codeBlockShikiPluginKey, {
+              decorations,
+            });
+            view.dispatch(tr);
+          } catch {
+            // ignore
+          }
+        }, 150);
+
+        schedule();
+
+        return {
+          update: (_view, prevState) => {
+            const docChanged = !prevState.doc.eq(view.state.doc);
+
+            if (docChanged) {
+              schedule();
+            }
+          },
+          destroy: () => {
+            schedule.cancel();
+          },
+        };
+      },
+    });
+
+    return [...basePlugins, highlightPlugin];
+  },
+});

package/template/client/src/components/business-ui/tiptap-editor/extensions/complete-kit.ts

@@ -0,0 +1,260 @@
+import { Extension } from '@tiptap/core';
+import Color, { type ColorOptions } from '@tiptap/extension-color';
+import Highlight, { type HighlightOptions } from '@tiptap/extension-highlight';
+import type { LinkOptions } from '@tiptap/extension-link';
+import Placeholder, {
+  type PlaceholderOptions,
+} from '@tiptap/extension-placeholder';
+import TaskItem, { type TaskItemOptions } from '@tiptap/extension-task-item';
+import TaskList, { type TaskListOptions } from '@tiptap/extension-task-list';
+import TextAlign, { type TextAlignOptions } from '@tiptap/extension-text-align';
+import { TextStyle, type TextStyleOptions } from '@tiptap/extension-text-style';
+import StarterKit, { type StarterKitOptions } from '@tiptap/starter-kit';
+
+import {
+  Attachment,
+  type AttachmentExtensionOptions,
+} from '@/components/business-ui/tiptap-editor/extensions/attachment';
+import { CodeBlockShiki } from '@/components/business-ui/tiptap-editor/extensions/code-block-shiki';
+import {
+  Image,
+  type ImageOptions,
+} from '@/components/business-ui/tiptap-editor/extensions/image';
+
+/**
+ * 从 StarterKitOptions 中排除不需要单独配置的选项
+ */
+type StarterKitBaseOptions = Omit<
+  StarterKitOptions,
+  'heading' | 'link' | 'codeBlock'
+>;
+
+export interface CompleteKitOptions extends StarterKitBaseOptions {
+  // #region 块级扩展
+  /**
+   * Heading 配置。设置为 false 禁用。
+   * @default { levels: [1, 2, 3, 4, 5, 6] }
+   */
+  heading: StarterKitOptions['heading'];
+
+  /**
+   * CodeBlock (Shiki 语法高亮) 配置。设置为 false 禁用。
+   * 注意：此扩展使用 CodeBlockShiki 替代官方 CodeBlock。
+   */
+  codeBlock: false;
+  // #endregion
+
+  // #region 行内标记扩展
+  /**
+   * Link 配置。设置为 false 禁用。
+   * @default { autolink: true, openOnClick: true }
+   */
+  link: Partial<LinkOptions> | false;
+  // #endregion
+
+  // #region 列表扩展
+  /**
+   * TaskList 配置。设置为 false 禁用。
+   */
+  taskList: Partial<TaskListOptions> | false;
+
+  /**
+   * TaskItem 配置。设置为 false 禁用。
+   * @default { nested: true }
+   */
+  taskItem: Partial<TaskItemOptions> | false;
+  // #endregion
+
+  // #region 样式扩展
+  /**
+   * TextStyle 配置。设置为 false 禁用。
+   */
+  textStyle: Partial<TextStyleOptions> | false;
+
+  /**
+   * Color 配置。设置为 false 禁用。
+   */
+  color: Partial<ColorOptions> | false;
+
+  /**
+   * Highlight 配置。设置为 false 禁用。
+   * @default { multicolor: true }
+   */
+  highlight: Partial<HighlightOptions> | false;
+
+  /**
+   * TextAlign 配置。设置为 false 禁用。
+   * @default { types: ["heading", "paragraph"] }
+   */
+  textAlign: Partial<TextAlignOptions> | false;
+  // #endregion
+
+  // #region 媒体扩展
+  /**
+   * Image 配置。设置为 false 禁用。
+   */
+  image: Partial<ImageOptions> | false;
+
+  /**
+   * Attachment 配置。设置为 false 禁用。
+   */
+  attachment: Partial<AttachmentExtensionOptions> | false;
+  // #endregion
+
+  // #region 其他扩展
+  /**
+   * Placeholder 配置。设置为 false 禁用。
+   * @default { placeholder: "请输入..." }
+   */
+  placeholder: Partial<PlaceholderOptions> | false;
+  // #endregion
+}
+
+/**
+ * CompleteKit 是一个完整的编辑器扩展集合。
+ *
+ * 它是构建富文本编辑器的良好起点，包含了所有常用的编辑功能。
+ *
+ * @example
+ * ```ts
+ * // 使用默认配置
+ * const editor = useEditor({
+ *   extensions: [CompleteKit],
+ * })
+ *
+ * // 自定义配置
+ * const editor = useEditor({
+ *   extensions: [
+ *     CompleteKit.configure({
+ *       // 禁用 image 扩展
+ *       image: false,
+ *       // 自定义 placeholder
+ *       placeholder: { placeholder: "开始输入..." },
+ *       // 自定义 heading
+ *       heading: { levels: [1, 2, 3] },
+ *       // 禁用 link
+ *       link: false,
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export const CompleteKit = Extension.create<CompleteKitOptions>({
+  name: 'completeKit',
+
+  addExtensions() {
+    const extensions = [];
+
+    // StarterKit 基础扩展（排除 heading、link、codeBlock）
+    const starterKitOptions: Partial<StarterKitOptions> = {
+      // 将顶级选项映射到 StarterKit
+      blockquote: this.options.blockquote,
+      bold: this.options.bold,
+      bulletList: this.options.bulletList,
+      code: this.options.code,
+      document: this.options.document,
+      dropcursor: this.options.dropcursor,
+      gapcursor: this.options.gapcursor,
+      hardBreak: this.options.hardBreak,
+      horizontalRule: this.options.horizontalRule,
+      italic: this.options.italic,
+      listItem: this.options.listItem,
+      listKeymap: this.options.listKeymap,
+      orderedList: this.options.orderedList,
+      paragraph: this.options.paragraph,
+      strike: this.options.strike,
+      text: this.options.text,
+      trailingNode: this.options.trailingNode,
+      underline: this.options.underline,
+      undoRedo: this.options.undoRedo,
+      // 默认禁用 StarterKit 的 codeBlock，使用 CodeBlockShiki 替代
+      codeBlock: false,
+      // 配置 heading
+      heading:
+        this.options.heading !== false
+          ? {
+              levels: [1, 2, 3, 4, 5, 6],
+              ...this.options.heading,
+            }
+          : false,
+      // 配置 link
+      link:
+        this.options.link !== false
+          ? {
+              autolink: true,
+              openOnClick: true,
+              ...this.options.link,
+            }
+          : false,
+    };
+
+    extensions.push(StarterKit.configure(starterKitOptions));
+
+    // CodeBlock (Shiki)
+    if (this.options.codeBlock !== false) {
+      extensions.push(CodeBlockShiki);
+    }
+
+    // TaskList & TaskItem
+    if (this.options.taskList !== false) {
+      extensions.push(TaskList.configure(this.options.taskList));
+    }
+
+    if (this.options.taskItem !== false) {
+      extensions.push(
+        TaskItem.configure({
+          nested: true,
+          ...this.options.taskItem,
+        }),
+      );
+    }
+
+    // 样式扩展
+    if (this.options.textStyle !== false) {
+      extensions.push(TextStyle.configure(this.options.textStyle));
+    }
+
+    if (this.options.color !== false) {
+      extensions.push(Color.configure(this.options.color));
+    }
+
+    if (this.options.highlight !== false) {
+      extensions.push(
+        Highlight.configure({
+          multicolor: true,
+          ...this.options.highlight,
+        }),
+      );
+    }
+
+    if (this.options.textAlign !== false) {
+      extensions.push(
+        TextAlign.configure({
+          types: ['heading', 'paragraph'],
+          ...this.options.textAlign,
+        }),
+      );
+    }
+
+    // 媒体扩展
+    if (this.options.image !== false) {
+      extensions.push(Image.configure(this.options.image));
+    }
+
+    if (this.options.attachment !== false) {
+      extensions.push(Attachment.configure(this.options.attachment));
+    }
+
+    // 其他扩展
+    if (this.options.placeholder !== false) {
+      extensions.push(
+        Placeholder.configure({
+          placeholder: '请输入...',
+          ...this.options.placeholder,
+        }),
+      );
+    }
+
+    return extensions;
+  },
+});