diff --git a/README.md b/README.md index 794f018..bb83333 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# j-elements +# JElements > Proof-of-concept helpers and prototype web components @@ -9,7 +9,7 @@ ## Proof-of-concept helper elements and mixins -See the documentation for `StylableMixin` and `TeleportingElement`. +See the documentation for `LightStyleElement`, `StylableMixin` and `PortalElement`. diff --git a/docs/app-layout.md b/docs/app-layout.md index 72b0341..65f722f 100644 --- a/docs/app-layout.md +++ b/docs/app-layout.md @@ -1,4 +1,4 @@ -# App Layout (Prototype) +# App Layout (Preview) The `` is a responsive application layout that covers multiple common application layout patterns. diff --git a/docs/avatar.md b/docs/avatar.md index e212d00..57f139a 100644 --- a/docs/avatar.md +++ b/docs/avatar.md @@ -1,4 +1,4 @@ -# Avatar (Request for feedback) +# Avatar (Beta) ### Default avatar diff --git a/docs/card.md b/docs/card.md index 01eccbc..b5c13aa 100644 --- a/docs/card.md +++ b/docs/card.md @@ -1,4 +1,4 @@ -# Card (Prototype) +# Card (Preview) ### Simple card ```html,live diff --git a/docs/dialog.md b/docs/dialog.md index ee690fe..32a0dc2 100644 --- a/docs/dialog.md +++ b/docs/dialog.md @@ -1,8 +1,8 @@ # Dialog (Proof of concept) -A dialog is created using the `` element. It is based on [Teleporting Element](/teleporting-element), and because of that will always show on top of other content, escaping any parent stacking contexts. +A dialog is created using the `` element. It is based on [Portal Element](/portal-element), and because of that will always show on top of other content, escaping any parent stacking contexts. -Place any content you wish to show inside the dialog as the children, and use the `visible` attribute/property or the `show()` and `hide()` methods for opening and closing it. +Place any content you wish to show inside the dialog as the children, and use the `show()` and `hide()` methods for opening and closing it. ```html @@ -17,12 +17,12 @@ Place any content you wish to show inside the dialog as the children, and use th Demonstrating how you can toggle the visibility of a dialog which has been created declaratively with HTML. ```html,live - +Open

Declarative dialog

Dialog content.

- + Close
+``` + +Then we can use the new element and apply animations for inserted and removed elements. + +
+```html,live +Add item +Remove item +Add & remove items + + +
Item 1
+
Item 2
+
Item 3
+
Item 4
+
Item 5
+
+ + + + +``` + + diff --git a/docs/portal-element.md b/docs/portal-element.md new file mode 100644 index 0000000..89ee9a9 --- /dev/null +++ b/docs/portal-element.md @@ -0,0 +1,35 @@ +# Portal Element (Proof of concept) + +## Problem + +Showing an element on top of all other content on the page regardless of its position in the element hierarchy is sometimes tricky. + +Unless you know the full hierarchy “above” the element that needs to be shown on top of all others, you have to be prepared that there might be a clipping stacking context somewhere in the hierarchy which ends up clipping your element. + +The problem is most apparent when creating a reusable overlay element. + +## Solution + +Most often, this problem is solved by declaring such elements directly under the `` element, which guarantees they are inside the topmost stacking context on the page. This makes it tricky to manage the elements when building modular applications. + +The Portal Element utility (base class) allows you to define an element anywhere in the hierarchy and, when enabled, move itself (and its contents) under the `` element. + +> Unlike the previous iteration, Teleporting Element, Portal Element does support one level of nested `` elements, making it more versatile in compositions. + +## Limitations + +- When the element `disabled` property is toggled the `disconnectedCallback` and `connectedCallback` are called on the main element as well as on all the child elements +- The content is “live” (i.e. parsed and executed) even when it is not show to the user. This is similar how for example [``](https://www.webcomponents.org/element/PolymerElements/paper-dialog) works. +- Wrapping the content in a `