@domql/utils 3.6.1 → 3.6.4

package/README.md

@@ -0,0 +1,77 @@
+# @domql/utils
+
+Core utility functions for the DOMQL element system.
+
+## Propertization (`props.js`)
+
+The propertization system normalizes element definitions by sorting keys between the element root (child elements, framework keys) and `props` (CSS properties, design tokens, custom data).
+
+### Two-phase process
+
+1. **`pickupPropsFromElement`** — Scans element root keys and moves non-element, non-builtin keys into `props`
+2. **`pickupElementFromProps`** — Scans `props` keys and moves element-like or builtin keys back to the element root
+
+### Key classification rules
+
+| Pattern | Classification | Example |
+|---------|---------------|---------|
+| Starts with uppercase | Child element | `Header`, `Button`, `Nav` |
+| Numeric key | Child element | `0`, `1`, `2` |
+| In `DOMQ_PROPERTIES` | Framework builtin | `tag`, `extends`, `on` |
+| In `CSS_SELECTOR_PREFIXES` | CSS-in-props | `:hover`, `@mobileS`, `$isActive` |
+| Has define handler | Define key (stays at root) | `$router`, deprecated: `$propsCollection` |
+| `childProps` | Always in props | `childProps` |
+| `onXxx` + function | Event handler | `onClick`, `onSubmit` |
+| Everything else | Prop | `padding`, `theme`, `color` |
+
+### CSS_SELECTOR_PREFIXES
+
+```javascript
+const CSS_SELECTOR_PREFIXES = new Set([
+  ':', '@', '[', '*', '+', '~', '&', '>', '$', '-', '.', '!'
+])
+```
+
+These single-character prefixes identify keys that should be processed by `css-in-props` via `transformersByPrefix`. When a key starts with one of these characters, it gets moved into `props`.
+
+### Define-awareness
+
+The `$` prefix is shared between css-in-props conditionals (`$isActive`) and define handlers (built-in `$router`, plus deprecated v2 handlers like `$propsCollection`, `$collection` that some older projects still use). The propertization must check for define handlers **before** applying prefix rules:
+
+```javascript
+// Check define handlers first — these stay at root
+const defineValue = this.define?.[key]
+const globalDefineValue = this.context?.define?.[key]
+if (isFunction(defineValue) || isFunction(globalDefineValue)) continue
+
+// Only then apply prefix-based classification
+if (CSS_SELECTOR_PREFIXES.has(firstChar)) {
+  obj.props[key] = value
+}
+```
+
+Without this check, define keys like `$router` (or deprecated `$propsCollection` in older projects) get moved into `props` and become invisible to `throughInitialDefine`, breaking routing and collection-based rendering.
+
+### childProps handling
+
+`childProps` is a framework property that configures child element props. It must always stay in `props` (consumed by `inheritParentProps`) even though its value may contain uppercase keys that look like child elements:
+
+```javascript
+// childProps: { Icon: { name: 'star' }, Hgroup: { ... } }
+// The uppercase keys inside are NOT child elements
+if (key === 'childProps') {
+  obj.props[key] = value
+  delete obj[key]
+  continue
+}
+```
+
+### ignoreChildProps
+
+When set on `element.props`, prevents the element from inheriting `childProps` from its parent via `inheritParentProps`. Used by fragment elements to avoid double-application of childProps (since fragments explicitly forward childProps to their children).
+
+## Key Sets (`keys.js`)
+
+- **`DOMQ_PROPERTIES`** — Framework-level keys that stay at element root
+- **`PROPS_METHODS`** — Keys on the props prototype (update, __element)
+- **`STATE_METHODS`** — State management methods (update, parse, set, toggle, etc.)

package/dist/cjs/props.js

@@ -43,6 +43,7 @@ var import_types = require("./types.js");
 var import_string = require("./string.js");
 const RE_UPPER = /^[A-Z]/;
 const RE_DIGITS = /^\d+$/;
