clava 0.4.1 → 0.5.0

package/src/refine-warning.ts

@@ -0,0 +1,161 @@
+export interface RefineRunState {
+  remaining: number;
+  warned?: boolean;
+}
+
+export interface CreationFrame {
+  stack?: string;
+}
+
+export interface VariantChange {
+  from: unknown;
+  to: unknown;
+}
+
+// Once a refine loop is within this many iterations of the cap, start tracking
+// the latest value transition for 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.
+export const REFINE_UNSTABLE_TRACKING_WINDOW = 10;
+
+// 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.
+export 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();
+}
+
+export 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);
+    }
+  }
+  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}`;
+  }
+  return undefined;
+}
+
+function isInternalCreationFrame(line: string): boolean {
+  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: unknown): string {
+  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 === undefined) 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: Map<string, VariantChange>,
+  key: string,
+  from: unknown,
+  to: unknown,
+): void {
+  into.set(key, { from, to });
+}
+
+export function accumulateUnstableVariantChanges(
+  into: Map<string, VariantChange>,
+  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])) {
+      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], undefined);
+  }
+}
+
+function formatVariantChanges(changes: Map<string, VariantChange>): string {
+  return Array.from(changes)
+    .map(([key, { from, to }]) => {
+      return `${key}: ${formatVariantValue(from)} -> ${formatVariantValue(to)}`;
+    })
+    .join(", ");
+}
+
+interface WarnRefineLimitParams {
+  runState: RefineRunState;
+  creationFrame: CreationFrame | undefined;
+  unstableChanges: Map<string, VariantChange> | null;
+}
+
+export function warnRefineLimit({
+  runState,
+  creationFrame,
+  unstableChanges,
+}: WarnRefineLimitParams): 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;
+  let message =
+    "Clava: Maximum refine iterations exceeded. This can happen when a " +
+    "computed default variant or refine callback changes one of the " +
+    "variants 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);
+}

package/src/types.ts

@@ -254,7 +254,30 @@ type ExtractVariantValue<T> = T extends null
           : never;
 
 export type VariantValues<V> = {
-  [K in keyof V]?: ExtractVariantValue<V[K]>;
+  [K in keyof V]?: ExtractVariantValue<V[K]> | undefined;
+};
+
+interface DefaultVariantContext<V, K extends keyof V> {
+  defaultValue: ExtractVariantValue<V[K]> | undefined;
+  variants: Readonly<VariantValues<V>>;
+}
+
+type ComputedDefaultVariant<V, K extends keyof V> = (
+  context: DefaultVariantContext<V, K>,
+) => ExtractVariantValue<V[K]> | undefined;
+
+type NonFunctionVariantValue<T> = Exclude<T, (...args: any[]) => any>;
+
+type DefaultVariantValue<V, K extends keyof V> = [
+  NonFunctionVariantValue<ExtractVariantValue<V[K]>>,
+] extends [never]
+  ? ComputedDefaultVariant<V, K>
+  :
+      | NonFunctionVariantValue<ExtractVariantValue<V[K]>>
+      | ComputedDefaultVariant<V, K>;
+
+export type DefaultVariants<V> = {
+  [K in keyof V]?: DefaultVariantValue<V, K> | undefined;
 };
 
 export type StyleValue = CSS.Properties & {
@@ -269,7 +292,6 @@ export interface StyleClassValue {
 export interface RefineContext<V> {
   variants: VariantValues<V>;
   setVariants: (variants: VariantValues<V>) => void;
-  setDefaultVariants: (variants: VariantValues<V>) => void;
   addClass: (className: ClassValue) => void;
   addStyle: (style: StyleValue) => void;
 }

package/tests/build.test.ts

@@ -82,6 +82,7 @@ test("vite removes warning logic from the production bundle", async () => {
       expect(code).not.toContain("console.warn");
       expect(code).not.toContain("Clava: Maximum refine iterations exceeded");
       expect(code).not.toContain("Variant(s) that did not stabilize");
+      expect(code).not.toContain("Latest variant changes before warning");
       expect(code).not.toContain("Component created at");
       expect(code).not.toContain("captureStackTrace");
       expect(code).not.toMatch(/\.warned\b|["']warned["']/);

package/tests/component-api.test.ts

@@ -59,6 +59,33 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "sm" });
     });
 
+    test("getVariants omits undefined defaultVariants", () => {
+      const component = getModeComponent(
+        mode,
+        cv({
+          variants: { size: { sm: "sm", lg: "lg" } },
+          defaultVariants: { size: undefined },
+        }),
+      );
+      const variants = component.getVariants();
+      expect(variants).toStrictEqual({});
+      expect(Object.hasOwn(variants, "size")).toBe(false);
+    });
+
+    test("getVariants undefined defaultVariants clear inherited defaultVariants", () => {
+      const base = cv({
+        variants: { size: { sm: "sm", lg: "lg" } },
+        defaultVariants: { size: "sm" },
+      });
+      const component = getModeComponent(
+        mode,
+        cv({ extend: [base], defaultVariants: { size: undefined } }),
+      );
+      const variants = component.getVariants();
+      expect(variants).toStrictEqual({});
+      expect(Object.hasOwn(variants, "size")).toBe(false);
+    });
+
     test("getVariants returns variants set by refine setVariants", () => {
       const component = getModeComponent(
         mode,
@@ -100,7 +127,7 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "sm", color: "red" });
     });
 
-    test("getVariants re-runs when setDefaultVariants changes variants", () => {
+    test("getVariants re-runs when computed defaultVariants change variants", () => {
       const component = getModeComponent(
         mode,
         cv({
@@ -108,11 +135,10 @@ for (const config of Object.values(CONFIGS)) {
             size: { sm: "sm", lg: "lg" },
             color: { red: "red", blue: "blue" },
           },
-          refine: ({ variants, setDefaultVariants }) => {
-            setDefaultVariants({ color: "red" });
-            if (variants.color === "red") {
-              setDefaultVariants({ size: "lg" });
-            }
+          defaultVariants: {
+            color: () => "red" as const,
+            size: ({ defaultValue, variants }) =>
+              variants.color === "red" ? "lg" : defaultValue,
           },
         }),
       );
@@ -120,7 +146,7 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "lg", color: "red" });
     });
 
-    test("getVariants returns variants set by refine setDefaultVariants", () => {
+    test("getVariants returns computed defaultVariants", () => {
       const component = getModeComponent(
         mode,
         cv({
@@ -128,10 +154,9 @@ for (const config of Object.values(CONFIGS)) {
             size: { sm: "sm", lg: "lg" },
             color: { red: "red", blue: "blue" },
           },
-          refine: ({ variants, setDefaultVariants }) => {
-            if (variants.size === "lg") {
-              setDefaultVariants({ color: "blue" });
-            }
+          defaultVariants: {
+            color: ({ defaultValue, variants }) =>
+              variants.size === "lg" ? "blue" : defaultValue,
           },
         }),
       );
@@ -139,7 +164,7 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "lg", color: "blue" });
     });
 
-    test("getVariants setDefaultVariants does not override props", () => {
+    test("getVariants computed defaultVariants do not override props", () => {
       const component = getModeComponent(
         mode,
         cv({
@@ -147,8 +172,8 @@ for (const config of Object.values(CONFIGS)) {
             size: { sm: "sm", lg: "lg" },
             color: { red: "red", blue: "blue" },
           },
-          refine: ({ setDefaultVariants }) => {
-            setDefaultVariants({ color: "blue" });
+          defaultVariants: {
+            color: () => "blue" as const,
           },
         }),
       );
@@ -173,11 +198,11 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ color: "blue" });
     });
 
-    test("getVariants picks up setDefaultVariants from extended component", () => {
+    test("getVariants picks up computed defaultVariants from extended component", () => {
       const base = cv({
         variants: { size: { sm: "sm", lg: "lg" } },
-        refine: ({ setDefaultVariants }) => {
-          setDefaultVariants({ size: "lg" });
+        defaultVariants: {
+          size: () => "lg" as const,
         },
       });
       const component = getModeComponent(
@@ -192,11 +217,11 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "lg", color: "red" });
     });
 
-    test("getVariants picks up setDefaultVariants from grandparent component", () => {
+    test("getVariants picks up computed defaultVariants from grandparent component", () => {
       const grandparent = cv({
         variants: { size: { sm: "sm", lg: "lg" } },
-        refine: ({ setDefaultVariants }) => {
-          setDefaultVariants({ size: "lg" });
+        defaultVariants: {
+          size: () => "lg" as const,
         },
       });
       const parent = cv({ extend: [grandparent] });
@@ -238,21 +263,21 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "lg", active: true, color: "red" });
     });
 
-    test("getVariants preserves base setDefaultVariants after its own setVariants re-run", () => {
+    test("getVariants preserves computed defaultVariants after a setVariants re-run", () => {
       const base = cv({
         variants: {
           size: { sm: "sm", lg: "lg" },
           active: "",
           mode: { on: "on" },
         },
-        defaultVariants: { size: "sm" },
-        refine: ({ variants, setVariants, setDefaultVariants }) => {
+        defaultVariants: {
+          size: ({ defaultValue, variants }) =>
+            variants.mode === "on" ? "lg" : defaultValue,
+        },
+        refine: ({ variants, setVariants }) => {
           if (variants.active) {
             setVariants({ mode: "on" });
           }
-          if (variants.mode === "on") {
-            setDefaultVariants({ size: "lg" });
-          }
         },
       });
       const component = getModeComponent(mode, cv({ extend: [base] }));
@@ -276,11 +301,11 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "sm" });
     });
 
-    test("getVariants child setVariants keeps overriding base setDefaultVariants across re-runs", () => {
+    test("getVariants child setVariants keeps overriding base computed defaultVariants across re-runs", () => {
       const base = cv({
         variants: { color: { red: "red", blue: "blue" } },
-        refine: ({ setDefaultVariants }) => {
-          setDefaultVariants({ color: "blue" });
+        defaultVariants: {
+          color: () => "blue" as const,
         },
       });
       const component = getModeComponent(
@@ -300,11 +325,11 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ color: "red", size: "sm" });
     });
 
-    test("getVariants setVariants sticks across re-runs", () => {
+    test("getVariants setVariants sticks across computed default re-runs", () => {
       const base = cv({
         variants: { color: { red: "red", blue: "blue" } },
-        refine: ({ setDefaultVariants }) => {
-          setDefaultVariants({ color: "blue" });
+        defaultVariants: {
+          color: () => "blue" as const,
         },
       });
       const component = getModeComponent(
@@ -323,20 +348,21 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ color: "red", done: true });
     });
 
-    test("getVariants base setDefaultVariants can override child static defaults after a re-run", () => {
+    test("getVariants base computed defaultVariants can override child static defaults after a re-run", () => {
       const base = cv({
         variants: {
           size: { sm: "sm", lg: "lg" },
           active: "",
           mode: { on: "on" },
         },
-        refine: ({ variants, setVariants, setDefaultVariants }) => {
+        defaultVariants: {
+          size: ({ defaultValue, variants }) =>
+            variants.mode === "on" ? "lg" : defaultValue,
+        },
+        refine: ({ variants, setVariants }) => {
           if (variants.active) {
             setVariants({ mode: "on" });
           }
-          if (variants.mode === "on") {
-            setDefaultVariants({ size: "lg" });
-          }
         },
       });
       const component = getModeComponent(
@@ -347,7 +373,7 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ size: "lg", active: true, mode: "on" });
     });
 
-    test("getVariants setVariants from earlier extends overrides setDefaultVariants from later extends", () => {
+    test("getVariants setVariants from earlier extends overrides computed defaultVariants from later extends", () => {
       const first = cv({
         variants: { color: { red: "first-red", blue: "first-blue" } },
         refine: ({ setVariants }) => {
@@ -356,8 +382,8 @@ for (const config of Object.values(CONFIGS)) {
       });
       const second = cv({
         variants: { color: { red: "second-red", blue: "second-blue" } },
-        refine: ({ setDefaultVariants }) => {
-          setDefaultVariants({ color: "blue" });
+        defaultVariants: {
+          color: () => "blue" as const,
         },
       });
       const component = getModeComponent(mode, cv({ extend: [first, second] }));
@@ -365,17 +391,17 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ color: "red" });
     });
 
-    test("getVariants setDefaultVariants from later extends overrides setDefaultVariants from earlier extends", () => {
+    test("getVariants computed defaultVariants from later extends override earlier extends", () => {
       const first = cv({
         variants: { color: { red: "first-red", blue: "first-blue" } },
-        refine: ({ setDefaultVariants }) => {
-          setDefaultVariants({ color: "red" });
+        defaultVariants: {
+          color: () => "red" as const,
         },
       });
       const second = cv({
         variants: { color: { red: "second-red", blue: "second-blue" } },
-        refine: ({ setDefaultVariants }) => {
-          setDefaultVariants({ color: "blue" });
+        defaultVariants: {
+          color: () => "blue" as const,
         },
       });
       const component = getModeComponent(mode, cv({ extend: [first, second] }));
@@ -383,7 +409,7 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ color: "blue" });
     });
 
-    test("getVariants setDefaultVariants does not override stable setVariants on later passes", () => {
+    test("getVariants computed defaultVariants do not override stable setVariants on later passes", () => {
       const base = cv({
         variants: { color: { red: "base-red", blue: "base-blue" } },
         refine: ({ setVariants }) => {
@@ -395,10 +421,9 @@ for (const config of Object.values(CONFIGS)) {
         cv({
           extend: [base],
           variants: { color: { red: "child-red", blue: "child-blue" } },
-          refine: ({ variants, setDefaultVariants }) => {
-            if (variants.color === "red") {
-              setDefaultVariants({ color: "blue" });
-            }
+          defaultVariants: {
+            color: ({ defaultValue, variants }) =>
+              variants.color === "red" ? "blue" : defaultValue,
           },
         }),
       );
@@ -406,7 +431,7 @@ for (const config of Object.values(CONFIGS)) {
       expect(variants).toEqual({ color: "red" });
     });
 
-    test("getVariants setDefaultVariants does not override setVariants from a previous pass", () => {
+    test("getVariants computed defaultVariants do not override setVariants from a previous pass", () => {
       const component = getModeComponent(
         mode,
         cv({
@@ -414,13 +439,14 @@ for (const config of Object.values(CONFIGS)) {
             color: { red: "red", blue: "blue" },
             done: "",
           },
-          refine: ({ variants, setVariants, setDefaultVariants }) => {
+          defaultVariants: {
+            color: ({ defaultValue, variants }) =>
+              variants.done ? "blue" : defaultValue,
+          },
+          refine: ({ variants, setVariants }) => {
             if (!variants.done) {
               setVariants({ color: "red", done: true });
             }
-            if (variants.done) {
-              setDefaultVariants({ color: "blue" });
-            }
           },
         }),
       );

package/tests/extend.test.ts

@@ -144,7 +144,7 @@ for (const config of Object.values(CONFIGS)) {
       });
     });
 
-    test("extend disabled variant value with refine setDefaultVariants", () => {
+    test("extend disabled variant value with computed defaultVariants", () => {
       const base = cv({
         variants: {
           size: {
@@ -158,8 +158,8 @@ for (const config of Object.values(CONFIGS)) {
         cv({
           extend: [base],
           variants: { size: { sm: null } },
-          refine: ({ setDefaultVariants }) => {
-            setDefaultVariants({ size: "lg" });
+          defaultVariants: {
+            size: () => "lg" as const,
           },
         }),
       );
@@ -173,19 +173,53 @@ for (const config of Object.values(CONFIGS)) {
         cv({
           extend: [base],
           variants: { size: { sm: null } },
-          refine: ({ setDefaultVariants }) => {
-            setDefaultVariants({
-              // @ts-expect-error disabled variant value cannot be set
-              size:
-                // no error
-                "sm",
-            });
+          defaultVariants: {
+            // @ts-expect-error disabled variant value cannot be set
+            size: () =>
+              // no error
+              "sm",
           },
         }),
       );
       expect(getStyleClass(invalidComponent())).toEqual({ class: "" });
     });
 
+    test("extend filters disabled values from inherited computed defaultVariants", () => {
+      const base = cv({
+        variants: {
+          size: {
+            sm: { class: "base-sm", style: { fontSize: "12px" } },
+            lg: { class: "base-lg", style: { fontSize: "16px" } },
+          },
+        },
+        defaultVariants: {
+          size: () => "sm" as const,
+        },
+      });
+      const component = getModeComponent(
+        mode,
+        cv({
+          extend: [base],
+          variants: {
+            size: { sm: null },
+            color: { red: "red", blue: "blue" },
+          },
+          defaultVariants: {
+            size: "lg",
+            color: ({ variants }) => (variants.size === "lg" ? "blue" : "red"),
+          },
+        }),
+      );
+      expect(getStyleClass(component())).toEqual({
+        class: cls("base-lg blue"),
+        fontSize: "16px",
+      });
+      expect(component.getVariants()).toEqual({
+        size: "lg",
+        color: "blue",
+      });
+    });
+
     test("extend disabled variant value with refine setVariants", () => {
       const base = cv({
         variants: {

package/tests/prototype-pollution.test.ts

@@ -27,11 +27,10 @@ test("render ignores keys inherited from Object.prototype", () => {
   expect(component({}).class).toBe("sm");
 });
 
-test("extend's resolveDefaults ignores polluted prototype on parent's refine", () => {
+test("extend's resolver ignores polluted prototype on parent's refine", () => {
   // Base's refine branches on its own variants.size — if the polluted "size"
-  // key leaks into resolveDefaultsFn's resolvedVariants, the refine callback
-  // would see size = "lg" instead of the staticDefault "sm" and emit the
-  // lg-specific class.
+  // key leaks into resolved variants, the refine callback would see size =
+  // "lg" instead of the staticDefault "sm" and emit the lg-specific class.
   proto.size = "lg";
   const base = cv({
     variants: { size: { sm: "sm", lg: "lg" } },

package/tests/refine-warning.test.ts

@@ -0,0 +1,28 @@
+import { expect, test } from "vitest";
+import { formatCreationStack } from "../src/refine-warning.ts";
+
+test("formatCreationStack returns the first app frame", () => {
+  const stack = [
+    "Error",
+    "    at captureCreationFrame (/repo/packages/clava/src/refine-warning.ts:31:10)",
+    "    at cv (/repo/packages/clava/src/index.ts:734:9)",
+    "    at eval (/repo/app/src/button.ts:12:21)",
+    "    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)",
+  ].join("\n");
+
+  expect(formatCreationStack({ stack })).toBe(
+    "    at eval (/repo/app/src/button.ts:12:21)",
+  );
+});
+
+test("formatCreationStack omits dependency and runtime frames", () => {
+  const stack = [
+    "Error",
+    "    at captureCreationFrame (/repo/packages/clava/src/refine-warning.ts:31:10)",
+    "    at cv(/repo/packages/clava/src/index.ts:734:9)",
+    "    at eval (/repo/node_modules/package/index.js:1:1)",
+    "    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)",
+  ].join("\n");
+
+  expect(formatCreationStack({ stack })).toBeUndefined();
+});