@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental 1.107.3 → 1.107.4

package/skills/managing-agentforce-conversation-client/references/examples.md

@@ -0,0 +1,132 @@
+# Additional Examples
+
+Essential examples for common patterns and combinations. All use flat props API.
+
+---
+
+## Layout Patterns
+
+### Sidebar Chat
+
+```tsx
+export default function DashboardWithChat() {
+  return (
+    <div style={{ display: "flex", height: "100vh" }}>
+      <main style={{ flex: 1 }}>{/* Main content */}</main>
+      <aside style={{ width: 400 }}>
+        <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="100%" />
+      </aside>
+    </div>
+  );
+}
+```
+
+### Full Page Chat
+
+```tsx
+export default function SupportPage() {
+  return (
+    <div>
+      <h1>Customer Support</h1>
+      <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="600px" />
+    </div>
+  );
+}
+```
+
+---
+
+## Size Variations
+
+### Responsive sizing
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." inline width="100%" height="80vh" />
+```
+
+### Calculated dimensions
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." inline width="500px" height="calc(100vh - 100px)" />
+```
+
+---
+
+## Theming Combinations
+
+### Brand theme with custom sizing
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  inline
+  width="500px"
+  height="700px"
+  styleTokens={{
+    headerBlockBackground: "#0176d3",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundBackgroundColor: "#0176d3",
+    messageBlockInboundTextColor: "#ffffff",
+    messageInputFooterSendButton: "#0176d3",
+  }}
+/>
+```
+
+### Dark theme
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "#1a1a1a",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundBackgroundColor: "#2d2d2d",
+    messageBlockInboundTextColor: "#ffffff",
+    messageBlockOutboundBackgroundColor: "#3a3a3a",
+    messageBlockOutboundTextColor: "#f0f0f0",
+  }}
+/>
+```
+
+### Inline without header
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  inline
+  width="100%"
+  height="600px"
+  headerEnabled={false}
+  styleTokens={{
+    messageBlockBorderRadius: "12px",
+  }}
+/>
+```
+
+---
+
+## Complete Host Component Example
+
+```tsx
+import { Outlet } from "react-router";
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+
+export default function AgentChatHost() {
+  return (
+    <>
+      <Outlet />
+      <AgentforceConversationClient
+        agentId="0Xx..."
+        styleTokens={{
+          headerBlockBackground: "#0176d3",
+          headerBlockTextColor: "#ffffff",
+        }}
+      />
+    </>
+  );
+}
+```
+
+---
+
+For complete style token reference, see `references/style-tokens.md` or `node_modules/@salesforce/agentforce-conversation-client/README.md`.

package/skills/managing-agentforce-conversation-client/references/style-tokens.md

@@ -0,0 +1,101 @@
+# Style Tokens Reference
+
+This document explains how to use `styleTokens` for theming and styling the AgentforceConversationClient.
+
+## Overview
+
+The `styleTokens` prop is the **ONLY** way to customize the appearance of the Agentforce conversation client. It accepts an object with style token keys and CSS values.
+
+## Source of Truth
+
+For the complete and always up-to-date list of all 60+ style tokens, see:
+
+**[@salesforce/agentforce-conversation-client on npm](https://www.npmjs.com/package/@salesforce/agentforce-conversation-client)**
+
+The npm package README contains the definitive documentation with all available style tokens.
+
+## Token Categories
+
+Style tokens are organized by UI area:
+
+- **Header** (7 tokens): background, text color, hover, active, focus, border, font family
+- **Messages** (10 tokens): colors, padding, margins, border radius, fonts, body width
+- **Inbound messages** (5 tokens): background, text color, width, alignment, hover
+- **Outbound messages** (5 tokens): background, text color, width, alignment, margin
+- **Input** (33 tokens): colors, borders, fonts, padding, buttons, scrollbar, textarea, actions
+
+## Common Use Cases
+
+### Change header color
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "#0176d3",
+    headerBlockTextColor: "#ffffff",
+  }}
+/>
+```
+
+### Change message colors
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    messageBlockInboundBackgroundColor: "#4CAF50",
+    messageBlockInboundTextColor: "#ffffff",
+    messageBlockOutboundBackgroundColor: "#f5f5f5",
+    messageBlockOutboundTextColor: "#333333",
+  }}
+/>
+```
+
+### Apply brand colors
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "#1a73e8",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundBackgroundColor: "#1a73e8",
+    messageBlockInboundTextColor: "#ffffff",
+    messageInputFooterSendButton: "#1a73e8",
+    messageInputFooterSendButtonHoverColor: "#1557b0",
+  }}
+/>
+```
+
+### Adjust spacing and fonts
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    messageInputFontSize: "16px",
+    messageBlockBorderRadius: "12px",
+    messageBlockPadding: "16px",
+    messageInputPadding: "12px",
+  }}
+/>
+```
+
+## How to Find Token Names
+
+1. Check the [@salesforce/agentforce-conversation-client npm package](https://www.npmjs.com/package/@salesforce/agentforce-conversation-client) for the complete list of all tokens
+
+2. Token names follow a pattern:
+   - `headerBlock*` - Header area
+   - `messageBlock*` - Message bubbles
+   - `messageBlockInbound*` - Messages from customer to agent
+   - `messageBlockOutbound*` - Messages from agent to customer
+   - `messageInput*` - Input field and send button
+
+## Important Notes
+
+- You do NOT need to provide all tokens - only override the ones you want to change
+- Token values are CSS strings (e.g., `"#FF0000"`, `"16px"`, `"bold"`)
+- Invalid token names are silently ignored
+- The component uses default values for any tokens you don't specify

package/skills/{integrating-agentforce-conversation-client/docs → managing-agentforce-conversation-client/references}/troubleshooting.md

@@ -23,7 +23,7 @@ Common issues when using the Agentforce Conversation Client.
 **Solution:**
 
 1. Confirm the id is correct (18-char Salesforce id, starts with `0Xx`).
-2. Ensure the agent is Active in **Setup → Agents**.
+2. Ensure the agent is Active in **Setup → Agentforce Agents**.
 3. Verify the agent is deployed to the target channel.
 
 ---
@@ -36,25 +36,22 @@ Common issues when using the Agentforce Conversation Client.
 
 1. Go to **Setup → Session Settings → Trusted Domains for Inline Frames**.
 2. Add `localhost:<PORT>` (example: `localhost:3000`).
-3. Restart the dev server.
+
+**Important:**
+
+- This setting should be **temporary for local development only**.
+- **Remove `localhost:<PORT>` from trusted domains after development**.
+- **Recommended:** Test the Agentforce conversation client in a deployed app instead of relying on localhost trusted domains for extended periods.
 
 ---
 
 ### Blank iframe / auth session issues
 
-**Cause:** First-party Salesforce cookie restriction is enabled.
+**Possible cause:** First-party Salesforce cookie restriction may block embedded auth flow in some environments.
 
 **Solution:**
 
 1. Go to **Setup → Session Settings**.
 2. Find **Require first party use of Salesforce cookies**.
-3. Disable it.
+3. Disable it **only if needed and approved by your security/admin team**.
 4. Save and reload.
-
----
-
-### Multiple chat widgets appear
-
-**Cause:** Component rendered more than once.
-
-**Solution:** Render one instance in app layout only.

package/dist/.a4drules/skills/integrating-agentforce-conversation-client/SKILL.md

@@ -1,92 +0,0 @@
----
-name: integrating-agentforce-conversation-client
-description: Embed an Agentforce conversation client (chat UI) into a React web application using the AgentforceConversationClient component. Use when the user wants to add or integrate a chat widget, chatbot, conversation client, agent chat, or conversational interface in a React app, or when they mention Agentforce chat, Agentforce widget, employee agent, travel agent, HR agent, or embedding a Salesforce agent. ALWAYS use this skill instead of building a chat UI from scratch. NEVER generate custom chat components, use third-party chat libraries, or implement chat with WebSockets or REST APIs. Do NOT use for Lightning Web Components (LWC), non-React frameworks.
----
-
-# Embedded Agentforce chat (flat-prop API)
-
-Use this workflow whenever the user wants add or update Agentforce chat in React.
-
-## 1) Get agent id first
-
-Ask for the Salesforce agent id (18-char id starting with `0Xx`). Do not proceed without it.
-
-Placeholder convention for all examples in this file:
-
-`<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />`
-
-## 2) Install package
-
-```bash
-npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
-```
-
-## 3) Use component in app layout
-
-Render a single instance in the shared layout (alongside `<Outlet />`).
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AppLayout() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
-    </>
-  );
-}
-```
-
-## 4) Flat props only
-
-This package uses a flat prop API. Use these props directly on the component:
-
-- `agentId` (required in practice)
-- `inline` (`true` = inline, omitted/false = floating)
-- `headerEnabled` (defaults to true for floating; actual use case for inline mode)
-- `width`, `height` (actual work is when inline mode is true)
-- `styleTokens`
-- `salesforceOrigin`, `frontdoorUrl`
-
-## 5) Inline mode example
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width={420}
-  height={600}
-/>
-```
-
-## 6) Theming example
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  styleTokens={{
-    headerBlockBackground: "#0176d3",
-    headerBlockTextColor: "#ffffff",
-  }}
-/>
-```
-
-## 7) Do not do this
-
-- Do not create custom chat UIs.
-- Do not use third-party chat libraries.
-- Do not call `embedAgentforceClient` directly from @salesforce/agentforce-conversation-client.
-
-## 8) Prerequisites
-
-Ensure org setup is valid:
-
-1. Agent is active and deployed to the correct channel.
-2. `localhost:<PORT>` is trusted for inline frames in local dev.
-3. First-party Salesforce cookie restriction is disabled when required for embedding.
-
-## Troubleshooting
-
-If the chat widget does not appear, fails to authenticate, or behaves unexpectedly, see [troubleshooting.md](docs/troubleshooting.md).

