@tmlmt/cooklang-parser 3.0.0-alpha.21 → 3.0.0-alpha.22

package/dist/index.d.cts

@@ -509,7 +509,7 @@ interface IngredientExtras {
      * Used if: the ingredient is a recipe
      *
      * @example
-     * ```cooklang
+     * ```yaml
      * Take @./essentials/doughs/pizza dough{1} out of the freezer and let it unfreeze overnight
      * ```
      * Would lead to:
@@ -541,9 +541,12 @@ interface AlternativeIngredientRef {
 interface IngredientQuantityGroup extends QuantityWithPlainUnit {
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an AND group of quantities when primary units are incompatible but equivalents can be summed.
@@ -557,9 +560,12 @@ interface IngredientQuantityAndGroup extends FlatAndGroup<QuantityWithPlainUnit>
     equivalents?: QuantityWithPlainUnit[];
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an ingredient in a recipe.
@@ -1760,15 +1766,15 @@ declare function renderFractionAsVulgar(num: number, den: number): string;
  * Format a numeric value (decimal or fraction) to a string.
  *
  * @param value - The decimal or fraction value to format
- * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: false)
+ * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: true)
  * @returns The formatted string representation
  * @category Helpers
  *
  * @example
  * ```typescript
  * formatNumericValue({ type: "decimal", decimal: 1.5 }); // "1.5"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "1/2"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }, true); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }, false); // "1/2"
  * formatNumericValue({ type: "fraction", num: 5, den: 4 }, true); // "1¼"
  * ```
  */
@@ -1899,7 +1905,7 @@ declare function isGroupedItem(item: IngredientItem): boolean;
  * for (const item of step.items) {
  *   if (item.type === 'ingredient') {
  *     item.alternatives.forEach((alt, idx) => {
- *       const isSelected = isAlternativeSelected(item, idx, recipe, choices);
+ *       const isSelected = isAlternativeSelected(recipe, choices, item, idx);
  *       // Render differently based on isSelected
  *     });
  *   }
@@ -2033,15 +2039,18 @@ declare function isSimpleGroup(entry: IngredientQuantityGroup | IngredientQuanti
  * for (const entry of ingredient.quantities) {
  *   if (hasAlternatives(entry)) {
  *     // entry.alternatives is available and non-empty
- *     for (const alt of entry.alternatives) {
- *       console.log(`Alternative ingredient index: ${alt.index}`);
+ *     for (const subgroup of entry.alternatives) {
+ *       // Each subgroup is one "or" choice; items within are combined with "+"
+ *       for (const alt of subgroup) {
+ *         console.log(`Alternative ingredient index: ${alt.index}`);
+ *       }
  *     }
  *   }
  * }
  * ```
  */
 declare function hasAlternatives(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is (IngredientQuantityGroup | IngredientQuantityAndGroup) & {
-    alternatives: AlternativeIngredientRef[];
+    alternatives: AlternativeIngredientRef[][];
 };
 
 /**

package/dist/index.d.ts

@@ -509,7 +509,7 @@ interface IngredientExtras {
      * Used if: the ingredient is a recipe
      *
      * @example
-     * ```cooklang
+     * ```yaml
      * Take @./essentials/doughs/pizza dough{1} out of the freezer and let it unfreeze overnight
      * ```
      * Would lead to:
@@ -541,9 +541,12 @@ interface AlternativeIngredientRef {
 interface IngredientQuantityGroup extends QuantityWithPlainUnit {
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an AND group of quantities when primary units are incompatible but equivalents can be summed.
@@ -557,9 +560,12 @@ interface IngredientQuantityAndGroup extends FlatAndGroup<QuantityWithPlainUnit>
     equivalents?: QuantityWithPlainUnit[];
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an ingredient in a recipe.
@@ -1760,15 +1766,15 @@ declare function renderFractionAsVulgar(num: number, den: number): string;
  * Format a numeric value (decimal or fraction) to a string.
  *
  * @param value - The decimal or fraction value to format
- * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: false)
+ * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: true)
  * @returns The formatted string representation
  * @category Helpers
  *
  * @example
  * ```typescript
  * formatNumericValue({ type: "decimal", decimal: 1.5 }); // "1.5"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "1/2"
- * formatNumericValue({ type: "fraction", num: 1, den: 2 }, true); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }, false); // "1/2"
  * formatNumericValue({ type: "fraction", num: 5, den: 4 }, true); // "1¼"
  * ```
  */
@@ -1899,7 +1905,7 @@ declare function isGroupedItem(item: IngredientItem): boolean;
  * for (const item of step.items) {
  *   if (item.type === 'ingredient') {
  *     item.alternatives.forEach((alt, idx) => {
- *       const isSelected = isAlternativeSelected(item, idx, recipe, choices);
+ *       const isSelected = isAlternativeSelected(recipe, choices, item, idx);
  *       // Render differently based on isSelected
  *     });
  *   }
@@ -2033,15 +2039,18 @@ declare function isSimpleGroup(entry: IngredientQuantityGroup | IngredientQuanti
  * for (const entry of ingredient.quantities) {
  *   if (hasAlternatives(entry)) {
  *     // entry.alternatives is available and non-empty
- *     for (const alt of entry.alternatives) {
- *       console.log(`Alternative ingredient index: ${alt.index}`);
+ *     for (const subgroup of entry.alternatives) {
+ *       // Each subgroup is one "or" choice; items within are combined with "+"
+ *       for (const alt of subgroup) {
+ *         console.log(`Alternative ingredient index: ${alt.index}`);
+ *       }
  *     }
  *   }
  * }
  * ```
  */
 declare function hasAlternatives(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is (IngredientQuantityGroup | IngredientQuantityAndGroup) & {
-    alternatives: AlternativeIngredientRef[];
+    alternatives: AlternativeIngredientRef[][];
 };
 
 /**

package/dist/index.js

@@ -2033,7 +2033,7 @@ function unionOfSets(s1, s2) {
 }
 function getAlternativeSignature(alternatives) {
   if (!alternatives || alternatives.length === 0) return null;
-  return alternatives.map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
+  return alternatives.flat().map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
 }
 
 // src/classes/pantry.ts
@@ -3346,7 +3346,7 @@ var _Recipe = class _Recipe {
             const currentSubgroupIdx = groupSubgroups.findIndex(
               (sg) => sg.some((alt) => alt.itemId === item.id)
             );
-            alternativeRefs = groupSubgroups.filter((_, idx) => idx !== currentSubgroupIdx).flatMap(
+            alternativeRefs = groupSubgroups.filter((_, idx) => idx !== currentSubgroupIdx).map(
               (subgroup) => subgroup.map((otherAlt) => {
                 const ref = {
                   index: otherAlt.index
@@ -3385,7 +3385,7 @@ var _Recipe = class _Recipe {
                 };
                 ref.quantities = [altQty];
               }
-              return ref;
+              return [ref];
             });
           }
           const altIndices = getAlternativeSignature(alternativeRefs) ?? "";
@@ -3406,28 +3406,36 @@ var _Recipe = class _Recipe {
           if (!groupsForIng.has(signature)) {
             groupsForIng.set(signature, {
               quantities: [],
-              alternativeQuantities: /* @__PURE__ */ new Map()
+              alternativeQuantities: /* @__PURE__ */ new Map(),
+              alternativeSubgroups: []
             });
           }
           const group = groupsForIng.get(signature);
           group.quantities.push(quantityEntry);
-          for (const ref of alternativeRefs ?? []) {
-            if (!group.alternativeQuantities.has(ref.index)) {
-              group.alternativeQuantities.set(ref.index, []);
-            }
-            for (const altQty of ref.quantities ?? []) {
-              const extended = toExtendedUnit({
-                quantity: altQty.quantity,
-                unit: altQty.unit
-              });
-              if (altQty.equivalents?.length) {
-                const eqEntries = [
-                  extended,
-                  ...altQty.equivalents.map((eq) => toExtendedUnit(eq))
-                ];
-                group.alternativeQuantities.get(ref.index).push({ or: eqEntries });
-              } else {
-                group.alternativeQuantities.get(ref.index).push(extended);
+          if (alternativeRefs && alternativeRefs.length > 0 && group.alternativeSubgroups.length === 0) {
+            group.alternativeSubgroups = alternativeRefs.map(
+              (subgroup) => subgroup.map((ref) => ref.index)
+            );
+          }
+          for (const subgroup of alternativeRefs ?? []) {
+            for (const ref of subgroup) {
+              if (!group.alternativeQuantities.has(ref.index)) {
+                group.alternativeQuantities.set(ref.index, []);
+              }
+              for (const altQty of ref.quantities ?? []) {
+                const extended = toExtendedUnit({
+                  quantity: altQty.quantity,
+                  unit: altQty.unit
+                });
+                if (altQty.equivalents?.length) {
+                  const eqEntries = [
+                    extended,
+                    ...altQty.equivalents.map((eq) => toExtendedUnit(eq))
+                  ];
+                  group.alternativeQuantities.get(ref.index).push({ or: eqEntries });
+                } else {
+                  group.alternativeQuantities.get(ref.index).push(extended);
+                }
               }
             }
           }
@@ -3550,17 +3558,25 @@ var _Recipe = class _Recipe {
               this.unitSystem
             );
             const flattened = flattenPlainUnitGroup(summed);
-            const alternatives = group.alternativeQuantities.size > 0 ? [...group.alternativeQuantities].map(([altIdx, altQtys]) => ({
-              index: altIdx,
-              ...altQtys.length > 0 && {
-                quantities: flattenPlainUnitGroup(
-                  addEquivalentsAndSimplify(altQtys, this.unitSystem)
-                ).flatMap(
-                  /* v8 ignore next -- item.and branch requires complex nested AND-with-equivalents structure */
-                  (item) => "quantity" in item ? [item] : item.and
-                )
-              }
-            })) : void 0;
+            let alternatives;
+            if (group.alternativeSubgroups.length > 0) {
+              alternatives = group.alternativeSubgroups.map(
+                (subgroupIndices) => subgroupIndices.map((altIdx) => {
+                  const altQtys = group.alternativeQuantities.get(altIdx);
+                  return {
+                    index: altIdx,
+                    ...altQtys.length > 0 && {
+                      quantities: flattenPlainUnitGroup(
+                        addEquivalentsAndSimplify(altQtys, this.unitSystem)
+                      ).flatMap(
+                        /* v8 ignore next -- item.and branch requires complex nested AND-with-equivalents structure */
+                        (item) => "quantity" in item ? [item] : item.and
+                      )
+                    }
+                  };
+                })
+              );
+            }
             for (const gq of flattened) {
               if ("and" in gq) {
                 quantityGroups.push({