@capawesome/capacitor-screen-orientation 8.0.1 → 8.0.2

package/README.md

@@ -1,4 +1,4 @@
-# @capawesome/capacitor-screen-orientation
+# Capacitor Screen Orientation Plugin
 
 Capacitor plugin to lock/unlock the screen orientation.
 
@@ -10,7 +10,7 @@ Capacitor plugin to lock/unlock the screen orientation.
 
 ## Features
 
-We are proud to offer one of the most complete and feature-rich Capacitor plugins for screen orientation control. Here are some of the key features:
+The Capacitor Screen Orientation plugin is one of the most complete orientation control solutions for Capacitor apps. Here are some of the key features:
 
 - 🖥️ **Cross-platform**: Supports Android, iOS, and Web.
 - 🔒 **Orientation locking**: Lock screen to specific orientations.
@@ -20,13 +20,20 @@ We are proud to offer one of the most complete and feature-rich Capacitor plugin
 - 📢 **Event listeners**: Listen to orientation change events.
 - 📐 **Fine-grained control**: Primary and secondary orientation modes.
 - 🍎 **iPad support**: Special configuration for iPad orientation locking.
+- 🤝 **Compatibility**: Works alongside the [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/), [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/) and [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/) plugins.
 - 🔁 **Up-to-date**: Always supports the latest Capacitor version.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The Screen Orientation plugin is typically used whenever certain screens of an app only work well in a specific orientation, for example:
+
+- **Video players**: Lock the screen to landscape for fullscreen video playback.
+- **Games**: Keep the game in a fixed orientation regardless of how the device is held.
+- **Camera and scanner screens**: Lock the screen to portrait while capturing photos or scanning codes.
+- **Forms and reading views**: Prevent accidental rotation while the user is typing or reading.
+- **Responsive layouts**: React to orientation changes with the `screenOrientationChange` event to adapt your UI.
 
 ## Compatibility
 
@@ -39,6 +46,21 @@ Stay up to date with the latest news and updates about the Capawesome, Capacitor
 
 ## Installation
 
+You can use our **AI-Assisted Setup** to install the plugin.
+Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:
+
+```bash
+npx skills add capawesome-team/skills --skill capacitor-plugins
+```
+
+Then use the following prompt:
+
+```
+ Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-screen-orientation` plugin in my project.
+```
+
+If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:
+
 ```bash
 npm install @capawesome/capacitor-screen-orientation
 npx cap sync
@@ -51,7 +73,7 @@ npx cap sync
 On iOS you must add the following to your app's `AppDelegate.swift`:
 
 ```diff
-+ import CapawesomeCapacitorScreenOrientation
++ import ScreenOrientationPlugin
 
 @UIApplicationMain
 class AppDelegate: UIResponder, UIApplicationDelegate {
@@ -61,6 +83,12 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
 + }
 ```
 
+If your project still uses CocoaPods instead of Swift Package Manager (SPM), import `CapawesomeCapacitorScreenOrientation` rather than `ScreenOrientationPlugin`:
+
+```diff
++ import CapawesomeCapacitorScreenOrientation
+```
+
 #### iPad Orientation Lock
 
 On iPad, you must add the following to your app's `Info.plist`:
