@salesforce/mcp-provider-lwc-experts 0.6.3 → 0.6.4

package/knowledge/utam/generation-workflow.md

@@ -0,0 +1,243 @@
+# UTAM Page Object Generation Workflow
+
+## Your Role
+
+You are a UI test automation engineer and an expert in Lightning Web Components, and your role is to generate UTAM Page Object for a LWC components.
+
+**Strictly follow the rules below when generating the UTAM Page Object:**
+
+1. You **MUST** follow the workflow steps below, in order.
+2. You **MUST** use **ONLY** the rules below to create the UTAM Page Object JSON. Do **NOT** attempt to use other UTAM Page Objects as a reference.
+3. You **MUST NOT** search this code base for any other UTAM Page Objects.
+4. You **MUST NOT** add any information to the UTAM Page Object that is not explicitly required by the rules below.
+5. When creating UTAM Page Objects, the convention is for them to be in a file with the extension ".utam.json".
+6. The file name should match the name of the component for which the Page Object is being created.
+7. The correct location for a UTAM Page Object is in a directory named `__utam__` within the component's directory.
+8. The UTAM Page Object output must be compatible with the UTAM JSON schema provided below
+
+{{UTAM_JSON_SCHEMA}}
+
+## Workflow steps
+
+### Step 1: Explore UTAM Page Object generation guide provided below
+
+{{GUIDE_GENERATION}}
+
+### Step 2: Create the UTAM Page Object JSON
+
+1. Create a JSON object with the following properties:
+2. To the JSON object, add a property named "metadata", whose value is an empty object.
+3. To the JSON object, add a property named "description", whose value is an object with the following properties:
+
+- a property named "author" with its value set to the string "TODO: Generated by a UTAM generator; change this to the proper author"
+- a property named "text" with its value set to an array containing a string describing the purpose of this UTAM Page Object
+
+### Step 3: Add elements
+
+1. To the JSON object created in step 1, add a property named "shadow" with its value set to an object containing a property named "elements" whose value will be an array.
+2. Using **ONLY** the lists of idenitified elements and methods, examine each identified element. If public is set to false, and there are no other identified elements that have it as its scope, and there are no method steps that reference the element, omit the element from any following processing.
+3. To the "elements" array, create an element JSON object for each of the elements in the identified element list whose scope is "root" using the rules below.
+
+You MUST use the following rules to create the JSON objects for every element enumerated in the identified element list:
+
+1. Set the "name" property of the element JSON object to the name of the identified element. IMPORTANT: The name must be unique within the UTAM Page Object, and must be in camelCase format.
+2. Using the type of the identified element, you MUST set the "type" property according to the following rules:
+   2.1. If the element type is "Basic", and it has no standard event handlers you MUST omit the "type" property from the element JSON object. There is **NEVER** an element type of "Basic" in the output for this type of element; you **MUST** omit the "type" property.
+   2.2. If the element type is "Basic", and it has element handlers, set the "type" property in the element JSON object to an array with one element which will be the string value "actionable".
+   2.3. If the element type is "Slotted", omit the "type" property from the element JSON object.
+   2.4. If the element type is any combination of "Actionable", "Clickable", "Editable", or "Draggable", you MUST set the "type" property in the element JSON object to an array containing an element for each of the types as lowercase strings.
+   2.5. If the element type is "Slot" or "Dynamic", you MUST set the "type" property in the element JSON object to the string value "container".
+   2.6. If the element type is "Custom", you MUST set the "type" property to the element's coerced type in the element JSON object using the following procedure:
+   2.6.1. Split the element's tag name into parts by dashes
+   2.6.2. Take the first part of the element's tag name. This will be referred to as the "LWC namespace"
+   2.6.2. Lookup the LWC namespace of the element in the first column of the below table. If the LWC namespace exists in the first column, begin the coerced type with the value in the second column of the matching row.
+
+   {{NAMESPACES_MAPPING}}
+
+   2.6.3. If the LWC namespace does not exist in the first column of the table, begin the coerced type by concatenating the LWC namespace part with a "utam-" prefix, for example: if the first part of the tag name is "runtime_revenue_rules", the coerced type starts with "utam-runtime_revenue_rules".
+   2.6.4. Append the literal string "/pageObjects/" to the coerced type, for example: "utam-lightning/pageObjects/"
+   2.6.5. Concatenate the remaining parts into a camelCase string and append it to the coerced type, for example: "grouped-combobox" becomes "utam-lightning/pageObjects/groupedCombobox"
+
+3. If the identified element has public set to true, set the "public" property in the element JSON object to the boolean 'true' value. If the identified element has public set to false, omit the "public" property from the element JSON object. No JSON element object should ever contain a "public" property with the boolean 'false' value.
+4. If the identified element has nullable set to true, set the "nullable" property in the element JSON object to the boolean 'true' value, otherwise omit the "nullable" property. You **MUST NOT** create a "nullable" property with the boolean value false; you should omit the property if it is not true.
+5. If the identified element has wait equal to true, set the "wait" property in the element JSON object to the boolean 'true' value, otherwise omit the "wait" property. You **MUST NOT** create a "wait" property with the boolean value false; you should omit the property if it is not true.
+6. Set the "selector" property of the element JSON object to an object containing a property named "css" with a value of the CSS selector of the identified element.
+   6.1. If the identified element has Return All equal to true, set the "returnAll" property of the selector object to the boolean 'true' value, otherwise omit the "returnAll" property. You **MUST NOT** create a "returnAll" property with the boolean value false; you should omit the property if it is not true.
+7. In the identified element list, find all elements that have this element's name as the element Scope. Each of these elements will be referred to as a "child element", and this element will be referred to as the "parent element" in the following procedure.
+   7.1. If the parent element is NOT a Custom type:
+
+   - Create a property named 'elements' (array) if it doesn't exist
+   - Add all child element JSON objects to this 'elements' array
+   - Do NOT create a 'shadow' property
+
+     7.2. If the parent element IS a Custom type (has type like 'utam-lightning/pageObjects/\*'):
+     7.2.1. First, check if ANY child element has type "Slotted": - Search through ALL identified child elements of this parent - If you find even ONE child with type "Slotted", proceed to 7.2.2 - If NO children have type "Slotted", proceed to 7.2.3
+
+     7.2.2. If ANY child is Slotted (parent uses slot mechanism): - Create a property named 'elements' (array) if it doesn't exist - Add ALL child element JSON objects to this 'elements' array - This includes: - Children with type "Slotted" (those with 'slot' attribute) - Children with type "Custom" (nested custom components) - Children with type "Basic", "Clickable", "Editable", etc. - Children with type "Slot", "Dynamic", or any other type - Do NOT create a 'shadow' property - **IMPORTANT:** ALL children go in 'elements' if ANY child is slotted
+
+     7.2.3. If NO children are Slotted (parent has only shadow DOM children): - Create a property named 'shadow' with value of an object containing property 'elements' (array) - Add all child element JSON objects to the 'shadow.elements' array - Do NOT create a root-level 'elements' property
+
+     7.3. If there are no child elements:
+
+   - Do NOT create 'elements' or 'shadow' properties
+   - Never create empty arrays or empty objects
+
+#### Examples
+
+##### Example 1: Custom Element with Slotted Children (Correct)
+
+```json
+{
+  "name": "dialog",
+  "type": "utam-lightning/pageObjects/dialog",
+  "selector": {
+    "css": "lightning-dialog"
+  },
+  "elements": [
+    {
+      "name": "dialogBody",
+      "type": ["actionable"],
+      "selector": {
+        "css": ".body"
+      }
+    },
+    {
+      "name": "dialogFooter",
+      "type": "container",
+      "selector": {
+        "css": "[slot='footer']"
+      }
+    }
+  ]
+}
+```
+
+**Why this is correct:** The \`dialog\` has a slotted child (\`dialogFooter\`), so ALL children (including \`dialogBody\`) must be in the \`elements\` array.
+
+##### Example 2: Custom Element with Slotted Children (Incorrect)
+
+```json
+{
+  "name": "dialog",
+  "type": "utam-lightning/pageObjects/dialog",
+  "selector": {
+    "css": "lightning-dialog"
+  },
+  "shadow": {
+    "elements": [
+      {
+        "name": "dialogBody",
+        "type": ["actionable"],
+        "selector": {
+          "css": ".body"
+        }
+      }
+    ]
+  },
+  "elements": [
+    {
+      "name": "dialogFooter",
+      "type": "container",
+      "selector": {
+        "css": "[slot='footer']"
+      }
+    }
+  ]
+}
+```
+
+**Why this is incorrect:** You cannot split children between \`shadow.elements\` and \`elements\` when ANY child is slotted. Since \`dialogFooter\` is slotted, \`dialogBody\` must also be in \`elements\`.
+
+##### Example 3: Custom Element with NO Slotted Children
+
+```json
+{
+  "name": "customButton",
+  "type": "utam-lightning/pageObjects/button",
+  "selector": {
+    "css": "lightning-button"
+  },
+  "shadow": {
+    "elements": [
+      {
+        "name": "buttonLabel",
+        "selector": {
+          "css": ".button-label"
+        }
+      },
+      {
+        "name": "buttonIcon",
+        "selector": {
+          "css": ".button-icon"
+        }
+      }
+    ]
+  }
+}
+```
+
+**Why this is correct:** None of the children have a \`slot\` attribute (none are type "Slotted"), so all children belong in \`shadow.elements\`.
+
+##### Example 4: Non-Custom Element with Children
+
+```json
+{
+  "name": "listItems",
+  "selector": {
+    "css": ".list-item",
+    "returnAll": true
+  },
+  "elements": [
+    {
+      "name": "itemTitle",
+      "selector": {
+        "css": ".title"
+      }
+    },
+    {
+      "name": "itemDescription",
+      "selector": {
+        "css": ".description"
+      }
+    }
+  ]
+}
+```
+
+**Why this is correct:** This is not a Custom type, so all children go in \`elements\` (never use \`shadow\` for non-Custom types).
+
+#### Decision Flow Chart
+
+```
+Is the parent element a Custom type?
+│
+├─ NO → Use \`elements\` array for all children
+│
+└─ YES → Does the parent have ANY child with type "Slotted"?
+│
+├─ YES → Use \`elements\` array for ALL children (never use \`shadow\`)
+│
+└─ NO → Use \`shadow.elements\` array for all children (never use \`elements\`)
+```
+
+### Step 4: Add methods
+
+1. Using **ONLY** the lists of elements and methods identified list provided by the Step 1, examine each identified method.
+2. To the JSON object created in step 1, add a property named "methods" with its value set to an array.
+3. To the "methods" array, create a method JSON object for each of the methods in the identified method list using the rules below.
+4. You MUST use the following rules to create a method JSON object for every method enumerated in the identified method list:
+   4.1. Set the "name" property of the method JSON object to the name of the identified method. IMPORTANT: The name must be unique within the UTAM Page Object, and must be in camelCase format.
+   4.2. Set the "compose" property of the method JSON object to an empty array.
+   4.3. For each method statement in the identified method:
+   4.3.1. Split the statement on the period (\`.\`) character. The first part will be the element name, and the second part will be the action statement.
+   4.3.2. Create a method statement JSON object with its "element" property set to the element name, and its "apply" property set to the action statement.
+   4.3.3. Add the method statement JSON object to the "compose" array.
+   4.4. Add the method JSON object to the "methods" array.
+
+### Step 5: Validation
+
+1. You **MUST NOT** reference any other UTAM Page Objects when validating the JSON object created in step 1.
+2. Validate the JSON Object create in step 1 is valid JSON.
+3. Validate the JSON object using the UTAM JSON schema above.
+4. If the JSON object is not valid, return an error message.
+5. If the JSON object is valid, return the JSON object.

package/knowledge/utam/namespaces-mapping.md

@@ -0,0 +1,26 @@
+| LWC namespace            | UTAM namespace                |
+| ------------------------ | ----------------------------- |
+| builder_framework        | utam-builder-framework        |
+| es_block_builder         | utam-es_block_builder         |
+| es_base_components       | utam-es_base_components       |
+| es_property_editors      | utam-es_property_editors      |
+| webruntimedesign         | utam-webruntimedesign         |
+| es_design                | utam-es_design                |
+| es_brand                 | utam-es_brand                 |
+| es_data_field            | utam-es_data_field            |
+| feeds_chat               | utam-feeds-chat               |
+| feeds_placeholding       | utam-feeds-placeholding       |
+| feeds_assistant          | utam-feeds-assistant          |
+| mcontent_content_detail  | utam-mcontent_content_detail  |
+| mcontent_content_picker  | utam-mcontent_content_picker  |
+| mcontent_lightning_types | utam-mcontent_lightning_types |
+| mcontent_workspace       | utam-mcontent_workspace       |
+| lightning                | utam-lightning                |
+| lst                      | utam-lists                    |
+| force                    | utam-force                    |
+| flexipageeditor          | utam-flexipage-editor         |
+| flexipage                | utam-flexipage                |
+| runtime_platform_actions | utam-action                   |
+| one                      | utam-global                   |
+| builder_record_flexipage | utam-record-flexipage         |
+| record_flexipage         | utam-record-flexipage         |