+const CSS_SELECTOR_PREFIXES = /* @__PURE__ */ new Set([":", "@", "[", "*", "+", "~", "&", ">", "$", "-", ".", "!"]);
 const ELEMENT_INDICATOR_KEYS = /* @__PURE__ */ new Set([
   "extend",
   "props",
@@ -89,11 +90,27 @@ function pickupPropsFromElement(obj, opts = {}) {
       delete obj[key];
       continue;
     }
-    const hasDefine = (0, import_types.isObject)(this.define?.[key]);
-    const hasGlobalDefine = (0, import_types.isObject)(this.context?.define?.[key]);
+    if (key === "childProps") {
+      obj.props[key] = value;
+      delete obj[key];
+      cachedKeys.push(key);
+      continue;
+    }
+    const defineValue = this.define?.[key];
+    const globalDefineValue = this.context?.define?.[key];
+    const hasDefine = (0, import_types.isObject)(defineValue) || (0, import_types.isFunction)(defineValue);
+    const hasGlobalDefine = (0, import_types.isObject)(globalDefineValue) || (0, import_types.isFunction)(globalDefineValue);
+    if (hasDefine || hasGlobalDefine) continue;
+    const firstChar = key.charAt(0);
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) {
+      obj.props[key] = value;
+      delete obj[key];
+      cachedKeys.push(key);
+      continue;
+    }
     const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key) || looksLikeElement(value);
     const isBuiltin = import_keys.DOMQ_PROPERTIES.has(key);
