@salesforce/webapp-template-app-react-b2c-sample-experimental 1.29.0

package/dist/.a4drules/graphql.md

@@ -0,0 +1,408 @@
+# AI Rule: GraphQL Data Access
+
+Instructs agents to use the established GraphQL utilities for Salesforce data access.
+
+## Targets
+- `force-app/main/default/webApplications/static-app/**/*.ts`
+- `force-app/main/default/webApplications/static-app/**/*.tsx`
+
+## TypeScript Types & Code Generation
+
+### Generated Types File
+Types are auto-generated at: `force-app/main/default/webApplications/static-app/src/api/graphql-operations-types.ts`
+
+### Generation Command
+```bash
+cd force-app/main/default/webApplications/static-app && npm run graphql:codegen
+```
+
+The codegen configuration is located at `scripts/graphql/codegen.js` and generates types from:
+- Schema: `schema.graphql` (root level)
+- Documents: `force-app/main/default/webApplications/static-app/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/static-app/src/api/graphql.ts`:
+
+```typescript
+function executeGraphQL<T, InputVariables = Record<string, unknown>>(
+  query: string,
+  variables?: InputVariables
+): Promise<T>
+```
+
+- `T` - The response type (e.g., `GetHighRevenueAccountsQuery`)
+- `InputVariables` - The variables type (e.g., `GetHighRevenueAccountsQueryVariables`)
+
+### gql Template Tag
+Also exported from `graphql.ts` for inline query definitions:
+
+```typescript
+import { gql } from '../api/graphql';
+
+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
+The raw response wrapper (handled internally by `executeGraphQL`):
+
+```typescript
+interface GraphQLResponse<T> {
+  data: T;
+  errors?: Array<{
+    message: string;
+    locations?: Array<{ line: number; column: number }>;
+    path?: string[];
+  }>;
+}
+```
+
+### NodeOfConnection Utility Type
+Extract the node type from a connection (edges/node pattern):
+
+```typescript
+import { type NodeOfConnection } from '../api/graphql';
+
+// Extract Account node type from the query response
+type AccountNode = NodeOfConnection<
+  GetHighRevenueAccountsQuery['uiapi']['query']['Account']
+>;
+```
+
+### UIAPI Response Shape
+All Salesforce GraphQL queries follow this structure:
+
+```typescript
+interface UIAPIQueryResponse {
+  uiapi: {
+    query: {
+      [ObjectName]: {
+        edges?: Array<{
+          node?: {
+            Id: string;
+            [FieldName]?: { value?: FieldType | null } | null;
+            // Reference fields include the related record
+            [ReferenceField]?: {
+              value?: string | null;  // The ID
+              [RelatedField]?: { value?: RelatedType | null } | null;
+            } | null;
+          } | null;
+        } | null> | null;
+      } | null;
+    };
+  };
+}
+```
+
+## Required Workflow
+
+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/static-app/src/api/utils/query/myQuery.graphql
+query GetMyData($myVariable: String) {
+  uiapi {
+    query {
+      MyObject(first: 10, where: { Field: { eq: $myVariable } }) {
+        edges {
+          node {
+            Id
+            Name { value }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### Step 2: Run Code Generation
+```bash
+cd force-app/main/default/webApplications/static-app && 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) || [];
+}
+```
+
+**Key imports for Pattern 1:**
+- `executeGraphQL` - Execute the query
+- `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
+- Better for complex queries with fragments and multiple variables
+- IDE support for GraphQL (autocomplete, validation)
+- Queries can be tested independently
+- 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)
+- Slight overhead for very simple queries
+- Need to navigate between files during development
+- Doesn't support dynamic queries (e.g., the set of fields changes based on runtime conditions and cannot be predetermined)
+
+### Pattern 2: Inline Query with gql Tag (Recommended for simple queries)
+
+For simpler queries without variables or when colocation is preferred:
+
+```typescript
+import { executeGraphQL, gql } from '../api/graphql';
+import { type CurrentUserQuery } from '../graphql-operations-types';
+
+const CURRENT_USER_QUERY = gql`
+  query CurrentUser {
+    uiapi {
+      currentUser {
+        Id
+        Name {
+          value
+        }
+      }
+    }
+  }
+`;
+
+interface User {
+    id: string;
+    name: string;
+}
+
+export async function getCurrentUser(): Promise<User | null> {
+  try {
+    const response = await executeGraphQL<CurrentUserQuery>(CURRENT_USER_QUERY);
+
+    const userData = response.uiapi.currentUser;
+
+    if (!userData) {
+      throw new Error('No user data found');
+    }
+
+    return {
+      id: userData.Id,
+      name: userData.Name?.value || 'User',
+    };
+  } catch (error) {
+    console.error('Error fetching user data:', error);
+    throw error;
+  }
+}
+```
+
+**Key imports for Pattern 2:**
+- `executeGraphQL` - Execute the query
+- `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
+- Still gets type-checked against generated types
+- 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/static-app/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/static-app/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
+# static-app/src/api/utils/query/getAccountDetails.graphql
+query GetAccountDetails(
+  $id: ID!
+  $includeFinancials: Boolean!
+  $includeContacts: Boolean!
+) {
+  uiapi {
+    query {
+      Account(where: { Id: { eq: $id } }) {
+        edges {
+          node {
+            Id
+            Name { value }
+            ...FinancialFields @include(if: $includeFinancials)
+            ...ContactFields @include(if: $includeContacts)
+          }
+        }
+      }
+    }
+  }
+}
+
+fragment FinancialFields on Account {
+  AnnualRevenue { value }
+  NumberOfEmployees { value }
+}
+
+fragment ContactFields on Account {
+  Phone { value }
+  Website { value }
+}
+```
+
+### Usage
+```typescript
+import { executeGraphQL } from '../api/graphql';
+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,
+});
+```
+
+### 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 });
+
+// PREFERRED: Use executeGraphQL
+const data = await executeGraphQL<ResponseType>(query, variables);
+```
+
+### Missing Type Definitions
+```typescript
+// NOT RECOMMENDED: Untyped GraphQL calls
+const data = await executeGraphQL(query);
+
+// PREFERRED: Provide response type
+const data = await executeGraphQL<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);
+
+// PREFERRED: Use gql tag for inline queries
+const QUERY = gql`query { ... }`;
+const data = await executeGraphQL<ResponseType>(QUERY);
+
+// OR: Use .graphql file for complex queries
+import QUERY from './query/myQuery.graphql?raw';
+const data = await executeGraphQL<ResponseType>(QUERY);
+```
+
+**Why avoid plain strings:**
+- No syntax highlighting or validation
+- Harder to maintain and refactor
+- More error-prone
+
+## Benefits of executeGraphQL
+- Centralized error handling for GraphQL errors
+- Consistent typing with `GraphQLResponse<T>` interface
+- Uses the configured `baseDataClient` with proper authentication
+- Automatic extraction of `data` from response envelope
+
+## 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`
+
+### 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
+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/dist/.a4drules/images.md

@@ -0,0 +1,13 @@
+# Rule: Images
+
+**Description:** Image rules for React web apps (SFDX): default to Unsplash, CSP compliance, and accessibility. Ensures Unsplash is used as the default image source unless the developer provides their own.
+
+**Applies to:** `force-app/main/default/webapplications/*/**/*.{js,jsx,ts,tsx,css,html}`
+
+**Guidelines:**
+- Default to Unsplash when the user does not specify an image source; it is pre-configured in CSP and works in Salesforce without extra setup.
+- Use URL format: `https://images.unsplash.com/photo-{PHOTO_ID}?w={WIDTH}&h={HEIGHT}&fit=crop&q=80&auto=format` (e.g. photo ID `1557683316-973673baf926`).
+- If the user requests a different source, use it and inform: "Add CSP Trusted Site in Setup → Security → CSP Trusted Sites".
+- Always add descriptive `alt` text; use `alt=""` only for decorative images.
+- Avoid `placeholder.com`, `picsum.photos`, `via.placeholder.com` unless requested.
+- CSP-approved domains: `images.unsplash.com` (primary), `source.unsplash.com`, `images.pexels.com`.