sprae 12.3.9 → 12.4.0

package/core.js

@@ -1,23 +1,142 @@
 import store, { _change, _signals } from "./store.js";
 
-export const _dispose = (Symbol.dispose ||= Symbol("dispose")),
-  _state = Symbol("state"),
-  _on = Symbol('on'),
-  _off = Symbol('off'),
-  _add = Symbol('init');
+/** Symbol for disposal (using standard Symbol.dispose if available) */
+export const _dispose = (Symbol.dispose ||= Symbol("dispose"))
 
-export let prefix = ':', signal, effect, computed, batch = (fn) => fn(), untracked = batch;
+/** Symbol for accessing element's reactive state */
+export const _state = Symbol("state")
 
-export let directive = {}, modifier = {}
+/** Symbol for enabling element effects */
+export const _on = Symbol('on')
+
+/** Symbol for disabling element effects */
+export const _off = Symbol('off')
+
+/** Symbol for adding child to element */
+export const _add = Symbol('init')
+
+/** Directive prefix (default: ':') */
+export let prefix = ':';
+
+/**
+ * A reactive signal containing a value.
+ * @template T
+ * @typedef {Object} Signal
+ * @property {T} value - Current value (reading subscribes, writing notifies)
+ * @property {() => T} peek - Read without subscribing
+ * @property {() => T} valueOf - Get value for coercion
+ * @property {() => T} toJSON - Get value for JSON serialization
+ * @property {() => string} toString - Get value as string
+ */
+
+/**
+ * Internal effect function type.
+ * @typedef {Object} EffectFn
+ * @property {Set<Set<EffectFn>>} deps - Dependency sets
+ * @property {() => void} fn - Original function
+ */
+
+/**
+ * Creates a reactive signal.
+ * @template T
+ * @type {<T>(value: T) => Signal<T>}
+ */
+export let signal;
+
+/**
+ * Creates a reactive effect that re-runs when dependencies change.
+ * @type {(fn: () => void | (() => void)) => () => void}
+ */
+export let effect;
+
+/**
+ * Creates a computed signal derived from other signals.
+ * @template T
+ * @type {<T>(fn: () => T) => Signal<T>}
+ */
+export let computed;
+
+/**
+ * Batches multiple signal updates into a single notification.
+ * @template T
+ * @type {<T>(fn: () => T) => T}
+ */
+export let batch = (fn) => fn();
+
+/**
+ * Runs a function without tracking signal dependencies.
+ * @template T
+ * @type {<T>(fn: () => T) => T}
+ */
+export let untracked = batch;
+
+/**
+ * Registry of directive handlers.
+ * @type {Record<string, DirectiveHandler>}
+ */
+export let directive = {};
+
+/**
+ * Registry of modifier functions.
+ * @type {Record<string, ModifierHandler>}
+ */
+export let modifier = {}
 
 let currentDir = null;
