@bamboocss/generator 1.38.0 → 1.39.1

package/dist/index.cjs

@@ -2338,18 +2338,64 @@ const generateTypesEntry = (ctx) => {
 //#region src/artifacts/types/prop-types.ts
 function generatePropTypes(ctx) {
 	const { utility } = ctx;
-	const result = [outdent.outdent`
+	const result = [
+		outdent.outdent`
     ${ctx.file.importType("ConditionalValue", "./conditions")}
     ${ctx.file.importType("CssProperties", "./system-types")}
     ${ctx.file.importType("Tokens", "../tokens/index")}
-
-    export interface UtilityValues {`];
+    `,
+		outdent.outdent`
+    /**
+     * A property's own keywords, without the open \`string\` csstype ends every property with.
+     *
+     * That trailing \`(string & {})\` is what makes \`color: 'mutedd'\` type-check: it is a
+     * string, so it is a colour. Removing it leaves what the property actually enumerates —
+     * \`transparent\`, \`currentColor\`, every named colour — which is what
+     * \`strictTokens: 'unknown-tokens'\` keeps.
+     *
+     * \`string extends T\` is the test, so the wide member goes and the literal ones stay. The
+     * second branch is for the *boxed* \`String\`, which \`Properties<String | Number>\` puts on
+     * every length-taking property and which is not assignable to \`string\` — so it survives the
+     * first test and admits every string on its own. \`Number\` is deliberately kept: a number
+     * cannot be a misspelled token path.
+     */
+    export type KnownKeywords<T> =
+      T extends string ? (string extends T ? never : T)
+      : T extends String ? never
+      : T
+    `,
+		"export interface UtilityValues {"
+	];
 	const types = utility.getTypes();
 	for (const [prop, values] of types.entries()) result.push(`\t${prop}: ${values.join(" | ")};`);
 	result.push("}", "\n");
 	return outdent.outdent`
   ${result.join("\n")}
 
+  /**
+   * Values whose *shape* says they are CSS rather than a token path.
+   *
+   * A token path is a bare identifier, possibly dotted. Anything that starts with a digit, a
+   * dot-digit, \`#\` or \`-\`, or that contains a space, a comma or a call, cannot be one — so
+   * these stay allowed under \`strictTokens: 'unknown-tokens'\` while \`'mutedd'\` does not.
+   *
+   * Constant, and not parameterised by the token union: a template literal distributes over a
+   * union in any placeholder, so a shape built from \`\${Token}\` would multiply the property's
+   * union by the size of the palette. These add seven members whatever the theme contains — see
+   * \`WithModifier\` below for what the other arrangement costs.
+   *
+   * The ambiguity this cannot resolve is a typo that is also a plausible value: \`'2xll'\` starts
+   * with a digit exactly as \`'2rem'\` does, and passes.
+   */
+  export type CssValueShape =
+    | \`\${number}\${string}\`
+    | \`.\${number}\${string}\`
+    | \`#\${string}\`
+    | \`-\${string}\`
+    | \`\${string} \${string}\`
+    | \`\${string},\${string}\`
+    | \`\${string}(\${string})\`
+
   type ImportantMark = "!" | "!important"
   type WhitespaceImportant = \` \${ImportantMark}\`
   type Important = ImportantMark | WhitespaceImportant
@@ -2436,7 +2482,7 @@ function generateStyleProps(ctx) {
 	const cssVars = (0, _bamboocss_shared.unionType)(ctx.globalVars.vars);
 	return outdent.default`
     ${ctx.file.importType("ConditionalValue", "./conditions")}
-    ${ctx.file.importType("OnlyKnown, UtilityValues, WithEscapeHatch", "./prop-type")}
+    ${ctx.file.importType("CssValueShape, KnownKeywords, OnlyKnown, UtilityValues, WithEscapeHatch", "./prop-type")}
     ${ctx.file.importType("CssProperties", "./system-types")}
     ${ctx.file.importType("Token", "../tokens/index")}
 
@@ -2455,25 +2501,93 @@ function generateStyleProps(ctx) {
 		const prop = ctx.utility.shorthands.get(key) ?? key;
 		const union = [];
 		const cssFallback = _bamboocss_is_valid_prop.allCssProperties.includes(prop) ? `CssProperties["${prop}"]` : "";
+		const knownFallback = ctx.config.strictTokens === "unknown-tokens" && !authorIdentProperties.has(prop) && cssFallback ? `KnownKeywords<${cssFallback}>` : "";
+		const gradedFallback = ctx.config.strictTokens === true ? "" : knownFallback || cssFallback;
+		/**
+		* The token side, held out of the union under `'unknown-tokens'` so `restrict` can
+		* put it back inside `WithEscapeHatch`.
+		*
+		* `WithModifier` is `[T] extends [string] ? … : never`, so one non-string member of
+		* `T` — and csstype supplies `undefined` and a boxed `Number` — turns `'blue.300/40'`
+		* and `'blue.300!'` off for the whole property. Wrapping the tokens alone is what
+		* keeps those working, and listing them in both places instead would repeat one of
+		* the largest members a property has.
+		*/
+		let heldOutTokens = "";
+		const separateTokens = ctx.config.strictTokens === "unknown-tokens";
 		if (propTypes.has(prop)) {
-			const utilityValue = `UtilityValues["${prop}"]`;
-			if (strictPropertyList.has(key)) union.push([utilityValue, "CssVars"].join(" | "));
+			const tokenValue = `UtilityValues["${prop}"]`;
+			if (separateTokens) heldOutTokens = tokenValue;
+			const own = separateTokens ? "" : tokenValue;
+			if (strictPropertyList.has(key)) union.push([
+				own,
+				"CssVars",
+				knownFallback
+			].filter(Boolean).join(" | "));
 			else union.push([
-				utilityValue,
+				own,
 				"CssVars",
-				ctx.config.strictTokens ? "" : cssFallback
+				gradedFallback
 			].filter(Boolean).join(" | "));
-		} else union.push([strictPropertyList.has(key) ? "CssVars" : "", cssFallback].filter(Boolean).join(" | "));
+		} else union.push([strictPropertyList.has(key) ? "CssVars" : "", knownFallback || cssFallback].filter(Boolean).join(" | "));
 		const filtered = union.filter(Boolean);
 		if (!filtered.length) filtered.push("string | number");
 		let comment = comments?.[prop] || "";
 		if (ctx.utility.isDeprecated(prop)) comment = comment ? comment.replace("@see", "@deprecated\n@see") : "/** @deprecated */";
-		const line = `${key}?: ${restrict(prop, filtered.filter(Boolean).join(" | "), ctx.config)}`;
+		const line = `${key}?: ${restrict(prop, filtered.filter(Boolean).join(" | "), ctx.config, heldOutTokens)}`;
 		return " " + [comment, line].filter(Boolean).join("\n");
 	}).join("\n")}
     }
     `;
 }
+/**
+* Properties whose values are identifiers the author invents, not values anything enumerates.
+*
+* `strictTokens: 'unknown-tokens'` rejects a bare identifier that names no token and no keyword,
+* on the reasoning that nothing else is shaped like one. That reasoning stops at a property
+* whose values *are* bare identifiers by design: a `@keyframes` name written in CSS rather than
+* in `theme.keyframes`, a grid area, a counter, a container, a view-transition name, a font
+* family, a property name in `transitionProperty`. csstype types all of these as open strings
+* for the same reason, so there is nothing to check against and everything to reject wrongly.
+*
+* Left alone rather than narrowed, so they behave under this setting exactly as they do under
+* the default. The cost is that a typo in one of them is not caught — which is what
+* `strictTokens: true` is for.
+*
+* `content` is here because its values are quoted strings, and `''""''` is neither a keyword nor
+* a shape this can recognise.
+*/
+const authorIdentProperties = new Set([
+	"anchorName",
+	"anchorScope",
+	"animationName",
+	"animationTimeline",
+	"containerName",
+	"content",
+	"counterIncrement",
+	"counterReset",
+	"counterSet",
+	"fontFamily",
+	"fontPalette",
+	"gridArea",
+	"gridColumn",
+	"gridColumnEnd",
+	"gridColumnStart",
+	"gridRow",
+	"gridRowEnd",
+	"gridRowStart",
+	"gridTemplateAreas",
+	"listStyleType",
+	"page",
+	"positionAnchor",
+	"positionTryFallbacks",
+	"scrollTimelineName",
+	"timelineScope",
+	"transitionProperty",
+	"viewTimelineName",
+	"viewTransitionName",
+	"willChange"
+]);
 const strictPropertyList = new Set([
 	"alignContent",
 	"alignItems",
@@ -2538,8 +2652,23 @@ const strictPropertyList = new Set([
 	"wordBreak",
 	"writingMode"
 ]);
-const restrict = (key, value, config) => {
-	if (config.strictPropertyValues && strictPropertyList.has(key)) return `ConditionalValue<WithEscapeHatch<OnlyKnown<"${key}", ${value}>>>`;
+const restrict = (key, value, config, heldOutTokens = "") => {
+	if (config.strictPropertyValues && strictPropertyList.has(key)) return `ConditionalValue<WithEscapeHatch<OnlyKnown<"${key}", ${[heldOutTokens, value].filter(Boolean).join(" | ")}>>>`;
+	/**
+	* The escape hatch wraps the *tokens*, not the whole value.
+	*
+	* `WithModifier` is `[T] extends [string] ? … : never`, so one non-string member of `T`
+	* turns the modifier forms off for the property entirely — and under this setting `T`
+	* carries csstype's keywords, which include `undefined` and boxed `Number`. Wrapping the
+	* whole union that way silently rejected `color: 'blue.300/40'` and `'blue.300!'`, which
+	* decorate a token and have nothing to do with raw values.
+	*
+	* `CssValueShape` is what keeps raw values writable without an escape hatch: the shapes a
+	* token path cannot have — a leading digit, `#` or `-`, or a space, comma or call anywhere.
+	* A bare identifier that names no token and no keyword matches none of them, which is the
+	* mistake this setting exists to catch.
+	*/
+	if (config.strictTokens === "unknown-tokens") return `ConditionalValue<WithEscapeHatch<${heldOutTokens || "never"}> | ${value} | CssValueShape>`;
 	if (config.strictTokens) return `ConditionalValue<WithEscapeHatch<${value}>>`;
 	return `ConditionalValue<${value} | AnyString>`;
 };

