@symbo.ls/element 3.14.0

package/src/delegate.js

@@ -0,0 +1,163 @@
+'use strict'
+
+// Event Delegation - single root listener per event type
+// Uses WeakMap to associate DOM nodes with their handlers
+
+import { DELEGATED_EVENTS, LIFECYCLE_EVENTS, PASSIVE_EVENTS } from './registry.js'
+import { pushConfig, popConfig } from '@symbo.ls/scratch'
+
+const delegateRoots = new WeakMap()
+
+// Reused listener-option objects — browsers treat `{ passive: true }` as
+// read-only metadata, so a single shared instance per shape is safe and
+// avoids a per-listener allocation.
+const PASSIVE_BUBBLE = { passive: true }
+const PASSIVE_CAPTURE = { passive: true, capture: true }
+
+const listenerOptions = (eventName, useCapture) => {
+  if (PASSIVE_EVENTS.has(eventName)) {
+    return useCapture ? PASSIVE_CAPTURE : PASSIVE_BUBBLE
+  }
+  return useCapture || false
+}
+
+function getDelegateRoot(rootNode) {
+  let root = delegateRoots.get(rootNode)
+  if (!root) {
+    root = { handlers: new Map(), installed: new Set() }
+    delegateRoots.set(rootNode, root)
+  }
+  return root
+}
+
+function installDelegatedEvent(eventName, rootNode) {
+  const root = getDelegateRoot(rootNode)
+  if (root.installed.has(eventName)) return
+
+  root.installed.add(eventName)
+
+  // Use capture for non-bubbling events (focus/blur, mouseenter/mouseleave)
+  const useCapture = eventName === 'focus' || eventName === 'blur' ||
+                     eventName === 'focusin' || eventName === 'focusout' ||
+                     eventName === 'mouseenter' || eventName === 'mouseleave'
+
+  const isEnterLeave = eventName === 'mouseenter' || eventName === 'mouseleave'
+
+  rootNode.addEventListener(eventName, (event) => {
+    let target = event.target
+
+    while (target && target !== rootNode) {
+      const handlerMap = root.handlers.get(eventName)
+      if (handlerMap) {
+        const handler = handlerMap.get(target)
+        if (handler) {
+          // For mouseenter/mouseleave: only fire if relatedTarget is outside this node
+          // (prevents firing when moving between children inside the element)
+          if (isEnterLeave && event.relatedTarget && target.contains(event.relatedTarget)) {
+            target = target.parentNode
+            continue
+          }
+          handler(event)
+          if (event.cancelBubble) return
+        }
+      }
+      target = target.parentNode
+    }
+  }, listenerOptions(eventName, useCapture))
+}
+
+// Register a delegated event handler for a DOM node
+export function addDelegatedEvent(eventName, node, handler, rootNode) {
+  if (!rootNode) rootNode = node.ownerDocument?.documentElement || node.getRootNode()
+
+  const root = getDelegateRoot(rootNode)
+
+  // Ensure the root listener is installed
+  installDelegatedEvent(eventName, rootNode)
+
+  // Get or create the handler map for this event
+  if (!root.handlers.has(eventName)) {
+    root.handlers.set(eventName, new WeakMap())
+  }
+
+  root.handlers.get(eventName).set(node, handler)
+}
+
+// Remove a delegated event handler
+export function removeDelegatedEvent(eventName, node, rootNode) {
+  if (!rootNode) rootNode = node.ownerDocument?.documentElement || node.getRootNode()
+
+  const root = delegateRoots.get(rootNode)
+  if (!root) return
+
+  const handlerMap = root.handlers.get(eventName)
+  if (handlerMap) {
+    handlerMap.delete(node)
+  }
+}
+
+// Check if an event name should be delegated
+export function isDelegatable(eventName) {
+  return DELEGATED_EVENTS.has(eventName) && !LIFECYCLE_EVENTS.has(eventName)
+}
+
+// Register event from element's `on` object or props
+export function registerEvent(eventName, element, handler) {
+  const { node, context } = element
+  if (!node) return
+
+  // Capture config reference at registration time so it remains
+  // stable across async boundaries. The document is stored on the
+  // config, so getActiveDocument() resolves it via the config stack.
+  const ds = context?.designSystem
+
+  const wrappedHandler = (event) => {
+    // Push the element's design system config so runtime CSS injections
+    // and token resolution use the correct app scope. The document is
+    // stored on the config, so getActiveDocument() resolves it too.
+    if (ds) pushConfig(ds)
+    try {
+      const result = handler.call(element, event, element, element.state, context)
+      if (result && typeof result.then === 'function') {
+        // For async handlers, re-scope config around the promise
+        // resolution so continuations see the right config.
+        result
+          .catch(err => {
+            element.error = err
+            console.error('[DOMQL] Async event error:', err)
+          })
+          .finally(() => {
+            if (ds) popConfig()
+          })
+        // Don't pop in the outer finally — the promise chain owns it
+        return
+      }
+    } catch (err) {
+      element.error = err
+      console.error('[DOMQL] Event error:', err)
+      if (context?.strictMode) throw err
+    }
+    // Sync path — pop immediately
+    if (ds) popConfig()
+  }
+
+  if (isDelegatable(eventName)) {
+    // Find root node for delegation
+    const rootNode = context?.rootNode || node.ownerDocument?.documentElement
+    addDelegatedEvent(eventName, node, wrappedHandler, rootNode)
+  } else {
+    // Non-delegatable events (e.g., transitionend, animationend, resize)
+    node.addEventListener(eventName, wrappedHandler, listenerOptions(eventName, false))
+  }
+
+  // Track for cleanup
+  if (!element.__ref.__eventCleanup) element.__ref.__eventCleanup = []
+  element.__ref.__eventCleanup.push(() => {
+    if (isDelegatable(eventName)) {
+      const rootNode = context?.rootNode || node.ownerDocument?.documentElement
+      removeDelegatedEvent(eventName, node, rootNode)
+    } else {
+      node.removeEventListener(eventName, wrappedHandler, listenerOptions(eventName, false))
+    }
+  })
+}

