@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
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Apex UI Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,95 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @apexhub/apex-ui-design-token-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Apex UI 设计令牌 CLI。把 Figma(Tokens Studio 导出)的 `tokens/` 目录一键转成可消费的 CSS 变量 + TypeScript 类型 + Markdown 速查表。
|
|
4
|
+
|
|
5
|
+
## 安装与使用
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# 公开 npm 发布完成后,在项目中执行
|
|
9
|
+
npx @apexhub/apex-ui-design-token-cli theme --in ./tokens --out ./src/styles
|
|
10
|
+
|
|
11
|
+
# 产物:
|
|
12
|
+
# src/styles/apex-theme.css 主题 CSS(:root + 多 Mode 时的 [data-theme="dark"])
|
|
13
|
+
# src/styles/apex-tokens.d.ts 类型扩展(inline style 自动补全)
|
|
14
|
+
# src/styles/apex-tokens.md 可改 token 速查表
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
业务方 `app.ts`:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import '@apexhub/apex-ui-react/style.css' // 组件基础结构
|
|
21
|
+
import './styles/apex-theme.css' // 主题色(覆盖默认)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## 命令
|
|
25
|
+
|
|
26
|
+
### `apex-ui theme`(业务方主用)
|
|
27
|
+
|
|
28
|
+
| 参数 | 默认 | 说明 |
|
|
29
|
+
|------|------|------|
|
|
30
|
+
| `--in <dir>` | `./tokens` | 包含 `$metadata.json` 的目录 |
|
|
31
|
+
| `--out <dir>` | `./src/styles` | 产物输出目录 |
|
|
32
|
+
| `--scope <selector>` | `:root` | 主 Mode 的 CSS 选择器 |
|
|
33
|
+
| `--dark-selector <selector>` | `[data-theme="dark"]` | 暗色 Mode 的选择器 |
|
|
34
|
+
| `--no-dts` | 否 | 跳过类型生成 |
|
|
35
|
+
| `--no-cheatsheet` | 否 | 跳过 markdown 输出 |
|
|
36
|
+
| `--dry-run` | 否 | 只打印不写文件 |
|
|
37
|
+
|
|
38
|
+
### `apex-ui build`(Apex UI 仓库自用)
|
|
39
|
+
|
|
40
|
+
在 Apex UI 仓库内:`pnpm tokens:build`(`--in ./theme/tokens --out ./theme/src`)。
|
|
41
|
+
|
|
42
|
+
把 `tokens/` 解析为三层 CSS 文件,写入 `theme/src/`:
|
|
43
|
+
|
|
44
|
+
- `primitives.css`:`:root` 字面量(`palette` 色板 + `base value` 间距/尺寸/圆角等)
|
|
45
|
+
- `aliases.css`:`:root` 语义别名(`foundation`,`var()` 引用 palette)
|
|
46
|
+
- `component-tokens.css`:**组件作用域**嵌套 CSS,例如:
|
|
47
|
+
|
|
48
|
+
```css
|
|
49
|
+
.apex-button {
|
|
50
|
+
&.apex-main-md-button {
|
|
51
|
+
--button-gap: var(--apex-spacing-4);
|
|
52
|
+
}
|
|
53
|
+
&.apex-main-default-button {
|
|
54
|
+
--button-text-default: var(--apex-text-neutral-primary);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
组件 CSS(`button.css`)消费 `--button-*` 局部变量;色板变体 class(如 `apex-main-default-button`)与尺寸变体 class(如 `apex-main-md-button`)由生成文件赋值。
|
|
60
|
+
|
|
61
|
+
命名:Color = 组件/变体/结构/状态(四层);Number = 组件/尺寸或形态变体/结构(三层)。详见 `docs/design-tokens/01-命名规范.md`。
|
|
62
|
+
|
|
63
|
+
## 与 `/tokenSync`(仓库内)
|
|
64
|
+
|
|
65
|
+
Apex UI monorepo 在 `pnpm tokens:build` 之后运行:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pnpm tokens:impact # scripts/token-impact.mjs → .apex/token-sync-report.json
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Agent 工作流见 `.agents/skills/tokenSync/SKILL.md`(独立 skill,Handoff 到 `/apexComp plan` patch)。
|
|
72
|
+
|
|
73
|
+
### `build --report`(结构化 diff)
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
apex-ui build --in ./theme/tokens --out ./theme/src --report ./.apex/build-report.json
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
对比**写入前磁盘上的** `theme/src/*.css` 与本次生成内容,输出 JSON:
|
|
80
|
+
|
|
81
|
+
| 字段 | 说明 |
|
|
82
|
+
|------|------|
|
|
83
|
+
| `layers.primitives` / `aliases` | `varsAdded` / `varsRemoved` / `varsValueChanged` |
|
|
84
|
+
| `layers.component-tokens` | 同上 + `selectorsAdded` / `selectorsRemoved` |
|
|
85
|
+
|
|
86
|
+
仓库根目录 `pnpm tokens:build` 已默认带 `--report ./.apex/build-report.json`。
|
|
87
|
+
`pnpm tokens:impact` 优先读取该文件;不存在时回退 `git diff theme/src`。
|
|
88
|
+
|
|
89
|
+
## 设计原则
|
|
90
|
+
|
|
91
|
+
- **`tokens/` 是 CSS 变量的唯一真相源**。变量名直接由 Figma 路径派生,不维护任何 Figma→Apex 命名映射表。
|
|
92
|
+
- **CSS 链式引用**:`$value` 为单一 `{path}` 时输出 `var(--apex-…)`,字面量/表达式仍展平;加载顺序 `primitives → aliases → component-tokens`。
|
|
93
|
+
- **零运行时依赖**:保证 `npx` 拉取速度。
|
|
94
|
+
- **多 Mode 自动合并**:第一个 Mode 落到 `:root`,其余落到 `[data-theme="<mode>"]`。
|
|
95
|
+
- **set 间命名冲突**:按 `$metadata.json` 的 `tokenSetOrder` 后者覆盖前者,同时打 warning。
|
package/dist/bin.d.ts
ADDED
package/dist/bin.js
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import process from 'node:process';
|
|
3
|
+
import { runBuild } from './commands/build.js';
|
|
4
|
+
import { runTheme } from './commands/theme.js';
|
|
5
|
+
import { DEFAULT_GLOBAL_TOKEN_SCOPE } from './lib/emit-css.js';
|
|
6
|
+
import { DEFAULT_NAMESPACE } from './lib/path-to-var.js';
|
|
7
|
+
const HELP = `apex-ui — Apex UI design token CLI
|
|
8
|
+
|
|
9
|
+
Usage:
|
|
10
|
+
apex-ui theme [options] 生成主题 CSS / d.ts / cheatsheet(业务方)
|
|
11
|
+
apex-ui build [options] 按 tokens/ 重建 theme/src/ 三层 CSS(Apex UI 仓库自用)
|
|
12
|
+
|
|
13
|
+
Common options:
|
|
14
|
+
--in <dir> tokens 目录(默认 ./tokens)
|
|
15
|
+
--out <dir> 输出目录(theme 默认 ./src/styles;build 默认 ./theme/src)
|
|
16
|
+
--scope <selector> 主 Mode 选择器(默认 :root, :host)
|
|
17
|
+
--dark-selector <s> 暗色 Mode 选择器(默认 [data-theme="dark"])
|
|
18
|
+
--namespace <name> CSS 变量 / class 前缀(默认 "${DEFAULT_NAMESPACE}";小写 kebab,2-32 字符)
|
|
19
|
+
--no-dts 跳过类型生成(仅 theme)
|
|
20
|
+
--no-cheatsheet 跳过 markdown 输出(仅 theme)
|
|
21
|
+
--dry-run 只打印不写文件
|
|
22
|
+
--report <path> 写入结构化 diff JSON(仅 build;对比写入前磁盘 vs 本次生成)
|
|
23
|
+
-h, --help 查看本帮助
|
|
24
|
+
|
|
25
|
+
Examples:
|
|
26
|
+
npx @apexhub/apex-ui-design-token-cli theme --in ./tokens --out ./src/styles
|
|
27
|
+
npx @apexhub/apex-ui-design-token-cli theme --in ./tokens --out ./src/styles --namespace dino
|
|
28
|
+
apex-ui build --in ./tokens --out ./theme/src
|
|
29
|
+
`;
|
|
30
|
+
function parseArgs(argv) {
|
|
31
|
+
const flags = {};
|
|
32
|
+
let command;
|
|
33
|
+
for (let i = 0; i < argv.length; i++) {
|
|
34
|
+
const arg = argv[i];
|
|
35
|
+
if (!arg)
|
|
36
|
+
continue;
|
|
37
|
+
if (!arg.startsWith('-') && command === undefined) {
|
|
38
|
+
command = arg;
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
if (arg.startsWith('--')) {
|
|
42
|
+
const key = arg.slice(2);
|
|
43
|
+
const next = argv[i + 1];
|
|
44
|
+
if (next !== undefined && !next.startsWith('-')) {
|
|
45
|
+
flags[key] = next;
|
|
46
|
+
i++;
|
|
47
|
+
}
|
|
48
|
+
else {
|
|
49
|
+
flags[key] = true;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
else if (arg.startsWith('-')) {
|
|
53
|
+
flags[arg.slice(1)] = true;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
return { command, flags };
|
|
57
|
+
}
|
|
58
|
+
async function main() {
|
|
59
|
+
const argv = process.argv.slice(2);
|
|
60
|
+
const { command, flags } = parseArgs(argv);
|
|
61
|
+
if (flags.help || flags.h || command === 'help' || command === undefined) {
|
|
62
|
+
process.stdout.write(`${HELP}\n`);
|
|
63
|
+
process.exit(flags.help || flags.h || command === 'help' ? 0 : 1);
|
|
64
|
+
}
|
|
65
|
+
try {
|
|
66
|
+
switch (command) {
|
|
67
|
+
case 'theme':
|
|
68
|
+
await runTheme({
|
|
69
|
+
inDir: flags.in ?? './tokens',
|
|
70
|
+
outDir: flags.out ?? './src/styles',
|
|
71
|
+
scope: flags.scope ?? DEFAULT_GLOBAL_TOKEN_SCOPE,
|
|
72
|
+
darkSelector: flags['dark-selector'] ?? '[data-theme="dark"]',
|
|
73
|
+
emitDts: !flags['no-dts'],
|
|
74
|
+
emitCheatsheet: !flags['no-cheatsheet'],
|
|
75
|
+
dryRun: Boolean(flags['dry-run']),
|
|
76
|
+
namespace: flags.namespace ?? DEFAULT_NAMESPACE,
|
|
77
|
+
});
|
|
78
|
+
break;
|
|
79
|
+
case 'build':
|
|
80
|
+
await runBuild({
|
|
81
|
+
inDir: flags.in ?? './tokens',
|
|
82
|
+
outDir: flags.out ?? './theme/src',
|
|
83
|
+
dryRun: Boolean(flags['dry-run']),
|
|
84
|
+
reportPath: typeof flags.report === 'string' ? flags.report : undefined,
|
|
85
|
+
namespace: flags.namespace ?? DEFAULT_NAMESPACE,
|
|
86
|
+
});
|
|
87
|
+
break;
|
|
88
|
+
default:
|
|
89
|
+
process.stderr.write(`Unknown command: ${command}\n\n${HELP}\n`);
|
|
90
|
+
process.exit(1);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
catch (err) {
|
|
94
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
95
|
+
process.stderr.write(`[apex-ui] error: ${msg}\n`);
|
|
96
|
+
process.exit(1);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
main();
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export interface BuildOptions {
|
|
2
|
+
inDir: string;
|
|
3
|
+
/** Apex UI 仓库的 theme/src 目录 */
|
|
4
|
+
outDir: string;
|
|
5
|
+
dryRun: boolean;
|
|
6
|
+
/** 结构化 diff 报告路径(对比写入前的磁盘文件 vs 本次生成内容) */
|
|
7
|
+
reportPath?: string;
|
|
8
|
+
/** CSS 变量 / class 前缀,默认 {@link DEFAULT_NAMESPACE}("apex") */
|
|
9
|
+
namespace?: string;
|
|
10
|
+
}
|
|
11
|
+
export declare function runBuild(options: BuildOptions): Promise<void>;
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { createBuildReport, readLayerFile, writeBuildReport } from '../lib/build-report.js';
|
|
4
|
+
import { emitComponentScoped } from '../lib/emit-component-scoped.js';
|
|
5
|
+
import { DEFAULT_GLOBAL_TOKEN_SCOPE, emitCss } from '../lib/emit-css.js';
|
|
6
|
+
import { flattenSet } from '../lib/flatten.js';
|
|
7
|
+
import { mergeModes } from '../lib/merge-modes.js';
|
|
8
|
+
import { assertValidNamespace, DEFAULT_NAMESPACE } from '../lib/path-to-var.js';
|
|
9
|
+
import { readTokens } from '../lib/read-tokens.js';
|
|
10
|
+
import { resolveAllRefs } from '../lib/resolve-refs.js';
|
|
11
|
+
/**
|
|
12
|
+
* Apex UI 仓库自用:把 tokens/ 解析为三层 CSS。
|
|
13
|
+
*
|
|
14
|
+
* 分层规则(按 setKey 归类):
|
|
15
|
+
* - palette, base value → primitives.css(字面量:色板 + 间距/尺寸/圆角等尺度)
|
|
16
|
+
* - foundation → aliases.css(语义别名,引用 palette)
|
|
17
|
+
* - component, component usage → component-tokens.css
|
|
18
|
+
*
|
|
19
|
+
* 未识别的 setKey 一律归到 aliases.css(保守兜底),并打 warning。
|
|
20
|
+
*/
|
|
21
|
+
const LAYER_MAP = {
|
|
22
|
+
palette: 'primitives',
|
|
23
|
+
'base value': 'primitives',
|
|
24
|
+
foundation: 'aliases',
|
|
25
|
+
component: 'component-tokens',
|
|
26
|
+
'component usage': 'component-tokens',
|
|
27
|
+
};
|
|
28
|
+
const LAYER_FILES = {
|
|
29
|
+
primitives: 'primitives.css',
|
|
30
|
+
aliases: 'aliases.css',
|
|
31
|
+
'component-tokens': 'component-tokens.css',
|
|
32
|
+
};
|
|
33
|
+
export async function runBuild(options) {
|
|
34
|
+
const namespace = options.namespace ?? DEFAULT_NAMESPACE;
|
|
35
|
+
assertValidNamespace(namespace);
|
|
36
|
+
const { sets, modeNames } = readTokens(options.inDir);
|
|
37
|
+
const raw = [];
|
|
38
|
+
for (const s of sets)
|
|
39
|
+
raw.push(...flattenSet(s));
|
|
40
|
+
const resolved = resolveAllRefs(raw);
|
|
41
|
+
const merged = mergeModes(resolved, modeNames);
|
|
42
|
+
// 收集所有用到的 setKey → 决定要输出哪些 layer
|
|
43
|
+
const setKeysByLayer = {
|
|
44
|
+
primitives: new Set(),
|
|
45
|
+
aliases: new Set(),
|
|
46
|
+
'component-tokens': new Set(),
|
|
47
|
+
};
|
|
48
|
+
for (const s of sets) {
|
|
49
|
+
const layer = LAYER_MAP[s.setKey];
|
|
50
|
+
if (layer) {
|
|
51
|
+
setKeysByLayer[layer].add(s.setKey);
|
|
52
|
+
}
|
|
53
|
+
else {
|
|
54
|
+
process.stderr.write(`[apex-ui] warn: 未识别的 setKey "${s.setKey}",归到 aliases.css\n`);
|
|
55
|
+
setKeysByLayer.aliases.add(s.setKey);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
const stamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
|
|
59
|
+
const header = `Generated at ${stamp} from ${path.basename(path.resolve(options.inDir))}`;
|
|
60
|
+
const absOut = path.resolve(options.outDir);
|
|
61
|
+
const beforeSnapshots = {
|
|
62
|
+
primitives: readLayerFile(absOut, LAYER_FILES.primitives),
|
|
63
|
+
aliases: readLayerFile(absOut, LAYER_FILES.aliases),
|
|
64
|
+
'component-tokens': readLayerFile(absOut, LAYER_FILES['component-tokens']),
|
|
65
|
+
};
|
|
66
|
+
const products = [];
|
|
67
|
+
for (const layer of ['primitives', 'aliases']) {
|
|
68
|
+
const setKeys = [...setKeysByLayer[layer]];
|
|
69
|
+
if (setKeys.length === 0)
|
|
70
|
+
continue;
|
|
71
|
+
const content = emitCss(merged, {
|
|
72
|
+
scope: DEFAULT_GLOBAL_TOKEN_SCOPE,
|
|
73
|
+
darkSelector: '[data-theme="dark"]',
|
|
74
|
+
header: `${header} — ${layer} layer (${setKeys.join(', ')})`,
|
|
75
|
+
filterSetKey: setKeys,
|
|
76
|
+
namespace,
|
|
77
|
+
});
|
|
78
|
+
products.push({ filename: LAYER_FILES[layer], content });
|
|
79
|
+
}
|
|
80
|
+
const componentSetKeys = [...setKeysByLayer['component-tokens']];
|
|
81
|
+
if (componentSetKeys.length > 0) {
|
|
82
|
+
const content = emitComponentScoped(merged, {
|
|
83
|
+
header: `${header} — component layer (${componentSetKeys.join(', ')})`,
|
|
84
|
+
filterSetKey: componentSetKeys,
|
|
85
|
+
namespace,
|
|
86
|
+
});
|
|
87
|
+
products.push({ filename: LAYER_FILES['component-tokens'], content });
|
|
88
|
+
}
|
|
89
|
+
const afterByFilename = Object.fromEntries(products.map((p) => [p.filename, p.content]));
|
|
90
|
+
if (options.reportPath) {
|
|
91
|
+
const report = createBuildReport({
|
|
92
|
+
inDir: path.resolve(options.inDir),
|
|
93
|
+
outDir: absOut,
|
|
94
|
+
dryRun: options.dryRun,
|
|
95
|
+
before: beforeSnapshots,
|
|
96
|
+
after: {
|
|
97
|
+
primitives: afterByFilename[LAYER_FILES.primitives] ?? null,
|
|
98
|
+
aliases: afterByFilename[LAYER_FILES.aliases] ?? null,
|
|
99
|
+
'component-tokens': afterByFilename[LAYER_FILES['component-tokens']] ?? null,
|
|
100
|
+
},
|
|
101
|
+
});
|
|
102
|
+
writeBuildReport(options.reportPath, report);
|
|
103
|
+
}
|
|
104
|
+
if (options.dryRun) {
|
|
105
|
+
process.stdout.write(`[apex-ui] dry-run — 以下文件将被写入:\n`);
|
|
106
|
+
for (const p of products) {
|
|
107
|
+
process.stdout.write(` ${path.join(absOut, p.filename)} (${p.content.length} chars)\n`);
|
|
108
|
+
}
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
fs.mkdirSync(absOut, { recursive: true });
|
|
112
|
+
for (const p of products) {
|
|
113
|
+
const target = path.join(absOut, p.filename);
|
|
114
|
+
fs.writeFileSync(target, p.content, 'utf-8');
|
|
115
|
+
process.stdout.write(`[apex-ui] wrote ${target}\n`);
|
|
116
|
+
}
|
|
117
|
+
process.stdout.write(`[apex-ui] build done.\n`);
|
|
118
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export interface ThemeOptions {
|
|
2
|
+
inDir: string;
|
|
3
|
+
outDir: string;
|
|
4
|
+
scope: string;
|
|
5
|
+
darkSelector: string;
|
|
6
|
+
emitDts: boolean;
|
|
7
|
+
emitCheatsheet: boolean;
|
|
8
|
+
dryRun: boolean;
|
|
9
|
+
/** CSS 变量 / class 前缀,也决定输出文件名(`{namespace}-theme.css` 等),默认 {@link DEFAULT_NAMESPACE}("apex") */
|
|
10
|
+
namespace?: string;
|
|
11
|
+
}
|
|
12
|
+
export declare function runTheme(options: ThemeOptions): Promise<void>;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { emitCheatsheet } from '../lib/emit-cheatsheet.js';
|
|
4
|
+
import { emitComponentScoped } from '../lib/emit-component-scoped.js';
|
|
5
|
+
import { emitCss } from '../lib/emit-css.js';
|
|
6
|
+
import { emitDts } from '../lib/emit-dts.js';
|
|
7
|
+
import { flattenSet } from '../lib/flatten.js';
|
|
8
|
+
import { mergeModes } from '../lib/merge-modes.js';
|
|
9
|
+
import { assertValidNamespace, DEFAULT_NAMESPACE } from '../lib/path-to-var.js';
|
|
10
|
+
import { readTokens } from '../lib/read-tokens.js';
|
|
11
|
+
import { resolveAllRefs } from '../lib/resolve-refs.js';
|
|
12
|
+
export async function runTheme(options) {
|
|
13
|
+
const namespace = options.namespace ?? DEFAULT_NAMESPACE;
|
|
14
|
+
assertValidNamespace(namespace);
|
|
15
|
+
const { metadata, sets, modeNames } = readTokens(options.inDir);
|
|
16
|
+
const raw = [];
|
|
17
|
+
for (const s of sets)
|
|
18
|
+
raw.push(...flattenSet(s));
|
|
19
|
+
const resolved = resolveAllRefs(raw);
|
|
20
|
+
const merged = mergeModes(resolved, modeNames);
|
|
21
|
+
const stamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
|
|
22
|
+
const header = `Generated at ${stamp} from ${path.basename(path.resolve(options.inDir))} (${sets.length} sets, ${modeNames.length || 1} mode${modeNames.length > 1 ? 's' : ''})`;
|
|
23
|
+
const rootCss = emitCss(merged, {
|
|
24
|
+
scope: options.scope,
|
|
25
|
+
darkSelector: options.darkSelector,
|
|
26
|
+
header: `${header} — global tokens`,
|
|
27
|
+
filterSetKey: ['palette', 'foundation', 'base value', 'global'],
|
|
28
|
+
namespace,
|
|
29
|
+
});
|
|
30
|
+
const componentCss = emitComponentScoped(merged, {
|
|
31
|
+
header: `${header} — component tokens (scoped)`,
|
|
32
|
+
filterSetKey: ['component', 'component usage'],
|
|
33
|
+
namespace,
|
|
34
|
+
});
|
|
35
|
+
const css = `${rootCss}\n${componentCss}`;
|
|
36
|
+
const products = [
|
|
37
|
+
{ filename: `${namespace}-theme.css`, content: css },
|
|
38
|
+
];
|
|
39
|
+
if (options.emitDts) {
|
|
40
|
+
products.push({
|
|
41
|
+
filename: `${namespace}-tokens.d.ts`,
|
|
42
|
+
content: emitDts(merged, { header, namespace }),
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
if (options.emitCheatsheet) {
|
|
46
|
+
products.push({
|
|
47
|
+
filename: `${namespace}-tokens.md`,
|
|
48
|
+
content: emitCheatsheet(merged, { header, namespace }),
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
if (options.dryRun) {
|
|
52
|
+
process.stdout.write(`[apex-ui] dry-run — 跳过写入,以下文件将被生成:\n`);
|
|
53
|
+
for (const p of products) {
|
|
54
|
+
process.stdout.write(` ${path.join(options.outDir, p.filename)} (${p.content.length} chars)\n`);
|
|
55
|
+
}
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
const absOut = path.resolve(options.outDir);
|
|
59
|
+
fs.mkdirSync(absOut, { recursive: true });
|
|
60
|
+
for (const p of products) {
|
|
61
|
+
const target = path.join(absOut, p.filename);
|
|
62
|
+
fs.writeFileSync(target, p.content, 'utf-8');
|
|
63
|
+
process.stdout.write(`[apex-ui] wrote ${target}\n`);
|
|
64
|
+
}
|
|
65
|
+
process.stdout.write(`[apex-ui] done. ${merged.base.length} base tokens, ${merged.alts.length} alt mode(s).\n`);
|
|
66
|
+
// 仅供未来扩展使用(避免 unused warning)
|
|
67
|
+
void metadata;
|
|
68
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
export { runBuild } from './commands/build.js';
|
|
2
|
+
export { runTheme } from './commands/theme.js';
|
|
3
|
+
export type { BuildReport, LayerDiff, VarValueChange } from './lib/build-report.js';
|
|
4
|
+
export { createBuildReport, diffComponentBlocks, diffRootVars, writeBuildReport, } from './lib/build-report.js';
|
|
5
|
+
export { tokenCssValue } from './lib/css-value.js';
|
|
6
|
+
export { emitCheatsheet } from './lib/emit-cheatsheet.js';
|
|
7
|
+
export { emitComponentScoped } from './lib/emit-component-scoped.js';
|
|
8
|
+
export { DEFAULT_GLOBAL_TOKEN_SCOPE, emitCss } from './lib/emit-css.js';
|
|
9
|
+
export { emitDts } from './lib/emit-dts.js';
|
|
10
|
+
export { flattenSet } from './lib/flatten.js';
|
|
11
|
+
export { mergeModes, orderModeNames } from './lib/merge-modes.js';
|
|
12
|
+
export { componentBlockClass, componentLocalVar, parseComponentPath, variantScopeClass, } from './lib/parse-component-path.js';
|
|
13
|
+
export { parseComponentScopedCss, parseRootLayerCss, } from './lib/parse-css-snapshot.js';
|
|
14
|
+
export { assertValidNamespace, DEFAULT_NAMESPACE, isValidNamespace, pathToVar, } from './lib/path-to-var.js';
|
|
15
|
+
export { readTokens } from './lib/read-tokens.js';
|
|
16
|
+
export { parseSingleRef, REF_PATTERN, resolveAllRefs } from './lib/resolve-refs.js';
|
|
17
|
+
export { blockRootForSelector, buildSelectorParentMap } from './lib/selector-parent-map.js';
|
|
18
|
+
export * from './lib/types.js';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export { runBuild } from './commands/build.js';
|
|
2
|
+
export { runTheme } from './commands/theme.js';
|
|
3
|
+
export { createBuildReport, diffComponentBlocks, diffRootVars, writeBuildReport, } from './lib/build-report.js';
|
|
4
|
+
export { tokenCssValue } from './lib/css-value.js';
|
|
5
|
+
export { emitCheatsheet } from './lib/emit-cheatsheet.js';
|
|
6
|
+
export { emitComponentScoped } from './lib/emit-component-scoped.js';
|
|
7
|
+
export { DEFAULT_GLOBAL_TOKEN_SCOPE, emitCss } from './lib/emit-css.js';
|
|
8
|
+
export { emitDts } from './lib/emit-dts.js';
|
|
9
|
+
export { flattenSet } from './lib/flatten.js';
|
|
10
|
+
export { mergeModes, orderModeNames } from './lib/merge-modes.js';
|
|
11
|
+
export { componentBlockClass, componentLocalVar, parseComponentPath, variantScopeClass, } from './lib/parse-component-path.js';
|
|
12
|
+
export { parseComponentScopedCss, parseRootLayerCss, } from './lib/parse-css-snapshot.js';
|
|
13
|
+
export { assertValidNamespace, DEFAULT_NAMESPACE, isValidNamespace, pathToVar, } from './lib/path-to-var.js';
|
|
14
|
+
export { readTokens } from './lib/read-tokens.js';
|
|
15
|
+
export { parseSingleRef, REF_PATTERN, resolveAllRefs } from './lib/resolve-refs.js';
|
|
16
|
+
export { blockRootForSelector, buildSelectorParentMap } from './lib/selector-parent-map.js';
|
|
17
|
+
export * from './lib/types.js';
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { type ComponentBlockMap, type RootVarMap } from './parse-css-snapshot.js';
|
|
2
|
+
export interface VarValueChange {
|
|
3
|
+
before: string;
|
|
4
|
+
after: string;
|
|
5
|
+
}
|
|
6
|
+
export interface LayerDiff {
|
|
7
|
+
changed: boolean;
|
|
8
|
+
varsAdded: string[];
|
|
9
|
+
varsRemoved: string[];
|
|
10
|
+
varsValueChanged: Record<string, VarValueChange>;
|
|
11
|
+
selectorsAdded: string[];
|
|
12
|
+
selectorsRemoved: string[];
|
|
13
|
+
}
|
|
14
|
+
export interface BuildReport {
|
|
15
|
+
generatedAt: string;
|
|
16
|
+
inDir: string;
|
|
17
|
+
outDir: string;
|
|
18
|
+
dryRun: boolean;
|
|
19
|
+
layers: {
|
|
20
|
+
primitives: LayerDiff;
|
|
21
|
+
aliases: LayerDiff;
|
|
22
|
+
'component-tokens': LayerDiff;
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
export interface BuildReportInput {
|
|
26
|
+
inDir: string;
|
|
27
|
+
outDir: string;
|
|
28
|
+
dryRun: boolean;
|
|
29
|
+
before: {
|
|
30
|
+
primitives: string | null;
|
|
31
|
+
aliases: string | null;
|
|
32
|
+
'component-tokens': string | null;
|
|
33
|
+
};
|
|
34
|
+
after: {
|
|
35
|
+
primitives: string | null;
|
|
36
|
+
aliases: string | null;
|
|
37
|
+
'component-tokens': string | null;
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
export declare function diffRootVars(before: RootVarMap, after: RootVarMap): LayerDiff;
|
|
41
|
+
export declare function diffComponentBlocks(before: ComponentBlockMap, after: ComponentBlockMap): LayerDiff;
|
|
42
|
+
export declare function createBuildReport(input: BuildReportInput): BuildReport;
|
|
43
|
+
export declare function readLayerFile(outDir: string, filename: string): string | null;
|
|
44
|
+
export declare function writeBuildReport(reportPath: string, report: BuildReport): void;
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { parseComponentScopedCss, parseRootLayerCss, } from './parse-css-snapshot.js';
|
|
4
|
+
export function diffRootVars(before, after) {
|
|
5
|
+
const varsAdded = [];
|
|
6
|
+
const varsRemoved = [];
|
|
7
|
+
const varsValueChanged = {};
|
|
8
|
+
for (const name of Object.keys(after)) {
|
|
9
|
+
if (!(name in before))
|
|
10
|
+
varsAdded.push(name);
|
|
11
|
+
else if (before[name] !== after[name]) {
|
|
12
|
+
varsValueChanged[name] = { before: before[name], after: after[name] };
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
for (const name of Object.keys(before)) {
|
|
16
|
+
if (!(name in after))
|
|
17
|
+
varsRemoved.push(name);
|
|
18
|
+
}
|
|
19
|
+
const changed = varsAdded.length > 0 || varsRemoved.length > 0 || Object.keys(varsValueChanged).length > 0;
|
|
20
|
+
return {
|
|
21
|
+
changed,
|
|
22
|
+
varsAdded: varsAdded.sort(),
|
|
23
|
+
varsRemoved: varsRemoved.sort(),
|
|
24
|
+
varsValueChanged,
|
|
25
|
+
selectorsAdded: [],
|
|
26
|
+
selectorsRemoved: [],
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
export function diffComponentBlocks(before, after) {
|
|
30
|
+
const selectorsAdded = [];
|
|
31
|
+
const selectorsRemoved = [];
|
|
32
|
+
const varsAddedSet = new Set();
|
|
33
|
+
const varsRemovedSet = new Set();
|
|
34
|
+
const varsValueChanged = {};
|
|
35
|
+
const beforeKeys = Object.keys(before);
|
|
36
|
+
const afterKeys = Object.keys(after);
|
|
37
|
+
const seenSelectors = new Set();
|
|
38
|
+
for (const sel of beforeKeys) {
|
|
39
|
+
seenSelectors.add(sel);
|
|
40
|
+
if (!(sel in after))
|
|
41
|
+
selectorsRemoved.push(sel);
|
|
42
|
+
diffVarMaps(before[sel], after[sel] ?? {}, varsAddedSet, varsRemovedSet, varsValueChanged);
|
|
43
|
+
}
|
|
44
|
+
for (const sel of afterKeys) {
|
|
45
|
+
if (!seenSelectors.has(sel))
|
|
46
|
+
selectorsAdded.push(sel);
|
|
47
|
+
if (!(sel in before)) {
|
|
48
|
+
diffVarMaps({}, after[sel], varsAddedSet, varsRemovedSet, varsValueChanged);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
const changed = selectorsAdded.length > 0 ||
|
|
52
|
+
selectorsRemoved.length > 0 ||
|
|
53
|
+
varsAddedSet.size > 0 ||
|
|
54
|
+
varsRemovedSet.size > 0 ||
|
|
55
|
+
Object.keys(varsValueChanged).length > 0;
|
|
56
|
+
return {
|
|
57
|
+
changed,
|
|
58
|
+
varsAdded: [...varsAddedSet].sort(),
|
|
59
|
+
varsRemoved: [...varsRemovedSet].sort(),
|
|
60
|
+
varsValueChanged,
|
|
61
|
+
selectorsAdded: selectorsAdded.sort(),
|
|
62
|
+
selectorsRemoved: selectorsRemoved.sort(),
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
function diffVarMaps(b, a, added, removed, valueChanged) {
|
|
66
|
+
for (const name of Object.keys(a)) {
|
|
67
|
+
if (!(name in b))
|
|
68
|
+
added.add(name);
|
|
69
|
+
else if (b[name] !== a[name])
|
|
70
|
+
valueChanged[name] = { before: b[name], after: a[name] };
|
|
71
|
+
}
|
|
72
|
+
for (const name of Object.keys(b)) {
|
|
73
|
+
if (!(name in a))
|
|
74
|
+
removed.add(name);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
export function createBuildReport(input) {
|
|
78
|
+
const primitivesBefore = input.before.primitives ? parseRootLayerCss(input.before.primitives) : {};
|
|
79
|
+
const primitivesAfter = input.after.primitives ? parseRootLayerCss(input.after.primitives) : {};
|
|
80
|
+
const aliasesBefore = input.before.aliases ? parseRootLayerCss(input.before.aliases) : {};
|
|
81
|
+
const aliasesAfter = input.after.aliases ? parseRootLayerCss(input.after.aliases) : {};
|
|
82
|
+
const ctBefore = input.before['component-tokens']
|
|
83
|
+
? parseComponentScopedCss(input.before['component-tokens'])
|
|
84
|
+
: {};
|
|
85
|
+
const ctAfter = input.after['component-tokens']
|
|
86
|
+
? parseComponentScopedCss(input.after['component-tokens'])
|
|
87
|
+
: {};
|
|
88
|
+
return {
|
|
89
|
+
generatedAt: new Date().toISOString(),
|
|
90
|
+
inDir: input.inDir,
|
|
91
|
+
outDir: input.outDir,
|
|
92
|
+
dryRun: input.dryRun,
|
|
93
|
+
layers: {
|
|
94
|
+
primitives: diffRootVars(primitivesBefore, primitivesAfter),
|
|
95
|
+
aliases: diffRootVars(aliasesBefore, aliasesAfter),
|
|
96
|
+
'component-tokens': diffComponentBlocks(ctBefore, ctAfter),
|
|
97
|
+
},
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
export function readLayerFile(outDir, filename) {
|
|
101
|
+
const p = path.join(outDir, filename);
|
|
102
|
+
if (!fs.existsSync(p))
|
|
103
|
+
return null;
|
|
104
|
+
return fs.readFileSync(p, 'utf-8');
|
|
105
|
+
}
|
|
106
|
+
export function writeBuildReport(reportPath, report) {
|
|
107
|
+
const abs = path.resolve(reportPath);
|
|
108
|
+
fs.mkdirSync(path.dirname(abs), { recursive: true });
|
|
109
|
+
fs.writeFileSync(abs, `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
|
|
110
|
+
process.stdout.write(`[apex-ui] wrote report ${abs}\n`);
|
|
111
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { DEFAULT_NAMESPACE, pathToVar } from './path-to-var.js';
|
|
2
|
+
/**
|
|
3
|
+
* 把 token 转成写入 CSS 的值。
|
|
4
|
+
* 单一 `{path}` 引用 → `var(--{namespace}-…)`;其余用已解引的 value(字面量 / 表达式)。
|
|
5
|
+
*/
|
|
6
|
+
export function tokenCssValue(token, namespace = DEFAULT_NAMESPACE) {
|
|
7
|
+
if (token.refTarget) {
|
|
8
|
+
return `var(${pathToVar(token.refTarget, namespace)})`;
|
|
9
|
+
}
|
|
10
|
+
return token.value;
|
|
11
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { MergedTokens } from './types.js';
|
|
2
|
+
interface EmitCheatsheetOptions {
|
|
3
|
+
header?: string;
|
|
4
|
+
/** CSS 变量前缀,默认 {@link DEFAULT_NAMESPACE}("apex") */
|
|
5
|
+
namespace?: string;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* 业务方可覆盖 token 的速查表。按 setKey 分组列表。
|
|
9
|
+
*
|
|
10
|
+
* 输出格式:markdown,便于直接 `cat` 或在 IDE 预览。
|
|
11
|
+
*/
|
|
12
|
+
export declare function emitCheatsheet(merged: MergedTokens, options?: EmitCheatsheetOptions): string;
|
|
13
|
+
export {};
|