clava 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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
@@ -18,7 +60,7 @@ const button = cv({
     size: { sm: "sm", lg: "lg" },
     intent: { neutral: "neutral", brand: "brand" },
   },
-  refine: ({ variants, setDefaultVariants }) => {
+  refine({ variants, setDefaultVariants }) {
     if (variants.size === "lg") {
       setDefaultVariants({ intent: "neutral" });
     }
@@ -111,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");
     }
@@ -124,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,7 @@ You can extend any component mode, including `baseButton.jsx`, `baseButton.html`
 
 ## Refine
 
-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 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.
 
@@ -331,10 +334,10 @@ const toolbarButton = cv({
     loading: "toolbar-button-loading",
   },
   defaultVariants: {
-    intent: ({ defaultValue, variants }) =>
+    intent: (defaultValue, variants) =>
       variants.size === "lg" ? "neutral" : defaultValue,
   },
-  refine: ({ variants, setVariants, addClass, addStyle }) => {
+  refine({ variants, setVariants, addClass, addStyle }) {
     if (variants.loading) {
       setVariants({ pressed: false });
     }
@@ -384,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);
@@ -431,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)} />;
 }
 ```
 
@@ -459,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)} />;
 }
 ```
 
@@ -504,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.
@@ -534,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`.

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>;
@@ -77,17 +158,41 @@ 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]> | 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 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;
@@ -105,9 +210,87 @@ 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;

package/dist/index.js

@@ -816,10 +816,7 @@ function create({ transformClass = (className) => className } = {}) {
 				if (protectedVariantKeys?.has(key)) continue;
 				const variantSnapshot = getOwnVariants();
 				const defaultValue = inheritedComputedDefaultKeys.has(key) ? variantSnapshot[key] : defaultResolved[key];
-				const value = computedDefaultFns[i]({
-					defaultValue,
-					variants: variantSnapshot
-				});
+				const value = computedDefaultFns[i](defaultValue, variantSnapshot);
 				if (hasAnyDisabled) {
 					if (disabledVariantKeys.has(key)) continue;
 					const valueKey = getVariantValueKey(value);