clava 0.3.0 → 0.4.1

package/dist/index.js

@@ -223,7 +223,8 @@ function isHTMLObjStyle(style) {
 //#region src/index.ts
 const META_KEY = "__meta";
 const EMPTY_DEFAULTS = Object.freeze({});
-const MAX_COMPUTED_RUNS = 50;
+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 warnComputedLimit(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 computed update iterations exceeded. This can happen when a computed 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 = {};
@@ -334,10 +372,6 @@ function collectVariantKeys(config) {
 		}
 		keys.add(key);
 	}
-	if (config.computedVariants) for (const key in config.computedVariants) {
-		if (!Object.hasOwn(config.computedVariants, key)) continue;
-		keys.add(key);
-	}
 	return Array.from(keys);
 }
 function isVariantDisabled(config, key) {
@@ -514,28 +548,27 @@ function create({ transformClass = (className) => className } = {}) {
 		const extend = config.extend;
 		const hasExtend = !!extend && extend.length > 0;
 		const variants = config.variants;
-		const computedVariantsCfg = config.computedVariants;
-		const computed = config.computed;
+		const refine = config.refine;
 		const baseStyle = config.style;
 		const hasBaseStyle = !!baseStyle;
 		const variantEntryNames = [];
 		const variantEntryDefs = [];
+		const functionVariantNames = [];
+		const functionVariantFns = [];
 		if (variants) for (const name in variants) {
 			if (!Object.hasOwn(variants, name)) continue;
 			const variant = variants[name];
 			if (variant === null) continue;
+			if (typeof variant === "function") {
+				functionVariantNames.push(name);
+				functionVariantFns.push(variant);
+				continue;
+			}
 			variantEntryNames.push(name);
 			variantEntryDefs.push(buildPrebuiltVariant(variant));
 		}
 		const variantEntryCount = variantEntryNames.length;
-		const computedVariantNames = [];
-		const computedVariantFns = [];
-		if (computedVariantsCfg) for (const name in computedVariantsCfg) {
-			if (!Object.hasOwn(computedVariantsCfg, name)) continue;
-			computedVariantNames.push(name);
-			computedVariantFns.push(computedVariantsCfg[name]);
-		}
-		const computedVariantCount = computedVariantNames.length;
+		const functionVariantCount = functionVariantNames.length;
 		const staticDefaults = {};
 		if (extend) for (const ext of extend) {
 			const meta = getComponentMeta(ext);
@@ -576,18 +609,39 @@ function create({ transformClass = (className) => className } = {}) {
 			} else extBaseClassesArr.push(meta.baseClass);
 		}
 		const extCount = extMetas.length;
-		const extMetasWithComputed = [];
+		const extMetasWithRefine = [];
 		for (let i = 0; i < extCount; i++) {
 			const meta = extMetas[i];
-			if (meta.resolveDefaults) extMetasWithComputed.push(meta);
+			if (meta.resolveDefaults) extMetasWithRefine.push(meta);
+		}
+		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;
+			for (const k of fnKeys) {
+				if (disabledVariantKeys.has(k)) continue;
+				functionVariantKeys.add(k);
+			}
+		}
+		for (let i = 0; i < functionVariantCount; i++) functionVariantKeys.add(functionVariantNames[i]);
+		for (let i = 0; i < variantEntryCount; i++) functionVariantKeys.delete(variantEntryNames[i]);
+		let staticVariantsOverridingExtFn = null;
+		if (variantEntryCount > 0 && extCount > 0) for (let i = 0; i < variantEntryCount; i++) {
+			const name = variantEntryNames[i];
+			for (let j = 0; j < extCount; j++) if (extMetas[j].functionVariantKeys.has(name)) {
+				if (!staticVariantsOverridingExtFn) staticVariantsOverridingExtFn = [];
+				staticVariantsOverridingExtFn.push(name);
+				break;
+			}
 		}
-		const extMetasWithComputedCount = extMetasWithComputed.length;
-		const shouldCollectChangedVariants = extMetasWithComputedCount > 0;
 		let staticExtSkipKeys = null;
-		if (hasDisabledVariantKeys || computedVariantCount > 0) {
+		if (hasDisabledVariantKeys || functionVariantCount > 0 || staticVariantsOverridingExtFn !== null) {
 			staticExtSkipKeys = /* @__PURE__ */ new Set();
 			for (const k of disabledVariantKeys) staticExtSkipKeys.add(k);
-			for (let i = 0; i < computedVariantCount; i++) staticExtSkipKeys.add(computedVariantNames[i]);
+			for (let i = 0; i < functionVariantCount; i++) staticExtSkipKeys.add(functionVariantNames[i]);
+			if (staticVariantsOverridingExtFn) for (const k of staticVariantsOverridingExtFn) staticExtSkipKeys.add(k);
 		}
 		const staticExtSkipValues = hasDisabledVariantValues ? disabledVariantValues : null;
 		function filterDisabledInto(input, out) {
@@ -606,7 +660,7 @@ function create({ transformClass = (className) => className } = {}) {
 				out[key] = value;
 			}
 		}
-		const resolveDefaultsFn = computed || extMetasWithComputedCount > 0 ? (childDefaults, userProps = EMPTY_DEFAULTS) => {
+		const resolveDefaultsFn = refine || extMetasWithRefineCount > 0 ? (childDefaults, userProps = EMPTY_DEFAULTS) => {
 			const resolvedVariants = {};
 			Object.assign(resolvedVariants, staticDefaults);
 			for (const key in childDefaults) {
@@ -621,21 +675,21 @@ function create({ transformClass = (className) => className } = {}) {
 				if (v === void 0) continue;
 				resolvedVariants[key] = v;
 			}
-			const computedDefaults = {};
-			for (let i = 0; i < extMetasWithComputedCount; i++) {
-				const extDefaults = extMetasWithComputed[i].resolveDefaults(childDefaults, userProps);
+			const refineDefaults = {};
+			for (let i = 0; i < extMetasWithRefineCount; i++) {
+				const extDefaults = extMetasWithRefine[i].resolveDefaults(childDefaults, userProps);
 				for (const k in extDefaults) {
 					if (!Object.hasOwn(extDefaults, k)) continue;
-					computedDefaults[k] = extDefaults[k];
+					refineDefaults[k] = extDefaults[k];
 				}
 			}
-			if (computed) {
+			if (refine) {
 				const ownVariants = {};
 				for (let i = 0; i < variantKeysLength; i++) {
 					const k = variantKeys[i];
 					if (Object.hasOwn(resolvedVariants, k)) ownVariants[k] = resolvedVariants[k];
 				}
-				computed({
+				refine({
 					variants: ownVariants,
 					setVariants: noop,
 					setDefaultVariants: (newDefaults) => {
@@ -645,23 +699,23 @@ function create({ transformClass = (className) => className } = {}) {
 							if (userProps[key] !== void 0) continue;
 							if (isVariantDisabled(config, key)) continue;
 							if (isVariantValueDisabled(config, key, value)) continue;
-							computedDefaults[key] = value;
+							refineDefaults[key] = value;
 						}
 					},
 					addClass: noop,
 					addStyle: noop
 				});
 			}
-			return computedDefaults;
+			return refineDefaults;
 		} : null;
 		function resolveVariantsHot(propsVariants) {
 			const defaults = {};
 			Object.assign(defaults, staticDefaults);
-			for (let i = 0; i < extMetasWithComputedCount; i++) {
-				const extComputed = extMetasWithComputed[i].resolveDefaults(defaults, propsVariants);
-				for (const k in extComputed) {
-					if (!Object.hasOwn(extComputed, k)) continue;
-					defaults[k] = extComputed[k];
+			for (let i = 0; i < extMetasWithRefineCount; i++) {
+				const extDefaults = extMetasWithRefine[i].resolveDefaults(defaults, propsVariants);
+				for (const k in extDefaults) {
+					if (!Object.hasOwn(extDefaults, k)) continue;
+					defaults[k] = extDefaults[k];
 				}
 			}
 			for (const k in propsVariants) {
@@ -675,12 +729,12 @@ function create({ transformClass = (className) => className } = {}) {
 			filterDisabledInto(defaults, result);
 			return result;
 		}
-		const runComputedContext = (resolved, userVariantProps, filterOwnVariants, collectOutput, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
+		const runRefineContext = (resolved, userVariantProps, filterOwnVariants, collectOutput, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
 			let workingResolved = resolved;
 			let cClasses = null;
 			let cStyle = null;
 			let changedVariants = null;
-			if (computed) {
+			if (refine) {
 				let ownVariants = resolved;
 				if (filterOwnVariants) {
 					const filteredVariants = {};
@@ -713,7 +767,7 @@ function create({ transformClass = (className) => className } = {}) {
 				const getCurrentVariantValue = (key) => {
 					return updatedVariants ? updatedVariants[key] : ownVariants[key];
 				};
-				const result = computed({
+				const result = refine({
 					variants: ownVariants,
 					setVariants: (newVariants) => {
 						if (!hasAnyDisabled) {
@@ -798,12 +852,12 @@ function create({ transformClass = (className) => className } = {}) {
 			let cClasses = null;
 			let cStyle = null;
 			let changedVariants = null;
-			if (computed) {
-				const computedResult = runComputedContext(resolved, userVariantProps, true, true, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
-				workingResolved = computedResult.workingResolved;
-				cClasses = computedResult.classes;
-				cStyle = computedResult.style;
-				changedVariants = computedResult.changedVariants;
+			if (refine) {
+				const refineResult = runRefineContext(resolved, userVariantProps, true, true, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
+				workingResolved = refineResult.workingResolved;
+				cClasses = refineResult.classes;
+				cStyle = refineResult.style;
+				changedVariants = refineResult.changedVariants;
 			}
 			if (hasExtend) {
 				let extSkipKeys;
@@ -828,7 +882,7 @@ function create({ transformClass = (className) => className } = {}) {
 						} else extSkipVals[k] = staticExtSkipValues[k];
 					}
 				}
-				const extUserVariantProps = extMetasWithComputedCount > 0 ? getExtUserVariantProps(userVariantProps, protectedVariants ?? null, changedVariants) : userVariantProps;
+				const extUserVariantProps = extMetasWithRefineCount > 0 ? getExtUserVariantProps(userVariantProps, protectedVariants ?? null, changedVariants) : userVariantProps;
 				for (let i = 0; i < extCount; i++) {
 					if (hasIsolatedExt && extIsolated[i]) {
 						const extClasses = [];
@@ -838,7 +892,7 @@ function create({ transformClass = (className) => className } = {}) {
 							if (joined.length > 0) classesOut.push(extMetas[i].transformClass(joined));
 						}
 					} else workingResolved = extMetas[i].compute(workingResolved, extUserVariantProps, extSkipKeys, extSkipVals, classesOut, styleOut, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
-					if (protectedVariants && extMetasWithComputedCount > 0) Object.assign(extUserVariantProps, protectedVariants);
+					if (protectedVariants && extMetasWithRefineCount > 0) Object.assign(extUserVariantProps, protectedVariants);
 				}
 			}
 			if (hasBaseStyle) Object.assign(styleOut, baseStyle);
@@ -865,14 +919,14 @@ function create({ transformClass = (className) => className } = {}) {
 					if (v.style) Object.assign(styleOut, v.style);
 				}
 			}
-			for (let i = 0; i < computedVariantCount; i++) {
-				const variantName = computedVariantNames[i];
+			for (let i = 0; i < functionVariantCount; i++) {
+				const variantName = functionVariantNames[i];
 				if (ownSkipKeys && ownSkipKeys.has(variantName)) continue;
 				const selectedValue = workingResolved[variantName];
 				if (selectedValue === void 0) continue;
 				const selectedKey = getVariantValueKey(selectedValue);
 				if (ownSkipValues && selectedKey != null && ownSkipValues[variantName]?.has(selectedKey)) continue;
-				const fn = computedVariantFns[i];
+				const fn = functionVariantFns[i];
 				const computedResult = fn(selectedValue);
 				if (computedResult == null) continue;
 				const r = extractClassAndStylePrebuilt(computedResult);
@@ -883,16 +937,12 @@ function create({ transformClass = (className) => className } = {}) {
 			if (cStyle) Object.assign(styleOut, cStyle);
 			return workingResolved;
 		};
-		const compute = !computed && extMetasWithComputedCount === 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_COMPUTED_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;
@@ -920,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) {
-					warnComputedLimit(runState);
+					warnRefineLimit(runState, creationFrame, unstableKeys);
 					return nextResolved;
 				}
 				if (useDirectOutput) {
@@ -934,43 +988,41 @@ function create({ transformClass = (className) => className } = {}) {
 				workingResolved = nextResolved;
 				isFirstRun = false;
 			}
-			warnComputedLimit(runState);
+			warnRefineLimit(runState, creationFrame, unstableKeys);
 			for (let i = 0; i < lastClasses.length; i++) classesOut.push(lastClasses[i]);
 			Object.assign(styleOut, lastStyle);
 			return workingResolved;
 		};
-		const resolveComputedOnce = (resolved, userVariantProps, filterOwnVariants = true, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
+		const resolveRefineOnce = (resolved, userVariantProps, filterOwnVariants = true, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
 			let workingResolved = resolved;
 			let changedVariants = null;
-			if (computed) {
-				const computedResult = runComputedContext(resolved, userVariantProps, filterOwnVariants, false, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
-				workingResolved = computedResult.workingResolved;
-				changedVariants = computedResult.changedVariants;
+			if (refine) {
+				const refineResult = runRefineContext(resolved, userVariantProps, filterOwnVariants, false, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
+				workingResolved = refineResult.workingResolved;
+				changedVariants = refineResult.changedVariants;
 			}
-			if (extMetasWithComputedCount > 0) {
+			if (extMetasWithRefineCount > 0) {
 				const extUserVariantProps = getExtUserVariantProps(userVariantProps, protectedVariants ?? null, changedVariants);
-				for (let i = 0; i < extMetasWithComputedCount; i++) {
-					const resolveComputed = extMetasWithComputed[i].resolveComputed;
-					if (!resolveComputed) continue;
-					workingResolved = resolveComputed(workingResolved, extUserVariantProps, true, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
+				for (let i = 0; i < extMetasWithRefineCount; i++) {
+					const resolveRefine = extMetasWithRefine[i].resolveRefine;
+					if (!resolveRefine) continue;
+					workingResolved = resolveRefine(workingResolved, extUserVariantProps, true, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys);
 					if (protectedVariants) Object.assign(extUserVariantProps, protectedVariants);
 				}
 			}
 			return workingResolved;
 		};
-		const resolveComputed = computed || extMetasWithComputedCount > 0 ? (resolved, userVariantProps, filterOwnVariants = true, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
-			runState ??= {
-				remaining: MAX_COMPUTED_RUNS,
-				warned: false
-			};
+		const resolveRefine = refine || extMetasWithRefineCount > 0 ? (resolved, userVariantProps, filterOwnVariants = true, runState, protectedVariants, pendingProtectedVariants, protectedVariantKeys) => {
+			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;
 				const nextPendingProtectedVariants = {};
-				const nextResolved = resolveComputedOnce(workingResolved, userVariantProps, filterOwnVariants, runState, protectedVariants, nextPendingProtectedVariants, protectedVariantKeys);
+				const nextResolved = resolveRefineOnce(workingResolved, userVariantProps, filterOwnVariants, runState, protectedVariants, nextPendingProtectedVariants, protectedVariantKeys);
 				let protectedChanged;
 				if (pendingProtectedVariants) protectedChanged = mergeVariants(pendingProtectedVariants, nextPendingProtectedVariants, protectedVariantKeys);
 				else protectedChanged = mergeVariants(protectedVariants, nextPendingProtectedVariants, protectedVariantKeys);
@@ -979,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) warnComputedLimit(runState);
+			if (reachedLimit) warnRefineLimit(runState, creationFrame, unstableKeys);
 			return workingResolved;
 		} : null;
 		const computeResult = (props = EMPTY_DEFAULTS) => {
@@ -989,17 +1045,17 @@ function create({ transformClass = (className) => className } = {}) {
 			let resolved = {};
 			Object.assign(resolved, staticDefaults);
 			let userVariantProps;
-			if (extMetasWithComputedCount > 0) {
+			if (extMetasWithRefineCount > 0) {
 				const variantProps = {};
 				for (let i = 0; i < variantKeysLength; i++) {
 					const key = variantKeys[i];
 					if (Object.hasOwn(propsRecord, key)) variantProps[key] = propsRecord[key];
 				}
-				for (let i = 0; i < extMetasWithComputedCount; i++) {
-					const extComputed = extMetasWithComputed[i].resolveDefaults(resolved, variantProps);
-					for (const k in extComputed) {
-						if (!Object.hasOwn(extComputed, k)) continue;
-						resolved[k] = extComputed[k];
+				for (let i = 0; i < extMetasWithRefineCount; i++) {
+					const extDefaults = extMetasWithRefine[i].resolveDefaults(resolved, variantProps);
+					for (const k in extDefaults) {
+						if (!Object.hasOwn(extDefaults, k)) continue;
+						resolved[k] = extDefaults[k];
 					}
 				}
 				for (const k in variantProps) {
@@ -1050,7 +1106,7 @@ function create({ transformClass = (className) => className } = {}) {
 		const getVariants = (variants) => {
 			const variantProps = variants ?? EMPTY_DEFAULTS;
 			let resolvedVariants = resolveVariantsHot(variantProps);
-			if (resolveComputed) resolvedVariants = resolveComputed(resolvedVariants, variantProps, false);
+			if (resolveRefine) resolvedVariants = resolveRefine(resolvedVariants, variantProps, false);
 			return resolvedVariants;
 		};
 		const computedBaseClass = hasExtend ? clsx(...extBaseClassesArr, config.class) : clsx(config.class);
@@ -1062,8 +1118,9 @@ function create({ transformClass = (className) => className } = {}) {
 			staticDefaults,
 			resolveDefaults: resolveDefaultsFn,
 			compute,
-			resolveComputed,
-			transformClass
+			resolveRefine,
+			transformClass,
+			functionVariantKeys
 		};
 		const initComponent = (c, propKeys, style) => {
 			c.class = classFn;