@elementor/editor-components 3.35.0-356 → 3.35.0-358

package/dist/index.mjs

@@ -2,7 +2,7 @@
 import { injectIntoLogic, injectIntoTop } from "@elementor/editor";
 import {
   registerElementType,
-  settingsTransformersRegistry
+  settingsTransformersRegistry as settingsTransformersRegistry2
 } from "@elementor/editor-canvas";
 import { getV1CurrentDocument } from "@elementor/editor-documents";
 import {
@@ -19,7 +19,7 @@ import { __registerSlice as registerSlice } from "@elementor/store";
 import { __ as __17 } from "@wordpress/i18n";
 
 // src/component-instance-transformer.ts
-import { createTransformer } from "@elementor/editor-canvas";
+import { createTransformer, RenderContext } from "@elementor/editor-canvas";
 import { __getState as getState } from "@elementor/store";
 
 // src/store/store.ts
@@ -73,7 +73,8 @@ var apiClient = {
     {
       componentIds
     }
-  ).then((res) => res.data.data)
+  ).then((res) => res.data.data),
+  validate: async (payload) => await httpService().post(`${BASE_URL}/create-validate`, payload).then((res) => res.data)
 };
 
 // src/store/thunks.ts
@@ -173,7 +174,11 @@ var selectComponents = createSelector(
   selectData,
   selectUnpublishedData,
   (data, unpublishedData) => [
-    ...unpublishedData.map((item) => ({ uid: item.uid, name: item.name })),
+    ...unpublishedData.map((item) => ({
+      uid: item.uid,
+      name: item.name,
+      overridableProps: item.overridableProps
+    })),
     ...data
   ]
 );
@@ -237,25 +242,73 @@ var invalidateComponentDocumentData = (id) => {
 };
 
 // src/component-instance-transformer.ts
+var componentInstanceContext = new RenderContext("component-instance", {
+  overrides: {}
+});
 var componentInstanceTransformer = createTransformer(
-  async ({ component_id: id }) => {
+  async ({
+    component_id: id,
+    overrides: overridesValue
+  }) => {
     const unpublishedComponents = selectUnpublishedComponents(getState());
     const unpublishedComponent = unpublishedComponents.find(({ uid }) => uid === id);
+    const overrides = overridesValue?.reduce((acc, override) => ({ ...acc, ...override }), {});
     if (unpublishedComponent) {
-      return structuredClone(unpublishedComponent.elements);
+      return {
+        elements: structuredClone(unpublishedComponent.elements),
+        overrides
+      };
     }
     if (typeof id !== "number") {
-      throw new Error(`Component ID "${id}" not found.`);
+      throw new Error(`Component ID "${id}" not valid.`);
     }
     const data = await getComponentDocumentData(id);
-    return data?.elements ?? [];
+    return {
+      elements: data?.elements ?? [],
+      overrides
+    };
   }
 );
 
 // src/component-overridable-transformer.ts
-import { createTransformer as createTransformer2 } from "@elementor/editor-canvas";
-var componentOverridableTransformer = createTransformer2((value) => {
-  return value.origin_value;
+import { createTransformer as createTransformer2, settingsTransformersRegistry } from "@elementor/editor-canvas";
+var componentOverridableTransformer = createTransformer2(
+  (value, options) => {
+    const { overrides } = componentInstanceContext.get();
+    const overrideValue = overrides?.[value.override_key];
+    if (overrideValue) {
+      const isOverride = isOriginValueOverride(value.origin_value);
+      if (isOverride) {
+        return transformOverride(value, options, overrideValue);
+      }
+      return overrideValue;
+    }
+    return value.origin_value;
+  }
+);
+function transformOverride(value, options, overrideValue) {
+  const transformer = settingsTransformersRegistry.get("override");
+  if (!transformer) {
+    return null;
+  }
+  const transformedValue = transformer(value.origin_value.value, options);
+  if (!transformedValue) {
+    return null;
+  }
+  const [key] = Object.keys(transformedValue);
+  return {
+    [key]: overrideValue
+  };
+}
+function isOriginValueOverride(originValue) {
+  return originValue.$$type === "override";
+}
+
+// src/component-override-transformer.ts
+import { createTransformer as createTransformer3 } from "@elementor/editor-canvas";
+var componentOverrideTransformer = createTransformer3((override) => {
+  const { override_key: key, override_value: overrideValue } = override;
+  return { [key]: overrideValue };
 });
 
 // src/components/component-panel-header/component-panel-header.tsx
@@ -567,9 +620,10 @@ function createComponentView(options) {
       return currentDocument?.id === this.getComponentId();
     }
     afterSettingsResolve(settings) {
-      if (settings.component_instance) {
+      const componentInstance = settings.component_instance;
+      if (componentInstance) {
         this.collection = this.legacyWindow.elementor.createBackboneElementsCollection(
-          settings.component_instance
+          componentInstance.elements
         );
         this.collection.models.forEach(setInactiveRecursively);
         settings.component_instance = "<template data-children-placeholder></template>";
@@ -843,7 +897,8 @@ var createComponentModel = (component) => {
             value: component.id ?? component.uid
           }
         }
-      }
+      },
+      overridable_props: component.overridableProps
     },
     editor_settings: {
       title: component.name,
@@ -1116,25 +1171,25 @@ import { __ as __8 } from "@wordpress/i18n";
 import { __privateRunCommand as runCommand2 } from "@elementor/editor-v1-adapters";
 import { __dispatch as dispatch3 } from "@elementor/store";
 import { generateUniqueId } from "@elementor/utils";
-function createUnpublishedComponent(name, element, eventData) {
-  const uid = generateUniqueId("component");
-  const componentBase = { uid, name };
+function createUnpublishedComponent(name, element, eventData, overridableProps, uid) {
+  const generatedUid = uid ?? generateUniqueId("component");
+  const componentBase = { uid: generatedUid, name, overridableProps };
   dispatch3(
     slice.actions.addUnpublished({
       ...componentBase,
       elements: [element]
     })
   );
-  dispatch3(slice.actions.addCreatedThisSession(uid));
+  dispatch3(slice.actions.addCreatedThisSession(generatedUid));
   replaceElementWithComponent(element, componentBase);
   trackComponentEvent({
     action: "created",
-    component_uid: uid,
+    component_uid: generatedUid,
     component_name: name,
     ...eventData
   });
   runCommand2("document/save/auto");
-  return uid;
+  return generatedUid;
 }
 
 // src/components/create-component-form/hooks/use-form.ts
@@ -2273,72 +2328,320 @@ function isPropAllowed(bind) {
 import { getMCPByDomain as getMCPByDomain2 } from "@elementor/editor-mcp";
 
 // src/mcp/save-as-component-tool.ts
-import { getContainer as getContainer2 } from "@elementor/editor-elements";
-import { getMCPByDomain } from "@elementor/editor-mcp";
+import { DOCUMENT_STRUCTURE_URI, WIDGET_SCHEMA_URI } from "@elementor/editor-canvas";
+import { getContainer as getContainer2, getElementType, getWidgetsCache as getWidgetsCache2 } from "@elementor/editor-elements";
+import { getMCPByDomain, toolPrompts } from "@elementor/editor-mcp";
+import { AxiosError } from "@elementor/http-client";
 import { z as z6 } from "@elementor/schema";
+import { generateUniqueId as generateUniqueId3 } from "@elementor/utils";
 var InputSchema = {
   element_id: z6.string().describe(
     'The unique identifier of the element to save as a component. Use the "list-elements" tool to find available element IDs in the current document.'
   ),
-  component_name: z6.string().describe("The name for the new component. Should be descriptive and unique among existing components.")
+  component_name: z6.string().describe("The name for the new component. Should be descriptive and unique among existing components."),
+  overridable_props: z6.object({
+    props: z6.record(
+      z6.object({
+        elementId: z6.string().describe("The id of the child element that you want to override its settings"),
+        propKey: z6.string().describe(
+          'The property key of the child element that you want to override its settings (e.g., "text", "url", "tag"). To get the available propKeys for an element, use the "get-element-type-config" tool.'
+        )
+      })
+    )
+  }).optional().describe(
+    'Overridable properties configuration. Specify which CHILD element properties can be customized. Only elementId and propKey are required; To get the available propKeys for a child element you must use the "get-element-type-config" tool.'
+  )
 };
 var OutputSchema = {
   message: z6.string().optional().describe("Additional information about the operation result"),
   component_uid: z6.string().optional().describe("The unique identifier of the newly created component (only present on success)")
 };
-var VALID_ELEMENT_TYPES = ["e-div-block", "e-flexbox", "e-tabs"];
 var ERROR_MESSAGES = {
   ELEMENT_NOT_FOUND: "Element not found. Use 'list-elements' to get valid element IDs.",
-  ELEMENT_NOT_ONE_OF_TYPES: `Element is not one of the following types: ${VALID_ELEMENT_TYPES.join(", ")}`,
+  ELEMENT_NOT_ONE_OF_TYPES: (validTypes) => `Element is not one of the following types: ${validTypes.join(", ")}`,
   ELEMENT_IS_LOCKED: "Cannot save a locked element as a component."
 };
 var handleSaveAsComponent = async (params) => {
-  const { element_id: elementId, component_name: componentName } = params;
+  const { element_id: elementId, component_name: componentName, overridable_props: overridablePropsInput } = params;
+  const validElementTypes = getValidElementTypes();
   const container = getContainer2(elementId);
   if (!container) {
     throw new Error(ERROR_MESSAGES.ELEMENT_NOT_FOUND);
   }
   const elType = container.model.get("elType");
-  if (!VALID_ELEMENT_TYPES.includes(elType)) {
-    throw new Error(ERROR_MESSAGES.ELEMENT_NOT_ONE_OF_TYPES);
+  if (!validElementTypes.includes(elType)) {
+    throw new Error(ERROR_MESSAGES.ELEMENT_NOT_ONE_OF_TYPES(validElementTypes));
   }
   const element = container.model.toJSON({ remove: ["default"] });
   if (element?.isLocked) {
     throw new Error(ERROR_MESSAGES.ELEMENT_IS_LOCKED);
   }
-  const uid = createUnpublishedComponent(componentName, element, null);
+  const overridableProps = overridablePropsInput ? enrichOverridableProps(overridablePropsInput, element) : void 0;
+  if (overridableProps) {
+    updateElementDataWithOverridableProps(element, overridableProps);
+  }
+  const uid = generateUniqueId3("component");
+  try {
+    await apiClient.validate({
+      items: [
+        { uid, title: componentName, elements: [element], settings: { overridable_props: overridableProps } }
+      ]
+    });
+  } catch (error) {
+    if (error instanceof AxiosError) {
+      throw new Error(error.response?.data.messge);
+    }
+    throw new Error("Unknown error");
+  }
+  createUnpublishedComponent(componentName, element, null, overridableProps, uid);
   return {
     status: "ok",
     message: `Component "${componentName}" created successfully.`,
     component_uid: uid
   };
 };
-var initSaveAsComponentTool = () => {
-  return getMCPByDomain("components").addTool({
-    name: "save-as-component",
-    schema: InputSchema,
-    outputSchema: OutputSchema,
-    description: `Save an existing element as a reusable component in the Elementor editor.
-
-## When NOT to use this tool:
-- Do not use for elements that are already components (widgetType: 'e-component').
-- Do not use for locked elements.
-- Do not guess element IDs. Always use "list-elements" first to get valid IDs.
+function enrichOverridableProps(input, rootElement) {
+  const enrichedProps = {};
+  const defaultGroupId = generateUniqueId3("group");
+  Object.entries(input.props).forEach(([, prop]) => {
+    const { elementId, propKey } = prop;
+    const element = findElementById(rootElement, elementId);
+    if (!element) {
+      throw new Error(`Element with ID "${elementId}" not found in component`);
+    }
+    const elType = element.elType;
+    const widgetType = element.widgetType || element.elType;
+    const elementType = getElementType(widgetType);
+    if (!elementType) {
+      throw new Error(
+        `Element type "${widgetType}" is not atomic or does not have a settings schema. Cannot expose property "${propKey}" for element "${elementId}".`
+      );
+    }
+    if (!elementType.propsSchema[propKey]) {
+      const availableProps = Object.keys(elementType.propsSchema).join(", ");
+      throw new Error(
+        `Property "${propKey}" does not exist in element "${elementId}" (type: ${widgetType}). Available properties: ${availableProps}`
+      );
+    }
+    const overrideKey = generateUniqueId3("prop");
+    const originValue = element.settings?.[propKey] ? element.settings[propKey] : elementType.propsSchema[propKey].default ?? null;
+    const label = generateLabel(propKey);
+    enrichedProps[overrideKey] = {
+      overrideKey,
+      label,
+      elementId,
+      propKey,
+      elType,
+      widgetType,
+      originValue,
+      groupId: defaultGroupId
+    };
+  });
+  return {
+    props: enrichedProps,
+    groups: {
+      items: {
+        [defaultGroupId]: {
+          id: defaultGroupId,
+          label: "Default",
+          props: Object.keys(enrichedProps)
+        }
+      },
+      order: [defaultGroupId]
+    }
+  };
+}
+function updateElementDataWithOverridableProps(rootElement, overridableProps) {
+  Object.values(overridableProps.props).forEach((prop) => {
+    const element = findElementById(rootElement, prop.elementId);
+    if (!element || !element.settings) {
+      return;
+    }
+    element.settings[prop.propKey] = {
+      $$type: "overridable",
+      value: {
+        override_key: prop.overrideKey,
+        origin_value: prop.originValue
+      }
+    };
+  });
+}
+function findElementById(root, targetId) {
+  if (root.id === targetId) {
+    return root;
+  }
+  if (root.elements) {
+    for (const child of root.elements) {
+      const found = findElementById(child, targetId);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+function generateLabel(propKey) {
+  const uniqueId = generateUniqueId3("prop");
+  return `${uniqueId} - ${propKey}`;
+}
+function getValidElementTypes() {
+  const types = getWidgetsCache2();
+  if (!types) {
+    return [];
+  }
+  return Object.entries(types).reduce((acc, [type, value]) => {
+    if (!value.atomic_props_schema || !value.show_in_panel || value.elType === "widget") {
+      return acc;
+    }
+    acc.push(type);
+    return acc;
+  }, []);
+}
+var generatePrompt = () => {
+  const saveAsComponentPrompt = toolPrompts("save-as-component");
+  saveAsComponentPrompt.description(`
+Save an existing element as a reusable component in the Elementor editor.
+
+# When to use this tool
+Use this tool when the user wants to:
+- Create a reusable component from an existing element structure
+- Make specific child element properties customizable in component instances
+- Build a library of reusable design patterns
+
+# When NOT to use this tool
+- Element is already a component (widgetType: 'e-component')
+- Element is locked
+- Element is not an atomic element (atomic_props_schema is not defined)
+- Element elType is a 'widget'
+
+# **CRITICAL - REQUIRED RESOURCES (Must read before using this tool)**
+1. [${DOCUMENT_STRUCTURE_URI}]
+   **MANDATORY** - Required to understand the document structure and identify child elements for overridable properties.
+   Use this resource to find element IDs and understand the element hierarchy.
+
+2. [${WIDGET_SCHEMA_URI}]
+   **MANDATORY** - Required to understand which properties are available for each widget type.
+   Use this to identify available propKeys in the atomic_props_schema for child elements.
+
+# Instructions - MUST FOLLOW IN ORDER
+## Step 1: Identify the Target Element
+1. Read the [${DOCUMENT_STRUCTURE_URI}] resource to understand the document structure
+2. Locate the element you want to save as a component by its element_id
+3. Verify the element type is a valid element type
+4. Ensure the element is not locked and is not already a component
+
+## Step 2: Define Overridable Properties
+Do this step to make child element properties customizable.
+Skip that step ONLY if the user explicitly requests to not make any properties customizable.
+
+1. **Identify Child Elements**
+   - Use the [${DOCUMENT_STRUCTURE_URI}] resource to find all child elements
+   - Note the elementId and widgetType/elType of each child element you want to customize
+
+2. **Find Available Properties**
+   - Use the [${WIDGET_SCHEMA_URI}] resource to find the child element's widget type schema
+   - Review the atomic_props_schema to find available propKeys (ONLY use top-level props)
+   - Common propKeys include: "text", "url", "tag", "size", etc.
+   - Use only the top level properties, do not use nested properties.
+
+3. **Build the overridable_props Object**
+   - For each property you want to make overridable, add an entry:
+     \`{ "elementId": "<child-element-id>", "propKey": "<property-key>" }\`
+   - Group all entries under the "props" object
+
+## Step 3: Execute the Tool
+Call the tool with:
+- element_id: The ID of the parent element to save as component
+- component_name: A descriptive name for the component
+- overridable_props: (Optional) The properties configuration from Step 2
+
+# CONSTRAINTS
+- NEVER try to override properties of the parent element itself - ONLY child elements
+- NEVER use invalid propKeys - always verify against the widget's atomic_props_schema in [${WIDGET_SCHEMA_URI}]
+- Property keys must exist in the child element's atomic_props_schema
+- Element IDs must exist within the target element's children
+- When tool execution fails, read the error message and adjust accordingly
+- The element being saved must not be inside another component
+`);
+  saveAsComponentPrompt.parameter(
+    "element_id",
+    `**MANDATORY** The unique identifier of the element to save as a component.
+Use the [${DOCUMENT_STRUCTURE_URI}] resource to find available element IDs.`
+  );
+  saveAsComponentPrompt.parameter(
+    "component_name",
+    `**MANDATORY** A descriptive name for the new component.
+Should be unique and clearly describe the component's purpose (e.g., "Hero Section", "Feature Card").`
+  );
+  saveAsComponentPrompt.parameter(
+    "overridable_props",
+    `**OPTIONAL** Configuration for which child element properties can be customized in component instances.
 
-## Prerequisites:
-- **Verify element type**: Ensure the element is not already a component (widgetType should not be 'e-component').
-- **Check if element is unlocked**: Locked elements cannot be saved as components.
-- **Check that the element is one of the following types**: ${VALID_ELEMENT_TYPES.join(", ")}
+Structure:
+\`\`\`json
+{
+  "props": {
+    "<unique-key>": {
+      "elementId": "<child-element-id>",
+      "propKey": "<property-key>"
+    }
+  }
+}
+\`\`\`
 
-## Required parameters:
-- **element_id**: The unique ID of the element to save.
-- **component_name**: A descriptive name for the component (2-50 characters).
+To populate this correctly:
+1. Use [${DOCUMENT_STRUCTURE_URI}] to find child element IDs and their widgetType
+2. Use [${WIDGET_SCHEMA_URI}] to find the atomic_props_schema for each child element's widgetType
+3. Only include properties you want to be customizable in component instances
+4. Common propKeys: "text", "url", "tag", "size", "align", etc.`
+  );
+  saveAsComponentPrompt.example(`
+Basic component without overridable properties:
+\`\`\`json
+{
+  "element_id": "abc123",
+  "component_name": "Hero Section"
+}
+\`\`\`
 
-## Example tool call:
+Component with overridable properties:
 \`\`\`json
-{ "element_id": "abc123", "component_name": "Hero Section" }
+{
+  "element_id": "abc123",
+  "component_name": "Feature Card",
+  "overridable_props": {
+    "props": {
+      "heading-text": {
+        "elementId": "heading-123",
+        "propKey": "text"
+      },
+      "button-text": {
+        "elementId": "button-456",
+        "propKey": "text"
+      },
+      "button-link": {
+        "elementId": "button-456",
+        "propKey": "url"
+      }
+    }
+  }
+}
 \`\`\`
-`,
+`);
+  saveAsComponentPrompt.instruction(
+    `After successful creation, the component will be available in the components library and can be inserted into any page or template.`
+  );
+  saveAsComponentPrompt.instruction(
+    `When overridable properties are defined, component instances will show customization controls for those specific properties in the editing panel.`
+  );
+  return saveAsComponentPrompt.prompt();
+};
+var initSaveAsComponentTool = () => {
+  return getMCPByDomain("components").addTool({
+    name: "save-as-component",
+    schema: InputSchema,
+    outputSchema: OutputSchema,
+    description: generatePrompt(),
     handler: handleSaveAsComponent
   });
 };
@@ -2411,7 +2714,8 @@ async function createComponentsBeforeSave({
         unpublishedComponents.map((component) => ({
           id: uidToComponentId.get(component.uid),
           name: component.name,
-          uid: component.uid
+          uid: component.uid,
+          overridableProps: component.overridableProps ? component.overridableProps : void 0
         }))
       )
     );
@@ -2426,7 +2730,8 @@ async function createComponents(components, status) {
     items: components.map((component) => ({
       uid: component.uid,
       title: component.name,
-      elements: component.elements
+      elements: component.elements,
+      settings: component.overridableProps ? { overridable_props: component.overridableProps } : void 0
     }))
   });
   const map = /* @__PURE__ */ new Map();
@@ -2607,8 +2912,9 @@ function init() {
     condition: (_, elementType) => elementType.key === "e-component",
     component: InstanceEditingPanel
   });
-  settingsTransformersRegistry.register("component-instance", componentInstanceTransformer);
-  settingsTransformersRegistry.register("overridable", componentOverridableTransformer);
+  settingsTransformersRegistry2.register("component-instance", componentInstanceTransformer);
+  settingsTransformersRegistry2.register("overridable", componentOverridableTransformer);
+  settingsTransformersRegistry2.register("override", componentOverrideTransformer);
   initMcp();
 }
 export {