Skip to content
This repository has been archived by the owner on Mar 8, 2020. It is now read-only.

Commit

Permalink
major updates for 0.11.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@ryansolid
ryansolid committed Jul 18, 2019
1 parent ca75070 commit 42b8cd9
Show file tree
Hide file tree
Showing 18 changed files with 390 additions and 792 deletions.
111 changes: 14 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ This package is a JSX compiler built for [DOM Expressions](https://github.com/ry

## Features

This plugin treats all lowercase tags as html elements and mixed cased tags as Custom Functions. This enables breaking up your view into functional components. This library supports Web Component Custom Elements spec. Support for common camelcase event handlers like React, dom safe attributes like class and for, a simple ref property, and parsing of objects for style, and classList properties.
This plugin treats all lowercase tags as html elements and mixed cased tags as Custom Functions. This enables breaking up your view into components. This library supports Web Component Custom Elements spec. Support for common camelcase event handlers like React, dom safe attributes like class and for, a simple ref property, and parsing of objects for style, and classList properties.

In general JSX Attribute Expressions are treated as properties by default, with exception of hyphenated(-) ones that will always be set as attributes on the DOM element. Plain string attributes(Non expression, no {}) will be treated as attributes.

Expand Down Expand Up @@ -39,7 +39,7 @@ import { insert as _$insert } from "dom";
import { wrap as _$wrap } from "dom";

const _tmpl$ = document.createElement("template");
_tmpl$.innerHTML = "<tr><td class='col-md-1'></td><td class='col-md-4'><a></a></td><td class='col-md-1'><a><span class='glyphicon glyphicon-remove' aria-hidden='true'></span></a></td><td class='col-md-6'></td></tr>";
_tmpl$.innerHTML = `<tr><td class="col-md-1"></td><td class="col-md-4"><a></a></td><td class="col-md-1"><a><span class="glyphicon glyphicon-remove" aria-hidden="true"></span></a></td><td class="col-md-6"></td></tr>`;

const view = ({ item }) =>
function () {
Expand Down Expand Up @@ -73,7 +73,13 @@ The name of the runtime module to import the methods from.
Boolean to indicate whether to enable automatic event delegation on camelCase.

### contextToCustomElements
Boeolean Indicates whether to set current render context on Custom Elements and slots. Useful for seemless Context API with Web Components.
Boolean indicates whether to set current render context on Custom Elements and slots. Useful for seemless Context API with Web Components.

### alwaysCreateComponents
Always use createComponent method instead of just calling the function. Needed to support class components.

### builtIns
Array of Component exports from module, that aren't included by default with the library. This plugin will automatically import them if it comes across them in the JSX.

## Special Binding

Expand All @@ -83,7 +89,7 @@ This binding will assign the variable you pass to it with the DOM element.

### forwardRef

This binding takes a props.ref for Function Components and forwards a Real DOM reference.
This binding takes a function callback and calls it with the ref. Useful for moving refs out Components or doing Custom Bindings.

```jsx
const Child = props => <div forwardRef={props.ref} />
Expand All @@ -100,23 +106,15 @@ These will be treated as event handlers expecting a function. All lowercase are

```jsx
<ul>
<$ each={list}>{ item => <li model={item.id} onClick={handler} /> }</$>
{( list().map(item => <li model={item.id} onClick={handler} />) )}
</ul>
```
This delegation solution works with Web Components and the Shadow DOM as well if the events are composed. That limits the list to custom events and most UA UI events like onClick, onKeyUp, onKeyDown, onDblClick, onInput, onMouseDown, onMouseUp, etc..

Important:
* To allow for casing to work all custom events should follow the all lowercase convention of native events. If you want to use different event convention (or use Level 3 Events "addEventListener") use the events binding.

* Event delegates aren't cleaned up automatically off Document. If you will be completely unmounting the library and wish to remove the handlers from the current page use r.clearDelegatedEvents.

### $____

Custom directives are written with a $ prefix. Their signature is:
```js
function(element, valueAccessor) {}
```
where valueAccessor is function wrapping the expression.
* Event delegates aren't cleaned up automatically off Document. If you will be completely unmounting the library and wish to remove the handlers from the current page use `clearDelegatedEvents`.

### classList

Expand Down Expand Up @@ -158,90 +156,9 @@ const MyComp = props => (

Components may have children. This is available as props.children. It will either be the value of a single expression child or it will be a DOM node(Fragment in case of multi-children) which can be rendered. Children are always evaluated lazily upon access (like dynamic properties).

## Control Flow

Loops and conditionals are handled by a special JSX tag `<$></$>`. The reason to use a tag instead of just data.map comes from the fact that it isn't just a map function in fine grain. It requires creating nested contexts and memoizing values. Even with custom methods the injection can never be as optimized as giving a special helper and I found I was re-writing pretty much identical code in all implementations. Currently there is support for 6 props on this component 'each', 'when', 'switch', 'provide', 'suspend', and 'portal' where the argument is the list to iterate or the condition. The Child is a function (render prop). For each it passes the item and the index to the function, and for when it passes the evaluated value.

```jsx
<ul>
<$ each={ state.users }>{
user => <li>
<div>{( user.firstName )}</div>
<$ when={ user.stars > 100 }>{
() => <div>Verified</div>
}</$>
</li>
}</$>
</ul>
```
Often for when there is no need for the argument and it can be skipped if desired using direct descendants. Since this is parsed at compile time there is no concern about the inner code running if the outer condition is not met.

```jsx
<$ when={ todos.length > 0 }>
<span>{( todos.length )}</span>
<button onClick={ removeCompleted }>Clear Completed</button>
</$>
```
Sometimes you want mutually exclusive options. Switch will evaluate each child when in succession until it hits the first truthy value.

```jsx
<$ switch fallback={<div>Route not Found</div>}>
<$ when={state.route === 'home'}><Home /></$>
<$ when={state.route === 'profile'}><Profile /></$>
<$ when={state.route === 'settings'}><Settings /></$>
</$>
```

Provide(Experimental) is used with a Context API to allow for hierarchically resolved dependency injection. The value provided will be either passed to an initializer function defined or will be the provided context. Opt in for the specific library runtime.

```jsx
<$ provide={ ThemeContext } value= { 'dark' }>
<ThemedComponent />
</$>
```
Suspend(Experimental) works almost the opposite of when where a truthy value will put the child in suspense. It differs from when in that instead of not rendering the child content it attaches it to a foreign document(important to fire connectedCallbacks on Web Components). This is useful if you still want load child components but don't wish to attach them to the current DOM until your are ready and display some fallback content instead. Useful for upstream handling of loading mechanisms when fetching data. It either takes a specific boolean accessor or uses a defined Suspense Context provided by the library.

```jsx
<$ suspend={ state.loading } fallback={<div>Loading...</div>}>
<MyComp query={( state.query )} onLoaded={() => setState({ loading: false })} />
</$>
```
Portal(Experimental) renders to a different than the current rendering tree. This is useful for handling modals. By default it will create a div under document.body but the target can be set by passing an argument. To support isolated styles there is an option to useShadow to stick the portal in an isolated ShadowRoot.

```jsx
<$ portal>
<MyModal>
<h1>Header</h1>
<p>Lorem ipsum ...</p>
</MyModal>
</$>
```

Control flow also has some additional options that can be passed as attributes.

### afterRender
Pass in a function that will be called after each update with the first element and next sibling of the inserted nodes. Useful for postprocessing nodes on mass. Like a batch ref.
Supported by: each, when

### fallback
If the condition is falsy this fallback content will rendered instead.
Supported by: each, when, suspend

### useShadow
Uses a Shadow Root for portals.
Supported by: portal

### value
Sets initialization value for provide control flow.
Supported by: provide

```jsx
<$ each={ todos } fallback={<span>Loading...</span>}>{ todo =>
<div>{todo.title}</div>
}</$>
```
## Fragments

This plugin also supports JSX Fragments with `<></>` notation. This is the prefered way to add multi-node roots explicit arrays tend to create more HTML string templates than necessary.
This plugin also supports JSX Fragments with `<></>` notation. However they use a Persistent Fragment based on [Document Persistent Fragment](https://github.com/WebReflection/document-persistent-fragment). Look at your specific libraries documentation to learn how to include the polyfill.

## Work in Progress

Expand Down
Loading

0 comments on commit 42b8cd9

Please sign in to comment.