@tmlmt/cooklang-parser 3.0.0-alpha.16 → 3.0.0-alpha.19

package/dist/index.js

@@ -277,7 +277,7 @@ var nonWordCharStrict = "\\s@#~\\[\\]{(,;:!?|";
 var ingredientWithAlternativeRegex = d().literal("@").startNamedGroup("ingredientModifiers").anyOf("@\\-&?").zeroOrMore().endGroup().optional().startNamedGroup("ingredientRecipeAnchor").literal("./").endGroup().optional().startGroup().startGroup().startNamedGroup("mIngredientName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").endGroup().or().startNamedGroup("sIngredientName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().endGroup().startGroup().literal("{").startNamedGroup("ingredientQuantityModifier").literal("=").exactly(1).endGroup().optional().startNamedGroup("ingredientQuantity").startGroup().notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").notAnyOf("|}").oneOrMore().lazy().endGroup().optional().startGroup().literal("|").notAnyOf("}").oneOrMore().lazy().endGroup().zeroOrMore().endGroup().literal("}").endGroup().optional().startGroup().literal("(").startNamedGroup("ingredientPreparation").notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().startGroup().literal("[").startNamedGroup("ingredientNote").notAnyOf("\\]").oneOrMore().lazy().endGroup().literal("]").endGroup().optional().startNamedGroup("ingredientAlternative").startGroup().literal("|").startGroup().anyOf("@\\-&?").zeroOrMore().endGroup().optional().startGroup().literal("./").endGroup().optional().startGroup().startGroup().startGroup().notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").endGroup().or().startGroup().notAnyOf(nonWordChar).oneOrMore().endGroup().endGroup().startGroup().literal("{").startGroup().literal("=").exactly(1).endGroup().optional().startGroup().notAnyOf("}%").oneOrMore().endGroup().optional().startGroup().literal("%").startGroup().notAnyOf("}").oneOrMore().lazy().endGroup().endGroup().optional().literal("}").endGroup().optional().startGroup().literal("(").startGroup().notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().startGroup().literal("[").startGroup().notAnyOf("\\]").oneOrMore().lazy().endGroup().literal("]").endGroup().optional().endGroup().zeroOrMore().endGroup().toRegExp();
 var inlineIngredientAlternativesRegex = new RegExp("\\|" + ingredientWithAlternativeRegex.source.slice(1));
 var quantityAlternativeRegex = d().startNamedGroup("quantity").notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").startNamedGroup("unit").notAnyOf("|}").oneOrMore().endGroup().endGroup().optional().startGroup().literal("|").startNamedGroup("alternative").startGroup().notAnyOf("}").oneOrMore().endGroup().zeroOrMore().endGroup().endGroup().optional().toRegExp();
