@capgo/camera-preview 7.4.0-alpha.3 → 7.4.0-alpha.32

package/dist/docs.json

@@ -161,7 +161,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Set the aspect ratio of the camera preview.",
@@ -180,7 +184,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Gets the current aspect ratio of the camera preview.",
@@ -422,7 +430,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Checks if the camera preview is currently running.",
@@ -441,7 +453,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Gets all available camera devices.",
@@ -462,7 +478,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Gets the current zoom state, including min/max and current lens info.",
@@ -471,6 +491,25 @@
         ],
         "slug": "getzoom"
       },
+      {
+        "name": "getZoomButtonValues",
+        "signature": "() => Promise<{ values: number[]; }>",
+        "parameters": [],
+        "returns": "Promise<{ values: number[]; }>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Returns zoom button values for quick switching.\n- iOS/Android: includes 0.5 if ultra-wide available; 1 and 2 if wide available; 3 if telephoto available\n- Web: unsupported",
+        "complexTypes": [],
+        "slug": "getzoombuttonvalues"
+      },
       {
         "name": "setZoom",
         "signature": "(options: { level: number; ramp?: boolean; autoFocus?: boolean; }) => Promise<void>",
@@ -493,7 +532,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Sets the zoom level of the camera.",
@@ -512,7 +555,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Gets the current flash mode.",
@@ -529,7 +576,11 @@
         "tags": [
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Removes all registered listeners.",
@@ -558,7 +609,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Switches the active camera to the one with the specified `deviceId`.",
@@ -577,7 +632,11 @@
           },
           {
             "name": "since",
-            "text": "7.4.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Gets the ID of the currently active camera device.",
@@ -592,6 +651,14 @@
         "tags": [
           {
             "name": "returns"
+          },
+          {
+            "name": "since",
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Gets the current preview size and position.",
@@ -617,6 +684,14 @@
           {
             "name": "returns",
             "text": "A promise that resolves with the actual preview dimensions and position."
+          },
+          {
+            "name": "since",
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Sets the preview size and position.",
@@ -645,12 +720,168 @@
           },
           {
             "name": "since",
-            "text": "8.1.0"
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
           }
         ],
         "docs": "Sets the camera focus to a specific point in the preview.",
         "complexTypes": [],
         "slug": "setfocus"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: \"screenResize\", listenerFunc: (data: { width: number; height: number; x: number; y: number; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- The event name to listen for.",
+            "type": "'screenResize'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- The function to call when the event is triggered.",
+            "type": "(data: { width: number; height: number; x: number; y: number; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - The event name to listen for."
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - The function to call when the event is triggered."
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves with a handle to the listener."
+          },
+          {
+            "name": "since",
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Adds a listener for screen resize events.",
+        "complexTypes": [
+          "PluginListenerHandle"
+        ],
+        "slug": "addlistenerscreenresize-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: \"orientationChange\", listenerFunc: (data: { orientation: DeviceOrientation; }) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- The event name to listen for.",
+            "type": "'orientationChange'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- The function to call when the event is triggered.",
+            "type": "(data: { orientation: DeviceOrientation; }) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - The event name to listen for."
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - The function to call when the event is triggered."
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves with a handle to the listener."
+          },
+          {
+            "name": "since",
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Adds a listener for orientation change events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "DeviceOrientation"
+        ],
+        "slug": "addlistenerorientationchange-"
+      },
+      {
+        "name": "deleteFile",
+        "signature": "(options: { path: string; }) => Promise<{ success: boolean; }>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "{ path: string; }"
+          }
+        ],
+        "returns": "Promise<{ success: boolean; }>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Deletes a file at the given absolute path on the device.\nUse this to quickly clean up temporary images created with `storeToFile`.\nOn web, this is not supported and will throw.",
+        "complexTypes": [],
+        "slug": "deletefile"
+      },
+      {
+        "name": "getSafeAreaInsets",
+        "signature": "() => Promise<SafeAreaInsets>",
+        "parameters": [],
+        "returns": "Promise<SafeAreaInsets>",
+        "tags": [
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Gets the safe area insets for devices.\nReturns the orientation-aware notch/camera cutout inset and the current orientation.\nIn portrait mode: returns top inset (notch at top).\nIn landscape mode: returns left inset (notch moved to side).\nThis specifically targets the cutout area (notch, punch hole, etc.) that all modern phones have.\n\nAndroid: Values returned in dp (logical pixels).\niOS: Values returned in physical pixels, excluding status bar (only pure notch/cutout size).",
+        "complexTypes": [
+          "SafeAreaInsets"
+        ],
+        "slug": "getsafeareainsets"
+      },
+      {
+        "name": "getOrientation",
+        "signature": "() => Promise<{ orientation: DeviceOrientation; }>",
+        "parameters": [],
+        "returns": "Promise<{ orientation: DeviceOrientation; }>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "7.5.0"
+          },
+          {
+            "name": "platform",
+            "text": "android, ios"
+          }
+        ],
+        "docs": "Gets the current device orientation in a cross-platform format.",
+        "complexTypes": [
+          "DeviceOrientation"
+        ],
+        "slug": "getorientation"
       }
     ],
     "properties": []
