https://github.com/knownasilya/ember-shadow-dom

Write templates for your components inside of a Shadow DOM root.
https://github.com/knownasilya/ember-shadow-dom

ember ember-addon emberjs shadow-dom shadow-root

Last synced: 2 months ago
JSON representation

Write templates for your components inside of a Shadow DOM root.

• Host: GitHub
• URL: https://github.com/knownasilya/ember-shadow-dom
• Owner: knownasilya
• License: mit
• Created: 2018-10-22T14:32:10.000Z (over 5 years ago)
• Default Branch: main
• Last Pushed: 2023-07-18T23:51:52.000Z (12 months ago)
• Last Synced: 2024-05-01T21:33:17.293Z (2 months ago)
• Topics: ember, ember-addon, emberjs, shadow-dom, shadow-root
• Language: JavaScript
• Size: 2.65 MB
• Stars: 28
• Watchers: 3
• Forks: 1
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.md

Lists

• awesome-ember - shadow-dom - Write templates for your components inside of a Shadow DOM root. (Packages / Web Components)

README

        
# ember-shadow-dom

Write templates for your components inside of a Shadow DOM root.

Allows encapsulating styles (CSS) and markup (HTML) but using templates like

you're used to.

🛠 Support for SSR/FastBoot in Chrome 90+, [Release notes](https://developer.chrome.com/blog/new-in-chrome-90/#declarative).

🤔 Not sure what Shadow DOM is? Check out this [MDN article](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).

> Compatibility: Most browsers support Shadow DOM (v1), except for IE11, see [CanIUse](https://caniuse.com/#feat=shadowdomv1) for details

[![npm version][npm-badge]][npm-badge-url]

## Compatibility

- Ember.js v3.16 or above

- Ember CLI v2.13 or above

- Node.js v12 or above

If using Ember < 3.20, this addon will use the private version of `{{in-element}}` via a polyfill.

## Installation

```sh

ember install ember-shadow-dom

```

## Usage

This addon provides a component called `ShadowRoot`.

```hbs

  

    .internal { color: red; }

  

  Internal

```

This makes the encapsulating component's children a shadow root.

### Slots

In Shadow DOM you can generally use ``, but with Ember you can just use `{{yield}}`.

```hbs

{{! components/test.hbs }}

  

    .internal { color: red; }

  

  

    {{yield}}

  

```

And you can call the component:

```hbs

  Hello World!

```

And the contents `Hello World!` will be inside the shadow root. If you need multiple

"slots", you can use [ember-named-blocks-polyfill](https://github.com/ember-polyfills/ember-named-blocks-polyfill).

```hbs

{{! components/card.hbs }}

  

    .title { color: red; } .body { margin-top: 1rem; }

  

  

    {{yield to='title'}}

  

  


    {{yield to='body'}}

  


```

And use the component like so:

```hbs

  <:title>

    My title

  

  <:body>

    Some content here!

  

```

## API

### `` Component

#### Arguments

- `@mode` (string) - The mode of the Shadow Root, defaults to `'open'`. Can be `'open'` or `'closed'`.

  Note that `'closed'` mode prevents you from querying into the DOM of your components in tests.

- `@tagName` (string) - This defaults to `'div'`, but can be any valid element tag name used in HTML.

  Setting this argument changes the top level element that the shadow root is attached to.

## FastBoot/SSR

This addon supports ShadowDom in SSR (meaning your styles will remain the same on initial render and not change when rehydrated) in Chrome 90+

Other browser vendors should follow, but there is some risk that it never happens.

Details here: https://www.chromestatus.com/feature/5191745052606464

## Testing

Components with a open shadowroot can be tested using qunit-dom like so:

```js

let root = find('#internal').shadowRoot;

assert.dom('.block', root).hasText('template block text');

```

Where the template looks like:

```hbs

  
template block text


```

> Note: check out https://github.com/salesforce/kagekiri for piercing the shadow for querying elements

## Contributing

See the [Contributing](CONTRIBUTING.md) guide for details.

## Attribution

Thanks to [@rwjblue](https://github.com/rwjblue) for realizing that `{{in-element}}` can be used for the shadow root!

## License

This project is licensed under the [MIT License](LICENSE.md).

[npm-badge]: https://badge.fury.io/js/ember-shadow-dom.svg

[npm-badge-url]: http://badge.fury.io/js/ember-shadow-dom