@lostgradient/cinder 0.27.1 → 0.28.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.
Files changed (261) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/components.json +1 -1
  3. package/dist/_internal/code-highlighter-context.d.ts +28 -0
  4. package/dist/cli/index.js +12 -8
  5. package/dist/components/approval-card/index.js +4 -4
  6. package/dist/components/button/button.css +25 -0
  7. package/dist/components/calendar/calendar.css +14 -0
  8. package/dist/components/capability-gate/capability-gate.css +5 -0
  9. package/dist/components/checkbox/checkbox.css +19 -0
  10. package/dist/components/chip/chip.css +14 -0
  11. package/dist/components/code-block/code-block.d.svelte.ts +1 -1
  12. package/dist/components/code-block/code-block.examples.json +1 -1
  13. package/dist/components/code-block/code-block.schema.js +3 -3
  14. package/dist/components/code-block/code-block.svelte.d.ts +1 -1
  15. package/dist/components/code-block/code-block.types.d.ts +14 -12
  16. package/dist/components/code-block/index.js +2 -2
  17. package/dist/components/color-picker/color-picker.css +2 -0
  18. package/dist/components/combobox/combobox.css +9 -1
  19. package/dist/components/command-palette/command-palette.css +7 -5
  20. package/dist/components/file-upload/file-upload.css +2 -1
  21. package/dist/components/guidance-region/index.css +1 -1
  22. package/dist/components/image/image.examples.json +1 -1
  23. package/dist/components/input/input.css +20 -6
  24. package/dist/components/json-schema-editor/index.js +5 -5
  25. package/dist/components/json-schema-editor/json-view-highlighter.d.ts +14 -0
  26. package/dist/components/key-value-editor/index.css +1 -1
  27. package/dist/components/modal-region/index.css +1 -1
  28. package/dist/components/multi-select/multi-select.css +9 -0
  29. package/dist/components/pagination/pagination.css +12 -0
  30. package/dist/components/pin-input/pin-input.css +9 -1
  31. package/dist/components/radio-group/radio-group.css +16 -0
  32. package/dist/components/run-step-timeline/index.js +2 -2
  33. package/dist/components/schema-form/index.js +2 -2
  34. package/dist/components/schema-form/schema-form.css +9 -0
  35. package/dist/components/segmented-control/segmented-control.css +3 -3
  36. package/dist/components/selection-popover/selection-popover.css +7 -1
  37. package/dist/components/tag-input/tag-input.css +10 -1
  38. package/dist/components/terminal-frame/index.js +2 -2
  39. package/dist/components/terminal-frame/terminal-frame.schema.js +2 -2
  40. package/dist/components/terminal-frame/terminal-frame.types.d.ts +8 -0
  41. package/dist/components/textarea/textarea.css +1 -1
  42. package/dist/components/toggle/toggle.css +16 -0
  43. package/dist/components/tree/tree.examples.json +1 -1
  44. package/dist/components/virtual-list/index.js +2 -2
  45. package/dist/components/virtual-list/virtual-list.css +42 -9
  46. package/dist/highlighters/shiki/default.d.ts +13 -1
  47. package/dist/highlighters/shiki/default.js +2 -2
  48. package/dist/highlighters/shiki/index.d.ts +20 -12
  49. package/dist/highlighters/shiki/index.js +2 -2
  50. package/dist/index.browser.css +1 -1
  51. package/dist/index.d.ts +2 -0
  52. package/dist/index.js +23 -23
  53. package/dist/scripts/knowledge/index.d.ts +5 -1
  54. package/dist/server/components/approval-card/index.js +1 -1
  55. package/dist/server/components/code-block/index.js +1 -1
  56. package/dist/server/components/color-field/index.js +2 -2
  57. package/dist/server/components/color-picker/index.js +2 -2
  58. package/dist/server/components/json-schema-editor/index.js +2 -2
  59. package/dist/server/components/run-step-timeline/index.js +1 -1
  60. package/dist/server/components/terminal-frame/index.js +1 -1
  61. package/dist/server/components/virtual-list/index.js +1 -1
  62. package/dist/server/github-dark-e7nywpbe.js +3 -0
  63. package/dist/server/github-light-bqtmm1zq.js +3 -0
  64. package/dist/server/highlighters/shiki/default.js +2 -2
  65. package/dist/server/highlighters/shiki/index.js +2 -2
  66. package/dist/server/index.js +6 -6
  67. package/dist/server/{index.server-4qyyw4y5.js → index.server-043cfznf.js} +1 -1
  68. package/dist/server/{index.server-p46tn4eb.js → index.server-09tjs48p.js} +2 -2
  69. package/dist/server/index.server-0hyvdf74.js +8 -0
  70. package/dist/server/{index.server-dxgkh9tk.js → index.server-17thvpd3.js} +1 -1
  71. package/dist/server/index.server-19z6hqd6.js +4 -0
  72. package/dist/server/index.server-31020qgk.js +3 -0
  73. package/dist/server/{index.server-w3nqzde5.js → index.server-45wmvjrn.js} +3 -3
  74. package/dist/server/{index.server-3tkgm2gn.js → index.server-6mb7w5g4.js} +2 -2
  75. package/dist/server/{index.server-2vxmn7x1.js → index.server-c5yajkkc.js} +4 -4
  76. package/dist/server/index.server-e6fknxd9.js +4 -0
  77. package/dist/server/index.server-fev4kwm0.js +4 -0
  78. package/dist/server/index.server-k4vjk75r.js +4 -0
  79. package/dist/server/index.server-mjbtd1gs.js +7 -0
  80. package/dist/server/{index.server-2bfkhzzq.js → index.server-rkp4py5n.js} +2 -2
  81. package/dist/server/index.server-wdz9tsq4.js +3 -0
  82. package/dist/server/index.server-zj9909hd.js +4 -0
  83. package/dist/server/json-68twtta3.js +3 -0
  84. package/dist/server/tokens/registry.generated.js +1 -1
  85. package/dist/server/tokens/runtime/index.js +92 -0
  86. package/dist/styles/check-token-contrast-test-values.d.ts +1 -3
  87. package/dist/styles/token-contrast-test-readers.d.ts +1 -1
  88. package/dist/tokens/registry.generated.js +2 -2
  89. package/dist/tokens/resolved/dark-reduced-motion.json +104 -43
  90. package/dist/tokens/resolved/dark.json +104 -43
  91. package/dist/tokens/resolved/light-reduced-motion.json +104 -43
  92. package/dist/tokens/resolved/light.json +104 -43
  93. package/dist/tokens/runtime/authoring-catalogue.d.ts +19 -0
  94. package/dist/tokens/runtime/authoring-catalogue.generated.d.ts +8 -0
  95. package/dist/tokens/runtime/authoring-palette.d.ts +25 -0
  96. package/dist/tokens/runtime/authoring-profiles.d.ts +48 -0
  97. package/dist/tokens/runtime/authoring-provenance.d.ts +31 -0
  98. package/dist/tokens/runtime/authoring-types.d.ts +182 -0
  99. package/dist/tokens/runtime/base-corpus.d.ts +29 -0
  100. package/dist/tokens/runtime/base-corpus.generated.d.ts +8 -0
  101. package/dist/tokens/runtime/context-order.d.ts +60 -0
  102. package/dist/tokens/runtime/context-stack.d.ts +11 -0
  103. package/dist/tokens/runtime/contrast/color-difference.d.ts +16 -0
  104. package/dist/{styles/color-contrast-utilities.d.ts → tokens/runtime/contrast/color-math.d.ts} +2 -17
  105. package/dist/tokens/runtime/contrast/color-mix.d.ts +3 -0
  106. package/dist/tokens/runtime/contrast/css-color.d.ts +29 -0
  107. package/dist/tokens/runtime/contrast/index.d.ts +7 -0
  108. package/dist/tokens/runtime/contrast/measure.d.ts +45 -0
  109. package/dist/tokens/runtime/contrast/pairings.d.ts +36 -0
  110. package/dist/tokens/runtime/contrast/thresholds.d.ts +47 -0
  111. package/dist/tokens/runtime/corpus-documents.d.ts +36 -0
  112. package/dist/tokens/runtime/corpus-validation.d.ts +10 -0
  113. package/dist/tokens/runtime/corpus.d.ts +35 -0
  114. package/dist/tokens/runtime/css-configuration.d.ts +1 -0
  115. package/dist/tokens/runtime/css-stylelint.d.ts +2 -0
  116. package/dist/tokens/runtime/css-support.d.ts +110 -0
  117. package/dist/tokens/runtime/evaluate.d.ts +95 -0
  118. package/dist/tokens/runtime/evaluated-provenance.d.ts +36 -0
  119. package/dist/tokens/runtime/index.d.ts +38 -0
  120. package/dist/tokens/runtime/index.js +95 -0
  121. package/dist/tokens/runtime/package-version.generated.d.ts +9 -0
  122. package/dist/tokens/runtime/projection.d.ts +32 -0
  123. package/dist/tokens/runtime/registry.d.ts +125 -0
  124. package/dist/tokens/runtime/resolve-extends.d.ts +30 -0
  125. package/dist/tokens/runtime/resolve-references.d.ts +49 -0
  126. package/dist/tokens/runtime/resolve-shared.d.ts +34 -0
  127. package/dist/tokens/runtime/resolve.d.ts +44 -0
  128. package/dist/tokens/runtime/resolver-order.d.ts +89 -0
  129. package/dist/tokens/runtime/source-digest.d.ts +20 -0
  130. package/dist/tokens/runtime/stylesheet-skeleton.d.ts +31 -0
  131. package/dist/tokens/runtime/theme-runtime.test-support.d.ts +24 -0
  132. package/dist/tokens/runtime/theme-sources.d.ts +46 -0
  133. package/dist/tokens/runtime/theme-stylesheet.d.ts +31 -0
  134. package/dist/tokens/runtime/types.d.ts +115 -0
  135. package/dist/tokens/runtime/validate-resolver.d.ts +31 -0
  136. package/dist/tokens/runtime/validate-schema.d.ts +22 -0
  137. package/dist/tokens/runtime/validate-tokens.d.ts +25 -0
  138. package/dist/tokens/runtime/validate-values.d.ts +33 -0
  139. package/dist/tokens/runtime/validate.d.ts +3 -0
  140. package/dist/tokens/runtime/value-color-parse.d.ts +128 -0
  141. package/dist/tokens/runtime/value-color.d.ts +85 -0
  142. package/dist/tokens/runtime/value-entry.d.ts +3 -0
  143. package/dist/tokens/runtime/value-formatters.d.ts +59 -0
  144. package/dist/tokens/sets/colors.tokens.json +65 -13
  145. package/dist/tokens/sets/foundation.tokens.json +23 -0
  146. package/dist/tokens/sets/semantic.tokens.json +136 -30
  147. package/dist/utilities/highlighter.d.ts +5 -5
  148. package/dist/utilities/retrying-loader-cache.d.ts +3 -6
  149. package/package.json +15 -3
  150. package/src/_internal/code-highlighter-context.ts +41 -0
  151. package/src/components/button/button.css +25 -0
  152. package/src/components/calendar/calendar.css +14 -0
  153. package/src/components/capability-gate/capability-gate.css +5 -0
  154. package/src/components/checkbox/checkbox.css +19 -0
  155. package/src/components/chip/chip.css +14 -0
  156. package/src/components/code-block/code-block.examples.json +1 -1
  157. package/src/components/code-block/code-block.schema.json +2 -2
  158. package/src/components/code-block/code-block.schema.ts +2 -2
  159. package/src/components/code-block/code-block.svelte +15 -19
  160. package/src/components/code-block/code-block.types.ts +14 -12
  161. package/src/components/color-picker/color-picker.css +2 -0
  162. package/src/components/combobox/combobox.css +9 -1
  163. package/src/components/command-palette/command-palette.css +7 -5
  164. package/src/components/file-upload/file-upload.css +2 -1
  165. package/src/components/image/image.examples.json +1 -1
  166. package/src/components/input/input.css +20 -6
  167. package/src/components/json-schema-editor/json-view-highlighter.ts +23 -0
  168. package/src/components/json-schema-editor/json-view.svelte +2 -0
  169. package/src/components/multi-select/multi-select.css +9 -0
  170. package/src/components/pagination/pagination.css +12 -0
  171. package/src/components/pin-input/pin-input.css +9 -1
  172. package/src/components/radio-group/radio-group.css +16 -0
  173. package/src/components/schema-form/schema-form.css +9 -0
  174. package/src/components/segmented-control/segmented-control.css +3 -3
  175. package/src/components/selection-popover/selection-popover.css +7 -1
  176. package/src/components/tag-input/tag-input.css +10 -1
  177. package/src/components/terminal-frame/terminal-frame.schema.json +5 -0
  178. package/src/components/terminal-frame/terminal-frame.schema.ts +6 -0
  179. package/src/components/terminal-frame/terminal-frame.svelte +6 -2
  180. package/src/components/terminal-frame/terminal-frame.types.ts +8 -0
  181. package/src/components/textarea/textarea.css +1 -1
  182. package/src/components/toggle/toggle.css +16 -0
  183. package/src/components/tree/tree.examples.json +1 -1
  184. package/src/components/virtual-list/virtual-list.css +42 -9
  185. package/src/components/virtual-list/virtual-list.svelte +54 -20
  186. package/src/highlighters/shiki/default.ts +13 -1
  187. package/src/highlighters/shiki/index.ts +20 -12
  188. package/src/index.ts +5 -0
  189. package/src/styles/foundation.css +33 -1
  190. package/src/styles/tokens-base.css +4 -4
  191. package/src/tokens/registry.generated.json +3 -3
  192. package/src/tokens/resolved/dark-reduced-motion.json +104 -43
  193. package/src/tokens/resolved/dark.json +104 -43
  194. package/src/tokens/resolved/light-reduced-motion.json +104 -43
  195. package/src/tokens/resolved/light.json +104 -43
  196. package/src/tokens/runtime/authoring-catalogue.generated.ts +19300 -0
  197. package/src/tokens/runtime/authoring-catalogue.ts +256 -0
  198. package/src/tokens/runtime/authoring-palette.ts +100 -0
  199. package/src/tokens/runtime/authoring-profiles.ts +288 -0
  200. package/src/tokens/runtime/authoring-provenance.ts +290 -0
  201. package/src/tokens/runtime/authoring-types.ts +199 -0
  202. package/src/tokens/runtime/base-corpus.generated.ts +10 -0
  203. package/src/tokens/runtime/base-corpus.ts +78 -0
  204. package/src/tokens/runtime/context-order.ts +182 -0
  205. package/src/tokens/runtime/context-stack.ts +52 -0
  206. package/src/tokens/runtime/contrast/color-difference.ts +114 -0
  207. package/src/tokens/runtime/contrast/color-math.ts +89 -0
  208. package/src/tokens/runtime/contrast/color-mix.ts +20 -0
  209. package/src/tokens/runtime/contrast/css-color.ts +312 -0
  210. package/src/tokens/runtime/contrast/index.ts +7 -0
  211. package/src/tokens/runtime/contrast/measure.ts +185 -0
  212. package/src/tokens/runtime/contrast/pairings.ts +324 -0
  213. package/src/tokens/runtime/contrast/thresholds.ts +81 -0
  214. package/src/tokens/runtime/corpus-documents.ts +289 -0
  215. package/src/tokens/runtime/corpus-validation.ts +336 -0
  216. package/src/tokens/runtime/corpus.ts +179 -0
  217. package/src/tokens/runtime/css-configuration.ts +1 -0
  218. package/src/tokens/runtime/css-stylelint.ts +15 -0
  219. package/src/tokens/runtime/css-support.ts +407 -0
  220. package/src/tokens/runtime/evaluate.ts +262 -0
  221. package/src/tokens/runtime/evaluated-provenance.ts +116 -0
  222. package/src/tokens/runtime/format-validator.generated.d.ts +18 -0
  223. package/src/tokens/runtime/format-validator.generated.js +13029 -0
  224. package/src/tokens/runtime/index.ts +78 -0
  225. package/src/tokens/runtime/package-version.generated.ts +9 -0
  226. package/src/tokens/runtime/projection.ts +65 -0
  227. package/src/tokens/runtime/registry.ts +365 -0
  228. package/src/tokens/runtime/resolve-extends.ts +211 -0
  229. package/src/tokens/runtime/resolve-references.ts +313 -0
  230. package/src/tokens/runtime/resolve-shared.ts +186 -0
  231. package/src/tokens/runtime/resolve.ts +246 -0
  232. package/src/tokens/runtime/resolver-order.ts +326 -0
  233. package/src/tokens/runtime/resolver-validator.generated.d.ts +18 -0
  234. package/src/tokens/runtime/resolver-validator.generated.js +15492 -0
  235. package/src/tokens/runtime/source-digest.ts +49 -0
  236. package/src/tokens/runtime/stylesheet-skeleton.ts +123 -0
  237. package/src/tokens/runtime/theme-sources.ts +121 -0
  238. package/src/tokens/runtime/theme-stylesheet.ts +177 -0
  239. package/src/tokens/runtime/types.ts +140 -0
  240. package/src/tokens/runtime/validate-resolver.ts +338 -0
  241. package/src/tokens/runtime/validate-schema.ts +269 -0
  242. package/src/tokens/runtime/validate-tokens.ts +181 -0
  243. package/src/tokens/runtime/validate-values.ts +396 -0
  244. package/src/tokens/runtime/validate.ts +57 -0
  245. package/src/tokens/runtime/value-color-parse.ts +309 -0
  246. package/src/tokens/runtime/value-color.ts +217 -0
  247. package/src/tokens/runtime/value-entry.ts +52 -0
  248. package/src/tokens/runtime/value-formatters.ts +414 -0
  249. package/src/tokens/sets/colors.tokens.json +65 -13
  250. package/src/tokens/sets/foundation.tokens.json +23 -0
  251. package/src/tokens/sets/semantic.tokens.json +136 -30
  252. package/src/utilities/highlighter.ts +5 -5
  253. package/src/utilities/retrying-loader-cache.ts +3 -6
  254. package/dist/components/code-block/code-block-default-highlighter.d.ts +0 -40
  255. package/dist/server/index.server-298z43yn.js +0 -4
  256. package/dist/server/index.server-3h11wjyh.js +0 -8
  257. package/dist/server/index.server-a3aerbfr.js +0 -4
  258. package/dist/server/index.server-kge3zp6n.js +0 -4
  259. package/dist/server/index.server-syf81nwz.js +0 -6
  260. package/dist/server/index.server-zs08f5te.js +0 -3
  261. package/src/components/code-block/code-block-default-highlighter.ts +0 -63
