clava 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # clava
 
+## 0.4.2
+
+- Improved [`refine`](https://clava.style/docs/reference/refine) iteration warnings to show the latest changing variant values with a shorter component creation stack.
+- Fixed [`setDefaultVariants`](https://clava.style/docs/reference/refine#setdefaultvariants) calls with stable values to avoid extra [`refine`](https://clava.style/docs/reference/refine) passes.
+
+## 0.4.1
+
+### Improved refine iteration warning with debugging context
+
+When the [`refine`](https://clava.style/docs/reference/refine) iteration cap is hit, the development warning now lists the variant keys that did not stabilize and includes the stack trace of the [`cv`](https://clava.style/docs/reference/cv) call that defined the component. This makes it easier to find the offending component without searching through the codebase.
+
+```txt
+Clava: Maximum refine iterations exceeded. This can happen when a refine callback calls setVariants or setDefaultVariants, but one of the variants changes on every run.
+Variant(s) that did not stabilize: size.
+Component created at:
+    at toolbarButton (src/components/toolbar.ts:42:18)
+    ...
+```
+
+The frame is captured at component creation but formatted lazily, so component creation stays cheap unless the warning actually fires, and the capture is skipped entirely for components that cannot enter the refine loop. The whole warning is wrapped in a `process.env.NODE_ENV !== "production"` guard, so bundlers that inline that constant strip the warning machinery from production builds.
+
+### Other updates
+
+- Removed refine warning-only code from production bundles when bundlers statically replace `process.env.NODE_ENV`.
+
 ## 0.4.0
 
 ### Removed `computedVariants` in favor of function values in `variants`

package/dist/index.d.ts

@@ -30,11 +30,11 @@ type ComponentProps<V = {}> = VariantValues<V> & NullableComponentResult;
 type GetVariants<V> = (variants?: VariantValues<V>) => VariantValues<V>;
 type ComponentPropKey<R extends ComponentResult> = keyof R | (R extends StyleClassProps ? "className" : never);
 type KeySourceArray = readonly string[];
-type KeySourceComponent = {
+interface KeySourceComponent {
   propKeys: readonly string[];
   variantKeys: readonly string[];
   getVariants: () => Record<string, unknown>;
-};
+}
 type KeySource = KeySourceArray | KeySourceComponent;
 type IsComponent<S> = S extends {
   getVariants: () => unknown;

package/dist/index.js

@@ -1,4 +1,92 @@
 import clsx from "clsx";
+//#region src/refine-warning.ts
+function captureCreationFrame(skipFn) {
+	if (process.env.NODE_ENV === "production") return void 0;
+	if (typeof Error.captureStackTrace === "function") {
+		const holder = {};
+		Error.captureStackTrace(holder, skipFn);
+		return holder;
+	}
+	return /* @__PURE__ */ new Error();
+}
+function formatCreationStack(frame) {
+	let stack = frame.stack;
+	if (!stack) return void 0;
+	const newlineIdx = stack.indexOf("\n");
+	if (newlineIdx > 0) {
+		const firstLine = stack.slice(0, newlineIdx);
+		if (firstLine === "Error" || firstLine.startsWith("Error:")) stack = stack.slice(newlineIdx + 1);
+	}
+	const frames = stack.split("\n");
+	for (let i = 0; i < frames.length; i++) {
+		const line = frames[i]?.trim();
+		if (!line) continue;
+		if (isInternalCreationFrame(line)) continue;
+		if (line.includes("/node_modules/")) continue;
+		if (line.includes("\\node_modules\\")) continue;
+		if (line.includes("node:internal")) continue;
+		return `    ${line}`;
+	}
+}
+function isInternalCreationFrame(line) {
+	if (line.includes("captureCreationFrame")) return true;
+	if (line.startsWith("at cv ")) return true;
+	if (line.startsWith("at cv(")) return true;
+	if (line.startsWith("cv@")) return true;
+	return false;
+}
+function formatVariantValue(value) {
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (Number.isNaN(value)) return "NaN";
+		return String(value);
+	}
+	if (typeof value === "bigint") return `${value}n`;
+	if (value === void 0) return "undefined";
+	if (value === null) return "null";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "symbol") return String(value);
+	if (typeof value === "function") return "[function]";
+	return "[object]";
+}
+function setVariantChange(into, key, from, to) {
+	into.set(key, {
+		from,
+		to
+	});
+}
+function accumulateUnstableVariantChanges(into, prev, next) {
+	for (const key in next) {
+		if (!Object.hasOwn(next, key)) continue;
+		if (!Object.is(prev[key], next[key])) setVariantChange(into, key, prev[key], next[key]);
+	}
+	for (const key in prev) {
+		if (!Object.hasOwn(prev, key)) continue;
+		if (Object.hasOwn(next, key)) continue;
+		setVariantChange(into, key, prev[key], void 0);
+	}
+}
+function formatVariantChanges(changes) {
+	return Array.from(changes).map(([key, { from, to }]) => {
+		return `${key}: ${formatVariantValue(from)} -> ${formatVariantValue(to)}`;
+	}).join(", ");
+}
+function warnRefineLimit({ runState, creationFrame, unstableChanges }) {
+	if (process.env.NODE_ENV === "production") return;
+	if (runState.warned) return;
+	runState.warned = true;
+	let message = "Clava: Maximum refine iterations exceeded. This can happen when a refine callback calls setVariants or setDefaultVariants, but one of the variants changes on every run.";
+	if (unstableChanges && unstableChanges.size > 0) {
+		message += `\nVariant(s) that did not stabilize: ${Array.from(unstableChanges.keys()).join(", ")}.`;
+		message += `\nLatest variant changes before warning: ${formatVariantChanges(unstableChanges)}.`;
+	}
+	if (creationFrame) {
+		const creationStack = formatCreationStack(creationFrame);
+		if (creationStack) message += `\nComponent created at:\n${creationStack}`;
+	}
+	console.warn(message);
+}
+//#endregion
 //#region src/utils.ts
 const hasOwn = Object.prototype.hasOwnProperty;
 function isAsciiLetter(code) {
@@ -235,11 +323,6 @@ function areVariantsEqual(a, b) {
 	}
 	return true;
 }
-function warnRefineLimit(runState) {
-	if (runState.warned) return;
-	runState.warned = true;
-	if (process.env.NODE_ENV !== "production") console.warn("Clava: Maximum refine iterations exceeded. This can happen when a refine callback calls setVariants or setDefaultVariants, but one of the variants changes on every run.");
-}
 function getExtUserVariantProps(userVariantProps, protectedVariants, changedVariants) {
 	const extUserVariantProps = {};
 	Object.assign(extUserVariantProps, userVariantProps);
@@ -578,6 +661,7 @@ function create({ transformClass = (className) => className } = {}) {
 		}
 		const extMetasWithRefineCount = extMetasWithRefine.length;
 		const shouldCollectChangedVariants = extMetasWithRefineCount > 0;
+		const creationFrame = !!refine || extMetasWithRefineCount > 0 ? captureCreationFrame(cv) : void 0;
 		const functionVariantKeys = /* @__PURE__ */ new Set();
 		for (let i = 0; i < extCount; i++) {
 			const fnKeys = extMetas[i].functionVariantKeys;
@@ -736,7 +820,7 @@ function create({ transformClass = (className) => className } = {}) {
 								if (!Object.hasOwn(newVariants, key)) continue;
 								const value = newVariants[key];
 								setChangedVariant(key, value, true);
-								if (getCurrentVariantValue(key) === value) continue;
+								if (Object.is(getCurrentVariantValue(key), value)) continue;
 								ensureUpdated()[key] = value;
 							}
 							return;
@@ -750,7 +834,7 @@ function create({ transformClass = (className) => className } = {}) {
 								if (valueKey != null && disabledVariantValues[key]?.has(valueKey)) continue;
 							}
 							setChangedVariant(key, value, true);
-							if (getCurrentVariantValue(key) === value) continue;
+							if (Object.is(getCurrentVariantValue(key), value)) continue;
 							ensureUpdated()[key] = value;
 						}
 					},
@@ -765,9 +849,9 @@ function create({ transformClass = (className) => className } = {}) {
 								const valueKey = getVariantValueKey(value);
 								if (valueKey != null && disabledVariantValues[key]?.has(valueKey)) continue;
 							}
+							if (Object.is(getCurrentVariantValue(key), value)) continue;
 							setChangedVariant(key, value);
 							if (pendingProtectedVariants) pendingProtectedVariants[key] = value;
-							if (getCurrentVariantValue(key) === value) continue;
 							ensureUpdated()[key] = value;
 						}
 					},