+let currentEl = null;
+
+/**
+ * Formats element for error message (minimal context).
+ * @param {Element} [el] - Element to format
+ * @returns {string} Element hint like "<div#id.class>"
+ */
+const elHint = (el) => {
+  if (!el?.tagName) return ''
+  let hint = el.tagName.toLowerCase()
+  if (el.id) hint += '#' + el.id
+  else if (el.className) hint += '.' + el.className.split(' ')[0]
+  return `<${hint}>`
+}
+
+/**
+ * Reports an error with context.
+ * @param {Error|string} e - Error to report
+ * @param {string} [expr] - Expression that caused error
+ */
+const err = (e, expr) => {
+  let msg = `∴ ${e}`
+  if (currentEl) msg += `\n  in ${elHint(currentEl)}`
+  if (currentDir && expr) msg += `\n  ${currentDir}="${expr}"`
+  console.error(msg)
+}
+
+/**
+ * @callback DirectiveHandler
+ * @param {Element} el - Target element
+ * @param {Object} state - Reactive state object
+ * @param {string} expr - Expression string
+ * @param {string} [name] - Directive name with modifiers
+ * @returns {((value: any) => void | (() => void)) | { [Symbol.dispose]: () => void } | void}
+ */
+
+/**
+ * @callback ModifierHandler
+ * @param {Function} fn - Function to modify
+ * @param {...string} args - Modifier arguments (from dash-separated values)
+ * @returns {Function}
+ */
+
+/**
+ * @typedef {Object} SpraeState
+ * @property {Record<string, Signal>} [_signals] - Internal signals map
+ */
 
 /**
  * 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|store} [state] - Initial state values to populate the element's reactive state.
- * @returns {Object} The reactive state object associated with the element.
+ * @param {Object} [state] - Initial state values to populate the element's reactive state.
+ * @returns {SpraeState & Object} The reactive state object associated with the element.
  */
 const sprae = (el = document.body, state) => {
   // repeated call can be caused by eg. :each with new objects with old keys
@@ -50,6 +169,7 @@ const sprae = (el = document.body, state) => {
         el.removeAttribute(name)
 
         currentDir = name;
+        currentEl = el;
 
         // directive initializer can be redefined
         fx.push(start = dir(el, name.slice(prefix.length), value, state)), offs.push(start())
@@ -60,8 +180,12 @@ const sprae = (el = document.body, 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)
+    // real DOM: firstChild/nextSibling avoids array copy; frag.childNodes is already snapshot array
+    if (el.firstChild !== undefined) {
+      let child = el.firstChild, next
+      while (child) (next = child.nextSibling, child.nodeType == 1 && add(child), child = next)
+    }
+    else for (let child of el.childNodes) child.nodeType == 1 && add(child)
   };
 
   add(el);
@@ -75,80 +199,82 @@ const sprae = (el = document.body, state) => {
 }
 
 // directive initializer
+/** @type {(el: Element, name: string, expr: string, state: Object) => () => (() => void) | void} */
 export let dir
 
 /**
- * Compiles an expression into an evaluator function.
- * @type {(dir:string, expr: string, clean?: string => string) => Function}
+ * Compiles an expression string into an evaluator function.
+ * @type {(expr: string) => (state: Object) => any}
  */
 export let compile
 
 /**
  * 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.
+ * @param {string} expr - The expression to parse and compile into a function.
+ * @returns {(state: Object, cb?: (value: any) => any) => any} The compiled evaluator function for the expression.
  */
 export const parse = (expr) => {
   let fn  = cache[expr=expr.trim()]
   if (fn) return fn
 
-  let _expr = (expr || 'undefined') + '\n'
-
-  // if, const, let - no return
-  if (/^(if|let|const)\b/.test(_expr));
-  // first-level semicolons - no return
-  else if (hasSemi(_expr));
-  else _expr = `return ${_expr}`
-
-  // async expression
-  if (/\bawait\s/.test(_expr)) _expr = `return (async()=>{${_expr}})()`
-
   // static time errors
   try {
-    fn = compile(_expr)
+    fn = compile(expr || 'undefined')
     // Object.defineProperty(fn, "name", { value: `∴ ${expr}` })
-  } catch (e) { console.error(`∴ ${e}\n\n${currentDir}="${expr}"`) }
+  } catch (e) { err(e, expr) }
 
   // run time errors
   return cache[expr] = function (state, cb, _out) {
     try {
       let result = fn?.call(this, state)
       // if cb is given (to handle async/await exprs, usually directive update) - call it with result and return a cleanup function
-      if (cb) return result?.then ? (result.then(v => _out = cb(v)), () => typeof _out === 'function' && _out()) : cb(result)
+      if (cb) return result?.then
+        ? (result.then(v => _out = cb(v)).catch(e => err(e, expr)), () => typeof _out === 'function' && _out())
+        : cb(result)
       else return result
     } catch (e) {
-      console.error(`∴ ${e}\n\n${currentDir}="${expr}"`)
+      err(e, expr)
     }
   }
 }
 const cache = {};
 
-const hasSemi = s => {
-  for (let d=0,i=0;i<s.length;i++) {
-    if (s[i]=='{') d++
-    else if (s[i]=='}') d--
-    else if (s[i]==';' && !d) return true
-  }
-  return false
-}
 
