c063 1.1.7 → 1.3.0

package/README.md

@@ -1 +1 @@
-# Code.js
+# c063

package/dist/components/CodeBlock.d.ts

@@ -1,5 +1,15 @@
 import { CodeBlockProps } from "../types/props";
+/**
+ * 顯示完整程式碼區塊，支援多行語法 token 與行號顯示。
+ *
+ * @template T 元件渲染類型，預設為 <span>
+ * @param props.tokenLines 所有程式碼行的 token 陣列
+ * @param props.showLineNumbers 是否顯示行號，預設為 true
+ * @param props.lineNumberStyle 行號的自訂樣式
+ * @param rest 其他傳遞給 <pre> 的屬性
+ * @returns JSX 元素，呈現語法高亮的程式碼區塊
+ */
 export declare const CodeBlock: {
-    ({ tokenLines, showLineNumbers, lineNumberStyle, ...rest }: CodeBlockProps): import("react/jsx-runtime").JSX.Element;
+    <T extends React.ElementType = "span">({ tokenLines, showLineNumbers, lineNumberStyle, theme, ...rest }: CodeBlockProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/components/CodeBlock.js

@@ -1,11 +1,21 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CodeLine } from "./CodeLine";
-export const CodeBlock = ({ tokenLines, showLineNumbers = true, lineNumberStyle, ...rest }) => {
+/**
+ * 顯示完整程式碼區塊，支援多行語法 token 與行號顯示。
+ *
+ * @template T 元件渲染類型，預設為 <span>
+ * @param props.tokenLines 所有程式碼行的 token 陣列
+ * @param props.showLineNumbers 是否顯示行號，預設為 true
+ * @param props.lineNumberStyle 行號的自訂樣式
+ * @param rest 其他傳遞給 <pre> 的屬性
+ * @returns JSX 元素，呈現語法高亮的程式碼區塊
+ */
+export const CodeBlock = ({ tokenLines, showLineNumbers = true, lineNumberStyle, theme, ...rest }) => {
     return (_jsx("pre", { ...rest, children: tokenLines.map((line, index) => (_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, { tokens: line })] }, index))) }));
+            }, children: [showLineNumbers && (_jsx("span", { style: { color: "#888", userSelect: "none", ...lineNumberStyle }, children: index + 1 })), _jsx(CodeLine, { theme: theme, tokens: line })] }, index))) }));
 };
 CodeBlock.displayName = "CodeBlock";

package/dist/components/CodeLine.d.ts

@@ -1,5 +1,14 @@
 import { CodeLineProps } from "../types/props";
+/**
+ * 渲染單一程式碼行，包含多個語法 token。
+ *
+ * @template T 元件渲染類型，例如 <code>、<span> 等
+ * @param props.tokens 該行所包含的語法 token 陣列
+ * @param props.style 自訂樣式，會與 whiteSpace: pre-wrap 合併
+ * @param rest 其他 HTMLAttributes
+ * @returns JSX 元素，呈現語法 token 的單行程式碼
+ */
 export declare const CodeLine: {
-    ({ style, tokens, ...rest }: CodeLineProps): import("react/jsx-runtime").JSX.Element;
+    <T extends React.ElementType>({ style, tokens, theme, ...rest }: CodeLineProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/components/CodeLine.js

@@ -1,9 +1,18 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { CodeToken } from "./CodeToken";
-export const CodeLine = ({ style, tokens, ...rest }) => {
+/**
+ * 渲染單一程式碼行，包含多個語法 token。
+ *
+ * @template T 元件渲染類型，例如 <code>、<span> 等
+ * @param props.tokens 該行所包含的語法 token 陣列
+ * @param props.style 自訂樣式，會與 whiteSpace: pre-wrap 合併
+ * @param rest 其他 HTMLAttributes
+ * @returns JSX 元素，呈現語法 token 的單行程式碼
+ */
+export const CodeLine = ({ style, tokens, theme, ...rest }) => {
     return (_jsx("code", { ...rest, style: {
             whiteSpace: "pre-wrap",
             ...style,
-        }, children: tokens.map((token, index) => (_jsx(CodeToken, { ...token }, `${token.type}-${index}`))) }));
+        }, children: tokens.map((token, index) => (_jsx(CodeToken, { theme: theme, ...token }, `${token.type}-${index}`))) }));
 };
 CodeLine.displayName = "CodeLine";

package/dist/components/CodeToken.d.ts

@@ -1,5 +1,16 @@
 import { CodeTokenProps } from "../types/props";
