sprae 7.0.0 → 8.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprae",
   "description": "DOM microhydration.",
-  "version": "7.0.0",
+  "version": "8.0.1",
   "main": "src/index.js",
   "module": "src/index.js",
   "type": "module",
@@ -13,8 +13,7 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.5.0",
-    "swapdom": "^1.1.1"
+    "@preact/signals-core": "^1.5.0"
   },
   "devDependencies": {
     "@preact/signals": "^1.1.3",
@@ -22,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": {
@@ -54,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 enhanced 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
 
@@ -40,8 +43,27 @@ To init manually as module, import [`sprae.js`](./sprae.js):
 ```
 
 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.
+
+## 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>
@@ -65,14 +87,11 @@ Multiply element. `index` value starts from 1.
 <!-- Cases -->
 <li :each="item, idx in list" />
 <li :each="val, key in obj" />
-<li :each="idx0, idx in number" />
+<li :each="idx in number" />
 
 <!-- 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"`
@@ -94,8 +113,8 @@ Set class value from either a string, array or object.
 <!-- extends existing class as "foo bar" -->
 <div class="foo" :class="`bar`"></div>
 
-<!-- object with values -->
-<div :class="{foo:true, bar: false}"></div>
+<!-- clsx: object / list -->
+<div :class="[foo && 'foo', {bar: bar}]"></div>
 ```
 
 #### `:style="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,10 +274,17 @@ 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
@@ -282,6 +311,7 @@ cd ..
 cd webdriver-ts
 npm run results
 ```
+</details>
 
 ## Examples
 
@@ -289,14 +319,13 @@ npm run results
 * 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
 
 * [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.