package/src/dispose.js

@@ -0,0 +1,76 @@
+'use strict'
+
+// Element disposal - cleanup effects, events, and children
+
+export function dispose(element) {
+  if (!element) return
+
+  const ref = element.__ref
+  if (!ref) return
+
+  // User-defined cleanup hooks fire BEFORE we tear refs/state/effects down,
+  // so handlers can still read state and call methods on the element.
+  // `onBeforeRemove` is for last-chance cleanup (close sockets, cancel
+  // in-flight requests); `onRemove` is the canonical post-unmount hook.
+  try { if (typeof element.onBeforeRemove === 'function') element.onBeforeRemove(element, element.state, element.context) } catch (e) { console.error('[smbls] onBeforeRemove error:', e) }
+
+  // Dispose all reactive effects
+  if (ref.__effects) {
+    for (let i = 0; i < ref.__effects.length; i++) {
+      ref.__effects[i].dispose()
+    }
+    ref.__effects.length = 0
+  }
+
+  // Cleanup event listeners
+  if (ref.__eventCleanup) {
+    for (let i = 0; i < ref.__eventCleanup.length; i++) {
+      ref.__eventCleanup[i]()
+    }
+    ref.__eventCleanup.length = 0
+  }
+
+  // Recursively dispose children
+  if (ref.__children) {
+    for (let i = 0; i < ref.__children.length; i++) {
+      const childKey = ref.__children[i]
+      const child = element[childKey]
+      if (child && child.__ref) {
+        dispose(child)
+      }
+    }
+    ref.__children.length = 0
+  }
+
+  // Remove DOM node
+  if (element.node?.parentNode) {
+    element.node.remove()
+  }
+
+  // Destroy state if owned
+  if (element.state?.destroy && element.state.__element === element) {
+    element.state.destroy()
+  }
+
+  // Remove from parent's tracking
+  if (element.parent?.__ref?.__children) {
+    const idx = element.parent.__ref.__children.indexOf(element.key)
+    if (idx !== -1) {
+      element.parent.__ref.__children.splice(idx, 1)
+    }
+    delete element.parent[element.key]
+  }
+
+  // Fire onRemove AFTER DOM detach + state.destroy but BEFORE clearing refs,
+  // so the hook can still read element.key / element.parent for logging.
+  try { if (typeof element.onRemove === 'function') element.onRemove(element) } catch (e) { console.error('[smbls] onRemove error:', e) }
+
+  // Clear references
+  element.node = null
+  element.parent = null
+  element.__ref = null
+}
+
+export function remove() {
+  dispose(this)
+}

