sprae 0.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "sprae",
+  "description": "Reactive directives with expressions for DOM microtemplating.",
+  "version": "0.0.0",
+  "main": "sprae.js",
+  "dependencies": {
+    "sube": "^2.2.1",
+    "element-props": "^2.0.4",
+    "htm": "^3.1.1",
+    "swapdom": "^1.1.1",
+    "preact": "^10.11.2"
+  },
+  "devDependencies": {
+    "@preact/signals": "^1.1.2",
+    "hyperf": "^1.4.0",
+    "tst": "^7.1.1",
+    "value-ref": "^2.1.0",
+    "wait-please": "^3.1.0"
+  },
+  "scripts": {
+    "test": "node test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dy/sporae.git"
+  },
+  "keywords": [
+    "preact",
+    "preact-signals",
+    "signals",
+    "observable",
+    "reactive",
+    "petite-vue",
+    "vue",
+    "template-parts",
+    "templize",
+    "alpine",
+    "alpinejs",
+    "directives",
+    "templating"
+  ],
+  "author": "Dmitry Ivanov <df.creative@gmail.com>",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/dy/sprae/issues"
+  },
+  "homepage": "https://github.com/dy/sprae#readme"
+}

package/r&d.md

@@ -0,0 +1,51 @@
+## name
+
+* rasa
+* dew
+* water
+* humidify
+* sprinkle
+* va
+* soma
+* ley
+* ros
+* dewdrops
+* mtn-dew
+* pores
+* drips
+* straw
+* spores
+* spor
+  + spores
+  + russian
+    - spor
+  + sport
+* spore
+* sporae
+  + scottish twist
+  + sounds russian-ish too
+  - a bit unusual from API perspective...
+  + similar to algae
+  + dots associate with colon prefix
+* spour
+* sprae?
+  + reference to sporae and similar assoication
+  + simpler word
+  + better assoc with hydration
+
+
+## :attr, :data, :id, :class, :style, :on, :aria - do we enforce JS object or support unscoped expression? -> Use JS convention, too many use-cases.
+
+1. JS object
++ JS object can directly set value as `:props="obj"`
+- JS object is a bit verbose `:props="{a:1, b:2}"`, `:on="{click(e){}, touch(e){}}"`
+  + It's very explicitly JS, no confusion must be introduced
+- It makes HTML look a bit more noisy
++ It is more familiar
++ JS syntax saves redundant questions and an item from docs
+
+2. Custom expressions
++ 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

package/readme.md

