Device Posture API

files/en-us/web/api/device_posture_api/index.md

@@ -0,0 +1,59 @@
+---
+title: Device Posture API
+slug: Web/API/Device_Posture_API
+page-type: web-api-overview
+browser-compat: api.DevicePosture
+---
+
+{{DefaultAPISidebar("Device Posture API")}}{{seecompattable}}
+
+The **Device Posture API** allows developers to create user interfaces that adapt to a foldable device's posture and respond to posture changes.
+
+## Concepts and usage
+
+Foldable devices present unique design challenges to developers — they can be used like a regular flat screen or like a book. In addition, some of them feature a single folded screen, and some of them feature two screens with a physical join in the middle. Care must be taken to ensure that content is not hidden by the physical join, or rendered difficult to read due to close proximity to the central fold.
+
+The Device Posture API defines **postures**, which indicate the current physical state of a foldable device. The current available postures are:
+
+- `continuous`
+  - : Indicates a flat screen — this can include a foldable device while it is being used flat, a seamless curved display, or a standard desktop, laptop, tablet or mobile screen.
+    ![A selection of flat screens including mobiles and tablets, and a seamless curved display](continuous-screens.png)
+- `folded`
+  - : Indicates a folded screen — this can include a foldable device being used in a book or laptop posture.
+    ![A selection of folded screens, including foldable mobiles and tablets in book and laptop postures](folded-screens.png)
+
+The Device Posture API introduces a couple of new features enabling you to run script and vary layouts depending on current device posture and posture changes:
+
+- The {{domxref("DevicePosture", "Navigator.devicePosture")}} object, which contains a {{domxref("DevicePosture.type", "type")}} property containing the device's current posture and a {{domxref("DevicePosture.change_event", "change")}} event that fires when the device posture changes.
+- The [`device-posture`](/en-US/docs/Web/CSS/@media/device-posture) [media query](/en-US/docs/Web/CSS/CSS_media_queries) feature, which applies CSS conditionally depending on what posture the device is currently in.
+
+## CSS features
+
+- The [`device-posture`](/en-US/docs/Web/CSS/@media/device-posture) [media query](/en-US/docs/Web/CSS/CSS_media_queries) feature
+  - : Detects the device's current posture.
+
+## Interfaces
+
+- {{domxref("DevicePosture")}}
+  - : Represents the device's posture, providing access to the current posture `type` and a `change` event that fires on posture change.
+
+### Extensions to other interfaces
+
+- {{domxref("Navigator.devicePosture")}}
+  - : The entry point for the Device Posture API — returns the browser's `DevicePosture` object.
+
+## Examples
+
+You can find example code snippets in the above reference pages and a complete example showing all of the features in action — see [Device Posture API test](#). (TBD, FILL IN WHEN IT HAS BEEN APPROVED AND ADDED TO THE DOM-EXAMPLES DEMO).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Origin trial for Foldable APIs](https://developer.chrome.com/blog/foldable-apis-ot) on developer.chrome.com (2024)

files/en-us/web/api/deviceposture/change_event/index.md

@@ -0,0 +1,53 @@
+---
+title: "DevicePosture: change event"
+short-title: change
+slug: Web/API/DevicePosture/change_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.DevicePosture.change_event
+---
+
+{{APIRef}}{{SeeCompatTable}}
+
+The **`change`** event of the {{domxref("DevicePosture")}} interface fires when the device's posture changes.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("change", (event) => {});
+
+onchange = (event) => {};
+```
+
+## Event type
+
+A generic {{domxref("Event")}}.
+
+## Examples
+
+```js
+const postureOutput = document.querySelector("p");
+
+function reportPostureOutput() {
+  postureOutput.textContent = `Device posture: ${navigator.devicePosture.type}`;
+}
+
+navigator.devicePosture.addEventListener("change", reportPostureOutput);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{cssxref("@media/device-posture", "device-posture")}} media query feature
+- [Device Posture API](/en-US/docs/Web/API/Device_Posture_API)
+- [Origin trial for Foldable APIs](https://developer.chrome.com/blog/foldable-apis-ot) on developer.chrome.com (2024)

files/en-us/web/api/deviceposture/index.md

@@ -0,0 +1,52 @@
+---
+title: DevicePosture
+slug: Web/API/DevicePosture
+page-type: web-api-interface
+status:
+  - experimental
+browser-compat: api.DevicePosture
+---
+
+{{APIRef("Device Posture API")}}{{SeeCompatTable}}
+
+The **`DevicePosture`** interface of the {{domxref("Device Posture API", "Device Posture API", "", "nocode")}} represents the device's posture.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+_Inherits properties from its parent, {{DOMxRef("EventTarget")}}._
+
+- {{domxref("DevicePosture.type", "type")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the device's current posture.
+
+## Events
+
+- {{domxref("DevicePosture.change_event", "change")}} {{Experimental_Inline}}
+  - : Fires when the device's posture changes.
+
+## Examples
+
+```js
+const postureOutput = document.querySelector("p");
+
+function reportPostureOutput() {
+  postureOutput.textContent = `Device posture: ${navigator.devicePosture.type}`;
+}
+
+navigator.devicePosture.addEventListener("change", reportPostureOutput);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{cssxref("@media/device-posture", "device-posture")}} media query feature
+- [Device Posture API](/en-US/docs/Web/API/Device_Posture_API)
+- [Origin trial for Foldable APIs](https://developer.chrome.com/blog/foldable-apis-ot) on developer.chrome.com (2024)

files/en-us/web/api/deviceposture/type/index.md

@@ -0,0 +1,48 @@
+---
+title: "DevicePosture: type property"
+short-title: type
+slug: Web/API/DevicePosture/type
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.DevicePosture.type
+---
+
+{{APIRef("Device Posture API")}}{{SeeCompatTable}}
+
+The **`type`** read-only property of the {{domxref("DevicePosture")}} interface returns the device's current posture.
+
+## Value
+
+A string representing the device's current posture. The value can be one of:
+
+- `continuous`
+  - : Indicates a flat screen posture — this can include a foldable device while it is being used flat, a seamless curved display, or a standard desktop, laptop, tablet or mobile screen.
+- `folded`
+  - : Indicates a folded screen posture — this can include a foldable device being used in a book or laptop posture.
+
+## Examples
+
+```js
+const postureOutput = document.querySelector("p");
+
+function reportPostureOutput() {
+  postureOutput.textContent = `Device posture: ${navigator.devicePosture.type}`;
+}
+
+navigator.devicePosture.addEventListener("change", reportPostureOutput);
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{cssxref("@media/device-posture", "device-posture")}} media query feature
+- [Device Posture API](/en-US/docs/Web/API/Device_Posture_API)
+- [Origin trial for Foldable APIs](https://developer.chrome.com/blog/foldable-apis-ot) on developer.chrome.com (2024)

files/en-us/web/api/navigator/deviceposture/index.md

@@ -0,0 +1,40 @@
+---
+title: "Navigator: devicePosture property"
+short-title: devicePosture
+slug: Web/API/Navigator/devicePosture
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.Navigator.devicePosture
+---
+
+{{APIRef("WebdevicePosture API")}}{{SeeCompatTable}}
+
+The **`Navigator.devicePosture`** read-only property returns the browser's {{domxref("DevicePosture")}} object, which allows developers to query the device's current posture and run code in response to posture changes.
+
+## Value
+
+A {{domxref("DevicePosture")}} object.
+
+## Examples
+
+```js
+const postureOutput = document.querySelector("p");
+
+function reportPostureOutput() {
+  postureOutput.textContent = `Device posture: ${navigator.devicePosture.type}`;
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Device Posture API](/en-US/docs/Web/API/Device_Posture_API)
+- The [`device-posture`](/en-US/docs/Web/CSS/@media/device-posture) [media query](/en-US/docs/Web/CSS/CSS_media_queries) feature

files/en-us/web/api/navigator/index.md

@@ -31,6 +31,8 @@ _Doesn't inherit any properties._
   - : Returns the {{domxref("CredentialsContainer")}} interface which exposes methods to request credentials and notify the user agent when interesting events occur such as successful sign in or sign out.
 - {{domxref("Navigator.deviceMemory")}} {{ReadOnlyInline}} {{SecureContext_Inline}}
   - : Returns the amount of device memory in gigabytes. This value is an approximation given by rounding to the nearest power of 2 and dividing that number by 1024.
+- {{domxref("Navigator.devicePosture")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the browser's {{domxref("DevicePosture")}} object, which allows developers to query the device's current posture and run code in response to posture changes.
 - {{domxref("Navigator.geolocation")}} {{ReadOnlyInline}}
   - : Returns a {{domxref("Geolocation")}} object allowing accessing the location of the device.
 - {{domxref("Navigator.gpu")}} {{ReadOnlyInline}} {{Experimental_Inline}} {{SecureContext_Inline}}

files/en-us/web/css/@media/device-posture/index.md

@@ -0,0 +1,52 @@
+---
+title: device-posture
+slug: Web/CSS/@media/device-posture
+page-type: css-media-feature
+browser-compat: css.at-rules.media.device-posture
+---
+
+{{CSSRef}}{{seecompattable}}
+
+The **`device-posture`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US/docs/Web/CSS/@media#media_features) can be used to detect the device's [current posture](/en-US/docs/Web/API/Device_Posture_API).
+
+## Syntax
+
+The `device-posture` feature is specified as a keyword value chosen from the list below:
+
+- `continuous`
+  - : Indicates a flat screen posture — this can include a foldable device while it is being used flat, a seamless curved display, or a standard desktop, laptop, tablet or mobile screen.
+- `folded`
+  - : Indicates a folded screen posture — this can include a foldable device being used in a book or laptop posture.
+
+## Examples
+
+The following snippet is taken from our [Device Posture API test](#) demo. (TBD, FILL IN WHEN IT HAS BEEN APPROVED AND ADDED TO THE DOM-EXAMPLES DEMO). In this demo, we have two panels of equal size, laid out side-by-side on landscape screens and top-to-bottom on portrait screens. We use the `device-posture` media feature to detect when the device is in a folded posture, and add a larger gutter in between the two panels so that the content is less likely to be hidden by the physical join, or rendered difficult to read due to close proximity to the central fold.
+
+```css
+@media (device-posture: folded) and (orientation: landscape) {
+  .list-view {
+    margin-inline-end: 60px;
+  }
+}
+
+@media (device-posture: folded) and (orientation: portrait) {
+  .list-view {
+    margin-block-end: 60px;
+  }
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("DevicePosture")}}
+- [Device Posture API](/en-US/docs/Web/API/Device_Posture_API)
+- [Using Media Queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries)
+- [@media](/en-US/docs/Web/CSS/@media)

files/en-us/web/css/@media/index.md

@@ -78,6 +78,8 @@ Media feature expressions test for their presence, value, or range of values, an
   - : Width-to-height aspect ratio of the output device. Deprecated in Media Queries Level 4.
 - {{cssxref("@media/device-height", "device-height")}}
   - : Height of the rendering surface of the output device. Deprecated in Media Queries Level 4.
+- {{cssxref("@media/device-posture", "device-posture")}} {{experimental_inline}}
+  - : Detects the device's current posture. Added in the [Device Posture API](/en-US/docs/Web/API/Device_Posture_API).
 - {{cssxref("@media/device-width", "device-width")}}
   - : Width of the rendering surface of the output device. Deprecated in Media Queries Level 4.
 - {{cssxref("@media/display-mode", "display-mode")}}

files/en-us/web/css/css_media_queries/index.md

@@ -37,6 +37,7 @@ When designing reusable HTML components, you may also use [container queries](/e
 - {{cssxref("@media/color-index", "color-index")}}
 - {{cssxref("@media/device-aspect-ratio", "device-aspect-ratio")}}
 - {{cssxref("@media/device-height", "device-height")}}
+- {{cssxref("@media/device-posture", "device-posture")}}
 - {{cssxref("@media/device-width", "device-width")}}
 - {{cssxref("@media/display-mode", "display-mode")}}
 - {{cssxref("@media/dynamic-range", "dynamic-range")}}

files/en-us/web/css/css_media_queries/using_media_queries/index.md

@@ -36,6 +36,7 @@ Media queries are case-insensitive.
   - {{cssxref("@media/color-index", "color-index")}}
   - {{cssxref("@media/device-aspect-ratio", "device-aspect-ratio")}} {{deprecated_inline}}
   - {{cssxref("@media/device-height", "device-height")}} {{deprecated_inline}}
+  - {{cssxref("@media/device-posture", "device-posture")}} {{experimental_inline}}
   - {{cssxref("@media/device-width", "device-width")}} {{deprecated_inline}}
   - {{cssxref("@media/display-mode", "display-mode")}}
   - {{cssxref("@media/dynamic-range", "dynamic-range")}}
@@ -57,7 +58,7 @@ Media queries are case-insensitive.
   - {{cssxref("@media/scripting", "scripting")}}
   - {{cssxref("@media/update", "update")}}
   - {{cssxref("@media/video-dynamic-range", "video-dynamic-range")}}
-  - {{cssxref("@media/width", "width")}}.
+  - {{cssxref("@media/width", "width")}}
 
   For example, the {{cssxref("@media/hover", "hover")}} feature allows a query to check whether the device supports hovering over elements.
   Media feature expressions test for their presence or value, and are entirely optional.

files/jsondata/GroupData.json

@@ -382,6 +382,14 @@
         "Window: devicemotion"
       ]
     },
+    "Device Posture API": {
+      "overview": ["Device Posture API"],
+      "guides": [],
+      "interfaces": ["DevicePosture"],
+      "methods": ["Navigator.devicePosture"],
+      "properties": [],
+      "events": []
+    },
     "Document Picture-in-Picture API": {
       "overview": ["Document Picture-in-Picture API"],
       "guides": ["/docs/Web/API/Document_Picture-in-Picture_API/Using"],