Skip to content

Commit

Permalink
chore: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
0kku committed Mar 30, 2021
1 parent 1f3ca26 commit 18773db
Showing 1 changed file with 6 additions and 4 deletions.
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,20 @@ A reactive UI library for JavaScript and TypeScript. Uses standard JS/TS syntax;
3. run `npm run compile` in root
4. start a dev server (ex: `npx http-server .`) and open `/index.html` to view demo

To get syntax-highlighting for HTML templates, you can use an extension called [`tobermory.es6-string-html`](https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html) on VSCode. Similar plugins are available for other editors too. Any extension that makes the editor treat template literals' tags as that block's file extension (ex. ``html`...`;`` is treated as an .html snippet) should also work. This only gives you syntax highlighting, though: slots are unfortunately not type checked; that would require a dedicated extension for this library, which does not yet exist.
To get syntax-highlighting for HTML templates, you can use an extension called [`tobermory.es6-string-html`](https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html) on VSCode. Similar plugins are available for other editors too. Any extension that makes the editor treat template literals' tags as that block's file extension (ex. ``xml/*html*/`…`;`` is treated as an .html snippet) should also work. This only gives you syntax highlighting, though: slots are unfortunately not type checked; that would require a dedicated extension for this library, which does not yet exist.

## Examples

Live demo (with source maps): https://destiny.okku.dev/

You can convert anything to be reactive using the `reactive()` function. Their primitive value can be accessed via the `value` property. Setting `value` will cause the reactive item to dispatch events to all its listeners.

The `html` template tag will parse the content as HTML and returns an TempalteResult object containing a `DocumentFragment`. Any reactive items given to it via `${}` slots are bound both ways. This means that when the value of the reactive element is changed later, the relevant part of the HTML is automatically updated. If a reactive item is bound to something that may change from user input, the value of the reactive item will be automatically updated accordingly as user input comes in.
The `xml` template tag will parse the content as XHTML and returns an TemplateResult object containing a `DocumentFragment`. Any reactive items given to it via `${}` slots are bound both ways. This means that when the value of the reactive element is changed later, the relevant part of the DOM is automatically updated. If a reactive item is bound to something that may change from user input, the value of the reactive item will be automatically updated accordingly as user input comes in.

In the below example, two reactive items `#who` and `#count` are defined. `#who` is set as the value of an input element: the value of `#who` is updated whenever the text field in question receives input. `#who` is also rendered as text below, so as the user types, the text below will update in real time. `#count` on the other hand is just a number which is incremented once a second; the seconds counter is automatically rerendered every time the count changes.

```js
import { Component, html, reactive, register } from "https://code.okku.dev/destiny-ui/0.4.1/dist/mod.js";
import { Component, xml, reactive, register } from "https://code.okku.dev/destiny-ui/0.5.1/dist/mod.js";

register(class ExampleComponent extends Component {
#who = reactive("visitor");
Expand All @@ -62,14 +62,15 @@ register(class ExampleComponent extends Component {
`;
});
```

[👉 View on codepen.io](https://codepen.io/okku/pen/MWKXMVK?editors=1010)

The library figures out what the appropriate DOM operation for each slot is from the location of the slots and binds those as callbacks to each reactive item it receives. Non-reactive slots are not bound; they are simply stringified and inserted in. There is no vDOM and no diffing or reconciliation. When a reactive item is updated, the changes will automatically propagate correctly to each dependent reactive item in the chain. This means that performance of updates scales with the complexity of the update (how many things need to be rerendered because of the update) instead of the total complexity of the application (like you would have with vDOM based solutions). Parsed HTML templates are cached in a WeakMap, so rendering multiple elements with the same template is quick after the first render.

You can also make arrays reactive. ReactiveArrays will behave generally akin to normal arrays, except that they will give you reactive properties instead of normal ones. You can manipulate the array like you would normal arrays and the DOM and other dependents will update with it; forget immutability! Here's an example of using a reactive array:

```js
import { xml, reactive } from "https://code.okku.dev/destiny-ui/0.4.1/dist/mod.js";
import { xml, reactive } from "https://code.okku.dev/destiny-ui/0.5.1/dist/mod.js";

const thingsILike = reactive(["cats", "JavaScript", "sleep"]);

Expand All @@ -88,6 +89,7 @@ setTimeout(() => {
thingsILike[1] = "TypeScript";
}, 3e3);
```

[👉 View on codepen.io](https://codepen.io/okku/pen/wvMXLpZ?editors=0010)

## Docs
Expand Down

0 comments on commit 18773db

Please sign in to comment.