Compatibility (PR #253)

1. Introduction

There exists an increasingly large corpus of web content that depends on web browsers supporting a number of specific vendor CSS properties and DOM APIs for functionality or layout. This holds especially true for mobile-optimized web content, which is highly dependent on -webkit--prefixed properties.

This specification aims to describe the minimal set of -webkit--prefixed CSS properties and DOM APIs that user agents are required to support for web compatibility, which aren’t specified elsewhere.

The HTTP User-Agent header field as found in major browsers today is also described.

2. Conformance

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the keyword ("must", "should", "may", etc.) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

3. CSS Compatibility

3.1. CSS At-rules

The following -webkit- vendor prefixed at-rules must be supported as aliases of the corresponding unprefixed at-rules:

3.2. CSS Media Queries

3.2.1. -webkit-device-pixel-ratio

-webkit-device-pixel-ratio must be treated as an alias of the resolution range type media feature, with its value interpreted as a dppx unit.

The min- or max- prefixes on range features must not apply to -webkit-device-pixel-ratio, instead the following aliases must be used:

3.2.2. -webkit-transform-3d

The -webkit-transform-3d media feature is used to query whether the user agent supports CSS 3D transforms. [css-transforms-1]

If the user agent supports 3D transforms, the value will be 1. Otherwise the value is 0.

3.3. CSS Gradient Functions

3.3.1. -webkit-linear-gradient()

The -webkit-linear-gradient() gradient function must be treated as an alias of linear-gradient as defined in [css3-images-20110217].

3.3.2. -webkit-radial-gradient()

The -webkit-radial-gradient() gradient function must be treated as an alias of radial-gradient as defined in [css3-images-20110217].

3.3.3. -webkit-repeating-linear-gradient()

The -webkit-repeating-linear-gradient() gradient function must be treated as an alias of repeating-linear-gradient as defined in [css3-images-20110217].

3.3.4. -webkit-repeating-radial-gradient()

The -webkit-repeating-radial-gradient() gradient function must be treated as an alias of repeating-radial-gradient as defined in [css3-images-20110217].

3.4. CSS Properties

3.4.1. Legacy name aliases

The following -webkit- vendor prefixed properties must be supported as legacy name aliases of the corresponding unprefixed property:

3.4.2. Prefixed legacy name aliases

The following -webkit- vendor prefixed properties must be supported as legacy name aliases of the corresponding unprefixed properties. If the user agent does not ship the unprefixed equivalent, the -webkit- prefixed property must be treated as an alias of the user agent’s own vendor prefixed property.

Note: As soon as each property is unprefixable it can be defined as a legacy name alias.

3.4.3. Non-aliased vendor prefixed properties

Note: This section used to specify the -webkit-appearance property. This is now defined in CSS Basic User Interface Module.

3.4.4. Property mappings

The following -webkit- vendor prefixed properties must be supported as mappings to the corresponding unprefixed property:

These definitions of -webkit-box-* are known to not be web compatible.

3.4.5. Keyword mappings

The following -webkit- vendor prefixed keywords must be supported as mappings to the corresponding unprefixed keyword:

These definitions of -webkit-box-* are known to not be web compatible.

3.4.6. Text Fill and Stroking

3.4.6.1. Foreground Text Color: the -webkit-text-fill-color property

The -webkit-text-fill-color property defines the foreground fill color of an element’s text content.

.one {
  color: blue;
  /* the following can be omitted because it’s the initial value:
  -webkit-text-fill-color: currentcolor; */
}

.two {
  color: red;
  -webkit-text-fill-color: blue;
}

3.4.6.2. Text Stroke Color: the -webkit-text-stroke-color property

The -webkit-text-stroke-color property specifies a stroke color for an element’s text.

3.4.6.3. Text Stroke Thickness: the -webkit-text-stroke-width property

The -webkit-text-stroke-width property specifies the width of the stroke drawn at the edge of each glyph of an element’s text. A zero value results in no stroke being painted. A negative value is invalid.

3.4.6.4. Text Stroke Shorthand: the -webkit-text-stroke property

The -webkit-text-stroke property is a shorthand property for the -webkit-text-stroke-width and -webkit-text-stroke-color properties, for setting the stroke width and stroke color of an element’s text.

.stroked-text-longhand {
  color: #fff;
  -webkit-text-stroke-color: #000;
  -webkit-text-stroke-width: 1px;
}

.stroked-text-shorthand {
  -webkit-text-fill-color: #fff;
  -webkit-text-stroke: thin #000;
}

<p class="stroked-text-longhand">Serious typography</p>

3.5. CSS Property values

3.5.1. Additional touch-action values

This section augments the definition of touch-action from [pointerevents2] to add the pinch-zoom value.

When specified, the pinch-zoom token enables multi-finger panning and zooming of the page. For zooming to occur, all fingers must start on an element that has the pinch-zoom behavior enabled (via one of the pinch-zoom, manipulation, or auto values on itself or an ancestor).

manipulation is an alias for "pan-x pan-y pinch-zoom".

4. DOM Compatibility

4.1. The WebKitCSSMatrix interface

Note: WebKitCSSMatrix is now defined by the DOM Geometry specification. [geometry-1].

4.2. window.orientation API

partial interface Window {
    readonly attribute short orientation;
    attribute EventHandler onorientationchange;
};

partial interface HTMLBodyElement {
    attribute EventHandler onorientationchange;
};

When getting the orientation attribute, the user agent must run the following steps:

1. Let document be this’s relevant global object’s associated Document.

2. Return document’s current window.orientation angle.

Whenever the viewport is drawn at a different angle compared to the device’s natural orientation, the user agent must run the following steps:

1. Fire an event named orientationchange at the Window object of the active document.

User agents implementing the window.orientation attribute and its associated orientationchange event must not expose them on non-Mobile platforms.

4.2.1. window.orientation angle

The possible integer values for the window.orientation angle are: -90, 0, 90, 180. User agents must support the -90, 0 and 90 values and may optionally support 180.

0 represents the natural orientation. -90 represents a rotation 90 degrees clockwise from the natural orientation. 90 represents a rotation 90 degrees counterclockwise from the natural orientation. 180 represents a rotation 180 degrees from the natural orientation.

In order to determine the current window.orientation angle, the user agent must run the following steps:

1. Let orientationAngle be the current orientation angle.
   1. If orientationAngle is less than 180, return orientationAngle.
   2. If orientationAngle is 180, and the user agent supports that value, return orientationAngle, else return 0.
   3. If orientationAngle is greater than 180, return orientationAngle - 360.

4.2.2. Event Handlers on Window objects and body elements

The following are the event handlers and their corresponding event handler event types that must be supported on all Window objects and body elements as attributes:

5. Cookie Access Heuristics

User agents are blocking third-party cookies by default while avoiding user-facing breakage by removing support for common web patterns, particularly login flows via third-party identity providers. Browsers should follow the established patterns in this specification in order to provide short-term cookie access to unbreak these flows.

5.1. Global Data

A site pair is a tuple consisting of a site third party site and a site first party site

The user agent holds a heuristic grants map which is a map of site pairs to moments. The moment represents the expiration timestamp of a cookie access grant for third party site on first party site.

5.2. Constants

The popup heuristic grant duration is an implementation-defined duration that represents the length of time after the popup heuristic is triggered that a user agent will store the corresponding popup heuristic grant in its heuristic grants map.

Note: Most implementations use 30 days as the popup heuristic grant duration.

The redirect heuristic grant duration is an implementation-defined duration that represents the length of time after the redirect heuristic is triggered that a user agent will store the corresponding redirect heuristic grant in its heuristic grants map.

Note: Most implementations use 15 minutes as the redirect heuristic grant duration.

5.3. Cookie Access Grant

5.4. Cookie Access Monkey Patch

TODO: add monkey patch to network fetch cookie access that reads from heuristic grants map.

5.5. Popup Heuristic

Append the following steps to the [HTML]’s activation notification algorithm:

5.6. Redirect Heuristic

Insert the following steps at the start of [HTML]’s load a document algorithm.

6. The User-Agent String

The User-Agent header field syntax is formally defined by [HTTP-SEMANTICS] and provides SHOULD-level guidance on its value. This section serves as a descriptive record of the User-Agent patterns found in the so-called major web browsers, but much of it will apply to other browsers with a shared heritage (i.e., forks and embedders) as well as any user agent in the more general sense that send a User-Agent header.

6.1. User-Agent Tokens

A User-Agent token is a string that represents an abstraction over a semantic unit in the User-Agent string. This document formalizes a token as a string that begins with an opening bracket "<" and ends with a closing ">" bracket, e.g., <version>. A token may also contain other tokens.

A User-Agent constant is a string whose value does not change.

When a token’s value is made up from one or more tokens, and optionally constants, it is said to decompose to those tokens and constants.

6.1.1. User-Agent Token Reference

This is a non-exhaustive list of common User-Agent tokens.

6.2. Meta Structure

The User-Agent strings that follow share the common meta structure:

"Mozilla/5.0 (a) b"

Where a is one or more tokens representing device information and b is one or more tokens representing browser information.

6.3. Chrome

6.3.1. Chrome User-Agent pattern

"Mozilla/5.0 (<unifiedPlatform>) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/<majorVersion>.0.0.0 <deviceCompat>Safari/537.36"

6.3.2. Chrome-specific tokens

6.4. Firefox

6.4.1. Firefox User-Agent pattern

"Mozilla/5.0 (<firefoxPlatform>; rv: <firefoxVersion>) Gecko/<geckoVersion> Firefox/<firefoxVersion>"

6.4.2. Firefox-specific tokens

<firefoxVersion> decomposes to the following:

"<majorVersion>.0"

In Firefox on desktop platforms (Windows, macOS, Linux, etc.), <geckoVersion> is the frozen build date "20100101". In Firefox for Android, <geckoVersion> is the same value as <firefoxVersion>.

<firefoxPlatform> decomposes to the following:

On desktop platforms, "<platform>; <oscpu>".

On Firefox for Android, "<platform>; <deviceCompat>".

6.5. Safari

6.5.1. Safari User-Agent pattern

"Mozilla/5.0 (<safariPlatform>) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/<safariVersion><deviceCompat>Safari/<webkitVersion>"

6.5.2. Safari-specific tokens

<safariVersion> decomposes to the following:

"<majorVersion>.<minorVersion>", where <minorVersion> is a single digit.

<safariPlatform> decomposes to the following:

On desktop and larger iPad form factors, the constant "Macintosh; Intel Mac OS X 10_15_7".

On mobile platforms, including smaller iPad form factors "<appleProduct>; CPU <mobileOSName> <iOSVersion> like Mac OS X".

Acknowledgements

Thanks to Mounir Lamouri and Marcos Cáceres for defining the ScreenOrientation interface. [screen-orientation]

Special thanks to Apple and the WebKit.org blog authors for providing initial descriptions of much of the content defined in this specification.

This standard is written by Mike Taylor (Google, miketaylr@google.com).

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.

This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft.