sprae 4.0.0 → 5.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprae",
   "description": "DOM microhydration.",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "main": "src/index.js",
   "module": "src/index.js",
   "type": "module",

package/r&d.md

@@ -518,15 +518,57 @@
   ? Some 'or' character `:onclick--onkeydown`
   ? We can redirect to main event, that's it for now
 
-## [ ] Insert content by reusing the node/template,
+## [x] Insert content by reusing the node/template -> use `:render="ref" :with="data"`
 
   * Makes easy use of repeatable fragments, instead of web-components
   + sort-of "detached" for-each
   + reinforces :ref
   ? does it replace element or puts a content?
+  * Refs:
+    * https://github.com/justinfagnani/html-include-element - src=
+    * https://www.npmjs.com/package/imported-template - content=path-to-file
+    * https://github.com/SirPepe/html-import src="content.selector"
+    * https://github.com/Juicy/juicy-html - html="rawhtml"
+    * https://www.npmjs.com/package/html-import-wc - src=path
+    * https://github.com/sashafirsov/slotted-element - src=path-to-htmlor-json
+    * https://github.com/webcomponents/html-imports - href=filepath
+    * https://github.com/giuseppeg/xm - import src=filepath
+    * https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-include-html#link-tag-html-only
+    * https://github.com/maherbo/include-HTML-document-fragment - link href=path
+    * https://github.com/github/include-fragment-element - src=path-to-html
 
   1. :use="ref-id"
-  2. :
+  ```
+  <template :ref="abc" id="abc"><span :text="abc"></span></template>
+
+  <div :use="abc" :with="{abc:'def'}"></div>
+  <div :use="'#abc'" :with="{abc:'def'}"></div>
+  ```
+
+  - `<use>` from SVG replaces element, but we need inserting content
+
+  2. :content="#template-id"
+
+  - conflicts with direct inline content
+
+  3. :include="#template-id"
+
+  - conflicts with path to file
+
+  4. :tpl="#template-id"
+
+  - some confusion of meaning
+
+  5. :render="#template-id"
+
+  + compatible with liquid 5.0
+  + makes sense as :render=a :with=b
+
+  * Let's think consequently.
+    1. `<template>` element has direct purpose for that
+    2. We provide content fallback for unloaded elements in case of `:text` as `<x :text="abc">fallback</x>`
+    3. There's too many ways to implement fetching - ideally we leave that concern out and focus only on including content
+    4. The approach is almost ready declarative custom element. `<template>` is standard part of it - adds to 1.
 
 ## [x] Remove non-essential directives -> yep, less API friction
   * :aria - can be defined via plain attributes

package/readme.md

@@ -12,9 +12,7 @@ To autoinit on document, include [`sprae.auto.js`](./sprae.auto.js):
 <!-- <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>
+<a :each="id in ['a','b','c']" :href="`#${id}`"></a>
 ```
 
 To use as module, import [`sprae.js`](./sprae.js):
@@ -50,23 +48,6 @@ Sprae evaluates attributes starting with `:`:
 
 ## Attributes
 
-#### `:scope="data"`
-
-Define or extend data scope for a subtree.
-
-```html
-<!-- Inline data -->
-<x :scope="{ foo: 'bar' }" :text="foo"></x>
-
-<!-- External data -->
-<y :scope="data"></y>
-
-<!-- Extend scope -->
-<x :scope="{ foo: 'bar' }">
-  <y :scope="{ baz: 'qux' }" :text="foo + baz"></y>
-</x>
-```
-
 #### `:if="condition"`, `:else`
 
 Control flow of elements.
@@ -148,7 +129,7 @@ Set value of an input, textarea or select. Takes handle of `checked` and `select
 </select>
 ```
 
-#### `:<prop>="value?"`, `:="props?"`
+#### `:<prop>="value?"`
 
 Set any attribute value or run effect.
 
@@ -159,16 +140,21 @@ Set any attribute value or run effect.
 <!-- Multiple properties -->
 <input :id:name="name" />
 
-<!-- Bulk properties -->
-<input :="{ id: name, name, type:'text', value }" />
+<!-- Effect (triggers any time bar changes) -->
+<div :fx="void bar()" ></div>
+```
+
+#### `:="props?"`
 
-<!-- Effects (trigger any time foo or bar changes) -->
-<div :="if (foo) bar()" :fx="void bar()" ></div>
+Spread multiple attibures.
+
+```html
+<input :="{ id: name, name, type:'text', value }" />
 ```
 
-#### `:on<event>="handler"`, `:on="events"`, `:<in>..<out>="handler"`
+#### `:on<event>="handler"`, `:on<in>..on<out>="handler"`
 
