clava 0.4.2 → 0.6.0

package/src/refine-warning.ts

@@ -145,8 +145,8 @@ export function warnRefineLimit({
   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.";
+    "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)}.`;

package/src/types.ts

@@ -1,5 +1,20 @@
 import type * as CSS from "csstype";
 
+/**
+ * A class value accepted by Clava. It supports strings, numbers, booleans,
+ * nullish values, and nested arrays.
+ *
+ * @example
+ * ```ts
+ * import type { ClassValue } from "clava";
+ *
+ * const className: ClassValue = [
+ *   "button",
+ *   false && "button-hidden",
+ *   ["button-primary"],
+ * ];
+ * ```
+ */
 export type ClassValue =
   | string
   | number
@@ -17,21 +32,68 @@ export type CSSProperties = CSS.Properties;
 
 export type StyleProperty = JSXCSSProperties | HTMLCSSProperties | string;
 
+/**
+ * The prop object returned by a component's `.jsx()` mode.
+ *
+ * @example
+ * ```ts
+ * import { type JSXProps, cv } from "clava";
+ *
+ * const button = cv({ class: "button" });
+ * const props: JSXProps = button.jsx();
+ * ```
+ */
 export interface JSXProps {
   className: string;
   style: JSXCSSProperties;
 }
 
+/**
+ * The prop object returned by a component's `.html()` mode. The `style` value
+ * is serialized as an HTML style string.
+ *
+ * @example
+ * ```ts
+ * import { type HTMLProps, cv } from "clava";
+ *
+ * const button = cv({ style: { color: "red" } });
+ * const props: HTMLProps = button.html();
+ * ```
+ */
 export interface HTMLProps {
   class: string;
   style: string;
 }
 
+/**
+ * The prop object returned by a component's `.htmlObj()` mode. The `style`
+ * value uses hyphenated CSS property names.
+ *
+ * @example
+ * ```ts
+ * import { type HTMLObjProps, cv } from "clava";
+ *
+ * const button = cv({ style: { fontSize: "16px" } });
+ * const props: HTMLObjProps = button.htmlObj();
+ * ```
+ */
 export interface HTMLObjProps {
   class: string;
   style: HTMLCSSProperties;
 }
 
+/**
+ * The default prop object returned by a Clava component. It uses `class`
+ * rather than `className` and keeps styles as a normalized object.
+ *
+ * @example
+ * ```ts
+ * import { type StyleClassProps, cv } from "clava";
+ *
+ * const button = cv({ class: "button" });
+ * const props: StyleClassProps = button();
+ * ```
+ */
 export interface StyleClassProps {
   class: string;
   style: StyleValue;
@@ -177,6 +239,25 @@ export interface ModalComponent<V, R extends ComponentResult> {
   propKeys: (keyof V | ComponentPropKey<R>)[];
 }
 
+/**
+ * A callable Clava component returned by `cv()`. It includes the default
+ * output mode plus `.jsx()`, `.html()`, and `.htmlObj()` mode helpers.
+ *
+ * @example
+ * ```ts
+ * import { type CVComponent, cv } from "clava";
+ *
+ * const button: CVComponent<{
+ *   size: { sm: string; lg: string };
+ * }> = cv({
+ *   variants: {
+ *     size: { sm: "button-sm", lg: "button-lg" },
+ *   },
+ * });
+ *
+ * button.jsx({ size: "lg" });
+ * ```
+ */
 export interface CVComponent<
   V extends Variants = {},
   E extends AnyComponent[] = [],
@@ -254,13 +335,60 @@ 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;
 };
 
+type ComputedDefaultVariant<V, K extends keyof V> = (
+  defaultValue: ExtractVariantValue<V[K]> | undefined,
+  variants: Readonly<VariantValues<V>>,
+) => 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;
+};
+
+/**
+ * A normalized style object accepted by Clava config, variant, and refine
+ * style entries. CSS custom properties are supported with string values.
+ *
+ * @example
+ * ```ts
+ * import type { StyleValue } from "clava";
+ *
+ * const style: StyleValue = {
+ *   color: "red",
+ *   "--button-accent": "oklch(62% 0.2 250)",
+ * };
+ * ```
+ */
 export type StyleValue = CSS.Properties & {
   [key: `--${string}`]: string;
 };
 
+/**
+ * A value that contributes both class and style output from a base config,
+ * variant value, function variant, or refine callback.
+ *
+ * @example
+ * ```ts
+ * import type { StyleClassValue } from "clava";
+ *
+ * const tone: StyleClassValue = {
+ *   class: "button-primary",
+ *   style: { color: "white" },
+ * };
+ * ```
+ */
 export interface StyleClassValue {
   style?: StyleValue;
   class?: ClassValue;
@@ -269,7 +397,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/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/language-service.test.ts

@@ -80,7 +80,10 @@ function createLanguageServiceHost(
 function createLanguageServiceFixture(
   consumerSource: string,
 ): LanguageServiceFixture {
-  const tempDir = mkdtempSync(join(workspaceDir, ".tmp-language-service-"));
+  const tempRoot = join(workspaceDir, ".tmp");
+  mkdirSync(tempRoot, { recursive: true });
+
+  const tempDir = mkdtempSync(join(tempRoot, "language-service-"));
   tempDirs.push(tempDir);
 
   const fixtureSourceDir = join(tempDir, "src");
@@ -134,6 +137,14 @@ afterEach(() => {
 });
 
 describe("TypeScript language service", () => {
+  test("creates fixtures inside the workspace .tmp directory", () => {
+    const fixture = createLanguageServiceFixture(getVariantFixtureSource());
+    const fixtureDir = dirname(fixture.consumerFile);
+    const fixturePrefix = join(workspaceDir, ".tmp", "language-service-");
+
+    expect(fixtureDir.startsWith(fixturePrefix)).toBe(true);
+  });
+
   test("goes to the local variant definition from a variant prop usage", () => {
     const fixture = createLanguageServiceFixture(getVariantFixtureSource());
     const definitionStart = getFixturePosition(

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" } },