+/**
+ * 渲染單一語法 token（例如關鍵字、字串、註解等），可指定標籤與樣式。
+ *
+ * @template T 元件渲染類型，預設為 <span>
+ * @param props.as 指定要渲染的 HTML 標籤或客製元件
+ * @param props.type 語法類型，用於對應不同顏色
+ * @param props.style 額外樣式，會與語法顏色合併
+ * @param props.children 顯示的程式碼字串
+ * @param rest 其他 HTML 屬性
+ * @returns JSX 元素，顯示帶有語法顏色的 token
+ */
 export declare const CodeToken: {
-    <T extends React.ElementType = "span">({ as, style, children, type, ...rest }: CodeTokenProps<T>): import("react/jsx-runtime").JSX.Element;
+    <T extends React.ElementType = "span">({ as, style, children, type, theme, ...rest }: CodeTokenProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/components/CodeToken.js

@@ -1,9 +1,20 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { codeColoreMap } from "../libs/codeColorMap";
-export const CodeToken = ({ as, style, children, type, ...rest }) => {
+import { themeMap } from "../libs";
+/**
+ * 渲染單一語法 token（例如關鍵字、字串、註解等），可指定標籤與樣式。
+ *
+ * @template T 元件渲染類型，預設為 <span>
+ * @param props.as 指定要渲染的 HTML 標籤或客製元件
+ * @param props.type 語法類型，用於對應不同顏色
+ * @param props.style 額外樣式，會與語法顏色合併
+ * @param props.children 顯示的程式碼字串
+ * @param rest 其他 HTML 屬性
+ * @returns JSX 元素，顯示帶有語法顏色的 token
+ */
+export const CodeToken = ({ as, style, children, type, theme, ...rest }) => {
     const Tag = as || "span";
     return (_jsx(Tag, { ...rest, style: {
-            color: codeColoreMap[type || "default"],
+            color: themeMap[theme || "default-dark-modern"][type || "default"],
             ...style,
         }, children: children }));
 };

package/dist/libs/default-dark-modern.d.ts

@@ -0,0 +1,2 @@
+import { CodeTokenType } from "../types";
+export declare const map: Record<CodeTokenType, React.CSSProperties["color"]>;

package/dist/libs/default-dark-modern.js

@@ -0,0 +1,15 @@
+export const map = {
+    keyword1: "#569cd6", // 深藍色關鍵字
+    keyword2: "#c586c0", // 紫色關鍵字
+    string: "#ce9178", // 淺棕色字串
+    number: "#b5cea8", // 淺綠色數字
+    comment: "#6a9955", // 綠色註解
+    variable: "#9cdcfe", // 藍色變數
+    constant: "#4fc1ff", // 藍色常數
+    type: "#4ec9b0", // 青綠色類型
+    brackets1: "#ffd700", // 金黃色括號層級1
+    brackets2: "#da70d6", // 紫羅蘭色括號層級2
+    brackets3: "#179fff", // 藍色括號層級3
+    operator: "#d4d4d4", // 淺灰色運算符
+    default: "#d4d4d4", // 淺灰色預設文字
+};

package/dist/libs/index.d.ts

@@ -1 +1,7 @@
-export { codeColoreMap } from "./codeColorMap";
+import type { CodeTokenType, CodeTheme } from "../types";
+export declare const themeRegistry: {
+    readonly "default-dark-modern": Record<CodeTokenType, import("csstype").Property.Color | undefined>;
+    readonly "visual-studio-light": Record<CodeTokenType, import("csstype").Property.Color | undefined>;
+};
+export declare const themes: (keyof typeof themeRegistry)[];
+export declare const themeMap: Record<CodeTheme, Record<CodeTokenType, React.CSSProperties["color"]>>;

package/dist/libs/index.js

@@ -1 +1,10 @@
-export { codeColoreMap } from "./codeColorMap";
+import { map as darkModern } from "./default-dark-modern";
+import { map as vsLight } from "./visual-studio-light";
+export const themeRegistry = {
+    "default-dark-modern": darkModern,
+    "visual-studio-light": vsLight,
+};
+// 自動推導主題名稱
+export const themes = Object.keys(themeRegistry);
+// themeMap 保留給外部使用
+export const themeMap = themeRegistry;

package/dist/libs/visual-studio-light.d.ts

@@ -0,0 +1,2 @@
+import { CodeTokenType } from "../types";
+export declare const map: Record<CodeTokenType, React.CSSProperties["color"]>;

package/dist/libs/visual-studio-light.js

@@ -0,0 +1,15 @@
+export const map = {
+    keyword1: "#0000ff",
+    keyword2: "#0000ff",
+    string: "#000000",
+    number: "#098658",
+    comment: "#008000",
+    variable: "#000000",
+    constant: "#000000",
+    type: "#000000",
+    brackets1: "#0431fa",
+    brackets2: "#319331",
+    brackets3: "#7b3814",
+    operator: "#000000",
+    default: "#000000",
+};

package/dist/types/common.d.ts

@@ -3,7 +3,7 @@ export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K
 /** 用於重載同名屬性（用於覆蓋類型 T 中與類型 P 相同名稱的屬性，並保留其餘屬性*/
 export type OverrideProps<T, P> = DistributiveOmit<T, keyof P> & P;
 /** 支援元件型別 (可複寫屬性)*/
-export type AsComponentProps<As extends React.ElementType, PermanentProps extends object = {}> = OverrideProps<React.ComponentPropsWithRef<As>, PermanentProps> & {
+export type AsComponentProps<T extends React.ElementType, P = {}> = OverrideProps<React.ComponentPropsWithRef<T>, P> & {
     /** 指定用於渲染的 React 元件（可為任意元件*/
-    as?: As;
+    as?: T;
 };

package/dist/types/props.d.ts

@@ -1,22 +1,58 @@
-import { AsComponentProps, DistributiveOmit, OverrideProps } from "./common";
-export type KeywordColorType = "blue" | "purple";
-export type CodeTokenType = `keyword-${KeywordColorType}` | "string" | "number" | "comment" | "type" | "variable" | "constant" | `brackets-${1 | 2 | 3}` | "operator" | "default";
+import { themes } from "../libs";
+import { AsComponentProps, OverrideProps } from "./common";
+/**
+ * 用於表示語法高亮中每個 token 的語意分類，對應於 `<CodeToken />` 中的 `type`。
+ *
+ * 每個類型會對應特定的顏色與用途，例如關鍵字、數字、字串、註解等，
+ * 可配合 `codeColoreMap` 指定顯示樣式。s
+ *
+ * 類型分為以下幾大類：
+ *
+ * - `keyword1` / `keyword2`: 關鍵字，如 `const`、`return`、`import` 等，分顏色類別。
+ * - `string`: 字串常值，如 `'text'`、`"value"`。
+ * - `number`: 數字常值，如 `123`、`3.14`。
+ * - `comment`: 註解內容，如 `//`。
+ * - `type`: 類型定義，如 `interface`、`enum`、`type`。
+ * - `variable`: 識別符號，如變數名、函式名、類別名。
+ * - `constant`: 常數或靜態值，如 `PI`、`MAX_VALUE`。
+ * - `brackets1`, `brackets2`, `brackets3`: 括號配對，區分不同層級的括號。
+ * - `operator`: 運算符，如 `=`, `+`, `===`, `<`, `>=`。
+ * - `default`: 其他符號，如 `;`, `,`, `.`, `?`, `"`, `'`。
+ *
+ * @example
+ * const token: CodeTokenType = "keyword1";
+ * const token2: CodeTokenType = "string";
+ */
+export type CodeTokenType = `keyword${1 | 2}` | "string" | "number" | "comment" | "type" | "variable" | "constant" | `brackets${1 | 2 | 3}` | "operator" | "default";
+/**
+ * 表示可用的語法高亮主題名稱。
+ * 對應 `themes` 陣列中定義的名稱，例如 `"vscode-dark"`。
+ *
+ * @example
+ * const theme: CodeTheme = "vscode-dark";
+ */
+export type CodeTheme = (typeof themes)[number];
 /**
  * 單一語法 token 的屬性，用於 <CodeToken /> 元件。
  *
  * @template T HTML 或客製元素，例如 span、a、Link 等
  */
-export type CodeTokenProps<T extends React.ElementType = React.ElementType> = AsComponentProps<T, {
+export type CodeTokenProps<T extends React.ElementType> = AsComponentProps<T, {
     /**
      * 語法 token 的語意類型，用於指定樣式顏色。
      */
     type?: CodeTokenType;
+    /**
+     * 語法主題名稱。
+     * @default "vscode-dark"
+     */
+    theme?: CodeTheme;
 }>;
-export type CodeTokenBuilder = <T extends React.ElementType>(children: CodeTokenProps<T>["children"] extends undefined ? React.ReactNode : CodeTokenProps<T>["children"], props?: DistributiveOmit<CodeTokenProps<T>, "type">) => CodeTokenProps<T>;
+export type CodeTokenBuilder = <T extends React.ElementType>(children: CodeTokenProps<T>["children"], props?: CodeTokenProps<T>) => CodeTokenProps<T>;
 /**
  * 用於單一程式碼行的屬性，用在 <CodeLine /> 或類似元件中。
  */
-export type CodeLineProps = OverrideProps<React.HTMLAttributes<HTMLElement>, {
+export type CodeLineProps<T extends React.ElementType> = OverrideProps<React.HTMLAttributes<HTMLElement>, {
     /**
      * 該行所包含的語法 token。
      *
@@ -30,9 +66,14 @@ export type CodeLineProps = OverrideProps<React.HTMLAttributes<HTMLElement>, {
      * ]} />
      * ```
      */
-    tokens: CodeTokenProps[];
+    tokens: CodeTokenProps<T>[];
+    /**
+     * 語法主題名稱。
+     * @default "vscode-dark"
+     */
+    theme?: CodeTheme;
 }>;
-export type CodeBlockProps = OverrideProps<React.HTMLAttributes<HTMLPreElement>, {
+export type CodeBlockProps<T extends React.ElementType> = OverrideProps<React.HTMLAttributes<HTMLPreElement>, {
     /**
      * 所有程式碼行的 token 陣列。
      *
@@ -52,7 +93,7 @@ export type CodeBlockProps = OverrideProps<React.HTMLAttributes<HTMLPreElement>,
      * ]} />
      * ```
      */
-    tokenLines: CodeTokenProps[][];
+    tokenLines: CodeTokenProps<T>[][];
     /**
      * 是否顯示行號。
      * @default true
@@ -67,4 +108,9 @@ export type CodeBlockProps = OverrideProps<React.HTMLAttributes<HTMLPreElement>,
      * ```
      * */
     lineNumberStyle?: React.CSSProperties;
+    /**
+     * 語法主題名稱。
+     * @default "vscode-dark"
+     */
+    theme?: CodeTheme;
 }>;

package/dist/utils/index.d.ts

@@ -1,3 +1,28 @@
 import { CodeTokenBuilder, CodeTokenProps, CodeTokenType } from "../types";
-export declare const createToken: Record<CodeTokenType, CodeTokenBuilder>;
-export declare const whiteSpace: (count?: number) => CodeTokenProps;
+/**
+ * 語法 token 的建構器集合，每個 key 對應一種語法類型（如 `keyword-blue`, `string`, `comment` 等），
+ * 透過 Proxy 生成對應的 `CodeTokenBuilder`。
+ *
+ * 使用方式：
+ * ```tsx
+ * c063["keyword-blue"]("const") // -> { type: "keyword-blue", children: "const" }
+ * c063["string"]("'hello'", { as: "code" }) // 可自訂 as 或其他 props
+ * ```
+ *
+ * @example
+ * tokens.push(c063["keyword-blue"]("const"));
+ * tokens.push(c063.string("'Hello'"));
+ *
+ * @returns 一個以 `CodeTokenType` 為 key 的建構器函式集合
+ */
+export declare const c063: Record<CodeTokenType, CodeTokenBuilder>;
+/**
+ * 產生指定空白數量的 CodeToken，用於程式碼中的縮排或空格。
+ *
+ * @param count 空白字元數，預設為 1
+ * @returns `CodeTokenProps` 物件，type 為 "default"，children 為空白字串
+ *
+ * @example
+ * tokens.push(whiteSpace(2)); // -> { type: "default", children: "  " }
+ */
+export declare const whiteSpace: (count?: number) => CodeTokenProps<"span">;

package/dist/utils/index.js

@@ -1,16 +1,38 @@
-export const createToken = new Proxy({}, {
+/**
+ * 語法 token 的建構器集合，每個 key 對應一種語法類型（如 `keyword-blue`, `string`, `comment` 等），
+ * 透過 Proxy 生成對應的 `CodeTokenBuilder`。
+ *
+ * 使用方式：
+ * ```tsx
+ * c063["keyword-blue"]("const") // -> { type: "keyword-blue", children: "const" }
+ * c063["string"]("'hello'", { as: "code" }) // 可自訂 as 或其他 props
+ * ```
+ *
+ * @example
+ * tokens.push(c063["keyword-blue"]("const"));
+ * tokens.push(c063.string("'Hello'"));
+ *
+ * @returns 一個以 `CodeTokenType` 為 key 的建構器函式集合
+ */
+export const c063 = new Proxy({}, {
     get: (_, prop) => {
         const builder = (children, props) => {
             return {
-                type: prop,
                 children,
+                type: prop,
                 ...props,
             };
         };
         return builder;
     },
 });
-export const whiteSpace = (count = 1) => ({
-    type: "default",
-    children: " ".repeat(count),
-});
+/**
+ * 產生指定空白數量的 CodeToken，用於程式碼中的縮排或空格。
+ *
+ * @param count 空白字元數，預設為 1
+ * @returns `CodeTokenProps` 物件，type 為 "default"，children 為空白字串
+ *
+ * @example
+ * tokens.push(whiteSpace(2)); // -> { type: "default", children: "  " }
+ */
+export const whiteSpace = (count = 1) => c063.default(" ".repeat(count));

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "c063",
-  "version": "1.1.7",
+  "version": "1.3.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,12 +1,22 @@
 import { CodeBlockProps } from "../types/props";
 import { CodeLine } from "./CodeLine";
-
-export const CodeBlock = ({
+/**
+ * 顯示完整程式碼區塊，支援多行語法 token 與行號顯示。
+ *
+ * @template T 元件渲染類型，預設為 <span>
+ * @param props.tokenLines 所有程式碼行的 token 陣列
+ * @param props.showLineNumbers 是否顯示行號，預設為 true
+ * @param props.lineNumberStyle 行號的自訂樣式
+ * @param rest 其他傳遞給 <pre> 的屬性
+ * @returns JSX 元素，呈現語法高亮的程式碼區塊
+ */
+export const CodeBlock = <T extends React.ElementType = "span">({
   tokenLines,
   showLineNumbers = true,
   lineNumberStyle,
+  theme,
   ...rest
-}: CodeBlockProps) => {
+}: CodeBlockProps<T>) => {
   return (
     <pre {...rest}>
       {tokenLines.map((line, index) => (
@@ -19,7 +29,6 @@ export const CodeBlock = ({
             gap: "0.5rem",
           }}
         >
-          {/* 如果需要顯示行號，則在每行前添加行號 */}
           {showLineNumbers && (
             <span
               style={{ color: "#888", userSelect: "none", ...lineNumberStyle }}
@@ -27,7 +36,7 @@ export const CodeBlock = ({
               {index + 1}
             </span>
           )}
-          <CodeLine tokens={line} />
+          <CodeLine theme={theme} tokens={line} />
         </div>
       ))}
     </pre>

package/src/components/CodeLine.tsx

@@ -1,7 +1,20 @@
 import { CodeLineProps } from "../types/props";
 import { CodeToken } from "./CodeToken";
-
-export const CodeLine = ({ style, tokens, ...rest }: CodeLineProps) => {
+/**
+ * 渲染單一程式碼行，包含多個語法 token。
+ *
+ * @template T 元件渲染類型，例如 <code>、<span> 等
+ * @param props.tokens 該行所包含的語法 token 陣列
+ * @param props.style 自訂樣式，會與 whiteSpace: pre-wrap 合併
+ * @param rest 其他 HTMLAttributes
+ * @returns JSX 元素，呈現語法 token 的單行程式碼
+ */
+export const CodeLine = <T extends React.ElementType>({
+  style,
+  tokens,
+  theme,
+  ...rest
+}: CodeLineProps<T>) => {
   return (
     <code
       {...rest}
@@ -11,7 +24,7 @@ export const CodeLine = ({ style, tokens, ...rest }: CodeLineProps) => {
       }}
     >
       {tokens.map((token, index) => (
-        <CodeToken key={`${token.type}-${index}`} {...token} />
+        <CodeToken key={`${token.type}-${index}`} theme={theme} {...token} />
       ))}
     </code>
   );

package/src/components/CodeToken.tsx

@@ -1,11 +1,22 @@
-import { codeColoreMap } from "../libs/codeColorMap";
+import { themeMap } from "../libs";
 import { CodeTokenProps } from "../types/props";
-
+/**
+ * 渲染單一語法 token（例如關鍵字、字串、註解等），可指定標籤與樣式。
+ *
+ * @template T 元件渲染類型，預設為 <span>
+ * @param props.as 指定要渲染的 HTML 標籤或客製元件
+ * @param props.type 語法類型，用於對應不同顏色
+ * @param props.style 額外樣式，會與語法顏色合併
+ * @param props.children 顯示的程式碼字串
+ * @param rest 其他 HTML 屬性
+ * @returns JSX 元素，顯示帶有語法顏色的 token
+ */
 export const CodeToken = <T extends React.ElementType = "span">({
   as,
   style,
   children,
   type,
+  theme,
   ...rest
 }: CodeTokenProps<T>) => {
   const Tag = as || "span";
@@ -14,7 +25,7 @@ export const CodeToken = <T extends React.ElementType = "span">({
     <Tag
       {...rest}
       style={{
-        color: codeColoreMap[type || "default"],
+        color: themeMap[theme || "default-dark-modern"][type || "default"],
         ...style,
       }}
     >

package/src/libs/default-dark-modern.tsx

@@ -0,0 +1,17 @@
+import { CodeTokenType } from "../types";
+
+export const map: Record<CodeTokenType, React.CSSProperties["color"]> = {
+  keyword1: "#569cd6", // 深藍色關鍵字
+  keyword2: "#c586c0", // 紫色關鍵字
+  string: "#ce9178", // 淺棕色字串
+  number: "#b5cea8", // 淺綠色數字
+  comment: "#6a9955", // 綠色註解
+  variable: "#9cdcfe", // 藍色變數
+  constant: "#4fc1ff", // 藍色常數
+  type: "#4ec9b0", // 青綠色類型
+  brackets1: "#ffd700", // 金黃色括號層級1
+  brackets2: "#da70d6", // 紫羅蘭色括號層級2
+  brackets3: "#179fff", // 藍色括號層級3
+  operator: "#d4d4d4", // 淺灰色運算符
+  default: "#d4d4d4", // 淺灰色預設文字
+};

package/src/libs/index.tsx

@@ -0,0 +1,19 @@
+import type { CodeTokenType, CodeTheme } from "../types";
+import { map as darkModern } from "./default-dark-modern";
+import { map as vsLight } from "./visual-studio-light";
+
+export const themeRegistry = {
+  "default-dark-modern": darkModern,
+  "visual-studio-light": vsLight,
+} as const;
+
+// 自動推導主題名稱
+export const themes = Object.keys(
+  themeRegistry
+) as (keyof typeof themeRegistry)[];
+
+// themeMap 保留給外部使用
+export const themeMap: Record<
+  CodeTheme,
+  Record<CodeTokenType, React.CSSProperties["color"]>
+> = themeRegistry;

package/src/libs/visual-studio-light.tsx

@@ -0,0 +1,17 @@
+import { CodeTokenType } from "../types";
+
+export const map: Record<CodeTokenType, React.CSSProperties["color"]> = {
+  keyword1: "#0000ff",
+  keyword2: "#0000ff",
+  string: "#000000",
+  number: "#098658",
+  comment: "#008000",
+  variable: "#000000",
+  constant: "#000000",
+  type: "#000000",
+  brackets1: "#0431fa",
+  brackets2: "#319331",
+  brackets3: "#7b3814",
+  operator: "#000000",
+  default: "#000000",
+};

package/src/types/common.tsx

@@ -8,9 +8,9 @@ export type OverrideProps<T, P> = DistributiveOmit<T, keyof P> & P;
 
 /** 支援元件型別 (可複寫屬性)*/
 export type AsComponentProps<
-  As extends React.ElementType,
-  PermanentProps extends object = {}
-> = OverrideProps<React.ComponentPropsWithRef<As>, PermanentProps> & {
+  T extends React.ElementType,
+  P = {}
+> = OverrideProps<React.ComponentPropsWithRef<T>, P> & {
   /** 指定用於渲染的 React 元件（可為任意元件*/
-  as?: As;
+  as?: T;
 };

package/src/types/index.ts

@@ -1,2 +1,2 @@
 export * from "./common";
-export * from "./props";
+export * from "./props";

package/src/types/props.tsx

@@ -1,48 +1,78 @@
-import { AsComponentProps, DistributiveOmit, OverrideProps } from "./common";
-
-export type KeywordColorType =
-  | "blue" // const, let, function, if, else class type
-  | "purple"; // import, export, from, as ,return
-
+import { themes } from "../libs";
+import { AsComponentProps, OverrideProps } from "./common";
+/**
+ * 用於表示語法高亮中每個 token 的語意分類，對應於 `<CodeToken />` 中的 `type`。
+ *
+ * 每個類型會對應特定的顏色與用途，例如關鍵字、數字、字串、註解等，
+ * 可配合 `codeColoreMap` 指定顯示樣式。s
+ *
+ * 類型分為以下幾大類：
+ *
+ * - `keyword1` / `keyword2`: 關鍵字，如 `const`、`return`、`import` 等，分顏色類別。
+ * - `string`: 字串常值，如 `'text'`、`"value"`。
+ * - `number`: 數字常值，如 `123`、`3.14`。
+ * - `comment`: 註解內容，如 `//`。
+ * - `type`: 類型定義，如 `interface`、`enum`、`type`。
+ * - `variable`: 識別符號，如變數名、函式名、類別名。
+ * - `constant`: 常數或靜態值，如 `PI`、`MAX_VALUE`。
+ * - `brackets1`, `brackets2`, `brackets3`: 括號配對，區分不同層級的括號。
+ * - `operator`: 運算符，如 `=`, `+`, `===`, `<`, `>=`。
+ * - `default`: 其他符號，如 `;`, `,`, `.`, `?`, `"`, `'`。
+ *
+ * @example
+ * const token: CodeTokenType = "keyword1";
+ * const token2: CodeTokenType = "string";
+ */
 export type CodeTokenType =
-  | `keyword-${KeywordColorType}`
-  | "string" // string
-  | "number" // number
-  | "comment" // comment ex: //, /* */, /** */
-  | "type" // type, interface, enum
-  | "variable" // variable, function name, class name, method name
-  | "constant" // constant, enum value, static property
-  | `brackets-${1 | 2 | 3}` // (), [], {}, <>, (), [], {}, <
-  | "operator" // +, -, *, /, %, =, ==, ===, !=, !==, <, >, <=, >=
-  | "default"; // ., ,, ;, :, ?, !, @, #, $, %, ^, &, *, (, ), [, ], {, }, <, >, /, \, |, \", ', `;
+  | `keyword${1 | 2}` // 關鍵字，分兩種樣式層級
+  | "string" // 字串常值：'abc'、"hello"
+  | "number" // 數值常量：123、3.14
+  | "comment" // 註解內容：// 或 /* */
+  | "type" // 類型定義：type、interface、enum
+  | "variable" // 變數名、函式名、類別名等識別符號
+  | "constant" // 常數值：例如 enum 值、靜態屬性
+  | `brackets${1 | 2 | 3}` // 括號配對，三層不同樣式：(), [], {}
+  | "operator" // 運算符號：=、+、*、===、<、>= 等
+  | "default"; // 其他符號：, ; . ? ! 等
+
+/**
+ * 表示可用的語法高亮主題名稱。
+ * 對應 `themes` 陣列中定義的名稱，例如 `"vscode-dark"`。
+ *
+ * @example
+ * const theme: CodeTheme = "vscode-dark";
+ */
+export type CodeTheme = (typeof themes)[number];
 
 /**
  * 單一語法 token 的屬性，用於 <CodeToken /> 元件。
  *
  * @template T HTML 或客製元素，例如 span、a、Link 等
  */
-export type CodeTokenProps<T extends React.ElementType = React.ElementType> =
-  AsComponentProps<
-    T,
-    {
-      /**
-       * 語法 token 的語意類型，用於指定樣式顏色。
-       */
-      type?: CodeTokenType;
-    }
-  >;
+export type CodeTokenProps<T extends React.ElementType> = AsComponentProps<
+  T,
+  {
+    /**
+     * 語法 token 的語意類型，用於指定樣式顏色。
+     */
+    type?: CodeTokenType;
+    /**
+     * 語法主題名稱。
+     * @default "vscode-dark"
+     */
+    theme?: CodeTheme;
+  }
+>;
 
 export type CodeTokenBuilder = <T extends React.ElementType>(
-  children: CodeTokenProps<T>["children"] extends undefined
-    ? React.ReactNode
-    : CodeTokenProps<T>["children"],
-  props?: DistributiveOmit<CodeTokenProps<T>, "type">
+  children: CodeTokenProps<T>["children"],
+  props?: CodeTokenProps<T>
 ) => CodeTokenProps<T>;
 
 /**
  * 用於單一程式碼行的屬性，用在 <CodeLine /> 或類似元件中。
  */
-export type CodeLineProps = OverrideProps<
+export type CodeLineProps<T extends React.ElementType> = OverrideProps<
   React.HTMLAttributes<HTMLElement>,
   {
     /**
@@ -58,11 +88,16 @@ export type CodeLineProps = OverrideProps<
      * ]} />
      * ```
      */
-    tokens: CodeTokenProps[];
+    tokens: CodeTokenProps<T>[];
+    /**
+     * 語法主題名稱。
+     * @default "vscode-dark"
+     */
+    theme?: CodeTheme;
   }
 >;
 
-export type CodeBlockProps = OverrideProps<
+export type CodeBlockProps<T extends React.ElementType> = OverrideProps<
   React.HTMLAttributes<HTMLPreElement>,
   {
     /**
@@ -84,7 +119,7 @@ export type CodeBlockProps = OverrideProps<
      * ]} />
      * ```
      */
-    tokenLines: CodeTokenProps[][];
+    tokenLines: CodeTokenProps<T>[][];
 
     /**
      * 是否顯示行號。
@@ -100,5 +135,10 @@ export type CodeBlockProps = OverrideProps<
      * ```
      * */
     lineNumberStyle?: React.CSSProperties;
+    /**
+     * 語法主題名稱。
+     * @default "vscode-dark"
+     */
+    theme?: CodeTheme;
   }
 >;

package/src/utils/index.ts

@@ -1,31 +1,47 @@
-import {
-  CodeTokenBuilder,
-  CodeTokenProps,
-  CodeTokenType,
-  DistributiveOmit,
-} from "../types";
-
-export const createToken = new Proxy(
+import { CodeTokenBuilder, CodeTokenProps, CodeTokenType } from "../types";
+/**
+ * 語法 token 的建構器集合，每個 key 對應一種語法類型（如 `keyword-blue`, `string`, `comment` 等），
+ * 透過 Proxy 生成對應的 `CodeTokenBuilder`。
+ *
+ * 使用方式：
+ * ```tsx
+ * c063["keyword-blue"]("const") // -> { type: "keyword-blue", children: "const" }
+ * c063["string"]("'hello'", { as: "code" }) // 可自訂 as 或其他 props
+ * ```
+ *
+ * @example
+ * tokens.push(c063["keyword-blue"]("const"));
+ * tokens.push(c063.string("'Hello'"));
+ *
+ * @returns 一個以 `CodeTokenType` 為 key 的建構器函式集合
+ */
+export const c063 = new Proxy(
   {},
   {
     get: (_, prop: CodeTokenType) => {
-      const builder = <T extends React.ElementType = React.ElementType>(
-        children: CodeTokenProps<T>["children"],
-        props: DistributiveOmit<CodeTokenProps<T>, "type">
-      ): CodeTokenProps<T> =>
-        {
-          return {
-            type: prop,
-            children,
-            ...props,
-          };
+      const builder = <T extends React.ElementType = "span">(
+        children: React.ReactNode,
+        props: CodeTokenProps<T>
+      ) => {
+        return {
+          children,
+          type: prop,
+          ...props,
         };
-      return builder;
+      };
+      return builder as CodeTokenBuilder;
     },
   }
 ) as Record<CodeTokenType, CodeTokenBuilder>;
 
-export const whiteSpace = (count: number = 1): CodeTokenProps => ({
-  type: "default",
-  children: " ".repeat(count),
-});
+/**
+ * 產生指定空白數量的 CodeToken，用於程式碼中的縮排或空格。
+ *
+ * @param count 空白字元數，預設為 1
+ * @returns `CodeTokenProps` 物件，type 為 "default"，children 為空白字串
+ *
+ * @example
+ * tokens.push(whiteSpace(2)); // -> { type: "default", children: "  " }
+ */
+export const whiteSpace = (count: number = 1): CodeTokenProps<"span"> =>
+  c063.default(" ".repeat(count));

package/src/libs/codeColorMap.tsx

@@ -1,20 +0,0 @@
-import { CodeTokenType } from "../types/props";
-
-export const codeColoreMap: Record<
-  CodeTokenType,
-  React.HTMLAttributes<React.ElementType>["className"]
-> = {
-  "keyword-blue": "#569cd6",
-  "keyword-purple": "#c586c0",
-  string: "#ce9178",
-  number: "#b5cea8",
-  comment: "#6a9955",
-  variable: "#9cdcfe",
-  constant: "#4fc1ff",
-  type: "#4ec9b0",
-  "brackets-1": "#ffd700",
-  "brackets-2": "#da70d6",
-  "brackets-3": "#179fff",
-  operator: "#d4d4d4",
-  default: "#d4d4d4",
-};

package/src/libs/index.ts

@@ -1 +0,0 @@
-export { codeColoreMap } from "./codeColorMap";