@vte-js/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vte-js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @vte/core
+
+Vue Token Engine 的核心包，提供 token 解析和类型工具。
+
+## 安装
+
+```bash
+npm install @vte/core
+# 或
+pnpm add @vte/core
+```
+
+## API
+
+### `defineTokens<T>(tokens)`
+
+定义设计 tokens，返回类型安全的 token 配置。
+
+```typescript
+import { defineTokens } from "@vte/core";
+
+const tokens = defineTokens({
+  primitive: {
+    blue: {
+      500: "#3b82f6",
+    },
+  },
+  semantic: {
+    color: {
+      primary: "{primitive.blue.500}", // 引用语法
+      background: "#ffffff",
+    },
+  },
+});
+```
+
+### `parseTokens(sourceFile)`
+
+解析 token 文件，返回扁平化的 TokenMap。
+
+```typescript
+import { parseTokens } from "@vte/core";
+
+const tokenMap = await parseTokens("./design-tokens.ts");
+
+// tokenMap 是 Map<string, TokenValue>
+// Key: "semantic.color.primary"
+// Value: { path, value, raw, refs }
+```
+
+### `TokenPath<T>` 类型
+
+从 token 定义中提取所有合法路径的联合类型，用于 IDE 自动补全。
+
+```typescript
+import { type TokenPath } from "@vte/core";
+
+type Paths = TokenPath<typeof tokens>;
+// "primitive" | "primitive.blue" | "primitive.blue.500" | ...
+```
+
+### `TokenMap` 类型
+
+```typescript
+interface TokenValue {
+  path: string;      // token 路径
+  value: string;     // 解析后的值
+  raw: string;       // 原始值
+  refs: string[];    // 引用链
+}
+
+type TokenMap = Map<string, TokenValue>;
+```
+
+## Token 语法
+
+### 直接值
+
+```typescript
+defineTokens({
+  color: {
+    primary: "#3b82f6",
+    spacing: "0.5rem",
+  },
+});
+```
+
+### 引用语法
+
+使用 `{path}` 语法引用其他 token：
+
+```typescript
+defineTokens({
+  primitive: {
+    blue: { 500: "#3b82f6" },
+  },
+  semantic: {
+    color: {
+      primary: "{primitive.blue.500}", // 引用 primitive.blue.500
+    },
+  },
+});
+```
+
+### 支持链式引用
+
+```typescript
+defineTokens({
+  primitive: { blue: { 500: "#3b82f6" } },
+  semantic: { color: { primary: "{primitive.blue.500}" } },
+  component: { button: { bg: "{semantic.color.primary}" } },
+});
+// component.button.bg → semantic.color.primary → primitive.blue.500 → #3b82f6
+```
+
+## 错误处理
+
+### 循环引用
+
+```typescript
+// ❌ 会抛出错误
+defineTokens({
+  a: "{b}",
+  b: "{a}",
+});
+// Error: [VTE] Circular reference detected: a → b → a
+```
+
+### 未解析引用
+
+```typescript
+// ❌ 会抛出错误
+defineTokens({
+  color: "{nonexistent.path}",
+});
+// Error: [VTE] Unresolved reference: "{nonexistent.path}" in token "color"
+```
+
+## License
+
+ISC

package/dist/__tests__/parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/parser.test.js

