sprae 11.6.0 → 12.0.1

package/core.js

@@ -1,138 +1,247 @@
-import { use, effect, untracked } from "./signal.js";
-import { store } from './store.js';
+import store, { _change, _signals } from "./store.js";
 
-// polyfill
-export const _dispose = (Symbol.dispose ||= Symbol("dispose"));
+export const _dispose = (Symbol.dispose ||= Symbol("dispose")),
+  _state = Symbol("state"),
+  _on = Symbol('on'),
+  _off = Symbol('off'),
+  _add = Symbol('add');
 
-export const _state = Symbol("state"), _on = Symbol('on'), _off = Symbol('off')
 
-// registered directives
-export const directive = {}
+export let prefix = ':', signal, effect, computed, batch = (fn) => fn(), untracked = batch;
 
-/**
- * Register a directive with a parsed expression and evaluator.
- * @param {string} name - The name of the directive.
- * @param {(el: Element, state: Object, expr: string, name: 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) => (
-  update = create(el, state, expr, name),
-  evaluate = p(expr, ':'+name),
-  () => update(evaluate(state))
-)
+export let directive = {}, modifier = {}
+
+let currentDir = null;
 
 /**
  * Applies directives to an HTML element and manages its reactive state.
  *
  * @param {Element} [el=document.body] - The target HTML element to apply directives to.
- * @param {Object} [values] - Initial values to populate the element's reactive state.
+ * @param {Object|store} [state] - Initial state values to populate the element's reactive state.
  * @returns {Object} The reactive state object associated with the element.
  */
