@totalpave/cordova-plugin-insets 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -4,7 +4,56 @@
 
 # Changelog
 
-## 0.2.0 (TBD)
+## 0.3.0 (TBD)
+
+### Breaking Changes:
+
+#### Depluralize symbols
+
+Several symbols were written in plural form which goes against common naming
+conventions. In effort to make the API a bit cleaner, this was corrected.
+
+|Old Name|New Name|
+|---|---|
+|`Insets`|`Inset`|
+|`IInsets`|`IInset`|
+
+`window.totalpave.Insets` has been renamed to `window.totalpave.Inset`
+
+The typescript global typedefs have been updated accordingly.
+
+#### IInsetAPI
+
+This type interface was removed, the `Inset` class can be referenced instead.
+
+#### Inset API is no longer static
+
+The static `addListener`, `removeListener`, and `getInsets` APIs have been
+removed and replaced with non-static versions. Two new static methods are introduced:
+
+- `Inset.create`
+- `Inset.free`
+
+It is now the application's responsibility to create their own `Inset` instance via
+`Inset.create`, passing
+in their own configuration object. An instance of `Inset` will be returned that
+can be used like before.
+
+Once the inset instance is no longer needed it will be desirable to free resources
+by calling `inset.free()` which will free up retained references allowing the
+objects to be garbage collected.
+
+Most use cases only calls for a single instance to be created for the application,
+but it is valid to create several `Inset` instances with different configuration
+parameters.
+
+A non-static version of `getInsets` as noted above was introduced replacing the
+static method. However `getInsets` is also deprecated in effort to de-pluralize
+the API for better naming conventions. It will be removed in a future release.
+
+Any usages of `getInsets` should use `getInset` instead.
+
+## 0.2.0 (December 6, 2023)
 
 ### Breaking Changes:
 

package/README.md

@@ -15,7 +15,7 @@ If your app suppots multiple platforms, the API calls to this plugin should be p
 
 ```javascript
 if (cordova.platform === 'android') {
-    let insets = totalpave.Insets.getInsets();
+    let insets = await window.totalpave.Inset.create();
 }
 ```
 

package/docs.md

