@salesforce/webapp-template-app-react-byo-experimental 1.3.3

package/dist/.a4drules/graphql.md

@@ -0,0 +1,98 @@
+# AI Rule: GraphQL Data Access
+
+Instructs agents to use the established GraphQL utilities for Salesforce data access.
+
+## Targets
+- `force-app/main/default/webapplications/*/**/*.ts`
+- `force-app/main/default/webapplications/*/**/*.tsx`
+
+## Required: Use executeGraphQL Function
+
+When fetching data via GraphQL in the web app, **always** use the `executeGraphQL` function from `force-app/main/default/webapplications/<appName>/src/api/graphql.ts`.
+
+### Import Pattern
+```typescript
+import { executeGraphQL } from '../api/graphql';
+// or adjust relative path as needed based on file location
+```
+
+### Usage Pattern
+```typescript
+interface MyQueryResponse {
+  uiapi: {
+    query: {
+      MyObject: {
+        edges: Array<{
+          node: {
+            Id: string;
+            Name: { value: string };
+            // ... other fields
+          };
+        }>;
+      };
+    };
+  };
+}
+
+const MY_QUERY = `
+  query GetMyData {
+    uiapi {
+      query {
+        MyObject(first: 10) {
+          edges {
+            node {
+              Id
+              Name { value }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const response = await executeGraphQL<MyQueryResponse>(MY_QUERY, { /* variables */ });
+```
+
+## Reference Example
+
+See `force-app/main/default/webapplications/<appName>/src/api/utils/accounts.ts` for a complete working example that demonstrates:
+1. TypeScript interface definitions for GraphQL response shapes
+2. GraphQL query construction using UIAPI syntax
+3. Proper typing with `executeGraphQL<T>()`
+4. Data extraction from the response
+
+## Anti-Patterns (FORBIDDEN)
+
+### Direct API Calls
+```typescript
+// FORBIDDEN: Direct axios/fetch calls for GraphQL
+const response = await axios.post('/graphql', { query });
+
+// REQUIRED: Use executeGraphQL
+const data = await executeGraphQL<ResponseType>(query, variables);
+```
+
+### Missing Type Definitions
+```typescript
+// FORBIDDEN: Untyped GraphQL calls
+const data = await executeGraphQL(query);
+
+// REQUIRED: Provide response type
+const data = await executeGraphQL<MyTypedResponse>(query);
+```
+
+## 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:
+1. Import `executeGraphQL` from the correct path
+2. Define TypeScript interfaces for the query response
+3. Use proper generic typing: `executeGraphQL<ResponseType>`
+4. Handle the returned data appropriately
+5. Follow the pattern established in `force-app/main/default/webapplications/<appName>/src/api/utils/accounts.ts`
+

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`.

package/dist/.a4drules/react.md

@@ -0,0 +1,361 @@
+# AI Customization Rule: React Web App (SFDX)
+
+This rule consolidates React web application guidelines, data access rules, security standards, anti-patterns, and project integration requirements for consistent AI-generated code.
+
+## Targets (File Pattern Matching)
+
+Apply these rules to the React web app files under the SFDX package directory:
+
+- `force-app/main/default/webapplications/*/**/*.js`
+- `force-app/main/default/webapplications/*/**/*.jsx`
+- `force-app/main/default/webapplications/*/**/*.ts`
+- `force-app/main/default/webapplications/*/**/*.tsx`
+
+## Rule Objectives
+
+- Enforce secure, performant, and maintainable patterns for Salesforce data access.
+- Standardize UI with shadcn/ui and Tailwind.
+- Prevent prohibited patterns that break React or Salesforce constraints.
+
+## Project & Entry Points
+
+- React web app root: `force-app/main/default/webapplications/<appName>/`
+- Main entry component: `force-app/main/default/webapplications/<appName>/src/App.tsx`
+- Running Development Server:
+  - `npm run dev`
+  - You can generally assume the dev server is already running and don't need to start it.
+- Keep build/deploy workflow intact:
+  - `npm run build`
+  - `npm run deploy`
+  - `npm run open`
+
+## Component Library (MANDATORY)
+
+- Use shadcn/ui for UI components (Buttons, Cards, Inputs, Dialogs, etc.).
+- Import patterns:
+
+```javascript
+import { Button } from '@/components/ui/button';
+import { Card, CardHeader, CardContent } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+```
+
+## Styling Standards
+
+- Use Tailwind CSS utility classes.
+- Follow consistent spacing, color, and typography conventions.
+
+## Module & Platform Restrictions
+
+- React apps must NOT import or rely on Salesforce platform modules; do not use:
+  - `@salesforce/*`
+  - `lightning/*`
+  - `@wire` (LWC-only)
+- Use standard web APIs and npm packages only.
+
+## LWC MCP Server Integration (Data Access Guidance)
+
+The LWC MCP server (via Agentforce Vibes extension) provides framework-agnostic data access guidance for UI API and GraphQL patterns.
+
+### Primary Tool: `orchestrate_lds_data_requirements`
+
+The `orchestrate_lds_data_requirements` tool analyzes data requirements and routes to appropriate guidance tools (UI API or GraphQL). **Note:** Tool names may change, but the purpose remains orchestrating LDS data requirements.
+
+**Important for React Applications:** If the MCP tool recommends Apex REST, React applications should ignore this recommendation. Apex REST is not available in React applications. Follow the [Apex REST Strategy](#data-access-priority-order) section above to evaluate whether GraphQL can handle the requirement, or inform the user that the feature is not currently supported in React.
+
+### Tool Availability Check (MANDATORY)
+
+Before implementing data access, **MUST** verify `orchestrate_lds_data_requirements` is available. If unavailable:
+
+1. Notify user: "LWC MCP data access tools not enabled. Add 'lwc-experts' to --toolsets in a4d_mcp_settings.json"
+2. Offer to update the file if you have write access
+3. Otherwise, provide manual instructions
+
+**Configuration:** Add `"lwc-experts"` to `--toolsets` in `a4d_mcp_settings.json` (typically at `{VSCode/Cursor globalStorage}/salesforce.salesforcedx-einstein-gpt/settings/a4d_mcp_settings.json`). Example: `"metadata,lwc-experts"` in the args array.
+
+### LWC MCP Server Tool Usage Restrictions (CRITICAL)
+
+**This rule applies when building React applications. Do NOT create LWC components or use LWC-specific development tools.**
+
+**Allowed MCP Tools (Data Access Only):**
+
+- `orchestrate_lds_data_requirements` - Primary tool for data access guidance
+- Any data access guidance tools referenced by `orchestrate_lds_data_requirements` (e.g., UI API or GraphQL guidance tools)
+
+**Note:** If the MCP tool recommends Apex REST guidance tools, React applications should ignore these recommendations as Apex REST is not available in React.
+
+**Prohibited MCP Tools (LWC Component Development):**
+
+- `guide_lwc_development` - LWC component development guidance
+- `orchestrate_lwc_component_creation` - LWC component creation orchestration
+- `create_lwc_component_from_prd` - LWC component creation from PRD
+- Any other LWC component creation, development, or framework-specific tools
+
+**Enforcement:**
+
+- **NEVER** call LWC component creation or development tools from the LWC MCP server
+- **ONLY** use data access related tools that provide framework-agnostic guidance
+- If you encounter a request to create LWC components, remind the user that you are building a React app and redirect them to use React patterns instead
+
+## Data Access Rules (CRITICAL)
+
+- MANDATORY: Use `axios` for all API calls from React.
+
+### Data Access Workflow (MANDATORY)
+
+**Before implementing any data access functionality:**
+
+1. **Proactively check** for LWC MCP server tool availability (see [LWC MCP Server Integration](#lwc-mcp-server-integration-data-access-guidance) section above)
+2. **Use the LWC MCP server's `orchestrate_lds_data_requirements` tool** to get guidance on the appropriate data access pattern
+3. The MCP tool will analyze your requirements and guide you to the appropriate Salesforce data access pattern (GraphQL or UI API)
+4. **Follow the MCP tool's recommendations** when implementing data access code, prioritizing GraphQL for all operations
+5. **If the tool recommends Apex REST**, ignore this recommendation and follow the [Apex REST Strategy](#data-access-priority-order) to evaluate if GraphQL can handle the requirement
+
+**Note:** The code examples below serve as reference patterns, but your implementation should be informed by the MCP tool's guidance, which provides the most up-to-date best practices and framework-agnostic patterns.
+
+### Data Access Priority Order
+
+The LWC MCP server's `orchestrate_lds_data_requirements` tool follows this priority order when recommending data access patterns:
+
+1. **GraphQL** (queries & mutations) - Preferred for all data operations including reads, writes, complex queries, relationships, and multi-entity operations
+2. **Salesforce UI API** - For standard CRUD operations when GraphQL is not suitable
+
+**Apex REST Strategy (CRITICAL):**
+
+- **Apex REST is NOT available in React applications.** If the MCP tool recommends Apex REST, or if you believe Apex is needed:
+  1. **Reflect** on why Apex seems necessary
+  2. **Evaluate** whether GraphQL queries or mutations can accomplish the task
+  3. **If GraphQL cannot handle the requirement**, inform the user that the feature is not currently supported in React applications
+  4. **Do NOT** implement Apex REST endpoints or attempt to call them from React
+
+**Note:** For AI/generative features, see the [Einstein LLM Gateway](#einstein-llm-gateway-aigenerative-features) section below.
+
+### Reference Code Examples
+
+The following code examples serve as reference patterns for React applications. **Always consult the LWC MCP server's `orchestrate_lds_data_requirements` tool first** to ensure you're using the most appropriate pattern and latest best practices for your specific use case.
+
+UI API example (read):
+
+```javascript
+async function fetchRecord(recordId) {
+  try {
+    const res = await axios.get(
+      `/services/data/v62.0/ui-api/records/${recordId}`
+    );
+    return res.data;
+  } catch (error) {
+    const text = error.message;
+    throw new Error(`UI API failed: ${error.status} ${text}`);
+  }
+}
+```
+
+GraphQL utility (supports both queries and mutations):
+
+```javascript
+export async function sfGraphQL(query, variables = {}) {
+  try {
+    const res = await axios.post('/services/data/v62.0/graphql', {
+      query,
+      variables,
+    });
+    const json = res.data;
+    if (Array.isArray(json.errors) && json.errors.length) {
+      throw new Error(json.errors.map(e => e.message).join('; '));
+    }
+    return json.data;
+  } catch (error) {
+    throw new Error(`GraphQL error: ${error.status}`);
+  }
+}
+```
+
+GraphQL query example:
+
+```javascript
+const GET_ACCOUNT = `
+  query GetAccount($id: ID!) {
+    uiapi {
+      query {
+        Account(where: { Id: { eq: $id } }) {
+          edges {
+            node {
+              Id
+              Name {
+                value
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const account = await sfGraphQL(GET_ACCOUNT, { id: '001...' });
+```
+
+GraphQL mutation example:
+
+```javascript
+const UPDATE_ACCOUNT = `
+  mutation UpdateAccount($id: ID!, $name: String!) {
+    uiapi {
+      AccountUpdate(input: {
+        Id: $id
+        Account: {
+          Name: { value: $name }
+        }
+      }) {
+        Record {
+          Id
+          Name {
+            value
+          }
+        }
+      }
+    }
+  }
+`;
+
+const result = await sfGraphQL(UPDATE_ACCOUNT, {
+  id: '001...',
+  name: 'New Name',
+});
+```
+
+## Einstein LLM Gateway (AI/Generative Features)
+
+Einstein LLM Gateway provides AI and generative capabilities for your React application. Use this service when you want to add features such as:
+
+- Text generation
+- Prompt-based AI responses
+- LLM-powered content creation
+- AI-assisted workflows
+
+### Einstein LLM Gateway Pattern
+
+```javascript
+async function callEinsteinGenerations({ prompt, model = 'gpt-4', signal }) {
+  const url = '/services/data/v62.0/einstein/llm/prompt/generations';
+  try {
+    const resp = await axios.post(
+      url,
+      {
+        additionalConfig: {
+          applicationName: 'PromptTemplateGenerationsInvocable',
+          model,
+        },
+        promptTextorId: prompt,
+      },
+      {
+        signal,
+      }
+    );
+    const data = resp.data;
+    return data?.generations?.[0]?.text || '';
+  } catch (error) {
+    throw new Error(
+      error.message || `Einstein LLM request failed (${error.status})`
+    );
+  }
+}
+```
+
+## Error Handling Pattern
+
+- Always implement robust try/catch for async operations.
+- Provide useful but safe error messages (no sensitive data leakage).
+
+```javascript
+async function safeFetch(recordId) {
+  try {
+    const data = await fetchRecord(recordId);
+    return data;
+  } catch (err) {
+    console.error('Salesforce UI API Error:', err);
+    throw err;
+  }
+}
+```
+
+## Anti-Patterns (Do NOT do these)
+
+- **Apex REST is not available in React applications** - Do NOT attempt to use or call Apex REST endpoints from React code
+- Unnecessary Apex controllers for simple UI API/GraphQL operations
+- Missing error handling for async operations
+- Hardcoded Salesforce URLs, IDs, or sensitive data
+- Ignoring field-level security and permission checks
+- Direct DOM manipulation in React components
+- Using LWC-specific patterns (`@wire`, LDS) or `@salesforce/*` modules in React
+
+## Security Standards (CRITICAL)
+
+- Validate user permissions before data operations.
+- Respect record sharing rules and field-level security.
+- Never hardcode credentials or secrets in client code.
+- Sanitize all user inputs.
+- Use HTTPS for all API calls.
+
+### Authentication Error Handling (MANDATORY)
+
+- All axios clients MUST include response interceptors that handle 401/403 errors.
+- When a 401 (Unauthorized) or 403 (Forbidden) response is received, trigger a page refresh with `window.location.reload()` to redirect to login.
+- Always return `Promise.reject(error)` after handling authentication errors to maintain proper error flow.
+
+### Notes
+
+- avoid swallowing errors.
+
+Input sanitization example:
+
+```javascript
+function sanitizeInput(input) {
+  if (typeof input !== 'string') return '';
+  return input
+    .trim()
+    .replace(/<script[^>]*>.*?<\/script>/gi, '')
+    .replace(/javascript:/gi, '')
+    .slice(0, 255);
+}
+```
+
+## Performance Standards
+
+- Implement client-side caching (e.g., RTK Query or React Query) for API data.
+- Use `React.memo`, `useMemo`, and `useCallback` where appropriate.
+- Implement proper loading and error states.
+
+## TypeScript Standards
+
+- Prefer TypeScript for React components and utilities.
+- Define clear and explicit interfaces for props and API data.
+
+## Testing Requirements
+
+- Use Jest + React Testing Library for UI tests.
+- Test loading, success, and error states for data-fetching components.
+
+## Application Generation Rules
+
+- When requested to generate a new application:
+  - Replace existing template content; do not append to the starter.
+  - Preserve the entry point and routes under `force-app/main/default/webapplications/<appName>/src/`.
+  - Keep existing build and deploy commands working.
+  - Follow the Data Access and Security standards above.
+
+## Debugging Guidance
+
+- Use React DevTools for component inspection.
+- Monitor the browser Network tab for REST/GraphQL calls and auth headers.
+- Implement Error Boundaries for unhandled exceptions.
+
+## Quality Checklist (for generated code)
+
+- Entry point maintained (`App.js` present and wired in pages).
+- Uses shadcn/ui and Tailwind for UI.
+- Follows Data Access rules with proper auth and error handling.
+- Enforces Security standards and input sanitization.
+- Includes loading and error states.
+- Performance optimizations present where reasonable.
+- Tests cover core UI and data interactions.

package/dist/.a4drules/react_image_processing.md

@@ -0,0 +1,45 @@
+#Goal
+
+- You are configuring image usage for React applications generated through Vibe Coding. 
+- Your goal is to ensure Unsplash is used as the default image source unless the developer provides their own images.
+
+# AI Customization Rule: React Image Processing
+
+Image handling standards for React web apps (SFDX): CSP compliance, accessibility, and proper image sources.
+
+## Targets (File Pattern Matching)
+
+- `force-app/main/default/webapplications/*/**/*.tsx`
+- `force-app/main/default/webapplications/*/**/*.ts`
+- `force-app/main/default/webapplications/*/**/*.jsx`
+- `force-app/main/default/webapplications/*/**/*.js`
+- `force-app/main/default/webapplications/*/**/*.html`
+
+## Core Rules
+
+### Default Image Source: Unsplash
+
+Use Unsplash by default (pre-configured in CSP):
+
+```
+https://images.unsplash.com/photo-{PHOTO_ID}?w={WIDTH}&h={HEIGHT}&fit=crop&q=80
+```
+
+Sample Photo IDs: `1557683316-973673baf926` (tech), `1506905925346-21bda4d32df4` (nature)
+
+### Alternative Sources
+
+If user requests another source (Pexels, custom):
+
+- Use requested source
+- Inform user: "Add CSP Trusted Site in Setup → Security → CSP Trusted Sites"
+
+### Accessibility (MANDATORY)
+
+- Always include descriptive `alt` text
+- Use `alt=""` for decorative images only
+
+### Avoid (CSP Violations)
+
+- Avoid until requested `placeholder.com`, `picsum.photos`, `via.placeholder.com`  
+- Pre-configured: `images.unsplash.com`, `source.unsplash.com`, `images.pexels.com`