clava 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # clava
 
+## 0.6.0
+
+### Computed default variant parameters
+
+**BREAKING** if you're using computed `defaultVariants` functions in [`cv`](https://clava.style/docs/reference/cv).
+
+Computed `defaultVariants` functions now receive `defaultValue` and `variants` as separate parameters instead of a context object.
+
+Before:
+
+```ts
+const button = cv({
+  variants: {
+    size: { sm: "sm", lg: "lg" },
+    intent: { neutral: "neutral", brand: "brand" },
+  },
+  defaultVariants: {
+    intent: ({ defaultValue, variants }) =>
+      variants.size === "lg" ? "neutral" : defaultValue,
+  },
+});
+```
+
+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,
+  },
+});
+```
+
+### Other updates
+
+- Documented Clava's public TypeScript helper declarations with inline examples.
+
+## 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.
@@ -70,7 +153,7 @@ Before:
 ```ts
 const button = cv({
   variants: { size: { sm: "sm", lg: "lg" } },
-  computed: ({ variants, addClass }) => {
+  computed({ variants, addClass }) {
     if (variants.size === "lg") {
       addClass("is-large");
     }
@@ -83,7 +166,7 @@ After:
 ```ts
 const button = cv({
   variants: { size: { sm: "sm", lg: "lg" } },
-  refine: ({ variants, addClass }) => {
+  refine({ variants, addClass }) {
     if (variants.size === "lg") {
       addClass("is-large");
     }

package/README.md

@@ -24,6 +24,7 @@ import type { Variant, VariantProps } from "clava";
 - [Solid](#solid)
 - [`create()` And `cx()`](#create-and-cx)
 - [Type Helpers](#type-helpers)
+- [Comparison](#comparison)
 - [API Summary](#api-summary)
 
 ## Install
@@ -230,17 +231,19 @@ Variant values can be class values, arrays, `{ class, style }` objects, or [func
 
 ## 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.
+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. Method syntax works well for multi-line callbacks; compact one-line callbacks can stay as arrow-function property values.
 
 ```ts
 const grid = cv({
   class: "grid",
   variants: {
-    columns: (value: number) => ({
-      class: `grid-cols-${value}`,
-      style: { "--grid-columns": `${value}` },
-    }),
-    color: (value: string | null) => {
+    columns(value: number) {
+      return {
+        class: `grid-cols-${value}`,
+        style: { "--grid-columns": `${value}` },
+      };
+    },
+    color(value: string | null) {
       return value ? `text-${value}` : "text-current";
     },
   },
@@ -316,7 +319,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 as the first parameter and the resolved variants snapshot as the second parameter, then 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 +333,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 +352,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
 
@@ -373,17 +387,18 @@ const button = cv({
       lg: "button-lg",
     },
   },
-}).jsx;
+});
 
-type ButtonProps = ComponentProps<"button"> & VariantProps<typeof button>;
+interface ButtonProps
+  extends ComponentProps<"button">, VariantProps<typeof button> {}
 
 function Button(props: ButtonProps) {
   const [variantProps, buttonProps] = splitProps(props, button);
-  return <button {...buttonProps} {...button(variantProps)} />;
+  return <button {...buttonProps} {...button.jsx(variantProps)} />;
 }
 ```
 
-The first component source claims variant props plus styling props (`class`, `className`, and `style`, depending on the mode). Later component sources receive only their variant props. Array sources receive exactly the listed keys and do not claim styling props.
+The first component source claims variant props plus the styling props exposed by that component's `propKeys`. The base component claims `class`, `className`, and `style`; mode-specific components claim their own styling props. Later component sources receive only their variant props. Array sources receive exactly the listed keys and do not claim styling props.
 
 ```ts
 const [buttonProps, fieldProps, rest] = splitProps(props, button, field);
@@ -420,14 +435,14 @@ const button = cv({
       md: "button-md",
     },
   },
-}).jsx;
+});
 
 interface ButtonProps
   extends ComponentProps<"button">, VariantProps<typeof button> {}
 
 function Button(props: ButtonProps) {
   const [variantProps, buttonProps] = splitProps(props, button);
-  return <button {...buttonProps} {...button(variantProps)} />;
+  return <button {...buttonProps} {...button.jsx(variantProps)} />;
 }
 ```
 
@@ -448,13 +463,14 @@ const button = cv({
       md: "button-md",
     },
   },
-}).htmlObj;
+});
 
-type ButtonProps = ComponentProps<"button"> & VariantProps<typeof button>;
+interface ButtonProps
+  extends ComponentProps<"button">, VariantProps<typeof button> {}
 
 function Button(props: ButtonProps) {
   const [variantProps, buttonProps] = splitProps(props, button);
-  return <button {...buttonProps} {...button(variantProps)} />;
+  return <button {...buttonProps} {...button.htmlObj(variantProps)} />;
 }
 ```
 
