sprae 11.5.7 → 12.0.0

package/readme.md

@@ -1,101 +1,73 @@
 # ∴ spræ [![tests](https://github.com/dy/sprae/actions/workflows/node.js.yml/badge.svg)](https://github.com/dy/sprae/actions/workflows/node.js.yml) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/sprae)](https://bundlephobia.com/package/sprae) [![npm](https://img.shields.io/npm/v/sprae?color=orange)](https://www.npmjs.com/package/sprae)
 
-> DOM tree microhydration
+Simple progressive enhancement for DOM or JSX.<br/>
 
-_Sprae_ is open & minimalistic progressive enhancement framework with _preact-signals_ reactivity.<br/>
-Perfect for small websites, static pages, prototypes, lightweight UI or nextjs / SSR (see [JSX](#jsx)).<br/>
-A light and fast alternative to _alpine_, _petite-vue_, _lucia_ etc (see [why](#justification)).
+<!-- [Usage](#usage) · [Directives](#directives) · [Modifiers](#modifiers) · [Store](#store) · [Signals](#signals) · [Evaluator](#evaluator) · [Start](#autoinit) · [JSX](#jsx) · [Build](#custom-build) · [Hints](#hints) · [Examples](#examples) -->
 
 ## Usage
 
 ```html
-<div id="container" :if="user">
-  Hello <span :text="user.name">there</span>.
+<div id="counter" :scope="{ count: 0 }">
+  <p :text="`Clicked ${count} times`"></p>
+  <button :onclick="count++">Click me</button>
 </div>
 
-<script type="module">
-  import sprae from './sprae.js' // https://unpkg.com/sprae/dist/sprae.min.js
-
-  // init
-  const container = document.querySelector('#container');
-  const state = sprae(container, { user: { name: 'friend' } })
-
-  // update
-  state.user.name = 'love'
-</script>
+<script src="https://cdn.jsdelivr.net/npm/sprae@12.x.x" start></script>
 ```
 
-Sprae evaluates `:`-directives and evaporates them, returning reactive state for updates.
-
-### UMD
+Sprae evaluates `:`-directives enabling reactivity.
 
-`sprae.umd` enables sprae via CDN, CJS, AMD etc.
-
-```html
-<script src="https://unpkg.com/sprae/dist/sprae.umd"></script>
-<script>
-  window.sprae; // global standalone
-</script>
-```
-
-### Autoinit
-
-`sprae.auto` autoinits sprae on document body.
-
-```html
-<!-- Optional attr `prefix` (by default ':'). -->
-<script src="https://unpkg.com/sprae/dist/sprae.auto" prefix="js-"></script>
-```
-
-
-## Directives
+<!--
+## Concepts
 
-#### `:if="condition"`, `:else`
+**Directives** are `:` prefixed attributes that evaluate JavaScript expressions:
+`<div :text="message"></div>`
 
-Control flow of elements.
+**Reactivity** happens automatically through signals—just mutate values:
+`<button :onclick="count++">` updates `<span :text="count">`
 
-```html
-<span :if="foo">foo</span>
-<span :else :if="bar">bar</span>
-<span :else>baz</span>
+**Scope** creates a state container for a subtree:
+`<div :scope="{ user: 'Alice' }">` makes `user` available to children
 
-<!-- fragment -->
-<template :if="foo">foo <span>bar</span> baz</template>
-```
+**Effects** run side effects:
+`:fx="console.log(count)"` logs when `count` changes
 
-#### `:each="item, index? in items"`
+**Modifiers** adjust directive behavior:
+`:oninput.debounce-200` delays handler by 200ms
+-->
 
-Multiply element.
+<!--
+### Flavors
 
-```html
-<ul><li :each="item in items" :text="item" /></ul>
+* [sprae.js](dist/sprae.js) – ESM.
+* [sprae.umd.js](dist/sprae.umd.js) – CJS / UMD / standalone with autoinit.
+* [sprae.micro.js](dist/sprae.micro.js) – <2.5kb [micro version](#micro).
+-->
+<!-- * sprae.async.js - sprae with async events -->
+<!-- * sprae.alpine.js - alpine sprae, drop-in alpinejs replacement -->
+<!-- * sprae.vue.js - vue sprae, drop-in petite-vue replacement -->
+<!-- * sprae.preact.js - sprae with preact-signals -->
 
-<!-- cases -->
-<li :each="item, idx in array" />
-<li :each="value, key in object" />
-<li :each="count, idx in number" />
 
-<!-- fragment -->
-<template :each="item in items">
-  <dt :text="item.term"/>
-  <dd :text="item.definition"/>
-</template>
-```
+## Directives
 
-#### `:text="value"`
+#### `:text`
 
-Set text content of an element.
+Set text content.
 
 ```html
 Welcome, <span :text="user.name">Guest</span>.
 
 <!-- fragment -->
 Welcome, <template :text="user.name"><template>.
+
+<!-- function -->
+<span :text="val => val + text"></span>
 ```
 
-#### `:class="value"`
+#### `:class`
 
-Set class value.
+Set className.
 
 ```html
 <div :class="foo"></div>
@@ -105,136 +77,181 @@ Set class value.
 
 <!-- array/object, a-la clsx -->
 <div :class="['foo', bar && 'bar', { baz }]"></div>
+
+<!-- function -->
+<div :class="str => [str, 'active']"></div>
 ```
 
-#### `:style="value"`
+#### `:style`
 
-Set style value.
+Set style.
 
 ```html
-<span style="'display: inline-block'"></span>
+<span :style="'display: inline-block'"></span>
 
 <!-- extends static style -->
 <div style="foo: bar" :style="'bar-baz: qux'">
 
 <!-- object -->
-<div :style="{barBaz: 'qux'}"></div>
+<div :style="{bar: 'baz', '--qux': 'quv'}"></div>
 
-<!-- set CSS variable -->
-<div :style="{'--bar-baz': qux}"></div>
+<!-- function -->
+<div :style="obj => ({'--bar': baz})"></div>
 ```
 
-#### `:value="value"`
+#### `:value`
 
-Set value to/from an input, textarea or select (like alpinejs `x-model`).
+Bind input, textarea or select value.
 
 ```html
 <input :value="value" />
 <textarea :value="value" />
 
-<!-- selects right option & handles selected attr -->
+<!-- handles option & selected attr -->
 <select :value="selected">
   <option :each="i in 5" :value="i" :text="i"></option>
 </select>
 
-<!-- handles checked attr -->
+<!-- checked attr -->
 <input type="checkbox" :value="item.done" />
+
+<!-- function -->
+<input :value="value => value + str" />
 ```
 
-#### `:<prop>="value"`, `:="values"`
+#### `:<attr>`, `:`
 
 Set any attribute(s).
 
 ```html
 <label :for="name" :text="name" />
 
-<!-- multiple attributes -->
+<!-- multiple -->
 <input :id:name="name" />
 
-<!-- spread attributes -->
-<input :="{ id: name, name, type: 'text', value }" />
+<!-- function -->
+<div :hidden="hidden => !hidden"></div>
+
+<!-- spread -->
+<input :="{ id: name, name, type: 'text', value, ...props  }" />
+```
+
+#### `:if`, `:else`
+
+Control flow.
+
+```html
+<span :if="foo">foo</span>
+<span :else :if="bar">bar</span>
+<span :else>baz</span>
+
+<!-- fragment -->
+<template :if="foo">foo <span>bar</span> baz</template>
+
+<!-- function -->
+<span :if="active => test()"></span>
+```
+
+#### `:each`
+
+Multiply content.
+
+```html
+<ul><li :each="item in items" :text="item" /></ul>
+
+<!-- cases -->
+<li :each="item, idx? in array" />
+<li :each="value, key? in object" />
+<li :each="count, idx? in number" />
+<li :each="item, idx? in function" />
+
+<!-- fragment -->
+<template :each="item in items">
+  <dt :text="item.term"/>
+  <dd :text="item.definition"/>
+</template>
 ```
 
-#### `:with="values"`
+#### `:scope`
 
-Define values for a subtree.
+Define state container for a subtree.
 
 ```html
-<x :with="{ foo: 'bar' }">
-  <y :with="{ baz: 'qux' }" :text="foo + baz"></y>
+<!-- transparent -->
+<x :scope="{foo: 'foo'}">
+  <y :scope="{bar: 'bar'}" :text="foo + bar"></y>
 </x>
+
+<!-- define variables -->
+<x :scope="x=1, y=2" :text="x+y"></x>
+
+<!-- blank -->
+<x :scope :ref="id"></x>
+
+<!-- access to local scope instance -->
+<x :scope="scope => { scope.x = 'foo'; return scope }" :text="x"></x>
 ```
 
-#### `:fx="code"`
+#### `:fx`
 
-Run effect, not changing any attribute.
+Run effect.
 
 ```html
+<!-- inline -->
 <div :fx="a.value ? foo() : bar()" />
 
-<!-- cleanup function -->
-<div :fx="id = setInterval(tick, 1000), () => clearInterval(id)" />
+<!-- function / cleanup -->
+<div :fx="() => (id = setInterval(tick, 1000), () => clearInterval(id))" />
 ```
 
-#### `:ref="name"`, `:ref="el => (...)"`
+#### `:ref`
 
-Expose element in state with `name` or get reference to element.
+Expose an element in scope or get ref to the element.
 
 ```html
 <div :ref="card" :fx="handle(card)"></div>
 
+<!-- reference -->
+<div :ref="el => el.innerHTML = '...'"></div>
+
 <!-- local reference -->
-<li :each="item in items" :ref="li">
-  <input :onfocus..onblur="e => (li.classList.add('editing'), e => li.classList.remove('editing'))"/>
+<li :each="item in items" :scope :ref="li">
+  <input :onfocus="e => li.classList.add('editing')"/>
 </li>
 
-<!-- set innerHTML -->
-<div :ref="el => el.innerHTML = '...'"></div>
-
 <!-- mount / unmount -->
-<textarea :ref="el => (/* onmount */, () => (/* onunmount */))" :if="show"></textarea>
+<textarea :ref="el => {/* onmount */ return () => {/* onunmount */}}" :if="show"></textarea>
 ```
 
-#### `:on<event>="handler"`, `:on<in>..on<out>="handler"`
+#### `:on<event>`
 
-Attach event(s) listener with optional modifiers.
+Add event listener.
 
 ```html
-<input type="checkbox" :onchange="e => isChecked = e.target.value">
+<!-- inline -->
+<button :onclick="count++">Up</button>
+
+<!-- function -->
+<input type="checkbox" :onchange="event => isChecked = event.target.value">
 
-<!-- multiple events -->
-<input :value="text" :oninput:onchange="e => text = e.target.value">
+<!-- multiple -->
+<input :onvalue="text" :oninput:onchange="event => text = event.target.value">
 
-<!-- sequence of events -->
-<button :onfocus..onblur="e => (handleFocus(), e => handleBlur())">
+<!-- sequence -->
+<button :onfocus..onblur="evt => { handleFocus(); return evt => handleBlur()}">
 
 <!-- modifiers -->
-<button :onclick.throttle-500="handler">Not too often</button>
+<button :onclick.throttle-500="handle()">Not too often</button>
 ```
 
-##### Modifiers:
-
-* `.once`, `.passive`, `.capture` – listener [options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options).
-* `.prevent`, `.stop` (`.immediate`) – prevent default or stop (immediate) propagation.
-* `.window`, `.document`, `.parent`, `.outside`, `.self` – specify event target.
-* `.throttle-<ms>`, `.debounce-<ms>` – defer function call with one of the methods.
-* `.<key>` – filtered by [`event.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values):
-  * `.ctrl`, `.shift`, `.alt`, `.meta`, `.enter`, `.esc`, `.tab`, `.space` – direct key
-  * `.delete` – delete or backspace
-  * `.arrow` – up, right, down or left arrow
-  * `.digit` – 0-9
-  * `.letter` – A-Z, a-z or any [unicode letter](https://unicode.org/reports/tr18/#General_Category_Property)
-  * `.char` – any non-space character
-  * `.ctrl-<key>, .alt-<key>, .meta-<key>, .shift-<key>` – key combinations, eg. `.ctrl-alt-delete` or `.meta-x`.
-* `.*` – any other modifier has no effect, but allows binding multiple handlers to same event (like jQuery event classes).
-
+<!--
 #### `:data="values"`
 
 Set `data-*` attributes. CamelCase is converted to dash-case.
 
 ```html
 <input :data="{foo: 1, barBaz: true}" />
-<!-- <input data-foo="1" data-bar-baz /> -->
+<!-- <input data-foo="1" data-bar-baz />
 ```
 
 #### `:aria="values"`
@@ -251,8 +268,8 @@ Set `aria-*` attributes. Boolean values are stringified.
 }" />
 <!--
 <input role="combobox" aria-controls="joketypes" aria-autocomplete="list" aria-expanded="false" aria-active-option="item1" aria-activedescendant>
--->
 ```
+-->
 
 <!--
 #### `:onvisible..oninvisible="e => e => {}"`
@@ -275,110 +292,267 @@ Trigger when element is connected / disconnected from DOM.
 ```
 -->
 
+
+## Modifiers
+
+
+#### `.debounce-<ms|tick|frame|idle>?`
+
+Defer callback by ms, next tick/animation frame, or until idle. Defaults to 250ms.
+
+```html
+<!-- debounce keyboard input by 200ms -->
+<input :oninput.debounce-200="event => update(event)" />
+
+<!-- set class in the next tick -->
+<div :class.debounce-tick="{ active }">...</div>
+
+<!-- debounce resize to animation framerate -->
+<div :onresize.window.debounce-frame="updateSize()">...</div>
+
+<!-- batch logging when idle -->
+<div :fx.debounce-idle="sendAnalytics(batch)"></div>
+```
+
+#### `.throttle-<ms|tick|frame>?`
+
+Limit callback rate to interval in ms, tick or animation framerate. By default 250ms.
+
+```html
+<!-- throttle text update -->
+<div :text.throttle-100="text.length"></div>
+
+<!-- lock style update to animation framerate -->
+<div :onscroll.throttle-frame="progress = (scrollTop / scrollHeight) * 100"/>
+
+<!-- ensure separate stack for events -->
+<div :onmessage.window.throttle-tick="event => log(event)">...</div>
+```
+
+#### `.once`
+
+Call only once.
+
+```html
+<!-- run event callback only once -->
+<button :onclick.once="loadMoreData()">Start</button>
+
+<!-- run once on sprae init -->
+<div :fx.once="console.log('sprae init')">
+```
+
+#### `.window`, `.document`, `.parent`, `.outside`, `.self`  <kbd>events only</kbd>
+
+Specify event target.
+
+```html
+<!-- close dropdown when click outside -->
+<div :onclick.outside="closeMenu()" :class="{ open: isOpen }">Dropdown</div>
+
+<!-- interframe communication -->
+<div :onmessage.window="e => e.data.type === 'success' && complete()">...</div>
+```
+
+#### `.passive`, `.capture`  <kbd>events only</kbd>
+
+Event listener [options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options).
+
+```html
+<div :onscroll.passive="e => pos = e.scrollTop">Scroll me</div>
+
+<body :ontouchstart.capture="logTouch(e)"></body>
+```
+
+#### `.prevent`, `.stop`, `.stop-immediate`  <kbd>events only</kbd>
+
+Prevent default or stop (immediate) propagation.
+
+```html
+<!-- prevent default -->
+<a :onclick.prevent="navigate('/page')" href="/default">Go</a>
+
+<!-- stop immediate propagation -->
+<button :onclick.stop-immediate="criticalHandle()">Click</button>
+```
+
+#### `.<key>-<*>` <kbd>events only</kbd>
+
+Filter event by [`event.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) or combination:
+
+* `.ctrl`, `.shift`, `.alt`, `.meta`, `.enter`, `.esc`, `.tab`, `.space` – direct key
+* `.delete` – delete or backspace
+* `.arrow` – up, right, down or left arrow
+* `.digit` – 0-9
+* `.letter` – A-Z, a-z or any [unicode letter](https://unicode.org/reports/tr18/#General_Category_Property)
+* `.char` – any non-space character
+
+```html
+<!-- any arrow event -->
+<div :onkeydown.arrow="event => navigate(event.key)"></div>
+
+<!-- key combination -->
+<input :onkeydown.prevent.ctrl-c="copy(clean(value))">
+```
+
+<!--
+#### `.persist-<kind?>`  <kbd>props</kbd>
+
+Persist value in local or session storage.
+
+```html
+<textarea :value.persist="text" />
+
+<select :onchange="event => theme = event.target.value" :value.persist="theme">
+  <option value="light">Light</option>
+  <option value="dark">Dark</option>
+</select>
+```
+-->
+
+#### `.<any>`
+
+Any other modifier has no effect, but allows binding multiple handlers.
+
+```html
+<span :fx.once="init(x)" :fx.update="() => (update(), () => destroy())">
+```
+
+
+## Store
+
+Sprae uses signals store for reactivity.
+
+```js
+import sprae, { store, signal, effect, computed } from 'sprae'
+
+const name = signal('foo');
+const capname = computed(() => name.value.toUpperCase());
+
+const state = store(
+  {
+    count: 0,                             // prop
+    inc(){ this.count++ },                // method
+    name, capname,                        // signal
+    get twice(){ return this.count * 2 }, // computed
+    _i: 0,                                // untracked
+  },
+
+  // globals / sandbox
+  { Math }
+)
+
+// manual init
+sprae(element, state)
+
+state.inc(), state.count++  // update
+name.value = 'bar'          // signal update
+state._i++                  // no update
+
+state.Math                  // == globalThis.Math
+state.navigator             // == undefined
+```
+
+
 ## Signals
 
-Sprae uses _preact-flavored signals_ for reactivity and can take _signal_ values as inputs.<br/>
-Signals can be switched to an alternative preact/compatible implementation:
+Default signals can be replaced with _preact-signals_ alternative:
 
 ```js
 import sprae from 'sprae';
 import { signal, computed, effect, batch, untracked } from 'sprae/signal';
 import * as signals from '@preact/signals-core';
 
-// switch sprae signals to @preact/signals-core
 sprae.use(signals);
-
-// use signal as state value
-const name = signal('Kitty')
-sprae(el, { name });
-
-// update state
-name.value = 'Dolly';
 ```
 
 Provider | Size | Feature
 :---|:---|:---
 [`ulive`](https://ghub.io/ulive) | 350b | Minimal implementation, basic performance, good for small states.
-[`@webreflection/signal`](https://ghub.io/@webreflection/signal) | 531b | Class-based, better performance, good for small-medium states.
-[`usignal`](https://ghub.io/usignal) | 850b | Class-based with optimizations, good for medium states.
+[`signal`](https://ghub.io/@webreflection/signal) | 633b | Class-based, better performance, good for small-medium states.
+[`usignal`](https://ghub.io/usignal) | 955b | Class-based with optimizations and optional async effects.
 [`@preact/signals-core`](https://ghub.io/@preact/signals-core) | 1.47kb | Best performance, good for any states, industry standard.
 [`signal-polyfill`](https://ghub.io/signal-polyfill) | 2.5kb | Proposal signals. Use via [adapter](https://gist.github.com/dy/bbac687464ccf5322ab0e2fd0680dc4d).
+[`alien-signals`](https://github.com/WebReflection/alien-signals) | 2.67kb | Preact-flavored [alien signals](https://github.com/stackblitz/alien-signals).
 
 
 ## Evaluator
 
-Expressions use _new Function_ as default evaluator, which is fast & compact way, but violates "unsafe-eval" CSP.
-To make eval stricter & safer, as well as sandbox expressions, an alternative evaluator can be used, eg. _justin_:
+Default evaluator is fast and compact, but violates "unsafe-eval" CSP.<br/>
+To make eval stricter & safer, any alternative can be used, eg. [_justin_](https://github.com/dy/subscript#justin):
 
 ```js
 import sprae from 'sprae'
 import justin from 'subscript/justin'
 
-sprae.use({compile: justin}) // set up justin as default compiler
+sprae.use({compile: justin})
 ```
 
-[_Justin_](https://github.com/dy/subscript#justin) is minimal JS subset that avoids "unsafe-eval" CSP and provides sandboxing.
-
-###### Operators:
+<!--
+a minimal JS subset:
 
 `++ -- ! - + * / % ** && || ??`<br/>
 `= < <= > >= == != === !==`<br/>
 `<< >> >>> & ^ | ~ ?: . ?. [] ()=>{} in`<br/>
-`= += -= *= /= %= **= &&= ||= ??= ... ,`
-
-###### Primitives:
-
+`= += -= *= /= %= **= &&= ||= ??= ... ,`<br/>
 `[] {} "" ''`<br/>
 `1 2.34 -5e6 0x7a`<br/>
 `true false null undefined NaN`
+-->
 
 
-## Custom Build
+## Autoinit
 
-_Sprae_ can be tailored to project needs via `sprae/core`:
+The `start` or `data-sprae-start` attribute automatically starts sprae on document. It can use a selector to adjust target container.
 
-```js
-// sprae.custom.js
-import sprae, { dir, parse } from 'sprae/core'
-import * as signals from '@preact/signals'
-import compile from 'subscript'
+```html
+<div id="counter" :scope="{count: 1}">
+  <p :text="`Clicked ${count} times`"></p>
+  <button :onclick="count++">Click me</button>
+</div>
 
-// standard directives
-import 'sprae/directive/default.js'
-import 'sprae/directive/if.js'
-import 'sprae/directive/text.js'
+<script src="./sprae.js" data-sprae-start="#counter"></script>
+```
 
-// custom directive :id="expression"
-dir('id', (el, state, expr) => {
-  // ...init
-  return value => el.id = value // update
-})
+For manual start, remove `start` attribute:
 
-sprae.use({
-  // configure signals
-  ...signals,
+```html
+<script src="./sprae.js"></script>
+<script>
+  // watch & autoinit els
+  sprae.start(document.body, { count: 1 });
 
-  // configure compiler
-  compile,
+  // OR init individual el (no watch)
+  const state = sprae(document.getElementById('counter'), { count: 0 })
+</script>
+```
 
-  // custom prefix, default is `:`
-  prefix: 'js-'
-})
+For more control use ESM:
+
+```html
+<script type="module">
+  import sprae from './sprae.js'
+
+  // init
+  const state = sprae(document.getElementById('counter'), { count: 0 })
+
+  // update state
+  state.count++
+</script>
 ```
 
-## JSX
 
-Sprae works with JSX via custom prefix.
+## JSX
 
-Case: Next.js server components can't do dynamic UI – active nav, tabs, sliders etc. Converting to client components breaks data fetching and adds overhead. Sprae can offload UI logic to keep server components intact.
+Sprae works with JSX via custom prefix (eg. `data-sprae-`).
+Useful to offload UI logic from server components in react / nextjs, instead of converting them to client components.
 
 ```jsx
 // app/page.jsx - server component
 export default function Page() {
   return <>
     <nav id="nav">
-      <a href="/" js-class="location.pathname === '/' && 'active'">Home</a>
-      <a href="/about" js-class="location.pathname === '/about' && 'active'">About</a>
+      <a href="/" data-sprae-class="location.pathname === '/' && 'active'">Home</a>
+      <a href="/about" data-sprae-class="location.pathname === '/about' && 'active'">About</a>
     </nav>
     ...
   </>
@@ -392,42 +566,100 @@ import Script from 'next/script'
 export default function Layout({ children }) {
   return <>
     {children}
-    <Script src="https://unpkg.com/sprae" prefix="js-" />
+    <Script src="https://unpkg.com/sprae" data-sprae-prefix="data-sprae-" data-sprae-start />
   </>
 }
 ```
 
+## Custom build
+
+Sprae build can be tweaked for project needs / size:
+
+```js
+// sprae.custom.js
+import sprae, { directive, use } from 'sprae/core'
+import * as signals from '@preact/signals'
+import compile from 'subscript/justin'
+
+import _default from 'sprae/directive/default.js'
+import _if from 'sprae/directive/if.js'
+import _text from 'sprae/directive/text.js'
+
+use({
+  // custom prefix, defaults to ':'
+  prefix: 'data-sprae-',
+
+  // use preact signals
+  ...signals,
+
+  // use safer compiler
+  compile
+})
+
+// standard directives
+directive.if = _if;
+directive.text = _text;
+directive.default = _default;
+
+// custom directive :id="expression"
+directive.id = (el, state, expr) => {
+  // ...init
+  return newValue => {
+    // ...update
+    let nextValue = el.id = newValue
+    return nextValue
+  }
+}
+
+export default sprae;
+```
+
+<!--
+## Micro
+
+Micro sprae version is 2.5kb bundle with essentials:
+
+* no multieffects `:a:b`
+* no modifiers `:a.x.y`
+* no sequences `:ona..onb`
+* no `:each`, `:if`, `:value`
+-->
+
 ## Hints
 
 * To prevent [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) add `<style>[\:each],[\:if],[\:else] {visibility: hidden}</style>`.
 * Attributes order matters, eg. `<li :each="el in els" :text="el.name"></li>` is not the same as `<li :text="el.name" :each="el in els"></li>`.
-* Invalid self-closing tags like `<a :text="item" />` will cause error. Valid self-closing tags are: `li`, `p`, `dt`, `dd`, `option`, `tr`, `td`, `th`, `input`, `img`, `br`.
-* Properties prefixed with `_` are untracked: `let state = sprae(el, {_x:2}); state._x++; // no effect`.
+* Invalid self-closing tags like `<a :text="item" />` cause error. Valid self-closing tags are: `li`, `p`, `dt`, `dd`, `option`, `tr`, `td`, `th`, `input`, `img`, `br`.
 * To destroy state and detach sprae handlers, call `element[Symbol.dispose]()`.
-* State getters/setters work as computed effects, eg. `sprae(el, { x:1, get x2(){ return this.x * 2} })`.
-* `this` is not used, to get current element use `:ref`.
-* `event` is not used, `:on*` attributes expect a function with event argument `:onevt="event => handle()"`, see [#46](https://github.com/dy/sprae/issues/46).
+* `this` is not used, to get element reference use `:ref="element => {...}"`.
 * `key` is not used, `:each` uses direct list mapping instead of DOM diffing.
-* `await` is not supported in attributes, it’s a strong indicator you need to put these methods into state.
-* `:ref` comes after `:if` for mount/unmount events `<div :if="cond" :ref="(init(), ()=>dispose())"></div>`.
+* Expressions can be async: `<div :text="await load()"></div>`
+
+<!--
+## FAQ
+
+1. Errors handling?
+2. Typescript support?
+3. Performance tips?
+-->
 
 ## Justification
 
-Modern frontend stack is obese and unhealthy, like non-organic processed food. There are healthy alternatives, but:
+Modern frontend is unhealthy—like processed, non-organic food. Frameworks force you into JS-land: build pipelines for "Hello World", proprietary conventions, virtual DOM overhead, brittle tooling. Pages are not functional without JS. Progressive enhancement is anachronism. Build tools should be optional, not mandatory. Frameworks should enhance HTML, not replace it.
+
+Native [template-parts](https://github.com/github/template-parts) and [DCE](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Declarative-Custom-Elements-Strawman.md) give hope, but quite distant and stuck with HTML quirks [1](https://github.com/github/template-parts/issues/24), [2](https://github.com/github/template-parts/issues/25), [3](https://shopify.github.io/liquid/tags/template/#raw).
 
-* [Template-parts](https://github.com/dy/template-parts) 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).
-* [Alpine](https://github.com/alpinejs/alpine) / [petite-vue](https://github.com/vuejs/petite-vue) / [lucia](https://github.com/aidenybai/lucia) escape native HTML quirks, but have excessive API (`:`, `x-`, `{}`, `@`, `$`), tend to [self-encapsulate](https://github.com/alpinejs/alpine/discussions/3223) and not care about size/performance.
+[Alpine](https://github.com/alpinejs/alpine) and [petite-vue](https://github.com/vuejs/petite-vue) offer progressive enhancement, but introduce invalid syntax `@click`, bloated API, opaque reactivity, [self-encapsulation](https://github.com/alpinejs/alpine/discussions/3223), limited extensibility, size / performance afterthoughts.
 
-_Sprae_ holds open & minimalistic philosophy:
+_Sprae_ holds open, safe, minimalistic philosophy:
 
-* Minimal syntax `:`.
-* _Signals_ for reactivity.
-* Pluggable directives, configurable internals.
-* Small, safe & performant.
-* Bits of organic sugar.
-* Aims at making developers happy 🫰
+* One `:` prefix. Valid HTML. Zero magic.
+* Signals reactivity. (preact-signals compatible)
+* Plugggable: signals, eval, directives, modifiers.
+* Build-free, ecosystem-agnostic: `<script src>`, JSX, anything.
+* Small, safe & fast.
+* 🫰 developers
 
-> Perfection is not when there is nothing to add, but when there is nothing to take away.
 
 <!--
 |                       | [AlpineJS](https://github.com/alpinejs/alpine)          | [Petite-Vue](https://github.com/vuejs/petite-vue)        | Sprae            |
@@ -445,6 +677,9 @@ _Sprae_ holds open & minimalistic philosophy:
 | _Fragments_ | Yes | No | Yes |
 | _Plugins_ | Yes | No | Yes |
 | _Modifiers_ | Yes | No | Yes |
+
+_Nested directives_ Yes
+_Inline directives_ Yes
 -->
 
 <!--
@@ -487,18 +722,6 @@ npm run results
 </details>
 -->
 
-<!-- ## See also -->
-
-<!--
-## Alternatives
-
-* [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)
-* [hmpl](https://github.com/hmpl-language/hmpl)
- -->
-
 
 ## Examples
 
@@ -507,12 +730,16 @@ 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)
 * Carousel: [demo](https://rwdevelopment.github.io/sprae_js_carousel/), [code](https://github.com/RWDevelopment/sprae_js_carousel)
 * Tabs: [demo](https://rwdevelopment.github.io/sprae_js_tabs/), [code](https://github.com/RWDevelopment/sprae_js_tabs?tab=readme-ov-file)
-* Prostogreen [demo](https://web-being.org/prostogreen/), [code](https://github.com/web-being/prostogreen/)
+<!-- * Prostogreen [demo](https://web-being.org/prostogreen/), [code](https://github.com/web-being/prostogreen/) -->
 
 <!--
 ## See Also
 
 * [nadi](https://github.com/dy/nadi) - 101 signals. -->
 
+## Refs
+
+[alpine](https://github.com/alpinejs/alpine), [lucia](https://github.com/aidenybai/lucia), [petite-vue](https://github.com/vuejs/petite-vue), [nuejs](https://github.com/nuejs/nuejs), [hmpl](https://github.com/hmpl-language/hmpl), [unpoly](https://unpoly.com/up.link), [dagger](https://github.com/dagger8224/dagger.js)
+
 
 <p align="center"><a href="https://github.com/krsnzd/license/">🕉</a></p>