@lynstack/recipe 1.8.0 → 1.9.0

package/dist/index.d.ts

@@ -7,16 +7,17 @@ type Simplify<Type> = { [Key in keyof Type]: Type[Key]; };
 type OptionName<Options> = `${Extract<keyof Options, string | number>}`;
 type BooleanName = "true" | "false";
 type NumberOption<Options> = Extract<keyof Options, number>;
-type BooleanOption<Name extends string> = [Extract<Name, BooleanName>] extends [never] ? never : BooleanName | boolean;
+type BooleanOption<Name extends string> = [Extract<Name, BooleanName>] extends [never] ? never : "true" | "false" | boolean;
 type BooleanVariantName<Variants> = { [Name in keyof Variants]: [OptionName<Variants[Name]>] extends [never] ? never : [OptionName<Variants[Name]>] extends [BooleanName] ? Name : never; }[keyof Variants];
 /**
  * The values accepted for one variant: the names of its options, as
  * strings or, for numeric names, as numbers, plus `true`, `false`, `"true"`,
  * and `"false"` when it declares an option named `"true"` or `"false"`.
+ * Editors and errors show them by name, such as `"sm" | "md"`.
  *
  * @typeParam Options - The options of the variant, keyed by option name.
  */
-type VariantOption<Options> = OptionName<Options> | NumberOption<Options> | BooleanOption<OptionName<Options>>;
+type VariantOption<Options> = [Options] extends [unknown] ? OptionName<Options> | NumberOption<Options> | BooleanOption<OptionName<Options>> : never;
 /**
  * The variants a selection names. A variant with a default may be omitted,
  * and so may a boolean variant, whose only options are `"true"` and
@@ -146,6 +147,8 @@ interface RecipeKind<Value, Accumulator, Result> {
    */
   readonly cache?: boolean | undefined;
 }
+//#endregion
+//#region src/unknown-slots.d.ts
 /**
  * Rejects the slots of each option's values that `Slot` does not name,
  * unless the option's slot names are not known at compile time. A library
@@ -165,12 +168,201 @@ interface RecipeKind<Value, Accumulator, Result> {
  * ```
  */
 type NoUnknownSlots<Variants, Slot extends string> = NoUnknownComposedSlots<Variants, Slot, never>;
