@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental 1.61.2 → 1.61.4

package/dist/.a4drules/{graphql.md → features/feature-graphql-graphql-data-access-rule.md}

@@ -1,38 +1,45 @@
-# AI Rule: GraphQL Data Access
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
 
-Instructs agents to use the established GraphQL utilities for Salesforce data access.
+# GraphQL Data Access
 
-## Targets
-- `force-app/main/default/webapplications/<appName>/**/*.ts`
-- `force-app/main/default/webapplications/<appName>/**/*.tsx`
+Instructs agents to use the established GraphQL utilities for Salesforce data access.
 
 ## TypeScript Types & Code Generation
 
 ### Generated Types File
-Types are auto-generated at: `force-app/main/default/webapplications/<appName>/src/api/graphql-operations-types.ts`
+
+Types are auto-generated at: `src/api/graphql-operations-types.ts`
 
 ### Generation Command
-Run from the web app directory (replace `<appName>` with your app folder name, e.g. `base-react-app`):
+
 ```bash
-cd force-app/main/default/webapplications/<appName> && npm run graphql:codegen
+npm run graphql:codegen
 ```
 
-The codegen configuration is located at `scripts/graphql/codegen.js` (or the package's codegen config) and generates types from:
-- Schema: `schema.graphql` (root level of the web app or as configured)
-- Documents: `force-app/main/default/webapplications/<appName>/src/**/*.{graphql,ts,tsx}`
+The codegen configuration is at `codegen.yml` and generates types from:
+
+- Schema: `schema.graphql` (project root)
+- Documents: `src/**/*.{graphql,ts,tsx}`
 
 ### Type Naming Convention
+
 For a GraphQL operation named `GetHighRevenueAccounts`:
+
 - **Query/Mutation Response Type**: `GetHighRevenueAccountsQuery` or `GetHighRevenueAccountsMutation`
 - **Input Variables Type**: `GetHighRevenueAccountsQueryVariables` or `GetHighRevenueAccountsMutationVariables`
 
 ## Core Types & Function Signatures
 
 ### getDataSDK Function
+
 Available from `@salesforce/sdk-data`:
 
 ```typescript
-import { getDataSDK } from '@salesforce/sdk-data';
+import { getDataSDK } from "@salesforce/sdk-data";
 
 const data = await getDataSDK();
 const response = await data.graphql?.<ResponseType, VariablesType>(query, variables);
@@ -40,7 +47,26 @@ const response = await data.graphql?.<ResponseType, VariablesType>(query, variab
 
 `getDataSDK()` returns a lazily-initialized `DataSDK` singleton. The `graphql` method uses optional chaining (`?.`) because not all surfaces support GraphQL.
 
+### gql Template Tag
+
+Also available from `@salesforce/sdk-data` for inline query definitions:
+
+```typescript
+import { gql } from "@salesforce/sdk-data";
+
+const MY_QUERY = gql`
+  query MyQuery {
+    uiapi {
+      ...
+    }
+  }
+`;
+```
+
+The `gql` tag is a template literal that allows defining GraphQL queries inline while maintaining syntax highlighting in most editors.
+
 ### GraphQLResponse Shape
+
 `data.graphql?.()` returns `GraphQLResponse<T>`. Callers destructure `{ data, errors }` and handle errors themselves:
 
 ```typescript
@@ -61,64 +87,48 @@ GraphQL can return **both `data` and `errors`** in the same response (partial su
 ```typescript
 // Strategy A: Strict — treat any errors as failure (default for most queries)
 if (response?.errors?.length) {
-  throw new Error(response.errors.map(e => e.message).join('; '));
+  throw new Error(response.errors.map((e) => e.message).join("; "));
 }
 const result = response?.data;
 
 // Strategy B: Tolerant — log errors but use partial data
 if (response?.errors?.length) {
-  console.warn('GraphQL partial errors:', response.errors);
+  console.warn("GraphQL partial errors:", response.errors);
 }
 const result = response?.data;
 
 // Strategy C: Discriminated — fail only when no data came back
 if (response?.errors?.length && !response?.data) {
-  throw new Error(response.errors.map(e => e.message).join('; '));
+  throw new Error(response.errors.map((e) => e.message).join("; "));
 }
 if (response?.errors?.length) {
-  console.warn('Partial success with errors:', response.errors);
+  console.warn("Partial success with errors:", response.errors);
 }
 const result = response?.data;
 ```
 
 **When to use each:**
+
 - **Strategy A** — Default. Use for queries where incomplete data would be misleading (e.g., financial summaries, approval workflows).
 - **Strategy B** — Use when partial data is still useful and the UI can degrade gracefully (e.g., dashboard tiles, optional fields).
 - **Strategy C** — Use for mutations where the operation may succeed but some return fields are inaccessible.
 
 For mutation-specific partial responses, see `docs/generate-mutation-query.md` which covers `PARTIAL` and `FAILED` status handling workflows.
 
-### gql Template Tag
-Also available from `@salesforce/sdk-data` for inline query definitions:
-
-```typescript
-import { gql } from '@salesforce/sdk-data';
-
-const MY_QUERY = gql`
-  query MyQuery {
-    uiapi {
-      ...
-    }
-  }
-`;
-```
-
-The `gql` tag is a template literal that allows defining GraphQL queries inline while maintaining syntax highlighting in most editors.
-
 ### NodeOfConnection Utility Type
+
 Extract the node type from a connection (edges/node pattern):
 
 ```typescript
-import { type NodeOfConnection } from '@salesforce/sdk-data';
+import { type NodeOfConnection } from "@salesforce/sdk-data";
 
 // Extract Account node type from the query response
-type AccountNode = NodeOfConnection<
-  GetHighRevenueAccountsQuery['uiapi']['query']['Account']
->;
+type AccountNode = NodeOfConnection<GetHighRevenueAccountsQuery["uiapi"]["query"]["Account"]>;
 ```
 
 ### UIAPI Response Shape
-All Salesforce GraphQL queries follow this structure:
+
+All Salesforce GraphQL record queries follow this structure (https://developer.salesforce.com/docs/platform/graphql/guide/query-record-objects.html):
 
 ```typescript
 interface UIAPIQueryResponse {
@@ -131,7 +141,7 @@ interface UIAPIQueryResponse {
             [FieldName]?: { value?: FieldType | null } | null;
             // Reference fields include the related record
             [ReferenceField]?: {
-              value?: string | null;  // The ID
+              value?: string | null; // The ID
               [RelatedField]?: { value?: RelatedType | null } | null;
             } | null;
           } | null;
@@ -149,10 +159,11 @@ There are **two acceptable patterns** for defining GraphQL queries:
 ### Pattern 1: External .graphql File (Recommended for complex queries)
 
 #### Step 1: Create .graphql File
+
 Store queries in `.graphql` files for codegen to process:
 
 ```graphql
-# force-app/main/default/webapplications/<appName>/src/api/utils/query/myQuery.graphql
+# src/api/utils/query/myQuery.graphql
 query GetMyData($myVariable: String) {
   uiapi {
     query {
@@ -160,7 +171,9 @@ query GetMyData($myVariable: String) {
         edges {
           node {
             Id
-            Name { value }
+            Name {
+              value
+            }
           }
         }
       }
@@ -170,47 +183,50 @@ query GetMyData($myVariable: String) {
 ```
 
 #### Step 2: Run Code Generation
+
 ```bash
-cd force-app/main/default/webapplications/<appName> && npm run graphql:codegen
+npm run graphql:codegen
 ```
 
 This generates types in `graphql-operations-types.ts`:
+
 - `GetMyDataQuery` - response type
 - `GetMyDataQueryVariables` - variables type
 
 #### Step 3: Import and Use
+
 ```typescript
-import { getDataSDK, type NodeOfConnection } from '@salesforce/sdk-data';
-import MY_QUERY from './query/myQuery.graphql?raw';
-import type {
-  GetMyDataQuery,
-  GetMyDataQueryVariables,
-} from '../graphql-operations-types';
+import { getDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
+import MY_QUERY from "./query/myQuery.graphql?raw";
+import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";
 
-type MyNode = NodeOfConnection<GetMyDataQuery['uiapi']['query']['MyObject']>;
+type MyNode = NodeOfConnection<GetMyDataQuery["uiapi"]["query"]["MyObject"]>;
 
-export async function getMyData(
-  variables: GetMyDataQueryVariables
-): Promise<MyNode[]> {
+export async function getMyData(variables: GetMyDataQueryVariables): Promise<MyNode[]> {
   const data = await getDataSDK();
-  const response = await data.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(MY_QUERY, variables);
+  const response = await data.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(
+    MY_QUERY,
+    variables,
+  );
 
   if (response?.errors?.length) {
-    const errorMessages = response.errors.map(e => e.message).join('; ');
+    const errorMessages = response.errors.map((e) => e.message).join("; ");
     throw new Error(`GraphQL Error: ${errorMessages}`);
   }
 
-  return response?.data?.uiapi?.query?.MyObject?.edges?.map(edge => edge?.node) || [];
+  return response?.data?.uiapi?.query?.MyObject?.edges?.map((edge) => edge?.node) || [];
 }
 ```
 
 **Key imports for Pattern 1:**
+
 - `getDataSDK` - Get the DataSDK singleton
 - `NodeOfConnection` - Extract node types from connection responses
 - Query from `.graphql` file with `?raw` suffix
 - Generated types from `graphql-operations-types.ts`
 
 **Pattern 1 Benefits:**
+
 - Full codegen support with automatic type generation
 - Syntax highlighting and validation in `.graphql` files
 - Easier to share queries across multiple files/components
@@ -220,6 +236,7 @@ export async function getMyData(
 - Clear separation of concerns between query definition and usage
 
 **Pattern 1 Limitations:**
+
 - Requires separate file management
 - Extra step to run codegen after query changes
 - More boilerplate (file import with `?raw`, separate file to maintain)
@@ -232,8 +249,8 @@ export async function getMyData(
 For simpler queries without variables or when colocation is preferred:
 
 ```typescript
-import { getDataSDK, gql } from '@salesforce/sdk-data';
-import { type CurrentUserQuery } from '../graphql-operations-types';
+import { getDataSDK, gql } from "@salesforce/sdk-data";
+import { type CurrentUserQuery } from "../graphql-operations-types";
 
 const CURRENT_USER_QUERY = gql`
   query CurrentUser {
@@ -249,8 +266,8 @@ const CURRENT_USER_QUERY = gql`
 `;
 
 interface User {
-    id: string;
-    name: string;
+  id: string;
+  name: string;
 }
 
 export async function getCurrentUser(): Promise<User | null> {
@@ -259,32 +276,34 @@ export async function getCurrentUser(): Promise<User | null> {
     const response = await data.graphql?.<CurrentUserQuery>(CURRENT_USER_QUERY);
 
     if (response?.errors?.length) {
-      throw new Error(response.errors.map(e => e.message).join('; '));
+      throw new Error(response.errors.map((e) => e.message).join("; "));
     }
 
     const userData = response?.data?.uiapi.currentUser;
 
     if (!userData) {
-      throw new Error('No user data found');
+      throw new Error("No user data found");
     }
 
     return {
       id: userData.Id,
-      name: userData.Name?.value || 'User',
+      name: userData.Name?.value || "User",
     };
   } catch (error) {
-    console.error('Error fetching user data:', error);
+    console.error("Error fetching user data:", error);
     throw error;
   }
 }
 ```
 
 **Key imports for Pattern 2:**
+
 - `getDataSDK` - Get the DataSDK singleton
 - `gql` - Template tag for inline query definition
 - Generated types from `graphql-operations-types.ts`
 
 **Pattern 2 Benefits:**
+
 - Query is colocated with usage code
 - Supports dynamic queries (e.g., the set of fields changes based on runtime conditions and cannot be predetermined)
 - No separate file to maintain
@@ -292,51 +311,33 @@ export async function getCurrentUser(): Promise<User | null> {
 - Simpler for straightforward queries
 
 **Pattern 2 Limitations:**
+
 - Inline queries without `gql` template tag are not processed by codegen
 - Must manually ensure query name matches generated types
 - Less suitable for complex queries with fragments
 
-## Reference Examples
-
-### Pattern 1 Example: accounts.ts
-See `force-app/main/default/webapplications/<appName>/src/api/utils/accounts.ts` for Pattern 1:
-1. Importing query from `.graphql` file with `?raw` suffix
-2. Importing generated types from `graphql-operations-types.ts`
-3. Using `NodeOfConnection` to extract node types
-4. Proper typing with `data.graphql?.<ResponseType>(query, variables)`
-5. Safe data extraction from the nested response
-
-### Pattern 2 Example: user.ts
-See `force-app/main/default/webapplications/<appName>/src/api/utils/user.ts` for Pattern 2:
-1. Using `gql` template tag for inline query definition
-2. Importing generated types from `graphql-operations-types.ts`
-3. Simple query without variables
-4. Error handling with try/catch
-5. Direct access to `uiapi.currentUser` (non-connection response)
-
 ## Conditional Field Selection with Directives
 
 For dynamic fieldsets with known fields that should be conditionally included, use GraphQL directives instead of building queries dynamically. This preserves type generation while allowing runtime control.
 
 ### Directives
+
 - **`@include(if: $condition)`** - include field/fragment when `$condition` is `true`
 - **`@skip(if: $condition)`** - skip field/fragment when `$condition` is `true`
 
 ### Example with Fragments
+
 ```graphql
-# <appName>/src/api/utils/query/getAccountDetails.graphql
-query GetAccountDetails(
-  $id: ID!
-  $includeFinancials: Boolean!
-  $includeContacts: Boolean!
-) {
+query GetAccountDetails($id: ID!, $includeFinancials: Boolean!, $includeContacts: Boolean!) {
   uiapi {
     query {
       Account(where: { Id: { eq: $id } }) {
         edges {
           node {
             Id
-            Name { value }
+            Name {
+              value
+            }
             ...FinancialFields @include(if: $includeFinancials)
             ...ContactFields @include(if: $includeContacts)
           }
@@ -347,46 +348,52 @@ query GetAccountDetails(
 }
 
 fragment FinancialFields on Account {
-  AnnualRevenue { value }
-  NumberOfEmployees { value }
+  AnnualRevenue {
+    value
+  }
+  NumberOfEmployees {
+    value
+  }
 }
 
 fragment ContactFields on Account {
-  Phone { value }
-  Website { value }
+  Phone {
+    value
+  }
+  Website {
+    value
+  }
 }
 ```
 
 ### Usage
+
 ```typescript
-import { getDataSDK } from '@salesforce/sdk-data';
-import QUERY from './query/getAccountDetails.graphql?raw';
+import { getDataSDK } from "@salesforce/sdk-data";
+import QUERY from "./query/getAccountDetails.graphql?raw";
 import type {
   GetAccountDetailsQuery,
   GetAccountDetailsQueryVariables,
-} from '../graphql-operations-types';
+} from "../graphql-operations-types";
 
 const data = await getDataSDK();
-const response = await data.graphql?.<GetAccountDetailsQuery, GetAccountDetailsQueryVariables>(QUERY, {
-  id: accountId,
-  includeFinancials: userWantsFinancials,
-  includeContacts: userWantsContacts,
-});
+const response = await data.graphql?.<GetAccountDetailsQuery, GetAccountDetailsQueryVariables>(
+  QUERY,
+  {
+    id: accountId,
+    includeFinancials: userWantsFinancials,
+    includeContacts: userWantsContacts,
+  },
+);
 ```
 
-### Benefits
-- Query stays in `.graphql` file (codegen works)
-- Generated types include all possible fields as optional
-- Runtime control over which fields are fetched
-- Better performance when fields aren't needed
-- Type safety is preserved
-
 ## Anti-Patterns (Not Recommended)
 
 ### Direct API Calls
+
 ```typescript
 // NOT RECOMMENDED: Direct axios/fetch calls for GraphQL
-const response = await axios.post('/graphql', { query });
+const response = await axios.post("/graphql", { query });
 
 // PREFERRED: Use the DataSDK
 const data = await getDataSDK();
@@ -394,6 +401,7 @@ const response = await data.graphql?.<ResponseType>(query, variables);
 ```
 
 ### Missing Type Definitions
+
 ```typescript
 // NOT RECOMMENDED: Untyped GraphQL calls
 const data = await getDataSDK();
@@ -405,6 +413,7 @@ const response = await data.graphql?.<GetMyDataQuery>(query);
 ```
 
 ### Plain String Queries (Without gql Tag)
+
 ```typescript
 // NOT RECOMMENDED: Plain string queries without gql tag
 const query = `query { ... }`;
@@ -417,36 +426,36 @@ const data = await getDataSDK();
 const response = await data.graphql?.<ResponseType>(QUERY);
 
 // OR: Use .graphql file for complex queries
-import QUERY from './query/myQuery.graphql?raw';
+import QUERY from "./query/myQuery.graphql?raw";
 const data = await getDataSDK();
 const response = await data.graphql?.<ResponseType>(QUERY);
 ```
 
-**Why avoid plain strings:**
-- No syntax highlighting or validation
-- Harder to maintain and refactor
-- More error-prone
-
 ## Benefits of the DataSDK GraphQL API
+
 - Uses the DataSDK with proper authentication and CSRF token handling
 - Consistent typing with `GraphQLResponse<T>` interface
 - Optional chaining (`?.`) safely handles surfaces where GraphQL is unavailable
 - Callers get full `GraphQLResponse<T>` for flexible error handling
 
 ## Quality Checklist
+
 Before completing GraphQL data access code:
 
 ### For Pattern 1 (.graphql files):
+
 1. [ ] Create `.graphql` file for the query/mutation
 2. [ ] Run `npm run graphql:codegen` to generate types
 3. [ ] Import query with `?raw` suffix
 4. [ ] Import generated types from `graphql-operations-types.ts`
 5. [ ] Use `data.graphql?.<ResponseType>()` with proper generic
-6. [ ] Use `NodeOfConnection` for cleaner node types when needed
-7. [ ] Handle optional chaining for nested response data
-8. [ ] Follow the pattern in `accounts.ts`
+6. [ ] Handle `response.errors` and destructure `response.data`
+7. [ ] Use `NodeOfConnection` for cleaner node types when needed
+8. [ ] Handle optional chaining for nested response data
+9. [ ] Follow the pattern in `accounts.ts`
 
 ### For Pattern 2 (inline with gql):
+
 1. [ ] Define query using `gql` template tag
 2. [ ] Ensure query name matches generated types in `graphql-operations-types.ts`
 3. [ ] Import generated types for the query
@@ -456,5 +465,6 @@ Before completing GraphQL data access code:
 7. [ ] Follow the pattern in `user.ts`
 
 ### General:
+
 - [ ] Choose Pattern 1 for complex queries with variables, fragments, or when shared
 - [ ] Choose Pattern 2 for simple, colocated queries without complex requirements

package/dist/.a4drules/features/feature-react-agentforce-conversation-client-embedded-agent-rule.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/components/**/*.ts"
+---
+
+# Agentforce Conversation Client (standards)
+
+When adding or editing the embedded Agentforce chat client in this project, follow these conventions.
+
+## Component and library
+
+- Use the shared **AgentforceConversationClient** React component from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. Do not call `embedAgentforceClient` directly in application code.
+- Install with `npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. The underlying SDK (`@salesforce/agentforce-conversation-client`) is included automatically as a dependency.
+
+## Authentication
+
+- The component resolves auth automatically: **localhost** fetches `frontdoorUrl` from `/__lo/frontdoor`; **production** uses `window.location.origin` as `salesforceOrigin`.
+- Do not hard-code `salesforceOrigin` or `frontdoorUrl` unless the consumer explicitly provides them as props.
+
+## Rendering mode
+
+- Pass `agentforceClientConfig.renderingConfig.mode` to select **floating** (default) or **inline**. Do not apply custom positioning CSS to override the built-in layout.
+- For inline mode, set `width` and `height` in `renderingConfig`. Do not override iframe dimensions with external CSS.
+
+## Agent selection
+
+- Use `agentforceClientConfig.agentId` to select a specific agent. Ask the user for the agent ID; if not provided, note that the org's default agent is used.
+
+## Placement
+
+- Render `<AgentforceConversationClient />` inside the existing app layout (e.g. alongside `<Outlet />`). Do not replace the entire page shell with the chat client.

package/dist/.a4drules/features/feature-react-chart-analytics-charts-rule.md

@@ -0,0 +1,27 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/components/**/*.ts"
+---
+
+# Analytics charts (standards)
+
+When adding or editing chart UI in this project, follow these conventions.
+
+## Components and library
+
+- Use the shared **AnalyticsChart** component (and **ChartContainer** when a framed block is needed). Do not use raw Recharts components for standard line or bar charts.
+- The project must have **recharts** installed (`npm install recharts`).
+
+## Data shape
+
+- **Time-series** (line): data must be an array of `{ x: string, y: number }`. Map raw fields (e.g. `date`, `value`) to these keys before passing to the chart.
+- **Categorical** (bar): data must be an array of `{ name: string, value: number }`. Map raw fields (e.g. `category`, `total`) accordingly.
+
+## Theming
+
+- Use only the **theme** prop on AnalyticsChart: `red` (decline/loss), `green` (growth/gain), `neutral` (default or mixed). Do not introduce ad-hoc color schemes for these semantics.
+
+## Placement
+
+- Render charts inside the existing application frame (e.g. main content or a route). Do not replace the full app shell with a single chart.