kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-07-30 11:19:27 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

changes with clt ref to mosaic rendition

Browse Source
This commit is contained in:
sowmya.sriram 2026-04-10 13:18:27 +05:30
parent dbd471aa45
commit 0e22a65d0b
No known key found for this signature in database
GPG Key ID: 50B1C900A9E2B573
3 changed files with 150 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
skills/generating-custom-lightning-type/SKILL.md
View File

@ -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, 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."
---
## When to Use This Skill
@ -10,6 +10,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
- Troubleshoot deployment errors related to Custom Lightning Types
## Specification
@ -23,6 +24,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.
- **Choose mosaic rendition** only when mosaic/fragment/widget rendition is requested. Refer **Mosaic override pattern** below for guidance.
## Critical Rules (Read First)
- **Root object schemas MUST include**:
@ -98,6 +100,7 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
- 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.
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.
@ -119,7 +122,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.
@ -130,6 +133,17 @@ 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.
- **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["<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**:
@ -189,3 +203,9 @@ 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.

128
skills/generating-custom-lightning-type/references/mosaic-rendition.md Normal file
View File

@ -0,0 +1,128 @@
# Guidance for creating Mosaic Rendition for a Custom Lighting Type
## Specification
# Fragment 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.
## 🎯 Purpose
Fragments 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.
## ⚙️ Composition
A fragment is a UEM (Unified Experience Model) tree of blocks and regions. The fragment 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 fragment composition.
**Use for:** Finding available blocks before building your fragment 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 attributes before adding them to your fragment.
**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
**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 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.<attrName>}` as the placeholder for each attribute 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 attribute 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 **fragment 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").
3. **Select Components**
- Choose blocks that can represent each property in the **fragment 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.
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.
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 produced by the fragment workflow (e.g. "tile/card", per getUiComponentSchemas) }`
---
## ⚠️ Important Notes
- **fragment 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}`.

117
skills/generating-fragment/SKILL.md
View File

@ -1,117 +0,0 @@
---
name: generating-fragment
description: "Use this skill when users need to create or edit Salesforce Fragments (reusable UI pieces). Trigger when users mention fragments, UEM blocks, reusable UI templates, structured rendering across Slack/Mobile/LEX, or block-based layouts. Also use when users want to create unified experience components. Always use this skill for any fragment work."
---
## When to Use This Skill
Use this skill when you need to:
- Create reusable UI fragments for Salesforce experiences
- Generate Fragment metadata following UEM structure
- Build fragments for Slack, Mobile, LEX, and other Salesforce experiences
- Troubleshoot deployment errors related to Fragments
## Specification
# Fragment Generation Guide
## 📋 Overview
Fragments 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 and editing fragments.
## 🎯 Purpose
Fragments render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc
## ⚙️ Composition
A fragment is a UEM (Unified Experience Model) tree of blocks and regions. The fragment 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
**When:** You want to see what block components are available for fragments.
**Purpose:** Discover the palette of available blocks that can be used in fragment composition.
**Input Parameters:**
- `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
**Use for:** Finding available blocks before building your fragment structure.
#### getUiComponentSchemas
**When:** You know which components you want but need to understand their properties and attributes.
**Purpose:** Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules.
**Input Parameters:**
- `pageType` (required): "FRAGMENT"
- `pageContext` (optional): JSON object - not required for FRAGMENT type
- `componentDefinitions` (required): List of fully qualified names (e.g., ["namespace/definition"])
- `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)
**Use for:** Understanding how to configure component attributes before adding blocks to your fragment.
**Key Feature:** Supports partial failures - if some components can't be found, you still get schemas for the successful ones.
---
## 💡 Typical Workflow
1. **Discover Available Blocks**
- Use `discoverUiComponents` to explore what blocks are available
- Optional: Use `searchQuery` to filter by keywords (e.g., "text", "button", "image")
2. **Select Components**
- Choose blocks that fit your fragment requirements
- Note their fully qualified definitions (e.g., "namespace/definition")
3. **Get Component Schemas**
- Use `getUiComponentSchemas` with the selected component definitions
- Review the JSON schemas to understand required and optional attributes
4. **Build Fragment**
- Construct your fragment using the UEM tree structure
- Configure block attributes according to the schemas
- Use the TypeScript interfaces defined above
---
## ⚠️ Important Notes
- Block definitions always follow the `{namespace}/{blockName}` convention
- Use the same definition format returned by `discoverUiComponents` when calling `getUiComponentSchemas`
- The FRAGMENT page type doesn't require additional `pageContext` parameters
- Schemas include both required and optional attributes - review carefully to ensure valid configuration