@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental 1.112.4 → 1.112.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/.a4drules/webapp-data.md +5 -5
  2. package/dist/.a4drules/webapp-ui.md +2 -2
  3. package/dist/AGENT.md +6 -10
  4. package/dist/CHANGELOG.md +16 -0
  5. package/dist/force-app/main/default/webapplications/feature-react-agentforce-conversation-client/.forceignore +15 -0
  6. package/dist/force-app/main/default/webapplications/feature-react-agentforce-conversation-client/package.json +3 -3
  7. package/dist/package-lock.json +2 -2
  8. package/dist/package.json +1 -1
  9. package/dist/{.a4drules/skills/using-salesforce-data → scripts}/graphql-search.sh +4 -4
  10. package/package.json +3 -4
  11. package/dist/.a4drules/skills/building-data-visualization/SKILL.md +0 -72
  12. package/dist/.a4drules/skills/building-data-visualization/implementation/bar-line-chart.md +0 -316
  13. package/dist/.a4drules/skills/building-data-visualization/implementation/dashboard-layout.md +0 -189
  14. package/dist/.a4drules/skills/building-data-visualization/implementation/donut-chart.md +0 -181
  15. package/dist/.a4drules/skills/building-data-visualization/implementation/stat-card.md +0 -150
  16. package/dist/.a4drules/skills/building-react-components/SKILL.md +0 -96
  17. package/dist/.a4drules/skills/building-react-components/implementation/component.md +0 -78
  18. package/dist/.a4drules/skills/building-react-components/implementation/header-footer.md +0 -132
  19. package/dist/.a4drules/skills/building-react-components/implementation/page.md +0 -93
  20. package/dist/.a4drules/skills/configuring-csp-trusted-sites/SKILL.md +0 -90
  21. package/dist/.a4drules/skills/configuring-csp-trusted-sites/implementation/metadata-format.md +0 -281
  22. package/dist/.a4drules/skills/configuring-webapp-metadata/SKILL.md +0 -158
  23. package/dist/.a4drules/skills/creating-webapp/SKILL.md +0 -140
  24. package/dist/.a4drules/skills/deploying-to-salesforce/SKILL.md +0 -226
  25. package/dist/.a4drules/skills/implementing-file-upload/SKILL.md +0 -396
  26. package/dist/.a4drules/skills/installing-webapp-features/SKILL.md +0 -210
  27. package/dist/.a4drules/skills/managing-agentforce-conversation-client/SKILL.md +0 -186
  28. package/dist/.a4drules/skills/managing-agentforce-conversation-client/references/constraints.md +0 -134
  29. package/dist/.a4drules/skills/managing-agentforce-conversation-client/references/examples.md +0 -132
  30. package/dist/.a4drules/skills/managing-agentforce-conversation-client/references/style-tokens.md +0 -101
  31. package/dist/.a4drules/skills/managing-agentforce-conversation-client/references/troubleshooting.md +0 -57
  32. package/dist/.a4drules/skills/using-salesforce-data/SKILL.md +0 -363
  33. package/skills/managing-agentforce-conversation-client/SKILL.md +0 -186
  34. package/skills/managing-agentforce-conversation-client/references/constraints.md +0 -134
  35. package/skills/managing-agentforce-conversation-client/references/examples.md +0 -132
  36. package/skills/managing-agentforce-conversation-client/references/style-tokens.md +0 -101
  37. package/skills/managing-agentforce-conversation-client/references/troubleshooting.md +0 -57
