clava 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # clava
 
+## 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

@@ -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