explain limitation of focus wrapping

PolymerElements · Jun 21, 2016 · c0e45fe · c0e45fe
1 parent 2e22be6
commit c0e45fe
Showing 1 changed file with 6 additions and 1 deletion.
diff --git a/iron-overlay-behavior.html b/iron-overlay-behavior.html
@@ -52,6 +52,10 @@
 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.
 
+Focus wrapping is limited to content in the light DOM (see [`withBackdrop`](#Polymer.IronOverlayBehavior:property-withBackdrop)).
+First and last focusables are computed on opening, so ensure to set any focus related
+properties (e.g. `tabindex` or `disabled` attributes) before opening the overlay.
+
 @demo demo/index.html
 @polymerBehavior Polymer.IronOverlayBehavior
 */
@@ -81,7 +85,8 @@
       },
 
       /**
-       * Set to true to display a backdrop behind the overlay.
+       * Set to true to display a backdrop behind the overlay. It traps the focus
+       * within the light DOM of the overlay.
        */
       withBackdrop: {
         observer: '_withBackdropChanged',