fix(recipe): accept its own slots in a function generic over the slot recipe it composes

A function generic over the slot recipe that its slot recipe composes,
such as `withFooter<Base extends ComposableKindSlotRecipe<Style>>(base)`,
could not name the recipe's own slots in `base`, the variants, or the
compound variants: the config typed their keys with ComposedSlot, a
conditional type that TypeScript cannot reduce while Base is generic, so
it rejected every slot.

The config now types the slots of the composed recipes apart, as indexed
access, and checks a variant's slots against the recipe's own slots
first. Slot values are one mapped type, which TypeScript relates an
object to while some of its keys are generic; it is the same type as
before. A recipe that composes nothing, or concrete recipes, is checked
as it was.

Making library recipes composable advised ComposedSlot for the keys of
`base` and of compound variants, which gave a library the same bug. It
now advises the slots written out, as the engine types them.

Where I looked: the slot config of createSlotRecipeKind, sva in
class-recipe, createSlotStyleRecipe and the themed one in native-recipe
(each fixed in its own commit), the plain recipe config (not affected:
it has no slots), and the docs and skills (Making library recipes
composable, fixed here; the skills type no slots of a library). A
compound variant whose condition names the recipe's own variants is
still rejected in such a function; that is not fixed here.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: timphandev

api/consumers/recipe/define.d.ts

@@ -10,4 +10,14 @@ declare function defineSlots<const Slot extends string, const Variants extends K
 declare function defineComposed<const Variants extends KindVariants<Style>, const DefaultedName extends keyof ComposedVariants<Composed, Variants> = never, const Composed extends readonly ComposableKindRecipe<Style>[] = readonly []>(config: KindRecipeConfig<Style, Variants, DefaultedName, Composed>): ReturnType<typeof styleRecipe<Variants, DefaultedName, Composed>>;
 /** Creates a slot recipe that may compose others, as a library's helper does. */
 declare function defineComposedSlots<const Slot extends string, const Variants extends KindSlotVariants<Style>, const DefaultedName extends keyof ComposedVariants<Composed, Variants> = never, const Composed extends readonly ComposableKindSlotRecipe<Style>[] = readonly []>(config: KindSlotRecipeConfig<Slot, Style, Variants, DefaultedName, Composed>): ReturnType<typeof slotStyleRecipe<Slot, Variants, DefaultedName, Composed>>;
-export { define, defineComposed, defineComposedSlots, defineSlots };
+/** Adds a footer to any slot recipe, as a library's own helper does. */
+declare function withFooter<const Base extends ComposableKindSlotRecipe<Style>>(base: Base): ReturnType<typeof slotStyleRecipe<"footer", {
+    readonly dense: {
+        readonly true: {
+            readonly footer: {
+                readonly borderStyle: "dashed";
+            };
+        };
+    };
+}, never, readonly [Base]>>;
+export { define, defineComposed, defineComposedSlots, defineSlots, withFooter };

api/consumers/recipe/index.d.ts

