sprae 6.1.2 → 8.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprae",
   "description": "DOM microhydration.",
-  "version": "6.1.2",
+  "version": "8.0.0",
   "main": "src/index.js",
   "module": "src/index.js",
   "type": "module",
@@ -13,7 +13,7 @@
     "src"
   ],
   "dependencies": {
-    "swapdom": "^1.1.1"
+    "@preact/signals-core": "^1.5.0"
   },
   "devDependencies": {
     "@preact/signals": "^1.1.3",
@@ -21,11 +21,9 @@
     "esbuild": "^0.15.14",
     "hyperf": "^1.6.2",
     "jsdom": "^21.1.0",
-    "signal-struct": "^1.10.0",
     "terser": "^5.15.1",
     "tst": "^7.1.1",
     "usignal": "^0.8.9",
-    "value-ref": "^2.1.0",
     "wait-please": "^3.1.0"
   },
   "scripts": {
@@ -53,7 +51,7 @@
     "directives",
     "templating"
   ],
-  "author": "Dmitry Ivanov <df.creative@gmail.com>",
+  "author": "Dmitry Iv <df.creative@gmail.com>",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/dy/sprae/issues"

package/readme.md

@@ -2,9 +2,12 @@
 
 > 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 compact ergonomic[*](#justification--alternatives) progressive enhancement framework.<br/>
+It provides reactive `:`-attributes that enable simple markup logic without need for complex scripts.<br/>
+Perfect for small-scale websites, prototypes or UI logic.<br/>
+It is tiny and performant 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).
 
-## Use
+## Usage
 
 ### Autoinit
 
@@ -12,7 +15,7 @@ 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>
 
 <ul>
   <li :each="item in ['apple', 'bananas', 'citrus']"">
@@ -40,8 +43,27 @@ To init manually as module, import [`sprae.js`](./sprae.js):
 ```
 
 Sprae evaluates `:`-attributes and evaporates them.<br/>
-Reactive `state` reflects current values, can be updated directly.<br/>
-It batches multiple updates internally for efficiency.
+
+## State
+
+Sprae creates reactive state that mirrors current DOM values.<br/>
+It is based on [signals](https://github.com/preactjs/signals) and can take them as inputs.
+
+```js
+const version = signal('alpha')
+
+// Sprae container with initial state values
+const state = sprae(container, { foo: 'bar', version })
+
+// Modify state property 'foo', triggering a DOM update
+state.foo = 'baz'
+
+// Update the version signal, which also triggers a DOM refresh
+version.value = 'beta'
+
+// For batch update, re-sprae with new state values
+sprae(container, { foo: 'qux', version: 'gamma' })
+```
 
 ## Attributes
 
@@ -57,7 +79,7 @@ Control flow of elements.
 
 #### `:each="item, index in items"`
 
-Multiply element. `index` value starts from 1.
+Multiply element.
 
 ```html
 <ul><li :each="item in items" :text="item"></ul>
@@ -70,9 +92,6 @@ Multiply element. `index` value starts from 1.
 <!-- Loop by condition -->
 <li :if="items" :each="item in items" :text="item" />
 <li :else>Empty list</li>
-
-<!-- Key items to reuse elements -->
-<li :each="item in items" :key="item.id" :text="item.value" />
 ```
 
 #### `:text="value"`
@@ -239,7 +258,10 @@ Expressions are sandboxed, ie. don't access global/window scope by default (sinc
 <!-- scrollY is undefined -->
 ```
 
-Default sandbox provides: _window_, _document_, _console_, _history_, _location_, _Date_, _Set_, _Map_.
+Default sandbox provides most popular global objects: _Array_, _Object_, _Number_, _String_, _Boolean_, _Date_,
+  _console_, _window_, _document_, _history_, _navigator_, _location_, _screen_, _localStorage_, _sessionStorage_,
+  _alert_, _prompt_, _confirm_, _fetch_, _performance_,
+  _setTimeout_, _setInterval_, _requestAnimationFrame_.
 
 Sandbox can be extended as `Object.assign(sprae.globals, { BigInt })`.
 
@@ -252,19 +274,58 @@ To avoid _flash of unstyled content_, you can hide sprae attribute or add a cust
 <style>[:each],[:hidden] {visibility: hidden}</style>
 ```
 
+## Dispose
+
+To destroy state and detach sprae handlers, call `element[Symbol.dispose]()`.
+
+## Benchmark
+
+Done via [js-framework-benchmark](https://github.com/krausest/js-framework-benchmark).
+
+<details>
+<summary>How to run</summary>
+
+```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
+```
+</details>
+
 ## 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.
-* React/[preact](https://ghub.io/preact) does the job wiring up JS to HTML, but with an extreme of migrating HTML to JSX and enforcing SPA, which is not organic for HTML. Also it doesn't support reactive fields (needs render call).
+* React / [preact](https://ghub.io/preact) does the job wiring up JS to HTML, but with an extreme of migrating HTML to JSX and enforcing SPA, which is not organic for HTML. Also it doesn't support reactive fields (needs render call).
 
-_Sprae_ takes idea of _templize directives_/_alpine_/_vue_ attrs and builds upon <del>[_@preact/signals_](https://ghub.io/@preact/signals)</del> simple reactive state.
+_Sprae_ takes idea of _templize_ / _alpine_ / _vue_ attributes and builds simple reactive state based on [_@preact/signals_](https://ghub.io/@preact/signals).
 
 * It doesn't break or modify static html markup.
 * It falls back to element content if uninitialized.
@@ -281,5 +342,6 @@ It is reminiscent of [XSLT](https://www.w3schools.com/xml/xsl_intro.asp), consid
 * [Alpine](https://github.com/alpinejs/alpine)
 * ~~[Lucia](https://github.com/aidenybai/lucia)~~ deprecated
 * [Petite-vue](https://github.com/vuejs/petite-vue)
+* [nuejs](https://github.com/nuejs/nuejs)
 
 <p align="center"><a href="https://github.com/krsnzd/license/">🕉</a></p>