From 47905322e08dc80326deda2d5190194f2e9d3ad9 Mon Sep 17 00:00:00 2001 From: "sowmya.sriram" Date: Wed, 15 Apr 2026 19:21:23 +0530 Subject: [PATCH] updated widget rendition guidance --- .../generating-custom-lightning-type/SKILL.md | 217 +++++++++--------- ...osaic-rendition.md => widget-rendition.md} | 58 +++-- 2 files changed, 132 insertions(+), 143 deletions(-) rename skills/generating-custom-lightning-type/references/{mosaic-rendition.md => widget-rendition.md} (57%) diff --git a/skills/generating-custom-lightning-type/SKILL.md b/skills/generating-custom-lightning-type/SKILL.md index 74ab717..75a5912 100644 --- a/skills/generating-custom-lightning-type/SKILL.md +++ b/skills/generating-custom-lightning-type/SKILL.md @@ -1,6 +1,8 @@ --- name: generating-custom-lightning-type -description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, CLT with mosaic aka fragment aka widget, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work." +description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, + Custom Lightning Types (CLTs) with widget/mosaic/fragment rendition/renderer, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. When widget renditions are requested, you + MUST first read the widget-rendition.md reference file in this skill's references/ directory and follow its complete workflow. This is complex - always use this skill for CLT work." --- ## When to Use This Skill @@ -10,7 +12,7 @@ Use this skill when you need to: - Generate JSON Schema-based type definitions for Lightning Platform - Configure CLTs for Einstein Agent actions - Set up editor and renderer configurations for custom UI -- Create CLTs with mosaic/widget/fragment renditions +- Create CLTs with widget/mosaic/fragment rendition - Troubleshoot deployment errors related to Custom Lightning Types ## Specification @@ -24,32 +26,32 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the - **Choose standard Lightning types** when the structure is simple and can be expressed with properties and supported primitive `lightning:type` identifiers. - **Choose Apex class types** (`@apexClassType/...`) when the structure already exists server-side and you want the Apex class to define the shape. - **Include editor/renderer config** only when you need custom UI behavior (custom LWC input/output components). Otherwise, omit. -- **Choose mosaic rendition** only when mosaic/fragment/widget rendition is requested. Refer **Mosaic override pattern** below for guidance. +- **Widget rendition**: After `schema.json` is drafted, you **must read references/widget-rendition.md and follow the "Widget renderer pattern"** section below for complete guidance. Do NOT attempt widget generation without reading the reference file first. ## Critical Rules (Read First) - **Root object schemas MUST include**: - - `"type": "object"` - - `"title"` - - `"lightning:type": "lightning__objectType"` - - `"unevaluatedProperties": false` + - `"type": "object"` + - `"title"` + - `"lightning:type": "lightning__objectType"` + - `"unevaluatedProperties": false` - `"unevaluatedProperties"` is enforced as `false` by the CLT metaschema. Do not set it to `true`. - **Root object schemas MUST NOT include** `"examples"` when `"unevaluatedProperties": false` is set. - **Nested objects (inside `properties`) MUST NOT set** `"lightning:type": "lightning__objectType"`. - - Nested objects should be plain JSON Schema objects (`type`, `properties`, optional `required`, optional `unevaluatedProperties`). + - Nested objects should be plain JSON Schema objects (`type`, `properties`, optional `required`, optional `unevaluatedProperties`). - **List/array properties are highly restricted by the CLT metaschema**: - - **CRITICAL LIMITATION**: the CLT metaschema may reject the `items` keyword entirely. Treat `items` as **disallowed by default**. - - **Root-level arrays** (direct children of the root `properties`): - - **MUST include** `"lightning:type": "lightning__listType"` - - **MUST NOT include** `"items"` - - **OPTIONAL** `"type": "array"` - - **Nested arrays** (arrays inside nested objects) are the most common failure: - - **MUST include** `"type": "array"` - - **MUST NOT include** `"lightning:type": "lightning__listType"` - - **MUST NOT include** `"items"` + - **CRITICAL LIMITATION**: the CLT metaschema may reject the `items` keyword entirely. Treat `items` as **disallowed by default**. + - **Root-level arrays** (direct children of the root `properties`): + - **MUST include** `"lightning:type": "lightning__listType"` + - **MUST NOT include** `"items"` + - **OPTIONAL** `"type": "array"` + - **Nested arrays** (arrays inside nested objects) are the most common failure: + - **MUST include** `"type": "array"` + - **MUST NOT include** `"lightning:type": "lightning__listType"` + - **MUST NOT include** `"items"` - **When `"unevaluatedProperties": false` is set, any unknown keyword will fail validation**. Prefer removing keywords over relaxing strictness. - **Apex class CLTs are minimal**: - - Include **only** `title`, `description` (optional), and `lightning:type` set to `@apexClassType/...`. - - Do **not** add `type`, `properties`, `required`, or `unevaluatedProperties`. + - Include **only** `title`, `description` (optional), and `lightning:type` set to `@apexClassType/...`. + - Do **not** add `type`, `properties`, `required`, or `unevaluatedProperties`. ## Additional CLT Metaschema Validations - **Org namespace validation**: titles/descriptions and other string fields may be validated to ensure you are not using an org namespace in places that are disallowed. @@ -58,26 +60,26 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the ## Primitive Types & Constraints - `lightning__textType` - - Max length 255 + - Max length 255 - `lightning__multilineTextType` - - Max length 2000 + - Max length 2000 - `lightning__richTextType` - - Max length 100000 + - Max length 100000 - `lightning__urlType` - - Max length 2000 - - Optional `lightning:allowedUrlSchemes` enum values: `https`, `http`, `relative`, `mailto`, `tel` + - Max length 2000 + - Optional `lightning:allowedUrlSchemes` enum values: `https`, `http`, `relative`, `mailto`, `tel` - `lightning__dateType` - - Data pattern: YYYY-MM-DD + - Data pattern: YYYY-MM-DD - `lightning__timeType` - - Data pattern: HH:MM:SS.sssZ + - Data pattern: HH:MM:SS.sssZ - `lightning__dateTimeType` - - Data shape is an object with required `dateTime` and optional `timeZone` + - Data shape is an object with required `dateTime` and optional `timeZone` - `lightning__numberType` - - Decimal numbers; optional `maximum`, `minimum`, `multipleOf` + - Decimal numbers; optional `maximum`, `minimum`, `multipleOf` - `lightning__integerType` - - Whole numbers only; optional `maximum`, `minimum` + - Whole numbers only; optional `maximum`, `minimum` - `lightning__booleanType` - - true/false + - true/false ## Allowed Property-Level Keywords When strict validation is enabled (`unevaluatedProperties: false`), keep each property minimal and prefer only keywords known to be allowed: @@ -93,88 +95,85 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr ## Generation Workflow 1. **Confirm the CLT approach** - - If referencing Apex: capture the exact class reference (`@apexClassType/namespace__ClassName$InnerClass`). - - If using standard primitives: list the fields, their Lightning primitive types, and which fields are required. + - If referencing Apex: capture the exact class reference (`@apexClassType/namespace__ClassName$InnerClass`). + - If using standard primitives: list the fields, their Lightning primitive types, and which fields are required. 2. **Draft `schema.json`** - - Start with the root object structure (required root fields). - - Add `properties` using valid primitive `lightning:type` identifiers. - - For nested objects: omit `lightning:type` and keep keywords minimal. - - For arrays: follow the strict list rules (avoid `items`; avoid `lightning:type` on nested arrays). - - **Mosaic rendition**: If the user asks for a CLT with **fragment**, **mosaic**, **widget** rendition, follow the **Mosaic override pattern** after `schema.json` is drafted, using it as the grounding schema for fragment generation. + - Start with the root object structure (required root fields). + - Add `properties` using valid primitive `lightning:type` identifiers. + - For nested objects: omit `lightning:type` and keep keywords minimal. + - For arrays: follow the strict list rules (avoid `items`; avoid `lightning:type` on nested arrays). 3. **(Optional) Draft `editor.json`** (only if custom UI is required) - - **Supported shape:** Top-level `editor` object with `editor.componentOverrides` and `editor.layout`. - - Top-level `editor` object. - - Use `editor.componentOverrides` for component overrides. - - Use `editor.layout` for layout. - - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead. - - **Root override pattern** (most common for fully custom editing UI): - - `editor.componentOverrides["$"] = { "definition": "c/", "attributes": { ... } }` - - When passing schema data into a custom LWC, use attribute mapping with the `{!$attrs.}` syntax: e.g. `"attributes": { "myField": "{!$attrs.value}" }` so the runtime binds schema values to your component's attributes. - - **CRITICAL**: The `` in `{!$attrs.}` must be a property defined in your type schema. For example, if your schema has a property called `temperature`, use `{!$attrs.temperature}`, not `{!$attrs.value}` unless `value` is an actual property. - - **Property-level override pattern** (for individual fields): - - `editor.componentOverrides[""] = { "definition": "es_property_editors/<...>" }` - - **Valid editor components** (examples): `es_property_editors/inputText`, `es_property_editors/inputNumber`, `es_property_editors/inputRichText`, `es_property_editors/inputImage`, `es_property_editors/inputTextarea`. **Do not use** `es_property_editors/inputList`. - - **Collection editor** (for root-level `lightning__listType` properties): Use a collection-level override so the list is edited by a custom component: `collection.editor.componentOverrides["$"] = { "definition": "c/" }`. Alternatively, use `editor.layout` with `lightning/propertyLayout` and `attributes.property = ""` for default list editing. - - **Layout pattern**: - - `editor.layout.definition = "lightning/verticalLayout"` - - `editor.layout.children[*].definition = "lightning/propertyLayout"` with `attributes.property = ""` - - **CRITICAL**: `lightning/propertyLayout` only accepts the `property` attribute. Do NOT add `label`, `title`, or any other attributes — these will fail validation with `additionalProperties: false` errors. - - **Avoid known-invalid patterns**: - - Do not use `es_property_editors/inputList`. - - Do not use `itemSchema` attributes. + - **Supported shape:** Top-level `editor` object with `editor.componentOverrides` and `editor.layout`. + - Top-level `editor` object. + - Use `editor.componentOverrides` for component overrides. + - Use `editor.layout` for layout. + - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead. + - **Root override pattern** (most common for fully custom editing UI): + - `editor.componentOverrides["$"] = { "definition": "c/", "attributes": { ... } }` + - When passing schema data into a custom LWC, use attribute mapping with the `{!$attrs.}` syntax: e.g. `"attributes": { "myField": "{!$attrs.value}" }` so the runtime binds schema values to your component's attributes. + - **CRITICAL**: The `` in `{!$attrs.}` must be a property defined in your type schema. For example, if your schema has a property called `temperature`, use `{!$attrs.temperature}`, not `{!$attrs.value}` unless `value` is an actual property. + - **Property-level override pattern** (for individual fields): + - `editor.componentOverrides[""] = { "definition": "es_property_editors/<...>" }` + - **Valid editor components** (examples): `es_property_editors/inputText`, `es_property_editors/inputNumber`, `es_property_editors/inputRichText`, `es_property_editors/inputImage`, `es_property_editors/inputTextarea`. **Do not use** `es_property_editors/inputList`. + - **Collection editor** (for root-level `lightning__listType` properties): Use a collection-level override so the list is edited by a custom component: `collection.editor.componentOverrides["$"] = { "definition": "c/" }`. Alternatively, use `editor.layout` with `lightning/propertyLayout` and `attributes.property = ""` for default list editing. + - **Layout pattern**: + - `editor.layout.definition = "lightning/verticalLayout"` + - `editor.layout.children[*].definition = "lightning/propertyLayout"` with `attributes.property = ""` + - **CRITICAL**: `lightning/propertyLayout` only accepts the `property` attribute. Do NOT add `label`, `title`, or any other attributes — these will fail validation with `additionalProperties: false` errors. + - **Avoid known-invalid patterns**: + - Do not use `es_property_editors/inputList`. + - Do not use `itemSchema` attributes. 4. **(Optional) Draft `renderer.json`** (only if custom UI or mosaic rendition is required) - - **Supported shape:** Top-level `renderer` object with `renderer.componentOverrides` and `renderer.layout`. - - Top-level `renderer` object. - - Use `renderer.componentOverrides` for component overrides. - - Use `renderer.layout` for layout. - - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead. - - **Root override pattern** (most common for fully custom rendering UI): - - `renderer.componentOverrides["$"] = { "definition": "c/", "attributes": { ... } }` - - Use `{!$attrs.}` in attribute mappings when binding schema data to custom renderer component attributes. - - **CRITICAL**: Attribute mappings like `{!$attrs.propertyName}` must reference properties that **actually exist** in your type schema. Referencing non-existent properties will fail validation. - - **Type matching**: Attribute values must match the expected type for the component. For example, if a component expects a string attribute, passing an integer will fail validation. - - **Mosaic override pattern** (for inline aka declarative mosaic rendition): - - **When to use:** Use this when users request "mosaic", "widget", "fragment", or "cross-platform rendering" for their CLT. - - **Structure:** `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }` - - **REQUIRED workflow:** You MUST follow the complete step-by-step workflow in [Mosaic Rendition Reference](references/mosaic-rendition.md). This workflow is mandatory and includes: - - Use CLT schema as the grounding schema - - Schema parsing and property extraction - - Calling `discoverUiComponents` metadata action to discover available UEM blocks - - Selecting components that represent CLT schema properties - - Calling `getUiComponentSchemas` metadata action to get component schemas - - Building the UEM tree with proper attribute bindings using `{!$attrs.*}` syntax - - Writing output to `renderer.json` in the CLT bundle as per the defined **Structure**. - - **Property-level override pattern**: - - `renderer.componentOverrides[""] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }`. **Valid renderer components** (examples): `es_property_editors/outputText`, `es_property_editors/outputNumber`, `es_property_editors/outputImage`. Avoid input-style components in the renderer. - - **Layout pattern for renderer**: - - `renderer.layout.definition = "lightning/verticalLayout"` - - `renderer.layout.children[*].definition = "lightning/propertyLayout"` with `attributes.property = ""` - - **CRITICAL**: Same as editor layouts, `lightning/propertyLayout` only accepts the `property` attribute. Do NOT add `label`, `title`, or any other attributes. - - **Collection renderer** (for root-level `lightning__listType` properties): Use `collection.renderer.componentOverrides["$"] = { "definition": "c/" }` or `es_property_editors/genericListTypeRenderer` to render the list. + - **Supported shape:** Top-level `renderer` object with `renderer.componentOverrides` and `renderer.layout`. + - Top-level `renderer` object. + - Use `renderer.componentOverrides` for component overrides. + - Use `renderer.layout` for layout. + - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead. + - **Root override pattern** (most common for fully custom rendering UI): + - `renderer.componentOverrides["$"] = { "definition": "c/", "attributes": { ... } }` + - Use `{!$attrs.}` in attribute mappings when binding schema data to custom renderer component attributes. + - **CRITICAL**: Attribute mappings like `{!$attrs.propertyName}` must reference properties that **actually exist** in your type schema. Referencing non-existent properties will fail validation. + - **Type matching**: Attribute values must match the expected type for the component. For example, if a component expects a string attribute, passing an integer will fail validation. + - **Widget renderer pattern** (for widget rendition): + - **When to use:** Use this when users request "mosaic", "widget", "fragment", or "cross-platform rendering" for their CLT. + - **Structure:** `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }` + - **REQUIRED workflow:** + - **STOP**: Do NOT attempt to create the widget renderer yourself. + - **MANDATORY FIRST STEP**: You MUST fetch the reference file `references/widget-rendition.md` located in this skill's directory before proceeding. + - Follow the complete workflow documented in `widget-rendition.md` using the generated CLT schema as the grounding schema. + - The `widget-rendition.md` reference contains the full widget generation workflow: discovering UEM blocks via discoverUiComponents, calling getUiComponentSchemas, building the UEM tree, and writing renderer.json. + - **Do not** attempt to generate widget rendition without first fetching the `widget-rendition.md` reference file. + - **Property-level override pattern**: + - `renderer.componentOverrides[""] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }`. **Valid renderer components** (examples): `es_property_editors/outputText`, `es_property_editors/outputNumber`, `es_property_editors/outputImage`. Avoid input-style components in the renderer. + - **Layout pattern for renderer**: + - `renderer.layout.definition = "lightning/verticalLayout"` + - `renderer.layout.children[*].definition = "lightning/propertyLayout"` with `attributes.property = ""` + - **CRITICAL**: Same as editor layouts, `lightning/propertyLayout` only accepts the `property` attribute. Do NOT add `label`, `title`, or any other attributes. + - **Collection renderer** (for root-level `lightning__listType` properties): Use `collection.renderer.componentOverrides["$"] = { "definition": "c/" }` or `es_property_editors/genericListTypeRenderer` to render the list. 5. **Place files in the correct bundle structure** - - `lightningTypes//schema.json` - - (Optional) `lightningTypes//lightningDesktopGenAi/editor.json` - - (Optional) `lightningTypes//lightningDesktopGenAi/renderer.json` - - For Gen AI / Copilot the standard path is `lightningDesktopGenAi/`. Other targets (e.g. Experience Builder, Mobile Copilot, Enhanced Web Chat) use different subfolders when supported: `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/`. + - `lightningTypes//schema.json` + - (Optional) `lightningTypes//lightningDesktopGenAi/editor.json` + - (Optional) `lightningTypes//lightningDesktopGenAi/renderer.json` + - For Gen AI / Copilot the standard path is `lightningDesktopGenAi/`. Other targets (e.g. Experience Builder, Mobile Copilot, Enhanced Web Chat) use different subfolders when supported: `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/`. 6. **Configure custom LWC components (if using custom components)** - - **CRITICAL**: Custom LWC components referenced in editor/renderer configs MUST have the correct target configuration in their `-meta.xml` files: - - **For editor components** (`c/` used in `editor.json`): The LWC's `-meta.xml` file must include `lightning__AgentforceInput` - - **For renderer components** (`c/` used in `renderer.json`): The LWC's `-meta.xml` file must include `lightning__AgentforceOutput` - - Without the correct target, deployment will fail with: `Invalid target configuration. To use 'c/componentName' as a renderer/editor, your js-meta.xml file must include valid target 'lightning__AgentforceOutput/Input'.` - - Example `-meta.xml` for a renderer component: - ```xml - - - 60.0 - true - - lightning__AgentforceOutput - - - ``` + - **CRITICAL**: Custom LWC components referenced in editor/renderer configs MUST have the correct target configuration in their `-meta.xml` files: + - **For editor components** (`c/` used in `editor.json`): The LWC's `-meta.xml` file must include `lightning__AgentforceInput` + - **For renderer components** (`c/` used in `renderer.json`): The LWC's `-meta.xml` file must include `lightning__AgentforceOutput` + - Without the correct target, deployment will fail with: `Invalid target configuration. To use 'c/componentName' as a renderer/editor, your js-meta.xml file must include valid target 'lightning__AgentforceOutput/Input'.` + - Example `-meta.xml` for a renderer component: + ```xml + + + 60.0 + true + + lightning__AgentforceOutput + + + ``` 7. **Deploy and validate** - - Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles. - - Validate incrementally: if deployment fails, remove disallowed keywords first (especially `examples`, `items`, nested `lightning:type`). + - Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles. + - Validate incrementally: if deployment fails, remove disallowed keywords first (especially `examples`, `items`, nested `lightning:type`). ## Common Deployment Errors | Error / Symptom | Likely Cause | Fix | @@ -203,9 +202,3 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr - [ ] Layout configurations use `lightning/propertyLayout` with ONLY the `property` attribute (no `label`, `title`, or other attributes) - [ ] All attribute mappings (`{!$attrs.propertyName}`) reference properties that exist in the type schema - [ ] Custom LWC components have correct targets in `-meta.xml`: `lightning__AgentforceInput` for editors, `lightning__AgentforceOutput` for renderers - ---- - -## Reference - -- **[mosaic-rendition.md](references/mosaic-rendition.md)** - Complete guidance on creating mosaic renditions for CLTs. diff --git a/skills/generating-custom-lightning-type/references/mosaic-rendition.md b/skills/generating-custom-lightning-type/references/widget-rendition.md similarity index 57% rename from skills/generating-custom-lightning-type/references/mosaic-rendition.md rename to skills/generating-custom-lightning-type/references/widget-rendition.md index b5152cf..454f12f 100644 --- a/skills/generating-custom-lightning-type/references/mosaic-rendition.md +++ b/skills/generating-custom-lightning-type/references/widget-rendition.md @@ -1,20 +1,16 @@ -# Guidance for creating Mosaic Rendition for a Custom Lighting Type - -## Specification - -# Fragment Generation Guide +# Widget Generation Guide ## 📋 Overview -Mosaics aka fragments aka widgets are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating mosaic renditions for CLTs. +Widgets are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating mosaic renditions for CLTs. ## 🎯 Purpose -Fragments render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc. +Widgets render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc. ## Schema Grounding -Fragment generation is **always schema-grounded** using a CLT's schema. The schema describes the data shape the fragment should render. Extract property names, types, required vs optional, and nesting from the schema; then follow the full **Workflow** below, using this extracted structure to guide every step. Do not add or remove properties relative to the schema. +Widget generation is **always schema-grounded** using a CLT's schema. The schema describes the data shape the widget should render. Extract property names, types, required vs optional, and nesting from the schema; then follow the full **Workflow** below, using this extracted structure to guide every step. Do not add or remove properties relative to the schema. ## ⚙️ Composition -A fragment is a UEM (Unified Experience Model) tree of blocks and regions. The fragment you return must follow the Typescript interfaces below: +A widget is a UEM (Unified Experience Model) tree of blocks and regions. The widget you return must follow the Typescript interfaces below: ```ts interface BlockType { @@ -30,7 +26,6 @@ interface RegionType { children: BlockType[] } ``` - --- ## 🔧 Available Metadata Actions @@ -39,9 +34,9 @@ interface RegionType { #### discoverUiComponents -**Purpose:** Discover the palette of available blocks that can be used in fragment composition. +**Purpose:** Discover the palette of available blocks that can be used in widget composition. -**Use for:** Finding available blocks before building your fragment structure. +**Use for:** Finding available blocks before building your widget structure. **Input Parameters:** - `actionName` (**required***): "discoverUiComponents" @@ -61,16 +56,17 @@ interface RegionType { **Purpose:** Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules. -**Use for:** You know which components you want but need to understand their attributes before adding them to your fragment. +**Use for:** You know which components you want but need to understand their properties before adding them to your widget. **Input Parameters:** - `actionName` (**required***): "getUiComponentSchemas" - `metadataType` (**required**): "FRAGMENT" - `parameters` (**required**): JSON object with the below fields - - `pageType` (**required**): "FRAGMENT" - - `componentDefinitions` (**required**): List of fully qualified names (e.g., ["namespace/definition"]) - - `pageContext` (optional): JSON object - not required for FRAGMENT type - - `includeKnowledge` (optional): Boolean, defaults to true - includes additional component-specific guidance + - `pageType` (**required**): "FRAGMENT" + - `componentDefinitions` (**required**): List of fully qualified names (e.g., ["namespace/definition"]) + - **CRITICAL**: NEVER include "tile/mosaic" in this list. "tile/mosaic" is a container component used in renderer.json structure and **should not** be passed to getUiComponentSchemas + - `pageContext` (optional): JSON object - not required for FRAGMENT type + - `includeKnowledge` (optional): Boolean, defaults to true - includes additional component-specific guidance **Returns:** - `componentSchemas`: List of results (supports partial failures) @@ -84,10 +80,10 @@ interface RegionType { ## Attribute binding using placeholder syntax -- **Where to use:** When block attributes must display or pass through runtime data from the grounding schema, use the **Placeholder Syntax** below so that the runtime binds values into the fragment. Check each block's schema (from `getUiComponentSchemas`) for the correct attribute name (e.g. `value`, `text`, `label`). -- **Placeholder Syntax:** Use `{!$attrs.}` as the placeholder for each attribute that should receive data. +- **Where to use:** When block properties must display or pass runtime data from the grounding schema, use the **Placeholder Syntax** below so that the runtime binds values into the widget. Check each block's schema (from `getUiComponentSchemas`) for the correct property name (e.g. `value`, `text`, `label`). +- **Placeholder Syntax:** Use `{!$attrs.}` as the placeholder for each block property that should receive data. `` **must** match the property name from the grounding schema so that the runtime can resolve its value. - Example: for a schema property `title`, set the block attribute to `{!$attrs.title}`. + Example: for a schema property `title`, set the block property to `{!$attrs.title}`. - **List / iterative data:** Only the children (list items) hold bound values; the parent list block does not. For each item inside a list (e.g. `tile/listItem`), use `{!$attrs..item}` so the runtime binds the current item. `` MUST match the schema property name of the list. Example: for `icons`, use `"{!$attrs.icons.item}"` on the list item. --- @@ -95,34 +91,34 @@ interface RegionType { ## 💡Workflow 1. **Schema Parsing** -- Parse the schema and extract: property names, types, required vs optional, and nested structure. Use this as the **fragment spec**. +- Parse the schema and extract: property names, types, required vs optional, and nested structure. Use this as the **widget spec**. 2. **Discover Available Blocks** (**REQUIRED** - do NOT skip) - Use **discoverUiComponents metadata action** above to explore what blocks are available. -- Use property types from the **fragment spec** to inform `searchQuery` (e.g. text → "text", number → "number"). +- Use property types from the **widget spec** to inform `searchQuery` (e.g. text → "text", number → "number"). 3. **Select Components** -- Choose blocks that can represent each property in the **fragment spec** from the results of step 2. +- Choose blocks that can represent each property in the **widget spec** from the results of step 2. 4. **Get Component Schemas** (**REQUIRED** - do NOT skip) -- Use **getUiComponentSchemas metadata action** above with the selected component definitions and review attribute metadata. +- Use **getUiComponentSchemas metadata action** with the selected block definitions from step 3 and review block properties' metadata. -5. **Build Fragment** -- Construct the UEM tree. Map each property in the **fragment spec** to block attributes and preserve order of the **fragment spec**. -- For attributes that must show or pass runtime data, use the placeholder syntax (see **Attribute binding (placeholders)** above). -- Use the attribute names from the schemas retrieved in step 4. +5. **Build Widget** +- Construct the UEM tree. Map each property in the **widget spec** to block properties and preserve order of the **widget spec**. +- For block properties that must show or pass runtime data, use the placeholder syntax (see **Attribute binding using placeholder syntax** above). +- Use block properties from the schemas retrieved in step 4. 6. **Write output to CLT Bundle** - Always write to `lightningTypes//lightningDesktopGenAi/renderer.json` (or the correct target subfolder for the product surface, e.g. `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/` when applicable). Check **required root override pattern** below - - `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ ... ] — array of UEM nodes produced by the fragment workflow (e.g. "tile/card", per getUiComponentSchemas) }` + `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ ... ] — array of UEM nodes - contains the widget UEM generated using the **Workflow** steps 1-5 above }` --- ## ⚠️ Important Notes -- **fragment spec** includes both required and optional attributes - review carefully to ensure valid configuration. +- **widget spec** includes both required and optional attributes - review carefully to ensure valid configuration. - When using **`execute_metadata_action`** tool, always supply **`parameters`** with the required fields above; missing `parameters` or required keys causes hard failures, not partial results. - Block definitions always follow the `{namespace}/{blockName}` convention. - Use the same definition format returned by `discoverUiComponents` when calling `getUiComponentSchemas` -- Placeholder syntax for non-list properties is `{!$attrs.}` and for list properties is `{!$attrs..item}`. +- Placeholder syntax for non-list properties is `{!$attrs.}` and for list properties is `{!$attrs..item}`. \ No newline at end of file