@symbo.ls/element 3.14.0 → 3.14.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@symbo.ls/element",
-  "version": "3.14.0",
-  "description": "Core element creation, update, and disposal engine for smbls v4",
+  "version": "3.14.2",
+  "description": "Core element creation, update, and disposal engine for smbls v3.14",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -16,6 +16,9 @@
     "css-in-props": "^3.14.0",
     "attrs-in-props": "^3.14.0"
   },
-  "files": ["src", "index.js"],
+  "files": [
+    "src",
+    "index.js"
+  ],
   "license": "CC-BY-NC-4.0"
 }

package/src/cache.js

@@ -1,7 +1,7 @@
 'use strict'
 
 // Node caching - cloneNode from cached prototypes instead of createElement
-// This is already a v3 optimization that works well -- preserved in v4
+// This is already a v3 optimization that works well -- preserved in v3.14
 
 const SVG_NS = 'http://www.w3.org/2000/svg'
 

package/src/create.js

@@ -90,6 +90,22 @@ export function create(definition, parent, key, options = {}, attachOptions) {
       const components = element.context?.components
       if (components && (components[baseName] || components['smbls.' + baseName])) {
         definition = { extends: baseName, ...definition }
+      } else if (
+        // FRAMEWORK-5: dev-mode warning. A key shaped like a multi-instance
+        // suffix (e.g. `Link_1`) clearly intends to auto-extend a base
+        // component, so silently rendering as a bare div is the kind of
+        // failure that takes a click test to discover. Warn loudly in dev
+        // so the typo / missing import is visible at mount time.
+        components &&
+        process.env.NODE_ENV !== 'production' &&
+        /^[A-Z]\w*_\d+$/.test(key)
+      ) {
+        console.warn(
+          `[smbls] auto-extend: key "${key}" looks like a multi-instance ` +
+          `(${baseName}_N) but neither "${baseName}" nor "smbls.${baseName}" ` +
+          `is registered in context.components — element will render as a ` +
+          `plain <div>. Register the base component or rename the key.`
+        )
       }
     }
   }