+/**
+ * The type that {@link NoUnknownSlots} gives a key of an option that is not
+ * one of the slots `Slot`. No value is assignable to it, so the error names
+ * both the key and the slots, as `UnknownSlot<"lable", "label" | "root">`.
+ *
+ * @typeParam Name - The key that names no slot.
+ * @typeParam Slot - The names of the slots.
+ */
+interface UnknownSlot<Name, Slot extends string> {
+  readonly "~unknownSlot": Name;
+  readonly "~slots": Slot;
+}
 /**
  * Rejects the slots of the variants' options that are neither `Slot` nor
- * `InheritedSlot`. A recipe's own slots are excluded first, so that they
- * are accepted even when the inherited slots are generic.
+ * `InheritedSlot`. The recipe's own slots are checked before the inherited
+ * ones, so that they are accepted even when the inherited slots are
+ * generic.
+ */
+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 [Unknown in Exclude<Exclude<keyof Variants[Name][Option], Slot>, InheritedSlot>]?: UnknownSlot<Unknown, Slot | InheritedSlot>; }; }; };
+//#endregion
+//#region src/slot-recipe-kind.d.ts
+/**
+ * Values for some of a slot recipe's slots, keyed by slot name.
+ *
+ * @typeParam Slot - The names of the slots.
+ * @typeParam Value - The value of a slot.
+ */
+type SlotValues<Slot extends string, Value> = { readonly [Name in Slot]?: Value | undefined; };
+/**
+ * The variants of a {@link KindSlotRecipeConfig}: for each variant name,
+ * the values of each slot for each of its options.
+ *
+ * @typeParam Value - The value of a slot.
+ */
+type KindSlotVariants<Value> = KindVariants<SlotValues<string, Value>>;
+/**
+ * Values added to some slots when several variants have particular options
+ * at the same time.
+ *
+ * @typeParam Variants - The variant definitions of the slot recipe.
+ * @typeParam Slot - The names of the slots.
+ * @typeParam Value - The value of a slot.
+ */
+interface KindSlotCompoundVariant<Variants, Slot extends string, Value> {
+  /**
+   * The options that must all be selected for
+   * {@link KindSlotCompoundVariant.value} to apply.
+   */
+  readonly variants: KindCompoundCondition<Variants>;
+  /** The value added to each slot when the condition matches. */
+  readonly value: SlotValues<Slot, Value>;
+}
+/**
+ * The configuration of a slot recipe made from a {@link RecipeKind}.
+ *
+ * @typeParam Slot - The names of the slots.
+ * @typeParam Value - The value of a slot.
+ * @typeParam Variants - The variant definitions, keyed by variant name.
+ * @typeParam DefaultedName - The names of the variants that have a default.
+ */
+interface KindSlotRecipeConfig<Slot extends string, Value, Variants extends KindSlotVariants<Value>, DefaultedName extends keyof ComposedVariants<Composed, Variants>, Composed extends readonly ComposableKindSlotRecipe<Value>[] = readonly []> {
+  /**
+   * Slot recipes whose config the recipe adds to its own, in order, as if
+   * it were written in one config: their slots and bases first, the values
+   * of each of their options before its own, and their compound variants
+   * first. A slot recipe composed several times counts once.
+   */
+  readonly composes?: Composed | undefined;
+  /**
+   * The names of the slots, in the order of the recipe's result, after
+   * those of the slot recipes it composes. A name of a property that every
+   * object has, such as `toString`, is not supported.
+   */
+  readonly slots: readonly Slot[];
+  /** The value of each slot that the values of every selection are added to. */
+  readonly base?: SlotValues<NoInfer<Slot> | InheritedSlot<Composed>, Value> | undefined;
+  /** For each variant name, the values of each slot for each of its options. */
+  readonly variants: Variants & SlotVariantsCheck<Variants, NoInfer<Slot>, InheritedSlot<Composed>, Value>;
+  /**
+   * Values added to some slots when several variants have particular
+   * options at the same time, applied in order after the values of the
+   * variants' options.
+   */
+  readonly compoundVariants?: readonly KindSlotCompoundVariant<NoInfer<ComposedVariants<Composed, Variants>>, NoInfer<Slot> | InheritedSlot<Composed>, Value>[] | undefined;
+  /** The option each variant uses when the recipe is called without it. */
+  readonly defaultVariants?: WrittenKindDefaults<ComposedVariants<Composed, Variants>, DefaultedName> | undefined;
+  /** Whether the recipe caches its results. Defaults to the kind's `cache`. */
+  readonly cache?: boolean | undefined;
+}
+/**
+ * Creates slot recipes of one kind, the function that
+ * {@link createSlotRecipeKind} returns.
+ *
+ * @typeParam Value - The value of a slot.
+ * @typeParam Result - What a recipe of this kind returns for each slot.
+ * @param config - The slot recipes it composes, and the slots, base values,
+ *   variants, compound variants, and default variants of the slot recipe,
+ *   and whether it caches its results.
+ * @returns The slot recipe.
+ */
+type CreateKindSlotRecipe<Value, Result> = <const Slot extends string, const Variants extends KindSlotVariants<Value>, const DefaultedName extends keyof ComposedVariants<Composed, Variants> = never, const Composed extends readonly ComposableKindSlotRecipe<Value>[] = readonly []>(config: KindSlotRecipeConfig<Slot, Value, Variants, DefaultedName, Composed>) => ComposedKindRecipe<ComposedVariants<Composed, Variants>, DefaultedName | InheritedDefaultedName<Composed, Variants>, Value, Readonly<Record<Slot | Exclude<Composed[number]["~composition"], undefined>["slots"][number], Result>>, readonly (Slot | Exclude<Composed[number]["~composition"], undefined>["slots"][number])[]>;
+/**
+ * Creates a kind of slot recipe from how it turns the values of each slot
+ * into that slot's result, and returns the function that creates slot
+ * recipes of that kind. A slot recipe maps a selection of variants to the
+ * result of each of several slots, such as the class names or the styles of
+ * the elements of a component, as `sva` of `@lynstack/class-recipe` does.
+ *
+ * @remarks
+ * A slot recipe reduces the values of each slot as a recipe of the same
+ * kind from {@link createRecipeKind} would: `kind.initial` returns the
+ * accumulator for the slot's base value, `kind.reduce` adds the slot's
+ * value of each variant's selected option, in the order of `variants`, and
+ * of each matching compound variant, in the order of `compoundVariants`,
+ * and `kind.finish` turns the accumulator into the slot's result. A slot
+ * without values gets the result of its accumulator for an `undefined`
+ * base, so every slot is in the result.
+ *
+ * The result is a frozen object of each slot's result, keyed by slot name
+ * in the order of `slots`. With the cache, a slot recipe builds it once for
+ * each declared selection and returns the same object for the same
+ * variants. The `cache` of a slot recipe's config overrides the kind's.
+ * Variants, boolean variants, undeclared options, the `TypeError` for a
+ * config with the wrong shape, the warning about undeclared names, and the
+ * `variantKeys`, `variantOptions`, and `defaultVariants` properties are as
+ * in {@link createRecipeKind}. It also
+ * warns about a value for a slot that no config lists in `slots`, which is
+ * ignored.
+ *
+ * A slot recipe composes the slot recipes listed in `composes` as a recipe
+ * composes recipes, and has the slots of each, theirs first. With
+ * `kind.combine`, the values of each slot are combined as a recipe's are.
+ *
+ * @typeParam Value - The value of a slot, inferred from the `value`
+ *   parameter of `kind.reduce` or the `base` parameter of `kind.initial`.
+ * @typeParam Accumulator - What the values of a slot are reduced to,
+ *   inferred from `kind.initial`.
+ * @typeParam Result - What a slot recipe returns for each slot, inferred
+ *   from `kind.finish`, or the accumulator without it.
+ * @param kind - How a slot recipe turns the values of each slot into its
+ *   result, and whether it caches its results. The same kind can create
+ *   recipes with {@link createRecipeKind}.
+ * @returns The function that creates slot recipes of this kind.
+ *
+ * @example
+ * ```ts
+ * type Style = Readonly<Record<string, string | number>>;
+ *
+ * const styleKind = {
+ *   initial: (base?: Style): Record<string, string | number> => ({ ...base }),
+ *   reduce: (style: Record<string, string | number>, value: Style) =>
+ *     Object.assign(style, value),
+ *   finish: (style: Record<string, string | number>): Style =>
+ *     Object.freeze(style),
+ * };
+ *
+ * const slotStyleRecipe = createSlotRecipeKind(styleKind);
+ *
+ * const card = slotStyleRecipe({
+ *   slots: ["root", "title"],
+ *   base: { root: { padding: 16 }, title: { fontSize: 18 } },
+ *   variants: {
+ *     tone: {
+ *       light: { root: { backgroundColor: "white" } },
+ *       dark: { root: { backgroundColor: "black" }, title: { color: "white" } },
+ *     },
+ *   },
+ *   compoundVariants: [
+ *     { variants: { tone: "dark" }, value: { title: { fontWeight: 600 } } },
+ *   ],
+ *   defaultVariants: { tone: "light" },
+ * });
+ *
+ * card();
+ * // => { root: { padding: 16, backgroundColor: "white" }, title: { fontSize: 18 } }
+ *
+ * card({ tone: "dark" });
+ * // => {
+ * //   root: { padding: 16, backgroundColor: "black" },
+ * //   title: { fontSize: 18, color: "white", fontWeight: 600 },
+ * // }
+ *
+ * card.variantOptions; // => { tone: ["light", "dark"] }
+ * card.defaultVariants; // => { tone: "light" }
+ *
+ * const dialog = slotStyleRecipe({
+ *   composes: [card],
+ *   slots: ["footer"],
+ *   variants: { tone: { dark: { footer: { borderColor: "white" } } } },
+ * });
+ *
+ * dialog({ tone: "dark" }).footer; // => { borderColor: "white" }
+ * ```
  */
