feat(render-helpers): add optional unit-first quantity formatting

src/utils/render_helpers.ts

@@ -188,11 +188,16 @@ export function formatUnit(unit: string | Unit | undefined): string {
 export function formatQuantityWithUnit(
   quantity: FixedValue | Range | undefined,
   unit: string | Unit | undefined,
+  unitOrder: "quantity-first" | "unit-first" = "quantity-first",
 ): string {
   if (!quantity) return "";
   const qty = formatQuantity(quantity);
   const unitStr = formatUnit(unit);
-  return unitStr ? `${qty} ${unitStr}` : qty;
+  if (!unitStr) return qty;
+  if (unitOrder === "unit-first") {
+    return `${unitStr}${qty}`;
+  }
+  return `${qty} ${unitStr}`;
 }
 
 /**
@@ -202,8 +207,11 @@ export function formatQuantityWithUnit(
  * @returns The formatted string
  * @category Helpers
  */
-export function formatExtendedQuantity(item: QuantityWithExtendedUnit): string {
-  return formatQuantityWithUnit(item.quantity, item.unit);
+export function formatExtendedQuantity(
+  item: QuantityWithExtendedUnit,
+  unitOrder: "quantity-first" | "unit-first" = "quantity-first",
+): string {
+  return formatQuantityWithUnit(item.quantity, item.unit, unitOrder);
 }
 
 /**
@@ -224,16 +232,17 @@ export function formatExtendedQuantity(item: QuantityWithExtendedUnit): string {
 export function formatItemQuantity(
   itemQuantity: MaybeScalableQuantity,
   separator: string = " | ",
+  unitOrder: "quantity-first" | "unit-first" = "quantity-first",
 ): string {
   const parts: string[] = [];
 
   // Primary quantity
-  parts.push(formatExtendedQuantity(itemQuantity));
+  parts.push(formatExtendedQuantity(itemQuantity, unitOrder));
 
   // Equivalents
   if (itemQuantity.equivalents) {
     for (const eq of itemQuantity.equivalents) {
-      parts.push(formatExtendedQuantity(eq));
+      parts.push(formatExtendedQuantity(eq, unitOrder));
     }
   }
 

test/render_helpers.test.ts

@@ -250,6 +250,24 @@ describe("formatQuantityWithUnit", () => {
     };
     expect(formatQuantityWithUnit(range, "tsp")).toBe("1-2 tsp");
   });
+
+  it("should format quantity with unit first and no space", () => {
+    const fixed: FixedValue = {
+      type: "fixed",
+      value: { type: "decimal", decimal: 1 },
+    };
+    expect(formatQuantityWithUnit(fixed, "大さじ", "unit-first")).toBe(
+      "大さじ1",
+    );
+  });
+
+  it("should ignore unit order when unit is missing", () => {
+    const fixed: FixedValue = {
+      type: "fixed",
+      value: { type: "decimal", decimal: 3 },
+    };
+    expect(formatQuantityWithUnit(fixed, undefined, "unit-first")).toBe("3");
+  });
 });
 
 // ============================================================================
@@ -271,6 +289,14 @@ describe("formatExtendedQuantity", () => {
     };
     expect(formatExtendedQuantity(item)).toBe("2");
   });
+
+  it("should support unit-first formatting", () => {
+    const item: QuantityWithExtendedUnit = {
+      quantity: { type: "fixed", value: { type: "decimal", decimal: 1 } },
+      unit: { name: "大さじ" },
+    };
+    expect(formatExtendedQuantity(item, "unit-first")).toBe("大さじ1");
+  });
 });
 
 // ============================================================================
@@ -335,6 +361,23 @@ describe("formatItemQuantity", () => {
     };
     expect(formatItemQuantity(itemQty)).toBe("240 ml | 1 cup | 8 fl oz");
   });
+
+  it("should thread unit-first formatting to primary and equivalents", () => {
+    const itemQty: MaybeScalableQuantity = {
+      quantity: { type: "fixed", value: { type: "decimal", decimal: 1 } },
+      unit: { name: "大さじ" },
+      equivalents: [
+        {
+          quantity: { type: "fixed", value: { type: "decimal", decimal: 3 } },
+          unit: { name: "小さじ" },
+        },
+      ],
+      scalable: true,
+    };
+    expect(formatItemQuantity(itemQty, " | ", "unit-first")).toBe(
+      "大さじ1 | 小さじ3",
+    );
+  });
 });
 
 // ============================================================================