@@ -8,15 +8,19 @@ This document describes the public API available to library consumers.
 - [1.0 - General Notes](#10---general-notes)
   - [1.1 - TypeScript](#11---typescript)
 - [2.0 - Interfaces](#20---interfaces)
-  - [2.1 - IInsets](#21---iinsets)
-  - [2.2 - IInsetCallbackFunc]()
-- [3.0 - Insets](#30---insets)
-  - [3.1 - addListener](#31---addlistener)
-  - [3.2 - removeListener](#32---removelistener)
-  - [3.3 - getInsets](#33---getinsets)
+  - [2.1 - IInset](#21---iinset)
+  - [2.2 - IInsetCallbackFunc](#22---iinsertcallbackfunc)
+  - [2.3 - IInsetConfiguration](#23---iinsetconfiguration)
+  - [2.4 - InsetMask](#24---insetmask)
+- [3.0 - Inset](#30---inset)
+  - [3.1 - create](#31---create)
+  - [3.2 - free](#32---free)
+  - [3.3 - addListener](#33---addlistener)
+  - [3.4 - removeListener](#34---removelistener)
+  - [3.5 - getInset](#35---getinset)
 
 ## 1.0 - General Notes
-The namespace of this plugin is `totalpave.Insets`. It will become available after the `deviceready` event. Throughout this document, I'll refer to the `totalpave.Insets` object as `Insets`.
+The namespace of this plugin is `window.totalpave.Inset`. It will become available after the `deviceready` event. Throughout this document, I'll refer to the `totalpave.Inset` object as `Inset`.
 
 ### 1.1 - TypeScript
 
@@ -47,23 +51,102 @@ A type that describes the callback signature to [addListener](#31---addlistener)
 type IInsetCallbackFunc = (inset: IInsets) => void;
 ```
 
-## 3.0 - Insets
+### 2.3 - IInsetConfiguration
 
-`Insets` is a static class that provides the APIs to retrieve and to listen for inset changes.
+A type that describes the configuration object used when creating new `Inset` provider instances. All fields are optional.
 
-### 3.1 - addListener
+Structure:
+
+```typescript
+interface IInsetConfiguration {
+  mask?: number;
+  includeRoundedCorners?: boolean;
+}
+```
+
+If `mask` is not set, the default will be `DISPLAY_CUTOUT | SYSTEM_BARS`.
+If `includeRoundedCorners` is not set, the default will be `true`.
+
+### 2.4 - InsetMask
+
+An enumeration of mask values. These correlate to [WindowInsetsCompat.Type](https://developer.android.com/reference/androidx/core/view/WindowInsetsCompat.Type) though the values may not match, they are mapped during runtime.
+
+Currently the following mask values are supported:
+
+- CAPTION_BAR
+- DISPLAY_CUTOUT
+- IME
+- MANDATORY_SYSTEM_GESTURES
+- NAVIGATION_BARS
+- STATUS_BARS
+- SYSTEM_BARS
+- SYSTEM_GESTURES
+- TAPPABLE_ELEMENT
+
+If the android SDK introduces any newer ones, feel free to open a PR.
+
+## 3.0 - Inset
+
+`Inset` is a class that provides the APIs to retrieve and to listen for inset changes. It serves as a provider object and wil hold the configuration state as well as a collection of inset listeners. It is valid to have more than one `Inset` object alive in your application, with different configurations though it will be recommended to keep the instance count low for performance reasons.
+
+Direct access to the `Inset` constructor is forbidden but an instance can be created via the static `create` method. If the `Inset` provider instance is no
+longer used, it should be freed via `Insets.free(inset)` which will clean up
+references to objects and allow them to be garbage collected, both in the webview
+and in the Java/Native runtime. Additionally if your application holds any references to listener functions, they should also be cleaned up.
+
+Note that the configuration parameters cannot be modified on an inset provider
+instance.
+
+### 3.1 - create
+
+Creates a new `Inset` provider object with the given configuration. If the configuration object is missing, default values are used as indicated in [IInsetConfiguration](#23---iinsetconfiguration).
+
+The returned `Inset` instance can be used to attach listeners on for inset
+update notifications. When the provider is no longer needed, it should be freed by calling [free()](#32---free).
+
+Creating `Inset` objects will trigger a layout request, triggering an update on
+all inset providers.
+
+##### Signature
+
+```typescript
+static create(config?: IInsetConfiguration): Promise<Inset>;
+```
+
+### 3.2 - free
+
+Frees an inset provider, cleaning up references to allow objects to be
+garbage collected. Once freed, it will be unhooked from the global listener system
+and that inset provider instance will no longer receive inset updates.
+
+It's the applications responsibility to clean up any retained `IInsetCallbackFunc`
+listener functions.
+
+##### Signature
+
+```typescript
+static free(inset: Inset): Promise<void>;
+```
+
+Alternatively, the inset can be freed by calling the instance member `free`.
+
+```typescript
+free(): Promise<void>;
+```
+
+### 3.3 - addListener
 
 Attaches a new handler which will be invoked when the view layout/inset information changes. The reference of `callback` must be retained by the user for the [removeListener](#32---removelistener) call.
 
-When the callback is invoked, it will receive an [IInsets](#21---iinsets) object as an argument.
+When the callback is invoked, it will receive an [IInset](#21---iinset) object as an argument.
 
 ##### Signature
 
 ```typescript
-static addListener(callback: IInsetCallbackFunc): void;
+addListener(callback: IInsetCallbackFunc): void;
 ```
 
-### 3.2 - removeListener
+### 3.4 - removeListener
 
 Removes an attached handler from the listener pool.
 This will be a no-op if the `callback` is not in the listener pool.
@@ -71,15 +154,15 @@ This will be a no-op if the `callback` is not in the listener pool.
 ##### Signature
 
 ```typescript
-static removeListener(callback: IInsetCallbackFunc): void;
+removeListener(callback: IInsetCallbackFunc): void;
 ```
 
-### 3.3 - getInsets
+### 3.5 - getInset
 
-Returns the last known [IInsets](#21---iinsets) object.
+Returns the last known [IInset](#21---iinset) object.
 
 ##### Signature
 
 ```typescript
-getInsets(): IInsets;
+getInset(): IInset;
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalpave/cordova-plugin-insets",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Cordova Android Plugin to receive native information regarding the unsafe area insets.",
   "main": "www/insets.js",
   "types": "www/api.d.ts",
@@ -30,11 +30,11 @@
     "@rollup/plugin-node-resolve": "15.2.3",
     "@types/cordova": "11.0.3",
     "ejs": "3.1.9",
-    "rollup": "4.6.1",
+    "rollup": "4.9.2",
     "rollup-plugin-progress": "1.1.2",
     "rollup-plugin-typescript2": "0.36.0",
-    "ts-node": "10.9.1",
-    "typescript": "5.3.2"
+    "ts-node": "10.9.2",
+    "typescript": "5.3.3"
   },
   "engines": {
     "cordovaDependencies": {

package/plugin.xml

@@ -2,26 +2,26 @@
 <plugin
   xmlns="http://apache.org/cordova/ns/plugins/1.0"
   id="@totalpave/cordova-plugin-insets"
-  version="0.2.0"
+  version="0.3.1"
 >
   <name>cordova-plugin-insets</name>
   <description>Cordova Android Plugin to receive native information regarding the unsafe area insets</description>
   <author>Total Pave Inc.</author>
   <license>Apache 2.0</license>
   <keywords>cordova,cordova-android,unsafe-inset</keywords>
-  <repo>https://github.com/totalpaveinc/cordova-plugin-unsafe-insets</repo>
+  <repo>https://github.com/totalpaveinc/cordova-plugin-insets</repo>
 
-  <js-module src="www/insets.js" name="Insets">
+  <js-module src="www/insets.js" name="Inset">
     <merges target="totalpave" />
   </js-module>
 
   <platform name="android">
     <config-file target="res/xml/config.xml" parent="/*">
-      <feature name="Insets">
-        <param name="android-package" value="com.totalpave.cordova.insets.Insets" />
+      <feature name="Inset">
+        <param name="android-package" value="com.totalpave.cordova.inset.Inset" />
       </feature>
     </config-file>
 
-    <source-file src="src/android/com/totalpave/cordova/insets/Insets.java" target-dir="src/com/totalpave/cordova/insets" />
+    <source-file src="src/android/com/totalpave/cordova/inset/Inset.java" target-dir="src/com/totalpave/cordova/inset" />
   </platform>
 </plugin>

package/plugin.xml.ejs

@@ -9,19 +9,19 @@
   <author>Total Pave Inc.</author>
   <license>Apache 2.0</license>
   <keywords>cordova,cordova-android,unsafe-inset</keywords>
-  <repo>https://github.com/totalpaveinc/cordova-plugin-unsafe-insets</repo>
+  <repo>https://github.com/totalpaveinc/cordova-plugin-insets</repo>
 
-  <js-module src="www/insets.js" name="Insets">
+  <js-module src="www/insets.js" name="Inset">
     <merges target="totalpave" />
   </js-module>
 
   <platform name="android">
     <config-file target="res/xml/config.xml" parent="/*">
-      <feature name="Insets">
-        <param name="android-package" value="com.totalpave.cordova.insets.Insets" />
+      <feature name="Inset">
+        <param name="android-package" value="com.totalpave.cordova.inset.Inset" />
       </feature>
     </config-file>
 
-    <source-file src="src/android/com/totalpave/cordova/insets/Insets.java" target-dir="src/com/totalpave/cordova/insets" />
+    <source-file src="src/android/com/totalpave/cordova/inset/Inset.java" target-dir="src/com/totalpave/cordova/inset" />
   </platform>
 </plugin>

package/src/android/com/totalpave/cordova/inset/Inset.java

@@ -0,0 +1,337 @@
+/*
+   Copyright 2019 Total Pave Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+package com.totalpave.cordova.inset;
+
+import android.content.res.Configuration;
+import android.content.Context;
+import android.os.Build;
+import android.view.RoundedCorner;
+import android.view.WindowInsets;
+import androidx.core.view.ViewCompat;
+import androidx.core.view.WindowInsetsCompat;
+import org.apache.cordova.CallbackContext;
+import org.apache.cordova.CordovaPlugin;
+import org.apache.cordova.PluginResult.Status;
+import org.apache.cordova.PluginResult;
+import org.json.JSONArray;
+import org.json.JSONObject;
+import org.json.JSONException;
+import java.lang.NumberFormatException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.UUID;
+
+public class Inset extends CordovaPlugin {
+    public static final int DEFAULT_INSET_MASK = WindowInsetsCompat.Type.displayCutout() | WindowInsetsCompat.Type.systemBars();
+    public static final boolean DEFAULT_INCLUDE_ROUNDED_CORNERS = true;
+
+    public static class WebviewMask {
+        private WebviewMask() {}
+
+        public static final int CAPTION_BAR                 = 1;
+        public static final int DISPLAY_CUTOUT              = 1 << 1;
+        public static final int IME                         = 1 << 2;
+        public static final int MANDATORY_SYSTEM_GESTURES   = 1 << 3;
+        public static final int NAVIGATION_BARS             = 1 << 4;
+        public static final int STATUS_BARS                 = 1 << 5;
+        public static final int SYSTEM_BARS                 = 1 << 6;
+        public static final int SYSTEM_GESTURES             = 1 << 7;
+        public static final int TAPPABLE_ELEMENT            = 1 << 8;
+    }
+
+    public static class ListenerConfiguration {
+        public Integer mask;
+        public boolean includeRoundedCorners;
+
+        public ListenerConfiguration() {
+            mask = null;
+            includeRoundedCorners = DEFAULT_INCLUDE_ROUNDED_CORNERS;
+        }
+    }
+
+    public static class Listener {
+        private final Context $context;
+        private final CallbackContext $callback;
+        private JSONObject $currentInset;
+        private final int $mask;
+        private final boolean $includeRoundedCorners;
+        private final UUID $id;
+
+        public Listener(Context context, CallbackContext callback, ListenerConfiguration config) {
+            $id = UUID.randomUUID();
+            $context = context;
+            $callback = callback;
+            if (config.mask == null) {
+                $mask = DEFAULT_INSET_MASK;
+            }
+            else {
+                $mask = $mapMask(config.mask);
+            }
+            $includeRoundedCorners = config.includeRoundedCorners;
+        }
+
+        public String getID() {
+            return $id.toString();
+        }
+
+        public void onInsetUpdate(WindowInsetsCompat insetProvider) {
+            JSONObject result = new JSONObject();
+
+            try {
+                float density = $context.getResources().getDisplayMetrics().density;
+
+                // Ideally, we'd import this, but it shares the same name as our plugin
+                androidx.core.graphics.Insets insets = insetProvider.getInsets($mask);
+
+                double topLeftRadius = 0.0;
+                double topRightRadius = 0.0;
+                double botLeftRadius = 0.0;
+                double botRightRadius = 0.0;
+
+                if ($includeRoundedCorners && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                    WindowInsets sourceInsets = insetProvider.toWindowInsets();
+                    if (sourceInsets != null) {
+                        RoundedCorner topLeft = sourceInsets.getRoundedCorner(RoundedCorner.POSITION_TOP_LEFT);
+                        RoundedCorner topRight = sourceInsets.getRoundedCorner(RoundedCorner.POSITION_TOP_RIGHT);
+                        RoundedCorner botLeft = sourceInsets.getRoundedCorner(RoundedCorner.POSITION_BOTTOM_LEFT);
+                        RoundedCorner botRight = sourceInsets.getRoundedCorner(RoundedCorner.POSITION_BOTTOM_RIGHT);
+
+                        if (topLeft != null) {
+                            int radius = topLeft.getRadius();
+                            topLeftRadius = (double) radius / density;
+                        }
+
+                        if (topRight != null) {
+                            int radius = topRight.getRadius();
+                            topRightRadius = (double) radius / density;
+                        }
+
+                        if (botLeft != null) {
+                            int radius = botLeft.getRadius();
+                            botLeftRadius = (double) radius / density;
+                        }
+
+                        if (botRight != null) {
+                            int radius = botRight.getRadius();
+                            botRightRadius = (double) radius / density;
+                        }
+                    }
+                }
+
+                double top = insets.top / density;
+                double right = insets.right / density;
+                double bottom = insets.bottom / density;
+                double left = insets.left / density;
+
+                // First we will get the screen orientation. This may be locked by the user, so it
+                // may not match the physical orientation. If the orientation cannot be determined,
+                // we will assume PORTRAIT
+                int orientation = Configuration.ORIENTATION_UNDEFINED;
+
+                // There are other orientation types, albeit deprecated and supposedly no longer
+                // used, but this limits us from handling only portrait and landscape.
+                switch ($context.getResources().getConfiguration().orientation) {
+                    case Configuration.ORIENTATION_LANDSCAPE:
+                    case Configuration.ORIENTATION_PORTRAIT:
+                        orientation = $context.getResources().getConfiguration().orientation;
+                        break;
+                    case Configuration.ORIENTATION_SQUARE:
+                    case Configuration.ORIENTATION_UNDEFINED:
+                        // SQUARE is not used anymore since API 16, but included just to satisfy
+                        // lint warnings. If undefined, then fallback to PORTRAIT
+                        orientation = Configuration.ORIENTATION_PORTRAIT;
+                        break;
+                }
+
+                // Insets do not include rounded corner radius. If an inset is present, it
+                // generally will be big enough to cover the rounded corner. This is a coincidence,
+                // not a designed thing. In either case, we need to determine how much space is
+                // required to cover the rounded corner and take the higher between the inset and
+                // the rounded corner.
+
+                // If portrait, then top-left & top-right is applied to the top inset,
+                // and bot-left & bot-right is applied to the bottom inset
+                if (orientation == Configuration.ORIENTATION_PORTRAIT) {
+                    top = Math.max(Math.max(top, topLeftRadius), topRightRadius);
+                    bottom = Math.max(Math.max(bottom, botLeftRadius), botRightRadius);
+                }
+                else {
+                    left = Math.max(Math.max(left, topLeftRadius), botLeftRadius);
+                    right = Math.max(Math.max(right, topRightRadius), botRightRadius);
+                }
+
+                result.put("top", top);
+                result.put("right", right);
+                result.put("bottom", bottom);
+                result.put("left", left);
+            }
+            catch (JSONException e) {
+                e.printStackTrace();
+                return;
+            }
+
+            this.$currentInset = result;
+
+            JSONObject update = new JSONObject();
+            try {
+                update.put("type", "update");
+                update.put("id", this.getID());
+                update.put("data", this.$currentInset);
+            }
+            catch (JSONException ex) {
+                throw new RuntimeException(ex);
+            }
+
+            PluginResult response = new PluginResult(Status.OK, update);
+            response.setKeepCallback(true);
+            $callback.sendPluginResult(response);
+        }
+
+        private int $mapMask(int webviewMask) {
+            int insetTypeMask = 0;
+
+            if ((webviewMask & WebviewMask.CAPTION_BAR) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.captionBar();
+            }
+
+            if ((webviewMask & WebviewMask.DISPLAY_CUTOUT) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.displayCutout();
+            }
+
+            if ((webviewMask & WebviewMask.IME) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.ime();
+            }
+
+            if ((webviewMask & WebviewMask.MANDATORY_SYSTEM_GESTURES) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.mandatorySystemGestures();
+            }
+
+            if ((webviewMask & WebviewMask.NAVIGATION_BARS) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.navigationBars();
+            }
+
+            if ((webviewMask & WebviewMask.STATUS_BARS) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.statusBars();
+            }
+
+            if ((webviewMask & WebviewMask.SYSTEM_BARS) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.systemBars();
+            }
+
+            if ((webviewMask & WebviewMask.SYSTEM_GESTURES) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.systemGestures();
+            }
+
+            if ((webviewMask & WebviewMask.TAPPABLE_ELEMENT) != 0) {
+                insetTypeMask |= WindowInsetsCompat.Type.tappableElement();
+            }
+
+            return insetTypeMask;
+        }
+    }
+
+    private ArrayList<Listener> $listeners;
+    private HashMap<String, Listener> $listenerMap;
+    private final Object $listenerLock = new Object();
+
+    @Override
+    protected void pluginInitialize() {
+        $listeners = new ArrayList<>();
+        $listenerMap = new HashMap<>();
+        
+        ViewCompat.setOnApplyWindowInsetsListener(
+                this.cordova.getActivity().findViewById(android.R.id.content), (v, insetProvider) -> {
+
+                    synchronized($listenerLock) {
+                        for (Listener listener : $listeners) {
+                            listener.onInsetUpdate(insetProvider);
+                        }
+                    }
+
+                    return WindowInsetsCompat.CONSUMED;
+                }
+        );
+    }
+
+    private void $createNewListener(CallbackContext callback, JSONArray args) {
+        ListenerConfiguration config = new ListenerConfiguration();
+
+        try {
+            JSONObject params = args.getJSONObject(0);
+            if (params.has("mask")) {
+                config.mask = params.getInt("mask");
+            }
+            if (params.has("includeRoundedCorners")) {
+                config.includeRoundedCorners = params.getBoolean("includeRoundedCorners");
+            }
+        }
+        catch (JSONException ex) {
+            ex.printStackTrace();
+            callback.error(ex.getMessage());
+            return;
+        }
+        Listener listener = new Listener(cordova.getActivity(), callback, config);
+        synchronized ($listenerLock) {
+            $listeners.add(listener);
+            $listenerMap.put(listener.getID(), listener);
+        }
+
+        cordova.getActivity().runOnUiThread(() -> {
+            ViewCompat.requestApplyInsets(cordova.getActivity().findViewById(android.R.id.content));
+        });
+
+        JSONObject responseData = new JSONObject();
+        try {
+            responseData.put("type", "init");
+            responseData.put("data", listener.getID());
+        }
+        catch(JSONException e) {
+            throw new RuntimeException("Could not build listener creation response", e);
+        }
+
+        PluginResult result = new PluginResult(Status.OK, responseData);
+        result.setKeepCallback(true);
+        callback.sendPluginResult(result);
+    }
+
+    private void $freeListener(CallbackContext callback, JSONArray args) throws JSONException {
+        String id = args.getString(0);
+
+        synchronized ($listenerLock) {
+            Listener listener = $listenerMap.remove(id);
+            if (listener != null) {
+                $listeners.remove(listener);
+            }
+        }
+
+        callback.success();
+    }
+
+    @Override
+    public boolean execute(String action, JSONArray args, CallbackContext callback) throws JSONException, NumberFormatException {
+        if (action.equals("create")) {
+            $createNewListener(callback, args);
+            return true;
+        }
+        else if (action.equals("delete")) {
+            $freeListener(callback, args);
+            return true;
+        }
+
+        return false;
+    }
+}

package/src/www/IInset.ts

@@ -0,0 +1,22 @@
+/*
+   Copyright 2022-2024 Total Pave Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+export interface IInset {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}