sprae 3.0.1 → 4.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprae",
   "description": "DOM microhydration.",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "main": "src/index.js",
   "module": "src/index.js",
   "type": "module",
@@ -23,9 +23,11 @@
   },
   "scripts": {
     "test": "node -r ./test/register.cjs test/test.js",
-    "build": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm && npm run min",
+    "build": "npm run build-esm && npm run build-iife && npm run min",
+    "build-esm": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm",
+    "build-iife": "esbuild --bundle ./src/index.js --outfile=sprae.auto.js --format=iife",
     "watch": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm --sourcemap --watch",
-    "min": "terser sprae.js -o sprae.min.js --module -c passes=3 -m"
+    "min": "terser sprae.js -o sprae.min.js --module -c passes=3 -m && terser sprae.auto.js -o sprae.auto.min.js --module -c passes=3 -m"
   },
   "repository": {
     "type": "git",

package/r&d.md

@@ -474,6 +474,7 @@
   * [ ] x.raf="abc" - run regularly?
   * [ ] x.watch-a-b-c - update by change of any of the deps
   * [ ] :x.always - update by _any_ dep change
+  * [ ] :class.active="active"
 
 ## [x] Writing props on elements (like ones in :each) -> nah, just use `:x="this.x=abc"`
 
@@ -526,3 +527,8 @@
 
   1. :use="ref-id"
   2. :
+
+## [x] Remove non-essential directives -> yep, less API friction
+  * :aria - can be defined via plain attributes
+  * :data - confusable with :scope, doesn't provide much value, can be used as `:data-x=""` etc
+  * :={} - what's the meaning? Can be replaced with multiple attributes, no? No: no easy way to spread attributes.

package/readme.md

@@ -1,11 +1,35 @@
 # ∴ spræ [![tests](https://github.com/dy/sprae/actions/workflows/node.js.yml/badge.svg)](https://github.com/dy/sprae/actions/workflows/node.js.yml) [![size](https://img.shields.io/bundlephobia/minzip/sprae?label=size)](https://bundlephobia.com/result?p=sprae) [![npm](https://img.shields.io/npm/v/sprae?color=orange)](https://npmjs.org/sprae)
 
-> DOM microhydration with `:` attributes
+> DOM microhydration with `:` attributes.
 
+_Sprae_ is tiny progressive enhancement lib, a minimal 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. It enables simple markup logic without external scripts. Perfect for small websites or prototypes.
 
-## Usage
+## Install
 
-Sprae defines attributes starting with `:` as directives:
+To autoinit on 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>
+
+<div :scope="{foo:'bar'}">
+  <span :text="foo"></span>
+</div>
+```
+
+To use as module, import [`sprae.js`](./sprae.js):
+
+```html
+<script type="module">
+  // import sprae from 'https://cdn.jsdelivr.net/npm/sprae/sprae.js';
+  import sprae from './path/to/sprae.js';
+  sprae(el, {foo: 'bar'});
+</script>
+```
+
+## Use
+
+Sprae evaluates attributes starting with `:`:
 
 ```html
 <div id="container" :if="user">
@@ -20,30 +44,28 @@ Sprae defines attributes starting with `:` as directives:
 </script>
 ```
 
-* `sprae` initializes subtree with data and immediately evaporates `:` attrs.
-* `state` is object reflecting current values, changing any of its props rerenders subtree.
-* To batch-update multiple properties `sprae` can be run repeatedly as: `sprae(container, newValues)`
+* `sprae` initializes container's subtree with data and immediately evaporates `:` attrs.
+* `state` object reflects current values, changing any props rerenders subtree next tick.
 
-<!--
-<details>
-<summary><strong>Autoinit</strong></summary>
 
-sprae can be used without build step or JS, autoinitializing document:
+## Attributes
 
-```html
-<script src="./sprae.js" defer init="{ count: 0 }"></script>
+#### `:scope="data"`
 
-<span :text="count">
-<button :on="{ click: e => count++ }">inc</button>
-```
+Define or extend data scope for a subtree.
 
-* `:with` defines data for regions of the tree to autoinit sprae on.
-* `init` attribute tells sprae to automatically initialize document.
+```html
+<!-- Inline data -->
+<x :scope="{ foo: 'bar' }" :text="foo"></x>
 
-</details>
--->
+<!-- External data -->
+<y :scope="data"></y>
 
-## Attributes
+<!-- Extend scope -->
+<x :scope="{ foo: 'bar' }">
+  <y :scope="{ baz: 'qux' }" :text="foo + baz"></y>
+</x>
+```
 
 #### `:if="condition"`, `:else`
 
@@ -90,17 +112,17 @@ Welcome, <span :text="user.name">Guest</span>.
 
 #### `:class="value"`
 
-Set class value from either string, array or object. Appends existing `class` attribute, if any.
+Set class value from either string, array or object. Extends existing `class` attribute, if any.
 
 ```html
 <div :class="`foo ${bar}`"></div>
-<div :class="['foo', 'bar']"></div>
-<div :class="{foo: true, bar: false}"></div>
 
-<div class="a" :class="['b', 'c']"></div>
-<!--
-<div class="a b c"></div>
--->
+<!-- extend existing class -->
+<div class="foo" :class="`bar`"></div>
+<!-- <div class="foo bar"></div> -->
+
+<!-- object with values -->
+<div :class="{foo:true, bar: false}"></div>
 ```
 
 #### `:style="value"`
@@ -183,54 +205,10 @@ Add event listeners.
 * `.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-*](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*) attributes. CamelCase is converted to dash-case.