package/src/extends.js

@@ -0,0 +1,105 @@
+'use strict'
+
+// Extends resolution - merges component inheritance chains
+// Uses structural sharing where possible (no deepClone)
+
+const extendsCache = new WeakMap()
+
+export function applyExtends(element, definition, options) {
+  let ext = definition.extends || definition.extend
+  if (!ext) return
+
+  const context = element.context || options?.context || {}
+  const components = context.components || {}
+
+  // Normalize to array
+  if (!Array.isArray(ext)) ext = [ext]
+
+  // Resolve extends chain
+  for (let i = 0; i < ext.length; i++) {
+    const base = resolveExtend(ext[i], components)
+    // Skip self-references (component extends itself by same name)
+    if (base && base !== definition) {
+      mergeBase(element, base, options, new Set([definition]))
+    }
+  }
+}
+
+function resolveExtend(ext, components) {
+  if (typeof ext === 'string') {
+    // Support nested child access: 'Component > Child > SubChild'
+    if (ext.includes('>')) {
+      const parts = ext.split('>').map(s => s.trim())
+      let resolved = components[parts[0]] || components[`smbls.${parts[0]}`]
+      for (let i = 1; i < parts.length && resolved; i++) {
+        resolved = resolved[parts[i]]
+      }
+      return resolved || null
+    }
+    return components[ext] || components[`smbls.${ext}`] || null
+  }
+  if (typeof ext === 'object' && ext !== null) {
+    return ext
+  }
+  return null
+}
+
+function mergeBase(element, base, options, visited = new Set()) {
+  if (visited.has(base)) return
+  visited.add(base)
+
+  // Recursively resolve base's own extends first (support both 'extends' and 'extend')
+  const baseExtends = base.extends || base.extend
+  if (baseExtends) {
+    const context = element.context || options?.context || {}
+    const components = context.components || {}
+    let baseExt = baseExtends
+    if (!Array.isArray(baseExt)) baseExt = [baseExt]
+    for (let i = 0; i < baseExt.length; i++) {
+      const ancestor = resolveExtend(baseExt[i], components)
+      if (ancestor) mergeBase(element, ancestor, options, visited)
+    }
+  }
+
+  // Merge properties from base onto element (later extends override earlier)
+  for (const key in base) {
+    if (key === 'extends' || key === 'extend') continue
+
+    const val = base[key]
+    if (element[key] === undefined) {
+      if (val && typeof val === 'object' && !Array.isArray(val) && typeof val !== 'function') {
+        element[key] = { ...val }
+      } else {
+        element[key] = val
+      }
+    } else if (typeof element[key] === 'object' && typeof val === 'object' &&
+               !Array.isArray(element[key]) && !Array.isArray(val) &&
+               element[key] !== null && val !== null) {
+      // Deep merge objects — element (child) values override base values
+      // element[key] is already set from a previous extends; val is the newer/more-specific definition
+      // The newer definition (val) should override the older ancestor (element[key])
+      element[key] = deepMergeChild(element[key], val)
+    } else {
+      // Later extends override earlier for primitives/functions
+      element[key] = val
+    }
+  }
+}
+
+// Deep merge where override wins over base at every level
+function deepMergeChild(base, override) {
+  const result = { ...base }
+  for (const key in override) {
+    const baseVal = result[key]
+    const overVal = override[key]
+    if (baseVal && overVal &&
+        typeof baseVal === 'object' && typeof overVal === 'object' &&
+        !Array.isArray(baseVal) && !Array.isArray(overVal) &&
+        typeof baseVal !== 'function' && typeof overVal !== 'function') {
+      result[key] = deepMergeChild(baseVal, overVal)
+    } else {
+      result[key] = overVal
+    }
+  }
+  return result
+}

