` elements, observe properties changes and delegate events. It can also resolve `Promise`s and pipe `Observable`s directly in the template.
-
-## Browsers support
-
-Tests are run against all ever green browsers, Internet Explorer and old Safari versions. DNA itself does not require any polyfill and it is distribute as ES6 module (with untranspiled classes and `async`/`await` statements), but some Babel helpers if you want to use decorators need support for `Symbol`, `Object.assign` and `Array.prototype.find`. Also, a polyfill for `Promise`s is required in IE11 if you are using async methods.
-
-
-
-## Ok, I'm in!
-
-Read the [Get started](./get-started) page or try out DNA in the [sandbox](https://stackblitz.com/edit/dna-sandbox?embed=1&file=HelloWorld.ts&hideExplorer=1&hideNavigation=1)!
diff --git a/docs/_Footer.md b/docs/_Footer.md
deleted file mode 100644
index 46fec3e5..00000000
--- a/docs/_Footer.md
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-[](https://www.chialab.it)
-
-[Chialab]((https://www.chialab.it)) is a design company.
-By developing strategy, design, software and content, we generate exciting relationships between brands and people.
-
-
diff --git a/docs/_Header.md b/docs/_Header.md
deleted file mode 100644
index 372988ba..00000000
--- a/docs/_Header.md
+++ /dev/null
@@ -1,13 +0,0 @@
-
-
-
-
-
-
-
-
- DNA • Progressive Web Components
-
\ No newline at end of file
diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
deleted file mode 100644
index 60fc4757..00000000
--- a/docs/_Sidebar.md
+++ /dev/null
@@ -1,47 +0,0 @@
-* [Introduction](./home)
-* [Get started](./get-started)
- * [Install](./get-started#get-started)
- * [Define a component](./get-started#define-a-component)
- * [Extending native elements](./get-started#extending-native-elements)
- * [Render a component](./get-started#render-a-component)
-* [Templates](./templates)
- * [Render](./templates#templates)
- * [JSX](./templates#jsx)
- * [Expressions](./templates#expressions)
- * [Functional components](./templates#functional-components)
- * [Nodes and references](./templates#nodes-and-references)
- * [Slotted children](./templates#slotted-children)
- * [Keyed elements](./templates#keyed-elements)
-* [Reactive properties](./properties)
- * [Declare a property](./properties#declare-a-property)
- * [Declare a state](./properties#declare-a-state)
- * [Configuration](./properties#configuration)
- * [Accessors](./properties#accessors)
- * [Observers](./properties#observers)
- * [Attributes](./properties#attributes)
-* [Events](./events)
- * [Declarative listeners](./events#declarative-listeners)
- * [Template listeners](./events#template-listeners)
- * [Delegation](./events#delegation)
- * [Dispatching events](./events#dispatching-events)
- * [Async dispatch](./events#async-dispatch)
-* [Life cycle](./life-cycle)
- * [connectedCallback](./life-cycle#connectedcallback)
- * [disconnectedCallback](./life-cycle#disconnectedcallback)
- * [attributeChangedCallback](./life-cycle#attributechangedcallback)
- * [propertyChangedCallback](./life-cycle#propertychangedcallback)
- * [stateChangedCallback](./life-cycle#statechangedcallback)
-* [Styling](./styling)
- * [Scoped styles](./styling#scoped-styles)
- * [Native CSS modules](./styling#native-css-modules)
- * [Other techniques](./styling#other-styling-techniques)
-* [Integrations](./integrations)
- * [Frameworks](./integrations#frameworks)
- * [View libraries](./integrations#view-libraries)
- * [Manipulating the DOM](./integrations#manipulating-the-dom)
-* [Use in Node.js](./use-in-node)
-* [Helpers](./helpers)
-* [Tools](./tools)
-* [Migrations](./migrations)
- * [v3 -> v4](./migrations#from-v3-to-v4)
- * [v2 -> v3](./migrations#from-v2-to-v3)
diff --git a/docs/get-started.md b/docs/get-started.md
deleted file mode 100644
index ee72c86e..00000000
--- a/docs/get-started.md
+++ /dev/null
@@ -1,244 +0,0 @@
-# Get started
-
-The recommended way to use DNA is to setup a project with Babel or TypeScript which has a lot of life saver features like modules, decorators and typechecking, but it also works untranspiled in the browser.
-
-### Use a CDN
-
-You can use DNA via CDN thanks to the [Unpkg](https://unpkg.com/):
-
-```ts
-import { Component, customElements } from 'https://unpkg.com/@chialab/dna?module';
-```
-
-### Setup a bundler
-
-The DNA environment is pretty common (if you are familiar with other libraries like React, Angular, LitElement etc.):
-
-1. Make sure you have a recent [Node.js](https://nodejs.org/en/) version installed
-2. Setup a bundler ([Rollup](https://rollupjs.org) is recommended, but [Webpack](https://webpack.js.org/) and [Parcel](https://parceljs.org/) are equally good choices)
-3. Setup Babel ([Rollup](https://github.com/rollup/rollup-plugin-babel), [Webpack](https://github.com/babel/babel-loader), [Parcel](https://parceljs.org/transforms.html#babel)) or TypeScript ([Rollup](https://github.com/rollup/rollup-plugin-typescript), [Webpack](https://webpack.js.org/guides/typescript/), [Parcel](https://parceljs.org/transforms.html#typescript)):
- * if your choice is Babel, please make sure all this plugins are loaded in order to use all DNA features:
- ```sh
- $ npm i -D \
- @babel/plugin-proposal-decorators \
- @babel/plugin-proposal-class-properties
- ```
-
- **.babelrc**
-
- ```json
- {
- "plugins": [
- "@babel/plugin-proposal-decorators",
- "@babel/plugin-proposal-class-properties"
- ]
- }
- ```
-
- If you want to use React JSX instead of template strings, you will also need to install the [`@babel/plugin-transform-react-jsx`](https://www.npmjs.com/package/@babel/plugin-transform-react-jsx):
-
- **Classic**
-
- ```json
- {
- "plugins": [
- ["@babel/plugin-transform-react-jsx", {
- "pragma": "h"
- }]
- ]
- }
- ```
-
- **Automatic**
-
- ```json
- {
- "plugins": [
- ["@babel/plugin-transform-react-jsx", {
- "runtime": "automatic",
- "importSource": "@chialab/dna"
- }]
- ]
- }
- ```
-
- Since the DNA `html` method is provided by the [`htm`](https://github.com/developit/htm) module by [Jason Miller](https://github.com/developit), you can also use the [`babel-plugin-htm`](https://www.npmjs.com/package/babel-plugin-htm) to preprocess templates.
-
- ```json
- {
- "plugins": [
- ["babel-plugin-htm", {
- "pragma": "h",
- "import": {
- "module": "@chialab/dna"
- }
- }]
- ]
- }
- ```
-4. Install DNA
- ```sh
- $ npm i @chialab/dna
- ```
-
-## Define a component
-
-DNA components are classes which extends the base HTMLElement with helpers for [templating](./templates), [styling](./styles), [events delegation](./events) and [life cycle](./life-cycle).
-
-Defining a component means to link a HTML tag with the element's constructor, as described by the Custom Elements specification.
-In this example we are going to use the `customElement` decorator method to register the component in the DNA registry:
-
-```ts
-import { Component, customElement, property } from '@chialab/dna';
-
-@customElement('hello-world')
-class HelloWorld extends Component {
- @property() name: string = '';
-
- // define a template
- render() {
- return Hello {this.name || 'world'}! ;
- }
-}
-```
-
-
-JavaScript
-
-
-You can use the class decorator if you are using TypeScript or this Babel plugin, otherwise you have to fallback directly using `customElements.define`:
-
-```ts
-import { Component, customElements, html } from '@chialab/dna';
-
-class HelloWorld extends Component {
- static get properties() {
- return {
- name: {
- type: String,
- defaultValue: '',
- },
- };
- }
-
- // define a template
- render() {
- return html`
Hello ${this.name || 'world'}! `;
- }
-}
-
-customElements.define('hello-world', HelloWorld);
-```
-
-
-
-
-### Extending native elements
-
-Custom Element specification allows to define an element using the `is` attribute instead of the tag.
-This is very useful when you want to extend a HTML tag, preserving its semanthic meaning. For example:
-
-```tsx
-import { Component, customElement, property } from '@chialab/dna';
-
-@customElement('blog-post', {
- extends: 'article'
-})
-class BlogPost extends Component {
- @property() title: string = '';
-
- render() {
- return {this.title} ;
- }
-}
-```
-
-
-JavaScript
-
-
-```ts
-import { Component, customElements, html } from '@chialab/dna';
-
-class BlogPost extends Component {
- static get properties() {
- return {
- title: {
- type: String,
- defaultValue: '',
- },
- };
- }
-
- render() {
- return html`
${this.title} `;
- }
-}
-
-customElements.define('blog-post', BlogPost, {
- extends: 'article'
-});
-```
-
-
-
-
-In the example above, a new instance of `BlogPost` inherits all class methods and properties, but its `tagName` will be `ARTICLE`.
-
-> **Note**
-> Extending builtin elements also preserves accessibility and usability features: extending the `BUTTON` element will make the component reachable and clickable via keyboard navigation without setting `role` and `tabindex`.
-
-## Render a component
-
-The `render` helper is used by DNA components to generate their templates, but it can be used to add a component or a template in a specific point of the DOM tree, for example to instantiate the root component of your application:
-
-```ts
-import { Component, customElement, render } from '@chialab/dna';
-
-@customElement('x-card')
-class Card extends Component {
- ...
-}
-
-render(
-
Title
-, document.body);
-```
diff --git a/docs/events.md b/docs/guide/events.md
similarity index 72%
rename from docs/events.md
rename to docs/guide/events.md
index b7861f0b..f43d743a 100644
--- a/docs/events.md
+++ b/docs/guide/events.md
@@ -5,15 +5,17 @@ DNA add some extra features like declarative event listeners and delegations.
## Declarative listeners
-You can declare event listeners on a component using the `listen` decorator:
+You can declare event listeners on a component using the `listen` decorator or the `listeners` static accessor:
-```ts
-import { window, extend, customElement, listen } from '@chialab/dna';
+::: code-group
+
+```ts [@listen]
+import { builtin, customElement, listen } from '@chialab/dna';
@customElement('x-button', {
extends: 'button',
})
-class Button extends extend(window.HTMLButtonElement) {
+class Button extends builtin.HTMLButtonElement {
@listen('click')
onClick(event) {
event.preventDefault();
@@ -26,32 +28,34 @@ class Button extends extend(window.HTMLButtonElement) {
}
```
-Or the `listeners` static accessor:
-
-```ts
-import { window, extend, customElements } from '@chialab/dna';
+```ts [get listeners]
+import { builtin, define } from '@chialab/dna';
-class Button extends extend(window.HTMLButtonElement) {
+class Button extends builtin.HTMLButtonElement {
static get listeners() {
return {
- 'click': function(event) {
+ 'click': function (event) {
event.preventDefault();
},
- 'input [name="age"]': function(event, target) {
+ 'input [name="age"]': function (event, target) {
console.log(target.value);
},
};
}
}
-customElements.define('x-button', Button, {
+define('x-button', Button, {
extends: 'button',
});
```
-Declarations can be configured with [event listener options]((https://developer.mozilla.org/it/docs/Web/API/Element/addEventListener)):
+:::
-```ts
+Declarations can be configured with [event listener options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener):
+
+::: code-group
+
+```ts [@listen]
import { Component, customElement, listen } from '@chialab/dna';
@customElement('x-tracker')
@@ -63,15 +67,11 @@ class Tracker extends Component {
}
```
-
-JavaScript
-
-
-```ts
-import { Component, customElements } from '@chialab/dna';
+```ts [get listeners]
+import { Component, define } from '@chialab/dna';
class Tracker extends Component {
- static get listeners(){
+ static get listeners() {
return {
touchmove: {
callback(event) {
@@ -83,17 +83,16 @@ class Tracker extends Component {
}
}
-customElements.define('x-tracker', Tracker);
+define('x-tracker', Tracker);
```
-
-
+:::
## Template listeners
Listeners can be added via a template attribute named as the event with the `on` prefix:
-```ts
+```tsx
import { Component, customElement } from '@chialab/dna';
@customElement('x-header', {
@@ -101,12 +100,14 @@ import { Component, customElement } from '@chialab/dna';
})
class Header extends Component {
render() {
- return <>
- {this.title}
-
- Close
-
- ;
+ return (
+ <>
+ {this.title}
+
+ Close
+
+
+ );
}
}
```
@@ -115,8 +116,10 @@ class Header extends Component {
Event listeners are automatically bound with the component. If you need a different target, such as the document or the window, you can pass the target to the declaration. In this case, event listeners are added once the element has been added to the DOM tree and removed once disconnected.
-```ts
-import { window, Component, customElement, listen } from '@chialab/dna';
+::: code-group
+
+```ts [@listen]
+import { Component, customElement, listen } from '@chialab/dna';
@customElement('x-tracker')
class Tracker extends Component {
@@ -127,15 +130,11 @@ class Tracker extends Component {
}
```
-
-JavaScript
-
-
-```ts
-import { window, Component, customElements } from '@chialab/dna';
+```ts [get listeners]
+import { Component, define } from '@chialab/dna';
class Tracker extends Component {
- static get listeners(){
+ static get listeners() {
return {
touchmove: {
callback(event) {
@@ -148,11 +147,10 @@ class Tracker extends Component {
}
}
-customElements.define('x-tracker', Tracker);
+define('x-tracker', Tracker);
```
-
-
+:::
## Delegation
@@ -160,13 +158,15 @@ DNA supports event delegation for both imperatively and declaratively declaratio
Using the `listen` decorator or the `listeners` static getter, you can specify the delegated child selector after the event name in the declaration key:
-```ts
-import { window, extend, customElement, listen } from '@chialab/dna';
+::: code-group
+
+```ts [@listen]
+import { builtin, customElement, listen } from '@chialab/dna';
@customElement('x-dialog', {
extends: 'dialog',
})
-class Dialog extends extend(window.HTMLDialogElement) {
+class Dialog extends builtin.HTMLDialogElement {
@listen('click', 'nav button', { passive: false })
onClick(event, target) {
// ...
@@ -174,14 +174,10 @@ class Dialog extends extend(window.HTMLDialogElement) {
}
```
-
-JavaScript
-
+```ts [get listeners]
+import { builtin, define } from '@chialab/dna';
-```ts
-import { window, extend, customElements } from '@chialab/dna';
-
-class Dialog extends extend(window.HTMLDialogElement) {
+class Dialog extends builtin.HTMLDialogElement {
static get listeners() {
return {
'click nav button': {
@@ -191,30 +187,29 @@ class Dialog extends extend(window.HTMLDialogElement) {
passive: false,
},
};
- };
+ }
}
-customElements.define('x-dialog', Dialog, {
+define('x-dialog', Dialog, {
extends: 'dialog',
-})
+});
```
-
-
+:::
You can also use `delegateEventListener` and `undelegateEventListener` methods:
```ts
-import { Component, customElement, DOM } from '@chialab/idom';
+import { builtin, customElement } from '@chialab/idom';
@customElement('x-dialog', {
extends: 'dialog',
})
-class Dialog extends Component { ... }
+class Dialog extends builtin.HTMLDialogElement { ... }
const element = new Dialog();
const closeDialog = (event, target) => { ... };
-DOM.appendChild(document.body, element);
+document.body.appendChild(element);
// delegate listener
element.delegateEventListener('click', 'nav button', closeDialog, { passive: false });
// undelegate listener
@@ -226,15 +221,15 @@ element.undelegateEventListener('click', 'nav button', closeDialog);
DNA components overrides the `dispatchEvent` method in order to support an alternative signature for easier [CustomEvents](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events) creation:
```ts
-import { Component, customElement, DOM } from '@chialab/dna';
+import { builtin, customElement } from '@chialab/dna';
@customElement('x-button', {
extends: 'button',
})
-class Button extends Component { ... }
+class Button extends builtin.HTMLButtonElement { ... }
const button = new Button();
-DOM.appendChild(document.body, element);
+document.body.appendChild(element);
// native dispatch
const event = new CustomEvent('sendEmail', {
detail: { from: '...', to: '...', body: '...' },
@@ -262,7 +257,7 @@ button.dispatchEvent('sendEmail',
With DNA, you can also dispatch events and await a `Promise` which resolves when all async listeners are completed. This is useful for events based communication with other components:
```ts
-import { Component, customElement, listen, DOM } from '@chialab/dna';
+import { Component, customElement, listen } from '@chialab/dna';
@customElement('x-paginator')
class Paginator extends Component {
diff --git a/docs/guide/index.md b/docs/guide/index.md
new file mode 100644
index 00000000..dabf681c
--- /dev/null
+++ b/docs/guide/index.md
@@ -0,0 +1,226 @@
+# Get started
+
+The recommended way to use DNA is to setup a project with Babel or TypeScript which has a lot of life saver features like modules, decorators and typechecking, but it also works untranspiled in the browser.
+
+## Install
+
+DNA is published to the NPM registry
+
+::: code-group
+
+```bash [npm]
+npm install @chialab/dna
+```
+
+```bash [yarn]
+yarn add @chialab/dna
+```
+
+```bash [pnpm]
+pnpm add @chialab/dna
+```
+
+:::
+
+### or use a CDN
+
+You can use DNA via CDN thanks to [unpkg](https://unpkg.com/):
+
+```ts
+import { Component, define } from 'https://unpkg.com/@chialab/dna?module';
+```
+
+## Configure JSX
+
+### Typescript
+
+::: code-group
+
+```json [tsconfig.json]
+{
+ "compilerOptions": {
+ "experimentalDecorators": true,
+ "jsx": "react-jsx",
+ "jsxImportSource": "@chialab/dna"
+ }
+}
+```
+
+:::
+
+### Babel
+
+::: code-group
+
+```json [babel.config.json]
+{
+ "plugins": [
+ [
+ "@babel/plugin-transform-react-jsx",
+ {
+ "pragma": "h",
+ "pragmaFrag": "Fragment"
+ }
+ ]
+ ]
+}
+```
+
+:::
+
+## Define a component
+
+DNA components are classes which extends the base `HTMLElement``.
+
+Defining a component means to link a HTML tag with the element's constructor, as described by the Custom Elements specification.
+In this example we are going to use the `customElement` decorator method to register the component in the DNA registry:
+
+::: code-group
+
+```tsx [TypeScript]
+import { Component, customElement, property } from '@chialab/dna';
+
+@customElement('hello-world')
+class HelloWorld extends Component {
+ @property() name: string = '';
+
+ render() {
+ return Hello {this.name || 'world'}! ;
+ }
+}
+```
+
+```ts [JavaScript]
+import { Component, define, html } from '@chialab/dna';
+
+class HelloWorld extends Component {
+ static get properties() {
+ return {
+ name: {
+ type: String,
+ defaultValue: '',
+ },
+ };
+ }
+
+ render() {
+ return html`Hello ${this.name || 'world'}! `;
+ }
+}
+
+define('hello-world', HelloWorld);
+```
+
+:::
+
+### Extending native elements
+
+Custom Element specification allows to define an element using the `is` attribute instead of the tag.
+This is very useful when you want to extend a HTML tag, preserving its semanthic meaning. For example:
+
+::: code-group
+
+```tsx [TypeScript]
+import { builtin, customElement, property } from '@chialab/dna';
+
+@customElement('alert-dialog', {
+ extends: 'dialog',
+})
+class AlertDialog extends builtin.HTMLDialogElement {
+ @property() title: string = '';
+
+ render() {
+ return {this.title} ;
+ }
+}
+```
+
+```ts [JavaScript]
+import { builtin, define, html } from '@chialab/dna';
+
+class AlertDialog extends builtin.HTMLDialogElement {
+ static get properties() {
+ return {
+ title: {
+ type: String,
+ defaultValue: '',
+ },
+ };
+ }
+
+ render() {
+ return html`${this.title} `;
+ }
+}
+
+define('alert-dialog', AlertDialog, {
+ extends: 'dialog',
+});
+```
+
+:::
+
+In the example above, a new instance of `AlertDialog` inherits all class methods and properties, but its `tagName` will be `DIALOG`.
+
+::: info
+
+Extending builtin elements also preserves accessibility and usability features: extending `HTMLButtonElement` will make the component reachable and clickable via keyboard navigation without setting `role` and `tabindex`.
+
+:::
+
+## Render a component
+
+The `render` helper is used by DNA components to generate their templates, but it can be used to add a component or a template in a specific point of the DOM tree, for example to instantiate the root component of your application:
+
+```tsx
+import { Component, customElement, render } from '@chialab/dna';
+
+@customElement('x-card')
+class Card extends Component {
+ ...
+}
+
+render(Hello world! `;
+ return Hello world! ;
}
}
```
-### JSX
-
-If you familiar with JSX, you can also use it since DNA templates are 100% compatible with JSX transpiled output:
-
-```ts
-import { Component, customElement, h } from '@chialab/dna';
+```ts [html]
+import { Component, customElement, html } from '@chialab/dna';
@customElement('hello-world')
class HelloWorld extends Component {
render() {
- return Hello world! ;
+ return html`Hello world! `;
}
}
```
-Please rember to configure the `@babel/plugin-transform-react-jsx` in roder to use the DNA's `h` and `Fragment` helpers:
-
-```json
-{
- "plugins": [
- ["@babel/plugin-transform-react-jsx", {
- "pragma": "h",
- "pragmaFrag": "Fragment",
- }]
- ]
-}
-```
+:::
## Expressions
When interpolating an expression, the following rules (based on the type of the result and context) are applied:
-| Type | Content | Attribute |
-| ---- | ---- | --------- |
-| `string` | Add/update as Text node | Add as value |
-| `number` | Add/update as Text node | Add as value |
-| `boolean` | / | Add/remove attribute, reference as property |
-| `null` | / | Remove attribute |
-| `undefined` | / | Remove attribute |
-| `Node` | Add/update node | `.toString()` as value, reference as property |
-| `array` | Add/update iterated content | `.toString()` as value, reference as property |
-| `object` | `.toString()` as Text node | `.toString()` as value, reference as property |
-| `function` | `.toString()` as Text node | `.toString()` as value, reference as property |
+| Type | Content | Attribute |
+| ----------- | --------------------------- | --------------------------------------------- |
+| `string` | Add/update as Text node | Add as value |
+| `number` | Add/update as Text node | Add as value |
+| `boolean` | / | Add/remove attribute, reference as property |
+| `null` | / | Remove attribute |
+| `undefined` | / | Remove attribute |
+| `Node` | Add/update node | `.toString()` as value, reference as property |
+| `array` | Add/update iterated content | `.toString()` as value, reference as property |
+| `object` | `.toString()` as Text node | `.toString()` as value, reference as property |
+| `function` | `.toString()` as Text node | `.toString()` as value, reference as property |
### Content expression
-```ts
-html`${this.firstName} ${this.lastName} `
-```
-
-
-JSX
-
+::: code-group
-```ts
-{this.firstName} {this.lastName}
+```tsx [jsx]
+
+ {this.firstName} {this.lastName}
+
```
-
-
-
-
-Raw
-
-
-```ts
-h('span', null, this.firstName, ' ', this.lastName)
+```ts [html]
+html`${this.firstName} ${this.lastName} `;
```
-
-
-
-### Attribute expression
-```ts
-html`
-JSX
-
+:::
-```ts
-
-
+::: code-group
-
-Raw
-
+```tsx [jsx]
+
-
+
+:::
### Loops
When using loops it is necessary to keep in mind the [expressions](#expressions): in order to correctly render a table or a list of data, we need to interpolate an array of templates:
-```ts
-html`
- ${this.items.map((item, index) => html`${index}. ${item} `)}
- `
-```
+::: code-group
-
-JSX
-
-
-```ts
+```tsx [jsx]
- {this.items.map((item, index) => {index}. {item} )}
+ {this.items.map((item, index) => (
+
+ {index}. {item}
+
+ ))}
```
-
-
-
-Raw
-
-
+```ts [html]
+html`
+ ${this.items.map((item, index) => html`${index}. ${item} `)}
+ `;
+```
-```ts
-h('ul', null, this.items.map((item, index) =>
- h('li', null, index, '. ', item)
-))
+```ts [vdom]
+h(
+ 'ul',
+ null,
+ this.items.map((item, index) => h('li', null, index, '. ', item))
+);
```
-
+
+:::
### Conditionals
You can create conditional expressions based on a boolean value using ternary operator or logical expression which results in a template or any other value:
-```ts
-html`
- ${this.avatar && html`${this.title || 'Untitled'}
- ${this.members.length ?
- html`${this.members.length} members` :
- 'No members'
- }
-`
-```
-
-
-JSX
-
+::: code-group
-```ts
+```tsx [jsx]
<>
{this.avatar &&
}
{this.title || 'Untitled'}
- {this.members.length ?
- `${this.members.length} members` :
- 'No members'
- }
+ {this.members.length ? `${this.members.length} members` : 'No members'}
```
-
-
-
-Raw
-
-
+```ts [html]
+html`
+ ${this.avatar && html`
`}
+
${this.title || 'Untitled'}
+ ${this.members.length ? html`${this.members.length} members` : 'No members'}
+`;
+```
-```ts
-h(Fragment, null,
- this.avatar && h('img', { 'src': this.avatar }),
+```ts [vdom]
+h(
+ Fragment,
+ null,
+ this.avatar && h('img', { src: this.avatar }),
h('h1', null, this.title || 'Untitled'),
- this.members.length ?
- `${this.members.length} members` :
- 'No members'
-)
+ this.members.length ? `${this.members.length} members` : 'No members'
+);
```
-
+
+:::
### Promises
-The DNA's render algorithm has builtin support for `Promise`s in template: it interpolates the result of a `Promise` as if you were using the `await` statement and provides the helper `until` for status handling:
+DNA exposes two directives to handle promises: the `$await` directive can be used to render a `Promise` result in the template as if you were using the `await` statement, while the `$until` directive is useful for status handling.
-```ts
-import { until } from '@chialab/dna';
+```tsx
+import { $await, $until } from '@chialab/dna';
const json = fetch('/data.json')
.then(() => response.json())
.then((data) => data.map(({ name }) => html`${name} `));
-html`
- ${until(json, 'Loading...')}
- ${json
- .then((data) => html``)
- .catch((error) => html`Error: ${error}
`)
- }
-`
-```
-
-
-JSX
-
-
-```ts
-import { until } from '@chialab/dna';
-
<>
- {until(json, 'Loading...')}
- {json
- .then((data) =>
)
- .catch((error) =>
Error: {error}
)}
-
+ {$until(json, 'Loading...')}
+ {$await(json.then((data) =>
).catch((error) =>
Error: {error}
))}
+;
```
-
-
-
-Raw
-
-
-
-```ts
-h(Fragment, null,
- until(json, 'Loading...'),
- json
- .then((data) => h('ul', null, data))
- .catch((error) => h('div', null, 'Error ', error)),
-)
-```
-
-
-
### Observables
-As well as `Promise`s, DNA treats [`Observable`](https://rxjs-dev.firebaseapp.com/)s like as first class references. You can interpolate [`Observable`]s' values or pipe a template:
+DNA has also a directive to `$pipe` [`Observable`](https://rxjs-dev.firebaseapp.com/)s like as first class references. You can interpolate [`Observable`]s' values or pipe a template:
-```ts
-import { timer, interval } from 'rxjs';
+```tsx
+import { $pipe } from '@chialab/dna';
+import { interval, timer } from 'rxjs';
import { take } from 'rxjs/operators';
const clock$ = timer(Date.now());
const numbers$ = interval(1000).pipe(take(4));
-html`
- Timer: ${timer$},
- Numbers: ${numbers$.pipe((val) => val % 2 ? html`${val} ` : val)}
-`
-```
-
-
-JSX
-
-
-```ts
<>
- Timer: {timer$},
- Numbers: {numbers$.pipe((val) => val % 2 ? {val} : val)}
-
+ Timer: {$pipe(timer$)}, Numbers: {numbers$.pipe((val) => (val % 2 ? {$pipe(val)} : $pipe(val)))}
+;
```
-
-
-
-
-Raw
-
-
-
-```ts
-h(Fragment, null,
- 'Timer: ',
- timer$,
- ', Numbers',
- numbers$.pipe((val) => val % 2 ? h('strong', null, val) : val)
-)
-```
-
-
-
## HTML content
-By default, HTML strings will be interpolated as plain content. It means that a property `content` valorized as `"Hello "` will not create a H1 element, but it will print the code as is. In order to render dynamic html content, you can use the `parseDOM` directive:
+By default, HTML strings will be interpolated as plain content. It means that a property `content` valorized as `"Hello "` will not create a H1 element, but it will print the code as is. In order to render dynamic html content, you can use the `$parse` directive:
```diff
-import { html, parseDOM } from '@chialab/dna';
+import { html, $parse } from '@chialab/dna';
const content = 'Hello ';
-html`${content} `;
-+html`${parseDOM(content)} `;
++html`${$parse(content)} `;
```
-⚠️ Injecting uncontrolled HTML content may exposes your application to XSS vulnerabilities. Always make sure you are rendering secure code!
+::: warning
+
+Injecting uncontrolled HTML content may exposes your application to XSS vulnerabilities. Always make sure you are rendering secure code!
+
+:::
## Function components
Sometimes, you may want to break up templates in smaller parts without having to define new Custom Elements. In this cases, you can use functional components. Function components have first class support in many frameworks like React and Vue, but they require hooks in order to update DOM changes. Since DNA's state is reflected to the DOM and a "current context" is missing, the implemention is slightly different and does not require extra abstraction.
+::: code-group
-
-```ts
+```tsx [jsx]
function Row({ children, id }, { store, requestUpdate }) {
const selected = store.get('selcted') ?? false;
const toggle = () => {
@@ -328,24 +222,29 @@ function Row({ children, id }, { store, requestUpdate }) {
requestUpdate();
};
- return html`${children}>${children} `;
+ return (
+
+ {...children}
+
+ );
}
-html`
+
- ${items.map((item) => html`<${Row} ...${item}>
- ${item.id}
- ${item.label}
- `)}
+ {items.map((item) => (
+
+ {item.id}
+ {item.label}
+
+ ))}
-
`
+
;
```
-
-JSX
-
-
-```ts
+```ts [html]
function Row({ children, id }, { store, requestUpdate }) {
const selected = store.get('selcted') ?? false;
const toggle = () => {
@@ -353,28 +252,28 @@ function Row({ children, id }, { store, requestUpdate }) {
requestUpdate();
};
- return
{...children} ;
+ return html`
${children}>${children} `;
}
-
+html`
- {items.map((item) =>
- {item.id}
- {item.label}
-
)}
+ ${items.map(
+ (item) =>
+ html`<${Row} ...${item}>
+ ${item.id}
+ ${item.label}
+ `
+ )}
-
+
`;
```
-
-
-
-Raw
-
-
-
-```ts
+```ts [vdom]
function Row({ children, id }, { store, requestUpdate }) {
const selected = store.get('selcted') ?? false;
const toggle = () => {
@@ -394,20 +293,20 @@ h('table', null,
),
)
```
-
-
+
+:::
## Nodes and references
DNA can handle `Node` instances as children and hyper nodes as well. When passed as children, the very same node is positioned "as is" to the right place in the template:
-```ts
-import { DOM, render } from '@chialab/dna';
+```tsx
+import { render } from '@chialab/dna';
-let paragraph = DOM.createElement('p');
+const paragraph = document.createElement('p');
paragraph.textContent = 'Lorem Ipsum';
-render(html`${paragraph}
`, document.body);
+render({paragraph}
, document.body);
```
will render:
@@ -423,16 +322,22 @@ will render:
If you want to add some properties to the instance, you can pass it as an hyper node using the `ref` property. This is useful if you want to reference some nodes in your component:
```tsx
-import { DOM, Component, customElement, listen } from '@chialab/dna';
+import { Component, customElement, listen } from '@chialab/dna';
@customElement('x-form')
class Form extends Component {
- input = DOM.createElement('input');
+ input = this.onwenrDocument.createElement('input');
render() {
- return ;
+ return (
+
+ );
}
@listen('change', this.input)
@@ -449,32 +354,32 @@ Slotted children are nodes that semantically are children of the component, but
For example, we may declare a custom `` tag with some layout features:
```tsx
-import { window, extend, customElement, property } from '@chialab/dna';
+import { builtin, customElement, property } from '@chialab/dna';
@customElement('x-dialog', {
extends: 'dialog',
})
-class Dialog extends extend(window.HTMLDialogElement) {
+class Dialog extends builtin.HTMLDialogElement {
@property() title: string = '';
@property() content: string = '';
render() {
- return
-
-
- {this.content}
+ return (
+
-
;
+ );
}
}
```
This example has two problems:
-* content is passed as property, which is not good for semantic
-* body is interpolated as string, so HTML code is rendered as plain text.
+- content is passed as property, which is not good for semantic
+- body is interpolated as string, so HTML code is rendered as plain text.
DNA solves those two issues, rendering "soft" children of an element into the `
` tag:
@@ -571,15 +476,21 @@ Now the resulting DOM would be:
DNA optimizes rendering re-using elements when possible, comparing the tag name for elements, content for text nodes and constructor for components. Sometimes, you may prefer re-create a node instead of reusing the previous one. In this cases, you can use the `key` attribute to define an unique slug for the component that will be used for comparisons.
-```ts
-html`
-
- ${this.items.map((item) => html`
- ${item}
- `)}
- Other
-
-`
+```tsx
+
+ {this.items.map((item) => (
+
+ {item}
+
+ ))}
+
+ Other
+
+
```
In this example, once the last `` element has been created, it never changes its DOM reference, since previous ` ` generations always re-create the element instead of re-using the keyed one.
diff --git a/docs/styling.md b/docs/guide/styling.md
similarity index 74%
rename from docs/styling.md
rename to docs/guide/styling.md
index cc8a5225..99f2a8da 100644
--- a/docs/styling.md
+++ b/docs/guide/styling.md
@@ -4,8 +4,11 @@ DNA can render plain `
Alan Turing
-
```
In the resulting HTML of the example above, the first `H1` color will not be affected by the scoped style declaration.
@@ -48,13 +56,17 @@ In the resulting HTML of the example above, the first `H1` color will not be aff
DNA uses the component definition name to prefix all CSS rules with an unique selector for the element. For example, the rule
```css
-h1 { color: cadetblue; }
+h1 {
+ color: cadetblue;
+}
```
is transformed into
```css
-[is="x-card"] h1 { color: cadetblue; }
+[is='x-card'] h1 {
+ color: cadetblue;
+}
```
### The `:host` pseudo selector
@@ -119,20 +131,18 @@ x-card .title {
```
```html
-1 | ✅ | ✅ | ✅ |
-| Lit | ✅2 | ✅ | ✅ | ⚠️3 |
-| Vue | ✅2 | ⚠️5 | ⚠️5 | ⚠️5 |
-| Angular | 🚧 | 🚧 | 🚧 | 🚧 |
-
-
-1 partial support in React is granted primitive properties, but not for reference values before React 19.
-
-2 support in Lit is granted using [property expressions](https://lit.dev/docs/templates/expressions/#property-expressions).
-
-3 partial support in Lit is granted for first render, but inserting/removing children may lead to render issues.
-
-4 support in Vue is granted using [property expressions](https://vuejs.org/guide/extras/render-function.html).
-
-5 partial support in Vue is granted for first render and insterted children, but removing children may lead to render issues.
-
-## View libraries
-
-Sometimes you need to encapsulate in DNA another UI library, like [Mapbox](https://github.com/mapbox/mapbox-gl-js) or [Pickr](https://github.com/Simonwep/pickr). Since DNA components are DOM nodes, the integration is possible using the element context as library param:
-
-```ts
-import { Component, customElement } from '@chialab/dna';
-import Pickr from '@simonwep/pickr';
-
-@customElement('color-picker')
-export class ColorPicker extends Component {
- private pickr: Pickr;
-
- connectedCallback() {
- super.connectedCallback();
- this.pickr = new Pickr({
- el: this,
- });
- }
-
- disconnectedCallback() {
- this.pickr.destroyAndRemove();
- super.disconnectedCallback();
- }
-}
-```
-
-## Manipulating the DOM
-
-Since DNA does not require any Custom Elements polyfill, the [life cycle](./life-cycle) is delegated to the render cycle which uses the `DOM` helper under the hood. This helper invokes the life cycle methods for each DOM operation like `appendChild`, `removeChild` etc.
-If you want to manipulate the DOM tree outside of a render cycle, always use `DOM` methods instead of the `HTMLElement` prototype:
-
-```ts
-import { ChildComponent } from './child-component';
-
-const child = new ChildComponent();
-
-// ✘ DON'T
-document.body.appendChild(child);
-// ✔︎ DO!
-DOM.appendChild(document.body, child);
-```
-
-All methods inherit the prototype signature with the context node as first argument:
-
-| `HTMLElement.prototype` | `DOM` helper |
-| :------------------- | :------------ |
-| `appendChild(newChild)` | `appendChild(parent, newChild)` |
-| `removeChild(oldChild)` | `removeChild(parent, oldChild)` |
-| `insertBefore(newChild, refChild)` | `insertBefore(parent, newChild, refChild)` |
-| `replaceChild(newChild, oldChild)` | `replaceChild(parent, newChild, oldChild)` |
-| `insertAdjacentElement(position, instertedElement)` | `insertAdjacentElement(parent, position, instertedElement)` |
-| `getAttribute(qualifiedName)` | `getAttribute(element, qualifiedName)` |
-| `hasAttribute(qualifiedName)` | `hasAttribute(element, qualifiedName)` |
-| `setAttribute(qualifiedName, value)` | `setAttribute(element, qualifiedName, value)` |
-| `removeAttribute(qualifiedName)` | `removeAttribute(element, qualifiedName)` |
-| `dispatchEvent(event)` | `dispatchEvent(element, event)` |
-| `matches(selector)` | `matches(element, selector)` |
-
-
diff --git a/docs/migrations.md b/docs/migrations.md
index c1354dda..e0d68c69 100644
--- a/docs/migrations.md
+++ b/docs/migrations.md
@@ -2,16 +2,16 @@
**Changes**
-* Function Component signature has changed:
+- Function Component signature has changed:
```diff
- function Card(properties, store, requestUpdate) {
+ function Card(properties, { store, requestUpdate }) {
```
-* Typings improvements
+- Typings improvements
-* Using the `compile` function is now the preferred way to compile on the fly an HTML string into a virtual DOM template:
+- Using the `compile` function is now the preferred way to compile on the fly an HTML string into a virtual DOM template:
```diff
-import { html } from '@chialab/dna';
@@ -27,9 +27,9 @@ Please note that VDOM convertion does not handle HTML entities and it can lead t
This is a list of changes requested to completely migrate to the DNA 3.0 version.
-* Install and use the new `@chialab/dna` instead of the `@dnajs/idom` module
+- Install and use the new `@chialab/dna` instead of the `@dnajs/idom` module
-* Extends the `Component` constructor instead of the `BaseComponent` class
+- Extends the `Component` constructor instead of the `BaseComponent` class
```diff
- import { BaseComponent } from '@dnajs/idom';
@@ -39,42 +39,42 @@ This is a list of changes requested to completely migrate to the DNA 3.0 version
+ class Card extends Component {
```
-* Convert `template` getter to `render` method.
+- Convert `template` getter to `render` method.
-* Convert `css` getter to ``;
- },
- };
- /* eslint-enable mocha/no-setup-in-describe */
-
- for (const type in TEMPLATES) {
- it(type, () => {
- const rootName = getComponentName();
- class MyElement extends DNA.extend(DNA.window.HTMLDivElement) {
- render() {
- return TEMPLATES[type]();
- }
- }
-
- DNA.customElements.define(`${rootName}-${type.toLowerCase()}`, MyElement, { extends: 'div' });
-
- const element = DNA.render(DNA.h(MyElement), wrapper);
- expect(element.childNodes).to.have.lengthOf(1);
- expect(element.childNodes[0].tagName).to.be.equal('STYLE');
- expect(element.childNodes[0].textContent).to.be.equal(`div[is="${rootName}-${type.toLowerCase()}"] .test {}`);
- });
- }
- });
-
- describe('slot', () => {
- /* eslint-disable mocha/no-setup-in-describe */
- const TEMPLATES = {
- JSX(titleName) {
- return DNA.h(DNA.Fragment, null,
- DNA.h('div', { class: 'layout-header' }, DNA.h(`${titleName}-jsx`, null, DNA.h('slot', { name: 'title' }))),
- DNA.h('div', { class: 'layout-body' }, DNA.h('slot'))
- );
- },
- HTML(titleName) {
- return DNA.html`
-
-
-
- `;
- },
- };
- /* eslint-enable mocha/no-setup-in-describe */
-
- for (const type in TEMPLATES) {
- it(type, () => {
- const rootName = getComponentName();
- const titleName = getComponentName();
- class MyElement extends DNA.Component {
- render() {
- return TEMPLATES[type](titleName);
- }
- }
-
- DNA.customElements.define(`${rootName}-${type.toLowerCase()}`, MyElement);
-
- class MyTitle extends DNA.Component {
- render() {
- return DNA.h('span', { class: 'title' }, DNA.h('slot', {}, ['Untitled']));
- }
- }
-
- DNA.customElements.define(`${titleName}-${type.toLowerCase()}`, MyTitle);
-
- const element = DNA.render(DNA.h(`${rootName}-${type.toLowerCase()}`, null,
- DNA.h('img', { src: IMG }),
- DNA.h('p', null, 'Body')
- ), wrapper);
-
- expect(element.childNodes).to.have.lengthOf(2);
- expect(element.childNodes[0].tagName).to.be.equal('DIV');
- expect(element.childNodes[0].className).to.be.equal('layout-header');
- expect(element.childNodes[0].childNodes).to.have.lengthOf(1);
- expect(element.childNodes[0].childNodes[0].tagName).to.be.equal(`${titleName}-${type}`.toUpperCase());
- expect(element.childNodes[0].childNodes[0].childNodes[0].tagName).to.be.equal('SPAN');
- expect(element.childNodes[0].childNodes[0].childNodes[0].textContent).to.be.equal('Untitled');
-
- DNA.render(DNA.h(`${rootName}-${type.toLowerCase()}`, null,
- DNA.h('h1', { slot: 'title' }, 'Title'),
- DNA.h('img', { src: IMG }),
- DNA.h('p', null, 'Body')
- ), wrapper);
-
- expect(element.childNodes[0].childNodes[0].childNodes[0].tagName).to.be.equal('SPAN');
- expect(element.childNodes[0].childNodes[0].childNodes[0].textContent).to.be.equal('Title');
- expect(element.childNodes[1].tagName).to.be.equal('DIV');
- expect(element.childNodes[1].className).to.be.equal('layout-body');
- expect(element.childNodes[1].childNodes[0].tagName).to.be.equal('IMG');
- expect(element.childNodes[1].childNodes[0].getAttribute('src')).to.be.equal(IMG);
- expect(element.childNodes[1].childNodes[1].tagName).to.be.equal('P');
- expect(element.childNodes[1].childNodes[1].textContent).to.be.equal('Body');
- });
- }
- });
-
- describe('slot with upgraded elements', () => {
- /* eslint-disable mocha/no-setup-in-describe */
- const TEMPLATES = {
- JSX() {
- return DNA.h(DNA.Fragment, null,
- DNA.h('div', { class: 'layout-header' }, DNA.h('slot', { name: 'title' })),
- DNA.h('div', { class: 'layout-body' }, DNA.h('slot'))
- );
- },
- HTML() {
- return DNA.html`
-
-
-
- `;
- },
- };
- /* eslint-enable mocha/no-setup-in-describe */
-
- for (const type in TEMPLATES) {
- it(type, () => {
- const name = getComponentName();
- class MyElement extends DNA.Component {
- render() {
- return TEMPLATES[type]();
- }
- }
+describe(
+ 'template',
+ () => {
+ let wrapper;
+ beforeEach(() => {
+ wrapper = document.createElement('div');
+ document.body.appendChild(wrapper);
+ });
- const element = DNA.render(DNA.h(`${name}-${type.toLowerCase()}`, null,
- DNA.h('h1', { slot: 'title' }, 'Title'),
- DNA.h('img', { src: IMG }),
- DNA.h('p', null, 'Body')
- ), wrapper);
-
- DNA.customElements.define(`${name}-${type.toLowerCase()}`, MyElement);
- DNA.customElements.upgrade(element);
-
- expect(element.childNodes).to.have.lengthOf(2);
- expect(element.childNodes[0].tagName).to.be.equal('DIV');
- expect(element.childNodes[0].className).to.be.equal('layout-header');
- expect(element.childNodes[0].childNodes).to.have.lengthOf(1);
- expect(element.childNodes[0].childNodes[0].tagName).to.be.equal('H1');
- expect(element.childNodes[0].childNodes[0].textContent).to.be.equal('Title');
- expect(element.childNodes[1].tagName).to.be.equal('DIV');
- expect(element.childNodes[1].className).to.be.equal('layout-body');
- expect(element.childNodes[1].childNodes[0].tagName).to.be.equal('IMG');
- expect(element.childNodes[1].childNodes[0].getAttribute('src')).to.be.equal(IMG);
- expect(element.childNodes[1].childNodes[1].tagName).to.be.equal('P');
- expect(element.childNodes[1].childNodes[1].textContent).to.be.equal('Body');
- });
- }
- });
-
- describe('slot moved across elements', () => {
- /* eslint-disable mocha/no-setup-in-describe */
- const TEMPLATES = {
- JSX(cardName, collapsed) {
- if (collapsed) {
- return DNA.h('slot');
- }
+ afterEach(() => {
+ document.body.removeChild(wrapper);
+ });
- return DNA.h(cardName, {}, DNA.h('slot'));
- },
- HTML(cardName, collapsed) {
- if (collapsed) {
- return DNA.html`Hello world! `;
+ },
+ PLAIN_HTML() {
+ return DNA.compile('Hello world! ');
+ },
+ };
- return DNA.html`<${cardName}>
- Hello world! `;
+ },
+ };
- DNA.customElements.define(`${cardName}-${type.toLowerCase()}`, MyCard);
-
- const element = DNA.render(DNA.h(`${name}-${type.toLowerCase()}`, null,
- DNA.h('h1', {}, 'Title'),
- DNA.h('img', { src: IMG }),
- DNA.h('p', null, 'Body')
- ), wrapper);
-
- DNA.customElements.define(`${name}-${type.toLowerCase()}`, MyElement);
- DNA.customElements.upgrade(element);
-
- expect(element.childNodes).to.have.lengthOf(1);
- expect(element.childNodes[0].childNodes[0].tagName).to.be.equal('H1');
- expect(element.childNodes[0].childNodes[0].textContent).to.be.equal('Title');
- expect(element.childNodes[0].childNodes[1].tagName).to.be.equal('IMG');
- expect(element.childNodes[0].childNodes[1].getAttribute('src')).to.be.equal(IMG);
- expect(element.childNodes[0].childNodes[2].tagName).to.be.equal('P');
- expect(element.childNodes[0].childNodes[2].textContent).to.be.equal('Body');
- element.collapsed = true;
- element.forceUpdate();
- expect(element.childNodes[0].tagName).to.be.equal('H1');
- expect(element.childNodes[0].textContent).to.be.equal('Title');
- expect(element.childNodes[1].tagName).to.be.equal('IMG');
- expect(element.childNodes[1].getAttribute('src')).to.be.equal(IMG);
- expect(element.childNodes[2].tagName).to.be.equal('P');
- expect(element.childNodes[2].textContent).to.be.equal('Body');
- element.collapsed = false;
- element.forceUpdate();
- expect(element.childNodes[0].childNodes[0].tagName).to.be.equal('H1');
- expect(element.childNodes[0].childNodes[0].textContent).to.be.equal('Title');
- expect(element.childNodes[0].childNodes[1].tagName).to.be.equal('IMG');
- expect(element.childNodes[0].childNodes[1].getAttribute('src')).to.be.equal(IMG);
- expect(element.childNodes[0].childNodes[2].tagName).to.be.equal('P');
- expect(element.childNodes[0].childNodes[2].textContent).to.be.equal('Body');
- });
- }
- });
+ for (const type in TEMPLATES) {
+ it(type, () => {
+ DNA.render(TEMPLATES[type](), wrapper);
+ expect(wrapper.childNodes).toHaveLength(1);
+ expect(wrapper.childNodes[0].tagName).toBe('H1');
+ expect(wrapper.childNodes[0].textContent).toBe('Hello world!');
+ });
+ }
+ });
- describe('events', () => {
- describe('should add an event listener', () => {
- /* eslint-disable mocha/no-setup-in-describe */
+ describe('content interpolation', () => {
const TEMPLATES = {
JSX(context) {
- return DNA.h('button', { onclick: context.listener });
+ return DNA.h(
+ 'h1',
+ null,
+ 'Hello! My name is ',
+ context.name,
+ ' and my favorite number is ',
+ context.num
+ );
},
HTML(context) {
- return DNA.html`Hello! My name is ${context.name} and my favorite number is ${context.num} `;
},
};
- /* eslint-enable mocha/no-setup-in-describe */
for (const type in TEMPLATES) {
it(type, () => {
- const listener = spy((event) => {
- event.preventDefault();
- });
-
- DNA.render(TEMPLATES[type]({
- listener,
- }), wrapper);
+ DNA.render(
+ TEMPLATES[type]({
+ name: 'Alan',
+ num: 42,
+ }),
+ wrapper
+ );
+ expect(wrapper.childNodes).toHaveLength(1);
+ expect(wrapper.childNodes[0].tagName).toBe('H1');
+ expect(wrapper.childNodes[0].textContent).toBe(
+ 'Hello! My name is Alan and my favorite number is 42'
+ );
+ });
+ }
+ });
- const button = wrapper.childNodes[0];
- button.click();
+ describe('attribute interpolation', () => {
+ const TEMPLATES = {
+ JSX(context) {
+ return DNA.h('input', {
+ name: context.name,
+ disabled: context.disabled,
+ required: true,
+ });
+ },
+ HTML(context) {
+ return DNA.html`
- ${DNA.until(context.promise, 'Loading...')}
-
${context.promise.then((res) => DNA.html`Hello ${res}`)}
-
+ ${context.items.map((item, index) => DNA.html`${index}. ${item} `)}
+ `;
},
};
- /* eslint-enable mocha/no-setup-in-describe */
for (const type in TEMPLATES) {
- it(type, async () => {
- const promise = new Promise((resolve) => {
- setTimeout(() => resolve('World!'), 1000);
- });
-
- DNA.render(TEMPLATES[type]( {
- promise,
- }), wrapper);
-
- expect(wrapper.innerHTML).to.be.equal('');
- DNA.render(TEMPLATES[type]( {
- promise,
- }), wrapper);
- await wait(1500);
- expect(wrapper.innerHTML).to.be.equal('');
+ it(type, () => {
+ DNA.render(
+ TEMPLATES[type]({
+ items: ['Alan', 'Brian', 'Carl'],
+ }),
+ wrapper
+ );
+ expect(wrapper.childNodes).toHaveLength(1);
+ expect(wrapper.childNodes[0].tagName).toBe('UL');
+ expect(wrapper.childNodes[0].childNodes).toHaveLength(3);
+ expect(wrapper.childNodes[0].childNodes[0].tagName).toBe('LI');
+ expect(wrapper.childNodes[0].childNodes[0].textContent).toBe('0. Alan');
+ expect(wrapper.childNodes[0].childNodes[1].tagName).toBe('LI');
+ expect(wrapper.childNodes[0].childNodes[1].textContent).toBe('1. Brian');
+ expect(wrapper.childNodes[0].childNodes[2].tagName).toBe('LI');
+ expect(wrapper.childNodes[0].childNodes[2].textContent).toBe('2. Carl');
});
}
});
- describe('should handle failed promises', () => {
- /* eslint-disable mocha/no-setup-in-describe */
+ describe('conditionals', () => {
const TEMPLATES = {
JSX(context) {
- return DNA.h('div', null,
- DNA.until(context.promise, 'Loading...'),
- context.promise.catch((error) => ['Error ', error])
+ return DNA.h(
+ DNA.Fragment,
+ null,
+ context.avatar && DNA.h('img', { src: context.avatar }),
+ DNA.h('h1', null, context.title || 'Untitled'),
+ context.members.length ? `${context.members.length} members` : 'No members'
);
},
HTML(context) {
- return DNA.html`
- ${DNA.until(context.promise, 'Loading...')}
- ${context.promise.catch((error) => DNA.html`Error ${error}`)}
-
`;
+ return DNA.html`
+ ${context.avatar && DNA.html`${context.title || 'Untitled'}
+ ${context.members.length ? DNA.html`${context.members.length} members` : 'No members'}`;
+ },
+ };
+
+ for (const type in TEMPLATES) {
+ it(type, () => {
+ DNA.render(
+ TEMPLATES[type]({
+ avatar: IMG,
+ title: 'Romeo',
+ members: [],
+ }),
+ wrapper
+ );
+ expect(wrapper.childNodes).toHaveLength(3);
+ expect(wrapper.childNodes[0].tagName).toBe('IMG');
+ expect(wrapper.childNodes[0].getAttribute('src')).toBe(IMG);
+ expect(wrapper.childNodes[1].tagName).toBe('H1');
+ expect(wrapper.childNodes[1].textContent).toBe('Romeo');
+ expect(wrapper.childNodes[2].textContent).toBe('No members');
+ });
+ }
+ });
+
+ describe('style', () => {
+ const TEMPLATES = {
+ JSX() {
+ return DNA.h('style', {}, '.test {}');
+ },
+ HTML() {
+ return DNA.html``;
},
};
- /* eslint-enable mocha/no-setup-in-describe */
for (const type in TEMPLATES) {
it(type, async () => {
- const promise = new Promise((resolve, reject) => {
- setTimeout(() => reject('timeout'), 1000);
- });
+ const rootName = getComponentName();
+ class MyElement extends DNA.builtin.HTMLDivElement {
+ render() {
+ return TEMPLATES[type]();
+ }
+ }
- DNA.render(TEMPLATES[type]({
- promise,
- }), wrapper);
+ DNA.define(`${rootName}-${type.toLowerCase()}`, MyElement, { extends: 'div' });
- expect(wrapper.innerHTML).to.be.equal('Loading...
');
- DNA.render(TEMPLATES[type]({
- promise,
- }), wrapper);
- await wait(1500);
- expect(wrapper.innerHTML).to.be.equal('Error timeout
');
+ const element = DNA.render(DNA.h(MyElement), wrapper);
+ await new Promise((r) => setTimeout(r, 0));
+
+ const realm = element.realm;
+ realm.dangerouslyOpen();
+ expect(element.childNodes).toHaveLength(1);
+ expect(element.childNodes[0].tagName).toBe('STYLE');
+ expect(element.childNodes[0].textContent).toBe(
+ `[:scope="${rootName}-${type.toLowerCase()}"] .test {}`
+ );
+ realm.dangerouslyClose();
});
}
});
- it('should ignore outdated promises in template', async () => {
- let flag = false;
- const promise = new Promise((resolve) => {
- setTimeout(() => {
- flag = true;
- DNA.render(template(), wrapper);
- resolve('World!');
- }, 1000);
- });
- const template = () => DNA.html`
- ${!flag && DNA.until(promise, 'Loading...')}
- ${flag && 'Done'}
-
`;
+ describe('slot', () => {
+ const TEMPLATES = {
+ JSX(titleName) {
+ return DNA.h(
+ DNA.Fragment,
+ null,
+ DNA.h(
+ 'div',
+ { class: 'layout-header' },
+ DNA.h(`${titleName}-jsx`, null, DNA.h('slot', { name: 'title' }))
+ ),
+ DNA.h('div', { class: 'layout-body' }, DNA.h('slot'))
+ );
+ },
+ HTML(titleName) {
+ return DNA.html`
+
+
+
+ `;
+ },
+ };
- DNA.render(template(), wrapper);
- expect(wrapper.innerHTML).to.be.equal('Loading...
');
- DNA.render(template(), wrapper);
- await wait(1500);
- expect(wrapper.innerHTML).to.be.equal('Done
');
- });
+ for (const type in TEMPLATES) {
+ it(type, () => {
+ const rootName = getComponentName();
+ const titleName = getComponentName();
+ class MyElement extends DNA.Component {
+ render() {
+ return TEMPLATES[type](titleName);
+ }
+ }
- it('should ignore outdated dependents promises in template', async () => {
- const promise = new Promise((resolve) => {
- setTimeout(() => resolve('World!'), 1000);
- });
- const promise2 = new Promise((resolve) => {
- setTimeout(() => resolve('World!'), 500);
- });
- DNA.render(DNA.html`
- ${DNA.until(promise2, DNA.html`${promise.then((res) => DNA.html`Hello ${res}`)}`)}
-
`, wrapper);
- await wait(1500);
- expect(wrapper.innerHTML).to.be.equal('
');
+ DNA.define(`${rootName}-${type.toLowerCase()}`, MyElement);
+
+ class MyTitle extends DNA.Component {
+ render() {
+ return DNA.h('span', { class: 'title' }, DNA.h('slot', {}, ['Untitled']));
+ }
+ }
+
+ DNA.define(`${titleName}-${type.toLowerCase()}`, MyTitle);
+
+ const element = DNA.render(
+ DNA.h(
+ `${rootName}-${type.toLowerCase()}`,
+ null,
+ DNA.h('img', { src: IMG }),
+ DNA.h('p', null, 'Body')
+ ),
+ wrapper
+ );
+ const realm = element.realm;
+
+ realm.dangerouslyOpen();
+ const innerRealm = element.childNodes[0].childNodes[0].realm;
+ innerRealm.dangerouslyOpen();
+ expect(element.childNodes).toHaveLength(2);
+ expect(element.childNodes[0].tagName).toBe('DIV');
+ expect(element.childNodes[0].className).toBe('layout-header');
+ expect(element.childNodes[0].childNodes).toHaveLength(1);
+ expect(element.childNodes[0].childNodes[0].tagName).toBe(`${titleName}-${type}`.toUpperCase());
+ expect(element.childNodes[0].childNodes[0].childNodes[0].tagName).toBe('SPAN');
+ expect(element.childNodes[0].childNodes[0].childNodes[0].textContent).toBe('Untitled');
+ innerRealm.dangerouslyClose();
+ realm.dangerouslyClose();
+
+ DNA.render(
+ DNA.h(
+ `${rootName}-${type.toLowerCase()}`,
+ null,
+ DNA.h('h1', { slot: 'title' }, 'Title'),
+ DNA.h('img', { src: IMG }),
+ DNA.h('p', null, 'Body')
+ ),
+ wrapper
+ );
+
+ realm.dangerouslyOpen();
+ innerRealm.dangerouslyOpen();
+ expect(element.childNodes[0].childNodes[0].childNodes[0].tagName).toBe('SPAN');
+ expect(element.childNodes[0].childNodes[0].childNodes[0].textContent).toBe('Title');
+ expect(element.childNodes[1].tagName).toBe('DIV');
+ expect(element.childNodes[1].className).toBe('layout-body');
+ expect(element.childNodes[1].childNodes[0].tagName).toBe('IMG');
+ expect(element.childNodes[1].childNodes[0].getAttribute('src')).toBe(IMG);
+ expect(element.childNodes[1].childNodes[1].tagName).toBe('P');
+ expect(element.childNodes[1].childNodes[1].textContent).toBe('Body');
+ innerRealm.dangerouslyClose();
+ realm.dangerouslyClose();
+ });
+ }
});
- });
- describe('observables', () => {
- describe('should subscribe', () => {
- /* eslint-disable mocha/no-setup-in-describe */
+ describe('slot with upgraded elements', () => {
const TEMPLATES = {
- JSX(context) {
- /* eslint-disable mocha/no-setup-in-describe */
- return DNA.h('div', null, context.observable$);
+ JSX() {
+ return DNA.h(
+ DNA.Fragment,
+ null,
+ DNA.h('div', { class: 'layout-header' }, DNA.h('slot', { name: 'title' })),
+ DNA.h('div', { class: 'layout-body' }, DNA.h('slot'))
+ );
},
- HTML(context) {
- /* eslint-disable mocha/no-setup-in-describe */
- return DNA.html`
- ${context.observable$}
-
`;
+ HTML() {
+ return DNA.html`
+
+
+
+ `;
},
};
- /* eslint-enable mocha/no-setup-in-describe */
for (const type in TEMPLATES) {
- it(type, async () => {
- const observable$ = new Observable(async (subscriber) => {
- await wait(100);
- subscriber.next(1);
- await wait(100);
- subscriber.next(2);
- await wait(100);
- subscriber.next(3);
- await wait(100);
- subscriber.next(4);
- subscriber.complete();
- });
+ it(type, () => {
+ const name = getComponentName();
+ class MyElement extends DNA.Component {
+ render() {
+ return TEMPLATES[type]();
+ }
+ }
- DNA.render(TEMPLATES[type]({ observable$ }), wrapper);
+ const element = DNA.render(
+ DNA.h(
+ `${name}-${type.toLowerCase()}`,
+ null,
+ DNA.h('h1', { slot: 'title' }, 'Title'),
+ DNA.h('img', { src: IMG }),
+ DNA.h('p', null, 'Body')
+ ),
+ wrapper
+ );
- await wait(100);
- expect(wrapper.innerHTML).to.be.equal('1
');
- await wait(100);
- expect(wrapper.innerHTML).to.be.equal('2
');
- await wait(100);
- expect(wrapper.innerHTML).to.be.equal('3
');
- await wait(100);
- expect(wrapper.innerHTML).to.be.equal('4
');
+ DNA.define(`${name}-${type.toLowerCase()}`, MyElement);
+ window.customElements.upgrade(element);
+
+ const realm = element.realm;
+
+ realm.dangerouslyOpen();
+ expect(element.childNodes).toHaveLength(2);
+ expect(element.childNodes[0].tagName).toBe('DIV');
+ expect(element.childNodes[0].className).toBe('layout-header');
+ expect(element.childNodes[0].childNodes).toHaveLength(1);
+ expect(element.childNodes[0].childNodes[0].tagName).toBe('H1');
+ expect(element.childNodes[0].childNodes[0].textContent).toBe('Title');
+ expect(element.childNodes[1].tagName).toBe('DIV');
+ expect(element.childNodes[1].className).toBe('layout-body');
+ expect(element.childNodes[1].childNodes[0].tagName).toBe('IMG');
+ expect(element.childNodes[1].childNodes[0].getAttribute('src')).toBe(IMG);
+ expect(element.childNodes[1].childNodes[1].tagName).toBe('P');
+ expect(element.childNodes[1].childNodes[1].textContent).toBe('Body');
+ realm.dangerouslyClose();
});
}
});
- describe('should subscribe and pipe', () => {
- /* eslint-disable mocha/no-setup-in-describe */
+ describe('slot moved across elements', () => {
const TEMPLATES = {
- JSX(context) {
- /* eslint-disable mocha/no-setup-in-describe */
- return DNA.h('div', null, context.observable$.pipe((num) => DNA.h('span', null, num)));
+ JSX(cardName, collapsed) {
+ if (collapsed) {
+ return DNA.h('slot');
+ }
+
+ return DNA.h(cardName, {}, DNA.h('slot'));
},
- HTML(context) {
- /* eslint-disable mocha/no-setup-in-describe */
- return DNA.html`
- ${context.observable$.pipe((num) => DNA.html`${num} `)}
-
`;
+ HTML(cardName, collapsed) {
+ if (collapsed) {
+ return DNA.html`1
');
- await wait(100);
- expect(wrapper.innerHTML).to.be.equal('2
');
- await wait(100);
- expect(wrapper.innerHTML).to.be.equal('3
');
- await wait(100);
- expect(wrapper.innerHTML).to.be.equal('4
');
+ class MyCard extends DNA.Component {
+ render() {
+ return DNA.h('slot');
+ }
+ }
+
+ DNA.define(`${cardName}-${type.toLowerCase()}`, MyCard);
+
+ const element = DNA.render(
+ DNA.h(
+ `${name}-${type.toLowerCase()}`,
+ null,
+ DNA.h('h1', {}, 'Title'),
+ DNA.h('img', { src: IMG }),
+ DNA.h('p', null, 'Body')
+ ),
+ wrapper
+ );
+
+ DNA.define(`${name}-${type.toLowerCase()}`, MyElement);
+ window.customElements.upgrade(element);
+ const realm = element.realm;
+
+ realm.dangerouslyOpen();
+ expect(element.childNodes).toHaveLength(1);
+ expect(element.childNodes[0].childNodes[0].tagName).toBe('H1');
+ expect(element.childNodes[0].childNodes[0].textContent).toBe('Title');
+ expect(element.childNodes[0].childNodes[1].tagName).toBe('IMG');
+ expect(element.childNodes[0].childNodes[1].getAttribute('src')).toBe(IMG);
+ expect(element.childNodes[0].childNodes[2].tagName).toBe('P');
+ expect(element.childNodes[0].childNodes[2].textContent).toBe('Body');
+ realm.dangerouslyClose();
+
+ element.collapsed = true;
+ element.forceUpdate();
+
+ realm.dangerouslyOpen();
+ expect(element.childNodes[0].tagName).toBe('H1');
+ expect(element.childNodes[0].textContent).toBe('Title');
+ expect(element.childNodes[1].tagName).toBe('IMG');
+ expect(element.childNodes[1].getAttribute('src')).toBe(IMG);
+ expect(element.childNodes[2].tagName).toBe('P');
+ expect(element.childNodes[2].textContent).toBe('Body');
+ realm.dangerouslyClose();
+
+ element.collapsed = false;
+ element.forceUpdate();
+
+ realm.dangerouslyOpen();
+ expect(element.childNodes[0].childNodes[0].tagName).toBe('H1');
+ expect(element.childNodes[0].childNodes[0].textContent).toBe('Title');
+ expect(element.childNodes[0].childNodes[1].tagName).toBe('IMG');
+ expect(element.childNodes[0].childNodes[1].getAttribute('src')).toBe(IMG);
+ expect(element.childNodes[0].childNodes[2].tagName).toBe('P');
+ expect(element.childNodes[0].childNodes[2].textContent).toBe('Body');
+ realm.dangerouslyClose();
});
}
});
- });
-});
+
+ describe('events', () => {
+ describe('should add an event listener', () => {
+ const TEMPLATES = {
+ JSX(context) {
+ return DNA.h('button', { onclick: context.listener });
+ },
+ HTML(context) {
+ return DNA.html`
+ ${DNA.$until(context.promise, 'Loading...')}
+
${DNA.$await(context.promise.then((res) => DNA.html`Hello ${res}`))}
+
+ ${DNA.$until(context.promise, 'Loading...')}
+ ${DNA.$await(context.promise.catch((error) => DNA.html`Error ${error}`))}
+
`;
+ },
+ };
+
+ for (const type in TEMPLATES) {
+ it(type, async () => {
+ const promise = new Promise((resolve, reject) => {
+ setTimeout(() => reject('timeout'), 1000);
+ });
+
+ DNA.render(
+ TEMPLATES[type]({
+ promise,
+ }),
+ wrapper
+ );
+
+ expect(wrapper.innerHTML).toBe('Loading...
');
+ DNA.render(
+ TEMPLATES[type]({
+ promise,
+ }),
+ wrapper
+ );
+ await new Promise((r) => setTimeout(r, 1500));
+ expect(wrapper.innerHTML).toBe('Error timeout
');
+ });
+ }
+ });
+
+ it('should ignore outdated promises in template', async () => {
+ let flag = false;
+ const promise = new Promise((resolve) => {
+ setTimeout(() => {
+ flag = true;
+ DNA.render(template(), wrapper);
+ resolve('World!');
+ }, 1000);
+ });
+ const template = () => DNA.html`
+ ${!flag && DNA.$until(promise, 'Loading...')}
+ ${flag && 'Done'}
+
`;
+
+ DNA.render(template(), wrapper);
+ expect(wrapper.innerHTML).toBe('Loading...
');
+ DNA.render(template(), wrapper);
+ await new Promise((r) => setTimeout(r, 1500));
+ expect(wrapper.innerHTML).toBe('Done
');
+ });
+
+ it('should ignore outdated dependents promises in template', async () => {
+ const promise = new Promise((resolve) => {
+ setTimeout(() => resolve('World!'), 1000);
+ });
+ const promise2 = new Promise((resolve) => {
+ setTimeout(() => resolve('World!'), 500);
+ });
+ DNA.render(
+ DNA.html`
+ ${DNA.$until(promise2, DNA.html`${promise.then((res) => DNA.html`Hello ${res}`)}`)}
+
`,
+ wrapper
+ );
+ await new Promise((r) => setTimeout(r, 1500));
+ expect(wrapper.innerHTML).toBe('
');
+ });
+ });
+
+ describe('observables', () => {
+ describe('should subscribe', () => {
+ const TEMPLATES = {
+ JSX(context) {
+ return DNA.h('div', null, DNA.$pipe(context.observable$));
+ },
+ HTML(context) {
+ return DNA.html`
+ ${DNA.$pipe(context.observable$)}
+
`;
+ },
+ };
+
+ for (const type in TEMPLATES) {
+ it(type, async () => {
+ const observable$ = new Observable((subscriber) => {
+ Promise.resolve().then(async () => {
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(1);
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(2);
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(3);
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(4);
+ subscriber.complete();
+ });
+ });
+
+ DNA.render(TEMPLATES[type]({ observable$ }), wrapper);
+
+ await new Promise((r) => setTimeout(r, 150));
+ expect(wrapper.innerHTML).toBe('1
');
+ await new Promise((r) => setTimeout(r, 100));
+ expect(wrapper.innerHTML).toBe('2
');
+ await new Promise((r) => setTimeout(r, 100));
+ expect(wrapper.innerHTML).toBe('3
');
+ await new Promise((r) => setTimeout(r, 100));
+ expect(wrapper.innerHTML).toBe('4
');
+ });
+ }
+ });
+
+ describe('should subscribe and pipe', () => {
+ const TEMPLATES = {
+ JSX(context) {
+ return DNA.h(
+ 'div',
+ null,
+ context.observable$.pipe((num) => DNA.h('span', null, DNA.$pipe(num)))
+ );
+ },
+ HTML(context) {
+ return DNA.html`
+ ${context.observable$.pipe((num) => DNA.html`${DNA.$pipe(num)} `)}
+
`;
+ },
+ };
+
+ for (const type in TEMPLATES) {
+ it(type, async () => {
+ const observable$ = new Observable((subscriber) => {
+ Promise.resolve().then(async () => {
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(1);
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(2);
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(3);
+ await new Promise((r) => setTimeout(r, 100));
+ subscriber.next(4);
+ subscriber.complete();
+ });
+ });
+
+ DNA.render(TEMPLATES[type]({ observable$ }), wrapper);
+
+ await new Promise((r) => setTimeout(r, 150));
+ expect(wrapper.innerHTML).toBe('1
');
+ await new Promise((r) => setTimeout(r, 100));
+ expect(wrapper.innerHTML).toBe('2
');
+ await new Promise((r) => setTimeout(r, 100));
+ expect(wrapper.innerHTML).toBe('3
');
+ await new Promise((r) => setTimeout(r, 100));
+ expect(wrapper.innerHTML).toBe('4
');
+ });
+ }
+ });
+ });
+ },
+ 10 * 1000
+);
diff --git a/test/typings/render.tsx b/test/typings/render.tsx
deleted file mode 100644
index 95b10584..00000000
--- a/test/typings/render.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-// eslint-disable-next-line import/no-unresolved
-import { DOM, Fragment, h, render } from '@chialab/dna';
-import { TestElement, TestBuiltinElement } from './Component';
-
-render(
);
-render( {}} />);
-// @ts-expect-error Promise is not a HTMLElement constructor
-render( 