package/dist/index.mjs

@@ -2312,18 +2312,64 @@ const generateTypesEntry = (ctx) => {
 //#region src/artifacts/types/prop-types.ts
 function generatePropTypes(ctx) {
 	const { utility } = ctx;
-	const result = [outdent`
+	const result = [
+		outdent`
     ${ctx.file.importType("ConditionalValue", "./conditions")}
     ${ctx.file.importType("CssProperties", "./system-types")}
     ${ctx.file.importType("Tokens", "../tokens/index")}
-
-    export interface UtilityValues {`];
+    `,
+		outdent`
+    /**
+     * A property's own keywords, without the open \`string\` csstype ends every property with.
+     *
+     * That trailing \`(string & {})\` is what makes \`color: 'mutedd'\` type-check: it is a
+     * string, so it is a colour. Removing it leaves what the property actually enumerates —
+     * \`transparent\`, \`currentColor\`, every named colour — which is what
+     * \`strictTokens: 'unknown-tokens'\` keeps.
+     *
+     * \`string extends T\` is the test, so the wide member goes and the literal ones stay. The
+     * second branch is for the *boxed* \`String\`, which \`Properties<String | Number>\` puts on
+     * every length-taking property and which is not assignable to \`string\` — so it survives the
+     * first test and admits every string on its own. \`Number\` is deliberately kept: a number
+     * cannot be a misspelled token path.
+     */
+    export type KnownKeywords<T> =
+      T extends string ? (string extends T ? never : T)
+      : T extends String ? never
+      : T
+    `,
+		"export interface UtilityValues {"
+	];
 	const types = utility.getTypes();
 	for (const [prop, values] of types.entries()) result.push(`\t${prop}: ${values.join(" | ")};`);
 	result.push("}", "\n");
 	return outdent`
   ${result.join("\n")}
 
+  /**
+   * Values whose *shape* says they are CSS rather than a token path.
+   *
+   * A token path is a bare identifier, possibly dotted. Anything that starts with a digit, a
+   * dot-digit, \`#\` or \`-\`, or that contains a space, a comma or a call, cannot be one — so
+   * these stay allowed under \`strictTokens: 'unknown-tokens'\` while \`'mutedd'\` does not.
+   *
+   * Constant, and not parameterised by the token union: a template literal distributes over a
+   * union in any placeholder, so a shape built from \`\${Token}\` would multiply the property's
+   * union by the size of the palette. These add seven members whatever the theme contains — see
+   * \`WithModifier\` below for what the other arrangement costs.
+   *
+   * The ambiguity this cannot resolve is a typo that is also a plausible value: \`'2xll'\` starts
+   * with a digit exactly as \`'2rem'\` does, and passes.
+   */
+  export type CssValueShape =
+    | \`\${number}\${string}\`
+    | \`.\${number}\${string}\`
+    | \`#\${string}\`
+    | \`-\${string}\`
+    | \`\${string} \${string}\`
+    | \`\${string},\${string}\`
+    | \`\${string}(\${string})\`
+
   type ImportantMark = "!" | "!important"
   type WhitespaceImportant = \` \${ImportantMark}\`
   type Important = ImportantMark | WhitespaceImportant
@@ -2410,7 +2456,7 @@ function generateStyleProps(ctx) {
 	const cssVars = unionType(ctx.globalVars.vars);
 	return outdent$1`
     ${ctx.file.importType("ConditionalValue", "./conditions")}
-    ${ctx.file.importType("OnlyKnown, UtilityValues, WithEscapeHatch", "./prop-type")}
+    ${ctx.file.importType("CssValueShape, KnownKeywords, OnlyKnown, UtilityValues, WithEscapeHatch", "./prop-type")}
     ${ctx.file.importType("CssProperties", "./system-types")}
     ${ctx.file.importType("Token", "../tokens/index")}
 
@@ -2429,25 +2475,93 @@ function generateStyleProps(ctx) {
 		const prop = ctx.utility.shorthands.get(key) ?? key;
 		const union = [];
 		const cssFallback = allCssProperties.includes(prop) ? `CssProperties["${prop}"]` : "";
+		const knownFallback = ctx.config.strictTokens === "unknown-tokens" && !authorIdentProperties.has(prop) && cssFallback ? `KnownKeywords<${cssFallback}>` : "";
+		const gradedFallback = ctx.config.strictTokens === true ? "" : knownFallback || cssFallback;
+		/**
+		* The token side, held out of the union under `'unknown-tokens'` so `restrict` can
+		* put it back inside `WithEscapeHatch`.
+		*
+		* `WithModifier` is `[T] extends [string] ? … : never`, so one non-string member of
+		* `T` — and csstype supplies `undefined` and a boxed `Number` — turns `'blue.300/40'`
+		* and `'blue.300!'` off for the whole property. Wrapping the tokens alone is what
+		* keeps those working, and listing them in both places instead would repeat one of
+		* the largest members a property has.
+		*/
+		let heldOutTokens = "";
+		const separateTokens = ctx.config.strictTokens === "unknown-tokens";
 		if (propTypes.has(prop)) {
-			const utilityValue = `UtilityValues["${prop}"]`;
-			if (strictPropertyList.has(key)) union.push([utilityValue, "CssVars"].join(" | "));
+			const tokenValue = `UtilityValues["${prop}"]`;
+			if (separateTokens) heldOutTokens = tokenValue;
+			const own = separateTokens ? "" : tokenValue;
+			if (strictPropertyList.has(key)) union.push([
+				own,
+				"CssVars",
+				knownFallback
+			].filter(Boolean).join(" | "));
 			else union.push([
-				utilityValue,
+				own,
 				"CssVars",
-				ctx.config.strictTokens ? "" : cssFallback
+				gradedFallback
 			].filter(Boolean).join(" | "));
-		} else union.push([strictPropertyList.has(key) ? "CssVars" : "", cssFallback].filter(Boolean).join(" | "));
+		} else union.push([strictPropertyList.has(key) ? "CssVars" : "", knownFallback || cssFallback].filter(Boolean).join(" | "));
 		const filtered = union.filter(Boolean);
 		if (!filtered.length) filtered.push("string | number");
 		let comment = comments?.[prop] || "";
 		if (ctx.utility.isDeprecated(prop)) comment = comment ? comment.replace("@see", "@deprecated\n@see") : "/** @deprecated */";
-		const line = `${key}?: ${restrict(prop, filtered.filter(Boolean).join(" | "), ctx.config)}`;
+		const line = `${key}?: ${restrict(prop, filtered.filter(Boolean).join(" | "), ctx.config, heldOutTokens)}`;
 		return " " + [comment, line].filter(Boolean).join("\n");
 	}).join("\n")}
     }
     `;
 }
+/**
+* Properties whose values are identifiers the author invents, not values anything enumerates.
+*
+* `strictTokens: 'unknown-tokens'` rejects a bare identifier that names no token and no keyword,
+* on the reasoning that nothing else is shaped like one. That reasoning stops at a property
+* whose values *are* bare identifiers by design: a `@keyframes` name written in CSS rather than
+* in `theme.keyframes`, a grid area, a counter, a container, a view-transition name, a font
+* family, a property name in `transitionProperty`. csstype types all of these as open strings
+* for the same reason, so there is nothing to check against and everything to reject wrongly.
+*
+* Left alone rather than narrowed, so they behave under this setting exactly as they do under
+* the default. The cost is that a typo in one of them is not caught — which is what
+* `strictTokens: true` is for.
+*
+* `content` is here because its values are quoted strings, and `''""''` is neither a keyword nor
+* a shape this can recognise.
+*/
+const authorIdentProperties = new Set([
+	"anchorName",
+	"anchorScope",
+	"animationName",
+	"animationTimeline",
+	"containerName",
+	"content",
+	"counterIncrement",
+	"counterReset",
+	"counterSet",
+	"fontFamily",
+	"fontPalette",
+	"gridArea",
+	"gridColumn",
+	"gridColumnEnd",
+	"gridColumnStart",
+	"gridRow",
+	"gridRowEnd",
+	"gridRowStart",
+	"gridTemplateAreas",
+	"listStyleType",
+	"page",
+	"positionAnchor",
+	"positionTryFallbacks",
+	"scrollTimelineName",
+	"timelineScope",
+	"transitionProperty",
+	"viewTimelineName",
+	"viewTransitionName",
+	"willChange"
+]);
 const strictPropertyList = new Set([
 	"alignContent",
 	"alignItems",
@@ -2512,8 +2626,23 @@ const strictPropertyList = new Set([
 	"wordBreak",
 	"writingMode"
 ]);
-const restrict = (key, value, config) => {
-	if (config.strictPropertyValues && strictPropertyList.has(key)) return `ConditionalValue<WithEscapeHatch<OnlyKnown<"${key}", ${value}>>>`;
+const restrict = (key, value, config, heldOutTokens = "") => {
+	if (config.strictPropertyValues && strictPropertyList.has(key)) return `ConditionalValue<WithEscapeHatch<OnlyKnown<"${key}", ${[heldOutTokens, value].filter(Boolean).join(" | ")}>>>`;
+	/**
+	* The escape hatch wraps the *tokens*, not the whole value.
+	*
+	* `WithModifier` is `[T] extends [string] ? … : never`, so one non-string member of `T`
+	* turns the modifier forms off for the property entirely — and under this setting `T`
+	* carries csstype's keywords, which include `undefined` and boxed `Number`. Wrapping the
+	* whole union that way silently rejected `color: 'blue.300/40'` and `'blue.300!'`, which
+	* decorate a token and have nothing to do with raw values.
+	*
+	* `CssValueShape` is what keeps raw values writable without an escape hatch: the shapes a
+	* token path cannot have — a leading digit, `#` or `-`, or a space, comma or call anywhere.
+	* A bare identifier that names no token and no keyword matches none of them, which is the
+	* mistake this setting exists to catch.
+	*/
+	if (config.strictTokens === "unknown-tokens") return `ConditionalValue<WithEscapeHatch<${heldOutTokens || "never"}> | ${value} | CssValueShape>`;
 	if (config.strictTokens) return `ConditionalValue<WithEscapeHatch<${value}>>`;
 	return `ConditionalValue<${value} | AnyString>`;
 };

package/package.json

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