@symbo.ls/element 3.14.1 → 3.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/element",
-  "version": "3.14.1",
+  "version": "3.14.3",
   "description": "Core element creation, update, and disposal engine for smbls v3.14",
   "type": "module",
   "main": "./index.js",
@@ -11,8 +11,8 @@
   },
   "dependencies": {
     "@symbo.ls/signal": "^3.14.0",
-    "@symbo.ls/state": "^3.14.0",
-    "@symbo.ls/utils": "^3.14.0",
+    "@symbo.ls/state": "^3.14.2",
+    "@symbo.ls/utils": "^3.14.2",
     "css-in-props": "^3.14.0",
     "attrs-in-props": "^3.14.0"
   },

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.`
+        )
       }
     }
   }
@@ -165,15 +181,22 @@ export function create(definition, parent, key, options = {}, attachOptions) {
   // — 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) {
-    element.scope = baseScope
-      ? Object.assign(Object.create(baseScope), definition.scope)
-      : definition.scope
+  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)
   }
@@ -304,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)
     }
@@ -473,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
@@ -1018,9 +1116,17 @@ function injectScopedCSS(node, rules) {
       for (const k in val) {
         const v = val[k]
         if (typeof v === 'object') {
-          const nestedSelector = k.replace(/&/g, '.' + id)
-          const nestedSuffix = ' ' + nestedSelector.replace('.' + id, '')
-          const fullSelector = resolvedSelector.split(', ').map(s => s + nestedSuffix).join(', ')
+          // `&` in the nested key references the outer's resolved selector
+          // (standard CSS-nesting semantics). `&.X` chains on the outer,
+          // `& .X` is a descendant of the outer, `&:hover` / `&[disabled]`
+          // chain a pseudo/attr selector — all of these work because the
+          // replace preserves the user's whitespace and punctuation between
+          // `&` and the rest. When the nested key has no `&`, treat it as
+          // an implicit descendant (preserves keys like `'> h1'` rendering
+          // as `outer > h1`).
+          const fullSelector = k.includes('&')
+            ? resolvedSelector.split(', ').map(s => k.replace(/&/g, s)).join(', ')
+            : resolvedSelector.split(', ').map(s => `${s} ${k}`).join(', ')
           let nestedProps = ''
           for (const nk in v) {
             nestedProps += `${nk.replace(/[A-Z]/g, m => '-' + m.toLowerCase())}: ${v[nk]};`
@@ -1190,13 +1296,30 @@ 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
         hasStyles = true
       }
+    } else if (prop.charAt(0) === '&') {
+      // Top-level scope-anchored selector — e.g. `'& .token': { '&.keyword': {color} }`
+      // — flows straight to the atomic CSS engine, which substitutes `&` with
+      // the generated class. The `:` and `@` branches below already do this for
+      // pseudo-classes and at-rules; without this branch, top-level `&` keys
+      // were silently dropped and projects had to wrap every scope rule in a
+      // `style: {}` block (or inject a `<style>` child as a workaround).
+      const val = element[prop]
+      if (val && typeof val === 'object') {
+        cssStyles[prop] = val
+        hasStyles = true
+      }
     } else if (prop.charAt(0) === '@' || prop.charAt(0) === ':') {
       // Selector-based CSS: @dark, @media, :hover
       const val = element[prop]

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