-export const sprae = (el=document.body, values) => {
+const sprae = (el = document.body, state) => {
   // repeated call can be caused by eg. :each with new objects with old keys
-  if (el[_state]) return Object.assign(el[_state], values)
+  if (el[_state]) return Object.assign(el[_state], state)
+
+  // console.group('sprae', el.outerHTML)
 
   // take over existing state instead of creating a clone
-  let state = store(values || {}), offs = [], fx = []
+  state = store(state || {})
 
-  let init = (el, attrs = el.attributes) => {
-      // we iterate live collection (subsprae can init args)
-      if (attrs) for (let i = 0; i < attrs.length;) {
-        let { name, value } = attrs[i], update, dir
+  let fx = [], offs = [], fn,
+    on = () => (!offs && (offs = fx.map(fn => fn()))),
+    off = () => (offs?.map(off => off()), offs = null)
 
-        // if we have parts meaning there's attr needs to be spraed
-        if (name.startsWith(prefix)) {
-          el.removeAttribute(name);
+  // on/off all effects
+  // we don't call prevOn as convention: everything defined before :else :if won't be disabled by :if
+  // imagine <x :onx="..." :if="..."/> - when :if is false, it disables directives after :if (calls _off) but ignores :onx
+  el[_on] = on
+  el[_off] = off
 
-          // multiple attributes like :id:for=""
-          for (dir of name.slice(prefix.length).split(':')) {
-            update = (directive[dir] || directive.default)(el, value, state, dir)
+  // destroy
+  el[_dispose] ||= () => (el[_off](), el[_off] = el[_on] = el[_dispose] = el[_state] = el[_add] = null)
 
-            // save & start effect
-            fx.push(update)
-            // FIXME: since effect can have async start, we can just use el[_on]
-            offs.push(effect(update))
+  const add = (el, _attrs = el.attributes) => {
+    // we iterate live collection (subsprae can init args)
+    if (_attrs) for (let i = 0; i < _attrs.length;) {
+      let { name, value } = _attrs[i]
 
-            // stop after :each, :if, :with etc.
-            if (el[_state] === null) return
-          }
-        } else i++
-      }
+      if (name.startsWith(prefix)) {
+        el.removeAttribute(name)
 
-      // :if and :each replace element with text node, which tweaks .children length, but .childNodes length persists
-      for (let child of el.childNodes) child.nodeType == 1 && init(child)
-    };
+        // directive initializer can be redefined
+        fx.push(fn = initDirective(el, name, value, state))
+        offs.push(fn())
 
-  init(el);
+        // stop after subsprae like :each, :if, :scope etc.
+        if (_state in el) return
+      } else i++
+    }
 
-  // if element was spraed by inline :with instruction (meaning it has extended state) - skip, otherwise save _state
-  if (!(_state in el)) {
-    el[_state] = state
+    // :if and :each replace element with text node, which tweaks .children length, but .childNodes length persists
+    // for (let i = 0, child; i < (el.childNodes.length); i++) child =  el.childNodes[i], child.nodeType == 1 && add(child)
+    for (let child of [...el.childNodes]) child.nodeType == 1 && add(child)
+  };
 
-    // on/off all effects
-    el[_off] = () => (offs.map(off => off()), offs = [])
-    el[_on] = () => offs = fx.map(f => effect(f))
+  el[_add] = add;
 
-    // destroy
-    el[_dispose] = () => (el[_off](), el[_off] = el[_on] = el[_dispose] = el[_state] = null)
-  }
+  add(el);
+
+  // if element was spraed by inline :with/:if/:each/etc instruction (meaning it has state placeholder) - skip, otherwise save _state
+  if (el[_state] === undefined) el[_state] = state
+
+  // console.groupEnd()
 
   return state;
 }
 
-// configure signals/compile
-// it's more compact than using sprae.signal = signal etc.
-sprae.use = s => (
-  s.signal && use(s),
-  s.compile && (compile = s.compile),
-  s.prefix && (prefix = s.prefix)
-)
 
 /**
- * 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, fn) => {
-  if (fn = memo[expr = expr.trim()]) return fn
+ * Initializes directive (defined by sprae build), returns "on" function that enables it
+ * Multiprop sequences initializer, eg. :a:b..c:d
+ * @type {(el: HTMLElement, name:string, value:string, state:Object) => Function}
+ * */
+const initDirective = (el, attrName, expr, state) => {
+  let cur, // current step callback
+    off // current step disposal
 
-  // static time errors
-  try { fn = compile(expr) }
-  catch (e) { err(e, dir, expr) }
+  let steps = attrName.slice(prefix.length).split('..').map((step, i, { length }) => (
+    // multiple attributes like :id:for=""
+    step.split(prefix).reduce((prev, str) => {
+      let [name, ...mods] = str.split('.');
+      let evaluate = parse(expr, directive[currentDir = name]?.parse)
 
-  // run time errors
-  return memo[expr] = s => {
-    try { return fn(s) }
-    catch(e) { err(e, dir, expr) }
-  }
+      // events have no effects and can be sequenced
+      if (name.startsWith('on')) {
+        let type = name.slice(2),
+          first = e => (call(evaluate(state), e)),
+          fn = applyMods(
+            Object.assign(
+              // single event vs chain
+              length == 1 ? first :
+                e => (cur = (!i ? first : cur)(e), off(), off = steps[(i + 1) % length]()),
+              { target: el, type }
+            ),
+            mods);
+
+        return (_poff) => (_poff = prev?.(), fn.target.addEventListener(type, fn, fn), () => (_poff?.(), fn.target.removeEventListener(type, fn)))
+      }
+
+      // props have no sequences and can be sync
+      let update = (directive[name] || directive['*'])(el, state, expr, name)
+
+      // no-modifiers shortcut
+      if (!mods.length && !prev) return () => update && effect(() => evaluate(state, update))
+
+      let dispose,
+        change = signal(-1), // signal authorized to trigger effect: 0 = init; >0 = trigger
+        count = -1, // called effect count
+
+        // effect applier - first time it applies the effect, next times effect is triggered by change signal
+        fn = throttle(applyMods(() => {
+          if (++change.value) return // all calls except for the first one are handled by effect
+          dispose = effect(() => update && (
+            change.value == count ? fn() : // separate tick makes sure planner effect call is finished before real eval call
+              (count = change.value, evaluate(state, update)) // if changed more than effect called - call it
+          ));
+        }, mods))
+
+      return (_poff) => (
+        _poff = prev?.(),
+        // console.log('ON', name),
+        fn(),
+        ({
+          [name]: () => (
+            // console.log('OFF', name, el),
+            _poff?.(), dispose(), change.value = -1, count = dispose = null
+          )
+        })[name]
+      )
+    }, null)
+  ));
+
+  // off can be changed on the go
+  return () => (off = steps[0]())
 }
-const memo = {};
+
 
 /**
- * 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.
+ * Configure sprae
  */
-export const err = (e, dir = '', expr = '') => {
-  throw Object.assign(e, { message: `∴ ${e.message}\n\n${dir}${expr ? `="${expr}"\n\n` : ""}`, expr })
+export const use = (s) => (
+  s.compile && (compile = s.compile),
+  s.prefix && (prefix = s.prefix),
+  s.signal && (signal = s.signal),
+  s.effect && (effect = s.effect),
+  s.computed && (computed = s.computed),
+  s.batch && (batch = s.batch),
+  s.untracked && (untracked = s.untracked)
+)
+
+
+/**
+ * Lifecycle hanger: makes DOM slightly slower but spraes automatically
+ */
+export const start = (root = document.body, values) => {
+  const state = store(values);
+  sprae(root, state);
+  const mo = new MutationObserver(mutations => {
+    for (const m of mutations) {
+      for (const el of m.addedNodes) {
+        if (el.nodeType === 1 && el[_state] === undefined) {
+          for (const attr of el.attributes) {
+            if (attr.name.startsWith(prefix)) {
+              root[_add](el); break;
+            }
+          }
+        }
+      }
+      // for (const el of m.removedNodes) el[Symbol.dispose]?.()
+    }
+  });
+  mo.observe(root, { childList: true, subtree: true });
+  return state
 }
 
+
 /**
  * Compiles an expression into an evaluator function.
- *
- * @type {(expr: string) => Function}
+ * @type {(dir:string, expr: string, clean?: string => string) => Function}
  */
 export let compile
 
 /**
- * Attributes prefix, by default ':'
+ * Parses an expression into an evaluator function, caching the result for reuse.
+ *
+ * @param {string} expr The expression to parse and compile into a function.
+ * @returns {Function} The compiled evaluator function for the expression.
  */
-export let prefix = ':'
+export const parse = (expr, prepare, _fn) => {
+  if (_fn = parse.cache[expr]) return _fn
+
+  let _expr = expr.trim() || 'undefined'
+  if (prepare) _expr = prepare(_expr)
+
+  // if, const, let - no return
+  if (/^(if|let|const)\b/.test(_expr) || /;/.test(_expr)) ;
+  else _expr = `return ${_expr}`
+
+  // async expression
+  if (/\bawait\s/.test(_expr)) _expr = `return (async()=>{ ${_expr} })()`
+
+  // static time errors
+  try {
+    _fn = compile(_expr)
+    Object.defineProperty(_fn, "name", {value: `∴ ${expr}`})
+  } catch (e) { console.error(`∴ ${e}\n\n${prefix + currentDir}="${expr}"`) }
+
+  // run time errors
+  return parse.cache[expr] = (state, cb, _out) => {
+    try {
+      let result = _fn?.(state)
+      // if cb is given - call it with result and return function that returns last cb result - needed for effect cleanup
+      if (cb) return result?.then ? result.then(v => _out = cb(v)) : _out = cb(result), () => call(_out)
+      else return result
+    } catch (e) {
+      console.error(`∴ ${e}\n\n${prefix + currentDir}="${expr}"`)
+    }
+  }
+}
+parse.cache = {};
+
+
+// apply modifiers to context (from the end due to nature of wrapping ctx.call)
+const applyMods = (fn, mods) => {
+  while (mods.length) {
+    let [name, ...params] = mods.pop().split('-')
+    fn = sx(modifier[name]?.(fn, ...params) ?? fn, fn)
+  }
+  return fn
+}
+
+// soft-extend missing props and ignoring signals
+const sx = (a, b) => { if (a != b) for (let k in b) (a[k] ??= b[k]); return a }
 
 // instantiated <template> fragment holder, like persisting fragment but with minimal API surface
 export const frag = (tpl) => {
@@ -160,4 +269,34 @@ export const frag = (tpl) => {
   }
 }
 
+// if value is function - return result of its call
+export const call = (v, arg) => typeof v === 'function' ? v(arg) : v
+
+// camel to kebab
+export const dashcase = (str) => str.replace(/[A-Z\u00C0-\u00D6\u00D8-\u00DE]/g, (match, i) => (i ? '-' : '') + match.toLowerCase());
+
+// set attr
+export const attr = (el, name, v) => (v == null || v === false) ? el.removeAttribute(name) : el.setAttribute(name, v === true ? "" : v);
+
+// convert any-arg to className string
+export const clsx = (c, _out = []) => !c ? '' : typeof c === 'string' ? c : (
+  Array.isArray(c) ? c.map(clsx) :
+    Object.entries(c).reduce((s, [k, v]) => !v ? s : [...s, k], [])
+).join(' ')
+
+// throttle function to (once per tick or other custom scheduler)
+export const throttle = (fn, schedule = queueMicrotask) => {
+  let _planned = 0;
+  const throttled = (e) => {
+    if (!_planned++) fn(e), schedule((_dirty = _planned > 1) => (
+      _planned = 0, _dirty && throttled(e)
+    ));
+  }
+  return throttled;
+}
+
+export const debounce = (fn, schedule = queueMicrotask, _count = 0) => (arg, _planned=++_count) => schedule(() => (_planned == _count && fn(arg)))
+
+export * from './store.js';
+
 export default sprae

package/directive/class.js

@@ -1,15 +1,11 @@
-import { dir } from "../core.js";
+import { clsx, call } from "../core.js";
 
-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));
-      else if (Array.isArray(v)) v.map(v => v && clsx.add(v));
-      else Object.entries(v).map(([k, v]) => v && clsx.add(k));
-    }
-    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)
-  })
+export default (el, _cur, _new) => (
+  _cur = new Set,
+  (v) => {
+    _new = new Set
+    if (v) clsx(call(v, el.className)).split(' ').map(c => c && _new.add(c))
+    for (let c of _cur) if (_new.has(c)) _new.delete(c); else el.classList.remove(c);
+    for (let c of _cur = _new) el.classList.add(c)
+  }
 )