+/**
+ * @typedef {Object} SpraeConfig
+ * @property {(expr: string) => (state: Object) => any} [compile] - Custom expression compiler
+ * @property {string} [prefix] - Directive prefix (default: ':')
+ * @property {<T>(value: T) => Signal<T>} [signal] - Signal factory
+ * @property {(fn: () => void | (() => void)) => () => void} [effect] - Effect factory
+ * @property {<T>(fn: () => T) => Signal<T>} [computed] - Computed factory
+ * @property {<T>(fn: () => T) => T} [batch] - Batch function
+ * @property {<T>(fn: () => T) => T} [untracked] - Untracked function
+ * @property {(el: Element, name: string, expr: string, state: Object) => () => (() => void) | void} [dir] - Directive initializer
+ */
 
 /**
- * Configure sprae
+ * Configure sprae with custom signals, compiler, or prefix.
+ * @param {SpraeConfig} config - Configuration options
+ * @returns {void}
  */
-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),
-  s.dir && (dir = s.dir)
+export const use = (config) => (
+  config.compile && (compile = config.compile),
+  config.prefix && (prefix = config.prefix),
+  config.signal && (signal = config.signal),
+  config.effect && (effect = config.effect),
+  config.computed && (computed = config.computed),
+  config.batch && (batch = config.batch),
+  config.untracked && (untracked = config.untracked),
+  config.dir && (dir = config.dir)
 )
 
