clava 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # clava
 
+## 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

@@ -224,6 +224,7 @@ function isHTMLObjStyle(style) {
 const META_KEY = "__meta";
 const EMPTY_DEFAULTS = Object.freeze({});
 const MAX_REFINE_RUNS = 50;
+const REFINE_UNSTABLE_TRACKING_WINDOW = 10;
 function areVariantsEqual(a, b) {
 	for (const key in a) {
 		if (!Object.hasOwn(a, key)) continue;
@@ -235,10 +236,47 @@ function areVariantsEqual(a, b) {
 	}
 	return true;
 }
-function warnRefineLimit(runState) {
+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);
+	}
+	return stack;
+}
+function accumulateUnstableVariantKeys(into, prev, next) {
+	for (const key in next) {
+		if (!Object.hasOwn(next, key)) continue;
+		if (!Object.is(prev[key], next[key])) into.add(key);
+	}
+	for (const key in prev) {
+		if (!Object.hasOwn(prev, key)) continue;
+		if (Object.hasOwn(next, key)) continue;
+		into.add(key);
+	}
+}
+function warnRefineLimit(runState, creationFrame, unstableKeys) {
+	if (process.env.NODE_ENV === "production") return;
 	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.");
+	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 (unstableKeys && unstableKeys.size > 0) message += `\nVariant(s) that did not stabilize: ${Array.from(unstableKeys).join(", ")}.`;
+	if (creationFrame) {
+		const creationStack = formatCreationStack(creationFrame);
+		if (creationStack) message += `\nComponent created at:\n${creationStack}`;
+	}
+	console.warn(message);
 }
 function getExtUserVariantProps(userVariantProps, protectedVariants, changedVariants) {
 	const extUserVariantProps = {};
@@ -578,6 +616,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;
@@ -898,16 +937,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 unstableKeys = null;
 			let lastClasses = [];
 			let lastStyle = {};
 			let isFirstRun = true;
@@ -935,8 +970,12 @@ function create({ transformClass = (className) => className } = {}) {
 					}
 					return nextResolved;
 				}
+				if (process.env.NODE_ENV !== "production" && runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW) {
+					if (!unstableKeys) unstableKeys = /* @__PURE__ */ new Set();
+					accumulateUnstableVariantKeys(unstableKeys, workingResolved, nextResolved);
+				}
 				if (useDirectOutput && runState.remaining === 0) {
-					warnRefineLimit(runState);
+					warnRefineLimit(runState, creationFrame, unstableKeys);
 					return nextResolved;
 				}
 				if (useDirectOutput) {
@@ -949,7 +988,7 @@ function create({ transformClass = (className) => className } = {}) {
 				workingResolved = nextResolved;
 				isFirstRun = false;
 			}
-			warnRefineLimit(runState);
+			warnRefineLimit(runState, creationFrame, unstableKeys);
 			for (let i = 0; i < lastClasses.length; i++) classesOut.push(lastClasses[i]);
 			Object.assign(styleOut, lastStyle);
 			return workingResolved;
@@ -974,13 +1013,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 unstableKeys = null;
 			let reachedLimit = true;
 			while (runState.remaining > 0) {
 				runState.remaining -= 1;
@@ -994,9 +1031,13 @@ function create({ transformClass = (className) => className } = {}) {
 					reachedLimit = false;
 					break;
 				}
+				if (process.env.NODE_ENV !== "production" && runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW) {
+					if (!unstableKeys) unstableKeys = /* @__PURE__ */ new Set();
+					accumulateUnstableVariantKeys(unstableKeys, workingResolved, nextResolved);
+				}
 				workingResolved = nextResolved;
 			}
-			if (reachedLimit) warnRefineLimit(runState);
+			if (reachedLimit) warnRefineLimit(runState, creationFrame, unstableKeys);
 			return workingResolved;
 		} : null;
 		const computeResult = (props = EMPTY_DEFAULTS) => {