@totalpave/cordova-plugin-insets 0.4.0 → 0.4.2

package/README.md

@@ -8,6 +8,10 @@ On iOS, in rare circumstances the CSS safe area inset variables may resolve to i
 
 This plugin provides a work around to obtain these values in javascript. You will have to implement your own javascript code to actually start using these values in your CSS.
 
+## Installation
+
+`cordova plugin add @totalpave/cordova-plugin-insets`
+
 ## Supported Platforms
 
 - Android

package/docs.md

@@ -18,6 +18,7 @@ This document describes the public API available to library consumers.
   - [3.3 - addListener](#33---addlistener)
   - [3.4 - removeListener](#34---removelistener)
   - [3.5 - getInset](#35---getinset)
+- [4.0 - Sample Code](#40---sample-code)
 
 ## 1.0 - General Notes
 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`.
@@ -168,3 +169,44 @@ Returns the last known [IInset](#21---iinset) object.
 ```typescript
 getInset(): IInset;
 ```
+
+## 4.0 - Sample Code
+
+The plugin concerns itself with reporting safe area values. How the app consumes them is entirely up to the app. A very basic example that goes straight to the point would look something like this:
+
+```js
+let insetProvider = await window.totalpave.Inset.create();
+insetProvider.addListener((insets) => {
+    let bottomOffset = insets.bottom;
+
+    let myDiv = document.getElementById('myDiv').style.marginBottom = bottomOffset + 'px';
+});
+```
+
+However, styling a lot of UI directly in the JS isn't very ideal, so a better method is to read the inset reports and set CSS variables which is then accessible from your CSS:
+
+```js
+let insetProvider = await window.totalpave.Inset.create();
+insetProvider.addListener((insets) => {
+    let r = document.querySelector(':root');
+
+    r.style.setProperty('--my-inset-top', `${insets.top}px`);
+    r.style.setProperty('--my-inset-bottom', `${insets.bottom}px`);
+    r.style.setProperty('--my-inset-left', `${insets.left}px`);
+    r.style.setProperty('--my-inset-right', `${insets.right}px`);
+});
+```
+
+This sets variables that can be referenced from CSS:
+
+```css
+#myDiv {
+    margin-bottom: var(--my-inset-bottom, env(safe-area-inset-bottom));
+}
+```
+
+Of course you can use `var(--my-inset-bottom)` anywhere you see fit in CSS, inside padding directives, or top/left/right/botton directives, etc...
+
+If `--my-inset-bottom` is not set, it falls back to the webview environment variable `env(safe-area-inset-bottom)`, useful if you're sharing web code between cordova and other web environments like a standard website.
+
+If you use a CSS preprocessor like Less, Stylus or Sass. It may be smart to create a macro to abstract the usages of the custom variable. There may be a time where this plugin becomes completely unnecessary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalpave/cordova-plugin-insets",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Cordova Android Plugin to receive native information regarding the unsafe area insets.",
   "main": "www/insets.js",
   "types": "www/api.d.ts",
@@ -26,16 +26,16 @@
   },
   "homepage": "https://github.com/totalpaveinc/cordova-plugin-insets#readme",
   "devDependencies": {
-    "@rollup/plugin-commonjs": "28.0.6",
+    "@rollup/plugin-commonjs": "29.0.0",
     "@rollup/plugin-node-resolve": "16.0.1",
     "@types/cordova": "11.0.3",
     "@types/node": "24.3.1",
-    "ejs": "3.1.10",
-    "rollup": "4.50.1",
+    "ejs": "4.0.1",
+    "rollup": "4.57.1",
     "rollup-plugin-progress": "1.1.2",
     "rollup-plugin-typescript2": "0.36.0",
     "ts-node": "10.9.2",
-    "typescript": "5.9.2"
+    "typescript": "5.9.3"
   },
   "engines": {
     "cordovaDependencies": {

package/plugin.xml

@@ -2,7 +2,7 @@
 <plugin
   xmlns="http://apache.org/cordova/ns/plugins/1.0"
   id="@totalpave/cordova-plugin-insets"
-  version="0.4.0"
+  version="0.4.2"
 >
   <name>cordova-plugin-insets</name>
   <description>Cordova Android Plugin to receive native information regarding the unsafe area insets</description>
@@ -19,6 +19,7 @@
     <config-file target="res/xml/config.xml" parent="/*">
     <feature name="Inset">
       <param name="android-package" value="com.totalpave.cordova.inset.Inset" />
+      <param name="onload" value="true" />
     </feature>
   </config-file>
     <source-file src="src/android/com/totalpave/cordova/inset/Inset.java" target-dir="src/com/totalpave/cordova/inset" />
@@ -28,6 +29,7 @@
     <config-file target="config.xml" parent="/*">
       <feature name="Inset">
         <param name="ios-package" value="TPIInset" />
+        <param name="onload" value="true" />
       </feature>
     </config-file>
     
@@ -36,5 +38,8 @@
 
     <header-file src="src/ios/TPIInsetObserver.h" target-dir="totalpave/insets" />
     <source-file src="src/ios/TPIInsetObserver.m" target-dir="totalpave/insets" />
+
+    <header-file src="src/ios/TPIInsetObserverController.h" target-dir="totalpave/insets" />
+    <source-file src="src/ios/TPIInsetObserverController.m" target-dir="totalpave/insets" />
   </platform>
 </plugin>

package/plugin.xml.ejs

@@ -19,6 +19,7 @@
     <config-file target="res/xml/config.xml" parent="/*">
     <feature name="Inset">
       <param name="android-package" value="com.totalpave.cordova.inset.Inset" />
+      <param name="onload" value="true" />
     </feature>
   </config-file>
     <source-file src="src/android/com/totalpave/cordova/inset/Inset.java" target-dir="src/com/totalpave/cordova/inset" />
@@ -28,6 +29,7 @@
     <config-file target="config.xml" parent="/*">
       <feature name="Inset">
         <param name="ios-package" value="TPIInset" />
+        <param name="onload" value="true" />
       </feature>
     </config-file>
     
@@ -36,5 +38,8 @@
 
     <header-file src="src/ios/TPIInsetObserver.h" target-dir="totalpave/insets" />
     <source-file src="src/ios/TPIInsetObserver.m" target-dir="totalpave/insets" />
+
+    <header-file src="src/ios/TPIInsetObserverController.h" target-dir="totalpave/insets" />
+    <source-file src="src/ios/TPIInsetObserverController.m" target-dir="totalpave/insets" />
   </platform>
 </plugin>

package/src/ios/TPIInset.m

@@ -16,24 +16,19 @@
 
 #import <Foundation/Foundation.h>
 #import "TPIInset.h"
-#import "TPIInsetObserver.h"
+#import "TPIInsetObserverController.h"
 #import <UIKit/UIKit.h>
 
 @implementation TPIInset {
     NSMutableDictionary* $listeners;
-    TPIInsetObserver* $observer;
+    TPIInsetObserverController* $observer;
 }
 
 - (void) pluginInitialize {
-    self->$listeners = [[NSMutableDictionary alloc] init];
-    self->$observer = [[TPIInsetObserver alloc] init];
-    self->$observer.frame = self.viewController.view.frame;
-    self->$observer.userInteractionEnabled = false;
-    self->$observer.translatesAutoresizingMaskIntoConstraints = false;
-    
     __weak TPIInset* weakSelf = self;
     
-    self->$observer.safeAreaChanged = ^(UIEdgeInsets insets) {
+    self->$listeners = [[NSMutableDictionary alloc] init];
+    self->$observer = [[TPIInsetObserverController alloc] initWithSAICallback:^(UIEdgeInsets insets) {
         TPIInset* strongSelf = weakSelf;
         
         if (strongSelf == nil) {
@@ -46,24 +41,28 @@
                 [strongSelf emitInsetChange: value inset: insets];
             }
         }
-    };
+    }];
     
-    [self.viewController.view addSubview: self->$observer];
+    [self.viewController addChildViewController: self->$observer];
+
+    [self.viewController.view addSubview: self->$observer.view];
     
     [NSLayoutConstraint activateConstraints:@[
-        [self->$observer.topAnchor constraintEqualToAnchor:self.viewController.view.topAnchor],
-        [self->$observer.bottomAnchor constraintEqualToAnchor:self.viewController.view.bottomAnchor],
-        [self->$observer.leadingAnchor constraintEqualToAnchor:self.viewController.view.leadingAnchor],
-        [self->$observer.trailingAnchor constraintEqualToAnchor:self.viewController.view.trailingAnchor],
+        [self->$observer.view.topAnchor constraintEqualToAnchor:self.viewController.view.topAnchor],
+        [self->$observer.view.bottomAnchor constraintEqualToAnchor:self.viewController.view.bottomAnchor],
+        [self->$observer.view.leadingAnchor constraintEqualToAnchor:self.viewController.view.leadingAnchor],
+        [self->$observer.view.trailingAnchor constraintEqualToAnchor:self.viewController.view.trailingAnchor],
     ]];
+    
+    [self->$observer didMoveToParentViewController: self.viewController];
 }
 
 - (void) emitInsetChange:(NSDictionary*) listener inset:(UIEdgeInsets) inset {
     NSString* callbackID = [listener objectForKey: @"callbackID"];
-    
     if (callbackID == nil) return;
     
     NSString* ident = [listener objectForKey:@"id"];
+    
     if (ident == nil) return;
     
     NSDictionary* payload = @{
@@ -82,14 +81,6 @@
     [self.commandDelegate sendPluginResult: result callbackId: callbackID];
 }
 
-- (UIEdgeInsets) $getViewInsets {
-    if (self.viewController.viewIfLoaded == nil) {
-        return UIEdgeInsetsMake(0.0f, 0.0f, 0.0f, 0.0f);
-    }
-    
-    return self.viewController.view.safeAreaInsets;
-}
-
 - (void) create:(CDVInvokedUrlCommand*) command {
     NSString* ident = [[NSUUID UUID] UUIDString];
     
@@ -110,7 +101,7 @@
     
     [self.commandDelegate sendPluginResult: result callbackId: command.callbackId];
     
-    [self emitInsetChange: listener inset: self->$observer.safeAreaInsets];
+    [self emitInsetChange: listener inset: self->$observer.view.safeAreaInsets];
 }
 
 - (void) delete:(CDVInvokedUrlCommand*) command {
@@ -125,8 +116,11 @@
 }
 
 - (void) dealloc {
-    [self->$observer removeFromSuperview];
+    [self->$observer willMoveToParentViewController: nil];
+    [self->$observer.view removeFromSuperview];
+    [self->$observer removeFromParentViewController];
     self->$observer.safeAreaChanged = nil;
+    self->$observer = nil;
 }
 
 @end

package/src/ios/TPIInsetObserverController.h

@@ -0,0 +1,37 @@
+/*
+   Copyright 2026 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.
+*/
+
+#ifndef TPIInsetObserverController_h
+#define TPIInsetObserverController_h
+
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+typedef void (^TPIInsetSAICallback)(UIEdgeInsets insets);
+
+@interface TPIInsetObserverController: UIViewController
+
+@property (nonatomic, copy) TPIInsetSAICallback safeAreaChanged;
+
+- (instancetype) init NS_UNAVAILABLE;
+- (instancetype) initWithNibName:(NSString*) nib bundle:(NSBundle*) bundle NS_UNAVAILABLE;
+- (instancetype) initWithCoder:(NSCoder*) code NS_UNAVAILABLE;
+
+- (instancetype) initWithSAICallback:(TPIInsetSAICallback) callback NS_DESIGNATED_INITIALIZER;
+
+@end
+
+#endif

package/src/ios/TPIInsetObserverController.m

@@ -0,0 +1,57 @@
+/*
+   Copyright 2026 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.
+*/
+
+#import <Foundation/Foundation.h>
+#import "TPIInsetObserverController.h"
+#import "TPIInsetObserver.h"
+
+@implementation TPIInsetObserverController : UIViewController
+
+- (instancetype) initWithSAICallback:(TPIInsetSAICallback) callback {
+    self = [super initWithNibName: nil bundle: nil];
+    
+    self.safeAreaChanged = callback;
+    
+    return self;
+}
+
+- (void) loadView {
+    TPIInsetObserver* view = [[TPIInsetObserver alloc] initWithFrame:[UIScreen mainScreen].bounds];
+    view.safeAreaChanged = self.safeAreaChanged;
+    view.userInteractionEnabled = false;
+    view.translatesAutoresizingMaskIntoConstraints = false;
+    self.view = view;
+}
+
+- (void) viewDidLoad {
+    [super viewDidLoad];
+    UIView* parent = self.view.superview;
+    if (!parent) return;
+    
+    [NSLayoutConstraint activateConstraints:@[
+        [self.view.topAnchor constraintEqualToAnchor:parent.topAnchor],
+        [self.view.bottomAnchor constraintEqualToAnchor:parent.bottomAnchor],
+        [self.view.leadingAnchor constraintEqualToAnchor:parent.leadingAnchor],
+        [self.view.trailingAnchor constraintEqualToAnchor:parent.trailingAnchor],
+    ]];
+}
+
+- (void) dealloc {
+    self.safeAreaChanged = nil;
+    self.view = nil;
+}
+
+@end