feat(api): add logical monitor bounds to the Monitor object (#15520)

* feat(api): add logical monitor bounds to the Monitor object

* docs(api): document physical pixel units on Monitor fields

Replaces the logicalPosition/logicalSize/logicalWorkArea fields with JSDoc
on Monitor.size, Monitor.position and Monitor.workArea stating the values
are in physical pixels, including examples converting to the logical pixels
expected by window creation options.

* fix monitor position example null check

Author: polw1

.changes/monitor-logical-bounds.md

@@ -0,0 +1,5 @@
+---
+"@tauri-apps/api": "patch:enhance"
+---
+
+Document that `Monitor.size`, `Monitor.position` and `Monitor.workArea` are in physical pixels, with examples showing how to convert them to the logical pixels expected by window creation options via `toLogical(monitor.scaleFactor)`.

packages/api/src/window.ts

@@ -47,16 +47,46 @@ import { Image, transformImage } from './image'
 export interface Monitor {
   /** Human-readable name of the monitor */
   name: string | null
-  /** The monitor's resolution. */
+  /**
+   * The monitor's resolution in physical pixels.
+   *
+   * Use {@linkcode Monitor.scaleFactor} to convert to logical pixels:
+   * ```typescript
+   * const logicalSize = monitor.size.toLogical(monitor.scaleFactor);
+   * ```
+   */
   size: PhysicalSize
-  /** the Top-left corner position of the monitor relative to the larger full screen area. */
+  /**
+   * the Top-left corner position of the monitor relative to the larger full screen area, in physical pixels.
+   *
+   * Note that window creation options such as `x`, `y`, `width` and `height` expect
+   * logical pixels, so convert with {@linkcode Monitor.scaleFactor} first:
+   * ```typescript
+   * import { currentMonitor } from '@tauri-apps/api/window';
+   * import { WebviewWindow } from '@tauri-apps/api/webviewWindow';
+   *
+   * const monitor = await currentMonitor();
+   * if (monitor) {
+   *   const position = monitor.position.toLogical(monitor.scaleFactor);
+   *   const webview = new WebviewWindow('my-label', { x: position.x, y: position.y });
+   * }
+   * ```
+   */
   position: PhysicalPosition
-  /** The monitor's work area. */
+  /**
+   * The monitor's work area (the monitor area excluding taskbars and docks) in physical pixels.
+   *
+   * Use {@linkcode Monitor.scaleFactor} to convert to logical pixels as shown in
+   * {@linkcode Monitor.position}.
+   */
   workArea: {
     position: PhysicalPosition
     size: PhysicalSize
   }
-  /** The scale factor that can be used to map physical pixels to logical pixels. */
+  /**
+   * The scale factor that can be used to map physical pixels to logical pixels,
+   * e.g. `monitor.position.toLogical(monitor.scaleFactor)`.
+   */
   scaleFactor: number
 }