@@ -1357,6 +1588,45 @@
           "type": "number"
         }
       ]
+    },
+    {
+      "name": "PluginListenerHandle",
+      "slug": "pluginlistenerhandle",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "remove",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "() => Promise<void>"
+        }
+      ]
+    },
+    {
+      "name": "SafeAreaInsets",
+      "slug": "safeareainsets",
+      "docs": "Represents safe area insets for devices.\nAndroid: Values are expressed in logical pixels (dp) to match JS layout units.\niOS: Values are expressed in physical pixels and exclude status bar.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "orientation",
+          "tags": [],
+          "docs": "Current device orientation (1 = portrait, 2 = landscape, 0 = unknown).",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "top",
+          "tags": [],
+          "docs": "Orientation-aware notch/camera cutout inset (excluding status bar).\nIn portrait mode: returns top inset (notch at top).\nIn landscape mode: returns left inset (notch at side).\nAndroid: Value in dp, iOS: Value in pixels (status bar excluded).",
+          "complexTypes": [],
+          "type": "number"
+        }
+      ]
     }
   ],
   "enums": [
@@ -1513,6 +1783,37 @@
           ]
         }
       ]
+    },
+    {
+      "name": "DeviceOrientation",
+      "slug": "deviceorientation",
+      "docs": "Canonical device orientation values across platforms.",
+      "types": [
+        {
+          "text": "\"portrait\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"landscape\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"landscape-left\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"landscape-right\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"portrait-upside-down\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"unknown\"",
+          "complexTypes": []
+        }
+      ]
     }
   ],
   "pluginConfigs": []

package/dist/esm/definitions.d.ts

@@ -1,3 +1,4 @@
+import type { PluginListenerHandle } from "@capacitor/core";
 export type CameraPosition = "rear" | "front";
 export type FlashMode = CameraPreviewFlashMode;
 export type GridMode = "none" | "3x3" | "4x4";
@@ -289,6 +290,26 @@ export interface CameraOpacityOptions {
      */
     opacity?: number;
 }
+/**
+ * Represents safe area insets for devices.
+ * Android: Values are expressed in logical pixels (dp) to match JS layout units.
+ * iOS: Values are expressed in physical pixels and exclude status bar.
+ */
+export interface SafeAreaInsets {
+    /** Current device orientation (1 = portrait, 2 = landscape, 0 = unknown). */
+    orientation: number;
+    /**
+     * Orientation-aware notch/camera cutout inset (excluding status bar).
+     * In portrait mode: returns top inset (notch at top).
+     * In landscape mode: returns left inset (notch at side).
+     * Android: Value in dp, iOS: Value in pixels (status bar excluded).
+     */
+    top: number;
+}
+/**
+ * Canonical device orientation values across platforms.
+ */
+export type DeviceOrientation = "portrait" | "landscape" | "landscape-left" | "landscape-right" | "portrait-upside-down" | "unknown";
 /**
  * The main interface for the CameraPreview plugin.
  */
