platform-tools2.zip

# ShadyCSS ShadyCSS 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). ## Requirements ShadyCSS requires support for the `<template>` element, ShadowDOM, MutationObserver, Promise, and Object.assign ## Loading 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 } ``` ## About ScopingShim 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. ### Example: Here's an example of a custom element when Scoping Shim is not needed. ```html <my-element> <!-- shadow-root --> <style> :host { display: block; } #container slot::slotted(*) { color: gray; } #foo { color: black; } </style> <div id="foo">Shadow</div> <div id="container"> <slot> <!-- span distributed here --> </slot> </div> <!-- /shadow-root --> <span>Light</span> </my-element> ``` becomes: ```html <style scope="my-element"> my-element { display: block; } #container.my-element > * { color: gray; } #foo.my-element { color: black; } </style> <my-element> <div id="foo">Shadow</div> <div id="container"> <span>Light</span> </div> </my-element> ``` ## About ApplyShim 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. ### Status: The `@apply` proposal has been abandoned in favor of the ::part/::theme [Shadow Parts spec](https://tabatkins.github.io/specs/css-shadow-parts/). Therefore, the ApplyShim library is deprecated and provided only for backwards compatibility. Support going forward will be limited to critical bug fixes. ### Known Issues: * 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 selectors can result in `background-color: transparent` 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 `transparent`, as an empty `background` definition replaces the `@apply` definition. For this reason, we recommend avoiding shorthand properties. ### Example: 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); } ``` ## About CustomStyleInterface CustomStyleInterface provides API to process `<style>` elements that are not inside of ShadowRoots, and simulate upper-boundary style scoping for ShadyDOM. To add document-level styles to ShadyCSS, one can call `CustomStyleInterface.addCustomStyle(styleElement)` or `CustomStyleInterface.addCustomStyle({getStyle: () => styleElement})` An example usage of the document-level styling api can be found in `examples/document-style-lib.js`, and another example that uses a custom element wrapper can be found in `examples/custom-style-element.js` ### Example: ```html <style class="document-style"> html { --content-color: brown; } </style> <my-element>This text will be brown!</my-element> <script> CustomStyleInterface.addCustomStyle(document.querySelector('style.document-style')); </script> ``` Another example with a wrapper `<custom-style>` element ```html <custom-style> <style> html { --content-color: brown; } </style> </custom-style> <script> class CustomStyle extends HTMLElement { constructor() { CustomStyleInterface.addCustomStyle(this); } getStyle() { return this.querySelector('style'); } } </script> <my-element>This this text will be brown!</my-element> ``` Another example with a function that produces style elements ```html <my-element>This this text will be brown!</my-element> <script> CustomStyleInterface.addCustomStyle({ getStyle() { const s = document.createElement('style'); s.textContent = 'html{ --content-color: brown }'; return s; } }); </script> ``` ## Usage To use ShadyCSS: 1. First, call `ShadyCSS.prepareTemplate(template, name)` on a `<template>` 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 <template id="myElementTemplate"> <style> :host { display: block; padding: 8px; } #content { background-color: var(--content-color); } .slot-container ::slotted(*) { border: 1px solid steelblue; margin: 4px; } </style> <div id="content">Content</div> <div class="slot-container"> <slot></slot> </div> </template> <script> // Use polyfill only in browsers that lack native Shadow DOM. window.ShadyCSS && ShadyCSS.prepareTemplate(myElementTemplate, 'my-element'); class MyElement extends HTMLElement { connectedCallback() { window.ShadyCSS && ShadyCSS.styleElement(this); if (!this.shadowRoot) { this.attachShadow({mode: 'open'}); this.shadowRoot.appendChild( document.importNode(myElementTemplate.content, true)); } } } customElements.define('my-element', MyElement); </script> ``` ## Type Extension elements ShadyCSS can also be used with type extension elements by supplying the base element name to `prepareTemplate` as a third argument. ### Example ```html <template id="myElementTemplate"> <style> :host { display: block; padding: 8px; } #content { background-color: var(--content-color); } .slot-container ::slotted(*) { border: 1px solid steelblue; margin: 4px; } </style> <div id="content">Content</div> <div class="slot-container"> <slot></slot> </div> </template> <script> windo