@@ -898,16 +982,12 @@ function create({ transformClass = (className) => className } = {}) {
 			if (cStyle) Object.assign(styleOut, cStyle);
 			return workingResolved;
 		};
-		const compute = !refine && extMetasWithRefineCount === 0 ? (resolved, userVariantProps, skipKeys, skipValues, classesOut, styleOut, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
-			return computeOnce(resolved, userVariantProps, skipKeys, skipValues, classesOut, styleOut, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
-		} : (resolved, userVariantProps, skipKeys, skipValues, classesOut, styleOut, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
-			runState ??= {
-				remaining: MAX_REFINE_RUNS,
-				warned: false
-			};
+		const compute = !refine && extMetasWithRefineCount === 0 ? computeOnce : (resolved, userVariantProps, skipKeys, skipValues, classesOut, styleOut, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
+			runState ??= { remaining: MAX_REFINE_RUNS };
 			protectedVariants ??= {};
 			protectedVariantKeys ??= /* @__PURE__ */ new Set();
 			let workingResolved = resolved;
+			let unstableChanges = null;
 			let lastClasses = [];
 			let lastStyle = {};
 			let isFirstRun = true;
@@ -935,8 +1015,16 @@ function create({ transformClass = (className) => className } = {}) {
 					}
 					return nextResolved;
 				}
+				if (process.env.NODE_ENV !== "production" && runState.remaining < 10) {
+					if (!unstableChanges) unstableChanges = /* @__PURE__ */ new Map();
+					accumulateUnstableVariantChanges(unstableChanges, workingResolved, nextResolved);
+				}
 				if (useDirectOutput && runState.remaining === 0) {
-					warnRefineLimit(runState);
+					warnRefineLimit({
+						runState,
+						creationFrame,
+						unstableChanges
+					});
 					return nextResolved;
 				}
 				if (useDirectOutput) {
@@ -949,7 +1037,11 @@ function create({ transformClass = (className) => className } = {}) {
 				workingResolved = nextResolved;
 				isFirstRun = false;
 			}
-			warnRefineLimit(runState);
+			warnRefineLimit({
+				runState,
+				creationFrame,
+				unstableChanges
+			});
 			for (let i = 0; i < lastClasses.length; i++) classesOut.push(lastClasses[i]);
 			Object.assign(styleOut, lastStyle);
 			return workingResolved;
@@ -974,13 +1066,11 @@ function create({ transformClass = (className) => className } = {}) {
 			return workingResolved;
 		};
 		const resolveRefine = refine || extMetasWithRefineCount > 0 ? (resolved, userVariantProps, filterOwnVariants = true, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
-			runState ??= {
-				remaining: MAX_REFINE_RUNS,
-				warned: false
-			};
+			runState ??= { remaining: MAX_REFINE_RUNS };
 			protectedVariants ??= {};
 			protectedVariantKeys ??= /* @__PURE__ */ new Set();
 			let workingResolved = resolved;
+			let unstableChanges = null;
 			let reachedLimit = true;
 			while (runState.remaining > 0) {
 				runState.remaining -= 1;
@@ -994,9 +1084,17 @@ function create({ transformClass = (className) => className } = {}) {
 					reachedLimit = false;
 					break;
 				}
+				if (process.env.NODE_ENV !== "production" && runState.remaining < 10) {
+					if (!unstableChanges) unstableChanges = /* @__PURE__ */ new Map();
+					accumulateUnstableVariantChanges(unstableChanges, workingResolved, nextResolved);
+				}
 				workingResolved = nextResolved;
 			}
-			if (reachedLimit) warnRefineLimit(runState);
+			if (reachedLimit) warnRefineLimit({
+				runState,
+				creationFrame,
+				unstableChanges
+			});
 			return workingResolved;
 		} : null;
 		const computeResult = (props = EMPTY_DEFAULTS) => {