diff --git a/Accessibility/HighContrast/explainer.md b/Accessibility/HighContrast/explainer.md index 422dc5893..789ba13a3 100644 --- a/Accessibility/HighContrast/explainer.md +++ b/Accessibility/HighContrast/explainer.md @@ -1,9 +1,18 @@ -# High Contrast Explainer +# High Contrast Explainer Authors: [Rossen Atanassov](https://github.com/atanassov), [Alison Maher](https://github.com/amaher23) Last Updated: 2019-01-18 +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [W3C CSS Working Group](https://www.w3.org/Style/CSS/) | [w3c/csswg-drafts](https://github.com/w3c/csswg-drafts) +* Current version: + * [System Colors](https://drafts.csswg.org/css-color/#css-system-colors) section of [CSS Color Module Level 4](https://drafts.csswg.org/css-color) | ![GitHub issues by-label](https://img.shields.io/github/issues/w3c/csswg-drafts/css-color-4) + * ['forced-color-adjust'](https://drafts.csswg.org/css-color-adjust-1/#forced) of [CSS Color Adjustment Module Level 1](https://drafts.csswg.org/css-color-adjust-1) | ![GitHub issues by-label](https://img.shields.io/github/issues/w3c/csswg-drafts/css-color-adjust-1) + * ['forced-colors'](https://drafts.csswg.org/mediaqueries-5/#forced-colors) of [Media Queries Level 5](https://drafts.csswg.org/mediaqueries-5) | ![GitHub issues by-label](https://img.shields.io/github/issues/w3c/csswg-drafts/mediaqueries-5) + ## Overview High contrast is a [Windows accessibility feature](https://docs.microsoft.com/en-us/windows/desktop/w8cookbook/high-contrast-mode) intended to increase the readability of text through color contrast. Individuals with low vision may find it more comfortable to read content when there is a strong contrast between foreground and background colors. High contrast is a useful feature in increasing the readability of screen-based text for such users. diff --git a/CSSModules/v1Explainer.md b/CSSModules/v1Explainer.md index eb54d4b8a..0d8ee513c 100644 --- a/CSSModules/v1Explainer.md +++ b/CSSModules/v1Explainer.md @@ -1,9 +1,13 @@ -# MOVED. This doc is now maintained at https://github.com/w3c/webcomponents/blob/gh-pages/proposals/css-modules-v1-explainer.md. Please refer to that link for the latest content. - # CSS Modules V1 Explainer Author: [@dandclark](https://github.com/dandclark) +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [Web Components Incubator of the W3C Web Applications Working Group and WHATWG HTML and DOM Workstreams](https://github.com/w3c/webcomponents/) | [w3c/webcomponents](https://github.com/w3c/webcomponents/) | ![GitHub issues by-label](https://img.shields.io/github/issues/w3c/webcomponents/modules) +* Current version: [CSS Modules V1 Explainer](https://github.com/w3c/webcomponents/blob/gh-pages/proposals/css-modules-v1-explainer.md) + ## Introduction This document proposes an extension of the ES Script Modules system to include CSS Modules. These will allow web developers to load CSS into a component definition in a manner that interacts seamlessly with other module types. diff --git a/EditContext/explainer.md b/EditContext/explainer.md index c546c3c60..47cf5a258 100644 --- a/EditContext/explainer.md +++ b/EditContext/explainer.md @@ -1,4 +1,11 @@ # EditContext API Explainer + +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [W3C Editing Task Force](https://w3c.github.io/editing/) | [w3c/editing](https://github.com/w3c/editing/) +* Current version: [EditContext API Explainer](https://github.com/w3c/editing/blob/gh-pages/ActiveDocuments/EditContext/explainer.md) + ## Introduction The EditContext is a new API that simplifies the process of integrating a web app with [advanced text input methods](#example-text-input-methods), improves accessibility and performance, and unlocks new capabilities for web-based editors. diff --git a/Foldables/explainer.md b/Foldables/explainer.md index c322537a2..74814e798 100644 --- a/Foldables/explainer.md +++ b/Foldables/explainer.md @@ -1,251 +1,259 @@ -# Web Platform Primitives for Enlightened Experiences on Foldable Devices - -Authors: [Bogdan Brinza](https://github.com/boggydigital), [Daniel Libby](https://github.com/dlibby-), [Zouhir Chahoud](https://github.com/Zouhir) - -### Table of content -- [Motivation](#motivation) - * [Some of the current problems](#current-problems) - * [Complementary existing proposals](#complementary-existing-proposals) - -- [Proposal: CSS primitives for dual screen layouts](#proposal-css-primitives-for-building-dual-screen-layouts) - * [The 'spanning' CSS media feature](#the-spanning-css-media-feature) - * [Device fold CSS environment variables](#device-fold-css-environment-variables) - * [Non-goals](#non-goals) - -- [Proposal: Window Segments Enumeration JavaScript API](#proposal-window-segments-enumeration-javascript-api) - -- [Security and Privacy](#security-and-privacy) - * [APIs avalibility in iframe context](#apis-avalibility-in-iframe-context) - -- [Examples of user experiences and solution outlines that can leverage two screens](#examples-of-user-experiences-and-solution-outlines-that-can-leverage-two-screens) - -- [Additional Links](#additional-links) - * [CSS Spanning media feature polyfill & example](https://github.com/zouhir/spanning-css-polyfill) - * [Window Segments Enumeration API polyfill & example](https://github.com/zouhir/windowsegments-polyfill) - * [Simple CSS spanning media feature demo in a web-based device emulator](https://foldables-emulator.netlify.com/?url=https://css-spanning.netlify.com/demo/basic/) - -## Motivation: -Web developers targeting dual-screen and foldable devices want to be able to effectively lay out the content in a window that spans multiple display regions. However, the web platform does not yet provide the necessary primitives for building layouts that are optimized for dual-screen or foldable experiences. - -Developers may be able to solve this by taking a hard dependency on a specific device hardware parameters - an approach that is fragile, not scalable, and requires work duplication for each new device. - -### Current problems: -More specific challenges we've heard from our internal product teams that were exploring building experiences for this emerging classes of devices include: - -- *Hardware differences*: Devices could be seamless (e.g. Samsung Galaxy Fold) or have a seam (e.g. [Microsoft Surface Neo](https://www.microsoft.com/en-us/surface/devices/surface-neo), [Microsoft Surface Duo](https://www.microsoft.com/en-us/surface/devices/surface-duo) or ZTE Axon M). In both cases developers might want to take it into account or intentionally ignore depending on scenario; -- *Folding capabilities, state*: the fold area could be safe or unsafe region to present content; -- *Future-proofing*: Ideally developers would want a somewhat stable way to target this class of devices without having to rely on specific device hardware parameters. - -### Complementary existing proposals: -Before discussing the solution proposal - let's overview existing proposals that are relevant and applicable to the problem space. -As matter of principle we should generally avoid creating redundant concepts if we can reuse existing platform APIs and capabilities. - -- [Presentation API](https://w3c.github.io/presentation-api/) is solving the problem of a effective use of a _secondary_ screen and likely won't attempt to solve challenges outlined above that are specific to devices where a window can span separate physical displays. This would likely still be a separate problem for foldables - -- [Screen Enumeration API Explainer](https://github.com/spark008/screen-enumeration/blob/master/EXPLAINER.md) provides information about the physical screen configuration. Web developers might be able to leverage that on foldables, but would need to do extra effort to correlate that information with window parameters. Some concrete examples on why a special purpose API might be useful in addition to Screen Enumeration: - - Getting adjacency information about spanning window regions to lay out content in several areas in logical way for a device; - - Getting inner window dimensions that account for application frame, OS UI elements, etc. -- [Window Placement API Explainer](https://github.com/spark008/window-placement/blob/master/EXPLAINER.md) is useful in multi-window scenarios on multiple screen devices, but does not target scenarios in which the hosting application (i.e. browser) has a single window which spans multiple displays. In this case, the developer may not wish to open new windows - just hints to help lay out things properly and take advantage of the physical partitioning of the available layout space. - -Additionally, while not a solution in the same sense, a ["[css-media-queries] Foldables support and enablement"](https://github.com/w3c/csswg-drafts/issues/4141) issue discusses the problem space and outlines some details and touches upon outlined issues. - -## Proposal: CSS primitives for building dual screen layouts - -A summary of the concepts from the other proposals: -* Display region - The representation of a physical monitor on dual-screen devices or the logical view area seperated by the hinge on foldable devices. -* Screen - the aggregate 2D space occupied by all the connected displays. - -In order to enable web developers to build layouts that are optimized for dual-screen and foldable experiences declaratively using CSS, we must consider fundamental assumptions of CSS (i.e. a single contiguous rectangular space for laying out content) and introduce new primitives that -together with existing layout media queries- allow developers to create layouts that react to states where the root viewport spans across multiple display regions. - -The first primitive we propose is a CSS media feature to determine whether the website is spanning across two adjacent display regions along with the configuration of those two adjacent display regions (e.g. stacked or aside). The second primitive is a set of user agent-defined environment variables that will help developers calculate the size of each screen region in CSS pixels. - -### The 'spanning' CSS media feature - -The `spanning` CSS media feature can be used to test whether the browser window is spanning across multiple display regions. - -![Figure showing 2 foldable devices with different hinge postures](spanning-media-query.svg) - -#### Syntax - -The `spanning` media feature value can be one of the following keywords: - -- **single-fold-vertical** - -This value matches when the layout viewport is spanning a single fold (two display regions) and the fold posture is vertical. - -- **single-fold-horizontal** - -This value matches when the layout viewport is spanning a single fold (two display regions) and the fold posture is horizontal. - -- **none** - -This value describes the state of when the browser window is not in spanning mode. - -### Device fold CSS environment variables - -![predefined environment variables](css-env-variables.svg) - -We propose the addition of 6 pre-defined CSS environment variables `fold-top`, `fold-right`, `fold-bottom`, `fold-left`, `fold-width`, `fold-height`. Web developers can utilize those variables to calculate each screen segment size at both landscape and portrait orientations. While the spanning media query guarantees there is only a single hinge and two screen segments, developers must not take a dependency that each screen segment is 50% of the viewport height or width, as that is not always the case (see above example of `single-fold-horizontal` where portions of the top display are consumed by browser UI). - -The values of these variables are CSS pixels, and are relative to the layout viewport (i.e. are in the [client coordinates, as defined by CSSOM Views](https://drafts.csswg.org/cssom-view/#dom-mouseevent-clientx)). When evaluated when not in one of the spanning states, these values will be treated as if they don't exist, and use the fallback value as passed to the `env()` function. - -### Non-goals: - -This proposal is not meant to solve the problem for foldable devices with more than two screens, due to the unavailability of a CSS construct that allows authors to iterate over a set of values. In this case, an author would need a function that allows them to retrieve the browser's predefined `env()` variables of the `n-th` fold/hinge. - -The proposed CSS constructs are not currently meant to map to spanning configurations in window managers that allow arbitrary window placement. When windows are spanned across external monitors, it is not clear that there is user intent that applications should split their view over the gap between the physical monitors. Additionally, these values would change as the user moves the window. However, if a valid use case presents itself, it's something we can certainly reconsider. - -## Proposal: Window Segments Enumeration JavaScript API - -- Feb 26, 2020: 🚚📦 Window Segments Enumeration JavaScript API has now moved to the [W3C Second Screen Community Group](https://www.w3.org/community/webscreens/). For the explainer, issues, and comments please refer to the [webscreens/window-segments](https://github.com/webscreens/window-segments) GitHub repo. - -## Security and Privacy - -### APIs avalibility in iframe context - -The CSS constructs and the JavaScript API will be available in `iframe` context but disabled by default for privacy and security considerations. An author may enable them using the `screen-spanning` policy; a new feature policy we are proposing that will enable authors to selectively enable the previously mentioned CSS and JavaScript constructs in iframe context. When disabled, getWindowSegments will return a single segment the size of the iframe's viewport, and the CSS environment variables will be treated as unset, and use the fallback values. - -iframes where `screen-spanning` feature policy is enabled will receive values in the client coordinates of the top most window, and it's possible the iframe won't be able to interpret that data without other information from its embedder. As an example, for cross origin iframes, the iframe's embedder must provide information about how to transform from the root client coordinate space to the iframe's client coordinate space, as this information is not available to cross-origin iframes for security reasons. - -## Examples of user experiences and solution outlines that can leverage two screens: - -Let's take a look at a few practical examples of the scenarios above and how window segments would allow to resolve them for better user experience. In each case we'll start with some existing scenario and complicate it to provide opportunity to apply the proposal. - -### A map application that presents a map on one window segment and search results on another - -![Foldable with the left segment of the window containing a map and the right segment containing list of search results](map-app.svg) - -#### CSS solution outline: - -```css -@media (spanning: single-fold-vertical) { - body { - flex-direction: row; - } - - .map { - flex: 1 1 env(fold-left) - } - - .locations-list { - flex: 1; - } -} -``` - -#### JavaScript solution outline: - -```js -const screenSegments = window.getWindowSegments(); - -if( screenSegments.length > 1 ) { - // now we know the device is a foldable - // it's recommended to test whether screenSegments[0].width === screenSegments[1].width - // and we can update CSS classes in our layout as appropriate - document.body.classList.add('is-foldable'); - document.querySelector('.map').classList.add('flex-one-half'); - document.querySelector('.locations-list').classList.add('flex-one-half'); -} -``` - -### Reacting to map application resize/spanning state change - -![Foldable with the left segment of the window containing browser and location finder website, right segment containing calculator app](map-app-resized.svg) - -#### CSS solution outline: - -```css - -@media (spanning: none) and (max-width: 728px) { - body { - flex-direction: column; - } - - .map { - flex: 0 0 300px; - } - - .locations-list { - flex: 1; - } -} - -``` - -#### JavaScript solution outline: - -```js -window.onresize = function() { - const segments = window.getWindowSegments(); - console.log(segments.length) // 1 -} -``` - -### Colored boxes absolutely positioned - -![Foldable with the left segment of the window containing browser and location finder website, right segment containing calculator app](colored-boxes.svg) - -This is an illustrative example that demonstrates how to use the new enviroment variables to position content relative to the fold. - -Box 1 `.blue` and Box 4 `.green` have a *width* and *height* of *100px*, however, the requirement for Box 2 `.yellow` and Box 3 `.pink` is to *fill the screen segment width* and have a height of *100px* - -#### CSS solution outline: - -```css -@media (spanning: single-fold-vertical) { - .blue { - height: 100px; - width: 100px; - position: absolute; - left: calc(env(fold-left) - 100px); - top: 0; - } - - .yellow { - height: 100px; - width: calc(100vw - env(fold-right)); - position: absolute; - left: env(fold-right); - top: 0; - } - - .pink { - height: 100px; - width: env(fold-left); - position: absolute; - left: 0; - bottom: 0; - } - - .green { - height: 100px; - width: 100px; - position: absolute; - left: env(fold-right); - bottom: 0; - } -} -``` - -#### LTR and RTL Layout Example -![Yelow flex column being hinge aware in both LTR and RTL writing modes](ltr-rtl.svg) - -#### CSS solution outline: - -```css -[dir="ltr"] .col { - flex: 0 0 env(fold-left); -} - -[dir="rtl"] .col { - flex: 0 0 env(fold-right); -} -``` - -## Additional Links - -- [CSS Spanning media feature polyfill & example](https://github.com/zouhir/spanning-css-polyfill) - -- [Window Segments Enumeration API polyfill & example](https://github.com/zouhir/windowsegments-polyfill) - -- [Simple CSS spanning media feature demo in a web-based device emulator](https://foldables-emulator.netlify.com/?url=https://css-spanning.netlify.com/demo/basic/) \ No newline at end of file +# Web Platform Primitives for Enlightened Experiences on Foldable Devices + +Authors: [Bogdan Brinza](https://github.com/boggydigital), [Daniel Libby](https://github.com/dlibby-), [Zouhir Chahoud](https://github.com/Zouhir) + +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **Active** (CSS primitives for dual screen layouts) + * Expected venue: [W3C CSS Working Group](https://www.w3.org/Style/CSS/) +* This document status: **ARCHIVED** (Window Segments Enumeration JavaScript API) + * Current venue: [W3C Second Screen Community Group](https://www.w3.org/community/webscreens/) | [webscreens/window-segments](https://github.com/webscreens/window-segments) | ![GitHub issues](https://img.shields.io/github/issues/webscreens/window-segments) + * Current version: [Window Segments Enumeration JavaScript API](https://github.com/webscreens/window-segments/blob/master/EXPLAINER.md) + +### Table of content +- [Motivation](#motivation) + * [Some of the current problems](#current-problems) + * [Complementary existing proposals](#complementary-existing-proposals) + +- [Proposal: CSS primitives for dual screen layouts](#proposal-css-primitives-for-building-dual-screen-layouts) + * [The 'spanning' CSS media feature](#the-spanning-css-media-feature) + * [Device fold CSS environment variables](#device-fold-css-environment-variables) + * [Non-goals](#non-goals) + +- [Proposal: Window Segments Enumeration JavaScript API](#proposal-window-segments-enumeration-javascript-api) + +- [Security and Privacy](#security-and-privacy) + * [APIs avalibility in iframe context](#apis-avalibility-in-iframe-context) + +- [Examples of user experiences and solution outlines that can leverage two screens](#examples-of-user-experiences-and-solution-outlines-that-can-leverage-two-screens) + +- [Additional Links](#additional-links) + * [CSS Spanning media feature polyfill & example](https://github.com/zouhir/spanning-css-polyfill) + * [Window Segments Enumeration API polyfill & example](https://github.com/zouhir/windowsegments-polyfill) + * [Simple CSS spanning media feature demo in a web-based device emulator](https://foldables-emulator.netlify.com/?url=https://css-spanning.netlify.com/demo/basic/) + +## Motivation: +Web developers targeting dual-screen and foldable devices want to be able to effectively lay out the content in a window that spans multiple display regions. However, the web platform does not yet provide the necessary primitives for building layouts that are optimized for dual-screen or foldable experiences. + +Developers may be able to solve this by taking a hard dependency on a specific device hardware parameters - an approach that is fragile, not scalable, and requires work duplication for each new device. + +### Current problems: +More specific challenges we've heard from our internal product teams that were exploring building experiences for this emerging classes of devices include: + +- *Hardware differences*: Devices could be seamless (e.g. Samsung Galaxy Fold) or have a seam (e.g. [Microsoft Surface Neo](https://www.microsoft.com/en-us/surface/devices/surface-neo), [Microsoft Surface Duo](https://www.microsoft.com/en-us/surface/devices/surface-duo) or ZTE Axon M). In both cases developers might want to take it into account or intentionally ignore depending on scenario; +- *Folding capabilities, state*: the fold area could be safe or unsafe region to present content; +- *Future-proofing*: Ideally developers would want a somewhat stable way to target this class of devices without having to rely on specific device hardware parameters. + +### Complementary existing proposals: +Before discussing the solution proposal - let's overview existing proposals that are relevant and applicable to the problem space. +As matter of principle we should generally avoid creating redundant concepts if we can reuse existing platform APIs and capabilities. + +- [Presentation API](https://w3c.github.io/presentation-api/) is solving the problem of a effective use of a _secondary_ screen and likely won't attempt to solve challenges outlined above that are specific to devices where a window can span separate physical displays. This would likely still be a separate problem for foldables + +- [Screen Enumeration API Explainer](https://github.com/spark008/screen-enumeration/blob/master/EXPLAINER.md) provides information about the physical screen configuration. Web developers might be able to leverage that on foldables, but would need to do extra effort to correlate that information with window parameters. Some concrete examples on why a special purpose API might be useful in addition to Screen Enumeration: + - Getting adjacency information about spanning window regions to lay out content in several areas in logical way for a device; + - Getting inner window dimensions that account for application frame, OS UI elements, etc. +- [Window Placement API Explainer](https://github.com/spark008/window-placement/blob/master/EXPLAINER.md) is useful in multi-window scenarios on multiple screen devices, but does not target scenarios in which the hosting application (i.e. browser) has a single window which spans multiple displays. In this case, the developer may not wish to open new windows - just hints to help lay out things properly and take advantage of the physical partitioning of the available layout space. + +Additionally, while not a solution in the same sense, a ["[css-media-queries] Foldables support and enablement"](https://github.com/w3c/csswg-drafts/issues/4141) issue discusses the problem space and outlines some details and touches upon outlined issues. + +## Proposal: CSS primitives for building dual screen layouts + +A summary of the concepts from the other proposals: +* Display region - The representation of a physical monitor on dual-screen devices or the logical view area seperated by the hinge on foldable devices. +* Screen - the aggregate 2D space occupied by all the connected displays. + +In order to enable web developers to build layouts that are optimized for dual-screen and foldable experiences declaratively using CSS, we must consider fundamental assumptions of CSS (i.e. a single contiguous rectangular space for laying out content) and introduce new primitives that -together with existing layout media queries- allow developers to create layouts that react to states where the root viewport spans across multiple display regions. + +The first primitive we propose is a CSS media feature to determine whether the website is spanning across two adjacent display regions along with the configuration of those two adjacent display regions (e.g. stacked or aside). The second primitive is a set of user agent-defined environment variables that will help developers calculate the size of each screen region in CSS pixels. + +### The 'spanning' CSS media feature + +The `spanning` CSS media feature can be used to test whether the browser window is spanning across multiple display regions. + +![Figure showing 2 foldable devices with different hinge postures](spanning-media-query.svg) + +#### Syntax + +The `spanning` media feature value can be one of the following keywords: + +- **single-fold-vertical** + +This value matches when the layout viewport is spanning a single fold (two display regions) and the fold posture is vertical. + +- **single-fold-horizontal** + +This value matches when the layout viewport is spanning a single fold (two display regions) and the fold posture is horizontal. + +- **none** + +This value describes the state of when the browser window is not in spanning mode. + +### Device fold CSS environment variables + +![predefined environment variables](css-env-variables.svg) + +We propose the addition of 6 pre-defined CSS environment variables `fold-top`, `fold-right`, `fold-bottom`, `fold-left`, `fold-width`, `fold-height`. Web developers can utilize those variables to calculate each screen segment size at both landscape and portrait orientations. While the spanning media query guarantees there is only a single hinge and two screen segments, developers must not take a dependency that each screen segment is 50% of the viewport height or width, as that is not always the case (see above example of `single-fold-horizontal` where portions of the top display are consumed by browser UI). + +The values of these variables are CSS pixels, and are relative to the layout viewport (i.e. are in the [client coordinates, as defined by CSSOM Views](https://drafts.csswg.org/cssom-view/#dom-mouseevent-clientx)). When evaluated when not in one of the spanning states, these values will be treated as if they don't exist, and use the fallback value as passed to the `env()` function. + +### Non-goals: + +This proposal is not meant to solve the problem for foldable devices with more than two screens, due to the unavailability of a CSS construct that allows authors to iterate over a set of values. In this case, an author would need a function that allows them to retrieve the browser's predefined `env()` variables of the `n-th` fold/hinge. + +The proposed CSS constructs are not currently meant to map to spanning configurations in window managers that allow arbitrary window placement. When windows are spanned across external monitors, it is not clear that there is user intent that applications should split their view over the gap between the physical monitors. Additionally, these values would change as the user moves the window. However, if a valid use case presents itself, it's something we can certainly reconsider. + +## Proposal: Window Segments Enumeration JavaScript API + +- Feb 26, 2020: 🚚📦 Window Segments Enumeration JavaScript API has now moved to the [W3C Second Screen Community Group](https://www.w3.org/community/webscreens/). For the explainer, issues, and comments please refer to the [webscreens/window-segments](https://github.com/webscreens/window-segments) GitHub repo. + +## Security and Privacy + +### APIs avalibility in iframe context + +The CSS constructs and the JavaScript API will be available in `iframe` context but disabled by default for privacy and security considerations. An author may enable them using the `screen-spanning` policy; a new feature policy we are proposing that will enable authors to selectively enable the previously mentioned CSS and JavaScript constructs in iframe context. When disabled, getWindowSegments will return a single segment the size of the iframe's viewport, and the CSS environment variables will be treated as unset, and use the fallback values. + +iframes where `screen-spanning` feature policy is enabled will receive values in the client coordinates of the top most window, and it's possible the iframe won't be able to interpret that data without other information from its embedder. As an example, for cross origin iframes, the iframe's embedder must provide information about how to transform from the root client coordinate space to the iframe's client coordinate space, as this information is not available to cross-origin iframes for security reasons. + +## Examples of user experiences and solution outlines that can leverage two screens: + +Let's take a look at a few practical examples of the scenarios above and how window segments would allow to resolve them for better user experience. In each case we'll start with some existing scenario and complicate it to provide opportunity to apply the proposal. + +### A map application that presents a map on one window segment and search results on another + +![Foldable with the left segment of the window containing a map and the right segment containing list of search results](map-app.svg) + +#### CSS solution outline: + +```css +@media (spanning: single-fold-vertical) { + body { + flex-direction: row; + } + + .map { + flex: 1 1 env(fold-left) + } + + .locations-list { + flex: 1; + } +} +``` + +#### JavaScript solution outline: + +```js +const screenSegments = window.getWindowSegments(); + +if( screenSegments.length > 1 ) { + // now we know the device is a foldable + // it's recommended to test whether screenSegments[0].width === screenSegments[1].width + // and we can update CSS classes in our layout as appropriate + document.body.classList.add('is-foldable'); + document.querySelector('.map').classList.add('flex-one-half'); + document.querySelector('.locations-list').classList.add('flex-one-half'); +} +``` + +### Reacting to map application resize/spanning state change + +![Foldable with the left segment of the window containing browser and location finder website, right segment containing calculator app](map-app-resized.svg) + +#### CSS solution outline: + +```css + +@media (spanning: none) and (max-width: 728px) { + body { + flex-direction: column; + } + + .map { + flex: 0 0 300px; + } + + .locations-list { + flex: 1; + } +} + +``` + +#### JavaScript solution outline: + +```js +window.onresize = function() { + const segments = window.getWindowSegments(); + console.log(segments.length) // 1 +} +``` + +### Colored boxes absolutely positioned + +![Foldable with the left segment of the window containing browser and location finder website, right segment containing calculator app](colored-boxes.svg) + +This is an illustrative example that demonstrates how to use the new enviroment variables to position content relative to the fold. + +Box 1 `.blue` and Box 4 `.green` have a *width* and *height* of *100px*, however, the requirement for Box 2 `.yellow` and Box 3 `.pink` is to *fill the screen segment width* and have a height of *100px* + +#### CSS solution outline: + +```css +@media (spanning: single-fold-vertical) { + .blue { + height: 100px; + width: 100px; + position: absolute; + left: calc(env(fold-left) - 100px); + top: 0; + } + + .yellow { + height: 100px; + width: calc(100vw - env(fold-right)); + position: absolute; + left: env(fold-right); + top: 0; + } + + .pink { + height: 100px; + width: env(fold-left); + position: absolute; + left: 0; + bottom: 0; + } + + .green { + height: 100px; + width: 100px; + position: absolute; + left: env(fold-right); + bottom: 0; + } +} +``` + +#### LTR and RTL Layout Example +![Yelow flex column being hinge aware in both LTR and RTL writing modes](ltr-rtl.svg) + +#### CSS solution outline: + +```css +[dir="ltr"] .col { + flex: 0 0 env(fold-left); +} + +[dir="rtl"] .col { + flex: 0 0 env(fold-right); +} +``` + +## Additional Links + +- [CSS Spanning media feature polyfill & example](https://github.com/zouhir/spanning-css-polyfill) + +- [Window Segments Enumeration API polyfill & example](https://github.com/zouhir/windowsegments-polyfill) + +- [Simple CSS spanning media feature demo in a web-based device emulator](https://foldables-emulator.netlify.com/?url=https://css-spanning.netlify.com/demo/basic/) diff --git a/HTMLModules/explainer.md b/HTMLModules/explainer.md index 849756f84..2788c00e7 100644 --- a/HTMLModules/explainer.md +++ b/HTMLModules/explainer.md @@ -1,11 +1,13 @@ -# MOVED. This explainer is now maintained at https://github.com/w3c/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md. Please refer to that link for the latest content. - -This document remains here for archival purposes. - # HTML Modules Explainer Author: [@dandclark](https://github.com/dandclark) +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [Web Components Incubator of the W3C Web Applications Working Group and WHATWG HTML and DOM Workstreams](https://github.com/w3c/webcomponents/) | [w3c/webcomponents](https://github.com/w3c/webcomponents/) | ![GitHub issues by-label](https://img.shields.io/github/issues/w3c/webcomponents/modules) +* Current version: [HTML Modules Explainer](https://github.com/w3c/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md) + ## Introduction We are proposing an extension of the ES6 Script Modules system to include HTML Modules. These will allow web developers to package and access declarative content from script in a way that allows for good componentization and reusability, and integrates well into the existing ES6 Modules infrastructure. diff --git a/MediaBlob/explainer.md b/MediaBlob/explainer.md index 007a8c815..0c9ca4781 100644 --- a/MediaBlob/explainer.md +++ b/MediaBlob/explainer.md @@ -2,6 +2,12 @@ By: Yash Khandelwal & Greg Whitworth +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [W3C Web Incubator Community Group](https://wicg.io/) | [WICG/video-editing](https://github.com/WICG/video-editing) | ![GitHub issues](https://img.shields.io/github/issues/WICG/video-editing) +* Current version: [Improved Client-side Video Editing Explainer](https://github.com/WICG/video-editing/blob/master/readme.md) + ## Introduction Currently editing video within the browser is a very complex task as there isn't any straight forward approach to decoding the encoded video file to produce a raw stream that diff --git a/Shortcuts/explainer.md b/Shortcuts/explainer.md index 6a89752df..55e6e47d2 100644 --- a/Shortcuts/explainer.md +++ b/Shortcuts/explainer.md @@ -5,6 +5,12 @@ Authors: * [Matt Giuca](https://github.com/mgiuca) (Google) * [Aaron Gustafson](https://github.com/aarongustafson) (Microsoft) +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [W3C Web Applications Working Group](https://www.w3.org/2019/webapps/) | [w3c/manifest](https://github.com/w3c/manifest/) | ![GitHub issues](https://img.shields.io/github/issues/w3c/manifest) +* Current version: ['shortcuts' member](https://w3c.github.io/manifest/#shortcuts-member) of [Web App Manifest](https://w3c.github.io/manifest/) + ## Introduction A number of operating systems offer a means by which authors add menu items to the app launcher icon itself. These provide quick access to key tasks for an app. Typically, these are exposed via a right click, long tap, or a similar context menu-triggering action. The list of shortcut actions often contains a mixture of static and dynamic shortcuts.[1](#f1) Generally these number around 4–5, depending on the platform—or in the case of Android, the launcher—used. Adding these to the web platform provides an equivalent capability to native apps on many platforms. diff --git a/WebDriverRPC/webdriver.md b/WebDriverRPC/webdriver.md index 185368ee9..f456ea5a0 100644 --- a/WebDriverRPC/webdriver.md +++ b/WebDriverRPC/webdriver.md @@ -1,5 +1,11 @@ # Bidirectional WebDriver Protocol +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [WebDriver incubator](https://github.com/w3c/webdriver/) of the [W3C Browser Testing and Tools Working Group](https://www.w3.org/testing/browser/) | [w3c/webdriver](https://github.com/w3c/webdriver/) +* Current version: [Bidirectional WebDriver Protocol Explainer](https://github.com/w3c/webdriver/blob/master/webdriver-bidi/webdriver.md) + ## Overview This document presents a possible design for a bidirectional WebDriver protocol, incorporating scenarios and resolutions discussed at the TPAC 2019 working group meeting. The protocol uses JSON-RPC messaging over WebSockets as the transport mechanism. WebDriver's current model of the browser is extended to include service workers and other non-page targets and make it possible for clients to target these additional contexts. We also discuss how the new protocol can interoperate with the existing protocol. Sample protocol messages illustrating how the protocol would work are included, and an JSON API specification is included alongside the document. @@ -480,4 +486,4 @@ Or, disallow web element references in script commands. Instead, add a new WebDr 2. [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) 3. [OpenRPC Specification](https://spec.open-rpc.org/) 4. [Browser Tools- and Testing WG, Day 1, TPAC 2019, Fukuoka](https://www.w3.org/2019/09/19-webdriver-minutes.html) -5. [Browser Tools- and Testing WG, Day 2, TPAC 2019, Fukuoka](https://www.w3.org/2019/09/20-webdriver-minutes.html) \ No newline at end of file +5. [Browser Tools- and Testing WG, Day 2, TPAC 2019, Fukuoka](https://www.w3.org/2019/09/20-webdriver-minutes.html) diff --git a/WebInkEnhancement/explainer.md b/WebInkEnhancement/explainer.md index c1f9d03c9..7b81d481c 100644 --- a/WebInkEnhancement/explainer.md +++ b/WebInkEnhancement/explainer.md @@ -6,7 +6,7 @@ Author: [Daniel Libby](https://github.com/dlibby-) This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. * This document status: **ARCHIVED** * Current venue: [W3C Web Incubator Community Group](https://wicg.io/) | [WICG/ink-enhancement](https://github.com/WICG/ink-enhancement) | ![GitHub issues](https://img.shields.io/github/issues/WICG/ink-enhancement) -* Current version: [Explainer](https://github.com/WICG/ink-enhancement/blob/master/README.md) +* Current version: [Web Ink Enhancement: Delegated Ink Trail Presentation Aided By The OS Explainer](https://github.com/WICG/ink-enhancement/blob/master/README.md) ## Introduction Achieving low latency is critical for delivering great inking experiences on the Web. Ink on the Web is generally produced by consuming PointerEvents and rendering strokes to the application view, whether that be 2D or WebGL canvas, or less commonly, SVG or even HTML. diff --git a/highlight/explainer.md b/highlight/explainer.md index 832eb8741..bc36cb403 100644 --- a/highlight/explainer.md +++ b/highlight/explainer.md @@ -1,7 +1,11 @@ -# MOVED. This doc is now maintained at https://drafts.csswg.org/css-highlight-api-1/. Please refer to that link for the latest content. - # Highlight API Explained +## Status of this Document +This document is intended as a starting point for engaging the community and standards bodies in developing collaborative solutions fit for standardization. As the solutions to problems described in this document progress along the standards-track, we will retain this document as an archive and use this section to keep the community up-to-date with the most current standards venue and content location of future work and discussions. +* This document status: **ARCHIVED** +* Current venue: [W3C CSS Working Group](https://www.w3.org/Style/CSS/) | [w3c/csswg-drafts](https://github.com/w3c/csswg-drafts) | ![GitHub issues by-label](https://img.shields.io/github/issues/w3c/csswg-drafts/css-highlight-api-1) +* Current version: [CSS Custom Highlight API Module Level 1](https://drafts.csswg.org/css-highlight-api-1/) + ## Overview The Highlight API extends the concept of [CSS Highlight Pseudo-elements](https://drafts.csswg.org/css-pseudo-4/#highlight-pseudos) by providing a way for web developers to style the text of arbitrary Range objects, rather than being limited to the user-agent defined ```::selection```, ```::inactive-selection```, ```::spelling-error```, and ```::grammar-error```. This is useful in a variety of scenarios, including editing frameworks that wish to implement their own selection, find-on-page over virtualized documents, multiple selection to represent online collaboration, and spellchecking frameworks.