feat: Add ML Kit zoom suggestions to the Barcode Scanner output (Andr…

docs/content/docs/barcode-scanner.mdx

@@ -124,6 +124,31 @@ async function scanBarcodeImage() {
 </Tab>
 </Tabs>
 
+### Zoom suggestions (Android)
+
+When a barcode is detected but too far away to be decoded, ML Kit suggests a zoom ratio. Pass [`onZoomSuggested`](/api/react-native-vision-camera-barcode-scanner/interfaces/BarcodeScannerOutputOptions#onzoomsuggested) to apply it to the Camera's [`zoom`](/api/react-native-vision-camera/interfaces/CameraViewProps#zoom), and [`maxZoomRatio`](/api/react-native-vision-camera-barcode-scanner/interfaces/BarcodeScannerOutputOptions#maxzoomratio) to cap suggestions at the device's maximum zoom:
+
+```tsx
+const device = useCameraDevice('back')
+const [zoom, setZoom] = useState(1)
+const scannerOutput = useBarcodeScannerOutput({
+  barcodeFormats: ['qr-code'],
+  onBarcodeScanned(barcodes) {
+    console.log(`Scanned ${barcodes.length} barcodes!`)
+  },
+  onError(error) {
+    console.error(`Failed to scan barcodes!`, error)
+  },
+  maxZoomRatio: device.maxZoom,
+  onZoomSuggested(zoomRatio) {
+    setZoom(zoomRatio)
+  },
+})
+```
+
+> [!NOTE]
+> Zoom suggestions are only available on Android - ML Kit on iOS does not provide them.
+
 ### Configuring Barcode Formats
 
 The examples above are configured to detect **all** [`BarcodeFormat`](/api/react-native-vision-camera-barcode-scanner/type-aliases/BarcodeFormat)s.

packages/react-native-vision-camera-barcode-scanner/android/src/main/java/com/margelo/nitro/camera/barcodescanner/extensions/BarcodeScannerOptions+toMLBarcodeScannerOptions.kt

@@ -1,5 +1,6 @@
 package com.margelo.nitro.camera.barcodescanner.extensions
 
+import com.google.mlkit.vision.barcode.ZoomSuggestionOptions
 import com.margelo.nitro.camera.barcodescanner.BarcodeScannerOptions
 import com.margelo.nitro.camera.barcodescanner.BarcodeScannerOutputOptions
 import com.margelo.nitro.camera.barcodescanner.TargetBarcodeFormat
@@ -23,8 +24,19 @@ fun BarcodeScannerOptions.toMLBarcodeScannerOptions(): com.google.mlkit.vision.b
 }
 
 fun BarcodeScannerOutputOptions.toMLBarcodeScannerOptions(): com.google.mlkit.vision.barcode.BarcodeScannerOptions {
-  return com.google.mlkit.vision.barcode.BarcodeScannerOptions
-    .Builder()
-    .setBarcodeFormats(this.barcodeFormats)
-    .build()
+  val builder =
+    com.google.mlkit.vision.barcode.BarcodeScannerOptions
+      .Builder()
+      .setBarcodeFormats(this.barcodeFormats)
+  val onZoomSuggested = this.onZoomSuggested
+  if (onZoomSuggested != null) {
+    val zoomSuggestionOptions =
+      ZoomSuggestionOptions.Builder { zoomRatio ->
+        onZoomSuggested(zoomRatio.toDouble())
+        true
+      }
+    this.maxZoomRatio?.let { zoomSuggestionOptions.setMaxSupportedZoomRatio(it.toFloat()) }
+    builder.setZoomSuggestionOptions(zoomSuggestionOptions.build())
+  }
+  return builder.build()
 }