c063 1.4.9 → 1.6.0

package/dist/components/CodeBlock.d.ts

@@ -11,6 +11,6 @@ import { CodeBlockProps } from "../types/index";
  * @returns JSX 元素，呈現語法高亮的程式碼區塊
  */
 export declare const CodeBlock: {
-    <T extends React.ElementType = "span">({ tokenLines, showLineNumbers, lineNumberStyle, theme, ...rest }: CodeBlockProps<T>): import("react/jsx-runtime").JSX.Element;
+    <T extends React.ElementType = "span">({ tokenLines, showLineNumbers, lineNumberStyle, autoWrap, theme, ...rest }: CodeBlockProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/components/CodeBlock.js

@@ -11,14 +11,15 @@ import { CodeLine } from "./CodeLine";
  * @param rest 其他傳遞給 <pre> 的屬性
  * @returns JSX 元素，呈現語法高亮的程式碼區塊
  */
-export const CodeBlock = ({ tokenLines, showLineNumbers = true, lineNumberStyle, theme, ...rest }) => {
-    return (_jsx("pre", { ...rest, children: tokenLines.map((line, index) => (
-        // eslint-disable-next-line react/react-in-jsx-scope
-        _jsxs("div", { style: {
-                display: "flex",
-                flexWrap: "nowrap",
-                width: "100%",
-                gap: "0.5rem",
-            }, children: [showLineNumbers && (_jsx("span", { style: { color: "#888", userSelect: "none", ...lineNumberStyle }, children: index + 1 })), _jsx(CodeLine, { theme: theme, tokens: line })] }, index))) }));
+export const CodeBlock = ({ tokenLines, showLineNumbers = true, lineNumberStyle, autoWrap, theme, ...rest }) => {
+    return (_jsx("pre", { ...rest, style: { margin: 0, padding: 0, overflowX: "auto" }, children: _jsx("table", { style: { borderCollapse: "collapse", width: "100%" }, children: _jsx("tbody", { children: tokenLines.map((line, index) => (_jsxs("tr", { children: [showLineNumbers && (_jsx("td", { style: {
+                                paddingInline: "0.5rem",
+                                textAlign: "right",
+                                whiteSpace: "pre",
+                                fontVariantNumeric: "tabular-nums",
+                                color: "#888",
+                                userSelect: "none",
+                                ...lineNumberStyle,
+                            }, children: index + 1 })), _jsx("td", { style: { width: "100%" }, children: _jsx(CodeLine, { theme: theme, tokens: line, autoWrap: autoWrap }) })] }, index))) }) }) }));
 };
 CodeBlock.displayName = "CodeBlock";

package/dist/components/CodeLine.d.ts

@@ -6,10 +6,11 @@ import { CodeLineProps } from "../types/index";
  * @param props.tokens 該行所包含的語法 token 陣列
  * @param props.style 自訂樣式，會與 whiteSpace: pre-wrap 合併
  * @param props.theme 主題
+ * @param prop.autoWrap 是否自動換行
  * @param rest 其他 HTMLAttributes
  * @returns JSX 元素，呈現語法 token 的單行程式碼
  */
 export declare const CodeLine: {
-    <T extends React.ElementType = "span">({ style, tokens, theme, ...rest }: CodeLineProps<T>): import("react/jsx-runtime").JSX.Element;
+    <T extends React.ElementType = "span">({ style, tokens, theme, autoWrap, ...rest }: CodeLineProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/components/CodeLine.js

@@ -7,12 +7,13 @@ import { CodeToken } from "./CodeToken";
  * @param props.tokens 該行所包含的語法 token 陣列
  * @param props.style 自訂樣式，會與 whiteSpace: pre-wrap 合併
  * @param props.theme 主題
+ * @param prop.autoWrap 是否自動換行
  * @param rest 其他 HTMLAttributes
  * @returns JSX 元素，呈現語法 token 的單行程式碼
  */
-export const CodeLine = ({ style, tokens, theme, ...rest }) => {
+export const CodeLine = ({ style, tokens, theme, autoWrap = true, ...rest }) => {
     return (_jsx("code", { ...rest, style: {
-            whiteSpace: "pre-wrap",
+            whiteSpace: autoWrap ? "pre-wrap" : "nowrap",
             ...style,
         }, children: tokens.map((token, index) => (_jsx(CodeToken, { theme: theme, ...token }, index))) }));
 };

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@ import { AsComponentProps, OverrideProps } from "./common";
  *
  * 類型分為以下幾大類：
  *
- * - `keyword1` / `keyword2`: 關鍵字，如 `const`、`return`、`import` 等，分顏色類別。
+ * - `keyword1` / `keyword2`: 關鍵字，如 `const`/`return`、`import` 等，分顏色類別。
  * - `string`: 字串常值，如 `'text'`、`"value"`。
  * - `number`: 數字常值，如 `123`、`3.14`。
  * - `comment`: 註解內容，如 `//`。
@@ -71,6 +71,11 @@ export type CodeLineProps<T extends React.ElementType> = OverrideProps<React.HTM
      * @default "vscode-dark"
      */
     theme?: CodeTheme;
+    /**
+     * 是否自動換行
+     * @default true
+     */
+    autoWrap?: boolean;
 }>;
 export type CodeBlockProps<T extends React.ElementType> = OverrideProps<React.HTMLAttributes<HTMLPreElement>, {
     /**
@@ -80,13 +85,13 @@ export type CodeBlockProps<T extends React.ElementType> = OverrideProps<React.HT
      * ```tsx
      * <CodeBlock tokenLines={[
      *   [
-     *     { type: "keyword-blue", children: "const" },
+     *     { type: "keyword1", children: "const" },
      *     { type: "variable", children: "x" },
      *     { type: "operator", children: "=" },
      *     { type: "number", children: "42" },
      *   ],
      *   [
-     *     { type: "keyword-purple", children: "return" },
+     *     { type: "keyword2", children: "return" },
      *     { type: "variable", children: "x" },
      *   ],
      * ]} />
@@ -109,8 +114,13 @@ export type CodeBlockProps<T extends React.ElementType> = OverrideProps<React.HT
     lineNumberStyle?: React.CSSProperties;
     /**
      * 語法主題名稱。
-     * @default "vscode-dark"
+     * @default "default-dark-modern"
      */
     theme?: CodeTheme;
+    /**
+     * 是否自動換行
+     * @default true
+     */
+    autoWrap?: boolean;
 }>;
 export type ParsableLanguage = (typeof parsableLanguages)[number];

package/dist/utils/index.d.ts

@@ -1,31 +1,56 @@
 import React from "react";
 import { CodeTokenBuilder, CodeTokenProps, CodeTokenType } from "../types";
 /**
- * 語法 token 的建構器集合，每個 key 對應一種語法類型（如 `keyword-blue`, `string`, `comment` 等），
- * 透過 Proxy 生成對應的 `CodeTokenBuilder`。
+ * `c063` 是一組語法高亮 token 建構器集合。
+ * 每個 key 對應一種語法分類（如 `keyword1`, `string`, `comment` 等），
+ * 回傳對應的 `CodeTokenProps` 物件。
  *
- * 使用方式：
+ * @example
  * ```tsx
- * c063.keyword1("const") // -> { type: "keyword1", children: "const" }
- * c063.string("'hello'", { as: "code" }) // 可自訂 as 或其他 props
+ * const keyword = c063.keyword1("const");
+ * const str = c063.string("'Hello'", { as: "code" });
  * ```
  *
- * @example
- * tokens.push(c063.keyword1("const"));
- * tokens.push(c063.string("'Hello'"));
- *
- * @returns 一個以 `CodeTokenType` 為 key 的建構器函式集合
+ * @returns 以 `CodeTokenType` 為 key 的建構器函式集合。
  */
 declare const c063: Record<CodeTokenType, CodeTokenBuilder>;
+export default c063;
 /**
- * 產生指定空白數量的 CodeToken，用於程式碼中的縮排或空格。
+ * 產生指定空白數量的 CodeToken，用於縮排、空格等用途。
  *
  * @param count 空白字元數，預設為 1
- * @returns `CodeTokenProps` 物件，type 為 "default"，children 為空白字串
+ * @returns type 為 `"default"`、內容為空格的 `CodeTokenProps`
  *
  * @example
+ * ```tsx
  * tokens.push(whiteSpace(2)); // -> { type: "default", children: "  " }
+ * ```
  */
 export declare const whiteSpace: (count?: number) => CodeTokenProps<"span">;
+/**
+ * 抽取單個 `CodeTokenProps` 的純文字內容。
+ *
+ * @param token 要處理的 token
+ * @returns 對應的文字內容
+ *
+ * @example
+ * ```tsx
+ * extractTokenContent(c063.keyword1("return")); // => "return"
+ * ```
+ */
 export declare const extractTokenContent: <T extends React.ElementType>(token: CodeTokenProps<T>) => string;
-export default c063;
+/**
+ * 判斷兩個 token 是否相等（type 與內容皆相同）。
+ *
+ * @param a 第一個 token
+ * @param b 第二個 token
+ * @returns 是否相等
+ */
+export declare const isTokenEqual: <T extends React.ElementType>(a: CodeTokenProps<T>, b: CodeTokenProps<T>) => boolean;
+/**
+ * 將 token 列表按語法類型分類。
+ *
+ * @param lines 二維陣列，每行為一組 token
+ * @returns 分組後的 token 映射，key 為 `CodeTokenType`
+ */
+export declare const groupTokensByType: <T extends React.ElementType>(lines: CodeTokenProps<T>[][]) => Record<CodeTokenType, CodeTokenProps<T>[]>;

package/dist/utils/index.js

@@ -1,22 +1,26 @@
 import React from "react";
 /**
- * 語法 token 的建構器集合，每個 key 對應一種語法類型（如 `keyword-blue`, `string`, `comment` 等），
- * 透過 Proxy 生成對應的 `CodeTokenBuilder`。
+ * `c063` 是一組語法高亮 token 建構器集合。
+ * 每個 key 對應一種語法分類（如 `keyword1`, `string`, `comment` 等），
+ * 回傳對應的 `CodeTokenProps` 物件。
  *
- * 使用方式：
+ * @example
  * ```tsx
- * c063.keyword1("const") // -> { type: "keyword1", children: "const" }
- * c063.string("'hello'", { as: "code" }) // 可自訂 as 或其他 props
+ * const keyword = c063.keyword1("const");
+ * const str = c063.string("'Hello'", { as: "code" });
  * ```
  *
- * @example
- * tokens.push(c063.keyword1("const"));
- * tokens.push(c063.string("'Hello'"));
- *
- * @returns 一個以 `CodeTokenType` 為 key 的建構器函式集合
+ * @returns 以 `CodeTokenType` 為 key 的建構器函式集合。
  */
 const c063 = new Proxy({}, {
     get: (_, prop) => {
+        /**
+         * 建立指定語法類型的 CodeToken。
+         *
+         * @param children 要包裹的 React 內容或字串
+         * @param props 可選的額外屬性，如 `as` 或 `className`
+         * @returns 一個 CodeToken 物件
+         */
         const builder = (children, props) => {
             return {
                 children,
@@ -27,39 +31,113 @@ const c063 = new Proxy({}, {
         return builder;
     },
 });
+export default c063;
 /**
- * 產生指定空白數量的 CodeToken，用於程式碼中的縮排或空格。
+ * 產生指定空白數量的 CodeToken，用於縮排、空格等用途。
  *
  * @param count 空白字元數，預設為 1
- * @returns `CodeTokenProps` 物件，type 為 "default"，children 為空白字串
+ * @returns type 為 `"default"`、內容為空格的 `CodeTokenProps`
  *
  * @example
+ * ```tsx
  * tokens.push(whiteSpace(2)); // -> { type: "default", children: "  " }
+ * ```
  */
 export const whiteSpace = (count = 1) => c063.default(" ".repeat(count));
+/**
+ * 遞迴抽取 ReactNode 中的純文字內容。
+ *
+ * @param children ReactNode，可以是字串、數字、JSX 元素、陣列等
+ * @returns 純文字內容字串
+ */
+const _extractReactNode = (children) => {
+    if (typeof children === "string")
+        return children;
+    if (typeof children === "number")
+        return children.toString();
+    if (Array.isArray(children))
+        return children.map(_extractReactNode).join("");
+    if (React.isValidElement(children)) {
+        return _extractReactNode(children.props.children);
+    }
+    if (typeof children === "object" && children !== null) {
+        return React.Children.toArray(children).map(_extractReactNode).join("");
+    }
+    return ""; // 如果 children 是 null 或 undefined，則返回空字串
+};
+/**
+ * 抽取單個 `CodeTokenProps` 的純文字內容。
+ *
+ * @param token 要處理的 token
+ * @returns 對應的文字內容
+ *
+ * @example
+ * ```tsx
+ * extractTokenContent(c063.keyword1("return")); // => "return"
+ * ```
+ */
 export const extractTokenContent = (token) => {
-    const _extract = (children) => {
-        if (typeof children === "string")
-            return children;
-        if (typeof children === "number")
-            return children.toString();
-        if (Array.isArray(children))
-            return children.map(_extract).join("");
-        if (React.isValidElement(children)) {
-            return _extract(children.props.children);
-        }
-        return ""; // 如果 children 是 null 或 undefined，則返回空字串
+    return _extractReactNode(token.children);
+};
+/**
+ * 判斷兩個 token 是否相等（type 與內容皆相同）。
+ *
+ * @param a 第一個 token
+ * @param b 第二個 token
+ * @returns 是否相等
+ */
+export const isTokenEqual = (a, b) => {
+    return a.type === b.type && extractTokenContent(a) === extractTokenContent(b);
+};
+/**
+ * 將 token 列表按語法類型分類。
+ *
+ * @param lines 二維陣列，每行為一組 token
+ * @returns 分組後的 token 映射，key 為 `CodeTokenType`
+ */
+export const groupTokensByType = (lines) => {
+    var _a;
+    const grouped = {
+        keyword1: [],
+        keyword2: [],
+        function: [],
+        string: [],
+        number: [],
+        comment: [],
+        type: [],
+        variable: [],
+        constant: [],
+        brackets1: [],
+        brackets2: [],
+        brackets3: [],
+        operator: [],
+        default: [],
     };
-    return _extract(token.children);
+    for (const token of lines.flat()) {
+        grouped[(_a = token.type) !== null && _a !== void 0 ? _a : "default"].push(token);
+    }
+    return grouped;
 };
-export default c063;
 /**
- * 待實現
+ * 待實作
+ * `parseTokens` 是語法解析器的代理集合，用來解析特定語言的程式碼字串。
+ *
+ * 每個 key 對應一種可解析語言（如 `"javascript"`、`"python"` 等），
+ * 傳入原始程式碼字串後，回傳解析後的 token 二維陣列（每行一組 token）。
+ *
+ *
+ * @example
+ * ```ts
+ * const tokens = parseTokens.javascript("const x = 1;");
+ * ```
+ *
+ * @returns 語法高亮用的 `CodeTokenProps` 二維陣列
  */
-const _parseTokens = new Proxy({}, {
+const parseTokens = new Proxy({}, {
     get: (_, prop) => {
         const parser = (content) => {
-            return [];
+            const result = [];
+            return result;
         };
         return parser;
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "c063",
-  "version": "1.4.9",
+  "version": "1.6.0",
   "description": "A React component for displaying code snippets with syntax highlighting.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/components/CodeBlock.tsx

@@ -1,5 +1,6 @@
 import { CodeBlockProps } from "../types/index";
 import { CodeLine } from "./CodeLine";
+
 /**
  * 顯示完整程式碼區塊，支援多行語法 token 與行號顯示。
  *
@@ -15,32 +16,38 @@ export const CodeBlock = <T extends React.ElementType = "span">({
   tokenLines,
   showLineNumbers = true,
   lineNumberStyle,
+  autoWrap,
   theme,
   ...rest
 }: CodeBlockProps<T>) => {
   return (
-    <pre {...rest}>
-      {tokenLines.map((line, index) => (
-        // eslint-disable-next-line react/react-in-jsx-scope
-        <div
-          key={index}
-          style={{
-            display: "flex",
-            flexWrap: "nowrap",
-            width: "100%",
-            gap: "0.5rem",
-          }}
-        >
-          {showLineNumbers && (
-            <span
-              style={{ color: "#888", userSelect: "none", ...lineNumberStyle }}
-            >
-              {index + 1}
-            </span>
-          )}
-          <CodeLine theme={theme} tokens={line} />
-        </div>
-      ))}
+    <pre {...rest} style={{ margin: 0, padding: 0, overflowX: "auto" }}>
+      <table style={{ borderCollapse: "collapse", width: "100%" }}>
+        <tbody>
+          {tokenLines.map((line, index) => (
+            <tr key={index}>
+              {showLineNumbers && (
+                <td
+                  style={{
+                    paddingInline: "0.5rem",
+                    textAlign: "right",
+                    whiteSpace: "pre",
+                    fontVariantNumeric: "tabular-nums",
+                    color: "#888",
+                    userSelect: "none",
+                    ...lineNumberStyle,
+                  }}
+                >
+                  {index + 1}
+                </td>
+              )}
+              <td style={{ width: "100%" }}>
+                <CodeLine theme={theme} tokens={line} autoWrap={autoWrap} />
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
     </pre>
   );
 };

package/src/components/CodeLine.tsx

@@ -6,7 +6,8 @@ import { CodeToken } from "./CodeToken";
  * @template T 元件渲染類型，例如 <code>、<span> 等
  * @param props.tokens 該行所包含的語法 token 陣列
  * @param props.style 自訂樣式，會與 whiteSpace: pre-wrap 合併
- * @param props.theme 主題 
+ * @param props.theme 主題
+ * @param prop.autoWrap 是否自動換行
  * @param rest 其他 HTMLAttributes
  * @returns JSX 元素，呈現語法 token 的單行程式碼
  */
@@ -14,13 +15,14 @@ export const CodeLine = <T extends React.ElementType = "span">({
   style,
   tokens,
   theme,
+  autoWrap = true,
   ...rest
 }: CodeLineProps<T>) => {
   return (
     <code
       {...rest}
       style={{
-        whiteSpace: "pre-wrap",
+        whiteSpace: autoWrap ? "pre-wrap" : "nowrap",
         ...style,
       }}
     >

package/src/types/{index.ts → index.tsx}

@@ -7,7 +7,7 @@ import { AsComponentProps, OverrideProps } from "./common";
  *
  * 類型分為以下幾大類：
  *
- * - `keyword1` / `keyword2`: 關鍵字，如 `const`、`return`、`import` 等，分顏色類別。
+ * - `keyword1` / `keyword2`: 關鍵字，如 `const`/`return`、`import` 等，分顏色類別。
  * - `string`: 字串常值，如 `'text'`、`"value"`。
  * - `number`: 數字常值，如 `123`、`3.14`。
  * - `comment`: 註解內容，如 `//`。
@@ -94,6 +94,12 @@ export type CodeLineProps<T extends React.ElementType> = OverrideProps<
      * @default "vscode-dark"
      */
     theme?: CodeTheme;
+
+    /**
+     * 是否自動換行
+     * @default true
+     */
+    autoWrap?: boolean;
   }
 >;
 
@@ -107,13 +113,13 @@ export type CodeBlockProps<T extends React.ElementType> = OverrideProps<
      * ```tsx
      * <CodeBlock tokenLines={[
      *   [
-     *     { type: "keyword-blue", children: "const" },
+     *     { type: "keyword1", children: "const" },
      *     { type: "variable", children: "x" },
      *     { type: "operator", children: "=" },
      *     { type: "number", children: "42" },
      *   ],
      *   [
-     *     { type: "keyword-purple", children: "return" },
+     *     { type: "keyword2", children: "return" },
      *     { type: "variable", children: "x" },
      *   ],
      * ]} />
@@ -137,9 +143,15 @@ export type CodeBlockProps<T extends React.ElementType> = OverrideProps<
     lineNumberStyle?: React.CSSProperties;
     /**
      * 語法主題名稱。
-     * @default "vscode-dark"
+     * @default "default-dark-modern"
      */
     theme?: CodeTheme;
+
+    /**
+     * 是否自動換行
+     * @default true
+     */
+    autoWrap?: boolean;
   }
 >;
 

package/src/utils/index.tsx

@@ -7,28 +7,32 @@ import {
 } from "../types";
 
 /**
- * 語法 token 的建構器集合，每個 key 對應一種語法類型（如 `keyword-blue`, `string`, `comment` 等），
- * 透過 Proxy 生成對應的 `CodeTokenBuilder`。
+ * `c063` 是一組語法高亮 token 建構器集合。
+ * 每個 key 對應一種語法分類（如 `keyword1`, `string`, `comment` 等），
+ * 回傳對應的 `CodeTokenProps` 物件。
  *
- * 使用方式：
+ * @example
  * ```tsx
- * c063.keyword1("const") // -> { type: "keyword1", children: "const" }
- * c063.string("'hello'", { as: "code" }) // 可自訂 as 或其他 props
+ * const keyword = c063.keyword1("const");
+ * const str = c063.string("'Hello'", { as: "code" });
  * ```
  *
- * @example
- * tokens.push(c063.keyword1("const"));
- * tokens.push(c063.string("'Hello'"));
- *
- * @returns 一個以 `CodeTokenType` 為 key 的建構器函式集合
+ * @returns 以 `CodeTokenType` 為 key 的建構器函式集合。
  */
 const c063 = new Proxy(
   {},
   {
     get: (_, prop: CodeTokenType) => {
+      /**
+       * 建立指定語法類型的 CodeToken。
+       *
+       * @param children 要包裹的 React 內容或字串
+       * @param props 可選的額外屬性，如 `as` 或 `className`
+       * @returns 一個 CodeToken 物件
+       */
       const builder = <T extends React.ElementType = "span">(
         children: React.ReactNode,
-        props: CodeTokenProps<T>
+        props?: CodeTokenProps<T>
       ) => {
         return {
           children,
@@ -40,45 +44,129 @@ const c063 = new Proxy(
     },
   }
 ) as Record<CodeTokenType, CodeTokenBuilder>;
+export default c063;
 
 /**
- * 產生指定空白數量的 CodeToken，用於程式碼中的縮排或空格。
+ * 產生指定空白數量的 CodeToken，用於縮排、空格等用途。
  *
  * @param count 空白字元數，預設為 1
- * @returns `CodeTokenProps` 物件，type 為 "default"，children 為空白字串
+ * @returns type 為 `"default"`、內容為空格的 `CodeTokenProps`
  *
  * @example
+ * ```tsx
  * tokens.push(whiteSpace(2)); // -> { type: "default", children: "  " }
+ * ```
  */
 export const whiteSpace = (count: number = 1): CodeTokenProps<"span"> =>
   c063.default(" ".repeat(count));
 
+/**
+ * 遞迴抽取 ReactNode 中的純文字內容。
+ *
+ * @param children ReactNode，可以是字串、數字、JSX 元素、陣列等
+ * @returns 純文字內容字串
+ */
+const _extractReactNode = (children: React.ReactNode): string => {
+  if (typeof children === "string") return children;
+  if (typeof children === "number") return children.toString();
+  if (Array.isArray(children)) return children.map(_extractReactNode).join("");
+  if (React.isValidElement(children)) {
+    return _extractReactNode((children as React.JSX.Element).props.children);
+  }
+  if (typeof children === "object" && children !== null) {
+    return React.Children.toArray(children).map(_extractReactNode).join("");
+  }
+
+  return ""; // 如果 children 是 null 或 undefined，則返回空字串
+};
+
+/**
+ * 抽取單個 `CodeTokenProps` 的純文字內容。
+ *
+ * @param token 要處理的 token
+ * @returns 對應的文字內容
+ *
+ * @example
+ * ```tsx
+ * extractTokenContent(c063.keyword1("return")); // => "return"
+ * ```
+ */
 export const extractTokenContent = <T extends React.ElementType>(
   token: CodeTokenProps<T>
 ): string => {
-  const _extract = (children: React.ReactNode): string => {
-    if (typeof children === "string") return children;
-    if (typeof children === "number") return children.toString();
-    if (Array.isArray(children)) return children.map(_extract).join("");
-    if (React.isValidElement(children)) {
-      return _extract((children as React.JSX.Element).props.children);
-    }
-    return ""; // 如果 children 是 null 或 undefined，則返回空字串
-  };
-  return _extract(token.children);
+  return _extractReactNode(token.children);
 };
 
-export default c063;
+/**
+ * 判斷兩個 token 是否相等（type 與內容皆相同）。
+ *
+ * @param a 第一個 token
+ * @param b 第二個 token
+ * @returns 是否相等
+ */
+export const isTokenEqual = <T extends React.ElementType>(
+  a: CodeTokenProps<T>,
+  b: CodeTokenProps<T>
+): boolean => {
+  return a.type === b.type && extractTokenContent(a) === extractTokenContent(b);
+};
 
 /**
- * 待實現
+ * 將 token 列表按語法類型分類。
+ *
+ * @param lines 二維陣列，每行為一組 token
+ * @returns 分組後的 token 映射，key 為 `CodeTokenType`
  */
-const _parseTokens = new Proxy(
+export const groupTokensByType = <T extends React.ElementType>(
+  lines: CodeTokenProps<T>[][]
+): Record<CodeTokenType, CodeTokenProps<T>[]> => {
+  const grouped: Record<CodeTokenType, CodeTokenProps<T>[]> = {
+    keyword1: [],
+    keyword2: [],
+    function: [],
+    string: [],
+    number: [],
+    comment: [],
+    type: [],
+    variable: [],
+    constant: [],
+    brackets1: [],
+    brackets2: [],
+    brackets3: [],
+    operator: [],
+    default: [],
+  };
+
+  for (const token of lines.flat()) {
+    grouped[token.type ?? "default"].push(token);
+  }
+
+  return grouped;
+};
+
+/**
+ * 待實作
+ * `parseTokens` 是語法解析器的代理集合，用來解析特定語言的程式碼字串。
+ *
+ * 每個 key 對應一種可解析語言（如 `"javascript"`、`"python"` 等），
+ * 傳入原始程式碼字串後，回傳解析後的 token 二維陣列（每行一組 token）。
+ *
+ *
+ * @example
+ * ```ts
+ * const tokens = parseTokens.javascript("const x = 1;");
+ * ```
+ *
+ * @returns 語法高亮用的 `CodeTokenProps` 二維陣列
+ */
+const parseTokens = new Proxy(
   {},
   {
     get: (_, prop: ParsableLanguage) => {
       const parser = (content: string): CodeTokenProps<"span">[][] => {
-        return [];
+        const result: CodeTokenProps<"span">[][] = [];
+
+        return result;
       };
       return parser;
     },