-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>>>; }; };
+declare function createSlotRecipeKind<Value, Accumulator, Result = Accumulator>(kind: RecipeKind<Value, Accumulator, Result>): CreateKindSlotRecipe<Value, Result>;
 //#endregion
 //#region src/kind-selection.d.ts
 /**
@@ -193,6 +385,21 @@ type KindSelection<Variants, DefaultedName extends keyof Variants> = string exte
 type KindCompoundCondition<Variants> = string extends keyof Variants ? AnySelection : CompoundCondition<Variants>;
 /** The default variants of a recipe, or any for unknown variant names. */
 type KindDefaultVariants<Variants, DefaultedName extends keyof Variants> = string extends keyof Variants ? AnySelection : DefaultVariants<Variants, DefaultedName>;
+/**
+ * The type of `defaultVariants`: the defaults as written, checked. While an
+ * editor completes them, TypeScript has not yet inferred their names and
+ * takes `never`, which would allow no name, so the type then takes an
+ * optional default for each variant.
+ */
+type WrittenKindDefaults<Variants, DefaultedName extends keyof Variants> = [DefaultedName] extends [never] ? { readonly [Name in keyof Variants]?: VariantOption<NoInfer<Variants>[Name]>; } : KindDefaultVariants<Variants, DefaultedName>;
+/**
+ * The check of the variants of a slot recipe: it rejects the slots that are
+ * neither `Slot` nor `InheritedSlot`, and lists every slot in each option,
+ * so that an editor completes their names and values. It leaves out a slot
+ * named after a property that every object has, such as `toString`: an
+ * option that does not give it would still have it, with another type.
+ */
+type SlotVariantsCheck<Variants, Slot extends string, InheritedSlot extends string, Value> = NoUnknownComposedSlots<Variants, Slot, InheritedSlot> & { readonly [Name in keyof Variants]: { readonly [Option in keyof Variants[Name]]: string extends keyof Variants[Name][Option] ? unknown : SlotValues<Exclude<Slot | InheritedSlot, keyof typeof Object.prototype>, Value>; }; };
 //#endregion
 //#region src/composition.d.ts
 /**
@@ -258,9 +465,13 @@ type ComposedDefaultedName<Composed extends readonly unknown[], DefaultedName> =
 /**
  * The names of the variants that the recipes of `Composed` give a default,
  * among the variants of a recipe that composes them with its own
- * `Variants`. Kept apart from the recipe's own defaulted names, so that a
- * recipe that composes nothing has exactly those, even when they are
- * generic.
+ * `Variants`. A library adds them to the recipe's own `DefaultedName`,
+ * rather than passing that to {@link ComposedDefaultedName}, so that a
+ * function generic over a config can return the recipe, and a recipe that
+ * composes nothing has exactly its own defaulted names.
+ *
+ * @typeParam Composed - The types of the recipes composed.
+ * @typeParam Variants - The variant definitions of the recipe's own config.
  */
 type InheritedDefaultedName<Composed extends readonly unknown[], Variants> = Extract<ComposedPart<Composed, "defaultedName">, keyof ComposedVariants<Composed, Variants>>;
 /**
@@ -272,9 +483,12 @@ type InheritedDefaultedName<Composed extends readonly unknown[], Variants> = Ext
  */
 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.