@@ -493,7 +509,8 @@ Use `VariantProps<typeof component>` to add a Clava component's variant props to
 import type { ComponentProps } from "react";
 import type { VariantProps } from "clava";
 
-type ButtonProps = ComponentProps<"button"> & VariantProps<typeof button>;
+interface ButtonProps
+  extends ComponentProps<"button">, VariantProps<typeof button> {}
 ```
 
 Use `Variant<typeof component, "key">` to constrain a new variant map to the same values as another component's variant.
@@ -523,6 +540,36 @@ const icon = cv({
 
 The package also exports `ClassValue`, `StyleValue`, `StyleClassProps`, `StyleClassValue`, `JSXProps`, `HTMLProps`, `HTMLObjProps`, `CVComponent`, and `CVConfig`.
 
+## Comparison
+
+This table compares Clava with the packages used by the repository's alternative benchmark: `class-variance-authority@0.7.1`, `cva@1.0.0-beta.4`, `tailwind-variants/lite@3.2.2`, and `tailwind-variants@3.2.2`.
+
+| Feature                                              | Clava          | CVA v0             | CVA v1 beta        | TV Lite            | TV                 |
+| ---------------------------------------------------- | -------------- | ------------------ | ------------------ | ------------------ | ------------------ |
+| Typed variants and default variants                  | Yes            | Yes                | Yes                | Yes                | Yes                |
+| Boolean shorthand variants                           | Yes            | No                 | No                 | No                 | No                 |
+| Component extension or composition                   | `extend`       | No helper          | `compose()`        | `extend`           | `extend`           |
+| Cross-variant conditions                             | `refine()`     | `compoundVariants` | `compoundVariants` | `compoundVariants` | `compoundVariants` |
+| Function variant values                              | Yes            | No                 | No                 | No                 | No                 |
+| Computed default variants                            | Yes            | No                 | No                 | No                 | No                 |
+| Class and style prop output                          | Yes            | Classes only       | Classes only       | Classes only       | Classes only       |
+| JSX, HTML string, and hyphenated-object output modes | Yes            | No                 | No                 | No                 | No                 |
+| Built-in prop splitting for framework props          | `splitProps()` | No                 | No                 | No                 | No                 |
+| Dedicated slots API                                  | No             | No                 | No                 | Yes                | Yes                |
+| Built-in Tailwind conflict merging                   | No             | No                 | No                 | No                 | Yes                |
+
+The `pnpm perf-alternatives` benchmark resolves a composed Tailwind-style button with inherited variants, defaults, and cross-variant conditions. On Node v24.14.1, Vitest reported these results, where higher ops/sec is better:
+
+| Package                          |   Ops/sec | Relative to Clava |
+| -------------------------------- | --------: | ----------------: |
+| `clava@0.5.0`                    | 1,040,314 |             1.00x |
+| `class-variance-authority@0.7.1` |   426,132 |      2.44x slower |
+| `tailwind-variants/lite@3.2.2`   |   369,732 |      2.81x slower |
+| `tailwind-variants@3.2.2`        |   273,503 |      3.80x slower |
+| `cva@1.0.0-beta.4`               |   211,474 |      4.92x slower |
+
+Benchmark results vary by runtime and hardware, so treat them as a reproducible snapshot of this repository's composed-variant case rather than a universal ranking.
+
 ## API Summary
 
 `cv(config?)` creates a typed Clava component. Supported config keys are `extend`, `class`, `style`, `variants`, `defaultVariants`, and `refine`.
@@ -539,7 +586,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

@@ -2,22 +2,84 @@ import { ClassValue as ClassValue$1 } from "clsx";
 import * as CSS from "csstype";
 
 //#region src/types.d.ts
+/**
+ * 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"],
+ * ];
+ * ```
+ */
 type ClassValue = string | number | boolean | null | undefined | void | ClassValue[];
 type JSXCSSProperties = CSS.Properties<string | number>;
 type HTMLCSSProperties = CSS.PropertiesHyphen<string | number>;
 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();
