GeezerVison

This document specifies an API that allows web applications to request and be notified of changes of the posture of a device.

This specification is implemented in Chromium-based browsers. WebKit and Mozilla have not yet published formal positions on this specification.

Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.

Introduction

The device posture is the physical position in which a device holds which may be derived from sensors in addition to the angle. New types of mobile devices are appearing that have some sort of capabilities that allow them to change their posture. The most common types of devices are the ones that can fold (their screen or around their screen), allowing them to physically alter their form factor. The main interest in knowing the posture of a device is to enable new user experiences with responsive design.

Among the described "folding" devices, there are mainly two different physical form factors: devices with a single flexible screen (seamless), and devices with two screens (with seam). They can both fold around a hinge, and the current specification applies to both types. It should be clarified as well that both seamless and (devices) with seam can be of different dimension ranging from mobile and tablets to laptop sizes. It should also be noted that different devices will have different default orientations (portrait or landscape), and that the fold might happen in a vertical or horizontal way.

From enhancing the usability of a website by avoiding the area of a fold, to enabling innovative use cases for the web, knowing the posture of a device can help developers tailor their content to different devices.

Content can be consumed and browsed even when the device is not flat, in which case the developer might want to provide a different layout for it depending on the posture state in which the device is being used.

Extensions to the `Document` interface

The following internal slots are added to the {{Document}} interface.

Extensions to the `Navigator` interface

The [[HTML]] specification defines the {{Navigator}} interface, which this specification extends:

        [SecureContext, Exposed=(Window)]
        partial interface Navigator {
          [SameObject] readonly attribute DevicePosture devicePosture;
        };
      

The DevicePosture interface

        [SecureContext, Exposed=(Window)]
        interface DevicePosture : EventTarget {
          readonly attribute DevicePostureType type;
          attribute EventHandler onchange;
        };

        enum DevicePostureType {
          "continuous",
          "folded"      
        };
      

Posture types

This specification defines the following posture values:

1. 

   Continuous posture: The continuous posture refers to a "flat" position. This is the default case for most devices not allowing different postures.

   It includes devices with no folds, hinges or similar capabilities.

   Due to the nature of hardware innovation, it also includes devices with dual, foldable, rollable or curved screens, as long as they are in a posture where the {{Document}} is expected to be displayed with a flat layout.

   Examples of these are:

   • Foldable device in a flat, fully unfolded posture.
   • Foldable device running the browser in a window/section that does not span across the hinge.
   • 2-in-1 device in tablet mode using only 1 screen/side.
   • Devices that do not fold.

   In some cases, devices can run several apps and be in a physical posture other than flat, but as long as the browser does not span through several screens/sections, the corresponding posture is continuous.

2. Folded posture: The folded posture refers to devices that can physically fold. These devices can have one flexible screen or two adjacent screens. This posture forms an angle between the displays/sections that does not exceed a 'flat' position.

   Examples of these are:

   • Foldable device with a vertical hinge and internal screens being used in a 'book' posture, where the content spans through both sections and forms an angle between ~30° and ~170°.
   • Foldable device with a horizontal hinge and internal screens being used in a 'laptop' posture.

   When a foldable is used in a half-folded state (like a book), implementers might need to take into account the effect of text direction and writing mode on the layout and presentation.

   For example, right-to-left languages (those that use scripts such as Arabic, Hebrew, Syriac, and others) and many vertical writing modes used by, for example, East Asian languages progress pages in the opposite order to that used by an English book, with the lower numbered page on the right.

   See Chinese, Japanese, and Korean differences in writing modes for more information.

In the API, the [=posture=] values are represented by the {{DevicePostureType}} enum values.

Device Posture Media Queries

The device-posture media feature

The [=device-posture=] media feature represents, via a CSS media query [[MEDIAQ]], the posture of the device. All navigables reflect the posture of their [=navigable/top-level traversable=].

Value:

continuous | folded

Applies to:

visual media types

Accepts min/max prefixes:

No

A user agent MUST reflect the applied posture of the web application via a CSS media query [[MEDIAQ]].

Reading the posture

Every instance of {{Document}} has an internal slot {{Document/[[CurrentPosture]]}}, which should be initialized when the {{Document}} is created, otherwise they MUST be initialized the first time they are accessed and before their value is read. The user agent MUST run the device posture change steps with [=device posture change steps/document=] set to the {{Document}} and [=device posture change steps/disallowRecursion=] set to true to initialize it.

For a given {{Document}}, the current posture is derived from the current hinge angle and the screen orientation, and potentially other implementation-specific signals.

These tables are non-normative.

Posture values table

The values are approximations and might differ per device. For instance, a device might not yield exactly 180° when laying flat, but instead values ranging from 175° to 185°. Device makers SHOULD make sure that the physical device postures map correctly to the postures defined by this specification. Device makers are also allowed to determine the posture using more sensors than just the hinge angle. For example, they can also detect if keyboard is docked on the bottom half of the screen or not. Another example is to detect whether the kickstand is deployed or not.

Some devices might also lack one or more of the postures due to physical constraints or device design, in which case the device SHOULD make sure that all combinations of angles and device orientation (which can be locked by [[SCREEN-ORIENTATION]] and host OS), as well as device specific signals, maps into one of the defined postures.

Foldables

Algorithms

Security considerations