@@ -0,0 +1,163 @@
+# ∴ spræ
+
+Reactive directives for DOM microtemplating: moisturize tree without trasplanting to JSX.<br/>
+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).
+
+
+## Usage
+
+```html
+<script src="./sprae.js" defer init></script>
+
+<div :scope="{ count: 0 }">
+  <span :text="count">
+  <button :on="{ click: e => count++ }">inc</button>
+</div>
+```
+
+* `:scope` marks regions on the tree that should be controlled by sprae.
+* `init` attribute tells sprae to automatically initialize all elements that have `:scope`.
+* any attribute starting with `:` is considered a sprae directive.
+
+## Manual init
+
+The more direct case is initializing sprae via JS.
+
+```html
+<div id="element" :if="user">
+  Logged in as <span :text="user.displayName">Guest.</span>
+</div>
+
+<script type="module">
+  import init 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
+</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).
+
+
+## Directives
+
+* `:scope="data"` – autoinit subtree.
+* `:if="condition"`, `:else-if="condition"`, `:else` - controls flow of elements.
+* `:each="item, idx? in list"` - map list to instances of an element.
+* `: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.
+
+<!--
+### Loops
+
+Iterating over set of items can be done with `:each` directive:
+
+```html
+<ul>
+  <li :each="item, index in items" :id="'item-' + item.id" :data="{value:item.value}" :text="item.label"></li>
+</ul>
+
+<li :each="{{ item, index in array }}">
+<li :each="{{ key, value, index in object }}">
+<li :each="{{ value in object }}">
+```
+
+### Conditions
+
+To optionally display an element, there are `if`, `else-if`, `else` directives.
+
+```html
+<span :if="status == 0">Inactive</span>
+<span :else-if="status == 1">Active</span>
+<span :else>Finished</span>
+```
+-->
+
+### Adding directives
+
+Directives can be added by registering them via `directive(name, initializer)`:
+
+```js
+import init, { directive } from 'sprae'
+
+directive(':html', (el, expr) => {
+  // ...initialize here
+  const evaluate = parseExpression(expr)
+  return (state) => {
+    // ...update here
+    el.innerHTML = evaluate(state)
+  }
+})
+```
+
+
+## Reactivity
+
+Directive expressions are naturally reactive, ie. data may contain any async/reactive values, such as:
+
+* _Promise_ / _Thenable_
+* _Observable_ / _Subject_ / _Subscribable_
+* _AsyncIterable_
+* _observ-*_
+* etc., see [sube](https://github.com/dy/sube/blob/main/README.md) for the full list.
+
+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>
+
+<script>
+  import spores from 'sprae';
+  import { signals } from '@preact/signals';
+
+  // <div id="done">...</div>
+
+  const loading = signal(true),
+        result = signal(false);
+  spores(done, { loading, result })
+
+  // <div id="done">loading</div>
+
+  setTimeout(() => (loading.value = true, result.value = 'done'), 1000)
+
+  // ... 1s after
+  // <div id="done">done</div>
+</script>
+```
+
+Note: observers don't require disposal, since they're connected in weak fashion. Once element is disposed, observables are disconnected.
+
+
+
+## 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 case, svg attributes, conflict with liquid syntax etc). Besides 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.
+* [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.
+
+_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.
+
+* 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.
+
+<p align="center"><a href="https://github.com/krsnzd/license/">🕉</a></p>

package/src/core.js

@@ -0,0 +1,50 @@
+// autoinit
+const s = document.currentScript
+if (s && s.hasAttribute('init')) {
+  sprae(document.documentElement)
+}
+
+// sprae element: apply directives
+export default function sprae(el, scope) {
+  scope ||= {}
+
+  let params, updates=[]
+
+  // prepare directives
+  for (let dir in directives) updates[dir] = directives[dir](el, scope)
+
+  const update = (diff=scope) => {
+    if (diff !== scope) Object.assign(scope, diff);
+    for (let dir in updates) updates[dir].forEach(update => update(scope))
+  }
+
+  // return update via destructuring of result to allow batch-update
+  scope[Symbol.iterator] = function*(){ yield params; yield update; }
+
+  return params = new Proxy(scope,  {
+    set: (s, k, v) => (scope[k]=v, update(), 1),
+    deleteProperty: (s,k) => (delete scope[k], update(), 1)
+  })
+}
+
+// dict of directives
+const directives = {}, store = new WeakMap
+
+// register a directive
+export const directive = (name, initializer) => (
+  directives[name] = (container) => {
+    const els = container.querySelectorAll(`[${name}]`)
+    const updates = []
+
+    // replace all shortcuts with inner templates
+    for (el of els) {
+      // FIXME: make sure no leak is introduced here
+      if (!store.has(el)) {
+        store.add(el)
+        updates.push(initializer(el, el.getAttribute(name)))
+      }
+    }
+
+    return updates
+  }
+)

package/src/dirs.js

@@ -0,0 +1,43 @@
+import { directive } from './core'
+import { parseExpr } from './eval'
+
+// hidden attribute directive example
+directive(':hidden', (el, expr) => {
+  let evaluate = parseExpr(expr)
+  return (state) => {
+    let value = evaluate(state)
+    prop(el, 'hidden', value)
+  }
+})
+
+
+// directive(':if', (el, expr, stash) => {
+//   stasj
+//   let stash = {els: [el], clauses:[parse(expr)], holder:new Text}, current = el
+//   ifStash.set(el, stash)
+//   return state => {
+//     let idx = stash.clauses.findIndex(match => match(state))
+//     if (idx >= 0) current.replaceWith(current = els[idx])
+//     else current.replaceWith(current = holder)
+//   }
+// })
+// directive(':else-if', (el, expr) => {
+//   const ifNode = prev('text-with-if')
+//   const stash = ifStash.get(ifNode)
+//   stash.els.push(el)
+//   stash.els.
+//   return
+// })
+// directive(':else', (el, expr) => {
+
+// })
+
+// directive(':each', (instance, part) => {
+//   let evalLoop = part.eval
+//   part.eval = state => {
+//     let [itemId, items] = evalLoop(state), list=[]
+//     // FIXME: cache els instead of recreating. Causes difficulties tracking el children
+//     for (let item of items) list.push(new TemplateInstance(part.template, {...state,[itemId]:item}, processor))
+//     return list
+//   }
+// })

package/src/eval.js

@@ -0,0 +1,33 @@
+let evaluatorMemo = {}
+
+// borrowed from alpine: https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/evaluator.js#L61
+// it seems to be more robust than subscript
+export function parseExpr(expression, el) {
+    if (evaluatorMemo[expression]) return evaluatorMemo[expression]
+
+    let AsyncFunction = Object.getPrototypeOf(async function(){}).constructor
+
+    // Some expressions that are useful in Alpine are not valid as the right side of an expression.
+    // Here we'll detect if the expression isn't valid for an assignement and wrap it in a self-
+    // calling function so that we don't throw an error AND a "return" statement can b e used.
+    let rightSideSafeExpression = 0
+      // Support expressions starting with "if" statements like: "if (...) doSomething()"
+      || /^[\n\s]*if.*\(.*\)/.test(expression)
+      // Support expressions starting with "let/const" like: "let foo = 'bar'"
+      || /^(let|const)\s/.test(expression)
+          ? `(() => { ${expression} })()`
+          : expression
+
+    const safeAsyncFunction = () => {
+      try {
+        return new AsyncFunction(['scope'], `let result; with (scope) { result = ${rightSideSafeExpression} }; return result;`)
+      } catch ( error ) {
+        Object.assign( error, { el, expression } )
+        console.warn(`∴ Expression Error: ${error.message}\n\n${ expression ? 'Expression: \"' + expression + '\"\n\n' : '' }`, el)
+        setTimeout(() => { throw error }, 0)
+        return Promise.resolve()
+      }
+    }
+
+    return evaluatorMemo[expression] = safeAsyncFunction()
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { directives } from './dirs.js';
+export { default } from './core.js';

package/test.js

@@ -0,0 +1,84 @@
+import v from 'value-ref'
+import { signal } from '@preact/signals'
+import test, {is, throws} from 'tst'
+import {tick, time} from 'wait-please'
+import sprae from '../sprae.js'
+import h from 'hyperf'
+
+
+test.only('hidden', async () => {
+  let el = `<div :hidden="hidden"></div>`
+  let params = sprae
+})
+
+test('conditions: short', async () => {
+  let el = h`<p>
+    <span :if="a==1">a</span>
+    <span :else-if="a==2">b</span>
+    <span :else >c</span>
+  </p>`
+
+  const params = sprae(el, { a: 1 })
+
+  is(el.innerHTML, '<span>a</span>')
+  params.a = 2
+  is(el.innerHTML, '<span>b</span>')
+  params.a = 3
+  is(el.innerHTML, '<span>c</span>')
+
+  delete params.a
+})
+
+test('conditions: short with insertions', async () => {
+  let el = h`<p>
+    <span :if="a==1" :text="['1:',a]"></span>
+    <span :else-if="a==2" :text="['2:',a]"></span>
+    <span :else :text="a"></span>
+  </p>`
+
+  const params = templize(el, { a: 1 }, exprProcessor)
+
+  is(el.innerHTML, '<span>1:1</span>')
+  params.a = 2
+  is(el.innerHTML, '<span>2:2</span>')
+  params.a = 3
+  is(el.innerHTML, '<span>3</span>')
+  params.a = 4
+  is(el.innerHTML, '<span>4</span>')
+
+  params.a = 1
+  is(el.innerHTML, '<span>1:1</span>')
+  params.a = 4
+  is(el.innerHTML, '<span>4</span>')
+
+  delete params.a
+})
+
+test.todo('conditions: reactive values', async () => {
+
+})
+
+
+test('loops: short', async () => {
+  // FIXME: in some conspicuous reason jsdom fails to update text nodes somehow
+  let el = h`<p>
+    <span :each="item in items" :text="item"></span>
+  </p>`
+
+  const params = sprae(el, { items: [] })
+
+  is(el.innerHTML, '')
+  params.items = [1,2]
+  is(el.innerHTML, '<span>1</span><span>2</span>')
+  params.items = []
+  is(el.innerHTML, '')
+
+  delete params.items
+})
+
+test.todo('loops: reactive values', async () => {
+})
+
+test.todo('loops: condition within loop')
+
+test.todo('loops: loop within condition')