@@ -1,363 +0,0 @@
1
- ---
2
- name: using-salesforce-data
3
- description: Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks.
4
- ---
5
-
6
- # Salesforce Data Access
7
-
8
- ## When to Use
9
-
10
- Use this skill when the user wants to:
11
-
12
- - **Fetch or display Salesforce data** — Query records (Account, Contact, Opportunity, custom objects) to show in a component
13
- - **Create, update, or delete records** — Perform mutations on Salesforce data
14
- - **Add data fetching to a component** — Wire up a React component to Salesforce data
15
- - **Call REST APIs** — Use Connect REST, Apex REST, or UI API endpoints
16
- - **Explore the org schema** — Discover available objects, fields, or relationships
17
-
18
- ## Data SDK Requirement
19
-
20
- > **All Salesforce data access MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK handles authentication, CSRF, and base URL resolution. Never use `fetch()` or `axios` directly.
21
-
22
- ```typescript
23
- import { createDataSDK, gql } from "@salesforce/sdk-data";
24
-
25
- const sdk = await createDataSDK();
26
-
27
- // GraphQL for record queries/mutations (PREFERRED)
28
- const response = await sdk.graphql?.<ResponseType>(query, variables);
29
-
30
- // REST for Connect REST, Apex REST, UI API (when GraphQL insufficient)
31
- const res = await sdk.fetch?.("/services/apexrest/my-resource");
32
- ```
33
-
34
- **Always use optional chaining** (`sdk.graphql?.()`, `sdk.fetch?.()`) — these methods may be undefined in some surfaces.
35
-
36
- ## Supported APIs
37
-
38
- **Only the following APIs are permitted.** Any endpoint not listed here must not be used.
39
-
40
- | API | Method | Endpoints / Use Case |
41
- |-----|--------|----------------------|
42
- | GraphQL | `sdk.graphql` | All record queries and mutations via `uiapi { }` namespace |
43
- | UI API REST | `sdk.fetch` | `/services/data/v{ver}/ui-api/records/{id}` — record metadata when GraphQL is insufficient |
44
- | Apex REST | `sdk.fetch` | `/services/apexrest/{resource}` — custom server-side logic, aggregates, multi-step transactions |
45
- | Connect REST | `sdk.fetch` | `/services/data/v{ver}/connect/file/upload/config` — file upload config |
46
- | Einstein LLM | `sdk.fetch` | `/services/data/v{ver}/einstein/llm/prompt/generations` — AI text generation |
47
-
48
- **Not supported:**
49
-
50
- - **Enterprise REST query endpoint** (`/services/data/v*/query` with SOQL) — blocked at the proxy level. Use GraphQL for record reads; use Apex REST if server-side SOQL aggregates are required.
51
- - **Aura-enabled Apex** (`@AuraEnabled`) — an LWC/Aura pattern with no invocation path from React webapps.
52
- - **Chatter API** (`/chatter/users/me`) — use `uiapi { currentUser { ... } }` in a GraphQL query instead.
53
- - **Any other Salesforce REST endpoint** not listed in the supported table above.
54
-
55
- ## Decision: GraphQL vs REST
56
-
57
- | Need | Method | Example |
58
- |------|--------|---------|
59
- | Query/mutate records | `sdk.graphql` | Account, Contact, custom objects |
60
- | Current user info | `sdk.graphql` | `uiapi { currentUser { Id Name { value } } }` |
61
- | UI API record metadata | `sdk.fetch` | `/ui-api/records/{id}` |
62
- | Connect REST | `sdk.fetch` | `/connect/file/upload/config` |
63
- | Apex REST | `sdk.fetch` | `/services/apexrest/auth/login` |
64
- | Einstein LLM | `sdk.fetch` | `/einstein/llm/prompt/generations` |
65
-
66
- **GraphQL is preferred** for record operations. Use REST only when GraphQL doesn't cover the use case.
67
-
68
- ---
69
-
70
- ## GraphQL Workflow
71
-
72
- ### Step 1: Acquire Schema
73
-
74
- The `schema.graphql` file (265K+ lines) is the source of truth. **Never open or parse it directly.**
75
-
76
- 1. Check if `schema.graphql` exists at the SFDX project root
77
- 2. If missing, run from the **webapp dir**: `npm run graphql:schema`
78
- 3. Custom objects appear only after metadata is deployed
79
-
80
- ### Step 2: Look Up Entity Schema
81
-
82
- Map user intent to PascalCase names ("accounts" → `Account`), then **run the search script from the project root**:
83
-
84
- ```bash
85
- # From project root — look up all relevant schema info for one or more entities
86
- bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
87
-
88
- # Multiple entities at once
89
- bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
90
- ```
91
-
92
- The script outputs five sections per entity:
93
- 1. **Type definition** — all queryable fields and relationships
94
- 2. **Filter options** — available fields for `where:` conditions
95
- 3. **Sort options** — available fields for `orderBy:`
96
- 4. **Create input** — fields accepted by create mutations
97
- 5. **Update input** — fields accepted by update mutations
98
-
99
- Use this output to determine exact field names before writing any query or mutation. **Maximum 2 script runs.** If the entity still can't be found, ask the user — the object may not be deployed.
100
-
101
- ### Step 3: Generate Query
102
-
103
- Use the templates below. Every field name **must** be verified from the script output in Step 2.
104
-
105
- #### Read Query Template
106
-
107
- ```graphql
108
- query GetAccounts {
109
- uiapi {
110
- query {
111
- Account(where: { Industry: { eq: "Technology" } }, first: 10) {
112
- edges {
113
- node {
114
- Id
115
- Name @optional { value }
116
- Industry @optional { value }
117
- # Parent relationship
118
- Owner @optional { Name { value } }
119
- # Child relationship
120
- Contacts @optional {
121
- edges { node { Name @optional { value } } }
122
- }
123
- }
124
- }
125
- }
126
- }
127
- }
128
- }
129
- ```
130
-
131
- **FLS Resilience**: Apply `@optional` to all record fields. The server omits inaccessible fields instead of failing. Consuming code must use optional chaining:
132
-
133
- ```typescript
134
- const name = node.Name?.value ?? "";
135
- ```
136
-
137
- #### Mutation Template
138
-
139
- ```graphql
140
- mutation CreateAccount($input: AccountCreateInput!) {
141
- uiapi {
142
- AccountCreate(input: $input) {
143
- Record { Id Name { value } }
144
- }
145
- }
146
- }
147
- ```
148
-
149
- **Mutation constraints:**
150
- - Create: Include required fields, only `createable` fields, no child relationships
151
- - Update: Include `Id`, only `updateable` fields
152
- - Delete: Include `Id` only
153
-
154
- #### Object Metadata & Picklist Values
155
-
156
- Use `uiapi { objectInfos(...) }` to fetch field metadata or picklist values. Pass **either** `apiNames` or `objectInfoInputs` — never both in the same query.
157
-
158
- **Object metadata** (field labels, data types, CRUD flags):
159
-
160
- ```typescript
161
- const GET_OBJECT_INFO = gql`
162
- query GetObjectInfo($apiNames: [String!]!) {
163
- uiapi {
164
- objectInfos(apiNames: $apiNames) {
165
- ApiName
166
- label
167
- labelPlural
168
- fields {
169
- ApiName
170
- label
171
- dataType
172
- updateable
173
- createable
174
- }
175
- }
176
- }
177
- }
178
- `;
179
-
180
- const sdk = await createDataSDK();
181
- const response = await sdk.graphql?.(GET_OBJECT_INFO, { apiNames: ["Account"] });
182
- const objectInfos = response?.data?.uiapi?.objectInfos ?? [];
183
- ```
184
-
185
- **Picklist values** (use `objectInfoInputs` + `... on PicklistField` inline fragment):
186
-
187
- ```typescript
188
- const GET_PICKLIST_VALUES = gql`
189
- query GetPicklistValues($objectInfoInputs: [ObjectInfoInput!]!) {
190
- uiapi {
191
- objectInfos(objectInfoInputs: $objectInfoInputs) {
192
- ApiName
193
- fields {
194
- ApiName
195
- ... on PicklistField {
196
- picklistValuesByRecordTypeIDs {
197
- recordTypeID
198
- picklistValues {
199
- label
200
- value
201
- }
202
- }
203
- }
204
- }
205
- }
206
- }
207
- }
208
- `;
209
-
210
- const response = await sdk.graphql?.(GET_PICKLIST_VALUES, {
211
- objectInfoInputs: [{ objectApiName: "Account" }],
212
- });
213
- const fields = response?.data?.uiapi?.objectInfos?.[0]?.fields ?? [];
214
- ```
215
-
216
- ### Step 4: Validate & Test
217
-
218
- 1. **Lint**: `npx eslint <file>` from webapp dir
219
- 2. **Test**: Ask user before testing. For mutations, request input values — never fabricate data.
220
-
221
- **If ESLint reports a GraphQL error** (e.g. `Cannot query field`, `Unknown type`, `Unknown argument`), the field or type name is wrong. Re-run the schema search script to find the correct name — do not guess:
222
-
223
- ```bash
224
- # From project root — re-check the entity that caused the error
225
- bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
226
- ```
227
-
228
- Then fix the query using the exact names from the script output.
229
-
230
- ---
231
-
232
- ## Webapp Integration (React)
233
-
234
- ```typescript
235
- import { createDataSDK, gql } from "@salesforce/sdk-data";
236
-
237
- const GET_ACCOUNTS = gql`
238
- query GetAccounts {
239
- uiapi {
240
- query {
241
- Account(first: 10) {
242
- edges {
243
- node {
244
- Id
245
- Name @optional { value }
246
- Industry @optional { value }
247
- }
248
- }
249
- }
250
- }
251
- }
252
- }
253
- `;
254
-
255
- const sdk = await createDataSDK();
256
- const response = await sdk.graphql?.(GET_ACCOUNTS);
257
-
258
- if (response?.errors?.length) {
259
- throw new Error(response.errors.map(e => e.message).join("; "));
260
- }
261
-
262
- const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
263
- ```
264
-
265
- ---
266
-
267
- ## REST API Patterns
268
-
269
- Use `sdk.fetch` when GraphQL is insufficient. See the [Supported APIs](#supported-apis) table for the full allowlist.
270
-
271
- ```typescript
272
- declare const __SF_API_VERSION__: string;
273
- const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
274
-
275
- // Connect — file upload config
276
- const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`);
277
-
278
- // Apex REST (no version in path)
279
- const res = await sdk.fetch?.("/services/apexrest/auth/login", {
280
- method: "POST",
281
- body: JSON.stringify({ email, password }),
282
- headers: { "Content-Type": "application/json" },
283
- });
284
-
285
- // UI API — record with metadata (prefer GraphQL for simple reads)
286
- const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/ui-api/records/${recordId}`);
287
-
288
- // Einstein LLM
289
- const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/prompt/generations`, {
290
- method: "POST",
291
- body: JSON.stringify({ promptTextorId: prompt }),
292
- });
293
- ```
294
-
295
- **Current user**: Do not use Chatter (`/chatter/users/me`). Use GraphQL instead:
296
-
297
- ```typescript
298
- const GET_CURRENT_USER = gql`
299
- query CurrentUser {
300
- uiapi { currentUser { Id Name { value } } }
301
- }
302
- `;
303
- const response = await sdk.graphql?.(GET_CURRENT_USER);
304
- ```
305
-
306
- ---
307
-
308
- ## Directory Structure
309
-
310
- ```
311
- <project-root>/ ← SFDX project root
312
- ├── schema.graphql ← grep target (lives here)
313
- ├── sfdx-project.json
314
- └── force-app/main/default/webapplications/<app-name>/ ← webapp dir
315
- ├── package.json ← npm scripts
316
- └── src/
317
- ```
318
-
319
- | Command | Run From | Why |
320
- |---------|----------|-----|
321
- | `npm run graphql:schema` | webapp dir | Script in webapp's package.json |
322
- | `npx eslint <file>` | webapp dir | Reads eslint.config.js |
323
- | `bash .a4drules/skills/using-salesforce-data/graphql-search.sh <Entity>` | project root | Schema lookup |
324
- | `sf api request rest` | project root | Needs sfdx-project.json |
325
-
326
- ---
327
-
328
- ## Quick Reference
329
-
330
- ### Schema Lookup (from project root)
331
-
332
- Run the search script to get all relevant schema info in one step:
333
-
334
- ```bash
335
- bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
336
- ```
337
-
338
- | Script Output Section | Used For |
339
- |-----------------------|----------|
340
- | Type definition | Field names, parent/child relationships |
341
- | Filter options | `where:` conditions |
342
- | Sort options | `orderBy:` |
343
- | CreateRepresentation | Create mutation field list |
344
- | UpdateRepresentation | Update mutation field list |
345
-
346
- ### Error Categories
347
-
348
- | Error Contains | Resolution |
349
- |----------------|------------|
350
- | `Cannot query field` | Field name is wrong — run `graphql-search.sh <Entity>` and use the exact name from the Type definition section |
351
- | `Unknown type` | Type name is wrong — run `graphql-search.sh <Entity>` to confirm the correct PascalCase entity name |
352
- | `Unknown argument` | Argument name is wrong — run `graphql-search.sh <Entity>` and check Filter or OrderBy sections |
353
- | `invalid syntax` | Fix syntax per error message |
354
- | `validation error` | Field name is wrong — run `graphql-search.sh <Entity>` to verify |
355
- | `VariableTypeMismatch` | Correct argument type from schema |
356
- | `invalid cross reference id` | Entity deleted — ask for valid Id |
357
-
358
- ### Checklist
359
-
360
- - [ ] All field names verified via search script (Step 2)
361
- - [ ] `@optional` applied to record fields (reads)
362
- - [ ] Optional chaining in consuming code
363
- - [ ] Lint passes: `npx eslint <file>`
@@ -1,186 +0,0 @@
1
- ---
2
- name: managing-agentforce-conversation-client
3
- description: Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says "add chat widget", "embed agentforce", "add agent", "add chatbot", "integrate conversational AI", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat.
4
- metadata:
5
- author: ACC Components
6
- version: 1.0.0
7
- package: "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental"
8
- sdk-package: "@salesforce/agentforce-conversation-client"
9
- last-updated: 2025-03-18
10
- ---
11
-
12
- # Managing Agentforce Conversation Client
13
-
14
- ## Instructions
15
-
16
- ### Step 1: Check if component already exists
17
-
18
- Search for existing usage across all app files (not implementation files):
19
-
20
- ```bash
21
- grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules
22
- ```
23
-
24
- **Important:** Look for React files that import and USE the component (for example, shared shells, route components, or feature pages). Do NOT open files named `AgentforceConversationClient.tsx` or `AgentforceConversationClient.jsx` - those are the component implementation.
25
-
26
- **If found:** Read the file and check the current `agentId` value.
27
-
28
- **Agent ID validation rule (deterministic):**
29
-
30
- - Valid only if it matches: `^0Xx[a-zA-Z0-9]{15}$`
31
- - Meaning: starts with `0Xx` and total length is 18 characters
32
-
33
- **Decision:**
34
-
35
- - If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user wants to update other props → Go to Step 4 (update props)
36
- - If `agentId` is missing, empty, or does NOT match `^0Xx[a-zA-Z0-9]{15}$` → Continue to Step 2 (need real ID)
37
- - If not found → Continue to Step 2 (add new)
38
-
39
- ### Step 2: Get agent ID
40
-
41
- If component doesn't exist or has an invalid placeholder value, ask user for their Salesforce agent ID.
42
-
43
- Treat these as placeholder/invalid values:
44
-
45
- - `"0Xx..."`
46
- - `"Placeholder"`
47
- - `"YOUR_AGENT_ID"`
48
- - `"<USER_AGENT_ID_18_CHAR_0Xx...>"`
49
- - Any value that does not match `^0Xx[a-zA-Z0-9]{15}$`
50
-
51
- Skip this step if:
52
-
53
- - Component exists with a real agent ID
54
- - User only wants to update styling or dimensions
55
-
56
- ### Step 3: Canonical import strategy
57
-
58
- Use this import path by default in app code:
59
-
60
- ```tsx
61
- import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
62
- ```
63
-
64
- If the package is not installed, install it:
65
-
66
- ```bash
67
- npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
68
- ```
69
-
70
- Only use a local relative import (for example, `./components/AgentforceConversationClient`) when the user explicitly asks to use a patched/local component in that app.
71
-
72
- Do not infer import path from file discovery alone. Prefer one consistent package import across the codebase.
73
-
74
- ### Step 4: Add or update component
75
-
76
- **For new installations:**
77
-
78
- Add to the target React component file using the canonical package import:
79
-
80
- ```tsx
81
- import { Outlet } from "react-router";
82
- import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
83
-
84
- export default function AgentChatHost() {
85
- return (
86
- <>
87
- <Outlet />
88
- <AgentforceConversationClient agentId="0Xx..." />
89
- </>
90
- );
91
- }
92
- ```
93
-
94
- **Fallback note:** Use a local relative import only when the user explicitly requests patched/local component usage in that app.
95
-
96
- **For updates:**
97
-
98
- Read the file where component is used and modify only the props that need to change. Preserve all other props. Never delete and recreate.
99
-
100
- **Replacing placeholder values:**
101
-
102
- If the component has a placeholder agentId (e.g., `agentId="Placeholder"` or `agentId="0Xx..."`), replace it with the real agent ID:
103
-
104
- ```tsx
105
- // Before (template with placeholder)
106
- <AgentforceConversationClient agentId="Placeholder" />
107
-
108
- // After (with real agent ID)
109
- <AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />
110
- ```
111
-
112
- ### Step 5: Configure props
113
-
114
- **Available props (use directly on component):**
115
-
116
- - `agentId` (string, required) - Salesforce agent ID
117
- - `inline` (boolean) - `true` for inline mode, omit for floating
118
- - `width` (number | string) - e.g., `420` or `"100%"`
119
- - `height` (number | string) - e.g., `600` or `"80vh"`
120
- - `headerEnabled` (boolean) - Show/hide header
121
- - `styleTokens` (object) - For all styling (colors, fonts, spacing)
122
- - `salesforceOrigin` (string) - Auto-resolved
123
- - `frontdoorUrl` (string) - Auto-resolved
124
-
125
- **Examples:**
126
-
127
- Floating mode (default):
128
-
129
- ```tsx
130
- <AgentforceConversationClient agentId="0Xx..." />
131
- ```
132
-
133
- Inline mode with dimensions:
134
-
135
- ```tsx
136
- <AgentforceConversationClient agentId="0Xx..." inline width="420px" height="600px" />
137
- ```
138
-
139
- Styling with styleTokens:
140
-
141
- ```tsx
142
- <AgentforceConversationClient
143
- agentId="0Xx..."
144
- styleTokens={{
145
- headerBlockBackground: "#0176d3",
146
- headerBlockTextColor: "#ffffff",
147
- messageBlockInboundBackgroundColor: "#4CAF50",
148
- }}
149
- />
150
- ```
151
-
152
- **For complex patterns,** consult `references/examples.md` for:
153
-
154
- - Sidebar containers and responsive sizing
155
- - Dark theme and advanced theming combinations
156
- - Inline without header, calculated dimensions
157
- - Complete host component examples
158
-
159
- **For styling:** For ANY color, font, or spacing changes, use `styleTokens` prop only. See `references/style-tokens.md` for complete token list and examples.
160
-
161
- **Common mistakes to avoid:** Consult `references/constraints.md` for:
162
-
163
- - Invalid props (containerStyle, style, className)
164
- - Invalid styling approaches (CSS files, style tags)
165
- - What files NOT to edit (implementation files)
166
-
167
- ## Common Issues
168
-
169
- If component doesn't appear or authentication fails, see `references/troubleshooting.md` for:
170
-
171
- - Agent activation and deployment
172
- - Localhost trusted domains
173
- - Cookie restriction settings
174
-
175
- ## Prerequisites
176
-
177
- Before the component will work, the following Salesforce settings must be configured by the user:
178
-
179
- **Cookie settings:**
180
-
181
- - Setup → My Domain → Disable "Require first party use of Salesforce cookies"
182
-
183
- **Trusted domains (required only for local development):**
184
-
185
- - Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
186
- - Local development: `localhost:<PORT>` (e.g., `localhost:3000`)
@@ -1,134 +0,0 @@
1
- # Constraints and Anti-Patterns
2
-
3
- This document lists all invalid approaches and patterns to avoid when working with AgentforceConversationClient.
4
-
5
- ## Never Edit Implementation Files
6
-
7
- **CRITICAL: Only edit files where the component is USED, never the component implementation itself.**
8
-
9
- - ✅ **DO edit**: Any React files that import and use `<AgentforceConversationClient />` (for example, shared shells, route components, or feature pages)
10
- - ❌ **DO NOT edit**: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
11
- - `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/`
12
- - `packages/template/feature/feature-react-agentforce-conversation-client/src/`
13
- - `src/components/AgentforceConversationClient.tsx` (patched templates)
14
- - Any path containing `/components/AgentforceConversationClient.`
15
-
16
- **If you're reading a file named `AgentforceConversationClient.tsx`, you're in the wrong place. Stop and search for the USAGE instead.**
17
-
18
- ## Invalid Props
19
-
20
- AgentforceConversationClient uses a flat prop API and does NOT accept these props:
21
-
22
- - ❌ `containerStyle` - Use `width` and `height` props directly instead
23
- - ❌ `style` - Use `styleTokens` for theming
24
- - ❌ `className` - Not supported
25
- - ❌ Any standard React div props - This wraps an embedded iframe, not a div
26
-
27
- **Why:** The component is a wrapper around an embedded iframe using Lightning Out 2.0. Standard React styling props don't apply.
28
-
29
- ## Invalid Styling Approaches
30
-
31
- **CRITICAL: For ALL styling, theming, branding, or color changes - ONLY use `styleTokens` prop.**
32
-
33
- Never use these approaches:
34
-
35
- - ❌ Creating CSS files (e.g., `agent-styles.css`, `theme.css`)
36
- - ❌ Creating `<style>` tags or internal stylesheets
37
- - ❌ Using `style` attribute on the component
38
- - ❌ Using `className` prop
39
- - ❌ Inline styles
40
- - ❌ CSS modules
41
- - ❌ Styled-components or any CSS-in-JS libraries
42
-
43
- **Why:** The component controls its own internal styling through the `styleTokens` API. External CSS cannot reach into the embedded iframe.
44
-
45
- ## Invalid Implementation Approaches
46
-
47
- Never do these:
48
-
49
- - ❌ Create custom chat UIs from scratch
50
- - ❌ Use third-party chat libraries (socket.io, WebSocket libraries, etc.)
51
- - ❌ Call `embedAgentforceClient` directly from `@salesforce/agentforce-conversation-client`
52
- - ❌ Build custom WebSocket or REST API chat implementations
53
-
54
- **Why:** The AgentforceConversationClient component is the official wrapper that handles authentication, Lightning Out 2.0 initialization, and all communication with Salesforce agents. Custom implementations will not work.
55
-
56
- ## Invalid Update Patterns
57
-
58
- When updating an existing component:
59
-
60
- - ❌ Delete and recreate the component
61
- - ❌ Remove all props and start over
62
- - ❌ Copy the entire component to a new file
63
-
64
- **Why:** This loses configuration, introduces errors, and creates unnecessary diffs. Always update props in place.
65
-
66
- ## Examples
67
-
68
- ### ❌ Wrong - Using containerStyle
69
-
70
- ```tsx
71
- <AgentforceConversationClient agentId="0Xx..." containerStyle={{ width: 420, height: 600 }} />
72
- ```
73
-
74
- ### ✅ Correct - Using width/height directly
75
-
76
- ```tsx
77
- <AgentforceConversationClient agentId="0Xx..." width="420px" height="600px" />
78
- ```
79
-
80
- ### ❌ Wrong - Creating CSS file
81
-
82
- ```css
83
- /* agent-styles.css */
84
- .agentforce-chat {
85
- background: red;
86
- color: white;
87
- }
88
- ```
89
-
90
- ```tsx
91
- import "./agent-styles.css";
92
-
93
- <AgentforceConversationClient className="agentforce-chat" />;
94
- ```
95
-
96
- ### ✅ Correct - Using styleTokens
97
-
98
- ```tsx
99
- <AgentforceConversationClient
100
- agentId="0Xx..."
101
- styleTokens={{
102
- headerBlockBackground: "red",
103
- headerBlockTextColor: "white",
104
- }}
105
- />
106
- ```
107
-
108
- ### ❌ Wrong - Creating style tag
109
-
110
- ```tsx
111
- <>
112
- <style>{`.agent-chat { background: blue; }`}</style>
113
- <AgentforceConversationClient agentId="0Xx..." />
114
- </>
115
- ```
116
-
117
- ### ✅ Correct - Using styleTokens
118
-
119
- ```tsx
120
- <AgentforceConversationClient
121
- agentId="0Xx..."
122
- styleTokens={{
123
- headerBlockBackground: "blue",
124
- }}
125
- />
126
- ```
127
-
128
- ### ❌ Wrong - Editing implementation file
129
-
130
- Reading or editing: `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx`
131
-
132
- ### ✅ Correct - Editing usage file
133
-
134
- Reading and editing: usage files where the component is imported and used (for example, `src/app.tsx`, a route component, or a feature page)