https://github.com/tomalec/translate-shadowdom
Set of utilities to translate both ways between Shadow DOM V0 and V1
https://github.com/tomalec/translate-shadowdom
shadow-dom
Last synced: 3 months ago
JSON representation
Set of utilities to translate both ways between Shadow DOM V0 and V1
- Host: GitHub
- URL: https://github.com/tomalec/translate-shadowdom
- Owner: tomalec
- License: mit
- Created: 2017-02-16T21:14:38.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2017-04-04T21:58:34.000Z (over 8 years ago)
- Last Synced: 2025-07-21T09:56:20.139Z (3 months ago)
- Topics: shadow-dom
- Language: HTML
- Homepage: https://tomalec.github.io/Translate-ShadowDOM/
- Size: 4.62 MB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Translate-ShadowDOM [](https://travis-ci.org/tomalec/Translate-ShadowDOM)
Set of utilities to translate between Shadow DOM v0 and v1 (both ways).
Usefull, when writing "hybrid" Web Components which are V1 ready, but run in V0 environment/polyfill;
or when running legacy code in V1 environment.
### [Live Demo](https://tomalec.github.io/Translate-ShadowDOM/)
[](https://tomalec.github.io/Translate-ShadowDOM/)
### Small sample
If you have Shadow DOM prepared for V1
```html
I want to be distributed as in V1
::slotted(p){
color: green;
}
Shadow DOM prepared for V1
```
You can now use it in your current app/element running on V0 environment (like current [webcomponentsjs polyfill](https://github.com/webcomponents/webcomponentsjs))
```javascript
let sRoot = myElement.createShadowRoot();
sRoot.innerHTML = TranslateShadowDOM.v1tov0.html(compositionString);
// or if you already have it parsed as document fragment
TranslateShadowDOM.v1tov0.fragment(documentfragment, true);
```
To get
```html
::content>p{
color: green;
}
Shadow DOM prepared for V1
```
So, it would get rendered as you would expect in V1:
```html
Shadow DOM prepared for V1
I want to be distributed as in V1
```
## Related custom elements
- [``](https://github.com/Juicy/juicy-composition) - applies Document Fragment to Shadow DOM
## Features
- Translates strings,
- Modifies `DocumentFragment`s,
- Preserves attributes,
- Translates HTML, CSS and basic JS
- works both ways between V0 and V1
## Install
Install the component using [Bower](http://bower.io/):
```sh
$ bower install translate-shadowdom --save
```
[npm](https://www.npmjs.com/)
```sh
$ npm install translate-shadowdom --save
```
Or [download as ZIP](https://github.com/Starcounter/translate-shadowdom/archive/master.zip).
## API
### V1 to V0
#### TranslateShadowDOM.v1tov0.html(_String_ `compositionString`) : _String_
Translates the HTML given in string, replacing all `smth` with `smth`
#### TranslateShadowDOM.v1tov0.slot(_HTMLElement_ `slot`) : _ContentElement_
Replaces given `SlotElement` (or `UnknownElement` ``) with `ContentElement` (``).
#### TranslateShadowDOM.v1tov0.fragment(_HTMLElement | DocumentFragment_ `root`, _Boolean_ `withStyle`, _Boolean_ `withScript`) : _HTMLElement | DocumentFragment_
Replaces all `SlotElement`s (or `UnknownElement`s ``) with `ContentElement`s (``) in given `root`.
If `withStyle` is set to true, will also translate CSS selectors in enclosed `` elements.
If `withScript` is set to true, will also translate JS code in enclosed `<script>` elements.
#### TranslateShadowDOM.v1tov0.css(_String_ `styleString`) : _String_
Replaces `::slotted(.foo)` with `::content .foo` in given string.
### V0 to V1
#### TranslateShadowDOM.v0tov1.html(_String_ `compositionString`) : _String_
Translates the HTML given in string, replacing all `<content select="[slot='foo']">smth</content>` with `<slot name="foo">smth</slot>`
#### TranslateShadowDOM.v0tov1.content(_HTMLElement_ `content`) : _SlotElement_
Replaces given `ContentElement` (or `UnknownElement` `<content>`) with `SlotElement` (`<slot>`).
It preserves all attributes **except** `name`.
If selector cannot be directly translated to slot name, default slot would be created.
#### TranslateShadowDOM.v0tov1.fragment(_HTMLElement | DocumentFragment_ `root`, _Boolean_ `withStyle`, _Boolean_ `withScript`) : _HTMLElement | DocumentFragment_
Replaces all `ContentElement`s (or `UnknownElement`s `<content>`) with `SlotElement`s (`<slot>`) in given `root`.
It preserves all attributes **except** `name`.
If selector cannot be directly translated to slot name, default slot would be created.
If `withStyle` is set to true, will also translate CSS selectors in enclosed `<style>` elements.
If `withScript` is set to true, will also translate JS code in enclosed `<script>` elements.
#### TranslateShadowDOM.v0tov1.css(_String_ `styleString`) : _String_
Replaces `::content .foo` with `::slotted(.foo)` in given string.
Adds warnings in code comments if a selector cannot be translated in 100% compatible way,
for example `#i1::content .foo+.bar` will be translated to
`#i1::slotted(.foo)/* FIXME V1 matches only direct children; V1 supports only compound selectors, selector skipped:+.bar;*/`
## Test suite
- local browser `./test/index.html`
- [online](http://tomalec.github.io/translate-shadowdom/test)
## Contributing
1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -m 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Open corresponding issue if needed
6. Submit a pull request :D
## History
For detailed changelog, check [Releases](https://github.com/tomalec/translate-shadowdom/releases).
## License
MIT