@hia-doc/design-token-bridge 0.0.0-stage → 1.0.0-rc.2
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/API.md +64 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +10 -0
- package/README.md +22 -2
- package/package.json +39 -4
- package/src/index.mjs +154 -0
package/API.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Design Token Bridge API
|
|
2
|
+
|
|
3
|
+
中文:将显式DTCG样式JSON子集桥接为CSSDoc设计令牌符号,不是完整验证器或引用解析器。
|
|
4
|
+
|
|
5
|
+
## Public exports
|
|
6
|
+
|
|
7
|
+
`designTokensToCssExtraction(tokens, options?)` traverses token/group JSON and
|
|
8
|
+
projects design-token symbols. Only `.` is exported, without binaries or
|
|
9
|
+
schema resource subpaths.
|
|
10
|
+
|
|
11
|
+
## Inputs
|
|
12
|
+
|
|
13
|
+
Provide ordinary acyclic JSON parsed from a trusted token document and ordinary
|
|
14
|
+
options with optional `path`. A node owning `$value` is treated as a token;
|
|
15
|
+
groups can inherit `$type`, and `$root` projects a group-root token. The bridge
|
|
16
|
+
does not validate all DTCG names/types/values or resolve aliases/`$extends`.
|
|
17
|
+
Nonobject leaves are ignored; null/empty inputs produce an empty extraction.
|
|
18
|
+
|
|
19
|
+
## Returns
|
|
20
|
+
|
|
21
|
+
Returns `hia-cssdoc-extraction@1.0.0`, artifact profile `design-tokens@1.0.0`,
|
|
22
|
+
producer version `1.0.0`, token names, optional descriptions, type/value/deprecated/
|
|
23
|
+
extension metadata and synthetic source references. Some metadata values retain
|
|
24
|
+
the input's object references; clone before mutation. Input is not changed.
|
|
25
|
+
|
|
26
|
+
## Defaults
|
|
27
|
+
|
|
28
|
+
Path `tokens.json`; no source body; null map href and policy `none`. Type inherits
|
|
29
|
+
from groups or is null when unspecified. Source ranges are synthetic `1:1`.
|
|
30
|
+
`$schema` containing `/2025.10/` records that specification label, otherwise
|
|
31
|
+
retains the string or null; the label is not a conformance verdict.
|
|
32
|
+
|
|
33
|
+
## Errors
|
|
34
|
+
|
|
35
|
+
Unsafe path uses a fixed TypeError without echoing it. This API does not promise
|
|
36
|
+
fixed safe failures for cyclic/non-JSON objects, getters or arbitrary coercion;
|
|
37
|
+
parse/validate external JSON and apply disclosure rules before passing it here.
|
|
38
|
+
|
|
39
|
+
## Effects
|
|
40
|
+
|
|
41
|
+
Synchronous traversal, no I/O, network, file discovery, CSS generation, schema
|
|
42
|
+
loading, alias resolution or npm publication.
|
|
43
|
+
|
|
44
|
+
## Compatibility
|
|
45
|
+
|
|
46
|
+
The existing DTCG-style group/root/type subset is retained. CSS custom properties
|
|
47
|
+
and design tokens remain distinct. Exact old CSSDoc artifacts remain readable
|
|
48
|
+
through the spec/adapter; see [migration](MIGRATION.md).
|
|
49
|
+
|
|
50
|
+
## Source linkage
|
|
51
|
+
|
|
52
|
+
Token coordinates are placeholders, not parser-proven extents. Map output keeps
|
|
53
|
+
unknown conventions and adapter emits JSON references without exact fragments.
|
|
54
|
+
Token ids use local normalized slugs. Distinct case-sensitive names can normalize
|
|
55
|
+
to the same slug; the first id is preserved and later collisions use the existing
|
|
56
|
+
CSS `-2`, `-3` allocation in traversal order, including suffix collisions. Names
|
|
57
|
+
and values are unchanged. Downstream consumers must not interpret
|
|
58
|
+
them as DTCG reference syntax or source coordinates.
|
|
59
|
+
|
|
60
|
+
## Privacy
|
|
61
|
+
|
|
62
|
+
No body is embedded, but values, descriptions, extensions and relative paths are
|
|
63
|
+
still caller data. Lexical path checks are not content redaction or a filesystem
|
|
64
|
+
sandbox. Authorize them separately before publication.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HIA
|
|
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/MIGRATION.md
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Compatibility and migration
|
|
2
|
+
|
|
3
|
+
Writer provenance now uses 1.0.0. Existing noncolliding ids remain; later slug collisions now use the existing CSS numeric suffix allocation, retaining original names/values. JSON source references stay synthetic and do not gain exact extents. This is not full DTCG validation or alias resolution.
|
|
4
|
+
|
|
5
|
+
This source candidate does not imply registry publication. Node.js support is
|
|
6
|
+
`^22.23.4 || ^24.22.1`. Internal runtime dependencies are pinned to the matching
|
|
7
|
+
1.0.0 candidate cohort. See [API responsibilities](API.md) for inputs, ownership,
|
|
8
|
+
defaults, errors, effects, precision and privacy before adopting the package.
|
|
9
|
+
|
|
10
|
+
中文:包候选与真实发布分开;保留已确认的稳定子集和旧读责任,不按包号推定源码精度。
|
package/README.md
CHANGED
|
@@ -1,3 +1,23 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Design Token Bridge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Supported runtime
|
|
4
|
+
|
|
5
|
+
Current source supports Node.js `^22.23.4 || ^24.22.1`. Release checks use
|
|
6
|
+
Node.js 22.23.4 and 24.22.1 on Windows and Ubuntu; actual package qualification
|
|
7
|
+
and npm availability remain separate. The repository default is Node.js 24.22.1.
|
|
8
|
+
|
|
9
|
+
中文:当前源码运行范围为上述两条已确认版本线,CI/安装验收与实际npm发布分别核对。
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
Bridges design token artifacts into HIA-compatible documentation data.
|
|
13
|
+
|
|
14
|
+
Current output uses `hia-cssdoc-extraction@1.0.0` and its paired artifact profile. The existing input subset is unchanged; this is not a full CSS/DTCG validator. See the repository migration guide for exact historical reading and source-precision limits.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
## API and compatibility
|
|
18
|
+
|
|
19
|
+
See the packaged [API reference](API.md) and [migration notes](MIGRATION.md) for
|
|
20
|
+
all public entries, ownership, defaults, effects, source precision and privacy.
|
|
21
|
+
The package is a 1.0.0 source candidate; registry availability is a separate gate.
|
|
22
|
+
|
|
23
|
+
中文:公开责任与迁移文档随包提供;源码候选不代表已经发布npm。
|
package/package.json
CHANGED
|
@@ -1,6 +1,41 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/design-token-bridge",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0-rc.2",
|
|
4
|
+
"description": "Bridges design token artifacts to HIA-compatible documentation data.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./src/index.mjs"
|
|
9
|
+
},
|
|
10
|
+
"dependencies": {
|
|
11
|
+
"@hia-doc/cssdoc-spec": "1.0.0-rc.2"
|
|
12
|
+
},
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": "^22.23.4 || ^24.22.1"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"src",
|
|
18
|
+
"README.md",
|
|
19
|
+
"API.md",
|
|
20
|
+
"MIGRATION.md",
|
|
21
|
+
"LICENSE"
|
|
22
|
+
],
|
|
23
|
+
"publishConfig": {
|
|
24
|
+
"access": "public",
|
|
25
|
+
"registry": "https://registry.npmjs.org/"
|
|
26
|
+
},
|
|
27
|
+
"repository": {
|
|
28
|
+
"type": "git",
|
|
29
|
+
"url": "git+https://github.com/mandolin/hia-cssdoc.git",
|
|
30
|
+
"directory": "packages/design-token-bridge"
|
|
31
|
+
},
|
|
32
|
+
"homepage": "https://github.com/mandolin/hia-cssdoc/tree/main/packages/design-token-bridge",
|
|
33
|
+
"bugs": {
|
|
34
|
+
"url": "https://github.com/mandolin/hia-cssdoc/issues"
|
|
35
|
+
},
|
|
36
|
+
"keywords": [
|
|
37
|
+
"documentation",
|
|
38
|
+
"css",
|
|
39
|
+
"hia"
|
|
40
|
+
]
|
|
41
|
+
}
|
package/src/index.mjs
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file 有界DTCG样式JSON到CSSDoc桥接;保留语义值但不执行引用解析。
|
|
3
|
+
* @lang en Bounded DTCG-style JSON to CSSDoc bridge, preserving semantic values without reference resolution.
|
|
4
|
+
*/
|
|
5
|
+
import {
|
|
6
|
+
CSSDOC_EXTRACTION_CONTRACT,
|
|
7
|
+
CSSDOC_EXTRACTION_CONTRACT_VERSION,
|
|
8
|
+
CSSDOC_PROFILE_VERSION,
|
|
9
|
+
CSSDOC_SYMBOL_KINDS
|
|
10
|
+
} from "@hia-doc/cssdoc-spec";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* @lang zh-CN 按既有$value、$root及继承$type子集遍历设计令牌,生成保留组名称和合成1:1源码范围的CSS提取件。
|
|
14
|
+
* @lang en Traverses design tokens under the existing $value, $root and inherited-$type subset, producing a CSS extraction retaining group names and synthetic 1:1 source ranges.
|
|
15
|
+
* @param {object} tokens <lang><zh-CN>已解析的普通无环JSON;支持$value/group/$root/继承$type子集,不是完整validator。</zh-CN><en>Parsed ordinary acyclic JSON; supports the $value/group/$root/inherited-$type subset, not a complete validator.</en></lang>
|
|
16
|
+
* @param {Object} [options] <lang><zh-CN>设计令牌来源配置。</zh-CN><en>Design-token source options.</en></lang>
|
|
17
|
+
* @param {string} [options.path="tokens.json"] <lang><zh-CN>来源相对路径。</zh-CN><en>Relative source path.</en></lang>
|
|
18
|
+
* @returns {object} <lang><zh-CN>当前CSSDoc JSON;不改输入,但部分metadata值共享引用,1:1范围为合成占位。</zh-CN><en>Current CSSDoc JSON; input is unchanged but some metadata values share references and 1:1 ranges are synthetic placeholders.</en></lang>
|
|
19
|
+
* @throws {TypeError} <lang><zh-CN>来源路径不合法;任意非JSON/循环对象不在本API保证内。</zh-CN><en>Invalid source path; arbitrary non-JSON/cyclic objects are outside this API's guarantees.</en></lang>
|
|
20
|
+
*/
|
|
21
|
+
export function designTokensToCssExtraction(tokens, options = {}) {
|
|
22
|
+
// <lang><zh-CN>来源定位仅词法校验,不读文件。</zh-CN><en>Validate the source locator lexically without reading a file.</en></lang>
|
|
23
|
+
const sourcePath = normalizeSourcePath(options.path ?? "tokens.json");
|
|
24
|
+
// <lang><zh-CN>符号与去重集合均只属于本次遍历,不跨请求保留。</zh-CN><en>Symbols and allocated ids belong to this traversal only, never persisting across requests.</en></lang>
|
|
25
|
+
const symbols = [];
|
|
26
|
+
const usedIds = new Set();
|
|
27
|
+
collectTokens(tokens, [], symbols, sourcePath, null, usedIds);
|
|
28
|
+
|
|
29
|
+
return {
|
|
30
|
+
contract: CSSDOC_EXTRACTION_CONTRACT,
|
|
31
|
+
contractVersion: CSSDOC_EXTRACTION_CONTRACT_VERSION,
|
|
32
|
+
producer: {
|
|
33
|
+
name: "@hia-doc/design-token-bridge",
|
|
34
|
+
version: "1.0.0"
|
|
35
|
+
},
|
|
36
|
+
profile: {
|
|
37
|
+
name: "design-tokens",
|
|
38
|
+
version: CSSDOC_PROFILE_VERSION
|
|
39
|
+
},
|
|
40
|
+
source: {
|
|
41
|
+
kind: "design-tokens",
|
|
42
|
+
path: sourcePath
|
|
43
|
+
},
|
|
44
|
+
symbols,
|
|
45
|
+
annotations: [],
|
|
46
|
+
diagnostics: [],
|
|
47
|
+
sourceMap: {
|
|
48
|
+
kind: "hia-doc-source-map-ref",
|
|
49
|
+
href: null,
|
|
50
|
+
sourcesContentPolicy: "none"
|
|
51
|
+
},
|
|
52
|
+
metadata: {
|
|
53
|
+
format: "dtcg",
|
|
54
|
+
specification: inferDtcgSpecification(tokens?.$schema)
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* @param {unknown} node <lang><zh-CN>当前JSON节点,非对象叶忽略。</zh-CN><en>Current JSON node; nonobject leaves are ignored.</en></lang>
|
|
61
|
+
* @param {string[]} pathParts <lang><zh-CN>语义名称分段,不改变原始名称大小写。</zh-CN><en>Semantic name segments retaining original name case.</en></lang>
|
|
62
|
+
* @param {object[]} symbols <lang><zh-CN>本次遍历追加的符号。</zh-CN><en>Symbols appended by this traversal.</en></lang>
|
|
63
|
+
* @param {string} sourcePath <lang><zh-CN>已核相对来源。</zh-CN><en>Checked relative source.</en></lang>
|
|
64
|
+
* @param {string|null} inheritedType <lang><zh-CN>父组类型或未知。</zh-CN><en>Parent group type or unknown.</en></lang>
|
|
65
|
+
* @param {Set<string>} usedIds <lang><zh-CN>已分配局部标识,用既有CSS后缀策略避免slug碰撞。</zh-CN><en>Allocated local ids, using the existing CSS suffix strategy to avoid slug collisions.</en></lang>
|
|
66
|
+
* @returns {void} <lang><zh-CN>追加输出,不改变输入;metadata对象值仍可共享。</zh-CN><en>Appends output without changing input; metadata object values may still be shared.</en></lang>
|
|
67
|
+
*/
|
|
68
|
+
function collectTokens(node, pathParts, symbols, sourcePath, inheritedType, usedIds) {
|
|
69
|
+
// <lang><zh-CN>只把对象作为token/group;这不替代完整DTCG结构验证。</zh-CN><en>Only objects can be tokens/groups; this does not replace full DTCG structure validation.</en></lang>
|
|
70
|
+
if (!node || typeof node !== "object") {
|
|
71
|
+
return;
|
|
72
|
+
}
|
|
73
|
+
if (Object.hasOwn(node, "$value")) {
|
|
74
|
+
// <lang><zh-CN>展示名称保留原大小写;根token继续使用既有root名称。</zh-CN><en>Display names retain original case; root tokens keep the existing root name.</en></lang>
|
|
75
|
+
const name = pathParts.join(".") || "root";
|
|
76
|
+
// <lang><zh-CN>未提供描述时省略字段,保持真实JSON对象和既有字符串schema。</zh-CN><en>Omit an absent description to retain a real JSON object and the existing string schema.</en></lang>
|
|
77
|
+
symbols.push({
|
|
78
|
+
id: allocateId(`token:${slug(name)}`, usedIds),
|
|
79
|
+
kind: CSSDOC_SYMBOL_KINDS.designToken,
|
|
80
|
+
name,
|
|
81
|
+
...(node.$description ? { summary: node.$description } : {}),
|
|
82
|
+
source: {
|
|
83
|
+
path: sourcePath,
|
|
84
|
+
range: {
|
|
85
|
+
start: { line: 1, column: 1 },
|
|
86
|
+
end: { line: 1, column: 1 }
|
|
87
|
+
}
|
|
88
|
+
},
|
|
89
|
+
metadata: {
|
|
90
|
+
type: node.$type ?? inheritedType,
|
|
91
|
+
value: node.$value,
|
|
92
|
+
deprecated: node.$deprecated ?? null,
|
|
93
|
+
extensions: node.$extensions ?? null
|
|
94
|
+
}
|
|
95
|
+
});
|
|
96
|
+
return;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// <lang><zh-CN>局部组类型覆盖父类型,$root先投影到本组名称。</zh-CN><en>A local group type overrides its parent; $root projects to the group name first.</en></lang>
|
|
100
|
+
const groupType = node.$type ?? inheritedType;
|
|
101
|
+
if (node.$root && typeof node.$root === "object") {
|
|
102
|
+
collectTokens(node.$root, pathParts, symbols, sourcePath, groupType, usedIds);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
// <lang><zh-CN>按现有JSON成员顺序访问命名子节点;保留元数据键但不把它们当子token。</zh-CN><en>Visit named children in existing JSON member order; metadata keys are not child tokens.</en></lang>
|
|
106
|
+
for (const [key, value] of Object.entries(node)) {
|
|
107
|
+
if (key.startsWith("$")) {
|
|
108
|
+
continue;
|
|
109
|
+
}
|
|
110
|
+
collectTokens(value, [...pathParts, key], symbols, sourcePath, groupType, usedIds);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* @param {string} baseId <lang><zh-CN>既有规范化局部标识。</zh-CN><en>Existing normalized local id.</en></lang>
|
|
116
|
+
* @param {Set<string>} usedIds <lang><zh-CN>本次请求已分配集合。</zh-CN><en>Ids allocated in this request.</en></lang>
|
|
117
|
+
* @returns {string} <lang><zh-CN>首个ID保持;碰撞按CSS既有-2/-3顺序后缀,集合同步更新。</zh-CN><en>Preserves the first id; collisions use existing CSS -2/-3 suffixes and update the set.</en></lang>
|
|
118
|
+
*/
|
|
119
|
+
function allocateId(baseId, usedIds) {
|
|
120
|
+
// <lang><zh-CN>候选与计数器只作用于当前slug,不改变语义名称或值。</zh-CN><en>The candidate and counter affect this slug only, never semantic names or values.</en></lang>
|
|
121
|
+
let id = baseId;
|
|
122
|
+
let index = 2;
|
|
123
|
+
while (usedIds.has(id)) {
|
|
124
|
+
id = `${baseId}-${index}`;
|
|
125
|
+
index += 1;
|
|
126
|
+
}
|
|
127
|
+
usedIds.add(id);
|
|
128
|
+
return id;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
function inferDtcgSpecification(schema) {
|
|
132
|
+
if (typeof schema !== "string") {
|
|
133
|
+
return null;
|
|
134
|
+
}
|
|
135
|
+
return schema.includes("/2025.10/") ? "2025.10" : schema;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function slug(value) {
|
|
139
|
+
return String(value).trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-|-$/g, "") || "unnamed";
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* @param {unknown} sourcePath <lang><zh-CN>调用方显式来源定位器。</zh-CN><en>Explicit caller source locator.</en></lang>
|
|
144
|
+
* @returns {string} <lang><zh-CN>正斜杠安全相对路径;仅词法检查,不是symlink沙箱。</zh-CN><en>Slash-normalized safe relative path; lexical validation, not a symlink sandbox.</en></lang>
|
|
145
|
+
* @throws {TypeError} <lang><zh-CN>非字符串/URI/盘符/父级路径固定拒绝,不回显输入。</zh-CN><en>Fixed refusal of nonstrings, URIs, drive and parent paths without echoing input.</en></lang>
|
|
146
|
+
*/
|
|
147
|
+
function normalizeSourcePath(sourcePath) {
|
|
148
|
+
// <lang><zh-CN>来源边界在生成前拒绝私有定位器,不将其写进错误。</zh-CN><en>Reject private locators before generation without copying them into errors.</en></lang>
|
|
149
|
+
const normalized = typeof sourcePath === "string" ? sourcePath.replaceAll("\\", "/") : "";
|
|
150
|
+
if (!normalized || normalized.startsWith("/") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(normalized) || normalized.split("/").includes("..")) {
|
|
151
|
+
throw new TypeError("Unsafe design token source path.");
|
|
152
|
+
}
|
|
153
|
+
return normalized;
|
|
154
|
+
}
|