-    if (!isElement && !isBuiltin && !hasDefine && !hasGlobalDefine) {
+    if (!isElement && !isBuiltin) {
       obj.props[key] = value;
       delete obj[key];
       cachedKeys.push(key);
@@ -113,8 +130,13 @@ function pickupElementFromProps(obj = this, opts) {
       continue;
     }
     if (cachedKeys.includes(key)) continue;
-    const hasDefine = (0, import_types.isObject)(this.define?.[key]);
-    const hasGlobalDefine = (0, import_types.isObject)(this.context?.define?.[key]);
+    if (key === "childProps") continue;
+    const firstChar = key.charAt(0);
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) continue;
+    const defineValue = this.define?.[key];
+    const globalDefineValue = this.context?.define?.[key];
+    const hasDefine = (0, import_types.isObject)(defineValue) || (0, import_types.isFunction)(defineValue);
+    const hasGlobalDefine = (0, import_types.isObject)(globalDefineValue) || (0, import_types.isFunction)(globalDefineValue);
     const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key);
     const isBuiltin = import_keys.DOMQ_PROPERTIES.has(key);
     if (isElement || isBuiltin || hasDefine || hasGlobalDefine) {
@@ -153,7 +175,7 @@ const inheritParentProps = (element, parent) => {
   const parentProps = parent.props;
   if (!parentProps) return propsStack;
   const matchParentKeyProps = parentProps[element.key];
-  const matchParentChildProps = parentProps.childProps;
+  const matchParentChildProps = parentProps.childProps || parent.childProps;
   const ignoreChildProps = element.props?.ignoreChildProps;
   if (matchParentChildProps && !ignoreChildProps) {
     const childProps = objectizeStringProperty(matchParentChildProps);

package/dist/esm/props.js

@@ -5,6 +5,7 @@ import { is, isArray, isFunction, isObject, isObjectLike } from "./types.js";
 import { lowercaseFirstLetter } from "./string.js";
 const RE_UPPER = /^[A-Z]/;
 const RE_DIGITS = /^\d+$/;
+const CSS_SELECTOR_PREFIXES = /* @__PURE__ */ new Set([":", "@", "[", "*", "+", "~", "&", ">", "$", "-", ".", "!"]);
 const ELEMENT_INDICATOR_KEYS = /* @__PURE__ */ new Set([
   "extend",
   "props",
@@ -51,11 +52,27 @@ function pickupPropsFromElement(obj, opts = {}) {
       delete obj[key];
       continue;
     }
-    const hasDefine = isObject(this.define?.[key]);
-    const hasGlobalDefine = isObject(this.context?.define?.[key]);
+    if (key === "childProps") {
+      obj.props[key] = value;
+      delete obj[key];
+      cachedKeys.push(key);
+      continue;
+    }
+    const defineValue = this.define?.[key];
+    const globalDefineValue = this.context?.define?.[key];
+    const hasDefine = isObject(defineValue) || isFunction(defineValue);
+    const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue);
+    if (hasDefine || hasGlobalDefine) continue;
+    const firstChar = key.charAt(0);
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) {
+      obj.props[key] = value;
+      delete obj[key];
+      cachedKeys.push(key);
+      continue;
+    }
     const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key) || looksLikeElement(value);
     const isBuiltin = DOMQ_PROPERTIES.has(key);
-    if (!isElement && !isBuiltin && !hasDefine && !hasGlobalDefine) {
+    if (!isElement && !isBuiltin) {
       obj.props[key] = value;
       delete obj[key];
       cachedKeys.push(key);
@@ -75,8 +92,13 @@ function pickupElementFromProps(obj = this, opts) {
       continue;
     }
     if (cachedKeys.includes(key)) continue;
-    const hasDefine = isObject(this.define?.[key]);
-    const hasGlobalDefine = isObject(this.context?.define?.[key]);
+    if (key === "childProps") continue;
+    const firstChar = key.charAt(0);
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) continue;
+    const defineValue = this.define?.[key];
+    const globalDefineValue = this.context?.define?.[key];
+    const hasDefine = isObject(defineValue) || isFunction(defineValue);
+    const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue);
     const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key);
     const isBuiltin = DOMQ_PROPERTIES.has(key);
     if (isElement || isBuiltin || hasDefine || hasGlobalDefine) {
@@ -115,7 +137,7 @@ const inheritParentProps = (element, parent) => {
   const parentProps = parent.props;
   if (!parentProps) return propsStack;
   const matchParentKeyProps = parentProps[element.key];
-  const matchParentChildProps = parentProps.childProps;
+  const matchParentChildProps = parentProps.childProps || parent.childProps;
   const ignoreChildProps = element.props?.ignoreChildProps;
   if (matchParentChildProps && !ignoreChildProps) {
     const childProps = objectizeStringProperty(matchParentChildProps);

package/dist/iife/index.js

@@ -2004,6 +2004,7 @@ var DomqlUtils = (() => {
   // props.js
   var RE_UPPER = /^[A-Z]/;
   var RE_DIGITS = /^\d+$/;
+  var CSS_SELECTOR_PREFIXES = /* @__PURE__ */ new Set([":", "@", "[", "*", "+", "~", "&", ">", "$", "-", ".", "!"]);
   var ELEMENT_INDICATOR_KEYS = /* @__PURE__ */ new Set([
     "extend",
     "props",
@@ -2050,11 +2051,27 @@ var DomqlUtils = (() => {
         delete obj[key];
         continue;
       }
-      const hasDefine = isObject(this.define?.[key]);
-      const hasGlobalDefine = isObject(this.context?.define?.[key]);
+      if (key === "childProps") {
+        obj.props[key] = value;
+        delete obj[key];
+        cachedKeys.push(key);
+        continue;
+      }
+      const defineValue = this.define?.[key];
+      const globalDefineValue = this.context?.define?.[key];
+      const hasDefine = isObject(defineValue) || isFunction(defineValue);
+      const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue);
+      if (hasDefine || hasGlobalDefine) continue;
+      const firstChar = key.charAt(0);
+      if (CSS_SELECTOR_PREFIXES.has(firstChar)) {
+        obj.props[key] = value;
+        delete obj[key];
+        cachedKeys.push(key);
+        continue;
+      }
       const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key) || looksLikeElement(value);
       const isBuiltin = DOMQ_PROPERTIES.has(key);
-      if (!isElement && !isBuiltin && !hasDefine && !hasGlobalDefine) {
+      if (!isElement && !isBuiltin) {
         obj.props[key] = value;
         delete obj[key];
         cachedKeys.push(key);
@@ -2074,8 +2091,13 @@ var DomqlUtils = (() => {
         continue;
       }
       if (cachedKeys.includes(key)) continue;
-      const hasDefine = isObject(this.define?.[key]);
-      const hasGlobalDefine = isObject(this.context?.define?.[key]);
+      if (key === "childProps") continue;
+      const firstChar = key.charAt(0);
+      if (CSS_SELECTOR_PREFIXES.has(firstChar)) continue;
+      const defineValue = this.define?.[key];
+      const globalDefineValue = this.context?.define?.[key];
+      const hasDefine = isObject(defineValue) || isFunction(defineValue);
+      const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue);
       const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key);
       const isBuiltin = DOMQ_PROPERTIES.has(key);
       if (isElement || isBuiltin || hasDefine || hasGlobalDefine) {
@@ -2114,7 +2136,7 @@ var DomqlUtils = (() => {
     const parentProps = parent.props;
     if (!parentProps) return propsStack;
     const matchParentKeyProps = parentProps[element.key];
-    const matchParentChildProps = parentProps.childProps;
+    const matchParentChildProps = parentProps.childProps || parent.childProps;
     const ignoreChildProps = element.props?.ignoreChildProps;
     if (matchParentChildProps && !ignoreChildProps) {
       const childProps = objectizeStringProperty(matchParentChildProps);

package/extends.js

@@ -334,7 +334,7 @@ export const getExtendsInElement = obj => {
   function traverse (o) {
     for (const key in o) {
       if (Object.prototype.hasOwnProperty.call(o, key)) {
-        // Check if the key starts with a capital letter and exclude keys like @mobileL, $propsCollection
+        // Check if the key starts with a capital letter and exclude keys like @mobileL, $router
         if (matchesComponentNaming(key)) {
           result.push(key)
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domql/utils",
-  "version": "3.6.1",
+  "version": "3.6.4",
   "license": "MIT",
   "type": "module",
   "module": "./dist/esm/index.js",

package/props.js

@@ -9,6 +9,10 @@ import { lowercaseFirstLetter } from './string.js'
 const RE_UPPER = /^[A-Z]/
 const RE_DIGITS = /^\d+$/
 
+// Characters that mark css-in-props selectors (pseudo-selectors, media queries, etc.)
+// These properties must always live in props so useCssInProps() can process them
+const CSS_SELECTOR_PREFIXES = new Set([':', '@', '[', '*', '+', '~', '&', '>', '$', '-', '.', '!'])
+
 const ELEMENT_INDICATOR_KEYS = new Set([
   'extend', 'props', 'text', 'tag', 'on', 'if', 'childExtend',
   'children', 'childrenAs', 'state', 'html', 'attr',
@@ -50,13 +54,38 @@ export function pickupPropsFromElement (obj, opts = {}) {
       continue
     }
 
-    const hasDefine = isObject(this.define?.[key])
-    const hasGlobalDefine = isObject(this.context?.define?.[key])
+    // childProps is a framework property that must always live in props
+    // even though its value may contain uppercase keys (Icon, Hgroup, etc.)
+    if (key === 'childProps') {
+      obj.props[key] = value
+      delete obj[key]
+      cachedKeys.push(key)
+      continue
+    }
+
+    // Check define handlers - keys with define handlers must stay at root
+    // for throughInitialDefine to process them
+    const defineValue = this.define?.[key]
+    const globalDefineValue = this.context?.define?.[key]
+    const hasDefine = isObject(defineValue) || isFunction(defineValue)
+    const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue)
+    if (hasDefine || hasGlobalDefine) continue
+
+    // CSS-in-props selectors (:after, :hover, @mobileS, etc.) must always
+    // live in props so useCssInProps() can process them via transformersByPrefix
+    const firstChar = key.charAt(0)
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) {
+      obj.props[key] = value
+      delete obj[key]
+      cachedKeys.push(key)
+      continue
+    }
+
     const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key) || looksLikeElement(value)
     const isBuiltin = DOMQ_PROPERTIES.has(key)
 
     // If it's not a special case, move to props
-    if (!isElement && !isBuiltin && !hasDefine && !hasGlobalDefine) {
+    if (!isElement && !isBuiltin) {
       obj.props[key] = value
       delete obj[key]
       cachedKeys.push(key)
@@ -85,8 +114,17 @@ export function pickupElementFromProps (obj = this, opts) {
     // Skip if key was originally from obj
     if (cachedKeys.includes(key)) continue
 
-    const hasDefine = isObject(this.define?.[key])
-    const hasGlobalDefine = isObject(this.context?.define?.[key])
+    // childProps must stay in props - it's consumed by inheritParentProps
+    if (key === 'childProps') continue
+
+    // CSS-in-props selectors must stay in props
+    const firstChar = key.charAt(0)
+    if (CSS_SELECTOR_PREFIXES.has(firstChar)) continue
+
+    const defineValue = this.define?.[key]
+    const globalDefineValue = this.context?.define?.[key]
+    const hasDefine = isObject(defineValue) || isFunction(defineValue)
+    const hasGlobalDefine = isObject(globalDefineValue) || isFunction(globalDefineValue)
     const isElement = RE_UPPER.test(key) || RE_DIGITS.test(key)
     const isBuiltin = DOMQ_PROPERTIES.has(key)
 
@@ -140,7 +178,7 @@ export const inheritParentProps = (element, parent) => {
   if (!parentProps) return propsStack
 
   const matchParentKeyProps = parentProps[element.key]
-  const matchParentChildProps = parentProps.childProps
+  const matchParentChildProps = parentProps.childProps || parent.childProps
 
   // Order matters: key-specific props should be added after childProps
   const ignoreChildProps = element.props?.ignoreChildProps