@apexhub/apex-ui-design-token-cli 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +94 -2
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +99 -0
- package/dist/commands/build.d.ts +11 -0
- package/dist/commands/build.js +118 -0
- package/dist/commands/theme.d.ts +12 -0
- package/dist/commands/theme.js +68 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +17 -0
- package/dist/lib/build-report.d.ts +44 -0
- package/dist/lib/build-report.js +111 -0
- package/dist/lib/css-value.d.ts +6 -0
- package/dist/lib/css-value.js +11 -0
- package/dist/lib/emit-cheatsheet.d.ts +13 -0
- package/dist/lib/emit-cheatsheet.js +53 -0
- package/dist/lib/emit-component-scoped.d.ts +20 -0
- package/dist/lib/emit-component-scoped.js +140 -0
- package/dist/lib/emit-css.d.ts +25 -0
- package/dist/lib/emit-css.js +95 -0
- package/dist/lib/emit-dts.d.ts +13 -0
- package/dist/lib/emit-dts.js +42 -0
- package/dist/lib/flatten.d.ts +8 -0
- package/dist/lib/flatten.js +35 -0
- package/dist/lib/merge-modes.d.ts +17 -0
- package/dist/lib/merge-modes.js +66 -0
- package/dist/lib/parse-component-path.d.ts +27 -0
- package/dist/lib/parse-component-path.js +61 -0
- package/dist/lib/parse-css-snapshot.d.ts +18 -0
- package/dist/lib/parse-css-snapshot.js +59 -0
- package/dist/lib/path-to-var.d.ts +31 -0
- package/dist/lib/path-to-var.js +56 -0
- package/dist/lib/read-tokens.d.ts +33 -0
- package/dist/lib/read-tokens.js +107 -0
- package/dist/lib/resolve-refs.d.ts +22 -0
- package/dist/lib/resolve-refs.js +232 -0
- package/dist/lib/selector-parent-map.d.ts +7 -0
- package/dist/lib/selector-parent-map.js +36 -0
- package/dist/lib/types.d.ts +84 -0
- package/dist/lib/types.js +2 -0
- package/package.json +43 -3
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parse generated theme CSS into comparable snapshots (for build --report).
|
|
3
|
+
*/
|
|
4
|
+
const ROOT_VAR_LINE_RE = /^(--[\w-]+):\s*(.+?);?\s*$/;
|
|
5
|
+
const ROOT_VAR_GLOBAL_RE = /(--[\w-]+):\s*([^;]+);/g;
|
|
6
|
+
/** Exported for selector-parent-map (single source of truth). */
|
|
7
|
+
export const BLOCK_OPEN_RE = /^\.(apex-[\w-]+)\s*\{/;
|
|
8
|
+
export const NESTED_OPEN_RE = /^&\.(apex-[\w-]+)\s*\{/;
|
|
9
|
+
/**
|
|
10
|
+
* Extract all `--name: value` declarations (primitives / aliases are flat under :root).
|
|
11
|
+
*/
|
|
12
|
+
export function parseRootLayerCss(css) {
|
|
13
|
+
const vars = {};
|
|
14
|
+
for (const m of css.matchAll(ROOT_VAR_GLOBAL_RE)) {
|
|
15
|
+
vars[m[1]] = m[2].trim();
|
|
16
|
+
}
|
|
17
|
+
if (Object.keys(vars).length > 0)
|
|
18
|
+
return vars;
|
|
19
|
+
for (const line of css.split('\n')) {
|
|
20
|
+
const trimmed = line.trim();
|
|
21
|
+
if (!trimmed || trimmed.startsWith('/*'))
|
|
22
|
+
continue;
|
|
23
|
+
const m = trimmed.match(ROOT_VAR_LINE_RE);
|
|
24
|
+
if (m)
|
|
25
|
+
vars[m[1]] = m[2].trim();
|
|
26
|
+
}
|
|
27
|
+
return vars;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Parse component-tokens.css nested blocks.
|
|
31
|
+
*/
|
|
32
|
+
export function parseComponentScopedCss(css) {
|
|
33
|
+
const blocks = {};
|
|
34
|
+
const selectorStack = [];
|
|
35
|
+
for (const line of css.split('\n')) {
|
|
36
|
+
const trimmed = line.trim();
|
|
37
|
+
if (!trimmed || trimmed.startsWith('/*'))
|
|
38
|
+
continue;
|
|
39
|
+
const blockOpen = trimmed.match(BLOCK_OPEN_RE);
|
|
40
|
+
const nestedOpen = trimmed.match(NESTED_OPEN_RE);
|
|
41
|
+
if (blockOpen || nestedOpen) {
|
|
42
|
+
const sel = (blockOpen ?? nestedOpen)[1];
|
|
43
|
+
if (!blocks[sel])
|
|
44
|
+
blocks[sel] = {};
|
|
45
|
+
selectorStack.push(sel);
|
|
46
|
+
continue;
|
|
47
|
+
}
|
|
48
|
+
if (trimmed === '}') {
|
|
49
|
+
selectorStack.pop();
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
const m = trimmed.match(ROOT_VAR_LINE_RE);
|
|
53
|
+
const current = selectorStack[selectorStack.length - 1];
|
|
54
|
+
if (m && current) {
|
|
55
|
+
blocks[current][m[1]] = m[2].trim();
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
return blocks;
|
|
59
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 团队命名空间白标:所有生成产物默认使用的前缀。
|
|
3
|
+
* CLI `--namespace` 未传时、以及各 emit* 函数的 `namespace` 参数缺省时均回落到此值。
|
|
4
|
+
*/
|
|
5
|
+
export declare const DEFAULT_NAMESPACE = "apex";
|
|
6
|
+
export declare function isValidNamespace(namespace: string): boolean;
|
|
7
|
+
/** 非法 namespace 直接抛错(CLI / 各 command 入口统一在此处失败)。 */
|
|
8
|
+
export declare function assertValidNamespace(namespace: string): void;
|
|
9
|
+
/**
|
|
10
|
+
* 把 Figma token 路径转成 CSS 自定义属性名。
|
|
11
|
+
*
|
|
12
|
+
* 规则(无映射表,纯转换):
|
|
13
|
+
* 1. `/` 和 `.` 都视为段分隔符
|
|
14
|
+
* 2. 段内驼峰转 kebab(`borderWidth` → `border-width`)
|
|
15
|
+
* 3. 多余的连字符合并、首尾连字符去掉
|
|
16
|
+
* 4. 加 `--{namespace}-` 前缀(默认 "apex")
|
|
17
|
+
* 5. 全部小写
|
|
18
|
+
*
|
|
19
|
+
* 例:
|
|
20
|
+
* "grey.1" → "--apex-grey-1"
|
|
21
|
+
* "fill.neutral.primary" → "--apex-fill-neutral-primary"
|
|
22
|
+
* "spacing.4" → "--apex-spacing-4"
|
|
23
|
+
* (component 层由 parseComponentPath 生成 --button-fill-default 等局部变量)
|
|
24
|
+
* "borderWidth.thin" → "--apex-border-width-thin"
|
|
25
|
+
* "base value.spacing.4" → "--apex-base-value-spacing-4"(含空格的 setKey 不会进路径,这里只处理 figma path)
|
|
26
|
+
*/
|
|
27
|
+
/** 单段 Figma token 名 → kebab(空格、驼峰、大小写) */
|
|
28
|
+
export declare function tokenPathSegment(seg: string): string;
|
|
29
|
+
/** 多段路径拼成 kebab 局部名(component localName 等) */
|
|
30
|
+
export declare function joinTokenSegments(...segments: string[]): string;
|
|
31
|
+
export declare function pathToVar(figmaPath: string, namespace?: string): string;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 团队命名空间白标:所有生成产物默认使用的前缀。
|
|
3
|
+
* CLI `--namespace` 未传时、以及各 emit* 函数的 `namespace` 参数缺省时均回落到此值。
|
|
4
|
+
*/
|
|
5
|
+
export const DEFAULT_NAMESPACE = 'apex';
|
|
6
|
+
/** 合法 namespace:小写 kebab-case,2-32 字符(如 "apex"、"dino"、"team-a")。 */
|
|
7
|
+
const NAMESPACE_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
|
|
8
|
+
export function isValidNamespace(namespace) {
|
|
9
|
+
return namespace.length >= 2 && namespace.length <= 32 && NAMESPACE_PATTERN.test(namespace);
|
|
10
|
+
}
|
|
11
|
+
/** 非法 namespace 直接抛错(CLI / 各 command 入口统一在此处失败)。 */
|
|
12
|
+
export function assertValidNamespace(namespace) {
|
|
13
|
+
if (!isValidNamespace(namespace)) {
|
|
14
|
+
throw new Error(`Invalid --namespace "${namespace}": must be lowercase kebab-case, 2-32 chars (e.g. "apex", "dino").`);
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* 把 Figma token 路径转成 CSS 自定义属性名。
|
|
19
|
+
*
|
|
20
|
+
* 规则(无映射表,纯转换):
|
|
21
|
+
* 1. `/` 和 `.` 都视为段分隔符
|
|
22
|
+
* 2. 段内驼峰转 kebab(`borderWidth` → `border-width`)
|
|
23
|
+
* 3. 多余的连字符合并、首尾连字符去掉
|
|
24
|
+
* 4. 加 `--{namespace}-` 前缀(默认 "apex")
|
|
25
|
+
* 5. 全部小写
|
|
26
|
+
*
|
|
27
|
+
* 例:
|
|
28
|
+
* "grey.1" → "--apex-grey-1"
|
|
29
|
+
* "fill.neutral.primary" → "--apex-fill-neutral-primary"
|
|
30
|
+
* "spacing.4" → "--apex-spacing-4"
|
|
31
|
+
* (component 层由 parseComponentPath 生成 --button-fill-default 等局部变量)
|
|
32
|
+
* "borderWidth.thin" → "--apex-border-width-thin"
|
|
33
|
+
* "base value.spacing.4" → "--apex-base-value-spacing-4"(含空格的 setKey 不会进路径,这里只处理 figma path)
|
|
34
|
+
*/
|
|
35
|
+
/** 单段 Figma token 名 → kebab(空格、驼峰、大小写) */
|
|
36
|
+
export function tokenPathSegment(seg) {
|
|
37
|
+
return seg
|
|
38
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
|
|
39
|
+
.replace(/\s+/g, '-')
|
|
40
|
+
.toLowerCase()
|
|
41
|
+
.replace(/-+/g, '-')
|
|
42
|
+
.replace(/^-|-$/g, '');
|
|
43
|
+
}
|
|
44
|
+
/** 多段路径拼成 kebab 局部名(component localName 等) */
|
|
45
|
+
export function joinTokenSegments(...segments) {
|
|
46
|
+
return segments
|
|
47
|
+
.map(tokenPathSegment)
|
|
48
|
+
.filter(Boolean)
|
|
49
|
+
.join('-')
|
|
50
|
+
.replace(/-+/g, '-')
|
|
51
|
+
.replace(/^-|-$/g, '');
|
|
52
|
+
}
|
|
53
|
+
export function pathToVar(figmaPath, namespace = DEFAULT_NAMESPACE) {
|
|
54
|
+
const kebab = joinTokenSegments(...figmaPath.split(/[/.]/));
|
|
55
|
+
return `--${namespace}-${kebab}`;
|
|
56
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { type TokenSet, type TokensMetadata, type TokenTree } from './types.js';
|
|
2
|
+
interface ReadResult {
|
|
3
|
+
metadata: TokensMetadata;
|
|
4
|
+
sets: TokenSet[];
|
|
5
|
+
/** 出现过的 mode 名(已规范化排序:light/Mode1 优先作 base,dark 作 alt) */
|
|
6
|
+
modeNames: string[];
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* 把 `metadata.tokenSetOrder` 中的某一项拆成 (setKey, modeName)。
|
|
10
|
+
*
|
|
11
|
+
* 例:
|
|
12
|
+
* - "palette/Mode 1" → { setKey: "palette", modeName: "Mode 1" }
|
|
13
|
+
* - "foundation/light" → { setKey: "foundation", modeName: "light" }
|
|
14
|
+
* - "foundation/dark" → { setKey: "foundation", modeName: "dark" }
|
|
15
|
+
* - "component usage/Mode 2" → { setKey: "component usage", modeName: "Mode 2" }
|
|
16
|
+
* - "global" → { setKey: "global", modeName: DEFAULT_MODE }
|
|
17
|
+
*/
|
|
18
|
+
export declare function splitSetName(rawName: string): {
|
|
19
|
+
setKey: string;
|
|
20
|
+
modeName: string;
|
|
21
|
+
};
|
|
22
|
+
/** 检测 token tree 是否为空(兼容 global.json 是 `{}` 的情况)。 */
|
|
23
|
+
export declare function isEmptyTree(tree: TokenTree | undefined | null): boolean;
|
|
24
|
+
/**
|
|
25
|
+
* 读取 tokens 目录,返回 metadata + 各 set + 出现的 mode 列表。
|
|
26
|
+
*
|
|
27
|
+
* 错误处理:
|
|
28
|
+
* - 缺少 $metadata.json:抛错(明确指引用户)
|
|
29
|
+
* - 个别 set 文件缺失:抛错(说明 Figma 导出不完整)
|
|
30
|
+
* - set 内容为空对象:跳过(如 global.json 是 {})
|
|
31
|
+
*/
|
|
32
|
+
export declare function readTokens(inDir: string): ReadResult;
|
|
33
|
+
export {};
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { orderModeNames } from './merge-modes.js';
|
|
4
|
+
import { DEFAULT_MODE } from './types.js';
|
|
5
|
+
/** Tokens Studio 的 Mode 命名约定:`Mode 1` / `Mode 2`,以及语义名 `light` / `dark` / `night`。 */
|
|
6
|
+
const MODE_PATTERN = /^(Mode\s+\S+|light|dark|night)$/i;
|
|
7
|
+
/**
|
|
8
|
+
* 把 `metadata.tokenSetOrder` 中的某一项拆成 (setKey, modeName)。
|
|
9
|
+
*
|
|
10
|
+
* 例:
|
|
11
|
+
* - "palette/Mode 1" → { setKey: "palette", modeName: "Mode 1" }
|
|
12
|
+
* - "foundation/light" → { setKey: "foundation", modeName: "light" }
|
|
13
|
+
* - "foundation/dark" → { setKey: "foundation", modeName: "dark" }
|
|
14
|
+
* - "component usage/Mode 2" → { setKey: "component usage", modeName: "Mode 2" }
|
|
15
|
+
* - "global" → { setKey: "global", modeName: DEFAULT_MODE }
|
|
16
|
+
*/
|
|
17
|
+
export function splitSetName(rawName) {
|
|
18
|
+
const idx = rawName.lastIndexOf('/');
|
|
19
|
+
if (idx < 0)
|
|
20
|
+
return { setKey: rawName, modeName: DEFAULT_MODE };
|
|
21
|
+
const last = rawName.slice(idx + 1);
|
|
22
|
+
if (!MODE_PATTERN.test(last))
|
|
23
|
+
return { setKey: rawName, modeName: DEFAULT_MODE };
|
|
24
|
+
// 规范化语义 mode 名为小写,便于 merge / emit 匹配
|
|
25
|
+
const modeName = /^(light|dark|night)$/i.test(last) ? last.toLowerCase() : last;
|
|
26
|
+
return { setKey: rawName.slice(0, idx), modeName };
|
|
27
|
+
}
|
|
28
|
+
/** 检测 token tree 是否为空(兼容 global.json 是 `{}` 的情况)。 */
|
|
29
|
+
export function isEmptyTree(tree) {
|
|
30
|
+
if (!tree)
|
|
31
|
+
return true;
|
|
32
|
+
for (const key of Object.keys(tree)) {
|
|
33
|
+
if (!key.startsWith('$'))
|
|
34
|
+
return false;
|
|
35
|
+
}
|
|
36
|
+
return true;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* 某 setKey 若只出现在一个具名 Mode 下(例如仅有 `palette/dark`),
|
|
40
|
+
* 则把该 Mode 降为 DEFAULT_MODE,使色板等共享层写入 `:root`,
|
|
41
|
+
* 避免 light foundation 引用不到 palette 变量。
|
|
42
|
+
*/
|
|
43
|
+
function promoteSingleModeSetsToDefault(sets) {
|
|
44
|
+
const modesBySetKey = new Map();
|
|
45
|
+
for (const s of sets) {
|
|
46
|
+
let modes = modesBySetKey.get(s.setKey);
|
|
47
|
+
if (!modes) {
|
|
48
|
+
modes = new Set();
|
|
49
|
+
modesBySetKey.set(s.setKey, modes);
|
|
50
|
+
}
|
|
51
|
+
modes.add(s.modeName);
|
|
52
|
+
}
|
|
53
|
+
for (const s of sets) {
|
|
54
|
+
const modes = modesBySetKey.get(s.setKey);
|
|
55
|
+
if (!modes)
|
|
56
|
+
continue;
|
|
57
|
+
const named = [...modes].filter((m) => m !== DEFAULT_MODE);
|
|
58
|
+
if (modes.size === 1 && named.length === 1) {
|
|
59
|
+
s.modeName = DEFAULT_MODE;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* 读取 tokens 目录,返回 metadata + 各 set + 出现的 mode 列表。
|
|
65
|
+
*
|
|
66
|
+
* 错误处理:
|
|
67
|
+
* - 缺少 $metadata.json:抛错(明确指引用户)
|
|
68
|
+
* - 个别 set 文件缺失:抛错(说明 Figma 导出不完整)
|
|
69
|
+
* - set 内容为空对象:跳过(如 global.json 是 {})
|
|
70
|
+
*/
|
|
71
|
+
export function readTokens(inDir) {
|
|
72
|
+
const absIn = path.resolve(inDir);
|
|
73
|
+
const metaPath = path.join(absIn, '$metadata.json');
|
|
74
|
+
if (!fs.existsSync(metaPath)) {
|
|
75
|
+
throw new Error(`未找到 ${metaPath}\n` +
|
|
76
|
+
`请确认 --in 指向的目录是 Tokens Studio 导出的 tokens 根目录(应包含 $metadata.json)`);
|
|
77
|
+
}
|
|
78
|
+
const metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
|
|
79
|
+
if (!Array.isArray(metadata.tokenSetOrder) || metadata.tokenSetOrder.length === 0) {
|
|
80
|
+
throw new Error(`${metaPath} 的 tokenSetOrder 为空,无法解析`);
|
|
81
|
+
}
|
|
82
|
+
const sets = [];
|
|
83
|
+
for (const rawName of metadata.tokenSetOrder) {
|
|
84
|
+
const setPath = path.join(absIn, `${rawName}.json`);
|
|
85
|
+
if (!fs.existsSync(setPath)) {
|
|
86
|
+
throw new Error(`metadata.tokenSetOrder 含 "${rawName}",但找不到 ${setPath}\nTokens Studio 导出不完整?`);
|
|
87
|
+
}
|
|
88
|
+
const content = JSON.parse(fs.readFileSync(setPath, 'utf-8'));
|
|
89
|
+
if (isEmptyTree(content))
|
|
90
|
+
continue;
|
|
91
|
+
const { setKey, modeName } = splitSetName(rawName);
|
|
92
|
+
sets.push({ rawName, setKey, modeName, content });
|
|
93
|
+
}
|
|
94
|
+
if (sets.length === 0) {
|
|
95
|
+
throw new Error(`tokens 目录解析后无任何有效 token set\n` + `请确认 ${absIn} 下的 JSON 不全是 {} 空集合`);
|
|
96
|
+
}
|
|
97
|
+
promoteSingleModeSetsToDefault(sets);
|
|
98
|
+
const modeSet = new Set();
|
|
99
|
+
const modeOrder = [];
|
|
100
|
+
for (const s of sets) {
|
|
101
|
+
if (s.modeName !== DEFAULT_MODE && !modeSet.has(s.modeName)) {
|
|
102
|
+
modeSet.add(s.modeName);
|
|
103
|
+
modeOrder.push(s.modeName);
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
return { metadata, sets, modeNames: orderModeNames(modeOrder) };
|
|
107
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { type FlatToken, type RawFlatToken } from './types.js';
|
|
2
|
+
/** Tokens Studio 引用语法:`{a.b.c}`。 */
|
|
3
|
+
export declare const REF_PATTERN: RegExp;
|
|
4
|
+
/** 若 rawValue 为单一引用,返回目标 figma path;否则 undefined。 */
|
|
5
|
+
export declare function parseSingleRef(rawValue: string | number): string | undefined;
|
|
6
|
+
interface ResolveOptions {
|
|
7
|
+
/** 设为 true 时遇到无法解引会抛错(默认 false:warn 后输出原值,方便用户排查) */
|
|
8
|
+
strict?: boolean;
|
|
9
|
+
/** 警告通道(便于测试时捕获) */
|
|
10
|
+
warn?: (msg: string) => void;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* 先按 (modeName, figmaPath) 建索引,再按 mode 解引。
|
|
14
|
+
*
|
|
15
|
+
* 同 mode 内跨 set 冲突:后注册覆盖前注册(Tokens Studio 规范),打 warning。
|
|
16
|
+
* 跨 mode 同 path:各自保留(light / dark 语义色)。
|
|
17
|
+
*
|
|
18
|
+
* 解引查找顺序:当前 mode → DEFAULT_MODE → 任意其它 mode(共享色板兜底)。
|
|
19
|
+
*/
|
|
20
|
+
export declare function resolveAllRefs(rawTokens: RawFlatToken[], options?: ResolveOptions): FlatToken[];
|
|
21
|
+
export declare function formatNumber(value: number, type: string, figmaPath: string): string;
|
|
22
|
+
export {};
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
import { DEFAULT_MODE } from './types.js';
|
|
2
|
+
/** Tokens Studio 引用语法:`{a.b.c}`。 */
|
|
3
|
+
export const REF_PATTERN = /^\{(.+)\}$/;
|
|
4
|
+
/** 若 rawValue 为单一引用,返回目标 figma path;否则 undefined。 */
|
|
5
|
+
export function parseSingleRef(rawValue) {
|
|
6
|
+
if (typeof rawValue !== 'string')
|
|
7
|
+
return undefined;
|
|
8
|
+
const match = rawValue.match(REF_PATTERN);
|
|
9
|
+
return match?.[1];
|
|
10
|
+
}
|
|
11
|
+
/** Figma 插件导出的颜色表达式:`rgba({fill.neutral.tertiary}, 0.8)`。 */
|
|
12
|
+
const FIGMA_RGBA_REF_PATTERN = /^rgba\(\s*\{([^{}]+)\}\s*,\s*([^)]+?)\s*\)$/i;
|
|
13
|
+
/**
|
|
14
|
+
* Tokens Studio 中数学表达式(如 `{spacing.4} * 2`)暂不支持。
|
|
15
|
+
* Figma 插件导出的 `rgba({path}, alpha)` 是唯一支持的复合表达式。
|
|
16
|
+
*/
|
|
17
|
+
function looksLikeExpression(value) {
|
|
18
|
+
return value.includes('{') && !REF_PATTERN.test(value);
|
|
19
|
+
}
|
|
20
|
+
function parseAlpha(value) {
|
|
21
|
+
const trimmed = value.trim();
|
|
22
|
+
if (trimmed.endsWith('%')) {
|
|
23
|
+
const percent = Number(trimmed.slice(0, -1));
|
|
24
|
+
return Number.isFinite(percent) && percent >= 0 && percent <= 100 ? percent / 100 : undefined;
|
|
25
|
+
}
|
|
26
|
+
const alpha = Number(trimmed);
|
|
27
|
+
return Number.isFinite(alpha) && alpha >= 0 && alpha <= 1 ? alpha : undefined;
|
|
28
|
+
}
|
|
29
|
+
function parseHexColor(value) {
|
|
30
|
+
const hex = value.trim().match(/^#([\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i)?.[1];
|
|
31
|
+
if (!hex)
|
|
32
|
+
return undefined;
|
|
33
|
+
const expanded = hex.length <= 4 ? [...hex].map((digit) => `${digit}${digit}`).join('') : hex;
|
|
34
|
+
const channel = (start) => Number.parseInt(expanded.slice(start, start + 2), 16);
|
|
35
|
+
const alpha = expanded.length === 8 ? channel(6) / 255 : undefined;
|
|
36
|
+
return { red: channel(0), green: channel(2), blue: channel(4), alpha };
|
|
37
|
+
}
|
|
38
|
+
function parseRgbColor(value) {
|
|
39
|
+
const match = value.trim().match(/^rgba?\(\s*([^()]+?)\s*\)$/i);
|
|
40
|
+
if (!match)
|
|
41
|
+
return undefined;
|
|
42
|
+
const parts = match[1].split(',').map((part) => part.trim());
|
|
43
|
+
if (parts.length !== 3 && parts.length !== 4)
|
|
44
|
+
return undefined;
|
|
45
|
+
const channels = parts.slice(0, 3).map(Number);
|
|
46
|
+
if (channels.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 255)) {
|
|
47
|
+
return undefined;
|
|
48
|
+
}
|
|
49
|
+
const alpha = parts.length === 4 ? parseAlpha(parts[3]) : undefined;
|
|
50
|
+
if (parts.length === 4 && alpha === undefined)
|
|
51
|
+
return undefined;
|
|
52
|
+
return { red: channels[0], green: channels[1], blue: channels[2], alpha };
|
|
53
|
+
}
|
|
54
|
+
function parseColor(value) {
|
|
55
|
+
return parseHexColor(value) ?? parseRgbColor(value);
|
|
56
|
+
}
|
|
57
|
+
function formatAlpha(alpha) {
|
|
58
|
+
return Number(alpha.toFixed(6)).toString();
|
|
59
|
+
}
|
|
60
|
+
function formatFigmaRgba(color, alphaValue) {
|
|
61
|
+
const alpha = parseAlpha(alphaValue);
|
|
62
|
+
if (alpha === undefined)
|
|
63
|
+
return undefined;
|
|
64
|
+
const combinedAlpha = color.alpha === undefined ? alpha : color.alpha * alpha;
|
|
65
|
+
return `rgba(${color.red}, ${color.green}, ${color.blue}, ${formatAlpha(combinedAlpha)})`;
|
|
66
|
+
}
|
|
67
|
+
function modePathKey(modeName, figmaPath) {
|
|
68
|
+
return `${modeName}\u0000${figmaPath}`;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* 先按 (modeName, figmaPath) 建索引,再按 mode 解引。
|
|
72
|
+
*
|
|
73
|
+
* 同 mode 内跨 set 冲突:后注册覆盖前注册(Tokens Studio 规范),打 warning。
|
|
74
|
+
* 跨 mode 同 path:各自保留(light / dark 语义色)。
|
|
75
|
+
*
|
|
76
|
+
* 解引查找顺序:当前 mode → DEFAULT_MODE → 任意其它 mode(共享色板兜底)。
|
|
77
|
+
*/
|
|
78
|
+
export function resolveAllRefs(rawTokens, options = {}) {
|
|
79
|
+
const warn = options.warn ?? ((msg) => process.stderr.write(`[apex-ui] ${msg}\n`));
|
|
80
|
+
/** mode → (figmaPath → token),同 mode 内后写覆盖 */
|
|
81
|
+
const modeMaps = new Map();
|
|
82
|
+
/** 任意 mode 都可查到的 path 兜底(后写覆盖,仅用于跨 mode 回退) */
|
|
83
|
+
const anyPathMap = new Map();
|
|
84
|
+
for (const t of rawTokens) {
|
|
85
|
+
let pathMap = modeMaps.get(t.modeName);
|
|
86
|
+
if (!pathMap) {
|
|
87
|
+
pathMap = new Map();
|
|
88
|
+
modeMaps.set(t.modeName, pathMap);
|
|
89
|
+
}
|
|
90
|
+
const existing = pathMap.get(t.figmaPath);
|
|
91
|
+
if (existing && existing.setKey !== t.setKey) {
|
|
92
|
+
warn(`命名冲突:${t.figmaPath} 在 ${existing.setKey} 和 ${t.setKey} 中同时存在(mode=${t.modeName}),` +
|
|
93
|
+
`已采用后者(${t.setKey})`);
|
|
94
|
+
}
|
|
95
|
+
pathMap.set(t.figmaPath, t);
|
|
96
|
+
anyPathMap.set(t.figmaPath, t);
|
|
97
|
+
}
|
|
98
|
+
const cache = new Map();
|
|
99
|
+
const stack = new Set();
|
|
100
|
+
function lookupRaw(modeName, figmaPath) {
|
|
101
|
+
const own = modeMaps.get(modeName)?.get(figmaPath);
|
|
102
|
+
if (own)
|
|
103
|
+
return own;
|
|
104
|
+
if (modeName !== DEFAULT_MODE) {
|
|
105
|
+
const shared = modeMaps.get(DEFAULT_MODE)?.get(figmaPath);
|
|
106
|
+
if (shared)
|
|
107
|
+
return shared;
|
|
108
|
+
}
|
|
109
|
+
return anyPathMap.get(figmaPath);
|
|
110
|
+
}
|
|
111
|
+
function resolveByPath(modeName, figmaPath, fromPath) {
|
|
112
|
+
const cacheKey = modePathKey(modeName, figmaPath);
|
|
113
|
+
const cached = cache.get(cacheKey);
|
|
114
|
+
if (cached !== undefined)
|
|
115
|
+
return cached;
|
|
116
|
+
if (stack.has(cacheKey)) {
|
|
117
|
+
throw new Error(`检测到循环引用:${[...stack, cacheKey].join(' → ')}`);
|
|
118
|
+
}
|
|
119
|
+
const token = lookupRaw(modeName, figmaPath);
|
|
120
|
+
if (!token) {
|
|
121
|
+
const ref = `{${figmaPath}}`;
|
|
122
|
+
warn(`无法解引:${ref}${fromPath ? `(来自 ${fromPath})` : ''},输出原值`);
|
|
123
|
+
if (options.strict)
|
|
124
|
+
throw new Error(`无法解引:${ref}`);
|
|
125
|
+
return ref;
|
|
126
|
+
}
|
|
127
|
+
// 用 token 自身的 mode 继续解引,避免跨 mode 串值
|
|
128
|
+
const resolveMode = token.modeName;
|
|
129
|
+
stack.add(cacheKey);
|
|
130
|
+
const value = token.rawValue;
|
|
131
|
+
let resolved;
|
|
132
|
+
if (typeof value === 'number') {
|
|
133
|
+
resolved = formatNumber(value, token.type, token.figmaPath);
|
|
134
|
+
}
|
|
135
|
+
else {
|
|
136
|
+
const match = value.match(REF_PATTERN);
|
|
137
|
+
if (match) {
|
|
138
|
+
resolved = resolveByPath(resolveMode, match[1], token.figmaPath);
|
|
139
|
+
}
|
|
140
|
+
else if (looksLikeExpression(value)) {
|
|
141
|
+
const rgbaMatch = value.match(FIGMA_RGBA_REF_PATTERN);
|
|
142
|
+
if (rgbaMatch) {
|
|
143
|
+
const referencedColor = parseColor(resolveByPath(resolveMode, rgbaMatch[1], token.figmaPath));
|
|
144
|
+
const rgbaValue = referencedColor
|
|
145
|
+
? formatFigmaRgba(referencedColor, rgbaMatch[2])
|
|
146
|
+
: undefined;
|
|
147
|
+
if (rgbaValue) {
|
|
148
|
+
resolved = rgbaValue;
|
|
149
|
+
}
|
|
150
|
+
else {
|
|
151
|
+
warn(`暂不支持颜色表达式:${value}(来自 ${token.figmaPath}),输出原值`);
|
|
152
|
+
resolved = value;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
else {
|
|
156
|
+
warn(`暂不支持表达式语法:${value}(来自 ${token.figmaPath}),输出原值`);
|
|
157
|
+
resolved = value;
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
else {
|
|
161
|
+
resolved = value;
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
stack.delete(cacheKey);
|
|
165
|
+
cache.set(cacheKey, resolved);
|
|
166
|
+
return resolved;
|
|
167
|
+
}
|
|
168
|
+
// 同 (modeName + figmaPath) 去重,保留最后注册。
|
|
169
|
+
const finalMap = new Map();
|
|
170
|
+
for (const raw of rawTokens) {
|
|
171
|
+
const key = modePathKey(raw.modeName, raw.figmaPath);
|
|
172
|
+
const finalRaw = modeMaps.get(raw.modeName)?.get(raw.figmaPath) ?? raw;
|
|
173
|
+
const refPath = parseSingleRef(finalRaw.rawValue);
|
|
174
|
+
const refTarget = refPath && lookupRaw(raw.modeName, refPath) ? refPath : undefined;
|
|
175
|
+
finalMap.set(key, {
|
|
176
|
+
figmaPath: raw.figmaPath,
|
|
177
|
+
value: resolveByPath(raw.modeName, raw.figmaPath),
|
|
178
|
+
rawValue: finalRaw.rawValue,
|
|
179
|
+
refTarget,
|
|
180
|
+
type: finalRaw.type,
|
|
181
|
+
description: finalRaw.description,
|
|
182
|
+
setKey: finalRaw.setKey,
|
|
183
|
+
modeName: raw.modeName,
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
return [...finalMap.values()];
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* `$type: "number"` 的值需要按上下文加单位。
|
|
190
|
+
*
|
|
191
|
+
* 规则(按优先级):
|
|
192
|
+
* 1. dimension / 路径含尺寸语义 → 加 px
|
|
193
|
+
* 2. opacity 类 → 无单位
|
|
194
|
+
* 3. fontspacing → Figma 字间距百分比(1 = 1%)→ CSS `em`(1% ≈ 0.01em)
|
|
195
|
+
* 4. fontWeight / z-index / line-height 数值 → 无单位
|
|
196
|
+
* 5. fallback → 无单位(保守,避免错误加单位)
|
|
197
|
+
*/
|
|
198
|
+
const PX_PATH_PATTERNS = [
|
|
199
|
+
'spacing',
|
|
200
|
+
'radius',
|
|
201
|
+
'border',
|
|
202
|
+
'padding',
|
|
203
|
+
'gap',
|
|
204
|
+
'height',
|
|
205
|
+
'width',
|
|
206
|
+
'size',
|
|
207
|
+
'icon',
|
|
208
|
+
'layout',
|
|
209
|
+
'thickness',
|
|
210
|
+
'offset',
|
|
211
|
+
'stroke',
|
|
212
|
+
];
|
|
213
|
+
const UNITLESS_PATH_PATTERNS = ['opacity', 'fontWeight', 'zIndex', 'lineHeight', 'z.index'];
|
|
214
|
+
/** Figma `fontspacing.{n}`:字间距为字号的 n%(CSS 无 %,用 em 等比缩放)。 */
|
|
215
|
+
function isFontSpacingPath(figmaPath) {
|
|
216
|
+
return figmaPath.toLowerCase().startsWith('fontspacing.');
|
|
217
|
+
}
|
|
218
|
+
export function formatNumber(value, type, figmaPath) {
|
|
219
|
+
if (type === 'dimension')
|
|
220
|
+
return `${value}px`;
|
|
221
|
+
const lower = figmaPath.toLowerCase();
|
|
222
|
+
if (isFontSpacingPath(figmaPath)) {
|
|
223
|
+
return value === 0 ? '0' : `${value / 100}em`;
|
|
224
|
+
}
|
|
225
|
+
if (UNITLESS_PATH_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) {
|
|
226
|
+
return String(value);
|
|
227
|
+
}
|
|
228
|
+
if (PX_PATH_PATTERNS.some((p) => lower.includes(p))) {
|
|
229
|
+
return value === 0 ? '0' : `${value}px`;
|
|
230
|
+
}
|
|
231
|
+
return String(value);
|
|
232
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Map nested variant selector → enclosing block root (e.g. apex-main-switch → apex-switch).
|
|
3
|
+
* Single pass with a selector stack (aligned with parseComponentScopedCss).
|
|
4
|
+
*/
|
|
5
|
+
export declare function buildSelectorParentMap(css: string): Map<string, string>;
|
|
6
|
+
/** Resolve block root for any selector (nested → parent, root → self). */
|
|
7
|
+
export declare function blockRootForSelector(sel: string, parentOf: Map<string, string>): string;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { BLOCK_OPEN_RE, NESTED_OPEN_RE } from './parse-css-snapshot.js';
|
|
2
|
+
/**
|
|
3
|
+
* Map nested variant selector → enclosing block root (e.g. apex-main-switch → apex-switch).
|
|
4
|
+
* Single pass with a selector stack (aligned with parseComponentScopedCss).
|
|
5
|
+
*/
|
|
6
|
+
export function buildSelectorParentMap(css) {
|
|
7
|
+
const parentOf = new Map();
|
|
8
|
+
const stack = [];
|
|
9
|
+
for (const line of css.split('\n')) {
|
|
10
|
+
const trimmed = line.trim();
|
|
11
|
+
if (!trimmed || trimmed.startsWith('/*'))
|
|
12
|
+
continue;
|
|
13
|
+
const blockOpen = trimmed.match(BLOCK_OPEN_RE);
|
|
14
|
+
const nestedOpen = trimmed.match(NESTED_OPEN_RE);
|
|
15
|
+
if (blockOpen) {
|
|
16
|
+
stack.push(blockOpen[1]);
|
|
17
|
+
continue;
|
|
18
|
+
}
|
|
19
|
+
if (nestedOpen) {
|
|
20
|
+
const sel = nestedOpen[1];
|
|
21
|
+
const parent = stack[stack.length - 1];
|
|
22
|
+
if (parent)
|
|
23
|
+
parentOf.set(sel, parent);
|
|
24
|
+
stack.push(sel);
|
|
25
|
+
continue;
|
|
26
|
+
}
|
|
27
|
+
if (trimmed === '}') {
|
|
28
|
+
stack.pop();
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
return parentOf;
|
|
32
|
+
}
|
|
33
|
+
/** Resolve block root for any selector (nested → parent, root → self). */
|
|
34
|
+
export function blockRootForSelector(sel, parentOf) {
|
|
35
|
+
return parentOf.get(sel) ?? sel;
|
|
36
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tokens Studio JSON 中的单个 token。
|
|
3
|
+
*/
|
|
4
|
+
export interface RawW3CToken {
|
|
5
|
+
$value: string | number;
|
|
6
|
+
$type: string;
|
|
7
|
+
$description?: string;
|
|
8
|
+
$extensions?: Record<string, unknown>;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* 嵌套 token 树(Tokens Studio 输出结构)。
|
|
12
|
+
*/
|
|
13
|
+
export type TokenTree = {
|
|
14
|
+
[key: string]: TokenTree | RawW3CToken;
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* tokens/$metadata.json。
|
|
18
|
+
*/
|
|
19
|
+
export interface TokensMetadata {
|
|
20
|
+
tokenSetOrder: string[];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* 已读取的单个 token set。
|
|
24
|
+
*/
|
|
25
|
+
export interface TokenSet {
|
|
26
|
+
/** 在 metadata.tokenSetOrder 中的原始名(如 "palette/Mode 1") */
|
|
27
|
+
rawName: string;
|
|
28
|
+
/** 去掉 mode 后的归属(如 "palette"),用于 build 命令按层分文件 */
|
|
29
|
+
setKey: string;
|
|
30
|
+
/** Mode 名(如 "Mode 1"),若 set 没有多 Mode 则为 DEFAULT_MODE */
|
|
31
|
+
modeName: string;
|
|
32
|
+
/** 该 set 的 JSON 内容 */
|
|
33
|
+
content: TokenTree;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* 扁平化后未解引的 token(保留原始引用字符串)。
|
|
37
|
+
*/
|
|
38
|
+
export interface RawFlatToken {
|
|
39
|
+
/** Figma 内部路径,如 "fill.neutral.primary" */
|
|
40
|
+
figmaPath: string;
|
|
41
|
+
/** 原始值,可能是 "{ref}" / "#hex" / number */
|
|
42
|
+
rawValue: string | number;
|
|
43
|
+
/** $type */
|
|
44
|
+
type: string;
|
|
45
|
+
/** 描述(可选) */
|
|
46
|
+
description?: string;
|
|
47
|
+
/** 该 token 来自哪个 set(用于 build 分层 & 调试) */
|
|
48
|
+
setKey: string;
|
|
49
|
+
/** 该 token 属于哪个 mode */
|
|
50
|
+
modeName: string;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* 已解引、已加单位的 token。
|
|
54
|
+
*/
|
|
55
|
+
export interface FlatToken {
|
|
56
|
+
figmaPath: string;
|
|
57
|
+
/** 已解引的最终值(用于 d.ts、cheatsheet、diff) */
|
|
58
|
+
value: string;
|
|
59
|
+
/** 原始未解引的值,用于 cheatsheet 显示来源 */
|
|
60
|
+
rawValue: string | number;
|
|
61
|
+
/**
|
|
62
|
+
* 当 rawValue 为单一 `{path}` 且目标 token 存在时,emit CSS 输出
|
|
63
|
+
* `var(--apex-…)` 而非展平后的字面量。
|
|
64
|
+
*/
|
|
65
|
+
refTarget?: string;
|
|
66
|
+
type: string;
|
|
67
|
+
description?: string;
|
|
68
|
+
setKey: string;
|
|
69
|
+
modeName: string;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* 多 Mode 合并产物。
|
|
73
|
+
*/
|
|
74
|
+
export interface MergedTokens {
|
|
75
|
+
/** 第一个 Mode 的全部 token(写入 --scope) */
|
|
76
|
+
base: FlatToken[];
|
|
77
|
+
/** 其他 Mode:仅与 base 存在差异的 token(写入 [data-theme="<mode>"]) */
|
|
78
|
+
alts: Array<{
|
|
79
|
+
modeName: string;
|
|
80
|
+
tokens: FlatToken[];
|
|
81
|
+
}>;
|
|
82
|
+
}
|
|
83
|
+
/** 无多 Mode 时使用的占位名。 */
|
|
84
|
+
export declare const DEFAULT_MODE = "default";
|