Expose recipe's class names (#1104)

Author: aspirisen

.changeset/brave-snakes-yawn.md

@@ -0,0 +1,5 @@
+---
+'@vanilla-extract/recipes': minor
+---
+
+Expose recipe's class names to allow their selection

.changeset/weak-rabbits-design.md

@@ -0,0 +1,5 @@
+---
+'@vanilla-extract/recipes': minor
+---
+
+Always create a base class name for a recipe

packages/recipes/src/createRuntimeFn.ts

@@ -1,9 +1,11 @@
 import type {
   PatternResult,
+  RecipeClassNames,
   RuntimeFn,
   VariantGroups,
   VariantSelection,
 } from './types';
+import { mapValues } from './utils';
 
 const shouldApplyCompound = <Variants extends VariantGroups>(
   compoundCheck: VariantSelection<Variants>,
@@ -64,5 +66,17 @@ export const createRuntimeFn = <Variants extends VariantGroups>(
 
   runtimeFn.variants = () => Object.keys(config.variantClassNames);
 
+  runtimeFn.classNames = {
+    get base() {
+      return config.defaultClassName.split(' ')[0];
+    },
+
+    get variants() {
+      return mapValues(config.variantClassNames, (classNames) =>
+        mapValues(classNames, (className) => className.split(' ')[0]),
+      ) as RecipeClassNames<Variants>['variants'];
+    },
+  };
+
   return runtimeFn;
 };

packages/recipes/src/index.ts

@@ -9,22 +9,10 @@ import type {
   VariantGroups,
   VariantSelection,
 } from './types';
+import { mapValues } from './utils';
 
 export type { RecipeVariants, RuntimeFn } from './types';
 
-function mapValues<Input extends Record<string, any>, OutputValue>(
-  input: Input,
-  fn: (value: Input[keyof Input], key: keyof Input) => OutputValue,
-): Record<keyof Input, OutputValue> {
-  const result: any = {};
-
-  for (const key in input) {
-    result[key] = fn(input[key], key);
-  }
-
-  return result;
-}
-
 export function recipe<Variants extends VariantGroups>(
   options: PatternOptions<Variants>,
   debugId?: string,
@@ -33,11 +21,17 @@ export function recipe<Variants extends VariantGroups>(
     variants = {},
     defaultVariants = {},
     compoundVariants = [],
-    base = '',
+    base,
   } = options;
 
-  const defaultClassName =
-    typeof base === 'string' ? base : style(base, debugId);
+  let defaultClassName;
+
+  if (!base || typeof base === 'string') {
+    const baseClassName = style({});
+    defaultClassName = base ? `${baseClassName} ${base}` : baseClassName;
+  } else {
+    defaultClassName = style(base, debugId);
+  }
 
   // @ts-expect-error
   const variantClassNames: PatternResult<Variants>['variantClassNames'] =

packages/recipes/src/types.ts

@@ -11,11 +11,15 @@ export type VariantSelection<Variants extends VariantGroups> = {
   [VariantGroup in keyof Variants]?: BooleanMap<keyof Variants[VariantGroup]>;
 };
 
+export type VariantsClassNames<Variants extends VariantGroups> = {
+  [P in keyof Variants]: {
+    [PP in keyof Variants[P]]: string;
+  };
+};
+
 export type PatternResult<Variants extends VariantGroups> = {
   defaultClassName: string;
-  variantClassNames: {
-    [P in keyof Variants]: { [P in keyof Variants[keyof Variants]]: string };
-  };
+  variantClassNames: VariantsClassNames<Variants>;
   defaultVariants: VariantSelection<Variants>;
   compoundVariants: Array<[VariantSelection<Variants>, string]>;
 };
@@ -32,9 +36,17 @@ export type PatternOptions<Variants extends VariantGroups> = {
   compoundVariants?: Array<CompoundVariant<Variants>>;
 };
 
+export type RecipeClassNames<Variants extends VariantGroups> = {
+  base: string;
+  variants: VariantsClassNames<Variants>;
+};
+
 export type RuntimeFn<Variants extends VariantGroups> = ((
   options?: VariantSelection<Variants>,
-) => string) & { variants: () => (keyof Variants)[] };
+) => string) & {
+  variants: () => (keyof Variants)[];
+  classNames: RecipeClassNames<Variants>;
+};
 
 export type RecipeVariants<RecipeFn extends RuntimeFn<VariantGroups>> =
   Parameters<RecipeFn>[0];

packages/recipes/src/utils.ts

@@ -0,0 +1,12 @@
+export function mapValues<Input extends Record<string, any>, OutputValue>(
+  input: Input,
+  fn: (value: Input[keyof Input], key: keyof Input) => OutputValue,
+): Record<keyof Input, OutputValue> {
+  const result: any = {};
+
+  for (const key in input) {
+    result[key] = fn(input[key], key);
+  }
+
+  return result;
+}

site/docs/packages/recipes.md

