@capgo/capacitor-inappbrowser 8.18.1 → 8.20.0

package/dist/docs.json

@@ -399,6 +399,30 @@
         ],
         "slug": "addlistenerurlchangeevent-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'fullscreenChange', listenerFunc: (event: FullscreenChangeEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'fullscreenChange'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(event: FullscreenChangeEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [],
+        "docs": "Listen for applied fullscreen changes, including startup entry, the native exit button,\nAndroid Back, and native lifecycle cleanup. Register before opening to observe startup entry.\nRepeated requests for the current state do not emit duplicate events.\nThis event describes host-controlled fullscreen, not HTML/video fullscreen.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "FullscreenChangeEvent"
+        ],
+        "slug": "addlistenerfullscreenchange-"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'buttonNearDoneClick', listenerFunc: ButtonNearListener) => Promise<PluginListenerHandle>",
@@ -926,6 +950,38 @@
         ],
         "slug": "updatedimensions"
       },
+      {
+        "name": "setFullscreen",
+        "signature": "(options: { enabled: boolean; id?: string; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "{ enabled: boolean; id?: string | undefined; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [],
+        "docs": "Enter or exit immersive fullscreen without recreating or reloading the webview.\nWhen `id` is omitted, targets the active webview. Repeated calls are idempotent.\nEntry requires a visible, frontmost, full-size `openWebView` on iOS or Android.\nMissing webviews, invalid arguments, custom dimensions, behind-host presentations,\nand the Web platform reject. Use the opening `fullscreen` option for an initially hidden webview.\nDisabling also cancels any pending fullscreen-at-launch request.\n\nNative exit controls, backgrounding, hiding, closing, cross-origin navigation, and renderer\ntermination restore the original chrome even when host JavaScript cannot respond.",
+        "complexTypes": [],
+        "slug": "setfullscreen"
+      },
+      {
+        "name": "getFullscreen",
+        "signature": "(options?: { id?: string | undefined; } | undefined) => Promise<{ enabled: boolean; }>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "{ id?: string | undefined; } | undefined"
+          }
+        ],
+        "returns": "Promise<{ enabled: boolean; }>",
+        "tags": [],
+        "docs": "Read the applied host-controlled fullscreen state of an `openWebView`.\nWhen `id` is omitted, targets the active webview. Initially hidden fullscreen webviews\nreport `false` until their first presentation. Missing webviews and Web usage reject.\nHTML/video fullscreen does not change this value.",
+        "complexTypes": [],
+        "slug": "getfullscreen"
+      },
       {
         "name": "setEnabledSafeTopMargin",
         "signature": "(options: { enabled: boolean; id?: string; }) => Promise<void>",
@@ -1400,6 +1456,22 @@
       "tags": [],
       "methods": [],
       "properties": [
+        {
+          "name": "fullscreen",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            },
+            {
+              "text": "fullscreen: true,\ntoolbarType: ToolBarType.NAVIGATION // Restored when the user exits fullscreen",
+              "name": "example"
+            }
+          ],
+          "docs": "Present this webview in immersive fullscreen from its first visible frame.\nHides native navigation and system bars and provides a native exit-fullscreen button.\nThe same webview, page state, cookies, and history are retained on entry and exit.\nExiting restores the configured toolbar and safe-area settings.\n\nApplies before presentation, including when `isPresentAfterPageLoad` is true.\nWith `hidden: true`, waits for the first `show()` without changing the host's system bars.\nSubsequent hide/show or background/resume cycles do not re-enter fullscreen automatically.\nOnly supported on iOS and Android for full-size, frontmost `openWebView` presentations.\nCustom dimensions and `toBack: true` are unsupported. The Web implementation rejects `true`.\nPermission prompts, if needed, are the host application's responsibility.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
         {
           "name": "url",
           "tags": [
@@ -1684,10 +1756,28 @@
               "name": "since"
             }
           ],
-          "docs": "Automatically handles downloads triggered inside the webview without requiring a custom JavaScript bridge.\n\nWhen enabled:\n- Standard attachment responses are written to a temporary file.\n- `blob:` downloads are also captured when the platform supports them.\n- Previewable files reopen inside the in-app browser when possible.\n- Other files are handed off to the native preview or viewer flow.\n- `downloadCompleted` and `downloadFailed` events notify the host app about the saved file.",
+          "docs": "Automatically handles downloads triggered inside the webview without requiring a custom JavaScript bridge.\n\nWhen enabled:\n- Standard attachment responses are written to a temporary file.\n- `blob:` downloads are also captured when the platform supports them.\n- Previewable files reopen inside the in-app browser when possible (see `downloadPreview`).\n- Other files are handed off to the native preview or viewer flow.\n- `downloadCompleted` and `downloadFailed` events notify the host app about the saved file.",
           "complexTypes": [],
           "type": "boolean | undefined"
         },
