feat!: alternative units and ingredients (#80)

# Description

Introduction of alternative units and ingredients

Resolves: #66

Resolves: #69

## Type of change

Please delete options that are not relevant.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [x] This change requires a documentation update

Author: tmlmt

.gitignore

@@ -3,4 +3,5 @@ dist
 coverage
 docs/.vitepress/cache
 docs/.vitepress/dist
-docs/api
+docs/api
+.nuxt

docs/guide-extensions.md

@@ -96,12 +96,55 @@ When referencing ingredients, the added quantities will be converted to [Decimal
 ```
 
 Also works with Cookware and Timers
-  
+
 ## Cookware quantities
 
 - Cookware can also be quantified (without any unit, e.g. `#bowls{2}`)
 - Quantities will be added similarly as ingredients if cookware is referenced, e.g. `#&bowls{2}`
 
+## Alternative units
+
+You can define equivalent quantities in different units for the same ingredient using the pipe `|` separator within the curly braces.
+
+Usage: `@flour{100%g|3.5%oz}`
+
+This is useful for providing multiple units (e.g. metric and imperial) simultaneously for the same ingredient. The first unit is considered the primary unit.
+
+## Ingredient alternatives
+
+### Inline alternatives
+
+You can specify alternative ingredients directly in the ingredient syntax using pipes: `@baseName{quantity}|altName{altQuantity}[note]|...`
+
+This allows users to select from multiple alternatives when computing recipe quantities.
+
+Use cases:
+- `@milk{200%ml}|almond milk{100%ml}[vegan version]|soy milk{150%ml}[another vegan option]`
+- `@sugar{100%g}|brown sugar{100%g}[for a richer flavor]`
+
+When inline alternatives are defined, the recipe's [`choices`](/api/interfaces/RecipeChoices) property will be populated. You can then use the `calc_ingredient_quantities()` method to compute quantities corresponding to the user's choices.
+
+All modifiers (`&`, `-`, `?`) work with inline alternatives:
+`@&milk{200%ml}|-almond milk{100%ml}[vegan version]|?soy milk{150%ml}[another vegan option]`
+
+### Grouped alternatives
+
+Ingredients can also have alternatives by grouping them with the same group key using the syntax: `@|groupKey|ingredientName{}`
+
+This is useful when you want to provide alternative choices in your recipe text naturally:
+
+Use cases:
+- `Add @|milk|milk{200%ml} or @|milk|almond milk{100%ml} or @|milk|oat milk{150%ml} for a vegan version`
+- `Add some @|spices|salt{} or maybe some @|spices|pepper{}`
+
+When grouped alternatives are defined, the recipe's [`choices`](/api/interfaces/RecipeChoices) property will be populated with available alternatives for each group. You can then use the `calc_ingredient_quantities()` method to compute quantities corresponding to the user's choices.
+
+All modifiers (`&`, `-`, `?`) work with grouped alternatives:
+```
+Add @|flour|&flour tipo 00{100%g} or @|flour|flour tipo 1{50%g}
+Add @|spices|-salt{} or @|spices|?pepper{}
+```
+
 ## Ingredient aliases
 
 - `@ingredientName|displayAlias{}` will add the ingredient as "ingredientName" in the ingredients list, but will display is as "displayAlias" in the preparation step.

pnpm-workspace.yaml

@@ -2,4 +2,6 @@ packages:
   - .
 
 onlyBuiltDependencies:
+  - '@parcel/watcher'
   - esbuild
+  - vue-demi

src/classes/product_catalog.ts

@@ -3,13 +3,14 @@ import type {
   FixedNumericValue,
   ProductOption,
   ProductOptionToml,
+  ProductSize,
 } from "../types";
 import type { TomlTable } from "smol-toml";
 import {
   isPositiveIntegerString,
   parseQuantityInput,
   stringifyQuantityValue,
-} from "../parser_helpers";
+} from "../utils/parser_helpers";
 import { InvalidProductCatalogFormat } from "../errors";
 
 /**
@@ -76,27 +77,32 @@ export class ProductCatalog {
         const { name, size, price, ...rest } =
           productData as unknown as ProductOptionToml;
 
-        const sizeAndUnitRaw = size.split("%");
-        const sizeParsed = parseQuantityInput(
-          sizeAndUnitRaw[0]!,
-        ) as FixedNumericValue;
+        // Handle size as string or string[]
+        const sizeStrings = Array.isArray(size) ? size : [size];
+        const sizes: ProductSize[] = sizeStrings.map((sizeStr) => {
+          const sizeAndUnitRaw = sizeStr.split("%");
+          const sizeParsed = parseQuantityInput(
+            sizeAndUnitRaw[0]!,
+          ) as FixedNumericValue;
+          const productSize: ProductSize = { size: sizeParsed };
+          if (sizeAndUnitRaw.length > 1) {
+            productSize.unit = sizeAndUnitRaw[1]!;
+          }
+          return productSize;
+        });
 
         const productOption: ProductOption = {
           id: productId,
           productName: name,
           ingredientName: ingredientName,
           price: price,
-          size: sizeParsed,
+          sizes,
           ...rest,
         };
         if (aliases) {
           productOption.ingredientAliases = aliases;
         }
 
-        if (sizeAndUnitRaw.length > 1) {
-          productOption.unit = sizeAndUnitRaw[1]!;
-        }
-
         this.products.push(productOption);
       }
     }
@@ -116,8 +122,7 @@ export class ProductCatalog {
         id,
         ingredientName,
         ingredientAliases,
-        size,
-        unit,
+        sizes,
         productName,
         ...rest
       } = product;
@@ -127,12 +132,19 @@ export class ProductCatalog {
       if (ingredientAliases && !grouped[ingredientName].aliases) {
         grouped[ingredientName].aliases = ingredientAliases;
       }
+
+      // Stringify each size as "value%unit" or just "value"
+      const sizeStrings = sizes.map((s) =>
+        s.unit
+          ? `${stringifyQuantityValue(s.size)}%${s.unit}`
+          : stringifyQuantityValue(s.size),
+      );
+
       grouped[ingredientName][id] = {
         ...rest,
         name: productName,
-        size: unit
-          ? `${stringifyQuantityValue(size)}%${unit}`
-          : stringifyQuantityValue(size),
+        // Use array if multiple sizes, otherwise single string
+        size: sizeStrings.length === 1 ? sizeStrings[0]! : sizeStrings,
       };
     }
 
@@ -184,7 +196,11 @@ export class ProductCatalog {
           }
 
           const hasProductName = typeof record.name === "string";
-          const hasSize = typeof record.size === "string";
+          // Size can be a string or an array of strings
+          const hasSize =
+            typeof record.size === "string" ||
+            (Array.isArray(record.size) &&
+              record.size.every((s) => typeof s === "string"));
           const hasPrice = typeof record.price === "number";
 
           if (!(hasProductName && hasSize && hasPrice)) {