@bamboocss/generator 1.29.0 → 1.30.0

package/dist/index.cjs

@@ -1409,37 +1409,40 @@ function generateTokenJs(ctx) {
 		js: outdent.default`
   const tokens = ${JSON.stringify(obj, null, 2)}
 
-  // \`??\`, not \`||\`. The fallback is for a path that names no token, and \`||\` also swallows a
-  // token whose value is legitimately falsy — \`zIndex: { base: { value: 0 } }\` returned the
-  // fallback instead of 0. Nothing in the default preset has one, so this only ever bit a
-  // custom theme.
-  export function token(path, fallback) {
-    return tokens[path]?.variable ?? fallback
+  // No fallback parameter: \`token(path) ?? fallback\` says the same thing in the language, and
+  // the parameter had to be proved side-effect-free before a build could fold the call away.
+  export function token(path) {
+    return tokens[path]?.variable
   }
 
-  function tokenValue(path, fallback) {
-    return tokens[path]?.value ?? fallback
+  function tokenValue(path) {
+    return tokens[path]?.value
   }
 
-  // \`token.var\` predates \`token()\` returning the reference itself. Kept as the same
-  // function rather than removed, so the spelling that was correct before still is.
-  token.var = token
   token.value = tokenValue
   `,
 		dts: outdent.default`
-  ${ctx.file.importType("Token", "./tokens")}
+  ${ctx.file.importType("Token, LiteralToken", "./tokens")}
 
   export declare const token: {
-    /** The css variable reference — \`var(--colors-red-300)\`. Stays correct across themes. */
-    (path: Token, fallback?: string): string
-    /** Alias of \`token()\`, kept for compatibility. */
-    var: (path: Token, fallback?: string) => string
+    /**
+     * The css variable reference — \`var(--colors-red-300)\`. Stays correct across themes.
+     *
+     * The parameter is the closed set of tokens the theme declares, so this always answers.
+     * A path cast past that type does not, which is the usual bargain for a cast.
+     */
+    (path: Token): string
     /**
      * The resolved literal — \`#fca5a5\`. Use where css variables cannot be resolved, such as
-     * canvas or a charting library. A conditional token has no single literal and still
-     * returns its \`var()\`.
+     * a canvas fill or a charting library.
+     *
+     * Restricted to the tokens that have one. A virtual or conditional token resolves to its
+     * \`var()\` because there is no single value to hand back, and a negative token to
+     * \`calc(var(--spacing-4) * -1)\` because it has no declaration of its own — so asking for
+     * a literal that cannot exist is a type error rather than a reference the caller then
+     * hands to a canvas.
      */
-    value: (path: Token, fallback?: string) => string
+    value: (path: LiteralToken) => string
   }
 
   ${ctx.file.exportTypeStar("./tokens")}
@@ -2465,6 +2468,8 @@ const restrict = (key, value, config) => {
 };
 //#endregion
 //#region src/artifacts/types/token-types.ts
+/** A css function whose result only the browser can produce, so it is never a literal. */
+const COMPUTED_BY_CSS = /\b(?:var|env|attr)\s*\(/i;
 const categories = [
 	"aspectRatios",
 	"zIndex",
@@ -2494,6 +2499,7 @@ function generateTokenTypes(ctx) {
 	const { tokens } = ctx;
 	const set = /* @__PURE__ */ new Set();
 	const tokenSet = /* @__PURE__ */ new Set();
+	const literalTokenSet = /* @__PURE__ */ new Set();
 	const result = new Set(["export type Tokens = {"]);
 	if (tokens.isEmpty) result.add("[token: string]: string");
 	else {
@@ -2505,6 +2511,14 @@ function generateTokenTypes(ctx) {
 			tokenSet.add(`${key}.$\{${categoryName}}`);
 			result.add(`\t\t${key}: ${categoryName}`);
 		}
+		for (const token of tokens.allTokens) {
+			const { category, prop } = token.extensions;
+			if (!category || prop == null) continue;
+			const resolved = tokens.view.get(token.name);
+			if (resolved === void 0) continue;
+			if (typeof resolved === "string" && COMPUTED_BY_CSS.test(resolved)) continue;
+			literalTokenSet.add(`${category}.${prop}`);
+		}
 	}
 	result.add("} & { [token: string]: never }");
 	set.add(Array.from(result).join("\n"));
@@ -2513,7 +2527,7 @@ function generateTokenTypes(ctx) {
 	arr.unshift(`export type Token = ${(0, _bamboocss_shared.unionType)(tokenSet, {
 		stringify: (t) => `\`${t}\``,
 		fallback: "string"
-	})}`);
+	})}`, `export type LiteralToken = ${(0, _bamboocss_shared.unionType)(literalTokenSet, { fallback: tokenSet.size ? "never" : "string" })}`);
 	return outdent.outdent.string(arr.join("\n\n"));
 }
 //#endregion
