@soil/web

Soil

A foundational library to help building long-lasting web applications.

Motivation

The pace with which the web ecosystem evolves is unthinkably fast. At the same time, trendy web frameworks often offer poor interoperability with standard technologies, and the technical burden they introduce tends to be significant and clearer than the benefits. Projects based on them are left with the choice of deprecation and long-term unmaintainability, or the expense of unreasonable amounts of resources to match the community's speed.

Soil aims at putting together a minimal set of basic elements that embrace today's web standards and help you in developing high-quality, enduring applications, while being competitive with popular frameworks in areas such as reliability, testability, reusability, development experience and performance.

Basics

Soil encourages an architecture around components, conceptually similar to the Web Components' proposal. Components are responsible for rendering parts of UI and controlling the user interaction with them.

They create and manipulate HTML elements dynamically, with the help of type-safe functions with a one-to-one correspondence with standard HTML elements, which provides a look-and-feel similar to regular HTML.

import {h, extend} from '@soil/web'

const counter = (input: {value?: number} = {}) => {

    const $count = h.span({})

    const $counter = h.div({}, [
        h.button({onclick: () => api.value = api.value - 1}, '-'),
        $count,
        h.button({onclick: () => api.value = api.value + 1}, '+')
    ])

    const state = {
        value: input.value || 0
    }

    const api = {
        get value() {
            return state.value
        },
        set value(v: number) {
            state.value = v
            $count.textContent = '' + v
        }
    }

    api.value = api.value

    return extend($counter, api)
}

Custom components can be used in a way similar to native ones.

import {counter} from './counter'

const $counter = counter({value: 0})
$counter.value++

document.body.appendChild($counter)

Purely presentational components have no dependencies, but container components may have them, including other components. For this, pure dependency injection is recommended, which can be achieved through default parameters.

const counterContainer = (counterService = new CounterService) => (input = {}) => {
    // ...
}

To get more familiar with the ideas presented above, head to the documentation, check out the examples, or dive directly into the source code.

Installation

The package is available at npm, so it can be installed by running:

npm i -S @soil/web # AKA npm install --save @soil/web

Compatibility

Browser support comes down to the individual functions used internally by Soil. The potentially problematic ones are summarized below. Polyfills are offered by MDN for most of them.

Function	Source files	Chrome	Edge	Firefox	IE	Opera	Safari
Array.from()	fix/autofocus.ts	45	(Yes)	32	No	(Yes)	9
Object.setPrototypeOf()	core/assert.ts	34	(Yes)	31	11	(Yes)	9
document.querySelectorAll()	fix/autofocus.ts	1	(Yes)	3.5	9	10	3.2
Object.defineProperty()	core/extend.ts	5	(Yes)	4	9	11.6	5.1
Array.prototype.forEach()	core/Channel.ts, dom/h.ts, dom/s.ts	(Yes)	(Yes)	1.5	9	(Yes)	(Yes)
Array.prototype.filter()	core/Channel.ts, fix/autofocus.ts	(Yes)	(Yes)	1.5	9	(Yes)	(Yes)
Window.getComputedStyle()	fix/autofocus.ts	(Yes)	(Yes)	(Yes)	9	(Yes)	(Yes)

Contributions

Feel free and encouraged to open new discussions on any non-technical topic that may help maturing Soil. For technical contributions, pull requests are also welcomed.

License

The Soil project is licensed under the GNU Affero General Public License.