npm - sprae - Versions diffs - 2.0.0 → 2.1.1 - Mend

sprae 2.0.0 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/examples/todomvc.html ADDED Viewed

@@ -0,0 +1,100 @@
+<!doctype html>
+<html lang="en" data-framework="sprae">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>sprae • TodoMVC</title>
+  <link rel="stylesheet" href="https://unpkg.com/todomvc-common/base.css">
+  <link rel="stylesheet" href="https://unpkg.com/todomvc-app-css/index.css">
+  <style>[\:each]{display: none;}</style>
+</head>
+<body>
+  <section class="todoapp">
+    <header class="header">
+      <h1>todos</h1>
+      <input class="new-todo" placeholder="What needs to be done?" autofocus :onkeypress="e => {
+        if (e.key !== 'Enter') return
+        save(todos = [...todos, { text: e.target.value, done: false}])
+        e.target.value = ''
+      }">
+    </header>
+    <section class="main">
+      <input id="toggle-all" class="toggle-all" type="checkbox" :onclick="e => {
+        const all = todos.every(item => item.done)
+        save(todos = todos.map(item => (item.done = !all, item)))
+      }">
+      <label for="toggle-all">Mark all as complete</label>
+      <ul class="todo-list">
+        <li :ref="li" :each="item in todos"
+          :class="{completed: item.done}"
+          :hidden="hash === '#/active' ? item.done : hash === '#/completed' ? !item.done : false"
+          :ondblclick="e => {
+            li.querySelector('.edit').focus()
+            li.classList.add('editing')
+          }">
+          <div class="view">
+            <input class="toggle" type="checkbox"
+              :checked="item.done"
+              :onchange="e => (item.done = !item.done, save(todos))"
+            />
+            <label :text="item.text"></label>
+            <button class="destroy" :onclick="e => save(todos = todos.filter(i => i !== item))"></button>
+          </div>
+          <input class=edit
+            :value="item.text"
+            :on="{
+              input(e) { item.text = e.target.value; save(todos) },
+              blur(e) { li.classList.remove('editing'); },
+              keypress(e) { e.key === 'Enter' ? e.target.blur() : null },
+            }"
+          />
+        </li>
+      </ul>
+    </section>
+    <footer class="footer">
+      <span class="todo-count" :with="{count: todos.filter(item => !item.done).length}">
+        <strong :text="count">#</strong> <span :text="plur('item', count)">items</span> left
+      </span>
+      <ul class="filters">
+        <li :each="label, key in {'#/': 'All', '#/active': 'Active', '#/completed': 'Completed'}">
+          <a :class="{selected: hash===key}" :href="key" :text="label"></a>
+        </li>
+      </ul>
+      <button class="clear-completed"
+        :hidden="todos.every(item => !item.done)"
+        :onclick="e => save(todos = todos.filter(item => !item.done ? true : false))">
+        Clear completed
+      </button>
+    </footer>
+  </section>
+  <footer class="info">
+    <p>Double-click to edit a todo</p>
+    <p>Created by <a href="https://github.com/dy">dy</a></p>
+    <p>Part of <a href="http://todomvc.com">TodoMVC</a></p>
+  </footer>
+  <script src="https://unpkg.com/todomvc-common/base.js"></script>
+  <script type="importmap"> {
+    "imports": {
+      "sprae": "../../sprae.js",
+      "plur": "https://cdn.skypack.dev/plur"
+    }
+  }
+  </script>
+  <script type="module">
+    import sprae from 'sprae'
+    import plur from 'plur'
+    let state = sprae(document.body, {
+      plur,
+      todos: JSON.parse(localStorage.getItem('todomvc.items') || '[]'),
+      hash: window.location.hash || '#/',
+      save: items => localStorage.setItem('todomvc.items', JSON.stringify(items))
+    })
+    // hash source
+    window.addEventListener('hashchange', e => state.hash = window.location.hash)
+  </script>
+</body>
+</html>

package/package.json CHANGED Viewed