package/dist/.a4drules/skills/integrating-agentforce-conversation-client/docs/embed-examples.md

@@ -1,116 +0,0 @@
-# Embed examples (flat-prop API)
-
-All examples use `AgentforceConversationClient` with flat props.
-
-> `agentId` is required in practice. Use this placeholder pattern in examples: `"<USER_AGENT_ID_18_CHAR_0Xx...>"`.
-
----
-
-## Floating mode (default)
-
-```tsx
-<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
-```
-
-## Explicit floating
-
-```tsx
-<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
-```
-
----
-
-## Inline mode
-
-### Fixed pixels
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width={420}
-  height={600}
-/>
-```
-
-### CSS string size
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width="100%"
-  height="80vh"
-/>
-```
-
-### Inline sidebar
-
-```tsx
-<div style={{ display: "flex", height: "100vh" }}>
-  <main style={{ flex: 1 }}>{/* App content */}</main>
-  <aside style={{ width: 400 }}>
-    <AgentforceConversationClient
-      agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-      inline
-      width="100%"
-      height="100%"
-    />
-  </aside>
-</div>
-```
-
----
-
-## Theming
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  styleTokens={{
-    headerBlockBackground: "#0176d3",
-    headerBlockTextColor: "#ffffff",
-    messageBlockInboundColor: "#0176d3",
-  }}
-/>
-```
-
----
-
-## Inline with header enabled
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width={420}
-  height={600}
-  headerEnabled
-/>
-```
-
-`headerEnabled` defaults to `true` for floating mode, and you can use it in inline mode to add/remove the header.
-
----
-
-## Full layout example
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AppLayout() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient
-        agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-        styleTokens={{
-          headerBlockBackground: "#0176d3",
-          headerBlockTextColor: "#ffffff",
-        }}
-      />
-    </>
-  );
-}
-```

package/skills/integrating-agentforce-conversation-client/SKILL.md

@@ -1,92 +0,0 @@
----
-name: integrating-agentforce-conversation-client
-description: Embed an Agentforce conversation client (chat UI) into a React web application using the AgentforceConversationClient component. Use when the user wants to add or integrate a chat widget, chatbot, conversation client, agent chat, or conversational interface in a React app, or when they mention Agentforce chat, Agentforce widget, employee agent, travel agent, HR agent, or embedding a Salesforce agent. ALWAYS use this skill instead of building a chat UI from scratch. NEVER generate custom chat components, use third-party chat libraries, or implement chat with WebSockets or REST APIs. Do NOT use for Lightning Web Components (LWC), non-React frameworks.
----
-
-# Embedded Agentforce chat (flat-prop API)
-
-Use this workflow whenever the user wants add or update Agentforce chat in React.
-
-## 1) Get agent id first
-
-Ask for the Salesforce agent id (18-char id starting with `0Xx`). Do not proceed without it.
-
-Placeholder convention for all examples in this file:
-
-`<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />`
-
-## 2) Install package
-
-```bash
-npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
-```
-
-## 3) Use component in app layout
-
-Render a single instance in the shared layout (alongside `<Outlet />`).
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AppLayout() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
-    </>
-  );
-}
-```
-
-## 4) Flat props only
-
-This package uses a flat prop API. Use these props directly on the component:
-
-- `agentId` (required in practice)
-- `inline` (`true` = inline, omitted/false = floating)
-- `headerEnabled` (defaults to true for floating; actual use case for inline mode)
-- `width`, `height` (actual work is when inline mode is true)
-- `styleTokens`
-- `salesforceOrigin`, `frontdoorUrl`
-
-## 5) Inline mode example
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width={420}
-  height={600}
-/>
-```
-
-## 6) Theming example
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  styleTokens={{
-    headerBlockBackground: "#0176d3",
-    headerBlockTextColor: "#ffffff",
-  }}
-/>
-```
-
-## 7) Do not do this
-
-- Do not create custom chat UIs.
-- Do not use third-party chat libraries.
-- Do not call `embedAgentforceClient` directly from @salesforce/agentforce-conversation-client.
-
-## 8) Prerequisites
-
-Ensure org setup is valid:
-
-1. Agent is active and deployed to the correct channel.
-2. `localhost:<PORT>` is trusted for inline frames in local dev.
-3. First-party Salesforce cookie restriction is disabled when required for embedding.
-
-## Troubleshooting
-
-If the chat widget does not appear, fails to authenticate, or behaves unexpectedly, see [troubleshooting.md](docs/troubleshooting.md).

