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

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`

package/dist/.a4drules/skills/install-feature/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: install-feature
+description: Install a feature into the current app. Use when the user asks to add a feature, capability, or functionality like authentication, search, charts, or navigation to their React web app. Do this when user wants to do _anything_ to webapplications/webapps.
+---
+
+# Install feature
+
+When the user asks to add a feature to their app, follow this workflow.
+
+## 1. Match the request to a feature
+
+Available features (npm packages):
+
+
+| Feature                | Package                                                                 | Description                                                            |
+| ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Authentication**     | `@salesforce/webapp-template-feature-react-authentication-experimental` | Login, register, password reset, protected routes                      |
+| **Global search**      | `@salesforce/webapp-template-feature-react-global-search-experimental`  | Search Salesforce objects with filters and pagination                  |
+| **Navigation menu**    | `@salesforce/webapp-template-feature-react-nav-menu-experimental`       | App layout with responsive navigation menu                             |
+| **Analytics charts**   | `@salesforce/webapp-template-feature-react-chart-experimental`          | Recharts line/bar charts with theming (AnalyticsChart, ChartContainer) |
+| **GraphQL data access**| `@salesforce/webapp-template-feature-graphql-experimental`              | executeGraphQL utilities, codegen tooling, and example AccountsTable   |
+| **Shared UI (shadcn)** | `@salesforce/webapp-template-feature-react-shadcn-experimental`         | Button, Card, Input, Select, Table, Tabs, etc.                         |
+
+
+
+If no feature matches, tell the user and offer to build it from scratch following the project's existing patterns.
+
+## 2. Install the npm package
+
+```bash
+npm install <package-name>
+```
+
+## 3. Copy skills and rules from the package
+
+Run the script so skills and rules from the package are copied into your project. Pass `[skills-dir]` and `[rules-dir]` for your environment; the script reports what it copied.
+
+```bash
+# Default (e.g. Cline): .cline/skills, .clinerules
+bash <this-skill>/scripts/copy-feature-assets.sh <package-name>
+
+# Agentforce: .a4drules/ ([docs](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/devagent-rules.html))
+bash <this-skill>/scripts/copy-feature-assets.sh <package-name> .a4drules/skills .a4drules
+
+# Cursor: .cursor/skills, .cursor/rules
+bash <this-skill>/scripts/copy-feature-assets.sh <package-name> .cursor/skills .cursor/rules
+```
+
+## 4. Read the feature's exports and components
+
+Read the package's entry point (usually `index.ts` or the `main` field in its `package.json`) to understand what components and types it exports.
+
+Also read the `feature.ts` file if it exists — it lists dependencies on other features (e.g. shadcn) and any npm dependencies the feature needs (e.g. `recharts`). Install any missing dependencies.
+
+## 5. Implement the feature in the current app
+
+- **If the package exports reusable components** (e.g. `AnalyticsChart`, `ChartContainer`): import and use them directly. Follow the package's README or skill instructions for props, data shapes, and usage patterns.
+- **If the package is a reference implementation** (e.g. authentication pages, search pages): read its source code under `src/` as a reference, then create equivalent pages/components in the current app following the app's existing patterns and conventions.
+
+Place new routes inside the existing app's router (e.g. `routes.tsx`). Do not replace the app shell; add the feature as new routes or sections within it.
+
+## 6. Verify
+
+- Confirm the app builds without errors.
+- Confirm any new routes are accessible and render correctly.
+

package/dist/.a4drules/skills/install-feature/scripts/copy-feature-assets.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Copies skills/ and rules/ from an installed npm package into the current project.
+# Usage: bash <this-script> <package-name> [skills-dir] [rules-dir]
+#
+# Examples:
+#   bash copy-feature-assets.sh @salesforce/webapp-template-feature-graphql-experimental
+#   bash copy-feature-assets.sh @salesforce/webapp-template-feature-graphql-experimental .cursor/skills .cursor/rules
+set -euo pipefail
+
+PKG="${1:?Usage: copy-feature-assets.sh <package-name> [skills-dir] [rules-dir]}"
+SKILLS_DIR="${2:-.cline/skills}"
+RULES_DIR="${3:-.clinerules}"
+
+PKG_DIR="node_modules/$PKG"
+
+if [ ! -d "$PKG_DIR" ]; then
+  echo "Error: Package not found at $PKG_DIR" >&2
+  echo "Run 'npm install $PKG' first." >&2
+  exit 1
+fi
+
+if [ -d "$PKG_DIR/skills" ] && [ "$(ls -A "$PKG_DIR/skills")" ]; then
+  mkdir -p "$SKILLS_DIR"
+  cp -r "$PKG_DIR"/skills/* "$SKILLS_DIR"/
+  echo "Copied skills → $SKILLS_DIR/"
+else
+  echo "No skills/ found in $PKG_DIR — nothing to copy."
+fi
+
+if [ -d "$PKG_DIR/rules" ] && [ "$(ls -A "$PKG_DIR/rules")" ]; then
+  mkdir -p "$RULES_DIR"
+  cp -r "$PKG_DIR"/rules/* "$RULES_DIR"/
+  echo "Copied rules  → $RULES_DIR/"
+else
+  echo "No rules/ found in $PKG_DIR — nothing to copy."
+fi