sprae 0.1.0 → 2.0.0

package/.github/workflows/node.js.yml

@@ -0,0 +1,30 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test

package/package.json

@@ -1,25 +1,33 @@
 {
   "name": "sprae",
   "description": "Reactive directives with expressions for DOM microtemplating.",
-  "version": "0.1.0",
+  "version": "2.0.0",
   "main": "sprae.js",
+  "type": "module",
   "dependencies": {
-    "element-props": "^2.0.4",
-    "htm": "^3.1.1",
-    "preact": "^10.11.2",
+    "@preact/signals-core": "^1.2.2",
+    "element-props": "^2.3.0",
+    "primitive-pool": "^2.0.0",
+    "signal-struct": "^1.5.0",
     "sube": "^2.2.1",
     "swapdom": "^1.1.1"
   },
   "devDependencies": {
     "@preact/signals": "^1.1.2",
+    "browser-env": "^3.3.0",
     "es-module-shims": "^1.6.2",
+    "esbuild": "^0.15.14",
     "hyperf": "^1.4.0",
+    "terser": "^5.15.1",
     "tst": "^7.1.1",
+    "usignal": "^0.8.9",
     "value-ref": "^2.1.0",
     "wait-please": "^3.1.0"
   },
   "scripts": {
-    "test": "node test"
+    "test": "node -r browser-env/register test/test.js",
+    "build": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm",
+    "min": "terser sprae.js -o sprae.min.js --module -c passes=3 -m"
   },
   "repository": {
     "type": "git",

package/plan.md

@@ -0,0 +1,20 @@
+* [x] finish directives
+* [x] better list diffing
+* [x] ordered directives init (:each + :if vs :if + :each) -> find out if really needed and which is faster
+  -> yes, needed and solve many init issues.
+* [?] autoinit -> too much maintenance burden
+* [x] node tests
+* [x] better deps updating -> cumulative signal
+* [x] combinations: :else :if
+* [x] :each :if, :if :each
+* [x] :each :each
+* [x] :with must be able to write state value as well
+* [x] docs: give example to each directive
+* [x] initialize per-element: <x :each><y :if></y><x> - tree-dependent (:each comes first).
+* [x] generalize common attributes :prop="xyz"
+* [x] spread props
+* [x] optimization: arrays with multiple elements can be slow on creation. Maybe signal-struct must ignore arrays.
+  -> yep: arrays are rarely changed as `a[i]=newItem` and regularly they're mapped.
+* [x] expand to any subscribables: both as state vars
+* [ ] optimization: replace element-props with direct (better) setters
+* [ ] report usignal problem

package/r&d.md

@@ -1,4 +1,4 @@
-## name
+## [x] name -> sprae
 
 * rasa
 * dew
@@ -32,9 +32,14 @@
   + reference to sporae and similar assoication
   + simpler word
   + better assoc with hydration
+  + spree
+  + spread
+* sprinkle
+  + better meaning
+  - stands out less than sprae
+* aerosol
 
-
-## :attr, :data, :id, :class, :style, :on, :aria - do we enforce JS object or support unscoped expression? -> Use JS convention, too many use-cases.
+## [x] :attr, :data, :id, :class, :style, :on, :aria - do we enforce JS syntax or support unscoped expression? -> Use JS convention, too many use-cases.
 
 1. JS object
 + JS object can directly set value as `:props="obj"`
@@ -48,4 +53,110 @@
 + We anyways introduce custom-ish expression in `:each="item in items"`
   - Vue introduces simple-ish parsing for that
 + Custom expressions are shorter: `:attr="a:1, b:2, c:3"`
-- Custom expressions are confusing for style: `:style="a:1, b:2, c:3"` - very similar to direct style string
+- Custom expressions are confusing for style: `:style="a:1, b:2, c:3"` - very similar to direct style string
+
+## [x] Attribute directive: `:={a:1}` vs `:attr={a:1}` vs `:prop={a:1}` -> hold on for now
+
++ `:=obj` reminds pascal assignment operator, which is cool
++ `:={a:1,b:2}` is natural convention from vue/alpine as - all props in object are assigned as `:{attr}`
+- We can use `:="{data}"` fro sprae autoinit, since scope has confusing name: `:scope={}`, `:sprae={}`, `:with={}`
+-> let's use :prop= for now, since `:={}` can have multiple interpretations
+
+## [x] Scopes mechanism: prototype inheritance chain vs multiple `with` wrappers -> init subtrees, no need for explicit mechanism
+
+- prototype inheritance chain causes deps update difficulties
+- prototype chain is messy-ish
+- prototype chain is a bit more difficult to provide multiple parent scopes
+- prototype state object is inheritance mess - can be super-hard to analyze
+~ `with(a) with(b) with(c)` is the same as `with(a)` with prototype inheritance in terms of access.
+- `with` chain allows runtime update of scopes, eg. child scope was updated to something new.
+  - `prototype` chain is fixed from the time of init.
+- `prototype` chain hails to unidentified root scope and inherits from that. Maybe we should clarify scopes inhertiance and first implement reactive store (see next item).
+
+? what if we avoid scope inheritance mechanism (what's the real use for it?) and instead just make reactive store object, so that :with directive subscribes to any input props, but "shadows" subtree?
+  ? are there uses for inheritance
+
+? Do we need scopes at all? Only for the purpose of autoinit?
+- it seems scopes can introduce more confusion and mess in templates: indicating full paths is more beneficial
+  + unless we introduce proper ":with="item.x as x""
++ prototype chain is a single object:
+  + meaning updators receive one actual-for-element scope instance
+  + that makes external API easier
+  + that allows handling store via single reactive object
+
+-> possibly we have to just subscribe via mechanism of signals-like deps, and :with just initializes subtree with extended object
+
+## [x] Should we inherit values from `init` in `sprae(el, init)`, instead of creating a snapshot of reactive values in `init`? -> nah, nice idea but too little use. Better create signals struct.
+
++ it allows passing any arbitrary scope to initialize from.
+- it can make hard finding reactive sources...
++ it is sort-of neat pattern: object parent updates its particular state: it can also have observable method making object a store
+-> can be delegated to a separate functionality - init just gets converted to reactive store
++ it sort-of makes `init` directly a scope (a parent of scope), which is more natural-ish rather than 2 independent entities
++ can pass both observables and direct state anywhere, eg. init child components from it
+-> worthy of a separate library, signal-struct?
+
+## [x] Per-directive initialize vs per-element initialize -> directives can immediately initialize rest on elements
+
++ Per-directive is very simple and trivial approach
+- Per-directive doesn't read attributes order and init directives independently
+  ~ Practically linear in-order init doesn't make much service either here
+- Per-directive is a bit hard to deal with scopes
+-> gotta benchmark, vs just walker.
+-> seems unavoidable to combine :if within :each, since :each should remove elements and init on find only
+
+## [x] avoid updating unchanged directives if values don't affect them -> signal struct
+
+? what if we use preact/signals to subscribe only to required props?
+-> parseExpr is going to need to be handled by core.js (not directives), and detect & subscribe to dependencies itself
+-> so that directive updator gets invoked only when any of expr dependencies change
+-> gotta solve via signal-struct
+
+## [x] Replace :else-if with :else :if -> not ideal technically, but done
+
++ `:else :if=""` is meaningful expansion of both directives
++ `:else :if` is coming from JS
++ `:else :if` doesn't throw error in JSDOM tests
+- less resemblance with vue: who cares, we already remotely resemble it
+
+## [x] Keep className marker of directive or not?
+
+-> No: first, there's :class directive changing the class itself;
+-> Second, there's easier way to just "evaporate" directive = not initialize twice;
+-> Third, there's too much pollution with class markers
+
+## [ ] Plugins
+
+* init/connected/mount, unmount/disconnected?
+  * init and connected are different apparently
+* :html?
+* :effect?
+* @sprae/tailwind: `<x :tw="mt-1 mx-2"></x>` - separate tailwind utility classes from main ones; allow conditional setters.
+* @sprae/item: `<x :item="{type:a, scope:b}"` – provide microdata
+* @sprae/hcodes: `<x :h=""` – provide microformats
+
+## [x] Write any-attributes via :<prop>?
+
++ Since we support attr walking, maybe instead of :on and :prop just allow any attributes?
+  + that would allow event and attr modifiers...
+  + that would allow somewhat alpine/vue-compatible code
++ makes sense for `:="{}"` spread
++ makes place for other specific directives `:init=""` etc
+
+## [x] :value is confusing: <option> also uses that.
+
+? :model="value"
+  + v-model, x-model
+  - confusing
+? :in="text"
+? :input="text"
+? :bind="value"
+  + more accurate logically
+  - conflicts with existing naming (bind is used for attrs)
+  - conflict if used along with `:value="x" :bind="y"`
+? :value="value" :onchange="e=>value=e.target.value"
+  + more apparent and explicit
+  + less mental load, "model" is too heavy term
+  + overhead is minimal
+  + react-like
+  + it has better control over serialization

package/readme.md

@@ -1,95 +1,175 @@
-# ∴ spræ
+# ∴ 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)
 
-> Reactive directives for DOM microtemplating: moisturize tree without trasplanting to JSX.
+> Soft DOM hydration with reactive microdirectives
 
-A lightweight essential alternative to [alpine](https://github.com/alpinejs/alpine), [petite-vue](https://github.com/vuejs/petite-vue) and [templize](https://github.com/dy/templize) with better ergonomics[*](#justification).
+A 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[*](#justification).
 
 
 ## Usage
 
-Sprae enables directives as attributes starting with `:`.
+Spraedrops (directives) are attributes starting with `:` that contain regular JS expressions:
 
 ```html
-<div id="element" :if="user">
+<div id="container" :if="user">
   Logged in as <span :text="user.displayName">Guest.</span>
 </div>
 
 <script type="module">
-  import init from 'sprae';
+  import sprae from 'sprae';
 
-  const data = { user: { displayName: 'Dmitry Ivanov' } }
-  const [state, update] = init(user, data);
-
-  state.user.displayName = 'dy'       // update value
-  update({user: {displayName: 'dy'}}) // alternatively
+  const state = sprae(container, { user: { displayName: 'Dmitry Ivanov' } });
+  state.user.displayName = 'dy'; // automatically updates DOM
 </script>
 ```
 
-* `init` initializes directives within an `element` subtree with passed `data`.
-* `state` is proxy reflecting used values, changing any of its props updates directives.
-* `update` can be used for bulk-updating multiple props.
-* `data` is the initial state to render the template. It can include reactive values, see [reactivity](#reactivity).
+* `sprae` initializes directives with data (can include [signals](https://github.com/preactjs/signals) or [reactive values](https://github.com/dy/sube)). Once initialized, they immediately evaporate.
+* `state` is object reflecting values, changing any of its props rerenders directives.
 
+<!--
 <details>
-<summary><h3>Autoinit</h3></summary>
+<summary><strong>Autoinit</strong></summary>
 
-Sprae can be used without build step or JS, autoinitializing HTML:
+Sprae can be used without build step or JS, autoinitializing document:
 
 ```html
-<script src="./sprae.js" defer init></script>
+<script src="./sprae.js" defer init="{ count: 0 }"></script>
 
-<div :scope="{ count: 0 }">
-  <span :text="count">
-  <button :on="{ click: e => count++ }">inc</button>
-</div>
+<span :text="count">
+<button :on="{ click: e => count++ }">inc</button>
 ```
 
-* `:scope` marks regions on the tree that should be controlled by sprae.
-* `init` attribute tells sprae to automatically initialize all elements that have `:scope`.
+* `:with` defines data for regions of the tree to autoinit sprae on.
+* `init` attribute tells sprae to automatically initialize document.
 
 </details>
-
+-->
 
 ## Directives
 
-* [x] `:if="condition"`, `:else-if="condition"`, `:else` - controls flow of elements.
-* [x] `:each="item, i? in list"`,`:each="i in number"` - create multiple instances of element by mapping list or number.
-* [x] `:text="value"` - set text content of an element.
-* [ ] `:value="value"` – bind value to input or textarea.
-* [ ]`:id`, `:name`, `:for`, `:type`, `:hidden`, `:disabled`, `:href`, `:src` – common attributes setters.
-* [ ] `:class="[ foo, 'bar' ]"` – set element class from an array, object or a string.
-* [ ] `:style="{ top:1, position:'absolute' }"` – set element style from a string or an object.
-* [ ] `:prop="{ alt:'foo', title:'bar' }"` – set any attribute / property.
-* [ ] `:on="{ click:e=>{}, touch:e=>{} }"` – add event listeners.
-* [ ] `:data="{ foo:1, bar:2 }"` – set [data-*](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*) attributes.
-* [ ] `:aria="{ role:'progressbar' }"` – set [aria-role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes.
-* [ ] `:item="{ id: 1 }"` – set [item*](https://developer.mozilla.org/en-US/docs/Web/HTML/Microdata) microdata attribute.
-* [ ] `:scope="data"` – autoinit subtree.
+#### `:if="condition"`, `:else`
 
-<details>
-<summary><h3>Adding directives</h3></summary>
+Control flow of elements.
+
+```html
+<span :if="foo">foo</span>
+<span :else :if="bar">bar</span>
+<span :else>baz</span>
+```
 
-Directives can be added by registering them via `directive(name, initializer)`:
+#### `:each="item, index in items"`
 
-```js
-import init, { directive } from 'sprae';
+Multiply element. `index` value starts from 1.
 
-directive(':html', (el) => {
-  // ...initialize here
-  const evaluate = parseExpression(el.getAttribute(':html'));
-  return (state) => {
-    // ...update here
-    el.innerHTML = evaluate(state);
-  }
-});
+```html
+<ul :with="{items: ['a','b','c']}">
+  <li :each="item in items" :text="item">Untitled</li>
+</ul>
+
+<!-- Cases -->
+<li :each="item, idx in list" />
+<li :each="val, key in obj" />
+<li :each="idx in 10" />
+
+<!-- Loop by condition -->
+<li :if="items" :each="item in items" :text="item" />
+<li :else>Empty list</li>
 ```
 
-</details>
+#### `:text="value"`
+
+Set text content of an element. Default text can be used as fallback:
+
+```html
+Welcome, <span :text="user.name">Guest</span>.
+```
+
+#### `:class="value"`
+
+Set class value from either string, array or object.
+
+```html
+<div :class="`foo ${bar}`"></div>
+<div :class="['foo', 'bar']"></div>
+<div :class="{foo: true, bar: false}"></div>
+```
+
+#### `:style="value"`
+
+Set style value from object or a string.
+
+```html
+<div :style="foo: bar"></div>
+<div :style="{foo: 'bar'}"></div>
+```
+
+<!--
+#### `:value="value"`
+
+Bind (2-way) value to input, textarea or select.
+
+```html
+<input :with="{text: ''}" :value="text" />
+<textarea :with="{text: ''}" :value="text" />
 
+<select :with="{selected: 0}" :value="selected">
+  <option :each="i in 5" :value="i" :text="i"></option>
+</select>
+```
+-->
+
+#### `:<prop>="value"`, `:="props"`
+
+Set any other prop or props value.
+
+```html
+<label :for="name" :text="name" />
+<input :="{ id: name, name, type, value }" :onchange="e => value=e.target.value" />
+```
+
+#### `:on="events"`
 
-## Reactivity
+Add event listeners.
 
-Directive expressions are naturally reactive, ie. data may contain any async/reactive values, such as:
+```html
+<button :on="{ click: handler, touch: handler }">Submit</button>
+```
+
+#### `: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}" />
+```
+
+#### `:aria="values"`
+
+Set [aria-role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes. Boolean values are stringified.
+
+```html
+<input type="text" id="jokes" role="combobox" :aria="{
+  controls: 'joketypes',
+  autocomplete: 'list',
+  expanded: false,
+  activeOption: 'item1',
+  activedescendant: ''
+}" />
+```
+
+#### `:with="data"`
+
+Set data for a subtree fragment scope.
+
+```html
+<x :with="{ foo: 'bar' }">
+  <y :with="{ baz: 'qux' }" :text="foo + baz"></y>
+</x>
+```
+
+<!--
+### Reactive values
+
+Directive expressions are natively reactive, ie. data may contain any async/reactive values, such as:
 
 * _Promise_ / _Thenable_
 * _Observable_ / _Subject_ / _Subscribable_
@@ -105,14 +185,14 @@ Update happens when any value changes:
 <div id="done" :text="loading ? 'loading' : result">...</div>
 
 <script>
-  import spores from 'sprae';
+  import sprae from 'sprae';
   import { signals } from '@preact/signals';
 
   // <div id="done">...</div>
 
   const loading = signal(true), result = signal(false);
 
-  spores(done, { loading, result })
+  sprae(done, { loading, result })
 
   // <div id="done">loading</div>
 
@@ -123,14 +203,15 @@ Update happens when any value changes:
 </script>
 ```
 
-Note: observers don't require disposal, since they're connected in weak fashion. Once element is disposed, observables are disconnected.
+Internally directives trigger updates only for used properties change. They subscribe in weak fashion and get disposed when element is disposed.
+-->
 
 
 ## 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.
 * [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. Also they tend to [self-encapsulate](https://github.com/alpinejs/alpine/discussions/3223), making interop hard.
-* [preact](https://ghub.io/preact) with HTML as JSX is a nice way to wire JS to templates, but it doesn't really support reactive fields (needs render call). Also migrating HTML to JS is an extreme with unwanted side-effects.
+* [preact](https://ghub.io/preact) with HTML as JSX is a nice way to wire JS to templates, but it doesn't really support reactive fields (needs render call). Also migrating all HTML to JS is an extreme: SPAs are not organic for HTML.
 
 _Sprae_ takes elegant syntax convention of _alpine_ and method of _templize_ to connect any reactive values (like [@preact/signals](https://ghub.io/@preact/signals) or observables) to static HTML.
 
@@ -141,4 +222,5 @@ _Sprae_ takes elegant syntax convention of _alpine_ and method of _templize_ to
 * It doesn'y introduce syntax scatter.
 * It supports simple expressions with exposed reactive data types.
 
+
 <p align="center"><a href="https://github.com/krsnzd/license/">🕉</a></p>