@@ -118,6 +118,28 @@ export const button = recipe({
 });
 ```
 
+The recipes function also exposes an array property `variants` that includes all the variants from your recipe.
+
+```ts
+button.variants();
+// -> ['color', 'size']
+```
+
+## Recipe class name selection
+
+Recipes function exposes internal class names in `classNames` property.
+The property has two predefined props: `base` and `variants`. The `base` prop includes base class name. It is always defined even if you do not have any base styles. The `variants` prop includes class names for each defined variant.
+
+```ts
+// app.css.ts
+console.log(button.classNames.base);
+// -> app_button__129pj250
+console.log(button.classNames.variants.color.neutral);
+// -> app_button_color_neutral__129pj251
+console.log(button.classNames.variants.size.small);
+// -> app_button_size_small__129pj254
+```
+
 ## 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.

tests/compiler/compiler.vitest.test.ts

@@ -300,6 +300,47 @@ describe('compiler', () => {
     `);
   });
 
+  test('recipes class names', async () => {
+    const compiler = compilers.default;
+
+    const cssPath = path.join(
+      __dirname,
+      'fixtures/recipes/recipeClassNames.css.ts',
+    );
+    const output = await compiler.processVanillaFile(cssPath);
+    const { css } = await compiler.getCssForFile(cssPath);
+
+    expect(output.source).toMatchInlineSnapshot(`
+      "import 'fixtures/recipes/recipeClassNames.css.ts.vanilla.css';
+      import { createRuntimeFn as _7a468 } from '@vanilla-extract/recipes/createRuntimeFn';
+      export var recipeWithReferences = _7a468({defaultClassName:'recipeClassNames_recipeWithReferences__129pj258',variantClassNames:{first:{true:'recipeClassNames_recipeWithReferences_first_true__129pj259'}},defaultVariants:{},compoundVariants:[]});"
+    `);
+
+    expect(css).toMatchInlineSnapshot(`
+      ".recipeClassNames_basic_rounded_true__129pj257 {
+        border-radius: 999px;
+      }
+      .recipeClassNames_recipeWithReferences__129pj258 {
+        color: red;
+      }
+      .recipeClassNames__129pj250 .recipeClassNames_recipeWithReferences__129pj258 {
+        color: blue;
+      }
+      .recipeClassNames_basic_spaceWithDefault_large__129pj252 .recipeClassNames_recipeWithReferences__129pj258 {
+        color: yellow;
+      }
+      .recipeClassNames_basic_spaceWithoutDefault_small__129pj253 .recipeClassNames_recipeWithReferences__129pj258 {
+        color: green;
+      }
+      .recipeClassNames_basic_color_red__129pj255 .recipeClassNames_recipeWithReferences_first_true__129pj259 {
+        color: black;
+      }
+      .recipeClassNames_basic_spaceWithDefault_large__129pj252.recipeClassNames_basic_rounded_true__129pj257 .recipeClassNames_recipeWithReferences_first_true__129pj259 {
+        color: white;
+      }"
+    `);
+  });
+
   afterAll(async () => {
     await Promise.allSettled(
       Object.values(compilers).map((compiler) => compiler.close()),

tests/compiler/fixtures/recipes/recipeClassNames.css.ts

@@ -0,0 +1,53 @@
+import { recipe } from '@vanilla-extract/recipes';
+
+const basic = recipe({
+  variants: {
+    spaceWithDefault: {
+      small: {},
+      large: {},
+    },
+    spaceWithoutDefault: {
+      small: {},
+      large: {},
+    },
+    color: {
+      red: {},
+      blue: {},
+    },
+    rounded: {
+      true: { borderRadius: 999 },
+    },
+  },
+});
+
+export const recipeWithReferences = recipe({
+  base: {
+    color: 'red',
+    selectors: {
+      [`.${basic.classNames.base} &`]: {
+        color: 'blue',
+      },
+      [`.${basic.classNames.variants.spaceWithDefault.large} &`]: {
+        color: 'yellow',
+      },
+      [`.${basic.classNames.variants.spaceWithoutDefault.small} &`]: {
+        color: 'green',
+      },
+    },
+  },
+  variants: {
+    first: {
+      true: {
+        selectors: {
+          [`.${basic.classNames.variants.color.red} &`]: {
+            color: 'black',
+          },
+          [`.${basic.classNames.variants.spaceWithDefault.large}.${basic.classNames.variants.rounded.true} &`]:
+            {
+              color: 'white',
+            },
+        },
+      },
+    },
+  },
+});

tests/recipes/recipes.css.ts

@@ -32,3 +32,23 @@ export const basic = recipe({
     },
   ],
 });
+
+export const empty = recipe({});
+
+export const definedStringBase = recipe({
+  base: 'definedStringBase',
+  variants: {
+    variant: {
+      simple: 'simple-one',
+    },
+  },
+});
+
+export const definedStringBaseArray = recipe({
+  base: ['definedStringBaseInArray_1', 'definedStringBaseInArray_2'],
+  variants: {
+    variant: {
+      simple: ['simple-one', 'simple-two'],
+    },
+  },
+});