@@ -0,0 +1,211 @@
1
+ import {
2
+ clone,
3
+ collectGroups,
4
+ extensionIssue,
5
+ type ExtensionOrigins,
6
+ issue,
7
+ isTokenGroup,
8
+ tokenPathFromReference,
9
+ } from './resolve-shared.ts';
10
+ import type { TokenGroup } from './types.ts';
11
+ import { TokenValidationError } from './types.ts';
12
+
13
+ export function inheritMissingGroupMembers(
14
+ target: TokenGroup,
15
+ source: TokenGroup,
16
+ extensionOrigins?: ExtensionOrigins,
17
+ ): void {
18
+ for (const [name, value] of Object.entries(source)) {
19
+ const existing = target[name];
20
+ if (isTokenGroup(existing) && isTokenGroup(value))
21
+ inheritMissingGroupMembers(existing, value, extensionOrigins);
22
+ else if (!Object.hasOwn(target, name)) {
23
+ Object.defineProperty(target, name, {
24
+ configurable: true,
25
+ enumerable: true,
26
+ value: clone(value, extensionOrigins),
27
+ writable: true,
28
+ });
29
+ if (name === '$extends') {
30
+ const origin = extensionOrigins?.get(source);
31
+ if (origin) extensionOrigins?.set(target, origin);
32
+ }
33
+ }
34
+ }
35
+ }
36
+
37
+ /**
38
+ * The `$deprecated` a group at `groupPath` carries EFFECTIVELY, once ordinary
39
+ * (non-`$extends`) ancestor nesting is taken into account -- the nearest of
40
+ * the group itself, its parent, its grandparent, and so on that declares
41
+ * `$deprecated` directly. `groups` is keyed by the RAW merged tree
42
+ * (`collectGroups`, run before any `$extends` expansion), so this reads each
43
+ * candidate's own declared value only; it does not itself resolve a further
44
+ * `$extends` chain on an ancestor (a deeper edge case -- an ancestor that is
45
+ * itself only deprecated via its OWN `$extends` -- outside what this helper
46
+ * addresses).
47
+ *
48
+ * `resolveExtends` needs this rather than a plain `extended.$deprecated`
49
+ * property read: `generate.ts`'s `collectEntries` propagates `$deprecated`
50
+ * down through ordinary group nesting at CSS/registry generation time, well
51
+ * after `$extends` has already run here, so a group that inherits
52
+ * `$deprecated` only from an ANCESTOR (never declaring it directly itself)
53
+ * still reads `undefined` at this point unless this helper walks up for it.
54
+ * Without it, `derived: { $extends: '{outer.base}' }` under a deprecated
55
+ * `outer` (with `outer.base` itself never declaring `$deprecated`) copied no
56
+ * deprecation onto `derived` at all, even though every token under
57
+ * `outer.base` is itself effectively deprecated by the time generation walks
58
+ * it.
59
+ */
60
+ export function effectiveGroupDeprecated(
61
+ groupPath: string,
62
+ groups: Map<string, TokenGroup>,
63
+ ): TokenGroup['$deprecated'] {
64
+ const segments = groupPath === '' ? [] : groupPath.split('.');
65
+ for (let end = segments.length; end >= 0; end -= 1) {
66
+ const candidate = groups.get(segments.slice(0, end).join('.'));
67
+ if (candidate?.$deprecated !== undefined) return candidate.$deprecated;
68
+ }
69
+ return undefined;
70
+ }
71
+
72
+ export function effectiveGroupType(
73
+ groupPath: string,
74
+ groups: Map<string, TokenGroup>,
75
+ ): TokenGroup['$type'] {
76
+ const segments = groupPath === '' ? [] : groupPath.split('.');
77
+ for (let end = segments.length; end >= 0; end -= 1) {
78
+ const candidate = groups.get(segments.slice(0, end).join('.'));
79
+ if (candidate?.$type !== undefined) return candidate.$type;
80
+ }
81
+ return undefined;
82
+ }
83
+
84
+ export function groupMetadataBase(
85
+ group: TokenGroup,
86
+ groupPath: string,
87
+ groups: Map<string, TokenGroup>,
88
+ ): TokenGroup {
89
+ const type = group.$type ?? effectiveGroupType(groupPath, groups);
90
+ const deprecated =
91
+ group.$deprecated === undefined
92
+ ? effectiveGroupDeprecated(groupPath, groups)
93
+ : group.$deprecated;
94
+ if (type === undefined && deprecated === undefined) return group;
95
+ return {
96
+ ...group,
97
+ ...(type === undefined ? {} : { $type: type }),
98
+ ...(deprecated === undefined ? {} : { $deprecated: deprecated }),
99
+ };
100
+ }
101
+
102
+ export function resolveExtends(
103
+ groupPath: string,
104
+ groups: Map<string, TokenGroup>,
105
+ visiting: Set<string>,
106
+ complete: Set<string>,
107
+ lookupGroups: Map<string, TokenGroup> = groups,
108
+ extensionOrigins?: ExtensionOrigins,
109
+ ): TokenGroup {
110
+ const group = groups.get(groupPath);
111
+ if (!group) return issue(groupPath, '$extends must reference an existing group');
112
+ if (complete.has(groupPath)) return group;
113
+ if (visiting.has(groupPath))
114
+ return extensionIssue(groupPath, 'circular $extends reference', group, extensionOrigins);
115
+ visiting.add(groupPath);
116
+ if (group.$extends) {
117
+ let extendedPath: string;
118
+ try {
119
+ extendedPath = tokenPathFromReference(group.$extends);
120
+ } catch (error) {
121
+ if (error instanceof TokenValidationError && extensionOrigins?.has(group))
122
+ return extensionIssue(
123
+ groupPath,
124
+ error.issues.map((entry) => entry.reason).join('; '),
125
+ group,
126
+ extensionOrigins,
127
+ );
128
+ throw error;
129
+ }
130
+ if (!groups.has(extendedPath)) {
131
+ return extensionIssue(
132
+ extendedPath,
133
+ '$extends must reference an existing group',
134
+ group,
135
+ extensionOrigins,
136
+ );
137
+ }
138
+ if (visiting.has(extendedPath)) {
139
+ return extensionIssue(extendedPath, 'circular $extends reference', group, extensionOrigins);
140
+ }
141
+ const extended = resolveExtends(
142
+ extendedPath,
143
+ groups,
144
+ visiting,
145
+ complete,
146
+ lookupGroups,
147
+ extensionOrigins,
148
+ );
149
+ if (group.$type === undefined && extended.$type !== undefined) group.$type = extended.$type;
150
+ // `$deprecated: false` is a real, meaningful value (it un-deprecates a
151
+ // subtree under a deprecated ancestor) rather than an absence, so this
152
+ // must check `=== undefined` and assign directly -- the same `??`-not-`||`
153
+ // rule `generate.ts`'s `collectEntries` already applies for ordinary
154
+ // group nesting (see CIN-471). Nested extended groups already inherit
155
+ // `$deprecated` through `inheritMissingGroupMembers`'s unfiltered member
156
+ // copy below; this closes the top-level gap, where the extending group's
157
+ // OWN `$deprecated` was previously left untouched even when the group it
158
+ // extends was itself deprecated -- including when the extended group's
159
+ // `$deprecated` is itself only inherited from ITS OWN ancestor rather
160
+ // than declared directly (`effectiveGroupDeprecated`, not a bare property
161
+ // read).
162
+ // Resolve any ancestor `$extends` chains before reading their effective
163
+ // deprecation. This makes inheritance independent of declaration order.
164
+ const ancestors = extendedPath ? extendedPath.split('.') : [];
165
+ for (let end = ancestors.length; end >= 0; end -= 1) {
166
+ const ancestorPath = ancestors.slice(0, end).join('.');
167
+ if (groups.get(ancestorPath)?.$extends)
168
+ resolveExtends(ancestorPath, groups, visiting, complete, lookupGroups, extensionOrigins);
169
+ if (lookupGroups.get(ancestorPath)?.$extends)
170
+ resolveExtends(
171
+ ancestorPath,
172
+ lookupGroups,
173
+ new Set(),
174
+ new Set(),
175
+ lookupGroups,
176
+ extensionOrigins,
177
+ );
178
+ }
179
+ const effectiveExtendedDeprecated =
180
+ effectiveGroupDeprecated(extendedPath, groups) ??
181
+ effectiveGroupDeprecated(extendedPath, lookupGroups);
182
+ if (group.$deprecated === undefined && effectiveExtendedDeprecated !== undefined)
183
+ group.$deprecated = effectiveExtendedDeprecated;
184
+ for (const [name, value] of Object.entries(extended))
185
+ if (!name.startsWith('$') || name === '$root') {
186
+ const existing = group[name];
187
+ if (isTokenGroup(existing) && isTokenGroup(value))
188
+ inheritMissingGroupMembers(existing, value, extensionOrigins);
189
+ else if (!Object.hasOwn(group, name))
190
+ Object.defineProperty(group, name, {
191
+ configurable: true,
192
+ enumerable: true,
193
+ value: clone(value, extensionOrigins),
194
+ writable: true,
195
+ });
196
+ }
197
+ // `$extends` may add a group that an ordinary nested wrapper references.
198
+ // Register the expanded tree before traversing those wrappers so their
199
+ // targets are visible to the same path index used by resolveExtends.
200
+ collectGroups(group, groupPath, groups);
201
+ }
202
+ for (const [name, value] of Object.entries(group)) {
203
+ if (name.startsWith('$') || !isTokenGroup(value)) continue;
204
+ const nestedPath = groupPath ? `${groupPath}.${name}` : name;
205
+ if (groups.get(nestedPath)?.$extends)
206
+ resolveExtends(nestedPath, groups, visiting, complete, lookupGroups, extensionOrigins);
207
+ }
208
+ visiting.delete(groupPath);
209
+ complete.add(groupPath);
210
+ return group;
211
+ }
@@ -0,0 +1,313 @@
1
+ import { groupMetadataBase } from './resolve-extends.ts';
2
+ import {
3
+ type JsonObject,
4
+ type RawRefs,
5
+ type ResolvedTokens,
6
+ clone,
7
+ getByPath,
8
+ isObject,
9
+ issue,
10
+ pointerSegments,
11
+ tokenPathFromReference,
12
+ } from './resolve-shared.ts';
13
+ import type { DesignToken, TokenGroup } from './types.ts';
14
+ import { TokenValidationError } from './types.ts';
15
+
16
+ export function resolveReference(
17
+ reference: string,
18
+ tokens: ResolvedTokens,
19
+ rawRefs: RawRefs,
20
+ rootTokenPaths: Set<string>,
21
+ resolving: Set<string>,
22
+ groups: Map<string, TokenGroup>,
23
+ completed: Set<string>,
24
+ ): unknown {
25
+ if (reference === '#/') return issue(reference, 'reference target does not exist');
26
+ const segments = reference.startsWith('#/')
27
+ ? pointerSegments(reference)
28
+ : reference.slice(1, -1).split('.');
29
+ // The document itself is also the root group. When it carries both group
30
+ // metadata and a `$root` token, document-level metadata pointers must read
31
+ // the group object unless `$root` is explicitly present.
32
+ const documentGroup = groups.get('');
33
+ if (
34
+ reference.startsWith('#/') &&
35
+ documentGroup &&
36
+ typeof segments[0] === 'string' &&
37
+ segments[0].startsWith('$') &&
38
+ segments[0] !== '$root' &&
39
+ segments[0] !== '$value'
40
+ ) {
41
+ const propertyValue = getByPath(documentGroup, segments);
42
+ if (propertyValue === undefined)
43
+ issue(reference, 'reference target document group has no requested property');
44
+ return clone(propertyValue);
45
+ }
46
+ if (reference.startsWith('#/') && segments[0] === '$root') {
47
+ const rootToken = tokens.get('');
48
+ if (!rootToken) return issue(reference, 'reference target does not exist');
49
+ // A bare `#/$root` pointer (nothing after `$root`) names the document
50
+ // root token's WHOLE identity, exactly like an ordinary whole-token
51
+ // pointer with no trailing segments -- it must extract `$value`, not
52
+ // return the raw `DesignToken` object. An explicit reserved-property
53
+ // segment (`#/$root/$value`, `#/$root/$description`, ...) should walk the
54
+ // `DesignToken` object itself instead -- see the identical discrimination
55
+ // in the loop below for why any `$`-prefixed segment, not just `$value`,
56
+ // selects that base.
57
+ const remainder = segments.slice(1);
58
+ const usesTokenObjectBase = typeof remainder[0] === 'string' && remainder[0].startsWith('$');
59
+ const readsRawMetadata = usesTokenObjectBase && remainder[0] !== '$value';
60
+ const requiresResolvedType =
61
+ readsRawMetadata && remainder[0] === '$type' && rootToken.$type === undefined;
62
+ const resolvedToken = usesTokenObjectBase
63
+ ? readsRawMetadata && !requiresResolvedType
64
+ ? tokens.get('')!
65
+ : resolveToken('', tokens, rawRefs, rootTokenPaths, resolving, groups, completed)
66
+ : resolveToken('', tokens, rawRefs, rootTokenPaths, resolving, groups, completed);
67
+ const propertyValue =
68
+ remainder[0] === '$ref'
69
+ ? getByPath(rawRefs.get(''), remainder.slice(1))
70
+ : getByPath(usesTokenObjectBase ? resolvedToken : resolvedToken.$value, remainder);
71
+ if (propertyValue === undefined)
72
+ issue(reference, 'reference target $root has no requested property');
73
+ return clone(propertyValue);
74
+ }
75
+ for (let end = segments.length; end > 0; end -= 1) {
76
+ const candidatePath = segments.slice(0, end).join('.');
77
+ const token = tokens.get(candidatePath);
78
+ const group = groups.get(candidatePath);
79
+ if (!token && !group) continue;
80
+ const propertySegments = segments.slice(end);
81
+ if (
82
+ reference.startsWith('#/') &&
83
+ propertySegments.length === 0 &&
84
+ group &&
85
+ rootTokenPaths.has(candidatePath)
86
+ )
87
+ return issue(reference, `reference target ${candidatePath} must name $root explicitly`);
88
+ // `$root`, when present AND `candidatePath` actually names a GROUP that
89
+ // carries one (`rootTokenPaths.has(candidatePath)`) -- not merely an
90
+ // ordinary token that happens to share that path -- is a REDIRECT to the
91
+ // group's own root token, already what `resolvedToken` is in that case,
92
+ // not an extra path level, so it is stripped before walking the
93
+ // remainder. Without the `rootTokenPaths` check, `#/base/$root` where
94
+ // `base` is an ordinary token with no `$root` member would silently
95
+ // redirect to `base` itself instead of correctly failing -- the token
96
+ // index has no other way to distinguish a group's redirected root token
97
+ // from an ordinary token indexed at the same path. A remainder that is
98
+ // empty after stripping it (a bare `#/group/$root` alias) names the root
99
+ // token's whole identity and must extract `$value`, exactly like the
100
+ // ordinary whole-token case just below it; only an explicit `$value`
101
+ // segment walks the raw `DesignToken` object.
102
+ const targetsRootToken =
103
+ reference.startsWith('#/') &&
104
+ propertySegments[0] === '$root' &&
105
+ rootTokenPaths.has(candidatePath);
106
+ const remainder = targetsRootToken ? propertySegments.slice(1) : propertySegments;
107
+ if (targetsRootToken && remainder.length > 0 && !remainder[0]?.startsWith('$'))
108
+ return issue(reference, `reference target ${candidatePath} has no requested property`);
109
+ // A remainder starting with ANY of the token's own reserved `$`-prefixed
110
+ // properties -- not just `$value` -- names something on the `DesignToken`
111
+ // object itself: `#/base/$description`, `#/base/$deprecated`,
112
+ // `#/base/$extensions/...` are all valid pointer targets alongside
113
+ // `#/base/$value/...`. A resolved `$value` payload never itself carries a
114
+ // `$`-prefixed key (DTCG values are plain objects, strings, numbers, or
115
+ // arrays), so this discriminates cleanly without a fixed allowlist.
116
+ const usesTokenObjectBase =
117
+ reference.startsWith('#/') &&
118
+ typeof remainder[0] === 'string' &&
119
+ remainder[0].startsWith('$');
120
+ const readsRawMetadata = usesTokenObjectBase && remainder[0] !== '$value';
121
+ // `$ref` is unique among token metadata: `resolveToken` deletes it from
122
+ // the token object once resolved (see `resolveRefToken`'s doc comment --
123
+ // deliberate, so downstream consumers never see a leftover alias pointer
124
+ // next to the value it named). A pointer that targets another alias
125
+ // token's OWN `$ref` string (`#/alias/$ref`) must read the pre-resolution
126
+ // snapshot (`rawRefs`) rather than the mutated `resolvedToken` -- and
127
+ // rather than `token.$ref` itself, which may already have been deleted by
128
+ // an EARLIER, unrelated resolution of the same path (see `RawRefs`'s doc
129
+ // comment). Every other reserved property is untouched by resolution.
130
+ const requiresResolvedType =
131
+ readsRawMetadata &&
132
+ remainder[0] === '$type' &&
133
+ token?.$type === undefined &&
134
+ (!group || targetsRootToken);
135
+ const resolvedToken = token
136
+ ? readsRawMetadata && !requiresResolvedType
137
+ ? token
138
+ : resolveToken(candidatePath, tokens, rawRefs, rootTokenPaths, resolving, groups, completed)
139
+ : undefined;
140
+ const metadataBase =
141
+ readsRawMetadata && group && !targetsRootToken
142
+ ? groupMetadataBase(group, candidatePath, groups)
143
+ : (resolvedToken ?? group);
144
+ const propertyValue =
145
+ remainder[0] === '$ref'
146
+ ? getByPath(rawRefs.get(candidatePath), remainder.slice(1))
147
+ : getByPath(usesTokenObjectBase ? metadataBase : resolvedToken?.$value, remainder);
148
+ if (propertyValue === undefined)
149
+ issue(reference, `reference target ${candidatePath} has no requested property`);
150
+ return clone(propertyValue);
151
+ }
152
+ return issue(reference, 'reference target does not exist');
153
+ }
154
+
155
+ export function resolveValue(
156
+ value: unknown,
157
+ tokens: ResolvedTokens,
158
+ rawRefs: RawRefs,
159
+ rootTokenPaths: Set<string>,
160
+ resolving: Set<string>,
161
+ groups: Map<string, TokenGroup>,
162
+ completed: Set<string>,
163
+ ): unknown {
164
+ if (typeof value === 'string')
165
+ return /^\{[^{}]+\}$/.test(value) || value.startsWith('#/')
166
+ ? resolveReference(value, tokens, rawRefs, rootTokenPaths, resolving, groups, completed)
167
+ : value;
168
+ if (Array.isArray(value))
169
+ return value.map((entry) =>
170
+ resolveValue(entry, tokens, rawRefs, rootTokenPaths, resolving, groups, completed),
171
+ );
172
+ if (!isObject(value)) return value;
173
+ const resolved: JsonObject = Object.create(null);
174
+ for (const [key, entry] of Object.entries(value))
175
+ resolved[key] = resolveValue(
176
+ entry,
177
+ tokens,
178
+ rawRefs,
179
+ rootTokenPaths,
180
+ resolving,
181
+ groups,
182
+ completed,
183
+ );
184
+ return resolved;
185
+ }
186
+
187
+ /**
188
+ * Resolves a `$ref` token -- a whole-token DTCG 2025.10 alias, distinct from
189
+ * a `{a.b.c}`/`#/a/b/c` reference embedded IN a `$value`. Reuses
190
+ * `resolveReference` (the same machinery an ordinary alias `$value` goes
191
+ * through) rather than a separate path walk, so chained aliases and
192
+ * property-level pointers (`#/base/$value/blur`) work identically for both
193
+ * forms, and so `resolving` cycle detection is shared: a `$ref` chain that
194
+ * loops back on itself trips the same "circular token alias" guard
195
+ * `resolveToken` already applies before this runs.
196
+ *
197
+ * `$type` precedence for a `$ref` token: its own declared `$type` (validated
198
+ * only for known-type membership in `validate.ts`, never required) wins;
199
+ * failing that, the type already inherited from its enclosing group -- set
200
+ * by `withResolvedType` before `resolveToken` is ever called -- wins;
201
+ * failing THAT, the whole-token alias target's resolved `$type` is copied in
202
+ * here. A property-level `$ref` has no whole-token target to borrow a type
203
+ * from, so `$type` is left however it was (possibly still undefined), and
204
+ * `validateResolvedToken` is what reports a genuinely untyped resolved
205
+ * token, the same way it already does for an untyped ordinary token.
206
+ *
207
+ * The `$ref` key is deleted once resolved: a fully resolved `DesignToken` is
208
+ * expected to carry `$value` alone (mirroring the `$value`/`$ref` mutual
209
+ * exclusivity `validate.ts` enforces on the raw document), and downstream
210
+ * consumers of `resolveDocuments`'s output should never have to check for a
211
+ * leftover alias pointer next to the value it named.
212
+ */
213
+ /**
214
+ * The `tokens` index key a whole-token reference ultimately names, for type
215
+ * inference below -- distinct from `tokenPathFromReference`'s plain dotted
216
+ * join, which treats trailing `$value`/`$root` segments as ordinary path
217
+ * levels. A group's root token is indexed under the GROUP's own path
218
+ * (`collectTokens` sets it at `prefix`, not `prefix.$root`), so
219
+ * `#/group/$root` and `#/$root` need their `$root` segment stripped before
220
+ * the `tokens.get` lookup, or it misses -- the same redirect
221
+ * `resolveReference`'s loop applies to `targetsRootToken` above, factored out
222
+ * here since type inference needs only the final indexed path, not a
223
+ * resolved value. A trailing `$value` segment (`#/base/$value`,
224
+ * `#/group/$root/$value`, `#/$root/$value`) names the token's WHOLE value,
225
+ * not a nested property, and must be stripped FIRST -- otherwise
226
+ * `#/group/$root/$value` dot-joins to `group.$root.$value`, which ends in
227
+ * neither `$root` nor a bare `$root`, and the redirect below never fires.
228
+ */
229
+ export function refTargetIndexPath(reference: string): string {
230
+ let path = tokenPathFromReference(reference);
231
+ if (!reference.startsWith('#/')) return path;
232
+ if (path.endsWith('.$value')) path = path.slice(0, -'.$value'.length);
233
+ if (path === '$root') return '';
234
+ return path.endsWith('.$root') ? path.slice(0, -'.$root'.length) : path;
235
+ }
236
+
237
+ export function resolveRefToken(
238
+ path: string,
239
+ token: DesignToken,
240
+ tokens: ResolvedTokens,
241
+ rawRefs: RawRefs,
242
+ rootTokenPaths: Set<string>,
243
+ resolving: Set<string>,
244
+ groups: Map<string, TokenGroup>,
245
+ completed: Set<string>,
246
+ ): void {
247
+ const ref = token.$ref;
248
+ if (typeof ref !== 'string') return issue(path, '$ref must be a string');
249
+ try {
250
+ token.$value = resolveReference(
251
+ ref,
252
+ tokens,
253
+ rawRefs,
254
+ rootTokenPaths,
255
+ resolving,
256
+ groups,
257
+ completed,
258
+ );
259
+ } catch (error) {
260
+ if (error instanceof TokenValidationError)
261
+ return issue(
262
+ path,
263
+ `unresolvable $ref "${ref}": ${error.issues.map((tokenIssue) => tokenIssue.reason).join('; ')}`,
264
+ );
265
+ throw error;
266
+ }
267
+ if (token.$type === undefined) {
268
+ const targetToken = tokens.get(refTargetIndexPath(ref));
269
+ if (targetToken?.$type !== undefined) token.$type = targetToken.$type;
270
+ }
271
+ delete token.$ref;
272
+ }
273
+
274
+ export function resolveToken(
275
+ path: string,
276
+ tokens: ResolvedTokens,
277
+ rawRefs: RawRefs,
278
+ rootTokenPaths: Set<string>,
279
+ resolving: Set<string>,
280
+ groups: Map<string, TokenGroup>,
281
+ completed: Set<string>,
282
+ ): DesignToken {
283
+ const token = tokens.get(path);
284
+ if (!token) return issue(path, 'token does not exist');
285
+ if (completed.has(path)) return token;
286
+ if (resolving.has(path)) return issue(path, 'circular token alias');
287
+ // Validation (`assertValidTokenDocument`) is what enforces `$value`/`$ref`
288
+ // mutual exclusivity on the raw document; this is a resolve-time backstop
289
+ // for a caller that reaches `resolveDocuments`/`createValueResolver`
290
+ // without validating first (there is no such caller in this repo today --
291
+ // every entry point runs validation first -- but nothing in the type
292
+ // system enforces that, and a token carrying both keys would otherwise
293
+ // silently prefer `$ref` and drop `$value` with no diagnostic). Named
294
+ // explicitly rather than left as an implicit precondition.
295
+ if (token.$ref !== undefined && token.$value !== undefined)
296
+ return issue(path, '$value and $ref are mutually exclusive on a resolved token');
297
+ resolving.add(path);
298
+ if (token.$ref !== undefined)
299
+ resolveRefToken(path, token, tokens, rawRefs, rootTokenPaths, resolving, groups, completed);
300
+ else
301
+ token.$value = resolveValue(
302
+ token.$value,
303
+ tokens,
304
+ rawRefs,
305
+ rootTokenPaths,
306
+ resolving,
307
+ groups,
308
+ completed,
309
+ );
310
+ resolving.delete(path);
311
+ completed.add(path);
312
+ return token;
313
+ }