+        {
+          "name": "downloadPreview",
+          "tags": [
+            {
+              "text": "\"inAppBrowser\"",
+              "name": "default"
+            },
+            {
+              "text": "8.19.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Controls where managed downloads are previewed after saving.\n\n- `'inAppBrowser'` (default): Reopens previewable files (PDF, images, text, JSON) inside the same webview.\n- `'systemPreview'`: Opens the system Quick Look preview with share and Save to Files actions. iOS only; ignored on Android.\n\nRequires `handleDownloads: true`.",
+          "complexTypes": [
+            "DownloadPreview"
+          ],
+          "type": "DownloadPreview"
+        },
         {
           "name": "shareDisclaimer",
           "tags": [
@@ -2960,6 +3050,29 @@
         }
       ]
     },
+    {
+      "name": "FullscreenChangeEvent",
+      "slug": "fullscreenchangeevent",
+      "docs": "A change to host-controlled fullscreen; independent of HTML/video fullscreen.",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "id",
+          "tags": [],
+          "docs": "Webview instance id.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "enabled",
+          "tags": [],
+          "docs": "Whether fullscreen is currently applied to the visible webview.",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
     {
       "name": "ButtonNearDoneEvent",
       "slug": "buttonneardoneevent",
@@ -3861,6 +3974,21 @@
         }
       ]
     },
