clava 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # clava
 
+## 0.5.0
+
+### Computed default variants
+
+**BREAKING** if you're using `setDefaultVariants` in [`cv`](https://clava.style/docs/reference/cv) `refine` callbacks.
+
+The `setDefaultVariants` function has been removed from `refine`. Define dependent defaults directly in `defaultVariants` by passing a function for the variant key. The function receives the current `defaultValue` for that key and the resolved `variants` snapshot.
+
+Computed default variants run before `refine`, so `refine` callbacks now read computed default values during their first pass. If a variant value itself is a function, return that function from a computed default variant instead of passing it directly as a static default.
+
+Before:
+
+```ts
+const button = cv({
+  variants: {
+    size: { sm: "sm", lg: "lg" },
+    intent: { neutral: "neutral", brand: "brand" },
+  },
+  refine: ({ variants, setDefaultVariants }) => {
+    if (variants.size === "lg") {
+      setDefaultVariants({ intent: "neutral" });
+    }
+  },
+});
+```
+
+After:
+
+```ts
+const button = cv({
+  variants: {
+    size: { sm: "sm", lg: "lg" },
+    intent: { neutral: "neutral", brand: "brand" },
+  },
+  defaultVariants: {
+    intent: ({ defaultValue, variants }) =>
+      variants.size === "lg" ? "neutral" : defaultValue,
+  },
+});
+```
+
+## 0.4.2
+
+- Improved [`refine`](https://clava.style/docs/reference/refine) iteration warnings to show the latest changing variant values with a shorter component creation stack.
+- Fixed [`setDefaultVariants`](https://clava.style/docs/reference/refine#setdefaultvariants) calls with stable values to avoid extra [`refine`](https://clava.style/docs/reference/refine) passes.
+
 ## 0.4.1
 
 ### Improved refine iteration warning with debugging context

package/README.md

@@ -316,7 +316,9 @@ You can extend any component mode, including `baseButton.jsx`, `baseButton.html`
 
 ## Refine
 
-Use `refine` for compound conditions, dependent defaults, and final class/style adjustments. It receives the resolved variant values for the component and can return class/style output.
+Use computed `defaultVariants` for dependent defaults. A function entry receives the current default value for that key plus the resolved variants snapshot, and returns the next default value.
+
+Use `refine` for final variant overrides and class/style adjustments. It receives the resolved variant values for the component and can return class/style output.
 
 ```ts
 const toolbarButton = cv({
@@ -328,21 +330,15 @@ const toolbarButton = cv({
     },
     loading: "toolbar-button-loading",
   },
-  refine: ({
-    variants,
-    setVariants,
-    setDefaultVariants,
-    addClass,
-    addStyle,
-  }) => {
+  defaultVariants: {
+    intent: ({ defaultValue, variants }) =>
+      variants.size === "lg" ? "neutral" : defaultValue,
+  },
+  refine: ({ variants, setVariants, addClass, addStyle }) => {
     if (variants.loading) {
       setVariants({ pressed: false });
     }
 
-    if (variants.size === "lg") {
-      setDefaultVariants({ intent: "neutral" });
-    }
-
     if (variants.pressed && variants.intent === "brand") {
       addClass("toolbar-button-brand-pressed");
       addStyle({ transform: "translateY(1px)" });
@@ -353,9 +349,24 @@ const toolbarButton = cv({
 });
 ```
 
-`setVariants()` overrides explicit props. `setDefaultVariants()` overrides static `defaultVariants` and inherited defaults, but it does not override a prop the user explicitly passed unless that prop value is `undefined`. `addClass()` and `addStyle()` append output without changing resolved variant values. `getVariants()` includes values changed by `setVariants()` and `setDefaultVariants()`.
+Computed `defaultVariants` do not override a prop the user explicitly passed unless that prop value is `undefined`. Return `defaultValue` to preserve the inherited or static default value. Return `undefined` to clear the default value. If a variant's value is a function, return that function from a computed default:
+
+```ts
+const transform = (value: string) => value.toUpperCase();
+
+const input = cv({
+  variants: {
+    transform: (fn: (value: string) => string) => fn("example"),
+  },
+  defaultVariants: {
+    transform: () => transform,
+  },
+});
+```
+
+`setVariants()` overrides explicit props. `addClass()` and `addStyle()` append output without changing resolved variant values. `getVariants()` includes values changed by computed `defaultVariants` and `setVariants()`.
 
-When a `refine` callback changes variants, Clava re-runs the refine chain so later reads see the latest values. Re-runs are capped at 50 iterations, after which Clava stops and logs a warning in development.
+When a computed default or `refine` callback changes variants, Clava re-runs the refine chain so later reads see the latest values. Re-runs are capped at 50 iterations, after which Clava stops and logs a warning in development.
 
 ## Splitting Props
 
@@ -539,7 +550,7 @@ The package also exports `ClassValue`, `StyleValue`, `StyleClassProps`, `StyleCl
 
 `component.style(props?)` returns only the resolved style value for that component mode.
 
-`component.getVariants(props?)` returns resolved variant values after static defaults, inherited defaults, and `refine` updates.
+`component.getVariants(props?)` returns resolved variant values after static defaults, inherited defaults, computed defaults, and `refine` updates.
 
 `component.propKeys` lists style props plus variant props for that component mode.
 

package/dist/index.d.ts

@@ -76,7 +76,15 @@ type StringToBoolean<T> = T extends "true" | "false" ? boolean : T;
 type VariantValue = ClassValue | StyleClassValue;
 type NonNullKeys<T> = { [K in keyof T]: T[K] extends null ? never : K }[keyof T];
 type ExtractVariantValue<T> = T extends null ? never : T extends ((value: infer V) => any) ? V : T extends readonly unknown[] ? boolean : T extends Record<string, any> ? StringToBoolean<NonNullKeys<T>> : T extends ClassValue ? boolean : never;
-type VariantValues<V> = { [K in keyof V]?: ExtractVariantValue<V[K]> };
+type VariantValues<V> = { [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>;
+type DefaultVariants<V> = { [K in keyof V]?: DefaultVariantValue<V, K> | undefined };
 type StyleValue = CSS.Properties & {
   [key: `--${string}`]: string;
 };
@@ -87,7 +95,6 @@ interface StyleClassValue {
 interface RefineContext<V> {
   variants: VariantValues<V>;
   setVariants: (variants: VariantValues<V>) => void;
-  setDefaultVariants: (variants: VariantValues<V>) => void;
   addClass: (className: ClassValue) => void;
   addStyle: (style: StyleValue) => void;
 }
@@ -106,7 +113,7 @@ interface CVConfig<V extends Variants = {}, E extends AnyComponent[] = []> {
   class?: ClassValue;
   style?: StyleValue;
   variants?: ExtendableVariants<V, E>;
-  defaultVariants?: VariantValues<MergeVariants<V, E>>;
+  defaultVariants?: DefaultVariants<MergeVariants<V, E>>;
   refine?: Refine<MergeVariants<V, E>>;
 }
 interface CreateParams {