@@ -1,14 +1,14 @@
 {
   "name": "sprae",
-  "description": "Reactive directives with expressions for DOM microtemplating.",
-  "version": "2.0.0",
+  "description": "DOM microhydration.",
+  "version": "2.1.1",
   "main": "sprae.js",
   "type": "module",
   "dependencies": {
     "@preact/signals-core": "^1.2.2",
     "element-props": "^2.3.0",
     "primitive-pool": "^2.0.0",
-    "signal-struct": "^1.5.0",
+    "signal-struct": "^1.5.1",
     "sube": "^2.2.1",
     "swapdom": "^1.1.1"
   },
@@ -27,6 +27,7 @@
   "scripts": {
     "test": "node -r browser-env/register test/test.js",
     "build": "esbuild --bundle ./src/index.js --outfile=sprae.js --format=esm",
+    "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"
   },
   "repository": {
@@ -34,16 +35,14 @@
     "url": "git+https://github.com/dy/sprae.git"
   },
   "keywords": [
-    "preact",
+    "hydration",
     "preact-signals",
     "signals",
     "observable",
     "reactive",
     "petite-vue",
-    "vue",
     "template-parts",
     "templize",
-    "alpine",
     "alpinejs",
     "directives",
     "templating"

package/plan.md CHANGED Viewed

@@ -16,5 +16,13 @@
 * [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
+* [x] :ref
+* [x] :ref + :each
 * [ ] optimization: replace element-props with direct (better) setters
-* [ ] report usignal problem
+* [ ] report usignal problem
+* [ ] :onconnect, :ondisconnect
+* [ ] frameworks benchmark
+* [ ] examples
+  * [ ] todomvc
+* [ ] Sandbox expressions: no global, no "scope" object name, no "arguments"
+* [ ] `this` in expressions must refer to current element always

package/r&d.md CHANGED Viewed

@@ -1,4 +1,4 @@
-## [x] name -> sprae
+## [x] name -> sprea
 * rasa
 * dew
@@ -38,6 +38,17 @@
   + better meaning
   - stands out less than sprae
 * aerosol
+* sprea
+  + inherits sprae
+  + prea(ct)
+  + spree and spread
+  + something priya
+  + anagram: parse, spare, spear
+  + river: https://en.wiktionary.org/wiki/Sprea
+  + spring
+  - sprae has nice ae ligature
+  - sprae is closer to spray
+  - sprae is closer to a verb
 ## [x] :attr, :data, :id, :class, :style, :on, :aria - do we enforce JS syntax or support unscoped expression? -> Use JS convention, too many use-cases.
@@ -125,17 +136,34 @@
 -> Second, there's easier way to just "evaporate" directive = not initialize twice;
 -> Third, there's too much pollution with class markers
+## [ ] :html?
+  - introduces malign hole of including sprae inside of html
+## [x] :fx? -> nah, already works. Just return `null` in any attr, that's it.
+  * let's wait for use-case
+  - doesn't necessarily useful, since any directive is already an effect
+  + works already out of box, just creates `fx` attribute if value is returned
+## [x] :init? -> same as fx.
+  * waiting for use-case
+## [ ] :key.enter?
+  - opens gateway to generic modifiers
+  - introduces a whole mental layer to learn, including combinations of modifiers all around.
+## [ ] :onconnected/disconnected?
 ## [ ] 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>?
+## [x] Write any-attributes via :<prop>? -> yep
 + Since we support attr walking, maybe instead of :on and :prop just allow any attributes?
   + that would allow event and attr modifiers...
@@ -143,7 +171,7 @@
 + makes sense for `:="{}"` spread
 + makes place for other specific directives `:init=""` etc
-## [x] :value is confusing: <option> also uses that.
+## [x] :value is confusing: <option> also uses that. -> let's skip for now: onchange is not a big deal
 ? :model="value"
   + v-model, x-model
@@ -154,9 +182,36 @@
   + 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"
+-> :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
+## [ ] Sandbox?
+1. Use subscript?
+  + solves access to any internal signals on syntactic level
+    + can tentatively be faster than signal-struct
+    + could tentatively get rid of struct and just use signals as input
+      ~ Yep, it's a bit weird template converts data into some reactive state. Just expose an update method instead and current state like useState hook. This way you can avoid exposing signal-specific functions.
+  + Provides precisely controlled sandbox
+  - Some limited lang opportunities
+    - need to match many syntax quirks, can be tedious
+  - Somewhat heavy to bundle
+  + Scope is easier to provide: no need for signal proxy essentially
+  + Can detect access errors in advance
+  + Syntax-level access to signals can be inavoidable: external signals still "leak in" (via arrays or etc.).
+  + Updating simple objects should also rerender the template parts, not just signals.
+  + Deps can be analyzed / implemented without signals
+  - Screwed up debugging / stacktrace (unless errored)
+  + that "unlimits" returned struct, so that any property can be added/deleted.
+## [ ] :onclick="direct code" ?
+  + compatible with direct `onclick=...`
+  + no need for arrow/regular functions syntax in templates
+    - still need that syntax for filters, maps etc
+  + can be made async by default
+  - illicit `event` object

package/readme.md CHANGED Viewed

@@ -1,13 +1,13 @@
-# ∴ 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)
+# ∴ 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)
-> Soft DOM hydration with reactive microdirectives
+> DOM microhydration with `:` attributes
 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
-Spraedrops (directives) are attributes starting with `:` that contain regular JS expressions:
+Sprae defines attributes starting with `:` as directives:
 ```html
 <div id="container" :if="user">
@@ -22,14 +22,14 @@ Spraedrops (directives) are attributes starting with `:` that contain regular JS
 </script>
 ```
-* `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.
+* `sprae` initializes subtree with data and immediately evaporates `:` attrs.
+* `state` is object reflecting current values, changing any of its props rerenders subtree.
 <!--
 <details>
 <summary><strong>Autoinit</strong></summary>
-Sprae can be used without build step or JS, autoinitializing document:
+sprae can be used without build step or JS, autoinitializing document:
 ```html
 <script src="./sprae.js" defer init="{ count: 0 }"></script>
@@ -44,7 +44,7 @@ Sprae can be used without build step or JS, autoinitializing document:
 </details>
 -->
-## Directives
+## Attributes
 #### `:if="condition"`, `:else`
@@ -68,11 +68,14 @@ Multiply element. `index` value starts from 1.
 <!-- Cases -->
 <li :each="item, idx in list" />
 <li :each="val, key in obj" />
-<li :each="idx in 10" />
+<li :each="idx, idx0 in number" />
 <!-- Loop by condition -->
 <li :if="items" :each="item in items" :text="item" />
 <li :else>Empty list</li>
+<!-- To avoid FOUC -->
+<style>[:each]{visibility: hidden}</style>
 ```
 #### `:text="value"`
@@ -166,9 +169,31 @@ Set data for a subtree fragment scope.
 </x>
 ```
+#### `:ref="id"`
+Expose element to a subtree fragment with the `id`.
+```html
+<li :ref="item">
+  <input
+    :onfocus="e=> item.classList.add('editing')"
+    :onblur="e => item.classList.remove('editing')"
+  />
+</li>
+```
 <!--
-### Reactive values
+### Reactivity
+_sprae_ is built on top of [_@preact/signals_](https://ghub.io/@preact/signals). That gives:
+* Expressions don't require explicit access to `.value` (see [signal-struct](https://github.com/dy/signal-struct))
+* Expressions support any reactive values in data (see [sube](https://github.com/dy/sube))
+* Updates happen minimally only when used values update
+* Subscription is weak and get disposed when element is disposed.
+-->
+<!--
 Directive expressions are natively reactive, ie. data may contain any async/reactive values, such as:
 * _Promise_ / _Thenable_
@@ -180,7 +205,8 @@ Directive expressions are natively reactive, ie. data may contain any async/reac
 This way, for example, _@preact/signals_ or _rxjs_ can be connected directly bypassing subscription or reading value.
 Update happens when any value changes:
+-->
+<!--
 ```html
 <div id="done" :text="loading ? 'loading' : result">...</div>
@@ -202,25 +228,22 @@ Update happens when any value changes:
   // <div id="done">done</div>
 </script>
 ```
-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 all HTML to JS is an extreme: SPAs are not organic for HTML.
+* 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 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.
+_sprae_ takes convention of _templize directives_ (_alpine_/_vue_ attrs) and builds upon [_@preact/signals_](https://ghub.io/@preact/signals).
 * It doesn't break static html markup.
-* It doesn't intrude native syntax space.
 * It falls back to element content if uninitialized.
-* It provides means for island hydration.
-* It doesn'y introduce syntax scatter.
-* It supports simple expressions with exposed reactive data types.
+* It doesn't enforce SPA nor JSX.
+* It enables island hydration.
+* It introduces minimal syntax space as `:` convention.
+* Expressions are naturally reactive and incur minimal updates.
+* Input data may contain [signals](https://ghub.io/@preact/signals) or [reactive values](https://ghub.io/sube).
 <p align="center"><a href="https://github.com/krsnzd/license/">🕉</a></p>