+    {
+      "name": "DownloadPreview",
+      "slug": "downloadpreview",
+      "docs": "Where managed downloads are previewed after saving.",
+      "types": [
+        {
+          "text": "'inAppBrowser'",
+          "complexTypes": []
+        },
+        {
+          "text": "'systemPreview'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "PreferredContentMode",
       "slug": "preferredcontentmode",

package/dist/esm/definitions.d.ts

@@ -11,6 +11,13 @@ export interface UrlEvent {
      */
     url: string;
 }
+/** A change to host-controlled fullscreen; independent of HTML/video fullscreen. */
+export interface FullscreenChangeEvent {
+    /** Webview instance id. */
+    id: string;
+    /** Whether fullscreen is currently applied to the visible webview. */
+    enabled: boolean;
+}
 /**
  * Event emitted when the managed webview intercepts a non-standard custom scheme
  * and hands it to the operating system.
@@ -331,6 +338,12 @@ export interface ConsoleMessageEvent {
  * @since 8.6.0
  */
 export type DownloadHandledBy = 'inAppBrowser' | 'systemPreview' | 'external';
+/**
+ * Where managed downloads are previewed after saving.
+ *
+ * @since 8.19.0
+ */
+export type DownloadPreview = 'inAppBrowser' | 'systemPreview';
 /**
  * Event emitted after a managed download is saved locally.
  *
@@ -614,6 +627,25 @@ export interface CloseWebviewOptions {
     isAnimated?: boolean;
 }
 export interface OpenWebViewOptions {
+    /**
+     * Present this webview in immersive fullscreen from its first visible frame.
+     * Hides native navigation and system bars and provides a native exit-fullscreen button.
+     * The same webview, page state, cookies, and history are retained on entry and exit.
+     * Exiting restores the configured toolbar and safe-area settings.
+     *
+     * Applies before presentation, including when `isPresentAfterPageLoad` is true.
+     * With `hidden: true`, waits for the first `show()` without changing the host's system bars.
+     * Subsequent hide/show or background/resume cycles do not re-enter fullscreen automatically.
+     * Only supported on iOS and Android for full-size, frontmost `openWebView` presentations.
+     * Custom dimensions and `toBack: true` are unsupported. The Web implementation rejects `true`.
+     * Permission prompts, if needed, are the host application's responsibility.
+     *
+     * @default false
+     * @example
+     * fullscreen: true,
+     * toolbarType: ToolBarType.NAVIGATION // Restored when the user exits fullscreen
+     */
+    fullscreen?: boolean;
     /**
      * Target URL to load.
      *
@@ -822,7 +854,7 @@ export interface OpenWebViewOptions {
      * When enabled:
      * - Standard attachment responses are written to a temporary file.
      * - `blob:` downloads are also captured when the platform supports them.
-     * - Previewable files reopen inside the in-app browser when possible.
+     * - Previewable files reopen inside the in-app browser when possible (see `downloadPreview`).
      * - Other files are handed off to the native preview or viewer flow.
      * - `downloadCompleted` and `downloadFailed` events notify the host app about the saved file.
      *
@@ -830,6 +862,18 @@ export interface OpenWebViewOptions {
      * @since 8.6.0
      */
     handleDownloads?: boolean;
+    /**
+     * Controls where managed downloads are previewed after saving.
+     *
+     * - `'inAppBrowser'` (default): Reopens previewable files (PDF, images, text, JSON) inside the same webview.
+     * - `'systemPreview'`: Opens the system Quick Look preview with share and Save to Files actions. iOS only; ignored on Android.
+     *
+     * Requires `handleDownloads: true`.
+     *
+     * @default "inAppBrowser"
+     * @since 8.19.0
+     */
+    downloadPreview?: DownloadPreview;
     /**
      * Share options for the webview. When provided, shows a disclaimer dialog before sharing content.
      * This is useful for:
@@ -1632,6 +1676,13 @@ export interface InAppBrowserPlugin {
      * @since 0.0.1
      */
     addListener(eventName: 'urlChangeEvent', listenerFunc: UrlChangeListener): Promise<PluginListenerHandle>;
+    /**
+     * Listen for applied fullscreen changes, including startup entry, the native exit button,
+     * Android Back, and native lifecycle cleanup. Register before opening to observe startup entry.
+     * Repeated requests for the current state do not emit duplicate events.
+     * This event describes host-controlled fullscreen, not HTML/video fullscreen.
+     */
+    addListener(eventName: 'fullscreenChange', listenerFunc: (event: FullscreenChangeEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Listen for buttonNearDone clicks.
      *
@@ -1790,6 +1841,32 @@ export interface InAppBrowserPlugin {
     updateDimensions(options: DimensionOptions & {
         id?: string;
     }): Promise<void>;
+    /**
+     * Enter or exit immersive fullscreen without recreating or reloading the webview.
+     * When `id` is omitted, targets the active webview. Repeated calls are idempotent.
+     * Entry requires a visible, frontmost, full-size `openWebView` on iOS or Android.
+     * Missing webviews, invalid arguments, custom dimensions, behind-host presentations,
+     * and the Web platform reject. Use the opening `fullscreen` option for an initially hidden webview.
+     * Disabling also cancels any pending fullscreen-at-launch request.
+     *
+     * Native exit controls, backgrounding, hiding, closing, cross-origin navigation, and renderer
+     * termination restore the original chrome even when host JavaScript cannot respond.
+     */
+    setFullscreen(options: {
+        enabled: boolean;
+        id?: string;
+    }): Promise<void>;
+    /**
+     * Read the applied host-controlled fullscreen state of an `openWebView`.
+     * When `id` is omitted, targets the active webview. Initially hidden fullscreen webviews
+     * report `false` until their first presentation. Missing webviews and Web usage reject.
+     * HTML/video fullscreen does not change this value.
+     */
+    getFullscreen(options?: {
+        id?: string;
+    }): Promise<{
+        enabled: boolean;
+    }>;
     /**
      * Sets the enabled safe top margin of the webview at runtime.
      * When `id` is omitted, targets the active webview.