forked from PolymerElements/iron-overlay-behavior
-
Notifications
You must be signed in to change notification settings - Fork 0
/
iron-overlay-behavior.html
657 lines (578 loc) · 20.6 KB
/
iron-overlay-behavior.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
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
<!--
@license
Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->
<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../iron-fit-behavior/iron-fit-behavior.html">
<link rel="import" href="../iron-resizable-behavior/iron-resizable-behavior.html">
<link rel="import" href="iron-overlay-manager.html">
<script>
(function() {
'use strict';
/**
Use `Polymer.IronOverlayBehavior` to implement an element that can be hidden or shown, and displays
on top of other content. It includes an optional backdrop, and can be used to implement a variety
of UI controls including dialogs and drop downs. Multiple overlays may be displayed at once.
See the [demo source code](https://github.com/PolymerElements/iron-overlay-behavior/blob/master/demo/simple-overlay.html)
for an example.
### Closing and canceling
An overlay may be hidden by closing or canceling. The difference between close and cancel is user
intent. Closing generally implies that the user acknowledged the content on the overlay. By default,
it will cancel whenever the user taps outside it or presses the escape key. This behavior is
configurable with the `no-cancel-on-esc-key` and the `no-cancel-on-outside-click` properties.
`close()` should be called explicitly by the implementer when the user interacts with a control
in the overlay element. When the dialog is canceled, the overlay fires an 'iron-overlay-canceled'
event. Call `preventDefault` on this event to prevent the overlay from closing.
### Positioning
By default the element is sized and positioned to fit and centered inside the window. You can
position and size it manually using CSS. See `Polymer.IronFitBehavior`.
### Backdrop
Set the `with-backdrop` attribute to display a backdrop behind the overlay. The backdrop is
appended to `<body>` and is of type `<iron-overlay-backdrop>`. See its doc page for styling
options.
In addition, `with-backdrop` will wrap the focus within the content in the light DOM.
Override the [`_focusableNodes` getter](#Polymer.IronOverlayBehavior:property-_focusableNodes)
to achieve a different behavior.
### Limitations
The element is styled to appear on top of other content by setting its `z-index` property. You
must ensure no element has a stacking context with a higher `z-index` than its parent stacking
context. You should place this element as a child of `<body>` whenever possible.
@demo demo/index.html
@polymerBehavior Polymer.IronOverlayBehavior
*/
Polymer.IronOverlayBehaviorImpl = {
properties: {
/**
* True if the overlay is currently displayed.
*/
opened: {
observer: '_openedChanged',
type: Boolean,
value: false,
notify: true
},
/**
* True if the overlay was canceled when it was last closed.
*/
canceled: {
observer: '_canceledChanged',
readOnly: true,
type: Boolean,
value: false
},
/**
* Set to true to display a backdrop behind the overlay. It traps the focus
* within the light DOM of the overlay.
*/
withBackdrop: {
observer: '_withBackdropChanged',
type: Boolean
},
/**
* Set to true to disable auto-focusing the overlay or child nodes with
* the `autofocus` attribute` when the overlay is opened.
*/
noAutoFocus: {
type: Boolean,
value: false
},
/**
* Set to true to disable canceling the overlay with the ESC key.
*/
noCancelOnEscKey: {
type: Boolean,
value: false
},
/**
* Set to true to disable canceling the overlay by clicking outside it.
*/
noCancelOnOutsideClick: {
type: Boolean,
value: false
},
/**
* Contains the reason(s) this overlay was last closed (see `iron-overlay-closed`).
* `IronOverlayBehavior` provides the `canceled` reason; implementers of the
* behavior can provide other reasons in addition to `canceled`.
*/
closingReason: {
// was a getter before, but needs to be a property so other
// behaviors can override this.
type: Object
},
/**
* Set to true to enable restoring of focus when overlay is closed.
*/
restoreFocusOnClose: {
type: Boolean,
value: false
},
/**
* Set to true to keep overlay always on top.
*/
alwaysOnTop: {
type: Boolean
},
/**
* Shortcut to access to the overlay manager.
* @private
* @type {Polymer.IronOverlayManagerClass}
*/
_manager: {
type: Object,
value: Polymer.IronOverlayManager
},
/**
* The node being focused.
* @type {?Node}
*/
_focusedChild: {
type: Object
}
},
listeners: {
'iron-resize': '_onIronResize'
},
/**
* The backdrop element.
* @type {Element}
*/
get backdropElement() {
return this._manager.backdropElement;
},
/**
* Returns the node to give focus to.
* @type {Node}
*/
get _focusNode() {
return this._focusedChild || Polymer.dom(this).querySelector('[autofocus]') || this;
},
/**
* Array of nodes that can receive focus (overlay included), ordered by `tabindex`.
* This is used to retrieve which is the first and last focusable nodes in order
* to wrap the focus for overlays `with-backdrop`.
*
* If you know what is your content (specifically the first and last focusable children),
* you can override this method to return only `[firstFocusable, lastFocusable];`
* @type {Array<Node>}
* @protected
*/
get _focusableNodes() {
// Elements that can be focused even if they have [disabled] attribute.
var FOCUSABLE_WITH_DISABLED = [
'a[href]',
'area[href]',
'iframe',
'[tabindex]',
'[contentEditable=true]'
];
// Elements that cannot be focused if they have [disabled] attribute.
var FOCUSABLE_WITHOUT_DISABLED = [
'input',
'select',
'textarea',
'button'
];
// Discard elements with tabindex=-1 (makes them not focusable).
var selector = FOCUSABLE_WITH_DISABLED.join(':not([tabindex="-1"]),') +
':not([tabindex="-1"]),' +
FOCUSABLE_WITHOUT_DISABLED.join(':not([disabled]):not([tabindex="-1"]),') +
':not([disabled]):not([tabindex="-1"])';
var focusables = Polymer.dom(this).querySelectorAll(selector);
if (this.tabIndex >= 0) {
// Insert at the beginning because we might have all elements with tabIndex = 0,
// and the overlay should be the first of the list.
focusables.splice(0, 0, this);
}
// Sort by tabindex.
return focusables.sort(function (a, b) {
if (a.tabIndex === b.tabIndex) {
return 0;
}
if (a.tabIndex === 0 || a.tabIndex > b.tabIndex) {
return 1;
}
return -1;
});
},
ready: function() {
// Used to skip calls to notifyResize and refit while the overlay is animating.
this.__isAnimating = false;
// with-backdrop needs tabindex to be set in order to trap the focus.
// If it is not set, IronOverlayBehavior will set it, and remove it if with-backdrop = false.
this.__shouldRemoveTabIndex = false;
// Used for wrapping the focus on TAB / Shift+TAB.
this.__firstFocusableNode = this.__lastFocusableNode = null;
// Used by __onNextAnimationFrame to cancel any previous callback.
this.__raf = null;
// Focused node before overlay gets opened. Can be restored on close.
this.__restoreFocusNode = null;
this._ensureSetup();
},
attached: function() {
// Call _openedChanged here so that position can be computed correctly.
if (this.opened) {
this._openedChanged(this.opened);
}
this._observer = Polymer.dom(this).observeNodes(this._onNodesChange);
},
detached: function() {
Polymer.dom(this).unobserveNodes(this._observer);
this._observer = null;
if (this.__raf) {
window.cancelAnimationFrame(this.__raf);
this.__raf = null;
}
this._manager.removeOverlay(this);
},
/**
* Toggle the opened state of the overlay.
*/
toggle: function() {
this._setCanceled(false);
this.opened = !this.opened;
},
/**
* Open the overlay.
*/
open: function() {
this._setCanceled(false);
this.opened = true;
},
/**
* Close the overlay.
*/
close: function() {
this._setCanceled(false);
this.opened = false;
},
/**
* Cancels the overlay.
* @param {Event=} event The original event
*/
cancel: function(event) {
var cancelEvent = this.fire('iron-overlay-canceled', event, {cancelable: true});
if (cancelEvent.defaultPrevented) {
return;
}
this._setCanceled(true);
this.opened = false;
},
_ensureSetup: function() {
if (this._overlaySetup) {
return;
}
this._overlaySetup = true;
this.style.outline = 'none';
this.style.display = 'none';
},
/**
* Called when `opened` changes.
* @param {boolean=} opened
* @protected
*/
_openedChanged: function(opened) {
if (opened) {
this.removeAttribute('aria-hidden');
} else {
this.setAttribute('aria-hidden', 'true');
}
// Defer any animation-related code on attached
// (_openedChanged gets called again on attached).
if (!this.isAttached) {
return;
}
this.__isAnimating = true;
// Use requestAnimationFrame for non-blocking rendering.
this.__onNextAnimationFrame(this.__openedChanged);
},
_canceledChanged: function() {
this.closingReason = this.closingReason || {};
this.closingReason.canceled = this.canceled;
},
_withBackdropChanged: function() {
// If tabindex is already set, no need to override it.
if (this.withBackdrop && !this.hasAttribute('tabindex')) {
this.setAttribute('tabindex', '-1');
this.__shouldRemoveTabIndex = true;
} else if (this.__shouldRemoveTabIndex) {
this.removeAttribute('tabindex');
this.__shouldRemoveTabIndex = false;
}
if (this.opened && this.isAttached) {
this._manager.trackBackdrop();
}
},
/**
* tasks which must occur before opening; e.g. making the element visible.
* @protected
*/
_prepareRenderOpened: function() {
// Store focused node.
this.__restoreFocusNode = this._manager.deepActiveElement;
// Needed to calculate the size of the overlay so that transitions on its size
// will have the correct starting points.
this._preparePositioning();
this.refit();
this._finishPositioning();
// Safari will apply the focus to the autofocus element when displayed
// for the first time, so we make sure to return the focus where it was.
if (this.noAutoFocus && document.activeElement === this._focusNode) {
this._focusNode.blur();
this.__restoreFocusNode.focus();
}
},
/**
* Tasks which cause the overlay to actually open; typically play an animation.
* @protected
*/
_renderOpened: function() {
this._finishRenderOpened();
},
/**
* Tasks which cause the overlay to actually close; typically play an animation.
* @protected
*/
_renderClosed: function() {
this._finishRenderClosed();
},
/**
* Tasks to be performed at the end of open action. Will fire `iron-overlay-opened`.
* @protected
*/
_finishRenderOpened: function() {
this.notifyResize();
this.__isAnimating = false;
// Store it so we don't query too much.
var focusableNodes = this._focusableNodes;
this.__firstFocusableNode = focusableNodes[0];
this.__lastFocusableNode = focusableNodes[focusableNodes.length - 1];
this.fire('iron-overlay-opened');
},
/**
* Tasks to be performed at the end of close action. Will fire `iron-overlay-closed`.
* @protected
*/
_finishRenderClosed: function() {
// Hide the overlay.
this.style.display = 'none';
// Reset z-index only at the end of the animation.
this.style.zIndex = '';
this.notifyResize();
this.__isAnimating = false;
this.fire('iron-overlay-closed', this.closingReason);
},
_preparePositioning: function() {
this.style.transition = this.style.webkitTransition = 'none';
this.style.transform = this.style.webkitTransform = 'none';
this.style.display = '';
},
_finishPositioning: function() {
// First, make it invisible & reactivate animations.
this.style.display = 'none';
// Force reflow before re-enabling animations so that they don't start.
// Set scrollTop to itself so that Closure Compiler doesn't remove this.
this.scrollTop = this.scrollTop;
this.style.transition = this.style.webkitTransition = '';
this.style.transform = this.style.webkitTransform = '';
// Now that animations are enabled, make it visible again
this.style.display = '';
// Force reflow, so that following animations are properly started.
// Set scrollTop to itself so that Closure Compiler doesn't remove this.
this.scrollTop = this.scrollTop;
},
/**
* Applies focus according to the opened state.
* @protected
*/
_applyFocus: function() {
if (this.opened) {
if (!this.noAutoFocus) {
this._focusNode.focus();
}
}
else {
this._focusNode.blur();
this._focusedChild = null;
// Restore focus.
if (this.restoreFocusOnClose && this.__restoreFocusNode) {
this.__restoreFocusNode.focus();
}
this.__restoreFocusNode = null;
// If many overlays get closed at the same time, one of them would still
// be the currentOverlay even if already closed, and would call _applyFocus
// infinitely, so we check for this not to be the current overlay.
var currentOverlay = this._manager.currentOverlay();
if (currentOverlay && this !== currentOverlay) {
currentOverlay._applyFocus();
}
}
},
/**
* Cancels (closes) the overlay. Call when click happens outside the overlay.
* @param {!Event} event
* @protected
*/
_onCaptureClick: function(event) {
if (!this.noCancelOnOutsideClick) {
this.cancel(event);
}
},
/**
* Keeps track of the focused child. If withBackdrop, traps focus within overlay.
* @param {!Event} event
* @protected
*/
_onCaptureFocus: function (event) {
if (!this.withBackdrop) {
return;
}
var path = Polymer.dom(event).path;
if (path.indexOf(this) === -1) {
event.stopPropagation();
this._applyFocus();
} else {
this._focusedChild = path[0];
}
},
/**
* Handles the ESC key event and cancels (closes) the overlay.
* @param {!Event} event
* @protected
*/
_onCaptureEsc: function(event) {
if (!this.noCancelOnEscKey) {
this.cancel(event);
}
},
/**
* Handles TAB key events to track focus changes.
* Will wrap focus for overlays withBackdrop.
* @param {!Event} event
* @protected
*/
_onCaptureTab: function(event) {
if (!this.withBackdrop) {
return;
}
// TAB wraps from last to first focusable.
// Shift + TAB wraps from first to last focusable.
var shift = event.shiftKey;
var nodeToCheck = shift ? this.__firstFocusableNode : this.__lastFocusableNode;
var nodeToSet = shift ? this.__lastFocusableNode : this.__firstFocusableNode;
var shouldWrap = false;
if (nodeToCheck === nodeToSet) {
// If nodeToCheck is the same as nodeToSet, it means we have an overlay
// with 0 or 1 focusables; in either case we still need to trap the
// focus within the overlay.
shouldWrap = true;
} else {
// In dom=shadow, the manager will receive focus changes on the main
// root but not the ones within other shadow roots, so we can't rely on
// _focusedChild, but we should check the deepest active element.
var focusedNode = this._manager.deepActiveElement;
// If the active element is not the nodeToCheck but the overlay itself,
// it means the focus is about to go outside the overlay, hence we
// should prevent that (e.g. user opens the overlay and hit Shift+TAB).
shouldWrap = (focusedNode === nodeToCheck || focusedNode === this);
}
if (shouldWrap) {
// When the overlay contains the last focusable element of the document
// and it's already focused, pressing TAB would move the focus outside
// the document (e.g. to the browser search bar). Similarly, when the
// overlay contains the first focusable element of the document and it's
// already focused, pressing Shift+TAB would move the focus outside the
// document (e.g. to the browser search bar).
// In both cases, we would not receive a focus event, but only a blur.
// In order to achieve focus wrapping, we prevent this TAB event and
// force the focus. This will also prevent the focus to temporarily move
// outside the overlay, which might cause scrolling.
event.preventDefault();
this._focusedChild = nodeToSet;
this._applyFocus();
}
},
/**
* Refits if the overlay is opened and not animating.
* @protected
*/
_onIronResize: function() {
if (this.opened && !this.__isAnimating) {
this.__onNextAnimationFrame(this.refit);
}
},
/**
* Will call notifyResize if overlay is opened.
* Can be overridden in order to avoid multiple observers on the same node.
* @protected
*/
_onNodesChange: function() {
if (this.opened && !this.__isAnimating) {
this.notifyResize();
}
},
/**
* Tasks executed when opened changes: prepare for the opening, move the
* focus, update the manager, render opened/closed.
* @private
*/
__openedChanged: function() {
if (this.opened) {
// Make overlay visible, then add it to the manager.
this._prepareRenderOpened();
this._manager.addOverlay(this);
// Move the focus to the child node with [autofocus].
this._applyFocus();
this._renderOpened();
} else {
// Remove overlay, then restore the focus before actually closing.
this._manager.removeOverlay(this);
this._applyFocus();
this._renderClosed();
}
},
/**
* Executes a callback on the next animation frame, overriding any previous
* callback awaiting for the next animation frame. e.g.
* `__onNextAnimationFrame(callback1) && __onNextAnimationFrame(callback2)`;
* `callback1` will never be invoked.
* @param {!Function} callback Its `this` parameter is the overlay itself.
* @private
*/
__onNextAnimationFrame: function(callback) {
if (this.__raf) {
window.cancelAnimationFrame(this.__raf);
}
var self = this;
this.__raf = window.requestAnimationFrame(function nextAnimationFrame() {
self.__raf = null;
callback.call(self);
});
}
};
/** @polymerBehavior */
Polymer.IronOverlayBehavior = [Polymer.IronFitBehavior, Polymer.IronResizableBehavior, Polymer.IronOverlayBehaviorImpl];
/**
* Fired after the overlay opens.
* @event iron-overlay-opened
*/
/**
* Fired when the overlay is canceled, but before it is closed.
* @event iron-overlay-canceled
* @param {Event} event The closing of the overlay can be prevented
* by calling `event.preventDefault()`. The `event.detail` is the original event that
* originated the canceling (e.g. ESC keyboard event or click event outside the overlay).
*/
/**
* Fired after the overlay closes.
* @event iron-overlay-closed
* @param {Event} event The `event.detail` is the `closingReason` property
* (contains `canceled`, whether the overlay was canceled).
*/
})();
</script>