@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 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
- # Temporary Holding Version
1
+ # Design Token Bridge
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }