@enhance/enhance-style-transform

v0.1.2

Published

a year ago

Scope Web Component styles for SSR

Downloads

391

0High
0Medium
0Low

Enhance style scoping transform

This transform enables scoping styles in Enhance components with or without the need for shadowDOM.

It does not add new syntax. It sets firm upper bound so component styles can't bleed outside the component. It also allows some Web Component CSS selectors (::part, ::slotted, and :host) to target enhance components both before and after JavaScript hydrates the components. For server side rendering these selectors are converted to CSS that does not require the shadowDOM.

Goal

The shadowDOM gives full encapsulation of styles, but breaks other things like forms. When building with components what we want is some reasonable tools to help scope styles to those components. More like caution tape than chain-link fence. If the shadowDOM is used styles can be written once that will work before and after the shadowDOM initializes.

limitations

This approach doesn't completely avoid deep selection of nested elements. It makes tradeoffs to improve scoping without creating other problems. Transformed shadow selectors can also select some unintended elements if they are written to too broadly (i.e. ::slotted(*) will select all children). If you prefer a bullet proof style encapsulation and are willing to accept the downsides (broken forms, FOUC, etc.) use the shadowDOM.

Other Recommendations

Use with utility classes. This transform works well with utility class styles. We recommend writing most styles as utility classes directly on the elements in your template. This only leaves styles that cannot be written as utility classes which can be added to the component.
Use specific selectors to avoid deep selecting. It is better to use the > child selector rather than the general descendent selector when possible(i.e. :host > div ).
With slotted and part be specific enough to avoid over selection

Basic Usage

Below is an example a style transform when deploying to https://arc.codes.

Input

//Renderer handler.mjs
import enhance from '@enhance/ssr'
import styleTransform from '@enhance/enhance-style-transform'

const html = enhance({
  styleTransforms: [styleTransform]
})

const myDoc = html`<my-tag>Something</my-tag>`

//<my-tag> component definition
export default function MyTag({html}){
  return html`
    <style>
      h1 {
        background: red;
      }
    </style>

    <h1>
      <slot></slot>
    </h1>
  `
}

Output

<!-- Rendered Output-->
<head>
  <style>
    /* scoped version of styles from <my-tag> */
    my-tag h1 {
      background: red;
    }
  </style>
</head>
<body>
  <template>
    <style>
    /* unscoped version of styles from <my-tag> */
      h1 {
        background: red;
      }
    </style>

    <h1>
      <slot></slot>
    </h1>
  </template>
  <my-tag>
    <h1>Something</h1>
  </my-tag>
</body>

SSR transformations

The transformations below are used for the server rendered styles. These styles will be collected and placed in the document head. The 'template' context styles do not receive any transformation.

Component scoping

Basic component scoping is done by adding a component selector to every rule. This effectively sets the upper bound to all rules so styles cannot leak outside the component. The rule div {background: red} becomes my-tag div {background: red}. This sets a firm upper bound on styles but it does not limit deep selecting for anything nested inside the component. This is sometimes useful and sometimes a problem. To limit deep selection you can use more specificity in your selector choice. Combining this technique with utility classes also helps limit deep selection by minimizing the number of rules that need to be written for each component.

`:host` `:host()` `:host-context()`

When writing components it is often necessary to add styles to the element itself. The :host selector and its variations solve this problem, but they do not work when there is no shadowDOM. For the SSR context these styles are converted so that they work for both. :host itself is a selector stand in for the element. The function form of :host() is required to specify a class or attribute on the host itself. In order to select the context outside of host you can use the :host-context() form.

/* Scoping without host */
div { color: red; }
/* Becomes */
my-tag div { color: red; }

/* Scoping with host selector */
:host { color: red; }
/* Becomes */
my-tag { color: red; }

:host(.some-class) div { color: red; }
/* Becomes */
my-tag.some-class div { color: red; }

:host-context(footer > h1) div { color: red; }
/* Becomes */
footer > h1 my-tag div { color: red; }

`::slotted()`

With shadowDOM <slot>'s child elements in the light DOM are rendered inside the shadowDOM. The ::slotted() pseudo selector is used inside the shadowDOM to style these elements. Any selector argument will be applied to any matching elements that are slotted. The transform takes rules like div::slotted([slot=here]) { color:red; } and returns div[slot=here] { color: red; }. This allows for styles to be written that work both with and without the shadowDOM. It also lets you write styles so the intent is clear. Use caution picking the selector argument so that it does not select more than intended after transformation. ::slotted(*) for instance would select all elements. ::slotted([slot]) is useful for selecting all named slot contents.

`::part()`

The shadow parts API allows selected elements to be exposed for styling outside the shadowDOM. By labeling an element inside the component with a part=something attribute it can be selected outside that component with a the-tag::part(something) {color: red;} selector. For server rendering this is transformed into the-tag [part*=something] { color: red; }. Notice again that this does not stop deep selection. This selector will match any part of the same name nested within.

`scope=global`

Global unscoped styles can be added to components if desired. If a scope=global attribute is added to a style tag the styles will be collected and added to the head tag as with other styles. But no transforms or scoping will be done. These styles are removed from the template tag so that they will not appear inside shadowDOM.

<style scope=global>
  /* this rule will be put in the head and */
  /* will select all div's in the document */
  div { color:red; }
</style>

A style tag that is nested inside a component but is not a direct child will not be transformed or collected at all by the transform.

export default Component({html}){
  return html`
    <div>Hello World</div>
    <script>
      //this script will be transformed and moved 
    </script>
    <div>
      <script>
        //this script is left alone
      </script>
    </div>
  `
}

Style context

Enhance renders pages by expanding each component instance in the document with their template contents. The templates are also placed into the page for use in the shadowDOM. The styles are transformed for each of these context. The styles transformed for the server rendered output are collected and put in the document head. Any duplicated style tags are removed. The template context styles are left with the template tags for use with the shadowDOM.

API

Style Transforms are passed as an array. Transforms are called with a single object argument with the following properties:

raw: a string with the contents of the script tag
attrs: with any attributes on the script tag
context: a value of 'markup' for SSR global CSS, and 'template' for shadowDOM CSS
tagName: the custom element tagName

The return value from the transform should be the new string contents of the style tag for the given context.

More Examples

//global block
  <style scope="global"> 
    div {
       background:blue;
     }
  </style>
// component block
  <style scope="component">
    :host {
      display: block;
    }
    .container > ::slotted(*) {
      display: block;
    }
    .container > ::slotted(*[slot="title"]) {
      display: block;
    }
    .foo {
      display: block;
    }
    another-tag::part(title){
      display:block;
    }
  </style>

// instance block
  <style scope="instance">
    :host {
      display: block;
    }
    .container > ::slotted(*) {
      display: block;
    }
    .container > ::slotted(*[slot="title"]) {
      display: block;
    }
    .foo {
      display: block;
    }
    another-tag::part(title){
      display:block;
    }
  </style>
  <div class="foo">Shadow</div>
  <div class="container">
    <slot> </slot>
    <slot name="title"></slot>
  </div>

Used like this

<my-element>
  <span>Light</span>
  <span slot="title">Title</span>
  <another-tag><div part="title"></div></another-tag>
</my-element>

Becomes this

<my-element class="xyz123">

<style scope="global">
    div {
      background:blue;
      }
</style>
<style scope="my-element">
  my-element {
    display: block;
  }
  my-element .container > * {
      display: block;
  }
  my-element .container > *[slot="title"] {
      display: block;
  }
  my-element .foo {
      display: block;
  }
  my-element another-tag [part*="title"][part*="another-tag"]{
    display:block;
  }
</style>
<style scope="my-element.xyz123">
  my-element.xyz123 {
    display: block;
  }
  my-element.xyz123 .container > * {
      display: block;
  }
  my-element.xyz123 .container > *[slot="title"] {
      display: block;
  }
  my-element.xyz123 .foo {
      display: block;
  }
  my-element.xyz123 another-tag [part*="title"][part*="another-tag"]{
    display:block;
  }
</style>

  <div class="foo">Shadow</div>
  <div class="container">
    <span>Light</span>
    <span slot="title">Title</span>
  </div>
  <another-tag><div part="title another-tag"></div></another-tag>
</my-element>

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme