@elementor/editor-props - npm Package Compare versions

Comparing version 4.2.0-924 to 4.2.0-925

dist/index.js

@@ -991,3 +991,9 @@ "use strict";
 // src/utils/props-to-llm-schema.ts
-function propTypeToJsonSchema(propType) {
+var DYNAMIC_PROP_TYPE_KEY = "dynamic";
+var OVERRIDABLE_PROP_TYPE_KEY = "overridable";
+var dynamicTagNamesResolver = null;
+function setDynamicTagNamesResolver(resolver) {
+  dynamicTagNamesResolver = resolver;
+}
+function propTypeToJsonSchema(propType, suppressDynamic = false) {
   const description = propType.meta?.description;
@@ -1003,7 +1009,7 @@ const schema = {};
     case "union":
-      return convertUnionPropType(propType, schema);
+      return convertUnionPropType(propType, schema, suppressDynamic);
     case "object":
-      return convertObjectPropType(propType, schema);
+      return convertObjectPropType(propType, schema, suppressDynamic);
     case "array":
-      return convertArrayPropType(propType, schema);
+      return convertArrayPropType(propType, schema, suppressDynamic);
     default:
@@ -1049,12 +1055,19 @@ return convertPlainPropType(propType, schema);
 }
-function convertUnionPropType(propType, baseSchema) {
+function convertUnionPropType(propType, baseSchema, suppressDynamic) {
   const schema = structuredClone(baseSchema);
   const propTypes = propType.prop_types || {};
+  const offersDynamic = !suppressDynamic && Boolean(propTypes[DYNAMIC_PROP_TYPE_KEY]);
+  const suppressNestedDynamic = suppressDynamic || offersDynamic;
   const schemas = [];
   for (const [typeKey, subPropType] of Object.entries(propTypes)) {
-    if (typeKey === "dynamic" || typeKey === "overridable") {
+    if (typeKey === OVERRIDABLE_PROP_TYPE_KEY) {
       continue;
     }
-    const subSchema = convertPropTypeToJsonSchema(subPropType);
-    schemas.push(subSchema);
+    if (typeKey === DYNAMIC_PROP_TYPE_KEY) {
+      if (offersDynamic) {
+        schemas.push(convertDynamicPropType(subPropType));
+      }
+      continue;
+    }
+    schemas.push(propTypeToJsonSchema(subPropType, suppressNestedDynamic));
   }
@@ -1070,3 +1083,30 @@ if (schemas.length > 0) {
 }
-function convertObjectPropType(propType, baseSchema) {
+function convertDynamicPropType(propType) {
+  const categories = Array.isArray(propType.settings?.categories) ? propType.settings.categories : [];
+  const allowedTagNames = dynamicTagNamesResolver?.(categories) ?? [];
+  return {
+    type: "object",
+    description: `Bind THIS value to a dynamic tag instead of a static value (this may be a nested field, e.g. an image's "src"). Look up the chosen tag in the "elementor://dynamic-tags" resource and populate "settings" exactly as its schema requires.`,
+    properties: {
+      $$type: { type: "string", const: DYNAMIC_PROP_TYPE_KEY },
+      value: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: 'Dynamic tag name from "elementor://dynamic-tags".',
+            ...allowedTagNames.length ? { enum: allowedTagNames } : {}
+          },
+          settings: {
+            type: "object",
+            description: "Tag settings matching the chosen tag's schema in the resource."
+          }
+        },
+        required: ["name"]
+      }
+    },
+    required: ["$$type", "value"]
+  };
+}
+function convertObjectPropType(propType, baseSchema, suppressDynamic) {
   const schema = structuredClone(baseSchema);
@@ -1091,3 +1131,3 @@ schema.type = "object";
   for (const [key, subPropType] of Object.entries(shape)) {
-    const propSchema = propTypeToJsonSchema(subPropType);
+    const propSchema = propTypeToJsonSchema(subPropType, suppressDynamic);
     if (subPropType.settings?.required === true) {
@@ -1109,3 +1149,3 @@ valueRequired.push(key);
 }
-function convertArrayPropType(propType, baseSchema) {
+function convertArrayPropType(propType, baseSchema, suppressDynamic) {
   const schema = structuredClone(baseSchema);
@@ -1116,3 +1156,3 @@ schema.type = "object";
   if (itemPropType) {
-    items = convertPropTypeToJsonSchema(itemPropType);
+    items = propTypeToJsonSchema(itemPropType, suppressDynamic);
   }
@@ -1131,5 +1171,2 @@ schema.properties = {
 }
-function convertPropTypeToJsonSchema(propType) {
-  return propTypeToJsonSchema(propType);
-}
 var nonConfigurablePropKeys = ["_cssid", "classes", "attributes"];
@@ -1483,3 +1520,4 @@ function isPropKeyConfigurable(propKey, propType) {
   enrichWithIntention,
-  removeIntention
+  removeIntention,
+  setDynamicTagNamesResolver
 };
@@ -1486,0 +1524,0 @@ // Annotate the CommonJS export names for ESM import in node:

dist/index.mjs

@@ -882,3 +882,9 @@ // src/prop-types/box-shadow.ts
 // src/utils/props-to-llm-schema.ts
-function propTypeToJsonSchema(propType) {
+var DYNAMIC_PROP_TYPE_KEY = "dynamic";
+var OVERRIDABLE_PROP_TYPE_KEY = "overridable";
+var dynamicTagNamesResolver = null;
+function setDynamicTagNamesResolver(resolver) {
+  dynamicTagNamesResolver = resolver;
+}
+function propTypeToJsonSchema(propType, suppressDynamic = false) {
   const description = propType.meta?.description;
@@ -894,7 +900,7 @@ const schema = {};
     case "union":
-      return convertUnionPropType(propType, schema);
+      return convertUnionPropType(propType, schema, suppressDynamic);
     case "object":
-      return convertObjectPropType(propType, schema);
+      return convertObjectPropType(propType, schema, suppressDynamic);
     case "array":
-      return convertArrayPropType(propType, schema);
+      return convertArrayPropType(propType, schema, suppressDynamic);
     default:
@@ -940,12 +946,19 @@ return convertPlainPropType(propType, schema);
 }
-function convertUnionPropType(propType, baseSchema) {
+function convertUnionPropType(propType, baseSchema, suppressDynamic) {
   const schema = structuredClone(baseSchema);
   const propTypes = propType.prop_types || {};
+  const offersDynamic = !suppressDynamic && Boolean(propTypes[DYNAMIC_PROP_TYPE_KEY]);
+  const suppressNestedDynamic = suppressDynamic || offersDynamic;
   const schemas = [];
   for (const [typeKey, subPropType] of Object.entries(propTypes)) {
-    if (typeKey === "dynamic" || typeKey === "overridable") {
+    if (typeKey === OVERRIDABLE_PROP_TYPE_KEY) {
       continue;
     }
-    const subSchema = convertPropTypeToJsonSchema(subPropType);
-    schemas.push(subSchema);
+    if (typeKey === DYNAMIC_PROP_TYPE_KEY) {
+      if (offersDynamic) {
+        schemas.push(convertDynamicPropType(subPropType));
+      }
+      continue;
+    }
+    schemas.push(propTypeToJsonSchema(subPropType, suppressNestedDynamic));
   }
@@ -961,3 +974,30 @@ if (schemas.length > 0) {
 }
-function convertObjectPropType(propType, baseSchema) {
+function convertDynamicPropType(propType) {
+  const categories = Array.isArray(propType.settings?.categories) ? propType.settings.categories : [];
+  const allowedTagNames = dynamicTagNamesResolver?.(categories) ?? [];
+  return {
+    type: "object",
+    description: `Bind THIS value to a dynamic tag instead of a static value (this may be a nested field, e.g. an image's "src"). Look up the chosen tag in the "elementor://dynamic-tags" resource and populate "settings" exactly as its schema requires.`,
+    properties: {
+      $$type: { type: "string", const: DYNAMIC_PROP_TYPE_KEY },
+      value: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: 'Dynamic tag name from "elementor://dynamic-tags".',
+            ...allowedTagNames.length ? { enum: allowedTagNames } : {}
+          },
+          settings: {
+            type: "object",
+            description: "Tag settings matching the chosen tag's schema in the resource."
+          }
+        },
+        required: ["name"]
+      }
+    },
+    required: ["$$type", "value"]
+  };
+}
+function convertObjectPropType(propType, baseSchema, suppressDynamic) {
   const schema = structuredClone(baseSchema);
@@ -982,3 +1022,3 @@ schema.type = "object";
   for (const [key, subPropType] of Object.entries(shape)) {
-    const propSchema = propTypeToJsonSchema(subPropType);
+    const propSchema = propTypeToJsonSchema(subPropType, suppressDynamic);
     if (subPropType.settings?.required === true) {
@@ -1000,3 +1040,3 @@ valueRequired.push(key);
 }
-function convertArrayPropType(propType, baseSchema) {
+function convertArrayPropType(propType, baseSchema, suppressDynamic) {
   const schema = structuredClone(baseSchema);
@@ -1007,3 +1047,3 @@ schema.type = "object";
   if (itemPropType) {
-    items = convertPropTypeToJsonSchema(itemPropType);
+    items = propTypeToJsonSchema(itemPropType, suppressDynamic);
   }
@@ -1022,5 +1062,2 @@ schema.properties = {
 }
-function convertPropTypeToJsonSchema(propType) {
-  return propTypeToJsonSchema(propType);
-}
 var nonConfigurablePropKeys = ["_cssid", "classes", "attributes"];
@@ -1374,3 +1411,4 @@ function isPropKeyConfigurable(propKey, propType) {
   enrichWithIntention,
-  removeIntention
+  removeIntention,
+  setDynamicTagNamesResolver
 };
@@ -1377,0 +1415,0 @@ export {

package.json

 {
   "name": "@elementor/editor-props",
   "description": "This package contains the props model for the Elementor editor",
-  "version": "4.2.0-924",
+  "version": "4.2.0-925",
   "private": false,
@@ -43,3 +43,3 @@ "author": "Elementor Team",
   "dependencies": {
-    "@elementor/schema": "4.2.0-924",
+    "@elementor/schema": "4.2.0-925",
     "jsonschema": "1.5.0"
@@ -46,0 +46,0 @@ },

src/index.ts

@@ -10,2 +10,3 @@ import { adjustLlmPropValueSchema } from './utils/adjust-llm-prop-value-schema';
 	removeIntention,
+	setDynamicTagNamesResolver,
 } from './utils/props-to-llm-schema';
@@ -48,2 +49,3 @@ import { validatePropValue } from './utils/validate-prop-value';
 	removeIntention,
+	setDynamicTagNamesResolver,
 };

src/utils/props-to-llm-schema.ts

 import { type PropsSchema, type PropType } from '../types';
 import { type JsonSchema7 } from './prop-json-schema';
 
-export function propTypeToJsonSchema( propType: PropType ): JsonSchema7 {
+const DYNAMIC_PROP_TYPE_KEY = 'dynamic';
+const OVERRIDABLE_PROP_TYPE_KEY = 'overridable';
+
+type DynamicTagNamesResolver = ( categories: string[] ) => string[];
+
+// Host (editor-canvas) injects a resolver that maps a prop's accepted categories to the names of the
+// dynamic tags allowed for it. Keeping it injectable preserves this lib's purity: without a host the
+// `name` field stays an open string instead of an enum.
+let dynamicTagNamesResolver: DynamicTagNamesResolver | null = null;
+
+export function setDynamicTagNamesResolver( resolver: DynamicTagNamesResolver | null ): void {
+	dynamicTagNamesResolver = resolver;
+}
+
+// A dynamic value replaces the value of the exact node it is attached to, which may be a nested
+// field (e.g. an image's `src`) rather than the property root. It is advertised once per branch, at
+// the outermost prop type that supports it, and suppressed for descendants of that node to avoid
+// offering the same dynamic option twice on a single branch.
+export function propTypeToJsonSchema( propType: PropType, suppressDynamic: boolean = false ): JsonSchema7 {
 	const description = propType.meta?.description;
@@ -21,7 +39,7 @@
 		case 'union':
-			return convertUnionPropType( propType, schema );
+			return convertUnionPropType( propType, schema, suppressDynamic );
 		case 'object':
-			return convertObjectPropType( propType, schema );
+			return convertObjectPropType( propType, schema, suppressDynamic );
 		case 'array':
-			return convertArrayPropType( propType, schema );
+			return convertArrayPropType( propType, schema, suppressDynamic );
 		default:
@@ -77,11 +95,18 @@ return convertPlainPropType( propType, schema );
 /**
- * Converts a union prop type to JSON Schema ( электричество anyOf)
+ * Converts a union prop type to JSON Schema (anyOf).
  *
- * @param propType   The union prop type to convert
- * @param baseSchema Base schema to extend
+ * @param propType        The union prop type to convert
+ * @param baseSchema      Base schema to extend
+ * @param suppressDynamic When true, an ancestor already offered the dynamic option for this branch
  */
-function convertUnionPropType( propType: PropType & { kind: 'union' }, baseSchema: JsonSchema7 ): JsonSchema7 {
+function convertUnionPropType(
+	propType: PropType & { kind: 'union' },
+	baseSchema: JsonSchema7,
+	suppressDynamic: boolean
+): JsonSchema7 {
 	const schema = structuredClone( baseSchema );
 
 	const propTypes = propType.prop_types || {};
+	const offersDynamic = ! suppressDynamic && Boolean( propTypes[ DYNAMIC_PROP_TYPE_KEY ] );
+	const suppressNestedDynamic = suppressDynamic || offersDynamic;
 	const schemas: JsonSchema7[] = [];
@@ -91,7 +116,12 @@
 	for ( const [ typeKey, subPropType ] of Object.entries( propTypes ) ) {
-		if ( typeKey === 'dynamic' || typeKey === 'overridable' ) {
+		if ( typeKey === OVERRIDABLE_PROP_TYPE_KEY ) {
 			continue;
 		}
-		const subSchema = convertPropTypeToJsonSchema( subPropType );
-		schemas.push( subSchema );
+		if ( typeKey === DYNAMIC_PROP_TYPE_KEY ) {
+			if ( offersDynamic ) {
+				schemas.push( convertDynamicPropType( subPropType ) );
+			}
+			continue;
+		}
+		schemas.push( propTypeToJsonSchema( subPropType, suppressNestedDynamic ) );
 	}
@@ -110,3 +140,46 @@
 
-function convertObjectPropType( propType: PropType & { kind: 'object' }, baseSchema: JsonSchema7 ): JsonSchema7 {
+// Emits a compact representation of the `dynamic` union member. It is offered as one option of THIS
+// node's value (e.g. a property root, or a nested field such as an image's `src`): put the dynamic
+// object exactly here, in place of the sibling static variant. Only `name` is required from the LLM
+// (constrained to the tags allowed here); `group` is filled by the host resolver, and `settings` are
+// described per-tag in the dynamic-tags resource, so the full tag catalog is never inlined.
+function convertDynamicPropType( propType: PropType ): JsonSchema7 {
+	const categories = Array.isArray( propType.settings?.categories )
+		? ( propType.settings.categories as string[] )
+		: [];
+	const allowedTagNames = dynamicTagNamesResolver?.( categories ) ?? [];
+
+	return {
+		type: 'object',
+		description:
+			'Bind THIS value to a dynamic tag instead of a static value (this may be a nested field, ' +
+			'e.g. an image\'s "src"). Look up the chosen tag in the "elementor://dynamic-tags" resource ' +
+			'and populate "settings" exactly as its schema requires.',
+		properties: {
+			$$type: { type: 'string', const: DYNAMIC_PROP_TYPE_KEY },
+			value: {
+				type: 'object',
+				properties: {
+					name: {
+						type: 'string',
+						description: 'Dynamic tag name from "elementor://dynamic-tags".',
+						...( allowedTagNames.length ? { enum: allowedTagNames } : {} ),
+					},
+					settings: {
+						type: 'object',
+						description: "Tag settings matching the chosen tag's schema in the resource.",
+					},
+				},
+				required: [ 'name' ],
+			},
+		},
+		required: [ '$$type', 'value' ],
+	};
+}
+
+function convertObjectPropType(
+	propType: PropType & { kind: 'object' },
+	baseSchema: JsonSchema7,
+	suppressDynamic: boolean
+): JsonSchema7 {
 	const schema = structuredClone( baseSchema );
@@ -141,3 +214,3 @@
 	for ( const [ key, subPropType ] of Object.entries( shape ) ) {
-		const propSchema = propTypeToJsonSchema( subPropType );
+		const propSchema = propTypeToJsonSchema( subPropType, suppressDynamic );
 
@@ -165,3 +238,7 @@ // Check if this property is required
 
-function convertArrayPropType( propType: PropType & { kind: 'array' }, baseSchema: JsonSchema7 ): JsonSchema7 {
+function convertArrayPropType(
+	propType: PropType & { kind: 'array' },
+	baseSchema: JsonSchema7,
+	suppressDynamic: boolean
+): JsonSchema7 {
 	const schema = structuredClone( baseSchema );
@@ -175,3 +252,3 @@
 	if ( itemPropType ) {
-		items = convertPropTypeToJsonSchema( itemPropType );
+		items = propTypeToJsonSchema( itemPropType, suppressDynamic );
 	}
@@ -192,6 +269,2 @@
 
-function convertPropTypeToJsonSchema( propType: PropType ): JsonSchema7 {
-	return propTypeToJsonSchema( propType );
-}
-
 export const nonConfigurablePropKeys = [ '_cssid', 'classes', 'attributes' ] as readonly string[];
@@ -198,0 +271,0 @@

src/utils/test-utils/stubs.ts

@@ -53,2 +53,169 @@ import { type ObjectPropType, type PropsSchema } from '../../types';
 	},
+	dynamicText: {
+		kind: 'union',
+		default: null,
+		meta: {
+			description: 'A text value that also supports dynamic tags',
+		},
+		settings: {},
+		prop_types: {
+			string: {
+				kind: 'string',
+				key: 'string',
+				default: null,
+				meta: {},
+				settings: {},
+				dependencies: undefined,
+				initial_value: null,
+			},
+			dynamic: {
+				kind: 'plain',
+				key: 'dynamic',
+				default: null,
+				meta: {},
+				settings: {
+					categories: [ 'text' ],
+				},
+				dependencies: undefined,
+				initial_value: null,
+			},
+			overridable: {
+				kind: 'plain',
+				key: 'overridable',
+				default: null,
+				meta: {},
+				settings: {},
+				dependencies: undefined,
+				initial_value: null,
+			},
+		},
+		dependencies: undefined,
+		initial_value: null,
+	},
+	htmlV3Title: {
+		kind: 'union',
+		default: null,
+		meta: {},
+		settings: {},
+		prop_types: {
+			'html-v3': {
+				kind: 'object',
+				key: 'html-v3',
+				default: null,
+				meta: {},
+				settings: {},
+				shape: {
+					content: {
+						kind: 'union',
+						default: null,
+						meta: {},
+						settings: {},
+						prop_types: {
+							string: {
+								kind: 'string',
+								key: 'string',
+								default: null,
+								meta: {},
+								settings: {},
+								dependencies: undefined,
+								initial_value: null,
+							},
+							dynamic: {
+								kind: 'plain',
+								key: 'dynamic',
+								default: null,
+								meta: {},
+								settings: { categories: [ 'text' ] },
+								dependencies: undefined,
+								initial_value: null,
+							},
+						},
+						dependencies: undefined,
+						initial_value: null,
+					},
+				},
+				dependencies: undefined,
+				initial_value: null,
+			},
+			dynamic: {
+				kind: 'plain',
+				key: 'dynamic',
+				default: null,
+				meta: {},
+				settings: { categories: [ 'text' ] },
+				dependencies: undefined,
+				initial_value: null,
+			},
+		},
+		dependencies: undefined,
+		initial_value: null,
+	},
+	dynamicImage: {
+		kind: 'object',
+		key: 'image',
+		default: null,
+		meta: {},
+		settings: {},
+		shape: {
+			src: {
+				kind: 'union',
+				default: null,
+				meta: {},
+				settings: {},
+				prop_types: {
+					'image-src': {
+						kind: 'object',
+						key: 'image-src',
+						default: null,
+						meta: {},
+						settings: {},
+						shape: {
+							id: {
+								kind: 'number',
+								key: 'image-attachment-id',
+								default: null,
+								meta: {},
+								settings: {},
+								dependencies: undefined,
+								initial_value: null,
+							},
+							url: {
+								kind: 'string',
+								key: 'url',
+								default: null,
+								meta: {},
+								settings: {},
+								dependencies: undefined,
+								initial_value: null,
+							},
+						},
+						dependencies: undefined,
+						initial_value: null,
+					},
+					dynamic: {
+						kind: 'plain',
+						key: 'dynamic',
+						default: null,
+						meta: {},
+						settings: { categories: [ 'image' ] },
+						dependencies: undefined,
+						initial_value: null,
+					},
+				},
+				dependencies: undefined,
+				initial_value: null,
+			},
+			size: {
+				kind: 'string',
+				key: 'string',
+				default: null,
+				meta: {},
+				settings: {},
+				dependencies: undefined,
+				initial_value: null,
+			},
+		},
+		dependencies: undefined,
+		initial_value: null,
+	},
 	alignContent: {
@@ -55,0 +222,0 @@ kind: 'string',

No alert changes

Improved metrics

Total package byte prevSize

882286

2.12%

Lines of code

13711

2.36%

Dependency changes

• + Added

  @elementor/schema@4.2.0-925
  (transitive)

• - Removed

  @elementor/schema@4.2.0-924
  (transitive)

• Updated

  @elementor/schema@4.2.0-925