@@ -458,4 +458,92 @@ declare const sheet: ((props?: {
     }, "tone", Readonly<Record<string, string | number>>, readonly ("footer" | "root" | "title")[]> | undefined;
 };
 declare const sheetStyles: Readonly<Record<"root" | "title" | "footer", Style>>;
-export { bigText, bigTextStyle, badge, badgeStyle, card, composable, composableSlots, dialog, dialogOptions, dialogStyles, emphasis, emphasisKeys, emphasisStyle, field, fieldStyles, knownSlots, sizes, cardKeys, cardStyles, recipe, sheet, sheetStyles, slotStyleRecipe, style, styleRecipe, text, textDefaults, textKey, textKeys, textOptions, variants, };
+declare const footedCard: ((props?: {
+    readonly dense?: import("@lynstack/recipe").VariantOption<{
+        readonly true: {
+            readonly footer: {
+                readonly borderStyle: "dashed";
+            };
+        };
+    }> | undefined;
+    readonly tone?: import("@lynstack/recipe").VariantOption<{
+        readonly dark: {
+            readonly root: {
+                readonly backgroundColor: "black";
+            };
+            readonly title: {
+                readonly color: "white";
+            };
+        };
+        readonly light: {
+            readonly root: {
+                readonly backgroundColor: "white";
+            };
+        };
+    }> | undefined;
+} | undefined) => Readonly<Record<"footer" | "root" | "title", Readonly<Record<string, string | number>>>>) & {
+    readonly variantKeys: readonly ("dense" | "tone")[];
+    readonly variantOptions: {
+        readonly dense: readonly ("false" | "true")[];
+        readonly tone: readonly import("@lynstack/recipe").VariantOption<{
+            readonly dark: {
+                readonly root: {
+                    readonly backgroundColor: "black";
+                };
+                readonly title: {
+                    readonly color: "white";
+                };
+            };
+            readonly light: {
+                readonly root: {
+                    readonly backgroundColor: "white";
+                };
+            };
+        }>[];
+    };
+    readonly defaultVariants: {
+        readonly dense: "false" | "true";
+        readonly tone: import("@lynstack/recipe").VariantOption<{
+            readonly dark: {
+                readonly root: {
+                    readonly backgroundColor: "black";
+                };
+                readonly title: {
+                    readonly color: "white";
+                };
+            };
+            readonly light: {
+                readonly root: {
+                    readonly backgroundColor: "white";
+                };
+            };
+        }>;
+    };
+} & {
+    readonly "~composition"?: import("@lynstack/recipe").RecipeComposition<{
+        readonly dense: {
+            readonly true: {
+                readonly footer: {
+                    readonly borderStyle: "dashed";
+                };
+            };
+        };
+        readonly tone: {
+            readonly dark: {
+                readonly root: {
+                    readonly backgroundColor: "black";
+                };
+                readonly title: {
+                    readonly color: "white";
+                };
+            };
+            readonly light: {
+                readonly root: {
+                    readonly backgroundColor: "white";
+                };
+            };
+        };
+    }, "tone", Readonly<Record<string, string | number>>, readonly ("footer" | "root" | "title")[]> | undefined;
+};
+declare const footedCardStyles: Readonly<Record<"root" | "title" | "footer", Style>>;
+export { bigText, bigTextStyle, badge, badgeStyle, card, composable, composableSlots, dialog, dialogOptions, dialogStyles, emphasis, emphasisKeys, footedCard, footedCardStyles, emphasisStyle, field, fieldStyles, knownSlots, sizes, cardKeys, cardStyles, recipe, sheet, sheetStyles, slotStyleRecipe, style, styleRecipe, text, textDefaults, textKey, textKeys, textOptions, variants, };

api/recipe.d.ts

@@ -23,7 +23,8 @@ interface RecipeKind<Value, Accumulator, Result> {
   readonly finish?: ((accumulator: Accumulator) => Result) | undefined;
   readonly cache?: boolean | undefined;
 }
-type NoUnknownSlots<Variants, Slot extends string> = { readonly [Name in keyof Variants]: { readonly [Option in keyof Variants[Name]]: string extends keyof Variants[Name][Option] ? unknown : Readonly<Partial<Record<Exclude<keyof Variants[Name][Option], Slot>, never>>>; }; };
+type NoUnknownSlots<Variants, Slot extends string> = NoUnknownComposedSlots<Variants, Slot, never>;
+type NoUnknownComposedSlots<Variants, Slot extends string, InheritedSlot extends string> = { readonly [Name in keyof Variants]: { readonly [Option in keyof Variants[Name]]: string extends keyof Variants[Name][Option] ? unknown : Readonly<Partial<Record<Exclude<Exclude<keyof Variants[Name][Option], Slot>, InheritedSlot>, never>>>; }; };
 //#endregion
 //#region src/kind-selection.d.ts
 type AnySelection = Readonly<Record<string, unknown>>;
@@ -53,6 +54,7 @@ type MergeVariants<Union> = { readonly [Name in KeyOfEach<Union>]: MergeEach<Val
 type ComposedDefaultedName<Composed extends readonly unknown[], DefaultedName> = DefaultedName | ComposedPart<Composed, "defaultedName">;
 type InheritedDefaultedName<Composed extends readonly unknown[], Variants> = Extract<ComposedPart<Composed, "defaultedName">, keyof ComposedVariants<Composed, Variants>>;
 type ComposedSlot<Composed extends readonly unknown[], Slot extends string> = Slot | SlotOf<ComposedPart<Composed, "slots">>;
+type InheritedSlot<Composed extends readonly ComposableKindSlotRecipe<unknown>[]> = NonNullable<Composed[number]["~composition"]>["slots"][number];
 type SlotOf<Slots> = Slots extends readonly (infer Slot extends string)[] ? Slot : never;
 type ComposableKindRecipe<Value> = Composable<RecipeComposition<object, PropertyKey, Value, undefined>>;
 type ComposableKindSlotRecipe<Value> = Composable<RecipeComposition<object, PropertyKey, Value, readonly string[]>>;
@@ -84,7 +86,7 @@ type CreateKindRecipe<Value, Result> = <const Variants extends KindVariants<Valu
 declare function createRecipeKind<Value, Accumulator, Result = Accumulator>(kind: RecipeKind<Value, Accumulator, Result>): CreateKindRecipe<Value, Result>;
 //#endregion
 //#region src/slot-recipe-kind.d.ts
-type SlotValues<Slot extends string, Value> = Readonly<Partial<Record<Slot, Value | undefined>>>;
+type SlotValues<Slot extends string, Value> = { readonly [Name in Slot]?: Value | undefined; };
 type KindSlotVariants<Value> = KindVariants<SlotValues<string, Value>>;
 interface KindSlotCompoundVariant<Variants, Slot extends string, Value> {
   readonly variants: KindCompoundCondition<Variants>;
@@ -93,9 +95,9 @@ interface KindSlotCompoundVariant<Variants, Slot extends string, Value> {
 interface KindSlotRecipeConfig<Slot extends string, Value, Variants extends KindSlotVariants<Value>, DefaultedName extends keyof ComposedVariants<Composed, Variants>, Composed extends readonly ComposableKindSlotRecipe<Value>[] = readonly []> {
   readonly composes?: Composed | undefined;
   readonly slots: readonly Slot[];
-  readonly base?: SlotValues<NoInfer<ComposedSlot<Composed, Slot>>, Value> | undefined;
-  readonly variants: Variants & NoUnknownSlots<Variants, NoInfer<ComposedSlot<Composed, Slot>>>;
-  readonly compoundVariants?: readonly KindSlotCompoundVariant<NoInfer<ComposedVariants<Composed, Variants>>, NoInfer<ComposedSlot<Composed, Slot>>, Value>[] | undefined;
+  readonly base?: SlotValues<NoInfer<Slot> | InheritedSlot<Composed>, Value> | undefined;
+  readonly variants: Variants & NoUnknownComposedSlots<Variants, NoInfer<Slot>, InheritedSlot<Composed>>;
+  readonly compoundVariants?: readonly KindSlotCompoundVariant<NoInfer<ComposedVariants<Composed, Variants>>, NoInfer<Slot> | InheritedSlot<Composed>, Value>[] | undefined;
   readonly defaultVariants?: KindDefaultVariants<ComposedVariants<Composed, Variants>, DefaultedName> | undefined;
   readonly cache?: boolean | undefined;
 }

consumers/recipe/define.ts

@@ -76,4 +76,27 @@ function defineComposedSlots<
   return slotStyleRecipe(config);
 }
 
-export { define, defineComposed, defineComposedSlots, defineSlots };
+/** Adds a footer to any slot recipe, as a library's own helper does. */
+function withFooter<const Base extends ComposableKindSlotRecipe<Style>>(
+  base: Base,
+): ReturnType<
+  typeof slotStyleRecipe<
+    "footer",
+    {
+      readonly dense: {
+        readonly true: { readonly footer: { readonly borderStyle: "dashed" } };
+      };
+    },
+    never,
+    readonly [Base]
+  >
+> {
+  return slotStyleRecipe({
+    base: { footer: { borderStyle: "solid" } },
+    composes: [base],
+    slots: ["footer"],
+    variants: { dense: { true: { footer: { borderStyle: "dashed" } } } },
+  });
+}
+
+export { define, defineComposed, defineComposedSlots, defineSlots, withFooter };

consumers/recipe/index.ts

@@ -17,6 +17,7 @@ import {
   defineComposed,
   defineComposedSlots,
   defineSlots,
+  withFooter,
 } from "./define.js";
 
 type Style = Readonly<Record<string, string | number>>;
@@ -125,6 +126,10 @@ const sheetStyles: Readonly<Record<"root" | "title" | "footer", Style>> = sheet(
   { tone: "dark" },
 );
 
+const footedCard = withFooter(card);
+const footedCardStyles: Readonly<Record<"root" | "title" | "footer", Style>> =
+  footedCard({ dense: true });
+
 export {
   bigText,
   bigTextStyle,
@@ -138,6 +143,8 @@ export {
   dialogStyles,
   emphasis,
   emphasisKeys,
+  footedCard,
+  footedCardStyles,
   emphasisStyle,
   field,
   fieldStyles,

docs/src/content/docs/recipe/composable-libraries.mdx

@@ -85,10 +85,13 @@ A library of slot recipes does the same with the slot recipe types:
 
 - `ComposableKindSlotRecipe<Style>` instead of `ComposableKindRecipe`, as
   the type of `composes`.
-- `ComposedSlot<Composed, Slot>` for the slot names, which adds the slots
-  of the slot recipes it composes to those of `slots`. Use it for the
-  keys of `base` and of compound variants.
-- The same slots written out for the keys of the result and in its
+- The slots of `slots` and those of the slot recipes it composes,
+  written out, for the keys of `base` and of compound variants, as
+  `SlotValues<NoInfer<Slot> | NonNullable<Composed[number]["~composition"]>["slots"][number], Style>`.
+  Not `ComposedSlot<Composed, Slot>`, a conditional type that TypeScript
+  cannot reduce while `Composed` is generic: a user's function generic
+  over the recipe it composes could then name none of its own slots.
+- The same slots for the keys of the result and in its
   `RecipeComposition`, whose last type parameter is the list of its
   slots:
   `Slot | Exclude<Composed[number]["~composition"], undefined>["slots"][number]`.

packages/recipe/.oxlintrc.json

@@ -21,5 +21,14 @@
         ]
       }
     ]
-  }
+  },
+  "overrides": [
+    {
+      // TypeScript relates an object to one mapped type over slots that
+      // are generic, as in a function generic over the slot recipe that a
+      // recipe composes, but not to a Record nested in Partial and Readonly.
+      "files": ["src/slot-recipe-kind.ts"],
+      "rules": { "typescript/consistent-indexed-object-style": "off" }
+    }
+  ]
 }