@@ -0,0 +1,143 @@
+import { describe, it, expect } from "vitest";
+import path from "path";
+import { parseTokens, defineTokens } from "../index.js";
+const playgroundDir = path.resolve(__dirname, "../../../../playground");
+describe("parseTokens", () => {
+    it("should parse design tokens from file", async () => {
+        const tokenPath = path.join(playgroundDir, "design-tokens.ts");
+        const map = await parseTokens(tokenPath);
+        expect(map).toBeDefined();
+        expect(map.size).toBeGreaterThan(0);
+    });
+    it("should flatten nested objects to dot notation", async () => {
+        const tokenPath = path.join(playgroundDir, "design-tokens.ts");
+        const map = await parseTokens(tokenPath);
+        expect(map.has("primitive.blue.500")).toBe(true);
+        expect(map.has("semantic.color.primary")).toBe(true);
+        expect(map.has("component.button.height")).toBe(true);
+    });
+    it("should resolve token references", async () => {
+        const tokenPath = path.join(playgroundDir, "design-tokens.ts");
+        const map = await parseTokens(tokenPath);
+        const primary = map.get("semantic.color.primary");
+        expect(primary?.value).toBe("#3b82f6");
+        const buttonHeight = map.get("component.button.height");
+        expect(buttonHeight?.value).toBe("1rem");
+    });
+    it("should resolve chain references", async () => {
+        const tokenPath = path.join(playgroundDir, "design-tokens.ts");
+        const map = await parseTokens(tokenPath);
+        // component.button.height -> semantic.spacing.md -> "1rem"
+        const buttonHeight = map.get("component.button.height");
+        expect(buttonHeight?.value).toBe("1rem");
+        expect(buttonHeight?.refs).toEqual(["semantic.spacing.md"]);
+    });
+    it("should throw on circular references", async () => {
+        const tokenPath = path.join(playgroundDir, "design-tokens-circular.ts");
+        await expect(parseTokens(tokenPath)).rejects.toThrow(/\[VTE\] Circular reference detected/);
+    });
+    it("should throw on unresolved references", async () => {
+        // Create a temporary file with unresolved reference
+        const fs = await import("fs");
+        const tmpFile = path.join(playgroundDir, "__tmp_unresolved.ts");
+        fs.writeFileSync(tmpFile, `
+      export default {
+        color: {
+          primary: "{nonexistent.path}",
+        },
+      };
+    `);
+        try {
+            await expect(parseTokens(tmpFile)).rejects.toThrow(/\[VTE\] Unresolved reference/);
+        }
+        finally {
+            fs.unlinkSync(tmpFile);
+        }
+    });
+    it("should store raw value for reference tokens", async () => {
+        const tokenPath = path.join(playgroundDir, "design-tokens.ts");
+        const map = await parseTokens(tokenPath);
+        const primary = map.get("semantic.color.primary");
+        expect(primary?.raw).toBe("{primitive.blue.500}");
+        expect(primary?.refs).toEqual(["primitive.blue.500"]);
+    });
+    it("should store string value for primitive tokens", async () => {
+        const tokenPath = path.join(playgroundDir, "design-tokens.ts");
+        const map = await parseTokens(tokenPath);
+        const blue500 = map.get("primitive.blue.500");
+        expect(blue500?.value).toBe("#3b82f6");
+        expect(blue500?.raw).toBe("#3b82f6");
+        expect(blue500?.refs).toEqual([]);
+    });
+    it("should handle numeric string values", async () => {
+        const fs = await import("fs");
+        const tmpFile = path.join(playgroundDir, "__tmp_numeric.ts");
+        fs.writeFileSync(tmpFile, `
+      export default {
+        spacing: {
+          small: 8,
+          medium: 16,
+        },
+      };
+    `);
+        try {
+            const map = await parseTokens(tmpFile);
+            expect(map.get("spacing.small")?.value).toBe("8");
+            expect(map.get("spacing.medium")?.value).toBe("16");
+        }
+        finally {
+            fs.unlinkSync(tmpFile);
+        }
+    });
+    it("should handle deeply nested tokens", async () => {
+        const fs = await import("fs");
+        const tmpFile = path.join(playgroundDir, "__tmp_deep.ts");
+        fs.writeFileSync(tmpFile, `
+      export default {
+        a: {
+          b: {
+            c: {
+              d: "deep-value",
+            },
+          },
+        },
+      };
+    `);
+        try {
+            const map = await parseTokens(tmpFile);
+            expect(map.has("a.b.c.d")).toBe(true);
+            expect(map.get("a.b.c.d")?.value).toBe("deep-value");
+        }
+        finally {
+            fs.unlinkSync(tmpFile);
+        }
+    });
+});
+describe("defineTokens", () => {
+    it("should return the input object", () => {
+        const tokens = defineTokens({
+            color: {
+                primary: "#3b82f6",
+            },
+        });
+        expect(tokens).toEqual({ color: { primary: "#3b82f6" } });
+    });
+    it("should preserve nested structure", () => {
+        const tokens = defineTokens({
+            semantic: {
+                color: {
+                    primary: "#3b82f6",
+                },
+            },
+        });
+        expect(tokens.semantic.color.primary).toBe("#3b82f6");
+    });
+    it("should preserve reference syntax in values", () => {
+        const tokens = defineTokens({
+            color: {
+                primary: "{primitive.blue.500}",
+            },
+        });
+        expect(tokens.color.primary).toBe("{primitive.blue.500}");
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { parseTokens, defineTokens, toCssVarName } from "./parser.js";
+export type { TokenValue, TokenMap } from "./parser.js";
+export type { DeepReadonly, FlattenPaths, TokenPath, TokenRef, TokenDefinition, TokenConfig, } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { parseTokens, defineTokens, toCssVarName } from "./parser.js";

package/dist/parser.d.ts

@@ -0,0 +1,16 @@
+import type { TokenDefinition, TokenConfig } from "./types.js";
+export interface TokenValue {
+    path: string;
+    value: string;
+    raw: string;
+    refs: string[];
+}
+export type TokenMap = Map<string, TokenValue>;
+/**
+ * Convert a token path to a CSS variable name.
+ * @example toCssVarName("semantic.color.primary") => "--vte-semantic-color-primary"
+ * @example toCssVarName("semantic.color.primary", "my") => "--my-semantic-color-primary"
+ */
+export declare function toCssVarName(tokenPath: string, prefix?: string): string;
+export declare function parseTokens(sourceFile: string): Promise<TokenMap>;
+export declare function defineTokens<T extends object>(tokens: TokenDefinition<T>): TokenConfig<T>;

package/dist/parser.js

@@ -0,0 +1,161 @@
+import { transformFile } from "@swc/core";
+import vm from "vm";
+import path from "path";
+/**
+ * Convert a token path to a CSS variable name.
+ * @example toCssVarName("semantic.color.primary") => "--vte-semantic-color-primary"
+ * @example toCssVarName("semantic.color.primary", "my") => "--my-semantic-color-primary"
+ */
+export function toCssVarName(tokenPath, prefix = "vte") {
+    return `--${prefix}-${tokenPath.replace(/\./g, "-")}`;
+}
+/**
+ * Load and evaluate a token file using @swc/core for AST transformation.
+ * This replaces the unsafe require() approach with proper TS parsing.
+ */
+async function loadTokenFile(sourceFile) {
+    const resolvedPath = path.resolve(sourceFile);
+    const result = await transformFile(resolvedPath, {
+        jsc: {
+            parser: {
+                syntax: "typescript",
+                decorators: true,
+            },
+            target: "es2020",
+        },
+        module: {
+            type: "commonjs",
+        },
+        isModule: true,
+    });
+    const transpiledCode = result.code;
+    // Create a sandboxed context with require and module exports
+    const moduleExports = {};
+    const moduleObj = { exports: moduleExports };
+    const sandbox = {
+        require: (id) => {
+            // Allow @vte-js/core for defineTokens
+            if (id === "@vte-js/core" || id.endsWith("/vte-core/dist/index.js")) {
+                return {
+                    defineTokens: (tokens) => tokens,
+                };
+            }
+            // Allow node built-in modules
+            if (id === "path" || id === "fs" || id === "os") {
+                return require(id);
+            }
+            throw new Error(`[VTE] Cannot require "${id}" in token files`);
+        },
+        module: moduleObj,
+        exports: moduleExports,
+        console,
+        setTimeout,
+        setInterval,
+        clearTimeout,
+        clearInterval,
+    };
+    // Execute the transpiled code in sandbox
+    const script = new vm.Script(transpiledCode, {
+        filename: resolvedPath,
+    });
+    const context = vm.createContext(sandbox);
+    script.runInContext(context);
+    // Get the exported value (handle both default and named exports)
+    const rawTokens = moduleObj.exports.default ?? moduleObj.exports;
+    return rawTokens;
+}
+export async function parseTokens(sourceFile) {
+    const rawTokens = await loadTokenFile(sourceFile);
+    const tokenMap = new Map();
+    const refGraph = {};
+    function flatten(obj, prefix = "") {
+        for (const key in obj) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            const value = obj[key];
+            if (typeof value === "string" &&
+                value.startsWith("{") &&
+                value.endsWith("}")) {
+                const refPath = value.slice(1, -1);
+                refGraph[path] = [refPath];
+                tokenMap.set(path, {
+                    path,
+                    value: "",
+                    raw: value,
+                    refs: [refPath],
+                });
+            }
+            else if (typeof value === "object" && value !== null) {
+                flatten(value, path);
+            }
+            else {
+                tokenMap.set(path, {
+                    path,
+                    value: String(value),
+                    raw: String(value),
+                    refs: [],
+                });
+            }
+        }
+    }
+    flatten(rawTokens);
+    // 循环引用检测：DFS 沿引用链遍历，发现环则抛出带路径的错误
+    function detectCircularRefs() {
+        const visiting = new Set();
+        const visited = new Set();
+        function dfs(node, chain) {
+            if (visited.has(node))
+                return;
+            if (visiting.has(node)) {
+                const cycleStart = chain.indexOf(node);
+                const cycle = chain.slice(cycleStart).concat(node);
+                throw new Error(`[VTE] Circular reference detected: ${cycle.join(" → ")}`);
+            }
+            visiting.add(node);
+            chain.push(node);
+            const refs = refGraph[node];
+            if (refs) {
+                for (const ref of refs) {
+                    dfs(ref, chain);
+                }
+            }
+            chain.pop();
+            visiting.delete(node);
+            visited.add(node);
+        }
+        for (const node of Object.keys(refGraph)) {
+            dfs(node, []);
+        }
+    }
+    detectCircularRefs();
+    // BFS 解析引用
+    function resolveRefs() {
+        let changed = true;
+        const maxDepth = 10;
+        let depth = 0;
+        while (changed && depth < maxDepth) {
+            changed = false;
+            depth++;
+            for (const [path, token] of tokenMap) {
+                if (token.refs.length > 0 && !token.value) {
+                    const refPath = token.refs[0];
+                    const refToken = tokenMap.get(refPath);
+                    if (refToken?.value) {
+                        token.value = refToken.value;
+                        changed = true;
+                    }
+                }
+            }
+        }
+        for (const [path, token] of tokenMap) {
+            if (token.refs.length > 0 && !token.value) {
+                throw new Error(`[VTE] Unresolved reference: "${token.raw}" in token "${path}". ` +
+                    `Check if "${token.refs[0]}" exists.`);
+            }
+        }
+    }
+    resolveRefs();
+    return tokenMap;
+}
+export function defineTokens(tokens) {
+    return tokens;
+}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 深度只读类型
+ */
+export type DeepReadonly<T> = T extends (infer U)[] ? ReadonlyArray<DeepReadonly<U>> : T extends Map<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * 将嵌套对象展平为点路径联合类型
+ * 例如: { a: { b: { c: 1 } } } => "a" | "a.b" | "a.b.c"
+ */
+export type FlattenPaths<T, Prefix extends string = ""> = T extends object ? {
+    [K in keyof T & string]: T[K] extends object ? FlattenPaths<T[K], Prefix extends "" ? K : `${Prefix}.${K}`> : Prefix extends "" ? K : `${Prefix}.${K}`;
+}[keyof T & string] : never;
+/**
+ * Token 路径类型：从 token 定义中提取所有合法的点路径
+ * 用于 IDE 自动补全 $token.path
+ *
+ * @example
+ * const tokens = defineTokens({ semantic: { color: { primary: "#3b82f6" } } });
+ * type Paths = TokenPath<typeof tokens>;
+ * // "semantic" | "semantic.color" | "semantic.color.primary"
+ *
+ * // 在 Vue 组件中使用
+ * type ValidPath = TokenPath<typeof import("./design-tokens").default>;
+ * const path: ValidPath = "$semantic.color.primary"; // ✅
+ */
+export type TokenPath<T> = T extends object ? FlattenPaths<T> : never;
+/**
+ * Token 引用类型: {path.to.token}
+ */
+export type TokenRef<P extends string> = `{${P}}`;
+/**
+ * defineTokens 的输入类型约束
+ * - 所有叶子值必须是 string
+ * - 引用值必须符合 {path} 格式
+ */
+export type TokenDefinition<T> = {
+    [K in keyof T]: T[K] extends string ? T[K] extends `{${string}}` ? T[K] : T[K] : T[K] extends object ? TokenDefinition<T[K]> : never;
+};
+/**
+ * defineTokens 返回类型：深度只读
+ */
+export type TokenConfig<T> = DeepReadonly<T>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@vte-js/core",
+  "version": "1.0.0",
+  "description": "Core parser and type definitions for Vue Token Engine",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@swc/core": "^1.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0"
+  },
+  "keywords": [
+    "vue",
+    "design-tokens",
+    "css-variables",
+    "core"
+  ],
+  "author": "vte-js",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vte-js/vte.git",
+    "directory": "packages/vte-core"
+  },
+  "homepage": "https://github.com/vte-js/vte/tree/main/packages/vte-core",
+  "bugs": {
+    "url": "https://github.com/vte-js/vte/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}