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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -16,11 +16,17 @@ declare class Section {
16
16
  name: string;
17
17
  /** An array of steps and notes that make up the content of the section. */
18
18
  content: (Step | Note)[];
19
+ /** Optional list of variant names this section belongs to. */
20
+ variants?: string[];
21
+ /** Whether the section has been marked as optional ([?]) */
22
+ optional?: boolean;
19
23
  /**
20
24
  * Creates an instance of Section.
21
25
  * @param name - The name of the section. Defaults to an empty string.
26
+ * @param variants - Optional variant names for this section.
27
+ * @param optional - Whether the section is optional.
22
28
  */
23
- constructor(name?: string);
29
+ constructor(name?: string, variants?: string[], optional?: boolean);
24
30
  /**
25
31
  * Checks if the section is blank (has no name and no content).
26
32
  * Used during recipe parsing
@@ -207,6 +213,25 @@ declare class Recipe {
207
213
  * ```
208
214
  */
209
215
  getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
216
+ /**
217
+ * Returns the list of cookware items that are used in the active variant.
218
+ * Cookware in steps/sections not matching the active variant are excluded.
219
+ * Hidden cookware is always excluded.
220
+ *
221
+ * @param options - Options for filtering:
222
+ * - `choices`: The choices to apply (only `variant` is used)
223
+ * @returns Array of Cookware objects referenced by active steps
224
+ *
225
+ * @example
226
+ * ```typescript
227
+ * // Get all cookware for the default variant
228
+ * const cookware = recipe.getCookwareForVariant();
229
+ *
230
+ * // Get cookware for a specific variant
231
+ * const veganCookware = recipe.getCookwareForVariant({ choices: { variant: 'vegan' } });
232
+ * ```
233
+ */
234
+ getCookwareForVariant(options?: Pick<GetIngredientQuantitiesOptions, "choices">): Cookware[];
210
235
  /**
211
236
  * Parses a recipe from a string.
212
237
  * @param content - The recipe content to parse.
@@ -407,6 +432,8 @@ interface Metadata {
407
432
  * This stores the original value as written by the user.
408
433
  */
409
434
  unitSystem?: string;
435
+ /** The list of available variant names for this recipe. */
436
+ variants?: string[];
410
437
  /**
411
438
  * Index signature for additional metadata fields not explicitly typed.
412
439
  * Any metadata key in the frontmatter will be captured here.
@@ -567,6 +594,12 @@ interface Ingredient {
567
594
  /** The collection of potential additional metadata for the ingredient */
568
595
  extras?: IngredientExtras;
569
596
  }
597
+ /**
598
+ * Represents a quantity with extended unit and additional information
599
+ * about its scalability and potential equivalents
600
+ *
601
+ * @category Types
602
+ */
570
603
  type MaybeScalableQuantity = QuantityWithExtendedUnit & {
571
604
  /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
572
605
  scalable: boolean;
@@ -574,6 +607,15 @@ type MaybeScalableQuantity = QuantityWithExtendedUnit & {
574
607
  * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g. */
575
608
  equivalents?: QuantityWithExtendedUnit[];
576
609
  };
610
+ /**
611
+ * Defines a type containing an optional {@link QuantityWithExtendedUnit} with scalability and potential info about equivalents
612
+ *
613
+ * Used in {@link IngredientAlternative}
614
+ *
615
+ * @param T - The base type to which the optional quantity properties will be added.
616
+ *
617
+ * @category Types
618
+ */
577
619
  type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
578
620
  quantity?: undefined;
579
621
  scalable?: never;
@@ -581,8 +623,7 @@ type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
581
623
  equivalents?: never;
582
624
  });
583
625
  /**
584
- * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
585
- * to a specific ingredient and its corresponding quantity information.
626
+ * Base type of {@link IngredientAlternative}
586
627
  * @category Types
587
628
  */
588
629
  type IngredientAlternativeBase = {
@@ -597,6 +638,14 @@ type IngredientAlternativeBase = {
597
638
  * Can be useful for creating alternative selection UI elements with anchor links */
598
639
  itemId?: string;
599
640
  };
641
+ /**
642
+ * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
643
+ * to a specific ingredient and its corresponding quantity information.
644
+ *
645
+ * Used in {@link IngredientItem} and for the various maps of {@link RecipeAlternatives}
646
+ *
647
+ * @category Types
648
+ */
600
649
  type IngredientAlternative = WithOptionalQuantity<IngredientAlternativeBase>;
601
650
  /**
602
651
  * Represents an ingredient item in a recipe step.
@@ -644,6 +693,11 @@ interface RecipeAlternatives {
644
693
  * their own single-element subgroup.
645
694
  */
646
695
  ingredientGroups: Map<string, IngredientAlternative[][]>;
696
+ /**
697
+ * All variant names discovered in the recipe (from metadata, step tags,
698
+ * and section tags). Includes `*` if any step/section uses the default tag.
699
+ */
700
+ variants: string[];
647
701
  }