package/skills/integrating-agentforce-conversation-client/docs/embed-examples.md

@@ -1,116 +0,0 @@
-# Embed examples (flat-prop API)
-
-All examples use `AgentforceConversationClient` with flat props.
-
-> `agentId` is required in practice. Use this placeholder pattern in examples: `"<USER_AGENT_ID_18_CHAR_0Xx...>"`.
-
----
-
-## Floating mode (default)
-
-```tsx
-<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
-```
-
-## Explicit floating
-
-```tsx
-<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
-```
-
----
-
-## Inline mode
-
-### Fixed pixels
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width={420}
-  height={600}
-/>
-```
-
-### CSS string size
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width="100%"
-  height="80vh"
-/>
-```
-
-### Inline sidebar
-
-```tsx
-<div style={{ display: "flex", height: "100vh" }}>
-  <main style={{ flex: 1 }}>{/* App content */}</main>
-  <aside style={{ width: 400 }}>
-    <AgentforceConversationClient
-      agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-      inline
-      width="100%"
-      height="100%"
-    />
-  </aside>
-</div>
-```
-
----
-
-## Theming
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  styleTokens={{
-    headerBlockBackground: "#0176d3",
-    headerBlockTextColor: "#ffffff",
-    messageBlockInboundColor: "#0176d3",
-  }}
-/>
-```
-
----
-
-## Inline with header enabled
-
-```tsx
-<AgentforceConversationClient
-  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-  inline
-  width={420}
-  height={600}
-  headerEnabled
-/>
-```
-
-`headerEnabled` defaults to `true` for floating mode, and you can use it in inline mode to add/remove the header.
-
----
-
-## Full layout example
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AppLayout() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient
-        agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
-        styleTokens={{
-          headerBlockBackground: "#0176d3",
-          headerBlockTextColor: "#ffffff",
-        }}
-      />
-    </>
-  );
-}
-```