packages/recipe/CHANGELOG.md

@@ -6,6 +6,11 @@ tagged `recipe@<version>`.
 
 ## Unreleased
 
+- A slot recipe's config types the slots of the slot recipes it composes
+  apart from its own, so that a function generic over the slot recipe it
+  composes can name its own slots, and declarations print the slots of
+  `base` and of compound variants by name. Making library recipes
+  composable advises the same for a library's types.
 - Creating a recipe or a slot recipe warns, once, with `console.warn`,
   about a default or a compound variant that names a variant or an option
   that no config of the recipe declares, and, in a slot recipe, about a

packages/recipe/src/compose-slots.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, expectTypeOf, it } from "vitest";
 
+import type { ComposableKindSlotRecipe } from "./composition.js";
 import type { VariantsOf } from "./types.js";
 import { createRecipeKind } from "./recipe-kind.js";
 import { createSlotRecipeKind } from "./slot-recipe-kind.js";
@@ -108,4 +109,66 @@ describe("a slot recipe that composes slot recipes", () => {
 
     expect(Object.keys(labeled())).toStrictEqual(["root", "label"]);
   });
+
+  it("accepts its own slots in a function generic over the slot recipe it composes", () => {
+    const footed = withFooter(field);
+
+    expect(footed({ dense: true })).toStrictEqual({
+      root: ["field", "field-sm"],
+      label: ["field-label"],
+      footer: ["footer", "footer-dense"],
+    });
+    expectTypeOf<VariantsOf<typeof footed>>().toEqualTypeOf<{
+      readonly size?: "sm" | "md" | undefined;
+      readonly invalid?: boolean | "true" | "false" | undefined;
+      readonly dense?: boolean | "true" | "false" | undefined;
+    }>();
+  });
+
+  it("rejects a slot that it does not declare in a function generic over the slot recipe it composes", () => {
+    expect(Object.keys(withIcon(field)())).toStrictEqual([
+      "root",
+      "label",
+      "footer",
+    ]);
+  });
 });
