sprae 1.0.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,12 +1,16 @@
 {
   "name": "sprae",
   "description": "Reactive directives with expressions for DOM microtemplating.",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "main": "sprae.js",
   "type": "module",
   "dependencies": {
+    "@preact/signals-core": "^1.2.2",
     "element-props": "^2.3.0",
-    "sube": "^2.2.1"
+    "primitive-pool": "^2.0.0",
+    "signal-struct": "^1.5.0",
+    "sube": "^2.2.1",
+    "swapdom": "^1.1.1"
   },
   "devDependencies": {
     "@preact/signals": "^1.1.2",
@@ -16,6 +20,7 @@
     "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"
   },

package/plan.md

@@ -1,6 +1,20 @@
-* [ ] finish directives
-* [ ] better list diffing
-* [?] ordered directives init (:each + :if vs :if + :each) -> find out if really needed
-* [x] ~~autoinit~~ -> too much maintenance burden
-* [ ] node tests
-* [ ] better deps updating
+* [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

@@ -32,7 +32,12 @@
   + reference to sporae and similar assoication
   + simpler word
   + better assoc with hydration
-
+  + spree
+  + spread
+* sprinkle
+  + better meaning
+  - stands out less than sprae
+* aerosol
 
 ## [x] :attr, :data, :id, :class, :style, :on, :aria - do we enforce JS syntax or support unscoped expression? -> Use JS convention, too many use-cases.
 
@@ -50,14 +55,14 @@
 + 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
 
-## [x] Attribute directive: `:={a:1}` vs `:attr={a:1}` vs `:prop={a:1}`
+## [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
+## [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
@@ -81,7 +86,7 @@
 
 -> possibly we have to just subscribe via mechanism of signals-like deps, and :with just initializes subtree with extended object
 
-## [ ] Should we inherit values from `init` in `sprae(el, init)`, instead of creating a snapshot of reactive values in `init`?
+## [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...
@@ -89,23 +94,69 @@
 -> 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
+-> worthy of a separate library, signal-struct?
 
-## [ ] Per-directive initialize vs per-element initialize
+## [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
 
-## [ ] avoid updating unchanged directives if values don't affect them
+## [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
 
-## [ ] Replace :else-if with :else :if
+## [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
++ `: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,48 +1,29 @@
-# ∴ spræ [![size](https://img.shields.io/bundlephobia/minzip/sprae?label=size)](https://bundlephobia.com/result?p=sprae)
+# ∴ 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 microdirectives for soft DOM hydration.
+> 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), [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 sprae from 'sprae';
 
-  const init = { user: { displayName: 'Dmitry Ivanov' } }
-  const state = sprae(user, init);
-
-  state.user.displayName = 'dy' // automatically updates DOM
+  const state = sprae(container, { user: { displayName: 'Dmitry Ivanov' } });
+  state.user.displayName = 'dy'; // automatically updates DOM
 </script>
 ```
 
-* `sprae` initializes directives within an `element` subtree with passed `init` data.
-* `state` is proxy reflecting directives values, changing any of its props updates directives.
-* `init` is the initial state to render the template. It can include reactive values, see [reactivity](#reactivity).
-
-
-<details>
-<summary><strong>Bulk update</strong></summary>
-
-To update multiple values at once, state can be expanded as:
-
-```js
-let [values, update] = state;
-update({ user: { displayName: 'dy' } });
-```
-
-* `values` holds actual rendered state values. Changing it doesn't rerender DOM, unlike `state`.
-* `update` useful for bulk-updating multiple values at once.
-
-</details>
+* `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>
@@ -51,12 +32,10 @@ update({ user: { displayName: 'dy' } });
 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 :with="{ count: 0 }">
-  <span :text="count">
-  <button :on="{ click: e => count++ }">inc</button>
-</div>
+<span :text="count">
+<button :on="{ click: e => count++ }">inc</button>
 ```
 
 * `:with` defines data for regions of the tree to autoinit sprae on.
@@ -67,62 +46,130 @@ Sprae can be used without build step or JS, autoinitializing document:
 
 ## Directives
 
-* `:if="condition"`, `:else` - controls flow of elements.
-* `:each="item, i? in list|number"` - create multiple instances of element from list or 1..number range.
-* `:text="value"` - set text content of an element.
-* `:value="value"` – bind value to input or textarea (reflected in model).
-* `: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 other 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.
-* `:with="data"` – provide data alias for subtree fragment.
-<!-- * [ ] `:item="{ id: 1 }"` – set [item*](https://developer.mozilla.org/en-US/docs/Web/HTML/Microdata) microdata attribute. -->
-
-
+#### `:if="condition"`, `:else`
 
-<details>
-<summary><strong>Combining directives</strong></summary>
-
-Directives can be naturally combined as:
+Control flow of elements.
 
 ```html
 <span :if="foo">foo</span>
 <span :else :if="bar">bar</span>
 <span :else>baz</span>
+```
+
+#### `:each="item, index in items"`
 
-<span :if="items" :each="item in items"></span>
-<span :else>Empty list</span>
+Multiply element. `index` value starts from 1.
+
+```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"`
 
-<details>
-<summary><strong>Adding directives</strong></summary>
+Set text content of an element. Default text can be used as fallback:
 
-Directives can be added by registering them via `directive(name, initializer)`:
+```html
+Welcome, <span :text="user.name">Guest</span>.
+```
 
-```js
-import { directive, parseExpr } from 'sprae';
+#### `:class="value"`
 
-directive(':html', (el, expr) => {
-  // ...initialize here
-  const evaluate = parseExpr(expr);
-  return (state) => {
-    // ...update here
-    el.innerHTML = evaluate(state);
-  }
-});
+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>
 ```
 
-</details>
+#### `:style="value"`
+
+Set style value from object or a string.
+
+```html
+<div :style="foo: bar"></div>
+<div :style="{foo: 'bar'}"></div>
+```
 
+<!--
+#### `:value="value"`
 
-## Reactivity
+Bind (2-way) value to input, textarea or select.
 
-Directive expressions are naturally reactive, ie. data may contain any async/reactive values, such as:
+```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"`
+
+Add event listeners.
+
+```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_
@@ -156,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.
 
@@ -174,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>