package/src/index.js

@@ -0,0 +1,8 @@
+export { create, default } from './create.js'
+export { update } from './update.js'
+export { dispose, remove } from './dispose.js'
+export { REGISTRY, LIFECYCLE_EVENTS, DELEGATED_EVENTS, MIXINS } from './registry.js'
+export { addDelegatedEvent, removeDelegatedEvent, registerEvent } from './delegate.js'
+export { cacheNode, detectTag, createHTMLNode, isValidTag, isSvgTag, SVG_TAGS } from './cache.js'
+export { applyExtends } from './extends.js'
+export { addMethods } from './methods.js'

package/src/methods.js

@@ -0,0 +1,257 @@
+'use strict'
+
+import { update } from './update.js'
+import { remove } from './dispose.js'
+import { CSS_PROPS_REGISTRY } from 'css-in-props/src/props'
+import {
+  getDB,
+  getQuery,
+  getRootData,
+  getRootState as _getRootState,
+  getRoot as _getRoot,
+  getRootContext as _getRootContext,
+  getContext as _getContext,
+  getChildren,
+  getPath,
+  nextElement,
+  previousElement,
+  verbose as _verbose,
+  warn as _warn,
+  error as _error,
+  variables as _variables,
+  spotByPath
+} from '@symbo.ls/utils'
+
+// Forward warnings + errors to the analyze plugin (when present) so they
+// appear in the audit log alongside lifecycle events. Falls through to the
+// original env-gated console.warn / throw.
+function emitToAnalyze(element, level, params) {
+  const a = element?.context?.analyze
+  if (!a || !a.emit) return
+  if (level === 'warn' && !a.shouldCapture('warnings')) return
+  if (level === 'error' && !a.shouldCapture('errors')) return
+  const msg = params.map(p => p?.message || (typeof p === 'string' ? p : null)).filter(Boolean).join(' ')
+  a.emit({
+    id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+    ts: Date.now(),
+    type: level === 'error' ? 'error' : 'warning',
+    level,
+    hook: level === 'error' ? 'el.error' : 'el.warn',
+    element: {
+      key: element.key != null ? String(element.key) : null,
+      name: element.__name || null,
+      tag: element.tag || null
+    },
+    message: msg || null,
+    args: params
+  })
+}
+
+function elWarn(...params) {
+  emitToAnalyze(this, 'warn', params)
+  return _warn.apply(this, params)
+}
+
+function elError(...params) {
+  emitToAnalyze(this, 'error', params)
+  return _error.apply(this, params)
+}
+
+// Shared prototype for all elements — methods are defined once, shared by all instances
+const elementProto = {
+  update,
+  remove,
+  getDB,
+  getQuery,
+  getRootData,
+  getChildren,
+  getPath,
+  nextElement,
+  previousElement,
+  verbose: _verbose,
+  warn: elWarn,
+  error: elError,
+  variables: _variables,
+  spotByPath,
+
+  set(content, options) {
+    this.removeContent()
+    if (content != null) {
+      const createFn = this.context?.__create
+      if (createFn) createFn(content, this, 'content', options)
+    }
+  },
+
+  reset(options) {
+    const createFn = this.context?.__create
+    if (!createFn) return this
+    const parent = this.parent
+    const key = this.key
+    const def = this.parse()
+    this.remove()
+    return createFn(def, parent, key, options)
+  },
+
+  lookup(predicate) {
+    let current = this.parent
+    while (current) {
+      if (typeof predicate === 'function') {
+        if (predicate(current)) return current
+      } else if (typeof predicate === 'string') {
+        if (current.key === predicate) return current
+        if (current[predicate] && current[predicate].__ref)
+          return current[predicate]
+      }
+      current = current.parent
+    }
+    return null
+  },
+
+  lookdown(predicate) {
+    const ref = this.__ref
+    if (!ref?.__children) return null
+    for (const key of ref.__children) {
+      const child = this[key]
+      if (!child) continue
+      if (typeof predicate === 'function') {
+        if (predicate(child)) return child
+      } else if (typeof predicate === 'string') {
+        if (child.key === predicate) return child
+      }
+      const found = child.lookdown?.(predicate)
+      if (found) return found
+    }
+    return null
+  },
+
+  lookdownAll(predicate, results = []) {
+    const ref = this.__ref
+    if (!ref?.__children) return results
+    for (const key of ref.__children) {
+      const child = this[key]
+      if (!child) continue
+      if (typeof predicate === 'function') {
+        if (predicate(child)) results.push(child)
+      } else if (typeof predicate === 'string') {
+        if (child.key === predicate) results.push(child)
+      }
+      child.lookdownAll?.(predicate, results)
+    }
+    return results
+  },
+
+  getRef() {
+    return this.__ref
+  },
+
+  getRoot: _getRoot,
+  getRootState: _getRootState,
+  getRootContext: _getRootContext,
+  getContext: _getContext,
+
+  parse(exclude) {
+    const result = {}
+    const excludeSet = exclude ? new Set(exclude) : null
+    for (const key in this) {
+      if (key === 'parent' || key === 'node' || key === '__ref') continue
+      if (typeof this[key] === 'function') continue
+      if (excludeSet?.has(key)) continue
+      result[key] = this[key]
+    }
+    return result
+  },
+
+  parseDeep(exclude) {
+    const result = this.parse(exclude)
+    const ref = this.__ref
+    if (ref?.__children) {
+      for (const key of ref.__children) {
+        if (this[key]?.parseDeep) {
+          result[key] = this[key].parseDeep(exclude)
+        }
+      }
+    }
+    return result
+  },
+
+  keys() {
+    return Object.keys(this)
+  },
+
+  log(...keys) {
+    if (keys.length) {
+      const data = {}
+      for (const k of keys) data[k] = this[k]
+      console.log(data)
+    } else {
+      console.log(this)
+    }
+  },
+
+  setProps(props, options) {
+    return this.update(props, options)
+  },
+
+  setNodeStyles(styles) {
+    if (!this.node?.style) return
+    for (const prop in styles) {
+      this.node.style[prop] = styles[prop]
+    }
+  },
+
+  call(methodName, ...args) {
+    const ctx = this.context
+    const method =
+      ctx?.methods?.[methodName] ||
+      ctx?.functions?.[methodName] ||
+      ctx?.utils?.[methodName] ||
+      this[methodName]
+    if (typeof method === 'function') {
+      return method.call(this, ...args)
+    }
+  },
+
+  removeContent() {
+    const ref = this.__ref
+    if (!ref?.__children) return
+    const contentChild = this.content
+    if (contentChild?.remove) {
+      contentChild.remove()
+      delete this.content
+      const idx = ref.__children.indexOf('content')
+      if (idx !== -1) ref.__children.splice(idx, 1)
+    }
+    if (contentChild?.node?.parentNode) {
+      contentChild.node.parentNode.removeChild(contentChild.node)
+    }
+  }
+}
+
+// Cache per-context prototypes so we don't recreate them for every element
+const contextProtoCache = new WeakMap()
+
+function getContextProto(ctx) {
+  if (!ctx) return elementProto
+  let proto = contextProtoCache.get(ctx)
+  if (proto) return proto
+
+  // Create a context-specific prototype that chains from elementProto
+  proto = Object.create(elementProto)
+  const methods = ctx.methods
+  if (methods) {
+    for (const k in methods) {
+      // Functions become prototype methods; non-function values (e.g. an SDK
+      // instance) are exposed as shared properties so `el.sdk.x` keeps working.
+      proto[k] = methods[k]
+    }
+  }
+  contextProtoCache.set(ctx, proto)
+  return proto
+}
+
+export function addMethods(element) {
+  const proto = getContextProto(element.context)
+  Object.setPrototypeOf(element, proto)
+}
+
+export { elementProto }

