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

package/dist/index.d.cts

@@ -16,11 +16,17 @@ declare class Section {
     name: string;
     /** An array of steps and notes that make up the content of the section. */
     content: (Step | Note)[];
+    /** Optional list of variant names this section belongs to. */
+    variants?: string[];
+    /** Whether the section has been marked as optional ([?]) */
+    optional?: boolean;
     /**
      * 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?: string);
+    constructor(name?: string, variants?: string[], optional?: boolean);
     /**
      * Checks if the section is blank (has no name and no content).
      * Used during recipe parsing
@@ -114,6 +120,11 @@ declare class Recipe {
      * Used for giving ID numbers to items during parsing.
      */
     private static itemCounts;
+    /**
+     * External storage for subgroup index tracking during parsing.
+     * Maps groupKey → subgroupKey → index within the subgroups array.
+     */
+    private static subgroupIndices;
     /**
      * Gets the current item count for this recipe.
      */
@@ -202,6 +213,25 @@ declare class Recipe {
      * ```
      */
     getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
+    /**
+     * 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?: Pick<GetIngredientQuantitiesOptions, "choices">): Cookware[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -402,6 +432,8 @@ interface Metadata {
      * This stores the original value as written by the user.
      */
     unitSystem?: string;
+    /** The list of available variant names for this recipe. */
+    variants?: string[];
     /**
      * Index signature for additional metadata fields not explicitly typed.
      * Any metadata key in the frontmatter will be captured here.
@@ -562,6 +594,12 @@ interface Ingredient {
     /** The collection of potential additional metadata for the ingredient */
     extras?: IngredientExtras;
 }
+/**
+ * Represents a quantity with extended unit and additional information
+ * about its scalability and potential equivalents
+ *
+ * @category Types
+ */
 type MaybeScalableQuantity = QuantityWithExtendedUnit & {
     /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
     scalable: boolean;
@@ -569,6 +607,15 @@ type MaybeScalableQuantity = QuantityWithExtendedUnit & {
      * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g. */
     equivalents?: QuantityWithExtendedUnit[];
 };
+/**
+ * Defines a type containing an optional {@link QuantityWithExtendedUnit} with scalability and potential info about equivalents
+ *
+ * Used in {@link IngredientAlternative}
+ *
+ * @param T - The base type to which the optional quantity properties will be added.
+ *
+ * @category Types
+ */
 type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
     quantity?: undefined;
     scalable?: never;
@@ -576,8 +623,7 @@ type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
     equivalents?: never;
 });
 /**
- * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
- * to a specific ingredient and its corresponding quantity information.
+ * Base type of {@link IngredientAlternative}
  * @category Types
  */
 type IngredientAlternativeBase = {
@@ -592,6 +638,14 @@ type IngredientAlternativeBase = {
      * Can be useful for creating alternative selection UI elements with anchor links */
     itemId?: string;
 };
+/**
+ * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
+ * to a specific ingredient and its corresponding quantity information.
+ *
+ * Used in {@link IngredientItem} and for the various maps of {@link RecipeAlternatives}
+ *
+ * @category Types
+ */
 type IngredientAlternative = WithOptionalQuantity<IngredientAlternativeBase>;
 /**
  * Represents an ingredient item in a recipe step.
@@ -613,6 +667,12 @@ interface IngredientItem {
      * `@|group|...` syntax), they represent a single logical choice.
      */
     group?: string;
+    /**
+     * An optional subgroup identifier for binding multiple ingredients together
+     * within a group. Ingredients sharing the same `group` and `subgroup` are
+     * selected together as a unit (e.g., from `@|group/1|...` syntax).
+     */
+    subgroup?: string;
 }
 /**
  * Represents the choices one can make in a recipe
@@ -626,9 +686,18 @@ interface RecipeAlternatives {
     ingredientItems: Map<string, IngredientAlternative[]>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's
      * - Keys are the Group IDs (e.g. "eggs" for `@|eggs|...`)
-     * - Values are arrays of IngredientAlternative objects representing the choices available for that group
+     * - Values are arrays of subgroups, where each subgroup is an array of
+     *   bound IngredientAlternative objects that are selected together.
+     *   Items sharing the same subgroup key (e.g., `@|group/1|...`) are
+     *   in the same inner array. Items without a subgroup key each form
+     *   their own single-element subgroup.
+     */
+    ingredientGroups: Map<string, IngredientAlternative[][]>;
+    /**
+     * All variant names discovered in the recipe (from metadata, step tags,
+     * and section tags). Includes `*` if any step/section uses the default tag.
      */
-    ingredientGroups: Map<string, IngredientAlternative[]>;
+    variants: string[];
 }
 /**
  * Represents the choices to apply when computing ingredient quantities.
@@ -640,6 +709,8 @@ interface RecipeChoices {
     ingredientItems?: Map<string, number>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's */
     ingredientGroups?: Map<string, number>;
+    /** The selected variant name */
+    variant?: string;
 }
 /**
  * Options for the {@link Recipe.getIngredientQuantities | getIngredientQuantities()} method.
@@ -664,9 +735,9 @@ interface GetIngredientQuantitiesOptions {
 }
 /**
  * Represents a raw (unprocessed) group of quantities for a single ingredient.
- * Returned by {@link Recipe.getRawQuantityGroups | getRawQuantityGroups()},
- * these are the pre-addition quantities that can be fed directly into
- * {@link addEquivalentsAndSimplify} for cross-recipe aggregation.
+ * Returned by {@link Recipe.getRawQuantityGroups},
+ * these are the pre-addition quantities that are fed internally
+ * to another non-public helper function for cross-recipe aggregation.
  * @category Types
  */
 interface RawQuantityGroup {
@@ -767,6 +838,10 @@ interface Step {
     type: "step";
     /** The items in the step. */
     items: StepItem[];
+    /** Optional list of variant names this step belongs to */
+    variants?: string[];
+    /** Whether the step has been marked as optional ("[?]") */
+    optional?: boolean;
 }
 /**
  * Represents an item in a note (can be text or arbitrary scalable).
@@ -837,6 +912,9 @@ interface RecipeWithServings {
 type AddedRecipe = RecipeWithFactor | RecipeWithServings;
 /**
  * Options for adding a recipe to a shopping list
+ *
+ * Used in {@link ShoppingList.addRecipe}
+ *
  * @category Types
  */
 type AddedRecipeOptions = {
@@ -1842,6 +1920,81 @@ declare function isGroupedItem(item: IngredientItem): boolean;
  * ```
  */
 declare function isAlternativeSelected(recipe: Recipe, choices: RecipeChoices, item: IngredientItem, alternativeIndex?: number): boolean;
+/**
+ * Determines if a section is active (should be displayed or processed) for a given variant.
+ *
+ * - Sections with no `variants` property are always active.
+ * - When no variant is selected (default), sections tagged `[*]` are active,
+ *   and sections tagged with named variants are not.
+ * - When a named variant is selected, sections whose `variants` array includes
+ *   that name are active.
+ *
+ * @param section - The Section to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the section should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * for (const section of recipe.sections) {
+ *   if (isSectionActive(section, choices.variant)) {
+ *     // render section
+ *   }
+ * }
+ * ```
+ */
+declare function isSectionActive(section: Section, variant?: string): boolean;
+/**
+ * Determines if a step is active (should be displayed) for a given variant.
+ *
+ * - Steps with no `variants` property are always active.
+ * - When no variant is selected (default), steps tagged `[*]` are active,
+ *   and steps tagged with named variants are not.
+ * - When a named variant is selected, steps whose `variants` array includes
+ *   that name are active.
+ *
+ * @param step - The Step to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the step should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const item of section.content) {
+ *   if (item.type === 'step' && isStepActive(item, choices.variant)) {
+ *     // render step
+ *   }
+ * }
+ * ```
+ */
+declare function isStepActive(step: Step, variant?: string): boolean;
+/**
+ * Returns the effective choices for a recipe given a variant selection.
+ *
+ * When a named variant is active, this scans ingredient alternatives whose
+ * `note` contains the variant name (case-insensitive substring match) and
+ * returns a `RecipeChoices` object with auto-selected alternatives.
+ *
+ * For inline alternatives: auto-selects the first alternative whose note
+ * matches the variant name.
+ *
+ * For grouped alternatives: auto-selects the first subgroup that has any
+ * alternative whose note matches the variant name.
+ *
+ * @param recipe - The Recipe instance
+ * @param variant - The active variant name, or `undefined`/`*` for defaults
+ * @returns A `RecipeChoices` with the `variant` set and auto-selected alternatives
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * const choices = getEffectiveChoices(recipe, "vegan");
+ * const ingredients = recipe.getIngredientQuantities({ choices });
+ * ```
+ */
+declare function getEffectiveChoices(recipe: Recipe, variant?: string): RecipeChoices;
 
 /**
  * Type guard to check if an ingredient quantity-like object is an AND group.
@@ -1931,11 +2084,5 @@ declare class NoProductCatalogForCartError extends Error {
 declare class NoShoppingListForCartError extends Error {
     constructor();
 }
-declare class NoTabAsIndentError extends Error {
-    constructor();
-}
-declare class BadIndentationError extends Error {
-    constructor();
-}
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, BadIndentationError, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataScalingVar, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup, renderFractionAsVulgar };
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataScalingVar, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, getEffectiveChoices, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSectionActive, isSimpleGroup, isStepActive, renderFractionAsVulgar };

package/dist/index.d.ts

@@ -16,11 +16,17 @@ declare class Section {
     name: string;
     /** An array of steps and notes that make up the content of the section. */
     content: (Step | Note)[];
+    /** Optional list of variant names this section belongs to. */
+    variants?: string[];
+    /** Whether the section has been marked as optional ([?]) */
+    optional?: boolean;
     /**
      * 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?: string);
+    constructor(name?: string, variants?: string[], optional?: boolean);
     /**
      * Checks if the section is blank (has no name and no content).
      * Used during recipe parsing
@@ -114,6 +120,11 @@ declare class Recipe {
      * Used for giving ID numbers to items during parsing.
      */
     private static itemCounts;
+    /**
+     * External storage for subgroup index tracking during parsing.
+     * Maps groupKey → subgroupKey → index within the subgroups array.
+     */
+    private static subgroupIndices;
     /**
      * Gets the current item count for this recipe.
      */
@@ -202,6 +213,25 @@ declare class Recipe {
      * ```
      */
     getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
+    /**
+     * 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?: Pick<GetIngredientQuantitiesOptions, "choices">): Cookware[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -402,6 +432,8 @@ interface Metadata {
      * This stores the original value as written by the user.
      */
     unitSystem?: string;
+    /** The list of available variant names for this recipe. */
+    variants?: string[];
     /**
      * Index signature for additional metadata fields not explicitly typed.
      * Any metadata key in the frontmatter will be captured here.
@@ -562,6 +594,12 @@ interface Ingredient {
     /** The collection of potential additional metadata for the ingredient */
     extras?: IngredientExtras;
 }
+/**
+ * Represents a quantity with extended unit and additional information
+ * about its scalability and potential equivalents
+ *
+ * @category Types
+ */
 type MaybeScalableQuantity = QuantityWithExtendedUnit & {
     /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
     scalable: boolean;
@@ -569,6 +607,15 @@ type MaybeScalableQuantity = QuantityWithExtendedUnit & {
      * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g. */
     equivalents?: QuantityWithExtendedUnit[];
 };
+/**
+ * Defines a type containing an optional {@link QuantityWithExtendedUnit} with scalability and potential info about equivalents
+ *
+ * Used in {@link IngredientAlternative}
+ *
+ * @param T - The base type to which the optional quantity properties will be added.
+ *
+ * @category Types
+ */
 type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
     quantity?: undefined;
     scalable?: never;
@@ -576,8 +623,7 @@ type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
     equivalents?: never;
 });
 /**
- * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
- * to a specific ingredient and its corresponding quantity information.
+ * Base type of {@link IngredientAlternative}
  * @category Types
  */
 type IngredientAlternativeBase = {
@@ -592,6 +638,14 @@ type IngredientAlternativeBase = {
      * Can be useful for creating alternative selection UI elements with anchor links */
     itemId?: string;
 };
+/**
+ * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
+ * to a specific ingredient and its corresponding quantity information.
+ *
+ * Used in {@link IngredientItem} and for the various maps of {@link RecipeAlternatives}
+ *
+ * @category Types
+ */
 type IngredientAlternative = WithOptionalQuantity<IngredientAlternativeBase>;
 /**
  * Represents an ingredient item in a recipe step.
@@ -613,6 +667,12 @@ interface IngredientItem {
      * `@|group|...` syntax), they represent a single logical choice.
      */
     group?: string;
+    /**
+     * An optional subgroup identifier for binding multiple ingredients together
+     * within a group. Ingredients sharing the same `group` and `subgroup` are
+     * selected together as a unit (e.g., from `@|group/1|...` syntax).
+     */
+    subgroup?: string;
 }
 /**
  * Represents the choices one can make in a recipe
@@ -626,9 +686,18 @@ interface RecipeAlternatives {
     ingredientItems: Map<string, IngredientAlternative[]>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's
      * - Keys are the Group IDs (e.g. "eggs" for `@|eggs|...`)
-     * - Values are arrays of IngredientAlternative objects representing the choices available for that group
+     * - Values are arrays of subgroups, where each subgroup is an array of
+     *   bound IngredientAlternative objects that are selected together.
+     *   Items sharing the same subgroup key (e.g., `@|group/1|...`) are
+     *   in the same inner array. Items without a subgroup key each form
+     *   their own single-element subgroup.
+     */
+    ingredientGroups: Map<string, IngredientAlternative[][]>;
+    /**
+     * All variant names discovered in the recipe (from metadata, step tags,
+     * and section tags). Includes `*` if any step/section uses the default tag.
      */
-    ingredientGroups: Map<string, IngredientAlternative[]>;
+    variants: string[];
 }
 /**
  * Represents the choices to apply when computing ingredient quantities.
@@ -640,6 +709,8 @@ interface RecipeChoices {
     ingredientItems?: Map<string, number>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's */
     ingredientGroups?: Map<string, number>;
+    /** The selected variant name */
+    variant?: string;
 }
 /**
  * Options for the {@link Recipe.getIngredientQuantities | getIngredientQuantities()} method.
@@ -664,9 +735,9 @@ interface GetIngredientQuantitiesOptions {
 }
 /**
  * Represents a raw (unprocessed) group of quantities for a single ingredient.
- * Returned by {@link Recipe.getRawQuantityGroups | getRawQuantityGroups()},
- * these are the pre-addition quantities that can be fed directly into
- * {@link addEquivalentsAndSimplify} for cross-recipe aggregation.
+ * Returned by {@link Recipe.getRawQuantityGroups},
+ * these are the pre-addition quantities that are fed internally
+ * to another non-public helper function for cross-recipe aggregation.
  * @category Types
  */
 interface RawQuantityGroup {
@@ -767,6 +838,10 @@ interface Step {
     type: "step";
     /** The items in the step. */
     items: StepItem[];
+    /** Optional list of variant names this step belongs to */
+    variants?: string[];
+    /** Whether the step has been marked as optional ("[?]") */
+    optional?: boolean;
 }
 /**
  * Represents an item in a note (can be text or arbitrary scalable).
@@ -837,6 +912,9 @@ interface RecipeWithServings {
 type AddedRecipe = RecipeWithFactor | RecipeWithServings;
 /**
  * Options for adding a recipe to a shopping list
+ *
+ * Used in {@link ShoppingList.addRecipe}
+ *
  * @category Types
  */
 type AddedRecipeOptions = {
@@ -1842,6 +1920,81 @@ declare function isGroupedItem(item: IngredientItem): boolean;
  * ```
  */
 declare function isAlternativeSelected(recipe: Recipe, choices: RecipeChoices, item: IngredientItem, alternativeIndex?: number): boolean;
+/**
+ * Determines if a section is active (should be displayed or processed) for a given variant.
+ *
+ * - Sections with no `variants` property are always active.
+ * - When no variant is selected (default), sections tagged `[*]` are active,
+ *   and sections tagged with named variants are not.
+ * - When a named variant is selected, sections whose `variants` array includes
+ *   that name are active.
+ *
+ * @param section - The Section to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the section should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * for (const section of recipe.sections) {
+ *   if (isSectionActive(section, choices.variant)) {
+ *     // render section
+ *   }
+ * }
+ * ```
+ */
+declare function isSectionActive(section: Section, variant?: string): boolean;
+/**
+ * Determines if a step is active (should be displayed) for a given variant.
+ *
+ * - Steps with no `variants` property are always active.
+ * - When no variant is selected (default), steps tagged `[*]` are active,
+ *   and steps tagged with named variants are not.
+ * - When a named variant is selected, steps whose `variants` array includes
+ *   that name are active.
+ *
+ * @param step - The Step to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the step should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const item of section.content) {
+ *   if (item.type === 'step' && isStepActive(item, choices.variant)) {
+ *     // render step
+ *   }
+ * }
+ * ```
+ */
+declare function isStepActive(step: Step, variant?: string): boolean;
+/**
+ * Returns the effective choices for a recipe given a variant selection.
+ *
+ * When a named variant is active, this scans ingredient alternatives whose
+ * `note` contains the variant name (case-insensitive substring match) and
+ * returns a `RecipeChoices` object with auto-selected alternatives.
+ *
+ * For inline alternatives: auto-selects the first alternative whose note
+ * matches the variant name.
+ *
+ * For grouped alternatives: auto-selects the first subgroup that has any
+ * alternative whose note matches the variant name.
+ *
+ * @param recipe - The Recipe instance
+ * @param variant - The active variant name, or `undefined`/`*` for defaults
+ * @returns A `RecipeChoices` with the `variant` set and auto-selected alternatives
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * const choices = getEffectiveChoices(recipe, "vegan");
+ * const ingredients = recipe.getIngredientQuantities({ choices });
+ * ```
+ */
+declare function getEffectiveChoices(recipe: Recipe, variant?: string): RecipeChoices;
 
 /**
  * Type guard to check if an ingredient quantity-like object is an AND group.
@@ -1931,11 +2084,5 @@ declare class NoProductCatalogForCartError extends Error {
 declare class NoShoppingListForCartError extends Error {
     constructor();
 }
-declare class NoTabAsIndentError extends Error {
-    constructor();
-}
-declare class BadIndentationError extends Error {
-    constructor();
-}
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, BadIndentationError, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataScalingVar, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, NoTabAsIndentError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSimpleGroup, renderFractionAsVulgar };
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataScalingVar, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, getEffectiveChoices, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSectionActive, isSimpleGroup, isStepActive, renderFractionAsVulgar };