sprae 10.11.0 → 10.12.0

package/readme.md

@@ -4,7 +4,7 @@
 
 _Sprae_ is open & minimalistic progressive enhancement framework.<br/>
 Perfect for small-scale websites, static pages, landings, prototypes, or lightweight UI.<br/>
-A light alternative to alpine, petite-vue etc.
+A light alternative to alpine, petite-vue etc (see [why](#justification)).
 
 ## Usage
 
@@ -14,7 +14,7 @@ A light alternative to alpine, petite-vue etc.
 </div>
 
 <script type="module">
-  import sprae from './sprae.js'
+  import sprae from './sprae.js' // https://unpkg.com/sprae/dist/sprae.min.js
 
   // init
   const container = document.querySelector('#container');
@@ -370,23 +370,24 @@ sprae.use({ compile })
 
 * 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>`.
+* Watch out for self-closing tags, it's tempting to use `<a :text="item" />` but that's invalid html, it will create rendering errors.
 * Properties prefixed with `_` are untracked: `let state = sprae(el, {_x:2}); state._x++; // no effect`.
 * 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` keyword is not used, to get access to current element use `<input :ref="el" :text="el.value"/>`.
-* Async/await is not supported in attributes, it's a strong indicator you need to put these methods into state.
-* `:each` doesn't need `key` since it uses direct mapping, see [#44](https://github.com/dy/sprae/issues/44).
-* Event attributes always expect a function value `:onevt="event => handle()"`, see [#46](https://github.com/dy/sprae/issues/46).
+* `this` is not used, to get access to current element use `<input :ref="el" :text="el.value"/>`.
+* `event` is not used, `:on*` attributes expect a function with event object as first argument `:onevt="event => handle()"`, see [#46](https://github.com/dy/sprae/issues/46).
+* `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.
 
 ## Justification
 
-Modern frontend stack is unhealthy like non-organic / processed food. There are few resorts, but:
+Modern frontend stack is unhealthy, like non-organic processed food. There are alternatives, but:
 
 * [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/aidenyabi/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.
 
-_Sprae_ holds open, sweet & minimalistic philosophy:
-* Slim `:` API and _signals_ reactivity.
+_Sprae_ holds open & minimalistic philosophy:
+* Slim `:` API, _signals_ for reactivity.
 * Pluggable directives & configurable internals.
 * Small, safe & performant.
 * Bits of organic sugar.