@bamboocss/token-dictionary 1.30.0 → 1.31.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/dist/index.cjs +92 -143
- package/dist/index.d.cts +20 -4
- package/dist/index.d.mts +20 -4
- package/dist/index.mjs +87 -144
- package/package.json +5 -5
package/dist/index.cjs
CHANGED
|
@@ -58,53 +58,82 @@ const isCompositeTokenValue = (value) => {
|
|
|
58
58
|
//#endregion
|
|
59
59
|
//#region src/utils.ts
|
|
60
60
|
/**
|
|
61
|
-
*
|
|
61
|
+
* A reference to another token inside a string value: `token(colors.red.300)`.
|
|
62
|
+
*
|
|
63
|
+
* The comma exclusion keeps a fallback form — `token(spacing.4, 4)` — out of this pass
|
|
64
|
+
* deliberately: only `expandTokenReferences` can resolve one, and matching it here would report a
|
|
65
|
+
* reference where none is substitutable.
|
|
62
66
|
*/
|
|
63
|
-
const REFERENCE_REGEX = /(
|
|
64
|
-
|
|
67
|
+
const REFERENCE_REGEX = /token\(([^(),]+)\)/g;
|
|
68
|
+
/**
|
|
69
|
+
* How a reference to `key` is spelled, for a caller building one rather than reading one.
|
|
70
|
+
*
|
|
71
|
+
* The one place that knows, so retiring a spelling is an edit here rather than a search for
|
|
72
|
+
* string concatenation across three packages.
|
|
73
|
+
*/
|
|
74
|
+
const referenceOf = (key) => `token(${key})`;
|
|
75
|
+
/** Replaces every reference to `key`, so a caller need not spell one itself. */
|
|
76
|
+
const replaceReference = (value, key, replacement) => value.replaceAll(referenceOf(key), replacement);
|
|
65
77
|
/**
|
|
66
78
|
* Returns all references in a string
|
|
67
79
|
*
|
|
68
80
|
* @example
|
|
69
81
|
*
|
|
70
|
-
* `
|
|
82
|
+
* `token(colors.red.300) token(sizes.sm)` => ['colors.red.300', 'sizes.sm']
|
|
71
83
|
*/
|
|
72
84
|
function getReferences(value) {
|
|
73
85
|
if (typeof value !== "string") return [];
|
|
74
|
-
|
|
75
|
-
if (!matches) return [];
|
|
76
|
-
return matches.map((match) => match.replace(curlyBracketRegex, "")).map((value) => value.trim());
|
|
86
|
+
return [...value.matchAll(REFERENCE_REGEX)].map((match) => match[1].trim()).filter(Boolean);
|
|
77
87
|
}
|
|
78
88
|
const hasReference = (value) => getReferences(value).length > 0;
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
89
|
+
/**
|
|
90
|
+
* The retired curly reference — `{colors.red.300}`, or `{$spacing-2}` under a custom
|
|
91
|
+
* `formatTokenName`.
|
|
92
|
+
*
|
|
93
|
+
* Detected in order to *fail*, because leaving it alone is silent in both directions: in a style
|
|
94
|
+
* value the declaration is dropped, and in a token value the literal text is emitted into the
|
|
95
|
+
* stylesheet. Neither reports itself and neither is valid css.
|
|
96
|
+
*
|
|
97
|
+
* Safe to throw on because the spelling was never available for anything else. Until it was
|
|
98
|
+
* removed, `{…}` in a value was consumed unconditionally — braces stripped, and an unresolved
|
|
99
|
+
* path emitted bare — so no literal `{a.b}` could have survived to mean itself. There is no
|
|
100
|
+
* legitimate use to break, which is what separates this from a strict-mode opinion.
|
|
101
|
+
*
|
|
102
|
+
* Excludes whitespace, quotes and `:` so a `content` string holding json-ish text is not read as
|
|
103
|
+
* a stale reference.
|
|
104
|
+
*/
|
|
105
|
+
const CURLY_REFERENCE = /\{[^{}\s:;"']+\}/;
|
|
106
|
+
/** The stale spelling in `value`, or `undefined`. Guarded, since this runs per style value. */
|
|
107
|
+
const findCurlyReference = (value) => value.includes("{") ? CURLY_REFERENCE.exec(value)?.[0] ?? void 0 : void 0;
|
|
108
|
+
/**
|
|
109
|
+
* The retired fallback form — `token(spacing.4, 4)`.
|
|
110
|
+
*
|
|
111
|
+
* Removed along with the parser that existed to read it. A pattern that needed "this token, or
|
|
112
|
+
* this literal" now asks `PatternHelpers.token()` and emits the answer, so the question is
|
|
113
|
+
* settled where it can be answered rather than deferred into a string.
|
|
114
|
+
*
|
|
115
|
+
* Detected in order to fail: left alone, the comma keeps it out of `REFERENCE_REGEX`, so it is
|
|
116
|
+
* emitted into the stylesheet as text — the same silence the curly form had.
|
|
117
|
+
*/
|
|
118
|
+
const FALLBACK_REFERENCE = /token\([^(),]+,[^()]*\)/;
|
|
119
|
+
const findFallbackReference = (value) => value.includes("token(") ? FALLBACK_REFERENCE.exec(value)?.[0] ?? void 0 : void 0;
|
|
120
|
+
/** Shared wording, so the config and style-value paths say the same thing. */
|
|
121
|
+
const curlyReferenceMessage = (found, where) => {
|
|
122
|
+
return `\`${found}\` in ${where} is the retired token reference syntax. Write \`token(${found.slice(1, -1)})\` instead.\n\nCurly references were removed so a token is referenced one way. They are not ignored quietly: in a style value the declaration is dropped, and in a token value the text is emitted into the stylesheet as-is.`;
|
|
123
|
+
};
|
|
83
124
|
const notFoundMessage = (key, value) => `Reference not found: \`${key}\` in "${value}"`;
|
|
84
|
-
const isTokenReference = (v) => hasReference(v) || hasTokenReference(v);
|
|
85
125
|
function expandReferences(value, fn) {
|
|
86
|
-
if (!
|
|
87
|
-
|
|
126
|
+
if (!hasReference(value)) return value;
|
|
127
|
+
return getReferences(value).reduce((valueStr, key) => {
|
|
88
128
|
const resolved = fn(key);
|
|
89
129
|
if (!resolved) _bamboocss_logger.logger.warn("token", notFoundMessage(key, value));
|
|
90
|
-
|
|
91
|
-
return valueStr.replaceAll(`{${key}}`, expandedValue);
|
|
130
|
+
return replaceReference(valueStr, key, resolved ?? (0, _bamboocss_shared.esc)(key));
|
|
92
131
|
}, value);
|
|
93
|
-
if (!expanded.includes(`token(`)) return expanded;
|
|
94
|
-
return expanded.replace(tokenFunctionRegex, (_, token) => {
|
|
95
|
-
const [tokenValue, tokenFallback] = token.split(",").map((s) => s.trim());
|
|
96
|
-
const result = [tokenValue, tokenFallback].filter(Boolean).map((key) => {
|
|
97
|
-
const resolved = fn(key);
|
|
98
|
-
if (!resolved && isTokenReference(key)) _bamboocss_logger.logger.warn("token", notFoundMessage(key, value));
|
|
99
|
-
return resolved ?? (0, _bamboocss_shared.esc)(key);
|
|
100
|
-
});
|
|
101
|
-
if (result.length > 1) {
|
|
102
|
-
const [a, b] = result;
|
|
103
|
-
return tokenReplacer(a, b);
|
|
104
|
-
}
|
|
105
|
-
return tokenReplacer(result[0]);
|
|
106
|
-
});
|
|
107
132
|
}
|
|
133
|
+
/** The same, for the fallback form. */
|
|
134
|
+
const fallbackReferenceMessage = (found, where) => {
|
|
135
|
+
return `\`${found}\` in ${where} uses the retired \`token(path, fallback)\` form. Write \`token(${found.slice(6, found.lastIndexOf(",")).trim()})\` instead.\n\nThe fallback was removed with the parser that read it. A value that may not name a token is resolved where that can be answered — \`PatternHelpers.token(path, fallback)\` in a pattern — rather than deferred into a string.`;
|
|
136
|
+
};
|
|
108
137
|
/**
|
|
109
138
|
* Converts a JS Map to an object
|
|
110
139
|
*/
|
|
@@ -163,7 +192,7 @@ var Token = class Token {
|
|
|
163
192
|
}
|
|
164
193
|
/**
|
|
165
194
|
* Whether the token has a reference in its value.
|
|
166
|
-
* e.g.
|
|
195
|
+
* e.g. token(color.gray.100)
|
|
167
196
|
*/
|
|
168
197
|
get hasReference() {
|
|
169
198
|
return !!this.extensions?.references;
|
|
@@ -176,7 +205,7 @@ var Token = class Token {
|
|
|
176
205
|
}
|
|
177
206
|
/**
|
|
178
207
|
* Returns the token value with the references expanded.
|
|
179
|
-
* e.g.
|
|
208
|
+
* e.g. token(color.gray.100) => var(--colors-gray-100)
|
|
180
209
|
*
|
|
181
210
|
*/
|
|
182
211
|
expandReferences() {
|
|
@@ -185,8 +214,7 @@ var Token = class Token {
|
|
|
185
214
|
this.value = Object.keys(references).reduce((valueStr, key) => {
|
|
186
215
|
const referenceToken = references[key];
|
|
187
216
|
if (referenceToken.isConditional) return valueStr;
|
|
188
|
-
|
|
189
|
-
return valueStr.replaceAll(`{${key}}`, value);
|
|
217
|
+
return replaceReference(valueStr, key, referenceToken.expandReferences());
|
|
190
218
|
}, this.value);
|
|
191
219
|
delete this.extensions.references;
|
|
192
220
|
return this.value;
|
|
@@ -633,7 +661,7 @@ const transforms = [
|
|
|
633
661
|
prefix,
|
|
634
662
|
hash
|
|
635
663
|
}).ref;
|
|
636
|
-
token.value = token.value
|
|
664
|
+
token.value = replaceReference(token.value, ref, variable);
|
|
637
665
|
});
|
|
638
666
|
else {
|
|
639
667
|
const tokenFn = (name) => {
|
|
@@ -754,113 +782,22 @@ const transforms = [
|
|
|
754
782
|
//#endregion
|
|
755
783
|
//#region src/expand-token-references.ts
|
|
756
784
|
/**
|
|
757
|
-
*
|
|
758
|
-
*
|
|
759
|
-
*
|
|
785
|
+
* Expand `token(path)` references in a string value to whatever `resolve` returns for the path.
|
|
786
|
+
*
|
|
787
|
+
* This was a 180-line character-state parser, and every line of it was there for the fallback
|
|
788
|
+
* form — `token(a, b)`, which could nest arbitrarily as `token(a, token(b, var(--c, blue)))`.
|
|
789
|
+
* With the fallback gone the grammar has no recursion left in it, so one regex covers it.
|
|
790
|
+
*
|
|
791
|
+
* A path that resolves to nothing is escaped rather than dropped, so it survives into the class
|
|
792
|
+
* name as written instead of silently becoming empty.
|
|
760
793
|
*/
|
|
794
|
+
const REFERENCE = /token\(([^()]+)\)/g;
|
|
761
795
|
const expandTokenReferences = (str, resolve) => {
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
const currentStates = [];
|
|
768
|
-
while (index < str.length) {
|
|
769
|
-
const char = str[index];
|
|
770
|
-
if (char === "{") {
|
|
771
|
-
const endIndex = str.indexOf("}", index);
|
|
772
|
-
if (endIndex === -1) break;
|
|
773
|
-
const path = str.slice(index + 1, endIndex);
|
|
774
|
-
const resolved = resolve(path);
|
|
775
|
-
expanded += resolved ?? path;
|
|
776
|
-
index = endIndex + 1;
|
|
777
|
-
continue;
|
|
778
|
-
}
|
|
779
|
-
if (state === "token") {
|
|
780
|
-
if (char === ",") {
|
|
781
|
-
if (str[index] === "") index++;
|
|
782
|
-
state = "fallback";
|
|
783
|
-
currentStates.push(state);
|
|
784
|
-
const resolved = resolve(tokenPath);
|
|
785
|
-
if (resolved?.endsWith(")")) expanded += resolved.slice(0, -1);
|
|
786
|
-
tokenPath = "";
|
|
787
|
-
fallback = "";
|
|
788
|
-
continue;
|
|
789
|
-
}
|
|
790
|
-
}
|
|
791
|
-
if (state === "fallback") {
|
|
792
|
-
if (fallback + char === ", var(") {
|
|
793
|
-
const endIndex = cssVarParser(str.slice(index + 1)) + index + 1;
|
|
794
|
-
const cssVar = str.slice(index + 1, endIndex);
|
|
795
|
-
if (endIndex === -1) break;
|
|
796
|
-
expanded += ", var(" + cssVar + ")";
|
|
797
|
-
index = endIndex + 1;
|
|
798
|
-
state = currentStates.pop() ?? state;
|
|
799
|
-
fallback = "";
|
|
800
|
-
continue;
|
|
801
|
-
}
|
|
802
|
-
}
|
|
803
|
-
if (state === "token" || state === "fallback") {
|
|
804
|
-
index++;
|
|
805
|
-
if (char === ")") {
|
|
806
|
-
state = currentStates.pop() ?? state ?? "char";
|
|
807
|
-
fallback += char;
|
|
808
|
-
const resolved = tokenPath ? resolve(tokenPath) ?? (0, _bamboocss_shared.esc)(tokenPath) : tokenPath;
|
|
809
|
-
if (fallback) {
|
|
810
|
-
fallback = fallback.slice(1).trim();
|
|
811
|
-
if (!fallback.startsWith("token(") && fallback.endsWith(")")) fallback = fallback.slice(0, -1);
|
|
812
|
-
if (fallback.includes("token(")) {
|
|
813
|
-
const parsed = expandTokenReferences(fallback, resolve);
|
|
814
|
-
if (parsed) fallback = parsed.slice(0, -1);
|
|
815
|
-
} else if (fallback) {
|
|
816
|
-
const resolvedFallback = resolve(fallback);
|
|
817
|
-
if (resolvedFallback) fallback = resolvedFallback;
|
|
818
|
-
}
|
|
819
|
-
}
|
|
820
|
-
const lastChar = expanded.at(-1);
|
|
821
|
-
if (fallback) if (lastChar?.trim()) expanded += resolved.slice(0, -1) + (", " + fallback + ")");
|
|
822
|
-
else expanded += fallback;
|
|
823
|
-
else expanded += resolved || ")";
|
|
824
|
-
tokenPath = "";
|
|
825
|
-
fallback = "";
|
|
826
|
-
state = "char";
|
|
827
|
-
continue;
|
|
828
|
-
}
|
|
829
|
-
if (state === "token") tokenPath += char;
|
|
830
|
-
if (state === "fallback") fallback += char;
|
|
831
|
-
continue;
|
|
832
|
-
}
|
|
833
|
-
const tokenIndex = str.indexOf("token(", index);
|
|
834
|
-
if (tokenIndex !== -1) {
|
|
835
|
-
const innerTokenIndex = tokenIndex + 6;
|
|
836
|
-
expanded += str.slice(index, tokenIndex);
|
|
837
|
-
index = innerTokenIndex;
|
|
838
|
-
state = "token";
|
|
839
|
-
currentStates.push(state);
|
|
840
|
-
continue;
|
|
841
|
-
}
|
|
842
|
-
expanded += char;
|
|
843
|
-
index++;
|
|
844
|
-
}
|
|
845
|
-
return expanded;
|
|
846
|
-
};
|
|
847
|
-
/**
|
|
848
|
-
* Finds the closing parenthesis index in a string starting from the start of a CSS var
|
|
849
|
-
* @example cssVarParser('--colors-red-100, var(--colors-blue-200, var(--fallback)))')
|
|
850
|
-
*/
|
|
851
|
-
const cssVarParser = (str) => {
|
|
852
|
-
let index = 0;
|
|
853
|
-
const openedParenthesises = ["("];
|
|
854
|
-
while (index < str.length) {
|
|
855
|
-
const char = str[index];
|
|
856
|
-
if (char === "(") openedParenthesises.push(char);
|
|
857
|
-
else if (char === ")") {
|
|
858
|
-
openedParenthesises.pop();
|
|
859
|
-
if (openedParenthesises.length === 0) return index;
|
|
860
|
-
}
|
|
861
|
-
index++;
|
|
862
|
-
}
|
|
863
|
-
return index;
|
|
796
|
+
if (!str.includes("token(")) return str;
|
|
797
|
+
return str.replace(REFERENCE, (_match, path) => {
|
|
798
|
+
const trimmed = path.trim();
|
|
799
|
+
return resolve(trimmed) ?? (0, _bamboocss_shared.esc)(trimmed);
|
|
800
|
+
});
|
|
864
801
|
};
|
|
865
802
|
//#endregion
|
|
866
803
|
//#region src/dictionary.ts
|
|
@@ -1115,6 +1052,10 @@ var TokenDictionary = class {
|
|
|
1115
1052
|
* Expand token references to their CSS variable
|
|
1116
1053
|
*/
|
|
1117
1054
|
expandReferenceInValue(value) {
|
|
1055
|
+
const stale = findCurlyReference(value);
|
|
1056
|
+
if (stale) throw new _bamboocss_shared.BambooError("INVALID_TOKEN", curlyReferenceMessage(stale, `the value \`${value}\``));
|
|
1057
|
+
const withFallback = findFallbackReference(value);
|
|
1058
|
+
if (withFallback) throw new _bamboocss_shared.BambooError("INVALID_TOKEN", fallbackReferenceMessage(withFallback, `the value \`${value}\``));
|
|
1118
1059
|
return expandTokenReferences(value, (path) => {
|
|
1119
1060
|
if (!path) return;
|
|
1120
1061
|
if (path.includes("/")) {
|
|
@@ -1140,14 +1081,16 @@ var TokenDictionary = class {
|
|
|
1140
1081
|
const stack = [originalValue];
|
|
1141
1082
|
while (stack.length) {
|
|
1142
1083
|
const next = stack.pop();
|
|
1143
|
-
if (next.startsWith("
|
|
1144
|
-
|
|
1084
|
+
if (next.startsWith("token(")) {
|
|
1085
|
+
const resolved = this.resolveReference(next);
|
|
1086
|
+
if (resolved === next) return next;
|
|
1087
|
+
stack.push(resolved);
|
|
1145
1088
|
continue;
|
|
1146
1089
|
}
|
|
1147
1090
|
if (next.startsWith("var(")) {
|
|
1148
1091
|
const ref = this.view.nameByVar.get(next);
|
|
1149
1092
|
if (ref) {
|
|
1150
|
-
stack.push(this.resolveReference(
|
|
1093
|
+
stack.push(this.resolveReference(referenceOf(ref)));
|
|
1151
1094
|
continue;
|
|
1152
1095
|
}
|
|
1153
1096
|
}
|
|
@@ -1306,8 +1249,14 @@ exports.TOKEN_CATEGORIES = TOKEN_CATEGORIES;
|
|
|
1306
1249
|
exports.Token = Token;
|
|
1307
1250
|
exports.TokenDictionary = TokenDictionary;
|
|
1308
1251
|
exports.assertTokenFormat = assertTokenFormat;
|
|
1252
|
+
exports.curlyReferenceMessage = curlyReferenceMessage;
|
|
1309
1253
|
exports.expandReferences = expandReferences;
|
|
1254
|
+
exports.fallbackReferenceMessage = fallbackReferenceMessage;
|
|
1255
|
+
exports.findCurlyReference = findCurlyReference;
|
|
1256
|
+
exports.findFallbackReference = findFallbackReference;
|
|
1310
1257
|
exports.getReferences = getReferences;
|
|
1311
1258
|
exports.hasReference = hasReference;
|
|
1312
1259
|
exports.isToken = isToken;
|
|
1313
1260
|
exports.mapToJson = mapToJson;
|
|
1261
|
+
exports.referenceOf = referenceOf;
|
|
1262
|
+
exports.replaceReference = replaceReference;
|
package/dist/index.d.cts
CHANGED
|
@@ -51,7 +51,7 @@ declare class Token {
|
|
|
51
51
|
get isConditional(): boolean;
|
|
52
52
|
/**
|
|
53
53
|
* Whether the token has a reference in its value.
|
|
54
|
-
* e.g.
|
|
54
|
+
* e.g. token(color.gray.100)
|
|
55
55
|
*/
|
|
56
56
|
get hasReference(): boolean;
|
|
57
57
|
/**
|
|
@@ -60,7 +60,7 @@ declare class Token {
|
|
|
60
60
|
get isComposite(): boolean;
|
|
61
61
|
/**
|
|
62
62
|
* Returns the token value with the references expanded.
|
|
63
|
-
* e.g.
|
|
63
|
+
* e.g. token(color.gray.100) => var(--colors-gray-100)
|
|
64
64
|
*
|
|
65
65
|
*/
|
|
66
66
|
expandReferences(): string;
|
|
@@ -215,16 +215,32 @@ declare class TokenDictionaryView {
|
|
|
215
215
|
}
|
|
216
216
|
//#endregion
|
|
217
217
|
//#region src/utils.d.ts
|
|
218
|
+
/**
|
|
219
|
+
* How a reference to `key` is spelled, for a caller building one rather than reading one.
|
|
220
|
+
*
|
|
221
|
+
* The one place that knows, so retiring a spelling is an edit here rather than a search for
|
|
222
|
+
* string concatenation across three packages.
|
|
223
|
+
*/
|
|
224
|
+
declare const referenceOf: (key: string) => string;
|
|
225
|
+
/** Replaces every reference to `key`, so a caller need not spell one itself. */
|
|
226
|
+
declare const replaceReference: (value: string, key: string, replacement: string) => string;
|
|
218
227
|
/**
|
|
219
228
|
* Returns all references in a string
|
|
220
229
|
*
|
|
221
230
|
* @example
|
|
222
231
|
*
|
|
223
|
-
* `
|
|
232
|
+
* `token(colors.red.300) token(sizes.sm)` => ['colors.red.300', 'sizes.sm']
|
|
224
233
|
*/
|
|
225
234
|
declare function getReferences(value: string): string[];
|
|
226
235
|
declare const hasReference: (value: string) => boolean;
|
|
236
|
+
/** The stale spelling in `value`, or `undefined`. Guarded, since this runs per style value. */
|
|
237
|
+
declare const findCurlyReference: (value: string) => string | undefined;
|
|
238
|
+
declare const findFallbackReference: (value: string) => string | undefined;
|
|
239
|
+
/** Shared wording, so the config and style-value paths say the same thing. */
|
|
240
|
+
declare const curlyReferenceMessage: (found: string, where: string) => string;
|
|
227
241
|
declare function expandReferences(value: string, fn: (key: string) => string): string;
|
|
242
|
+
/** The same, for the fallback form. */
|
|
243
|
+
declare const fallbackReferenceMessage: (found: string, where: string) => string;
|
|
228
244
|
/**
|
|
229
245
|
* Converts a JS Map to an object
|
|
230
246
|
*/
|
|
@@ -232,4 +248,4 @@ declare function mapToJson(map: Map<string, any>): Record<string, unknown>;
|
|
|
232
248
|
declare const isToken: (value: any) => value is Token$1;
|
|
233
249
|
declare function assertTokenFormat(token: any): asserts token is Token$1;
|
|
234
250
|
//#endregion
|
|
235
|
-
export { TOKEN_CATEGORIES, Token, type TokenCategory, TokenDictionary, type TokenExtensions, assertTokenFormat, expandReferences, getReferences, hasReference, isToken, mapToJson };
|
|
251
|
+
export { TOKEN_CATEGORIES, Token, type TokenCategory, TokenDictionary, type TokenExtensions, assertTokenFormat, curlyReferenceMessage, expandReferences, fallbackReferenceMessage, findCurlyReference, findFallbackReference, getReferences, hasReference, isToken, mapToJson, referenceOf, replaceReference };
|
package/dist/index.d.mts
CHANGED
|
@@ -51,7 +51,7 @@ declare class Token {
|
|
|
51
51
|
get isConditional(): boolean;
|
|
52
52
|
/**
|
|
53
53
|
* Whether the token has a reference in its value.
|
|
54
|
-
* e.g.
|
|
54
|
+
* e.g. token(color.gray.100)
|
|
55
55
|
*/
|
|
56
56
|
get hasReference(): boolean;
|
|
57
57
|
/**
|
|
@@ -60,7 +60,7 @@ declare class Token {
|
|
|
60
60
|
get isComposite(): boolean;
|
|
61
61
|
/**
|
|
62
62
|
* Returns the token value with the references expanded.
|
|
63
|
-
* e.g.
|
|
63
|
+
* e.g. token(color.gray.100) => var(--colors-gray-100)
|
|
64
64
|
*
|
|
65
65
|
*/
|
|
66
66
|
expandReferences(): string;
|
|
@@ -215,16 +215,32 @@ declare class TokenDictionaryView {
|
|
|
215
215
|
}
|
|
216
216
|
//#endregion
|
|
217
217
|
//#region src/utils.d.ts
|
|
218
|
+
/**
|
|
219
|
+
* How a reference to `key` is spelled, for a caller building one rather than reading one.
|
|
220
|
+
*
|
|
221
|
+
* The one place that knows, so retiring a spelling is an edit here rather than a search for
|
|
222
|
+
* string concatenation across three packages.
|
|
223
|
+
*/
|
|
224
|
+
declare const referenceOf: (key: string) => string;
|
|
225
|
+
/** Replaces every reference to `key`, so a caller need not spell one itself. */
|
|
226
|
+
declare const replaceReference: (value: string, key: string, replacement: string) => string;
|
|
218
227
|
/**
|
|
219
228
|
* Returns all references in a string
|
|
220
229
|
*
|
|
221
230
|
* @example
|
|
222
231
|
*
|
|
223
|
-
* `
|
|
232
|
+
* `token(colors.red.300) token(sizes.sm)` => ['colors.red.300', 'sizes.sm']
|
|
224
233
|
*/
|
|
225
234
|
declare function getReferences(value: string): string[];
|
|
226
235
|
declare const hasReference: (value: string) => boolean;
|
|
236
|
+
/** The stale spelling in `value`, or `undefined`. Guarded, since this runs per style value. */
|
|
237
|
+
declare const findCurlyReference: (value: string) => string | undefined;
|
|
238
|
+
declare const findFallbackReference: (value: string) => string | undefined;
|
|
239
|
+
/** Shared wording, so the config and style-value paths say the same thing. */
|
|
240
|
+
declare const curlyReferenceMessage: (found: string, where: string) => string;
|
|
227
241
|
declare function expandReferences(value: string, fn: (key: string) => string): string;
|
|
242
|
+
/** The same, for the fallback form. */
|
|
243
|
+
declare const fallbackReferenceMessage: (found: string, where: string) => string;
|
|
228
244
|
/**
|
|
229
245
|
* Converts a JS Map to an object
|
|
230
246
|
*/
|
|
@@ -232,4 +248,4 @@ declare function mapToJson(map: Map<string, any>): Record<string, unknown>;
|
|
|
232
248
|
declare const isToken: (value: any) => value is Token$1;
|
|
233
249
|
declare function assertTokenFormat(token: any): asserts token is Token$1;
|
|
234
250
|
//#endregion
|
|
235
|
-
export { TOKEN_CATEGORIES, Token, type TokenCategory, TokenDictionary, type TokenExtensions, assertTokenFormat, expandReferences, getReferences, hasReference, isToken, mapToJson };
|
|
251
|
+
export { TOKEN_CATEGORIES, Token, type TokenCategory, TokenDictionary, type TokenExtensions, assertTokenFormat, curlyReferenceMessage, expandReferences, fallbackReferenceMessage, findCurlyReference, findFallbackReference, getReferences, hasReference, isToken, mapToJson, referenceOf, replaceReference };
|
package/dist/index.mjs
CHANGED
|
@@ -34,53 +34,82 @@ const isCompositeTokenValue = (value) => {
|
|
|
34
34
|
//#endregion
|
|
35
35
|
//#region src/utils.ts
|
|
36
36
|
/**
|
|
37
|
-
*
|
|
37
|
+
* A reference to another token inside a string value: `token(colors.red.300)`.
|
|
38
|
+
*
|
|
39
|
+
* The comma exclusion keeps a fallback form — `token(spacing.4, 4)` — out of this pass
|
|
40
|
+
* deliberately: only `expandTokenReferences` can resolve one, and matching it here would report a
|
|
41
|
+
* reference where none is substitutable.
|
|
38
42
|
*/
|
|
39
|
-
const REFERENCE_REGEX = /(
|
|
40
|
-
|
|
43
|
+
const REFERENCE_REGEX = /token\(([^(),]+)\)/g;
|
|
44
|
+
/**
|
|
45
|
+
* How a reference to `key` is spelled, for a caller building one rather than reading one.
|
|
46
|
+
*
|
|
47
|
+
* The one place that knows, so retiring a spelling is an edit here rather than a search for
|
|
48
|
+
* string concatenation across three packages.
|
|
49
|
+
*/
|
|
50
|
+
const referenceOf = (key) => `token(${key})`;
|
|
51
|
+
/** Replaces every reference to `key`, so a caller need not spell one itself. */
|
|
52
|
+
const replaceReference = (value, key, replacement) => value.replaceAll(referenceOf(key), replacement);
|
|
41
53
|
/**
|
|
42
54
|
* Returns all references in a string
|
|
43
55
|
*
|
|
44
56
|
* @example
|
|
45
57
|
*
|
|
46
|
-
* `
|
|
58
|
+
* `token(colors.red.300) token(sizes.sm)` => ['colors.red.300', 'sizes.sm']
|
|
47
59
|
*/
|
|
48
60
|
function getReferences(value) {
|
|
49
61
|
if (typeof value !== "string") return [];
|
|
50
|
-
|
|
51
|
-
if (!matches) return [];
|
|
52
|
-
return matches.map((match) => match.replace(curlyBracketRegex, "")).map((value) => value.trim());
|
|
62
|
+
return [...value.matchAll(REFERENCE_REGEX)].map((match) => match[1].trim()).filter(Boolean);
|
|
53
63
|
}
|
|
54
64
|
const hasReference = (value) => getReferences(value).length > 0;
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
65
|
+
/**
|
|
66
|
+
* The retired curly reference — `{colors.red.300}`, or `{$spacing-2}` under a custom
|
|
67
|
+
* `formatTokenName`.
|
|
68
|
+
*
|
|
69
|
+
* Detected in order to *fail*, because leaving it alone is silent in both directions: in a style
|
|
70
|
+
* value the declaration is dropped, and in a token value the literal text is emitted into the
|
|
71
|
+
* stylesheet. Neither reports itself and neither is valid css.
|
|
72
|
+
*
|
|
73
|
+
* Safe to throw on because the spelling was never available for anything else. Until it was
|
|
74
|
+
* removed, `{…}` in a value was consumed unconditionally — braces stripped, and an unresolved
|
|
75
|
+
* path emitted bare — so no literal `{a.b}` could have survived to mean itself. There is no
|
|
76
|
+
* legitimate use to break, which is what separates this from a strict-mode opinion.
|
|
77
|
+
*
|
|
78
|
+
* Excludes whitespace, quotes and `:` so a `content` string holding json-ish text is not read as
|
|
79
|
+
* a stale reference.
|
|
80
|
+
*/
|
|
81
|
+
const CURLY_REFERENCE = /\{[^{}\s:;"']+\}/;
|
|
82
|
+
/** The stale spelling in `value`, or `undefined`. Guarded, since this runs per style value. */
|
|
83
|
+
const findCurlyReference = (value) => value.includes("{") ? CURLY_REFERENCE.exec(value)?.[0] ?? void 0 : void 0;
|
|
84
|
+
/**
|
|
85
|
+
* The retired fallback form — `token(spacing.4, 4)`.
|
|
86
|
+
*
|
|
87
|
+
* Removed along with the parser that existed to read it. A pattern that needed "this token, or
|
|
88
|
+
* this literal" now asks `PatternHelpers.token()` and emits the answer, so the question is
|
|
89
|
+
* settled where it can be answered rather than deferred into a string.
|
|
90
|
+
*
|
|
91
|
+
* Detected in order to fail: left alone, the comma keeps it out of `REFERENCE_REGEX`, so it is
|
|
92
|
+
* emitted into the stylesheet as text — the same silence the curly form had.
|
|
93
|
+
*/
|
|
94
|
+
const FALLBACK_REFERENCE = /token\([^(),]+,[^()]*\)/;
|
|
95
|
+
const findFallbackReference = (value) => value.includes("token(") ? FALLBACK_REFERENCE.exec(value)?.[0] ?? void 0 : void 0;
|
|
96
|
+
/** Shared wording, so the config and style-value paths say the same thing. */
|
|
97
|
+
const curlyReferenceMessage = (found, where) => {
|
|
98
|
+
return `\`${found}\` in ${where} is the retired token reference syntax. Write \`token(${found.slice(1, -1)})\` instead.\n\nCurly references were removed so a token is referenced one way. They are not ignored quietly: in a style value the declaration is dropped, and in a token value the text is emitted into the stylesheet as-is.`;
|
|
99
|
+
};
|
|
59
100
|
const notFoundMessage = (key, value) => `Reference not found: \`${key}\` in "${value}"`;
|
|
60
|
-
const isTokenReference = (v) => hasReference(v) || hasTokenReference(v);
|
|
61
101
|
function expandReferences(value, fn) {
|
|
62
|
-
if (!
|
|
63
|
-
|
|
102
|
+
if (!hasReference(value)) return value;
|
|
103
|
+
return getReferences(value).reduce((valueStr, key) => {
|
|
64
104
|
const resolved = fn(key);
|
|
65
105
|
if (!resolved) logger.warn("token", notFoundMessage(key, value));
|
|
66
|
-
|
|
67
|
-
return valueStr.replaceAll(`{${key}}`, expandedValue);
|
|
106
|
+
return replaceReference(valueStr, key, resolved ?? esc(key));
|
|
68
107
|
}, value);
|
|
69
|
-
if (!expanded.includes(`token(`)) return expanded;
|
|
70
|
-
return expanded.replace(tokenFunctionRegex, (_, token) => {
|
|
71
|
-
const [tokenValue, tokenFallback] = token.split(",").map((s) => s.trim());
|
|
72
|
-
const result = [tokenValue, tokenFallback].filter(Boolean).map((key) => {
|
|
73
|
-
const resolved = fn(key);
|
|
74
|
-
if (!resolved && isTokenReference(key)) logger.warn("token", notFoundMessage(key, value));
|
|
75
|
-
return resolved ?? esc(key);
|
|
76
|
-
});
|
|
77
|
-
if (result.length > 1) {
|
|
78
|
-
const [a, b] = result;
|
|
79
|
-
return tokenReplacer(a, b);
|
|
80
|
-
}
|
|
81
|
-
return tokenReplacer(result[0]);
|
|
82
|
-
});
|
|
83
108
|
}
|
|
109
|
+
/** The same, for the fallback form. */
|
|
110
|
+
const fallbackReferenceMessage = (found, where) => {
|
|
111
|
+
return `\`${found}\` in ${where} uses the retired \`token(path, fallback)\` form. Write \`token(${found.slice(6, found.lastIndexOf(",")).trim()})\` instead.\n\nThe fallback was removed with the parser that read it. A value that may not name a token is resolved where that can be answered — \`PatternHelpers.token(path, fallback)\` in a pattern — rather than deferred into a string.`;
|
|
112
|
+
};
|
|
84
113
|
/**
|
|
85
114
|
* Converts a JS Map to an object
|
|
86
115
|
*/
|
|
@@ -139,7 +168,7 @@ var Token = class Token {
|
|
|
139
168
|
}
|
|
140
169
|
/**
|
|
141
170
|
* Whether the token has a reference in its value.
|
|
142
|
-
* e.g.
|
|
171
|
+
* e.g. token(color.gray.100)
|
|
143
172
|
*/
|
|
144
173
|
get hasReference() {
|
|
145
174
|
return !!this.extensions?.references;
|
|
@@ -152,7 +181,7 @@ var Token = class Token {
|
|
|
152
181
|
}
|
|
153
182
|
/**
|
|
154
183
|
* Returns the token value with the references expanded.
|
|
155
|
-
* e.g.
|
|
184
|
+
* e.g. token(color.gray.100) => var(--colors-gray-100)
|
|
156
185
|
*
|
|
157
186
|
*/
|
|
158
187
|
expandReferences() {
|
|
@@ -161,8 +190,7 @@ var Token = class Token {
|
|
|
161
190
|
this.value = Object.keys(references).reduce((valueStr, key) => {
|
|
162
191
|
const referenceToken = references[key];
|
|
163
192
|
if (referenceToken.isConditional) return valueStr;
|
|
164
|
-
|
|
165
|
-
return valueStr.replaceAll(`{${key}}`, value);
|
|
193
|
+
return replaceReference(valueStr, key, referenceToken.expandReferences());
|
|
166
194
|
}, this.value);
|
|
167
195
|
delete this.extensions.references;
|
|
168
196
|
return this.value;
|
|
@@ -609,7 +637,7 @@ const transforms = [
|
|
|
609
637
|
prefix,
|
|
610
638
|
hash
|
|
611
639
|
}).ref;
|
|
612
|
-
token.value = token.value
|
|
640
|
+
token.value = replaceReference(token.value, ref, variable);
|
|
613
641
|
});
|
|
614
642
|
else {
|
|
615
643
|
const tokenFn = (name) => {
|
|
@@ -730,113 +758,22 @@ const transforms = [
|
|
|
730
758
|
//#endregion
|
|
731
759
|
//#region src/expand-token-references.ts
|
|
732
760
|
/**
|
|
733
|
-
*
|
|
734
|
-
*
|
|
735
|
-
*
|
|
761
|
+
* Expand `token(path)` references in a string value to whatever `resolve` returns for the path.
|
|
762
|
+
*
|
|
763
|
+
* This was a 180-line character-state parser, and every line of it was there for the fallback
|
|
764
|
+
* form — `token(a, b)`, which could nest arbitrarily as `token(a, token(b, var(--c, blue)))`.
|
|
765
|
+
* With the fallback gone the grammar has no recursion left in it, so one regex covers it.
|
|
766
|
+
*
|
|
767
|
+
* A path that resolves to nothing is escaped rather than dropped, so it survives into the class
|
|
768
|
+
* name as written instead of silently becoming empty.
|
|
736
769
|
*/
|
|
770
|
+
const REFERENCE = /token\(([^()]+)\)/g;
|
|
737
771
|
const expandTokenReferences = (str, resolve) => {
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
const currentStates = [];
|
|
744
|
-
while (index < str.length) {
|
|
745
|
-
const char = str[index];
|
|
746
|
-
if (char === "{") {
|
|
747
|
-
const endIndex = str.indexOf("}", index);
|
|
748
|
-
if (endIndex === -1) break;
|
|
749
|
-
const path = str.slice(index + 1, endIndex);
|
|
750
|
-
const resolved = resolve(path);
|
|
751
|
-
expanded += resolved ?? path;
|
|
752
|
-
index = endIndex + 1;
|
|
753
|
-
continue;
|
|
754
|
-
}
|
|
755
|
-
if (state === "token") {
|
|
756
|
-
if (char === ",") {
|
|
757
|
-
if (str[index] === "") index++;
|
|
758
|
-
state = "fallback";
|
|
759
|
-
currentStates.push(state);
|
|
760
|
-
const resolved = resolve(tokenPath);
|
|
761
|
-
if (resolved?.endsWith(")")) expanded += resolved.slice(0, -1);
|
|
762
|
-
tokenPath = "";
|
|
763
|
-
fallback = "";
|
|
764
|
-
continue;
|
|
765
|
-
}
|
|
766
|
-
}
|
|
767
|
-
if (state === "fallback") {
|
|
768
|
-
if (fallback + char === ", var(") {
|
|
769
|
-
const endIndex = cssVarParser(str.slice(index + 1)) + index + 1;
|
|
770
|
-
const cssVar = str.slice(index + 1, endIndex);
|
|
771
|
-
if (endIndex === -1) break;
|
|
772
|
-
expanded += ", var(" + cssVar + ")";
|
|
773
|
-
index = endIndex + 1;
|
|
774
|
-
state = currentStates.pop() ?? state;
|
|
775
|
-
fallback = "";
|
|
776
|
-
continue;
|
|
777
|
-
}
|
|
778
|
-
}
|
|
779
|
-
if (state === "token" || state === "fallback") {
|
|
780
|
-
index++;
|
|
781
|
-
if (char === ")") {
|
|
782
|
-
state = currentStates.pop() ?? state ?? "char";
|
|
783
|
-
fallback += char;
|
|
784
|
-
const resolved = tokenPath ? resolve(tokenPath) ?? esc(tokenPath) : tokenPath;
|
|
785
|
-
if (fallback) {
|
|
786
|
-
fallback = fallback.slice(1).trim();
|
|
787
|
-
if (!fallback.startsWith("token(") && fallback.endsWith(")")) fallback = fallback.slice(0, -1);
|
|
788
|
-
if (fallback.includes("token(")) {
|
|
789
|
-
const parsed = expandTokenReferences(fallback, resolve);
|
|
790
|
-
if (parsed) fallback = parsed.slice(0, -1);
|
|
791
|
-
} else if (fallback) {
|
|
792
|
-
const resolvedFallback = resolve(fallback);
|
|
793
|
-
if (resolvedFallback) fallback = resolvedFallback;
|
|
794
|
-
}
|
|
795
|
-
}
|
|
796
|
-
const lastChar = expanded.at(-1);
|
|
797
|
-
if (fallback) if (lastChar?.trim()) expanded += resolved.slice(0, -1) + (", " + fallback + ")");
|
|
798
|
-
else expanded += fallback;
|
|
799
|
-
else expanded += resolved || ")";
|
|
800
|
-
tokenPath = "";
|
|
801
|
-
fallback = "";
|
|
802
|
-
state = "char";
|
|
803
|
-
continue;
|
|
804
|
-
}
|
|
805
|
-
if (state === "token") tokenPath += char;
|
|
806
|
-
if (state === "fallback") fallback += char;
|
|
807
|
-
continue;
|
|
808
|
-
}
|
|
809
|
-
const tokenIndex = str.indexOf("token(", index);
|
|
810
|
-
if (tokenIndex !== -1) {
|
|
811
|
-
const innerTokenIndex = tokenIndex + 6;
|
|
812
|
-
expanded += str.slice(index, tokenIndex);
|
|
813
|
-
index = innerTokenIndex;
|
|
814
|
-
state = "token";
|
|
815
|
-
currentStates.push(state);
|
|
816
|
-
continue;
|
|
817
|
-
}
|
|
818
|
-
expanded += char;
|
|
819
|
-
index++;
|
|
820
|
-
}
|
|
821
|
-
return expanded;
|
|
822
|
-
};
|
|
823
|
-
/**
|
|
824
|
-
* Finds the closing parenthesis index in a string starting from the start of a CSS var
|
|
825
|
-
* @example cssVarParser('--colors-red-100, var(--colors-blue-200, var(--fallback)))')
|
|
826
|
-
*/
|
|
827
|
-
const cssVarParser = (str) => {
|
|
828
|
-
let index = 0;
|
|
829
|
-
const openedParenthesises = ["("];
|
|
830
|
-
while (index < str.length) {
|
|
831
|
-
const char = str[index];
|
|
832
|
-
if (char === "(") openedParenthesises.push(char);
|
|
833
|
-
else if (char === ")") {
|
|
834
|
-
openedParenthesises.pop();
|
|
835
|
-
if (openedParenthesises.length === 0) return index;
|
|
836
|
-
}
|
|
837
|
-
index++;
|
|
838
|
-
}
|
|
839
|
-
return index;
|
|
772
|
+
if (!str.includes("token(")) return str;
|
|
773
|
+
return str.replace(REFERENCE, (_match, path) => {
|
|
774
|
+
const trimmed = path.trim();
|
|
775
|
+
return resolve(trimmed) ?? esc(trimmed);
|
|
776
|
+
});
|
|
840
777
|
};
|
|
841
778
|
//#endregion
|
|
842
779
|
//#region src/dictionary.ts
|
|
@@ -1091,6 +1028,10 @@ var TokenDictionary = class {
|
|
|
1091
1028
|
* Expand token references to their CSS variable
|
|
1092
1029
|
*/
|
|
1093
1030
|
expandReferenceInValue(value) {
|
|
1031
|
+
const stale = findCurlyReference(value);
|
|
1032
|
+
if (stale) throw new BambooError("INVALID_TOKEN", curlyReferenceMessage(stale, `the value \`${value}\``));
|
|
1033
|
+
const withFallback = findFallbackReference(value);
|
|
1034
|
+
if (withFallback) throw new BambooError("INVALID_TOKEN", fallbackReferenceMessage(withFallback, `the value \`${value}\``));
|
|
1094
1035
|
return expandTokenReferences(value, (path) => {
|
|
1095
1036
|
if (!path) return;
|
|
1096
1037
|
if (path.includes("/")) {
|
|
@@ -1116,14 +1057,16 @@ var TokenDictionary = class {
|
|
|
1116
1057
|
const stack = [originalValue];
|
|
1117
1058
|
while (stack.length) {
|
|
1118
1059
|
const next = stack.pop();
|
|
1119
|
-
if (next.startsWith("
|
|
1120
|
-
|
|
1060
|
+
if (next.startsWith("token(")) {
|
|
1061
|
+
const resolved = this.resolveReference(next);
|
|
1062
|
+
if (resolved === next) return next;
|
|
1063
|
+
stack.push(resolved);
|
|
1121
1064
|
continue;
|
|
1122
1065
|
}
|
|
1123
1066
|
if (next.startsWith("var(")) {
|
|
1124
1067
|
const ref = this.view.nameByVar.get(next);
|
|
1125
1068
|
if (ref) {
|
|
1126
|
-
stack.push(this.resolveReference(
|
|
1069
|
+
stack.push(this.resolveReference(referenceOf(ref)));
|
|
1127
1070
|
continue;
|
|
1128
1071
|
}
|
|
1129
1072
|
}
|
|
@@ -1278,4 +1221,4 @@ function replaceRootWithColorPalette(path, colorPaletteRoot) {
|
|
|
1278
1221
|
}
|
|
1279
1222
|
const tokenPathRegex = /\w+\.\w+/;
|
|
1280
1223
|
//#endregion
|
|
1281
|
-
export { TOKEN_CATEGORIES, Token, TokenDictionary, assertTokenFormat, expandReferences, getReferences, hasReference, isToken, mapToJson };
|
|
1224
|
+
export { TOKEN_CATEGORIES, Token, TokenDictionary, assertTokenFormat, curlyReferenceMessage, expandReferences, fallbackReferenceMessage, findCurlyReference, findFallbackReference, getReferences, hasReference, isToken, mapToJson, referenceOf, replaceReference };
|
package/package.json
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bamboocss/token-dictionary",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.31.0",
|
|
4
4
|
"description": "Common error messages for css bamboo",
|
|
5
5
|
"homepage": "https://bamboocss.com",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "Gajus Kuizinas <gajus@gajus.com>",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
10
|
-
"url": "git+https://github.com/bamboocss
|
|
10
|
+
"url": "git+https://github.com/gajus/bamboocss.git",
|
|
11
11
|
"directory": "packages/token-dictionary"
|
|
12
12
|
},
|
|
13
13
|
"files": [
|
|
@@ -35,9 +35,9 @@
|
|
|
35
35
|
"dependencies": {
|
|
36
36
|
"picomatch": "4.0.5",
|
|
37
37
|
"ts-pattern": "5.9.0",
|
|
38
|
-
"@bamboocss/logger": "^1.
|
|
39
|
-
"@bamboocss/shared": "1.
|
|
40
|
-
"@bamboocss/types": "1.
|
|
38
|
+
"@bamboocss/logger": "^1.31.0",
|
|
39
|
+
"@bamboocss/shared": "1.31.0",
|
|
40
|
+
"@bamboocss/types": "1.31.0"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@types/picomatch": "4.0.2"
|