+ * The slots of the slot recipes of `Composed`. Unlike
+ * {@link ComposedSlot}, TypeScript relates a config to them while
+ * `Composed` is generic, so a library types the slots of a config's `base`
+ * and compound variants as `Slot | InheritedSlot<Composed>`.
+ *
+ * @typeParam Composed - The types of the slot recipes composed.
  */
 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;
@@ -356,7 +570,7 @@ interface KindRecipeConfig<Value, Variants extends KindVariants<Value>, Defaulte
    */
   readonly compoundVariants?: readonly KindCompoundVariant<NoInfer<ComposedVariants<Composed, Variants>>, Value>[] | undefined;
   /** The option each variant uses when the recipe is called without it. */
-  readonly defaultVariants?: KindDefaultVariants<ComposedVariants<Composed, Variants>, DefaultedName> | undefined;
+  readonly defaultVariants?: WrittenKindDefaults<ComposedVariants<Composed, Variants>, DefaultedName> | undefined;
   /** Whether the recipe caches its results. Defaults to the kind's `cache`. */
   readonly cache?: boolean | undefined;
 }
@@ -425,10 +639,13 @@ type CreateKindRecipe<Value, Result> = <const Variants extends KindVariants<Valu
  * each, and `defaultVariants` the option each uses when a selection leaves
  * it out, so that a library can list every selection of a recipe.
  *
