Add RecipeVariants type to get variants from recipes (#376)

Author: TheMightyPenguin

.changeset/rare-lemons-study.md

@@ -0,0 +1,39 @@
+---
+'@vanilla-extract/recipes': minor
+---
+
+Add `RecipeVariants` type
+
+A utility to make use of the recipe’s type interface. This can be useful when typing functions or component props that need to accept recipe values as part of their interface.
+
+```ts
+// button.css.ts
+import {
+  recipe,
+  RecipeVariants
+} from '@vanilla-extract/recipes';
+
+export const button = recipe({
+  variants: {
+    color: {
+      neutral: { background: 'whitesmoke' },
+      brand: { background: 'blueviolet' },
+      accent: { background: 'slateblue' }
+    },
+    size: {
+      small: { padding: 12 },
+      medium: { padding: 16 },
+      large: { padding: 24 }
+    }
+  }
+});
+
+// Get the type
+export type ButtonVariants = RecipeVariants<typeof button>;
+
+// the above will result in a type equivalent to:
+export type ButtonVariants = {
+  color?: 'neutral' | 'brand' | 'accent';
+  size?: 'small' | 'medium' | 'large';
+};
+```

packages/recipes/src/index.ts

@@ -10,6 +10,8 @@ import type {
   VariantSelection,
 } from './types';
 
+export type { RecipeVariants } from './types';
+
 function mapValues<Input extends Record<string, any>, OutputValue>(
   input: Input,
   fn: (value: Input[keyof Input], key: keyof Input) => OutputValue,

packages/recipes/src/types.ts

@@ -35,3 +35,6 @@ export type PatternOptions<Variants extends VariantGroups> = {
 export type RuntimeFn<Variants extends VariantGroups> = (
   options?: VariantSelection<Variants>,
 ) => string;
+
+export type RecipeVariants<RecipeFn extends RuntimeFn<VariantGroups>> =
+  Parameters<RecipeFn>[0];

site/docs/recipes-api.md

@@ -112,3 +112,39 @@ export const button = recipe({
   }
 });
 ```
+
+## RecipeVariants
+
+A utility to make use of the recipe’s type interface. This can be useful when typing functions or component props that need to accept recipe values as part of their interface.
+
+```ts
+// button.css.ts
+import {
+  recipe,
+  RecipeVariants
+} from '@vanilla-extract/recipes';
+
+export const button = recipe({
+  variants: {
+    color: {
+      neutral: { background: 'whitesmoke' },
+      brand: { background: 'blueviolet' },
+      accent: { background: 'slateblue' }
+    },
+    size: {
+      small: { padding: 12 },
+      medium: { padding: 16 },
+      large: { padding: 24 }
+    }
+  }
+});
+
+// Get the type
+export type ButtonVariants = RecipeVariants<typeof button>;
+
+// the above will result in a type equivalent to:
+export type ButtonVariants = {
+  color?: 'neutral' | 'brand' | 'accent';
+  size?: 'small' | 'medium' | 'large';
+};
+```

tests/recipes/recipes-type-tests.ts

@@ -0,0 +1,45 @@
+/*
+    This file is for validating types, it is not designed to be executed
+*/
+import { recipe, RecipeVariants } from '@vanilla-extract/recipes';
+
+// @ts-expect-error Unused args
+const noop = (...args: Array<any>) => {};
+
+type AssertIsString<S> = S extends string ? true : never;
+
+() => {
+  const textRecipes = recipe({
+    variants: {
+      size: {
+        small: { fontSize: '12px' },
+        medium: { fontSize: '16px' },
+        large: { fontSize: '24px' },
+      },
+    },
+  });
+
+  type TextVariants = RecipeVariants<typeof textRecipes>;
+
+  const invalidVariantValue: TextVariants = {
+    // @ts-expect-error Type '"extraLarge"' is not assignable to type '"small" | "large" | "medium" | undefined'.
+    size: 'extraLarge',
+  };
+
+  const invalidVariantName: TextVariants = {
+    // @ts-expect-error Property 'color' does not exist in type
+    color: 'brand',
+  };
+
+  const validTextVariant: TextVariants = {
+    size: 'large',
+  };
+
+  const recipeStyles = textRecipes({ size: 'small' });
+  const recipeShouldReturnString: AssertIsString<typeof recipeStyles> = true;
+
+  noop(invalidVariantValue);
+  noop(invalidVariantName);
+  noop(validTextVariant);
+  noop(recipeShouldReturnString);
+};