From 2be3d9a44f5d57276622ba2cde18cac5bb99f81a Mon Sep 17 00:00:00 2001
From: "Menard, Alexis" <alexis.menard@intel.com>
Date: Fri, 12 Jul 2024 10:07:15 -0400
Subject: [PATCH] [css-viewport] Add the segments property (#9237).

This property exposes in JavaScript what is already exposed to
CSS via env() variables.

TAG review w3ctag/design-reviews#689.

CSSWG Approval: #9237#issuecomment-2160730855

Fixes #9237.
---
 css-viewport-1/Overview.bs | 46 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/css-viewport-1/Overview.bs b/css-viewport-1/Overview.bs
index f335a2193f7..af172a9b73e 100644
--- a/css-viewport-1/Overview.bs
+++ b/css-viewport-1/Overview.bs
@@ -526,6 +526,52 @@ The <dfn export>unscaled</dfn> value of a CSS length relative to an element is t
 	The {{Window/devicePixelRatio}} of a frame is multiplied by the [=effective zoom=] inherited by its parent frame.
 </h3>
 
+<h2 id=extensions-to-the-window-interface>Extensions to the {{Window}} Interface</h2>
+
+<pre class=idl>
+partial interface Window {
+[SameObject, Replaceable] readonly attribute Viewport viewport;
+};
+</pre>
+
+<h2 id=viewport>Viewport</h2>
+
+<h3 id="the-viewport-interface">The {{Viewport}} Interface</h3>
+
+<pre class=idl>
+[Exposed=Window]
+interface Viewport {
+  readonly attribute FrozenArray&lt;DOMRect>? segments;
+};
+</pre>
+
+<h2 id='segments'>
+	The <dfn attribute for=Viewport>segments</dfn> property
+</h2>
+
+The {{segments}} property is an array of {{DOMRect}} that represent the dimensions of each existing viewport segment.
+Each {{DOMRect}} contains the geometry of the segment (x, y, width, height) in CSS ''<length>/px''.
+
+Additonal details about the definition of a viewport segment can be found here: [[css-env-1#viewport-segments]].
+
+The {{segments}} attribute must run these steps:
+1. If the {{Viewport}}'s associated {{Document}} is not <a>fully active</a>, return null.
+2. Returns null if there is only a single viewport segment and abort these steps.
+3. Otherwise, return the {{Viewport}}'s [[css-env-1#viewport-segments|segments]] array.
+
+<div class=non-normative>
+<em>This section is not normative.</em>
+
+The {{segments}} property represents an immutable snapshot of the device {{segments}} when the value was queried.
+If the device state changes (rotation, window resize, <a spec="DEVICE-POSTURE">posture</a> change), the value previously retrieved will be invalid. Developers can listen to {{ScreenOrientation/onchange|Screen Orientation}}, {{Window/resize|Window Resize}}, or {{DevicePosture/onchange|Posture}} changes events to detect device state changes.
+
+<div class="example">
+If a viewport of 400px by 400px is split horizontally into two side-by-side segments, the {{segments}} array will have the following content:
+<code highlight=javascript>[DOMRect(0, 0, 400, 200), DOMRect(0, 200, 400, 200)]</code>
+</div>
+
+</div>
+
 <h2 class="no-num" id="changes">Appendix A. Changes</h2>
 
 This appendix is <em>informative</em>.