-// modifier applier
+/**
+ * Applies modifiers to a function.
+ * @param {Function & { target?: Element }} fn - Function to decorate
+ * @param {string[]} mods - Modifier names with arguments (e.g., ['throttle-500', 'prevent'])
+ * @returns {Function} Decorated function
+ */
 export const decorate = (fn, mods) => {
   while (mods.length) {
     let [name, ...params] = mods.pop().split('-'), mod = modifier[name], wrapFn
@@ -162,7 +288,21 @@ export const decorate = (fn, mods) => {
   return fn
 }
 
-// instantiated <template> fragment holder, like persisting fragment but with minimal API surface
+/**
+ * @typedef {Object} FragmentLike
+ * @property {Node[]} childNodes - Child nodes of the fragment
+ * @property {DocumentFragment} content - The document fragment content
+ * @property {() => void} remove - Remove the fragment from DOM
+ * @property {(el: Node) => void} replaceWith - Replace the fragment with an element
+ * @property {Attr[]} attributes - Attributes from the original template
+ * @property {(name: string) => void} removeAttribute - Remove an attribute
+ */
+
+/**
+ * Creates a fragment holder from a template element with minimal API surface.
+ * @param {HTMLTemplateElement | FragmentLike} tpl - Template element or existing fragment
+ * @returns {FragmentLike} Fragment-like object
+ */
 export const frag = (tpl) => {
   if (!tpl.nodeType) return tpl // existing tpl
 
@@ -173,7 +313,6 @@ export const frag = (tpl) => {
     childNodes = (content.append(ref), [...content.childNodes])
 
   return {
-    // get parentNode() { return childNodes[0].parentNode },
     childNodes,
     content,
     remove: () => content.append(...childNodes),
@@ -184,25 +323,45 @@ export const frag = (tpl) => {
     },
     attributes,
     removeAttribute(name) { attributes.splice(attributes.findIndex(a => a.name === name), 1) },
-    // setAttributeNode() { }
   }
 }
 
-// camel to kebab
+/**
+ * Converts camelCase to kebab-case.
+ * @param {string} str - String to convert
+ * @returns {string} Kebab-case string
+ */
 export const dashcase = (str) => str.replace(/[A-Z\u00C0-\u00D6\u00D8-\u00DE]/g, (match, i) => (i ? '-' : '') + match.toLowerCase());
 
-// set attr
+/**
+ * Sets or removes an attribute on an element.
+ * @param {Element} el - Target element
+ * @param {string} name - Attribute name
+ * @param {string | boolean | null | undefined} v - Attribute value (null/false removes, true sets empty)
+ * @returns {void}
+ */
 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
+/**
+ * Converts class input to className string (like clsx/classnames).
+ * @param {string | string[] | Record<string, boolean> | null | undefined} c - Class input
+ * @returns {string} Space-separated class 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, arg;
+/**
+ * Throttles a function to run at most once per tick (or custom scheduler).
+ * Fires on leading edge, then on trailing edge if called during throttle.
+ * @template {Function} T
+ * @param {T} fn - Function to throttle
+ * @param {number|Function} [ms] - Delay in ms or scheduler function (default: microtask)
+ * @returns {T} Throttled function
+ */
+export const throttle = (fn, ms) => {
+  let _planned = 0, arg, schedule = typeof ms === 'function' ? ms : ms ? (fn) => setTimeout(fn, ms) : queueMicrotask;
   const throttled = (e) => {
     arg = e
     if (!_planned++) fn(arg), schedule((_dirty = _planned > 1) => (
@@ -212,8 +371,26 @@ export const throttle = (fn, schedule = queueMicrotask) => {
   return throttled;
 }
 
-export const debounce = (fn, schedule = queueMicrotask, _count = 0) => (arg, _planned = ++_count) => schedule(() => (_planned == _count && fn(arg)))
+/**
+ * Debounces a function to run after a delay since the last call.
+ * @template {Function} T
+ * @param {T} fn - Function to debounce
+ * @param {number|Function} [ms] - Delay in ms or scheduler function (default: microtask)
+ * @param {boolean} [immediate=false] - Fire on leading edge instead of trailing
+ * @returns {T} Debounced function
+ */
+export const debounce = (fn, ms, immediate) => {
+  let schedule = typeof ms === 'function' ? ms : ms ? (fn) => setTimeout(fn, ms) : queueMicrotask;
+  return immediate
+    ? ((_blocked) => (arg) => !_blocked && (fn(arg), _blocked = 1, schedule(() => _blocked = 0)))()
+    : ((_count = 0) => (arg, _c = ++_count) => schedule(() => _c == _count && fn(arg)))()
+}
 
+/**
+ * Parses time string to milliseconds. Supports: 100, 100ms, 1s, 1m
+ * @param {string|number} t - Time value
+ * @returns {number} Milliseconds
+ */
 export * from './store.js';
 
 export default sprae

package/directive/_.js

@@ -1,3 +1,11 @@
 import { attr } from "../core.js";
 
+/**
+ * Default attribute directive - sets any attribute value.
+ * @param {Element} el - Target element
+ * @param {Object} st - State object
+ * @param {string} ex - Expression
+ * @param {string} name - Attribute name
+ * @returns {(v: any) => void} Update function
+ */
 export default (el, st, ex, name) => v => attr(el, name, typeof v === 'function' ? v(el.getAttribute(name)) : v)

package/directive/class.js

@@ -1,5 +1,14 @@
 import { clsx, decorate } from "../core.js";
 
+/**
+ * Class directive - manages CSS classes reactively.
+ * Supports strings, arrays, and objects (like clsx/classnames).
+ * @param {Element} el - Target element
+ * @param {Object} st - State object
+ * @param {string} ex - Expression
+ * @param {string} name - Directive name with modifiers
+ * @returns {(v: string | string[] | Record<string, boolean>) => void} Update function
+ */
 export default (el, st, ex, name) => {
   let _cur = new Set, _new
 

package/directive/each.js

@@ -1,5 +1,13 @@
 import sprae, { store, parse, _state, effect, _change, _signals, frag, throttle, debounce } from "../core.js";
 
+/**
+ * Each directive - renders list items from array/object/number.
+ * Syntax: `:each="item in items"` or `:each="(item, idx) of items"`
+ * @param {HTMLTemplateElement | Element} tpl - Template element
+ * @param {Object} state - State object
+ * @param {string} expr - Iterator expression
+ * @returns {{ eval: Function, [Symbol.dispose]: () => void }} Directive result
+ */
 export default (tpl, state, expr) => {
   const [lhs, rhs] = expr.split(/\bin|of\b/)
 
@@ -11,7 +19,6 @@ export default (tpl, state, expr) => {
   // we re-create items any time new items are produced
   let cur, keys, items, prevl = 0
 
-  // FIXME: pass items to update instead of global
   let update = throttle(() => {
     let i = 0, newItems = items, newl = newItems.length
 
@@ -32,27 +39,32 @@ export default (tpl, state, expr) => {
       // update
       else while (i < prevl) cur[i] = newItems[i++]
 
+      // batch append using DocumentFragment for efficiency
+      let batchSize = newl - i
+      let batch = batchSize > 1 ? document.createDocumentFragment() : null
+      let pending = batch ? [] : null
+
       // append
       for (; i < newl; i++) {
         cur[i] = newItems[i]
 
-        let idx = i,
-          // inherited state must be cheaper in terms of memory and faster in terms of performance, compared to creating a proxy store
-          // subscope = store({
-          //   // NOTE: since we simulate signal, we have to make sure it's actual signal, not fake one
-          //   // FIXME: try to avoid this, we also have issue with wrongly calling dispose in store on delete
-          //   [itemVar]: cur[_signals]?.[idx]?.peek ? cur[_signals]?.[idx] : cur[idx],
-          //   [idxVar]: keys ? keys[idx] : idx
-          // }, state)
-        subscope = Object.create(state, {
-          [itemVar]: { get: () => cur[idx] },
-          [idxVar]: { value: keys ? keys[idx] : idx }
-        })
-
+        let idx = i
         let el = tpl.content ? frag(tpl) : tpl.cloneNode(true);
-
-        holder.before(el.content || el);
-        sprae(el, subscope);
+        // el.content is DocumentFragment for frag() output, el itself for cloneNode
+        let insertNode = el.content || el
+
+        // collect for batch insert
+        if (batch) {
+          batch.appendChild(insertNode)
+          pending.push([ el, idx ])
+        } else {
+          holder.before(insertNode)
+          let subscope = Object.create(state, {
+            [itemVar]: { get: () => cur[idx] },
+            [idxVar]: { value: keys ? keys[idx] : idx }
+          })
+          sprae(el, subscope)
+        }
 
         // signal/holder disposal removes element
         let _prev = ((cur[_signals] ||= [])[i] ||= {})[Symbol.dispose]
@@ -60,6 +72,18 @@ export default (tpl, state, expr) => {
           _prev?.(), el[Symbol.dispose]?.(), el.remove()
         };
       }
+
+      // batch insert all at once, then sprae
+      if (batch) {
+        holder.before(batch)
+        for (let [el, idx] of pending) {
+          let subscope = Object.create(state, {
+            [itemVar]: { get: () => cur[idx] },
+            [idxVar]: { value: keys ? keys[idx] : idx }
+          })
+          sprae(el, subscope)
+        }
+      }
     }
 
     prevl = newl

package/directive/else.js

@@ -1,7 +1,11 @@
 import { _on, _off, _state, frag } from '../core.js';
 
-
-// NOTE: we can reach :else counterpart whereas prev :else :if is on hold
+/**
+ * Else directive - conditional branch following :if.
+ * Can be used as `:else` or `:else :if="condition"`.
+ * @param {Element | HTMLTemplateElement} el - Element with directive
+ * @returns {() => void} Update function
+ */
 export default (el) => {
   let _el, _prev = el
 

package/directive/event.js

@@ -1,5 +1,14 @@
 import { parse, decorate } from "../core.js"
 
+/**
+ * Event directive - attaches event listeners with modifiers.
+ * Syntax: `:onclick="handler"` or `:onclick.prevent.stop="handler"`
+ * @param {Element} el - Target element
+ * @param {Object} state - State object
+ * @param {string} expr - Handler expression
+ * @param {string} name - Event name with modifiers (e.g., 'onclick.prevent')
+ * @returns {{ [Symbol.dispose]: () => void }} Disposal object
+ */
 export default (el, state, expr, name) => {
   // wrap inline cb into function
   // if (!/^(?:[\w$]+|\([^()]*\))\s*=>/.test(expr) && !/^function\b/.test(expr)) expr = `()=>{${expr}}`;

package/directive/fx.js

@@ -1 +1,6 @@
+/**
+ * Effect directive - runs side effects.
+ * Calls function result if expression evaluates to a function.
+ * @returns {(fn: any) => any} Update function
+ */
 export default () => (fn) => typeof fn === 'function' && fn()

package/directive/hidden.js

@@ -0,0 +1,6 @@
+/**
+ * Hidden directive - toggles the hidden attribute.
+ * @param {Element} el - Target element
+ * @returns {(value: any) => boolean} Update function
+ */
+export default (el) => (value) => el.hidden = !!value

package/directive/html.js

@@ -1,7 +1,30 @@
-import sprae, { _dispose, frag } from "../core.js"
+import sprae, { _dispose } from "../core.js"
 
-export default (el, state) => (
-  // <template :html="a"/> or previously initialized template
-  el.content && el.replaceWith(el = frag(el).childNodes[0]),
-  v => (v = typeof v === 'function' ? v(el.innerHTML) : v, el.innerHTML = v == null ? "" : v, sprae(el, state), el[_dispose])
-)
+/**
+ * HTML directive - sets innerHTML and initializes nested directives.
+ * Supports templates for fragment insertion.
+ * @param {Element | HTMLTemplateElement} el - Target element
+ * @param {Object} state - State object
+ * @returns {(v: string | ((html: string) => string)) => void | (() => void)} Update function
+ */
+export default (el, state) => {
+  // <template :html="a"/> - fragment case: use placeholder + range
+  if (el.content) {
+    let start = document.createTextNode(''),
+        end = document.createTextNode(''),
+        range = document.createRange()
+    el.replaceWith(start, end)
+    return v => {
+      v = typeof v === 'function' ? v('') : v
+      range.setStartAfter(start)
+      range.setEndBefore(end)
+      range.deleteContents()
+      if (v != null && v !== '') {
+        let frag = range.createContextualFragment(v)
+        sprae(frag, state)
+        range.insertNode(frag)
+      }
+    }
+  }
+  return v => (v = typeof v === 'function' ? v(el.innerHTML) : v, el.innerHTML = v == null ? "" : v, sprae(el, state), el[_dispose])
+}

package/directive/if.js

@@ -1,7 +1,12 @@
-// "centralized" version of :if
 import sprae, { throttle, _on, _off, _state, frag } from '../core.js';
 
-// :if="a"
+/**
+ * Conditional directive - shows/hides element based on condition.
+ * Works with :else and :else :if for branching.
+ * @param {Element | HTMLTemplateElement} el - Target element
+ * @param {Object} state - State object
+ * @returns {(value: any) => void} Update function
+ */
 export default (el, state) => {
   let _holder, _el, _match
 

package/directive/portal.js

@@ -0,0 +1,38 @@
+/**
+ * Portal directive - teleports element to another container.
+ * Value can be selector string, element, or falsy to return home.
+ * @param {Element} el - Element to teleport
+ * @param {Object} state - State object
+ * @param {string} expr - Expression
+ * @returns {(value: string | Element | null | false) => void} Update function
+ */
+export default (el, state, expr) => {
+  const comment = document.createComment(':portal')
+  let currentTarget = null
+
+  // Insert placeholder before element
+  el.before(comment)
+
+  return (value) => {
+    // Resolve target: selector string, element, or null/false to return home
+    // For selectors, first try within the same root, then document
+    const root = el.getRootNode()
+    const target = typeof value === 'string'
+      ? (root.querySelector?.(value) || document.querySelector(value))
+      : value instanceof Element ? value
+        : value ? document.body : null
+
+    // No change needed
+    if (target === currentTarget) return
+
+    if (target) {
+      // Move to target
+      target.appendChild(el)
+    } else {
+      // Return home (after placeholder)
+      comment.after(el)
+    }
+
+    currentTarget = target
+  }
+}

package/directive/ref.js

@@ -1,6 +1,14 @@
 import { parse } from "../core.js"
 import { setter } from "./value.js"
 
+/**
+ * Ref directive - stores element reference in state.
+ * If expression is a function, calls it with element (returns dispose).
+ * @param {Element} el - Target element
+ * @param {Object} state - State object
+ * @param {string} expr - Variable name or function expression
+ * @returns {{ [Symbol.dispose]: () => void } | void} Disposal object or void
+ */
 export default (el, state, expr) => {
   let fn = parse(expr)(state)