-Add event listeners.
+Add event listener or events chain.
 
 ```html
 <!-- Single event -->
@@ -189,9 +175,6 @@ Add event listeners.
 
 <!-- Event modifiers -->
 <button :onclick.throttle-500="handler">Not too often</button>
-
-<!-- Bulk/custom events -->
-<button :on="{ click: handler, touch: handler, special: handler }">Submit</button>
 ```
 
 ##### Event modifiers
@@ -205,6 +188,33 @@ 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).
 
+#### `:with="data"`
+
+Define or extend data scope for a subtree.
+
+```html
+<!-- Inline data -->
+<x :with="{ foo: 'bar' }" :text="foo"></x>
+
+<!-- External data -->
+<y :with="data"></y>
+
+<!-- Extend scope -->
+<x :with="{ foo: 'bar' }">
+  <y :with="{ baz: 'qux' }" :text="foo + baz"></y>
+</x>
+```
+
+#### `:render="ref"`
+
+Include template as element content.
+
+```html
+<template :ref="foo"><span :text="foo"></span></template>
+
+<div :render="foo" :with="{foo:'bar'}">unknown</div>
+<div :render="foo" :with="{foo:'baz'}">unknown</div>
+```
 
 #### `:ref="id"`
 
@@ -233,8 +243,14 @@ Expose element to current data scope with the `id`:
 ## Sandbox
 
 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 as `Object.assign(sprae.globals, { BigInt, window, document })` etc.
+
+```html
+<div :x="window.x"></div>
+<!-- window is undefined -->
+```
+
+Default sandbox provides: _Array_, _Object_, _Number_, _String_, _Boolean_, _Date_, _console_.<br/>
+Sandbox can be extended as `Object.assign(sprae.globals, { BigInt, window, document })`.
 
 ## Examples
 

package/src/directives.js

@@ -2,7 +2,7 @@
 import sprae from './core.js'
 import swap from './domdiff.js'
 import { state as createState} from './state.js'
-import { WeakishMap } from './weakish-map.js'
+import { queueMicrotask, WeakishMap } from './util.js'
 
 // reserved directives - order matters!
 // primary initialized first by selector, secondary initialized by iterating attributes
@@ -10,8 +10,8 @@ export const primary = {}, secondary = {}
 
 
 // :if is interchangeable with :each depending on order, :if :each or :each :if have different meanings
-// as for :if :scope - :if must init first, since it is lazy, to avoid initializing component ahead of time by :scope
-// we consider :scope={x} :if={x} case insignificant
+// as for :if :with - :if must init first, since it is lazy, to avoid initializing component ahead of time by :with
+// we consider :with={x} :if={x} case insignificant
 primary['if'] = (el, expr) => {
   let holder = document.createTextNode(''),
       clauses = [parseExpr(el, expr, ':if')],
@@ -44,9 +44,9 @@ primary['if'] = (el, expr) => {
   }
 }
 
