Web: return MonitorHandle in Window::fullscreen() (#3861)

- Change `OrientationData::natural` type from `bool` to `Orientation`, just telling the user what the natural orientation is.
- Fix and improve some monitor related documentation.

src/changelog/unreleased.md

@@ -51,8 +51,11 @@ changelog entry.
   Without prompting the user for permission, only the current monitor is returned. But when
   prompting and being granted permission through
   `ActiveEventLoop::request_detailed_monitor_permission()`, access to all monitors and their
-  information is available. This "detailed monitors" can be used in `Window::set_fullscreen()` as
+  details is available. Handles created with "detailed monitor permissions" can be used in
-  well.
+  `Window::set_fullscreen()` as well.
+  
+  Keep in mind that handles do not auto-upgrade after permissions are granted and have to be
+  re-created to make full use of this feature.
 - Add `Touch::finger_id` with a new type `FingerId`.
 - On Web and Windows, add `FingerIdExt*::is_primary()`, exposing a way to determine
   the primary finger in a multi-touch interaction.

src/platform/web.rs

@@ -699,10 +699,9 @@ pub struct OrientationData {
     pub orientation: Orientation,
     /// [`true`] if the [`orientation`](Self::orientation) is flipped upside down.
     pub flipped: bool,
-    /// [`true`] if the [`Orientation`] is the most natural one for the screen regardless of being
+    /// The most natural orientation for the screen. Computer monitors are commonly naturally
-    /// flipped. Computer monitors are commonly naturally landscape mode, while mobile phones
+    /// landscape mode, while mobile phones are commonly naturally portrait mode.
-    /// are commonly naturally portrait mode.
+    pub natural: Orientation,
-    pub natural: bool,
 }
 
 /// Screen orientation.
@@ -726,14 +725,14 @@ pub enum OrientationLock {
     /// User is locked to landscape mode.
     Landscape {
         /// - [`None`]: User is locked to both upright or upside down landscape mode.
-        /// - [`false`]: User is locked to upright landscape mode.
+        /// - [`true`]: User is locked to upright landscape mode.
         /// - [`false`]: User is locked to upside down landscape mode.
         flipped: Option<bool>,
     },
     /// User is locked to portrait mode.
     Portrait {
         /// - [`None`]: User is locked to both upright or upside down portrait mode.
-        /// - [`false`]: User is locked to upright portrait mode.
+        /// - [`true`]: User is locked to upright portrait mode.
         /// - [`false`]: User is locked to upside down portrait mode.
         flipped: Option<bool>,
     },

src/platform_impl/web/monitor.rs

@@ -322,22 +322,22 @@ impl Inner {
             OrientationType::LandscapePrimary => OrientationData {
                 orientation: Orientation::Landscape,
                 flipped: false,
-                natural: angle == 0,
+                natural: if angle == 0 { Orientation::Landscape } else { Orientation::Portrait },
             },
             OrientationType::LandscapeSecondary => OrientationData {
                 orientation: Orientation::Landscape,
                 flipped: true,
-                natural: angle == 180,
+                natural: if angle == 180 { Orientation::Landscape } else { Orientation::Portrait },
             },
             OrientationType::PortraitPrimary => OrientationData {
                 orientation: Orientation::Portrait,
                 flipped: false,
-                natural: angle == 0,
+                natural: if angle == 0 { Orientation::Portrait } else { Orientation::Landscape },
             },
             OrientationType::PortraitSecondary => OrientationData {
                 orientation: Orientation::Portrait,
                 flipped: true,
-                natural: angle == 180,
+                natural: if angle == 180 { Orientation::Portrait } else { Orientation::Landscape },
             },
             _ => {
                 unreachable!("found unrecognized orientation: {}", orientation.type_string())

src/platform_impl/web/window.rs

@@ -312,7 +312,7 @@ impl Inner {
     #[inline]
     pub(crate) fn fullscreen(&self) -> Option<Fullscreen> {
         if self.canvas.is_fullscreen() {
-            Some(Fullscreen::Borderless(None))
+            Some(Fullscreen::Borderless(Some(self.monitor.current_monitor())))
         } else {
             None
         }

src/window.rs

@@ -1151,7 +1151,7 @@ impl Window {
     /// - **iOS:** Can only be called on the main thread.
     /// - **Android / Orbital:** Will always return `None`.
     /// - **Wayland:** Can return `Borderless(None)` when there are no monitors.
-    /// - **Web:** Can only return `None` or `Borderless(None)`.
+    /// - **Web:** Can only return `None` or `Borderless`.
     #[inline]
     pub fn fullscreen(&self) -> Option<Fullscreen> {
         let _span = tracing::debug_span!("winit::Window::fullscreen",).entered();