clava 0.5.0 → 0.6.0

package/src/index.ts

@@ -69,10 +69,10 @@ type ResolveRefineFn = (
   defaultResolved?: Record<string, unknown>,
 ) => Record<string, unknown>;
 
-type ComputedDefaultVariantFn = (context: {
-  defaultValue: unknown;
-  variants: Readonly<Record<string, unknown>>;
-}) => unknown;
+type ComputedDefaultVariantFn = (
+  defaultValue: unknown,
+  variants: Readonly<Record<string, unknown>>,
+) => unknown;
 
 // Internal metadata stored on components but hidden from public types.
 interface ComponentMeta {
@@ -218,12 +218,64 @@ export type {
   CVComponent,
 };
 
+/**
+ * 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,
+ * };
+ * ```
+ */
 export type VariantProps<T extends Pick<AnyComponent, "getVariants">> =
   ReturnType<T["getVariants"]>;
 
 // Variant props expose booleans, but variant object keys are always strings.
 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">,
+ *   },
+ * });
+ * ```
+ */
 export type Variant<
   T extends Pick<AnyComponent, "getVariants">,
   K extends keyof VariantProps<T>,
@@ -232,6 +284,32 @@ export type Variant<
   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);
+ * ```
+ */
 export interface CVConfig<
   V extends Variants = {},
   E extends AnyComponent[] = [],
@@ -1015,10 +1093,7 @@ export function create({
         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);

package/src/types.ts

@@ -1,5 +1,20 @@
 import type * as CSS from "csstype";
 
+/**
+ * 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"],
+ * ];
+ * ```
+ */
 export type ClassValue =
   | string
   | number
@@ -17,21 +32,68 @@ export type CSSProperties = CSS.Properties;
 
 export 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();
+ * ```
+ */
 export 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();
+ * ```
+ */
 export 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();
+ * ```
+ */
 export 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();
+ * ```
+ */
 export interface StyleClassProps {
   class: string;
   style: StyleValue;
@@ -177,6 +239,25 @@ export interface ModalComponent<V, R extends ComponentResult> {
   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" });
+ * ```
+ */
 export interface CVComponent<
   V extends Variants = {},
   E extends AnyComponent[] = [],
@@ -257,13 +338,9 @@ export 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>,
+  defaultValue: ExtractVariantValue<V[K]> | undefined,
+  variants: Readonly<VariantValues<V>>,
 ) => ExtractVariantValue<V[K]> | undefined;
 
 type NonFunctionVariantValue<T> = Exclude<T, (...args: any[]) => any>;
@@ -280,10 +357,38 @@ export 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)",
+ * };
+ * ```
+ */
 export 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" },
+ * };
+ * ```
+ */
 export interface StyleClassValue {
   style?: StyleValue;
   class?: ClassValue;

package/tests/component-api.test.ts

@@ -137,7 +137,7 @@ for (const config of Object.values(CONFIGS)) {
           },
           defaultVariants: {
             color: () => "red" as const,
-            size: ({ defaultValue, variants }) =>
+            size: (defaultValue, variants) =>
               variants.color === "red" ? "lg" : defaultValue,
           },
         }),
@@ -155,7 +155,7 @@ for (const config of Object.values(CONFIGS)) {
             color: { red: "red", blue: "blue" },
           },
           defaultVariants: {
-            color: ({ defaultValue, variants }) =>
+            color: (defaultValue, variants) =>
               variants.size === "lg" ? "blue" : defaultValue,
           },
         }),
@@ -271,7 +271,7 @@ for (const config of Object.values(CONFIGS)) {
           mode: { on: "on" },
         },
         defaultVariants: {
-          size: ({ defaultValue, variants }) =>
+          size: (defaultValue, variants) =>
             variants.mode === "on" ? "lg" : defaultValue,
         },
         refine: ({ variants, setVariants }) => {
@@ -356,7 +356,7 @@ for (const config of Object.values(CONFIGS)) {
           mode: { on: "on" },
         },
         defaultVariants: {
-          size: ({ defaultValue, variants }) =>
+          size: (defaultValue, variants) =>
             variants.mode === "on" ? "lg" : defaultValue,
         },
         refine: ({ variants, setVariants }) => {
@@ -422,7 +422,7 @@ for (const config of Object.values(CONFIGS)) {
           extend: [base],
           variants: { color: { red: "child-red", blue: "child-blue" } },
           defaultVariants: {
-            color: ({ defaultValue, variants }) =>
+            color: (defaultValue, variants) =>
               variants.color === "red" ? "blue" : defaultValue,
           },
         }),
@@ -440,7 +440,7 @@ for (const config of Object.values(CONFIGS)) {
             done: "",
           },
           defaultVariants: {
-            color: ({ defaultValue, variants }) =>
+            color: (defaultValue, variants) =>
               variants.done ? "blue" : defaultValue,
           },
           refine: ({ variants, setVariants }) => {

package/tests/extend.test.ts

@@ -206,7 +206,7 @@ for (const config of Object.values(CONFIGS)) {
           },
           defaultVariants: {
             size: "lg",
-            color: ({ variants }) => (variants.size === "lg" ? "blue" : "red"),
+            color: (_, variants) => (variants.size === "lg" ? "blue" : "red"),
           },
         }),
       );

package/tests/language-service.test.ts

@@ -80,7 +80,10 @@ function createLanguageServiceHost(
 function createLanguageServiceFixture(
   consumerSource: string,
 ): LanguageServiceFixture {
-  const tempDir = mkdtempSync(join(workspaceDir, ".tmp-language-service-"));
+  const tempRoot = join(workspaceDir, ".tmp");
+  mkdirSync(tempRoot, { recursive: true });
+
+  const tempDir = mkdtempSync(join(tempRoot, "language-service-"));
   tempDirs.push(tempDir);
 
   const fixtureSourceDir = join(tempDir, "src");
@@ -134,6 +137,14 @@ afterEach(() => {
 });
 
 describe("TypeScript language service", () => {
+  test("creates fixtures inside the workspace .tmp directory", () => {
+    const fixture = createLanguageServiceFixture(getVariantFixtureSource());
+    const fixtureDir = dirname(fixture.consumerFile);
+    const fixturePrefix = join(workspaceDir, ".tmp", "language-service-");
+
+    expect(fixtureDir.startsWith(fixturePrefix)).toBe(true);
+  });
+
   test("goes to the local variant definition from a variant prop usage", () => {
     const fixture = createLanguageServiceFixture(getVariantFixtureSource());
     const definitionStart = getFixturePosition(