@totalpave/cordova-plugin-insets 0.4.1 → 0.4.2

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.1",
+  "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.1"
+  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>
     

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>