package/src/registry.js

@@ -0,0 +1,79 @@
+'use strict'
+
+// REGISTRY defines all framework-reserved property keys.
+// Any key NOT in this set that starts with uppercase is treated as a child element.
+
+export const REGISTRY = new Set([
+  // Extends/Inheritance
+  'extends',
+  // Children/Content
+  'children', 'content',
+  'childExtends',
+  'childExtendsRecursive',
+  'childProps', 'inheritParentProps',
+  // State
+  'state', 'if',
+  // Define
+  'define', 'deps',
+  // DOM
+  'tag', 'attr', 'style', 'text', 'html', 'value',
+  'data', 'classlist', 'class',
+  // Scope/Context
+  'scope', 'root', 'context',
+  // Routing/Fetching
+  '$router', 'routes', 'fetch',
+  // Meta
+  'variables', 'query', 'key',
+  'component', 'preventContentUpdate',
+  'preventContentRecreate',
+  // Internal
+  '__name', '__ref', '__hash', '__text',
+  'parent', 'node'
+])
+
+// Mixin handlers - these get special processing during create/update
+export const MIXINS = {
+  text: 'text',
+  html: 'html',
+  style: 'style',
+  attr: 'attr',
+  data: 'data',
+  classlist: 'classlist',
+  state: 'state',
+  scope: 'scope'
+}
+
+// Events that are lifecycle events (not DOM events)
+export const LIFECYCLE_EVENTS = new Set([
+  'start', 'init', 'complete', 'attachNode',
+  'stateInit', 'stateCreated',
+  'beforeUpdate', 'update', 'afterUpdate',
+  'beforeClassAssign', 'lazyLoad',
+  'render', 'renderRouter', 'done', 'create', 'frame',
+  'startUpdate', 'stateUpdate', 'beforeStateUpdate',
+  'initInspect', 'initSync', 'error',
+  'beforeRemove', 'remove'
+])
+
+// DOM events that block scroll performance unless registered `{ passive: true }`.
+// Chrome logs a "Added non-passive event listener to a scroll-blocking" warning
+// for each non-passive listener on these.
+export const PASSIVE_EVENTS = new Set([
+  'wheel', 'mousewheel',
+  'touchstart', 'touchmove', 'touchend', 'touchcancel'
+])
+
+// DOM events that should be delegated
+export const DELEGATED_EVENTS = new Set([
+  'click', 'dblclick', 'mousedown', 'mouseup', 'mousemove',
+  'mouseenter', 'mouseleave', 'mouseover', 'mouseout',
+  'pointerdown', 'pointerup', 'pointermove',
+  'pointerenter', 'pointerleave', 'pointerover', 'pointerout',
+  'touchstart', 'touchend', 'touchmove',
+  'keydown', 'keyup', 'keypress',
+  'input', 'change', 'submit', 'reset',
+  'focus', 'blur', 'focusin', 'focusout',
+  'scroll', 'wheel',
+  'contextmenu', 'drag', 'dragstart', 'dragend',
+  'dragenter', 'dragleave', 'dragover', 'drop'
+])