@domql/element 3.6.3 → 3.6.4

package/README.md

@@ -34,4 +34,60 @@ const MyComponent = {
 }
 ```
 
-`el.html` takes priority when both are set. `props.html` is used as a fallback when `el.html` is not defined.
+`el.html` takes priority when both are set. `props.html` is used as a fallback when `el.html` is not defined.
+
+## REGISTRY (`mixins/registry.js`)
+
+The `REGISTRY` object defines which keys are recognized as framework properties (rather than child elements). Any key **not** in REGISTRY and starting with an uppercase letter is treated as a child element.
+
+**Every framework-level key must be listed here.** If a key like `childExtend` is missing from REGISTRY, it gets interpreted as a child element name, causing silent rendering failures (e.g., cart components not rendering in Archy).
+
+Current framework keys that must remain in REGISTRY:
+
+```
+extends, children, content,
+childExtend (deprecated), childExtends,
+childExtendRecursive (deprecated), childExtendsRecursive,
+props, if, define,
+__name, __ref, __hash, __text, key, tag, query, parent, node,
+variables, on, component, context
+```
+
+Plus mixin handlers: `attr`, `style`, `text`, `html`, `data`, `classlist`, `state`, `scope`, `deps`.
+
+> **v3 note:** `childExtend` (singular) is deprecated v2 syntax — use `childExtends` (plural) in new code. The singular forms remain in REGISTRY for backwards compatibility with older projects. If a key is missing from REGISTRY, it gets interpreted as a child element name, causing silent rendering failures.
+
+## set.js — Content Setting
+
+### Fragment forwarding
+
+When `set()` receives content with `tag: 'fragment'`, the fragment itself doesn't create a DOM node — its children are inserted directly. This means:
+
+1. **childExtends forwarding** — The parent's `childExtends` must be forwarded to the fragment's params so that fragment children inherit the correct extends:
+   ```javascript
+   if (tag === 'fragment') {
+     const elementChildExtends = element.childExtends || element.childExtend
+     if (!childExtends && elementChildExtends) {
+       params.childExtends = elementChildExtends
+     }
+   }
+   ```
+   (Also checks deprecated `childExtend` for backwards compatibility with v2 projects.)
+
+2. **childProps forwarding** — Similarly, `childProps` from the parent must be explicitly passed through the fragment to its children.
+
+3. **ignoreChildProps** — When forwarding `childProps` through a fragment, set `props.ignoreChildProps = true` on the fragment itself to prevent the fragment from inheriting the parent's `childProps` via `inheritParentProps`. The `childProps` are already forwarded explicitly for the fragment's children.
+
+### Infinite loop guard
+
+`set()` includes a re-entrancy guard via `ref.__settingContent`. Without this, define handlers (like `$router`) that call `el.set()` can trigger infinite recursion when content-setting triggers another content-set cycle.
+
+```javascript
+if (ref.__settingContent) return element
+ref.__settingContent = true
+try {
+  return _setInner(params, options, element)
+} finally {
+  ref.__settingContent = false
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domql/element",
-  "version": "3.6.3",
+  "version": "3.6.4",
   "license": "MIT",
   "type": "module",
   "module": "./dist/esm/index.js",
@@ -46,10 +46,10 @@
     "build:iife": "cross-env NODE_ENV=$NODE_ENV esbuild index.js --bundle --target=es2020 --format=iife --global-name=DomqlElement --outfile=dist/iife/index.js --define:process.env.NODE_ENV=process.env.NODE_ENV"
   },
   "dependencies": {
-    "@domql/report": "^3.6.3",
-    "@domql/state": "^3.6.3",
-    "@domql/utils": "^3.6.3",
-    "attrs-in-props": "^3.6.3"
+    "@domql/report": "^3.6.4",
+    "@domql/state": "^3.6.4",
+    "@domql/utils": "^3.6.4",
+    "attrs-in-props": "^3.6.4"
   },
   "gitHead": "9fc1b79b41cdc725ca6b24aec64920a599634681",
   "devDependencies": {