- * Creating a recipe warns once, with `console.warn`, about a default or a
+ * Creating a recipe from a config with the wrong shape, such as one without
+ * `variants`, throws a `TypeError` that names what is wrong. Creating a
+ * recipe also warns once, with `console.warn`, about a default or a
  * compound variant's condition that names a variant or an option that no
- * config of the recipe declares. Such a default is ignored, and such a
- * condition never matches.
+ * config of the recipe declares. Such a default is ignored. A condition on
+ * such a variant never matches, and such an option in a condition's list
+ * of options is ignored.
  *
  * With the cache, a recipe builds the result of each declared selection
  * once, and calling it again with the same variants returns the same
@@ -505,180 +722,6 @@ 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
-/**
- * Values for some of a slot recipe's slots, keyed by slot name.
- *
- * @typeParam Slot - The names of the slots.
- * @typeParam Value - The value of a slot.
- */
-type SlotValues<Slot extends string, Value> = { readonly [Name in Slot]?: Value | undefined; };
-/**
- * The variants of a {@link KindSlotRecipeConfig}: for each variant name,
- * the values of each slot for each of its options.
- *
- * @typeParam Value - The value of a slot.
- */
-type KindSlotVariants<Value> = KindVariants<SlotValues<string, Value>>;
-/**
- * Values added to some slots when several variants have particular options
- * at the same time.
- *
- * @typeParam Variants - The variant definitions of the slot recipe.
- * @typeParam Slot - The names of the slots.
- * @typeParam Value - The value of a slot.
- */
-interface KindSlotCompoundVariant<Variants, Slot extends string, Value> {
-  /**
-   * The options that must all be selected for
-   * {@link KindSlotCompoundVariant.value} to apply.
-   */
-  readonly variants: KindCompoundCondition<Variants>;
-  /** The value added to each slot when the condition matches. */
-  readonly value: SlotValues<Slot, Value>;
-}
-/**
- * The configuration of a slot recipe made from a {@link RecipeKind}.
- *
- * @typeParam Slot - The names of the slots.
- * @typeParam Value - The value of a slot.
- * @typeParam Variants - The variant definitions, keyed by variant name.
- * @typeParam DefaultedName - The names of the variants that have a default.
- */
-interface KindSlotRecipeConfig<Slot extends string, Value, Variants extends KindSlotVariants<Value>, DefaultedName extends keyof ComposedVariants<Composed, Variants>, Composed extends readonly ComposableKindSlotRecipe<Value>[] = readonly []> {
-  /**
-   * Slot recipes whose config the recipe adds to its own, in order, as if
-   * it were written in one config: their slots and bases first, the values
-   * of each of their options before its own, and their compound variants
-   * first. A slot recipe composed several times counts once.
-   */
-  readonly composes?: Composed | undefined;
-  /**
-   * The names of the slots, in the order of the recipe's result, after
-   * those of the slot recipes it composes.
-   */
-  readonly slots: readonly Slot[];
-  /** The value of each slot that the values of every selection are added to. */
-  readonly base?: SlotValues<NoInfer<Slot> | InheritedSlot<Composed>, Value> | undefined;
-  /** For each variant name, the values of each slot for each of its options. */
-  readonly variants: Variants & NoUnknownComposedSlots<Variants, NoInfer<Slot>, InheritedSlot<Composed>>;
-  /**
-   * Values added to some slots when several variants have particular
-   * options at the same time, applied in order after the values of the
-   * variants' options.
-   */
-  readonly compoundVariants?: readonly KindSlotCompoundVariant<NoInfer<ComposedVariants<Composed, Variants>>, NoInfer<Slot> | InheritedSlot<Composed>, Value>[] | undefined;
-  /** The option each variant uses when the recipe is called without it. */
-  readonly defaultVariants?: KindDefaultVariants<ComposedVariants<Composed, Variants>, DefaultedName> | undefined;
-  /** Whether the recipe caches its results. Defaults to the kind's `cache`. */
-  readonly cache?: boolean | undefined;
-}
-/**
- * Creates slot recipes of one kind, the function that
- * {@link createSlotRecipeKind} returns.
- *
- * @typeParam Value - The value of a slot.
- * @typeParam Result - What a recipe of this kind returns for each slot.
- * @param config - The slot recipes it composes, and the slots, base values,
- *   variants, compound variants, and default variants of the slot recipe,
- *   and whether it caches its results.
- * @returns The slot recipe.
- */
-type CreateKindSlotRecipe<Value, Result> = <const Slot extends string, const Variants extends KindSlotVariants<Value>, const DefaultedName extends keyof ComposedVariants<Composed, Variants> = never, const Composed extends readonly ComposableKindSlotRecipe<Value>[] = readonly []>(config: KindSlotRecipeConfig<Slot, Value, Variants, DefaultedName, Composed>) => ComposedKindRecipe<ComposedVariants<Composed, Variants>, DefaultedName | InheritedDefaultedName<Composed, Variants>, Value, Readonly<Record<Slot | Exclude<Composed[number]["~composition"], undefined>["slots"][number], Result>>, readonly (Slot | Exclude<Composed[number]["~composition"], undefined>["slots"][number])[]>;
-/**
- * Creates a kind of slot recipe from how it turns the values of each slot
- * into that slot's result, and returns the function that creates slot
- * recipes of that kind. A slot recipe maps a selection of variants to the
- * result of each of several slots, such as the class names or the styles of
- * the elements of a component, as `sva` of `@lynstack/class-recipe` does.
- *
- * @remarks
- * A slot recipe reduces the values of each slot as a recipe of the same
- * kind from {@link createRecipeKind} would: `kind.initial` returns the
- * accumulator for the slot's base value, `kind.reduce` adds the slot's
- * value of each variant's selected option, in the order of `variants`, and
- * of each matching compound variant, in the order of `compoundVariants`,
- * and `kind.finish` turns the accumulator into the slot's result. A slot
- * without values gets the result of its accumulator for an `undefined`
- * base, so every slot is in the result.
- *
- * The result is a frozen object of each slot's result, keyed by slot name
- * in the order of `slots`. With the cache, a slot recipe builds it once for
- * each declared selection and returns the same object for the same
- * variants. The `cache` of a slot recipe's config overrides the kind's.
- * Variants, boolean variants, undeclared options, the warning about
- * undeclared names, and the `variantKeys`, `variantOptions`, and
- * `defaultVariants` properties are as in {@link createRecipeKind}. It also
- * warns about a value for a slot that no config lists in `slots`, which is
- * ignored.
- *
- * A slot recipe composes the slot recipes listed in `composes` as a recipe
- * composes recipes, and has the slots of each, theirs first. With
- * `kind.combine`, the values of each slot are combined as a recipe's are.
- *
- * @typeParam Value - The value of a slot, inferred from the `value`
- *   parameter of `kind.reduce` or the `base` parameter of `kind.initial`.
- * @typeParam Accumulator - What the values of a slot are reduced to,
- *   inferred from `kind.initial`.
- * @typeParam Result - What a slot recipe returns for each slot, inferred
- *   from `kind.finish`, or the accumulator without it.
- * @param kind - How a slot recipe turns the values of each slot into its
- *   result, and whether it caches its results. The same kind can create
- *   recipes with {@link createRecipeKind}.
- * @returns The function that creates slot recipes of this kind.
- *
- * @example
- * ```ts
- * type Style = Readonly<Record<string, string | number>>;
- *
- * const styleKind = {
- *   initial: (base?: Style): Record<string, string | number> => ({ ...base }),
- *   reduce: (style: Record<string, string | number>, value: Style) =>
- *     Object.assign(style, value),
- *   finish: (style: Record<string, string | number>): Style =>
- *     Object.freeze(style),
- * };
- *
- * const slotStyleRecipe = createSlotRecipeKind(styleKind);
- *
- * const card = slotStyleRecipe({
- *   slots: ["root", "title"],
- *   base: { root: { padding: 16 }, title: { fontSize: 18 } },
- *   variants: {
- *     tone: {
- *       light: { root: { backgroundColor: "white" } },
- *       dark: { root: { backgroundColor: "black" }, title: { color: "white" } },
- *     },
- *   },
- *   compoundVariants: [
- *     { variants: { tone: "dark" }, value: { title: { fontWeight: 600 } } },
- *   ],
- *   defaultVariants: { tone: "light" },
- * });
- *
- * card();
- * // => { root: { padding: 16, backgroundColor: "white" }, title: { fontSize: 18 } }
- *
- * card({ tone: "dark" });
- * // => {
- * //   root: { padding: 16, backgroundColor: "black" },
- * //   title: { fontSize: 18, color: "white", fontWeight: 600 },
- * // }
- *
- * card.variantOptions; // => { tone: ["light", "dark"] }
- * card.defaultVariants; // => { tone: "light" }
- *
- * const dialog = slotStyleRecipe({
- *   composes: [card],
- *   slots: ["footer"],
- *   variants: { tone: { dark: { footer: { borderColor: "white" } } } },
- * });
- *
- * dialog({ tone: "dark" }).footer; // => { borderColor: "white" }
- * ```
- */
-declare function createSlotRecipeKind<Value, Accumulator, Result = Accumulator>(kind: RecipeKind<Value, Accumulator, Result>): CreateKindSlotRecipe<Value, Result>;
-//#endregion
 //#region src/recipe-of.d.ts
 /**
  * The names of the variants with a default in a config of type `Config`:
@@ -706,9 +749,10 @@ interface KindRecipeConfigParts<Value> {
  * `isolatedDeclarations`, which cannot infer the type of a call. A config
  * that lists `composes` is rejected, so that the type cannot leave out the
  * recipes it composes.
- * It applies to a config whose type is known, not in a function generic
- * over the whole config, from which the recipe's creator cannot infer the
- * variants; make such a function generic over the variants instead.
+ *
+ * It needs a config whose type is known. In a function generic over the
+ * whole config, the recipe's creator cannot infer the variants, so make
+ * such a function generic over the variants instead.
  *
  * @typeParam Value - The value of an option, as in `CreateKindRecipe`.
  * @typeParam Result - What a recipe of the kind returns, as in
@@ -761,10 +805,10 @@ interface KindSlotRecipeConfigParts<Value> {
  * on its own, as with `isolatedDeclarations`, which cannot infer the type
  * of a call. A config that lists `composes` is rejected, so that the type
  * cannot leave out the slot recipes it composes.
- * It applies to a config whose type is known, not in a function generic
- * over the whole config, from which the slot recipe's creator cannot
- * infer the variants; make such a function generic over the variants
- * instead.
+ *
+ * It needs a config whose type is known. In a function generic over the
+ * whole config, the slot recipe's creator cannot infer the variants, so
+ * make such a function generic over the variants instead.
  *
  * @typeParam Value - The value of a slot, as in `CreateKindSlotRecipe`.
  * @typeParam Result - What a slot recipe of the kind returns for each
@@ -802,5 +846,5 @@ interface KindSlotRecipeConfigParts<Value> {
  */
 type KindSlotRecipeOf<Value, Result, Config extends KindSlotRecipeConfigParts<Value>, Composed extends readonly ComposableKindSlotRecipe<Value>[] = readonly []> = ComposedKindRecipe<ComposedVariants<Composed, Config["variants"]>, DefaultedNameOf<Config, Composed> | InheritedDefaultedName<Composed, Config["variants"]>, Value, Readonly<Record<Config["slots"][number] | Exclude<Composed[number]["~composition"], undefined>["slots"][number], Result>>, readonly (Config["slots"][number] | Exclude<Composed[number]["~composition"], undefined>["slots"][number])[]>;
 //#endregion
