@salesforce/templates 66.3.1 → 66.3.2

package/lib/templates/project/reactb2e/.a4drules/{graphql.md → features/feature-graphql-graphql-data-access-rule.md}

@@ -1,51 +1,58 @@
-# 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
 
-### executeGraphQL Function
-Located in `force-app/main/default/webapplications/<appName>/src/api/graphql.ts`:
+### getDataSDK Function
+
+Available from `@salesforce/sdk-data`:
 
 ```typescript
-function executeGraphQL<T, InputVariables = Record<string, unknown>>(
-  query: string,
-  variables?: InputVariables
-): Promise<T>
+import { getDataSDK } from "@salesforce/sdk-data";
+
+const data = await getDataSDK();
+const response = await data.graphql?.<ResponseType, VariablesType>(query, variables);
 ```
 
-- `T` - The response type (e.g., `GetHighRevenueAccountsQuery`)
-- `InputVariables` - The variables type (e.g., `GetHighRevenueAccountsQueryVariables`)
+`getDataSDK()` returns a lazily-initialized `DataSDK` singleton. The `graphql` method uses optional chaining (`?.`) because not all surfaces support GraphQL.
 
 ### gql Template Tag
-Also exported from `graphql.ts` for inline query definitions:
+
+Also available from `@salesforce/sdk-data` for inline query definitions:
 
 ```typescript
-import { gql } from '../api/graphql';
+import { gql } from "@salesforce/sdk-data";
 
 const MY_QUERY = gql`
   query MyQuery {
@@ -59,7 +66,8 @@ const MY_QUERY = gql`
 The `gql` tag is a template literal that allows defining GraphQL queries inline while maintaining syntax highlighting in most editors.
 
 ### GraphQLResponse Shape
-The raw response wrapper (handled internally by `executeGraphQL`):
+
+`data.graphql?.()` returns `GraphQLResponse<T>`. Callers destructure `{ data, errors }` and handle errors themselves:
 
 ```typescript
 interface GraphQLResponse<T> {
@@ -72,20 +80,55 @@ interface GraphQLResponse<T> {
 }
 ```
 
+### Handling Mixed Responses (Partial Success)
+
+GraphQL can return **both `data` and `errors`** in the same response (partial success). For example, some fields may resolve while others fail due to field-level security. Choose a strategy per use case:
+
+```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("; "));
+}
+const result = response?.data;
+
+// Strategy B: Tolerant — log errors but use partial data
+if (response?.errors?.length) {
+  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("; "));
+}
+if (response?.errors?.length) {
+  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.
+
 ### NodeOfConnection Utility Type
+
 Extract the node type from a connection (edges/node pattern):
 
 ```typescript
-import { type NodeOfConnection } from '../api/graphql';
+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 {
@@ -98,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;
@@ -116,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 {
@@ -127,7 +171,9 @@ query GetMyData($myVariable: String) {
         edges {
           node {
             Id
-            Name { value }
+            Name {
+              value
+            }
           }
         }
       }
@@ -137,41 +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 { executeGraphQL, type NodeOfConnection } from '../api/graphql';
-import MY_QUERY from './query/myQuery.graphql?raw';
-import type {
-  GetMyDataQuery,
-  GetMyDataQueryVariables,
-} from '../graphql-operations-types';
-
-// Extract node type for cleaner return types
-type MyNode = NodeOfConnection<GetMyDataQuery['uiapi']['query']['MyObject']>;
-
-export async function getMyData(
-  variables: GetMyDataQueryVariables
-): Promise<MyNode[]> {
-  const response = await executeGraphQL<GetMyDataQuery>(MY_QUERY, variables);
-  return response.uiapi?.query?.MyObject?.edges?.map(edge => edge?.node) || [];
+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"]>;
+
+export async function getMyData(variables: GetMyDataQueryVariables): Promise<MyNode[]> {
+  const data = await getDataSDK();
+  const response = await data.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(
+    MY_QUERY,
+    variables,
+  );
+
+  if (response?.errors?.length) {
+    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) || [];
 }
 ```
 
 **Key imports for Pattern 1:**
-- `executeGraphQL` - Execute the query
+
+- `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
@@ -181,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)
@@ -193,8 +249,8 @@ export async function getMyData(
 For simpler queries without variables or when colocation is preferred:
 
 ```typescript
-import { executeGraphQL, gql } from '../api/graphql';
-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 {
@@ -210,37 +266,44 @@ const CURRENT_USER_QUERY = gql`
 `;
 
 interface User {
-    id: string;
-    name: string;
+  id: string;
+  name: string;
 }
 
 export async function getCurrentUser(): Promise<User | null> {
   try {
-    const response = await executeGraphQL<CurrentUserQuery>(CURRENT_USER_QUERY);
+    const data = await getDataSDK();
+    const response = await data.graphql?.<CurrentUserQuery>(CURRENT_USER_QUERY);
+
+    if (response?.errors?.length) {
+      throw new Error(response.errors.map((e) => e.message).join("; "));
+    }
 
-    const userData = response.uiapi.currentUser;
+    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:**
-- `executeGraphQL` - Execute the query
+
+- `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
@@ -248,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 `executeGraphQL<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)
           }
@@ -303,107 +348,123 @@ 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 { executeGraphQL } from '../api/graphql';
-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';
-
-const data = await executeGraphQL<GetAccountDetailsQuery>(QUERY, {
-  id: accountId,
-  includeFinancials: userWantsFinancials,
-  includeContacts: userWantsContacts,
-});
+} from "../graphql-operations-types";
+
+const data = await getDataSDK();
+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 executeGraphQL
-const data = await executeGraphQL<ResponseType>(query, variables);
+// PREFERRED: Use the DataSDK
+const data = await getDataSDK();
+const response = await data.graphql?.<ResponseType>(query, variables);
 ```
 
 ### Missing Type Definitions
+
 ```typescript
 // NOT RECOMMENDED: Untyped GraphQL calls
-const data = await executeGraphQL(query);
+const data = await getDataSDK();
+await data.graphql?.(query);
 
 // PREFERRED: Provide response type
-const data = await executeGraphQL<GetMyDataQuery>(query);
+const data = await getDataSDK();
+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 { ... }`;
-const data = await executeGraphQL(query);
+const data = await getDataSDK();
+await data.graphql?.(query);
 
 // PREFERRED: Use gql tag for inline queries
 const QUERY = gql`query { ... }`;
-const data = await executeGraphQL<ResponseType>(QUERY);
+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';
-const data = await executeGraphQL<ResponseType>(QUERY);
+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
 
-## Benefits of executeGraphQL
-- Centralized error handling for GraphQL errors
+- Uses the DataSDK with proper authentication and CSRF token handling
 - Consistent typing with `GraphQLResponse<T>` interface
-- Uses the configured `baseDataClient` with proper authentication
-- Automatic extraction of `data` from response envelope
+- 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 `executeGraphQL<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`
+5. [ ] Use `data.graphql?.<ResponseType>()` with proper generic
+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
-4. [ ] Use `executeGraphQL<ResponseType>()` with proper generic
-5. [ ] Handle errors with try/catch when appropriate
+4. [ ] Use `data.graphql?.<ResponseType>()` with proper generic
+5. [ ] Handle `response.errors` and destructure `response.data`
 6. [ ] Handle optional chaining for nested response data
 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/lib/templates/project/reactb2e/.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/lib/templates/project/reactb2e/.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.