-
-```html
-<input :data="{foo: 1, barBaz: true}" />
-<!--
-<input data-foo="1" data-bar-baz="true" />
--->
-```
-
-#### `:aria="values"`
-
-Set [aria-role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes. Boolean values are stringified.
-
-```html
-<input role="combobox" :aria="{
-  controls: 'joketypes',
-  autocomplete: 'list',
-  expanded: false,
-  activeOption: 'item1',
-  activedescendant: ''
-}" />
-<!--
-<input role="combobox" aria-controls="joketypes" aria-autocomplete="list" aria-expanded="false" aria-active-option="item1" aria-activedescendant="">
--->
-```
-
-#### `:with="data"`
-
-Define variables for a subtree fragment scope.
-
-```html
-<!-- Inline data -->
-<x :with="{ foo: 'bar' }" :text="foo"></x>
-
-<!-- External data -->
-<y :with="data"></y>
-
-<!-- Transparency -->
-<x :with="{ foo: 'bar' }">
-  <y :with="{ baz: 'qux' }" :text="foo + baz"></y>
-</x>
-```
 
 #### `:ref="id"`
 
-Expose element to data scope with the `id`:
+Expose element to current data scope with the `id`:
 
 ```html
 <!-- single item -->
@@ -254,28 +232,24 @@ Expose element to data scope with the `id`:
 
 ## Sandbox
 
-Expressions are sandboxed, ie. have no access to global or window.
-
+Expressions are sandboxed, ie. have no access to global or window (since sprae can be run in server environment).
 Default sandbox provides: _Array_, _Object_, _Number_, _String_, _Boolean_, _Date_, _console_.
-
-Sandbox can be extended via `Object.assign(sprae.globals, { BigInt, window, document })` etc.
+Sandbox can be extended as `Object.assign(sprae.globals, { BigInt, window, document })` etc.
 
 ## Examples
 
 * TODO MVC: [demo](https://dy.github.io/sprae/examples/todomvc), [code](https://github.com/dy/sprae/blob/main/examples/todomvc.html)
-* Waveplay: [demo](https://dy.github.io/waveplay), [code](https://github.com/dy/waveedit)
+* Wavearea: [demo](https://dy.github.io/wavearea?src=//cdn.freesound.org/previews/586/586281_2332564-lq.mp3), [code](https://github.com/dy/wavearea)
 
 ## Justification
 
-_Sprae_ is lightweight essential alternative to [alpine](https://github.com/alpinejs/alpine), [petite-vue](https://github.com/vuejs/petite-vue), [templize](https://github.com/dy/templize) or JSX with better ergonomics.
-
 * [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.
 * [Alpine](https://github.com/alpinejs/alpine) / [vue](https://github.com/vuejs/petite-vue) / [lit](https://github.com/lit/lit/tree/main/packages/lit-html) escapes native HTML quirks, but the syntax is a bit scattered: `:attr`, `v-*`,`x-*`, `@evt`, `{{}}` can be expressed with single convention. Besides, functionality is too broad and can be reduced to essence: perfection is when there's nothing to take away, not add. Also they tend to [self-encapsulate](https://github.com/alpinejs/alpine/discussions/3223), making interop hard.
 * 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 convention of _templize directives_ (_alpine_/_vue_ attrs) and builds upon [_@preact/signals_](https://ghub.io/@preact/signals).
+_Sprae_ takes convention of _templize directives_ (_alpine_/_vue_ attrs) and builds upon <del>[_@preact/signals_](https://ghub.io/@preact/signals)</del> simple reacti.
 
-* It doesn't break static html markup.
+* It doesn't break or modify initial static html markup.
 * It falls back to element content if uninitialized.
 * It doesn't enforce SPA nor JSX.
 * It enables island hydration.
@@ -284,7 +258,6 @@ _Sprae_ takes convention of _templize directives_ (_alpine_/_vue_ attrs) and bui
 * Input data may contain [signals](https://ghub.io/@preact/signals) or [reactive values](https://ghub.io/sube).
 * Elements / data API is open and enable easy interop.
 
-
 It is reminiscent of [XSLT](https://www.w3schools.com/xml/xsl_intro.asp), considered a [buried treasure](https://github.com/bahrus/be-restated) by web-connoisseurs.