clava 0.4.0 → 0.4.1

package/src/index.ts

@@ -59,7 +59,7 @@ type ResolveRefineFn = (
 
 interface RefineRunState {
   remaining: number;
-  warned: boolean;
+  warned?: boolean;
 }
 
 // Internal metadata stored on components but hidden from public types.
@@ -94,6 +94,10 @@ interface ComponentMeta {
 
 const META_KEY = "__meta";
 
+interface ComponentWithMeta {
+  [META_KEY]?: ComponentMeta;
+}
+
 const EMPTY_DEFAULTS: Record<string, unknown> = Object.freeze({}) as Record<
   string,
   unknown
@@ -101,6 +105,13 @@ const EMPTY_DEFAULTS: Record<string, unknown> = Object.freeze({}) as Record<
 
 const MAX_REFINE_RUNS = 50;
 
+// Once a refine loop is within this many iterations of the cap, start tracking
+// every variant key that changes between iterations so the warning can report
+// every key that contributed to the oscillation, not just the keys that
+// happened to flip on the final step. Convergent loops (the common case) exit
+// well before this threshold and pay no per-iteration tracking cost.
+const REFINE_UNSTABLE_TRACKING_WINDOW = 10;
+
 function areVariantsEqual(
   a: Record<string, unknown>,
   b: Record<string, unknown>,
@@ -116,16 +127,94 @@ function areVariantsEqual(
   return true;
 }
 
-function warnRefineLimit(runState: RefineRunState): void {
+interface CreationFrame {
+  stack?: string;
+}
+
+// Captures the call site of the function passed in `skipFn` so refine-limit
+// warnings can point developers at the originating `cv()` call. Returns
+// `undefined` in production so bundlers that replace `process.env.NODE_ENV` at
+// build time can drop the entire warning machinery. The underlying `.stack`
+// string is formatted lazily on first access in every major engine (V8,
+// SpiderMonkey, JavaScriptCore), so holding the captured frame for the
+// lifetime of the component is cheap when no warning fires.
+function captureCreationFrame(skipFn: Function): CreationFrame | undefined {
+  if (process.env.NODE_ENV === "production") return undefined;
+  if (typeof Error.captureStackTrace === "function") {
+    const holder: CreationFrame = {};
+    Error.captureStackTrace(holder, skipFn);
+    return holder;
+  }
+  // Engines without `Error.captureStackTrace` (SpiderMonkey, JavaScriptCore)
+  // can't strip internal frames, but their `Error.stack` getter is still
+  // lazy, so returning the Error instance defers the format cost. The
+  // resulting trace includes 1–2 extra frames at the top from this helper and
+  // `cv` itself.
+  return new Error();
+}
+
+function formatCreationStack(frame: CreationFrame): string | undefined {
+  let stack = frame.stack;
+  if (!stack) return undefined;
+  // V8 prefixes the stack with a leading "Error" / "Error: message" line that
+  // isn't meaningful for a captured location — drop it.
+  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;
+}
+
+// Accumulates the union of variant keys that differ between `prev` and `next`
+// into `into`. Called on every non-converging iteration of the refine loop so
+// the refine-limit warning can report any key that ever changed across runs,
+// not just the keys that changed on the final iteration (two keys flipping at
+// different cadences could otherwise hide each other on the last step).
+function accumulateUnstableVariantKeys(
+  into: Set<string>,
+  prev: Record<string, unknown>,
+  next: Record<string, unknown>,
+): void {
+  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: RefineRunState,
+  creationFrame: CreationFrame | undefined,
+  unstableKeys: Set<string> | null,
+): void {
+  // Bundlers are expected to replace this branch with a production literal,
+  // allowing warning-only code below to be removed from consumer bundles.
+  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(
@@ -154,7 +243,9 @@ function mergeVariants(
     for (const key in source) {
       if (!Object.hasOwn(source, key)) continue;
       const value = source[key];
-      if (!Object.is(target[key], value)) changed = true;
+      if (!Object.is(target[key], value)) {
+        changed = true;
+      }
       target[key] = value;
     }
     return changed;
@@ -163,21 +254,22 @@ function mergeVariants(
     if (!Object.hasOwn(source, key)) continue;
     if (skipKeys.has(key)) continue;
     const value = source[key];
-    if (!Object.is(target[key], value)) changed = true;
+    if (!Object.is(target[key], value)) {
+      changed = true;
+    }
     target[key] = value;
   }
   return changed;
 }
 
-// Dynamic property access on function requires cast through unknown.
+// Components carry internal metadata on a non-public property so user-facing
+// component types stay clean.
 function getComponentMeta(component: AnyComponent): ComponentMeta | undefined {
-  return (component as unknown as Record<string, unknown>)[META_KEY] as
-    | ComponentMeta
-    | undefined;
+  return (component as AnyComponent & ComponentWithMeta)[META_KEY];
 }
 
 function setComponentMeta(component: AnyComponent, meta: ComponentMeta): void {
-  (component as unknown as Record<string, unknown>)[META_KEY] = meta;
+  (component as AnyComponent & ComponentWithMeta)[META_KEY] = meta;
 }
 
 export type {
@@ -321,9 +413,15 @@ function isVariantDisabled(
 }
 
 function getVariantValueKey(value: unknown): string | undefined {
-  if (typeof value === "string") return value;
-  if (typeof value === "number") return String(value);
-  if (typeof value === "boolean") return String(value);
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  if (typeof value === "boolean") {
+    return String(value);
+  }
   return undefined;
 }
 
@@ -343,7 +441,9 @@ function collectDisabledVariantKeys(
   config: CVConfig<Variants, AnyComponent[]>,
 ): Set<string> {
   const keys = new Set<string>();
-  if (!config.variants) return keys;
+  if (!config.variants) {
+    return keys;
+  }
   for (const key in config.variants) {
     if (!Object.hasOwn(config.variants, key)) continue;
     if ((config.variants as Record<string, unknown>)[key] === null) {
@@ -357,7 +457,9 @@ function collectDisabledVariantValues(
   config: CVConfig<Variants, AnyComponent[]>,
 ): Record<string, Set<string>> {
   const values: Record<string, Set<string>> = {};
-  if (!config.variants) return values;
+  if (!config.variants) {
+    return values;
+  }
   for (const key in config.variants) {
     if (!Object.hasOwn(config.variants, key)) continue;
     const variant = (config.variants as Record<string, unknown>)[key];
@@ -397,14 +499,22 @@ function normalizeKeySource(source: unknown): NormalizedSource {
     };
   }
 
-  if (!source) return EMPTY_SOURCE;
+  if (!source) {
+    return EMPTY_SOURCE;
+  }
   if (typeof source !== "object" && typeof source !== "function") {
     return EMPTY_SOURCE;
   }
   const typed = source as Record<string, unknown>;
-  if (typeof typed.getVariants !== "function") return EMPTY_SOURCE;
-  if (!Array.isArray(typed.propKeys)) return EMPTY_SOURCE;
-  if (!Array.isArray(typed.variantKeys)) return EMPTY_SOURCE;
+  if (typeof typed.getVariants !== "function") {
+    return EMPTY_SOURCE;
+  }
+  if (!Array.isArray(typed.propKeys)) {
+    return EMPTY_SOURCE;
+  }
+  if (!Array.isArray(typed.variantKeys)) {
+    return EMPTY_SOURCE;
+  }
 
   return {
     propKeys: typed.propKeys as string[],
@@ -540,7 +650,9 @@ function buildPrebuiltVariant(variantDef: unknown): PrebuiltVariant {
     if (!Object.hasOwn(variantDef, key)) continue;
     const value = variantDef[key];
     if (value === null) {
-      if (!disabledValues) disabledValues = new Set<string>();
+      if (!disabledValues) {
+        disabledValues = new Set<string>();
+      }
       disabledValues.add(key);
       continue;
     }
@@ -619,7 +731,9 @@ export function create({
     if (extend) {
       for (const ext of extend) {
         const meta = getComponentMeta(ext);
-        if (meta) Object.assign(staticDefaults, meta.staticDefaults);
+        if (meta) {
+          Object.assign(staticDefaults, meta.staticDefaults);
+        }
       }
     }
     if (variants) {
@@ -700,6 +814,18 @@ export function create({
     const extMetasWithRefineCount = extMetasWithRefine.length;
     const shouldCollectChangedVariants = extMetasWithRefineCount > 0;
 
+    // Call-site frame captured at the `cv()` call site so refine-limit warnings
+    // can point developers at the component definition. Skipped entirely for
+    // components that can never enter the refine loop, and stripped in
+    // production via the NODE_ENV guard inside `captureCreationFrame`. The
+    // frame is captured at creation time but the underlying `.stack` string is
+    // formatted lazily on first access, so component creation stays cheap
+    // unless the warning actually fires.
+    const canTriggerRefineWarning = !!refine || extMetasWithRefineCount > 0;
+    const creationFrame = canTriggerRefineWarning
+      ? captureCreationFrame(cv)
+      : undefined;
+
     // Function variant keys inherited from extends, filtered through this
     // component's own variants: a static (object/shorthand) variant in this
     // component replaces an inherited function variant for the same key.
@@ -753,7 +879,9 @@ export function create({
       staticVariantsOverridingExtFn !== null
     ) {
       staticExtSkipKeys = new Set<string>();
-      for (const k of disabledVariantKeys) staticExtSkipKeys.add(k);
+      for (const k of disabledVariantKeys) {
+        staticExtSkipKeys.add(k);
+      }
       for (let i = 0; i < functionVariantCount; i++) {
         staticExtSkipKeys.add(functionVariantNames[i]);
       }
@@ -777,7 +905,9 @@ export function create({
     ): void {
       if (!hasAnyDisabled) {
         for (const key in input) {
-          if (Object.hasOwn(input, key)) out[key] = input[key];
+          if (Object.hasOwn(input, key)) {
+            out[key] = input[key];
+          }
         }
         return;
       }
@@ -901,7 +1031,9 @@ export function create({
         defaults[k] = v;
       }
 
-      if (!hasAnyDisabled) return defaults;
+      if (!hasAnyDisabled) {
+        return defaults;
+      }
 
       // Filter disabled
       const result: Record<string, unknown> = {};
@@ -938,7 +1070,9 @@ export function create({
           const filteredVariants: Record<string, unknown> = {};
           for (let i = 0; i < variantKeysLength; i++) {
             const k = variantKeys[i];
-            if (Object.hasOwn(resolved, k)) filteredVariants[k] = resolved[k];
+            if (Object.hasOwn(resolved, k)) {
+              filteredVariants[k] = resolved[k];
+            }
           }
           ownVariants = filteredVariants;
         }
@@ -949,7 +1083,9 @@ export function create({
         const localCClasses: ClassValue[] | null = collectOutput ? [] : null;
         let localCStyle: StyleValue | null = null;
         const ensureUpdated = (): Record<string, unknown> => {
-          if (updatedVariants) return updatedVariants;
+          if (updatedVariants) {
+            return updatedVariants;
+          }
           const u: Record<string, unknown> = {};
           Object.assign(u, ownVariants);
           updatedVariants = u;
@@ -961,7 +1097,9 @@ export function create({
           protect = false,
         ) => {
           if (shouldCollectChangedVariants) {
-            if (!changedVariants) changedVariants = {};
+            if (!changedVariants) {
+              changedVariants = {};
+            }
             changedVariants[key] = value;
           }
           if (protect && protectedVariants) {
@@ -1036,16 +1174,22 @@ export function create({
           },
           addStyle: (newStyle: StyleValue) => {
             if (!collectOutput) return;
-            if (!localCStyle) localCStyle = {};
+            if (!localCStyle) {
+              localCStyle = {};
+            }
             Object.assign(localCStyle, newStyle);
           },
         };
         const result = refine(ctx);
         if (collectOutput && result != null) {
           const r = extractClassAndStylePrebuilt(result);
-          if (r.class != null) localCClasses?.push(r.class);
+          if (r.class != null) {
+            localCClasses?.push(r.class);
+          }
           if (r.style) {
-            if (!localCStyle) localCStyle = {};
+            if (!localCStyle) {
+              localCStyle = {};
+            }
             Object.assign(localCStyle, r.style);
           }
         }
@@ -1129,7 +1273,9 @@ export function create({
           extSkipKeys = skipKeys;
         } else {
           extSkipKeys = new Set(skipKeys);
-          for (const k of staticExtSkipKeys) extSkipKeys.add(k);
+          for (const k of staticExtSkipKeys) {
+            extSkipKeys.add(k);
+          }
         }
 
         let extSkipVals: Record<string, Set<string>> | null;
@@ -1146,7 +1292,9 @@ export function create({
             const existing = extSkipVals[k];
             if (existing) {
               const merged = new Set<string>(existing);
-              for (const v of staticExtSkipValues[k]) merged.add(v);
+              for (const v of staticExtSkipValues[k]) {
+                merged.add(v);
+              }
               extSkipVals[k] = merged;
             } else {
               extSkipVals[k] = staticExtSkipValues[k];
@@ -1211,7 +1359,9 @@ export function create({
       }
 
       // Apply own base style (after extends' styles, matching original order).
-      if (hasBaseStyle) Object.assign(styleOut, baseStyle);
+      if (hasBaseStyle) {
+        Object.assign(styleOut, baseStyle);
+      }
 
       // Apply own variants. Skip keys/values come from caller (e.g., parent
       // wants its own function variant to override this variant).
@@ -1246,12 +1396,20 @@ export function create({
           if (selectedKey == null) continue;
           const v = variant.values[selectedKey];
           if (!v) continue;
-          if (v.class != null) classesOut.push(v.class as ClsxClassValue);
-          if (v.style) Object.assign(styleOut, v.style);
+          if (v.class != null) {
+            classesOut.push(v.class as ClsxClassValue);
+          }
+          if (v.style) {
+            Object.assign(styleOut, v.style);
+          }
         } else if (variant.shorthand && selectedValue === true) {
           const v = variant.shorthand;
-          if (v.class != null) classesOut.push(v.class as ClsxClassValue);
-          if (v.style) Object.assign(styleOut, v.style);
+          if (v.class != null) {
+            classesOut.push(v.class as ClsxClassValue);
+          }
+          if (v.style) {
+            Object.assign(styleOut, v.style);
+          }
         }
       }
 
@@ -1275,8 +1433,12 @@ export function create({
         const computedResult = fn(selectedValue);
         if (computedResult == null) continue;
         const r = extractClassAndStylePrebuilt(computedResult);
-        if (r.class != null) classesOut.push(r.class as ClsxClassValue);
-        if (r.style) Object.assign(styleOut, r.style);
+        if (r.class != null) {
+          classesOut.push(r.class as ClsxClassValue);
+        }
+        if (r.style) {
+          Object.assign(styleOut, r.style);
+        }
       }
 
       // Apply `refine` results — must come after own variants (static and
@@ -1286,38 +1448,16 @@ export function create({
           classesOut.push(cClasses[i] as ClsxClassValue);
         }
       }
-      if (cStyle) Object.assign(styleOut, cStyle);
+      if (cStyle) {
+        Object.assign(styleOut, cStyle);
+      }
 
       return workingResolved;
     };
 
     const compute: ComputeFn =
       !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,
-            );
-          }
+        ? computeOnce
         : (
             resolved,
             userVariantProps,
@@ -1330,10 +1470,15 @@ export function create({
             pendingProtectedVariants,
             protectedVariantKeys,
           ) => {
-            runState ??= { remaining: MAX_REFINE_RUNS, warned: false };
+            runState ??= { remaining: MAX_REFINE_RUNS };
             protectedVariants ??= {};
             protectedVariantKeys ??= new Set<string>();
             let workingResolved = resolved;
+            // Union of variant keys that differed on non-converging iterations
+            // inside the tracking window, so the refine-limit warning can name
+            // every variant that contributed to the late-stage oscillation.
+            // Lazy-init keeps convergent loops allocation-free.
+            let unstableKeys: Set<string> | null = null;
             let lastClasses: ClsxClassValue[] = [];
             let lastStyle: StyleValue = {};
             let isFirstRun = true;
@@ -1397,10 +1542,24 @@ export function create({
                 return nextResolved;
               }
 
+              if (
+                process.env.NODE_ENV !== "production" &&
+                runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW
+              ) {
+                if (!unstableKeys) {
+                  unstableKeys = new Set<string>();
+                }
+                accumulateUnstableVariantKeys(
+                  unstableKeys,
+                  workingResolved,
+                  nextResolved,
+                );
+              }
+
               if (useDirectOutput && runState.remaining === 0) {
                 // Keep the direct output from the last allowed run. Rolling
                 // back here would drop it before the fallback copy below.
-                warnRefineLimit(runState);
+                warnRefineLimit(runState, creationFrame, unstableKeys);
                 return nextResolved;
               }
 
@@ -1420,7 +1579,7 @@ export function create({
               isFirstRun = false;
             }
 
-            warnRefineLimit(runState);
+            warnRefineLimit(runState, creationFrame, unstableKeys);
 
             for (let i = 0; i < lastClasses.length; i++) {
               classesOut.push(lastClasses[i]);
@@ -1493,10 +1652,15 @@ export function create({
             pendingProtectedVariants,
             protectedVariantKeys,
           ) => {
-            runState ??= { remaining: MAX_REFINE_RUNS, warned: false };
+            runState ??= { remaining: MAX_REFINE_RUNS };
             protectedVariants ??= {};
             protectedVariantKeys ??= new Set<string>();
             let workingResolved = resolved;
+            // Union of variant keys that differed on non-converging iterations
+            // inside the tracking window — see the compute loop above for the
+            // shared rationale. Lazy-init keeps convergent loops
+            // allocation-free.
+            let unstableKeys: Set<string> | null = null;
             let reachedLimit = true;
 
             while (runState.remaining > 0) {
@@ -1536,11 +1700,24 @@ export function create({
                 break;
               }
 
+              if (
+                process.env.NODE_ENV !== "production" &&
+                runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW
+              ) {
+                if (!unstableKeys) {
+                  unstableKeys = new Set<string>();
+                }
+                accumulateUnstableVariantKeys(
+                  unstableKeys,
+                  workingResolved,
+                  nextResolved,
+                );
+              }
               workingResolved = nextResolved;
             }
 
             if (reachedLimit) {
-              warnRefineLimit(runState);
+              warnRefineLimit(runState, creationFrame, unstableKeys);
             }
 
             return workingResolved;

package/src/types.ts

@@ -76,11 +76,11 @@ type ComponentPropKey<R extends ComponentResult> =
 
 // Key source types - what can be passed as additional parameters to splitProps
 export type KeySourceArray = readonly string[];
-export type KeySourceComponent = {
+export interface KeySourceComponent {
   propKeys: readonly string[];
   variantKeys: readonly string[];
   getVariants: () => Record<string, unknown>;
-};
+}
 export type KeySource = KeySourceArray | KeySourceComponent;
 
 // Check if source is a component (has getVariants)

package/src/utils.ts

@@ -39,7 +39,9 @@ export function hyphenToCamel(str: string) {
   }
   // Fast path: no hyphen -> return as-is
   let hyphenIndex = str.indexOf("-");
-  if (hyphenIndex === -1) return str;
+  if (hyphenIndex === -1) {
+    return str;
+  }
 
   let result = "";
   let lastIndex = 0;
@@ -91,7 +93,9 @@ export function camelToHyphen(str: string) {
     lastIndex = i + 1;
   }
 
-  if (lastIndex === 0) return str;
+  if (lastIndex === 0) {
+    return str;
+  }
   return result + str.slice(lastIndex);
 }
 
@@ -102,7 +106,9 @@ export function camelToHyphen(str: string) {
  * parseLengthValue("2em"); // "2em"
  */
 export function parseLengthValue(value: string | number) {
-  if (typeof value === "string") return value;
+  if (typeof value === "string") {
+    return value;
+  }
   return `${value}px`;
 }
 
@@ -135,7 +141,10 @@ export function htmlStyleToStyleValue(styleString: string) {
     }
     if (i >= len || styleString.charCodeAt(i) === 59) {
       // No colon found - skip this declaration
-      if (i < len) i++; // skip ';'
+      if (i < len) {
+        // Skip ';'.
+        i++;
+      }
       continue;
     }
     let propEnd = i;
@@ -147,12 +156,17 @@ export function htmlStyleToStyleValue(styleString: string) {
     }
     if (propEnd === propStart) {
       // Empty property - skip
-      while (i < len && styleString.charCodeAt(i) !== 59) i++;
-      if (i < len) i++;
+      while (i < len && styleString.charCodeAt(i) !== 59) {
+        i++;
+      }
+      if (i < len) {
+        i++;
+      }
       continue;
     }
     const property = styleString.slice(propStart, propEnd);
-    i++; // skip ':'
+    // Skip ':'.
+    i++;
     // Skip whitespace before value
     while (i < len) {
       const c = styleString.charCodeAt(i);
@@ -160,14 +174,19 @@ export function htmlStyleToStyleValue(styleString: string) {
       i++;
     }
     const valStart = i;
-    while (i < len && styleString.charCodeAt(i) !== 59) i++;
+    while (i < len && styleString.charCodeAt(i) !== 59) {
+      i++;
+    }
     let valEnd = i;
     while (valEnd > valStart) {
       const c = styleString.charCodeAt(valEnd - 1);
       if (c !== 32 && c !== 9 && c !== 10 && c !== 13) break;
       valEnd--;
     }
-    if (i < len) i++; // skip ';'
+    if (i < len) {
+      // Skip ';'.
+      i++;
+    }
     if (valEnd === valStart) continue;
     const value = styleString.slice(valStart, valEnd);
     // CSS property names and values are dynamic - cast required for index access
@@ -229,7 +248,9 @@ export function styleValueToHTMLStyle(style: StyleValue): string {
     if (!hasOwn.call(style, key)) continue;
     const value = (style as Record<string, unknown>)[key];
     if (value == null) continue;
-    if (result) result += "; ";
+    if (result) {
+      result += "; ";
+    }
     result += camelToHyphen(key);
     result += ": ";
     result += value as string | number;