mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 11:43:26 +08:00
feat: @W-22259678@ changes with clt ref to mosaic rendition guidance (#190)
* changes with clt ref to mosaic rendition * updated widget rendition guidance * removed new line characters from description. * added back version metadata
This commit is contained in:
sowmya-sriram
GitHub
parent
597ec0162d
commit
5d33d63d48
@ -1,6 +1,6 @@
|
||||
---
|
||||
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, 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."
|
||||
metadata:
|
||||
version: "1.0"
|
||||
---
|
||||
@ -12,6 +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 widget/mosaic/fragment rendition
|
||||
- Troubleshoot deployment errors related to Custom Lightning Types
|
||||
|
||||
## Specification
|
||||
@ -26,6 +27,7 @@ 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.
|
||||
- **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**:
|
||||
@ -127,7 +129,7 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
|
||||
- **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 is required)
|
||||
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.
|
||||
@ -138,6 +140,15 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
|
||||
- Use `{!$attrs.<name>}` 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["<propertyName>"] = { "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**:
|
||||
|
||||
@ -0,0 +1,124 @@
|
||||
# Widget Generation Guide
|
||||
|
||||
## 📋 Overview
|
||||
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
|
||||
Widgets render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc.
|
||||
|
||||
## Schema Grounding
|
||||
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 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 {
|
||||
type: 'block'
|
||||
definition: string // {namespace}/{blockName}
|
||||
attributes?: Record<string, any>
|
||||
children?: (BlockType | RegionType)[]
|
||||
}
|
||||
|
||||
interface RegionType {
|
||||
type: 'region'
|
||||
name: string
|
||||
children: BlockType[]
|
||||
}
|
||||
```
|
||||
---
|
||||
|
||||
## 🔧 Available Metadata Actions
|
||||
|
||||
### When to Use Each Action
|
||||
|
||||
#### discoverUiComponents
|
||||
|
||||
**Purpose:** Discover the palette of available blocks that can be used in widget composition.
|
||||
|
||||
**Use for:** Finding available blocks before building your widget structure.
|
||||
|
||||
**Input Parameters:**
|
||||
- `actionName` (**required***): "discoverUiComponents"
|
||||
- `metadataType` (**required**): "FRAGMENT"
|
||||
- `parameters` (**required**): JSON object with the below fields
|
||||
- `pageType` (**required**): "FRAGMENT"
|
||||
- `pageContext` (optional): JSON object - not required for FRAGMENT type
|
||||
- `searchQuery` (optional): String to filter components by name or description
|
||||
|
||||
**Returns:** List of components with:
|
||||
- `definition`: Fully qualified name (e.g., "namespace/definiton")
|
||||
- `description`: Component description
|
||||
- `label`: Human-readable label
|
||||
- `attributes`: Optional attribute metadata
|
||||
|
||||
#### getUiComponentSchemas
|
||||
|
||||
**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 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"])
|
||||
- **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)
|
||||
- **Success entries**: Contains JSON schema with property definitions, types, constraints
|
||||
- **Failure entries**: Contains error message explaining why schema couldn't be retrieved
|
||||
- `$defs`: Schema definitions and references (if schema transformation applied)
|
||||
|
||||
**Key Feature:** Supports partial failures - if some components can't be found, you still get schemas for the successful ones.
|
||||
|
||||
---
|
||||
|
||||
## Attribute binding using placeholder syntax
|
||||
|
||||
- **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.<attrName>}` as the placeholder for each block property that should receive data.
|
||||
`<attrName>` **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 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.<listAttrName>.item}` so the runtime binds the current item. `<listAttrName>` MUST match the schema property name of the list. Example: for `icons`, use `"{!$attrs.icons.item}"` on the list item.
|
||||
|
||||
---
|
||||
|
||||
## 💡Workflow
|
||||
|
||||
1. **Schema Parsing**
|
||||
- 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 **widget spec** to inform `searchQuery` (e.g. text → "text", number → "number").
|
||||
|
||||
3. **Select Components**
|
||||
- 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** with the selected block definitions from step 3 and review block properties' metadata.
|
||||
|
||||
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/<TypeName>/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 - contains the widget UEM generated using the **Workflow** steps 1-5 above }`
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
- **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.<attrName>}` and for list properties is `{!$attrs.<listAttrName>.item}`.
|
||||
Loading…
Reference in New Issue
Block a user