-export { type Composable, type ComposableKindRecipe, type ComposableKindSlotRecipe, type ComposedDefaultedName, type ComposedSlot, type ComposedVariants, type CompoundCondition, type CreateKindRecipe, type CreateKindSlotRecipe, type DefaultVariants, type KindCompoundVariant, type KindRecipe, type KindRecipeConfig, type KindRecipeOf, type KindSelection, type KindSlotCompoundVariant, type KindSlotRecipeConfig, type KindSlotRecipeOf, type KindSlotVariants, type KindVariants, type NoUnknownSlots, type RecipeComposition, type RecipeFunction, type RecipeKind, type SlotValues, type VariantKey, type VariantOption, type VariantSelection, type VariantsOf, createRecipeKind, createSlotRecipeKind };
+export { type Composable, type ComposableKindRecipe, type ComposableKindSlotRecipe, type ComposedDefaultedName, type ComposedSlot, type ComposedVariants, type CompoundCondition, type CreateKindRecipe, type CreateKindSlotRecipe, type DefaultVariants, type InheritedDefaultedName, type InheritedSlot, type KindCompoundVariant, type KindRecipe, type KindRecipeConfig, type KindRecipeOf, type KindSelection, type KindSlotCompoundVariant, type KindSlotRecipeConfig, type KindSlotRecipeOf, type KindSlotVariants, type KindVariants, type NoUnknownSlots, type RecipeComposition, type RecipeFunction, type RecipeKind, type SlotValues, type UnknownSlot, type VariantKey, type VariantOption, type VariantSelection, type VariantsOf, createRecipeKind, createSlotRecipeKind };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,8 +3,9 @@ const noProps = Object.freeze({});
 * Prepares variants for selecting values. A variant that declares an option
 * named `"true"` or `"false"` also declares the other one, with
 * `config.noValue`, and a variant whose only options are those defaults to
