sprae 6.1.1 → 7.0.0

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "sprae",
   "description": "DOM microhydration.",
-  "version": "6.1.1",
+  "version": "7.0.0",
   "main": "src/index.js",
   "module": "src/index.js",
   "type": "module",
+  "files": [
+    "sprae.auto.js",
+    "sprae.auto.min.js",
+    "sprae.js",
+    "sprae.min.js",
+    "src"
+  ],
   "dependencies": {
+    "@preact/signals-core": "^1.5.0",
     "swapdom": "^1.1.1"
   },
   "devDependencies": {

package/readme.md

@@ -2,7 +2,7 @@
 
 > DOM tree hydration with reactivity.
 
-_Sprae_ is progressive enhancement framework, a tiny essential alternative to [alpine](https://github.com/alpinejs/alpine), [petite-vue](https://github.com/vuejs/petite-vue) or [template-parts](https://github.com/github/template-parts) with improved ergonomics[*](#justification--alternatives). It enables simple markup logic without external scripts. Perfect for small websites, prototypes or UI logic.
+_Sprae_ is progressive enhancement framework, a tiny essential alternative to [alpine](https://github.com/alpinejs/alpine), [petite-vue](https://github.com/vuejs/petite-vue) or [template-parts](https://github.com/github/template-parts) with enhanced ergonomics[*](#justification--alternatives). It enables simple markup logic without external scripts. Perfect for small websites, prototypes or UI logic.
 
 ## Use
 
@@ -12,9 +12,13 @@ To autoinit document, include [`sprae.auto.js`](./sprae.auto.js):
 
 ```html
 <!-- <script src="https://cdn.jsdelivr.net/npm/sprae/sprae.auto.js" defer></script> -->
-<script src="./path/to/sprae.auto.js" defer></script>
+<script defer src="./path/to/sprae.auto.js"></script>
 
-<a :each="id in ['a','b','c']" :href="`#${id}`" :text="id"></a>
+<ul>
+  <li :each="item in ['apple', 'bananas', 'citrus']"">
+    <a :href="`#${item}`" :text="item" />
+  </li>
+</ul>
 ```
 
 ### Manual init
@@ -23,19 +27,21 @@ To init manually as module, import [`sprae.js`](./sprae.js):
 
 ```html
 <div id="container" :if="user">
-  Logged in as <span :text="user.displayName">Guest.</span>
+  Logged in as <span :text="user.name">Guest.</span>
 </div>
 
 <script type="module">
   // import sprae from 'https://cdn.jsdelivr.net/npm/sprae/sprae.js';
   import sprae from './path/to/sprae.js';
 
-  const state = sprae(container, { user: { displayName: 'Dmitry Ivanov' } });
-  state.user.displayName = 'dy'; // updates DOM
+  const state = sprae(container, { user: { name: 'Dmitry Ivanov' } });
+  state.user.name = 'dy'; // updates DOM
 </script>
 ```
 
-Sprae evaluates `:`-attributes and evaporates them. Reactive `state` reflects current values, can be updated directly (batches multiple updates internally for efficiency).
+Sprae evaluates `:`-attributes and evaporates them.<br/>
+Sprae creates reactive state representing current values in rendered DOM.<br/>
+It is based on [preact signals](https://github.com/preactjs/signals) and can take them as inputs.
 
 ## Attributes
 
@@ -79,14 +85,14 @@ Welcome, <span :text="user.name">Guest</span>.
 
 #### `:class="value"`
 
-Set class value from either string, array or object. Extends existing `class` attribute, if any.
+Set class value from either a string, array or object.
 
 ```html
+<!-- set from string -->
 <div :class="`foo ${bar}`"></div>
 
-<!-- extend existing class -->
+<!-- extends existing class as "foo bar" -->
 <div class="foo" :class="`bar`"></div>
-<!-- <div class="foo bar"></div> -->
 
 <!-- object with values -->
 <div :class="{foo:true, bar: false}"></div>
@@ -94,11 +100,16 @@ Set class value from either string, array or object. Extends existing `class` at
 
 #### `:style="value"`
 
-Set style value from object or a string. Extends existing `style` attribute, if any.
+Set style value from an object or a string. Extends existing `style` attribute, if any.
 
 ```html
-<div :style="foo: bar"></div>
+<!-- from string -->
+<div :style="`foo: ${bar}`"></div>
+
+<!-- from object -->
 <div :style="{foo: 'bar'}"></div>
+
+<!-- set CSS variable -->
 <div :style="{'--baz': qux}"></div>
 ```
 
@@ -107,9 +118,11 @@ Set style value from object or a string. Extends existing `style` attribute, if
 Set value of an input, textarea or select. Takes handle of `checked` and `selected` attributes.
 
 ```html
-<input :value="text" />
-<textarea :value="text" />
+<!-- set from value -->
+<input :value="value" />
+<textarea :value="value" />
 
+<!-- selects right option -->
 <select :value="selected">
   <option :each="i in 5" :value="i" :text="i"></option>
 </select>
@@ -132,15 +145,30 @@ Define or extend data scope for a subtree.
 </x>
 ```
 
-#### `:render="ref"`
+#### `:<prop>="value?"`
 
-Include template as element content.
+Set any attribute value or run an effect.
 
 ```html
-<template :ref="foo"><span :text="foo"></span></template>
+<!-- Single property -->
+<label :for="name" :text="name" />
 
-<div :render="foo" :with="{foo:'bar'}">...inserted here...</div>
-<div :render="foo" :with="{foo:'baz'}">...inserted here...</div>
+<!-- Multiple properties -->
+<input :id:name="name" />
+
+<!-- Effect - returns undefined, triggers any time bar changes -->
+<div :fx="void bar()" ></div>
+
+<!-- Raw event listener (see events) -->
+<div :onclick="e=>e.preventDefault()"></div>
+```
+
+#### `:="props?"`
+
+Spread multiple attibures.
+
+```html
+<input :="{ id: name, name, type:'text', value }" />
 ```
 
 #### `:ref="id"`
@@ -160,30 +188,17 @@ Expose element to current data scope with the `id`:
 </ul>
 ```
 
-#### `:="props?"`
-
-Spread multiple attibures.
-
-```html
-<input :="{ id: name, name, type:'text', value }" />
-```
-
-#### `:<prop>="value?"`
+#### `:render="ref"`
 
-Set any attribute value or run an effect.
+Include template as element content.
 
 ```html
-<!-- Single property -->
-<label :for="name" :text="name" />
-
-<!-- Multiple properties -->
-<input :id:name="name" />
-
-<!-- Effect - returns undefined, triggers any time bar changes -->
-<div :fx="void bar()" ></div>
+<!-- assign template element to foo variable -->
+<template :ref="foo"><span :text="foo"></span></template>
 
-<!-- Raw event listener (see events) -->
-<div :onclick="e=>e.preventDefault()"></div>
+<!-- rended template as content -->
+<div :render="foo" :with="{foo:'bar'}">...inserted here...</div>
+<div :render="foo" :with="{foo:'baz'}">...inserted here...</div>
 ```
 
 
@@ -191,7 +206,7 @@ Set any attribute value or run an effect.
 
 #### `@<event>="handle"`, `@<foo>@<bar>.<baz>="handle"`
 
-Attach event(s) listener with possible modifiers. `event` variable holds current event.
+Attach event(s) listener with possible modifiers. `event` variable holds current event. Allows async handlers.
 
 ```html
 <!-- Single event -->
@@ -224,7 +239,7 @@ Expressions are sandboxed, ie. don't access global/window scope by default (sinc
 <!-- scrollY is undefined -->
 ```
 
-Default sandbox provides: _window_, _document_, _console_, _history_, _location_, _Array_, _Object_, _Number_, _String_, _Boolean_, _Date_, _Set_, _Map_.
+Default sandbox provides: _window_, _document_, _console_, _history_, _location_, _Date_, _Set_, _Map_.
 
 Sandbox can be extended as `Object.assign(sprae.globals, { BigInt })`.
 
@@ -237,13 +252,45 @@ To avoid _flash of unstyled content_, you can hide sprae attribute or add a cust
 <style>[:each],[:hidden] {visibility: hidden}</style>
 ```
 
+## Benchmark
+
+Done via [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark).
+
+```sh
+# prerequisite
+npm ci
+npm run install-server
+npm start
+
+# build
+cd frameworks/keyed/sprae
+npm ci
+npm run build-prod
+
+# bench
+cd ../../..
+cd webdriver-ts
+npm ci
+npm run compile
+npm run bench keyed/sprae
+
+# show results
+cd ..
+cd webdriver-ts-results
+npm ci
+cd ..
+cd webdriver-ts
+npm run results
+```
+
 ## Examples
 
 * TODO MVC: [demo](https://dy.github.io/sprae/examples/todomvc), [code](https://github.com/dy/sprae/blob/main/examples/todomvc.html)
 * Wavearea: [demo](https://dy.github.io/wavearea?src=//cdn.freesound.org/previews/586/586281_2332564-lq.mp3), [code](https://github.com/dy/wavearea)
 * Prostogreen [demo](http://web-being.org/prostogreen/), [code](https://github.com/web-being/prostogreen/)
 
-## Justification & alternatives
+
+## Justification
 
 * [Template-parts](https://github.com/dy/template-parts) / [templize](https://github.com/dy/templize) is progressive, but is stuck with native HTML quirks ([parsing table](https://github.com/github/template-parts/issues/24), [SVG attributes](https://github.com/github/template-parts/issues/25), [liquid syntax](https://shopify.github.io/liquid/tags/template/#raw) conflict etc). Also ergonomics of `attr="{{}}"` is inferior to `:attr=""` since it creates flash of uninitialized values. Also it's just nice to keep `{{}}` generic, regardless of markup, and attributes as part of markup.
 * [Alpine](https://github.com/alpinejs/alpine) / [vue](https://github.com/vuejs/petite-vue) / [lit](https://github.com/lit/lit/tree/main/packages/lit-html) escape native HTML quirks, but the syntax space (`:attr`, `v-*`,`x-*`, `l-*` `@evt`, `{{}}`) is too broad, as well as functionality. Perfection is when there's nothing to take away, not add (c). Also they tend to [self-encapsulate](https://github.com/alpinejs/alpine/discussions/3223) making interop hard, invent own tooling or complex reactivity.
@@ -264,8 +311,8 @@ It is reminiscent of [XSLT](https://www.w3schools.com/xml/xsl_intro.asp), consid
 ## Alternatives
 
 * [Alpine](https://github.com/alpinejs/alpine)
-* [Lucia](https://github.com/aidenybai/lucia)
+* ~~[Lucia](https://github.com/aidenybai/lucia)~~ deprecated
 * [Petite-vue](https://github.com/vuejs/petite-vue)
-* [Reken](https://github.com/hbroek/reken)
+* [nuejs](https://github.com/nuejs/nuejs)
 
 <p align="center"><a href="https://github.com/krsnzd/license/">🕉</a></p>