clava 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # clava
 
+## 0.4.1
+
+### Improved refine iteration warning with debugging context
+
+When the [`refine`](https://clava.style/docs/reference/refine) iteration cap is hit, the development warning now lists the variant keys that did not stabilize and includes the stack trace of the [`cv`](https://clava.style/docs/reference/cv) call that defined the component. This makes it easier to find the offending component without searching through the codebase.
+
+```txt
+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.
+Variant(s) that did not stabilize: size.
+Component created at:
+    at toolbarButton (src/components/toolbar.ts:42:18)
+    ...
+```
+
+The frame is captured at component creation but formatted lazily, so component creation stays cheap unless the warning actually fires, and the capture is skipped entirely for components that cannot enter the refine loop. The whole warning is wrapped in a `process.env.NODE_ENV !== "production"` guard, so bundlers that inline that constant strip the warning machinery from production builds.
+
+### Other updates
+
+- Removed refine warning-only code from production bundles when bundlers statically replace `process.env.NODE_ENV`.
+
+## 0.4.0
+
+### Removed `computedVariants` in favor of function values in `variants`
+
+**BREAKING** if you're using the `computedVariants` config option.
+
+Define a function directly inside [`variants`](https://clava.style/docs/reference/cv#variants) — it now acts as a function variant. The function's parameter type defines the prop type and replaces any inherited variant for the same key.
+
+Before:
+
+```ts
+const grid = cv({
+  variants: {
+    color: { red: "text-red", blue: "text-blue" },
+  },
+  computedVariants: {
+    columns: (value: number) => `grid-cols-${value}`,
+  },
+});
+```
+
+After:
+
+```ts
+const grid = cv({
+  variants: {
+    color: { red: "text-red", blue: "text-blue" },
+    columns: (value: number) => `grid-cols-${value}`,
+  },
+});
+```
+
+### Renamed `computed` to `refine`
+
+**BREAKING** if you use the `computed` config field on [`cv`](https://clava.style/docs/reference/cv).
+
+The `computed` field previously collided with `computedVariants`, even though the two have very different semantics: `computedVariants` is a map of pure per-variant transformer functions, while `computed` is a single imperative callback that can mutate variants, set defaults, and emit class/style output across re-runs until variants stabilize. The new name `refine` describes that iterative refinement and removes the collision.
+
+Rename the `computed` field to `refine`. The callback signature and context (`variants`, `setVariants`, `setDefaultVariants`, `addClass`, `addStyle`) are unchanged.
+
+Before:
+
+```ts
+const button = cv({
+  variants: { size: { sm: "sm", lg: "lg" } },
+  computed: ({ variants, addClass }) => {
+    if (variants.size === "lg") {
+      addClass("is-large");
+    }
+  },
+});
+```
+
+After:
+
+```ts
+const button = cv({
+  variants: { size: { sm: "sm", lg: "lg" } },
+  refine: ({ variants, addClass }) => {
+    if (variants.size === "lg") {
+      addClass("is-large");
+    }
+  },
+});
+```
+
 ## 0.3.0
 
 ### Removed `keys`

package/README.md

@@ -16,9 +16,9 @@ import type { Variant, VariantProps } from "clava";
 - [Output Modes](#output-modes)
 - [Classes And Styles](#classes-and-styles)
 - [Variants](#variants)
+- [Function Variants](#function-variants)
 - [Extending Components](#extending-components)
-- [Computed Variants](#computed-variants)
-- [Computed Logic](#computed-logic)
+- [Refine](#refine)
 - [Splitting Props](#splitting-props)
 - [React](#react)
 - [Solid](#solid)
@@ -78,7 +78,7 @@ button({ size: "lg", disabled: true, fluid: true, className: "mt-2" });
 // }
 ```
 
-Variant prop types are inferred from the `variants`, `computedVariants`, `defaultVariants`, and `extend` configuration. Invalid variant keys and values are TypeScript errors and are ignored at runtime.
+Variant prop types are inferred from the `variants`, `defaultVariants`, and `extend` configuration. Invalid variant keys and values are TypeScript errors and are ignored at runtime.
 
 Input props may use `class` or `className` in any output mode. Both are appended to the generated class string.
 
@@ -152,7 +152,7 @@ const card = cv({
 });
 ```
 
-Variant and computed style results must use an explicit `{ style }` wrapper. A raw object like `{ backgroundColor: "red" }` is not a style result by itself.
+Style results from `variants` and `refine` must use an explicit `{ style }` wrapper. A raw object like `{ backgroundColor: "red" }` is not a style result by itself.
 
 ```ts
 const chip = cv({
@@ -226,7 +226,34 @@ item({ active: true, interactive: true }).class;
 // "item-active item-interactive focus-visible:ring"
 ```
 
-Variant values can be class values, arrays, or `{ class, style }` objects. Use `null` in an extending component to disable inherited variants or inherited variant values.
+Variant values can be class values, arrays, `{ class, style }` objects, or [functions](#function-variants). Use `null` in an extending component to disable inherited variants or inherited variant values.
+
+## Function Variants
+
+Add a function as a variant value when the prop should generate class/style output dynamically. The function's parameter type defines the prop type.
+
+```ts
+const grid = cv({
+  class: "grid",
+  variants: {
+    columns: (value: number) => ({
+      class: `grid-cols-${value}`,
+      style: { "--grid-columns": `${value}` },
+    }),
+    color: (value: string | null) => {
+      return value ? `text-${value}` : "text-current";
+    },
+  },
+});
+
+grid({ columns: 3, color: null });
+// {
+//   class: "grid grid-cols-3 text-current",
+//   style: { "--grid-columns": "3" },
+// }
+```
+
+Function variants can return any class value, `{ class, style }`, a default Clava component result, `null`, or `undefined`. A function variant with the same key as an extended variant replaces that inherited variant's prop type and output.
 
 ## Extending Components
 
@@ -287,36 +314,9 @@ const plainButton = cv({
 
 You can extend any component mode, including `baseButton.jsx`, `baseButton.html`, and `baseButton.htmlObj`.
 
-## Computed Variants
-
-Use `computedVariants` when a prop value should generate class/style output dynamically. The function parameter defines the prop type.
-
-```ts
-const grid = cv({
-  class: "grid",
-  computedVariants: {
-    columns: (value: number) => ({
-      class: `grid-cols-${value}`,
-      style: { "--grid-columns": `${value}` },
-    }),
-    color: (value: string | null) => {
-      return value ? `text-${value}` : "text-current";
-    },
-  },
-});
-
-grid({ columns: 3, color: null });
-// {
-//   class: "grid grid-cols-3 text-current",
-//   style: { "--grid-columns": "3" },
-// }
-```
-
-Computed variants can return any class value, `{ class, style }`, a default Clava component result, `null`, or `undefined`. A `computedVariants` entry with the same key as an extended variant replaces that inherited variant's prop type and output.
-
-## Computed Logic
+## Refine
 
-Use `computed` 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 `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.
 
 ```ts
 const toolbarButton = cv({
@@ -328,7 +328,7 @@ const toolbarButton = cv({
     },
     loading: "toolbar-button-loading",
   },
-  computed: ({
+  refine: ({
     variants,
     setVariants,
     setDefaultVariants,
@@ -355,7 +355,7 @@ 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()`.
 
-When a computed callback changes variants, Clava re-runs the computed 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 `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
 
@@ -525,7 +525,7 @@ The package also exports `ClassValue`, `StyleValue`, `StyleClassProps`, `StyleCl
 
 ## API Summary
 
-`cv(config?)` creates a typed Clava component. Supported config keys are `extend`, `class`, `style`, `variants`, `computedVariants`, `defaultVariants`, and `computed`.
+`cv(config?)` creates a typed Clava component. Supported config keys are `extend`, `class`, `style`, `variants`, `defaultVariants`, and `refine`.
 
 `component(props?)` returns `{ class, style }` with normalized camelCase style keys.
 
@@ -539,7 +539,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 computed variant updates.
+`component.getVariants(props?)` returns resolved variant values after static defaults, inherited defaults, and `refine` updates.
 
 `component.propKeys` lists style props plus variant props for that component mode.
 

package/dist/index.d.ts

@@ -30,11 +30,11 @@ type ComponentProps<V = {}> = VariantValues<V> & NullableComponentResult;
 type GetVariants<V> = (variants?: VariantValues<V>) => VariantValues<V>;
 type ComponentPropKey<R extends ComponentResult> = keyof R | (R extends StyleClassProps ? "className" : never);
 type KeySourceArray = readonly string[];
-type KeySourceComponent = {
+interface KeySourceComponent {
   propKeys: readonly string[];
   variantKeys: readonly string[];
   getVariants: () => Record<string, unknown>;
-};
+}
 type KeySource = KeySourceArray | KeySourceComponent;
 type IsComponent<S> = S extends {
   getVariants: () => unknown;
@@ -61,21 +61,17 @@ interface ModalComponent<V, R extends ComponentResult> {
   variantKeys: (keyof V)[];
   propKeys: (keyof V | ComponentPropKey<R>)[];
 }
-interface CVComponent<V extends Variants = {}, CV extends ComputedVariants = {}, E extends AnyComponent[] = [], R extends ComponentResult = StyleClassProps> extends ModalComponent<MergeVariants<V, CV, E>, R> {
-  jsx: ModalComponent<MergeVariants<V, CV, E>, JSXProps>;
-  html: ModalComponent<MergeVariants<V, CV, E>, HTMLProps>;
-  htmlObj: ModalComponent<MergeVariants<V, CV, E>, HTMLObjProps>;
+interface CVComponent<V extends Variants = {}, E extends AnyComponent[] = [], R extends ComponentResult = StyleClassProps> extends ModalComponent<MergeVariants<V, E>, R> {
+  jsx: ModalComponent<MergeVariants<V, E>, JSXProps>;
+  html: ModalComponent<MergeVariants<V, E>, HTMLProps>;
+  htmlObj: ModalComponent<MergeVariants<V, E>, HTMLObjProps>;
 }
-type AnyComponent = CVComponent<any, any, any, any> | ModalComponent<any, any>;
+type AnyComponent = CVComponent<any, any, any> | ModalComponent<any, any>;
 type MergeExtendedVariants<T> = T extends readonly [infer First, ...infer Rest] ? ExtractVariants<First> & MergeExtendedVariants<Rest> : {};
-type MergeExtendedComputedVariants<T> = T extends readonly [infer First, ...infer Rest] ? ExtractComputedVariants<First> & MergeExtendedComputedVariants<Rest> : {};
-type ExtractVariants<T> = T extends CVComponent<infer V, any, infer E, any> ? V & MergeExtendedVariants<E> : {};
-type ExtractComputedVariants<T> = T extends CVComponent<any, infer CV, infer E, any> ? CV & Omit<MergeExtendedComputedVariants<E>, keyof CV> : {};
-type MergeVariantDefinition<Child, Parent> = Child extends Record<string, any> ? Parent extends Record<string, any> ? Omit<Parent, keyof Child> & Child : Child : Child;
+type ExtractVariants<T> = T extends CVComponent<infer V, infer E, any> ? MergeVariantMaps<V, MergeExtendedVariants<E>> : {};
+type MergeVariantDefinition<Child, Parent> = Child extends ((...args: any[]) => any) ? Child : Parent extends ((...args: any[]) => any) ? Child : Child extends Record<string, any> ? Parent extends Record<string, any> ? Omit<Parent, keyof Child> & Child : Child : Child;
 type MergeVariantMaps<Child, Parent> = Omit<Parent, keyof Child> & Child & { [K in keyof Child & keyof Parent]: MergeVariantDefinition<Child[K], Parent[K]> };
-type MergeExtendedAllVariants<E extends AnyComponent[]> = MergeExtendedVariants<E> & MergeExtendedComputedVariants<E>;
-type MergeBaseVariants<V, E extends AnyComponent[]> = MergeVariantMaps<NoInfer<V>, MergeExtendedAllVariants<E>>;
-type MergeVariants<V, CV, E extends AnyComponent[]> = NoInfer<CV> & Omit<MergeBaseVariants<V, E>, keyof CV>;
+type MergeVariants<V, E extends AnyComponent[]> = MergeVariantMaps<NoInfer<V>, MergeExtendedVariants<E>>;
 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];
@@ -88,34 +84,30 @@ interface StyleClassValue {
   style?: StyleValue;
   class?: ClassValue;
 }
-interface ComputedContext<V> {
+interface RefineContext<V> {
   variants: VariantValues<V>;
   setVariants: (variants: VariantValues<V>) => void;
   setDefaultVariants: (variants: VariantValues<V>) => void;
   addClass: (className: ClassValue) => void;
   addStyle: (style: StyleValue) => void;
 }
-type Computed<V> = (context: ComputedContext<V>) => VariantValue;
-type ComputedVariant = (value: any) => VariantValue;
-type ComputedVariants = Record<string, ComputedVariant>;
-type Variant$1 = ClassValue | Record<string, VariantValue>;
+type Refine<V> = (context: RefineContext<V>) => VariantValue;
+type Variant$1 = ClassValue | Record<string, VariantValue> | ((value: any) => VariantValue);
 type Variants = Record<string, Variant$1>;
-type ExtendedVariants<E extends AnyComponent[]> = MergeExtendedVariants<E> & MergeExtendedComputedVariants<E>;
 type NullablePartial<T> = T extends Record<string, any> ? { [K in keyof T]?: T[K] | null } : T | null;
-type ExtendableVariants<V extends Variants, E extends AnyComponent[]> = V & { [K in keyof ExtendedVariants<E>]?: NullablePartial<ExtendedVariants<E>[K]> | Variant$1 };
+type ExtendableVariants<V extends Variants, E extends AnyComponent[]> = V & { [K in keyof MergeExtendedVariants<E>]?: NullablePartial<MergeExtendedVariants<E>[K]> | Variant$1 };
 //#endregion
 //#region src/index.d.ts
 type VariantProps<T extends Pick<AnyComponent, "getVariants">> = ReturnType<T["getVariants"]>;
 type VariantKey<T> = T extends boolean ? "true" | "false" : Extract<T, string>;
 type Variant<T extends Pick<AnyComponent, "getVariants">, K extends keyof VariantProps<T>> = Record<VariantKey<NonNullable<VariantProps<T>[K]>>, ClassValue | StyleClassValue>;
-interface CVConfig<V extends Variants = {}, CV extends ComputedVariants = {}, E extends AnyComponent[] = []> {
+interface CVConfig<V extends Variants = {}, E extends AnyComponent[] = []> {
   extend?: E;
   class?: ClassValue;
   style?: StyleValue;
   variants?: ExtendableVariants<V, E>;
-  computedVariants?: CV;
-  defaultVariants?: VariantValues<MergeVariants<V, CV, E>>;
-  computed?: Computed<MergeVariants<V, CV, E>>;
+  defaultVariants?: VariantValues<MergeVariants<V, E>>;
+  refine?: Refine<MergeVariants<V, E>>;
 }
 interface CreateParams {
   transformClass?: (className: string) => string;
@@ -135,10 +127,10 @@ declare const splitProps: SplitPropsFunction;
 declare function create({
   transformClass
 }?: CreateParams): {
-  cv: <V extends Variants = {}, CV extends ComputedVariants = {}, const E extends AnyComponent[] = []>(config?: CVConfig<V, CV, E>) => CVComponent<V, CV, E>;
+  cv: <V extends Variants = {}, const E extends AnyComponent[] = []>(config?: CVConfig<V, E>) => CVComponent<V, E>;
   cx: (...classes: ClassValue$1[]) => string;
 };
-declare const cv: <V extends Variants = {}, CV extends ComputedVariants = {}, const E extends AnyComponent[] = []>(config?: CVConfig<V, CV, E>) => CVComponent<V, CV, E>, cx: (...classes: ClassValue$1[]) => string;
+declare const cv: <V extends Variants = {}, const E extends AnyComponent[] = []>(config?: CVConfig<V, E>) => CVComponent<V, E>, cx: (...classes: ClassValue$1[]) => string;
 //#endregion
 export { type CVComponent, CVConfig, type ClassValue, type HTMLObjProps, type HTMLProps, type JSXProps, type StyleClassProps, type StyleClassValue, type StyleValue, Variant, VariantProps, create, cv, cx, splitProps };
 //# sourceMappingURL=index.d.ts.map