@@ -356,7 +377,8 @@ export interface CameraPreviewPlugin {
      *   - x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.
      *   - y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.
      * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     setAspectRatio(options: {
         aspectRatio: "4:3" | "16:9";
@@ -372,7 +394,8 @@ export interface CameraPreviewPlugin {
      * Gets the current aspect ratio of the camera preview.
      *
      * @returns {Promise<{ aspectRatio: '4:3' | '16:9' }>} A promise that resolves with the current aspect ratio.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     getAspectRatio(): Promise<{
         aspectRatio: "4:3" | "16:9";
@@ -461,7 +484,8 @@ export interface CameraPreviewPlugin {
      * Checks if the camera preview is currently running.
      *
      * @returns {Promise<{ isRunning: boolean }>} A promise that resolves with the running state.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     isRunning(): Promise<{
         isRunning: boolean;
@@ -470,7 +494,8 @@ export interface CameraPreviewPlugin {
      * Gets all available camera devices.
      *
      * @returns {Promise<{ devices: CameraDevice[] }>} A promise that resolves with the list of available camera devices.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     getAvailableDevices(): Promise<{
         devices: CameraDevice[];
@@ -479,7 +504,8 @@ export interface CameraPreviewPlugin {
      * Gets the current zoom state, including min/max and current lens info.
      *
      * @returns {Promise<{ min: number; max: number; current: number; lens: LensInfo }>} A promise that resolves with the zoom state.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     getZoom(): Promise<{
         min: number;
@@ -487,12 +513,23 @@ export interface CameraPreviewPlugin {
         current: number;
         lens: LensInfo;
     }>;
+    /**
+     * Returns zoom button values for quick switching.
+     * - iOS/Android: includes 0.5 if ultra-wide available; 1 and 2 if wide available; 3 if telephoto available
+     * - Web: unsupported
+     * @since 7.5.0
+     * @platform android, ios
+     */
+    getZoomButtonValues(): Promise<{
+        values: number[];
+    }>;
     /**
      * Sets the zoom level of the camera.
      *
      * @param {{ level: number; ramp?: boolean; autoFocus?: boolean }} options - The desired zoom level. `ramp` is currently unused. `autoFocus` defaults to true.
      * @returns {Promise<void>} A promise that resolves when the zoom level is set.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     setZoom(options: {
         level: number;
@@ -503,7 +540,8 @@ export interface CameraPreviewPlugin {
      * Gets the current flash mode.
      *
      * @returns {Promise<{ flashMode: FlashMode }>} A promise that resolves with the current flash mode.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     getFlashMode(): Promise<{
         flashMode: FlashMode;
@@ -511,7 +549,8 @@ export interface CameraPreviewPlugin {
     /**
      * Removes all registered listeners.
      *
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     removeAllListeners(): Promise<void>;
     /**
@@ -519,7 +558,8 @@ export interface CameraPreviewPlugin {
      *
      * @param {{ deviceId: string }} options - The ID of the device to switch to.
      * @returns {Promise<void>} A promise that resolves when the camera is switched.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     setDeviceId(options: {
         deviceId: string;
@@ -528,7 +568,8 @@ export interface CameraPreviewPlugin {
      * Gets the ID of the currently active camera device.
      *
      * @returns {Promise<{ deviceId: string }>} A promise that resolves with the current device ID.
-     * @since 7.4.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     getDeviceId(): Promise<{
         deviceId: string;
@@ -536,6 +577,8 @@ export interface CameraPreviewPlugin {
     /**
      * Gets the current preview size and position.
      * @returns {Promise<{x: number, y: number, width: number, height: number}>}
+     * @since 7.5.0
+     * @platform android, ios
      */
     getPreviewSize(): Promise<{
         x: number;
@@ -547,6 +590,8 @@ export interface CameraPreviewPlugin {
      * Sets the preview size and position.
      * @param options The new position and dimensions.
      * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.
+     * @since 7.5.0
+     * @platform android, ios
      */
     setPreviewSize(options: {
         x?: number;
@@ -566,10 +611,69 @@ export interface CameraPreviewPlugin {
      * @param {number} options.x - The x coordinate in the preview view to focus on (0-1 normalized).
      * @param {number} options.y - The y coordinate in the preview view to focus on (0-1 normalized).
      * @returns {Promise<void>} A promise that resolves when the focus is set.
-     * @since 8.1.0
+     * @since 7.5.0
+     * @platform android, ios
      */
     setFocus(options: {
         x: number;
         y: number;
     }): Promise<void>;
+    /**
+     * Adds a listener for screen resize events.
+     * @param {string} eventName - The event name to listen for.
+     * @param {Function} listenerFunc - The function to call when the event is triggered.
+     * @returns {Promise<PluginListenerHandle>} A promise that resolves with a handle to the listener.
+     * @since 7.5.0
+     * @platform android, ios
+     */
+    addListener(eventName: "screenResize", listenerFunc: (data: {
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    }) => void): Promise<PluginListenerHandle>;
+    /**
+     * Adds a listener for orientation change events.
+     * @param {string} eventName - The event name to listen for.
+     * @param {Function} listenerFunc - The function to call when the event is triggered.
+     * @returns {Promise<PluginListenerHandle>} A promise that resolves with a handle to the listener.
+     * @since 7.5.0
+     * @platform android, ios
+     */
+    addListener(eventName: "orientationChange", listenerFunc: (data: {
+        orientation: DeviceOrientation;
+    }) => void): Promise<PluginListenerHandle>;
+    /**
+     * Deletes a file at the given absolute path on the device.
+     * Use this to quickly clean up temporary images created with `storeToFile`.
+     * On web, this is not supported and will throw.
+     * @since 7.5.0
+     * @platform android, ios
+     */
+    deleteFile(options: {
+        path: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Gets the safe area insets for devices.
+     * Returns the orientation-aware notch/camera cutout inset and the current orientation.
+     * In portrait mode: returns top inset (notch at top).
+     * In landscape mode: returns left inset (notch moved to side).
+     * This specifically targets the cutout area (notch, punch hole, etc.) that all modern phones have.
+     *
+     * Android: Values returned in dp (logical pixels).
+     * iOS: Values returned in physical pixels, excluding status bar (only pure notch/cutout size).
+     *
+     * @platform android, ios
+     */
+    getSafeAreaInsets(): Promise<SafeAreaInsets>;
+    /**
+     * Gets the current device orientation in a cross-platform format.
+     * @since 7.5.0
+     * @platform android, ios
+     */
+    getOrientation(): Promise<{
+        orientation: DeviceOrientation;
+    }>;
 }