Styling helpers for ShadyDOM
npm install optimized-shadycssShadyCSS provides a library to simulate ShadowDOM style encapsulation (ScopingShim), a shim for the proposed CSS mixin @apply syntax (ApplyShim), and a library to integrate document-level stylesheets with both of the former libraries (CustomStyleInterface).
ShadyCSS can be used by loading the ScopingShim, ApplyShim, CustomStyleInterface, or any combination of those.
The most-supported loading order is:
1. ScopingShim
1. ApplyShim
1. CustomStyleInterface
All libraries will expose an object on window named ShadyCSS with the following interface:
``js`
ShadyCSS = {
prepareTemplate(templateElement, elementName, elementExtension){},
styleElement(element){},
styleSubtree(element, overrideProperties){},
styleDocument(overrideProperties){},
getComputedStyleValue(element, propertyName){
return // style value for property name on element
},
nativeCss: Boolean,
nativeShadow: Boolean
}
ScopingShim provides simulated ShadyDOM style encapsulation, and a shim for CSS Custom Properties.
ScopingShim works by rewriting style contents and transforming selectors to enforce scoping.
Additionally, if CSS Custom Properties is not detected, ScopingShim will replace CSS Custom Property usage with realized values.
`html`
Shadow
Light
becomes:
`html`Shadow
Light
ApplyShim provides a shim for the @apply syntax proposed at https://tabatkins.github.io/specs/css-apply-rule/, which expands the definition CSS Custom Properties to include objects that can be applied as a block.
This is done by transforming the block definition into a set of CSS Custom Properties, and replacing uses of @apply with consumption of those custom properties.
The @apply proposal has been abandoned in favor of the ::part/::theme Shadow Parts spec. Therefore, the ApplyShim library is deprecated and provided only for backwards compatibility. Support going forward will be limited to critical bug fixes.
* Mixin properties cannot be modified at runtime.
* Nested mixins are not supported.
* Shorthand properties are not expanded and may conflict with more explicit properties. Whenever shorthand notations are used in conjunction with their expanded forms in @apply, depending in the order of usage of the mixins, properties can be overridden. This means that using both background-color: green; and background: red; in two separate CSS selectorsbackground-color: transparent
can result in in the selector that background: red; is specified.`
css`
#nonexistent {
--my-mixin: {
background: red;
}
}
with an element style definition of
css`
:host {
display: block;
background-color: green;
@apply(--my-mixin);
}
results in the background being , as an empty background definition replaces@apply
the definition.
For this reason, we recommend avoiding shorthand properties.
Here we define a block called --mixin at the document level, and apply that block to my-element somewhere in the page.
`css
html {
--mixin: {
border: 2px solid black;
background-color: green;
}
}
my-element {
border: 1px dotted orange;
@apply --mixin;
}
`
becomes:
`css
html {
--mixin_-_border: 2px solid black;
--mixin_-_background-color: green;
}
my-element {
border: var(--mixin_-_border, 1px dotted orange);
background-color: var(--mixin_-_background-color);
}
`
CustomStyleInterface provides API to process
`
Another example with a wrapper element
`html`
Another example with a function that produces style elements
`html`
To use ShadyCSS:
1. First, call ShadyCSS.prepareTemplate(template, name) on a element that will be imported into a shadowRoot.
2. When the element instance is connected, call ShadyCSS.styleElement(element)
3. Create and stamp the element's shadowRoot
4. Whenever dynamic updates are required, call ShadyCSS.styleSubtree(element).
5. If a styling change is made that may affect the whole document, call
ShadyCSS.styleDocument().
The following example uses ShadyCSS and ShadyDOM to define a custom element.
`html`
Content
ShadyCSS can also be used with type extension elements by supplying the base
element name to prepareTemplate as a third argument.
`html`
Content
To set the value of a CSS Custom Property imperatively, ShadyCSS.styleSubtree
and support an additional argument of an object mapping
variable name to value.
When using ApplyShim, defining new mixins or new values for current mixins imperatively is not
supported.
html
Text
Text
`Limitations
$3
You must have a selector for ascendants of the
element when using the ::slotted
pseudo-element.You cannot use any selector for the
element. Rules like .foo .bar::slotted(*) are not supported.$3
Dynamic changes are not automatically applied. If elements change such that they
conditionally match selectors they did not previously,
ShadyCSS.styleDocument()
must be called.For a given element's shadowRoot, only 1 value is allowed per custom properties.
Properties cannot change from parent to child as they can under native custom
properties; they can only change when a shadowRoot boundary is crossed.
To receive a custom property, an element must directly match a selector that
defines the property in its host's stylesheet.
$3
If
is never called, elements will process
after HTML Imports have loaded, after the document loads, or after the next paint.
This means that there may be a flash of unstyled content on the first load.$3
Crawling the DOM and updating styles is very expensive, and we found that trying to
update mixins through
insertion points to be too expensive to justify for both
polyfilled CSS Mixins and polyfilled CSS Custom Properties.$3
External stylesheets loaded via
within a shadow root or
@import syntax inside a shadow root's stylesheet are not currently shimmed by
the polyfill. This is mainly due to the fact that shimming them would require
a fetch of the stylesheet text that is async cannot be easily coordinated with
the upgrade timing of custom elements using them, making it impossible to avoid
"flash of unstyled content" when running on polyfill.$3
ShadyCSS mimics the behavior of shadow dom, but it is not able to prevent document
level styling to affect elements inside a shady dom. Global styles defined in
index.html or any styles not processed by ShadyCSS will affect all elements on the page.To scope document level styling, the style must be wrapped in the
element
found in Polymer, or use the CustomStyleInterface` library to modify document level styles.ShadyCSS works by processing a template for a given custom element class. Only the style
elements present in that template will be scoped for the custom element's ShadowRoot.