sprae 11.0.7 → 11.1.0

package/core.js

@@ -3,15 +3,31 @@ import store, { _signals } from './store.js';
 
 // polyfill
 const _dispose = (Symbol.dispose ||= Symbol("dispose"));
-export const _state = Symbol("state")
-export const _on = Symbol('on')
-export const _off = Symbol('off')
 
-// reserved directives - order matters!
-export const directive = {};
-
-
-// sprae element: apply directives
+export const _state = Symbol("state"), _on = Symbol('on'), _off = Symbol('off')
+
+// registered directives
+const directive = {}
+
+/**
+ * Register a directive with a parsed expression and evaluator.
+ * @param {string} name - The name of the directive.
+ * @param {(el: Element, state: Object, attrValue: string, attrName: string) => (value: any) => void} create - A function to create the directive.
+ * @param {(expr: string) => (state: Object) => any} [p=parse] - Create evaluator from expression string.
+ */
+export const dir = (name, create, p = parse) => directive[name] = (el, expr, state, name, update, evaluate) => (
+  evaluate = p(expr),
+  update = create(el, state, expr, name, evaluate),
+  () => update(evaluate(state))
+)
+
+/**
+ * Applies directives to an HTML element and manages its reactive state.
+ *
+ * @param {Element} el - The target HTML element to apply directives to.
+ * @param {Object} [values] - Initial values to populate the element's reactive state.
+ * @returns {Object} The reactive state object associated with the element.
+ */
 export default function sprae(el, values) {
   // text nodes, comments etc
   if (!el?.childNodes) return
@@ -47,17 +63,16 @@ export default function sprae(el, values) {
 
     // init generic-name attributes second
     for (let i = 0; i < el.attributes?.length;) {
-      let attr = el.attributes[i];
+      let attr = el.attributes[i], update;
 
       if (attr.name[0] === ':') {
         el.removeAttribute(attr.name);
 
         // multiple attributes like :id:for=""
         for (let name of attr.name.slice(1).split(':')) {
-          let dir = directive[name] || directive.default,
-              update = dir(el, (dir.parse || parse)(attr.value), state, name)
-          fx.push(update)
-          offs.push(effect(update))
+          update = (directive[name] || directive.default)(el, attr.value, state, name)
+
+          fx.push(update), offs.push(effect(update)) // save & start effect
 
           // stop after :each, :if, :with?
           if (_state in el) return
@@ -70,9 +85,17 @@ export default function sprae(el, values) {
 }
 
 
-// parse expression into evaluator fn
 const memo = {};
-export const parse = (expr, dir, fn) => {
+/**
+ * Parses an expression into an evaluator function, caching the result for reuse.
+ *
+ * @param {string} expr - The expression to parse and compile into a function.
+ * @param {string} dir - The directive associated with the expression (used for error reporting).
+ * @returns {Function} The compiled evaluator function for the expression.
+ */
+export const parse = (expr, dir) => {
+  let fn
+
   if (fn = memo[expr = expr.trim()]) return fn
 
   // static-time errors
@@ -83,11 +106,23 @@ export const parse = (expr, dir, fn) => {
   return memo[expr] = fn
 }
 
-// wrapped call
+/**
+ * Branded sprae error with context about the directive and expression
+ *
+ * @param {Error} e - The original error object to enhance.
+ * @param {string} dir - The directive where the error occurred.
+ * @param {string} [expr=''] - The expression associated with the error, if any.
+ * @throws {Error} The enhanced error object with a formatted message.
+ */
 export const err = (e, dir, expr = '') => {
-  throw Object.assign(e, { message: `∴ ${e.message}\n\n${dir}${expr ? `="${expr}"\n\n` : ""}`, expr })
+  throw Object.assign(e, { message: `∴ ${e.message}\n\n${dir || ''}${expr ? `="${expr}"\n\n` : ""}`, expr })
 }
 
+/**
+ * Compiles an expression into an evaluator function.
+ *
+ * @type {(expr: string) => Function}
+ */
 export let compile
 
 // configure signals/compile

package/directive/aria.js

@@ -1,9 +1,6 @@
-import { directive } from "../core.js";
+import { dir } from "../core.js";
 import { attr, dashcase } from './default.js'
 
-directive['aria'] = (el, evaluate, state) => {
-  const update = (value) => {
-    for (let key in value) attr(el, 'aria-' + dashcase(key), value[key] == null ? null : value[key] + '');
-  }
-  return () => update(evaluate(state))
-}
+dir('aria', (el) => value => {
+  for (let key in value) attr(el, 'aria-' + dashcase(key), value[key] == null ? null : value[key] + '')
+})

package/directive/class.js

@@ -1,9 +1,8 @@
-import { directive } from "../core.js";
+import { dir } from "../core.js";
 
-directive.class = (el, evaluate, state) => {
-  let cur = new Set
-  return () => {
-    let v = evaluate(state);
+dir('class', (el, cur) => (
+  cur = new Set,
+  v => {
     let clsx = new Set;
     if (v) {
       if (typeof v === "string") v.split(' ').map(cls => clsx.add(cls));
@@ -12,5 +11,5 @@ directive.class = (el, evaluate, state) => {
     }
     for (let cls of cur) if (clsx.has(cls)) clsx.delete(cls); else el.classList.remove(cls);
     for (let cls of cur = clsx) el.classList.add(cls)
-  };
-};
+  })
+)

package/directive/data.js

@@ -1,8 +1,3 @@
-import { directive } from "../core.js";
+import { dir } from "../core.js";
 
-directive['data'] = (el, evaluate, state) => {
-  return () => {
-    let value = evaluate(state)
-    for (let key in value) el.dataset[key] = value[key];
-  }
-}
+dir('data', el => value => {for (let key in value) el.dataset[key] = value[key];})

package/directive/default.js

@@ -1,13 +1,12 @@
-import { directive, err } from "../core.js";
+// generic property directive
+import { dir, err } from "../core.js";
 
-// set generic property directive
-directive.default = (target, evaluate, state, name) => {
+dir('default', (target, state, expr, name) => {
   // simple prop
-  if (!name.startsWith('on')) return () => {
-    let value = evaluate(state);
-    if (name) attr(target, name, value)
-    else for (let key in value) attr(target, dashcase(key), value[key]);
-  };
+  if (!name.startsWith('on'))
+    return name ?
+      value => attr(target, name, value) :
+      value => { for (let key in value) attr(target, dashcase(key), value[key]) };
 
   // bind event to a target
   // NOTE: if you decide to remove chain of events, thing again - that's unique feature of sprae, don't diminish your own value.
@@ -15,30 +14,13 @@ directive.default = (target, evaluate, state, name) => {
   const ctxs = name.split('..').map(e => {
     let ctx = { evt: '', target, test: () => true };
     ctx.evt = (e.startsWith('on') ? e.slice(2) : e).replace(/\.(\w+)?-?([-\w]+)?/g,
-      (match, mod, param = '') => (ctx.test = mods[mod]?.(ctx, ...param.split('-')) || ctx.test, '')
+      (_, mod, param = '') => (ctx.test = mods[mod]?.(ctx, ...param.split('-')) || ctx.test, '')
     );
     return ctx;
   });
 
-  // single event
-  if (ctxs.length == 1) return () => addListener(evaluate(state), ctxs[0])
-
-  // events cycler
-  let startFn, nextFn, off, idx = 0
-  const nextListener = (fn) => {
-    off = addListener((e) => (
-      off(), nextFn = fn?.(e), (idx = ++idx % ctxs.length) ? nextListener(nextFn) : (startFn && nextListener(startFn))
-    ), ctxs[idx]);
-  }
-
-  return () => (
-    startFn = evaluate(state),
-    !off && nextListener(startFn),
-    () => startFn = null // nil startFn to autodispose chain
-  )
-
   // add listener with the context
-  function addListener(fn, { evt, target, test, defer, stop, prevent, immediate, ...opts }) {
+  const addListener = (fn, { evt, target, test, defer, stop, prevent, immediate, ...opts }) => {
     if (defer) fn = defer(fn)
 
     const cb = (e) => {
@@ -51,7 +33,23 @@ directive.default = (target, evaluate, state, name) => {
     return () => target.removeEventListener(evt, cb, opts)
   };
 
-};
+  // single event
+  if (ctxs.length == 1) return v => addListener(v, ctxs[0])
+
+  // events cycler
+  let startFn, nextFn, off, idx = 0
+  const nextListener = (fn) => {
+    off = addListener((e) => (
+      off(), nextFn = fn?.(e), (idx = ++idx % ctxs.length) ? nextListener(nextFn) : (startFn && nextListener(startFn))
+    ), ctxs[idx]);
+  }
+
+  return value => (
+    startFn = value,
+    !off && nextListener(startFn),
+    () => startFn = null // nil startFn to autodispose chain
+  )
+})
 
 // event modifiers
 const mods = {
@@ -117,12 +115,6 @@ const keys = {
   char: (e) => /^\S$/.test(e.key),
 };
 
-// set attr
-export const attr = (el, name, v) => {
-  if (v == null || v === false) el.removeAttribute(name);
-  else el.setAttribute(name, v === true ? "" : typeof v === "number" || typeof v === "string" ? v : "");
-}
-
 // create delayed fns
 const throttle = (fn, limit) => {
   let pause, planned,
@@ -152,6 +144,12 @@ const debounce = (fn, wait) => {
   };
 };
 
+// set attr
+export const attr = (el, name, v) => {
+  if (v == null || v === false) el.removeAttribute(name);
+  else el.setAttribute(name, v === true ? "" : typeof v === "number" || typeof v === "string" ? v : "");
+}
+
 export const dashcase = (str) => {
   return str.replace(/[A-Z\u00C0-\u00D6\u00D8-\u00DE]/g, (match, i) => (i ? '-' : '') + match.toLowerCase());
 }

package/directive/each.js

@@ -1,53 +1,37 @@
-import sprae, { _state, directive, frag, parse } from "../core.js";
+import sprae, { _state, dir, frag, parse } from "../core.js";
 import store, { _change, _signals } from "../store.js";
-import { untracked, computed } from '../signal.js';
+import { effect } from '../signal.js';
 
 
-directive.each = (tpl, [itemVar, idxVar, evaluate], state) => {
-  // we need :if to be able to replace holder instead of tpl for :if :each case
-  const holder = (document.createTextNode(""));
-  tpl.replaceWith(holder);
-  tpl[_state] = null // mark as fake-spraed, to preserve :-attribs for template
+dir('each', (tpl, state, expr) => {
+    const [itemVar, idxVar = "$"] = expr.split(/\s+in\s+/)[0].split(/\s*,\s*/);
 
-  // we re-create items any time new items are produced
-  let cur, keys, prevl = 0
+    // we need :if to be able to replace holder instead of tpl for :if :each case
+    const holder = document.createTextNode("");
+    tpl.replaceWith(holder);
+    tpl[_state] = null // mark as fake-spraed, to preserve :-attribs for template
 
-  // separate computed effect reduces number of needed updates for the effect
-  const items = computed(() => {
-    keys = null
-    let items = evaluate(state)
-    if (typeof items === "number") items = Array.from({ length: items }, (_, i) => i + 1)
-    if (items?.constructor === Object) keys = Object.keys(items), items = Object.values(items)
-    return items || []
-  })
+    // we re-create items any time new items are produced
+    let cur, keys, items, prevl = 0
 
-  const update = () => {
-    // NOTE: untracked avoids rerendering full list whenever internal items or props change
-    untracked(() => {
-      let i = 0, newItems = items.value, newl = newItems.length
+    const update = () => {
+      let i = 0, newItems = items, newl = newItems.length
 
       // plain array update, not store (signal with array) - updates full list
-      if (cur && !(cur[_change])) {
-        for (let s of cur[_signals] || []) { s[Symbol.dispose]() }
+      if (cur && !cur[_change]) {
+        for (let s of cur[_signals] || []) s[Symbol.dispose]()
         cur = null, prevl = 0
       }
 
       // delete
-      if (newl < prevl) {
-        cur.length = newl
-      }
+      if (newl < prevl) cur.length = newl
+
       // update, append, init
       else {
         // init
-        if (!cur) {
-          cur = newItems
-        }
+        if (!cur) cur = newItems
         // update
-        else {
-          for (; i < prevl; i++) {
-            cur[i] = newItems[i]
-          }
-        }
+        else while (i < prevl) cur[i] = newItems[i++]
 
         // append
         for (; i < newl; i++) {
@@ -70,24 +54,26 @@ directive.each = (tpl, [itemVar, idxVar, evaluate], state) => {
       }
 
       prevl = newl
-    })
-  }
-
-  let planned = 0
-  return () => {
-    // subscribe to items change (.length) - we do it every time (not just on init) since preact unsubscribes unused signals
-    items.value[_change]?.value
-
-    // make first render immediately, debounce subsequent renders
-    if (!planned++) update(), queueMicrotask(() => (planned > 1 && update(), planned = 0));
-  }
-}
-
-
-// redefine parser to exclude `[a in] b`
-directive.each.parse = (expr) => {
-  let [leftSide, itemsExpr] = expr.split(/\s+in\s+/);
-  let [itemVar, idxVar = "$"] = leftSide.split(/\s*,\s*/);
-
-  return [itemVar, idxVar, parse(itemsExpr)]
-}
+    }
+
+    return value => {
+      keys = null
+      if (typeof value === "number") items = Array.from({ length: value }, (_, i) => i + 1)
+      else if (value?.constructor === Object) keys = Object.keys(value), items = Object.values(value)
+      else items = value || []
+
+      // whenever list changes, we rebind internal change effect
+      let planned = 0
+      return effect(() => {
+        // subscribe to items change (.length) - we do it every time (not just in update) since preact unsubscribes unused signals
+        items[_change]?.value
+
+        // make first render immediately, debounce subsequent renders
+        if (!planned++) update(), queueMicrotask(() => (planned > 1 && update(), planned = 0));
+      })
+    }
+  },
+
+  // redefine evaluator to take second part of expression
+  expr => parse(expr.split(/\s+in\s+/)[1])
+)

package/directive/fx.js

@@ -1,5 +1,3 @@
-import { directive } from "../core.js";
+import { dir } from "../core.js";
 
-directive.fx = (el, evaluate, state) => {
-  return () => evaluate(state);
-};
+dir('fx', _ => _ => _)

package/directive/if.js

@@ -1,12 +1,14 @@
-import sprae, { directive, _state, _on, _off, frag } from "../core.js";
+import sprae, { dir, _state, _on, _off, frag } from "../core.js";
 
 // :if is interchangeable with :each depending on order, :if :each or :each :if have different meanings
 // 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
 const _prevIf = Symbol("if");
-directive.if = (el, evaluate, state) => {
+
+dir('if', (el, state) => {
+  const holder = document.createTextNode('')
+
   let next = el.nextElementSibling,
-    holder = document.createTextNode(''),
     curEl, ifEl, elseEl;
 
   el.replaceWith(holder)
@@ -20,8 +22,8 @@ directive.if = (el, evaluate, state) => {
     if (!next.hasAttribute(":if")) next.remove(), elseEl = next.content ? frag(next) : next, elseEl[_state] = null
   }
 
-  return () => {
-    const newEl = evaluate(state) ? ifEl : el[_prevIf] ? null : elseEl;
+  return (value) => {
+    const newEl = value ? ifEl : el[_prevIf] ? null : elseEl;
     if (next) next[_prevIf] = newEl === ifEl
     if (curEl != newEl) {
       // disable effects on child elements when element is not matched
@@ -34,4 +36,4 @@ directive.if = (el, evaluate, state) => {
       }
     }
   };
-};
+})

package/directive/ref.js

@@ -1,6 +1,9 @@
-import { directive } from "../core.js";
+import { dir, parse } from "../core.js";
+import { setter, ensure } from "./value.js";
 
-// ref must be last within primaries, since that must be skipped by :each, but before secondaries
-directive.ref = (el, evaluate, state) => {
-  return () => evaluate(state)?.call?.(null, el)
-}
+dir('ref', (el, state, expr, _, ev) => (
+  ensure(state, expr),
+  ev(state) == null ?
+    (setter(expr)(state, el), _ => _) :
+    v => v.call(null, el)
+))

package/directive/style.js

@@ -1,14 +1,12 @@
-import { directive } from "../core.js";
+import { dir } from "../core.js";
 
-directive.style = (el, evaluate, state) => {
-  let initStyle = el.getAttribute("style");
-
-  return () => {
-    let v = evaluate(state);
+dir('style', (el, initStyle) => (
+  initStyle = el.getAttribute("style"),
+  v => {
     if (typeof v === "string") el.setAttribute("style", initStyle + (initStyle.endsWith(';') ? '' : '; ') + v);
     else {
       if (initStyle) el.setAttribute("style", initStyle);
       for (let k in v) k[0] == '-' ? (el.style.setProperty(k, v[k])) : el.style[k] = v[k]
     }
-  };
-};
+  })
+)

package/directive/text.js

@@ -1,12 +1,7 @@
-import { directive, frag } from "../core.js";
+import { dir, frag } from "../core.js";
 
-// set text content
-directive.text = (el, evaluate, state) => {
+dir('text', el => (
   // <template :text="a"/> or previously initialized template
-  if (el.content) el.replaceWith(el = frag(el).childNodes[0])
-
-  return () => {
-    let value = evaluate(state);
-    el.textContent = value == null ? "" : value;
-  };
-};
+  el.content && el.replaceWith(el = frag(el).childNodes[0]),
+  value => el.textContent = value == null ? "" : value
+))

package/directive/value.js

@@ -1,9 +1,9 @@
 import sprae from "../core.js";
-import { directive, parse } from "../core.js";
+import { dir, parse } from "../core.js";
 import { attr } from './default.js';
 
-// connect expr to element value
-directive.value = (el, [getValue, setValue], state) => {
+
+dir('value', (el, state, expr) => {
   const update =
     (el.type === "text" || el.type === "") ?
       (value) => el.setAttribute("value", (el.value = value == null ? "" : value)) :
@@ -29,36 +29,39 @@ directive.value = (el, [getValue, setValue], state) => {
             } :
               (value) => (el.value = value);
 
+  // make sure value exists in state
+  ensure(state, expr)
+
   // bind ui back to value
-  const handleChange = el.type === 'checkbox' ? () => setValue(state, el.checked) : el.type === 'select-multiple' ? () => setValue(state, [...el.selectedOptions].map(o => o.value)) : (e) => setValue(state, el.selectedIndex < 0 ? null : el.value)
+  try {
+    const set = setter(expr)
+    const handleChange = el.type === 'checkbox' ? () => set(state, el.checked) :
+      el.type === 'select-multiple' ? () => set(state, [...el.selectedOptions].map(o => o.value)) :
+        () => set(state, el.selectedIndex < 0 ? null : el.value)
 
-  el.oninput = el.onchange = handleChange; // hope user doesn't redefine these manually via `.oninput = somethingElse` - it saves 5 loc vs addEventListener
+    el.oninput = el.onchange = handleChange; // hope user doesn't redefine these manually via `.oninput = somethingElse` - it saves 5 loc vs addEventListener
 
-  if (el.type?.startsWith('select')) {
-    // select element also must observe any added/removed options or changed values (outside of sprae)
-    new MutationObserver(handleChange).observe(el, { childList: true, subtree: true, attributes: true });
+    if (el.type?.startsWith('select')) {
+      // select element also must observe any added/removed options or changed values (outside of sprae)
+      new MutationObserver(handleChange).observe(el, { childList: true, subtree: true, attributes: true });
 
-    // select options must be initialized before calling an update
-    sprae(el, state)
-  }
+      // select options must be initialized before calling an update
+      sprae(el, state)
+    }
+  } catch {}
 
-  return () => {
-    update(getValue(state));
-  }
-};
+  return update
+})
 
-directive.value.parse = expr => {
-  let evaluate = [parse(expr)]
-  // catch wrong assigns like `123 =...`, `foo?.bar =...`
-  try {
-    const set = parse(`${expr}=__`);
-    // FIXME: if there's a simpler way to set value in justin?
-    evaluate.push((state, value) => {
-      state.__ = value
-      set(state, value)
-      delete state.__
-    })
-  }
-  catch (e) { }
-  return evaluate
-}
+// create expression setter, reflecting value back to state
+export const setter = (expr, set = parse(`${expr}=__`)) => (
+  // FIXME: if there's a simpler way to set value in justin?
+  (state, value) => (
+    state.__ = value,
+    set(state, value),
+    delete state.__
+  )
+)
+
+// make sure state contains first element of path, eg. `a` from `a.b[c]`
+export const ensure = (state, expr, name = expr.match(/^\w+(?=\s*(?:\.|\[|$))/)) => name && (state[name[0]] ||= null)

package/directive/with.js

@@ -1,10 +1,4 @@
-import sprae, { directive } from "../core.js";
+import sprae, { dir } from "../core.js";
 import store, { _signals } from '../store.js';
 
-directive.with = (el, evaluate, rootState) => {
-  let state
-  return () => {
-    let values = evaluate(rootState);
-    sprae(el, state ? values : state = store(values, rootState))
-  }
-};
+dir('with', (el, rootState, state) => (state=null, values => sprae(el, state ? values : state = store(values, rootState))))