@tmlmt/cooklang-parser 3.0.0-alpha.10 → 3.0.0-alpha.11

package/dist/index.cjs

@@ -40,6 +40,7 @@ __export(index_exports, {
   Section: () => Section,
   ShoppingCart: () => ShoppingCart,
   ShoppingList: () => ShoppingList,
+  convertQuantityToSystem: () => convertQuantityToSystem,
   formatExtendedQuantity: () => formatExtendedQuantity,
   formatItemQuantity: () => formatItemQuantity,
   formatNumericValue: () => formatNumericValue,
@@ -51,7 +52,8 @@ __export(index_exports, {
   isAlternativeSelected: () => isAlternativeSelected,
   isAndGroup: () => isAndGroup,
   isGroupedItem: () => isGroupedItem,
-  isSimpleGroup: () => isSimpleGroup
+  isSimpleGroup: () => isSimpleGroup,
+  renderFractionAsVulgar: () => renderFractionAsVulgar
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -355,7 +357,8 @@ var units = [
     type: "mass",
     system: "metric",
     aliases: ["gram", "grams", "grammes"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   },
   {
     name: "kg",
@@ -364,20 +367,28 @@ var units = [
     aliases: ["kilogram", "kilograms", "kilogrammes", "kilos", "kilo"],
     toBase: 1e3
   },
-  // Mass (Imperial)
+  // Mass (US/UK - identical in both systems)
   {
     name: "oz",
     type: "mass",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["ounce", "ounces"],
-    toBase: 28.3495
+    toBase: 28.3495,
+    // default: US (same as UK)
+    toBaseBySystem: { US: 28.3495, UK: 28.3495 },
+    maxValue: 31,
+    // 16 oz = 1 lb, allow a bit more
+    fractions: { enabled: true, denominators: [2] }
   },
   {
     name: "lb",
     type: "mass",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["pound", "pounds"],
-    toBase: 453.592
+    toBase: 453.592,
+    // default: US (same as UK)
+    toBaseBySystem: { US: 453.592, UK: 453.592 },
+    fractions: { enabled: true, denominators: [2, 4] }
   },
   // Volume (Metric)
   {
@@ -385,21 +396,26 @@ var units = [
     type: "volume",
     system: "metric",
     aliases: ["milliliter", "milliliters", "millilitre", "millilitres", "cc"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   },
   {
     name: "cl",
     type: "volume",
     system: "metric",
     aliases: ["centiliter", "centiliters", "centilitre", "centilitres"],
-    toBase: 10
+    toBase: 10,
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "dl",
     type: "volume",
     system: "metric",
     aliases: ["deciliter", "deciliters", "decilitre", "decilitres"],
-    toBase: 100
+    toBase: 100,
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "l",
@@ -408,55 +424,102 @@ var units = [
     aliases: ["liter", "liters", "litre", "litres"],
     toBase: 1e3
   },
+  // Volume (JP)
+  {
+    name: "go",
+    type: "volume",
+    system: "JP",
+    aliases: ["gou", "goo", "\u5408", "rice cup"],
+    toBase: 180,
+    maxValue: 10
+  },
+  // Volume (Ambiguous: metric/US/UK)
   {
     name: "tsp",
     type: "volume",
-    system: "metric",
+    system: "ambiguous",
     aliases: ["teaspoon", "teaspoons"],
-    toBase: 5
+    toBase: 5,
+    // default: metric
+    toBaseBySystem: { metric: 5, US: 4.929, UK: 5.919, JP: 5 },
+    maxValue: 5,
+    // 3 tsp = 1 tbsp (but allow a bit more)
+    fractions: { enabled: true, denominators: [2, 3, 4, 8] }
   },
   {
     name: "tbsp",
     type: "volume",
-    system: "metric",
+    system: "ambiguous",
     aliases: ["tablespoon", "tablespoons"],
-    toBase: 15
+    toBase: 15,
+    // default: metric
+    toBaseBySystem: { metric: 15, US: 14.787, UK: 17.758, JP: 15 },
+    maxValue: 4,
+    // ~16 tbsp = 1 cup
+    fractions: { enabled: true }
   },
-  // Volume (Imperial)
+  // Volume (Ambiguous: US/UK only)
   {
     name: "fl-oz",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["fluid ounce", "fluid ounces"],
-    toBase: 29.5735
+    toBase: 29.5735,
+    // default: US
+    toBaseBySystem: { US: 29.5735, UK: 28.4131 },
+    maxValue: 15,
+    // 8 fl-oz ~ 1 cup, allow more
+    fractions: { enabled: true, denominators: [2] }
   },
   {
     name: "cup",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["cups"],
-    toBase: 236.588
+    toBase: 236.588,
+    // default: US
+    toBaseBySystem: { US: 236.588, UK: 284.131 },
+    maxValue: 15,
+    // upgrade to gallons above 15 cups
+    fractions: { enabled: true }
   },
   {
     name: "pint",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["pints"],
-    toBase: 473.176
+    toBase: 473.176,
+    // default: US
+    toBaseBySystem: { US: 473.176, UK: 568.261 },
+    maxValue: 3,
+    // 2 pints = 1 quart
+    fractions: { enabled: true, denominators: [2] },
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "quart",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["quarts"],
-    toBase: 946.353
+    toBase: 946.353,
+    // default: US
+    toBaseBySystem: { US: 946.353, UK: 1136.52 },
+    maxValue: 3,
+    // 4 quarts = 1 gallon
+    fractions: { enabled: true, denominators: [2] },
+    isBestUnit: false
+    // exists but not a "best" candidate
   },
   {
     name: "gallon",
     type: "volume",
-    system: "imperial",
+    system: "ambiguous",
     aliases: ["gallons"],
-    toBase: 3785.41
+    toBase: 3785.41,
+    // default: US
+    toBaseBySystem: { US: 3785.41, UK: 4546.09 },
+    fractions: { enabled: true, denominators: [2] }
   },
   // Count units (no conversion, but recognized as a type)
   {
@@ -464,7 +527,8 @@ var units = [
     type: "count",
     system: "metric",
     aliases: ["pieces", "pc"],
-    toBase: 1
+    toBase: 1,
+    maxValue: 999
   }
 ];
 var unitMap = /* @__PURE__ */ new Map();
@@ -488,8 +552,14 @@ function isNoUnit(unit) {
   return resolveUnit(unit.name).name === NO_UNIT;
 }
 
+// src/units/conversion.ts
+var import_big2 = __toESM(require("big.js"), 1);
+
 // src/quantities/numeric.ts
 var import_big = __toESM(require("big.js"), 1);
+var DEFAULT_DENOMINATORS = [2, 3, 4];
+var DEFAULT_FRACTION_ACCURACY = 0.05;
+var DEFAULT_MAX_WHOLE = 4;
 function gcd(a2, b) {
   return b === 0 ? a2 : gcd(b, a2 % b);
 }
@@ -510,6 +580,41 @@ function simplifyFraction(num, den) {
     return { type: "fraction", num: simplifiedNum, den: simplifiedDen };
   }
 }
+function approximateFraction(value, denominators = DEFAULT_DENOMINATORS, accuracy = DEFAULT_FRACTION_ACCURACY, maxWhole = DEFAULT_MAX_WHOLE) {
+  if (value <= 0 || !Number.isFinite(value)) {
+    return null;
+  }
+  const wholePart = Math.floor(value);
+  if (wholePart > maxWhole) {
+    return null;
+  }
+  const fractionalPart = value - wholePart;
+  if (fractionalPart < 1e-4) {
+    return null;
+  }
+  let bestFraction = null;
+  for (const den of denominators) {
+    const exactNum = value * den;
+    const roundedNum = Math.round(exactNum);
+    if (roundedNum === 0) continue;
+    const approximatedValue = roundedNum / den;
+    const relativeError = Math.abs(approximatedValue - value) / value;
+    if (relativeError <= accuracy) {
+      if (!bestFraction || relativeError < bestFraction.error) {
+        bestFraction = { num: roundedNum, den, error: relativeError };
+      }
+    }
+  }
+  if (!bestFraction) {
+    return null;
+  }
+  const commonDivisor = gcd(bestFraction.num, bestFraction.den);
+  return {
+    type: "fraction",
+    num: bestFraction.num / commonDivisor,
+    den: bestFraction.den / commonDivisor
+  };
+}
 function getNumericValue(v) {
   if (v.type === "decimal") {
     return v.decimal;
@@ -558,9 +663,35 @@ function addNumericValues(val1, val2) {
     };
   }
 }
-var toRoundedDecimal = (v) => {
+var toRoundedDecimal = (v, precision = 3) => {
   const value = v.type === "decimal" ? v.decimal : v.num / v.den;
-  return { type: "decimal", decimal: Math.round(value * 1e3) / 1e3 };
+  if (value === 0) {
+    return { type: "decimal", decimal: 0 };
+  }
+  const absValue = Math.abs(value);
+  if (absValue >= 1e3) {
+    return { type: "decimal", decimal: Math.round(value) };
+  }
+  const magnitude = Math.floor(Math.log10(absValue));
+  const scale = Math.pow(10, precision - 1 - magnitude);
+  const rounded = Math.round(value * scale) / scale;
+  return { type: "decimal", decimal: rounded };
+};
+var formatOutputValue = (value, unitDef, precision = 3) => {
+  if (unitDef.fractions?.enabled) {
+    const denominators = unitDef.fractions.denominators ?? DEFAULT_DENOMINATORS;
+    const maxWhole = unitDef.fractions.maxWhole ?? DEFAULT_MAX_WHOLE;
+    const fraction = approximateFraction(
+      value,
+      denominators,
+      DEFAULT_FRACTION_ACCURACY,
+      maxWhole
+    );
+    if (fraction) {
+      return fraction;
+    }
+  }
+  return toRoundedDecimal({ type: "decimal", decimal: value }, precision);
 };
 function multiplyQuantityValue(value, factor) {
   if (value.type === "fixed") {
@@ -594,6 +725,143 @@ function getAverageValue(q) {
   }
 }
 
+// src/units/compatibility.ts
+function areUnitsGroupable(u1, u2) {
+  if (u1.name === u2.name) {
+    return true;
+  }
+  if (u1.type === "other" || u2.type === "other") {
+    return false;
+  }
+  if (u1.type === u2.type && u1.system === u2.system) {
+    return true;
+  }
+  if (u1.type === u2.type) {
+    if (u1.system === "ambiguous" && u2.system === "metric" && u1.toBaseBySystem?.metric !== void 0) {
+      return true;
+    }
+    if (u2.system === "ambiguous" && u1.system === "metric" && u2.toBaseBySystem?.metric !== void 0) {
+      return true;
+    }
+  }
+  return false;
+}
+function areUnitsConvertible(u1, u2) {
+  if (u1.name === u2.name) return true;
+  if (u1.type === "other" || u2.type === "other") return false;
+  return u1.type === u2.type;
+}
+function isUnitCompatibleWithSystem(unit, system) {
+  if (unit.system === system) return true;
+  if (unit.system === "ambiguous") {
+    if (unit.toBaseBySystem) {
+      return system in unit.toBaseBySystem;
+    }
+    if (system === "metric") return true;
+  }
+  if (unit.system === "metric" && system === "JP") {
+    return true;
+  }
+  return false;
+}
+
+// src/units/conversion.ts
+var EPSILON = 0.01;
+var DEFAULT_MAX_VALUE = 999;
+function isCloseToInteger(value) {
+  return Math.abs(value - Math.round(value)) < EPSILON;
+}
+function getMaxValue(unit) {
+  return unit.maxValue ?? DEFAULT_MAX_VALUE;
+}
+function isValueInRange(value, unit) {
+  const maxValue = getMaxValue(unit);
+  if (value >= 1 && value <= maxValue) {
+    return true;
+  }
+  if (value > 0 && value < 1 && unit.fractions?.enabled) {
+    const denominators = unit.fractions.denominators ?? DEFAULT_DENOMINATORS;
+    const maxWhole = unit.fractions.maxWhole ?? DEFAULT_MAX_WHOLE;
+    const fraction = approximateFraction(
+      value,
+      denominators,
+      DEFAULT_FRACTION_ACCURACY,
+      maxWhole
+    );
+    return fraction !== null;
+  }
+  return false;
+}
+function findBestUnit(valueInBase, unitType, system, inputUnits) {
+  const inputUnitNames = new Set(inputUnits.map((u) => u.name));
+  const candidates = units.filter(
+    (u) => u.type === unitType && isUnitCompatibleWithSystem(u, system) && (u.isBestUnit !== false || inputUnitNames.has(u.name))
+  );
+  if (candidates.length === 0) {
+    const fallbackUnit = inputUnits[0];
+    return {
+      unit: fallbackUnit,
+      value: valueInBase / getToBase(fallbackUnit, system)
+    };
+  }
+  const candidatesWithValues = candidates.map((unit) => ({
+    unit,
+    value: valueInBase / getToBase(unit, system)
+  }));
+  const inRange = candidatesWithValues.filter(
+    (c) => isValueInRange(c.value, c.unit)
+  );
+  if (inRange.length > 0) {
+    const integersInInputFamily = inRange.filter(
+      (c) => isCloseToInteger(c.value) && inputUnitNames.has(c.unit.name)
+    );
+    if (integersInInputFamily.length > 0) {
+      return integersInInputFamily.sort((a2, b) => a2.value - b.value)[0];
+    }
+    const integersAny = inRange.filter((c) => isCloseToInteger(c.value));
+    if (integersAny.length > 0) {
+      return integersAny.sort((a2, b) => a2.value - b.value)[0];
+    }
+    return inRange.sort((a2, b) => {
+      const aInFamily = inputUnitNames.has(a2.unit.name) ? 0 : 1;
+      const bInFamily = inputUnitNames.has(b.unit.name) ? 0 : 1;
+      if (aInFamily !== bInFamily) return aInFamily - bInFamily;
+      return a2.value - b.value;
+    })[0];
+  }
+  return candidatesWithValues.sort((a2, b) => {
+    const aMaxValue = getMaxValue(a2.unit);
+    const bMaxValue = getMaxValue(b.unit);
+    const aDistance = a2.value < 1 ? 1 - a2.value : a2.value - aMaxValue;
+    const bDistance = b.value < 1 ? 1 - b.value : b.value - bMaxValue;
+    return aDistance - bDistance;
+  })[0];
+}
+function getUnitRatio(q1, q2) {
+  const q1Value = getAverageValue(q1.quantity);
+  const q2Value = getAverageValue(q2.quantity);
+  const factor = "toBase" in q1.unit && "toBase" in q2.unit ? q1.unit.toBase / q2.unit.toBase : 1;
+  if (typeof q1Value !== "number" || typeof q2Value !== "number") {
+    throw Error(
+      "One of both values is not a number, so a ratio cannot be computed"
+    );
+  }
+  return (0, import_big2.default)(q1Value).times(factor).div(q2Value);
+}
+function getBaseUnitRatio(q, qRef) {
+  if ("toBase" in q.unit && "toBase" in qRef.unit) {
+    return q.unit.toBase / qRef.unit.toBase;
+  } else {
+    return 1;
+  }
+}
+function getToBase(unit, system) {
+  if (unit.system === "ambiguous" && system && unit.toBaseBySystem) {
+    return unit.toBaseBySystem[system] ?? unit.toBase;
+  }
+  return unit.toBase;
+}
+
 // src/errors.ts
 var ReferencedItemCannotBeRedefinedError = class extends Error {
   constructor(item_type, item_name, new_modifier) {
@@ -732,11 +1000,6 @@ function normalizeAllUnits(q) {
     return newQ;
   }
 }
-var convertQuantityValue = (value, def, targetDef) => {
-  if (def.name === targetDef.name) return value;
-  const factor = def.toBase / targetDef.toBase;
-  return multiplyQuantityValue(value, factor);
-};
 function getDefaultQuantityValue() {
   return { type: "fixed", value: { type: "decimal", decimal: 0 } };
 }
@@ -763,7 +1026,7 @@ function addQuantityValues(v1, v2) {
   );
   return { type: "range", min: newMin, max: newMax };
 }
-function addQuantities(q1, q2) {
+function addQuantities(q1, q2, system) {
   const v1 = q1.quantity;
   const v2 = q2.quantity;
   if (v1.type === "fixed" && v1.value.type === "text" || v2.type === "fixed" && v2.value.type === "text") {
@@ -781,35 +1044,129 @@ function addQuantities(q1, q2) {
   if ((q2.unit?.name === "" || q2.unit === void 0) && q1.unit !== void 0) {
     return addQuantityValuesAndSetUnit(v1, v2, q1.unit);
   }
-  if (!q1.unit && !q2.unit || q1.unit && q2.unit && q1.unit.name.toLowerCase() === q2.unit.name.toLowerCase()) {
+  if (!q1.unit && !q2.unit) {
+    return addQuantityValuesAndSetUnit(v1, v2, q1.unit);
+  }
+  if (q1.unit && q2.unit && q1.unit.name.toLowerCase() === q2.unit.name.toLowerCase()) {
+    if (unit1Def) {
+      const effectiveSystem = system ?? (["metric", "JP"].includes(unit1Def.system) ? unit1Def.system : "US");
+      return addAndFindBestUnit(v1, v2, unit1Def, unit1Def, effectiveSystem, [
+        unit1Def
+      ]);
+    }
     return addQuantityValuesAndSetUnit(v1, v2, q1.unit);
   }
   if (unit1Def && unit2Def) {
-    if (unit1Def.type !== unit2Def.type) {
+    if (!areUnitsConvertible(unit1Def, unit2Def)) {
       throw new IncompatibleUnitsError(
         `${unit1Def.type} (${q1.unit?.name})`,
         `${unit2Def.type} (${q2.unit?.name})`
       );
     }
-    let targetUnitDef;
-    if (unit1Def.system !== unit2Def.system) {
-      const metricUnitDef = unit1Def.system === "metric" ? unit1Def : unit2Def;
-      targetUnitDef = units.filter((u) => u.type === metricUnitDef.type && u.system === "metric").reduce(
-        (prev, current) => prev.toBase > current.toBase ? prev : current
-      );
-    } else {
-      targetUnitDef = unit1Def.toBase >= unit2Def.toBase ? unit1Def : unit2Def;
+    let effectiveSystem = system;
+    if (!effectiveSystem) {
+      if (unit1Def.system === "metric" || unit2Def.system === "metric") {
+        effectiveSystem = "metric";
+      } else {
+        if (unit1Def.system === "JP" && unit2Def.system === "JP") {
+          effectiveSystem = "JP";
+        } else {
+          const unit1SupportsUS = unit1Def.system === "US" || unit1Def.system === "ambiguous" && unit1Def.toBaseBySystem && "US" in unit1Def.toBaseBySystem;
+          const unit2SupportsUS = unit2Def.system === "US" || unit2Def.system === "ambiguous" && unit2Def.toBaseBySystem && "US" in unit2Def.toBaseBySystem;
+          effectiveSystem = unit1SupportsUS && unit2SupportsUS ? "US" : "metric";
+        }
+      }
     }
-    const convertedV1 = convertQuantityValue(v1, unit1Def, targetUnitDef);
-    const convertedV2 = convertQuantityValue(v2, unit2Def, targetUnitDef);
-    const targetUnit = { name: targetUnitDef.name };
-    return addQuantityValuesAndSetUnit(convertedV1, convertedV2, targetUnit);
+    return addAndFindBestUnit(v1, v2, unit1Def, unit2Def, effectiveSystem, [
+      unit1Def,
+      unit2Def
+    ]);
   }
   throw new IncompatibleUnitsError(
     q1.unit?.name,
     q2.unit?.name
   );
 }
+function addAndFindBestUnit(v1, v2, unit1Def, unit2Def, system, inputUnits) {
+  const toBase1 = getToBase(unit1Def, system);
+  const toBase2 = getToBase(unit2Def, system);
+  let sumInBase;
+  if (v1.type === "fixed" && v2.type === "fixed") {
+    const val1 = getNumericValue(v1.value);
+    const val2 = getNumericValue(v2.value);
+    sumInBase = val1 * toBase1 + val2 * toBase2;
+  } else {
+    const avg1 = getAverageValue(v1);
+    const avg2 = getAverageValue(v2);
+    sumInBase = avg1 * toBase1 + avg2 * toBase2;
+  }
+  const { unit: bestUnit, value: bestValue } = findBestUnit(
+    sumInBase,
+    unit1Def.type,
+    system,
+    inputUnits
+  );
+  const formattedValue = formatOutputValue(bestValue, bestUnit);
+  if (v1.type === "range" || v2.type === "range") {
+    const r1 = v1.type === "range" ? v1 : { type: "range", min: v1.value, max: v1.value };
+    const r2 = v2.type === "range" ? v2 : { type: "range", min: v2.value, max: v2.value };
+    const minInBase = getNumericValue(r1.min) * toBase1 + getNumericValue(r2.min) * toBase2;
+    const maxInBase = getNumericValue(r1.max) * toBase1 + getNumericValue(r2.max) * toBase2;
+    const bestToBase = getToBase(bestUnit, system);
+    const minValue = minInBase / bestToBase;
+    const maxValue = maxInBase / bestToBase;
+    return {
+      quantity: {
+        type: "range",
+        min: formatOutputValue(minValue, bestUnit),
+        max: formatOutputValue(maxValue, bestUnit)
+      },
+      unit: { name: bestUnit.name }
+    };
+  }
+  return {
+    quantity: { type: "fixed", value: formattedValue },
+    unit: { name: bestUnit.name }
+  };
+}
+function convertQuantityToSystem(quantity, system) {
+  const unitDef = resolveUnit(
+    typeof quantity.unit === "string" ? quantity.unit : quantity.unit?.name
+  );
+  if (unitDef.type === "other" || !("toBase" in unitDef)) {
+    return void 0;
+  }
+  const avgValue = getAverageValue(quantity.quantity);
+  if (typeof avgValue !== "number") {
+    return void 0;
+  }
+  const toBase = getToBase(unitDef, system);
+  const valueInBase = avgValue * toBase;
+  const { unit: bestUnit, value: bestValue } = findBestUnit(
+    valueInBase,
+    unitDef.type,
+    system,
+    [unitDef]
+  );
+  const formattedValue = formatOutputValue(bestValue, bestUnit);
+  if (quantity.quantity.type === "range") {
+    const bestToBase = getToBase(bestUnit, system);
+    const minValue = getNumericValue(quantity.quantity.min) * toBase / bestToBase;
+    const maxValue = getNumericValue(quantity.quantity.max) * toBase / bestToBase;
+    return {
+      quantity: {
+        type: "range",
+        min: formatOutputValue(minValue, bestUnit),
+        max: formatOutputValue(maxValue, bestUnit)
+      },
+      unit: { name: bestUnit.name }
+    };
+  }
+  return {
+    quantity: { type: "fixed", value: formattedValue },
+    unit: { name: bestUnit.name }
+  };
+}
 function toPlainUnit(quantity) {
   if (isQuantity(quantity))
     return quantity.unit ? { ...quantity, unit: quantity.unit.name } : quantity;
@@ -916,6 +1273,53 @@ var flattenPlainUnitGroup = (summed) => {
     ];
   }
 };
+function applyBestUnit(q, system) {
+  if (!q.unit?.name) {
+    return q;
+  }
+  const unitDef = resolveUnit(q.unit.name);
+  if (unitDef.type === "other") {
+    return q;
+  }
+  if (q.quantity.type === "fixed" && q.quantity.value.type === "text") {
+    return q;
+  }
+  const avgValue = getAverageValue(q.quantity);
+  const effectiveSystem = system ?? (["metric", "JP"].includes(unitDef.system) ? unitDef.system : "US");
+  const toBase = getToBase(unitDef, effectiveSystem);
+  const valueInBase = avgValue * toBase;
+  const { unit: bestUnit, value: bestValue } = findBestUnit(
+    valueInBase,
+    unitDef.type,
+    effectiveSystem,
+    [unitDef]
+  );
+  const originalCanonicalName = normalizeUnit(q.unit.name)?.name;
+  if (bestUnit.name === originalCanonicalName) {
+    return q;
+  }
+  const formattedValue = formatOutputValue(bestValue, bestUnit);
+  if (q.quantity.type === "range") {
+    const bestToBase = getToBase(bestUnit, effectiveSystem);
+    const minValue = getNumericValue(q.quantity.min) * toBase / bestToBase;
+    const maxValue = getNumericValue(q.quantity.max) * toBase / bestToBase;
+    return {
+      quantity: {
+        type: "range",
+        min: formatOutputValue(minValue, bestUnit),
+        max: formatOutputValue(maxValue, bestUnit)
+      },
+      unit: { name: bestUnit.name }
+    };
+  }
+  return {
+    quantity: {
+      type: "fixed",
+      value: formattedValue
+    },
+    unit: { name: bestUnit.name }
+  };
+}
 
 // src/utils/parser_helpers.ts
 function flushPendingNote(section, noteItems) {
@@ -1119,6 +1523,18 @@ function extractMetadata(content) {
     const stringMetaValue = parseSimpleMetaVar(metadataContent, metaVar);
     if (stringMetaValue) metadata[metaVar] = stringMetaValue;
   }
+  let unitSystem;
+  const unitSystemRaw = parseSimpleMetaVar(metadataContent, "unit system");
+  if (unitSystemRaw) {
+    metadata["unit system"] = unitSystemRaw;
+    const unitSystemMap = {
+      metric: "metric",
+      us: "US",
+      uk: "UK",
+      jp: "JP"
+    };
+    unitSystem = unitSystemMap[unitSystemRaw.toLowerCase()];
+  }
   for (const metaVar of ["serves", "yield", "servings"]) {
     const scalingMetaValue = parseScalingMetaVar(metadataContent, metaVar);
     if (scalingMetaValue && scalingMetaValue[1]) {
@@ -1130,7 +1546,7 @@ function extractMetadata(content) {
     const listMetaValue = parseListMetaVar(metadataContent, metaVar);
     if (listMetaValue) metadata[metaVar] = listMetaValue;
   }
-  return { metadata, servings };
+  return { metadata, servings, unitSystem };
 }
 function isPositiveIntegerString(str) {
   return /^\d+$/.test(str);
@@ -1313,44 +1729,14 @@ var Section = class {
 // src/quantities/alternatives.ts
 var import_big3 = __toESM(require("big.js"), 1);
 
-// src/units/conversion.ts
-var import_big2 = __toESM(require("big.js"), 1);
-function getUnitRatio(q1, q2) {
-  const q1Value = getAverageValue(q1.quantity);
-  const q2Value = getAverageValue(q2.quantity);
-  const factor = "toBase" in q1.unit && "toBase" in q2.unit ? q1.unit.toBase / q2.unit.toBase : 1;
-  if (typeof q1Value !== "number" || typeof q2Value !== "number") {
-    throw Error(
-      "One of both values is not a number, so a ratio cannot be computed"
-    );
-  }
-  return (0, import_big2.default)(q1Value).times(factor).div(q2Value);
-}
-function getBaseUnitRatio(q, qRef) {
-  if ("toBase" in q.unit && "toBase" in qRef.unit) {
-    return q.unit.toBase / qRef.unit.toBase;
-  } else {
-    return 1;
-  }
-}
-
 // src/units/lookup.ts
-function areUnitsCompatible(u1, u2) {
-  if (u1.name === u2.name) {
-    return true;
-  }
-  if (u1.type !== "other" && u1.type === u2.type && u1.system === u2.system) {
-    return true;
-  }
-  return false;
-}
 function findListWithCompatibleQuantity(list, quantity) {
   const quantityWithUnitDef = {
     ...quantity,
     unit: resolveUnit(quantity.unit?.name)
   };
   return list.find(
-    (l) => l.some((lq) => areUnitsCompatible(lq.unit, quantityWithUnitDef.unit))
+    (l) => l.some((lq) => areUnitsGroupable(lq.unit, quantityWithUnitDef.unit))
   );
 }
 function findCompatibleQuantityWithinList(list, quantity) {
@@ -1407,11 +1793,9 @@ function getEquivalentUnitsLists(...quantities) {
   });
   function findLinkIndexForUnits(lists, unitsToCheck) {
     return lists.findIndex((l) => {
-      const listItem = l.map((q) => resolveUnit(q.unit?.name));
+      const listItems = l.map((q) => resolveUnit(q.unit?.name));
       return unitsToCheck.some(
-        (u) => listItem.some(
-          (lu) => lu.name === u?.name || lu.system === u?.system && lu.type === u?.type && lu.type !== "other"
-        )
+        (u) => u && listItems.some((lu) => areUnitsGroupable(lu, u))
       );
     });
   }
@@ -1423,16 +1807,18 @@ function getEquivalentUnitsLists(...quantities) {
         unit: resolveUnit(v.unit?.name, v.unit?.integerProtected)
       };
       const commonQuantity = og.or.find(
-        (q) => isQuantity(q) && areUnitsCompatible(q.unit, normalizedV.unit)
+        (q) => isQuantity(q) && areUnitsGroupable(q.unit, normalizedV.unit)
       );
       if (commonQuantity) {
         acc.push(normalizedV);
-        unitRatio = getUnitRatio(normalizedV, commonQuantity);
+        if (!unitRatio) {
+          unitRatio = getUnitRatio(normalizedV, commonQuantity);
+        }
       }
       return acc;
     }, []);
     for (const newQ of og.or) {
-      if (commonUnitList.some((q) => areUnitsCompatible(q.unit, newQ.unit))) {
+      if (commonUnitList.some((q) => areUnitsGroupable(q.unit, newQ.unit))) {
         continue;
       } else {
         const scaledQuantity = multiplyQuantityValue(newQ.quantity, unitRatio);
@@ -1549,7 +1935,7 @@ function reduceOrsToFirstEquivalent(unitList, quantities) {
     return reduceToQuantity(qListModified[0]);
   });
 }
-function addQuantitiesOrGroups(...quantities) {
+function addQuantitiesOrGroups(quantities, system) {
   if (quantities.length === 0)
     return {
       sum: {
@@ -1579,7 +1965,7 @@ function addQuantitiesOrGroups(...quantities) {
         unit: resolveUnit(nextQ.unit?.name)
       });
     } else {
-      const sumQ = addQuantities(existingQ, nextQ);
+      const sumQ = addQuantities(existingQ, nextQ, system);
       existingQ.quantity = sumQ.quantity;
       existingQ.unit = resolveUnit(sumQ.unit?.name);
     }
@@ -1589,7 +1975,7 @@ function addQuantitiesOrGroups(...quantities) {
   }
   return { sum: { and: sum }, unitsLists };
 }
-function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
+function regroupQuantitiesAndExpandEquivalents(sum, unitsLists, system) {
   const sumQuantities = isAndGroup(sum) ? sum.and : [sum];
   const result = [];
   const processedQuantities = /* @__PURE__ */ new Set();
@@ -1617,9 +2003,19 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
       }
       return main.reduce((acc, v) => {
         const mainInList = findCompatibleQuantityWithinList(list, v);
+        const conversionRatio = getBaseUnitRatio(v, mainInList);
+        const valueInOriginalUnit = (0, import_big3.default)(getAverageValue(v.quantity)).times(
+          conversionRatio
+        );
         const newValue = {
           quantity: multiplyQuantityValue(
-            v.quantity,
+            {
+              type: "fixed",
+              value: {
+                type: "decimal",
+                decimal: valueInOriginalUnit.toNumber()
+              }
+            },
             (0, import_big3.default)(getAverageValue(equiv.quantity)).div(
               getAverageValue(mainInList.quantity)
             )
@@ -1628,7 +2024,7 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
         if (equiv.unit && !isNoUnit(equiv.unit)) {
           newValue.unit = { name: equiv.unit.name };
         }
-        return addQuantities(acc, newValue);
+        return addQuantities(acc, newValue, system);
       }, initialValue);
     });
     if (main.length + equivalents.length > 1) {
@@ -1645,12 +2041,16 @@ function regroupQuantitiesAndExpandEquivalents(sum, unitsLists) {
   sumQuantities.filter((q) => !processedQuantities.has(q)).forEach((q) => result.push(deNormalizeQuantity(q)));
   return result;
 }
-function addEquivalentsAndSimplify(...quantities) {
+function addEquivalentsAndSimplify(quantities, system) {
   if (quantities.length === 1) {
     return toPlainUnit(quantities[0]);
   }
-  const { sum, unitsLists } = addQuantitiesOrGroups(...quantities);
-  const regrouped = regroupQuantitiesAndExpandEquivalents(sum, unitsLists);
+  const { sum, unitsLists } = addQuantitiesOrGroups(quantities, system);
+  const regrouped = regroupQuantitiesAndExpandEquivalents(
+    sum,
+    unitsLists,
+    system
+  );
   if (regrouped.length === 1) {
     return toPlainUnit(regrouped[0]);
   } else {
@@ -1710,6 +2110,15 @@ var _Recipe = class _Recipe {
       this.parse(content);
     }
   }
+  /**
+   * Gets the unit system specified in the recipe metadata.
+   * Used for resolving ambiguous units like tsp, tbsp, cup, etc.
+   *
+   * @returns The unit system if specified, or undefined to use defaults
+   */
+  get unitSystem() {
+    return _Recipe.unitSystems.get(this);
+  }
   /**
    * Gets the current item count for this recipe.
    */
@@ -2222,13 +2631,16 @@ var _Recipe = class _Recipe {
         if (groupsForIng) {
           const quantityGroups = [];
           for (const [, group] of groupsForIng) {
-            const summed = addEquivalentsAndSimplify(...group.quantities);
+            const summed = addEquivalentsAndSimplify(
+              group.quantities,
+              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)
+                  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
@@ -2267,9 +2679,10 @@ var _Recipe = class _Recipe {
    */
   parse(content) {
     const cleanContent = content.replace(metadataRegex, "").replace(commentRegex, "").replace(blockCommentRegex, "").trim().split(/\r\n?|\n/);
-    const { metadata, servings } = extractMetadata(content);
+    const { metadata, servings, unitSystem } = extractMetadata(content);
     this.metadata = metadata;
     this.servings = servings;
+    if (unitSystem) _Recipe.unitSystems.set(this, unitSystem);
     let blankLineBefore = true;
     let section = new Section();
     const items = [];
@@ -2427,6 +2840,7 @@ var _Recipe = class _Recipe {
     if (originalServings === void 0 || originalServings === 0) {
       originalServings = 1;
     }
+    const unitSystem = this.unitSystem;
     function scaleAlternativesBy(alternatives, factor2) {
       for (const alternative of alternatives) {
         if (alternative.itemQuantity) {
@@ -2454,6 +2868,20 @@ var _Recipe = class _Recipe {
               }
             );
           }
+          const optimizedPrimary = applyBestUnit(
+            {
+              quantity: alternative.itemQuantity.quantity,
+              unit: alternative.itemQuantity.unit
+            },
+            unitSystem
+          );
+          alternative.itemQuantity.quantity = optimizedPrimary.quantity;
+          alternative.itemQuantity.unit = optimizedPrimary.unit;
+          if (alternative.itemQuantity.equivalents) {
+            alternative.itemQuantity.equivalents = alternative.itemQuantity.equivalents.map(
+              (eq) => applyBestUnit(eq, unitSystem)
+            );
+          }
         }
       }
     }
@@ -2514,6 +2942,139 @@ var _Recipe = class _Recipe {
     }
     return newRecipe;
   }
+  /**
+   * Converts all ingredient quantities in the recipe to a target unit system.
+   *
+   * @param system - The target unit system to convert to (metric, US, UK, JP)
+   * @param method - How to handle existing quantities:
+   *   - "keep": Keep all existing equivalents (swap if needed, or add converted)
+   *   - "replace": Replace primary with target system quantity, discard equivalent used for conversion
+   *   - "remove": Only keep target system quantity, delete all equivalents
+   * @returns A new Recipe instance with converted quantities
+   *
+   * @example
+   * ```typescript
+   * // Convert a recipe to metric, keeping original units as equivalents
+   * const metricRecipe = recipe.convertTo("metric", "keep");
+   *
+   * // Convert to US units, removing all other equivalents
+   * const usRecipe = recipe.convertTo("US", "remove");
+   * ```
+   */
+  convertTo(system, method) {
+    const newRecipe = this.clone();
+    function buildNewPrimary(convertedQty, oldPrimary, remainingEquivalents, scalable, integerProtected, source) {
+      const newUnit = integerProtected && convertedQty.unit ? { name: convertedQty.unit.name, integerProtected: true } : convertedQty.unit;
+      const newPrimary = {
+        quantity: convertedQty.quantity,
+        unit: newUnit,
+        scalable
+      };
+      if (method === "remove") {
+        return newPrimary;
+      } else if (method === "replace") {
+        if (remainingEquivalents.length > 0) {
+          newPrimary.equivalents = remainingEquivalents;
+          if (source === "converted") newPrimary.equivalents.push(oldPrimary);
+        }
+      } else {
+        newPrimary.equivalents = [oldPrimary, ...remainingEquivalents];
+      }
+      return newPrimary;
+    }
+    function convertItemQuantity(itemQuantity) {
+      const primaryUnit = resolveUnit(itemQuantity.unit?.name);
+      const equivalents = itemQuantity.equivalents ?? [];
+      const oldPrimary = {
+        quantity: itemQuantity.quantity,
+        unit: itemQuantity.unit
+      };
+      if (primaryUnit.type !== "other" && isUnitCompatibleWithSystem(primaryUnit, system)) {
+        if (method === "remove") {
+          return { ...itemQuantity, equivalents: void 0 };
+        }
+        return itemQuantity;
+      }
+      const targetEquivIndex = equivalents.findIndex((eq) => {
+        const eqUnit = resolveUnit(eq.unit?.name);
+        return eqUnit.type !== "other" && isUnitCompatibleWithSystem(eqUnit, system);
+      });
+      if (targetEquivIndex !== -1) {
+        const targetEquiv = equivalents[targetEquivIndex];
+        const remainingEquivalents = equivalents.filter(
+          (_, i2) => i2 !== targetEquivIndex
+        );
+        return buildNewPrimary(
+          targetEquiv,
+          oldPrimary,
+          remainingEquivalents,
+          itemQuantity.scalable,
+          targetEquiv.unit?.integerProtected,
+          "swapped"
+        );
+      }
+      const converted = convertQuantityToSystem(oldPrimary, system);
+      if (converted && converted.unit) {
+        return buildNewPrimary(
+          converted,
+          oldPrimary,
+          equivalents,
+          itemQuantity.scalable,
+          itemQuantity.unit?.integerProtected,
+          "swapped"
+        );
+      }
+      for (let i2 = 0; i2 < equivalents.length; i2++) {
+        const equiv = equivalents[i2];
+        const convertedEquiv = convertQuantityToSystem(equiv, system);
+        if (convertedEquiv && convertedEquiv.unit) {
+          const remainingEquivalents = method === "keep" ? equivalents : equivalents.filter((_, idx) => idx !== i2);
+          return buildNewPrimary(
+            convertedEquiv,
+            oldPrimary,
+            remainingEquivalents,
+            itemQuantity.scalable,
+            equiv.unit?.integerProtected,
+            "converted"
+          );
+        }
+      }
+      if (method === "remove") {
+        return { ...itemQuantity, equivalents: void 0 };
+      } else {
+        return itemQuantity;
+      }
+    }
+    function convertAlternatives(alternatives) {
+      for (const alternative of alternatives) {
+        if (alternative.itemQuantity) {
+          alternative.itemQuantity = convertItemQuantity(
+            alternative.itemQuantity
+          );
+        }
+      }
+    }
+    for (const section of newRecipe.sections) {
+      for (const step of section.content.filter(
+        (item) => item.type === "step"
+      )) {
+        for (const item of step.items.filter(
+          (item2) => item2.type === "ingredient"
+        )) {
+          convertAlternatives(item.alternatives);
+        }
+      }
+    }
+    for (const alternatives of newRecipe.choices.ingredientGroups.values()) {
+      convertAlternatives(alternatives);
+    }
+    for (const alternatives of newRecipe.choices.ingredientItems.values()) {
+      convertAlternatives(alternatives);
+    }
+    newRecipe._populate_ingredient_quantities();
+    if (method !== "keep") _Recipe.unitSystems.set(newRecipe, system);
+    return newRecipe;
+  }
   /**
    * Gets the number of servings for the recipe.
    * @private
@@ -2547,6 +3108,11 @@ var _Recipe = class _Recipe {
     return newRecipe;
   }
 };
+/**
+ * External storage for unit system (not a property on instances).
+ * Used for resolving ambiguous units during quantity addition.
+ */
+__publicField(_Recipe, "unitSystems", /* @__PURE__ */ new WeakMap());
 /**
  * External storage for item count (not a property on instances).
  * Used for giving ID numbers to items during parsing.
@@ -2598,10 +3164,10 @@ var ShoppingList = class {
             existing.quantityTotal
           );
           const existingQuantities = isAndGroup(existingQuantityTotalExtended) ? existingQuantityTotalExtended.and : [existingQuantityTotalExtended];
-          existing.quantityTotal = addEquivalentsAndSimplify(
+          existing.quantityTotal = addEquivalentsAndSimplify([
             ...existingQuantities,
             ...newQuantities
-          );
+          ]);
           return;
         } catch {
         }
@@ -2652,7 +3218,7 @@ var ShoppingList = class {
               (q) => extendAllUnits(q)
             );
             const totalQuantity = addEquivalentsAndSimplify(
-              ...extendedQuantities
+              extendedQuantities
             );
             addIngredientQuantity(ingredient.name, totalQuantity);
           }
@@ -2948,12 +3514,12 @@ var ShoppingCart = class {
           alternative.quantity = scaledQuantity;
           const matchOptions = normalizedOptions2.filter(
             (option) => option.sizes.some(
-              (s) => areUnitsCompatible(alternative.unit, s.unit)
+              (s) => areUnitsGroupable(alternative.unit, s.unit)
             )
           );
           if (matchOptions.length > 0) {
             const findCompatibleSize = (option) => option.sizes.find(
-              (s) => areUnitsCompatible(alternative.unit, s.unit)
+              (s) => areUnitsGroupable(alternative.unit, s.unit)
             );
             if (matchOptions.length == 1) {
               const matchedOption = matchOptions[0];
@@ -3055,10 +3621,37 @@ var ShoppingCart = class {
 };
 
 // src/utils/render_helpers.ts
-function formatNumericValue(value) {
+var VULGAR_FRACTIONS = {
+  "1/2": "\xBD",
+  "1/3": "\u2153",
+  "2/3": "\u2154",
+  "1/4": "\xBC",
+  "3/4": "\xBE",
+  "1/8": "\u215B",
+  "3/8": "\u215C",
+  "5/8": "\u215D",
+  "7/8": "\u215E"
+};
+function renderFractionAsVulgar(num, den) {
+  const wholePart = Math.floor(num / den);
+  const remainder = num % den;
+  if (remainder === 0) {
+    return String(wholePart);
+  }
+  const fractionKey = `${remainder}/${den}`;
+  const vulgar = VULGAR_FRACTIONS[fractionKey];
+  if (wholePart > 0) {
+    return vulgar ? `${wholePart}${vulgar}` : `${wholePart} ${remainder}/${den}`;
+  }
+  return vulgar ?? `${num}/${den}`;
+}
+function formatNumericValue(value, useVulgar = true) {
   if (value.type === "decimal") {
     return String(value.decimal);
   }
+  if (useVulgar) {
+    return renderFractionAsVulgar(value.num, value.den);
+  }
   return `${value.num}/${value.den}`;
 }
 function formatSingleValue(value) {
@@ -3125,6 +3718,7 @@ function isAlternativeSelected(recipe, choices, item, alternativeIndex) {
   Section,
   ShoppingCart,
   ShoppingList,
+  convertQuantityToSystem,
   formatExtendedQuantity,
   formatItemQuantity,
   formatNumericValue,
@@ -3136,11 +3730,15 @@ function isAlternativeSelected(recipe, choices, item, alternativeIndex) {
   isAlternativeSelected,
   isAndGroup,
   isGroupedItem,
-  isSimpleGroup
+  isSimpleGroup,
+  renderFractionAsVulgar
 });
 /* v8 ignore else -- @preserve */
+/* v8 ignore next -- @preserve: defensive fallback for ambiguous units without toBaseBySystem */
+/* v8 ignore start -- @preserve: defensive fallback that shouldn't happen with valid inputs */
 // v8 ignore else -- @preserve
-/* v8 ignore else -- expliciting error type -- @preserve */
 // v8 ignore if -- @preserve
+/* v8 ignore else -- expliciting error type -- @preserve */
 /* v8 ignore if -- @preserve */
+// v8 ignore next -- @preserve
 //# sourceMappingURL=index.cjs.map