feat(recipe): add variant-aware step index interpretation to getIngredientQuantities

Author: tmlmt

src/classes/recipe.ts

@@ -245,6 +245,17 @@ export class Recipe {
     );
   }
 
+  /**
+   * Returns whether a step is active (visible) for the given variant.
+   * Steps with no `variants` tag are active in all variants.
+   * Use `"*"` for the default variant.
+   */
+  private isStepActiveForVariant(step: Step, variant: string): boolean {
+    if (!step.variants) return true;
+    if (variant === "*") return step.variants.includes("*");
+    return step.variants.includes(variant);
+  }
+
   /**
    * Creates a new Recipe instance.
    * @param content - The recipe content to parse.
@@ -728,7 +739,7 @@ export class Recipe {
   // Defined as a static type alias for the private method's return type
   /** @internal */
   private collectQuantityGroups(options?: GetIngredientQuantitiesOptions) {
-    const { section, step, choices } = options || {};
+    const { section, step, variant: indexingVariant, choices } = options || {};
 
     // Active variant (undefined or "*" = default)
     const activeVariant = choices?.variant;
@@ -795,13 +806,23 @@ export class Recipe {
       // Track whether this section is optional
       const isOptionalSection = currentSection.optional === true;
 
+      // When a variant is given for step-index interpretation, limit indexing
+      // to the steps active in that variant — matching how step numbers are
+      // assigned during rendering (inactive steps are skipped/unnumbered).
+      const stepsForIndexing =
+        indexingVariant !== undefined
+          ? allSteps.filter((s) =>
+              this.isStepActiveForVariant(s, indexingVariant),
+            )
+          : allSteps;
+
       // Determine steps to process
       const stepsToProcess =
         step === undefined
           ? allSteps
           : typeof step === "number"
-            ? step >= 0 && step < allSteps.length
-              ? [allSteps[step]!]
+            ? step >= 0 && step < stepsForIndexing.length
+              ? [stepsForIndexing[step]!]
               : []
             : allSteps.includes(step)
               ? [step]
@@ -2008,14 +2029,10 @@ export class Recipe {
       for (const alternative of alternatives) {
         // v8 ignore else -- @preserve
         if (alternative.quantity) {
-          const converted = convertAlternativeQuantity(
-            alternative,
-          );
+          const converted = convertAlternativeQuantity(alternative);
           alternative.quantity = converted.quantity;
           alternative.unit = converted.unit;
-          (
-            alternative
-          ).scalable = converted.scalable;
+          alternative.scalable = converted.scalable;
           alternative.equivalents = converted.equivalents;
         }
       }

src/types.ts

@@ -503,6 +503,16 @@ export interface GetIngredientQuantitiesOptions {
    * Can be a Step object or step index (0-based within the section, or global if no section specified).
    */
   step?: Step | number;
+  /**
+   * When `step` is a number, interpret it as a 0-based index into the steps
+   * that are active for this variant (i.e., the steps that would be visible
+   * when rendering with this variant), rather than into all steps in the section.
+   *
+   * Has no effect when `step` is a {@link Step} object or when `step` is `undefined`.
+   *
+   * Use `"*"` to refer to the default variant (steps tagged `[*]` and untagged steps).
+   */
+  variant?: string;
   /**
    * The choices to apply when computing quantities.
    * If not provided, uses primary alternatives (index 0 for all).

test/recipe_variants.test.ts

@@ -782,4 +782,120 @@ Serve on a #plate{}.
       });
     });
   });
+
+  // ============================================================================
+  // variant option in getIngredientQuantities — step-number interpretation
+  // ============================================================================
+
+  describe("variant step-index interpretation", () => {
+    // recipeWithStepVariants steps (all-steps order):
+    //   0: "Preheat..."            — no variant (active everywhere)
+    //   1: "[vegan] Use flax eggs" — vegan only
+    //   2: "[*] Crack eggs"        — default only
+    //   3: "Mix flour and sugar"   — no variant (active everywhere)
+    //
+    // Visible in "vegan" variant: [0, 1, 3]  → indices 0, 1, 2
+    // Visible in "*"    variant:  [0, 2, 3]  → indices 0, 1, 2
+
+    it("without variant option, step index uses raw all-steps order (backward compat)", () => {
+      const recipe = new Recipe(recipeWithStepVariants);
+      // Step index 3 in all-steps = "Mix flour and sugar"
+      const ingredients = recipe.getIngredientQuantities({ step: 3 });
+      const names = ingredients
+        .filter((i) => i.usedAsPrimary)
+        .map((i) => i.name);
+      expect(names).toContain("flour");
+      expect(names).toContain("sugar");
+    });
+
+    it("with variant='vegan', step 1 maps to the [vegan] step", () => {
+      const recipe = new Recipe(recipeWithStepVariants);
+      const ingredients = recipe.getIngredientQuantities({
+        step: 1,
+        variant: "vegan",
+        choices: { variant: "vegan" },
+      });
+      const names = ingredients
+        .filter((i) => i.usedAsPrimary)
+        .map((i) => i.name);
+      expect(names).toContain("flax eggs");
+      expect(names).not.toContain("eggs");
+    });
+
+    it("with variant='*', step 1 maps to the [*] step", () => {
+      const recipe = new Recipe(recipeWithStepVariants);
+      const ingredients = recipe.getIngredientQuantities({
+        step: 1,
+        variant: "*",
+      });
+      const names = ingredients
+        .filter((i) => i.usedAsPrimary)
+        .map((i) => i.name);
+      expect(names).toContain("eggs");
+      expect(names).not.toContain("flax eggs");
+    });
+
+    it("with variant='vegan', step 2 maps to the last active step (Mix)", () => {
+      const recipe = new Recipe(recipeWithStepVariants);
+      // vegan-active steps: [Preheat(0), UseFlaxEggs(1), Mix(2)]
+      const ingredients = recipe.getIngredientQuantities({
+        step: 2,
+        variant: "vegan",
+        choices: { variant: "vegan" },
+      });
+      const names = ingredients
+        .filter((i) => i.usedAsPrimary)
+        .map((i) => i.name);
+      expect(names).toContain("flour");
+      expect(names).toContain("sugar");
+    });
+
+    it("out-of-bounds step index with variant returns no primary ingredients", () => {
+      const recipe = new Recipe(recipeWithStepVariants);
+      // vegan-active steps: 3 steps (indices 0-2); index 3 is out-of-bounds
+      const ingredients = recipe.getIngredientQuantities({
+        step: 3,
+        variant: "vegan",
+        choices: { variant: "vegan" },
+      });
+      const primaries = ingredients.filter((i) => i.usedAsPrimary);
+      expect(primaries).toHaveLength(0);
+    });
+
+    it("step object reference is unaffected by variant option", () => {
+      const recipe = new Recipe(recipeWithStepVariants);
+      const steps = recipe.sections[0]!.content.filter(
+        (item): item is Step => item.type === "step",
+      );
+      // Pass the [vegan] step object directly — variant option should not change behaviour
+      const ingredients = recipe.getIngredientQuantities({
+        step: steps[1]!,
+        variant: "vegan",
+        choices: { variant: "vegan" },
+      });
+      const names = ingredients
+        .filter((i) => i.usedAsPrimary)
+        .map((i) => i.name);
+      expect(names).toContain("flax eggs");
+    });
+
+    it("works correctly combined with section filter", () => {
+      const recipe = new Recipe(recipeWithSectionAndStepVariants);
+      // Section 0 "[vegan] Plant-based Additions":
+      //   all steps: [paneer step (vegetarian), tofu step (untagged)]
+      //   vegan-active steps: [tofu step] (paneer excluded as it's [vegetarian])
+      // So step index 0 with variant="vegan" → tofu step
+      const ingredients = recipe.getIngredientQuantities({
+        section: 0,
+        step: 0,
+        variant: "vegan",
+        choices: { variant: "vegan" },
+      });
+      const names = ingredients
+        .filter((i) => i.usedAsPrimary)
+        .map((i) => i.name);
+      expect(names).toContain("tofu");
+      expect(names).not.toContain("paneer");
+    });
+  });
 });