+ * ```
+ */
 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();
+ * ```
+ */
 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();
+ * ```
+ */
 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();
+ * ```
+ */
 interface StyleClassProps {
   class: string;
   style: StyleValue;
@@ -61,6 +123,25 @@ interface ModalComponent<V, R extends ComponentResult> {
   variantKeys: (keyof V)[];
   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" });
+ * ```
+ */
 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>;
@@ -76,10 +157,42 @@ 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 };
+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>;
+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)",
+ * };
+ * ```
+ */
 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" },
+ * };
+ * ```
+ */
 interface StyleClassValue {
   style?: StyleValue;
   class?: ClassValue;
@@ -87,7 +200,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;
 }
@@ -98,15 +210,93 @@ type NullablePartial<T> = T extends Record<string, any> ? { [K in keyof T]?: T[K
 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
+/**
+ * Extracts the variant props inferred for a Clava component. Use it to add a
+ * component's variant props to framework component props.
+ *
+ * @example
+ * ```ts
+ * import { type VariantProps, cv } from "clava";
+ * import type { ComponentProps } from "react";
+ *
+ * const button = cv({
+ *   variants: {
+ *     size: { sm: "button-sm", lg: "button-lg" },
+ *     disabled: { true: "button-disabled", false: "" },
+ *   },
+ * });
+ *
+ * interface ButtonProps
+ *   extends ComponentProps<"button">,
+ *     VariantProps<typeof button> {}
+ *
+ * const props: ButtonProps = {
+ *   size: "lg",
+ *   disabled: true,
+ * };
+ * ```
+ */
 type VariantProps<T extends Pick<AnyComponent, "getVariants">> = ReturnType<T["getVariants"]>;
 type VariantKey<T> = T extends boolean ? "true" | "false" : Extract<T, string>;
+/**
+ * Constrains a variant map to the same value keys as a variant on another
+ * component. Boolean variants are represented with `"true"` and `"false"`
+ * object keys.
+ *
+ * @example
+ * ```ts
+ * import { type Variant, cv } from "clava";
+ *
+ * const button = cv({
+ *   variants: {
+ *     size: { sm: "button-sm", lg: "button-lg" },
+ *   },
+ * });
+ *
+ * const icon = cv({
+ *   extend: [button],
+ *   variants: {
+ *     size: {
+ *       sm: "icon-sm",
+ *       lg: "icon-lg",
+ *     } satisfies Variant<typeof button, "size">,
+ *   },
+ * });
+ * ```
+ */
 type Variant<T extends Pick<AnyComponent, "getVariants">, K extends keyof VariantProps<T>> = Record<VariantKey<NonNullable<VariantProps<T>[K]>>, ClassValue | StyleClassValue>;
+/**
+ * The configuration object accepted by `cv()`. It defines base class/style
+ * output, variants, default variants, component extensions, and refinement
+ * logic.
+ *
+ * @example
+ * ```ts
+ * import { type CVConfig, cv } from "clava";
+ *
+ * const config: CVConfig<{
+ *   tone: { info: string; danger: string };
+ * }> = {
+ *   variants: {
+ *     tone: {
+ *       info: "alert-info",
+ *       danger: "alert-danger",
+ *     },
+ *   },
+ *   defaultVariants: {
+ *     tone: "info",
+ *   },
+ * };
+ *
+ * const alert = cv(config);
+ * ```
+ */
 interface CVConfig<V extends Variants = {}, E extends AnyComponent[] = []> {
   extend?: E;
   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 {