-var ingredientWithGroupKeyRegex = d().literal("@|").startNamedGroup("gIngredientGroupKey").notAnyOf(nonWordCharStrict).oneOrMore().endGroup().literal("|").startNamedGroup("gIngredientModifiers").anyOf("@\\-&?").zeroOrMore().endGroup().optional().startNamedGroup("gIngredientRecipeAnchor").literal("./").endGroup().optional().startGroup().startGroup().startNamedGroup("gmIngredientName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").endGroup().or().startNamedGroup("gsIngredientName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().endGroup().startGroup().literal("{").startNamedGroup("gIngredientQuantityModifier").literal("=").exactly(1).endGroup().optional().startNamedGroup("gIngredientQuantity").startGroup().notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").notAnyOf("|}").oneOrMore().lazy().endGroup().optional().startGroup().literal("|").notAnyOf("}").oneOrMore().lazy().endGroup().zeroOrMore().endGroup().literal("}").endGroup().optional().startGroup().literal("(").startNamedGroup("gIngredientPreparation").notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().toRegExp();
+var ingredientWithGroupKeyRegex = d().literal("@|").startNamedGroup("gIngredientGroupKey").notAnyOf(nonWordCharStrict + "/").oneOrMore().endGroup().startGroup().literal("/").startNamedGroup("gIngredientSubgroupKey").notAnyOf(nonWordCharStrict).oneOrMore().endGroup().endGroup().optional().literal("|").startNamedGroup("gIngredientModifiers").anyOf("@\\-&?").zeroOrMore().endGroup().optional().startNamedGroup("gIngredientRecipeAnchor").literal("./").endGroup().optional().startGroup().startGroup().startNamedGroup("gmIngredientName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\}|\\([^)]*\\))").endGroup().or().startNamedGroup("gsIngredientName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().endGroup().startGroup().literal("{").startNamedGroup("gIngredientQuantityModifier").literal("=").exactly(1).endGroup().optional().startNamedGroup("gIngredientQuantity").startGroup().notAnyOf("}|%").oneOrMore().endGroup().optional().startGroup().literal("%").notAnyOf("|}").oneOrMore().lazy().endGroup().optional().startGroup().literal("|").notAnyOf("}").oneOrMore().lazy().endGroup().zeroOrMore().endGroup().literal("}").endGroup().optional().startGroup().literal("(").startNamedGroup("gIngredientPreparation").notAnyOf(")").oneOrMore().lazy().endGroup().literal(")").endGroup().optional().startGroup().literal("[").startNamedGroup("gIngredientNote").notAnyOf("\\]").oneOrMore().lazy().endGroup().literal("]").endGroup().optional().toRegExp();
 var ingredientAliasRegex = d().startAnchor().startNamedGroup("ingredientListName").notAnyOf("|").oneOrMore().endGroup().literal("|").startNamedGroup("ingredientDisplayName").notAnyOf("|").oneOrMore().endGroup().endAnchor().toRegExp();
 var cookwareRegex = d().literal("#").startNamedGroup("cookwareModifiers").anyOf("\\-&?").zeroOrMore().endGroup().startGroup().startGroup().startNamedGroup("mCookwareName").notAnyOf(nonWordChar).oneOrMore().startGroup().whitespace().oneOrMore().notAnyOf(nonWordChar).oneOrMore().endGroup().oneOrMore().endGroup().positiveLookahead("\\s*(?:\\{[^\\}]*\\})").endGroup().or().startNamedGroup("sCookwareName").notAnyOf(nonWordChar).zeroOrMore().notAnyOf("\\." + nonWordChar).endGroup().endGroup().startGroup().literal("{").startNamedGroup("cookwareQuantity").anyCharacter().zeroOrMore().lazy().endGroup().literal("}").endGroup().optional().toRegExp();
 var timerRegex = d().literal("~").startNamedGroup("timerName").anyCharacter().zeroOrMore().lazy().endGroup().literal("{").startNamedGroup("timerQuantity").anyCharacter().oneOrMore().lazy().endGroup().startGroup().literal("%").startNamedGroup("timerUnit").anyCharacter().oneOrMore().lazy().endGroup().endGroup().optional().literal("}").toRegExp();
@@ -305,6 +305,7 @@ var shoppingListRegex = d().literal("[").startNamedGroup("name").anyCharacter().
 var rangeRegex = d().startAnchor().digit().oneOrMore().startGroup().anyOf(".,/").exactly(1).digit().oneOrMore().endGroup().optional().literal("-").digit().oneOrMore().startGroup().anyOf(".,/").exactly(1).digit().oneOrMore().endGroup().optional().endAnchor().toRegExp();
 var numberLikeRegex = d().startAnchor().digit().oneOrMore().startGroup().anyOf(".,/").exactly(1).digit().oneOrMore().endGroup().optional().endAnchor().toRegExp();
 var floatRegex = d().startAnchor().digit().oneOrMore().startGroup().anyOf(".").exactly(1).digit().oneOrMore().endGroup().optional().endAnchor().toRegExp();
+var variantTagRegex = d().startAnchor().literal("[").startNamedGroup("variantOptionalPrefix").literal("?").endGroup().optional().startNamedGroup("variantNames").notAnyOf("\\]").zeroOrMore().endGroup().literal("]").whitespace().zeroOrMore().toRegExp();
 var mdEscaped = d().literal("\\").startCaptureGroup().anyOf("*_`").endGroup();
 var mdInlineCode = d().literal("`").startCaptureGroup().notAnyOf("`").oneOrMore().lazy().endGroup().literal("`");
 var mdLink = d().literal("[").startCaptureGroup().notAnyOf("\\]").oneOrMore().lazy().endGroup().literal("](").startCaptureGroup().notAnyOf(")").oneOrMore().lazy().endGroup().literal(")");
@@ -1359,9 +1360,12 @@ function flushPendingNote(section, noteItems) {
   }
   return noteItems;
 }