-* `"false"`. A compound variant that names an undeclared variant or option,
-* or lists no option for a variant, never matches and is left out.
+* `"false"`. An undeclared option in a compound variant's list is ignored,
+* and a compound variant that names an undeclared variant, or no declared
+* option of a variant, never matches and is left out.
 */
 function compileVariants(config) {
 	const names = Object.keys(config.variants);
@@ -48,7 +49,7 @@ function product(numbers) {
 	return numbers.reduce((result, number) => result * number, 1);
 }
 function withBooleanOptions(valuesByOption, noValue) {
-	if (!Object.keys(valuesByOption).some((option) => isBooleanName$1(option))) return valuesByOption;
+	if (!Object.keys(valuesByOption).some((option) => isBooleanName(option))) return valuesByOption;
 	return {
 		false: noValue,
 		true: noValue,
@@ -69,7 +70,7 @@ function compileCondition(indexByOption, variant, value) {
 	return [variant, toOptionNames(value).map((option) => indexes?.get(option)).filter((index) => index !== void 0)];
 }
 function isBooleanVariant(indexByOption) {
-	return indexByOption !== void 0 && indexByOption.size > 0 && [...indexByOption.keys()].every((option) => isBooleanName$1(option));
+	return indexByOption !== void 0 && indexByOption.size > 0 && [...indexByOption.keys()].every((option) => isBooleanName(option));
 }
 function toOptionName(value) {
 	if (typeof value === "string") return value;
@@ -104,7 +105,7 @@ function defaultVariantsOf(compiled) {
 	});
 	return Object.fromEntries(entries);
 }
-function isBooleanName$1(option) {
+function isBooleanName(option) {
 	return option === "true" || option === "false";
 }
 //#endregion
@@ -410,9 +411,6 @@ function declaredOptionsOf(layers) {
 	}
 	return optionsByName;
 }
-function isBooleanName(option) {
-	return option === "true" || option === "false";
-}
 function unknownDefaults(defaultVariants, declared) {
 	return Object.entries(defaultVariants).flatMap(([name, value]) => {
 		if (value === void 0) return [];
@@ -445,7 +443,8 @@ function unknownSlots(own, slots) {
 * Returns the names in a recipe's own config that none of its layers
 * declares: a variant or option in its defaults or compound variants, and,
 * for a slot recipe, a slot that a value is given to. Such a default or
-* value is left out, and such a compound variant never matches. Each layer
+* value is left out, an undeclared option in a compound variant's list is
+* ignored, and any other such compound variant never matches. Each layer
 * was checked when its own recipe was created, so only `own` is checked.
 */
 function unknownNames(own, layers, isSlotRecipe) {