@@ -155,12 +171,34 @@ export function create(definition, parent, key, options = {}, attachOptions) {
   if (definition.classlist !== undefined) element.classlist = definition.classlist
   if (definition.text !== undefined) element.text = definition.text
   if (definition.html !== undefined) element.html = definition.html
-  if (definition.scope !== undefined) {
-    element.scope = parent?.scope
-      ? Object.assign(Object.create(parent.scope), definition.scope)
-      : definition.scope
-  } else if (parent?.scope) {
-    element.scope = Object.create(parent.scope)
+  // The scope chain at any element resolves keys in this order:
+  //   own (definition.scope) → parent.scope → … → root.scope → context.globalScope
+  // Direct reads like `el.scope.LANG_META` walk the prototype chain, so a
+  // component that doesn't declare its own scope still sees parent scopes
+  // and the project's globalScope as fallbacks. Without `globalScope` at the
+  // bottom of the chain, every project pattern that puts shared constants
+  // in `globalScope.js` and reads them via `el.scope.X` was silently broken
+  // — the user's reactive function got `undefined` and either threw or
+  // rendered nothing. The frank-rewriter's `__scope` helper already chains
+  // through globalScope; this brings the runtime `el.scope` to parity.
+  // Capture scope set by the extends chain (applyExtends ran above) BEFORE
+  // we rebuild element.scope. Otherwise scope blocks declared on the base
+  // component (e.g. `Navbar.scope = { LANG_META }`) get blown away when
+  // a consumer extends without redeclaring scope (`AppNavbar: { extends:
+  // 'Navbar' }`). FA-L24.
+  const inheritedFromExtends = element.scope && typeof element.scope === 'object' ? element.scope : null
+  const ancestorScope = parent?.scope
+  const globalScope =
+    (element.context && typeof element.context.globalScope === 'object' && element.context.globalScope) || null
+  const baseScope = ancestorScope ||
+    (globalScope ? Object.create(globalScope) : null)
+  if (definition.scope !== undefined || inheritedFromExtends) {
+    const target = baseScope ? Object.create(baseScope) : {}
+    if (inheritedFromExtends) Object.assign(target, inheritedFromExtends)
+    if (definition.scope !== undefined) Object.assign(target, definition.scope)
+    element.scope = target
+  } else if (baseScope) {
+    element.scope = Object.create(baseScope)
   }
   if (definition.if !== undefined) element.if = definition.if
 
@@ -289,15 +327,24 @@ export function create(definition, parent, key, options = {}, attachOptions) {
   triggerLifecycle('RenderRouter', element, options)
 
   // Start onFrame loop if defined
+  // FT-FRAMEWORK-3: Previously this returned early when `!element.node.isConnected`,
+  // killing the loop. During an initial top-down mount, the first rAF often
+  // fires before the root has been attached to document.body — so deeply
+  // nested children's onFrame loops self-terminated and never restarted.
+  // Now we reschedule unconditionally and gate only the handler call on
+  // `isConnected`. The loop stops only when the element is disposed
+  // (`element.node === null`).
   if (typeof element.onFrame === 'function') {
     const frameHandler = element.onFrame
     const frameDsConfig = element.context?.designSystem
     const tick = () => {
-      if (!element.node || !element.node.isConnected) return
-      if (frameDsConfig) pushConfig(frameDsConfig)
-      try { frameHandler(element, element.state, element.context) } catch (e) { console.error('[DOMQL] onFrame error:', e) }
-      finally {
-        if (frameDsConfig) popConfig()
+      if (!element.node) return
+      if (element.node.isConnected) {
+        if (frameDsConfig) pushConfig(frameDsConfig)
+        try { frameHandler(element, element.state, element.context) } catch (e) { console.error('[DOMQL] onFrame error:', e) }
+        finally {
+          if (frameDsConfig) popConfig()
+        }
       }
       requestAnimationFrame(tick)
     }
@@ -316,7 +363,21 @@ function createElementState(element, parent, definition) {
   // Dashboard defines `state: { useJson: true }` would lose its state because
   // the local definition has no `state` field, and we'd silently inherit
   // parent state instead.
-  const stateDef = definition.state !== undefined
+  // Treat an empty plain-object `state: {}` declaration as "not provided"
+  // when this is the root element AND context.state has content. Without
+  // this, scaffolded `app.js` files that ship with `state: {}` boilerplate
+  // would silently override context.state (loaded from `state.js`) and
+  // leave the root state empty at runtime — see chatbot template where
+  // `s.root.navTabs` resolved undefined despite a populated state.js.
+  // Explicit non-empty objects + non-root elements bypass this rewrite.
+  const isRootCandidate = !parent
+  const isEmptyObjectState = definition.state &&
+    typeof definition.state === 'object' &&
+    !Array.isArray(definition.state) &&
+    Object.keys(definition.state).length === 0
+  const useContextStateFallback = isRootCandidate && isEmptyObjectState && element.context?.state
+
+  const stateDef = (definition.state !== undefined && !useContextStateFallback)
     ? definition.state
     : (element.state && !isStore(element.state) ? element.state : undefined)
 
@@ -444,9 +505,75 @@ function resolveStatePath(path, parent) {
 
 // --- Reactive Effects ---
 
+function wrapCustomPropFunctions(element) {
+  const ref = element.__ref
+  const tag = element.tag || 'div'
+  const ds = element.context?.designSystem
+
+  // Two-pass: collect first, install second. Lets sibling refs like
+  // `a: fn`, `b: (el) => el.a + 1` work regardless of declaration order
+  // because every peer is already a value-producing getter once we begin
+  // evaluating any of them.
+  const targets = []
+  const ownProps = Object.keys(element)
+  for (let i = 0; i < ownProps.length; i++) {
+    const prop = ownProps[i]
+    if (typeof element[prop] !== 'function') continue
+    if (REGISTRY.has(prop)) continue
+    const firstChar = prop.charCodeAt(0)
+    if (firstChar >= 65 && firstChar <= 90) continue // child component
+    if (isEventHandler(prop)) continue
+    if (CSS_PROPS_REGISTRY[prop]) continue // handled by CSS effect loop
+    if (DEFAULT_CSS_PROPERTIES_LIST && DEFAULT_CSS_PROPERTIES_LIST.has(prop)) continue
+    if (checkAttributeByTagName(tag, prop)) continue // handled by attr effect loop
+    targets.push({ prop, fn: element[prop] })
+  }
+
+  for (let i = 0; i < targets.length; i++) {
+    const { prop, fn } = targets[i]
+    ref.__exec[prop] = fn
+    Object.defineProperty(element, prop, {
+      get () {
+        // Re-run fn on each read. Signal dependency tracking still works:
+        // whatever effect is reading el[prop] subscribes to state signals
+        // touched inside fn, so it re-fires on state changes. We skip a
+        // memoizing layer (createComputed) so fn never sees a peer custom
+        // prop in its raw-function form during this pass's eager init.
+        if (ds) pushConfig(ds)
+        try {
+          return fn(element, element.state, element.context)
+        } catch (e) {
+          return undefined
+        } finally {
+          if (ds) popConfig()
+        }
+      },
+      set (val) {
+        delete ref.__exec[prop]
+        Object.defineProperty(element, prop, {
+          value: val, writable: true, configurable: true, enumerable: true
+        })
+      },
+      configurable: true,
+      enumerable: true
+    })
+  }
+}
+
 function registerEffects(element, definition) {
   const ref = element.__ref
 
+  // Custom-prop function reactivity (FRAMEWORK-1).
+  // Replace user-defined function-valued props (lowercase, not framework-
+  // reserved, not CSS, not HTML attribute, not event/lifecycle) with a getter
+  // that calls the function on read. Reads via `el.X` — including
+  // `el.parent.X` from descendants — return the evaluated value, and signal
+  // dependency tracking propagates through dependent effects (`text:`,
+  // `width:`, `href:`, etc.). Without this wrap, dependent effects coerce the
+  // un-invoked function via `Function.prototype.toString` and ship the
+  // arrow-function source into the DOM (e.g. "(el, s) => 8 / 10").
+  wrapCustomPropFunctions(element)
+
   // Text effect
   if (typeof element.text === 'function') {
     const fn = element.text
@@ -590,6 +717,23 @@ function registerEffects(element, definition) {
     }, { depth: ref.path.length })
     ref.__effects.push(effect)
     ref.__exec.style = fn
+  } else if (element.style && typeof element.style === 'object') {
+    // Nested-object style: function values per-key get individual effects.
+    // Static keys go through applyStaticMixins → applyStyles at mount.
+    // Without this branch, `style: { color: (el, s) => s.theme }` runs
+    // once at mount and never re-evaluates, while flat top-level
+    // `color: fn` IS reactive — surprising parity gap (FA-L23).
+    for (const styleKey in element.style) {
+      const styleFn = element.style[styleKey]
+      if (typeof styleFn !== 'function') continue
+      const effect = createEffect(() => {
+        try {
+          const val = styleFn(element, element.state, element.context)
+          if (element.node) applyStyles(element.node, { [styleKey]: val })
+        } catch (e) { /* style fn may fail before state is populated */ }
+      }, { depth: ref.path.length })
+      ref.__effects.push(effect)
+    }
   }
 
   // Attribute effects for function-valued attrs (check element.attr which includes extends)
@@ -617,6 +761,84 @@ function registerEffects(element, definition) {
     }
   }
 
+  // Reactive nested aria.X — `aria: { label: (el, s) => s.title }` re-runs
+  // on every state change. Static aria.X values are flattened to top-level
+  // attrs by `filterAttributesByTagName` (attrs-in-props/index.js), so we
+  // only wire effects for function values here.
+  if (element.aria && typeof element.aria === 'object') {
+    for (const ariaKey in element.aria) {
+      const ariaFn = element.aria[ariaKey]
+      if (typeof ariaFn !== 'function') continue
+      const attrName = 'aria-' + ariaKey.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
+      const effect = createEffect(() => {
+        try {
+          const val = ariaFn(element, element.state, element.context)
+          if (!element.node?.setAttribute) return
+          if (val == null || val === false) {
+            element.node.removeAttribute(attrName)
+          } else if (typeof val !== 'function' && typeof val !== 'object') {
+            element.node.setAttribute(attrName, val === true ? '' : val)
+          }
+        } catch (e) { /* aria fn may fail before state is populated */ }
+      }, { depth: ref.path.length })
+      ref.__effects.push(effect)
+    }
+  }
+
+  // Reactive nested data.X — same shape as aria, kebab-cases the key.
+  if (element.data && typeof element.data === 'object') {
+    for (const dataKey in element.data) {
+      const dataFn = element.data[dataKey]
+      if (typeof dataFn !== 'function') continue
+      const kebab = dataKey.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
+      const attrName = 'data-' + kebab
+      const effect = createEffect(() => {
+        try {
+          const val = dataFn(element, element.state, element.context)
+          if (!element.node?.setAttribute) return
+          if (val == null || val === false) {
+            element.node.removeAttribute(attrName)
+          } else if (typeof val !== 'function' && typeof val !== 'object') {
+            element.node.setAttribute(attrName, val === true ? '' : val)
+          }
+        } catch (e) { /* data fn may fail before state is populated */ }
+      }, { depth: ref.path.length })
+      ref.__effects.push(effect)
+    }
+  }
+
+  // Reactive classlist / class — `class: { active: (el, s) => s.isOpen }`
+  // toggles on state change. Static keys are applied at mount by
+  // applyStaticMixins; only function-valued keys need effects here.
+  const classObj = (element.classlist && typeof element.classlist === 'object' && !Array.isArray(element.classlist))
+    ? element.classlist
+    : (element.class && typeof element.class === 'object' && !Array.isArray(element.class))
+      ? element.class
+      : null
+  if (classObj) {
+    for (const className in classObj) {
+      const classFn = classObj[className]
+      if (typeof classFn !== 'function') continue
+      const effect = createEffect(() => {
+        try {
+          const val = classFn(element, element.state, element.context)
+          if (!element.node?.classList) return
+          // Mirror the static-path logic: `val: 'custom-name'` → toggle that
+          // string class on; falsy → toggle base key off; truthy non-string →
+          // toggle base key on.
+          if (typeof val === 'string') {
+            element.node.classList.add(val)
+          } else if (val) {
+            element.node.classList.add(className)
+          } else {
+            element.node.classList.remove(className)
+          }
+        } catch (e) { /* class fn may fail before state is populated */ }
+      }, { depth: ref.path.length })
+      ref.__effects.push(effect)
+    }
+  }
+
   // If condition effect
   if (typeof definition.if === 'function') {
     const fn = definition.if
@@ -785,10 +1007,17 @@ function applyStaticMixins(element) {
     }
   }
 
-  // Data attributes
+  // Data attributes — same guard shape as the attr loop above. Function-
+  // valued data.X is handled by the reactive-data effect in registerEffects;
+  // writing the function reference into `dataset` here would render as a
+  // stringified function literal in the DOM until something else overwrote
+  // it. Skip null/false/object values too.
   if (element.data && typeof element.data === 'object') {
     for (const key in element.data) {
-      if (node.dataset) node.dataset[key] = element.data[key]
+      const val = element.data[key]
+      if (typeof val === 'function' || typeof val === 'object') continue
+      if (val == null || val === false) continue
+      if (node.dataset) node.dataset[key] = val === true ? '' : val
     }
   }
 
@@ -826,12 +1055,22 @@ function applyStyles(node, styles) {
 
     try {
       const str = String(val)
-      if (str.includes('!important')) {
-        const cssProp = prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
-        node.style.setProperty(cssProp, str.replace(/\s*!important\s*$/, ''), 'important')
-      } else {
-        node.style[prop] = val
-      }
+      // Reactive writes go through `setProperty` as plain inline (no
+      // priority). Inline already beats class-rule selectors in the cascade
+      // — the smbls atomic CSS engine never emits `!important`, so a plain
+      // inline value wins on its own. The previous `'important'` priority
+      // was a cargo-culted band-aid for an apparent stale-getComputedStyle
+      // observation; in practice it caused CSS transitions on the same
+      // element to leave stuck `Animation` objects (currentTime:0,
+      // fill:'backwards') because Chrome's transition state machine
+      // mishandles a mid-transition switch to/from `!important`.
+      // If a value carries an explicit `!important` suffix from upstream
+      // (rare — design tokens etc.), honor it.
+      const cssProp = prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
+      const trimmed = str.trim()
+      const isImportant = /\s*!important\s*$/.test(trimmed)
+      const cleanVal = trimmed.replace(/\s*!important\s*$/, '')
+      node.style.setProperty(cssProp, cleanVal, isImportant ? 'important' : '')
     } catch (e) {
       // Invalid style value
     }
@@ -1049,8 +1288,13 @@ function applyCssInProps(element) {
         cssStyles[prop] = val
         hasStyles = true
       }
-    } else if (prop.charCodeAt(0) === 45 && prop.charCodeAt(1) === 45) {
-      // CSS custom properties (--var-name): apply as inline style
+    } else if (prop.charCodeAt(0) === 45) {
+      // FT-FRAMEWORK-4: any dash-prefixed CSS key — both custom properties
+      // (`--var-name`) and vendor-prefixed properties
+      // (`-webkit-text-stroke`, `-moz-osx-font-smoothing`, …) — pass
+      // straight through the atomic CSS engine. Previously only `--`
+      // matched; `-webkit-text-stroke: 1px darkgrey` at the top level was
+      // silently dropped, forcing consumers to wrap it in `style: { ... }`.
       const val = element[prop]
       if (val != null && typeof val !== 'object') {
         cssStyles[prop] = val
@@ -1208,6 +1452,22 @@ function applyAttrsInProps(element) {
   const { node } = element
   if (!node || !node.setAttribute) return
 
+  // Apply STATIC nested aria.X / data.X values at mount. Function values
+  // are owned by the reactive aria/data effects in registerEffects — those
+  // re-run on state changes. Without this loop, aria/data static values
+  // declared as nested objects (`aria: { label: 'Search' }`) silently
+  // dropped — `applyStaticMixins` already promoted top-level data.X to
+  // dataset and the parallel aria branch had no equivalent.
+  if (element.aria && typeof element.aria === 'object') {
+    for (const ariaKey in element.aria) {
+      const v = element.aria[ariaKey]
+      if (typeof v === 'function' || typeof v === 'object') continue
+      if (v == null || v === false) continue
+      const attrName = 'aria-' + ariaKey.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
+      node.setAttribute(attrName, v === true ? '' : v)
+    }
+  }
+
   // Apply attribute transforms (src, href, poster, etc. with file/template resolution)
   const transformed = applyAttrTransforms(element)
   for (const attr in transformed) {
@@ -1264,8 +1524,10 @@ function registerEvents(element, options) {
 
     let handler = element[key]
 
-    // String shortcut: onClick: 'fnName' → el.call('fnName', ev)
-    if (typeof handler === 'string') {
+    // String shortcut: onClick: 'fnName' → el.call('fnName', ev).
+    // Only valid JS identifiers — arbitrary strings like 'not a function' fall
+    // through to the typeof-function check below and are skipped.
+    if (typeof handler === 'string' && /^[A-Za-z_$][\w$]*$/.test(handler)) {
       const fnName = handler
       handler = function stringHandlerShortcut (ev) {
         return element.call(fnName, ev)

package/src/extends.js

@@ -5,16 +5,33 @@
 
 const extendsCache = new WeakMap()
 
+// FT-FRAMEWORK-EXTEND-CUSTOM: collect entries from BOTH `extends:`
+// (plural) and `extend:` (singular). Previously the resolver did
+// `definition.extends || definition.extend`, silently dropping one when
+// the other was set. childsafetynet's blog-detail pages used both
+// (`extends: 'Page'` for route-mode + `extend: 'BlogArticle'` for the
+// article shell) and only Page resolved — BlogArticle's child keys
+// never reached the render tree.
+function collectExtendsList (definition) {
+  const list = []
+  if (definition.extends) {
+    if (Array.isArray(definition.extends)) list.push(...definition.extends)
+    else list.push(definition.extends)
+  }
+  if (definition.extend) {
+    if (Array.isArray(definition.extend)) list.push(...definition.extend)
+    else list.push(definition.extend)
+  }
+  return list
+}
+
 export function applyExtends(element, definition, options) {
-  let ext = definition.extends || definition.extend
-  if (!ext) return
+  const ext = collectExtendsList(definition)
+  if (!ext.length) 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)
@@ -48,13 +65,14 @@ 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) {
+  // Recursively resolve base's own extends first — combining both
+  // `extends:` (plural) and `extend:` (singular). Mirrors the entry-point
+  // collectExtendsList logic so chains like Page → BlogArticle → Flex
+  // resolve correctly when intermediate components mix the two forms.
+  const baseExt = collectExtendsList(base)
+  if (baseExt.length) {
     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)

package/src/methods.js

@@ -152,10 +152,20 @@ const elementProto = {
   parse(exclude) {
     const result = {}
     const excludeSet = exclude ? new Set(exclude) : null
+    const exec = this.__ref?.__exec
     for (const key in this) {
       if (key === 'parent' || key === 'node' || key === '__ref') continue
-      if (typeof this[key] === 'function') continue
       if (excludeSet?.has(key)) continue
+      // Reactive props (text/html/value/style/attr/css/custom-prop fns) are
+      // wrapped at create time; the live value is the evaluated result, but
+      // ref.__exec[key] holds the original function (or template). Restore it
+      // so reset() / parseDeep() reproduce the reactive definition rather
+      // than baking in a snapshot value.
+      if (exec && exec[key] !== undefined) {
+        result[key] = exec[key]
+        continue
+      }
+      if (typeof this[key] === 'function') continue
       result[key] = this[key]
     }
     return result
@@ -195,7 +205,11 @@ const elementProto = {
   setNodeStyles(styles) {
     if (!this.node?.style) return
     for (const prop in styles) {
-      this.node.style[prop] = styles[prop]
+      const val = styles[prop]
+      if (val == null) continue
+      const cssProp = prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
+      const str = String(val).replace(/\s*!important\s*$/, '')
+      this.node.style.setProperty(cssProp, str, 'important')
     }
   },
 

package/src/update.js

@@ -47,11 +47,19 @@ export function update(params = {}, opts = {}) {
       }
     }
 
-    // Update style
+    // Update style — mirrors applyStyles in create.js: write via setProperty
+    // with `important` priority so cascade resolves to the inline value
+    // even when the element carries atomic CSS classes for sibling static
+    // props. Plain `node.style[prop] = val` writes don't invalidate the
+    // cached cascade when the first-paint resolved to a different value.
     if (params.style && element.node?.style) {
       if (!ref.__exec.style) {
         for (const prop in params.style) {
-          element.node.style[prop] = params.style[prop]
+          const val = params.style[prop]
+          if (val == null) continue
+          const cssProp = prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase())
+          const str = String(val).replace(/\s*!important\s*$/, '')
+          element.node.style.setProperty(cssProp, str, 'important')
         }
       }
       if (!element.style) element.style = {}