-function flushPendingItems(section, items) {
+function flushPendingItems(section, items, stepVariants, stepOptional) {
   if (items.length > 0) {
-    section.content.push({ type: "step", items: [...items] });
+    const step = { type: "step", items: [...items] };
+    if (stepVariants) step.variants = stepVariants;
+    if (stepOptional) step.optional = true;
+    section.content.push(step);
     items.length = 0;
     return true;
   }
@@ -1905,7 +1909,8 @@ function extractMetadata(content) {
     "yield",
     "serves",
     // List fields
-    "tags"
+    "tags",
+    "variants"
   ]);
   for (const metaVar of [
     "title",
@@ -1992,6 +1997,8 @@ function extractMetadata(content) {
   }
   const tags = parseListMetaVar(metadataContent, "tags");
   if (tags) metadata.tags = tags;
+  const variants = parseListMetaVar(metadataContent, "variants");
+  if (variants) metadata.variants = variants;
   const allKeys = extractAllMetadataKeys(metadataContent);
   for (const key of allKeys) {
     if (handledKeys.has(key)) continue;
@@ -2379,8 +2386,10 @@ var Section = class {
   /**
    * Creates an instance of Section.
    * @param name - The name of the section. Defaults to an empty string.
+   * @param variants - Optional variant names for this section.
+   * @param optional - Whether the section is optional.
    */
-  constructor(name = "") {
+  constructor(name = "", variants, optional) {
     /**
      * The name of the section. Can be an empty string for the default (first) section.
      * @defaultValue `""`
@@ -2388,7 +2397,13 @@ var Section = class {
     __publicField(this, "name");
     /** An array of steps and notes that make up the content of the section. */
     __publicField(this, "content", []);
+    /** Optional list of variant names this section belongs to. */
+    __publicField(this, "variants");
+    /** Whether the section has been marked as optional ([?]) */
+    __publicField(this, "optional");
     this.name = name;
+    if (variants) this.variants = variants;
+    if (optional) this.optional = true;
   }
   /**
    * Checks if the section is blank (has no name and no content).
@@ -2748,7 +2763,8 @@ var _Recipe = class _Recipe {
      */
     __publicField(this, "choices", {
       ingredientItems: /* @__PURE__ */ new Map(),
-      ingredientGroups: /* @__PURE__ */ new Map()
+      ingredientGroups: /* @__PURE__ */ new Map(),
+      variants: []
     });
     /**
      * The parsed recipe ingredients.
@@ -2779,6 +2795,7 @@ var _Recipe = class _Recipe {
      */
     __publicField(this, "servings");
     _Recipe.itemCounts.set(this, 0);
+    _Recipe.subgroupIndices.set(this, /* @__PURE__ */ new Map());
     if (content) {
       this.parse(content);
     }
@@ -2996,6 +3013,7 @@ var _Recipe = class _Recipe {
     if (!match?.groups) return;
     const groups = match.groups;
     const groupKey = groups.gIngredientGroupKey;
+    const subgroupKey = groups.gIngredientSubgroupKey;
     let name = groups.gmIngredientName || groups.gsIngredientName;
     const preparation = groups.gIngredientPreparation;
     const modifiers = groups.gIngredientModifiers;
@@ -3063,7 +3081,12 @@ var _Recipe = class _Recipe {
     if (itemQuantity) {
       Object.assign(alternative, itemQuantity);
     }
-    const existingAlternatives = this.choices.ingredientGroups.get(groupKey);
+    const note = groups.gIngredientNote?.trim();
+    if (note) {
+      alternative.note = note;
+    }
+    const existingSubgroups = this.choices.ingredientGroups.get(groupKey);
+    const existingAlternativesFlat = existingSubgroups?.flat();
     function upsertAlternativeToIngredient(ingredients, ingredientIdx, newAlternativeIdx) {
       const ingredient = ingredients[ingredientIdx];
       if (ingredient) {
@@ -3074,8 +3097,8 @@ var _Recipe = class _Recipe {
         }
       }
     }
-    if (existingAlternatives) {
-      for (const alt of existingAlternatives) {
+    if (existingAlternativesFlat) {
+      for (const alt of existingAlternativesFlat) {
         upsertAlternativeToIngredient(this.ingredients, alt.index, idxInList);
         upsertAlternativeToIngredient(this.ingredients, idxInList, alt.index);
       }
@@ -3087,14 +3110,35 @@ var _Recipe = class _Recipe {
       group: groupKey,
       alternatives: [alternative]
     };
+    if (subgroupKey !== void 0) {
+      newItem.subgroup = subgroupKey;
+    }
     items.push(newItem);
     const choiceAlternative = deepClone(alternative);
     choiceAlternative.itemId = id;
     const existingChoice = this.choices.ingredientGroups.get(groupKey);
+    const sgMap = _Recipe.subgroupIndices.get(this);
     if (!existingChoice) {
-      this.choices.ingredientGroups.set(groupKey, [choiceAlternative]);
+      this.choices.ingredientGroups.set(groupKey, [[choiceAlternative]]);
+      if (subgroupKey !== void 0) {
+        sgMap.set(groupKey, /* @__PURE__ */ new Map([[subgroupKey, 0]]));
+      }
+    } else if (subgroupKey !== void 0) {
+      const groupSgMap = sgMap.get(groupKey);
+      const existingIdx = groupSgMap?.get(subgroupKey);
+      if (existingIdx !== void 0) {
+        existingChoice[existingIdx].push(choiceAlternative);
+      } else {
+        const newIdx = existingChoice.length;
+        existingChoice.push([choiceAlternative]);
+        if (!groupSgMap) {
+          sgMap.set(groupKey, /* @__PURE__ */ new Map([[subgroupKey, newIdx]]));
+        } else {
+          groupSgMap.set(subgroupKey, newIdx);
+        }
+      }
     } else {
-      existingChoice.push(choiceAlternative);
+      existingChoice.push([choiceAlternative]);
     }
   }
   /**
@@ -3134,6 +3178,8 @@ var _Recipe = class _Recipe {
   /** @internal */
   collectQuantityGroups(options) {
     const { section, step, choices } = options || {};
+    const activeVariant = choices?.variant;
+    const isDefaultVariant = activeVariant === void 0 || activeVariant === "*";
     const sectionsToProcess = section !== void 0 ? (() => {
       const idx = typeof section === "number" ? section : this.sections.indexOf(section);
       return idx >= 0 && idx < this.sections.length ? [this.sections[idx]] : [];
@@ -3141,36 +3187,89 @@ var _Recipe = class _Recipe {
     const ingredientGroups = /* @__PURE__ */ new Map();
     const selectedIndices = /* @__PURE__ */ new Set();
     const referencedIndices = /* @__PURE__ */ new Set();
+    const dynamicOptionalIndices = /* @__PURE__ */ new Set();
     for (const currentSection of sectionsToProcess) {
+      if (currentSection.variants) {
+        if (isDefaultVariant) {
+          if (!currentSection.variants.includes("*")) continue;
+        } else {
+          if (!currentSection.variants.includes(activeVariant)) continue;
+        }
+      }
       const allSteps = currentSection.content.filter(
         (item) => item.type === "step"
       );
+      const isOptionalSection = currentSection.optional === true;
       const stepsToProcess = step === void 0 ? allSteps : typeof step === "number" ? step >= 0 && step < allSteps.length ? [allSteps[step]] : [] : allSteps.includes(step) ? [step] : [];
       for (const currentStep of stepsToProcess) {
+        if (currentStep.variants) {
+          if (isDefaultVariant) {
+            if (!currentStep.variants.includes("*")) continue;
+          } else {
+            if (!currentStep.variants.includes(activeVariant)) continue;
+          }
+        }
+        const isOptionalStep = currentStep.optional === true || isOptionalSection;
         for (const item of currentStep.items.filter(
           (item2) => item2.type === "ingredient"
         )) {
           const isGrouped = "group" in item && item.group !== void 0;
-          const groupAlternatives = isGrouped ? this.choices.ingredientGroups.get(item.group) : void 0;
+          const groupSubgroups = isGrouped ? this.choices.ingredientGroups.get(item.group) : void 0;
           let selectedAltIndex = 0;
           let isSelected;
           let hasExplicitChoice;
           if (isGrouped) {
             const groupChoice = choices?.ingredientGroups?.get(item.group);
             hasExplicitChoice = groupChoice !== void 0;
-            const targetIndex = groupChoice ?? 0;
-            isSelected = groupAlternatives?.[targetIndex]?.itemId === item.id;
+            if (!hasExplicitChoice && !isDefaultVariant) {
+              const matchingSubgroupIdx = groupSubgroups?.findIndex(
+                (sg) => sg.some(
+                  (alt) => alt.note && alt.note.toLowerCase().includes(activeVariant.toLowerCase())
+                )
+              );
+              if (matchingSubgroupIdx !== void 0 && matchingSubgroupIdx >= 0) {
+                const matchedSubgroup = groupSubgroups[matchingSubgroupIdx];
+                isSelected = matchedSubgroup.some(
+                  (alt) => alt.itemId === item.id
+                );
+                hasExplicitChoice = true;
+                selectedAltIndex = 0;
+              } else {
+                const targetSubgroupIndex = 0;
+                const selectedSubgroup = groupSubgroups?.[targetSubgroupIndex];
+                isSelected = selectedSubgroup?.some((alt) => alt.itemId === item.id) ?? false;
+              }
+            } else {
+              const targetSubgroupIndex = groupChoice ?? 0;
+              const selectedSubgroup = groupSubgroups?.[targetSubgroupIndex];
+              isSelected = selectedSubgroup?.some((alt) => alt.itemId === item.id) ?? false;
+            }
           } else {
             const itemChoice = choices?.ingredientItems?.get(item.id);
             hasExplicitChoice = itemChoice !== void 0;
-            selectedAltIndex = itemChoice ?? 0;
+            if (!hasExplicitChoice && !isDefaultVariant) {
+              const matchingIndices = item.alternatives.map((alt, idx) => ({ alt, idx })).filter(
+                ({ alt }) => alt.note && alt.note.toLowerCase().includes(activeVariant.toLowerCase())
+              ).map(({ idx }) => idx);
+              if (matchingIndices.length > 0) {
+                selectedAltIndex = matchingIndices[0];
+                hasExplicitChoice = true;
+              } else {
+                selectedAltIndex = itemChoice ?? 0;
+              }
+            } else {
+              selectedAltIndex = itemChoice ?? 0;
+            }
             isSelected = true;
           }
           const alternative = item.alternatives[selectedAltIndex];
           if (!alternative || !isSelected) continue;
           selectedIndices.add(alternative.index);
-          const allAlts = isGrouped ? groupAlternatives : item.alternatives;
-          for (const alt of allAlts) {
+          if (isOptionalStep) {
+            dynamicOptionalIndices.add(alternative.index);
+          }
+          const allAltsFlat = isGrouped ? groupSubgroups.flat() : item.alternatives;
+          for (const alt of allAltsFlat) {
             referencedIndices.add(alt.index);
           }
           if (!alternative.quantity) continue;
@@ -3182,10 +3281,34 @@ var _Recipe = class _Recipe {
           };
           const quantityEntry = alternative.equivalents?.length ? { or: [baseQty, ...alternative.equivalents] } : baseQty;
           let alternativeRefs;
-          if (!hasExplicitChoice && allAlts.length > 1) {
-            alternativeRefs = allAlts.filter(
-              (alt) => isGrouped ? alt.itemId !== item.id : alt.index !== alternative.index
-            ).map((otherAlt) => {
+          if (!hasExplicitChoice && groupSubgroups && groupSubgroups.length > 1) {
+            const currentSubgroupIdx = groupSubgroups.findIndex(
+              (sg) => sg.some((alt) => alt.itemId === item.id)
+            );
+            alternativeRefs = groupSubgroups.filter((_, idx) => idx !== currentSubgroupIdx).flatMap(
+              (subgroup) => subgroup.map((otherAlt) => {
+                const ref = {
+                  index: otherAlt.index
+                };
+                if (otherAlt.quantity) {
+                  const altQty = {
+                    quantity: otherAlt.quantity,
+                    ...otherAlt.unit && {
+                      unit: otherAlt.unit.name
+                    },
+                    ...otherAlt.equivalents && {
+                      equivalents: otherAlt.equivalents.map(
+                        (eq) => toPlainUnit(eq)
+                      )
+                    }
+                  };
+                  ref.quantities = [altQty];
+                }
+                return ref;
+              })
+            );
+          } else if (!hasExplicitChoice && !isGrouped && allAltsFlat.length > 1) {
+            alternativeRefs = allAltsFlat.filter((alt) => alt.index !== alternative.index).map((otherAlt) => {
               const ref = { index: otherAlt.index };
               if (otherAlt.quantity) {
                 const altQty = {
@@ -3250,7 +3373,12 @@ var _Recipe = class _Recipe {
         }
       }
     }
-    return { ingredientGroups, selectedIndices, referencedIndices };
+    return {
+      ingredientGroups,
+      selectedIndices,
+      referencedIndices,
+      dynamicOptionalIndices
+    };
   }
   /**
    * Gets the raw (unprocessed) quantity groups for each ingredient, before
@@ -3269,12 +3397,21 @@ var _Recipe = class _Recipe {
    * ```
    */
   getRawQuantityGroups(options) {
-    const { ingredientGroups, selectedIndices, referencedIndices } = this.collectQuantityGroups(options);
+    const {
+      ingredientGroups,
+      selectedIndices,
+      referencedIndices,
+      dynamicOptionalIndices
+    } = this.collectQuantityGroups(options);
     const result = [];
     for (let index = 0; index < this.ingredients.length; index++) {
       if (!referencedIndices.has(index)) continue;
       const orig = this.ingredients[index];
       const usedAsPrimary = selectedIndices.has(index);
+      let flags = orig.flags;
+      if (dynamicOptionalIndices.has(index) && !flags?.includes("optional")) {
+        flags = [...flags ?? [], "optional"];
+      }
       const quantities = [];
       if (usedAsPrimary) {
         const groupsForIng = ingredientGroups.get(index);
@@ -3287,7 +3424,7 @@ var _Recipe = class _Recipe {
       result.push({
         name: orig.name,
         ...usedAsPrimary && { usedAsPrimary: true },
-        ...orig.flags && { flags: orig.flags },
+        ...flags && { flags },
         quantities
       });
     }
@@ -3321,15 +3458,24 @@ var _Recipe = class _Recipe {
    * ```
    */
   getIngredientQuantities(options) {
-    const { ingredientGroups, selectedIndices, referencedIndices } = this.collectQuantityGroups(options);
+    const {
+      ingredientGroups,
+      selectedIndices,
+      referencedIndices,
+      dynamicOptionalIndices
+    } = this.collectQuantityGroups(options);
     const result = [];
     for (let index = 0; index < this.ingredients.length; index++) {
       if (!referencedIndices.has(index)) continue;
       const orig = this.ingredients[index];
+      let flags = orig.flags;
+      if (dynamicOptionalIndices.has(index) && !flags?.includes("optional")) {
+        flags = [...flags ?? [], "optional"];
+      }
       const ing = {
         name: orig.name,
         ...orig.preparation && { preparation: orig.preparation },
-        ...orig.flags && { flags: orig.flags },
+        ...flags && { flags },
         ...orig.extras && { extras: orig.extras }
       };
       if (selectedIndices.has(index)) {
@@ -3380,6 +3526,59 @@ var _Recipe = class _Recipe {
     }
     return result;
   }
+  /**
+   * Returns the list of cookware items that are used in the active variant.
+   * Cookware in steps/sections not matching the active variant are excluded.
+   * Hidden cookware is always excluded.
+   *
+   * @param options - Options for filtering:
+   *   - `choices`: The choices to apply (only `variant` is used)
+   * @returns Array of Cookware objects referenced by active steps
+   *
+   * @example
+   * ```typescript
+   * // Get all cookware for the default variant
+   * const cookware = recipe.getCookwareForVariant();
+   *
+   * // Get cookware for a specific variant
+   * const veganCookware = recipe.getCookwareForVariant({ choices: { variant: 'vegan' } });
+   * ```
+   */
+  getCookwareForVariant(options) {
+    const { choices } = options || {};
+    const activeVariant = choices?.variant;
+    const isDefaultVariant = activeVariant === void 0 || activeVariant === "*";
+    const cookwareIndices = /* @__PURE__ */ new Set();
+    for (const currentSection of this.sections) {
+      if (currentSection.variants) {
+        if (isDefaultVariant) {
+          if (!currentSection.variants.includes("*")) continue;
+        } else {
+          if (!currentSection.variants.includes(activeVariant)) continue;
+        }
+      }
+      const allSteps = currentSection.content.filter(
+        (item) => item.type === "step"
+      );
+      for (const currentStep of allSteps) {
+        if (currentStep.variants) {
+          if (isDefaultVariant) {
+            if (!currentStep.variants.includes("*")) continue;
+          } else {
+            if (!currentStep.variants.includes(activeVariant)) continue;
+          }
+        }
+        for (const item of currentStep.items) {
+          if (item.type === "cookware") {
+            cookwareIndices.add(item.index);
+          }
+        }
+      }
+    }
+    return this.cookware.filter(
+      (cw, idx) => cookwareIndices.has(idx) && !cw.flags?.includes("hidden")
+    );
+  }
   /**
    * Parses a recipe from a string.
    * @param content - The recipe content to parse.
@@ -3395,9 +3594,14 @@ var _Recipe = class _Recipe {
     const items = [];
     let noteText = "";
     let inNote = false;
+    let stepVariants;
+    let stepOptional;
+    const discoveredVariants = /* @__PURE__ */ new Set();
     for (const line of cleanContent) {
       if (line.trim().length === 0) {
-        flushPendingItems(section, items);
+        flushPendingItems(section, items, stepVariants, stepOptional);
+        stepVariants = void 0;
+        stepOptional = void 0;
         flushPendingNote(
           section,
           noteText ? this._parseNoteText(noteText) : []
@@ -3408,26 +3612,48 @@ var _Recipe = class _Recipe {
         continue;
       }
       if (line.startsWith("=")) {
-        flushPendingItems(section, items);
+        flushPendingItems(section, items, stepVariants, stepOptional);
+        stepVariants = void 0;
+        stepOptional = void 0;
         flushPendingNote(
           section,
           noteText ? this._parseNoteText(noteText) : []
         );
         noteText = "";
+        let sectionName = line.replace(/^=+|=+$/g, "").trim();
+        let sectionVariants;
+        let sectionOptional;
+        const sectionVarMatch = sectionName.match(variantTagRegex);
+        if (sectionVarMatch?.groups) {
+          const isOptionalPrefix = sectionVarMatch.groups.variantOptionalPrefix === "?";
+          const names = (sectionVarMatch.groups.variantNames ?? "").split(",").map((n2) => n2.trim()).filter((n2) => n2.length > 0);
+          if (names.length > 0) {
+            sectionVariants = names;
+            for (const v of names) discoveredVariants.add(v);
+          }
+          if (isOptionalPrefix) {
+            sectionOptional = true;
+          }
+          sectionName = sectionName.slice(sectionVarMatch[0].length).trim();
+        }
         if (this.sections.length === 0 && section.isBlank()) {
-          section.name = line.replace(/^=+|=+$/g, "").trim();
+          section.name = sectionName;
+          if (sectionVariants) section.variants = sectionVariants;
+          if (sectionOptional) section.optional = true;
         } else {
           if (!section.isBlank()) {
             this.sections.push(section);
           }
-          section = new Section(line.replace(/^=+|=+$/g, "").trim());
+          section = new Section(sectionName, sectionVariants, sectionOptional);
         }
         blankLineBefore = true;
         inNote = false;
         continue;
       }
       if (blankLineBefore && line.startsWith(">")) {
-        flushPendingItems(section, items);
+        flushPendingItems(section, items, stepVariants, stepOptional);
+        stepVariants = void 0;
+        stepOptional = void 0;
         noteText = line.substring(1).trim();
         inNote = true;
         blankLineBefore = false;
@@ -3442,11 +3668,31 @@ var _Recipe = class _Recipe {
         blankLineBefore = false;
         continue;
       }
+      let currentLine = line;
+      if (items.length === 0) {
+        const varMatch = currentLine.match(variantTagRegex);
+        if (varMatch?.groups) {
+          const isOptionalPrefix = varMatch.groups.variantOptionalPrefix === "?";
+          const names = (varMatch.groups.variantNames ?? "").split(",").map((n2) => n2.trim()).filter((n2) => n2.length > 0);
+          if (names.length > 0) {
+            stepVariants = names;
+            for (const v of names) discoveredVariants.add(v);
+          }
+          if (isOptionalPrefix) {
+            stepOptional = true;
+          }
+          currentLine = currentLine.slice(varMatch[0].length);
+          if (currentLine.trim().length === 0) {
+            blankLineBefore = false;
+            continue;
+          }
+        }
+      }
       let cursor = 0;
-      for (const match of line.matchAll(tokensRegex)) {
+      for (const match of currentLine.matchAll(tokensRegex)) {
         const idx = match.index;
         if (idx > cursor) {
-          items.push(...parseMarkdownSegments(line.slice(cursor, idx)));
+          items.push(...parseMarkdownSegments(currentLine.slice(cursor, idx)));
         }
         const groups = match.groups;
         if (groups.mIngredientName || groups.sIngredientName) {
@@ -3507,16 +3753,21 @@ var _Recipe = class _Recipe {
         }
         cursor = idx + match[0].length;
       }
-      if (cursor < line.length) {
-        items.push(...parseMarkdownSegments(line.slice(cursor)));
+      if (cursor < currentLine.length) {
+        items.push(...parseMarkdownSegments(currentLine.slice(cursor)));
       }
       blankLineBefore = false;
     }
-    flushPendingItems(section, items);
+    flushPendingItems(section, items, stepVariants, stepOptional);
     flushPendingNote(section, noteText ? this._parseNoteText(noteText) : []);
     if (!section.isBlank()) {
       this.sections.push(section);
     }
+    const metaVariants = this.metadata.variants ?? [];
+    const allVariants = /* @__PURE__ */ new Set([...metaVariants, ...discoveredVariants]);
+    if (allVariants.size > 0) {
+      this.choices.variants = [...allVariants];
+    }
     this._populateIngredientQuantities();
   }
   /**
@@ -3603,8 +3854,10 @@ var _Recipe = class _Recipe {
         }
       }
     }
-    for (const alternatives of newRecipe.choices.ingredientGroups.values()) {
-      scaleAlternativesBy(alternatives, factor);
+    for (const subgroups of newRecipe.choices.ingredientGroups.values()) {
+      for (const subgroup of subgroups) {
+        scaleAlternativesBy(subgroup, factor);
+      }
     }
     for (const alternatives of newRecipe.choices.ingredientItems.values()) {
       scaleAlternativesBy(alternatives, factor);
@@ -3791,8 +4044,10 @@ var _Recipe = class _Recipe {
         }
       }
     }
-    for (const alternatives of newRecipe.choices.ingredientGroups.values()) {
-      convertAlternatives(alternatives);
+    for (const subgroups of newRecipe.choices.ingredientGroups.values()) {
+      for (const subgroup of subgroups) {
+        convertAlternatives(subgroup);
+      }
     }
     for (const alternatives of newRecipe.choices.ingredientItems.values()) {
       convertAlternatives(alternatives);
@@ -3823,7 +4078,11 @@ var _Recipe = class _Recipe {
     newRecipe.metadata = deepClone(this.metadata);
     newRecipe.ingredients = deepClone(this.ingredients);
     newRecipe.sections = this.sections.map((section) => {
-      const newSection = new Section(section.name);
+      const newSection = new Section(
+        section.name,
+        section.variants,
+        section.optional
+      );
       newSection.content = deepClone(section.content);
       return newSection;
     });
@@ -3844,6 +4103,11 @@ __publicField(_Recipe, "unitSystems", /* @__PURE__ */ new WeakMap());
  * Used for giving ID numbers to items during parsing.
  */
 __publicField(_Recipe, "itemCounts", /* @__PURE__ */ new WeakMap());
+/**
+ * External storage for subgroup index tracking during parsing.
+ * Maps groupKey → subgroupKey → index within the subgroups array.
+ */
+__publicField(_Recipe, "subgroupIndices", /* @__PURE__ */ new WeakMap());
 var Recipe = _Recipe;
 
 // src/classes/shopping_list.ts
@@ -4681,22 +4945,62 @@ function isGroupedItem(item) {
 function isAlternativeSelected(recipe, choices, item, alternativeIndex) {
   if (item.group) {
     const selectedIndex2 = choices?.ingredientGroups?.get(item.group);
-    const groupAlternatives = recipe.choices.ingredientGroups.get(item.group);
-    if (groupAlternatives && selectedIndex2 !== void 0 && selectedIndex2 < groupAlternatives.length) {
-      const selectedItemId = groupAlternatives[selectedIndex2]?.itemId;
-      return selectedItemId === item.id;
+    const groupSubgroups = recipe.choices.ingredientGroups.get(item.group);
+    if (groupSubgroups && selectedIndex2 !== void 0 && selectedIndex2 < groupSubgroups.length) {
+      const selectedSubgroup = groupSubgroups[selectedIndex2];
+      return selectedSubgroup?.some((alt) => alt.itemId === item.id);
     }
     return false;
   }
   const selectedIndex = choices?.ingredientItems?.get(item.id);
   return alternativeIndex === selectedIndex;
 }
+function isSectionActive(section, variant) {
+  if (!section.variants) return true;
+  const isDefault = variant === void 0 || variant === "*";
+  if (isDefault) {
+    return section.variants.includes("*");
+  }
+  return section.variants.includes(variant);
+}
+function isStepActive(step, variant) {
+  if (!step.variants) return true;
+  const isDefault = variant === void 0 || variant === "*";
+  if (isDefault) {
+    return step.variants.includes("*");
+  }
+  return step.variants.includes(variant);
+}
+function getEffectiveChoices(recipe, variant) {
+  const choices = { variant };
+  if (variant === void 0 || variant === "*") return choices;
+  const variantLower = variant.toLowerCase();
+  for (const [itemId, alternatives] of recipe.choices.ingredientItems) {
+    const matchIdx = alternatives.findIndex(
+      (alt) => alt.note && alt.note.toLowerCase().includes(variantLower)
+    );
+    if (matchIdx >= 0) {
+      if (!choices.ingredientItems) choices.ingredientItems = /* @__PURE__ */ new Map();
+      choices.ingredientItems.set(itemId, matchIdx);
+    }
+  }
+  for (const [groupId, subgroups] of recipe.choices.ingredientGroups) {
+    const matchIdx = subgroups.findIndex(
+      (sg) => sg.some(
+        (alt) => alt.note && alt.note.toLowerCase().includes(variantLower)
+      )
+    );
+    if (matchIdx >= 0) {
+      if (!choices.ingredientGroups) choices.ingredientGroups = /* @__PURE__ */ new Map();
+      choices.ingredientGroups.set(groupId, matchIdx);
+    }
+  }
+  return choices;
+}
 export {
-  BadIndentationError,
   CategoryConfig,
   NoProductCatalogForCartError,
   NoShoppingListForCartError,
-  NoTabAsIndentError,
   Pantry,
   ProductCatalog,
   Recipe,
@@ -4711,11 +5015,14 @@ export {
   formatQuantityWithUnit,
   formatSingleValue,
   formatUnit,
+  getEffectiveChoices,
   hasAlternatives,
   isAlternativeSelected,
   isAndGroup,
   isGroupedItem,
+  isSectionActive,
   isSimpleGroup,
+  isStepActive,
   renderFractionAsVulgar
 };
 /* v8 ignore else -- @preserve */