-
Notifications
You must be signed in to change notification settings - Fork 19
/
Copy pathindex.html
573 lines (570 loc) · 20.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>
Window Controls Overlay
</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"
defer></script>
<script class="remove">
// All config options at https://respec.org/docs/
var respecConfig = {
mdn: true,
specStatus: "CG-DRAFT",
editors: [{ name: "Diego González",
url: "https://twitter.com/diekus",
company: "Microsoft",
companyURL: "https://www.microsoft.com"}],
github: "WICG/window-controls-overlay",
shortName:"window-controls-overlay",
xref: {
profile: "web-platform",
specs: [
"appmanifest",
"cssom-view",
"geometry-1",
"manifest-incubations",
"MEDIAQUERIES-5"
]
},
group: "wicg",
};
</script>
</head>
<body>
<section id="abstract">
<p>
This document specifies a set of technologies that allow a Web
developer to take control over the area that would generally be
occupied by the title bar in an installed web application running on a
desktop environment. These technologies are known as (<abbr title=
"Window Controls Overlay">WCO</abbr>).
</p>
</section>
<section id="sotd">
<p>
This draft is meant to serve as a starting point for the
standardization process of WCO and the technologies described in it
might be migrated to other specifications on different working groups.
</p>
</section>
<section class="informative">
<h2>
Introduction
</h2>
<p>
Applications targeting non-mobile devices are hosted within frames that
commonly have a title bar. A title bar is a UI element generally
represented as a horizontal bar at the top of a window, bearing the
name of the active program or the name of the current active document
and and the [=window controls=]. Modern applications can take advantage
of the area in the title bar in order to display UI content to create a
better UX.
</p>
<p>
For installed web apps hosted within a user agent (UA) frame, it is
possible to get some form of customization in the frame by declaring
which type of display mode is preferred. Developers can select the mode
that best meets the needs of the application via the [=manifest=]
file's `display` member. However, these modes are limited and do not
provide the same level of control over the title bar, therefore
developers looking to create an immersive, native-like title bar for
their installed application can't achieve this with the aforementioned
member. Instead, the client area begins immediately below the reserved
title bar region, which can create a cramped application space
specially on portable devices with smaller screens.
</p>
<p>
WCO enables the creation of custom title bar UI by leaving only the
[=window controls=] [=overlaid=] on the frame, in which case web
content can flow into the area previously held by the title bar.
</p><img src="spec-wco.png" alt=
"Blank window frame showing the controls area.">
<section>
<h3>
Examples
</h3>
<aside class="example">
<p>
Positioning a div on the title bar area
</p>
<pre class="css">
.titleBar {
position: fixed;
left: env(titlebar-area-x, 0);
top: env(titlebar-area-y, 0);
width: env(titlebar-area-width, 100%);
height: env(titlebar-area-height, 40px);
app-region: drag;
}
</pre>
<pre>
<div class="titlebar">
This is web content in the title bar region!
<div>
</pre>
</aside>
</section>
<aside class="note">
<p>
The WCO feature is useful in environments that use the paradigm of a
window to house applications. Notches, irregular shaped viewports or
layout of content around hardware constraints is outside of the scope
of the spec.
</p>
<p>
The window paradigm for desktop-like environments is UX that has
proven effective at managing information architecture over decades.
It is a paradigm that continues to evolve, and part of this evolution
is allowing modern apps to take control of the area of the window
that was before reserved for the title bar. WCO enables this in the
same way that apps created with native technologies can take
advantage of today.
</p>
<p>
<strong>Notches and other hardware elements do not interfere with the
title bar region of any app window on any platform</strong>. They can
intersect parts of the OS such as the status or menu area, and this
is handled entirely by the host OS. The WCO feature does not deal
with any area that can be intersected by a notch.
</p>
<p>
Notches do not leave considerable space to work with, can be in
arbitrary positions, and not necessarily be rectangular.
Additionally, most GUI guidelines from vendors that implement notches
to maximize screen-body ratio on their devices recommend not to
position content around the notch.
</p>
</aside>
</section>
<section>
<h2>
Concepts
</h2>
<ul>
<li>
<dfn>Window Controls Overlay</dfn>: feature for installed web
applications running on non-mobile environments that allows the
viewport to expand over the [=title bar area=] using JS and CSS.
</li>
<li>
<dfn>Title bar area</dfn>: When WCO is enabled, this is the the
region of the window frame occupied by the title bar without the area
corresponding to the [=overlay=] that houses the [=controls of the
window=].
</li>
<li>
<dfn data-lt="controls of the window">Window controls</dfn>:
interface elements that the operating system uses consistently across
applications to enable the user to perform certain actions to control
the application. Common actions in the [=window controls=] include
minimize, maximize/restore, and close buttons.
</li>
<li>
<dfn data-lt="overlaid">Overlay</dfn> of [=window controls=]: Area
that houses the [=controls of the window=] and is overlaid on top of
the viewport.
</li><img src="spec-wco-areas.png" alt=
"Window frame with window controls circled.">
</ul>
</section>
<section>
<h2>
Extensions to the `Navigator` interface
</h2>
<p>
The [[HTML]] specification defines the <dfn>Navigator</dfn> interface,
which this specification extends:
</p>
<pre class="idl">
[SecureContext, Exposed=(Window)]
partial interface Navigator {
[SameObject] readonly attribute WindowControlsOverlay windowControlsOverlay;
};
</pre>
</section>
<section>
<h2>
Extensions to the `Window` interface
</h2>
<section>
<h3>
Internal slots
</h3>
<table class="simple">
<thead>
<tr>
<th>
Internal slot
</th>
<th>
Initial value
</th>
<th>
Description
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<dfn data-dfn-for="Window">[[\TitleBarArea]]</dfn>
</td>
<td>
Empty [=struct=] for the title bar region.
</td>
<td>
A [=struct=] that stores the values of the area that defines
the title bar region. These values are `x`, `y`, `width`,
`height`.
</td>
</tr>
</tbody>
</table>
</section>
</section>
<section data-dfn-for='WindowControlsOverlay' data-link-for=
'WindowControlsOverlay'>
<h2>
<dfn>WindowControlsOverlay</dfn> interface
</h2>
<pre class='idl' data-cite="DOM HTML">
[Exposed=Window]
interface WindowControlsOverlay : EventTarget {
readonly attribute boolean visible;
DOMRect getTitlebarAreaRect();
attribute EventHandler ongeometrychange;
};
[Exposed=Window]
interface WindowControlsOverlayGeometryChangeEvent : Event {
constructor(DOMString type, WindowControlsOverlayGeometryChangeEventInit eventInitDict);
[SameObject] readonly attribute DOMRect titlebarAreaRect;
readonly attribute boolean visible;
};
dictionary WindowControlsOverlayGeometryChangeEventInit : EventInit {
required DOMRect titlebarAreaRect;
boolean visible = false;
};
</pre>
<section>
<h3>
The <dfn>visible</dfn> attribute
</h3>
<p>
The `visible` attribute is a [=boolean=] that returns `true` when the
values of the {{Window/window}}.[[\TitleBarArea]] are not 0.
</p>
</section>
<section>
<h3>
The <dfn>getTitlebarAreaRect</dfn> method
</h3>
<p>
The `getTitlebarAreaRect()` method returns a DOMRect that represents
the available area for displaying web content. This available title
bar region does not include the area under the [=window controls=]
[=overlay=].
</p><img src="spec-wco-gbr.png" alt=
"depiction of the area returned by the getTitlebarAreaRect method">
<aside class="note">
<p>
The client viewport does not make any special considerations when
rendering content with the WCO feature enabled. The content will be
displayed in the same way that it would be displayed inside the
browser window. In order to avoid content being hidden by the area
where the [=window controls=] are [=overlaid=], developers need to
use the `getTitlebarAreaRect` method or the [=title bar area env
variables=].
</p>
</aside>
<aside class="note">
<p>
If a user agent does not support WCO, the developer can use
reasonable fallbacks for both the [=manifest/display_override=]
using [=manifest/display=] and the CSS variables and JS object
accordingly.
</p>
</aside>
</section>
<section>
<h3>
The <dfn>ongeometrychange</dfn> attribute
</h3>
<p>
The `ongeometrychange` attribute is an event handler whose
corresponding event handler event type is "change".
</p>
</section>
</section>
<section>
<h2>
Addition of new [=display mode/window-controls-overlay=] [=display mode=]
</code>
</h2>
<p>
This specification defines the following [=display mode=]:
</p>
<dl>
<dt>
<dfn data-export="" data-dfn-for="display mode">
window-controls-overlay
</dfn>
</dt>
<dd>
The web application opens with native OS window controls visible but
with the web contents extended to the rest of the title bar area. The
app will also be able to specify [=draggable region=]s in the web
contents to create a customized title bar.
</dd>
</dl>
<p>
The <code>[=display mode/window-controls-overlay=]</code>
[=display mode=] can be specified in the
<code>[=manifest/display_override=]</code> member of the manifest.
</p>
<aside class="issue">
<p>
TO DO: This is draft text for features that might belong in other
specifications. This document might not be the final venue for some
of the work specified in this draft. (manifest/manifest incubations)
</p>
</aside>
</section>
<section>
<h2>
<dfn>Title bar area environmental variables</dfn>
</h2>
<aside class="issue">
<p>
TO DO: This is draft text for features that might belong in other
specifications. This document might not be the final venue for some
of the work specified in this draft. (CSS)
</p>
</aside>
<section>
<h3>
<dfn>Title bar area env variables</dfn>
</h3>
<table dfn-type="value" dfn-for="env()">
<tr>
<th>
Name
</th>
<th>
Value
</th>
</tr>
<tr>
<td>
<dfn>`titlebar-area-x`</dfn>
</td>
<td>
<a href=
"https://drafts.csswg.org/css-values-3/#length-value">length</a>
</td>
</tr>
<tr>
<td>
<dfn>`titlebar-area-y`</dfn>
</td>
<td>
<a href=
"https://drafts.csswg.org/css-values-3/#length-value">length</a>
</td>
</tr>
<tr>
<td>
<dfn>`titlebar-area-width`</dfn>
</td>
<td>
<a href=
"https://drafts.csswg.org/css-values-3/#length-value">length</a>
</td>
</tr>
<tr>
<td>
<dfn>`titlebar-area-height`</dfn>
</td>
<td>
<a href=
"https://drafts.csswg.org/css-values-3/#length-value">length</a>
</td>
</tr>
</table>
<p>
The [=title bar area environmental variables=] are four env variables
that define a rectangle by the width and height from a starting point
in the viewport. This area corresponds to the available area of the
title bar, and allows to position dynamic Web content inside its
bounds.
</p>
</section>
</section>
<section>
<h2>
Integration with CSSOM
</h2>
<p>
This specification integrates with the [[cssom-view]] specification by
patching the <a href=
"https://www.w3.org/TR/cssom-view-1/#run-the-resize-steps">algorithm
below</a>:
</p>
<p>
In the viewport [=Window/resize=] algorithm, run [=resize the title bar
area=] after step 1.
</p>
</section>
<section>
<h2>
Algorithms
</h2>
<section>
<h3>
Resize the title bar area
</h3>
<p>
To <dfn data-lt="title bar region resizes">resize the title bar
area</dfn> for a window |win|, run these steps:
</p>
<ol>
<li>If |win|'s [=overlay=] has had its width or height changed (e.g.
as a result of the user resizing the browser window, or changing the
page zoom factor, or other UI appearing or disappearing on the
[=overlay=]), since the last time these steps were run, [=fire an
event=] named `ongeometrychange` at the {{Window/window}} object and
[=update the overlay area information=].
</li>
</ol>
</section>
<section>
<h3>
Update the overlay area information
</h3>
<p>
To <dfn>update the overlay area information</dfn>, run these steps:
</p>
<ol class="algorithm">
<li>Let |ovls| be a [=list=] of regions defined by the [=overlays=]
that house the [=window controls=] on the the window frame.
</li>
<li>Let |tba| be an empty {{DOMRect}} object representing the
available title bar area.
<ol>
<li>If there is only one overlay region in |ovls|, set |tba| as a
{{DOMRect}} that encompasses the area from the edge of the frame
to the innermost edge of the |ovls|.
</li>
<li>If there is more than one overlay region in |ovls|, set |tba|
to a {{DOMRect}} that encompasses the area between the
intersection of the regions in |ovls| and the [=document=]'s
<a href="https://drafts.csswg.org/css2/#viewport">viewport</a>.
</li>
<li>|tba|'s height should be the same as the height of the
regions in |ovls|.
</li>
</ol>
</li>
<li>Make {{Window/window}}.[[\TitleBarArea]] equal to |tba|.
</li>
<li>Update the [=title bar area env variables=] with information from
{{Window/window}}.[[\TitleBarArea]].
</li>
</ol>
</section>
</section>
<section>
<h2>
Security and privacy considerations
</h2>
<section>
<h3>
Security
</h3>
<section>
<h4>
Spoofing risks
</h4>
<p>
Displaying installed web apps in a frameless window leaves room for
developers to spoof content in what was previously a trusted,
UA-controlled region.
</p>
<p>
Currently in Chromium browsers, `standalone` mode includes a title
bar which on initial launch displays the title of the webpage on
the left, and the origin of the page on the right (followed by the
"settings and more" button and the window controls). After a few
seconds, the origin text disappears.
</p>
<p>
In RTL configured browsers, this layout is flipped such that the
origin text is on the left. This open the window controls overlay
to spoofing the origin if there is insufficient padding between the
origin and the right edge of the overlay. For example, the origin
"evil.ltd" could be appended with a trusted site "google.com",
leading users to believe that the source is trustworthy.
</p>
</section>
<section>
<h4>
Out-of-scope Navigation
</h4>
<p>
Another existing security feature for installed web apps is an
indicator of when a user has left the declared scope of the app.
When a user navigates out of scope, a black bar appears between the
title bar and the web content, and it includes the following
information:
</p>
<ul>
<li>A close button to allow users to easily navigate back into
scope
</li>
<li>A security icon which opens the security info popup when
clicked
</li>
<li>The origin and title of the site
</li>
</ul>
<p>
With the window controls overlay enabled, if a user navigates
out-of-scope the overlay will be temporarily replaced with a
standalone title bar. When the user navigates back to into scope,
the standalone title bar will be hidden again and the overlay
displayed.
</p>
</section>
</section>
<section>
<h3>
Privacy
</h3>
<p>
Enabling Window Controls Overlay poses an increased fingerprinting
surface since the size of the overlay can vary depending on the OS,
the text scale, the OS font size, the OS zoom factor, and the web
content’s zoom factor.
</p>
<p>
Although this is a potential fingerprinting issue, it only applies to
installed desktop web apps that use the window controls overlay
feature and does not apply to general browser usage. Additionally,
the windowControlsOverlay API will not be available to iframes
embedded inside of an installed web app.
</p>
</section>
</section>
<section class="appendix informative" id="acknowledgments">
<h2>
Acknowledgments
</h2>
<p>
Huge thanks to Amanda Baker, Joshua Bell and Yoav Weiss for their
contributions to this work.
</p>
</section>
<section id="conformance"></section>
</body>
</html>