@bamboocss/generator 1.28.0 → 1.29.0

package/dist/index.cjs

@@ -1373,15 +1373,35 @@ function generateSvaFn(ctx) {
 }
 //#endregion
 //#region src/artifacts/js/token.ts
+/**
+* `token()` hands back the variable reference for every token, and `token.value()` the
+* resolved literal.
+*
+* It used to be the other way round, decided per token: a base token resolved to its literal
+* and a virtual or conditional one to its `var()`. That made the return kind a property of
+* the *theme* rather than of the call, so adding `_dark` to a token silently changed what
+* every caller received — same call, same path, a colour before and a variable after, with
+* both typed `string` and nothing to catch it.
+*
+* Always-a-reference is the predictable half and the one that keeps working when a theme
+* switches, so it takes the short name. The literal is still reachable, but has to be asked
+* for — which is also the honest signal, since it is the form that stops responding to
+* conditions.
+*
+* `value` keeps the old per-token split rather than becoming `token.value` for everything:
+* a virtual or conditional token has no single literal to hand back, so its `var()` is still
+* the only truthful answer.
+*/
 function generateTokenJs(ctx) {
 	const { tokens } = ctx;
 	const map = /* @__PURE__ */ new Map();
 	tokens.allTokens.forEach((token) => {
 		const { varRef, isVirtual } = token.extensions;
-		const value = isVirtual || token.extensions.condition !== "base" ? varRef : token.value;
+		const variable = tokens.view.getVar(token.name) ?? varRef;
+		const value = tokens.view.get(token.name) ?? (isVirtual || token.extensions.condition !== "base" ? varRef : token.value);
 		map.set(token.name, {
 			value,
-			variable: varRef
+			variable
 		});
 	});
 	const obj = Object.fromEntries(map);
@@ -1389,22 +1409,37 @@ 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]?.value || fallback
+    return tokens[path]?.variable ?? fallback
   }
 
-  function tokenVar(path, fallback) {
-    return tokens[path]?.variable || fallback
+  function tokenValue(path, fallback) {
+    return tokens[path]?.value ?? fallback
   }
 
-  token.var = tokenVar
+  // \`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")}
 
   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 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()\`.
+     */
+    value: (path: Token, fallback?: string) => string
   }
 
   ${ctx.file.exportTypeStar("./tokens")}
@@ -3602,7 +3637,7 @@ const generateTokenExamples = (token) => {
 	const fullTokenName = token.name;
 	const functionExamples = [`css({ ${prop}: '${tokenName}' })`];
 	const tokenFunctionExamples = [`token('${fullTokenName}')`];
-	if (token.extensions.varRef) tokenFunctionExamples.push(`token.var('${fullTokenName}')`);
+	tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
 	return {
 		functionExamples,
 		tokenFunctionExamples
@@ -3872,30 +3907,36 @@ var Generator = class extends _bamboocss_core.Context {
 		return names;
 	};
 	/**
-	* Tokens whose javascript value is a `var()` reference rather than a literal.
-	* `token('colors.text')` hands those to the caller as a reference, so the declaration
-	* has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-	* to a literal in javascript and need no such exemption.
+	* The token declarations held open so a runtime `token()` can answer for any path.
+	*
+	* `token()` hands javascript the *variable reference* for every token, so a path the build
+	* cannot resolve could name any of them and every declaration has to survive. That is a
+	* blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+	* declaration behind it, which resolves to the guaranteed-invalid value and inherits
+	* rather than falling back — silently wrong, which is worse than visibly large.
 	*
-	* The two cases mirror `generateTokenJs`, which is what decides the value javascript
-	* actually receives:
+	* It used to be narrower, because `token()` used to return a *literal* for a plain token
+	* and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+	* narrowing this to match it would now strand exactly the base tokens the old split made
+	* safe.
 	*
-	* - A virtual token, or one carrying a condition, is handed its own `varRef`.
-	* - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-	*   the *positive* token's declaration. Its own var is never declared, so the name has
-	*   to come out of the value.
+	* So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+	* project, so nothing outside it can import them -- if no file under `include` reaches for
+	* a token from javascript, no caller exists to serve and the declarations are as prunable
+	* as any other.
+	*
+	* That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+	* project whose token calls all resolve to string literals needs none of this, because
+	* `collectTokenReferences` already kept those paths by name. Deciding that needs the
+	* reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
 	*/
 	getAlwaysKeptTokenVars = (tokensReachableFromJs) => {
 		const names = /* @__PURE__ */ new Set();
 		if (!tokensReachableFromJs) return names;
 		this.tokens.allTokens.forEach((token) => {
-			const { isVirtual, isNegative, condition, var: varName } = token.extensions;
-			if (isVirtual || condition !== "base") {
-				if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
-				return;
-			}
-			if (!isNegative) return;
-			for (const name of (0, _bamboocss_shared.cssVarRefs)(token.value)) names.add(name);
+			const { var: varName } = token.extensions;
+			if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
+			if (typeof token.value === "string") for (const name of (0, _bamboocss_shared.cssVarRefs)(token.value)) names.add(name);
 		});
 		return names;
 	};

package/dist/index.d.cts

@@ -93,18 +93,28 @@ declare class Generator extends Context {
    */
   private getThemeTokenVars;
   /**
-   * Tokens whose javascript value is a `var()` reference rather than a literal.
-   * `token('colors.text')` hands those to the caller as a reference, so the declaration
-   * has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-   * to a literal in javascript and need no such exemption.
+   * The token declarations held open so a runtime `token()` can answer for any path.
    *
-   * The two cases mirror `generateTokenJs`, which is what decides the value javascript
-   * actually receives:
+   * `token()` hands javascript the *variable reference* for every token, so a path the build
+   * cannot resolve could name any of them and every declaration has to survive. That is a
+   * blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+   * declaration behind it, which resolves to the guaranteed-invalid value and inherits
+   * rather than falling back — silently wrong, which is worse than visibly large.
    *
-   * - A virtual token, or one carrying a condition, is handed its own `varRef`.
-   * - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-   *   the *positive* token's declaration. Its own var is never declared, so the name has
-   *   to come out of the value.
+   * It used to be narrower, because `token()` used to return a *literal* for a plain token
+   * and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+   * narrowing this to match it would now strand exactly the base tokens the old split made
+   * safe.
+   *
+   * So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+   * project, so nothing outside it can import them -- if no file under `include` reaches for
+   * a token from javascript, no caller exists to serve and the declarations are as prunable
+   * as any other.
+   *
+   * That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+   * project whose token calls all resolve to string literals needs none of this, because
+   * `collectTokenReferences` already kept those paths by name. Deciding that needs the
+   * reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
    */
   private getAlwaysKeptTokenVars;
   getParserCss: (decoder: StyleDecoder) => string;

package/dist/index.d.mts

@@ -93,18 +93,28 @@ declare class Generator extends Context {
    */
   private getThemeTokenVars;
   /**
-   * Tokens whose javascript value is a `var()` reference rather than a literal.
-   * `token('colors.text')` hands those to the caller as a reference, so the declaration
-   * has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-   * to a literal in javascript and need no such exemption.
+   * The token declarations held open so a runtime `token()` can answer for any path.
    *
-   * The two cases mirror `generateTokenJs`, which is what decides the value javascript
-   * actually receives:
+   * `token()` hands javascript the *variable reference* for every token, so a path the build
+   * cannot resolve could name any of them and every declaration has to survive. That is a
+   * blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+   * declaration behind it, which resolves to the guaranteed-invalid value and inherits
+   * rather than falling back — silently wrong, which is worse than visibly large.
    *
-   * - A virtual token, or one carrying a condition, is handed its own `varRef`.
-   * - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-   *   the *positive* token's declaration. Its own var is never declared, so the name has
-   *   to come out of the value.
+   * It used to be narrower, because `token()` used to return a *literal* for a plain token
+   * and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+   * narrowing this to match it would now strand exactly the base tokens the old split made
+   * safe.
+   *
+   * So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+   * project, so nothing outside it can import them -- if no file under `include` reaches for
+   * a token from javascript, no caller exists to serve and the declarations are as prunable
+   * as any other.
+   *
+   * That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+   * project whose token calls all resolve to string literals needs none of this, because
+   * `collectTokenReferences` already kept those paths by name. Deciding that needs the
+   * reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
    */
   private getAlwaysKeptTokenVars;
   getParserCss: (decoder: StyleDecoder) => string;

package/dist/index.mjs

@@ -1347,15 +1347,35 @@ function generateSvaFn(ctx) {
 }
 //#endregion
 //#region src/artifacts/js/token.ts
+/**
+* `token()` hands back the variable reference for every token, and `token.value()` the
+* resolved literal.
+*
+* It used to be the other way round, decided per token: a base token resolved to its literal
+* and a virtual or conditional one to its `var()`. That made the return kind a property of
+* the *theme* rather than of the call, so adding `_dark` to a token silently changed what
+* every caller received — same call, same path, a colour before and a variable after, with
+* both typed `string` and nothing to catch it.
+*
+* Always-a-reference is the predictable half and the one that keeps working when a theme
+* switches, so it takes the short name. The literal is still reachable, but has to be asked
+* for — which is also the honest signal, since it is the form that stops responding to
+* conditions.
+*
+* `value` keeps the old per-token split rather than becoming `token.value` for everything:
+* a virtual or conditional token has no single literal to hand back, so its `var()` is still
+* the only truthful answer.
+*/
 function generateTokenJs(ctx) {
 	const { tokens } = ctx;
 	const map = /* @__PURE__ */ new Map();
 	tokens.allTokens.forEach((token) => {
 		const { varRef, isVirtual } = token.extensions;
-		const value = isVirtual || token.extensions.condition !== "base" ? varRef : token.value;
+		const variable = tokens.view.getVar(token.name) ?? varRef;
+		const value = tokens.view.get(token.name) ?? (isVirtual || token.extensions.condition !== "base" ? varRef : token.value);
 		map.set(token.name, {
 			value,
-			variable: varRef
+			variable
 		});
 	});
 	const obj = Object.fromEntries(map);
@@ -1363,22 +1383,37 @@ 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]?.value || fallback
+    return tokens[path]?.variable ?? fallback
   }
 
-  function tokenVar(path, fallback) {
-    return tokens[path]?.variable || fallback
+  function tokenValue(path, fallback) {
+    return tokens[path]?.value ?? fallback
   }
 
-  token.var = tokenVar
+  // \`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")}
 
   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 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()\`.
+     */
+    value: (path: Token, fallback?: string) => string
   }
 
   ${ctx.file.exportTypeStar("./tokens")}
@@ -3576,7 +3611,7 @@ const generateTokenExamples = (token) => {
 	const fullTokenName = token.name;
 	const functionExamples = [`css({ ${prop}: '${tokenName}' })`];
 	const tokenFunctionExamples = [`token('${fullTokenName}')`];
-	if (token.extensions.varRef) tokenFunctionExamples.push(`token.var('${fullTokenName}')`);
+	tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
 	return {
 		functionExamples,
 		tokenFunctionExamples
@@ -3846,30 +3881,36 @@ var Generator = class extends Context {
 		return names;
 	};
 	/**
-	* Tokens whose javascript value is a `var()` reference rather than a literal.
-	* `token('colors.text')` hands those to the caller as a reference, so the declaration
-	* has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-	* to a literal in javascript and need no such exemption.
+	* The token declarations held open so a runtime `token()` can answer for any path.
+	*
+	* `token()` hands javascript the *variable reference* for every token, so a path the build
+	* cannot resolve could name any of them and every declaration has to survive. That is a
+	* blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+	* declaration behind it, which resolves to the guaranteed-invalid value and inherits
+	* rather than falling back — silently wrong, which is worse than visibly large.
 	*
-	* The two cases mirror `generateTokenJs`, which is what decides the value javascript
-	* actually receives:
+	* It used to be narrower, because `token()` used to return a *literal* for a plain token
+	* and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+	* narrowing this to match it would now strand exactly the base tokens the old split made
+	* safe.
 	*
-	* - A virtual token, or one carrying a condition, is handed its own `varRef`.
-	* - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-	*   the *positive* token's declaration. Its own var is never declared, so the name has
-	*   to come out of the value.
+	* So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+	* project, so nothing outside it can import them -- if no file under `include` reaches for
+	* a token from javascript, no caller exists to serve and the declarations are as prunable
+	* as any other.
+	*
+	* That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+	* project whose token calls all resolve to string literals needs none of this, because
+	* `collectTokenReferences` already kept those paths by name. Deciding that needs the
+	* reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
 	*/
 	getAlwaysKeptTokenVars = (tokensReachableFromJs) => {
 		const names = /* @__PURE__ */ new Set();
 		if (!tokensReachableFromJs) return names;
 		this.tokens.allTokens.forEach((token) => {
-			const { isVirtual, isNegative, condition, var: varName } = token.extensions;
-			if (isVirtual || condition !== "base") {
-				if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
-				return;
-			}
-			if (!isNegative) return;
-			for (const name of cssVarRefs(token.value)) names.add(name);
+			const { var: varName } = token.extensions;
+			if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
+			if (typeof token.value === "string") for (const name of cssVarRefs(token.value)) names.add(name);
 		});
 		return names;
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/generator",
-  "version": "1.28.0",
+  "version": "1.29.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.28.0",
-    "@bamboocss/is-valid-prop": "^1.28.0",
-    "@bamboocss/logger": "1.28.0",
-    "@bamboocss/shared": "1.28.0",
-    "@bamboocss/token-dictionary": "1.28.0",
-    "@bamboocss/types": "1.28.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"
   },
   "devDependencies": {
     "@types/pluralize": "0.0.33"