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

package/README.md

@@ -37,7 +37,7 @@ Take into account that this will make transparent all ion-content on application
 ```
 
 If the camera preview is not displaying after applying the above styles, apply transparent background color to the root div element of the parent component
-Ex: VueJS >> App.vue component 
+Ex: VueJS >> App.vue component
 ```html
 <template>
   <ion-app id="app">
@@ -76,6 +76,24 @@ Video and photo taken with the plugin are never removed, so do not forget to rem
 use https://capacitorjs.com/docs/apis/filesystem#deletefile for that
 
 
+## Fast base64 from file path (no bridge)
+
+When using `storeToFile: true`, you can avoid sending large base64 strings over the Capacitor bridge:
+
+```ts
+import { CameraPreview, getBase64FromFilePath } from '@capgo/camera-preview'
+
+// Take a picture and get a file path
+const { value: filePath } = await CameraPreview.capture({ quality: 85, storeToFile: true })
+
+// Convert the file to base64 entirely on the JS side (fast, no bridge)
+const base64 = await getBase64FromFilePath(filePath)
+
+// Optionally cleanup the temp file natively
+await CameraPreview.deleteFile({ path: filePath })
+```
+
+
 # Installation
 
 ```
@@ -234,6 +252,7 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 * [`isRunning()`](#isrunning)
 * [`getAvailableDevices()`](#getavailabledevices)
 * [`getZoom()`](#getzoom)
+* [`getZoomButtonValues()`](#getzoombuttonvalues)
 * [`setZoom(...)`](#setzoom)
 * [`getFlashMode()`](#getflashmode)
 * [`removeAllListeners()`](#removealllisteners)
@@ -242,6 +261,11 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 * [`getPreviewSize()`](#getpreviewsize)
 * [`setPreviewSize(...)`](#setpreviewsize)
 * [`setFocus(...)`](#setfocus)
+* [`addListener('screenResize', ...)`](#addlistenerscreenresize-)
+* [`addListener('orientationChange', ...)`](#addlistenerorientationchange-)
+* [`deleteFile(...)`](#deletefile)
+* [`getSafeAreaInsets()`](#getsafeareainsets)
+* [`getOrientation()`](#getorientation)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 * [Enums](#enums)
@@ -352,7 +376,7 @@ Set the aspect ratio of the camera preview.
 
 **Returns:** <code>Promise&lt;{ width: number; height: number; x: number; y: number; }&gt;</code>
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -367,7 +391,7 @@ Gets the current aspect ratio of the camera preview.
 
 **Returns:** <code>Promise&lt;{ aspectRatio: '4:3' | '16:9'; }&gt;</code>
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -524,7 +548,7 @@ Checks if the camera preview is currently running.
 
 **Returns:** <code>Promise&lt;{ isRunning: boolean; }&gt;</code>
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -539,7 +563,7 @@ Gets all available camera devices.
 
 **Returns:** <code>Promise&lt;{ devices: CameraDevice[]; }&gt;</code>
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -554,7 +578,24 @@ Gets the current zoom state, including min/max and current lens info.
 
 **Returns:** <code>Promise&lt;{ min: number; max: number; current: number; lens: <a href="#lensinfo">LensInfo</a>; }&gt;</code>
 
-**Since:** 7.4.0
+**Since:** 7.5.0
+
+--------------------
+
+
+### getZoomButtonValues()
+
+```typescript
+getZoomButtonValues() => Promise<{ values: number[]; }>
+```
+
+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
+
+**Returns:** <code>Promise&lt;{ values: number[]; }&gt;</code>
+
+**Since:** 7.5.0
 
 --------------------
 
@@ -571,7 +612,7 @@ Sets the zoom level of the camera.
 | ------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
 | **`options`** | <code>{ level: number; ramp?: boolean; autoFocus?: boolean; }</code> | - The desired zoom level. `ramp` is currently unused. `autoFocus` defaults to true. |
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -586,7 +627,7 @@ Gets the current flash mode.
 
 **Returns:** <code>Promise&lt;{ flashMode: <a href="#camerapreviewflashmode">CameraPreviewFlashMode</a>; }&gt;</code>
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -599,7 +640,7 @@ removeAllListeners() => Promise<void>
 
 Removes all registered listeners.
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -616,7 +657,7 @@ Switches the active camera to the one with the specified `deviceId`.
 | ------------- | ---------------------------------- | ------------------------------------ |
 | **`options`** | <code>{ deviceId: string; }</code> | - The ID of the device to switch to. |
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -631,7 +672,7 @@ Gets the ID of the currently active camera device.
 
 **Returns:** <code>Promise&lt;{ deviceId: string; }&gt;</code>
 
-**Since:** 7.4.0
+**Since:** 7.5.0
 
 --------------------
 
@@ -646,6 +687,8 @@ Gets the current preview size and position.
 
 **Returns:** <code>Promise&lt;{ x: number; y: number; width: number; height: number; }&gt;</code>
 
+**Since:** 7.5.0
+
 --------------------
 
 
@@ -663,6 +706,8 @@ Sets the preview size and position.
 
 **Returns:** <code>Promise&lt;{ width: number; height: number; x: number; y: number; }&gt;</code>
 
+**Since:** 7.5.0
+
 --------------------
 
 
@@ -678,7 +723,103 @@ Sets the camera focus to a specific point in the preview.
 | ------------- | -------------------------------------- | -------------------- |
 | **`options`** | <code>{ x: number; y: number; }</code> | - The focus options. |
 
-**Since:** 8.1.0
+**Since:** 7.5.0
+
+--------------------
+
+
+### addListener('screenResize', ...)
+
+```typescript
+addListener(eventName: "screenResize", listenerFunc: (data: { width: number; height: number; x: number; y: number; }) => void) => Promise<PluginListenerHandle>
+```
+
+Adds a listener for screen resize events.
+
+| Param              | Type                                                                                     | Description                                         |
+| ------------------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **`eventName`**    | <code>'screenResize'</code>                                                              | - The event name to listen for.                     |
+| **`listenerFunc`** | <code>(data: { width: number; height: number; x: number; y: number; }) =&gt; void</code> | - The function to call when the event is triggered. |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 7.5.0
+
+--------------------
+
+
+### addListener('orientationChange', ...)
+
+```typescript
+addListener(eventName: "orientationChange", listenerFunc: (data: { orientation: DeviceOrientation; }) => void) => Promise<PluginListenerHandle>
+```
+
+Adds a listener for orientation change events.
+
+| Param              | Type                                                                                                 | Description                                         |
+| ------------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **`eventName`**    | <code>'orientationChange'</code>                                                                     | - The event name to listen for.                     |
+| **`listenerFunc`** | <code>(data: { orientation: <a href="#deviceorientation">DeviceOrientation</a>; }) =&gt; void</code> | - The function to call when the event is triggered. |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 7.5.0
+
+--------------------
+
+
+### deleteFile(...)
+
+```typescript
+deleteFile(options: { path: string; }) => Promise<{ success: boolean; }>
+```
+
+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.
+
+| Param         | Type                           |
+| ------------- | ------------------------------ |
+| **`options`** | <code>{ path: string; }</code> |
+
+**Returns:** <code>Promise&lt;{ success: boolean; }&gt;</code>
+
+**Since:** 7.5.0
+
+--------------------
+
+
+### getSafeAreaInsets()
+
+```typescript
+getSafeAreaInsets() => Promise<SafeAreaInsets>
+```
+
+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).
+
+**Returns:** <code>Promise&lt;<a href="#safeareainsets">SafeAreaInsets</a>&gt;</code>
+
+--------------------
+
+
+### getOrientation()
+
+```typescript
+getOrientation() => Promise<{ orientation: DeviceOrientation; }>
+```
+
+Gets the current device orientation in a cross-platform format.
+
+**Returns:** <code>Promise&lt;{ orientation: <a href="#deviceorientation">DeviceOrientation</a>; }&gt;</code>
+
+**Since:** 7.5.0
 
 --------------------
 
@@ -816,6 +957,25 @@ Represents the detailed information of the currently active lens.
 | **`digitalZoom`**   | <code>number</code>                               | The current digital zoom factor applied on top of the base zoom. |
 
 
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### SafeAreaInsets
+
+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.
+
+| Prop              | Type                | Description                                                                                                                                                                                                                                      |
+| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`orientation`** | <code>number</code> | Current device orientation (1 = portrait, 2 = landscape, 0 = unknown).                                                                                                                                                                           |
+| **`top`**         | <code>number</code> | 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). |
+
+
 ### Type Aliases
 
 
@@ -852,6 +1012,13 @@ The available flash modes for the camera.
 <code><a href="#camerapreviewflashmode">CameraPreviewFlashMode</a></code>
 
 
+#### DeviceOrientation
+
+Canonical device orientation values across platforms.
+
+<code>"portrait" | "landscape" | "landscape-left" | "landscape-right" | "portrait-upside-down" | "unknown"</code>
+
+
 ### Enums