wc-reactor
v0.1.3
Published
Node module to create a React wrapper from web components
Downloads
10
Readme
wc-reactor
Node module to create React components wrappers for web components. The module is a part of Advanced REST Client ecosystem.
What does it do?
It generates a React wrapper for web components so it can be used in React application. It creates exactly the same interface as web components uses. It handles all custom events, property change events and data binding (in a React way).
Installation
$ npm i --save-dev wc-reactorExample
const reactor = require('wc-reactor');
reactor({
// Polymer web component import file or Polymer bundle.
webComponent: 'component-or-bundle.html',
// Default destination where to put files.
dest: './build/',
// print a lot of stuff unto the console
verbose: true,
// Creates separate component definition for each module
bundle: false
});
.then(() => console.log('Build complete <3'));The result of generating React components is located in ./build directory.
It's structure is:
| build/
| - ComponentName/
| - ComponentName.js
| - index.js
... (each components separately)
| - WebComponentsImports.jsThe definition is in ComponentName/ComponentName.js file. index.js is a
shorthand for importing the module.
The WebComponentsImports.js contains 2 helper functions. polyfillScript function
contains HTML code that should be put in web page's head section. It imports
polyfills in a browser that doesn't support web components. componentsImport function
contains a declaration of the <link> tag that points to web component import file.
Examples
import { polyfillScript, componentsImport } from './WebComponentsImports';
var doc = `<html>
<head>
...
${polyfillScript('/base-path')}
${componentsImport('/base-path', 'import-file-name.html')}
</head>
<body></body>
</html>`This would produce a document like the following:
<html>
<head>
...
<script>// bit of a minified code</script>
<link rel="import" href="/base-path/import-file-name.html">
</head>
<body></body>
</html>Names mapping in React component
React wrapper contains interface to manipulate web component's properties, handle custom events (including properties change events) and to call public API functions.
Properties mapping
Web components property names are the same as React's props. So you can use
generated component like this:
render() {
return (
<PaperCombobox label="My label" value={this.props.value}/>
);
}When the PaperCombobox component is mounted then the label and value properties
are propagated to the underlying web component. The same is happening each time
when React's state change:
/**
* Updates list of suggestion in the PaperCombobox web component
*/
updateSuggestions() {
this.setState({
source: ['One', 'Two', 'Three']
});
}
render() {
return (
<PaperCombobox label="My label" source={this.state.source}/>
);
}Updating the sate value will update corresponding web component's property.
Polymer's data binding
Polymer powered web components uses Polymer's data binding for properties. This
can be easily done in react by using on + propertyName + Changed function set to a property.
Assuming that the PaperCombobox web component has value property that notify value change (sends non-bubbling custom event when value changes).
You can handle it in React application using functions:
_onValueChanged(newValue, e) {
e.preventDefault();
console.log(newValue);
}
render() {
return (
<PaperCombobox label="My label" source={this.state.source} onValueChanged={this._onValueChanged}/>
);
}New value and original event is always passed to data binding change function calls. You can use event to access additional data like information about the target or path. Note, that target may not be the web component but an element inside it.
Note: Only public properties are handled by the wrapper. It doesn't work with protected properties (property name starts with _).
Methods mapping
Methods are mapped 1:1 from the web component. Only public methods are available to wrapper. Web component's lifecycle methods are also unavailable.
Let's assume that the PaperCombobox element has a selectNext method in it's public API:
selectNextDropdownItem() {
this._refElement.selectNext();
}
render() {
return (
<PaperCombobox ref={(element) => {this._refElement = element;}}/>
);
}Events mapping
Custom events names are translated to camel case function call as:
on + UppercaseCamelCaseEventName.
Custom event's detail object and the event itself is passed as an argument to the function call.
Assuming that the paper-combobox web components dispatches next-selected event. It can be handled by
setting onNextSelected property on the components that is a handler for event.
_comboNextSelected(detail, e) {
console.log(e.target, e.path);
console.log('Next element selected', detail);
// detail === e.detail
}
render() {
return (
<PaperCombobox onNextSelected={this._comboNextSelected}/>
);
}The script above handles the next-selected event and passes the detail of the event
to the function.
More examples
Checkout our example build usage project to see how to use generated module in React application: https://github.com/advanced-rest-client/arc-components-builder-example
API
All options are defined in lib/options.js.
webComponent {String}
A path to a Polymer powered web component to analyze and build the React wrapper for.
It can be a single web component declaration or a bundle file of Polymer web components.
reactComponents {Array<String>}
List of web components names to be exposed to generated React component so it can be included in React application.
Defining this option is optional. By default all components found in the webComponent file are processed and wrapped into React component.
To reduce size of generated code it is a good idea to declare number of components that your application is using. If the webComponent file is a bundle of web components you can reduce generated file by setting this property.
Provide list of components names only, without any repository path or version information.
For example ['raml-request-panel', 'paper-input']
dest {String}
The destination where the build files are put. Absolute or relative path.
By default it puts the files into build directory of the working dir.
bundle {Boolean}
By default it creates a separate file for each web component found in webComponent file. When this option is set then it bundles all React components into a single file and exports each React component.
bundleName {String}
File name of generated component. It defaults to WebComponents.js. This is only relevant if bundle is set. Otherwise each file name is a web component name.
logger {Object}
Instance of any logger library that has log(), info(), warn() and error() functions.
If not provided a console's output will be used.
verbose {Boolean}
If set then it prints verbose messages.
Double events problem
Sometimes Polymer web components sends an event that has the same name as data binding event. In this case you will notice two handler function calls with different set of arguments.
Polymer powered web component can contain a property declaration with notify
set to true. It is used by the data binding system to update property value on a
parent element / application. Those change events does not bubble. They can be only
handled when setting an event listener on the element. That's is why sometimes
authors prefer to send additional event with the same name that bubbles through
the DOM. Consider the following example:
// Polymer element (v1)
Poymer({
is: 'paper-combobox',
properties: {
value: {
type: String,
notify: true,
observer: '_valueChanged'
}
},
_valueChanged: function(value) {
this.fire('value-changed', {
value: value
});
}
});This components sends two value-changed events when the value property have changed.
Because of the name collision the React wrapper automatically calls onValueChanged
prop function as a data binding automated function and then it also listens for
the value-changed event and calls the same onValueChanged function.
Automated change handler functions have a value of changed property as the first argument. Regulars event handlers have event's detail object as a first argument. Therefore you may end up handling the same event twice but with different argument.
Contributing
- Fork it
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request <3
Supported Node.js Versions
arc-components-builder officially supports the latest current & active LTS versions of Node.js. It may be working with previous versions but it is not intentional.