648
702
  /**
649
703
  * Represents the choices to apply when computing ingredient quantities.
@@ -655,6 +709,8 @@ interface RecipeChoices {
655
709
  ingredientItems?: Map<string, number>;
656
710
  /** Map of choices that can be made for Grouped Ingredient StepItem's */
657
711
  ingredientGroups?: Map<string, number>;
712
+ /** The selected variant name */
713
+ variant?: string;
658
714
  }
659
715
  /**
660
716
  * Options for the {@link Recipe.getIngredientQuantities | getIngredientQuantities()} method.
@@ -679,9 +735,9 @@ interface GetIngredientQuantitiesOptions {
679
735
  }
680
736
  /**
681
737
  * Represents a raw (unprocessed) group of quantities for a single ingredient.
682
- * Returned by {@link Recipe.getRawQuantityGroups | getRawQuantityGroups()},
683
- * these are the pre-addition quantities that can be fed directly into
684
- * {@link addEquivalentsAndSimplify} for cross-recipe aggregation.
738
+ * Returned by {@link Recipe.getRawQuantityGroups},
739
+ * these are the pre-addition quantities that are fed internally
740
+ * to another non-public helper function for cross-recipe aggregation.
685
741
  * @category Types
686
742
  */
687
743
  interface RawQuantityGroup {
@@ -782,6 +838,10 @@ interface Step {
782
838
  type: "step";
783
839
  /** The items in the step. */
784
840
  items: StepItem[];
841
+ /** Optional list of variant names this step belongs to */
842
+ variants?: string[];
843
+ /** Whether the step has been marked as optional ("[?]") */
844
+ optional?: boolean;
785
845
  }
786
846
  /**
787
847
  * Represents an item in a note (can be text or arbitrary scalable).
@@ -852,6 +912,9 @@ interface RecipeWithServings {
852
912
  type AddedRecipe = RecipeWithFactor | RecipeWithServings;
853
913
  /**
854
914
  * Options for adding a recipe to a shopping list
915
+ *
916
+ * Used in {@link ShoppingList.addRecipe}
917
+ *
855
918
  * @category Types
856
919
  */
857
920
  type AddedRecipeOptions = {
@@ -1857,6 +1920,81 @@ declare function isGroupedItem(item: IngredientItem): boolean;
1857
1920
  * ```
1858
1921
  */
1859
1922
  declare function isAlternativeSelected(recipe: Recipe, choices: RecipeChoices, item: IngredientItem, alternativeIndex?: number): boolean;
1923
+ /**
1924
+ * Determines if a section is active (should be displayed or processed) for a given variant.
1925
+ *
1926
+ * - Sections with no `variants` property are always active.
1927
+ * - When no variant is selected (default), sections tagged `[*]` are active,
1928
+ * and sections tagged with named variants are not.
1929
+ * - When a named variant is selected, sections whose `variants` array includes
1930
+ * that name are active.
1931
+ *
1932
+ * @param section - The Section to check
1933
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
1934
+ * @returns `true` if the section should be displayed
1935
+ * @category Helpers
1936
+ *
1937
+ * @example
1938
+ * ```typescript
1939
+ * const recipe = new Recipe(cooklangText);
1940
+ * for (const section of recipe.sections) {
1941
+ * if (isSectionActive(section, choices.variant)) {
1942
+ * // render section
1943
+ * }
1944
+ * }
1945
+ * ```
1946
+ */
1947
+ declare function isSectionActive(section: Section, variant?: string): boolean;
1948
+ /**
1949
+ * Determines if a step is active (should be displayed) for a given variant.
1950
+ *
1951
+ * - Steps with no `variants` property are always active.
1952
+ * - When no variant is selected (default), steps tagged `[*]` are active,
1953
+ * and steps tagged with named variants are not.
1954
+ * - When a named variant is selected, steps whose `variants` array includes
1955
+ * that name are active.
1956
+ *
1957
+ * @param step - The Step to check
1958
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
1959
+ * @returns `true` if the step should be displayed
1960
+ * @category Helpers
1961
+ *
1962
+ * @example
1963
+ * ```typescript
1964
+ * for (const item of section.content) {
1965
+ * if (item.type === 'step' && isStepActive(item, choices.variant)) {
1966
+ * // render step
1967
+ * }
1968
+ * }
1969
+ * ```
1970
+ */
1971
+ declare function isStepActive(step: Step, variant?: string): boolean;
1972
+ /**
1973
+ * Returns the effective choices for a recipe given a variant selection.
1974
+ *
1975
+ * When a named variant is active, this scans ingredient alternatives whose
1976
+ * `note` contains the variant name (case-insensitive substring match) and
1977
+ * returns a `RecipeChoices` object with auto-selected alternatives.
1978
+ *
1979
+ * For inline alternatives: auto-selects the first alternative whose note
1980
+ * matches the variant name.
1981
+ *
1982
+ * For grouped alternatives: auto-selects the first subgroup that has any
1983
+ * alternative whose note matches the variant name.
1984
+ *
1985
+ * @param recipe - The Recipe instance
1986
+ * @param variant - The active variant name, or `undefined`/`*` for defaults
1987
+ * @returns A `RecipeChoices` with the `variant` set and auto-selected alternatives
1988
+ * @category Helpers
1989
+ *
1990
+ * @example
1991
+ * ```typescript
1992
+ * const recipe = new Recipe(cooklangText);
1993
+ * const choices = getEffectiveChoices(recipe, "vegan");
1994
+ * const ingredients = recipe.getIngredientQuantities({ choices });
1995
+ * ```
1996
+ */
1997
+ declare function getEffectiveChoices(recipe: Recipe, variant?: string): RecipeChoices;
1860
1998
 
1861
1999
  /**
1862
2000
  * Type guard to check if an ingredient quantity-like object is an AND group.
@@ -1946,11 +2084,5 @@ declare class NoProductCatalogForCartError extends Error {
1946
2084
  declare class NoShoppingListForCartError extends Error {
1947
2085
  constructor();
1948
2086
  }
1949
- declare class NoTabAsIndentError extends Error {
1950
- constructor();
1951
- }
1952
- declare class BadIndentationError extends Error {
1953
- constructor();
1954
- }
1955
2087
 
1956
- 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 };
2088
+ 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 CHANGED
@@ -16,11 +16,17 @@ declare class Section {
16
16
  name: string;
17
17
  /** An array of steps and notes that make up the content of the section. */
18
18
  content: (Step | Note)[];
19
+ /** Optional list of variant names this section belongs to. */
20
+ variants?: string[];
21
+ /** Whether the section has been marked as optional ([?]) */
22
+ optional?: boolean;
19
23
  /**
20
24
  * Creates an instance of Section.
21
25
  * @param name - The name of the section. Defaults to an empty string.
26
+ * @param variants - Optional variant names for this section.
27
+ * @param optional - Whether the section is optional.
22
28
  */
23
- constructor(name?: string);
29
+ constructor(name?: string, variants?: string[], optional?: boolean);
24
30
  /**
25
31
  * Checks if the section is blank (has no name and no content).
26
32
  * Used during recipe parsing
@@ -207,6 +213,25 @@ declare class Recipe {
207
213
  * ```
208
214
  */
209
215
  getIngredientQuantities(options?: GetIngredientQuantitiesOptions): Ingredient[];
216
+ /**
217
+ * Returns the list of cookware items that are used in the active variant.
218
+ * Cookware in steps/sections not matching the active variant are excluded.
219
+ * Hidden cookware is always excluded.
220
+ *
221
+ * @param options - Options for filtering:
222
+ * - `choices`: The choices to apply (only `variant` is used)
223
+ * @returns Array of Cookware objects referenced by active steps
224
+ *
225
+ * @example
226
+ * ```typescript
227
+ * // Get all cookware for the default variant
228
+ * const cookware = recipe.getCookwareForVariant();
229
+ *
230
+ * // Get cookware for a specific variant
231
+ * const veganCookware = recipe.getCookwareForVariant({ choices: { variant: 'vegan' } });
232
+ * ```
233
+ */
234
+ getCookwareForVariant(options?: Pick<GetIngredientQuantitiesOptions, "choices">): Cookware[];
210
235
  /**
211
236
  * Parses a recipe from a string.
212
237
  * @param content - The recipe content to parse.
@@ -407,6 +432,8 @@ interface Metadata {
407
432
  * This stores the original value as written by the user.
408
433
  */
409
434
  unitSystem?: string;
435
+ /** The list of available variant names for this recipe. */
436
+ variants?: string[];
410
437
  /**
411
438
  * Index signature for additional metadata fields not explicitly typed.
412
439
  * Any metadata key in the frontmatter will be captured here.
@@ -567,6 +594,12 @@ interface Ingredient {
567
594
  /** The collection of potential additional metadata for the ingredient */
568
595
  extras?: IngredientExtras;
569
596
  }
597
+ /**
598
+ * Represents a quantity with extended unit and additional information
599
+ * about its scalability and potential equivalents
600
+ *
601
+ * @category Types
602
+ */
570
603
  type MaybeScalableQuantity = QuantityWithExtendedUnit & {
571
604
  /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
572
605
  scalable: boolean;
@@ -574,6 +607,15 @@ type MaybeScalableQuantity = QuantityWithExtendedUnit & {
574
607
  * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g. */
575
608
  equivalents?: QuantityWithExtendedUnit[];
576
609
  };
610
+ /**
611
+ * Defines a type containing an optional {@link QuantityWithExtendedUnit} with scalability and potential info about equivalents
612
+ *
613
+ * Used in {@link IngredientAlternative}
614
+ *
615
+ * @param T - The base type to which the optional quantity properties will be added.
616
+ *
617
+ * @category Types
618
+ */
577
619
  type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
578
620
  quantity?: undefined;
579
621
  scalable?: never;
@@ -581,8 +623,7 @@ type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
581
623
  equivalents?: never;
582
624
  });
583
625
  /**
584
- * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
585
- * to a specific ingredient and its corresponding quantity information.
626
+ * Base type of {@link IngredientAlternative}
586
627
  * @category Types
587
628
  */
588
629
  type IngredientAlternativeBase = {
@@ -597,6 +638,14 @@ type IngredientAlternativeBase = {
597
638
  * Can be useful for creating alternative selection UI elements with anchor links */
598
639
  itemId?: string;
599
640
  };
641
+ /**
642
+ * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
643
+ * to a specific ingredient and its corresponding quantity information.
644
+ *
645
+ * Used in {@link IngredientItem} and for the various maps of {@link RecipeAlternatives}
646
+ *
647
+ * @category Types
648
+ */
600
649
  type IngredientAlternative = WithOptionalQuantity<IngredientAlternativeBase>;
601
650
  /**
602
651
  * Represents an ingredient item in a recipe step.
@@ -644,6 +693,11 @@ interface RecipeAlternatives {
644
693
  * their own single-element subgroup.
645
694
  */
646
695
  ingredientGroups: Map<string, IngredientAlternative[][]>;
696
+ /**
697
+ * All variant names discovered in the recipe (from metadata, step tags,
698
+ * and section tags). Includes `*` if any step/section uses the default tag.
699
+ */
700
+ variants: string[];
647
701
  }
648
702
  /**
649
703
  * Represents the choices to apply when computing ingredient quantities.
@@ -655,6 +709,8 @@ interface RecipeChoices {
655
709
  ingredientItems?: Map<string, number>;
656
710
  /** Map of choices that can be made for Grouped Ingredient StepItem's */
657
711
  ingredientGroups?: Map<string, number>;
712
+ /** The selected variant name */
713
+ variant?: string;
658
714
  }
659
715
  /**
660
716
  * Options for the {@link Recipe.getIngredientQuantities | getIngredientQuantities()} method.
@@ -679,9 +735,9 @@ interface GetIngredientQuantitiesOptions {
679
735
  }
680
736
  /**
681
737
  * Represents a raw (unprocessed) group of quantities for a single ingredient.
682
- * Returned by {@link Recipe.getRawQuantityGroups | getRawQuantityGroups()},
683
- * these are the pre-addition quantities that can be fed directly into
684
- * {@link addEquivalentsAndSimplify} for cross-recipe aggregation.
738
+ * Returned by {@link Recipe.getRawQuantityGroups},
739
+ * these are the pre-addition quantities that are fed internally
740
+ * to another non-public helper function for cross-recipe aggregation.
685
741
  * @category Types
686
742
  */
687
743
  interface RawQuantityGroup {
@@ -782,6 +838,10 @@ interface Step {
782
838
  type: "step";
783
839
  /** The items in the step. */
784
840
  items: StepItem[];
841
+ /** Optional list of variant names this step belongs to */
842
+ variants?: string[];
843
+ /** Whether the step has been marked as optional ("[?]") */
844
+ optional?: boolean;
785
845
  }
786
846
  /**
787
847
  * Represents an item in a note (can be text or arbitrary scalable).
@@ -852,6 +912,9 @@ interface RecipeWithServings {
852
912
  type AddedRecipe = RecipeWithFactor | RecipeWithServings;
853
913
  /**
854
914
  * Options for adding a recipe to a shopping list
915
+ *
916
+ * Used in {@link ShoppingList.addRecipe}
917
+ *
855
918
  * @category Types
856
919
  */
857
920
  type AddedRecipeOptions = {
@@ -1857,6 +1920,81 @@ declare function isGroupedItem(item: IngredientItem): boolean;
1857
1920
  * ```
1858
1921
  */
1859
1922
  declare function isAlternativeSelected(recipe: Recipe, choices: RecipeChoices, item: IngredientItem, alternativeIndex?: number): boolean;
1923
+ /**
1924
+ * Determines if a section is active (should be displayed or processed) for a given variant.
1925
+ *
1926
+ * - Sections with no `variants` property are always active.
1927
+ * - When no variant is selected (default), sections tagged `[*]` are active,
1928
+ * and sections tagged with named variants are not.
1929
+ * - When a named variant is selected, sections whose `variants` array includes
1930
+ * that name are active.
1931
+ *
1932
+ * @param section - The Section to check
1933
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
1934
+ * @returns `true` if the section should be displayed
1935
+ * @category Helpers
1936
+ *
1937
+ * @example
1938
+ * ```typescript
1939
+ * const recipe = new Recipe(cooklangText);
1940
+ * for (const section of recipe.sections) {
1941
+ * if (isSectionActive(section, choices.variant)) {
1942
+ * // render section
1943
+ * }
1944
+ * }
1945
+ * ```
1946
+ */
1947
+ declare function isSectionActive(section: Section, variant?: string): boolean;
1948
+ /**
1949
+ * Determines if a step is active (should be displayed) for a given variant.
1950
+ *
1951
+ * - Steps with no `variants` property are always active.
1952
+ * - When no variant is selected (default), steps tagged `[*]` are active,
1953
+ * and steps tagged with named variants are not.
1954
+ * - When a named variant is selected, steps whose `variants` array includes
1955
+ * that name are active.
1956
+ *
1957
+ * @param step - The Step to check
1958
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
1959
+ * @returns `true` if the step should be displayed
1960
+ * @category Helpers
1961
+ *
1962
+ * @example
1963
+ * ```typescript
1964
+ * for (const item of section.content) {
1965
+ * if (item.type === 'step' && isStepActive(item, choices.variant)) {
1966
+ * // render step
1967
+ * }
1968
+ * }
1969
+ * ```
1970
+ */
1971
+ declare function isStepActive(step: Step, variant?: string): boolean;
1972
+ /**
1973
+ * Returns the effective choices for a recipe given a variant selection.
1974
+ *
1975
+ * When a named variant is active, this scans ingredient alternatives whose
1976
+ * `note` contains the variant name (case-insensitive substring match) and
1977
+ * returns a `RecipeChoices` object with auto-selected alternatives.
1978
+ *
1979
+ * For inline alternatives: auto-selects the first alternative whose note
1980
+ * matches the variant name.
1981
+ *
1982
+ * For grouped alternatives: auto-selects the first subgroup that has any
1983
+ * alternative whose note matches the variant name.
1984
+ *
1985
+ * @param recipe - The Recipe instance
1986
+ * @param variant - The active variant name, or `undefined`/`*` for defaults
1987
+ * @returns A `RecipeChoices` with the `variant` set and auto-selected alternatives
1988
+ * @category Helpers
1989
+ *
1990
+ * @example
1991
+ * ```typescript
1992
+ * const recipe = new Recipe(cooklangText);
1993
+ * const choices = getEffectiveChoices(recipe, "vegan");
1994
+ * const ingredients = recipe.getIngredientQuantities({ choices });
1995
+ * ```
1996
+ */
1997
+ declare function getEffectiveChoices(recipe: Recipe, variant?: string): RecipeChoices;
1860
1998
 
1861
1999
  /**
1862
2000
  * Type guard to check if an ingredient quantity-like object is an AND group.
@@ -1946,11 +2084,5 @@ declare class NoProductCatalogForCartError extends Error {
1946
2084
  declare class NoShoppingListForCartError extends Error {
1947
2085
  constructor();
1948
2086
  }
1949
- declare class NoTabAsIndentError extends Error {
1950
- constructor();
1951
- }
1952
- declare class BadIndentationError extends Error {
1953
- constructor();
1954
- }
1955
2087
 
1956
- 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 };
2088
+ 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 };