-// :scope must come before :each, but :if has primary importance
-primary['scope'] = (el, expr, rootState) => {
-  let evaluate = parseExpr(el, expr, 'scope')
+// :with must come before :each, but :if has primary importance
+primary['with'] = (el, expr, rootState) => {
+  let evaluate = parseExpr(el, expr, ':with')
   const localState = evaluate(rootState)
   let state = createState(localState, rootState)
   // console.log(123, state.foo, state.bar)
@@ -58,7 +58,7 @@ const _each = Symbol(':each')
 // :each must init before :ref, :id or any others, since it defines scope
 primary['each'] = (tpl, expr) => {
   let each = parseForExpression(expr);
-  if (!each) return exprError(new Error, tpl, expr);
+  if (!each) return exprError(new Error, tpl, expr, ':each');
 
   // FIXME: make sure no memory leak here
   // we need :if to be able to replace holder instead of tpl for :if :each case
@@ -68,7 +68,7 @@ primary['each'] = (tpl, expr) => {
   const evaluate = parseExpr(tpl, each[2], ':each');
 
   const keyExpr = tpl.getAttribute(':key');
-  const itemKey = keyExpr ? parseExpr(null, keyExpr) : null;
+  const itemKey = keyExpr ? parseExpr(null, keyExpr, ':each') : null;
   tpl.removeAttribute(':key')
 
   const refExpr = tpl.getAttribute(':ref');
@@ -142,6 +142,16 @@ function parseForExpression(expression) {
   return [item, '', items]
 }
 
+secondary['render'] = (el, expr, state) => {
+  let evaluate = parseExpr(el, expr, ':render'),
+      tpl = evaluate(state)
+
+  if (!tpl) exprError(new Error('Template not found'), el, expr, ':render');
+
+  let content = tpl.content.cloneNode(true);
+  el.replaceChildren(content)
+  sprae(el, state)
+}
 
 secondary['ref'] = (el, expr, state) => {
   // FIXME: wait for complex ref use-case
@@ -426,9 +436,9 @@ function parseExpr(el, expression, dir) {
   }
 }
 
-function exprError(error, element, expression, dir) {
+function exprError(error, element, expression, directive) {
   Object.assign( error, { element, expression } )
-  console.warn(`∴ ${error.message}\n\n${dir}=${ expression ? `"${expression}"\n\n` : '' }`, element)
+  console.warn(`∴ ${error.message}\n\n${directive}=${ expression ? `"${expression}"\n\n` : '' }`, element)
   queueMicrotask(() => { throw error }, 0)
 }
 

package/src/state.js

@@ -1,3 +1,5 @@
+import { queueMicrotask } from "./util.js"
+
 // currentFx stack of listeners
 let currentFx, batch = new Set, pendingUpdate
 

package/src/{weakish-map.js → util.js}

@@ -1,3 +1,8 @@
+
+// reset stacktrace or plan for fastest next call
+// https://twitter.com/_developit/status/1634033380940455936
+export const queueMicrotask = Promise.prototype.then.bind(Promise.resolve());
+
 // based on https://github.com/WebReflection/not-so-weak/
 const refs = new WeakMap;
 

package/test/dom.js

@@ -277,8 +277,8 @@ test('if: (#3) subsequent content is not abandoned', async () => {
   is(x.outerHTML, `<x><z>123</z></x>`)
 })
 
-test('if: + :scope doesnt prevent secondary effects from happening', async () => {
-  let el = h`<div><x :if="x" :scope="{}" :text="x"></x></div>`
+test('if: + :with doesnt prevent secondary effects from happening', async () => {
+  let el = h`<div><x :if="x" :with="{}" :text="x"></x></div>`
   let state = sprae(el, {x:''})
   is(el.innerHTML, ``)
   state.x = '123'
@@ -286,7 +286,7 @@ test('if: + :scope doesnt prevent secondary effects from happening', async () =>
   is(el.innerHTML, `<x>123</x>`)
 
   // NOTE: we ignore this case
-  // let el2 = h`<div><x :if="x" :scope="{x:cond}" :text="x"></x></div>`
+  // let el2 = h`<div><x :if="x" :with="{x:cond}" :text="x"></x></div>`
   // let state2 = sprae(el, {cond:''})
   // is(el2.innerHTML, ``)
   // state2.cond = '123'
@@ -859,7 +859,7 @@ test('on: modifiers chain', async e => {
 })
 
 test('with: inline', async () => {
-  let el = h`<x :scope="{foo:'bar'}"><y :text="foo + baz"></y></x>`
+  let el = h`<x :with="{foo:'bar'}"><y :text="foo + baz"></y></x>`
   let state = sprae(el, {baz: 'qux'})
   // FIXME: this doesn't inherit root scope baz property and instead uses hard-initialized one
   is(el.innerHTML, `<y>barqux</y>`)
@@ -868,7 +868,7 @@ test('with: inline', async () => {
   is(el.innerHTML, `<y>barquux</y>`)
 })
 test.skip('with: inline reactive', () => {
-  let el = h`<x :scope="{foo:'bar'}"><y :text="foo + baz"></y></x>`
+  let el = h`<x :with="{foo:'bar'}"><y :text="foo + baz"></y></x>`
   let baz = signal('qux')
   sprae(el, {baz})
   // FIXME: this doesn't inherit root scope baz property and instead uses hard-initialized one
@@ -877,7 +877,7 @@ test.skip('with: inline reactive', () => {
   is(el.innerHTML, `<y>barquux</y>`)
 })
 test('with: data', async () => {
-  let el = h`<x :scope="x"><y :text="foo"></y></x>`
+  let el = h`<x :with="x"><y :text="foo"></y></x>`
   let state = sprae(el, {x: {foo:'bar'}})
   is(el.innerHTML, `<y>bar</y>`)
   console.log('update', state.x)
@@ -889,7 +889,7 @@ test('with: data', async () => {
 test('with: transparency', async () => {
   // NOTE: y:text initializes through directive, not through parent
   // therefore by default :text uses parent's state, not defined by element itself
-  let el = h`<x :scope="{foo:'foo'}"><y :scope="b" :text="foo+bar"></y></x>`
+  let el = h`<x :with="{foo:'foo'}"><y :with="b" :text="foo+bar"></y></x>`
   let params = sprae(el, {b:{bar:'bar'}})
   is(el.innerHTML, `<y>foobar</y>`)
   params.b.bar = 'baz'
@@ -897,7 +897,7 @@ test('with: transparency', async () => {
   is(el.innerHTML, `<y>foobaz</y>`)
 })
 test.skip('with: reactive transparency', () => {
-  let el = h`<x :scope="{foo:1}"><y :scope="b.c" :text="foo+bar"></y></x>`
+  let el = h`<x :with="{foo:1}"><y :with="b.c" :text="foo+bar"></y></x>`
   const bar = signal('2')
   sprae(el, {b:{c:{bar}}})
   is(el.innerHTML, `<y>12</y>`)
@@ -905,7 +905,7 @@ test.skip('with: reactive transparency', () => {
   is(el.innerHTML, `<y>13</y>`)
 })
 test('with: writes to state', async () => {
-  let a = h`<x :scope="{a:1}"><y :on="{x(){a++}}" :text="a"></y></x>`
+  let a = h`<x :with="{a:1}"><y :on="{x(){a++}}" :text="a"></y></x>`
   sprae(a)
   is(a.innerHTML, `<y>1</y>`)
   a.firstChild.dispatchEvent(new window.Event('x'))
@@ -916,6 +916,21 @@ test('with: writes to state', async () => {
   is(a.innerHTML, `<y>3</y>`)
 })
 
+test(':render by ref', async () => {
+  let a = h`<template :ref="abc"><div :text="123"></div></template><x :render="abc">456</x>`
+  sprae(a)
+  is(a.outerHTML, `<template><div :text="123"></div></template><x><div>123</div></x>`)
+})
+
+test(':render :with', async () => {
+  let a = h`<template :ref="abc"><div :text="text"></div></template><x :render="abc" />`
+  let state = sprae(a, {text:'abc'})
+  is(a.outerHTML, `<template><div :text="text"></div></template><x><div>abc</div></x>`)
+  state.text = 'def'
+  await tick()
+  is(a.outerHTML, `<template><div :text="text"></div></template><x><div>def</div></x>`)
+})
+
 test('ref: base', async () => {
   let a = h`<a :ref="a" :init="log.push(a), null" :text="b"></a>`
   let state = sprae(a, {log:[], b:1})
@@ -959,7 +974,7 @@ test(':: scope refers to current element', async () => {
 
 test(':: scope directives must come first', async () => {
   // NOTE: we init attributes in order of definition
-  let a = h`<x :text="y" :scope="{y:1}" :ref="x"></x>`
+  let a = h`<x :text="y" :with="{y:1}" :ref="x"></x>`
   sprae(a, {})
   is(a.outerHTML, `<x>1</x>`)
 })

package/test/index.html

@@ -3,7 +3,7 @@
 <title>Test</title>
 
 <script defer src="../sprae.auto.js"></script>
-<div :scope="{data:1}">
+<div :with="{data:1}">
   <span :text="data"></span>
 </div>
 

package/todo.md

@@ -8,7 +8,7 @@
 * [x] combinations: :else :if
 * [x] :each :if, :if :each
 * [x] :each :each
-* [x] :scope must be able to write state value as well
+* [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"
@@ -22,7 +22,7 @@
 * [x] bulk events :ona:onb
 * [x] multiprop setter :a:b="c"
 * [x] make `this` in expression an element
-  * ~~[x] replace :ref with :scope="this as x"~~
+  * ~~[x] replace :ref with :with="this as x"~~
 * [x] :ref creates instance in current state, not creates a new state
   * [x] to avoid extending signal-struct, we must collect state data before, and call updates after for extended state
 * [x] optimization: replace element-props with direct (better) setters
@@ -31,11 +31,11 @@
 * ~~[x] report usignal problem~~ author is not really interested
 * [x] `this` doesn't refer to element/scope in event handlers
 * [x] :text="" empty values shouldn't throw
-* [x] implement :scope
+* [x] implement :with
 * [x] update :value without losing focus / position
 * ~~[x] run tiredown if element got removed from condition or loop (free memory)~~ no need just make sure no refs to elements stored
 * [x] `sprae(el, newState)` can update element's state directly (as batch!?) -> must be tested against repeats in directives
-* [x] :if :ref, :if :scope -> context setters must come first always
+* [x] :if :ref, :if :with -> context setters must come first always
 * [x] :style="{'--x':value}"
 * [x] :onkeydown.ctrl-alt-D
 * [ ] frameworks benchmark