feat(recipe)!: make alternative choices variant-aware

BREAKING CHANGE: varianted choice behavior is now strict. For non-default variants, inactive-variant alternatives are no longer considered during auto-selection or quantity resolution.

Author: tmlmt

docs/guide-rendering.md

@@ -338,6 +338,31 @@ Both functions follow the same logic:
 
 When a variant is active, ingredient alternatives can be auto-selected too. See [Applying choices](#applying-choices) for the full explanation and examples.
 
+**Auto-selection by note matching:**
+
+Call [`getEffectiveChoices()`](/api/functions/getEffectiveChoices) to auto-build a `RecipeChoices` that selects alternatives whose `note` matches the variant name:
+
+```typescript
+import { getEffectiveChoices } from "@tmlmt/cooklang-parser";
+
+const choices = getEffectiveChoices(recipe, "vegan");
+const ingredients = recipe.getIngredientQuantities({ choices });
+```
+
+**Filtering available choices by variant:**
+
+To show only the ingredient choices available for a given variant in your UI, use the [`getChoicesForVariant()`](/api/classes/Recipe.html#getchoicesforvariant) method on the recipe. It returns a filtered [`RecipeAlternatives`](/api/interfaces/RecipeAlternatives) containing only alternatives that are linked to the active variant (or untagged, making them available in all variants):
+
+```typescript
+const variant = "vegan"; // or undefined for default
+
+// Get variant-filtered alternatives
+const variantChoices = recipe.getChoicesForVariant(variant);
+
+// variantChoices.ingredientItems contains only alternatives linked to [vegan]
+// variantChoices.ingredientGroups contains only grouped alternatives linked to [vegan]
+```
+
 ## Handling alternative selections
 
 Ingredient alternatives (both [inline](/guide-extensions#inline-alternatives) and [grouped](/guide-extensions#grouped-alternatives)) appear in the step items as an `alternatives` array on [`IngredientItem`](/api/interfaces/IngredientItem).

playground/app/components/recipe/RecipeChoices.vue

@@ -77,25 +77,27 @@ const step = computed(() => {
 });
 
 // --- Compute available choices ---
+const variantFilteredChoices = computed(() => {
+  return props.recipe.getChoicesForVariant(selectedVariant.value);
+});
+
 const hasInlineChoices = computed(
-  () => props.recipe.choices.ingredientItems.size > 0,
+  () => variantFilteredChoices.value.ingredientItems.size > 0,
 );
 const hasGroupedChoices = computed(
-  () => props.recipe.choices.ingredientGroups.size > 0,
-);
-const hasVariants = computed(
-  () => props.recipe.choices.variants.length > 0,
+  () => variantFilteredChoices.value.ingredientGroups.size > 0,
 );
+const hasVariants = computed(() => props.recipe.choices.variants.length > 0);
 const hasAnyChoices = computed(
   () => hasInlineChoices.value || hasGroupedChoices.value,
 );
 
 // Convert Maps to arrays for iteration
 const inlineChoicesArray = computed(() => {
-  return Array.from(props.recipe.choices.ingredientItems.entries());
+  return Array.from(variantFilteredChoices.value.ingredientItems.entries());
 });
 const groupedChoicesArray = computed(() => {
-  return Array.from(props.recipe.choices.ingredientGroups.entries());
+  return Array.from(variantFilteredChoices.value.ingredientGroups.entries());
 });
 
 // --- Variant options ---

src/classes/recipe.ts

@@ -190,6 +190,61 @@ export class Recipe {
     return current;
   }
 
+  /**
+   * Computes variant linkage for parsed items based on section and step tags.
+   * Undefined means no variant restriction.
+   */
+  private getLinkedVariants(
+    sectionVariants?: string[],
+    stepVariants?: string[],
+  ): string[] | undefined {
+    if (!sectionVariants && !stepVariants) {
+      return undefined;
+    }
+    if (!sectionVariants) {
+      return [...stepVariants!];
+    }
+    if (!stepVariants) {
+      return [...sectionVariants];
+    }
+    const stepSet = new Set(stepVariants);
+    const intersection = sectionVariants.filter((v) => stepSet.has(v));
+    return intersection;
+  }
+
+  /**
+   * Checks whether an alternative linked to specific variants is active
+   * for the requested variant.
+   */
+  private isAlternativeLinkedToVariant(
+    alternative: IngredientAlternative,
+    variant?: string,
+  ): boolean {
+    const linked = alternative.linkedVariants;
+    if (!linked || linked.length === 0) {
+      return true;
+    }
+    const isDefaultVariant = variant === undefined || variant === "*";
+    if (isDefaultVariant) {
+      return linked.includes("*");
+    }
+    return linked.includes(variant);
+  }
+
+  /**
+   * Filters grouped choice subgroups based on active variant linkage.
+   */
+  private filterGroupSubgroupsForVariant(
+    subgroups: IngredientAlternative[][],
+    variant?: string,
+  ): IngredientAlternative[][] {
+    return subgroups.filter((subgroup) =>
+      subgroup.every((alternative) =>
+        this.isAlternativeLinkedToVariant(alternative, variant),
+      ),
+    );
+  }
+
   /**
    * Creates a new Recipe instance.
    * @param content - The recipe content to parse.
@@ -292,6 +347,7 @@ export class Recipe {
   private _parseIngredientWithAlternativeRecursive(
     ingredientMatchString: string,
     items: Step["items"],
+    linkedVariants?: string[],
   ): void {
     const alternatives: IngredientAlternative[] = [];
     let testString = ingredientMatchString;
@@ -391,6 +447,7 @@ export class Recipe {
       const alternative: IngredientAlternative = {
         index: idxInList,
         displayName,
+        ...(linkedVariants && { linkedVariants: [...linkedVariants] }),
       };
       // Only add quantity fields and note if they exist
       const note = groups.ingredientNote?.trim();
@@ -448,6 +505,7 @@ export class Recipe {
   private _parseIngredientWithGroupKey(
     ingredientMatchString: string,
     items: Step["items"],
+    linkedVariants?: string[],
   ): void {
     const match = ingredientMatchString.match(ingredientWithGroupKeyRegex);
     // This is a type guard to ensure match and match.groups are defined
@@ -542,6 +600,7 @@ export class Recipe {
     const alternative: IngredientAlternative = {
       index: idxInList,
       displayName,
+      ...(linkedVariants && { linkedVariants: [...linkedVariants] }),
     };
     // Only add quantity fields if it exists
     if (itemQuantity) {
@@ -766,24 +825,31 @@ export class Recipe {
           (item): item is IngredientItem => item.type === "ingredient",
         )) {
           const isGrouped = "group" in item && item.group !== undefined;
-          const groupSubgroups = isGrouped
+          const allGroupSubgroups = isGrouped
             ? this.choices.ingredientGroups.get(item.group!)
             : undefined;
+          const groupSubgroups = allGroupSubgroups
+            ? this.filterGroupSubgroupsForVariant(
+                allGroupSubgroups,
+                activeVariant,
+              )
+            : undefined;
 
           // Determine selection state
           let selectedAltIndex = 0;
           let isSelected: boolean;
           let hasExplicitChoice: boolean;
 
           if (isGrouped) {
+            const availableSubgroups = groupSubgroups!;
             const groupChoice = choices?.ingredientGroups?.get(item.group!);
             hasExplicitChoice = groupChoice !== undefined;
 
             // Variant-aware auto-selection for grouped items: when a named
             // variant is active and no explicit choice, look for subgroups
             // whose alternatives have a note matching the variant name
             if (!hasExplicitChoice && !isDefaultVariant) {
-              const matchingSubgroupIdx = groupSubgroups?.findIndex((sg) =>
+              const matchingSubgroupIdx = availableSubgroups.findIndex((sg) =>
                 sg.some(
                   (alt) =>
                     alt.note &&
@@ -796,25 +862,25 @@ export class Recipe {
                 matchingSubgroupIdx !== undefined &&
                 matchingSubgroupIdx >= 0
               ) {
-                const matchedSubgroup = groupSubgroups![matchingSubgroupIdx]!;
+                const matchedSubgroup =
+                  availableSubgroups[matchingSubgroupIdx]!;
                 isSelected = matchedSubgroup.some(
                   (alt) => alt.itemId === item.id,
                 );
                 hasExplicitChoice = true; // treat as explicit so alternativeRefs are not built
                 selectedAltIndex = 0;
               } else {
-                const targetSubgroupIndex = 0;
-                const selectedSubgroup = groupSubgroups?.[targetSubgroupIndex];
-                isSelected = selectedSubgroup!.some(
+                isSelected = availableSubgroups[0]!.some(
                   (alt) => alt.itemId === item.id,
                 );
               }
             } else {
               const targetSubgroupIndex = groupChoice ?? 0;
-              const selectedSubgroup = groupSubgroups?.[targetSubgroupIndex];
-              isSelected =
-                selectedSubgroup?.some((alt) => alt.itemId === item.id) ??
-                false;
+              const selectedSubgroup = availableSubgroups[targetSubgroupIndex];
+              if (!selectedSubgroup) continue;
+              isSelected = selectedSubgroup.some(
+                (alt) => alt.itemId === item.id,
+              );
             }
           } else {
             const itemChoice = choices?.ingredientItems?.get(item.id);
@@ -859,9 +925,9 @@ export class Recipe {
           }
 
           // Add all alternatives to referenced set (so indices remain valid in result)
-          const allAltsFlat = isGrouped
-            ? groupSubgroups!.flat()
-            : item.alternatives;
+          const allAltsFlat = (
+            isGrouped ? groupSubgroups!.flat() : item.alternatives
+          ).filter((alt): alt is IngredientAlternative => alt !== undefined);
           for (const alt of allAltsFlat) {
             referencedIndices.add(alt.index);
           }
@@ -1025,6 +1091,39 @@ export class Recipe {
     };
   }
 
+  /**
+   * Returns choices available for a given active variant.
+   *
+   * For grouped alternatives, only groups with at least two available
+   * subgroups are returned.
+   */
+  getChoicesForVariant(variant?: string): RecipeAlternatives {
+    const ingredientItems = new Map<string, IngredientAlternative[]>();
+    for (const [itemId, alternatives] of this.choices.ingredientItems) {
+      const isVisible = alternatives.some((alternative) =>
+        this.isAlternativeLinkedToVariant(alternative, variant),
+      );
+      if (isVisible) {
+        ingredientItems.set(itemId, alternatives);
+      }
+    }
+
+    const ingredientGroups = new Map<string, IngredientAlternative[][]>();
+    for (const [groupId, subgroups] of this.choices.ingredientGroups) {
+      const filtered = this.filterGroupSubgroupsForVariant(subgroups, variant);
+      // v8 ignore else -- @preserve: only include groups with at least 2 subgroups (otherwise it's not really a choice)
+      if (filtered.length > 1) {
+        ingredientGroups.set(groupId, filtered);
+      }
+    }
+
+    return {
+      ingredientItems,
+      ingredientGroups,
+      variants: [...this.choices.variants],
+    };
+  }
+
   /**
    * Gets the raw (unprocessed) quantity groups for each ingredient, before
    * any summation or equivalents simplification. This is useful for cross-recipe
@@ -1426,6 +1525,10 @@ export class Recipe {
 
       // Detecting items
       let cursor = 0;
+      const linkedVariants = this.getLinkedVariants(
+        section.variants,
+        stepVariants,
+      );
       for (const match of currentLine.matchAll(tokensRegex)) {
         const idx = match.index;
         /* v8 ignore else -- @preserve */
@@ -1437,11 +1540,15 @@ export class Recipe {
 
         // Ingredient items with potential in-line alternatives
         if (groups.mIngredientName || groups.sIngredientName) {
-          this._parseIngredientWithAlternativeRecursive(match[0], items);
+          this._parseIngredientWithAlternativeRecursive(
+            match[0],
+            items,
+            linkedVariants,
+          );
         }
         // Ingredient items part of a group of alternative ingredients
         else if (groups.gmIngredientName || groups.gsIngredientName) {
-          this._parseIngredientWithGroupKey(match[0], items);
+          this._parseIngredientWithGroupKey(match[0], items, linkedVariants);
         }
         // Cookware items
         else if (groups.mCookwareName || groups.sCookwareName) {

src/classes/shopping_list.ts

@@ -1130,9 +1130,7 @@ export class ShoppingList {
       const indent = "  ".repeat(depth);
       for (const [segment, child] of sorted) {
         const fullPath = `${pathPrefix}/${segment}`;
-        if (child.suffix !== undefined) {
-          lines.push(`${indent}./${fullPath}${child.suffix}`);
-        }
+        lines.push(`${indent}./${fullPath}${child.suffix}`);
         emitDescendantsFlat(child, fullPath, depth);
       }
     };

src/types.ts

@@ -396,6 +396,11 @@ export type IngredientAlternativeBase = {
   index: number;
   /** The alias/name of the ingredient as it should be displayed for this occurrence. */
   displayName: string;
+  /**
+   * Variants this alternative is linked to, based on step/section tags
+   * where it was parsed. If undefined, it is available in all variants.
+   */
+  linkedVariants?: string[];
   /** An optional note for this specific choice (e.g., "for a vegan version"). */
   note?: string;
   /** When {@link Recipe.choices} is populated for alternatives ingredients

src/utils/render_helpers.ts

@@ -433,9 +433,10 @@ export function getEffectiveChoices(
   if (variant === undefined || variant === "*") return choices;
 
   const variantLower = variant.toLowerCase();
+  const variantChoices = recipe.getChoicesForVariant(variant);
 
   // Auto-select inline alternatives by note match
-  for (const [itemId, alternatives] of recipe.choices.ingredientItems) {
+  for (const [itemId, alternatives] of variantChoices.ingredientItems) {
     const matchIdx = alternatives.findIndex(
       (alt) => alt.note && alt.note.toLowerCase().includes(variantLower),
     );
@@ -448,7 +449,7 @@ export function getEffectiveChoices(
   }
 
   // Auto-select grouped alternatives by note match
-  for (const [groupId, subgroups] of recipe.choices.ingredientGroups) {
+  for (const [groupId, subgroups] of variantChoices.ingredientGroups) {
     const matchIdx = subgroups.findIndex((sg) =>
       sg.some(
         (alt) => alt.note && alt.note.toLowerCase().includes(variantLower),