+
+/** Adds a footer to any slot recipe, as a library's own helper does. */
+function withFooter<const Base extends ComposableKindSlotRecipe<string>>(
+  base: Base,
+): ReturnType<
+  typeof slotListRecipe<
+    "footer",
+    { readonly dense: { readonly true: { readonly footer: "footer-dense" } } },
+    never,
+    readonly [Base]
+  >
+> {
+  return slotListRecipe({
+    composes: [base],
+    slots: ["footer"],
+    base: { footer: "footer" },
+    variants: { dense: { true: { footer: "footer-dense" } } },
+  });
+}
+
+/** Adds a footer, and a value for a slot that no recipe declares. */
+function withIcon<const Base extends ComposableKindSlotRecipe<string>>(
+  base: Base,
+): ReturnType<
+  typeof slotListRecipe<
+    "footer",
+    { readonly dense: { readonly true: { readonly footer: "footer-dense" } } },
+    never,
+    readonly [Base]
+  >
+> {
+  return slotListRecipe({
+    composes: [base],
+    slots: ["footer"],
+    // @ts-expect-error: icon is not a slot of the recipe.
+    base: { icon: "icon" },
+    variants: { dense: { true: { footer: "footer-dense" } } },
+  });
+}

packages/recipe/src/composition.ts

@@ -114,6 +114,15 @@ type InheritedDefaultedName<
 type ComposedSlot<Composed extends readonly unknown[], Slot extends string> =
   Slot | SlotOf<ComposedPart<Composed, "slots">>;
 
+/**
+ * The slots of the slot recipes of `Composed`, as indexed access rather
+ * than a conditional type, so that TypeScript relates a config to them
+ * while `Composed` is generic.
+ */
+type InheritedSlot<
+  Composed extends readonly ComposableKindSlotRecipe<unknown>[],
+> = NonNullable<Composed[number]["~composition"]>["slots"][number];
+
 type SlotOf<Slots> = Slots extends readonly (infer Slot extends string)[]
   ? Slot
   : never;
@@ -164,5 +173,6 @@ export type {
   ComposedSlot,
   ComposedVariants,
   InheritedDefaultedName,
+  InheritedSlot,
   RecipeComposition,
 };