package/directive/default.js

@@ -1,155 +1,3 @@
-// generic property directive
-import { dir, err } from "../core.js";
+import { attr, call } from "../core.js";
 
-dir('default', (target, state, expr, name) => {
-  // simple prop
-  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.
-  // ona..onb
-  let ctxs = name.split('..').map(e => {
-    let ctx = { evt: '', target, test: () => true };
-    ctx.evt = (e.startsWith('on') ? e.slice(2) : e).replace(/\.(\w+)?-?([-\w]+)?/g,
-      (_, mod, param = '') => (ctx.test = mods[mod]?.(ctx, ...param.split('-')) || ctx.test, '')
-    );
-    return ctx;
-  });
-
-  // add listener with the context
-  let addListener = (fn, { evt, target, test, defer, stop, prevent, immediate, ...opts }, cb) => {
-    if (defer) fn = defer(fn)
-
-    cb = (e) => {
-      try {
-        test(e) && (stop && (immediate ? e.stopImmediatePropagation() : e.stopPropagation()), prevent && e.preventDefault(), fn?.call(state, e))
-      } catch (error) { err(error, `:on${evt}`, fn) }
-    };
-
-    target.addEventListener(evt, cb, opts)
-    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
-  let 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 = {
-  // actions
-  prevent(ctx) { ctx.prevent = true; },
-  stop(ctx) { ctx.stop = true; },
-  immediate(ctx) { ctx.immediate = true; },
-
-  // options
-  once(ctx) { ctx.once = true; },
-  passive(ctx) { ctx.passive = true; },
-  capture(ctx) { ctx.capture = true; },
-
-  // target
-  window(ctx) { ctx.target = window; },
-  document(ctx) { ctx.target = document; },
-  parent(ctx) { ctx.target = ctx.target.parentNode; },
-
-  throttle(ctx, limit=108) { ctx.defer = (fn) => throttle(fn, limit)},
-  debounce(ctx, wait=108) { ctx.defer = (fn) => debounce(fn, wait) },
-
-  // test
-  outside: (ctx) => (e) => {
-    let target = ctx.target;
-    if (target.contains(e.target)) return false;
-    if (e.target.isConnected === false) return false;
-    if (target.offsetWidth < 1 && target.offsetHeight < 1) return false;
-    return true;
-  },
-  self: (ctx) => (e) => e.target === ctx.target,
-
-  // keyboard
-  ctrl: (_, ...param) => (e) => keys.ctrl(e) && param.every((p) => (keys[p] ? keys[p](e) : e.key === p)),
-  shift: (_, ...param) => (e) => keys.shift(e) && param.every((p) => (keys[p] ? keys[p](e) : e.key === p)),
-  alt: (_, ...param) => (e) => keys.alt(e) && param.every((p) => (keys[p] ? keys[p](e) : e.key === p)),
-  meta: (_, ...param) => (e) => keys.meta(e) && param.every((p) => (keys[p] ? keys[p](e) : e.key === p)),
-  // NOTE: we don't expose up/left/right/down as too verbose: can and better be handled/differentiated at once
-  arrow: () => keys.arrow,
-  enter: () => keys.enter,
-  esc: () => keys.esc,
-  tab: () => keys.tab,
-  space: () => keys.space,
-  delete: () => keys.delete,
-  digit: () => keys.digit,
-  letter: () => keys.letter,
-  char: () => keys.char,
-};
-
-// key testers
-const keys = {
-  ctrl: (e) => e.ctrlKey || e.key === "Control" || e.key === "Ctrl",
-  shift: (e) => e.shiftKey || e.key === "Shift",
-  alt: (e) => e.altKey || e.key === "Alt",
-  meta: (e) => e.metaKey || e.key === "Meta" || e.key === "Command",
-  arrow: (e) => e.key.startsWith("Arrow"),
-  enter: (e) => e.key === "Enter",
-  esc: (e) => e.key.startsWith("Esc"),
-  tab: (e) => e.key === "Tab",
-  space: (e) => e.key === " " || e.key === "Space" || e.key === " ",
-  delete: (e) => e.key === "Delete" || e.key === "Backspace",
-  digit: (e) => /^\d$/.test(e.key),
-  letter: (e) => /^\p{L}$/gu.test(e.key),
-  char: (e) => /^\S$/.test(e.key),
-};
-
-// create delayed fns
-const throttle = (fn, limit) => {
-  let pause, planned,
-    block = (e) => {
-      pause = true;
-      setTimeout(() => {
-        pause = false;
-        // if event happened during blocked time, it schedules call by the end
-        if (planned) return (planned = false), block(e), fn(e);
-      }, limit);
-    };
-  return (e) => {
-    if (pause) return (planned = true);
-    block(e);
-    return fn(e);
-  };
-};
-
-const debounce = (fn, wait) => {
-  let timeout;
-  return (e) => {
-    clearTimeout(timeout);
-    timeout = setTimeout(() => {
-      timeout = null;
-      fn(e);
-    }, 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());
-}
+export default (el, st, ex, name) => v => attr(el, name, call(v, el.getAttribute(name)))