@@ -3631,13 +3645,26 @@ const CATEGORY_PROPERTY_MAP = {
 const getCategoryProperty = (category) => {
 	return category ? CATEGORY_PROPERTY_MAP[category] ?? "color" : "color";
 };
-const generateTokenExamples = (token) => {
+/**
+* Whether `token.value()` would answer with an actual literal.
+*
+* Takes the *resolved* value rather than the token, because the token alone cannot answer.
+* A semantic token appears once per condition under one name, and `view.get` is last-write —
+* so `colors.button.thick` carries `value: '#fff'` on its base variant while the view returns
+* `var(--colors-button-thick)`, because a `_dark` sibling wrote after it. Asking the token's
+* own fields said "literal" and the `.d.ts` said otherwise; only the view knows.
+*/
+const hasLiteralValue = (resolved) => {
+	if (resolved === void 0) return false;
+	return typeof resolved !== "string" || !COMPUTED_BY_CSS.test(resolved);
+};
+const generateTokenExamples = (token, resolved) => {
 	const prop = getCategoryProperty(token.extensions?.category);
 	const tokenName = token.extensions.prop;
-	const fullTokenName = token.name;
+	const fullTokenName = token.extensions.category ? `${token.extensions.category}.${tokenName}` : token.name;
 	const functionExamples = [`css({ ${prop}: '${tokenName}' })`];
 	const tokenFunctionExamples = [`token('${fullTokenName}')`];
-	tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
+	if (hasLiteralValue(resolved)) tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
 	return {
 		functionExamples,
 		tokenFunctionExamples
@@ -3658,7 +3685,7 @@ const generateThemeTokenGroups = (ctx, themeName, filterFn) => {
 	return Array.from(byCategory.entries()).map(([category, typeTokens]) => {
 		if (!typeTokens.length) return null;
 		const firstToken = typeTokens[0];
-		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 		return {
 			type: category,
 			values: typeTokens.map((token) => {
@@ -3705,7 +3732,7 @@ const generateTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => !token.extensions.isSemantic && !token.extensions.isVirtual && !token.extensions.conditions && !token.extensions.isNegative);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => ({
@@ -3728,7 +3755,7 @@ const generateSemanticTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => (token.extensions.isSemantic || token.extensions.conditions) && !token.extensions.isVirtual);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => {

package/dist/index.mjs

@@ -1383,37 +1383,40 @@ function generateTokenJs(ctx) {
 		js: outdent$1`
   const tokens = ${JSON.stringify(obj, null, 2)}
 
-  // \`??\`, not \`||\`. The fallback is for a path that names no token, and \`||\` also swallows a
-  // token whose value is legitimately falsy — \`zIndex: { base: { value: 0 } }\` returned the
-  // fallback instead of 0. Nothing in the default preset has one, so this only ever bit a
-  // custom theme.
-  export function token(path, fallback) {
-    return tokens[path]?.variable ?? fallback
+  // No fallback parameter: \`token(path) ?? fallback\` says the same thing in the language, and
+  // the parameter had to be proved side-effect-free before a build could fold the call away.
+  export function token(path) {
+    return tokens[path]?.variable
   }
 
-  function tokenValue(path, fallback) {
-    return tokens[path]?.value ?? fallback
+  function tokenValue(path) {
+    return tokens[path]?.value
   }
 
-  // \`token.var\` predates \`token()\` returning the reference itself. Kept as the same
-  // function rather than removed, so the spelling that was correct before still is.
-  token.var = token
   token.value = tokenValue
   `,
 		dts: outdent$1`
-  ${ctx.file.importType("Token", "./tokens")}
+  ${ctx.file.importType("Token, LiteralToken", "./tokens")}
 
   export declare const token: {
-    /** The css variable reference — \`var(--colors-red-300)\`. Stays correct across themes. */
-    (path: Token, fallback?: string): string
-    /** Alias of \`token()\`, kept for compatibility. */
-    var: (path: Token, fallback?: string) => string
+    /**
+     * The css variable reference — \`var(--colors-red-300)\`. Stays correct across themes.
+     *
+     * The parameter is the closed set of tokens the theme declares, so this always answers.
+     * A path cast past that type does not, which is the usual bargain for a cast.
+     */
+    (path: Token): string
     /**
      * The resolved literal — \`#fca5a5\`. Use where css variables cannot be resolved, such as
-     * canvas or a charting library. A conditional token has no single literal and still
-     * returns its \`var()\`.
+     * a canvas fill or a charting library.
+     *
+     * Restricted to the tokens that have one. A virtual or conditional token resolves to its
+     * \`var()\` because there is no single value to hand back, and a negative token to
+     * \`calc(var(--spacing-4) * -1)\` because it has no declaration of its own — so asking for
+     * a literal that cannot exist is a type error rather than a reference the caller then
+     * hands to a canvas.
      */
-    value: (path: Token, fallback?: string) => string
+    value: (path: LiteralToken) => string
   }
 
   ${ctx.file.exportTypeStar("./tokens")}
@@ -2439,6 +2442,8 @@ const restrict = (key, value, config) => {
 };
 //#endregion
 //#region src/artifacts/types/token-types.ts
+/** A css function whose result only the browser can produce, so it is never a literal. */
+const COMPUTED_BY_CSS = /\b(?:var|env|attr)\s*\(/i;
 const categories = [
 	"aspectRatios",
 	"zIndex",
@@ -2468,6 +2473,7 @@ function generateTokenTypes(ctx) {
 	const { tokens } = ctx;
 	const set = /* @__PURE__ */ new Set();
 	const tokenSet = /* @__PURE__ */ new Set();
+	const literalTokenSet = /* @__PURE__ */ new Set();
 	const result = new Set(["export type Tokens = {"]);
 	if (tokens.isEmpty) result.add("[token: string]: string");
 	else {
@@ -2479,6 +2485,14 @@ function generateTokenTypes(ctx) {
 			tokenSet.add(`${key}.$\{${categoryName}}`);
 			result.add(`\t\t${key}: ${categoryName}`);
 		}
+		for (const token of tokens.allTokens) {
+			const { category, prop } = token.extensions;
+			if (!category || prop == null) continue;
+			const resolved = tokens.view.get(token.name);
+			if (resolved === void 0) continue;
+			if (typeof resolved === "string" && COMPUTED_BY_CSS.test(resolved)) continue;
+			literalTokenSet.add(`${category}.${prop}`);
+		}
 	}
 	result.add("} & { [token: string]: never }");
 	set.add(Array.from(result).join("\n"));
@@ -2487,7 +2501,7 @@ function generateTokenTypes(ctx) {
 	arr.unshift(`export type Token = ${unionType(tokenSet, {
 		stringify: (t) => `\`${t}\``,
 		fallback: "string"
-	})}`);
+	})}`, `export type LiteralToken = ${unionType(literalTokenSet, { fallback: tokenSet.size ? "never" : "string" })}`);
 	return outdent.string(arr.join("\n\n"));
 }
 //#endregion
@@ -3605,13 +3619,26 @@ const CATEGORY_PROPERTY_MAP = {
 const getCategoryProperty = (category) => {
 	return category ? CATEGORY_PROPERTY_MAP[category] ?? "color" : "color";
 };
-const generateTokenExamples = (token) => {
+/**
+* Whether `token.value()` would answer with an actual literal.
+*
+* Takes the *resolved* value rather than the token, because the token alone cannot answer.
+* A semantic token appears once per condition under one name, and `view.get` is last-write —
+* so `colors.button.thick` carries `value: '#fff'` on its base variant while the view returns
+* `var(--colors-button-thick)`, because a `_dark` sibling wrote after it. Asking the token's
+* own fields said "literal" and the `.d.ts` said otherwise; only the view knows.
+*/
+const hasLiteralValue = (resolved) => {
+	if (resolved === void 0) return false;
+	return typeof resolved !== "string" || !COMPUTED_BY_CSS.test(resolved);
+};
+const generateTokenExamples = (token, resolved) => {
 	const prop = getCategoryProperty(token.extensions?.category);
 	const tokenName = token.extensions.prop;
-	const fullTokenName = token.name;
+	const fullTokenName = token.extensions.category ? `${token.extensions.category}.${tokenName}` : token.name;
 	const functionExamples = [`css({ ${prop}: '${tokenName}' })`];
 	const tokenFunctionExamples = [`token('${fullTokenName}')`];
-	tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
+	if (hasLiteralValue(resolved)) tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
 	return {
 		functionExamples,
 		tokenFunctionExamples
@@ -3632,7 +3659,7 @@ const generateThemeTokenGroups = (ctx, themeName, filterFn) => {
 	return Array.from(byCategory.entries()).map(([category, typeTokens]) => {
 		if (!typeTokens.length) return null;
 		const firstToken = typeTokens[0];
-		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 		return {
 			type: category,
 			values: typeTokens.map((token) => {
@@ -3679,7 +3706,7 @@ const generateTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => !token.extensions.isSemantic && !token.extensions.isVirtual && !token.extensions.conditions && !token.extensions.isNegative);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => ({
@@ -3702,7 +3729,7 @@ const generateSemanticTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => (token.extensions.isSemantic || token.extensions.conditions) && !token.extensions.isVirtual);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/generator",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "The css generator for css bamboo",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -38,12 +38,12 @@
     "pluralize": "8.0.0",
     "postcss": "8.5.26",
     "ts-pattern": "5.9.0",
-    "@bamboocss/core": "1.29.0",
-    "@bamboocss/is-valid-prop": "^1.29.0",
-    "@bamboocss/logger": "1.29.0",
-    "@bamboocss/shared": "1.29.0",
-    "@bamboocss/token-dictionary": "1.29.0",
-    "@bamboocss/types": "1.29.0"
+    "@bamboocss/core": "1.30.0",
+    "@bamboocss/is-valid-prop": "^1.30.0",
+    "@bamboocss/logger": "1.30.0",
+    "@bamboocss/shared": "1.30.0",
+    "@bamboocss/token-dictionary": "1.30.0",
+    "@bamboocss/types": "1.30.0"
   },
   "devDependencies": {
     "@types/pluralize": "0.0.33"