@@ -80,16 +108,38 @@ A working example can be found here: [robingenz/capacitor-plugin-demo](https://g
 
 ## Usage
 
+The following examples show how to lock, unlock, and read the current screen orientation.
+
+### Lock the screen orientation
+
+Lock the device to a specific orientation, for example landscape. Besides `LANDSCAPE` and `PORTRAIT`, you can also lock to a primary or secondary mode such as `LANDSCAPE_PRIMARY` for fine-grained control:
+
 ```typescript
 import { ScreenOrientation, OrientationType } from '@capawesome/capacitor-screen-orientation';
 
 const lock = async () => {
   await ScreenOrientation.lock({ type: OrientationType.LANDSCAPE });
 };
+```
+
+### Unlock the screen orientation
+
+Remove the orientation lock and restore automatic rotation:
+
+```typescript
+import { ScreenOrientation } from '@capawesome/capacitor-screen-orientation';
 
 const unlock = async () => {
   await ScreenOrientation.unlock();
 };
+```
+
+### Get the current screen orientation
+
+Read the current orientation type of the device:
+
+```typescript
+import { ScreenOrientation } from '@capawesome/capacitor-screen-orientation';
 
 const getCurrentOrientation = async () => {
   const result = await ScreenOrientation.getCurrentOrientation();
@@ -240,6 +290,43 @@ Callback to receive the screen orientation change notifications.
 
 </docgen-api>
 
+## FAQ
+
+### Why does the orientation lock not work on iPad?
+
+For the orientation lock to work on iPad, you must add the `UIRequiresFullScreen` key with the value `true` to your app's `Info.plist` file, as described in the [Installation](#installation) section. Also make sure that you have applied the required changes to your `AppDelegate.swift`.
+
+### Do I need to modify my AppDelegate on iOS?
+
+Yes. You must implement the `supportedInterfaceOrientationsFor` method in your app's `AppDelegate.swift` and return `ScreenOrientation.getSupportedInterfaceOrientations()`, as shown in the [Installation](#installation) section. Without this change, the orientation lock has no effect on iOS.
+
+### What is the difference between LANDSCAPE and LANDSCAPE_PRIMARY?
+
+The `LANDSCAPE` type covers both landscape modes, so the device can be rotated between landscape-primary and landscape-secondary while locked. The `LANDSCAPE_PRIMARY` and `LANDSCAPE_SECONDARY` types lock the screen to exactly one of the two landscape modes. The same applies to `PORTRAIT`, `PORTRAIT_PRIMARY` and `PORTRAIT_SECONDARY`.
+
+### How do I restore automatic rotation after locking the orientation?
+
+Simply call the `unlock()` method. It removes the orientation lock so that the device rotates automatically again based on the user's device settings.
+
+### How can I react to orientation changes?
+
+Add a listener for the `screenOrientationChange` event using the `addListener(...)` method. The listener receives the new orientation type every time the screen orientation changes. Use `removeAllListeners()` to remove all listeners when you no longer need them.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [Home Indicator](https://capawesome.io/docs/sdks/capacitor/home-indicator/): Hide and show the iOS home indicator.
+- [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/): Keep the screen awake, for example during video playback.
+- [Navigation Bar](https://capawesome.io/docs/sdks/capacitor/navigation-bar/): Set the background color and button style of the Android navigation bar.
+- [Screen Brightness](https://capawesome.io/docs/sdks/capacitor/screen-brightness/): Read and control the screen brightness.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/screen-orientation/CHANGELOG.md).

package/ios/Plugin/ScreenOrientation.swift

@@ -8,6 +8,10 @@ import Capacitor
     private var currentOrientationType: String?
     private var lastOrientationType: String?
 
+    private var windowScene: UIWindowScene? {
+        return plugin.bridge?.viewController?.view.window?.windowScene
+    }
+
     init(plugin: ScreenOrientationPlugin) {
         self.plugin = plugin
         super.init()
@@ -70,7 +74,7 @@ import Capacitor
 
     @objc private func requestGeometryUpdate(orientationValue: Int, orientationMask: UIInterfaceOrientationMask) {
         if #available(iOS 16, *) {
-            let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene
+            let windowScene = self.windowScene
             windowScene?.keyWindow?.rootViewController?.setNeedsUpdateOfSupportedInterfaceOrientations()
             windowScene?.requestGeometryUpdate(.iOS(interfaceOrientations: orientationMask)) { error in
                 CAPLog.print("requestGeometryUpdate failed.", error)
@@ -122,7 +126,7 @@ import Capacitor
         case UIInterfaceOrientation.portraitUpsideDown.rawValue:
             return UIInterfaceOrientationMask.portraitUpsideDown
         default:
-            let isPortrait = UIApplication.shared.windows.first?.windowScene?.interfaceOrientation.isPortrait ?? false
+            let isPortrait = windowScene?.interfaceOrientation.isPortrait ?? false
             return isPortrait ? UIInterfaceOrientationMask.portrait : UIInterfaceOrientationMask.landscape
         }
     }
@@ -176,7 +180,7 @@ import Capacitor
         case UIInterfaceOrientation.portraitUpsideDown.rawValue:
             return "portrait-secondary"
         default:
-            let isPortrait = UIApplication.shared.windows.first?.windowScene?.interfaceOrientation.isPortrait ?? false
+            let isPortrait = windowScene?.interfaceOrientation.isPortrait ?? false
             return isPortrait ? "portrait-primary" : "landscape-primary"
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-screen-orientation",
-  "version": "8.0.1",
-  "description": "Capacitor plugin to lock/unlock the screen orientation.",
+  "version": "8.0.2",
+  "description": "Capacitor plugin to lock/unlock the screen orientation on Android, iOS, and Web.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -33,7 +33,7 @@
       "url": "https://opencollective.com/capawesome"
     }
   ],
-  "homepage": "https://capawesome.io/plugins/screen-orientation/",
+  "homepage": "https://capawesome.io/docs/sdks/capacitor/screen-orientation/",
   "keywords": [
     "capacitor",
     "plugin",
@@ -42,7 +42,14 @@
     "android",
     "ios",
     "web",
-    "screen orientation"
+    "screen orientation",
+    "capacitor-plugin",
+    "orientation lock",
+    "lock orientation",
+    "landscape",
+    "portrait",
+    "screen rotation",
+    "device orientation"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",
@@ -64,24 +71,21 @@
   },
   "devDependencies": {
     "@capacitor/android": "8.0.0",
-    "@capacitor/cli": "8.0.0",
+    "@capacitor/cli": "8.4.2",
     "@capacitor/core": "8.0.0",
     "@capacitor/docgen": "0.3.1",
     "@capacitor/ios": "8.0.0",
     "@ionic/eslint-config": "0.4.0",
-    "@ionic/swiftlint-config": "2.0.0",
     "eslint": "8.57.0",
-    "prettier": "3.4.2",
-    "prettier-plugin-java": "2.6.7",
+    "prettier-plugin-java": "2.9.7",
     "rimraf": "6.1.2",
-    "rollup": "4.53.3",
+    "rollup": "4.62.3",
     "swiftlint": "2.0.0",
     "typescript": "5.9.3"
   },
   "peerDependencies": {
     "@capacitor/core": ">=8.0.0"
   },
-  "swiftlint": "@ionic/swiftlint-config",
   "eslintConfig": {
     "extends": "@ionic/eslint-config/recommended"
   },