No new security considerations have been reported on this specification. However it is encouraged to look at the potential [[[#privacy-considerations]]] listed in this document.

Privacy considerations

Accessibility considerations

1. Designing and making applications which do not place content in the fold/hinge area, especially buttons. This area is typically hard to interact with fingers because the curvature of the fold makes touch less precise or impossible.
2. Designing and making applications which do not put large, contiguous content (such as video or a picture) spanning across the fold/hinge area if the device is folded. This area slightly distorts content and colors.
3. Designing and making applications which use the screen estate better by providing a split UI (a user interface where the content is split up across the screen segments), allowing the application to provide a differentiated and more powerful interface.

• Placement of UI elements: A typical placement logic for dialogs is to center them horizontally and vertically, but in a device folded with a symmetrical fold they may end up in the middle of the fold area making it harder to interact with, for instance clicking on buttons. It might also make it harder to read text due to distortion and light reflection.
• Fullscreen mode: When resizing an element in fullscreen, a typical logic would expand that element to the width and the height of the {{Window}}. If the device is folded, the element will be laid out across the fold, leading to a subpar user experience. An alternative is to display that element either on top or below the fold area.
• Improving the user experience: With this API it is possible to create a different and adapted user experience when the device is folded, allowing for a better user experience and improved accessibility. For example, when watching a video and the device is folded, the video could be displayed on top of the fold while the comments section could be shown below the fold by default. Another example would be a video conferencing application showing the video feed on top of the fold and the chat below the fold.
• Content shouldn't be designed for just one {{posture}}: The idea of foldable devices is their versatility and the ability for the user to change the posture as they see fit. Similarly to the orientation, it is important to not always choose for the user as they might have other needs but allowing them to choose the UI that fits their needs better. Ideally it is preferred to make the UI configurable.
• Content announcements for assistive devices: Use ARIA live regions to announce significant layout changes dynamically. For instance, when a fold changes the layout of a webpage, ensure that screen readers announce these changes to users. For example, if a video player is moved to the top of the screen and comments to the bottom, an announcement like "Video player moved to the top screen, comments moved below the fold" can help users navigate better.
• Assistive technology compatibility: Conduct thorough testing with various assistive technologies to ensure compatibility and proper communication of changes when different postures are reached.

Automation

The Device Posture API pose a challenge to test authors, as fully exercising interface requires physical hardware devices. To address this challenge this document defines a [[WEBDRIVER2]] [=extension commands=] that allows users to control the reported device posture and simulate a real device.

To support the [=extension commands=] below and their integration with [[[#algorithms]]], [=top-level traversables=] must have the following internal slots:

Extension Commands

Set device posture

This [=extension command=] changes device posture to a specific {{DevicePostureType}}.

The [=remote end steps=] are:

1. Let |posture| be the result of invoking get a property "posture" from |parameters|.
2. If |posture| is not a [=string=], return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
3. If |posture| is neither "{{DevicePostureType/continuous}}" nor "{{DevicePostureType/folded}}", return [=error=] with [=error code|WebDriver error code=] [=invalid argument=].
4. Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=].
5. Set |topLevelTraversable|. [[\PostureOverride]] to |posture|.
6. Let |document| be |topLevelTraversable|'s [=navigable/active document=].
7. Invoke [=device posture change steps=] with |document|.
8. Return [=success=] with data null.

Clear device posture

This [=extension command=] removes device posture override and returns device posture control back to hardware.

The [=remote end steps=] are:

1. Let |topLevelTraversable| be the current browsing context's [=browsing context/top-level traversable=].
2. If |topLevelTraversable|. [[\PostureOverride]] is null, return [=success=] with data null.
3. Set |topLevelTraversable|. [[\PostureOverride]] to null.
4. Let |document| be |topLevelTraversable|'s [=navigable/active document=].
5. Invoke [=device posture change steps=] with |document|.
6. Return [=success=] with data null.

Examples

Example 1: Posture data

This is a simple use case of the posture being printed on the console.

          navigator.devicePosture.addEventListener("change", () => {
            console.log(`The current posture is: ${navigator.devicePosture.type}!`);
          })
      

Example 2: device-posture

The device is being used for a video call web service. It can be folded into the laptop posture to enable a hands-free experience when placed on a surface. The UA detects the posture and the UI is enhanced. Similar examples can be drafted for content to adapt to any posture. See the explainer for other key scenarios.

        @media (device-posture: folded) and (vertical-viewport-segments: 2) {
          body {
            display: flex;
            flex-flow: column nowrap;
          }

          .videocall-area, .videocall-controls  {
            flex: 1 1 env(viewport-segment-bottom 0 0);
          }
        }
      

Example 3: Feature detection of device-posture media feature

As one of the valid device-posture values will always be true, you can use the following snippet to detect whether a user agent supports the media feature:

          @media (device-posture) {
            /*The browser supports device-posture feature*/
          }
        

This specification defines conformance criteria for a single product: a user agent that implements the interfaces that it contains.

Acknowledgments

We would like to thank Diego González for his major contributions to the specification as the founding editor, and for creating a visual identity to both this specification and the Devices and Sensors Working Group.

We would like to offer our sincere thanks to Daniel Appelquist, Jo Balletti, Michael Blix, Paul Grenier and Laura Morinigo for their contributions to this work.

Summary of substantive changes